@ultimat3/db 13.0.0 → 15.0.0

package/src/drift-findings.ts

@@ -0,0 +1,231 @@
+// Single responsibility: what a schema difference is CALLED and what its `fix:` line says — one
+// constructor per `DriftKind`, and nothing that compares anything. Split out of `drift.ts` at the
+// 500-line ceiling, along the seam that file already drew: comparison decides *whether* two
+// schemas disagree, and this decides how the disagreement reads.
+//
+// The rendered `X_DB_DRIFT` output is byte-for-byte pinned by the framework contract and
+// duplicated in `@ultimat3/entity` — do not reword a `cause` without changing both.
+//
+// Two rules run through every one of them. A `fix:` is a command the reader can RUN: `x db
+// migrate` where the migration has not been applied, and the statement itself where it has, since
+// re-running the migrator applies nothing a ledger row already claims. And a difference names the
+// declared side's own spelling, never the catalog's, because the catalog's is Postgres' rewriting.
+
+import { onDeleteRule, rebuildForeignKey } from './foreign-key';
+import type { CheckDescription, ForeignKeyDescription } from './introspect';
+import type { Migration } from './migrate';
+
+export type DriftKind =
+  | 'unexpected-column'
+  | 'missing-column'
+  | 'changed-column'
+  | 'unexpected-table'
+  | 'missing-table'
+  | 'unknown-schema'
+  | 'missing-index'
+  | 'changed-index'
+  | 'missing-check'
+  | 'missing-foreign-key'
+  | 'changed-foreign-key';
+
+export interface DriftDifference {
+  readonly kind: DriftKind;
+  readonly table: string;
+  readonly column: string | null;
+  readonly cause: string;
+  readonly fix: string;
+}
+
+export interface DriftReport {
+  readonly ok: boolean;
+  readonly differences: readonly DriftDifference[];
+}
+
+export function unexpectedColumn(table: string, column: string): DriftDifference {
+  return {
+    kind: 'unexpected-column',
+    table,
+    column,
+    // Pinned by the contract. Do not reword without changing docs/errors/X_DB_DRIFT.
+    cause: `table "${table}" has column "${column}" not present in any migration`,
+    fix: `x db gen "add ${column}"`,
+  };
+}
+
+export function missingColumn(table: string, column: string): DriftDifference {
+  return {
+    kind: 'missing-column',
+    table,
+    column,
+    cause: `table "${table}" is missing column "${column}" that migrations declare`,
+    fix: 'x db migrate',
+  };
+}
+
+/**
+ * The column exists on both sides and one of them lets it be `NULL`.
+ *
+ * This is the finding the expand/contract flow needs and never had. `generate.ts` emits a `NOT
+ * NULL` add as nullable plus a `-- backfill "c", then: … set not null;` comment, because the
+ * strict version cannot succeed on a populated table — and phase 2 is a comment, so it is a thing
+ * a human has to remember. Nobody did, and `compareTable` compared columns by name and by type
+ * while `snapshotOf` had recorded `nullable` all along, so the column stayed nullable forever
+ * against an entity schema that said otherwise, with `ok: true` on every check. The first
+ * `undefined` write then lands as `NULL` and crashes three services away from the migration.
+ *
+ * `x db gen` is deliberately not the fix: it diffs types and indexes and has never emitted a
+ * `set not null`, so naming it would send a reader to a command that generates an empty migration.
+ */
+export function changedColumn(
+  table: string,
+  column: string,
+  liveNullable: boolean,
+): DriftDifference {
+  const clause = liveNullable ? 'set not null' : 'drop not null';
+  return {
+    kind: 'changed-column',
+    table,
+    column,
+    cause: liveNullable
+      ? `table "${table}" allows NULL in column "${column}" that migrations declare not null`
+      : `table "${table}" forbids NULL in column "${column}" that migrations declare nullable`,
+    fix:
+      `alter table "${table}" alter column "${column}" ${clause};   # in a new migration` +
+      (liveNullable ? ' — backfill the existing NULLs first' : ''),
+  };
+}
+
+export function unexpectedTable(table: string): DriftDifference {
+  return {
+    kind: 'unexpected-table',
+    table,
+    column: null,
+    cause: `table "${table}" is not present in any migration`,
+    fix: `x db gen "add ${table}"`,
+  };
+}
+
+export function missingTable(table: string): DriftDifference {
+  return {
+    kind: 'missing-table',
+    table,
+    column: null,
+    cause: `table "${table}" is declared by migrations but does not exist`,
+    fix: 'x db migrate',
+  };
+}
+
+/**
+ * Not a difference between two schemas but the absence of one to compare against — reported
+ * through the same channel so it reaches an operator, since a check that quietly answered "clean"
+ * because it had nothing to check is the one failure mode drift detection cannot have.
+ */
+export function unknownSchema(migrations: readonly Migration[]): DriftDifference {
+  const newest = [...migrations].sort((a, b) => (a.id < b.id ? -1 : 1)).at(-1);
+  return {
+    kind: 'unknown-schema',
+    table: '',
+    column: null,
+    cause:
+      `migration "${newest?.id ?? ''}" records no schema snapshot, so what this database owes ` +
+      'cannot be established',
+    // The same two remedies `X_MIGRATION_SNAPSHOT_MISSING` names, in the same order, because it is
+    // the same condition. It used to lead with `x db gen`, which raises that error and whose own
+    // fix pointed back here — a cycle a scaffolded app hit on its first `x db migrate`. The
+    // pathspec is a glob because this package is tier 1: only `@ultimat3/cli` knows the directory.
+    fix:
+      `git checkout -- "*${newest?.id ?? ''}.snapshot.json"   # or, if it was never written: ` +
+      `delete migration "${newest?.id ?? ''}" and rerun x db gen "${newest?.name ?? 'initial'}"`,
+  };
+}
+
+export function missingIndex(table: string, index: string): DriftDifference {
+  return {
+    kind: 'missing-index',
+    table,
+    column: null,
+    cause: `table "${table}" is missing index "${index}" that migrations declare`,
+    fix: 'x db migrate',
+  };
+}
+
+export function changedIndex(table: string, index: string, detail: string): DriftDifference {
+  return {
+    kind: 'changed-index',
+    table,
+    column: null,
+    cause: `index "${index}" on "${table}" ${detail}, not what migrations declare`,
+    fix: 'x db migrate',
+  };
+}
+
+/**
+ * A CHECK a migration declares and the catalog does not hold.
+ *
+ * There is no `changed-check` beside it and there never will be, for the reason
+ * `IndexDescription.where` gives: `pg_get_constraintdef` answers Postgres' own rewriting —
+ * `status in ('draft','published')` reads back as `CHECK ((status = ANY (ARRAY['draft'::text,
+ * 'published'::text])))` — so a text comparison reports drift on a correct database forever, and
+ * normalising it is an expression parser competing with the server's. Presence is not text.
+ *
+ * The `fix` is the statement, not `x db migrate`: the migration that declares this constraint is
+ * already in the ledger, so re-running the migrator applies nothing. Same reasoning as
+ * `changedColumn` and `changedForeignKey` — the declared side holds the author's own spelling of
+ * the predicate, which is what makes an executable fix possible at all.
+ */
+export function missingCheck(table: string, check: CheckDescription): DriftDifference {
+  return {
+    kind: 'missing-check',
+    table,
+    column: null,
+    cause: `table "${table}" is missing check constraint "${check.name}" that migrations declare`,
+    // The command rides on the same line as the statement, and not only because `check` is a
+    // banned advice word the `errors` gate demands a command beside: writing the migration is half
+    // the repair and applying it is the other half, and `changedColumn`'s bare `# in a new
+    // migration` leaves the second half to be guessed.
+    fix:
+      `alter table "${table}" add constraint "${check.name}" ` +
+      `check (${check.expression});   # in a new migration, then x db migrate`,
+  };
+}
+
+export function missingForeignKey(table: string, key: ForeignKeyDescription): DriftDifference {
+  return {
+    kind: 'missing-foreign-key',
+    table,
+    column: null,
+    cause:
+      `table "${table}" has no foreign key on (${key.columns.join(', ')}) to ` +
+      `"${key.referencedTable}" (${key.referencedColumns.join(', ')}) that migrations declare`,
+    fix: 'x db migrate',
+  };
+}
+
+/**
+ * The key points where it was declared to point and one side's `on delete` rule is not the other's
+ * — reported apart from `missing-foreign-key` because it is a different repair: the constraint is
+ * there, and what changed is what happens to the child rows.
+ *
+ * The `fix` is the pair, not `x db migrate`: a rule cannot be altered in place, `add constraint`
+ * alone is `42710` on a name already taken, and no `x db gen` diff emits either statement, so
+ * naming a command would send a reader to one that generates an empty migration. Same reasoning
+ * as `changedColumn`.
+ */
+export function changedForeignKey(
+  table: string,
+  declared: ForeignKeyDescription,
+  held: ForeignKeyDescription,
+): DriftDifference {
+  const rule = onDeleteRule(held.onDelete);
+  return {
+    kind: 'changed-foreign-key',
+    table,
+    column: null,
+    cause:
+      `foreign key on "${table}" (${declared.columns.join(', ')}) to ` +
+      `"${declared.referencedTable}" ` +
+      `${rule === null ? 'declares no on delete rule' : `is on delete ${rule}`}, not what ` +
+      'migrations declare',
+    fix: `${rebuildForeignKey(table, declared, held)}   # in a new migration`,
+  };
+}

