@ultimat3/db 16.0.0 → 18.0.0

package/CLAUDE.md

@@ -9,6 +9,7 @@ reaches down to this package for it. **Never** import `entity`, `jobs`, `http` o
 |---|---|
 | Deps | none. `@electric-sql/pglite` is an **optional peer**, imported by variable specifier inside `loadPgliteDriver()` so no consumer's `tsc` or bundler resolves it. **No ORM** — `entity`'s hand-written `postgresDriver()` is the production backing |
 | SQL | `sql` binds `$n`; anything non-scalar and non-fragment throws `X_SQL_UNSAFE` |
+| A name reaching a `fix:` | `shellInertIdentifier()` (`sql.ts`), the tree's ONE screen for it, `As of 2026-08-26`. `identifier()` alone does not close it: it refuses `"`, `\` and whitespace and **accepts** a backtick and a `$` — `SAFE_IDENTIFIER` allows `$` on its fast path — which are the two characters a shell substitutes inside DOUBLE quotes. A refused name is left OUT of the command, never escaped into it |
 | Escape hatches | `raw()`, `identifier()`, `literal()` — each call is an audit point. `literal()` is the tree's ONE SQL-string-literal escape (`scripts/sql-literal-copies.ts`, pinned at zero) and it emits `E'…'` when the value carries a backslash |
 | SQLSTATE | one reader, `sqlState()` (`sqlstate.ts`). Never read `error.code` for a SQLSTATE |
 | Reading a caught value | `renderThrowable()` from core; never `error instanceof Error ? error.message : String(error)` — both halves RUN app code (a `Proxy` trap, `Symbol.toPrimitive`) and `checkDb` backs `/readyz`, where a render that throws is an exception in place of the report the kubelet asked for |
@@ -239,7 +240,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
@@ -256,7 +257,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
@@ -270,7 +271,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,
@@ -288,8 +289,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
@@ -1006,13 +1007,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
@@ -1276,12 +1300,146 @@ takes, and left unsaid an `alter database … set statement_timeout` on the serv
 that must outlive it. The splitter honours libpq's backslash escape, so a `search_path=two\ words`
 survives the round trip whole.
 
