@everystack/cli 0.4.84 → 0.4.85

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);
 }

package/src/cli/schema-fingerprint-v12.ts

@@ -0,0 +1,239 @@
+/**
+ * FROZEN v12 canonicalizer — the exact live-side hash the CLI produced under
+ * FINGERPRINT_VERSION 12, before a NOT VALID foreign key entered the state at v13.
+ *
+ * DO NOT EDIT this to track new behaviour. It exists for ONE purpose: `db:apply`'s
+ * fast-forward proof recomputes a `schema_log` row recorded at `fp_version = 12` against a
+ * CURRENT live read, and comparing an old-format hash against a current-format one reports a
+ * phantom mismatch. So the descent registry recomputes the LIVE side under the ROW's canon —
+ * this function — per the standing rule in `RETAINED_CANONS`.
+ *
+ * It is a SELF-CONTAINED copy of the v12 canonical form. The ONLY behavioural difference from
+ * v13 is the foreign-key slice: v12 hashed a key's columns, target and referential actions and
+ * nothing else, so a key pg had never checked against the rows already in the table (`NOT
+ * VALID`) hashed IDENTICALLY to the validated key the models declare — a half-applied key
+ * reported MATCH. v13 adds the flag. Everything else (the command fan, effective-privilege
+ * deadness, the USAGE-only sequence derivation) is byte-identical to v13 and frozen here so a
+ * future change to the live form cannot silently move a recorded v12 hash. It reuses only the
+ * stable leaf normalizers (deparse + structure) and the authz-contract privilege oracles, whose
+ * behaviour is equal across every version.
+ */
+
+import { createHash } from 'node:crypto';
+import type { PolicyContract, TableContract, SequenceGrantContract } from './authz-contract';
+import { holdsPrivilegeEffective, policyCommands } from './authz-contract';
+import type { SchemaSnapshot, TableSchema } from './schema-introspect';
+import { normalizeDefault, normalizeCheck, indexKey, nextvalSequence } from './schema-diff';
+import { stableStringify, schemaOf, type CanonicalizeOptions } from './schema-fingerprint';
+
+const PUBLIC_ROLE = 'public';
+
+const byKey = <T>(items: T[], key: (item: T) => string): T[] =>
+  [...items].sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+
+// --- v12 authz canonical form (frozen: the command fan, identical to v13) ---
+
+interface PolicyArm {
+  role: string;
+  command: string;
+  permissive: boolean;
+  using: string;
+  check: string;
+}
+
+function policyArms(p: PolicyContract): PolicyArm[] {
+  const roles = p.roles.includes(PUBLIC_ROLE) ? [PUBLIC_ROLE] : [...p.roles].sort();
+  const arms: PolicyArm[] = [];
+  for (const command of policyCommands(p)) {
+    const using = command === 'INSERT' ? '' : (p.using ?? '');
+    const check = command === 'SELECT' || command === 'DELETE' ? '' : ((p.check ?? p.using) ?? '');
+    for (const role of roles) arms.push({ role, command, permissive: p.permissive, using, check });
+  }
+  return arms;
+}
+
+function armKey(a: PolicyArm): string {
+  return `${a.role}|${JSON.stringify([a.command, a.permissive, a.using, a.check])}`;
+}
+
+function multiset(entries: string[]): Array<[string, number]> {
+  const counts = new Map<string, number>();
+  for (const e of entries) counts.set(e, (counts.get(e) ?? 0) + 1);
+  return [...counts.entries()].sort(([a], [b]) => (a < b ? -1 : 1));
+}
+
+function governedArm(governed: ReadonlySet<string>, role: string): boolean {
+  return governed.has(role) || role === PUBLIC_ROLE || (role.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'));
+}
+
+function armDead(t: TableContract, a: PolicyArm): boolean {
+  if (a.role === PUBLIC_ROLE || a.role.toUpperCase() === 'PUBLIC') {
+    const grantees = t.effectivePrivileges
+      ? Object.keys(t.effectivePrivileges)
+      : [...new Set([...Object.keys(t.grants), ...Object.keys(t.columnGrants ?? {})])];
+    return !grantees.some((r) => holdsPrivilegeEffective(t, r, a.command));
+  }
+  return !holdsPrivilegeEffective(t, a.role, a.command);
+}
+
+function armSubsumed(a: PolicyArm, alive: readonly PolicyArm[]): boolean {
+  if (!a.permissive || a.role === PUBLIC_ROLE || a.role.toUpperCase() === 'PUBLIC') return false;
+  return alive.some((o) =>
+    (o.role === PUBLIC_ROLE || o.role.toUpperCase() === 'PUBLIC')
+    && o.permissive && o.command === a.command && o.using === a.using && o.check === a.check);
+}
+
+function canonicalPolicyArms(contract: TableContract, governed?: ReadonlySet<string>): Array<[string, number]> {
+  const alive = contract.policies.flatMap(policyArms).filter((a) => !armDead(contract, a));
+  const kept = alive
+    .filter((a) => !armSubsumed(a, alive))
+    .filter((a) => (governed ? governedArm(governed, a.role) : true));
+  return multiset(kept.map(armKey));
+}
+
+function governedOnly<T>(map: Record<string, T> | undefined, governed: ReadonlySet<string> | undefined): Record<string, T> {
+  if (!map) return {};
+  if (!governed) return map;
+  return Object.fromEntries(
+    Object.entries(map).filter(([grantee]) => governed.has(grantee) || (grantee.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'))),
+  );
+}
+
+function canonicalAuthzV12(contract: TableContract, governed?: ReadonlySet<string>): Record<string, unknown> {
+  const grants = governedOnly(contract.grants, governed);
+  const columnGrants = governedOnly(contract.columnGrants, governed);
+  return {
+    table: contract.table,
+    rls: { enabled: contract.rls.enabled, forced: contract.rls.forced },
+    grants: Object.fromEntries(
+      Object.entries(grants).map(([role, privs]) => [role, [...(privs as string[])].sort()] as const).sort(([a], [b]) => (a < b ? -1 : 1)),
+    ),
+    ...(Object.keys(columnGrants).length > 0
+      ? {
+          columnGrants: Object.fromEntries(
+            Object.entries(columnGrants)
+              .map(([role, byPriv]) => [
+                role,
+                Object.fromEntries(
+                  Object.entries(byPriv as Record<string, string[]>).map(([priv, cols]) => [priv, [...cols].sort()] as const).sort(([a], [b]) => (a < b ? -1 : 1)),
+                ),
+              ] as const)
+              .sort(([a], [b]) => (a < b ? -1 : 1)),
+          ),
+        }
+      : {}),
+    policies: canonicalPolicyArms(contract, governed),
+  };
+}
+
+// --- v12 base-schema canonical form (v13 adds the NOT VALID flag to the FK slice; everything
+//     else is identical, frozen here for self-containment) ---
+
+function canonicalTableV12(table: TableSchema): Record<string, unknown> {
+  return {
+    table: table.table,
+    columns: byKey(
+      table.columns.map((c) => ({ name: c.name, type: c.type, notNull: c.notNull, default: normalizeDefault(c.default) })),
+      (c) => c.name,
+    ),
+    primaryKey: table.primaryKey,
+    uniques: byKey(table.uniques.map((u) => ({ columns: u.columns })), (u) => u.columns.join(',')),
+    checks: byKey(table.checks.map((c) => ({ expr: normalizeCheck(c.expr) })), (c) => c.expr),
+    foreignKeys: byKey(
+      table.foreignKeys.map((f) => ({
+        columns: f.columns, refTable: f.refTable, refColumns: f.refColumns,
+        ...(f.onDelete ? { onDelete: f.onDelete } : {}),
+        ...(f.onUpdate ? { onUpdate: f.onUpdate } : {}),
+      })),
+      (f) => stableStringify(f),
+    ),
+    indexes: [...new Set(table.indexes.map(indexKey))].sort(),
+  };
+}
+
+// --- v12 serial-sequence ACL slice (frozen: USAGE only, exactly as v13 derives it) ---
+
+/**
+ * The v12 inheritance rule: an INSERT-holder inherits USAGE on the table's serial sequence —
+ * exactly what `nextval` needs, and exactly what v13 still derives. Pinned as a literal here
+ * (rather than imported) so a LATER narrowing or widening of the live rule cannot move a hash
+ * this function is supposed to reproduce forever.
+ */
+function inheritedSequenceGrantsV12(table: TableContract): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const [grantee, privileges] of Object.entries(table.grants)) {
+    if (privileges.includes('INSERT')) out[grantee] = ['USAGE'];
+  }
+  return out;
+}
+
+function isGovernedGrantee(governed: ReadonlySet<string> | undefined, grantee: string): boolean {
+  if (!governed) return true;
+  return governed.has(grantee) || (grantee.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'));
+}
+
+function seqShape(grants: Record<string, string[]>, governed?: ReadonlySet<string>): string {
+  const kept = Object.entries(grants)
+    .filter(([grantee, privs]) => privs.length > 0 && isGovernedGrantee(governed, grantee))
+    .map(([grantee, privs]) => [grantee, [...privs].sort()] as const);
+  return stableStringify(Object.fromEntries(kept));
+}
+
+function canonicalSequenceAuthzV12(
+  tables: TableSchema[],
+  authzTables: TableContract[],
+  measured: SequenceGrantContract[] | undefined,
+  governed: ReadonlySet<string> | undefined,
+  keepTable: (name: string) => boolean,
+): Array<[string, string[]]> {
+  const snapshotByTable = new Map(tables.map((t) => [t.table, t]));
+  const measuredByTable = new Map<string, SequenceGrantContract[]>();
+  for (const s of measured ?? []) {
+    (measuredByTable.get(s.table) ?? measuredByTable.set(s.table, []).get(s.table)!).push(s);
+  }
+  const out: Array<[string, string[]]> = [];
+  for (const az of authzTables) {
+    if (!keepTable(az.table)) continue;
+    let shapes: string[];
+    if (measuredByTable.has(az.table)) {
+      shapes = measuredByTable.get(az.table)!.filter((s) => !s.identity).map((s) => seqShape(s.grants, governed));
+    } else {
+      const snap = snapshotByTable.get(az.table);
+      const serialCount = (snap?.columns ?? []).filter((c) => nextvalSequence(normalizeDefault(c.default)) != null).length;
+      if (serialCount === 0) continue;
+      const inherited = seqShape(inheritedSequenceGrantsV12(az), governed);
+      shapes = Array.from({ length: serialCount }, () => inherited);
+    }
+    if (shapes.length === 0) continue;
+    out.push([az.table, shapes.sort()]);
+  }
+  return out.sort(([a], [b]) => (a < b ? -1 : 1));
+}
+
+/** The frozen v12 live hash for (snapshot, authzTables, opts). */
+export function fingerprintV12(snapshot: SchemaSnapshot, authzTables: TableContract[], opts: CanonicalizeOptions = {}): string {
+  const inScope = opts.schemas ? new Set(opts.schemas) : null;
+  const keepTable = (name: string) => inScope === null || inScope.has(schemaOf(name));
+  const tables = snapshot.tables.filter((t) => keepTable(t.table));
+  const usedEnum = new Set<string>();
+  for (const t of tables) for (const c of t.columns) usedEnum.add(schemaOf(c.type) === 'public' ? c.type : c.type.slice(c.type.indexOf('.') + 1));
+  const sequences = byKey(
+    (snapshot.sequences ?? [])
+      .filter((s) => inScope === null || inScope.has(schemaOf(s.name)))
+      .map((s) => ({ name: s.name, as: s.as, ...(s.start != null ? { start: s.start } : {}), ...(s.increment != null ? { increment: s.increment } : {}) })),
+    (s) => String(s.name),
+  );
+  const sequenceAuthz = canonicalSequenceAuthzV12(tables, authzTables, opts.sequenceGrants, opts.governedRoles, keepTable);
+  const canonical = {
+    v: 12,
+    tables: byKey(tables.map(canonicalTableV12), (t) => String(t.table)),
+    enums: byKey(
+      (snapshot.enums ?? []).filter((e) => inScope === null || usedEnum.has(e.name)).map((e) => ({ name: e.name, values: e.values })),
+      (e) => e.name,
+    ),
+    authz: byKey(authzTables.filter((t) => keepTable(t.table)).map((t) => canonicalAuthzV12(t, opts.governedRoles)), (t) => String(t.table)),
+    ...(sequences.length ? { sequences } : {}),
+    ...(sequenceAuthz.length ? { sequenceAuthz } : {}),
+  };
+  return createHash('sha256').update(stableStringify(canonical)).digest('hex');
+}

package/src/cli/schema-fingerprint.ts

@@ -61,6 +61,7 @@ import { governedRoleSet, inheritedSequenceGrants } from './authz-reconcile';
 import { normalizeDefault, normalizeCheck, indexKey, nextvalSequence } from './schema-diff';
 import { fingerprintV10 } from './schema-fingerprint-v10';
 import { fingerprintV11 } from './schema-fingerprint-v11';
+import { fingerprintV12 } from './schema-fingerprint-v12';
 
 // v2: expression fields (defaults, checks, partial-index WHERE) normalize through
 // the diff's pg-deparse normalizers before hashing, so the model form and the live
@@ -141,7 +142,20 @@ import { fingerprintV11 } from './schema-fingerprint-v11';
 // On every deployed stage the next db:plan mints a REVOKE narrowing those sequence grants to USAGE
 // (the report classifies it as narrowing access). The v11 canon is frozen in schema-fingerprint-v11
 // and registered in RETAINED_CANONS so a schema_log row recorded under it still descends.
-export const FINGERPRINT_VERSION = 12;
+// v13 — a NOT VALID foreign key is its OWN state. A foreign key added `NOT VALID` exists and is
+// enforced on every new write, but has never been checked against the rows already in the table:
+// it is the declared key one step short, and that step is precisely where a two-step add
+// (`ADD … NOT VALID` then `VALIDATE`) can be interrupted. The v12 form hashed a key's columns,
+// target and referential actions only, so the half-applied key and the validated one the models
+// declare were the SAME hash — `db:fingerprint` reported MATCH on a database whose rows no
+// constraint had ever been proved against, and a re-plan had nothing to emit. The flag now rides
+// the canonical form (written only when true, so a fully-valid database's hash is unmoved by the
+// field itself; the `v` stamp moves it, like every bump). Same consequence as every bump: a plan
+// or baseline minted under v12 refuses as a FORMAT CHANGE and must be re-minted (db:plan) or
+// re-baselined (db:reconcile --rebaseline) — no DDL, the fingerprint is a content address. The
+// v12 canon is frozen in schema-fingerprint-v12 and registered in RETAINED_CANONS so a schema_log
+// row recorded under it still descends.
+export const FINGERPRINT_VERSION = 13;
 
 // ---------------------------------------------------------------------------
 // Canonical form.
@@ -178,11 +192,18 @@ function canonicalTable(table: TableSchema): Record<string, unknown> {
     // Predicates hash as the diff compares them — one layer of pg's wrapping parens dropped
     // (`(scope = ANY (...))` == `scope = ANY (...)`), whitespace collapsed.
     checks: byKey(table.checks.map((c) => ({ expr: normalizeCheck(c.expr) })), (c) => c.expr),
+    // v13: a key pg has NEVER CHECKED against the rows already in the table is not the key the
+    // models declare — it is that key one step short, and the difference is exactly the step a
+    // two-step add can be interrupted between. Without the flag a half-applied foreign key
+    // hashed identically to a validated one, so `db:fingerprint` reported MATCH on a database
+    // whose data no constraint had ever been proved against. Written only when true, so every
+    // fully-valid database keeps the hash it had.
     foreignKeys: byKey(
       table.foreignKeys.map((f) => ({
         columns: f.columns, refTable: f.refTable, refColumns: f.refColumns,
         ...(f.onDelete ? { onDelete: f.onDelete } : {}),
         ...(f.onUpdate ? { onUpdate: f.onUpdate } : {}),
+        ...(f.notValid ? { notValid: true } : {}),
       })),
       (f) => stableStringify(f),
     ),
@@ -500,13 +521,15 @@ export type CanonHasher = (
  * absent from this map is unrecomputable: `fingerprintLiveAtVersion` returns null and descent
  * SKIPS that row (fails closed), never guesses a hash.
  *
- * Retired entries: `fingerprintV10` (no command fan, direct-grant deadness, no sequence ACLs) and
+ * Retired entries: `fingerprintV10` (no command fan, direct-grant deadness, no sequence ACLs),
  * `fingerprintV11` (the command fan and sequence ACLs, but the pre-least-privilege derivation that
- * gave an INSERT-holder SELECT + UPDATE + USAGE on its sequence).
+ * gave an INSERT-holder SELECT + UPDATE + USAGE on its sequence), and `fingerprintV12` (everything
+ * v13 has except the foreign-key validity flag, so a NOT VALID key hashed as a validated one).
  */
 export const RETAINED_CANONS: Readonly<Record<number, CanonHasher>> = {
   10: (snapshot, tables, opts) => fingerprintV10(snapshot, tables, opts),
   11: (snapshot, tables, opts) => fingerprintV11(snapshot, tables, opts),
+  12: (snapshot, tables, opts) => fingerprintV12(snapshot, tables, opts),
   [FINGERPRINT_VERSION]: (snapshot, tables, opts) => fingerprintState(snapshot, tables, opts).hash,
 };
 

package/src/cli/schema-introspect.ts

@@ -52,6 +52,18 @@ export interface ForeignKey {
   /** Lowercased referential actions, omitted when the Postgres default (`no action`). */
   onDelete?: string;
   onUpdate?: string;
+  /**
+   * The constraint exists but has NOT been checked against the rows already in the table
+   * (`convalidated = false`; `pg_get_constraintdef` spells it `… NOT VALID`).
+   *
+   * LIVE-SIDE ONLY. A Model declares a foreign key, never a half-installed one, so the
+   * compiled side never sets this — which is exactly what makes it visible as drift: a live
+   * NOT VALID key is a DIFFERENT state from the declared (validated) one. It rides the
+   * canonical fingerprint form for the same reason, so a half-applied key can never report
+   * MATCH. Omitted (not `false`) when the constraint is validated, so every already-recorded
+   * hash for a fully-valid database is untouched.
+   */
+  notValid?: boolean;
 }
 
 export interface UniqueConstraint {
@@ -416,6 +428,8 @@ export interface ConstraintDescriptor {
   /** FK referential actions, lowercased; omitted when the Postgres default (`no action`). */
   onDelete?: string;
   onUpdate?: string;
+  /** FK installed but never checked against the existing rows (`… NOT VALID`); omitted when valid. */
+  notValid?: boolean;
 }
 
 /** Parse one `pg_get_constraintdef` row into a structured descriptor. */
@@ -448,6 +462,12 @@ export function constraintRowToDescriptor(row: ConstraintRow): ConstraintDescrip
       refColumns: m ? parseColumnList(m[3]) : [],
       onDelete: action('DELETE'),
       onUpdate: action('UPDATE'),
+      // `pg_get_constraintdef` appends NOT VALID to a constraint pg has never checked against
+      // the rows already in the table — the state a two-step FK add leaves behind between its
+      // ADD and its VALIDATE. Read from the SAME deparsed text as everything else here, so no
+      // second catalog column has to be threaded through every caller of CONSTRAINTS_SQL.
+      // Omitted when valid: absence is what keeps a fully-valid snapshot byte-identical.
+      ...(/\bNOT\s+VALID\s*$/i.test(def.trim()) ? { notValid: true } : {}),
     };
   }
   // check — keep the predicate text inside the outer CHECK ( ... ), normalized.
@@ -662,6 +682,9 @@ export function assembleSchema(rows: SchemaRows): SchemaSnapshot {
           name: d.name, columns: d.columns ?? [], refTable: d.refTable ?? '', refColumns: d.refColumns ?? [],
           ...(d.onDelete ? { onDelete: d.onDelete } : {}),
           ...(d.onUpdate ? { onUpdate: d.onUpdate } : {}),
+          // Carried, not dropped: an unchecked key is a DIFFERENT state from a checked one, and
+          // the snapshot is what the differ and the fingerprint both read.
+          ...(d.notValid ? { notValid: true } : {}),
         });
         break;
     }