@ultimat3/db 17.0.0 → 19.0.0

package/CLAUDE.md

@@ -233,6 +233,30 @@ means the nested scope never opened, and a release that failed means its work is
 the outer one. Swallowing either would keep running against a transaction that is not the one the
 caller thinks it is in.
 
+**`close()` is BOUNDED, `As of 2026-08-27`, and by the driver's OWN option rather than a race here**
+(#394). `BunSqlDriver.close` has declared `{ timeout }` since this package's `Bun.SQL` slice was
+written and **nothing ever passed it** — a capability sitting unused in the seam, the same shape as
+`setOfflineMode` on the CDP port. Measured against a real server, three runs per case: `end()` waits
+on an outstanding RESERVED connection and never returns, on Bun 1.3.14 **and** on 1.4.0, with the
+database perfectly healthy; once that connection's backend has been terminated it becomes a race
+1.3.14 loses 3 of 3 and 1.4.0 loses 1 of 3. So the runtime was never the variable — an unbounded
+await was, and `@ultimat3/cli`'s `releaseQueue` awaits this method. A container that will not drain
+is drained by SIGKILL, and the operator's only signal is a pod that took its full grace period.
+
+Three rules ride with it. **The unit is SECONDS** — `close({ timeout: profile.drainTimeoutMs /
+1000 })`, and `timeout: 5000` would be an eighty-three minute budget, which is the same hang with
+extra steps. **`drainTimeoutMs: 0` sends no option at all**, rather than `{ timeout: 0 }`: `migrate`
+and `replicator` mean "wait", for `acquireTimeoutMs`' reason, and a zero handed to the driver is an
+instruction whose reading is the driver's. **The verdict is the elapsed time**, because the driver
+RESOLVES when it gives up rather than rejecting — a drain that abandoned in-flight work looks exactly
+like a clean one, so `X_DB_DRAIN_TIMEOUT` is raised on the clock or nothing is said at all. That
+clock is `performance.now()` and never `Date.now()`, and the reason is this repo rather than NTP:
+the framework preload freezes `Date` for every test in the tree (`installDeterminism`), so a duration
+subtracted from `Date.now()` is 0 in all of them and the branch could not fire — a test asserting it
+would have been one that cannot fail. `pool-drain.test.ts` pins what is ASKED for, against a fake
+pool; `pool-drain.live.test.ts` pins that a real server's driver honours it, because a fake's
+`close()` is whatever the fake decided and the finding is about the real one.
+
 `close()` reads its cached driver into a local, clears the field, **then** awaits the teardown —
 `client.ts` and `pglite.ts` both. A teardown that rejects has still torn the pool down, so clearing
 after the await left the corpse cached for the next `connect()`, and a second `close()` threw in
@@ -240,7 +264,7 @@ the same place rather than clearing it. The rejection still reaches the caller o
 (`pglite.ts` swallows a failed *boot*, which is a different thing: there is nothing to close).
 
 `execute()` trusts the command tag only when it is `> 0`, in **both** drivers — `rowsOf`
-(`pglite.ts`) and `affectedBy` (`client.ts`) are one rule written twice, not two rules. PGlite
+(`pglite.ts`) and `affectedBy` (`statement-funnel.ts`) are one rule written twice, not two rules. PGlite
 counts MODIFIED rows, so a SELECT that returned rows is tagged `0` and `??` would report 0 for
 every read; a driver that tags a read `0` on the pooled side would have diverged from PGlite the
 same way, and the same guard closes both. A write that modified nothing returned no rows either, so
@@ -257,7 +281,7 @@ the seam swallows nothing** — a throw from `onStatement` is how strict test mo
 N+1 happened in, so a guarding facade here would silently delete that mode. `onStatement` is
 synchronous, runs on the caller's stack after the statement settled, and must not issue SQL: a
 statement from inside it re-enters the funnel and observes itself. Only two places may invoke it —
-`runOn` (`client.ts`) and `statement()` (`pglite.ts`), the funnels every statement already passes
+`runOn` (`statement-funnel.ts`) and `statement()` (`pglite.ts`), the funnels every statement already passes
 through. Reserving a connection, booting PGlite and closing a pool are not statements and stay out.
 
 Both funnels are now split in two, and the split is the whole design: `sendOn`/`send` is the raw
@@ -271,7 +295,7 @@ timeouts are still fifty statements; **notify outside the statement's own `try`*
 that succeeded as `X_DB_UNAVAILABLE` and delete strict test mode's failure. On the failing path
 the observer's throw replaces the DB error instead, which is the price of never swallowing — an
 observer that only reports must not throw. `rows` comes from the same helper `execute()` uses
-(`affectedBy` in `client.ts`, `rowsOf` in `pglite.ts`, hoisted to module scope for it), so the
+(`affectedBy` in `statement-funnel.ts`, `rowsOf` in `pglite.ts`, hoisted to module scope for it), so the
 report and the return value cannot disagree about one statement.
 
 `attribution.ts` is `StatementEvent.attribution`'s producer: `withStatementAttribution(entity, op,
@@ -289,8 +313,8 @@ is the same fact written five times, with every path an author forgot it emittin
 **Nesting keeps the innermost pair**, exactly as `expectedQueryLoop` keeps the innermost reason: a
 relation preloaded during `findMany` reads through the *related* repository, so its statement is
 attributed to that entity and its own operation, not to the read that triggered the preload.
-**The funnels stamp, on both settle paths** — `runOn` (`client.ts`) and `statement()` (`pglite.ts`)
-read `statementAttribution()` inside the branch that already found an observer, next to
+**The funnels stamp, on both settle paths** — `runOn` (`statement-funnel.ts`) and
+`statement()` (`pglite.ts`) read `statementAttribution()` inside the branch that already found an observer, next to
 `expectedQueryLoopReason()`, and put it on the event whether the statement succeeded or failed, the
 same argument as `expected`: a diagnostic that judges a whole request runs long after every scope
 in it closed. `@ultimat3/entity`'s `postgresRepo` is the one producer — the last caller that still
@@ -1007,13 +1031,36 @@ generate repairs nothing. The empty-diff exclusion is `@ultimat3/cli`'s
 makes every `x db gen` write a file holding no statement — a ledger row, a checksum and a place in
 the apply order for nothing.
 
-**`REPLICA IDENTITY FULL` is still emitted by nothing, and it does not belong here.** Which tables
-need it is derived from the `live: true` queries in the manifest, not from any entity — this package
-is tier 1 and can see neither. An `EntityDescriptionLike.replicaIdentity` field would be a
-declared-and-never-wired key, which is the defect class this release exists to eliminate. The shape
-that works is a `GenerateOptions.replicaIdentityFull: readonly string[]` passed by
-`@ultimat3/cli`'s `db-generate.ts` from the live-query set, and it lands with that caller or not at
-all.
+**`REPLICA IDENTITY FULL` is emitted, `As of 2026-08-26` — by a PARAMETER, never by an entity
+field.** `@ultimat3/realtime` refuses a live query on a table without it and nothing in the
+framework wrote it, so a scaffolded app generated a schema its own preflight rejected (issue #357).
+Which tables need it is **declared** by each `live: true` query's `subscribes:` and read out of the
+manifest — **not derived**, and this file said "derived" until 2026-08-26. It cannot be derived: the
+relation name is a string inside the query's `sql:` callback, which no generator can invoke without
+valid input, so a live-query-to-table set does not exist anywhere to be read. `liveFeed` in the
+reference app requires `{ orgId: t.uuid, limit }` and its table is the `'posts'` literal inside
+`from<PostSummary>('posts', …)`; `packages/query/src/sql.ts` says the same thing about itself —
+"`null` when no sample input was supplied". `X_QUERY_SUBSCRIBES_DRIFT` is what keeps the declaration
+honest, checked against the resolved shape at first subscribe. It is still a PARAMETER and never an
+`EntityDescriptionLike` field — this package is tier 1 and can see neither the manifest nor
+`@ultimat3/query` — so such a field would have been a declared-and-never-wired key, the defect class
+this release exists to eliminate. `GenerateOptions.replicaIdentityFull: readonly string[] |
+undefined` is the shape, passed by `@ultimat3/cli`'s `db-generate.ts` from `describeQueries()` —
+the descriptor, one hop BEFORE the manifest. `x.manifest.json` projects the same declaration
+(`QueryFact.subscribes`) and is what any other reader should use, but `appManifest(root)` re-loads
+the app and calls `appIdentity(root)`, which throws `X_APP_PACKAGE_INVALID` where there is no
+`package.json` — and `x db gen` has never needed one. `replica-identity.ts` owns every rule that
+rides with it.
+
+| Rule | Why |
+|---|---|
+| recorded on the snapshot as `TableDescription.replicaIdentityFull` | `true` or **absent**, never `false` — the literal type is the enforcement. Absent is "nothing recorded", the reading `checks` and `using` already have, so a sidecar written before the field emits the ALTER once more and Postgres accepts it on a table that has it. Without the record the statement lands in **every** migration forever, which is a generator an author learns to ignore |
+| the snapshot records the **union** with what was already recorded | a caller passing no set must not erase the fact. `snapshotOf(entities)` alone answers `NONE`, so the one place the union is computed is `generateMigration` |
+| dead **last** in `up` | the table has to exist and a `create table` in this same migration is why it might not. It is ordered against nothing else — replica identity constrains no column, index or constraint — so the end is the only placement that cannot read as depending on a statement above it |
+| never `-- destructive: true` | it drops no row, rewrites no column and matches none of `destructive.ts`'s four rules. `generate-replica-identity.test.ts` asserts both the verdict and `destructiveStatements()` |
+| a name **no entity declares** is skipped, silently | the list comes from the manifest, and a live query whose entity was deleted is an app fault this generator cannot repair. Emitting it anyway is `42P01` at `ROLE=migrate`, which is the one place this package refuses to put a fault |
+| nothing is ever **reverted** | the option is optional, so "absent" and "no live query subscribes any more" are the same value. Reading them alike would let a caller that never passes it turn off replication for every subscribed table in the app |
+| `down` is `replica identity default`, except on a table this migration **creates** | that table's whole `down` is already `drop table`; a second statement ahead of it is a line an author reads and nothing performs |
 
 **A column the DATABASE computes is a different thing at every step, and `generated-column.ts` is
 all of them** — `As of 2026-08-24`. `ColumnDescriptionLike.generated` carries the
@@ -1289,21 +1336,50 @@ survives the round trip whole.
   is 0 and not 1.
 
 - **`client.ts` reached the 500-line ceiling on 2026-08-26, and shed the five jobs that were not
-  "open a connection and send a statement".** `pool-profile.ts` owns the five numbers a pool runs
+  "open a connection and send a statement".** `pool-profile.ts` owns the six numbers a pool runs
   on — the per-role table, `DATABASE_POOL_MAX` and the screen every merged profile passes;
   `connection-url.ts` builds the connection string (the libpq `options` merge and the
   `application_name` label); `bun-sql.ts` declares the slice of `Bun.SQL` this package uses and
   looks the global up lazily;
   `pool-reserve.ts` is `reserve()` under the acquire deadline; `db-health.ts` is `checkDb`, the
-  `/readyz` report. `client.ts` keeps connecting, the statement funnel and the ambient `db()` —
+  `/readyz` report. `client.ts` keeps connecting, the client object and the ambient `db()` —
   and it still opens no socket at import, because `bunSqlFactory()` is reached from inside
-  `connect()`. **The public surface did not move**: `src/index.ts` exports every one of those
+  `connect()`. The **statement funnel** left with it on the same day, once the 500-line ceiling
+  turned out not to be the bound this package is held to: `packages/db/src/**/*.ts` carries a
+  path instruction of 200, and 263 lines is over it. `statement-funnel.ts` is `sendOn`/`runOn`
+  plus the two shape helpers (`rowsOf`, `affectedBy`) — the seam this file already documents, and
+  the one piece of `createPostgresClient` that closed over none of its state, so the move is a
+  cut and a paste with no signature invented for it. Nothing outside this package imported any of
+  the four, so no test's imports moved and no assertion changed. **The public surface did not move**: `src/index.ts` exports every one of those
   names from its new module, so `@ultimat3/db` is byte-identical to what it was. The same day,
   `drift.test.ts` split three ways along the three questions it was asking — `drift.test.ts`
   (tables and columns), `drift-index.test.ts` and `drift-ledger.test.ts` (what the migrations
   declare, and the post-migrate check) — over one shared `drift-fixtures.ts`, which
   `drift-foreign-key.test.ts` now imports instead of carrying its own byte-identical copy.
 
+- **`DATABASE_URL`'s SCHEME is screened at boot, `As of 2026-08-26`** (issue #367). `new URL()`
+  accepts a scheme-less connection string — `db.internal:5432/app` parses with `db.internal:` as
+  the SCHEME and `5432/app` as the path — so `connectionUrl` saw a well-formed url and handed it
+  on. Measured on bun 1.4.0, `Bun.SQL` then reads it as host `db.internal`, port 5432, database
+  `app` and opens a Postgres pool on it, so the first symptom is a connect failure at the first
+  QUERY, in another process phase, worded by the driver and naming neither the variable nor the
+  missing `postgres://`. `POSTGRES_SCHEMES` is closed at **`postgres:` and `postgresql:`** —
+  measured, not assumed: those two answer `adapter: 'postgres'`, while `pg:`, `tcp:` and
+  `postgresql+ssl:` are refused by the driver itself (`Unsupported protocol: … Supported adapters:
+  "postgres", "sqlite", "mysql", "mariadb"`), so excluding them costs a capability nobody has. The
+  direction that matters is the one the driver ACCEPTS: `mysql:`, `mariadb:`, `sqlite:` and
+  `file:` open a **different engine** and every statement generated here is Postgres. A
+  **behaviour change**, not a defect repair — it narrows what the framework accepts, which is why
+  it was deferred out of #364.
+  **The received scheme is deliberately never echoed**, and this is the one refusal in the package
+  that withholds the actionable token. `URL` reads the first token as the scheme, and for the value
+  this exists for that token is the HOST (`db.internal:`); one dashboard field over
+  (`app:hunter2@db.internal/app`) it is the USERNAME. Naming "the scheme" therefore puts a host or
+  a credential in the boot log and the `--json` payload, where the logger has no key left to redact
+  it by. The REQUIRED scheme is a constant and carries the whole instruction, and `describeValue`
+  still keeps the shape, so an empty variable is told apart from a truncated one.
+  `connection-url.test.ts` asserts the absence, so echoing it back is a failing test.
+
 - **`unexpectedTable`'s `fix:` no longer names `x db gen`, `As of 2026-08-26`** (issue #345). That
   command diffs the ENTITY REGISTRY against the newest snapshot, and a table nothing declares is on
   neither side of it — so the diff came back empty, the generator's empty-diff branch writes NO
@@ -1341,6 +1417,46 @@ survives the round trip whole.
   both declarations true; `packages/entity/src/errors.test.ts` asserts the two texts are equal,
   so a one-sided edit is a failing test rather than a comment nobody read.
 
+- **A JS array bound as a parameter is rendered here, because `Bun.SQL` does not render it,
+  `As of 2026-08-26`** (issue #384). `Bun.SQL`'s positional form serialises an array by JOINING ITS
+  ELEMENTS WITH COMMAS, so `unsafe('select $1::text[]', [['x', 'y']])` sends the string `x,y` and
+  Postgres answers `22P02 malformed array literal: "x,y"` — measured on bun 1.4.0 against Postgres
+  17. **Three shipped statements bind an array and all three failed**: `@ultimat3/jobs`' `SQL_CLAIM`
+  (the whole loop of every `ROLE=worker` container the framework produces, so a real deployment
+  claimed nothing and every job sat in its queue), `SQL_OUTBOX_RELEASE` (the relay giving an
+  unpublished batch back) and `@ultimat3/notify`'s `SQL_NOTIFY_INBOX_MARK_READ`.
+  `array-parameter.ts` is the encoder and `sendOn` (`statement-funnel.ts`) is the one caller — this
+  driver's only `unsafe` call, so one encoder is every caller fixed and a helper each site imports
+  is three chances to forget and a fourth site tomorrow that does (axiom 1).
+
+  **Why nothing caught it, and why the repair test is in `@ultimat3/cli`.** `pglite.ts` is a
+  separate driver that encodes an array correctly, and `x dev` runs the embedded default — so the
+  framework's own dev loop is blind by construction and only a container with `DATABASE_URL` ever
+  meets the failure. Every other test of those three statements runs against a recording executor
+  and asserts their SQL as TEXT, which cannot see whether a parameter PARSES;
+  `grep -rln '\.claim(' --include=*.live.test.ts packages/` answered ONE file before this landed.
+  `packages/db/src/array-parameter.live.test.ts` pins the grammar against a real server — and
+  asserts the RAW array is still refused, so deleting the encoder fails rather than passing on any
+  driver that happens to encode. `packages/cli/src/pg-array.live.test.ts` is the composition test:
+  it is in `cli` because nothing else can see all three — this package is tier 1 and may not import
+  `jobs` (3) or `notify` (4), and neither of those can build a db-backed `PgExecutor` — so
+  `pgExecutorFor(createPostgresClient(...))`, the executor every booted role actually gets, is the
+  only place the three real statements meet the real driver.
+
+  Three grammar rules earn their line. **`NULL` bare is the array null and `"NULL"` is the
+  four-character string**, so a JS `null` renders bare and a queue really spelled `NULL` must not
+  become one. **Quoting is by content, not by type** — a comma, a brace, a quote, a backslash,
+  surrounding whitespace or the empty string, which unquoted is not an element at all. **A
+  `Uint8Array` is BYTEA and is deliberately not an array**: `Array.isArray` answers `false` for a
+  typed array, which is behaviour this relies on rather than a case it writes. **A RAGGED nest is
+  REFUSED**, never rendered — Postgres has no jagged array and `{{a,b},{c}}` is the same `22P02`,
+  measured on 17 beside the rectangular `{{a,b},{c,d}}` that parses, so a literal this module is
+  willing to emit is one the server is willing to read. `X_INVARIANT` through core's `assert`, the
+  code this package already borrows for a value this build cannot honour; mixed depth (`{a,{b,c}}`)
+  is caught by the same guard, which a rule comparing row LENGTHS alone would let through. And the
+  common path allocates nothing — one `some` over a short list, then the caller's own array by identity, because
+  every statement the framework runs passes through here and almost none binds an array (axiom 6).
+
 ```bash
 bun test                      # from packages/db
 bun run typecheck

package/README.md

@@ -43,7 +43,7 @@ await withTransaction(async (tx) => {
 | `snapshotJson()` | `As of 2026-08`: the sidecar's **bytes** — the JSON Biome would have printed, trailing newline included. The one writer of a `<id>.snapshot.json`, because `JSON.stringify(…, null, 2)` is not formatter-clean and an app's `lint` step rejected the file `x db gen` had just written |
 | `isLedgerMissing()` | `As of 2026-08`: whether an error is Postgres' `undefined_table` for `x_migrations` — the one condition a caller may read as "nothing applied" |
 | `appTables()` / `FRAMEWORK_TABLE_PREFIX` | `As of 2026-08`: the live schema minus the `x_` namespace — no migration declares the ledger, the queue, the outbox or an auth table, so none of them is drift |
-| `generateMigration()` | `x db gen "<name>"` — reversible up/down SQL, and `destructive` for the marker the file must carry. `As of 2026-08` a foreign key is its own `alter table … add constraint`, emitted after every table statement: inline, a `references()` had to point at a table entity registration order happened to create first, and `down` had to drop them in an order it did not control. `As of 2026-08-19` a **removed** `references()` emits its `drop constraint` (it emitted nothing, and the snapshot then denied a constraint the database still held), a changed `onDelete` is a drop-and-add rebuild, and a declared `on delete` rule reaches the clause at all. `As of 2026-08-25` a **retype** drops the partial indexes and CHECK constraints written against that column first and restores them in `down`: Postgres compiles both predicates against the old type and cannot recompile either, so `alter column … type text using …::text` was `42883 operator does not exist: text = post_status` and the migration aborted mid-run. A plain btree over the column is left alone — measured, Postgres rebuilds that one itself |
+| `generateMigration()` | `x db gen "<name>"` — reversible up/down SQL, and `destructive` for the marker the file must carry. `As of 2026-08` a foreign key is its own `alter table … add constraint`, emitted after every table statement: inline, a `references()` had to point at a table entity registration order happened to create first, and `down` had to drop them in an order it did not control. `As of 2026-08-19` a **removed** `references()` emits its `drop constraint` (it emitted nothing, and the snapshot then denied a constraint the database still held), a changed `onDelete` is a drop-and-add rebuild, and a declared `on delete` rule reaches the clause at all. `As of 2026-08-25` a **retype** drops the partial indexes and CHECK constraints written against that column first and restores them in `down`: Postgres compiles both predicates against the old type and cannot recompile either, so `alter column … type text using …::text` was `42883 operator does not exist: text = post_status` and the migration aborted mid-run. A plain btree over the column is left alone — measured, Postgres rebuilds that one itself. `As of 2026-08-26` `replicaIdentityFull` names the tables a live query subscribes to and emits one `alter table … replica identity full` each, last in `up`, recorded on the snapshot so the next generation emits none — a parameter and never an entity field, because the live-query set is a tier-3 fact (`replica-identity.ts`) |
 | `declaredIndexes()` / `invariantChecks()` / `constraintNameFor()` | `As of 2026-08-25`: the DDL an entity **invariant** becomes — a `check` as a named `CONSTRAINT`, a `unique` as a partial-capable unique INDEX, an `assert` as nothing. `EntityDescriptionLike` had no `invariants` field for three majors, so a regenerated migration silently held **none** of them, including the composite UNIQUE `upsertAll`'s `on conflict` is inferred against |
 | `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` |

package/package.json

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

package/src/array-parameter.ts

@@ -0,0 +1,91 @@
+// Single responsibility: a JS array bound as a statement parameter, rendered as the Postgres array
+// literal `Bun.SQL` does not render.
+//
+// WHAT IS BROKEN WITHOUT IT. `Bun.SQL`'s positional form serialises an array by JOINING ITS
+// ELEMENTS WITH COMMAS, so `unsafe('select $1::text[]', [['x', 'y']])` sends the string `x,y` and
+// Postgres answers `malformed array literal: "x,y"` (SQLSTATE 22P02). Measured on Bun 1.4.0
+// against Postgres 17. Three shipped statements bound an array through that path and every one
+// of them failed — `SQL_CLAIM` (the worker's claim loop), `SQL_OUTBOX_RELEASE` and
+// `SQL_NOTIFY_INBOX_MARK_READ`. Issue #384.
+//
+// WHY HERE AND NOT AT THE THREE CALL SITES. `sendOn` is the one place this driver's `unsafe` is
+// called, so one encoder here is every caller fixed and none of them has to remember — a helper
+// each site imports is three chances to forget and a fourth site tomorrow that does. Axiom 1.
+//
+// WHY PGLITE IS UNTOUCHED. `pglite.ts` is a separate driver with its own `send`, and it encodes an
+// array parameter correctly already — which is exactly why nothing caught this: `x dev` runs the
+// embedded default, so the framework's own dev loop is systematically blind to a defect that only
+// appears once `DATABASE_URL` selects `Bun.SQL`. A container is where it bites.
+
+import { assert } from '@ultimat3/core';
+
+/**
+ * One element, quoted only when it has to be.
+ *
+ * `NULL` unquoted is the array NULL and `"NULL"` is the four-character string, so a JS `null`
+ * MUST render bare and a string that happens to spell it must not. Everything else is quoted when
+ * it holds a character the literal grammar reads as structure — a comma, a brace, a quote, a
+ * backslash, or leading/trailing whitespace the parser would strip — plus the empty string, which
+ * unquoted is not an element at all.
+ */
+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()}"`;
+  const text = String(value);
+  const structural = /[{},"\\\s]/.test(text) || text.length === 0 || text.toUpperCase() === 'NULL';
+  if (!structural) return text;
+  return `"${text.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+}
+
+/**
+ * The array literal for one parameter: `{a,b,c}`, elements escaped.
+ *
+ * NESTED ARRAYS ARE RENDERED, not refused: Postgres reads `{{a,b},{c,d}}` as a 2-dimensional
+ * array, and rendering one is strictly closer to right than sending `a,b,c,d`. Nothing in this
+ * tree binds one today.
+ *
+ * A RAGGED nest is REFUSED, never rendered. Postgres has no jagged array — every extent of a
+ * dimension must match — and `{{a,b},{c}}` is `22P02 malformed array literal`, measured on 17
+ * beside the rectangular `{{a,b},{c,d}}` that parses (`array-parameter.live.test.ts`). So a
+ * literal this function is willing to emit is one the server is willing to read: rendering the
+ * jagged one puts the fault two layers away, in the driver's words, naming neither the parameter
+ * nor which row is short. `X_INVARIANT` through core's `assert`, the code this package already
+ * borrows for a value this build cannot honour (`createIndex`'s unique GIN, `generatedClause`'s
+ * generated-and-defaulted column).
+ */
+export function pgArrayLiteral(values: readonly unknown[]): string {
+  const nested = values.filter((value): value is readonly unknown[] => Array.isArray(value));
+  // Mixed depth is ragged too — `{a,{b,c}}` is a scalar beside a dimension, which Postgres reads
+  // as the same malformed literal. Comparing counts alone would let it through.
+  assert(
+    nested.length === 0 || nested.length === values.length,
+    'a nested array parameter mixes scalars and arrays at one level, and Postgres has no such array',
+    'bind one array of scalars, or one array whose every element is an array of equal length',
+  );
+  const width = nested[0]?.length;
+  assert(
+    nested.every((row) => row.length === width),
+    `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',
+  );
+  return `{${values.map((value) => (Array.isArray(value) ? pgArrayLiteral(value) : element(value))).join(',')}}`;
+}
+
+/**
+ * Every parameter of one statement, arrays rendered and everything else passed through untouched.
+ *
+ * A NEW ARRAY ONLY WHEN SOMETHING CHANGED. Every statement the framework runs goes through this
+ * function, and almost none of them binds an array — so the common path is one `some` over a short
+ * list and the caller's own array object, byte for byte, which is what `sendOn` had before this
+ * existed (axiom 6).
+ *
+ * A `Uint8Array` is BYTEA and is deliberately not an array here: `Array.isArray` answers `false`
+ * for a typed array, which is the behaviour this relies on rather than a special case it writes.
+ */
+export function encodeArrayParameters(values: readonly unknown[]): readonly unknown[] {
+  if (!values.some(Array.isArray)) return values;
+  return values.map((value) => (Array.isArray(value) ? pgArrayLiteral(value) : value));
+}

package/src/bun-sql.ts

@@ -1,13 +1,55 @@
-// Single responsibility: the slice of `Bun.SQL` this package uses, declared structurally, and the
-// lazy lookup of the global that provides it. Reached through a function so importing the client
-// never touches `Bun` at module evaluation — the CLI imports it to print help.
+// Single responsibility: the slice of `Bun.SQL` this package uses, declared structurally, the lazy
+// lookup of the global that provides it, and the one safe way to hand a pinned connection back.
+// Reached through a function so importing the client never touches `Bun` at module evaluation —
+// the CLI imports it to print help.
 
+import { logger, renderThrowable } from '@ultimat3/core';
 import { dbUnavailable } from './errors';
 
 /** One connection pinned out of `Bun.SQL`'s pool, released back by hand. */
 export interface BunSqlReserved {
   unsafe(text: string, values?: readonly unknown[]): Promise<unknown>;
-  release(): void;
+  /**
+   * **Answers a PROMISE, and typing it `void` is what made both callers float it.** Measured on
+   * Bun 1.3.14 and 1.4.0 against a real server: `release()` returns a promise on both, and on
+   * 1.3.14 that promise REJECTS with `ERR_POSTGRES_CONNECTION_CLOSED` when the pool has already
+   * been closed. Nothing was attached to it, so it surfaced as an UNHANDLED REJECTION — which Bun
+   * takes the process down for. `unknown` rather than `Promise<void>` because a fake reserved
+   * connection returns nothing at all, and the caller has to handle both anyway.
+   */
+  release(): unknown;
+}
+
+/**
+ * Hand a pin back, totally. The one place that knows `release()` answers a promise, so neither
+ * caller can forget it (axiom 1) — `client.ts`'s `DbConnection.release` and `pool-reserve.ts`'s
+ * late arrival both route here.
+ *
+ * A failed release is **best-effort, exactly where a throw would mask the error that caused it** —
+ * the rule this package already applies to `ROLLBACK`. `[Symbol.dispose]` is `DbConnection.release`
+ * itself, so a throw there replaces whatever error reached the `using` block, or invents one where
+ * the body succeeded. And the news is unactionable: the connection this would hand back is gone
+ * either way.
+ *
+ * Reachable, and reachable BECAUSE `close()` is bounded: an abandoned drain leaves every
+ * still-pinned connection to be released against a pool that no longer exists.
+ */
+export function releaseReserved(reserved: BunSqlReserved): void {
+  const report = (error: unknown): void => {
+    logger.debug('db.release_failed', { error: renderThrowable(error) });
+  };
+  let settled: unknown;
+  try {
+    settled = reserved.release();
+  } catch (error) {
+    report(error);
+    return;
+  }
+  // `then` and not `instanceof Promise`: the value comes from the driver, and a thenable is the
+  // contract every await in this package already relies on.
+  if (typeof (settled as PromiseLike<unknown> | undefined)?.then === 'function') {
+    void (settled as PromiseLike<unknown>).then(undefined, report);
+  }
 }
 
 /** The slice of `Bun.SQL` we use. Declared structurally so this package has no dependency. */

package/src/client.ts

@@ -1,22 +1,20 @@
-// Single responsibility: the pooled Postgres client and the ambient `db()` handle — one statement
-// funnel, the reserved-connection pin, and the process-wide client every repository reaches
+// Single responsibility: the pooled Postgres client and the ambient `db()` handle — the lazy
+// connect, the reserved-connection pin, and the process-wide client every repository reaches
 // through. Sizing lives in `pool-profile.ts`, the connection string in `connection-url.ts`, the
-// `Bun.SQL` slice in `bun-sql.ts`, so importing this module never opens a socket.
+// `Bun.SQL` slice in `bun-sql.ts` and the observed statement funnel in `statement-funnel.ts`, so
+// importing this module never opens a socket.
 
 import { type Role, resolveRole } from '@ultimat3/core';
-import { statementAttribution } from './attribution';
-import { type BunSqlDriver, type BunSqlReserved, bunSqlFactory } from './bun-sql';
+import { type BunSqlDriver, type BunSqlReserved, bunSqlFactory, releaseReserved } from './bun-sql';
 import { connectionUrl } from './connection-url';
 // Deliberate cycle, the same shape as `client.ts ⇄ transaction.ts`: nothing here is referenced at
 // module evaluation, and both sides are `function` declarations, so hoisting covers the TDZ.
 import { defaultClient } from './default-client';
-import { DbError, driverError } from './errors';
-import { expectedQueryLoopReason } from './expected-loop';
-import { statementObserver } from './observe';
+import { DbError, drainTimeout, driverError } from './errors';
 import { assertPoolProfile, type PoolProfile, poolProfileFor } from './pool-profile';
 import { reserveWithin } from './pool-reserve';
 import { type SqlFragment, sql } from './sql';
-import { withStatementSpan } from './statement-span';
+import { affectedBy, rowsOf, runOn } from './statement-funnel';
 import { currentTx } from './transaction';
 
 export interface DbClient {
@@ -51,20 +49,6 @@ export interface PostgresClientOptions {
   readonly applicationName?: string | undefined;
 }
 
-function rowsOf<T>(result: unknown): readonly T[] {
-  return Array.isArray(result) ? (result as readonly T[]) : [];
-}
-
-// The command tag only when it counted something, exactly like `rowsOf` in `pglite.ts` — one rule
-// across both drivers, so `execute()` and the observer's event cannot answer differently for the
-// same statement depending on which database is behind them. A driver that tags a read `0` while
-// returning rows would otherwise report 0 here and the row count there.
-function affectedBy(result: unknown): number {
-  if (!Array.isArray(result)) return 0;
-  const count = (result as { count?: unknown }).count;
-  return typeof count === 'number' && count > 0 ? count : result.length;
-}
-
 export interface PostgresClient extends ReservableClient {
   readonly profile: PoolProfile;
   ping(): Promise<void>;
@@ -88,76 +72,6 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
     return driver;
   }
 
-  /** The send itself: one statement on one handle, every driver failure typed on the way out. */
-  async function sendOn(
-    driver: Pick<BunSqlDriver, 'unsafe'>,
-    fragment: SqlFragment,
-  ): Promise<unknown> {
-    try {
-      return await driver.unsafe(fragment.text, fragment.values);
-    } catch (error) {
-      // `driverError`, not `dbUnavailable`: the SQLSTATE has always been on this error and nothing
-      // read it, so a `23505` from two clicks racing a signup told the operator the database was
-      // unreachable and paged on-call for an outage that never happened. Everything the table does
-      // not classify is still `X_DB_UNAVAILABLE`, byte for byte.
-      throw driverError(`statement failed: ${fragment.text.slice(0, 120)}`, error);
-    }
-  }
-
-  /**
-   * The funnel — pooled and pinned statements both arrive here, which is why the observer hangs
-   * off this one function and nowhere else. Uninstalled it costs one property read and one
-   * branch: no clock read, no span, no event object, and `sendOn` receives exactly the call `runOn`
-   * made before the seam existed (axiom 6).
-   */
-  async function runOn(
-    driver: Pick<BunSqlDriver, 'unsafe'>,
-    fragment: SqlFragment,
-  ): Promise<unknown> {
-    const observer = statementObserver();
-    if (observer === undefined) return sendOn(driver, fragment);
-    // Read here, not by the consumer: the scope is gone by the time a per-request detector judges
-    // what it collected, so the reason has to be captured with the statement it defends.
-    const expected = expectedQueryLoopReason();
-    // Same moment, same argument: `postgresRepo` is several frames and a microtask above this one,
-    // and what it knows — the entity and the operation — is what turns fifty identical `select`s
-    // into "50× findById on members". Absent for hand-written SQL, a migration, a health probe.
-    const attribution = statementAttribution();
-    const started = performance.now();
-    let result: unknown;
-    try {
-      // The span wraps the send and nothing else, so its duration is the statement's and the
-      // observer's own work is not charged to the database.
-      result = await withStatementSpan(fragment.text, () => sendOn(driver, fragment));
-    } catch (error) {
-      // A statement that failed is still a statement: fifty identical timeouts are an N+1 of
-      // timeouts. The error is already `X_DB_UNAVAILABLE`, so the event carries what the caller
-      // is about to be thrown — and an observer that throws here replaces it, which is why
-      // `observe.ts` says a reporting-only observer must not throw.
-      observer.onStatement({
-        text: fragment.text,
-        values: fragment.values,
-        durationMs: performance.now() - started,
-        rows: 0,
-        error,
-        attribution,
-        expected,
-      });
-      throw error;
-    }
-    // Outside the `try` deliberately: a throw from `onStatement` is the observer's, not the
-    // database's, and catching it above would report a statement that succeeded as failed.
-    observer.onStatement({
-      text: fragment.text,
-      values: fragment.values,
-      durationMs: performance.now() - started,
-      rows: affectedBy(result),
-      attribution,
-      expected,
-    });
-    return result;
-  }
-
   async function run(fragment: SqlFragment): Promise<unknown> {
     return runOn(connect(), fragment);
   }
@@ -206,7 +120,8 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
       const release = (): void => {
         if (!held) return;
         held = false;
-        reserved.release();
+        // Total by construction — `releaseReserved` owns the reason (`bun-sql.ts`).
+        releaseReserved(reserved);
       };
       return {
         query: async <T>(fragment: SqlFragment) => rowsOf<T>(await on(fragment)),
@@ -227,7 +142,40 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
       // rejection still reaches the caller — a shutdown that could not drain wants to know.
       const pool = driver;
       driver = undefined;
-      await pool?.close();
+      if (pool === undefined) return;
+      // BOUNDED, `As of 2026-08-27`, and through the driver's OWN option rather than a race here.
+      // This was a bare `await pool.close()`, and `Bun.SQL`'s `end()` waits on an outstanding
+      // reserved connection without ever giving up — measured three runs per case on Bun 1.3.14
+      // AND 1.4.0, no database outage involved (#394). So a role whose database went away
+      // mid-shutdown never finished shutting down, and the operator's only signal was a container
+      // that burned its whole termination grace period before SIGKILL.
+      //
+      // `BunSqlDriver.close` has declared `{ timeout }` since this port was written and NOTHING
+      // ever passed it — the capability was in the seam, unused, exactly like `setOfflineMode` on
+      // the CDP port. Measured with a reserve outstanding: `close({ timeout: 1 })` returns in
+      // ~1002ms on 1.3.14, 1.4.0 and 1.4.1-canary alike, where a bare `close()` never returns.
+      //
+      // **The unit is SECONDS**, not milliseconds. `timeout: 5000` would be an eighty-three minute
+      // shutdown budget, which is the same hang with extra steps.
+      if (profile.drainTimeoutMs === 0) {
+        // `migrate` and `replicator`, for `acquireTimeoutMs`' reason: a run-once role cutting off
+        // its own session mid-statement is worse than a slow exit.
+        await pool.close();
+        return;
+      }
+      // `performance.now()`, never `Date.now()`, and the reason is this repo rather than NTP: the
+      // framework preload freezes `Date` for every test in the tree (`installDeterminism`), so a
+      // duration subtracted from `Date.now()` is 0 in all of them — the branch below could not
+      // fire, and the test asserting it would have been one that cannot fail.
+      const started = performance.now();
+      await pool.close({ timeout: profile.drainTimeoutMs / 1000 });
+      // The driver RESOLVES when it gives up — it does not reject — so the elapsed time is the only
+      // thing that separates "drained" from "abandoned". Reporting it is the point: a drain that
+      // silently gave up looks exactly like a clean one, and the work still in flight is lost with
+      // no line anywhere saying so. The pool is gone either way, which is why this is terminal.
+      if (performance.now() - started >= profile.drainTimeoutMs) {
+        throw drainTimeout(profile.drainTimeoutMs, role);
+      }
     },
   };
   return client;

package/src/connection-url.ts

@@ -3,7 +3,7 @@
 // `client.ts` because which settings reach a connection is a rule, not a step of connecting.
 
 import { describeValue } from '@ultimat3/core';
-import { dbUnavailable } from './errors';
+import { DbError, dbUnavailable } from './errors';
 import { declaresLibpqOption, mergeLibpqOptions } from './libpq-options';
 import type { PoolProfile } from './pool-profile';
 
@@ -12,6 +12,41 @@ export interface ConnectionUrlOptions {
   readonly applicationName?: string | undefined;
 }
 
+/**
+ * The schemes on which `Bun.SQL` opens a POSTGRES connection — measured against bun 1.4.0, never
+ * assumed. `postgres:` and `postgresql:` both answer `adapter: 'postgres'`; `pg:`, `tcp:` and
+ * `postgresql+ssl:` are refused by the driver itself (`Unsupported protocol: … Supported adapters:
+ * "postgres", "sqlite", "mysql", "mariadb"`), so excluding them costs a capability nobody has.
+ * The two that matter are the ones the driver ACCEPTS and this package cannot speak: `mysql:`,
+ * `mariadb:`, `sqlite:` and `file:` open a different engine, and every statement generated here is
+ * Postgres — a pool that connects and then answers a syntax error to the migration is strictly
+ * worse than one that refuses at boot.
+ */
+const POSTGRES_SCHEMES: ReadonlySet<string> = new Set(['postgres:', 'postgresql:']);
+
+/**
+ * The received scheme is deliberately NOT named, which is the one place this refusal differs from
+ * every other "errors are instructions" case in the package. `new URL()` accepts a scheme-less
+ * string by reading the first token as the scheme, and that token is exactly the value this must
+ * not echo: `db.internal:5432/app` parses with `db.internal:` — the HOST — as its protocol, and
+ * `app:hunter2@db.internal/app`, the same typo copied one dashboard field over, parses with the
+ * USERNAME as its protocol. Naming "the scheme" therefore puts a host or a credential in the boot
+ * log AND the `--json` payload, where the logger has no key left to redact it by (see the block in
+ * the parse `catch` below). The REQUIRED scheme is a constant and carries the whole instruction, so
+ * nothing actionable is lost by withholding the received one; `describeValue` keeps the shape, so
+ * an empty variable is still told apart from a truncated one.
+ */
+const schemeUnsupported = (raw: string): DbError =>
+  new DbError({
+    code: 'X_DB_UNAVAILABLE',
+    cause:
+      'DATABASE_URL does not name a postgres:// or postgresql:// url: ' +
+      `received ${describeValue(raw)}`,
+    fix:
+      'set DATABASE_URL to postgres://user@host:5432/database — a value with no scheme parses ' +
+      'as a url whose scheme is its own first token — or run `x dev` to use the embedded PGlite',
+  });
+
 export function connectionUrl(options: ConnectionUrlOptions, profile: PoolProfile): string {
   const raw = options.url ?? process.env['DATABASE_URL'];
   if (raw === undefined || raw === '') {
@@ -30,6 +65,13 @@ export function connectionUrl(options: ConnectionUrlOptions, profile: PoolProfil
     // `maskedEnvValues`.
     throw dbUnavailable(`DATABASE_URL is not a valid url: received ${describeValue(raw)}`, error);
   }
+  // Screened here because `Bun.SQL` will not screen it: measured on bun 1.4.0, it reads
+  // `db.internal:5432/app` as host `db.internal`, port 5432, database `app` and opens a Postgres
+  // pool on it, so the first symptom is a connect failure at the first QUERY, in another process
+  // phase, worded by the driver and naming neither `DATABASE_URL` nor the missing scheme. Worse,
+  // `sqlite://./dev.db` succeeds outright on a different engine. A boot-time refusal is the only
+  // point at which the value is still nameable.
+  if (!POSTGRES_SCHEMES.has(url.protocol)) throw schemeUnsupported(raw);
   // libpq `options` is the portable way to pin a statement timeout for every pooled connection —
   // MERGED into the operator's own, never assigned over it, and emitted for every role including
   // the two whose bound is 0. `set` here dropped a `?options=-c search_path=app` on `web`, `sync`,

package/src/errors.ts

@@ -25,6 +25,7 @@ export const DB_OWNED_ERROR_CODES = [
   'X_DB_STATEMENT_TIMEOUT',
   'X_DB_LOCK_TIMEOUT',
   'X_DB_POOL_EXHAUSTED',
+  'X_DB_DRAIN_TIMEOUT',
   'X_DB_DRIFT',
   'X_MIGRATION_CONFLICT',
   'X_MIGRATION_IRREVERSIBLE',
@@ -66,6 +67,7 @@ export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
   X_DB_STATEMENT_TIMEOUT: 'the statement ran past its statement_timeout',
   X_DB_LOCK_TIMEOUT: 'the statement waited past its lock_timeout',
   X_DB_POOL_EXHAUSTED: 'no connection was available',
+  X_DB_DRAIN_TIMEOUT: 'the pool did not drain inside its shutdown budget',
   X_DB_DRIFT: 'schema differs from migrations',
   X_MIGRATION_CONFLICT: 'the migration ledger disagrees with this build',
   X_MIGRATE_CONCURRENT: 'another migrator holds the migration lock',
@@ -238,6 +240,24 @@ export const driverError = (detail: string, sourceError: unknown): DbError => {
   });
 };
 
+/**
+ * `close()` gave up waiting for the pool. TERMINAL, and deliberately not retryable: the pool is
+ * gone either way — `close()` clears the handle before it awaits — so a caller that retried would
+ * be closing a pool that no longer exists. What this reports is that connections were still held
+ * when the process stopped waiting, which is a fact about the shutdown an operator has to see.
+ *
+ * The alternative was to resolve quietly on the deadline, and that is the version that hides the
+ * bug: a drain that silently gave up looks exactly like a clean one, and the rows still in flight
+ * are lost with no line anywhere saying so.
+ */
+export const drainTimeout = (ms: number, role: string): DbError =>
+  new DbError({
+    code: 'X_DB_DRAIN_TIMEOUT',
+    cause: `the ${role} pool still held connections after ${String(ms)}ms, so close() stopped waiting`,
+    fix: `find the statement that will not finish — psql "$DATABASE_URL" -c "select pid, state, query from pg_stat_activity where state <> 'idle'" — or raise drainTimeoutMs in createPostgresClient({ profile }) for the ${role} role`,
+    meta: { drainTimeoutMs: ms, role },
+  });
+
 /**
  * The pool answered nothing inside `acquireTimeoutMs`. Distinct from the server's own `53300` and
  * deliberately the same code: to a caller both mean "there was no connection for this unit of

package/src/generate.ts

@@ -22,6 +22,8 @@ import {
 } from './introspect';
 import { declaredIndexes } from './invariant-ddl';
 import { migrationIrreversible } from './migration-errors';
+import type { ReplicaIdentityInput } from './replica-identity';
+import { replicaIdentityFullAfter, replicaIdentityPlan } from './replica-identity';
 import type { MovedAside } from './retype-dependents';
 import { moveDependentsAside } from './retype-dependents';
 import { moveKeysAside, retypedColumns, retypedIn } from './retype-keys';
@@ -54,7 +56,13 @@ function columnClause(column: ColumnDescriptionLike): string {
   return parts.join(' ');
 }
 
-export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDescription {
+/** No table subscribed to, which is what every caller outside `generateMigration` describes. */
+const NONE: ReadonlySet<string> = new Set();
+
+export function snapshotOf(
+  entities: readonly EntityDescriptionLike[],
+  replicaIdentityFull: ReadonlySet<string> = NONE,
+): SchemaDescription {
   const tables = [...entities]
     .sort((a, b) => (a.table < b.table ? -1 : 1))
     .map((entity): TableDescription => {
@@ -99,6 +107,9 @@ export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDe
         // read as "nothing recorded" so the next generation adds the constraints the database is
         // genuinely missing — the rule `using` and `generated` already state one field up.
         ...(checks.length === 0 ? {} : { checks }),
+        // The same rule once more: `true` or absent, never `false`. This is what makes the ALTER
+        // beside it a one-time statement rather than a line every `x db gen` writes again.
+        ...(replicaIdentityFull.has(entity.table) ? { replicaIdentityFull: true as const } : {}),
       };
     });
   return { tables };
@@ -227,6 +238,17 @@ export interface GenerateOptions {
   readonly now?: Date | undefined;
   /** Allow a DROP COLUMN whose down cannot restore the data. `x db gen --allow-destructive`. */
   readonly allowDestructive?: boolean | undefined;
+  /**
+   * Tables a live query subscribes to, so logical replication carries the old row —
+   * `@ultimat3/realtime` refuses a subscription without it. Absent or empty emits nothing.
+   *
+   * A parameter and never an `EntityDescriptionLike` field: which tables need it is DECLARED by
+   * each `live: true` query's `subscribes:`, never derived — the relation is a literal inside the
+   * query's `sql:` callback, which nothing can invoke without valid input. This package is tier 1
+   * and can see neither the manifest nor `@ultimat3/query`, so `@ultimat3/cli`'s `db-generate.ts`
+   * is the one caller that can answer it.
+   */
+  readonly replicaIdentityFull?: readonly string[] | undefined;
 }
 
 export interface GeneratedMigration {
@@ -275,6 +297,9 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   // of one key can move in two different entities' diffs (`retype-keys.ts`).
   const preAlters: Plan = { up: [], down: [] };
   const wanted = new Set(options.entities.map((entity) => entity.table));
+  // The tables this run brings into being, read by the replica-identity arm below: their `down` is
+  // already `drop table`, so reverting the identity ahead of it performs nothing.
+  const created = new Set<string>();
 
   const doomed = new Set(
     current.tables.filter((table) => !wanted.has(table.name)).map((table) => table.name),
@@ -291,6 +316,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     if (live === undefined) {
       plan.up.push(...createTable(entity));
       plan.down.push(`drop table ${identifier(entity.table).text};`);
+      created.add(entity.table);
       continue;
     }
     diffTable(entity, live, plan, retypedIn(retyped, entity.table));
@@ -337,6 +363,18 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   plan.up.push(...constraints.up);
   plan.down.push(...constraints.down);
 
+  // Dead last in `up`, and it is the only placement that is right for every arm: the table has to
+  // exist, and a `create table` in this same migration is the reason it might not. It is ordered
+  // against nothing else — replica identity constrains no column, no index and no constraint — so
+  // the end is where it can never be read as depending on a statement above it.
+  const replicaIdentity: ReplicaIdentityInput = {
+    wanted: options.replicaIdentityFull,
+    declared: wanted,
+    created,
+    current,
+  };
+  replicaIdentityPlan(plan, replicaIdentity);
+
   const id = `${migrationStamp(options.now ?? systemClock.now())}_${slugify(options.name)}`;
   // At the TOP of `up`, so what is MISSING is the first thing read — and a line comment, so it is
   // noise to every reader that matters: `statementsOf` drops a chunk of comments alone,
@@ -362,7 +400,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     // FRONT here precisely so reversal puts it last — a key is added back only once both of its
     // ends have been retyped back, which is every other statement in the script.
     down: [...preAlters.down, ...plan.down].reverse().join('\n'),
-    snapshot: snapshotOf(options.entities),
+    snapshot: snapshotOf(options.entities, replicaIdentityFullAfter(replicaIdentity)),
     destructive: isDestructive(up),
     unrendered,
   };

package/src/introspect.ts

@@ -105,6 +105,22 @@ export interface TableDescription {
    * read one instead of reporting every declared constraint as missing.
    */
   readonly checkNames?: readonly string[] | undefined;
+  /**
+   * That a migration set `replica identity full` on this table — what `@ultimat3/realtime` requires
+   * of every table a live query subscribes to, and the only reason this generator emits it.
+   *
+   * `true` or absent, never `false`, and the literal type is what enforces it. Absent means
+   * *nothing recorded*: a sidecar written before this field existed, exactly as `checks` absent
+   * means "no constraint was recorded" rather than "none is declared". Writing `false` onto every
+   * table an app has would rewrite every sidecar in the tree on the next `x db gen` for a fact that
+   * was already true — the argument `IndexDescription.using` makes about `btree`.
+   *
+   * `introspect()` never answers it. The catalog's half is `pg_class.relreplident`, which
+   * `@ultimat3/realtime`'s preflight already reads at the only moment it matters; a second reader
+   * here would let a `diffSchema` compare a declaration against a catalog value, which is the
+   * mistake `checks` and `checkNames` exist as two fields to prevent.
+   */
+  readonly replicaIdentityFull?: true | undefined;
 }
 
 export interface SchemaDescription {

package/src/pool-profile.ts

@@ -1,4 +1,4 @@
-// Single responsibility: the five numbers a Postgres pool runs on — the per-role defaults, the one
+// Single responsibility: the six numbers a Postgres pool runs on — the per-role defaults, the one
 // environment override an operator may layer over them, and the screen every resolved profile
 // passes. Split from `client.ts`, which now owns connecting and nothing about sizing.
 
@@ -25,6 +25,24 @@ export interface PoolProfile {
    * kills the pod, and the replacement inherits the same saturated database.
    */
   readonly acquireTimeoutMs: number;
+  /**
+   * How long `close()` may wait for the pool to drain before `X_DB_DRAIN_TIMEOUT`. 0 waits forever.
+   *
+   * **A drain that cannot finish is the failure this bounds, and it is not hypothetical.** Measured
+   * against a real Postgres, three runs per case: `Bun.SQL`'s `end()` waits on an outstanding
+   * RESERVED connection and never stops waiting — 3 of 3 on Bun 1.3.14 *and* 3 of 3 on 1.4.0, with
+   * no database outage involved at all. Once that connection's backend has been terminated it
+   * becomes a race, which 1.3.14 loses 3 of 3 and 1.4.0 loses 1 of 3. So the runtime is not the
+   * variable; an unbounded await is (#394).
+   *
+   * What that cost, before this: `releaseQueue` awaits `db.close()`, so a role whose database went
+   * away mid-shutdown never finished shutting down. A container that will not drain is drained by
+   * SIGKILL, and the operator's only signal is a pod that took its full termination grace period.
+   *
+   * `migrate` and `replicator` wait forever, deliberately, for `acquireTimeoutMs`' reason: a
+   * run-once role cutting off its own session mid-statement is worse than a slow exit.
+   */
+  readonly drainTimeoutMs: number;
 }
 
 /** Sized per role because the failure modes differ: RPS bursts vs. queue depth vs. run-once. */
@@ -35,6 +53,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     idleTimeoutMs: 30_000,
     lockTimeoutMs: 0,
     acquireTimeoutMs: 5_000,
+    drainTimeoutMs: 5_000,
   },
   sync: {
     max: 10,
@@ -42,6 +61,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     idleTimeoutMs: 60_000,
     lockTimeoutMs: 0,
     acquireTimeoutMs: 5_000,
+    drainTimeoutMs: 5_000,
   },
   worker: {
     max: 8,
@@ -49,6 +69,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     idleTimeoutMs: 30_000,
     lockTimeoutMs: 0,
     acquireTimeoutMs: 10_000,
+    drainTimeoutMs: 15_000,
   },
   scheduler: {
     max: 2,
@@ -56,6 +77,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     idleTimeoutMs: 60_000,
     lockTimeoutMs: 0,
     acquireTimeoutMs: 10_000,
+    drainTimeoutMs: 5_000,
   },
   // `migrate` waits: its pool is `max: 1` and the advisory-lock pin holds it for the whole run, so
   // a deadline here would refuse the migration's own session. The wait that needed bounding is the
@@ -66,6 +88,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     idleTimeoutMs: 10_000,
     lockTimeoutMs: 3_000,
     acquireTimeoutMs: 0,
+    drainTimeoutMs: 0,
   },
   replicator: {
     max: 4,
@@ -73,6 +96,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     idleTimeoutMs: 60_000,
     lockTimeoutMs: 0,
     acquireTimeoutMs: 0,
+    drainTimeoutMs: 0,
   },
 });
 
@@ -99,13 +123,13 @@ export function poolMaxFromEnv(): Partial<PoolProfile> {
 }
 
 /**
- * The five numbers a pool runs on, screened on the MERGED profile — an override is spread over a
+ * The six numbers a pool runs on, screened on the MERGED profile — an override is spread over a
  * role default the caller never restated, so the resolved object is the only one that can be
  * judged. Every one of them is a plausible `Number(process.env.…)`, which is `NaN` for an unset
- * variable and not nullish, so `??` and the spread both keep it. None of the five then fails
+ * variable and not nullish, so `??` and the spread both keep it. None of the six then fails
  * loudly: `idleTimeout: NaN` goes to `Bun.SQL`, `statement_timeout=NaN` goes into the libpq
  * options string for the SERVER to reject on connect, and a timer given `NaN` fires at 1ms in this
- * Bun — so a pool with free connections reports itself exhausted. `0` stays legal for the three
+ * Bun — so a pool with free connections reports itself exhausted. `0` stays legal for the five
  * budgets that document it as "no bound"; `max` is at least one connection, or nothing can run.
  */
 export function assertPoolProfile(profile: PoolProfile): PoolProfile {
@@ -121,5 +145,6 @@ export function assertPoolProfile(profile: PoolProfile): PoolProfile {
   whole('idleTimeoutMs', profile.idleTimeoutMs, 0);
   whole('lockTimeoutMs', profile.lockTimeoutMs, 0);
   whole('acquireTimeoutMs', profile.acquireTimeoutMs, 0);
+  whole('drainTimeoutMs', profile.drainTimeoutMs, 0);
   return profile;
 }

package/src/pool-reserve.ts

@@ -2,7 +2,7 @@
 // and giving back a reservation that arrives after the deadline has passed. Split from `client.ts`,
 // which now asks for a pin rather than owning what "waited too long" means.
 
-import type { BunSqlDriver, BunSqlReserved } from './bun-sql';
+import { type BunSqlDriver, type BunSqlReserved, releaseReserved } from './bun-sql';
 import { poolAcquireTimeout } from './errors';
 import type { PoolProfile } from './pool-profile';
 
@@ -42,7 +42,7 @@ export async function reserveWithin(
     // Attached unconditionally so a rejection arriving after we gave up is handled, not unhandled.
     void pending.then(
       (late) => {
-        if (expired) late.release();
+        if (expired) releaseReserved(late);
       },
       () => undefined,
     );

package/src/replica-identity.ts

@@ -0,0 +1,84 @@
+// Single responsibility: the `alter table … replica identity full` a live query needs, emitted once.
+// `@ultimat3/realtime` refuses a subscription to a table without it — logical replication carries no
+// old row on an UPDATE, so no patch can be computed — and which tables need it is a tier-3 fact no
+// entity carries, so it arrives as `GenerateOptions.replicaIdentityFull` and is recorded on the
+// snapshot: the record is what stops the statement being re-emitted on every `x db gen`.
+
+import type { Plan } from './foreign-key-plan';
+import { findTable, type SchemaDescription } from './introspect';
+import { identifier } from './sql';
+
+export interface ReplicaIdentityInput {
+  /** Tables a live query subscribes to. Absent or empty emits nothing and reverts nothing. */
+  readonly wanted: readonly string[] | undefined;
+  /** The tables this migration leaves standing — the ALTER may name no other. */
+  readonly declared: ReadonlySet<string>;
+  /** Of those, the ones it CREATES: their whole `down` is already `drop table`. */
+  readonly created: ReadonlySet<string>;
+  /** What migrations already recorded — `expectedSchema(migrations, ledger)`. */
+  readonly current: SchemaDescription;
+}
+
+/**
+ * Whether the recorded schema already says this table carries it.
+ *
+ * Absent — never `false` — is a sidecar written before the field existed: it declares nothing, so
+ * the ALTER is emitted once more against a table that may already have it, which Postgres accepts.
+ * The opposite reading would be "recorded as not full", and a snapshot that predates the field
+ * cannot mean that. `TableDescription.checks` states the same rule for the same reason.
+ */
+export function recordsReplicaIdentityFull(current: SchemaDescription, table: string): boolean {
+  return findTable(current, table)?.replicaIdentityFull === true;
+}
+
+/** Which tables to record on the snapshot — sorted only by the caller's own table order. */
+function pending(input: ReplicaIdentityInput): readonly string[] {
+  // Deduplicated and sorted, so the same live-query set generates the same bytes whatever order the
+  // manifest walked its queries in: a diff that moves a line is a diff an author has to read.
+  return [...new Set(input.wanted ?? [])]
+    .filter((table) => input.declared.has(table))
+    .filter((table) => !recordsReplicaIdentityFull(input.current, table))
+    .sort();
+}
+
+/**
+ * The tables carrying it once this migration has applied — what `snapshotOf` records.
+ *
+ * The UNION with what is already recorded, never this run's set alone. A caller that passes no
+ * live-query set (`x db gen` from a command that never learned about one) must not silently erase
+ * the fact from the sidecar, or the very next run emits the ALTER again on a table that has it.
+ */
+export function replicaIdentityFullAfter(input: ReplicaIdentityInput): ReadonlySet<string> {
+  const after = new Set<string>();
+  for (const table of input.declared) {
+    if (recordsReplicaIdentityFull(input.current, table)) after.add(table);
+  }
+  for (const table of pending(input)) after.add(table);
+  return after;
+}
+
+/**
+ * Additive only, and never destructive. `alter table … replica identity full` widens what logical
+ * replication carries; it drops no row, rewrites no column and matches none of `destructive.ts`'s
+ * four rules, so the migration it lands in needs no `-- destructive: true` marker.
+ *
+ * A name matching no entity is SKIPPED rather than refused: the list is derived from the manifest's
+ * live queries, and a query whose entity has been deleted is an app fault the generator cannot
+ * repair — emitting the statement anyway would be `42P01` at `ROLE=migrate`, which is the one place
+ * this package refuses to put a fault.
+ *
+ * Nothing is ever reverted. A table dropping out of the live-query set keeps the identity it has:
+ * the option is optional, so "absent" and "no live query subscribes any more" are the same value,
+ * and reading them alike would let a caller that never passes the option turn off replication for
+ * every subscribed table in the app.
+ */
+export function replicaIdentityPlan(plan: Plan, input: ReplicaIdentityInput): void {
+  for (const table of pending(input)) {
+    const name = identifier(table).text;
+    plan.up.push(`alter table ${name} replica identity full;`);
+    // A table this migration created is dropped by its own `down`; a second statement ahead of that
+    // is a line an author reads and nothing performs.
+    if (input.created.has(table)) continue;
+    plan.down.push(`alter table ${name} replica identity default;`);
+  }
+}

package/src/snapshot-parse.ts

@@ -112,11 +112,20 @@ function tableOf(value: unknown): TableDescription | undefined {
   // Absent, never `[]`. A sidecar written before constraints were recorded says nothing about
   // them, and reading that as "this table declares none" would drop every invariant an app has
   // already generated instead of adding the ones its database is missing.
+  // `true` or nothing. `false` is accepted and NORMALISED away rather than rejecting the file: it
+  // is a hand-edit meaning exactly what absence means, and discarding the whole snapshot over it
+  // makes `x db gen` refuse with `X_MIGRATION_SNAPSHOT_MISSING` on a sidecar that says nothing
+  // wrong. Any other value is garbage and takes the file with it, like every field above.
+  const identity = value['replicaIdentityFull'];
+  if (!(identity === undefined || bool(identity))) return undefined;
+  const replica = identity === true ? { replicaIdentityFull: true as const } : {};
   const raw = value['checks'];
-  if (raw === undefined) return { schema, name, columns, primaryKey, indexes, foreignKeys };
+  if (raw === undefined) {
+    return { schema, name, columns, primaryKey, indexes, foreignKeys, ...replica };
+  }
   const checks = all(raw, check);
   if (checks === undefined) return undefined;
-  return { schema, name, columns, primaryKey, indexes, foreignKeys, checks };
+  return { schema, name, columns, primaryKey, indexes, foreignKeys, checks, ...replica };
 }
 
 /**

package/src/statement-funnel.ts

@@ -0,0 +1,101 @@
+// Single responsibility: the pooled driver's statement funnel — one statement on one handle, every
+// driver failure typed on the way out, and the installed `StatementObserver` notified on both
+// settle paths. Split from `client.ts` at the file-size rule; `pglite.ts` holds the mirror pair
+// (`send`/`statement`) for the embedded driver, and the two must keep answering the same way.
+
+import { encodeArrayParameters } from './array-parameter';
+import { statementAttribution } from './attribution';
+import type { BunSqlDriver } from './bun-sql';
+import { driverError } from './errors';
+import { expectedQueryLoopReason } from './expected-loop';
+import { statementObserver } from './observe';
+import type { SqlFragment } from './sql';
+import { withStatementSpan } from './statement-span';
+
+export function rowsOf<T>(result: unknown): readonly T[] {
+  return Array.isArray(result) ? (result as readonly T[]) : [];
+}
+
+// The command tag only when it counted something, exactly like `rowsOf` in `pglite.ts` — one rule
+// across both drivers, so `execute()` and the observer's event cannot answer differently for the
+// same statement depending on which database is behind them. A driver that tags a read `0` while
+// returning rows would otherwise report 0 here and the row count there.
+export function affectedBy(result: unknown): number {
+  if (!Array.isArray(result)) return 0;
+  const count = (result as { count?: unknown }).count;
+  return typeof count === 'number' && count > 0 ? count : result.length;
+}
+
+/** The send itself: one statement on one handle, every driver failure typed on the way out. */
+async function sendOn(
+  driver: Pick<BunSqlDriver, 'unsafe'>,
+  fragment: SqlFragment,
+): Promise<unknown> {
+  try {
+    // `encodeArrayParameters`, never `fragment.values` raw: `Bun.SQL` joins a JS array's elements
+    // with commas, so every `any($n::T[])` in this framework sent Postgres a malformed literal and
+    // failed — the worker's claim loop among them (#384). One encoder here rather than one import
+    // per call site, because this is the only place this driver's `unsafe` is called.
+    return await driver.unsafe(fragment.text, encodeArrayParameters(fragment.values));
+  } catch (error) {
+    // `driverError`, not `dbUnavailable`: the SQLSTATE has always been on this error and nothing
+    // read it, so a `23505` from two clicks racing a signup told the operator the database was
+    // unreachable and paged on-call for an outage that never happened. Everything the table does
+    // not classify is still `X_DB_UNAVAILABLE`, byte for byte.
+    throw driverError(`statement failed: ${fragment.text.slice(0, 120)}`, error);
+  }
+}
+
+/**
+ * The funnel — pooled and pinned statements both arrive here, which is why the observer hangs
+ * off this one function and nowhere else. Uninstalled it costs one property read and one
+ * branch: no clock read, no span, no event object, and `sendOn` receives exactly the call `runOn`
+ * made before the seam existed (axiom 6).
+ */
+export async function runOn(
+  driver: Pick<BunSqlDriver, 'unsafe'>,
+  fragment: SqlFragment,
+): Promise<unknown> {
+  const observer = statementObserver();
+  if (observer === undefined) return sendOn(driver, fragment);
+  // Read here, not by the consumer: the scope is gone by the time a per-request detector judges
+  // what it collected, so the reason has to be captured with the statement it defends.
+  const expected = expectedQueryLoopReason();
+  // Same moment, same argument: `postgresRepo` is several frames and a microtask above this one,
+  // and what it knows — the entity and the operation — is what turns fifty identical `select`s
+  // into "50× findById on members". Absent for hand-written SQL, a migration, a health probe.
+  const attribution = statementAttribution();
+  const started = performance.now();
+  let result: unknown;
+  try {
+    // The span wraps the send and nothing else, so its duration is the statement's and the
+    // observer's own work is not charged to the database.
+    result = await withStatementSpan(fragment.text, () => sendOn(driver, fragment));
+  } catch (error) {
+    // A statement that failed is still a statement: fifty identical timeouts are an N+1 of
+    // timeouts. The error is already `X_DB_UNAVAILABLE`, so the event carries what the caller
+    // is about to be thrown — and an observer that throws here replaces it, which is why
+    // `observe.ts` says a reporting-only observer must not throw.
+    observer.onStatement({
+      text: fragment.text,
+      values: fragment.values,
+      durationMs: performance.now() - started,
+      rows: 0,
+      error,
+      attribution,
+      expected,
+    });
+    throw error;
+  }
+  // Outside the `try` deliberately: a throw from `onStatement` is the observer's, not the
+  // database's, and catching it above would report a statement that succeeded as failed.
+  observer.onStatement({
+    text: fragment.text,
+    values: fragment.values,
+    durationMs: performance.now() - started,
+    rows: affectedBy(result),
+    attribution,
+    expected,
+  });
+  return result;
+}

package/src/ungeneratable.ts

@@ -59,6 +59,17 @@ export const GENERATABLE_FORMS: readonly GeneratableForm[] = [
     name: 'alter column drop expression',
     pattern: /^alter\s+table\s[\s\S]*?\balter\s+column\s[\s\S]*?\bdrop\s+expression\b/,
   },
+  // The form the doc block above calls "the statement that started this", finally on the list:
+  // `GenerateOptions.replicaIdentityFull` emits it `As of 2026-08-26`, so without this entry the
+  // rail reports SQL the generator itself just wrote. Covers `full` and `default` in one phrase —
+  // the down side is as generated as the up side.
+  {
+    name: 'alter table … replica identity full/default',
+    // `full` and `default` ONLY — the two modes `replicaIdentityPlan` emits. `using index` and
+    // `nothing` are hand-written configuration no entity declares, and admitting them here would
+    // read them as generatable and let a squash discard the replication setup in silence.
+    pattern: /^alter\s+table\s[\s\S]*?\breplica\s+identity\s+(?:full|default)\b/,
+  },
 ];
 
 /**