@ultimat3/db 2.0.0 → 4.0.0

package/CLAUDE.md

@@ -11,6 +11,7 @@ reaches down to this package for it. **Never** import `entity`, `jobs`, `http` o
 | SQL | `sql` binds `$n`; anything non-scalar and non-fragment throws `X_SQL_UNSAFE` |
 | Escape hatches | `raw()`, `identifier()`, `literal()` — each call is an audit point |
 | SQLSTATE | one reader, `sqlState()` (`sqlstate.ts`). Never read `error.code` for a SQLSTATE |
+| Reading a caught value | `renderThrowable()` from core; never `error instanceof Error ? error.message : String(error)` — both halves RUN app code (a `Proxy` trap, `Symbol.toPrimitive`) and `checkDb` backs `/readyz`, where a render that throws is an exception in place of the report the kubelet asked for |
 | Errors | subclass `DbError`; never `throw new Error` **in source**. A test simulating a *database* failure throws `dbUnavailable()`; a test simulating the *caller's body* failing throws a bare `Error` on purpose — an arbitrary throw is exactly what rollback and disposal must survive, and a `DbError` there would prove the narrower thing |
 | New code | add to `DB_ERROR_CODES` **and** `DB_ERROR_TITLES` in `errors.ts` |
 | Exports | explicit in `src/index.ts`; no `export *` |
@@ -148,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
@@ -318,6 +323,44 @@ block is the join of that fix with the engine it ships through — an entity des
 `generateMigration`, applied by `migrate()` itself against a real server, columns confirmed against
 `pg_indexes`, rather than either half alone.
 
