@ultimat3/testing 1.2.0 → 3.0.0

package/CLAUDE.md

@@ -0,0 +1,57 @@
+# @ultimat3/testing — boundary
+
+Tier 5. May import tiers 0–4. Imported by every package's tests and by generated apps.
+
+Deps: `core` (tier 0), plus `time`, `jobs`, `mail`, `db` and `entity` — imported **dynamically
+inside the fixture factories only**, so a test that never destructures `mail` never loads the mail
+package and a `packages/core` test never loads the entity registry. `entity` is a dependency for
+exactly one call: `nPlusOne()`, so the strict fixture reports the error `x dev` reports, with the
+`fix:` the schema's own relations spell. A second N+1 code owned here would be a second answer to
+one condition. The one static `entity` import is `registry-isolation.ts`, which is why that module
+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 |
+| 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. Without it `value instanceof Date` is false for every Date the runtime built itself — a `timestamptz` off a Postgres socket, a `structuredClone`, anything from another realm — and the guards that read it fail under test and nowhere else |
+| 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` |
+| 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 |
+| 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 |
+| No retries | a flake is fixed or deleted the day it flakes; there is no `retry: 3` |
+| Test names | the filename picks the step; `testName(type, name)` on the outer `describe` puts that type on every failure line under it. Never on the inner `test` too — the prefix would print twice |
+| Injection | `SqlRunner` and `connect` are parameters, so unit tests need no server |
+| Fixtures | the preload registers the whole framework bag — an app registers only what the framework cannot know (`seed`, `actorFor`) |
+| e2e without a driver | `e2eTest` becomes `test.skip`, and the gate reports the step GREEN over it — `bun test` exits 0 on a skip and the exit code is the only channel between the step and the child that registers the driver. `hasE2eDriver()` is what a harness asks instead of reading an all-skipped run as a pass. Zero drivers are registered `As of 2026-08` |
+| Built vs declared | `clock` `mail` `network` `runJobs` `statements` are built in-process; `page` `budget` `signIn` `deploy` `subscribe` are declared and wait for a driver (`X_TEST_FIXTURE_UNAVAILABLE`) |
+| Strict is opt-in by destructuring | `statements` installs the N+1 detector in throw mode for one test. A fixture nobody names is a fixture nobody built, so there is no `strict: true` and no suite-wide switch — and no way to leave it on for the next file |
+| One threshold, one error | `N_PLUS_ONE_THRESHOLD` and `nPlusOne()` are `@ultimat3/entity`'s. A number or a message written here would make a loop that fails a test a different loop from the one `x dev` warns about |
+| The unit of work is the test | `x dev`'s ledger tallies per `Ctx` and ignores a statement issued outside a request; this counts every statement from build to disposal, because `posts.findById(id)` in a unit test has no request and is exactly the loop worth catching |
+| Throws once per shape | the failing line is the loop's own statement (the seam lets `onStatement` throw for this reason alone). It keeps counting after, so a body that catches the error still reports the whole loop through `shapes()` — the same hole Bullet's `raise` has, named rather than papered over |
+| Measure vs judge | `all()` `count()` `shapes()` count `expectedQueryLoop` statements too; only the verdict honours the suppression, so "this page issues two statements" never depends on who declared what |
+| One seam for drivers | a driver registers over a declaration with `defineFixtures` — merges, last wins. Never a second registration mechanism |
+| A driver arrives whole | `defineFixtures` holds every name `Fixtures` declares to its declared type, so a half-built `page` is a compile error at the registration, not a missing method three awaits later |
+| Registry hygiene | the fixture registry is process-global; a test that clears it snapshots with `fixtureSnapshot()` and hands it back in `afterAll` |
+| Leaks are the file's, not the next file's | `installRegistryLeakGuard()` runs from the preload and fails the run naming the FILE that left cache tags declared or a cache tier registered after its last test (`X_TEST_REGISTRY_LEAK`). `bun test` is one process, so without it the failure lands on an innocent suite in another package. What a file's MODULE graph declares is its environment; what the file installs after that is its own to undo |
+| The baseline is not a hook | measured on Bun 1.3.14 the order is onLoad → module eval → file `beforeAll` → describe `beforeAll` → preload `beforeEach`, so a preload hook cannot sample before the file's own `beforeAll` — a `declareTags()` there read as environment and the run went green. The load handler appends the sample to the file's source instead: after evaluation, before any hook the file registers. It is also the only signal carrying file identity, which `bun:test` hooks do not |
+| Guarded state is boot state | only the two registries whose honest invariant is "clean when the file ends" — `declareTags` and `registerTier` are boot installs. `entity()`, `job()` and `defineRoute()` register at MODULE scope, which is how an app declares itself, so a filled registry there is idiomatic and unguarded |
+| An empty registry is a premise you state | a test whose subject is "nothing is declared" — `x db gen` with nothing to generate — calls `isolateEntityRegistry()` and restores in a `finally`. Inheriting it means the test passes until a neighbouring file imports an entity |
+| That one helper is off the barrel | `@ultimat3/testing/registry-isolation`, its own entry point. It is the only module here that value-imports `@ultimat3/entity` — the restore is handed back synchronously, so it cannot be a dynamic import inside the call — and a static re-export from `src/index.ts` would load the entity registry into every test that imports this package for `expect` |
+| Teardown restores, never uninstalls | `describeApp`/`testApp` capture the seal and the determinism snapshot before booting and put those back — `restoreDeterminism()` in a scope hands the REAL clock and the REAL `fetch` to every later FILE in the process. `captureDeterminism()` / `restoreCapturedDeterminism()` are the pair for any nested install |
+| 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 stranded clone is one `ultimate_test_template_wN` leaked per failing run |
+| A boot that rejects is its own teardown | `acquireWorkerDatabase`, `seed` or `boot` throwing returns no `BootedHarness`, so no caller can ever reach `close()` — `bootApp` drops the clone it acquired and restores the seal, the allow-list and the clock itself, then rethrows the boot's OWN error. A `drop` that also fails is swallowed: there is no handle left to report a second failure through |
+| 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 — on any Postgres that outlives one run the template is found, not created, and skipping it clones the first run's schema forever |
+| 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; `fixtureTest` disposes in reverse build order even when the body throws |
+| Building one by hand | `createRunJobs()` outside `fixtureTest` is not disposed for you — reset the driver in `afterEach`, or the next file in the process inherits your queue |
+| 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 |
+| Which command shards | `bun test` is one process on one database, and that is still what a scaffolded app's `test` script runs. `x verify` DOES shard its parallel test steps, over `ULTIMATE_TEST_WORKER` and one database per worker; `live` and `e2e` stay serial because a replication slot is cluster-scoped and `e2e` has one built `dist/`. Say which command a claim is about |
+
+Commands: `bun test`, `bunx tsc --noEmit -p tsconfig.json`.
+
+Entry points: `.` (the API), `./preload` (side effects for bunfig) and `./registry-isolation`
+(`isolateEntityRegistry()`, kept off `.` because it loads `@ultimat3/entity`).

package/README.md

@@ -18,9 +18,11 @@ frozen clock. Never let a test reach the network unmocked — it fails by design
 | `test-types.ts` | the six test types and their helpers |
 | `matchers.ts` | `toBeUltimateError` `toDenyPolicy` `toEmitSteps` `toMatchOpenApi` `toBeWithinBudget` `toRejectInput` |
 | `fixtures.ts` | the registry + `test('…', ({ clock }) => …)` injection |
-| `fixture-{clock,mail,jobs,network}.ts` | the four fixtures the framework builds in-process |
+| `fixture-{clock,mail,jobs,network,statements}.ts` | the five fixtures the framework builds in-process |
 | `fixture-drivers.ts` | the five it declares but a driver must build — `page` `budget` `signIn` `deploy` `subscribe` |
 | `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 |
