Lockstep Protocol

[flyingrobots]

Migrated from Method backlog

This issue was created from a legacy filesystem backlog card. GitHub Issues are now the live work tracker; repository docs remain Method evidence.

Source backlog: docs/method/backlog/cool-ideas/KERNEL_splash-guy-lockstep-protocol.md
Original lane: cool-ideas
Original legend: KERNEL

Original backlog card

Milestone: Splash Guy | Priority: P2

Status: active cool idea. Task DAG issue #223 is still live.
docs/guide/course/01-lockstep.md teaches the contract, but no Splash Guy
two-peer harness exists yet.

Lockstep Protocol

Issue: #223

User Story: As a learner studying deterministic networking, I want a lockstep protocol that exchanges player inputs between two peers and verifies per-tick fingerprints so that I can see how networked determinism works in practice.

Requirements

• R1: Implement a lockstep input protocol: each peer sends its input for tick T, waits for the other peer's input, then both advance.
• R2: Each peer computes state_fingerprint after advancing and exchanges it; mismatch triggers a desync alert.
• R3: Two-peer harness: a test binary or integration harness that runs two Echo
  instances in the same process (or via loopback), exchanging inputs via
  channels.
• R4: Support configurable simulated latency (delay input delivery by N ticks) to test buffering.
• R5: Log input exchange and fingerprint comparison for debugging.

Acceptance Criteria

• AC1: Two-peer harness completes a 100-tick game with identical final state on both peers.
• AC2: Per-tick fingerprints match on both peers for all 100 ticks.
• AC3: Harness with 3-tick simulated latency still completes correctly (inputs are buffered and applied at the correct tick).
• AC4: Desync alert fires when one peer's rules are intentionally mutated (setup for controlled-desync).

Definition of Done

• Code reviewed and merged
• Tests pass (CI green)
• Documentation updated (if applicable)

Scope: Lockstep protocol, two-peer harness, fingerprint exchange, simulated latency.
Out of Scope: Real network transport (uses in-process channels); rollback/prediction; more than 2 peers.

Test Plan

• Goldens: Golden per-tick fingerprint sequence for a scripted 100-tick two-peer game.
• Failures: One peer sends no input (timeout after N ticks, harness reports stall); peer sends input for wrong tick (rejected with error).
• Edges: Both peers send identical inputs (valid, should produce identical state); zero-latency (no buffering needed).
• Fuzz/Stress: Property test: random inputs from both peers, random latency 0-10 ticks, verify fingerprint match on every tick.

Blocked By: rules-and-state
Blocking: controlled-desync

Est. Hours: 6h
Expected Complexity: ~450 LoC

[coderabbitai]

🔗 Related PRs

#175 - T1 (#169) WVP demo hardening tests [merged]
#178 - TT0 (#166) TimeStreams + wormholes spec lock [merged]
#247 - M2.1: DPO concurrency litmus (spec + tests) [merged]
#309 - feat: add Doghouse PR flight recorder [merged]
#388 - docs(method): add backlog cards and hook failure note [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!