@ultimat3/db 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# @ultimat3/db 🐘
+
+Postgres access for Ultimate: parameterised SQL, transactions, migrations, drift detection,
+branch databases, and a read-only client for anything an LLM drives.
+
+Tier 1. Imports `@ultimat3/core` only. No runtime dependencies; `@electric-sql/pglite` is an
+**optional peer**, loaded at first query and only by the embedded driver. **No ORM backs any of
+this** — `@ultimat3/entity`'s hand-written `postgresDriver()` compiles every statement out of the
+`sql` / `identifier` / `join` fragments below; this package declares the narrow structural types it
+consumes (`DbClient`, `SqlFragment`, `EntityDescriptionLike`) so the SQL stays readable and the
+boundary stays thin.
+
+## Public API
+
+```ts
+import { db, sql, raw, withTransaction, currentTx, readOnly, setDbClient } from '@ultimat3/db';
+
+const rows = await db().query<Post>(sql`select * from posts where org_id = ${orgId}`);
+
+await withTransaction(async (tx) => {
+  await tx.execute(sql`update posts set likes = likes + 1 where id = ${id}`);
+  tx.onRollback(() => cache.restore(id));      // fires in reverse order on rollback
+}, { isolation: 'serializable', readOnly: false });
+```
+
+| Export | |
+|---|---|
+| `sql` / `raw` / `identifier` / `literal` / `join` | fragment builders |
+| `db()` / `baseClient()` / `setDbClient()` | the ambient client; `db()` returns the open tx if any |
+| `withTransaction()` / `currentTx()` | transaction scope; `currentTx()` is the outbox seam |
+| `migrate()` / `rollback()` / `readLedger()` | the `x_migrations` ledger |
+| `checkDrift()` / `diffSchema()` / `assertNoDrift()` | drift, with a `--json` report |
+| `generateMigration()` | `x db gen "<name>"` — reversible up/down SQL |
+| `introspect()` | live schema → `SchemaDescription` |
+| `createBranch()` / `dropBranch()` / `reapBranches()` | copy-on-write branch databases |
+| `createPgliteClient()` / `branchPglite()` | the embedded database — Postgres in this process |
+| `readOnly()` | mutation-rejecting wrapper |
+| `ensureReadOnlyRole()` / `grantReadOnlySql()` / `READONLY_ROLE` | a `NOLOGIN`, SELECT-only Postgres role — layer 1 of `db.query`'s defence |
+| `readOnlyQuery()` / `READONLY_TIMEOUT_MS` | one statement inside `BEGIN READ ONLY` with a statement timeout — layer 2 |
+| `createRecordingClient()` | in-memory `DbClient` that records SQL, for tests |
+
+## `sql` is parameters-only
+
+String interpolation is how every SQL injection ships, and an agent writing SQL cannot be
+trusted to remember the difference between a value and a fragment. So:
+
+- scalars (`string`, `number`, `boolean`, `bigint`, `Date`, `Uint8Array`, arrays, `null`) become
+  `$1..$n` and never touch `.text`;
+- a nested fragment is spliced and its parameters are renumbered;
+- **anything else throws `X_SQL_UNSAFE`** — including an object shaped like a `SqlFragment` that
+  `sql`/`raw` did not produce;
+- `raw(trusted)` is the one audited escape hatch, `identifier(name)` the safe way to interpolate
+  a table or column, `literal(text)` for utility statements that reject bound parameters.
+
+## Read-only access for anything an LLM drives
+
+`As of 2026-07`: a bug in one defence must not become a write, so `db.query` on the MCP dev
+server stacks independent layers rather than trusting a single gate. This package owns the two
+layers that are Postgres facts rather than MCP facts — the tool-boundary layers (pre-parse scan,
+policy) live above it, and `@ultimat3/mcp` never imports this package directly.
+
+```ts
+import { ensureReadOnlyRole, readOnlyQuery } from '@ultimat3/db';
+
+const role = await ensureReadOnlyRole(db());                   // layer 1, once at boot
+const { rows, guards } = await readOnlyQuery(statement, { role }); // layer 2, per statement
+```
+
+| Layer | Export | |
+|---|---|---|
+| 1 | `ensureReadOnlyRole()` | idempotent DDL (`grantReadOnlySql()`) for `READONLY_ROLE`, a `NOLOGIN` role granted `SELECT` on every table and nothing else. Returns `null` instead of throwing when the connection cannot create or grant roles — a managed Postgres where the app user isn't a role admin |
+| 2 | `readOnlyQuery()` | runs one statement inside `BEGIN READ ONLY`, assumes `role` via `SET LOCAL ROLE` when given one, bounds it with `SET LOCAL statement_timeout` (`READONLY_TIMEOUT_MS` default, `timeoutMs: 0` to disable), and always exits via `ROLLBACK` |
+
+`readOnlyQuery()` reports which guards actually engaged (`result.guards`, e.g. `['txn:read-only',
+'timeout:5000ms', 'role:ultimate_readonly']`) instead of assuming every layer held — a silently
+degraded layer is a caller's problem to surface, never this package's to hide.
+
+Only layer 1 degrades. `readOnlyQuery()` **throws** — a pool that cannot reserve a connection
+(`X_DB_UNAVAILABLE`), a refused `SET LOCAL ROLE`, a failed transaction command, or the
+statement's own error. Every caller handles that failure; nothing here swallows it.
+
+`ALTER DEFAULT PRIVILEGES` is scoped to whoever creates an object, so pass
+`creators: ['migrator']` when migrations run as a different DB user than the one that ran
+`ensureReadOnlyRole()` — otherwise a table created later is not selectable by the role, and
+layer 1 covers only what existed at grant time.
+
+## The drift contract
+
+`x db drift` compares `introspect()` against the snapshot the newest applied migration carries.
+Rendered output is pinned byte-for-byte:
+
+```
+X_DB_DRIFT: schema differs from migrations
+  cause: table "posts" has column "publish_at" not present in any migration
+  fix:   x db gen "add publish_at"
+```
+
+| Difference | cause | fix |
+|---|---|---|
+| live column, no migration | `table "T" has column "C" not present in any migration` | `x db gen "add C"` |
+| 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"` |
+| migrated table, not live | `table "T" is declared by migrations but does not exist` | `x db migrate` |
+
+`checkDrift()` returns every difference; `assertNoDrift()` throws the first. `x verify` fails on it.
+
+## The embedded database
+
+No `DATABASE_URL` means no Docker: `createPgliteClient()` runs Postgres as WASM inside this
+process. The module is resolved on the first statement, never at import, so an image that only
+ever talks to a managed Postgres never loads it.
+
+```ts
+const dev = createPgliteClient({ dataDir: pgliteDataDir(services.db.url) });  // or memory://
+await dev.ping();                                       // pay the ~3s boot before serving
+setDbClient(dev);
+
+const branch = await branchPglite('feature_x', { from: '.x/pgdata' });
+setDbClient(createPgliteClient({ dataDir: branch.dataDir }));
+```
+
+PGlite has no `CREATE DATABASE ... TEMPLATE`, so `branchPglite()` copies the data directory —
+close the source first, and expect `X_NOT_IMPLEMENTED` on `memory://`, which has no directory to
+copy. Branch names go through the same `assertBranchName()` as the Postgres path: here the name
+lands in a filesystem path, so an unvalidated one is traversal rather than a typo.
+
+### One session, so callers take turns
+
+Embedded Postgres is a single session, not a pool. `createPgliteClient()` is therefore
+`ReservableClient`: `withTransaction()` and `readOnlyQuery()` pin it, and every other statement
+waits for its turn. Without that pin two concurrent units of work each run `BEGIN` on the same
+connection — the second `COMMIT` commits the first's rows and the first `ROLLBACK` finds no
+transaction left to undo.
+
+| On a pooled server | Embedded, on one session |
+|---|---|
+| concurrent transactions run side by side | they run consecutively; throughput is one at a time |
+| a statement outside a transaction gets its own connection | it waits for the open transaction to finish |
+| `enqueue(input, { outbox: false })` inside a transaction survives its rollback | it joins that transaction, and rolls back with it |
+
+The last row is the one divergence a second connection would remove and PGlite cannot: a statement
+issued *inside* an open transaction's scope runs immediately rather than waiting for a turn that
+scope is already holding, because waiting would be a deadlock with no error to explain it.
+
+## Pool sizing by role
+
+`ROLE` picks the profile — a `worker` draining a queue must not size like a `web` process.
+
+| Role | max | statement timeout | idle timeout |
+|---|---|---|---|
+| `web` | 20 | 10s | 30s |
+| `sync` | 10 | 10s | 60s |
+| `worker` | 8 | 120s | 30s |
+| `scheduler` | 2 | 15s | 60s |
+| `migrate` | 1 | none | 10s |
+| `replicator` | 4 | none | 60s |
+
+The timeout is pinned per connection via libpq `options=-c statement_timeout=`. `Bun.SQL` is
+reached lazily, so importing this package never opens a socket.
+
+## Migrations
+
+`migrate()` takes an advisory lock (`pg_advisory_lock(4919202607)`), ensures `x_migrations`
+(`id, name, checksum, applied_at, app_version, duration_ms`), audits, then applies each pending
+migration inside its own transaction. It refuses **before applying anything** when:
+
+- the ledger records a migration this build does not ship **and** its `app_version` differs from
+  the running one — another version owns the database; or
+- an applied migration's `up` SQL no longer matches its recorded checksum.
+
+Report (`--json`): `{ applied: [{ id, name, durationMs }], skipped: [id], durationMs, appVersion }`.
+
+## Error codes
+
+| Code | Meaning |
+|---|---|
+| `X_DB_UNAVAILABLE` | no reachable database; `fix:` names `DATABASE_URL` |
+| `X_DB_DRIFT` | live schema differs from migrations |
+| `X_MIGRATION_CONFLICT` | ledger app-version fence or checksum mismatch |
+| `X_MIGRATION_IRREVERSIBLE` | generated `down` would lose data |
+| `X_SQL_UNSAFE` | non-bindable interpolation, or an unsafe identifier/branch name |
+| `X_BRANCH_EXISTS` | branch database already exists (or is the connected one) |
+| `X_READONLY_VIOLATION` | a mutating statement reached a `readOnly()` client |
+| `X_NOT_IMPLEMENTED` | branching an in-memory PGlite — a copy needs a directory |
+
+```bash
+x db migrate --json
+x db drift --json
+x db gen "add publish_at"
+x db branch create feature_x
+```

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@ultimat3/db",
+  "version": "1.0.0",
+  "description": "Postgres access, transactions, migrations and drift detection",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/db"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "1.0.0"
+  },
+  "peerDependencies": {
+    "@electric-sql/pglite": ">=0.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    }
+  }
+}

