Architecture Decision Records

Architecture Decision Records (ADRs)

RustySNES uses Architecture Decision Records to document major structural and cross-cutting decisions. These follow the Michael Nygard format (Context / Decision / Consequences) and live in the docs/adr/ directory of the repository.

Below is an index of the current ADRs:

• ADR 0001: Master-Clock Lockstep Scheduler + the SPC700 Second Clock Domain (Accepted) — Advancing a single master clock and stepping every chip on its own divisor, rather than catch-up scheduling, to make mid-instruction PPU/DMA events correct without per-quirk patches. See Lockstep-Scheduler.
• ADR 0002: The Fractional-Timebase Refactor (Proposed) — A future sub-cycle (phi1/phi2-split) master-clock model to close any hard-tier accuracy residuals the current whole-tick model can't reach. Designed in from day one but the refactor itself is deferred until the accuracy program demonstrates it's actually needed; flagged as the one future release expected to break save-state compatibility.
• ADR 0003: The Coprocessor Accuracy-Tiering Honesty Gate (Accepted) — The SNES has a dozen-plus in-cart coprocessors of wildly varying verifiability. Rather than report one flat "N coprocessors supported" number, each board is tiered (Core/Curated/BestEffort) and a CI gate enforces that the tier claim matches what's actually validated — never silently presenting an approximate or unverified board as accurate.
• ADR 0004: The Determinism Contract (Accepted) — Same seed + ROM + input sequence must yield a bit-identical framebuffer and audio stream. Real-hardware SPC700/S-DSP resonator drift and real-time-clock coprocessors (S-RTC, SPC7110's paired RTC) are deliberately frozen out of the deterministic core path, since both are genuine non-determinism sources on real hardware. Required for save-state round-trips and any future rollback netplay or TAS replay.
• ADR 0005: The 65816 Per-Opcode Oracle — Self-Generate, Cross-Validate, Commit (Proposed) — The primary CPU-accuracy oracle candidate (a SingleStepTests-style 65816 JSON corpus) ships with no license, unlike its spc700 sibling suite. This ADR resolves how the CPU oracle is sourced given that constraint.
• ADR 0006: The Save-State Binary Format + Versioning Policy (Accepted, shipped in v0.2.0 "Persistence") — A versioned envelope (magic + format-version header) wrapping every subsystem's own save_state/load_state, proven by a round-trip determinism test rather than merely asserted. The prerequisite every downstream feature that snapshots/restores state (rewind, run-ahead, and eventually netplay rollback and TAS replay) builds on.

These ADRs record the why behind cross-cutting decisions — the rationale doesn't belong in commit messages or the CHANGELOG, since both fade from view as the codebase evolves.