@everystack/cli 0.2.39 → 0.3.0

package/src/cli/schema-diff.ts

@@ -0,0 +1,605 @@
+/**
+ * The structural schema diff — the data layer's reconcile.
+ *
+ * The counterpart to authz-reconcile's `emitReconcileSql`: that transforms the live
+ * database's RLS/grants/policies into the declared authz; this transforms the live
+ * *structure* (columns, constraints) into the declared schema. Both diff one IR —
+ * `diffSchema` works on the `TableSchema` shape both producers target (the compiled
+ * Model and whole-DB introspection), so it never needs the Model or the database.
+ *
+ * It is the brownfield generalization of `compileMigration`: greenfield emits "vs an
+ * empty database"; this emits "vs whatever the database currently is". The two stages
+ * mirror authz too — `diffSchema` produces a structured change set (the analog of the
+ * reconcile findings), `emitSchemaSql` turns it into `ALTER TABLE` DDL.
+ *
+ * Deliberately scoped, with clear seams for the follow-ups:
+ *   - A column gone from desired and a new one appearing are an independent drop + add.
+ *     RENAME is intent that cannot be recovered from two snapshots, so it is opt-in via
+ *     a `renamedFrom` marker on the Model (a later increment) — never guessed here.
+ *   - A type change emits a real `ALTER COLUMN ... TYPE`, classified safe/lossy/risky: a
+ *     safe widening is a bare conversion; a lossy or risky one gets an explicit `USING`
+ *     cast and a `-- WARNING` (it can truncate, or fail on rows that don't convert). The
+ *     classifier defaults to risky, so it never silently under-warns.
+ *   - Defaults compare *semantically* (`normalizeDefault`) so a deparser cast
+ *     (`'draft'` vs `'draft'::text`) never produces spurious churn.
+ */
+
+import type {
+  SchemaSnapshot,
+  TableSchema,
+  ColumnSchema,
+  EnumType,
+  IndexSchema,
+} from './schema-introspect.js';
+
+// ---------------------------------------------------------------------------
+// The change set.
+// ---------------------------------------------------------------------------
+
+/** A constraint to add, in the form the emitter renders `ADD CONSTRAINT` from. */
+export type ConstraintSpec =
+  | { type: 'unique'; name: string; columns: string[] }
+  | { type: 'check'; name: string; expr: string }
+  | { type: 'foreignKey'; name: string; columns: string[]; refTable: string; refColumns: string[]; onDelete?: string; onUpdate?: string };
+
+export type SchemaChange =
+  | { kind: 'createTable'; table: string; schema: TableSchema }
+  | { kind: 'dropTable'; table: string }
+  | { kind: 'addColumn'; table: string; column: ColumnSchema }
+  | { kind: 'dropColumn'; table: string; column: string }
+  | { kind: 'setNotNull'; table: string; column: string; notNull: boolean }
+  /** `expr: null` means DROP DEFAULT. */
+  | { kind: 'setDefault'; table: string; column: string; expr: string | null }
+  /** A type change → real `ALTER COLUMN ... TYPE`. `risk` decides USING + a data-loss warning. */
+  | { kind: 'alterType'; table: string; column: string; from: string; to: string; risk: TypeChangeRisk }
+  | { kind: 'addConstraint'; table: string; constraint: ConstraintSpec }
+  | { kind: 'dropConstraint'; table: string; name: string }
+  | { kind: 'addPrimaryKey'; table: string; columns: string[] }
+  /** A PK change other than first-time add — a notice (the drop needs its constraint name). */
+  | { kind: 'primaryKeyChange'; table: string; from: string[]; to: string[] }
+  /** A `renamedFrom` marker satisfied: old column present, new absent → preserve the data. */
+  | { kind: 'renameColumn'; table: string; from: string; to: string }
+  /** A marker whose rename is already applied (new name present) — inert, a notice. */
+  | { kind: 'renameSatisfied'; table: string; column: string; from: string }
+  /** A marker pointing at a column the database doesn't have — fell back to ADD, a notice. */
+  | { 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 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). */
+  | { kind: 'addEnumValue'; type: string; value: string }
+  /** An enum type present in the DB but no longer declared → `DROP TYPE` (a removal — gated like drops). */
+  | { kind: 'dropType'; name: string }
+  /** An enum value the DB has but the Model dropped/renamed — Postgres can't drop one in place (a notice). */
+  | { kind: 'enumValuesChanged'; name: string; from: string[]; to: string[] }
+  /** A standalone index to create → `CREATE [UNIQUE] INDEX … [WHERE …]`. */
+  | { kind: 'createIndex'; table: string; name: string; columns: string[]; unique: boolean; where?: string }
+  /** A standalone index present in the DB but no longer declared → `DROP INDEX` (a removal — gated). */
+  | { kind: 'dropIndex'; table: string; name: string };
+
+/**
+ * Rename intent, keyed like the snapshot's tables (`public.posts`) → { newColumn: oldColumn }.
+ * Produced by `compileRenames` off the Models' `.renamedFrom()` markers. It rides *beside*
+ * the snapshots, never on a column: introspection can't produce it (the DB has no rename
+ * history), so keeping it off the IR preserves the round-trip both producers share.
+ */
+export type RenameMap = Record<string, Record<string, string>>;
+
+// ---------------------------------------------------------------------------
+// Normalization — so semantically-equal expressions don't read as drift.
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonicalize a column DEFAULT so the Model's form and the database's deparsed form
+ * compare equal. The Model emits `'draft'`; `pg_get_expr` gives `'draft'::text`. The
+ * Model emits `now()`; a `CURRENT_TIMESTAMP` default deparses to `now()`. We strip a
+ * trailing type cast and canonicalize the timestamp keyword — internal casts (inside a
+ * function call like `nextval('s'::regclass)`) are left alone.
+ */
+export function normalizeDefault(expr: string | null): string | null {
+  if (expr == null) return null;
+  let s = expr.trim();
+  if (s === '') return null;
+
+  // Strip a trailing `::type` cast (type may be quoted, multi-word, or array): the
+  // literal `'draft'::text` -> `'draft'`, `0::bigint` -> `0`, `'{}'::jsonb` -> `'{}'`.
+  let prev: string;
+  do {
+    prev = s;
+    s = s.replace(/::\s*"?[A-Za-z_][A-Za-z0-9_ ]*"?(\s*\([^)]*\))?(\s*\[\])?$/, '').trim();
+  } while (s !== prev);
+
+  if (/^current_timestamp$/i.test(s)) return 'now()';
+  return s;
+}
+
+// ---------------------------------------------------------------------------
+// Type-change classification — does the conversion need a USING cast and a warning?
+// ---------------------------------------------------------------------------
+
+/** safe: a lossless widening. lossy: an assignment cast that can truncate. risky: a cast that can fail at runtime. */
+export type TypeChangeRisk = 'safe' | 'lossy' | 'risky';
+
+/** Integer/numeric widening rank — a value at a lower rank always fits a higher one. */
+const NUMERIC_RANK: Record<string, number> = { smallint: 1, integer: 2, bigint: 3, numeric: 4 };
+
+/** Split a `format_type` string into its base and any precision/length args: `numeric(12,2)` -> {base:'numeric', args:[12,2]}. */
+function parseType(t: string): { base: string; args: number[] } {
+  const m = t.match(/^(.*?)\s*\(([^)]*)\)\s*$/);
+  if (!m) return { base: t.trim(), args: [] };
+  return { base: m[1].trim(), args: m[2].split(',').map((s) => parseInt(s.trim(), 10)).filter((n) => !Number.isNaN(n)) };
+}
+
+/** True when every target arg is >= the source's (or the target is unbounded) — a widening of precision/length. */
+function argsWiden(from: number[], to: number[]): boolean {
+  if (to.length === 0) return true; // unbounded target (e.g. numeric, varchar) holds anything
+  if (from.length === 0) return false; // bounding a previously-unbounded source narrows it
+  return to.every((v, i) => from[i] == null || v >= from[i]);
+}
+
+/**
+ * Classify a column type change. Conservative by construction — anything not provably safe
+ * or merely lossy falls through to `risky`, so a dangerous conversion is never mistaken for
+ * a free one. (The vocabulary is the field bridge's: text, the integer/numeric family,
+ * varchar, timestamp(/tz), uuid, boolean, jsonb.)
+ */
+export function classifyTypeChange(from: string, to: string): TypeChangeRisk {
+  const f = parseType(from);
+  const t = parseType(to);
+
+  if (t.base === 'text') return 'safe'; // text is the universal sink: every type assignment-casts to it losslessly
+
+  const fr = NUMERIC_RANK[f.base];
+  const tr = NUMERIC_RANK[t.base];
+  if (fr && tr) {
+    if (f.base === t.base) return argsWiden(f.args, t.args) ? 'safe' : 'lossy';
+    return tr > fr ? 'safe' : 'lossy'; // widen up the integer/numeric ranks is safe; down can overflow
+  }
+
+  if (f.base === t.base) return argsWiden(f.args, t.args) ? 'safe' : 'lossy'; // same base, only precision/length moved
+
+  const timestamps = new Set(['timestamp', 'timestamp with time zone', 'timestamp without time zone']);
+  if (timestamps.has(f.base) && timestamps.has(t.base)) return 'lossy'; // tz semantics shift
+
+  if (f.base === 'text' || f.base === 'character varying') return 'risky'; // parsing text into a scalar can fail per-row
+  if (t.base === 'character varying') return 'lossy'; // bounding into a length-limited string can truncate
+
+  return 'risky';
+}
+
+/** True when `s`'s outer parens already wrap the whole expression. */
+function isWrapped(s: string): boolean {
+  if (!s.startsWith('(') || !s.endsWith(')')) return false;
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === '(') depth++;
+    else if (s[i] === ')') {
+      depth--;
+      if (depth === 0 && i < s.length - 1) return false;
+    }
+  }
+  return depth === 0;
+}
+
+/** A predicate parenthesized exactly once (mirrors authz-reconcile's `clause`). */
+function wrapOnce(expr: string): string {
+  return isWrapped(expr) ? expr : `(${expr})`;
+}
+
+/**
+ * Canonicalize a CHECK predicate for comparison: drop one layer of wrapping parens and
+ * collapse whitespace. The Model emits `char_length(title) >= 1`; `pg_get_constraintdef`
+ * gives `(char_length(title) >= 1)`. Deeper deparser-faithful matching (the same concern
+ * type changes raise) is a follow-up — this kills the common paren/whitespace churn.
+ */
+export function normalizeCheck(expr: string): string {
+  let s = expr.trim();
+  while (isWrapped(s)) s = s.slice(1, -1).trim();
+  return s.replace(/\s+/g, ' ');
+}
+
+// ---------------------------------------------------------------------------
+// Diff.
+// ---------------------------------------------------------------------------
+
+/**
+ * Diff desired (compiled Model) against current (introspected DB) into an ordered,
+ * dependency-safe change set. The order each change is emitted in is the order it must
+ * be applied: new tables, then new columns, then column alters, then dropped
+ * constraints, then added constraints, then dropped columns, then dropped tables — so a
+ * 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[] {
+  const creates: SchemaChange[] = [];
+  const renameColumns: SchemaChange[] = [];
+  const addColumns: SchemaChange[] = [];
+  const alters: SchemaChange[] = [];
+  const dropConstraints: SchemaChange[] = [];
+  const addConstraints: SchemaChange[] = [];
+  const createIndexes: SchemaChange[] = [];
+  const dropIndexes: SchemaChange[] = [];
+  const dropColumns: SchemaChange[] = [];
+  const dropTables: SchemaChange[] = [];
+  const notices: SchemaChange[] = [];
+
+  const currentByName = new Map(current.tables.map((t) => [t.table, t]));
+  const desiredNames = new Set(desired.tables.map((t) => t.table));
+
+  for (const d of desired.tables) {
+    const c = currentByName.get(d.table);
+    if (!c) {
+      // Whole new table: CREATE TABLE (PK/unique/check inline), then its FKs as
+      // separate adds so every table exists before any FK references it.
+      creates.push({ kind: 'createTable', table: d.table, schema: d });
+      for (const fk of d.foreignKeys) {
+        addConstraints.push({
+          kind: 'addConstraint',
+          table: d.table,
+          constraint: { type: 'foreignKey', name: fk.name, columns: fk.columns, refTable: fk.refTable, refColumns: fk.refColumns, onDelete: fk.onDelete, onUpdate: fk.onUpdate },
+        });
+      }
+      for (const ix of d.indexes) createIndexes.push(createIndexChange(d.table, ix));
+      continue;
+    }
+    const cd = diffColumns(d, c, renames[d.table] ?? {});
+    renameColumns.push(...cd.renameColumns);
+    addColumns.push(...cd.addColumns);
+    alters.push(...cd.alters);
+    dropColumns.push(...cd.dropColumns);
+    notices.push(...cd.notices);
+    diffConstraints(d, c, dropConstraints, addConstraints, alters);
+    diffIndexes(d, c, createIndexes, dropIndexes);
+  }
+
+  for (const c of current.tables) {
+    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.
+  return [
+    ...e.creates, ...e.adds,
+    ...creates, ...renameColumns, ...addColumns, ...alters,
+    ...dropConstraints, ...addConstraints, ...createIndexes,
+    ...dropColumns, ...dropIndexes, ...dropTables,
+    ...e.drops, ...notices, ...e.notices,
+  ];
+}
+
+/** A `createIndex` change from an index spec (the new-table path and the per-table diff share it). */
+function createIndexChange(table: string, ix: IndexSchema): SchemaChange {
+  return { kind: 'createIndex', table, name: ix.name, columns: ix.columns, unique: ix.unique, ...(ix.where ? { where: ix.where } : {}) };
+}
+
+/** An index's content identity — columns, uniqueness, and partial predicate, name-independent (like checks). */
+function indexKey(ix: IndexSchema): string {
+  return `${ix.unique ? 'u' : ''}|${ix.columns.join(',')}|${normalizeCheck(ix.where ?? '')}`;
+}
+
+/**
+ * Diff standalone indexes by content, not name: an index with the same columns, uniqueness, and
+ * partial predicate is the same index whatever it's called, so a pulled index (whose DB name we
+ * didn't choose) re-generates clean. A dropped index is a removal, gated like the others.
+ */
+function diffIndexes(d: TableSchema, c: TableSchema, creates: SchemaChange[], drops: SchemaChange[]): void {
+  const desiredByKey = new Map(d.indexes.map((ix) => [indexKey(ix), ix]));
+  const currentByKey = new Map(c.indexes.map((ix) => [indexKey(ix), ix]));
+  for (const [k, ix] of currentByKey) {
+    if (!desiredByKey.has(k)) drops.push({ kind: 'dropIndex', table: d.table, name: ix.name });
+  }
+  for (const [k, ix] of desiredByKey) {
+    if (!currentByKey.has(k)) creates.push(createIndexChange(d.table, ix));
+  }
+}
+
+interface EnumDiff {
+  creates: SchemaChange[];
+  adds: SchemaChange[];
+  drops: SchemaChange[];
+  notices: SchemaChange[];
+}
+
+/**
+ * Diff declared enum types against introspected ones. A new type is a `CREATE TYPE`; a
+ * value appended to the END of an existing type is an `ALTER TYPE ADD VALUE` (Postgres
+ * can only append, and only one at a time — so each is its own change, warned at emit). A
+ * type the database has but no model declares is a `dropType` (gated like other removals).
+ * Any other value-set change — a removed value, a reorder, a rename — Postgres cannot do in
+ * place; it is surfaced as a notice, never a silent or destructive guess.
+ */
+function diffEnums(desired: EnumType[], current: EnumType[]): EnumDiff {
+  const out: EnumDiff = { creates: [], adds: [], drops: [], notices: [] };
+  const currentByName = new Map(current.map((e) => [e.name, e]));
+  const desiredNames = new Set(desired.map((e) => e.name));
+
+  for (const d of desired) {
+    const c = currentByName.get(d.name);
+    if (!c) {
+      out.creates.push({ kind: 'createType', name: d.name, values: d.values });
+      continue;
+    }
+    if (d.values.join(',') === c.values.join(',')) continue;
+    // Pure append? current must be a prefix of desired — then each extra value is ADD VALUE.
+    const isAppend = d.values.length > c.values.length && c.values.every((v, i) => d.values[i] === v);
+    if (isAppend) {
+      for (const value of d.values.slice(c.values.length)) out.adds.push({ kind: 'addEnumValue', type: d.name, value });
+    } else {
+      out.notices.push({ kind: 'enumValuesChanged', name: d.name, from: c.values, to: d.values });
+    }
+  }
+
+  for (const c of current) {
+    if (!desiredNames.has(c.name)) out.drops.push({ kind: 'dropType', name: c.name });
+  }
+
+  return out;
+}
+
+interface ColumnDiff {
+  renameColumns: SchemaChange[];
+  addColumns: SchemaChange[];
+  alters: SchemaChange[];
+  dropColumns: SchemaChange[];
+  notices: SchemaChange[];
+}
+
+/** Column-level type/nullability/default changes between a renamed-or-matched column and its source. */
+function columnAlters(table: string, desired: ColumnSchema, source: ColumnSchema, into: SchemaChange[]): void {
+  if (desired.type !== source.type) into.push({ kind: 'alterType', table, column: desired.name, from: source.type, to: desired.type, risk: classifyTypeChange(source.type, desired.type) });
+  if (desired.notNull !== source.notNull) into.push({ kind: 'setNotNull', table, column: desired.name, notNull: desired.notNull });
+  if (normalizeDefault(desired.default) !== normalizeDefault(source.default)) into.push({ kind: 'setDefault', table, column: desired.name, expr: desired.default });
+}
+
+function diffColumns(d: TableSchema, c: TableSchema, tableRenames: Record<string, string>): ColumnDiff {
+  const out: ColumnDiff = { renameColumns: [], addColumns: [], alters: [], dropColumns: [], notices: [] };
+  const currentByName = new Map(c.columns.map((col) => [col.name, col]));
+  const desiredNames = new Set(d.columns.map((col) => col.name));
+  const consumedByRename = new Set<string>(); // current columns claimed by a rename (so not dropped)
+
+  for (const col of d.columns) {
+    const cur = currentByName.get(col.name);
+    const oldName = tableRenames[col.name]; // a `.renamedFrom()` marker on this field, if any
+
+    if (cur) {
+      // New name already present. A marker here means the rename is already applied → inert.
+      if (oldName) out.notices.push({ kind: 'renameSatisfied', table: d.table, column: col.name, from: oldName });
+      columnAlters(d.table, col, cur, out.alters);
+      continue;
+    }
+
+    // New name absent: an add, or a rename of an existing column.
+    const source = oldName ? currentByName.get(oldName) : undefined;
+    if (oldName && source) {
+      out.renameColumns.push({ kind: 'renameColumn', table: d.table, from: oldName, to: col.name });
+      consumedByRename.add(oldName);
+      columnAlters(d.table, col, source, out.alters); // a rename may also change type/default/nullability
+    } else if (oldName) {
+      // Marker points at a column the database doesn't have — fall back to an honest add.
+      out.addColumns.push({ kind: 'addColumn', table: d.table, column: col });
+      out.notices.push({ kind: 'renameSourceMissing', table: d.table, column: col.name, from: oldName });
+    } else {
+      out.addColumns.push({ kind: 'addColumn', table: d.table, column: col });
+    }
+  }
+
+  for (const col of c.columns) {
+    if (!desiredNames.has(col.name) && !consumedByRename.has(col.name)) {
+      out.dropColumns.push({ kind: 'dropColumn', table: d.table, column: col.name });
+    }
+  }
+
+  // Unmarked-rename hint: with no marker involved on this table, a lone same-type drop+add
+  // *might* be a rename the author forgot to mark. Surface it as a comment — never act on it
+  // (that guess is exactly the data-corrupting heuristic the marker exists to avoid).
+  if (out.notices.length === 0 && out.addColumns.length === 1 && out.dropColumns.length === 1) {
+    const added = (out.addColumns[0] as { column: ColumnSchema }).column;
+    const dropped = currentByName.get((out.dropColumns[0] as { column: string }).column)!;
+    if (added.type === dropped.type) {
+      out.notices.push({ kind: 'renameHint', table: d.table, from: dropped.name, to: added.name });
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Name-keyed constraints whose names are content-derived and stable — uniques (named by
+ * their columns) and foreign keys. Checks are handled separately, matched by predicate, because
+ * a `check(...)` carries no author-given name and the database's name is arbitrary.
+ */
+function namedConstraints(t: TableSchema): Map<string, ConstraintSpec> {
+  const m = new Map<string, ConstraintSpec>();
+  for (const u of t.uniques) m.set(u.name, { type: 'unique', name: u.name, columns: u.columns });
+  for (const fk of t.foreignKeys) m.set(fk.name, { type: 'foreignKey', name: fk.name, columns: fk.columns, refTable: fk.refTable, refColumns: fk.refColumns, onDelete: fk.onDelete, onUpdate: fk.onUpdate });
+  return m;
+}
+
+/**
+ * Diff CHECK constraints by their normalized predicate, not their name: a check with the
+ * same predicate is the same check no matter what it's called, so a pulled check (whose DB
+ * name we didn't choose) re-generates clean. A changed predicate drops the old (by its real
+ * name) and adds the new.
+ */
+function diffChecks(d: TableSchema, c: TableSchema, dropConstraints: SchemaChange[], addConstraints: SchemaChange[]): void {
+  const desiredByPred = new Map(d.checks.map((ck) => [normalizeCheck(ck.expr), ck]));
+  const currentByPred = new Map(c.checks.map((ck) => [normalizeCheck(ck.expr), ck]));
+  for (const [pred, ck] of currentByPred) {
+    if (!desiredByPred.has(pred)) dropConstraints.push({ kind: 'dropConstraint', table: d.table, name: ck.name });
+  }
+  for (const [pred, ck] of desiredByPred) {
+    if (!currentByPred.has(pred)) addConstraints.push({ kind: 'addConstraint', table: d.table, constraint: { type: 'check', name: ck.name, expr: ck.expr } });
+  }
+}
+
+function constraintsEqual(a: ConstraintSpec, b: ConstraintSpec): boolean {
+  if (a.type !== b.type) return false;
+  if (a.type === 'unique' && b.type === 'unique') return a.columns.join(',') === b.columns.join(',');
+  if (a.type === 'check' && b.type === 'check') return normalizeCheck(a.expr) === normalizeCheck(b.expr);
+  if (a.type === 'foreignKey' && b.type === 'foreignKey') {
+    return a.columns.join(',') === b.columns.join(',')
+      && a.refTable === b.refTable
+      && a.refColumns.join(',') === b.refColumns.join(',')
+      && (a.onDelete ?? '') === (b.onDelete ?? '')
+      && (a.onUpdate ?? '') === (b.onUpdate ?? '');
+  }
+  return false;
+}
+
+function diffConstraints(d: TableSchema, c: TableSchema, dropConstraints: SchemaChange[], addConstraints: SchemaChange[], alters: SchemaChange[]): void {
+  const desired = namedConstraints(d);
+  const current = namedConstraints(c);
+
+  // Drop removed or changed constraints first (a changed one is dropped here, re-added below).
+  for (const [name, cur] of current) {
+    const des = desired.get(name);
+    if (!des || !constraintsEqual(des, cur)) dropConstraints.push({ kind: 'dropConstraint', table: d.table, name });
+  }
+  for (const [name, des] of desired) {
+    const cur = current.get(name);
+    if (!cur || !constraintsEqual(des, cur)) addConstraints.push({ kind: 'addConstraint', table: d.table, constraint: des });
+  }
+
+  diffChecks(d, c, dropConstraints, addConstraints);
+
+  // Primary key: a first-time add is safe; any other change needs the existing
+  // constraint's name to drop it (which the snapshot discards), so it is surfaced.
+  const dPk = d.primaryKey.join(',');
+  const cPk = c.primaryKey.join(',');
+  if (dPk !== cPk) {
+    if (c.primaryKey.length === 0) addConstraints.push({ kind: 'addPrimaryKey', table: d.table, columns: d.primaryKey });
+    else alters.push({ kind: 'primaryKeyChange', table: d.table, from: c.primaryKey, to: d.primaryKey });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Emit — change set to DDL.
+// ---------------------------------------------------------------------------
+
+const quote = (name: string): string => `"${name}"`;
+const colList = (cols: string[]): string => cols.map(quote).join(', ');
+/** A single-quoted enum value literal, doubling any embedded quote. */
+const enumLiteral = (value: string): string => `'${value.replace(/'/g, "''")}'`;
+
+/** A column definition body (no leading indent): `"name" type [DEFAULT expr] [NOT NULL]`. */
+function columnSql(col: ColumnSchema): string {
+  let s = `${quote(col.name)} ${col.type}`;
+  if (col.default != null) s += ` DEFAULT ${col.default}`;
+  if (col.notNull) s += ' NOT NULL';
+  return s;
+}
+
+/** `CREATE TABLE` from the IR: columns + PK/unique/check inline; FKs are emitted separately. */
+function createTableSql(t: TableSchema): string {
+  const lines = t.columns.map((c) => `\t${columnSql(c)}`);
+  if (t.primaryKey.length) lines.push(`\tPRIMARY KEY (${colList(t.primaryKey)})`);
+  for (const u of t.uniques) lines.push(`\tCONSTRAINT ${quote(u.name)} UNIQUE (${colList(u.columns)})`);
+  for (const ck of t.checks) lines.push(`\tCONSTRAINT ${quote(ck.name)} CHECK ${wrapOnce(ck.expr)}`);
+  return `CREATE TABLE ${t.table} (\n${lines.join(',\n')}\n);`;
+}
+
+function addConstraintSql(table: string, c: ConstraintSpec): string {
+  const head = `ALTER TABLE ${table} ADD CONSTRAINT ${quote(c.name)}`;
+  switch (c.type) {
+    case 'unique': return `${head} UNIQUE (${colList(c.columns)});`;
+    case 'check': return `${head} CHECK ${wrapOnce(c.expr)};`;
+    case 'foreignKey': {
+      let s = `${head} FOREIGN KEY (${colList(c.columns)}) REFERENCES ${quote(c.refTable)}(${colList(c.refColumns)})`;
+      if (c.onDelete) s += ` ON DELETE ${c.onDelete.toUpperCase()}`;
+      if (c.onUpdate) s += ` ON UPDATE ${c.onUpdate.toUpperCase()}`;
+      return `${s};`;
+    }
+  }
+}
+
+export interface EmitOptions {
+  /**
+   * Override how a whole-new-table `createTable` renders. `db:generate` passes the greenfield
+   * `compileCreateTable` (byte-identical to what the app ships) instead of the IR renderer.
+   */
+  createTable?: (change: Extract<SchemaChange, { kind: 'createTable' }>) => string;
+}
+
+/** Render one change to SQL — or a `-- NOTICE:` comment for the cases held for a follow-up. */
+function emitOne(change: SchemaChange, opts: EmitOptions): string {
+  switch (change.kind) {
+    case 'createTable':
+      return opts.createTable ? opts.createTable(change) : createTableSql(change.schema);
+    case 'dropTable':
+      return `DROP TABLE ${change.table};`;
+    case 'addColumn': {
+      const ddl = `ALTER TABLE ${change.table} ADD COLUMN ${columnSql(change.column)};`;
+      // Adding a NOT NULL column with no default fails on a table that already has rows.
+      if (change.column.notNull && change.column.default == null) {
+        return `-- WARNING: ADD COLUMN ${quote(change.column.name)} NOT NULL on ${change.table} has no default and FAILS if the table has rows; add a default or backfill first.\n${ddl}`;
+      }
+      return ddl;
+    }
+    case 'dropColumn':
+      return `ALTER TABLE ${change.table} DROP COLUMN ${quote(change.column)};`;
+    case 'setNotNull': {
+      const ddl = `ALTER TABLE ${change.table} ALTER COLUMN ${quote(change.column)} ${change.notNull ? 'SET NOT NULL' : 'DROP NOT NULL'};`;
+      // SET NOT NULL fails if any existing row holds a null in that column.
+      if (change.notNull) {
+        return `-- WARNING: SET NOT NULL on ${quote(change.column)} (${change.table}) FAILS if existing rows hold nulls; backfill the column first.\n${ddl}`;
+      }
+      return ddl;
+    }
+    case 'setDefault':
+      return change.expr == null
+        ? `ALTER TABLE ${change.table} ALTER COLUMN ${quote(change.column)} DROP DEFAULT;`
+        : `ALTER TABLE ${change.table} ALTER COLUMN ${quote(change.column)} SET DEFAULT ${change.expr};`;
+    case 'alterType': {
+      const setType = `ALTER TABLE ${change.table} ALTER COLUMN ${quote(change.column)} SET DATA TYPE ${change.to}`;
+      if (change.risk === 'safe') return `${setType};`;
+      const ddl = `${setType} USING ${quote(change.column)}::${change.to};`;
+      const warn = change.risk === 'lossy'
+        ? `-- WARNING: ${change.from} → ${change.to} on column ${quote(change.column)} (${change.table}) may truncate or lose data; review before running.`
+        : `-- WARNING: ${change.from} → ${change.to} on column ${quote(change.column)} (${change.table}) casts with USING and may FAIL on rows that don't convert; review before running.`;
+      return `${warn}\n${ddl}`;
+    }
+    case 'addConstraint':
+      return addConstraintSql(change.table, change.constraint);
+    case 'dropConstraint':
+      return `ALTER TABLE ${change.table} DROP CONSTRAINT IF EXISTS ${quote(change.name)};`;
+    case 'addPrimaryKey':
+      return `ALTER TABLE ${change.table} ADD PRIMARY KEY (${colList(change.columns)});`;
+    case 'primaryKeyChange':
+      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 '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':
+      return `-- NOTICE: a renamedFrom marker on column ${quote(change.column)} (${change.table}) points at column "${change.from}", which the database doesn't have; emitting ADD COLUMN instead — verify the marker.`;
+    case 'renameHint':
+      return `-- NOTICE: dropping ${quote(change.from)} and adding ${quote(change.to)} on ${change.table}; if this is a rename, replace those two with: ALTER TABLE ${change.table} RENAME COLUMN ${quote(change.from)} TO ${quote(change.to)};  (or mark the field .renamedFrom('${change.from}')).`;
+    case 'createType':
+      return `CREATE TYPE ${quote(change.name)} AS ENUM (${change.values.map(enumLiteral).join(', ')});`;
+    case 'addEnumValue':
+      return `-- WARNING: ADD VALUE to enum ${quote(change.type)} cannot run inside a transaction on PostgreSQL < 12, and the new value can't be used until the statement commits; apply it on its own.\nALTER TYPE ${quote(change.type)} ADD VALUE ${enumLiteral(change.value)};`;
+    case 'dropType':
+      return `DROP TYPE ${quote(change.name)};`;
+    case 'createIndex': {
+      const unique = change.unique ? 'UNIQUE ' : '';
+      const where = change.where ? ` WHERE ${change.where}` : '';
+      return `CREATE ${unique}INDEX ${quote(change.name)} ON ${change.table} (${colList(change.columns)})${where};`;
+    }
+    case 'dropIndex': {
+      const schema = change.table.includes('.') ? `${change.table.split('.')[0]}.` : '';
+      return `DROP INDEX ${schema}${quote(change.name)};`;
+    }
+    case 'enumValuesChanged':
+      return `-- NOTICE: enum ${quote(change.name)} values changed ([${change.from.join(', ')}] → [${change.to.join(', ')}]) in a way Postgres can't apply in place (a removal, reorder, or rename). ADD VALUE only appends; reshaping an enum needs a manual type swap (create new type, ALTER COLUMN ... TYPE using a cast, drop old).`;
+  }
+}
+
+/** The change set as an ordered list of SQL statements (and notice comments). */
+export function emitSchemaSql(changes: SchemaChange[], opts: EmitOptions = {}): string[] {
+  return changes.map((c) => emitOne(c, opts));
+}