docs: unify compatibility policy handbooks

Author: pakitovic

AI/ARCHITECTURE.md

@@ -114,6 +114,27 @@ For an early-stage repo, a simplified equivalent is acceptable as long as these
 - When CGB arrives, prefer one standard CGB model before attempting fine-grained CGB hardware revision support.
 - Architecture should allow the same core to run in DMG-family mode or CGB mode without duplicating subsystem implementations.
 
+## Compatibility-policy architecture
+
+- Compatibility policy is a loader/config contract around the T-cycle core, not a second hardware model.
+- The project should expose a typed execution-mode concept such as `ExecutionMode::{Strict, Permissive, Experimental}` rather than scattered booleans.
+- The project should expose one central `CompatibilityPolicy`-style structure, or an equally explicit equivalent, that at least carries:
+  - `execution_mode`
+  - `validation_policy`
+  - `heuristic_policy`
+  - `override_policy`
+  - `diagnostic_policy`
+- One central decision point should translate typed cartridge classification, the active compatibility policy, and explicit manual overrides into a final load decision.
+- That decision point must not reparse cartridge headers differently per frontend, per mode, or per call site.
+- For already supported hardware, switching execution mode must not change T-cycle-visible hardware truth such as timing, arbitration, memory mapping, IRQ behavior, or mapper semantics.
+- Mode changes are allowed to affect admission, validation severity, heuristic enablement, manual overrides, diagnostics, and access to explicitly experimental implementations.
+- Any temporary exception where a mode changes supported-hardware runtime behavior should be documented as technical debt rather than normalized as ordinary behavior.
+- `Strict` is the oracle and CI mode for official accuracy claims.
+- `Permissive` is the intended tolerant interactive mode for ordinary users once frontends expose mode selection.
+- `Experimental` is for research, bring-up, and partial hardware paths; it must not be treated as evidence for official accuracy claims.
+- Save states, replays, and official test artifacts must record the execution mode and active overrides that produced them.
+- Restoring or replaying under a different execution mode should fail by default unless a later explicit developer-only conversion workflow is designed on top of the recorded metadata.
+
 ## Suggested subsystem boundaries
 
 - CPU: instruction flow, register state, decode/execution state, fine-grained fetch/read/write/internal steps, IME state, interrupt acceptance/dispatch, HALT/STOP semantics, and micro-operation visibility for timing-sensitive hardware interactions
@@ -142,6 +163,7 @@ to immediately materialize as a separate directory.
 - system base types
 - enums for hardware variants and shared configuration
 - structural core configuration
+- shared compatibility-policy types such as execution mode and override metadata
 - architectural extension points for future variants such as CGB
 
 ### `scheduler/`
@@ -266,8 +288,9 @@ to immediately materialize as a separate directory.
 - typed cartridge-header parsing over `0x0100-0x014F`
 - decoded cartridge capability model including cartridge type, ROM size, RAM size, CGB flag, and SGB flag
 - explicit capability metadata for battery-backed RAM, RTC, and rumble derived from the validated header type
-- central cartridge factory and validation policy
+- central cartridge factory, compatibility-policy consumption, and validation policy
 - typed loader result that separates supported cartridge construction from structured special / unsupported classification, preserving raw `0x0147`, detected name, category, and reason
+- one central load-decision path that combines cartridge classification, compatibility policy, and explicit overrides into admit / warn / reject results
 - concrete cartridge devices such as `NoMbcCartridge`, `Mbc1Cartridge`, `Mbc2Cartridge`, `Mbc3Cartridge`, and `Mbc5Cartridge`
 - No MBC family support, including the `0x00`, `0x08`, and `0x09` header variants
 - MBC implementations
@@ -313,6 +336,7 @@ to immediately materialize as a separate directory.
 - Storage backends such as disk or in-memory adapters should own serialization format, versioning, file naming, path mapping, timestamps, and atomic replacement policy, not cartridge semantics.
 - Frontend and tooling layers may decide when to flush, such as on close, on explicit manual save, or via optional auto-flush, but they should do so through the persistence backend rather than through bus hooks or cartridge-local file I/O.
 - Cartridge persistence and emulator save states must remain separate systems. Cartridge persistence stores only cartridge-owned hardware state; emulator save states may snapshot the whole machine.
+- Emulator save states and replays should also preserve the execution mode and active compatibility overrides that were in effect when they were created.
 - Tests and tools must be able to use an in-memory persistence backend so cartridge persistence can be validated without host file I/O.
 
 ## Module mapping notes

