@ultimat3/db 1.2.0 → 2.0.0

package/src/sql-scan.ts

@@ -0,0 +1,159 @@
+// Single responsibility: name the span of SQL text starting at one offset — a comment, a literal,
+// a quoted identifier, a dollar-quoted body, or none of them. One scanner, because a splitter that
+// disagreed with a guard about where a literal ends is a `;` sent as data or a `delete` read as
+// prose, and the two answers must be the same answer.
+
+const IDENTIFIER_START = /[A-Za-z_]/;
+export const IDENTIFIER_PART = /[A-Za-z0-9_]/;
+/** `$` is legal in an identifier after the first character — `a$b` is one name, not three. */
+const IDENTIFIER_TAIL = /[A-Za-z0-9_$]/;
+
+export type NoiseKind = 'line-comment' | 'block-comment' | 'string' | 'identifier' | 'dollar-body';
+
+/** A span that is not code: what it is, and the offset just past it. */
+export interface NoiseSpan {
+  readonly kind: NoiseKind;
+  readonly end: number;
+}
+
+/** Past a `--` comment, including the newline that ends it. */
+function skipLineComment(script: string, index: number): number {
+  const newline = script.indexOf('\n', index);
+  return newline === -1 ? script.length : newline + 1;
+}
+
+/**
+ * Past a block comment. Postgres **nests** them, so the depth is counted rather than matched to
+ * the first terminator — a commented-out block that itself contains a comment closes once, and
+ * every `;` after that point would otherwise be read as data.
+ */
+function skipBlockComment(script: string, index: number): number {
+  let depth = 0;
+  let at = index;
+  while (at < script.length) {
+    const char = script[at];
+    const next = script[at + 1];
+    if (char === '/' && next === '*') {
+      depth += 1;
+      at += 2;
+      continue;
+    }
+    if (char === '*' && next === '/') {
+      depth -= 1;
+      at += 2;
+      if (depth === 0) return at;
+      continue;
+    }
+    at += 1;
+  }
+  return script.length;
+}
+
+/**
+ * Past a run closing on `quote`, where a doubled quote is an escaped one — `'it''s'` and
+ * `"a""b"` are each one token. `escapes` is the `E''` dialect, the only one where a backslash
+ * escapes the character after it; a standard-conforming string carries it as data.
+ */
+function skipQuoted(script: string, index: number, quote: string, escapes: boolean): number {
+  let at = index + 1;
+  while (at < script.length) {
+    const char = script[at];
+    if (escapes && char === '\\') {
+      at += 2;
+      continue;
+    }
+    if (char === quote) {
+      if (script[at + 1] === quote) {
+        at += 2;
+        continue;
+      }
+      return at + 1;
+    }
+    at += 1;
+  }
+  return script.length;
+}
+
+/**
+ * Whether the `$` at `index` continues an identifier instead of opening a delimiter.
+ *
+ * The run before it is walked to its start rather than one character being read, because the
+ * answer is what that run *began* as: `foo$tag$` is the single identifier Postgres reads it as
+ * (`$` is legal after the first character), while `$1$tag$` is a bound parameter followed by a
+ * real delimiter — a run opening with a digit or a `$` cannot be an identifier at all.
+ */
+function insideIdentifier(script: string, index: number): boolean {
+  let at = index - 1;
+  while (at >= 0 && IDENTIFIER_TAIL.test(script[at] ?? '')) at -= 1;
+  const first = script[at + 1];
+  return at + 1 < index && first !== undefined && IDENTIFIER_START.test(first);
+}
+
+/**
+ * The `$tag$` opening a dollar-quoted body at `index`, or `null`. A tag is an identifier or
+ * empty, which is what keeps a bound parameter out: `$1` cannot open a body, so `where "id" = $1`
+ * never swallows the rest of the script.
+ *
+ * A delimiter also needs separating from the identifier before it, or `select foo$tag$; select
+ * 2;` is one statement to us and two to the server — which answers `cannot insert multiple
+ * commands into a prepared statement`.
+ */
+export function dollarTagAt(script: string, index: number): string | null {
+  if (script[index] !== '$') return null;
+  if (insideIdentifier(script, index)) return null;
+  let at = index + 1;
+  while (at < script.length) {
+    const char = script[at] ?? '';
+    const valid = at === index + 1 ? IDENTIFIER_START.test(char) : IDENTIFIER_PART.test(char);
+    if (!valid) break;
+    at += 1;
+  }
+  return script[at] === '$' ? script.slice(index, at + 1) : null;
+}
+
+/** Past the body `tag` opened, up to and including the matching close. */
+function skipDollarBody(script: string, index: number, tag: string): number {
+  const close = script.indexOf(tag, index + tag.length);
+  return close === -1 ? script.length : close + tag.length;
+}
+
+/**
+ * Whether the `'` at `index` opens an `E''` string. The prefix is a whole token, so a trailing
+ * `e` on an identifier does not turn the literal beside it into an escape string.
+ */
+function escapesAt(script: string, index: number): boolean {
+  const prefix = script[index - 1];
+  if (prefix !== 'E' && prefix !== 'e') return false;
+  const before = script[index - 2];
+  return before === undefined || !IDENTIFIER_PART.test(before);
+}
+
+/**
+ * The non-code span starting at `index`, or `null` when `index` is code.
+ *
+ * Source order is the whole point: a caller that asked "is there a comment anywhere" before
+ * "where do the literals end" reads the `--` in `select '--'; delete from posts` as a comment and
+ * erases a live statement. Walking forward one span at a time cannot make that mistake, because
+ * by the time the `--` is reached it is already inside the literal that was scanned first.
+ *
+ * A span left unterminated ends at the end of the text rather than being refused: Postgres names
+ * that syntax error precisely, and a second SQL parser competing with it would only report the
+ * same fault in worse words.
+ */
+export function noiseAt(script: string, index: number): NoiseSpan | null {
+  const char = script[index];
+  if (char === '-' && script[index + 1] === '-') {
+    return { kind: 'line-comment', end: skipLineComment(script, index) };
+  }
+  if (char === '/' && script[index + 1] === '*') {
+    return { kind: 'block-comment', end: skipBlockComment(script, index) };
+  }
+  if (char === "'") {
+    return { kind: 'string', end: skipQuoted(script, index, char, escapesAt(script, index)) };
+  }
+  if (char === '"') {
+    return { kind: 'identifier', end: skipQuoted(script, index, char, false) };
+  }
+  const tag = dollarTagAt(script, index);
+  return tag === null ? null : { kind: 'dollar-body', end: skipDollarBody(script, index, tag) };
+}

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);
 }