@ultimat3/db 22.15.0 → 24.0.0

package/CLAUDE.md

@@ -14,7 +14,7 @@ Tier 1 — it imports `@ultimat3/core` and nothing else. That placement is load-
 | SQLSTATE | one reader, `sqlState()` (`sqlstate.ts`). Never read `error.code` for a SQLSTATE |
 | Reading a caught value | `renderThrowable()` from core (`checkDb` backs `/readyz`) |
 | Errors | subclass `DbError`; never `throw new Error` in source. A test simulating a database failure throws `dbUnavailable()`; one simulating the caller's body failing throws a bare `Error` on purpose |
-| New code | add to `DB_ERROR_CODES` **and** `DB_ERROR_TITLES` in `errors.ts`, whichever file holds the constructor (`migration-errors.ts`, `invariant-errors.ts`, `drift-errors.ts`); `src/index.ts` re-exports all |
+| New code | `bun run new-error-code <CODE> --package db --title '…' --fix '…'` writes `DB_OWNED_ERROR_CODES`, `DB_ERROR_TITLES` and the wiki row together; then add it to `errors.test.ts`'s pinned list. The constructor lives where its imports allow (`migration-errors.ts`, `invariant-errors.ts`, `drift-errors.ts`, `dump-drift.ts`); `src/index.ts` re-exports all |
 | A value ambient across an `await` | `asyncContext<T>(subject)` from core — never `new AsyncLocalStorage`. Three scopes: `transaction.ts`, `attribution.ts`, `expected-loop.ts` |
 | Exports | explicit in `src/index.ts`; no `export *` |
 | Files | < 200 LOC (the `packages/db/src/**/*.ts` path instruction), one responsibility, `kebab-case.ts`, test beside source |
@@ -35,40 +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 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
@@ -76,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.
@@ -88,12 +95,11 @@ 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`).
+  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 because
   `packages/cli/src/dev-queue.ts` wraps a real client for its `PgExecutor`, unattributed.
 
@@ -123,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`)
@@ -168,11 +174,10 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   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;
+  `generate-generated-{column,rebuild}.live.test.ts`.
+- **`REPLICA IDENTITY FULL` is emitted by a PARAMETER** (`GenerateOptions.replicaIdentityFull`, from
+  `@ultimat3/cli`'s `db-generate.ts`), in `replica-identity.ts`: recorded `true` or absent; the
+  snapshot records the union; dead last in `up`; never destructive; an undeclared name is skipped;
   `down` is `replica identity default` except on a table this migration creates.
 - **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
@@ -184,20 +189,19 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 - **`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.
+  that into `unknown-schema`, and `x db gen` refuses with `X_MIGRATION_SNAPSHOT_MISSING`. Both lead
+  with the same two remedies in order: restore the sidecar (`git checkout --`), or delete the
+  migration's files FIRST and then run `x db gen`. Both commands are screened (`shellInertIdentifier`
+  / `renderFixShellArg`), degrading the whole line to prose.
 
 ## 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.
@@ -205,26 +209,57 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 - `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).
+  `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`).
 - `introspect()` 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
   `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.
 
+## The schema dump
+
+- **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
+  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 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,
+  arguments). The live side is the operator's Postgres, the expected side a PGlite replay.
+- **No app path here.** Where the dump lives, which engine replays, and when it is written are
+  `@ultimat3/cli`'s (`db-schema-dump.ts`). `schema-load.contract.test.ts` reads the reference app's
+  migrations as text and runs on Postgres when `TEST_DATABASE_URL` is set.
+- **`pglite-extensions.ts` is the one linker** (`linkPgliteExtensions` → `{ linked, missing }`):
+  `contrib/<name>` then the package root; the name is data (read from migration text), screened
+  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
+  (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

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 |
@@ -51,6 +52,13 @@ await withTransaction(async (tx) => {
 | `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`. **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 |
+| `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. 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 |
 | `ensureReadOnlyRole()` / `grantReadOnlySql()` / `READONLY_ROLE` | a `NOLOGIN`, SELECT-only Postgres role — layer 1 of `db.query`'s defence |
@@ -68,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
@@ -192,8 +224,9 @@ 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.
 
