@everystack/cli 0.4.83 → 0.4.85

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

package/src/cli/state-apply.ts

@@ -26,7 +26,12 @@ import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog';
 import { generateMigrationSql, HELD_DROP_PREFIX } from './migration-generate';
 import type { SequenceDescriptor } from '@everystack/model';
 import { fingerprintLive, FINGERPRINT_VERSION } from './schema-fingerprint';
-import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from './derived-apply';
+import {
+  ENSURE_RECONCILER_SQL,
+  renderSchemaLogInsert,
+  renderSchemaLogFingerprintUpdate,
+  renderSchemaLogCompletionUpdate,
+} from './derived-apply';
 import { isPureComment, statementBody, statementHead } from './sql-statement';
 
 const NOTICE_PREFIX = '-- NOTICE';
@@ -52,6 +57,32 @@ export function classifyGeneratedStatements(statements: string[]): ClassifiedSta
   return { executable, heldDrops, notices };
 }
 
+/**
+ * Split an executable stream into the EDGE and the CHECKS: `ALTER TABLE … VALIDATE CONSTRAINT`
+ * is held out of the batch and run afterwards, one statement at a time.
+ *
+ * This is what makes the two-step foreign-key add worth splitting at all. `ADD CONSTRAINT …
+ * NOT VALID` holds an ACCESS EXCLUSIVE lock until its transaction COMMITS, so a VALIDATE in the
+ * same transaction runs under that lock and blocks every writer for the whole scan — precisely
+ * the outage the split exists to avoid. Run after the commit, the VALIDATE takes its own, much
+ * weaker SHARE UPDATE EXCLUSIVE lock, which readers and writers pass through.
+ *
+ * The second consequence is durability, and it is the point of doing it here rather than in the
+ * emitter: a VALIDATE that fails no longer rolls back the edge. The key stays installed and
+ * NOT VALID — enforced on every new write, unproven against the old rows — which is a state the
+ * next `db:plan` sees and finishes with a VALIDATE alone. An edge that rolled back instead would
+ * have thrown away a correct, committed schema change because of data it does not own.
+ */
+export function splitValidations(executable: readonly string[]): { batch: string[]; validations: string[] } {
+  const batch: string[] = [];
+  const validations: string[] = [];
+  for (const statement of executable) {
+    if (/^ALTER\s+TABLE\s+[\s\S]+?\sVALIDATE\s+CONSTRAINT\b/i.test(statementBody(statement))) validations.push(statement);
+    else batch.push(statement);
+  }
+  return { batch, validations };
+}
+
 /**
  * The destructive subset of an executable statement stream — destructive
  * means DATA LOSS (brick 9's classification, design decision 11):
@@ -105,12 +136,14 @@ const ADDITIVE_MATCHERS: RegExp[] = [
   /^GRANT\b/,
   /^COMMENT\s+ON\b/,
   // ADD COLUMN alone. Its siblings `ADD CONSTRAINT` (FOREIGN KEY / CHECK / UNIQUE) and
-  // `ADD PRIMARY KEY` are deliberately NOT here: each one VALIDATES every row already in the
-  // table and then RESTRICTS every write after it. An FK add fails on orphan rows, a CHECK add
-  // fails on any violating row, a UNIQUE add fails on existing duplicates, and ADD PRIMARY KEY
-  // fails on duplicates or NULLs *and* silently makes every included column NOT NULL. Calling
-  // those additive tells the reviewer the plan is safe when it can abort the apply outright —
-  // the same false zero described above. They read as `unclassified`, like `SET NOT NULL`.
+  // `ADD PRIMARY KEY` are deliberately NOT here: each one RESTRICTS every write after it, and
+  // all but the NOT VALID form also VALIDATE every row already in the table. A CHECK add fails
+  // on any violating row, a UNIQUE add fails on existing duplicates, and ADD PRIMARY KEY fails
+  // on duplicates or NULLs *and* silently makes every included column NOT NULL. A foreign key
+  // is emitted `NOT VALID` and so cannot fail on the old rows — but its `VALIDATE CONSTRAINT`
+  // can, and it still refuses every future write that breaks it. Calling any of these additive
+  // tells the reviewer the plan is safe when it can abort the apply outright — the same false
+  // zero described above. They read as `unclassified`, like `SET NOT NULL`.
   /^ALTER\s+TABLE\s+[\s\S]+?\sADD\s+COLUMN\b/,
   // Enabling/forcing RLS only ever RESTRICTS; it cannot widen access or lose a row.
   /^ALTER\s+TABLE\s+[\s\S]+?\s(ENABLE|FORCE)\s+ROW\s+LEVEL\s+SECURITY\b/,
@@ -344,6 +377,30 @@ export interface StateApplyOptions {
    * row is still a witness.
    */
   descentNote?: () => string | undefined;