+**The ledger audit asks one question — does this build ship every migration the ledger records?**
+`auditLedger`'s `foreign` filter is `!known.has(row.id)` and nothing else, `As of 2026-08`. It used
+to also require `row.app_version !== appVersion`, which switched the audit OFF wherever the two
+agree: `runningAppVersion()` answers `dev` for every development build, so a migration applied by an
+earlier `dev` build and since deleted was invisible, and `expectedSchema` (`drift.ts`) then dropped
+its table from the comparison — `x db drift` answering `ok: true` against a database that still has
+the table. The version is a detail of the ANSWER and lives in the cause, never in the predicate.
+
+**`rollback({ steps })` refuses anything that is not a positive safe integer, before the lock.**
+`steps` reaches `slice(0, steps)`, where a negative count counts from the END: `steps: -1` selected
+every applied migration but the newest and reversed four of five. `X_INVARIANT` (core's generic
+code, borrowed in `DB_BORROWED_ERROR_CODES` the way `@ultimat3/money`'s `roundRatio` borrows it —
+a bad argument is not a fact about the ledger), thrown by `rollbackStepsInvalid` before the advisory
+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. (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
 disagreement is the whole reason this is a bug rather than a preference: `pglite.ts` calls
@@ -447,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
@@ -461,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`.
@@ -481,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
@@ -562,6 +641,20 @@ itself all reach the caller, and every caller must handle that. Layers 3–4 (pr
 policy) live in `@ultimat3/mcp`, which must still never import this package — the CLI wires the
 two together.
 
+**`libpq-options.ts` merges the framework's `options` into the operator's, and `connectionUrl` may
+not `set` that key again.** `DATABASE_URL` is the operator's file: `url.searchParams.set('options',
+…)` REPLACED whatever they had written, and only on the roles whose `statementTimeoutMs` is
+non-zero — so `?options=-c search_path=app` survived on `migrate` and `replicator` and was dropped
+on `web`, `sync`, `worker` and `scheduler`, i.e. the role that runs the migrations and the role that
+serves the traffic looked at different schemas with nothing reporting it. Precedence is **the
+framework wins on the names it sets, the operator keeps every other flag**, and it is enforced by
+removing those names from the operator's tokens before appending, never by position: "the last `-c`
+wins" is backend argument-order behaviour nobody here measured. The bound is emitted for all six
+roles including the two whose value is `0` — `0` is `migrate` saying it may take as long as it
+takes, and left unsaid an `alter database … set statement_timeout` on the server kills the one role
+that must outlive it. The splitter honours libpq's backslash escape, so a `search_path=two\ words`
+survives the round trip whole.
+
 ```bash
 bun test                      # from packages/db
 bun run typecheck

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,11 +136,15 @@ 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` reports
-them and exits non-zero; a `ROLE=migrate` container logs them and still exits 0, because its
-contract is "apply every migration, then exit" and a schema difference after a clean apply is a
-diagnostic, not a failed 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
+(`assertNoDrift`, in `runRole`) and exits non-zero too, because the release phase has one channel —
+the exit code — and a deploy that rolled on past a schema nobody can reconstruct is the failure
+drift exists to catch. There is no `x db drift`, and `x verify`'s `drift` step is the *source*
+detector (`checkSourceDrift`), which needs no database and never calls this.
 
 ## The embedded database
 
@@ -198,6 +202,16 @@ does reach the backend: `client.live.test.ts` asserts `current_setting('statemen
 is the only reading a DSN test cannot fake. `Bun.SQL` is reached lazily, so importing this package
 never opens a socket.
 
+**That setting is MERGED into the operator's own `options`, never assigned over them** (`As of
+2026-08`). `?options=-c search_path=app` in `DATABASE_URL` survives on every role, and the role's
+`statement_timeout` is appended to it; if the URL sets `statement_timeout` itself, the **role
+wins** — it is a bound the pool is sized around — and every other flag is kept. It is emitted for
+all six roles, `migrate`'s and `replicator`'s `0` included: `0` is "this role may take as long as
+it takes", and left unsaid a server-side `alter database … set statement_timeout` would kill the
+one role that has to outlive it. Before this, `set` replaced the whole value and only on the roles
+with a non-zero timeout, so a `search_path` survived on `migrate` and vanished on `web` — the role
+that runs the migrations and the role that serves the traffic reading different schemas.
+
 **`DATABASE_POOL_MAX` overrides `max`** (`As of 2026-08`), and it is the only pool knob an operator
 can turn without shipping an image — 400 `web` pods × the frozen `max: 20` is 8,000 backends. A
 value that is not a positive integer refuses at boot rather than falling back.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "2.0.0"
+    "@ultimat3/core": "4.0.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,14 +157,36 @@ 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;
-    if (new Date(branch.createdAt).getTime() > cutoff) continue;
+    const createdAtMs = Date.parse(branch.createdAt);
+    // `NaN > cutoff` is `false`, which is the same answer "older than the cutoff" gives — so a
+    // truncated or hand-edited comment used to be a database DROPPED on the next sweep, whatever
+    // `maxAgeMs` said. An age nothing can read is not an old age.
+    if (!Number.isFinite(createdAtMs)) continue;
+    // Finite is not enough: `'2026-08-18T10:00'` parses as LOCAL time, so a truncated comment
+    // names an instant hours from the one it reads as, and the sweep acts on a date nobody wrote.
+    // `createBranch` writes `toISOString()` and nothing else does, so a value that does not round
+    // trip through it is not ours — there is no legitimate non-canonical comment to strand.
+    if (new Date(createdAtMs).toISOString() !== branch.createdAt) continue;
+    if (createdAtMs > cutoff) continue;
     await dropBranch(branch.name, options);
     dropped.push(branch.name);
   }

package/src/client.ts

@@ -3,10 +3,11 @@
 // pool like a `web` process behind a CDN. `Bun.SQL` is reached lazily so importing this module
 // never opens a socket (the CLI imports it to print help).
 
-import { type Role, resolveRole } from '@ultimat3/core';
+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 { declaresLibpqOption, mergeLibpqOptions } from './libpq-options';
 import { statementObserver } from './observe';
 import { type SqlFragment, sql } from './sql';
 import { withStatementSpan } from './statement-span';
@@ -172,11 +173,32 @@ function connectionUrl(options: PostgresClientOptions, profile: PoolProfile): st
   } catch (error) {
     throw dbUnavailable(`DATABASE_URL is not a valid url: ${raw}`, error);
   }
-  // libpq `options` is the portable way to pin a statement timeout for every pooled connection.
-  if (profile.statementTimeoutMs > 0) {
-    url.searchParams.set('options', `-c statement_timeout=${profile.statementTimeoutMs}`);
-  }
-  url.searchParams.set('application_name', options.applicationName ?? 'ultimate');
+  // libpq `options` is the portable way to pin a statement timeout for every pooled connection —
+  // MERGED into the operator's own, never assigned over it, and emitted for every role including
+  // the two whose bound is 0. `set` here dropped a `?options=-c search_path=app` on `web`, `sync`,
+  // `worker` and `scheduler` and kept it on `migrate` and `replicator`, so the role that runs the
+  // 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.
+  // `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();
 }
 
@@ -447,7 +469,9 @@ export async function checkDb(client: DbClient = baseClient()): Promise<DbHealth
     return {
       ok: false,
       latencyMs: Math.round(performance.now() - started),
-      error: error instanceof Error ? error.message : String(error),
+      // `renderThrowable`, never `error.message`: the probe wants a report, and a render that
+      // throws is an exception out of `/readyz` — the one caller that cannot catch it.
+      error: renderThrowable(error),
     };
   }
 }

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;
 }
 
 /**
@@ -294,7 +366,13 @@ export function driftError(difference: DriftDifference): DbError {
   });
 }
 
-/** Throws the first difference. `x verify` calls this; `x db drift --json` reads the report. */
+/**
+ * Throws the first difference. The one caller is the release phase — `runRole` in `@ultimat3/cli`
+ * under `ROLE=migrate`, where the exit code is the only channel a container has. `x db migrate`
+ * and `x db reset` hold the same report and render every difference as a finding instead
+ * (`driftFindings`), and `x verify`'s `drift` step is the *source* detector (`checkSourceDrift`),
+ * which never reaches this function. There is no `x db drift` command.
+ */
 export function assertNoDrift(report: DriftReport): void {
   const first = report.differences[0];
   if (first !== undefined) throw driftError(first);

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/errors.ts

@@ -32,8 +32,17 @@ export const DB_OWNED_ERROR_CODES = [
  * `@ultimat3/core`'s. Never titled here, never registered here. `X_ENV_MISSING` is core's word for
  * "a variable this process was given is missing or invalid", and `DATABASE_POOL_MAX` is one — a
  * db-local code for it would be a second answer to a question core already answers.
+ *
+ * `X_INVARIANT` is core's own "the generic code, for checks that have no dedicated code yet"
+ * (`assert()` in `core/src/assert.ts`), borrowed the same way `@ultimat3/money`'s `roundRatio`
+ * borrows it: an argument a caller built wrong is not a fact about the ledger or the schema, so
+ * none of the `X_MIGRATION_*` codes above describes one.
  */
-export const DB_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED', 'X_ENV_MISSING'] as const;
+export const DB_BORROWED_ERROR_CODES = [
+  'X_NOT_IMPLEMENTED',
+  'X_ENV_MISSING',
+  'X_INVARIANT',
+] as const;
 
 /** Every code db can throw: the ones it owns plus the ones it borrows. */
 export const DB_ERROR_CODES = [...DB_OWNED_ERROR_CODES, ...DB_BORROWED_ERROR_CODES] as const;
@@ -249,6 +258,21 @@ export const migrationConflict = (cause: string, fix: string): DbError =>
 export const migrationIrreversible = (cause: string, fix: string): DbError =>
   new DbError({ code: 'X_MIGRATION_IRREVERSIBLE', cause, fix });
 
+/**
+ * A rollback step count this build cannot honour. `steps` reaches `Array.prototype.slice`, where a
+ * negative count counts from the END: `steps: -1` selected every applied migration except the
+ * newest and reversed four of five, which is the one class of mistake a rollback cannot undo.
+ * Refused rather than coerced, exactly as `DATABASE_POOL_MAX` is — a number silently reinterpreted
+ * as a different one is the failure a validated argument exists to prevent.
+ */
+export const rollbackStepsInvalid = (received: number): DbError =>
+  new DbError({
+    code: 'X_INVARIANT',
+    cause: `rollback was asked to reverse ${String(received)} migrations, which is not a positive integer`,
+    fix: 'rollback({ migrations, steps: 1 })   # a whole number of migrations, newest first',
+    meta: { steps: received },
+  });
+
 /**
  * `packages/db/migrations/0000_initial.snapshot.json` → `packages/db/migrations/0000_initial.*` —
  * every file that one migration owns, as one `rm` argument. Derived from the path the caller passed

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,
@@ -71,19 +76,14 @@ export {
   multipleStatements,
   poolAcquireTimeout,
   poolMaxInvalid,
+  rollbackStepsInvalid,
   serializationExhausted,
   sqlUnsafe,
 } from './errors';
 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

@@ -0,0 +1,86 @@
+// Single responsibility: merging the framework's own libpq `options` into whatever the operator
+// already put in `DATABASE_URL`. A connection string is the operator's file, not the framework's,
+// and `searchParams.set` on a key they may have written is a silent overwrite of their setting.
+
+/**
+ * libpq hands `options` to the backend as command-line arguments, split on whitespace with a
+ * backslash escaping the next character. Escapes are kept intact, so re-joining the tokens
+ * reproduces the operator's string byte for byte.
+ */
+export function splitLibpqOptions(options: string): readonly string[] {
+  const tokens: string[] = [];
+  let current = '';
+  let open = false;
+  for (let index = 0; index < options.length; index += 1) {
+    const char = options[index] ?? '';
+    const escaped = options[index + 1];
+    if (char === '\\' && escaped !== undefined) {
+      current += `\\${escaped}`;
+      open = true;
+      index += 1;
+      continue;
+    }
+    if (char.trim() === '') {
+      if (open) tokens.push(current);
+      current = '';
+      open = false;
+      continue;
+    }
+    current += char;
+    open = true;
+  }
+  if (open) tokens.push(current);
+  return tokens;
+}
+
+/**
+ * The three spellings a backend accepts for one GUC on the command line: `-c name=value` as two
+ * arguments, `-cname=value` as one, and `--name=value` (where a hyphen in the name reads as an
+ * underscore). A bare `name=value` token is the second half of the first spelling.
+ */
+const ASSIGNS = (name: string): RegExp => new RegExp(`^(?:-c|--)?${name.replaceAll('_', '[_-]')}=`);
+
+/** Drops every assignment of `name`, and the `-c` that introduced it. */
+function without(tokens: readonly string[], name: string): readonly string[] {
+  const assigns = ASSIGNS(name);
+  const kept: string[] = [];
+  for (const token of tokens) {
+    if (!assigns.test(token)) {
+      kept.push(token);
+      continue;
+    }
+    if (kept.at(-1) === '-c') kept.pop();
+  }
+  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.
+ *
+ * **Precedence: the framework wins on the settings it names, the operator keeps everything else.**
+ * A role's `statement_timeout` is a safety bound the role is sized around — `web`'s 10s is what
+ * stops a slow endpoint holding all 20 pool slots — so a value in the URL may not raise it; but a
+ * `search_path`, an `application_name` or a `-c` an operator added is theirs and must survive.
+ * Enforced by removing the framework's own names before appending, never by position: relying on
+ * "the last `-c` wins" would make the bound depend on backend argument order nobody here measured.
+ */
+export function mergeLibpqOptions(
+  existing: string | null,
+  settings: Readonly<Record<string, string>>,
+): string {
+  let tokens = splitLibpqOptions(existing ?? '');
+  for (const [name, value] of Object.entries(settings)) {
+    tokens = [...without(tokens, name), '-c', `${name}=${value}`];
+  }
+  return tokens.join(' ');
+}

package/src/migrate.ts

@@ -11,7 +11,7 @@ import {
   isReservable,
   poolProfileFor,
 } from './client';
-import { migrateConcurrent, migrationConflict } from './errors';
+import { migrateConcurrent, migrationConflict, rollbackStepsInvalid } from './errors';
 import { expectedQueryLoop } from './expected-loop';
 import type { SchemaDescription } from './introspect';
 import { raw, sql } from './sql';
@@ -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;
@@ -149,7 +152,13 @@ export function auditLedger(
 ): void {
   const known = new Map(migrations.map((migration) => [migration.id, migration]));
 
-  const foreign = ledger.filter((row) => !known.has(row.id) && row.app_version !== appVersion);
+  // The predicate is "this build does not ship it" and NOTHING else. It used to also require
+  // `row.app_version !== appVersion`, which switched the audit off wherever the two agree —
+  // `runningAppVersion()` answers `dev` for every development build, so a migration applied by an
+  // earlier `dev` build and since deleted was invisible here, and `expectedSchema` then dropped
+  // its table from the drift comparison: `ok: true` against a database that still has the table.
+  // The version is a detail of the ANSWER, so it moved into the cause.
+  const foreign = ledger.filter((row) => !known.has(row.id));
   const first = foreign[0];
   if (first !== undefined) {
     throw migrationConflict(
@@ -374,8 +383,12 @@ export async function migrate(options: MigrateOptions): Promise<MigrationReport>
 export interface RollbackOptions {
   readonly migrations: readonly Migration[];
   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;
@@ -387,6 +400,9 @@ export interface RollbackOptions {
 export async function rollback(options: RollbackOptions): Promise<readonly string[]> {
   const client = options.client ?? baseClient();
   const steps = options.steps ?? 1;
+  // Before the lock and before the ledger read: `slice(0, -1)` is "all but the newest", not
+  // "one fewer", so an unvalidated count reverses migrations nobody asked about.
+  if (!Number.isSafeInteger(steps) || steps < 1) throw rollbackStepsInvalid(steps);
   const lockTimeoutMs = migrationLockTimeoutMs(options.lockTimeoutMs);
   const known = new Map(options.migrations.map((migration) => [migration.id, migration]));
 

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: