@everystack/cli 0.4.99 → 0.4.102

package/src/cli/schema-diff.ts

@@ -33,6 +33,7 @@ import type {
   IndexSchema,
   SequenceSchema,
 } from './schema-introspect';
+import { renderConstraintRename, renderIndexRename } from './catalog-rename';
 
 // ---------------------------------------------------------------------------
 // The change set.
@@ -73,8 +74,14 @@ export type SchemaChange =
    * from `from`, so it can only ever emit the one statement that applies.
    */
   | { kind: 'setIdentity'; table: string; column: string; identity: 'always' | 'byDefault' | null; from: 'always' | 'byDefault' | 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 }
+  /**
+   * A type change → real `ALTER COLUMN ... TYPE`. `risk` decides USING + a data-loss warning.
+   * `toEnum`: the target is a declared enum. PostgreSQL has no cast between two enum types, so
+   * the USING goes through text. `dropDefault`: the live column has a default, which cannot be
+   * cast automatically either, so it is dropped first; a `setDefault` after the retype restores
+   * the declared one. Both are absent, never false, so every other retype keeps its shape.
+   */
+  | { kind: 'alterType'; table: string; column: string; from: string; to: string; risk: TypeChangeRisk; toEnum?: true; dropDefault?: true }
   | { kind: 'addConstraint'; table: string; constraint: ConstraintSpec; note?: string }
   /**
    * A foreign key that is already installed on the live table but has never been checked
@@ -85,9 +92,23 @@ export type SchemaChange =
    * This is what the state after an interrupted two-step add re-plans to — VALIDATE only.
    */
   | { kind: 'validateConstraint'; table: string; name: string }
-  | { 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). */
+  /**
+   * `replacesPrimaryKey`: this is the LIVE primary key, dropped so the declared one (these
+   * columns) can take its place. The structured marker for a key replacement — it exempts the
+   * drop from the held-removal gate (an `addPrimaryKey` follows it in the same edge) and it is
+   * what the emitter writes the `-- WARNING: primary key …` note from. Absent on every other drop.
+   */
+  | { kind: 'dropConstraint'; table: string; name: string; replacesPrimaryKey?: string[] }
+  /**
+   * `name` is set when the key REPLACES a live one, and is what a from-scratch build names it
+   * ({@link primaryKeyConstraintName}). A first-time add carries none and PostgreSQL names it.
+   */
+  | { kind: 'addPrimaryKey'; table: string; columns: string[]; name?: string }
+  /**
+   * A PK change the differ cannot plan: the live key's name is unknown (a snapshot read before
+   * introspection carried it), so there is nothing to drop it by. A notice — and db:plan refuses
+   * to mint over one, because the fingerprint sees the key the plan would leave unchanged.
+   */
   | { 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 }
@@ -226,6 +247,67 @@ function bareTable(table: string): string {
   return table.replace(/^[^.]+\./, '');
 }
 
