@everystack/cli 0.4.36 → 0.4.39

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';
@@ -29,6 +40,8 @@ import {
   evaluateRedTeam,
   GRANT_COMPLETENESS_SQL,
   toGrantGap,
+  buildInheritedPrivilegeSql,
+  toInheritedGrant,
 } from '../authz-redteam.js';
 import {
   buildOwnerProbeSql,
@@ -43,6 +56,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 +73,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 +141,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 +156,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 +173,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,36 +223,49 @@ export async function dbAuthzTestCommand(flags: Record<string, string>): Promise
 
   let rows: any[];
   let gapRows: any[];
+  let inheritedRows: 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;
+    const roles = probeRoles(contract);
+    const tables = contract.tables.map((t) => t.table);
     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(buildProbeSql(roles, tables), PROBE_SELECT_SQL);
+    step('Attributing undeclared privileges to role membership...');
+    inheritedRows = await venue.runner(buildInheritedPrivilegeSql(roles, tables));
     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));
+  const findings = evaluateRedTeam(contract, rows.map(toProbeResult), inheritedRows.map(toInheritedGrant));
   const holes = findings.filter((f) => f.severity === 'hole');
   const broken = findings.filter((f) => f.severity === 'broken');
   const unprobed = findings.filter((f) => f.severity === 'unprobed');
+  const inconclusive = findings.filter((f) => f.severity === 'inconclusive');
+  const inheritedFindings = findings.filter((f) => f.severity === 'inherited');
   const gaps = gapRows.map(toGrantGap);
 
   console.log('');
   for (const f of holes) fail(`[HOLE]   ${f.detail}`);
   for (const f of broken) warn(`[BROKEN] ${f.detail}`);
   for (const g of gaps) fail(`[GRANT-GAP] ${g.secdef} calls ${g.helper} but its owner cannot EXECUTE it (42501 in prod once ownership is normalized)`);
