docs: tighten DMG hardening handbook consistency

Author: pakitovic

AI/ARCHITECTURE.md

@@ -301,6 +301,7 @@ to immediately materialize as a separate directory.
 - watchpoints
 - snapshots
 - state inspection
+- targeted subsystem viewers or equivalent structured dumps for CPU, scheduler, PPU, DMA, APU, IRQ, and cartridge state
 - internal analysis and comparison tools
 - utilities for synchronization and trace-debug workflows
 

AI/REFERENCES.md

@@ -18,15 +18,21 @@ Primary documentation should be consulted before using emulator source code as g
 ## Test ROMs and executable references
 
 - blargg test ROMs
+- retrio/gb-test-roms — https://github.com/retrio/gb-test-roms
 - dmg-acid2 — https://github.com/mattcurrie/dmg-acid2
 - cgb-acid2 — https://github.com/mattcurrie/cgb-acid2
 - mealybug-tearoom-tests — https://github.com/mattcurrie/mealybug-tearoom-tests
 - Mooneye GB test suite — https://github.com/Gekkio/mooneye-gb
+- SameSuite — https://github.com/LIJI32/SameSuite
+- GB Accuracy Tests — see the awesome-gbdev testing section below
+- 144p Test Suite — see the awesome-gbdev testing section below
+- MBC3 RTC test ROMs — see the awesome-gbdev testing section below
 
 ## Community indexes
 
 - gbdev resources — https://gbdev.io/resources/
 - awesome-gbdev — https://github.com/gbdev/awesome-gbdev
+- use the awesome-gbdev testing section to discover and cross-check broader external DMG-closure suites that are not listed above directly
 
 ## Audio references
 
@@ -61,10 +67,10 @@ This default order balances coverage, maintainability, and accessibility; it is
 
 ## Practical specialization by reference
 
-- SameBoy: best general reference and the practical ceiling for DMG/CGB behavior, LCD timing, audio, and compatibility study.
+- SameBoy: best general reference and the practical ceiling for DMG/CGB behavior, LCD timing, audio, and compatibility study; use it as the primary DMG differential oracle when comparable traces or observables are available.
 - binjgb: strong reference for timing, CPU/bus behavior, and compact architecture.
 - GameRoy: useful reference for idiomatic Rust-oriented structure.
 - accurateboy: especially valuable for PPU, fetcher, and pixel FIFO behavior.
 - Mooneye GB: strong documentary and edge-case reasoning reference.
 - Danger Boy: useful smaller codebase for DMG timing study.
-- Gambatte: historical high-accuracy reference and a strong corroborating oracle for practical accuracy and corner cases.
+- Gambatte: historical high-accuracy reference and a strong corroborating oracle for practical accuracy and corner cases; use it as the secondary DMG differential oracle when triangulation or arbitration is needed.

AI/ROADMAP.md

@@ -1157,6 +1157,68 @@ Build the audio subsystem as a real temporal part of the hardware, integrated wi
 
 ---
 
