@minnowdb/core 0.6.9 → 0.7.1

package/dist/testing/simulator.js

@@ -3,592 +3,554 @@ import { MemoryBlockStore } from "../storage/index.js";
 import { FaultInjectingBlockStore } from "./index.js";
 import { md5Hex } from "./sqllogictest.js";
 async function collectStoragePages(read) {
-    const records = [];
-    let cursor = null;
-    for (;;) {
-        const page = await read(cursor);
-        records.push(...page.records);
-        if (page.nextCursor === null)
-            return records;
-        cursor = page.nextCursor;
-    }
+  const records = [];
+  let cursor = null;
+  for (; ; ) {
+    const page = await read(cursor);
+    records.push(...page.records);
+    if (page.nextCursor === null)
+      return records;
+    cursor = page.nextCursor;
+  }
 }
-/** Chooses every storage completion from a seeded queue and keeps only a bounded trace tail. */
-export class DeterministicScheduler {
-    #random;
-    #traceLimit;
-    #pending = [];
-    #trace = [];
-    #sequence = 0;
-    #highWater = 0;
-    constructor(seed, traceLimit = 256) {
-        if (!Number.isSafeInteger(traceLimit) || traceLimit < 0) {
-            throw new RangeError("Simulator trace limit must be a non-negative whole number");
-        }
-        this.#random = mulberry32(seed);
-        this.#traceLimit = traceLimit;
-    }
-    get highWater() {
-        return this.#highWater;
-    }
-    get trace() {
-        return this.#trace;
+class DeterministicScheduler {
+  #random;
+  #traceLimit;
+  #pending = [];
+  #trace = [];
+  #sequence = 0;
+  #highWater = 0;
+  constructor(seed, traceLimit = 256) {
+    if (!Number.isSafeInteger(traceLimit) || traceLimit < 0) {
+      throw new RangeError("Simulator trace limit must be a non-negative whole number");
     }
-    schedule(label, run) {
-        return new Promise((resolve, reject) => {
-            this.#pending.push({ label, run, resolve, reject });
-            this.#highWater = Math.max(this.#highWater, this.#pending.length);
-        });
-    }
-    async settle(promises) {
-        const state = { complete: false };
-        const settled = Promise.allSettled(promises).then((results) => {
-            state.complete = true;
-            return results;
-        });
-        let emptyTurns = 0;
-        while (!state.complete) {
-            await Promise.resolve();
-            const pending = this.#pending.length;
-            if (pending === 0) {
-                // Production maintenance deliberately yields through a timer between bounded pages.
-                // A microtask-only poll can therefore declare deadlock while the next scheduled store
-                // call is merely waiting for its event-loop turn. Let timers advance before counting an
-                // empty turn; the chosen storage completion order remains seeded and deterministic.
-                await nextEventLoopTurn();
-                if (this.#pending.length > 0) {
-                    emptyTurns = 0;
-                    continue;
-                }
-                emptyTurns++;
-                if (emptyTurns > 100) {
-                    throw new Error("Deterministic simulator deadlocked with no scheduled storage operation");
-                }
-                continue;
-            }
-            emptyTurns = 0;
-            const index = Math.floor(this.#random() * pending);
-            const operation = this.#pending.splice(index, 1)[0];
-            if (operation === undefined)
-                continue;
-            try {
-                const value = await operation.run();
-                operation.resolve(value);
-                this.#record(operation.label, "resolved");
-            }
-            catch (error) {
-                operation.reject(error);
-                this.#record(operation.label, "rejected");
-            }
+    this.#random = mulberry32(seed);
+    this.#traceLimit = traceLimit;
+  }
+  get highWater() {
+    return this.#highWater;
+  }
+  get trace() {
+    return this.#trace;
+  }
+  schedule(label, run) {
+    return new Promise((resolve, reject) => {
+      this.#pending.push({ label, run, resolve, reject });
+      this.#highWater = Math.max(this.#highWater, this.#pending.length);
+    });
+  }
+  async settle(promises) {
+    const state = { complete: false };
+    const settled = Promise.allSettled(promises).then((results) => {
+      state.complete = true;
+      return results;
+    });
+    let emptyTurns = 0;
+    while (!state.complete) {
+      await Promise.resolve();
+      const pending = this.#pending.length;
+      if (pending === 0) {
+        await nextEventLoopTurn();
+        if (this.#pending.length > 0) {
+          emptyTurns = 0;
+          continue;
         }
-        return settled;
-    }
-    #record(operation, outcome) {
-        this.#sequence++;
-        if (this.#traceLimit === 0)
-            return;
-        this.#trace.push({ sequence: this.#sequence, operation, outcome });
-        if (this.#trace.length > this.#traceLimit)
-            this.#trace.shift();
+        emptyTurns++;
+        if (emptyTurns > 100) {
+          throw new Error("Deterministic simulator deadlocked with no scheduled storage operation");
+        }
+        continue;
+      }
+      emptyTurns = 0;
+      const index = Math.floor(this.#random() * pending);
+      const operation = this.#pending.splice(index, 1)[0];
+      if (operation === void 0)
+        continue;
+      try {
+        const value = await operation.run();
+        operation.resolve(value);
+        this.#record(operation.label, "resolved");
+      } catch (error) {
+        operation.reject(error);
+        this.#record(operation.label, "rejected");
+      }
     }
+    return settled;
+  }
+  #record(operation, outcome) {
+    this.#sequence++;
+    if (this.#traceLimit === 0)
+      return;
+    this.#trace.push({ sequence: this.#sequence, operation, outcome });
+    if (this.#trace.length > this.#traceLimit)
+      this.#trace.shift();
+  }
 }
 function nextEventLoopTurn() {
-    if (typeof MessageChannel === "undefined") {
-        return new Promise((resolve) => setTimeout(resolve, 0));
-    }
-    return new Promise((resolve) => {
-        const channel = new MessageChannel();
-        channel.port1.onmessage = () => {
-            channel.port1.close();
-            channel.port2.close();
-            resolve();
-        };
-        channel.port2.postMessage(undefined);
-    });
-}
-/** Wraps every asynchronous BlockStore entry point in the deterministic completion scheduler. */
-export function scheduledBlockStore(store, scheduler) {
-    return new Proxy(store, {
-        get(target, property) {
-            const value = Reflect.get(target, property, target);
-            if (typeof value !== "function")
-                return value;
-            const method = value;
-            if (property === "close")
-                return (...arguments_) => method.apply(target, arguments_);
-            return (...arguments_) => scheduler.schedule(String(property), async () => method.apply(target, arguments_));
-        },
-    });
+  if (typeof MessageChannel === "undefined") {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+  }
+  return new Promise((resolve) => {
+    const channel = new MessageChannel();
+    channel.port1.onmessage = () => {
+      channel.port1.close();
+      channel.port2.close();
+      resolve();
+    };
+    channel.port2.postMessage(void 0);
+  });
 }
-export function generateSimulationPlan(seed, options = {}) {
-    if (!Number.isSafeInteger(seed)) {
-        throw new RangeError("Simulator seed must be a whole number");
-    }
-    const rounds = options.rounds ?? 48;
-    const clients = options.clients ?? 4;
-    const keySpace = options.keySpace ?? 32;
-    if (!Number.isSafeInteger(rounds) || rounds < 1 || rounds > 100_000) {
-        throw new RangeError("Simulator rounds must be between 1 and 100,000");
-    }
-    if (!Number.isSafeInteger(clients) || clients < 1 || clients > 32) {
-        throw new RangeError("Simulator clients must be between 1 and 32");
+function scheduledBlockStore(store, scheduler) {
+  return new Proxy(store, {
+    get(target, property) {
+      const value = Reflect.get(target, property, target);
+      if (typeof value !== "function")
+        return value;
+      const method = value;
+      if (property === "close")
+        return (...arguments_) => method.apply(target, arguments_);
+      return (...arguments_) => scheduler.schedule(String(property), async () => method.apply(target, arguments_));
     }
-    if (!Number.isSafeInteger(keySpace) || keySpace < 1 || keySpace > 10_000) {
-        throw new RangeError("Simulator key space must be between 1 and 10,000");
-    }
-    if (keySpace < clients) {
-        throw new RangeError("Simulator key space must be at least the client count");
+  });
+}
+function generateSimulationPlan(seed, options = {}) {
+  if (!Number.isSafeInteger(seed)) {
+    throw new RangeError("Simulator seed must be a whole number");
+  }
+  const rounds = options.rounds ?? 48;
+  const clients = options.clients ?? 4;
+  const keySpace = options.keySpace ?? 32;
+  if (!Number.isSafeInteger(rounds) || rounds < 1 || rounds > 1e5) {
+    throw new RangeError("Simulator rounds must be between 1 and 100,000");
+  }
+  if (!Number.isSafeInteger(clients) || clients < 1 || clients > 32) {
+    throw new RangeError("Simulator clients must be between 1 and 32");
+  }
+  if (!Number.isSafeInteger(keySpace) || keySpace < 1 || keySpace > 1e4) {
+    throw new RangeError("Simulator key space must be between 1 and 10,000");
+  }
+  if (keySpace < clients) {
+    throw new RangeError("Simulator key space must be at least the client count");
+  }
+  const random = mulberry32(seed);
+  const steps = [];
+  const faultPoints = [
+    "beforeBlockWrite",
+    "afterBlockWrite",
+    "beforeTransactionCommit",
+    "afterTransactionCommit"
+  ];
+  for (let round = 0; round < rounds; round++) {
+    const operations = [];
+    const start = Math.floor(random() * keySpace);
+    let stride = Math.floor(random() * keySpace) + 1;
+    while (greatestCommonDivisor(stride, keySpace) !== 1)
+      stride++;
+    for (let client = 0; client < clients; client++) {
+      const key = (start + client * stride) % keySpace + 1;
+      if (random() < 0.18)
+        operations.push({ kind: "delete", client, key });
+      else
+        operations.push({ kind: "put", client, key, amount: Math.floor(random() * 1e6) });
     }
-    const random = mulberry32(seed);
-    const steps = [];
-    const faultPoints = [
-        "beforeBlockWrite",
-        "afterBlockWrite",
-        "beforeTransactionCommit",
-        "afterTransactionCommit",
-    ];
-    for (let round = 0; round < rounds; round++) {
-        const operations = [];
-        const start = Math.floor(random() * keySpace);
-        let stride = Math.floor(random() * keySpace) + 1;
-        while (greatestCommonDivisor(stride, keySpace) !== 1)
-            stride++;
-        for (let client = 0; client < clients; client++) {
-            // A round is a genuinely concurrent commit race, but its row mutations commute. That gives
-            // the reference model one exact answer instead of guessing which same-key promise linearized
-            // last. Contention still happens at the shared manifest/transaction boundary.
-            const key = ((start + client * stride) % keySpace) + 1;
-            if (random() < 0.18)
-                operations.push({ kind: "delete", client, key });
-            else
-                operations.push({ kind: "put", client, key, amount: Math.floor(random() * 1_000_000) });
-        }
-        steps.push({ kind: "concurrent", operations });
-        if (round % 4 === 3)
-            steps.push({ kind: "checkpoint" });
-        if (round % 12 === 11)
-            steps.push({ kind: "maintenance" });
-        if (round % 20 === 19) {
-            const point = faultPoints[Math.floor(random() * faultPoints.length)] ?? "beforeBlockWrite";
-            steps.push({
-                kind: "fault",
-                point,
-                occurrence: 1,
-                operation: {
-                    kind: "put",
-                    client: Math.floor(random() * clients),
-                    key: Math.floor(random() * keySpace) + 1,
-                    amount: Math.floor(random() * 1_000_000),
-                },
-            });
+    steps.push({ kind: "concurrent", operations });
+    if (round % 4 === 3)
+      steps.push({ kind: "checkpoint" });
+    if (round % 12 === 11)
+      steps.push({ kind: "maintenance" });
+    if (round % 20 === 19) {
+      const point = faultPoints[Math.floor(random() * faultPoints.length)] ?? "beforeBlockWrite";
+      steps.push({
+        kind: "fault",
+        point,
+        occurrence: 1,
+        operation: {
+          kind: "put",
+          client: Math.floor(random() * clients),
+          key: Math.floor(random() * keySpace) + 1,
+          amount: Math.floor(random() * 1e6)
         }
+      });
     }
-    steps.push({ kind: "checkpoint" }, { kind: "maintenance" }, { kind: "checkpoint" });
-    return { version: 1, seed, clients, keySpace, steps };
+  }
+  steps.push({ kind: "checkpoint" }, { kind: "maintenance" }, { kind: "checkpoint" });
+  return { version: 1, seed, clients, keySpace, steps };
 }
-export function parseSimulationPlan(source) {
-    const value = JSON.parse(source);
-    if (typeof value !== "object" || value === null)
-        throw new TypeError("Simulation plan must be an object");
-    const plan = value;
-    if (plan.version !== 1)
-        throw new TypeError("Simulation plan version must be 1");
-    if (!Number.isSafeInteger(plan.seed))
-        throw new TypeError("Simulation seed must be a whole number");
-    if (!Number.isSafeInteger(plan.clients) || (plan.clients ?? 0) < 1 || (plan.clients ?? 0) > 32) {
-        throw new TypeError("Simulation client count is invalid");
-    }
-    if (!Number.isSafeInteger(plan.keySpace) ||
-        (plan.keySpace ?? 0) < 1 ||
-        (plan.keySpace ?? 0) > 10_000) {
-        throw new TypeError("Simulation key space is invalid");
-    }
-    if ((plan.keySpace ?? 0) < (plan.clients ?? 0)) {
-        throw new TypeError("Simulation key space must be at least the client count");
-    }
-    if (!Array.isArray(plan.steps) || plan.steps.length > 200_000) {
-        throw new TypeError("Simulation steps must be a bounded array");
-    }
-    validateSteps(plan.steps, plan.clients ?? 0, plan.keySpace ?? 0);
-    return plan;
+function parseSimulationPlan(source) {
+  const value = JSON.parse(source);
+  if (typeof value !== "object" || value === null)
+    throw new TypeError("Simulation plan must be an object");
+  const plan = value;
+  if (plan.version !== 1)
+    throw new TypeError("Simulation plan version must be 1");
+  if (!Number.isSafeInteger(plan.seed))
+    throw new TypeError("Simulation seed must be a whole number");
+  if (!Number.isSafeInteger(plan.clients) || (plan.clients ?? 0) < 1 || (plan.clients ?? 0) > 32) {
+    throw new TypeError("Simulation client count is invalid");
+  }
+  if (!Number.isSafeInteger(plan.keySpace) || (plan.keySpace ?? 0) < 1 || (plan.keySpace ?? 0) > 1e4) {
+    throw new TypeError("Simulation key space is invalid");
+  }
+  if ((plan.keySpace ?? 0) < (plan.clients ?? 0)) {
+    throw new TypeError("Simulation key space must be at least the client count");
+  }
+  if (!Array.isArray(plan.steps) || plan.steps.length > 2e5) {
+    throw new TypeError("Simulation steps must be a bounded array");
+  }
+  validateSteps(plan.steps, plan.clients ?? 0, plan.keySpace ?? 0);
+  return plan;
 }
-/** Runs a replayable state-machine plan through production SQL, transactions, and block storage. */
-export async function runSimulation(plan, options = {}) {
-    parseSimulationPlan(JSON.stringify(plan));
-    const base = new MemoryBlockStore();
-    const faults = new FaultController();
-    const scheduler = new DeterministicScheduler(plan.seed ^ 0x5f3759df, options.traceEvents ?? 256);
-    const store = scheduledBlockStore(new FaultInjectingBlockStore(base, (point) => faults.inject(point)), scheduler);
-    let clock = Date.parse("2026-01-01T00:00:00.000Z");
-    let id = 0;
-    const createDatabase = () => new MinnowDatabase(store, {
-        compression: "raw",
-        rowsPerBlock: 8,
-        maxCommitRetries: 16,
-        now: () => new Date(clock),
-        createId: () => `sim-${String(id++)}`,
-        bufferPoolBytes: 0,
-        autoCompact: false,
-        autoCollect: false,
-    });
-    const setup = createDatabase();
-    await drive(scheduler, setup.execute("CREATE TABLE items (id INTEGER PRIMARY KEY, client INTEGER NOT NULL, amount INTEGER NOT NULL)"));
-    await drive(scheduler, setup.close());
-    const clients = Array.from({ length: plan.clients }, createDatabase);
-    const model = new Map();
-    let acceptedMutations = 0;
-    let rejectedConflicts = 0;
-    let injectedFaults = 0;
-    let checkpoints = 0;
-    for (const step of plan.steps) {
-        clock += 1_000;
-        if (step.kind === "concurrent") {
-            const operations = step.operations.map((operation) => executeMutation(requireClient(clients, operation.client), operation)
-                .then(() => {
-                applyMutation(model, operation);
-                acceptedMutations++;
-            })
-                .catch((error) => {
-                if (/manifest changed|conflict/iu.test(errorMessage(error))) {
-                    rejectedConflicts++;
-                    return;
-                }
-                throw error;
-            }));
-            assertSettled(await scheduler.settle(operations));
-            continue;
+async function runSimulation(plan, options = {}) {
+  parseSimulationPlan(JSON.stringify(plan));
+  const base = new MemoryBlockStore();
+  const faults = new FaultController();
+  const scheduler = new DeterministicScheduler(plan.seed ^ 1597463007, options.traceEvents ?? 256);
+  const store = scheduledBlockStore(new FaultInjectingBlockStore(base, (point) => faults.inject(point)), scheduler);
+  let clock = Date.parse("2026-01-01T00:00:00.000Z");
+  let id = 0;
+  const createDatabase = () => new MinnowDatabase(store, {
+    compression: "raw",
+    rowsPerBlock: 8,
+    maxCommitRetries: 16,
+    now: () => new Date(clock),
+    createId: () => `sim-${String(id++)}`,
+    bufferPoolBytes: 0,
+    autoCompact: false,
+    autoCollect: false
+  });
+  const setup = createDatabase();
+  await drive(scheduler, setup.execute("CREATE TABLE items (id INTEGER PRIMARY KEY, client INTEGER NOT NULL, amount INTEGER NOT NULL)"));
+  await drive(scheduler, setup.close());
+  const clients = Array.from({ length: plan.clients }, createDatabase);
+  const model = /* @__PURE__ */ new Map();
+  let acceptedMutations = 0;
+  let rejectedConflicts = 0;
+  let injectedFaults = 0;
+  let checkpoints = 0;
+  for (const step of plan.steps) {
+    clock += 1e3;
+    if (step.kind === "concurrent") {
+      const operations = step.operations.map((operation) => executeMutation(requireClient(clients, operation.client), operation).then(() => {
+        applyMutation(model, operation);
+        acceptedMutations++;
+      }).catch((error) => {
+        if (/manifest changed|conflict/iu.test(errorMessage(error))) {
+          rejectedConflicts++;
+          return;
         }
-        if (step.kind === "checkpoint") {
-            await assertModel(scheduler, clients[0] ?? setup, model);
-            checkpoints++;
-            continue;
-        }
-        if (step.kind === "maintenance") {
-            const database = clients[0] ?? setup;
-            await drive(scheduler, database.compactTable("items"));
-            // One pass can remove obsolete manifests/segments while their transaction journals are
-            // still provenance roots. The next pass can reclaim those now-unreferenced journals.
-            await drive(scheduler, database.collectGarbage());
-            await drive(scheduler, database.collectGarbage());
-            continue;
-        }
-        const before = new Map(model);
-        const after = new Map(model);
-        applyMutation(after, step.operation);
-        faults.arm(step.point, step.occurrence);
-        const result = await scheduler.settle([
-            executeMutation(requireClient(clients, step.operation.client), step.operation),
-        ]);
-        if (!faults.fired)
-            throw new Error(`Simulation fault was not reached: ${step.point}`);
-        injectedFaults++;
-        faults.disarm();
-        const failedClient = requireClient(clients, step.operation.client);
-        await drive(scheduler, failedClient.close());
-        const replacement = createDatabase();
-        clients[step.operation.client] = replacement;
-        const actual = await readRows(scheduler, replacement);
-        if (sameRows(actual, before)) {
-            if (result[0]?.status === "fulfilled") {
-                throw new Error(`Fault ${step.point} returned success but did not persist its mutation`);
-            }
-            replaceModel(model, before);
-        }
-        else if (sameRows(actual, after))
-            replaceModel(model, after);
-        else
-            throw new Error(`Fault ${step.point} left a state that was neither before nor after the mutation`);
+        throw error;
+      }));
+      assertSettled(await scheduler.settle(operations));
+      continue;
     }
-    await assertModel(scheduler, clients[0] ?? setup, model);
-    const closeResults = await scheduler.settle(clients.map((client) => client.close()));
-    assertSettled(closeResults);
-    // Measure eventual storage after the simulated tabs release their deliberately cached reader
-    // leases. A fresh maintenance client can then collapse history without an artificial pin from
-    // the workload whose final state has already been checked.
-    const maintenance = createDatabase();
-    const compacted = await compactToFixedPoint(scheduler, maintenance, plan.steps.length);
-    const maintenanceCompactions = compacted.passes;
-    const compactionStop = compacted.stop;
-    const collected = await collectToFixedPoint(scheduler, maintenance, plan.steps.length);
-    let collectionPasses = collected.passes;
-    const collectionTail = [...collected.tail];
-    await assertModel(scheduler, maintenance, model);
-    await drive(scheduler, maintenance.close());
-    const sweeper = createDatabase();
-    const swept = await collectToFixedPoint(scheduler, sweeper, plan.steps.length);
-    collectionPasses += swept.passes;
-    collectionTail.push(...swept.tail);
-    if (collectionTail.length > 8)
-        collectionTail.splice(0, collectionTail.length - 8);
-    await drive(scheduler, sweeper.close());
-    const rows = sortedRows(model);
-    const [segments, transactions, manifests, currentManifest, leases, compactions, storageBytes] = await Promise.all([
-        collectStoragePages((cursor) => base.listSegmentPage(cursor, 256)),
-        collectStoragePages((cursor) => base.listTransactionPage(cursor, 256)),
-        collectStoragePages((cursor) => base.listManifestPage(cursor, 256)),
-        base.getCurrentManifest(),
-        base.listLeases(),
-        base.listCompactionJobs(),
-        base.getLogicalStorageBytes(),
-    ]);
-    const blockCount = currentManifest?.liveBlockCount ?? 0;
-    const blockLimit = plan.keySpace * 16 + 64;
-    const segmentLimit = plan.keySpace + 16;
-    const transactionLimit = segmentLimit + 16;
-    if (blockCount > blockLimit ||
-        segments.length > segmentLimit ||
-        transactions.length > transactionLimit) {
-        const transactionStates = transactions.reduce((counts, transaction) => {
-            counts[transaction.status] = (counts[transaction.status] ?? 0) + 1;
-            return counts;
-        }, {});
-        const compactionStates = compactions.reduce((counts, compaction) => {
-            counts[compaction.state] = (counts[compaction.state] ?? 0) + 1;
-            return counts;
-        }, {});
-        throw new Error(`Storage did not compact to a bound: ${String(blockCount)}/${String(blockLimit)} live blocks, ` +
-            `${String(segments.length)}/${String(segmentLimit)} segments, ` +
-            `${String(transactions.length)}/${String(transactionLimit)} transactions; ` +
-            `${JSON.stringify(transactionStates)} transaction states, ` +
-            `${JSON.stringify(compactionStates)} compaction states, ` +
-            `${String(currentManifest?.liveBlockCount ?? 0)} current blocks, compaction stopped at ${compactionStop}, ` +
-            `${String(manifests.length)} manifests (${String(manifests.filter((manifest) => manifest.prunedAt !== undefined).length)} pruned) remain after ${String(maintenanceCompactions)} compactions ` +
-            `and ${String(collectionPasses)} collection passes; collection tail ${JSON.stringify(collectionTail)}`);
+    if (step.kind === "checkpoint") {
+      await assertModel(scheduler, clients[0] ?? setup, model);
+      checkpoints++;
+      continue;
     }
-    if (manifests.length > 2) {
-        throw new Error(`Garbage collection left ${String(manifests.length)} manifests and ${String(leases.length)} leases`);
+    if (step.kind === "maintenance") {
+      const database = clients[0] ?? setup;
+      await drive(scheduler, database.compactTable("items"));
+      await drive(scheduler, database.collectGarbage());
+      await drive(scheduler, database.collectGarbage());
+      continue;
     }
-    if (leases.length !== 0) {
-        throw new Error(`Simulation clients leaked ${String(leases.length)} leases`);
-    }
-    const trace = [...scheduler.trace];
-    return {
-        seed: plan.seed,
-        acceptedMutations,
-        rejectedConflicts,
-        injectedFaults,
-        checkpoints,
-        maintenanceCompactions,
-        compactionStop,
-        collectionPasses,
-        collectionTail,
-        rows,
-        blockCount,
-        segmentCount: segments.length,
-        transactionCount: transactions.length,
-        manifestCount: manifests.length,
-        leaseCount: leases.length,
-        storageBytes,
-        schedulerHighWater: scheduler.highWater,
-        trace,
-        traceDigest: md5Hex(JSON.stringify(trace)),
-    };
+    const before = new Map(model);
+    const after = new Map(model);
+    applyMutation(after, step.operation);
+    faults.arm(step.point, step.occurrence);
+    const result = await scheduler.settle([
+      executeMutation(requireClient(clients, step.operation.client), step.operation)
+    ]);
+    if (!faults.fired)
+      throw new Error(`Simulation fault was not reached: ${step.point}`);
+    injectedFaults++;
+    faults.disarm();
+    const failedClient = requireClient(clients, step.operation.client);
+    await drive(scheduler, failedClient.close());
+    const replacement = createDatabase();
+    clients[step.operation.client] = replacement;
+    const actual = await readRows(scheduler, replacement);
+    if (sameRows(actual, before)) {
+      if (result[0]?.status === "fulfilled") {
+        throw new Error(`Fault ${step.point} returned success but did not persist its mutation`);
+      }
+      replaceModel(model, before);
+    } else if (sameRows(actual, after))
+      replaceModel(model, after);
+    else
+      throw new Error(`Fault ${step.point} left a state that was neither before nor after the mutation`);
+  }
+  await assertModel(scheduler, clients[0] ?? setup, model);
+  const closeResults = await scheduler.settle(clients.map((client) => client.close()));
+  assertSettled(closeResults);
+  const maintenance = createDatabase();
+  const compacted = await compactToFixedPoint(scheduler, maintenance, plan.steps.length);
+  const maintenanceCompactions = compacted.passes;
+  const compactionStop = compacted.stop;
+  const collected = await collectToFixedPoint(scheduler, maintenance, plan.steps.length);
+  let collectionPasses = collected.passes;
+  const collectionTail = [...collected.tail];
+  await assertModel(scheduler, maintenance, model);
+  await drive(scheduler, maintenance.close());
+  const sweeper = createDatabase();
+  const swept = await collectToFixedPoint(scheduler, sweeper, plan.steps.length);
+  collectionPasses += swept.passes;
+  collectionTail.push(...swept.tail);
+  if (collectionTail.length > 8)
+    collectionTail.splice(0, collectionTail.length - 8);
+  await drive(scheduler, sweeper.close());
+  const rows = sortedRows(model);
+  const [segments, transactions, manifests, currentManifest, leases, compactions, storageBytes] = await Promise.all([
+    collectStoragePages((cursor) => base.listSegmentPage(cursor, 256)),
+    collectStoragePages((cursor) => base.listTransactionPage(cursor, 256)),
+    collectStoragePages((cursor) => base.listManifestPage(cursor, 256)),
+    base.getCurrentManifest(),
+    base.listLeases(),
+    base.listCompactionJobs(),
+    base.getLogicalStorageBytes()
+  ]);
+  const blockCount = currentManifest?.liveBlockCount ?? 0;
+  const blockLimit = plan.keySpace * 16 + 64;
+  const segmentLimit = plan.keySpace + 16;
+  const transactionLimit = segmentLimit + 16;
+  if (blockCount > blockLimit || segments.length > segmentLimit || transactions.length > transactionLimit) {
+    const transactionStates = transactions.reduce((counts, transaction) => {
+      counts[transaction.status] = (counts[transaction.status] ?? 0) + 1;
+      return counts;
+    }, {});
+    const compactionStates = compactions.reduce((counts, compaction) => {
+      counts[compaction.state] = (counts[compaction.state] ?? 0) + 1;
+      return counts;
+    }, {});
+    throw new Error(`Storage did not compact to a bound: ${String(blockCount)}/${String(blockLimit)} live blocks, ${String(segments.length)}/${String(segmentLimit)} segments, ${String(transactions.length)}/${String(transactionLimit)} transactions; ${JSON.stringify(transactionStates)} transaction states, ${JSON.stringify(compactionStates)} compaction states, ${String(currentManifest?.liveBlockCount ?? 0)} current blocks, compaction stopped at ${compactionStop}, ${String(manifests.length)} manifests (${String(manifests.filter((manifest) => manifest.prunedAt !== void 0).length)} pruned) remain after ${String(maintenanceCompactions)} compactions and ${String(collectionPasses)} collection passes; collection tail ${JSON.stringify(collectionTail)}`);
+  }
+  if (manifests.length > 2) {
+    throw new Error(`Garbage collection left ${String(manifests.length)} manifests and ${String(leases.length)} leases`);
+  }
+  if (leases.length !== 0) {
+    throw new Error(`Simulation clients leaked ${String(leases.length)} leases`);
+  }
+  const trace = [...scheduler.trace];
+  return {
+    seed: plan.seed,
+    acceptedMutations,
+    rejectedConflicts,
+    injectedFaults,
+    checkpoints,
+    maintenanceCompactions,
+    compactionStop,
+    collectionPasses,
+    collectionTail,
+    rows,
+    blockCount,
+    segmentCount: segments.length,
+    transactionCount: transactions.length,
+    manifestCount: manifests.length,
+    leaseCount: leases.length,
+    storageBytes,
+    schedulerHighWater: scheduler.highWater,
+    trace,
+    traceDigest: md5Hex(JSON.stringify(trace))
+  };
 }
 class FaultController {
-    #point;
-    #occurrence = 0;
-    #seen = 0;
-    fired = false;
-    arm(point, occurrence) {
-        this.#point = point;
-        this.#occurrence = occurrence;
-        this.#seen = 0;
-        this.fired = false;
-    }
-    disarm() {
-        this.#point = undefined;
-    }
-    inject(point) {
-        if (point !== this.#point || this.fired)
-            return;
-        this.#seen++;
-        if (this.#seen !== this.#occurrence)
-            return;
-        this.fired = true;
-        throw new Error(`injected ${point} #${String(this.#occurrence)}`);
-    }
+  #point;
+  #occurrence = 0;
+  #seen = 0;
+  fired = false;
+  arm(point, occurrence) {
+    this.#point = point;
+    this.#occurrence = occurrence;
+    this.#seen = 0;
+    this.fired = false;
+  }
+  disarm() {
+    this.#point = void 0;
+  }
+  inject(point) {
+    if (point !== this.#point || this.fired)
+      return;
+    this.#seen++;
+    if (this.#seen !== this.#occurrence)
+      return;
+    this.fired = true;
+    throw new Error(`injected ${point} #${String(this.#occurrence)}`);
+  }
 }
 async function drive(scheduler, promise) {
-    const result = (await scheduler.settle([promise]))[0];
-    if (result?.status === "fulfilled")
-        return result.value;
-    throw result?.reason ?? new Error("Scheduled operation did not settle");
+  const result = (await scheduler.settle([promise]))[0];
+  if (result?.status === "fulfilled")
+    return result.value;
+  throw result?.reason ?? new Error("Scheduled operation did not settle");
 }
 function assertSettled(results) {
-    const failed = results.find((result) => result.status === "rejected");
-    if (failed?.status === "rejected")
-        throw failed.reason;
+  const failed = results.find((result) => result.status === "rejected");
+  if (failed?.status === "rejected")
+    throw failed.reason;
 }
 function executeMutation(database, operation) {
-    if (operation.kind === "delete") {
-        return database.execute("DELETE FROM items WHERE id = ?", [operation.key]);
-    }
-    return database.execute("INSERT INTO items (id, client, amount) VALUES (?, ?, ?) " +
-        "ON CONFLICT (id) DO UPDATE SET client = excluded.client, amount = excluded.amount", [operation.key, operation.client, operation.amount]);
+  if (operation.kind === "delete") {
+    return database.execute("DELETE FROM items WHERE id = ?", [operation.key]);
+  }
+  return database.execute("INSERT INTO items (id, client, amount) VALUES (?, ?, ?) ON CONFLICT (id) DO UPDATE SET client = excluded.client, amount = excluded.amount", [operation.key, operation.client, operation.amount]);
 }
 function applyMutation(model, operation) {
-    if (operation.kind === "delete")
-        model.delete(operation.key);
-    else
-        model.set(operation.key, {
-            id: operation.key,
-            client: operation.client,
-            amount: operation.amount,
-        });
+  if (operation.kind === "delete")
+    model.delete(operation.key);
+  else
+    model.set(operation.key, {
+      id: operation.key,
+      client: operation.client,
+      amount: operation.amount
+    });
 }
 async function assertModel(scheduler, database, model) {
-    const actual = await readRows(scheduler, database);
-    if (!sameRows(actual, model)) {
-        throw new Error(`Model mismatch:\nexpected ${JSON.stringify(sortedRows(model))}\nreceived ${JSON.stringify(actual)}`);
-    }
+  const actual = await readRows(scheduler, database);
+  if (!sameRows(actual, model)) {
+    throw new Error(`Model mismatch:
+expected ${JSON.stringify(sortedRows(model))}
+received ${JSON.stringify(actual)}`);
+  }
 }
 async function readRows(scheduler, database) {
-    const result = await drive(scheduler, database.query("SELECT id, client, amount FROM items ORDER BY id", { memoize: false }));
-    return result.rows;
+  const result = await drive(scheduler, database.query("SELECT id, client, amount FROM items ORDER BY id", { memoize: false }));
+  return result.rows;
 }
 function sameRows(rows, model) {
-    return JSON.stringify(rows) === JSON.stringify(sortedRows(model));
+  return JSON.stringify(rows) === JSON.stringify(sortedRows(model));
 }
 function sortedRows(model) {
-    return [...model.values()].sort((left, right) => left.id - right.id);
+  return [...model.values()].sort((left, right) => left.id - right.id);
 }
 function replaceModel(target, source) {
-    target.clear();
-    for (const [key, value] of source)
-        target.set(key, value);
+  target.clear();
+  for (const [key, value] of source)
+    target.set(key, value);
 }
 function requireClient(clients, index) {
-    const client = clients[index];
-    if (client === undefined)
-        throw new RangeError(`Simulation client is out of range: ${String(index)}`);
-    return client;
+  const client = clients[index];
+  if (client === void 0)
+    throw new RangeError(`Simulation client is out of range: ${String(index)}`);
+  return client;
 }
 function validateSteps(steps, clients, keySpace) {
-    const validPoint = new Set([
-        "beforeBlockWrite",
-        "afterBlockWrite",
-        "beforeBlockRead",
-        "afterBlockRead",
-        "beforeTransactionCommit",
-        "afterTransactionCommit",
-    ]);
-    const validateMutation = (value) => {
-        if (typeof value !== "object" || value === null) {
-            throw new TypeError("Simulation mutation must be an object");
-        }
-        const operation = value;
-        if (operation.kind !== "put" && operation.kind !== "delete") {
-            throw new TypeError("Simulation mutation kind is invalid");
-        }
-        const client = operation.client;
-        if (typeof client !== "number" ||
-            !Number.isSafeInteger(client) ||
-            client < 0 ||
-            client >= clients) {
-            throw new TypeError("Simulation mutation has an invalid client");
-        }
-        const key = operation.key;
-        if (typeof key !== "number" || !Number.isSafeInteger(key) || key < 1 || key > keySpace) {
-            throw new TypeError("Simulation mutation has an invalid key");
-        }
-        if (operation.kind === "put" &&
-            (typeof operation.amount !== "number" || !Number.isSafeInteger(operation.amount))) {
-            throw new TypeError("Simulation put has an invalid amount");
-        }
-    };
-    for (const value of steps) {
-        if (typeof value !== "object" || value === null) {
-            throw new TypeError("Simulation step must be an object");
-        }
-        const step = value;
-        if (step.kind === "concurrent") {
-            if (!Array.isArray(step.operations) || step.operations.length > clients * 4) {
-                throw new TypeError("Simulation concurrent step is unbounded");
-            }
-            step.operations.forEach(validateMutation);
-        }
-        else if (step.kind === "fault") {
-            if (typeof step.point !== "string" || !validPoint.has(step.point)) {
-                throw new TypeError("Simulation fault point is invalid");
-            }
-            const occurrence = step.occurrence;
-            if (typeof occurrence !== "number" || !Number.isSafeInteger(occurrence) || occurrence < 1) {
-                throw new TypeError("Simulation fault occurrence is invalid");
-            }
-            validateMutation(step.operation);
-        }
-        else if (step.kind !== "checkpoint" && step.kind !== "maintenance") {
-            throw new TypeError("Simulation step kind is invalid");
-        }
+  const validPoint = /* @__PURE__ */ new Set([
+    "beforeBlockWrite",
+    "afterBlockWrite",
+    "beforeBlockRead",
+    "afterBlockRead",
+    "beforeTransactionCommit",
+    "afterTransactionCommit"
+  ]);
+  const validateMutation = (value) => {
+    if (typeof value !== "object" || value === null) {
+      throw new TypeError("Simulation mutation must be an object");
+    }
+    const operation = value;
+    if (operation.kind !== "put" && operation.kind !== "delete") {
+      throw new TypeError("Simulation mutation kind is invalid");
+    }
+    const client = operation.client;
+    if (typeof client !== "number" || !Number.isSafeInteger(client) || client < 0 || client >= clients) {
+      throw new TypeError("Simulation mutation has an invalid client");
+    }
+    const key = operation.key;
+    if (typeof key !== "number" || !Number.isSafeInteger(key) || key < 1 || key > keySpace) {
+      throw new TypeError("Simulation mutation has an invalid key");
+    }
+    if (operation.kind === "put" && (typeof operation.amount !== "number" || !Number.isSafeInteger(operation.amount))) {
+      throw new TypeError("Simulation put has an invalid amount");
     }
+  };
+  for (const value of steps) {
+    if (typeof value !== "object" || value === null) {
+      throw new TypeError("Simulation step must be an object");
+    }
+    const step = value;
+    if (step.kind === "concurrent") {
+      if (!Array.isArray(step.operations) || step.operations.length > clients * 4) {
+        throw new TypeError("Simulation concurrent step is unbounded");
+      }
+      step.operations.forEach(validateMutation);
+    } else if (step.kind === "fault") {
+      if (typeof step.point !== "string" || !validPoint.has(step.point)) {
+        throw new TypeError("Simulation fault point is invalid");
+      }
+      const occurrence = step.occurrence;
+      if (typeof occurrence !== "number" || !Number.isSafeInteger(occurrence) || occurrence < 1) {
+        throw new TypeError("Simulation fault occurrence is invalid");
+      }
+      validateMutation(step.operation);
+    } else if (step.kind !== "checkpoint" && step.kind !== "maintenance") {
+      throw new TypeError("Simulation step kind is invalid");
+    }
+  }
 }
 function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
+  return error instanceof Error ? error.message : String(error);
 }
 async function compactToFixedPoint(scheduler, database, workloadSteps) {
-    const maximumPasses = Math.min(10_000, workloadSteps + 128);
-    for (let pass = 0; pass < maximumPasses; pass++) {
-        const result = await drive(scheduler, database.compactTable("items"));
-        if (!result.compacted)
-            return { passes: pass, stop: result.skipReason ?? "unknown" };
-    }
-    throw new Error(`Compaction did not converge within ${String(maximumPasses)} passes`);
+  const maximumPasses = Math.min(1e4, workloadSteps + 128);
+  for (let pass = 0; pass < maximumPasses; pass++) {
+    const result = await drive(scheduler, database.compactTable("items"));
+    if (!result.compacted)
+      return { passes: pass, stop: result.skipReason ?? "unknown" };
+  }
+  throw new Error(`Compaction did not converge within ${String(maximumPasses)} passes`);
 }
 async function collectToFixedPoint(scheduler, database, workloadSteps) {
-    const maximumPasses = Math.min(10_000, workloadSteps + 128);
-    let emptyPasses = 0;
-    const tail = [];
-    for (let pass = 1; pass <= maximumPasses; pass++) {
-        const result = await drive(scheduler, database.collectGarbage());
-        tail.push(summarizeCollection(result));
-        if (tail.length > 8)
-            tail.shift();
-        const changed = result.prunedManifestCount +
-            result.reclaimedSegmentCount +
-            result.reclaimedBlockCount +
-            result.reclaimedTransactionCount;
-        // collectGarbage also prunes finished maintenance records after returning its counters. A
-        // zero-artifact pass can therefore remove the final provenance root that lets the next pass
-        // reclaim bytes. Two consecutive empty passes prove both layers have settled.
-        if (changed === 0) {
-            emptyPasses++;
-            if (emptyPasses === 2)
-                return { passes: pass, tail };
-        }
-        else
-            emptyPasses = 0;
-    }
-    throw new Error(`Garbage collection did not converge within ${String(maximumPasses)} passes`);
+  const maximumPasses = Math.min(1e4, workloadSteps + 128);
+  let emptyPasses = 0;
+  const tail = [];
+  for (let pass = 1; pass <= maximumPasses; pass++) {
+    const result = await drive(scheduler, database.collectGarbage());
+    tail.push(summarizeCollection(result));
+    if (tail.length > 8)
+      tail.shift();
+    const changed = result.prunedManifestCount + result.reclaimedSegmentCount + result.reclaimedBlockCount + result.reclaimedTransactionCount;
+    if (changed === 0) {
+      emptyPasses++;
+      if (emptyPasses === 2)
+        return { passes: pass, tail };
+    } else
+      emptyPasses = 0;
+  }
+  throw new Error(`Garbage collection did not converge within ${String(maximumPasses)} passes`);
 }
 function summarizeCollection(result) {
-    return {
-        prunedManifests: result.prunedManifestCount,
-        retainedManifests: result.retainedManifestCount,
-        reclaimedSegments: result.reclaimedSegmentCount,
-        retainedSegments: result.retainedSegmentCount,
-        reclaimedBlocks: result.reclaimedBlockCount,
-        retainedBlocks: result.retainedBlockCount,
-        reclaimedTransactions: result.reclaimedTransactionCount,
-        retainedTransactions: result.retainedTransactionCount,
-    };
+  return {
+    prunedManifests: result.prunedManifestCount,
+    retainedManifests: result.retainedManifestCount,
+    reclaimedSegments: result.reclaimedSegmentCount,
+    retainedSegments: result.retainedSegmentCount,
+    reclaimedBlocks: result.reclaimedBlockCount,
+    retainedBlocks: result.retainedBlockCount,
+    reclaimedTransactions: result.reclaimedTransactionCount,
+    retainedTransactions: result.retainedTransactionCount
+  };
 }
-// Stream-identical copy of `mulberry32` in ./seeds.ts. This module ships in the tarball and
-// seeds.ts does not (it reads MINNOW_SEED and the unpublished regression-seeds.json), so the
-// published simulator cannot import the canonical copy.
 function mulberry32(seed) {
-    let state = seed >>> 0;
-    return () => {
-        state = (state + 0x6d2b79f5) >>> 0;
-        let mixed = state;
-        mixed = Math.imul(mixed ^ (mixed >>> 15), mixed | 1);
-        mixed ^= mixed + Math.imul(mixed ^ (mixed >>> 7), mixed | 61);
-        return ((mixed ^ (mixed >>> 14)) >>> 0) / 4_294_967_296;
-    };
+  let state = seed >>> 0;
+  return () => {
+    state = state + 1831565813 >>> 0;
+    let mixed = state;
+    mixed = Math.imul(mixed ^ mixed >>> 15, mixed | 1);
+    mixed ^= mixed + Math.imul(mixed ^ mixed >>> 7, mixed | 61);
+    return ((mixed ^ mixed >>> 14) >>> 0) / 4294967296;
+  };
 }
 function greatestCommonDivisor(left, right) {
-    let a = left;
-    let b = right;
-    while (b !== 0)
-        [a, b] = [b, a % b];
-    return a;
+  let a = left;
+  let b = right;
+  while (b !== 0)
+    [a, b] = [b, a % b];
+  return a;
 }
+export {
+  DeterministicScheduler,
+  generateSimulationPlan,
+  parseSimulationPlan,
+  runSimulation,
+  scheduledBlockStore
+};