@ultimat3/db 6.0.0 → 8.0.0

package/CLAUDE.md

@@ -14,6 +14,7 @@ reaches down to this package for it. **Never** import `entity`, `jobs`, `http` o
 | Reading a caught value | `renderThrowable()` from core; never `error instanceof Error ? error.message : String(error)` — both halves RUN app code (a `Proxy` trap, `Symbol.toPrimitive`) and `checkDb` backs `/readyz`, where a render that throws is an exception in place of the report the kubelet asked for |
 | Errors | subclass `DbError`; never `throw new Error` **in source**. A test simulating a *database* failure throws `dbUnavailable()`; a test simulating the *caller's body* failing throws a bare `Error` on purpose — an arbitrary throw is exactly what rollback and disposal must survive, and a `DbError` there would prove the narrower thing |
 | New code | add to `DB_ERROR_CODES` **and** `DB_ERROR_TITLES` in `errors.ts` |
+| A value ambient across an `await` | `asyncContext<T>(subject)` from `@ultimat3/core` — never `new AsyncLocalStorage`. Three scopes here use it: `transaction.ts`, `attribution.ts`, `expected-loop.ts` |
 | Exports | explicit in `src/index.ts`; no `export *` |
 | Files | < 200 LOC, one responsibility, `kebab-case.ts`, test beside source |
 
@@ -28,6 +29,22 @@ Deliberate cycle (safe — nothing is referenced at module-evaluation time):
 consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`, or it would re-enter
 itself. Keep both sides `function` declarations so hoisting covers the TDZ.
 
+**The three ambient scopes open through core's one lazy seam, and that is a build error rather than
+a convention, `As of 2026-08`.** `transaction.ts` (`TxState`), `attribution.ts` (the entity/op
+pair) and `expected-loop.ts` (the reason) each constructed a module-scope `AsyncLocalStorage` until
+issue #255 closed it. A bundler stubs `node:async_hooks` to `{}` — Bun's `target: 'browser'` emits
+`var { AsyncLocalStorage } = (() => ({}))` — so the `new` threw
+`TypeError: undefined is not a constructor` at module **evaluation**, before any app code ran, and
+took every importer of that file down with it. Through `asyncContext<T>(subject)` the module
+evaluates, `get()` answers `undefined` (in a browser nothing IS in flight, so that is the true
+answer) and `run()` throws `X_ASYNC_CONTEXT_UNAVAILABLE` naming the scope. Deferring the
+construction changes nothing a server can observe: the storage is built on the first `get()` or
+`run()` rather than at module load, and `getStore()` outside a scope answers `undefined` either
+way — one object per scope, on first use, in place of one at module evaluation.
+`scripts/async-context-guard.ts` refuses a `new AsyncLocalStorage` — and the import that binds the
+class, aliased or namespaced — anywhere but `packages/core/src/async-context.ts`, and
+`scripts/async-context-guard.test.ts` runs it over the tree in the gate's `unit` step.
+
 `pglite.ts` is a pool of exactly one: PGlite is a single session, so `reserve()` (backed by
 `pglite-turns.ts`) is what stops two concurrent `BEGIN`s becoming one transaction. Three rules
 hold it together and none is optional — the plain path takes a turn; a statement issued while a
@@ -45,7 +62,7 @@ seam `observe.ts` already draws.
 
 **The second rule fences on `inLiveTx()`, never on `currentTx() !== undefined`** — the two are
 different questions and reading the second as the first was a cross-transaction write. The
-`AsyncLocalStorage` store rides into every promise chain started inside `withTransaction`, so a
+async-context store rides into every promise chain started inside `withTransaction`, so a
 statement the app forgot to `await` still found a store after COMMIT, skipped the turn queue, and
 landed inside whichever unit of work held the single session next: measured `BEGIN`, `select 'inside
 tx'`, `COMMIT`, `BEGIN`, `select 'straggler'`, `select 'inside tx 2'`, `COMMIT` — committed by a