+/** The longest identifier PostgreSQL keeps (NAMEDATALEN - 1), in bytes. */
+const MAX_IDENTIFIER_BYTES = 63;
+
+/** `s` clipped to at most `max` UTF-8 bytes, never splitting a character. */
+function clipBytes(s: string, max: number): string {
+  const enc = new TextEncoder();
+  let out = s;
+  while (enc.encode(out).length > max) out = out.slice(0, -1);
+  return out;
+}
+
+/**
+ * The name a from-scratch build gives a table's primary key — ONE definition, read by the
+ * greenfield compiler and by the differ when it replaces a live key, so an evolved database and
+ * a fresh build of the same models name the key the same way.
+ *
+ *   - one column: the compiler writes it inline (`"id" uuid PRIMARY KEY`) and PostgreSQL names
+ *     it `<table>_pkey`, clipping the TABLE part (never the suffix) to fit 63 bytes.
+ *   - several columns: the compiler names the table constraint `<table>_<cols>_pk`, the way
+ *     drizzle does.
+ *
+ * `table` is the bare table name, never schema-qualified.
+ */
+export function primaryKeyConstraintName(table: string, columns: readonly string[]): string {
+  if (columns.length > 1) return `${table}_${columns.join('_')}_pk`;
+  const suffix = '_pkey';
+  return `${clipBytes(table, MAX_IDENTIFIER_BYTES - suffix.length)}${suffix}`;
+}
+
+/**
+ * The note a primary key REPLACEMENT carries on its DROP, and its parser. Rendered from the
+ * change's structured `replacesPrimaryKey` marker and read back by the plain plan report for its
+ * `⚠ CONSTRAINT` line; the two live side by side so they cannot drift, and the parser accepts
+ * exactly the line the renderer writes. `WARNING`, not `NOTICE`: the statement under it runs
+ * (NOTICE is the reserved prefix of a pure comment).
+ */
+export interface PrimaryKeyReplacement {
+  /** Schema-qualified, as the snapshot spells it (`public.likes`). */
+  table: string;
+  /** The live key being dropped. */
+  name: string;
+  /** The declared key's columns. */
+  columns: string[];
+}
+
+export function renderPrimaryKeyReplacement(r: PrimaryKeyReplacement): string {
+  return `-- WARNING: primary key ${quote(r.name)} on ${r.table} is replaced by (${colList(r.columns)}).`;
+}
+
+// Assumes a whitespace-free table name (`\S+`); the plan file carries statements only, so this note is the one record.
+const PK_REPLACEMENT_RE = /^-- WARNING: primary key "([^"]*)" on (\S+) is replaced by \(((?:"[^"]*"(?:, )?)+)\)\.$/;
+
+/** The replacement a statement's note records, or null when it carries none. */
+export function parsePrimaryKeyReplacement(statement: string): PrimaryKeyReplacement | null {
+  for (const line of statement.split('\n')) {
+    const m = PK_REPLACEMENT_RE.exec(line.trim());
+    if (m) return { name: m[1], table: m[2], columns: [...m[3].matchAll(/"([^"]*)"/g)].map((c) => c[1]) };
+  }
+  return null;
+}
+
 /** `CREATE SEQUENCE` DDL for a standalone sequence — emitted BEFORE any table, so a
  *  column's `defaultSql(nextval(…))` can draw on it from the first CREATE. */
 export function sequenceCreateSql(seq: SequenceSchema): string {
@@ -412,8 +494,8 @@ function parenOnlyNote(kind: string, name: string, liveName: string, liveExpr: s
 /**
  * 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
+ * be applied: new tables, then new columns, then dropped constraints and primary keys,
+ * then column alters, 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.
  */
@@ -426,6 +508,10 @@ export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, ren
   const alters: SchemaChange[] = [];
   const dropConstraints: SchemaChange[] = [];
   const addConstraints: SchemaChange[] = [];
+  /** Primary keys: the live key's drop after every other constraint drop (a foreign key on it
+   *  goes first), the declared key's add before every other add (a foreign key may need it). */
+  const dropPrimaryKeys: SchemaChange[] = [];
+  const addPrimaryKeys: SchemaChange[] = [];
   const createIndexes: SchemaChange[] = [];
   /** Catalog-only renames — indexes (B3) and FK constraints (A8). */
   const catalogRenames: SchemaChange[] = [];
@@ -510,6 +596,7 @@ export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, ren
     currentByName.set(to, { ...source, table: to });
   }
 
+  const declaredEnumNames = new Set((desired.enums ?? []).map((e) => e.name));
   for (const d of desired.tables) {
     const c = currentByName.get(d.table);
     if (!c) {
@@ -526,13 +613,14 @@ export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, ren
       for (const ix of d.indexes) createIndexes.push(createIndexChange(d.table, ix));
       continue;
     }
-    const cd = diffColumns(d, c, renames[d.table] ?? {});
+    const cd = diffColumns(d, c, renames[d.table] ?? {}, declaredEnumNames);
     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, catalogRenames);
+    diffPrimaryKey(d, c, dropPrimaryKeys, addPrimaryKeys, alters);
     diffIndexes(d, c, createIndexes, dropIndexes, catalogRenames, redefineIndexes);
   }
 
@@ -587,12 +675,15 @@ export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, ren
     ...e.creates, ...e.adds, ...sequenceCreates,
     ...moveTables,
     ...renameTables,
-    ...creates, ...renameColumns, ...addColumns, ...alters, ...trailingDefaults,
+    ...creates, ...renameColumns, ...addColumns,
     // Renames are catalog-only and precede the creates, so a declared name freed by renaming an
     // existing object is never claimed by a fresh CREATE first.
     // redefineIndexes immediately precede createIndexes: PostgreSQL has no CREATE OR REPLACE
     // INDEX, so the old one must be gone before its replacement claims the name.
-    ...catalogRenames, ...dropConstraints, ...addConstraints, ...redefineIndexes, ...createIndexes,
+    // A replaced primary key: the old one is dropped after every other constraint drop and the
+    // new one added after column alters and before every other add — so a partial unique index or a foreign key that
+    // needs the new key comes after it, and nothing still references the old one when it goes.
+    ...catalogRenames, ...dropConstraints, ...dropPrimaryKeys, ...alters, ...trailingDefaults, ...addPrimaryKeys, ...addConstraints, ...redefineIndexes, ...createIndexes,
     ...dropColumns, ...dropIndexes, ...dropTables,
     ...e.drops, ...notices, ...e.notices, ...sequenceNotices,
   ];
