@everystack/cli 0.4.84 → 0.4.86

package/src/cli/fk-preflight.ts

@@ -0,0 +1,414 @@
+/**
+ * fk-preflight — the orphan check that runs BEFORE a foreign key's DDL, not during it.
+ *
+ * A foreign key is only VALIDATABLE 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 would validate, so the
+ * report can name the COMPLETE list — how many rows, on which key, and what a few of them look
+ * like — before anything runs.
+ *
+ * WHAT THE ANSWER IS FOR, and this is the part that changed. It used to refuse the WHOLE apply
+ * if any key had one orphan: unrelated grants, unrelated clean keys, the entire edge, held
+ * behind a data audit. On a long-lived database that is the wrong trade — ~11,500 legitimately
+ * orphaned rows across 12 of 23 keys is ordinary decay, not a broken deploy. Now the answer is
+ * PER KEY: the offending key's `VALIDATE` is withheld (the key stays installed and NOT VALID,
+ * enforced on every new write), it is recorded as a pending validation, and everything else in
+ * the edge commits. Fix the data when you choose (`db:exec` is the credential-free lane) and the
+ * next plan emits that one `VALIDATE` alone — or declare `validate: false` on the reference and
+ * the question is never asked about that key again.
+ *
+ * THE UNIT IS A `VALIDATE` STATEMENT, not a foreign key add. That is the whole rule, and it is
+ * why a key declared `validate: false` is never scanned: the differ emits no `VALIDATE` for it,
+ * so there is nothing here to ask about. An `ADD … NOT VALID` and the `VALIDATE` that follows it
+ * in the same edge are ONE question — the key is the unit, not the statement — and an
+ * `ADD … NOT VALID` with NO `VALIDATE` behind it is not a question at all.
+ *
+ * WHICH VALIDATED 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.
+ *
+ * Pure: the parsing, the SQL, the findings, and the text. The caller runs the query.
+ */
+
+import type { SchemaSnapshot, TableSchema, ForeignKey } from './schema-introspect';
+import type { PendingValidation } from './state-apply';
+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 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.
+ *
+ * Driven by the `VALIDATE` statements, never by the `ADD`s. An `ADD … NOT VALID` used to imply
+ * the question because the emitter always paired the two; a key declared `validate: false` is
+ * emitted with no pair, and scanning for it would be scanning a table to answer a question
+ * nobody asked. The ADD is still read — it is where a NEW key's columns and target come from,
+ * which the live snapshot cannot supply.
+ */
+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]));
+  }
+
+  // The keys this edge actually asks to be PROVEN. Everything below is about them and only
+  // them: a key whose `ADD … NOT VALID` stands alone is the declared state, not a pending step.
+  const validated = new Set<string>();
+  for (const body of bodies) {
+    const m = VALIDATE_RE.exec(body);
+    if (m) validated.add(`${normalizeTableName(m[1])}::${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]);
+      // No `VALIDATE` behind this ADD — `validate: false`. Nothing to prove, nothing to scan.
+      if (!validated.has(`${table}::${unquote(add[2])}`)) continue;
+      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 {@link fkOrphanFindings},
+ * which reports an empty list — "every key is satisfied" — for an empty answer. 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');
+}
+
+/**
+ * One key the read found orphaned rows for.
+ *
+ * This, not the prose, is what the apply and the plan report from: the apply has to decide PER
+ * KEY which `VALIDATE` to withhold, and the plan has to cross-reference the column against the
+ * row-ownership declarations. Neither can be done by parsing a message.
+ */
+export interface FkOrphanFinding {
+  /** Schema-qualified child table (`public.posts`). */
+  table: string;
+  /** The constraint name the withheld `VALIDATE` would have named. */
+  constraint: string;
+  /** The key's own columns, in order. */
+  columns: string[];
+  /** Schema-qualified target table. */
+  refTable: string;
+  /** How many rows hold a value with no matching parent. Exact — the read counts, it does not sample. */
+  orphans: number;
+  /** At most three KEY VALUES, for recognising a row. Never row contents. */
+  samples: string[];
+}
+
+/**
+ * The keys with orphaned rows, as data. Empty when every key's rows already satisfy it.
+ *
+ * THROWS on a count it cannot read, for exactly the reason {@link toCount} does: an empty
+ * findings list means "asked and satisfied", so an unreadable answer must never be able to
+ * produce one.
+ */
+export function fkOrphanFindings(rows: readonly FkOrphanRow[]): FkOrphanFinding[] {
+  const out: FkOrphanFinding[] = [];
+  for (const r of rows) {
+    const table = String(r.table_name);
+    const constraint = String(r.constraint_name);
+    const orphans = toCount(r.orphans, `${table}.${constraint}`);
+    if (orphans <= 0) continue;
+    out.push({
+      table,
+      constraint,
+      columns: String(r.columns).split(', ').filter((c) => c.length > 0),
+      refTable: String(r.ref_table),
+      orphans,
+      samples: toSamples(r.samples),
+    });
+  }
+  return out;
+}
+
+/**
+ * Split an edge into the statements to RUN and the `VALIDATE`s to WITHHOLD, one per orphaned key.
+ *
+ * The withheld statement is not a failure and not a refusal — it is a check whose answer is
+ * already known, so running it would take a lock and a full scan to be told what the preflight
+ * just counted. It goes into the SAME `pendingValidations` record a check that ran and failed
+ * goes into: the operator's situation is identical (key installed, enforced forward, unproven
+ * against the old rows) and so is the next move.
+ *
+ * Matching is by table + constraint name, which is the name the `VALIDATE` will speak — a rename
+ * in the same edge lands first, and {@link fkOrphanChecks} already keys the check on the NEW
+ * name, so the two agree.
+ */
+export function withheldValidations(
+  statements: readonly string[],
+  findings: readonly FkOrphanFinding[],
+): { statements: string[]; withheld: PendingValidation[] } {
+  if (findings.length === 0) return { statements: [...statements], withheld: [] };
+  const byKey = new Map(findings.map((f) => [`${f.table}::${f.constraint}`, f]));
+  const kept: string[] = [];
+  const withheld: PendingValidation[] = [];
+  for (const statement of statements) {
+    const m = VALIDATE_RE.exec(statementBody(statement));
+    const finding = m ? byKey.get(`${normalizeTableName(m[1])}::${unquote(m[2])}`) : undefined;
+    if (!finding) {
+      kept.push(statement);
+      continue;
+    }
+    withheld.push({
+      sql: statement,
+      // Phrased so it reads as the orphan-data cause it IS — `validationPendingReason` sends
+      // the operator to the data fix, which is the right move here.
+      error:
+        `not attempted: ${finding.orphans} row(s) already in ${finding.table} hold a value in `
+        + `(${finding.columns.join(', ')}) with no matching row in ${finding.refTable}, counted by the foreign-key `
+        + 'row check before any DDL ran. The key is installed and enforced on new writes; the rest of the edge applied.',
+      skipped: true,
+    });
+  }
+  return { statements: kept, withheld };
+}

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/model-render.ts

@@ -549,6 +549,14 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
     if (fk.name && fk.name !== generatedForeignKeyName(bareName(table.table), fk.columns, bareName(fk.refTable), fk.refColumns)) {
       actions.push(`name: ${tsLiteral(fk.name)}`);
     }
+    // The key is live and has NEVER been checked against the rows already in the table. Rendering
+    // it as an ordinary reference would declare a state this database is not in — and the FIRST
+    // plan after the pull would then emit a `VALIDATE` the legacy rows cannot pass. On the schema
+    // this was measured against that was 12 of 23 keys, every one of them deliberately NOT VALID
+    // in the app's own migration ("enforce forward, grandfather legacy"). So the pull SAYS what it
+    // found, the adoption plan comes out empty, and removing the flag later is how an operator
+    // opts into the scan. Same rule as the index and constraint names one line up: be faithful.
+    if (fk.notValid) actions.push('validate: false');
     const opts = actions.length ? `, { ${actions.join(', ')} }` : '';
       expr += `.references(() => ${modelVarName(fk.refTable)}${opts})`;
     } else comment += ` // FK → ${fk.refTable} (not in the pulled set)`;
@@ -631,6 +639,8 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
     if (fk.name && fk.name !== generatedForeignKeyName(bareName(table.table), fk.columns, bareName(fk.refTable), fk.refColumns)) {
       actions.push(`name: ${tsLiteral(fk.name)}`);
     }
+    // Faithful about validity, exactly as the single-column case above is — see there for why.
+    if (fk.notValid) actions.push('validate: false');
     const opts = actions.length ? `, { ${actions.join(', ')} }` : '';
     items.push(`foreignKey(${cols}, () => ${modelVarName(fk.refTable)}, ${refCols}${opts})`);
   }

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-compile.ts

@@ -187,6 +187,12 @@ function refActions(spec: { onDelete?: string; onUpdate?: string }): { onDelete?
  * disagree. Single-column FKs come from each field's `.references()`; composite FKs come from
  * the table-level `foreignKey([...], () => Other, [...])` constraint. Both name themselves the
  * way drizzle does — `<table>_<cols>_<target>_<refcols>_fk` — so a brownfield FK round-trips.
+ *
+ * `validate: false` on either surface compiles to `notValid: true`. That is the DECLARED half of
+ * a field introspection also sets (see {@link ForeignKey.notValid}): the author is saying this
+ * key's permanent state is installed-and-unproven, so the differ must never emit a `VALIDATE`
+ * for it and the from-scratch build must land it `NOT VALID` — otherwise the declared state and
+ * the state a build of that declaration produces would be two different states.
  */
 export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
   const out: ForeignKey[] = [];
@@ -207,6 +213,7 @@ export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
       refTable: refTableName(target),
       refColumns: [targetPk],
       ...refActions(field.spec),
+      ...(field.spec.referencesValidate === false ? { notValid: true } : {}),
     });
   }
 
