mirror of
https://github.com/morluto/rea.git
synced 2026-11-20 05:32:44 +00:00
* fix(v8): read the code cache header size from the container
V8 sizes the header with `kHeaderSize = POINTER_SIZE_ALIGN(kUnalignedHeaderSize)` and
`kUnalignedHeaderSize` is 28, so the header is padded *after* its words: a 64-bit producer writes
32 header bytes and a 32-bit one writes 28. The reader pinned 32 and required the declared payload
to equal `bytes.length - 32`, so every container from a 32-bit producer failed as "truncated or
corrupt".
Measured here on Node 24.22.1 (V8 in x64): take a real cache and drop the four alignment bytes at
offset 28. V8 loads it unchanged — `cachedDataRejected === false` — while the reader refused it:
before: Header declares a 392-byte payload but 388 bytes follow the 32-byte header
after: ACCEPT header_bytes=28 words=7 payload.offset=28
The payload-length word sits at byte 20 in both layouts, so the declared length already states how
much trailing padding the container carries. The header size is derived from it now: `28` and `32`
are admitted, the reported word table covers exactly the header the container holds (7 or 8 words),
and the schema requires that table to agree with `header_bytes`.
Nothing is loosened. A header that is neither 28 nor 32 bytes is still `malformed`, and the
16 existing cases pass unchanged — dropping only the derivation back to the constant fails exactly
the new narrow-header case.
`src/v8` — 26 passing. `npm run lint` and `tsc --noEmit` clean.
* fix(v8): refuse a wide cache that is only four bytes short
A review finding on the previous commit, and a real one: deriving the header size from the declared
payload length makes a 32-byte-header container truncated by four bytes resolve to 28, because
`bytes.length - declaredPayload` loses exactly those four bytes. The reader then accepted a
truncated cache and read its payload one word long.
The wide header's last word is `POINTER_SIZE_ALIGN` padding that V8 leaves zero, and a narrow
container has payload where that word sits. Measured on Node 24.22.1 across six different sources:
the padding word is always `0x00000000` and the first payload word is always non-zero. So the zero
word is the only evidence that separates the two, and it is now required to be non-zero for the
28-byte layout:
| container | before this commit | after |
| --- | --- | --- |
| real 32-byte header | accept | accept, `header_bytes=32` |
| real 28-byte header | accept | accept, `header_bytes=28` |
| 32-byte header truncated by 4 | **accept** | refused as `malformed` |
The guide also described one pinned 32-byte header; it now describes both layouts, how the size is
resolved, and why an ambiguous container is refused.
`src/v8` — 27 passing. Removing the guard accepts the truncated container again.
* fix(v8): read the padding word through the header accessor
A Static checks finding: `verify/architecture-guards.mjs` counts raw Buffer reads in parser folders
and allows only a shrinking baseline, and the previous commit added one:
```
raw Buffer or DataView numeric read (use BinaryReader ...); new copies are not allowed:
src/v8/V8CodeCacheParser.ts: 2 (baseline 1)
```
The read is the narrow-header discriminator — the alignment word a 64-bit producer leaves zero at
offset 28. It now goes through the file's existing `field(index)` accessor instead of calling
`bytes.readUInt32LE` directly, so the count returns to the baseline while the check itself is
unchanged: `field(7)` is byte 28, and `V8_CODE_CACHE_NARROW_HEADER_BYTES / 4` spells that index.
`node scripts/verify/architecture-guards.mjs` — passed across 2 843 source files.
`src/v8` + `tests/boundary/rust` — 68 passing. `tsc --noEmit` 0 errors.
Setting the condition to `false` fails "refuses a wide container that is only four bytes short",
so the check is still load-bearing.
* fix(v8): ground the narrow-header rule in the producer, and test the word table
Two review findings.
**The rule was stated as measurement, not as format.** The previous comment justified the zero-word
discriminator with "measured on Node 24.22.1 every real payload begins with a non-zero word", which
makes support for other producers depend on one host. The producer zeroes that padding rather than
copying payload over it: `SerializedData::AllocateWithPayload` in `src/snapshot/snapshot-data.cc`
runs `std::fill_n(data_, header_size, 0)` before writing any header word, and
`kHeaderSize = POINTER_SIZE_ALIGN(kUnalignedHeaderSize)` in `src/snapshot/code-serializer.h` puts the
four padding bytes inside `header_size`. So a zero word at byte 28 is a fact about the producer, not
about one Node build.
The refusal is now worded as the reservation it is: a narrow container whose payload happened to
begin with four zero bytes would match the same test, and no reading of the header alone separates
the two cases. The message says both readings instead of asserting corruption.
**The word-table rule had no test that could fail.** `header.fields.length * 4 === header.header_bytes`
cannot disagree on a parsed container — the parser derives both from `payloadOffset` — so it is only
reachable through the schema, which is what a stored or projected report also goes through. The new
case builds four reports directly: seven words with 32 bytes and eight words with 28 are refused on
`header.fields`, while the two consistent pairs are accepted. Setting the rule to `false` fails it
with `7 words / 32 bytes: expected true to be false`.
`node scripts/verify/architecture-guards.mjs` — passed across 2 843 source files.
`src/v8` + `tests/boundary/rust` — 69 passing. `tsc --noEmit` 0 errors, `npm run lint` 0 errors.
* refactor(v8): share decoded code cache header words
* fix(v8): validate narrow header evidence without assuming runtime compatibility
---------
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
Documentation directory
REA documentation is organized by reader task and document owner. This directory
links every authored guide; the site also serves separate
product pages. The VitePress documentation source is this docs/ tree.
Getting started
- Installation and setup
- Client configuration and troubleshooting
- CLI and Evidence
- Guided MCP prompts and completion
Native binaries
- Native binary investigation
- Go binary build metadata
- DWARF compile units
- Offline binary diagnostics
- ELF separate debug files
- ELF and Mach-O initializer functions
- ELF unwind function ranges
- Linux kernel build config
- Recorded crash evidence
- CycloneDX dependencies
- Windows Shell Link shortcuts
- Acquired NTFS metadata and change journals
JavaScript and Electron
- JavaScript Application Graph
- Cross-layer JavaScript application workflows
- JavaScript artifact reconstruction
- JavaScript source recovery
- Passive Node and Electron runtime observation
- JavaScript static/runtime reconciliation
- Electron file-page observation
- V8 code cache inspection
Browser and captured websites
- Website observation with CDP
- Browser scenario contract
- Website runtime source attribution
- Historical web network captures
- HTTP/3 capture lab
- Captured website source locations
- Captured website module relationships
- Captured website scripts and static JavaScript analysis
Android applications
- Static Android APK analysis
- Apktool resource decoding
- ADB device inspection and acquisition
- Flutter build identification
Apple applications
.NET assemblies
Firmware
HarmonyOS packages
WebAssembly
EVM contracts
Databases and recorded packets
Process capture and instrumentation
Signal recordings
Provider setup and formats
- Ghidra provider semantics
- DOS MZ and COM analysis with Ghidra
- Optional NativeAOT metadata recovery
- MIPS ELF analysis through Ghidra
- PSP static ELF analysis through Ghidra
- RISC-V ELF analysis through Ghidra
- Windows Ghidra P0
- Headerless raw-binary analysis with Ghidra
- IDA provider
- JEB instrumentation and analysis
Contracts and evidence
Development and verification
- Settings and recovery
- REA limit inventory
- MCP tool design
- Testing REA
- Client and agent verification
- Reconstruction readiness conformance
- Releasing REA
- REA roadmap
Release migrations
Architecture and authoring
- Architecture map
- Documentation ownership and contribution model
- Feature specifications
- Architectural decision records
Machine-owned documentation
| Path | Owner and update command |
|---|---|
public/product-catalog.json |
Ignored contract projection; npm run docs:generate |
verification/managed-conformance-*.json |
Ignored managed conformance projections; npm run evidence:generate |
error-contract.schema.json |
Tracked schema from contracts; npm run docs:error-schema |
user-visible-errors.csv |
Generated error code and category per domain and provider-owned error case; npm run docs:error-schema |
releases/<version>.contributions.json |
Durable release contribution record; follow the release guide |
assets/ |
Shared authored images referenced by guides |
Do not edit generated catalogs or evidence to change product facts. Change their canonical contracts or producer and regenerate. Historical release records retain the exact commit messages and references from the release they describe.
Additional guides
- Offline API contract inventory
- Bun standalone executables
- Deno compile executables
- Capability composition and ownership
- .NET single-file bundles
- ESP flash images
- U-Boot FIT images
- Measure MCP catalog costs in Codex
- Offline Playwright traces
- Testing lanes and provider verification
- UF2 and DfuSe images
- WeChat mini-program wxapkg archives
- Binary hardening
- Desktop application capture
- Desktop application export
- Desktop application state
- Desktop application tasks
- Desktop build computer
- Desktop build witness
- iNES containers
- Build RL environments with REA
- Agent environments from recorded captures
- Android boot and vendor_boot images
- APK signature schemes
- Android OTA update payloads
- Apple IPS crash reports
- Static analysis in GitHub Actions
- Desktop installation directories
- Flattened devicetree inspection
- Electron fuse state
- ELF note tables
- ELF dependency tables
- Erlang BEAM files
- ESP images
- GameCube DOL analysis through Ghidra
- PowerPC ELF analysis through Ghidra
- Godot PCK archives
- Static CUDA and HIP code objects
- Intel HEX and S-record images
- IL2CPP metadata
- Static JavaScript route inventory
- Linux kernel modules
- Kuna provider
- Maven POM and Gradle module metadata
- Model file declarations
- Match native functions across builds
- Node.js single executable applications
- NuGet packages
- PE Authenticode certificate tables
- PE import and delay-load tables
- PE TLS callbacks and load configuration
- Python packaged applications
- CPython pyc inspection
- Reconstruction coverage
- Release exposure
- Reverse-engineering tool integrations
- Rust binary dependency metadata
- U-Boot legacy uImage containers
- UnityFS AssetBundle archives