@ultimat3/testing 22.15.0 → 24.0.0

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/failure-context.ts

@@ -0,0 +1,42 @@
+// What a FAILED test carries beside its own message: under e2e, the spawned app's last log lines.
+// The app's log was shown only when it failed to boot, so a live-path bug — a fanout that dropped a
+// change, a 500 behind a page — failed with a browser assertion and nothing from the server.
+// Held on `globalThis` under one `Symbol.for` key: the e2e preload and a test file may each hold
+// their own copy of this module, as `e2e-browser-handle.ts` already explains.
+
+const KEY = Symbol.for('ultimate.test.failure-context');
+
+/** Bounded twice: a log line can be a megabyte of JSON, and an app can talk for minutes. */
+const TAIL_LINES = 40;
+const TAIL_CHARS = 4_000;
+
+/** Install (or with `undefined`, remove) the source of a failure's context. */
+export function setFailureContext(source: (() => string) | undefined): void {
+  if (source === undefined) Reflect.deleteProperty(globalThis, KEY);
+  else Object.defineProperty(globalThis, KEY, { value: source, configurable: true });
+}
+
+/** The last `TAIL_LINES` lines of `log`, and never more than `TAIL_CHARS` of them. */
+export function appLogTail(log: string): string {
+  const lines = log.trimEnd().split('\n').slice(-TAIL_LINES).join('\n');
+  return lines.length <= TAIL_CHARS ? lines : lines.slice(-TAIL_CHARS);
+}
+
+/**
+ * `error` with the app's log tail appended to its message, when a source is installed and has
+ * anything to say. Only an `Error`'s message is extended — that is what the runner prints under
+ * the failing test — and a thrown non-Error is handed back exactly as it was.
+ */
+export function withFailureContext(error: unknown): unknown {
+  const source = Reflect.get(globalThis, KEY) as (() => string) | undefined;
+  if (source === undefined || !(error instanceof Error)) return error;
+  const tail = appLogTail(source());
+  if (tail === '') return error;
+  const count = tail.split('\n').length;
+  Object.defineProperty(error, 'message', {
+    value: `${error.message}\n\n── the e2e app logged, last ${String(count)} line(s): ──\n${tail}`,
+    configurable: true,
+    writable: true,
+  });
+  return error;
+}

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-island.ts

@@ -3,13 +3,13 @@
 // packages are tier 5, so importing it here would be the reverse of the one declared `cli → testing`
 // edge. A structural seam keeps the direction honest and survives the bundler changing underneath.
 
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
 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 type { ResizeInput } from './island-observers';
 import { deliverResize } from './island-observers';
+import { createScratchDir, removeScratchDir } from './island-scratch';
 
 /** The two fields a mounted island needs from a chunk. Anything else a bundler grows — a CSS
  *  artifact, a source map, a dev/production flag — is invisible here on purpose. */
@@ -139,49 +139,13 @@ function entryOf(module: unknown, file: string): IslandEntry {
   return { mount: mount as IslandEntry['mount'] };
 }
 
