@botiverse/k-carrier 0.1.0

package/harness/src/scenario/sandbox.ts

@@ -0,0 +1,259 @@
+/**
+ * scenario sandbox (harness-design §1.3) — one scenario, one sandbox.
+ *
+ * Each sandbox owns:
+ *  - a fresh temp stateDir (mkdtemp) — install dir, stateDir, and the
+ *    fake-server's release store all live INSIDE it, so teardown =
+ *    delete the sandbox (harness-design §1.77 "沙箱边界即清场边界");
+ *  - an independently allocated localhost port, unique among live
+ *    sandboxes, so parallel scenarios never collide;
+ *  - a marker file carrying the sandbox id, so the future fake-host
+ *    daemon's teardown half can pgrep by marker ("按沙箱标记 pgrep 复核
+ *    零残留" — verify-dead; that half lands with the daemon, this is the
+ *    skeleton it plugs into).
+ *
+ * teardown() currently deletes the sandbox tree; the process-tree
+ * verify-dead step is a documented no-op stub until fake-host daemon
+ * exists (the process-tree verify-dead half lands once the fake-host daemon is in place).
+ */
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createServer } from "node:net";
+import { spawn } from "node:child_process";
+import assert from "node:assert/strict";
+import { processAlive } from "../fake-host/daemon.ts";
+import { findPidsByMarkerToken } from "./processScan.ts";
+import { type ToothContext } from "../teeth/registry.ts";
+
+/**
+ * The sandbox marker: processes spawned inside a sandbox carry the literal
+ * token `K_SANDBOX_MARKER=<sandbox id>` on TWO channels at once —
+ *
+ *   env    (`envMarker()`)  observable via `ps e` on POSIX, even for
+ *                           orphans whose parent died;
+ *   argv   (`argvMarker()`) observable in the command line everywhere:
+ *                           `ps` shows argv on POSIX, and Windows exposes
+ *                           `Win32_Process.CommandLine` — its ONLY public
+ *                           out-of-band channel (other processes' env
+ *                           blocks are not readable without NT internals).
+ *
+ * One token, two carriers: the scanner greps for the same literal string on
+ * every platform, only the enumeration command forks (harness-design §1.77:
+ * "按沙箱标记 pgrep 复核零残留").
+ */
+export const MARKER_ENV = "K_SANDBOX_MARKER";
+
+export interface Sandbox {
+  /** Unique temp dir (mkdtemp); the scenario's entire world. */
+  readonly dir: string;
+  /** Port reserved for this sandbox's fake-server. */
+  readonly port: number;
+  /** Sandbox marker file content (the pgrep-by-marker key). */
+  readonly id: string;
+  /** The env var a spawned process needs to be claimable by this sandbox. */
+  envMarker(): Record<string, string>;
+  /** The argv token making the marker command-line-visible (Windows' only
+   *  public out-of-band channel; harmless trailing arg elsewhere). */
+  argvMarker(): string[];
+  /** Delete the sandbox tree; idempotent. */
+  teardown(): Promise<void>;
+}
+
+export interface SandboxOptions {
+  /** Prefix for the mkdtemp dir name. Default: "scenario". */
+  prefix?: string;
+  /** Parent dir for the sandbox. Default: os.tmpdir(). */
+  baseDir?: string;
+}
+
+/** Ports currently reserved by live sandboxes (distinctness guarantee). */
+const reservedPorts = new Set<number>();
+
+/**
+ * Allocate a free localhost port, unique among live sandboxes.
+ * Binds 127.0.0.1:0, reads the OS-assigned port, closes, reserves it.
+ * (The probe-close-bind window is the standard tradeoff; the reservation
+ * set removes the practical parallel-collision case.)
+ */
+export async function allocatePort(): Promise<number> {
+  for (;;) {
+    const port = await probeFreePort();
+    if (reservedPorts.has(port)) continue; // recently handed out; avoid reuse
+    reservedPorts.add(port);
+    return port;
+  }
+}
+
+function probeFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const s = createServer();
+    s.once("error", reject);
+    s.listen(0, "127.0.0.1", () => {
+      const addr = s.address();
+      s.close(() => {
+        if (addr && typeof addr === "object") resolve(addr.port);
+        else reject(new Error("allocatePort: no port assigned"));
+      });
+    });
+  });
+}
+
+export async function createSandbox(opts: SandboxOptions = {}): Promise<Sandbox> {
+  const baseDir = opts.baseDir ?? os.tmpdir();
+  const prefix = opts.prefix ?? "scenario";
+  const dir = await fs.mkdtemp(path.join(baseDir, `${SANDBOX_DIR_PREFIX}${prefix}-`));
+  const id = path.basename(dir);
+  const port = await allocatePort();
+  // Marker file: future fake-host daemon teardown pgrep's by this id to
+  // verify zero residual processes (harness-design §1.77).
+  await fs.writeFile(path.join(dir, ".k-sandbox-marker"), `${id}\n`);
+
+  let tornDown = false;
+  const teardown = async (): Promise<void> => {
+    if (tornDown) return;
+    await verifyProcessTreeDead(dir, id); // throws on residuals; dir kept as evidence
+    await fs.rm(dir, { recursive: true, force: true });
+    reservedPorts.delete(port);
+    tornDown = true;
+  };
+
+  return {
+    dir,
+    port,
+    id,
+    envMarker: () => ({ [MARKER_ENV]: id }),
+    argvMarker: () => [`${MARKER_ENV}=${id}`],
+    teardown,
+  };
+}
+
+/** Prefix every sandbox directory name carries (see createSandbox). */
+const SANDBOX_DIR_PREFIX = "k-harness-";
+
+/**
+ * The marker a process must carry to be found by this sandbox's teardown.
+ *
+ * Teeth often derive a NESTED context (e.g. `<sandbox>/respawn` per host
+ * shape). Taking basename() of that nested dir yields "respawn", which no
+ * teardown scan will ever match -- so the scan returns zero, the tooth reports
+ * a clean teardown, and the leaked process is still running. The zero means
+ * "the query matched nothing", not "nothing leaked". (Found 08-05 by looking
+ * for the surviving pid instead of trusting the count.)
+ *
+ * So the marker is always resolved back to the SANDBOX's own id, however deep
+ * the caller's context is nested.
+ */
+export function sandboxMarkerFor(dir: string): string {
+  for (let cur = path.resolve(dir); ; cur = path.dirname(cur)) {
+    const base = path.basename(cur);
+    if (base.startsWith(SANDBOX_DIR_PREFIX)) return base;
+    if (path.dirname(cur) === cur) return path.basename(path.resolve(dir));
+  }
+}
+
+export { findPidsByMarkerToken };
+
+/** Typed teardown failure: residual processes survived the kill+verify. */
+export class VerifyDeadError extends Error {
+  readonly code = "SANDBOX_VERIFY_DEAD";
+  readonly survivors: number[];
+
+  constructor(survivors: number[]) {
+    super(`SANDBOX_VERIFY_DEAD: ${survivors.length} process(es) still alive after teardown kill: ${survivors.join(", ")}`);
+    this.name = "VerifyDeadError";
+    this.survivors = survivors;
+  }
+}
+
+const KILL_GRACE_MS = 2000;
+const POLL_MS = 10;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => {
+    setTimeout(r, ms);
+  });
+}
+
+/**
+ * Process-tree verify-dead — the teardown half that proves "发了 kill"≠
+ * "死了" (zombie `__service` was a real production lesson): scan for every
+ * process carrying this sandbox's marker, SIGKILL them, then make the OS
+ * confirm each is gone. Any survivor raises a typed VerifyDeadError and
+ * the sandbox dir is kept as evidence (the teardown did NOT succeed).
+ */
+export async function verifyProcessTreeDead(_sandboxDir: string, markerId: string): Promise<void> {
+  const alive = findPidsByMarkerToken(MARKER_ENV, markerId);
+  if (alive.length === 0) return;
+  for (const pid of alive) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // already gone between the scan and the signal
+    }
+  }
+  const survivors: number[] = [];
+  const deadline = Date.now() + KILL_GRACE_MS;
+  for (const pid of alive) {
+    while (processAlive(pid)) {
+      if (Date.now() > deadline) {
+        survivors.push(pid);
+        break;
+      }
+      await sleep(POLL_MS);
+    }
+  }
+  if (survivors.length > 0) throw new VerifyDeadError(survivors);
+}
+
+/**
+ * The sandbox verify-dead tooth check (registered as
+ * scenario.sandbox-verify-dead): a process carrying the sandbox marker
+ * must be SIGKILLed and OS-confirmed gone by teardown ("发了 kill"≠"死
+ * 了"). `skipTeardownKill` simulates the must-red mutation (teardown's
+ * kill/verify is a no-op) for known-red driving.
+ */
+export async function checkSandboxVerifyDead(
+  ctx: ToothContext,
+  opts: { skipTeardownKill?: boolean } = {},
+): Promise<void> {
+  const sb = await createSandbox({ prefix: "verify-dead", baseDir: ctx.sandboxDir });
+  // Marker on both channels: env (POSIX ps e) + argv (the command-line token
+  // Windows' CIM scan needs; node ignores args after the -e script).
+  const child = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)", ...sb.argvMarker()], {
+    env: { ...process.env, ...sb.envMarker() },
+    stdio: "ignore", // no pipes: a failed assertion must not degrade into a hang
+  });
+  try {
+    await waitForMarker(sb.id);
+    if (opts.skipTeardownKill) {
+      // mutation: teardown's kill/verify never ran — the marker process is
+      // still alive, and the zero-residual assertion must go RED
+      assert.deepEqual(
+        findPidsByMarkerToken(MARKER_ENV, sb.id),
+        [],
+        "after teardown no marker processes may remain (kill step skipped => RED)",
+      );
+      return;
+    }
+    await sb.teardown();
+    assert.ok(!processAlive(child.pid ?? -1), "teardown must kill the marker process");
+    assert.deepEqual(
+      findPidsByMarkerToken(MARKER_ENV, sb.id),
+      [],
+      "no marker processes may remain after teardown",
+    );
+    await assert.rejects(fs.access(sb.dir), "teardown must remove the sandbox dir");
+  } finally {
+    if (processAlive(child.pid ?? -1)) child.kill("SIGKILL");
+    await sb.teardown().catch(() => {});
+  }
+}
+
+async function waitForMarker(markerId: string): Promise<void> {
+  const deadline = Date.now() + 2000;
+  while (findPidsByMarkerToken(MARKER_ENV, markerId).length === 0) {
+    if (Date.now() > deadline) throw new Error(`marker process ${markerId} never became visible`);
+    await sleep(20);
+  }
+}