@@ -745,10 +836,21 @@ interface ColumnDiff {
 }
 
 /** 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) });
+function columnAlters(table: string, desired: ColumnSchema, source: ColumnSchema, into: SchemaChange[], enumNames: ReadonlySet<string>): void {
+  // A retype onto an enum drops the live default first (see `alterType`), so the declared
+  // default must be set again even when it reads the same on both sides.
+  const dropsDefault = desired.type !== source.type && enumNames.has(desired.type) && source.default != null;
+  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),
+      ...(enumNames.has(desired.type) ? { toEnum: true as const } : {}),
+      ...(dropsDefault ? { dropDefault: true as const } : {}),
+    });
+  }
   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 });
+  if (normalizeDefault(desired.default) !== normalizeDefault(source.default) || (dropsDefault && desired.default != null)) {
+    into.push({ kind: 'setDefault', table, column: desired.name, expr: desired.default });
+  }
   // Emitted AFTER setDefault deliberately: Postgres refuses ADD GENERATED on a column that
   // still holds a default, which is exactly the shape of a serial → identity migration.
   if ((desired.identity ?? null) !== (source.identity ?? null)) {
@@ -756,7 +858,7 @@ function columnAlters(table: string, desired: ColumnSchema, source: ColumnSchema
   }
 }
 
-function diffColumns(d: TableSchema, c: TableSchema, tableRenames: Record<string, string>): ColumnDiff {
+function diffColumns(d: TableSchema, c: TableSchema, tableRenames: Record<string, string>, enumNames: ReadonlySet<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));
@@ -769,7 +871,7 @@ function diffColumns(d: TableSchema, c: TableSchema, tableRenames: Record<string
     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);
+      columnAlters(d.table, col, cur, out.alters, enumNames);
       continue;
     }
 
@@ -778,7 +880,7 @@ function diffColumns(d: TableSchema, c: TableSchema, tableRenames: Record<string
     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
+      columnAlters(d.table, col, source, out.alters, enumNames); // 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 });
@@ -849,8 +951,12 @@ export function foreignKeyContentKey(
  * 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.
+ *
+ * R9, the CHECK half of B3/A8: a predicate match whose DECLARED name disagrees with the live
+ * one is the same check under another name — `RENAME CONSTRAINT`, catalog-only, no re-scan.
+ * An undeclared (positional) name never renames the database.
  */