@@ -222,6 +229,7 @@ export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
       refTable: refTableName(target),
       refColumns: refCols,
       ...refActions(con),
+      ...(con.validate === false ? { notValid: true } : {}),
     });
   }
 
@@ -614,6 +622,10 @@ export { sequenceCreateSql } from './schema-diff';
  * are emitted *after* every `CREATE TABLE` (a FK's target table must already exist), so they
  * are separate from the table DDL — which is why FKs are not rendered inline by
  * compileCreateTable. Named the way drizzle names them: `<table>_<cols>_<target>_<refcols>_fk`.
+ *
+ * A key declared `validate: false` is rendered `… NOT VALID` here too. The declared state IS
+ * unproven-against-old-rows, so a migration artifact that installed it validated would build a
+ * database that does not match the models it was generated from.
  */
 export function foreignKeySql(model: ModelDescriptor): string[] {
   return modelForeignKeys(model).map((fk) => {
@@ -624,7 +636,8 @@ export function foreignKeySql(model: ModelDescriptor): string[] {
     // stays bare-but-quoted (`"uploads"`), preserving the proven output.
     return (
       `ALTER TABLE ${qualifiedTable(model)} ADD CONSTRAINT "${fk.name}" ` +
-      `FOREIGN KEY (${cols}) REFERENCES ${quoteParts(fk.refTable)}(${refCols})${refActionSql(fk)};`
+      `FOREIGN KEY (${cols}) REFERENCES ${quoteParts(fk.refTable)}(${refCols})${refActionSql(fk)}`
+      + `${fk.notValid ? ' NOT VALID' : ''};`
     );
   });
 }