+| `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` |
 | `preload.ts` | the bunfig preload that installs all of the above |
 
 ## Install
@@ -53,6 +55,7 @@ test('the three-day sleep releases the worker', async ({ clock, runJobs }) => {
 | `mail` | `outbox()` · `lastTo(address)` · `failOnce(mail)` over an in-memory transport | the preload |
 | `network` | `offline()` · `drop()` · `online()` · `state()` over the sealed network | the preload |
 | `runJobs` | a worker: call it to enqueue+drain, then `drain()` `due()` `inFlight()` `depth()` | 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 |
 | `budget` | `jsBytes(route)` measured off the built output | a browser driver |
 | `signIn` | put the browser session in a member's shoes | a browser driver |
@@ -88,6 +91,33 @@ that *is* registered — never `undefined is not an object` from inside the body
 registered but has no driver fails with `X_TEST_FIXTURE_UNAVAILABLE` instead; the two are different
 instructions, so they are different codes.
 
+## An N+1 fails the test it happened in
+
+```ts
+test('the feed reads its authors once', async ({ statements }) => {
+  await renderFeed();                              // a per-row findById throws here:
+  //   X_N_PLUS_ONE_QUERY: members.findById ran 5 times in one request — one read per row
+  //   fix: db.posts.preload('author')   # one statement for the whole page
+  expect(statements.count('posts.findMany')).toBe(1);
+  expect(statements.shapes()[0]?.count).toBe(1);
+});
+```
+
+Opting in is naming it. `statements` installs `@ultimat3/db`'s statement observer for the length of
+one test and hands the seam back afterwards, so there is no `strict: true` to remember and no
+suite-wide switch to forget.
+
+| | |
+|---|---|
+| **the unit of work is the test** | `x dev`'s ledger counts per request and skips a statement issued outside one; a unit test calling `posts.findById(id)` has no request anywhere, and that is the loop it was written to catch |
+| **one threshold** | `N_PLUS_ONE_THRESHOLD` from `@ultimat3/entity`, the number `x dev` warns at. A loop that fails a test and a loop that warns in dev are the same loop |
+| **one error** | `nPlusOne()`'s, so the `fix:` is the `preload()` the schema's own relations spell — never a line this package composes |
+| **it throws where it happened** | the loop's fifth statement rejects, so the failing line is the loop's own. Once per shape: a body that catches it gets one failure, not one per statement after it |
+| **measurement ≠ verdict** | `all()` `count()` `shapes()` count every statement, `expectedQueryLoop` ones included; only the verdict honours the suppression |
+
+`expectedQueryLoop(reason, fn)` from `@ultimat3/db` stays the one way to declare a loop deliberate —
+there is no flag on the fixture and no code to silence.
+
 ## The six test types
 
 | Helper | Asserts | `x verify` step |
@@ -96,7 +126,7 @@ instructions, so they are different codes.
 | `contractTest` | OpenAPI diff vs the committed spec, MCP exposure | `contract` |
 | `liveTest` | exactly what each subscriber receives | `live` |
 | `jobTest` | step sequence, retries, idempotency | `job` |
-| `e2eTest` | Playwright incl. offline mode + SW update | `e2e` |
+| `e2eTest` | a browser driver incl. offline mode + SW update; with none registered it SKIPS, and the gate's `e2e` step passes over the skip — ask `hasE2eDriver()` rather than reading that as a pass | `e2e` |
 | `evalTest` | LLM output scoring against a threshold | `eval` |
 
 Each helper prefixes the test name with its type (`job · onboards an org`), which is what
@@ -161,11 +191,12 @@ The first worker creates the template under a Postgres advisory lock and migrate
 worker then clones it copy-on-write. With no Postgres configured it falls back to PGlite, so
 `bun test` works on a laptop with nothing installed.
 
-**Parallelism is opt-in, not the default.** `As of 2026-08`:
+**The gate shards; a bare `bun test` does not.** `As of 2026-08`:
 
 | Command | Processes | Worker ids | Databases |
 |---|---|---|---|
-| `bun test` (what a scaffolded app's `test` script runs, and what every `x verify` test step runs) | 1 | `0` | one |
+| `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 |
 | `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 |
 
@@ -173,9 +204,26 @@ worker then clones it copy-on-write. With no Postgres configured it falls back t
 its own `--parallel` worker — measured on Bun 1.3.14, `--parallel` populates `BUN_TEST_WORKER_ID`
 and `JEST_WORKER_ID` itself, so that precedence is load-bearing rather than defensive.
 
+## The harness puts back what it found
+
+`bun test` is one process, so `describeApp`/`testApp` teardown is a **restore**, never an uninstall.
+`As of 2026-08`:
+
+| State | Owned by | What teardown does |
+|---|---|---|
+| the seal on `fetch` | 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 |
+
+`installDeterminism()` runs during a boot only when the boot has something of its own to say
+(`seedValue`/`now`) or nothing installed it yet, so a run configured with `ULTIMATE_TEST_NOW` is not
+reset by the first `describeApp`. `restoreDeterminism()` is the process's own call, not a scope's:
+it hands the real clock and the real `Math.random` back to every later **file** in the run.
+
 ## Sealed network
 
-```
+```text
 X_TEST_NETWORK_SEALED
   cause: POST https://api.stripe.com/v1/charges was not mocked (allowed hosts: none)
   fix:   mockFetch('https://api.stripe.com/v1/charges', () => new Response('{}')) — or allowHost('api.stripe.com') if it must be real
@@ -189,4 +237,38 @@ integration — never for a socket test.
 ## 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_FACTORY_TRAIT_UNKNOWN` `X_TEST_FACTORY_NOT_PERSISTED` `X_TEST_REGISTRY_LEAK`
+
+## One process, one registry
+
+`bun test` runs every file of one invocation in the same process — only `x verify`'s shards pass
+`--isolate`. A file that leaves a process-global registry dirty therefore changes what every later
+file sees, and the failure lands on an innocent suite in another package: `bun test packages/query
+packages/cli` failed five tests in `query`, all of them installed by `cli`, while either package
+alone was green.
+
+The preload installs the guard. It samples the cache tag set and the cache tier registry once per
+file, at the end of that file's module evaluation — so an app's own boot declarations are its
+environment — and reports what the file added after that and did not put back:
+
+```text
+X_TEST_REGISTRY_LEAK: a test file left a process-global registry dirty —
+"packages/cli/src/cmd-dev.test.ts" left cache tags declared ["devfixture"] after its last test
+  fix: in "packages/cli/src/cmd-dev.test.ts" add: import { isolateDeclaredTags } from
+       '@ultimat3/cache'; const restoreTags = isolateDeclaredTags(); afterAll(restoreTags);
+       — then re-run: bun test "packages/cli/src/cmd-dev.test.ts"
+```
+
+The baseline is not a `beforeEach`: a file's own `beforeAll` runs **before** a preload's
+`beforeEach` (onLoad → module eval → file `beforeAll` → describe `beforeAll` → preload
+`beforeEach`, measured on Bun 1.3.14), so a `declareTags()` in `beforeAll` would have been sampled
+as the file's environment and the run would have gone green. The guard appends the sample to the
+file's own source in its load handler instead — the one place a file's identity and its evaluation
+boundary are both known.
+
+The fix is `isolateDeclaredTags()` or `isolateTiers()` (both `@ultimat3/cache`), never a loosened
+assertion in the file that paid for it — and never a **reset**. A reset drops what a neighbour
+registered, and this guard reports additions only, so the damage lands on an innocent file with
+nothing pointing back. A leak fails a one-file run exactly as it fails the suite —
+each file is judged against its own baseline — which is what makes the `bun test <file>` in the fix
+line reproduce it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "1.2.0",
+  "version": "3.0.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -15,11 +15,13 @@
   },
   "exports": {
     ".": "./src/index.ts",
-    "./preload": "./src/preload.ts"
+    "./preload": "./src/preload.ts",
+    "./registry-isolation": "./src/registry-isolation.ts"
   },
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -31,10 +33,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "1.2.0",
-    "@ultimat3/db": "1.2.0",
-    "@ultimat3/jobs": "1.2.0",
-    "@ultimat3/mail": "1.2.0",
-    "@ultimat3/time": "1.2.0"
+    "@ultimat3/cache": "3.0.0",
+    "@ultimat3/core": "3.0.0",
+    "@ultimat3/db": "3.0.0",
+    "@ultimat3/entity": "3.0.0",
+    "@ultimat3/jobs": "3.0.0",
+    "@ultimat3/mail": "3.0.0",
+    "@ultimat3/time": "3.0.0"
   }
 }

