@ultimat3/db 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -35,47 +35,48 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   only while its turn is held. `pglite-embedded.test.ts`, `pglite.test.ts`,
   `pglite-two-clients.test.ts`, `pglite-observer.test.ts`.
 - **The third rule is both drivers'**: `client.ts`'s pinned handle also runs direct only while held.
-  `release()` is idempotent on both; `DbConnection` and `Turn` are `Disposable` (`[Symbol.dispose]` is
-  `release()`).
+  `release()` is idempotent on both; `DbConnection` and `Turn` are `Disposable`.
 - **A pin is held by `using`, never a hand-rolled `try/finally`** (`withTransaction`,
   `readOnlyQuery`); `BEGIN` lives inside the guarded scope.
-- **`sqlstate.ts`**: `errno` first, `code` second, both shape-tested (`^[0-9A-Z]{5}$`).
-  `DB_SQLSTATE_CODES` is closed; `driverError()` is its one consumer, `sendOn` its one caller.
+- **`sqlstate.ts`**: `errno` first, `code` second, shape AND provenance (`isState`: `severity` =
+  server; `syscall`/numeric `errno` = socket; else needs a digit). `DB_SQLSTATE_CODES` is closed; `driverError()` is its one consumer, `sendOn` its one caller.
 - **`DbTx.origin` is the client the scope was opened on**, never the pin (entity's pinned-repository
   check reads it); a nested scope reports the root's.
 - **`withTransaction(fn, { retry })` re-runs `fn` only on `40001`/`40P01`**, default 0; each attempt
   its own pin, `BEGIN` and undo list (`runRoot`); a nested `retry` is `X_INVARIANT`. A re-run waits
-  (`transaction-backoff.ts`: core's `backoffDelay`, 10 ms → 500 ms, full jitter; `{ sleep, random }`
-  are injection seams); nothing waits at retry 0 or after the last attempt.
-- **Four codes are classified `retryable`** (`DB_ERROR_RETRY`: `X_DB_SERIALIZATION_FAILURE`,
-  `X_DB_LOCK_TIMEOUT`, `X_DB_POOL_EXHAUSTED`, `X_MIGRATE_CONCURRENT`); terminal ones are deliberately
-  unclassified (`errors-retry.test.ts` asserts the absence). Core's `retry()` executor is NOT adopted.
-- **`BEGIN` re-derives its isolation level from the closed set** (`isolationMode` switch with a `never`
-  default; anything else `X_SQL_UNSAFE`).
-- Transaction control: `ROLLBACK` / `ROLLBACK TO SAVEPOINT` are best-effort; `SAVEPOINT` and
-  `RELEASE SAVEPOINT` are deliberately uncaught.
-- **`close()` is BOUNDED by the driver's own `{ timeout }` in SECONDS** (`drainTimeoutMs / 1000`);
-  `drainTimeoutMs: 0` sends no option; the verdict is elapsed time on `performance.now()`
-  (`X_DB_DRAIN_TIMEOUT`). `pool-drain.test.ts`, `pool-drain.live.test.ts`. `close()` clears the cached
-  driver before awaiting the teardown.
+  (`transaction-backoff.ts`: 10 ms → 500 ms, full jitter; `{ sleep, random }` are seams).
+- **Four codes are `retryable`** (`DB_ERROR_RETRY`); terminal ones stay unclassified
+  (`errors-retry.test.ts`). Core's `retry()` executor is NOT adopted.
+- **`BEGIN` re-derives its isolation level from the closed set** (`isolationMode`; else `X_SQL_UNSAFE`).
+- **An aborted transaction is reported** (`X_DB_TRANSACTION_ABORTED`; README "Transactions that end
+  badly"): a failure carrying a SQLSTATE marks the root's `abort`, only a successful `ROLLBACK TO`
+  clears it (a failed one sets it), and `COMMIT` is then refused unsent. `commit-tag.ts` reads the
+  COMMIT tag in BOTH funnels. `COMMIT` rejecting with no SQLSTATE is `X_DB_COMMIT_UNKNOWN`: neither
+  list runs. `transaction-errors.ts`; `transaction-options.ts` holds `DbTx`, options, `BEGIN` text.
+- **Sibling nested scopes take turns** (`TxState.children`; savepoints are a stack) under a deadline
+  (`sibling-turn.ts`, `siblingWaitMs`, `X_DB_SIBLING_SCOPE_TIMEOUT`). A nested
+  `isolation`/`readOnly`/`deferrable`/foreign `client` is `X_INVARIANT`.
+- **`close()` is BOUNDED by the driver's own `{ timeout }` in SECONDS** (`drainTimeoutMs / 1000`; `0`
+  sends none); the verdict is elapsed `performance.now()` (`X_DB_DRAIN_TIMEOUT`). It clears the
+  cached driver before awaiting the teardown. `pool-drain{,.live}.test.ts`.
 - **`client.listen` is ONE session beside the pool** (`listen.ts`; `Bun.SQL.listen`, PGlite's
   `listen` under a turn), never a reserved pin. `onListening` fires on every re-dial; a channel is
   refused unless it is a plain identifier. `listen.test.ts`, `listen.live.test.ts`.
 - `execute()` trusts the command tag only when `> 0`, in both drivers (`rowsOf`, `affectedBy`).
-- **`pool-gauge.ts` derives `db_pool_max` / `db_pool_in_use` / `db_pool_waiting` from DEMAND** —
-  `Bun.SQL` publishes no occupancy. `client.ts` is the one counter: `run()` from send to settle, a
-  pin from the ask to its (idempotent) release; a statement ON a pin is not counted again. Declared
-  on the first tracked pool, never at import. `pool-gauge.test.ts`.
+- **`pool-gauge.ts` derives `db_pool_max` / `db_pool_in_use` / `db_pool_waiting` from DEMAND**
+  (`Bun.SQL` publishes no occupancy). `client.ts` is the one counter: `run()` from send to settle, a
+  pin from ask to release; a statement ON a pin is not counted again. Declared on the first pool.
 - **`client.ts` connects, holds the client and the ambient `db()`**, and opens no socket at import;
   `pool-profile.ts`, `connection-url.ts`, `bun-sql.ts`, `pool-reserve.ts`, `db-health.ts` (`checkDb`)
   and `statement-funnel.ts` (`sendOn`/`runOn`) hold the rest.
-- **`libpq-options.ts` merges the framework's `options` into the operator's**: the framework wins on
-  the names it sets, the operator keeps every other flag; the bound is emitted for all six roles.
+- **`libpq-options.ts` merges the framework's `options` into the operator's**: the framework wins
+  on the names it sets, the operator keeps the rest; emitted for all six roles.
 - **`DATABASE_URL`'s scheme is screened at boot** (`POSTGRES_SCHEMES`: `postgres:`, `postgresql:`); the
