@ultimat3/testing 23.0.0 → 25.0.0

package/src/e2e-errors.ts

@@ -95,11 +95,22 @@ export class E2eLocatorAmbiguousError extends UltimateError {
  * test that hangs, and CI then reports a runner timeout with no assertion anywhere in it.
  */
 export class E2eServiceWorkerAbsentError extends UltimateError {
-  constructor(input: { readonly url: string; readonly timeoutMs: number }) {
+  constructor(input: {
+    readonly url: string;
+    readonly timeoutMs: number;
+    /**
+     * True when a worker was ACTIVE and the page was reloaded once for it to answer — a first
+     * page `clients.claim()` missed (#678) — and the reload was not controlled either.
+     */
+    readonly reloaded?: boolean | undefined;
+  }) {
     super({
       code: 'X_E2E_SERVICE_WORKER_ABSENT',
-      cause: `no service worker took control of ${renderCauseValue(input.url)} within ${String(input.timeoutMs)}ms`,
-      fix: `x build --target static — the worker is generated by the pwa build; then confirm the route at ${renderFixLiteral(input.url, URL_PLACEHOLDER)} registers it`,
+      cause:
+        input.reloaded === true
+          ? `a service worker is active for ${renderCauseValue(input.url)} but did not control it, even reloaded once, within ${String(input.timeoutMs)}ms`
+          : `no service worker took control of ${renderCauseValue(input.url)} within ${String(input.timeoutMs)}ms`,
+      fix: `x build --target static — the worker is generated by the pwa build; then confirm the route at ${renderFixLiteral(input.url, URL_PLACEHOLDER)} registers it, or raise this call's budget: await page.waitForServiceWorker({ timeoutMs: 30_000 })`,
     });
   }
 }

package/src/e2e-locale.ts

@@ -1,30 +1,21 @@
-// The locale an e2e run's browser asks for: the app's own `defaultLocale`, read off `app.config.ts`
-// the way the CLI reads its other boot facts. `@ultimat3/testing` sits below `@ultimat3/cli`, so the
-// file name and the export name are restated here rather than imported from it.
-
-import { join } from 'node:path'; // why: Bun ships no path join.
-
-/** The app root's config module and the export holding the config — `x new` writes both. */
-const APP_CONFIG_FILE = 'app.config.ts';
-const APP_CONFIG_EXPORT = 'config';
+// The locale an e2e run's browser asks for: the default the app's `defineCatalogs()` declared —
+// the one place an app names its locales since 25.0.0 (`app.config.ts`'s `defaultLocale` and
+// `locales` keys were deleted). Read through `@ultimat3/i18n/app-catalogs`, the one reader the CLI
+// shares; what is this file's own is the answer to a module that will not load.
 
 /**
- * The app's `defaultLocale`, or `undefined` when it cannot be read — and then nothing is pinned.
- * Never a guessed `en`: pinning the wrong language would make every run photograph and assert on a
- * page no visitor at the unprefixed URL sees, which is worse than the runner's own Chrome locale.
- * The import runs the config module, which may validate an environment this process lacks.
+ * The app's default locale, or `undefined` when it cannot be read — and then nothing is pinned.
+ * Never a guessed `en`: `loadAppCatalogs` answers only when a `defineCatalogs()` was declared.
+ * Pinning the wrong language would make every run photograph and assert on a page no visitor at
+ * the unprefixed URL sees. The import runs the app's module, which may validate an environment
+ * this process lacks — so a module that throws is "nothing pinned", never a failed run.
  */
 export async function e2eDefaultLocale(root: string): Promise<string | undefined> {
-  const path = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(path).exists())) return undefined;
-  let module: Record<string, unknown>;
+  // Dynamic, like every non-core dependency of this package: only the e2e preload pays for it.
+  const { loadAppCatalogs } = await import('@ultimat3/i18n/app-catalogs');
   try {
-    module = (await import(path)) as Record<string, unknown>;
+    return (await loadAppCatalogs(root))?.defaultLocale;
   } catch {
     return undefined;
   }
-  const config = Object.hasOwn(module, APP_CONFIG_EXPORT) ? module[APP_CONFIG_EXPORT] : undefined;
-  if (typeof config !== 'object' || config === null) return undefined;
-  const locale = (config as Record<string, unknown>)['defaultLocale'];
-  return typeof locale === 'string' && locale !== '' ? locale : undefined;
 }