package/src/drift.ts

@@ -4,200 +4,35 @@
 // by the framework contract; `x verify` fails on it and `--json` carries every difference.
 
 import { baseClient, type DbClient } from './client';
+import type { DriftDifference } from './drift-findings';
+import {
+  changedColumn,
+  changedForeignKey,
+  changedIndex,
+  missingCheck,
+  missingColumn,
+  missingForeignKey,
+  missingIndex,
+  missingTable,
+  unexpectedColumn,
+  unexpectedTable,
+  unknownSchema,
+} from './drift-findings';
 import { DbError } from './errors';
-import { addForeignKey, dropForeignKey, foreignKeyTarget, onDeleteRule } from './foreign-key';
+import { foreignKeyTarget, onDeleteRule } from './foreign-key';
 import { indexMethodOf } from './index-method';
-import {
-  type ForeignKeyDescription,
-  findTable,
-  introspect,
-  type SchemaDescription,
-  type TableDescription,
-} from './introspect';
+import { findTable, introspect, type SchemaDescription, type TableDescription } from './introspect';
 import { type LedgerRow, type Migration, readLedger } from './migrate';
 
-export type DriftKind =
-  | 'unexpected-column'
-  | 'missing-column'
-  | 'changed-column'
-  | 'unexpected-table'
-  | 'missing-table'
-  | 'unknown-schema'
-  | 'missing-index'
-  | 'changed-index'
-  | 'missing-foreign-key'
-  | 'changed-foreign-key';
-
-export interface DriftDifference {
-  readonly kind: DriftKind;
-  readonly table: string;
-  readonly column: string | null;
-  readonly cause: string;
-  readonly fix: string;
-}
+// Re-exported explicitly, never `export *`: `src/index.ts` publishes both from `'./drift'`, so the
+// split is invisible to `@ultimat3/db`'s public surface and no consumer moves with it.
+export type { DriftDifference, DriftKind } from './drift-findings';
 
 export interface DriftReport {
   readonly ok: boolean;
   readonly differences: readonly DriftDifference[];
 }
 