package/harness/src/scenario/virtualClock.ts

@@ -0,0 +1,56 @@
+/**
+ * VirtualClock — deterministic Clock for scenarios (harness-design §1.3).
+ * Time moves only via advance(); timers fire in due-time order (FIFO among
+ * equals), and timers scheduled by fired callbacks within the advanced
+ * window fire in the same advance() call. No real sleeping anywhere.
+ */
+import type { Clock } from "../../../core/src/clock.ts";
+
+interface PendingTimer {
+  dueMs: number;
+  seq: number;
+  fn: () => void;
+  cancelled: boolean;
+}
+
+export class VirtualClock implements Clock {
+  private currentMs = 0;
+  private seq = 0;
+  private timers: PendingTimer[] = [];
+
+  nowMs(): number {
+    return this.currentMs;
+  }
+
+  after(ms: number, fn: () => void): () => void {
+    const t: PendingTimer = {
+      dueMs: this.currentMs + Math.max(0, ms),
+      seq: this.seq++,
+      fn,
+      cancelled: false,
+    };
+    this.timers.push(t);
+    return () => {
+      t.cancelled = true;
+    };
+  }
+
+  /** Advance virtual time, firing due timers in (dueMs, seq) order. */
+  advance(ms: number): void {
+    const target = this.currentMs + Math.max(0, ms);
+    for (;;) {
+      const due = this.timers
+        .filter((t) => !t.cancelled && t.dueMs <= target)
+        .toSorted((a, b) => a.dueMs - b.dueMs || a.seq - b.seq)[0];
+      if (!due) break;
+      this.timers = this.timers.filter((t) => t !== due);
+      this.currentMs = due.dueMs;
+      due.fn(); // may schedule more timers within the window
+    }
+    this.currentMs = target;
+  }
+
+  pendingCount(): number {
+    return this.timers.filter((t) => !t.cancelled).length;
+  }
+}

