@ultimat3/db 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -11,6 +11,7 @@ reaches down to this package for it. **Never** import `entity`, `jobs`, `http` o
 | 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 |
 | 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` |
 | Exports | explicit in `src/index.ts`; no `export *` |
@@ -318,6 +319,29 @@ block is the join of that fix with the engine it ships through — an entity des
 `generateMigration`, applied by `migrate()` itself against a real server, columns confirmed against
 `pg_indexes`, rather than either half alone.
 
+**The ledger audit asks one question — does this build ship every migration the ledger records?**
+`auditLedger`'s `foreign` filter is `!known.has(row.id)` and nothing else, `As of 2026-08`. It used
+to also require `row.app_version !== appVersion`, which switched the audit OFF wherever the two
+agree: `runningAppVersion()` answers `dev` for every development build, so a migration applied by an
+earlier `dev` build and since deleted was invisible, and `expectedSchema` (`drift.ts`) then dropped
+its table from the comparison — `x db drift` answering `ok: true` against a database that still has
+the table. The version is a detail of the ANSWER and lives in the cause, never in the predicate.
+
+**`rollback({ steps })` refuses anything that is not a positive safe integer, before the lock.**
+`steps` reaches `slice(0, steps)`, where a negative count counts from the END: `steps: -1` selected
+every applied migration but the newest and reversed four of five. `X_INVARIANT` (core's generic
+code, borrowed in `DB_BORROWED_ERROR_CODES` the way `@ultimat3/money`'s `roundRatio` borrows it —
+a bad argument is not a fact about the ledger), thrown by `rollbackStepsInvalid` before the advisory
+lock is taken and before the ledger is read. Same discipline as `poolMaxInvalid`: a number this
+build cannot honour is refused, never reinterpreted.
+
+**`reapBranches` skips a `createdAt` it cannot parse; it never reads one as infinitely old.**
+`NaN > cutoff` is `false`, which is the same answer "older than the cutoff" gives — so a
+`COMMENT ON DATABASE` that was truncated or hand-edited used to be a database DROPPED on the next
+nightly sweep whatever `maxAgeMs` said. `Date.parse` + `Number.isFinite`, the discipline
+`@ultimat3/seo`'s `feed-dates.ts` applies to the same question. (Distinct from the open
+source-blindness of the reaper, issue #133.)
+
 **One send is one statement, so `migrate()` and `rollback()` split the script.** `tx.execute(raw(
 migration.up))` on a text holding two commands is where the two drivers disagreed, and the
 disagreement is the whole reason this is a bug rather than a preference: `pglite.ts` calls
@@ -562,6 +586,20 @@ itself all reach the caller, and every caller must handle that. Layers 3–4 (pr
 policy) live in `@ultimat3/mcp`, which must still never import this package — the CLI wires the
 two together.
 
+**`libpq-options.ts` merges the framework's `options` into the operator's, and `connectionUrl` may
+not `set` that key again.** `DATABASE_URL` is the operator's file: `url.searchParams.set('options',
+…)` REPLACED whatever they had written, and only on the roles whose `statementTimeoutMs` is
+non-zero — so `?options=-c search_path=app` survived on `migrate` and `replicator` and was dropped
+on `web`, `sync`, `worker` and `scheduler`, i.e. the role that runs the migrations and the role that
+serves the traffic looked at different schemas with nothing reporting it. Precedence is **the
+framework wins on the names it sets, the operator keeps every other flag**, and it is enforced by
+removing those names from the operator's tokens before appending, never by position: "the last `-c`
+wins" is backend argument-order behaviour nobody here measured. The bound is emitted for all six
+roles including the two whose value is `0` — `0` is `migrate` saying it may take as long as it
+takes, and left unsaid an `alter database … set statement_timeout` on the server kills the one role
+that must outlive it. The splitter honours libpq's backslash escape, so a `search_path=two\ words`
+survives the round trip whole.
+
 ```bash
 bun test                      # from packages/db
 bun run typecheck

package/README.md

