Inspiration
Distributed-systems bugs are famously hard to reproduce: a race that fires once under load may never fire again. Detrace came from wanting a small, honest sandbox where failures are deterministic - inject a fault, watch a safety property break, then rewind and replay the exact same run.
What it does
Detrace simulates a simplified Raft-inspired 5-node key-value cluster entirely in the browser, on a seeded discrete-event kernel. You can:
- Inject message drops, duplicates, delay spikes, node crashes and network partitions.
- Watch live invariant monitors check election safety, commit safety and committed-overwrite on every event.
- Rewind the cluster to any earlier event and inspect state there.
- Verify replay: re-run the recorded trace from event zero and confirm the run digest matches exactly.
- Open the injected-bug lab: a deliberate toy mutation (leader commits without majority) so you can watch the monitors catch a commit-safety violation and show the conflicting values.
Scope, honestly: this is an educational model, not production Raft, and the injected bug is a teaching mutation, not a real Raft vulnerability. Monitor results apply to the simulated run and checked properties.
How we built it
Vanilla JavaScript with no build step. A single deterministic event kernel (seeded PRNG, virtual clock, priority queue) drives the whole simulation; the DOM/SVG UI renders cluster state live; Node's built-in test runner covers 16 engine tests including replay reproducibility and the crash-reset regression. Hosted as a static site on GitHub Pages.
Built with AI assistance for design, code generation, debugging, automated testing and demo production, under M J Anthony's direction.
Challenges we ran into
Byte-exact replay means every source of nondeterminism - timers, message ordering, UI-driven restarts - must go through the seeded kernel. A real bug we caught late: resetting a crashed node's state cleared its "down" flag, so crashed nodes silently came back to life while the tests still passed, because they asserted log survival instead of visible state. That bug is now a regression test.
Accomplishments that we're proud of
Replay verified exactly from the exported trace; the injected bug is caught by the monitors with the affected log index and conflicting values shown; the whole thing runs client-side with no backend.
What we learned
Deterministic simulation is a forcing function for honesty: any hidden nondeterminism breaks replay immediately. And asserting visible state in tests matters as much as asserting logs.
What's next for Detrace
Richer workloads (linearizable reads, snapshots), more injected bugs (election livelock, stale reads), and exporting traces to standard formats for external model checkers.
Built With
- distributed-systems
- github
- javascript
- raft
- simulation
