@ultimat3/db 9.0.0 → 11.0.0

package/CLAUDE.md

@@ -137,6 +137,16 @@ that would start attempt two answers `25P01 ROLLBACK TO SAVEPOINT can only be us
 blocks`. There is nothing to retry into, and an author who believes they hold a budget they do not
 is worse off than one who is told.
 
+**`BEGIN` re-derives its isolation level from the closed set, `As of 2026-08-23`.** `BEGIN` takes
+no parameters, so `beginStatement` is one of the two statements here built as TEXT — and the level
+was `options.isolation.toUpperCase()` spliced into it. The TYPE is not the guard: the value reaches
+`withTransaction` from an app's config, a JSON body or a CLI flag, and
+`{ isolation: 'read committed; drop table x; --' }` became exactly that statement while a
+non-string became an uncoded `TypeError` inside a template literal. `isolationMode` is a `switch`
+over `IsolationLevel` whose `default` arm is `never` — a fourth level with no SQL beside it is a
+type error, and anything else at runtime is `X_SQL_UNSAFE` (`isolationLevelInvalid`), the code
+`branchNameInvalid` already uses for a value spliced into a statement.
+
 **The migration lock is polled, never waited on.** `pg_advisory_lock` blocks with no timeout, so a
 predecessor OOM-killed on a network partition kept its backend — and the lock — for hours while the
 new `ROLE=migrate` pod sat inside one statement printing nothing: `helm upgrade --wait` blocked on a
@@ -547,13 +557,35 @@ app: `create table "comments" (… references "posts" …)` before `create table
 `relation "posts" does not exist`. `down` had the mirror fault — `drop table "posts"` while
 `comments` still referenced it is `2BP01`. So `foreignKeyPlan` collects every key into a bucket of
 its own, merged into the plan **after** every table statement; `down` is reversed as a whole, so the
-drops pushed last there come out first. No topological sort and **no cycle error**: two tables
-referencing each other cannot be expressed inline in any order, and separate constraints need no
-order at all. The same call site answers the other half — a `references()` added to a column that
+drops pushed last there come out first. No topological sort and **no cycle error** *for adds*: two
+tables referencing each other cannot be expressed inline in any order, and separate constraints need
+no order at all. Dropping is not symmetrical and does need one — the paragraph below. The same call site answers the other half — a `references()` added to a column that
 already exists now emits its `add constraint`, where before `up` came out **empty**, `x db gen`
 wrote no file, and `x verify`'s drift step stayed red forever with `x db gen "…"` as a fix that did
 nothing.
 
+**Dropping a table has its own bucket, emitted BEFORE the table statements — the mirror image of
+the one above, `As of 2026-08-23`.** `--allow-destructive` emitted a bare `drop table "authors";`
+with every `alter table … drop constraint` appended AFTER it, so dropping a table another entity
+`references()` was `2BP01 cannot drop table authors because other objects depend on it` — during
+`ROLE=migrate` in the release phase, with the ledger recording nothing and a `down` of
+`-- "<table>" cannot be restored`, i.e. nothing to reverse and a generated file to hand-edit. The
+two-table case failed identically because drops came out **alphabetically**, which puts the parent
+first. Two halves. `foreignKeyPlan` routes a key whose `referencedTable` is doomed into `preDrops`
+instead of `constraints` — whether the entity still declares it or not, since a constraint cannot
+outlive its target — and its `down` is a comment, because `add constraint` against a table no
+`down` can restore is a rollback that cannot run. `drop-order.ts` orders the drops children-first
+(a self-reference is not a blocker: `drop table` takes the table's own constraints with it) and
+breaks a cycle between two doomed tables by dropping one inbound key first, which is the only
+statement it emits. The `--allow-destructive` refusal is raised over that same ordered list, so
+which table it names does not move with the alphabet.
+
+**`foreignKeyPlan` lives in `foreign-key-plan.ts`, `As of 2026-08-23`** — split out of
+`generate.ts` at the 500-line ceiling, along the seam it already drew: `generate.ts` assembles a
+plan, `foreign-key-plan.ts` decides which bucket each key statement goes in, `foreign-key.ts`
+writes the SQL. `Plan`, `foreignKeysOf` and `referenceParts` went with it because they are that
+module's vocabulary; `snapshotOf` imports `foreignKeysOf` back, one direction only.
+
 **`foreignKeyPlan` walks both directions, `As of 2026-08-19`.** A *removed* `references()` used to
 emit nothing while the snapshot beside it recorded `foreignKeys: []` — so the orphan constraint
 stayed on the database **and** the record denied one the catalog holds, which `compareForeignKeys`
@@ -647,7 +679,13 @@ statement_timeout` set moments earlier, so `select 1; set statement_timeout = 0`
 while `guards` went on reporting `timeout:5000ms`. `BEGIN READ ONLY` still held, so this was a
 defeated layer reported as an engaged one rather than a write — and a guard list that lies is worse
 than a guard list that is short. `statementsOf` is the package's one splitter, so a `;` inside a