@@ -219,10 +252,12 @@ 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 |
+| 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
 them all as findings and exits non-zero; a `ROLE=migrate` container throws the first one
@@ -231,6 +266,55 @@ the exit code — and a deploy that rolled on past a schema nobody can reconstru
 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 schema dump
+
+**Imported from `@ultimat3/db/schema-dump`, never from the barrel** (23.0.0): `introspectCatalog`,
+`emptyCatalog`, the `Catalog*` types, `renderSchemaDump`, `loadSchemaDump`, `compareSchemaDump`,
+`reloadDifferences`, `schemaDumpDrift`, `schemaDumpDifferenceOf` and `unexpectedObjects`. Three
+callers run them — `x db gen`, `x db migrate`, the gate's `drift` step — and `@ultimat3/db` is in
+every role's boot graph, where these ten modules served nothing. `schema-dump-entry.test.ts` holds
+both halves: the barrel evaluates none of them, and no name has two homes.
+
+`renderSchemaDump(await introspectCatalog({ client }))` is the schema as files: one directory per
+object kind, numbered in the order a database is built in, one file per named object.
+
+| Directory | Holds |
+|---|---|
+| `01_extensions/` | `create extension if not exists` — never `plpgsql` |
+| `02_types/` | enums, domains |
+| `03_sequences/` | sequences no column owns |
+| `04_tables/` | the table; a `serial` column's sequence before it and its ownership after; `replica identity full` |
+| `05_indexes/` | per table, indexes no constraint backs; `replica identity using index` |
+| `06_foreign_keys/` | per table, `alter table … add constraint` |
+| `07_views/` | views; a materialized view with its indexes |
+| `08_functions/` | per name, overloads together |
+| `09_triggers/` | per table |
+
+- An object whose owner — its table, else itself — starts with `x_` goes to a `framework/` twin of
+  the same layout. The rule is `FRAMEWORK_TABLE_PREFIX`, the one `appTables()` already holds.
+- Postgres' own spellings (`format_type`, `pg_get_expr`, `pg_get_*def`), so a loaded dump renders
+  the same bytes. Sorted in JS, never by `order by`: a name's order follows the server's collation.
+- No timestamp, version, owner or grant. Every sequence option is written, defaults included.
+- A name becomes a file name with everything outside `[A-Za-z0-9_-]` percent-encoded.
+- 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 (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
+that loads nothing ends with `X_SCHEMA_DUMP_DRIFT` naming the file.
+
+**Not the snapshot.** `<id>.snapshot.json` is `x db gen`'s diff base, in the entity's vocabulary:
+both sides of that diff are generator spellings. The dump is what the database holds, in SQL:
+both sides of ITS comparison are catalog spellings. Neither can be compared with the other.
+
+Which engine, where the files live, when they are written and what holds them is `@ultimat3/cli`'s
+(`x db gen`, `x db migrate`, the `drift` step). This package renders, loads and compares.
+
 ## The embedded database
 
 No `DATABASE_URL` means no Docker: `createPgliteClient()` runs Postgres as WASM inside this
@@ -312,6 +396,33 @@ so nothing else would ever end that wait. `migrate()` emits it as `SET LOCAL loc
 each migration's own transaction — it reverts at COMMIT, so a DDL value never leaks onto the session
 the ledger insert runs on.
 
+## `LISTEN` on a session of its own
+
+A pooled statement cannot hold a subscription: the next one runs on another connection. Both
+clients hold ONE session beside the pool for it.
+
+```ts
+import { createPostgresClient } from '@ultimat3/db';
+
+const client = createPostgresClient({ url: 'postgres://localhost:5432/app_test' });
+const subscription = await client.listen(
+  'x_jobs_wake',
+  (payload) => console.log('notified', payload),
+  () => console.log('listening'), // again after every re-dial
+);
+await subscription.unlisten();
+```
+
+| Fact | Detail |
+|---|---|
+| the session | `Bun.SQL.listen` on the pooled client — outside `max`, untouched by `idleTimeout`, ended by `unlisten()` or `close()`; PGlite's own `listen` on the embedded one. Every channel a client listens on shares it |
+| `onListening` | fires each time the subscription is (re-)established. The driver re-dials a session that died, and what was notified in between is LOST — re-read the source of truth there |
+| the channel | a lower-case identifier of at most 63 characters, refused otherwise before a driver sees it |
+| a transaction-pooling proxy | `listen()` resolves and nothing is ever delivered. Only a notification that arrives proves the path |
+| `canListen(client)` | `true` for both shipped clients. `false` for a replicated pair — listen on the primary it was built from, as the boot does |
+
+`@ultimat3/jobs`' `startQueueWake` is the framework's one caller.
+
 ## Migrations
 
 `migrate()` takes the advisory lock by **polling** `pg_try_advisory_lock(4919202607)` every 500ms
@@ -415,6 +526,9 @@ 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` |
@@ -424,6 +538,7 @@ job the moment Postgres fails over.
 | `X_MIGRATION_IRREVERSIBLE` | generated `down` would lose data |
 | `X_SQL_UNSAFE` | non-bindable interpolation, or an unsafe identifier/branch name |
 | `X_BRANCH_EXISTS` | branch database already exists (or is the connected one) |
+| `X_SCHEMA_DUMP_DRIFT` | the committed schema dump is not what the migrations produce, or does not load back |
 | `X_NOT_IMPLEMENTED` | branching an in-memory PGlite — a copy needs a directory |
 | `X_ENV_MISSING` | core's — `DATABASE_POOL_MAX` is set to something that is not a positive integer |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "22.15.0",
+  "version": "24.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -14,11 +14,13 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./schema-dump": "./src/schema-dump-entry.ts"
   },
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -31,7 +33,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.15.0"
+    "@ultimat3/core": "24.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/array-parameter.ts

