@everystack/cli 0.4.45 → 0.4.46

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

@@ -57,22 +57,14 @@ 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 { borrowedSessionRunner, type SessionRunner } from '../session.js';
+import { invokeAction, lambdaQueryRunner, lambdaSessionRunner } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
 import { opsAdviceLines, IAM_ADVICE } from '../ops-advice.js';
 import { loadModels } from './db-generate.js';
 
 const DEFAULT_DIR = 'authz';
 
-/** 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 ?? [];
-  };
-}
-
 /**
  * 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
@@ -81,6 +73,8 @@ function lambdaRunner(region: string, fn: string): QueryRunner {
 interface AuthzVenue {
   /** Read-only introspection. */
   runner: QueryRunner;
+  /** The consistent multi-statement read — what every introspection takes. */
+  session: SessionRunner;
   /** Self-reverting red-team probe (writes, always rolled back). */
   probe: (setup: string, read: string) => Promise<any[]>;
   /** Human-readable venue, printed with every verdict. */
@@ -97,15 +91,16 @@ 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' };
+    const { runner, session, probe, end } = await createUrlProbeRunner(source.url);
+    return { runner, session, probe, end, label: 'direct connection' };
   }
   step('Resolving deployed config...');
   const config = await resolveConfig(flags.stage);
   const fn = opsFunction(config);
   info(`Region: ${config.region}, Function: ${fn}`);
   return {
-    runner: lambdaRunner(config.region, fn),
+    runner: lambdaQueryRunner(config.region, fn),
+    session: lambdaSessionRunner(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);
@@ -120,7 +115,7 @@ async function introspectVenue(flags: Record<string, string>): Promise<{ contrac
   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 };
+    return { contract: await introspectContract(venue.session, contractFunctionRow, FUNCTIONS_SQL), label: venue.label };
   } finally {
     await venue.end();
   }

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

@@ -21,46 +21,70 @@ import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import {
   fingerprintLive,
   fingerprintModels,
+  governedRolesForModels,
   mapUnfingerprintedRows,
   UNFINGERPRINTED_SQL,
   type UnfingerprintedObject,
 } from '../schema-fingerprint.js';
+import { predictLiveFingerprint, governedLiveFingerprint } from '../edge-plan.js';
 import { resolveModelsPath } from '../models-path.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