package/src/e2e-page.ts

@@ -3,10 +3,10 @@
 // may import the other — so the join is here, in the one package allowed to know about both.
 
 import { finiteCount } from '@ultimat3/core';
-import { E2eServiceWorkerAbsentError } from './e2e-errors';
 import { evaluateClosure } from './e2e-evaluate';
 import { e2eLocator } from './e2e-locator';
 import type { E2eSelection } from './e2e-selection';
+import { callBudget, waitForServiceWorker } from './e2e-service-worker';
 import type { LocatorLike, PageLike } from './test-types';
 
 /**
@@ -39,7 +39,10 @@ export interface E2ePageOptions {
   readonly baseUrl: string;
   /** Per-navigation deadline, handed to the driver rather than enforced here. */
   readonly timeoutMs?: number | undefined;
-  /** How long `waitForServiceWorker()` waits before refusing. Bounded IN THE PAGE. */
+  /**
+   * How long `waitForServiceWorker()` waits before refusing, the handover reload included. Bounded
+   * IN THE PAGE. One test raises its own with `waitForServiceWorker({ timeoutMs })`.
+   */
   readonly serviceWorkerTimeoutMs?: number | undefined;
 }
 
@@ -77,24 +80,6 @@ const firstFlushExpression = (url: string): string =>
       .then((chunk) => { reader.cancel().catch(() => {}); return chunk; }); })
     .then((chunk) => JSON.stringify({ html: new TextDecoder().decode(chunk.value || new Uint8Array()) })))()`;
 
-/**
- * `ready` alone is not control: a first load activates a worker that is not yet the page's
- * controller, and an offline assertion made in that window tests nothing. So this waits for
- * `controllerchange` too — an EVENT, not a poll, so the harness still has exactly one retry loop.
- */
-const serviceWorkerExpression = (timeoutMs: number): string =>
-  `(() => {
-  if (!navigator.serviceWorker) return JSON.stringify({ controlled: false });
-  const controlled = new Promise((resolve) => {
-    if (navigator.serviceWorker.controller) { resolve(true); return; }
-    navigator.serviceWorker.addEventListener('controllerchange', () => resolve(true), { once: true });
-  });
-  const deadline = new Promise((resolve) => setTimeout(() => resolve(false), ${String(timeoutMs)}));
-  return Promise.race([navigator.serviceWorker.ready.then(() => controlled), deadline])
-    .catch(() => false)
-    .then((ok) => JSON.stringify({ controlled: ok === true }));
-})()`;
-
 /**
  * The adapter. Every member re-reads the live page: a `PageLike` handed to a test outlives every
  * navigation the test makes, so nothing here may capture a URL, a document or an element.
@@ -132,12 +117,13 @@ export function e2ePage(options: E2ePageOptions): PageLike {
       const html = readField(await page.evaluate(firstFlushExpression(target)), 'html');
       return { html: typeof html === 'string' ? html : '' };
     },
-    waitForServiceWorker: async () => {
-      const raw = await page.evaluate(serviceWorkerExpression(swTimeout));
-      if (readField(raw, 'controlled') !== true) {
-        throw new E2eServiceWorkerAbsentError({ url: page.url(), timeoutMs: swTimeout });
-      }
-    },
+    // The handover is `e2e-service-worker.ts`'s: an unclaimed first page is reloaded once (#678).
+    waitForServiceWorker: async (waitOptions) =>
+      waitForServiceWorker({
+        page,
+        timeoutMs: callBudget(swTimeout, waitOptions?.timeoutMs),
+        navigationTimeoutMs: timeout,
+      }),
     evaluate: <T>(fn: () => T): Promise<T> => evaluateClosure(page, fn) as unknown as Promise<T>,
     locator: (selector) => locate({ kind: 'css', selector, first: false }),
     getByRole: (role, roleOptions) =>

package/src/e2e-run.ts

@@ -5,7 +5,9 @@
 
 import { finiteCount } from '@ultimat3/core';
 import type { E2eBrowser } from './cdp-browser';
+import { E2E_BROWSER_CLOSE_MS, E2E_BROWSER_OPEN_MS } from './cdp-browser';
 import type { E2eApp } from './e2e-app';
+import { E2E_APP_STOP_MS } from './e2e-app';
 import { e2eBrowser, publishE2eRun, republishE2eBrowser } from './e2e-browser-handle';
 import type { E2eDriverOptions } from './e2e-driver';
 import type { E2eBrowserPage } from './e2e-page';
@@ -35,8 +37,9 @@ export interface E2eRunDeps {
   readonly app: E2eApp;
   readonly openBrowser: () => Promise<E2eBrowser>;
   readonly install: (options: E2eDriverOptions) => () => void;
-  readonly beforeEach: (hook: () => Promise<void>) => void;
-  readonly afterAll: (hook: () => Promise<void>) => void;
+  /** Bun's, in the preload: the second argument is the hook's deadline, never left to the 5 s default. */
+  readonly beforeEach: (hook: () => Promise<void>, timeoutMs: number) => void;
+  readonly afterAll: (hook: () => Promise<void>, timeoutMs: number) => void;
   readonly probeMs?: number | undefined;
 }
 
@@ -74,19 +77,26 @@ export async function startE2eRun(deps: E2eRunDeps): Promise<void> {
   // call (run 8). So each test starts with a short probe, and a browser that fails it — or one a
   // deploy ran under — is closed and relaunched: the app is untouched, and the test gets a fresh
   // profile, a fresh SharedWorker and a fresh tab on the same origin.
-  deps.beforeEach(async () => {
-    const alive = !deployed && (await answersWithin(e2eBrowser().page, probeMs));
-    if (alive) return;
-    deployed = false;
-    browser.close();
-    browser = await deps.openBrowser();
-    republishE2eBrowser(browser);
-  });
+  //
+  // Deadlines are the designed lengths of the work, because Bun's 5 s default killed both hooks
+  // mid-work: a relaunch cut short left its open in flight, assigned later over the next one's
+  // browser and never closed; a close cut short as the run exited left the profile half-removed.
+  deps.beforeEach(
+    async () => {
+      const alive = !deployed && (await answersWithin(e2eBrowser().page, probeMs));
+      if (alive) return;
+      deployed = false;
+      await browser.close();
+      browser = await deps.openBrowser();
+      republishE2eBrowser(browser);
+    },
+    probeMs + E2E_BROWSER_CLOSE_MS + E2E_BROWSER_OPEN_MS,
+  );
 
   deps.afterAll(async () => {
     setFailureContext(undefined);
     uninstall();
-    browser.close();
+    await browser.close();
     await app.stop();
-  });
+  }, E2E_BROWSER_CLOSE_MS + E2E_APP_STOP_MS);
 }

package/src/e2e-service-worker.ts

@@ -0,0 +1,92 @@
+// Single responsibility: `waitForServiceWorker()` — wait for the worker to control the page, and
+// hand the page over when it cannot claim it. The FIRST page of a run registers its worker on
+// `load`, so it is committed before the worker activates, and `clients.claim()` can miss it: `ready`
+// resolves, no `controllerchange` ever fires, and waiting longer waits for nothing (#678).
+
+import { finiteCount } from '@ultimat3/core';
+import { E2eServiceWorkerAbsentError } from './e2e-errors';
+import type { E2eBrowserPage } from './e2e-page';
+
+/**
+ * How long a page whose worker is ACTIVE waits to be claimed before it is reloaded. Activation
+ * sets `registration.active` — which resolves `ready` — before the activate handler reaches its
+ * `clients.claim()`, so the claim trails `ready` by the cache cleanup in between. A second is
+ * that gap with room; past it, the reload is cheaper than any further wait.
+ */
+export const CLAIM_GRACE_MS = 1_000;
+
+/** What the page answers. `unclaimed`: an active worker, and a document it does not control. */
+export type ServiceWorkerState = 'controlled' | 'unclaimed' | 'absent';
+
+/**
+ * The in-page half: `ready`, then the claim — an EVENT, not a poll, so the harness keeps exactly
+ * one retry loop. Bounded IN THE PAGE by `timeoutMs`: an unbounded wait is a hung test, and CI then
+ * reports a runner timeout with no assertion anywhere in it.
+ */
+export const serviceWorkerExpression = (timeoutMs: number): string =>
+  `(() => {
+  const sw = navigator.serviceWorker;
+  if (!sw) return JSON.stringify({ state: 'absent' });
+  const claimed = new Promise((resolve) => {
+    if (sw.controller) { resolve('controlled'); return; }
+    sw.addEventListener('controllerchange', () => resolve('controlled'), { once: true });
+  });
+  const grace = () => new Promise((resolve) =>
+    setTimeout(() => resolve(sw.controller ? 'controlled' : 'unclaimed'), ${String(CLAIM_GRACE_MS)}));
+  const deadline = new Promise((resolve) => setTimeout(() => resolve('absent'), ${String(timeoutMs)}));
+  return Promise.race([sw.ready.then(() => Promise.race([claimed, grace()])), deadline])
+    .catch(() => 'absent')
+    .then((state) => JSON.stringify({ state }));
+})()`;
+
+const stateOf = (raw: unknown): ServiceWorkerState | undefined => {
+  const decoded = typeof raw === 'string' ? (JSON.parse(raw) as unknown) : raw;
+  const state =
+    typeof decoded === 'object' && decoded !== null
+      ? (decoded as Record<string, unknown>)['state']
+      : undefined;
+  return state === 'controlled' || state === 'unclaimed' || state === 'absent' ? state : undefined;
+};
+
+/**
+ * The URL to reload, fragment dropped: a navigation to the same URL plus a `#fragment` is a
+ * same-document navigation in Chromium, which scrolls and never replaces the uncontrolled
+ * document — the one thing the handover reload is for.
+ */
+const withoutFragment = (href: string): string => {
+  const url = new URL(href);
+  url.hash = '';
+  return url.href;
+};
+
+export interface ServiceWorkerWait {
+  readonly page: E2eBrowserPage;
+  /** The whole budget, both checks and the reload between them. Screened by the caller. */
+  readonly timeoutMs: number;
+  /** The per-navigation deadline the reload is handed. */
+  readonly navigationTimeoutMs: number;
+}
+
+/**
+ * Wait for control; an unclaimed page is reloaded ONCE — that navigation is answered by the active
+ * worker, which is what control means — then asked again with what is left of the budget. A page
+ * with no worker at all is refused without a reload: the same request would answer the same.
+ */
+export async function waitForServiceWorker(wait: ServiceWorkerWait): Promise<void> {
+  const { page, timeoutMs } = wait;
+  const began = performance.now();
+  const first = stateOf(await page.evaluate(serviceWorkerExpression(timeoutMs)));
+  if (first === 'controlled') return;
+  if (first === 'unclaimed') {
+    await page.goto(withoutFragment(page.url()), { timeout: wait.navigationTimeoutMs });
+    const left = Math.max(CLAIM_GRACE_MS, Math.round(timeoutMs - (performance.now() - began)));
+    const second = stateOf(await page.evaluate(serviceWorkerExpression(left)));
+    if (second === 'controlled') return;
+    throw new E2eServiceWorkerAbsentError({ url: page.url(), timeoutMs, reloaded: true });
+  }
+  throw new E2eServiceWorkerAbsentError({ url: page.url(), timeoutMs, reloaded: false });
+}
+
+/** A per-call budget, screened where it is read — it is interpolated into the in-page source. */
+export const callBudget = (fallback: number, timeoutMs: number | undefined): number =>
+  timeoutMs === undefined ? fallback : finiteCount('waitForServiceWorker', 'timeoutMs', timeoutMs);

