@ultimat3/testing 3.0.0 → 4.0.0

package/CLAUDE.md

@@ -21,6 +21,7 @@ is its own entry point and not part of the barrel.
 | 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` |
+| `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` — so a suite pinning "never throw a bare `Error`" stayed green through exactly the regression it guards (`matchers.test.ts`). Same discriminator `packages/cli/src/output.ts` uses to decide what the terminal shows, and a hostile getter answers `undefined` instead of raising inside the assertion |
 | 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`) |
@@ -36,6 +37,7 @@ is its own entry point and not part of the barrel.
 | 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 |
+| Reported and restored are different sets | the guard also RESTORES, at the same file boundary, the registries whose module-scope declarations a neighbour's cleanup destroys — the locale config, the catalogs, the permission set and the role map (`registry-snapshot.ts`). A module evaluates once per process, so a later file's own `import` is a cache hit that declares nothing: `clearPermissions()` in one CLI test took `admin:*` from `@ultimat3/admin`'s barrel for the whole run, and a `defineCatalogs()` inside a loaded app narrowed `supported` so `Accept-Language: de-DE` answered `en` in files that never mentioned locales. Nothing restored is reported and nothing reported is restored — a repair followed by a failure over it would be two answers to one question |
 | 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` |

package/README.md

@@ -21,7 +21,8 @@ frozen clock. Never let a test reach the network unmocked — it fails by design
 | `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-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-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 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -33,12 +33,14 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@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"
+    "@ultimat3/cache": "4.0.0",
+    "@ultimat3/core": "4.0.0",
+    "@ultimat3/db": "4.0.0",
+    "@ultimat3/entity": "4.0.0",
+    "@ultimat3/i18n": "4.0.0",
+    "@ultimat3/jobs": "4.0.0",
+    "@ultimat3/mail": "4.0.0",
+    "@ultimat3/policy": "4.0.0",
+    "@ultimat3/time": "4.0.0"
   }
 }

package/src/factories.ts

@@ -63,7 +63,15 @@ export interface FactoryOptions<TRow, TTraits extends TraitMap<TRow> = TraitMap<
   /** Values for every column the entity requires; called once per built row. */
   defaults(index: number, ids: FactoryIds): TRow;
   readonly traits?: TTraits;
-  readonly associations?: AssociationMap<TRow>;
+  /**
+   * `NoInfer`, because `AssociationMap<TRow>` is homomorphic over `keyof TRow` and TypeScript
+   * reverse-maps it into an inference candidate: a factory declaring `associations: { orgId }`
+   * inferred `TRow = { orgId: string }` and silently dropped every other column from `build()`,
+   * `Partial<TRow>` overrides and `Trait<TRow>`. Associations are a SUBSET of the columns by
+   * construction, so they can never be a correct source for the row type — `defaults` is, and it
+   * is the one member required to name every column.
+   */
+  readonly associations?: AssociationMap<NoInfer<TRow>>;
 }
 
 export interface Factory<TRow, TTrait extends string = string> {
@@ -117,8 +125,13 @@ export function defineFactory<TRow extends object, TTraits extends TraitMap<TRow
     number: () => Math.floor(random() * 1_000_000),
   };
 
