@everystack/cli 0.4.34 → 0.4.36

package/src/cli/swap-execute.ts

@@ -54,11 +54,260 @@ 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;
+  /**
+   * The PAIRED swap: derived schemas that swap alongside the base schema, with their incoming
+   * twins already built over `<schema>_incoming` (see swap-pair). This is the zero-downtime path
+   * — the derived layer is recreated in parallel and renamed in the same transaction, so it is
+   * never absent and never welded to the retiring schema.
+   *
+   * Supplying this makes the CASCADE gate treat the whole set as one unit: an object depending on
+   * a paired schema is INSIDE the swap and rides along, exactly as an object inside the base
+   * schema always has.
+   */
+  paired?: string[];
+  /**
+   * Build the incoming derived layer. Runs after the artifact lands in `<schema>_incoming` and
+   * before the swap transaction, while every live schema keeps serving. Paired swaps only.
+   */
+  buildPairedDerived?: (runner: QueryRunner) => Promise<void>;
+  /**
+   * Schema-level USAGE applied inside the swap transaction (renderSwapSchemaUsage), and the
+   * (schema, role) pairs asserted after it commits. Without these a swap can land correct data
+   * behind schemas no application role can enter — see diffSchemaUsage.
+   */
+  schemaUsage?: string[];
+  schemaUsageRoles?: Array<{ schema: string; role: string }>;
+  /**
+   * The `_incoming`-qualified identities the paired build must produce (expectedIncomingObjects).
+   * Asserted before the rename: a partial derived layer refuses while live is untouched, instead
+   * of committing a swap that reports success with objects missing.
+   */
+  expectedDerived?: string[];
+  /**
+   * Record provenance for the objects the paired build created, once they are live at their final
+   * identities. Without it the next db:reconcile sees the whole layer as drift and rebuilds it —
+   * an expensive, ACCESS EXCLUSIVE no-op that surfaces days later on an unrelated run.
+   */
+  recordProvenance?: (runner: QueryRunner) => Promise<void>;
+}
+
+/** 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,
+  opts: { paired?: string[]; incomingSuffix?: string; retiringSuffix?: string } = {},
+): string {
+  const q = (s: string) => s.replace(/'/g, "''");
+  const arr = (xs: string[]) => `ARRAY[${xs.map((s) => `'${q(s)}'`).join(',')}]`;
+  const paired = opts.paired ?? [];
+  const inSuffix = opts.incomingSuffix ?? '_incoming';
+  const reSuffix = opts.retiringSuffix ?? '_retiring';
+
+  // A PAIRED derived schema is INSIDE the swap: its objects are rebuilt into the incoming twin
+  // and renamed in the same transaction, so they are not at risk and must not trigger a refusal.
+  // They also seed the walk — something outside the set depending on a PAIRED schema is destroyed
+  // by that schema's rename + drop just as surely as a dependent of the base schema is.
+  const swapped = [schema, ...paired];
+  const twins = paired.flatMap((p) => [`${p}${inSuffix}`, `${p}${reSuffix}`]);
+  const skip = arr([incoming, retiring, ...twins]);
+  const notSelf = `n.nspname <> ALL (${arr(swapped)}) AND n.nspname <> ALL (${skip})`;
+  const seedIn = `= ANY (${arr(swapped)})`;
+  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 ${seedIn}
+  UNION
+  SELECT t.oid, 'pg_type'::regclass
+    FROM pg_type t JOIN pg_namespace n ON n.oid = t.typnamespace WHERE n.nspname ${seedIn}
+  UNION
+  SELECT p.oid, 'pg_proc'::regclass
+    FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace WHERE n.nspname ${seedIn}
+), 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`;
+}
+
+/**
+ * Every view / matview / function physically living in `schemas` — what a paired swap is about to
+ * replace wholesale.
+ *
+ * The paired swap renames a derived schema out and its rebuilt twin in, then drops the retiring
+ * one. The twin is built from the DECLARED descriptors, so anything live-but-undeclared in that
+ * schema has no counterpart in the twin and the drop destroys it. Pairing widens the set of
+ * schemas the gate considers "inside" the swap; this is what keeps that from becoming a licence to
+ * delete. Same reasoning as the undeclared-dependent refusal, applied one schema over.
+ */
+export function schemaObjectsQuery(schemas: string[]): string {
+  const q = (s: string) => s.replace(/'/g, "''");
+  const list = `ARRAY[${schemas.map((s) => `'${q(s)}'`).join(',')}]`;
+  return `SELECT 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 pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+ WHERE n.nspname = ANY (${list}) AND c.relkind IN ('v','m')
+UNION
+SELECT n.nspname, p.proname,
+       CASE p.prokind WHEN 'p' THEN 'procedure' ELSE 'function' END,
+       pg_get_function_identity_arguments(p.oid)
+  FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+ WHERE n.nspname = ANY (${list})
+ 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 +318,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 +332,93 @@ export function isFatalVerdict(verdict: SwapVerdict): boolean {
   return checks.some((c) => !c.ok && (c.severity ?? 'fatal') === 'fatal');
 }
 
+/**
+ * The reachability assertion: every role that holds a declared grant in a swapped schema must
+ * still have USAGE on it after the swap.
+ *
+ * The row-count assertion proves the DATA landed. This proves the data can be REACHED, which is a
+ * different failure and a quieter one: a swap that lands perfect data behind a schema no
+ * application role can enter reports success while every endpoint 500s. PostgreSQL surfaces a
+ * missing schema USAGE as ABSENCE rather than denial, so the error the operator sees is
+ * `relation "..." does not exist` — pointing at the table, not the grant.
+ *
+ * Pure: the impure half reads has_schema_privilege and hands the rows here.
+ */
+export function diffSchemaUsage(rows: Array<{ schema: string; role: string; ok: boolean }>): SwapCheck[] {
+  return rows
+    .filter((r) => !r.ok)
+    .map((r) => ({
+      name: `usage:${r.schema}:${r.role}`,
+      ok: false,
+      severity: 'fatal' as const,
+      detail: `role ${r.role} has no USAGE on schema ${r.schema} after the swap — it holds declared grants there, so every one of them is unreachable (PostgreSQL will report the tables as "does not exist").`,
+    }));
+}
+
+/** `has_schema_privilege` for each (role, schema) pair — catalog-only, locks nothing. */
+export function schemaUsageQuery(pairs: Array<{ schema: string; role: string }>): string {
+  const q = (s: string) => s.replace(/'/g, "''");
+  const values = pairs.map((p) => `('${q(p.schema)}','${q(p.role)}')`).join(',');
+  return `SELECT s AS schema, r AS role,
+       (EXISTS (SELECT 1 FROM pg_roles WHERE rolname = r)
+        AND has_schema_privilege(r, s, 'USAGE')) AS ok
+  FROM (VALUES ${values}) AS t(s, r)`;
+}
+
+/**
+ * The derived-layer completeness assertion: every declared object in the swap set must actually
+ * EXIST in the incoming schemas after the build.
+ *
+ * The row-count assertion proves the base tables landed. This proves the derived layer did. They
+ * are different failures, and this one was silent: a build that throws is caught, but a build that
+ * quietly produces 38 of 79 objects sailed straight through to a successful swap. Seen in the
+ * field — a consumer's run printed the success line with half the layer missing.
+ *
+ * The same silent-success class as the original `--direct` swap reporting success without landing
+ * anything. That got a per-table count; the derived layer never got the equivalent until now.
+ *
+ * Pure: the caller reads the incoming catalog and hands both sides here.
+ */
+export function diffDerivedObjects(expected: string[], present: string[]): SwapCheck[] {
+  const have = new Set(present);
+  const missing = expected.filter((id) => !have.has(id)).sort();
+  if (missing.length === 0) return [];
+  const shown = missing.slice(0, 20).join(', ');
+  return [{
+    name: 'derived:incomplete',
+    ok: false,
+    severity: 'fatal',
+    detail: `the incoming derived layer is INCOMPLETE — ${missing.length} of ${expected.length} declared object(s) were not built: `
+      + `${shown}${missing.length > 20 ? `, and ${missing.length - 20} more` : ''}.`,
+  }];
+}
+
+/** Every view / matview / function physically present in the given schemas, as `schema.name`. */
+export function objectsPresentQuery(schemas: string[]): string {
+  return schemaObjectsQuery(schemas);
+}
+
+/** 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 {
@@ -88,14 +427,141 @@ export async function executeSwap(runner: QueryRunner, opts: ExecuteSwapOptions)
     };
   }
 
-  const plan = renderSchemaSwap(opts.models, { schema: opts.schema, incoming: opts.incoming, retiring: opts.retiring });
+  const paired = opts.paired ?? [];
+  const plan = renderSchemaSwap(opts.models, {
+    schema: opts.schema,
+    incoming: opts.incoming,
+    retiring: opts.retiring,
+    paired,
+    schemaUsage: opts.schemaUsage,
+  });
+
+  // 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.
+  // 1a. PAIRED PRE-FLIGHT. A paired schema is replaced wholesale by a twin built from the declared
+  //     descriptors, so anything live in it that is NOT declared has no counterpart in the twin
+  //     and the retiring drop would destroy it. Pairing must never become a quieter way to lose an
+  //     object than the unpaired gate already refuses to be.
+  if (paired.length > 0) {
+    const declared = new Set(opts.declaredIdentities ?? []);
+    const liveRows = await runner(schemaObjectsQuery(paired));
+    const orphans: CrossSchemaDependent[] = liveRows
+      .map((r: any) => ({ schema: r.dep_schema, name: r.dep_name, kind: r.dep_kind, args: r.dep_args || undefined }))
+      .filter((d: CrossSchemaDependent) => !declared.has(dependentIdentity(d)));
+    if (orphans.length > 0) {
+      const name = (d: CrossSchemaDependent) => `${d.schema}.${d.name} (${d.kind})`;
+      return {
+        status: 'refused-dependents',
+        reason: `${orphans.length} object(s) live in the paired schema(s) ${paired.join(', ')} but are NOT declared, so the rebuilt schema would not contain them and the swap would DESTROY them: `
+          + `${orphans.slice(0, 20).map(name).join(', ')}${orphans.length > 20 ? `, and ${orphans.length - 20} more` : ''}. `
+          + `A paired swap replaces the whole derived schema with one built from db/models — anything not declared there has nothing to rebuild it. `
+          + `Nothing was changed. Declare them in db/models, or drop them yourself if they are genuinely disposable.`,
+        dependents: orphans,
+        undeclaredDependents: orphans,
+      };
+    }
+  }
+
+  const depRows = await runner(crossSchemaDependentsQuery(opts.schema, plan.incoming, plan.retiring, { paired }));
+  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.`,
+    };
+  }
+
+  // 3b. PAIRED: build the derived layer over the incoming base tables, while every live schema
+  //     keeps serving. This is the whole point — the layer exists in full before the rename, so
+  //     there is no window in which it is absent and no refresh that could read stale rows.
+  //     A failure here leaves live untouched: nothing has been renamed yet.
+  if (opts.buildPairedDerived) {
+    const twins = paired.map((p) => `${p}_incoming`);
+    for (const t of twins) await runner(`DROP SCHEMA IF EXISTS ${quoteIdent(t)} CASCADE`);
+    try {
+      await opts.buildPairedDerived(runner);
+    } catch (err: any) {
+      for (const t of twins) {
+        try { await runner(`DROP SCHEMA IF EXISTS ${quoteIdent(t)} CASCADE`); } catch { /* best effort */ }
+      }
+      try { await runner(`DROP SCHEMA IF EXISTS ${quoteIdent(plan.incoming)} CASCADE`); } catch { /* best effort */ }
+      return {
+        status: 'refused-integrity',
+        reason: `building the incoming derived layer failed, so the swap was NOT applied and live is untouched: ${String(err?.message ?? err)}. `
+          + `The declared descriptors must compose against the INCOMING base schema — if the artifact's shape no longer matches what the derived layer selects, that mismatch surfaces here rather than after the rename.`,
+      };
+    }
+    // COMPLETENESS. A build that throws is caught above; a build that quietly produces only some
+    // of its objects is not, and used to reach a successful swap. Assert BEFORE the rename, while
+    // live is still untouched — a refusal here costs nothing, where the same finding after the
+    // rename would cost a snapshot restore.
+    if (opts.expectedDerived?.length) {
+      const rows = await runner(objectsPresentQuery(twins.length ? [plan.incoming, ...twins] : [plan.incoming]));
+      const present = rows.map((r: any) => `${r.dep_schema}.${r.dep_name}`);
+      const checks = diffDerivedObjects(opts.expectedDerived, present);
+      if (checks.length > 0) {
+        for (const t of twins) {
+          try { await runner(`DROP SCHEMA IF EXISTS ${quoteIdent(t)} CASCADE`); } catch { /* best effort */ }
+        }
+        try { await runner(`DROP SCHEMA IF EXISTS ${quoteIdent(plan.incoming)} CASCADE`); } catch { /* best effort */ }
+        return {
+          status: 'refused-integrity',
+          reason: `${checks[0].detail} The swap was NOT applied and live is untouched. `
+            + `A partial derived layer is what a swap that reports success while half the layer is missing looks like from the inside — this refuses instead.`,
+          verdict: { ok: false, checks },
+        };
+      }
+      log(`derived layer complete: ${opts.expectedDerived.length} declared object(s) present in the incoming schemas`);
+    }
+    log(`built the incoming derived layer into ${twins.join(', ')} — live still serving the old one`);
+  }
+
   // 4. The atomic swap. A FK re-validation failure (a bad artifact) rolls the whole thing back.
   await runner('BEGIN');
   try {
@@ -111,7 +577,43 @@ 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 },
+    };
+  }
+
+  // 5a-bis. The REACHABILITY assertion. Counts prove the data landed; this proves an application
+  //     role can still get to it. A swap that commits perfect data behind a schema nobody can
+  //     enter looks like a success and reads, at the app, as every table having vanished.
+  if (opts.schemaUsageRoles?.length) {
+    const usageRows = await runner(schemaUsageQuery(opts.schemaUsageRoles));
+    const usageChecks = diffSchemaUsage(
+      usageRows.map((r: any) => ({ schema: r.schema, role: r.role, ok: r.ok === true })),
+    );
+    if (usageChecks.length > 0) {
+      if (opts.rollbackToSnapshot) await opts.rollbackToSnapshot();
+      return {
+        status: 'rolled-back-verify',
+        reason: `the swap landed but the schemas are unreachable: ${usageChecks.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: usageChecks },
+      };
+    }
+    log(`reachability: ${opts.schemaUsageRoles.length} (role, schema) pair(s) verified — the app can still read through the swapped schemas`);
+  }
+
+  // 5b. Verify (post-commit). Fatal → roll back to the snapshot; warn → surface only.
   let verdict: SwapVerdict | undefined;
   if (opts.verify) {
     verdict = await opts.verify();
@@ -125,8 +627,25 @@ export async function executeSwap(runner: QueryRunner, opts: ExecuteSwapOptions)
     }
   }
 
-  // 6. Drop the retiring schema — the swap is committed and verified.
-  await runner(dropRetiringSql(plan.retiring));
+  // 6. Drop EVERY retiring schema — the swap is committed and verified. On a paired swap that is
+  //    the base plus each derived twin; dropping only the base would strand the old derived
+  //    schemas, which the next swap then collides with on its own rename.
+  for (const r of plan.retiringSchemas) await runner(dropRetiringSql(r));
+
+  // 7. Bookkeeping. The build created the derived layer with raw DDL; the reconciler knows nothing
+  //    about it until this runs. Recorded AFTER the retiring drop so the catalog read behind it
+  //    sees only the live objects. A failure here does not undo a good swap — the data is correct
+  //    and serving; the cost is a redundant rebuild on the next reconcile, which is what this
+  //    prevents rather than something it can break.
+  if (opts.recordProvenance) {
+    try {
+      await opts.recordProvenance(runner);
+    } catch (err: any) {
+      log(`WARNING: the swap succeeded but recording provenance failed: ${String(err?.message ?? err)}. `
+        + `The derived layer is live and correct; the next db:reconcile will rebuild it needlessly. `
+        + `Run db:reconcile --rebaseline to record it without DDL.`);
+    }
+  }
 
   const warnings = (verdict?.checks ?? []).filter((c) => !c.ok && c.severity === 'warn');
   return { status: 'swapped', verdict, ...(warnings.length ? { warnings } : {}) };