@ultimat3/db 22.15.0 → 24.0.0

package/src/schema-dump.ts

@@ -0,0 +1,192 @@
+// Single responsibility: a `CatalogDescription` as files — the schema dump. Pure: the same catalog
+// is the same bytes, so the gate can compare what is committed with what the migrations produce.
+// It decides which file a statement belongs to; `schema-dump-table.ts` spells a table, and every
+// other object is the catalog's own `pg_get_*def` text with a terminator.
+
+import type { CatalogDescription, CatalogType } from './catalog';
+import { FRAMEWORK_TABLE_PREFIX } from './drift';
+import { constraintClause, createSequence, quoted, tableStatements } from './schema-dump-table';
+import { literal } from './sql';
+
+export interface SchemaDumpFile {
+  /** Relative to the dump directory, POSIX: `04_tables/posts.sql`, `framework/04_tables/x_jobs.sql`. */
+  readonly path: string;
+  readonly content: string;
+}
+
+/** One directory per object kind, numbered in the order a database can be built in. */
+export const SCHEMA_DUMP_KINDS = [
+  '01_extensions',
+  '02_types',
+  '03_sequences',
+  '04_tables',
+  '05_indexes',
+  '06_foreign_keys',
+  '07_views',
+  '08_functions',
+  '09_triggers',
+] as const;
+
+export type SchemaDumpKind = (typeof SCHEMA_DUMP_KINDS)[number];
+
+/** The framework's own tables (`x_jobs`, `x_migrations`, …) live under a twin of the same layout. */
+export const FRAMEWORK_DUMP_DIR = 'framework';
+
+/** What the dump could not spell — comments only, so it loads as nothing. */
+export const UNRENDERED_DUMP_FILE = 'unrendered.sql';
+
+/** The ceiling the `filesize` step holds for source. A longer file is split, never exempted. */
+export const SCHEMA_DUMP_MAX_LINES = 500;
+
+export const SCHEMA_DUMP_HEADER =
+  '-- generated by `x db gen` from the migrations; never edited by hand (X_SCHEMA_DUMP_DRIFT)';
+
+/**
+ * A name as a file name: anything outside `[A-Za-z0-9_-]` becomes `%XX` per UTF-8 byte. A `.` is
+ * encoded too, which is what makes the `.<n>.sql` suffix of a split file unambiguous.
+ */
+export function dumpFileName(name: string): string {
+  return [...new TextEncoder().encode(name)]
+    .map((byte) => {
+      const char = String.fromCharCode(byte);
+      return /[A-Za-z0-9_-]/.test(char)
+        ? char
+        : `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+    })
+    .join('');
+}
+
+/** The `x_` rule `appTables()` already holds: the owner (a table, else the object) decides the twin. */
+const twinOf = (owner: string): string =>
+  owner.startsWith(FRAMEWORK_TABLE_PREFIX) ? `${FRAMEWORK_DUMP_DIR}/` : '';
+
+function typeStatement(type: CatalogType): string {
+  if (type.kind === 'enum') {
+    const labels = type.labels.map((label) => literal(label).text).join(', ');
+    return `create type ${quoted(type.name)} as enum (${labels});`;
+  }
+  const clauses = [`create domain ${quoted(type.name)} as ${type.baseType}`];
+  if (type.default !== null) clauses.push(`default ${type.default}`);
+  if (type.notNull) clauses.push('not null');
+  clauses.push(...type.checks.map(constraintClause));
+  return `${clauses.join(' ')};`;
+}
+
+/** `pg_get_*def` text with exactly one terminator, whether or not the catalog wrote one. */
+const terminated = (definition: string): string => `${definition.trim().replace(/;$/, '')};`;
+
+const TRIGGER_STATE: ReadonlyMap<string, string> = new Map([
+  ['D', 'disable trigger'],
+  ['R', 'enable replica trigger'],
+  ['A', 'enable always trigger'],
+]);
+
+/** Statements per file path, in insertion order within a file. */
+class Buckets {
+  private readonly files = new Map<string, string[]>();
+
+  add(kind: SchemaDumpKind, owner: string, file: string, ...statements: readonly string[]): void {
+    const path = `${twinOf(owner)}${kind}/${dumpFileName(file)}`;
+    const bucket = this.files.get(path) ?? [];
+    bucket.push(...statements);
+    this.files.set(path, bucket);
+  }
+
+  entries(): readonly (readonly [string, readonly string[]])[] {
+    return [...this.files.entries()];
+  }
+}
+
+function collect(catalog: CatalogDescription): Buckets {
+  const out = new Buckets();
+  const materialized = new Set(catalog.views.filter((v) => v.materialized).map((v) => v.name));
+  for (const extension of catalog.extensions) {
+    const statement = `create extension if not exists ${quoted(extension.name)};`;
+    out.add('01_extensions', extension.name, extension.name, statement);
+  }
+  for (const type of catalog.types) out.add('02_types', type.name, type.name, typeStatement(type));
+  for (const sequence of catalog.sequences) {
+    out.add('03_sequences', sequence.name, sequence.name, createSequence(sequence));
+  }
+  for (const table of catalog.tables) {
+    out.add('04_tables', table.name, table.name, ...tableStatements(table));
+  }
+  for (const view of catalog.views) {
+    const head = view.materialized ? 'create materialized view' : 'create view';
+    const options = view.options === null ? '' : ` with (${view.options})`;
+    const statement = `${head} ${quoted(view.name)}${options} as\n${terminated(view.definition)}`;
+    out.add('07_views', view.name, view.name, statement);
+  }
+  for (const index of catalog.indexes) {
+    // A materialized view's index rides in the view's own file: the view is built in a later
+    // directory than `05_indexes`, so an index filed there would name a relation not yet created.
+    const kind = materialized.has(index.table) ? '07_views' : '05_indexes';
+    out.add(kind, index.table, index.table, terminated(index.definition));
+  }
+  for (const table of catalog.tables) {
+    if (table.replicaIdentity.kind !== 'index') continue;
+    const using = `replica identity using index ${quoted(table.replicaIdentity.index)}`;
+    out.add('05_indexes', table.name, table.name, `alter table ${quoted(table.name)} ${using};`);
+  }
+  for (const key of catalog.foreignKeys) {
+    const statement = `alter table ${quoted(key.table)} add ${constraintClause(key)};`;
+    out.add('06_foreign_keys', key.table, key.table, statement);
+  }
+  for (const fn of catalog.functions) {
+    out.add('08_functions', fn.name, fn.name, terminated(fn.definition));
+  }
+  for (const trigger of catalog.triggers) {
+    const state = TRIGGER_STATE.get(trigger.enabled);
+    const on = quoted(trigger.table);
+    out.add('09_triggers', trigger.table, trigger.table, terminated(trigger.definition));
+    if (state !== undefined) {
+      const statement = `alter table ${on} ${state} ${quoted(trigger.name)};`;
+      out.add('09_triggers', trigger.table, trigger.table, statement);
+    }
+  }
+  return out;
+}
+
+/** One file, or `<name>.1.sql`, `<name>.2.sql`, … when it would pass the ceiling. */
+function split(path: string, content: string): readonly SchemaDumpFile[] {
+  // The trailing newline is the file's terminator, not a line of its own.
+  const lines = content.replace(/\n$/, '').split('\n');
+  if (lines.length <= SCHEMA_DUMP_MAX_LINES) return [{ path: `${path}.sql`, content }];
+  const parts: SchemaDumpFile[] = [];
+  for (let at = 0; at < lines.length; at += SCHEMA_DUMP_MAX_LINES) {
+    const chunk = lines.slice(at, at + SCHEMA_DUMP_MAX_LINES).join('\n');
+    parts.push({ path: `${path}.${parts.length + 1}.sql`, content: `${chunk}\n` });
+  }
+  return parts;
+}
+
+function unrenderedFiles(catalog: CatalogDescription): readonly SchemaDumpFile[] {
+  const twins = new Map<string, string[]>();
+  for (const object of catalog.unrendered) {
+    const twin = twinOf(object.table ?? object.name);
+    const on = object.table === null ? '' : ` on ${quoted(object.table)}`;
+    const lines = twins.get(twin) ?? [];
+    lines.push(`-- not rendered: ${object.kind} ${quoted(object.name)}${on}`);
+    twins.set(twin, lines);
+  }
+  return [...twins.entries()].map(([twin, lines]) => ({
+    path: `${twin}${UNRENDERED_DUMP_FILE}`,
+    content: `${SCHEMA_DUMP_HEADER}\n\n${lines.join('\n')}\n`,
+  }));
+}
+
+/**
+ * The whole dump, sorted by path. Deterministic by construction: the catalog arrives sorted
+ * (`introspectCatalog`), nothing here reads a clock, a version or an owner, and every file ends
+ * in exactly one newline.
+ */
+export function renderSchemaDump(catalog: CatalogDescription): readonly SchemaDumpFile[] {
+  const files = collect(catalog)
+    .entries()
+    .flatMap(([path, statements]) =>
+      split(path, `${SCHEMA_DUMP_HEADER}\n\n${statements.join('\n\n')}\n`),
+    );
+  return [...files, ...unrenderedFiles(catalog)].sort((a, b) =>
+    a.path < b.path ? -1 : a.path > b.path ? 1 : 0,
+  );
+}

package/src/schema-load.ts

@@ -0,0 +1,119 @@
+// Single responsibility: build a schema from the dump `schema-dump.ts` wrote — every file's
+// statements, in kind order, inside one transaction. The inverse of the dump and the half of
+// "load equals replay" that proves the files are a cache of the migrations rather than a second
+// source: load, introspect, render again, and the bytes must be the ones that were loaded.
+
+import { renderThrowable } from '@ultimat3/core';
+import type { DbClient } from './client';
+import { baseClient } from './client';
+import { schemaDumpDrift, unloadableDump } from './dump-drift';
+import { DbError } from './errors';
+import { FRAMEWORK_DUMP_DIR, type SchemaDumpFile } from './schema-dump';
+import { raw } from './sql';
+import { SQLSTATE, sqlState } from './sqlstate';
+import { statementsOf } from './statement-split';
+import { withTransaction } from './transaction';
+
+export interface LoadSchemaDumpOptions {
+  readonly files: readonly SchemaDumpFile[];
+  readonly client?: DbClient | undefined;
+}
+
+export interface SchemaLoadReport {
+  readonly files: number;
+  readonly statements: number;
+}
+
+/** One loadable unit: a whole file, or the numbered parts of a split one joined back together. */
+interface Unit {
+  readonly path: string;
+  readonly kind: string;
+  readonly framework: boolean;
+  readonly script: string;
+}
+
+const SPLIT_PART = /^(.*)\.(\d+)\.sql$/;
+
+/**
+ * Files regrouped into units and put in load order: by kind directory, the framework twin first
+ * within a kind (an app's foreign key may point at `x_users`; nothing of the framework's points at
+ * the app), then by name. A split file's parts are joined in NUMERIC order — `.10.sql` after
+ * `.9.sql` — because a statement may straddle the cut.
+ */
+export function loadOrder(files: readonly SchemaDumpFile[]): readonly Unit[] {
+  const parts = new Map<string, { part: number; content: string }[]>();
+  for (const file of files) {
+    const match = SPLIT_PART.exec(file.path);
+    const base = match === null ? file.path : `${match[1] ?? ''}.sql`;
+    const list = parts.get(base) ?? [];
+    list.push({ part: match === null ? 0 : Number(match[2]), content: file.content });
+    parts.set(base, list);
+  }
+  const units = [...parts.entries()].map(([path, list]): Unit => {
+    const framework = path.startsWith(`${FRAMEWORK_DUMP_DIR}/`);
+    const local = framework ? path.slice(FRAMEWORK_DUMP_DIR.length + 1) : path;
+    return {
+      path,
+      kind: local.includes('/') ? (local.split('/')[0] ?? '') : '',
+      framework,
+      script: list
+        .sort((a, b) => a.part - b.part)
+        .map((part) => part.content)
+        .join(''),
+    };
+  });
+  const key = (unit: Unit): string => `${unit.kind}/${unit.framework ? '0' : '1'}/${unit.path}`;
+  return units.sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+}
+
+/** "Not created YET" — the three states a statement raises when it names something later in the order. */
+const NOT_YET: ReadonlySet<string> = new Set([
+  SQLSTATE.undefinedTable,
+  SQLSTATE.undefinedFunction,
+  SQLSTATE.undefinedObject,
+]);
+
+const detailOf = (error: unknown): string =>
+  error instanceof DbError ? error.cause : renderThrowable(error);
+
+/**
+ * Load every file. A unit that fails because something it names does not exist yet is rolled back
+ * to its savepoint and retried after the rest — kind order is right for nearly every schema, and
+ * the exceptions (a view over a view, a column default calling a function) are dependencies no
+ * directory layout can order. A pass that loads nothing ends the loop with the last refusal.
+ *
+ * `check_function_bodies` is off for the transaction: a SQL-language function body is validated
+ * at creation, and it may name a table an alphabetical neighbour has not created.
+ */
+export async function loadSchemaDump(options: LoadSchemaDumpOptions): Promise<SchemaLoadReport> {
+  const client = options.client ?? baseClient();
+  let pending = loadOrder(options.files);
+  const files = pending.length;
+  let statements = 0;
+  await withTransaction(
+    async (tx) => {
+      await tx.execute(raw('set local check_function_bodies = off'));
+      while (pending.length > 0) {
+        const deferred: Unit[] = [];
+        let refusal: DbError | undefined;
+        for (const unit of pending) {
+          const script = statementsOf(unit.script);
+          try {
+            await withTransaction(async (savepoint) => {
+              for (const statement of script) await savepoint.execute(raw(statement));
+            });
+            statements += script.length;
+          } catch (error) {
+            refusal = schemaDumpDrift(unloadableDump(unit.path, detailOf(error)));
+            if (!NOT_YET.has(sqlState(error) ?? '')) throw refusal;
+            deferred.push(unit);
+          }
+        }
+        if (deferred.length === pending.length && refusal !== undefined) throw refusal;
+        pending = deferred;
+      }
+    },
+    { client },
+  );
+  return { files, statements };
+}

package/src/sibling-turn.ts

@@ -0,0 +1,49 @@
+// Single responsibility: a nested scope's wait for its turn among its siblings, under a deadline.
+// Sibling scopes run one after the other (savepoints are a stack), so a body that awaits a sibling
+// queued BEHIND it is a cycle nothing can break from inside — and an unbounded wait made it a
+// silent, permanent hang. Same shape as `pool-reserve.ts`: a late turn is given back, never dropped.
+
+import type { DbError } from './errors';
+import type { Turn, TurnQueue } from './pglite-turns';
+
+/**
+ * The default wait, in milliseconds. Above the serving roles' `statement_timeout` (10–15 s,
+ * `pool-profile.ts`), so a sibling that is merely inside one slow statement finishes or fails
+ * first; `{ siblingWaitMs }` moves it and `0` removes it.
+ */
+export const SIBLING_SCOPE_WAIT_MS = 30_000;
+
+/**
+ * `queue.take()` under a deadline. The place in the queue is claimed the moment `take()` is called
+ * and cannot be withdrawn, so a wait that gives up must still hand the turn straight on when it
+ * arrives — otherwise every later sibling waits behind a scope that no longer exists.
+ */
+export async function siblingTurn(
+  queue: TurnQueue,
+  waitMs: number,
+  refusal: () => DbError,
+): Promise<Turn> {
+  const pending = queue.take();
+  if (waitMs === 0) return pending;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let expired = false;
+  try {
+    return await Promise.race([
+      pending,
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => {
+          expired = true;
+          // Built at expiry, so it names the scope holding the turn NOW.
+          reject(refusal());
+        }, waitMs);
+        // The deadline must not be what keeps a finished process alive.
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    void pending.then((late) => {
+      if (expired) late.release();
+    });
+  }
+}

package/src/sqlstate.ts

@@ -16,6 +16,9 @@ export const SQLSTATE = Object.freeze({
   undefinedTable: '42P01',
   /** `undefined_column` — an entity edited before the migration that adds the column ran. */
   undefinedColumn: '42703',
+  /** `undefined_function` and `undefined_object` — with `undefined_table`, "not created YET". */
+  undefinedFunction: '42883',
+  undefinedObject: '42704',
   uniqueViolation: '23505',
   foreignKeyViolation: '23503',
   serializationFailure: '40001',
@@ -28,12 +31,6 @@ export const SQLSTATE = Object.freeze({
   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;
@@ -44,6 +41,32 @@ function unknownField(value: unknown, key: string): unknown {
   }
 }
 
+/** Five characters, digits and uppercase letters — `42P01`, never `ERR_POSTGRES_SERVER_ERROR`. */
+const SQLSTATE_SHAPE = /^[0-9A-Z]{5}$/;
+
+/**
+ * Whether five characters of that shape are a SQLSTATE, decided by where the object CAME FROM —
+ * the shape alone cannot say. `EPIPE` and `E2BIG` are errno names of exactly that shape, and
+ * `raise exception … using errcode = 'ABCDE'` is a legal state with no digit in it, so a rule
+ * about letters and digits is wrong in both directions.
+ *
+ * Measured on Bun.SQL against Postgres 17 and on PGlite: a server ErrorResponse carries
+ * `severity` on both drivers, and nothing the socket layer throws does. A syscall error carries
+ * `syscall` and a NUMERIC `errno`. An object marked as neither — a fake, a wrapper, a driver this
+ * package has not measured — keeps the old reading only for a state that carries a digit, which
+ * is every state Postgres itself defines and no bare errno name this package has been handed.
+ */
+function isState(holder: unknown, candidate: string): boolean {
+  if (!SQLSTATE_SHAPE.test(candidate)) return false;
+  if (stringField(holder, 'severity') !== undefined) return true;
+  if (stringField(holder, 'syscall') !== undefined) return false;
+  if (typeof unknownField(holder, 'errno') === 'number') return false;
+  return /[0-9]/.test(candidate);
+}
+
+/** How deep a wrap may nest before we stop looking. `DbError` adds exactly one level. */
+const MAX_WRAPS = 4;
+
 /**
  * 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.
@@ -54,17 +77,17 @@ function unknownField(value: unknown, key: string): unknown {
  * 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.
+ * The shape test keeps `ERR_POSTGRES_SERVER_ERROR` and `X_DB_UNAVAILABLE` out — neither is five
+ * characters of `[0-9A-Z]` — and `isState` keeps an errno NAME out, which the shape cannot.
  */
 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;
+    if (errno !== undefined && isState(value, errno)) return errno;
     const code = stringField(value, 'code');
-    if (code !== undefined && SQLSTATE_SHAPE.test(code)) return code;
+    if (code !== undefined && isState(value, code)) return code;
     value = unknownField(value, 'sourceError');
   }
   return undefined;

package/src/statement-funnel.ts

@@ -6,6 +6,7 @@
 import { statementAttribution } from './attribution';
 import { encodeBoundParameters } from './bound-parameters';
 import type { BunSqlDriver } from './bun-sql';
+import { refuseRolledBackCommit } from './commit-tag';
 import { driverError } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
 import { statementObserver } from './observe';
@@ -32,12 +33,18 @@ async function sendOn(
   driver: Pick<BunSqlDriver, 'unsafe'>,
   fragment: SqlFragment,
 ): Promise<unknown> {
+  // `encodeBoundParameters`, never `fragment.values` raw: `Bun.SQL` joins a JS array's elements
+  // with commas (#384), and on the pool's unnamed statements sends a `Date` as its local-zone
+  // `toString()`. One encoder here rather than one import per call site, because this is the
+  // only place this driver's `unsafe` is called.
+  //
+  // ABOVE the `try`: its refusals are this package's own and already coded. Inside it, a ragged
+  // array or an Invalid Date came back as `X_DB_UNAVAILABLE` — "set DATABASE_URL" — from a driver
+  // that was never called.
+  const values = encodeBoundParameters(fragment.values);
+  let result: unknown;
   try {
-    // `encodeBoundParameters`, never `fragment.values` raw: `Bun.SQL` joins a JS array's elements
-    // with commas (#384), and on the pool's unnamed statements sends a `Date` as its local-zone
-    // `toString()`. One encoder here rather than one import per call site, because this is the
-    // only place this driver's `unsafe` is called.
-    return await driver.unsafe(fragment.text, encodeBoundParameters(fragment.values));
+    result = await driver.unsafe(fragment.text, 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
@@ -45,6 +52,10 @@ async function sendOn(
     // not classify is still `X_DB_UNAVAILABLE`, byte for byte.
     throw driverError(statementExcerpt(fragment.text), error);
   }
+  // Outside the `try`: this refusal is already typed, and `driverError` would re-wrap it as a
+  // database nobody could reach.
+  refuseRolledBackCommit(fragment.text, result);
+  return result;
 }
 
 /**

package/src/transaction-errors.ts

@@ -0,0 +1,66 @@
+// Single responsibility: the two refusals a transaction's END can raise — the server rolled it back
+// while the body carried on, and the answer to COMMIT never arrived. Split from `errors.ts` at the
+// file-size rule; both are thrown by `transaction.ts`, the first by the two statement funnels too.
+
+import { renderThrowable } from '@ultimat3/core';
+import { DbError } from './errors';
+import { sqlState } from './sqlstate';
+
+const ABORTED_FIX =
+  'await withTransaction(() => fallible()).catch(fallback)   # a nested scope is a SAVEPOINT, so ' +
+  'only it rolls back — or rethrow the statement error instead of catching it';
+
+/**
+ * Postgres aborts the WHOLE transaction on any statement error and answers the `COMMIT` that
+ * follows with the tag `ROLLBACK` and no error, so a body that caught the failure and returned was
+ * reported committed with nothing stored. `first` is the statement the body threw away — rendered
+ * into the cause, deliberately NOT chained as `sourceError`: `sqlState()` unwraps that chain, and a
+ * caller asking "was this a unique violation" would be answered yes by an error that means the
+ * whole unit of work is gone.
+ */
+export const transactionAborted = (first?: unknown): DbError => {
+  const state = sqlState(first);
+  return new DbError({
+    code: 'X_DB_TRANSACTION_ABORTED',
+    cause:
+      first === undefined
+        ? 'COMMIT was answered with ROLLBACK: a statement failed earlier in this transaction, its error was caught, and the server had already rolled the whole unit of work back'
+        : `a statement failed inside the transaction and the error was caught rather than rethrown, so the server rolled the whole unit of work back: ${renderThrowable(first)}`,
+    fix: ABORTED_FIX,
+    ...(state === undefined ? {} : { meta: { sqlState: state } }),
+  });
+};
+
+/**
+ * A nested scope gave up waiting for the sibling holding the turn. Names both: the scope that
+ * waited is identified by its parent (it never opened, so it has no savepoint of its own), and the
+ * holder by the savepoint it is inside. Terminal: the usual cause is a body awaiting a sibling
+ * queued behind it, and the same call made again waits for the same cycle.
+ */
+export const siblingScopeTimeout = (
+  parent: string,
+  holder: string | undefined,
+  waitedMs: number,
+): DbError =>
+  new DbError({
+    code: 'X_DB_SIBLING_SCOPE_TIMEOUT',
+    cause: `a nested scope under ${parent} waited ${waitedMs}ms for its sibling ${holder ?? 'scope'} to finish and never got a turn — sibling scopes run one after the other, so a body that awaits a sibling started after it waits for itself`,
+    fix: 'await withTransaction(first); await withTransaction(second)   # one after the other, never a nested body awaiting a sibling — or raise the wait: withTransaction(fn, { siblingWaitMs: 120000 })',
+    meta: { parent, waitedMs, ...(holder === undefined ? {} : { holder }) },
+  });
+
+/**
+ * `COMMIT` was sent and rejected with no SQLSTATE — the socket went before the answer did. The
+ * transaction is durable or it is not, and nothing on this side can say which, so neither list
+ * runs: an `onRollback` undo would revert state the database may have kept, and an `onCommit`
+ * effect would announce rows it may not have.
+ */
+export const commitUnknown = (sourceError: unknown): DbError =>
+  new DbError({
+    code: 'X_DB_COMMIT_UNKNOWN',
+    cause: `the connection failed while COMMIT was in flight, so the transaction is either durable or rolled back and this process cannot tell which; neither onCommit effects nor onRollback undos ran. Only the data can say which — a row the transaction wrote is present if it committed and absent if it did not: ${renderThrowable(sourceError)}`,
+    // A session, never a `-c "<placeholder>"`: which row proves it is the caller's knowledge, and
+    // a placeholder inside a command is a command that does not run.
+    fix: 'psql "$DATABASE_URL"   # a session on that database: select a row the transaction wrote, and re-run the unit of work only when it is absent',
+    sourceError,
+  });

package/src/transaction-options.ts

@@ -0,0 +1,122 @@
+// Single responsibility: what a transaction scope is ASKED for and what it hands back — the `DbTx`
+// handle, `TransactionOptions`, and the `BEGIN` text those options spell. Split from
+// `transaction.ts` at the file-size rule; the scope itself (pin, savepoints, COMMIT) stays there.
+
+import type { Random } from '@ultimat3/core';
+import type { DbClient } from './client';
+import { isolationLevelInvalid } from './errors';
+
+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, and never
+   * when the answer to COMMIT was lost: the write it would undo may be durable.
+   */
+  onRollback(undo: () => void): void;
+  /**
+   * Fired in registration order once the ROOT transaction has COMMITTED — never on rollback, and
+   * never when the answer to COMMIT was lost (`X_DB_COMMIT_UNKNOWN`). A
+   * nested scope's effects are handed to its parent on `RELEASE` and dropped on `ROLLBACK TO`, so
+   * nothing fires for a write that is not durable. What a change feed, a cache purge or a dev row
+   * observer needs: reporting a write before COMMIT reports rows a rollback then erases. An effect
+   * that throws is swallowed — the transaction already committed, and nothing can un-commit it.
+   */
+  onCommit(effect: () => void): void;
+}
+
+export type IsolationLevel = 'read committed' | 'repeatable read' | 'serializable';
+
+export interface TransactionOptions {
+  readonly isolation?: IsolationLevel | undefined;
+  readonly readOnly?: boolean | undefined;
+  /** Only meaningful with `serializable` + `readOnly`; lets Postgres wait instead of retrying. */
+  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.
+   *
+   * Each re-run waits first (`transaction-backoff.ts`). A budget of 0 waits not at all.
+   */
+  readonly retry?: number | undefined;
+  /**
+   * The wait between attempts, and the roll behind its jitter. Injected for one reason — a schedule
+   * provable only by waiting for it is a schedule no test pins — and production passes neither.
+   * They are only ever read when `retry` is 1 or more.
+   */
+  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+  readonly random?: Random | undefined;
+  /**
+   * How long a NESTED scope waits for a sibling scope to finish before it may open, in
+   * milliseconds. Sibling scopes under one parent run one after the other, so a body that awaits
+   * a sibling started after it waits for itself; past this the waiting call rejects with
+   * `X_DB_SIBLING_SCOPE_TIMEOUT` instead of hanging. Default `SIBLING_SCOPE_WAIT_MS` (30 s); `0`
+   * waits without a deadline. Read only by a nested scope — the outermost one has no sibling.
+   */
+  readonly siblingWaitMs?: number | undefined;
+}
+
+/**
+ * The SQL for one isolation level, RE-DERIVED from the closed set rather than built out of the
+ * value — the same rule `pg-sql.ts` follows for `asc|desc`, and for the same reason: `BEGIN` takes
+ * no parameters, so this is one of the two statements here built as text, and a level spliced into
+ * it is whatever the caller passed. `isolation` is typed, and a type is not a runtime guard: the
+ * value reaches `withTransaction` from an app's config, a JSON body or a CLI flag —
+ * `{ isolation: 'read committed; drop table x; --' }` became exactly that statement, and a
+ * non-string became an uncoded `TypeError` inside a template literal.
+ *
+ * The `default` arm is `never`, so a fourth member added to `IsolationLevel` with no SQL beside it
+ * is a type error here rather than a refusal at runtime.
+ */
+const isolationMode = (declared: IsolationLevel): string => {
+  switch (declared) {
+    case 'read committed':
+      return 'ISOLATION LEVEL READ COMMITTED';
+    case 'repeatable read':
+      return 'ISOLATION LEVEL REPEATABLE READ';
+    case 'serializable':
+      return 'ISOLATION LEVEL SERIALIZABLE';
+    default: {
+      const unhandled: never = declared;
+      throw isolationLevelInvalid(unhandled);
+    }
+  }
+};
+
+export function beginStatement(options: TransactionOptions): string {
+  const modes: string[] = [];
+  if (options.isolation !== undefined) modes.push(isolationMode(options.isolation));
+  if (options.readOnly === true) modes.push('READ ONLY');
+  if (options.deferrable === true) modes.push('DEFERRABLE');
+  return modes.length === 0 ? 'BEGIN' : `BEGIN ${modes.join(' ')}`;
+}