-let moduleDir: string | undefined;
-
-/**
- * One directory per process, outside the app under test — so no test leaves a `.mjs` behind. Two
- * properties the module-scope `mkdtempSync` it replaces had neither of:
- *
- * LAZY. This module is on the `.` barrel, so importing `@ultimat3/testing` for `expect` alone
- * created a directory — in every test process in the repo, whether or not it ever mounts anything.
- *
- * REMOVED. `exit` and `rmSync`, because an exit handler runs synchronously and nothing else covers
- * every path: `mountIsland` restores and rethrows on a failed mount, so that run never reaches the
- * `Disposable`, and the directory is per PROCESS while the disposable is per mount.
- */
-function moduleDirPath(): string {
-  const existing = moduleDir;
-  if (existing !== undefined) return existing;
-  const created = mkdtempSync(join(tmpdir(), 'ultimate-island-'));
-  process.on('exit', () => {
-    rmSync(created, { recursive: true, force: true });
-  });
-  moduleDir = created;
-  return created;
-}
-
-/**
- * The scratch root, or `undefined` when nothing has been mounted. Read by the leak test, which
- * asserts both halves of the above from a CHILD process — the only place where "this process
- * created no directory" and "the directory is gone afterwards" are both observable.
- */
-export const islandModuleDir = (): string | undefined => moduleDir;
-
 /**
- * A temp file named by the chunk's own hash, NOT a `data:` URL. The URL form read better and
- * crashed the coverage reporter: `bun test --coverage` panics with `range end index N out of range
- * for slice of length 4096` on `import()` of any `data:` module whose URL exceeds ~4 kB, and an
- * island chunk is 12-55 kB. Measured on Bun 1.4.0, threshold at a URL length of 4032; without
- * `--coverage` the same import is fine, which is why only the per-package CI job ever saw it.
- *
- * The property the URL form was chosen for survives: the name is derived from the bytes, so an
- * edited island is a different module rather than a cache hit on the same path.
+ * A temp FILE named by the chunk's own hash, NOT a `data:` URL: `bun test --coverage` panics on
+ * `import()` of a `data:` module past ~4 kB (Bun 1.4.0) and an island chunk is 12-55 kB. The file
+ * sits in the mount's OWN directory (`island-scratch.ts`), so a mount is a fresh module instance.
  */
-const modulePathFor = (code: string): string =>
-  join(moduleDirPath(), `${Bun.SHA256.hash(code, 'hex').slice(0, 16)}.mjs`);
+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.
@@ -249,6 +213,10 @@ export function disposeLiveIslands(): number {
   return pending.length;
 }
 
+// Registered here, not by each preload: the repo's own preload and an app's both install the leak
+// guard that runs the boundary, and a mount a file forgot is one only this module can see.
+onFileBoundary(disposeLiveIslands);
+
 export async function mountIsland(options: MountIslandOptions): Promise<MountedIsland> {
   // `only`, because this fixture has always KNOWN which island it wants and asked for all of them
   // anyway — `island-bundle.ts` added the option for exactly this caller ("a test that mounts a
@@ -275,14 +243,17 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
 
   const { documentElement, globals, resizeObservers } = createIslandDocument();
   const restore = installGlobals({ ...globals, ...options.globals });
+  let dir: string | undefined;
   try {
+    dir = createScratchDir();
+    const scratch = dir;
     // Beside the entry, under the name its bytes import them by: the same relative resolution a
     // browser does under `/islands/`. Named by their content-addressed URL, so a rewrite is the same
     // bytes at the same name.
     for (const shared of bundle.shared ?? []) {
-      await Bun.write(join(moduleDirPath(), basename(shared.url)), shared.code);
+      await Bun.write(join(scratch, basename(shared.url)), shared.code);
     }
-    const path = modulePathFor(chunk.code);
+    const path = modulePathFor(scratch, chunk.code);
     await Bun.write(path, chunk.code);
     const entry = entryOf(await import(path), chunk.file);
     const el = new FakeElement('div');
@@ -310,6 +281,7 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
         // 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);
       }
     };
     liveMounts.add(dispose);
@@ -349,6 +321,7 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
     // 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);
     throw error;
   }
 }

package/src/fixture-jobs.ts

@@ -5,6 +5,7 @@
 // holding a connection — so the trace this returns is keyed by step name and counts executions.
 // 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 type {
   AnyJobHandle,
@@ -16,6 +17,7 @@ import type {
   StepStatus,
 } from '@ultimat3/jobs';
 import { frozenNow } from './determinism';