-function unexpectedColumn(table: string, column: string): DriftDifference {
-  return {
-    kind: 'unexpected-column',
-    table,
-    column,
-    // Pinned by the contract. Do not reword without changing docs/errors/X_DB_DRIFT.
-    cause: `table "${table}" has column "${column}" not present in any migration`,
-    fix: `x db gen "add ${column}"`,
-  };
-}
-
-function missingColumn(table: string, column: string): DriftDifference {
-  return {
-    kind: 'missing-column',
-    table,
-    column,
-    cause: `table "${table}" is missing column "${column}" that migrations declare`,
-    fix: 'x db migrate',
-  };
-}
-
-/**
- * The column exists on both sides and one of them lets it be `NULL`.
- *
- * This is the finding the expand/contract flow needs and never had. `generate.ts` emits a `NOT
- * NULL` add as nullable plus a `-- backfill "c", then: … set not null;` comment, because the
- * strict version cannot succeed on a populated table — and phase 2 is a comment, so it is a thing
- * a human has to remember. Nobody did, and `compareTable` compared columns by name and by type
- * while `snapshotOf` had recorded `nullable` all along, so the column stayed nullable forever
- * against an entity schema that said otherwise, with `ok: true` on every check. The first
- * `undefined` write then lands as `NULL` and crashes three services away from the migration.
- *
- * `x db gen` is deliberately not the fix: it diffs types and indexes and has never emitted a
- * `set not null`, so naming it would send a reader to a command that generates an empty migration.
- */
-function changedColumn(table: string, column: string, liveNullable: boolean): DriftDifference {
-  const clause = liveNullable ? 'set not null' : 'drop not null';
-  return {
-    kind: 'changed-column',
-    table,
-    column,
-    cause: liveNullable
-      ? `table "${table}" allows NULL in column "${column}" that migrations declare not null`
-      : `table "${table}" forbids NULL in column "${column}" that migrations declare nullable`,
-    fix:
-      `alter table "${table}" alter column "${column}" ${clause};   # in a new migration` +
-      (liveNullable ? ' — backfill the existing NULLs first' : ''),
-  };
-}
-
-function unexpectedTable(table: string): DriftDifference {
-  return {
-    kind: 'unexpected-table',
-    table,
-    column: null,
-    cause: `table "${table}" is not present in any migration`,
-    fix: `x db gen "add ${table}"`,
-  };
-}
-
-function missingTable(table: string): DriftDifference {
-  return {
-    kind: 'missing-table',
-    table,
-    column: null,
-    cause: `table "${table}" is declared by migrations but does not exist`,
-    fix: 'x db migrate',
-  };
-}
-
-/**
- * Not a difference between two schemas but the absence of one to compare against — reported
- * through the same channel so it reaches an operator, since a check that quietly answered "clean"
- * because it had nothing to check is the one failure mode drift detection cannot have.
- */
-function unknownSchema(migrations: readonly Migration[]): DriftDifference {
-  const newest = [...migrations].sort((a, b) => (a.id < b.id ? -1 : 1)).at(-1);
-  return {
-    kind: 'unknown-schema',
-    table: '',
-    column: null,
-    cause:
-      `migration "${newest?.id ?? ''}" records no schema snapshot, so what this database owes ` +
-      'cannot be established',
-    // The same two remedies `X_MIGRATION_SNAPSHOT_MISSING` names, in the same order, because it is
-    // the same condition. It used to lead with `x db gen`, which raises that error and whose own
-    // fix pointed back here — a cycle a scaffolded app hit on its first `x db migrate`. The
-    // pathspec is a glob because this package is tier 1: only `@ultimat3/cli` knows the directory.
-    fix:
-      `git checkout -- "*${newest?.id ?? ''}.snapshot.json"   # or, if it was never written: ` +
-      `delete migration "${newest?.id ?? ''}" and rerun x db gen "${newest?.name ?? 'initial'}"`,
-  };
-}
-
-function missingIndex(table: string, index: string): DriftDifference {
-  return {
-    kind: 'missing-index',
-    table,
-    column: null,
-    cause: `table "${table}" is missing index "${index}" that migrations declare`,
-    fix: 'x db migrate',
-  };
-}
-
-function changedIndex(table: string, index: string, detail: string): DriftDifference {
-  return {
-    kind: 'changed-index',
-    table,
-    column: null,
-    cause: `index "${index}" on "${table}" ${detail}, not what migrations declare`,
-    fix: 'x db migrate',
-  };
-}
-
-function missingForeignKey(table: string, key: ForeignKeyDescription): DriftDifference {
-  return {
-    kind: 'missing-foreign-key',
-    table,
-    column: null,
-    cause:
-      `table "${table}" has no foreign key on (${key.columns.join(', ')}) to ` +
-      `"${key.referencedTable}" (${key.referencedColumns.join(', ')}) that migrations declare`,
-    fix: 'x db migrate',
-  };
-}
-
-/**
- * The key points where it was declared to point and one side's `on delete` rule is not the other's
- * — reported apart from `missing-foreign-key` because it is a different repair: the constraint is
- * there, and what changed is what happens to the child rows.
- *
- * The `fix` is the pair, not `x db migrate`: a rule cannot be altered in place, `add constraint`
- * alone is `42710` on a name already taken, and no `x db gen` diff emits either statement, so
- * naming a command would send a reader to one that generates an empty migration. Same reasoning
- * as `changedColumn`.
- */
-function changedForeignKey(
-  table: string,
-  declared: ForeignKeyDescription,
-  held: ForeignKeyDescription,
-): DriftDifference {
-  const rule = onDeleteRule(held.onDelete);
-  return {
-    kind: 'changed-foreign-key',
-    table,
-    column: null,
-    cause:
-      `foreign key on "${table}" (${declared.columns.join(', ')}) to ` +
-      `"${declared.referencedTable}" ` +
-      `${rule === null ? 'declares no on delete rule' : `is on delete ${rule}`}, not what ` +
-      'migrations declare',
-    fix:
-      `${dropForeignKey(table, held.name)} ${addForeignKey(table, declared)}` +
-      '   # in a new migration',
-  };
-}
-
 /**
  * Indexes migrations declare, against the ones the catalog holds — by column list and by
  * uniqueness, which is what caught a composite index rebuilt with its columns the other way round
@@ -316,6 +151,33 @@ function compareForeignKeys(live: TableDescription, expected: TableDescription):
   return differences;
 }
 
+/**
+ * CHECK constraints migrations declare, against the NAMES the catalog holds — `checkNames`, which
+ * is a separate field from `checks` precisely so this comparison cannot reach a definition it must
+ * not read (`introspect.ts`).
+ *
+ * Two absences, and they mean opposite things. `expected.checks` absent is a sidecar written
+ * before constraints were recorded: it declares nothing, so nothing can be missing. `live.checkNames`
+ * absent is a description that never asked the catalog — a stub, a fake client's rows, a
+ * `TableDescription` built by hand — and reading that as "the database holds none" is one finding
+ * per declared constraint against a database nobody looked at. `introspect()` always answers with
+ * the field, `[]` included, so a real read is never mistaken for an unread one.
+ *
+ * Only the declared side is judged, the rule `compareIndexes` and `compareForeignKeys` both state:
+ * a NOT NULL, an `enumerated()` column's old anonymous form, a constraint an extension brought and
+ * every hand-written CHECK an app has ever added would each be a finding against a database that
+ * is exactly right.
+ */
+function compareChecks(live: TableDescription, expected: TableDescription): DriftDifference[] {
+  const declared = expected.checks;
+  const held = live.checkNames;
+  if (declared === undefined || held === undefined) return [];
+  const present = new Set(held);
+  return declared
+    .filter((check) => !present.has(check.name))
+    .map((check) => missingCheck(live.name, check));
+}
+
 /**
  * A primary key column is `NOT NULL` in the catalog whether or not anything declared it — Postgres
  * adds the constraint with the key. Both sides are therefore read through the union of the two
@@ -352,6 +214,7 @@ function compareTable(live: TableDescription, expected: TableDescription): Drift
     }
   }
   differences.push(...compareIndexes(live, expected));
+  differences.push(...compareChecks(live, expected));
   differences.push(...compareForeignKeys(live, expected));
   return differences;
 }

package/src/entity-shape.ts

@@ -2,6 +2,7 @@
 // tier 1 and may never import `entity` (tier 2), so a snapshot arrives as a parameter and every
 // part of it — a column's `on delete` rule included — crosses the seam by shape or not at all.
 
+import type { ColumnDefaultLike } from './column-default';
 import type { IndexMethod } from './index-method';
 
 /** Structurally assignment-compatible with `@ultimat3/entity`'s `ColumnDescription`. */
