@everystack/cli 0.3.18 → 0.3.21

package/README.md

@@ -219,6 +219,8 @@ everystack db:pull                      # introspect a live DB → field() Model
 everystack db:reconcile                 # deploy the derived layer (functions/views/matviews) from db/sql — no migrations
 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
 
 # Security
 everystack db:doctor                    # is the DB least-privilege + RLS-subject?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.18",
+  "version": "0.3.21",
   "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,170 @@
+/**
+ * `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 } from '../authz-contract.js';
+import { introspectSchema } 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 { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+import { step, success, fail, info } 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;
+  /** Injectable clock for tests. */
+  now?: () => number;
+}
+
+export interface ApplyPlanResult {
+  status: 'applied' | 'already-applied' | '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 };
+  }
+
+  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);
+  }
+
+  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` : ''})`);
+    step('Verifying the target is where the plan started...');
+    const result = await executeApplyPlan(runner, plan, {
+      actor: process.env.USER ?? null,
+      gitRef: currentGitRef() ?? plan.gitRef,
+    });
+
+    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 '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-diff.ts

@@ -0,0 +1,87 @@
+/**
+ * `everystack db:diff` — the state edge between two declared states, no
+ * database anywhere (brick 3's command surface).
+ *
+ *   db:diff --from-models <barrel> [--to-models db/models/index.ts]
+ *           [--allow-drops] [--check] [--json]
+ *
+ * Compiles both model sets and prints the SQL edge from one to the other —
+ * the same statement grammar db:generate produces (executable DDL, held
+ * drops, notices), computed with no connection, no network, no side
+ * effects. Deterministic: same two states, same edge, forever.
+ *
+ * The uses this unlocks:
+ * - CI plan preview: materialize the base branch's models, diff to HEAD's,
+ *   attach the edge to the PR. `--check` exits 1 when the edge is non-empty.
+ * - Computed rollback: swap the flags. The reverse edge is derived from the
+ *   same two states — nobody authors a down migration.
+ * - Review: the exact SQL a `db:sync` / `db:generate --apply` will run when
+ *   the target database sits at the from-state.
+ *
+ * Between two declared states a removed table is intent (unlike the live
+ * diff, where an undeclared table is unmodeled and untouchable) — removals
+ * surface as drops, held back unless `--allow-drops`, like everywhere else.
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import { diffDeclaredStates } from '../declared-diff.js';
+import { classifyGeneratedStatements } from '../state-apply.js';
+import { fingerprintModels } from '../schema-fingerprint.js';
+import { resolveModelsPath } from '../models-path.js';
+import { loadModels } from './db-generate.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+export async function dbDiffCommand(flags: Record<string, string>): Promise<void> {
+  const fromPath = flags['from-models'];
+  if (!fromPath) {
+    fail('db:diff needs --from-models <barrel> — the declared state to diff FROM (--to-models defaults to the checkout\'s db/models).');
+    process.exit(1);
+  }
+  const toPath = resolveModelsPath(flags['to-models']);
+
+  let from: ModelDescriptor[];
+  let to: ModelDescriptor[];
+  try {
+    step(`Loading FROM models from ${fromPath}...`);
+    from = await loadModels(fromPath);
+    step(`Loading TO models from ${toPath}...`);
+    to = await loadModels(toPath);
+    info(`${from.length} → ${to.length} model(s).`);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  const statements = diffDeclaredStates(from, to, { allowDrops: flags['allow-drops'] === 'true' });
+  const classified = classifyGeneratedStatements(statements);
+  const fromFingerprint = fingerprintModels(from).hash;
+  const toFingerprint = fingerprintModels(to).hash;
+
+  if (flags.json === 'true') {
+    console.log(JSON.stringify({
+      fromFingerprint,
+      toFingerprint,
+      statements,
+      executable: classified.executable.length,
+      heldDrops: classified.heldDrops.length,
+      notices: classified.notices.length,
+      empty: statements.length === 0,
+    }, null, 2));
+  } else {
+    console.log('');
+    if (statements.length === 0) {
+      success('The two states are identical — the edge is empty.');
+    } else {
+      info(`edge — ${statements.length} statement(s):`);
+      console.log('');
+      for (const s of statements) console.log(s.endsWith(';') ? s : `${s};`);
+      console.log('');
+      if (classified.heldDrops.length) warn(`${classified.heldDrops.length} destructive change(s) held back as comments (re-run with --allow-drops to emit them).`);
+      if (classified.notices.length) info(`${classified.notices.length} notice(s) — renames / manual follow-ups.`);
+    }
+    info(`fingerprint: ${fromFingerprint.slice(0, 12)} → ${toFingerprint.slice(0, 12)}`);
+  }
+
+  if (flags.check === 'true' && statements.length > 0) process.exit(1);
+  process.exit(0);
+}

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

@@ -0,0 +1,111 @@
+/**
+ * `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 { 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)}`);
+    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?.();
+  }
+}

package/src/cli/declared-diff.ts

@@ -0,0 +1,89 @@
+/**
+ * declared-diff — the state edge between two DECLARED states, no live
+ * database anywhere (brick 3 of the migration-authority design).
+ *
+ * The live diff (db:generate) asks "what does the database need to become
+ * the models?" — one side is introspected. This module answers the same
+ * question between two model sets: compile the FROM models to the exact
+ * snapshot + contract shapes introspection produces, and run the one diff
+ * engine over them (`scope: 'full'` — between declared states the from-side
+ * is fully known, so a removed table is intent and becomes a drop, held by
+ * the same `allowDrops` gate as everywhere else).
+ *
+ * What this buys, per the design:
+ * - CI-pure plan previews: the edge between any two git states is
+ *   `diffDeclaredStates(modelsAt(A), modelsAt(B))` — no database, no
+ *   network, deterministic.
+ * - Computed rollback: the reverse edge is the same call with the arguments
+ *   swapped — `diff(B, A)` — derived, never authored. Down migrations stop
+ *   being a thing anyone writes.
+ * - The seed of plan minting (brick 4/7): a plan is this edge plus the two
+ *   fingerprints naming its endpoints.
+ *
+ * The identity that makes it trustworthy, proven on real PostgreSQL in the
+ * integration suite: build a database at A, apply `diff(A→B)`, and
+ * `fingerprintLive` equals `fingerprintModels(B)` exactly — the pure edge
+ * and the live edge are the same edge.
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import type { SchemaSnapshot } from './schema-introspect.js';
+import type { AuthzContract } from './authz-contract.js';
+import { compileTableSchema, compileEnums } from './schema-compile.js';
+import { compileTableContract } from './authz-compile.js';
+import { generateMigrationSql } from './migration-generate.js';
+
+export interface DeclaredState {
+  snapshot: SchemaSnapshot;
+  contract: AuthzContract;
+}
+
+export interface DeclaredDiffOptions {
+  /** The Postgres schema the Models default to. Default: `public`. */
+  schema?: string;
+  /** Emit real drops for removals. Default false — held back as comments. */
+  allowDrops?: boolean;
+}
+
+/**
+ * Compile a model set to the shapes introspection produces — the same
+ * compilation `fingerprintModels` hashes, exposed as a state the diff
+ * engine can treat as "current".
+ */
+export function compileDeclaredState(
+  models: ModelDescriptor[],
+  opts: { schema?: string } = {},
+): DeclaredState {
+  const schema = opts.schema ?? 'public';
+  return {
+    snapshot: {
+      tables: models.map((m) => compileTableSchema(m, { schema })),
+      enums: compileEnums(models),
+    },
+    contract: {
+      tables: models.map((m) => compileTableContract(m, { schema })),
+      functions: [],
+    },
+  };
+}
+
+/**
+ * The pure state edge `from → to`: the statement stream `db:generate` would
+ * produce against a live database at `from`, computed with no database.
+ * Same statement grammar throughout — executable DDL, held drops as
+ * comments, notices — so `classifyGeneratedStatements` and the apply path
+ * treat it identically. Swap the arguments for the reverse edge.
+ */
+export function diffDeclaredStates(
+  from: ModelDescriptor[],
+  to: ModelDescriptor[],
+  opts: DeclaredDiffOptions = {},
+): string[] {
+  const a = compileDeclaredState(from, { schema: opts.schema });
+  return generateMigrationSql(to, a.snapshot, {
+    schema: opts.schema,
+    allowDrops: opts.allowDrops,
+    liveAuthz: a.contract,
+    scope: 'full',
+  });
+}