package/src/e2e-spawn.ts

@@ -8,8 +8,9 @@
 import { get } from 'node:http';
 // why: Bun exposes no path API — the CLI's bin is joined onto its package directory.
 import { dirname, join } from 'node:path';
-import { assert } from '@ultimat3/core';
+import { assert, DRAIN_DEADLINE_DEFAULT_MS, READINESS_GRACE_DEFAULT_MS } from '@ultimat3/core';
 import { E2eAppFailedError } from './e2e-errors';
+import { freePort } from './free-port';
 
 /** `x dev` (sync included), or the production entry `apps/web/server.ts` under `ROLE=web`. */
 export type E2eAppMode = 'dev' | 'serve';
@@ -42,6 +43,29 @@ export async function xBin(root: string): Promise<string> {
 }
 const POLL_MS = 250;
 
+/**
+ * How long one `/readyz` probe may hang before it counts as "not yet": an app that accepted the
+ * connection mid-boot and has not answered. The readiness deadline can overshoot by one of these.
+ */
+export const READY_PROBE_MS = POLL_MS * 4;
+
+/**
+ * What a SIGTERM'd app is given before it is killed outright: its own designed drain at the
+ * defaults — the readiness grace a deployed app holds, then `drain.deadlineMs` — because a stop
+ * shorter than the drain kills an app that was doing what it was told.
+ */
+const TERM_GRACE_MS = READINESS_GRACE_DEFAULT_MS + DRAIN_DEADLINE_DEFAULT_MS;
+
+/** After SIGKILL: the kernel's to deliver, bounded for a container whose init never reaps. */
+const KILL_GRACE_MS = 5_000;
+
+/**
+ * The longest `stop()` is DESIGNED to take: the drain, then the kill. THE deadline a hook that
+ * stops an e2e app derives from — unbounded, a wedged app held the hook until Bun killed it, and
+ * the browser close behind it in the same hook never ran.
+ */
+export const E2E_APP_STOP_MS = TERM_GRACE_MS + KILL_GRACE_MS;
+
 export interface SpawnedE2eApp {
   /** `http://localhost:<port>`, no trailing slash. */
   readonly base: string;
@@ -62,24 +86,24 @@ export interface SpawnE2eAppOptions {
   readonly readyTimeoutMs: number;
   /** `xBin(root)`, when the caller already resolved it; resolved here otherwise, in `dev` mode only. */
   readonly bin?: string | undefined;
+  /** How long a SIGTERM'd app has before SIGKILL. Defaults to the app's own drain at its defaults. */
+  readonly termGraceMs?: number | undefined;
 }
 
-/** A port nothing holds right now, asked of the OS and handed to the child. */
-const freePort = (): number => {
-  const probe = Bun.serve({ port: 0, fetch: () => new Response() });
-  const port = probe.port ?? 0;
-  probe.stop(true);
-  return port;
-};
-
 /**
  * This process's environment minus what makes the child a TEST process. Spawned from `bun test`,
  * `NODE_ENV=test` rode along and the app resolved its environment as `test` — so a development-only
  * seam (the demo viewer an app installs instead of a sign-in route) was off and every page 401'd.
  * The app under e2e is a development app unless the caller's `env` says otherwise.
+ *
+ * Minus the two bindings `ULTIMATE_STATE_DIR` relocates, too — the database and the disk. The
+ * harness boots on a throwaway state directory, and a developer's exported `DATABASE_URL` (their
+ * integration-test Postgres) turned that into a reset of a database the run does not own: `x db
+ * reset` refused it, and the e2e step went red for an environment reason (#674). A run that WANTS
+ * an external one passes it in `startE2eApp({ env })`, which is spread after this.
  */
 export const inherited = (): Record<string, string | undefined> => {
-  const { NODE_ENV: _node, ...rest } = Bun.env;
+  const { NODE_ENV: _node, DATABASE_URL: _db, S3_ENDPOINT: _disk, ...rest } = Bun.env;
   return { ...rest, ULTIMATE_ENV: 'development' };
 };
 
@@ -114,14 +138,17 @@ export async function spawnE2eApp(options: SpawnE2eAppOptions): Promise<SpawnedE
       stdout: 'pipe',
       stderr: 'pipe',
     });
