docs: backfill 3 ADRs, add DRAM-refresh implementation research (#34)

docs: ADR backfill (0007-0009) + v0.5.0/v0.6.0 ladder research and CI infrastructure.

Documentation: docs/audit/ (SPC7110 boot-crash trail), Sharp S-RTC naming fixes, 3 new ADRs (versioning/release-process, ExLoROM decode-formula sourcing, ST018 detection+catch-up architecture), docs/DOCUMENTATION_INDEX.md, docs/benchmarks.md + a real Criterion headless-frame benchmark (3.27ms/frame baseline against the ~2ms target).

v0.6.0 'Shippable': SHA-256 checksums on release archives; new security.yml CI gate (cargo audit + cargo deny), verified green end-to-end, suppressing 3 documented no-upgrade-path RUSTSEC advisories after explicit review.

v0.5.0 'Fidelity' hardware-gotcha research: fixed a real doc/code drift (HDMA already fires at the hardware-correct dot 276, docs wrongly claimed scanline-boundary+deferred); $4203/$4206 multiply/divide overlap reclassified as an intentional non-goal (SNESdev errata: genuinely undefined hardware behavior); open-bus-via-HDMA-latch and the DMA/HDMA-collision crash quirk both researched to ground truth and correctly NOT force-landed after real regression risk was found (a prototype open-bus fix broke all 24 Super FX golden hashes) or no oracle existed to verify against; mid-scanline/HDMA-driven register timing — found and documented a genuine, previously-undocumented off-by-one-line compositor bug (not fixed this pass, hottest code path, no dedicated test ROM yet); hi-res color-math precision confirmed blocked on a real feature gap (no 512-wide hi-res output yet), not a precision tweak.

CI green (audit/deny/lint), all Gemini/Copilot review threads resolved, human-reviewed and approved.

Author: doublegate

.cargo/audit.toml

@@ -0,0 +1,24 @@
+# cargo-audit configuration (the "Dependency Audit" CI job, `.github/workflows/security.yml`).
+#
+# Keep this ignore list IN SYNC with `deny.toml`'s `[advisories].ignore` -- the two tools scan
+# the same RUSTSEC database and gate the same workflow. Every entry's full justification lives in
+# deny.toml; this file only mirrors the IDs. Never suppress an advisory reachable from a runtime
+# code path. Each suppression below was independently verified against RustySNES's own
+# Cargo.lock (not copied from RustyNES's equivalent file, which happens to hit the identical
+# dependency chain via the same winit/egui/wgpu frontend stack) and explicitly approved by the
+# user (2026-07-08) after review.
+
+[advisories]
+ignore = [
+    # ttf-parser unmaintained (informational, not a vulnerability) -- transitive via winit's
+    # Wayland client-side-decoration font stack (winit -> sctk-adwaita -> ab_glyph ->
+    # owned_ttf_parser -> ttf-parser 0.25.1, already the latest release); no upgrade path exists
+    # until winit's decoration stack moves off ab_glyph. Full rationale in deny.toml.
+    "RUSTSEC-2026-0192",
+    # quick-xml 0.39.4 (two real advisories) -- consumed ONLY by the wayland-scanner PROC-MACRO
+    # parsing vendored Wayland protocol XML at COMPILE TIME (trusted input, never runtime/
+    # untrusted data); no upgrade path until wayland-scanner (its own max version, 0.31.10) moves
+    # off its ^0.39 quick-xml pin. Full rationale in deny.toml.
+    "RUSTSEC-2026-0194",
+    "RUSTSEC-2026-0195",
+]

.github/workflows/release.yml

@@ -77,6 +77,21 @@ jobs:
           Compress-Archive -Force -Path $stage -DestinationPath "$stage.zip"
           Add-Content -Path $env:GITHUB_ENV -Value "ASSET=$stage.zip"
 
+      # A detached SHA-256 checksum alongside each archive, so a downloader can verify the
+      # binary they fetched matches what CI actually built without trusting GitHub's transport
+      # alone. Neither `sha256sum` (GNU coreutils — absent on macOS) nor `shasum` (Perl-based —
+      # not guaranteed present in Windows' Git-Bash `PATH`) is available on every runner this
+      # matrix uses, so try both rather than assuming one.
+      - name: Checksum
+        shell: bash
+        run: |
+          set -euo pipefail
+          if command -v sha256sum >/dev/null 2>&1; then
+            sha256sum "$ASSET" > "$ASSET.sha256"
+          else
+            shasum -a 256 "$ASSET" > "$ASSET.sha256"
+          fi
+
       # Attach to the GitHub release matching this tag, creating a minimal one first if it
       # doesn't exist yet (the release ceremony normally authors the real release notes with
       # `gh release create --notes-file` around the same time the tag is pushed — this is a
@@ -102,4 +117,4 @@ jobs:
               exit 1
             }
           fi