package/harness/src/selfverify/selfVerify.ts

@@ -0,0 +1,136 @@
+/**
+ * Harness self-verification — M0's exit gate (harness-design §1.6).
+ *
+ * The harness must prove it can judge before it is allowed to judge anything.
+ * Three samples, all required:
+ *
+ *   known-green    a correct world must pass          (no false alarms)
+ *   known-red      a seeded defect must be caught     (it detects at all)
+ *   adversarial    a world that satisfies the CHECKS while violating the
+ *                  real oracle must STILL be caught   (it detects what the
+ *                  author did not think to check)
+ *
+ * The third is the one that matters. Anyone can write a checker that passes
+ * its own examples; the question is whether it survives something built
+ * specifically to slip through it. Escapes found in the wild get added here
+ * permanently, so the suite only ever gets harder.
+ */
+import {
+  checkInvariants,
+  workloadPreserved,
+  type Invariant,
+  type WorldSnapshot,
+} from "../../../core/src/invariants.ts";
+
+export type SampleVerdict = "caught" | "passed";
+
+export interface SelfVerifyOutcome {
+  knownGreen: SampleVerdict;
+  knownRed: SampleVerdict;
+  adversarial: SampleVerdict;
+  /** True only when all three behaved as required. */
+  qualified: boolean;
+  detail: string[];
+}
+
+function healthyWorld(): WorldSnapshot {
+  return {
+    phase: "promoted",
+    slots: { stable: "2.0.0", experiment: null },
+    liveProcesses: [{ slot: "stable", pid: 7, startId: "s-7", version: "2.0.0" }],
+    journalIntents: ["staged", "handing-over", "running-experiment", "readback", "promoted"],
+    workloadDigest: "ledger:42:abc",
+  };
+}
+
+/** A seeded defect the checks are explicitly designed to catch. */
+function defectiveWorld(): WorldSnapshot {
+  return {
+    ...healthyWorld(),
+    // promote completed but the experiment slot was never cleared
+    slots: { stable: "2.0.0", experiment: "2.0.0" },
+  };
+}
+
+/**
+ * The adversarial sample: a world engineered to satisfy every structural
+ * check while violating the real oracle.
+ *
+ * Here: the upgrade reports success, invariants about slots/journal/phase all
+ * hold, and exactly one process is live — but that process is the OLD binary
+ * (the new version never actually took over). Every "shape" check passes;
+ * only comparing the live process against the version that was promoted
+ * exposes it. This is the live-PID false-success family.
+ */
+function adversarialWorld(): WorldSnapshot {
+  return {
+    phase: "promoted",
+    slots: { stable: "2.0.0", experiment: null },
+    // EVERY structural check passes: one live process, its version matches
+    // the stable slot, journal complete, no leftover experiment slot.
+    liveProcesses: [{ slot: "stable", pid: 7, startId: "s-BEFORE", version: "2.0.0" }],
+    journalIntents: ["staged", "handing-over", "running-experiment", "readback", "promoted"],
+    workloadDigest: "ledger:42:abc",
+    // ...but this is the SAME incarnation that was live before the upgrade:
+    // the service never restarted; it merely reports the new version string.
+    priorIncarnationStartId: "s-BEFORE",
+  };
+}
+
+/**
+ * The oracle the adversarial sample violates: a promote means the service was
+ * actually restarted onto the new bytes. A version STRING can be reported by
+ * the old incarnation; only a fresh incarnation identity proves the restart.
+ * Registered as a first-class invariant so this escape can never reopen.
+ */
+export const promotedVersionIsLive: Invariant = {
+  id: "k.promoted-runs-a-fresh-incarnation",
+  description: "after promote, the live incarnation is not the one that preceded the upgrade",
+  // Conditional: we can only trust incarnation identity if the host's probe
+  // reports from the live process rather than from a file or cache.
+  assumes: ["probe-from-live-process"],
+  check: (s) => {
+    if (s.phase !== "promoted" || s.priorIncarnationStartId === undefined) return null;
+    const stale = s.liveProcesses.filter((p) => p.startId === s.priorIncarnationStartId);
+    return stale.length > 0
+      ? `promoted ${s.slots.stable} but the live incarnation (startId ${s.priorIncarnationStartId}) is the pre-upgrade one — it reports the new version without having restarted`
+      : null;
+  },
+};
+
+export function runSelfVerification(invariants: readonly Invariant[]): SelfVerifyOutcome {
+  const detail: string[] = [];
+
+  const greenViolations = checkInvariants(healthyWorld(), invariants);
+  const knownGreen: SampleVerdict = greenViolations.length === 0 ? "passed" : "caught";
+  if (knownGreen === "caught") {
+    detail.push(`known-green FALSE ALARM: ${greenViolations.map((v) => v.invariantId).join(", ")}`);
+  }
+
+  const redViolations = checkInvariants(defectiveWorld(), invariants);
+  const knownRed: SampleVerdict = redViolations.length > 0 ? "caught" : "passed";
+  if (knownRed === "passed") detail.push("known-red ESCAPED: seeded defect went undetected");
+
+  const advViolations = checkInvariants(adversarialWorld(), invariants);
+  const adversarial: SampleVerdict = advViolations.length > 0 ? "caught" : "passed";
+  if (adversarial === "passed") {
+    detail.push(
+      "adversarial ESCAPED: a world that satisfies every structural check while running the OLD binary was judged healthy",
+    );
+  }
+
+  // The workload oracle must also survive a faked-preservation attempt.
+  const fakedPreservation = workloadPreserved(healthyWorld(), {
+    ...healthyWorld(),
+    workloadDigest: "ledger:0:reset",
+  });
+  if (fakedPreservation === null) detail.push("workload oracle ESCAPED: digest change went unnoticed");
+
+  const qualified =
+    knownGreen === "passed" &&
+    knownRed === "caught" &&
+    adversarial === "caught" &&
+    fakedPreservation !== null;
+
+  return { knownGreen, knownRed, adversarial, qualified, detail };
+}

