@ultimat3/db 16.0.0 → 17.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 |
@@ -1276,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": "16.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": "16.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;
+}

package/src/client.ts

@@ -1,17 +1,20 @@
-// Single responsibility: the Postgres connection and the ambient `db()` handle. Pool size and
-// statement timeout are chosen by runtime ROLE — a `worker` draining a queue must not size its
-// 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).
+// Single responsibility: the pooled Postgres client and the ambient `db()` handle — one statement
+// funnel, the reserved-connection pin, and the process-wide client every repository reaches
+// through. Sizing lives in `pool-profile.ts`, the connection string in `connection-url.ts`, the
+// `Bun.SQL` slice in `bun-sql.ts`, so importing this module never opens a socket.
 
-import { type Role, renderThrowable, resolveRole } from '@ultimat3/core';
+import { type Role, resolveRole } from '@ultimat3/core';
 import { statementAttribution } from './attribution';
+import { type BunSqlDriver, type BunSqlReserved, bunSqlFactory } from './bun-sql';
+import { connectionUrl } from './connection-url';
 // Deliberate cycle, the same shape as `client.ts ⇄ transaction.ts`: nothing here is referenced at
 // module evaluation, and both sides are `function` declarations, so hoisting covers the TDZ.
 import { defaultClient } from './default-client';
-import { DbError, dbUnavailable, driverError, poolAcquireTimeout, poolMaxInvalid } from './errors';
+import { DbError, driverError } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
-import { declaresLibpqOption, mergeLibpqOptions } from './libpq-options';
 import { statementObserver } from './observe';
+import { assertPoolProfile, type PoolProfile, poolProfileFor } from './pool-profile';
+import { reserveWithin } from './pool-reserve';
 import { type SqlFragment, sql } from './sql';
 import { withStatementSpan } from './statement-span';
 import { currentTx } from './transaction';
@@ -41,123 +44,6 @@ export function isReservable(client: DbClient): client is ReservableClient {
   return typeof (client as Partial<ReservableClient>).reserve === 'function';
 }
 
