@everystack/cli 0.4.72 → 0.4.74

package/src/cli/authz-reconcile.ts

@@ -18,6 +18,7 @@
 import type { AuthzContract, TableContract, PolicyContract, SequenceGrantContract } from './authz-contract';
 import { effectivePolicyCheck, parenthesizeOnce, isPolicyDead, isPolicySubsumed } from './authz-contract';
 import { matchPolicies } from './authz-identity';
+import { tablePoliciesEquivalent } from './authz-canonical';
 import { quoteQualified } from './pg-ident';
 
 /**
@@ -247,7 +248,8 @@ export function inheritedSequenceGrants(table: TableContract): Record<string, st
 function reconcileSequenceGrants(
   d: TableContract,
   liveSequences: readonly SequenceGrantContract[],
-  out: string[],
+  narrow: string[],
+  widen: string[],
   governed: ReadonlySet<string>,
 ): void {
   const declared = inheritedSequenceGrants(d);
@@ -275,8 +277,8 @@ function reconcileSequenceGrants(
       const role = grantee.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : grantee;
       const toRevoke = [...have].filter((p) => !want.has(p)).sort();
       const toGrant = [...want].filter((p) => !have.has(p)).sort();
-      if (toRevoke.length) out.push(`REVOKE ${toRevoke.join(', ')} ON SEQUENCE ${target} FROM ${role};`);
-      if (toGrant.length) out.push(`GRANT ${toGrant.join(', ')} ON SEQUENCE ${target} TO ${role};`);
+      if (toRevoke.length) narrow.push(`REVOKE ${toRevoke.join(', ')} ON SEQUENCE ${target} FROM ${role};`);
+      if (toGrant.length) widen.push(`GRANT ${toGrant.join(', ')} ON SEQUENCE ${target} TO ${role};`);
     }
   }
 }
@@ -293,6 +295,13 @@ export function emitReconcileSql(
   live: AuthzContract,
   opts: { governedRoles?: ReadonlySet<string> } = {},
 ): string[] {
+  // Condition C — two phases PER TABLE in one transaction: every access-REMOVING statement
+  // (policy DROP, REVOKE, RLS ENABLE/FORCE) before every access-ADDING one (policy CREATE, GRANT,
+  // RLS DISABLE/NO FORCE). The batch is atomic, so this is defence in depth — but it makes every
+  // prefix of the plan fail-safe: a partial application is never broader than both endpoints. A
+  // same-name policy replacement stays a DROP (narrow) then CREATE (widen), never co-existing.
+  // Per table, not global: grants and policies are table-scoped, so a widen on one table can
+  // never be exploited through another's narrow — and tables stay grouped, as the plan reads.
   const sql: string[] = [];
   const lTables = tableMap(live);
   // Default: govern exactly what the models name (plus the always-governed set). A caller
@@ -311,12 +320,15 @@ export function emitReconcileSql(
     // The contract keys on the bare `<schema>.<table>` (so the diff matches both producers);
     // the EMITTED SQL must quote it, or a reserved table name (`public.user`) is a syntax error.
     const table = quoteQualified(d.table);
-    reconcileRls(table, d, l, sql);
-    reconcilePolicies(table, d, l, sql, governed);
-    reconcileGrants(table, d, l, sql, governed);
-    reconcileColumnGrants(table, d, l, sql, governed);
+    const narrow: string[] = [];
+    const widen: string[] = [];
+    reconcileRls(table, d, l, narrow, widen);
+    reconcilePolicies(table, d, l, narrow, widen, governed);
+    reconcileGrants(table, d, l, narrow, widen, governed);
+    reconcileColumnGrants(table, d, l, narrow, widen, governed);
     // A6: the sequences behind this table's SERIAL columns inherit its grants (identity ones do not).
-    reconcileSequenceGrants(d, sequencesByTable.get(d.table) ?? [], sql, governed);
+    reconcileSequenceGrants(d, sequencesByTable.get(d.table) ?? [], narrow, widen, governed);
+    sql.push(...narrow, ...widen);
   }
 
   return sql;
@@ -339,29 +351,37 @@ export function emitReconcileSql(
  * already-enabled table is a no-op; the dump carried no grants).
  */
 export function emitSwapAuthzSql(declared: AuthzContract): string[] {
+  // Same narrow-before-widen shape as emitReconcileSql (Condition C), per table: RLS enable/force
+  // and the idempotent policy DROPs narrow; the CREATEs and GRANTs widen. Drop-BEFORE-create per
+  // policy is preserved (drop in the narrow phase, create in the widen phase of the same table),
+  // so no CREATE lands on a policy the dump restored.
   const sql: string[] = [];
   const governed = governedRoleSet(declared);
   for (const d of declared.tables) {
     const table = quoteQualified(d.table);
-    if (d.rls.enabled) sql.push(`ALTER TABLE ${table} ENABLE ROW LEVEL SECURITY;`);
-    if (d.rls.forced) sql.push(`ALTER TABLE ${table} FORCE ROW LEVEL SECURITY;`);
+    const narrow: string[] = [];
+    const widen: string[] = [];
+    if (d.rls.enabled) narrow.push(`ALTER TABLE ${table} ENABLE ROW LEVEL SECURITY;`);
+    if (d.rls.forced) narrow.push(`ALTER TABLE ${table} FORCE ROW LEVEL SECURITY;`);
     for (const p of d.policies) {
-      sql.push(policyDropSql(table, p.name)); // idempotent against the policy the dump restored
-      sql.push(policyCreateSql(table, p));
+      narrow.push(policyDropSql(table, p.name)); // idempotent against the policy the dump restored
+      widen.push(policyCreateSql(table, p));
     }
     // No live side here, so every grantee comes from the DECLARED contract and is
     // governed by definition — the exemption can never fire on this path.
-    reconcileGrants(table, d, undefined, sql, governed);
-    reconcileColumnGrants(table, d, undefined, sql, governed);
+    reconcileGrants(table, d, undefined, narrow, widen, governed);
+    reconcileColumnGrants(table, d, undefined, narrow, widen, governed);
+    sql.push(...narrow, ...widen);
   }
   return sql;
 }
 
