@ultimat3/testing 23.0.0 → 24.0.0

package/src/e2e-spawn.ts

@@ -10,6 +10,7 @@ import { get } from 'node:http';
 import { dirname, join } from 'node:path';
 import { assert } from '@ultimat3/core';
 import { E2eAppFailedError } from './e2e-errors';
+import { freePort } from './free-port';
 
 /** `x dev` (sync included), or the production entry `apps/web/server.ts` under `ROLE=web`. */
 export type E2eAppMode = 'dev' | 'serve';
@@ -64,14 +65,6 @@ export interface SpawnE2eAppOptions {
   readonly bin?: string | undefined;
 }
 
-/** A port nothing holds right now, asked of the OS and handed to the child. */
-const freePort = (): number => {
-  const probe = Bun.serve({ port: 0, fetch: () => new Response() });
-  const port = probe.port ?? 0;
-  probe.stop(true);
-  return port;
-};
-
 /**
  * This process's environment minus what makes the child a TEST process. Spawned from `bun test`,
  * `NODE_ENV=test` rode along and the app resolved its environment as `test` — so a development-only

package/src/errors.ts

@@ -48,6 +48,7 @@ export const TESTING_ERROR_CODES = [
   'X_TEST_OPENAPI_EXPECTED',
   'X_TEST_NUMBER_EXPECTED',
   'X_TEST_ISLAND_STATE_UNKNOWN',
+  'X_TEST_APP_NOT_BOOTED',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -87,6 +88,7 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   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',
+  X_TEST_APP_NOT_BOOTED: 'describeApp handle read before boot',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -135,7 +137,18 @@ export class NondeterministicError extends UltimateError {
     super({
       code: 'X_TEST_NONDETERMINISTIC',
       cause: `${input.what} produced "${input.first}" then "${input.second}"`,
-      fix: 'wrap the test in frozenClock() / seededRandom(), or remove the wall-clock read',
+      fix: "assertDeterministic('…', () => { installDeterminism(); return body(); })",
+    });
+  }
+}
+
+/** `describeApp`'s `app()` read while the block was still being registered, before `beforeAll`. */
+export class AppNotBootedError extends UltimateError {
+  constructor(input: { suite: string }) {
+    super({
+      code: 'X_TEST_APP_NOT_BOOTED',
+      cause: `describeApp('${input.suite}') — app() was called while the describe block was being registered, before its beforeAll booted the app`,
+      fix: "test('…', () => { const handle = app(); })",
     });
   }
 }

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

@@ -244,11 +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?.();
-      renewals[Symbol.dispose]();
-      jobs.setEventBus(previousBus);
-      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/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/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;
     });
   });

package/src/index.ts

@@ -27,6 +27,8 @@ export { afterAll, afterEach, beforeAll, beforeEach, describe, expect } from 'bu
 // `@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
@@ -50,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,
@@ -62,6 +70,8 @@ export {
   CHROME_PATH_ENV,
   CONTAINER_CHROME_ARGS,
   findChrome,
+  LAUNCH_ATTEMPTS,
+  LAUNCH_TIMEOUT_MS,
   launchChrome,
   launchFoundChrome,
 } from './cdp-launch';
@@ -121,6 +131,7 @@ export {
 } from './e2e-selection';
 export type { TestingErrorCode } from './errors';
 export {
+  AppNotBootedError,
   FixtureUnavailableError,
   NetworkOfflineError,
   NetworkSealedError,
@@ -271,6 +282,7 @@ 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.

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