Files
reverse-engineering-anything/docs/ines-containers.md
T
a836c89d75 fix(artifacts): preserve iNES shutdown ownership and I/O failures (#11748)
* fix(artifacts): preserve iNES shutdown ownership and I/O failures

* test(cli): publish complete doctor readiness before cancellation

* test(mcp): observe cleanup failures at their current delivery boundary

* fix(mcp): preserve workflow completion progress through delivery

* test(ci): assert current MCP and evidence ownership contracts

* test(setup): keep the Windows Kimi profile fixture on a supported profile

The Windows-only case at `clientConfigurationEnvironment.test.ts:226` wrote
`rea_mcp_input_schema_profile: "full"`. That profile was retired: the reader
now refuses it ("REA_MCP_INPUT_SCHEMA_PROFILE accepts only \"compact\" …"),
so `configureClientConfiguration` returned `failed/readback` before writing
and the case failed on every Windows run, including main's own
`Windows capability and package lane`.

The case has no Windows dependency — it passes an explicit `configPath` and
the Kimi write dialect is the same everywhere — so it now runs on every
platform, which is what let the stale value rot unnoticed. The fixture keeps
the lowercase explicit key the case is about, with the supported value.

Verified on `main` `d6bcfc10`: the same fixture driven through
`configureClientConfiguration(..., "win32")` on this host reproduced
`{"status":"failed","reason":"readback"}` with the retired value and now
returns `{"status":"configured"}` with `compact`. The file's 75 cases pass
here (66 run, 9 platform-conditioned skips) and `check:fast` passes.

* test(ci): restore verifier and MCP contract regressions

* test(captures): assert adapter-owned input issue field names

* fix(ghidra): avoid Java probes for missing installations

* test(capture): retain final cleanup progress assertions

* fix(artifacts): keep iNES shutdown ownership free of unrelated edits

The doctor readiness fixture and process-capture progress assertions
are not required by descriptor retirement or I/O failure precedence.
Restoring them, and the Ghidra installation test already merged in
#11732, leaves this change on the iNES reader, chunk reader, and
their regressions. The unused artifact chunk helper import is removed.

Co-authored-by: morluto <morluto@users.noreply.github.com>

* test(artifacts): age the iNES header race before same-size rewrites

Identity checks observe mtime, and a same-size overwrite inside one
clock tick is indistinguishable from the original file. The admission
test then reports a format error instead of source integrity. Age the
fixture the same way the prefix race already does.

* test(go): assert truncated Mach-O command tables by typed failure

An unstored oversized command table is a truncated Mach-O load-command
parse, projected as invalid_format. The old message lock named a
sentence the parser no longer produces.

Co-authored-by: morluto <morluto@users.noreply.github.com>

* test(artifacts): fold the paused iNES inventory close into the existing case

The standalone close test repeated the paused entries() refusal already
covered by the close/cancel pair. The borrowed-descriptor stat stays on
that close case.

Co-authored-by: morluto <morluto@users.noreply.github.com>

* fix(artifacts): preserve first iNES stream interruption

---------

Co-authored-by: ShuaixinHuang <197200901+ShuaixinHuang@users.noreply.github.com>
Co-authored-by: g0at <50488370+g1at@users.noreply.github.com>
Co-authored-by: IvenKooLab <276572622@qq.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: morluto <morluto@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
2026-11-19 19:19:32 +00:00

4.2 KiB
Raw Blame History

Classic iNES container inspection

REA recognizes classic iNES from the NES + 0x1a byte signature, independently of the file extension. This read-only container inspection uses portable Node.js file reads; it needs neither Ghidra nor an emulator.

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: original 16-byte header_hex, PRG/CHR file-unit counts, mapper, raw flags 6/7, trainer and battery flags, and the declared mirroring mode.
  • 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. 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.

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 increment 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 and 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 and flags 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; the related #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.

Format references: iNES and NES 2.0.