@everystack/cli 0.2.39 → 0.3.3

package/src/cli/rds-snapshot.ts

@@ -0,0 +1,47 @@
+/**
+ * db:snapshot — the pure core for RDS *physical* snapshots (the thin `aws rds` wrapper).
+ *
+ * RDS snapshot identifiers are far stricter than our backup ids: 1–255 chars, must start with a
+ * letter, letters/digits/hyphens only, no two consecutive hyphens, no trailing hyphen, stored
+ * lowercase. (Underscores, dots, colons — all rejected by RDS.) So our `YYYYMMDDTHHMMSSZ` stamp
+ * can't be used verbatim; this module builds a guaranteed-valid identifier and a validator that
+ * pins the contract. No IO — the clock is passed in. See docs/plans/db-backup-restore.md.
+ */
+
+/**
+ * RDS DBSnapshotIdentifier validity (per the AWS API reference):
+ *   - 1 to 255 letters, numbers, or hyphens
+ *   - first character must be a letter
+ *   - can't end with a hyphen or contain two consecutive hyphens
+ */
+const RDS_SNAPSHOT_ID = /^[A-Za-z][A-Za-z0-9]*(-[A-Za-z0-9]+)*$/;
+
+/** Whether `id` satisfies RDS's DBSnapshotIdentifier constraints. */
+export function isValidRdsSnapshotId(id: string): boolean {
+  return id.length >= 1 && id.length <= 255 && RDS_SNAPSHOT_ID.test(id);
+}
+
+/**
+ * Sanitize a stage name into the leading segment of an RDS identifier: lowercase, non-alphanumeric
+ * runs collapse to a single hyphen, and it is forced to start with a letter (a `db` prefix is
+ * prepended when the stage starts with a digit or is empty). Never emits a trailing hyphen.
+ */
+function sanitizeStage(stage: string): string {
+  let s = stage.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  if (s === '' || !/^[a-z]/.test(s)) s = `db-${s}`.replace(/-+$/g, '');
+  return s;
+}
+
+/**
+ * Build a valid, deterministic RDS snapshot identifier from a stage and a `YYYYMMDDTHHMMSSZ` stamp.
+ * The stamp is lowercased (its `T`/`Z` become valid letters); the result is
+ * `<sanitized-stage>-<stamp>`, e.g. `dev-20260628t120000z`. Throws if — against expectation — the
+ * composed id is still invalid, so a malformed id can never reach the AWS API.
+ */
+export function rdsSnapshotIdentifier(stage: string, stamp: string): string {
+  const id = `${sanitizeStage(stage)}-${stamp.toLowerCase()}`;
+  if (!isValidRdsSnapshotId(id)) {
+    throw new Error(`Could not build a valid RDS snapshot identifier from stage="${stage}", stamp="${stamp}" (got "${id}")`);
+  }
+  return id;
+}

package/src/cli/schema-compile.ts