+  // `Object.hasOwn`, not `traits[name] === undefined`: the plain read walked the prototype chain,
+  // so `f.with('toString')` was ACCEPTED and applied `Object.prototype.toString` — `overridesOf`
+  // called it with no receiver, got `"[object Undefined]"` and spread a string, producing a row
+  // with 18 numeric columns that `create()` then handed to `persistRow`. `f.with('constructor')`
+  // was accepted the same way and applied nothing at all.
   const assertTrait = (name: string): string => {
-    if (traits[name] === undefined) {
+    if (!Object.hasOwn(traits, name)) {
       throw new FactoryTraitUnknownError({ table: entity.table, trait: name, declared });
     }
     return name;

package/src/fixture-drivers.ts

@@ -21,6 +21,14 @@ export interface TestDeploy {
 /**
  * What `query.live(input, { actor })` resolves to, named structurally so `@ultimat3/testing` does
  * not take a dependency on `@ultimat3/query` for one type. The real `LiveQuery` satisfies it.
+ *
+ * NOT what `query.as(actor, input)` resolves to, which is a ROW ARRAY — and the difference is
+ * invisible until a driver exists. `examples/dummy`'s five `subscribe` tests all call
+ * `subscribe(liveFeed.as(actor, input))`, which is `TS2345` against `Subscribe` below and has
+ * never been read, because that app's `typecheck` is pinned red in `scripts/lib/gated-apps.ts`.
+ * A driver built to satisfy those call sites would have to accept a row array — and a `subscribe`
+ * loose enough to do that proves nothing, which is strictly worse than the fixture being
+ * unavailable, because it then reads as coverage.
  */
 export interface LiveTarget {
   readonly name: string;
@@ -62,7 +70,9 @@ export const DRIVER_FIXTURE_NEEDS: Readonly<Record<DriverFixtureName, string>> =
   deploy: 'a second build to switch the running app to',
   page: 'a browser driving the built app',
   signIn: 'a browser session against the app’s own sign-in route',
-  subscribe: 'an in-process replicator feeding the live-query registry',
+  subscribe:
+    'an in-process replicator feeding the live-query registry, and a caller that hands it ' +
+    'query.live(input, { actor }) — query.as() resolves to ROWS, which is not a LiveTarget',
 };
 
 /**

package/src/fixtures.ts

@@ -160,6 +160,21 @@ export function requestedFixtures(body: (...args: never[]) => unknown): readonly
 
 export type FixtureBody = (fixtures: Fixtures) => void | Promise<void>;
 
+/**
+ * What the RUNNER hands a body, which is wider than `Fixtures` and always was: `defineFixtures`
+ * accepts a key `Fixtures` does not name — "the app's", per its own docstring — so a body
+ * destructuring an app-registered fixture is the primary case, not an edge. `runWithFixtures`
+ * built exactly this shape and then asserted it back to `Fixtures` to call the body.
+ *
+ * `fixtureTest` still takes `FixtureBody`, so nothing an app writes gets looser: the framework
+ * keys stay exactly typed, and an app types its OWN keys by augmenting `Fixtures`, which remains
+ * the one documented way to do it.
+ */
+export type FixtureBag = Fixtures & Readonly<Record<string, unknown>>;
+
+/** The runner's body. Looser than `FixtureBody` for the reason `FixtureBag` states. */
+export type FixtureRunBody = (bag: FixtureBag) => unknown;
+
 /**
  * A fixture that installs process-global state — the ambient job driver, the ambient mail
  * driver — implements one of the standard disposal symbols to put it back. Bun shares one
@@ -187,8 +202,8 @@ const disposerOf = (value: unknown): (() => PromiseLike<void> | void) | undefine
  * testing, and it cannot be observed through a registration. Not in the package's public API:
  * `fixtureTest` stays the one way to write a test with fixtures.
  */
-export async function runWithFixtures(body: FixtureBody): Promise<void> {
-  const wanted = requestedFixtures(body as (...args: never[]) => unknown);
+export async function runWithFixtures(body: FixtureRunBody): Promise<void> {
+  const wanted = requestedFixtures(body);
   // Partial by construction — only what the body destructured is built. Handed over as the
   // full `Fixtures` because the keys came from that same body: a key it did not name is a key
   // it cannot read, so the missing ones are unobservable.
@@ -205,7 +220,7 @@ export async function runWithFixtures(body: FixtureBody): Promise<void> {
       built.push(value);
       bag[key] = value;
     }
-    await body(bag as Fixtures);
+    await body(bag as FixtureBag);
   } catch (error) {
     failure = { error };
   }

package/src/harness.ts

@@ -6,8 +6,9 @@ import { afterAll, beforeAll, describe, test } from 'bun:test';
 import { captureDeterminism, installDeterminism, restoreCapturedDeterminism } from './determinism';
 import {
   allowHost,
+  captureNetwork,
   isNetworkSealed,
-  resetNetwork,
+  restoreCapturedNetwork,
   sealNetwork,
   unsealNetwork,
 } from './sealed-network';
@@ -73,6 +74,10 @@ export async function bootApp(
   // `bun test` is one process. Restore only what this boot actually changed.
   const determinism = captureDeterminism();
   const sealedBefore = isNetworkSealed();
+  // The gate's own contents, not just whether it was installed. `resetNetwork()` here CLEARED the
+  // allow-list, the mocks and the offline state — the one line in this teardown that uninstalled
+  // instead of restoring, while everything around it put back what it captured.
+  const networkBefore = captureNetwork();
 
   // 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.
@@ -88,7 +93,7 @@ export async function bootApp(
   // 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();
+    restoreCapturedNetwork(networkBefore);
     if (!sealedBefore) unsealNetwork();
     restoreCapturedDeterminism(determinism);
   };

package/src/index.ts

@@ -110,18 +110,22 @@ export { matchersInstalled, recordSteps } from './matchers';
 // 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';
+export type { ProcessRegistrySnapshot } from './registry-snapshot';
+export { captureProcessRegistries, restoreProcessRegistries } from './registry-snapshot';
+export type { MockRoute, NetworkSnapshot, 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
 // offline for every file after it. The fixture is the way to go offline — there is no second one.
 export {
   allowHost,
+  captureNetwork,
   isNetworkSealed,
   mockFetch,
   mockJson,
   networkState,
   requestedUrls,
   resetNetwork,
+  restoreCapturedNetwork,
   sealNetwork,
   unsealNetwork,
 } from './sealed-network';

package/src/matcher-surface.ts

@@ -0,0 +1,32 @@
+// The custom matchers' declared surface, in ONE place: the `bun:test` augmentation, and the
+// interface `matchers.ts` implements against. Split out of `matchers.ts` because every test
+// program in the repo has to READ this declaration — `tsconfig.tests.json` names this file — and a
+// tier-0 test cannot reach it by importing tier-5 `@ultimat3/testing`.
+
+import type { OpenApiLike } from './test-types';
+
+/**
+ * One entry per `expect.extend` implementation in `matchers.ts`, and `T` is what the matcher
+ * answers with. Adding a matcher is one edit here: `matchers.ts` will not compile until it has an
+ * implementation whose arguments match, because its `expect.extend` argument is typed from this.
+ *
+ * A `.ts` and not a `.d.ts`, deliberately: `.gitignore` treats every `.d.ts` under a package's
+ * `src` as stale `tsc` emit and drops it, and the one hand-written exception
+ * (`packages/ui/src/scss.d.ts`) had to be un-ignored by name. A declaration needs no `.d.ts` to be
+ * ambient — `declare module` in any file the program reads is the augmentation.
+ */
+export interface UltimateMatchers<T> {
+  toBeUltimateError(code?: string): T;
+  toDenyPolicy(context: Readonly<Record<string, unknown>>): Promise<T>;
+  toEmitSteps(steps: readonly string[]): Promise<T>;
+  toMatchOpenApi(committed: OpenApiLike): T;
+  toBeWithinBudget(limit: number): T;
+  toRejectInput(input: unknown): Promise<T>;
+  toAcceptInput(input: unknown): Promise<T>;
+}
+
+declare module 'bun:test' {
+  // `extends`, not a restatement: bun's own docs give this shape, and it keeps the member list on
+  // `UltimateMatchers` where the implementation is checked against it.
+  interface Matchers<T> extends UltimateMatchers<T> {}
+}

package/src/matchers.ts

@@ -2,10 +2,19 @@
 // hand, differently, in every test — and a hand-written version of "did this policy deny?" is how
 // a test ends up asserting on the wrong branch.
 
+import type { ExpectExtendMatchers } from 'bun:test';
 import { expect } from 'bun:test';
+import { describeValue, isUltimateError, stringField } from '@ultimat3/core';
 import { TestJobExpectedError, TestSchemaExpectedError } from './errors';
+import type { UltimateMatchers } from './matcher-surface';
 import type { OpenApiLike } from './test-types';
 
+// Re-exported so the EMITTED `matchers.d.ts` still names `./matcher-surface`. A type-only import
+// used by a non-exported const is elided from the declaration output, and with it goes the
+// `bun:test` augmentation for anyone consuming this package through `dist/` — which is every
+// package that reaches it across a project reference.
+export type { UltimateMatchers } from './matcher-surface';
+
 export interface MatcherResult {
   readonly pass: boolean;
   message(): string;
@@ -14,10 +23,27 @@ export interface MatcherResult {
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null;
 
+/**
+ * The Ultimate error code carried by `value`, or `undefined` for anything that is not one.
+ *
+ * Three parts, not one. "An object with a string `code`" passed a Node `ENOENT` — so a suite
+ * pinning "never throw a bare Error" stayed green through exactly the regression it guards. The
+ * contract is `X_SCREAMING_SNAKE` + a cause + an executable fix, which is the same two-part
+ * discriminator `packages/cli/src/output.ts` uses to decide what the terminal shows.
+ *
+ * `stringField` and not a bare index: a matcher is asked about a value a test caught, and a
+ * throwing getter or a `Proxy` here would raise INSIDE the assertion — replacing the test's real
+ * failure with the matcher's.
+ */
 const codeOf = (value: unknown): string | undefined => {
-  if (!isRecord(value)) return undefined;
-  const code = value['code'];
-  return typeof code === 'string' ? code : undefined;
+  const code = stringField(value, 'code');
+  if (code === undefined || !code.startsWith('X_')) return undefined;
+  // A branded error is one by construction; a plain object has to show all three fields, which is
+  // what a `{ code, cause, fix }` literal in a test fixture already does.
+  if (isUltimateError(value)) return code;
+  const complete =
+    stringField(value, 'cause') !== undefined && stringField(value, 'fix') !== undefined;
+  return complete ? code : undefined;
 };
 
 /** Standard Schema is the validation contract, so every blessed schema exposes `~standard`. */
@@ -142,11 +168,22 @@ function breakingChanges(before: OpenApiLike, after: OpenApiLike): readonly stri
   return broke;
 }
 
-expect.extend({
+/**
+ * Typed from the declaration rather than inferred from this literal, which is what makes the two
+ * halves one thing: a matcher on `UltimateMatchers` with no entry here fails to compile, an entry
+ * here that nothing declares is an excess property, and an argument list that drifts from the
+ * declared one is a type error at the key that drifted. Inferred — `expect.extend({ … })` — none
+ * of the three is visible, and a declared-but-unimplemented matcher fails at runtime in whichever
+ * test calls it first.
+ */
+const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
   toBeUltimateError(received: unknown, code?: string) {
     const actual = codeOf(received);
     if (actual === undefined) {
-      return result(false, `expected an UltimateError, received ${typeof received}`);
+      return result(
+        false,
+        `expected an UltimateError (an X_ code with a cause and a fix), received ${describeValue(received)}`,
+      );
     }
     if (code === undefined) return result(true, `expected not to be an UltimateError`);
     return result(actual === code, `expected error code ${code}, received ${actual}`);
@@ -204,19 +241,9 @@ expect.extend({
     const rejected = await hasIssues(received, input);
     return result(!rejected, `expected the schema to accept ${JSON.stringify(input)}`);
   },
-});
+};
 
-declare module 'bun:test' {
-  interface Matchers<T> {
-    toBeUltimateError(code?: string): T;
-    toDenyPolicy(context: Readonly<Record<string, unknown>>): Promise<T>;
-    toEmitSteps(steps: readonly string[]): Promise<T>;
-    toMatchOpenApi(committed: OpenApiLike): T;
-    toBeWithinBudget(limit: number): T;
-    toRejectInput(input: unknown): Promise<T>;
-    toAcceptInput(input: unknown): Promise<T>;
-  }
-}
+expect.extend(implementations);
 
 /** Imported for its side effect by the preload; exported so a test can be explicit about it. */
 export const matchersInstalled = true;

package/src/registry-leak-guard.ts

@@ -1,19 +1,26 @@
-// 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.
+// Cross-file state pollution, caught at the boundary it crosses and — where a registry can be put
+// back — repaired there. `bun test` runs one invocation in ONE process, 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. What is REPORTED and what is RESTORED are disjoint sets.
 
 import { afterAll } from 'bun:test';
 import { knownTags, registeredTiers } from '@ultimat3/cache';
 import { RegistryLeakError } from './errors';
+import type { ProcessRegistrySnapshot } from './registry-snapshot';
+import { captureProcessRegistries, restoreProcessRegistries } from './registry-snapshot';
 
 /**
- * What is guarded, and why only these two. Both are BOOT installs — `declareTags` takes the
+ * What is REPORTED, 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()`.
+ *
+ * Neither is RESTORED, and that is the same judgement read the other way: `@ultimat3/cache`
+ * publishes no un-declare for a tag, so there is nothing to put a tag registry back WITH. The
+ * registries that are restored are `registry-snapshot.ts`'s, and none of them is reported —
+ * repairing a state and then failing the run over it would be two answers to one question.
  */
 export interface RegistrySample {
   readonly tags: readonly string[];
@@ -87,13 +94,23 @@ export function installRegistryLeakGuard(): void {
   installed = true;
 
   let pending: string | undefined;
-  let current: { readonly file: string; readonly before: RegistrySample } | undefined;
+  let current:
+    | {
+        readonly file: string;
+        readonly before: RegistrySample;
+        readonly snapshot: ProcessRegistrySnapshot;
+      }
+    | 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);
+    // The repair, at the only point it is safe: the file is over and the next one has not
+    // evaluated yet, so what goes back is exactly what that file inherited — module-scope
+    // declarations included, which is the half a plain `resetX()` in a `beforeEach` destroys.
+    restoreProcessRegistries(current.snapshot);
     current = undefined;
   };
 
@@ -102,7 +119,11 @@ export function installRegistryLeakGuard(): void {
   // 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() };
+    current = {
+      file: pending,
+      before: sampleRegistries(),
+      snapshot: captureProcessRegistries(),
+    };
     pending = undefined;
   };
 

package/src/registry-snapshot.ts

@@ -0,0 +1,61 @@
+// The process registries a test file inherits, captured and handed back at the file boundary;
+// `registry-leak-guard.ts` owns WHEN. A snapshot rather than a reset to defaults, because what a
+// module declares at MODULE scope evaluates once per `bun test` process — a neighbour's clear is
+// permanent and there is no second evaluation left to redo it.
+
+import type { Catalog, Locale, LocaleConfig } from '@ultimat3/i18n';
+import {
+  catalogFor,
+  configureLocales,
+  localeConfig,
+  registerCatalog,
+  registeredLocales,
+  resetCatalogs,
+} from '@ultimat3/i18n';
+import type { RoleMap } from '@ultimat3/policy';
+import {
+  knownPermissions,
+  restorePermissions,
+  restoreRoles,
+  roleDeclarationSites,
+  roleDefinitions,
+} from '@ultimat3/policy';
+
+/**
+ * Every member is captured by value or by a reference its owner replaces rather than mutates
+ * (`configureLocales`, `defineRoles` and `registerCatalog` all build a new object and assign it),
+ * so a snapshot describes the process at the instant it was taken and no later write reaches it.
+ */
+export interface ProcessRegistrySnapshot {
+  readonly locales: LocaleConfig;
+  readonly catalogs: readonly (readonly [Locale, Catalog])[];
+  readonly permissions: readonly string[];
+  readonly roles: RoleMap;
+  /** Kept beside the map: restoring through `defineRoles()` would rewrite every site. */
+  readonly roleSites: Readonly<Record<string, string>>;
+}
+
+export function captureProcessRegistries(): ProcessRegistrySnapshot {
+  return {
+    locales: localeConfig(),
+    catalogs: registeredLocales().map((locale) => [locale, catalogFor(locale)] as const),
+    permissions: knownPermissions(),
+    roles: roleDefinitions(),
+    roleSites: roleDeclarationSites(),
+  };
+}
+
+/**
+ * Idempotent, and a REPLACE on every registry rather than a merge: a snapshot is the whole truth
+ * about the process at capture time, so anything declared since must go as surely as anything
+ * cleared since must come back.
+ */
+export function restoreProcessRegistries(snapshot: ProcessRegistrySnapshot): void {
+  // A full `LocaleConfig`, so the merge `configureLocales` performs replaces all three fields —
+  // a partial call can never widen `supported` back.
+  configureLocales(snapshot.locales);
+  resetCatalogs();
+  for (const [locale, catalog] of snapshot.catalogs) registerCatalog(locale, catalog);
+  restorePermissions(snapshot.permissions);
+  restoreRoles(snapshot.roles, snapshot.roleSites);
+}

package/src/sealed-network.ts

@@ -148,3 +148,35 @@ export function resetNetwork(): void {
   state.seen.length = 0;
   state.network = 'online';
 }
+
+/** Everything `resetNetwork` clears, as a value — so a nested scope can put it back instead. */
+export interface NetworkSnapshot {
+  readonly allowed: readonly string[];
+  readonly mocks: readonly MockRoute[];
+  readonly seen: readonly string[];
+  readonly network: NetworkState;
+}
+
+/**
+ * Capture before a nested install, restore after — the pair `captureDeterminism` /
+ * `restoreCapturedDeterminism` already ships for the clock, and for the same reason. `bun test` is
+ * ONE process: a `bootApp` that ended by CLEARING this gate took the outer scope's allow-list, its
+ * mocks and its offline state with it, so an outer fixture that was offline came back online
+ * because an inner boot finished. Teardown restores; it never uninstalls.
+ */
+export const captureNetwork = (): NetworkSnapshot => ({
+  allowed: [...state.allowed],
+  mocks: [...state.mocks],
+  seen: [...state.seen],
+  network: state.network,
+});
+
+export function restoreCapturedNetwork(snapshot: NetworkSnapshot): void {
+  state.allowed.clear();
+  for (const host of snapshot.allowed) state.allowed.add(host);
+  state.mocks.length = 0;
+  state.mocks.push(...snapshot.mocks);
+  state.seen.length = 0;
+  state.seen.push(...snapshot.seen);
+  state.network = snapshot.network;
+}

package/src/template-db.ts

@@ -3,6 +3,7 @@
 // transaction-rollback wrapper (which breaks anything that commits), no shared schema with a
 // `truncate` between tests (which serialises the suite and still leaks sequences).
 
+import { renderThrowable } from '@ultimat3/core';
 import { TestDatabaseUnavailableError } from './errors';
 
 export type DbKind = 'postgres' | 'pglite';
@@ -169,8 +170,14 @@ export async function acquireWorkerDatabase(
   };
 }
 
-const messageOf = (error: unknown): string =>
-  error instanceof Error ? error.message : String(error);
+/**
+ * Core's renderer, not a local `String(error)`. Both reads this feeds are inside a `catch` that
+ * owes its caller an answer, and `String(Object.create(null))` THROWS — a driver that rejects with
+ * a null-prototype object would have replaced `X_TEST_DATABASE_UNAVAILABLE` with a `TypeError`
+ * raised while formatting it. `bun run error-render` cannot see a value laundered through a local
+ * helper, which is exactly how this one survived.
+ */
+const messageOf = (error: unknown): string => renderThrowable(error);
 
 const alreadyExists = (error: unknown): boolean =>
   messageOf(error).toLowerCase().includes('already exists');