@@ -137,10 +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 db migrate` reports
-them and exits non-zero; a `ROLE=migrate` container logs them and still exits 0, because its
-contract is "apply every migration, then exit" and a schema difference after a clean apply is a
-diagnostic, not a failed migration.
+`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
 
@@ -198,6 +200,16 @@ does reach the backend: `client.live.test.ts` asserts `current_setting('statemen
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "2.0.0"
+    "@ultimat3/core": "3.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/branch.ts

@@ -134,7 +134,17 @@ export async function reapBranches(options: ReapOptions): Promise<readonly strin
   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);
   }

package/src/client.ts

@@ -3,10 +3,11 @@
 // pool like a `web` process behind a CDN. `Bun.SQL` is reached lazily so importing this module
 // never opens a socket (the CLI imports it to print help).
 
-import { type Role, resolveRole } from '@ultimat3/core';
+import { type Role, renderThrowable, resolveRole } from '@ultimat3/core';
 import { statementAttribution } from './attribution';
 import { DbError, dbUnavailable, driverError, poolAcquireTimeout, poolMaxInvalid } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
+import { mergeLibpqOptions } from './libpq-options';
 import { statementObserver } from './observe';
 import { type SqlFragment, sql } from './sql';
 import { withStatementSpan } from './statement-span';
@@ -172,10 +173,19 @@ function connectionUrl(options: PostgresClientOptions, profile: PoolProfile): st
   } catch (error) {
     throw dbUnavailable(`DATABASE_URL is not a valid url: ${raw}`, error);
   }
-  // libpq `options` is the portable way to pin a statement timeout for every pooled connection.
-  if (profile.statementTimeoutMs > 0) {
-    url.searchParams.set('options', `-c statement_timeout=${profile.statementTimeoutMs}`);
-  }
+  // libpq `options` is the portable way to pin a statement timeout for every pooled connection —
+  // MERGED into the operator's own, never assigned over it, and emitted for every role including
+  // the two whose bound is 0. `set` here dropped a `?options=-c search_path=app` on `web`, `sync`,
+  // `worker` and `scheduler` and kept it on `migrate` and `replicator`, so the role that runs the
+  // migrations and the role that serves the traffic read different schemas. 0 is a value, not a
+  // silence: it is `migrate` saying it may take as long as it takes, and left unsaid a server-side
+  // `alter database ... set statement_timeout` kills the one role that must outlive it.
+  url.searchParams.set(
+    'options',
+    mergeLibpqOptions(url.searchParams.get('options'), {
+      statement_timeout: String(profile.statementTimeoutMs),
+    }),
+  );
   url.searchParams.set('application_name', options.applicationName ?? 'ultimate');
   return url.toString();
 }
@@ -447,7 +457,9 @@ export async function checkDb(client: DbClient = baseClient()): Promise<DbHealth
     return {
       ok: false,
       latencyMs: Math.round(performance.now() - started),
-      error: error instanceof Error ? error.message : String(error),
+      // `renderThrowable`, never `error.message`: the probe wants a report, and a render that
+      // throws is an exception out of `/readyz` — the one caller that cannot catch it.
+      error: renderThrowable(error),
     };
   }
 }

package/src/drift.ts

@@ -294,7 +294,13 @@ export function driftError(difference: DriftDifference): DbError {
   });
 }
 
-/** Throws the first difference. `x verify` calls this; `x db drift --json` reads the report. */
+/**
+ * Throws the first difference. The one caller is the release phase — `runRole` in `@ultimat3/cli`
+ * under `ROLE=migrate`, where the exit code is the only channel a container has. `x db migrate`
+ * and `x db reset` hold the same report and render every difference as a finding instead
+ * (`driftFindings`), and `x verify`'s `drift` step is the *source* detector (`checkSourceDrift`),
+ * which never reaches this function. There is no `x db drift` command.
+ */
 export function assertNoDrift(report: DriftReport): void {
   const first = report.differences[0];
   if (first !== undefined) throw driftError(first);

package/src/errors.ts

@@ -32,8 +32,17 @@ export const DB_OWNED_ERROR_CODES = [
  * `@ultimat3/core`'s. Never titled here, never registered here. `X_ENV_MISSING` is core's word for
  * "a variable this process was given is missing or invalid", and `DATABASE_POOL_MAX` is one — a
  * db-local code for it would be a second answer to a question core already answers.
+ *
+ * `X_INVARIANT` is core's own "the generic code, for checks that have no dedicated code yet"
+ * (`assert()` in `core/src/assert.ts`), borrowed the same way `@ultimat3/money`'s `roundRatio`
+ * borrows it: an argument a caller built wrong is not a fact about the ledger or the schema, so
+ * none of the `X_MIGRATION_*` codes above describes one.
  */
-export const DB_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED', 'X_ENV_MISSING'] as const;
+export const DB_BORROWED_ERROR_CODES = [
+  'X_NOT_IMPLEMENTED',
+  'X_ENV_MISSING',
+  'X_INVARIANT',
+] as const;
 
 /** Every code db can throw: the ones it owns plus the ones it borrows. */
 export const DB_ERROR_CODES = [...DB_OWNED_ERROR_CODES, ...DB_BORROWED_ERROR_CODES] as const;
@@ -249,6 +258,21 @@ export const migrationConflict = (cause: string, fix: string): DbError =>
 export const migrationIrreversible = (cause: string, fix: string): DbError =>
   new DbError({ code: 'X_MIGRATION_IRREVERSIBLE', cause, fix });
 
+/**
+ * A rollback step count this build cannot honour. `steps` reaches `Array.prototype.slice`, where a
+ * negative count counts from the END: `steps: -1` selected every applied migration except the
+ * newest and reversed four of five, which is the one class of mistake a rollback cannot undo.
+ * Refused rather than coerced, exactly as `DATABASE_POOL_MAX` is — a number silently reinterpreted
+ * as a different one is the failure a validated argument exists to prevent.
+ */
+export const rollbackStepsInvalid = (received: number): DbError =>
+  new DbError({
+    code: 'X_INVARIANT',
+    cause: `rollback was asked to reverse ${String(received)} migrations, which is not a positive integer`,
+    fix: 'rollback({ migrations, steps: 1 })   # a whole number of migrations, newest first',
+    meta: { steps: received },
+  });
+
 /**
  * `packages/db/migrations/0000_initial.snapshot.json` → `packages/db/migrations/0000_initial.*` —
  * every file that one migration owns, as one `rm` argument. Derived from the path the caller passed

package/src/index.ts

@@ -71,6 +71,7 @@ export {
   multipleStatements,
   poolAcquireTimeout,
   poolMaxInvalid,
+  rollbackStepsInvalid,
   serializationExhausted,
   sqlUnsafe,
 } from './errors';

package/src/libpq-options.ts

@@ -0,0 +1,76 @@
+// Single responsibility: merging the framework's own libpq `options` into whatever the operator
+// already put in `DATABASE_URL`. A connection string is the operator's file, not the framework's,
+// and `searchParams.set` on a key they may have written is a silent overwrite of their setting.
+
+/**
+ * libpq hands `options` to the backend as command-line arguments, split on whitespace with a
+ * backslash escaping the next character. Escapes are kept intact, so re-joining the tokens
+ * reproduces the operator's string byte for byte.
+ */
+export function splitLibpqOptions(options: string): readonly string[] {
+  const tokens: string[] = [];
+  let current = '';
+  let open = false;
+  for (let index = 0; index < options.length; index += 1) {
+    const char = options[index] ?? '';
+    const escaped = options[index + 1];
+    if (char === '\\' && escaped !== undefined) {
+      current += `\\${escaped}`;
+      open = true;
+      index += 1;
+      continue;
+    }
+    if (char.trim() === '') {
+      if (open) tokens.push(current);
+      current = '';
+      open = false;
+      continue;
+    }
+    current += char;
+    open = true;
+  }
+  if (open) tokens.push(current);
+  return tokens;
+}
+
+/**
+ * The three spellings a backend accepts for one GUC on the command line: `-c name=value` as two
+ * arguments, `-cname=value` as one, and `--name=value` (where a hyphen in the name reads as an
+ * underscore). A bare `name=value` token is the second half of the first spelling.
+ */
+const ASSIGNS = (name: string): RegExp => new RegExp(`^(?:-c|--)?${name.replaceAll('_', '[_-]')}=`);
+
+/** Drops every assignment of `name`, and the `-c` that introduced it. */
+function without(tokens: readonly string[], name: string): readonly string[] {
+  const assigns = ASSIGNS(name);
+  const kept: string[] = [];
+  for (const token of tokens) {
+    if (!assigns.test(token)) {
+      kept.push(token);
+      continue;
+    }
+    if (kept.at(-1) === '-c') kept.pop();
+  }
+  return kept;
+}
+
+/**
+ * The operator's `options` with the framework's settings merged in.
+ *
+ * **Precedence: the framework wins on the settings it names, the operator keeps everything else.**
+ * A role's `statement_timeout` is a safety bound the role is sized around — `web`'s 10s is what
+ * stops a slow endpoint holding all 20 pool slots — so a value in the URL may not raise it; but a
+ * `search_path`, an `application_name` or a `-c` an operator added is theirs and must survive.
+ * Enforced by removing the framework's own names before appending, never by position: relying on
+ * "the last `-c` wins" would make the bound depend on backend argument order nobody here measured.
+ */
+export function mergeLibpqOptions(
+  existing: string | null,
+  settings: Readonly<Record<string, string>>,
+): string {
+  let tokens = splitLibpqOptions(existing ?? '');
+  for (const [name, value] of Object.entries(settings)) {
+    tokens = [...without(tokens, name), '-c', `${name}=${value}`];
+  }
+  return tokens.join(' ');
+}

package/src/migrate.ts

@@ -11,7 +11,7 @@ import {
   isReservable,
   poolProfileFor,
 } from './client';
-import { migrateConcurrent, migrationConflict } from './errors';
+import { migrateConcurrent, migrationConflict, rollbackStepsInvalid } from './errors';
 import { expectedQueryLoop } from './expected-loop';
 import type { SchemaDescription } from './introspect';
 import { raw, sql } from './sql';
@@ -149,7 +149,13 @@ export function auditLedger(
 ): void {
   const known = new Map(migrations.map((migration) => [migration.id, migration]));
 
-  const foreign = ledger.filter((row) => !known.has(row.id) && row.app_version !== appVersion);
+  // The predicate is "this build does not ship it" and NOTHING else. It used to also require
+  // `row.app_version !== appVersion`, which switched the audit off wherever the two agree —
+  // `runningAppVersion()` answers `dev` for every development build, so a migration applied by an
+  // earlier `dev` build and since deleted was invisible here, and `expectedSchema` then dropped
+  // its table from the drift comparison: `ok: true` against a database that still has the table.
+  // The version is a detail of the ANSWER, so it moved into the cause.
+  const foreign = ledger.filter((row) => !known.has(row.id));
   const first = foreign[0];
   if (first !== undefined) {
     throw migrationConflict(
@@ -374,6 +380,7 @@ export async function migrate(options: MigrateOptions): Promise<MigrationReport>
 export interface RollbackOptions {
   readonly migrations: readonly Migration[];
   readonly client?: DbClient | undefined;
+  /** How many applied migrations to reverse, newest first. A positive integer; defaults to 1. */
   readonly steps?: number | undefined;
   /** Skip the advisory lock. Only `x db branch` does this, against a private database. */
   readonly lock?: boolean | undefined;
@@ -387,6 +394,9 @@ export interface RollbackOptions {
 export async function rollback(options: RollbackOptions): Promise<readonly string[]> {
   const client = options.client ?? baseClient();
   const steps = options.steps ?? 1;
+  // Before the lock and before the ledger read: `slice(0, -1)` is "all but the newest", not
+  // "one fewer", so an unvalidated count reverses migrations nobody asked about.
+  if (!Number.isSafeInteger(steps) || steps < 1) throw rollbackStepsInvalid(steps);
   const lockTimeoutMs = migrationLockTimeoutMs(options.lockTimeoutMs);
   const known = new Map(options.migrations.map((migration) => [migration.id, migration]));