@everystack/cli 0.3.19 → 0.3.21

package/README.md

@@ -220,6 +220,7 @@ 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
 
 # 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.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-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/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

@@ -15,6 +15,8 @@ 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';
@@ -188,6 +190,12 @@ async function main() {
     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;
@@ -314,6 +322,8 @@ Usage:
   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';
@@ -82,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();
 }
 
@@ -106,14 +111,26 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
   // (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)),
+        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, {
@@ -143,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':