Architecture Decision Records

Architecture Decision Records

Rusty2600 records cross-cutting architectural decisions as ADRs in Michael Nygard format (Context, Decision, Consequences), stored numbered under docs/adr/ in the repository. A superseded ADR is never rewritten in place — a new ADR supersedes and cross-links it instead.

ADR	Title	Status	Summary
0001	Integer color-clock lockstep scheduler	Accepted	The TIA color clock is the master timebase; the scheduler advances it one unit at a time, lockstep (not catch-up), so mid-scanline register writes compose correctly with no per-quirk patching. See Lockstep-Scheduler.
0002	The fractional-timebase refactor	Proposed, deferred	Integer color-clock resolution is sufficient for the 2600 (unlike consoles with sub-cycle bus-phase quirks) — likely permanently unneeded here.
0003	Accuracy-tiering honesty gate	Accepted	Every bankswitch scheme is classified Core / Curated / BestEffort; a BestEffort board can never back the accuracy oracle, enforced structurally by CI, not just documented. See Cart-Catalogue.
0004	The determinism contract	Accepted	Same seed + ROM + input sequence yields bit-identical framebuffer and audio. Power-on state is seeded from a deterministic PRNG, never the OS RNG. The foundation for save-states, rewind, run-ahead, TAS replay, and netplay rollback.
0005	TIA revision variation as flags, not a chip enum	Accepted	Real-hardware TIA fabrication-run differences are modeled as independent quirk flags rather than a closed chip-revision enum, matching Gopher2600's approach.
0006	Power-on RAM/register state is seeded, not zero, not the OS RNG	Accepted	Real hardware powers on with indeterminate RIOT RAM and CPU register contents; Rusty2600 reproduces "random-looking" boot state deterministically from a seed rather than zeroing it or using the OS RNG.
0007	Save-state format and versioning policy	Accepted	System already derives serde::Serialize/Deserialize throughout under no_std + alloc; save-states are a thin, versioned (postcard-encoded) wrapper around those existing derives, not new serialization work.
0008	Netplay WebRTC: async-runtime containment boundary	Accepted	Rusty2600 is 100% synchronous everywhere except one-time WebRTC connection setup on wasm32; the async surface is deliberately contained there and never leaks into the core simulation loop. See Netplay-and-Rollback.

Why ADRs, not just doc prose

The per-chip spec docs (docs/cpu.md, docs/tia.md, docs/riot.md, docs/cart.md) describe what the hardware does. ADRs capture why Rusty2600 is built the way it is — decisions with real alternatives that were considered and rejected, worth preserving even after the immediate context fades. Read the linked ADR source in the repository for the full Context/Decision/Consequences writeup; this page is an index, not a substitute.

See also

Architecture-Overview · Reference-Materials