[GH-ISSUE #2072] Feature request: NES / iNES container routing (6502 ROMs) — real-world use case and proposed scope #687

New issue

Open

opened 2026-10-15 18:27:23 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-15 18:27:23 +00:00

Owner

Originally created by @imaginedays on GitHub (Oct 12, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/2072

Summary

REA's format router (open_binary) recognizes native executables (PE/ELF/Mach-O), ASAR/JS trees, APK, firmware images, etc., but has no route for NES ROMs (iNES/UNIF containers, 6502 code, PRG/CHR banking). The README does not mention NES, 6502, iNES, emulator, or console anywhere (closest is Ghidra's 16-bit DOS support).

I'd like to request NES/6502 support — or start a discussion about what a minimal, REA-idiomatic version would look like. I have a real, ongoing project that would benefit from it and can contribute case data.

Real-world use case

I am reverse-engineering the FC/NES game Sangokushi II: Haou no Tairiku (三國志II 覇王の大陸, Namco 1988, Mapper 19/Namcot 163) with an agent-driven workflow:

Static: custom bank splitter + py65 (6502 emulator/disassembler) + da65/ca65 round-trips, all driven from scripts.
Dynamic: a headless Mesen 2 fork CLI (mesen-agent, JSONL stdout: breakpoints with value conditions, memory dumps, savestates, PPU nametable dumps, serialized console state).
Evidence: REA 6.4.0 as the evidence ledger — rea capture-process wraps every Python experiment into Evidence records; each conclusion cites original bytes / model / emulator observation separately.

This works today, but REA itself cannot open the ROM: the only REA-side integration is process-capture of helper scripts. The ROM bytes, iNES header, mapper layout, and 6502 analysis all live outside REA's evidence model.

What would make REA useful here (proposed scope, smallest first)

Container routing only (smallest): recognize .nes (iNES) as an artifact type — parse the 16-byte header (PRG/CHR sizes, mapper, flags), inventory PRG/CHR banks as regions with per-bank SHA-256, byte-exact reconstruction check (same spirit as inspect_artifact + the Android inventory). No 6502 analysis required — this alone lets Evidence reference bank-granular locations instead of raw file offsets.
6502 static provider (bigger): disassembly of a selected bank/window (mapper-aware $8000/$A000/$C000/$E000 window mapping is essential; without it 6502 disassembly produces mostly garbage), procedure/string/call-graph inventories, and Hopper/Ghidra/IDA-style Evidence records. Ghidra has community 6502 support; py65/da65 are MIT-licensed fallbacks.
Emulator evidence integration (biggest, optional): a typed provider for headless emulator sessions (input scripts, savestates, memory/PPU dumps, breakpoint hits) so dynamic claims about ROM behavior get first-class Evidence instead of generic process captures.

What I can contribute

Test-case metadata (ROM SHA-256 hashes, bank layouts, mapper behavior notes — no copyrighted ROM bytes).
A worked example: Mapper 19 bank-window evidence collected via the workflow above (nametable writes, dakuten overlay mechanism, dynamic-number placeholders in text streams).
Workflow documentation for the evidence-ledger pattern (REA process-capture + external emulator), if useful to others in the interim.

Happy to move this to a discussion if that fits the project better.

Originally created by @imaginedays on GitHub (Oct 12, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/2072 ## Summary REA's format router (`open_binary`) recognizes native executables (PE/ELF/Mach-O), ASAR/JS trees, APK, firmware images, etc., but has no route for **NES ROMs** (iNES/UNIF containers, 6502 code, PRG/CHR banking). The README does not mention NES, 6502, iNES, emulator, or console anywhere (closest is Ghidra's 16-bit DOS support). I'd like to request NES/6502 support — or start a discussion about what a minimal, REA-idiomatic version would look like. I have a real, ongoing project that would benefit from it and can contribute case data. ## Real-world use case I am reverse-engineering the FC/NES game *Sangokushi II: Haou no Tairiku* (三國志II 覇王の大陸, Namco 1988, Mapper 19/Namcot 163) with an agent-driven workflow: - **Static**: custom bank splitter + py65 (6502 emulator/disassembler) + da65/ca65 round-trips, all driven from scripts. - **Dynamic**: a headless Mesen 2 fork CLI (`mesen-agent`, JSONL stdout: breakpoints with value conditions, memory dumps, savestates, PPU nametable dumps, serialized console state). - **Evidence**: REA 6.4.0 as the evidence ledger — `rea capture-process` wraps every Python experiment into Evidence records; each conclusion cites original bytes / model / emulator observation separately. This works today, but REA itself cannot open the ROM: the only REA-side integration is process-capture of helper scripts. The ROM bytes, iNES header, mapper layout, and 6502 analysis all live outside REA's evidence model. ## What would make REA useful here (proposed scope, smallest first) 1. **Container routing only (smallest)**: recognize `.nes` (iNES) as an artifact type — parse the 16-byte header (PRG/CHR sizes, mapper, flags), inventory PRG/CHR banks as regions with per-bank SHA-256, byte-exact reconstruction check (same spirit as `inspect_artifact` + the Android inventory). No 6502 analysis required — this alone lets Evidence reference bank-granular locations instead of raw file offsets. 2. **6502 static provider (bigger)**: disassembly of a selected bank/window (mapper-aware $8000/$A000/$C000/$E000 window mapping is essential; without it 6502 disassembly produces mostly garbage), procedure/string/call-graph inventories, and Hopper/Ghidra/IDA-style Evidence records. Ghidra has community 6502 support; py65/da65 are MIT-licensed fallbacks. 3. **Emulator evidence integration (biggest, optional)**: a typed provider for headless emulator sessions (input scripts, savestates, memory/PPU dumps, breakpoint hits) so dynamic claims about ROM behavior get first-class Evidence instead of generic process captures. ## What I can contribute - Test-case metadata (ROM SHA-256 hashes, bank layouts, mapper behavior notes — no copyrighted ROM bytes). - A worked example: Mapper 19 bank-window evidence collected via the workflow above (nametable writes, dakuten overlay mechanism, dynamic-number placeholders in text streams). - Workflow documentation for the evidence-ledger pattern (REA process-capture + external emulator), if useful to others in the interim. Happy to move this to a discussion if that fits the project better.

bsakaguchi added the

area: evidence

enhancement

P2: medium

labels

2026-10-15 18:27:23 +00:00

bsakaguchi commented

2026-10-15 18:27:23 +00:00

Author

Owner

@matbrgz commented on GitHub (Oct 12, 2026):

Design & Retro Architecture Review

Supporting NES / iNES ROM containers (6502) links with the broader 6502 / WDC Ghidra discussion (#1641):

Header Parsing: The iNES header (4E 45 53 1A / "NES\x1a") and NES 2.0 extension specify PRG-ROM size, CHR-ROM size, and mapper number cleanly in bytes 4–8. A pure TypeScript parser can unpack PRG/CHR banks into static artifact occurrences.
Provider Binding: Ghidra includes a mature 6502 processor module (6502:LE:16:default). Mapping unpacked PRG banks to Ghidra's 6502 language with bank switching documentation establishes static disassembly without requiring emulator execution authority.

@matbrgz commented on GitHub (Oct 12, 2026): ### Design & Retro Architecture Review Supporting NES / iNES ROM containers (6502) links with the broader 6502 / WDC Ghidra discussion (#1641): - **Header Parsing:** The iNES header (`4E 45 53 1A` / `"NES\x1a"`) and NES 2.0 extension specify PRG-ROM size, CHR-ROM size, and mapper number cleanly in bytes 4–8. A pure TypeScript parser can unpack PRG/CHR banks into static artifact occurrences. - **Provider Binding:** Ghidra includes a mature 6502 processor module (`6502:LE:16:default`). Mapping unpacked PRG banks to Ghidra's 6502 language with bank switching documentation establishes static disassembly without requiring emulator execution authority.

bsakaguchi referenced this issue

2026-10-15 18:28:29 +00:00

[GH-ISSUE #2383] [Tracker] Audit analysis and debugging coverage for the TIOBE top 100 languages (October 2026) #794

bsakaguchi referenced this issue

2026-10-16 21:15:09 +00:00

[PR #687] [CLOSED] fix(javascript): keep optional parameter input unknown #2169

bsakaguchi referenced this issue

2026-10-16 21:15:24 +00:00

[PR #705] [MERGED] fix: integrate 14 approved fix PRs (668,671,673,675,678-681,685-690) #2185

bsakaguchi added

enhancement

and removed