package/src/branch.ts

@@ -0,0 +1,136 @@
+// Single responsibility: copy-on-write branch databases. `CREATE DATABASE ... TEMPLATE` gives an
+// agent (or a preview environment) a private copy in seconds, so destructive work — a migration
+// it is unsure about, a data backfill, a DROP — never happens against the shared database.
+// Branches are cheap and forgettable, so `reapBranches()` is part of the design, not an add-on.
+
+import { baseClient, type DbClient } from './client';
+import { branchExists, branchNameInvalid, DbError } from './errors';
+import { identifier, literal, sql } from './sql';
+
+const BRANCH_NAME = /^[a-z0-9_-]+$/;
+
+/** Written as a database comment at creation time — `pg_database` has no created_at. */
+const BRANCH_MARKER = 'ultimate:branch:';
+
+export interface BranchInfo {
+  readonly name: string;
+  readonly createdAt: string | null;
+  readonly sizeBytes: number;
+}
+
+export function assertBranchName(branch: string): string {
+  if (!BRANCH_NAME.test(branch)) throw branchNameInvalid(branch);
+  return branch;
+}
+
+export interface BranchOptions {
+  readonly client?: DbClient | undefined;
+  /** The database to copy. Defaults to the current one. */
+  readonly base?: string | undefined;
+  readonly now?: Date | undefined;
+}
+
+async function exists(client: DbClient, branch: string): Promise<boolean> {
+  const row = await client.one<{ ok: number }>(
+    sql`select 1 as ok from pg_database where datname = ${branch}`,
+  );
+  return row !== null;
+}
+
+/**
+ * `CREATE DATABASE` cannot run inside a transaction and needs no other session connected to the
+ * template, so this deliberately runs statement-by-statement on the ambient client.
+ */
+export async function createBranch(
+  branch: string,
+  options: BranchOptions = {},
+): Promise<BranchInfo> {
+  const client = options.client ?? baseClient();
+  assertBranchName(branch);
+  if (await exists(client, branch)) throw branchExists(branch);
+
+  const base = options.base ?? (await currentDatabase(client));
+  await client.execute(sql`create database ${identifier(branch)} template ${identifier(base)}`);
+  const createdAt = (options.now ?? new Date()).toISOString();
+  await client.execute(
+    sql`comment on database ${identifier(branch)} is ${literal(`${BRANCH_MARKER}${createdAt}`)}`,
+  );
+  return { name: branch, createdAt, sizeBytes: 0 };
+}
+
+export async function currentDatabase(client: DbClient = baseClient()): Promise<string> {
+  const row = await client.one<{ name: string }>(sql`select current_database() as name`);
+  return row?.name ?? 'postgres';
+}
+
+interface BranchRow {
+  readonly name: string;
+  readonly comment: string | null;
+  readonly size_bytes: string | number;
+}
+
+export async function listBranches(options: BranchOptions = {}): Promise<readonly BranchInfo[]> {
+  const client = options.client ?? baseClient();
+  const rows = await client.query<BranchRow>(sql`
+    select
+      d.datname as name,
+      shobj_description(d.oid, 'pg_database') as comment,
+      pg_database_size(d.datname) as size_bytes
+    from pg_database d
+    where not d.datistemplate
+    order by d.datname
+  `);
+  return rows
+    .filter((row) => row.comment?.startsWith(BRANCH_MARKER) === true)
+    .map((row) => ({
+      name: row.name,
+      createdAt: row.comment?.slice(BRANCH_MARKER.length) ?? null,
+      sizeBytes: Number(row.size_bytes),
+    }));
+}
+
+export interface DropBranchOptions extends BranchOptions {
+  /** Disconnect other sessions first. Without it Postgres refuses while anyone is connected. */
+  readonly force?: boolean | undefined;
+}
+
+export async function dropBranch(
+  branch: string,
+  options: DropBranchOptions = {},
+): Promise<boolean> {
+  const client = options.client ?? baseClient();
+  assertBranchName(branch);
+  if (branch === (await currentDatabase(client))) {
+    throw new DbError({
+      code: 'X_BRANCH_EXISTS',
+      cause: `"${branch}" is the database this session is connected to, so it cannot be dropped`,
+      fix: 'connect to another database (DATABASE_URL=.../postgres) and drop it from there',
+      meta: { branch },
+    });
+  }
+  if (options.force === true) {
+    await client.execute(sql`
+      select pg_terminate_backend(pid) from pg_stat_activity where datname = ${branch}
+    `);
+  }
+  const affected = await client.execute(sql`drop database if exists ${identifier(branch)}`);
+  return affected >= 0;
+}
+
+export interface ReapOptions extends DropBranchOptions {
+  readonly maxAgeMs: number;
+}
+
+/** Preview environments leak branches; this is what the nightly `reapBranches` task calls. */
+export async function reapBranches(options: ReapOptions): Promise<readonly string[]> {
+  const cutoff = (options.now ?? new Date()).getTime() - options.maxAgeMs;
+  const branches = await listBranches(options);
+  const dropped: string[] = [];
+  for (const branch of branches) {
+    if (branch.createdAt === null) continue;
+    if (new Date(branch.createdAt).getTime() > cutoff) continue;
+    await dropBranch(branch.name, options);
+    dropped.push(branch.name);
+  }
+  return dropped;
+}