package/src/determinism.ts

@@ -94,6 +94,35 @@ export function restoreDeterminism(): void {
   installed = false;
 }
 
+/** Everything `installDeterminism` overwrites, so a nested install can put back what it found. */
+export interface DeterminismSnapshot {
+  readonly installed: boolean;
+  readonly frozenAt: number;
+  readonly random: () => number;
+  readonly date: DateConstructor;
+}
+
+/**
+ * Capture before a nested `installDeterminism`, restore after — the shape `fixture-network.ts`
+ * uses for the seal. The preload installs determinism once for the whole process, so an inner
+ * scope that called `restoreDeterminism()` would hand the REAL clock and the REAL `Math.random`
+ * to every later test file in it. `random` is captured by identity because a generator's state is
+ * its closure: re-seeding produces an equal sequence, not the same position in this one.
+ */
+export const captureDeterminism = (): DeterminismSnapshot => ({
+  installed,
+  frozenAt,
+  random: Math.random,
+  date: globalThis.Date,
+});
+
+export function restoreCapturedDeterminism(snapshot: DeterminismSnapshot): void {
+  frozenAt = snapshot.frozenAt;
+  Math.random = snapshot.random;
+  globalThis.Date = snapshot.date;
+  installed = snapshot.installed;
+}
+
 export const isDeterminismInstalled = (): boolean => installed;
 
 /** Move the frozen clock forward. The only legal way for time to pass inside a test. */

package/src/errors.ts

@@ -1,6 +1,15 @@
 // The X_* codes owned by @ultimat3/testing. A test failure has to be as actionable as a runtime
 // failure — the fix line here is the mock to add, the service to start, or the seed to freeze.
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+import {
+  registerErrorCodes,
+  renderCauseValue,
+  renderFixLiteral,
+  UltimateError,
+} from '@ultimat3/core';
+// Type-only, so the cycle with the guard that throws it is erased at build: the code is declared
+// here because this file is the package's code registry, and the shape it reports lives with the
+// sampler that produces it.
+import type { RegistryLeak } from './registry-leak-guard';
 
 export const TESTING_ERROR_CODES = [
   'X_TEST_NETWORK_SEALED',
@@ -15,6 +24,7 @@ export const TESTING_ERROR_CODES = [
   'X_TEST_NETWORK_RACE',
   'X_TEST_FACTORY_TRAIT_UNKNOWN',
   'X_TEST_FACTORY_NOT_PERSISTED',
+  'X_TEST_REGISTRY_LEAK',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -32,6 +42,7 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_TEST_NETWORK_RACE: 'a request raced unsealNetwork() and lost the patched fetch',
   X_TEST_FACTORY_TRAIT_UNKNOWN: 'a factory was asked for a trait it does not declare',
   X_TEST_FACTORY_NOT_PERSISTED: 'a factory create() had nowhere to write the row',
+  X_TEST_REGISTRY_LEAK: 'a test file left a process-global registry dirty',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -239,3 +250,62 @@ export class NetworkRaceError extends UltimateError {
     });
   }
 }
+
+/**
+ * Every value in this message is uncontrolled: the path arrives from `Bun.plugin`'s `onLoad`, and
+ * the names are whatever the app under test passed to `declareTags()` / `registerTier()`. So the
+ * sentence renders them (bounded, never throwing while describing a leak) and the command quotes
+ * them (a fix has to parse after a path with a space or a quote in it lands in the middle of it).
+ */
+const describeLeak = (leak: RegistryLeak): string => {
+  const left = [
+    ...(leak.tags.length > 0 ? [`cache tags declared ${renderCauseValue(leak.tags)}`] : []),
+    ...(leak.tiers.length > 0 ? [`cache tiers registered ${renderCauseValue(leak.tiers)}`] : []),
+  ];
+  return `${renderCauseValue(leak.file)} left ${left.join(' and ')} after its last test`;
+};
+
+/** The placeholder is the cause's own sentence: it already names every file, in order. */
+const FILE_PLACEHOLDER = '<the file the cause names>';
+
+/**
+ * The edit, spelled as the lines to paste — the imports included, since neither call is global.
+ *
+ * Both repairs isolate; neither resets. `afterAll(resetTiers)` was the first spelling of the tier
+ * half and it is the bug wearing the fix's clothes: it drops the tiers, the revalidator and both
+ * logs a NEIGHBOUR registered, and the guard reports additions only, so the damage lands on an
+ * innocent file with nothing pointing back here. An error whose instruction causes the next defect
+ * is worse than no instruction.
+ */
+const repairFor = (leak: RegistryLeak): string => {
+  const imports: string[] = [];
+  const calls: string[] = [];
+  if (leak.tags.length > 0) {
+    imports.push('isolateDeclaredTags');
+    calls.push('const restoreTags = isolateDeclaredTags(); afterAll(restoreTags);');
+  }
+  if (leak.tiers.length > 0) {
+    imports.push('isolateTiers');
+    calls.push('const restoreTiers = isolateTiers(); afterAll(restoreTiers);');
+  }
+  const file = renderFixLiteral(leak.file, FILE_PLACEHOLDER);
+  return `in ${file} add: import { ${imports.join(', ')} } from '@ultimat3/cache'; ${calls.join(' ')}`;
+};
+
+/**
+ * One error for every leaker in the run, not one per file: the run has already finished by the
+ * time the last file can be judged, and two throws would report the second as an unhandled one.
+ * The trailing command reproduces the failure on its own — the guard judges each file against its
+ * own baseline, so one leaking file fails a one-file run exactly as it failed the whole suite.
+ */
+export class RegistryLeakError extends UltimateError {
+  constructor(input: { readonly leaks: readonly RegistryLeak[] }) {
+    const files = input.leaks.map((leak) => renderFixLiteral(leak.file, FILE_PLACEHOLDER));
+    super({
+      code: 'X_TEST_REGISTRY_LEAK',
+      cause: input.leaks.map(describeLeak).join('; '),
+      fix: `${input.leaks.map(repairFor).join('; ')} — then re-run: bun test ${files.join(' ')}`,
+      docs: docsFor('X_TEST_REGISTRY_LEAK'),
+    });
+  }
+}

package/src/fixture-clock.ts