-function diffChecks(d: TableSchema, c: TableSchema, dropConstraints: SchemaChange[], addConstraints: SchemaChange[]): void {
+function diffChecks(d: TableSchema, c: TableSchema, dropConstraints: SchemaChange[], addConstraints: SchemaChange[], renames: 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]));
   // Paren-blind lookup, diagnostic only (see diffIndexes): a compound CHECK churns for the
@@ -860,7 +966,11 @@ function diffChecks(d: TableSchema, c: TableSchema, dropConstraints: SchemaChang
     if (!desiredByPred.has(pred)) dropConstraints.push({ kind: 'dropConstraint', table: d.table, name: ck.name });
   }
   for (const [pred, ck] of desiredByPred) {
-    if (currentByPred.has(pred)) continue;
+    const live = currentByPred.get(pred);
+    if (live) {
+      if (ck.nameDeclared && live.name !== ck.name) renames.push({ kind: 'renameConstraint', table: d.table, from: live.name, to: ck.name });
+      continue;
+    }
     const twin = currentByParenBlind.get(stripAllParens(ck.expr));
     // Annotate only a twin that is itself being dropped (no exact desired match) — a real churn.
     const churning = twin && !desiredByPred.has(normalizeCheck(twin.expr));
@@ -921,16 +1031,35 @@ function diffConstraints(d: TableSchema, c: TableSchema, dropConstraints: Schema
     for (const cur of bucket) dropConstraints.push({ kind: 'dropConstraint', table: d.table, name: cur.name });
   }
 
-  diffChecks(d, c, dropConstraints, addConstraints);
+  diffChecks(d, c, dropConstraints, addConstraints, renames);
+}
 
-  // 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 });
+/**
+ * Primary key. Compared by columns only — the name is not state, so a live key under another
+ * name with the same columns is no change at all.
+ *
+ *   - first-time add: `ADD PRIMARY KEY`, PostgreSQL names it.
+ *   - removed (declared has none): a plain drop of the live key, held like any other removal.
+ *   - replaced: drop the live key BY ITS LIVE NAME, add the declared one under the name a
+ *     from-scratch build gives it. Never CASCADE: a foreign key on the old key fails the apply.
+ *   - the live name is unknown (an old snapshot): a `primaryKeyChange` notice, never a guess.
+ */
+function diffPrimaryKey(d: TableSchema, c: TableSchema, drops: SchemaChange[], adds: SchemaChange[], alters: SchemaChange[]): void {
+  if (d.primaryKey.join(',') === c.primaryKey.join(',')) return;
+  if (c.primaryKey.length === 0) {
+    adds.push({ kind: 'addPrimaryKey', table: d.table, columns: d.primaryKey });
+    return;
+  }
+  if (!c.primaryKeyName) {
+    alters.push({ kind: 'primaryKeyChange', table: d.table, from: c.primaryKey, to: d.primaryKey });
+    return;
+  }
+  if (d.primaryKey.length === 0) {
+    drops.push({ kind: 'dropConstraint', table: d.table, name: c.primaryKeyName });
+    return;
   }
+  drops.push({ kind: 'dropConstraint', table: d.table, name: c.primaryKeyName, replacesPrimaryKey: d.primaryKey });
+  adds.push({ kind: 'addPrimaryKey', table: d.table, columns: d.primaryKey, name: primaryKeyConstraintName(bareTable(d.table), d.primaryKey) });
 }
 
 // ---------------------------------------------------------------------------