+import { frozenScheduler } from './frozen-scheduler';
 
 export interface StepTally {
   /** Times the step body actually ran. A replay from storage does not count. */
@@ -30,18 +32,43 @@ export interface StepTally {
  * about the whole run — a per-drain trace could not express it.
  */
 export interface JobRunTrace {
+  /**
+   * Each run as the worker settled it. `executions[n].result` is what the BODY returned, on a
+   * completed run — `{ skipped: true }` and "did the work" are otherwise one trace.
+   */
   readonly executions: readonly JobExecution[];
   /** `trace.steps['welcome-email'].executions` — the assertion a job test is written around. */
   readonly steps: Readonly<Record<string, StepTally>>;
 }
 
+/** How a test files the row: the half of `handle.as(actor, input)` that reaches the queue. */
+export interface JobEnqueueAs {
+  /**
+   * The ENQUEUER's tenant on the row — the limiter's bucket and the idempotency namespace, so one
+   * key in two tenants is two jobs. Never the tenant the body runs under: that is the job's own
+   * declaration (`tenant: (input) => input.orgId`), read off the input.
+   */
+  readonly tenantId?: string;
+}
+
+/** Who the worker is: what an app wires through `WorkerOptions.context()`. */
+export interface JobDrainAs {
+  /**
+   * The identity the body runs as. Its ORG is replaced by the job's declared tenant, exactly as a
+   * real worker's is (`jobRunActor`) — `tenant: 'none'` strips it. Absent is core's anonymous actor.
+   */
+  readonly actor?: Actor;
+}
+
+export interface RunJobsOptions extends JobEnqueueAs, JobDrainAs {}
+
 /** `AsyncDisposable`: the fixture installs the ambient job driver and restores it after the test. */
 export interface RunJobs extends AsyncDisposable {
   /** Enqueue and drain in one call — the common case. */
-  <I>(handle: JobHandle<I>, input: I): Promise<JobRunTrace>;
-  enqueue<I>(handle: JobHandle<I>, input: I): Promise<EnqueueResult>;
+  <I>(handle: JobHandle<I>, input: I, options?: RunJobsOptions): Promise<JobRunTrace>;
+  enqueue<I>(handle: JobHandle<I>, input: I, options?: JobEnqueueAs): Promise<EnqueueResult>;
   /** Claim and execute everything due at the current instant, until nothing is. */
-  drain(): Promise<JobRunTrace>;
+  drain(options?: JobDrainAs): Promise<JobRunTrace>;
   /** Live jobs — ready, delayed, running or suspended — optionally for one job only. */
   depth(handle?: AnyJobHandle): Promise<number>;
   /** Live jobs claimable right now. `clock.advance()` is what turns delayed into due. */
@@ -52,6 +79,14 @@ export interface RunJobs extends AsyncDisposable {
 const WORKER_ID = 'test-worker';
 const VISIBILITY_TIMEOUT_MS = 30_000;
 const CLAIM_LIMIT = 64;
+/**
+ * Lease and slot renewals, every millisecond of TEST time — on the frozen clock, through
+ * `frozenScheduler`, so any `clock.advance()` renews every running job once and the wall clock
+ * renews nothing. A renewal is how a running body learns its row was cancelled (`x jobs cancel`,
+ * an app's own cancel action): cancel, advance, and the drain settles. The LAPSE side of the lease
+ * reads the same clock, so a renewal can never report a lease lost that `clock.advance()` did not.
+ */
+const RENEW_MS = 1;
 /** A drain that has not settled in this many rounds is a runaway, not a slow queue. */
 const MAX_ROUNDS = 100;
 const LIVE_STATES: ReadonlySet<string> = new Set(['ready', 'delayed', 'running', 'suspended']);
@@ -80,7 +115,13 @@ export async function createRunJobs(): Promise<RunJobs> {
   // next file to call `send()` enqueues into this test's dead queue instead of sending inline.
   const previous = jobs.jobDriver();
   jobs.setJobDriver(driver);
-  const ctx = createContext({ role: 'worker' });
+  // The same for the event bus `step.waitForEvent` reads: it is ambient and it STORES, so an
+  // 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' });
+  const renewals = frozenScheduler();
 
   const introspect = (): NonNullable<JobDriver['introspect']> => {
     const found = driver.introspect;
@@ -92,8 +133,22 @@ export async function createRunJobs(): Promise<RunJobs> {
     return found;
   };
 
+  // Walked by cursor: one `list()` answers a PAGE (`MAX_JOB_PAGE`), and a test that queued more
+  // than a page of jobs must still see every one of them.
   const live = async (name?: string): Promise<readonly JobRecord[]> => {
-    const rows = await introspect().list({ limit: 1000, ...(name === undefined ? {} : { name }) });
+    const rows: JobRecord[] = [];
+    let after: string | undefined;
+    for (;;) {
+      const page = await introspect().list({
+        limit: jobs.MAX_JOB_PAGE,
+        ...(name === undefined ? {} : { name }),
+        ...(after === undefined ? {} : { after }),
+      });
+      rows.push(...page);
+      const last = page[page.length - 1];
+      if (last === undefined || page.length < jobs.MAX_JOB_PAGE) break;
+      after = jobs.jobCursor(last);
+    }
     return rows.filter((record) => LIVE_STATES.has(record.state));
   };
 
@@ -101,32 +156,51 @@ export async function createRunJobs(): Promise<RunJobs> {
     ...new Set([jobs.DEFAULT_QUEUE, ...jobs.registeredJobs().map((handle) => handle.queue)]),
   ];
 
-  const round = async (): Promise<readonly JobExecution[]> => {
-    const claimed = await driver.claim({
+  /**
+   * One pass, through a REAL worker's `tick()`: claim, admission — the in-process limiter and the
+   * fleet slot `job.concurrency` holds, keyed or not — then the run. Calling `executeJob` on what
+   * `claim()` answered skipped admission entirely, so `whenBusy: 'fail'` never refused and
+   * `concurrency: 1` never waited under this fixture. Never `start()`ed: no timer, no registry
+   * 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({
+      driver,
+      workerId: WORKER_ID,
       queues: queues(),
-      limit: CLAIM_LIMIT,
+      // A whole batch per pass, as `claim({ limit })` was: two runs of one key are in flight
+      // together only if one pass claims both.
+      concurrency: CLAIM_LIMIT,
       visibilityTimeoutMs: VISIBILITY_TIMEOUT_MS,
-      workerId: WORKER_ID,
+      heartbeatIntervalMs: RENEW_MS,
+      schedule: renewals.schedule,
+      // A shed run is claimable on the next pass, not after a wait this clock would never reach.
+      pollIntervalMs: 0,
+      drainOnShutdown: false,
+      context: () => ctx,
     });
-    const executions: JobExecution[] = [];
-    for (const job of claimed) {
-      const handle = jobs.getJob(job.name);
-      assert(
-        handle !== undefined,
-        `queue holds job "${job.name}" but nothing registered it`,
-        `import the module that declares job("${job.name}") from the test file — the registry is populated by the import, not by the queue`,
-      );
-      executions.push(await jobs.executeJob({ driver, claimed: job, handle, ctx }));
-    }
+    const executions = await worker.tick();
+    // The worker PARKS a job no module registered — right for a fleet mid-deploy, where the pod
+    // beside it may know the name, and silence in a test that forgot an import.
+    const orphan = executions.find((run) => run.error === `no job registered as "${run.job}"`);
+    assert(
+      orphan === undefined,
+      `queue holds job "${orphan?.job ?? ''}" but nothing registered it`,
+      `import the module that declares job("${orphan?.job ?? ''}") from the test file — the registry is populated by the import, not by the queue`,
+    );
     return executions;
   };
 
   /** Every execution this fixture has driven, because the trace is cumulative. */
   const history: JobExecution[] = [];
 
-  const drain = async (): Promise<JobRunTrace> => {
+  const drain = async (options: JobDrainAs = {}): Promise<JobRunTrace> => {
+    const ctx =
+      options.actor === undefined
+        ? anonymousWorker
+        : createContext({ role: 'worker', actor: options.actor });
     for (let rounds = 0; rounds < MAX_ROUNDS; rounds += 1) {
-      const batch = await round();
+      const batch = await round(ctx);
       if (batch.length === 0) return { executions: [...history], steps: tallyOf(history) };
       history.push(...batch);
     }
@@ -137,18 +211,27 @@ export async function createRunJobs(): Promise<RunJobs> {
     );
   };
 
-  const enqueue = async <I>(handle: JobHandle<I>, input: I): Promise<EnqueueResult> =>
+  const enqueue = async <I>(
+    handle: JobHandle<I>,
+    input: I,
+    options: JobEnqueueAs = {},
+  ): Promise<EnqueueResult> =>
     driver.enqueue({
       name: handle.name,
       queue: handle.queue,
       input,
       idempotencyKey: handle.idempotencyKeyFor(input),
       maxAttempts: handle.retry.attempts,
+      ...(options.tenantId === undefined ? {} : { tenantId: options.tenantId }),
     });
 
-  const enqueueThenDrain = async <I>(handle: JobHandle<I>, input: I): Promise<JobRunTrace> => {
-    await enqueue(handle, input);
-    return drain();
+  const enqueueThenDrain = async <I>(
+    handle: JobHandle<I>,
+    input: I,
+    options: RunJobsOptions = {},
+  ): Promise<JobRunTrace> => {
+    await enqueue(handle, input, options);
+    return drain(options);
   };
 
   return Object.assign(enqueueThenDrain, {
@@ -161,9 +244,15 @@ export async function createRunJobs(): Promise<RunJobs> {
       ).length,
     inFlight: async () => (await live()).filter((record) => record.state === 'running').length,
     [Symbol.asyncDispose]: async (): Promise<void> => {
-      await driver.close?.();
-      if (previous === undefined) jobs.resetJobDriver();
-      else jobs.setJobDriver(previous);
+      // A `finally`: a close that throws must still hand every later file its bus and its driver.
+      try {
+        await driver.close?.();
+      } finally {
+        renewals[Symbol.dispose]();
+        jobs.setEventBus(previousBus);
+        if (previous === undefined) jobs.resetJobDriver();
+        else jobs.setJobDriver(previous);
+      }
     },
   });
 }

package/src/fixtures.ts

@@ -10,13 +10,14 @@
 
 import { test as bunTest } from 'bun:test';
 import { fixtureUnknown } from './errors';
+import { withFailureContext } from './failure-context';
 import type { TestClock } from './fixture-clock';
 import type { SignIn, Subscribe, TestBudget, TestDeploy } from './fixture-drivers';
 import type { RunJobs } from './fixture-jobs';
 import type { TestMail } from './fixture-mail';
 import type { TestNetwork } from './fixture-network';
 import type { TestStatements } from './fixture-statements';
-import type { PageLike } from './test-types';
+import type { PageLike, TestOptions } from './test-types';
 
 /** Built once per test, on first use. */
 export type FixtureFactory<T = unknown> = () => T | Promise<T>;
@@ -222,7 +223,8 @@ export async function runWithFixtures(body: FixtureRunBody): Promise<void> {
     }
     await body(bag as FixtureBag);
   } catch (error) {
-    failure = { error };
+    // The body's own failure, with the e2e app's log tail when one is running (`failure-context.ts`).
+    failure = { error: withFailureContext(error) };
   }
 
   // Every disposer runs even when an earlier one throws: a fixture that cannot clean up must
@@ -244,7 +246,10 @@ export async function runWithFixtures(body: FixtureRunBody): Promise<void> {
  *
  * Teardown runs in reverse build order whether the body passed or threw: a failing assertion
  * must not be the reason the next file inherits a queue.
+ *
+ * `options.timeoutMs` is the test's own deadline, the same key the six typed helpers take: a
+ * fixture that builds something slow (an island, a browser) is the test that needs one.
  */
-export function fixtureTest(name: string, body: FixtureBody): void {
-  bunTest(name, () => runWithFixtures(body));
+export function fixtureTest(name: string, body: FixtureBody, options?: TestOptions): void {
+  bunTest(name, () => runWithFixtures(body), options?.timeoutMs);
 }

package/src/free-port.ts

@@ -0,0 +1,46 @@
+// One responsibility: a port the e2e app can listen on AND a browser will open. The OS hands out
+// whatever is free in its ephemeral range, and a box whose range starts at 1024 hands out ports
+// Chrome refuses outright — every navigation of the run then fails `net::ERR_UNSAFE_PORT`.
+
+/** What `freePort` needs of a listener: the port the OS gave it, and a way to give it back. */
+export interface PortProbe {
+  readonly port: number;
+  stop(): void;
+}
+
+/**
+ * Chromium's restricted ports (`net/base/port_util.cc`, `kRestrictedPorts`) from 1024 up — the
+ * ones an unprivileged listener can be handed. Below 1024 the OS never answers a `port: 0` ask.
+ */
+export const BROWSER_REFUSED_PORTS: ReadonlySet<number> = new Set([
+  1719, 1720, 1723, 2049, 3659, 4045, 4190, 5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668, 6669,
+  6679, 6697, 10_080,
+]);
+
+/** Listen on a port of the OS's choosing. */
+const listenOnAnyPort = (): PortProbe => {
+  const probe = Bun.serve({ port: 0, fetch: () => new Response() });
+  return { port: probe.port ?? 0, stop: () => void probe.stop(true) };
+};
+
+/**
+ * A port nothing holds right now, asked of the OS and handed to the child — and one a browser will
+ * open. A refused port is KEPT listening while the next is asked for, so the OS cannot answer with
+ * it again: the walk ends after at most one ask per refused port, with no counter and no retry.
+ */
+export const freePort = (listen: () => PortProbe = listenOnAnyPort): number => {
+  const refused: PortProbe[] = [];
+  try {
+    for (;;) {
+      const probe = listen();
+      if (BROWSER_REFUSED_PORTS.has(probe.port)) {
+        refused.push(probe);
+        continue;
+      }
+      probe.stop();
+      return probe.port;
+    }
+  } finally {
+    for (const probe of refused) probe.stop();
+  }
+};

package/src/frozen-scheduler.ts

@@ -0,0 +1,49 @@
+// An interval scheduler on the FROZEN clock: a tick fires when a test moves time past it, never on
+// the wall clock. What the `runJobs` fixture renews its leases and slots on, so a running body
+// hears its cancel at the next `clock.advance()` and no job test pays for a real-time loop.
+
+import type { IntervalScheduler } from '@ultimat3/jobs';
+import { frozenNow, onClockMoved } from './determinism';
+
+interface Armed {
+  readonly tick: () => void;
+  readonly everyMs: number;
+  dueAt: number;
+}
+
+export interface FrozenScheduler extends Disposable {
+  readonly schedule: IntervalScheduler;
+  /** Ticks armed right now. A number that does not fall back to `0` is a renewal nobody stopped. */
+  armed(): number;
+}
+
+/**
+ * One tick per armed renewal per move, however far the clock jumped: a renewal is idempotent, and
+ * firing a three-day advance as 259,200 one-second ticks would be the wall-clock loop again.
+ */
+export function frozenScheduler(): FrozenScheduler {
+  const timers = new Set<Armed>();
+  const stopListening = onClockMoved(() => {
+    const now = frozenNow().getTime();
+    for (const timer of [...timers]) {
+      if (!timers.has(timer) || timer.dueAt > now) continue;
+      timer.dueAt = now + timer.everyMs;
+      timer.tick();
+    }
+  });
+  const schedule: IntervalScheduler = (tick, everyMs) => {
+    const timer: Armed = { tick, everyMs, dueAt: frozenNow().getTime() + everyMs };
+    timers.add(timer);
+    return () => {
+      timers.delete(timer);
+    };
+  };
+  return {
+    schedule,
+    armed: () => timers.size,
+    [Symbol.dispose]: () => {
+      stopListening();
+      timers.clear();
+    },
+  };
+}

package/src/harness.ts

@@ -4,6 +4,7 @@
 
 import { afterAll, beforeAll, describe, test } from 'bun:test';
 import { captureDeterminism, installDeterminism, restoreCapturedDeterminism } from './determinism';
+import { AppNotBootedError } from './errors';
 import {
   allowHost,
   captureNetwork,
@@ -171,7 +172,7 @@ export function describeApp(
       booted = undefined;
     });
     body(() => {
-      if (booted === undefined) throw new ReferenceError('app is not booted yet');
+      if (booted === undefined) throw new AppNotBootedError({ suite: name });
       return booted.handle;
     });
   });