@@ -28,18 +28,45 @@ import { assert } from '@ultimat3/core';
  * backslash, or leading/trailing whitespace the parser would strip — plus the empty string, which
  * unquoted is not an element at all.
  */
+const hexOf = (bytes: Uint8Array): string =>
+  Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+
+/**
+ * A `Date` as the instant Postgres reads, or `X_INVARIANT` for one that holds no instant.
+ * `toISOString()` on an Invalid Date is a bare `RangeError`, and inside the funnel that became
+ * "cannot reach the database". `position` names the parameter when the caller knows it.
+ */
+export function instantText(value: Date, position?: number): string {
+  assert(
+    !Number.isNaN(value.getTime()),
+    `${position === undefined ? 'an array element' : `parameter $${position}`} is an Invalid Date, which names no instant Postgres could store`,
+    'new Date(input) answers Invalid Date for text it cannot parse — parse it with t.date first, or bind null: Number.isNaN(value.getTime()) ? null : value',
+  );
+  return value.toISOString();
+}
+
 function element(value: unknown): string {
   if (value === null || value === undefined) return 'NULL';
   // A Date is ALWAYS quoted, even though an ISO-8601 instant carries no character the grammar
   // reads as structure. A timestamp element is conventionally quoted, and the alternative is a
   // rule that holds only while nothing ever renders a timestamp with a space in it.
-  if (value instanceof Date) return `"${value.toISOString()}"`;
+  if (value instanceof Date) return `"${instantText(value)}"`;
+  // BYTEA's hex form, never `String(bytes)` — that is `1,2,3`, three elements where one was bound,
+  // and no error anywhere. The backslash is doubled because a quoted element reads `\\` as one.
+  if (value instanceof Uint8Array) return `"\\\\x${hexOf(value)}"`;
   const text = String(value);
   const structural = /[{},"\\\s]/.test(text) || text.length === 0 || text.toUpperCase() === 'NULL';
   if (!structural) return text;
   return `"${text.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
 }
 
+/** The extents along a value's FIRST path, `2x3` for two rows of three — `''` for a scalar. */
+function extentsOf(value: unknown): string {
+  if (!Array.isArray(value)) return '';
+  const inner = extentsOf(value[0]);
+  return inner === '' ? String(value.length) : `${value.length}x${inner}`;
+}
+
 /**
  * The array literal for one parameter: `{a,b,c}`, elements escaped.
  *
@@ -71,5 +98,15 @@ export function pgArrayLiteral(values: readonly unknown[]): string {
     `a nested array parameter is ragged — its rows are ${nested.map((row) => row.length).join(', ')} long, and Postgres has no jagged array`,
     'give every row the same length, or bind one array per row',
   );
+  // Every extent, not only this level's: `[[['a']], [['b', 'c']]]` is two rows of one element each,
+  // each rectangular on its own, and `{{{a}},{{b,c}}}` is the same 22P02 — measured on 17. Each
+  // row is checked against itself by the recursion below, so comparing one path's extents per row
+  // is comparing all of them.
+  const depth = extentsOf(nested[0]);
+  assert(
+    nested.every((row) => extentsOf(row) === depth),
+    `a nested array parameter is ragged below its first level — its rows have the extents ${nested.map((row) => extentsOf(row)).join(' | ')}, and Postgres has no jagged array`,
+    'give every branch the same length at every depth, or bind one array per row',
+  );
   return `{${values.map((value) => (Array.isArray(value) ? pgArrayLiteral(value) : element(value))).join(',')}}`;
 }

package/src/bound-parameters.ts

@@ -4,7 +4,7 @@
 // described type to go by the driver sent `Date.prototype.toString()`, a local-zone string
 // Postgres refuses (`22007`), so every entity write carrying a timestamp failed.
 
-import { pgArrayLiteral } from './array-parameter';
+import { instantText, pgArrayLiteral } from './array-parameter';
 
 const needsEncoding = (value: unknown): boolean => Array.isArray(value) || value instanceof Date;
 
@@ -12,12 +12,31 @@ const needsEncoding = (value: unknown): boolean => Array.isArray(value) || value
  * A NEW ARRAY ONLY WHEN SOMETHING CHANGED — every statement in the process passes through here, so
  * the common path is one `some` and the caller's own array, byte for byte (axiom 6). A
  * `Uint8Array` is BYTEA, never an array: `Array.isArray` answers `false` for a typed array.
+ *
+ * It REFUSES what cannot be sent — a ragged array, an Invalid Date — with `X_INVARIANT`, so the
+ * funnel calls it BEFORE the driver's `try`: inside it, a refusal was re-wrapped as a driver
+ * failure and read "cannot reach the database".
  */
+/**
+ * The refusals alone, for a driver that does its own encoding. PGlite renders an array and a
+ * `Date` correctly, so `pglite.ts` sends the caller's values untouched — but what cannot be sent
+ * must be refused alike on both funnels: an Invalid Date (its serializer answers a bare
+ * `RangeError`) and a ragged or mixed-depth array, which the pooled path refuses in
+ * `pgArrayLiteral`. That function IS the shape rule, so it is asked and its literal discarded
+ * rather than restated here; only a statement that binds an array pays for it.
+ */
+export function refuseUnsendable(values: readonly unknown[]): void {
+  for (const [index, value] of values.entries()) {
+    if (value instanceof Date) instantText(value, index + 1);
+    else if (Array.isArray(value)) pgArrayLiteral(value);
+  }
+}
+
 export function encodeBoundParameters(values: readonly unknown[]): readonly unknown[] {
   if (!values.some(needsEncoding)) return values;
-  return values.map((value) => {
+  return values.map((value, index) => {
     if (Array.isArray(value)) return pgArrayLiteral(value);
-    if (value instanceof Date) return value.toISOString();
+    if (value instanceof Date) return instantText(value, index + 1);
     return value;
   });
 }

package/src/bun-sql.ts

@@ -58,6 +58,18 @@ export interface BunSqlDriver {
   unsafe(text: string, values?: readonly unknown[]): Promise<unknown>;
   reserve(): Promise<BunSqlReserved>;
   close(options?: { readonly timeout?: number }): Promise<void>;
+  /**
+   * `LISTEN` on a connection the driver opens for it, OUTSIDE the pool. Measured on Bun 1.4.0
+   * against Postgres 17: a `max: 1` pool still answers statements while it is held;
+   * `idleTimeout` does not close it; a backend killed under it is re-dialled by the driver, with
+   * its own growing gap between attempts, and `onlisten` fires again once it is back; `close()`
+   * and `unlisten()` both end the session. Optional because a fake driver has none.
+   */
+  listen?(
+    channel: string,
+    onnotify: (payload: string) => void,
+    onlisten?: () => void,
+  ): Promise<{ unlisten(): Promise<void> }>;
 }
 
 export type BunSqlFactory = new (