@ultimat3/db 11.1.0 → 11.2.0

package/CLAUDE.md

@@ -137,6 +137,41 @@ that would start attempt two answers `25P01 ROLLBACK TO SAVEPOINT can only be us
 blocks`. There is nothing to retry into, and an author who believes they hold a budget they do not
 is worse off than one who is told.
 
+**A re-run waits first, `As of 2026-08-23`, and the default still waits not at all.** The loop had
+NO backoff: two transactions that deadlocked woke in the same microsecond, took the same locks in
+the same order, and one of them lost again — so a `retry: 8` budget was spent inside one round
+trip's worth of wall clock, which is the deadlock reproduced rather than resolved.
+`transaction-backoff.ts` is the schedule: `@ultimat3/core`'s `backoffDelay`, exponential from
+**10ms**, capped at **500ms**, **full** jitter. The constants are contention's, not an outage's — the
+winner of the race is already committing, and this loop holds a connection on a request's critical
+path, so ai's 500ms base and jobs' one-second base would turn a recovered transaction into a
+timed-out one. Full jitter because the two callers whose retries must not re-collide are, by
+construction, scheduled at the same offset from the same event. Nothing waits when `retry` is 0 or
+absent, and nothing waits after the LAST attempt. `{ sleep, random }` on `TransactionOptions` are
+the injection seams and production passes neither.
+
+**Four codes are classified `retryable`, and the terminal ones are deliberately NOT classified,
+`As of 2026-08-23`.** `DB_ERROR_RETRY` registers `X_DB_SERIALIZATION_FAILURE`, `X_DB_LOCK_TIMEOUT`,
+`X_DB_POOL_EXHAUSTED` and `X_MIGRATE_CONCURRENT` — each is a resource that frees. Before it, this
+package classified nothing, so `X_DB_SERIALIZATION_FAILURE` rendered `retry: "terminal"` in every
+problem document while its own `fix:` line read `withTransaction(fn, { retry: 3 })`.
+
+The half that needs the argument is the codes left OUT. Core's shape (`CORE_ERROR_RETRY` lists only
+the exceptions) rather than `@ultimat3/scraping`'s exhaustive one, because a REGISTERED `terminal` is
+not the same as an unclassified code: `@ultimat3/jobs`' `nextRetryForError` dead-letters the first on
+attempt 1 and keeps the attempt count for the second. `X_DB_UNAVAILABLE: 'terminal'` is defensible
+for an HTTP client — four of its six throw sites are permanent config faults — and would dead-letter
+every in-flight job the moment Postgres fails over. A code that means two things to two readers stays
+unclassified until it is two codes. `errors-retry.test.ts` asserts the absence, so adding one is a
+failing test first.
+
+**What did NOT move down is core's `retry()` executor.** It stops on a `terminal` classification and
+retries everything else, so an UNCLASSIFIED throw is retried — and the value caught here is a raw
+driver error carrying a SQLSTATE, which core cannot see and nobody classified. Adopting it would
+have re-run `fn` on a unique violation, a statement timeout and a throw from `fn` itself.
+`isRetryableState` stays the guard, `40001`/`40P01` stays this package's Postgres knowledge, and only
+the arithmetic is core's.
+
 **`BEGIN` re-derives its isolation level from the closed set, `As of 2026-08-23`.** `BEGIN` takes
 no parameters, so `beginStatement` is one of the two statements here built as TEXT — and the level
 was `options.isolation.toUpperCase()` spliced into it. The TYPE is not the guard: the value reaches

package/README.md