+### Phase 8 — Block AP: final DMG hardening, differential validation, and closure
+
+This phase is the roadmap home for the final DMG closure work. Parts of it should begin earlier, but the block only closes once the project can justify DMG correctness through layered evidence on the shared T-cycle model rather than through informal game compatibility.
+
+#### Goal
+
+Close the DMG core with a formal validation matrix, strong differential and determinism tooling, and explicit closure criteria that leave no major blind hardware areas behind.
+
+#### Modules involved
+
+- `tests/`
+- `gb-test-runner/`
+- `debugger/`
+- `scheduler/`
+- subsystem cores as needed for per-area traces and inspections
+- frontend or tooling adapters only where they are needed for capture, visualization, or artifact export
+
+#### Deliverables
+
+- formal DMG hardening matrix with layers `A/B/C/D/E`, severity classes, and explicit `must-pass` areas
+- automated external-ROM harness with timeout, pass/fail policy, framebuffer and serial capture, and retained failure artifacts
+- differential comparison tooling for SameBoy and Gambatte with first-divergence reporting and short T-cycle windows
+- deterministic replay, save/load determinism, and longer-running soak coverage
+- minimum closure-ready debugging tooling: traces, breakpoints, watchpoints, snapshots, and targeted subsystem viewers
+- explicit DMG closure checklist covering internal suites, external suites, differential comparison, determinism, save/load determinism, and primary cartridge families
+
+#### Recommended sequencing inside Phase 8
+
+1. Formalize the DMG hardening matrix and closure severity policy.
+   Scope: define layers `A/B/C/D/E`, `must-pass` versus non-blocking categories, minimum DMG closure suites, and the rule that no single layer substitutes for another.
+   Acceptance criteria: the project docs name the closure layers explicitly, identify the blocking hardware areas for DMG closure, and define a stable checklist instead of relying on informal compatibility claims.
+2. Build the external ROM harness and minimum closure suites.
+   Scope: automate CPU / interrupt ROMs, `dmg-acid2`, and `mealybug-tearoom-tests`; support framebuffer and serial capture; define timeouts, pass/fail rules, and retained artifacts; and keep explicit reserved follow-up slots for broader closure suites such as Mooneye / Gekkio coverage, SameSuite, GB Accuracy Tests, 144p Test Suite, and MBC3 RTC-focused ROMs.
+   Acceptance criteria: the minimum DMG closure ROM suites run without manual screen inspection, every case has a timeout plus explicit pass/fail policy, and the harness can preserve enough output to debug failures offline.
+3. Add differential comparison against SameBoy and Gambatte.
+   Scope: end-of-test comparison, end-of-instruction comparison, short T-cycle-window comparison, and first-divergence localization with archived context.
+   Acceptance criteria: SameBoy acts as the default primary DMG oracle, Gambatte is available for triangulation, disagreements between the oracles are marked for arbitration rather than auto-pass, and the tooling can report the first divergence instead of only a final mismatch.
+4. Close the minimum debugging and inspection tooling.
+   Scope: instruction / micro-op / short-window T-cycle tracing, breakpoints and watchpoints on `PC`, memory, MMIO, and cartridge-bank state, plus fast inspection of CPU, scheduler, bus owner, PPU mode / dot / `LY`, DMA, timer, APU, and cartridge / MBC state.
+   Acceptance criteria: a blocking divergence can be localized without a long blind rerun, and the project has practical viewers or equivalent dumps for PPU, cartridge / MBC, APU, and IRQ state.
+5. Lock determinism, replay, save/load determinism, soak, and regression retention.
+   Scope: same-ROM replay with identical input stream and injected time source, mid-run save/load equivalence, longer-running soak cases, and a permanent regression path for every important hardening bug.
+   Acceptance criteria: repeated runs converge exactly under the same inputs and injected time source, save/load continuation matches uninterrupted execution, soak coverage includes at least one real game plus long-running synthetic coverage, and fixed hardening bugs leave behind permanent regression assets.
+
+#### Done criteria
+
+- core unit and short integration suites for the blocking DMG areas are green
+- the minimum external closure suites are green
+- differential comparison either shows no unexplained divergence in the covered scenarios or records the remaining arbitrations explicitly
+- deterministic replay and save/load determinism are green
+- no severe open correctness bugs remain in `NoMbc`, `Mbc1`, `Mbc2`, `Mbc3`, or `Mbc5`
+- the project has an explicit DMG closure checklist instead of relying on a general compatibility impression
+
+#### Risks if omitted or overly simplified
+
+- false confidence from a few booting games or one passing smoke suite
+- unresolved blind spots in scheduler ordering, timing, or cartridge behavior
+- repeated rediscovery of the same bugs because regressions were never turned into permanent assets
+- inability to explain oracle divergences without expensive manual debugging sessions
+
+---
+
 ## Final order summary
 
 1. Test model and test ROM strategy  
@@ -1203,6 +1265,11 @@ Build the audio subsystem as a real temporal part of the hardware, integrated wi
 35. APU channel 3
 36. APU channel 4
 37. Mixing, output, DACs, power control, and audio edge cases
+38. Formal DMG hardening matrix, severity classes, and closure checklist
+39. Automated external ROM harness and minimum closure suites
+40. Differential comparison against SameBoy and Gambatte
+41. Deterministic replay, save/load determinism, and soak coverage
+42. Final DMG closure and regression-retention pass
 
 ---
 
@@ -1252,6 +1319,10 @@ Suggested entry style:
 
 - None currently.
 
+### Phase 8 — Block AP: final DMG hardening, differential validation, and closure
+
+- None currently.
+
 ---
 
 ## Final notes

AI/TESTING.md

@@ -8,6 +8,7 @@ Use multiple layers:
 - subsystem integration tests
 - ROM-based validation
 - oracle comparisons where useful
+- determinism, replay, and longer-running regression coverage
 
 ## Authority and scope
 
@@ -25,6 +26,49 @@ Every subsystem change should aim to leave behind one of these:
 - a documented oracle comparison when timing or ordering is under review
 - a characterization test before structural refactors in behavior-sensitive code
 