AI/ROADMAP.md

@@ -383,8 +383,11 @@ They do not move full joypad, serial, audio, or timing-complete PPU implementati
    Acceptance criteria: the bus can read `0x0000-0x7FFF` and `0xA000-0xBFFF` without knowing the active MBC, ROM-space writes route to cartridge commands, and header bytes remain visible through ordinary ROM bank `0` reads.
 3. Add the cartridge factory.
    Acceptance criteria: the loader selects `NoMbc`, `Mbc1`, `Mbc2`, `Mbc3`, `Mbc5`, or a structured special / unsupported classification from `0x0147`, and unsupported types preserve raw `0x0147`, detected name, category, and reason for diagnostics.
-4. Close validation and diagnostics policy.
-   Acceptance criteria: ROM-size and RAM-size metadata are checked explicitly, size mismatches produce useful warnings or errors, special ROM-size codes are not ignored silently, documented-but-unsupported cartridge types fail in a controlled way without mapper fallback, and the project exposes a configurable strict-versus-permissive policy with heuristics disabled by default in strict mode.
+4. Define the typed compatibility-policy model.
+   Scope: one real `ExecutionMode::{Strict, Permissive, Experimental}` type plus a central `CompatibilityPolicy`-style structure carrying validation, heuristic, override, and diagnostic policy.
+   Acceptance criteria: execution modes are not represented as scattered booleans, one shared policy object exists for loader, tooling, and frontends, and the T-cycle core does not need to read ad hoc global compatibility flags.
+5. Close validation and diagnostics policy.
+   Acceptance criteria: ROM-size and RAM-size metadata are checked explicitly, size mismatches produce useful warnings or errors, special ROM-size codes are not ignored silently, documented-but-unsupported cartridge types fail in a controlled way without mapper fallback, and the project exposes a central strict / permissive / experimental policy with heuristics disabled by default in strict and permissive modes.
 
 ##### No MBC milestone
 
@@ -397,10 +400,25 @@ They do not move full joypad, serial, audio, or timing-complete PPU implementati
 4. Add optional external RAM.
    Acceptance criteria: `0xA000-0xBFFF` is either explicit "RAM absent" behavior or one linear `8 KiB` RAM window; there is no RAM enable, no RAM banking, no RTC, and battery only changes persistence policy.
 5. Harden validation and diagnostics.
-   Acceptance criteria: No MBC expects `32 KiB` ROM and at most `8 KiB` RAM, inconsistent headers report declared type, declared ROM size, declared RAM size, and actual file size, `0x08` and `0x09` may warn as rare but are not rejected solely for rarity, and strict/permissive/test modes remain configurable.
+   Acceptance criteria: No MBC expects `32 KiB` ROM and at most `8 KiB` RAM, inconsistent headers report declared type, declared ROM size, declared RAM size, and actual file size, `0x08` and `0x09` may warn as rare but are not rejected solely for rarity, and strict / permissive / experimental mode handling stays centralized.
 6. Close integration coverage.
    Acceptance criteria: skip-boot and post-`FF50` mapping tests use No MBC as the first closed cartridge baseline in this phase; once Phase 2 real-boot execution exists, the first real-boot cartridge coverage also lands on No MBC before any MBC-dependent validation.
 
+#### Compatibility-policy sequencing across cartridge bring-up
+
+1. Model the policy types.
+   Scope: `ExecutionMode::{Strict, Permissive, Experimental}` plus a central `CompatibilityPolicy` or equivalent.
+   Acceptance criteria: execution modes are real types rather than loose booleans, and loader, tooling, and frontends consume one shared compatibility-policy shape.
+2. Centralize the category-by-mode decision table.
+   Scope: resolve `Supported`, `PlannedVariant`, `DocumentedButUnsupported`, `ExperimentalHeuristic`, `AccessorySpecialCase`, and `UnknownCode` through one shared matrix driven by typed cartridge classification.
+   Acceptance criteria: load / warn / reject behavior is decided centrally, the loader does not duplicate per-mode classification logic, and `Strict`, `Permissive`, and `Experimental` keep supported-hardware runtime semantics identical.
+3. Close diagnostics and manual overrides.
+   Scope: explicit rejection and warning reasons, visible heuristic and partial-path diagnostics, and manual overrides for model, mapper, mode, and validation policy.
+   Acceptance criteria: loader messages report raw `0x0147`, detected name, category, current mode, and precise reason; overrides are visible in logs and tooling; and no silent mapper invention remains.
+4. Integrate execution mode into save states, replays, CI, and tooling.
+   Scope: persist execution-mode metadata, reject mismatched-mode restore by default, keep CI and oracle comparison on `Strict`, and segregate `Experimental` artifacts.
+   Acceptance criteria: save states and replay logs record the originating mode and active overrides, strict-mode CI remains the official closure path, and experimental runs cannot be mistaken for oracle evidence.
+
 ---
 
 ### Phase 2 — CPU and real temporal control