-export interface PoolProfile {
-  readonly max: number;
-  /** 0 disables the timeout — only `migrate`, which is allowed to take as long as it takes. */
-  readonly statementTimeoutMs: number;
-  readonly idleTimeoutMs: number;
-  /**
-   * How long a statement may **wait for a lock** before `55P03`, distinct from how long it may run.
-   * 0 everywhere but `migrate`, which is the only role that takes `ACCESS EXCLUSIVE`: an `alter
-   * table` queued behind a long `SELECT` puts every later query on that table behind it too,
-   * because Postgres' lock queue is FIFO — and `migrate` runs `statement_timeout = 0`, so nothing
-   * else would ever end the wait. Read by `migrate()` as a `SET LOCAL`, never by the pool.
-   */
-  readonly lockTimeoutMs: number;
-  /**
-   * How long `reserve()` may wait for a free connection before `X_DB_POOL_EXHAUSTED`. 0 waits
-   * forever, which is what a run-once role wants and what a request-serving one must never do:
-   * 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.
-   */
-  readonly acquireTimeoutMs: number;
-}
-
-/** Sized per role because the failure modes differ: RPS bursts vs. queue depth vs. run-once. */
-export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
-  web: {
-    max: 20,
-    statementTimeoutMs: 10_000,
-    idleTimeoutMs: 30_000,
-    lockTimeoutMs: 0,
-    acquireTimeoutMs: 5_000,
-  },
-  sync: {
-    max: 10,
-    statementTimeoutMs: 10_000,
-    idleTimeoutMs: 60_000,
-    lockTimeoutMs: 0,
-    acquireTimeoutMs: 5_000,
-  },
-  worker: {
-    max: 8,
-    statementTimeoutMs: 120_000,
-    idleTimeoutMs: 30_000,
-    lockTimeoutMs: 0,
-    acquireTimeoutMs: 10_000,
-  },
-  scheduler: {
-    max: 2,
-    statementTimeoutMs: 15_000,
-    idleTimeoutMs: 60_000,
-    lockTimeoutMs: 0,
-    acquireTimeoutMs: 10_000,
-  },
-  // `migrate` waits: its pool is `max: 1` and the advisory-lock pin holds it for the whole run, so
-  // a deadline here would refuse the migration's own session. The wait that needed bounding is the
-  // advisory lock's, and `MIGRATION_LOCK_WAIT_MS` bounds it.
-  migrate: {
-    max: 1,
-    statementTimeoutMs: 0,
-    idleTimeoutMs: 10_000,
-    lockTimeoutMs: 3_000,
-    acquireTimeoutMs: 0,
-  },
-  replicator: {
-    max: 4,
-    statementTimeoutMs: 0,
-    idleTimeoutMs: 60_000,
-    lockTimeoutMs: 0,
-    acquireTimeoutMs: 0,
-  },
-});
-
-export function poolProfileFor(role: Role = resolveRole()): PoolProfile {
-  return POOL_PROFILES[role];
-}
-
-/** The one pool knob an operator can turn without a rebuild. Layered over the role default. */
-export const POOL_MAX_ENV = 'DATABASE_POOL_MAX';
-
-/**
- * `DATABASE_POOL_MAX`, or nothing. `POOL_PROFILES` is frozen into the build, so before this the
- * only way to change a fleet's connection count was to ship a new image — and 400 `web` pods at
- * `max: 20` is 8,000 backends against a `max_connections` of 450. An unparseable value **refuses**
- * rather than falling back: a fleet that ignored the number it was given is the failure the
- * variable exists to prevent, and it would only be found in `pg_stat_activity` at 3am.
- */
-export function poolMaxFromEnv(): Partial<PoolProfile> {
-  const raw = process.env[POOL_MAX_ENV];
-  if (raw === undefined || raw.trim() === '') return {};
-  const max = Number(raw);
-  if (!Number.isSafeInteger(max) || max < 1) throw poolMaxInvalid(raw);
-  return { max };
-}
-
-/** One connection pinned out of `Bun.SQL`'s pool, released back by hand. */
-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. */
-interface BunSqlDriver {
-  unsafe(text: string, values?: readonly unknown[]): Promise<unknown>;
-  reserve(): Promise<BunSqlReserved>;
-  close(options?: { readonly timeout?: number }): Promise<void>;
-}
-
-type BunSqlFactory = new (url: string, options?: Readonly<Record<string, unknown>>) => BunSqlDriver;
-
-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;
-}
-
 export interface PostgresClientOptions {
   readonly url?: string | undefined;
   readonly role?: Role | undefined;
@@ -165,46 +51,6 @@ export interface PostgresClientOptions {
   readonly applicationName?: string | undefined;
 }
 
-function connectionUrl(options: PostgresClientOptions, profile: PoolProfile): string {
-  const raw = options.url ?? process.env['DATABASE_URL'];
-  if (raw === undefined || raw === '') {
-    throw dbUnavailable('DATABASE_URL is not set, so there is no database to connect to');
-  }
-  let url: URL;
-  try {
-    url = new URL(raw);
-  } 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 —
-  // 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.
-  // `application_name` is a LABEL, not a bound: 'ultimate' is a DEFAULT, and a default may not
-  // overwrite what the operator wrote — `?application_name=billing-api` is the filter their
-  // `pg_stat_activity` query, their pooler rule and their audit rule all match on, and losing it
-  // is silent. Both spellings count, or the URL parameter and a `-c application_name=` in
-  // `options` disagree and which one the backend honours is argument order nobody here measured.
-  const named = options.applicationName;
-  const settings: Record<string, string> = {
-    statement_timeout: String(profile.statementTimeoutMs),
-  };
-  const inOptions = declaresLibpqOption(url.searchParams.get('options'), 'application_name');
-  // An explicit `applicationName` is a deliberate call by the role that opened the pool, so it
-  // wins. Only then is the setting named to the merge, and only when the operator wrote the other
-  // spelling: `mergeLibpqOptions` drops their assignment before appending, so the two cannot
-  // disagree — and a URL with no assignment in it keeps the exact `options` it always had.
-  if (named !== undefined && inOptions) settings['application_name'] = named;
-  const declared = url.searchParams.has('application_name') || inOptions;
-  url.searchParams.set('options', mergeLibpqOptions(url.searchParams.get('options'), settings));
-  if (named !== undefined) url.searchParams.set('application_name', named);
-  else if (!declared) url.searchParams.set('application_name', 'ultimate');
-  return url.toString();
-}
-
 function rowsOf<T>(result: unknown): readonly T[] {
   return Array.isArray(result) ? (result as readonly T[]) : [];
 }
@@ -219,49 +65,6 @@ function affectedBy(result: unknown): number {
   return typeof count === 'number' && count > 0 ? count : result.length;
 }
 
-/**
- * `pool.reserve()` under a deadline. Without one an exhausted pool does not fail, it **queues** —
- * so a slow endpoint filling all 20 slots turns every later request, `/readyz`'s `select 1`
- * included, into a wait with no end and no error, and the pod is killed for being unready rather
- * than answering 503 for the requests it cannot serve.
- *
- * The losing reservation is released, never dropped: the pool hands out a connection whenever one
- * frees, deadline or no deadline, and a pin nobody holds is a connection nobody gets back. That is
- * the whole reason this is not a bare `Promise.race`.
- */
-async function reserveWithin(
-  pool: Pick<BunSqlDriver, 'reserve'>,
-  profile: PoolProfile,
-): Promise<BunSqlReserved> {
-  const budget = profile.acquireTimeoutMs;
-  if (budget <= 0) return pool.reserve();
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  let expired = false;
-  const pending = pool.reserve();
-  try {
-    return await Promise.race([
-      pending,
-      new Promise<never>((_resolve, reject) => {
-        timer = setTimeout(() => {
-          expired = true;
-          reject(poolAcquireTimeout(budget, profile.max));
-        }, budget);
-        // The deadline must not be what keeps a finished process alive.
-        timer.unref?.();
-      }),
-    ]);
-  } finally {
-    if (timer !== undefined) clearTimeout(timer);
-    // Attached unconditionally so a rejection arriving after we gave up is handled, not unhandled.
-    void pending.then(
-      (late) => {
-        if (expired) late.release();
-      },
-      () => undefined,
-    );
-  }
-}
-
 export interface PostgresClient extends ReservableClient {
   readonly profile: PoolProfile;
   ping(): Promise<void>;
@@ -271,7 +74,10 @@ export interface PostgresClient extends ReservableClient {
 /** Lazily connects: the pool opens on the first statement, never at import. */
 export function createPostgresClient(options: PostgresClientOptions = {}): PostgresClient {
   const role = options.role ?? resolveRole();
-  const profile: PoolProfile = { ...poolProfileFor(role), ...(options.profile ?? {}) };
+  const profile: PoolProfile = assertPoolProfile({
+    ...poolProfileFor(role),
+    ...(options.profile ?? {}),
+  });
   let driver: BunSqlDriver | undefined;
 
   function connect(): BunSqlDriver {
@@ -455,27 +261,3 @@ export function baseClient(): DbClient {
 export function db(): DbClient {
   return currentTx() ?? baseClient();
 }
-
-/** Named `Db*` because `@ultimat3/core` already exports a `HealthReport` for the lifecycle. */
-export interface DbHealthReport {
-  readonly ok: boolean;
-  readonly latencyMs: number;
-  readonly error?: string | undefined;
-}
-
-/** Backs `/readyz` for every role. Never throws — the probe wants a report, not an exception. */
-export async function checkDb(client: DbClient = baseClient()): Promise<DbHealthReport> {
-  const started = performance.now();
-  try {
-    await client.query(sql`select 1`);
-    return { ok: true, latencyMs: Math.round(performance.now() - started) };
-  } catch (error) {
-    return {
-      ok: false,
-      latencyMs: Math.round(performance.now() - started),
-      // `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/connection-url.ts

@@ -0,0 +1,60 @@
+// Single responsibility: turning `DATABASE_URL` plus a resolved pool profile into the connection
+// string the driver opens — the libpq `options` merge and the `application_name` label. Split from
+// `client.ts` because which settings reach a connection is a rule, not a step of connecting.
+
+import { describeValue } from '@ultimat3/core';
+import { dbUnavailable } from './errors';
+import { declaresLibpqOption, mergeLibpqOptions } from './libpq-options';
+import type { PoolProfile } from './pool-profile';
+
+export interface ConnectionUrlOptions {
+  readonly url?: string | undefined;
+  readonly applicationName?: string | undefined;
+}
+
+export function connectionUrl(options: ConnectionUrlOptions, profile: PoolProfile): string {
+  const raw = options.url ?? process.env['DATABASE_URL'];
+  if (raw === undefined || raw === '') {
+    throw dbUnavailable('DATABASE_URL is not set, so there is no database to connect to');
+  }
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch (error) {
+    // The SHAPE of the rejected value, never the value. A connection string is
+    // `user:password@host` by construction, and this `cause` is the boot log line AND the `--json`
+    // payload — the logger redacts `fields` by key, so a password baked into a message has no key
+    // left to redact it by. `@ultimat3/core`'s `defineEnv` reached the identical conclusion about
+    // the identical variable (`packages/core/src/env.ts`); this is the same rule at the second
+    // reader, not a second rule. The value still has a printer: `x env check`, through
+    // `maskedEnvValues`.
+    throw dbUnavailable(`DATABASE_URL is not a valid url: received ${describeValue(raw)}`, error);
+  }
+  // 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.
+  // `application_name` is a LABEL, not a bound: 'ultimate' is a DEFAULT, and a default may not
+  // overwrite what the operator wrote — `?application_name=billing-api` is the filter their
+  // `pg_stat_activity` query, their pooler rule and their audit rule all match on, and losing it
+  // is silent. Both spellings count, or the URL parameter and a `-c application_name=` in
+  // `options` disagree and which one the backend honours is argument order nobody here measured.
+  const named = options.applicationName;
+  const settings: Record<string, string> = {
+    statement_timeout: String(profile.statementTimeoutMs),
+  };
+  const inOptions = declaresLibpqOption(url.searchParams.get('options'), 'application_name');
+  // An explicit `applicationName` is a deliberate call by the role that opened the pool, so it
+  // wins. Only then is the setting named to the merge, and only when the operator wrote the other
+  // spelling: `mergeLibpqOptions` drops their assignment before appending, so the two cannot
+  // disagree — and a URL with no assignment in it keeps the exact `options` it always had.
+  if (named !== undefined && inOptions) settings['application_name'] = named;
+  const declared = url.searchParams.has('application_name') || inOptions;
+  url.searchParams.set('options', mergeLibpqOptions(url.searchParams.get('options'), settings));
+  if (named !== undefined) url.searchParams.set('application_name', named);
+  else if (!declared) url.searchParams.set('application_name', 'ultimate');
+  return url.toString();
+}

package/src/db-health.ts

@@ -0,0 +1,31 @@
+// Single responsibility: the database's readiness answer — one `select 1` timed and reported, never
+// thrown. Split from `client.ts` because a probe's report is a different job from opening a pool,
+// and every role's `/readyz` reads this one and nothing else of the client.
+
+import { renderThrowable } from '@ultimat3/core';
+import { baseClient, type DbClient } from './client';
+import { sql } from './sql';
+
+/** Named `Db*` because `@ultimat3/core` already exports a `HealthReport` for the lifecycle. */
+export interface DbHealthReport {
+  readonly ok: boolean;
+  readonly latencyMs: number;
+  readonly error?: string | undefined;
+}
+
+/** Backs `/readyz` for every role. Never throws — the probe wants a report, not an exception. */
+export async function checkDb(client: DbClient = baseClient()): Promise<DbHealthReport> {
+  const started = performance.now();
+  try {
+    await client.query(sql`select 1`);
+    return { ok: true, latencyMs: Math.round(performance.now() - started) };
+  } catch (error) {
+    return {
+      ok: false,
+      latencyMs: Math.round(performance.now() - started),
+      // `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/default-client.ts

@@ -3,7 +3,8 @@
 // framework decides a process's database topology from the environment, and `client.ts` is at the
 // line ceiling.
 
-import { createPostgresClient, type DbClient, poolMaxFromEnv } from './client';
+import { createPostgresClient, type DbClient } from './client';
+import { poolMaxFromEnv } from './pool-profile';
 import { replicatedClient } from './replica-client';
 
 /**

package/src/drift-errors.ts

@@ -0,0 +1,36 @@
+// Single responsibility: the `X_DB_DRIFT` constructor — the error form of the finding
+// `drift-findings.ts`'s `unexpectedColumn` reports, thrown where a caller has no report to hand
+// back. Split out of `errors.ts` for the import it needs and nothing else: the fix line puts a
+// column name into a shell command, so it screens through `shellInertIdentifier` (`sql.ts`) —
+// and `sql.ts` imports `errors.ts`, so this cannot live there without a cycle around the module
+// whose evaluation registers every code. The code is still declared, titled and registered in
+// `errors.ts`, exactly as `migration-errors.ts` and `invariant-errors.ts` are.
+
+import { DbError } from './errors';
+import { shellInertIdentifier } from './sql';
+
+/**
+ * The contract's pinned wording. Mirror of `@ultimat3/entity`'s `dbDrift()` — keep in sync; that
+ * one screens the column through the same `@ultimat3/db` export, so the two lines are the same
+ * text on both sides of the tier seam.
+ *
+ * The column name is the CATALOG's, so it is data: whoever can add a column picks the text that
+ * lands here, and `x db gen "add C"` puts it inside SHELL DOUBLE QUOTES, where `$(…)` and a
+ * backtick substitute before `x` is reached at all. The argument is a migration DESCRIPTION and
+ * not an identifier, so no quoted form makes a hostile name safe to pass — a name the screen
+ * refuses is left OUT of the command rather than escaped into it. The command still runs and
+ * still generates the migration; the name is read off `cause` and `meta`, which are prose nobody
+ * pastes.
+ */
+export const dbDrift = (tableName: string, columnName: string): DbError =>
+  new DbError({
+    code: 'X_DB_DRIFT',
+    cause: `table "${tableName}" has column "${columnName}" not present in any migration`,
+    fix:
+      shellInertIdentifier(columnName) === null
+        ? 'x db gen "add the column named in this error"   # its name carries a backtick, a ' +
+          'dollar sign, a quote, a backslash or whitespace, so it is in the cause and not in ' +
+          'this command'
+        : `x db gen "add ${columnName}"`,
+    meta: { table: tableName, column: columnName },
+  });

package/src/drift-findings.ts

@@ -14,6 +14,7 @@
 import { onDeleteRule, rebuildForeignKey } from './foreign-key';
 import type { CheckDescription, ForeignKeyDescription } from './introspect';
 import type { Migration } from './migrate';
+import { shellInertIdentifier } from './sql';
 
 export type DriftKind =
   | 'unexpected-column'
@@ -41,6 +42,15 @@ export interface DriftReport {
   readonly differences: readonly DriftDifference[];
 }
 
+/**
+ * The one `fix:` here whose second layer no quoting closes. `x db gen "add C"` puts the column
+ * inside SHELL DOUBLE QUOTES, where `$(…)` and a backtick substitute before `x` is reached at all
+ * — and the argument is a migration DESCRIPTION, not an identifier, so there is no quoted form
+ * that would make a hostile name safe to pass. A name `shellInertIdentifier` (`sql.ts`) refuses
+ * is therefore left out of the command rather than escaped into it: the command still runs and
+ * still generates the migration, and the name is read off `cause` and `column`, which are prose
+ * nobody pastes.
+ */
 export function unexpectedColumn(table: string, column: string): DriftDifference {
   return {
     kind: 'unexpected-column',
@@ -48,7 +58,12 @@ export function unexpectedColumn(table: string, column: string): DriftDifference
     column,
     // Pinned by the contract. Do not reword without changing docs/errors/X_DB_DRIFT.
     cause: `table "${table}" has column "${column}" not present in any migration`,
-    fix: `x db gen "add ${column}"`,
+    fix:
+      shellInertIdentifier(column) === null
+        ? 'x db gen "add the undeclared column"   # the live column name carries a backtick, a ' +
+          'dollar sign, a quote, a backslash or whitespace, so it is in the cause and not in ' +
+          'this command'
+        : `x db gen "add ${column}"`,
   };
 }
 
@@ -82,6 +97,8 @@ export function changedColumn(
   liveNullable: boolean,
 ): DriftDifference {
   const clause = liveNullable ? 'set not null' : 'drop not null';
+  const relation = shellInertIdentifier(table);
+  const attribute = shellInertIdentifier(column);
   return {
     kind: 'changed-column',
     table,
@@ -89,19 +106,47 @@ export function changedColumn(
     cause: liveNullable
       ? `table "${table}" allows NULL in column "${column}" that migrations declare not null`
       : `table "${table}" forbids NULL in column "${column}" that migrations declare nullable`,
+    // Both identifiers are the catalog's, so both go through the one screen. A refusal names the
+    // column as the thing it could not spell, which is what tells this line apart from
+    // `missingCheck`'s refusal in a report that carries both.
     fix:
-      `alter table "${table}" alter column "${column}" ${clause};   # in a new migration` +
-      (liveNullable ? ' — backfill the existing NULLs first' : ''),
+      relation === null || attribute === null
+        ? `${clause} on the column named in this difference, in a new migration, then ` +
+          'x db migrate — its table or column name carries a backtick, a dollar sign, a quote, ' +
+          'a backslash or whitespace, so no statement here can spell it'
+        : `alter table ${relation} alter column ${attribute} ${clause};   # in a new migration` +
+          (liveNullable ? ' — backfill the existing NULLs first' : ''),
   };
 }
 
+/**
+ * The `fix:` names the two edits that actually resolve this, and neither is `x db gen` (issue
+ * #345). That command diffs the ENTITY REGISTRY against the newest snapshot, and a table nothing
+ * declares is absent from both sides of that diff — so it wrote an EMPTY migration, and the
+ * generator's own empty-diff branch writes no file at all, leaving the reader with nothing to run
+ * and the same finding on the next deploy.
+ *
+ * What is left once `@ultimat3/cli`'s `acceptCreatedTables` has run is a table no migration's SQL
+ * creates and no entity declares — so either a migration should claim it (`if not exists`, because
+ * the relation is already there, and `x db migrate` then accepts a table its own SQL creates), or
+ * nothing owns it and it should not be in this schema. No migration PATH is named: where an app
+ * keeps its migrations is the CLI's fact, not this package's.
+ */
 export function unexpectedTable(table: string): DriftDifference {
+  const name = shellInertIdentifier(table);
   return {
     kind: 'unexpected-table',
     table,
     column: null,
     cause: `table "${table}" is not present in any migration`,
-    fix: `x db gen "add ${table}"`,
+    fix:
+      name === null
+        ? 'claim it in a migration with create table if not exists, or drop it by hand — its ' +
+          'table name carries a backtick, a dollar sign, a quote, a backslash or whitespace, so ' +
+          'no statement here can spell it'
+        : `put a create table if not exists ${name} (…) statement in a migration — x db migrate ` +
+          'then accepts a table its own SQL creates — or, if nothing owns it, run ' +
+          `drop table ${name}; inside psql "$DATABASE_URL"`,
   };
 }
 
@@ -174,6 +219,8 @@ export function changedIndex(table: string, index: string, detail: string): Drif
  * the predicate, which is what makes an executable fix possible at all.
  */
 export function missingCheck(table: string, check: CheckDescription): DriftDifference {
+  const relation = shellInertIdentifier(table);
+  const constraint = shellInertIdentifier(check.name);
   return {
     kind: 'missing-check',
     table,
@@ -183,9 +230,19 @@ export function missingCheck(table: string, check: CheckDescription): DriftDiffe
     // banned advice word the `errors` gate demands a command beside: writing the migration is half
     // the repair and applying it is the other half, and `changedColumn`'s bare `# in a new
     // migration` leaves the second half to be guessed.
+    //
+    // Both NAMES go through the one screen; the EXPRESSION deliberately does not, and cannot. It
+    // is a predicate, so no screen could accept `status in ('draft', 'published')` and reject a
+    // second statement — and it is the DECLARED side's own text, out of the author's migration,
+    // where both names are the catalog's and a sidecar's. Narrower than "this line is safe", and
+    // it is the honest claim.
     fix:
-      `alter table "${table}" add constraint "${check.name}" ` +
-      `check (${check.expression});   # in a new migration, then x db migrate`,
+      relation === null || constraint === null
+        ? 'add the constraint named in this difference back in a new migration, then ' +
+          'x db migrate — its table or constraint name carries a backtick, a dollar sign, a ' +
+          'quote, a backslash or whitespace, so no statement here can spell it'
+        : `alter table ${relation} add constraint ${constraint} ` +
+          `check (${check.expression});   # in a new migration, then x db migrate`,
   };
 }
 

package/src/drift-fixtures.ts

@@ -0,0 +1,23 @@
+// TEST-ONLY. The two builders every drift suite compares with — a `TableDescription` of text
+// columns and the `SchemaDescription` around it. One copy, because three suites arguing about
+// schemas built differently would each be judging a different fixture. Never exported from
+// `index.ts`.
+
+import type { SchemaDescription, TableDescription } from './introspect';
+
+export const table = (name: string, columns: readonly string[]): TableDescription => ({
+  schema: 'public',
+  name,
+  columns: columns.map((column, index) => ({
+    name: column,
+    dataType: 'text',
+    nullable: true,
+    default: null,
+    position: index + 1,
+  })),
+  primaryKey: ['id'],
+  indexes: [],
+  foreignKeys: [],
+});
+
+export const schema = (...tables: readonly TableDescription[]): SchemaDescription => ({ tables });

package/src/errors.ts

@@ -285,15 +285,6 @@ export const serializationExhausted = (attempts: number, sourceError: unknown):
     sourceError,
   });
 
-/** The contract's pinned wording. Mirror of `@ultimat3/entity`'s `dbDrift()` — keep in sync. */
-export const dbDrift = (tableName: string, columnName: string): DbError =>
-  new DbError({
-    code: 'X_DB_DRIFT',
-    cause: `table "${tableName}" has column "${columnName}" not present in any migration`,
-    fix: `x db gen "add ${columnName}"`,
-    meta: { table: tableName, column: columnName },
-  });
-
 export const sqlUnsafe = (received: string, position: number): DbError =>
   new DbError({
     code: 'X_SQL_UNSAFE',

package/src/index.ts

@@ -23,25 +23,15 @@ export {
 export type {
   DbClient,
   DbConnection,
-  DbHealthReport,
-  PoolProfile,
   PostgresClient,
   PostgresClientOptions,
   ReservableClient,
 } from './client';
-export {
-  baseClient,
-  checkDb,
-  createPostgresClient,
-  db,
-  isReservable,
-  POOL_MAX_ENV,
-  POOL_PROFILES,
-  poolProfileFor,
-  setDbClient,
-} from './client';
+export { baseClient, createPostgresClient, db, isReservable, setDbClient } from './client';
 export type { ColumnDefaultLike } from './column-default';
 export { defaultExpression } from './column-default';
+export type { DbHealthReport } from './db-health';
+export { checkDb } from './db-health';
 export { defaultClient, REPLICA_URL_ENV } from './default-client';
 export type { DestructiveKind, DestructiveStatement } from './destructive';
 export {
@@ -62,6 +52,7 @@ export {
   expectedSchema,
   FRAMEWORK_TABLE_PREFIX,
 } from './drift';
+export { dbDrift } from './drift-errors';
 export type {
   ColumnDescriptionLike,
   EntityDescriptionLike,
@@ -76,7 +67,6 @@ export {
   DB_ERROR_RETRY,
   DB_ERROR_TITLES,
   DbError,
-  dbDrift,
   dbNotImplemented,
   dbUnavailable,
   driverError,
@@ -169,6 +159,8 @@ export {
 } from './pglite';
 export type { PgliteBranchInfo, PgliteBranchOptions } from './pglite-branch';
 export { branchPglite, pgliteBranchDir } from './pglite-branch';
+export type { PoolProfile } from './pool-profile';
+export { POOL_MAX_ENV, POOL_PROFILES, poolProfileFor } from './pool-profile';
 export type { ReadOnlyQueryOptions, ReadOnlyQueryResult } from './readonly-query';
 export { READONLY_TIMEOUT_MS, readOnlyQuery } from './readonly-query';
 export type { ReadOnlyRoleOptions } from './readonly-role';
@@ -185,7 +177,15 @@ export { markScopeWrote, replicaScope, withReplicaReads } from './replica-scope'
 export { snapshotJson } from './snapshot-json';
 export { parseSnapshot } from './snapshot-parse';
 export type { SqlFragment } from './sql';
-export { identifier, isSqlFragment, join, literal, raw, sql } from './sql';
+export {
+  identifier,
+  isSqlFragment,
+  join,
+  literal,
+  raw,
+  shellInertIdentifier,
+  sql,
+} from './sql';
 export { stripSqlNoise } from './sql-noise';
 export type { DbSqlStateCode } from './sqlstate';
 export { DB_SQLSTATE_CODES, isRetryableState, SQLSTATE, sqlState, sqlStateCode } from './sqlstate';

package/src/migrate.ts

@@ -3,18 +3,13 @@
 // app-version fence is the `migrate` role's contract — a pod must refuse to migrate a database
 // another build already owns, because the alternative is two schemas racing during a rollout.
 
-import { appVersion } from '@ultimat3/core';
-import {
-  baseClient,
-  type DbClient,
-  type DbConnection,
-  isReservable,
-  poolProfileFor,
-} from './client';
+import { appVersion, finiteCount } from '@ultimat3/core';
+import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
 import { refuseDependentViews } from './dependent-view';
 import { expectedQueryLoop } from './expected-loop';
 import type { SchemaDescription } from './introspect';
 import { migrateConcurrent, migrationConflict, rollbackStepsInvalid } from './migration-errors';
+import { poolProfileFor } from './pool-profile';
 import { raw, sql } from './sql';
 import { SQLSTATE, sqlState } from './sqlstate';
 import { statementsOf } from './statement-split';
@@ -237,6 +232,9 @@ async function acquireLock(session: DbClient, waitMs: number): Promise<void> {
           sql`select pg_try_advisory_lock(${MIGRATION_LOCK_KEY}) as locked`,
         );
         if (row?.locked === true) return;
+        // `waitMs` is screened at both call sites: `NaN - elapsed` is `NaN`, `NaN <= 0` is false
+        // and `Bun.sleep(Math.min(POLL, NaN))` does not sleep — so an unbounded wait is not what a
+        // non-finite one produced, a tight spin re-taking `pg_try_advisory_lock` was.
         const remaining = waitMs - (performance.now() - started);
         if (remaining <= 0) {
           throw migrateConcurrent(MIGRATION_LOCK_KEY, Math.round(performance.now() - started));
@@ -317,7 +315,17 @@ async function setLockTimeout(tx: DbTx, lockTimeoutMs: number): Promise<void> {
  * same `ACCESS EXCLUSIVE` locks against the same tables.
  */
 function migrationLockTimeoutMs(explicit: number | undefined): number {
-  return explicit ?? poolProfileFor('migrate').lockTimeoutMs;
+  // Screened here, where BOTH `migrate()` and `rollback()` resolve it, and before either takes the
+  // advisory lock. `lockWaitMs` beside it was screened from the start and this one was not, so
+  // `Number(process.env.…)` on an unset variable travelled all the way to `SET LOCAL lock_timeout
+  // = NaN`, which the server rejects inside the migration's own transaction — the option that was
+  // wrong appears nowhere in what the deploy prints. `finiteCount`, never a second bound checker.
+  return finiteCount(
+    'migrate',
+    'lockTimeoutMs',
+    explicit ?? poolProfileFor('migrate').lockTimeoutMs,
+    0,
+  );
 }
 
 export async function migrate(options: MigrateOptions): Promise<MigrationReport> {
@@ -329,7 +337,7 @@ export async function migrate(options: MigrateOptions): Promise<MigrationReport>
   return withAdvisoryLock(
     client,
     options.lock !== false,
-    options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS,
+    finiteCount('migrate', 'lockWaitMs', options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS, 0),
     async (session) => {
       await ensureLedger(session);
       const ledger = await readLedger(session);
@@ -419,7 +427,7 @@ export async function rollback(options: RollbackOptions): Promise<readonly strin
   return withAdvisoryLock(
     client,
     options.lock !== false,
-    options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS,
+    finiteCount('migrate', 'lockWaitMs', options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS, 0),
     async (session) => {
       const ledger = await readLedger(session);
       const targets = [...ledger].reverse().slice(0, steps);

package/src/pool-profile.ts

@@ -0,0 +1,125 @@
+// Single responsibility: the five numbers a Postgres pool runs on — the per-role defaults, the one
+// environment override an operator may layer over them, and the screen every resolved profile
+// passes. Split from `client.ts`, which now owns connecting and nothing about sizing.
+
+import { assert, type Role, resolveRole } from '@ultimat3/core';
+import { poolMaxInvalid } from './errors';
+
+export interface PoolProfile {
+  readonly max: number;
+  /** 0 disables the timeout — only `migrate`, which is allowed to take as long as it takes. */
+  readonly statementTimeoutMs: number;
+  readonly idleTimeoutMs: number;
+  /**
+   * How long a statement may **wait for a lock** before `55P03`, distinct from how long it may run.
+   * 0 everywhere but `migrate`, which is the only role that takes `ACCESS EXCLUSIVE`: an `alter
+   * table` queued behind a long `SELECT` puts every later query on that table behind it too,
+   * because Postgres' lock queue is FIFO — and `migrate` runs `statement_timeout = 0`, so nothing
+   * else would ever end the wait. Read by `migrate()` as a `SET LOCAL`, never by the pool.
+   */
+  readonly lockTimeoutMs: number;
+  /**
+   * How long `reserve()` may wait for a free connection before `X_DB_POOL_EXHAUSTED`. 0 waits
+   * forever, which is what a run-once role wants and what a request-serving one must never do:
+   * 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.
+   */
+  readonly acquireTimeoutMs: number;
+}
+
+/** Sized per role because the failure modes differ: RPS bursts vs. queue depth vs. run-once. */
+export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
+  web: {
+    max: 20,
+    statementTimeoutMs: 10_000,
+    idleTimeoutMs: 30_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 5_000,
+  },
+  sync: {
+    max: 10,
+    statementTimeoutMs: 10_000,
+    idleTimeoutMs: 60_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 5_000,
+  },
+  worker: {
+    max: 8,
+    statementTimeoutMs: 120_000,
+    idleTimeoutMs: 30_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 10_000,
+  },
+  scheduler: {
+    max: 2,
+    statementTimeoutMs: 15_000,
+    idleTimeoutMs: 60_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 10_000,
+  },
+  // `migrate` waits: its pool is `max: 1` and the advisory-lock pin holds it for the whole run, so
+  // a deadline here would refuse the migration's own session. The wait that needed bounding is the
+  // advisory lock's, and `MIGRATION_LOCK_WAIT_MS` bounds it.
+  migrate: {
+    max: 1,
+    statementTimeoutMs: 0,
+    idleTimeoutMs: 10_000,
+    lockTimeoutMs: 3_000,
+    acquireTimeoutMs: 0,
+  },
+  replicator: {
+    max: 4,
+    statementTimeoutMs: 0,
+    idleTimeoutMs: 60_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 0,
+  },
+});
+
+export function poolProfileFor(role: Role = resolveRole()): PoolProfile {
+  return POOL_PROFILES[role];
+}
+
+/** The one pool knob an operator can turn without a rebuild. Layered over the role default. */
+export const POOL_MAX_ENV = 'DATABASE_POOL_MAX';
+
+/**
+ * `DATABASE_POOL_MAX`, or nothing. `POOL_PROFILES` is frozen into the build, so before this the
+ * only way to change a fleet's connection count was to ship a new image — and 400 `web` pods at
+ * `max: 20` is 8,000 backends against a `max_connections` of 450. An unparseable value **refuses**
+ * rather than falling back: a fleet that ignored the number it was given is the failure the
+ * variable exists to prevent, and it would only be found in `pg_stat_activity` at 3am.
+ */
+export function poolMaxFromEnv(): Partial<PoolProfile> {
+  const raw = process.env[POOL_MAX_ENV];
+  if (raw === undefined || raw.trim() === '') return {};
+  const max = Number(raw);
+  if (!Number.isSafeInteger(max) || max < 1) throw poolMaxInvalid(raw);
+  return { max };
+}
+
+/**
+ * The five numbers a pool runs on, screened on the MERGED profile — an override is spread over a
+ * role default the caller never restated, so the resolved object is the only one that can be
+ * judged. Every one of them is a plausible `Number(process.env.…)`, which is `NaN` for an unset
+ * variable and not nullish, so `??` and the spread both keep it. None of the five then fails
+ * loudly: `idleTimeout: NaN` goes to `Bun.SQL`, `statement_timeout=NaN` goes into the libpq
+ * options string for the SERVER to reject on connect, and a timer given `NaN` fires at 1ms in this
+ * Bun — so a pool with free connections reports itself exhausted. `0` stays legal for the three
+ * budgets that document it as "no bound"; `max` is at least one connection, or nothing can run.
+ */
+export function assertPoolProfile(profile: PoolProfile): PoolProfile {
+  const whole = (option: string, value: number, min: 0 | 1): void => {
+    assert(
+      Number.isSafeInteger(value) && value >= min,
+      `pool profile ${option} is ${String(value)}; it must be a whole number of ${min === 1 ? 'at least 1' : '0 or more, where 0 is the documented "no bound"'}`,
+      `pass a whole number for ${option} in createPostgresClient({ profile }), and parse an environment value first — Number(process.env.DATABASE_${option.toUpperCase()} ?? '') is NaN when the variable is unset`,
+    );
+  };
+  whole('max', profile.max, 1);
+  whole('statementTimeoutMs', profile.statementTimeoutMs, 0);
+  whole('idleTimeoutMs', profile.idleTimeoutMs, 0);
+  whole('lockTimeoutMs', profile.lockTimeoutMs, 0);
+  whole('acquireTimeoutMs', profile.acquireTimeoutMs, 0);
+  return profile;
+}

package/src/pool-reserve.ts

@@ -0,0 +1,50 @@
+// Single responsibility: pinning a connection out of the pool under the profile's acquire deadline,
+// and giving back a reservation that arrives after the deadline has passed. Split from `client.ts`,
+// which now asks for a pin rather than owning what "waited too long" means.
+
+import type { BunSqlDriver, BunSqlReserved } from './bun-sql';
+import { poolAcquireTimeout } from './errors';
+import type { PoolProfile } from './pool-profile';
+
+/**
+ * `pool.reserve()` under a deadline. Without one an exhausted pool does not fail, it **queues** —
+ * so a slow endpoint filling all 20 slots turns every later request, `/readyz`'s `select 1`
+ * included, into a wait with no end and no error, and the pod is killed for being unready rather
+ * than answering 503 for the requests it cannot serve.
+ *
+ * The losing reservation is released, never dropped: the pool hands out a connection whenever one
+ * frees, deadline or no deadline, and a pin nobody holds is a connection nobody gets back. That is
+ * the whole reason this is not a bare `Promise.race`.
+ */
+export async function reserveWithin(
+  pool: Pick<BunSqlDriver, 'reserve'>,
+  profile: PoolProfile,
+): Promise<BunSqlReserved> {
+  const budget = profile.acquireTimeoutMs;
+  if (budget <= 0) return pool.reserve();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let expired = false;
+  const pending = pool.reserve();
+  try {
+    return await Promise.race([
+      pending,
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => {
+          expired = true;
+          reject(poolAcquireTimeout(budget, profile.max));
+        }, budget);
+        // The deadline must not be what keeps a finished process alive.
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    // Attached unconditionally so a rejection arriving after we gave up is handled, not unhandled.
+    void pending.then(
+      (late) => {
+        if (expired) late.release();
+      },
+      () => undefined,
+    );
+  }
+}

package/src/readonly-query.ts

@@ -3,6 +3,7 @@
 // enforcing read-only beats a regex, and the timeout bounds a runaway scan the agent never
 // meant to ask for.
 
+import { finiteCount } from '@ultimat3/core';
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
 import { multipleStatements } from './errors';
 import { identifier, raw, sql } from './sql';
@@ -89,6 +90,26 @@ export async function readOnlyQuery<T>(
   const statements = statementsOf(statement);
   if (statements.length > 1) throw multipleStatements(statement, statements.length);
 
+  // Decided before anything is opened, for the reason `rollback({ steps })` screens before it
+  // takes the advisory lock: a value this build cannot honour is not a fact about the pool. It
+  // was computed after `reserve()` and after `BEGIN READ ONLY`, so an unbounded `timeoutMs`
+  // against an exhausted pool answered with the pool's error — or waited for a connection it was
+  // never going to use — in place of the `X_INVARIANT` naming the option that was wrong.
+  //
+  // Clamped and truncated to an integer: the result is a JS number the caller never touches
+  // as text, so there is nothing here for `raw()` to inject — `SET LOCAL` can't bind `$n`
+  // parameters, which is why this can't go through `sql` the normal, parameterised way.
+  // REFUSED rather than normalised: `NaN` used to take the default silently, so a config typo
+  // ran under a timeout nobody wrote. Only an explicit 0 disables the layer, which is why the
+  // floor is 0 and not 1; the hour ceiling is a clamp on a number that IS one.
+  const asked = finiteCount(
+    'readonlyQuery',
+    'timeoutMs',
+    options.timeoutMs ?? READONLY_TIMEOUT_MS,
+    0,
+  );
+  const ms = Math.min(3_600_000, asked);
+
   const client = options.client ?? baseClient();
   // A pooled BEGIN that lands on a different physical connection than the query that follows is
   // not a transaction at all, so a reservable client must pin one connection for the sequence.
@@ -104,14 +125,6 @@ export async function readOnlyQuery<T>(
     await connection.execute(raw('BEGIN READ ONLY'));
     guards.push('txn:read-only');
 
-    // Clamped and truncated to an integer: the result is a JS number the caller never touches
-    // as text, so there is nothing here for `raw()` to inject — `SET LOCAL` can't bind `$n`
-    // parameters, which is why this can't go through `sql` the normal, parameterised way.
-    // NaN normalises to the default first: only an explicit 0 disables the timeout, and
-    // `Math.min(3_600_000, NaN)` is NaN, which would fail `ms > 0` and silently skip the layer.
-    const asked = options.timeoutMs ?? READONLY_TIMEOUT_MS;
-    const requested = Number.isNaN(asked) ? READONLY_TIMEOUT_MS : asked;
-    const ms = Math.max(0, Math.min(3_600_000, Math.trunc(requested)));
     if (ms > 0) {
       // `LOCAL`, so the setting dies with the transaction — one agent read must not re-time
       // every request the pool serves afterwards. Caveat: embedded PGlite applies the setting

package/src/replica-client.ts

@@ -3,7 +3,7 @@
 // handle a statement is sent on, what happens when the replica will not answer, and the counters
 // that make both visible to a test that cannot scrape a metrics endpoint.
 
-import { type Clock, logger, renderThrowable, systemClock } from '@ultimat3/core';
+import { type Clock, finiteCount, logger, renderThrowable, systemClock } from '@ultimat3/core';
 import { type DbClient, type DbConnection, isReservable, type ReservableClient } from './client';
 import { isPlainRead } from './replica-route';
 import { markScopeWrote, replicaScope } from './replica-scope';
@@ -53,8 +53,21 @@ export function replicatedClient(
   options: ReplicatedClientOptions = {},
 ): ReplicatedClient {
   const clock = options.clock ?? systemClock;
-  const limit = options.breakerFailures ?? BREAKER_FAILURES;
-  const cooldown = options.breakerCooldownMs ?? BREAKER_COOLDOWN_MS;
+  // Both are comparisons and nothing else — `consecutiveFailures >= limit` opens the breaker,
+  // `monotonic() < parkedUntil` holds it open — so a `NaN` in either is a breaker that never trips
+  // and never parks, with every read still going to the replica that is failing.
+  const limit = finiteCount(
+    'replicatedClient',
+    'breakerFailures',
+    options.breakerFailures ?? BREAKER_FAILURES,
+    1,
+  );
+  const cooldown = finiteCount(
+    'replicatedClient',
+    'breakerCooldownMs',
+    options.breakerCooldownMs ?? BREAKER_COOLDOWN_MS,
+    1,
+  );
   let replicaCount = 0;
   let primaryCount = 0;
   let fallbackCount = 0;

package/src/sql.ts

@@ -131,6 +131,42 @@ export function identifier(name: string): SqlFragment {
   return raw(`"${name}"`);
 }
 
+/**
+ * The two characters a shell substitutes INSIDE double quotes. Rejected before `identifier` is
+ * consulted at all, because `identifier` accepts both.
+ */
+const SHELL_ACTIVE = /[`$]/;
+
+/**
+ * A quoted identifier that is ALSO inert wherever a human pastes it — or `null` for a name no line
+ * built here may spell. The one screen a catalog name goes through before it reaches a `fix:`.
+ *
+ * TWO layers, and `identifier` closes only the first. It answers about SQL: it refuses `"`, `\`
+ * and whitespace, and ACCEPTS a backtick and a `$` — `SAFE_IDENTIFIER` above allows `$` on its
+ * fast path — which are exactly the two characters `$(…)` and a command substitution are built
+ * from. A column called `$(id)` inside `x db gen "add $(id)"` therefore RUNS `id` the moment its
+ * reader pastes the line, and a screen reusing `identifier` unchanged would ship a green suite
+ * over that.
+ *
+ * The name is DATA at every caller: `create table "x""; drop table users; --" ("id" int)` is legal
+ * DDL, so whoever can create a table or a column picks the text that lands in a `fix:`. A refusal
+ * is degraded to prose by its caller and never escaped — the argument to `x db gen` is a migration
+ * DESCRIPTION, not an identifier, so there is no quoted form that makes a hostile name safe to
+ * pass, and a fix naming no command beats one running a second command the reader never read.
+ *
+ * `'` is deliberately NOT refused: it is legal in an identifier and inert both in a psql session
+ * and inside shell double quotes. The price of the two that ARE refused is a legal `a$b` losing
+ * its executable fix line, which is prose in place of something nobody read running.
+ */
+export function shellInertIdentifier(name: string): string | null {
+  if (SHELL_ACTIVE.test(name)) return null;
+  try {
+    return identifier(name).text;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * A quoted string literal Postgres reads IDENTICALLY under both settings of
  * `standard_conforming_strings`. Utility and DDL statements (`CREATE DATABASE`, `COMMENT ON`,