+## Final DMG hardening policy
+
+- Do not treat "boots a few commercial games" or "one final framebuffer looks right" as DMG closure.
+- Final DMG hardening must demonstrate, at the same time, subsystem-local correctness, deterministic behavior on the shared T-cycle timeline, differential agreement with trusted oracles, and enough tooling to explain a divergence without blind refactoring.
+- Use a formal multilayer validation matrix rather than one oversized suite or informal compatibility anecdotes.
+- No single layer substitutes for another: unit tests do not replace test ROMs, test ROMs do not replace differential comparison, and differential comparison does not replace determinism or replay.
+
+## Final DMG hardening matrix
+
+- `Layer A`: focused unit tests per subsystem, including CPU micro-ops and state machine behavior, interrupts and `IME` / `HALT` / `STOP`, timer and divider edges, bus arbitration, PPU mode timing plus fetcher/FIFOs/window/sprites, DMA, joypad, serial, cartridge/MBC behavior, APU channel and mixer behavior, and exact save-state restore paths.
+- `Layer B`: short integration tests for timing-coupled interactions such as timer plus interrupts, DMA plus bus plus CPU, PPU plus DMA plus VRAM/OAM blocking, serial plus interrupt plus scheduler, joypad plus `STOP` / `HALT` plus interrupt, cartridge plus bus plus boot-ROM overlay, and APU plus `DIV-APU` plus MMIO writes.
+- `Layer C`: external test ROM suites grouped by hardware category and run through automation rather than manual screen inspection.
+- `Layer D`: differential comparison against trusted emulator oracles, with the ability to localize the first divergence instead of reporting only one final mismatch.
+- `Layer E`: determinism, replay, save/load determinism, soak, and regression-retention coverage over medium and long runs.
+- For this T-cycle-based core, the matrix should support several validation granularities: end of test, end of instruction, and short per-T-cycle windows when a timing-sensitive divergence needs to be isolated.
+- Every corrected bug should end up attached to at least one permanent layer in this matrix.
+
+## External ROM harness policy
+
+- Test ROM execution must be automatable; manual inspection of the LCD is an auxiliary debugging aid, not the primary acceptance path.
+- The harness should support at least framebuffer capture and serial / link-port capture when the ROM exposes machine-readable output there.
+- Prefer serial / link-port capture for suites such as Blargg `cpu_instrs` when that path is available, because it avoids treating a scrolling framebuffer as the primary machine-readable result channel.
+- Each ROM case should define a timeout, an explicit pass/fail rule, and retained failure artifacts such as serial output, framebuffer output, trace excerpts, and optional snapshots.
+- The minimum DMG closure baseline should include automated CPU / interrupt coverage through `retrio/gb-test-roms` or equivalent Blargg automation, `dmg-acid2` for basic DMG PPU validation, and `mealybug-tearoom-tests` for fine PPU rendering / timing validation.
+- Keep explicit roadmap space for broader closure suites such as Mooneye / Gekkio coverage, SameSuite, GB Accuracy Tests, 144p Test Suite, and MBC3 RTC-focused ROMs.
+
+## Differential oracle policy
+
+- Use SameBoy as the primary differential oracle for DMG behavior whenever comparable observables are available.
+- Use Gambatte as a secondary oracle when triangulation adds value or when a SameBoy-only result still needs corroboration.
+- Differential comparison should support at least three granularities: end of test, end of instruction, and short T-cycle windows for reduced scenarios.
+- Prefer a clear "first point of divergence" workflow over one final hash or framebuffer mismatch.
+- When SameBoy and Gambatte agree and this project differs, treat the discrepancy as a project bug by default until evidence shows otherwise.
+- When the oracles disagree, mark the case as requiring arbitration rather than silently accepting one side as correct.
+
+## Validation tooling requirements
+
+- Hardening-ready validation requires trace logging at instruction level, micro-op level, and short T-cycle windows.
+- Breakpoints and watchpoints should cover at least `PC`, memory addresses, MMIO registers, and cartridge-bank or mapper-visible state.
+- Fast state inspection should expose CPU, scheduler, current bus owner, PPU mode / dot / `LY`, active DMA state, timer pipeline state, APU state, and cartridge / MBC state.
+- Specialized debug views for PPU internals, cartridge / MBC banks and raw registers, APU channels plus final mix, and IRQ / `IF` / `IE` / `IME` state are strongly recommended because they shorten divergence analysis substantially.
+- Instrumentation must not alter the core's hardware-visible behavior or reorder the shared T-cycle timeline.
+
 ## New-code baseline
 
 - New production code should normally introduce automated unit tests or integration tests in the same change.
@@ -155,10 +199,15 @@ Include dedicated CH4 quirk tests for ordinary `15`-bit mode, ordinary `7`-bit m
 
 ## Recommended external validation sources
 