package/harness/src/sim/checks.ts

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import { SMOKE_SEEDS } from "./corpus.ts";
+import { replayBytes, runSimulation, runSimulationBatch } from "./run.ts";
+
+export async function checkSeedReplayIdentical(): Promise<void> {
+  const seed = 0xdecafbad;
+  const first = await runSimulation(seed);
+  const second = await runSimulation(seed);
+  assert.equal(replayBytes(first), replayBytes(second), "the same seed must replay byte-for-byte");
+
+  const other = await runSimulation(seed + 1);
+  assert.notEqual(
+    first.transcriptSha256,
+    other.transcriptSha256,
+    "different seeds must control a different observable schedule",
+  );
+}
+
+export async function checkSmokeSeeds(): Promise<void> {
+  const batch = await runSimulationBatch(SMOKE_SEEDS);
+  const failures = batch.results
+    .filter((result) => result.status === "fail")
+    .map((result) => `seed ${result.seed}: ${result.failure} (${result.replay})`);
+  assert.deepEqual(failures, [], failures.join("\n"));
+}
+
+export async function checkFaultSurfaceCovered(): Promise<void> {
+  const batch = await runSimulationBatch(SMOKE_SEEDS);
+  for (const decision of [
+    "delay",
+    "crash-before",
+    "crash-after",
+    "fail-before",
+    "partial-write",
+    "reorder-volatile",
+  ] as const) {
+    assert.ok(
+      batch.coverage[decision] > 0,
+      `fixed smoke corpus never exercised ${decision}; add a seed before claiming that surface`,
+    );
+  }
+  assert.ok(
+    batch.results.some((result) => result.restarts > 0),
+    "fixed smoke corpus must exercise recovery, not only clean upgrades",
+  );
+}