@@ -0,0 +1,496 @@
+/**
+ * The Model -> table DDL compiler — the data slice of the one generator.
+ *
+ * The counterpart to authz-compile.ts: that turns `abilities` into RLS/grants;
+ * this turns `fields` into `CREATE TABLE`. Both feed the single migration the
+ * generator emits (tables first, then the authz that depends on them).
+ *
+ * It is the field bridge's generation half (architecture Layer 1): one `field()`
+ * carries the pg-precise type + the modifiers (NOT NULL, default, primary key,
+ * unique), and this emits the column DDL from them. drizzle-kit's generation job,
+ * owned. The Zod marriage (CHECK constraints from `.validate()` refinements, the
+ * runtime schema, the inferred TS type) is the next increment; this is structure.
+ *
+ * Output matches the clean drizzle DDL shape the example already ships, so a
+ * brownfield app's tables regenerate byte-for-byte. FK constraints are emitted
+ * separately by the generator (they must follow every table), so `.references()`
+ * is not rendered inline here.
+ *
+ * Input is a `@everystack/model` ModelDescriptor (type-only — no runtime dep).
+ */
+
+import type { ModelDescriptor, FieldSpec } from '@everystack/model';
+import type { TableSchema, EnumType, UniqueConstraint, CheckConstraint, IndexSchema, ForeignKey } from './schema-introspect.js';
+import type { RenameMap } from './schema-diff.js';
+
+/** `authorId` -> `author_id`. SQL identifiers are snake_case. */
+function toSnakeCase(name: string): string {
+  return name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+
+/**
+ * The table-level constraints a Model's `constraints: [...]` block declares — composite
+ * `unique(...)` and multi-column `check(...)`, folded into the structured form both
+ * `compileTableSchema` (the diff IR) and `compileCreateTable` (the DDL) render from, so the
+ * two never disagree. Field keys are snake_cased to SQL columns; names are deterministic
+ * (a composite unique by its columns, a check by its position) so they round-trip.
+ */
+export function modelConstraintSpecs(model: ModelDescriptor): { uniques: UniqueConstraint[]; checks: CheckConstraint[]; indexes: IndexSchema[] } {
+  const uniques: UniqueConstraint[] = [];
+  const checks: CheckConstraint[] = [];
+  const indexes: IndexSchema[] = [];
+  let checkIndex = 0;
+  const usedIndexNames = new Set<string>();
+  for (const con of model.constraints) {
+    if (con.kind === 'unique') {
+      const cols = con.columns.map(toSnakeCase);
+      uniques.push({ name: `${model.table}_${cols.join('_')}_unique`, columns: cols });
+    } else if (con.kind === 'check') {
+      checks.push({ name: `${model.table}_check_${checkIndex++}`, expr: con.predicate });
+    } else if (con.kind === 'index') {
+      const cols = con.columns.map(toSnakeCase);
+      // Disambiguate multiple indexes over the same columns — e.g. a full index plus a
+      // partial one (`familyId` and `familyId WHERE status='active'`): the name must be
+      // unique within the table for CREATE to succeed. The diff matches indexes by content
+      // (columns + uniqueness + predicate), never by name, so the suffix never affects the
+      // round-trip. Declaration order is deterministic, so the name is stable across calls.
+      let name = `${model.table}_${cols.join('_')}_index`;
+      for (let n = 2; usedIndexNames.has(name); n++) name = `${model.table}_${cols.join('_')}_index_${n}`;
+      usedIndexNames.add(name);
+      indexes.push({
+        name,
+        columns: cols,
+        unique: con.isUnique,
+        ...(con.predicate ? { where: con.predicate } : {}),
+      });
+    }
+  }
+  return { uniques, checks, indexes };
+}
+
+/** Postgres type for a field, with the precision drizzle-kit would emit. */
+const PG_TYPE: Record<string, string> = {
+  text: 'text',
+  uuid: 'uuid',
+  integer: 'integer',
+  boolean: 'boolean',
+  jsonb: 'jsonb',
+  bigint: 'bigint',
+  bigserial: 'bigserial',
+  timestamptz: 'timestamp with time zone',
+  // `format_type` canonicalizes a bare `timestamp` column to this spelling, and
+  // introspection compares against it — so the compiler must emit the same, or an
+  // unchanged `timestamp` column round-trips to a spurious ALTER COLUMN TYPE.
+  timestamp: 'timestamp without time zone',
+  date: 'date',
+};
+
+function pgType(spec: FieldSpec): string {
+  // An array is the base type with `[]` appended — `text` → `text[]`, exactly as
+  // `format_type` spells it.
+  return spec.isArray ? `${scalarPgType(spec)}[]` : scalarPgType(spec);
+}
+
+function scalarPgType(spec: FieldSpec): string {
+  // Parameterized types build their own canonical string — exactly as `format_type`
+  // spells it (no space after the comma; `varchar` is `character varying`; a
+  // precision-only numeric carries scale 0), so an unchanged column round-trips clean.
+  if (spec.type === 'numeric') {
+    if (spec.precision != null) return `numeric(${spec.precision},${spec.scale ?? 0})`;
+    return 'numeric';
+  }
+  if (spec.type === 'varchar') {
+    return spec.length != null ? `character varying(${spec.length})` : 'character varying';
+  }
+  if (spec.type === 'enum') {
+    // The column's type is the enum's own type name; `format_type` reports the same bare
+    // name, so it round-trips. The `CREATE TYPE` is emitted separately, before the table.
+    if (!spec.enumName) throw new Error('field bridge: an enum field needs a type name — field.enum(name, values)');
+    return spec.enumName;
+  }
+  const t = PG_TYPE[spec.type];
+  if (!t) {
+    // geometry needs PostGIS — a deliberate follow-up, not a silent wrong column.
+    throw new Error(`field bridge: no DDL mapping for field type '${spec.type}' yet`);
+  }
+  return t;
+}
+
+/**
+ * The FK referential actions declared on a field or a table-level `foreignKey(...)`, dropping
+ * the Postgres default (`no action`, which `pg_get_constraintdef` also omits) so the desired
+ * side matches what introspection reports — otherwise an unchanged FK would read as drift.
+ */
+function refActions(spec: { onDelete?: string; onUpdate?: string }): { onDelete?: string; onUpdate?: string } {
+  const out: { onDelete?: string; onUpdate?: string } = {};
+  if (spec.onDelete && spec.onDelete !== 'no action') out.onDelete = spec.onDelete;
+  if (spec.onUpdate && spec.onUpdate !== 'no action') out.onUpdate = spec.onUpdate;
+  return out;
+}
+
+/**
+ * Every foreign key a model declares — the single source both the structured IR
+ * (`compileTableSchema`) and the greenfield DDL (`foreignKeySql`) read from, so they never
+ * disagree. Single-column FKs come from each field's `.references()`; composite FKs come from
+ * the table-level `foreignKey([...], () => Other, [...])` constraint. Both name themselves the
+ * way drizzle does — `<table>_<cols>_<target>_<refcols>_fk` — so a brownfield FK round-trips.
+ */
+export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
+  const out: ForeignKey[] = [];
+
+  for (const [name, field] of Object.entries(model.fields)) {
+    const ref = field.spec.references;
+    if (!ref) continue;
+    const target = ref() as ModelDescriptor;
+    const col = toSnakeCase(name);
+    const targetPk = toSnakeCase(target.primaryKey[0] ?? 'id');
+    out.push({
+      name: `${model.table}_${col}_${target.table}_${targetPk}_fk`,
+      columns: [col],
+      refTable: refTableName(target),
+      refColumns: [targetPk],
+      ...refActions(field.spec),
+    });
+  }
+
+  for (const con of model.constraints) {
+    if (con.kind !== 'foreignKey') continue;
+    const target = con.references() as ModelDescriptor;
+    const cols = con.columns.map(toSnakeCase);
+    const refCols = con.refColumns.map(toSnakeCase);
+    out.push({
+      name: `${model.table}_${cols.join('_')}_${target.table}_${refCols.join('_')}_fk`,
+      columns: cols,
+      refTable: refTableName(target),
+      refColumns: refCols,
+      ...refActions(con),
+    });
+  }
+
+  return out;
+}
+
+/**
+ * The referenced table's name as the FK should carry it — schema-qualified for a non-public
+ * target (`auth.users`), bare for a public one (`uploads`). A cross-schema FK (auth → auth, or
+ * public → auth) must name the schema, and `pg_get_constraintdef` deparses it qualified when the
+ * target schema is off the search_path — so the desired side must match, or an unchanged auth FK
+ * would read as drift. public stays bare because it is on the search_path (the proven output).
+ */
+function refTableName(target: ModelDescriptor): string {
+  return target.schema && target.schema !== 'public' ? `${target.schema}.${target.table}` : target.table;
+}
+
+/** Quote each dot-separated part of a (possibly schema-qualified) name: `auth.users` → `"auth"."users"`. */
+function quoteParts(name: string): string {
+  return name.split('.').map((p) => `"${p}"`).join('.');
+}
+
+/** The ` ON DELETE … ON UPDATE …` clause for a FK, or '' when both are the default. */
+function refActionSql(fk: { onDelete?: string; onUpdate?: string }): string {
+  let s = '';
+  if (fk.onDelete) s += ` ON DELETE ${fk.onDelete.toUpperCase()}`;
+  if (fk.onUpdate) s += ` ON UPDATE ${fk.onUpdate.toUpperCase()}`;
+  return s;
+}
+
+/** A column's DEFAULT expression, or null when it has none. */
+function defaultExpr(spec: FieldSpec): string | null {
+  switch (spec.defaultKind) {
+    case 'now': return 'now()';
+    case 'random': return 'gen_random_uuid()';
+    case 'value':
+      return spec.isArray && Array.isArray(spec.default) ? arrayLiteral(spec.default) : literal(spec.default);
+    default: return null;
+  }
+}
+
+/**
+ * A Postgres array literal for a default — `[]` → `'{}'`, `['a','b']` → `'{"a","b"}'`.
+ * The introspected form carries a `::type[]` cast (`'{}'::text[]`) that `normalizeDefault`
+ * strips, so the bare literal round-trips.
+ */
+function arrayLiteral(arr: unknown[]): string {
+  const elems = arr.map((v) => (typeof v === 'string' ? `"${v.replace(/"/g, '\\"')}"` : String(v)));
+  return `'{${elems.join(',')}}'`;
+}
+
+function literal(value: unknown): string {
+  if (typeof value === 'string') return `'${value.replace(/'/g, "''")}'`;
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  return String(value);
+}
+
+/**
+ * One column definition (no leading indent). Clause order matches drizzle's:
+ * type, PRIMARY KEY (single-column only), DEFAULT, NOT NULL. `.references()`,
+ * `.unique()`, and composite PKs are table-level, emitted by compileCreateTable.
+ */
+export function fieldColumnSql(sqlName: string, spec: FieldSpec, inlinePrimaryKey: boolean): string {
+  let s = `"${sqlName}" ${pgType(spec)}`;
+  if (inlinePrimaryKey) s += ' PRIMARY KEY';
+  const def = defaultExpr(spec);
+  if (def) s += ` DEFAULT ${def}`;
+  if (spec.isNotNull) s += ' NOT NULL';
+  return s;
+}
+
+// --- CHECK constraints from .validate() Zod refinements --------------------
+
+interface ZodDefLike {
+  typeName?: string;
+  checks?: Array<{ kind: string; value?: unknown; inclusive?: boolean }>;
+  values?: readonly string[];
+  innerType?: { _def?: ZodDefLike };
+}
+
+function zodDef(schema: unknown): ZodDefLike | null {
+  const d = (schema as { _def?: unknown } | null | undefined)?._def;
+  return d && typeof d === 'object' ? (d as ZodDefLike) : null;
+}
+
+/** Unwrap ZodOptional / ZodNullable / ZodDefault to the base type. */
+function unwrapZod(def: ZodDefLike): ZodDefLike {
+  let cur = def;
+  while (cur.innerType?._def) cur = cur.innerType._def;
+  return cur;
+}
+
+/**
+ * The SQL CHECK predicate for a field's `.validate()` schema, or null when none
+ * of its refinements are SQL-expressible.
+ *
+ * The two-paths split (the field bridge's point): `min`/`max`/`length`/`enum`/
+ * range become a DB CHECK — the backstop that covers the SSR-direct write path,
+ * which never runs the app-layer Zod. Rich refinements (regex, email, cross-field
+ * `.refine()`) are NOT SQL-expressible and stay app-layer Zod only; they are
+ * intentionally skipped here, never half-emitted.
+ *
+ * Reads Zod's internal `_def` (pinned to zod 3.x — the same coupling drizzle-zod
+ * accepts). An unrecognized shape yields null, never a wrong constraint.
+ */
+export function fieldCheckPredicate(sqlName: string, spec: FieldSpec): string | null {
+  const top = zodDef(spec.validation);
+  if (!top) return null;
+  const def = unwrapZod(top);
+
+  if (def.typeName === 'ZodString') {
+    let min: number | undefined;
+    let max: number | undefined;
+    let exact: number | undefined;
+    for (const c of def.checks ?? []) {
+      if (c.kind === 'min') min = c.value as number;
+      else if (c.kind === 'max') max = c.value as number;
+      else if (c.kind === 'length') exact = c.value as number;
+    }
+    if (exact != null) return `char_length(${sqlName}) = ${exact}`;
+    if (min != null && max != null) return `char_length(${sqlName}) BETWEEN ${min} AND ${max}`;
+    if (min != null) return `char_length(${sqlName}) >= ${min}`;
+    if (max != null) return `char_length(${sqlName}) <= ${max}`;
+    return null;
+  }
+
+  if (def.typeName === 'ZodNumber') {
+    let min: number | undefined;
+    let max: number | undefined;
+    let minIncl = true;
+    let maxIncl = true;
+    for (const c of def.checks ?? []) {
+      if (c.kind === 'min') { min = c.value as number; minIncl = c.inclusive !== false; }
+      else if (c.kind === 'max') { max = c.value as number; maxIncl = c.inclusive !== false; }
+    }
+    if (min != null && max != null && minIncl && maxIncl) return `${sqlName} BETWEEN ${min} AND ${max}`;
+    const parts: string[] = [];
+    if (min != null) parts.push(`${sqlName} ${minIncl ? '>=' : '>'} ${min}`);
+    if (max != null) parts.push(`${sqlName} ${maxIncl ? '<=' : '<'} ${max}`);
+    return parts.length ? parts.join(' AND ') : null;
+  }
+
+  if (def.typeName === 'ZodEnum') {
+    const vals = def.values ?? [];
+    if (!vals.length) return null;
+    return `${sqlName} IN (${vals.map((v) => `'${String(v).replace(/'/g, "''")}'`).join(', ')})`;
+  }
+
+  return null;
+}
+
+export interface CompileTableOptions {
+  /** Indent for column/constraint lines. Default: a tab (matches drizzle's output). */
+  indent?: string;
+}
+
+/**
+ * A model's table as a quoted SQL name — schema-qualified only for a non-public
+ * schema. Drizzle leaves `public` tables bare (`"posts"`), and the example's
+ * brownfield DDL matches that, so a public model stays unqualified; a package
+ * table in its own schema becomes `"dist"."blobs"`.
+ */
+export function qualifiedTable(model: ModelDescriptor): string {
+  return model.schema && model.schema !== 'public'
+    ? `"${model.schema}"."${model.table}"`
+    : `"${model.table}"`;
+}
+
+/**
+ * `CREATE TABLE` for a model's fields. Single-column primary keys are inline;
+ * composite keys and uniques become table constraints, named the way drizzle
+ * names them (`<table>_<cols>_pk`, `<table>_<col>_unique`).
+ */
+export function compileCreateTable(model: ModelDescriptor, opts: CompileTableOptions = {}): string {
+  const indent = opts.indent ?? '\t';
+  const entries = Object.entries(model.fields);
+  const pkFields = model.primaryKey;
+  const singlePk = pkFields.length === 1 ? pkFields[0] : null;
+
+  const lines: string[] = [];
+  for (const [name, field] of entries) {
+    lines.push(indent + fieldColumnSql(toSnakeCase(name), field.spec, name === singlePk));
+  }
+
+  if (pkFields.length > 1) {
+    const cols = pkFields.map(toSnakeCase);
+    const quoted = cols.map((c) => `"${c}"`).join(',');
+    lines.push(`${indent}CONSTRAINT "${model.table}_${cols.join('_')}_pk" PRIMARY KEY(${quoted})`);
+  }
+
+  for (const [name, field] of entries) {
+    if (field.spec.isUnique) {
+      const col = toSnakeCase(name);
+      lines.push(`${indent}CONSTRAINT "${model.table}_${col}_unique" UNIQUE("${col}")`);
+    }
+  }
+
+  for (const [name, field] of entries) {
+    const col = toSnakeCase(name);
+    const pred = fieldCheckPredicate(col, field.spec);
+    if (pred) lines.push(`${indent}CONSTRAINT "${model.table}_${col}_check" CHECK (${pred})`);
+  }
+
+  // Table-level constraints (composite unique, multi-column check) after the field-derived ones.
+  const tableConstraints = modelConstraintSpecs(model);
+  for (const u of tableConstraints.uniques) {
+    lines.push(`${indent}CONSTRAINT "${u.name}" UNIQUE(${u.columns.map((c) => `"${c}"`).join(',')})`);
+  }
+  for (const ck of tableConstraints.checks) {
+    lines.push(`${indent}CONSTRAINT "${ck.name}" CHECK (${ck.expr})`);
+  }
+
+  return `CREATE TABLE ${qualifiedTable(model)} (\n${lines.join(',\n')}\n);`;
+}
+
+/**
+ * Compile a model's `fields` into the structured TableSchema — the same shape
+ * whole-DB introspection produces. This is the data layer's second producer (the
+ * counterpart to compileTableContract for authz): the Model and the live database
+ * meet at this IR, so `db:generate` can diff them. Types come from `format_type`'s
+ * vocabulary on both sides, so they compare.
+ *
+ * (compileCreateTable renders SQL directly for the greenfield emit; this is the
+ * structured form for the brownfield diff. They share the field→type/default/check
+ * helpers, so they never disagree.)
+ */
+export function compileTableSchema(model: ModelDescriptor, opts: { schema?: string } = {}): TableSchema {
+  const schema = model.schema ?? opts.schema ?? 'public';
+  const entries = Object.entries(model.fields);
+
+  const columns = entries.map(([name, field]) => ({
+    name: toSnakeCase(name),
+    type: pgType(field.spec),
+    notNull: field.spec.isNotNull,
+    default: defaultExpr(field.spec),
+  }));
+
+  const tableConstraints = modelConstraintSpecs(model);
+
+  const fieldUniques = entries
+    .filter(([, field]) => field.spec.isUnique)
+    .map(([name]) => {
+      const col = toSnakeCase(name);
+      return { name: `${model.table}_${col}_unique`, columns: [col] };
+    });
+  const uniques = [...fieldUniques, ...tableConstraints.uniques];
+
+  const fieldChecks = entries.flatMap(([name, field]) => {
+    const col = toSnakeCase(name);
+    const pred = fieldCheckPredicate(col, field.spec);
+    return pred ? [{ name: `${model.table}_${col}_check`, expr: pred }] : [];
+  });
+  const checks = [...fieldChecks, ...tableConstraints.checks];
+
+  return {
+    table: `${schema}.${model.table}`,
+    columns,
+    primaryKey: model.primaryKey.map(toSnakeCase),
+    uniques,
+    checks,
+    foreignKeys: modelForeignKeys(model),
+    indexes: tableConstraints.indexes,
+  };
+}
+
+/**
+ * The enum types a set of Models declares — the desired-side counterpart to the
+ * `enums` whole-DB introspection folds. Collected across every `field.enum(name, values)`,
+ * de-duplicated by name (the same enum may back columns on several tables), sorted to
+ * match `assembleSchema`'s order so the two sides diff. A name reused with *different*
+ * values is a model error surfaced here, not a silently-merged type.
+ */
+export function compileEnums(models: ModelDescriptor[]): EnumType[] {
+  const byName = new Map<string, EnumType>();
+  for (const model of models) {
+    for (const field of Object.values(model.fields)) {
+      const { type, enumName, enumValues } = field.spec;
+      if (type !== 'enum' || !enumName) continue;
+      const values = [...(enumValues ?? [])];
+      const existing = byName.get(enumName);
+      if (existing && existing.values.join(',') !== values.join(',')) {
+        throw new Error(`enum '${enumName}' is declared with conflicting values: [${existing.values}] vs [${values}]`);
+      }
+      if (!existing) byName.set(enumName, { name: enumName, values });
+    }
+  }
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Foreign-key constraints for a model — its `.references()` fields and its table-level
+ * `foreignKey(...)` constraints, via `modelForeignKeys` — as `ALTER TABLE` statements. These
+ * are emitted *after* every `CREATE TABLE` (a FK's target table must already exist), so they
+ * are separate from the table DDL — which is why FKs are not rendered inline by
+ * compileCreateTable. Named the way drizzle names them: `<table>_<cols>_<target>_<refcols>_fk`.
+ */
+export function foreignKeySql(model: ModelDescriptor): string[] {
+  return modelForeignKeys(model).map((fk) => {
+    const cols = fk.columns.map((c) => `"${c}"`).join(', ');
+    const refCols = fk.refColumns.map((c) => `"${c}"`).join(', ');
+    // Both sides are schema-qualified for a non-public table — `ALTER TABLE "auth"."identities"`
+    // and `REFERENCES "auth"."users"` — so a cross-schema FK targets the right table. public
+    // stays bare-but-quoted (`"uploads"`), preserving the proven output.
+    return (
+      `ALTER TABLE ${qualifiedTable(model)} ADD CONSTRAINT "${fk.name}" ` +
+      `FOREIGN KEY (${cols}) REFERENCES ${quoteParts(fk.refTable)}(${refCols})${refActionSql(fk)};`
+    );
+  });
+}
+
+/**
+ * Collect the `renamedFrom` markers off a set of Models into a rename map keyed the same
+ * way the compiled snapshot keys tables (`public.posts`). This is the rename *intent*,
+ * carried separately from the TableSchema IR — introspection cannot produce it (the
+ * database has no rename history), so it never belongs on a column. `diffSchema` reads
+ * this map to turn a drop+add into a `RENAME COLUMN`.
+ */
+export function compileRenames(models: ModelDescriptor[], opts: { schema?: string } = {}): RenameMap {
+  const map: RenameMap = {};
+  for (const model of models) {
+    const schema = model.schema ?? opts.schema ?? 'public';
+    for (const [name, field] of Object.entries(model.fields)) {
+      const from = field.spec.renamedFrom;
+      if (!from) continue;
+      const table = `${schema}.${model.table}`;
+      (map[table] ??= {})[toSnakeCase(name)] = toSnakeCase(from);
+    }
+  }
+  return map;
+}