+import { borrowedSessionRunner, INTROSPECTION_SESSION, type SessionRunner } from '../session.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';
 import { loadModels } from './db-generate.js';
 import { loadDeclaredDerived } from '../declared-derived.js';
 import type { SequenceDescriptor } from '@everystack/model';
 
 export interface FingerprintStatus {
+  /** The RAW live hash — everything introspected. The flavor plan.from and the backup chain use. */
   live: string;
+  /**
+   * The GOVERNED live hash — the live state filtered through the models' governed-role set,
+   * i.e. "the state the models describe". Present only when models loaded; equals `live` when
+   * no foreign grantee holds anything. THIS is the half MATCH compares — a live grant nothing
+   * will ever reconcile must not keep MATCH unreachable (the v4 rule, wired to the verdict).
+   */
+  governedLive?: string;
   declared: string | null;
+  /**
+   * The predicted endpoint: models + unmodeled live tables riding through, governed —
+   * `db:generate`'s no-op state. Equals `declared` when nothing is unmodeled. MATCH is
+   * `predicted === governedLive` (the declares-test): the identity is with what generate
+   * MANAGES, and generate manages only declared tables.
+   */
+  predicted?: string;
   match: boolean | null;
   unfingerprinted: UnfingerprintedObject[];
 }
 
 /** The testable core: live fingerprint, declared fingerprint, verdict, honesty report. */
 export async function computeFingerprintStatus(
-  runner: QueryRunner,
+  session: SessionRunner,
   models: ModelDescriptor[] | null,
   sequences?: SequenceDescriptor[],
+  governedExtras?: readonly string[],
 ): Promise<FingerprintStatus> {
-  const snapshot = await introspectSchema(runner);
-  const contract = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+  const snapshot = await introspectSchema(session);
+  const contract = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
+  // Rides the SAME session policy as the two introspections above. It used to be issued
+  // bare, outside any search_path pin — the one read in this command that was not
+  // canonicalized, and on the stage lane its own separate invoke.
+  const [unfingerprintedRows] = await session([UNFINGERPRINTED_SQL], INTROSPECTION_SESSION);
   const live = fingerprintLive(snapshot, contract).hash;
   const declared = models ? fingerprintModels(models, { sequences }).hash : null;
-  const unfingerprinted = mapUnfingerprintedRows((await runner(UNFINGERPRINTED_SQL)) as any[]);
-  return { live, declared, match: declared === null ? null : live === declared, unfingerprinted };
-}
-
-/** 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 ?? [];
+  const governedRoles = models ? governedRolesForModels(models, governedExtras) : undefined;
+  const governedLive = governedRoles ? governedLiveFingerprint(snapshot, contract, governedRoles) : undefined;
+  const predicted = models ? predictLiveFingerprint(models, snapshot, contract, { governedRoles }) : undefined;
+  const unfingerprinted = mapUnfingerprintedRows(unfingerprintedRows as any[]);
+  return {
+    live,
+    ...(governedLive !== undefined ? { governedLive } : {}),
+    declared,
+    ...(predicted !== undefined ? { predicted } : {}),
+    match: declared === null ? null : predicted === governedLive,
+    unfingerprinted,
   };
 }
 
@@ -76,9 +100,12 @@ export async function dbFingerprintCommand(flags: Record<string, string>): Promi
   const modelsPath = resolveModelsPath(flags.models);
   let models: ModelDescriptor[] | null = null;
   let sequences: SequenceDescriptor[] | undefined;
+  let governedExtras: string[] | undefined;
   try {
     models = await loadModels(modelsPath);
-    sequences = (await loadDeclaredDerived(flags.models))?.sequences;
+    const declared = await loadDeclaredDerived(flags.models);
+    sequences = declared?.sequences;
+    governedExtras = declared?.governedRoles;
   } catch (err: any) {
     // Two very different situations used to land here identically.
     //
@@ -100,18 +127,21 @@ export async function dbFingerprintCommand(flags: Record<string, string>): Promi
   }
 
   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 = lambdaRunner(config.region, opsFunction(config));
+    runner = lambdaQueryRunner(config.region, opsFunction(config));
+    session = lambdaSessionRunner(config.region, opsFunction(config));
   }
 
   try {
-    const status = await computeFingerprintStatus(runner, models, sequences);
+    const status = await computeFingerprintStatus(session, models, sequences, governedExtras);
 
     if (flags.json === 'true') {
       console.log(JSON.stringify(status, null, 2));
@@ -120,7 +150,13 @@ export async function dbFingerprintCommand(flags: Record<string, string>): Promi
       if (status.declared === null) {
         warn(`declared: (no models barrel at ${modelsPath} — live-only)`);
       } else {
+        if (status.governedLive !== undefined && status.governedLive !== status.live) {
+          info(`governed: ${status.governedLive} (live state minus ungoverned grantees — the half MATCH compares)`);
+        }
         info(`declared: ${status.declared}`);
+        if (status.predicted !== undefined && status.predicted !== status.declared) {
+          info(`predicted: ${status.predicted} (declared + unmodeled tables riding through — generate's no-op state)`);
+        }
         if (status.match) success('MATCH — the database is the state the models declare.');
         else fail('MISMATCH — run `everystack db:generate` to see the difference as SQL.');
       }

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

@@ -34,26 +34,18 @@ import { classifyAdoption, renderAdoptionReport } from '../authz-adoption-class.
 import { introspectTableOwners, buildOwnershipReport, renderOwnershipReport, type TableOwner } from '../authz-ownership.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.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 { loadDeclaredDerived, assertNoHoles, type DeclaredDerived } from '../declared-derived.js';
 import { asModelComposeError, opsAdviceLines } from '../ops-advice.js';
 import { applyStateAndVerify, classifyGeneratedStatements, renderStatementHistogram, currentGitRef, type StateSyncOutcome } 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';
 
 const DEFAULT_MIGRATIONS = 'drizzle';
 const DEFAULT_SCHEMA_OUT = 'db/schema.generated.ts';
 
-/** 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 ?? [];
-  };
-}
-
 /** Import the app's Model barrel and return its `models` array (runs under tsx, so TS imports work).
  *  Every failure is the operator's own barrel — ModelComposeError, never dressed as IAM. */
 export async function loadModels(modelsPath: string): Promise<ModelDescriptor[]> {
@@ -164,11 +156,11 @@ function reportGrantExemptions(liveAuthz: AuthzContract | undefined, models: Mod
 function reportAdoptionClasses(liveAuthz: AuthzContract | undefined, models: ModelDescriptor[]): void {
   if (!liveAuthz) return; // greenfield — every statement is additive, nothing to adjudicate
   const declared: AuthzContract = { tables: models.map((m) => compileTableContract(m, {})), functions: [] };
-  const { counts } = classifyAdoption(declared, liveAuthz);
+  const { counts, statements } = classifyAdoption(declared, liveAuthz);
   const total = Object.values(counts).reduce((a, b) => a + b, 0);
   if (total === 0) return;
   info(`${total} authorization statement(s), by why they exist:`);
-  for (const line of renderAdoptionReport(counts)) info(line);
+  for (const line of renderAdoptionReport(counts, statements)) info(line);
 }
 
 /**
@@ -249,6 +241,7 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
   let liveAuthz;
   let liveOwners: TableOwner[] = [];
   let runner!: QueryRunner;
+  let session!: SessionRunner;
   let end: (() => Promise<void>) | undefined;
   try {
     step(`Loading models from ${modelsPath}...`);
@@ -270,17 +263,18 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     }
     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);
       info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
-      runner = lambdaRunner(config.region, opsFunction(config));
+      runner = lambdaQueryRunner(config.region, opsFunction(config));
+      session = lambdaSessionRunner(config.region, opsFunction(config));
     }
     step('Introspecting live database (columns + constraints)...');
-    current = await introspectSchema(runner);
+    current = await introspectSchema(session);
     step('Introspecting authorization (rls + grants + policies)...');
-    liveAuthz = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+    liveAuthz = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
     // Ownership rides the same connection: it is not part of the contract (it never
     // enters the fingerprint), but it decides whether the contract is actually in force.
     liveOwners = await introspectTableOwners(runner);
@@ -352,7 +346,7 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     step(`Applying ${classified.executable.length} statement(s) as one transaction, then verifying by re-diff...`);
     let outcome: StateSyncOutcome;
     try {
-      outcome = await applyStateAndVerify(runner, models, statements, current, liveAuthz, {
+      outcome = await applyStateAndVerify(runner, session, models, statements, current, liveAuthz, {
         allowDrops, sequences: declaredDb?.sequences, actor: process.env.USER ?? null, gitRef: currentGitRef(),
       });
     } catch (err: any) {

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

@@ -16,15 +16,23 @@
  * 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.
+ *
+ * On the STAGE lane the read is not atomic: every catalog query is its own
+ * Lambda invoke, so one introspection can be assembled from several containers
+ * holding connections to different databases, and the minted `from` would then
+ * describe no real state. That lane reads TWICE and refuses a disagreement.
+ * Agreement is a non-detection, not a verification — see
+ * stage-read-consistency.ts. The direct lane reads once, over one session.
  */
 
 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 +40,15 @@ 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 { 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';
@@ -89,20 +99,41 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
   }
 
   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 +176,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 +210,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';
@@ -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-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) {