@@ -3,7 +3,13 @@
 // `clock.advance('3d')` is synchronous — a job test asserts on what is due on the very next
 // line — so the duration parser is resolved while the fixture is built, not when it is used.
 
-import { advanceClock, frozenNow, setFrozenClock } from './determinism';
+import {
+  advanceClock,
+  captureDeterminism,
+  frozenNow,
+  restoreCapturedDeterminism,
+  setFrozenClock,
+} from './determinism';
 
 /** `'3d'` | `'30s'` | `1500`. Same vocabulary as a job's `timeout` and a step's `sleep`. */
 export type TestDuration = string | number;
@@ -13,10 +19,23 @@ export interface TestClock {
   now(): Date;
   advance(duration: TestDuration): Date;
   set(instant: string | number): Date;
+  /** Puts the instant this fixture was built at back. `fixtureTest` calls it; see below. */
+  [Symbol.asyncDispose](): Promise<void>;
 }
 
+/**
+ * The frozen instant is module-global and `advance`/`set` move it, so this fixture installs
+ * process state exactly the way the mail and job fixtures do — and until it disposed, a test that
+ * advanced three days handed the advanced clock to every later test FILE in the run (`bun test` is
+ * one process), where the failure lands on an innocent suite.
+ *
+ * `captureDeterminism`/`restoreCapturedDeterminism` rather than `restoreDeterminism()`: the preload
+ * installed determinism once for the whole process, and uninstalling it here would hand the REAL
+ * `Date` and the REAL `Math.random` to everything after. Restore only what was found.
+ */
 export async function createTestClock(): Promise<TestClock> {
   const { toMs } = await import('@ultimat3/time');
+  const captured = captureDeterminism();
   return {
     now: frozenNow,
     advance: (duration) => advanceClock(toMs(duration)),
@@ -24,5 +43,8 @@ export async function createTestClock(): Promise<TestClock> {
       setFrozenClock(instant);
       return frozenNow();
     },
+    [Symbol.asyncDispose]: async () => {
+      restoreCapturedDeterminism(captured);
+    },
   };
 }

package/src/fixture-statements.ts

@@ -0,0 +1,148 @@
+// The `statements` fixture: every statement the test issues, counted by shape — and a shape that
+// repeats past the threshold throws where it happened, so an N+1 fails the test that caused it
+// instead of warning in a dev server nobody is watching.
+//
+// Strict by construction: there is no `strict: true` to remember, because a fixture nobody
+// destructured is a fixture nobody built. Opting in is naming `statements` in the test body.
+
+import type { StatementAttribution, StatementEvent, StatementObserver } from '@ultimat3/db';
+
+/** One statement, as this fixture kept it. Bound values are deliberately not retained. */
+export interface ObservedStatement {
+  /** What it is counted under: `members.findById` when attributed, else its own collapsed text. */
+  readonly fingerprint: string;
+  readonly kind: 'read' | 'write';
+  /** The statement as sent, parameters still `$1..$n`. */
+  readonly text: string;
+  /** The entity and operation that compiled it; absent for hand-written SQL and queue traffic. */
+  readonly attribution?: StatementAttribution | undefined;
+  /** The `expectedQueryLoop()` reason in force when it was sent, absent outside every such scope. */
+  readonly expected?: string | undefined;
+}
+
+/** One shape and how often the test issued it. */
+export interface StatementShape {
+  readonly fingerprint: string;
+  readonly kind: 'read' | 'write';
+  /** Every statement of this shape, expected ones included — this half measures, it never judges. */
+  readonly count: number;
+}
+
+/**
+ * `Disposable`: the observer seam is process-global, so the fixture hands back whatever it found —
+ * the state, not a fixed default, exactly as `network` and `runJobs` do.
+ */
+export interface TestStatements extends Disposable {
+  /** Every statement issued since the fixture was built, in order. */
+  all(): readonly ObservedStatement[];
+  /** How many of one shape, or of everything when asked with no fingerprint. */
+  count(fingerprint?: string): number;
+  /** Shapes seen, most repeated first, ties by fingerprint — a stable list to assert against. */
+  shapes(): readonly StatementShape[];
+}
+
+/** The live tally behind a `StatementShape`: what it measures, and what it judges. */
+interface ShapeTally {
+  readonly fingerprint: string;
+  readonly kind: 'read' | 'write';
+  /** Every statement of this shape. */
+  count: number;
+  /** The ones no `expectedQueryLoop()` scope covered — the only ones a verdict may count. */
+  unexpected: number;
+  /** Whether this shape has already thrown. The flag, not the count, so it throws exactly once. */
+  failed: boolean;
+}
+
+/**
+ * Install the strict detector for the length of one test.
+ *
+ * Three rules, each load-bearing and each different from `x dev`'s ledger for a stated reason.
+ *
+ * **The unit of work is the test, not the request.** The ledger keys its tally on the `Ctx` object
+ * and ignores a statement issued outside a request; a unit test calls `posts.findById(id)` with no
+ * request anywhere, which is exactly the loop it was written to catch — so this counts every
+ * statement from the moment the fixture is built until it is disposed, whatever context it was
+ * issued in.
+ *
+ * **The verdict counts only unexpected statements, the measurements count all of them.** An
+ * `expectedQueryLoop(reason, fn)` scope is the one way to declare a loop deliberate (there is no
+ * flag here and no second suppression), and it suppresses the *verdict* — the statements are still
+ * sent, still observed, and still reported by `count()` and `shapes()`, because a test asserting
+ * "this page issues two statements" must not see a different number depending on who declared what.
+ *
+ * **It throws where the loop happened, once per shape.** `@ultimat3/db`'s seam deliberately lets a
+ * throw from `onStatement` propagate to whoever ran the statement, which is what makes the failing
+ * line the loop's own line rather than a summary at teardown. Once a shape has thrown it keeps
+ * counting silently: a test that catches the error gets one failure at the statement that crossed
+ * the threshold, not one per statement after it, and `shapes()` still reports the whole loop. The
+ * consequence worth knowing is the same one Bullet's `raise` has — a body that swallows every error
+ * swallows this one too, and `shapes()` is what names the loop in that test.
+ *
+ * The threshold is `@ultimat3/entity`'s `N_PLUS_ONE_THRESHOLD` and there is no knob: a loop that
+ * fails a test and a loop that warns in `x dev` have to be the same loop.
+ */
+export async function createTestStatements(): Promise<TestStatements> {
+  // Imported on demand, like every other fixture factory here: a `packages/core` test that never
+  // names `statements` must not load the database layer or the entity registry to run.
+  const db = await import('@ultimat3/db');
+  const { N_PLUS_ONE_THRESHOLD, nPlusOne } = await import('@ultimat3/entity');
+  // Captured before the overwrite: the seam holds one observer, not a list, so an outer diagnostic
+  // is displaced for the length of this test and put back after it.
+  const previous = db.statementObserver();
+
+  const seen: ObservedStatement[] = [];
+  const tallies = new Map<string, ShapeTally>();
+
+  const observer: StatementObserver = {
+    onStatement(event: StatementEvent): void {
+      const fingerprint = db.statementFingerprint(event);
+      const kind = db.statementKind(event.text);
+      seen.push({
+        fingerprint,
+        kind,
+        text: event.text,
+        attribution: event.attribution,
+        expected: event.expected,
+      });
+      let tally = tallies.get(fingerprint);
+      if (tally === undefined) {
+        tally = { fingerprint, kind, count: 0, unexpected: 0, failed: false };
+        tallies.set(fingerprint, tally);
+      }
+      tally.count += 1;
+      if (event.expected !== undefined) return;
+      // A statement that threw is still a statement: fifty identical timeouts are still a loop.
+      tally.unexpected += 1;
+      if (tally.failed || tally.unexpected < N_PLUS_ONE_THRESHOLD) return;
+      tally.failed = true;
+      // `@ultimat3/entity`'s error, never one composed here: the `fix:` names the `preload` the
+      // schema's own relations spell, and a second answer to "what ends this loop" would be one
+      // the schema never agreed to.
+      throw nPlusOne({
+        kind,
+        subject: fingerprint,
+        count: tally.unexpected,
+        entity: event.attribution?.entity,
+        op: event.attribution?.op,
+      });
+    },
+  };
+  db.setStatementObserver(observer);
+
+  return {
+    all: (): readonly ObservedStatement[] => [...seen],
+    count: (fingerprint?: string): number =>
+      fingerprint === undefined ? seen.length : (tallies.get(fingerprint)?.count ?? 0),
+    shapes: (): readonly StatementShape[] =>
+      [...tallies.values()]
+        .map(({ fingerprint, kind, count }) => ({ fingerprint, kind, count }))
+        .sort((left, right) =>
+          left.count === right.count
+            ? left.fingerprint.localeCompare(right.fingerprint)
+            : right.count - left.count,
+        ),
+    [Symbol.dispose]: (): void => {
+      db.setStatementObserver(previous);
+    },
+  };
+}

