@ultimat3/testing 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -13,18 +13,18 @@ is its own entry point and not part of the barrel.
 | Rule | Detail |
 |---|---|
 | No mocks of the DB | clone a template database; `template-db.ts` is the only DB path |
-| No wall clock | `frozenClock` / `advanceClock`; `Date.now()` is frozen by the preload |
+| No wall clock | `withFrozenClock` / `advanceClock`; `Date.now()` is frozen by the preload |
 | Frozen ≠ different | `globalThis.Date` becomes a subclass, so `FrozenDate[Symbol.hasInstance]` brands on the `[[DateValue]]` slot — `Date.prototype.getTime.call(value)` throws or it doesn't. |
 | Slot, not prototype | the brand is cross-realm on purpose: `instanceof RealDate` misses a `node:vm` or worker Date, and `Object.prototype.toString` is spoofable by `Symbol.toStringTag: 'Date'`. Only the slot is both |
-| No unmocked egress | `sealed-network.ts` patches fetch; a miss is `X_TEST_NETWORK_SEALED` |
+| No unmocked egress | `sealed-network.ts` seals `fetch`; `sealed-sockets.ts` `WebSocket`, `Bun.connect` (not loopback); a miss is `X_TEST_NETWORK_SEALED` |
 | Self is not egress | a port core's `markListening()` announced passes through — a socket test never unseals |
-| Offline is a state, not a mock | `network.offline()` / `.drop()` fail every request as `X_TEST_NETWORK_OFFLINE`, ahead of the mocks — the app's own offline path runs |
+| Offline is a state, not a mock | `network.offline()` / `.drop()` fail every dial, loopback too, as `X_TEST_NETWORK_OFFLINE` before any mock: the app's offline path runs |
 | One way offline | the `network` fixture. `setNetworkState` is the gate's only writer and is not exported — setting it from a test body skips the fixture's disposal and leaves every later file offline |
-| The seal key is a test process's, and nobody's export | `test-seal-key.ts`: installed by the preload only when `NODE_ENV === 'test'` and neither `ULTIMATE_SECRETS_KEY` nor `.secrets.key` exists; `startE2eApp` hands it to the child by VALUE (`testSealKeyEnv`), because the spawned app is a server and must never be able to install one. The constant is module-private and off the barrel (`test-seal-key.test.ts`). Never loosen the `NODE_ENV` check: the key is public |
+| The seal key is a test process's, and nobody's export | `test-seal-key.ts`: installed by the preload only when `NODE_ENV === 'test'` and neither `ULTIMATE_SECRETS_KEY` nor `.secrets.key` exists; `startE2eApp` hands it to the child by VALUE (`testSealKeyEnv`): a spawned server must never install one. The constant is module-private and off the barrel (`test-seal-key.test.ts`). Never loosen the `NODE_ENV` check: the key is public |
 | `toEqualRow` never prints a server-only value | `matcher-row.ts` compares every OWN property (`toEqual` cannot see a `.sealed()` column — empty diff). A non-enumerable property that differs is NAMED; its value and its length stay out of the message, which lands in CI logs |
 | No retries | a flake is fixed or deleted the day it flakes; there is no `retry: 3` |
 | A mutator's `local()` runs against `memoryLocalTx()` | `local-tx.ts`: keyed rows with the record store's rules (update invents nothing, `undefined` leaves a column, rows frozen). Never a hand-rolled table per test |
-| A page test RENDERS, with no cast | `render-view.ts`: `renderRoute(module, { url, actor })` resolves `load` once and hands `meta` and the page that one object, as every render mode does; `renderView(Component, props)` is one component. `@ultimat3/render` is imported INSIDE both, never at module scope — the barrel is what a tier-0 test imports for `expect` |
+| A page test RENDERS, with no cast | `render-view.ts`: `renderRoute(module, { url, actor })` resolves `load` once and hands `meta` and the page that one object, as every render mode does; `renderView(Component, props)` is one component. `@ultimat3/render` is imported inside both, never at module scope: a tier-0 test imports this barrel |
 | `toBeUltimateError` reads THREE fields | an `X_` code plus a `cause` plus a `fix`, all through core's `stringField`. `typeof value.code === 'string'` alone passed a Node `ENOENT` |
 | One matcher WAITS, and it is `toBeVisible` | `await expect(locator).toBeVisible()` retries `isVisible()` to a budget — 5000ms every 100ms, Playwright's own default, narrowable per call. |
 | The budget is counted in LOOKS, not milliseconds | this package freezes `Date.now()`, so a deadline computed from the clock never expires and the loop spins forever. `attemptsFor(budget)` is `1 + floor(timeout / interval)` |
@@ -36,7 +36,7 @@ is its own entry point and not part of the barrel.
 | Test names | the filename picks the step; a typed helper prefixes its own name. `testName(type, name)` is for an outer `describe` only — never on the inner `test` too, the prefix would print twice |
 | One body shape, five registrars | `test` (= `fixtureTest`), `unitTest`, `contractTest`, `liveTest`, `jobTest` all take `FixtureBody` + `{ timeoutMs }`: `unitTest('…', async ({ runJobs }) => …)`. Never `describe(testName('unit', …))` + `test` to get a fixture |
 | `runJobs` says who and what | `{ actor }` is the WORKER's identity (the org stays the job's declared tenant), `{ tenantId }` the enqueuer's row; `executions[n].result` is the body's return. A fresh event bus per fixture |