package/harness/src/sim/corpus.ts

@@ -0,0 +1,36 @@
+/** Fixed, reviewable PR corpus. Nightly runs use a much larger range. */
+export const SMOKE_SEEDS: readonly number[] = [
+  1,
+  2,
+  3,
+  5,
+  8,
+  13,
+  21,
+  34,
+  55,
+  89,
+  144,
+  233,
+  377,
+  610,
+  987,
+  1597,
+  2584,
+  4181,
+  6765,
+  10946,
+  0x12345678,
+  0x6a09e667,
+  0x9e3779b9,
+  0xffffffff,
+];
+
+export function sequentialSeeds(startSeed: number, count: number): number[] {
+  if (!Number.isSafeInteger(count) || count <= 0) {
+    throw new RangeError(`seed count must be a positive safe integer, got ${count}`);
+  }
+  if (count > 1_000_000) throw new RangeError(`seed count ${count} exceeds the 1000000 safety cap`);
+  const start = startSeed >>> 0;
+  return Array.from({ length: count }, (_unused, index) => (start + index) >>> 0);
+}

package/harness/src/sim/effectRuntime.ts

@@ -0,0 +1,113 @@
+import type { Clock } from "../../../core/src/clock.ts";
+import { SimulationError } from "./error.ts";
+import {
+  FaultScheduler,
+  type EffectKind,
+  type FaultCoverage,
+} from "./scheduler.ts";
+
+interface Timer {
+  id: number;
+  dueMs: number;
+  fn: () => void;
+  canceled: boolean;
+}
+
+export interface VolatileFaultHooks {
+  partial?: () => void;
+  reorder?: () => void;
+}
+
+/** Seeded scheduling and virtual time, separated from the simulated machine. */
+export class EffectRuntime {
+  readonly trace: string[] = [];
+  readonly clock: Clock;
+  private readonly scheduler: FaultScheduler;
+  private now = 1_000;
+  private nextTimerId = 1;
+  private readonly timers: Timer[] = [];
+  private effectNumber = 0;
+  private readonly assertInvariants: (name: string) => void;
+
+  constructor(seed: number, faults: boolean, assertInvariants: (name: string) => void) {
+    this.scheduler = new FaultScheduler(seed, faults);
+    this.assertInvariants = assertInvariants;
+    this.clock = {
+      nowMs: () => this.now,
+      after: (ms, fn) => {
+        const timer: Timer = {
+          id: this.nextTimerId++,
+          dueMs: this.now + ms,
+          fn,
+          canceled: false,
+        };
+        this.timers.push(timer);
+        return () => {
+          timer.canceled = true;
+        };
+      },
+    };
+  }
+
+  get coverage(): FaultCoverage {
+    return { ...this.scheduler.coverage };
+  }
+
+  async effect<T>(
+    name: string,
+    kind: EffectKind,
+    apply: () => T,
+    volatile: VolatileFaultHooks = {},
+  ): Promise<T> {
+    const decision = this.scheduler.decide(kind);
+    this.effectNumber += 1;
+    this.trace.push(`${this.effectNumber}:${name}:${decision}`);
+
+    if (decision === "delay") this.advance(this.scheduler.delayMs());
+    if (decision === "partial-write") {
+      volatile.partial?.();
+      this.assertInvariants(name);
+      throw new SimulationError("crash", name, `SIM_CRASH_PARTIAL: ${name}`);
+    }
+    if (decision === "reorder-volatile") {
+      volatile.reorder?.();
+      this.assertInvariants(name);
+      throw new SimulationError(
+        "effect-failure",
+        name,
+        `SIM_EFFECT_FAIL: ${name}: volatile journal fragments reordered before fsync`,
+      );
+    }
+    if (decision === "crash-before") {
+      this.assertInvariants(name);
+      throw new SimulationError("crash", name, `SIM_CRASH_BEFORE: ${name}`);
+    }
+    if (decision === "fail-before") {
+      this.assertInvariants(name);
+      throw new SimulationError("effect-failure", name, `SIM_EFFECT_FAIL: ${name}: injected failure`);
+    }
+
+    const result = apply();
+    this.assertInvariants(name);
+    if (decision === "crash-after") {
+      throw new SimulationError("crash", name, `SIM_CRASH_AFTER: ${name}`);
+    }
+    return result;
+  }
+
+  reboot(reason: string, volatileTail: string): void {
+    this.trace.push(`reboot:${reason}:drop-tail=${volatileTail}`);
+    for (const timer of this.timers) timer.canceled = true;
+  }
+
+  private advance(ms: number): void {
+    this.now += ms;
+    const due = this.timers
+      .filter((timer) => !timer.canceled && timer.dueMs <= this.now)
+      .toSorted((left, right) => left.dueMs - right.dueMs || left.id - right.id);
+    for (const timer of due) {
+      timer.canceled = true;
+      timer.fn();
+    }
+  }
+}

