@ultimat3/testing 24.0.0 → 25.1.0

package/src/framework-fixtures.ts

@@ -2,13 +2,13 @@
 // `actorFor`, …). Called by the preload, which is why an app never writes
 // `defineFixtures({ clock })` and why two apps cannot disagree about what `clock` means.
 
-import { createTestClock } from './fixture-clock';
+import { testClock } from './fixture-clock';
 import { DRIVER_FIXTURE_NAMES, driverFixtures } from './fixture-drivers';
-import { createRunJobs } from './fixture-jobs';
-import { createTestMail } from './fixture-mail';
-import { createTestNetwork } from './fixture-network';
-import { createTestStatements } from './fixture-statements';
-import { createSubscribeDriver } from './fixture-subscribe';
+import { testJobs } from './fixture-jobs';
+import { testMail } from './fixture-mail';
+import { testNetwork } from './fixture-network';
+import { testStatements } from './fixture-statements';
+import { subscribeDriver } from './fixture-subscribe';
 import { defineFixtures } from './fixtures';
 
 /**
@@ -24,7 +24,7 @@ export const FRAMEWORK_FIXTURE_NAMES = [
   'runJobs',
   'statements',
   // Moved here from `DRIVER_FIXTURE_NAMES` on 2026-08-20: the driver it was waiting for is
-  // `createSubscribeDriver()`, and the framework can build one — a whole `sync` node in this
+  // `subscribeDriver()`, and the framework can build one — a whole `sync` node in this
   // process, over the change source `@ultimat3/entity`'s `setRowObserver` gives it. The four left
   // in that list all need something the framework genuinely cannot bundle: a browser, or a
   // second build.
@@ -48,14 +48,14 @@ export const ALL_FIXTURE_NAMES: readonly string[] = [
 export function registerFrameworkFixtures(): void {
   defineFixtures({
     ...driverFixtures(),
-    clock: createTestClock,
-    mail: createTestMail,
-    network: createTestNetwork,
-    runJobs: createRunJobs,
-    statements: createTestStatements,
+    clock: testClock,
+    mail: testMail,
+    network: testNetwork,
+    runJobs: testJobs,
+    statements: testStatements,
     // After the spread, so it REPLACES the `unavailableFixture('subscribe')` declaration above it —
     // `defineFixtures` merges and the last registration wins, which is the same seam an app's own
     // driver uses.
-    subscribe: async () => (await createSubscribeDriver()).subscribe,
+    subscribe: async () => (await subscribeDriver()).subscribe,
   });
 }

package/src/index.ts

@@ -37,9 +37,15 @@ export { budgetStoreConformance } from './budget-store-conformance';
 export type { E2eBrowser, OpenE2eBrowserOptions } from './cdp-browser';
 export {
   DEFAULT_CDP_TIMEOUT_MS,
+  E2E_BROWSER_CLOSE_MS,
+  E2E_BROWSER_OPEN_MS,
+  E2E_GOTO_MS,
+  E2E_TAB_OPEN_MS,
   openE2eBrowser,
   openE2eBrowserIfAvailable,
 } from './cdp-browser';
+export type { E2eBrowserLease, RunEndHook } from './cdp-browser-lease';
+export { closeE2eBrowsersAtRunEnd, leaseE2eBrowser } from './cdp-browser-lease';
 export type {
   CdpConnection,
   CdpConnectionOptions,
@@ -71,6 +77,7 @@ export {
   CONTAINER_CHROME_ARGS,
   findChrome,
   LAUNCH_ATTEMPTS,
+  LAUNCH_BUDGET_MS,
   LAUNCH_TIMEOUT_MS,
   launchChrome,
   launchFoundChrome,
@@ -89,7 +96,6 @@ export {
   captureDeterminism,
   DEFAULT_NOW,
   DEFAULT_SEED,
-  frozenClock,
   frozenNow,
   installDeterminism,
   isDeterminismInstalled,
@@ -98,9 +104,10 @@ export {
   seededRandom,
   seededUuid,
   setFrozenClock,
+  withFrozenClock,
 } from './determinism';
 export type { E2eApp, E2eAppMode, StartE2eAppOptions } from './e2e-app';
-export { startE2eApp } from './e2e-app';
+export { E2E_APP_START_MS, E2E_APP_STOP_MS, startE2eApp } from './e2e-app';
 export { E2E_ROOT_ENV, e2eApp, e2eBaseUrl, e2eBrowser } from './e2e-browser-handle';
 export type { E2eDriverOptions } from './e2e-driver';
 export { e2eFixtures, installE2eDriver } from './e2e-driver';
@@ -157,7 +164,7 @@ export { clearPersister, persisterInstalled, usePersister } from './factory-pers
 export type { EntityRegistry, FactoryRegistry } from './factory-registry';
 export { factoriesFor } from './factory-registry';
 export type { TestClock, TestDuration } from './fixture-clock';
-export { createTestClock } from './fixture-clock';
+export { testClock } from './fixture-clock';
 export type {
   DriverFixtureName,
   DriverFixtures,
@@ -190,15 +197,15 @@ export type {
   RunJobsOptions,
   StepTally,
 } from './fixture-jobs';
-export { createRunJobs } from './fixture-jobs';
+export { testJobs } from './fixture-jobs';
 export type { MailRef, TestMail } from './fixture-mail';
-export { createTestMail } from './fixture-mail';
+export { testMail } from './fixture-mail';
 export type { TestNetwork } from './fixture-network';
-export { createTestNetwork } from './fixture-network';
+export { testNetwork } from './fixture-network';
 export type { ObservedStatement, StatementShape, TestStatements } from './fixture-statements';
-export { createTestStatements } from './fixture-statements';
+export { testStatements } from './fixture-statements';
 export type { SubscribeDriver } from './fixture-subscribe';
-export { createSubscribeDriver } from './fixture-subscribe';
+export { subscribeDriver } from './fixture-subscribe';
 export { fixtureTest as test } from './fixtures';
 export {
   ALL_FIXTURE_NAMES,
@@ -284,7 +291,7 @@ export {
 export { ISOLATED_ENV, releasePluginsAfterIsolatedFile } from './isolated-plugins';
 export { jobDriverConformance } from './job-driver-conformance';
 export type { LiveConnection, LiveNodeHandle, LiveNodeOptions } from './live-node';
-export { createLiveNode } from './live-node';
+export { liveNode } from './live-node';
 // The store a mutator's `local()` half writes into under test — the Map every app hand-rolled.
 export type { LocalRows, MemoryLocalTx } from './local-tx';
 export { memoryLocalTx } from './local-tx';
@@ -335,11 +342,11 @@ export type { SqlRunner, TemplateDbConfig, WorkerDatabase } from './template-db'
 export {
   acquireWorkerDatabase,
   cloneSql,
-  createTemplateSql,
   DEFAULT_TEMPLATE,
   databaseNameFor,
   dropSql,
   lockSql,
+  templateSql,
   unlockSql,
   urlFor,
   workerId,

package/src/island-dom.ts

@@ -199,9 +199,24 @@ export class FakeClassList {
   }
 }
 
+/** One `addEventListener` call, alive until its own `removeEventListener`. */
+interface Registration {
+  readonly fn: (event: unknown) => void;
+  removed: boolean;
+}
+
 export class FakeElement extends FakeNode {
   readonly attributes = new Map<string, string>();
-  readonly listeners = new Map<string, (event: unknown) => void>();
+  /**
+   * EVERY listener per type, in the order added, deduplicated by identity — the DOM's own rule. One
+   * per type was a double that lost listeners: `@ultimat3/ui`'s Menu closes on an Escape it
+   * registers on `document`, and its focus trap's keydown, registered next, replaced it.
+   *
+   * A REGISTRATION per add, not the bare function, so a dispatch can tell "removed before its
+   * turn" (skipped, as a browser skips it) from "removed and added again" (a new registration the
+   * running dispatch never saw, so also skipped) — a `Set` of functions answers both as present.
+   */
+  readonly #listeners = new Map<string, Map<(event: unknown) => void, Registration>>();
   /** Plain object, so `delete el.dataset.theme` behaves as the DOM's `DOMStringMap` does. */
   readonly dataset: Record<string, string> = {};
   readonly classList: FakeClassList = new FakeClassList(this);
@@ -246,10 +261,34 @@ export class FakeElement extends FakeNode {
     else this.attributes.delete(name);
   }
   addEventListener(name: string, fn: (event: unknown) => void): void {
-    this.listeners.set(name, fn);
-  }
-  removeEventListener(name: string): void {
-    this.listeners.delete(name);
+    let held = this.#listeners.get(name);
+    if (held === undefined) {
+      held = new Map();
+      this.#listeners.set(name, held);
+    }
+    if (!held.has(fn)) held.set(fn, { fn, removed: false });
+  }
+  /** By IDENTITY: a different function — even one that does the same thing — removes nothing. */
+  removeEventListener(name: string, fn: (event: unknown) => void): void {
+    const held = this.#listeners.get(name);
+    const registration = held?.get(fn);
+    if (held === undefined || registration === undefined) return;
+    registration.removed = true;
+    held.delete(fn);
+    if (held.size === 0) this.#listeners.delete(name);
+  }
+  /** Every listener of `name`, as one call — `undefined` when there is none to run. */
+  listenerFor(name: string): ((event: unknown) => void) | undefined {
+    const held = this.#listeners.get(name);
+    if (held === undefined || held.size === 0) return undefined;
+    // The registrations as of NOW, for the DOM's rule: one added during the dispatch waits for the
+    // next, and one removed before its turn does not run.
+    const snapshot = [...held.values()];
+    return (event: unknown): void => {
+      for (const registration of snapshot) {
+        if (!registration.removed) registration.fn(event);
+      }
+    };
   }
   override cloneNode(deep?: boolean): FakeElement {
     const copy = new FakeElement(this.tagName);
@@ -295,7 +334,7 @@ export class FakeElement extends FakeNode {
       if (options.left !== undefined) this.scrollLeft = options.left;
       if (options.top !== undefined) this.scrollTop = options.top;
     }
-    this.listeners.get('scroll')?.({ currentTarget: this, target: this });
+    this.listenerFor('scroll')?.({ currentTarget: this, target: this });
   }
   /**
    * A compound of tag, `#id`, `.class`, `[attr]` and `[attr="value"]`, joined by the descendant
@@ -414,7 +453,8 @@ export function createIslandDocument(): IslandDocument {
     // reaches them through the surface `MountedIsland` already exposes.
     addEventListener: (name: string, fn: (event: unknown) => void): void =>
       documentElement.addEventListener(name, fn),
-    removeEventListener: (name: string): void => documentElement.removeEventListener(name),
+    removeEventListener: (name: string, fn: (event: unknown) => void): void =>
+      documentElement.removeEventListener(name, fn),
   };
   return {
     documentElement,
@@ -434,7 +474,7 @@ export function createIslandDocument(): IslandDocument {
   };
 }
 
-/** The delegated handler Solid parks on the node as `$$click`, or a listener it attached with
+/** The delegated handler Solid parks on the node as `$$click`, or EVERY listener attached with
  *  `addEventListener` — a compiled island uses one or the other and a driver must accept both. */
 export function handlerFor(
   element: FakeElement,
@@ -442,5 +482,5 @@ export function handlerFor(
 ): ((event: unknown) => void) | undefined {
   const delegated = (element as unknown as Record<string, unknown>)[`$$${type}`];
   if (typeof delegated === 'function') return delegated as (event: unknown) => void;
-  return element.listeners.get(type);
+  return element.listenerFor(type);
 }

package/src/island-globals.ts

@@ -0,0 +1,73 @@
+// The process globals the island fixture installs, as LAYERS over one snapshot of the real ones.
+// Each mount used to save what it found and restore that on dispose — right only newest-first: a
+// worker disposing A then B had B "restore" A's fake `document`/`Element` for every later file.
+
+/** One mount's globals, newest last. */
+const layers: Readonly<Record<string, unknown>>[] = [];
+
+/**
+ * The REAL descriptor of every key any live layer installs, taken the first time a layer installs
+ * it while no other live layer holds it — so 0→1 for each key — and put back only when the last
+ * layer goes (1→0). `undefined` is "no such global", which is restored as a delete.
+ *
+ * DESCRIPTORS, not values: a saved value cannot tell "no such global" from "a global holding
+ * `undefined`", and it cannot put an accessor back as an accessor.
+ */
+const real = new Map<string, PropertyDescriptor | undefined>();
+
+const host = globalThis as unknown as Record<string, unknown>;
+
+const putBack = (key: string, descriptor: PropertyDescriptor | undefined): void => {
+  if (descriptor === undefined) delete host[key];
+  else Object.defineProperty(host, key, descriptor);
+};
+
+/**
+ * The process as the remaining layers say it should be: each key holds the NEWEST live layer's
+ * value, and a key no live layer names is real again. Assignment for a layer's value, for
+ * `installGlobals`' reason — a global with a setter is meant to see the write.
+ */
+function settle(): void {
+  for (const [key, descriptor] of real) {
+    const owner = layers.findLast((layer) => Object.hasOwn(layer, key));
+    if (owner !== undefined) {
+      host[key] = owner[key];
+      continue;
+    }
+    putBack(key, descriptor);
+    real.delete(key);
+  }
+}
+
+/**
+ * Install `values` over the process, answering the undo. All-or-nothing: an assignment that throws
+ * — a getter-only own global among the caller's `globals` — settles the process back before it
+ * rethrows, or the fake `document` installed ahead of it would stay for the rest of the run.
+ *
+ * The undo is idempotent and ORDER-FREE: it removes this layer and settles, so whichever mount
+ * goes last hands the process the real globals, and a mount disposed while a newer one lives
+ * leaves the newer one's in place.
+ */
+export function installGlobals(values: Readonly<Record<string, unknown>>): () => void {
+  for (const key of Object.keys(values)) {
+    if (!real.has(key)) real.set(key, Object.getOwnPropertyDescriptor(host, key));
+  }
+  const layer = { ...values };
+  layers.push(layer);
+  let removed = false;
+  const remove = (): void => {
+    if (removed) return;
+    removed = true;
+    layers.splice(layers.indexOf(layer), 1);
+    settle();
+  };
+  try {
+    // Assignment, not `defineProperty`: `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) {
+    remove();
+    throw error;
+  }
+  return remove;
+}

package/src/island-scratch.ts

@@ -1,14 +1,71 @@
 // The island fixture's scratch directories: one per mount, created when the mount needs it and
 // removed when the mount ends. A per-PROCESS directory left one behind per `bun test` run, because
-// `process.on('exit')` never fires under `bun test` (Bun 1.4.0, measured) — 5,000+ in `/tmp`.
+// `process.on('exit')` never fires under `bun test` (Bun 1.4.0, measured) — 5,000+ in `/tmp`. A
+// KILLED process reaches no cleanup at all, so each directory carries its owner's pid and the next
+// process sweeps a dead owner's.
 
-import { mkdtempSync, rmSync } from 'node:fs';
+// why: Bun has no directory API — a scratch DIRECTORY is made, listed, aged and removed, synchronously
+import { mkdtempSync, readdirSync, rmSync, statSync } from 'node:fs';
 // why: Bun exposes no tmpdir(), so only node:os answers the platform temp root.
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 const live = new Set<string>();
 let exitHooked = false;
+let swept = false;
+
+const PREFIX = 'ultimate-island-';
+/** `ultimate-island-<pid>-<mkdtemp's six>` — this module's own spelling since 2026-10-06. */
+const OWNED = /^ultimate-island-(\d+)-[A-Za-z0-9]{6}$/;
+/** The spelling before it, with no owner to ask: swept once it is a day old. */
+const UNOWNED = /^ultimate-island-[A-Za-z0-9]{6}$/;
+const UNOWNED_AGE_MS = 24 * 60 * 60 * 1000;
+
+/** `kill(pid, 0)` delivers nothing and answers whether the pid exists; EPERM is alive. */
+const pidAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as { code?: unknown }).code === 'EPERM';
+  }
+};
+
+/**
+ * Remove every island directory under `root` whose owning process is gone — the gate's step
+ * deadline SIGKILLs a stalled `bun test`, and nothing in a killed process runs. Answers what it
+ * removed. Best-effort and silent: a directory another sweeper removed first, or one this user
+ * cannot read, is simply not this process's to report.
+ */
+export function sweepDeadScratchDirs(
+  root: string,
+  alive: (pid: number) => boolean,
+  now: number,
+): readonly string[] {
+  const removed: string[] = [];
+  let names: readonly string[];
+  try {
+    names = readdirSync(root).filter((name) => name.startsWith(PREFIX));
+  } catch {
+    return removed;
+  }
+  for (const name of names) {
+    const path = join(root, name);
+    try {
+      const owner = OWNED.exec(name)?.[1];
+      const dead =
+        owner !== undefined
+          ? !alive(Number(owner))
+          : UNOWNED.test(name) && now - statSync(path).mtimeMs > UNOWNED_AGE_MS;
+      if (!dead) continue;
+      rmSync(path, { recursive: true, force: true });
+      removed.push(path);
+    } catch {
+      // Gone already, or not ours to remove.
+    }
+  }
+  return removed;
+}
 
 /**
  * A fresh directory for one mount. Fresh, not shared: a module is cached by PATH, so two mounts
@@ -18,7 +75,14 @@ let exitHooked = false;
  * under `bun test` the file boundary and the run's `afterAll` dispose every mount instead.
  */
 export function createScratchDir(): string {
-  const dir = mkdtempSync(join(tmpdir(), 'ultimate-island-'));
+  const dir = mkdtempSync(join(tmpdir(), `${PREFIX}${String(process.pid)}-`));
+  // Once per process, at its first mount: the cost is one read of the temp dir. "Now" is the new
+  // directory's own mtime — the FILESYSTEM's clock, the one the swept mtimes were written by —
+  // never `Date.now()`, which a test process has frozen at whatever instant the suite chose.
+  if (!swept) {
+    swept = true;
+    sweepDeadScratchDirs(tmpdir(), pidAlive, statSync(dir).mtimeMs);
+  }
   live.add(dir);
   if (!exitHooked) {
     exitHooked = true;

package/src/island-state-errors.ts

@@ -135,6 +135,22 @@ export class IslandStateStubInvalidError extends UltimateError {
   }
 }
 
+/**
+ * A `records` stub whose rows are not the envelope's shape — record type -> record key -> row
+ * object, `removed` a list of keys per type. The client decodes that shape behind the header and
+ * refuses anything else (`X_CLIENT_RECORD_ENVELOPE_INVALID`), so the picture would be of that
+ * refusal. Its own class beside the one above, sharing one code: a stub that cannot answer.
+ */
+export class IslandStateRecordsInvalidError extends UltimateError {
+  constructor(input: { readonly island: string; readonly path: string; readonly reason: string }) {
+    super({
+      code: 'X_TEST_ISLAND_STATE_STUB_INVALID',
+      cause: `${input.path} ${input.reason}, so the page store would refuse the envelope rather than adopt it`,
+      fix: `respond: { kind: 'records', data: [{ id: 'r1' }], records: { runs: { 'r1': { id: 'r1' } } } } — in ${at(input.island)}`,
+    });
+  }
+}
+
 /**
  * A states file that imports the component it describes. The whole design rests on this file being
  * readable from Bun with no browser and no bundle — the command must know the complete expected

package/src/island-states.ts

@@ -25,8 +25,31 @@ export const DEFAULT_ISLAND_VIEWPORT: IslandViewport = { width: 1280, height: 80
  */
 export const ISLAND_SHOT_TIME_ZONE = 'UTC';
 
+/**
+ * The rows a `records` stub hands the page store: record type -> record key -> row — core's
+ * `RecordEnvelope['records']`, restated structurally because this file imports nothing.
+ */
+export type IslandStubRecords = Readonly<
+  Record<string, Readonly<Record<string, Readonly<Record<string, unknown>>>>>
+>;
+
+/**
+ * What a stubbed request answers. `json` is a bare body. `records` is what a query declaring an
+ * entity's `rows:` answers on the wire — the envelope `{ data, records, removed? }` behind
+ * `x-ultimate-records: 1` — so the island's page store adopts the rows exactly as it would from
+ * the server; a `json` stub of the same body is read as bare rows and adopts nothing (#683).
+ */
 export type IslandStubResponse =
   | { readonly kind: 'json'; readonly status?: number; readonly body: unknown }
+  | {
+      readonly kind: 'records';
+      readonly status?: number;
+      /** The read's own answer — what the island's `await` resolves to. */
+      readonly data: unknown;
+      readonly records: IslandStubRecords;
+      /** Record keys the store drops, by record type. */
+      readonly removed?: Readonly<Record<string, readonly string[]>>;
+    }
   | { readonly kind: 'pending' }
   | { readonly kind: 'offline' };
 

package/src/live-node.ts

@@ -78,7 +78,7 @@ export interface LiveNodeOptions {
   /** Pins the reconnect epoch, so a test can force a refetch by changing it. */
   readonly epoch?: string;
   // No `onMutate`: the socket carries no writes any more (plan 101, decision 2) — a mutation goes
-  // over HTTP as an action, and `createSyncNode` takes no mutation hook to forward.
+  // over HTTP as an action, and `syncNode` takes no mutation hook to forward.
 }
 
 export interface LiveNodeHandle {
@@ -115,7 +115,7 @@ const ACTORS = new Map<string, Actor | null>();
 
 let sequence = 0;
 
-export async function createLiveNode(options: LiveNodeOptions = {}): Promise<LiveNodeHandle> {
+export async function liveNode(options: LiveNodeOptions = {}): Promise<LiveNodeHandle> {
   const core = await import('@ultimat3/core');
   const query = await import('@ultimat3/query');
   const realtime = await import('@ultimat3/realtime/server');
@@ -126,7 +126,7 @@ export async function createLiveNode(options: LiveNodeOptions = {}): Promise<Liv
   const hub = new realtime.ChannelHub({ transport, sockets });
   const registry = new realtime.LiveQueryRegistry({ source: new realtime.RingChangeBuffer() });
 
-  const ctx = core.createContext({ role: 'sync', buildId });
+  const ctx = core.ctxOf({ role: 'sync', buildId });
   let live = 0;
   for (const target of query.listQueries()) {
     if (!target.isLive) continue;
@@ -143,7 +143,7 @@ export async function createLiveNode(options: LiveNodeOptions = {}): Promise<Liv
   // app that declared nothing. Said here, where the count is known.
   if (live === 0) throw liveNodeUnavailable();
 
-  const node = realtime.createSyncNode({
+  const node = realtime.syncNode({
     hub,
     registry,
     transport,

package/src/quiet-logs.ts

@@ -11,7 +11,7 @@
 // line collected nothing and failed for an environment variable. The level is therefore pinned at
 // `info` for the one moment core loads, and what the author named decides what is PRINTED.
 //
-// A test that asserts on log output hands `createLogger({ level, writer })` its own writer, or
+// A test that asserts on log output hands `structuredLogger({ level, writer })` its own writer, or
 // installs its own `setLogSink` and restores the previous one. Never `process.stdout`.
 
 import type { LogLevel } from '@ultimat3/core';

package/src/registry-leak-error.ts

@@ -0,0 +1,81 @@
+// Single responsibility: `X_TEST_REGISTRY_LEAK`'s message — which file left which cache tags and
+// tiers registered, the isolating lines to paste, and the `bun test` re-run. The CODE is declared
+// in `errors.ts`, the package's registry, which re-exports this class; the shape it reports is
+// `registry-leak-guard.ts`'s. Split from `errors.ts` at the 500-line ceiling.
+
+import { isFixShellSafe, renderCauseValue, renderFixLiteral, UltimateError } from '@ultimat3/core';
+// Type-only, so the cycle with the guard that throws it is erased at build.
+import type { RegistryLeak } from './registry-leak-guard';
+
+/**
+ * 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>';
+
+/**
+ * Inside double quotes `$`, a backtick and `!` are still live, and `renderFixLiteral` answers double
+ * quotes — so a path carrying one becomes the quoted placeholder in the `bun test` command. Any other
+ * path stays the JSON literal: an ordinary path, or one with a quote JSON escapes, still runs.
+ */
+const DOUBLE_QUOTE_LIVE = /[$`!]/;
+
+const rerunArg = (file: string): string =>
+  isFixShellSafe(file) || !DOUBLE_QUOTE_LIVE.test(file)
+    ? renderFixLiteral(file, FILE_PLACEHOLDER)
+    : `'${FILE_PLACEHOLDER}'`;
+
+/** Every leaked file as `bun test` arguments — one screen, so the fix-shell-arg guard can see it. */
+const rerunFileArgs = (leaks: readonly RegistryLeak[]): string =>
+  leaks.map((leak) => rerunArg(leak.file)).join(' ');
+
+/**
+ * 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[] }) {
+    super({
+      code: 'X_TEST_REGISTRY_LEAK',
+      cause: input.leaks.map(describeLeak).join('; '),
+      fix: `${input.leaks.map(repairFor).join('; ')} — then re-run: bun test ${rerunFileArgs(input.leaks)}`,
+    });
+  }
+}

package/src/registry-leak-guard.ts

@@ -32,7 +32,7 @@ import {
  * "Idiomatic to leave filled" says nothing about a file that calls `clear*()`/`reset*()` and takes
  * a module-scope declaration from every file after it — a module evaluates once per process, so the
  * next file's own `import` is a cache hit that declares nothing. That is what `registry-snapshot.ts`
- * repairs, and it repairs FOUR registries out of the set that has one:
+ * repairs, and it repairs SIX registries out of the set that has one:
  *
  *   | registry | reset export | owner | in the snapshot? |
  *   |---|---|---|---|
@@ -41,8 +41,9 @@ import {
  *   | routes | `clearRoutes` | `@ultimat3/render` | **no** |
  *   | jobs | `resetJobs` | `@ultimat3/jobs` | **no** |
  *   | tasks | `restoreTasks` | `@ultimat3/jobs` | yes (22.7) |
- *   | actions | `resetRegistry` | `@ultimat3/action` | **no** |
- *   | queries | `resetRegistry` | `@ultimat3/query` | **no** |
+ *   | measurement actor | `resetMeasurementActor` | `@ultimat3/core` | yes |
+ *   | actions | `resetActions` | `@ultimat3/action` | **no** |
+ *   | queries | `resetQueries` | `@ultimat3/query` | **no** |
  *   | models / prompts / agents | `resetModels` / `resetPrompts` / `resetAgents` | `@ultimat3/ai` | **no** |
  *   | mails | `resetMails` | `@ultimat3/mail` | **no** |
  *   | entities | `clearRegistry` | `@ultimat3/entity` | no, by decision — `registry-isolation.ts` |