package/src/cli/edge-plan.ts

@@ -0,0 +1,180 @@
+/**
+ * edge-plan — verified edges: a state diff plus the two fingerprints naming
+ * its endpoints (brick 4 of the migration-authority design).
+ *
+ * A plan is minted against a target: `from` is the target's EXACT live
+ * fingerprint — that is the lock; apply refuses when the live state moved —
+ * and `to` is the PREDICTED live fingerprint after apply: the compiled
+ * declared state merged with the target's unmodeled tables as-is. The
+ * prediction is exact (proven on real PostgreSQL in the edge-runner
+ * integration suite), which buys two properties the tape never had:
+ * verify-after needs no models — the plan is self-contained — and it stays
+ * exact on brownfield targets where undeclared tables keep the live
+ * fingerprint off the models-only one forever.
+ *
+ * Plans must be COMPLETE: held drops refuse the mint. A reviewed plan
+ * either carries its destruction explicitly (`--allow-drops`, counted and
+ * shown red) or the models change first — the predicted endpoint is always
+ * reachable, so a verify-after mismatch is always a real fault, never
+ * "held drops, by design".
+ *
+ * Plans are EPHEMERAL release artifacts (design decision 6): minted at the
+ * deploy boundary, reviewed, applied, reconstructible forever from git —
+ * never committed. Their identity is `planHash` — sha256 over the canonical
+ * JSON — recorded as `plan_ref` on the schema_log row the apply writes.
+ */
+
+import { createHash } from 'node:crypto';
+import type { ModelDescriptor } from '@everystack/model';
+import type { SchemaSnapshot } from './schema-introspect.js';
+import type { AuthzContract } from './authz-contract.js';
+import { generateMigrationSql, unmodeledTables } from './migration-generate.js';
+import { classifyGeneratedStatements } from './state-apply.js';
+import { fingerprintLive, fingerprintState, fingerprintModels, stableStringify } from './schema-fingerprint.js';
+import { compileDeclaredState } from './declared-diff.js';
+import { compileTableRenames } from './schema-compile.js';
+
+export const PLAN_VERSION = 1;
+
+export interface EdgePlan {
+  v: number;
+  /** The target's exact live fingerprint at mint time — the lock. */
+  fromFingerprint: string;
+  /** The predicted live fingerprint after apply — exact, unmodeled-aware. */
+  toFingerprint: string;
+  /** The models-only fingerprint — context for the strong claim. Equals `to` when nothing is unmodeled. */
+  declaredFingerprint: string;
+  /** The edge, in db:generate's statement grammar (no held drops — mint refuses them). */
+  statements: string[];
+  executable: number;
+  /** Executable statements that DROP something — shown red, explicit by construction. */
+  destructive: number;
+  notices: number;
+  /** Live tables no model declares — untouched by the edge, riding into `to` as-is. */
+  unmodeled: string[];
+  gitRef: string | null;
+  mintedBy: string | null;
+}
+
+export interface MintOptions {
+  schema?: string;
+  allowDrops?: boolean;
+  gitRef?: string | null;
+  actor?: string | null;
+}
+
+/**
+ * Mint the edge from a target's introspected state to the models' declared
+ * state. Pure: introspection in, plan out. Throws when the edge would hold
+ * drops back — a plan must be complete to have a reachable endpoint.
+ */
+export function mintEdgePlan(
+  models: ModelDescriptor[],
+  snapshot: SchemaSnapshot,
+  contract: AuthzContract,
+  opts: MintOptions = {},
+): EdgePlan {
+  const statements = generateMigrationSql(models, snapshot, {
+    schema: opts.schema,
+    allowDrops: opts.allowDrops,
+    liveAuthz: contract,
+  });
+  const classified = classifyGeneratedStatements(statements);
+  if (classified.heldDrops.length > 0) {
+    throw new Error(
+      `the edge holds ${classified.heldDrops.length} destructive change(s) back — a plan must be complete. ` +
+      'Re-mint with --allow-drops to carry the destruction explicitly, or mark the contraction in the models first and drop later.',
+    );
+  }
+
+  // The predicted endpoint: declared tables land exactly on their compiled
+  // shapes (that is what apply-and-verify proves), unmodeled tables and
+  // enums ride through untouched. A pending table rename's SOURCE does not
+  // ride through — the edge renames it away, and it lands as its declared
+  // new name. fingerprintState sorts internally, so merge order is
+  // irrelevant.
+  const declared = compileDeclaredState(models, { schema: opts.schema });
+  const declaredTables = new Set(declared.snapshot.tables.map((t) => t.table));
+  const currentNames = new Set(snapshot.tables.map((t) => t.table));
+  const pendingRenameSources = new Set(
+    Object.entries(compileTableRenames(models, { schema: opts.schema }))
+      .filter(([to, from]) => !currentNames.has(to) && currentNames.has(from))
+      .map(([, from]) => from),
+  );
+  const ridesThrough = (table: string): boolean =>
+    !declaredTables.has(table) && !pendingRenameSources.has(table);
+  const declaredEnumList = declared.snapshot.enums ?? [];
+  const declaredEnums = new Set(declaredEnumList.map((e) => e.name));
+  const mergedSnapshot: SchemaSnapshot = {
+    tables: [
+      ...declared.snapshot.tables,
+      ...snapshot.tables.filter((t) => ridesThrough(t.table)),
+    ],
+    enums: [
+      ...declaredEnumList,
+      ...(snapshot.enums ?? []).filter((e) => !declaredEnums.has(e.name)),
+    ],
+  };
+  const mergedAuthz = [
+    ...declared.contract.tables,
+    ...contract.tables.filter((t) => ridesThrough(t.table)),
+  ];
+
+  return {
+    v: PLAN_VERSION,
+    fromFingerprint: fingerprintLive(snapshot, contract).hash,
+    toFingerprint: fingerprintState(mergedSnapshot, mergedAuthz).hash,
+    declaredFingerprint: fingerprintModels(models, { schema: opts.schema }).hash,
+    statements,
+    executable: classified.executable.length,
+    // Data-destructive only: dropping a policy/grant is recoverable metadata
+    // (the authz phase is data-safe by construction); dropping a table,
+    // column, or type is not.
+    destructive: classified.executable.filter((s) => /\bDROP\s+(TABLE|COLUMN|TYPE)\b/.test(s)).length,
+    notices: classified.notices.length,
+    unmodeled: unmodeledTables(models, snapshot),
+    gitRef: opts.gitRef ?? null,
+    mintedBy: opts.actor ?? null,
+  };
+}
+
+/** The plan's content address — recorded as `plan_ref` on the schema_log row. */
+export function planHash(plan: EdgePlan): string {
+  return createHash('sha256').update(stableStringify(plan)).digest('hex');
+}
+
+export type PlanPrecondition = { ok: true } | { ok: false; reason: string };
+
+/** The lock: apply only when the target is exactly where the plan started. */
+export function checkPlanPrecondition(plan: EdgePlan, liveFingerprint: string): PlanPrecondition {
+  if (liveFingerprint === plan.fromFingerprint) return { ok: true };
+  return {
+    ok: false,
+    reason:
+      `target is at ${liveFingerprint.slice(0, 12)}, the plan expects ${plan.fromFingerprint.slice(0, 12)} — ` +
+      'the state moved since minting (a concurrent apply or a hand edit). Re-mint with db:plan against current reality.',
+  };
+}
+
+const short = (hash: string): string => hash.slice(0, 12);
+
+/** Human summary of a plan — the review surface. */
+export function buildPlanSummary(plan: EdgePlan): string[] {
+  const lines: string[] = [];
+  lines.push(`edge: ${short(plan.fromFingerprint)} → ${short(plan.toFingerprint)}`);
+  if (plan.statements.length === 0) {
+    lines.push('empty — the target already declares this state');
+    return lines;
+  }
+  lines.push(`${plan.executable} executable statement(s), ${plan.notices} notice(s)`);
+  if (plan.destructive > 0) {
+    lines.push(`! ${plan.destructive} DESTRUCTIVE statement(s) — drops carried explicitly, review them`);
+  }
+  if (plan.unmodeled.length > 0) {
+    lines.push(`· ${plan.unmodeled.length} unmodeled table(s) ride through untouched: ${plan.unmodeled.join(', ')}`);
+  }
+  if (plan.toFingerprint !== plan.declaredFingerprint) {
+    lines.push(`· predicted endpoint differs from the models-only fingerprint (${short(plan.declaredFingerprint)}) — the unmodeled tables above explain it`);
+  }
+  return lines;
+}