-| A `runJobs` pass is a real worker's `tick()` | `fixture-jobs.ts` builds an unstarted `createWorker` per pass, so admission runs: `concurrency` waits and `whenBusy: 'fail'` refuses (`X_JOB_KEY_BUSY`) exactly as in a fleet. Never `executeJob` on a bare `claim()`. The lease and slot renew every 1 ms of TEST time (`RENEW_MS`, `frozen-scheduler.ts` on `onClockMoved`), never on a wall-clock interval: cancel, `clock.advance(1)`, and the body hears `X_JOB_LEASE_LOST` — no hand-built worker |
+| A `runJobs` pass is a real worker's `tick()` | `fixture-jobs.ts` builds an unstarted `jobWorker` per pass, so admission runs: `concurrency` waits and `whenBusy: 'fail'` refuses (`X_JOB_KEY_BUSY`) exactly as in a fleet. Never `executeJob` on a bare `claim()`. The lease and slot renew every 1 ms of TEST time (`RENEW_MS`, `frozen-scheduler.ts` on `onClockMoved`), never on a wall-clock interval: cancel, `clock.advance(1)`, and the body hears `X_JOB_LEASE_LOST` — no hand-built worker |
 | Per-test state is `per-test-reset.ts` | the app preload's `beforeEach` resets the jobs event bus — only when `@ultimat3/jobs` is already loaded, so a core test never loads it |
 | An island test is `describeIslandState` | one block per declared state: mounted in `beforeAll` (60 s), disposed in `afterAll`, one build per file. `mountIslandState` + `using` for one test's own mount; an undeclared id is `X_TEST_ISLAND_STATE_UNKNOWN` |
 | An authenticator is tested with `authRequest()` | the hook's own two arguments, real — never `as unknown as Parameters<…>` |
@@ -72,20 +72,21 @@ is its own entry point and not part of the barrel.
 | Teardown restores, never uninstalls | `describeApp`/`testApp` capture the seal and the determinism snapshot before booting and put those back |
 | Teardown is a `finally` | an `app.close()` that rejects still reaches `db.drop()` and still restores the process state; the first failure is what the caller sees. |
 | A boot that rejects is its own teardown | `acquireWorkerDatabase`, `seed` or `boot` throwing returns no `BootedHarness`, so no caller can ever reach `close()` |
-| A found template is not a migrated one | `template-db.ts` tolerates "already exists" for the `CREATE DATABASE` alone. `config.migrate` runs unconditionally and un-swallowed |
+| A found template is not a migrated one | `template-db.ts` tolerates "already exists" for the `CREATE DATABASE` alone. `config.migrate` runs unconditionally; drop + clone hold the same lock |
 | Fixture teardown | a fixture that installs process-global state (the ambient job or mail driver) implements `Symbol.dispose` / `Symbol.asyncDispose` and restores what was there |
-| Building one by hand | `createRunJobs()` outside a fixture body is not disposed for you — dispose it in `afterEach`, or the next file inherits your queue and your event bus |
+| Building one by hand | `testJobs()` outside a fixture body is not disposed for you — dispose it in `afterEach`, or the next file inherits your queue and your event bus |
 | Factory strategy | an association is built with the strategy that asked for it: `build()` never reaches a database, `create()` writes the parent first. Never a third strategy |
 | One write seam | `usePersister` is the only place `create()` writes. A factory that took a repo argument would put the seam at every call site |
 | Factory seeds | derived from the table name unless given, so two entities never draw the same uuid stream. `reset()` cascades into associated parents — a half-reset row is worse than none |
 | Shared examples | `behavesLike` calls `describe`, so it goes at declaration scope; bun rejects a `describe` inside a test body |
+| A port's contract is shared examples | `jobDriverConformance`, `budgetStoreConformance` — `behavesLike(…, () => yours)` |
 | An island needs a BUILDER, not an import | `buildIslands` is `@ultimat3/cli`'s and both packages are tier 5; the one declared edge is `cli → testing`, so the reverse is a `bun run boundaries` failure. |
 | `mountIsland` AWAITS `mount` | `IslandEntry['mount']` returns `unknown`, not `void`, and the call is awaited |
 | Dispose STOPS the island, then restores the globals | when `mount` resolved to a function, `[Symbol.dispose]` calls it BEFORE `restore()` |
-| The micro-DOM is the fixture's, once **for islands** | `island-dom.ts`. `packages/ui/src/fake-dom.ts` is a second one for keyboard code, and `ui -> testing` is upward, so it is not a copy to collapse. `bun test` has no DOM and no DOM library may be added |
+| The micro-DOM is the fixture's, once **for islands** | `island-dom.ts`. `packages/ui/src/fake-dom-fixture.ts` is a second one for keyboard code, and `ui -> testing` is upward: not a copy to collapse. `bun test` has no DOM and no DOM library may be added |
 | `style` and `classList` RECORD | `FakeStyle` is one declaration map behind all four spellings compiled Solid uses (static attribute, `setProperty`, `cssText`, `removeAttribute`), so a test can assert the component set `--form-gap` |
-| `classList` is the class attribute | not a list of its own, so `classList.toggle` — what the compiler emits INLINE for `classList={{ … }}`, with no runtime helper in front of it — and `className` can never answer one element two ways. |
-| A `document` listener is the documentElement's | no bubbling: `document.addEventListener` registers on `documentElement`, and `fire(mounted.documentElement, 'keydown', …)` drives it. One handler per type, last wins |
+| `classList` is the class attribute | not a list of its own, so `classList.toggle` — which the compiler emits INLINE for `classList={{ … }}`, no runtime helper between — and `className` can never answer one element two ways. |
+| A `document` listener is the documentElement's | no bubbling: `document.addEventListener` registers on `documentElement`, and `fire(mounted.documentElement, 'keydown', …)` drives it. Every listener per type runs; removal is by function identity |
 | `querySelector` skips `this` | descendants only, as the DOM's does. Matching the element it is called on made a host `<div>` answer `find('div')` with the container the test built rather than the markup the island rendered |
 | The selector grammar is SMALL and REFUSES | `island-selector.ts`: compounds of tag, `#id`, `.class`, `[attr]`, `[attr="value"]`, joined by space or `>`. Anything else is `X_TEST_ISLAND_SELECTOR_UNSUPPORTED` with the offset, never an empty answer |
 | The box is 0 until a test writes it | `clientHeight`, `scrollTop`, `scrollHeight` and the rest are writable numbers, default 0; `getBoundingClientRect()` derives from the offset box |
@@ -102,16 +103,14 @@ is its own entry point and not part of the barrel.
 | Loose in, strict out | `findIslandStates` resolves `Settings`, `settings`, `settings.island.tsx` and the full path to one manifest, and refuses a name nothing answers to by listing EVERY valid one |
 | The disk check is not in `defineIslandStates` | a declaration evaluates wherever it is imported from, so a rule that reads the filesystem at import time fails on the cwd rather than on the path. |
 | The island EXTENSION is not restated here | `.island.tsx` is `@ultimat3/render`'s `ISLAND_EXTENSION` and `render` is not a dependency of this package. |
