Heartbeat

This page is the guide for anyone landing on the deployed site rather than the repo directly. The workshop itself, nine modules covering RPC through sharding plus a synthesis capstone, lives in the repo, whose own README covers the same ground in more detail once you've cloned it. Nothing here substitutes for cloning it; this is orientation, not the content.

Why a network, not a compiler, is the gate here

A correct-looking Raft implementation can pass every unit test and still lose committed data the first time a network partition heals badly. Heartbeat's premise is that the fix isn't more reading, it's a gate that can actually see network faults, not just type errors. Every exercise runs through your own coding-agent harness (Claude Code, Codex, or equivalent) against turmoil, a simulator that drops, delays, reorders, and partitions traffic on command, across a published set of seeds, not just one. A single arbitrary seed can get lucky in a way a compiler error never can, which is why the deterministic tier here means green across the whole seed set, not green once.

Two gates, not one

First, the deterministic gate: your implementation runs against a fixed, published set of turmoil seeds, no judgment call. Second, a conceptual gate: Coachgremlin, this workshop's teaching agent (a role you run yourself, inside your own harness, not a hosted service), checks whether you can explain why your implementation is safe, not just that it happened to survive every seed tried so far. A green deterministic tier is necessary, never sufficient on its own: this subject has more genuine open risk than most, since a broken implementation can pass a test by luck.

MIT 6.5840 already exists. This isn't a replacement for it.

MIT's 6.5840 ("Distributed Systems," formerly 6.824) is the field's dominant free teaching resource, and the reason this workshop didn't have to invent a lab sequence from scratch. Heartbeat's arc follows 6.5840's own real lab order: RPC, then a single-node KV service built before Raft exists (not after, the more obvious-sounding order this workshop's own research initially got wrong), then Raft itself in its four real parts, then a fault-tolerant KV service wrapping that Raft, then sharding. What Heartbeat adds is a Rust implementation, agent-native delivery, a deterministic-plus-conceptual gate instead of a bare pass/fail, and a keepable takeaway per module. See the repo's docs/workshop-design.md for the full curriculum-anchor research, including that correction.

What you walk away with

Two different things get built during each module: your own judgment, and a reusable artifact your agent can load next time. See each module's own README (once authored) for the evidence behind its specific gate.

• You get practiced judgment: diagnosing a failing seed instead of just rerunning it, reasoning about what a crash mid-replication actually has to survive, and telling apart a harness bug from a Raft bug.
• Your agent gets the packaged takeaways: a network-fault-injection harness template, an API-design checklist, a leader-election diagnostic playbook, a log-matching checklist, a crash-survival checklist, a snapshot-boundary decision guide, a layering playbook, a shard-ownership checklist, and a personal distributed-systems diagnostic playbook tying it all together.

The runbook

1. Prerequisites: comfortable with git, the CLI, and reading a diff; fluent in Rust (ownership, borrowing, traits, async/await, the level borrow-native teaches to); already using a coding-agent harness regularly; Rust and cargo installed.
2. Clone it: git clone https://github.com/coderturtle/heartbeat.git
3. Start at modules/README.md. It has the full arc, in order, and a table of what each module's gate requires and what you keep from it.
4. Work through the nine modules in order: RPC, a single-node KV service, the four parts of Raft, a fault-tolerant KV service on Raft, sharding, then the synthesis capstone. Each states a hard prerequisite on an earlier one.
5. No module completes by reading it. Every module states a required gate, checked first mechanically against a real, adversarial simulated network, then conceptually. If a module ever reduces to "read this, then move on," or a link here is broken, that's a defect: open an issue.

Current status

All nine modules are skeleton only: a decided question, arc position, gate shape (including a named fault scenario), and takeaway shape, but no authored exercise yet. That's real work still ahead, not a formality. Watch the build log below for progress.