@@ -213,7 +230,7 @@ report and the return value cannot disagree about one statement.
 
 `attribution.ts` is `StatementEvent.attribution`'s producer: `withStatementAttribution(entity, op,
 fn)` runs `fn` with every statement it issues — at any depth, across every `await` — attributed to
-that pair, on an `AsyncLocalStorage` the same shape `expected-loop.ts` already uses. Four rules,
+that pair, on an async context the same shape `expected-loop.ts` already uses. Four rules,
 none optional. **Guard first** — it reads `statementObserver()` before touching the scope at all
 and, with nothing installed, hands straight to `fn`: one property read, one branch, no object
 allocated, on the path every statement in the process takes (axiom 6) — which is also why the pair
@@ -263,14 +280,14 @@ the process. The OTel `kind` is `client`; the database is the remote peer.
 
 `expected-loop.ts` is the **only** suppression mechanism, and the reason it is a scope rather than
 a pragma or a list is the same reason `observe.ts` is one observer: a second path is the tax
-(axiom 1). `expectedQueryLoop(reason, fn)` rides an `AsyncLocalStorage`, so it survives every
+(axiom 1). `expectedQueryLoop(reason, fn)` rides an async context, so it survives every
 `await` at any depth and two loops running concurrently never read each other; nesting keeps the
 innermost reason, because the closest scope is the one describing this loop. A blank reason is
 `X_INVARIANT` through core's `assert` — no new code for it, and an exemption with no argument is a
 pragma with extra steps. Three rules. **The funnel stamps, the consumer reads** — `runOn` and
 `statement()` call `expectedQueryLoopReason()` inside the branch that already found an observer and
 put the answer on the event as `expected`; a detector that judges a whole request runs long after
-every scope in it closed, so reading the ALS later would find nothing. **It suppresses a verdict,
+every scope in it closed, so reading the scope later would find nothing. **It suppresses a verdict,
 not a statement** — the SQL is still sent, still observed, and the span still opens, so anything
 that measures still sees the loop and only the thing that warns is told the author already
 answered. **It costs nothing uninstalled** — the read lives inside the observer branch, so the

package/README.md

@@ -261,7 +261,7 @@ reader cannot tell a considered loop from a silenced one.
 
 | | |
 |---|---|
-| Scope | an `AsyncLocalStorage`: it survives every `await` at any depth, and two loops running at once never read each other. Nesting keeps the innermost reason |
+| Scope | core's `asyncContext<string>('the expected-loop reason')`, never a `new AsyncLocalStorage` here: it survives every `await` at any depth, and two loops running at once never read each other. Nesting keeps the innermost reason |
 | What it carries | `StatementEvent.expected`, stamped by both funnels at settle time — a diagnostic judging a whole request runs after every scope in it closed |
 | What it suppresses | a **verdict**, never a statement. The SQL is still sent, still observed, still a span: only the thing that warns is told the author already answered |
 | What it costs | nothing without a diagnostic — the reason is read inside the branch that already checks for an installed observer |
@@ -270,6 +270,24 @@ The framework's own deliberate loops declare themselves at source: `migrate()` a
 (one transaction per migration, so a failure leaves an exact ledger) and `@ultimat3/admin`'s
 cross-entity search (one indexed lookup per text field).
 
+**Every ambient scope in this package opens through `asyncContext<T>(subject)` from
+`@ultimat3/core`** — the transaction store, the attribution pair and this reason — and none of the
+three constructs an `AsyncLocalStorage`, `As of 2026-08`. What changed is what a browser bundle
+does with these three modules: a bundler stubs `node:async_hooks` to `{}`, so the module-scope `new`
+threw `TypeError: undefined is not a constructor` at module **evaluation** — before a line of app
+code ran, and taking every importer of the file with it. Now the module evaluates, a read answers
+`undefined` (nothing is in flight in a browser, so that is the true answer), and a write throws
+`X_ASYNC_CONTEXT_UNAVAILABLE` naming the scope it could not open. A server saves no allocation —
+the store is built on the first `get()` **or** `run()`, so a read constructs it too. What the
+laziness costs is nothing observable: `getStore()` outside a scope answers `undefined` whether the
+storage was ever constructed or not. Not a claim that the whole package
+bundles: `pglite-branch.ts` imports `node:fs/promises`, which is a separate question.
+
+The rule is a **build error**, not a convention: `scripts/async-context-guard.ts` refuses a
+`new AsyncLocalStorage` — and the import that binds the class, aliased or namespaced — anywhere but
+`packages/core/src/async-context.ts`, and `scripts/async-context-guard.test.ts` runs it over the
+tree in the gate's `unit` step.
+
 ## A statement knows who compiled it
 
 `As of 2026-08`: `StatementEvent.attribution` is no longer always `undefined`.
@@ -282,7 +300,7 @@ return withStatementAttribution('members', 'findById', () =>
 
 | | |
 |---|---|
-| Scope | an `AsyncLocalStorage`, `expectedQueryLoop()`'s own shape: it survives every `await` at any depth, and nesting keeps the innermost pair |
+| Scope | core's `asyncContext<StatementAttribution>()`, `expectedQueryLoop()`'s own shape: it survives every `await` at any depth, and nesting keeps the innermost pair |
 | What it carries | `StatementEvent.attribution`, stamped by both funnels at settle time, next to `expected` |
 | Producer | `@ultimat3/entity`'s `postgresRepo` — the last caller that still knows the entity and the operation once the SQL exists |
 | What it costs | nothing uninstalled — `statementObserver()` is read first, and with nothing installed `fn` runs directly; no scope entered, no object allocated |

package/package.json

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

package/src/attribution.ts

@@ -3,13 +3,15 @@
 // instead of fifty copies of one `select`. A scope, not a parameter: the statement leaves several
 // frames and at least one microtask below the repository call that caused it.
 
-// `node:` for the same reason `expected-loop.ts` needs it — Bun exposes no native async-context
-// primitive, and the pair has to survive every `await` between the repository call and the
-// statement it causes. A module-scope variable would be shared by two concurrent requests.
-import { AsyncLocalStorage } from 'node:async_hooks';
+// The pair has to survive every `await` between the repository call and the statement it causes,
+// and a module-scope variable would be shared by two concurrent requests — so it needs an async
+// context. It opens through core's seam for the same reason `expected-loop.ts` does: constructing
+// an `AsyncLocalStorage` here threw at module EVALUATION in a browser bundle, where
+// `node:async_hooks` is stubbed to `{}`, taking every importer of `@ultimat3/db` down with it.
+import { asyncContext } from '@ultimat3/core';
 import { type StatementAttribution, statementObserver } from './observe';
 
-const storage = new AsyncLocalStorage<StatementAttribution>();
+const storage = asyncContext<StatementAttribution>('the statement attribution');
 
 /**
  * Run `fn` with every statement it issues — at any depth, across every `await` — attributed to
@@ -41,5 +43,5 @@ export function withStatementAttribution<T>(entity: string, op: string, fn: () =
  * same answer captured at the moment the statement settled.
  */
 export function statementAttribution(): StatementAttribution | undefined {
-  return storage.getStore();
+  return storage.get();
 }

package/src/client.ts

@@ -61,7 +61,7 @@ export interface PoolProfile {
 }
 
 /** Sized per role because the failure modes differ: RPS bursts vs. queue depth vs. run-once. */
-export const POOL_PROFILES: Readonly<Record<Role, PoolProfile>> = Object.freeze({
+export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
   web: {
     max: 20,
     statementTimeoutMs: 10_000,

package/src/errors.ts

@@ -121,7 +121,7 @@ export const dbUnavailable = (detail: string, sourceError?: unknown): DbError =>
  * named, so the fix points at the one index or key that refused the row rather than at the idea
  * of one; `driverError` substitutes the placeholder when the driver reported none.
  */
-const SQLSTATE_FIXES: Readonly<Record<DbSqlStateCode, string>> = Object.freeze({
+const SQLSTATE_FIXES = Object.freeze<Record<DbSqlStateCode, string>>({
   X_DB_UNIQUE_VIOLATION:
     'upsertAll(rows, { onConflict: [...] }) over the columns {constraint} covers — ' +
     'or catch X_DB_UNIQUE_VIOLATION and answer 409, which is what a raced signup is',

package/src/expected-loop.ts

@@ -3,13 +3,14 @@
 // A scope with a written reason — never a comment pragma and never a config list of exempt call
 // sites (axiom 1), because both put the argument somewhere other than the loop it defends.
 
-// `node:` because Bun exposes no native async-context primitive: the reason has to outlive every
-// `await` inside the scope, and `AsyncLocalStorage` is the only thing that carries a value across
-// them. A module-scope variable would be shared by two concurrent loops.
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { assert } from '@ultimat3/core';
+// The reason has to outlive every `await` inside the scope and a module-scope variable would be
+// shared by two concurrent loops, so it needs an async context — opened through core's one lazy
+// seam rather than a `node:async_hooks` construction here, which threw at module EVALUATION in a
+// browser bundle (the bundler stubs the module to `{}`) and took every importer of `@ultimat3/db`
+// with it.
+import { assert, asyncContext } from '@ultimat3/core';
 
-const storage = new AsyncLocalStorage<string>();
+const storage = asyncContext<string>('the expected-loop reason');
 
 /**
  * Run `fn` with every statement it issues — at any depth, across every `await` — marked expected
@@ -49,5 +50,5 @@ export function expectedQueryLoop<T>(reason: string, fn: () => T): T {
  * answer captured at the moment the statement settled.
  */
 export function expectedQueryLoopReason(): string | undefined {
-  return storage.getStore();
+  return storage.get();
 }

package/src/transaction.ts

@@ -3,8 +3,7 @@
 // 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 { AsyncLocalStorage } from 'node:async_hooks';
-import { assert, nanoid } from '@ultimat3/core';
+import { assert, asyncContext, nanoid } from '@ultimat3/core';
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
 import { serializationExhausted } from './errors';
 import { raw, type SqlFragment } from './sql';
@@ -79,11 +78,15 @@ interface TxState {
   readonly live: { value: boolean };
 }
 
-const storage = new AsyncLocalStorage<TxState>();
+// Core's one lazy seam, never a construction here: a module-scope `new` threw at EVALUATION in a
+// browser bundle, where the bundler stubs `node:async_hooks` to `{}`, and took every importer of
+// `@ultimat3/db` with it. `get()` still answers `undefined` outside a scope, so the server pays
+// nothing for the deferral.
+const storage = asyncContext<TxState>('a database transaction');
 
 /** The open transaction, or `undefined` outside one. `@ultimat3/jobs` calls this per enqueue. */
 export function currentTx(): DbTx | undefined {
-  return storage.getStore()?.tx;
+  return storage.get()?.tx;
 }
 
 /**
@@ -96,7 +99,7 @@ export function currentTx(): DbTx | undefined {
  * reservation, whose own `held` fence already re-queues them.
  */
 export function inLiveTx(): boolean {
-  return storage.getStore()?.live.value === true;
+  return storage.get()?.live.value === true;
 }
 
 export function beginStatement(options: TransactionOptions): string {
@@ -217,7 +220,7 @@ export async function withTransaction<T>(
     `withTransaction({ retry }) needs a whole number of extra attempts, 0 or more; a budget that is not one opens nothing and runs fn zero times`,
     "pass an integer — withTransaction(fn, { retry: 3, isolation: 'serializable' }) — and parse it before you pass it: Number(process.env.DB_RETRY) is NaN when the variable is unset",
   );
-  const outer = storage.getStore();
+  const outer = storage.get();
   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