@everystack/cli 0.4.81 → 0.4.83

package/src/cli/commands/db-apply.ts

@@ -31,8 +31,8 @@
 
 import fs from 'node:fs/promises';
 import { type QueryRunner } from '../authz-contract';
-import { currentGitRef, worktreeDirty } from '../state-apply';
-import { planHash, PLAN_VERSION, APPLY_CONTRACT_VERSION, type EdgePlan } from '../edge-plan';
+import { currentGitRef, worktreeDirty, classifyGeneratedStatements, classifyDestructive } from '../state-apply';
+import { planHash, PLAN_VERSION, APPLY_CONTRACT_VERSION, declaredGranteesOf, type EdgePlan } from '../edge-plan';
 import {
   proveDescent,
   decideDescentApply,
@@ -72,7 +72,10 @@ import { estimateOpsRuntimeFit } from '../ops-fit';
 import { resolveOperatorUrlViaStage } from '../direct-venue';
 import { withMutationLease, MutationLeaseError } from '../mutation-lease';
 import { readStageStateTwice } from '../stage-read-consistency';
-import { step, success, fail, info, warn } from '../output';
+import { renderApplyReceipt, renderCatchUpFailure } from '../plain-output';
+import { catchUpDerived, type CatchUpVenue } from '../derived-catchup';
+import { buildReconcileReport } from './db-reconcile';
+import { step, success, fail, info, warn, line as printLine } from '../output';
 
 // The apply core lives in apply-execute.ts (shared with the ops Lambda's
 // db:apply action). Re-exported so the existing integration suites — and any
@@ -94,14 +97,58 @@ export type { ApplyPlanOptions, ApplyPlanResult } from '../apply-execute';
  * nothing and exited 0). formatApplyRefusal owns the string; this owns the
  * process.exit(1).
  */