+- **Every numeric option this package bounds anything with is screened, `As of 2026-08-26`** —
+  through core's `finiteCount`, which borrows `X_INVARIANT` as this package already does.
+  `replicaClient`'s `breakerFailures` and `breakerCooldownMs` (a breaker is two comparisons and
+  nothing else: `failures >= NaN` never opens it, `monotonic() < NaN` never parks it, so every read
+  keeps going to the replica that is failing), `migrate`'s `lockWaitMs` (`NaN - elapsed <= 0` is
+  false and `Bun.sleep(NaN)` does not sleep — a tight spin re-taking `pg_try_advisory_lock`, not an
+  unbounded wait) and `readonlyQuery`'s `timeoutMs`, plus `client.ts`'s pool profile. The last one
+  is a **behaviour change**: it used to normalise `NaN` to the default silently, so an agent read
+  ran under a ceiling nobody wrote. Only an explicit `0` disables that layer, which is why its floor
+  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
+  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 client object and the ambient `db()` —
+  and it still opens no socket at import, because `bunSqlFactory()` is reached from inside
+  `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
+  file, and the reader had nothing to run and the same finding on the next deploy. The two edits
+  that do resolve it are named instead: a `create table if not exists` in a migration (which
+  `x db migrate` then accepts, through `@ultimat3/cli`'s `acceptCreatedTables`), or `psql … drop
+  table` for a table nothing owns. No migration PATH is named — where an app keeps its migrations is
+  the CLI's fact. `X_DB_DRIFT` is a shipped code and is unchanged; only this `fix:` text moved.
+
+- **A name a `fix:` puts in a command is screened ONCE, by `shellInertIdentifier()` (`sql.ts`),
+  `As of 2026-08-26`.** `identifier()` answers about SQL and cannot close this: it refuses `"`,
+  `\` and whitespace and **accepts** a backtick and a `$` — `SAFE_IDENTIFIER` allows `$` on its
+  fast path — which are exactly the two characters a shell substitutes inside DOUBLE quotes. A
+  `fix:` is pasted into a shell at least as often as into a psql session, so a column named
+  `$(id)` inside `x db gen "add $(id)"` RUNS `id` the moment its reader pastes the line, and a
+  screen reusing `identifier()` unchanged ships a green suite over a live command-execution hole.
+  It began as a private `writableName` in `drift-findings.ts` and was promoted rather than copied:
+  three copies of a string-literal escape shipped here once and two were wrong the same way
+  (`scripts/sql-literal-copies.ts`). Callers **degrade to prose** — the argument to `x db gen` is a
+  migration DESCRIPTION, not an identifier, so no quoted form makes a hostile name safe to pass,
+  and the name is read off `cause`/`meta` instead. Every benign rendering is byte-identical: the
+  screen sits on the refusal branch alone, because roughly ten pages across `packages/cli`,
+  `packages/core`, `wiki/` and `docs/` quote `x db gen "add <name>"` verbatim.
+
+- **`dbDrift()` lives in `drift-errors.ts` and not in `errors.ts`, for exactly the reason
+  `dependent-view.ts` states.** Its `fix:` needs `shellInertIdentifier` and `sql.ts` imports
+  `errors.ts`, so keeping the constructor there is an import cycle around the module whose
+  evaluation REGISTERS every code. `dependent-view.ts` avoided the same cycle by handing
+  `errors.ts` a finished string; that is not available here, because `dbDrift(table, column)` is
+  public API shipped since 1.0 and its signature cannot change. So the constructor moved instead,
+  the way `migration-errors.ts` and `invariant-errors.ts` did — `X_DB_DRIFT` is still declared,
+  titled and registered in `errors.ts`, and `src/index.ts` still exports the same name, so the
+  public surface is byte-identical. `@ultimat3/entity`'s mirror screens through the **same**
+  export across the tier seam (tier 2 → tier 1), which is what keeps the "keep in sync" comment on
+  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
 ```
 
 Gotchas:
+
 - `exactOptionalPropertyTypes` — declare optional fields as `x?: T | undefined`.
 - `noUncheckedIndexedAccess` — array reads are `T | undefined`; `chunks[i] ?? ''` everywhere.
 - Tests use `createRecordingClient()` + `setDbClient()`; no test may need a live database.

package/README.md

@@ -26,6 +26,7 @@ await withTransaction(async (tx) => {
 | Export | |
 |---|---|
 | `sql` / `raw` / `identifier` / `literal` / `join` | fragment builders |
+| `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 |
@@ -42,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` |
@@ -216,9 +217,9 @@ X_DB_DRIFT: schema differs from migrations
 
 | Difference | cause | fix |
 |---|---|---|
-| live column, no migration | `table "T" has column "C" not present in any migration` | `x db gen "add C"` |
+| 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` | `x db gen "add T"` |
+| 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 |
 | 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "16.0.0",
+  "version": "18.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": "16.0.0"
+    "@ultimat3/core": "18.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

@@ -0,0 +1,32 @@
+// 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.
+
+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;
+}
+
+/** The slice of `Bun.SQL` we use. Declared structurally so this package has no dependency. */
+export interface BunSqlDriver {
+  unsafe(text: string, values?: readonly unknown[]): Promise<unknown>;
+  reserve(): Promise<BunSqlReserved>;
+  close(options?: { readonly timeout?: number }): Promise<void>;
+}
+
+export type BunSqlFactory = new (
+  url: string,
+  options?: Readonly<Record<string, unknown>>,
+) => BunSqlDriver;
+
+export function bunSqlFactory(): BunSqlFactory {
+  const host = globalThis as unknown as { readonly Bun?: { readonly SQL?: unknown } };
+  const factory = host.Bun?.SQL;
+  if (typeof factory !== 'function') {
+    throw dbUnavailable('Bun.SQL is unavailable — this package requires Bun >= 1.3');
+  }
+  return factory as BunSqlFactory;
+}