@ultimat3/db 3.0.0 → 4.1.0

package/CLAUDE.md

@@ -149,8 +149,12 @@ pool's idle timeout (`migrate`'s is 10s) closes it, releasing the lock mid-migra
 hid the first half by accident — its pool is `max: 1`, so every statement found the same connection.
 No other role and no test has that. The pin is therefore also why the lock scope hands its session
 *down*: on `max: 1` a statement sent to the pool while the pin is held waits for a connection that
-cannot come back until the migration blocking on it finishes. `lock: false` (`x db branch`, a
-private database) reserves nothing and takes no lock, exactly as before.
+cannot come back until the migration blocking on it finishes. `lock: false` reserves nothing and takes no lock, exactly as
+before — for a database only this process can reach. **No shipped path passes it**: both option
+comments named `x db branch`, which does not, and the only callers in the repo are
+`migrate-pin.test.ts`'s. The option stays because it is public API shipped in 3.0.0 and the "no pin
+was taken" assertions cannot be written without it; the false attribution is pinned out by
+`migrate-pin.test.ts`, which also refuses a passer appearing inside this package.
 
 Pinned by `migrate.live.test.ts` against a real Postgres: two concurrent `migrate()` calls (one
 applies, the other skips — never both, never a unique-violation crash) and a migration that fails
@@ -335,12 +339,27 @@ a bad argument is not a fact about the ledger), thrown by `rollbackStepsInvalid`
 lock is taken and before the ledger is read. Same discipline as `poolMaxInvalid`: a number this
 build cannot honour is refused, never reinterpreted.
 
+**`reapBranches` sweeps branches of THIS database, never the server's, `As of 2026-08-19`** (issue
+#133, closed). `listBranches` walks `pg_database` for the whole server and admits every database
+carrying the marker, so two Ultimate apps on one Postgres plus one nightly reap was the other app's
+branches dropped. The discriminator was in hand and thrown away: `createBranch` already resolves
+`options.base ?? currentDatabase(client)` and wrote only the timestamp. The marker is now
+`ultimate:branch:<base>:<iso>` and `BranchInfo.base` carries it, so the reaper skips a branch whose
+base is not the database it is connected to. **Split on the ISO tail, never on the first `:`** — a
+database name may contain one and an instant certainly does. A pre-4.x one-segment comment matches
+no base, keeps its readable date for `x db branch ls`, and is **skipped, never dropped**: a branch
+of nothing is not a branch of this database, which is what makes the change self-healing with no
+migration. Postgres records no template lineage in the catalog and `datdba` is shared when both
+apps use one role, so writing the base down at creation is the only answer there is.
+`@ultimat3/cli`'s `ls`/`drop` scope by the `<source>_branch_` name prefix instead — its own guard,
+and unaffected.
+
 **`reapBranches` skips a `createdAt` it cannot parse; it never reads one as infinitely old.**
 `NaN > cutoff` is `false`, which is the same answer "older than the cutoff" gives — so a
 `COMMENT ON DATABASE` that was truncated or hand-edited used to be a database DROPPED on the next
 nightly sweep whatever `maxAgeMs` said. `Date.parse` + `Number.isFinite`, the discipline
-`@ultimat3/seo`'s `feed-dates.ts` applies to the same question. (Distinct from the open
-source-blindness of the reaper, issue #133.)
+`@ultimat3/seo`'s `feed-dates.ts` applies to the same question. (Whose branches it may touch at
+all is the paragraph above.)
 
 **One send is one statement, so `migrate()` and `rollback()` split the script.** `tx.execute(raw(
 migration.up))` on a text holding two commands is where the two drivers disagreed, and the
@@ -471,11 +490,16 @@ never emitted one and would answer with an empty migration.
 catches a composite index rebuilt with its columns the other way round while the column diff said
 `ok: true`. A live index no snapshot names is deliberately **not** reported: Postgres creates one for
 every primary key and every unique constraint, so counting those is eight findings against a correct
-database, the same argument `appTables()` makes. The predicate and the direction are not compared
-either — the catalog returns its own rewriting of an expression (`(deleted_at IS NULL)`) and the
-snapshot holds the author's spelling, so a text comparison reports two identical indexes as drift.
-`x db gen` compares them instead (`redefineIndex`), where both sides are generated. Named in
-`wiki/Known-Gaps.md`.
+database, the same argument `appTables()` makes. **Three of the four parts are compared, and the fourth never
+will be**, `As of 2026-08-19`: the predicate's *text* stays uncompared, because the catalog returns
+its own rewriting of an expression (`(deleted_at IS NULL)`) where the snapshot holds the author's
+spelling, and normalising that is an expression parser competing with the server's — `x db gen`
+compares the text instead (`redefineIndex`), where both sides are generated. Its *presence* is a
+boolean, not text, and the direction is a closed enum on both sides, so both are compared now: a
+partial index recreated as a total one silently widens the constraint, and a `desc` index rebuilt
+ascending serves a feed's newest page off the wrong end. `asc` normalises to `null` first —
+`createIndex` writes `"col" asc`, which Postgres stores as not-descending, so the raw values differ
+on every ascending index in a correct database.
 
 `compareForeignKeys` judges **declared** keys the same way, and matches on **where the key points**
 — its columns, its target table, its target columns — never on the constraint name. That identity is