package/src/cli/index.ts

@@ -14,6 +14,9 @@ import { dbPullCommand } from './commands/db-pull.js';
 import { dbReconcileCommand } from './commands/db-reconcile.js';
 import { dbFingerprintCommand } from './commands/db-fingerprint.js';
 import { dbSyncCommand } from './commands/db-sync.js';
+import { dbDiffCommand } from './commands/db-diff.js';
+import { dbPlanCommand } from './commands/db-plan.js';
+import { dbApplyCommand } from './commands/db-apply.js';
 import { dbSnapshotCommand, dbSnapshotsCommand } from './commands/db-snapshot.js';
 import { dbBackupProbeCommand, dbBackupCommand, dbBackupsCommand, dbRestoreCommand, dbBackupDownloadCommand } from './commands/db-backup.js';
 import { consoleCommand } from './commands/console.js';
@@ -184,6 +187,15 @@ async function main() {
     case 'db:sync':
       await dbSyncCommand(flags);
       break;
+    case 'db:diff':
+      await dbDiffCommand(flags);
+      break;
+    case 'db:plan':
+      await dbPlanCommand(flags);
+      break;
+    case 'db:apply':
+      await dbApplyCommand(flags);
+      break;
     case 'db:authz:pull':
       await dbAuthzPullCommand(flags);
       break;
@@ -309,6 +321,9 @@ Usage:
   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      [--sql-dir db/sql] [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--overwrite-drift] [--json]  Reconcile the derived layer (functions/views/matviews) against db/sql sources: plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (direct connection only) and records provenance + schema_log. Hand-edits are drift (never overwritten silently); first contact with existing objects wants --baseline, once.
   everystack db:sync           [--database-url <url>] [--models <barrel>] [--sql-dir db/sql] [--schema-out <file.ts>] [--allow-drops] [--overwrite-drift] [--baseline] [--json]  Make the database match your checkout — one verb, both layers: apply the state diff (tables+authz, one transaction, verified by re-diff), reconcile the derived layer against db/sql, report the resulting fingerprint vs the models' declared one. Dev databases only (direct connection required); DROPs held back unless --allow-drops; derived drift refuses unless --overwrite-drift; exit 1 when not converged
+  everystack db:diff           --from-models <barrel> [--to-models db/models/index.ts] [--allow-drops] [--check] [--json]  The state edge between two declared states, NO database: the SQL db:generate would produce, computed purely — CI plan previews (--check exits 1 on a non-empty edge) and computed rollbacks (swap the flags)
+  everystack db:plan           [--stage <name> | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only — works via the ops Lambda; plans are ephemeral, never committed
+  everystack db:apply          --plan <file.plan.json> [--database-url <url>]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), apply as one transaction (schema_log w/ plan_ref), verify it landed exactly on plan.to. Idempotent when already at the target state; direct connection required
   everystack db:authz:pull     [--stage <name>] [--dir authz]  Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
   everystack db:authz:diff     [--stage <name>] [--dir authz]  Validate the live DB against the committed contract (non-zero exit on drift)
   everystack db:authz:test     [--stage <name>] [--dir authz]  Red-team enforcement: SET ROLE + attempt per role/table/command (non-zero exit on a hole)

package/src/cli/migration-generate.ts

@@ -18,7 +18,7 @@
 import type { ModelDescriptor } from '@everystack/model';
 import type { SchemaSnapshot } from './schema-introspect.js';
 import type { AuthzContract } from './authz-contract.js';
-import { compileTableSchema, compileRenames, compileCreateTable, compileEnums } from './schema-compile.js';
+import { compileTableSchema, compileRenames, compileTableRenames, compileCreateTable, compileEnums } from './schema-compile.js';
 import { compileTableContract } from './authz-compile.js';
 import { emitReconcileSql } from './authz-reconcile.js';
 import { diffSchema, emitSchemaSql, type SchemaChange } from './schema-diff.js';
@@ -33,6 +33,15 @@ export interface GenerateOptions {
    * never silently loses data. Destruction needs intent, the same rule renames are built on.
    */
   allowDrops?: boolean;
+  /**
+   * How much of `current` the diff may see. `'declared'` (default) scopes it to the
+   * tables/enums the Models declare — right against a LIVE database, where an
+   * undeclared table is unmodeled (auth, jobs, another team's) and must be invisible,
+   * never dropped. `'full'` diffs everything — right between two DECLARED states
+   * (declared-diff), where the from-side is fully known and absence is intent: a
+   * removed table/enum becomes a drop (still held by the `allowDrops` gate).
+   */
+  scope?: 'declared' | 'full';
   /**
    * The live authorization contract (`introspectContract`). When provided, the migration
    * carries the authz layer too — the Models' `abilities` compiled to RLS/policies/grants,
@@ -73,6 +82,11 @@ function holdDrop(sql: string): string {
 export function unmodeledTables(models: ModelDescriptor[], current: SchemaSnapshot, opts: GenerateOptions = {}): string[] {
   const schema = opts.schema ?? 'public';
   const declared = new Set(models.map((m) => `${schema}.${m.table}`));
+  // A pending table rename's source is ours — declared under its new name.
+  const currentNames = new Set(current.tables.map((t) => t.table));
+  for (const [to, from] of Object.entries(compileTableRenames(models, { schema }))) {
+    if (!currentNames.has(to)) declared.add(from);
+  }
   return current.tables.map((t) => t.table).filter((t) => !declared.has(t)).sort();
 }
 
@@ -94,13 +108,29 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
   const declaredTables = new Set(desired.tables.map((t) => t.table));
   const declaredEnums = new Set(desiredEnums.map((e) => e.name));
   // Scope both tables and enums to what the Models declare — an undeclared table OR enum
-  // (auth, jobs, observability ship their own) is invisible to the diff, so it is never dropped.
-  const scopedCurrent: SchemaSnapshot = {
-    tables: current.tables.filter((t) => declaredTables.has(t.table)),
-    enums: (current.enums ?? []).filter((e) => declaredEnums.has(e.name)),
-  };
+  // (auth, jobs, observability ship their own) is invisible to the diff, so it is never
+  // dropped. `scope: 'full'` (declared-diff, model→model) skips the filter: there the
+  // from-side is fully declared too, so absence is intent and removals must surface.
+  // Table-level rename intent: a pending rename's SOURCE is ours too — it must
+  // survive the declared-scope filter (so the diff's pre-pass can see it) and
+  // its authz contract must be read under the NEW name (the policies/grants
+  // ride the rename in Postgres; without the rewrite they would re-emit and
+  // collide).
+  const tableRenames = compileTableRenames(models, { schema });
+  const currentNames = new Set(current.tables.map((t) => t.table));
+  const pendingRenameSources = new Set(
+    Object.entries(tableRenames)
+      .filter(([to, from]) => !currentNames.has(to) && currentNames.has(from))
+      .map(([, from]) => from),
+  );
+  const scopedCurrent: SchemaSnapshot = opts.scope === 'full'
+    ? { tables: current.tables, enums: current.enums ?? [] }
+    : {
+        tables: current.tables.filter((t) => declaredTables.has(t.table) || pendingRenameSources.has(t.table)),
+        enums: (current.enums ?? []).filter((e) => declaredEnums.has(e.name)),
+      };
   const renames = compileRenames(models, { schema });
-  const changes = diffSchema(desired, scopedCurrent, renames);
+  const changes = diffSchema(desired, scopedCurrent, renames, tableRenames);
 
   const modelByTable = new Map(models.map((m) => [`${schemaOf(m)}.${m.table}`, m]));
   const emitted = emitSchemaSql(changes, {
@@ -130,8 +160,21 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
   // data DDL just created. Emitted only when the live contract is supplied; the Models'
   // `abilities` compile to the same contract shape introspection reads, so the two diff.
   // Authz changes are data-safe (no row touches), so they are never held by `allowDrops`.
-  const authzPhase = opts.liveAuthz
-    ? emitReconcileSql({ tables: models.map((m) => compileTableContract(m, { schema })), functions: [] }, opts.liveAuthz)
+  const pendingByFrom = new Map(
+    Object.entries(tableRenames)
+      .filter(([, from]) => pendingRenameSources.has(from))
+      .map(([to, from]) => [from, to] as const),
+  );
+  const liveAuthzRenamed = opts.liveAuthz && pendingByFrom.size > 0
+    ? {
+        ...opts.liveAuthz,
+        tables: opts.liveAuthz.tables.map((t) =>
+          pendingByFrom.has(t.table) ? { ...t, table: pendingByFrom.get(t.table)! } : t,
+        ),
+      }
+    : opts.liveAuthz;
+  const authzPhase = liveAuthzRenamed
+    ? emitReconcileSql({ tables: models.map((m) => compileTableContract(m, { schema })), functions: [] }, liveAuthzRenamed)
     : [];
 
   return [...dataPhase, ...authzPhase];

package/src/cli/schema-compile.ts

@@ -526,3 +526,20 @@ export function compileRenames(models: ModelDescriptor[], opts: { schema?: strin
   }
   return map;
 }
+
+/**
+ * Table-level rename intent: qualified new name → qualified old name (same
+ * schema — a rename never moves schemas). Produced off the Models'
+ * `renamedFrom` option, consumed by `diffSchema`'s pre-pass, which turns a
+ * create+drop into one `ALTER TABLE … RENAME TO …`.
+ */
+export function compileTableRenames(models: ModelDescriptor[], opts: { schema?: string } = {}): Record<string, string> {
+  const map: Record<string, string> = {};
+  for (const model of models) {
+    if (!model.renamedFrom) continue;
+    const schema = model.schema ?? opts.schema ?? 'public';
+    // Table names are literal Postgres names (like `model.table` itself) — no case mapping.
+    map[`${schema}.${model.table}`] = `${schema}.${model.renamedFrom}`;
+  }
+  return map;
+}

package/src/cli/schema-diff.ts

@@ -65,6 +65,12 @@ export type SchemaChange =
   | { kind: 'renameSourceMissing'; table: string; column: string; from: string }
   /** An unmarked drop+add that *might* be a rename — a hint comment, the SQL still drops+adds. */
   | { kind: 'renameHint'; table: string; from: string; to: string }
+  /** A table-level `renamedFrom` satisfied: old table present, new absent → one RENAME, data preserved. */
+  | { kind: 'renameTable'; from: string; to: string }
+  /** A table marker whose rename is already applied (new name present) — inert, a notice. */
+  | { kind: 'renameTableSatisfied'; table: string; from: string }
+  /** A table marker pointing at a table the database doesn't have — fell back to CREATE, a notice. */
+  | { kind: 'renameTableSourceMissing'; table: string; from: string }
   /** A new enum type → `CREATE TYPE … AS ENUM (…)`, emitted before the tables that use it. */
   | { kind: 'createType'; name: string; values: string[] }
   /** A value appended to an existing enum → `ALTER TYPE … ADD VALUE` (carries a -- WARNING). */
@@ -86,6 +92,14 @@ export type SchemaChange =
  */
 export type RenameMap = Record<string, Record<string, string>>;
 
+/**
+ * Table-level rename intent: qualified new name → qualified old name. Produced
+ * by `compileTableRenames` off the Models' `renamedFrom` option; consumed by
+ * `diffSchema`'s pre-pass, which rewrites the current snapshot (old table seen
+ * as the new name) so every downstream diff lands on the renamed table.
+ */
+export type TableRenameMap = Record<string, string>;
+
 // ---------------------------------------------------------------------------
 // Normalization — so semantically-equal expressions don't read as drift.
 // ---------------------------------------------------------------------------
@@ -232,8 +246,9 @@ export function normalizeCheck(expr: string): string {
  * replaced constraint never clashes with its old self and a column is never dropped out
  * from under a constraint that still references it.
  */
-export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, renames: RenameMap = {}): SchemaChange[] {
+export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, renames: RenameMap = {}, tableRenames: TableRenameMap = {}): SchemaChange[] {
   const creates: SchemaChange[] = [];
+  const renameTables: SchemaChange[] = [];
   const renameColumns: SchemaChange[] = [];
   const addColumns: SchemaChange[] = [];
   const alters: SchemaChange[] = [];
@@ -248,6 +263,28 @@ export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, ren
   const currentByName = new Map(current.tables.map((t) => [t.table, t]));
   const desiredNames = new Set(desired.tables.map((t) => t.table));
 
+  // Table-rename pre-pass: honor the Models' table-level `renamedFrom` before
+  // any matching. A satisfied rename rewrites the current snapshot — the old
+  // table is seen under its new name — so every downstream diff (columns,
+  // constraints, indexes, drops) lands on the renamed table, and the old name
+  // never reaches the dropTables sweep. Mirrors the column-rename semantics:
+  // new-name-present → inert notice; source missing → CREATE path + notice.
+  for (const [to, from] of Object.entries(tableRenames)) {
+    if (!desiredNames.has(to)) continue; // the marker's model isn't in this diff
+    if (currentByName.has(to)) {
+      notices.push({ kind: 'renameTableSatisfied', table: to, from });
+      continue;
+    }
+    const source = currentByName.get(from);
+    if (!source) {
+      notices.push({ kind: 'renameTableSourceMissing', table: to, from });
+      continue;
+    }
+    renameTables.push({ kind: 'renameTable', from, to });
+    currentByName.delete(from);
+    currentByName.set(to, { ...source, table: to });
+  }
+
   for (const d of desired.tables) {
     const c = currentByName.get(d.table);
     if (!c) {
@@ -274,18 +311,21 @@ export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, ren
     diffIndexes(d, c, createIndexes, dropIndexes);
   }
 
-  for (const c of current.tables) {
+  // Sweep the POST-RENAME view: a renamed-away old name is not a drop.
+  for (const c of currentByName.values()) {
     if (!desiredNames.has(c.table)) dropTables.push({ kind: 'dropTable', table: c.table });
   }
 
   const e = diffEnums(desired.enums ?? [], current.enums ?? []);
 
   // Enum types come first (a table or column may reference one); value adds before the
-  // columns that use them. Renames run before adds (a rename frees a name an add may
-  // reuse) and before alters (which target the new name). Enum drops sit with the other
-  // removals; notices are comments — emitted last, after the DDL.
+  // columns that use them. Table renames run before creates (a rename frees a name a
+  // create may reuse) and before every per-table change (which all target the new name).
+  // Column renames run before adds and alters for the same reason. Enum drops sit with
+  // the other removals; notices are comments — emitted last, after the DDL.
   return [
     ...e.creates, ...e.adds,
+    ...renameTables,
     ...creates, ...renameColumns, ...addColumns, ...alters,
     ...dropConstraints, ...addConstraints, ...createIndexes,
     ...dropColumns, ...dropIndexes, ...dropTables,
@@ -613,6 +653,13 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string {
       return `-- NOTICE: primary key on ${change.table} changed (${change.from.join(', ')} → ${change.to.join(', ')}); dropping a primary key needs its constraint name — regenerate this change manually.`;
     case 'renameColumn':
       return `ALTER TABLE ${change.table} RENAME COLUMN ${quote(change.from)} TO ${quote(change.to)};`;
+    case 'renameTable':
+      // RENAME TO takes a bare name — the table stays in its schema.
+      return `ALTER TABLE ${change.from} RENAME TO ${quote(change.to.split('.').pop()!)};`;
+    case 'renameTableSatisfied':
+      return `-- NOTICE: the renamedFrom marker on table ${change.table} is satisfied — the rename from "${change.from}" is applied, the marker is now inert and can be removed.`;
+    case 'renameTableSourceMissing':
+      return `-- NOTICE: table ${change.table} declares renamedFrom "${change.from}", but the database has neither — created fresh; remove the marker once every environment is past it.`;
     case 'renameSatisfied':
       return `-- NOTICE: the renamedFrom marker on column ${quote(change.column)} (${change.table}) is satisfied — the rename from "${change.from}" is applied, the marker is now inert and can be removed.`;
     case 'renameSourceMissing':