feat(cpu): use actual fetch regions for boundary bus snapshots

docs/architecture.md

@@ -46,6 +46,7 @@ The repository is a Cargo workspace with three crates:
 | `crates/gba-core/src/memory/fetch.rs` | Strict instruction samples with captured region-dependent bus observations |
 | `crates/gba-core/src/memory/fetch_tests.rs` | Fetch widths, bus lanes, captured refill/BIOS values, strict errors, and side-effect isolation |
 | `crates/gba-core/src/cpu/fetch_history_tests.rs` | Shared sample consumption, no execution-entry rereads, and failed-step retry |
+| `crates/gba-core/src/cpu/fetch_boundary_tests.rs` | Actual fetch-region snapshots, split refills, IWRAM lane requirements, ROM-window boundaries, and nominal timing |
 | `crates/gba-core/src/io.rs` | I/O registers, timers, HALT/STOP wake-up, next-event bounds, and IRQ latches |
 | `crates/gba-core/src/display.rs` | Display clock, scanline status, comparison edges, and display IRQ events |
 | `crates/gba-core/src/dma.rs` | DMA registers, internal pointers, retained channel data, trigger state, priority, and completion IRQs |

docs/hardware/cpu.md

@@ -152,9 +152,10 @@ Original regressions check the values separately. See [the public ARM result](..
 ## Thumb unused-memory data reads
 
 Thumb data reads use the same unused address ranges and lane rules as ARM reads above.
-The snapshot depends on the executing code region. P below is the executing instruction address, not the visible r15 operand.
+The snapshot depends on the newly fetched region at P+4, even when P lies in the preceding region.
+P below is the executing instruction address, not the visible r15 operand.
 
-| Code region | Snapshot |
+| Fetch region | Snapshot |
 | --- | --- |
 | External work RAM, palette RAM, video RAM, all three ROM windows | Halfword at P+4, repeated in both word lanes |
 | BIOS and object attribute memory (OAM) | Full word at `(P+4) & ~3` |
@@ -169,9 +170,14 @@ The pipeline's new fetch supplies the bus snapshot without rereading its instruc
 BIOS/OAM samples include the other halfword of the aligned bus word, but retain only the selected halfword as an instruction.
 Only the required mapped bytes are sampled. A 16-bit region needs two lookahead bytes, not four.
 Normal memory mirrors apply to these bytes, including physical RAM/video-memory wrap within a mapped region.
-If P+4 crosses a 16 MiB address-region boundary, the snapshot remains unknown.
-This conservative diagnostic policy avoids guessing pipeline behavior during a region transition.
-Missing lookahead or unknown history fails only an unused-memory load; ordinary instructions and mapped loads can still execute.
+Crossing a 16 MiB region boundary does not by itself make the snapshot unknown.
+Palette-to-VRAM fetches repeat the new halfword; VRAM-to-OAM fetches expose the new aligned word.
+OAM-to-ROM and mapped ROM-window crossings repeat the fetched ROM halfword.
+An EWRAM-to-IWRAM fetch drives its addressed local lane and requires the other lanes to be known.
+For example, P=`0x02fffffc` needs prior high-lane history; P=`0x02fffffe` can establish both halves through its fill/refill and lookahead.
+Missing lookahead, unknown IWRAM lanes, and unsupported I/O fetch observations still produce diagnostics for unused-memory loads.
+Ordinary instructions and mapped loads can execute without a usable unused-memory snapshot.
+See [the boundary evidence and original tests](../research/fetch-region-boundaries.md).
 
 All loads in one instruction share the snapshot, including block loads and stack loads.
 Normal sign extension, unaligned-load rotation, writeback, register aliases, and PC-load semantics still apply.
@@ -207,8 +213,9 @@ Each instruction stages all new fetches and data-access changes.
 Success commits history regardless of the resulting PC, instruction state, or region. Failure preserves the previous committed history.
 Block-transfer data accesses stage updates in order; unused-memory reads still use one entry snapshot per instruction.
 This preserves the existing atomic diagnostic policy without adding bus or device cycles.
-Missing or region-crossing Thumb lookahead still leaves that instruction's unused-memory snapshot unsupported.
-It does not erase independently known IWRAM lanes.
+Missing or unsupported Thumb lookahead still leaves that instruction's unused-memory snapshot unknown.
+Mapped boundary fetches into IWRAM use its resulting local lanes, even while the current instruction executes elsewhere.
+Failed or other-region observations do not erase independently known IWRAM lanes.
 
 ### Thumb IWRAM refill history
 

docs/references.md

@@ -50,7 +50,7 @@ Hardware references used for the core:
 - [NanoBoyAdvance keypad implementation](https://github.com/nba-emu/NanoBoyAdvance/blob/master/src/nba/src/hw/keypad/keypad.cc), compared for control access widths; its AND/retrigger behavior differs from the chosen polling model.
 - [mGBA keypad timing issue](https://github.com/mgba-emu/mgba/issues/2490), for frontend frame-based input timing limits.
 - [Tonc hardware interrupts](https://gbadev.net/tonc/interrupts.html), for keypad source enable and IF/IE bit 12.
-- [GBATEK memory mirrors, video byte writes, and unused-memory reads](https://problemkaputt.de/gbatek-gba-unpredictable-things.htm), for unused address ranges, ARM PC+8 open bus, byte lanes, the distinct Thumb region/history rules, and PC-dependent BIOS read protection. The Thumb implementation follows its 16-bit-region and BIOS/OAM formulas. IWRAM has persistent local lanes across ARM/Thumb fetches, data accesses, and DMA; region-crossing snapshots remain unsupported.
+- [GBATEK memory mirrors, video byte writes, and unused-memory reads](https://problemkaputt.de/gbatek-gba-unpredictable-things.htm), for unused address ranges, ARM PC+8 open bus, byte lanes, the distinct Thumb region/history rules, and PC-dependent BIOS read protection. The Thumb implementation follows its 16-bit-region and BIOS/OAM formulas. IWRAM has persistent local lanes across ARM/Thumb fetches, data accesses, and DMA; mapped boundary snapshots follow the actual fetch region.
 - [nocash GBA open-bus discussion](https://www.ngemu.com/threads/gba-open-bus.170809/), for ARM prefetch, repeated Thumb halfwords in 16-bit regions, aligned BIOS/OAM words, and history-dependent IWRAM lanes. Its data-load overwrite note prevents treating P+2 as a universal IWRAM rule.
 - [mGBA memory implementation](https://github.com/mgba-emu/mgba/blob/master/src/gba/memory.c), reviewed for `GBALoadBad`, ARM prefetch sourcing, byte/halfword lane selection, and separate DMA/history behavior. Also reviewed its BIOS region-exit prefetch retention and protected-load lane selection.
 - [GBATEK GBA memory map and bus widths](https://problemkaputt.de/gbatek-gba-memory-map.htm).
@@ -162,6 +162,16 @@ Instruction retention and supported bus snapshots now use [shared fetch samples]
 That refactor reuses the pinned NanoBoyAdvance loop/refill and ares local-lane evidence above.
 Complete bus history and per-access timing remain incomplete; no new hardware conformance result is claimed.
 
+Fetch-region boundary research:
+
+- The pinned ares `getBus` and IWRAM helpers above, for address-based dispatch, local lane updates, and the full pre-shift bus value.
+- [ares OAM reads at 6f6786e0](https://github.com/ares-emulator/ares/blob/6f6786e04f0822a3475463df284f313ab8518d51/ares/gba/ppu/memory.cpp), for full aligned words before CPU halfword selection.
+- The pinned jgenesis bus above, for width-dependent general-bus updates and IWRAM's complete local word driving open bus.
+- The nocash open-bus discussion above, revisited through a boundary-focused web search. It documents region formulas, not a dedicated boundary hardware test.
+
+See [fetch-region boundary findings](research/fetch-region-boundaries.md) for source agreement, implementation differences, and retained diagnostics.
+No physical-hardware or external-emulator differential result is claimed.
+
 Use [GBATEK](https://problemkaputt.de/gbatek.htm) and ARM7TDMI documentation for further hardware work.
 Only use game ROMs that you may lawfully use. Do not commit game ROMs, BIOS files, or game assets.
 The ignore file excludes `roms/`, common game ROM extensions, and save files.

docs/research/fetch-region-boundaries.md

@@ -0,0 +1,101 @@
+# Instruction fetches across memory-region boundaries
+
+## Finding
+
+The shared sampler already selected bus width from the new fetch address.
+However, `Memory::begin_cpu_access` rejected every Thumb sample whose upper address byte differed from the executing PC.
+It also selected the IWRAM latch from the executing PC rather than the actual fetch address.
+This prevented mapped boundary fetches from supplying an otherwise known bus value.
+
+The boundary extension removes that blanket restriction.
+Thumb unused-memory reads now use the bus observation at the newly fetched address P+4.
+ARM continues to use its fetched PC+8 word.
+This is a bounded entry-snapshot model, not a complete general-bus or cycle-accurate implementation.
+
+## Evidence and limits
+
+A boundary-focused web search revisited [nocash's open-bus discussion](https://www.ngemu.com/threads/gba-open-bus.170809/).
+It describes repeated Thumb halfwords, full BIOS/OAM words, and history-dependent IWRAM lanes.
+The search did not identify a dedicated physical-hardware boundary result for this implementation.
+Those formulas alone do not establish every boundary or timing case.
+
+The stronger implementation evidence is address-based bus dispatch:
+
+- [ares bus at 6f6786e0](https://github.com/ares-emulator/ares/blob/6f6786e04f0822a3475463df284f313ab8518d51/ares/gba/cpu/bus.cpp) selects the bus using the actual access address.
+  It assigns the full result to `mdr` before selecting the addressed CPU halfword/byte.
+  It does not reject a mapped fetch because the executing instruction occupies another region.
+- [ares memory helpers](https://github.com/ares-emulator/ares/blob/6f6786e04f0822a3475463df284f313ab8518d51/ares/gba/cpu/memory.cpp) return repeated halfwords from 16-bit regions and the complete local latch from IWRAM.
+- [ares OAM helper](https://github.com/ares-emulator/ares/blob/6f6786e04f0822a3475463df284f313ab8518d51/ares/gba/ppu/memory.cpp) returns the aligned word before CPU halfword selection.
+- [jgenesis bus at fab6e2cc](https://github.com/jsgroth/jgenesis/blob/fab6e2ccc60e492dd68b7f1e927b0829a6d80195/backend/gba-core/src/bus.rs) independently updates general open bus from access width and the addressed memory helper.
+  Its `iwram_update_open_bus` drives the complete local IWRAM word after a partial-lane update.
+  That revision marks OAM behavior as a TODO, so it is not independent confirmation of the full OAM rule.
+- [NanoBoyAdvance's loop/refill helpers](https://github.com/nba-emu/NanoBoyAdvance/blob/55b5cf0ae3d929582ac5bfd486558173502b8354/src/nba/src/arm/arm7tdmi.hh) place the new fetch before execution and refill target pairs in order.
+  Its [open-bus helper](https://github.com/nba-emu/NanoBoyAdvance/blob/55b5cf0ae3d929582ac5bfd486558173502b8354/src/nba/src/bus/bus.cc) uses opcode-based approximations with a BIOS/OAM TODO.
+  We do not treat that helper as an exact boundary oracle.
+
+These are source comparisons, not physical-hardware measurements or external-emulator differential runs.
+No external code, BIOS image, or test ROM was imported. All regression programs are original.
+
+## Supported behavior
+
+The instruction buffer and bus history consume the same captured new fetch.
+The consumer does not reread memory or replay observations from retained instructions.
+
+| Lookahead transition | Thumb unused-memory snapshot |
+| --- | --- |
+| Palette to VRAM | Newly fetched halfword repeated in both lanes |
+| VRAM to OAM | Full aligned OAM word |
+| OAM to mapped ROM | Newly fetched ROM halfword repeated in both lanes |
+| Mapped ROM page or wait-window boundary | Halfword from the normal mapped cartridge offset, repeated |
+| EWRAM to IWRAM | Persistent IWRAM word after the new fetch drives its addressed halfword |
+
+The existing ROM mapping applies across all three wait-state windows.
+A 16-bit fetch needs only its two mapped bytes, not an adjacent full word.
+This includes OAM-to-ROM crossings, despite the executing instruction still residing on a 32-bit bus.
+
+IWRAM does not acquire guessed lanes from adjacent memory.
+At P=`0x02fffffc`, only the low half has been fetched from IWRAM; the high half needs prior observed history.
+Without that history, an unused-memory load remains diagnostic.
+At P=`0x02fffffe`, a cold fill or target-pair refill can capture IWRAM's low half before the high lookahead fetch.
+The resulting complete local word is then available.
+A preceding CPU data access or successful DMA can also establish the required lanes.
+
+A refill can span two regions. Each actual IWRAM target sample updates only its addressed lanes.
+Later host writes do not replace those captured lanes; the target instruction's new lookahead updates its own lane normally.
+Diagnostic failures discard staged fetch/history changes and preserve the previous instruction buffer.
+A retry takes a new lookahead sample from current memory.
+
+## Preserved diagnostics and timing
+
+- Missing ROM bytes and unmapped instruction reads remain strict errors or deferred fetch diagnostics.
+- Unsupported I/O fetch observations do not borrow known IWRAM lanes or another region's bus value.
+- Unknown IWRAM lanes do not become zero or fabricated history.
+- An ordinary instruction or mapped data load does not require a complete unused-memory snapshot.
+- A branch can discard an unavailable sequential path without failing early.
+- Host reads, instruction fetches, and DMA do not inherit CPU unused-memory fallback.
+- Protected BIOS history remains separate and image-derived.
+- All data reads within an instruction still use one entry snapshot.
+
+Nominal timing remains based on the current instruction address and existing refill summaries.
+Crossing a wait-state window does not yet schedule code cost at the actual lookahead address.
+Per-access device updates, video-bus contention, general DMA handoff, and Game Pak prefetch remain incomplete.
+No boundary timing accuracy is claimed.
+
+## Original regression coverage
+
+Tests cover both Thumb alignments and cold/retained pipelines at mapped video/ROM boundaries.
+Load matrices check byte, halfword, word, signed and unaligned results without flag changes.
+Other tests cover block/stack writeback, CPU/DMA-seeded IWRAM lanes, unknown lanes, split refills, and failed-step retry.
+ROM tests span mapped page and wait-window boundaries with distinct wait settings.
+Short-ROM tests require exactly the fetched halfword.
+Unsupported I/O, missing ROM, discarded branch paths, strict host reads, and unchanged ARM snapshots remain covered.
+
+The mapped-crossing regressions failed under the old upper-address-byte guard, then passed with fetch-address selection.
+
+## Validation result
+
+Workspace and core/demo tests pass in debug and release on Darwin arm64.
+Formatting, lint checks, rustdoc, preparation tests, native ROM windows, and graphics smoke modes pass.
+Public ARM, Thumb, memory, and BIOS reports match the prior persistent-IWRAM reports exactly, including nominal cycle counts.
+Debug and release reports also match for the same fixture paths.
+These checks are regression results, not physical-hardware boundary or timing conformance tests.

docs/research/iwram-bus-history.md

@@ -57,8 +57,8 @@ Host inspection and setup never drive the latch.
 Initial lanes remain unknown until observed accesses establish them.
 Byte/halfword accesses may establish only part of the word; a word access establishes all lanes.
 All unused-memory reads within an instruction still use one entry snapshot.
-A Thumb fetch crossing a 16 MiB region boundary leaves that instruction's unused-memory snapshot unsupported.
-Successful IWRAM accesses still update the local latch independently of this conservative snapshot policy.
+The [boundary extension](fetch-region-boundaries.md) selects the bus observation from the actual new fetch region.
+An EWRAM-to-IWRAM lookahead uses the resulting local lanes; incomplete lanes still leave that instruction's snapshot unknown.
 
 ## Thumb IWRAM refill extension
 
@@ -102,7 +102,7 @@ Sub-instruction arbitration and DMA during CPU internal cycles remain unmodeled.
 This is persistent local IWRAM history, not a complete general-bus implementation or cycle-accurate pipeline.
 ARM unused-memory reads still use their supported PC+8 snapshot.
 BIOS protection remains separately retained and image-derived.
-General DMA open bus, unused/write-only I/O, disabled RAM, exact region-crossing snapshots, and per-access timing remain incomplete.
+General DMA open bus, unused/write-only I/O, disabled RAM, unsupported-region snapshots, and per-access timing remain incomplete.
 Nominal CPU/DMA costs do not change.
 
 Original tests cover:
@@ -117,7 +117,7 @@ Original tests cover:
 
 The persistent-history regressions failed under the previous Thumb-continuation-only implementation.
 Existing cold-entry tests now assert captured lane values instead of the removed unsupported-history diagnostic.
-Region-crossing and strict unmapped-fetch diagnostics remain covered.
+Unknown-lane boundary cases and strict unmapped-fetch diagnostics remain covered.
 
 ## Validation result
 

docs/research/shared-fetch-samples.md

@@ -50,7 +50,8 @@ Strict instruction reads never use protected BIOS or unused-memory data fallback
 ## Current scope and limits
 
 - Cold fills and cross-state local IWRAM history are now implemented in the [persistent-latch extension](iwram-bus-history.md).
-- Thumb 16 MiB region crossings remain unsupported for bus snapshots.
+- Mapped Thumb region crossings now use the actual fetched bus in the [boundary extension](fetch-region-boundaries.md).
+- Unknown IWRAM lanes and unavailable/unsupported fetch observations remain diagnostic.
 - BIOS history commits after successful BIOS instruction execution; target refills do not establish additional BIOS history.
 - All unused-memory data reads within an instruction still use its entry snapshot.
 - DMA remains scheduled between whole instructions. Sampling does not add an interleaving point.

docs/research/thumb-instruction-buffer.md

@@ -57,7 +57,8 @@ Refill bus history and instruction buffering now consume the same captured targe
 Buffer samples add no nominal cycles or data accesses.
 Timed and untimed execution use the same buffer logic.
 Destination-based refill summaries and one-shot non-sequential CPU resume costs remain unchanged.
-Complete fetch-driven bus history, exact region crossings, per-access timing, Game Pak prefetch, and sub-instruction DMA arbitration remain incomplete.
+Mapped boundary snapshots now follow the [actual fetch region](fetch-region-boundaries.md).
+Complete bus history, exact boundary timing, Game Pak prefetch, and sub-instruction DMA arbitration remain incomplete.
 Instruction-state-changing compare quirks also remain hardware-unverified.
 
 ## Original regression coverage

docs/status.md

@@ -76,7 +76,7 @@ Update this file when a feature lands or a limit is removed.
 - The original BIOS exposes documented boot, SoftReset, SWI, and IRQ protected-read words through its actual exit layout.
 - ARM test/compare Rd=15 status restoration, without a PC result write or nominal refill.
 - ARM unused-memory data reads return a PC+8 word snapshot, with normal byte lanes and load rotation.
-- Thumb unused-memory reads use repeated PC+4 halfwords in 16-bit code regions and aligned PC+4 words in BIOS/OAM.
+- Thumb unused-memory reads follow the actual PC+4 fetch region, including mapped boundaries, ROM windows, and IWRAM lane history.
 - Persistent IWRAM lanes track ARM/Thumb fetches, CPU data accesses, and successful DMA, with known-bit tracking and diagnostic rollback.
 - Cold fills and ARM/Thumb target pairs update local history; state changes and BIOS IRQ entry do not erase it.
 - Little-endian byte, halfword, and word reads/writes.
@@ -144,7 +144,8 @@ State changes, other-region execution, and BIOS IRQ entry preserve local history
 Successful DMA can establish lanes before CPU startup. Resumed fetches then update their addressed lanes.
 ARM/Thumb instruction buffering retains sequential instructions and refill target pairs.
 Instruction buffering and supported bus history now consume the same mapped fetch samples, without sharing retained storage.
-Complete ARM bus history, exact region-crossing bus behavior, general DMA handoff, and unused/write-only I/O open bus remain incomplete.
+Mapped boundary snapshots follow the actual fetched bus; unknown IWRAM lanes, missing bytes, and I/O fetch values remain diagnostic.
+Complete general-bus history, exact boundary timing, general DMA handoff, and unused/write-only I/O open bus remain incomplete.
 [DMA channel data latches](hardware/dma.md#retained-channel-data) support blocked-source reuse, but never replace CPU bus history.
 BIOS protection uses separate retained BIOS fetch snapshots as described in [BIOS behavior](hardware/bios.md#cpu-bios-read-protection).
 Host inspection and instruction fetches remain strict. Other unmapped reads return errors.
@@ -155,7 +156,7 @@ Writes to cartridge addresses return errors instead of modeling cartridge hardwa
 
 ## Next steps
 
-1. Extend shared fetch samples to verified general-bus history and region-crossing snapshots.
+1. Extend shared fetch samples to verified general-bus data-access history and unsupported fetch regions.
    General DMA open-bus reads and sub-instruction arbitration remain separate from retained channel data and local IWRAM lanes.
    Keep unknown history diagnostic until fetch ordering and latch ownership have independent coverage.
    Validate BIOS snapshots with independent hardware tests before claiming exact refill or data-access history.

docs/testing.md

@@ -68,7 +68,11 @@ ARM open-bus regressions cover unused-range boundaries, PC+8 source regions, byt
 They check branch-target resampling, missing lookahead, skipped conditions, nominal timing, device progress, and retained host/fetch/DMA diagnostics.
 Thumb open-bus tests cover supported code regions, both instruction alignments, ROM windows, mirrors, and physical memory wrap.
 They check widths, sign extension, rotation, block/stack/PC loads, aliases, modes, state preservation, and sequential/branch resampling.
-Short-ROM tests require only the fetched halfword in 16-bit regions. Region-crossing tests retain explicit diagnostics.
+Short-ROM tests require only the fetched halfword in 16-bit regions, including OAM-to-ROM boundaries.
+Mapped boundary tests cover palette/VRAM/OAM/ROM transitions, EWRAM-to-IWRAM lanes, and ROM page/wait-window crossings.
+They verify cold/retained pipelines, load widths and rotation, block/stack loads, split refills, rollback, and nominal timing.
+Unknown IWRAM lanes, missing ROM bytes, and unsupported I/O fetch values retain explicit diagnostics.
+See [fetch-region boundaries](research/fetch-region-boundaries.md) for source evidence and hardware-validation limits.
 Cold IWRAM tests now assert actual current/decode/lookahead lane updates before the first data read.
 Sequential IWRAM regressions check retained lanes across fetches, reads, writes, mirrors, and physical RAM wrap.
 They cover raw bus values before load rotation/sign extension, all modes, block transfers, and isolation from other memory regions.