Deterministic virtual time: clocks, sleep, deadlines, cancellation, and timer-aware replay

[schani]

Implements TIMERS-SPEC.md (added as the first commit): deterministic virtual time for the simulation, so timeout-heavy scenarios run instantly, replay exactly, and use the same business logic in production.

What's new

• Virtual clock — task.monotonicNow() / task.wallNow() (configurable wall-clock epoch). Virtual in simulation, performance.now()/Date.now() in noSimulation.
• Deterministic sleep — task.sleep(ms, reason, { signal? }) parks the task with a pending timer. Timer deadlines are lower bounds: when no task is runnable, an entropy-chosen pending timer — any of them — fires and the clock advances to max(now, deadline), so a 2,000ms timer can fire before a 1,000ms one, exactly as setTimeout lateness permits in production. Firing order is an ordinary recorded entropy decision; a single pending timer is a forced choice that consumes no entropy. The pick distribution is a configurable policy (pickTimerIndex), analogous to failpointFailureProbability.
• Cooperative cancellation — aborting a sleep's signal removes its timer and rejects with signal.reason (Node timers/promises contract); pre-aborted signals reject immediately with no timer and no entropy. task.createDeadline(ms, reason) returns a cancellable handle; task.withTimedSignal(f, ms, reason) scopes a timeout and guarantees no work started under it is still running when it returns — it never force-interrupts. In simulation the deadline signal is a determined-owned AbortSignal implementation: sleep wakeups are privileged callbacks, user listeners run under a guard (task APIs from a listener fail descriptively; a throwing listener aborts the run).
• Cancellation ≠ failure — CancellationError + isCancellation(e) alongside isApplicationFailure(e): retry loops retry simulated failures but must propagate cancellations.
• Timer-aware diagnostics — sleeping tasks never trigger false deadlocks; deadlock reports include park reasons and call out aborted-but-uncancelled deadline signals; work completing after its signal aborted is reported (warning, or a failure with failOnLateCompletion); maxSchedulingSteps distinguishes livelock (budget spent at a fixed virtual time) from an outgrown budget; maxVirtualDurationMs bounds the clock.
• Typed trace with explicit timer records — RecordingTraceSource/ReplayingTraceSource record/validate the wall-clock epoch, entropy draws, and timer create/cancel/fire events in order. This catches divergence that entropy alone cannot: forced choices consume no entropy, so a changed reason or deadline on a single pending timer would otherwise go unnoticed. The entropy-only sources still work, minus timer validation.

Notes

• All 20 acceptance tests from TIMERS-SPEC.md §14 are implemented across time.test.ts, trace.test.ts, and scenario.test.ts (a pi-orb-style retry/backoff + shutdown-flush scenario, 20 randomized record+replay iterations). 123 tests total, all green; tsup build passes.
• Spec §15's open questions resolved pragmatically: time lives on SimulationTask; timestamps are millisecond floats.
• The one-park-per-task invariant is preserved: a sleep occupies the task's single resolve slot exactly like a blockpoint, and the timer-fire and abort paths disarm each other. Park rollback on synchronous scheduler throws (the recent entropy-guard fixes) extends to sleep timers and abort hooks.
• Version bumped to 0.4.0.

🤖 Generated with Claude Code