@everystack/cli 0.4.78 → 0.4.79

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.79] - 2026-09-07
+
+### Removed
+
+- remove db:adopt — its proof was "would db:plan be empty", and db:plan answers that on the review surface
+
+### Added
+
+- db:pull ends with the on-ramp runbook; docs and help say the on-ramp is pull, commit, plan
+
+### Fixed
+
+- closing-gate round 1 — the as-is lane runs the shipped db:pull, the runbook is gated on --abilities live, the fixture proves live derivation, live-models.ts is gone
+
 ## [0.4.78] - 2026-09-07
 
 ### Fixed
@@ -941,6 +955,13 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [0.2.37] - 2026-06-17
 
+### Removed
+
+- remove onMutation callback — events replaces it
+- remove unused @everystack/jobs devDependency
+- remove secret auto-injection, skip SSR check for web-only updates
+- remove media asset pruning from update command
+
 ### Added
 
 - rename @everystack/updates → @everystack/cli, add db:migrate/db:seed, remove AdminSecret
@@ -992,7 +1013,6 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 ### Fixed
 
 - normalize cache:purge --path to strip query params and ensure leading slash
-- remove unused @everystack/jobs devDependency
 - include updateId in register-web payload
 - psql Lambda-only queries, composite key notify, logging defaults
 - add AWS KVS + SigV4a as direct dependencies
@@ -1011,14 +1031,12 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 - drop GetFunctionConfiguration from log group resolution
 - detect export completion to prevent static pre-rendering hang
 - rewrite secrets for SST Ion, filter EXPO_PUBLIC_* only
-- remove secret auto-injection, skip SSR check for web-only updates
 - clear Metro transform cache on export
 - worker function discovery and log group resolution for SQS subscribers
 - replace infrastructure headers with single X-Server-Debug timestamp
 - version bumps and publish fixes for cli, server, jobs
 - invalidate stale config cache on schema change
 - fall back to outputs.json for custom-named media buckets
-- remove media asset pruning from update command
 - media-sync test uses same minimatch interop as source
 - discover the Router distribution by domain and SST tags
 - use minimatch's named export — the package ships types now
@@ -1027,7 +1045,6 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Changed
 
-- remove onMutation callback — events replaces it
 - migrate all package schemas to everyschema canonical tables
 - lazy-load AWS SDK imports for faster CLI startup
 - drop type module from all packages, switch Jest to CJS mode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.78",
+  "version": "0.4.79",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

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

@@ -38,6 +38,36 @@ import { fingerprintLive } from '../schema-fingerprint';
 import { ungovernedGrants, vestigialSequenceGrants, renderVestigialSequenceGrants, ALWAYS_GOVERNED, type GrantExemption } from '../authz-reconcile';
 import { buildStageBaseline, mergeBaseline, readBaselineFile, writeBaselineFile, BASELINE_FILE } from '../authz-baseline';
 import { introspectDerived, type DerivedCatalog } from '../derived-introspect';
+
+/**
+ * The on-ramp runbook, printed last so the operator is never left guessing what a pull is FOR.
+ *
+ * db:pull is the only way an existing database comes in. What happens next is decided by
+ * db:plan, not by a verb: an EMPTY plan means the committed Models declare the database as it
+ * is (adopted — descent proves the pull commit by recompile, and every later apply descends from
+ * it); a NON-EMPTY plan is the hardening edge, reviewed and applied as the origin. db:adopt used
+ * to bolt a proof onto this render; the proof was "would the plan be empty", so the verb is gone
+ * (cli 0.4.79) and this is what replaced it. Exported so a test pins the lines and the
+ * refusal-runbook lint reads them.
+ */
+export function pullOnRampRunbook(opts: { stage?: string; out?: string; abilities?: string }): string[] {
+  const target = opts.stage ? `--stage ${opts.stage}` : '--stage <name>';
+  const what = opts.out ? `the files in ${opts.out}` : 'these Models';
+  // Only a LIVE pull transcribes the database's own authz; only then can an empty plan mean
+  // "adopted as it is". A commented or public-read pull carries authored abilities — its plan is
+  // an edge to review (public-read on an existing database GRANTS public read of every table),
+  // never an adoption, and the runbook must not call it one (closing-gate review, 2026-09-07).
+  if (opts.abilities !== 'live') {
+    return [
+      `Next: author each model's abilities (db:check fails until every model declares) — for an EXISTING database, re-pull with --abilities live to derive them from the grants and policies already there. Then commit ${what} and run \`everystack db:plan ${target}\`: the plan is an edge to review, not an adoption of what is live.`,
+    ];
+  }
+  return [
+    `Next: commit ${what}, then \`everystack db:plan ${target}\`.`,
+    'EMPTY plan = adopted as it is: that commit declares the database, and every later db:apply descends from it. Nothing to apply.',
+    `NON-EMPTY plan = the hardening edge: review it, then \`everystack db:apply --plan <file> ${target}\`. No commit declares this database yet, so the reviewed plan is the ORIGIN — db:apply proves that and records it.`,
+  ];
+}
 import { introspectContract, type TableContract, type AuthzContract } from '../authz-contract';
 import { introspectTableOwners, buildOwnershipReport, renderOwnershipReport, type TableOwner } from '../authz-ownership';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
