@everystack/cli 0.4.100 → 0.4.102

package/src/cli/schema-diff.ts

@@ -74,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
@@ -86,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 }
@@ -227,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 {
@@ -413,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.
  */
@@ -427,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[] = [];
@@ -511,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) {
@@ -527,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);
   }
 
@@ -588,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,
   ];
@@ -746,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)) {
@@ -757,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));
@@ -770,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;
     }
 
@@ -779,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 });
@@ -931,15 +1032,34 @@ function diffConstraints(d: TableSchema, c: TableSchema, dropConstraints: Schema
   }
 
   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) });
 }
 
 // ---------------------------------------------------------------------------
@@ -947,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, "''")}'`;
@@ -1110,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);
@@ -1126,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':
@@ -1157,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}` : '';

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

@@ -125,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[];
@@ -133,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[];
 }
@@ -245,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,
@@ -617,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 {
@@ -689,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':

package/src/cli/schema-source.ts

@@ -16,17 +16,28 @@
  *  - Cross-schema FKs (e.g. `profiles.id → auth.users.id`) are OMITTED — the model
  *    can't express a reference to a non-Model table, so neither can the emitter.
  *  - `relationName` strings are synthesized deterministically (the `Relation` type
- *    carries no name); only the pairing of a belongsTo with its inverse hasMany
- *    matters, which the synthesis guarantees.
+ *    carries no name); only the pairing of a belongsTo with its inverse hasMany or
+ *    hasOne matters, which the synthesis guarantees. A hasOne renders as `one(target)`.
  *
  * Pure and deterministic: imports sorted, declarations in model order, relation
  * keys in declared order — re-running on the same models is byte-identical.
  *
- * Input is a `@everystack/model` ModelDescriptor (type-only — no runtime dep).
+ * Input is a `@everystack/model` ModelDescriptor. The one runtime import is
+ * `relationDeleteActions`: a parent's hasMany `dependent` sets a child FK's onDelete, derived
+ * from the set passed in (pure; no spec is written).
  */
 
-import type { ModelDescriptor, FieldSpec, DerivedDescriptor, ViewDescriptor, MaterializedViewDescriptor } from '@everystack/model';
+import { relationDeleteActions, type ModelDescriptor, type ReferentialAction, type Relation, type FieldSpec, type DerivedDescriptor, type ViewDescriptor, type MaterializedViewDescriptor } from '@everystack/model';
 import { parseQualified } from './derived-source';
+import { commentText } from './ts-template';
+
+/**
+ * Drizzle relations carry no order, limit or filter, so `db.query.x.findMany({ with })` ignores a
+ * relation's display options and a hasOne returns any one matching row. Each such relation gets
+ * one note above it; a relation that declares none gets nothing (D8: byte-identical).
+ */
+const DISPLAY_NOTE = 'display options (where/limit/orderBy) are not applied by drizzle `with`: filter in the query';
+const HAS_ONE_NOTE = 'hasOne: drizzle `with` returns any one matching row (orderBy and where are not applied): order and filter in the query';
 
 /** `author_id` is the SQL identifier; `authorId` the field key. The single snake-case rule. */
 function toSnakeCase(name: string): string {
@@ -182,7 +193,7 @@ function columnModifiers(
   spec: FieldSpec,
   isComposite: boolean,
   modelsByDescriptor: Map<ModelDescriptor, { camel: string }>,
-  ctx: { builder?: string; self?: ModelDescriptor; usedTypes?: Set<string> } = {},
+  ctx: { builder?: string; self?: ModelDescriptor; usedTypes?: Set<string>; onDelete?: ReferentialAction } = {},
 ): string {
   let s = '';
   if (spec.isArray) s += '.array()';
@@ -208,7 +219,9 @@ function columnModifiers(
     if (entry) {
       const parentPk = primaryKeyKey(target);
       const opts: string[] = [];
-      if (spec.onDelete) opts.push(`onDelete: ${strLiteral(spec.onDelete)}`);
+      // A parent's hasMany `dependent` (ctx.onDelete, derived from the set) or the child's own.
+      const onDelete = ctx.onDelete ?? spec.onDelete;
+      if (onDelete) opts.push(`onDelete: ${strLiteral(onDelete)}`);
       if (spec.onUpdate) opts.push(`onUpdate: ${strLiteral(spec.onUpdate)}`);
       const optsText = opts.length ? `, { ${opts.join(', ')} }` : '';
       // A SELF-referential FK needs drizzle's documented return-type annotation. Without it
@@ -302,7 +315,7 @@ function planRelationNames(models: ModelDescriptor[]): RelationNaming {
 /** The `relationName: '…'` fragment for a relation, or '' when the pair is unambiguous. */
 function relationNameFragment(
   model: ModelDescriptor,
-  rel: { kind: 'belongsTo' | 'hasMany'; column: string; target: () => ModelDescriptor },
+  rel: Pick<Relation, 'kind' | 'column' | 'target'>,
   naming: RelationNaming,
 ): string {
   const other = rel.target().table;
@@ -348,6 +361,8 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
   // generated schema. (The migration generator still emits its SQL + authz.) The
   // command and the drift guard both call this, so filtering here keeps them in sync.
   const models = allModels.filter((m) => !m.private);
+  // Over the whole set, private models included: a hasMany `dependent` sets a child FK's ON DELETE.
+  const dependents = relationDeleteActions(allModels);
   const derivedRelations = typedRelations(_opts.derived ?? []);
 
   const modelsByDescriptor = new Map<ModelDescriptor, { camel: string }>();
@@ -396,7 +411,7 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
       const { call, builder: pgBuilder } = baseColumnSource(toSnakeCase(key), spec);
       pgCoreBuilders.add(pgBuilder);
       if (spec.defaultKind === 'sql') pgCoreBuilders.add('sql'); // imported from 'drizzle-orm', handled below
-      const mods = columnModifiers(spec, isComposite, modelsByDescriptor, { builder: pgBuilder, self: model, usedTypes: pgCoreTypes });
+      const mods = columnModifiers(spec, isComposite, modelsByDescriptor, { builder: pgBuilder, self: model, usedTypes: pgCoreTypes, onDelete: dependents.get(model)?.get(key) });
       if (spec.isDeprecated) {
         // The contract phase (decision 13): the column stays in the database and
         // stays readable; the strikethrough warns new code away at author time.
@@ -452,7 +467,7 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
     if (relEntries.length === 0) continue;
     const camel = modelCamel(model);
 
-    const usesOne = relEntries.some(([, r]) => r.kind === 'belongsTo');
+    const usesOne = relEntries.some(([, r]) => r.kind === 'belongsTo' || r.kind === 'hasOne');
     const usesMany = relEntries.some(([, r]) => r.kind === 'hasMany');
     const helpers = [usesOne ? 'one' : null, usesMany ? 'many' : null].filter(Boolean).join(', ');
 
@@ -461,6 +476,8 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
       const target = rel.target();
       const targetCamel = modelCamel(target);
       const nameFrag = relationNameFragment(model, rel, relationNaming);
+      if (rel.kind === 'hasOne') lines.push(`  // ${commentText(HAS_ONE_NOTE)}`);
+      else if (rel.orderBy !== undefined || rel.limit !== undefined || rel.where !== undefined) lines.push(`  // ${commentText(DISPLAY_NOTE)}`);
       if (rel.kind === 'belongsTo') {
         // belongsTo(() => Target, column, references?) -> one(...)
         const thisCol = rel.column; // FK FIELD KEY on this model
@@ -468,6 +485,20 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
         lines.push(
           `  ${key}: one(${targetCamel}, { fields: [${camel}.${thisCol}], references: [${targetCamel}.${targetPk}]${nameFrag} }),`,
         );
+      } else if (rel.kind === 'hasOne') {
+        // hasOne(() => Target, column) -> one(Target): the inverse of the target's belongsTo, as
+        // many(Target) is for a hasMany. Drizzle takes fields/references from that belongsTo, and
+        // a one() with no fields is typed nullable (a parent may have no such row). Its orderBy
+        // and where are display options with no drizzle form; F10 applies them per query.
+        // Drizzle's one() config requires fields, so a relationName alone is not an option: a
+        // pair joined by more than one FK is refused by name rather than emitted broken.
+        if (nameFrag) {
+          const at = model.schema === 'public' ? model.table : `${model.schema}.${model.table}`;
+          throw new Error(
+            `model '${at}': relation '${key}': a hasOne between two tables joined by more than one foreign key is not supported yet (${model.table} and ${target.table})`,
+          );
+        }
+        lines.push(`  ${key}: one(${targetCamel}),`);
       } else {
         // hasMany(() => Target, column, references?) -> many(...)
         if (nameFrag) {