core/replay_recorder library

Classes

ReplayCapsule: A versioned, signable envelope capturing everything needed to replay 1 recording session: the RNG seed (feed straight into SeededRandom(seed)/SeededRandomService(seed)), the appVersion it was captured under, and the ordered events.
ReplayDivergence: The first index at which expected and actual differ — null if they're identical throughout. Reported with both values so a caller (e.g. a replay-divergence debug view) has enough context to see exactly where and how a replay diverged from what was originally recorded, per-event or per-checkpoint (whatever unit the caller compares).
ReplayEvent: 1 recorded input/decision event — offsetMs is a monotonic offset from the moment ReplayRecorder.start was called (never wall-clock time, so a replay run doesn't need to happen at the same real-world moment). payload is entirely caller-defined — this class never inspects or interprets it, same "pure envelope, caller owns the shape" convention as LeaderboardEntry/VictoryCardTemplate.statLines.
ReplayRecorder: Records gameplay/input events into a bounded ring buffer during a QA session, then packages them (plus the session's RNG seed) into a ReplayCapsule a developer can import elsewhere to reproduce a bug that was hard to describe from a screen recording alone.

findFirstDivergence(List<Object?> expected, List<Object?> actual) → ReplayDivergence?: Compares 2 ordered outcome lists (e.g. a recorded session's outcomes vs a fresh replay's outcomes) and returns the FIRST point they differ — including a length mismatch, treated as the shorter list "missing" the longer one's extra entries starting there.
replayCapsule(ReplayCapsule capsule, Object? handler(ReplayEvent event, SeededRandomService rng), {SeededRandomService? rng}) → ReplayDivergence?: Replays capsule's events through handler — invoked once per event with a fresh SeededRandomService seeded from the capsule (so the SAME namespace-fork behaviour a live session got, FEAT-45, is exactly what a replay gets too) — and reports the first point the produced outcomes diverge from what was originally recorded, or null if the replay reproduced the session exactly.