@everystack/cli 0.4.84 → 0.4.86

package/src/cli/schema-diff.ts

@@ -29,6 +29,7 @@ import type {
   TableSchema,
   ColumnSchema,
   EnumType,
+  ForeignKey,
   IndexSchema,
   SequenceSchema,
 } from './schema-introspect';
@@ -41,7 +42,18 @@ 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;
+      /**
+       * The key is installed but unchecked — on the LIVE side an observation, on the DESIRED
+       * side the author's `validate: false` (see {@link ForeignKey.notValid}).
+       *
+       * It is never part of {@link constraintContentKey}: a NOT VALID key IS the declared key,
+       * one step short, so validity can never make a key match a DIFFERENT key. What it decides
+       * is the SECOND statement — a desired `notValid` key emits `ADD … NOT VALID` alone, and a
+       * live `notValid` key is finished with a `VALIDATE` only when the desired side asked for
+       * one.
+       */
+      notValid?: boolean };
 
 export type SchemaChange =
   | { kind: 'createTable'; table: string; schema: TableSchema }
@@ -64,6 +76,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). */
@@ -499,7 +520,7 @@ export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, ren
         addConstraints.push({
           kind: 'addConstraint',
           table: d.table,
-          constraint: { type: 'foreignKey', name: fk.name, columns: fk.columns, refTable: fk.refTable, refColumns: fk.refColumns, onDelete: fk.onDelete, onUpdate: fk.onUpdate },
+          constraint: { type: 'foreignKey', name: fk.name, columns: fk.columns, refTable: fk.refTable, refColumns: fk.refColumns, onDelete: fk.onDelete, onUpdate: fk.onUpdate, ...(fk.notValid ? { notValid: true } : {}) },
         });
       }
       for (const ix of d.indexes) createIndexes.push(createIndexChange(d.table, ix));
@@ -791,7 +812,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 } : {}) })),
   ];
 }
 