-| The chunk is imported from a temp FILE | named by its SHA-256, so an edit is a new module and nothing is left in the app. Never a `data:` URL: `bun test --coverage` panics importing one past ~4 kB (Bun 1.4.0); `fixture-island.test.ts` pins it |
-| The scratch directory is lazy and removed | made on the first mount, deleted on `exit`; never at module scope — this module is on the `.` barrel |
+| A mount imports from its own temp DIRECTORY | `island-scratch.ts`: per mount (identical chunks stay two modules); removed on dispose, at the file boundary and in the run's `afterAll` — `exit` never fires under `bun test`. Never a `data:` URL (coverage panics past ~4 kB) |
 | Attaching a node MOVES it | `appendChild`, `insertBefore`, `replaceChild` detach it from its old parent first; `removeChild` clears `parentNode` |
-| Globals install all-or-nothing | `installGlobals` saves DESCRIPTORS, not values — a saved value cannot tell "no such global" from "a global holding `undefined`", and the teardown deleted both |
-| Which command shards | `bun test` is one process on one database, and that is still what a scaffolded app's `test` script runs. |
-
+| Globals install in layers | `island-globals.ts`: a key's real DESCRIPTOR is saved by the first live mount, restored by the last, in any dispose order |
+| Which command shards | `bun test` is one process on one database — what a scaffolded app's `test` script runs |
 
 ## The frozen instant and the seed are screened
 
-`installDeterminism({ now })`, `setFrozenClock`, `frozenClock` and `advanceClock` go through one
+`installDeterminism({ now })`, `setFrozenClock`, `withFrozenClock` and `advanceClock` go through one
 `instantMs`: an unreadable instant would make `Date.now()` answer `NaN` for every later file. The
 seed is screened too — `seed >>> 0` maps `NaN`, `0.5` and `2 ** 32` onto seed 0 silently.
 `finiteOption`/`finiteCount` from `@ultimat3/core` are the one form; `determinism-bounds.test.ts`