-literal, a comment or a dollar-quoted body stays data.
+literal, a comment or a dollar-quoted body stays data. **And the splice takes the splitter's
+answer, `As of 2026-08-23`** — `statements[0]`, never the caller's text with a trailing `;` chopped
+off it by a regex. That second answer only saw a `;` at the very END: `select 1; -- note` is one
+statement to the splitter and does not end in `;`, so it reached the `DECLARE` whole and Postgres
+answered `cannot insert multiple commands into a prepared statement`, uncoded, out of the path
+whose whole job is bounding the read. The uncursored path still sends the caller's text
+byte-for-byte, because it splices nothing.
 
 `readonly-role.ts` and `readonly-query.ts` are layers 1–2 of that tool's defence-in-depth: a
 `NOLOGIN` Postgres role (`ensureReadOnlyRole`) and a per-statement `BEGIN READ ONLY` + statement

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "9.0.0",
+  "version": "11.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "9.0.0"
+    "@ultimat3/core": "11.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/drop-order.ts

@@ -0,0 +1,61 @@
+// Single responsibility: the order a set of tables can be dropped in, and the foreign keys that
+// have to go first when no order exists. `generate.ts` writes the statements; this file decides
+// which of them may run when, because `drop table` is refused (`2BP01`) while anything still
+// points at the table.
+
+import { dropForeignKey } from './foreign-key';
+import type { TableDescription } from './introspect';
+
+export interface DropOrder {
+  /** The tables, referencing before referenced. */
+  readonly tables: readonly TableDescription[];
+  /** `drop constraint` statements that must run BEFORE the first drop — cycles only. */
+  readonly constraints: readonly string[];
+}
+
+function referencesFrom(table: TableDescription, target: string): readonly string[] {
+  return table.foreignKeys
+    .filter((key) => key.referencedTable === target)
+    .map((key) => dropForeignKey(table.name, key.name));
+}
+
+/**
+ * Drop the children first: a table nothing still-to-be-dropped points at is always safe to drop,
+ * and removing it makes its own parents safe in turn. Alphabetical order — which is what
+ * `SchemaDescription` carries — puts `authors` before `posts`, i.e. the parent first, which is the
+ * one order Postgres refuses.
+ *
+ * A self-reference is never a blocker: `drop table` takes the table's OWN constraints with it, so
+ * a tree table needs no `drop constraint` of its own.
+ *
+ * A cycle between two doomed tables has no safe order at all, so one of them is chosen and the
+ * keys pointing at it are dropped first. That is the only case that emits a statement here — every
+ * other inbound key belongs to a table that SURVIVES, which `generate.ts` handles beside the entity
+ * that still owns the column.
+ */
+export function dropOrder(dropped: readonly TableDescription[]): DropOrder {
+  const remaining = [...dropped];
+  const tables: TableDescription[] = [];
+  const constraints: string[] = [];
+  while (remaining.length > 0) {
+    const free = remaining.findIndex(
+      (table) =>
+        !remaining.some(
+          (other) =>
+            other.name !== table.name &&
+            other.foreignKeys.some((key) => key.referencedTable === table.name),
+        ),
+    );
+    const index = free === -1 ? 0 : free;
+    const next = remaining[index] as TableDescription;
+    if (free === -1) {
+      for (const other of remaining) {
+        if (other.name === next.name) continue;
+        constraints.push(...referencesFrom(other, next.name));
+      }
+    }
+    tables.push(next);
+    remaining.splice(index, 1);
+  }
+  return { tables, constraints };
+}