@@ -461,5 +491,6 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       note(`Committing this file ADOPTS those roles. Anything not in it — or anything that grows beyond it — refuses at db:plan.`);
     }
   }
+  for (const line of pullOnRampRunbook({ stage: flags.stage, out: flags.out, abilities })) note(line);
   process.exit(0);
 }

package/src/cli/git-descent.ts

@@ -278,8 +278,9 @@ async function evaluateTree(candidate: ModelTreeCandidate, live: LiveState, ctx:
   // 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.
+  // UNVERIFIABLE — which sends a never-adopted database to "retry/upgrade" instead of to the
+  // first-adoption lane (db:pull → commit → db:plan). 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' };
 
@@ -433,7 +434,7 @@ const firstLine = summarizeCompileError;
  * in a monorepo the app (`apps/expo/db/models`) has `apps/expo/node_modules`, and the root
  * `node_modules` may not carry the package at all (closing-gate review round 4, reproduced). No
  * `node_modules` anywhere up to the repo root → the repo root itself (a nested checkout still walks
- * up to its host's). Never the OS temp dir — that resolves nothing (the db:adopt 0.4.74 bug).
+ * up to its host's). Never the OS temp dir — that resolves nothing (the 0.4.74 sandbox-resolution bug).
  */
 export function materializeBase(repoRoot: string, modelsAbs: string): string {
   let dir = path.dirname(modelsAbs);

package/src/cli/index.ts

@@ -11,7 +11,6 @@ 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';
@@ -186,9 +185,6 @@ async function main() {
     case 'db:pull':
       await dbPullCommand(flags);
       break;
-    case 'db:adopt':
-      await dbAdoptCommand(flags);
-      break;
     case 'db:reconcile':
       await dbReconcileCommand(flags);
       break;
@@ -368,9 +364,8 @@ Usage:
   everystack db:export         --schema <name> [--stage <name> | --database-url <url> [--out <file.dump>]] [--models <barrel>]  Schema-scoped pg_dump artifact, stamped with the DECLARED schema fingerprint (the canonical-sync export; db:swap gates on that stamp). --stage dumps the stage's private DB via the ops Lambda → S3; --database-url (explicit flag, never the env) dumps a reachable DB to a local .dump + .meta.json — the build-locally → publish → swap on-ramp
   everystack db:swap           --schema <name> --from <artifact.dump | artifact-id> [--stage <name> --direct | --database-url <url>] --confirm [--fingerprint <hash>] [--snapshot physical|logical|none] [--snapshot-ref <id>] [--rebuild-derived] [--dump-build <file.json>]  Land a schema artifact atomically: fingerprint gate → pre-flight refusals → CONFIRMED snapshot → restore into <schema>_incoming (COPY-safe rewrite) → build the paired derived layer → one txn (drop+rename+recreate app→schema FKs, re-apply authz + schema USAGE) → assertions → drop retiring. Refresh-free; app.* untouched; the derived layer is never absent. DESTRUCTIVE. The venue is EXPLICIT — DATABASE_URL in the env is refused, and --stage requires --direct (a multi-GB restore exceeds the ops-Lambda 900s clock). The rollback point defaults to a PHYSICAL RDS snapshot on a stage that exposes databaseInstanceId (no locks, no pg_dump contending with the restore) and a WAITED logical db:backup otherwise; a bare --database-url refuses without --snapshot-ref <id> or --snapshot none. docs/schema-swap.md
   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
+  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 on-ramp for an existing database: commit what it renders, then db:plan --stage <s>. EMPTY plan = adopted as it is (that commit declares the database; every later db:apply descends from it). NON-EMPTY plan = the hardening edge: review it, db:apply --plan <f> --stage <s> — no commit declares the database yet, so the reviewed plan is the ORIGIN. Render from the stage, never from a local restore of a dump. --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 AS IT IS, BY PROOF. A production DB that never went through Models has no committed ancestor declaring it; db:adopt is the on-ramp that makes one. It 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 edge, and writes NOTHING — that is the HARDENING case (the Models vocabulary cannot declare what is live, e.g. a sequence grant with no INSERT behind it), and it needs no adoption commit: commit the Models you intend, db:plan --stage, db:apply --stage. No commit declares the database yet, so db:apply PROVES that (proven drift) and treats the reviewed plan as the ORIGIN. 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.

package/src/cli/adopt.ts

@@ -1,58 +0,0 @@
-/**
- * adopt — the PROVE core of `db:adopt` (P2a). Pure: live introspection + compiled Models in, a
- * verdict out. The command shell (commands/db-adopt.ts) does the IO — introspect, render, load,
- * write files, print the commit.
- *
- * The doctrine (Fable-ruled 2026-09-05): PROVE, not attest. There is no bypass flag. db:adopt
- * renders Models from a live database and may finalize them ONLY when the compiled Models declare
- * that database EXACTLY — the same declares-test descent and db:check use (predicted == governed
- * live). A commit that carries such Models legitimately declares the live state, so a later
- * db:apply descends for real (proveDescent finds the adopt commit) instead of being forced past a
- * drift refusal. When the round-trip is not exact, adoption REFUSES and names what diverged —
- * because a baseline that silently papered over a difference is the bypass under another name.
- */
-
-import type { ModelDescriptor } from '@everystack/model';
-import type { SchemaSnapshot } from './schema-introspect';
-import type { AuthzContract } from './authz-contract';
-import { governedRolesForModels, fingerprintState, fingerprintLive, divergentSurfaces } from './schema-fingerprint';
-import { predictLiveState, governedLiveFingerprint } from './edge-plan';
-
-export interface AdoptionProof {
-  /** True when the compiled Models declare the live state exactly — safe to finalize the baseline. */
-  clean: boolean;
-  /** The RAW live fingerprint — the baseline id that names the adopt commit (`adopt live baseline <fp>`). */
-  fingerprint: string;
-  /** When not clean, the surfaces that still diverge (base schema / authorization / sequence ACLs,
-   *  with the tables named), so the refusal says exactly what the render could not capture. Empty when clean. */
-  divergentSurfaces: string[];
-}
-
-/**
- * Does this compiled Models set declare the live state exactly? The declares-test, governed on
- * both sides through the SAME set the Models imply — a governed prediction against a raw live
- * hash can never converge on a brownfield database with foreign roles. Reuses the very functions
- * descent (`evaluateTree`) and db:fingerprint compare with, so "adoption is clean" and "the plan
- * is empty" are one answer, not two that can disagree.
- */
-export function proveAdoption(
-  models: ModelDescriptor[],
-  snapshot: SchemaSnapshot,
-  contract: AuthzContract,
-  opts: { schema?: string } = {},
-): AdoptionProof {
-  const governedRoles = governedRolesForModels(models);
-  const predicted = predictLiveState(models, snapshot, contract, { schema: opts.schema, governedRoles });
-  const governedLiveHash = governedLiveFingerprint(snapshot, contract, governedRoles);
-  const clean = predicted.hash === governedLiveHash;
-  return {
-    clean,
-    fingerprint: fingerprintLive(snapshot, contract).hash,
-    divergentSurfaces: clean
-      ? []
-      : divergentSurfaces(
-          predicted.canonical,
-          fingerprintState(snapshot, contract.tables, { governedRoles, sequenceGrants: contract.sequenceGrants }).canonical,
-        ),
-  };
-}

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

@@ -1,243 +0,0 @@
-/**
- * `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. db:adopt is the deliberate, auditable on-ramp for taking it AS IT IS: 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
- * edge — because a baseline that papered over a difference is the bypass under another name. It
- * writes NOTHING on refusal; --out is left untouched. That refusal is the HARDENING case (the
- * vocabulary cannot declare something live), and it needs no adoption commit: commit the intended
- * Models, db:plan, db:apply — descent proves no commit declares the database and treats the
- * reviewed plan as the origin (git-descent.ts, proven drift, 2026-09-07).
- *
- * 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 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 Models vocabulary cannot declare the surfaces above as they are live (a sequence grant with no INSERT behind it, for example), so no render can round-trip this database. That is the HARDENING case, and it needs no adoption commit: commit the Models you intend, then');
-    info('  everystack db:plan --stage <name>                       # mints the edge above as a reviewable plan');
-    info('  everystack db:apply --plan <file.plan.json> --stage <name>   # credential-free; no commit declares this database yet, so the reviewed plan is the ORIGIN and is recorded as such');
-    info('Every later db:apply descends from that recorded origin.');
-    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);
-  }
-
-  // The proof-compile sandbox MUST live inside the project, never the OS temp dir. The rendered
-  // barrel imports `@everystack/model`, and Node resolves a bare specifier by walking UP from the
-  // importing file looking for node_modules. pnpm hoists workspace packages to the repo root (an
-  // app dir has no local copy), so a dir under $TMPDIR cannot reach them and the compile crashes
-  // with "Cannot find module '@everystack/model'". cwd is inside the project, so a sandbox under it
-  // resolves exactly as the real db/models barrel will. (Reported by a consumer on 0.4.74; the
-  // scratch-sweep harness documents the same rule: $TMPDIR → MODULE_NOT_FOUND, project dir resolves.)
-  const sandboxDir = opts.sandboxDir ?? await fs.mkdtemp(path.join(process.cwd(), '.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);
-    // A failure to load the rendered barrel is a COMPILE error, not a connection or IAM problem —
-    // don't send the operator to check their credentials for it.
-    if (/Could not load models|Cannot find module/i.test(err.message ?? '')) {
-      info('This is the proof-compile step, not the database. The rendered Models could not be loaded —');
-      info('run db:adopt from inside your project (where @everystack/model resolves), and check the models compile.');
-    } else 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/live-models.ts

@@ -1,65 +0,0 @@
-/**
- * renderLiveModelFiles — the render db:pull and db:adopt SHARE.
- *
- * Both commands turn a live database into `field()` Models with the same posture: derive each
- * model's authz from the grants and policies already there (`abilities: 'live'`), render the
- * derived layer from the live catalog, and write the directory shape (one file per model + an
- * index barrel). Factoring it here is not only DRY — it is the round-trip's correctness. db:adopt
- * PROVES the rendered Models declare the live state; if adopt rendered even slightly differently
- * from pull, the proof could refuse on a cosmetic difference pull produces fine. One renderer,
- * one result.
- *
- * Pure: introspection results in, rendered files out. The command shells do the IO.
- */
-
-import type { SchemaSnapshot } from './schema-introspect';
-import type { AuthzContract } from './authz-contract';
-import type { DerivedCatalog } from './derived-introspect';
-import { renderModelFiles, pullableTables, modelVarName, type RenderedModelFile } from './model-render';
-import { renderDerivedSource } from './derived-render';
-import { fingerprintLive } from './schema-fingerprint';
-import { ungovernedGrants, ALWAYS_GOVERNED, type GrantExemption } from './authz-reconcile';
-import { deriveAbilities } from './authz-derive';
-
-export interface LiveModelRender {
-  /** The directory shape: one file per model + `index.ts` (the barrel that exports `models`). */
-  files: RenderedModelFile[];
-  /** The RAW live fingerprint — the baseline id db:adopt names the commit by. */
-  fingerprint: string;
-  /** Foreign grantees present at pull, exempt from revocation (the adoption baseline observation). */
-  exemptions: GrantExemption[];
-}
-
-/**
- * Render `field()` Models from a live database in the live-abilities, directory shape. The
- * `--govern-roles` complete-or-refuse gate runs here (pure re-derivation on the pulled tables),
- * before any file is written, so a listed role holding a column-scoped grant throws instead of
- * leaving a half-written tree.
- */
-export function renderLiveModelFiles(
-  snapshot: SchemaSnapshot,
-  contract: AuthzContract,
-  derivedCatalog: DerivedCatalog,
-  opts: { schema?: string | string[]; governRoles?: string[] } = {},
-): LiveModelRender {
-  const schema = opts.schema ?? 'public';
-  const governRoles = opts.governRoles ?? [];
-  const pulled = pullableTables(snapshot, schema);
-  const knownTables = new Map(pulled.map((t) => [t.table, modelVarName(t.table)]));
-  const derived = renderDerivedSource(derivedCatalog, { knownTables, sequences: snapshot.sequences });
-  const liveAuthz = new Map(contract.tables.map((t) => [t.table, t]));
-
-  // The --govern-roles gate, BEFORE any file is written: a governed role holding a column-scoped
-  // grant fails the render (deriveAbilities throws) rather than producing a half-owned barrel.
-  if (governRoles.length) {
-    const pulledNames = new Set(pulled.map((t) => t.table));
-    const govern = new Set(governRoles);
-    for (const [name, c] of liveAuthz) if (pulledNames.has(name)) deriveAbilities(c, { governRoles: govern });
-  }
-
-  const files = renderModelFiles(snapshot, { schema, abilities: 'live', liveAuthz, governRoles, derived });
-  // A governed role's grants are DECLARED (transcribed as privileges), so they are not also
-  // recorded as exemptions — that would double-book them, declared and exempted at once.
-  const exemptions = ungovernedGrants(contract, new Set([...ALWAYS_GOVERNED, ...governRoles]));
-  return { files, fingerprint: fingerprintLive(snapshot, contract).hash, exemptions };
-}