@everystack/cli 0.4.73 → 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/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;
 }
 
 /**

package/src/cli/git-descent.ts

@@ -217,8 +217,17 @@ async function evaluateTree(candidate: ModelTreeCandidate, live: LiveState, ctx:
     }
   }
 
+  // A materialized tree that carries NO barrel DECLARES NOTHING — a clean, deterministic 'no',
+  // not a failure to read. Every pre-Models repo has such ancestors: the models directory
+  // scaffolded (or present for another reason) before its barrel existed. Letting the loader
+  // throw on the absent file would classify it `compile-failed`, poisoning the verdict to
+  // UNVERIFIABLE — which sends a never-adopted database to "retry/upgrade" instead of to
+  // db:adopt. So the missing barrel is decided here, before the loader is ever consulted.
+  const barrelPath = path.join(dest, ctx.barrel);
+  if (!fs.existsSync(barrelPath)) return { kind: 'no' };
+
   const evaluate = async (): Promise<boolean> => {
-    const models = await ctx.loader(path.join(dest, ctx.barrel));
+    const models = await ctx.loader(barrelPath);
     const governedRoles = governedRolesForModels(models);
     const predicted = predictLiveFingerprint(models, live.snapshot, live.contract, { schema: ctx.schema, governedRoles });
     return predicted === governedLiveFingerprint(live.snapshot, live.contract, governedRoles);
@@ -623,9 +632,13 @@ export async function proveDescent(
     reason:
       `no ancestor of your checkout declares the target's live fingerprint ` +
       `${short(fingerprintLive(live.snapshot, live.contract).hash)} — read ${candidates.length} ` +
-      'ancestor model state(s), all cleanly, and none matches. The database was hand-edited ' +
-      '(drift), or the deploying branch is not in this checkout. Align the models with the live ' +
-      'database (db:pull, commit), or waive the rule deliberately.',
+      'ancestor model state(s), all cleanly, and none matches. Either this database has never been ' +
+      'adopted into Models (nothing committed can declare it — the first-adoption case), or it ' +
+      'drifted after adoption. THE RUNBOOK: run everystack db:adopt — it renders Models from the ' +
+      'live database and PROVES they declare it exactly (it REFUSES rather than paper over any ' +
+      'difference); commit AND push that baseline, then re-run db:plan / db:apply and it descends ' +
+      'normally. If instead your Models are the source of truth and the database drifted, reconcile ' +
+      'with db:generate, or waive the rule deliberately.',
   };
 }
 

package/src/cli/index.ts

@@ -11,6 +11,7 @@ import { dbMigrateCommand, dbSeedCommand, dbResetCommand, dbPsqlCommand, dbDocto
 import { dbAuthzPullCommand, dbAuthzDiffCommand, dbAuthzTestCommand, dbAuthzOwnerCommand, dbAuthzReportCommand } from './commands/db-authz';
 import { dbGenerateCommand } from './commands/db-generate';
 import { dbPullCommand } from './commands/db-pull';
+import { dbAdoptCommand } from './commands/db-adopt';
 import { dbReconcileCommand } from './commands/db-reconcile';
 import { dbRefreshCommand } from './commands/db-refresh';
 import { dbFingerprintCommand } from './commands/db-fingerprint';
@@ -185,6 +186,9 @@ async function main() {
     case 'db:pull':
       await dbPullCommand(flags);
       break;
+    case 'db:adopt':
+      await dbAdoptCommand(flags);
+      break;
     case 'db:reconcile':
       await dbReconcileCommand(flags);
       break;
@@ -366,6 +370,7 @@ Usage:
   everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--schema-out db/schema.generated.ts] [--allow-drops] [--apply] [--dry-run]  Diff models vs the live DB → next migration file, or with --apply execute it directly (one transaction, schema_log recorded, verified by re-diff — no drizzle folder needed; direct connection only; DROPs held back unless --allow-drops). --dry-run prints the edge and writes NOTHING (no migration, no journal entry, no schema refresh) — the preview verb; db:diff computes a models-vs-models edge with no database at all. The resolved --schema-out is recorded in the migration journal: later flag-less runs reuse it (flag > recorded > default), a differing flag updates the record and says so
   everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities live|public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored). **--abilities live is the brownfield mode**: derive each model's authz from the grants and policies the database ALREADY has, and write the foreign-grantee baseline (db/authz-baseline.json) — this is what you want when adopting an existing schema. --abilities public-read stamps the common stanza (public read, admin write) uncommented — greenfield only, since on an existing database it declares public read of every table. Both are explicit generated code, never a runtime default. --govern-roles <r1,r2> (with --abilities live) transcribes the named FOREIGN roles' grants into privileges — the models then OWN them, so a fresh build recreates them; required for migration deletion when the migrations created grants to an ops/connection role. Explicit only (a re-pull must not silently govern), complete-or-refuse (a listed role holding a column-scoped grant fails the pull before anything is written). --matviews-as-tables renders every matview as defineMaterializedTable with INTROSPECTED fields (the canonical-sync flip: a pipeline-owned table everystack migrates but never refreshes) — names land in an exported materializedTables array to spread into your models; fields come back nullable/unkeyed (matviews carry no PK/NOT NULL) — tighten on review; add --suggest-keys to probe the LIVE rows for functionally-unique columns (one scan per matview) and surface each as a commented .primaryKey() suggestion. docs/derived-objects.md#flipping-a-matview-to-a-materialized-table---matviews-as-tables
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
+  everystack db:adopt          [--stage <name> | --database-url <url>] [--schema public] [--out db/models] [--govern-roles r1,r2]  First-time adoption of a pre-Models database, BY PROOF. A production DB that never went through Models has no committed ancestor declaring it, so db:apply refuses it as unverifiable drift and no waiver fits. db:adopt renders field() Models from the live DB (the same renderers db:pull uses, --abilities live), compiles them back, and finalizes the baseline ONLY when the compiled Models declare the live state EXACTLY (predicted == governed live — the same declares-test descent and db:check use). On success it writes --out (default db/models) and prints the \`chore(db): adopt live baseline <fp>\` commit — that commit legitimately declares the live state, so a later db:apply descends for real. PROVE not attest: there is NO bypass flag. When the round-trip is not exact, adoption REFUSES, names the surfaces that diverged, prints the db:generate edge, and writes NOTHING. Commit AND push the baseline before db:apply — an unpushed baseline is an unknown commit to teammates and the ops Lambda.
   everystack db:fingerprint    [--stage <name> | --database-url <url>] [--models <barrel>] [--json]  Content-address the live base schema (tables+constraints+authz) and compare against the models — MATCH/MISMATCH (exit 1), plus the unfingerprinted-objects report
   everystack db:reconcile      [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--overwrite-drift] [--only a,b] [--json]  Reconcile the derived layer (functions/views/matviews/triggers) against the DECLARED descriptors (defineView/defineMaterializedView/defineFunction/defineSql/trigger() on models, from the barrel) — the single home (db/sql is retired; leftover .sql files fail with the migration path): plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (atomic — DDL + provenance in one transaction) and records provenance + schema_log; --apply --stage runs credential-free in the ops Lambda (no admin URL on the deployer, the db:apply twin), --apply --database-url runs direct. Hand-edits are drift (never overwritten silently). First contact with existing objects: --baseline TRUSTS live == source (records provenance, verifies nothing), --rebuild GUARANTEES it (drop+create from source). They are mutually exclusive. --only <schema.name,…> restricts the run to the named objects (surgical); with --rebuild it FORCES those to rebuild from source even when the hashes show no diff — the recovery exit when a mistaken --rebaseline left a self-consistent-but-wrong provenance row (the dependency cascade rebuilds their live dependents).
   everystack db:refresh        [--stage <name> | --database-url <url> | --direct] [--only a,b] [--verify-nonempty] [--list]  Refresh the declared materialized views in dependency order, credential-free. --stage runs the whole refresh in the ops Lambda on the operator connection (no URL on the operator's machine — the data-lane twin of the reconcile lane); --database-url refreshes over a local connection (dev); --stage <name> --direct resolves the stage's operator connection from its ops Lambda (credential never on argv) and refreshes CLI-side on an UNBOUNDED clock, for a matview set that exceeds the ops-Lambda 900s limit; --only refreshes a named subset (full identity or bare name); --verify-nonempty gates on populated-but-zero-rows matviews (the dark-panel check — a scoped EXISTS on just what was refreshed, so a promotion script gets the gate with no read authority) and FAILS naming any empty; --list previews the order without connecting. Plain REFRESH (ACCESS EXCLUSIVE); fail-fast, idempotent to re-run.