package/src/errors.ts

@@ -2,7 +2,13 @@
 // fixes the situation — `X_DB_DRIFT` is the flagship and its rendering is byte-for-byte
 // pinned by the framework contract, so change its strings only with the contract.
 
-import { registerErrorCodes, renderThrowable, stringField, UltimateError } from '@ultimat3/core';
+import {
+  describeValue,
+  registerErrorCodes,
+  renderThrowable,
+  stringField,
+  UltimateError,
+} from '@ultimat3/core';
 import { DESTRUCTIVE_CAUSE, DESTRUCTIVE_MARKER, type DestructiveStatement } from './destructive';
 import { type DbSqlStateCode, sqlState, sqlStateCode } from './sqlstate';
 
@@ -97,7 +103,6 @@ export class DbError extends UltimateError {
       code: init.code,
       cause: init.cause,
       fix: init.fix,
-      docs: `https://ultimate.dev/errors/${init.code}`,
       meta: init.meta,
       sourceError: init.sourceError,
     });
@@ -385,6 +390,23 @@ export const branchNameInvalid = (branch: string): DbError =>
     meta: { branch },
   });
 
+/**
+ * An isolation level that is not one of the three. `X_SQL_UNSAFE` for the reason
+ * `branchNameInvalid` uses it: `BEGIN` takes no parameters, so the level is SPLICED into the
+ * statement text — `withTransaction(fn, { isolation: fromConfig })` with an operand TypeScript
+ * never saw is an injection, not a typo.
+ *
+ * `describeValue`, never the value: this cause is folded into a problem document and a log line,
+ * and an operand that arrived from a request body has no key left to redact once it is baked into
+ * a message. The three legal spellings are in the `fix:`, which is what the caller needs.
+ */
+export const isolationLevelInvalid = (received: unknown): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `an isolation level must be one of 'read committed', 'repeatable read' or 'serializable'; got ${describeValue(received)}`,
+    fix: "withTransaction(fn, { isolation: 'serializable' })   # or 'repeatable read', or 'read committed'",
+  });
+
 export const dbNotImplemented = (feature: string, fix: string): DbError =>
   new DbError({
     code: 'X_NOT_IMPLEMENTED',

package/src/foreign-key-plan.ts

@@ -0,0 +1,146 @@
+// Single responsibility: which foreign keys a migration must add or drop, and into which of the
+// two buckets each statement goes — `constraints` runs AFTER the table statements, `preDrops`
+// BEFORE them. `generate.ts` assembles the plan; `foreign-key.ts` writes the SQL.
+
+import type { EntityDescriptionLike } from './entity-shape';
+import { addForeignKey, dropForeignKey, foreignKeyTarget, onDeleteRule } from './foreign-key';
+import type { ForeignKeyDescription, TableDescription } from './introspect';
+
+/** The two directions of one migration, pushed in `up` order; `down` is reversed at assembly. */
+export interface Plan {
+  readonly up: string[];
+  readonly down: string[];
+}
+
+/**
+ * The two ends of a `references()`, which entity renders as `"<table>.<column>"`. Read once: the
+ * clause that writes the constraint and the snapshot that records it must not disagree about what
+ * it points at, or drift reports a key the database holds exactly as declared.
+ */
+export function referenceParts(references: string): readonly [string, string] {
+  const [table = references, column = 'id'] = references.split('.');
+  return [table, column];
+}
+
+/**
+ * The keys this entity declares, recorded so drift can see one dropped by hand. Recording
+ * `foreignKeys: []` while the same run emitted a constraint was a snapshot claiming a constraint
+ * does not exist that the migration beside it creates, and `compareTable` had nothing to compare —
+ * a key dropped on the database was invisible to every check the framework runs.
+ *
+ * The name is `<table>_<column>_fkey` — what Postgres would have called an inline `references`
+ * clause — and `addForeignKey` now writes it out, so the snapshot records a name the migration
+ * beside it chose rather than one it guessed. It is still *not* what drift matches on: see
+ * `compareForeignKeys` in `drift.ts`.
+ *
+ * `onDelete` is the column's own, and `addForeignKey` spells it: a rule recorded here while no
+ * clause declared one would be a claim about the database that is not true, which is what it was
+ * until the clause learned to write it out.
+ */
+export function foreignKeysOf(entity: EntityDescriptionLike): ForeignKeyDescription[] {
+  return entity.columns
+    .filter((column) => column.references !== null)
+    .map((column): ForeignKeyDescription => {
+      const [table, key] = referenceParts(column.references ?? '');
+      return {
+        name: `${entity.table}_${column.column}_fkey`,
+        columns: [column.column],
+        referencedTable: table,
+        referencedColumns: [key],
+        onDelete: column.onDelete ?? null,
+      };
+    })
+    .sort((a, b) => (a.name < b.name ? -1 : 1));
+}
+
+/**
+ * Every foreign key the entity declares that the previous snapshot does not already record, as its
+ * own `add constraint`. One call site for both cases the generator has — a table being created and
+ * a `references()` added to a column that already exists — because they are one question: which of
+ * this entity's keys does the database not hold yet.
+ *
+ * The statements land in a bucket of their own, appended after every table statement, so a key
+ * never runs before the table it points at. `down` is reversed as a whole, so pushing the drops
+ * last here puts them *first* on the way back: `drop table "posts"` with `comments` still
+ * referencing it is `2BP01`, a migration that cannot be rolled back at all.
+ *
+ * The mirror image of that asymmetry is `plans.preDrops`, which is emitted BEFORE the table
+ * statements: a key pointing at a table this migration DROPS has to go first, or the drop is
+ * `2BP01` on the way forward. Its `down` is a comment for the same reason the table's own is —
+ * `add constraint` against a table no `down` can restore is a rollback that cannot run.
+ *
+ * Both directions, because a snapshot may not lie: a removed `references()` used to emit nothing
+ * while the snapshot beside it recorded `foreignKeys: []`, so the orphan constraint stayed on the
+ * database *and* the record denied one the catalog holds — and `compareForeignKeys` judges the
+ * declared side, so no drift check could ever see it. Not parity with a removed index either: that
+ * leaves the snapshot correct by omission. The drop names the constraint the previous snapshot
+ * recorded, never the name this generator would have chosen — a hand-written `fk_legacy` is
+ * `42704` under the generated spelling.
+ */
+export function foreignKeyPlan(
+  entity: EntityDescriptionLike,
+  live: TableDescription | undefined,
+  plans: ConstraintPlans,
+): void {
+  const { constraints, preDrops, doomed } = plans;
+  const wanted = foreignKeysOf(entity);
+  const held = new Map((live?.foreignKeys ?? []).map((key) => [foreignKeyTarget(key), key]));
+  for (const key of wanted) {
+    const recorded = held.get(foreignKeyTarget(key));
+    if (doomed.has(key.referencedTable)) {
+      // Still declared, but its target is going away this migration. The constraint cannot outlive
+      // the table, so it goes first — and no `add constraint` is written for one that never was.
+      if (recorded !== undefined)
+        unrestorableDrop(entity.table, recorded.name, key.referencedTable, preDrops);
+      continue;
+    }
+    if (recorded === undefined) {
+      constraints.up.push(addForeignKey(entity.table, key));
+      constraints.down.push(dropForeignKey(entity.table, key.name));
+      continue;
+    }
+    // The rule is not part of a key's identity, so the same key under a new one is a rebuild —
+    // Postgres has no `alter constraint` for it, the same reason `redefineIndex` recreates.
+    if (onDeleteRule(recorded.onDelete) === onDeleteRule(key.onDelete)) continue;
+    constraints.up.push(
+      dropForeignKey(entity.table, recorded.name),
+      addForeignKey(entity.table, key),
+    );
+    // Pushed forwards and read backwards, like `redefineIndex`: `down` is reversed at assembly.
+    constraints.down.push(
+      addForeignKey(entity.table, recorded),
+      dropForeignKey(entity.table, key.name),
+    );
+  }
+  const declared = new Set(wanted.map(foreignKeyTarget));
+  const columns = new Set(entity.columns.map((column) => column.column));
+  for (const key of live?.foreignKeys ?? []) {
+    if (declared.has(foreignKeyTarget(key))) continue;
+    // `drop column` takes the constraint with it, so a `drop constraint` after that statement is
+    // `42704` on a constraint that is already gone.
+    if (!key.columns.every((column) => columns.has(column))) continue;
+    if (doomed.has(key.referencedTable)) {
+      unrestorableDrop(entity.table, key.name, key.referencedTable, preDrops);
+      continue;
+    }
+    constraints.up.push(dropForeignKey(entity.table, key.name));
+    constraints.down.push(addForeignKey(entity.table, key));
+  }
+}
+
+export interface ConstraintPlans {
+  /** `add`/`drop` for keys between tables that survive — appended AFTER the table statements. */
+  readonly constraints: Plan;
+  /** Keys pointing at a table this migration drops — emitted BEFORE the table statements. */
+  readonly preDrops: Plan;
+  /** The tables this migration drops, by name. */
+  readonly doomed: ReadonlySet<string>;
+}
+
+/** A key whose target is being dropped: gone on the way up, a note on the way back. */
+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`,
+  );
+}

package/src/foreign-key.ts

@@ -5,14 +5,22 @@
 import { assert } from '@ultimat3/core';
 import type { ForeignKeyDescription } from './introspect';
 
-/** `pg_constraint.confdeltype`. The catalog's vocabulary; a description holds the rule's name. */
-const CATALOG_RULES: Readonly<Record<string, string>> = {
-  a: 'no action',
-  c: 'cascade',
-  r: 'restrict',
-  n: 'set null',
-  d: 'set default',
-};
+/**
+ * `pg_constraint.confdeltype`. The catalog's vocabulary; a description holds the rule's name.
+ *
+ * A `Map`, because `raw` is a catalog string on every read: an object literal answered
+ * `CATALOG_RULES['constructor']` with the `Object` FUNCTION, which left this `string | null`
+ * function returning one into `compareForeignKeys`.
+ */
+const CATALOG_RULES: ReadonlyMap<string, string> = new Map(
+  Object.entries({
+    a: 'no action',
+    c: 'cascade',
+    r: 'restrict',
+    n: 'set null',
+    d: 'set default',
+  }),
+);
 
 /**
  * One `on delete` vocabulary for both sides. The catalog spells the rule as a single character and
@@ -25,7 +33,7 @@ const CATALOG_RULES: Readonly<Record<string, string>> = {
  */
 export function onDeleteRule(raw: string | null): string | null {
   if (raw === null) return null;
-  const named = CATALOG_RULES[raw] ?? raw.toLowerCase();
+  const named = CATALOG_RULES.get(raw) ?? raw.toLowerCase();
   return named === 'no action' ? null : named;
 }
 

package/src/generate.ts

@@ -5,16 +5,16 @@
 
 import { assert, systemClock } from '@ultimat3/core';
 import { isDestructive } from './destructive';
+import { dropOrder } from './drop-order';
 import type {
   ColumnDescriptionLike,
   EntityDescriptionLike,
   IndexDescriptionLike,
 } from './entity-shape';
 import { migrationIrreversible } from './errors';
-import { addForeignKey, dropForeignKey, foreignKeyTarget, onDeleteRule } from './foreign-key';
+import { type ConstraintPlans, foreignKeyPlan, foreignKeysOf, type Plan } from './foreign-key-plan';
 import {
   type ColumnDescription,
-  type ForeignKeyDescription,
   findTable,
   type IndexDescription,
   type SchemaDescription,
@@ -52,16 +52,6 @@ function defaultExpression(column: ColumnDescriptionLike): string | null {
   return null;
 }
 
-/**
- * The two ends of a `references()`, which entity renders as `"<table>.<column>"`. Read once: the
- * clause that writes the constraint and the snapshot that records it must not disagree about what
- * it points at, or drift reports a key the database holds exactly as declared.
- */
-function referenceParts(references: string): readonly [string, string] {
-  const [table = references, column = 'id'] = references.split('.');
-  return [table, column];
-}
-
 function columnClause(column: ColumnDescriptionLike): string {
   const parts = [`"${column.column}"`, sqlType(column.kind)];
   const expression = defaultExpression(column);
@@ -103,37 +93,6 @@ function impliedByColumnClause(
   return column !== undefined && column.unique && !column.primaryKey && added.has(only);
 }
 
-/**
- * The keys this entity declares, recorded so drift can see one dropped by hand. Recording
- * `foreignKeys: []` while the same run emitted a constraint was a snapshot claiming a constraint
- * does not exist that the migration beside it creates, and `compareTable` had nothing to compare —
- * a key dropped on the database was invisible to every check the framework runs.
- *
- * The name is `<table>_<column>_fkey` — what Postgres would have called an inline `references`
- * clause — and `addForeignKey` now writes it out, so the snapshot records a name the migration
- * beside it chose rather than one it guessed. It is still *not* what drift matches on: see
- * `compareForeignKeys` in `drift.ts`.
- *
- * `onDelete` is the column's own, and `addForeignKey` spells it: a rule recorded here while no
- * clause declared one would be a claim about the database that is not true, which is what it was
- * until the clause learned to write it out.
- */
-function foreignKeysOf(entity: EntityDescriptionLike): ForeignKeyDescription[] {
-  return entity.columns
-    .filter((column) => column.references !== null)
-    .map((column): ForeignKeyDescription => {
-      const [table, key] = referenceParts(column.references ?? '');
-      return {
-        name: `${entity.table}_${column.column}_fkey`,
-        columns: [column.column],
-        referencedTable: table,
-        referencedColumns: [key],
-        onDelete: column.onDelete ?? null,
-      };
-    })
-    .sort((a, b) => (a.name < b.name ? -1 : 1));
-}
-
 export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDescription {
   const tables = [...entities]
     .sort((a, b) => (a.table < b.table ? -1 : 1))
@@ -202,69 +161,6 @@ function createIndex(table: string, index: IndexDescriptionLike): string {
   return `${kind} "${index.name}" on "${table}" (${columns})${predicate};`;
 }
 
-interface Plan {
-  readonly up: string[];
-  readonly down: string[];
-}
-
-/**
- * Every foreign key the entity declares that the previous snapshot does not already record, as its
- * own `add constraint`. One call site for both cases the generator has — a table being created and
- * a `references()` added to a column that already exists — because they are one question: which of
- * this entity's keys does the database not hold yet.
- *
- * The statements land in a bucket of their own, appended after every table statement, so a key
- * never runs before the table it points at. `down` is reversed as a whole, so pushing the drops
- * last here puts them *first* on the way back: `drop table "posts"` with `comments` still
- * referencing it is `2BP01`, a migration that cannot be rolled back at all.
- *
- * Both directions, because a snapshot may not lie: a removed `references()` used to emit nothing
- * while the snapshot beside it recorded `foreignKeys: []`, so the orphan constraint stayed on the
- * database *and* the record denied one the catalog holds — and `compareForeignKeys` judges the
- * declared side, so no drift check could ever see it. Not parity with a removed index either: that
- * leaves the snapshot correct by omission. The drop names the constraint the previous snapshot
- * recorded, never the name this generator would have chosen — a hand-written `fk_legacy` is
- * `42704` under the generated spelling.
- */
-function foreignKeyPlan(
-  entity: EntityDescriptionLike,
-  live: TableDescription | undefined,
-  constraints: Plan,
-): void {
-  const wanted = foreignKeysOf(entity);
-  const held = new Map((live?.foreignKeys ?? []).map((key) => [foreignKeyTarget(key), key]));
-  for (const key of wanted) {
-    const recorded = held.get(foreignKeyTarget(key));
-    if (recorded === undefined) {
-      constraints.up.push(addForeignKey(entity.table, key));
-      constraints.down.push(dropForeignKey(entity.table, key.name));
-      continue;
-    }
-    // The rule is not part of a key's identity, so the same key under a new one is a rebuild —
-    // Postgres has no `alter constraint` for it, the same reason `redefineIndex` recreates.
-    if (onDeleteRule(recorded.onDelete) === onDeleteRule(key.onDelete)) continue;
-    constraints.up.push(
-      dropForeignKey(entity.table, recorded.name),
-      addForeignKey(entity.table, key),
-    );
-    // Pushed forwards and read backwards, like `redefineIndex`: `down` is reversed at assembly.
-    constraints.down.push(
-      addForeignKey(entity.table, recorded),
-      dropForeignKey(entity.table, key.name),
-    );
-  }
-  const declared = new Set(wanted.map(foreignKeyTarget));
-  const columns = new Set(entity.columns.map((column) => column.column));
-  for (const key of live?.foreignKeys ?? []) {
-    if (declared.has(foreignKeyTarget(key))) continue;
-    // `drop column` takes the constraint with it, so a `drop constraint` after that statement is
-    // `42704` on a constraint that is already gone.
-    if (!key.columns.every((column) => columns.has(column))) continue;
-    constraints.up.push(dropForeignKey(entity.table, key.name));
-    constraints.down.push(addForeignKey(entity.table, key));
-  }
-}
-
 /**
  * Skipping an existing column by name alone missed the type moving under it: a table created
  * while money's currency was bare `char` keeps `char(1)` and rejects every ISO 4217 code, yet the
@@ -405,11 +301,19 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   const plan: Plan = { up: [], down: [] };
   // Merged into `plan` once every table statement is in, never interleaved with them.
   const constraints: Plan = { up: [], down: [] };
+  // Merged in BEFORE them, for the mirror-image reason: a key still pointing at a table this
+  // migration drops makes that `drop table` `2BP01`.
+  const preDrops: Plan = { up: [], down: [] };
   const wanted = new Set(options.entities.map((entity) => entity.table));
 
+  const doomed = new Set(
+    current.tables.filter((table) => !wanted.has(table.name)).map((table) => table.name),
+  );
+  const plans: ConstraintPlans = { constraints, preDrops, doomed };
+
   for (const entity of options.entities) {
     const live = findTable(current, entity.table);
-    foreignKeyPlan(entity, live, constraints);
+    foreignKeyPlan(entity, live, plans);
     if (live === undefined) {
       plan.up.push(...createTable(entity));
       plan.down.push(`drop table "${entity.table}";`);
@@ -433,14 +337,18 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     }
   }
 
-  for (const table of current.tables) {
-    if (wanted.has(table.name)) continue;
+  const order = dropOrder(current.tables.filter((table) => !wanted.has(table.name)));
+  for (const table of order.tables) {
     if (options.allowDestructive !== true) {
       throw migrationIrreversible(
         `dropping table "${table.name}" discards every row and cannot be undone`,
         `x db gen "${options.name}" --allow-destructive   # or delete the entity in two releases`,
       );
     }
