@everystack/cli 0.4.33 → 0.4.35

package/src/cli/derived-grants.ts

@@ -41,6 +41,21 @@ export interface ParsedGrants {
 const GRANT_RE = /^GRANT\s+([A-Z]+)\s*(\([^)]*\))?\s+ON\s+(.+?)\s+TO\s+(.+)$/i;
 const REVOKE_PUBLIC_RE = /^REVOKE\s+ALL\s+ON\s+(.+?)\s+FROM\s+PUBLIC$/i;
 
+/**
+ * A PLAIN (non-column-scoped) grant/revoke attachment — a table/function-level `GRANT … TO …` with
+ * no column list, or a `REVOKE ALL … FROM PUBLIC`. These are the grants `diffObjectGrants` can fully
+ * express, so `bodyHash` excludes them: an authz-only change to them applies as a bare regrant, never
+ * a rebuild. Column-scoped grants (`GRANT SELECT ("a","b") …`) are NOT plain — attacl is not
+ * introspected, so a change to them must still rebuild; they stay in `bodyHash`. Non-grant
+ * attachments (index/comment) are structural and always return false.
+ */
+export function isPlainGrantAttachment(a: Attachment): boolean {
+  if (a.kind !== 'grant') return false;
+  if (REVOKE_PUBLIC_RE.test(a.sql)) return true;
+  const g = a.sql.match(GRANT_RE);
+  return g !== null && !g[2]; // g[2] is the (columns) group — present => column-scoped => not plain
+}
+
 /** The declared grant contract, read back from an object's own grant attachments. */
 export function parseGrantAttachments(attachments: readonly Attachment[]): ParsedGrants {
   const grants: Record<string, Set<string>> = {};

package/src/cli/derived-introspect.ts

@@ -81,6 +81,9 @@ export interface ProvenanceRow {
   kind?: string;
   /** How to remove what was recorded — the C1 closure: removal never orphans. */
   dropSql?: string;
+  /** The source hash MINUS plain grants at record time. Present only once the reconciler has
+   *  re-recorded the row post-fix; absent on legacy rows → the planner falls back to rebuild. */
+  bodyHash?: string;
 }
 
 export interface DerivedCatalog {
@@ -514,6 +517,7 @@ export function assembleDerivedCatalog(rows: DerivedRows): DerivedCatalog {
       defHash: String(r.def_hash ?? ''),
       ...(r.extra?.kind != null ? { kind: String(r.extra.kind) } : {}),
       ...(r.extra?.drop_sql != null ? { dropSql: String(r.extra.drop_sql) } : {}),
+      ...(r.extra?.body_hash != null ? { bodyHash: String(r.extra.body_hash) } : {}),
     }))
     .sort((a, b) => a.identity.localeCompare(b.identity));
 

package/src/cli/derived-plan.ts

@@ -29,7 +29,7 @@ import type { DerivedCatalog, LiveObject } from './derived-introspect.js';
 import { triggerDropSql } from './derived-apply.js';
 import { parseGrantAttachments, diffObjectGrants } from './derived-grants.js';
 
