@ultimat3/db 1.2.0 → 3.0.0

package/src/sqlstate.ts

@@ -0,0 +1,107 @@
+// Single responsibility: what the *database* said went wrong. One reader for the SQLSTATE a driver
+// error carries and one closed table from the states this framework can act on to a code. Two
+// drivers spell the field differently, so the read lives here once — a second copy is a second
+// answer to "is this a unique violation".
+
+import { stringField } from '@ultimat3/core';
+
+/**
+ * The SQLSTATEs the framework names. A closed list on purpose: a table enumerating all ~250 of
+ * Postgres' classes would be a second copy of the manual, and every entry here has a `fix:` an
+ * operator can run. Everything absent is `X_DB_UNAVAILABLE`, which is the honest answer to "the
+ * database said something we have no instruction for".
+ */
+export const SQLSTATE = Object.freeze({
+  /** `undefined_table` — the ledger's absence is a class, not a message to match on. */
+  undefinedTable: '42P01',
+  uniqueViolation: '23505',
+  foreignKeyViolation: '23503',
+  serializationFailure: '40001',
+  deadlockDetected: '40P01',
+  /** `query_canceled` — what `statement_timeout` raises. */
+  queryCanceled: '57014',
+  /** `lock_not_available` — what `lock_timeout` raises while a DDL statement queues. */
+  lockNotAvailable: '55P03',
+  tooManyConnections: '53300',
+  outOfMemory: '53200',
+} as const);
+
+/** Five characters, digits and uppercase letters — `42P01`, never `ERR_POSTGRES_SERVER_ERROR`. */
+const SQLSTATE_SHAPE = /^[0-9A-Z]{5}$/;
+
+/** How deep a wrap may nest before we stop looking. `DbError` adds exactly one level. */
+const MAX_WRAPS = 4;
+
+/** A field off a value that may fight being read — `stringField`'s shape, for a non-string. */
+function unknownField(value: unknown, key: string): unknown {
+  if (typeof value !== 'object' || value === null) return undefined;
+  try {
+    return (value as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The SQLSTATE a driver error carries, unwrapping `DbError.sourceError` on the way, or `undefined`
+ * when the failure never reached the server — a refused socket, a closed pool, a DNS miss.
+ *
+ * **`errno` is read before `code`, and that ordering is the bug this function fixes.** Measured on
+ * bun 1.3.14 against Postgres 17: `Bun.SQL` puts `ERR_POSTGRES_SERVER_ERROR` on `code` and the
+ * SQLSTATE on `errno`, while PGlite — node-postgres' protocol — puts the SQLSTATE on `code` and
+ * has no `errno` at all. Reading `code` alone is correct on the embedded driver and wrong on every
+ * production one, which is exactly the split `isLedgerMissing` was living on.
+ *
+ * The shape test is what keeps the two apart: `ERR_POSTGRES_SERVER_ERROR` and `X_DB_UNAVAILABLE`
+ * are not five characters of `[0-9A-Z]`, and no SQLSTATE contains an underscore.
+ */
+export function sqlState(error: unknown): string | undefined {
+  let value = error;
+  for (let depth = 0; depth < MAX_WRAPS; depth += 1) {
+    if (value === undefined || value === null) return undefined;
+    const errno = stringField(value, 'errno');
+    if (errno !== undefined && SQLSTATE_SHAPE.test(errno)) return errno;
+    const code = stringField(value, 'code');
+    if (code !== undefined && SQLSTATE_SHAPE.test(code)) return code;
+    value = unknownField(value, 'sourceError');
+  }
+  return undefined;
+}
+
+/** The codes a SQLSTATE can classify into. `errors.ts` owns their titles and their fixes. */
+export type DbSqlStateCode =
+  | 'X_DB_UNIQUE_VIOLATION'
+  | 'X_DB_FOREIGN_KEY_VIOLATION'
+  | 'X_DB_SERIALIZATION_FAILURE'
+  | 'X_DB_STATEMENT_TIMEOUT'
+  | 'X_DB_LOCK_TIMEOUT'
+  | 'X_DB_POOL_EXHAUSTED';
+
+/**
+ * SQLSTATE to code, closed. `40P01` (deadlock) joins `40001` because the instruction is identical
+ * — re-run the whole transaction — and a caller branching on which of the two it lost to would be
+ * writing the same retry twice. `53200` (out_of_memory) joins `53300` for the same reason: both are
+ * class 53, insufficient resources, and both are answered by asking for fewer connections.
+ */
+export const DB_SQLSTATE_CODES: Readonly<Record<string, DbSqlStateCode>> = Object.freeze({
+  [SQLSTATE.uniqueViolation]: 'X_DB_UNIQUE_VIOLATION',
+  [SQLSTATE.foreignKeyViolation]: 'X_DB_FOREIGN_KEY_VIOLATION',
+  [SQLSTATE.serializationFailure]: 'X_DB_SERIALIZATION_FAILURE',
+  [SQLSTATE.deadlockDetected]: 'X_DB_SERIALIZATION_FAILURE',
+  [SQLSTATE.queryCanceled]: 'X_DB_STATEMENT_TIMEOUT',
+  [SQLSTATE.lockNotAvailable]: 'X_DB_LOCK_TIMEOUT',
+  [SQLSTATE.tooManyConnections]: 'X_DB_POOL_EXHAUSTED',
+  [SQLSTATE.outOfMemory]: 'X_DB_POOL_EXHAUSTED',
+} as const);
+
+/** `undefined` when the state is unknown or absent — the caller then reports unavailability. */
+export function sqlStateCode(error: unknown): DbSqlStateCode | undefined {
+  const state = sqlState(error);
+  return state === undefined ? undefined : DB_SQLSTATE_CODES[state];
+}
+
+/** Whether re-running the whole transaction is the documented answer. `withTransaction`'s retry. */
+export function isRetryableState(error: unknown): boolean {
+  const state = sqlState(error);
+  return state === SQLSTATE.serializationFailure || state === SQLSTATE.deadlockDetected;
+}

package/src/statement-shape.ts

@@ -0,0 +1,58 @@
+// Single responsibility: what shape a statement is — the verb it opens with, whether that verb
+// writes, and the identity repeated statements are counted under. Two detectors above this package
+// group statements by that identity (`x dev`'s ledger, the `statements` test fixture) and a third
+// names spans from the same verb, so the rule lives once, next to the `StatementEvent` it reads.
+// Nothing here counts anything: a threshold is a verdict's, and a verdict is `@ultimat3/entity`'s.
+
+import type { StatementEvent } from './observe';
+
+const LEADING_WORD = /^[A-Za-z]+/;
+const WHITESPACE = /\s+/g;
+
+/**
+ * The first word, lowercased — `select`, `insert`, `begin` — and `''` when a statement opens with
+ * anything else. A text opening with a comment or a parenthesis has no verb, deliberately: this is
+ * the one word every statement carries, and stripping comments to find a later one would be a
+ * second reading of the SQL — `sql-noise.ts` is the one blanker — for the sake of one label.
+ */
+export function statementVerb(text: string): string {
+  return (LEADING_WORD.exec(text.trimStart())?.[0] ?? '').toLowerCase();
+}
+
+/**
+ * The verbs that make a statement a write. A set of verbs and not a set of repository operations:
+ * a soft delete is an `update`, an op list would drift with `@ultimat3/entity`'s method names, and
+ * hand-written SQL carries no operation at all.
+ */
+const WRITE_VERBS: ReadonlySet<string> = new Set([
+  'insert',
+  'update',
+  'delete',
+  'upsert',
+  'merge',
+  'truncate',
+  'copy',
+]);
+
+/**
+ * Read or write, decided from the statement rather than from the operation above it, for the same
+ * reason `statementSpanName` reads the verb: it is the one fact every statement carries, attributed
+ * or not. A statement opening with a CTE reads as a read — naming `insertAll` in a fix for a loop
+ * of `with … select` would be wrong more often than naming `preload` for a loop that writes.
+ */
+export function statementKind(text: string): 'read' | 'write' {
+  return WRITE_VERBS.has(statementVerb(text)) ? 'write' : 'read';
+}
+
+/**
+ * The identity a loop repeats. An attributed statement groups by `entity.op`, because
+ * `members.findById` fifty times is the report an author can act on and the SQL is one sample of
+ * it — which is the whole reason `withStatementAttribution` exists. Everything else groups by its
+ * own text, already `$n`-parameterized by `sql()`, with whitespace collapsed so a builder that
+ * indents differently between two calls is still one shape rather than two.
+ */
+export function statementFingerprint(event: StatementEvent): string {
+  const attribution = event.attribution;
+  if (attribution !== undefined) return `${attribution.entity}.${attribution.op}`;
+  return event.text.replace(WHITESPACE, ' ').trim();
+}

package/src/statement-span.ts

@@ -0,0 +1,40 @@
+// Single responsibility: the span one statement is. Named `db.<verb>` because `x dev`'s recorder
+// reads the panel's kind off the prefix, exactly as it does for `query.`, `cache.` and `job.`, and
+// carrying the text as `db.statement` — the attribute the timeline groups on to count an N+1. It is
+// opened on the observed path only, so a process with no diagnostic installed traces what it did
+// before the seam existed.
+
+import { withSpan } from '@ultimat3/core';
+import { statementVerb } from './statement-shape';
+
+/**
+ * OTel's name for the statement itself. Exported because it is a contract across two packages, not
+ * a local constant: `packages/cli/src/dev-traces.ts` reads it as a span's detail, so a rename that
+ * only landed here would leave the timeline grouping span names again with every test still green.
+ */
+export const STATEMENT_ATTRIBUTE = 'db.statement';
+
+/**
+ * `db.select`, `db.insert`, `db.begin` — low cardinality on purpose, so the flame reads at a glance
+ * and a trace backend can still aggregate by name. The full text rides on the span, never in it.
+ *
+ * The verb is `statement-shape.ts`'s, the same read the N+1 detectors classify a statement with: a
+ * text with no leading word is `db.statement` here and a read there, one scanner and two labels.
+ */
+export function statementSpanName(text: string): string {
+  const verb = statementVerb(text);
+  return `db.${verb === '' ? 'statement' : verb}`;
+}
+
+/**
+ * Wraps the send, so the span's duration is the statement's and a failure is recorded on it rather
+ * than inferred from the gap after it. `client` is the OTel kind — the database is the remote peer;
+ * the panel's own `sql` kind comes off the name prefix, since `db` is tier 1 and cannot name a
+ * tier-5 vocabulary.
+ */
+export function withStatementSpan<T>(text: string, send: () => Promise<T>): Promise<T> {
+  return withSpan(statementSpanName(text), send, {
+    kind: 'client',
+    attributes: { [STATEMENT_ATTRIBUTE]: text },
+  });
+}

package/src/statement-split.ts

@@ -0,0 +1,51 @@
+// Single responsibility: cut a SQL script into the statements a driver sends one at a time —
+// one send is one statement, or the server answers `cannot insert multiple commands into a
+// prepared statement`. Where a `;` separates and where it is data is `sql-scan.ts`'s answer.
+
+import { noiseAt } from './sql-scan';
+
+const WHITESPACE = /\s/;
+
+const isComment = (kind: string): boolean => kind === 'line-comment' || kind === 'block-comment';
+
+/**
+ * The statements of `script`, in order, each without its separator.
+ *
+ * A chunk holding only whitespace and comments is **not** a statement and is dropped: an empty
+ * `up`, or one whose tail is the `-- backfill …, then: …;` note `generateMigration` emits, would
+ * otherwise reach the driver as an empty query.
+ */
+export function statementsOf(script: string): readonly string[] {
+  const statements: string[] = [];
+  let start = 0;
+  let index = 0;
+  // Set by anything that is not whitespace and not inside a comment: what makes a chunk a
+  // statement rather than a note between two of them.
+  let content = false;
+
+  const cut = (end: number): void => {
+    const text = content ? script.slice(start, end).trim() : '';
+    if (text.length > 0) statements.push(text);
+    content = false;
+  };
+
+  while (index < script.length) {
+    const noise = noiseAt(script, index);
+    if (noise !== null) {
+      if (!isComment(noise.kind)) content = true;
+      index = noise.end;
+      continue;
+    }
+    const char = script[index] ?? '';
+    if (char === ';') {
+      cut(index);
+      start = index + 1;
+      index += 1;
+      continue;
+    }
+    if (!WHITESPACE.test(char)) content = true;
+    index += 1;
+  }
+  cut(script.length);
+  return statements;
+}

package/src/transaction.ts

@@ -4,12 +4,33 @@
 // to SAVEPOINTs, so an inner failure never silently aborts the outer unit of work.
 
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { nanoid } from '@ultimat3/core';
+import { assert, nanoid } from '@ultimat3/core';
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
+import { serializationExhausted } from './errors';
 import { raw, type SqlFragment } from './sql';
+import { isRetryableState } from './sqlstate';
 
 export interface DbTx extends DbClient {
   readonly id: string;
+  /**
+   * The client this transaction was **opened on** — `options.client`, or `baseClient()`. Not the
+   * reservation the statements run on: what a caller needs to know is which database and which
+   * pool this scope belongs to, and the pin is an implementation detail of that.
+   *
+   * It exists because the answer was unanswerable from above. `@ultimat3/entity`'s repositories
+   * can be pinned to a specific client (`database(shard)`), and a pinned repository inside
+   * `withTransaction` sends its statements to *its own pool* while the `BEGIN` sits on a
+   * connection this scope reserved — so the write commits immediately and survives the rollback,
+   * and reads inside the transaction cannot see it. `withTransaction(fn, { client: shard })` does
+   * not fix it either: the transaction runs on a *reservation* of the shard and the repository
+   * still sends to the pool. With nothing to compare against, tier 2's only honest answer was to
+   * refuse (`X_REPO_CLIENT_PINNED`). `tx.origin === thePinnedClient` turns that refusal into the
+   * case working — the repository joins its own shard's transaction — and leaves the refusal for
+   * what it should always have been: a genuine mix of two databases in one scope.
+   *
+   * A nested scope reports the root's, because a SAVEPOINT belongs to the transaction that opened.
+   */
+  readonly origin: DbClient;
   /** Fired in reverse registration order when this scope rolls back. Never on commit. */
   onRollback(undo: () => void): void;
 }
@@ -23,6 +44,21 @@ export interface TransactionOptions {
   readonly deferrable?: boolean | undefined;
   /** Override the ambient pool — tests and `x db branch` run against a specific client. */
   readonly client?: DbClient | undefined;
+  /**
+   * Extra attempts after a `40001`/`40P01`, and **only** after one. Default 0, so adding the option
+   * changed no existing transaction's behaviour (axiom 1) — a retry that ran without being asked
+   * for would silently double every non-idempotent handler in the framework.
+   *
+   * Opt in wherever `isolation: 'serializable'` is set: under SERIALIZABLE a serialization failure
+   * is normal traffic, not an exception, and until this existed a payments team choosing it for
+   * ledger correctness got ~3% of transactions surfacing to the user as "cannot reach the
+   * database" with no way to write their own retry, because nothing distinguished `40001` from a
+   * dead socket.
+   *
+   * **`fn` re-runs from the top, so it must be idempotent** — the same contract `job.handle` has.
+   * `onRollback` undos fire before each retry, in reverse registration order.
+   */
+  readonly retry?: number | undefined;
 }
 
 interface TxState {
@@ -31,6 +67,16 @@ interface TxState {
   readonly undos: (() => void)[];
   /** Shared by reference across nesting levels so savepoint names never collide. */
   readonly savepoints: { value: number };
+  /**
+   * Whether the scope is still OPEN. Shared by reference across nesting for the same reason the
+   * savepoint counter is: a SAVEPOINT lives and dies with the root transaction that opened it.
+   *
+   * Mutable because the store outlives the scope. `AsyncLocalStorage` propagates into every
+   * promise chain started inside `fn`, so a statement the app forgot to `await` still finds this
+   * store long after COMMIT — and a reader that treats the store's PRESENCE as an open
+   * transaction believes a dead one is live.
+   */
+  readonly live: { value: boolean };
 }
 
 const storage = new AsyncLocalStorage<TxState>();
@@ -40,6 +86,19 @@ export function currentTx(): DbTx | undefined {
   return storage.getStore()?.tx;
 }
 
+/**
+ * Is a transaction still OPEN on this async context? A different question from `currentTx() !==
+ * undefined`, which only says a store is present — and the store survives the scope. The one
+ * reader is `pglite.ts`'s `run()`, where the answer decides whether a statement may skip the
+ * single session's turn queue; skipping it on a *closed* transaction is how a straggler landed
+ * inside whichever unit of work held the connection next, committed with it, with nothing to read.
+ * `currentTx()` deliberately still answers with the dead handle: its statements go through the
+ * reservation, whose own `held` fence already re-queues them.
+ */
+export function inLiveTx(): boolean {
+  return storage.getStore()?.live.value === true;
+}
+
 export function beginStatement(options: TransactionOptions): string {
   const modes: string[] = [];
   if (options.isolation !== undefined) {
@@ -50,9 +109,10 @@ export function beginStatement(options: TransactionOptions): string {
   return modes.length === 0 ? 'BEGIN' : `BEGIN ${modes.join(' ')}`;
 }
 
-function makeTx(id: string, connection: DbClient, undos: (() => void)[]): DbTx {
+function makeTx(id: string, connection: DbClient, undos: (() => void)[], origin: DbClient): DbTx {
   return {
     id,
+    origin,
     query: <T>(fragment: SqlFragment) => connection.query<T>(fragment),
     one: <T>(fragment: SqlFragment) => connection.one<T>(fragment),
     execute: (fragment: SqlFragment) => connection.execute(fragment),
@@ -77,7 +137,11 @@ async function runNested<T>(outer: TxState, fn: (tx: DbTx) => Promise<T>): Promi
   outer.savepoints.value += 1;
   const name = `x_sp_${outer.savepoints.value}`;
   const undos: (() => void)[] = [];
-  const tx = makeTx(`${outer.tx.id}/${name}`, outer.connection, undos);
+  const tx = makeTx(`${outer.tx.id}/${name}`, outer.connection, undos, outer.tx.origin);
+  // `SAVEPOINT` and `RELEASE` are deliberately uncaught: a savepoint that was never taken means
+  // this scope never opened, and a release that failed means its work is not durable in the outer
+  // one. Both are the caller's failure to see — swallowing either would run the rest of the unit
+  // of work against a transaction that is not the one it thinks it is in.
   await outer.connection.execute(raw(`SAVEPOINT ${name}`));
   try {
     const result = await storage.run({ ...outer, tx, undos }, () => fn(tx));
@@ -87,38 +151,96 @@ async function runNested<T>(outer: TxState, fn: (tx: DbTx) => Promise<T>): Promi
     outer.undos.push(...undos);
     return result;
   } catch (error) {
-    await outer.connection.execute(raw(`ROLLBACK TO SAVEPOINT ${name}`));
+    // Best-effort, exactly like the root's ROLLBACK: the savepoint is already gone when the
+    // failure was the connection itself, and the caller needs the error that caused the rollback,
+    // never the rollback's own.
+    await outer.connection.execute(raw(`ROLLBACK TO SAVEPOINT ${name}`)).catch(() => undefined);
     runUndos(undos);
     throw error;
   }
 }
 
-export async function withTransaction<T>(
-  fn: (tx: DbTx) => Promise<T>,
-  options: TransactionOptions = {},
-): Promise<T> {
-  const outer = storage.getStore();
-  if (outer !== undefined) return runNested(outer, fn);
-
+/**
+ * One attempt at a root transaction: its own pin, its own BEGIN, its own undo list. Extracted so
+ * the retry loop can re-run it whole — a retry that reused the pin would be re-running against a
+ * connection whose transaction is already gone.
+ */
+async function runRoot<T>(fn: (tx: DbTx) => Promise<T>, options: TransactionOptions): Promise<T> {
   const client = options.client ?? baseClient();
-  const reserved: DbConnection | undefined = isReservable(client)
+  // A pooled BEGIN that lands on a different physical connection than the statements after it is
+  // not a transaction at all, so a reservable client pins one connection for the whole scope.
+  // Held by a `using` declaration rather than a `finally`, because a `finally` only covers what
+  // someone remembered to put in its `try`: BEGIN used to sit above the block, so a rejected BEGIN
+  // returned the pin to nobody — on PGlite, the single session's turn with it, wedging every later
+  // statement in the process. The declaration covers every exit, including the ones nobody wrote.
+  using reserved: DbConnection | undefined = isReservable(client)
     ? await client.reserve()
     : undefined;
   const connection: DbClient = reserved ?? client;
   const undos: (() => void)[] = [];
-  const tx = makeTx(`tx_${nanoid(12)}`, connection, undos);
+  const tx = makeTx(`tx_${nanoid(12)}`, connection, undos, client);
+  // Each attempt gets its own state, and therefore its own `live` — a retry re-runs `fn` against a
+  // transaction that is genuinely new, so the abandoned attempt's stragglers must read as closed.
+  const state: TxState = { tx, connection, undos, savepoints: { value: 0 }, live: { value: true } };
 
-  await connection.execute(raw(beginStatement(options)));
   try {
-    const state: TxState = { tx, connection, undos, savepoints: { value: 0 } };
+    await connection.execute(raw(beginStatement(options)));
     const result = await storage.run(state, () => fn(tx));
     await connection.execute(raw('COMMIT'));
     return result;
   } catch (error) {
+    // Best-effort: the caller needs the original failure, never the rollback's. A BEGIN that
+    // itself failed opened nothing, so this ROLLBACK is a no-op the server answers with a notice.
     await connection.execute(raw('ROLLBACK')).catch(() => undefined);
     runUndos(undos);
     throw error;
   } finally {
-    reserved?.release();
+    // The scope says when it CLOSED, on every exit, because nothing else can: the store it left
+    // behind is indistinguishable from a live one, and `inLiveTx()` is what tells them apart.
+    // Cleared before the `using` pin is given back, so no window exists where a straggler could
+    // still be sent direct at a connection this scope no longer owns.
+    state.live.value = false;
+  }
+}
+
+export async function withTransaction<T>(
+  fn: (tx: DbTx) => Promise<T>,
+  options: TransactionOptions = {},
+): Promise<T> {
+  const outer = storage.getStore();
+  if (outer !== undefined) {
+    // A nested scope is a SAVEPOINT, and a savepoint cannot survive the thing `retry` exists for:
+    // measured against Postgres 17, a `40001` aborts the **whole** transaction, so the
+    // `ROLLBACK TO SAVEPOINT` that would start attempt two answers `25P01 ROLLBACK TO SAVEPOINT
+    // can only be used in transaction blocks`. Re-running the inner body would also be re-running
+    // it against reads the outer scope took before the race — the retry has to own the BEGIN.
+    // Refused rather than ignored: a budget silently dropped is worse than one refused, because
+    // the author believes they have it.
+    assert(
+      options.retry === undefined || options.retry === 0,
+      'withTransaction({ retry }) inside another transaction: a nested scope is a SAVEPOINT, and a serialization failure aborts the whole transaction, so there is nothing left to retry into',
+      "move the retry to the OUTERMOST withTransaction — withTransaction(fn, { retry: 3, isolation: 'serializable' }) — and drop it here",
+    );
+    return runNested(outer, fn);
+  }
+
+  const attempts = (options.retry ?? 0) + 1;
+  let last: unknown;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      return await runRoot(fn, options);
+    } catch (error) {
+      // Only a lost serialization race, and only that: everything else — a constraint, a timeout, a
+      // dead socket, a throw from `fn` itself — is a failure re-running cannot change, and retrying
+      // it would turn one error into `retry + 1` of them.
+      if (!isRetryableState(error)) throw error;
+      // Nobody asked for a retry, so nothing was exhausted: the caller gets the driver's own
+      // `X_DB_SERIALIZATION_FAILURE`, whose fix is `withTransaction(fn, { retry: 3 })` — the
+      // instruction they actually need. Wrapping it would answer "raise your budget" to someone
+      // who has no budget.
+      if (attempts === 1) throw error;
+      last = error;
+    }
   }
+  throw serializationExhausted(attempts, last);
 }

package/src/type-pins.ts

@@ -0,0 +1,29 @@
+// Compile-time pins for this package's disposable resources. Source, not a `.test.ts`, on
+// purpose: `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a
+// type-level assertion written there can never fail. This module emits nothing and exports
+// nothing anybody imports — a regression is a build error, the only enforcement that counts
+// (axiom 3). `DbConnection` and `Turn` both went through a session where `release()`/`close()`
+// left a resource cached or unreturned; the fix each time was RAII (`Disposable` + `using`), and
+// this pin is what stops a future edit from quietly dropping `Disposable` off either interface —
+// the one place a regression here would otherwise surface is a leaked connection under load, not
+// a red test.
+
+import type { DbConnection } from './client';
+import type { Turn } from './pglite-turns';
+
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+
+/**
+ * The pinned handle `client.reserve()` returns must stay `Disposable`, or `using connection =
+ * await client.reserve()` in `transaction.ts` / `readonly-query.ts` stops compiling as a
+ * scope-bound resource and degrades silently back into a hand-rolled `try`/`finally`.
+ */
+export type _DbConnectionIsDisposable = Assert<[DbConnection] extends [Disposable] ? true : false>;
+
+/**
+ * PGlite's single-session turn must stay `Disposable` too, or `TurnQueue.run()`'s `using turn =
+ * await this.take()` in `pglite-turns.ts` loses the same guarantee — the connection never gets
+ * queued back to the next waiter on a throw.
+ */
+export type _TurnIsDisposable = Assert<[Turn] extends [Disposable] ? true : false>;

package/src/readonly.ts

@@ -1,111 +0,0 @@
-// Single responsibility: a `DbClient` that cannot mutate — for any caller that cannot open its
-// own transaction. An LLM with a Postgres connection and no gate is an outage waiting to be
-// prompted into existence. (MCP's `db.query` reaches past this for the stronger `readOnlyQuery`:
-// a SELECT-only role inside `BEGIN READ ONLY`, where Postgres refuses the write, not a regex.)
-// Detection strips comments and string literals first, because
-// `/* x */ update ...` and `WITH t AS (INSERT ...) SELECT` are exactly how a naive check is beaten.
-
-import type { DbClient } from './client';
-import { readonlyViolation } from './errors';
-import { raw, type SqlFragment } from './sql';
-
-const MUTATING = [
-  'insert',
-  'update',
-  'delete',
-  'truncate',
-  'drop',
-  'alter',
-  'create',
-  'grant',
-  'revoke',
-  'copy',
-  'set',
-  'call',
-  'do',
-  'refresh',
-  'vacuum',
-  'reindex',
-  'cluster',
-  'lock',
-  'merge',
-  'analyze',
-  'prepare',
-  'execute',
-] as const;
-
-const MUTATING_PATTERN = new RegExp(`\\b(${MUTATING.join('|')})\\b`, 'i');
-
-/**
- * Blank out anything a keyword could legitimately hide inside: line comments, block comments,
- * single-quoted literals, dollar-quoted bodies and quoted identifiers. Blanking (rather than
- * deleting) keeps offsets stable so the reported statement still reads correctly.
- */
-export function stripSqlNoise(text: string): string {
-  return text
-    .replace(/\$([A-Za-z_]\w*)?\$[\s\S]*?\$\1?\$/g, ' ')
-    .replace(/--[^\n]*/g, ' ')
-    .replace(/\/\*[\s\S]*?\*\//g, ' ')
-    .replace(/'(?:[^']|'')*'/g, " '' ")
-    .replace(/"(?:[^"]|"")*"/g, ' "" ');
-}
-
-export interface MutationVerdict {
-  readonly mutating: boolean;
-  readonly keyword: string | null;
-}
-
-/**
- * Whole-text scan, not a leading-keyword check: multi-statement strings and CTEs that end in a
- * writing branch must both be caught, and a false positive here is far cheaper than a false
- * negative. `updated_at` and `offset` do not match — `\b` requires a non-word boundary.
- */
-export function inspectStatement(text: string): MutationVerdict {
-  const match = MUTATING_PATTERN.exec(stripSqlNoise(text));
-  if (match === null) return { mutating: false, keyword: null };
-  return { mutating: true, keyword: match[1] ?? match[0] };
-}
-
-export function assertReadOnly(fragment: SqlFragment): void {
-  const verdict = inspectStatement(fragment.text);
-  if (!verdict.mutating) return;
-  throw readonlyViolation(fragment.text.trim().slice(0, 160), verdict.keyword ?? 'mutating');
-}
-
-export interface ReadOnlyOptions {
-  /** Also ask Postgres to enforce it. Off only for clients that cannot run `SET TRANSACTION`. */
-  readonly seal?: boolean | undefined;
-}
-
-/**
- * Belt and braces: the regex is the gate, `SET TRANSACTION READ ONLY` is the backstop for
- * anything the regex was too clever to catch. Sealing is best-effort — outside a transaction
- * block Postgres only warns, and a driver that rejects it must not break every read.
- */
-export function readOnly(client: DbClient, options: ReadOnlyOptions = {}): DbClient {
-  let sealed = options.seal === false;
-
-  async function seal(): Promise<void> {
-    if (sealed) return;
-    sealed = true;
-    await client.execute(raw('SET TRANSACTION READ ONLY')).catch(() => undefined);
-  }
-
-  return {
-    async query<T>(fragment: SqlFragment): Promise<readonly T[]> {
-      assertReadOnly(fragment);
-      await seal();
-      return client.query<T>(fragment);
-    },
-    async one<T>(fragment: SqlFragment): Promise<T | null> {
-      assertReadOnly(fragment);
-      await seal();
-      return client.one<T>(fragment);
-    },
-    async execute(fragment: SqlFragment): Promise<number> {
-      assertReadOnly(fragment);
-      await seal();
-      return client.execute(fragment);
-    },
-  };
-}