@everystack/cli 0.4.45 → 0.4.47

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

@@ -18,14 +18,19 @@
  *      is exact even on brownfield targets (mint predicted it with the
  *      unmodeled tables merged in). A mismatch here is a real fault, loud.
  *
- * Needs a direct connection (--database-url / DATABASE_URL): apply writes.
+ * Two lanes. DIRECT (--database-url / --stage --direct) executes CLI-side over
+ * one session. STAGE (--stage) executes credential-free in the ops Lambda —
+ * and reads over `lambdaQueryRunner`, one Lambda invoke per catalog query, so a
+ * single introspection can be assembled from several containers holding
+ * connections to different databases. That lane therefore reads the stage TWICE
+ * and refuses a disagreement, reports agreement as a non-detection (it cannot
+ * verify read consistency), and refuses a DESTRUCTIVE plan outright — losing
+ * data on a read that cannot be verified is not a trade the ceremony can buy.
+ * See stage-read-consistency.ts.
  */
 
 import fs from 'node:fs/promises';
 import { type QueryRunner } from '../authz-contract.js';
-import { introspectSchema } from '../schema-introspect.js';
-import { introspectContract } from '../authz-contract.js';
-import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { currentGitRef } from '../state-apply.js';
 import { planHash, PLAN_VERSION, type EdgePlan } from '../edge-plan.js';
 import { verifyDescent, type DescentVerdict, type LiveState } from '../git-descent.js';
@@ -37,12 +42,14 @@ import { compileTableContract } from '../authz-compile.js';
 import { governedRoleSet, ungovernedGrants } from '../authz-reconcile.js';
 import { readBaselineFile, checkAgainstBaseline, baselineRefusal } from '../authz-baseline.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, lambdaQueryRunner } from '../aws.js';
+import { invokeAction, lambdaQueryRunner, lambdaSessionRunner } from '../aws.js';
 import { executeApplyPlan, type ApplyPlanResult } from '../apply-execute.js';
 import { estimateOpsRuntimeFit } from '../ops-fit.js';
 import { resolveOperatorUrlViaStage } from '../direct-venue.js';
 import { withMutationLease, MutationLeaseError } from '../mutation-lease.js';
+import { readStageStateTwice, stageDestructiveRefusal } from '../stage-read-consistency.js';
 import { step, success, fail, info, warn } from '../output.js';
 
 // The apply core lives in apply-execute.ts (shared with the ops Lambda's