-export type ReconcileVerb = 'create' | 'replace' | 'refresh' | 'drop' | 'baseline' | 'rebaseline' | 'prune';
+export type ReconcileVerb = 'create' | 'replace' | 'refresh' | 'drop' | 'baseline' | 'rebaseline' | 'prune' | 'backfill';
 
 export interface ReconcileAction {
   action: ReconcileVerb;
@@ -192,6 +192,9 @@ export function planReconcile(
   const baseline: string[] = [];
   const rebaseline: string[] = [];
   const prune: string[] = [];
+  /** Up-to-date objects (src+live unchanged) whose provenance predates body_hash — record it once
+   *  so a FUTURE authz-only change is a regrant, not a rebuild. Record-only, no DDL; arms the fix. */
+  const backfill: string[] = [];
 
   // -------------------------------------------------------------------------
   // The decision table.
@@ -289,14 +292,34 @@ export function planReconcile(
       continue;
     }
     if (srcChanged) {
+      // Authz-only change: the BODY (and live) is untouched, only plain grants moved — bodyHash
+      // matches provenance. Route it like a rebaseline: no rebuild, re-record the (new) source +
+      // body hash, and the grant-drift pass below (which covers skipped ∪ rebaseline) applies the
+      // bare GRANT/REVOKE delta. Gate is strict — any leg missing falls through to today's rebuild:
+      //   - bodyHash recorded AND equal        → the change is grants-only, not body (armed row only)
+      //   - live grants introspected (≠ undef) → diffObjectGrants can actually run (absent ≠ empty)
+      //   - no column-scoped grants            → attacl isn't drift-applied, so those MUST rebuild
+      const parsed = parseGrantAttachments(src.attachments);
+      const authzOnly =
+        prov.bodyHash != null &&
+        src.bodyHash === prov.bodyHash &&
+        liveObj.grants !== undefined &&
+        !parsed.hasColumnGrants;
       // The live object is verifiably untouched here (liveChanged was handled above), so
       // under rebaseline a source re-render is bookkeeping: re-record the source hash,
       // rebuild nothing, cascade nothing.
-      if (options.rebaseline) rebaseline.push(src.identity);
+      if (options.rebaseline || authzOnly) rebaseline.push(src.identity);
       else if (isRelation(src.kind)) rebuild.set(src.identity, 'source changed');
       else fnReplace.set(src.identity, 'source changed');
       continue;
     }
+    // Up-to-date (src + live both match provenance). If provenance predates body_hash, record it
+    // once — a record-only backfill that ARMS the authz-only fast path for a future grant change.
+    // Converges: after this run the row has body_hash, so it skips cleanly next time.
+    if (prov.bodyHash == null) {
+      backfill.push(src.identity);
+      continue;
+    }
     skipped.push(src.identity);
   }
 
@@ -336,7 +359,7 @@ export function planReconcile(
   // Rebaselined objects join the lens: their live catalog rows are as real as a skip's,
   // and running the checks NOW means a migration converges (grants ride the same apply)
   // instead of surfacing on the next plan.
-  const lensSet = new Set([...skipped, ...rebaseline]);
+  const lensSet = new Set([...skipped, ...rebaseline, ...backfill]);
   for (const src of source.objects) {
     if (!lensSet.has(src.identity)) continue;
     if (src.kind === 'trigger' || src.kind === 'sql') continue; // no grants, no rewrite edges
@@ -485,6 +508,7 @@ export function planReconcile(
       .map(([id, reason]) => actionFor(id, 'refresh', reason)),
     ...baseline.sort().map((id) => actionFor(id, 'baseline', 'recording provenance for an existing match (trusted once, explicitly)')),
     ...rebaseline.sort().map((id) => actionFor(id, 'rebaseline', 'source re-rendered — live verified untouched (defHash match); provenance re-recorded, no rebuild')),
+    ...backfill.sort().map((id) => actionFor(id, 'backfill', 'recording body_hash on an up-to-date object — arms the authz-only fast path, no rebuild')),
     ...prune.sort().map((id) => ({
       action: 'prune' as const, identity: id, kind: 'view' as DerivedKind,
       reason: 'stale provenance — object gone from both source and database',

package/src/cli/derived-source.ts

@@ -48,6 +48,14 @@ export interface SourceObject {
   attachments: Attachment[];
   /** sha256 of the normalized CREATE + attachments — comment/whitespace edits do not change it. */
   hash: string;
+  /**
+   * sha256 of the normalized CREATE + attachments EXCEPT plain (non-column-scoped) grants — the
+   * "would a rebuild be required" hash. Equal across an authz-only change (plain grants moved, body
+   * unchanged), so the reconciler can route that to a bare GRANT delta instead of a matview rebuild.
+   * Column-scoped grants stay IN (attacl not introspected → they must rebuild). `hash` stays the
+   * full/stable formula for provenance compat; this is the additional discriminator.
+   */
+  bodyHash: string;
   /** Source file this object came from (descriptors: the declared-models marker). */
   file: string;
   /** Position in the concatenated source — a valid dependency order by convention. */

package/src/cli/swap-execute.ts

@@ -54,11 +54,181 @@ export interface ExecuteSwapOptions {
   verify?: () => Promise<SwapVerdict>;
   /** Restore the stage to the snapshot from step 2 when verify is fatal. */
   rollbackToSnapshot?: () => Promise<void>;
+  /** Progress/instrumentation sink (per-table landed rows, the count assertion). Defaults to a no-op. */
+  log?: (msg: string) => void;
+  /**
+   * `schema.name` of every object the DECLARED derived layer can regenerate (db:reconcile's source
+   * of truth). A dependent in this set is safe to drop: reconcile rebuilds it from the descriptor.
+   * A dependent NOT in it can never be rebuilt, so it is refused unconditionally.
+   */
+  declaredIdentities?: string[];
+  /**
+   * Informed consent to DROP the dependent derived objects as part of the swap (`--rebuild-derived`).
+   *
+   * This is the intended workflow — swap the schema, then regenerate the derived layer — not a
+   * workaround. The gate exists to stop SILENT destruction, so an operator who says "drop them, I
+   * will reconcile after" has supplied exactly the consent that was missing. Undeclared dependents
+   * are still refused: consent cannot cover an object nothing knows how to rebuild.
+   */
+  rebuildDerived?: boolean;
+}
+
+/** One table's landed-vs-live count, the intrinsic post-swap assertion's unit. */
+export interface RowCount {
+  table: string;
+  incoming: number;
+  live: number;
+}
+
+/**
+ * The intrinsic count assertion: after the rename, the LIVE schema must hold exactly what the
+ * artifact landed in the incoming schema. A no-op swap (the rename silently not taking) leaves the
+ * OLD table under `<schema>.<table>` — its count differs from what was restored, and this catches it.
+ * A table present in incoming but absent live (a partial rename) is a mismatch too. Pure — the impure
+ * path reads the two count maps and hands them here, so the verdict wording is unit-tested.
+ */
+export function diffRowCounts(counts: RowCount[]): SwapCheck[] {
+  const bad: SwapCheck[] = [];
+  for (const c of counts) {
+    if (c.incoming !== c.live) {
+      bad.push({
+        name: `rowcount:${c.table}`,
+        ok: false,
+        detail: `artifact landed ${c.incoming} rows but live ${c.table} has ${c.live} after swap — the swap did not take effect (or landed partial data).`,
+        severity: 'fatal',
+      });
+    }
+  }
+  return bad;
+}
+
+/** One object OUTSIDE the swapped schema that depends on something inside it. */
+export interface CrossSchemaDependent {
+  schema: string;
+  name: string;
+  /** `view`, `materialized view`, `function`, `procedure`. */
+  kind: string;
+  /** Identity arguments for a function/procedure — DROP FUNCTION needs them when overloaded. */
+  args?: string;
+}
+
+/** `schema.name`, the join key against the declared derived layer's identities. */
+export function dependentIdentity(d: CrossSchemaDependent): string {
+  return `${d.schema}.${d.name}`;
+}
+
+/**
+ * The DROP for one dependent. CASCADE is safe here and ordering does not matter: the dependent set
+ * is a transitive CLOSURE, so anything CASCADE could reach is already in the set being dropped.
+ */
+export function dropDependentSql(d: CrossSchemaDependent): string {
+  const ref = `"${d.schema.replace(/"/g, '""')}"."${d.name.replace(/"/g, '""')}"`;
+  if (d.kind === 'materialized view') return `DROP MATERIALIZED VIEW IF EXISTS ${ref} CASCADE;`;
+  if (d.kind === 'view') return `DROP VIEW IF EXISTS ${ref} CASCADE;`;
+  // Functions can be overloaded, so the identity arguments are load-bearing.
+  const kw = d.kind === 'procedure' ? 'PROCEDURE' : 'FUNCTION';
+  return `DROP ${kw} IF EXISTS ${ref}(${d.args ?? ''}) CASCADE;`;
+}
+
+/**
+ * Objects in OTHER schemas that depend on the swapped schema — the CASCADE blast radius.
+ *
+ * Why this gate exists. The swap ends with `DROP SCHEMA <schema>_retiring CASCADE`. PostgreSQL
+ * binds a view, matview or function to its dependencies by OID, so the rename carries every such
+ * binding onto the RETIRING schema — and CASCADE then drops them. Silently. The swap already
+ * understands this for foreign keys (it drops and recreates them around the rename, see
+ * crossSchemaForeignKeys) and was blind to everything else.
+ *
+ * The walk must be TRANSITIVE, and the first version was not. Matching only DIRECT dependents,
+ * given `stats.t` ← `other.v1` ← `other.v2`, it found v1 and missed v2 entirely. v2 binds to v1 by
+ * OID, so when v1 goes so does v2. Worse: when the only direct dependent lives INSIDE the swapped
+ * schema, a direct-only query reports NOTHING while CASCADE still destroys everything downstream.
+ *
+ * So: seed the closure with every relation, type and function in the schema, then walk pg_depend
+ * forward to fixpoint. Views and matviews reach their dependencies through pg_rewrite, so an edge
+ * is normalized to the OWNING relation (`rw.ev_class`), not the rewrite rule. Types are seeded
+ * because `RETURNS SETOF <schema>.<table>` records against the table's composite TYPE rather than
+ * the table — a pg_class-only walk misses every such function.
+ *
+ * Objects INSIDE the schema are excluded (they ride along with the swap), as are the incoming and
+ * retiring schemas (transient, and a leftover `<schema>_incoming` from a failed run must not make
+ * the gate refuse forever). Foreign keys never surface here: they are pg_constraint, and the swap
+ * drops and recreates them itself.
+ *
+ * Verified against a live PostgreSQL 16 fixture: a three-deep view chain, a function returning
+ * SETOF a table, a view inside the schema, and an unrelated view in another schema.
+ */
+export function crossSchemaDependentsQuery(schema: string, incoming: string, retiring: string): string {
+  const q = (s: string) => s.replace(/'/g, "''");
+  const skip = `ARRAY['${q(incoming)}','${q(retiring)}']`;
+  const notSelf = `n.nspname <> '${q(schema)}' AND n.nspname <> ALL (${skip})`;
+  return `WITH RECURSIVE seed AS (
+  SELECT c.oid AS oid, 'pg_class'::regclass AS cls
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = '${q(schema)}'
+  UNION
+  SELECT t.oid, 'pg_type'::regclass
+    FROM pg_type t JOIN pg_namespace n ON n.oid = t.typnamespace WHERE n.nspname = '${q(schema)}'
+  UNION
+  SELECT p.oid, 'pg_proc'::regclass
+    FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace WHERE n.nspname = '${q(schema)}'
+), closure AS (
+  SELECT oid, cls FROM seed
+  UNION
+  SELECT CASE WHEN d.classid = 'pg_rewrite'::regclass THEN rw.ev_class ELSE d.objid END,
+         CASE WHEN d.classid = 'pg_rewrite'::regclass THEN 'pg_class'::regclass ELSE d.classid END
+    FROM closure cl
+    JOIN pg_depend d ON d.refclassid = cl.cls AND d.refobjid = cl.oid
+    LEFT JOIN pg_rewrite rw ON rw.oid = d.objid AND d.classid = 'pg_rewrite'::regclass
+   WHERE d.classid IN ('pg_rewrite'::regclass, 'pg_class'::regclass, 'pg_proc'::regclass, 'pg_type'::regclass)
+)
+SELECT DISTINCT n.nspname AS dep_schema, c.relname AS dep_name,
+       CASE c.relkind WHEN 'v' THEN 'view' WHEN 'm' THEN 'materialized view' ELSE c.relkind::text END AS dep_kind,
+       ''::text AS dep_args
+  FROM closure cl
+  JOIN pg_class c     ON c.oid = cl.oid AND cl.cls = 'pg_class'::regclass
+  JOIN pg_namespace n ON n.oid = c.relnamespace
+ WHERE c.relkind IN ('v', 'm') AND ${notSelf}
+UNION
+SELECT DISTINCT n.nspname, p.proname,
+       CASE p.prokind WHEN 'p' THEN 'procedure' ELSE 'function' END,
+       pg_get_function_identity_arguments(p.oid)
+  FROM closure cl
+  JOIN pg_proc p      ON p.oid = cl.oid AND cl.cls = 'pg_proc'::regclass
+  JOIN pg_namespace n ON n.oid = p.pronamespace
+ WHERE ${notSelf}
+ ORDER BY 1, 2`;
+}
+
+/** The refusal message — names what is at risk, and which of the two refusals this is. */
+export function crossSchemaDependentsRefusal(
+  schema: string,
+  deps: CrossSchemaDependent[],
+  opts: { rebuildRequested?: boolean; undeclared?: CrossSchemaDependent[] } = {},
+): string {
+  const name = (d: CrossSchemaDependent) => `${d.schema}.${d.name} (${d.kind})`;
+  const undeclared = opts.undeclared ?? [];
+
+  // Refusal 1: consent was given, but something in the set cannot be regenerated.
+  if (opts.rebuildRequested && undeclared.length > 0) {
+    return `${undeclared.length} of the ${deps.length} object(s) depending on ${schema} are NOT declared, so nothing can regenerate them: `
+      + `${undeclared.slice(0, 20).map(name).join(', ')}${undeclared.length > 20 ? `, and ${undeclared.length - 20} more` : ''}. `
+      + `--rebuild-derived drops dependents on the promise that db:reconcile --apply rebuilds them, and that promise does not hold for an undeclared object — dropping it would destroy it. `
+      + `Nothing was changed. Declare them in db/models (then db:reconcile --apply), or drop them yourself if they are genuinely disposable.`;
+  }
+
+  // Refusal 2: no consent given. Explain the danger and the flag.
+  const listed = deps.slice(0, 20).map(name).join(', ');
+  const more = deps.length > 20 ? `, and ${deps.length - 20} more` : '';
+  return `${deps.length} object(s) outside ${schema} depend on it, and the swap would DESTROY them: ${listed}${more}. `
+    + `PostgreSQL binds views, matviews and functions to their dependencies by OID, so renaming ${schema} carries those bindings onto ${schema}_retiring, and the swap's final DROP SCHEMA ... CASCADE drops them silently. `
+    + `Nothing was changed — this refusal happens before the snapshot. `
+    + `If regenerating them is what you want, re-run with --rebuild-derived: the swap drops them in the same transaction and db:reconcile --apply rebuilds them from the declared descriptors.`;
 }
 
 export type SwapStatus =
   | 'swapped'
   | 'refused-fingerprint'
+  | 'refused-dependents'
   | 'refused-integrity'
   | 'rolled-back-verify';
 
@@ -69,6 +239,10 @@ export interface SwapResult {
   verdict?: SwapVerdict;
   /** Warn-severity checks that did NOT trigger rollback (surfaced). */
   warnings?: SwapCheck[];
+  /** On `refused-dependents`: exactly what CASCADE would have destroyed. */
+  dependents?: CrossSchemaDependent[];
+  /** The subset nothing can regenerate — the reason --rebuild-derived was not enough. */
+  undeclaredDependents?: CrossSchemaDependent[];
 }
 
 /** Does the verdict force a rollback? Any failing check whose severity is fatal (the default). */
@@ -79,7 +253,27 @@ export function isFatalVerdict(verdict: SwapVerdict): boolean {
   return checks.some((c) => !c.ok && (c.severity ?? 'fatal') === 'fatal');
 }
 
+/** Double-quote a Postgres identifier read from the catalog (embedded quotes doubled). */
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+/** The base tables physically present in `schema` (what a restore actually landed / what live serves). */
+async function baseTablesIn(runner: QueryRunner, schema: string): Promise<string[]> {
+  const rows = await runner(
+    `SELECT table_name FROM information_schema.tables WHERE table_schema = '${schema.replace(/'/g, "''")}' AND table_type = 'BASE TABLE' ORDER BY table_name`,
+  );
+  return rows.map((r: any) => r.table_name as string);
+}
+
+/** `count(*)` for one table, as a number. */
+async function countRows(runner: QueryRunner, schema: string, table: string): Promise<number> {
+  const rows = await runner(`SELECT count(*)::bigint AS n FROM ${quoteIdent(schema)}.${quoteIdent(table)}`);
+  return Number(rows[0]?.n ?? 0);
+}
+
 export async function executeSwap(runner: QueryRunner, opts: ExecuteSwapOptions): Promise<SwapResult> {
+  const log = opts.log ?? (() => {});
   // 1. Fingerprint gate — declared-vs-declared: does the artifact and the target agree on the shape.
   if (opts.artifactFingerprint !== opts.declaredFingerprint) {
     return {
@@ -90,12 +284,63 @@ export async function executeSwap(runner: QueryRunner, opts: ExecuteSwapOptions)
 
   const plan = renderSchemaSwap(opts.models, { schema: opts.schema, incoming: opts.incoming, retiring: opts.retiring });
 
+  // 1b. THE CASCADE GATE. Refuse before the snapshot — before anything moves at all — if any object
+  //     outside this schema depends on it. The swap's final DROP SCHEMA ... CASCADE would destroy
+  //     them silently, and a silent destroyer is the worst thing this command could be.
+  const depRows = await runner(crossSchemaDependentsQuery(opts.schema, plan.incoming, plan.retiring));
+  const dependents: CrossSchemaDependent[] = depRows.map((r: any) => ({
+    schema: r.dep_schema, name: r.dep_name, kind: r.dep_kind, args: r.dep_args || undefined,
+  }));
+  if (dependents.length > 0) {
+    const declared = new Set(opts.declaredIdentities ?? []);
+    const undeclared = dependents.filter((d) => !declared.has(dependentIdentity(d)));
+
+    // Consent covers only what can be rebuilt. An undeclared dependent is refused even WITH
+    // --rebuild-derived: dropping it destroys it, because nothing knows how to recreate it.
+    if (!opts.rebuildDerived || undeclared.length > 0) {
+      return {
+        status: 'refused-dependents',
+        reason: crossSchemaDependentsRefusal(opts.schema, dependents, {
+          rebuildRequested: !!opts.rebuildDerived,
+          undeclared,
+        }),
+        dependents,
+        undeclaredDependents: undeclared.length ? undeclared : undefined,
+      };
+    }
+
+    // Consented, and every one is declared: drop them inside the swap transaction, before the
+    // rename. db:reconcile --apply regenerates them from the descriptors afterwards.
+    // Future tense on purpose: these DROPs ride the swap transaction, which is several steps away
+    // and may never run. Announcing them as done was misleading on a restore that failed first.
+    log(`${dependents.length} declared derived object(s) depend on ${opts.schema} and WILL BE DROPPED by the swap transaction (regenerate with db:reconcile --apply). Nothing is dropped unless the swap itself commits.`);
+    plan.statements.unshift(...dependents.map(dropDependentSql));
+  }
+
   // 2. Snapshot (the rollback point) before anything destructive.
   if (opts.snapshot) await opts.snapshot();
 
-  // 3. Land the incoming schema while live keeps serving.
+  // 3. Land the incoming schema while live keeps serving. Drop a stale incoming FIRST so a retry
+  //    after a failed restore is idempotent (a half-landed <schema>_incoming from a prior crash
+  //    would otherwise collide on the artifact's CREATE SCHEMA and fail every retry).
+  await runner(`DROP SCHEMA IF EXISTS ${quoteIdent(plan.incoming)} CASCADE`);
   await opts.applyIncoming(runner);
 
+  // Capture what the artifact actually landed, per table — the count the live schema must match
+  // after the swap. Empty here means the restore created the schema but no tables: a silent
+  // partial that must fail, not pass.
+  const incomingTables = await baseTablesIn(runner, plan.incoming);
+  const expected = new Map<string, number>();
+  for (const t of incomingTables) expected.set(t, await countRows(runner, plan.incoming, t));
+  log(`landed ${incomingTables.length} table(s) into ${plan.incoming}: ${incomingTables.map((t) => `${t}=${expected.get(t)}`).join(', ') || '(none)'}`);
+  if (incomingTables.length === 0) {
+    try { await runner(`DROP SCHEMA IF EXISTS ${quoteIdent(plan.incoming)} CASCADE`); } catch { /* best effort */ }
+    return {
+      status: 'refused-integrity',
+      reason: `the restore landed NO base tables into ${plan.incoming} — the artifact did not apply (a restore that reported success but wrote nothing). The swap was NOT applied; live is untouched.`,
+    };
+  }
+
   // 4. The atomic swap. A FK re-validation failure (a bad artifact) rolls the whole thing back.
   await runner('BEGIN');
   try {
@@ -111,7 +356,23 @@ export async function executeSwap(runner: QueryRunner, opts: ExecuteSwapOptions)
     };
   }
 
-  // 5. Verify (post-commit). Fatal → roll back to the snapshot; warn → surface only.
+  // 5a. The intrinsic count assertion (ALWAYS runs — this is the safety net a silent no-op needs).
+  //     After the rename, live must hold exactly what landed. A mismatch means the swap did not
+  //     take effect; roll back to the snapshot and refuse LOUD.
+  const counts: RowCount[] = [];
+  for (const t of incomingTables) counts.push({ table: t, incoming: expected.get(t)!, live: await countRows(runner, opts.schema, t) });
+  log(`post-swap live counts: ${counts.map((c) => `${c.table}=${c.live}`).join(', ')}`);
+  const countChecks = diffRowCounts(counts);
+  if (countChecks.length > 0) {
+    if (opts.rollbackToSnapshot) await opts.rollbackToSnapshot();
+    return {
+      status: 'rolled-back-verify',
+      reason: `post-swap row counts do not match the artifact — the swap did not land: ${countChecks.map((c) => c.detail).join(' ')} ${opts.rollbackToSnapshot ? 'Rolled back to the pre-swap snapshot.' : 'NO snapshot was configured to roll back to.'}`,
+      verdict: { ok: false, checks: countChecks },
+    };
+  }
+
+  // 5b. Verify (post-commit). Fatal → roll back to the snapshot; warn → surface only.
   let verdict: SwapVerdict | undefined;
   if (opts.verify) {
     verdict = await opts.verify();