-          gh release upload "$TAG" "$ASSET" --repo "$REPO" --clobber
+          gh release upload "$TAG" "$ASSET" "$ASSET.sha256" --repo "$REPO" --clobber

.github/workflows/security.yml

@@ -0,0 +1,66 @@
+name: Security
+
+# Dependency-vulnerability scan (cargo-audit) + license/advisory/source policy (cargo-deny).
+#
+# Pure-documentation pushes are skipped: they cannot change Cargo.lock or any `.rs` code, so
+# there is nothing for these jobs to find. The weekly `schedule` cron still re-runs the full
+# suite, so a NEW advisory published against an unchanged dependency is still caught even when no
+# code is pushed.
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - "**/*.md"
+      - "docs/**"
+      - "ref-docs/**"
+      - "to-dos/**"
+      - "LICENSE-*"
+      - ".gitignore"
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - "**/*.md"
+      - "docs/**"
+      - "ref-docs/**"
+      - "to-dos/**"
+      - "LICENSE-*"
+      - ".gitignore"
+  schedule:
+    - cron: "0 0 * * 1"
+  workflow_dispatch:
+
+concurrency:
+  group: security-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+# Least-privilege default: neither job below writes to the repo or uploads anything -- both only
+# read the checked-out tree and Cargo.lock.
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    name: Dependency Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Install the PREBUILT binary, never `cargo install` (build-from-source): the repo pins
+      # rustc 1.96, but a from-source cargo-audit build can need a newer toolchain than that to
+      # COMPILE. The prebuilt binary runs fine under any toolchain -- it only parses Cargo.lock,
+      # it never compiles this project.
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-audit
+      - run: cargo audit
+
+  deny:
+    name: Cargo Deny Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Same rationale as the audit job: the prebuilt binary avoids needing a newer toolchain
+      # than the repo's pinned 1.96 just to build the checker itself. Policy lives in `deny.toml`.
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-deny
+      - run: cargo deny check

.gitignore

@@ -135,7 +135,6 @@ flamegraph.svg
 
 # --- Documentation ---
 /docs/_site/
-/docs/audit/
 /ref-proj/
 
 # --- Temporary files ---

CHANGELOG.md

