@ultimat3/testing 29.4.0 → 30.0.0

package/src/index.ts

@@ -27,8 +27,24 @@ 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';
+// The accessibility audit every `e2eTest` runs (plan 101 / 39): the one reader of the browser's
+// tree, its rules, and the reasoned per-test `allow`.
+export type { AxNode, AxTreeNode } from './ax-node';
+export { toAxNode, toAxTreeNodes } from './ax-node';
 export type { BudgetStoreLike } from './budget-store-conformance';
 export { budgetStoreConformance } from './budget-store-conformance';
+// Recorded vendor answers, replayed through `mockFetch` with the network sealed; recorded only by
+// hand (`ULTIMATE_CASSETTE=record`, never under CI), with the written bytes scanned for secrets.
+export type { Cassette, CassetteOptions } from './cassette';
+export { CASSETTE_ENV, cassette } from './cassette';
+export type { RecordRefusal, UnusedEntry } from './cassette-errors';
+export {
+  CassetteMissingError,
+  CassetteRecordRefusedError,
+  CassetteSecretError,
+  CassetteUnusedError,
+} from './cassette-errors';
+export type { CassetteEntry, CassetteFile } from './cassette-format';
 // 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
@@ -82,6 +98,10 @@ export {
   launchChrome,
   launchFoundChrome,
 } from './cdp-launch';
+// The exercise pass (plan 101 / 40, phase 2): an app's per-primitive overrides — 39's
+// `.contract({ exercise })` option, one shape — and the pass over every action, query and job.
+export type { ExerciseAppOptions, ExerciseOverride, ExerciseOverrides } from './define-exercise';
+export { defineExercise } from './define-exercise';
 // The island-state vocabulary. Pure data by design: a `*.island.states.ts` file is read by the
 // command that photographs the states, by the harness page and by a guard test — none of which has
 // a bundler, and only one of which has a browser.
@@ -106,6 +126,35 @@ export {
   setFrozenClock,
   withFrozenClock,
 } from './determinism';
+// `x drill` (plan 101 / 40): the eight fault drills, the fleet they run on, the verdict over evidence.
+export type { DrillConfig, DrillTiming } from './drill-budgets';
+export { drillBudgets } from './drill-budgets';
+export { DrillFailedError, DrillServiceMissingError } from './drill-errors';
+export type { DrillFleet, DrillRoleProcess, DrillServiceUrls } from './drill-fleet';
+export { startDrillFleet } from './drill-fleet';
+export { bunDrillSql } from './drill-jobs';
+export type { DrillTarget } from './drill-load';
+export type { DrillReport } from './drill-run';
+export { runDrill } from './drill-run';
+export type { DrillDeclarations } from './drill-services';
+export { DRILL_SERVICE_ENV, drillServices } from './drill-services';
+export type { DrillSyncEvidence, DrillSyncLane, DrillSyncOptions } from './drill-sync';
+export { startDrillSync } from './drill-sync';
+export type { DrillBudgets, DrillEvidence, DrillFailure, DrillProperty } from './drill-verdict';
+export { judgeDrill } from './drill-verdict';
+export type { DrillWriteCandidate, DrillWrites } from './drill-writes';
+export { DRILL_DRAW_SEED, drillWriteTargets } from './drill-writes';
+export type { Drill, DrillName, DrillRole, DrillService } from './drills';
+export { DRILL_NAMES, DRILLS, drillNamed, drillRoles } from './drills';
+export type { A11yFinding, A11yRule } from './e2e-a11y';
+export { auditTree, NAMED_ROLES } from './e2e-a11y';
+export type { A11yAllow, A11yOptions } from './e2e-a11y-run';
+export {
+  E2eA11yAllowUnreasonedError,
+  E2eA11yUnavailableError,
+  E2eA11yViolationError,
+} from './e2e-a11y-run';
+export { allowA11y } from './e2e-a11y-tabs';
 export type { E2eApp, E2eAppMode, StartE2eAppOptions } from './e2e-app';
 export { E2E_APP_START_MS, E2E_APP_STOP_MS, startE2eApp } from './e2e-app';
 export { E2E_ROOT_ENV, e2eApp, e2eBaseUrl, e2eBrowser } from './e2e-browser-handle';
