@everystack/cli 0.4.36 → 0.4.38

package/bin/everystack.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * The `everystack` entry point.
+ *
+ * This package ships TypeScript source deliberately — every `exports` target is a
+ * `./src/*.ts` file — so the CLI needs a TypeScript loader at runtime. It used to get one
+ * from `#!/usr/bin/env tsx` on `src/cli/index.ts`, which cannot work once the package is
+ * installed: `env` searches the CONSUMER's PATH, and tsx is a dependency of
+ * @everystack/cli, so under pnpm's isolated layout it lives in this package's own
+ * node_modules and is never on that PATH. `everystack --help` died with
+ * "env: tsx: No such file or directory"; only `pnpm exec everystack` worked, because that
+ * puts the local .bin on PATH first.
+ *
+ * So: boot under plain `node` — always present, it is what runs npm — and find tsx by
+ * MODULE RESOLUTION from this file rather than by PATH lookup.
+ *
+ * The loader is installed by re-executing node with `--import`, not by calling tsx's
+ * register() in-process. register() followed by `import()` of the TypeScript entry makes
+ * the entry load through a require(esm) path and Node rejects it with
+ * ERR_REQUIRE_CYCLE_MODULE. `--import` installs the hooks before any module graph exists,
+ * which is the only ordering that works. The extra process is the price of shipping
+ * source, and it is paid once per invocation.
+ */
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+let tsx;
+try {
+  tsx = pathToFileURL(require.resolve('tsx')).href;
+} catch {
+  console.error('everystack: could not resolve the "tsx" TypeScript loader from this package.');
+  console.error('This usually means a partial install — try reinstalling @everystack/cli.');
+  process.exit(1);
+}
+
+const entry = fileURLToPath(new URL('../src/cli/index.ts', import.meta.url));
+
+const result = spawnSync(process.execPath, ['--import', tsx, entry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+
+// Re-raise a signal death as a signal death so `everystack … &` + Ctrl-C behaves, and
+// otherwise pass the child's exit code through unchanged — the CLI's non-zero exits are
+// load-bearing (db:check, db:authz:diff and friends are CI gates).
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+} else {
+  process.exit(result.status ?? 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.36",
+  "version": "0.4.38",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -17,6 +17,7 @@
     "access": "public"
   },
   "files": [
+    "bin",
     "src",
     "README.md"
   ],
@@ -91,7 +92,7 @@
     }
   },
   "bin": {
-    "everystack": "./src/cli/index.ts"
+    "everystack": "./bin/everystack.mjs"
   },
   "dependencies": {
     "@aws-sdk/client-cloudfront": "3.1053.0",
@@ -111,7 +112,7 @@
     "@everystack/model": "0.4.5"
   },
   "peerDependencies": {
-    "@everystack/server": ">=0.1.0",
+    "@everystack/server": ">=0.4.0",
     "@aws-sdk/client-cloudwatch": "3.1053.0",
     "@aws-sdk/client-rds": "3.1053.0",
     "@aws-sdk/s3-request-presigner": "3.1053.0",

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

@@ -9,9 +9,20 @@
  * can diff a deployed database against. `pull` is the export + on-ramp; `diff` is the
  * audit and the CI gate (non-zero exit on any drift).
  *
- * Both introspect through the ops Lambda `db:query` action (read-only SQL), the same
- * path security:audit uses. The core (introspect/assemble/diff) is backend-agnostic and
- * pure; only the runner here is AWS-bound.
+ * Two venues, one verdict. The core (introspect/assemble/diff/evaluate) is backend-agnostic
+ * and pure — only the VENUE differs, and both satisfy the same `AuthzVenue` contract, so
+ * every command below runs identical evaluation code either way:
+ *
+ * - **Deployed** (`--stage`, the default): the ops Lambda's `db:query` + `db:authz:probe`
+ *   actions. Credentials never leave AWS.
+ * - **Direct** (`--database-url`, or an inherited ADMIN_DATABASE_URL / DATABASE_URL): a
+ *   postgres.js connection from this process.
+ *
+ * The direct venue is what makes a brownfield authz migration rehearsable. Translating
+ * hand-written RLS into Model abilities is the hardest part of an adoption, and until the
+ * local venue existed it was the ONLY part that required a deployed stage to iterate
+ * against. Every run names its venue, because a security verdict against an unintended
+ * database is worse than no verdict.
  */
 
 import path from 'node:path';
@@ -43,6 +54,7 @@ import { renderContractMarkdown } from '../authz-render.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { resolveModelsPath } from '../models-path.js';
+import { resolveDbSource, connectingVia, createUrlProbeRunner } from '../db-source.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
 import { opsAdviceLines, IAM_ADVICE } from '../ops-advice.js';
@@ -59,20 +71,65 @@ function lambdaRunner(region: string, fn: string): QueryRunner {
   };
 }
 