@@ -32,6 +33,45 @@ export interface ColumnDescriptionLike {
    * was a `23502`, because nothing computed it.
    */
   readonly generated?: string | undefined;
+  /**
+   * What the column defaults to, when the declaration carries the value and not only the flag.
+   * Optional for the reason `onDelete` and `generated` are: this package cannot import
+   * `@ultimat3/entity`, so a field that is not on the projection reaches no DDL at all.
+   *
+   * `hasDefault` beside it is NOT redundant and is not being replaced. It is the older, narrower
+   * fact — "this column defaults to something" — and it is what `generatedClause` reads to refuse
+   * a column that is both generated and defaulted. Where `hasDefault` is true and this is absent,
+   * `defaultExpression` falls back to the two defaults inferable from the kind and everything else
+   * is REPORTED as unrendered rather than dropped (`unrendered.ts`).
+   */
+  readonly default?: ColumnDefaultLike | undefined;
+}
+
+/**
+ * Structurally assignment-compatible with `@ultimat3/entity`'s `InvariantDescription`.
+ *
+ * An invariant is written once and enforced twice — in the app on every write, and in Postgres as
+ * a CHECK or a unique index. The second half reached no SQL at all until 2026-08-25, because this
+ * mirror had no `invariants` field: a regenerated migration silently held none of them, including
+ * the composite UNIQUE that `upsertAll`'s `on conflict` is inferred against, so a replay-safe
+ * write became a duplicate row on a database the framework itself generated.
+ */
+export interface InvariantDescriptionLike {
+  /** The rule's own name. `<table>_<name>_check` / `_key` is the constraint it becomes. */
+  readonly name: string;
+  /** `assert` is a rule only the app can run — no SQL, and nothing for a migration to emit. */
+  readonly kind: 'check' | 'unique' | 'assert';
+  readonly message: string;
+  /** The predicate for a `check`, the column list for a `unique`, `null` for an `assert`. */
+  readonly sql: string | null;
+  /** Partial-constraint predicate, e.g. `deleted_at is null`. `null` covers every row. */
+  readonly where: string | null;
+  /**
+   * The physical columns a `unique` names, when the declaration carries them. Optional, and
+   * `uniqueColumns()` falls back to splitting `sql` when it is absent — see the argument in
+   * `invariant-ddl.ts` for why that fallback is a validated re-read and not a name parsed back.
+   */
+  readonly columns?: readonly string[] | undefined;
 }
 
 /**
@@ -66,4 +106,10 @@ export interface EntityDescriptionLike {
   readonly primaryKey: readonly string[];
   readonly columns: readonly ColumnDescriptionLike[];
   readonly indexes: readonly IndexDescriptionLike[];
+  /**
+   * The domain rules the database must hold too. Optional so no existing description changes
+   * shape, exactly as `onDelete`, `generated` and `using` are — and absent reads as "declares
+   * none", which is what every hand-built description in this package's own tests is.
+   */
+  readonly invariants?: readonly InvariantDescriptionLike[] | undefined;
 }