@@ -126,7 +175,7 @@ export type { EvaluablePage } from './e2e-evaluate';
 export { closureSource, evaluateClosure, evaluateExpression } from './e2e-evaluate';
 export type { LocatablePage } from './e2e-locator';
 export { e2eLocator, resetLocatorMarks } from './e2e-locator';
-export type { E2eBrowserPage, E2ePageOptions } from './e2e-page';
+export type { AxTreeRequest, E2eBrowserPage, E2ePageOptions } from './e2e-page';
 export { DEFAULT_E2E_TIMEOUT_MS, DEFAULT_SERVICE_WORKER_TIMEOUT_MS, e2ePage } from './e2e-page';
 export type { E2eResolution, E2eSelection } from './e2e-selection';
 export {
@@ -148,6 +197,21 @@ export {
   TESTING_ERROR_TITLES,
   TestDatabaseUnavailableError,
 } from './errors';
+export type { ExercisePassOptions } from './exercise';
+export { runExercisePass } from './exercise';
+export type { ActorChoice, RoleGrants } from './exercise-actor';
+export type {
+  CrashFinding,
+  CrashProof,
+  EffectPayload,
+  ExerciseEffect,
+  ExerciseOutcome,
+  ExerciseRecord,
+  TenantFinding,
+  TenantLeg,
+  TenantProof,
+} from './exercise-report';
+export { overrideLine } from './exercise-report';
 export type {
   Association,
   AssociationMap,
@@ -163,6 +227,15 @@ export type { Persister } from './factory-persist';
 export { clearPersister, persisterInstalled, usePersister } from './factory-persist';
 export type { EntityRegistry, FactoryRegistry } from './factory-registry';
 export { factoriesFor } from './factory-registry';
+export type {
+  FakeIdentityProvider,
+  FakeIdentityProviderInput,
+  FakeIdpTamper,
+  FakeIdpUser,
+} from './fake-identity-provider';
+export { fakeIdentityProvider } from './fake-identity-provider';
+export type { FaultMode, FaultProxy, FaultProxyCounts } from './fault-proxy';
+export { faultProxy, throughFaultProxy } from './fault-proxy';
 export type { TestClock, TestDuration } from './fixture-clock';
 export { testClock } from './fixture-clock';
 export type {
@@ -291,7 +364,31 @@ export {
   normalizeIslandName,
 } from './island-states-resolve';
 export { ISOLATED_ENV, releasePluginsAfterIsolatedFile } from './isolated-plugins';
+export type {
+  CrashBoundary,
+  CrashDivergence,
+  CrashProofOptions,
+  CrashReport,
+  CrashRerun,
+} from './job-crash-proof';
+export { crashProof } from './job-crash-proof';
 export { jobDriverConformance } from './job-driver-conformance';
+export type { SimEffect } from './job-sim-effects';
+export {
+  JobCrashDivergedError,
+  JobSimInvariantError,
+  JobSimNondeterministicError,
+} from './job-sim-errors';
+export type { JobFaultKind } from './job-sim-schedule';
+export { ALL_FAULTS, JOB_FAULT_KINDS } from './job-sim-schedule';
+export type {
+  SimulatedJob,
+  SimulatedRun,
+  SimulateJobsOptions,
+  SimulationReport,
+  SimulationState,
+} from './job-simulate';
+export { JOB_SIM_SEED_ENV, simulateJobs } from './job-simulate';
 export type { LiveConnection, LiveNodeHandle, LiveNodeOptions } from './live-node';
 export { liveNode } from './live-node';
 // The store a mutator's `local()` half writes into under test — the Map every app hand-rolled.
@@ -305,6 +402,17 @@ export { memoryLocalTx } from './local-tx';
 export type { VisibleOptions } from './matcher-visible';
 export type { MatcherResult } from './matchers';
 export { matchersInstalled, recordSteps } from './matchers';
+export type { MockHandler, MockRoute } from './mock-route';
+// The plan and scale sweeps (plan 101 / 40-next-query-plans): every statement the pass sent planned
+// with no index but the declared ones, every reached primitive again at 2 and 8 rows a table.
+export type { PlanTableColumns, PlanVerdict, PlanVerdictCode } from './plan-oracle';
+export { judgePlan, planRoot } from './plan-oracle';
+export type { PlanExempt, PlanProof, SentStatement } from './plan-sweep';
+export { QueryPlanUnavailableError, sweepPlans } from './plan-sweep';
+export type { PlanFinding } from './plan-sweep-fix';
+export { planFindings } from './plan-sweep-fix';
+export type { SweepFinding } from './plan-sweep-report';
+export { planSweepFindings, planSweepLines } from './plan-sweep-report';
 // `isolateEntityRegistry` is deliberately NOT here — it is `@ultimat3/testing/registry-isolation`.
 // This barrel is what a `packages/core` test imports for `expect` alone, and a static re-export
 // evaluates the module it names: that one would load `@ultimat3/entity` and its process-global
@@ -319,9 +427,15 @@ export { captureProcessRegistries, restoreProcessRegistries } from './registry-s
 // 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';
+// What a test `x repro --write` generated calls: a captured request or a dead job, replayed.
+export type { JobFailure, ReproduceOptions, ReproOutcome } from './repro';
+export { reproduce, reproJob } from './repro';
+export type { LoggedRequest } from './request-log';
 export type { DatabaseSnapshot } from './reusable-database';
 export { restoreDatabase, reusableDatabase, snapshotDatabase } from './reusable-database';
-export type { MockRoute, NetworkSnapshot, NetworkState } from './sealed-network';
+export type { ScaleProof, ScaleShape, StatementTally } from './scale-sweep';
+export { judgeScale, SCALE_SIZES } from './scale-sweep';
+export type { NetworkSnapshot, NetworkState } from './sealed-network';
 // `setNetworkState` is deliberately not here: it is the offline gate's one writer, and a test that
 // called it directly would bypass the `network` fixture's disposal and leave the whole process
 // offline for every file after it. The fixture is the way to go offline — there is no second one.
@@ -332,14 +446,38 @@ export {
   mockFetch,
   mockJson,
   networkState,
-  requestedUrls,
+  requestLog,
   resetNetwork,
   restoreCapturedNetwork,
   sealNetwork,
   unsealNetwork,
 } from './sealed-network';
+// Rows for every table with no factory written (plan 101 / 40, phase 1): parents first, same-tenant
+// keys, values off each column's declaration. Types only from `@ultimat3/entity`, so no registry.
+export { seedGraph } from './seed-graph';
+export type { SeedGraphUnsatisfiedInput } from './seed-graph-error';
+// A seed graph written through each entity's own repository — a pinned client (Postgres, PGlite) or
+// the app's driver (memory, `testDriver()`). Loads `@ultimat3/entity` on its first write, not here.
+export { SeedGraphEntityUnknownError, SeedGraphUnsatisfiedError } from './seed-graph-error';
+export type {
+  SeedCanary,
+  SeedFactory,
+  SeedGraph,
+  SeedGraphOptions,
+  SeedRow,
+  SeedUpdate,
+  SeedWriter,
+} from './seed-graph-plan';
+export { insertSeedGraph } from './seed-graph-plan';
+export type { SeedEntity } from './seed-graph-shape';
+export type { SeedColumn } from './seed-graph-values';
+export type { EntitySeedWriterOptions, SeedWriterTarget } from './seed-writer';
+export { entitySeedWriter } from './seed-writer';
 export type { SharedExamples } from './shared-examples';
 export { behavesLike, sharedExamples } from './shared-examples';
+export type { SubjectProofOptions, SubjectProofResult } from './subject-proof';
+export { subjectProof } from './subject-proof';
+export { SubjectEraseIncompleteError } from './subject-proof-error';
 export type {
   DisposableWorkerDatabase,
   SqlRunner,
@@ -358,11 +496,18 @@ export {
   urlFor,
   workerId,
 } from './template-db';
+// The tenant proof's dynamic legs (plan 101 / 40): B with A's ids, A, B again. The report builders
+// are what `x exercise` prints; `tenancy:cross` is `@ultimat3/entity`'s `CROSS_TENANT_SCOPE`.
+export type { TenantProofFinding } from './tenant-proof-report';
+export { tenantFindingLines, tenantProofFindings } from './tenant-proof-report';
 export { paced, TEST_PACE_ENV, TestPaceInvalidError, testPace } from './test-pace';
+// `x exercise` is a test process too: it hands itself the same key, judged by the same rule.
+export { testSealKeyEnv } from './test-seal-key';
 export type {
   E2eBody,
   E2eDriver,
   E2eFixtures,
+  E2eTestOptions,
   EvalCase,
   EvalOptions,
   LocatorLike,

package/src/island-dom.ts

@@ -224,6 +224,11 @@ export class FakeElement extends FakeNode {
   /** Properties, not attributes: Solid assigns both of these straight onto the node. */
   value = '';
   checked = false;
+  /** The constraint API's message: `@ultimat3/ui`'s SearchableSelect refuses a required submit. */
+  validationMessage = '';
+  setCustomValidity(message: string): void {
+    this.validationMessage = String(message);
+  }
   constructor(readonly tagName: string) {
     super();
   }

package/src/isolated-plugins.ts

@@ -13,7 +13,7 @@ import { afterAll } from 'bun:test';
 export const ISOLATED_ENV = 'ULTIMATE_TEST_ISOLATED';
 
 /**
- * `Bun.plugin.clearAll()` after each file, isolated runs only. Measured on notificado.co's unit
+ * `Bun.plugin.clearAll()` after each file, isolated runs only. Measured on one adopter's unit
  * suite (652 files, 18 workers): per-worker peak 2.1–2.3 GB → 1.0–1.5 GB, total ~30 GB → 18 GB. The
  * next file's preload registers the plugins again, so every file still gets them.
  *

package/src/job-crash-proof.ts

@@ -0,0 +1,249 @@
+// `crashProof(handle, input)`: one clean run, then one run killed at each boundary the clean run
+// crossed — every step write landing, every settle — and one more where that write's answer is
+// lost. Judged by the effect log: a killed run that makes an effect more often than the clean one
+// is `X_JOB_CRASH_DIVERGED`; a lost answer rerunning a step is at-least-once, reported, never red.
+
+import type { Ctx } from '@ultimat3/core';
+import { finiteCount } from '@ultimat3/core';
+import type { JobHandle } from '@ultimat3/jobs';
+import { COMPENSATE_PREFIX, UNWINDING_STEP } from '@ultimat3/jobs';
+import { advanceClock, frozenNow } from './determinism';
+import type { SimDecision, SimOp } from './job-sim-driver';
+import { SEND_AND_ANSWER } from './job-sim-driver';
+import type { SimEffect } from './job-sim-effects';
+import { effectCounts } from './job-sim-effects';
+import { JobCrashDivergedError } from './job-sim-errors';
+import type { SimWorld } from './job-sim-world';
+import { openSimWorld } from './job-sim-world';
+
+export interface CrashBoundary {
+  /** `charge`, `charge (started)`, `sleep:1h (sleeping)`, `unwinding`, `compensate:charge`, `ack`. */
+  readonly at: string;
+  /** `forced-fail`: the run of a `compensates: true` job made to fail for good, then unwound. */
+  readonly mode: 'clean' | 'forced-fail';
+  /** The row's state once the killed run settled: `done`, `dead`, … */
+  readonly state: string;
+  /** The `X_*` code the row ended on, when it ended on one — `X_STEP_OUTCOME_UNKNOWN` after a kill inside `once`. */
+  readonly code?: string;
+}
+
+export interface CrashDivergence {
+  readonly boundary: string;
+  readonly mode: CrashBoundary['mode'];
+  readonly effect: string;
+  readonly clean: number;
+  readonly killed: number;
+  readonly error: JobCrashDivergedError;
+}
+
+/** A lost answer that made something run again: expected, since no framework can prevent it. */
+export interface CrashRerun {
+  readonly boundary: string;
+  readonly effect: string;
+  readonly clean: number;
+  readonly rerun: number;
+}
+
+export interface CrashReport {
+  readonly boundaries: readonly CrashBoundary[];
+  readonly divergences: readonly CrashDivergence[];
+  readonly reruns: readonly CrashRerun[];
+}
+
+export interface CrashProofOptions {
+  /** What the workers run bodies under. Default: an anonymous worker. */
+  readonly context?: () => Ctx;
+  /** Seeds `Math.random` for every run. Default 1. */
+  readonly seed?: number;
+}
+
+/** A drain that has not settled in this many passes is a job that never settles (a long wait). */
+const MAX_ROUNDS = 100;
+
+/** What one run is told to do at the n-th boundary event of the job under proof. */
+interface Plan {
+  readonly at?: number;
+  readonly fault?: 'kill' | 'lose';
+  /** Every forward ack dies: the run fails for good on its final attempt and unwinds. */
+  readonly forceFail: boolean;
+}
+
+interface Ran {
+  readonly boundaries: readonly string[];
+  readonly effects: readonly SimEffect[];
+  readonly compensated: readonly string[];
+  /** Forward steps that completed: what a compensator may undo. */
+  readonly forward: ReadonlySet<string>;
+  /** The row's state once the run settled. */
+  readonly settled: string;
+  readonly code?: string;
+}
+
+const labelOf = (op: SimOp): string =>
+  op.call !== 'put'
+    ? op.call
+    : op.status === 'completed'
+      ? (op.step ?? 'put')
+      : `${op.step ?? 'put'} (${op.status ?? '?'})`;
+
+async function drive(world: SimWorld): Promise<void> {
+  let n = 1;
+  for (let round = 0; round < MAX_ROUNDS; round += 1) {
+    const worker = `w${n}`;
+    const ran = await world.tick(worker);
+    // A dead process is replaced; the lease it held lapses below, and the next worker claims it.
+    if (world.sim.isDead(worker)) n += 1;
+    if (ran.length > 0) continue;
+    const due = await world.nextDue();
+    if (due === undefined) return;
+    advanceClock(Math.max(1, due - frozenNow().getTime()));
+  }
+}
+
+async function runOnce<I>(
+  handle: JobHandle<I>,
+  input: I,
+  plan: Plan,
+  options: CrashProofOptions,
+): Promise<Ran> {
+  const ids = { job: '', run: '' };
+  const boundaries: string[] = [];
+  const compensated: string[] = [];
+  const forward = new Set<string>();
+  const isOwn = (op: SimOp): boolean =>
+    op.call === 'put'
+      ? op.runId === ids.run
+      : (op.call === 'ack' || op.call === 'nack') && op.jobId === ids.job;
+  const decide = (op: SimOp): SimDecision => {
+    if (!isOwn(op)) return SEND_AND_ANSWER;
+    if (plan.forceFail && op.call === 'ack') return { before: 'kill', after: 'answer' };
+    boundaries.push(labelOf(op));
+    if (boundaries.length !== plan.at || plan.fault === undefined) return SEND_AND_ANSWER;
+    // A step write lands and then the worker dies; a settle dies before it is sent.
+    if (plan.fault === 'lose') return { before: 'send', after: 'lose' };
+    return op.call === 'put'
+      ? { before: 'send', after: 'kill' }
+      : { before: 'kill', after: 'answer' };
+  };
+  const landed = (op: SimOp): void => {
+    if (!isOwn(op) || op.call !== 'put' || op.status !== 'completed' || op.step === undefined) {
+      return;
+    }
+    if (op.step.startsWith(COMPENSATE_PREFIX)) compensated.push(op.step);
+    else if (op.step !== UNWINDING_STEP) forward.add(op.step);
+  };
+  await using world = await openSimWorld({
+    seed: finiteCount('crashProof', 'seed', options.seed ?? 1),
+    decide,
+    landed,
+    ...(options.context === undefined ? {} : { context: options.context }),
+  });
+  const queued = await world.enqueue(handle, input);
+  ids.job = queued.id;
+  ids.run = queued.runId;
+  await drive(world);
+  const row = (await world.rows()).find((one) => one.id === queued.id);
+  const code = /\b(X_[A-Z0-9_]+)\b/.exec(row?.lastError ?? '')?.[1];
+  return {
+    boundaries,
+    effects: world.effects(),
+    compensated,
+    forward,
+    settled: row?.state ?? 'gone',
+    ...(code === undefined ? {} : { code }),
+  };
+}
+
+/**
+ * Effects the killed run made more often than the reference — or less often, when both ended alike
+ * and neither unwound. An unwound run is also held to the reference's compensators: each once, last
+ * in first out, for exactly the forward steps that completed in it.
+ */
+function compare(reference: Ran, killed: Ran): readonly [string, number, number][] {
+  const before = effectCounts(reference.effects);
+  const after = effectCounts(killed.effects);
+  const unwound = reference.compensated.length > 0 || killed.compensated.length > 0;
+  const alike = killed.settled === reference.settled && !unwound;
+  const keys = [...new Set([...before.keys(), ...after.keys()])].sort();
+  const out: [string, number, number][] = [];
+  for (const key of keys) {
+    const c = before.get(key) ?? 0;
+    const k = after.get(key) ?? 0;
+    if (k > c || (k < c && alike)) out.push([key, c, k]);
+  }
+  if (unwound) {
+    const expected = reference.compensated.filter((name) =>
+      killed.forward.has(name.slice(COMPENSATE_PREFIX.length)),
+    );
+    const order = (list: readonly string[]): string => list.join(' → ') || 'none';
+    if (order(killed.compensated) !== order(expected)) {
+      out.push([`compensators ${order(killed.compensated)}, not ${order(expected)}`, 0, 1]);
+    }
+  }
+  return out;
+}
+
+export async function crashProof<I>(
+  handle: JobHandle<I>,
+  input: I,
+  options: CrashProofOptions = {},
+): Promise<CrashReport> {
+  const boundaries: CrashBoundary[] = [];
+  const divergences: CrashDivergence[] = [];
+  const reruns: CrashRerun[] = [];
+  const modes: readonly CrashBoundary['mode'][] = handle.compensates
+    ? ['clean', 'forced-fail']
+    : ['clean'];
+  // A kill on the final attempt of a compensating job unwinds it: that run is held to the run
+  // forced to fail for good, never to the clean one it no longer resembles.
+  const failed = handle.compensates
+    ? await runOnce(handle, input, { forceFail: true }, options)
+    : undefined;
+  for (const mode of modes) {
+    const forceFail = mode === 'forced-fail';
+    const clean =
+      forceFail && failed !== undefined
+        ? failed
+        : await runOnce(handle, input, { forceFail }, options);
+    const afterOf = (key: string): string | undefined =>
+      clean.effects.find((effect) => effect.key === key)?.after;
+    for (let at = 1; at <= clean.boundaries.length; at += 1) {
+      const label = clean.boundaries[at - 1] ?? '?';
+      const killed = await runOnce(handle, input, { at, fault: 'kill', forceFail }, options);
+      boundaries.push({
+        at: label,
+        mode,
+        state: killed.settled,
+        ...(killed.code === undefined ? {} : { code: killed.code }),
+      });
+      const reference =
+        failed !== undefined && killed.compensated.length > 0 && clean.compensated.length === 0
+          ? failed
+          : clean;
+      for (const [effect, c, k] of compare(reference, killed)) {
+        const after = afterOf(effect);
+        divergences.push({
+          boundary: label,
+          mode,
+          effect,
+          clean: c,
+          killed: k,
+          error: new JobCrashDivergedError({
+            job: handle.name,
+            boundary: label,
+            effect,
+            clean: c,
+            killed: k,
+            ...(after === undefined ? {} : { after }),
+          }),
+        });
+      }
+      if (forceFail) continue;
+      const lost = await runOnce(handle, input, { at, fault: 'lose', forceFail }, options);
+      for (const [effect, c, k] of compare(clean, lost)) {
+        if (k > c) reruns.push({ boundary: label, effect, clean: c, rerun: k });
+      }
+    }
+  }
+  return { boundaries, divergences, reruns };
+}

package/src/job-sim-driver.ts

@@ -0,0 +1,164 @@
+// One real `memoryJobDriver`, seen by each simulated worker through its own wrapper: every queue
+// and step-store call waits at a yield point first, and a fault decided there lands. After a kill
+// every call from that worker rejects and lands nothing; an answer lost has landed and still
+// rejects. The rejection is the one a real driver raises for a dead connection (`X_DB_UNAVAILABLE`).
+
+import { dbUnavailable } from '@ultimat3/db';
+import type {
+  ClaimedJob,
+  EnqueueRequest,
+  EnqueueResult,
+  JobDriver,
+  MemoryJobDriver,
+  StepRecord,
+  StepStore,
+} from '@ultimat3/jobs';
+
+/** Every call a worker makes through its view. `put` is the step store's write. */
+export type SimCall =
+  | 'claim'
+  | 'ack'
+  | 'nack'
+  | 'heartbeat'
+  | 'enqueue'
+  | 'enqueueMany'
+  | 'put'
+  | 'get'
+  | 'list'
+  | 'del'
+  | 'clear';
+
+export interface SimOp {
+  readonly worker: string;
+  readonly call: SimCall;
+  /** The row the call names: absent on `claim` and on an enqueue. */
+  readonly jobId?: string;
+  readonly runId?: string;
+  /** A step-store call's step, and on a `put` the status it writes. */
+  readonly step?: string;
+  readonly status?: StepRecord['status'];
+  /** An enqueue's job names, one per request. */
+  readonly names?: readonly string[];
+}
+
+/** What happens to one call: `before` decides if it is sent, `after` what its caller hears. */
+export interface SimDecision {
+  readonly before: 'send' | 'kill';
+  readonly after: 'answer' | 'kill' | 'lose';
+}
+
+export const SEND_AND_ANSWER: SimDecision = { before: 'send', after: 'answer' };
+
+export interface SimHooks {
+  /** Awaited before every call: the scheduler's yield point and the fault schedule's. */
+  decide(op: SimOp): SimDecision | Promise<SimDecision>;
+  /** A landed call, before its caller hears — what the effect log and the trace read. */
+  landed?(op: SimOp, answer: unknown): void;
+}
+
+export interface SimDriver {
+  readonly base: MemoryJobDriver;
+  /** The driver one worker holds. Same object for the same id. */
+  viewFor(worker: string): JobDriver;
+  kill(worker: string): void;
+  isDead(worker: string): boolean;
+}
+
+/** Every rejection this file made, so a caller can tell a planted fault from a real failure. */
+const planted = new WeakSet<object>();
+
+const fault = (detail: string) => {
+  const error = dbUnavailable(detail);
+  planted.add(error);
+  return error;
+};
+
+/** The value was raised by a simulated fault, never by the code under test. */
+export const isSimFault = (value: unknown): boolean =>
+  typeof value === 'object' && value !== null && planted.has(value);
+
+const dead = (worker: string) =>
+  fault(`the simulated worker "${worker}" died: its connection to the queue is gone`);
+
+const lost = (op: SimOp) =>
+  fault(`the answer to ${op.call} from simulated worker "${op.worker}" was lost after it landed`);
+
+export function simDriver(base: MemoryJobDriver, hooks: SimHooks): SimDriver {
+  const killed = new Set<string>();
+  const views = new Map<string, JobDriver>();
+
+  /** One call, through the yield point, the death check and the decided fault. */
+  const call = async <T>(op: SimOp, send: () => Promise<T>): Promise<T> => {
+    if (killed.has(op.worker)) throw dead(op.worker);
+    const decision = await hooks.decide(op);
+    // Killed while parked at the yield: a dead process sends nothing it had not yet sent.
+    if (killed.has(op.worker) || decision.before === 'kill') {
+      killed.add(op.worker);
+      throw dead(op.worker);
+    }
+    const answer = await send();
+    hooks.landed?.(op, answer);
+    if (decision.after === 'kill') {
+      killed.add(op.worker);
+      throw dead(op.worker);
+    }
+    if (decision.after === 'lose') throw lost(op);
+    return answer;
+  };
+
+  const stepsFor = (worker: string): StepStore => ({
+    get: (runId, name) =>
+      call({ worker, call: 'get', runId, step: name }, () => base.steps.get(runId, name)),
+    put: (record, by) =>
+      call(
+        {
+          worker,
+          call: 'put',
+          runId: record.runId,
+          step: record.name,
+          status: record.status,
+          ...(by === undefined ? {} : { jobId: by.jobId }),
+        },
+        () => base.steps.put(record, by),
+      ),
+    list: (runId) => call({ worker, call: 'list', runId }, () => base.steps.list(runId)),
+    del: (runId, name) =>
+      call({ worker, call: 'del', runId, step: name }, () => base.steps.del(runId, name)),
+    clear: (runId) => call({ worker, call: 'clear', runId }, () => base.steps.clear(runId)),
+  });
+
+  const viewOf = (worker: string): JobDriver => ({
+    ...base,
+    name: `sim:${worker}`,
+    steps: stepsFor(worker),
+    enqueue: (request: EnqueueRequest): Promise<EnqueueResult> =>
+      call({ worker, call: 'enqueue', names: [request.name] }, () => base.enqueue(request)),
+    enqueueMany: (requests) =>
+      call({ worker, call: 'enqueueMany', names: requests.map((one) => one.name) }, () =>
+        base.enqueueMany(requests),
+      ),
+    claim: (options): Promise<readonly ClaimedJob[]> =>
+      call({ worker, call: 'claim' }, () => base.claim({ ...options, workerId: worker })),
+    ack: (jobId, by) => call({ worker, call: 'ack', jobId }, () => base.ack(jobId, by)),
+    nack: (jobId, options) =>
+      call({ worker, call: 'nack', jobId }, () => base.nack(jobId, options)),
+    heartbeat: (jobId, options) =>
+      call({ worker, call: 'heartbeat', jobId }, () => base.heartbeat(jobId, options)),
+    // Every worker's teardown would close the ONE shared driver; the world closes it once.
+    close: () => Promise.resolve(),
+  });
+
+  return {
+    base,
+    viewFor(worker) {
+      let view = views.get(worker);
+      if (view === undefined) {
+        view = viewOf(worker);
+        views.set(worker, view);
+      }
+      return view;
+    },
+    kill: (worker) => killed.add(worker),
+    isDead: (worker) => killed.has(worker),
+  };
+}