[PR #2497] [MERGED] docs(nativeaot): document the verified Windows-host parser route #5274

New issue

Closed

opened 2026-10-31 01:05:21 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:05:21 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2497
Author: @pablodiazjorge
Created: 10/13/2026
Status: ✅ Merged
Merged: 10/13/2026
Merged by: @morluto

Base: main ← Head: docs/windows-nativeaot-host

📝 Commits (2)

58d17e0 docs(nativeaot): document the verified Windows-host parser route
7fe86f2 docs(nativeaot): distinguish adapter reads and Windows build environments

📊 Changes

5 files changed (+41 additions, -12 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/references/native-and-artifacts.md (+3 -1)
📝 docs/ghidra-nativeaot.md (+25 -7)
📝 docs/managed-code-analysis.md (+3 -2)
📝 docs/testing.md (+6 -0)
📝 docs/windows-ghidra-p0.md (+4 -2)

📄 Description

Summary

Documents what the built-in NativeAOT snapshot parser does on a real Windows host, so the guides stop calling that route unverified. docs/ghidra-nativeaot.md and docs/windows-ghidra-p0.md still say it has not had a real Windows-host run. Refs #744, where I posted the first Windows results and offered this docs PR.

One correction to that comment: I wrote that frozen strings need the adapter. They don't. On Windows the parser returns them in metadata_recovery.frozen_strings (594 strings, none omitted, including the three fixture literals). Only search_strings, which reads Ghidra's string inventory, misses them.

Problem and expected behavior

A reader on Windows learns today that the route is unverified, but not:

which results Windows Ghidra P0 gives without the JAR;
that each recovered type's type is null without the adapter, so inspect_native_data_type takes address;
that search_strings and read_bytes do not see the rehydrated bytes there. The rehydrated region is the hydrated section (BSS, no file bytes), and only the adapter writes the overlay into the database;
that building the fixture locally with only Visual Studio Build Tools 2026 fails with "Platform linker not found", because the .NET 8 ILCompiler looks for Visual Studio 2019 or 2022 only (vswhere -version [16,18) in findvcvarsall.bat).

Expected: the guides state what is covered on a Windows host, what is not and why, and how to build the fixture there.

Change and scope

Documentation only, five files:

docs/ghidra-nativeaot.md: replaces the "not yet had a real Windows-host run" sentence with what Windows P0 covers; adds the type: null route by address, where to read frozen strings and slot targets, and a short note on how the Windows check was run (manual, no CI lane).
docs/windows-ghidra-p0.md: replaces "A real Windows-host NativeAOT Ghidra run is still required" with the covered and uncovered parts.
docs/managed-code-analysis.md: the sentence saying the Windows boundary does not establish NativeAOT coverage now points to the guide.
docs/testing.md: Build Tools 2026 note for build:fixtures:nativeaot on a local Windows host.
.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md: one sentence so agents read frozen literals from the parser report on Windows P0.

Not included: a Windows read-only mode for verify:ghidra:nativeaot, which requires Linux x64 and the JAR. The check I ran mirrors its read-only steps in symbols mode; I can turn it into a lane if that is useful. The docs claim nothing beyond what was run.

Contribution scope: not applicable (documentation within existing boundaries).

Contract and boundary impact

Semantic owner and earliest changed stage: documentation and the authored skill reference.
Contribution scope fit and linked maintainer decision: not applicable.
CLI and MCP/tool-catalog contract: none.
Provider, bridge, target-format, or platform compatibility: none; documents existing Windows Ghidra P0 behavior.
Evidence, artifact, provenance, or reconstruction contract: none.
Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable.
Generated metadata (docs/public/product-catalog.json), package, or installation impact: none; CI regenerates skills/.
Documentation or usability only; no target interaction.

Evidence and regression coverage

Tests added or updated: none (documentation).
Base reproduction or other evidence: executed on real Windows. Results on bb540826d match the run on fb43dd97 posted in #744:

Check over MCP (Windows P0, no JAR)	Result
`open_binary` with Ghidra	pass
`inspect_native_load_image`	`dotnet-nativeaot`, `complete`, RTR 9.1, `signature-heuristic`, 324 MethodTables and 324 types; 594 frozen strings, 0 omitted, the 3 fixture literals present; derived overlay at `0x14009a000`, 186,264 bytes
Recovered identity at the derived MethodTable	`type: null` (no database type without the adapter)
`inspect_native_data_type` by `address`	generated name (`original_name: null`); MethodTable, base type, interface and a virtual slot reaching `Compute` match the linker map
`analyze_function` on `Compute` and `Dispatch`	`return param_2 * 0xb + 5;`; pseudocode present
`read_bytes` at the first virtual slot (`0x1400a9228`, in `hydrated`)	0 bytes, `complete: false`
`search_strings` for the 3 fixture literals	none found

User-visible CLI/MCP output (if applicable): not applicable.
Remaining proof gaps: one host and the symbols fixture only (no stripped fixture on Windows); manual check with no CI lane; NativeAOT DLLs and other RTR versions not covered.

Validation performed

Windows 11 x64 (10.0.26300), non-elevated, Node 22.22.3, Ghidra 12.1.4, Temurin JDK 21. REA main at bb540826d, built locally, with the Windows native addon built from the same commit. Fixture from scripts/generate-nativeaot-fixtures.mjs with .NET SDK 8.0.416 (win-x64 symbols, SHA-256 157a3b54…f9b95552).

MCP check mirroring the read-only steps of verify-real-ghidra-nativeaot.mjs (symbols mode), without REA_GHIDRA_NATIVEAOT_JAR: 17 of 22 checks pass in 65 s. The 5 that fail are the type identity, read_bytes in hydrated and the three search_strings lookups, as documented.
inspect_native_load_image frozen strings: 594, 0 omitted, 3 of 3 fixture literals.
npx oxfmt --check on the five files: passed.
npm run docs:check: passed.
npm run check:fast: passed.

Compatibility, safety, and release

Breaking changes or migration steps: none.
Real Hopper/Ghidra, browser, or OS coverage: real Ghidra 12.1.4 on native Windows 11 for the symbols fixture.
Package or release metadata impact: none.
Security, privacy, process, or containment review: none; the fixture is never executed.

Before merge

This PR addresses a concrete problem or an agreed enhancement.
Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/2497 **Author:** [@pablodiazjorge](https://github.com/pablodiazjorge) **Created:** 10/13/2026 **Status:** ✅ Merged **Merged:** 10/13/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `docs/windows-nativeaot-host` --- ### 📝 Commits (2) - [`58d17e0`](https://github.com/morluto/rea/commit/58d17e09f84d49ae9090a45e2e349c8d274273db) docs(nativeaot): document the verified Windows-host parser route - [`7fe86f2`](https://github.com/morluto/rea/commit/7fe86f2971f73798e5251864e90e64c7fb8c4a4e) docs(nativeaot): distinguish adapter reads and Windows build environments ### 📊 Changes **5 files changed** (+41 additions, -12 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md` (+3 -1) 📝 `docs/ghidra-nativeaot.md` (+25 -7) 📝 `docs/managed-code-analysis.md` (+3 -2) 📝 `docs/testing.md` (+6 -0) 📝 `docs/windows-ghidra-p0.md` (+4 -2) </details> ### 📄 Description ## Summary Documents what the built-in NativeAOT snapshot parser does on a real Windows host, so the guides stop calling that route unverified. `docs/ghidra-nativeaot.md` and `docs/windows-ghidra-p0.md` still say it has not had a real Windows-host run. Refs #744, where I posted the first Windows results and offered this docs PR. One correction to that comment: I wrote that frozen strings need the adapter. They don't. On Windows the parser returns them in `metadata_recovery.frozen_strings` (594 strings, none omitted, including the three fixture literals). Only `search_strings`, which reads Ghidra's string inventory, misses them. ## Problem and expected behavior A reader on Windows learns today that the route is unverified, but not: - which results Windows Ghidra P0 gives without the JAR; - that each recovered type's `type` is `null` without the adapter, so `inspect_native_data_type` takes `address`; - that `search_strings` and `read_bytes` do not see the rehydrated bytes there. The rehydrated region is the `hydrated` section (BSS, no file bytes), and only the adapter writes the overlay into the database; - that building the fixture locally with only Visual Studio Build Tools 2026 fails with "Platform linker not found", because the .NET 8 ILCompiler looks for Visual Studio 2019 or 2022 only (`vswhere -version [16,18)` in `findvcvarsall.bat`). Expected: the guides state what is covered on a Windows host, what is not and why, and how to build the fixture there. ## Change and scope Documentation only, five files: - `docs/ghidra-nativeaot.md`: replaces the "not yet had a real Windows-host run" sentence with what Windows P0 covers; adds the `type: null` route by `address`, where to read frozen strings and slot targets, and a short note on how the Windows check was run (manual, no CI lane). - `docs/windows-ghidra-p0.md`: replaces "A real Windows-host NativeAOT Ghidra run is still required" with the covered and uncovered parts. - `docs/managed-code-analysis.md`: the sentence saying the Windows boundary does not establish NativeAOT coverage now points to the guide. - `docs/testing.md`: Build Tools 2026 note for `build:fixtures:nativeaot` on a local Windows host. - `.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md`: one sentence so agents read frozen literals from the parser report on Windows P0. Not included: a Windows read-only mode for `verify:ghidra:nativeaot`, which requires Linux x64 and the JAR. The check I ran mirrors its read-only steps in symbols mode; I can turn it into a lane if that is useful. The docs claim nothing beyond what was run. Contribution scope: not applicable (documentation within existing boundaries). ## Contract and boundary impact - Semantic owner and earliest changed stage: documentation and the authored skill reference. - Contribution scope fit and linked maintainer decision: not applicable. - CLI and MCP/tool-catalog contract: none. - Provider, bridge, target-format, or platform compatibility: none; documents existing Windows Ghidra P0 behavior. - Evidence, artifact, provenance, or reconstruction contract: none. - Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: none; CI regenerates `skills/`. - [x] Documentation or usability only; no target interaction. ## Evidence and regression coverage - Tests added or updated: none (documentation). - Base reproduction or other evidence: executed on real Windows. Results on `bb540826d` match the run on `fb43dd97` posted in #744: | Check over MCP (Windows P0, no JAR) | Result | |---|---| | `open_binary` with Ghidra | pass | | `inspect_native_load_image` | `dotnet-nativeaot`, `complete`, RTR 9.1, `signature-heuristic`, 324 MethodTables and 324 types; 594 frozen strings, 0 omitted, the 3 fixture literals present; derived overlay at `0x14009a000`, 186,264 bytes | | Recovered identity at the derived MethodTable | `type: null` (no database type without the adapter) | | `inspect_native_data_type` by `address` | generated name (`original_name: null`); MethodTable, base type, interface and a virtual slot reaching `Compute` match the linker map | | `analyze_function` on `Compute` and `Dispatch` | `return param_2 * 0xb + 5;`; pseudocode present | | `read_bytes` at the first virtual slot (`0x1400a9228`, in `hydrated`) | 0 bytes, `complete: false` | | `search_strings` for the 3 fixture literals | none found | - User-visible CLI/MCP output (if applicable): not applicable. - Remaining proof gaps: one host and the symbols fixture only (no stripped fixture on Windows); manual check with no CI lane; NativeAOT DLLs and other RTR versions not covered. ## Validation performed Windows 11 x64 (10.0.26300), non-elevated, Node 22.22.3, Ghidra 12.1.4, Temurin JDK 21. REA `main` at `bb540826d`, built locally, with the Windows native addon built from the same commit. Fixture from `scripts/generate-nativeaot-fixtures.mjs` with .NET SDK 8.0.416 (win-x64 symbols, SHA-256 `157a3b54…f9b95552`). - MCP check mirroring the read-only steps of `verify-real-ghidra-nativeaot.mjs` (symbols mode), without `REA_GHIDRA_NATIVEAOT_JAR`: 17 of 22 checks pass in 65 s. The 5 that fail are the `type` identity, `read_bytes` in `hydrated` and the three `search_strings` lookups, as documented. - `inspect_native_load_image` frozen strings: 594, 0 omitted, 3 of 3 fixture literals. - `npx oxfmt --check` on the five files: passed. - `npm run docs:check`: passed. - `npm run check:fast`: passed. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: real Ghidra 12.1.4 on native Windows 11 for the symbols fixture. - Package or release metadata impact: none. - Security, privacy, process, or containment review: none; the fixture is never executed. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:05:21 +00:00