Documentation

FerroReplay

MorphIQ Labs’ deterministic-replay primitive: the machinery that makes an engine replayable, extracted from the products that proved it. Determinism machinery moves; trading semantics stay. v0.1.0 is the clock primitive — an injected Clock trait, a monotonic SystemClock, a replay VirtualClock, and grid-aligned intervals.

What it is

FerroReplay is a small, dependency-lean Rust crate that gives an engine a single, injectable source of time. Every timestamp read and every timer wait flows through one Clock — a monotonic SystemClock in production, a deadline-ordered VirtualClock in tests and replay. Because the rest of the code never touches the wall clock directly, live and replay run the identical path and produce byte-identical state.

Why it exists

Deterministic replay is the prerequisite for trustworthy backtests, reproducible incident analysis, and state-rebuild on restart. It is only achievable if time is a dependency rather than an ambient. FerroReplay makes time injectable and ships the discipline — the wallclock gate — that keeps it that way across an adopting codebase.

The primitives

  • The Clock trait — an async trait on an i64 epoch-nanosecond timeline: now_ns, cancel-safe sleep_until, and sleep. See core concepts.
  • SystemClock — the live clock; one wall-clock read anchors the epoch to a monotonic instant. The sole sanctioned wall-clock site in any adopting codebase.
  • VirtualClock — the replay clock; advance_to wakes due timers in deadline order, each observing now equal to its own deadline.
  • interval / ClockInterval — grid-aligned ticks with scheduled (not observed) stamps and skip-not-burst missed-tick semantics.

Start here

  • Getting started — add the dependency by git tag and wire your first clock.
  • Core concepts — the timeline, the two clocks, intervals, and the determinism laws they uphold.
  • The wallclock gate — the consumer discipline that keeps an adopting repo deterministic.
  • The use-case guides — wiring, testing, intervals, and replay, each from typed input to deterministic result.
Next →Getting started