@ultimat3/db 1.2.0 → 3.0.0

package/README.md

@@ -27,16 +27,30 @@ await withTransaction(async (tx) => {
 |---|---|
 | `sql` / `raw` / `identifier` / `literal` / `join` | fragment builders |
 | `db()` / `baseClient()` / `setDbClient()` | the ambient client; `db()` returns the open tx if any |
-| `withTransaction()` / `currentTx()` | transaction scope; `currentTx()` is the outbox seam |
+| `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 |
+| `sqlState()` / `sqlStateCode()` / `isRetryableState()` / `SQLSTATE` | `As of 2026-08`: the SQLSTATE a driver error carries, and the closed table from it to a code. `Bun.SQL` puts it on `errno`; PGlite puts it on `code`; **one** reader answers for both |
 | `migrate()` / `rollback()` / `readLedger()` | the `x_migrations` ledger |
-| `checkDrift()` / `diffSchema()` / `assertNoDrift()` | drift, with a `--json` report |
-| `generateMigration()` | `x db gen "<name>"` — reversible up/down SQL |
+| `statementsOf()` | `As of 2026-08`: a SQL script → the statements a driver sends one at a time. One send is one statement, so `migrate()` splits with this — a `;` inside a literal, an identifier, a dollar-quoted body or a comment is data |
+| `checkDrift()` / `diffSchema()` / `assertNoDrift()` | drift, with a `--json` report. `checkDrift()` is the **post-migrate verification** — the live database against the ledger: columns, declared indexes, and declared foreign keys, matched on where the key points and not on its constraint name |
+| `declaredSchema()` / `expectedSchema()` | `As of 2026-08`: the schema the migrations write down, or `undefined` when the newest one carries no snapshot — never an older snapshot standing in for it |
+| `parseSnapshot()` | `As of 2026-08`: a `<id>.snapshot.json` sidecar validated to the last nested field, or `undefined`. `{"tables":[null]}` is valid JSON and is not a schema |
+| `snapshotJson()` | `As of 2026-08`: the sidecar's **bytes** — the JSON Biome would have printed, trailing newline included. The one writer of a `<id>.snapshot.json`, because `JSON.stringify(…, null, 2)` is not formatter-clean and an app's `lint` step rejected the file `x db gen` had just written |
+| `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 |
+| `destructiveStatements()` / `hasDestructiveMarker()` / `isDestructive()` / `DESTRUCTIVE_MARKER` | `As of 2026-08`: the destructive-SQL rail — does this `up` drop, truncate or retype, and does the file declare it with `-- destructive: true`? One classifier, read by `x db gen` when it writes the marker and by `x verify` when it demands one |
+| `stripSqlNoise()` | comments, literals, dollar-quoted bodies and quoted identifiers blanked **in source order**, so a reader sees the operation and not the prose. Shared by `readOnlyQuery()` and the destructive rail |
 | `introspect()` | live schema → `SchemaDescription` |
 | `createBranch()` / `dropBranch()` / `reapBranches()` | copy-on-write branch databases |
 | `createPgliteClient()` / `branchPglite()` | the embedded database — Postgres in this process |
-| `readOnly()` | mutation-rejecting wrapper |
 | `ensureReadOnlyRole()` / `grantReadOnlySql()` / `READONLY_ROLE` | a `NOLOGIN`, SELECT-only Postgres role — layer 1 of `db.query`'s defence |
 | `readOnlyQuery()` / `READONLY_TIMEOUT_MS` | one statement inside `BEGIN READ ONLY` with a statement timeout — layer 2 |
+| `setStatementObserver()` / `statementObserver()` | `As of 2026-08`: one event **and one `db.<verb>` span** per settled statement, both drivers; uninstalled is one branch |
+| `expectedQueryLoop()` / `expectedQueryLoopReason()` | `As of 2026-08`: the one way to declare a loop of queries deliberate — the reason rides on every statement it issues as `StatementEvent.expected` |
+| `withStatementAttribution()` / `statementAttribution()` | `As of 2026-08`: the `{ entity, op }` pair on `StatementEvent.attribution`, scoped exactly like `expectedQueryLoop()` — `@ultimat3/entity`'s `postgresRepo` is the one producer |
+| `STATEMENT_ATTRIBUTE` | `As of 2026-08`: `db.statement`, the OTel attribute each span carries its text under — declared here, read by `x dev`'s timeline |
+| `statementFingerprint()` / `statementKind()` / `statementVerb()` | `As of 2026-08`: what shape a statement is — `entity.op` when attributed else its own collapsed text, read or write from the leading verb. One rule, so two detectors group identically |
 | `createRecordingClient()` | in-memory `DbClient` that records SQL, for tests |
 
 ## `sql` is parameters-only
@@ -86,7 +100,28 @@ layer 1 covers only what existed at grant time.
 
 ## The drift contract
 
-`x db drift` compares `introspect()` against the snapshot the newest applied migration carries.
+`checkDrift()` compares `introspect()` against the snapshot the newest applied migration carries —
+`expectedSchema(migrations, ledger)`. `declaredSchema(migrations)` is the same read with the ledger
+left out: the schema the files *declare*, applied or not, which is what `x db gen` diffs the app's
+entities against so generation needs no database at all. One implementation, two callers — a
+snapshot that meant one thing to the generator and another to drift is exactly the divergence the
+ledger exists to prevent.
+
+**One `X_DB_DRIFT`, two detectors, and which is which matters.** `checkDrift()` is the post-migrate
+verification: it needs a database, so it runs where one is open — `runMigrations` in
+`@ultimat3/cli`, which is `x db migrate`, `x db reset` and `ROLE=migrate` alike. It is the only one
+that can see a column added by hand. The other, `checkSourceDrift()` (also `@ultimat3/cli`), hashes
+the entity source against what `x db gen` recorded, opens nothing, and is `x verify`'s `drift` step
+— the gate runs in CI with no database, so a check that needed one could not run at all.
+
+A migration the ledger has not recorded is **not** drift: `expectedSchema` reads the ledger's own
+subset, so a database that simply has not migrated yet is pending, not divergent. Neither is a
+table in the `x_` namespace — `x_migrations`, the queue's tables, the outbox and every
+`@ultimat3/auth` table are created by `create table if not exists` at boot and appear in no
+snapshot, so `appTables()` drops them before the diff. `introspect()` keeps its own narrower
+exclusion (the ledger alone), because the admin schema view and the MCP `schema.describe` tool
+legitimately show `x_users`.
+
 Rendered output is pinned byte-for-byte:
 
 ```
@@ -102,7 +137,12 @@ X_DB_DRIFT: schema differs from migrations
 | live table, no migration | `table "T" is not present in any migration` | `x db gen "add T"` |
 | migrated table, not live | `table "T" is declared by migrations but does not exist` | `x db migrate` |
 
-`checkDrift()` returns every difference; `assertNoDrift()` throws the first. `x verify` fails on it.
+`checkDrift()` returns every difference; `assertNoDrift()` throws the first. `x db migrate` renders
+them all as findings and exits non-zero; a `ROLE=migrate` container throws the first one
+(`assertNoDrift`, in `runRole`) and exits non-zero too, because the release phase has one channel —
+the exit code — and a deploy that rolled on past a schema nobody can reconstruct is the failure
+drift exists to catch. There is no `x db drift`, and `x verify`'s `drift` step is the *source*
+detector (`checkSourceDrift`), which needs no database and never calls this.
 
 ## The embedded database
 
@@ -146,21 +186,53 @@ scope is already holding, because waiting would be a deadlock with no error to e
 
 `ROLE` picks the profile — a `worker` draining a queue must not size like a `web` process.
 
-| Role | max | statement timeout | idle timeout |
-|---|---|---|---|
-| `web` | 20 | 10s | 30s |
-| `sync` | 10 | 10s | 60s |
-| `worker` | 8 | 120s | 30s |
-| `scheduler` | 2 | 15s | 60s |
-| `migrate` | 1 | none | 10s |
-| `replicator` | 4 | none | 60s |
-
-The timeout is pinned per connection via libpq `options=-c statement_timeout=`. `Bun.SQL` is
-reached lazily, so importing this package never opens a socket.
+| Role | max | statement timeout | idle timeout | lock timeout | acquire timeout |
+|---|---|---|---|---|---|
+| `web` | 20 | 10s | 30s | none | 5s |
+| `sync` | 10 | 10s | 60s | none | 5s |
+| `worker` | 8 | 120s | 30s | none | 10s |
+| `scheduler` | 2 | 15s | 60s | none | 10s |
+| `migrate` | 1 | none | 10s | 3s | none |
+| `replicator` | 4 | none | 60s | none | none |
+
+The statement timeout is pinned per connection via libpq `options=-c statement_timeout=`, and it
+does reach the backend: `client.live.test.ts` asserts `current_setting('statement_timeout')`, which
+is the only reading a DSN test cannot fake. `Bun.SQL` is reached lazily, so importing this package
+never opens a socket.
+
+**That setting is MERGED into the operator's own `options`, never assigned over them** (`As of
+2026-08`). `?options=-c search_path=app` in `DATABASE_URL` survives on every role, and the role's
+`statement_timeout` is appended to it; if the URL sets `statement_timeout` itself, the **role
+wins** — it is a bound the pool is sized around — and every other flag is kept. It is emitted for
+all six roles, `migrate`'s and `replicator`'s `0` included: `0` is "this role may take as long as
+it takes", and left unsaid a server-side `alter database … set statement_timeout` would kill the
+one role that has to outlive it. Before this, `set` replaced the whole value and only on the roles
+with a non-zero timeout, so a `search_path` survived on `migrate` and vanished on `web` — the role
+that runs the migrations and the role that serves the traffic reading different schemas.
+
+**`DATABASE_POOL_MAX` overrides `max`** (`As of 2026-08`), and it is the only pool knob an operator
+can turn without shipping an image — 400 `web` pods × the frozen `max: 20` is 8,000 backends. A
+value that is not a positive integer refuses at boot rather than falling back.
+
+**`acquireTimeoutMs` bounds `reserve()`**, because queueing turns exhaustion into a hang: `/readyz`'s
+`select 1` joins the same queue, the kubelet kills the pod, and the replacement inherits the same
+saturated database. 0 waits, which is what a run-once role wants.
+
+**`lockTimeoutMs` bounds a *wait*, never the work.** `alter table … add column` takes `ACCESS
+EXCLUSIVE`; a long `SELECT` holding `ACCESS SHARE` makes it queue, and Postgres' lock queue is FIFO,
+so every later query on that table queues behind the ALTER. `migrate` runs `statement_timeout = 0`,
+so nothing else would ever end that wait. `migrate()` emits it as `SET LOCAL lock_timeout` inside
+each migration's own transaction — it reverts at COMMIT, so a DDL value never leaks onto the session
+the ledger insert runs on.
 
 ## Migrations
 
-`migrate()` takes an advisory lock (`pg_advisory_lock(4919202607)`), ensures `x_migrations`
+`migrate()` takes the advisory lock by **polling** `pg_try_advisory_lock(4919202607)` every 500ms
+until `lockWaitMs` (default 60s) and then throwing `X_MIGRATE_CONCURRENT` (`As of 2026-08`).
+`pg_advisory_lock` has no timeout, and a predecessor OOM-killed on a partition keeps its backend —
+and the lock — for hours, so a deploy hook sat inside one statement printing nothing while
+`helm upgrade --wait` blocked and `backoffLimit` never fired, because a job that never finishes
+never fails. It then ensures `x_migrations`
 (`id, name, checksum, applied_at, app_version, duration_ms`), audits, then applies each pending
 migration inside its own transaction. It refuses **before applying anything** when:
 
@@ -170,22 +242,88 @@ migration inside its own transaction. It refuses **before applying anything** wh
 
 Report (`--json`): `{ applied: [{ id, name, durationMs }], skipped: [id], durationMs, appVersion }`.
 
+## A loop of queries that is deliberate says so
+
+`As of 2026-08`:
+
+```ts
+return expectedQueryLoop('one indexed lookup per text field beats one unindexed OR', async () => {
+  for (const field of fields) hits.push(...(await repo.list({ where: [match(field)] })));
+  return hits;
+});
+```
+
+One mechanism, and only one: no comment pragma, no config list of exempt call sites (axiom 1).
+`reason` is required and non-blank — an exemption with no argument is a pragma, and the next
+reader cannot tell a considered loop from a silenced one.
+
+| | |
+|---|---|
+| Scope | an `AsyncLocalStorage`: it survives every `await` at any depth, and two loops running at once never read each other. Nesting keeps the innermost reason |
+| What it carries | `StatementEvent.expected`, stamped by both funnels at settle time — a diagnostic judging a whole request runs after every scope in it closed |
+| What it suppresses | a **verdict**, never a statement. The SQL is still sent, still observed, still a span: only the thing that warns is told the author already answered |
+| What it costs | nothing without a diagnostic — the reason is read inside the branch that already checks for an installed observer |
+
+The framework's own deliberate loops declare themselves at source: `migrate()` and `rollback()`
+(one transaction per migration, so a failure leaves an exact ledger) and `@ultimat3/admin`'s
+cross-entity search (one indexed lookup per text field).
+
+## A statement knows who compiled it
+
+`As of 2026-08`: `StatementEvent.attribution` is no longer always `undefined`.
+
+```ts
+return withStatementAttribution('members', 'findById', () =>
+  client.query(sql`select * from members where id = any(${ids})`),
+);
+```
+
+| | |
+|---|---|
+| Scope | an `AsyncLocalStorage`, `expectedQueryLoop()`'s own shape: it survives every `await` at any depth, and nesting keeps the innermost pair |
+| What it carries | `StatementEvent.attribution`, stamped by both funnels at settle time, next to `expected` |
+| Producer | `@ultimat3/entity`'s `postgresRepo` — the last caller that still knows the entity and the operation once the SQL exists |
+| What it costs | nothing uninstalled — `statementObserver()` is read first, and with nothing installed `fn` runs directly; no scope entered, no object allocated |
+
+Hand-written SQL, a migration, a health probe, `x db` commands and `@ultimat3/jobs`' own queue
+statements still carry no `attribution` — nothing above them knows an entity to name, so the field
+is optional and a detector must fall back to the statement text either way.
+
 ## Error codes
 
+Every driver failure is typed by the **SQLSTATE the server sent**, `As of 2026-08`. The state was
+always on the error and nothing read it, so a `23505` from two clicks racing a signup answered
+"cannot reach the database" and paged on-call for an outage that never happened. The table
+(`sqlstate.ts`) is closed; everything outside it is still `X_DB_UNAVAILABLE`, unchanged.
+
 | Code | Meaning |
 |---|---|
-| `X_DB_UNAVAILABLE` | no reachable database; `fix:` names `DATABASE_URL` |
+| `X_DB_UNAVAILABLE` | no reachable database, or a SQLSTATE the table does not name; `fix:` names `DATABASE_URL` |
+| `X_DB_UNIQUE_VIOLATION` | `23505` — `fix:` names `upsertAll(rows, { onConflict: [...] })` and the constraint the server named |
+| `X_DB_FOREIGN_KEY_VIOLATION` | `23503` |
+| `X_DB_SERIALIZATION_FAILURE` | `40001` / `40P01`, and an exhausted `withTransaction(fn, { retry: n })` budget |
+| `X_DB_STATEMENT_TIMEOUT` | `57014` — the statement ran past `statement_timeout` |
+| `X_DB_LOCK_TIMEOUT` | `55P03` — it waited past `lock_timeout` for a lock it never got |
+| `X_DB_POOL_EXHAUSTED` | `53300` / `53200`, or `reserve()` past `acquireTimeoutMs` |
 | `X_DB_DRIFT` | live schema differs from migrations |
 | `X_MIGRATION_CONFLICT` | ledger app-version fence or checksum mismatch |
+| `X_MIGRATE_CONCURRENT` | another migrator still held the lock when the wait ran out |
 | `X_MIGRATION_IRREVERSIBLE` | generated `down` would lose data |
 | `X_SQL_UNSAFE` | non-bindable interpolation, or an unsafe identifier/branch name |
 | `X_BRANCH_EXISTS` | branch database already exists (or is the connected one) |
-| `X_READONLY_VIOLATION` | a mutating statement reached a `readOnly()` client |
 | `X_NOT_IMPLEMENTED` | branching an in-memory PGlite — a copy needs a directory |
+| `X_ENV_MISSING` | core's — `DATABASE_POOL_MAX` is set to something that is not a positive integer |
 
 ```bash
 x db migrate --json
-x db drift --json
 x db gen "add publish_at"
+x db branch ls --json
 x db branch create feature_x
+x db branch drop feature_x
 ```
+
+**Drift has no subcommand of its own.** The database half runs *inside* `x db migrate`, which calls
+`checkDrift()` on the connection it already holds and exits non-zero on a difference; the source
+half is the `drift` step of `x verify`, which hashes entity source against what `x db gen` recorded
+and opens no database. Two questions, two owners, and no `drift` subcommand under `x db` — the
+`DB_SUBCOMMANDS` set is `gen`, `migrate`, `reset`, `studio`, `branch`, `backfill`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "1.2.0",
+  "version": "3.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "1.2.0"
+    "@ultimat3/core": "3.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/attribution.ts

@@ -0,0 +1,45 @@
+// Single responsibility: carry "which entity, which operation" from the layer that compiled a
+// statement down to the funnel that sends it, so a diagnostic reads `50× findById on members`
+// instead of fifty copies of one `select`. A scope, not a parameter: the statement leaves several
+// frames and at least one microtask below the repository call that caused it.
+
+// `node:` for the same reason `expected-loop.ts` needs it — Bun exposes no native async-context
+// primitive, and the pair has to survive every `await` between the repository call and the
+// statement it causes. A module-scope variable would be shared by two concurrent requests.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { type StatementAttribution, statementObserver } from './observe';
+
+const storage = new AsyncLocalStorage<StatementAttribution>();
+
+/**
+ * Run `fn` with every statement it issues — at any depth, across every `await` — attributed to
+ * `entity` and `op`. `@ultimat3/entity`'s `postgresRepo` is the one producer: it is the last caller
+ * that still knows both once the SQL exists, and it wraps each repository method rather than each
+ * `client()` call because the statement is sent below it — inside the coalescer's microtask flush,
+ * inside a chunked write loop, inside `readByIds` for a preload.
+ *
+ * Nesting keeps the innermost pair, exactly as `expectedQueryLoop` keeps the innermost reason: a
+ * relation preloaded during `findMany` reads through the *related* repository, and that read is
+ * what its own statement is.
+ *
+ * **With no observer installed this enters no scope at all** — one property read, one branch, no
+ * object allocated (axiom 6). Which is also why the pair arrives as two strings rather than as a
+ * `StatementAttribution`: a literal at the call site would be allocated before the branch could
+ * decline it, on the path every statement in the process takes. An observer installed *during*
+ * `fn` therefore sees the statements that follow unattributed; installation happens once, at boot,
+ * and paying for the scope on every production statement to close that window is the wrong trade.
+ */
+export function withStatementAttribution<T>(entity: string, op: string, fn: () => T): T {
+  if (statementObserver() === undefined) return fn();
+  return storage.run({ entity, op }, fn);
+}
+
+/**
+ * The innermost enclosing pair, or `undefined` outside every scope — hand-written SQL, a migration,
+ * a health probe, the job queue's own statements. Read by the two funnels when an observer is
+ * installed, and by nothing else: a diagnostic reads `StatementEvent.attribution`, which is this
+ * same answer captured at the moment the statement settled.
+ */
+export function statementAttribution(): StatementAttribution | undefined {
+  return storage.getStore();
+}

package/src/branch.ts

@@ -3,6 +3,7 @@
 // it is unsure about, a data backfill, a DROP — never happens against the shared database.
 // Branches are cheap and forgettable, so `reapBranches()` is part of the design, not an add-on.
 
+import { systemClock } from '@ultimat3/core';
 import { baseClient, type DbClient } from './client';
 import { branchExists, branchNameInvalid, DbError } from './errors';
 import { identifier, literal, sql } from './sql';
@@ -51,7 +52,7 @@ export async function createBranch(
 
   const base = options.base ?? (await currentDatabase(client));
   await client.execute(sql`create database ${identifier(branch)} template ${identifier(base)}`);
-  const createdAt = (options.now ?? new Date()).toISOString();
+  const createdAt = (options.now ?? systemClock.now()).toISOString();
   await client.execute(
     sql`comment on database ${identifier(branch)} is ${literal(`${BRANCH_MARKER}${createdAt}`)}`,
   );
@@ -113,8 +114,13 @@ export async function dropBranch(
       select pg_terminate_backend(pid) from pg_stat_activity where datname = ${branch}
     `);
   }
