Files
reverse-engineering-anything/docs/ines-containers.md
T
David Muñoz Reyandmorluto cd3590c8ee feat(artifacts): inspect NES 2.0 container headers and regions (#10674)
* feat(artifacts): inspect NES 2.0 container headers and regions

Problem: the iNES lane refused every header whose byte 7 bits 2-3 select
NES 2.0, so NES 2.0 cartridges could not be inventoried, extracted or
reconstructed even though their file layout extends classic iNES.

Fix: the single iNES-family header parser now reads NES 2.0 alongside
classic iNES. It reports the 12-bit mapper, submapper, 12-bit and
exponent-multiplier PRG/CHR sizes, declared PRG/CHR RAM and NVRAM sizes,
CPU/PPU timing, console type with Vs. System and extended console codes,
miscellaneous ROM count and default expansion device in a "nes-2.0"
header variant; classic headers keep their exact serialization. Regions
add one prg.bin/chr.bin for exponent sizes and misc-rom.bin for the bytes
after CHR-ROM when miscellaneous ROMs are declared. Oversized
declarations (with exact totals, including exponent sizes beyond safe
integers), nonzero unused header bits, empty PRG-ROM and declared but
absent miscellaneous ROM bytes are refused through the existing format
error. Nested byte classification now admits NES 2.0 through the same
parser. The reader limitation, tool description, guide and skill
reference now state that UNIF remains unsupported and that RAM, timing
and console values are declarations.

Validation: new synthetic NES 2.0 unit cases fail on the base (15 of 24)
and pass after the change; focused boundary and acceptance iNES suites
(75 tests) pass, including NES 2.0 inventory, extraction, reconstruction
and compiled CLI inspection; npm run check:fast passes.

Refs morluto/rea#2072

* test(artifacts): extract an exponent-sized NES 2.0 ROM area

Review follow-up for NES 2.0 headers.

The exponent-multiplier case stopped at parseInesLayout, and the
extraction test used counted ROM units, so prg.bin and chr.bin from
an exponent-sized area never went through the reader or extraction.
A boundary case now builds a NES 2.0 file with a 2^10 * 3 byte PRG-ROM
area beside one counted 8 KiB CHR-ROM unit. It checks the header omits
the PRG unit count, the source offsets of prg.bin and chr/000.bin,
the verified reconstruction order, and that the extracted regions
match the original bytes exactly.

Tests: tests/boundary/filesystem/inesArtifact.test.ts passes (38).

* refactor(artifacts): read NES header bytes through one helper

The NES 2.0 declaration added a sixth raw Buffer read to
inesContainer.ts. On current main the architecture guard allows five
there, so the merged tree failed Static checks. iNES and NES 2.0
declarations and the format probe now read header bytes through one
headerByte helper. The file has one raw read, and its counted baseline
drops from 5 to 1 through --shrink-baselines.

Tests: inesContainer domain tests (24) and the NES boundary and
acceptance tests (76) pass. architecture-guards, format:check and
check:ci:fast pass on the branch merged with main.

* refactor(artifacts): report iNES header failures through ParseFailure

Review follow-up: the NES 2.0 declaration added plain-string failures.
The iNES-family parser now returns Result<_, ParseFailure> with its
kind and where it was found:
- malformed: a missing signature, a dirty legacy header, an empty
  PRG-ROM area, reserved NES 2.0 bits or an invalid file extent;
- truncated: a short header, a short payload, or declared
  miscellaneous ROM with no bytes;
- unsupported: UNIF or another header variant, with undecoded content.
The detail text is unchanged.

The format registry refuses with the detail, and the iNES reader and
root classifier translate the failure at their boundary into the
existing format ArtifactReaderFailure, with the ParseFailureError as
its cause.

Tests: the refusal table now asserts each failure's kind and format
as well as its detail. iNES domain and recognition tests, NES boundary
and acceptance tests (76), architecture-guards, format:check and
check:ci:fast pass on the branch merged with main.

* fix(artifacts): preserve NES header declarations and iNES evidence

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
2026-11-19 20:49:33 +00:00

108 lines
6.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# iNES and NES 2.0 container inspection
REA recognizes iNES from the `NES` + `0x1a` byte signature, independently
of the file extension. Header byte 7 bits 2–3 equal to `0b10` select NES 2.0;
other headers are read as classic iNES. Both report the `ines` artifact format.
This read-only container inspection uses portable Node.js file reads; it needs
neither Ghidra nor an emulator.
```bash
rea inspect-artifact ./cartridge.nes --json
rea extract-artifact ./cartridge.nes --json
```
Through MCP, call `open_binary` with the local path, then `inspect_artifact`.
Use `extract_artifact` to materialize the regions in the fresh directory named
by its result. The caller owns that successful extraction directory.
## Header and file regions
Inspection returns `container-header` and `reconstruction` observations inline.
The single inventory Evidence under `substeps[].evidence.normalized_result`
contains the complete graph and an `ines` object:
- `ines.header`: `format` (`ines` or `nes-2.0`), original 16-byte `header_hex`,
PRG/CHR file-unit counts, mapper, raw flags 6/7, and trainer and battery
flags. Classic iNES also reports its existing declared mirroring mode.
- NES 2.0 headers add `prg_rom_bytes`/`chr_rom_bytes`, the 12-bit mapper and
`submapper`, `console_type`, `cpu_ppu_timing`, declared PRG-RAM,
PRG-NVRAM, CHR-RAM and CHR-NVRAM byte sizes (`0` when none is declared),
`misc_rom_count` and `default_expansion_device`. Vs. System headers add
`vs_ppu_type` and `vs_hardware_type`; extended console headers add
`extended_console_type`. These codes are reported as numbers. When the
exponent-multiplier form declares a ROM size, its unit count is omitted
rather than reported as zero. `nametable_layout_flags` preserves byte 6's
`arrangement_bit` (bit 0) and `alternative_layout_bit` (bit 3) as header
flags. Their effective behavior can depend on the mapper.
- `occurrences[]`: each region's path, `source_location.offset` and
`source_location.length` in the original container. Follow `artifact_id` to
the node's observed SHA-256 and byte count.
- `ines.reconstruction`: ordered region paths, concatenated byte count,
SHA-256 and `verified: true`. REA accumulates the concatenation digest during
the same physical-order region scan that produces node hashes, then compares
it with the original whole-file digest. Final source freshness is also checked.
No reconstructed file is written during inspection.
Regions are `header.bin`, optional `trainer.bin` (512 bytes),
`prg/000.bin` onward (16 KiB each), `chr/000.bin` onward (8 KiB each), and
optional `trailing.bin`. An exponent-multiplier size is one `prg.bin` or
`chr.bin` region of the declared byte length. When NES 2.0 declares
miscellaneous ROMs, all bytes after CHR-ROM form `misc-rom.bin` instead of
`trailing.bin`; the boundaries between several miscellaneous ROMs are
mapper-specific and are not split. Every input byte is retained, including
unused header fields and uninterpreted trailing data. Zero CHR-ROM units create
no CHR region; REA does not fabricate CHR-RAM contents. Declared RAM and NVRAM
sizes create no regions.
Reader shutdown stops region streams and waits for admitted reads and final
source checks before releasing an extraction-owned descriptor. Inventory readers
leave their borrowed descriptor open for the admitting scope. A failed descriptor
close retains the same owner for retry.
After extraction, concatenate the materialized files in
`ines.reconstruction.region_order` from the inspection inventory. Their bytes
reproduce the input exactly. Graph path order is lexical and is not physical
file order; use the explicit region order or source offsets.
## Supported boundary
This lane supports classic iNES with a complete 16-byte header, nonzero
PRG count, complete declared trainer/PRG/CHR payload, and zero reserved bytes
12–15. Dirty legacy headers are refused because their upper mapper bits are
ambiguous; REA does not silently repair them. NES 2.0 additionally requires
nonzero PRG-ROM, zero unused header bits (byte 12 bits 2–7, byte 13 outside
the Vs. System and extended console fields, byte 14 bits 2–7 and byte 15 bit
7), and at least one byte after CHR-ROM when miscellaneous ROMs are
declared. A NES 2.0 size larger than the file, including an exponent-multiplier
size beyond the safe integer range, is refused with its exact declared total;
REA does not fall back to a classic reading. UNIF signatures, unsupported
header variants and truncated payloads are explicitly refused. An arbitrary
file named `.nes` is not admitted as iNES.
The PRG/CHR units describe file storage, not mapper bank sizes or CPU windows.
The mapper number, flags, RAM/NVRAM sizes, timing, console and expansion-device
values are header declarations, not proof of cartridge hardware or runtime
behavior. Bank switching, 6502/65816 disassembly, emulator
sessions and interpretation of console-specific trailing data remain outside
this lane. Raw-binary Ghidra analysis is a separate workflow. This container
increment addresses the first milestone of [#2072](https://github.com/morluto/rea/issues/2072);
the related [#1641](https://github.com/morluto/rea/issues/1641) tracks 6502/65816
native analysis with explicit load addresses and provider limitations. Extracted
PRG units still need caller-selected CPU windows before static code analysis;
their physical file offsets do not establish those addresses.
Source-owned byte fixtures verify original offsets and hashes, extraction and
byte-exact reconstruction, CLI/stdio MCP parity, malformed/unsupported inputs,
failed target-switch recovery, cancellation and source identity. These checks
do not establish emulator behavior or compatibility with every historical ROM.
The portable CLI/stdio MCP acceptance and source-identity checks run in Linux
and macOS CI. The same workflows have also been executed on native Windows x64.
Synthetic NES 2.0 headers additionally cover simple and exponent-multiplier
sizes, trainer and miscellaneous ROM regions, console and timing fields,
refused declarations, source-boundary extraction and compiled CLI inspection
in the same Linux and macOS CI jobs. No real NES 2.0 cartridge image is
part of the test suite.
Format references: [iNES](https://www.nesdev.org/wiki/INES) and
[NES 2.0](https://www.nesdev.org/wiki/NES_2.0).