@ultimat3/testing 23.0.0 → 25.0.0

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';
@@ -198,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);
@@ -245,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);
@@ -294,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
@@ -350,8 +390,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 +402,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 +412,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);
@@ -410,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,
@@ -430,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,
@@ -438,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-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,105 @@
+// 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`. 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.
+
+// 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
+ * 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(), `${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;
+    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

@@ -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/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

@@ -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,
@@ -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.