-  const affected = await client.execute(sql`drop database if exists ${identifier(branch)}`);
-  return affected >= 0;
+  // Asked BEFORE the statement, because `drop database if exists` answers with the same command
+  // tag either way and `execute` counts no rows for it: `affected >= 0` was `true` by
+  // construction, so the boolean could not tell a branch that was dropped from a name that was
+  // never a database — which is the one question a reaper or a preview teardown asks it.
+  const existed = await exists(client, branch);
+  await client.execute(sql`drop database if exists ${identifier(branch)}`);
+  return existed;
 }
 
 export interface ReapOptions extends DropBranchOptions {
@@ -123,12 +129,22 @@ export interface ReapOptions extends DropBranchOptions {
 
 /** Preview environments leak branches; this is what the nightly `reapBranches` task calls. */
 export async function reapBranches(options: ReapOptions): Promise<readonly string[]> {
-  const cutoff = (options.now ?? new Date()).getTime() - options.maxAgeMs;
+  const cutoff = (options.now ?? systemClock.now()).getTime() - options.maxAgeMs;
   const branches = await listBranches(options);
   const dropped: string[] = [];
   for (const branch of branches) {
     if (branch.createdAt === null) continue;
-    if (new Date(branch.createdAt).getTime() > cutoff) continue;
+    const createdAtMs = Date.parse(branch.createdAt);
+    // `NaN > cutoff` is `false`, which is the same answer "older than the cutoff" gives — so a
+    // truncated or hand-edited comment used to be a database DROPPED on the next sweep, whatever
+    // `maxAgeMs` said. An age nothing can read is not an old age.
+    if (!Number.isFinite(createdAtMs)) continue;
+    // Finite is not enough: `'2026-08-18T10:00'` parses as LOCAL time, so a truncated comment
+    // names an instant hours from the one it reads as, and the sweep acts on a date nobody wrote.
+    // `createBranch` writes `toISOString()` and nothing else does, so a value that does not round
+    // trip through it is not ours — there is no legitimate non-canonical comment to strand.
+    if (new Date(createdAtMs).toISOString() !== branch.createdAt) continue;
+    if (createdAtMs > cutoff) continue;
     await dropBranch(branch.name, options);
     dropped.push(branch.name);
   }