@@ -938,6 +1067,11 @@ function diffConstraints(d: TableSchema, c: TableSchema, dropConstraints: Schema
 // ---------------------------------------------------------------------------
 
 const quote = (name: string): string => `"${name}"`;
+/** A type identity — `post_status` or `analytics.post_status` — quoted part by part. */
+const quoteType = (name: string): string => {
+  const dot = name.indexOf('.');
+  return dot === -1 ? quote(name) : `${quote(name.slice(0, dot))}.${quote(name.slice(dot + 1))}`;
+};
 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, "''")}'`;
@@ -1101,12 +1235,15 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string | string[] {
     }
     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};`;
+      if (change.risk === 'safe' && !change.toEnum) return `${setType};`;
+      const ddl = `${setType} USING ${quote(change.column)}::${change.toEnum ? 'text::' : ''}${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}`;
+      const retype = change.risk === 'safe' ? ddl : `${warn}\n${ddl}`;
+      return change.dropDefault
+        ? [`ALTER TABLE ${change.table} ALTER COLUMN ${quote(change.column)} DROP DEFAULT;`, retype]
+        : retype;
     }
     case 'addConstraint': {
       const [first, ...rest] = addConstraintSql(change.table, change.constraint);
@@ -1117,9 +1254,16 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string | string[] {
     case 'validateConstraint':
       return validateConstraintSql(change.table, change.name);
     case 'dropConstraint':
-      return `ALTER TABLE ${change.table} DROP CONSTRAINT IF EXISTS ${quote(change.name)};`;
+      // A replaced primary key drops WITHOUT `IF EXISTS`: a key renamed between plan and apply
+      // fails on the DROP itself, never silently skips it and fails later on the ADD.
+      return change.replacesPrimaryKey
+        ? `${renderPrimaryKeyReplacement({ table: change.table, name: change.name, columns: change.replacesPrimaryKey })}\n` +
+          `ALTER TABLE ${change.table} DROP CONSTRAINT ${quote(change.name)};`
+        : `ALTER TABLE ${change.table} DROP CONSTRAINT IF EXISTS ${quote(change.name)};`;
     case 'addPrimaryKey':
-      return `ALTER TABLE ${change.table} ADD PRIMARY KEY (${colList(change.columns)});`;
+      return change.name
+        ? `ALTER TABLE ${change.table} ADD CONSTRAINT ${quote(change.name)} PRIMARY KEY (${colList(change.columns)});`
+        : `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':
@@ -1148,11 +1292,11 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string | string[] {
     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(', ')});`;
+      return `CREATE TYPE ${quoteType(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)};`;
+      return `-- WARNING: ADD VALUE to enum ${quoteType(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 ${quoteType(change.type)} ADD VALUE ${enumLiteral(change.value)};`;
     case 'dropType':
-      return `DROP TYPE ${quote(change.name)};`;
+      return `DROP TYPE ${quoteType(change.name)};`;
     case 'createIndex': {
       const unique = change.unique ? 'UNIQUE ' : '';
       const using = change.using ? ` USING ${change.using}` : '';
@@ -1170,18 +1314,17 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string | string[] {
     }
     case 'renameConstraint':
       // Catalog-only and instant — the constraint and its backing index keep their identity.
-      return `ALTER TABLE ${change.table} RENAME CONSTRAINT ${quote(change.from)} TO ${quote(change.to)};`;
+      // Rendered beside its parser: db:apply reads this exact text back (catalog-rename).
+      return renderConstraintRename(change);
     case 'redefineIndex': {
       // Same statement as a removal; a DIFFERENT decision, which is why it is a different kind.
       const schema = change.table.includes('.') ? `${change.table.split('.')[0]}.` : '';
       return `DROP INDEX ${schema}${quote(change.name)};`;
     }
-    case 'renameIndex': {
-      // Non-destructive and instant — a catalog rename, no rebuild. The schema qualifier comes
-      // from the table; ALTER INDEX takes it on the OLD name only.
-      const schema = change.table.includes('.') ? `${change.table.split('.')[0]}.` : '';
-      return `ALTER INDEX ${schema}${quote(change.from)} RENAME TO ${quote(change.to)};`;
-    }
+    case 'renameIndex':
+      // Non-destructive and instant — a catalog rename, no rebuild. Rendered beside its parser:
+      // db:apply reads this exact text back (catalog-rename).
+      return renderIndexRename(change);
     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).`;
     case 'createSequence':

package/src/cli/schema-fingerprint.ts

@@ -53,7 +53,8 @@
 import { createHash } from 'node:crypto';
 import { canonicalAuthz } from './authz-canonical';
 import type { ModelDescriptor, SequenceDescriptor } from '@everystack/model';
-import type { SchemaSnapshot, TableSchema } from './schema-introspect';
+import { assertExternalTargets, relationDeleteActions } from '@everystack/model';
+import type { EnumType, SchemaSnapshot, TableSchema } from './schema-introspect';
 import type { AuthzContract, TableContract, SequenceGrantContract } from './authz-contract';
 import { compileTableSchema, compileEnums, compileSequences } from './schema-compile';
 import { compileTableContract } from './authz-compile';
@@ -340,6 +341,27 @@ export function schemaOf(qualifiedName: string): string {
   return dot === -1 ? 'public' : qualifiedName.slice(0, dot);
 }
 
+/**
+ * `stats.status` → `status`; a bare (public) name is returned as is.
+ * Live-side hash inputs are unchanged. The models side now also strips a qualifier a model
+ * declared (`field.enum('stats.status', …)`), which never converged against live anyway.
+ */
+const bareEnumName = (name: string): string => (schemaOf(name) === 'public' ? name : name.slice(name.indexOf('.') + 1));
+
+/**
+ * The enum list every canon hashes: bare names, in the order the introspection read used to
+ * give them (bare name, then schema). Two schemas holding the same bare name still hash both,
+ * as before, and in a fixed order.
+ */
+function bareEnums(enums: readonly EnumType[]): EnumType[] {
+  return [...enums]
+    .sort((a, b) => {
+      const [an, bn, as, bs] = [bareEnumName(a.name), bareEnumName(b.name), schemaOf(a.name), schemaOf(b.name)];
+      return an < bn ? -1 : an > bn ? 1 : as < bs ? -1 : as > bs ? 1 : 0;
+    })
+    .map((e) => ({ ...e, name: bareEnumName(e.name) }));
+}
+
 export interface CanonicalizeOptions {
   /** Restrict the state to these schemas — the content address of ONE schema (e.g. a
    *  schema-scoped artifact) instead of the whole database. Omitted = every schema. */
@@ -376,12 +398,15 @@ export function canonicalizeState(
   const keepTable = (name: string) => inScope === null || inScope.has(schemaOf(name));
 
   const tables = snapshot.tables.filter((t) => keepTable(t.table));
-  // Enums carry no schema in the descriptor (keyed by bare name, like the model side).
+  // The canon keys enums by BARE name. The snapshot now qualifies a non-public enum
+  // (`stats.status`) so the diff cannot mistake it for a public one; the canon strips that
+  // back off, so every hash input is exactly what it was. Keying the canon by the qualified
+  // identity is a canon change, and needs a FINGERPRINT_VERSION bump of its own.
   // Scope them by USE: an enum is in-scope when a kept table has a column of that type
   // (the type may be qualified under canonical introspection — `stats.status` — so match
   // on the bare tail). This keeps the exact set the scoped models declare.
   const usedEnum = new Set<string>();
-  for (const t of tables) for (const c of t.columns) usedEnum.add(schemaOf(c.type) === 'public' ? c.type : c.type.slice(c.type.indexOf('.') + 1));
+  for (const t of tables) for (const c of t.columns) usedEnum.add(bareEnumName(c.type));
 
   const sequences = byKey(
     (snapshot.sequences ?? [])
@@ -397,7 +422,7 @@ export function canonicalizeState(
     v: FINGERPRINT_VERSION,
     tables: byKey(tables.map(canonicalTable), (t) => String(t.table)),
     enums: byKey(
-      (snapshot.enums ?? [])
+      bareEnums(snapshot.enums ?? [])
         .filter((e) => inScope === null || usedEnum.has(e.name))
         .map((e) => ({ name: e.name, values: e.values })),
       (e) => e.name,
@@ -468,9 +493,14 @@ export function fingerprintModels(
   models: ModelDescriptor[],
   opts: { schema?: string; sequences?: SequenceDescriptor[]; schemas?: string[] } = {},
 ): Fingerprint {
+  // Over the WHOLE set, before scoping: an external target a model declares is refused wherever
+  // that model lives. Nothing else here knows an external FK from a model FK.
+  assertExternalTargets(models);
+  // Also over the whole set: a parent's hasMany `dependent` sets the ON DELETE of a child's FK.
+  const dependents = relationDeleteActions(models);
   const scoped = opts.schemas ? models.filter((m) => opts.schemas!.includes(m.schema)) : models;
   const snapshot: SchemaSnapshot = {
-    tables: scoped.map((m) => compileTableSchema(m, opts)),
+    tables: scoped.map((m) => compileTableSchema(m, { schema: opts.schema, dependents })),
     enums: compileEnums(scoped),
     ...(opts.sequences?.length ? { sequences: compileSequences(opts.sequences) } : {}),
   };
@@ -577,7 +607,10 @@ export function fingerprintLiveAtVersion(
   // Thread the measured serial-sequence ACLs the way `fingerprintLive` does, so a v11 canon
   // recomputes the SAME hash the apply recorded. A retired canon that predates sequence ACLs
   // (v10) simply ignores the field — its self-contained copy never reads `sequenceGrants`.
-  return canon ? canon(snapshot, contract.tables, { ...opts, sequenceGrants: contract.sequenceGrants }) : null;
+  // The retired canons are frozen copies that key enums by the name they are handed, so they get
+  // the bare names they were written against (see `bareEnums`).
+  const bare: SchemaSnapshot = snapshot.enums ? { ...snapshot, enums: bareEnums(snapshot.enums) } : snapshot;
+  return canon ? canon(bare, contract.tables, { ...opts, sequenceGrants: contract.sequenceGrants }) : null;
 }
 
 // ---------------------------------------------------------------------------

package/src/cli/schema-introspect.ts

@@ -88,6 +88,8 @@ export interface CheckConstraint {
   name: string;
   /** The predicate text, as `pg_get_constraintdef` deparses it. */
   expr: string;
+  /** The name was DECLARED (`check(sql, { name })`), not positional — same rule as {@link IndexSchema.nameDeclared}. */
+  nameDeclared?: boolean;
 }
 
 /** A standalone index (NOT one backing a PK or UNIQUE constraint — those are excluded). */
@@ -123,6 +125,13 @@ export interface TableSchema {
   columns: ColumnSchema[];
   /** Primary-key column names (empty when the table has no PK). */
   primaryKey: string[];
+  /**
+   * The live primary key constraint's NAME — introspection's observation, absent on a compiled
+   * (declared) table and on a snapshot read before this field existed. The differ needs it to
+   * drop a key that is being replaced. It is NOT state: no fingerprint version hashes it, so a
+   * key under another name with the same columns is the same database.
+   */
+  primaryKeyName?: string;
   uniques: UniqueConstraint[];
   checks: CheckConstraint[];
   foreignKeys: ForeignKey[];
@@ -131,6 +140,7 @@ export interface TableSchema {
 
 /** A Postgres enum type — its name and its values in `enumsortorder` (the declared order). */
 export interface EnumType {
+  /** Bare for public (`post_status`), qualified otherwise (`analytics.post_status`). */
   name: string;
   values: string[];
 }
@@ -243,6 +253,55 @@ WHERE con.contype IN ('p', 'u', 'c', 'f')
 ORDER BY n.nspname, c.relname, con.conname;
 `.trim();
 
+/**
+ * Every foreign key's target, read from the CATALOG by `confrelid` (schema and table as separate
+ * names). db:pull reads it to declare an external target exactly. The FK IR carries the target as
+ * one dotted, quote-stripped string from the deparse (`refTable`), and that string is ambiguous:
+ * public."a.b" and a.b both read as `a.b`. The IR and the fingerprint keep that string; only the
+ * renderer, which has to split it into schema and table, needs this. Same scope as CONSTRAINTS_SQL.
+ */
+export const FK_TARGETS_SQL = `
+SELECT
+  n.nspname AS schema,
+  c.relname AS "table",
+  con.conname AS name,
+  rn.nspname AS ref_schema,
+  r.relname AS ref_table
+FROM pg_constraint con
+JOIN pg_class c ON c.oid = con.conrelid
+JOIN pg_namespace n ON n.oid = c.relnamespace
+JOIN pg_class r ON r.oid = con.confrelid
+JOIN pg_namespace rn ON rn.oid = r.relnamespace
+WHERE con.contype = 'f'
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+ORDER BY n.nspname, c.relname, con.conname;
+`.trim();
+
+export interface ForeignKeyTargetRow {
+  schema: unknown;
+  table: unknown;
+  name: unknown;
+  ref_schema: unknown;
+  ref_table: unknown;
+}
+
+/** The key a {@link foreignKeyTargets} map is read with: the owning table (qualified) and the FK name. */
+export function foreignKeyTargetKey(table: string, constraint: string): string {
+  const dot = table.indexOf('.');
+  const qualified = dot === -1 ? `public.${table}` : table;
+  return `${qualified}\u0000${constraint}`;
+}
+
+/** FK_TARGETS_SQL rows → (owning table, FK name) → the target's exact schema and table. */
+export function foreignKeyTargets(rows: readonly ForeignKeyTargetRow[]): Map<string, { schema: string; table: string }> {
+  const out = new Map<string, { schema: string; table: string }>();
+  for (const r of rows) {
+    out.set(foreignKeyTargetKey(`${String(r.schema)}.${String(r.table)}`, String(r.name)), { schema: String(r.ref_schema), table: String(r.ref_table) });
+  }
+  return out;
+}
+
 /**
  * Every enum type and its values, in `enumsortorder` (the order the values were declared,
  * which `CREATE TYPE` must reproduce). Extension-owned types are excluded via pg_depend,
@@ -615,9 +674,14 @@ export interface EnumRow {
   values: unknown;
 }
 
+/**
+ * The same identity rule as sequences and tables: public bare, non-public qualified. A bare
+ * name for every schema let a stray `analytics.post_status` satisfy the declared public
+ * `post_status`, so the plan never created the type the column actually needs.
+ */
 export function enumRowToDescriptor(row: EnumRow): EnumType {
   const values = Array.isArray(row.values) ? row.values.map(String) : [];
-  return { name: row.name, values };
+  return { name: row.schema === 'public' ? row.name : `${row.schema}.${row.name}`, values };
 }
 
 export interface SequenceRow {
@@ -687,7 +751,7 @@ export function assembleSchema(rows: SchemaRows): SchemaSnapshot {
     const t = tables.get(d.table);
     if (!t) continue; // a constraint on a table we didn't enumerate (e.g. a view)
     switch (d.kind) {
-      case 'primaryKey': t.primaryKey = d.columns ?? []; break;
+      case 'primaryKey': t.primaryKey = d.columns ?? []; t.primaryKeyName = d.name; break;
       case 'unique': t.uniques.push({ name: d.name, columns: d.columns ?? [] }); break;
       case 'check': t.checks.push({ name: d.name, expr: d.expr ?? '' }); break;
       case 'foreignKey':