package/src/client.ts

@@ -0,0 +1,237 @@
+// 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, resolveRole } from '@ultimat3/core';
+import { dbUnavailable } from './errors';
+import { type SqlFragment, sql } from './sql';
+import { currentTx } from './transaction';
+
+export interface DbClient {
+  query<T>(fragment: SqlFragment): Promise<readonly T[]>;
+  one<T>(fragment: SqlFragment): Promise<T | null>;
+  /** Rows affected. */
+  execute(fragment: SqlFragment): Promise<number>;
+}
+
+/** A connection pinned out of the pool. `withTransaction` needs one so BEGIN/COMMIT agree. */
+export interface DbConnection extends DbClient {
+  release(): void;
+}
+
+export interface ReservableClient extends DbClient {
+  reserve(): Promise<DbConnection>;
+}
+
+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;
+}
+
+/** Sized per role because the failure modes differ: RPS bursts vs. queue depth vs. run-once. */
+export const POOL_PROFILES: Readonly<Record<Role, PoolProfile>> = Object.freeze({
+  web: { max: 20, statementTimeoutMs: 10_000, idleTimeoutMs: 30_000 },
+  sync: { max: 10, statementTimeoutMs: 10_000, idleTimeoutMs: 60_000 },
+  worker: { max: 8, statementTimeoutMs: 120_000, idleTimeoutMs: 30_000 },
+  scheduler: { max: 2, statementTimeoutMs: 15_000, idleTimeoutMs: 60_000 },
+  migrate: { max: 1, statementTimeoutMs: 0, idleTimeoutMs: 10_000 },
+  replicator: { max: 4, statementTimeoutMs: 0, idleTimeoutMs: 60_000 },
+});
+
+export function poolProfileFor(role: Role = resolveRole()): PoolProfile {
+  return POOL_PROFILES[role];
+}
+
+/** 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;
+  readonly profile?: Partial<PoolProfile> | undefined;
+  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.
+  if (profile.statementTimeoutMs > 0) {
+    url.searchParams.set('options', `-c statement_timeout=${profile.statementTimeoutMs}`);
+  }
+  url.searchParams.set('application_name', options.applicationName ?? 'ultimate');
+  return url.toString();
+}
+
+function rowsOf<T>(result: unknown): readonly T[] {
+  return Array.isArray(result) ? (result as readonly T[]) : [];
+}
+
+function affectedBy(result: unknown): number {
+  if (!Array.isArray(result)) return 0;
+  const count = (result as { count?: unknown }).count;
+  return typeof count === 'number' ? count : result.length;
+}
+
+export interface PostgresClient extends ReservableClient {
+  readonly profile: PoolProfile;
+  ping(): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** 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 ?? {}) };
+  let driver: BunSqlDriver | undefined;
+
+  function connect(): BunSqlDriver {
+    if (driver !== undefined) return driver;
+    const url = connectionUrl(options, profile);
+    const Factory = bunSqlFactory();
+    driver = new Factory(url, { max: profile.max, idleTimeout: profile.idleTimeoutMs / 1000 });
+    return driver;
+  }
+
+  async function runOn(
+    driver: Pick<BunSqlDriver, 'unsafe'>,
+    fragment: SqlFragment,
+  ): Promise<unknown> {
+    try {
+      return await driver.unsafe(fragment.text, fragment.values);
+    } catch (error) {
+      throw dbUnavailable(`statement failed: ${fragment.text.slice(0, 120)}`, error);
+    }
+  }
+
+  async function run(fragment: SqlFragment): Promise<unknown> {
+    return runOn(connect(), fragment);
+  }
+
+  const client: PostgresClient = {
+    profile,
+    async query<T>(fragment: SqlFragment): Promise<readonly T[]> {
+      return rowsOf<T>(await run(fragment));
+    },
+    async one<T>(fragment: SqlFragment): Promise<T | null> {
+      const rows = rowsOf<T>(await run(fragment));
+      return rows[0] ?? null;
+    },
+    async execute(fragment: SqlFragment): Promise<number> {
+      return affectedBy(await run(fragment));
+    },
+    async reserve(): Promise<DbConnection> {
+      // A real pin, not a seam: `Bun.SQL` refuses a bare BEGIN on a pooled handle
+      // (`ERR_POSTGRES_UNSAFE_TRANSACTION`), and a BEGIN that landed on a different connection
+      // than the statement after it would not be a transaction at all — which is exactly what
+      // `withTransaction` and `readOnlyQuery` depend on being true.
+      const pool = connect();
+      let reserved: BunSqlReserved;
+      try {
+        reserved = await pool.reserve();
+      } catch (error) {
+        // Acquiring the pin is the one step that runs outside `runOn`, so an exhausted or
+        // unreachable pool would escape as an untyped driver error — and `readOnlyQuery` reaches
+        // this line before its first statement, which is how MCP ends up returning something
+        // other than X_DB_UNAVAILABLE.
+        throw dbUnavailable('could not reserve a connection from the pool', error);
+      }
+      return {
+        query: async <T>(fragment: SqlFragment) => rowsOf<T>(await runOn(reserved, fragment)),
+        one: async <T>(fragment: SqlFragment) =>
+          rowsOf<T>(await runOn(reserved, fragment))[0] ?? null,
+        execute: async (fragment: SqlFragment) => affectedBy(await runOn(reserved, fragment)),
+        release: () => {
+          reserved.release();
+        },
+      };
+    },
+    async ping(): Promise<void> {
+      await client.query(sql`select 1`);
+    },
+    async close(): Promise<void> {
+      await driver?.close();
+      driver = undefined;
+    },
+  };
+  return client;
+}
+
+let ambient: DbClient | undefined;
+
+/** Test/dev seam. `setDbClient(undefined)` restores lazy construction from `DATABASE_URL`. */
+export function setDbClient(client: DbClient | undefined): void {
+  ambient = client;
+}
+
+/** The pool, ignoring any open transaction. `withTransaction` must not re-enter `db()`. */
+export function baseClient(): DbClient {
+  if (ambient === undefined) ambient = createPostgresClient();
+  return ambient;
+}
+
+/**
+ * The ambient client. Inside `withTransaction` this is the transaction, so a repository
+ * written against `db()` joins the caller's transaction without knowing it exists.
+ */
+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),
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}