@ultimat3/db 16.0.0 → 18.0.0

package/src/client.ts

@@ -1,19 +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).
-
-import { type Role, renderThrowable, resolveRole } from '@ultimat3/core';
-import { statementAttribution } from './attribution';
+// Single responsibility: the pooled Postgres client and the ambient `db()` handle — the lazy
+// connect, 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` and the observed statement funnel in `statement-funnel.ts`, so
+// importing this module never opens a socket.
+
+import { type Role, resolveRole } from '@ultimat3/core';
+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 { expectedQueryLoopReason } from './expected-loop';
-import { declaresLibpqOption, mergeLibpqOptions } from './libpq-options';
-import { statementObserver } from './observe';
+import { DbError, driverError } from './errors';
+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 { affectedBy, rowsOf, runOn } from './statement-funnel';
 import { currentTx } from './transaction';
 
 export interface DbClient {
@@ -41,123 +42,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,103 +49,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[]) : [];
-}
-
-// The command tag only when it counted something, exactly like `rowsOf` in `pglite.ts` — one rule
-// across both drivers, so `execute()` and the observer's event cannot answer differently for the
-// same statement depending on which database is behind them. A driver that tags a read `0` while
-// returning rows would otherwise report 0 here and the row count there.
-function affectedBy(result: unknown): number {
-  if (!Array.isArray(result)) return 0;
-  const count = (result as { count?: unknown }).count;
-  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 +58,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 {
@@ -282,76 +72,6 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
     return driver;
   }
 
-  /** The send itself: one statement on one handle, every driver failure typed on the way out. */
-  async function sendOn(
-    driver: Pick<BunSqlDriver, 'unsafe'>,
-    fragment: SqlFragment,
-  ): Promise<unknown> {
-    try {
-      return await driver.unsafe(fragment.text, fragment.values);
-    } catch (error) {
-      // `driverError`, not `dbUnavailable`: the SQLSTATE has always been on this error and nothing
-      // read it, so a `23505` from two clicks racing a signup told the operator the database was
-      // unreachable and paged on-call for an outage that never happened. Everything the table does
-      // not classify is still `X_DB_UNAVAILABLE`, byte for byte.
-      throw driverError(`statement failed: ${fragment.text.slice(0, 120)}`, error);
-    }
-  }
-
-  /**
-   * The funnel — pooled and pinned statements both arrive here, which is why the observer hangs
-   * off this one function and nowhere else. Uninstalled it costs one property read and one
-   * branch: no clock read, no span, no event object, and `sendOn` receives exactly the call `runOn`
-   * made before the seam existed (axiom 6).
-   */
-  async function runOn(
-    driver: Pick<BunSqlDriver, 'unsafe'>,
-    fragment: SqlFragment,
-  ): Promise<unknown> {
-    const observer = statementObserver();
-    if (observer === undefined) return sendOn(driver, fragment);
-    // Read here, not by the consumer: the scope is gone by the time a per-request detector judges
-    // what it collected, so the reason has to be captured with the statement it defends.
-    const expected = expectedQueryLoopReason();
-    // Same moment, same argument: `postgresRepo` is several frames and a microtask above this one,
-    // and what it knows — the entity and the operation — is what turns fifty identical `select`s
-    // into "50× findById on members". Absent for hand-written SQL, a migration, a health probe.
-    const attribution = statementAttribution();
-    const started = performance.now();
-    let result: unknown;
-    try {
-      // The span wraps the send and nothing else, so its duration is the statement's and the
-      // observer's own work is not charged to the database.
-      result = await withStatementSpan(fragment.text, () => sendOn(driver, fragment));
-    } catch (error) {
-      // A statement that failed is still a statement: fifty identical timeouts are an N+1 of
-      // timeouts. The error is already `X_DB_UNAVAILABLE`, so the event carries what the caller
-      // is about to be thrown — and an observer that throws here replaces it, which is why
-      // `observe.ts` says a reporting-only observer must not throw.
-      observer.onStatement({
-        text: fragment.text,
-        values: fragment.values,
-        durationMs: performance.now() - started,
-        rows: 0,
-        error,
-        attribution,
-        expected,
-      });
-      throw error;
-    }
-    // Outside the `try` deliberately: a throw from `onStatement` is the observer's, not the
-    // database's, and catching it above would report a statement that succeeded as failed.
-    observer.onStatement({
-      text: fragment.text,
-      values: fragment.values,
-      durationMs: performance.now() - started,
-      rows: affectedBy(result),
-      attribution,
-      expected,
-    });
-    return result;
-  }
-
   async function run(fragment: SqlFragment): Promise<unknown> {
     return runOn(connect(), fragment);
   }
@@ -455,27 +175,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,102 @@
+// 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 { DbError, 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;
+}
+
+/**
+ * The schemes on which `Bun.SQL` opens a POSTGRES connection — measured against bun 1.4.0, never
+ * assumed. `postgres:` and `postgresql:` both answer `adapter: 'postgres'`; `pg:`, `tcp:` and
+ * `postgresql+ssl:` are refused by the driver itself (`Unsupported protocol: … Supported adapters:
+ * "postgres", "sqlite", "mysql", "mariadb"`), so excluding them costs a capability nobody has.
+ * The two that matter are the ones the driver ACCEPTS and this package cannot speak: `mysql:`,
+ * `mariadb:`, `sqlite:` and `file:` open a different engine, and every statement generated here is
+ * Postgres — a pool that connects and then answers a syntax error to the migration is strictly
+ * worse than one that refuses at boot.
+ */
+const POSTGRES_SCHEMES: ReadonlySet<string> = new Set(['postgres:', 'postgresql:']);
+
+/**
+ * The received scheme is deliberately NOT named, which is the one place this refusal differs from
+ * every other "errors are instructions" case in the package. `new URL()` accepts a scheme-less
+ * string by reading the first token as the scheme, and that token is exactly the value this must
+ * not echo: `db.internal:5432/app` parses with `db.internal:` — the HOST — as its protocol, and
+ * `app:hunter2@db.internal/app`, the same typo copied one dashboard field over, parses with the
+ * USERNAME as its protocol. Naming "the scheme" therefore puts a host or a credential in the boot
+ * log AND the `--json` payload, where the logger has no key left to redact it by (see the block in
+ * the parse `catch` below). The REQUIRED scheme is a constant and carries the whole instruction, so
+ * nothing actionable is lost by withholding the received one; `describeValue` keeps the shape, so
+ * an empty variable is still told apart from a truncated one.
+ */
+const schemeUnsupported = (raw: string): DbError =>
+  new DbError({
+    code: 'X_DB_UNAVAILABLE',
+    cause:
+      'DATABASE_URL does not name a postgres:// or postgresql:// url: ' +
+      `received ${describeValue(raw)}`,
+    fix:
+      'set DATABASE_URL to postgres://user@host:5432/database — a value with no scheme parses ' +
+      'as a url whose scheme is its own first token — or run `x dev` to use the embedded PGlite',
+  });
+
+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);
+  }
+  // Screened here because `Bun.SQL` will not screen it: measured on bun 1.4.0, it reads
+  // `db.internal:5432/app` as host `db.internal`, port 5432, database `app` and opens a Postgres
+  // pool on it, so the first symptom is a connect failure at the first QUERY, in another process
+  // phase, worded by the driver and naming neither `DATABASE_URL` nor the missing scheme. Worse,
+  // `sqlite://./dev.db` succeeds outright on a different engine. A boot-time refusal is the only
+  // point at which the value is still nameable.
+  if (!POSTGRES_SCHEMES.has(url.protocol)) throw schemeUnsupported(raw);
+  // 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 },
+  });