@@ -145,11 +144,12 @@ lives beside the `PageLike` it implements. `cli` imports it over the declared `c
 | `e2e-errors.ts` | one constructor per refusal |
 | `e2e-dom-fixture.ts` | a document small enough to hold in a test and real enough to RUN the expressions above |
 | `cdp-browser.ts` | the two doors: `openE2eBrowserIfAvailable()` (undefined when there is no browser) and `openE2eBrowser()` (refuses by name), and the close that undoes both halves |
-| `cdp-launch.ts` | which Chrome, and starting it — the candidate list, the flags, and the endpoint read off its stderr |
-| `cdp-connection.ts` | CDP over Bun's own `WebSocket`: request framing, reply correlation by `id`, one-shot event waiters, the per-call deadline |
+| `cdp-launch.ts` | which Chrome, its flags, the launch deadline (`LAUNCH_TIMEOUT_MS`, 60 s — a cold start is not a call) and the ONE relaunch (`LAUNCH_ATTEMPTS`) |
+| `cdp-launch-attempt.ts` | one start in its own group; on no answer a full reap (group, then profile + singleton dir: `cdp-launch-profile.ts`). ONE awaited `close()` |
+| `cdp-connection.ts` | CDP over a transport — the launched Chrome's pipe (`cdp-pipe.ts`), a remote one's `WebSocket` (`cdpConnect`): reply correlation by `id`, event waiters, the per-call deadline; why one went unanswered is `cdp-wire-watch.ts` |
 | `cdp-e2e-session.ts` | the BROWSER half, `E2eSession`: every target auto-attached at browser level and PAUSED until its Network domain is on (a SharedWorker opens its socket at start-up) |
 | `cdp-e2e-page.ts` | one TAB, `E2eTab`: `E2eBrowserPage`'s five methods plus `reload`, `waitFor`, `indexedDbNames`, `close`. `offline()` forwards to the session — the switch is browser-wide |
-| `e2e-app.ts` | `startE2eApp({ root, mode, seed })`: reset + seed + spawn on a THROWAWAY `ULTIMATE_STATE_DIR` and free ports, `/readyz`-gated, spawned through the app's own `@ultimat3/cli` bin (`xBin`); `stop()` removes the directory |
+| `e2e-app.ts` | `startE2eApp({ root, mode, seed })`: reset + seed + spawn on a THROWAWAY `ULTIMATE_STATE_DIR` and free ports a browser opens (`free-port.ts`), `/readyz`-gated, spawned through the app's own `@ultimat3/cli` bin (`xBin`); `stop()` removes the directory |
 | `failure-context.ts` | a FAILED test's message ends with the e2e app's last 40 log lines (≤ 4 kB): `e2e-run.ts` installs `app.log()`, `fixtureTest` and `e2eTest` append it. Never on a pass |
 | `e2e-preload.ts` + `e2e-browser-handle.ts` | the `e2e` step's preload (`@ultimat3/testing/e2e-preload`): with `ULTIMATE_E2E_ROOT` set it spawns the app, opens ONE browser, installs its first tab, and publishes `e2eBrowser()`, `e2eApp()`, `e2eBaseUrl()` |
 | `packages/cli/src/verify-e2e.ts` | `withE2eApp` (cli's): in an app on a machine with Chrome, the `e2e` step runs the suite with that preload; otherwise exactly as before |

package/README.md

@@ -10,7 +10,8 @@ frozen clock. Never let a test reach the network unmocked — it fails by design
 | `harness.ts` | `describeApp()` / `testApp()` — boot an app in-process with its own database |
 | `template-db.ts` | N workers, N databases, one migrated template, `CREATE DATABASE ... TEMPLATE` |
 | `determinism.ts` | frozen clock, seeded RNG, seeded uuids, `assertDeterministic` |
-| `sealed-network.ts` | any unmocked egress fails, with the URL and the mock line |
+| `sealed-network.ts` | any unmocked `fetch`, `WebSocket` or `Bun.connect` egress fails, with the URL and the line that fixes it |
+| `sealed-sockets.ts` | the `WebSocket` and `Bun.connect` patches, behind `sealed-network.ts`'s one gate |
 | `factories.ts` | `defineFactory` — seeded rows, traits, associations, `build` vs `create` |
 | `factory-registry.ts` | `factoriesFor(registry)` — one factory per entity, defaults read off column names |
 | `factory-persist.ts` | `usePersister` — the one seam `create()` writes through |
@@ -39,9 +40,9 @@ frozen clock. Never let a test reach the network unmocked — it fails by design
 | `island-states-resolve.ts` | a name a reader typed → the manifest it meant; a manifest → the island file it claims |
 | `framework-fixtures.ts` | registers both sets; the app registers only what it owns |
 | `registry-leak-guard.ts` | fails the run naming the FILE that left a process-global registry dirty, and restores the ones that can be restored at the same boundary |
-| `registry-snapshot.ts` | `captureProcessRegistries()` / `restoreProcessRegistries()` — the locale config, the catalogs, the permission set and the role map, put back as a file inherited them. A module-scope declaration evaluates once per process (`bun test` without `--isolate`, `As of 2026-08`), so a neighbour's `clearPermissions()` is otherwise permanent |
+| `registry-snapshot.ts` | `captureProcessRegistries()` / `restoreProcessRegistries()` — the locale config, the catalogs, the permission set, the role map, the tasks and the declared measurement actor, put back as a file inherited them. A module-scope declaration evaluates once per process (`bun test` without `--isolate`, `As of 2026-08`), so a neighbour's `clearPermissions()` is otherwise permanent |
 | `registry-isolation.ts` | `isolateEntityRegistry()` — an empty entity registry, and the process's back after. Its own entry point (`@ultimat3/testing/registry-isolation`), never the barrel: it value-imports `@ultimat3/entity`, and the barrel is what a tier-0 test imports for `expect` |
-| `quiet-logs.ts` | a green run prints the reporter and nothing else: the framework's log lines go to a sink that drops them. `LOG_LEVEL=info bun test <file>` shows them — naming `LOG_LEVEL` is the one escape hatch, and a level above `info` filters what the TERMINAL shows, never what the logger emits (below). A test asserting on log output hands `createLogger({ level, writer })` its own writer, or installs its own `setLogSink` and restores the previous one |
+| `quiet-logs.ts` | a green run prints the reporter and nothing else: the framework's log lines go to a sink that drops them. `LOG_LEVEL=info bun test <file>` shows them — naming `LOG_LEVEL` is the one escape hatch, and a level above `info` filters what the TERMINAL shows, never what the logger emits (below). A test asserting on log output hands `structuredLogger({ level, writer })` its own writer, or installs its own `setLogSink` and restores the previous one |
 | `preload.ts` | the bunfig preload that installs all of the above |
 
 ## Install
@@ -93,7 +94,7 @@ with `{ runJobs }` — never `describe(testName('unit', …))` around a bare `te
 | `network` | `offline()` · `drop()` · `online()` · `state()` over the sealed network | the preload |
 | `runJobs` | a worker: call it to enqueue+drain, then `enqueue()` `drain()` `due()` `inFlight()` `depth()` — see [below](#a-job-under-runjobs) | the preload |
 | `statements` | every statement the test issued: `all()` `count(fingerprint?)` `shapes()` — and an N+1 throws | the preload |
-| `page` | the browser: `goto` `gotoStreamed` `getByRole` `evaluate` `waitForServiceWorker` | a browser driver |
+| `page` | the browser: `goto` `gotoStreamed` `getByRole` `evaluate` `waitForServiceWorker({ timeoutMs? })` — an uncontrolled first page is reloaded once for its worker (`e2e-service-worker.ts`) | a browser driver |
 | `budget` | `jsBytes(route)` measured off the built output | a browser driver |
 | `signIn` | put the browser session in a member's shoes | a browser driver |
 | `deploy` | `newBuild()` — same app, new build id, page still open | a browser driver |
@@ -160,7 +161,7 @@ unitTest('the sweep runs as the billing worker', async ({ runJobs }) => {
 | **`{ actor }`** | on the call and on `drain()`: the identity the WORKER runs as — what an app wires through `WorkerOptions.context()`. Its org is replaced by the job's declared tenant, as a real worker's is; `tenant: 'none'` strips it. Absent is core's anonymous actor |
 | **`{ tenantId }`** | on the call and on `enqueue()`: the ENQUEUER's tenant on the row — the limiter's bucket and the dedupe namespace, the half of `handle.as(actor, input)` that reaches the queue. Never the tenant the body runs under: that is the job's own `tenant:` |
 | **one event bus per fixture** | `step.waitForEvent` reads an ambient bus that STORES; the fixture installs a fresh one and hands the process's back, so one test's `publishEvent` cannot resume the next test's run |
-| **a real worker's pass** | each round is `createWorker(...).tick()`: admission, the limiter and keyed `concurrency` (`whenBusy: 'fail'` settles `refused`, `X_JOB_KEY_BUSY`) hold exactly as in production |
+| **a real worker's pass** | each round is `jobWorker(...).tick()`: admission, the limiter and keyed `concurrency` (`whenBusy: 'fail'` settles `refused`, `X_JOB_KEY_BUSY`) hold exactly as in production |
 | **a cancel reaches a running body** | the worker renews its lease on the TEST clock — every millisecond of it — and a renewal that misses the row aborts `ctx.signal` with `X_JOB_LEASE_LOST`: start `runJobs.drain()`, cancel the row (`cancelJob(jobDriver(), id)` or the app's own action), `clock.advance(1)`, await the drain. No hand-built worker, no sleep, no wall-clock timer |
 
 ## An N+1 fails the test it happened in
@@ -217,6 +218,14 @@ It registers `page` and nothing else. `budget`, `signIn` and `deploy` keep refus
 browser's own network state and a second build id are not things a page port can answer for, and a
 fixture that silently no-opped would make the assertion after it read as proof.
 
+**A browser call that is never answered says why.** `X_CDP_TIMEOUT` from the connection carries
+`meta.reading` — `target-gone` (session detached, target destroyed or crashed), `lost-in-transport`
+(`meta.framesDropped` frames arrived unparseable after the call) or `no-answer` — beside
+`framesArrived`, `lastFrames` (the last 8), `transportOpen` and `navigations`; `cause` is the
+one-line reading. `E2eSession.offline(false)` rejects with `X_CDP_CALL_FAILED` when a page that is
+still there refuses to take `navigator.onLine` back: the restore is attempted regardless, and the
+page stays in the set.
+
 Each helper prefixes the test name with its type (`job · onboards an org`), which is what
 `bun test --test-name-pattern "job · "` selects — the six lines of `x verify` come from the tests
 themselves, not from a directory convention.
@@ -271,14 +280,36 @@ failure line reads `publishPost > behaves like an authenticated action > denies
 — which subject, and which shared rule. `behavesLike` calls `describe`, so it goes at declaration
 scope, never inside a test body.
 
+Two ship, for the ports an app may implement itself — a `JobDriver` and `@ultimat3/ai`'s
+`BudgetStore`:
+
+```ts
+import { memoryBudgetStore } from '@ultimat3/ai';
+import { memoryJobDriver } from '@ultimat3/jobs';
+import { behavesLike, budgetStoreConformance, describe, jobDriverConformance } from '@ultimat3/testing';
+
+// The shipped ports pass; put your own driver or store where these are.
+describe('my queue', () => behavesLike(jobDriverConformance, () => memoryJobDriver()));
+describe('my budget store', () => behavesLike(budgetStoreConformance, () => memoryBudgetStore()));
+```
+
+| Suite | Holds a store to |
+|---|---|
+| `jobDriverConformance` | claim once · ack/nack fenced on the claim · a live key dedupes · `queues: []` refused · dead-letter never re-claimed · a lapsed lease re-claimed, the loser unable to renew · a lease lapsed on the final attempt buried, reported through `onExhausted` once, `failed` under `dropExhausted` |
+| `budgetStoreConformance` | 24 concurrent `take`s on one key never overspend · a refused take spends nothing · negative `add` · `reset(key)` scoped |
+
+The subject is called once per test. Each check claims from a queue — or counts under a key — of
+its own, so one shared store is enough.
+
 ## Parallel databases
 
 ```ts
 const db = await acquireWorkerDatabase({ adminUrl, migrate });
 ```
 
-The first worker creates the template under a Postgres advisory lock and migrates it once; every
-worker then clones it copy-on-write. With no Postgres configured it falls back to PGlite, so
+The first worker creates the template under a Postgres advisory lock and migrates it; every
+worker then clones it copy-on-write, under the same lock — a clone waits only 5 s for a session on
+the template to leave, and the next worker's migration holds one. With no Postgres configured it falls back to PGlite, so
 `bun test` works on a laptop with nothing installed.
 
 **The gate shards; a bare `bun test` does not.** `As of 2026-08`:
@@ -286,9 +317,9 @@ worker then clones it copy-on-write. With no Postgres configured it falls back t
 | Command | Processes | Worker ids | Databases |
 |---|---|---|---|
 | `bun test` (what a scaffolded app's `test` script still runs) | 1 | `0` | one |
-| `x verify` (`unit`, `contract`, `job`, `eval`; `live` and `e2e` stay serial) | `clamp(round(cpus * 1.5), 2, 8)` | `0..N-1`, from `ULTIMATE_TEST_WORKER` | N |
+| `x verify` (`unit`, `contract`, `job`, `eval`; `live` and `e2e` stay serial) | `clamp(round(cpus * 1.5), 2, 8)` | `1..N`, from Bun's own `BUN_TEST_WORKER_ID` — `0..N-1` from `ULTIMATE_TEST_WORKER` in its coverage run | N |
 | `bun test --parallel[=N]` | N (default: CPU count) | `1..N`, from Bun's own `BUN_TEST_WORKER_ID` | N |
-| `x test --workers N` | N | `0..N-1`, from `ULTIMATE_TEST_WORKER` | N |
+| `x test --workers N` | N | `1..N`, from Bun's own `BUN_TEST_WORKER_ID` | N |
 
 `ULTIMATE_TEST_WORKER` is read first so a runner-assigned shard always beats the index Bun assigns
 its own `--parallel` worker — measured on Bun 1.3.14, `--parallel` populates `BUN_TEST_WORKER_ID`
@@ -301,7 +332,7 @@ and `JEST_WORKER_ID` itself, so that precedence is load-bearing rather than defe
 
 | State | Owned by | What teardown does |
 |---|---|---|
-| the seal on `fetch` | the preload | unseals only if this boot was the one that sealed |
+| the seal on `fetch`, `WebSocket` and `Bun.connect` | the preload | unseals only if this boot was the one that sealed |
 | the frozen instant, `Math.random`, `globalThis.Date` | the preload (`ULTIMATE_TEST_NOW` / `ULTIMATE_TEST_SEED`) | `restoreCapturedDeterminism(captureDeterminism())` around the boot |
 | mocks, allow-listed hosts, the seen list | the boot | `resetNetwork()` |
 | the cloned worker database | the boot | `db.drop()`, in a `finally` — a rejecting `app.close()` reaches it |
@@ -319,11 +350,27 @@ X_TEST_NETWORK_SEALED
   fix:   mockFetch('https://api.stripe.com/v1/charges', () => new Response('{}')) — or allowHost('api.stripe.com') if it must be real
 ```
 
-A server this process booted is exempt: `createServer().start()` announces its socket through
+A server this process booted is exempt: `httpServer().start()` announces its socket through
 core's `markListening()`, so a test may call its own `handle.url()` on a kernel-assigned port with
 the seal fully on. Unsealing (`ULTIMATE_TEST_ALLOW_NET=1`) stays reserved for a deliberate live
 integration — never for a socket test.
 
+**Three dials are sealed, and only three** — `fetch`, `new WebSocket(url)` and `Bun.connect({ hostname,
+port })`, behind one gate: one allow-list (`allowHost('host[:port]')`), one offline state, one
+`requestedUrls()` record. As of 2026-10:
+
+| Dial | Refused with | Passes through |
+|---|---|---|
+| `fetch` | `X_TEST_NETWORK_SEALED` / `X_TEST_NETWORK_OFFLINE` | a mock, an allowed host, a port `markListening()` announced |
+| `new WebSocket(url)` | the same, thrown by the constructor before it dials | an allowed host, any loopback host |
+| `Bun.connect(…)` | the same, as the rejected promise | an allowed host, any loopback host, a unix socket |
+
+A socket to loopback is not egress on any port: it is how a test reaches a server it `Bun.listen`ed
+and the compose services the live suites dial. A socket test injects its transport (`connect`,
+`client`) rather than mocking the dial, so there is no `mockFetch` for one. **Not sealed:**
+`node:net`, `node:tls`, `node:http(s)`, `Bun.udpSocket` and the native clients (`Bun.sql`,
+`Bun.redis`, `Bun.S3Client`) — a test that must not reach the internet through those injects them.
+
 ## Rendering a page or a component
 
 A page is a function of props and a route is a module, so a unit test renders either in process —
@@ -361,7 +408,7 @@ unitTest('the shell keeps the page in <main>', async () => {
 | **`renderView(Component, props)`** | one component. `props` is the component's own type — a renamed prop is a compile error in the test. A component that renders an `island()` is refused here: its timing is a route's |
 | **`view.html`** | the markup as the document carries it |
 | **`view.text`** | what a reader sees: tags, `<script>` and `<style>` bodies removed, entities decoded, whitespace collapsed. Compare with `t('<key>')` — markup escapes what the catalog does not |
-| **`actor`** | `load` and the page run inside `runWithContext(createContext({ actor }))`. Without one they run outside any request context, as a static page does |
+| **`actor`** | `load` and the page run inside `runWithContext(ctxOf({ actor }))`. Without one they run outside any request context, as a static page does |
 | **the file stays `.test.ts`** | no JSX in a test: the registry-leak guard's loader covers `.test.ts` only, and children that need markup are a string |
 
 `@ultimat3/render` is imported inside the two functions, so the barrel still loads no renderer.
@@ -678,6 +725,40 @@ This package still owns the vocabulary, the expansion and the refusals, and owns
 capture, the harness page and the crop are `@ultimat3/cli`'s, because `cli → testing` is the
 declared edge and the reverse is a `bun run boundaries` failure.
 
+## Launching Chrome
+
+`launchChrome({ executable, timeoutMs, launchTimeoutMs?, wire? })` — what the `e2e` step and `x shot`
+both start a browser with. Driven over `--remote-debugging-pipe`, and on Windows — where the parent
+cannot hold Chrome's fds 3 and 4 — over `--remote-debugging-port=0` and the profile's
+`DevToolsActivePort` (`wire: 'pipe' | 'port'` overrides). The first answer is readiness.
+
+`CHROME_CANDIDATES` is this platform's install list, probed after `CHROME_PATH`: the `/usr/bin` names
+on Linux, the app bundles on macOS, Chrome under `%ProgramFiles%` / `%ProgramFiles(x86)%` /
+`%LOCALAPPDATA%` then Edge (`msedge.exe`) on Windows.
+
+| Export | What it is |
+|---|---|
+| `LAUNCH_TIMEOUT_MS` | `60_000` — the first answer's deadline per start. `launchTimeoutMs` defaults to the larger of this and `timeoutMs`; every later call has `timeoutMs` |
+| `LAUNCH_ATTEMPTS` | `2` — an unanswered start is reaped and started once more on a fresh profile. Never more |
+| `LAUNCH_BUDGET_MS` | derived: `LAUNCH_ATTEMPTS × (LAUNCH_TIMEOUT_MS + LAUNCH_REAP_MS)` — the longest a launch is designed to take, both starts and their bounded reaps |
+| `E2E_BROWSER_OPEN_MS` | derived: `LAUNCH_BUDGET_MS` + the session's two setup calls + the first tab, at `DEFAULT_CDP_TIMEOUT_MS` each. THE deadline of every `beforeAll` that opens a browser — one below it is killed by Bun before the relaunch, and `X_CDP_LAUNCH_FAILED` never names the slow step |
+| `E2E_BROWSER_CLOSE_MS` | derived: `4 × CLOSE_GRACE_MS` — SIGTERM's grace, SIGKILL's, the group reap, the profile's removal. THE deadline of an `afterAll` that closes a browser it holds (one that releases a lease takes `E2E_BROWSER_OPEN_MS`: it may await the open). At Bun's 5 s default a close cut short by the run's end left the profile half-removed in the temp root |
+| `E2E_TAB_OPEN_MS` | derived: one more `session.newTab()` — `Target.createTarget`, then its attach |
+| `E2E_GOTO_MS` | derived: one `tab.goto()` — the navigate raced by the load event, then two reads of the document |
+| `E2E_APP_START_MS` | derived: `startE2eApp()` at its default deadline — `x db reset`, `x db seed` and `/readyz` (wall-clock), each its whole 90 s, then a refused boot's stop |
+| `E2E_APP_STOP_MS` | derived: an e2e app's `stop()` — SIGTERM, the app's own drain at the defaults (readiness grace + `drain.deadlineMs`), then SIGKILL. Bounded: a wedged app no longer holds the hook forever |
+| `CdpLaunchAttempt` | one unanswered start, in `X_CDP_LAUNCH_FAILED`'s `meta.attempts`: `why` (`deadline` \| `closed` \| `spawn` — the binary could not be started at all), `waitedMs`, `exitCode` (`null` when killed), `stderr` (its last lines), `detail` (what the launcher saw end it: the refused dial and its endpoint, the call that timed out, the spawn error) |
+| `leaseE2eBrowser(key, open)` | ONE browser for every suite of the process that asks by `key`: `{ opened, release() }`, opened by the first, each suite its own tab. Closed by the last holder out — or, once a preload has called `closeE2eBrowsersAtRunEnd()`, at the run's end (Bun fires no `exit` under `bun test`, and runs one file to its end before loading the next) |
+| `LaunchedBrowser.close()` · `E2eBrowser.close()` | THE close, a promise, always awaited: the process, its whole process group (on Windows its process tree, `taskkill /T /F`), and only then its profile directory — removed again while something re-creates it, bounded — and Chrome's `com.google.Chrome.XXXXXX` singleton-socket directory beside it, when it holds nothing but singleton files. There is no synchronous close |
+
+Every hook that opens or closes a browser derives its deadline from these — the open, the close,
+the app's start or stop, plus its own steps. `e2e-browser-hooks.test.ts` reads every suite under
+`packages/*/e2e`, `examples/*/apps/*/e2e` and `dummy/*/apps/*/e2e`, follows each exported helper
+that calls an opener (`acceptanceBrowser()`) or `startE2eApp`, resolves named deadlines through
+their declarations, and refuses a literal, a missing deadline or a sum without the budget it needs.
+
+`As of 2026-10-05`.
+
 ## The one assertion that waits
 
 ```ts
@@ -707,7 +788,7 @@ fails on a page that simply has not painted yet.
 ## Errors
 
 `X_TEST_NETWORK_SEALED` `X_TEST_DB_UNAVAILABLE` `X_TEST_NONDETERMINISTIC` `X_TEST_FIXTURE_UNKNOWN`
-`X_TEST_FACTORY_TRAIT_UNKNOWN` `X_TEST_FACTORY_NOT_PERSISTED` `X_TEST_REGISTRY_LEAK`
+`X_TEST_APP_NOT_BOOTED` `X_TEST_FACTORY_TRAIT_UNKNOWN` `X_TEST_FACTORY_NOT_PERSISTED` `X_TEST_REGISTRY_LEAK`
 `X_TEST_ISLAND_NOT_BUILT` `X_TEST_ISLAND_NO_MOUNT` `X_TEST_ISLAND_SELECTOR_UNSUPPORTED`
 `X_TEST_ISLAND_STATES_EMPTY` `X_TEST_ISLAND_STATE_UNKNOWN`
 `X_TEST_ISLAND_STATES_NOT_PURE` `X_TEST_ISLAND_STATES_MISSING_FILE` `X_TEST_ISLAND_STATES_UNKNOWN`
@@ -722,6 +803,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 | Class | Code | Declared in |
 |---|---|---|
+| `AppNotBootedError` | `X_TEST_APP_NOT_BOOTED` | `src/errors.ts` |
 | `FixtureUnavailableError` | `X_TEST_FIXTURE_UNAVAILABLE` | `src/errors.ts` |
 | `NetworkOfflineError` | `X_TEST_NETWORK_OFFLINE` | `src/errors.ts` |
 | `NetworkSealedError` | `X_TEST_NETWORK_SEALED` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -29,26 +29,26 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "23.0.0",
-    "@ultimat3/cache": "23.0.0",
-    "@ultimat3/core": "23.0.0",
-    "@ultimat3/db": "23.0.0",
-    "@ultimat3/entity": "23.0.0",
-    "@ultimat3/http": "23.0.0",
-    "@ultimat3/i18n": "23.0.0",
-    "@ultimat3/jobs": "23.0.0",
-    "@ultimat3/mail": "23.0.0",
-    "@ultimat3/policy": "23.0.0",
-    "@ultimat3/query": "23.0.0",
-    "@ultimat3/realtime": "23.0.0",
-    "@ultimat3/render": "23.0.0",
-    "@ultimat3/time": "23.0.0"
+    "@ultimat3/action": "25.0.0",
+    "@ultimat3/cache": "25.0.0",
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/db": "25.0.0",
+    "@ultimat3/entity": "25.0.0",
+    "@ultimat3/http": "25.0.0",
+    "@ultimat3/i18n": "25.0.0",
+    "@ultimat3/jobs": "25.0.0",
+    "@ultimat3/mail": "25.0.0",
+    "@ultimat3/policy": "25.0.0",
+    "@ultimat3/query": "25.0.0",
+    "@ultimat3/realtime": "25.0.0",
+    "@ultimat3/render": "25.0.0",
+    "@ultimat3/time": "25.0.0"
   }
 }

package/src/auth-request.ts

@@ -42,7 +42,7 @@ export async function authRequest(init: AuthRequestInit = {}): Promise<Parameter
     );
   }
   if (init.bearer !== undefined) headers.set('authorization', `Bearer ${init.bearer}`);
-  const ctx = http.createRequestContext({
+  const ctx = http.requestContext({
     url,
     method,
     role: 'web',

package/src/budget-store-conformance.ts

@@ -0,0 +1,81 @@
+// The `BudgetStore` contract of `@ultimat3/ai` as shared examples, for a store of your own (Redis,
+// SQL): `behavesLike(budgetStoreConformance, () => store)`. The race is the point — `take` is the
+// one atomic step, and a store that awaits between its read and its write overspends under it.
+// Structural, so this package takes no dependency on `ai`: a `BudgetStore` is assignable.
+
+import { expect, test } from 'bun:test';
+import type { SharedExamples } from './shared-examples';
+import { sharedExamples } from './shared-examples';
+
+type Maybe<T> = T | Promise<T>;
+
+/** The four members of `@ultimat3/ai`'s `BudgetStore`, structurally. */
+export interface BudgetStoreLike {
+  spent(key: string): Maybe<number>;
+  add(key: string, tokens: number): Maybe<void>;
+  take(key: string, tokens: number, limit: number): Maybe<{ readonly taken: boolean }>;
+  reset(key?: string): Maybe<void>;
+}
+
+export interface BudgetStoreCheck {
+  readonly name: string;
+  run(store: BudgetStoreLike): Promise<void>;
+}
+
+/** Concurrent takers, and the ceiling only some of them fit under. */
+const BUDGET_RACE_TAKERS = 24;
+const RACE_LIMIT = 5;
+
+let minted = 0;
+const keyOf = (): string => {
+  minted += 1;
+  return `conformance:${process.pid.toString(36)}:${minted.toString(36)}`;
+};
+
+export const BUDGET_STORE_CHECKS: readonly BudgetStoreCheck[] = [
+  {
+    name: `${BUDGET_RACE_TAKERS} concurrent takes against one key never overspend the limit`,
+    async run(store) {
+      const key = keyOf();
+      const takes = Array.from({ length: BUDGET_RACE_TAKERS }, async () =>
+        store.take(key, 1, RACE_LIMIT),
+      );
+      const taken = (await Promise.all(takes)).filter((each) => each.taken).length;
+      expect([taken, await store.spent(key)]).toEqual([RACE_LIMIT, RACE_LIMIT]);
+    },
+  },
+  {
+    name: 'a refused take spends nothing, and a take that fits exactly is taken',
+    async run(store) {
+      const key = keyOf();
+      expect((await store.take(key, 3, 4)).taken).toBe(true);
+      expect((await store.take(key, 2, 4)).taken).toBe(false);
+      expect(await store.spent(key)).toBe(3);
+      expect((await store.take(key, 1, 4)).taken).toBe(true);
+      expect(await store.spent(key)).toBe(4);
+    },
+  },
+  {
+    name: 'add takes a negative credit, and reset(key) clears that key alone',
+    async run(store) {
+      const [key, other] = [keyOf(), keyOf()];
+      await store.add(key, 5);
+      await store.add(key, -2);
+      await store.add(other, 1);
+      expect(await store.spent(key)).toBe(3);
+      await store.reset(key);
+      expect([await store.spent(key), await store.spent(other)]).toEqual([0, 1]);
+    },
+  },
+];
+
+export const budgetStoreConformance: SharedExamples<Maybe<BudgetStoreLike>> = sharedExamples(
+  'a budget store',
+  (subject) => {
+    for (const check of BUDGET_STORE_CHECKS) {
+      test(check.name, async () => {
+        await check.run(await subject());
+      });
+    }
+  },
+);

package/src/cdp-browser-lease.ts

@@ -0,0 +1,112 @@
+// One responsibility: ONE browser shared by the suites of a test process that ask for it by the
+// same key — opened by the first, a holder count per suite, closed by the last out or at the run's
+// end. Opening and closing a browser is `cdp-browser.ts`; this file only decides WHEN.
+
+import { afterAll } from 'bun:test';
+import type { E2eBrowser } from './cdp-browser';
+import { E2E_BROWSER_OPEN_MS } from './cdp-browser';
+
+export interface E2eBrowserLease {
+  /** The shared browser: opened by the first lease of its key, `undefined` with no browser here. */
+  readonly opened: Promise<E2eBrowser | undefined>;
+  /** This holder is done. Idempotent. The last one out closes it, unless the run closes it at its end. */
+  release(): Promise<void>;
+}
+
+/** Registers a hook for the end of the run — a preload's `afterAll`, which Bun runs once, last. */
+export type RunEndHook = (hook: () => Promise<void>, timeoutMs: number) => void;
+
+export interface E2eBrowserLeases {
+  lease(key: string, open: () => Promise<E2eBrowser | undefined>): E2eBrowserLease;
+  /** From a PRELOAD: keep every leased browser open until the run ends, then close each. */
+  closeAtRunEnd(after: RunEndHook): void;
+}
+
+interface Held {
+  readonly opening: Promise<E2eBrowser | undefined>;
+  holders: number;
+}
+
+/** Its open already failed in front of the holder that awaited it: the close has nothing to add. */
+const closeHeld = async (held: Held): Promise<void> => {
+  const browser = await held.opening.catch(() => undefined);
+  await browser?.close();
+};
+
+/**
+ * A fresh registry. Why the last holder alone cannot make "last" mean the last SUITE: Bun runs one
+ * test file to its end before it loads the next (measured on 1.4.2), so between two suites the
+ * count is 0; and `exit` and `beforeExit` never fire under `bun test`, so a browser kept "for the
+ * next one" past the last file is a Chrome and a profile left behind. Only a preload's `afterAll`
+ * runs after every file — under `--isolate` after each, with a fresh global, which is right too.
+ */
+export function createE2eBrowserLeases(): E2eBrowserLeases {
+  const held = new Map<string, Held>();
+  let runEnd = false;
+  return {
+    lease(key, open) {
+      let shared = held.get(key);
+      if (shared === undefined) {
+        const made: Held = { opening: open(), holders: 0 };
+        held.set(key, made);
+        // A failed open is nobody's to share: the next holder opens afresh and meets its own error.
+        made.opening.catch(() => {
+          if (held.get(key) === made) held.delete(key);
+        });
+        shared = made;
+      }
+      const mine = shared;
+      mine.holders += 1;
+      let released = false;
+      return {
+        opened: mine.opening,
+        async release() {
+          if (released) return;
+          released = true;
+          mine.holders -= 1;
+          if (mine.holders > 0 || runEnd) return;
+          if (held.get(key) === mine) held.delete(key);
+          await closeHeld(mine);
+        },
+      };
+    },
+    closeAtRunEnd(after) {
+      if (runEnd) return;
+      runEnd = true;
+      // The deadline of an open: the hook awaits one still in flight before it can close it.
+      after(async () => {
+        const open = [...held.values()];
+        held.clear();
+        for (const one of open) await closeHeld(one);
+      }, E2E_BROWSER_OPEN_MS);
+    },
+  };
+}
+
+/**
+ * On `globalThis` under one `Symbol.for` key: the preload imports this module by path and a suite
+ * through `@ultimat3/testing`, and each may hold its own copy — `e2e-browser-handle.ts`'s reason.
+ */
+const KEY = Symbol.for('ultimate.e2e.browserLeases');
+
+const processLeases = (): E2eBrowserLeases => {
+  const known = Reflect.get(globalThis, KEY) as E2eBrowserLeases | undefined;
+  if (known !== undefined) return known;
+  const made = createE2eBrowserLeases();
+  Object.defineProperty(globalThis, KEY, { value: made, configurable: true });
+  return made;
+};
+
+/**
+ * The browser the suites of this process share under `key`; call it in a `beforeAll` and
+ * `release()` in the matching `afterAll`. Without `closeE2eBrowsersAtRunEnd` in the preload the
+ * last holder out closes it, which is one browser per suite again — never one left running.
+ */
+export const leaseE2eBrowser = (
+  key: string,
+  open: () => Promise<E2eBrowser | undefined>,
+): E2eBrowserLease => processLeases().lease(key, open);
+
+/** The preload's half: `closeE2eBrowsersAtRunEnd()` once, and leased browsers live for the run. */
+export const closeE2eBrowsersAtRunEnd = (after: RunEndHook = afterAll): void =>
+  processLeases().closeAtRunEnd(after);