@@ -804,10 +825,25 @@ function tableConstraintSpecs(t: TableSchema): ConstraintSpec[] {
  */
 function constraintContentKey(c: ConstraintSpec): string {
   if (c.type === 'unique') return `u|${c.columns.join(',')}`;
-  if (c.type === 'foreignKey') return `f|${c.columns.join(',')}|${c.refTable}|${c.refColumns.join(',')}|${c.onDelete ?? ''}|${c.onUpdate ?? ''}`;
+  if (c.type === 'foreignKey') return foreignKeyContentKey(c);
   return `c|${normalizeCheck(c.expr)}`; // checks take their own predicate-matched path (diffChecks)
 }
 
+/**
+ * A foreign key's content identity — columns, target, target columns, referential actions.
+ * VALIDITY IS NOT IN IT (see {@link ConstraintSpec}), and neither is the name.
+ *
+ * Exported because a second surface asks the same question: the plan's predicted endpoint has to
+ * find the live counterpart of a declared key to carry its validity through. Two spellings of
+ * "are these the same key" is how the differ and the prediction end up disagreeing about whether
+ * an edge changed anything.
+ */
+export function foreignKeyContentKey(
+  fk: Pick<ForeignKey, 'columns' | 'refTable' | 'refColumns' | 'onDelete' | 'onUpdate'>,
+): string {
+  return `f|${fk.columns.join(',')}|${fk.refTable}|${fk.refColumns.join(',')}|${fk.onDelete ?? ''}|${fk.onUpdate ?? ''}`;
+}
+
 /**
  * Diff CHECK constraints by their normalized predicate, not their name: a check with the
  * same predicate is the same check no matter what it's called, so a pulled check (whose DB
@@ -857,6 +893,26 @@ 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 —
+      // what an interrupted two-step add leaves behind, and what a hand-run
+      // `ADD CONSTRAINT … NOT VALID` leaves behind. When the declared side is a VALIDATED key
+      // that 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.
+      //
+      // …UNLESS the declared side ASKED for NOT VALID (`validate: false`). Then live and
+      // declared agree and there is nothing to emit: validating would be the edge doing the
+      // one thing the author declared it must never do. Note the direction — a live key that
+      // is fully VALID under a `validate: false` declaration also falls through here with no
+      // statement, because `matched.notValid` is absent. That is the accept-either rule: there
+      // is no `ALTER TABLE … INVALIDATE CONSTRAINT`, so a key proven MORE than the model asked
+      // for is not a difference anyone could act on.
+      const desiredNotValid = des.type === 'foreignKey' && des.notValid === true;
+      if (matched.type === 'foreignKey' && matched.notValid && !desiredNotValid) {
+        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 +990,43 @@ 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.
+ *
+ * ONE statement again for a key the model declared `validate: false`: step 1 alone IS the whole
+ * declared state there, so step 2 is not deferred, it does not exist. See
+ * `FieldSpec.referencesValidate` for why a schema needs to be able to say that.
+ */
+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 +1034,8 @@ 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};`;
+      const add = `${s} NOT VALID;`;
+      return c.notValid === true ? [add] : [add, validateConstraintSql(table, c.name)];
     }
   }
 }
@@ -959,8 +1048,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 +1108,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 +1191,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,41 @@ 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.
+//
+// NO v14 FOR `validate: false` — worked out here so the next reader does not ask again.
+// The Model can now DECLARE a foreign key permanently NOT VALID (`references(…, { validate:
+// false })` → `ForeignKey.notValid` on the COMPILED side, which v13 said only introspection ever
+// set). A bump is required when the CANONICAL FORM changes — when the same database would hash
+// differently before and after. Neither half of that happens here:
+//
+//   1. The form is byte-identical. `canonicalTable` below already reads `f.notValid` and already
+//      writes it only when true. No key is added, removed, or normalized differently; the shape
+//      that hashes a live snapshot is untouched.
+//   2. Every hash anyone RECORDED is a live hash. `RETAINED_CANONS`/`fingerprintLiveAtVersion`
+//      recompute from a SchemaSnapshot read out of the database, and this feature does not change
+//      what introspection reports about any existing key. So every schema_log row still descends.
+//
+// What moves is the DECLARED hash of a model that newly writes `validate: false` — which is a
+// state change the author made on purpose, exactly like adding a column. That is the format
+// working, not the format changing. (Deliberately kept in step: the from-scratch build emits
+// `ADD … NOT VALID` for such a key too — schema-diff's `addConstraintSql` and schema-compile's
+// `foreignKeySql` — so building a database FROM that declaration lands on the declared hash
+// rather than one step past it. Without that half the declared side would hash a state no build
+// of it could produce, and `db:check` could never reach MATCH.)
+export const FINGERPRINT_VERSION = 13;
 
 // ---------------------------------------------------------------------------
 // Canonical form.
@@ -178,11 +213,23 @@ 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.
+    //
+    // The flag now arrives from EITHER side — introspection's observation, or a Model's
+    // `validate: false` (see the FINGERPRINT_VERSION note above for why that needed no bump).
+    // The canonical form does not care which: one bit, one meaning — this key has never been
+    // checked against the rows that were already there.
     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 +547,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,31 @@ export interface ForeignKey {
   /** Lowercased referential actions, omitted when the Postgres default (`no action`). */
   onDelete?: string;
   onUpdate?: string;
+  /**
+   * The key is enforced on every new write but has NOT been checked against the rows already
+   * in the table (`convalidated = false`; `pg_get_constraintdef` spells it `… NOT VALID`).
+   *
+   * BOTH SIDES SET THIS, and they mean two different things by it:
+   *
+   *   LIVE-OBSERVED      — introspection read `convalidated = false`. It says nothing about
+   *                        WHY: an interrupted two-step add, a hand-run `ADD … NOT VALID`, or
+   *                        a key someone deliberately left unproven years ago.
+   *   DECLARED-INTENTIONAL — the Model said `validate: false` on the reference, which is the
+   *                        author declaring "enforce forward, grandfather legacy" as the
+   *                        PERMANENT state of this key (see `FieldSpec.referencesValidate`).
+   *                        The differ then emits `ADD CONSTRAINT … NOT VALID` and NEVER the
+   *                        paired `VALIDATE`.
+   *
+   * HOW THE TWO MEET. A declared-intentional key is satisfied by EITHER a live NOT VALID key
+   * or a live FULLY-VALID one: PostgreSQL has no "un-validate", so "more proven than you asked
+   * for" is not a difference anybody can act on and must not read as drift. The asymmetry only
+   * runs the other way — a live NOT VALID key under a declaration that did NOT say
+   * `validate: false` IS a real difference, and the edge closes it with a `VALIDATE` alone.
+   *
+   * Omitted (not `false`) when the key is validated, on both sides, so every already-recorded
+   * hash for a fully-valid database is untouched.
+   */
+  notValid?: boolean;
 }
 
 export interface UniqueConstraint {
@@ -416,6 +441,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 +475,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 +695,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;
     }