-function reconcileRls(table: string, d: TableContract, l: TableContract | undefined, out: string[]): void {
-  if (d.rls.enabled && !l?.rls.enabled) out.push(`ALTER TABLE ${table} ENABLE ROW LEVEL SECURITY;`);
-  if (d.rls.forced && !l?.rls.forced) out.push(`ALTER TABLE ${table} FORCE ROW LEVEL SECURITY;`);
-  if (!d.rls.enabled && l?.rls.enabled) out.push(`ALTER TABLE ${table} DISABLE ROW LEVEL SECURITY;`);
-  if (!d.rls.forced && l?.rls.forced) out.push(`ALTER TABLE ${table} NO FORCE ROW LEVEL SECURITY;`);
+function reconcileRls(table: string, d: TableContract, l: TableContract | undefined, narrow: string[], widen: string[]): void {
+  // ENABLE / FORCE deny by default — narrowing. DISABLE / NO FORCE lift a restriction — widening.
+  if (d.rls.enabled && !l?.rls.enabled) narrow.push(`ALTER TABLE ${table} ENABLE ROW LEVEL SECURITY;`);
+  if (d.rls.forced && !l?.rls.forced) narrow.push(`ALTER TABLE ${table} FORCE ROW LEVEL SECURITY;`);
+  if (!d.rls.enabled && l?.rls.enabled) widen.push(`ALTER TABLE ${table} DISABLE ROW LEVEL SECURITY;`);
+  if (!d.rls.forced && l?.rls.forced) widen.push(`ALTER TABLE ${table} NO FORCE ROW LEVEL SECURITY;`);
 }
 
 /**
@@ -375,12 +395,20 @@ function reconcileRls(table: string, d: TableContract, l: TableContract | undefi
  * The matcher requires full field equality, so this can only turn a DROP + CREATE pair into a
  * no-op — never emit DDL the name-keyed version would not have emitted.
  */
-function reconcilePolicies(table: string, d: TableContract, l: TableContract | undefined, out: string[], governed: ReadonlySet<string>): void {
+function reconcilePolicies(table: string, d: TableContract, l: TableContract | undefined, narrow: string[], widen: string[], governed: ReadonlySet<string>): void {
+  // Condition B — gate on the canonical equivalence the fingerprint uses, so this surface and
+  // that one can never disagree about the same database. A live `FOR ALL` with a dead DELETE arm
+  // and the granular pull that omits DELETE are equal here; emitting the DROP + CREATE the
+  // per-command matcher would produce is exactly the MATCH-but-nonzero split this closes. Only
+  // when the states genuinely differ do we fall back to the per-policy matcher below, which can
+  // only over-emit churn, never under-emit a real authorization difference.
+  if (l && tablePoliciesEquivalent(d, l, governed)) return;
   const live = l?.policies ?? [];
   const m = matchPolicies(d.policies, live);
   const byName = new Map(live.map((p) => [p.name, p]));
 
-  // Drops first, so a replaced policy never briefly co-exists with its old form.
+  // Condition C: DROPs go to the narrow phase, CREATEs to the widen phase — a replaced policy is
+  // dropped (narrow) before it is re-created (widen), so it never co-exists with its old form.
   for (const name of m.toDrop) {
     // A live policy scoped ENTIRELY to roles the models do not govern is left alone, exactly
     // as reconcileGrants leaves that role's privileges alone. Without this the two lanes
@@ -411,7 +439,7 @@ function reconcilePolicies(table: string, d: TableContract, l: TableContract | u
     // drops the PUBLIC policy that was covering it, the role-scoped one stops being redundant
     // the moment the plan lands — and leaving it would keep access the model never declared.
     if (p && l && isPolicySubsumed(l, p) && isPolicySubsumed(d, p)) continue;
-    out.push(policyDropSql(table, name));
+    narrow.push(policyDropSql(table, name));
   }
   // Symmetric with the drop rule above, and required by the same identity: a DECLARED policy
   // the declared grants do not back is inert — it would authorize nothing the moment it
@@ -420,11 +448,11 @@ function reconcilePolicies(table: string, d: TableContract, l: TableContract | u
   // moment the model grants the privilege it polices.
   for (const p of m.toCreate) {
     if (isPolicyDead(d, p) || isPolicySubsumed(d, p)) continue;
-    out.push(policyCreateSql(table, p));
+    widen.push(policyCreateSql(table, p));
   }
 }
 
-function reconcileGrants(table: string, d: TableContract, l: TableContract | undefined, out: string[], governed: ReadonlySet<string>): void {
+function reconcileGrants(table: string, d: TableContract, l: TableContract | undefined, narrow: string[], widen: string[], governed: ReadonlySet<string>): void {
   const grantees = new Set([...Object.keys(d.grants), ...Object.keys(l?.grants ?? {})]);
   for (const grantee of [...grantees].sort()) {
     // A live grantee the declared authz does not govern is LEFT ALONE. The union below
@@ -439,8 +467,9 @@ function reconcileGrants(table: string, d: TableContract, l: TableContract | und
 
     const toRevoke = [...live].filter((p) => !declared.has(p)).sort();
     const toGrant = [...declared].filter((p) => !live.has(p)).sort();
-    if (toRevoke.length) out.push(`REVOKE ${toRevoke.join(', ')} ON ${table} FROM ${target};`);
-    if (toGrant.length) out.push(`GRANT ${toGrant.join(', ')} ON ${table} TO ${target};`);
+    // REVOKE narrows, GRANT widens (Condition C).
+    if (toRevoke.length) narrow.push(`REVOKE ${toRevoke.join(', ')} ON ${table} FROM ${target};`);
+    if (toGrant.length) widen.push(`GRANT ${toGrant.join(', ')} ON ${table} TO ${target};`);
   }
 }
 
@@ -450,7 +479,7 @@ function reconcileGrants(table: string, d: TableContract, l: TableContract | und
  * those live-but-not-declared. This is how `auth.users` exposes id/email/role (and only those)
  * to `authenticated` without a whole-table grant. Columns are sorted, so a re-pull is a no-op.
  */
-function reconcileColumnGrants(table: string, d: TableContract, l: TableContract | undefined, out: string[], governed: ReadonlySet<string>): void {
+function reconcileColumnGrants(table: string, d: TableContract, l: TableContract | undefined, narrow: string[], widen: string[], governed: ReadonlySet<string>): void {
   const dcg = d.columnGrants ?? {};
   const lcg = l?.columnGrants ?? {};
   for (const grantee of [...new Set([...Object.keys(dcg), ...Object.keys(lcg)])].sort()) {
@@ -465,8 +494,8 @@ function reconcileColumnGrants(table: string, d: TableContract, l: TableContract
       const live = new Set(lPriv[priv] ?? []);
       const toRevoke = [...live].filter((c) => !declared.has(c)).sort();
       const toGrant = [...declared].filter((c) => !live.has(c)).sort();
-      if (toRevoke.length) out.push(`REVOKE ${priv} (${toRevoke.join(', ')}) ON ${table} FROM ${target};`);
-      if (toGrant.length) out.push(`GRANT ${priv} (${toGrant.join(', ')}) ON ${table} TO ${target};`);
+      if (toRevoke.length) narrow.push(`REVOKE ${priv} (${toRevoke.join(', ')}) ON ${table} FROM ${target};`);
+      if (toGrant.length) widen.push(`GRANT ${priv} (${toGrant.join(', ')}) ON ${table} TO ${target};`);
     }
   }
 }

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

@@ -0,0 +1,227 @@
+/**
+ * `everystack db:adopt` — first-time adoption of a pre-Models database, by PROOF.
+ *
+ *   db:adopt [--stage <name> | --database-url <url>] [--schema public] [--out db/models]
+ *            [--govern-roles r1,r2]
+ *
+ * The problem it solves: a production database that never went through Models has no committed
+ * ancestor declaring it, so db:apply refuses it as unverifiable drift — and no waiver fits (there
+ * is nothing to attest a lineage FROM). db:adopt is the deliberate, auditable on-ramp. It renders
+ * Models from the live database (the same renderers db:pull uses), compiles them back, and PROVES
+ * the compiled Models declare the live state EXACTLY — predicted == governed live, the same
+ * declares-test descent and db:check use. Only then does it write the model files and print the
+ * `chore(db): adopt live baseline <fp>` commit: that commit legitimately declares the live state,
+ * so a later db:apply descends for real instead of hitting the drift refusal.
+ *
+ * The doctrine (Fable-ruled 2026-09-05): PROVE, not attest. There is NO bypass flag. When the
+ * round-trip is not exact, adoption REFUSES, names the surfaces that diverged, and prints the
+ * db:generate edge — because a baseline that papered over a difference is the bypass under another
+ * name. It writes NOTHING on refusal; --out is left untouched.
+ *
+ * The pure proof core is adopt.ts (proveAdoption); the shared render is live-models.ts
+ * (renderLiveModelFiles). This shell is the IO: connect, render into a sandbox to compile, prove,
+ * and either finalize or refuse.
+ */
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { introspectSchema, type SchemaSnapshot } from '../schema-introspect';
+import { introspectContract, type AuthzContract, type QueryRunner } from '../authz-contract';
+import { introspectDerived } from '../derived-introspect';
+import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
+import { renderLiveModelFiles } from '../live-models';
+import { proveAdoption, type AdoptionProof } from '../adopt';
+import { generateMigrationSql } from '../migration-generate';
+import { loadModels } from './db-generate';
+import type { ModelDescriptor } from '@everystack/model';
+import type { RenderedModelFile } from '../model-render';
+import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source';
+import type { SessionRunner } from '../session';
+import { resolveConfig, opsFunction } from '../config';
+import { lambdaQueryRunner, lambdaSessionRunner } from '../aws';
+import { step, success, fail, info, warn } from '../output';
+import { opsAdviceLines } from '../ops-advice';
+
+const DEFAULT_OUT = 'db/models';
+
+export interface AdoptResult {
+  /** The proof: clean means the compiled Models declare the live state exactly. */
+  proof: AdoptionProof;
+  /** The rendered model files (directory shape) — written to --out only when the proof is clean. */
+  files: RenderedModelFile[];
+  /** The live schema, as introspected. */
+  snapshot: SchemaSnapshot;
+  /** The live authorization contract, as introspected. */
+  contract: AuthzContract;
+  /** `chore(db): adopt live baseline <fp>` when clean; null on refusal. */
+  commitMessage: string | null;
+  /** On refusal, the db:generate edge (what the Models and the live database still differ by). */
+  refusalDiff: string[];
+}
+
+/**
+ * The adopt CORE: introspect the live database, render Models with the shared renderer, compile
+ * them in `sandboxDir`, and prove they declare the live state. Pure of policy — it does not decide
+ * to write --out or to exit; the caller does that from the verdict. The sandbox is where the
+ * rendered barrel is written so it can be dynamically imported (the compile the proof needs);
+ * --out is written by the shell only after the proof is clean.
+ */
+export async function adoptFromLive(opts: {
+  session: SessionRunner;
+  runner: QueryRunner;
+  schema?: string | string[];
+  governRoles?: string[];
+  sandboxDir: string;
+  /** How to compile the rendered barrel back to descriptors. Defaults to loadModels (the barrel
+   *  loader db:generate uses). Injectable so a test runner that cannot dynamic-import a `.ts` via
+   *  a file:// URL (jest) can supply its own transforming import. */
+  loadBarrel?: (indexPath: string) => Promise<ModelDescriptor[]>;
+}): Promise<AdoptResult> {
+  const { session, sandboxDir } = opts;
+  const schema = opts.schema ?? 'public';
+  const load = opts.loadBarrel ?? loadModels;
+
+  const snapshot = await introspectSchema(session);
+  const contract = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
+  const derivedCatalog = await introspectDerived(session);
+
+  const rendered = renderLiveModelFiles(snapshot, contract, derivedCatalog, { schema, governRoles: opts.governRoles });
+
+  // Compile the rendered barrel: proveAdoption needs the loaded ModelDescriptors, and loading is a
+  // dynamic import, so the files must exist on disk under a tree where @everystack/model resolves.
+  await fs.mkdir(sandboxDir, { recursive: true });
+  for (const f of rendered.files) await fs.writeFile(path.join(sandboxDir, f.file), f.source, 'utf8');
+  const models = await load(path.join(sandboxDir, 'index.ts'));
+
+  const proof = proveAdoption(models, snapshot, contract, { schema: typeof schema === 'string' ? schema : undefined });
+  const commitMessage = proof.clean ? `chore(db): adopt live baseline ${proof.fingerprint}` : null;
+  // On refusal, show WHAT still differs — the same edge db:generate would mint against the live DB.
+  const refusalDiff = proof.clean ? [] : generateMigrationSql(models, snapshot, { liveAuthz: contract });
+
+  return { proof, files: rendered.files, snapshot, contract, commitMessage, refusalDiff };
+}
+
+/**
+ * Turn the adopt verdict into action — the SECURITY BOUNDARY, isolated so it is testable without a
+ * database. This is where "PROVE not attest, no bypass" is actually enforced: on refusal it writes
+ * NOTHING to --out and reports; on a clean proof it writes the baseline and prints the commit/push
+ * runbook. It never calls process.exit (the caller maps the returned code) — so a test can assert,
+ * against a synthetic verdict, that a dirty result leaves --out untouched and a clean one finalizes.
+ * A future edit that let the refusal path fall through to the write is caught by that test, red.
+ */
+export async function applyAdoptVerdict(result: AdoptResult, outDir: string): Promise<{ exitCode: 0 | 1; wrote: boolean }> {
+  if (!result.proof.clean) {
+    // REFUSAL — the round trip is not exact. Name what diverged and show the edge; write NOTHING.
+    console.log('');
+    fail('db:adopt refused — the rendered Models do NOT declare the live database exactly.');
+    warn('A baseline that papered over this difference would be a bypass. Nothing was written to --out.');
+    info('Surfaces that diverge:');
+    for (const s of result.proof.divergentSurfaces) info(`  • ${s}`);
+    if (result.refusalDiff.length) {
+      console.log('');
+      info(`What still differs (the db:generate edge, ${result.refusalDiff.length} statement(s)):`);
+      for (const stmt of result.refusalDiff) console.log(stmt.endsWith(';') ? stmt : `${stmt};`);
+    }
+    console.log('');
+    info('The renderer could not yet capture the surfaces above. Refine by hand until db:generate is empty, then commit the Models — a later db:apply will descend normally.');
+    return { exitCode: 1, wrote: false };
+  }
+
+  // CLEAN — finalize. Write the rendered barrel to --out, then print the runbook.
+  try {
+    await fs.mkdir(outDir, { recursive: true });
+    const written = new Set(result.files.map((f) => f.file));
+    const existing = (await fs.readdir(outDir)).filter((f) => f.endsWith('.ts') && !written.has(f));
+    for (const f of result.files) await fs.writeFile(path.join(outDir, f.file), f.source, 'utf8');
+    if (existing.length) {
+      warn(`${existing.length} existing .ts file(s) in ${path.relative(process.cwd(), outDir)} were not part of this adoption and were left untouched: ${existing.join(', ')}`);
+    }
+  } catch (err: any) {
+    fail(`Could not write ${outDir}: ${err.message}`);
+    return { exitCode: 1, wrote: false };
+  }
+
+  console.log('');
+  success(`db:adopt — the rendered Models declare the live database exactly (${result.files.length - 1} model(s)).`);
+  info(`Wrote ${path.relative(process.cwd(), outDir)} — the adopted baseline.`);
+  console.log('');
+  info('Finalize the baseline — commit, then PUSH before you apply:');
+  info(`  git add ${path.relative(process.cwd(), outDir)}`);
+  info(`  git commit -m "${result.commitMessage}"`);
+  info('  git push        # an unpushed baseline is an unknown commit to teammates and the ops Lambda');
+  info('  everystack db:plan --stage <name>   # empty — the live database is now declared');
+  return { exitCode: 0, wrote: true };
+}
+
+export async function dbAdoptCommand(
+  flags: Record<string, string>,
+  opts: {
+    /** Injected barrel loader (jest cannot file:// import a .ts). Default: adoptFromLive's loadModels. */
+    loadBarrel?: (indexPath: string) => Promise<ModelDescriptor[]>;
+    /** Injected sandbox dir, so a test can assert it is cleaned up. Default: a fresh mkdtemp. */
+    sandboxDir?: string;
+  } = {},
+): Promise<void> {
+  const schemas = (flags.schema || 'public').split(',').map((s) => s.trim()).filter(Boolean);
+  if (schemas.length === 0) fail('--schema needs at least one schema name.');
+  const schema = schemas.length === 1 ? schemas[0] : schemas;
+  const outDir = path.resolve(flags.out || DEFAULT_OUT);
+
+  // --govern-roles: the operator's EXPLICIT decision to transcribe foreign roles' grants as
+  // privileges (so a fresh build recreates them). Same vocabulary guard as db:pull.
+  const governRoles = (flags['govern-roles'] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+  for (const r of governRoles) {
+    if (['anon', 'authenticated', 'admin', 'PUBLIC', 'public'].includes(r)) {
+      fail(`--govern-roles ${r}: the vocabulary roles and PUBLIC are always governed — name only foreign roles (an ops/connection role the migrations granted to).`);
+      process.exit(1);
+    }
+  }
+
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  const sandboxDir = opts.sandboxDir ?? await fs.mkdtemp(path.join(os.tmpdir(), 'everystack-adopt-'));
+  let exitCode: 0 | 1 = 1;
+  let end: (() => Promise<void>) | undefined;
+  try {
+    let runner: QueryRunner;
+    let session: SessionRunner;
+    if (dbSource.kind === 'url') {
+      step(connectingVia(dbSource));
+      ({ 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 = lambdaQueryRunner(config.region, opsFunction(config));
+      session = lambdaSessionRunner(config.region, opsFunction(config));
+    }
+    step(`Introspecting live database (schema: ${schemas.join(', ')})...`);
+    const result = await adoptFromLive({ session, runner, schema, governRoles, sandboxDir, loadBarrel: opts.loadBarrel });
+    // Only after a proof do we act. A throw before here (connect, introspect, render, compile)
+    // never reaches applyAdoptVerdict, so --out is untouched — a bad baseline is impossible.
+    ({ exitCode } = await applyAdoptVerdict(result, outDir));
+  } catch (err: any) {
+    fail(err.message);
+    if (dbSource.kind === 'url') {
+      info('Check the connection string and that the database is accepting connections.');
+    } else {
+      for (const line of opsAdviceLines(err, [
+        'Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.',
+        'Adopting a local database instead? Pass --database-url or set DATABASE_URL.',
+      ])) info(line);
+    }
+    exitCode = 1;
+  } finally {
+    // The sandbox is the compile scratch, never the baseline — remove it on EVERY exit path.
+    await end?.();
+    await fs.rm(sandboxDir, { recursive: true, force: true });
+  }
+  process.exit(exitCode);
+}

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

@@ -21,12 +21,14 @@ import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
 import {
   fingerprintLive,
   fingerprintModels,
+  fingerprintState,
   governedRolesForModels,
+  divergentSurfaces,
   mapUnfingerprintedRows,
   UNFINGERPRINTED_SQL,
   type UnfingerprintedObject,
 } from '../schema-fingerprint';
-import { predictLiveFingerprint, governedLiveFingerprint } from '../edge-plan';
+import { predictLiveState, governedLiveFingerprint } from '../edge-plan';
 import { resolveModelsPath } from '../models-path';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source';
 import { borrowedSessionRunner, INTROSPECTION_SESSION, type SessionRunner } from '../session';
@@ -56,6 +58,9 @@ export interface FingerprintStatus {
    */
   predicted?: string;
   match: boolean | null;
+  /** On a MISMATCH, the surfaces that diverge (base schema / authorization / sequence ACLs, with
+   *  the tables named) — so the report says WHERE to look. Absent when MATCH or no models. */
+  divergentSurfaces?: string[];
   unfingerprinted: UnfingerprintedObject[];
 }
 
@@ -77,8 +82,14 @@ export async function computeFingerprintStatus(
   const live = fingerprintLive(snapshot, contract).hash;
   const declared = models ? fingerprintModels(models, { sequences }).hash : null;
   const governedRoles = models ? governedRolesForModels(models, governedExtras) : undefined;
-  const governedLive = governedRoles ? governedLiveFingerprint(snapshot, contract, governedRoles) : undefined;
-  const predicted = models ? predictLiveFingerprint(models, snapshot, contract, { governedRoles }) : undefined;
+  // Compute the governed-live and predicted states as full canonical forms, so a MISMATCH can
+  // name the diverging surface — not just their hashes.
+  const governedLiveState = governedRoles
+    ? fingerprintState(snapshot, contract.tables, { governedRoles, sequenceGrants: contract.sequenceGrants })
+    : undefined;
+  const governedLive = governedLiveState?.hash;
+  const predictedState = models ? predictLiveState(models, snapshot, contract, { governedRoles }) : undefined;
+  const predicted = predictedState?.hash;
   // B5 — a declared owner IS hashed (derived-source prefixes it), so reporting it as
   // unfingerprinted would be a false claim in the one report whose whole job is honesty about
   // coverage. SQL cannot know what the models declare; the filter belongs here.
@@ -89,12 +100,17 @@ export async function computeFingerprintStatus(
   );
   const unfingerprinted = mapUnfingerprintedRows(unfingerprintedRows as any[])
     .filter((u) => u.kind !== 'function owner' || !ownerDeclared.has(u.identity.split(' → ')[0]));
+  const match = declared === null ? null : predicted === governedLive;
+  const surfaces = match === false && predictedState && governedLiveState
+    ? divergentSurfaces(predictedState.canonical, governedLiveState.canonical)
+    : undefined;
   return {
     live,
     ...(governedLive !== undefined ? { governedLive } : {}),
     declared,
     ...(predicted !== undefined ? { predicted } : {}),
-    match: declared === null ? null : predicted === governedLive,
+    match,
+    ...(surfaces && surfaces.length ? { divergentSurfaces: surfaces } : {}),
     unfingerprinted,
   };
 }
@@ -172,7 +188,10 @@ export async function dbFingerprintCommand(flags: Record<string, string>): Promi
           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.');
+        else {
+          const where = status.divergentSurfaces?.length ? ` — diverges on ${status.divergentSurfaces.join('; ')}` : '';
+          fail(`MISMATCH${where}. Run \`everystack db:generate\` to see the difference as SQL.`);
+        }
       }
       if (status.unfingerprinted.length > 0) {
         warn(`unfingerprinted (${status.unfingerprinted.length}) — outside the base fingerprint and the derived manifest:`);

package/src/cli/derived-grants.ts

@@ -106,24 +106,30 @@ export interface ObjectGrantDiff {
 }
 
 /**
- * Ownership context for a FUNCTION's grant diff. Absent for relations.
+ * Ownership context for an object's grant diff — passed for EVERY kind (functions AND relations).
  *
- * Owner-implicit EXECUTE is excluded from both grant reads (`grantee <> proowner`), which is
- * correct in isolation — an owner's privileges are not grants. But it means the SET of
- * non-owner grants is computed RELATIVE TO THE OWNER, so two sides with different owners
- * produce two different sets for the same function, and the differ reconciles a difference
- * that is purely ownership.
+ * Owner-implicit privileges are excluded from both grant reads (`grantee <> proowner` for
+ * functions, `<> relowner` for relations), which is correct in isolation — an owner's privileges
+ * are not grants. But it means the SET of non-owner grants is computed RELATIVE TO THE OWNER, so
+ * two sides with different owners produce two different sets for the same object, and the differ
+ * reconciles a difference that is purely ownership.
  *
- * Measured by a consumer, 2026-08-10: their local `resolve_user_slug` is owned by
+ * First measured on functions, 2026-08-10: a consumer's local `resolve_user_slug` is owned by
  * `outbound_migrator` (owner-implicit, so the pull rendered NO privilege), while on stage the
  * same function is owned by `slug_resolver` and `outbound_migrator` holds an EXPLICIT grant.
  * The differ planned `REVOKE EXECUTE ON api.resolve_user_slug FROM outbound_migrator` — a real
  * access removal minted from an ownership difference. They did not apply it.
+ *
+ * The relation half surfaced 2026-09-04: after `db:provision ADOPT` made `outbound_migrator` own a
+ * VIEW the model also lists in its grants, the live read excluded the owner's own rows, so the
+ * declared self-grant was minted on every reconcile and never converged. The relation call site
+ * used to pass no ownership context on the belief that a relation's grant set does not shift with
+ * its owner — true only while relacl is NULL. Both kinds now share this context.
  */
 export interface GrantOwnerContext {
   /** The owner the DECLARED grant set was computed against, when the models declare one. */
   declared?: string;
-  /** The owner the LIVE grant set was computed against (`pg_get_userbyid(proowner)`). */
+  /** The owner the LIVE grant set was computed against (`pg_get_userbyid(proowner|relowner)`). */
   live?: string;
 }
 
@@ -131,8 +137,9 @@ export interface GrantOwnerContext {
  * The idempotent REVOKE/GRANT delta between the declared contract and the live ACLs —
  * the table path's reconcileGrants, per derived object. Empty when they match.
  *
- * When `owners` is supplied (functions) and the two sides cannot be shown to have been
- * computed against the SAME owner, REVOKEs are WITHHELD and reported. GRANTs still flow: a
+ * When `owners` is supplied (every kind — functions and relations) and the two sides cannot be
+ * shown to have been computed against the SAME owner, REVOKEs are WITHHELD and reported. GRANTs
+ * still flow: a
  * redundant GRANT is noise, a wrong REVOKE removes access that was really there. Failing to
  * revoke is the recoverable error and it is never silent.
  *
@@ -198,10 +205,10 @@ export function diffObjectGrants(
         out.push(`REVOKE ${toRevoke.join(', ')} ON ${target} FROM ${grantee}`);
       } else {
         const why = grantee === owners!.live
-          ? `'${grantee}' is the function's live OWNER, whose implicit privileges are excluded from both grant reads — so this difference is ownership, not a grant`
-          : `'${grantee}' is the function's declared owner (live owner: ${owners!.live}), and an owner's implicit privileges are excluded from both grant reads`;
+          ? `'${grantee}' is the object's live OWNER, whose implicit privileges are excluded from both grant reads — so this difference is ownership, not a grant`
+          : `'${grantee}' is the object's declared owner (live owner: ${owners!.live}), and an owner's implicit privileges are excluded from both grant reads`;
         suppressed.push(
-          `${target}: withheld REVOKE ${toRevoke.join(', ')} FROM ${grantee} — ${why}. An owner's implicit privileges are excluded from both reads, so the two grant sets are not comparable and this revoke may remove access that is really there. Declare the function's owner to restore revokes.`,
+          `${target}: withheld REVOKE ${toRevoke.join(', ')} FROM ${grantee} — ${why}. An owner's implicit privileges are excluded from both reads, so the two grant sets are not comparable and this revoke may remove access that is really there. Declare the object's owner to restore revokes.`,
         );
       }
     }

package/src/cli/derived-plan.ts

@@ -482,11 +482,21 @@ export function planReconcile(
         );
       } else {
         const target = parsed.target ?? (src.kind === 'function' ? `FUNCTION ${src.identity}` : src.identity);
-        // Functions carry ownership context; relations do not (relacl's NULL means owner-only
-        // and aclexplode(NULL) is empty, so a relation's grant set does not shift with its owner).
-        const owners = src.kind === 'function'
-          ? { ...(src.owner !== undefined ? { declared: src.owner } : {}), ...(liveObj.owner !== undefined ? { live: liveObj.owner } : {}) }
-          : undefined;
+        // Ownership context is passed for EVERY kind. An owner's implicit privileges are excluded
+        // from the live read for relations too (`a.grantee <> c.relowner`), so a model that both
+        // owns an object and lists that owner in its grants declares a self-grant the read can
+        // never confirm — diffObjectGrants normalizes the owner grantee away. The earlier belief
+        // that a relation's grant set "does not shift with its owner" holds only while relacl is
+        // NULL; the first non-owner grant materializes the ACL and the owner's own rows drop out,
+        // exactly as for a function. (A consumer's ADOPT'd view, owned by a role its model also
+        // grants, looped forever — 2026-09-04.)
+        // KNOWN LIMIT: a privilege an owner has deliberately self-revoked is not restored — that
+        // is a failure to ADD access (availability), never to remove it, and unnormalized code did
+        // not converge on it either.
+        const owners = {
+          ...(src.owner !== undefined ? { declared: src.owner } : {}),
+          ...(liveObj.owner !== undefined ? { live: liveObj.owner } : {}),
+        };
         const { statements, suppressed } = diffObjectGrants(target, parsed.grants, liveObj.grants, owners);
         if (statements.length > 0) regrants.push({ identity: src.identity, statements });
         // Never silent: a withheld revoke is reported every run until the owner is declared.

package/src/cli/edge-plan.ts

@@ -31,7 +31,7 @@ import type { AuthzContract } from './authz-contract';
 import { generateMigrationSql, unmodeledTables } from './migration-generate';
 import { compileTableContract } from './authz-compile';
 import { classifyGeneratedStatements, classifyDestructive, partitionStatements, renderStatementHistogram } from './state-apply';
-import { fingerprintLive, fingerprintState, fingerprintModels, governedRolesForModels, stableStringify, compareStoredFingerprint, formatChangedMessage, FINGERPRINT_VERSION } from './schema-fingerprint';
+import { fingerprintLive, fingerprintState, fingerprintModels, governedRolesForModels, stableStringify, compareStoredFingerprint, formatChangedMessage, FINGERPRINT_VERSION, type Fingerprint } from './schema-fingerprint';
 import { compileDeclaredState } from './declared-diff';
 import { compileTableRenames, compileTableMoves } from './schema-compile';
 
@@ -164,6 +164,20 @@ export function predictLiveFingerprint(
   contract: AuthzContract,
   opts: { schema?: string; governedRoles?: ReadonlySet<string> } = {},
 ): string {
+  return predictLiveState(models, snapshot, contract, opts).hash;
+}
+
+/**
+ * The predicted endpoint as a full {@link Fingerprint} (hash AND canonical form). The hash is
+ * the plan's `to` and the declares-test; the canonical form lets a MISMATCH report name WHICH
+ * surface diverged (base schema, authorization, sequence ACLs) against the live one.
+ */
+export function predictLiveState(
+  models: ModelDescriptor[],
+  snapshot: SchemaSnapshot,
+  contract: AuthzContract,
+  opts: { schema?: string; governedRoles?: ReadonlySet<string> } = {},
+): Fingerprint {
   // The prediction is a DECLARED-vs-live comparison, so it must hash through the
   // models' governed set — the live side of any comparison against it must use
   // the same set (see governedLiveFingerprint). Unfiltered, every ride-through
@@ -204,7 +218,12 @@ export function predictLiveFingerprint(
     ...declared.contract.tables,
     ...contract.tables.filter((t) => ridesThrough(t.table)),
   ];
-  return fingerprintState(mergedSnapshot, mergedAuthz, { governedRoles }).hash;
+  // Sequence ACLs (v11): declared tables DERIVE their reconciled (inherited) target, so pass
+  // measured ACLs ONLY for rides-through tables — the ones reconciliation never touches, whose
+  // live ACLs carry through unchanged. Passing all measured would make a declared table's
+  // predicted endpoint read its pre-reconcile ACL and never converge with the plan it mints.
+  const ridesThroughSeqGrants = (contract.sequenceGrants ?? []).filter((s) => ridesThrough(s.table));
+  return fingerprintState(mergedSnapshot, mergedAuthz, { governedRoles, sequenceGrants: ridesThroughSeqGrants });
 }
 
 /**
@@ -218,7 +237,9 @@ export function governedLiveFingerprint(
   contract: AuthzContract,
   governedRoles: ReadonlySet<string>,
 ): string {
-  return fingerprintState(snapshot, contract.tables, { governedRoles }).hash;
+  // A true live read: measure every table's serial-sequence ACLs (v11), so this half sees a
+  // sequence REVOKE the predicted endpoint's derived target does not.
+  return fingerprintState(snapshot, contract.tables, { governedRoles, sequenceGrants: contract.sequenceGrants }).hash;
 }
 
 /**