@ultimat3/db 15.0.0 → 17.0.0

package/CLAUDE.md

@@ -9,11 +9,12 @@ 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` |
-| Escape hatches | `raw()`, `identifier()`, `literal()` — each call is an audit point |
+| 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 |
 | Errors | subclass `DbError`; never `throw new Error` **in source**. A test simulating a *database* failure throws `dbUnavailable()`; a test simulating the *caller's body* failing throws a bare `Error` on purpose — an arbitrary throw is exactly what rollback and disposal must survive, and a `DbError` there would prove the narrower thing |
-| New code | add to `DB_ERROR_CODES` **and** `DB_ERROR_TITLES` in `errors.ts` |
+| New code | add to `DB_ERROR_CODES` **and** `DB_ERROR_TITLES` in `errors.ts` — always there, whichever file the CONSTRUCTOR lives in. `errors.ts` reached the 500-line ceiling on 2026-08-25, so a migration's constructors are `migration-errors.ts` and an invariant's are `invariant-errors.ts`; both import `DbError` from `errors.ts` and neither is imported back, and `src/index.ts` re-exports every one of them so no consumer can tell |
 | A value ambient across an `await` | `asyncContext<T>(subject)` from `@ultimat3/core` — never `new AsyncLocalStorage`. Three scopes here use it: `transaction.ts`, `attribution.ts`, `expected-loop.ts` |
 | Exports | explicit in `src/index.ts`; no `export *` |
 | Files | < 200 LOC, one responsibility, `kebab-case.ts`, test beside source |
@@ -511,7 +512,10 @@ migration ever generated and a marker on all of them marks none. **A closed list
 `drop table`, `drop column`, `truncate`, `alter column … type`; a rail enumerating every Postgres
 foot-gun is a second SQL parser competing with the server's, and every one of these four is a
 statement `generateMigration` emits, so each has a generated case holding it honest. `drop
-constraint`/`default`/`not null` and `drop index` are excluded by name: the database rebuilds them.
+constraint`/`default`/`not null` and `drop index` are excluded by name — a `drop index` holds no
+rows of its own, its `down` recreates the recorded definition, and `redefineIndex` has emitted one
+on every index rename since it existed, so classifying it marks nearly every migration and a marker
+on all is none.
 **Decide on blanked text, report the original** — `statementsOf` + `stripSqlNoise` before a keyword
 is looked for, so `-- drop table users` is prose and `values ('drop table users')` is data; but the
 excerpt in the error keeps its identifiers, because `drop table ""` names nothing an author can act
@@ -685,6 +689,36 @@ is the `add constraint` statement itself, not `x db migrate`: the migration decl
 in the ledger, so the migrator applies nothing, and the declared side carries the predicate that
 makes an executable fix possible at all.
 
+**`literal()` DOES receive caller input, and this file's own source said otherwise until
+2026-08-25.** `column-default.ts:43` renders `ColumnDefaultLike` through it — an app's own
+`.default('C:\\logs')`, crossing the tier seam from `@ultimat3/entity`, validated by nothing and
+guarded by no `identifier()`. Measured through `generateMigration` on 18.4: the emitted
+`default 'C:\logs'` stores `C:\logs` with `standard_conforming_strings` on and **`C:logs`** with it
+off. A declaration that type-checks, a migration that applies, a column defaulting to a value nobody
+wrote, and no error anywhere. A value ENDING in a backslash is worse — the escaped quote leaves the
+literal unterminated.
+
+The rule is `E'…'` **only** when the value actually carries a backslash: without one there is no
+escape mechanism for the two GUC settings to disagree about, so every migration already on disk
+stays byte for byte what it was and nothing regenerates spuriously. That property is load-bearing —
+both tracked apps hold applied migrations whose `.hash` covers this text — and
+`generate-default.live.test.ts` pins both halves against a real server, applying the same generated
+migration under `on` and under `off` and reading the stored default back. `sql.test.ts` pins the
+five shapes; the round trip through `statementsOf` is there too, because this package's own lexer
+has to read back what its escape writes or `migrate()` starts miscounting statements
+(`sql-scan.ts`'s `escapesAt` already knew the `E''` prefix).
+
+**The other two callers here are safe by CONSTRUCTION, never by input, and the difference matters
+if either is refactored.** `readonly-role.ts:71` sits in the same `sql` template as
+`identifier(role)`, which throws on a backslash before the tag function runs; `branch.ts:85` runs
+after an already-awaited `identifier(base)`. Neither is validating the value it passes to
+`literal()` — a caller moved out of that ordering loses the guard silently.
+
+`literal()` is now the tree's ONE answer, enforced: `scripts/sql-literal-copies.ts` refuses a
+`replace`/`replaceAll` whose replacement is `''` anywhere but `packages/db/src/sql.ts`, matched on
+the TRANSFORMATION rather than on a name — the three copies were called `literal`, `literalText`
+and an unnamed inline template. Pinned at zero.
+
 **A retype takes the objects written against the column out of its way first, `As of 2026-08-25`,
 and `retype-dependents.ts` decides which those are.** Postgres compiles a partial index's predicate
 and a CHECK's expression against the column's type at creation and cannot recompile either:
@@ -702,7 +736,7 @@ shape at a time on 18.4):
 | partial index whose predicate names the column | **no — 42883** |
 | partial index naming another column | yes |
 | CHECK whose expression names the column | **no — 42883** |