@@ -11,6 +11,105 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Mid-scanline/HDMA-driven register timing + hi-res color-math precision: researched — `v0.5.0`
+  "Fidelity" work.** Confirmed a genuine, previously-undocumented off-by-one-line compositor bug
+  against ares' per-pixel reference model (`ppu/main.cpp`'s active-pixel rendering runs strictly
+  *before* HDMA's per-line service point): RustySNES's end-of-line compositor applies a line `V`
+  HDMA-driven register write to line `V` itself, when real hardware only ever observes it starting
+  line `V+1` (the mechanism behind Air Strike Patrol's BG3 raster scroll and any similar
+  HDMA-driven per-line effect). Corrected two related overclaims this same investigation surfaced
+  (`docs/ppu.md`'s "single-split-per-line effects work" claim, and both that doc's and
+  `crates/rustysnes-ppu/src/lib.rs`'s claim that the per-scanline compositor is unconditionally
+  "bit-identical" to a per-dot renderer). Not fixed this pass — the change touches the hottest
+  code path in the engine (every frame, all 29 currently-passing goldens) with no dedicated test
+  ROM yet to verify a fix against; full mechanism and what a fix needs documented in
+  `docs/ppu.md` §Mid-scanline/HDMA-driven register timing. Separately confirmed hi-res
+  color-math precision (Bishoujo Janshi Suchie-Pai / Marvelous+SA-1) is blocked entirely on
+  512-wide hi-res output not existing yet (ares' `DAC::run()` shows hi-res is a dual-half-pixel
+  alternating-compositor-result trick, not a numeric-precision tweak) — a real feature gap, not
+  this pass's scope; full mechanism in `docs/ppu.md` §Hi-res color-math precision. No `.rs` code
+  changed beyond doc comments; full workspace + `--features test-roms` suites verified unaffected.
+
+- **The "DMA/HDMA-collision crash quirk": researched and reclassified — `v0.5.0` "Fidelity"
+  work.** The SNESdev errata page's DMA section bundles three distinct behaviors under this
+  vague label: a version-1-5A22-only crash and a version-2-5A22-only silent-DMA-failure bug
+  (both chip-revision defects compliant commercial ROMs are written to avoid, not reproduced as
+  a crash by any mainstream reference emulator), plus a version-agnostic silent whole-frame HDMA
+  failure that's well-defined but has no known commercial title or committed test ROM depending
+  on it — no oracle exists to verify an implementation against, and the sibling open-bus
+  investigation (below) already demonstrated this exact class of change carries real regression
+  risk even when the documented mechanism is correct. A fourth item on the same errata list
+  (A-bus address restrictions) turned out to already be correctly implemented, as is the general
+  "HDMA preempts GP-DMA" priority ordering — the well-defined half of what "collision" could have
+  meant was never actually a gap. Full citation and per-sub-case reasoning in `docs/scheduler.md`.
+
+- **`security.yml` CI gate — `v0.6.0` "Shippable" work, pulled forward.** A new dedicated
+  workflow runs `cargo audit` and `cargo deny check` on every `main`/PR push touching non-doc
+  paths, plus a weekly schedule so a newly-published advisory against an unchanged dependency is
+  still caught. Added `deny.toml`, built from RustySNES's own `cargo deny list` output (not
+  copied from RustyNES's config) — independently confirms the same winit/egui/wgpu dependency
+  chain trips the identical 3 RUSTSEC advisories RustyNES already documented (`ttf-parser`
+  unmaintained via winit's Wayland decoration stack; `quick-xml`'s two advisories, reachable only
+  through `wayland-scanner`'s compile-time XML parsing of trusted vendored protocol files, never
+  runtime input). Suppressed in `deny.toml` + the new `.cargo/audit.toml` with the full
+  rationale, after explicit review and approval.
+
+- **Checksummed release assets (SHA-256) — `v0.6.0` "Shippable" work, pulled forward.**
+  `.github/workflows/release.yml` gained a `Checksum` step that emits a detached `<archive>.sha256`
+  alongside each platform's packaged binary archive, portable across the three runner shells
+  (tries `sha256sum`, falls back to `shasum -a 256`, since GNU coreutils' `sha256sum` is absent on
+  macOS runners and Perl's `shasum` isn't guaranteed on Windows' Git-Bash `PATH`); the upload step
+  now attaches both files. Not yet exercised end-to-end against a real tag.
+
+- **`docs/benchmarks.md` + a real Criterion benchmark — `v0.6.0` "Shippable" work, pulled
+  forward.** The first-ever measured performance number on this codebase:
+  `crates/rustysnes-core/benches/headless_frame.rs` (Criterion 0.7) measures headless full-frame
+  throughput against a real committed test ROM (`tests/roms/undisbeliever/inidisp_hammer_0f00.sfc`,
+  chosen for no coprocessor/DMA-heavy content so the measurement isolates the base
+  CPU+PPU+scheduler cost). Result: **3.27 ms/frame** steady state, against `docs/performance.md`'s
+  ≤~2ms target — real-time headroom is fine (~5.1× at NTSC's 16.64ms/frame budget), but the
+  target itself isn't met yet. Documented honestly as a baseline to measure future optimization
+  against, not a claim of having hit the target.
+
+- **`docs/DOCUMENTATION_INDEX.md` — `v0.6.0` "Shippable" work, pulled forward.** The full
+  documentation map (subsystem specs, ADRs, testing strategy, `ref-docs`/`ref-proj`/`to-dos`
+  cross-references, external hardware-reference links), matching RustyNES's own index and linked
+  from the README.
+
+- **`$4203`/`$4206` multiply/divide overlap: researched and correctly reclassified — `v0.5.0`
+  "Fidelity" work, in progress.** The 65816 hardware-gotcha list named this as an open item;
+  research against SNESdev's own Errata page shows starting a new multiply/divide while a
+  previous one's 8-cycle latency hasn't elapsed produces genuinely **undefined** `RDMPY`/`RDDIV`
+  output — no canonical corrupted value is documented anywhere to port, and fabricating one would
+  violate the determinism contract's spirit (`docs/adr/0004`). `MulDiv`'s doc comment now cites
+  the errata directly and explains why this stays a documented non-goal rather than an open gap.
+  Added a regression test locking in the well-defined case real hardware *does* document (MPYA
+  is a stable latch; a fresh `$4203` write alone starts another multiply against whatever it
+  already holds, no `$4202` rewrite needed).
+
+- **ADR backfill: 3 new ADRs, `v0.5.0` "Fidelity" / `v0.6.0` "Shippable" work, in progress.**
+  `docs/adr/0007` (the versioning/release-process adoption itself — the named `v0.x.0` ladder,
+  the tag-body-is-the-release-note convention), `docs/adr/0008` (why the ExLoROM decode formula
+  is sourced from bsnes's runtime board database rather than extrapolated from LoROM or the
+  header-detection heuristic), and `docs/adr/0009` (ST018's title-match detection method, kept
+  consistent with the rest of the `$F`-nibble coprocessor family rather than reading the
+  `$xFBF` byte other customs are known-unreliable against; and the `Board::coprocessor_tick`
+  catch-up architecture chosen over the SA-1 second-CPU hooks, since ST018's ARM core is
+  self-contained in `rustysnes-cart` unlike SA-1's second 65C816). Also adds implementation
+  guidance for the still-unstarted DRAM-refresh hardware-gotcha fix to `docs/scheduler.md`,
+  surfacing a real architectural tension this project's CPU-driven master clock has with real
+  hardware's independent video-timing generator that needs resolving empirically (against the
+  full golden-framebuffer suite) before that fix lands, not assumed safe up front.
+
+- **`docs/audit/` — `v0.6.0` "Shippable" work, pulled forward.** A new decision-rationale /
+  open-investigation directory (modeled on RustyNES's own `docs/audit/`), seeded with the full
+  SPC7110 boot-crash trail: the `v0.4.0`-landed `bus_mirror` addressing fix (confirmed root
+  cause #1) and the still-open gap (root cause #2, narrowed to two candidate hypotheses, not
+  yet fixed) that keeps Far East of Eden Zero from booting to real content. Also fixed two
+  remaining "Sharp RTC-4513" naming errors (`docs/cart.md`, `coproc::sharprtc`'s module/struct
+  docs) — the standalone Sharp S-RTC has no established "4513" part number anywhere; that number
+  belongs only to the different Epson chip paired with SPC7110.
+
 - **`docs/STATUS.md`: an accuracy dashboard — `v0.5.0` "Fidelity" work, in progress.** RustySNES
   has no single monolithic oracle ROM the way RustyNES's AccuracyCoin does (an early skeleton for
   exactly that approach, `rustysnes-test-harness::accuracy_battery`, ticket T-04, was never