@@ -485,8 +509,14 @@ reported on a correct database. `snapshotOf` names a key `<table>_<column>_fkey`
 would have called an inline `references` clause — and `addForeignKey` now writes that name out, so
 the snapshot records a name the migration beside it chose rather than one it guessed; a hand-written
 migration may still have said `constraint fk_posts_org`, and a key pointing the same way under
-another name is the same key. `onDelete` is not compared: the catalog spells it `a`/`c`/`r` and no
-generated clause has ever declared one, so a snapshot has nothing truthful to hold there. Before
+another name is the same key. `onDelete` **is** compared, `As of 2026-08-19`, through `onDeleteRule`
+(`foreign-key.ts`) — the one normalisation both sides pass through, because the catalog spells the
+rule `a`/`c`/`r`/`n`/`d` and a description spells it out, and `a` (`no action`) is what a key that
+declared nothing has. A difference is `changed-foreign-key`, never a `missing` one: the rule is not
+part of a key's identity (`foreignKeyTarget` ignores it, pinned by `foreign-key.test.ts`), the
+constraint is there, and what changed is what happens to the child rows. Its `fix` is the drop/add
+pair built from `dropForeignKey`/`addForeignKey`, not `x db migrate` — a rule cannot be altered in
+place and no `x db gen` diff emits one for a schema already applied. Before
 this, `snapshotOf` recorded `foreignKeys: []` beside an `up` emitting `references "orgs" ("id")` — a
 snapshot denying a constraint its own migration creates — so `alter table … drop constraint` on the
 database answered `ok: true`.
@@ -505,7 +535,32 @@ referencing each other cannot be expressed inline in any order, and separate con
 order at all. 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. Removing a `references()` still emits nothing, exactly as a removed index does.
+nothing.
+
+**`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`
+can never see because it judges the declared side. That is not parity with a removed index: a
+removed index leaves the snapshot correct by omission, and this snapshot lied. The drop names the
+constraint **the previous snapshot recorded**, never the one this generator would have chosen — a
+hand-written `fk_legacy` is `42704` under the generated spelling — and a key whose columns this
+migration is dropping is skipped, because `drop column` takes the constraint with it. A key whose
+`onDelete` moved is a drop **and** an add, the rebuild `redefineIndex` performs for the parts of an
+index Postgres cannot alter in place.
+
+**`on delete` reaches the SQL, `As of 2026-08-19`.** `entity()` has carried
+`references(() => orgs.id, { onDelete: 'cascade' })` since 1.0, it type-checked, and the clause it
+produced was `references "orgs" ("id");` — a declared cascade the database refused the delete
+under instead. It was lost twice over: `describeColumn` renders `references` as the flat string
+`"orgs.id"`, which has no room for it, and `ReferenceDescription` had no field for it either. Both
+carry it now, `addForeignKey` writes it out, and a rule Postgres does not have is `X_INVARIANT`
+rather than spliced DDL — the discipline `createIndex` already applies to an index naming no column.
+
+**`entity-shape.ts` holds the three `*Like` interfaces**, split out of `generate.ts` for the line
+ceiling and along the seam the tier already draws: they are the structural mirror of
+`@ultimat3/entity`'s description, which is how a snapshot crosses tier 2 → tier 1 with no import.
+`ColumnDescriptionLike.onDelete` is optional for exactly that reason — a description written before
+the field existed still satisfies the shape.
 
 **`snapshot-json.ts` writes the sidecar's bytes, and they must be a fixed point of Biome.** A
 scaffolded app's `lint` step is `biome check .` over `"includes": ["**"]`, and `.sql`/`.hash` are

package/README.md