+- retrio/gb-test-roms
 - blargg test ROMs
 - Mooneye tests
 - dmg-acid2 / cgb-acid2
 - mealybug-tearoom-tests
+- SameSuite
+- GB Accuracy Tests
+- 144p Test Suite
+- MBC3 RTC test ROMs
 
 ## Behavioral cross-check policy
 
@@ -174,13 +223,34 @@ When a change affects observable timing or ordering:
 - Tests should prefer reproducible stepping and explicit expected state over fuzzy assertions.
 - Instrumentation should not change hardware-visible behavior.
 - Battery-backed RTC persistence tests must use an injected or otherwise explicit time source rather than the host wall clock.
+- Determinism coverage should include replay from the same ROM plus input stream, save/load determinism, and at least some longer-running soak cases.
+- "Same ROM + same input stream + same injected time source => same result" is the intended project contract.
+- Save/load determinism should prove that saving, restoring, and continuing produces the same result as uninterrupted execution.
+- Soak coverage should include at least one real game, one longer-running test ROM, and one or two cases with APU activity plus banked cartridges.
 
 ## Regression policy
 
-Every fixed bug should leave behind:
+- Every fixed bug should leave behind at least one permanent regression asset.
+- Use a focused unit or integration test when the bug is local to one subsystem or one cross-subsystem interaction.
+- Use a ROM-based reproduction case when the bug is systemic or easiest to demonstrate through an external suite.
+- Use a stored differential case when the bug was discovered by comparison against SameBoy, Gambatte, or another explicit oracle.
+- Keep regression organization by subsystem or hardware area so repeated failures do not disappear into one catch-all bucket.
+- Differential regressions should preserve enough reproduction context to rerun them quickly, including the ROM, input stream, injected seed or time source when relevant, first divergence point, and an optional snapshot when that reduces debug time.
+
+## Severity and DMG closure policy
+
+- Classify failures by closure impact instead of treating all red tests as equally important.
+- Treat scheduler ordering, CPU / interrupts, timer, PPU timing, DMA, primary cartridge families, basic joypad / serial behavior, and save/load determinism as `must-pass` DMG closure areas.
+- Treat finer APU behavior, serial edge cases beyond the baseline path, and RTC-specific long-tail work as high-importance compatibility items unless the roadmap explicitly promotes them to `must-pass`.
+- Keep optional tooling polish, special-cartridge heuristics, and experimental paths outside the `must-pass` gate unless they are needed to explain or reproduce a blocking core bug.
+- Do not declare DMG closed while `NoMbc`, `Mbc1`, `Mbc2`, `Mbc3`, or `Mbc5` still have open severe correctness bugs, or while CPU / interrupts, timer, PPU, DMA, basic joypad / serial, or save/load determinism coverage is still failing.
+- Keep a project-visible DMG closure checklist that includes internal core suites, minimum external suites, differential comparison, determinism, save/load determinism, and primary cartridge-family status.
+
+## CI stratification policy
 
-- a focused automated test, or
-- a documented ROM-based reproduction case
+- The regular CI path should always run critical unit tests, critical short integration tests, a stable subset of external ROMs, and save/load determinism coverage.
+- Longer differential runs, soak tests, and broader external ROM inventories may live in nightly or manual suites, but they must remain documented and runnable.
+- Failure artifacts should include enough information to debug without rerunning blindly, such as logs, optional snapshots, framebuffer output when relevant, and a diff against the reference output when one exists.
 
 ## Test organization policy
 

AI/TIMING-AND-ACCURACY.md

@@ -39,6 +39,15 @@ When implementing timing:
 - state which source supports the model
 - avoid claiming global cycle accuracy from local evidence
 
+## Closure and validation claims
+
+- Do not treat "boots a few games" as evidence that DMG timing is closed.
+- Do not treat one matching final framebuffer as sufficient evidence for a timing-sensitive subsystem when the path to that output is still unverified.
+- Closing a timing-sensitive DMG subsystem should rest on layered evidence: focused automated tests, ROM-based validation, trusted-oracle comparison, and determinism checks.
+- Because this project is T-cycle based, the validation stack should be able to compare behavior at end-of-test, end-of-instruction, and short per-T-cycle windows when locating the first divergence matters.
+- If coarser summaries are used for ergonomics, keep a path back to the underlying T-cycle ordering rather than hiding it behind aggregate instruction or frame-level claims.
+- Trace, comparison, and debugging instrumentation must preserve the same hardware-visible T-cycle behavior they are trying to explain.
+
 ## Modeling policy
 
 - Prefer explicit clock ownership.