@ultimat3/testing 22.14.0 → 23.0.0

package/src/determinism.ts

@@ -154,6 +154,24 @@ export function restoreCapturedDeterminism(snapshot: DeterminismSnapshot): void
 
 export const isDeterminismInstalled = (): boolean => installed;
 
+/**
+ * Told each time a test MOVES the clock — `advanceClock` and `setFrozenClock`. A frozen clock that
+ * nothing can hear move is one a timer can only ignore: `frozen-scheduler.ts` is the listener, and
+ * it is how the `runJobs` fixture renews a lease when time passes instead of on the wall clock.
+ */
+const clockMoved = new Set<() => void>();
+
+export function onClockMoved(listener: () => void): () => void {
+  clockMoved.add(listener);
+  return () => {
+    clockMoved.delete(listener);
+  };
+}
+
+const announceMove = (): void => {
+  for (const listener of [...clockMoved]) listener();
+};
+
 /** Move the frozen clock forward. The only legal way for time to pass inside a test. */
 export function advanceClock(ms: number): Date {
   // A required parameter with no default, so no `??` and no ratchet can see it — and it writes the
@@ -161,6 +179,7 @@ export function advanceClock(ms: number): Date {
   // process, which no later `advance` and no later `set` undoes. Negative is legal: a test may
   // move the clock backwards.
   frozenAt += finiteOption('advanceClock', 'ms', ms);
+  announceMove();
   return new RealDate(frozenAt);
 }
 
@@ -168,6 +187,7 @@ export const frozenNow = (): Date => new RealDate(frozenAt);
 
 export function setFrozenClock(now: string | number): void {
   frozenAt = instantMs('setFrozenClock', now);
+  announceMove();
 }
 
 /** Run `body` with the clock frozen at `now`, then restore whatever was there before. */

package/src/e2e-app.ts

@@ -12,6 +12,7 @@ import { join } from 'node:path';
 import { finiteCount } from '@ultimat3/core';
 import type { E2eAppMode } from './e2e-spawn';
 import { inherited, refuse, spawnE2eApp, xBin } from './e2e-spawn';
+import { testSealKeyEnv } from './test-seal-key';
 
 export type { E2eAppMode } from './e2e-spawn';
 
@@ -35,6 +36,11 @@ export interface E2eApp {
   readonly base: string;
   /** The throwaway `.x` this app runs on — the one directory a test may inspect or corrupt. */
   readonly stateDir: string;
+  /**
+   * The last of what the app printed, bounded — what a failing e2e test carries in its message
+   * (`failure-context.ts`), so a live-path bug is readable without running `x dev` by hand.
+   */
+  log(): string;
   /** Kill the app and delete its state directory. Idempotent. */
   stop(): Promise<void>;
   /**
@@ -72,7 +78,13 @@ export async function startE2eApp(options: StartE2eAppOptions): Promise<E2eApp>
   // Before the state directory too: an app that cannot name its `x` leaves nothing behind.
   const bin = await xBin(options.root);
   const stateDir = await mkdtemp(join(tmpdir(), 'ultimate-e2e-'));
-  const env: Record<string, string> = { ...options.env, ULTIMATE_STATE_DIR: stateDir };
+  // The app is a server, not a test process: it installs no seal key for itself. The harness hands
+  // down the throwaway one when the app's root has none, so a `.sealed()` column works under e2e.
+  const env: Record<string, string> = {
+    ...testSealKeyEnv({ root: options.root }),
+    ...options.env,
+    ULTIMATE_STATE_DIR: stateDir,
+  };
   const cleanup = (): Promise<void> => rm(stateDir, { recursive: true, force: true });
   try {
     x(bin, ['db', 'reset'], options.root, env);
@@ -93,6 +105,7 @@ export async function startE2eApp(options: StartE2eAppOptions): Promise<E2eApp>
     return {
       base: spawned.base,
       stateDir,
+      log: () => spawned.log(),
       restart: (next) => spawned.restart(next),
       async stop(): Promise<void> {
         await spawned.stop();

package/src/e2e-driver.ts

@@ -6,6 +6,7 @@ import { test as bunTest } from 'bun:test';
 import type { E2eBrowserPage, E2ePageOptions } from './e2e-page';
 import { e2ePage } from './e2e-page';
 import { FixtureUnavailableError } from './errors';
+import { withFailureContext } from './failure-context';
 import { unavailableFixture } from './fixture-drivers';
 import { defineFixtures } from './fixtures';
 import type { E2eBody, E2eFixtures, PageLike } from './test-types';
@@ -97,8 +98,16 @@ export function installE2eDriver(options: E2eDriverOptions): () => void {
     page: () => page,
     ...(newBuild === undefined ? {} : { deploy: () => ({ newBuild }) }),
   });
-  useE2eDriver((name, body: E2eBody) => {
-    bunTest(name, () => body(e2eFixtures(page, options.page, newBuild)));
+  useE2eDriver((name, body: E2eBody, test) => {
+    // Through `withFailureContext`, as `fixtureTest` is: the failing test carries the app's log.
+    const run = async (): Promise<void> => {
+      try {
+        await body(e2eFixtures(page, options.page, newBuild));
+      } catch (error) {
+        throw withFailureContext(error);
+      }
+    };
+    bunTest(name, run, test?.timeoutMs);
   });
   return () => {
     // Both halves, because both were installed. Putting the DECLARATION back — rather than

package/src/e2e-run.ts

@@ -10,6 +10,7 @@ import { e2eBrowser, publishE2eRun, republishE2eBrowser } from './e2e-browser-ha
 import type { E2eDriverOptions } from './e2e-driver';
 import type { E2eBrowserPage } from './e2e-page';
 import { answersWithin } from './e2e-probe';
+import { setFailureContext } from './failure-context';
 
 /** How long a live browser gets to answer `1` before it is declared hung and relaunched. */
 export const PROBE_MS = 5_000;
@@ -54,6 +55,9 @@ export async function startE2eRun(deps: E2eRunDeps): Promise<void> {
   };
   let browser = await openOrStop(app, deps.openBrowser);
   publishE2eRun({ browser, app });
+  // Every test that fails from here on carries the app's log tail: the server's half of a failure
+  // the browser can only report as "the row never arrived".
+  setFailureContext(() => app.log());
   // Installed ONCE, over a page that delegates to whichever browser is current: an `e2eTest` body
   // is bound to its fixtures when the file DEFINES it, so reinstalling on a relaunch would leave
   // every test defined before it driving a closed browser.
@@ -80,6 +84,7 @@ export async function startE2eRun(deps: E2eRunDeps): Promise<void> {
   });
 
   deps.afterAll(async () => {
+    setFailureContext(undefined);
     uninstall();
     browser.close();
     await app.stop();

package/src/e2e-spawn.ts

@@ -45,6 +45,8 @@ const POLL_MS = 250;
 export interface SpawnedE2eApp {
   /** `http://localhost:<port>`, no trailing slash. */
   readonly base: string;
+  /** The last of what the CURRENT process printed, stdout and stderr, bounded. */
+  log(): string;
   /** Kill the process. Idempotent. */
   stop(): Promise<void>;
   /** Kill it and start it again on the SAME port, with `env` added — a deploy. Refused after `stop()`. */
@@ -142,6 +144,7 @@ export async function spawnE2eApp(options: SpawnE2eAppOptions): Promise<SpawnedE
   }
   return {
     base,
+    log: () => tail(),
     stop,
     async restart(next: Readonly<Record<string, string>> = {}): Promise<void> {
       // `stop()` is final. A child respawned here would be one no later `stop()` kills — the flag

package/src/errors.ts

@@ -47,6 +47,7 @@ export const TESTING_ERROR_CODES = [
   'X_TEST_POLICY_EXPECTED',
   'X_TEST_OPENAPI_EXPECTED',
   'X_TEST_NUMBER_EXPECTED',
+  'X_TEST_ISLAND_STATE_UNKNOWN',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -85,6 +86,7 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_TEST_POLICY_EXPECTED: 'a matcher expected a policy and got something else',
   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',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is

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/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, {
@@ -162,6 +245,8 @@ export async function createRunJobs(): Promise<RunJobs> {
     inFlight: async () => (await live()).filter((record) => record.state === 'running').length,
     [Symbol.asyncDispose]: async (): Promise<void> => {
       await driver.close?.();
+      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/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/index.ts

@@ -23,6 +23,10 @@ export {
 // `test` is OURS (fixture-injecting); everything else passes through. Re-exported so an app
 // test has one import line, and so `expect` carries this package's matchers already installed.
 export { afterAll, afterEach, beforeAll, beforeEach, describe, expect } from 'bun:test';
+// The two arguments `hooks.authenticate` is handed, for a test of an app's own authenticator.
+// `@ultimat3/http` is imported inside the function.
+export type { AuthRequestInit } from './auth-request';
+export { authRequest } from './auth-request';
 // The browser-backed e2e driver and the raw-CDP browser under it — moved here from
 // `@ultimat3/cli` in 22.0.0. `installE2eDriver` is the ONE entry point an app's test preload calls;
 // `openE2eBrowserIfAvailable()` answers `undefined` on a machine with no Chrome, so a
@@ -167,7 +171,14 @@ export type {
   SharedChunkLike,
 } from './fixture-island';
 export { mountIsland } from './fixture-island';
-export type { JobRunTrace, RunJobs, StepTally } from './fixture-jobs';
+export type {
+  JobDrainAs,
+  JobEnqueueAs,
+  JobRunTrace,
+  RunJobs,
+  RunJobsOptions,
+  StepTally,
+} from './fixture-jobs';
 export { createRunJobs } from './fixture-jobs';
 export type { MailRef, TestMail } from './fixture-mail';
 export { createTestMail } from './fixture-mail';
@@ -201,6 +212,14 @@ export {
 // The file an error tells the reader to edit — the island's own name with `.states.ts` where
 // `.tsx` was. Exported so the command that takes the pictures names the same file the refusal does.
 export { islandStatesFile } from './island-state-errors';
+// One declared state, mounted: `describeIslandState` owns a block's mount and teardown,
+// `mountIslandState` is the one mount a single test asks for with `using`.
+export type { IslandStateMountOptions, IslandStateSuiteOptions } from './island-state-mount';
+export {
+  describeIslandState,
+  ISLAND_MOUNT_TIMEOUT_MS,
+  mountIslandState,
+} from './island-state-mount';
 export type {
   IslandRouteStub,
   IslandState,
@@ -254,6 +273,9 @@ export {
 export { ISOLATED_ENV, releasePluginsAfterIsolatedFile } from './isolated-plugins';
 export type { LiveConnection, LiveNodeHandle, LiveNodeOptions } from './live-node';
 export { createLiveNode } 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';
 /**
  * The budget `toBeVisible(options?)` takes. Exported because it is in a public matcher's signature;
  * `retryUntil` and `RetryBudget` deliberately are NOT — nothing outside this package calls them,
@@ -272,6 +294,10 @@ export type { RegistryLeak, RegistrySample } from './registry-leak-guard';
 export { installRegistryLeakGuard, leakBetween, sampleRegistries } from './registry-leak-guard';
 export type { ProcessRegistrySnapshot } from './registry-snapshot';
 export { captureProcessRegistries, restoreProcessRegistries } from './registry-snapshot';
+// What the server renders, for a unit test. `@ultimat3/render` is imported inside the two
+// functions, so a tier-0 test importing this barrel for `expect` still loads no renderer.
+export type { RenderedRoute, RenderedView, RouteModule, RouteRequest } from './render-view';
+export { renderRoute, renderView } from './render-view';
 export type { DatabaseSnapshot } from './reusable-database';
 export { restoreDatabase, reusableDatabase, snapshotDatabase } from './reusable-database';
 export type { MockRoute, NetworkSnapshot, NetworkState } from './sealed-network';
@@ -308,12 +334,14 @@ export {
 } from './template-db';
 export type {
   E2eBody,
+  E2eDriver,
   E2eFixtures,
   EvalCase,
   EvalOptions,
   LocatorLike,
   OpenApiLike,
   PageLike,
+  TestOptions,
   TestType,
 } from './test-types';
 export {

package/src/island-state-errors.ts

@@ -234,3 +234,22 @@ export class IslandStatesAmbiguousError extends UltimateError {
     });
   }
 }
+
+/**
+ * A state id the manifest does not declare — a test naming `idel`, or a state renamed in the
+ * manifest and not in the test beside it. Listing the declared ids is the whole value, for the
+ * reason `IslandStatesUnknownError` lists names: a typo and a rename are one symptom.
+ */
+export class IslandStateUnknownError extends UltimateError {
+  constructor(input: {
+    readonly island: string;
+    readonly id: string;
+    readonly known: readonly string[];
+  }) {
+    super({
+      code: 'X_TEST_ISLAND_STATE_UNKNOWN',
+      cause: `${renderCauseValue(input.island)} declares no state ${renderCauseValue(input.id)}; declared: ${input.known.join(', ')}`,
+      fix: `name one of them instead: ${input.known[0] ?? ''} — or declare the state in ${at(input.island)}`,
+    });
+  }
+}