-| a view over the column | no, `0A000`, and no snapshot records a view |
+| a view over the column | no, `0A000`; no snapshot records a view, so `migrate()` refuses it instead (`dependent-view.ts`) |
 
 So only an expression that MENTIONS the column is moved, and a plain btree is left alone — dropping
 it is a table scan to rebuild for nothing.
@@ -729,25 +763,151 @@ pushes the restores forwards and is reversed as a whole, so it reads: drop the n
 back, then recreate the ones compiled against the old type — restoring first is `42883` in the
 other direction. What it restores is what the snapshot RECORDED, never what the entity declares.
 
-**Three things it does not move, and each is measured rather than assumed.** A **foreign key** over
-the retyped column is `ERROR: foreign key constraint "c_k_fkey" cannot be implemented` — the
-dependents are in `live.foreignKeys` *and* in every OTHER table's, which `diffTable` cannot see from
-one entity, and the statements belong to `foreign-key-plan.ts`'s own buckets, so half a fix here
-would collide with it. Neither tracked app can reach it (every key is `uuid` on both sides) and it
-is the next thing to close. A **generated column's** own retype (`regenerate`) does not move
-dependents either: it emits `set expression` and `alter … type` with no `using`, and nothing covers
-a partial index over one. And **what no migration wrote down** is invisible by construction —
-`x db gen` runs with no database open, so a hand-added expression index over the column is still
-`42883` and a VIEW over it is `0A000` whatever this does, since `SchemaDescription` has a field for
-neither.
-
-**`index-ddl.ts` holds `createIndex`, `redefineIndex`, `indexShape`, `dropIndex` and
-`asDeclared`**, split out of `generate.ts` at the 500-line ceiling along the seam `check-ddl.ts` and
-`generated-column.ts` already drew — `generate.ts` assembles a plan, `index-ddl.ts` writes the index
-statements in it. `drift-findings.ts` is the same split on the other file: every `DriftDifference`
+**A FOREIGN KEY over the retyped column is moved too, `As of 2026-08-25`, and `retype-keys.ts`
+decides which — above `diffTable`, which is the whole point.** Postgres re-checks a key's two ends
+against each other on every `alter column … type`: measured on 18.4, `42804 foreign key constraint
+"rk_posts_org_code_fkey" cannot be implemented — Key columns "org_code" … and "code" … are of
+incompatible types: integer and text`, thrown by the ALTER itself, inside `ROLE=migrate`, with the
+ledger recording nothing.
+
+**It could not be answered from inside `diffTable` and that is not an implementation detail.** The
+constraint that breaks is recorded on the table that OWNS it, so for a retype of the key's TARGET it
+is a different entity's row — `diffTable(orgs)` is handed `orgs`'s record and can never see
+`posts.foreignKeys`. So `retypedColumns(entities, current)` derives the whole schema's retype set
+once, before the entity loop, and `retypeColumn` READS it instead of asking
+`recorded.dataType === wanted` a second time: two answers to "is this column being retyped" is the
+axiom-1 split this package has spent the week closing.
+
+Four rules ride with it.
+
+| Rule | Why |
+|---|---|
+| the drop goes in a `preAlters` bucket merged at the TOP of `up` and at the FRONT of `down` | both ends of one key can move in two different entities' diffs, so the drop must precede every ALTER in the migration and the restore must follow every one of them. `down` is reversed at assembly, so the front becomes the end: drop the new key, retype both ends back, then add the recorded one. Restoring any earlier is `42804` in the other direction |
+| what comes back in `up` is written by `foreignKeyPlan`, never here | `moveKeysAside` answers a set of `keyId`s and `ConstraintPlans.predropped` reads it as "the schema does not record this key" — the same reading `checkPlan` gives its own `predropped`. That is what makes the three outcomes fall out of code that already exists: still declared (added back in the `constraints` bucket that already runs after every table statement), no longer declared (gone, exactly as the removal arm would have left it), `on delete` moved (added back carrying the new rule). Three branches restating them here is the collision this was deferred over |
+| **both** ends of `breaksOn` earn their line, and they do not overlap | the OWNER arm catches a key whose table is retyped while its TARGET's table is being dropped; the TARGET arm catches the mirror — the key's own table is doomed, so nothing retypes its column and `foreignKeyPlan` is never called for it at all, while `drop table` is emitted at the END of `up`, long after the ALTER it would have unblocked. Both are pinned live (`generate-retype-key.live.test.ts`), because when both tables survive either arm alone would do |
+| a key whose own table or whose target is doomed gets a `--` note in `down` | `add constraint` against a table no `down` can restore is a rollback that cannot run — the rule `unrestorableDrop` already states |
+
+**Re-adding the key is still the SERVER's judgement, deliberately.** An entity that retypes one end
+and not the other declares a pairing Postgres has no operator for, and the `add constraint` at the
+end of `up` is where that is said. Refusing it at generation would need to know whether two types
+share an equality operator — `varchar(80)` and `text` do, `integer` and `text` do not — which is the
+operator-resolution knowledge a generator with no database cannot have, and the same reason
+`referencesColumn` over-approximates. What it cannot see at all is a key the recorded schema does
+not hold: a hand-written migration's, or a sidecar written before `foreignKeys` was recorded.
+
+`sql-type.ts` holds `SQL_TYPES`/`sqlType`, split out of `generate.ts` so the pre-pass can ask what a
+kind renders to without importing the module that imports it. The read is **guarded** with
+`Object.hasOwn`, and db's `proto-index` pin dropped 5 → 4 in the same commit — the ratchet reports a
+count that drops as `stale`, so the two could not land apart. `kind` is data: unguarded,
+`SQL_TYPES['constructor']` answered the `Object` function and its source went into the type position
+of an `alter` statement, and `'__proto__'` answered `[object Object]`. Guarded, both pass through as
+themselves like any other unknown kind, and no other input's answer moves.
+
+**A generated column's REBUILD moves its dependents aside too, `As of 2026-08-25`, and it reuses
+`retypeDependents` rather than answering again.** Plain → generated has no `set expression`, so
+`regenerate` drops the column and adds it back — and `drop column` silently takes every partial
+index whose PREDICATE names it and every CHECK whose expression does (measured, 18.4). The `rebuilt`
+set `diffTable` carries into its index loop is keyed on an index's COLUMNS, so neither is a name it
+can find: the table came back without them, the snapshot still recording both, and `down` unable to
+restore either. `regenerate` therefore takes `live` and `moved` and calls `moveDependentsAside`,
+which drops each explicitly, restores it in `down`, and puts the name where the ordinary diff will
+CREATE it. `generate-generated-rebuild.live.test.ts` applies it both ways.
+
+**A generated column's own `alter … type` deliberately does NOT move them, and the reason is
+measured.** It trips the same `42883` (`operator does not exist: text > integer`, on a generated
+`integer` column under `where (doubled > 0)`) — but moving the index aside only relocates the
+failure to the `create index` that puts it back, because a predicate whose operator the NEW type has
+no resolution for cannot be written either. The plain path's dependents survive precisely because an
+untyped literal re-resolves (`status = 'published'` under an enum and under `text`), and a generated
+column reaching that shape needs its EXPRESSION changed in the same migration, which `regenerate`
+emits AFTER the type statement. Left open with the failure named in the source rather than closed
+with a change no test could fail on.
+
+And **what no migration wrote down** is still invisible to the generator by construction — `x db gen`
+runs with no database open, so a hand-added expression index over the column is `42883` whatever
+this does, since `SchemaDescription` has a field for it nowhere.
+
+**A VIEW is NOT discoverable from anything this generator reads, and the honest ceiling is a
+refusal one statement earlier, `As of 2026-08-25`.** `SchemaDescription` has no field for a view,
+`introspect()` reads none by construction (`app-relation.ts` excludes every non-table relation), and
+no `entity()` can declare one — so a `GenerateOptions.views` with no caller to fill it would be the
+declared-and-never-wired defect this release exists to eliminate, and the caller is
+`@ultimat3/cli`'s. What DOES have a connection is `migrate()`. `dependent-view.ts` is the preflight:
+`refuseDependentViews(tx, script)` runs inside each migration's own transaction, before its first
+statement, and both `migrate()` and `rollback()` call it.
+
+It repairs nothing and does not claim to — the deploy still stops. What it replaces is
+`X_DB_UNAVAILABLE: cannot reach the database`, whose registered `fix:` is "set `DATABASE_URL` to a
+reachable Postgres url", on a database the migrator is connected to and mid-transaction on. The
+server's own words name the view in a **DETAIL** field nothing printed:
+`0A000 cannot alter type of a column used by a view or rule` /
+`rule _RETURN on view dv_docs_published depends on column "rank"`. `X_MIGRATION_VIEW_DEPENDS` names
+the view, the table and the column, and its `fix:` is the `drop view` plus the `create view` built
+from `pg_get_viewdef(oid, true)` — a paste, not an archaeology.
+
+Four rules.
+
+| Rule | Why |
+|---|---|
+| `retypeTargets` is a WORD scan over `sql-scan.ts`, never a regex | a retype inside a `--` comment is prose and one inside a literal is data, and both reach the scan when they sit inside an `alter table` statement — read as code either invents a target on a column the statement never touches. A **quoted** name is never a keyword: `alter table "t" alter "column" type text` retypes a column called `column`, and read as the keyword it names `type` and matches nothing |
+| the matcher is **narrow on purpose** | a miss costs exactly what happens today — the server's own `0A000`, one statement later — while a false positive refuses a migration that would have applied. Every retype `generateMigration` emits is `alter table <t> … alter [column] <c> type`; a hand-written `ALTER TABLE ONLY t …` is not, and is left to the server |
+| one catalog round trip, and the PAIR is filtered in JS | the query asks every retyped table against every retyped column, so it answers pairs nobody retypes — `dv_notes.rank` out of `dv_docs.rank` and `dv_notes.mark`. Refusing on one is a deploy stopped over a view standing in nobody's way, which is worse than the message this exists to improve. Pinned live |
+| the `fix:` is built through `identifier()` **inside a `try`** | `identifier()` refuses a name holding a quote, a space or a backslash, all three legal inside a quoted Postgres name, and a `fix:` may not throw — the rule `rebuildForeignKey` already states, with the same shape. `errors.ts` takes the finished string rather than importing `sql.ts`: that module imports `identifierUnsafe` from it, and an import cycle around the module whose evaluation REGISTERS every code is not one worth having for a quoted name |
+
+A script that retypes nothing costs one text scan and no round trip, which is nearly every migration
+an app writes.
+
+**`index-ddl.ts` holds `createIndex`, `redefineIndex`, `indexShape`, `dropIndex`,
+`dropRecordedIndex`, `mayBeConstraintBacked` and `asDeclared`**, split out of `generate.ts` at the
+500-line ceiling along the seam `check-ddl.ts` and `generated-column.ts` already drew —
+`generate.ts` assembles a plan, `index-plan.ts` decides which index statements go in it, and
+`index-ddl.ts` writes them. `drift-findings.ts` is the same split on the other file: every `DriftDifference`
 constructor and the `DriftKind` union, with `drift.ts` keeping the comparisons and re-exporting both
 types explicitly so the public surface does not move.
 