+  /**
+   * Read the live base fingerprint, for the row written the instant the batch commits.
+   *
+   * The `state apply` row is only a descent WITNESS if it carries a `to_fingerprint`
+   * (SCHEMA_LOG_WITNESS_SQL requires one), and it must be the hash of the database AS IT IS at
+   * that moment — with the new key installed and NOT VALID. Stamping the plan's target state
+   * there would be a prediction, not a record: if the process then dies mid-VALIDATE, the next
+   * apply recomputes the live hash, does not match the stamped one, and the row it was given to
+   * protect itself with is inert. The plan's own endpoint is stamped by the caller AFTER the
+   * last check passes.
+   *
+   * Optional: without it the row still goes in before the checks, and the caller fills the
+   * fingerprint in when it re-introspects (db:sync's lane). Called ONLY when there are checks to
+   * run — with none there is no window between the commit and the record to protect.
+   */
+  readFingerprint?: () => Promise<string>;
+}
+
+/** A `VALIDATE CONSTRAINT` that did not pass — the key is installed but still unproven. */
+export interface PendingValidation {
+  /** The exact statement to re-run once the data satisfies the key. */
+  sql: string;
+  /** PostgreSQL's message, trimmed for the record. */
+  error: string;
 }
 
 export interface StateApplyResult {
@@ -354,12 +411,25 @@ export interface StateApplyResult {
   batchSql: string;
   /** schema_log row id for this apply, when one was written. */
   logId?: number;
+  /**
+   * Constraints left NOT VALID because their post-commit `VALIDATE` failed. The edge itself
+   * COMMITTED — this is not a rollback and must never be reported as one. Empty on a clean apply.
+   */
+  pendingValidations: PendingValidation[];
 }
 
 /**
  * Execute the executable subset of a generated diff as one batch and record
  * it in schema_log. A failed batch rolls back (one implicit transaction),
  * logs the failure best-effort, and rethrows.
+ *
+ * ORDER OF WRITES, and it is the point: batch → RECORD → checks → amend the record. The
+ * `VALIDATE CONSTRAINT` pass is the longest thing an apply does (a full scan per key) and the
+ * one a wall clock or a dropped connection actually kills. Recording after it meant that death
+ * left the DDL committed with nothing on the record — and a live state no commit on any ref
+ * declares reads to the NEXT apply as proven drift, which is the loudest possible wrong answer.
+ * So the row is written as soon as the batch has committed, describing exactly what is true then
+ * (the key installed, none of the checks run yet), and amended when the checks are over.
  */
 export async function applyGeneratedStatements(
   runner: QueryRunner,
@@ -368,18 +438,28 @@ export async function applyGeneratedStatements(
 ): Promise<StateApplyResult> {
   const classified = classifyGeneratedStatements(statements);
   if (classified.executable.length === 0) {
-    return { applied: false, classified, batchSql: '' };
+    return { applied: false, classified, batchSql: '', pendingValidations: [] };
   }
 
   const now = options.now ?? Date.now;
   await runner(ENSURE_RECONCILER_SQL.join(';\n'));
 
+  // The row checks run AFTER the edge commits — see splitValidations for why that is the whole
+  // point of the two-step add, and why a failed check is a pending state rather than a rollback.
+  const { batch, validations } = splitValidations(classified.executable);
+
   // Semicolon on its own line: a statement whose last line is a comment
   // cannot swallow the separator.
-  const batchSql = classified.executable.join('\n;\n');
+  //
+  // `batchSql` is the batch that RAN IN THIS TRANSACTION — the checks are not in it. The record
+  // written below is a record of what committed, and the checks had not been attempted at that
+  // point; they join the row on the amendment, where their outcome is known.
+  const batchSql = batch.join('\n;\n');
+  const validationSql = validations.join('\n;\n');
+  const fullSql = [batchSql, validationSql].filter((s) => s.length > 0).join('\n;\n');
   const started = now();
   try {
-    await runner(batchSql);
+    if (batch.length > 0) await runner(batchSql);
   } catch (err: any) {
     try {
       await runner(renderSchemaLogInsert({
@@ -395,16 +475,79 @@ export async function applyGeneratedStatements(
   }
 
   const note = options.descentNote?.();
+  // The edge APPLIED — that word is load-bearing (the descent ledger matches `applied%`, and the
+  // schema changes really are committed). What is still unproven is named in the same line, so
+  // nobody reads a half-proven key as a finished one.
+  const outcomeWith = (pending: number): string =>
+    ['applied', note, pending > 0 ? `${pending} constraint(s) PENDING validation` : undefined]
+      .filter(Boolean)
+      .join(' — ');
+
+  // The hash of what just committed, read now rather than predicted. Only when checks follow:
+  // with none, the record goes in the same breath as the commit (as it always has) and the
+  // caller's own post-apply introspection stamps it — reading it twice would buy nothing and
+  // cost a full introspection on every apply. Best-effort: a fingerprint that cannot be read
+  // must not cost us the record.
+  let landedAfterBatch: string | undefined;
+  if (validations.length > 0 && options.readFingerprint) {
+    try {
+      landedAfterBatch = await options.readFingerprint();
+    } catch { /* the record matters more than the stamp */ }
+  }
+
+  // THE WITNESS, written before the long step. Every check is still outstanding here, and the
+  // outcome says exactly that — this row is true at the instant it is written, not a prediction
+  // of how the checks will go.
   const logRows = await runner(renderSchemaLogInsert({
-    kind: 'state apply', sql: batchSql, outcome: note ? `applied — ${note}` : 'applied',
+    kind: 'state apply', sql: batchSql, outcome: outcomeWith(validations.length),
     actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
     fromFingerprint: options.fromFingerprint,
+    ...(landedAfterBatch ? { toFingerprint: landedAfterBatch } : {}),
     fpVersion: options.fpVersion ?? FINGERPRINT_VERSION, dirty: options.dirty ?? false,
     durationMs: now() - started,
   }));
   const logId = logRows?.[0]?.id !== undefined ? Number(logRows[0].id) : undefined;
 
-  return { applied: true, classified, batchSql, ...(logId !== undefined ? { logId } : {}) };
+  // Every check is attempted, even after one fails: the operator is owed the COMPLETE list of
+  // keys still unproven, not the first one. Each runs on its own, so one failure cannot take a
+  // sibling's successful validation down with it.
+  const pendingValidations: PendingValidation[] = [];
+  for (const statement of validations) {
+    try {
+      await runner(statement);
+    } catch (err: any) {
+      pendingValidations.push({ sql: statement, error: String(err?.message ?? err).slice(0, 500) });
+    }
+  }
+
+  // The amendment: the SAME row, finished. A second `state apply` row would put two applies in
+  // the ledger for one edge — and the descent witness reads that ledger. So the checks and their
+  // result land on the row that already describes this apply, never beside it.
+  if (validations.length > 0 && logId !== undefined) {
+    try {
+      await runner(renderSchemaLogCompletionUpdate(logId, {
+        outcome: outcomeWith(pendingValidations.length),
+        sql: fullSql,
+        durationMs: now() - started,
+      }));
+    } catch { /* the memoir is best-effort; the row already says what committed */ }
+  }
+
+  // One row per unproven key, carrying the exact statement to re-run. Best-effort, like every
+  // other memoir write: failing to record why a key is pending must not mask that it is.
+  for (const pending of pendingValidations) {
+    try {
+      await runner(renderSchemaLogInsert({
+        kind: 'state validate', sql: pending.sql,
+        outcome: `pending: ${pending.error}`,
+        actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
+        fromFingerprint: options.fromFingerprint,
+        fpVersion: options.fpVersion ?? FINGERPRINT_VERSION, dirty: options.dirty ?? false,
+      }));
+    } catch { /* see above */ }
+  }
+
+  return { applied: true, classified, batchSql, pendingValidations, ...(logId !== undefined ? { logId } : {}) };
 }
 
 // ---------------------------------------------------------------------------
@@ -433,6 +576,9 @@ export interface StateSyncOutcome {
   toFingerprint: string;
   /** Executable statements still differing after apply — empty is the bar. */
   remaining: string[];
+  /** Constraints whose post-commit `VALIDATE` failed: installed, enforced, still unproven. They
+   *  also show up in `remaining` as a VALIDATE the next run re-emits. */
+  pendingValidations: PendingValidation[];
   /** schema_log row id, when DDL ran. */
   logId?: number;
   /** Fresh post-apply introspection (the pre-apply one when nothing ran). */
@@ -463,7 +609,7 @@ export async function applyStateAndVerify(
   if (classified.executable.length === 0) {
     return {
       statements, classified, applied: false,
-      fromFingerprint, toFingerprint: fromFingerprint, remaining: [],
+      fromFingerprint, toFingerprint: fromFingerprint, remaining: [], pendingValidations: [],
       after: { snapshot: current, contract: liveAuthz },
     };
   }
@@ -484,6 +630,7 @@ export async function applyStateAndVerify(
   return {
     statements, classified, applied: true,
     fromFingerprint, toFingerprint, remaining,
+    pendingValidations: result.pendingValidations,
     ...(result.logId !== undefined ? { logId: result.logId } : {}),
     after: { snapshot, contract },
   };