package/src/foreign-key-plan.ts

@@ -5,6 +5,7 @@
 import type { EntityDescriptionLike } from './entity-shape';
 import { addForeignKey, dropForeignKey, foreignKeyTarget, onDeleteRule } from './foreign-key';
 import type { ForeignKeyDescription, TableDescription } from './introspect';
+import { identifier } from './sql';
 
 /** The two directions of one migration, pushed in `up` order; `down` is reversed at assembly. */
 export interface Plan {
@@ -137,10 +138,17 @@ export interface ConstraintPlans {
   readonly doomed: ReadonlySet<string>;
 }
 
-/** A key whose target is being dropped: gone on the way up, a note on the way back. */
+/**
+ * A key whose target is being dropped: gone on the way up, a note on the way back.
+ *
+ * The note goes through `identifier` too. A `--` comment ends at the first newline, so a name
+ * holding one is a second command on the line after it — the same escape `columnClause` closed,
+ * one quoting rule short of the statement above it.
+ */
 function unrestorableDrop(table: string, constraint: string, target: string, preDrops: Plan): void {
   preDrops.up.push(dropForeignKey(table, constraint));
   preDrops.down.push(
-    `-- constraint "${constraint}" on "${table}" cannot be restored; "${target}" is gone`,
+    `-- constraint ${identifier(constraint).text} on ${identifier(table).text} ` +
+      `cannot be restored; ${identifier(target).text} is gone`,
   );
 }

package/src/foreign-key.ts

@@ -4,6 +4,7 @@
 
 import { assert } from '@ultimat3/core';
 import type { ForeignKeyDescription } from './introspect';
+import { identifier } from './sql';
 
 /**
  * `pg_constraint.confdeltype`. The catalog's vocabulary; a description holds the rule's name.
@@ -51,7 +52,16 @@ export function foreignKeyTarget(key: ForeignKeyDescription): string {
   return JSON.stringify([[...key.columns], key.referencedTable, [...key.referencedColumns]]);
 }
 
-const quoted = (names: readonly string[]): string => names.map((name) => `"${name}"`).join(', ');
+/**
+ * Through `identifier`, never `"${…}"` — the package's one rule, which every name this file writes
+ * now goes through. A name that closes its own quote produced a real `drop table` through
+ * `generateMigration` once already, out of `columnClause`, and every name below arrives the same
+ * way: from a projection this package cannot typecheck, or from a `.snapshot.json` on disk that
+ * anything may edit. Being unreachable with a hostile name today is a property of the CALLERS, not
+ * of this file, and it survives exactly until the next refactor.
+ */
+const quoted = (names: readonly string[]): string =>
+  names.map((name) => identifier(name).text).join(', ');
 
 /**
  * A statement of its own, never a clause inside `create table`. Inline, the constraint is created
@@ -76,14 +86,48 @@ export function addForeignKey(table: string, key: ForeignKeyDescription): string
     `references(() => target.id, { onDelete: 'cascade' })   # cascade | restrict | set null`,
   );
   return (
-    `alter table "${table}" add constraint "${key.name}" ` +
+    `alter table ${identifier(table).text} add constraint ${identifier(key.name).text} ` +
     `foreign key (${quoted(key.columns)}) ` +
-    `references "${key.referencedTable}" (${quoted(key.referencedColumns)})` +
+    `references ${identifier(key.referencedTable).text} (${quoted(key.referencedColumns)})` +
     `${rule === null ? '' : ` on delete ${rule}`};`
   );
 }
 
 /** The reverse. Dropping a constraint loses nothing the database cannot rebuild. */
 export function dropForeignKey(table: string, constraint: string): string {
-  return `alter table "${table}" drop constraint "${constraint}";`;
+  return `alter table ${identifier(table).text} drop constraint ${identifier(constraint).text};`;
+}
+
+/**
+ * The drop/add pair that moves a key's `on delete` rule — a rebuild, because Postgres has no
+ * `alter constraint` for it — for a `fix:` line an author pastes into a new migration.
+ *
+ * It lives here, beside the two writers, because it is the one caller reading values neither of
+ * them may assume: `held` is the **live catalog's** and `declared` is a `.snapshot.json`'s. Both
+ * writers refuse rather than guess — `identifier()` on a name holding a quote, a space or a
+ * backslash (all three legal inside a quoted Postgres name), and `addForeignKey` on an `on delete`
+ * rule Postgres does not have. That is exactly right for DDL this package SENDS and wrong for a
+ * `fix:` line: `diffSchema` is documented pure and total, so a pair it cannot write is a sentence,
+ * never a throw — a drift check that raises in place of its report hands the caller an exception
+ * where a verdict was asked for. The constraint is still named, because it is the only thing
+ * identifying which one, quoted by `JSON.stringify`, which escapes rather than refuses; nothing
+ * runs this string either way.
+ */
+export function rebuildForeignKey(
+  table: string,
+  declared: ForeignKeyDescription,
+  held: ForeignKeyDescription,
+): string {
+  // The writers are ASKED whether they can write the pair — never a second copy of their rules
+  // beside them, which is the copy that drifts. A refusal is the answer, and nothing here reads
+  // the thrown value.
+  try {
+    return `${dropForeignKey(table, held.name)} ${addForeignKey(table, declared)}`;
+  } catch {
+    return (
+      `drop constraint ${JSON.stringify(held.name)} on table ${JSON.stringify(table)} and add ` +
+      'it back with the on delete rule the migrations declare — by hand: x db gen cannot ' +
+      'write this pair'
+    );
+  }
 }