+**`index-plan.ts` walks both directions, `As of 2026-08-25`** — the third arm to learn it, after
+`checkPlan` and `foreignKeyPlan`. `diffTable`'s index loop walked `declaredIndexes(entity)` and
+matched by name with **no reverse pass**, so an index the entities stopped declaring stayed on the
+database forever while the sidecar beside it stopped recording it: measured on `examples/dummy`,
+`member_unique_per_org`, `members_tz_idx` and `post_slug_unique_per_org` all survived a regeneration
+that recorded none of them, and the `drift` gate step was green over all three because drift judges
+the declared side. `indexPlan(entity, live, plan, context)` is the whole question now — declared
+first and removed last, the order `checkPlan` uses — and `generate.ts` calls it.
+
+**A recorded UNIQUE index cannot be told from a UNIQUE CONSTRAINT's, and it never will be.**
+`TableDescription` carries no discriminator and cannot usefully be given one: the *same*
+declaration reaches the server as either, depending on which migration created it. A `unique` column
+on a table `createTable` writes goes out as `create table … slug text unique`, which Postgres backs
+with a **constraint** named `posts_slug_key`; the same column gaining `unique` later takes
+`diffTable`'s `create unique index "posts_slug_key"` and is a plain index. `snapshotOf` records both
+as `{ unique: true, primary: false }`, and every sidecar already on disk was written that way, so a
+new field could not classify one retroactively. Measured on 18.4
+(`index-removal.live.test.ts`):
+
+| statement | on a constraint's index | on a plain index |
+|---|---|---|
+| `drop index "n"` | **2BP01** | ok |
+| `drop index if exists "n"` | **2BP01** — `if exists` does not suppress it | ok |
+| `alter table … drop constraint if exists "n"` | drops it, index and all | notice, no-op |
+
+So `dropRecordedIndex` emits the **pair**, constraint first — reversed, the `drop index` reaches a
+constraint's index and is the 2BP01 this exists to avoid — and only for the shape a constraint could
+be backing: `mayBeConstraintBacked` is unique, non-primary, total, unordered and btree, because
+`add constraint … unique` and a `unique` column clause can produce nothing else. A partial or
+ordered or GIN index takes the bare `drop index`. The asymmetry that remains is named rather than
+hidden: `down` recreates it with `create unique index`, so a constraint comes back as an index. That
+is the one statement this generator has, and it restores what the record described.
+
+Four names are skipped by the removal arm, and each is a statement Postgres would refuse or repeat:
+a `primary` index (2BP01, and the key is `TableDescription.primaryKey`), one already in
+`MovedAside.indexes` (a retype dropped it ahead of the ALTER — 42704), one over a column
+`regenerate` rebuilt (it went with the `drop column` — 42704), and one over a column this migration
+DROPS (`alter table … drop column` takes it, the rule `foreignKeyPlan` already applies to a
+constraint on a dropped column). A doomed **table** needs no arm at all: `generate.ts` only reaches
+a diff for a table an entity still declares. The known limit is written in the file header — a
+unique index a foreign key on ANOTHER table still references cannot be dropped (2BP01), and this arm
+sees one table at a time.
+
 **An entity's INVARIANTS reach the DDL, `As of 2026-08-25`, and `invariant-ddl.ts` is what they
 become.** `EntityDescriptionLike` had no `invariants` field at all — the same seam gap
 `onDelete` carried until 3.0 — so a regenerated migration held **none** of them: measured on