+  const termGraceMs = options.termGraceMs ?? TERM_GRACE_MS;
+  // On the monotonic clock: counted in polls, every probe an app wedged mid-boot held for its
+  // whole `READY_PROBE_MS` stretched a 90 s deadline to 450 s, past any hook derived from it.
   const ready = async (child: ReturnType<typeof spawnApp>, tail: () => string): Promise<void> => {
-    for (let waited = 0; waited < deadline; waited += POLL_MS) {
+    const until = performance.now() + deadline;
+    while (performance.now() < until) {
       if (child.exitCode !== null) break;
       if (await answersOk(`${base}/readyz`)) return;
       await Bun.sleep(POLL_MS);
     }
-    child.kill();
-    await child.exited;
+    await end(child, termGraceMs);
     throw refuse(`${command.join(' ')} never answered ${base}/readyz`, tail());
   };
 
@@ -133,8 +160,7 @@ export async function spawnE2eApp(options: SpawnE2eAppOptions): Promise<SpawnedE
   const stop = async (): Promise<void> => {
     if (stopped) return;
     stopped = true;
-    child.kill();
-    await child.exited;
+    await end(child, termGraceMs);
   };
   try {
     await ready(child, tail);
@@ -156,8 +182,7 @@ export async function spawnE2eApp(options: SpawnE2eAppOptions): Promise<SpawnedE
       );
       // The same port and the same state directory — a deploy, not a second app: a tab already
       // open on `base` sees the new build on its next request, and the data it wrote is still there.
-      child.kill();
-      await child.exited;
+      await end(child, termGraceMs);
       child = spawnApp(next);
       tail = drainTail(child.stdout, child.stderr);
       await ready(child, tail);
@@ -165,6 +190,22 @@ export async function spawnE2eApp(options: SpawnE2eAppOptions): Promise<SpawnedE
   };
 }
 
+const within = (ms: number, work: Promise<unknown>): Promise<unknown> =>
+  Promise.race([work, Bun.sleep(ms)]);
+
+/** SIGTERM, the grace, then SIGKILL: bounded at `termGraceMs + KILL_GRACE_MS`, never forever. */
+async function end(child: Bun.Subprocess, termGraceMs: number): Promise<void> {
+  child.kill();
+  const exited =
+    (await within(
+      termGraceMs,
+      child.exited.then(() => true),
+    )) === true;
+  if (exited) return;
+  child.kill('SIGKILL');
+  await within(KILL_GRACE_MS, child.exited);
+}
+
 const TAIL_CHARS = 16_000;
 
 /** Read both streams to their end in the background; answer the last `TAIL_CHARS` of either. */

package/src/errors.ts

@@ -6,10 +6,9 @@ import {
   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';
+
+// `X_TEST_REGISTRY_LEAK` is declared below, in this registry; its message lives beside it.
+export { RegistryLeakError } from './registry-leak-error';
 
 export const TESTING_ERROR_CODES = [
   'X_TEST_NETWORK_SEALED',
@@ -48,6 +47,7 @@ export const TESTING_ERROR_CODES = [
   'X_TEST_OPENAPI_EXPECTED',
   'X_TEST_NUMBER_EXPECTED',
   'X_TEST_ISLAND_STATE_UNKNOWN',
+  'X_TEST_APP_NOT_BOOTED',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -87,6 +87,7 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_TEST_OPENAPI_EXPECTED: 'a matcher expected an OpenAPI document and got something else',
   X_TEST_NUMBER_EXPECTED: 'a matcher expected a finite number and got something else',
   X_TEST_ISLAND_STATE_UNKNOWN: 'an island state manifest declares no state with that id',
+  X_TEST_APP_NOT_BOOTED: 'describeApp handle read before boot',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -105,15 +106,29 @@ registerErrorCodes(
 // answered 404, host included, on every error it has ever thrown; restating the replacement here
 // would be the same constant in eight places waiting to drift again.
 
-/** A test reached the network without a mock or an allowlist entry. Always a bug, never a flake. */
+/**
+ * A test reached the network without a mock or an allowlist entry. Always a bug, never a flake.
+ * `transport` picks the repair: a `fetch` is mocked, a socket (`WebSocket`, `Bun.connect`) has no
+ * mock — the code under test takes its transport as a parameter, and the test hands one in.
+ */
 export class NetworkSealedError extends UltimateError {
-  constructor(input: { url: string; method: string; allowed: readonly string[] }) {
+  constructor(input: {
+    url: string;
+    method: string;
+    allowed: readonly string[];
+    transport?: 'fetch' | 'socket' | undefined;
+  }) {
+    const allowCall = `allowHost('${hostOf(input.url)}')`;
+    const allow = `${allowCall} if it must be real`;
     super({
       code: 'X_TEST_NETWORK_SEALED',
       cause: `${input.method} ${input.url} was not mocked (allowed hosts: ${
         input.allowed.length > 0 ? input.allowed.join(', ') : 'none'
       })`,
-      fix: `mockFetch('${input.url}', () => new Response('{}')) — or allowHost('${hostOf(input.url)}') if it must be real`,
+      fix:
+        input.transport === 'socket'
+          ? `${allowCall}   # only if it must be real — otherwise inject the transport: pass the code under test its \`connect\`/\`client\` option, or dial a Bun.listen server on 127.0.0.1 (loopback is never sealed)`
+          : `mockFetch('${input.url}', () => new Response('{}')) — or ${allow}`,
     });
   }
 }
@@ -135,7 +150,18 @@ export class NondeterministicError extends UltimateError {
     super({
       code: 'X_TEST_NONDETERMINISTIC',
       cause: `${input.what} produced "${input.first}" then "${input.second}"`,
-      fix: 'wrap the test in frozenClock() / seededRandom(), or remove the wall-clock read',
+      fix: "assertDeterministic('…', () => { installDeterminism(); return body(); })",
+    });
+  }
+}
+
+/** `describeApp`'s `app()` read while the block was still being registered, before `beforeAll`. */
+export class AppNotBootedError extends UltimateError {
+  constructor(input: { suite: string }) {
+    super({
+      code: 'X_TEST_APP_NOT_BOOTED',
+      cause: `describeApp('${input.suite}') — app() was called while the describe block was being registered, before its beforeAll booted the app`,
+      fix: "test('…', () => { const handle = app(); })",
     });
   }
 }
@@ -346,64 +372,6 @@ 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(' ')}`,
-    });
-  }
-}
-
 /** Neither path is controlled by the framework: both arrive from the test's own call. */
 const ISLAND_PLACEHOLDER = '<the island path the cause names>';
 

package/src/factories.ts

@@ -6,6 +6,7 @@
 // caller composes, an association is a column whose value comes from another factory built with
 // the SAME strategy — `build()` leaves the parent in memory, `create()` writes it.
 
+import { fnv1a } from '@ultimat3/core';
 import { seededRandom, seededUuid } from './determinism';
 import { FactoryTraitUnknownError } from './errors';
 import { persistRow } from './factory-persist';
@@ -91,15 +92,12 @@ export interface Factory<TRow, TTrait extends string = string> {
 
 /**
  * Two factories with the same seed emit the same uuids, so a default of `1` everywhere gave a user
- * and a post the same id — rows that only look related. FNV-1a over the table name keeps every
- * table on its own stream while staying a pure function of the schema, so the ids are still
+ * and a post the same id — rows that only look related. Core's FNV-1a over the table name keeps
+ * every table on its own stream while staying a pure function of the schema, so the ids are still
  * identical run to run and machine to machine.
  */
 export function seedFor(table: string): number {
-  let hash = 0x811c9dc5;
-  for (let i = 0; i < table.length; i += 1) {
-    hash = Math.imul(hash ^ table.charCodeAt(i), 0x01000193) >>> 0;
-  }
+  const hash = fnv1a(table);
   return hash === 0 ? 1 : hash;
 }
 

package/src/file-boundary.ts

@@ -119,13 +119,8 @@ export function restoreGlobals(snapshot: Baseline, host: object = globalThis): r
   return touched;
 }
 
-/** Called by the leak guard as each test file loads. The first call only takes the baseline. */
-export function runFileBoundary(): void {
-  if (baseline === undefined) {
-    baseline = captureGlobals();
-    envBaseline = { ...process.env };
-    return;
-  }
+/** Every `onFileBoundary` hook, in order — also run once after the run's last file. */
+export function runBoundaryHooks(): void {
   for (const hook of hooks) {
     try {
       hook();
@@ -133,6 +128,16 @@ export function runFileBoundary(): void {
       // A hook that throws (an island's own disposer) must not stop the rest of the reset.
     }
   }
+}
+
+/** Called by the leak guard as each test file loads. The first call only takes the baseline. */
+export function runFileBoundary(): void {
+  if (baseline === undefined) {
+    baseline = captureGlobals();
+    envBaseline = { ...process.env };
+    return;
+  }
+  runBoundaryHooks();
   restoreGlobals(baseline);
   if (envBaseline !== undefined) restoreEnv(envBaseline);
 }

package/src/fixture-clock.ts

@@ -33,7 +33,7 @@ export interface TestClock {
  * 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> {
+export async function testClock(): Promise<TestClock> {
   const { toMs } = await import('@ultimat3/time');
   const captured = captureDeterminism();
   return {