-- #689: persist the hand-curated "G 0…G 5" generation index from
-- canonical-persons.xlsx so the Stammbaum layout can use it as a strict
-- rank anchor (replacing the current iterative longest-path heuristic that
-- silently misplaces loose spouses with their own parents in the graph).
--
-- Nullable: pre-import rows and persons outside the curated family graph
-- legitimately have no generation. The canonical importer back-fills via
-- preferHuman on the next run; a human-edited value is never overwritten
-- (see ADR-025).

ALTER TABLE persons ADD COLUMN generation SMALLINT;

-- Allowlist of valid generation indices. The 0..10 bounds mirror
-- PersonGeneration.MIN_GENERATION / MAX_GENERATION in Java — keep the
-- two in sync (the DTO @Min/@Max and both importer range guards read from
-- those Java constants). Current data tops out at G 5, but a future G 6 →
-- G 10 widening needs no migration. A G −1 ancestor would require a
-- separate one-shot shift migration (out of scope here; the layout's
-- normalise step already handles negative seeds at render time).
ALTER TABLE persons ADD CONSTRAINT chk_generation_range
    CHECK (generation IS NULL OR generation BETWEEN 0 AND 10);

-- Partial index: only the curated rows (≈ 163 of 1,105) ever get a value,
-- and the layout only ever queries for non-null rows.
CREATE INDEX idx_persons_generation ON persons (generation)
    WHERE generation IS NOT NULL;
