@everystack/cli 0.3.19 → 0.3.22

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

@@ -212,7 +212,7 @@ export function syncFailed(run: SyncRun): boolean {
 // The CLI shell.
 // ---------------------------------------------------------------------------
 
-async function readSqlDirIfPresent(dir: string): Promise<SourceFile[] | null> {
+export async function readSqlDirIfPresent(dir: string): Promise<SourceFile[] | null> {
   let entries: string[];
   try {
     entries = await fs.readdir(dir);

package/src/cli/edge-plan.ts

@@ -0,0 +1,195 @@
+/**
+ * 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;
+}
+
+/**
+ * The predicted live fingerprint of a target AFTER the models' edge lands:
+ * declared tables on their compiled shapes exactly (that is what
+ * apply-and-verify proves), unmodeled tables and enums riding 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.
+ *
+ * Two callers, one meaning: minting uses it as a plan's `to` endpoint, and
+ * git-descent uses it as the declares-test — a commit DECLARES a target's
+ * live state exactly when this prediction equals the live fingerprint
+ * (the edge from the target to that commit's models is empty).
+ */
+export function predictLiveFingerprint(
+  models: ModelDescriptor[],
+  snapshot: SchemaSnapshot,
+  contract: AuthzContract,
+  opts: { schema?: string } = {},
+): string {
+  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 fingerprintState(mergedSnapshot, mergedAuthz).hash;
+}
+
+/**
+ * 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.',
+    );
+  }
+
+  return {
+    v: PLAN_VERSION,
+    fromFingerprint: fingerprintLive(snapshot, contract).hash,
+    toFingerprint: predictLiveFingerprint(models, snapshot, contract, { schema: opts.schema }),
+    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/git-descent.ts

@@ -0,0 +1,251 @@
+/**
+ * git-descent — a protected database is a git ref (brick 7 of the
+ * migration-authority design).
+ *
+ * The rule git already taught everyone: `db:apply` is a fast-forward push.
+ * The target's live fingerprint maps to the git commit whose committed
+ * models DECLARE that state; the deploying checkout must be a descendant
+ * of such a commit, or the apply refuses — "rebase first". This is what
+ * stops the multi-dev disaster case: A merges and deploys, B (branched
+ * before A merged) mints against the target — the concurrency lock passes,
+ * because B's plan was minted against current reality, but B's edge would
+ * REVERT A's merged work. The descent check catches exactly that: the
+ * commit declaring the target's state is not in B's history.
+ *
+ * The search runs over GIT ALONE, never `schema_log` (the ledger is a
+ * memoir, not a control surface — design decision 7): enumerate every
+ * historical state of the models directory across all refs, compile each
+ * unique tree, and ask whether its predicted live endpoint equals the
+ * target's live fingerprint (brick 4's merged prediction, so unmodeled
+ * brownfield tables ride through the test). A fingerprint no commit
+ * declares is a DRIFT report and an explicit operator decision — never a
+ * guess. Identity is the models-directory TREE, not the commit: a
+ * cherry-picked identical state is the same declared state.
+ */
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { ModelDescriptor } from '@everystack/model';
+import type { SchemaSnapshot } from './schema-introspect.js';
+import type { AuthzContract } from './authz-contract.js';
+import { fingerprintLive } from './schema-fingerprint.js';
+import { predictLiveFingerprint } from './edge-plan.js';
+
+/** Compile a models barrel on disk. The default rides the CLI's runtime (tsx). */
+export type ModelsLoader = (barrel: string) => Promise<ModelDescriptor[]>;
+
+export interface LiveState {
+  snapshot: SchemaSnapshot;
+  contract: AuthzContract;
+}
+
+export interface DescentOptions {
+  /** Where git commands run. Default: process.cwd(). */
+  cwd?: string;
+  /** The Postgres schema the Models default to. Default: `public`. */
+  schema?: string;
+  loader?: ModelsLoader;
+  /**
+   * Where historical trees materialize. Default: a fresh temp dir under the
+   * repo's node_modules — bare imports (`@everystack/model`) must resolve
+   * from the materialized files, and node walks parent directories.
+   */
+  materializeRoot?: string;
+  /** The ref that must descend from the declaring commit. Default: HEAD. */
+  headRef?: string;
+}
+
+export type DescentVerdict =
+  /** Not a git checkout (or no commits yet) — the rule cannot be verified here. */
+  | { status: 'no-git' }
+  /** The target has no tables — nothing to protect, first apply bootstraps it. */
+  | { status: 'fresh-target' }
+  /** Fast-forward: `commit` declares the target's live state and is an ancestor of HEAD. */
+  | { status: 'ok'; commit: string; tree: string; scannedTrees: number }
+  /** The declaring commits exist but none is an ancestor of HEAD — rebase first. */
+  | { status: 'diverged'; commits: string[]; tree: string; reason: string }
+  /** No committed models state declares the live fingerprint — operator decision. */
+  | { status: 'drift'; scannedTrees: number; compileFailures: string[]; reason: string };
+
+export interface ModelTreeCandidate {
+  /** The models directory's tree oid — the identity of a declared state. */
+  tree: string;
+  /** Every enumerated commit carrying that tree, newest first. */
+  commits: string[];
+}
+
+const short = (ref: string): string => ref.slice(0, 12);
+
+function git(args: string[], cwd: string): string | null {
+  try {
+    return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+  } catch {
+    return null;
+  }
+}
+
+const defaultLoader: ModelsLoader = async (barrel) => {
+  const mod: any = await import(pathToFileURL(path.resolve(barrel)).href);
+  const models = mod.models ?? mod.default;
+  if (!Array.isArray(models)) throw new Error(`${barrel} does not export a \`models\` array`);
+  return models;
+};
+
+/**
+ * Every historical state of the models directory across ALL refs, newest
+ * first, grouped by tree oid. `--full-history` keeps every !TREESAME commit
+ * (no simplification dropping a state introduced on a side branch); one
+ * `cat-file --batch-check` resolves all `<sha>:<dir>` specs in a single
+ * child process, in input order.
+ */
+export function enumerateModelTrees(modelsDir: string, cwd: string): ModelTreeCandidate[] {
+  const out = git(['rev-list', '--all', '--full-history', '--date-order', '--', modelsDir], cwd);
+  if (out === null) return [];
+  const shas = out.trim().split('\n').filter(Boolean);
+  if (shas.length === 0) return [];
+
+  const specs = shas.map((sha) => (modelsDir === '.' ? `${sha}^{tree}` : `${sha}:${modelsDir}`));
+  let batch: string;
+  try {
+    batch = execFileSync('git', ['cat-file', '--batch-check'], {
+      cwd,
+      input: specs.join('\n') + '\n',
+      stdio: ['pipe', 'pipe', 'ignore'],
+    }).toString();
+  } catch {
+    return [];
+  }
+
+  const byTree = new Map<string, string[]>();
+  const order: string[] = [];
+  batch.trim().split('\n').forEach((line, i) => {
+    const m = line.trim().match(/^([0-9a-f]{40,64}) tree /);
+    if (!m) return; // the directory is absent at that commit, or not a tree
+    if (!byTree.has(m[1])) {
+      byTree.set(m[1], []);
+      order.push(m[1]);
+    }
+    byTree.get(m[1])!.push(shas[i]);
+  });
+  return order.map((tree) => ({ tree, commits: byTree.get(tree)! }));
+}
+
+/** Extract a tree into `dest` — `git archive` piped to tar, no shell. */
+export function materializeTree(tree: string, dest: string, cwd: string): void {
+  fs.mkdirSync(dest, { recursive: true });
+  const archive = execFileSync('git', ['archive', '--format=tar', tree], {
+    cwd,
+    maxBuffer: 512 * 1024 * 1024,
+  });
+  execFileSync('tar', ['-xf', '-', '-C', dest], { input: archive });
+}
+
+/**
+ * The fast-forward rule. Given the target's live state (already
+ * introspected — the apply path has it in hand), find the commit whose
+ * committed models declare that state and verify the checkout descends
+ * from it. Any declaring ancestor satisfies the rule; `diverged` is
+ * reported only when NO tree declaring the state has one.
+ */
+export async function verifyDescent(
+  modelsPath: string,
+  live: LiveState,
+  opts: DescentOptions = {},
+): Promise<DescentVerdict> {
+  if (live.snapshot.tables.length === 0) return { status: 'fresh-target' };
+
+  const cwd = opts.cwd ?? process.cwd();
+  const rootOut = git(['rev-parse', '--show-toplevel'], cwd);
+  if (rootOut === null) return { status: 'no-git' };
+  const repoRoot = rootOut.trim();
+  const headOut = git(['rev-parse', opts.headRef ?? 'HEAD'], cwd);
+  if (headOut === null) return { status: 'no-git' };
+  const head = headOut.trim();
+
+  // realpath the cwd side: `--show-toplevel` resolves symlinks (macOS tmpdir
+  // is /var → /private/var), and a mismatched prefix would walk the models
+  // path right out of the repo.
+  const modelsAbs = path.resolve(fs.realpathSync(cwd), modelsPath);
+  const rel = path.relative(repoRoot, modelsAbs);
+  const modelsDir = path.dirname(rel) || '.';
+  const barrel = path.basename(modelsAbs);
+
+  const candidates = enumerateModelTrees(modelsDir, repoRoot);
+  const liveFingerprint = fingerprintLive(live.snapshot, live.contract).hash;
+
+  const nodeModules = path.join(repoRoot, 'node_modules');
+  const materializeRoot = opts.materializeRoot
+    ?? fs.mkdtempSync(path.join(fs.existsSync(nodeModules) ? nodeModules : os.tmpdir(), '.everystack-descent-'));
+  const ownsRoot = !opts.materializeRoot;
+  const loader = opts.loader ?? defaultLoader;
+
+  const compileFailures: string[] = [];
+  const declaringButDiverged: ModelTreeCandidate[] = [];
+  try {
+    for (const candidate of candidates) {
+      const dest = path.join(materializeRoot, candidate.tree);
+      let predicted: string;
+      try {
+        if (!fs.existsSync(dest)) materializeTree(candidate.tree, dest, repoRoot);
+        const models = await loader(path.join(dest, barrel));
+        predicted = predictLiveFingerprint(models, live.snapshot, live.contract, { schema: opts.schema });
+      } catch (err: any) {
+        compileFailures.push(`${short(candidate.tree)} (at ${short(candidate.commits[0])}): ${err.message}`);
+        continue;
+      }
+      if (predicted !== liveFingerprint) continue;
+
+      for (const commit of candidate.commits) {
+        try {
+          execFileSync('git', ['merge-base', '--is-ancestor', commit, head], {
+            cwd: repoRoot,
+            stdio: 'ignore',
+          });
+          return {
+            status: 'ok',
+            commit,
+            tree: candidate.tree,
+            scannedTrees: candidates.indexOf(candidate) + 1,
+          };
+        } catch {
+          // not an ancestor — keep looking; an identical tree elsewhere may be
+        }
+      }
+      declaringButDiverged.push(candidate);
+    }
+  } finally {
+    if (ownsRoot) fs.rmSync(materializeRoot, { recursive: true, force: true });
+  }
+
+  if (declaringButDiverged.length > 0) {
+    const commits = declaringButDiverged.flatMap((c) => c.commits);
+    return {
+      status: 'diverged',
+      commits,
+      tree: declaringButDiverged[0].tree,
+      reason:
+        `the target's state is declared by ${short(commits[0])}` +
+        (commits.length > 1 ? ` (+${commits.length - 1} more)` : '') +
+        ', which is NOT an ancestor of your checkout — your branch diverged before it. ' +
+        'Rebase onto it and re-mint, so your edge moves the target forward instead of reverting merged work.',
+    };
+  }
+
+  const failureNote = compileFailures.length > 0
+    ? ` (${compileFailures.length} historical tree(s) no longer compile and were skipped)`
+    : '';
+  return {
+    status: 'drift',
+    scannedTrees: candidates.length,
+    compileFailures,
+    reason:
+      `no committed models state declares the target's live fingerprint ${short(liveFingerprint)} — ` +
+      `scanned ${candidates.length} historical tree(s) across all refs${failureNote}. ` +
+      'Either the database was hand-edited (drift) or the declaring history was rewritten. ' +
+      'Align the models with the live database first (db:pull, commit), ' +
+      'or force with ceremony: --force-descent <snapshot-ref> --confirm.',
+  };
+}

package/src/cli/index.ts

@@ -15,6 +15,9 @@ 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 { dbCheckCommand } from './commands/db-check.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 +191,15 @@ 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:check':
+      await dbCheckCommand(flags);
+      break;
     case 'db:authz:pull':
       await dbAuthzPullCommand(flags);
       break;
@@ -314,6 +326,9 @@ 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>] [--models <barrel>] [--force-descent <snapshot-ref> --confirm]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule, else refuse — "rebase first"; force needs the snapshot you took + --confirm), 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:check          [--models <barrel>] [--sql-dir db/sql] [--schema-out <file.ts>] [--database-url <url>] [--json]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, db/sql parses) and generated artifacts must MATCH regeneration byte-for-byte; with a scratch PostgreSQL it builds the state from scratch on an ephemeral database (created + dropped) and requires fingerprint MATCH. Exit 1 on any failure; never touches a real target
   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;
+}