-async function introspectStage(flags: Record<string, string>): Promise<AuthzContract> {
+/**
+ * Where an authz command runs. Both venues expose the same two capabilities, so the
+ * commands never branch on venue after this point — that is what keeps the local
+ * rehearsal honest: same SQL, same evaluation, same verdict.
+ */
+interface AuthzVenue {
+  /** Read-only introspection. */
+  runner: QueryRunner;
+  /** Self-reverting red-team probe (writes, always rolled back). */
+  probe: (setup: string, read: string) => Promise<any[]>;
+  /** Human-readable venue, printed with every verdict. */
+  label: string;
+  /** Release any connection this venue holds. */
+  end: () => Promise<void>;
+}
+
+/**
+ * Precedence is `resolveDbSource`'s, shared with db:pull / db:generate / db:check:
+ * `--database-url` > explicit `--stage` > ADMIN_DATABASE_URL > DATABASE_URL > default stage.
+ */
+async function resolveVenue(flags: Record<string, string>): Promise<AuthzVenue> {
+  const source = resolveDbSource(flags);
+  if (source.kind === 'url') {
+    step(connectingVia(source));
+    const { runner, probe, end } = await createUrlProbeRunner(source.url);
+    return { runner, probe, end, label: 'direct connection' };
+  }
   step('Resolving deployed config...');
   const config = await resolveConfig(flags.stage);
-  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
-  step('Introspecting authorization (rls + grants + policies + secdef)...');
-  const runner = lambdaRunner(config.region, opsFunction(config));
-  return introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+  const fn = opsFunction(config);
+  info(`Region: ${config.region}, Function: ${fn}`);
+  return {
+    runner: lambdaRunner(config.region, fn),
+    probe: async (setup: string, read: string) => {
+      const result: any = await invokeAction(config.region, fn, 'db:authz:probe', { setup, read });
+      if (result?.error) throw new Error(result.error);
+      return result?.rows ?? [];
+    },
+    label: flags.stage ? `stage ${flags.stage}` : 'deployed stage (.sst/outputs.json)',
+    end: async () => {},
+  };
+}
+
+async function introspectVenue(flags: Record<string, string>): Promise<{ contract: AuthzContract; label: string }> {
+  const venue = await resolveVenue(flags);
+  try {
+    step('Introspecting authorization (rls + grants + policies + secdef)...');
+    return { contract: await introspectContract(venue.runner, contractFunctionRow, FUNCTIONS_SQL), label: venue.label };
+  } finally {
+    await venue.end();
+  }
 }
 
 export async function dbAuthzPullCommand(flags: Record<string, string>): Promise<void> {
   const dir = path.resolve(flags.dir || flags.out || DEFAULT_DIR);
   let contract: AuthzContract;
+  let venueLabel: string;
   try {
-    contract = await introspectStage(flags);
+    ({ contract, label: venueLabel } = await introspectVenue(flags));
   } catch (err: any) {
     fail(err.message);
     for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
@@ -82,7 +139,7 @@ export async function dbAuthzPullCommand(flags: Record<string, string>): Promise
   const files = await writeContract(dir, contract);
   const policies = contract.tables.reduce((n, t) => n + t.policies.length, 0);
   console.log('');
-  success(`Wrote ${files.length} file(s) to ${dir}`);
+  success(`Wrote ${files.length} file(s) to ${dir} (from ${venueLabel})`);
   info(`${contract.tables.length} table(s), ${policies} policy(ies), ${contract.functions.length} SECDEF function(s).`);
   console.log('');
   warn('pull OVERWROTE the committed contract with the live state — `git diff` IS your drift report.');
@@ -97,9 +154,10 @@ export async function dbAuthzDiffCommand(flags: Record<string, string>): Promise
 
   let declared: AuthzContract;
   let live: AuthzContract;
+  let venueLabel: string;
   try {
     declared = await loadContract(dir);
-    live = await introspectStage(flags);
+    ({ contract: live, label: venueLabel } = await introspectVenue(flags));
   } catch (err: any) {
     fail(err.message);
     process.exit(1);
@@ -113,11 +171,11 @@ export async function dbAuthzDiffCommand(flags: Record<string, string>): Promise
   const findings = diffContracts(declared, live);
   console.log('');
   if (findings.length === 0) {
-    success(`db:authz:diff — live database matches the declared contract (${declared.tables.length} tables)`);
+    success(`db:authz:diff — ${venueLabel} matches the declared contract (${declared.tables.length} tables)`);
     process.exit(0);
   }
 
-  fail(`db:authz:diff — ${findings.length} drift finding(s): the live database does NOT match the declared contract`);
+  fail(`db:authz:diff — ${findings.length} drift finding(s): ${venueLabel} does NOT match the declared contract`);
   console.log('');
   for (const f of findings) {
     warn(`[${f.kind}] ${f.subject} — ${f.detail}`);
@@ -163,24 +221,23 @@ export async function dbAuthzTestCommand(flags: Record<string, string>): Promise
 
   let rows: any[];
   let gapRows: any[];
+  let venueLabel: string;
+  let venue: AuthzVenue | undefined;
   try {
-    step('Resolving deployed config...');
-    const config = await resolveConfig(flags.stage);
-    const fn = opsFunction(config);
-    info(`Region: ${config.region}, Function: ${fn}`);
+    venue = await resolveVenue(flags);
+    venueLabel = venue.label;
     step('Red-teaming enforcement (SET ROLE + attempt per role/table/command, rolled back)...');
     const setup = buildProbeSql(probeRoles(contract), contract.tables.map((t) => t.table));
-    const result: any = await invokeAction(config.region, fn, 'db:authz:probe', { setup, read: PROBE_SELECT_SQL });
-    if (result?.error) throw new Error(result.error);
-    rows = result?.rows ?? [];
+    rows = await venue.probe(setup, PROBE_SELECT_SQL);
     step('Checking SECDEF grant-completeness (owner can EXECUTE every helper it calls)...');
-    const gc: any = await invokeAction(config.region, fn, 'db:query', { sql: GRANT_COMPLETENESS_SQL });
-    if (gc?.error) throw new Error(gc.error);
-    gapRows = gc?.rows ?? [];
+    gapRows = await venue.runner(GRANT_COMPLETENESS_SQL);
   } catch (err: any) {
     fail(`db:authz:test failed: ${err.message}`);
-    info('Ensure the stage is deployed with @everystack/server >= the version that adds db:authz:probe.');
+    info('Ensure the stage is deployed with @everystack/server >= the version that adds db:authz:probe,');
+    info('or rehearse locally: db:authz:test --database-url <url>.');
     process.exit(1);
+  } finally {
+    await venue?.end();
   }
 
   const findings = evaluateRedTeam(contract, rows.map(toProbeResult));
@@ -200,10 +257,10 @@ export async function dbAuthzTestCommand(flags: Record<string, string>): Promise
   console.log('');
 
   if (holes.length === 0 && broken.length === 0 && gaps.length === 0) {
-    success(`db:authz:test — enforcement matches the contract (${contract.tables.length} tables probed, default-deny holds, SECDEF grants complete)`);
+    success(`db:authz:test — ${venueLabel} enforces the contract (${contract.tables.length} tables probed, default-deny holds, SECDEF grants complete)`);
     process.exit(0);
   }
-  fail(`db:authz:test — ${holes.length} enforcement hole(s), ${broken.length} broken grant(s), ${gaps.length} SECDEF grant gap(s). The database does not enforce the contract.`);
+  fail(`db:authz:test — ${holes.length} enforcement hole(s), ${broken.length} broken grant(s), ${gaps.length} SECDEF grant gap(s). ${venueLabel} does not enforce the contract.`);
   process.exit(1);
 }
 
@@ -223,6 +280,8 @@ export async function dbAuthzOwnerCommand(flags: Record<string, string>): Promis
   let probes: OwnerProbe[];
   let publicReadTables = new Set<string>();
   let rows: any[];
+  let venueLabel = '';
+  let venue: AuthzVenue | undefined;
   try {
     step(`Loading models from ${modelsPath}...`);
     const models = await loadModels(modelsPath);
@@ -240,20 +299,17 @@ export async function dbAuthzOwnerCommand(flags: Record<string, string>): Promis
       success('db:authz:owner — no owner-scoped models (no `can({ owner })`); nothing to probe.');
       process.exit(0);
     }
-    step('Resolving deployed config...');
-    const config = await resolveConfig(flags.stage);
-    const fn = opsFunction(config);
-    info(`Region: ${config.region}, Function: ${fn}`);
+    venue = await resolveVenue(flags);
+    venueLabel = venue.label;
     step('Red-teaming owner isolation (two JWT identities per table, rolled back)...');
-    const result: any = await invokeAction(config.region, fn, 'db:authz:probe', {
-      setup: buildOwnerProbeSql(probes), read: OWNER_PROBE_SELECT_SQL,
-    });
-    if (result?.error) throw new Error(result.error);
-    rows = result?.rows ?? [];
+    rows = await venue.probe(buildOwnerProbeSql(probes), OWNER_PROBE_SELECT_SQL);
   } catch (err: any) {
     fail(`db:authz:owner failed: ${err.message}`);
-    info('Ensure the stage is deployed with @everystack/server >= the version that adds db:authz:probe.');
+    info('Ensure the stage is deployed with @everystack/server >= the version that adds db:authz:probe,');
+    info('or rehearse locally: db:authz:owner --database-url <url>.');
     process.exit(1);
+  } finally {
+    await venue?.end();
   }
 
   const findings = evaluateOwnerProbe(rows.map(toOwnerProbeResult), publicReadTables);
@@ -270,9 +326,9 @@ export async function dbAuthzOwnerCommand(flags: Record<string, string>): Promis
   console.log('');
 
   if (leaks.length === 0 && vacuous.length === 0) {
-    success(`db:authz:owner — owner isolation holds (${probes.length} table(s) probed${unprobed.length ? `, ${unprobed.length} unprobed` : ''}).`);
+    success(`db:authz:owner — owner isolation holds on ${venueLabel} (${probes.length} table(s) probed${unprobed.length ? `, ${unprobed.length} unprobed` : ''}).`);
     process.exit(0);
   }
-  fail(`db:authz:owner — ${leaks.length} IDOR leak(s), ${vacuous.length} vacuous policy(ies). One user can reach another's rows.`);
+  fail(`db:authz:owner — ${leaks.length} IDOR leak(s), ${vacuous.length} vacuous policy(ies) on ${venueLabel}. One user can reach another's rows.`);
   process.exit(1);
 }

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

@@ -37,9 +37,12 @@ import { formatBytes } from '../bundle-weight.js';
 import { rewriteStatementLine, opensCopyData, closesCopyData } from '../schema-rewrite.js';
 import { resolveOperatorUrlViaStage } from '../direct-venue.js';
 import { withMutationLease, MutationLeaseError } from '../mutation-lease.js';
-import { resolveConfig, opsFunction } from '../config.js';
-import { invokeAction, presignGet } from '../aws.js';
-import { keyForArtifactId, metaKey } from '../backup.js';
+import { resolveConfig, opsFunction, type CliConfig } from '../config.js';
+import { invokeAction, presignGet, createRdsSnapshot, describeRdsSnapshots } from '../aws.js';
+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 { pgEnvFromUrl, pgKeepaliveConninfo } from './db.js';
 import { step, success, fail, warn, info } from '../output.js';
 
@@ -264,11 +267,29 @@ async function restoreIntoIncoming(
     // never argv (libpq also REJECTS non-keyword URI params like the `search_path` the operator URL
     // bakes in — fine for postgres.js, fatal for a libpq URI). `-d` carries ONLY keepalives, which
     // have no PG* env equivalent and are what keep this connection from dying in the index phase.
+    //
+    // psql reads the file from STDIN (`-f -`) rather than opening it itself, purely so the restore
+    // knows its own write position. That position is the fact the heartbeat was missing: a server
+    // parked in `Client/ClientRead` is a STALL when bytes remain unsent and the successful TAIL when
+    // they do not, and those two used to print the same line. `-f -` keeps psql's `psql:<stdin>:N:`
+    // error prefixes, so the line number of a failing statement survives the change (verified
+    // against psql 16).
     io.log(`restore phase B: psql streaming ${formatBytes(written)} to the target — heartbeat every 10s.`);
-    const psql = spawn('psql', ['-d', pgKeepaliveConninfo(), '-v', 'ON_ERROR_STOP=1', '-f', sqlPath], {
-      stdio: ['ignore', 'ignore', 'pipe'],
+    const psql = spawn('psql', ['-d', pgKeepaliveConninfo(), '-v', 'ON_ERROR_STOP=1', '-f', '-'], {
+      stdio: ['pipe', 'ignore', 'pipe'],
       env: { ...process.env, ...pgEnvFromUrl(url) },
     });
+    let fedBytes = 0;
+    let feedDone = false;
+    // A psql that exits early (ON_ERROR_STOP) makes this pipeline fail with EPIPE. That is a
+    // DOWNSTREAM symptom — psql's own exit code and stderr are the authority on what went wrong, and
+    // a previous version of this code mistook the EPIPE for the cause and chased the wrong bug for
+    // two sessions. So the feed's error is swallowed here and psql's exit decides.
+    const feeding = pipeline(
+      fs.createReadStream(sqlPath),
+      countingTap((n) => { fedBytes = n; }),
+      psql.stdin!,
+    ).then(() => { feedDone = true; }).catch(() => { /* psql's exit is the authority */ });
     let pErr = '';
     psql.stderr.on('data', (d) => {
       const s = d.toString();
@@ -285,6 +306,9 @@ async function restoreIntoIncoming(
       incoming,
       log: io.log,
       warn: io.warn,
+      // The client half of the picture. Without it the heartbeat cried "deadlock signature" over the
+      // last poll of a run that had landed every row and was about to succeed.
+      clientFeed: () => ({ fedBytes, totalBytes: written, done: feedDone }),
       onSample: (sample) => {
         if (sample.state === null) deadBackendPolls += 1;
         else deadBackendPolls = 0;
@@ -319,8 +343,11 @@ async function restoreIntoIncoming(
       });
     } finally {
       await stopHeartbeat();
+      // The feed is already finished on the success path; on a failure path it is rejecting with
+      // EPIPE. Either way, await it so no stream work outlives the phase.
+      await feeding;
     }
-    io.log(`restore phase B done in ${humanElapsed(Date.now() - bStart)} (restore total ${humanElapsed(Date.now() - t0)}).`);
+    io.log(`restore phase B done in ${humanElapsed(Date.now() - bStart)} (restore total ${humanElapsed(Date.now() - t0)}); fed ${formatBytes(fedBytes)} of ${formatBytes(written)}.`);
   } finally {
     await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
   }
@@ -407,6 +434,60 @@ async function resolveSwapArtifact(
   return fetchArtifactFromS3(from, stage, fingerprintFlag);
 }
 
+/**
+ * Take (or account for) the pre-swap rollback point, and do not return until it EXISTS.
+ *
+ * Every branch here either produces a confirmed rollback point or throws — and a throw at this point
+ * means executeSwap never reaches the restore, so live is untouched. That property is the entire
+ * reason this is not a fire-and-forget dispatch any more.
+ */
+async function takePreSwapSnapshot(
+  plan: Exclude<ReturnType<typeof decideSnapshotMode>, { mode: 'refuse' }>,
+  ctx: { stage?: string; region?: string; opsFn?: string },
+): Promise<void> {
+  if (plan.mode === 'attested') {
+    info(`pre-swap rollback point: ${plan.ref} (attested via --snapshot-ref — no new snapshot taken).`);
+    return;
+  }
+
+  if (plan.mode === 'none') {
+    warn('NO pre-swap snapshot (--snapshot none). If this swap lands bad data there is no rollback point — the retiring schema is dropped once verify passes.');
+    return;
+  }
+
+  if (plan.mode === 'physical') {
+    step(`Snapshotting the instance before the swap (RDS physical snapshot of ${plan.instanceId})...`);
+    const snapshotId = rdsSnapshotIdentifier(`${ctx.stage ?? 'swap'}-swap`, utcStamp(new Date()));
+    const region = ctx.region!;
+    const { id } = await confirmPhysicalSnapshot({
+      create: (sid) => createRdsSnapshot(region, plan.instanceId, sid),
+      describe: () => describeRdsSnapshots(region, plan.instanceId),
+      log: (m) => info(m),
+      sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+      now: () => Date.now(),
+    }, { instanceId: plan.instanceId, snapshotId });
+    info(`rollback point CONFIRMED: RDS snapshot ${id} is available — restore the instance from it if this swap goes wrong.`);
+    return;
+  }
+
+  // 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,
+  });
+  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.`);
+}
+
 export async function dbSwapCommand(flags: Record<string, string>): Promise<void> {
   const schema = flags.schema;
   const from = flags.from;
@@ -445,9 +526,9 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
     process.exit(1);
   }
   let url = urlFlag;
-  let snapshotViaStage = false;
   let region: string | undefined;
   let opsFn: string | undefined;
+  let stageConfig: CliConfig | undefined;
 
   if (stage) {
     if (!direct) {
@@ -459,13 +540,12 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
       process.exit(1);
     }
     try {
-      const config = await resolveConfig(stage);
-      region = config.region;
-      opsFn = opsFunction(config);
+      stageConfig = await resolveConfig(stage);
+      region = stageConfig.region;
+      opsFn = opsFunction(stageConfig);
       step('Resolving the operator connection from the stage (--direct)...');
       const op = await resolveOperatorUrlViaStage(stage);
       url = op.url;
-      snapshotViaStage = true;
       info(`operator credential resolved (${op.source}) — swapping CLI-side, unbounded clock.`);
     } catch (err: any) { fail(err.message); process.exit(1); }
   }
@@ -475,6 +555,29 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
     process.exit(1);
   }
 
+  // THE ROLLBACK POINT. Decided here — before the models load, before the artifact is fetched, and
+  // long before anything is renamed — so a refusal costs nothing but a second.
+  //
+  // This step used to be a `db:backup` the swap did not wait for. The ops action dispatches a Task
+  // and returns, so the swap printed "snapshot on record" and began restoring while the pg_dump was
+  // still running: a consumer measured the restore blocked ~5 minutes on
+  // `Lock/relation HELD BY pid [pg_dump]`, the swap contending with its own backup. And a task that
+  // failed to start left a destructive swap running against a rollback point that did not exist.
+  //
+  // A physical RDS snapshot is now the default where the target is RDS (a control-plane call: no
+  // locks, no buffer-cache read, no client connection), the logical backup is the non-RDS fallback
+  // and is now WAITED ON, and the bare `--database-url` venue refuses rather than warning.
+  const snapshotPlan = decideSnapshotMode({
+    venue: stage ? 'stage' : 'url',
+    instanceId: flags.instance ?? stageConfig?.databaseInstanceId,
+    snapshotRef: flags['snapshot-ref'],
+    requested: flags.snapshot as SnapshotModeRequest | undefined,
+  });
+  if (snapshotPlan.mode === 'refuse') {
+    fail(snapshotPlan.reason);
+    process.exit(1);
+  }
+
   // --rebuild-derived carries a real outage window: the derived layer does not exist between the
   // swap committing and db:reconcile --apply finishing. State it BEFORE the work starts — saying it
   // only afterward tells the operator about an outage they are already in. It is now the OPT-OUT:
@@ -609,14 +712,7 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
             declaredIdentities: declaredDerivedObjects.map((o) => o.identity),
           });
         },
-        snapshot: snapshotViaStage
-          ? async () => {
-              step('Snapshotting the stage before the swap (db:backup)...');
-              const r: any = await invokeAction(region!, opsFn!, 'db:backup', { stage });
-              if (r?.error) throw new Error(`pre-swap snapshot failed, so the swap was NOT applied: ${r.error}`);
-              info(`snapshot on record: ${r?.id ?? 'backup complete'} — restore with db:restore --from ${r?.id ?? '<id>'} --confirm.`);
-            }
-          : async () => { warn('no snapshot taken (direct v1) — take one first: everystack db:backup --database-url … before a production swap.'); },
+        snapshot: () => takePreSwapSnapshot(snapshotPlan, { stage, region, opsFn }),
       }),
     );
 

package/src/cli/db-source.ts

@@ -70,13 +70,10 @@ export interface UrlRunner {
 }
 
 /**
- * A QueryRunner over a direct postgres.js connection. One connection is enough —
- * introspection is a handful of sequential catalog queries.
+ * Load the postgres.js driver, or explain how to get it. Shared by every direct-connection
+ * runner below so the missing-driver instructions can never drift between them.
  */
-export async function createUrlRunner(
-  url: string,
-  load: () => Promise<any> = () => import('postgres'),
-): Promise<UrlRunner> {
+async function loadPostgresDriver(load: () => Promise<any>): Promise<any> {
   let mod: any;
   try {
     mod = await load();
@@ -85,7 +82,18 @@ export async function createUrlRunner(
       'The direct-connection path needs the "postgres" driver. It ships with @everystack/server; in a project without it: pnpm add -D postgres',
     );
   }
-  const postgres = mod.default ?? mod;
+  return mod.default ?? mod;
+}
+
+/**
+ * A QueryRunner over a direct postgres.js connection. One connection is enough —
+ * introspection is a handful of sequential catalog queries.
+ */
+export async function createUrlRunner(
+  url: string,
+  load: () => Promise<any> = () => import('postgres'),
+): Promise<UrlRunner> {
+  const postgres = await loadPostgresDriver(load);
   // max_lifetime: null — the driver's default recycles a connection after a random 30–60
   // minutes, resolving the in-flight query and THEN killing the session. Under reconcile's
   // BEGIN-across-calls transaction that is a silent session swap mid-batch (the reconcile
@@ -114,15 +122,7 @@ export async function createUrlPipelineRunner(
   url: string,
   load: () => Promise<any> = () => import('postgres'),
 ): Promise<UrlPipelineRunner> {
-  let mod: any;
-  try {
-    mod = await load();
-  } catch {
-    throw new Error(
-      'The direct-connection path needs the "postgres" driver. It ships with @everystack/server; in a project without it: pnpm add -D postgres',
-    );
-  }
-  const postgres = mod.default ?? mod;
+  const postgres = await loadPostgresDriver(load);
   const sql = postgres(url, { max: 1, onnotice: () => {}, ...sslDefaults(url) });
   return {
     query: async (query: string) => Array.from(await sql.unsafe(query)),
@@ -132,6 +132,57 @@ export async function createUrlPipelineRunner(
   };
 }
 
+export interface UrlProbeRunner {
+  /** Read-only introspection, for the contract pull/diff. */
+  runner: QueryRunner;
+  /** The self-reverting red-team probe. See `probe` below. */
+  probe: (setup: string, read: string) => Promise<any[]>;
+  /** Close the client so the process can exit cleanly. */
+  end: () => Promise<void>;
+}
+
+/** Thrown to abort the probe transaction; never escapes `probe`. */
+const PROBE_ROLLBACK = Symbol('authz_probe_rollback');
+
+/**
+ * The direct-connection twin of the server's `db:authz:probe` action
+ * (`@everystack/server` plugin.ts) — the local venue for `db:authz:test` / `db:authz:owner`.
+ *
+ * The probe SQL must WRITE to test INSERT/UPDATE/DELETE privileges, so the only thing
+ * standing between a red-team run and a mutated developer database is the rollback. It is
+ * therefore unconditional: the transaction body always throws `PROBE_ROLLBACK` after
+ * reading the outcome rows, so postgres.js aborts it on every path — success included.
+ * There is no code path that commits. `SET ROLE` is transactional (its effect disappears
+ * when the transaction aborts), so the session's role is restored by the same rollback.
+ *
+ * `max: 1` is load-bearing, not tuning: the probe's SET ROLE / savepoint state only makes
+ * sense on the single connection that ran the setup.
+ */
+export async function createUrlProbeRunner(
+  url: string,
+  load: () => Promise<any> = () => import('postgres'),
+): Promise<UrlProbeRunner> {
+  const postgres = await loadPostgresDriver(load);
+  const sql = postgres(url, { max: 1, max_lifetime: null, onnotice: () => {}, ...sslDefaults(url) });
+  return {
+    runner: async (query: string) => Array.from(await sql.unsafe(query)),
+    probe: async (setup: string, read: string) => {
+      let rows: any[] = [];
+      try {
+        await sql.begin(async (tx: any) => {
+          await tx.unsafe(setup);
+          rows = Array.from(await tx.unsafe(read));
+          throw PROBE_ROLLBACK; // discard every probe write — unconditional
+        });
+      } catch (err: unknown) {
+        if (err !== PROBE_ROLLBACK) throw err;
+      }
+      return rows;
+    },
+    end: () => sql.end({ timeout: 5 }),
+  };
+}
+
 /**
  * Managed Postgres (RDS / Supabase / Neon) requires TLS — a direct connection without it
  * is rejected with pg_hba "no encryption". Default `ssl: 'require'` for remote hosts so the

package/src/cli/index.ts

@@ -373,7 +373,7 @@ Usage:
   everystack db:restore        --from <id> [--stage <name>] --confirm  Restore a backup INTO the stage's DB (DESTRUCTIVE)
   everystack db:backup:download <id> [--stage <name>]  Presigned URL to download a backup's dump (valid 1h)
   everystack db:export         --schema <name> [--stage <name> | --database-url <url> [--out <file.dump>]] [--models <barrel>]  Schema-scoped pg_dump artifact, stamped with the DECLARED schema fingerprint (the canonical-sync export; db:swap gates on that stamp). --stage dumps the stage's private DB via the ops Lambda → S3; --database-url (explicit flag, never the env) dumps a reachable DB to a local .dump + .meta.json — the build-locally → publish → swap on-ramp
-  everystack db:swap           --schema <name> --database-url <url> --from <artifact.dump> [--fingerprint <hash>]  Land a schema artifact atomically: fingerprint gate → restore into <schema>_incoming (COPY-safe rewrite) → one txn (drop+rename+recreate app→schema FKs, re-apply authz) → verify → drop retiring. Refresh-free; app.* untouched. DESTRUCTIVE (--stage/--direct ops venue rides stage-write-lanes)
+  everystack db:swap           --schema <name> --from <artifact.dump | artifact-id> [--stage <name> --direct | --database-url <url>] --confirm [--fingerprint <hash>] [--snapshot physical|logical|none] [--snapshot-ref <id>] [--rebuild-derived] [--dump-build <file.json>]  Land a schema artifact atomically: fingerprint gate → pre-flight refusals → CONFIRMED snapshot → restore into <schema>_incoming (COPY-safe rewrite) → build the paired derived layer → one txn (drop+rename+recreate app→schema FKs, re-apply authz + schema USAGE) → assertions → drop retiring. Refresh-free; app.* untouched; the derived layer is never absent. DESTRUCTIVE. The venue is EXPLICIT — DATABASE_URL in the env is refused, and --stage requires --direct (a multi-GB restore exceeds the ops-Lambda 900s clock). The rollback point defaults to a PHYSICAL RDS snapshot on a stage that exposes databaseInstanceId (no locks, no pg_dump contending with the restore) and a WAITED logical db:backup otherwise; a bare --database-url refuses without --snapshot-ref <id> or --snapshot none. docs/schema-swap.md
   everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--schema-out db/schema.generated.ts] [--allow-drops] [--apply] [--dry-run]  Diff models vs the live DB → next migration file, or with --apply execute it directly (one transaction, schema_log recorded, verified by re-diff — no drizzle folder needed; direct connection only; DROPs held back unless --allow-drops). --dry-run prints the edge and writes NOTHING (no migration, no journal entry, no schema refresh) — the preview verb; db:diff computes a models-vs-models edge with no database at all. The resolved --schema-out is recorded in the migration journal: later flag-less runs reuse it (flag > recorded > default), a differing flag updates the record and says so
   everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored); --abilities public-read stamps the common stanza (public read, admin write) uncommented — explicit generated code, never a runtime default. --matviews-as-tables renders every matview as defineMaterializedTable with INTROSPECTED fields (the canonical-sync flip: a pipeline-owned table everystack migrates but never refreshes) — names land in an exported materializedTables array to spread into your models; fields come back nullable/unkeyed (matviews carry no PK/NOT NULL) — tighten on review; add --suggest-keys to probe the LIVE rows for functionally-unique columns (one scan per matview) and surface each as a commented .primaryKey() suggestion. docs/derived-objects.md#flipping-a-matview-to-a-materialized-table---matviews-as-tables
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
@@ -394,10 +394,11 @@ Usage:
   everystack db:template:refresh [--database-url <url>] [--models <barrel>] [--seed "<cmd>"] [--no-seed]  (Re)build the dev template <base>_tpl FROM THE DECLARED STATE (both layers, fingerprint MATCH bar) + seed-as-code (the app's db:seed script, run with DATABASE_URL pointed at the template; --seed overrides). All or nothing: a failed build/seed leaves NO template. Never a data copy
   everystack db:branch         [--list | --drop --confirm | --prune --confirm] [--database-url <url>]  Mint (or find) the current git branch's database from the template (CREATE DATABASE … TEMPLATE — schema, authz, derived layer, and seed rows inherited), print its DATABASE_URL, then db:sync evolves it with the checkout. --list maps every branch DB to its branch; --prune drops the ones whose branch is gone (never guesses: unknown mappings are kept)
   everystack db:fork           --from-stage <src> --stage <target> --confirm [--backup <id>]  Fork one DEPLOYED stage's database into another: back up the source (or reuse --backup <id>), presign the dump (the operator's credentials ARE the cross-stage authorization; expires in 1h), restore into the target via its ops Lambda. Production is never a target (that's db:restore); forking FROM production warns about PII; the branch's schema edge then lands via db:plan → db:apply (descent composes). Teardown: sst remove --stage <target>
-  everystack db:authz:pull     [--stage <name>] [--dir authz]  Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
-  everystack db:authz:diff     [--stage <name>] [--dir authz]  Validate the live DB against the committed contract (non-zero exit on drift)
-  everystack db:authz:test     [--stage <name>] [--dir authz]  Red-team enforcement: SET ROLE + attempt per role/table/command (non-zero exit on a hole)
-  everystack db:authz:owner    [--stage <name>] [--models db/models/index.ts]  Red-team owner isolation: two JWT identities per owner-scoped table — catches IDOR (non-zero exit on a leak)
+  everystack db:authz:pull     [--stage <name> | --database-url <url>] [--dir authz]  Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
+  everystack db:authz:diff     [--stage <name> | --database-url <url>] [--dir authz]  Validate the live DB against the committed contract (non-zero exit on drift)
+  everystack db:authz:test     [--stage <name> | --database-url <url>] [--dir authz]  Red-team enforcement: SET ROLE + attempt per role/table/command (non-zero exit on a hole)
+  everystack db:authz:owner    [--stage <name> | --database-url <url>] [--models db/models/index.ts]  Red-team owner isolation: two JWT identities per owner-scoped table — catches IDOR (non-zero exit on a leak)
+                               All four accept a DIRECT venue (--database-url, or an inherited ADMIN_DATABASE_URL/DATABASE_URL) so a brownfield authz migration can be rehearsed against a local database instead of a deployed stage. Same SQL, same evaluation, same verdict — every run names the venue it judged. The red-team probes WRITE to test INSERT/UPDATE/DELETE privileges and are always rolled back.
   everystack db:authz:report   [--dir authz]  Render the committed contract as a human-readable authorization review (no DB)
   everystack console           --stage <name> [--sandbox]  Interactive REPL on deployed Lambda
   everystack status            [--stage <name>] [--hours <n>]  Platform health: CDN, Lambda, rollup summary

package/src/cli/swap-heartbeat.ts

@@ -78,6 +78,24 @@ export interface HeartbeatSample {
   blockedBy: string | null;
 }
 
+/**
+ * What the CLIENT has sent, to sit alongside what the server reports.
+ *
+ * The server side alone cannot tell a stalled load from a finished one. Both look like
+ * `Client/ClientRead` with flat progress: the server is waiting for the next command. The difference
+ * is whether there is anything left to send, and only the client knows that. Without this the
+ * detector called the deadlock signature on a run that had landed all 5,984,956 rows and was one
+ * second from completing.
+ */
+export interface ClientFeed {
+  /** Bytes handed to psql's stdin so far. */
+  fedBytes: number;
+  /** Bytes the restore has to feed in total (the rewritten SQL file's size). */
+  totalBytes: number;
+  /** The local reader has written everything — nothing more is coming from our side. */
+  done: boolean;
+}
+
 export type Liveness =
   /** Rows or COPY bytes grew since the last poll. */
   | 'progressing'
@@ -85,6 +103,12 @@ export type Liveness =
   | 'blocked'
   /** Flat progress AND the server is waiting on the client: the deadlock signature. */
   | 'client-stall'
+  /**
+   * The client has sent everything and the server is waiting on it. That is not a stall — it is the
+   * tail of a successful load (the final commit, the connection winding down). Distinguishing this
+   * from `client-stall` is the whole reason ClientFeed exists.
+   */
+  | 'finishing'
   /** Connected and working, but nothing measurable moved this poll (DDL, index build). */
   | 'busy'
   /** No psql backend connected — not started yet, or already gone. */
@@ -218,9 +242,14 @@ function movedForward(prev: HeartbeatSample, cur: HeartbeatSample): boolean {
  *   3. no predecessor        → busy (cannot claim progress OR a stall on the first poll)
  *   4. rows/bytes grew       → progressing, EVEN in ClientRead (the healthy high-latency case)
  *   5. schema not created    → busy (DDL phase, nothing to measure)
- *   6. flat + ClientRead     → client-stall (the deadlock signature)
+ *   6. flat + ClientRead + the client still has bytes to send → client-stall (the deadlock signature)
+ *   7. flat + ClientRead + the client has sent everything     → finishing (the successful tail)
+ *
+ * Step 7 is the B5 fix. "Nothing is moving" was treated as sufficient evidence of a stall, and it is
+ * not: at the end of a healthy load nothing moves either. A stall claim now requires UNLANDED WORK —
+ * bytes the client still owes the server — which is why `feed` is threaded this far down.
  */
-export function classify(prev: HeartbeatSample | null, cur: HeartbeatSample): Liveness {
+export function classify(prev: HeartbeatSample | null, cur: HeartbeatSample, feed?: ClientFeed): Liveness {
   if (cur.state === null) return 'absent';
   if (!prev) return 'busy';
   // PROGRESS OUTRANKS EVERY SCARY WAIT STATE, including Lock. A restore takes relation locks
@@ -231,7 +260,7 @@ export function classify(prev: HeartbeatSample | null, cur: HeartbeatSample): Li
   if (movedForward(prev, cur)) return 'progressing';
   if (cur.waitEventType === 'Lock') return 'blocked';
   if (!cur.schemaExists) return 'busy';
-  if (cur.waitEvent === 'ClientRead') return 'client-stall';
+  if (cur.waitEvent === 'ClientRead') return feed?.done ? 'finishing' : 'client-stall';
   return 'busy';
 }
 
@@ -251,16 +280,70 @@ function groupNum(n: number): string {
   return n.toLocaleString('en-US');
 }
 
-/** One operator-readable line per poll. Says what moved, what it is waiting on, and how long in. */
-export function formatSample(prev: HeartbeatSample | null, cur: HeartbeatSample, liveness: Liveness): string {
+/** `1.9 GB`, `512 KB` — bytes at poll-line resolution. */
+function fmtBytes(n: number): string {
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let v = n;
+  let u = 0;
+  while (v >= 1024 && u < units.length - 1) { v /= 1024; u += 1; }
+  return `${u === 0 ? v : v.toFixed(1)} ${units[u]}`;
+}
+
+/**
+ * WHICH signal moved between two samples, named honestly.
+ *
+ * The bug (B6): the progressing line said "COPY advancing" whenever the row delta was zero,
+ * regardless of what had actually moved. So a restore in its index phase — relations growing, no
+ * COPY anywhere — printed "COPY advancing", and so did the poll right after the final COPY finished.
+ * An idle tail read as a live load. Each branch below reports only what it actually observed.
+ */
+export function progressLabel(prev: HeartbeatSample, cur: HeartbeatSample): string {
+  const dRows = (cur.rows ?? 0) - (prev.rows ?? 0);
+  if (dRows > 0) {
+    const secs = Math.max(1, (cur.elapsedMs - prev.elapsedMs) / 1000);
+    return `+${groupNum(dRows)} row(s) (${groupNum(Math.round(dRows / secs))} rows/s)`;
+  }
+  const copyMoved = cur.copyBytes > prev.copyBytes || cur.copyRows > prev.copyRows;
+  // "Advancing" is a claim about NOW, so it needs a COPY running now — not merely one that moved.
+  if (copyMoved && cur.copies > 0) return 'COPY advancing';
+  const dRel = cur.relations - prev.relations;
+  if (dRel > 0) return `+${groupNum(dRel)} relation(s) created`;
+  if (copyMoved) return 'a COPY completed since the last poll';
+  return 'something moved';
+}
+
+/** The client-side position clause — `client fed 1.9 GB/2.0 GB (95%)`. Empty when unknown. */
+function clientClause(feed?: ClientFeed): string {
+  if (!feed) return '';
+  const pct = feed.totalBytes > 0 ? Math.floor((feed.fedBytes / feed.totalBytes) * 100) : 0;
+  const sent = feed.done ? 'client has fed ALL' : 'client fed';
+  return `, ${sent} ${fmtBytes(feed.fedBytes)}/${fmtBytes(feed.totalBytes)} (${pct}%)`;
+}
+
+/**
+ * One operator-readable line per poll. Says what moved, what it is waiting on, how long in — and, when
+ * known, what the CLIENT has sent.
+ *
+ * That last part is B7. A `Client/ClientRead` wait with the client 20% through the file and the same
+ * wait with the file fully fed are completely different situations, and they used to print
+ * identically: two debugging sessions went down the wrong path because "the client is not sending"
+ * and "the instance has no I/O left" were indistinguishable in the log.
+ */
+export function formatSample(
+  prev: HeartbeatSample | null,
+  cur: HeartbeatSample,
+  liveness: Liveness,
+  feed?: ClientFeed,
+): string {
   const at = `t+${humanElapsed(cur.elapsedMs)}`;
   const wait = cur.waitEventType ? `${cur.waitEventType}/${cur.waitEvent ?? '?'}` : (cur.state ?? 'idle');
+  const client = clientClause(feed);
 
   if (liveness === 'absent') {
     return `restore: no psql backend connected to the target (${at}) — the loader has not started yet, or has already exited.`;
   }
   if (!cur.schemaExists) {
-    return `restore: schema not created yet, no tables yet — DDL phase, ${wait} (${at}).`;
+    return `restore: schema not created yet, no tables yet — DDL phase, ${wait}${client} (${at}).`;
   }
 
   const rows = cur.rows === null ? 'unknown' : groupNum(cur.rows);
@@ -275,20 +358,18 @@ export function formatSample(prev: HeartbeatSample | null, cur: HeartbeatSample,
   if (liveness === 'blocked') {
     // Naming the holder is the difference between an actionable report and a shrug.
     const by = cur.blockedBy ? ` HELD BY ${cur.blockedBy}` : ' (holder not visible — it may belong to another role)';
-    return `restore: waiting on ${wait} with no progress this poll${by} — ${scope} (${at}).`;
+    return `restore: waiting on ${wait} with no progress this poll${by} — ${scope}${client} (${at}).`;
+  }
+  if (liveness === 'finishing') {
+    return `restore: ${scope}${client} — FINISHING: everything has been sent, the server is winding the load down (${wait}), ${at}.`;
   }
   if (liveness === 'client-stall') {
-    return `restore: nothing landed since the last poll and the server is waiting on the client (${wait}) — ${scope} (${at}).`;
+    return `restore: nothing landed since the last poll and the server is waiting on the client (${wait}) — ${scope}${client} (${at}).`;
   }
   if (liveness === 'progressing' && prev) {
-    const dRows = (cur.rows ?? 0) - (prev.rows ?? 0);
-    const secs = Math.max(1, (cur.elapsedMs - prev.elapsedMs) / 1000);
-    const moved = dRows > 0
-      ? `+${groupNum(dRows)} row(s) (${groupNum(Math.round(dRows / secs))} rows/s)`
-      : 'COPY advancing';
-    return `restore: ${scope}, ${moved} — ${wait} (${at}).`;
+    return `restore: ${scope}, ${progressLabel(prev, cur)} — ${wait}${client} (${at}).`;
   }
-  return `restore: ${scope}, nothing new this poll — ${wait} (${at}).`;
+  return `restore: ${scope}, nothing new this poll — ${wait}${client} (${at}).`;
 }
 
 /**
@@ -335,6 +416,12 @@ export interface HeartbeatOptions {
    * backend for. Must not throw; a sink that does is ignored so it cannot kill the heartbeat.
    */
   onSample?: (sample: HeartbeatSample) => void;
+  /**
+   * The client's current write position, read fresh each poll. Supplying it is what lets the
+   * heartbeat tell a stalled load from a finishing one (see ClientFeed) — without it the detector
+   * falls back to server-side-only reasoning and will call a quiet tail a stall.
+   */
+  clientFeed?: () => ClientFeed;
 }
 
 /**
@@ -363,8 +450,10 @@ export function startHeartbeat(runner: QueryRunner, opts: HeartbeatOptions): ()
     // Raw sample first: a caller acting on the probe (the dead-backend watchdog) must see every
     // sample, and must never be able to break the heartbeat by throwing.
     try { opts.onSample?.(cur); } catch { /* a sink's failure is not the probe's problem */ }
-    const liveness = classify(prev, cur);
-    const line = formatSample(prev, cur, liveness);
+    let feed: ClientFeed | undefined;
+    try { feed = opts.clientFeed?.(); } catch { /* same: a bad reader must not kill the probe */ }
+    const liveness = classify(prev, cur, feed);
+    const line = formatSample(prev, cur, liveness, feed);
 
     if (liveness === 'blocked') {
       warn(line);

package/src/cli/swap-snapshot.ts

@@ -0,0 +1,260 @@
+/**
+ * db:swap's pre-swap rollback point — which snapshot to take, and proof that it exists.
+ *
+ * The swap's step 2 is "SNAPSHOT — the rollback point, before anything destructive". It was taking a
+ * LOGICAL backup (`db:backup` via the ops Lambda) and that turned out to be wrong twice over:
+ *
+ *  - It never waited. The ops action DISPATCHES a Fargate task and returns the run id; the swap
+ *    printed "snapshot on record" and started restoring immediately. So the pg_dump ran alongside
+ *    the restore — a consumer measured the restore blocked ~5 minutes on
+ *    `Lock/relation HELD BY pid [pg_dump] COPY <schema>.<table>`, the swap contending with its own
+ *    backup. On a small instance that makes the swap's duration a coin flip unrelated to data volume.
+ *  - Worse than slow: unproven. A task that failed to start, or died on its credential, left the
+ *    swap proceeding into a destructive rename believing it had a rollback point it did not have.
+ *
+ * A PHYSICAL RDS snapshot is the better rollback point on every axis that matters here: it is a
+ * control-plane call, so it holds no relation locks, reads nothing through the buffer cache, and
+ * needs no client connection. It is also RDS-only, hence the mode selection below rather than a
+ * straight replacement.
+ *
+ * The decision is pure and the confirmation takes its IO injected, so both are provable without an
+ * AWS account. See docs/schema-swap.md.
+ */
+
+/** The values `--snapshot` accepts. `none` is the explicit opt-out; there is no implicit one. */
+export const SNAPSHOT_MODES = ['physical', 'logical', 'none'] as const;
+export type SnapshotModeRequest = (typeof SNAPSHOT_MODES)[number];
+
+/** What db:swap should do about a rollback point before it touches anything. */
+export type SnapshotDecision =
+  /** Take an RDS snapshot of this instance (no locks, no pg_dump, no connection). */
+  | { mode: 'physical'; instanceId: string }
+  /** Dispatch db:backup and WAIT for the task to finish before restoring. */
+  | { mode: 'logical' }
+  /** The operator already took one and named it — nothing to do but record it. */
+  | { mode: 'attested'; ref: string }
+  /** The operator explicitly accepted no rollback point. */
+  | { mode: 'none' }
+  /** Nothing safe is available and no consent was given — refuse before anything moves. */
+  | { mode: 'refuse'; reason: string };
+
+export interface SnapshotDecisionInput {
+  /**
+   * `stage` = `--stage <name> --direct`, which has an ops Lambda and deployed outputs behind it.
+   * `url` = a bare `--database-url`, which has neither: no stage config to read an instance id from
+   * and no ops function to dispatch a backup to.
+   */
+  venue: 'stage' | 'url';
+  /** `config.databaseInstanceId`. `placeholder` is what a non-RDS or dev-mode stage carries. */
+  instanceId?: string;
+  /** `--snapshot-ref <id>` — a snapshot the operator took themselves (db:apply's precedent). */
+  snapshotRef?: string;
+  /** `--snapshot <physical|logical|none>`. */
+  requested?: SnapshotModeRequest;
+}
+
+/** Is this instance id something we can actually snapshot, or an absent/placeholder output? */
+function usableInstanceId(id?: string): id is string {
+  return !!id && id !== 'placeholder';
+}
+
+/**
+ * Choose the rollback point.
+ *
+ * Precedence, and the reasoning for it:
+ *   1. `--snapshot-ref` — the operator attests one exists. Taking a second is waste, and this is the
+ *      shape db:apply's direct lane already uses, so the two destructive verbs read the same.
+ *   2. `--snapshot none` — informed consent to have no rollback point. Explicit only.
+ *   3. `--snapshot physical|logical` — an explicit choice, honoured or refused with the reason.
+ *   4. The default: physical on an RDS stage, logical on any other stage, refuse on a bare URL.
+ *
+ * The bare-URL default is a REFUSAL rather than a warning. It used to warn and carry on, which is
+ * the same class of hole as the `--stage` bypass 0.4.36 closed: a destructive verb whose safety step
+ * is optional in practice.
+ */
+export function decideSnapshotMode(input: SnapshotDecisionInput): SnapshotDecision {
+  const { venue, instanceId, snapshotRef, requested } = input;
+
+  if (requested !== undefined && !SNAPSHOT_MODES.includes(requested)) {
+    return {
+      mode: 'refuse',
+      reason: `--snapshot ${requested} is not a snapshot mode. Pass one of: ${SNAPSHOT_MODES.join(', ')} `
+        + `(physical = an RDS snapshot, logical = a db:backup pg_dump, none = explicitly no rollback point).`,
+    };
+  }
+
+  if (snapshotRef) return { mode: 'attested', ref: snapshotRef };
+  if (requested === 'none') return { mode: 'none' };
+
+  if (requested === 'physical') {
+    // A physical snapshot is an RDS control-plane call, which needs a REGION as well as an instance
+    // id — and the only source of a region here is the stage's deployed config. A bare
+    // --database-url has none, so honouring the request would mean calling AWS with an undefined
+    // region and reporting a confusing SDK error instead of the real problem.
+    if (venue === 'url') {
+      return {
+        mode: 'refuse',
+        reason: 'A physical snapshot needs the stage\'s region and instance id, and a bare --database-url carries neither. '
+          + 'Take one against the stage (everystack db:snapshot --stage <name>) and attest it here: --snapshot-ref <id>. '
+          + 'Or accept the risk explicitly with --snapshot none.',
+      };
+    }
+    if (!usableInstanceId(instanceId)) {
+      return {
+        mode: 'refuse',
+        reason: 'A physical snapshot needs the RDS instance id, and this stage does not expose one. '
+          + 'Add `databaseInstanceId: database.id` to the outputs return block in sst.config.ts and redeploy '
+          + '(run db:swap from the app directory so .sst/outputs.json is readable), or pass --snapshot logical '
+          + 'for a pg_dump rollback point instead.',
+      };
+    }
+    return { mode: 'physical', instanceId };
+  }
+
+  if (requested === 'logical') {
+    if (venue === 'url') {
+      return {
+        mode: 'refuse',
+        reason: 'A logical snapshot runs in the stage\'s Task lane via the ops Lambda, and a bare --database-url has no stage behind it. '
+          + 'Take one yourself and name it: --snapshot-ref <id> (everystack db:backup --database-url … or db:snapshot), '
+          + 'or accept the risk explicitly with --snapshot none.',
+      };
+    }
+    return { mode: 'logical' };
+  }
+
+  // No explicit request — the default per venue.
+  if (venue === 'stage') {
+    return usableInstanceId(instanceId) ? { mode: 'physical', instanceId } : { mode: 'logical' };
+  }
+  return {
+    mode: 'refuse',
+    reason: 'db:swap over a bare --database-url does not take a snapshot for you, and it will not run destructively without one. '
+      + 'Take a rollback point and name it: --snapshot-ref <id> (everystack db:snapshot, or db:backup --database-url …). '
+      + 'If you genuinely want no rollback point, say so: --snapshot none.',
+  };
+}
+
+/**
+ * A finished `pollTaskUntilStopped` result, read as "is there a rollback point or not".
+ *
+ * Kept pure and separate because this is the judgement the old code never made: it treated the
+ * DISPATCH as the answer. Every non-success outcome here has to abort the swap, and each one needs
+ * different advice, so the wording is worth pinning in a test.
+ */
+export function interpretBackupPoll(
+  poll:
+    | { outcome: 'timeout'; lastStatus: string }
+    | { outcome: 'error'; status: { error?: string } }
+    | { outcome: 'stopped'; status: { exitCode?: number | null; stoppedReason?: string | null } },
+  ids: { runId: string; id: string },
+): { ok: true } | { ok: false; reason: string } {
+  const untouched = 'so the swap was NOT applied and live is untouched.';
+  if (poll.outcome === 'timeout') {
+    return {
+      ok: false,
+      reason: `the pre-swap backup did not finish in time (last status: ${poll.lastStatus}), ${untouched} `
+        + `Run id ${ids.runId} — check everystack.task_log / ECS, then re-run with --snapshot-ref ${ids.id} once the backup is on record.`,
+    };
+  }
+  if (poll.outcome === 'error') {
+    return {
+      ok: false,
+      reason: `the pre-swap backup's status could not be read (${poll.status.error}), so the swap was NOT applied. `
+        + `It may still be running — reconcile run id ${ids.runId} before retrying.`,
+    };
+  }
+  if (poll.status.exitCode !== 0) {
+    return {
+      ok: false,
+      reason: `the pre-swap backup FAILED (exit ${poll.status.exitCode ?? 'unknown'})`
+        + `${poll.status.stoppedReason ? ` — ${poll.status.stoppedReason}` : ''}, ${untouched} `
+        + `Read the task logs (CloudWatch) before retrying.`,
+    };
+  }
+  return { ok: true };
+}
+
+/** The RDS control-plane calls confirmPhysicalSnapshot needs, injected so the wait is testable. */
+export interface PhysicalSnapshotIO {
+  /** CreateDBSnapshot — returns the new snapshot's identifier and initial status. */
+  create: (snapshotId: string) => Promise<{ identifier: string; status: string }>;
+  /** DescribeDBSnapshots for the instance (manual snapshots). */
+  describe: () => Promise<Array<{ identifier: string; status: string }>>;
+  log: (msg: string) => void;
+  sleep: (ms: number) => Promise<void>;
+  now: () => number;
+}
+
+export interface ConfirmPhysicalOptions {
+  instanceId: string;
+  snapshotId: string;
+  /** How long to wait for `available` before refusing. */
+  deadlineMs?: number;
+  /** How often to re-read the status. */
+  pollIntervalMs?: number;
+}
+
+/**
+ * A snapshot's status is polled to a TERMINAL state before the swap is allowed to continue. 15
+ * minutes is generous for a dev-sized instance and short enough that a stuck snapshot surfaces as a
+ * refusal rather than an hour of silence.
+ */
+const DEFAULT_SNAPSHOT_DEADLINE_MS = 15 * 60_000;
+const DEFAULT_SNAPSHOT_POLL_MS = 10_000;
+
+/**
+ * Take an RDS snapshot and do not return until RDS says it is `available`.
+ *
+ * Why wait at all, when the snapshot's consistency point is fixed the moment CreateDBSnapshot is
+ * accepted: because "accepted" is not "exists". A snapshot can go to `failed` (instance state,
+ * storage), and the entire value of this step is that the operator can get back. Proceeding into a
+ * destructive rename on an unconfirmed rollback point is the defect this module was written to
+ * remove — waiting is the only thing that turns the printed id into a fact.
+ *
+ * On the deadline it THROWS naming the snapshot id, because the re-run is one flag: the snapshot is
+ * still coming, so `--snapshot-ref <id>` reuses it instead of starting another.
+ */
+export async function confirmPhysicalSnapshot(
+  io: PhysicalSnapshotIO,
+  opts: ConfirmPhysicalOptions,
+): Promise<{ id: string }> {
+  const deadlineMs = opts.deadlineMs ?? DEFAULT_SNAPSHOT_DEADLINE_MS;
+  const pollMs = opts.pollIntervalMs ?? DEFAULT_SNAPSHOT_POLL_MS;
+  const created = await io.create(opts.snapshotId);
+  const id = created.identifier;
+  io.log(`physical snapshot ${id} of ${opts.instanceId} — status ${created.status}.`);
+  if (created.status === 'available') return { id };
+  if (created.status === 'failed') {
+    throw new Error(`the pre-swap RDS snapshot ${id} failed immediately, so the swap was NOT applied and live is untouched.`);
+  }
+
+  const start = io.now();
+  let lastStatus = created.status;
+  for (;;) {
+    if (io.now() - start >= deadlineMs) {
+      throw new Error(
+        `the pre-swap RDS snapshot ${id} is still "${lastStatus}" after ${Math.round(deadlineMs / 60_000)} minutes, so the swap was NOT applied and live is untouched. `
+        + `The snapshot is still being taken — it is a real rollback point once it reaches available. `
+        + `Watch it with \`everystack db:snapshots\`, then re-run this swap with --snapshot-ref ${id} to reuse it instead of taking another.`,
+      );
+    }
+    await io.sleep(pollMs);
+    const snaps = await io.describe();
+    const mine = snaps.find((s) => s.identifier === id);
+    if (!mine) {
+      throw new Error(
+        `the pre-swap RDS snapshot ${id} is no longer listed on ${opts.instanceId} — it was deleted or never registered, so there is no rollback point. `
+        + `The swap was NOT applied and live is untouched.`,
+      );
+    }
+    if (mine.status !== lastStatus) {
+      lastStatus = mine.status;
+      io.log(`physical snapshot ${id}: ${lastStatus}`);
+    }
+    if (mine.status === 'available') return { id };
+    if (mine.status === 'failed') {
+      throw new Error(`the pre-swap RDS snapshot ${id} FAILED, so the swap was NOT applied and live is untouched. Check the instance's state and storage, then retry.`);
+    }
+  }
+}