@@ -28,7 +28,7 @@ await withTransaction(async (tx) => {
 | `sql` / `raw` / `identifier` / `literal` / `join` | fragment builders |
 | `db()` / `baseClient()` / `setDbClient()` | the ambient client; `db()` returns the open tx if any |
 | `DbTx.origin` | `As of 2026-08`: the client the transaction was **opened on** — `options.client` or `baseClient()`, never the reservation it runs statements through. `@ultimat3/entity` compares a pinned repository's client against it, so a pinned repo joins its own shard's transaction instead of being refused |
-| `withTransaction()` / `currentTx()` | transaction scope; `currentTx()` is the outbox seam. `{ retry: n }` (`As of 2026-08`) re-runs `fn` from the top on a `40001`/`40P01` and on nothing else — default 0, so `fn` must be idempotent before you ask for it |
+| `withTransaction()` / `currentTx()` | transaction scope; `currentTx()` is the outbox seam. `{ retry: n }` (`As of 2026-08`) re-runs `fn` from the top on a `40001`/`40P01` and on nothing else — default 0, so `fn` must be idempotent before you ask for it. Each re-run **waits first**, `As of 2026-08-23`: exponential from 10ms, capped at 500ms, full jitter (`@ultimat3/core`'s `backoffDelay`). A budget of 0 waits not at all |
 | `sqlState()` / `sqlStateCode()` / `isRetryableState()` / `SQLSTATE` | `As of 2026-08`: the SQLSTATE a driver error carries, and the closed table from it to a code. `Bun.SQL` puts it on `errno`; PGlite puts it on `code`; **one** reader answers for both |
 | `migrate()` / `rollback()` / `readLedger()` | the `x_migrations` ledger |
 | `statementsOf()` | `As of 2026-08`: a SQL script → the statements a driver sends one at a time. One send is one statement, so `migrate()` splits with this — a `;` inside a literal, an identifier, a dollar-quoted body or a comment is data |
@@ -316,6 +316,14 @@ always on the error and nothing read it, so a `23505` from two clicks racing a s
 "cannot reach the database" and paged on-call for an outage that never happened. The table
 (`sqlstate.ts`) is closed; everything outside it is still `X_DB_UNAVAILABLE`, unchanged.
 
+**Four of them carry `retry: "retryable"` in `--json`, `As of 2026-08-23`** — `DB_ERROR_RETRY`:
+`X_DB_SERIALIZATION_FAILURE`, `X_DB_LOCK_TIMEOUT`, `X_DB_POOL_EXHAUSTED`, `X_MIGRATE_CONCURRENT`.
+Each is a resource that frees, so the same call has a real chance of a different answer with no edit
+in between. Everything else keeps core's fail-closed `terminal`, and is deliberately left
+UNREGISTERED rather than registered as terminal: `@ultimat3/jobs` dead-letters a registered
+`terminal` on attempt 1, so classifying `X_DB_UNAVAILABLE` that way would dead-letter every in-flight
+job the moment Postgres fails over.
+
 | Code | Meaning |
 |---|---|
 | `X_DB_UNAVAILABLE` | no reachable database, or a SQLSTATE the table does not name; `fix:` names `DATABASE_URL` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "11.1.0",
+  "version": "11.2.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "11.1.0"
+    "@ultimat3/core": "11.2.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/errors.ts

@@ -2,9 +2,11 @@
 // fixes the situation — `X_DB_DRIFT` is the flagship and its rendering is byte-for-byte
 // pinned by the framework contract, so change its strings only with the contract.
 
+import type { ErrorRetry } from '@ultimat3/core';
 import {
   describeValue,
   registerErrorCodes,
+  registerErrorRetry,
   renderThrowable,
   stringField,
   UltimateError,
@@ -80,6 +82,60 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(DB_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
 
+/**
+ * May a client run this again? Unclassified means `terminal` — core fails closed — and until
+ * 2026-08-23 this package classified nothing, so `X_DB_SERIALIZATION_FAILURE` reached every HTTP
+ * client carrying `retry: "terminal"` while its own `fix:` line read
+ * `withTransaction(fn, { retry: 3 })`. The document contradicted the instruction beside it.
+ *
+ * The rule, stated once: **retryable means the same call, made again, has a real chance of a
+ * different answer, with no edit in between.** A resource that frees qualifies — a lock, a
+ * connection, a serialization race, another migrator's advisory lock. A statement about the data or
+ * about this deployment's configuration does not.
+ *
+ * **Only the exceptions are listed**, which is core's own `CORE_ERROR_RETRY` shape and not
+ * `@ultimat3/scraping`'s exhaustive one, for a reason specific to this package: a REGISTERED
+ * `terminal` is read by `@ultimat3/jobs` as "dead-letter on attempt 1"
+ * (`retry-classification.ts`), where an unclassified code keeps the attempt count. Registering
+ * `X_DB_UNAVAILABLE: 'terminal'` — defensible on the client side, since four of its six throw sites
+ * are permanent config faults — would therefore dead-letter every in-flight job the moment Postgres
+ * fails over, which is the opposite of what that code means to a worker. A code that means two
+ * things to two readers stays unclassified until it is two codes.
+ */
+export const DB_ERROR_RETRY = {
+  // The canonical try-again. Postgres aborted one of two transactions precisely SO one of them can
+  // be re-run, and `withTransaction(fn, { retry })` is the framework's answer to it.
+  X_DB_SERIALIZATION_FAILURE: 'retryable',
+  // `55P03 lock_not_available` — `lock_timeout` fired while somebody else held the lock. The
+  // blocker commits or rolls back and the lock is free; nothing about the statement was refused.
+  X_DB_LOCK_TIMEOUT: 'retryable',
+  // Both halves are "no connection RIGHT NOW": the server's `53300`/`53200` and this pool's own
+  // acquire timeout. A slot frees when an in-flight unit of work finishes. Not `retry-after`, which
+  // is the spelling for a responder that NAMED a time — nothing here carries `retryAfterSeconds`,
+  // and inventing a number for `Retry-After` would be a guess presented as an answer.
+  X_DB_POOL_EXHAUSTED: 'retryable',
+  // Another migrator holds the advisory lock and will let it go when it finishes. This is the one
+  // code here a deploy pipeline reads: a `ROLE=migrate` job that exits non-zero on it should come
+  // back, which is what `backoffLimit` already does, and `terminal` said not to.
+  X_MIGRATE_CONCURRENT: 'retryable',
+} as const satisfies Readonly<Partial<Record<DbOwnedErrorCode, ErrorRetry>>>;
+
+// `Partial`, so the table may be a SUBSET — but every key is still checked against the owned set, so
+// a typo or a renamed code is a build error rather than a classification for a code nothing throws.
+//
+// Left to the fail-closed default, deliberately, each for its own reason:
+//   X_DB_UNAVAILABLE            two failures in one code — see the note above
+//   X_DB_STATEMENT_TIMEOUT      `57014`, and this package's fix for it is "add the index": an edit.
+//                               The queued-behind-a-lock case has its own code, above
+//   X_DB_UNIQUE_VIOLATION       the same row, the same constraint, the same refusal
+//   X_DB_FOREIGN_KEY_VIOLATION  the parent it names is still gone
+//   X_DB_DRIFT, X_MIGRATION_*, X_SQL_UNSAFE, X_BRANCH_EXISTS
+//                               author-time and deploy-time faults; every fix is a command or an edit
+//
+// The borrowed codes are absent for a different reason: `registerErrorRetry` refuses a code the
+// framework owns, and `X_ENV_MISSING` / `X_INVARIANT` belong to core, which classifies its own.
+registerErrorRetry(DB_ERROR_RETRY);
+
 export interface DbErrorInit {
   readonly code: DbErrorCode;
   readonly cause: string;

package/src/index.ts

@@ -61,6 +61,7 @@ export {
   branchExists,
   branchNameInvalid,
   DB_ERROR_CODES,
+  DB_ERROR_RETRY,
   DB_ERROR_TITLES,
   DbError,
   dbDrift,

package/src/transaction-backoff.ts

@@ -0,0 +1,43 @@
+// Single responsibility: how long a lost serialization race waits before `withTransaction` re-runs
+// `fn`. The curve is `@ultimat3/core`'s — this file is the two constants, and the case for them.
+
+import { backoffDelay, type Random } from '@ultimat3/core';
+
+/**
+ * A serialization conflict is CONTENTION, not overload, and the constants say so.
+ *
+ * `base: 10` — the transaction that won the race is already committing, and one round trip to a
+ * Postgres in the same network is under 2ms. A provider-outage base (`@ultimat3/ai` uses 500ms,
+ * `@ultimat3/jobs` a second) would put a `retry: 8` budget seconds past the deadline of the request
+ * it is serving, which turns a recovered transaction into a timed-out one.
+ *
+ * `max: 500` — this loop runs on a request's critical path, holding a connection nothing else can
+ * use. The eight-attempt worst case is under a second of waiting; a minute-long ceiling would be a
+ * queue's, and a queue can afford one because nobody is waiting on the other end.
+ *
+ * `full` jitter — the only mode that decorrelates. Two transactions that just deadlocked are, by
+ * construction, two callers whose retries would otherwise be scheduled at the same offset from the
+ * same event, and re-colliding is the failure this wait exists to prevent. `equal` keeps a latency
+ * floor for a client that must not be starved, which is not this.
+ */
+export const TRANSACTION_RETRY_BACKOFF = {
+  base: 10,
+  max: 500,
+  curve: 'exponential',
+  jitter: 'full',
+} as const;
+
+/**
+ * Milliseconds before attempt `attempt + 1`. 1-based, like core's, and `random` is injected so the
+ * schedule is a list a test can assert rather than a range it can only sample.
+ */
+export function serializationRetryDelayMs(attempt: number, random?: Random): number {
+  return backoffDelay({
+    attempt,
+    base: TRANSACTION_RETRY_BACKOFF.base,
+    max: TRANSACTION_RETRY_BACKOFF.max,
+    curve: TRANSACTION_RETRY_BACKOFF.curve,
+    jitter: TRANSACTION_RETRY_BACKOFF.jitter,
+    random,
+  });
+}

package/src/transaction.ts

@@ -3,11 +3,13 @@
 // the transactional outbox is only atomic because `currentTx()` finds this store. Nesting maps
 // to SAVEPOINTs, so an inner failure never silently aborts the outer unit of work.
 
+import type { Random } from '@ultimat3/core';
 import { assert, asyncContext, nanoid } from '@ultimat3/core';
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
 import { isolationLevelInvalid, serializationExhausted } from './errors';
 import { raw, type SqlFragment } from './sql';
 import { isRetryableState } from './sqlstate';
+import { serializationRetryDelayMs } from './transaction-backoff';
 
 export interface DbTx extends DbClient {
   readonly id: string;
@@ -56,8 +58,17 @@ export interface TransactionOptions {
    *
    * **`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;
 }
 
 interface TxState {
@@ -263,6 +274,9 @@ export async function withTransaction<T>(
   }
 
   const attempts = (options.retry ?? 0) + 1;
+  // `Bun.sleep`, never a `node:timers` import: this is the runtime's own, and `migrate.ts` polls
+  // the advisory lock through the same call.
+  const sleep = options.sleep ?? ((ms: number): Promise<void> => Bun.sleep(ms));
   let last: unknown;
   for (let attempt = 1; attempt <= attempts; attempt += 1) {
     try {
@@ -278,6 +292,12 @@ export async function withTransaction<T>(
       // who has no budget.
       if (attempts === 1) throw error;
       last = error;
+      // Jittered, and only between attempts. Re-running instantly is what this loop did until
+      // 2026-08-23, and it is the deadlock reproduced rather than resolved: both losers wake in the
+      // same microsecond, take the same locks in the same order, and one of them loses again — so a
+      // budget of 8 was spent inside a single round trip's worth of wall clock. Nothing waits after
+      // the LAST attempt: there is nothing behind it to give the contention room for.
+      if (attempt < attempts) await sleep(serializationRetryDelayMs(attempt, options.random));
     }
   }
   throw serializationExhausted(attempts, last);