@everystack/cli 0.4.45 → 0.4.47

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

@@ -2,7 +2,7 @@
  * `everystack db:plan` — mint a verified edge against a target database
  * (brick 4's mint surface; the review artifact of the deploy boundary).
  *
- *   db:plan [--stage <name> | --database-url <url>] [--models <barrel>]
+ *   db:plan [--stage <name> [--direct] | --database-url <url>] [--models <barrel>]
  *           [--allow-drops] [--out db.plan.json | --out -]
  *
  * Minting asks the TARGET its fingerprint (no repo-side release pointer to
@@ -16,15 +16,38 @@
  * Plans are EPHEMERAL — attach them to the release/PR run, never commit
  * them (committing plans would rebuild the tape). Minting is read-only, so
  * it works over the ops Lambda (--stage) as well as a direct connection.
+ *
+ * THREE VENUES, and the difference is what the resulting fingerprint is worth:
+ *
+ *   --stage <name>            the ops Lambda. A full read is two invokes (state, then authz),
+ *                             answerable by two containers at two moments, so the minted `from`
+ *                             can describe no single real state. This lane reads TWICE and
+ *                             refuses a disagreement — a DETECTOR, never a verification
+ *                             (stage-read-consistency.ts). Agreement proves nothing.
+ *   --stage <name> --direct   the stage's OPERATOR connection, resolved from its IAM-gated ops
+ *                             Lambda and held in memory only. One real connection, one session,
+ *                             read ONCE — a fingerprint that describes one database at one
+ *                             moment. The credential never reaches argv.
+ *   --database-url <url>      a LOCAL connection. Same read guarantee as --direct, but against a
+ *                             deployed stage it forces a privileged DSN onto the command line.
+ *
+ * `--direct` EXISTED FOR db:apply AND NOT FOR db:plan, WHICH INVERTED THE COST OF SAFETY. The
+ * only lane that can verify a fingerprint was the only lane that made the operator print their
+ * credential, so verifying a plan cost them their secret hygiene — and the destructive refusal
+ * then recommended exactly that. A consumer's operator put it plainly: "every command that
+ * requires ARN is a risk of exposure. A major purpose of everystack is to PREVENT this." The
+ * resolution is shared with db:apply, db:reconcile, db:backfill, db:refresh and db:swap
+ * (direct-venue.ts) — db:plan was the verb that never adopted it.
  */
 
 import fs from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
 import type { ModelDescriptor } from '@everystack/model';
-import { introspectContract, type QueryRunner } from '../authz-contract.js';
+import { introspectContract, type QueryRunner, type AuthzContract } from '../authz-contract.js';
 import { classifyAdoption, renderAdoptionReport } from '../authz-adoption-class.js';
 import { introspectTableOwners, buildOwnershipReport, renderOwnershipReport } from '../authz-ownership.js';
-import { introspectSchema } from '../schema-introspect.js';
+import { introspectSchema, type SchemaSnapshot } from '../schema-introspect.js';
+import { readStageStateTwice } from '../stage-read-consistency.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { mintEdgePlan, planHash, buildPlanSummary } from '../edge-plan.js';
 import { verifyDescent } from '../git-descent.js';
@@ -32,13 +55,16 @@ import { planBackfills, readBackfillLog } from '../backfill.js';
 import { readSqlDirIfPresent } from './db-sync.js';
 import { currentGitRef } from '../state-apply.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
+import { borrowedSessionRunner, type SessionRunner } from '../session.js';
 import { resolveModelsPath } from '../models-path.js';
 import { resolveConfig, opsFunction } from '../config.js';
-import { lambdaQueryRunner } from '../aws.js';
+import { resolveOperatorUrlViaStage } from '../direct-venue.js';
+import { lambdaQueryRunner, lambdaSessionRunner } from '../aws.js';
 import { loadModels } from './db-generate.js';
 import { loadDeclaredDerived } from '../declared-derived.js';
 import { governedRoleSet, ungovernedGrants } from '../authz-reconcile.js';
 import { readBaselineFile, checkAgainstBaseline, baselineRefusal } from '../authz-baseline.js';
+import { alterTypeStatementTargets, findAlterTypeDependents, renderAlterTypeRefusal } from '../alter-type-dependents.js';
 import { compileTableContract } from '../authz-compile.js';
 import { reportPipelineLastRun } from './pipeline-run.js';
 import { step, success, fail, info, warn, reserveStdoutForData } from '../output.js';
@@ -88,21 +114,58 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     process.exit(1);
   }
 
+  // `--stage --direct`: resolve the stage's OPERATOR connection from its IAM-gated ops Lambda
+  // and mint over it. The URL lives in this process's memory only — never printed, never
+  // written, never on argv. From here it IS a url source, so the single-read path below picks
+  // it up and `connectingVia` reports the operator credential honestly.
+  if (dbSource.kind === 'stage' && flags.direct === 'true') {
+    try {
+      step('Resolving the operator connection from the stage (--direct)...');
+      const op = await resolveOperatorUrlViaStage(flags.stage);
+      info(`operator credential resolved (${op.source}) — minting CLI-side over one connection.`);
+      dbSource = { kind: 'url', url: op.url, from: 'operator' };
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+  }
+
   let runner: QueryRunner;
+
+  let session: SessionRunner;
   let end: (() => Promise<void>) | undefined;
   if (dbSource.kind === 'url') {
     step(connectingVia(dbSource));
-    ({ runner, end } = await createUrlRunner(dbSource.url));
+    ({ runner, session, end } = await createUrlRunner(dbSource.url));
   } else {
     step('Resolving deployed config...');
     const config = await resolveConfig(flags.stage);
     runner = lambdaQueryRunner(config.region, opsFunction(config));
+    session = lambdaSessionRunner(config.region, opsFunction(config));
   }
 
   try {
-    step('Asking the target its fingerprint (introspecting state + authz)...');
-    const snapshot = await introspectSchema(runner);
-    const contract = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+    let snapshot: SchemaSnapshot;
+    let contract: AuthzContract;
+    if (dbSource.kind === 'url') {
+      // One session, one database — the read is atomic enough to trust.
+      step('Asking the target its fingerprint (introspecting state + authz)...');
+      snapshot = await introspectSchema(session);
+      contract = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
+    } else {
+      // Each introspection is one session now, but a full read is TWO of them (state,
+      // then authz) and they can land on two containers at two moments. Read twice and
+      // refuse a disagreement — see stage-read-consistency.ts for why agreement is a
+      // non-detection and not a verification.
+      step('Asking the target its fingerprint TWICE (the stage lane reads state and authz in separate ops-Lambda invokes)...');
+      const pair = await readStageStateTwice(session);
+      if (!pair.ok) {
+        fail(pair.reason);
+        process.exit(1);
+      }
+      warn(pair.warning);
+      ({ snapshot, contract } = pair.state);
+    }
     // Not part of the plan and not part of either fingerprint — the owner is
     // environment-specific. It is read here so the REVIEW surface can name it.
     const owners = await introspectTableOwners(runner);
@@ -145,6 +208,19 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       process.exit(1);
     }
 
+    // The plan lane's contract: what it mints, it can apply. A SET DATA TYPE on a
+    // column a view/matview/rule binds would fail MID-TRANSACTION at apply
+    // ("cannot alter type of a column used by a view or rule") — refuse at mint,
+    // with the dependents named, while there is still a live catalog to ask.
+    const alterTargets = alterTypeStatementTargets(plan.statements);
+    if (alterTargets.length > 0) {
+      const blockedAlters = await findAlterTypeDependents(runner, alterTargets);
+      if (blockedAlters.length > 0) {
+        fail(`Mint refused: ${renderAlterTypeRefusal(blockedAlters)}`);
+        process.exit(1);
+      }
+    }
+
     const body = JSON.stringify(plan, null, 2) + '\n';
     if (out === '-') {
       console.log(body);
@@ -166,8 +242,12 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     const adoptionTotal = Object.values(adoption.counts).reduce((a, b) => a + b, 0);
     if (adoptionTotal > 0) {
       info(`${adoptionTotal} authorization statement(s), by why they exist:`);
-      for (const line of renderAdoptionReport(adoption.counts)) info(line);
+      for (const line of renderAdoptionReport(adoption.counts, adoption.statements)) info(line);
     }
+    // The class rides on the ARTIFACT too, not only the terminal. A reviewer reading
+    // db.plan.json had the aggregate and no way to reach the statements behind it, so
+    // `unclassified: 5` was unreadable by the only person positioned to catch what it meant.
+    plan.adoption = adoption.statements;
 
     // WHO owns the tables this plan authorizes, and does that owner obey the policies it
     // is about to write? Re-derived live every mint, never stored — the owner is a fact

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

@@ -1,9 +1,13 @@
 /**
  * `everystack db:pull` — generate `field()` Models from a live database (the brownfield on-ramp).
  *
- *   db:pull [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>]
+ *   db:pull [--stage <name>] [--database-url <url>] [--schema public] [--out <dir | file.ts>]
  *           [--derived-out <file.ts>] [--abilities public-read]
  *
+ * `--stage` and `--database-url` COMPOSE: the URL picks the connection, the stage names the
+ * baseline entry (`db/authz-baseline.json` is per-stage — a local adoption pulls with
+ * `--database-url … --stage local`, which is the stage db:plan defaults to).
+ *
  * The reverse of db:generate: that writes migrations FROM Models; this writes Models FROM the
  * database. It introspects the deployed schema through the read-only ops Lambda `db:query`
  * action — or, for a database no Lambda can reach (the brownfield case where the target
@@ -41,8 +45,9 @@ import { renderDerivedSource, renderDerivedFile, type DerivedRenderResult } from
 import { renderModelSource, renderModelFiles, pullableTables, modelVarName, ABILITY_PRESETS } from '../model-render.js';
 import type { QueryRunner } from '../authz-contract.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
+import { borrowedSessionRunner, type SessionRunner } from '../session.js';
 import { resolveConfig, opsFunction } from '../config.js';
-import { invokeAction } from '../aws.js';
+import { invokeAction, lambdaQueryRunner, lambdaSessionRunner } from '../aws.js';
 import { fail } from '../output.js';
 import { opsAdviceLines } from '../ops-advice.js';
 
@@ -102,15 +107,6 @@ export function derivedImportSpecifier(out: string, derivedOut: string): string
   return rel.startsWith('.') ? rel : `./${rel}`;
 }
 
-/** A QueryRunner backed by the ops Lambda `db:query` action (read-only). */
-function lambdaRunner(region: string, fn: string): QueryRunner {
-  return async (sql: string) => {
-    const result: any = await invokeAction(region, fn, 'db:query', { sql });
-    if (result?.error) throw new Error(`Introspection query failed: ${result.error}`);
-    return result?.rows ?? [];
-  };
-}
-
 export async function dbPullCommand(flags: Record<string, string>): Promise<void> {
   const schema = flags.schema || 'public';
 
@@ -159,27 +155,29 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   let candidatesByIdentity: Map<string, string[]> | undefined;
   try {
     let runner: QueryRunner;
+    let session: SessionRunner;
     let end: (() => Promise<void>) | undefined;
     if (dbSource.kind === 'url') {
       note(connectingVia(dbSource));
-      ({ runner, end } = await createUrlRunner(dbSource.url));
+      ({ runner, session, end } = await createUrlRunner(dbSource.url));
     } else {
       note('Resolving deployed config...');
       const config = await resolveConfig(flags.stage);
       detail(`Region: ${config.region}, Function: ${opsFunction(config)}`);
-      runner = lambdaRunner(config.region, opsFunction(config));
+      runner = lambdaQueryRunner(config.region, opsFunction(config));
+      session = lambdaSessionRunner(config.region, opsFunction(config));
     }
     note(`Introspecting live database (schema: ${schema})...`);
-    current = await introspectSchema(runner);
+    current = await introspectSchema(session);
     // 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);
+    derivedCatalog = await introspectDerived(session);
     // --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);
+      const contract = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
       liveContract = contract;
       // The owner is NOT rendered into the models — it is the dev user here and the
       // operator role on a stage, so a model that declared it would drift everywhere.
@@ -357,8 +355,8 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     ok(`Rendered ${pulled.length} model(s) from schema "${schema}" (stdout — redirect or pass --out to save).`);
   }
 
-  const flagged = (source.match(/\/\/ (FIXME|TODO|composite|CHECK|FK →)/g) ?? []).length;
-  if (flagged) caution(`${flagged} inline comment(s) flag things to review (unmapped types, checks, cross-schema FKs).`);
+  const flagged = (source.match(/\/\/ (FIXME|TODO|composite|CHECK|FK →|verbatim:)/g) ?? []).length;
+  if (flagged) caution(`${flagged} inline comment(s) flag things to review (verbatim types, checks, cross-schema FKs).`);
   if (abilities === 'commented') {
     note(`Each model scaffolds its authz decision as comments — author them (db:check fails until every model declares), or stamp the common case: db:pull --abilities public-read.`);
   } else {

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

@@ -46,12 +46,13 @@ import {
   ENSURE_RECONCILER_SQL,
 } from '../derived-apply.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
+import { borrowedSessionRunner, type SessionRunner } from '../session.js';
 import { resolveOperatorUrlViaStage } from '../direct-venue.js';
 import { withMutationLease, MutationLeaseError } from '../mutation-lease.js';
 import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived.js';
 import { currentGitRef } from '../state-apply.js';
 import { resolveConfig, opsFunction } from '../config.js';
-import { invokeAction } from '../aws.js';
+import { invokeAction, lambdaQueryRunner, lambdaSessionRunner } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
 
 // ---------------------------------------------------------------------------
@@ -111,9 +112,10 @@ export function isTransactionalBatch(statements: string[]): boolean {
 
 export async function executeReconcile(
   runner: QueryRunner,
+  session: SessionRunner,
   options: ExecuteOptions = {},
 ): Promise<ReconcileRun> {
-  const live = await introspectDerived(runner);
+  const live = await introspectDerived(session);
   const parsed = { objects: options.declared ?? [], warnings: [] as string[] };
   const plan = planReconcile(parsed, live, options);
   const rendered = renderReconcileSql(plan, parsed.objects);
@@ -189,11 +191,14 @@ export async function executeReconcile(
       }
     }
 
-    // Re-read the catalog so provenance records the def hashes of what NOW exists, not what we hoped
-    // would exist. Inside the transaction this reads the batch's own not-yet-committed writes.
-    // introspectDerived pins the canonical search_path itself, so the defHash it records is stable
-    // regardless of the create-time wide path above (or any ambient override) — no manual reset here.
-    const after = await introspectDerived(runner);
+    // Re-read the catalog so provenance records the def hashes of what NOW exists, not what we
+    // hoped would exist. Inside the transaction this reads the batch's own not-yet-committed
+    // writes, so the read must BORROW that transaction: a session of its own would open a nested
+    // BEGIN and COMMIT this one out from under the bookkeeping below. The borrowed session pins
+    // the canonical search_path inside a savepoint it always rolls back, so the def hashes are
+    // stable regardless of the create-time wide path above — and that wide path survives the read.
+    // The unwrapped path has no transaction to borrow, so it takes a session of its own.
+    const after = await introspectDerived(atomic ? borrowedSessionRunner(runner) : session);
     const liveById = new Map(after.objects.map((o) => [o.identity, o]));
     const srcById = new Map(parsed.objects.map((o) => [o.identity, o]));
 
@@ -347,15 +352,6 @@ export function checkFails(plan: ReconcilePlan): boolean {
 // The CLI shell.
 // ---------------------------------------------------------------------------
 
-/** A QueryRunner backed by the ops Lambda `db:query` action (read-only). */
-function lambdaRunner(region: string, fn: string): QueryRunner {
-  return async (sql: string) => {
-    const result: any = await invokeAction(region, fn, 'db:query', { sql });
-    if (result?.error) throw new Error(`Query failed: ${result.error}`);
-    return result?.rows ?? [];
-  };
-}
-
 export async function dbReconcileCommand(flags: Record<string, string>): Promise<void> {
   const apply = flags.apply === 'true';
   const check = flags.check === 'true';
@@ -484,7 +480,7 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
       if (result?.error) {
         fail(`db:reconcile failed: ${result.error}`);
         if (/Unknown action/i.test(String(result.error))) {
-          info('The deployed handler predates the db:reconcile ops action (needs @everystack/server >= 0.4.8). Upgrade the server, or apply direct: db:reconcile --apply --database-url <url>.');
+          info('The deployed handler predates the db:reconcile ops action (needs @everystack/server >= 0.4.8). Upgrade the server, or apply credential-free over the direct lane: db:reconcile --apply --stage ' + (flags.stage ?? '<stage>') + ' --direct. (--database-url <url> is the local venue — against a deployed stage it puts a privileged connection string on argv.)');
         } else if (/timed out|timeout|task timed out/i.test(String(result.error))) {
           info('A large derived rebuild (dozens of objects) can exceed the ops-Lambda 900-second clock. Re-run credential-free with an unbounded clock: db:reconcile --apply --stage ' + (flags.stage ?? '<stage>') + ' --direct.');
         }
@@ -493,25 +489,27 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
       run = { plan: result.plan, applied: result.applied, statements: result.statements ?? [], refusal: result.refusal ?? undefined };
     } else {
       let runner: QueryRunner;
+      let session: SessionRunner;
       // A write over a direct connection (--database-url or --direct) takes the mutation
       // lease; a read-only stage dry-run over the ops Lambda does not (reads never lease).
       let leased = false;
       if (dbSource.kind === 'url') {
         step(connectingVia(dbSource));
-        ({ runner, end } = await createUrlRunner(dbSource.url));
+        ({ runner, session, end } = await createUrlRunner(dbSource.url));
         leased = apply;
       } else {
         step('Resolving deployed config...');
         const config = await resolveConfig(flags.stage);
-        runner = lambdaRunner(config.region, opsFunction(config));
+        runner = lambdaQueryRunner(config.region, opsFunction(config));
+        session = lambdaSessionRunner(config.region, opsFunction(config));
       }
       run = leased
         ? await withMutationLease(
             runner,
             { verb: 'db:reconcile', actor: process.env.USER ?? 'unknown' },
-            () => executeReconcile(runner, reconcileOptions),
+            () => executeReconcile(runner, session, reconcileOptions),
           )
-        : await executeReconcile(runner, reconcileOptions);
+        : await executeReconcile(runner, session, reconcileOptions);
     }
 
     if (flags.json === 'true') {

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

@@ -8,15 +8,26 @@
  * unchanged — a pure DATA-changed matview refresh had no credential-free path. This is the
  * data-lane twin: `--stage` runs the whole refresh in the ops Lambda on the operator connection
  * (the `db:refresh` action), so a least-privileged operator never holds a URL. `--database-url`
- * / `--direct` refresh over a direct connection (dev). `--list` previews the topo-ordered
- * matviews without connecting. Plain REFRESH (ACCESS EXCLUSIVE) — CONCURRENTLY is a follow-on.
- * (consumer field report 2026-07-19.)
+ * refreshes over a local connection (dev). `--stage <name> --direct` resolves the stage's
+ * operator credential from its ops Lambda and refreshes CLI-side on an UNBOUNDED clock — the
+ * lane for a matview set that exceeds the ops-Lambda 900-second limit. `--list` previews the
+ * topo-ordered matviews without connecting. Plain REFRESH (ACCESS EXCLUSIVE) — CONCURRENTLY is
+ * a follow-on. (consumer field report 2026-07-19.)
+ *
+ * `--direct` WAS ADVERTISED HERE AND IN `everystack --help` WITHOUT BEING WIRED. `resolveDbSource`
+ * does not know the flag — each command wires it — so `db:refresh --direct` fell through to the
+ * stage branch and `resolveConfig(undefined)` picked the DEFAULT stage. An operator asking for a
+ * direct dev refresh could refresh a deployed stage's matviews instead, believing the flag had
+ * scoped them locally. A documented flag that silently does nothing is the same class as the
+ * refusal that recommended `--database-url`: the tool's own words sending the operator somewhere
+ * they did not choose.
  */
 
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { loadDeclaredDerived } from '../declared-derived.js';
 import { executeRefresh, matviewIdentities, type RefreshRun } from '../refresh-execute.js';
 import { resolveConfig, opsFunction } from '../config.js';
+import { resolveOperatorUrlViaStage } from '../direct-venue.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info } from '../output.js';
 
@@ -57,9 +68,26 @@ export async function dbRefreshCommand(flags: Record<string, string>): Promise<v
     process.exit(1);
   }
 
-  // Two venues, mirroring the reconcile lane:
+  // `--stage --direct` (the shared direct venue): resolve the stage's OPERATOR connection from
+  // its ops Lambda and refresh CLI-side on an unbounded clock. The URL lives in this process's
+  // memory only — never printed, never written, never on argv. Same resolution db:apply,
+  // db:reconcile, db:backfill and db:swap use.
+  if (dbSource.kind === 'stage' && flags.direct === 'true') {
+    try {
+      step('Resolving the operator connection from the stage (--direct)...');
+      const op = await resolveOperatorUrlViaStage(flags.stage);
+      info(`operator credential resolved (${op.source}) — refreshing CLI-side, unbounded clock.`);
+      dbSource = { kind: 'url', url: op.url, from: 'operator' };
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+  }
+
+  // Three venues, mirroring the reconcile lane:
   //  - a deployed stage runs the whole refresh in the ops Lambda on the operator connection
   //    (the db:refresh action) — no raw URL on the operator's machine, the whole point.
+  //  - --stage --direct resolves that same operator credential and runs CLI-side, unbounded.
   //  - a direct URL refreshes locally (dev).
   let end: (() => Promise<void>) | undefined;
   try {
@@ -79,7 +107,7 @@ export async function dbRefreshCommand(flags: Record<string, string>): Promise<v
       if (result?.error) {
         fail(`db:refresh failed: ${result.error}`);
         if (/Unknown action/i.test(String(result.error))) {
-          info('The deployed handler predates the db:refresh ops action (needs @everystack/server >= 0.4.9). Upgrade the server, or refresh direct: db:refresh --database-url <url>.');
+          info('The deployed handler predates the db:refresh ops action (needs @everystack/server >= 0.4.9). Upgrade the server, or refresh credential-free over the direct lane: db:refresh --stage ' + (flags.stage ?? '<stage>') + ' --direct. (--database-url <url> is the local venue — against a deployed stage it puts a privileged connection string on argv.)');
         }
         process.exit(1);
       }

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

@@ -31,6 +31,7 @@ import { pairedDerivedSchemas, renderPairedDerivedBuild, renderSwapSchemaUsage,
 import { introspectDerived } from '../derived-introspect.js';
 import { legacyFunctionIdentity } from '../pg-argtypes.js';
 import { createUrlRunner } from '../db-source.js';
+import { borrowedSessionRunner, type SessionRunner } from '../session.js';
 import type { QueryRunner } from '../authz-contract.js';
 import { executeSwap, type SwapVerdict } from '../swap-execute.js';
 import { startHeartbeat, humanElapsed } from '../swap-heartbeat.js';
@@ -626,14 +627,14 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
   }
   const artifactFingerprint = artifact.fingerprint;
 
-  const { runner, end } = await createUrlRunner(url);
+  const { runner, session, end } = await createUrlRunner(url);
   try {
     step(`Swapping ${schema} — gate, land incoming, atomic swap, verify...`);
     // One operator mutates a database at a time — the swap is a whole-schema replacement.
     const res = await withMutationLease(
       runner,
       { verb: 'db:swap', actor: process.env.USER ?? 'unknown' },
-      () => executeSwap(runner, {
+      () => executeSwap(runner, session, {
         models, schema,
         artifactFingerprint,
         declaredFingerprint,
@@ -659,8 +660,8 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
         // later, for an unrelated edit — sees the whole layer as drift and rebuilds it under
         // ACCESS EXCLUSIVE. The objects are correct; only the bookkeeping was missing.
         recordProvenance: paired.length
-          ? async (r) => {
-              const live = await introspectDerived(r);
+          ? async (r, s) => {
+              const live = await introspectDerived(s);
               const prov = renderPairedProvenance(declaredDerivedObjects, live.objects, schema, paired);
               for (const st of prov.statements) await r(st);
               if (prov.recorded.length === 0) {

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

@@ -48,6 +48,7 @@ import { fingerprintModels } from '../schema-fingerprint.js';
 import { compileDrizzleSource } from '../schema-source.js';
 import type { SourceFile } from '../derived-source.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
+import { borrowedSessionRunner, type SessionRunner } from '../session.js';
 import { planBackfills, readBackfillLog } from '../backfill.js';
 import { resolveModelsPath } from '../models-path.js';
 import { executeReconcile, buildReconcileReport, type ReconcileRun } from './db-reconcile.js';
@@ -113,26 +114,27 @@ export interface SyncRun {
  */
 export async function executeSync(
   runner: QueryRunner,
+  session: SessionRunner,
   models: ModelDescriptor[],
   options: SyncOptions = {},
   hooks: SyncHooks = {},
 ): Promise<SyncRun> {
-  const current = await introspectSchema(runner);
-  const liveAuthz = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+  const current = await introspectSchema(session);
+  const liveAuthz = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
   const statements = generateMigrationSql(models, current, {
     allowDrops: options.allowDrops, liveAuthz, sequences: options.sequences,
     governedRoles: options.governedRoles,
   });
   hooks.onStatePlan?.(statements, classifyGeneratedStatements(statements));
 
-  const state = await applyStateAndVerify(runner, models, statements, current, liveAuthz, {
+  const state = await applyStateAndVerify(runner, session, models, statements, current, liveAuthz, {
     allowDrops: options.allowDrops, sequences: options.sequences,
     actor: options.actor, gitRef: options.gitRef, now: options.now,
   });
   hooks.onStateDone?.(state);
 
   // The declared derived layer is the one compute stream; nothing declared = skipped.
-  const compute = !options.declared?.length ? null : await executeReconcile(runner, {
+  const compute = !options.declared?.length ? null : await executeReconcile(runner, session, {
     apply: true,
     baseline: options.baseline,
     rebaseline: options.rebaseline,
@@ -303,11 +305,12 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
   }
 
   step(connectingVia(dbSource));
-  const { runner, end } = await createUrlRunner(dbSource.url);
+  const { runner, session, end } = await createUrlRunner(dbSource.url);
 
   try {
     const run = await executeSync(
       runner,
+      session,
       models,
       {
         declared: declaredDb?.objects,

package/src/cli/commands/db.ts

@@ -610,7 +610,8 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
         fail(`db:provision failed: ${err.message}`);
         if (/Unknown action/i.test(String(err.message))) {
           info('The deployed handler has no dbPlugin (no Ops Lambda), and no ADMIN_DATABASE_URL secret is set.');
-          info('Provision directly: everystack db:provision --stage <stage> --database-url <master-url> (once), or set the ADMIN_DATABASE_URL secret and use --direct.');
+          info('Preferred: set the secret once — everystack secrets set ADMIN_DATABASE_URL <url> --stage <stage> — then everystack db:provision --stage <stage> --direct reads it internally and the credential never reaches argv.');
+          info('Bootstrap fallback, when no secret exists yet: everystack db:provision --stage <stage> --database-url <master-url>. This puts the master credential on the command line (shell history, ps, CI logs) — do it once, then use --direct.');
         }
         for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
         process.exit(1);

package/src/cli/db-build.ts

@@ -107,10 +107,10 @@ export async function buildIntoDatabase(
   models: ModelDescriptor[],
   options: BuildOptions = {},
 ): Promise<BuildResult> {
-  const { runner, end } = await createUrlRunner(url);
+  const { runner, session, end } = await createUrlRunner(url);
   try {
     const createdRoles = await ensureContractRoles(runner, models);
-    const run = await executeSync(runner, models, {
+    const run = await executeSync(runner, session, models, {
       declared: options.declared,
       sequences: options.sequences,
       actor: options.actor ?? 'db-build',

package/src/cli/db-source.ts

@@ -25,6 +25,7 @@
  */
 
 import type { QueryRunner } from './authz-contract.js';
+import { buildSearchPathSql, type SessionRunner, type SessionResult } from './session.js';
 
 export type DbSource =
   | { kind: 'url'; url: string; from: 'flag' | 'env' | 'admin-env' | 'operator' }
@@ -65,10 +66,61 @@ export function connectingVia(source: Extract<DbSource, { kind: 'url' }>): strin
 
 export interface UrlRunner {
   runner: QueryRunner;
+  /**
+   * The direct lane's `SessionRunner` — N statements in ONE postgres.js transaction on
+   * the single connection. The stage lane's twin is `lambdaSessionRunner` (one invoke,
+   * one container); both honor the same ordering, `SET LOCAL` and `allowFailure` rules,
+   * so a caller typed against `SessionRunner` reads identically on either venue.
+   */
+  session: SessionRunner;
   /** Close the client so the process can exit cleanly. */
   end: () => Promise<void>;
 }
 
+/**
+ * Build a `SessionRunner` over a postgres.js client whose pool is a single connection.
+ *
+ * `sql.begin` holds that one connection for the whole callback, so every statement here
+ * shares a session by construction. The `searchPath` pin is `SET LOCAL` (it reverts with
+ * the transaction, never outliving its command) and consumes no result slot.
+ *
+ * An `allowFailure` statement rides `tx.savepoint`, the DRIVER's savepoint — not a
+ * hand-issued `SAVEPOINT` / `ROLLBACK TO SAVEPOINT` pair. postgres.js records any query
+ * error raised inside a transaction scope and re-throws it after the callback returns, so
+ * catching the error ourselves recovers the database and still loses the session. Its
+ * savepoint opens a nested scope with its own error bookkeeping, which is the only shape
+ * that survives. (Proven on a live PostgreSQL: the hand-rolled version passed against a
+ * fake and failed against the driver.)
+ */
+export function sessionRunnerOver(sql: any): SessionRunner {
+  return async (statements, opts) => {
+    const stmts = statements.map((s) => (typeof s === 'string' ? { sql: s } : s));
+    const results: SessionResult[] = [];
+    await sql.begin(async (tx: any) => {
+      if (opts?.isolation) await tx.unsafe(`SET TRANSACTION ISOLATION LEVEL ${opts.isolation}`);
+      if (opts?.readOnly) await tx.unsafe('SET TRANSACTION READ ONLY');
+      if (opts?.searchPath !== undefined) {
+        await tx.unsafe(buildSearchPathSql(String(opts.searchPath)));
+      }
+      for (const stmt of stmts) {
+        if (!stmt.allowFailure) {
+          results.push(Array.from(await tx.unsafe(stmt.sql)));
+          continue;
+        }
+        try {
+          results.push(
+            await tx.savepoint(async (sp: any) => Array.from(await sp.unsafe(stmt.sql))),
+          );
+        } catch (err: any) {
+          results.push({ everystackSessionError: true, message: err?.message || String(err) });
+        }
+      }
+    });
+    return results;
+  };
+}
+
+
 /**
  * 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.
@@ -101,6 +153,7 @@ export async function createUrlRunner(
   const sql = postgres(url, { max: 1, max_lifetime: null, onnotice: () => {}, ...sslDefaults(url) });
   return {
     runner: async (query: string) => Array.from(await sql.unsafe(query)),
+    session: sessionRunnerOver(sql),
     end: () => sql.end({ timeout: 5 }),
   };
 }
@@ -135,6 +188,8 @@ export async function createUrlPipelineRunner(
 export interface UrlProbeRunner {
   /** Read-only introspection, for the contract pull/diff. */
   runner: QueryRunner;
+  /** N statements on this one connection in one transaction — see sessionRunnerOver. */
+  session: SessionRunner;
   /** 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. */
@@ -166,6 +221,7 @@ export async function createUrlProbeRunner(
   const sql = postgres(url, { max: 1, max_lifetime: null, onnotice: () => {}, ...sslDefaults(url) });
   return {
     runner: async (query: string) => Array.from(await sql.unsafe(query)),
+    session: sessionRunnerOver(sql),
     probe: async (setup: string, read: string) => {
       let rows: any[] = [];
       try {