@@ -128,20 +135,34 @@ async function applyPlanViaStage(
 
   info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
 
+  // THE STAGE LANE'S READ GUARD, before anything is dispatched. Each introspection is
+  // one session, but a full read is two of them (state, then authz) and they can be
+  // answered by two containers at two moments. Read the stage twice and refuse a
+  // disagreement — the apply never starts. Deliberately OUTSIDE the try below: this
+  // refusal must exit as itself, not as "Apply failed".
+  step('Reading the stage TWICE (state and authz are separate ops-Lambda invokes)...');
+  const readSession = lambdaSessionRunner(region, fn);
+  const readPair = await readStageStateTwice(readSession).catch((err: any) => {
+    fail(`Apply failed: could not read the stage — ${err.message}`);
+    process.exit(1);
+  });
+  if (!readPair.ok) {
+    fail(readPair.reason);
+    process.exit(1);
+  }
+  warn(readPair.warning);
+
   try {
     // Descent — the fast-forward rule needs the git checkout, so the CLI
-    // decides it (the Lambda has no checkout). Read the stage's state read-only
-    // via the ops Lambda's db:query action, run the rule locally, and hand the
-    // verdict to the write action, which enforces + records it in order.
+    // decides it (the Lambda has no checkout). It runs against the state the
+    // double read already produced (no third trip), and the verdict goes to the
+    // write action, which enforces + records it in order.
     let descentVerdict: { ok: true } | { ok: false; reason: string };
     if (forceDescent !== undefined) {
       warn(`DESCENT FORCED — the fast-forward rule is bypassed for this apply. Snapshot on record: ${forceDescent}.`);
       descentVerdict = { ok: true };
     } else {
-      step('Asking the stage its state (read-only via the ops Lambda)...');
-      const readRunner = lambdaQueryRunner(region, fn);
-      const snapshot = await introspectSchema(readRunner);
-      const contract = await introspectContract(readRunner, contractFunctionRow, FUNCTIONS_SQL);
+      const { snapshot, contract } = readPair.state;
       step("Descent: searching git for the commit that declares the stage's state...");
       const verdict = await verifyDescent(resolveModelsPath(flags.models), { snapshot, contract }, {});
       switch (verdict.status) {
@@ -166,6 +187,11 @@ async function applyPlanViaStage(
     // and checks it against the stage's declared approver set (SSM). The safety
     // net is a VERIFIED backup: the Lambda auto-resolves the stage's newest (or
     // the id in --snapshot-ref) and refuses unless it covers this plan. --confirm always.
+    //
+    // CURRENTLY UNREACHABLE: dbApplyCommand refuses every destructive plan on the
+    // stage lane before it gets here (read consistency cannot be guaranteed on this
+    // lane). Kept intact and second in line, so lifting that refusal restores the
+    // full ceremony rather than silently shipping without one.
     let authorityVerdict: AuthorityVerdict | undefined;
     if (plan.destructive > 0) {
       const shape = `${plan.classification.drops} drop(s), ${plan.classification.narrowings} narrowing type change(s)`;
@@ -272,6 +298,16 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
   // Deployed stage, no direct URL: the write runs in the ops Lambda — the
   // operator never holds a database URL. --database-url stays local-only.
   if (dbSource.kind === 'stage') {
+    // A DESTRUCTIVE plan does not run on this lane at all — no ceremony lifts it.
+    // The stage lane's fingerprint (the concurrency lock) can be assembled from
+    // several ops-Lambda containers, and the double read below only DETECTS that;
+    // it cannot rule it out. Dropping data on a read that may be a collage is the
+    // one trade never worth making, so the destructive path is the direct lane's.
+    if (plan.destructive > 0) {
+      const shape = `${plan.classification.drops} drop(s), ${plan.classification.narrowings} narrowing type change(s)`;
+      fail(stageDestructiveRefusal(shape, planPath, flags.stage));
+      process.exit(1);
+    }
     // Will this edge fit the ops-Lambda's 900-second clock? If not, refuse up front and
     // name --direct (credential-free, unbounded) instead of burning 15 minutes to learn it.
     const fit = estimateOpsRuntimeFit(plan);
@@ -295,13 +331,29 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
       fail(`This plan is DESTRUCTIVE — ${plan.destructive} statement(s) lose data (${shape}). Explicit confirmation is required, always: re-run with --confirm.`);
       process.exit(1);
     }
-    // A DIRECT apply is operator-attested: the operator holds the URL, so the safety net is a backup
-    // they took and NAME here. (The credential-free path — db:apply --plan … --stage <name>, WITHOUT
-    // --direct — auto-resolves and verifies the stage's latest backup server-side; a direct/bare
-    // connection has no ops Lambda to verify against, so the ref is required and attested.)
+    // A DIRECT apply is operator-attested: the safety net is a backup the operator took and
+    // NAMES here, because this lane has no ops Lambda verifying one server-side.
+    //
+    // This used to end by offering "or drop --direct and let the credential-free --stage apply
+    // auto-verify your latest backup". THAT ADVICE CANNOT BE FOLLOWED. Auto-verification is
+    // real, but only for NON-destructive stage applies — and every plan reaching this block is
+    // destructive, so dropping --direct lands on the outright refusal above (the `--stage`
+    // destructive gate). It sent operators from a lane that works to one that refuses, and the
+    // refusal's own text then pointed them at --database-url. Two wrong signposts in a row are
+    // how a consumer ended up printing a privileged DSN to do something --direct already did.
+    //
+    // For a destructive plan there is exactly one remedy: take a safety point and name it.
     if (!flags['snapshot-ref']) {
-      const takeIt = `everystack db:backup${flags.stage ? ` --stage ${flags.stage}` : ''}`;
-      fail(`This plan is DESTRUCTIVE (${shape}) over a direct connection — the apply does not snapshot for you. Take a safety point (${takeIt}) and name it: --snapshot-ref <id>. Or drop --direct and let the credential-free --stage apply auto-verify your latest backup.`);
+      const stageArg = flags.stage ? ` --stage ${flags.stage}` : '';
+      const takeIt = `everystack db:backup${stageArg}`;
+      const lane = flags.stage
+        ? `${stageArg.trim()} --direct`
+        : '--database-url <url>';
+      fail(
+        `This plan is DESTRUCTIVE (${shape}) over a direct connection — the apply does not snapshot for you. `
+        + `Take a safety point (${takeIt}) and name it: everystack db:apply --plan ${planPath} ${lane} --confirm --snapshot-ref <id>. `
+        + 'A destructive plan always requires an attested --snapshot-ref; there is no lane that takes one for you.',
+      );
       process.exit(1);
     }
     if (flags.stage) {
@@ -328,7 +380,7 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
   }
 
   step(connectingVia(dbSource));
-  const { runner, end } = await createUrlRunner(dbSource.url);
+  const { runner, session, end } = await createUrlRunner(dbSource.url);
 
   try {
     info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
@@ -342,7 +394,7 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     const result = await withMutationLease(
       runner,
       { verb: 'db:apply', actor: process.env.USER ?? 'unknown' },
-      () => executeApplyPlan(runner, plan, {
+      () => executeApplyPlan(runner, session, plan, {
       actor: process.env.USER ?? null,
       gitRef: currentGitRef() ?? plan.gitRef,
       ...(verifyAuthority ? { verifyAuthority } : {}),
@@ -371,6 +423,16 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
               info('descent: fresh target (no tables) — nothing to protect, bootstrapping.');
               return { ok: true };
             case 'no-git':
+              // A DESTRUCTIVE plan may not ride an accidental waiver: the fast-forward
+              // rule's verdict must never depend on which directory the operator ran
+              // from. Unverifiable + destructive ⇒ the waiver must be the deliberate
+              // ceremony (--force-descent <snapshot-ref> --confirm), not a warning.
+              if (plan.destructive > 0) {
+                return {
+                  ok: false,
+                  reason: 'descent: not a git checkout, and this plan is DESTRUCTIVE — the fast-forward rule cannot be verified here, so waive it deliberately: re-run with --force-descent <snapshot-ref> --confirm.',
+                };
+              }
               warn('descent: not a git checkout — the fast-forward rule cannot be verified here.');
               return { ok: true };
             case 'diverged':

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-backfill.ts

@@ -87,7 +87,7 @@ async function runBackfillViaStage(
   if (res?.error) {
     fail(`db:backfill failed: ${res.error}`);
     if (/Unknown action/i.test(String(res.error))) {
-      info('The deployed handler predates the db:backfill ops action. Upgrade @everystack/server, or run direct: db:backfill --apply --database-url <url> (or --stage --direct).');
+      info('The deployed handler predates the db:backfill ops action. Upgrade @everystack/server, or run credential-free over the direct lane: db:backfill --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.)');
     }
     process.exit(1);
   }

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

@@ -31,7 +31,18 @@ async function readStdin(): Promise<string> {
   return Buffer.concat(chunks).toString('utf8');
 }
 
-/** The app schemas the digest guard covers on the direct path (--schemas a,b; default public). */
+/**
+ * The schemas argument the digest query still ACCEPTS but no longer scopes by.
+ *
+ * `--schemas` never reached the stage path at all — the ops invoke sent only `{ sql, actor,
+ * stage }`, so a consumer who passed `--schemas auth,public` had it silently dropped and the
+ * server fell back to its own `options.schemas ?? ['public']`. Their 21 `auth.*` functions were
+ * outside the projection and the guard stayed silent on 43 schema statements.
+ *
+ * Rather than plumb the flag through, the digest now covers EVERY non-system schema
+ * (exec-digest.ts): a guard that can be scoped can be scoped to blindness. This is kept so the
+ * call sites read unchanged, and `--schemas` is now a documented no-op rather than a silent one.
+ */
 function directSchemas(flags: Record<string, string>): string[] {
   if (flags.schemas && flags.schemas !== 'true') {
     return flags.schemas.split(',').map((s) => s.trim()).filter(Boolean);
@@ -39,6 +50,13 @@ function directSchemas(flags: Record<string, string>): string[] {
   return ['public'];
 }
 
+/** Say it, rather than accept a flag that does nothing. */
+function noteSchemasIsNoLongerNeeded(flags: Record<string, string>): void {
+  if (flags.schemas && flags.schemas !== 'true') {
+    info('--schemas is no longer needed and no longer narrows anything: the DML-only guard now covers every non-system schema. (It used to default to `public`, which is how a file of auth.* functions once passed it.)');
+  }
+}
+
 function reportOk(res: { rowsAffected?: number[] }): void {
   const rows = res.rowsAffected ?? [];
   const total = rows.reduce((a, b) => a + b, 0);
@@ -70,6 +88,7 @@ export async function dbExecCommand(flags: Record<string, string>, file?: string
 
   const source = resolveDbSource(flags);
   const actor = process.env.USER ?? null;
+  noteSchemasIsNoLongerNeeded(flags);
 
   // --- Stage venue: ship the SQL to the ops Lambda's db:exec action (operator holds no URL). ---
   if (source.kind === 'stage') {

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) {