@everystack/cli 0.3.19 → 0.3.22

package/README.md

@@ -220,6 +220,8 @@ everystack db:reconcile                 # deploy the derived layer (functions/vi
 everystack db:fingerprint               # content-address the live base schema vs the Models — MATCH/MISMATCH
 everystack db:sync                      # make the database match your checkout — state + compute, one verb (dev DBs)
 everystack db:diff                      # the state edge between two declared states — no DB, CI-pure; reverse = computed rollback
+everystack db:plan | db:apply           # mint a reviewable plan against a target, apply it fingerprint-verified at both ends + the fast-forward rule (checkout must descend from the commit declaring the target's state)
+everystack db:check                     # the CI gate per PR: merged declared state composes + artifacts match regeneration (+ ephemeral from-scratch build w/ a scratch PG)
 
 # Security
 everystack db:doctor                    # is the DB least-privilege + RLS-subject?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.19",
+  "version": "0.3.22",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -78,7 +78,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.3.4"
+    "@everystack/model": "0.3.5"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.1.0",

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

@@ -0,0 +1,233 @@
+/**
+ * `everystack db:apply` — run a reviewed plan: verify → apply → verify
+ * (brick 4's runner).
+ *
+ *   db:apply --plan <file.plan.json> [--database-url <url>]
+ *
+ * The three moves, in order, none skippable:
+ *   1. VERIFY the target is exactly where the plan started — live
+ *      fingerprint == plan.from, or REFUSE. This is the concurrency lock:
+ *      two applies racing the same stage serialize on it (the second's
+ *      parent no longer matches; it re-mints against the new reality). A
+ *      hand-edited target refuses the same way. A target already at
+ *      plan.to is done — re-apply is idempotent, not an error.
+ *   2. APPLY the edge as one transaction, recorded in schema_log with the
+ *      plan's content address (`plan_ref`) and both fingerprints.
+ *   3. VERIFY the target landed exactly on plan.to. The plan is
+ *      self-contained — no models needed at apply time — and the endpoint
+ *      is exact even on brownfield targets (mint predicted it with the
+ *      unmodeled tables merged in). A mismatch here is a real fault, loud.
+ *
+ * Needs a direct connection (--database-url / DATABASE_URL): apply writes.
+ */
+
+import fs from 'node:fs/promises';
+import { introspectContract, type QueryRunner, type AuthzContract } from '../authz-contract.js';
+import { introspectSchema, type SchemaSnapshot } from '../schema-introspect.js';
+import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
+import { fingerprintLive } from '../schema-fingerprint.js';
+import { applyGeneratedStatements, currentGitRef } from '../state-apply.js';
+import { renderSchemaLogFingerprintUpdate } from '../derived-apply.js';
+import { checkPlanPrecondition, planHash, PLAN_VERSION, type EdgePlan } from '../edge-plan.js';
+import { verifyDescent, type LiveState } from '../git-descent.js';
+import { resolveModelsPath } from '../models-path.js';
+import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+// ---------------------------------------------------------------------------
+// The testable core.
+// ---------------------------------------------------------------------------
+
+export interface ApplyPlanOptions {
+  actor?: string | null;
+  /** Defaults to the plan's own gitRef (the intent that minted it). */
+  gitRef?: string | null;
+  /**
+   * The fast-forward rule (brick 7): called with the target's live state
+   * after the concurrency lock passes, BEFORE anything executes. Return
+   * `ok: false` to refuse — the checkout does not descend from the commit
+   * declaring the target's state. Omitted = no descent enforcement (tests,
+   * or an explicit, confirmed, snapshotted force).
+   */
+  verifyDescent?: (live: {
+    snapshot: SchemaSnapshot;
+    contract: AuthzContract;
+    fingerprint: string;
+  }) => Promise<{ ok: true } | { ok: false; reason: string }>;
+  /** Injectable clock for tests. */
+  now?: () => number;
+}
+
+export interface ApplyPlanResult {
+  status: 'applied' | 'already-applied' | 'refused' | 'descent-refused' | 'verify-failed';
+  liveFingerprint: string;
+  reason?: string;
+  logId?: number;
+}
+
+/** Verify → apply → verify. Pure orchestration over an injected QueryRunner. */
+export async function executeApplyPlan(
+  runner: QueryRunner,
+  plan: EdgePlan,
+  options: ApplyPlanOptions = {},
+): Promise<ApplyPlanResult> {
+  const before = await introspectSchema(runner);
+  const beforeAuthz = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+  const live = fingerprintLive(before, beforeAuthz).hash;
+
+  if (live === plan.toFingerprint) {
+    return { status: 'already-applied', liveFingerprint: live };
+  }
+  const pre = checkPlanPrecondition(plan, live);
+  if (!pre.ok) {
+    return { status: 'refused', liveFingerprint: live, reason: pre.reason };
+  }
+
+  if (options.verifyDescent) {
+    const descent = await options.verifyDescent({ snapshot: before, contract: beforeAuthz, fingerprint: live });
+    if (!descent.ok) {
+      return { status: 'descent-refused', liveFingerprint: live, reason: descent.reason };
+    }
+  }
+
+  const result = await applyGeneratedStatements(runner, plan.statements, {
+    actor: options.actor,
+    gitRef: options.gitRef ?? plan.gitRef,
+    planRef: planHash(plan),
+    fromFingerprint: live,
+    now: options.now,
+  });
+
+  const after = await introspectSchema(runner);
+  const afterAuthz = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+  const landed = fingerprintLive(after, afterAuthz).hash;
+  if (result.logId !== undefined) {
+    await runner(renderSchemaLogFingerprintUpdate(result.logId, landed));
+  }
+
+  if (landed !== plan.toFingerprint) {
+    return {
+      status: 'verify-failed',
+      liveFingerprint: landed,
+      reason: `applied, but the target landed on ${landed.slice(0, 12)} — the plan predicted ${plan.toFingerprint.slice(0, 12)}. Investigate before touching this database again (db:fingerprint, db:generate).`,
+      ...(result.logId !== undefined ? { logId: result.logId } : {}),
+    };
+  }
+  return {
+    status: 'applied',
+    liveFingerprint: landed,
+    ...(result.logId !== undefined ? { logId: result.logId } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The CLI shell.
+// ---------------------------------------------------------------------------
+
+export async function dbApplyCommand(flags: Record<string, string>): Promise<void> {
+  const planPath = flags.plan;
+  if (!planPath) {
+    fail('db:apply needs --plan <file.plan.json> — mint one with db:plan.');
+    process.exit(1);
+  }
+
+  let plan: EdgePlan;
+  try {
+    plan = JSON.parse(await fs.readFile(planPath, 'utf8'));
+  } catch (err: any) {
+    fail(`Could not read the plan at ${planPath}: ${err.message}`);
+    process.exit(1);
+  }
+  if (plan.v !== PLAN_VERSION) {
+    fail(`Plan version ${plan.v} is not this CLI's ${PLAN_VERSION} — re-mint with this version's db:plan.`);
+    process.exit(1);
+  }
+
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  if (dbSource.kind !== 'url') {
+    fail('db:apply writes — it needs a direct connection (--database-url or DATABASE_URL).');
+    process.exit(1);
+  }
+
+  // The fast-forward rule's force ceremony (design decision 9): explicit
+  // (--force-descent), snapshotted (its value NAMES the snapshot you took),
+  // and confirmed (--confirm). All three or no bypass.
+  const forceDescent = flags['force-descent'];
+  if (forceDescent !== undefined) {
+    if (forceDescent === 'true') {
+      fail('--force-descent needs the snapshot you took as its value: --force-descent <snapshot-ref> (take one first: db:snapshot or db:backup).');
+      process.exit(1);
+    }
+    if (flags.confirm !== 'true') {
+      fail('--force-descent bypasses the fast-forward rule — confirm explicitly with --confirm.');
+      process.exit(1);
+    }
+  }
+
+  step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+  const { runner, end } = await createUrlRunner(dbSource.url);
+
+  try {
+    info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
+    if (forceDescent !== undefined) {
+      warn(`DESCENT FORCED — the fast-forward rule is bypassed for this apply. Snapshot on record: ${forceDescent}.`);
+    }
+    step('Verifying the target is where the plan started...');
+    const result = await executeApplyPlan(runner, plan, {
+      actor: process.env.USER ?? null,
+      gitRef: currentGitRef() ?? plan.gitRef,
+      ...(forceDescent === undefined ? {
+        verifyDescent: async (live: LiveState & { fingerprint: string }) => {
+          step('Descent: searching git for the commit that declares the target\'s state...');
+          const verdict = await verifyDescent(resolveModelsPath(flags.models), live, {});
+          switch (verdict.status) {
+            case 'ok':
+              info(`descent: ${verdict.commit.slice(0, 12)} declares the target's state and is an ancestor of HEAD — fast-forward.`);
+              return { ok: true };
+            case 'fresh-target':
+              info('descent: fresh target (no tables) — nothing to protect, bootstrapping.');
+              return { ok: true };
+            case 'no-git':
+              warn('descent: not a git checkout — the fast-forward rule cannot be verified here.');
+              return { ok: true };
+            case 'diverged':
+            case 'drift':
+              return { ok: false, reason: verdict.reason };
+          }
+        },
+      } : {}),
+    });
+
+    switch (result.status) {
+      case 'already-applied':
+        success(`Already at ${plan.toFingerprint.slice(0, 12)} — nothing to do (idempotent re-apply).`);
+        break;
+      case 'refused':
+        fail(`REFUSED: ${result.reason}`);
+        process.exit(1);
+        break;
+      case 'descent-refused':
+        fail(`REFUSED (fast-forward rule): ${result.reason}`);
+        process.exit(1);
+        break;
+      case 'verify-failed':
+        fail(`Verify FAILED: ${result.reason}`);
+        process.exit(1);
+        break;
+      case 'applied':
+        success(`Applied and verified — the target is at ${result.liveFingerprint.slice(0, 12)}, exactly as the plan predicted. Recorded in everystack.schema_log (plan_ref ${planHash(plan).slice(0, 12)}).`);
+        break;
+    }
+  } catch (err: any) {
+    fail(`Apply failed and rolled back: ${err.message}`);
+    process.exit(1);
+  } finally {
+    await end?.();
+  }
+}

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

@@ -0,0 +1,306 @@
+/**
+ * `everystack db:check` — the CI regenerate-and-match gate (brick 7's PR
+ * invariant: the merged declared state must compose, and generated
+ * artifacts must match regeneration).
+ *
+ *   db:check [--models <barrel>] [--sql-dir db/sql] [--schema-out <file.ts>]
+ *            [--database-url <url>] [--json]
+ *
+ * Two rings, both from the checkout alone (no target database is ever
+ * touched — the gate runs on every PR):
+ *
+ *   STATIC — the models load and compose (a semantic merge conflict that
+ *   git can't see, like two branches declaring the same table, fails
+ *   here); the generated drizzle schema matches a byte-for-byte
+ *   regeneration (hand-edited artifacts and forgotten `db:generate` runs
+ *   fail loudly); the derived sources in db/sql parse.
+ *
+ *   EPHEMERAL COMPOSE — with a scratch PostgreSQL (`--database-url` /
+ *   DATABASE_URL), build the merged declared state FROM SCRATCH on an
+ *   ephemeral database (created and dropped inside the run): state, authz,
+ *   and the derived layer. Cross-layer breakage both layers hid from the
+ *   static ring — a matview referencing a dropped column — fails here,
+ *   mechanically. The bar is the brick-2 identity: the fresh database must
+ *   land EXACTLY on the models' fingerprint (MATCH), which is
+ *   regenerate-and-match at full strength.
+ *
+ * Exit 1 on any failure; nothing is ever skipped silently.
+ */
+
+import fs from 'node:fs/promises';
+import postgres from 'postgres';
+import type { ModelDescriptor } from '@everystack/model';
+import type { TableContract } from '../authz-contract.js';
+import { compileDeclaredState } from '../declared-diff.js';
+import { compileMigration } from '../migration-compile.js';
+import { compileDrizzleSource } from '../schema-source.js';
+import { parseSqlSources, type SourceFile } from '../derived-source.js';
+import { currentGitRef } from '../state-apply.js';
+import { createUrlRunner } from '../db-source.js';
+import { resolveModelsPath } from '../models-path.js';
+import { executeSync, buildSyncReport, readSqlDirIfPresent } from './db-sync.js';
+import { loadModels } from './db-generate.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+const DEFAULT_SQL_DIR = 'db/sql';
+const DEFAULT_SCHEMA_OUT = 'db/schema.generated.ts';
+
+// ---------------------------------------------------------------------------
+// The static ring (pure).
+// ---------------------------------------------------------------------------
+
+export interface CheckFinding {
+  level: 'ok' | 'note' | 'fail';
+  area: 'models' | 'compose' | 'artifact' | 'compute';
+  message: string;
+}
+
+export interface StaticCheckInput {
+  modelsPath: string;
+  /** null = the barrel did not load — the gate's first failure. */
+  models: ModelDescriptor[] | null;
+  modelsError?: string;
+  artifactPath: string;
+  /** null = no generated schema artifact on disk. */
+  artifactSource: string | null;
+  /** null = no db/sql directory. */
+  sources: SourceFile[] | null;
+}
+
+export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
+  const findings: CheckFinding[] = [];
+
+  if (input.models === null) {
+    findings.push({
+      level: 'fail',
+      area: 'models',
+      message: `models did not load from ${input.modelsPath}: ${input.modelsError ?? 'unknown error'}`,
+    });
+    return findings;
+  }
+  findings.push({ level: 'ok', area: 'models', message: `${input.models.length} model(s) loaded from ${input.modelsPath}` });
+
+  // The semantic merge conflict git can't see: two branches declaring the
+  // same table both merge cleanly — the merged state must still compose.
+  const seen = new Map<string, number>();
+  for (const m of input.models) seen.set(`${m.schema}.${m.table}`, (seen.get(`${m.schema}.${m.table}`) ?? 0) + 1);
+  const duplicates = [...seen.entries()].filter(([, n]) => n > 1).map(([t]) => t);
+  if (duplicates.length > 0) {
+    findings.push({
+      level: 'fail',
+      area: 'compose',
+      message: `the merged declared state does NOT compose: table(s) declared more than once — ${duplicates.join(', ')}. A merge landed two declarations of the same table; resolve to one.`,
+    });
+    return findings;
+  }
+  try {
+    compileDeclaredState(input.models);
+    const statements = compileMigration(input.models);
+    findings.push({ level: 'ok', area: 'compose', message: `declared state composes — ${statements.length} statement(s) from scratch` });
+  } catch (err: any) {
+    findings.push({ level: 'fail', area: 'compose', message: `the merged declared state does NOT compose: ${err.message}` });
+    return findings;
+  }
+
+  if (input.artifactSource === null) {
+    findings.push({
+      level: 'note',
+      area: 'artifact',
+      message: `no generated schema at ${input.artifactPath} — nothing to match (db:generate writes it)`,
+    });
+  } else if (input.artifactSource === compileDrizzleSource(input.models)) {
+    findings.push({ level: 'ok', area: 'artifact', message: `${input.artifactPath} matches regeneration byte-for-byte` });
+  } else {
+    findings.push({
+      level: 'fail',
+      area: 'artifact',
+      message: `${input.artifactPath} does NOT match regeneration — the models moved without db:generate, or the artifact was hand-edited (generated artifacts are never edited). Regenerate and commit.`,
+    });
+  }
+
+  if (input.sources === null) {
+    findings.push({ level: 'note', area: 'compute', message: 'no db/sql directory — derived layer not declared, nothing to parse' });
+  } else {
+    try {
+      const parsed = parseSqlSources(input.sources);
+      findings.push({
+        level: 'ok',
+        area: 'compute',
+        message: `${parsed.objects.length} derived object(s) parsed from ${input.sources.length} db/sql file(s)`,
+      });
+      for (const w of parsed.warnings) findings.push({ level: 'note', area: 'compute', message: w });
+    } catch (err: any) {
+      findings.push({ level: 'fail', area: 'compute', message: `db/sql does not parse: ${err.message}` });
+    }
+  }
+
+  return findings;
+}
+
+export function checkFailed(findings: CheckFinding[]): boolean {
+  return findings.some((f) => f.level === 'fail');
+}
+
+// ---------------------------------------------------------------------------
+// The ephemeral compose ring.
+// ---------------------------------------------------------------------------
+
+/** Every role the contract grants to or names in a policy — the compose DB needs them. */
+export function rolesFromContract(tables: TableContract[]): string[] {
+  const roles = new Set<string>();
+  for (const t of tables) {
+    for (const grantee of Object.keys(t.grants)) roles.add(grantee);
+    for (const grantee of Object.keys(t.columnGrants ?? {})) roles.add(grantee);
+    for (const p of t.policies) for (const r of p.roles) roles.add(r);
+  }
+  roles.delete('PUBLIC');
+  roles.delete('public');
+  return [...roles].sort();
+}
+
+export interface EphemeralComposeResult {
+  database: string;
+  createdRoles: string[];
+  converged: boolean;
+  fingerprintMatch: boolean;
+  fingerprint: string;
+  report: string[];
+}
+
+/**
+ * Build the declared state from scratch on an ephemeral database: CREATE
+ * DATABASE, roles the contract references (NOLOGIN, cluster-level, created
+ * only if absent), one `executeSync` for both layers, DROP DATABASE —
+ * always, error or not. The bar is `converged && fingerprintMatch`: a
+ * fresh database has nothing unmodeled and nothing to drop, so anything
+ * short of MATCH is a real compose fault.
+ */
+export async function executeEphemeralCompose(
+  adminUrl: string,
+  models: ModelDescriptor[],
+  sources: SourceFile[] | null,
+  opts: { actor?: string | null; gitRef?: string | null } = {},
+): Promise<EphemeralComposeResult> {
+  const dbName = `escheck_${process.pid}_${Date.now()}`;
+  const admin = postgres(adminUrl, { max: 1 });
+  try {
+    await admin.unsafe(`CREATE DATABASE "${dbName}"`);
+  } finally {
+    await admin.end();
+  }
+
+  const { runner, end } = await createUrlRunner(adminUrl.replace(/\/[^/?]+(\?|$)/, `/${dbName}$1`));
+  try {
+    const roles = rolesFromContract(compileDeclaredState(models).contract.tables);
+    for (const role of roles) {
+      if (!/^[a-z_][a-z0-9_$]*$/i.test(role)) {
+        throw new Error(`contract references a role name that is not a plain identifier: ${JSON.stringify(role)}`);
+      }
+      await runner(
+        `DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${role}') THEN CREATE ROLE "${role}" NOLOGIN; END IF; END $$`,
+      );
+    }
+
+    const run = await executeSync(runner, models, sources, {
+      actor: opts.actor ?? 'db:check',
+      gitRef: opts.gitRef ?? null,
+    });
+    return {
+      database: dbName,
+      createdRoles: roles,
+      converged: run.converged,
+      fingerprintMatch: run.fingerprintMatch,
+      fingerprint: run.state.toFingerprint,
+      report: buildSyncReport(run),
+    };
+  } finally {
+    await end?.();
+    const reaper = postgres(adminUrl, { max: 1 });
+    try {
+      await reaper.unsafe(`DROP DATABASE IF EXISTS "${dbName}" WITH (FORCE)`);
+    } finally {
+      await reaper.end();
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The CLI shell.
+// ---------------------------------------------------------------------------
+
+const MARK: Record<CheckFinding['level'], string> = { ok: '=', note: '·', fail: '!' };
+
+export async function dbCheckCommand(flags: Record<string, string>): Promise<void> {
+  const modelsPath = resolveModelsPath(flags.models);
+  let models: ModelDescriptor[] | null = null;
+  let modelsError: string | undefined;
+  try {
+    step(`Loading models from ${modelsPath}...`);
+    models = await loadModels(modelsPath);
+  } catch (err: any) {
+    modelsError = err.message;
+  }
+
+  const artifactPath = flags['schema-out'] || DEFAULT_SCHEMA_OUT;
+  let artifactSource: string | null = null;
+  try {
+    artifactSource = await fs.readFile(artifactPath, 'utf8');
+  } catch {
+    artifactSource = null;
+  }
+  const sources = await readSqlDirIfPresent(flags['sql-dir'] || DEFAULT_SQL_DIR);
+
+  const findings = runStaticChecks({ modelsPath, models, modelsError, artifactPath, artifactSource, sources });
+  for (const f of findings) {
+    (f.level === 'fail' ? warn : info)(`${MARK[f.level]} ${f.area}: ${f.message}`);
+  }
+
+  let ephemeral: EphemeralComposeResult | null = null;
+  let ephemeralError: string | null = null;
+  const url = flags['database-url'] || process.env.DATABASE_URL;
+  const staticFailed = checkFailed(findings);
+  if (staticFailed) {
+    warn('ephemeral compose skipped — fix the static failures first.');
+  } else if (!url) {
+    warn('ephemeral compose SKIPPED — no --database-url / DATABASE_URL. Point db:check at a scratch PostgreSQL for the full gate (it creates and drops an ephemeral database).');
+  } else {
+    step('Composing the declared state from scratch on an ephemeral database...');
+    try {
+      ephemeral = await executeEphemeralCompose(url, models!, sources, {
+        actor: process.env.USER ?? 'db:check',
+        gitRef: currentGitRef(),
+      });
+      for (const line of ephemeral.report) info(`  ${line}`);
+    } catch (err: any) {
+      ephemeralError = err.message;
+      warn(`! compose: the declared state does NOT build from scratch: ${ephemeralError}`);
+    }
+  }
+
+  const ephemeralFailed = ephemeralError !== null
+    || (ephemeral !== null && !(ephemeral.converged && ephemeral.fingerprintMatch));
+  const failed = staticFailed || ephemeralFailed;
+
+  if (flags.json === 'true') {
+    console.log(JSON.stringify({
+      findings,
+      ephemeral: ephemeral === null ? null : {
+        converged: ephemeral.converged,
+        fingerprintMatch: ephemeral.fingerprintMatch,
+        fingerprint: ephemeral.fingerprint,
+        createdRoles: ephemeral.createdRoles,
+      },
+      ephemeralError,
+      ephemeralRan: ephemeral !== null,
+      failed,
+    }, null, 2));
+  } else if (failed) {
+    fail('db:check FAILED — the merged declared state is not shippable as-is (findings above).');
+  } else if (ephemeral !== null) {
+    success(`db:check passed — declared state composes from scratch and lands MATCH at ${ephemeral.fingerprint.slice(0, 12)}.`);
+  } else {
+    success('db:check passed (static ring only — no database provided for the ephemeral compose).');
+  }
+
+  if (failed) process.exit(1);
+}

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

@@ -0,0 +1,123 @@
+/**
+ * `everystack db:plan` — mint a verified edge against a target database
+ * (brick 4's mint surface; the review artifact of the deploy boundary).
+ *
+ *   db:plan [--stage <name> | --database-url <url>] [--models <barrel>]
+ *           [--allow-drops] [--out db.plan.json | --out -]
+ *
+ * Minting asks the TARGET its fingerprint (no repo-side release pointer to
+ * trust), diffs the checkout's models against it, and writes one reviewable
+ * plan: the edge plus both endpoint fingerprints. `from` is the target's
+ * exact live fingerprint — db:apply refuses if the state moves before the
+ * plan lands. `to` is the predicted endpoint, exact even with unmodeled
+ * tables. Held drops refuse the mint: a plan is complete or it is not a
+ * plan (--allow-drops carries the destruction explicitly, counted red).
+ *
+ * Plans are EPHEMERAL — attach them to the release/PR run, never commit
+ * them (committing plans would rebuild the tape). Minting is read-only, so
+ * it works over the ops Lambda (--stage) as well as a direct connection.
+ */
+
+import fs from 'node:fs/promises';
+import type { ModelDescriptor } from '@everystack/model';
+import { introspectContract, type QueryRunner } from '../authz-contract.js';
+import { introspectSchema } from '../schema-introspect.js';
+import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
+import { mintEdgePlan, planHash, buildPlanSummary } from '../edge-plan.js';
+import { verifyDescent } from '../git-descent.js';
+import { currentGitRef } from '../state-apply.js';
+import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+import { resolveModelsPath } from '../models-path.js';
+import { resolveConfig, opsFunction } from '../config.js';
+import { invokeAction } from '../aws.js';
+import { loadModels } from './db-generate.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+const DEFAULT_OUT = 'db.plan.json';
+
+/** A QueryRunner backed by the ops Lambda `db:query` action (read-only). */
+function lambdaRunner(region: string, fn: string): QueryRunner {
+  return async (sql: string) => {
+    const result: any = await invokeAction(region, fn, 'db:query', { sql });
+    if (result?.error) throw new Error(`Query failed: ${result.error}`);
+    return result?.rows ?? [];
+  };
+}
+
+export async function dbPlanCommand(flags: Record<string, string>): Promise<void> {
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  const modelsPath = resolveModelsPath(flags.models);
+  let models: ModelDescriptor[];
+  try {
+    step(`Loading models from ${modelsPath}...`);
+    models = await loadModels(modelsPath);
+    info(`${models.length} model(s).`);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  let runner: QueryRunner;
+  let end: (() => Promise<void>) | undefined;
+  if (dbSource.kind === 'url') {
+    step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+    ({ runner, end } = await createUrlRunner(dbSource.url));
+  } else {
+    step('Resolving deployed config...');
+    const config = await resolveConfig(flags.stage);
+    runner = lambdaRunner(config.region, opsFunction(config));
+  }
+
+  try {
+    step('Asking the target its fingerprint (introspecting state + authz)...');
+    const snapshot = await introspectSchema(runner);
+    const contract = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+
+    let plan;
+    try {
+      plan = mintEdgePlan(models, snapshot, contract, {
+        allowDrops: flags['allow-drops'] === 'true',
+        gitRef: currentGitRef(),
+        actor: process.env.USER ?? null,
+      });
+    } catch (err: any) {
+      fail(`Mint refused: ${err.message}`);
+      process.exit(1);
+    }
+
+    const out = flags.out || DEFAULT_OUT;
+    const body = JSON.stringify(plan, null, 2) + '\n';
+    if (out === '-') {
+      console.log(body);
+    } else {
+      await fs.writeFile(out, body, 'utf8');
+    }
+
+    for (const line of buildPlanSummary(plan)) info(line);
+    info(`plan_ref: ${planHash(plan).slice(0, 12)}`);
+
+    // The fast-forward rule, warn-only at mint time (db:apply enforces it):
+    // a stale checkout mints a legal-looking plan whose edge REVERTS merged
+    // work — say so on the review surface, where a human still reads it.
+    if (plan.statements.length > 0) {
+      const verdict = await verifyDescent(modelsPath, { snapshot, contract }, {});
+      if (verdict.status === 'diverged' || verdict.status === 'drift') {
+        warn(`descent: ${verdict.reason}`);
+        warn('db:apply from this checkout will refuse this plan — rebase first, then re-mint.');
+      }
+    }
+    if (out !== '-') {
+      success(`Wrote ${out} — review it, then \`everystack db:apply --plan ${out}\`.`);
+      warn('Plans are ephemeral release artifacts — attach to the run, do NOT commit.');
+    }
+  } finally {
+    await end?.();
+  }
+}