@everystack/cli 0.4.58 → 0.4.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.58",
+  "version": "0.4.60",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -160,7 +160,7 @@
     "jest": "29.7.0",
     "react": "19.2.0",
     "ts-jest": "29.4.9",
-    "@everystack/server": "0.4.20"
+    "@everystack/server": "0.4.21"
   },
   "scripts": {
     "test": "jest",

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

@@ -21,6 +21,7 @@ import { pipeline } from 'node:stream/promises';
 import { randomBytes } from 'node:crypto';
 import { resolveConfig, opsFunction, type CliConfig } from '../config.js';
 import { invokeAction, presignGet, getS3 } from '../aws.js';
+import { runStageBackup, stageBackupDeps } from '../stage-backup.js';
 import {
   parseBackupRef, keyForId, crossStageGuard, restoreTargetGuard,
   backupKey, backupId, metaKey, utcStamp,
@@ -226,39 +227,27 @@ export async function dbBackupCommand(flags: Record<string, string>): Promise<vo
   info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
   const fn = opsFunction(config);
 
-  step('Dispatching the backup task (credential-free, via the ops Lambda)...');
-  let dispatched: any;
-  try {
-    dispatched = await invokeAction(config.region, fn, 'db:backup', { stage: flags.stage, actor: process.env.USER ?? null });
-  } catch (err: any) {
-    fail(`Backup failed to dispatch: ${err.message}`);
-    process.exit(1);
-  }
-  if (dispatched?.error) {
-    fail(`Backup failed: ${dispatched.error}`);
-    process.exit(1);
-  }
-  const { runId, taskArn, id, warning } = dispatched as { runId: string; taskArn: string; id: string; warning?: string };
-  info(`backup ${id} — task ${taskArn}`);
-  info(`run id: ${runId} (everystack.task_log)`);
-  if (warning) info(`note: ${warning}`);
+  const result = await runStageBackup(stageBackupDeps(config, fn, flags.stage, {
+    onDispatch: (d) => {
+      info(`backup ${d.id} — task ${d.taskArn}`);
+      info(`run id: ${d.runId} (everystack.task_log)`);
+      // The dispatch warning is folded into result.warning and printed at the end, so printing it
+      // here too says the same thing twice.
+    },
+  }));
 
-  step('Running pg_dump → S3 (this may take a while for large databases)...');
-  const poll = await pollTaskUntilStopped(config.region, fn, { runId, taskArn });
-  if (poll.outcome === 'timeout') {
-    fail(`db:backup timed out (last status: ${poll.lastStatus}). Run id ${runId} — reconcile via ECS/everystack.task_log.`);
-    process.exit(1);
-  }
-  if (poll.outcome === 'error') {
-    fail(`task:status failed repeatedly: ${poll.status.error}. The backup may still be running — reconcile run id ${runId}.`);
-    process.exit(1);
-  }
-  if (poll.status.exitCode !== 0) {
-    fail(`Backup failed (exit ${poll.status.exitCode ?? 'unknown'})${poll.status.stoppedReason ? ` — ${poll.status.stoppedReason}` : ''}. Read the task logs (CloudWatch).`);
+  if (!result.ok) {
+    fail(`Backup failed: ${result.reason}`);
+    if (result.orphanKey) {
+      info(`The artifact is still in the bucket: s3://${config.backupsBucket ?? '<backups-bucket>'}/${result.orphanKey}`);
+    }
     process.exit(1);
   }
-  const bytes = (poll.status.result?.bytes as number | undefined) ?? undefined;
-  success(`Backup ${id} (${fmtBytes(bytes)}). Restore with: everystack db:restore --from ${id} --confirm`);
+
+  // Render it. The helper produced this and nothing printed it, so the one signal that an artifact
+  // was not verified against what the operator sent was invisible at the only moment it mattered.
+  if (result.warning) warn(result.warning);
+  success(`Backup ${result.id} (${fmtBytes(result.bytes)}). Restore with: everystack db:restore --from ${result.id} --confirm`);
 }
 
 /** db:backups — list a stage's logical backups. */

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

@@ -23,6 +23,7 @@ import { resolveConfig, opsFunction, type CliConfig } from '../config.js';
 import { invokeAction, presignGet } from '../aws.js';
 import { keyForId, parseBackupRef, isProductionTier, crossStageGuard } from '../backup.js';
 import { pollTaskUntilStopped } from '../task-poll.js';
+import { runStageBackup, stageBackupDeps } from '../stage-backup.js';
 import { step, success, fail, info, warn } from '../output.js';
 
 export type ForkGuardVerdict =
@@ -94,18 +95,17 @@ export async function dbForkCommand(flags: Record<string, string>): Promise<void
     info(`Reusing backup ${backupId}.`);
   } else {
     step(`Backing up ${from} (pg_dump → S3 in the Task; may take a while for large databases)...`);
-    const dispatched: any = await invokeAction(source.region, opsFunction(source), 'db:backup', { stage: from, actor: process.env.USER ?? null });
-    if (dispatched?.error) {
-      fail(`Source backup failed: ${dispatched.error}`);
-      process.exit(1);
-    }
-    backupId = dispatched.id;
-    const poll = await pollTaskUntilStopped(source.region, opsFunction(source), { runId: dispatched.runId, taskArn: dispatched.taskArn });
-    if (poll.outcome !== 'stopped' || poll.status.exitCode !== 0) {
-      const why = poll.outcome === 'stopped' ? `exit ${poll.status.exitCode}${poll.status.stoppedReason ? ` — ${poll.status.stoppedReason}` : ''}` : poll.outcome;
-      fail(`Source backup failed (${why}). Reconcile run ${dispatched.runId}.`);
+    // The shared sandwich: a fork built from a dump that spans a migration copies a schema that
+    // never existed. Same helper db:backup and db:swap use, so all three agree on what a proven
+    // artifact is.
+    const backup = await runStageBackup(stageBackupDeps(source, opsFunction(source), from, { onStep: step }));
+    if (!backup.ok) {
+      fail(`Source backup failed: ${backup.reason} The fork was NOT created.`);
+      if (backup.orphanKey) info(`The artifact is still in the bucket: s3://${source.backupsBucket}/${backup.orphanKey}`);
       process.exit(1);
     }
+    backupId = backup.id;
+    if (backup.warning) warn(backup.warning);
     info(`Backup ${backupId}.`);
   }
 

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

@@ -194,11 +194,19 @@ export async function executeReconcile(
   // renderEnsureObjectSchemas.
   const ensureSchemas = renderEnsureObjectSchemas(parsed.objects);
 
-  // Which phase we are in when something throws. A bookkeeping failure inside the atomic path
-  // rolls the DDL back too, so the operator sees no plan output and no applied statements —
+  // Which phase we are in when something throws. Anything after the DDL rolls the DDL back with
+  // it inside the atomic path, so the operator sees no plan output and no applied statements —
   // indistinguishable from a batch that never started, and the wrong thing to go debugging.
   // The phase is the difference between "your DDL is bad" and "your DDL was fine".
-  let phase: 'ddl' | 'bookkeeping' = 'ddl';
+  //
+  // THREE phases, not two, because the post-apply work has two halves that fail for different
+  // reasons and are fixed differently. `verify` is everything between the DDL and the write: the
+  // catalog re-read, and the checks that stand between it and recording (a recorded identity with
+  // no source object, an object the catalog cannot see afterwards, a backend pid that moved). The
+  // DDL ran and NO bookkeeping was ever attempted. `bookkeeping` is the single provenance +
+  // schema_log write, plus the COMMIT that seals it. Reporting a re-read failure as `bookkeeping`
+  // sent the operator looking at a write that never happened.
+  let phase: 'ddl' | 'verify' | 'bookkeeping' = 'ddl';
 
   if (atomic) await runner('BEGIN');
   try {
@@ -236,11 +244,47 @@ export async function executeReconcile(
     // the canonical search_path inside a savepoint it always rolls back, so the def hashes are
     // stable regardless of the create-time wide path above — and that wide path survives the read.
     // The unwrapped path has no transaction to borrow, so it takes a session of its own.
-    phase = 'bookkeeping';
+    phase = 'verify';
     const after = await introspectDerived(atomic ? borrowedSessionRunner(runner) : session);
     const liveById = new Map(after.objects.map((o) => [o.identity, o]));
     const srcById = new Map(parsed.objects.map((o) => [o.identity, o]));
 
+    // THE ORPHAN CHECK — an outcome assertion, not a plan-shape one. Every identity whose
+    // provenance we are about to DELETE must be gone from the database. The read above is the
+    // real post-DDL catalog, so this asks the only question that matters: after this batch, is
+    // there a live object whose bookkeeping we are about to throw away?
+    //
+    // A live object with no provenance row reads as `unmanaged` — "not in source, never touched"
+    // — so it is never dropped, keeps its grants, and `--check` stays green. Nothing downstream
+    // can tell that state apart from an object that was genuinely never ours, which is why this
+    // has to be caught at the moment the row is lost rather than found afterwards.
+    //
+    // Reachable, and the mechanism is a search_path disagreement, NOT a declared spelling (drop
+    // identities come from the live catalog, never from the declaration). Introspection pins
+    // `search_path = public`, so a public-schema type renders BARE inside a function identity;
+    // the DDL batch omits its own SET when every declared schema is public; and under an ambient
+    // `ALTER DATABASE … SET search_path = app` the rendered `DROP FUNCTION IF EXISTS
+    // public.f(my_enum)` cannot resolve `my_enum`. PostgreSQL answers `NOTICE: type "my_enum"
+    // does not exist, skipping` and drops nothing. IF EXISTS makes that silent.
+    //
+    // A `defineSql` object never trips this — not because it is catalog-invisible (a defineSql
+    // function or procedure is perfectly visible) but because its identity is `schema.name`
+    // while the catalog reports `schema.name(argtypes)`, so the two never join.
+    const orphaned = rendered.remove.filter((identity) => liveById.has(identity));
+    if (orphaned.length > 0) {
+      throw new Error(
+        `refusing to drop provenance for ${orphaned.map((i) => `${i} (${liveById.get(i)!.kind})`).join(', ')}: `
+        + `the object is STILL LIVE after the batch, so its DROP did not remove it. DROP ... IF EXISTS is `
+        + `silent when a name in the target cannot be resolved — check the database's search_path `
+        + `(SHOW search_path; ALTER DATABASE ... SET search_path) against the identity above. Deleting the `
+        + `row anyway would leave the object running with its grants, reported as "unmanaged", and never `
+        + `dropped again.\n\nNo provenance was written. There is no automated recovery for this state yet — `
+        + `the generic guidance below names --baseline and --rebuild, and NEITHER applies here: both act on `
+        + `objects the source still declares, and this one is absent from source. Drop the object by hand `
+        + `once its name resolves, then re-run.`,
+      );
+    }
+
     const bookkeeping: string[] = [];
     // ORDER MATTERS: migrate, then record, then remove. This ordering is LOAD-BEARING — it is the
     // fix, not the belt. `renderProvenanceMigrate`'s own guard is the belt (see its docstring).
@@ -254,11 +298,12 @@ export async function executeReconcile(
     // Migrating first leaves the row already keyed by its new identity, so the upsert updates it.
     //
     // The guard alone would NOT be enough. Under record-first it makes one case actively worse: a
-    // source 'sql'-kind object sharing a legacy function identity (derived-plan.ts:191 skips on
-    // `prov.kind === 'sql'` but not `src.kind`) gets its freshly recorded row deleted by the guard,
-    // orphaning its provenance for good. Migrating first is what prevents that.
-    // NOT YET PINNED BY A TEST — reverting this reorder leaves the whole suite green. See
-    // issue:db-reconcile-provenance-migrate-is-the-one-unguarded-write-a (G4).
+    // source 'sql'-kind object sharing a legacy function identity (derived-plan.ts skips on
+    // `prov.kind === 'sql'` but not `src.kind` — deliberately, see the DELIBERATELY NOT SKIPPED
+    // note there) gets its freshly recorded row deleted by the guard, orphaning its provenance for
+    // good. Migrating first is what prevents that.
+    // PINNED BY __tests__/integration/provenance-migrate.test.ts — that scenario is the only one
+    // where the two orders diverge, and it is the ONLY test that reverting this reorder turns red.
     for (const m of rendered.migrate) bookkeeping.push(renderProvenanceMigrate(m.from, m.to));
     for (const identity of rendered.record) {
       const src = srcById.get(identity);
@@ -299,6 +344,9 @@ export async function executeReconcile(
         );
       }
     }
+    // Everything after the DDL has so far only read and rendered. From here the phase is the
+    // bookkeeping write itself, and the COMMIT that seals it.
+    phase = 'bookkeeping';
     await runner(bookkeeping.join(';\n'));
 
     if (atomic) await runner('COMMIT');
@@ -330,24 +378,36 @@ export async function executeReconcile(
  * cryptic unique-violation on `pg_type`/`pg_class` instead of anything actionable. Turn that into
  * a message that tells the operator what to do.
  *
- * `phase` says WHICH half died. A bookkeeping failure rolls the DDL back with it, so the operator's
+ * `phase` says WHICH part died. A post-DDL failure rolls the DDL back with it, so the operator's
  * only evidence is an absence — no plan output, nothing applied — which reads as a batch that never
- * started. Say plainly that the DDL was fine, or the next person debugs the wrong half.
+ * started. Say plainly that the DDL was fine, or the next person debugs the wrong half. `verify` and
+ * `bookkeeping` are named apart because they fail for different reasons: the first is the catalog
+ * re-read and the checks that stand between it and recording, the second is the provenance/schema_log
+ * write and its COMMIT.
  */
-export function explainReconcileError(err: unknown, phase: 'ddl' | 'bookkeeping' = 'ddl', atomic = true): Error {
+export function explainReconcileError(err: unknown, phase: 'ddl' | 'verify' | 'bookkeeping' = 'ddl', atomic = true): Error {
   const msg = String((err as any)?.message ?? err);
-  if (/pg_type_typname_nsp_index|pg_class_relname_nsp_index|already exists/i.test(msg)) {
-    return new Error(
-      `${msg}\n\nreconcile tried to CREATE a derived object whose name already exists — usually a partial `
-      + `earlier run or a hand-created object (its create is not idempotent). Resolve by explicitly dropping `
-      + `the colliding object (DROP MATERIALIZED VIEW / VIEW … CASCADE) and re-running, or, if the plan reports `
-      + `it as drift, re-run with --overwrite-drift.`,
-    );
-  }
-  if (phase === 'bookkeeping') {
+  // PHASE FIRST — the order is load-bearing. The name-collision advice below tells the operator to
+  // DROP … CASCADE, which is destructive and simply wrong for a failure that happened after the DDL
+  // (there, the create already succeeded).
+  //
+  // No post-DDL error reaches that text TODAY, and the reason is what to re-check before trusting
+  // this: neither post-DDL phase runs a CREATE. `verify` is SELECTs plus in-process throws;
+  // `bookkeeping` is INSERT/UPDATE/DELETE on two everystack tables. Nothing there can raise 42P07
+  // or 42710. (`already exists` IS a primary message for 42P07 — the regex would match it fine.)
+  // So the ordering is insurance. It stops being insurance the moment a phase gains a CREATE —
+  // moving ENSURE_RECONCILER_SQL, with its CREATE … IF NOT EXISTS, inside the try would do it.
+  if (phase === 'verify' || phase === 'bookkeeping') {
     return new Error(
-      `${msg}\n\nThis failed AFTER the DDL, not in it. The failure came from the post-apply catalog re-read `
-      + `or from the provenance/schema_log write that records what was built`
+      `${msg}\n\nThis failed AFTER the DDL, not in it. `
+      + (phase === 'verify'
+        ? `The failure came from the verify half: the post-apply catalog re-read, or one of the checks `
+          + `over it — a recorded identity with no source object, an object the catalog cannot see `
+          + `afterwards, or a backend pid that moved. No provenance and no 'applied' schema_log row `
+          + `was written; the bookkeeping write is never reached`
+        : `The failure came from the bookkeeping write that records what was built — the provenance and `
+          + `schema_log statements, or the COMMIT that seals them. The post-apply catalog re-read `
+          + `succeeded, so every recorded object was introspectable when it ran`)
       + (atomic
         ? `. That work shares the DDL's transaction, so the transaction rolled EVERYTHING back and nothing is `
           + `applied — the database is exactly as it was. Resolve the cause and re-run.`
@@ -360,6 +420,14 @@ export function explainReconcileError(err: unknown, phase: 'ddl' | 'bookkeeping'
       + `WHERE outcome LIKE 'failed%' ORDER BY applied_at DESC LIMIT 3;`,
     );
   }
+  if (/pg_type_typname_nsp_index|pg_class_relname_nsp_index|already exists/i.test(msg)) {
+    return new Error(
+      `${msg}\n\nreconcile tried to CREATE a derived object whose name already exists — usually a partial `
+      + `earlier run or a hand-created object (its create is not idempotent). Resolve by explicitly dropping `
+      + `the colliding object (DROP MATERIALIZED VIEW / VIEW … CASCADE) and re-running, or, if the plan reports `
+      + `it as drift, re-run with --overwrite-drift.`,
+    );
+  }
   return err instanceof Error ? err : new Error(msg);
 }
 
@@ -385,6 +453,15 @@ export function buildReconcileReport(plan: ReconcilePlan): string[] {
     const cost = a.bytes !== undefined ? `; ${formatBytes(a.bytes)}${a.rows ? `, ~${a.rows} rows` : ''}` : '';
     lines.push(`${VERB_GLYPH[a.action] ?? '?'} ${a.action} ${a.identity} (${a.reason}${cost})`);
   }
+  // Pending identity migrations. Bookkeeping only — no DDL, no object changed — but they ARE a
+  // write, and they were invisible here while also being excluded from `checkFails`. Silence in
+  // both places is how a re-key nobody asked about becomes a surprise.
+  for (const m of plan.migrations) {
+    lines.push(
+      `⇢ re-key ${m.from} → ${m.to} (provenance only — the identity spelling this cli reports; `
+      + `pending until --apply, and it does NOT fail --check)`,
+    );
+  }
   const rebuilt = plan.actions.filter((a) => (a.action === 'create' || a.action === 'refresh') && a.bytes !== undefined);
   if (plan.totalRebuildBytes > 0) {
     lines.push(`estimated rebuild: ${formatBytes(plan.totalRebuildBytes)} across ${rebuilt.length} matview(s)`);
@@ -416,7 +493,16 @@ export function buildReconcileReport(plan: ReconcilePlan): string[] {
  *  Baseline and rebaseline are explicit adoption the operator asked for, not findings; a
  *  backfill is record-only bookkeeping (body_hash arming) — neither is a CI failure. An
  *  UNAPPLIED authz-only grant change still fails here via `regrants` below (the real signal);
- *  an empty regrant delta means live already matches declared, so green is correct. */
+ *  an empty regrant delta means live already matches declared, so green is correct.
+ *
+ *  `plan.migrations` is DELIBERATELY not here, for the backfill's reason. An identity migration
+ *  re-keys a provenance row a cli upgrade under-keyed; it emits no DDL, changes no object, and
+ *  converges in one apply. Failing on it would turn CI red for every consumer on the release that
+ *  introduces the new identity spelling, and the only fix on offer would be "run apply" — a gate
+ *  whose remedy is the thing the gate is supposed to be checking for. The live layer still matches
+ *  the declared source, which is what `--check` asserts. Decided 2026-08-12; reversible by adding
+ *  one clause. Green here is only defensible because the plan report PRINTS every pending
+ *  migration (see buildReconcileReport) — silent in both places would be a write nobody can see. */
 export function checkFails(plan: ReconcilePlan): boolean {
   return plan.actions.some((a) => a.action !== 'baseline' && a.action !== 'rebaseline' && a.action !== 'backfill')
     || plan.drift.length > 0

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

@@ -45,6 +45,7 @@ import { keyForArtifactId, metaKey, utcStamp } from '../backup.js';
 import { rdsSnapshotIdentifier } from '../rds-snapshot.js';
 import { pollTaskUntilStopped } from '../task-poll.js';
 import { decideSnapshotMode, confirmPhysicalSnapshot, interpretBackupPoll, type SnapshotModeRequest } from '../swap-snapshot.js';
+import { runStageBackup, stageBackupDeps } from '../stage-backup.js';
 import { pgEnvFromUrl, pgKeepaliveConninfo } from './db.js';
 import { step, success, fail, warn, info } from '../output.js';
 
@@ -475,19 +476,30 @@ async function takePreSwapSnapshot(
   // Logical: dispatch the Task and WAIT. The dispatch returning is not the backup existing — that
   // conflation is what let a pg_dump run concurrently with the restore it was supposed to precede.
   step('Snapshotting the stage before the swap (db:backup — waiting for the dump to finish)...');
-  const dispatched: any = await invokeAction(ctx.region!, ctx.opsFn!, 'db:backup', {
-    stage: ctx.stage,
-    actor: process.env.USER ?? null,
+  // The shared sandwich. A rollback point taken across a concurrent migration holds a schema that
+  // matches neither endpoint — restoring from it would not return the stage to where it was, which
+  // is the one thing a pre-swap snapshot has to guarantee. An unproven artifact fails the swap.
+  const backup = await runStageBackup({
+    ...stageBackupDeps({ region: ctx.region! }, ctx.opsFn!, ctx.stage, {
+      onStep: step,
+      onDispatch: (d: { id: string; runId: string }) => info(`backup ${d.id} dispatched (run ${d.runId}) — waiting for the task to stop before the restore starts.`),
+    }),
+    // Swap keeps its OWN reading of a finished poll: it is the only caller that can tell the
+    // operator to re-run with `--snapshot-ref <id>` once the dump lands, and each outcome needs
+    // different advice. The shared helper takes injected deps for exactly this.
+    awaitTask: async (ids) => {
+      const poll = await pollTaskUntilStopped(ctx.region!, ctx.opsFn!, { runId: ids.runId, taskArn: ids.taskArn });
+      const verdict = interpretBackupPoll(poll, { runId: ids.runId, id: ids.id });
+      if (!verdict.ok) return verdict;
+      // Carry the stamp through, or this caller silently opts out of the image-skew check.
+      return { ok: true, stampedFingerprint: (poll as any).status?.result?.fingerprint as string | undefined };
+    },
   });
-  if (dispatched?.error) throw new Error(`the pre-swap backup would not dispatch, so the swap was NOT applied: ${dispatched.error}`);
-  const { runId, taskArn, id } = dispatched as { runId: string; taskArn: string; id: string };
-  info(`backup ${id} dispatched (run ${runId}) — waiting for the task to stop before the restore starts.`);
-  const verdict = interpretBackupPoll(
-    await pollTaskUntilStopped(ctx.region!, ctx.opsFn!, { runId, taskArn }),
-    { runId, id },
-  );
-  if (!verdict.ok) throw new Error(verdict.reason);
-  info(`rollback point CONFIRMED: backup ${id} complete — restore with db:restore --from ${id} --confirm.`);
+  if (!backup.ok) {
+    throw new Error(`the pre-swap backup is not a usable rollback point, so the swap was NOT applied and live is untouched: ${backup.reason}`);
+  }
+  if (backup.warning) warn(backup.warning);
+  info(`rollback point CONFIRMED: backup ${backup.id} complete — restore with db:restore --from ${backup.id} --confirm.`);
 }
 
 export async function dbSwapCommand(flags: Record<string, string>): Promise<void> {

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

@@ -88,8 +88,9 @@ export interface SyncOptions {
 }
 
 export interface SyncHooks {
-  /** Fires after the state diff is computed, BEFORE anything executes — the review seam. */
-  onStatePlan?: (statements: string[], classified: ClassifiedStatements) => void;
+  /** Fires after the state diff is computed, BEFORE anything executes — the review seam.
+   *  `pass` is 1, or 2 on the settling pass (see {@link executeSync}). */
+  onStatePlan?: (statements: string[], classified: ClassifiedStatements, pass: number) => void;
   /** Fires after the state layer applied and verified, before the compute reconcile. */
   onStateDone?: (state: StateSyncOutcome) => void;
 }
@@ -114,12 +115,13 @@ export interface SyncRun {
  * compute, then the verdict. Pure orchestration over an injected QueryRunner;
  * the CLI shell below owns flags, files, and exits.
  */
-export async function executeSync(
+async function syncOnce(
   runner: QueryRunner,
   session: SessionRunner,
   models: ModelDescriptor[],
-  options: SyncOptions = {},
-  hooks: SyncHooks = {},
+  options: SyncOptions,
+  hooks: SyncHooks,
+  pass: number,
 ): Promise<SyncRun> {
   const current = await introspectSchema(session);
   const liveAuthz = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
@@ -127,7 +129,7 @@ export async function executeSync(
     allowDrops: options.allowDrops, liveAuthz, sequences: options.sequences,
     governedRoles: options.governedRoles, extensions: options.extensions,
   });
-  hooks.onStatePlan?.(statements, classifyGeneratedStatements(statements));
+  hooks.onStatePlan?.(statements, classifyGeneratedStatements(statements), pass);
 
   const state = await applyStateAndVerify(runner, session, models, statements, current, liveAuthz, {
     allowDrops: options.allowDrops, sequences: options.sequences, extensions: options.extensions,
@@ -167,6 +169,92 @@ export async function executeSync(
   };
 }
 
+/**
+ * A sync that SETTLES — at most one extra pass, and the reason it is needed is inherent to
+ * creating things rather than a patch over one bug.
+ *
+ * `syncOnce` is a single diff-and-verify: it reads the live authz contract, computes the delta,
+ * applies it. On a FROM-SCRATCH run some objects the authz layer must grant on do not exist at
+ * read time — most sharply the sequence behind a serial column, which our own CREATE TABLE makes
+ * moments later. The first pass cannot see it, the sequence inheritance rule (A6) has nothing to
+ * grant on, and the run ends with a role that may INSERT into a table but cannot draw its
+ * sequence value. Measured on a consumer's 251-model schema: pass one reported `MATCH` and
+ * `NOT converged` in the same breath, and pass two applied 205 statements, nearly all of them
+ * `GRANT … ON SEQUENCE`.
+ *
+ * `buildIntoDatabase` has carried this second pass since A12, so `db:build`, `db:check`'s
+ * compose ring and `db:template:refresh` always settled. The `db:sync` VERB did not — it ran
+ * once and told the operator to run it again. That put "run db:sync twice" in a consumer's
+ * runbook as folklore, and its exit 1 aborted their documented one-verb from-scratch path
+ * before any data loaded. The retry belongs HERE, where every caller gets it and none has to
+ * know.
+ *
+ * Bounded at exactly one extra pass. The second read sees everything the first one created, so
+ * a third could only differ if the apply were non-convergent — and that is a real failure the
+ * `converged` bar must report, never something to loop away.
+ *
+ * An already-synced database converges on pass one and never pays for the second read.
+ */
+export async function executeSync(
+  runner: QueryRunner,
+  session: SessionRunner,
+  models: ModelDescriptor[],
+  options: SyncOptions = {},
+  hooks: SyncHooks = {},
+): Promise<SyncRun> {
+  const first = await syncOnce(runner, session, models, options, hooks, 1);
+  // The trigger is the STATE bar, not the combined verdict. The cause above is state-layer
+  // only, so a compute refusal or an unadopted object cannot be settled by looking again —
+  // retrying on those would make every brownfield sync pay a second full read (and print its
+  // refusal twice) to reach the same answer.
+  if (first.stateConverged) return first;
+  const second = await syncOnce(runner, session, models, options, hooks, 2);
+  return {
+    ...second,
+    state: mergeStateOutcomes(first.state, second.state),
+    // Report the reconcile that DID the work. The settling pass re-reads the derived layer the
+    // first pass created and correctly finds it managed and unchanged — reporting THAT as the
+    // outcome tells the operator "N up to date" about objects this very command just created,
+    // and hands `--json` a `compute.applied: false` for a successful build. Findings are not
+    // lost either way: a refusal, drift and needsBaseline are recomputed from live state on
+    // every pass, so the second run reports them again.
+    compute: first.compute?.applied && !second.compute?.applied ? first.compute : second.compute,
+  };
+}
+
+/**
+ * Two passes, reported as the one operation the operator ran.
+ *
+ * The split is WORK DONE versus WORK PENDING, and each field belongs to one of them.
+ *
+ * Work done accumulates: `executable` is what actually ran, in the order it ran, and
+ * `fromFingerprint` is where the database ACTUALLY started — take the settling pass's and the
+ * record reads as though the first pass never happened.
+ *
+ * Work pending is whatever is STILL pending at the end, so it comes from the second pass alone.
+ * `heldDrops` and `notices` are regenerated from live state on every pass and are never
+ * executed, so concatenating them counts the same held `DROP TABLE` twice — and a destructive
+ * change reported at 2x is the wrong direction to be wrong in.
+ */
+function mergeStateOutcomes(first: StateSyncOutcome, second: StateSyncOutcome): StateSyncOutcome {
+  return {
+    // `remaining`, `toFingerprint`, `after` and the pending buckets all come from the second
+    // pass through this spread — the END state is the bar.
+    ...second,
+    statements: [...first.statements, ...second.statements],
+    classified: {
+      executable: [...first.classified.executable, ...second.classified.executable],
+      heldDrops: second.classified.heldDrops,
+      notices: second.classified.notices,
+    },
+    applied: first.applied || second.applied,
+    fromFingerprint: first.fromFingerprint,
+    // Two passes that both ran DDL wrote TWO schema_log rows, correctly chained (A→B, B→C).
+    // This carries the later one; `schema_log` itself is the record of the pair, not this field.
+    logId: second.logId ?? first.logId,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Report rendering (pure).
 // ---------------------------------------------------------------------------
@@ -327,9 +415,16 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
         gitRef: currentGitRef(),
       },
       {
-        onStatePlan: (statements, classified) => {
+        onStatePlan: (statements, classified, pass) => {
           if (classified.executable.length > 0) {
-            info(`state plan — ${classified.executable.length} statement(s):`);
+            // The settling pass is named, not hidden — an operator who sees a second plan with
+            // no explanation reads it as the sync failing. It says WHAT it is, never why: on a
+            // fresh database this is the grants for sequences the first pass created, but a
+            // genuinely non-convergent apply lands here too, and labelling that as routine
+            // settling would explain away the one failure this pass exists to surface.
+            info(pass > 1
+              ? `settling pass — ${classified.executable.length} statement(s) still differing after the first pass:`
+              : `state plan — ${classified.executable.length} statement(s):`);
             const { drops, narrowings } = classifyDestructive(classified.executable);
             if (drops.length + narrowings.length > 0) {
               warn(`${drops.length + narrowings.length} DESTRUCTIVE — ${drops.length} drop(s), ${narrowings.length} narrowing type change(s). Dev sync runs them; protected stages gate them (db:plan → db:apply).`);

package/src/cli/db-build.ts

@@ -168,7 +168,17 @@ export async function buildIntoDatabase(
     //
     // Provenance is recorded by this pass, so executeSync's own reconcile below sees the
     // functions already managed and unchanged, and plans nothing for them.
-    const declaredFunctions = (options.declared ?? []).filter((o) => o.kind === 'function');
+    // …and only the functions that CAN go first. A function's return and argument types are
+    // resolved by PostgreSQL when the function is created, and `check_function_bodies` does not
+    // reach them — it relaxes the BODY, which is why a body reading a not-yet-created table is
+    // fine here and `RETURNS SETOF stats_view.x_row` is not. A function whose SIGNATURE names a
+    // relation the declared state has not built yet stays behind and is created by the sync
+    // pass below, after state, in the compiler's dependency order. Measured on a consumer's
+    // declared state: 20 such pairs, `type "…_row" does not exist`, from-scratch only. Their
+    // explicit `dependsOn` could not have helped — this pass dropped the view from the wave, so
+    // no edge could order it back in.
+    const declaredFunctions = (options.declared ?? [])
+      .filter((o) => o.kind === 'function' && !o.signatureDeps?.length);
     if (declaredFunctions.length > 0) {
       await runner('SET check_function_bodies = off');
       try {
@@ -183,34 +193,16 @@ export async function buildIntoDatabase(
         await runner('RESET check_function_bodies');
       }
     }
-    let run = await executeSync(runner, session, models, {
+    // A12's second pass used to live HERE, and that is exactly why `db:sync` never settled: the
+    // from-scratch build got it and the verb an operator runs did not. `executeSync` owns it now
+    // (see its own comment for the sequence-behind-a-serial-column cause), so every caller
+    // settles and none has to know.
+    const run = await executeSync(runner, session, models, {
       declared: options.declared,
       sequences: options.sequences,
       actor: options.actor ?? 'db-build',
       gitRef: options.gitRef ?? null,
     });
-    // A12 — THE SECOND PASS, and it is inherent to building from nothing rather than a patch
-    // over one bug. `executeSync` is a single diff-and-verify: it reads the live authz contract,
-    // computes the delta, applies it. On a FROM-SCRATCH build some objects the authz layer must
-    // grant on do not exist at read time — most sharply the sequence behind a serial column,
-    // which our own CREATE TABLE makes moments later. So the first pass cannot see it, the
-    // sequence inheritance rule (A6) has nothing to grant on, and the build lands with a role
-    // that may INSERT into a table but cannot draw its sequence value.
-    //
-    // Caught by the round-trip oracle (B7), not by A6's own tests: the rule converges perfectly
-    // against an EXISTING database, which is what those tests exercise.
-    //
-    // Bounded at exactly one extra pass. The second read sees everything the first one created,
-    // so a third could only differ if the apply were non-convergent — and that is a real failure
-    // the `converged` bar must report, never something to loop away.
-    if (!run.converged) {
-      run = await executeSync(runner, session, models, {
-        declared: options.declared,
-        sequences: options.sequences,
-        actor: options.actor ?? 'db-build',
-        gitRef: options.gitRef ?? null,
-      });
-    }
     return {
       converged: run.converged,
       fingerprintMatch: run.fingerprintMatch,

package/src/cli/derived-apply.ts

@@ -487,6 +487,14 @@ export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[],
   // REVOKE/GRANT — no provenance to record (ACLs are not in any hash).
   for (const r of plan.regrants) statements.push(...r.statements);
 
+  // NOTE — a `remove` entry that is also a migration's TARGET is CORRECT, not a contradiction.
+  // A legacy-keyed function the source has removed migrates onto its signature identity and is
+  // then dropped through it: re-key, drop the object, delete the row. That is the documented path
+  // (the pre-pass reads the LIVE catalog precisely so a removed function drops instead of reading
+  // as unmanaged) and it converges. A guard here refusing that overlap was tried and reverted —
+  // it turned a right answer into a failed apply, and on `db:sync` it threw after the state layer
+  // had already committed. Pinned by "a removed legacy function renders as migrate-then-remove"
+  // in __tests__/cli/derived-apply.test.ts.
   return { statements, record, remove, migrate: [...plan.migrations] };
 }
 
@@ -514,7 +522,17 @@ ON CONFLICT (identity) DO UPDATE SET src_hash = EXCLUDED.src_hash, def_hash = EX
  *  provenance. See the ORDER MATTERS comment in db-reconcile.ts.
  *
  *  Both branches are mutually exclusive under one snapshot, and an unreferenced data-modifying CTE
- *  still executes exactly once — verified against PostgreSQL 16. */
+ *  still executes exactly once. All three branches (target free / target occupied / nothing to
+ *  migrate) run against a real database in __tests__/integration/provenance-migrate.test.ts.
+ *
+ *  A KIND GUARD WAS TRIED HERE AND REVERTED. It refused the DELETE when the two rows' kinds
+ *  differed, on the theory that a `defineSql` domain and a function can share a name and the
+ *  DELETE would then orphan one of them. The occupied-target branch IS reachable — the ops-Lambda
+ *  apply takes no mutation lease, so a second writer can occupy the target between plan and
+ *  statement — but in that reachable state the two rows are the SAME object: a pre-`kind`-column
+ *  legacy row (kind NULL) and the row the other apply just wrote. Measured on PostgreSQL 16: the
+ *  guard aborted the apply and left two rows, where this statement converges to one. It was
+ *  negative value on precisely the upgrade path it would have shipped to. */
 export function renderProvenanceMigrate(from: string, to: string): string {
   const fromLit = escapeLiteral(from);
   const toLit = escapeLiteral(to);

package/src/cli/derived-compile.ts

@@ -377,6 +377,57 @@ export function compileDerived(models: readonly ModelDescriptor[], derived: read
   const declaredIdentities = (refs: readonly DependsOnRef[]): string[] =>
     [...new Set(refs.map((r) => ('table' in r ? `${r.schema}.${r.table}` : derivedIdentity(r))))].sort();
 
+  // Every RELATION the declared state creates — the tables, views and matviews a function's
+  // signature could name. A function's return and argument types are resolved by PostgreSQL
+  // when the function is created, so `db:build`'s functions-ahead-of-state pass has to know
+  // which functions cannot go first. See SourceObject.signatureDeps.
+  const relationIdentity = (ref: SetofReturn['setof']): string =>
+    'table' in ref ? `${ref.schema}.${ref.table}` : derivedIdentity(ref);
+  const relationIdentities = new Map<string, string>(
+    [
+      ...models.map((m) => `${m.schema}.${m.table}`),
+      ...derived
+        .filter((d) => d.kind === 'view' || d.kind === 'materialized view')
+        .map((d) => derivedIdentity(d)),
+    ].map((id) => [id.toLowerCase(), id]),
+  );
+
+  /**
+   * A type name as written in a signature → the relation identity it names, if it names one.
+   *
+   * The quotes come off, and that is not cosmetic: `db:pull` writes the return type as
+   * `pg_get_function_result` spells it, and PostgreSQL quotes any identifier that needs it
+   * (mixed case, a reserved word, anything non-word). A pulled `SETOF "Stats_View"."x_row"`
+   * that read as no relation at all would go back into the ahead-of-state wave and fail exactly
+   * as before, silently.
+   */
+  const relationNamed = (type: string): string | null => {
+    const bare = type
+      .trim().replace(/^setof\s+/i, '').replace(/(\s*\[\s*\])+$/, '')
+      .split('.').map((part) => part.trim().replace(/^"(.*)"$/s, '$1')).join('.');
+    if (!bare) return null;
+    // A quoted identifier is case-SENSITIVE and an unquoted one folds to lower — but the
+    // declared names this compares against are the plain lowercase ones the model accepts,
+    // so folding both sides is right here and a quoted mixed-case name simply matches nothing.
+    const key = bare.toLowerCase();
+    return relationIdentities.get(key.includes('.') ? key : `public.${key}`) ?? null;
+  };
+
+  const signatureDeps = (fn: FunctionDescriptor): string[] => {
+    const out = new Set<string>();
+    // `setof(ref)` is the typed spelling — the ref IS a relation descriptor, so it always counts.
+    if (typeof fn.returns !== 'string') out.add(relationIdentity(fn.returns.setof));
+    else {
+      const named = relationNamed(fn.returns);
+      if (named) out.add(named);
+    }
+    for (const a of fn.args) {
+      const named = relationNamed(a.type);
+      if (named) out.add(named);
+    }
+    return [...out].sort();
+  };
+
   for (const d of derived) {
     const identity = derivedIdentity(d);
     switch (d.kind) {
@@ -398,7 +449,14 @@ export function compileDerived(models: readonly ModelDescriptor[], derived: read
         // The pin rides STRUCTURALLY as well as inside `sql`, so the differ can compare it
         // against the live catalog directly instead of only against a recorded hash. It is not
         // in the hash (it is already inside `sql`), so carrying it moves nobody's fingerprint.
-        nodes.push({ identity, deps: [...depIdentities(d.dependsOn), ...setofDep], build: make('function', d.name, sql, attachments, { identity, ...(d.owner ? { owner: d.owner } : {}), ...(d.searchPath !== undefined ? { searchPath: d.searchPath } : {}) }) });
+        // The signature is an ORDERING edge as well as a record. `setofDep` covers the typed
+        // `setof(ref)` spelling only; a return or argument type written as a plain string is
+        // the shape `db:pull` renders, and it carries no `dependsOn` of its own — so without
+        // this the function and its view order by identity sort, and whether the build works
+        // comes down to which name happens to sort first.
+        const sigDeps = signatureDeps(d);
+        const sigEdges = sigDeps.filter((id) => identities.has(id));
+        nodes.push({ identity, deps: [...depIdentities(d.dependsOn), ...setofDep, ...sigEdges], build: make('function', d.name, sql, attachments, { identity, ...(sigDeps.length ? { signatureDeps: sigDeps } : {}), ...(d.owner ? { owner: d.owner } : {}), ...(d.searchPath !== undefined ? { searchPath: d.searchPath } : {}) }) });
         break;
       }
       case 'sql': {

package/src/cli/derived-plan.ts

@@ -177,6 +177,18 @@ export function planReconcile(
   // two objects — those baseline honestly), a row a live NON-function already owns (a view
   // and a function can share `schema.name`), and a 'sql'-kind row (its identity is its
   // declared name, not a catalog signature).
+  //
+  // DELIBERATELY NOT SKIPPED: a legacy identity the SOURCE also claims with a different object —
+  // a `defineSql` domain named `pmo_label` alongside a function whose legacy identity is
+  // `public.pmo_label`. The kind read below is the PROVENANCE row's, never the source's, and that
+  // is the intent. Types and functions live in different PostgreSQL catalogs, so both objects are
+  // legal; the collision exists only while the function's row is under-keyed. Migrating is what
+  // VACATES the bare name for the object that legitimately owns it — the run converges in one
+  // apply and the next is a clean no-op (pinned by __tests__/integration/provenance-migrate.test.ts).
+  // Skipping instead would keep the collision and let the domain's upsert overwrite the function's
+  // row; refusing would block a state that is legal, self-healing, and ambiguous for exactly one
+  // apply. Adjudicated 2026-08-12 (issue G7). What this rests on is the caller's
+  // migrate-before-record ordering — see the ORDER MATTERS comment in db-reconcile.ts.
   const liveFnByLegacy = new Map<string, LiveObject[]>();
   for (const o of live.objects) {
     if (o.kind !== 'function') continue;

package/src/cli/derived-source.ts

@@ -96,6 +96,26 @@ export interface SourceObject {
    * "declared, then verified". Absent on kinds whose live edges pg_depend can't see.
    */
   declaredDeps?: string[];
+  /**
+   * kind 'function' only: the relations this function's SIGNATURE names — a `setof(ref)`
+   * return, or an argument/return type spelled as a declared table, view or matview.
+   *
+   * Distinct from `dependsOn`, and the distinction is load-bearing for the from-scratch build.
+   * A body reference is a FORWARD reference the build can defer (`check_function_bodies = off`
+   * is exactly that escape), so a function whose body reads a not-yet-created table still
+   * creates. A SIGNATURE reference is not deferrable: PostgreSQL resolves the return and
+   * argument types when the function is created, so `RETURNS SETOF stats_view.x_row` needs
+   * that view to exist already. `db:build` runs functions ahead of state (an RLS policy's
+   * predicate must resolve the function it calls) and uses this to hold back the ones that
+   * cannot go first; the compiler also orders the function after them.
+   *
+   * RELATIONS only — tables, views, matviews. A signature naming a declared ENUM, domain or
+   * composite type has the same problem and is NOT covered here, so it still fails in the
+   * ahead-of-state pass. Absent/empty means "names no declared relation", never "is safe".
+   *
+   * Not in the hash — it is derived from `sql`, so carrying it moves no fingerprint.
+   */
+  signatureDeps?: string[];
 }
 
 /** The provenance marker descriptor-compiled objects carry in `file` — the compiler

package/src/cli/stage-backup.ts

@@ -0,0 +1,229 @@
+/**
+ * The fingerprint sandwich around a stage backup — ONE implementation, three callers.
+ *
+ * A `db:backup` artifact carries a live base-schema fingerprint in its `.meta.json`, and the
+ * destructive-apply gate compares it against `plan.from`. That comparison is only meaningful if the
+ * fingerprint describes the schema the dump ACTUALLY holds. A dump taken across a concurrent
+ * migration holds a schema matching NEITHER endpoint, so its stamped fingerprint is a lie the gate
+ * would later trust. The sandwich reads the schema before the dump and again after it, and keeps
+ * the artifact only if the two agree.
+ *
+ * WHY THIS LIVES IN THE CLI: it used to run inside the task image, which imported
+ * `@everystack/cli/apply` to do it. The image is published and digest-pinned, so that froze a copy
+ * of the very CLI internals the gate depends on while the operator's checkout kept moving — a
+ * silent version skew on a safety-critical input. Here it runs from the operator's own checkout,
+ * the same code `db:apply` uses, so the two can never disagree about what a fingerprint means.
+ *
+ * WHY IT IS SHARED: `fingerprint` is a REQUIRED field on the backup job. Three commands dispatch
+ * backups (db:backup, db:fork, db:swap --snapshot logical), and when the field was added to one of
+ * them the other two silently broke. One implementation, one contract.
+ *
+ * The dispatch/poll/retract wiring is dependency-injected so the whole decision table is testable
+ * without AWS.
+ */
+
+import { invokeAction, lambdaSessionRunner } from './aws.js';
+import { pollTaskUntilStopped } from './task-poll.js';
+
+/** The verdict on a completed dump's fingerprint pair. Pure — the heart of the sandwich. */
+export type SandwichVerdict = { ok: true } | { ok: false; reason: string };
+
+/**
+ * Did the schema hold still across the dump window?
+ *
+ * Agreement proves no DDL landed ANYWHERE between the two reads, so the fingerprint genuinely
+ * describes the dump's schema. Disagreement means the artifact is unusable as a safety net —
+ * better a refused backup than a false one.
+ */
+export function judgeSandwich(fpBefore: string, fpAfter: string): SandwichVerdict {
+  if (fpBefore === fpAfter) return { ok: true };
+  return {
+    ok: false,
+    reason:
+      `the schema changed during the dump (${fpBefore.slice(0, 12)} → ${fpAfter.slice(0, 12)}), `
+      + 'so the backup spans a migration and its fingerprint cannot be proven. Re-run when no migration is concurrent.',
+  };
+}
+
+export interface StageBackupDeps {
+  /** Read the live base-schema fingerprint. Called twice, bracketing the dump. */
+  readFingerprint: () => Promise<string>;
+  /** Dispatch `db:backup` with the operator-computed fingerprint. */
+  dispatch: (fingerprint: string) => Promise<{ runId: string; taskArn: string; id: string; key: string; warning?: string }>;
+  /**
+   * Wait for the task to stop; resolve ok, or a human reason it did not.
+   *
+   * `stampedFingerprint` is what the task reported writing into the artifact's `.meta.json`. It is
+   * the evidence the image honored the job — see the skew check in runStageBackup.
+   */
+  awaitTask: (ids: { runId: string; taskArn: string; id: string }) => Promise<{ ok: true; bytes?: number; stampedFingerprint?: string } | { ok: false; reason: string }>;
+  /** Delete a retracted artifact (the ops Lambda's db:backup:retract). */
+  retract: (key: string) => Promise<void>;
+  /** Progress output. Optional so tests stay quiet. */
+  onStep?: (message: string) => void;
+}
+
+export type StageBackupResult =
+  | { ok: true; id: string; key: string; bytes?: number; fingerprint: string; warning?: string }
+  | { ok: false; reason: string; retracted?: boolean; orphanKey?: string };
+
+/**
+ * Take a stage backup whose fingerprint is PROVEN stable, or refuse.
+ *
+ * Never throws for an expected failure — every outcome is a verdict the caller renders, so the
+ * three commands can word their own consequences ("the swap was NOT applied", "the fork stopped")
+ * without re-deriving the logic.
+ */
+export async function runStageBackup(deps: StageBackupDeps): Promise<StageBackupResult> {
+  const step = deps.onStep ?? (() => {});
+
+  step('Reading the live schema fingerprint (before the dump)...');
+  let fpBefore: string;
+  try {
+    fpBefore = await deps.readFingerprint();
+  } catch (err: any) {
+    // Refuse BEFORE dispatching: a dump whose fingerprint cannot be proven is not a safety net, and
+    // taking one anyway would burn the dump window and still leave nothing trustworthy.
+    return { ok: false, reason: `the schema fingerprint could not be read, so no backup was dispatched: ${err?.message ?? String(err)}` };
+  }
+
+  let dispatched: { runId: string; taskArn: string; id: string; key: string; warning?: string };
+  try {
+    dispatched = await deps.dispatch(fpBefore);
+  } catch (err: any) {
+    return { ok: false, reason: `the backup would not dispatch: ${err?.message ?? String(err)}` };
+  }
+
+  const finished = await deps.awaitTask(dispatched);
+  if (!finished.ok) return { ok: false, reason: finished.reason };
+
+  // Did the image actually USE the fingerprint we sent?
+  //
+  // This is the version-skew guard, and it deliberately does not rely on the image cooperating. An
+  // older task image ignores the job's `fingerprint` field entirely and computes its own, stamping
+  // the manifest with a value this CLI never produced — the exact stale-internals problem the
+  // operator-side move exists to remove, arriving through a pinned digest nobody re-published. A
+  // protocol handshake cannot catch that, because an old image does not know to check it. Comparing
+  // what came back against what we sent works against ANY image, old or new.
+  if (finished.stampedFingerprint !== undefined && finished.stampedFingerprint !== fpBefore) {
+    step('Retracting the backup (the task stamped a fingerprint we did not send)...');
+    const mismatch =
+      `the task stamped fingerprint ${finished.stampedFingerprint.slice(0, 12)} but the operator sent `
+      + `${fpBefore.slice(0, 12)} — the task image computed its own instead of using the job's, which means it `
+      + 'predates the operator-side fingerprint contract. Re-publish the Task image (or pin a newer digest).';
+    try {
+      await deps.retract(dispatched.key);
+      return { ok: false, reason: `${mismatch} Backup ${dispatched.id} was retracted.`, retracted: true };
+    } catch (err: any) {
+      return {
+        ok: false,
+        reason: `${mismatch} Backup ${dispatched.id} could ALSO not be retracted (${err?.message ?? String(err)}) — delete it by hand.`,
+        retracted: false,
+        orphanKey: dispatched.key,
+      };
+    }
+  }
+
+  step('Re-reading the schema fingerprint (after the dump)...');
+  let fpAfter: string;
+  try {
+    fpAfter = await deps.readFingerprint();
+  } catch (err: any) {
+    // The dump exists but is unproven. Do NOT retract — an unreadable fingerprint is not evidence
+    // the schema moved, and silently destroying a good backup is the worse error.
+    return {
+      ok: false,
+      reason: `the dump finished but the schema fingerprint could not be re-read (${err?.message ?? String(err)}), so backup ${dispatched.id} is NOT proven stable. Verify no migration ran during the dump, or re-run.`,
+      orphanKey: dispatched.key,
+    };
+  }
+
+  const verdict = judgeSandwich(fpBefore, fpAfter);
+  if (verdict.ok) {
+    // A task that reported no fingerprint at all is not the skew case above — the result-ledger
+    // write is explicitly best-effort, so a blip there loses the whole result row. Failing the
+    // backup for that would turn a cosmetic outage into a lost safety net, so say it and continue.
+    const unverified = finished.stampedFingerprint === undefined
+      ? 'the task did not report the fingerprint it stamped, so the artifact could not be verified against what the operator sent (the result-ledger write is best-effort)'
+      : undefined;
+    const warning = [dispatched.warning, unverified].filter(Boolean).join('; ') || undefined;
+    return { ok: true, id: dispatched.id, key: dispatched.key, bytes: finished.bytes, fingerprint: fpBefore, warning };
+  }
+
+  step('Retracting the backup (its fingerprint cannot be proven)...');
+  try {
+    await deps.retract(dispatched.key);
+    return { ok: false, reason: `${verdict.reason} Backup ${dispatched.id} was retracted.`, retracted: true };
+  } catch (err: any) {
+    // The artifact outlived the failure. Say so loudly with the key — an unproven backup left in
+    // the bucket is exactly what the destructive-apply gate must never pick up.
+    return {
+      ok: false,
+      reason: `${verdict.reason} Backup ${dispatched.id} could ALSO not be retracted (${err?.message ?? String(err)}) — delete it by hand so the destructive-apply gate never trusts it.`,
+      retracted: false,
+      orphanKey: dispatched.key,
+    };
+  }
+}
+
+/**
+ * Bind the sandwich to a real stage: the ops Lambda supplies the session the fingerprint is read
+ * over, dispatches the task, reports status, and performs the retraction — so the operator never
+ * holds a database URL or an S3 credential for any of it.
+ *
+ * The ONE place the wiring is written. A caller that hand-rolled this is how `fingerprint` became
+ * required in db:backup while db:fork and db:swap kept dispatching without it.
+ */
+export function stageBackupDeps(
+  config: { region: string },
+  opsFn: string,
+  stage: string | undefined,
+  hooks: { onStep?: (message: string) => void; onDispatch?: (d: { runId: string; taskArn: string; id: string; warning?: string }) => void } = {},
+): StageBackupDeps {
+  return {
+    // BOTH ends of the sandwich read over this ONE closure, so they cannot land on different lanes.
+    // That matters: a before-read over a direct session and an after-read over the two-invoke
+    // ops-Lambda blend could manufacture a false mismatch — or, worse, a false match. The symmetry
+    // is structural here rather than asserted; if a caller ever needs to override one end, it has to
+    // override both.
+    readFingerprint: async () => {
+      // The SAME helper db:apply's concurrency lock uses — that shared definition is the point.
+      const { liveBaseFingerprint } = await import('./apply-execute.js');
+      return (await liveBaseFingerprint(lambdaSessionRunner(config.region, opsFn))).hash;
+    },
+    dispatch: async (fingerprint) => {
+      const dispatched: any = await invokeAction(config.region, opsFn, 'db:backup', {
+        stage, actor: process.env.USER ?? null, fingerprint,
+      });
+      if (dispatched?.error) throw new Error(dispatched.error);
+      hooks.onDispatch?.(dispatched);
+      return dispatched;
+    },
+    awaitTask: async (ids) => {
+      const poll = await pollTaskUntilStopped(config.region, opsFn, { runId: ids.runId, taskArn: ids.taskArn });
+      if (poll.outcome === 'timeout') {
+        return { ok: false, reason: `the dump did not finish in time (last status: ${poll.lastStatus}). Run id ${ids.runId} — reconcile via ECS / everystack.task_log.` };
+      }
+      if (poll.outcome === 'error') {
+        return { ok: false, reason: `the task status could not be read (${poll.status.error}). The dump may still be running — reconcile run id ${ids.runId}.` };
+      }
+      if (poll.status.exitCode !== 0) {
+        return { ok: false, reason: `the dump exited ${poll.status.exitCode ?? 'unknown'}${poll.status.stoppedReason ? ` — ${poll.status.stoppedReason}` : ''}. Read the task logs (CloudWatch).` };
+      }
+      return {
+        ok: true,
+        bytes: poll.status.result?.bytes as number | undefined,
+        // What the task says it wrote into the artifact's .meta.json — the skew evidence.
+        stampedFingerprint: poll.status.result?.fingerprint as string | undefined,
+      };
+    },
+    retract: async (key) => {
+      // `stage` scopes what the action is willing to delete — it refuses any key outside this
+      // stage's backup prefix, so a retraction cannot reach an export artifact or a restore intent.
+      const res: any = await invokeAction(config.region, opsFn, 'db:backup:retract', { key, stage });
+      if (res?.error) throw new Error(res.error);
+      if (!res?.retracted) throw new Error(`the ops function did not confirm the retraction (returned ${JSON.stringify(res)})`);
+    },
+    onStep: hooks.onStep,
+  };
+}