package/src/fixtures.ts

@@ -15,6 +15,7 @@ import type { SignIn, Subscribe, TestBudget, TestDeploy } from './fixture-driver
 import type { RunJobs } from './fixture-jobs';
 import type { TestMail } from './fixture-mail';
 import type { TestNetwork } from './fixture-network';
+import type { TestStatements } from './fixture-statements';
 import type { PageLike } from './test-types';
 
 /** Built once per test, on first use. */
@@ -44,6 +45,7 @@ export interface Fixtures {
   readonly mail: TestMail;
   readonly network: TestNetwork;
   readonly runJobs: RunJobs;
+  readonly statements: TestStatements;
   readonly budget: TestBudget;
   readonly deploy: TestDeploy;
   readonly page: PageLike;
@@ -88,6 +90,54 @@ export function fixtureSnapshot(): FixtureMap {
   return Object.fromEntries(registry);
 }
 
+const CLOSERS: Readonly<Record<string, string>> = { '{': '}', '[': ']', '(': ')' };
+const QUOTES = new Set(['"', "'", '`']);
+
+/**
+ * The pattern's own top-level segments: the `}` that closes the opening `{`, and the commas at
+ * depth zero inside it. `indexOf('}')` stopped at the FIRST closer, so `{ mail, clock: { now },
+ * network }` lost `network` and `{ clock = { now: 1 }, mail }` lost both — silently, and a fixture
+ * that is never built reads as `undefined` in the body, which is the failure this module exists to
+ * turn into a message. Strings are skipped so a default like `{ role = 'a, b' }` is one segment.
+ */
+function patternSegments(source: string, open: number): readonly string[] | undefined {
+  const segments: string[] = [];
+  const stack: string[] = [];
+  let start = open + 1;
+  let quote: string | undefined;
+  for (let index = open; index < source.length; index += 1) {
+    const char = source[index] ?? '';
+    if (quote !== undefined) {
+      if (char === '\\') index += 1;
+      else if (char === quote) quote = undefined;
+      continue;
+    }
+    if (QUOTES.has(char)) {
+      quote = char;
+      continue;
+    }
+    const closer = CLOSERS[char];
+    if (closer !== undefined) {
+      stack.push(closer);
+      continue;
+    }
+    if (stack.length > 0 && char === stack[stack.length - 1]) {
+      stack.pop();
+      if (stack.length === 0) {
+        segments.push(source.slice(start, index));
+        return segments;
+      }
+      continue;
+    }
+    if (char === ',' && stack.length === 1) {
+      segments.push(source.slice(start, index));
+      start = index + 1;
+    }
+  }
+  // An unbalanced pattern is not one this can read; building nothing beats guessing a name.
+  return undefined;
+}
+
 /**
  * The names a body destructures, read from its source.
  *
@@ -100,15 +150,11 @@ export function requestedFixtures(body: (...args: never[]) => unknown): readonly
   const source = body.toString();
   const open = source.indexOf('{');
   if (open === -1) return [];
-  const close = source.indexOf('}', open);
-  if (close === -1) return [];
   // Bail if the brace opens a body rather than a destructuring pattern — `async () => {`.
   const beforeBrace = source.slice(0, open);
   if (/\)\s*(?::[^=]*)?=>\s*$/.test(beforeBrace) || /\)\s*$/.test(beforeBrace)) return [];
-  return source
-    .slice(open + 1, close)
-    .split(',')
-    .map((part) => (part.split(':')[0] ?? '').trim())
+  return (patternSegments(source, open) ?? [])
+    .map((part) => (part.split(/[:=]/)[0] ?? '').trim())
     .filter((name) => /^[A-Za-z_$][\w$]*$/.test(name));
 }
 

package/src/framework-fixtures.ts

@@ -7,6 +7,7 @@ import { DRIVER_FIXTURE_NAMES, driverFixtures } from './fixture-drivers';
 import { createRunJobs } from './fixture-jobs';
 import { createTestMail } from './fixture-mail';
 import { createTestNetwork } from './fixture-network';
+import { createTestStatements } from './fixture-statements';
 import { defineFixtures } from './fixtures';
 
 /**
@@ -15,7 +16,13 @@ import { defineFixtures } from './fixtures';
  * installs. See `fixture-drivers.ts` for why a declared-and-unavailable fixture beats an
  * unregistered name.
  */
-export const FRAMEWORK_FIXTURE_NAMES = ['clock', 'mail', 'network', 'runJobs'] as const;
+export const FRAMEWORK_FIXTURE_NAMES = [
+  'clock',
+  'mail',
+  'network',
+  'runJobs',
+  'statements',
+] as const;
 
 export { DRIVER_FIXTURE_NAMES };
 
@@ -38,5 +45,6 @@ export function registerFrameworkFixtures(): void {
     mail: createTestMail,
     network: createTestNetwork,
     runJobs: createRunJobs,
+    statements: createTestStatements,
   });
 }

package/src/harness.ts

@@ -3,8 +3,14 @@
 // into a race and every failure into a log-scraping exercise.
 
 import { afterAll, beforeAll, describe, test } from 'bun:test';
-import { installDeterminism, restoreDeterminism } from './determinism';
-import { allowHost, resetNetwork, sealNetwork, unsealNetwork } from './sealed-network';
+import { captureDeterminism, installDeterminism, restoreCapturedDeterminism } from './determinism';
+import {
+  allowHost,
+  isNetworkSealed,
+  resetNetwork,
+  sealNetwork,
+  unsealNetwork,
+} from './sealed-network';
 import type { TemplateDbConfig, WorkerDatabase } from './template-db';
 import { acquireWorkerDatabase } from './template-db';
 import type { TestType } from './test-types';