@@ -1198,15 +1216,15 @@ Close the DMG core with a formal validation matrix, strong differential and dete
    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.
+   Scope: same-ROM replay with identical execution mode, explicit overrides, 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 recorded mode, overrides, inputs, and injected time source; save/load continuation matches uninterrupted execution; mismatched-mode restore is rejected by default; 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
+- deterministic replay and save/load determinism are green under `Strict`, with execution-mode metadata recorded in the relevant artifacts
 - 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
 

AI/TESTING.md

@@ -61,6 +61,15 @@ Every subsystem change should aim to leave behind one of these:
 - 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.
 
+## Execution-mode validation policy
+
+- `Strict` is the only mode that counts as the project's oracle path for CI, differential comparison, DMG closure, and official accuracy claims.
+- `Permissive` is for tolerant interactive use and loader-validation coverage around odd but still unambiguous supported cartridges; it must not change the runtime semantics of admitted supported hardware.
+- `Experimental` is for research and bring-up; its results must stay segregated from official closure metrics, oracle comparisons, and compatibility claims.
+- Mode-sensitive loader tests should cover the documented category matrix for `Supported`, `PlannedVariant`, `DocumentedButUnsupported`, `ExperimentalHeuristic`, `AccessorySpecialCase`, and `UnknownCode`.
+- When a test exercises heuristics, partial implementations, or manual overrides, the captured artifacts should say so explicitly rather than looking like ordinary strict-mode evidence.
+- Differential comparison against SameBoy or Gambatte should always run under `Strict`, not under `Permissive` or `Experimental`.
+
 ## Validation tooling requirements
 
 - Hardening-ready validation requires trace logging at instruction level, micro-op level, and short T-cycle windows.
@@ -219,13 +228,15 @@ When a change affects observable timing or ordering:
 
 ## Determinism policy
 
-- Core execution should be deterministic for the same inputs and model configuration.
+- Core execution should be deterministic for the same inputs, model configuration, execution mode, and explicit override set.
 - 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.
+- "Same ROM + same execution mode + same explicit overrides + 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 under the same recorded execution mode.
+- Save states and replay logs should record the execution mode and active overrides that produced them.
+- Restoring or replaying under a different execution mode should be rejected by default; if a later explicit developer conversion path is added, tests should cover that path separately and mark it as non-oracle.
 - 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
@@ -235,7 +246,7 @@ When a change affects observable timing or ordering:
 - 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.
+- Differential regressions should preserve enough reproduction context to rerun them quickly, including the ROM, execution mode, active overrides, 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
 
@@ -248,7 +259,8 @@ When a change affects observable timing or ordering:
 
 ## CI stratification policy
 
-- 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.
+- 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 under `Strict`.
+- Experimental suites may exist in nightly or manual jobs, but they must publish artifacts separately and must not gate or dilute the official strict-mode closure signal.
 - 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.
 

AI/hardware/BOOT-ROM.md

@@ -101,7 +101,7 @@ Real boot should start CPU execution at `0x0000` with the internal boot ROM mapp
 - `SkipBoot` must distinguish between values that are fixed by model, values derived from the cartridge header, and values that are genuinely unreliable after power-up.
 - WRAM and HRAM should not be treated as fixed zero-filled memory in the direct post-boot snapshot.
 - Cartridge RAM, whether external or mapper-local to the cartridge controller, should not be assumed clean on first power-up when a direct post-boot path is used.
-- A direct-boot path should use an explicit policy for uninitialized memory and unreliable registers, such as seeded pseudo-random data, a documented pattern, or a debug-oriented strict mode.
+- A direct-boot path should use an explicit policy for uninitialized memory and unreliable registers, such as seeded pseudo-random data, a documented pattern, or a debug-oriented deterministic startup policy.
 - That uninitialized-state policy must not overwrite values that are deterministic in the documented post-boot snapshot.
 
 ## Post-boot visible map baseline