@ultimat3/testing 22.15.0 → 24.0.0

package/src/index.ts

@@ -23,6 +23,12 @@ 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';
+export type { BudgetStoreLike } from './budget-store-conformance';
+export { budgetStoreConformance } from './budget-store-conformance';
 // 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
@@ -46,6 +52,12 @@ export type { CdpE2eTabOptions, E2eTab } from './cdp-e2e-page';
 export { cdpE2eTab } from './cdp-e2e-page';
 export type { CdpE2eSessionOptions, E2eSession } from './cdp-e2e-session';
 export { cdpE2eSession } from './cdp-e2e-session';
+export type {
+  CdpLaunchAttempt,
+  CdpTargetGone,
+  CdpTimeoutObservation,
+  CdpTimeoutReading,
+} from './cdp-errors';
 export {
   CdpBrowserMissingError,
   CdpCallFailedError,
@@ -58,6 +70,8 @@ export {
   CHROME_PATH_ENV,
   CONTAINER_CHROME_ARGS,
   findChrome,
+  LAUNCH_ATTEMPTS,
+  LAUNCH_TIMEOUT_MS,
   launchChrome,
   launchFoundChrome,
 } from './cdp-launch';
@@ -117,6 +131,7 @@ export {
 } from './e2e-selection';
 export type { TestingErrorCode } from './errors';
 export {
+  AppNotBootedError,
   FixtureUnavailableError,
   NetworkOfflineError,
   NetworkSealedError,
@@ -167,7 +182,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 +223,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,
@@ -252,8 +282,12 @@ export {
   normalizeIslandName,
 } from './island-states-resolve';
 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';
+// 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 +306,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 +346,14 @@ export {
 } from './template-db';
 export type {
   E2eBody,
+  E2eDriver,
   E2eFixtures,
   EvalCase,
   EvalOptions,
   LocatorLike,
   OpenApiLike,
   PageLike,
+  TestOptions,
   TestType,
 } from './test-types';
 export {

package/src/island-dom.ts

@@ -6,6 +6,7 @@
 // Two neighbours at the 500-line ceiling: `island-selector.ts` is the selector grammar `find`
 // and `all` read, and `island-observers.ts` is the `ResizeObserver` an island measures with.
 
+import { decodeEntities } from './island-html-entities';
 import type { FakeResizeObserver } from './island-observers';
 import { createResizeObservers, rectOf } from './island-observers';
 import { matchesSelector, parseSelector } from './island-selector';
@@ -350,8 +351,10 @@ const VOID_TAGS = new Set([
   'track',
   'wbr',
 ]);
+// Group 6 is a comment: Solid compiles `<!>` as the marker its `nextSibling` walk counts, so it must
+// be a node — read as text it merged into its neighbours and the walk landed one node short.
 const TOKEN =
-  /<(\/?)([a-zA-Z][\w-]*)((?:\s+[^\s=/>]+(?:=(?:"[^"]*"|'[^']*'|[^\s>]+))?)*)\s*(\/?)>|([^<]+)/g;
+  /<(\/?)([a-zA-Z][\w-]*)((?:\s+[^\s=/>]+(?:=(?:"[^"]*"|'[^']*'|[^\s>]+))?)*)\s*(\/?)>|([^<]+)|(<!(?:--[\s\S]*?--|[^>]*)>)/g;
 const ATTRIBUTE = /([^\s=/>]+)(?:=(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
 
 /** Only what `babel-preset-solid` emits into a template: tags, static attributes and text. */
@@ -360,8 +363,8 @@ export function parseHtml(html: string): FakeNode {
   const open: FakeNode[] = [root];
   for (const match of html.matchAll(TOKEN)) {
     const parent = open[open.length - 1] as FakeNode;
-    if (match[5] !== undefined) {
-      parent.appendChild(new FakeText(match[5]));
+    if (match[5] !== undefined || match[6] !== undefined) {
+      parent.appendChild(new FakeText(decodeEntities(match[5] ?? '')));
       continue;
     }
     if (match[1] === '/') {
@@ -370,7 +373,8 @@ export function parseHtml(html: string): FakeNode {
     }
     const element = new FakeElement(match[2] as string);
     for (const attr of (match[3] ?? '').matchAll(ATTRIBUTE)) {
-      if (attr[1] !== undefined) element.setAttribute(attr[1], attr[2] ?? attr[3] ?? attr[4] ?? '');
+      if (attr[1] !== undefined)
+        element.setAttribute(attr[1], decodeEntities(attr[2] ?? attr[3] ?? attr[4] ?? ''));
     }
     parent.appendChild(element);
     if (match[4] !== '/' && !VOID_TAGS.has(element.tagName)) open.push(element);

package/src/island-html-entities.ts

@@ -0,0 +1,27 @@
+// Character references in a compiled island template, decoded once — what a browser's parser does
+// before an island reads `textContent` or `getAttribute`.
+
+const NAMED = Object.freeze<Record<string, string>>({
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+});
+
+const REFERENCE = /&(?:#(\d+)|#[xX]([0-9a-fA-F]+)|([a-zA-Z]+));/g;
+const MAX_CODE_POINT = 0x10ffff;
+const REPLACEMENT = '\uFFFD';
+
+/** The five named entities Solid's escaper writes, and numeric references; an unknown name as written. */
+export function decodeEntities(text: string): string {
+  if (!text.includes('&')) return text;
+  return text.replace(REFERENCE, (whole, decimal?: string, hex?: string, name?: string) => {
+    if (name !== undefined) return Object.hasOwn(NAMED, name) ? (NAMED[name] as string) : whole;
+    const point = decimal !== undefined ? Number(decimal) : Number.parseInt(hex as string, 16);
+    // What the HTML parser does with a reference no character answers to: U+FFFD, never `\0` or a
+    // lone surrogate.
+    const invalid = point === 0 || point > MAX_CODE_POINT || (point >= 0xd800 && point <= 0xdfff);
+    return invalid ? REPLACEMENT : String.fromCodePoint(point);
+  });
+}

package/src/island-scratch.ts

@@ -0,0 +1,41 @@
+// 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`.
+
+import { mkdtempSync, rmSync } 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;
+
+/**
+ * A fresh directory for one mount. Fresh, not shared: a module is cached by PATH, so two mounts
+ * of byte-identical chunks under one directory imported as ONE instance and shared its state.
+ *
+ * The `exit` handler is the backstop for a process that is not `bun test` (`bun run`, `x shot`);
+ * 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-'));
+  live.add(dir);
+  if (!exitHooked) {
+    exitHooked = true;
+    process.on('exit', removeAllScratchDirs);
+  }
+  return dir;
+}
+
+/** Remove one mount's directory. Idempotent: dispose and a failed mount may both reach it. */
+export function removeScratchDir(dir: string): void {
+  live.delete(dir);
+  rmSync(dir, { recursive: true, force: true });
+}
+
+function removeAllScratchDirs(): void {
+  for (const dir of [...live]) removeScratchDir(dir);
+}
+
+/** Every scratch directory whose mount has not ended — read by the leak test. */
+export const islandScratchDirs = (): readonly string[] => [...live];

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)}`,
+    });
+  }
+}

package/src/island-state-mount.ts

@@ -0,0 +1,129 @@
+// One declared island STATE, mounted: the lookup every island test hand-rolled, and the suite
+// form that owns the `beforeAll` / `afterAll` a mount needs because it installs a process-global
+// `document`. The props a test asserts on are the props `x shot --island` photographs, so the
+// picture and the test cannot be of two different components.
+
+import { afterAll, beforeAll, describe } from 'bun:test';
+import { assert } from '@ultimat3/core';
+import type {
+  IslandBuilder,
+  IslandBundleLike,
+  MountedIsland,
+  MountIslandOptions,
+} from './fixture-island';
+import { mountIsland } from './fixture-island';
+import { IslandStateUnknownError } from './island-state-errors';
+import type { IslandStatesManifest } from './island-states';
+import type { TestOptions } from './test-types';
+import { testName } from './test-types';
+
+/** What a state's mount takes: `mountIsland`'s options, minus what the manifest already says. */
+export type IslandStateMountOptions = Omit<MountIslandOptions, 'file' | 'props'>;
+
+/** The suite form's: the mount's own, plus the deadline of the `beforeAll` that runs it. */
+export interface IslandStateSuiteOptions extends IslandStateMountOptions, TestOptions {}
+
+/**
+ * The deadline a block's mount gets when it names none. The first mount in a file pays the island
+ * build — a Babel pass and a browser bundle, seconds not milliseconds — and Bun's 5 s default is
+ * what a cold CI runner misses.
+ */
+export const ISLAND_MOUNT_TIMEOUT_MS = 60_000;
+
+/**
+ * Bundles already built in this process, per builder, by `<root>\0<island>`. A file with three
+ * states used to build its island three times; the source cannot change between two mounts of one
+ * test run, so the second is a lookup. A build that REJECTS is forgotten, so the next mount
+ * reports its own failure rather than a cached one.
+ */
+const bundles = new WeakMap<IslandBuilder, Map<string, Promise<IslandBundleLike>>>();
+
+const buildOnce =
+  (build: IslandBuilder): IslandBuilder =>
+  (root, options) => {
+    const built = bundles.get(build) ?? new Map<string, Promise<IslandBundleLike>>();
+    bundles.set(build, built);
+    const key = `${root}\0${options?.only ?? ''}`;
+    const known = built.get(key);
+    if (known !== undefined) return known;
+    const pending = build(root, options);
+    built.set(key, pending);
+    pending.catch(() => built.delete(key));
+    return pending;
+  };
+
+/**
+ * Mount one state the manifest declares. `using island = await mountIslandState(states, 'idle',
+ * { build: buildIslands, root })` inside one test — `using` owns the teardown. A file asserting
+ * several things about one state uses `describeIslandState`, which owns it for the block.
+ */
+export async function mountIslandState(
+  manifest: IslandStatesManifest,
+  id: string,
+  options: IslandStateMountOptions,
+): Promise<MountedIsland> {
+  const state = manifest.states.find((one) => one.id === id);
+  if (state === undefined) {
+    throw new IslandStateUnknownError({
+      island: manifest.island,
+      id,
+      known: manifest.states.map((one) => one.id),
+    });
+  }
+  return mountIsland({
+    ...options,
+    build: buildOnce(options.build),
+    file: manifest.island,
+    props: state.props,
+  });
+}
+
+/**
+ * One block per declared state: mounted before its first test, disposed after its last, with the
+ * island built once per file. `body` is handed an ACCESSOR, for `describeApp`'s reason — the
+ * block is declared at module scope and the mount does not exist until `beforeAll` has run:
+ *
+ * ```ts
+ * describeIslandState(counterStates, 'idle', { build: buildIslands, root }, (island) => {
+ *   test('a click reaches the DOM', () => {
+ *     expect(island().fire('button', 'click')).toBe(true);
+ *   });
+ * });
+ * ```
+ *
+ * Calls `describe`, so it goes at declaration scope. The block is named for the `unit` step — an
+ * island test is `<name>.island.test.ts`, which that step owns.
+ */
+export function describeIslandState(
+  manifest: IslandStatesManifest,
+  id: string,
+  options: IslandStateSuiteOptions,
+  body: (island: () => MountedIsland) => void,
+): void {
+  const { timeoutMs, ...mount } = options;
+  describe(testName('unit', `the ${manifest.name} island, ${id}`), () => {
+    let mounted: MountedIsland | undefined;
+    let over = false;
+    beforeAll(async () => {
+      const island = await mountIslandState(manifest, id, mount);
+      // A mount that outlived its deadline lands after `afterAll` has already run: disposed here,
+      // or its fake `document` is every later block's.
+      if (over) island[Symbol.dispose]();
+      else mounted = island;
+    }, timeoutMs ?? ISLAND_MOUNT_TIMEOUT_MS);
+    // Bun runs `afterAll` whether or not the mount resolved, so this reads what is there.
+    afterAll(() => {
+      over = true;
+      mounted?.[Symbol.dispose]();
+      mounted = undefined;
+    });
+    body(() => {
+      assert(
+        mounted !== undefined,
+        `the ${manifest.name} island's "${id}" state is not mounted — its mount failed, or the accessor was called outside this block's tests`,
+        'call the accessor inside a test of this describeIslandState block; a failed mount is reported above this line, by its own error',
+      );
+      return mounted;
+    });
+  });
+}

package/src/job-driver-checks.ts

@@ -0,0 +1,177 @@
+// What every `JobDriver` must do, as checks over a driver: claim, ack, nack, the claim fence, lease
+// expiry and the burial of a row whose lease lapsed on its final attempt. A custom `claim` that
+// ignored `onExhausted` / `dropExhausted` compiled and re-claimed a poisoned row forever.
+// Type-only imports: the barrel never loads `@ultimat3/jobs`.
+
+import { expect } from 'bun:test';
+import type { ClaimOptions, JobDriver, JobRecord, QueueStats } from '@ultimat3/jobs';
+
+export interface JobDriverCheck {
+  readonly name: string;
+  run(driver: JobDriver): Promise<void>;
+}
+
+let minted = 0;
+
+/** A queue and a job name of this check's own, so checks sharing one store never see each other. */
+const scope = (): { readonly queue: string; readonly name: string } => {
+  minted += 1;
+  const tag = `${process.pid.toString(36)}-${minted.toString(36)}`;
+  return { queue: `conformance-${tag}`, name: `conformance.job-${tag}` };
+};
+
+const enqueue = async (
+  driver: JobDriver,
+  at: { readonly queue: string; readonly name: string },
+  maxAttempts: number,
+  key = 'k',
+): Promise<string> =>
+  (
+    await driver.enqueue({
+      name: at.name,
+      queue: at.queue,
+      input: {},
+      idempotencyKey: key,
+      maxAttempts,
+    })
+  ).id;
+
+const claim = (
+  driver: JobDriver,
+  queue: string,
+  workerId: string,
+  extra: Partial<ClaimOptions> = {},
+) => driver.claim({ queues: [queue], limit: 10, visibilityTimeoutMs: 30_000, workerId, ...extra });
+
+const statsOf = async (driver: JobDriver, queue: string): Promise<QueueStats | undefined> =>
+  (await driver.stats()).find((each) => each.queue === queue);
+
+interface Lapsed {
+  readonly id: string;
+  readonly queue: string;
+  readonly reported: readonly (readonly JobRecord[])[];
+  /** How many rows the second claim handed out. */
+  readonly handed: number;
+}
+
+/**
+ * Two claims, the first with a lease that has already lapsed (0 ms): the second re-claims the row
+ * or, on its final attempt, buries it. `drop` names the job in `dropExhausted`.
+ */
+async function lapse(driver: JobDriver, maxAttempts: number, drop = false): Promise<Lapsed> {
+  const at = scope();
+  const id = await enqueue(driver, at, maxAttempts);
+  expect(await claim(driver, at.queue, 'w1', { visibilityTimeoutMs: 0 })).toHaveLength(1);
+  const reported: JobRecord[][] = [];
+  const second = await claim(driver, at.queue, 'w2', {
+    ...(drop ? { dropExhausted: [at.name] } : {}),
+    onExhausted: (dead) => reported.push([...dead]),
+  });
+  return { id, queue: at.queue, reported, handed: second.length };
+}
+
+const buried = (lapsed: Lapsed): readonly (readonly [string, string])[][] =>
+  lapsed.reported.map((rows) => rows.map((row) => [row.id, row.state] as const));
+
+export const JOB_DRIVER_CHECKS: readonly JobDriverCheck[] = [
+  {
+    name: 'a row is claimed once, and an ack by its claim settles it',
+    async run(driver) {
+      const at = scope();
+      const id = await enqueue(driver, at, 3);
+      const [first, ...rest] = await claim(driver, at.queue, 'w1');
+      expect(rest).toEqual([]);
+      expect(first).toMatchObject({ id, state: 'running', claimedBy: 'w1' });
+      expect(await claim(driver, at.queue, 'w2')).toEqual([]);
+      expect(await driver.ack(id, { workerId: 'w1', claim: first?.claim ?? -1 })).toBe(true);
+      expect(await claim(driver, at.queue, 'w2')).toEqual([]);
+      expect((await statsOf(driver, at.queue))?.running ?? 0).toBe(0);
+    },
+  },
+  {
+    name: 'a live idempotency key dedupes onto the row that holds it',
+    async run(driver) {
+      const at = scope();
+      const id = await enqueue(driver, at, 3, 'same');
+      const again = await driver.enqueue({
+        name: at.name,
+        queue: at.queue,
+        input: {},
+        idempotencyKey: 'same',
+        maxAttempts: 3,
+      });
+      expect(again).toMatchObject({ id, deduped: true });
+    },
+  },
+  {
+    name: 'an empty queue list is refused, never read as every queue or as default',
+    async run(driver) {
+      const refused = await Promise.resolve()
+        .then(() => driver.claim({ queues: [], limit: 1, visibilityTimeoutMs: 1, workerId: 'w' }))
+        .then(
+          () => undefined,
+          (error: unknown) => error,
+        );
+      expect(refused).toMatchObject({ code: 'X_JOB_CLAIM_QUEUES_EMPTY' });
+    },
+  },
+  {
+    name: 'a nack hands the row back, and the claim it ended can no longer settle it',
+    async run(driver) {
+      const at = scope();
+      const id = await enqueue(driver, at, 3);
+      const [first] = await claim(driver, at.queue, 'w1');
+      const one = { workerId: 'w1', claim: first?.claim ?? -1 };
+      expect(await driver.nack(id, { ...one, delayMs: 0 })).toBe(true);
+      const [second] = await claim(driver, at.queue, 'w1');
+      expect(second?.id).toBe(id);
+      expect(second?.claim).toBeGreaterThan(one.claim);
+      expect(await driver.ack(id, one)).toBe(false);
+      expect(await driver.ack(id, { workerId: 'w1', claim: second?.claim ?? -1 })).toBe(true);
+    },
+  },
+  {
+    name: 'a dead-lettered row is counted dead and never claimed again',
+    async run(driver) {
+      const at = scope();
+      const id = await enqueue(driver, at, 3);
+      const [first] = await claim(driver, at.queue, 'w1');
+      const by = { workerId: 'w1', claim: first?.claim ?? -1, delayMs: 0, deadLetter: true };
+      expect(await driver.nack(id, by)).toBe(true);
+      expect(await claim(driver, at.queue, 'w1')).toEqual([]);
+      expect(await statsOf(driver, at.queue)).toMatchObject({ dead: 1 });
+    },
+  },
+  {
+    name: 'a lapsed lease is re-claimed, and the worker that lost it can neither renew nor settle',
+    async run(driver) {
+      const { id, handed } = await lapse(driver, 3);
+      expect(handed).toBe(1);
+      const renew = (workerId: string) =>
+        driver.heartbeat(id, { visibilityTimeoutMs: 30_000, workerId });
+      expect(await renew('w1')).toBe(false);
+      expect(await renew('w2')).toBe(true);
+    },
+  },
+  {
+    name: 'a lease lapsed on the final attempt is buried dead, reported once, never handed out',
+    async run(driver) {
+      const lapsed = await lapse(driver, 1);
+      expect(lapsed.handed).toBe(0);
+      expect(buried(lapsed)).toEqual([[[lapsed.id, 'dead']]]);
+      let again = 0;
+      const third = await claim(driver, lapsed.queue, 'w3', { onExhausted: () => (again += 1) });
+      expect([third.length, again]).toEqual([0, 0]);
+      expect(await statsOf(driver, lapsed.queue)).toMatchObject({ dead: 1, running: 0 });
+    },
+  },
+  {
+    name: 'dropExhausted buries the named job failed, not dead',
+    async run(driver) {
+      const lapsed = await lapse(driver, 1, true);
+      expect(lapsed.handed).toBe(0);
+      expect(buried(lapsed)).toEqual([[[lapsed.id, 'failed']]]);
+      expect(await statsOf(driver, lapsed.queue)).toMatchObject({ failed: 1, dead: 0 });
+    },
+  },
+];

package/src/job-driver-conformance.ts

@@ -0,0 +1,21 @@
+// The `JobDriver` contract as shared examples: `behavesLike(jobDriverConformance, () => driver)`
+// runs every check in `job-driver-checks.ts` against a driver of your own, one test per check.
+// The subject is called once per test — hand back a fresh driver, or one store with no rows a
+// check could mistake for its own (each check claims only from a queue it named).
+
+import { test } from 'bun:test';
+import type { JobDriver } from '@ultimat3/jobs';
+import { JOB_DRIVER_CHECKS } from './job-driver-checks';
+import type { SharedExamples } from './shared-examples';
+import { sharedExamples } from './shared-examples';
+
+export const jobDriverConformance: SharedExamples<JobDriver | Promise<JobDriver>> = sharedExamples(
+  'a job driver',
+  (subject) => {
+    for (const check of JOB_DRIVER_CHECKS) {
+      test(check.name, async () => {
+        await check.run(await subject());
+      });
+    }
+  },
+);

package/src/live-node.ts

@@ -178,6 +178,8 @@ export async function createLiveNode(options: LiveNodeOptions = {}): Promise<Liv
           data = upgradeOptions.data;
           return true;
         },
+        // No socket behind this harness, so no peer address: a health path answers the verdict.
+        requestIP: () => null,
       };
       // `/_x/sync` is `SyncNodeOptions.path`'s default and `handleUpgrade` answers 404 to
       // anything else. The `c` parameter is this connection's actor key — see `ACTORS` above.

package/src/local-tx.ts

@@ -0,0 +1,87 @@
+// A mutator's `local()` half, run in a unit test: a `LocalTx` over rows held in memory, with the
+// semantics of the page's record store. The twin under test is the app's; this is only the store
+// it writes into, so a test asserts on rows and holds no cast and no hand-rolled table.
+
+import type { LocalTable, LocalTx } from '@ultimat3/action';
+
+/** `{ <table>: { <key>: <row> } }` — what the store holds, as a test seeds it and reads it back. */
+export type LocalRows<TRow extends object = object> = Readonly<
+  Record<string, Readonly<Record<string, TRow>>>
+>;
+
+export interface MemoryLocalTx {
+  /** What `mutator.local(tx, input)` is handed. `tx.<table>` and `tx.table('<name>')` are one table. */
+  readonly tx: LocalTx;
+  /** What a table holds now, by key — after however many applications. `{}` for one never seen. */
+  rows<TRow extends object = object>(table: string): Readonly<Record<string, TRow>>;
+}
+
+/** `undefined` in a patch means "leave it alone", exactly as the record store reads it. */
+const definedOf = (columns: object): Record<string, unknown> =>
+  Object.fromEntries(Object.entries(columns).filter(([, value]) => value !== undefined));
+
+/**
+ * A client store for one test. Keyed, exactly like the real one: the browser holds no entity
+ * schema, so a row is addressed by the key its server twin answers under, never by a column.
+ *
+ * | Call | Does |
+ * |---|---|
+ * | `insert(key, row)` | stores the row under the key |
+ * | `upsert(key, row)` | merges over what is held; an `undefined` field leaves the column alone |
+ * | `update(key, patch)` | changed fields, or a function of the held row. A NO-OP for a key the table does not hold — a twin must not invent a row |
+ * | `delete(key)` | removes it |
+ */
+export function memoryLocalTx(seed: LocalRows = {}): MemoryLocalTx {
+  const tables = new Map<string, Map<string, object>>();
+  const held = (name: string): Map<string, object> => {
+    const existing = tables.get(name);
+    if (existing !== undefined) return existing;
+    const created = new Map<string, object>();
+    tables.set(name, created);
+    return created;
+  };
+  // Frozen on the way in, as the record store freezes: a twin that mutated a row in place would
+  // pass here and corrupt the synced truth it was handed in a browser.
+  const stored = (row: object): object => Object.freeze({ ...row });
+  for (const [name, rows] of Object.entries(seed)) {
+    for (const [key, row] of Object.entries(rows)) held(name).set(key, stored(row));
+  }
+
+  // The one widening in this file: the store holds rows of whatever shape a test seeded, and a
+  // table is read back as the shape its caller names — the same door `tx.table<TRow>()` is.
+  const table = <TRow extends object>(name: string): LocalTable<TRow> => {
+    const rows = held(name) as Map<string, TRow>;
+    return {
+      get: (key) => rows.get(key),
+      all: () => [...rows.values()],
+      insert: (key, row) => {
+        rows.set(key, stored(row) as TRow);
+      },
+      upsert: (key, row) => {
+        rows.set(key, stored({ ...rows.get(key), ...definedOf(row) }) as TRow);
+      },
+      update: (key, patch) => {
+        const current = rows.get(key);
+        if (current === undefined) return;
+        const changed = typeof patch === 'function' ? patch(current) : patch;
+        rows.set(key, stored({ ...current, ...definedOf(changed) }) as TRow);
+      },
+      delete: (key) => {
+        rows.delete(key);
+      },
+    };
+  };
+
+  const tx = new Proxy({} as LocalTx, {
+    get: (_target, property) => {
+      if (typeof property !== 'string') return undefined;
+      return property === 'table' ? table : table(property);
+    },
+  });
+
+  return {
+    tx,
+    rows: <TRow extends object = object>(name: string): Readonly<Record<string, TRow>> =>
+      Object.fromEntries(tables.get(name) ?? []) as Record<string, TRow>,
+  };
+}