+  for (const f of inheritedFindings) info(`[inherited] ${f.detail}`);
+  if (inconclusive.length) {
+    // Never a pass and never a failure — a probe that proved nothing, said out loud so it
+    // can be fixed rather than silently counted as clean.
+    info(`[inconclusive] ${inconclusive.length} probe(s) failed before the privilege check and prove nothing:`);
+    for (const f of inconclusive.slice(0, 5)) info(`  ${f.command} ${f.table} (${f.role})`);
+    if (inconclusive.length > 5) info(`  …and ${inconclusive.length - 5} more`);
+  }
   if (unprobed.length) {
     const roles = [...new Set(unprobed.map((f) => f.role))].join(', ');
     info(`[unprobed] could not SET ROLE into: ${roles} — grant the operator membership to cover them.`);
@@ -200,10 +273,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 +296,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 +315,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 +342,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-fingerprint.ts

@@ -12,6 +12,7 @@
  * is deliberately absent here — `db:reconcile --check` is its verifier.
  */
 
+import { existsSync } from 'node:fs';
 import type { ModelDescriptor } from '@everystack/model';
 import type { QueryRunner } from '../authz-contract.js';
 import { introspectSchema } from '../schema-introspect.js';
@@ -78,8 +79,24 @@ export async function dbFingerprintCommand(flags: Record<string, string>): Promi
   try {
     models = await loadModels(modelsPath);
     sequences = (await loadDeclaredDerived(flags.models))?.sequences;
-  } catch {
-    // Live-only mode: no models barrel — still useful (what fingerprint is this DB at?).
+  } catch (err: any) {
+    // Two very different situations used to land here identically.
+    //
+    // No barrel at all is legitimate live-only mode — "what fingerprint is this database
+    // at?" is a useful question on its own.
+    //
+    // A barrel that EXISTS but will not load is not. Reporting "(live-only)" for it turns
+    // a broken measurement into a passing one: the operator asked whether the database
+    // matches their models, and got an answer that never looked at the models. That is
+    // how someone concludes a round-trip closed when nothing was compared.
+    if (existsSync(modelsPath)) {
+      fail(`Could not load the models barrel at ${modelsPath}`);
+      info(String(err?.message ?? err).split('\n').slice(0, 6).join('\n'));
+      info('');
+      info('Fix the barrel and re-run. (Refusing rather than falling back to live-only —');
+      info('a comparison that silently compares nothing is worse than an error.)');
+      process.exit(1);
+    }
   }
 
   let runner: QueryRunner;

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

@@ -31,6 +31,8 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { introspectSchema, MATVIEW_COLUMNS_SQL, matviewColumnsByIdentity, type ColumnRow, type ColumnSchema } from '../schema-introspect.js';
 import { introspectDerived, type DerivedCatalog } from '../derived-introspect.js';
+import { introspectContract, type TableContract } from '../authz-contract.js';
+import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { renderDerivedSource, renderDerivedFile, type DerivedRenderResult } from '../derived-render.js';
 import { renderModelSource, renderModelFiles, pullableTables, modelVarName, ABILITY_PRESETS } from '../model-render.js';
 import type { QueryRunner } from '../authz-contract.js';
@@ -102,8 +104,8 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   // The read-model scaffold: default 'commented' surfaces the authz decision in every
   // model; a preset stamps it. Validated up front so a typo fails before introspection.
   const abilities = flags.abilities || 'commented';
-  if (abilities !== 'commented' && !ABILITY_PRESETS[abilities]) {
-    fail(`Unknown --abilities preset '${abilities}'. Known: ${Object.keys(ABILITY_PRESETS).join(', ')} (omit the flag to scaffold the decision as comments).`);
+  if (abilities !== 'commented' && abilities !== 'live' && !ABILITY_PRESETS[abilities]) {
+    fail(`Unknown --abilities preset '${abilities}'. Known: live, ${Object.keys(ABILITY_PRESETS).join(', ')} (omit the flag to scaffold the decision as comments).`);
     process.exit(1);
   }
 
@@ -123,6 +125,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   }
 
   let current;
+  let liveAuthz: Map<string, TableContract> | undefined;
   let derivedCatalog: DerivedCatalog | undefined;
   let matviewColumns: Map<string, ColumnSchema[]> | undefined;
   let candidatesByIdentity: Map<string, string[]> | undefined;
@@ -143,6 +146,28 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     // The derived layer rides the same pull (B5) — views/matviews/functions/sequences
     // render as descriptors; adoption is pull → commit → --baseline → clean reconcile.
     derivedCatalog = await introspectDerived(runner);
+    // --abilities live: the authz half of the on-ramp. Same connection, one more read —
+    // the grants and policies that already exist become the models' declared abilities,
+    // instead of a human transcribing them by hand.
+    if (abilities === 'live') {
+      note('Introspecting live authorization (grants + policies)...');
+      const contract = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+      liveAuthz = new Map(contract.tables.map((t) => [t.table, t]));
+      detail(`${liveAuthz.size} table(s) carry authorization.`);
+      // Roles outside the model vocabulary (anon/authenticated/admin) are usually ONE
+      // operator account granted across the whole schema. Said once here rather than
+      // repeated in all N models, where it would bury the per-table findings.
+      const unmapped = new Set<string>();
+      for (const t of contract.tables) {
+        for (const r of Object.keys(t.grants)) {
+          if (!['anon', 'authenticated', 'admin', 'PUBLIC', 'public'].includes(r)) unmapped.add(r);
+        }
+      }
+      if (unmapped.size) {
+        note(`Grants exist for ${[...unmapped].sort().join(', ')} — not rendered: abilities name the roles the model knows (anon/authenticated/admin).`);
+        detail(`These are left exactly as they are in the database. Add can(..., { role }) only if you want the models to own them.`);
+      }
+    }
     // --matviews-as-tables: the flip needs real fields — one extra catalog read for the
     // matview columns the derived layer (definition-only) doesn't carry.
     if (matviewsAsTables) {
@@ -235,7 +260,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   if (flags.out && !flags.out.endsWith('.ts')) {
     // A directory: one file per model + index.ts — the default shape for a real app.
     const dir = path.resolve(flags.out);
-    const files = renderModelFiles(current, { schema, abilities, derived: embeddedDerived });
+    const files = renderModelFiles(current, { schema, abilities, liveAuthz, derived: embeddedDerived });
     try {
       await fs.mkdir(dir, { recursive: true });
       const written = new Set(files.map((f) => f.file));
@@ -252,7 +277,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     source = files.map((f) => f.source).join('\n');
   } else if (flags.out) {
     const outPath = path.resolve(flags.out);
-    source = renderModelSource(current, { schema, abilities, derived: embeddedDerived });
+    source = renderModelSource(current, { schema, abilities, liveAuthz, derived: embeddedDerived });
     try {
       await fs.mkdir(path.dirname(outPath), { recursive: true });
       await fs.writeFile(outPath, source, 'utf8');
@@ -262,7 +287,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     }
     ok(`Wrote ${path.relative(process.cwd(), outPath)} — ${pulled.length} model(s).`);
   } else {
-    source = renderModelSource(current, { schema, abilities, derived: embeddedDerived });
+    source = renderModelSource(current, { schema, abilities, liveAuthz, derived: embeddedDerived });
     process.stdout.write(source);
     ok(`Rendered ${pulled.length} model(s) from schema "${schema}" (stdout — redirect or pass --out to save).`);
   }

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

@@ -29,6 +29,7 @@ import { loadDeclaredDerived } from '../declared-derived.js';
 import type { SourceObject } from '../derived-source.js';
 import { pairedDerivedSchemas, renderPairedDerivedBuild, renderSwapSchemaUsage, swapSchemaRoles, expectedIncomingObjects, renderPairedProvenance } from '../swap-pair.js';
 import { introspectDerived } from '../derived-introspect.js';
+import { legacyFunctionIdentity } from '../pg-argtypes.js';
 import { createUrlRunner } from '../db-source.js';
 import type { QueryRunner } from '../authz-contract.js';
 import { executeSwap, type SwapVerdict } from '../swap-execute.js';
@@ -37,9 +38,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 +268,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 +307,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 +344,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 +435,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 +527,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 +541,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 +556,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:
@@ -534,7 +638,10 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
         artifactFingerprint,
         declaredFingerprint,
         // What db:reconcile can regenerate — the set a dependent must be in to be safe to drop.
-        declaredIdentities: declaredDerivedObjects.map((o) => o.identity),
+        // NAME granularity: both consumers (the paired pre-flight's dependentIdentity, the TOC
+        // filter) read a function as `schema.name` with its argument list stripped, so the
+        // signature half of a derived identity is dropped here rather than never matching.
+        declaredIdentities: declaredDerivedObjects.map((o) => legacyFunctionIdentity(o.identity)),
         rebuildDerived: flags['rebuild-derived'] === 'true',
         paired,
         // Schema-level USAGE, re-applied in the swap transaction and asserted after it commits.
@@ -606,17 +713,11 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
             runner: r,
             log: (m) => info(m),
             warn: (m) => warn(m),
-            declaredIdentities: declaredDerivedObjects.map((o) => o.identity),
+            // Name granularity — the TOC entry's argument list is stripped before the lookup.
+            declaredIdentities: declaredDerivedObjects.map((o) => legacyFunctionIdentity(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/commands/db.ts

@@ -721,6 +721,17 @@ function printDoctorReport(report: any): void {
     success('db:doctor — database is least-privilege and RLS-subject');
   } else {
     fail('db:doctor — the api connection is NOT correctly least-privilege (see failures above)');
+    // Probing a local database as your own superuser makes these fail by construction:
+    // the checks describe the credential the API serves with, not the schema. A developer
+    // reading them as defects in their app will go hunting for a bug that is not there.
+    if (report.api?.isSuperuser) {
+      console.log('');
+      info('Note: this probe connected as a SUPERUSER, so least-privilege / not-superuser / fails-closed');
+      info('cannot pass by construction. Those three describe the credential your API serves with —');
+      info('they are only meaningful against the app role (a deployed stage, or a local DATABASE_URL');
+      info('pointing at the least-privilege role from db:provision). The RLS and grant findings above');
+      info('are still real.');
+    }
   }
 }