@@ -32,17 +32,17 @@ await withTransaction(async (tx) => {
 | `sqlState()` / `sqlStateCode()` / `isRetryableState()` / `SQLSTATE` | `As of 2026-08`: the SQLSTATE a driver error carries, and the closed table from it to a code. `Bun.SQL` puts it on `errno`; PGlite puts it on `code`; **one** reader answers for both |
 | `migrate()` / `rollback()` / `readLedger()` | the `x_migrations` ledger |
 | `statementsOf()` | `As of 2026-08`: a SQL script → the statements a driver sends one at a time. One send is one statement, so `migrate()` splits with this — a `;` inside a literal, an identifier, a dollar-quoted body or a comment is data |
-| `checkDrift()` / `diffSchema()` / `assertNoDrift()` | drift, with a `--json` report. `checkDrift()` is the **post-migrate verification** — the live database against the ledger: columns, declared indexes, and declared foreign keys, matched on where the key points and not on its constraint name |
+| `checkDrift()` / `diffSchema()` / `assertNoDrift()` | drift, with a `--json` report. `checkDrift()` is the **post-migrate verification** — the live database against the ledger: columns, declared indexes (columns, uniqueness, direction, and whether a predicate is there at all — never its text) and declared foreign keys, matched on where the key points and not on its constraint name, with the `on delete` rule compared through one normalisation `As of 2026-08-19` |
 | `declaredSchema()` / `expectedSchema()` | `As of 2026-08`: the schema the migrations write down, or `undefined` when the newest one carries no snapshot — never an older snapshot standing in for it |
 | `parseSnapshot()` | `As of 2026-08`: a `<id>.snapshot.json` sidecar validated to the last nested field, or `undefined`. `{"tables":[null]}` is valid JSON and is not a schema |
 | `snapshotJson()` | `As of 2026-08`: the sidecar's **bytes** — the JSON Biome would have printed, trailing newline included. The one writer of a `<id>.snapshot.json`, because `JSON.stringify(…, null, 2)` is not formatter-clean and an app's `lint` step rejected the file `x db gen` had just written |
 | `isLedgerMissing()` | `As of 2026-08`: whether an error is Postgres' `undefined_table` for `x_migrations` — the one condition a caller may read as "nothing applied" |
 | `appTables()` / `FRAMEWORK_TABLE_PREFIX` | `As of 2026-08`: the live schema minus the `x_` namespace — no migration declares the ledger, the queue, the outbox or an auth table, so none of them is drift |
-| `generateMigration()` | `x db gen "<name>"` — reversible up/down SQL, and `destructive` for the marker the file must carry. `As of 2026-08` a foreign key is its own `alter table … add constraint`, emitted after every table statement: inline, a `references()` had to point at a table entity registration order happened to create first, and `down` had to drop them in an order it did not control |
+| `generateMigration()` | `x db gen "<name>"` — reversible up/down SQL, and `destructive` for the marker the file must carry. `As of 2026-08` a foreign key is its own `alter table … add constraint`, emitted after every table statement: inline, a `references()` had to point at a table entity registration order happened to create first, and `down` had to drop them in an order it did not control. `As of 2026-08-19` a **removed** `references()` emits its `drop constraint` (it emitted nothing, and the snapshot then denied a constraint the database still held), a changed `onDelete` is a drop-and-add rebuild, and a declared `on delete` rule reaches the clause at all |
 | `destructiveStatements()` / `hasDestructiveMarker()` / `isDestructive()` / `DESTRUCTIVE_MARKER` | `As of 2026-08`: the destructive-SQL rail — does this `up` drop, truncate or retype, and does the file declare it with `-- destructive: true`? One classifier, read by `x db gen` when it writes the marker and by `x verify` when it demands one |
 | `stripSqlNoise()` | comments, literals, dollar-quoted bodies and quoted identifiers blanked **in source order**, so a reader sees the operation and not the prose. Shared by `readOnlyQuery()` and the destructive rail |
 | `introspect()` | live schema → `SchemaDescription` |
-| `createBranch()` / `dropBranch()` / `reapBranches()` | copy-on-write branch databases |
+| `createBranch()` / `dropBranch()` / `reapBranches()` | copy-on-write branch databases. `As of 2026-08-19` the marker comment records the **base** as well as the instant (`ultimate:branch:<base>:<iso>`, on `BranchInfo.base`), and `reapBranches()` sweeps only branches of the database it is connected to — one Postgres hosting two Ultimate apps used to mean one app's nightly reap dropped the other's branches. A pre-3.x marker records no base and is skipped, never dropped |
 | `createPgliteClient()` / `branchPglite()` | the embedded database — Postgres in this process |
 | `ensureReadOnlyRole()` / `grantReadOnlySql()` / `READONLY_ROLE` | a `NOLOGIN`, SELECT-only Postgres role — layer 1 of `db.query`'s defence |
 | `readOnlyQuery()` / `READONLY_TIMEOUT_MS` | one statement inside `BEGIN READ ONLY` with a statement timeout — layer 2 |
@@ -136,6 +136,8 @@ X_DB_DRIFT: schema differs from migrations
 | migrated column, not live | `table "T" is missing column "C" that migrations declare` | `x db migrate` |
 | live table, no migration | `table "T" is not present in any migration` | `x db gen "add T"` |
 | migrated table, not live | `table "T" is declared by migrations but does not exist` | `x db migrate` |
+| index rebuilt differently | `index "I" on "T" covers (…)` / `is unique` / `is descending` / `is partial`, `not what migrations declare` | `x db migrate` |
+| foreign key, rule moved | `foreign key on "T" (C) to "R" is on delete cascade, not what migrations declare` | the `drop constraint` + `add constraint` pair, in a new migration |
 
 `checkDrift()` returns every difference; `assertNoDrift()` throws the first. `x db migrate` renders
 them all as findings and exits non-zero; a `ROLE=migrate` container throws the first one

package/package.json

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

package/src/branch.ts

@@ -10,15 +10,43 @@ import { identifier, literal, sql } from './sql';
 
 const BRANCH_NAME = /^[a-z0-9_-]+$/;
 
-/** Written as a database comment at creation time — `pg_database` has no created_at. */
+/**
+ * Written as a database comment at creation time — `pg_database` has no created_at, and no
+ * template lineage either. The payload is `<base>:<iso>`: the database this clone came from, then
+ * the instant it was made, always UTC through `toISOString()`.
+ *
+ * The base is half the marker because nothing else can answer "whose branch is this". Postgres
+ * records no lineage in the catalog and `datdba` is shared when both apps connect as one role, so
+ * a reaper reading the marker alone sweeps every Ultimate app on the server (issue #133).
+ */
 const BRANCH_MARKER = 'ultimate:branch:';
 
+/**
+ * `<base>:<iso>`, split on the ISO tail rather than on the first `:` — a database name may contain
+ * one and an ISO instant certainly does. A comment that does not match is a pre-4.x one-segment
+ * marker: its date is still readable, and its base is `null`, which is what keeps `reapBranches`
+ * off it. Unknown, never guessed at.
+ */
+const MARKER_PAYLOAD = /^(.*):(\d{4,}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)$/;
+
 export interface BranchInfo {
   readonly name: string;
+  /** The database this branch was cloned from. `null` on a branch made before 4.0 recorded it. */
+  readonly base: string | null;
   readonly createdAt: string | null;
   readonly sizeBytes: number;
 }
 
+function parseMarker(comment: string): Pick<BranchInfo, 'base' | 'createdAt'> {
+  const payload = comment.slice(BRANCH_MARKER.length);
+  const parts = MARKER_PAYLOAD.exec(payload);
+  const [, base, createdAt] = parts ?? [];
+  if (base === undefined || createdAt === undefined) {
+    return { base: null, createdAt: payload === '' ? null : payload };
+  }
+  return { base: base === '' ? null : base, createdAt };
+}
+
 export function assertBranchName(branch: string): string {
   if (!BRANCH_NAME.test(branch)) throw branchNameInvalid(branch);
   return branch;
@@ -54,9 +82,11 @@ export async function createBranch(
   await client.execute(sql`create database ${identifier(branch)} template ${identifier(base)}`);
   const createdAt = (options.now ?? systemClock.now()).toISOString();
   await client.execute(
-    sql`comment on database ${identifier(branch)} is ${literal(`${BRANCH_MARKER}${createdAt}`)}`,
+    sql`comment on database ${identifier(branch)} is ${literal(
+      `${BRANCH_MARKER}${base}:${createdAt}`,
+    )}`,
   );
-  return { name: branch, createdAt, sizeBytes: 0 };
+  return { name: branch, base, createdAt, sizeBytes: 0 };
 }
 
 export async function currentDatabase(client: DbClient = baseClient()): Promise<string> {
@@ -85,7 +115,7 @@ export async function listBranches(options: BranchOptions = {}): Promise<readonl
     .filter((row) => row.comment?.startsWith(BRANCH_MARKER) === true)
     .map((row) => ({
       name: row.name,
-      createdAt: row.comment?.slice(BRANCH_MARKER.length) ?? null,
+      ...parseMarker(row.comment ?? ''),
       sizeBytes: Number(row.size_bytes),
     }));
 }
@@ -127,12 +157,24 @@ export interface ReapOptions extends DropBranchOptions {
   readonly maxAgeMs: number;
 }
 
-/** Preview environments leak branches; this is what the nightly `reapBranches` task calls. */
+/**
+ * Preview environments leak branches; this is what the nightly `reapBranches` task calls.
+ *
+ * **Branches of THIS database only** (issue #133). `listBranches` walks `pg_database` for the whole
+ * server, so two Ultimate apps sharing one Postgres plus one nightly sweep was the other app's
+ * branches dropped — a `DROP DATABASE` nothing recovers from and nobody asked for. A branch whose
+ * base is not this database is skipped, and so is a pre-4.x marker that records no base at all:
+ * a branch of nothing is not a branch of this database, which makes the change self-healing with
+ * no migration — the next `createBranch` writes the base down.
+ */
 export async function reapBranches(options: ReapOptions): Promise<readonly string[]> {
   const cutoff = (options.now ?? systemClock.now()).getTime() - options.maxAgeMs;
-  const branches = await listBranches(options);
+  const client = options.client ?? baseClient();
+  const here = await currentDatabase(client);
+  const branches = await listBranches({ ...options, client });
   const dropped: string[] = [];
   for (const branch of branches) {
+    if (branch.base !== here) continue;
     if (branch.createdAt === null) continue;
     const createdAtMs = Date.parse(branch.createdAt);
     // `NaN > cutoff` is `false`, which is the same answer "older than the cutoff" gives — so a

package/src/client.ts

@@ -7,7 +7,7 @@ import { type Role, renderThrowable, resolveRole } from '@ultimat3/core';
 import { statementAttribution } from './attribution';
 import { DbError, dbUnavailable, driverError, poolAcquireTimeout, poolMaxInvalid } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
-import { mergeLibpqOptions } from './libpq-options';
+import { declaresLibpqOption, mergeLibpqOptions } from './libpq-options';
 import { statementObserver } from './observe';
 import { type SqlFragment, sql } from './sql';
 import { withStatementSpan } from './statement-span';
@@ -180,13 +180,25 @@ function connectionUrl(options: PostgresClientOptions, profile: PoolProfile): st
   // migrations and the role that serves the traffic read different schemas. 0 is a value, not a
   // silence: it is `migrate` saying it may take as long as it takes, and left unsaid a server-side
   // `alter database ... set statement_timeout` kills the one role that must outlive it.
-  url.searchParams.set(
-    'options',
-    mergeLibpqOptions(url.searchParams.get('options'), {
-      statement_timeout: String(profile.statementTimeoutMs),
-    }),
-  );
-  url.searchParams.set('application_name', options.applicationName ?? 'ultimate');
+  // `application_name` is a LABEL, not a bound: 'ultimate' is a DEFAULT, and a default may not
+  // overwrite what the operator wrote — `?application_name=billing-api` is the filter their
+  // `pg_stat_activity` query, their pooler rule and their audit rule all match on, and losing it
+  // is silent. Both spellings count, or the URL parameter and a `-c application_name=` in
+  // `options` disagree and which one the backend honours is argument order nobody here measured.
+  const named = options.applicationName;
+  const settings: Record<string, string> = {
+    statement_timeout: String(profile.statementTimeoutMs),
+  };
+  const inOptions = declaresLibpqOption(url.searchParams.get('options'), 'application_name');
+  // An explicit `applicationName` is a deliberate call by the role that opened the pool, so it
+  // wins. Only then is the setting named to the merge, and only when the operator wrote the other
+  // spelling: `mergeLibpqOptions` drops their assignment before appending, so the two cannot
+  // disagree — and a URL with no assignment in it keeps the exact `options` it always had.
+  if (named !== undefined && inOptions) settings['application_name'] = named;
+  const declared = url.searchParams.has('application_name') || inOptions;
+  url.searchParams.set('options', mergeLibpqOptions(url.searchParams.get('options'), settings));
+  if (named !== undefined) url.searchParams.set('application_name', named);
+  else if (!declared) url.searchParams.set('application_name', 'ultimate');
   return url.toString();
 }
 

package/src/drift.ts

@@ -5,7 +5,7 @@
 
 import { baseClient, type DbClient } from './client';
 import { DbError } from './errors';
-import { foreignKeyTarget } from './foreign-key';
+import { addForeignKey, dropForeignKey, foreignKeyTarget, onDeleteRule } from './foreign-key';
 import {
   type ForeignKeyDescription,
   findTable,
@@ -24,7 +24,8 @@ export type DriftKind =
   | 'unknown-schema'
   | 'missing-index'
   | 'changed-index'
-  | 'missing-foreign-key';
+  | 'missing-foreign-key'
+  | 'changed-foreign-key';
 
 export interface DriftDifference {
   readonly kind: DriftKind;
@@ -165,6 +166,37 @@ function missingForeignKey(table: string, key: ForeignKeyDescription): DriftDiff
   };
 }
 
+/**
+ * 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
@@ -176,11 +208,17 @@ function missingForeignKey(table: string, key: ForeignKeyDescription): DriftDiff
  * would be eight findings against a correct database, which is how a drift check earns being
  * ignored (`appTables` exists for the same reason).
  *
- * The predicate and the direction are deliberately **not** compared: the catalog returns its own
- * rewriting of an expression (`(deleted_at IS NULL)`) and a snapshot holds the author's spelling,
- * so a text comparison reports drift on two identical indexes. `x db gen` compares them instead,
- * where both sides are generated — see `redefineIndex` in `generate.ts`. Named in
- * `wiki/Known-Gaps.md`.
+ * Three of the four parts of an index are compared here; the fourth never will be. The predicate's
+ * **text** is uncomparable and stays so — the catalog answers its own rewriting of the expression
+ * (`(deleted_at IS NULL)`) where the snapshot holds the author's spelling (`deleted_at is null`),
+ * and normalising that means shipping an expression parser to compete with the server's. `x db gen`
+ * compares the text instead, where both sides are generated (`redefineIndex`).
+ *
+ * Its **presence** is not text but a boolean, and the direction is a closed enum on both sides, so
+ * both are compared: a partial index recreated as a total one silently widens the constraint, and
+ * a `desc` index rebuilt ascending by hand serves a feed's newest page off the wrong end. `asc` is
+ * normalised to `null` first — `createIndex` writes `"col" asc`, which Postgres stores as
+ * not-descending, so the raw values differ on every ascending index in a correct database.
  */
 function compareIndexes(live: TableDescription, expected: TableDescription): DriftDifference[] {
   const differences: DriftDifference[] = [];
@@ -201,6 +239,26 @@ function compareIndexes(live: TableDescription, expected: TableDescription): Dri
       differences.push(
         changedIndex(live.name, index.name, counterpart.unique ? 'is unique' : 'is not unique'),
       );
+      continue;
+    }
+    if ((counterpart.order ?? 'asc') !== (index.order ?? 'asc')) {
+      differences.push(
+        changedIndex(
+          live.name,
+          index.name,
+          counterpart.order === 'desc' ? 'is descending' : 'is ascending',
+        ),
+      );
+      continue;
+    }
+    if ((counterpart.where === null) !== (index.where === null)) {
+      differences.push(
+        changedIndex(
+          live.name,
+          index.name,
+          counterpart.where === null ? 'covers every row' : 'is partial',
+        ),
+      );
     }
   }
   return differences;
@@ -213,17 +271,31 @@ function compareIndexes(live: TableDescription, expected: TableDescription): Dri
  * and a constraint that points the same columns at the same table is the same constraint whatever
  * it is called; comparing the name would report drift on a database that is exactly right.
  *
- * `onDelete` is not compared either: the catalog spells it as a single character (`a`, `c`, `r`)
- * and no generated clause declares one, so a snapshot has nothing truthful to hold there. Only the
- * declared side is judged, for the reason `compareIndexes` gives. Named in `wiki/Known-Gaps.md`.
+ * `onDelete` **is** compared now, through `onDeleteRule`. It is not part of a key's identity — a
+ * key is the same key under a different rule, which is why the difference is `changed-foreign-key`
+ * rather than one `missing` — but it is a fact about the database a snapshot records truthfully
+ * since `addForeignKey` spells the clause out. Both sides go through the same normalisation: the
+ * catalog answers `c` where a snapshot holds `cascade`, and Postgres records `a` (`no action`) on
+ * every key that declared nothing.
+ *
+ * Only the declared side is judged, for the reason `compareIndexes` gives.
  */
 function compareForeignKeys(live: TableDescription, expected: TableDescription): DriftDifference[] {
   // The same identity `x db gen` diffs on (`foreign-key.ts`): a generator and a detector that
   // disagreed about whether two keys are the same key is drift on a correct database.
-  const present = new Set(live.foreignKeys.map(foreignKeyTarget));
-  return expected.foreignKeys
-    .filter((key) => !present.has(foreignKeyTarget(key)))
-    .map((key) => missingForeignKey(live.name, key));
+  const present = new Map(live.foreignKeys.map((key) => [foreignKeyTarget(key), key] as const));
+  const differences: DriftDifference[] = [];
+  for (const key of expected.foreignKeys) {
+    const counterpart = present.get(foreignKeyTarget(key));
+    if (counterpart === undefined) {
+      differences.push(missingForeignKey(live.name, key));
+      continue;
+    }
+    if (onDeleteRule(counterpart.onDelete) !== onDeleteRule(key.onDelete)) {
+      differences.push(changedForeignKey(live.name, key, counterpart));
+    }
+  }
+  return differences;
 }
 
 /**

package/src/entity-shape.ts

@@ -0,0 +1,49 @@
+// Single responsibility: the structural mirror of `@ultimat3/entity`'s entity description. `db` is
+// 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.
+
+/** Structurally assignment-compatible with `@ultimat3/entity`'s `ColumnDescription`. */
+export interface ColumnDescriptionLike {
+  readonly property: string;
+  readonly column: string;
+  readonly kind: string;
+  readonly notNull: boolean;
+  readonly primaryKey: boolean;
+  readonly unique: boolean;
+  readonly hasDefault: boolean;
+  readonly check: string | null;
+  readonly references: string | null;
+  /**
+   * The `references()` rule, `null` or absent when none was declared. Optional so a description
+   * written before it existed still satisfies the shape — this package cannot import `entity`, so
+   * the field travelling structurally is the *only* way the rule crosses the tier boundary.
+   */
+  readonly onDelete?: string | null | undefined;
+}
+
+/**
+ * Structurally assignment-compatible with `@ultimat3/entity`'s `IndexDescription`.
+ *
+ * The column list is carried, never recovered from `name`. Entity names an index
+ * `<table>_<a>_<b>_idx`, and that convention does not run backwards: two columns joined by `_`
+ * are one string, so a composite index read back out of its own name became the single column
+ * `"org_id_created_at"` — DDL Postgres answers `42703` and a migration nobody can apply.
+ */
+export interface IndexDescriptionLike {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly unique: boolean;
+  /** Partial index predicate as SQL, `null` when the index covers every row. */
+  readonly where: string | null;
+  /** `null` is Postgres' own default (`asc`), never written out. */
+  readonly order: 'asc' | 'desc' | null;
+}
+
+/** Structurally assignment-compatible with `@ultimat3/entity`'s `EntityDescription`. */
+export interface EntityDescriptionLike {
+  readonly name: string;
+  readonly table: string;
+  readonly primaryKey: readonly string[];
+  readonly columns: readonly ColumnDescriptionLike[];
+  readonly indexes: readonly IndexDescriptionLike[];
+}

package/src/foreign-key.ts

@@ -2,8 +2,35 @@
 // add or drop one. `generate.ts` writes them and `drift.ts` compares them, and a generator that
 // disagreed with a detector about whether two keys are the same key is drift on a correct database.
 
+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',
+};
+
+/**
+ * One `on delete` vocabulary for both sides. The catalog spells the rule as a single character and
+ * a description spells it out, so a comparison between them needs one of them translated — and
+ * translating both through the same total function keeps it idempotent, which is what lets either
+ * side be normalised without knowing where it came from.
+ *
+ * `no action` is `null`: Postgres records the default on **every** key, so reading it as a
+ * declared rule reports a difference against every constraint whose snapshot never spelled one.
+ */
+export function onDeleteRule(raw: string | null): string | null {
+  if (raw === null) return null;
+  const named = CATALOG_RULES[raw] ?? raw.toLowerCase();
+  return named === 'no action' ? null : named;
+}
+
+const WRITABLE = new Set(['cascade', 'restrict', 'set null', 'set default']);
+
 /**
  * A key's identity: its columns, its target table, its target columns — never its name. Postgres
  * names an inline `references` clause `<table>_<column>_fkey` and a hand-written migration may have
@@ -26,12 +53,25 @@ const quoted = (names: readonly string[]): string => names.map((name) => `"${nam
  *
  * The constraint is **named** here rather than left to Postgres' own convention, so the name the
  * snapshot beside it records is a name this migration wrote and not a name it guessed.
+ *
+ * `on delete` is written out, and it had never been: `entity()` has carried the option since 1.0,
+ * it type-checked, and the clause it reached was `references "orgs" ("id");` — a declared cascade
+ * that the database refuses the delete under instead. A rule Postgres does not have is
+ * `X_INVARIANT` rather than DDL, the same discipline `createIndex` applies to an index naming no
+ * column: `entity()`'s option is a closed union, so only a hand-built description can get here.
  */
 export function addForeignKey(table: string, key: ForeignKeyDescription): string {
+  const rule = onDeleteRule(key.onDelete);
+  assert(
+    rule === null || WRITABLE.has(rule),
+    `foreign key "${key.name}" on "${table}" declares an unknown on delete rule`,
+    `references(() => target.id, { onDelete: 'cascade' })   # cascade | restrict | set null`,
+  );
   return (
     `alter table "${table}" add constraint "${key.name}" ` +
     `foreign key (${quoted(key.columns)}) ` +
-    `references "${key.referencedTable}" (${quoted(key.referencedColumns)});`
+    `references "${key.referencedTable}" (${quoted(key.referencedColumns)})` +
+    `${rule === null ? '' : ` on delete ${rule}`};`
   );
 }
 

package/src/generate.ts

@@ -5,8 +5,13 @@
 
 import { assert, systemClock } from '@ultimat3/core';
 import { isDestructive } from './destructive';
+import type {
+  ColumnDescriptionLike,
+  EntityDescriptionLike,
+  IndexDescriptionLike,
+} from './entity-shape';
 import { migrationIrreversible } from './errors';
-import { addForeignKey, dropForeignKey, foreignKeyTarget } from './foreign-key';
+import { addForeignKey, dropForeignKey, foreignKeyTarget, onDeleteRule } from './foreign-key';
 import {
   type ColumnDescription,
   type ForeignKeyDescription,
@@ -16,46 +21,6 @@ import {
   type TableDescription,
 } from './introspect';
 
-/** Structurally assignment-compatible with `@ultimat3/entity`'s `ColumnDescription`. */
-export interface ColumnDescriptionLike {
-  readonly property: string;
-  readonly column: string;
-  readonly kind: string;
-  readonly notNull: boolean;
-  readonly primaryKey: boolean;
-  readonly unique: boolean;
-  readonly hasDefault: boolean;
-  readonly check: string | null;
-  readonly references: string | null;
-}
-
-/**
- * Structurally assignment-compatible with `@ultimat3/entity`'s `IndexDescription`.
- *
- * The column list is carried, never recovered from `name`. Entity names an index
- * `<table>_<a>_<b>_idx`, and that convention does not run backwards: two columns joined by `_`
- * are one string, so a composite index read back out of its own name became the single column
- * `"org_id_created_at"` — DDL Postgres answers `42703` and a migration nobody can apply.
- */
-export interface IndexDescriptionLike {
-  readonly name: string;
-  readonly columns: readonly string[];
-  readonly unique: boolean;
-  /** Partial index predicate as SQL, `null` when the index covers every row. */
-  readonly where: string | null;
-  /** `null` is Postgres' own default (`asc`), never written out. */
-  readonly order: 'asc' | 'desc' | null;
-}
-
-/** Structurally assignment-compatible with `@ultimat3/entity`'s `EntityDescription`. */
-export interface EntityDescriptionLike {
-  readonly name: string;
-  readonly table: string;
-  readonly primaryKey: readonly string[];
-  readonly columns: readonly ColumnDescriptionLike[];
-  readonly indexes: readonly IndexDescriptionLike[];
-}
-
 const SQL_TYPES: Readonly<Record<string, string>> = {
   uuid: 'uuid',
   text: 'text',
@@ -149,8 +114,9 @@ function impliedByColumnClause(
  * beside it chose rather than one it guessed. It is still *not* what drift matches on: see
  * `compareForeignKeys` in `drift.ts`.
  *
- * `onDelete` stays `null`. `entity()` carries the option and no clause here has ever spelled one,
- * so a value written down would be a claim about the database that is not true.
+ * `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
@@ -162,7 +128,7 @@ function foreignKeysOf(entity: EntityDescriptionLike): ForeignKeyDescription[] {
         columns: [column.column],
         referencedTable: table,
         referencedColumns: [key],
-        onDelete: null,
+        onDelete: column.onDelete ?? null,
       };
     })
     .sort((a, b) => (a.name < b.name ? -1 : 1));
@@ -251,17 +217,51 @@ interface Plan {
  * 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 held = new Set((live?.foreignKeys ?? []).map(foreignKeyTarget));
-  for (const key of foreignKeysOf(entity)) {
-    if (held.has(foreignKeyTarget(key))) continue;
-    constraints.up.push(addForeignKey(entity.table, key));
-    constraints.down.push(dropForeignKey(entity.table, key.name));
+  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));
   }
 }
 

package/src/index.ts

@@ -51,6 +51,11 @@ export {
   expectedSchema,
   FRAMEWORK_TABLE_PREFIX,
 } from './drift';
+export type {
+  ColumnDescriptionLike,
+  EntityDescriptionLike,
+  IndexDescriptionLike,
+} from './entity-shape';
 export type { DbErrorCode, DbErrorInit } from './errors';
 export {
   branchExists,
@@ -78,13 +83,7 @@ export {
 export { expectedQueryLoop, expectedQueryLoopReason } from './expected-loop';
 export type { RecordedStatement, RecordingClient, StubResponse } from './fake';
 export { createRecordingClient } from './fake';
-export type {
-  ColumnDescriptionLike,
-  EntityDescriptionLike,
-  GeneratedMigration,
-  GenerateOptions,
-  IndexDescriptionLike,
-} from './generate';
+export type { GeneratedMigration, GenerateOptions } from './generate';
 export { generateMigration, migrationStamp, slugify, snapshotOf } from './generate';
 export type {
   ColumnDescription,

package/src/libpq-options.ts

@@ -54,6 +54,16 @@ function without(tokens: readonly string[], name: string): readonly string[] {
   return kept;
 }
 
+/**
+ * Whether the operator already set `name` in their own `options` — the second spelling of a
+ * setting that also has a URL parameter. A framework DEFAULT may not overwrite either one, and
+ * a default that checks only the parameter leaves the two spellings free to disagree.
+ */
+export function declaresLibpqOption(existing: string | null, name: string): boolean {
+  const assigns = ASSIGNS(name);
+  return splitLibpqOptions(existing ?? '').some((token) => assigns.test(token));
+}
+
 /**
  * The operator's `options` with the framework's settings merged in.
  *

package/src/migrate.ts

@@ -76,7 +76,10 @@ export interface MigrateOptions {
   /** The running build. Defaults to `APP_VERSION`, then `dev`. */
   readonly appVersion?: string | undefined;
   readonly client?: DbClient | undefined;
-  /** Skip the advisory lock. Only `x db branch` does this, against a private database. */
+  /**
+   * Skip the advisory lock, for a database only this process can reach — a branch, a test. No
+   * shipped path passes it; every caller in the repo is a test (`migrate-pin.test.ts`).
+   */
   readonly lock?: boolean | undefined;
   /** How long to wait for the lock before `X_MIGRATE_CONCURRENT`. Defaults to 60s. */
   readonly lockWaitMs?: number | undefined;
@@ -382,7 +385,10 @@ export interface RollbackOptions {
   readonly client?: DbClient | undefined;
   /** How many applied migrations to reverse, newest first. A positive integer; defaults to 1. */
   readonly steps?: number | undefined;
-  /** Skip the advisory lock. Only `x db branch` does this, against a private database. */
+  /**
+   * Skip the advisory lock, for a database only this process can reach — a branch, a test. No
+   * shipped path passes it; every caller in the repo is a test (`migrate-pin.test.ts`).
+   */
   readonly lock?: boolean | undefined;
   /** How long to wait for the lock before `X_MIGRATE_CONCURRENT`. Defaults to 60s. */
   readonly lockWaitMs?: number | undefined;

package/src/pglite-branch.ts

@@ -78,6 +78,9 @@ export async function branchPglite(
 
   return {
     name: branch,
+    // The directory this copy came from — the embedded answer to `BranchInfo.base`'s question,
+    // "whose branch is this". There is no `pg_database` here, so nothing else could be asked.
+    base: from,
     createdAt: (options.now ?? systemClock.now()).toISOString(),
     dataDir: to,
     sizeBytes: await directorySize(to),

package/src/transaction.ts

@@ -207,6 +207,16 @@ export async function withTransaction<T>(
   fn: (tx: DbTx) => Promise<T>,
   options: TransactionOptions = {},
 ): Promise<T> {
+  // Before anything opens. `attempts = retry + 1` turned a negative, fractional or NaN budget into
+  // a loop that never ran its body: `fn` was called ZERO times and the caller was handed
+  // `X_DB_SERIALIZATION_FAILURE` — "lost its serialization race on all 0 attempts" — for a
+  // transaction that was never begun. `Number(process.env.DB_RETRY)` on an unset var is how the
+  // NaN arrives, and the nested branch below already refuses a budget it cannot honour.
+  assert(
+    options.retry === undefined || (Number.isInteger(options.retry) && options.retry >= 0),
+    `withTransaction({ retry }) needs a whole number of extra attempts, 0 or more; a budget that is not one opens nothing and runs fn zero times`,
+    "pass an integer — withTransaction(fn, { retry: 3, isolation: 'serializable' }) — and parse it before you pass it: Number(process.env.DB_RETRY) is NaN when the variable is unset",
+  );
   const outer = storage.getStore();
   if (outer !== undefined) {
     // A nested scope is a SAVEPOINT, and a savepoint cannot survive the thing `retry` exists for: