@ultimat3/testing 24.0.0 → 25.0.0

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;
-    await 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();
     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,7 +8,7 @@
 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';
 
@@ -43,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;
@@ -63,6 +86,8 @@ 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;
 }
 
 /**
@@ -70,9 +95,15 @@ export interface SpawnE2eAppOptions {
  * `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' };
 };
 
@@ -107,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());
   };
 
@@ -126,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);
@@ -149,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);
@@ -158,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',
@@ -107,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}`,
     });
   }
 }
@@ -359,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/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 {

package/src/fixture-island.ts

@@ -7,6 +7,7 @@ import { basename, join } from 'node:path';
 import { islandMountMissing, islandNotBuilt } from './errors';
 import { onFileBoundary } from './file-boundary';
 import { createIslandDocument, FakeElement, handlerFor, parseHtml } from './island-dom';
+import { installGlobals } from './island-globals';
 import type { ResizeInput } from './island-observers';
 import { deliverResize } from './island-observers';
 import { createScratchDir, removeScratchDir } from './island-scratch';
@@ -147,40 +148,6 @@ function entryOf(module: unknown, file: string): IslandEntry {
 const modulePathFor = (dir: string, code: string): string =>
   join(dir, `${Bun.SHA256.hash(code, 'hex').slice(0, 16)}.mjs`);
 
-/**
- * DESCRIPTORS, not values, and all-or-nothing.
- *
- * A saved value cannot tell "no such global" from "a global holding `undefined`", so a teardown
- * reading one deletes both — and `key in globalThis` flips behind whoever owned it. It also cannot
- * put an accessor back as an accessor.
- *
- * The rollback is the half with teeth. This runs BEFORE `mountIsland`'s own `try`, so an
- * assignment that throws — a getter-only own global among the caller's `globals` — would leave the
- * fake `document` already installed ahead of it for the whole rest of the process, which is the
- * exact leak the `catch` below exists to prevent.
- */
-function installGlobals(values: Readonly<Record<string, unknown>>): () => void {
-  const host = globalThis as unknown as Record<string, unknown>;
-  const saved = Object.keys(values).map(
-    (key) => [key, Object.getOwnPropertyDescriptor(host, key)] as const,
-  );
-  const restore = (): void => {
-    for (const [key, descriptor] of saved) {
-      if (descriptor === undefined) delete host[key];
-      else Object.defineProperty(host, key, descriptor);
-    }
-  };
-  try {
-    // Assignment, not `defineProperty`: a global with a setter is meant to see the write, and
-    // `Object.assign` over the lot would report the same failure with nothing rolled back.
-    for (const [key, value] of Object.entries(values)) host[key] = value;
-  } catch (error) {
-    restore();
-    throw error;
-  }
-  return restore;
-}
-
 /**
  * The island fixture. Everything it installs is process-global, so the result is `Disposable` and
  * the idiom is `using mounted = await mountIsland(…)` — a mount left installed hands a fake
@@ -194,9 +161,12 @@ function installGlobals(values: Readonly<Record<string, unknown>>): () => void {
  * clears (a listener on `document`, an interval whose callback reads it) was made against that one.
  */
 /**
- * Every mount not yet disposed. A worker runs many files in one global (22.7), so a mount a file
- * forgot to `using` is disposed at the file boundary (`file-boundary.ts`) instead of handing its
- * fake `window`/`document` to every later file.
+ * Every mount not yet disposed — from the moment it installs its globals, not from when `mount`
+ * answers. A worker runs many files in one global (22.7), so a mount a file forgot to `using` is
+ * disposed at the file boundary (`file-boundary.ts`) instead of handing its fake
+ * `window`/`document` to every later file. Registered BEFORE the awaits, because a mount that
+ * never settles — a test that timed out inside an island's `mount` — was otherwise nobody's: its
+ * globals stayed installed and its scratch directory stayed in the temp dir, one per timeout.
  */
 const liveMounts = new Set<() => void>();
 
@@ -244,6 +214,24 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
   const { documentElement, globals, resizeObservers } = createIslandDocument();
   const restore = installGlobals({ ...globals, ...options.globals });
   let dir: string | undefined;
+  let unmount: (() => void) | undefined;
+  let disposed = false;
+  const dispose = (): void => {
+    // Once: `using` and an `afterAll` that also disposes by hand are both real, and Solid's own
+    // disposer is idempotent while an island's `clearInterval` wrapper need not be.
+    if (disposed) return;
+    disposed = true;
+    liveMounts.delete(dispose);
+    try {
+      unmount?.();
+    } finally {
+      // Whatever the disposer did — including throw, which is the test's to see — the process
+      // gets its globals back, or the fake `document` reaches every later file in the run.
+      restore();
+      if (dir !== undefined) removeScratchDir(dir);
+    }
+  };
+  liveMounts.add(dispose);
   try {
     dir = createScratchDir();
     const scratch = dir;
@@ -267,24 +255,16 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
     // island's `mount` resumed AFTER the `restore()` below had taken the fake `document` back out
     // — so it failed with `document is not defined` inside whichever later test happened to be
     // running, with no thread back here.
-    const unmount = disposerOf(await entry.mount(el, options.props));
-    let disposed = false;
-    const dispose = (): void => {
-      // Once: `using` and an `afterAll` that also disposes by hand are both real, and Solid's own
-      // disposer is idempotent while an island's `clearInterval` wrapper need not be.
-      if (disposed) return;
-      disposed = true;
-      liveMounts.delete(dispose);
+    const stop = disposerOf(await entry.mount(el, options.props));
+    if (disposed) {
+      // The boundary took this mount back while `mount` was still running — its test is long
+      // over. What it started is stopped now, and nobody is left to see a throw from it.
       try {
-        unmount?.();
-      } finally {
-        // Whatever the disposer did — including throw, which is the test's to see — the process
-        // gets its globals back, or the fake `document` reaches every later file in the run.
-        restore();
-        removeScratchDir(scratch);
+        stop?.();
+      } catch {
+        // Its `document` is already gone; the stop was best-effort for that reason.
       }
-    };
-    liveMounts.add(dispose);
+    } else unmount = stop;
     const resolve = (target: string | FakeElement | null | undefined): FakeElement | null =>
       typeof target === 'string' ? el.querySelector(target) : (target ?? null);
     return {
@@ -320,8 +300,7 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
   } catch (error) {
     // A mount that throws restores the process before it rethrows: the alternative leaves every
     // later file in the run holding a fake `document`, which fails somewhere with no thread back.
-    restore();
-    if (dir !== undefined) removeScratchDir(dir);
+    dispose();
     throw error;
   }
 }

package/src/fixture-jobs.ts

@@ -6,7 +6,7 @@
 // Nothing here polls or sleeps: a job becomes due only because `clock.advance()` said so.
 
 import type { Actor, Ctx } from '@ultimat3/core';
-import { assert, createContext } from '@ultimat3/core';
+import { assert, ctxOf } from '@ultimat3/core';
 import type {
   AnyJobHandle,
   EnqueueResult,
@@ -108,9 +108,9 @@ const tallyOf = (executions: readonly JobExecution[]): Record<string, StepTally>
   return steps;
 };
 
-export async function createRunJobs(): Promise<RunJobs> {
+export async function testJobs(): Promise<RunJobs> {
   const jobs = await import('@ultimat3/jobs');
-  const driver: JobDriver = jobs.createMemoryDriver();
+  const driver: JobDriver = jobs.memoryJobDriver();
   // Captured before the overwrite: the ambient driver is process-global, so without this the
   // next file to call `send()` enqueues into this test's dead queue instead of sending inline.
   const previous = jobs.jobDriver();
@@ -119,8 +119,8 @@ export async function createRunJobs(): Promise<RunJobs> {
   // answer one test published resumed the next test's waiting run. A fresh bus per fixture, and
   // the process's own handed back with the driver.
   const previousBus = jobs.eventBus();
-  jobs.setEventBus(jobs.createMemoryEventBus());
-  const anonymousWorker = createContext({ role: 'worker' });
+  jobs.setEventBus(jobs.memoryEventBus());
+  const anonymousWorker = ctxOf({ role: 'worker' });
   const renewals = frozenScheduler();
 
   const introspect = (): NonNullable<JobDriver['introspect']> => {
@@ -164,7 +164,7 @@ export async function createRunJobs(): Promise<RunJobs> {
    * row, no shutdown hook — the frozen clock and the test decide when a pass happens.
    */
   const round = async (ctx: Ctx): Promise<readonly JobExecution[]> => {
-    const worker = jobs.createWorker({
+    const worker = jobs.jobWorker({
       driver,
       workerId: WORKER_ID,
       queues: queues(),
@@ -198,7 +198,7 @@ export async function createRunJobs(): Promise<RunJobs> {
     const ctx =
       options.actor === undefined
         ? anonymousWorker
-        : createContext({ role: 'worker', actor: options.actor });
+        : ctxOf({ role: 'worker', actor: options.actor });
     for (let rounds = 0; rounds < MAX_ROUNDS; rounds += 1) {
       const batch = await round(ctx);
       if (batch.length === 0) return { executions: [...history], steps: tallyOf(history) };

package/src/fixture-mail.ts

@@ -21,10 +21,10 @@ export interface TestMail extends Disposable {
 
 const idOf = (mail: MailRef): string => (typeof mail === 'string' ? mail : mail.id);
 
-export async function createTestMail(): Promise<TestMail> {
-  const { createMemoryDriver, driverUnavailable, resetMailDriver, setMailDriver, tryMailDriver } =
+export async function testMail(): Promise<TestMail> {
+  const { memoryMailDriver, driverUnavailable, resetMailDriver, setMailDriver, tryMailDriver } =
     await import('@ultimat3/mail');
-  const memory = createMemoryDriver();
+  const memory = memoryMailDriver();
   const failuresLeft = new Map<string, number>();
   // The ambient driver is process-global; the fixture borrows it for one test and hands it back.
   const previous = tryMailDriver();

package/src/fixture-network.ts

@@ -30,7 +30,7 @@ export interface TestNetwork extends Disposable {
  * no subsystem to import on demand. The test bodies rely on it — `network.offline()` is followed
  * on the next line by the mutation that has to observe it.
  */
-export function createTestNetwork(): TestNetwork {
+export function testNetwork(): TestNetwork {
   // A process that unsealed on purpose (ULTIMATE_TEST_ALLOW_NET=1) still gets a working
   // `offline()`, and gets its unsealed fetch back on disposal rather than keeping ours.
   const sealedBefore = isNetworkSealed();

package/src/fixture-statements.ts

@@ -81,7 +81,7 @@ interface ShapeTally {
  * 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> {
+export async function testStatements(): 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');

package/src/fixture-subscribe.ts

@@ -13,7 +13,7 @@ import type { LiveReplicator } from '@ultimat3/realtime/server';
 import { startLiveReplicator } from '@ultimat3/realtime/server';
 import type { LiveFeed, LiveFeedPatch, LiveTarget } from './fixture-drivers';
 import type { LiveConnection, LiveNodeHandle } from './live-node';
-import { createLiveNode } from './live-node';
+import { liveNode } from './live-node';
 
 interface Row {
   readonly id: string;
@@ -58,9 +58,9 @@ export interface SubscribeDriver {
  * once would each see the other's writes. `bun test` builds a fixture on first use and disposes it
  * with the test, which is exactly the lifetime this needs.
  */
-export async function createSubscribeDriver(): Promise<SubscribeDriver> {
+export async function subscribeDriver(): Promise<SubscribeDriver> {
   const realtime = await import('@ultimat3/realtime');
-  const node = await createLiveNode();
+  const node = await liveNode();
   const replicator = await startLiveReplicator({ registry: node.registry });
   const connections: LiveConnection[] = [];
   let sid = 0;