+  }
+  plan.up.push(...preDrops.up, ...order.constraints);
+  plan.down.push(...preDrops.down, ...order.constraints.map(() => '-- constraint not restored'));
+  for (const table of order.tables) {
     plan.up.push(`drop table "${table.name}";`);
     plan.down.push(`-- "${table.name}" cannot be restored; recover it from a backup`);
   }

package/src/readonly-query.ts

@@ -128,7 +128,15 @@ export async function readOnlyQuery<T>(
       guards.push(`role:${options.role}`);
     }
 
-    const rows = await readRows<T>(connection, statement, fetchCount(options.maxRows), guards);
+    // Two texts, deliberately: the caller's own, sent verbatim when nothing is spliced, and the
+    // one COMMAND `statementsOf` cut out of it, which is the only text a `DECLARE` may carry.
+    const rows = await readRows<T>(
+      connection,
+      statement,
+      statements[0] ?? statement,
+      fetchCount(options.maxRows),
+      guards,
+    );
     await connection.execute(raw('ROLLBACK'));
     return { rows, guards };
   } catch (error) {
@@ -151,16 +159,25 @@ export async function readOnlyQuery<T>(
  */
 async function readRows<T>(
   connection: DbClient,
+  /** What the caller wrote. Sent byte-for-byte on the uncursored path, which splices nothing. */
   statement: string,
+  /**
+   * The one command `statementsOf` cut out of it — what may be spliced.
+   *
+   * This was `statement.trim().replace(/;\s*$/, '')`, a second answer to "where does the command
+   * end" that only saw a `;` at the very END of the text: `select 1; -- note` is ONE statement to
+   * the splitter (a chunk of pure noise is not a statement), so it passed the one-statement gate
+   * and reached the splice whole, as `DECLARE … CURSOR FOR select 1; -- note` — two commands, and
+   * `cannot insert multiple commands into a prepared statement` out of the driver with no code
+   * and no `fix:`. The splitter is the package's one answer, and this is now its only reader.
+   */
+  command: string,
   fetch: number | undefined,
   guards: string[],
 ): Promise<readonly T[]> {
-  if (fetch === undefined || !cursorable(statement)) return connection.query<T>(raw(statement));
+  if (fetch === undefined || !cursorable(command)) return connection.query<T>(raw(statement));
 
-  // A trailing `;` would close `DECLARE` before its query and turn one statement into two. An
-  // EMBEDDED one is refused up in `readOnlyQuery`, before the transaction opens.
-  const query = statement.trim().replace(/;\s*$/, '');
-  await connection.execute(raw(`DECLARE ${CURSOR_NAME} NO SCROLL CURSOR FOR ${query}`));
+  await connection.execute(raw(`DECLARE ${CURSOR_NAME} NO SCROLL CURSOR FOR ${command}`));
   const rows = await connection.query<T>(raw(`FETCH FORWARD ${fetch} FROM ${CURSOR_NAME}`));
   guards.push(`fetch:${fetch} rows`);
   return rows;

package/src/sql.ts

@@ -135,6 +135,13 @@ export function identifier(name: string): SqlFragment {
  * A quoted string literal. Postgres utility statements (`CREATE DATABASE`, `COMMENT ON`) reject
  * bound parameters, so this is the only place a value may be inlined — and it escapes quotes.
  * Never reach for it in a query: `sql` binds parameters there.
+ *
+ * The doubling is only an escape while `standard_conforming_strings` is `on`, which has been the
+ * server default since 9.1: with it OFF, a backslash escapes the quote that follows and a value
+ * ending in one closes the literal early. So this is safe for framework-supplied names — a
+ * database, a schema, a comment this repo writes — and is NOT an escape for untrusted text under
+ * an arbitrary server configuration. Nothing passes it caller input today; if something must,
+ * bind a parameter instead, or send `E''`-style quoting from a statement that can take one.
  */
 export function literal(value: string): SqlFragment {
   return raw(`'${value.replaceAll("'", "''")}'`);

package/src/transaction.ts

@@ -5,7 +5,7 @@
 
 import { assert, asyncContext, nanoid } from '@ultimat3/core';
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
-import { serializationExhausted } from './errors';
+import { isolationLevelInvalid, serializationExhausted } from './errors';
 import { raw, type SqlFragment } from './sql';
 import { isRetryableState } from './sqlstate';
 
@@ -102,11 +102,36 @@ export function inLiveTx(): boolean {
   return storage.get()?.live.value === true;
 }
 
+/**
+ * The SQL for one isolation level, RE-DERIVED from the closed set rather than built out of the
+ * value — the same rule `pg-sql.ts` follows for `asc|desc`, and for the same reason: `BEGIN` takes
+ * no parameters, so this is one of the two statements here built as text, and a level spliced into
+ * it is whatever the caller passed. `isolation` is typed, and a type is not a runtime guard: the
+ * value reaches `withTransaction` from an app's config, a JSON body or a CLI flag —
+ * `{ isolation: 'read committed; drop table x; --' }` became exactly that statement, and a
+ * non-string became an uncoded `TypeError` inside a template literal.
+ *
+ * The `default` arm is `never`, so a fourth member added to `IsolationLevel` with no SQL beside it
+ * is a type error here rather than a refusal at runtime.
+ */
+const isolationMode = (declared: IsolationLevel): string => {
+  switch (declared) {
+    case 'read committed':
+      return 'ISOLATION LEVEL READ COMMITTED';
+    case 'repeatable read':
+      return 'ISOLATION LEVEL REPEATABLE READ';
+    case 'serializable':
+      return 'ISOLATION LEVEL SERIALIZABLE';
+    default: {
+      const unhandled: never = declared;
+      throw isolationLevelInvalid(unhandled);
+    }
+  }
+};
+
 export function beginStatement(options: TransactionOptions): string {
   const modes: string[] = [];
-  if (options.isolation !== undefined) {
-    modes.push(`ISOLATION LEVEL ${options.isolation.toUpperCase()}`);
-  }
+  if (options.isolation !== undefined) modes.push(isolationMode(options.isolation));
   if (options.readOnly === true) modes.push('READ ONLY');
   if (options.deferrable === true) modes.push('DEFERRABLE');
   return modes.length === 0 ? 'BEGIN' : `BEGIN ${modes.join(' ')}`;