@@ -36,19 +42,77 @@ export interface AppHandle {
 
 const BASE = 'http://app.test';
 
-async function boot(
+export interface BootedHarness {
+  readonly handle: AppHandle;
+  close(): Promise<void>;
+}
+
+export interface HarnessDeps {
+  /**
+   * How this harness gets a database. A parameter for the reason `TemplateDbDeps.connect` is one:
+   * the rejection path below drops what it acquired, and the PGlite fallback's `drop` is a no-op,
+   * so proving it needs an injected handle rather than a server.
+   */
+  readonly acquire: (config: TemplateDbConfig) => Promise<WorkerDatabase>;
+}
+
+/**
+ * The lifecycle `describeApp` and `testApp` are the two idiomatic wrappers around. Exported from
+ * this module but deliberately NOT from `src/index.ts`: those two are the ways an app boots, and a
+ * third public entry point would be a second answer to one question. It is exported at all because
+ * the teardown contract — a rejecting `close` must still drop the cloned database — cannot be
+ * asserted through a wrapper that rethrows into the test's own result.
+ */
+export async function bootApp(
   options: AppOptions,
-): Promise<{ handle: AppHandle; close: () => Promise<void> }> {
-  installDeterminism({
-    ...(options.seedValue === undefined ? {} : { seed: options.seedValue }),
-    ...(options.now === undefined ? {} : { now: options.now }),
-  });
+  deps: Partial<HarnessDeps> = {},
+): Promise<BootedHarness> {
+  // Captured, never assumed. The preload already sealed the network and installed determinism for
+  // the whole process, so `sealNetwork()` here is a no-op and an unconditional teardown would hand
+  // the real `fetch`, the real `Date` and the real `Math.random` to every later FILE in the run —
+  // `bun test` is one process. Restore only what this boot actually changed.
+  const determinism = captureDeterminism();
+  const sealedBefore = isNetworkSealed();
+
+  // Only when this boot has something of its own to say. A run configured with ULTIMATE_TEST_NOW /
+  // ULTIMATE_TEST_SEED (`preload.ts`) is otherwise reset to the defaults by the first describeApp.
+  if (!determinism.installed || options.seedValue !== undefined || options.now !== undefined) {
+    installDeterminism({
+      ...(options.seedValue === undefined ? {} : { seed: options.seedValue }),
+      ...(options.now === undefined ? {} : { now: options.now }),
+    });
+  }
   sealNetwork();
   for (const host of options.allowHosts ?? []) allowHost(host);
 
-  const db = await acquireWorkerDatabase(options.db ?? {});
-  if (options.seed !== undefined) await options.seed(db.url);
-  const app = await options.boot({ databaseUrl: db.url });
+  // What `close` puts back, named once: the boot has to run it too, and two copies of this list is
+  // how one of them ends up missing the allow-list.
+  const restoreProcessState = (): void => {
+    resetNetwork();
+    if (!sealedBefore) unsealNetwork();
+    restoreCapturedDeterminism(determinism);
+  };
+
+  let db: WorkerDatabase | undefined;
+  let app: BootedApp;
+  try {
+    db = await (deps.acquire ?? acquireWorkerDatabase)(options.db ?? {});
+    if (options.seed !== undefined) await options.seed(db.url);
+    app = await options.boot({ databaseUrl: db.url });
+  } catch (error) {
+    // A boot that rejects returns no `BootedHarness`, so nothing can ever call the `close` below —
+    // the same leak that block exists to prevent, one function earlier. A failing `seed` stranded
+    // its clone and left the clock, the seal and the allow-list this boot installed to every later
+    // FILE in the run; `bun test` is one process.
+    try {
+      await db?.drop();
+    } catch {
+      // The boot's own failure is what the caller must see, and there is no handle to report a
+      // second one through — the same "first failure wins" rule `close` runs by.
+    }
+    restoreProcessState();
+    throw error;
+  }
 
   const handle: AppHandle = {
     db,
@@ -61,12 +125,24 @@ async function boot(
 
   return {
     handle,
+    // Every step runs even when an earlier one rejects, and the FIRST failure is what the caller
+    // sees — the same rule `fixtures.ts` disposes by. An `app.close()` that threw used to strand
+    // the clone: one `ultimate_test_template_wN` leaked per failing run, and the seal and the
+    // clock were never put back either.
     close: async () => {
-      await app.close?.();
-      await db.drop();
-      resetNetwork();
-      unsealNetwork();
-      restoreDeterminism();
+      let failure: { readonly error: unknown } | undefined;
+      try {
+        await app.close?.();
+      } catch (error) {
+        failure = { error };
+      }
+      try {
+        await db.drop();
+      } catch (error) {
+        failure ??= { error };
+      }
+      restoreProcessState();
+      if (failure !== undefined) throw failure.error;
     },
   };
 }
@@ -81,9 +157,9 @@ export function describeApp(
   body: (app: () => AppHandle) => void,
 ): void {
   describe(name, () => {
-    let booted: { handle: AppHandle; close: () => Promise<void> } | undefined;
+    let booted: BootedHarness | undefined;
     beforeAll(async () => {
-      booted = await boot(options);
+      booted = await bootApp(options);
     });
     afterAll(async () => {
       await booted?.close();
@@ -104,7 +180,7 @@ export function testApp(
   type: TestType = 'unit',
 ): void {
   test(testName(type, name), async () => {
-    const booted = await boot(options);
+    const booted = await bootApp(options);
     try {
       await body(booted.handle);
     } finally {

package/src/index.ts

@@ -23,16 +23,21 @@ export {
 // `test` is OURS (fixture-injecting); everything else passes through. Re-exported so an app
 // test has one import line, and so `expect` carries this package's matchers already installed.
 export { afterAll, afterEach, beforeAll, beforeEach, describe, expect } from 'bun:test';
-export type { DeterminismOptions } from './determinism';
+export type { DeterminismOptions, DeterminismSnapshot } from './determinism';
+// `captureDeterminism` + `restoreCapturedDeterminism` are the pair a NESTED install needs;
+// `restoreDeterminism` uninstalls outright and hands the real clock and the real `Math.random`
+// back to every later file in the process, which is only ever what the process itself wants.
 export {
   advanceClock,
   assertDeterministic,
+  captureDeterminism,
   DEFAULT_NOW,
   DEFAULT_SEED,
   frozenClock,
   frozenNow,
   installDeterminism,
   isDeterminismInstalled,
+  restoreCapturedDeterminism,
   restoreDeterminism,
   seededRandom,
   seededUuid,
@@ -44,6 +49,7 @@ export {
   NetworkOfflineError,
   NetworkSealedError,
   NondeterministicError,
+  RegistryLeakError,
   TESTING_ERROR_CODES,
   TESTING_ERROR_TITLES,
   TestDatabaseUnavailableError,
@@ -83,6 +89,8 @@ export type { MailRef, TestMail } from './fixture-mail';
 export { createTestMail } from './fixture-mail';
 export type { TestNetwork } from './fixture-network';
 export { createTestNetwork } from './fixture-network';
+export type { ObservedStatement, StatementShape, TestStatements } from './fixture-statements';
+export { createTestStatements } from './fixture-statements';
 export { fixtureTest as test } from './fixtures';
 export {
   ALL_FIXTURE_NAMES,
@@ -94,6 +102,14 @@ export type { AppHandle, AppOptions, BootedApp } from './harness';
 export { describeApp, testApp } from './harness';
 export type { MatcherResult } from './matchers';
 export { matchersInstalled, recordSteps } from './matchers';
+// `isolateEntityRegistry` is deliberately NOT here — it is `@ultimat3/testing/registry-isolation`.
+// This barrel is what a `packages/core` test imports for `expect` alone, and a static re-export
+// evaluates the module it names: that one would load `@ultimat3/entity` and its process-global
+// registry into every test in the framework. Every other package this harness touches is imported
+// dynamically inside the fixture that needs it; a helper that must stay synchronous cannot do that,
+// so it gets its own entry point instead.
+export type { RegistryLeak, RegistrySample } from './registry-leak-guard';
+export { installRegistryLeakGuard, leakBetween, sampleRegistries } from './registry-leak-guard';
 export type { MockRoute, NetworkState } from './sealed-network';
 // `setNetworkState` is deliberately not here: it is the offline gate's one writer, and a test that
 // called it directly would bypass the `network` fixture's disposal and leave the whole process
@@ -138,6 +154,7 @@ export {
   contractTest,
   e2eTest,
   evalTest,
+  hasE2eDriver,
   jobTest,
   liveTest,
   SEPARATOR,

package/src/matchers.ts

@@ -105,6 +105,43 @@ const result = (pass: boolean, message: string): MatcherResult => ({
   message: () => message,
 });
 
+const isOpenApiLike = (value: unknown): value is OpenApiLike =>
+  isRecord(value) &&
+  Array.isArray(value['operations']) &&
+  value['operations'].every(
+    (entry) => typeof (entry as OpenApiLike['operations'][number] | null)?.operationId === 'string',
+  );
+
+/**
+ * The two breaking changes this matcher can see from the shape `OpenApiLike` declares: an
+ * operation that disappeared, and a parameter a surviving operation newly requires — the second
+ * breaks every caller already omitting it, and comparing operation ids alone let it through while
+ * a suite naming this matcher read as covered.
+ *
+ * Deliberately NOT a full OpenAPI diff. Response status codes, response schemas and parameter
+ * TYPES are not on `OpenApiLike` and are not compared; the message says what did break rather than
+ * claiming the contract is otherwise unchanged. `x verify`'s `contract-diff` step is the whole
+ * answer, against the committed manifest.
+ */
+function breakingChanges(before: OpenApiLike, after: OpenApiLike): readonly string[] {
+  const current = new Map(after.operations.map((operation) => [operation.operationId, operation]));
+  const broke: string[] = [];
+  for (const operation of before.operations) {
+    const now = current.get(operation.operationId);
+    if (now === undefined) {
+      broke.push(`removed operation ${operation.operationId}`);
+      continue;
+    }
+    // Only additions: dropping a requirement widens what the API accepts, which no caller notices.
+    const wasRequired = new Set(operation.required ?? []);
+    const added = (now.required ?? []).filter((name) => !wasRequired.has(name));
+    if (added.length > 0) {
+      broke.push(`${operation.operationId} newly requires ${added.join(', ')}`);
+    }
+  }
+  return broke;
+}
+
 expect.extend({
   toBeUltimateError(received: unknown, code?: string) {
     const actual = codeOf(received);
@@ -135,13 +172,16 @@ expect.extend({
   },
 
   toMatchOpenApi(received: unknown, committed: OpenApiLike) {
-    const current = received as OpenApiLike;
-    const before = committed.operations.map((operation) => operation.operationId).sort();
-    const after = current.operations.map((operation) => operation.operationId).sort();
-    const removed = before.filter((id) => !after.includes(id));
+    if (!isOpenApiLike(received)) {
+      return result(
+        false,
+        'expected an OpenAPI document — an object with operations: [{ operationId, required? }]',
+      );
+    }
+    const broke = breakingChanges(committed, received);
     return result(
-      removed.length === 0,
-      `contract removed operation(s): ${removed.join(', ')} — bump the package version or restore them`,
+      broke.length === 0,
+      `contract broke: ${broke.join('; ')} — bump the package version or restore the old shape`,
     );
   },
 

package/src/preload.ts

@@ -8,6 +8,7 @@
 import { installDeterminism } from './determinism';
 import { registerFrameworkFixtures } from './framework-fixtures';
 import './matchers';
+import { installRegistryLeakGuard } from './registry-leak-guard';
 import { sealNetwork } from './sealed-network';
 
 const seed = Number.parseInt(Bun.env['ULTIMATE_TEST_SEED'] ?? '', 10);
@@ -20,6 +21,10 @@ installDeterminism({
 
 registerFrameworkFixtures();
 
+// One `bun test` invocation is one process: a file that leaves a process-global registry dirty
+// fails a later file in another package, for a reason nothing in that file explains.
+installRegistryLeakGuard();
+
 // Opt-out exists for one case: a test that deliberately exercises a real integration in a job the
 // team runs on purpose. It is an env var, not an API, so it cannot be set from inside a test file.
 if (Bun.env['ULTIMATE_TEST_ALLOW_NET'] !== '1') sealNetwork();

package/src/registry-isolation.ts

@@ -0,0 +1,36 @@
+// One test seam: an empty entity registry for the test that needs one, and the process's own
+// registry back afterwards. `entity()` registers at MODULE scope — which is idiomatic, an app
+// declares its domain by importing it — so a test asserting on the WHOLE registry inherits every
+// entity any earlier file in the same `bun test` process imported, and its premise becomes
+// whatever ran before it rather than what it declared.
+//
+// Its OWN entry point (`@ultimat3/testing/registry-isolation`), off the barrel: the value import
+// below is static because the restore has to be handed back synchronously, so re-exporting this
+// from `src/index.ts` would load the entity registry into every test that imports the harness for
+// `expect`. One import line is worth less than a tier-0 test that stays tier-0.
+
+import { clearRegistry, registerEntity, registeredEntities } from '@ultimat3/entity';
+
+/**
+ * Empties the entity registry and returns the function that puts it back, entry for entry.
+ * For a test whose subject is "no entities are declared" — `x db gen` with nothing to generate,
+ * a manifest with no rows — which is otherwise true only until a neighbouring file imports one:
+ *
+ *   const restoreEntities = isolateEntityRegistry();
+ *   try {
+ *     // …the assertion that needs an empty registry
+ *   } finally {
+ *     restoreEntities();
+ *   }
+ *
+ * Restoring rather than leaving it empty is the half that matters: `entity()` runs once per
+ * module, so a registry cleared and not refilled cannot be repopulated by a later import.
+ */
+export function isolateEntityRegistry(): () => void {
+  const captured = registeredEntities();
+  clearRegistry();
+  return () => {
+    clearRegistry();
+    for (const entry of captured) registerEntity(entry);
+  };
+}

package/src/registry-leak-guard.ts

@@ -0,0 +1,138 @@
+// Cross-file state pollution, caught at the boundary it crosses. `bun test` runs every file of one
+// invocation in ONE process — only `--isolate` gives each file its own module registry — so a file
+// that leaves a process-global registry dirty changes what every file after it sees, and the
+// failure lands on an innocent suite in another package. This names the file that leaked.
+
+import { afterAll } from 'bun:test';
+import { knownTags, registeredTiers } from '@ultimat3/cache';
+import { RegistryLeakError } from './errors';
+
+/**
+ * What is guarded, and why only these two. Both are BOOT installs — `declareTags` takes the
+ * manifest's entity names, `registerTier` takes `app.config.ts`'s tiers — so "empty again when the
+ * file ends" is the honest invariant for a test. The entity, job, route and permission registries
+ * are not here: `entity()` and `job()` register at module scope, which is how an app declares
+ * itself, so a file that leaves them filled is idiomatic rather than leaky. A test whose subject is
+ * an EMPTY one of those establishes it itself — `isolateEntityRegistry()`.
+ */
+export interface RegistrySample {
+  readonly tags: readonly string[];
+  readonly tiers: readonly string[];
+}
+
+export interface RegistryLeak {
+  /** Repo-relative when it can be, so the message names the file an editor opens. */
+  readonly file: string;
+  readonly tags: readonly string[];
+  readonly tiers: readonly string[];
+}
+
+export function sampleRegistries(): RegistrySample {
+  return { tags: [...knownTags()], tiers: registeredTiers().map((tier) => tier.name) };
+}
+
+/**
+ * Additions only. A file that DROPS a tier a previous file registered is a different bug and not
+ * this one's to report — reporting both here would make the message ambiguous about which file to
+ * open.
+ */
+export function leakBetween(
+  file: string,
+  before: RegistrySample,
+  after: RegistrySample,
+): RegistryLeak | undefined {
+  const tags = after.tags.filter((name) => !before.tags.includes(name));
+  const tiers = after.tiers.filter((name) => !before.tiers.includes(name));
+  if (tags.length === 0 && tiers.length === 0) return undefined;
+  return { file, tags, tiers };
+}
+
+/** `Bun.file(path).text()` answers an absolute path; the message wants the one a reader types. */
+const repoRelative = (path: string): string => {
+  const root = `${process.cwd()}/`;
+  return path.startsWith(root) ? path.slice(root.length) : path;
+};
+
+/**
+ * The one point at which a file's baseline is honest, and the reason it is not a hook. Measured on
+ * Bun 1.3.14 with a `Bun.plugin` load handler and hooks at every scope, the order is:
+ *
+ *   onLoad → module eval → file `beforeAll` → describe `beforeAll` → preload `beforeEach` → test
+ *
+ * A preload's `beforeEach` therefore runs AFTER the file's own `beforeAll`, so a `declareTags()`
+ * there landed in the baseline and the file read clean — a false green in the guard whose entire
+ * job is catching false greens. Appending the sample to the file's own source is what puts it
+ * after module evaluation (its environment) and before the first hook the file registers (its own
+ * doing). `bun:test` hooks carry no file identity; this loader does.
+ */
+const BASELINE_HOOK = '__ultimateRegistryLeakBaseline';
+
+/** Appended, never prepended: an `import` is hoisted and would sample before the graph evaluates. */
+const SAMPLE_BASELINE = `\n;globalThis[${JSON.stringify(BASELINE_HOOK)}]?.();\n`;
+
+const hookHost = globalThis as typeof globalThis & { [BASELINE_HOOK]?: () => void };
+
+let installed = false;
+
+/**
+ * Called by the test preload, once per process. Idempotent because two preloads reaching it would
+ * otherwise register the hooks twice and report every leak twice.
+ *
+ * Under `--isolate` each file gets its own module registry, so the guard judges that one file and
+ * nothing carries across — which is correct, not a hole: with `--isolate` there is no cross-file
+ * pollution to find, and a file that leaks is still reported against itself.
+ */
+export function installRegistryLeakGuard(): void {
+  if (installed) return;
+  installed = true;
+
+  let pending: string | undefined;
+  let current: { readonly file: string; readonly before: RegistrySample } | undefined;
+  const leaks: RegistryLeak[] = [];
+
+  const close = (): void => {
+    if (current === undefined) return;
+    const leak = leakBetween(current.file, current.before, sampleRegistries());
+    if (leak !== undefined) leaks.push(leak);
+    current = undefined;
+  };
+
+  // Called by the statement appended below, once per test file, from that file's own module scope:
+  // everything the file's MODULE graph registered is its environment — importing an app module is
+  // how an app declares its tags — and everything after this point is the file's own to undo.
+  hookHost[BASELINE_HOOK] = () => {
+    if (pending === undefined) return;
+    current = { file: pending, before: sampleRegistries() };
+    pending = undefined;
+  };
+
+  // The only signal Bun gives a preload for "a new test file starts": its hooks carry no file. A
+  // load handler MUST answer with contents — one that answers `undefined` makes Bun load nothing
+  // for the file and the run reports zero tests, silently.
+  Bun.plugin({
+    name: 'ultimate-registry-leak-guard',
+    setup(build) {
+      // `.test.ts` only, never `.test.tsx`. A load handler that answered `loader: 'tsx'` would
+      // compile JSX with Bun's CLASSIC React fallback — the very factory `@ultimat3/render`'s own
+      // loader exists to replace — and, because the first matching handler wins and this one is
+      // registered from the preload, it would shadow render's transform for that file. Routing
+      // `.tsx` through `transformTsx` is not the alternative either: it needs `@ultimat3/render`,
+      // whose import installs that global loader into every test process in the repo. Zero
+      // `.test.tsx` files exist and the convention is `<file>.test.ts`, so the narrower filter
+      // costs nothing today; a `.test.tsx` added later is unguarded rather than mis-compiled.
+      build.onLoad({ filter: /\.test\.ts$/ }, async (args) => {
+        close();
+        pending = repoRelative(args.path);
+        return {
+          contents: `${await Bun.file(args.path).text()}${SAMPLE_BASELINE}`,
+          loader: 'ts',
+        };
+      });
+    },
+  });
+
+  afterAll(() => {
+    close();
+    if (leaks.length > 0) throw new RegistryLeakError({ leaks });
+  });
+}

package/src/template-db.ts

@@ -130,11 +130,19 @@ export async function acquireWorkerDatabase(
   try {
     await admin.exec(lockSql(template));
     try {
-      await admin.exec(createTemplateSql(template));
+      try {
+        await admin.exec(createTemplateSql(template));
+      } catch (error) {
+        // Tolerated for the CREATE alone: "already exists" means another worker got here first, or
+        // a Postgres that outlives one run still holds last run's template.
+        if (!alreadyExists(error)) throw error;
+      }
+      // Outside that tolerance on purpose, and unconditional. A template found rather than created
+      // is not a migrated one — skipping here clones the first run's schema forever, on every
+      // server that is not a fresh CI container. Migrations are idempotent and the advisory lock
+      // serialises them, so a failure here is a real failure and `alreadyExists` (a substring match
+      // on the message) would read `relation "x_jobs" already exists` as success.
       if (config.migrate !== undefined) await config.migrate(urlFor(adminUrl, template));
-    } catch (error) {
-      // "already exists" means another worker migrated it first — the lock made that safe.
-      if (!alreadyExists(error)) throw error;
     } finally {
       await admin.exec(unlockSql(template));
     }

package/src/test-types.ts

@@ -81,14 +81,25 @@ export type E2eBody = (fixtures: E2eFixtures) => Promise<void>;
 let e2eDriver: ((name: string, body: E2eBody) => void) | undefined;
 
 /**
- * Register the Playwright-backed driver. The e2e package wires this up; without it e2e tests are
- * skipped loudly rather than failing on a missing browser, and `x verify` reports the step as
- * skipped rather than green.
+ * Register the browser-backed driver. Without one, `e2eTest` skips loudly — the skipped test's own
+ * NAME carries the reason and the command that would build what it drives.
+ *
+ * What the gate then reports is a **pass over an all-skipped suite**, and that is stated here
+ * rather than claimed away: this used to say "`x verify` reports the step as skipped rather than
+ * green", which nothing implements. The step shells out to `bun test`, `bun test` exits 0 on a
+ * skip, and an exit code is the only channel between the two — the driver is registered inside the
+ * CHILD process, so the step cannot ask. Closing it means a channel the step can read, which is a
+ * design decision and not a docstring. `As of 2026-08` there are zero registered drivers, so every
+ * `e2eTest` in the tree is a skip; the framework's own `e2e` suites use plain `bun:test`.
  */
 export function useE2eDriver(driver: (name: string, body: E2eBody) => void): void {
   e2eDriver = driver;
 }
 
+/** Whether a driver is registered. Exported so a harness can say which of the two states it is in
+ * instead of reading an all-skipped run as a green one. */
+export const hasE2eDriver = (): boolean => e2eDriver !== undefined;
+
 export const e2eTest = (name: string, body: E2eBody): void => {
   if (e2eDriver === undefined) {
     test.skip(