package/harness/src/sim/error.ts

@@ -0,0 +1,14 @@
+export type SimulationErrorKind = "crash" | "effect-failure" | "invariant";
+
+/** One typed failure family keeps the runner's recovery policy explicit. */
+export class SimulationError extends Error {
+  readonly kind: SimulationErrorKind;
+  readonly effectName: string;
+
+  constructor(kind: SimulationErrorKind, effectName: string, message: string) {
+    super(message);
+    this.name = "SimulationError";
+    this.kind = kind;
+    this.effectName = effectName;
+  }
+}

package/harness/src/sim/prng.ts

@@ -0,0 +1,29 @@
+/**
+ * Small, specified 32-bit PRNG for deterministic simulation.
+ *
+ * Mulberry32 is deliberately implemented here instead of depending on a
+ * package: the integer operations below are the replay format. A seed means
+ * the same fault schedule on every OS and every future invocation.
+ */
+export class SeededPrng {
+  private state: number;
+
+  constructor(seed: number) {
+    this.state = seed >>> 0;
+  }
+
+  nextUint32(): number {
+    this.state = (this.state + 0x6d2b79f5) >>> 0;
+    let value = this.state;
+    value = Math.imul(value ^ (value >>> 15), value | 1);
+    value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+    return (value ^ (value >>> 14)) >>> 0;
+  }
+
+  below(exclusiveUpperBound: number): number {
+    if (!Number.isSafeInteger(exclusiveUpperBound) || exclusiveUpperBound <= 0) {
+      throw new RangeError(`PRNG bound must be a positive safe integer, got ${exclusiveUpperBound}`);
+    }
+    return this.nextUint32() % exclusiveUpperBound;
+  }
+}