-  received scheme is never echoed (it may be a host or a credential). `connection-url.test.ts`.
+  received scheme is never echoed (it may be a credential).
 - **A JS array bound as a parameter is rendered here** (`array-parameter.ts`, `bound-parameters.ts`,
   called only by `sendOn`) — `Bun.SQL` joins elements with commas. `NULL` bare vs `"NULL"`; quoting by
-  content; a `Uint8Array` is BYTEA; a ragged nest is refused. `array-parameter.live.test.ts`;
+  content; a `Uint8Array` is BYTEA, in an array too; a ragged nest and an Invalid Date are refused
+  (`X_INVARIANT`), ABOVE the driver's `try` in both funnels. `array-parameter.live.test.ts`;
   `packages/cli/src/pg-array.live.test.ts` is the composition test.
 - **Every numeric option is screened** through core's `finiteCount` (`replicaClient`'s breaker,
   `migrate`'s `lockWaitMs`, `readonlyQuery`'s `timeoutMs` — only an explicit `0` disables it — the pool
@@ -83,11 +84,10 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 
 ## Observation
 
-- **`observe.ts`: one process-wide `StatementObserver`** (`setStatementObserver()` /
-  `statementObserver()`). Guard at the call site; one observer, not a list; the seam swallows nothing;
-  `onStatement` is synchronous and must not issue SQL. Only `runOn` (`statement-funnel.ts`) and
-  `statement()` (`pglite.ts`) invoke it; both observe success and failure, and notify outside the
-  statement's own `try`.
+- **`observe.ts`: one process-wide `StatementObserver`** (`setStatementObserver()`). Guard at the
+  call site; one observer, not a list; the seam swallows nothing; `onStatement` is synchronous and
+  must not issue SQL. Only `runOn` (`statement-funnel.ts`) and `statement()` (`pglite.ts`) invoke
+  it; both observe success and failure, and notify outside the statement's own `try`.
 - **`attribution.ts`**: `withStatementAttribution(entity, op, fn)` — guard first (two strings, no
   allocation), a scope not a parameter, innermost pair wins; the funnels stamp it on both settle paths.
   `@ultimat3/entity`'s `postgresRepo` is the one producer.
@@ -95,20 +95,19 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   text) and `statementKind(text)` off `statementVerb(text)`. Read by `x dev`'s ledger and
   `@ultimat3/testing`'s `statements` fixture. It counts nothing.
 - **`statement-span.ts`**: `withStatementSpan` wraps the send alone — `db.<verb>`, attribute
-  `STATEMENT_ATTRIBUTE` (exported; `@ultimat3/cli`'s `dev-traces.ts` imports it), OTel kind `client`,
-  opened only when an observer is installed.
+  `STATEMENT_ATTRIBUTE` (`@ultimat3/cli`'s `dev-traces.ts` imports it), OTel kind `client`, opened
+  only when an observer is installed.
 - **`expected-loop.ts` is the ONLY suppression**: `expectedQueryLoop(reason, fn)`, innermost reason,
-  blank is `X_INVARIANT`; the funnel stamps `expected`; it suppresses a verdict, never a statement. The
-  framework's own loops declare themselves (`migrate()`, `rollback()`, `@ultimat3/admin`'s
-  `search.ts`).
-- `@ultimat3/jobs` never imports this package; its statements pass the observer only because
-  `packages/cli/src/dev-queue.ts` wraps a real client for its `PgExecutor`, unattributed.
+  blank is `X_INVARIANT`; the funnel stamps `expected`; it suppresses a verdict, never a statement.
+  The framework's own loops declare themselves (`migrate()`, `rollback()`, admin's `search.ts`).
+- `@ultimat3/jobs` never imports this package; its statements pass the observer only as
+  `packages/cli/src/runtime-queue.ts` wraps a real client for its `PgExecutor`, unattributed.
 
 ## Migrations
 
 - **The migration lock is polled** (`pg_try_advisory_lock` every `MIGRATION_LOCK_POLL_MS` until
   `MIGRATION_LOCK_WAIT_MS`, then `X_MIGRATE_CONCURRENT`), declared with `expectedQueryLoop`;
-  `createRecordingClient` stubs the lock as `locked: true`.
+  `recordingClient` stubs the lock as `locked: true`.
 - **`lock_timeout` is the migration's** (`SET LOCAL` inside each migration's transaction, from the
   `migrate` profile's 3 s).
 - **The advisory lock is held by one pinned session, and `migrate()`/`rollback()` run every statement
@@ -130,8 +129,8 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   (`rollbackStepsInvalid`, `X_INVARIANT`).
 - **`refuseDependentViews(tx, script)`** (`dependent-view.ts`) runs before each migration's first
   statement: a word scan over `sql-scan.ts` finds retyped columns, one catalog round trip, the pair
-  filtered in JS, and `X_MIGRATION_VIEW_DEPENDS` carries the `drop view` / `create view` from
-  `pg_get_viewdef` (built through `identifier()` inside a `try`).
+  filtered in JS (visible tables only), and `X_MIGRATION_VIEW_DEPENDS` carries the `drop view` /
+  `create view` from `pg_get_viewdef` (built through `identifier()` inside a `try`).
 - `runningAppVersion()` delegates to core's `appVersion()`.
 
 ## Generation (`x db gen`)
@@ -142,7 +141,7 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   declared is CLOSED, live is OPEN (`indexMethodOf` passes the catalog through; `declaredMethod`
   refuses); absent is `btree` through one function; `snapshotOf` records `using` only when declared;
   `indexMethodSql` re-derives the literal (`X_SQL_UNSAFE` default); a unique or ordered GIN is