@@ -961,8 +1121,10 @@ module's vocabulary; `snapshotOf` imports `foreignKeysOf` back, one direction on
 **`foreignKeyPlan` walks both directions, `As of 2026-08-19`.** A *removed* `references()` used to
 emit nothing while the snapshot beside it recorded `foreignKeys: []` — so the orphan constraint
 stayed on the database **and** the record denied one the catalog holds, which `compareForeignKeys`
-can never see because it judges the declared side. That is not parity with a removed index: a
-removed index leaves the snapshot correct by omission, and this snapshot lied. The drop names the
+can never see because it judges the declared side. **This paragraph said "that is not parity with a
+removed index: a removed index leaves the snapshot correct by omission", and that was wrong** — see
+`index-plan.ts` below: a removed index's snapshot lied in exactly the same way, and the arm to fix
+it did not land until 2026-08-25. The drop names the
 constraint **the previous snapshot recorded**, never the one this generator would have chosen — a
 hand-written `fk_legacy` is `42704` under the generated spelling — and a key whose columns this
 migration is dropping is skipped, because `drop column` takes the constraint with it. A key whose
@@ -1115,12 +1277,77 @@ 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 statement funnel 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
+  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.
+
+- **`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.
+
 ```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 |
@@ -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": "15.0.0",
+  "version": "17.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "15.0.0"
+    "@ultimat3/core": "17.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

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;
+}