-export function reportApplyResult(result: ApplyPlanResult, plan: EdgePlan): void {
+export function reportApplyResult(
+  result: ApplyPlanResult,
+  plan: EdgePlan,
+  opts: {
+    verbose?: boolean;
+    catchUp?: readonly string[];
+    /**
+     * The grantees the checkout's models declare — what makes a revoke against an
+     * UNdeclared role recognisable as a strip. Absent means the models could not be read,
+     * and a strip then reads as an ordinary `- revoke …` line: under-marking a receipt is
+     * the lesser evil against guessing, and the gate that actually decides already ran.
+     */
+    declaredGrantees?: ReadonlySet<string>;
+  } = {},
+): void {
+  // What the function/view catch-up ran on the same target. It joins the receipt's own change
+  // list — one command, one list, one count — so a caught-up view is never a second report the
+  // reader has to reconcile with the first.
+  const catchUp = opts.catchUp ?? [];
   switch (result.status) {
     case 'already-applied':
-      success(`Already at ${plan.toFingerprint.slice(0, 12)} — nothing to do (idempotent re-apply).`);
+      if (opts.verbose) success(`Already at ${plan.toFingerprint.slice(0, 12)} — nothing to do (idempotent re-apply).`);
+      else {
+        const lines = renderApplyReceipt({ executable: [], destructive: [], alreadyApplied: true, catchUp });
+        for (const text of lines.slice(0, -1)) printLine(text);
+        success(lines[lines.length - 1]);
+      }
       return;
-    case 'applied':
-      success(`Applied and verified — the target is at ${result.liveFingerprint.slice(0, 12)}, exactly as the plan predicted. Recorded in everystack.schema_log (plan_ref ${planHash(plan).slice(0, 12)}).`);
+    case 'applied': {
+      if (opts.verbose) {
+        success(`Applied and verified — the target is at ${result.liveFingerprint.slice(0, 12)}, exactly as the plan predicted. Recorded in everystack.schema_log (plan_ref ${planHash(plan).slice(0, 12)}).`);
+        return;
+      }
+      // The receipt: the plan's own change list back, one line each, as what just happened.
+      //
+      // The ⚠ subset is the SAME three kinds db:plan marked and the --confirm gate counted —
+      // drops, narrowing type changes, and STRIPS. A strip is a revoke against a grantee no
+      // model declares, so recognising one needs the declared side; the caller reads it off
+      // the models it already loads in this same command. Without it the classifier is asked
+      // the same question with less to answer from, and a strip prints as a plain
+      // `- revoke <role>: …`. The one direction this must never disagree in is the other one:
+      // a statement that carried the full destructive ceremony on the way in must not read as
+      // ordinary churn on the way out.
+      const executable = classifyGeneratedStatements(plan.statements ?? []).executable;
+      const { drops, narrowings, strips } = classifyDestructive(executable, {
+        ...(opts.declaredGrantees ? { declaredGrantees: opts.declaredGrantees } : {}),
+      });
+      const lines = renderApplyReceipt({ executable, destructive: [...drops, ...narrowings, ...strips], catchUp });
+      for (const text of lines.slice(0, -1)) printLine(text);
+      success(lines[lines.length - 1]);
       return;
+    }
     default:
       // Every remaining status is a refusal or a verify fault. TS narrows result.status here to
       // exactly ApplyRefusalStatus, so a future status that is neither success nor a known refusal
@@ -112,6 +159,145 @@ export function reportApplyResult(result: ApplyPlanResult, plan: EdgePlan): void
   }
 }
 
+// ---------------------------------------------------------------------------
+// The catch-up: the second half of the job, which db:apply no longer leaves to a human.
+// ---------------------------------------------------------------------------
+
+/**
+ * The command that retries ONLY the functions and views.
+ *
+ * It is db:apply with no plan, which is precisely the catch-up lane — so rerunning it cannot
+ * re-run the table/column changes that already committed. Same venue, same models, nothing
+ * else. A bare --database-url is given as a placeholder: the real one is a credential, and a
+ * credential does not belong in an error message.
+ */
+export function catchUpRerunCommand(flags: Record<string, string>): string {
+  const parts = ['db:apply'];
+  if (flags.stage) {
+    parts.push(`--stage ${flags.stage}`);
+    if (flags.direct === 'true') parts.push('--direct');
+  } else {
+    parts.push('--database-url <url>');
+  }
+  if (flags.models) parts.push(`--models ${flags.models}`);
+  return parts.join(' ');
+}
+
+/** What the catch-up did, or what to say about the fact that it did not. */
+type CatchUpReport = { ok: true; statements: string[] } | { ok: false; lines: string[] };
+
+/**
+ * Run the catch-up and translate its outcome into output — without exiting.
+ *
+ * The exit is the caller's, deliberately: the connection has to be closed first, and a failure
+ * here must NEVER be re-wrapped as "Apply failed and rolled back". The plan DID land; saying
+ * otherwise sends the operator hunting for a rollback that never happened.
+ *
+ * `applied` is how many table/column changes are already committed — the number the one-line
+ * failure report names as safe.
+ *
+ * `onRefusal` is passed STRAIGHT THROUGH to the catch-up, because it is a property of the
+ * caller, not of the catch-up: it says whether anything has been written yet. The two callers
+ * below answer it differently and must — see `catchUpAfterApply` and `catchUpOnly`.
+ */
+async function runCatchUp(
+  venue: CatchUpVenue,
+  flags: Record<string, string>,
+  applied: number,
+  onRefusal: 'exit' | 'throw',
+): Promise<CatchUpReport> {
+  const verbose = flags.verbose === 'true';
+  try {
+    const outcome = await catchUpDerived(venue, {
+      ...(flags.models ? { models: flags.models } : {}),
+      onStart: () => step('Catching the functions, views and triggers up to the checkout...'),
+      onRefusal,
+    });
+    if (verbose && outcome.run) for (const text of buildReconcileReport(outcome.run.plan)) info(text);
+    return { ok: true, statements: outcome.statements };
+  } catch (err: any) {
+    const cause = String(err?.message ?? err);
+    return {
+      ok: false,
+      // The cause is printed ONCE, at every verbosity: its headline on the report line, and
+      // the rest verbatim underneath. --verbose used to print it a second time, unfolded,
+      // above the report — the same text twice, in two different shapes.
+      lines: renderCatchUpFailure({ applied, rerun: catchUpRerunCommand(flags), reason: cause }),
+    };
+  }
+}
+
+/**
+ * The chain: a plan that LANDED is followed by the catch-up, on the same target, always —
+ * unless --state-only asked for the tables alone. A refusal or a verify fault chains nothing
+ * (there is no applied state to build on); reportApplyResult renders those and exits.
+ *
+ * THE POST-WRITE CALLER, and the only reason `'throw'` exists: the table and column changes are
+ * committed by the time this runs. Nothing downstream may end the process on its own, because
+ * the operator is owed one sentence first — your changes are safe, here is what to rerun. So a
+ * wire-contract refusal comes back as an exception and is rendered by `runCatchUp` like any
+ * other way the catch-up can fail.
+ */
+async function catchUpAfterApply(
+  result: ApplyPlanResult,
+  plan: EdgePlan,
+  venue: CatchUpVenue,
+  flags: Record<string, string>,
+): Promise<CatchUpReport> {
+  if (result.status !== 'applied' && result.status !== 'already-applied') return { ok: true, statements: [] };
+  if (flags['state-only'] === 'true') return { ok: true, statements: [] };
+  const applied = result.status === 'applied'
+    ? classifyGeneratedStatements(plan.statements ?? []).executable.length
+    : 0;
+  return runCatchUp(venue, flags, applied, 'throw');
+}
+
+/**
+ * The grantees the ⚠ lines are marked against — the receipt's half of the strip classification.
+ *
+ * The plan carries its own set, and that is the one that counts: db:apply can run long after
+ * db:plan minted it, across a rebase or a hotfix to the models, and the receipt must describe the
+ * plan that was verified rather than the tree the operator happens to be standing in. So the
+ * precedence is the plan first, and when the plan has it nothing is read from disk at all.
+ *
+ * The checkout is the FALLBACK, for a plan minted before the plan carried the set. It reads the
+ * same barrel `db:plan` reads, through the same helper, so the ⚠ lines printed after an apply
+ * cannot drift from the ⚠ lines printed before it. Best-effort ON PURPOSE: this runs to print a
+ * receipt for work that has already committed, so an unreadable models tree must cost the operator
+ * a mark on one line, never the receipt itself. Nothing is decided here — every gate that acts on
+ * a strip ran long before.
+ *
+ * Best-effort is not silent, though: a receipt that quietly stopped marking its destructive
+ * lines reads exactly like a receipt with nothing destructive in it. Say so.
+ */
+async function declaredGranteesForReceipt(
+  plan: EdgePlan,
+  flags: Record<string, string>,
+): Promise<ReadonlySet<string> | undefined> {
+  if (plan.declaredGrantees) return new Set(plan.declaredGrantees);
+  try {
+    return declaredGranteesOf(await loadModels(resolveModelsPath(flags.models)));
+  } catch (err: any) {
+    warn(`the models could not be read, so the receipt below cannot mark a revoke against an undeclared role as DESTRUCTIVE (${err?.message ?? err}). Everything listed still applied; only the marking is degraded.`);
+    return undefined;
+  }
+}
+
+/**
+ * Print a failed catch-up and exit: the report line, then the cause as it was written.
+ *
+ * Only the FIRST line is the failure. The block under it is the cause quoted verbatim, so it
+ * goes out plainly — marking every line of a copy-pasteable SQL statement with our own failure
+ * symbol would both misread and break the copy.
+ */
+function exitOnCatchUpFailure(report: CatchUpReport): asserts report is { ok: true; statements: string[] } {
+  if (report.ok) return;
+  const [head, ...cause] = report.lines;
+  fail(head);
+  for (const text of cause) printLine(text);
+  process.exit(1);
+}
+
 /**
  * Say what descent found, on BOTH lanes identically. Exported so a test can pin the one line
  * that matters most: proven drift is announced as the ORIGIN, loudly, before anything writes.
@@ -219,7 +405,8 @@ async function applyPlanViaStage(
   const fn = opsFunction(config);
   const attestLineageLost = flags['attest-lineage-lost']; // validated (not bare 'true') in dbApplyCommand
 
-  info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
+  // The edge as hashes — internal bookkeeping, not what a reader came for. Verbose only.
+  if (flags.verbose === 'true') info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
 
   // THE STAGE LANE'S READ GUARD, before anything is dispatched. Each introspection is
   // one session, but a full read is two of them (state, then authz) and they can be
@@ -260,6 +447,10 @@ async function applyPlanViaStage(
     process.exit(1);
   }
 
+  // Assigned inside the try; the catch-up and the report happen AFTER it, so a catch-up failure
+  // can never be re-wrapped as "Apply failed" for a plan that actually landed.
+  let landedResult: ApplyPlanResult | undefined;
+
   try {
     // Descent — the fast-forward rule needs the git checkout, so the CLI
     // decides it (the Lambda has no checkout). It runs against the state the
@@ -346,11 +537,21 @@ async function applyPlanViaStage(
     if (result?.snapshotId) {
       info(`snapshot on record: ${result.snapshotId} — restore with db:restore --from ${result.snapshotId} --confirm.`);
     }
-    reportApplyResult(result as ApplyPlanResult, plan);
+    landedResult = result as ApplyPlanResult;
   } catch (err: any) {
     fail(`Apply failed: ${err.message}`);
     process.exit(1);
   }
+
+  // Then the functions, views and triggers — on the same stage, credential-free, always.
+  const catchUp = await catchUpAfterApply(landedResult!, plan, { kind: 'stage', stage: flags.stage }, flags);
+  exitOnCatchUpFailure(catchUp);
+  const declaredGrantees = await declaredGranteesForReceipt(plan, flags);
+  reportApplyResult(landedResult!, plan, {
+    verbose: flags.verbose === 'true',
+    catchUp: catchUp.statements,
+    ...(declaredGrantees ? { declaredGrantees } : {}),
+  });
 }
 
 /**
@@ -383,11 +584,138 @@ async function escalateStageToDirect(
   return { kind: 'url', url: op.url, from: 'operator' };
 }
 
+/**
+ * `db:apply` with NO plan: catch the functions, views and triggers up, and nothing else.
+ *
+ * This is the lane that replaces running `db:reconcile --apply` by hand — the standalone second
+ * command whose being forgotten shipped half a database once, and drifted two stages apart
+ * once. It writes no table and no column, so it needs none of the plan flow's ceremony: there
+ * is no edge to lock a fingerprint against and no merged work a fast-forward rule could protect.
+ *
+ * THE PRE-WRITE CALLER, which is why it takes the `'exit'` default: nothing has been written
+ * when a wire-contract refusal lands here, so the refusal's own message is the correct and
+ * complete one — the stage and the CLI disagree, NOTHING WAS SENT, and the --direct venue
+ * crosses no wire. Borrowing the post-write wording here would tell the operator their changes
+ * are safe (there were none) and hand them a rerun of the command that just refused.
+ */
+async function catchUpOnly(flags: Record<string, string>): Promise<void> {
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  // The credential-free lane: the whole catch-up runs in the stage's ops Lambda.
+  if (dbSource.kind === 'stage' && flags.direct !== 'true') {
+    const report = await runCatchUp({ kind: 'stage', stage: flags.stage }, flags, 0, 'exit');
+    exitOnCatchUpFailure(report);
+    reportCatchUpOnly(report.statements);
+    return;
+  }
+
+  // --stage --direct: resolve the operator connection FROM the stage (held in memory only), then
+  // run CLI-side on an unbounded clock — a large rebuild outlives the ops Lambda's 900s.
+  if (dbSource.kind === 'stage') {
+    try {
+      step('Resolving the operator connection from the stage (--direct)...');
+      const op = await resolveOperatorUrlViaStage(flags.stage);
+      info(`operator credential resolved (${op.source}) — executing CLI-side, unbounded clock.`);
+      dbSource = { kind: 'url', url: op.url, from: 'operator' };
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+  }
+
+  step(connectingVia(dbSource));
+  const { runner, session, end } = await createUrlRunner(dbSource.url);
+  let report: CatchUpReport;
+  try {
+    // The same lease every other write verb takes: one operator mutates a database at a time.
+    report = await withMutationLease(
+      runner,
+      { verb: 'db:apply', actor: process.env.USER ?? 'unknown' },
+      () => runCatchUp({ kind: 'direct', runner, session }, flags, 0, 'exit'),
+    );
+  } catch (err: any) {
+    if (err instanceof MutationLeaseError) {
+      fail(err.message);
+      process.exit(1);
+    }
+    fail(`Apply failed: ${err.message}`);
+    process.exit(1);
+  } finally {
+    await end?.();
+  }
+  exitOnCatchUpFailure(report);
+  reportCatchUpOnly(report.statements);
+}
+
+/** The receipt for a catch-up-only run: the same change lines, the same count, no plan half. */
+function reportCatchUpOnly(statements: readonly string[]): void {
+  const lines = renderApplyReceipt({
+    executable: [],
+    destructive: [],
+    alreadyApplied: statements.length === 0,
+    catchUp: statements,
+  });
+  for (const text of lines.slice(0, -1)) printLine(text);
+  success(lines[lines.length - 1]);
+}
+
+/**
+ * Null when the value is an array of strings, otherwise the parenthetical the refusal carries: it
+ * names what was found, so a hand-edited file can be corrected without guessing which of its
+ * entries the reader means. Whether the field may be ABSENT is the caller's question, not this
+ * one's — the two plan fields checked below answer it differently.
+ */
+function malformedStringArray(value: unknown): string | null {
+  if (!Array.isArray(value)) return `the field is a ${typeof value}`;
+  const at = value.findIndex((entry) => typeof entry !== 'string');
+  if (at === -1) return null;
+  return `entry ${at} is ${value[at] === null ? 'null' : `a ${typeof value[at]}`}`;
+}
+
+/**
+ * What is wrong with a loaded plan's `statements`, or null when nothing is. The field is REQUIRED —
+ * a plan that does not carry one is not a plan — so missing and null are malformed too.
+ */
+function malformedStatementsField(value: unknown): string | null {
+  if (value === undefined) return 'the field is missing';
+  if (value === null) return 'the field is null';
+  return malformedStringArray(value);
+}
+
+/**
+ * What is wrong with a loaded plan's `declaredGrantees`, or null when nothing is.
+ *
+ * Unlike `statements` this field is OPTIONAL, and that difference is the whole check: a plan minted
+ * before the field existed simply does not carry one, and it must keep applying exactly as it does
+ * today — the receipt falls back to the checkout's models for its strip marking. So absent is
+ * VALID, and only a present-but-wrong value is malformed.
+ *
+ * It is refused here, next to `statements`, for the same reason: the field is dereferenced by
+ * `declaredGranteesForReceipt`, which runs to print the receipt AFTER the write has committed and
+ * schema_log has recorded it. A wrong value there is not a bad apply — it is a good apply that
+ * ends in an uncaught TypeError, which reads to the operator like the deploy broke.
+ */
+function malformedDeclaredGranteesField(value: unknown): string | null {
+  if (value === undefined || value === null) return null;
+  return malformedStringArray(value);
+}
+
 export async function dbApplyCommand(flags: Record<string, string>): Promise<void> {
   const planPath = flags.plan;
   if (!planPath) {
-    fail('db:apply needs --plan <file.plan.json> — mint one with db:plan.');
-    process.exit(1);
+    // --state-only says "skip the functions and views". With no plan, that is the whole job.
+    if (flags['state-only'] === 'true') {
+      fail('--state-only skips the functions and views, and without --plan there is nothing else to do. Pass --plan <file.plan.json> (mint one with db:plan), or drop --state-only to catch the functions and views up.');
+      process.exit(1);
+    }
+    await catchUpOnly(flags);
+    return;
   }
 
   let plan: EdgePlan;
@@ -401,6 +729,26 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     fail(`Plan version ${plan.v} is not this CLI's ${PLAN_VERSION} — re-mint with this version's db:plan.`);
     process.exit(1);
   }
+  // A plan is minted by db:plan, but it is still a FILE — a hand edit or an old-format artifact
+  // can hand this command a `statements` that is not an array of SQL strings. Every lane
+  // dereferences that field (the ops-fit estimate before dispatch, the receipt's classification
+  // after the write), so a malformed one used to surface as an uncaught TypeError — on the stage
+  // lane, from inside applyPlanViaStage, AFTER the tables had already changed. Refuse it here,
+  // before any read, any dispatch and any credential.
+  const malformed = malformedStatementsField(plan.statements);
+  if (malformed) {
+    fail(`The plan at ${planPath} is malformed: "statements" must be an array of SQL strings (${malformed}). A plan is minted, not written — re-mint it with db:plan.`);
+    process.exit(1);
+  }
+  // Its sibling, and the same story: `declaredGrantees` is dereferenced to mark the receipt's ⚠
+  // lines, AFTER the write has committed. Absent is fine — that is a plan minted before the field
+  // existed, and the receipt reads the checkout's models instead — so only a present-but-wrong
+  // value is refused, and it is refused in the same breath as `statements`, before anything runs.
+  const malformedGrantees = malformedDeclaredGranteesField(plan.declaredGrantees);
+  if (malformedGrantees) {
+    fail(`The plan at ${planPath} is malformed: "declaredGrantees" must be an array of role names, or absent (${malformedGrantees}). A plan is minted, not written — re-mint it with db:plan.`);
+    process.exit(1);
+  }
 
   let dbSource: DbSource;
   try {
@@ -595,8 +943,11 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
   step(connectingVia(dbSource));
   const { runner, session, end } = await createUrlRunner(dbSource.url);
 
+  let landed: ApplyPlanResult | undefined;
+  let catchUp: CatchUpReport = { ok: true, statements: [] };
   try {
-    info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
+    // The edge as hashes — internal bookkeeping, not what a reader came for. Verbose only.
+  if (flags.verbose === 'true') info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
     // Set inside checkDescent when --attest-lineage-lost is honoured; read at write time so the
     // waiver lands in the schema_log outcome (the descent decision runs before the apply writes).
     let descentAttested: string | undefined;
@@ -604,60 +955,86 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     // The mutation lease: one operator mutates a database at a time. Acquired on this apply's
     // own session (the max:1 createUrlRunner) before any write; a second operator is refused
     // by name. Self-releases on disconnect.
-    const result = await withMutationLease(
+    //
+    // ONE lease covers the WHOLE chain — the plan AND the catch-up that follows it. The
+    // catch-up creates, replaces and drops views, functions and triggers on this same
+    // connection, so it is a mutation in exactly the sense the lease exists for; releasing
+    // between the two halves would let a second operator start writing while this one is
+    // still replacing views. `executeReconcile` takes no lease of its own (every lease in
+    // this tree is taken by a command, never by the reconcile core) and opens no second
+    // connection, so widening the body cannot self-deadlock.
+    //
+    // WHAT THIS COVERS: the DIRECT lane, and every other DIRECT call site of the same
+    // catch-up — catchUpOnly below, and db:reconcile --apply. It does NOT cover the --stage
+    // (ops Lambda) lane, which holds no mutation lease at all, for its plan or for its
+    // catch-up: both halves are separate invokes on separate connections in separate
+    // containers, and neither ops action takes a lease. That is a server-side gap, tracked as
+    // m5-air-local.me1l0g.0mu398eqb.63cpjf, and there is nothing the CLI can widen to close it.
+    const leased = await withMutationLease(
       runner,
       { verb: 'db:apply', actor: process.env.USER ?? 'unknown' },
-      () => executeApplyPlan(runner, session, plan, {
-      actor: process.env.USER ?? null,
-      gitRef: currentGitRef() ?? plan.gitRef,
-      ...(verifyAuthority ? { verifyAuthority } : {}),
-      // The rollback point must capture the state this plan STARTS from. A logical backup stamps
-      // the live fingerprint at dump time; if it does not equal plan.from, restoring it would not
-      // return the database to where the plan began — so refuse (the escape is re-plan, not a
-      // flag). A physical snapshot carries no stamp: it is fresh and the concurrency lock below
-      // proves live == plan.from, so temporal ordering is its coverage. `none` opted out.
-      ...(rollbackPoint?.stampedFingerprint
-        ? {
-            verifySnapshot: async ({ planFrom }: { planFrom: string }) =>
-              rollbackPoint!.stampedFingerprint === planFrom
-                ? { ok: true as const }
-                : {
-                    ok: false as const,
-                    reason: snapshotMovedRefusal(rollbackPoint!.ref!, rollbackPoint!.stampedFingerprint!, planFrom),
-                  },
-          }
-        : {}),
-      // Re-verified here, not just at mint: a plan is an artifact with a lifetime, and a
-      // foreign role granted between minting and applying would otherwise ride through.
-      verifyAuthzBaseline: async ({ contract }) => {
-        const stageName = flags.stage || 'local';
-        const models = await loadModels(resolveModelsPath(flags.models));
-        const governedRoles = (await loadDeclaredDerived(flags.models))?.governedRoles ?? [];
-        const declaredAuthz = { tables: models.map((m) => compileTableContract(m, {})), functions: [] };
-        const exemptions = ungovernedGrants(contract, governedRoleSet(declaredAuthz, governedRoles));
-        const violations = checkAgainstBaseline(await readBaselineFile(), stageName, exemptions);
-        return violations.length === 0
-          ? { ok: true as const }
-          : { ok: false as const, reason: baselineRefusal(stageName, violations) };
-      },
-      dirty: worktreeDirty(resolveModelsPath(flags.models)),
-      descentNote: () => descentAttested,
-      checkDescent: async (live: LiveState & { fingerprint: string; ledger: DescentLedgerRow[] }) => {
-        step('Descent: proving the fast-forward rule against the schema_log ledger...');
-        const result = await proveDescentForApply({
-          modelsPath: resolveModelsPath(flags.models),
-          live,
-          ledger: live.ledger,
-          destructive: plan.destructive > 0,
-          ...(attestLineageLost ? { attestation: attestLineageLost } : {}),
+      async () => {
+        const result = await executeApplyPlan(runner, session, plan, {
+          actor: process.env.USER ?? null,
+          gitRef: currentGitRef() ?? plan.gitRef,
+          ...(verifyAuthority ? { verifyAuthority } : {}),
+          // The rollback point must capture the state this plan STARTS from. A logical backup stamps
+          // the live fingerprint at dump time; if it does not equal plan.from, restoring it would not
+          // return the database to where the plan began — so refuse (the escape is re-plan, not a
+          // flag). A physical snapshot carries no stamp: it is fresh and the concurrency lock below
+          // proves live == plan.from, so temporal ordering is its coverage. `none` opted out.
+          ...(rollbackPoint?.stampedFingerprint
+            ? {
+                verifySnapshot: async ({ planFrom }: { planFrom: string }) =>
+                  rollbackPoint!.stampedFingerprint === planFrom
+                    ? { ok: true as const }
+                    : {
+                        ok: false as const,
+                        reason: snapshotMovedRefusal(rollbackPoint!.ref!, rollbackPoint!.stampedFingerprint!, planFrom),
+                      },
+              }
+            : {}),
+          // Re-verified here, not just at mint: a plan is an artifact with a lifetime, and a
+          // foreign role granted between minting and applying would otherwise ride through.
+          verifyAuthzBaseline: async ({ contract }) => {
+            const stageName = flags.stage || 'local';
+            const models = await loadModels(resolveModelsPath(flags.models));
+            const governedRoles = (await loadDeclaredDerived(flags.models))?.governedRoles ?? [];
+            const declaredAuthz = { tables: models.map((m) => compileTableContract(m, {})), functions: [] };
+            const exemptions = ungovernedGrants(contract, governedRoleSet(declaredAuthz, governedRoles));
+            const violations = checkAgainstBaseline(await readBaselineFile(), stageName, exemptions);
+            return violations.length === 0
+              ? { ok: true as const }
+              : { ok: false as const, reason: baselineRefusal(stageName, violations) };
+          },
+          dirty: worktreeDirty(resolveModelsPath(flags.models)),
+          descentNote: () => descentAttested,
+          checkDescent: async (live: LiveState & { fingerprint: string; ledger: DescentLedgerRow[] }) => {
+            step('Descent: proving the fast-forward rule against the schema_log ledger...');
+            const result = await proveDescentForApply({
+              modelsPath: resolveModelsPath(flags.models),
+              live,
+              ledger: live.ledger,
+              destructive: plan.destructive > 0,
+              ...(attestLineageLost ? { attestation: attestLineageLost } : {}),
+            });
+            descentAttested = result.descentAttested;
+            return result.descentVerdict;
+          },
         });
-        descentAttested = result.descentAttested;
-        return result.descentVerdict;
+
+        // The catch-up rides the SAME connection and the SAME lease, right after the apply
+        // committed — so the functions and views can never be a release behind the tables
+        // they read, and no second operator can slip in between the two halves. Its failure
+        // is carried out as a report, never thrown: the plan landed, and "rolled back" would
+        // be a lie.
+        const report = await catchUpAfterApply(result, plan, { kind: 'direct', runner, session }, flags);
+        return { result, catchUp: report };
       },
-      }),
     );
 
-    reportApplyResult(result, plan);
+    catchUp = leased.catchUp;
+    landed = leased.result;
   } catch (err: any) {
     if (err instanceof MutationLeaseError) {
       // Nothing was applied — the lease refused before any write. Not a rollback.
@@ -669,4 +1046,12 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
   } finally {
     await end?.();
   }
+
+  exitOnCatchUpFailure(catchUp);
+  const declaredGrantees = await declaredGranteesForReceipt(plan, flags);
+  reportApplyResult(landed!, plan, {
+    verbose: flags.verbose === 'true',
+    catchUp: catchUp.statements,
+    ...(declaredGrantees ? { declaredGrantees } : {}),
+  });
 }