@everystack/cli 0.4.83 → 0.4.85

package/src/cli/fk-preflight.ts

@@ -0,0 +1,331 @@
+/**
+ * fk-preflight — the orphan check that runs BEFORE a foreign key's DDL, not during it.
+ *
+ * A foreign key is only installable if the rows already in the table satisfy it. PostgreSQL
+ * finds that out DURING `VALIDATE CONSTRAINT`, by raising on the first row that does not — one
+ * row, no count, no second offender, and (before the two-step split) after the apply had already
+ * taken an ACCESS EXCLUSIVE lock and scanned most of the table. The operator learned "there is a
+ * problem" at the worst possible moment and learned nothing else.
+ *
+ * So the apply asks the question first, the same way the declared-owner preflight in
+ * derived-apply does: ONE read that answers it for EVERY key the edge touches, so the refusal
+ * can name the COMPLETE list — how many rows, on which key, and what a few of them look like —
+ * and NOTHING has run when it is raised. Fix the data (`db:exec` is the credential-free lane for
+ * exactly that), re-plan, apply.
+ *
+ * WHICH KEYS NEED THE QUESTION ASKED. Only the ones where an existing row could already violate
+ * the constraint, which is a property of the LIVE database, not of the statement:
+ *
+ *   - a key on a table this edge CREATES         → no. The table has no rows yet, and it does
+ *                                                  not exist to be queried before the edge runs.
+ *   - a key on a column this edge ADDS           → no. Every existing row's value is NULL, which
+ *                                                  satisfies a foreign key (MATCH SIMPLE), and
+ *                                                  the column cannot be queried yet either.
+ *   - a key whose TARGET this edge creates       → no, and this one is a deliberate gap: the
+ *                                                  parent is empty until the edge runs, so the
+ *                                                  answer cannot be read beforehand. The VALIDATE
+ *                                                  then fails and the key stays NOT VALID — a
+ *                                                  pending state, not a rolled-back apply.
+ *   - a key already live but NOT VALID           → YES. This is the interrupted two-step add, and
+ *                                                  the rows it was never checked against are
+ *                                                  exactly what VALIDATE is about to scan.
+ *   - a key on an existing table and columns     → YES.
+ *
+ * An `ADD … NOT VALID` and the `VALIDATE` that follows it in the same edge are ONE question, not
+ * two — the key is the unit, not the statement.
+ *
+ * Pure: the parsing, the SQL, and the refusal text. The caller runs the query.
+ */
+
+import type { SchemaSnapshot, TableSchema, ForeignKey } from './schema-introspect';
+import { statementBody } from './sql-statement';
+import { quoteIdent, quoteQualified } from './pg-ident';
+import { escapeLiteral } from './derived-apply';
+
+/** One foreign key whose orphans must be counted before any DDL runs. */
+export interface FkOrphanCheck {
+  /** Schema-qualified, as the live snapshot spells it (`public.posts`). */
+  table: string;
+  /** The constraint name as it will exist when the VALIDATE runs. */
+  constraint: string;
+  columns: string[];
+  /** Schema-qualified target table. */
+  refTable: string;
+  refColumns: string[];
+}
+
+/** Strip quoting from one identifier token. */
+const unquote = (id: string): string => (/^".*"$/.test(id) ? id.slice(1, -1).replace(/""/g, '"') : id);
+
+/** `"public"."posts"` / `posts` / `public.posts` → `public.posts` (the snapshot's spelling). */
+export function normalizeTableName(raw: string): string {
+  const parts = raw.trim().replace(/;$/, '').match(/("(?:[^"]|"")*"|[^.\s]+)/g) ?? [];
+  const names = parts.map(unquote);
+  if (names.length === 0) return raw;
+  return names.length === 1 ? `public.${names[0]}` : names.slice(-2).join('.');
+}
+
+/** `("a", "b")` → `['a','b']`. */
+const parseColumns = (list: string): string[] =>
+  (list.replace(/^\(|\)$/g, '').match(/("(?:[^"]|"")*"|[^,\s]+)/g) ?? []).map(unquote);
+
+const CREATE_TABLE_RE = /^CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?((?:"(?:[^"]|"")*"|[A-Za-z_][\w$]*)(?:\.(?:"(?:[^"]|"")*"|[A-Za-z_][\w$]*))?)/i;
+const ADD_COLUMN_RE = /^ALTER\s+TABLE\s+(?:ONLY\s+)?(\S+)\s+ADD\s+COLUMN\s+(?:IF\s+NOT\s+EXISTS\s+)?("(?:[^"]|"")*"|[A-Za-z_][\w$]*)/i;
+const ADD_FK_RE = /^ALTER\s+TABLE\s+(?:ONLY\s+)?(\S+)\s+ADD\s+CONSTRAINT\s+("(?:[^"]|"")*"|[A-Za-z_][\w$]*)\s+FOREIGN\s+KEY\s*(\([^)]*\))\s*REFERENCES\s+((?:"(?:[^"]|"")*"|[^\s(]+)(?:\.(?:"(?:[^"]|"")*"|[^\s(]+))?)\s*(\([^)]*\))/i;
+const VALIDATE_RE = /^ALTER\s+TABLE\s+(?:ONLY\s+)?(\S+)\s+VALIDATE\s+CONSTRAINT\s+("(?:[^"]|"")*"|[A-Za-z_][\w$]*)/i;
+const RENAME_CONSTRAINT_RE = /^ALTER\s+TABLE\s+(?:ONLY\s+)?(\S+)\s+RENAME\s+CONSTRAINT\s+("(?:[^"]|"")*"|[A-Za-z_][\w$]*)\s+TO\s+("(?:[^"]|"")*"|[A-Za-z_][\w$]*)/i;
+
+/** The live table under its qualified name, or undefined. */
+const liveTable = (live: SchemaSnapshot, table: string): TableSchema | undefined =>
+  live.tables.find((t) => t.table === table);
+
+/**
+ * The foreign keys an edge is about to install or validate that could ALREADY be violated by
+ * rows in the live database — see the rules in the module docblock.
+ *
+ * `statements` is the edge exactly as it will execute (held drops and notices included; they are
+ * comments and match nothing). `live` is the target's state as the apply just read it — the same
+ * snapshot the concurrency lock was computed from, so the two cannot describe different databases.
+ */
+export function fkOrphanChecks(statements: readonly string[], live: SchemaSnapshot): FkOrphanCheck[] {
+  const bodies = statements.map(statementBody);
+
+  // Tables this edge creates: their rows do not exist yet, and neither do they.
+  const created = new Set<string>();
+  for (const body of bodies) {
+    const m = CREATE_TABLE_RE.exec(body);
+    if (m) created.add(normalizeTableName(m[1]));
+  }
+
+  // Columns this edge adds: every existing row holds NULL there, which satisfies the key.
+  const addedColumns = new Set<string>();
+  for (const body of bodies) {
+    const m = ADD_COLUMN_RE.exec(body);
+    if (m) addedColumns.add(`${normalizeTableName(m[1])}.${unquote(m[2])}`);
+  }
+
+  // A constraint renamed by this edge is validated under its NEW name, but it is LIVE under the
+  // old one — so the live lookup has to walk back through the rename.
+  const renamedFrom = new Map<string, string>();
+  for (const body of bodies) {
+    const m = RENAME_CONSTRAINT_RE.exec(body);
+    if (m) renamedFrom.set(`${normalizeTableName(m[1])}::${unquote(m[3])}`, unquote(m[2]));
+  }
+
+  const checks: FkOrphanCheck[] = [];
+  const seen = new Set<string>();
+
+  const push = (check: FkOrphanCheck): void => {
+    const key = `${check.table}::${check.constraint}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    checks.push(check);
+  };
+
+  for (const body of bodies) {
+    const add = ADD_FK_RE.exec(body);
+    if (add) {
+      const table = normalizeTableName(add[1]);
+      const columns = parseColumns(add[3]);
+      const target = liveTable(live, table);
+      // Not live yet, or one of its columns is not: nothing to scan, and nothing to scan it with.
+      if (!target) continue;
+      const liveColumns = new Set(target.columns.map((c) => c.name));
+      if (columns.some((c) => !liveColumns.has(c) || addedColumns.has(`${table}.${c}`))) continue;
+      const refTable = normalizeTableName(add[4]);
+      if (created.has(refTable) || !liveTable(live, refTable)) continue;
+      push({ table, constraint: unquote(add[2]), columns, refTable, refColumns: parseColumns(add[5]) });
+      continue;
+    }
+
+    const validate = VALIDATE_RE.exec(body);
+    if (validate) {
+      const table = normalizeTableName(validate[1]);
+      const constraint = unquote(validate[2]);
+      // Already covered when this edge also ADDs it — one key, one question.
+      if (seen.has(`${table}::${constraint}`)) continue;
+      const target = liveTable(live, table);
+      if (!target) continue;
+      const liveName = renamedFrom.get(`${table}::${constraint}`) ?? constraint;
+      const fk: ForeignKey | undefined = target.foreignKeys.find((f) => f.name === liveName);
+      // A VALIDATE naming a key the live database does not have is not a question this preflight
+      // can ask — it would be guessing at columns. The statement's own failure is the answer.
+      if (!fk) continue;
+      push({ table, constraint, columns: fk.columns, refTable: normalizeTableName(fk.refTable), refColumns: fk.refColumns });
+    }
+  }
+
+  return checks;
+}
+
+/** One row of {@link fkOrphanSql}'s result. */
+export interface FkOrphanRow {
+  constraint_name: unknown;
+  table_name: unknown;
+  columns: unknown;
+  ref_table: unknown;
+  orphans: unknown;
+  samples: unknown;
+}
+
+/**
+ * ONE read answering the question for every key at once — a first-failure refusal would make the
+ * operator fix one table, re-run, and discover the next.
+ *
+ * The scan is a real anti-join over the child table, which costs about what the VALIDATE it is
+ * protecting would cost. That is the price of knowing BEFORE the lock instead of during it, and
+ * it buys an exact count rather than pg's one-row-and-stop.
+ *
+ * NULLs are excluded, not counted: under MATCH SIMPLE (the only mode everystack emits) a row with
+ * a NULL in any key column satisfies the constraint. Counting them would refuse an apply that
+ * PostgreSQL would have accepted, which is the worse failure — a gate nobody can pass gets
+ * disabled.
+ *
+ * THE COUNT IS UNBOUNDED AND THE SAMPLE IS NOT, and the asymmetry is deliberate. The count is
+ * the full scan, which is the price of the answer and is paid either way. The SAMPLE is three
+ * values for the operator to recognise a row by — so it is taken from a `LIMIT 3` subquery and
+ * aggregated over those three rows alone. Aggregating the whole set and slicing it afterwards
+ * (`(array_agg(…))[1:3]`) builds the ENTIRE array in work memory first, which array_agg cannot
+ * spill to disk: on a table with millions of orphans the gate that exists to protect the
+ * database is the thing that takes it down.
+ */
+export function fkOrphanSql(checks: readonly FkOrphanCheck[]): string {
+  if (checks.length === 0) throw new Error('fkOrphanSql: no checks — the caller must skip the read');
+  return checks
+    .map((c) => {
+      // The columns come out of a REGEX over the ADD CONSTRAINT text. A short or empty parse is
+      // not a shape this read can paper over: joining the child's own column name against the
+      // parent errors on most schemas but SUCCEEDS on a parent that happens to carry the same
+      // name — and then counts zero, reporting a clean pass on a key nobody actually checked.
+      // Refuse, exactly as an empty check list is refused; the caller fails closed on the throw.
+      if (c.columns.length === 0) {
+        throw new Error(`fkOrphanSql: ${c.table}.${c.constraint} has no columns — the read cannot be built`);
+      }
+      if (c.refColumns.length !== c.columns.length) {
+        throw new Error(
+          `fkOrphanSql: ${c.table}.${c.constraint} names ${c.columns.length} column(s) but `
+          + `${c.refColumns.length} reference column(s) in ${c.refTable} — the read cannot be built `
+          + 'without guessing the join, and a guessed join can report a false clean.',
+        );
+      }
+      const child = quoteQualified(c.table);
+      const parent = quoteQualified(c.refTable);
+      const notNull = c.columns.map((col) => `c.${quoteIdent(col)} IS NOT NULL`).join(' AND ');
+      const join = c.columns.map((col, i) => `p.${quoteIdent(c.refColumns[i]!)} = c.${quoteIdent(col)}`).join(' AND ');
+      const where = (pad: string): string =>
+        `WHERE ${notNull}\n${pad}  AND NOT EXISTS (SELECT 1 FROM ${parent} p WHERE ${join})`;
+      // One printable value per offending row: a single-column key prints the value, a composite
+      // one prints the tuple. Capped, because a sample is for recognising the row, not for
+      // reading its contents into a refusal message.
+      const sample = c.columns.length === 1
+        ? `left(c.${quoteIdent(c.columns[0]!)}::text, 80)`
+        : `left(concat_ws(', ', ${c.columns.map((col) => `c.${quoteIdent(col)}::text`).join(', ')}), 80)`;
+      // Two scalar subqueries over no FROM: exactly ONE row per arm, at any orphan count —
+      // zero orphans gives 0 and a NULL sample array rather than no row at all. The caller
+      // asserts that shape (checkOrphanRowShape) and fails closed if it does not hold.
+      return `SELECT ${escapeLiteral(c.constraint)} AS constraint_name,
+       ${escapeLiteral(c.table)} AS table_name,
+       ${escapeLiteral(c.columns.join(', '))} AS columns,
+       ${escapeLiteral(c.refTable)} AS ref_table,
+       (SELECT count(*)::bigint
+          FROM ${child} c
+          ${where('          ')}) AS orphans,
+       (SELECT array_agg(s.sample)
+          FROM (SELECT ${sample} AS sample
+                  FROM ${child} c
+                  ${where('                  ')}
+                  ORDER BY 1
+                  LIMIT 3) s) AS samples`;
+    })
+    .join('\nUNION ALL\n');
+}
+
+/**
+ * The read returns exactly one row per key — see {@link fkOrphanSql}. Anything else is an answer
+ * nobody can read, and an unreadable answer is not "no orphans": it is the gate not running.
+ *
+ * FAIL CLOSED. A driver that hands back `[]` (a shape quirk, a transport that dropped the rows,
+ * a future change to the read) would otherwise walk straight through `fkOrphanRefusal`, which
+ * reports null — "every key is satisfied" — for an empty list. Asserted here, in the module that
+ * owns the read's shape, so the assertion cannot drift from the SQL it is about.
+ */
+export function checkOrphanRowShape(rows: unknown, expected: number): asserts rows is FkOrphanRow[] {
+  const got = Array.isArray(rows) ? rows.length : null;
+  if (got === expected) return;
+  throw new Error(
+    `the foreign-key row check answered with ${got === null ? 'something that is not a row set' : `${got} row(s)`} `
+    + `for ${expected} key(s) — the read produces exactly one row per key, so this answer cannot be read.`,
+  );
+}
+
+/**
+ * The orphan count as a number, or a THROW.
+ *
+ * It used to coerce null / unreadable text to 0, which is the answer "this key is satisfied" —
+ * the single most dangerous default in this module. `0` is a finding; `null` is a missing
+ * answer, and the two must never be spelled the same way. The caller turns the throw into the
+ * fail-closed refusal an unreachable database gets.
+ */
+const toCount = (v: unknown, where: string): number => {
+  if (v === null || v === undefined) throw new Error(`the orphan count for ${where} could not be read (it came back empty).`);
+  if (typeof v === 'object') throw new Error(`the orphan count for ${where} could not be read (unexpected shape).`);
+  if (typeof v === 'string' && v.trim() === '') throw new Error(`the orphan count for ${where} could not be read (it came back blank).`);
+  const n = typeof v === 'bigint' ? Number(v) : Number(v);
+  if (!Number.isFinite(n)) throw new Error(`the orphan count for ${where} could not be read (got ${JSON.stringify(String(v))}).`);
+  return n;
+};
+
+const toSamples = (v: unknown): string[] =>
+  Array.isArray(v) ? v.filter((s) => s != null).map((s) => String(s)) : [];
+
+/**
+ * The refusal when the read itself could not run (no privilege on a referenced table, a lock
+ * timeout, a dropped connection).
+ *
+ * FAIL CLOSED, the same rule the reconciler applies to grants it cannot see: a gate that did not
+ * run has not passed, and an apply that proceeds on an unanswered question is exactly the
+ * mid-VALIDATE surprise this preflight exists to remove. Nothing has run when this is raised.
+ */
+export function fkPreflightUnavailableRefusal(error: string): string {
+  return [
+    `the foreign-key row check could not run against this target — refused before any DDL, because a check that did not run has not passed.`,
+    `  ${error}`,
+    `Grant the applying role SELECT on the tables the keys join, or run the apply from a role that has it, then re-plan and apply.`,
+  ].join('\n');
+}
+
+/**
+ * The refusal text, or null when every key's rows already satisfy it.
+ *
+ * It names the COUNT and a SAMPLE per key, because those are the two things the operator needs
+ * and neither is in PostgreSQL's own error: how much work the fix is, and what the broken rows
+ * look like. The fix is data, so the escape is a data fix and a re-plan — never a flag. There is
+ * deliberately no `--force`: an unsatisfiable foreign key is not an intent someone can attest to.
+ *
+ * THROWS when a row's count cannot be read — see {@link toCount}. `null` returned from here means
+ * "asked and satisfied", so an unreadable count must not be able to produce it.
+ */
+export function fkOrphanRefusal(rows: readonly FkOrphanRow[]): string | null {
+  const where = (r: FkOrphanRow): string => `${String(r.table_name)}.${String(r.constraint_name)}`;
+  const counted = rows.map((r) => ({ row: r, count: toCount(r.orphans, where(r)) }));
+  const offenders = counted.filter((c) => c.count > 0);
+  if (offenders.length === 0) return null;
+
+  const lines = [
+    `${offenders.length} foreign key(s) cannot be validated — rows already in the table do not satisfy them. Refused before any DDL, so nothing is half-applied.`,
+    `Fix the data first (everystack db:exec runs a DML-only file against the target, credential-free), then re-plan and apply.`,
+  ];
+  for (const { row, count } of offenders) {
+    const samples = toSamples(row.samples);
+    lines.push(
+      `  ORPHANED ROWS  ${String(row.table_name)}.${String(row.constraint_name)}: ${count} row(s) hold a value in (${String(row.columns)}) with no matching row in ${String(row.ref_table)}.`,
+    );
+    if (samples.length > 0) {
+      lines.push(`      sample value(s): ${samples.join(', ')}${count > samples.length ? ', …' : ''}`);
+    }
+    lines.push(
+      `      the rows:  SELECT * FROM ${row.table_name} c WHERE NOT EXISTS (SELECT 1 FROM ${row.ref_table} p WHERE p.<key> = c.<fk>);`,
+    );
+  }
+  return lines.join('\n');
+}

package/src/cli/migration-generate.ts

@@ -21,7 +21,7 @@ import type { AuthzContract, SequenceGrantContract } from './authz-contract';
 import { compileTableSchema, compileRenames, compileTableRenames, compileTableMoves, compileCreateTable, compileEnums, compileSequences } from './schema-compile';
 import { compileTableContract } from './authz-compile';
 import { emitReconcileSql, governedRoleSet } from './authz-reconcile';
-import { diffSchema, emitSchemaSql, ownSequenceName, type SchemaChange } from './schema-diff';
+import { diffSchema, emitSchemaStatements, ownSequenceName, type SchemaChange } from './schema-diff';
 import { schemaOf } from './schema-fingerprint';
 
 export interface GenerateOptions {
@@ -195,7 +195,7 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
   const changes = diffSchema(desired, scopedCurrent, renames, tableRenames, tableMoves);
 
   const modelByTable = new Map(models.map((m) => [`${schemaOf(m)}.${m.table}`, m]));
-  const emitted = emitSchemaSql(changes, {
+  const emitted = emitSchemaStatements(changes, {
     createTable: (change) => {
       const model = modelByTable.get(change.table);
       if (!model) throw new Error(`db:generate: no model found for new table ${change.table}`);
@@ -205,17 +205,18 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
 
   // Non-destructive by default: a column/constraint/table in the database but absent
   // from the Models would otherwise become a DROP — silent data loss for a partial or
-  // lossy Model set. Hold removals back as comments unless `allowDrops`. emitSchemaSql
-  // returns one statement per change, index-aligned, so the gate stays a pure
-  // post-pass — `diffSchema`/`emitSchemaSql` remain honest (they always emit the DROP).
-  let dataPhase = emitted;
+  // lossy Model set. Hold removals back as comments unless `allowDrops`. Each emitted
+  // statement carries the change it came from (a foreign-key add is TWO statements, so a
+  // parallel index is not a pairing), which keeps the gate a pure post-pass —
+  // `diffSchema`/`emitSchemaSql` remain honest (they always emit the DROP).
+  let dataPhase = emitted.map((e) => e.sql);
   if (!opts.allowDrops) {
     const replacedConstraints = new Set(
       changes
         .filter((c): c is Extract<SchemaChange, { kind: 'addConstraint' }> => c.kind === 'addConstraint')
         .map((c) => `${c.table}::${c.constraint.name}`),
     );
-    dataPhase = emitted.map((sql, i) => (isRemoval(changes[i], replacedConstraints) ? holdDrop(sql) : sql));
+    dataPhase = emitted.map(({ change, sql }) => (isRemoval(change, replacedConstraints) ? holdDrop(sql) : sql));
   }
 
   // Authz phase — appended after the data phase so a policy/grant references columns the

package/src/cli/plain-output.ts

@@ -157,6 +157,12 @@ export function describeChange(statement: string, opts: DescribeOptions = {}): P
     if ((a = /^DROP\s+CONSTRAINT\s+(?:IF\s+EXISTS\s+)?("[^"]+"|[\w$]+)/i.exec(rest))) {
       return { symbol: '-', text: `remove constraint ${unquote(a[1])} on ${table}` };
     }
+    // The second half of a two-step foreign-key add (and the whole of a re-plan that finds one
+    // half-applied). It adds nothing and removes nothing — it CHECKS the rows already there —
+    // so without its own line it fell through to the raw-statement fallback.
+    if ((a = /^VALIDATE\s+CONSTRAINT\s+("[^"]+"|[\w$]+)/i.exec(rest))) {
+      return { symbol: '+', text: `check existing rows against constraint ${unquote(a[1])} on ${table}` };
+    }
     if ((a = /^ALTER\s+COLUMN\s+("[^"]+"|[\w$]+)\s+([\s\S]+)$/i.exec(rest))) {
       const column = `${table}.${unquote(a[1])}`;
       const what = a[2].trim();
@@ -394,18 +400,20 @@ export interface PlanReportInput {
   stage?: string | null;
   /** The plan file to name in the Run line; null when the plan went to stdout. */
   planPath: string | null;
+  /** --verbose: the promise behind "(--verbose for the full list)" — show every line, uncapped. */
+  verbose?: boolean;
 }
 
 /** db:plan's default output — the whole thing. */
 export function renderPlanReport(input: PlanReportInput): string[] {
-  const { executable, target, stage, planPath } = input;
+  const { executable, target, stage, planPath, verbose = false } = input;
   if (executable.length === 0) return ['Up to date. Nothing to plan.'];
 
   const destructive = new Set(input.destructive);
   const lines: string[] = [
     `Plan: ${executable.length} ${plural(executable.length, 'change', 'changes')} (${target})`,
     '',
-    ...changeLines(executable, destructive, MAX_LISTED_CHANGES),
+    ...changeLines(executable, destructive, verbose ? executable.length : MAX_LISTED_CHANGES),
     '',
   ];
 

package/src/cli/schema-diff.ts

@@ -41,7 +41,11 @@ import type {
 export type ConstraintSpec =
   | { type: 'unique'; name: string; columns: string[] }
   | { type: 'check'; name: string; expr: string }
-  | { type: 'foreignKey'; name: string; columns: string[]; refTable: string; refColumns: string[]; onDelete?: string; onUpdate?: string; nameDeclared?: boolean };
+  | { type: 'foreignKey'; name: string; columns: string[]; refTable: string; refColumns: string[]; onDelete?: string; onUpdate?: string; nameDeclared?: boolean;
+      /** LIVE-SIDE ONLY: the key is installed but unchecked (see {@link ForeignKey.notValid}).
+       *  It is never part of {@link constraintContentKey} — a NOT VALID key IS the declared key,
+       *  one step short — and the emitter ignores it, because an ADD is always emitted NOT VALID. */
+      notValid?: boolean };
 
 export type SchemaChange =
   | { kind: 'createTable'; table: string; schema: TableSchema }
@@ -64,6 +68,15 @@ export type SchemaChange =
   /** A type change → real `ALTER COLUMN ... TYPE`. `risk` decides USING + a data-loss warning. */
   | { kind: 'alterType'; table: string; column: string; from: string; to: string; risk: TypeChangeRisk }
   | { kind: 'addConstraint'; table: string; constraint: ConstraintSpec; note?: string }
+  /**
+   * A foreign key that is already installed on the live table but has never been checked
+   * against its rows (`NOT VALID`) → the second half of the two-step add, on its own.
+   *
+   * It is a DISTINCT kind from `addConstraint` because the ADD must not be re-emitted: the
+   * constraint is there, and a second `ADD CONSTRAINT` under the same name fails outright.
+   * This is what the state after an interrupted two-step add re-plans to — VALIDATE only.
+   */
+  | { kind: 'validateConstraint'; table: string; name: string }
   | { kind: 'dropConstraint'; table: string; name: string }
   | { kind: 'addPrimaryKey'; table: string; columns: string[] }
   /** A PK change other than first-time add — a notice (the drop needs its constraint name). */
@@ -791,7 +804,7 @@ function diffColumns(d: TableSchema, c: TableSchema, tableRenames: Record<string
 function tableConstraintSpecs(t: TableSchema): ConstraintSpec[] {
   return [
     ...t.uniques.map((u): ConstraintSpec => ({ type: 'unique', name: u.name, columns: u.columns })),
-    ...t.foreignKeys.map((fk): ConstraintSpec => ({ type: 'foreignKey', name: fk.name, columns: fk.columns, refTable: fk.refTable, refColumns: fk.refColumns, onDelete: fk.onDelete, onUpdate: fk.onUpdate, ...(fk.nameDeclared ? { nameDeclared: true } : {}) })),
+    ...t.foreignKeys.map((fk): ConstraintSpec => ({ type: 'foreignKey', name: fk.name, columns: fk.columns, refTable: fk.refTable, refColumns: fk.refColumns, onDelete: fk.onDelete, onUpdate: fk.onUpdate, ...(fk.nameDeclared ? { nameDeclared: true } : {}), ...(fk.notValid ? { notValid: true } : {}) })),
   ];
 }
 
@@ -857,6 +870,17 @@ function diffConstraints(d: TableSchema, c: TableSchema, dropConstraints: Schema
       if (des.type === 'foreignKey' && des.nameDeclared && matched.name !== des.name) {
         renames.push({ kind: 'renameConstraint', table: d.table, from: matched.name, to: des.name });
       }
+      // The live key is there but was never checked against the rows already in the table —
+      // the state an interrupted two-step add leaves behind, and the state a hand-run
+      // `ADD CONSTRAINT … NOT VALID` leaves behind. The declared side is a VALIDATED key, so
+      // this is a real difference and the edge finishes it: VALIDATE alone, never a second
+      // ADD (which would fail on the name that is already taken). Under the live name, which
+      // may not be the declared one — a rename emitted just above lands FIRST, so the
+      // validate must speak the name the constraint will have by then.
+      if (matched.type === 'foreignKey' && matched.notValid) {
+        const name = des.type === 'foreignKey' && des.nameDeclared ? des.name : matched.name;
+        addConstraints.push({ kind: 'validateConstraint', table: d.table, name });
+      }
     } else {
       addConstraints.push({ kind: 'addConstraint', table: d.table, constraint: des });
     }
@@ -934,11 +958,39 @@ function createTableSql(t: TableSchema): string {
   return `CREATE TABLE ${t.table} (\n${lines.join(',\n')}\n);`;
 }
 
-function addConstraintSql(table: string, c: ConstraintSpec): string {
+/**
+ * `ALTER TABLE … VALIDATE CONSTRAINT …` — the second half of a two-step foreign key add.
+ *
+ * ONE definition, read by the FK add (which always emits the pair) and by the change kind that
+ * finishes a key some earlier apply left NOT VALID. Two spellings of the same statement is how
+ * the "did this already run?" question ends up with two answers.
+ */
+export function validateConstraintSql(table: string, name: string): string {
+  return `ALTER TABLE ${table} VALIDATE CONSTRAINT ${quote(name)};`;
+}
+
+/**
+ * Rendering an `ADD CONSTRAINT`: ONE statement, except a foreign key, which is TWO.
+ *
+ * A validated FK add takes an ACCESS EXCLUSIVE lock on the table for the length of a full scan
+ * of every row already in it — on a large, live table that is a write outage measured in
+ * minutes. PostgreSQL's own answer is to split the work:
+ *
+ *   1. `ADD CONSTRAINT … NOT VALID` — catalog-only and near-instant. The key is enforced on
+ *      every row written from this moment on; the rows already there are simply unchecked.
+ *   2. `VALIDATE CONSTRAINT …` — the scan, under a SHARE UPDATE EXCLUSIVE lock that readers
+ *      and writers both pass through.
+ *
+ * The split only buys that if the two run in SEPARATE transactions (step 1's lock is held to
+ * commit), which is why the apply path runs every VALIDATE after the edge's batch commits — see
+ * `splitValidations` in state-apply. The text is produced HERE for both `db:diff` (no database)
+ * and `db:plan` (against a live one), so the two can never render the same edge differently.
+ */
+function addConstraintSql(table: string, c: ConstraintSpec): string[] {
   const head = `ALTER TABLE ${table} ADD CONSTRAINT ${quote(c.name)}`;
   switch (c.type) {
-    case 'unique': return `${head} UNIQUE (${colList(c.columns)});`;
-    case 'check': return `${head} CHECK ${wrapOnce(c.expr)};`;
+    case 'unique': return [`${head} UNIQUE (${colList(c.columns)});`];
+    case 'check': return [`${head} CHECK ${wrapOnce(c.expr)};`];
     case 'foreignKey': {
       // refTable may be schema-qualified (`auth.users`) for a cross-schema FK — quote each part,
       // not the whole string, or `"auth.users"` reads as one identifier.
@@ -946,7 +998,7 @@ function addConstraintSql(table: string, c: ConstraintSpec): string {
       let s = `${head} FOREIGN KEY (${colList(c.columns)}) REFERENCES ${refTable}(${colList(c.refColumns)})`;
       if (c.onDelete) s += ` ON DELETE ${c.onDelete.toUpperCase()}`;
       if (c.onUpdate) s += ` ON UPDATE ${c.onUpdate.toUpperCase()}`;
-      return `${s};`;
+      return [`${s} NOT VALID;`, validateConstraintSql(table, c.name)];
     }
   }
 }
@@ -959,8 +1011,16 @@ export interface EmitOptions {
   createTable?: (change: Extract<SchemaChange, { kind: 'createTable' }>) => string;
 }
 
-/** Render one change to SQL — or a `-- NOTICE:` comment for the cases held for a follow-up. */
-function emitOne(change: SchemaChange, opts: EmitOptions): string {
+/**
+ * Render one change to SQL — or a `-- NOTICE:` comment for the cases held for a follow-up.
+ *
+ * Returns a STRING for the one-statement kinds and an ARRAY for the kinds that are genuinely
+ * more than one statement (today: a foreign-key add, which is `NOT VALID` + `VALIDATE`).
+ * `emitSchemaStatements` flattens it and keeps each statement paired with the change it came
+ * from, so the callers that decide something per change (the held-drop gate) never have to
+ * assume one-statement-per-change.
+ */
+function emitOne(change: SchemaChange, opts: EmitOptions): string | string[] {
   switch (change.kind) {
     case 'createTable':
       return opts.createTable ? opts.createTable(change) : createTableSql(change.schema);
@@ -1011,8 +1071,14 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string {
         : `-- WARNING: ${change.from} → ${change.to} on column ${quote(change.column)} (${change.table}) casts with USING and may FAIL on rows that don't convert; review before running.`;
       return `${warn}\n${ddl}`;
     }
-    case 'addConstraint':
-      return (change.note ? `${change.note}\n` : '') + addConstraintSql(change.table, change.constraint);
+    case 'addConstraint': {
+      const [first, ...rest] = addConstraintSql(change.table, change.constraint);
+      // The note rides the FIRST statement only — it documents the change, and repeating it on
+      // the VALIDATE would read as a second finding.
+      return [(change.note ? `${change.note}\n` : '') + first, ...rest];
+    }
+    case 'validateConstraint':
+      return validateConstraintSql(change.table, change.name);
     case 'dropConstraint':
       return `ALTER TABLE ${change.table} DROP CONSTRAINT IF EXISTS ${quote(change.name)};`;
     case 'addPrimaryKey':
@@ -1088,7 +1154,28 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string {
   }
 }
 
+/** One emitted statement and the change that produced it. */
+export interface EmittedStatement {
+  change: SchemaChange;
+  sql: string;
+}
+
+/**
+ * The change set as an ordered list of statements, each still carrying its change.
+ *
+ * A change is NOT one statement any more (a foreign-key add is `NOT VALID` + `VALIDATE`), so
+ * callers that decide something per change — db:generate's held-drop gate is the only one —
+ * read the pairing from here instead of indexing a parallel array. Index alignment was a real
+ * invariant right up until it silently was not.
+ */
+export function emitSchemaStatements(changes: SchemaChange[], opts: EmitOptions = {}): EmittedStatement[] {
+  return changes.flatMap((change) => {
+    const emitted = emitOne(change, opts);
+    return (Array.isArray(emitted) ? emitted : [emitted]).map((sql) => ({ change, sql }));
+  });
+}
+
 /** The change set as an ordered list of SQL statements (and notice comments). */
 export function emitSchemaSql(changes: SchemaChange[], opts: EmitOptions = {}): string[] {
-  return changes.map((c) => emitOne(c, opts));
+  return emitSchemaStatements(changes, opts).map((e) => e.sql);
 }