@everystack/cli 0.4.44 → 0.4.46

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

@@ -30,28 +30,22 @@ import { generateMigrationSql, unmodeledTables, formatMigrationFile, planMigrati
 import { introspectContract, type QueryRunner, type AuthzContract } from '../authz-contract.js';
 import { compileTableContract } from '../authz-compile.js';
 import { governedRoleSet, ungovernedGrants, renderGrantExemptions } from '../authz-reconcile.js';
+import { classifyAdoption, renderAdoptionReport } from '../authz-adoption-class.js';
+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[]> {
@@ -151,6 +145,48 @@ function reportGrantExemptions(liveAuthz: AuthzContract | undefined, models: Mod
   info(`Bring them under the reconciler with defineModule({ governedRoles: [...] }), or leave them exempt — either way they are listed here every run.`);
 }
 
+/**
+ * WHY does each authorization statement exist? — printed on every brownfield generate.
+ *
+ * A first plan against an existing database is long, and the length is not the problem: the
+ * problem is that nobody can tell which statements are everystack imposing its own spelling
+ * and which are real differences. `convention` is the count that indicts US, and driving it to
+ * zero is the whole point — so it is named first and never hidden behind a flag.
+ */
+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, 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, statements)) info(line);
+}
+
+/**
+ * WHO owns each governed table, and is that owner subject to its own RLS? — printed
+ * on every generate that has a live database.
+ *
+ * The owner never appears in the contract or the fingerprint: it is the dev user locally
+ * and the operator role on a stage, so committing it would drift on every environment.
+ * That is precisely why it must be SAID. A deployed owner that differs from the one the
+ * author has in mind is invisible in every artifact, and an unforced table lets that owner
+ * write past every policy in this repo. The report names the owner even when nothing is
+ * wrong, because silence here is what makes the mismatch impossible to notice.
+ */
+function reportOwnership(
+  liveAuthz: AuthzContract | undefined,
+  owners: readonly TableOwner[],
+  models: ModelDescriptor[],
+): void {
+  if (!liveAuthz) return; // greenfield — nothing owns anything yet
+  const rows = buildOwnershipReport(owners, liveAuthz, { models });
+  for (const line of renderOwnershipReport(rows)) {
+    if (line.trimStart().startsWith('!')) warn(line.trim());
+    else info(line);
+  }
+}
+
 async function readJournal(migrationsDir: string): Promise<Journal | null> {
   try {
     return JSON.parse(await fs.readFile(path.join(migrationsDir, 'meta', '_journal.json'), 'utf8'));
@@ -203,7 +239,9 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
   let declaredDb: DeclaredDerived | null = null;
   let current;
   let liveAuthz;
+  let liveOwners: TableOwner[] = [];
   let runner!: QueryRunner;
+  let session!: SessionRunner;
   let end: (() => Promise<void>) | undefined;
   try {
     step(`Loading models from ${modelsPath}...`);
@@ -225,17 +263,21 @@ 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);
     if (!apply) await end?.();
   } catch (err: any) {
     fail(err.message);
@@ -257,6 +299,8 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
   // ungoverned grantee's privileges alone rather than revoking them; that is only
   // defensible because the artifact says exactly whose access it chose not to govern.
   reportGrantExemptions(liveAuthz, models, declaredDb?.governedRoles ?? []);
+  reportAdoptionClasses(liveAuthz, models);
+  reportOwnership(liveAuthz, liveOwners, models);
   console.log('');
   if (statements.length === 0) {
     success(`db:generate — the live database already matches the models. ${dryRun ? 'Nothing to preview.' : 'No migration written.'}`);
@@ -302,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,13 +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 { introspectSchema } from '../schema-introspect.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, 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';
@@ -30,16 +40,18 @@ 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 } from '../output.js';
+import { step, success, fail, info, warn, reserveStdoutForData } from '../output.js';
 
 const DEFAULT_OUT = 'db.plan.json';
 
@@ -61,6 +73,12 @@ function isGitIgnored(file: string): boolean {
 }
 
 export async function dbPlanCommand(flags: Record<string, string>): Promise<void> {
+  const out = flags.out || DEFAULT_OUT;
+  // `--out -` makes stdout the artifact. Declared before anything prints, so the summary,
+  // the adoption report and the ownership report land on stderr and the plan JSON is the
+  // only thing on stdout — otherwise `db:plan --out - | jq` reads a report as its input.
+  if (out === '-') reserveStdoutForData();
+
   let dbSource: DbSource;
   try {
     dbSource = resolveDbSource(flags);
@@ -81,20 +99,44 @@ 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);
     // The modules' widened governed-role set. A barrel that exports only `models` has none,
     // which is the greenfield default: govern exactly what the models name.
     let declaredGovernedRoles: string[] = [];
@@ -134,7 +176,19 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       process.exit(1);
     }
 
-    const out = flags.out || DEFAULT_OUT;
+    // 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);
@@ -145,6 +199,32 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     for (const line of buildPlanSummary(plan)) info(line);
     info(`plan_ref: ${planHash(plan).slice(0, 12)}`);
 
+    // WHY does each authorization statement exist? — the same report db:generate prints,
+    // on the artifact a human actually reviews before applying.
+    //
+    // Re-DERIVED from live every mint, never stored: a recorded claim about what the models
+    // fail to capture goes stale the moment someone closes the gap, and a stale note is worse
+    // than none. `capability` is the count that says "this plan removes something the model
+    // cannot express" — the operator reading this is the last one who can catch it.
+    const adoption = classifyAdoption(declaredAuthz, contract, { governedRoles: governedRoleSet(declaredAuthz, declaredGovernedRoles) });
+    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, 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
+    // about THIS target, and the target is the one thing a committed artifact cannot carry.
+    for (const line of renderOwnershipReport(buildOwnershipReport(owners, contract, { models }))) {
+      if (line.trimStart().startsWith('!')) warn(line.trim());
+      else info(line);
+    }
+
     // The fast-forward rule, warn-only at mint time (db:apply enforces it):
     // a stale checkout mints a legal-looking plan whose edge REVERTS merged
     // work — say so on the review surface, where a human still reads it.

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
@@ -34,14 +38,16 @@ import { fingerprintLive } from '../schema-fingerprint.js';
 import { ungovernedGrants, ALWAYS_GOVERNED, type GrantExemption } from '../authz-reconcile.js';
 import { buildStageBaseline, mergeBaseline, readBaselineFile, writeBaselineFile, BASELINE_FILE } from '../authz-baseline.js';
 import { introspectDerived, type DerivedCatalog } from '../derived-introspect.js';
-import { introspectContract, type TableContract } from '../authz-contract.js';
+import { introspectContract, type TableContract, type AuthzContract } from '../authz-contract.js';
+import { introspectTableOwners, buildOwnershipReport, renderOwnershipReport, type TableOwner } from '../authz-ownership.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { renderDerivedSource, renderDerivedFile, type DerivedRenderResult } from '../derived-render.js';
 import { renderModelSource, renderModelFiles, pullableTables, modelVarName, ABILITY_PRESETS } from '../model-render.js';
 import type { QueryRunner } from '../authz-contract.js';
 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';
 
@@ -101,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';
 
@@ -150,32 +147,42 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   /** Adoption observation — the foreign grantees present, and what the claim is true OF. */
   let pulledExemptions: GrantExemption[] = [];
   let pulledFingerprint = '';
+  /** Live ownership — reported, never rendered into a model (it is environment-specific). */
+  let liveContract: AuthzContract | undefined;
+  let liveOwners: TableOwner[] = [];
   let derivedCatalog: DerivedCatalog | undefined;
   let matviewColumns: Map<string, ColumnSchema[]> | undefined;
   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.
+      // It is read to be SAID, on the one surface that is looking at the database.
+      liveOwners = await introspectTableOwners(runner);
       liveAuthz = new Map(contract.tables.map((t) => [t.table, t]));
       detail(`${liveAuthz.size} table(s) carry authorization.`);
       // Roles outside the model vocabulary (anon/authenticated/admin) are usually ONE
@@ -243,6 +250,16 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     process.exit(1);
   }
 
+  // WHO owns the tables being pulled. Nothing is FLAGGED here: flagging needs a declared
+  // write principal to contradict, and the models this pull is about to write do not exist
+  // yet. Naming the owner is the half the pull genuinely saw — and the half that vanishes
+  // from every artifact afterwards, because the contract excludes the owner on purpose.
+  if (liveContract) {
+    for (const line of renderOwnershipReport(
+      buildOwnershipReport(liveOwners, liveContract, { tables: pulled.map((t) => t.table) }),
+    )) note(line);
+  }
+
   // The derived layer (B5): rendered from the live catalog with dependsOn from the real
   // edge graph. Everything inexpressible is a stderr warning AND an inline FIXME.
   const knownTables = new Map(pulled.map((t) => [t.table, modelVarName(t.table)]));
@@ -338,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 {