@crashlab/scheduler 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# @crashlab/scheduler
+
+Cooperative deterministic scheduler for mock I/O boundaries. Holds enqueued completions until their virtual time arrives, then releases them in a PRNG-shuffled order — making all macro-level race conditions fully reproducible with the same seed. Does **not** intercept V8 microtasks or Promise internals.
+
+## Usage
+
+```ts
+import { Scheduler } from '@crashlab/scheduler';
+
+const sched = new Scheduler({ prngSeed: 42 });
+
+// Mock I/O layer enqueues completions:
+sched.enqueueCompletion({ id: 'db-read-1', when: 80, run: () => resolveQuery1() });
+sched.enqueueCompletion({ id: 'db-read-2', when: 80, run: () => resolveQuery2() });
+
+// When the virtual clock advances to t=80:
+await sched.runTick(80);
+// Both completions run in deterministic PRNG-shuffled order.
+```
+
+## Clock integration
+
+```ts
+import { VirtualClock } from '@crashlab/clock';
+
+const clock = new VirtualClock(0);
+const sched = new Scheduler({ clock, prngSeed: 42 });
+// Contract: when clock.advance() reaches time t, call await sched.runTick(t).
+```

package/dist/index.cjs

@@ -0,0 +1,160 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Scheduler: () => Scheduler
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/prng.ts
+function mulberry32(seed) {
+  let s = seed | 0;
+  return function next() {
+    s = s + 1831565813 | 0;
+    let t = Math.imul(s ^ s >>> 15, 1 | s);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function shuffleInPlace(arr, rng) {
+  for (let i = arr.length - 1; i > 0; i--) {
+    const j = Math.floor(rng() * (i + 1));
+    [arr[i], arr[j]] = [arr[j], arr[i]];
+  }
+  return arr;
+}
+
+// src/index.ts
+var Scheduler = class {
+  _clock;
+  _rng;
+  _pending = [];
+  _runChain = Promise.resolve();
+  _autoDrainScheduled = false;
+  _requestedTick = null;
+  constructor(opts = {}) {
+    this._clock = opts.clock;
+    this._rng = mulberry32(opts.prngSeed ?? 0);
+  }
+  // public API
+  /**
+   * Enqueue a mock-I/O completion.
+   *
+   * The `run` callback is **not** invoked immediately — it is held in the
+   * pending queue until `runTick(t)` is called with `t >= op.when`.
+   */
+  enqueueCompletion(op) {
+    this._pending.push(op);
+  }
+  /**
+   * Request an asynchronous drain for ops ready at `virtualTime`.
+   *
+   * Multiple calls in the same turn are coalesced into one microtask and the
+   * highest requested virtual time is used.
+   */
+  requestRunTick(virtualTime) {
+    this._requestedTick = this._requestedTick == null ? virtualTime : Math.max(this._requestedTick, virtualTime);
+    if (this._autoDrainScheduled) return;
+    this._autoDrainScheduled = true;
+    queueMicrotask(() => {
+      this._autoDrainScheduled = false;
+      const tick = this._requestedTick;
+      this._requestedTick = null;
+      if (tick == null) return;
+      void this.runTick(tick).catch(() => {
+      });
+      if (this._requestedTick != null) {
+        this.requestRunTick(this._requestedTick);
+      }
+    });
+  }
+  /**
+   * Attach (or replace) the clock reference.
+   *
+   * Integration contract: when the clock advances to time `t`, it should
+   * call `await scheduler.runTick(t)`.
+   */
+  attachClock(clock) {
+    this._clock = clock;
+  }
+  /**
+   * Collect all enqueued ops with `when <= virtualTime`, shuffle them
+   * deterministically via the seeded PRNG, then execute their `run()`
+   * callbacks **sequentially** in that shuffled order, awaiting one
+   * microtask checkpoint (`await Promise.resolve()`) between each.
+   */
+  async runTick(virtualTime) {
+    const run = async () => {
+      while (true) {
+        const ready = [];
+        const remaining = [];
+        for (const op of this._pending) {
+          if (op.when <= virtualTime) {
+            ready.push(op);
+          } else {
+            remaining.push(op);
+          }
+        }
+        this._pending.length = 0;
+        this._pending.push(...remaining);
+        if (ready.length === 0) break;
+        ready.sort((a, b) => a.when - b.when);
+        let i = 0;
+        while (i < ready.length) {
+          let j = i;
+          while (j < ready.length && ready[j].when === ready[i].when) j++;
+          if (j - i > 1) {
+            const group = ready.slice(i, j);
+            shuffleInPlace(group, this._rng);
+            for (let k = 0; k < group.length; k++) {
+              ready[i + k] = group[k];
+            }
+          }
+          i = j;
+        }
+        for (const op of ready) {
+          await op.run();
+          await Promise.resolve();
+        }
+      }
+    };
+    const chained = this._runChain.then(run);
+    this._runChain = chained.catch(() => {
+    });
+    return chained;
+  }
+  /**
+   * Drain **all** pending ops immediately, regardless of their `when`.
+   * Useful for test teardown.
+   */
+  async drain() {
+    await this.runTick(Number.MAX_SAFE_INTEGER);
+  }
+  /** Number of operations currently held in the pending queue. */
+  get pendingCount() {
+    return this._pending.length;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Scheduler
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/prng.ts"],"sourcesContent":["import type { IClock, PendingOp } from './types.js';\nimport { mulberry32, shuffleInPlace } from './prng.js';\n\nexport type { IClock, PendingOp } from './types.js';\n\nexport interface SchedulerOptions {\n  /** Optional virtual clock. When attached, the scheduler can be called from clock.advance(). */\n  clock?: IClock;\n  /** Seed for the PRNG that determines execution order of same-tick ops. */\n  prngSeed?: number;\n}\n\n/**\n * Cooperative deterministic scheduler.\n *\n * Holds mock-I/O completions until their virtual time arrives, then\n * releases them in a PRNG-determined order — making all macro-level\n * race conditions reproducible across runs with the same seed.\n *\n * **This scheduler does NOT intercept V8 microtasks or Promise internals.**\n * It controls ordering exclusively at mock I/O boundaries.\n */\nexport class Scheduler {\n  private _clock: IClock | undefined;\n  private readonly _rng: () => number;\n  private readonly _pending: PendingOp[] = [];\n  private _runChain: Promise<void> = Promise.resolve();\n  private _autoDrainScheduled = false;\n  private _requestedTick: number | null = null;\n\n  constructor(opts: SchedulerOptions = {}) {\n    this._clock = opts.clock;\n    this._rng = mulberry32(opts.prngSeed ?? 0);\n  }\n\n  // public API\n\n  /**\n   * Enqueue a mock-I/O completion.\n   *\n   * The `run` callback is **not** invoked immediately — it is held in the\n   * pending queue until `runTick(t)` is called with `t >= op.when`.\n   */\n  enqueueCompletion(op: PendingOp): void {\n    this._pending.push(op);\n  }\n\n  /**\n   * Request an asynchronous drain for ops ready at `virtualTime`.\n   *\n   * Multiple calls in the same turn are coalesced into one microtask and the\n   * highest requested virtual time is used.\n   */\n  requestRunTick(virtualTime: number): void {\n    this._requestedTick = this._requestedTick == null\n      ? virtualTime\n      : Math.max(this._requestedTick, virtualTime);\n\n    if (this._autoDrainScheduled) return;\n    this._autoDrainScheduled = true;\n\n    queueMicrotask(() => {\n      this._autoDrainScheduled = false;\n      const tick = this._requestedTick;\n      this._requestedTick = null;\n      if (tick == null) return;\n      void this.runTick(tick).catch(() => {\n        // Errors still surface to explicit runTick callers; requestRunTick is\n        // best-effort and must not throw asynchronously.\n      });\n      if (this._requestedTick != null) {\n        this.requestRunTick(this._requestedTick);\n      }\n    });\n  }\n\n  /**\n   * Attach (or replace) the clock reference.\n   *\n   * Integration contract: when the clock advances to time `t`, it should\n   * call `await scheduler.runTick(t)`.\n   */\n  attachClock(clock: IClock): void {\n    this._clock = clock;\n  }\n\n  /**\n   * Collect all enqueued ops with `when <= virtualTime`, shuffle them\n   * deterministically via the seeded PRNG, then execute their `run()`\n   * callbacks **sequentially** in that shuffled order, awaiting one\n   * microtask checkpoint (`await Promise.resolve()`) between each.\n   */\n  async runTick(virtualTime: number): Promise<void> {\n    const run = async (): Promise<void> => {\n      // Loop to handle cascading completions: ops enqueued during callback\n      // execution that are also ready at this virtual time are picked up\n      // in the next iteration, preserving causal ordering.\n      while (true) {\n        // 1. Partition: pull out all ops ready at this tick.\n        const ready: PendingOp[] = [];\n        const remaining: PendingOp[] = [];\n        for (const op of this._pending) {\n          if (op.when <= virtualTime) {\n            ready.push(op);\n          } else {\n            remaining.push(op);\n          }\n        }\n        this._pending.length = 0;\n        this._pending.push(...remaining);\n\n        if (ready.length === 0) break;\n\n        // 2. Stable-sort by `when` ascending so earlier ops run first,\n        //    then shuffle within each same-`when` group via PRNG.\n        ready.sort((a, b) => a.when - b.when);\n\n        // Group by `when` and shuffle each group.\n        let i = 0;\n        while (i < ready.length) {\n          let j = i;\n          while (j < ready.length && ready[j].when === ready[i].when) j++;\n          if (j - i > 1) {\n            const group = ready.slice(i, j);\n            shuffleInPlace(group, this._rng);\n            for (let k = 0; k < group.length; k++) {\n              ready[i + k] = group[k];\n            }\n          }\n          i = j;\n        }\n\n        // 3. Execute sequentially, with a microtask boundary between each.\n        for (const op of ready) {\n          await op.run();\n          await Promise.resolve(); // microtask checkpoint\n        }\n      }\n    };\n\n    const chained = this._runChain.then(run);\n    this._runChain = chained.catch(() => {});\n    return chained;\n  }\n\n  /**\n   * Drain **all** pending ops immediately, regardless of their `when`.\n   * Useful for test teardown.\n   */\n  async drain(): Promise<void> {\n    await this.runTick(Number.MAX_SAFE_INTEGER);\n  }\n\n  /** Number of operations currently held in the pending queue. */\n  get pendingCount(): number {\n    return this._pending.length;\n  }\n}\n","/**\n * Mulberry32 — fast 32-bit seeded PRNG.\n * Returns a function yielding numbers in [0, 1).\n *\n * This is a self-contained fallback so `@crashlab/scheduler` has zero\n * hard dependencies.  If `@crashlab/random` is available in the monorepo,\n * consumers can pass their own SeededRandom instead.\n */\nexport function mulberry32(seed: number): () => number {\n  let s = seed | 0;\n  return function next(): number {\n    s = (s + 0x6d2b79f5) | 0;\n    let t = Math.imul(s ^ (s >>> 15), 1 | s);\n    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;\n    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n  };\n}\n\n/**\n * Deterministic Fisher-Yates shuffle using a seeded PRNG.\n * Mutates `arr` in place and returns it.\n */\nexport function shuffleInPlace<T>(arr: T[], rng: () => number): T[] {\n  for (let i = arr.length - 1; i > 0; i--) {\n    const j = Math.floor(rng() * (i + 1));\n    [arr[i], arr[j]] = [arr[j], arr[i]];\n  }\n  return arr;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+import type { IClock, PendingOp } from './types.js';
+export type { IClock, PendingOp } from './types.js';
+export interface SchedulerOptions {
+    /** Optional virtual clock. When attached, the scheduler can be called from clock.advance(). */
+    clock?: IClock;
+    /** Seed for the PRNG that determines execution order of same-tick ops. */
+    prngSeed?: number;
+}
+/**
+ * Cooperative deterministic scheduler.
+ *
+ * Holds mock-I/O completions until their virtual time arrives, then
+ * releases them in a PRNG-determined order — making all macro-level
+ * race conditions reproducible across runs with the same seed.
+ *
+ * **This scheduler does NOT intercept V8 microtasks or Promise internals.**
+ * It controls ordering exclusively at mock I/O boundaries.
+ */
+export declare class Scheduler {
+    private _clock;
+    private readonly _rng;
+    private readonly _pending;
+    private _runChain;
+    private _autoDrainScheduled;
+    private _requestedTick;
+    constructor(opts?: SchedulerOptions);
+    /**
+     * Enqueue a mock-I/O completion.
+     *
+     * The `run` callback is **not** invoked immediately — it is held in the
+     * pending queue until `runTick(t)` is called with `t >= op.when`.
+     */
+    enqueueCompletion(op: PendingOp): void;
+    /**
+     * Request an asynchronous drain for ops ready at `virtualTime`.
+     *
+     * Multiple calls in the same turn are coalesced into one microtask and the
+     * highest requested virtual time is used.
+     */
+    requestRunTick(virtualTime: number): void;
+    /**
+     * Attach (or replace) the clock reference.
+     *
+     * Integration contract: when the clock advances to time `t`, it should
+     * call `await scheduler.runTick(t)`.
+     */
+    attachClock(clock: IClock): void;
+    /**
+     * Collect all enqueued ops with `when <= virtualTime`, shuffle them
+     * deterministically via the seeded PRNG, then execute their `run()`
+     * callbacks **sequentially** in that shuffled order, awaiting one
+     * microtask checkpoint (`await Promise.resolve()`) between each.
+     */
+    runTick(virtualTime: number): Promise<void>;
+    /**
+     * Drain **all** pending ops immediately, regardless of their `when`.
+     * Useful for test teardown.
+     */
+    drain(): Promise<void>;
+    /** Number of operations currently held in the pending queue. */
+    get pendingCount(): number;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGpD,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,SAAS,CAAoC;IACrD,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,cAAc,CAAuB;gBAEjC,IAAI,GAAE,gBAAqB;IAOvC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IAItC;;;;;OAKG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAuBzC;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIhC;;;;;OAKG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqDjD;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,gEAAgE;IAChE,IAAI,YAAY,IAAI,MAAM,CAEzB;CACF"}

package/dist/index.js

@@ -0,0 +1,133 @@
+// src/prng.ts
+function mulberry32(seed) {
+  let s = seed | 0;
+  return function next() {
+    s = s + 1831565813 | 0;
+    let t = Math.imul(s ^ s >>> 15, 1 | s);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function shuffleInPlace(arr, rng) {
+  for (let i = arr.length - 1; i > 0; i--) {
+    const j = Math.floor(rng() * (i + 1));
+    [arr[i], arr[j]] = [arr[j], arr[i]];
+  }
+  return arr;
+}
+
+// src/index.ts
+var Scheduler = class {
+  _clock;
+  _rng;
+  _pending = [];
+  _runChain = Promise.resolve();
+  _autoDrainScheduled = false;
+  _requestedTick = null;
+  constructor(opts = {}) {
+    this._clock = opts.clock;
+    this._rng = mulberry32(opts.prngSeed ?? 0);
+  }
+  // public API
+  /**
+   * Enqueue a mock-I/O completion.
+   *
+   * The `run` callback is **not** invoked immediately — it is held in the
+   * pending queue until `runTick(t)` is called with `t >= op.when`.
+   */
+  enqueueCompletion(op) {
+    this._pending.push(op);
+  }
+  /**
+   * Request an asynchronous drain for ops ready at `virtualTime`.
+   *
+   * Multiple calls in the same turn are coalesced into one microtask and the
+   * highest requested virtual time is used.
+   */
+  requestRunTick(virtualTime) {
+    this._requestedTick = this._requestedTick == null ? virtualTime : Math.max(this._requestedTick, virtualTime);
+    if (this._autoDrainScheduled) return;
+    this._autoDrainScheduled = true;
+    queueMicrotask(() => {
+      this._autoDrainScheduled = false;
+      const tick = this._requestedTick;
+      this._requestedTick = null;
+      if (tick == null) return;
+      void this.runTick(tick).catch(() => {
+      });
+      if (this._requestedTick != null) {
+        this.requestRunTick(this._requestedTick);
+      }
+    });
+  }
+  /**
+   * Attach (or replace) the clock reference.
+   *
+   * Integration contract: when the clock advances to time `t`, it should
+   * call `await scheduler.runTick(t)`.
+   */
+  attachClock(clock) {
+    this._clock = clock;
+  }
+  /**
+   * Collect all enqueued ops with `when <= virtualTime`, shuffle them
+   * deterministically via the seeded PRNG, then execute their `run()`
+   * callbacks **sequentially** in that shuffled order, awaiting one
+   * microtask checkpoint (`await Promise.resolve()`) between each.
+   */
+  async runTick(virtualTime) {
+    const run = async () => {
+      while (true) {
+        const ready = [];
+        const remaining = [];
+        for (const op of this._pending) {
+          if (op.when <= virtualTime) {
+            ready.push(op);
+          } else {
+            remaining.push(op);
+          }
+        }
+        this._pending.length = 0;
+        this._pending.push(...remaining);
+        if (ready.length === 0) break;
+        ready.sort((a, b) => a.when - b.when);
+        let i = 0;
+        while (i < ready.length) {
+          let j = i;
+          while (j < ready.length && ready[j].when === ready[i].when) j++;
+          if (j - i > 1) {
+            const group = ready.slice(i, j);
+            shuffleInPlace(group, this._rng);
+            for (let k = 0; k < group.length; k++) {
+              ready[i + k] = group[k];
+            }
+          }
+          i = j;
+        }
+        for (const op of ready) {
+          await op.run();
+          await Promise.resolve();
+        }
+      }
+    };
+    const chained = this._runChain.then(run);
+    this._runChain = chained.catch(() => {
+    });
+    return chained;
+  }
+  /**
+   * Drain **all** pending ops immediately, regardless of their `when`.
+   * Useful for test teardown.
+   */
+  async drain() {
+    await this.runTick(Number.MAX_SAFE_INTEGER);
+  }
+  /** Number of operations currently held in the pending queue. */
+  get pendingCount() {
+    return this._pending.length;
+  }
+};
+export {
+  Scheduler
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/prng.ts","../src/index.ts"],"sourcesContent":["/**\n * Mulberry32 — fast 32-bit seeded PRNG.\n * Returns a function yielding numbers in [0, 1).\n *\n * This is a self-contained fallback so `@crashlab/scheduler` has zero\n * hard dependencies.  If `@crashlab/random` is available in the monorepo,\n * consumers can pass their own SeededRandom instead.\n */\nexport function mulberry32(seed: number): () => number {\n  let s = seed | 0;\n  return function next(): number {\n    s = (s + 0x6d2b79f5) | 0;\n    let t = Math.imul(s ^ (s >>> 15), 1 | s);\n    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;\n    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n  };\n}\n\n/**\n * Deterministic Fisher-Yates shuffle using a seeded PRNG.\n * Mutates `arr` in place and returns it.\n */\nexport function shuffleInPlace<T>(arr: T[], rng: () => number): T[] {\n  for (let i = arr.length - 1; i > 0; i--) {\n    const j = Math.floor(rng() * (i + 1));\n    [arr[i], arr[j]] = [arr[j], arr[i]];\n  }\n  return arr;\n}\n","import type { IClock, PendingOp } from './types.js';\nimport { mulberry32, shuffleInPlace } from './prng.js';\n\nexport type { IClock, PendingOp } from './types.js';\n\nexport interface SchedulerOptions {\n  /** Optional virtual clock. When attached, the scheduler can be called from clock.advance(). */\n  clock?: IClock;\n  /** Seed for the PRNG that determines execution order of same-tick ops. */\n  prngSeed?: number;\n}\n\n/**\n * Cooperative deterministic scheduler.\n *\n * Holds mock-I/O completions until their virtual time arrives, then\n * releases them in a PRNG-determined order — making all macro-level\n * race conditions reproducible across runs with the same seed.\n *\n * **This scheduler does NOT intercept V8 microtasks or Promise internals.**\n * It controls ordering exclusively at mock I/O boundaries.\n */\nexport class Scheduler {\n  private _clock: IClock | undefined;\n  private readonly _rng: () => number;\n  private readonly _pending: PendingOp[] = [];\n  private _runChain: Promise<void> = Promise.resolve();\n  private _autoDrainScheduled = false;\n  private _requestedTick: number | null = null;\n\n  constructor(opts: SchedulerOptions = {}) {\n    this._clock = opts.clock;\n    this._rng = mulberry32(opts.prngSeed ?? 0);\n  }\n\n  // public API\n\n  /**\n   * Enqueue a mock-I/O completion.\n   *\n   * The `run` callback is **not** invoked immediately — it is held in the\n   * pending queue until `runTick(t)` is called with `t >= op.when`.\n   */\n  enqueueCompletion(op: PendingOp): void {\n    this._pending.push(op);\n  }\n\n  /**\n   * Request an asynchronous drain for ops ready at `virtualTime`.\n   *\n   * Multiple calls in the same turn are coalesced into one microtask and the\n   * highest requested virtual time is used.\n   */\n  requestRunTick(virtualTime: number): void {\n    this._requestedTick = this._requestedTick == null\n      ? virtualTime\n      : Math.max(this._requestedTick, virtualTime);\n\n    if (this._autoDrainScheduled) return;\n    this._autoDrainScheduled = true;\n\n    queueMicrotask(() => {\n      this._autoDrainScheduled = false;\n      const tick = this._requestedTick;\n      this._requestedTick = null;\n      if (tick == null) return;\n      void this.runTick(tick).catch(() => {\n        // Errors still surface to explicit runTick callers; requestRunTick is\n        // best-effort and must not throw asynchronously.\n      });\n      if (this._requestedTick != null) {\n        this.requestRunTick(this._requestedTick);\n      }\n    });\n  }\n\n  /**\n   * Attach (or replace) the clock reference.\n   *\n   * Integration contract: when the clock advances to time `t`, it should\n   * call `await scheduler.runTick(t)`.\n   */\n  attachClock(clock: IClock): void {\n    this._clock = clock;\n  }\n\n  /**\n   * Collect all enqueued ops with `when <= virtualTime`, shuffle them\n   * deterministically via the seeded PRNG, then execute their `run()`\n   * callbacks **sequentially** in that shuffled order, awaiting one\n   * microtask checkpoint (`await Promise.resolve()`) between each.\n   */\n  async runTick(virtualTime: number): Promise<void> {\n    const run = async (): Promise<void> => {\n      // Loop to handle cascading completions: ops enqueued during callback\n      // execution that are also ready at this virtual time are picked up\n      // in the next iteration, preserving causal ordering.\n      while (true) {\n        // 1. Partition: pull out all ops ready at this tick.\n        const ready: PendingOp[] = [];\n        const remaining: PendingOp[] = [];\n        for (const op of this._pending) {\n          if (op.when <= virtualTime) {\n            ready.push(op);\n          } else {\n            remaining.push(op);\n          }\n        }\n        this._pending.length = 0;\n        this._pending.push(...remaining);\n\n        if (ready.length === 0) break;\n\n        // 2. Stable-sort by `when` ascending so earlier ops run first,\n        //    then shuffle within each same-`when` group via PRNG.\n        ready.sort((a, b) => a.when - b.when);\n\n        // Group by `when` and shuffle each group.\n        let i = 0;\n        while (i < ready.length) {\n          let j = i;\n          while (j < ready.length && ready[j].when === ready[i].when) j++;\n          if (j - i > 1) {\n            const group = ready.slice(i, j);\n            shuffleInPlace(group, this._rng);\n            for (let k = 0; k < group.length; k++) {\n              ready[i + k] = group[k];\n            }\n          }\n          i = j;\n        }\n\n        // 3. Execute sequentially, with a microtask boundary between each.\n        for (const op of ready) {\n          await op.run();\n          await Promise.resolve(); // microtask checkpoint\n        }\n      }\n    };\n\n    const chained = this._runChain.then(run);\n    this._runChain = chained.catch(() => {});\n    return chained;\n  }\n\n  /**\n   * Drain **all** pending ops immediately, regardless of their `when`.\n   * Useful for test teardown.\n   */\n  async drain(): Promise<void> {\n    await this.runTick(Number.MAX_SAFE_INTEGER);\n  }\n\n  /** Number of operations currently held in the pending queue. */\n  get pendingCount(): number {\n    return this._pending.length;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/prng.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Mulberry32 — fast 32-bit seeded PRNG.
+ * Returns a function yielding numbers in [0, 1).
+ *
+ * This is a self-contained fallback so `@crashlab/scheduler` has zero
+ * hard dependencies.  If `@crashlab/random` is available in the monorepo,
+ * consumers can pass their own SeededRandom instead.
+ */
+export declare function mulberry32(seed: number): () => number;
+/**
+ * Deterministic Fisher-Yates shuffle using a seeded PRNG.
+ * Mutates `arr` in place and returns it.
+ */
+export declare function shuffleInPlace<T>(arr: T[], rng: () => number): T[];
+//# sourceMappingURL=prng.d.ts.map

package/dist/prng.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prng.d.ts","sourceRoot":"","sources":["../src/prng.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,MAAM,CAQrD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,MAAM,GAAG,CAAC,EAAE,CAMlE"}

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Minimal clock interface (duck-typed — no hard dep on @crashlab/clock).
+ *
+ * When the clock advances to time `t`, it should call:
+ *   await scheduler.runTick(t)
+ */
+export interface IClock {
+    now(): number;
+}
+/** An enqueued mock-I/O completion that the scheduler holds until its virtual time arrives. */
+export interface PendingOp {
+    /** Unique operation identifier (for debugging / logging). */
+    id: string;
+    /** Virtual timestamp (ms) when this operation completes. */
+    when: number;
+    /** Callback to execute when the scheduler releases this operation. */
+    run: () => Promise<void> | void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,GAAG,IAAI,MAAM,CAAC;CACf;AAED,+FAA+F;AAC/F,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACjC"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@crashlab/scheduler",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup && tsc --build tsconfig.json --force",
+    "clean": "rimraf dist",
+    "prepack": "npm run build",
+    "build:pkg": "tsup && tsc --build tsconfig.json --force"
+  }
+}