-  `X_INVARIANT`. `introspect()` reads `pg_am` (`introspect-embedded.test.ts`).
+  `X_INVARIANT`. `introspectSchema()` reads `pg_am` (`introspect-embedded.test.ts`).
 - **`index-plan.ts` walks both directions** (declared first, removed last). `dropRecordedIndex` emits
   `alter table … drop constraint if exists` then `drop index` for a shape a constraint could back
   (`mayBeConstraintBacked`); four names are skipped (primary, moved aside, rebuilt, over a dropped
@@ -171,59 +170,58 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   in `preAlters` at the top of `up`, re-adding is `foreignKeyPlan`'s, both `breaksOn` ends are needed
   (`generate-retype-key.live.test.ts`). `sql-type.ts` reads `SQL_TYPES` with `Object.hasOwn`.
 - **A generated column** (`generated-column.ts`): the clause right after the type; generated-and-
-  defaulted refused; an expression change is `set expression as (…)`; a retype carries no `using`; a NOT
-  NULL add is one statement; generated → plain is `drop expression`; plain → generated rebuilds the
-  column (`regenerate` answers `rebuilt`) and moves its dependents aside; a generated column's own type
-  change deliberately does not. `introspect` never reads `generation_expression` back.
-  `generate-generated-column.live.test.ts`, `generate-generated-rebuild.live.test.ts`.
-- **`REPLICA IDENTITY FULL` is emitted by a PARAMETER** (`GenerateOptions.replicaIdentityFull`, passed
-  by `@ultimat3/cli`'s `db-generate.ts` from `describeQueries()`' `subscribes:`), in
-  `replica-identity.ts`: recorded as `replicaIdentityFull: true` or absent; the snapshot records the
-  union; dead last in `up`; never destructive; a name no entity declares is skipped; never reverted;
-  `down` is `replica identity default` except on a table this migration creates.
+  defaulted refused; an expression change is `set expression as (…)`; a retype has no `using`; a NOT
+  NULL add is one statement; generated → plain is `drop expression`; plain → generated rebuilds
+  (`rebuilt`) and moves dependents aside, its own type change does not. `introspectSchema` never reads
+  `generation_expression`.
+  `generate-generated-{column,rebuild}.live.test.ts`.
+- **`REPLICA IDENTITY FULL` is a PARAMETER** (`GenerateOptions.replicaIdentityFull`, from the CLI's
+  `db-generate.ts`; `replica-identity.ts`): recorded `true` or absent, as a union; last in `up`; an
+  undeclared name skipped; `down` reverts it unless this migration created the table.
+- **`appendOnly: true` is a trigger** (`generate-append-only.ts`): one `create or replace` function
+  (SQLSTATE `23001`, message leads `X_ENTITY_APPEND_ONLY`) and a fixed-name `ultimate_append_only`
+  `before update or delete … for each row`; recorded `true` or absent; no `truncate`. Drift:
+  enabled `triggerNames` (`drift-append-only.ts`, `X_APPEND_ONLY_TRIGGER_MISSING`).
 - **A foreign key is `alter table … add constraint`**, collected into a bucket merged after every table
   statement (`foreign-key-plan.ts`); **dropping a table has its own bucket emitted BEFORE the table
   statements** (`preDrops`), ordered children-first by `drop-order.ts`, which breaks a two-table cycle
   by dropping one key first. `foreignKeyPlan` walks both directions, drops the name the previous
   snapshot recorded, and rebuilds a key whose `onDelete` moved. **`on delete` reaches the SQL**
   (`onDeleteRule`, `foreign-key.ts`; an unknown rule is `X_INVARIANT`).
-- **`entity-shape.ts` holds the three `*Like` interfaces** (optional `onDelete` / `generated`).
-- **`snapshot-json.ts` writes bytes that are a fixed point of Biome** (arrays collapse when they fit at
-  `<= 100` counting the trailing comma); `snapshot-json.test.ts` runs the repo's own `biome format`.
-- **`declaredSchema()` answers the NEWEST migration's snapshot or `undefined`**; `checkDrift` turns
-  that into `unknown-schema`, and `x db gen` refuses with `X_MIGRATION_SNAPSHOT_MISSING`. Both lead with
-  the same two remedies in the same order: restore the sidecar (`git checkout --`), or delete the
-  migration's files FIRST and only then run `x db gen`. `snapshotSiblings` / `migrationNameOf` build
-  the second command from the caller's path; both commands are screened (`unknownSchema` through
-  `shellInertIdentifier`, `migrationSnapshotMissing` through `renderFixShellArg`), degrading the whole
-  line to prose.
+- **`entity-shape.ts` holds the `*Like` interfaces** (every later field optional).
+- **`snapshot-json.ts` writes a fixed point of Biome** (an array collapses when it fits at `<= 100`
+  with its trailing comma); `snapshot-json.test.ts` runs `biome format`.
+- **`declaredSchema()` answers the NEWEST migration's snapshot or `undefined`** (`checkDrift`:
+  `unknown-schema`; `x db gen`: `X_MIGRATION_SNAPSHOT_MISSING`). Both fixes: restore the sidecar
+  (`git checkout --`), else delete the migration's files FIRST, then `x db gen`; both screened.
 
 ## Drift and introspection
 
 - **`checkDrift()` is the post-migrate verification** (live catalog vs the ledger just written, asked
   by `@ultimat3/cli`'s `runMigrations`), returned never thrown. The OTHER `X_DB_DRIFT` is the CLI's
   `checkSourceDrift`. Neither grows the other's half.
-- `compareTable` compares existence and **nullability** (primary-key columns excluded by the union of
-  both sides' keys); the type is not compared. The `fix:` is the `alter table … set not null` itself.
+- `compareTable` compares existence, **nullability** (the DECLARED key's columns excluded) and the
+  **primary key** in column order (`changed-primary-key`, fix = one `psql -c` of the pair; `primary-key.ts`
+  holds `x db gen`'s arm, its `drop not null`s, its two refusals). The type is not compared.
 - **A missing CHECK is drift, compared by NAME**: `TableDescription.checks` (declared: name and
   expression) vs `TableDescription.checkNames` (catalog: `conname` for `contype = 'c'`, always written
-  by `introspect()`, `[]` included). Only the declared side is judged; no `changed-check`, ever.
+  by `introspectSchema()`, `[]` included). Only the declared side is judged; never a `changed-check`.
   `drift-check.live.test.ts`.
 - `compareTable` judges declared indexes (`missing-index`, `changed-index` over method, column list,
   uniqueness, predicate presence and direction; `asc` normalises to `null`); never the predicate text.
 - `compareForeignKeys` matches on where a key points (`foreignKeyTarget`, the one copy) and compares
-  `onDelete` through `onDeleteRule` (`changed-foreign-key`, fix = drop/add pair).
-- `introspect()` reads index columns in key order (`indkey`) and a foreign key's two column lists
+  `onDelete` through `onDeleteRule` (`changed-foreign-key`; its fix, `changed-column`'s and
+  `missing-check`'s are one `psql -c` too — `repair()`, schema-scoped off `public`).
+- `introspectSchema()` reads index columns in key order (`indkey`) and a foreign key's two column lists
   together (`unnest(a, b) with ordinality`), pinned by `introspect-embedded.test.ts`.
-- **`appTables()`** excludes the whole `x_` namespace for drift; `introspect()` alone excludes
+- **`appTables()`** excludes all of `x_` for drift; `introspectSchema()` alone excludes
   `x_migrations` by default. **`app-relation.ts`**: `nonAppRelations(client, schema)` — extension
   ownership from `pg_depend` (`deptype = 'e'`) plus views, materialised views and foreign tables —
   merged into `excluded` unconditionally.
-- **`unexpectedTable`'s `fix:` never names `x db gen`**: a `create table if not exists` in a migration
-  (accepted by `@ultimat3/cli`'s `acceptCreatedTables`) or dropping a table nothing owns.
-- **`dbDrift()` lives in `drift-errors.ts`** (it needs `shellInertIdentifier`); the `X_DB_DRIFT`
-  rendering and title are duplicated in `@ultimat3/entity`, held equal by
-  `packages/entity/src/errors.test.ts`. `errors.ts` registers `DB_ERROR_TITLES` unconditionally.
+- **`unexpectedTable`'s `fix:` never names `x db gen`**: `psql -c '\d "T"'`, commented with the two
+  repairs (claim it with `create table if not exists`, or drop it).
+- **`dbDrift()` lives in `drift-errors.ts`** (it needs `shellInertIdentifier`) and is the only one —
+  `@ultimat3/entity`'s copy is deleted. `errors.ts` registers `DB_ERROR_TITLES` unconditionally.
 - `drift-findings.ts` holds every `DriftDifference` constructor and `DriftKind`; `drift.ts` keeps the
   comparisons.
 
@@ -231,16 +229,17 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 
 - **Its own entry: `@ultimat3/db/schema-dump`** (`schema-dump-entry.ts`). The barrel is in every
   role's boot graph and must evaluate none of this family — `schema-dump-entry.test.ts`.
-- **Two readings of one catalog, never mixed.** `introspect()` → `SchemaDescription`, the entity
-  vocabulary a snapshot is diffed in. `introspectCatalog()` (`catalog.ts`; queries in `catalog-relations.ts` and
-  `catalog-objects.ts`; the pure fold in `catalog-fold.ts`) → `CatalogDescription`, Postgres' own `pg_get_*def` text, compared only to
+- **Two readings of one catalog, never mixed.** `introspectSchema()` → `SchemaDescription`, the entity
+  vocabulary a snapshot is diffed in. `introspectCatalog()` (`catalog.ts`; queries: `catalog-relations.ts`,
+  `catalog-objects.ts`; pure fold: `catalog-fold.ts`) → `CatalogDescription`, Postgres' own `pg_get_*def` text, compared only to
   itself. A catalog spelling on a `SchemaDescription` field is the `checks`/`checkNames` mistake.
 - **Sorted in JS** (`byCodeUnit`), never `order by` and never `localeCompare`: collations differ.
 - **`renderSchemaDump()` is pure**; `schema-dump-table.ts` spells one table. `quoted()` escapes any
   catalog name — `identifier()` refuses whitespace and `"`, which a migration may have created.
 - **`x_` owner → `framework/` twin** (`FRAMEWORK_TABLE_PREFIX`). No list is handed in.
-- **What cannot be rendered is named** (`unrenderedRows`, a closed list → `unrendered.sql`). A kind
-  rendered later leaves that list in the same diff. Never render a partition as a plain table.
+- **What cannot be rendered is named** (`unrenderedRows`, a closed list → `unrendered.sql`; a trigger
+  on an unrendered relation is named by the fold). A kind rendered later leaves that list in the
+  same diff. Never render a partition as a plain table. `generated` carries `stored`/`virtual`.
 - **`loadSchemaDump()`**: one transaction, `check_function_bodies` off, a savepoint per file, and
   only `42P01`/`42883`/`42704` are retried. Its refusal is `X_SCHEMA_DUMP_DRIFT` (`dump-drift.ts`).
 - **`object-drift.ts`**: `unexpectedObjects(live, expected)` compares IDENTITY (kind, table, name,
@@ -253,16 +252,15 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   by `pgliteExtensionExport` before it reaches a specifier; `plpgsql` is built in, never missing.
   Only a not-found import is `missing`; a bundle that throws is `X_DB_UNAVAILABLE`.
 - **`pglite-snapshot.ts`**: `snapshotDir` makes a `memory://` boot a restore. Key = PGlite version
-  (read off its `package.json`; unreadable = no cache), never the extension set. One file, checksum in its
-  header; unsound or unopenable → deleted and rebuilt; unreadable → a miss. Temp name + `rename`. Uncompressed by
-  measurement: gzip taxes the boot that writes, and a CI checkout always writes.
-- **One embedded boot** serves every database-backed dump test: `schema-dump.test.ts`.
+  (unreadable = no cache), never the extension set. One file, checksum in its header; unsound or
+  unopenable → deleted and rebuilt; unreadable → a miss. Temp name + `rename`. Uncompressed.
+- **Embedded boots for dump tests**: `schema-dump.test.ts` and `schema-dump-fidelity.test.ts`.
 
 ## Branches, replicas, read-only
 
-- **`reapBranches` sweeps branches of THIS database**: the marker is `ultimate:branch:<base>:<iso>`
-  (`BranchInfo.base`), split on the ISO tail; an older one-segment marker is skipped, never dropped; an
-  unparseable `createdAt` is skipped. `@ultimat3/cli`'s `ls`/`drop` scope by name prefix.
+- **`reapBranches` sweeps branches of THIS database**: the marker is `ultimate:branch:<base>:<iso>`,
+  split on the ISO tail; an older one-segment marker or an unparseable `createdAt` is skipped, never
+  dropped. `@ultimat3/cli`'s `ls`/`drop` scope by name prefix.
 - **Read replicas are opt-in twice**: a pool when `DATABASE_REPLICA_URL` names one
   (`default-client.ts`), and a read offered only inside `withReplicaReads(fn)` (`replica-scope.ts`);
   read-your-writes is `ReplicaScope.wrote`, never a request-id map. **`withTransaction` is on the
@@ -287,7 +285,7 @@ Gotchas:
 
 - `exactOptionalPropertyTypes` — declare optional fields as `x?: T | undefined`.
 - `noUncheckedIndexedAccess` — array reads are `T | undefined`; `chunks[i] ?? ''` everywhere.
-- Tests use `createRecordingClient()` + `setDbClient()`; no test may need a live database.
+- Tests use `recordingClient()` + `setDbClient()`; no test needs a live database.
 - A test that must prove a pin came back uses `reservableOver()` (`fake-reservable.ts`), never a copy.
 - `ALTER DEFAULT PRIVILEGES` is scoped to an object's creator, so layer 1 covers future tables only for
   the roles in `creators` (default: the connected user).

package/README.md

@@ -29,7 +29,8 @@ await withTransaction(async (tx) => {
 | `shellInertIdentifier()` | `As of 2026-08-26`: a quoted identifier that is also inert wherever a human PASTES it — or `null`. The one screen a catalog name goes through before it reaches a `fix:`. `identifier()` answers about SQL and **accepts** a backtick and a `$`, which are exactly what a shell substitutes inside double quotes, so a column called `$(id)` inside `x db gen "add $(id)"` runs `id` on paste |
 | `db()` / `baseClient()` / `setDbClient()` | the ambient client; `db()` returns the open tx if any |
 | `DbTx.origin` | `As of 2026-08`: the client the transaction was **opened on** — `options.client` or `baseClient()`, never the reservation it runs statements through. `@ultimat3/entity` compares a pinned repository's client against it, so a pinned repo joins its own shard's transaction instead of being refused |
-| `withTransaction()` / `currentTx()` | transaction scope; `currentTx()` is the outbox seam. `{ retry: n }` (`As of 2026-08`) re-runs `fn` from the top on a `40001`/`40P01` and on nothing else — default 0, so `fn` must be idempotent before you ask for it. Each re-run **waits first**, `As of 2026-08-23`: exponential from 10ms, capped at 500ms, full jitter (`@ultimat3/core`'s `backoffDelay`). A budget of 0 waits not at all |
+| `withTransaction()` / `currentTx()` | transaction scope; `currentTx()` is the outbox seam. `{ retry: n }` (`As of 2026-08`) re-runs `fn` from the top on a `40001`/`40P01` and on nothing else — default 0, so `fn` must be idempotent before you ask for it. Each re-run **waits first**, `As of 2026-08-23`: exponential from 10ms, capped at 500ms, full jitter (`@ultimat3/core`'s `backoffDelay`). A budget of 0 waits not at all. **A transaction the server aborted is reported as one**, `As of 2026-10-02` → [Transactions that end badly](#transactions-that-end-badly) |
+| `liveTxConnection()` | the connection of the transaction still **open** on this async context, or `undefined`. `currentTx()` keeps answering a finished scope's handle to a promise chain the body forgot to await; this is the one that says whether a statement sent now is really inside a transaction. `@ultimat3/action` reads it before binding an idempotency settlement to a commit |
 | `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 |
@@ -37,7 +38,7 @@ await withTransaction(async (tx) => {
 | `replicatedClient()` / `ReplicaStats` / `REPLICA_URL_ENV` | `As of 2026-08-24`: one `DbClient` over a primary and a standby. `baseClient()` builds one when `DATABASE_REPLICA_URL` is set and the single-pool client when it is not |
 | `INDEX_METHODS` / `IndexMethod` / `indexMethodOf()` / `indexMethodSql()` / `declaredMethod()` / `isIndexMethod()` | `As of 2026-08-24`: an index's access method — `btree` or `gin`, closed. Absent is `btree`, the live side is read open (whatever `pg_am` said), and the DDL literal is re-derived from the set rather than spliced from the input |
 | `isPlainRead()` | `As of 2026-08-24`: whether a statement may leave the primary. An allow-list — everything it cannot vouch for is the primary's |
-| `checkDrift()` / `diffSchema()` / `assertNoDrift()` | drift, with a `--json` report. `checkDrift()` is the **post-migrate verification** — the live database against the ledger: columns, declared indexes (access method `As of 2026-08-24`, columns, uniqueness, direction, and whether a predicate is there at all — never its text), declared CHECK constraints by NAME (`missing-check`, `As of 2026-08-25` — never a predicate, which the catalog answers rewritten) 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` |
+| `checkDrift()` / `diffSchema()` / `assertNoSchemaDrift()` | drift, with a `--json` report. `checkDrift()` is the **post-migrate verification** — the live database against the ledger: columns, declared indexes (access method `As of 2026-08-24`, columns, uniqueness, direction, and whether a predicate is there at all — never its text), declared CHECK constraints by NAME (`missing-check`, `As of 2026-08-25` — never a predicate, which the catalog answers rewritten) 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 |
@@ -48,18 +49,18 @@ await withTransaction(async (tx) => {
 | `declaredChecks()` / `checkClauses()` / `checkPlan()` / `columnChecks()` / `columnCheckName()` / `columnNamesConstraint()` | `As of 2026-08-25`: **every** CHECK a table declares — a column's own (`enumerated()`'s value set, `tz()`'s IANA whitelist, `locale()`'s tags, money's currency pattern and scale bound) and an invariant's — on ONE list, so `createTable`, `diffTable` and `snapshotOf` agree about what exists. A column's check reached `create table` **inline and anonymous** and nothing else: the snapshot recorded none and the diff had no arm, so a value added to `enumerated()` generated no migration and a regenerated ENUM column came back as bare `text`. The name is `<table>_<column>_check` because that is the name **Postgres itself mints** for the old anonymous form — measured — so the repair lands on the constraint an already-generated database is holding; `checkPlan` emits `drop constraint if exists` before the `add` for exactly that column, because a bare add is `42710` there and a no-op everywhere else |
 | `defaultExpression()` / `ColumnDefaultLike` | `As of 2026-08-25`: a column's `default` as SQL. A DECLARED default (`{ kind: 'value', value }`) wins; `gen_random_uuid()` and `now()` stay as the inference for a description that carries only `hasDefault` |
 | `unrenderedOf()` / `unrenderedComment()` / `UnrenderedDeclaration` | `As of 2026-08-25`: what the generator could **not** write, on `GeneratedMigration.unrendered` and as a `-- UNRENDERED` block at the top of a non-empty `up`. A generator that emits less than the declaration in silence is the defect the whole file exists against, and `x verify`'s `drift` step reads a source hash — it never reads the SQL, so the loss was green. **`unrenderedOf(entities, current)` takes the recorded schema**, required and nullable: a rule declared as an `assert` reaches no SQL by design and is no loss on its own, but one whose CHECK a previous migration RECORDED is dropped by this run and reported by nothing — five in `examples/dummy`, and `@ultimat3/cli`'s `repairFix` then offered `x db gen "drop <name>"` as the repair for the loss that command performs |
-| `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 |
+| `destructiveStatements()` / `hasDestructiveMarker()` / `isDestructiveMigration()` / `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`. **App tables only**, `As of 2026-08-24`: a relation an extension owns (`pg_depend`, `deptype = 'e'`) and anything that is not an ordinary or partitioned table are excluded before the fold, and an explicit `exclude` cannot bring them back |
-| `introspectCatalog()` / `CatalogDescription` / `emptyCatalog()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: the WHOLE schema in the catalog's own spelling — extensions, enum and domain types, sequences, tables, indexes, foreign keys, views, functions, triggers — sorted in code-unit order, plus `unrendered`: what exists and the dump cannot spell. Comparable only to another reading of itself; `introspect()` stays the entity-vocabulary reading a snapshot is diffed in |
+| `introspectSchema()` | live schema → `SchemaDescription`. **App tables only**, `As of 2026-08-24`: a relation an extension owns (`pg_depend`, `deptype = 'e'`) and anything that is not an ordinary or partitioned table are excluded before the fold, and an explicit `exclude` cannot bring them back |
+| `introspectCatalog()` / `CatalogDescription` / `emptyCatalog()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: the WHOLE schema in the catalog's own spelling — extensions, enum and domain types, sequences, tables, indexes, foreign keys, views, functions, triggers — sorted in code-unit order, plus `unrendered`: what exists and the dump cannot spell. Comparable only to another reading of itself; `introspectSchema()` stays the entity-vocabulary reading a snapshot is diffed in |
 | `renderSchemaDump()` / `SchemaDumpFile` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: a catalog → the schema dump's files. Pure and byte-deterministic. [The schema dump](#the-schema-dump) |
 | `loadSchemaDump()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: build a schema from those files, in one transaction, retrying a file that names something not created yet |
 | `compareSchemaDump()` / `reloadDifferences()` / `schemaDumpDrift()` / `schemaDumpDifferenceOf()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: `X_SCHEMA_DUMP_DRIFT` — committed files against rendered ones in both directions, and load-equals-replay as a comparison |
-| `unexpectedObjects()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: the triggers, functions, views, types and sequences a live catalog holds and an expected one does not, as `unexpected-object` drift. Identity, never definition text |
+| `unexpectedObjects()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: the triggers, functions, views, types and sequences a live catalog holds and an expected one does not, as `unexpected-object` drift. Identity, never definition text. Its `fix:` is one `psql -c` command that prints the object's definition, qualified by the catalog's schema — `\d+` a view, `\dT+` an enum, `\dD+` a domain, `\d` a sequence or a trigger's table, `pg_get_functiondef` by namespace for a function — with the repair as its comment |
 | `PgliteOptions.extensions` / `linkPgliteExtensions()` | `As of 2026-10`: Postgres extensions to link at boot, by name — a list, or a function for a caller whose list is read from disk. `linkPgliteExtensions(names)` answers `{ linked, missing }` without booting anything: `missing` is what the installed PGlite ships no bundle for, which is how `@ultimat3/cli` decides a replay needs a real Postgres. A missing name is skipped at boot and refused by `create extension` itself |
 | `PgliteOptions.snapshotDir` | `As of 2026-10`: a directory for the post-`initdb` snapshot, so an in-memory boot is a restore (~0.4 s against ~2.7 s). Keyed on the PGlite version alone — `initdb` never sees a linked extension, so one snapshot serves every set; checksummed, never trusted, written by temp-name-then-rename. Ignored for a data directory on disk |
 | `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 |
+| `pgliteClient()` / `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 |
 | `setStatementObserver()` / `statementObserver()` | `As of 2026-08`: one event **and one `db.<verb>` span** per settled statement, both drivers; uninstalled is one branch |
@@ -67,7 +68,7 @@ await withTransaction(async (tx) => {
 | `withStatementAttribution()` / `statementAttribution()` | `As of 2026-08`: the `{ entity, op }` pair on `StatementEvent.attribution`, scoped exactly like `expectedQueryLoop()` — `@ultimat3/entity`'s `postgresRepo` is the one producer |
 | `STATEMENT_ATTRIBUTE` | `As of 2026-08`: `db.statement`, the OTel attribute each span carries its text under — declared here, read by `x dev`'s timeline |
 | `statementFingerprint()` / `statementKind()` / `statementVerb()` | `As of 2026-08`: what shape a statement is — `entity.op` when attributed else its own collapsed text, read or write from the leading verb. One rule, so two detectors group identically |
-| `createRecordingClient()` | in-memory `DbClient` that records SQL, for tests |
+| `recordingClient()` | in-memory `DbClient` that records SQL, for tests |
 
 ## `sql` is parameters-only
 
@@ -75,13 +76,37 @@ String interpolation is how every SQL injection ships, and an agent writing SQL
 trusted to remember the difference between a value and a fragment. So:
 
 - scalars (`string`, `number`, `boolean`, `bigint`, `Date`, `Uint8Array`, arrays, `null`) become
-  `$1..$n` and never touch `.text`;
+  `$1..$n` and never touch `.text`. A value that cannot be SENT — an Invalid Date, a ragged array —
+  is `X_INVARIANT` before the driver is called, never `X_DB_UNAVAILABLE`; a `Uint8Array` inside an
+  array is one `bytea` element. Both drivers refuse alike;
 - a nested fragment is spliced and its parameters are renumbered;
 - **anything else throws `X_SQL_UNSAFE`** — including an object shaped like a `SqlFragment` that
   `sql`/`raw` did not produce;
 - `raw(trusted)` is the one audited escape hatch, `identifier(name)` the safe way to interpolate
   a table or column, `literal(text)` for utility statements that reject bound parameters.
 
+## Transactions that end badly
+
+`As of 2026-10-02`. Postgres aborts the WHOLE transaction on any statement error and answers the
+`COMMIT` that follows with the tag `ROLLBACK` and no error. `withTransaction` used to resolve on
+that, fire `onCommit`, and store nothing.
+
+| Situation | What happens |
+|---|---|
+| the body catches a failed statement and returns | `X_DB_TRANSACTION_ABORTED`, cause = the first failing statement; `ROLLBACK`, `onRollback` undos run, `onCommit` never fires |
+| the fallible statement sits in a nested `withTransaction` and THAT is caught | only the savepoint rolls back; the outer scope commits. This is the fix the error names |
+| a nested body swallows a failed statement | the nested call rejects with `X_DB_TRANSACTION_ABORTED`; its savepoint is rolled back and the outer scope is usable again |
+| `ROLLBACK TO SAVEPOINT` itself fails | the nested call still rejects with the body's error; the root is marked aborted and its `COMMIT` is refused, never sent |
+| two nested scopes under `Promise.all` | run one after the other, per parent scope — savepoints are a stack, and interleaved ones destroyed each other |
+| a nested scope waits past `siblingWaitMs` (default `SIBLING_SCOPE_WAIT_MS`, 30 s; `0` = no deadline) for its sibling | `X_DB_SIBLING_SCOPE_TIMEOUT`, naming the parent and the savepoint holding the turn. The shape it exists for: a body awaiting a sibling started after it, which waits for itself — a permanent hang before the deadline. The waiter never opened and its place is handed on |
+| any `COMMIT` answered `ROLLBACK`, on either driver | `X_DB_TRANSACTION_ABORTED` from the statement funnel (`commit-tag.ts`) — covers an abort the scope never saw and a hand-written `COMMIT` |
+| `COMMIT` rejects with a SQLSTATE (a deferred constraint, `40001`) | rolled back: the server's error surfaces, undos run |
+| `COMMIT` rejects with NO SQLSTATE | `X_DB_COMMIT_UNKNOWN`: neither `onCommit` nor `onRollback` runs, and it is never retried |
+| a nested scope passes `isolation`, `readOnly: true`, `deferrable: true`, or a `client` other than the root's | `X_INVARIANT` — a savepoint can honour none of them; `retry` was already refused |
+
+Only a failure carrying a SQLSTATE marks the scope aborted: a refusal raised before the send left
+the transaction untouched.
+
 ## Read-only access for anything an LLM drives
 
 `As of 2026-07`: a bug in one defence must not become a write, so `db.query` on the MCP dev
@@ -172,7 +197,7 @@ production traffic is routed.
 
 ## The drift contract
 
-`checkDrift()` compares `introspect()` against the snapshot the newest applied migration carries —
+`checkDrift()` compares `introspectSchema()` against the snapshot the newest applied migration carries —
 `expectedSchema(migrations, ledger)`. `declaredSchema(migrations)` is the same read with the ledger
 left out: the schema the files *declare*, applied or not, which is what `x db gen` diffs the app's
 entities against so generation needs no database at all. One implementation, two callers — a
@@ -190,7 +215,7 @@ A migration the ledger has not recorded is **not** drift: `expectedSchema` reads
 subset, so a database that simply has not migrated yet is pending, not divergent. Neither is a
 table in the `x_` namespace — `x_migrations`, the queue's tables, the outbox and every
 `@ultimat3/auth` table are created by `create table if not exists` at boot and appear in no
-snapshot, so `appTables()` drops them before the diff. `introspect()` keeps its own narrower
+snapshot, so `appTables()` drops them before the diff. `introspectSchema()` keeps its own narrower
 exclusion (the ledger alone), reserving `x_users` for a schema view that wants it.
 
 **A CHECK the catalog no longer holds is drift, `As of 2026-08-25` — by NAME.**
@@ -199,15 +224,16 @@ back as `CHECK ((status = ANY (ARRAY['draft'::text, 'published'::text])))`), so
 read as `conname` alone and lands on `TableDescription.checkNames`, a **separate field** from the
 declaration's `checks`. Only the declared side is judged, so a NOT NULL, an `enumerated()` column's
 old anonymous form and an extension's own constraint are all silent; a declared one the catalog
-does not hold is `missing-check`, whose `fix:` is the `add constraint` statement itself, because the
-migration that declares it is already in the ledger and `x db migrate` would apply nothing. There is
+does not hold is `missing-check`, whose `fix:` is the `add constraint` statement as one
+`psql "$DATABASE_URL" -c '…'` command against that database, because the migration that declares
+it is already in the ledger and `x db migrate` would apply nothing. There is
 no `changed-check`: presence is a boolean, a predicate is text, and normalising the text is an
 expression parser competing with the server's.
 
 **Nor is a relation an extension owns, `As of 2026-08-24`.** `create extension pg_stat_statements`
 in `public` is the CNPG, RDS, Supabase and Neon default, and its view read as `unexpected-table`
 with `x db gen "add pg_stat_statements"` as the fix — so every deploy failed terminally and the fix
-would have written an extension's internal view into the app's migration set. `introspect()` now
+would have written an extension's internal view into the app's migration set. `introspectSchema()` now
 excludes every relation Postgres records as extension-owned (`pg_depend`, `deptype = 'e'`), which is
 ownership rather than a name: a `pg_*` prefix rule covers that view and misses `postgis`'
 `spatial_ref_sys`. Views, materialised views and foreign tables go with them — no snapshot records
@@ -226,18 +252,41 @@ X_DB_DRIFT: schema differs from migrations
 |---|---|---|
 | live column, no migration | `table "T" has column "C" not present in any migration` | `x db gen "add C"` — the name goes through `shellInertIdentifier()`, and one it refuses is left OUT of the command rather than escaped into it (`x db gen "add the undeclared column"`, the name in the cause) |
 | 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` | a `create table if not exists` in a migration, then `x db migrate` — or `drop table` in `psql` where nothing owns it. Never `x db gen`, which diffs a table nothing declares against nothing and writes no file (issue #345). The name goes through `shellInertIdentifier()`, and one it refuses leaves the fix as prose |
+| live table, no migration | `table "T" is not present in any migration` | `psql "$DATABASE_URL" -c '\d "T"'` — one harmless command that shows the table — with the two repairs as its comment: a `create table if not exists` in a migration, then `x db migrate`, or `drop table` where nothing owns it. Never `x db gen`, which diffs a table nothing declares against nothing and writes no file (issue #345). The name goes through `shellInertIdentifier()`, and one it refuses leaves `psql "$DATABASE_URL"   # <the steps>` |
 | 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 |
+| foreign key, rule moved | `foreign key "K" on "T" (C) to "R" is on delete cascade, not what migrations declare` — `K` is the constraint the database holds | `psql "$DATABASE_URL" -c '<the drop constraint + add constraint pair>'` — one command, against the drifted database — then `x db migrate` |
+| column nullability differs (`changed-column`) | `table "T" allows NULL in column "C" that migrations declare not null` / `forbids NULL in column "C" that migrations declare nullable` | `psql "$DATABASE_URL" -c 'alter table "T" alter column "C" set not null;'` (or `drop not null`) — one command, then `x db migrate`. A table read from a schema other than `public` gets `set search_path = "<schema>";` ahead of the statement, in the same `psql -c` word, so it and every table it references resolve there. A name `shellInertIdentifier()` refuses degrades every one of these three to `psql "$DATABASE_URL"   # <the steps>`: still a command that runs, with no name in it |
+| append-only trigger gone (`missing-append-only-trigger`, `As of 2026-10-06`) — raised as `X_APPEND_ONLY_TRIGGER_MISSING`, the one kind with its own code | `table "T" is declared appendOnly, and its trigger ultimate_append_only is missing or disabled` — a disabled (`D`) or replica-only (`R`) trigger counts as missing, because an ordinary session fires neither | `psql "$DATABASE_URL" -c '<create or replace function …; drop trigger if exists "ultimate_append_only" on "T"; create trigger "ultimate_append_only" …>'` against the drifted database, then `x db migrate`. Drop-if-exists first: a disabled trigger still exists, and a bare `create trigger` would fail on it (`42710`) |
+| primary key differs (`changed-primary-key`, `As of 2026-10-02`) | `table "T" has primary key (id) as constraint "T_pkey", and migrations declare (slug)` — the constraint named is the one the DATABASE holds — compared in column ORDER; `has no primary key` when the database holds none | `psql "$DATABASE_URL" -c '<drop constraint "<the live key>"; add constraint "T_pkey" primary key (…)>'` — one command, against the drifted database — then `x db migrate`. Nullability is skipped for the DECLARED key's columns only |
 
-`checkDrift()` returns every difference; `assertNoDrift()` throws the first. `x db migrate` renders
+`checkDrift()` returns every difference; `assertNoSchemaDrift()` 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 —
+(`assertNoSchemaDrift`, 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.
 
+## Append-only tables
+
+`EntityDescriptionLike.appendOnly` (from `entity({ appendOnly: true })`) is a trigger, written by
+`x db gen` (`generate-append-only.ts`) and recorded on the snapshot as `appendOnly: true`:
+
+```sql
+create or replace function "ultimate_refuse_append_only"() returns trigger language plpgsql as $append_only$ begin raise exception 'X_ENTITY_APPEND_ONLY: % on %.% is refused, the table is append-only', tg_op, tg_table_schema, tg_table_name using errcode = '23001', hint = '…'; end; $append_only$;
+create trigger "ultimate_append_only" before update or delete on "ledger" for each row execute function "ultimate_refuse_append_only"();
+```
+
+| | |
+|---|---|
+| Names | fixed: the trigger is `ultimate_append_only` on every table (a trigger name is per table, so no 63-byte truncation), the function one shared `ultimate_refuse_append_only()` |
+| Refuses | UPDATE, DELETE, and the update arm of `insert … on conflict do update`. Not `truncate` — no row write, and `destructive.ts` already gates it |
+| The error | message leads with `X_ENTITY_APPEND_ONLY`, SQLSTATE `23001` (`restrict_violation`, class 23: an integrity rule refused it, so never retried) |
+| On / off | adding `appendOnly` emits the function (once per migration) and the trigger (drop-if-exists first on an existing table), `down` drops the trigger; removing it drops the trigger, `down` restores both. A dropped table takes its trigger with it; the function is never dropped |
+| NOT NULL with no backfill | a NEW NOT NULL column needs a default (or `.nullable()`), and an EXISTING column cannot be turned NOT NULL: `x db gen` refuses both (`X_MIGRATION_APPEND_ONLY_BACKFILL`) rather than emit the usual `-- backfill …, then: set not null` note — that backfill is an UPDATE the trigger refuses, and a default fills no NULL already stored (`generate-append-only-column.test.ts`) |
+| Engines | Postgres and PGlite alike (`generate-append-only.live.test.ts`, `generate-append-only-embedded.test.ts`) |
+| Drift | `introspectSchema()` writes `triggerNames` (enabled, non-internal) on every table — the catalog half; `appendOnly` is the snapshot half, never read from the catalog |
+
 ## The schema dump
 
 **Imported from `@ultimat3/db/schema-dump`, never from the barrel** (23.0.0): `introspectCatalog`,
@@ -271,7 +320,10 @@ object kind, numbered in the order a database is built in, one file per named ob
 - A file over 500 lines (`SCHEMA_DUMP_MAX_LINES`, the `filesize` ceiling) is split `<name>.1.sql`, `<name>.2.sql`;
   `loadSchemaDump()` joins the parts in numeric order.
 - What cannot be spelled — partitions, inheritance, foreign tables, composite and range types,
-  aggregates, row-security policies, rules — is named in `unrendered.sql` as comments.
+  aggregates, row-security policies (and `force row level security`), rules, extended statistics,
+  a column's non-default `storage`, a materialized view created `with no data`, and a trigger on
+  a relation the dump does not create — is named in `unrendered.sql` as comments.
+- A generated column is spelled `stored` or `virtual` (Postgres 18), as `attgenerated` says.
 
 `loadSchemaDump()` runs kind by kind, the framework twin first, each file in a savepoint. A file
 refused with `42P01`, `42883` or `42704` — "not created yet" — is retried after the rest; a pass
@@ -286,17 +338,17 @@ Which engine, where the files live, when they are written and what holds them is
 
 ## The embedded database
 
-No `DATABASE_URL` means no Docker: `createPgliteClient()` runs Postgres as WASM inside this
+No `DATABASE_URL` means no Docker: `pgliteClient()` runs Postgres as WASM inside this
 process. The module is resolved on the first statement, never at import, so an image that only
 ever talks to a managed Postgres never loads it.
 
 ```ts
-const dev = createPgliteClient({ dataDir: pgliteDataDir(services.db.url) });  // or memory://
+const dev = pgliteClient({ dataDir: pgliteDataDir(services.db.url) });  // or memory://
 await dev.ping();                                       // pay the ~3s boot before serving
 setDbClient(dev);
 
 const branch = await branchPglite('feature_x', { from: '.x/pgdata' });
-setDbClient(createPgliteClient({ dataDir: branch.dataDir }));
+setDbClient(pgliteClient({ dataDir: branch.dataDir }));
 ```
 
 PGlite has no `CREATE DATABASE ... TEMPLATE`, so `branchPglite()` copies the data directory —
@@ -306,7 +358,7 @@ lands in a filesystem path, so an unvalidated one is traversal rather than a typ
 
 ### One session, so callers take turns
 
-Embedded Postgres is a single session, not a pool. `createPgliteClient()` is therefore
+Embedded Postgres is a single session, not a pool. `pgliteClient()` is therefore
 `ReservableClient`: `withTransaction()` and `readOnlyQuery()` pin it, and every other statement
 waits for its turn. Without that pin two concurrent units of work each run `BEGIN` on the same
 connection — the second `COMMIT` commits the first's rows and the first `ROLLBACK` finds no
@@ -371,9 +423,9 @@ A pooled statement cannot hold a subscription: the next one runs on another conn
 clients hold ONE session beside the pool for it.
 
 ```ts
-import { createPostgresClient } from '@ultimat3/db';
+import { postgresClient } from '@ultimat3/db';
 
-const client = createPostgresClient({ url: 'postgres://localhost:5432/app_test' });
+const client = postgresClient({ url: 'postgres://localhost:5432/app_test' });
 const subscription = await client.listen(
   'x_jobs_wake',
   (payload) => console.log('notified', payload),
@@ -407,7 +459,13 @@ migration inside its own transaction. It refuses **before applying anything** wh
   the running one — another version owns the database; or
 - an applied migration's `up` SQL no longer matches its recorded checksum.
 
-Report (`--json`): `{ applied: [{ id, name, durationMs }], skipped: [id], durationMs, appVersion }`.
+**Except a rollback** (`As of 2026-10-05`, `migrate-rollback.ts`): when every unknown ledger row
+sorts after the newest migration this build ships, and this build has nothing left to apply, the
+ledger is an older image rolled back onto a newer build's schema. Nothing is applied, the rows are
+reported in `ahead` and logged as `ultimate migrate ledger ahead of build`; any other unknown row is
+still `X_MIGRATION_CONFLICT`.
+
+Report (`--json`): `{ applied: [{ id, name, durationMs }], skipped: [id], durationMs, appVersion, ahead: [id] }`.
 
 ## A loop of queries that is deliberate says so
 
@@ -495,11 +553,14 @@ job the moment Postgres fails over.
 | `X_DB_UNIQUE_VIOLATION` | `23505` — `fix:` names `upsertAll(rows, { onConflict: [...] })` and the constraint the server named |
 | `X_DB_FOREIGN_KEY_VIOLATION` | `23503` |
 | `X_DB_SERIALIZATION_FAILURE` | `40001` / `40P01`, and an exhausted `withTransaction(fn, { retry: n })` budget |
+| `X_DB_TRANSACTION_ABORTED` | a statement failed inside a transaction and its error was caught; the server rolled the unit of work back. Also any `COMMIT` answered with the tag `ROLLBACK` |
+| `X_DB_COMMIT_UNKNOWN` | `COMMIT` was sent and the connection failed before the answer: durable or rolled back, unknowable from here |
+| `X_DB_SIBLING_SCOPE_TIMEOUT` | a nested `withTransaction` waited past `siblingWaitMs` for a sibling scope that never finished |
 | `X_DB_STATEMENT_TIMEOUT` | `57014` — the statement ran past `statement_timeout` |
 | `X_DB_LOCK_TIMEOUT` | `55P03` — it waited past `lock_timeout` for a lock it never got |
 | `X_DB_POOL_EXHAUSTED` | `53300` / `53200`, or `reserve()` past `acquireTimeoutMs` |
 | `X_DB_DRIFT` | live schema differs from migrations |
-| `X_MIGRATION_CONFLICT` | ledger app-version fence or checksum mismatch |
+| `X_MIGRATION_CONFLICT` | ledger app-version fence or checksum mismatch — never for rows that are all newer than the build (a rollback) |
 | `X_MIGRATE_CONCURRENT` | another migrator still held the lock when the wait ran out |
 | `X_MIGRATION_IRREVERSIBLE` | generated `down` would lose data |
 | `X_SQL_UNSAFE` | non-bindable interpolation, or an unsafe identifier/branch name |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -26,14 +26,14 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "23.0.0"
+    "@ultimat3/core": "25.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"