[PR #1533] [MERGED] feat(wasm): inspect local artifacts with WABT #2951

Closed
opened 2026-10-17 21:12:11 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/1533
Author: @thangldw
Created: 10/10/2026
Status: ✅ Merged
Merged: 10/11/2026
Merged by: @morluto

Base: main ← Head: codex/inspect-wasm-wabt


📝 Commits (3)

  • c3f5766 feat(wasm): inspect local artifacts with WABT
  • f34747b fix(wasm): preserve custom names and failed cleanup ownership
  • 25520cf chore: merge main into WABT artifact inspection

📊 Changes

46 files changed (+2309 additions, -7 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+6 -1)
📝 README.md (+1 -0)
📝 docs/testing.md (+22 -0)
➕ docs/wasm-artifacts.md (+71 -0)
📝 package.json (+3 -0)
📝 scripts/lib/catalog-builders.mjs (+5 -0)
📝 scripts/lib/catalog-core.mjs (+2 -0)
📝 scripts/lib/module-boundaries.mjs (+1 -0)
➕ scripts/verify-packaged-wasm-artifact.mjs (+57 -0)
➕ scripts/verify-wasm-artifact.mjs (+313 -0)
📝 src/application/CapabilityInventory.ts (+9 -0)
➕ src/application/wasm/WasmArtifactPort.ts (+17 -0)
➕ src/application/wasm/WasmArtifactService.test.ts (+79 -0)
➕ src/application/wasm/WasmArtifactService.ts (+100 -0)
📝 src/artifacts/MachOSliceArtifactReader.ts (+1 -1)
📝 src/cli.ts (+2 -0)
➕ src/cli/wasmCommands.ts (+60 -0)
📝 src/cliCommandNames.ts (+1 -0)
➕ src/composition/wasm.ts (+7 -0)
📝 src/contracts/toolContracts.ts (+2 -0)

...and 26 more files

📄 Description

Summary

Fixes #884.

Add inspect-wasm-artifact / inspect_wasm_artifact for explicitly selected local WebAssembly files using caller-supplied WABT 1.0.42. CLI and MCP return identical Evidence with selected artifact and executable digests, validation, section ranges, exact upstream import/export WAT forms, decoded WAT and optional JavaScript glue candidate associations.

Problem and expected behavior

REA previously had no target-free WABT workflow for inspecting a saved website's WASM artifact. Operators should be able to inspect selected bytes, correlate static glue literals with explicit local candidates and read the same Evidence back through MCP, while preserving URL/path ambiguity and the distinction between decoded WAT, original source and runtime behavior.

Change and scope

  • Add a narrow WasmArtifactPort, shared input/output validation service and composition for the optional WABT adapter.
  • Admit the exact 1.0.42 upstream profile, retaining release/source commit, resolved executable paths, SHA-256, version banners and arguments. Use maintained wasm-validate, wasm-objdump and wasm2wat; no WASM binary parser or target interpreter is introduced.
  • Inspect stable selected bytes in a private read-only snapshot; recheck its digest before and after commands. Reuse owned subprocess cancellation, deadlines, output bounds and cleanup. Invalid/truncated modules retain upstream diagnostics and partial Evidence identifying the failed selected bytes.
  • Preserve full objdump output and extract exact top-level WABT WAT import/export forms. This avoids guessing identities from unescaped human-readable objdump names containing dots or newlines.
  • Reuse the existing Babel parser/traversal for selected glue literals. Preserve exact source coordinates, file identity, local path candidates, ambiguous URL/basename matches and unresolved references.
  • Add separate conditional real-tool and packaged-artifact verification lanes, public text fixtures, provenance and operator documentation.

Contract and boundary impact

  • Semantic owner and earliest changed stage: WABT producer admission/output adapters own tool protocol parsing; the application service owns caller validation and CLI/MCP Evidence construction.
  • CLI and MCP/tool-catalog contract: additive command/tool, strict input/output schemas, effect metadata, optional capability availability and provider/catalog registration. No active binary target is required.
  • Provider, bridge, target-format, or platform compatibility: caller-supplied WABT 1.0.42 tools selected by absolute REA_WABT_BIN_DIRECTORY; unsupported/missing profiles return actionable unavailable outcomes. Other providers are unchanged.
  • Evidence, artifact, provenance, or reconstruction contract: selected byte/tool identities, complete producer text/WAT and failure diagnostics are retained; static candidate associations do not prove runtime loading or URL-to-file identity.
  • Process execution, authorization, cleanup, or containment impact: trusted caller-supplied tool execution through existing owned-process supervision; 30-second per-command deadlines and 32 MiB combined output budgets. Cleanup uncertainty is an error. No target execution, implicit fetch, tool installation or OS memory sandbox claim.
  • Generated metadata, package, or installation impact: authored skill version 36, generated package metadata, catalog source registration and packaged WABT provenance README. Ignored catalogs/build outputs and binaries are not committed; no runtime dependency is added.

Evidence and regression coverage

  • Tests added or updated: producer framing and escaped WAT names; glue ambiguity; provider cancellation/deadline propagation, malformed output, snapshot mutation and cleanup uncertainty; application identity validation; actual MCP SDK schemas and session recording. Register the new adapter tests in the existing Vitest project.

  • Base reproduction or other evidence: #884 describes the missing integration; real WABT generates and validates the source-owned fixtures before inspection.

  • User-visible CLI/MCP output: the custom-section fixture reports 76 selected bytes, SHA-256 fc147439b4861e92c2f3f203818dd7a05a0b3c31c76c4096c85fe8dc2b5743c8, a test custom section, decoded @custom "test" "payload", and exact escaped import/export forms. Invalid/truncated inputs return typed errors with captured upstream diagnostics and partial Evidence.

  • Remaining proof gaps: real-tool execution was verified on macOS arm64 with the official release archive digest checked. Linux/Windows need their own real-tool verification; dynamic/computed JS data flow and runtime behavior remain unproven.

  • Observed, derived, and inferred claims remain distinguishable.

  • Artifact identity, source provenance, and failed attempts remain preserved.

  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

  • npm run check — passed typecheck, lint, formatting, knip, metadata and architecture guards; lint has warnings and no errors.
  • npm run docs:check — passed generated catalog/skill/error metadata and documentation checks.
  • Focused contract, capability, WASM service/adapter, MCP SDK and owned-command tests — 83 passed, 3 existing platform-dependent skips across 11 files.
  • npm run verify:test-discovery — all 729 test files discovered exactly once.
  • REA_WABT_BIN_DIRECTORY=... npm run verify:wasm:artifact -- --require-tools — 18 real CLI/MCP cases passed, including exact output, Evidence IDs/readback, invalid/truncated bytes, custom sections and escaped names; verified empty remaining verifier descendants.
  • REA_WABT_BIN_DIRECTORY=... npm run verify:wasm:package — the same 18 real cases passed against a freshly packed package installed into an isolated temporary prefix with lifecycle scripts disabled.
  • npm run verify:package — general packaging, installed CLI/MCP, schemas/catalog, Evidence, skill and startup checks passed.
  • npm run jscpd, npm run scan:todos, git diff --check — passed.
  • Conditional real-tool invocation without configuration — explicit skip; the required-tools mode refuses missing configuration.

Compatibility, safety, and release

  • Breaking changes or migration steps: none; this is an additive optional capability.
  • Real Hopper/Ghidra, browser, or OS coverage: those providers are not involved; real WABT verified on macOS arm64.
  • Package or release metadata impact: skill metadata increments; package release version remains unchanged. No WABT executables are bundled.
  • Security, privacy, process, or containment review: only caller-selected local files are inspected. Fixture binaries, temporary workspaces, downloaded verification tools and private data remain untracked. Caller-supplied executable hashes identify bytes, not publisher authenticity; there is no OS sandbox guarantee.

Review checklist

  • This PR addresses a concrete problem or an agreed enhancement.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked.
  • 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/1533 **Author:** [@thangldw](https://github.com/thangldw) **Created:** 10/10/2026 **Status:** ✅ Merged **Merged:** 10/11/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `codex/inspect-wasm-wabt` --- ### 📝 Commits (3) - [`c3f5766`](https://github.com/morluto/rea/commit/c3f5766a89fb45f86a876375ae1c62b90fb04113) feat(wasm): inspect local artifacts with WABT - [`f34747b`](https://github.com/morluto/rea/commit/f34747be2e9c56d079484fb131f9d67471cc542f) fix(wasm): preserve custom names and failed cleanup ownership - [`25520cf`](https://github.com/morluto/rea/commit/25520cfda839445e959fd9ef400da2a335f6fedc) chore: merge main into WABT artifact inspection ### 📊 Changes **46 files changed** (+2309 additions, -7 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+6 -1) 📝 `README.md` (+1 -0) 📝 `docs/testing.md` (+22 -0) ➕ `docs/wasm-artifacts.md` (+71 -0) 📝 `package.json` (+3 -0) 📝 `scripts/lib/catalog-builders.mjs` (+5 -0) 📝 `scripts/lib/catalog-core.mjs` (+2 -0) 📝 `scripts/lib/module-boundaries.mjs` (+1 -0) ➕ `scripts/verify-packaged-wasm-artifact.mjs` (+57 -0) ➕ `scripts/verify-wasm-artifact.mjs` (+313 -0) 📝 `src/application/CapabilityInventory.ts` (+9 -0) ➕ `src/application/wasm/WasmArtifactPort.ts` (+17 -0) ➕ `src/application/wasm/WasmArtifactService.test.ts` (+79 -0) ➕ `src/application/wasm/WasmArtifactService.ts` (+100 -0) 📝 `src/artifacts/MachOSliceArtifactReader.ts` (+1 -1) 📝 `src/cli.ts` (+2 -0) ➕ `src/cli/wasmCommands.ts` (+60 -0) 📝 `src/cliCommandNames.ts` (+1 -0) ➕ `src/composition/wasm.ts` (+7 -0) 📝 `src/contracts/toolContracts.ts` (+2 -0) _...and 26 more files_ </details> ### 📄 Description ## Summary Fixes #884. Add `inspect-wasm-artifact` / `inspect_wasm_artifact` for explicitly selected local WebAssembly files using caller-supplied WABT 1.0.42. CLI and MCP return identical Evidence with selected artifact and executable digests, validation, section ranges, exact upstream import/export WAT forms, decoded WAT and optional JavaScript glue candidate associations. ## Problem and expected behavior REA previously had no target-free WABT workflow for inspecting a saved website's WASM artifact. Operators should be able to inspect selected bytes, correlate static glue literals with explicit local candidates and read the same Evidence back through MCP, while preserving URL/path ambiguity and the distinction between decoded WAT, original source and runtime behavior. ## Change and scope - Add a narrow `WasmArtifactPort`, shared input/output validation service and composition for the optional WABT adapter. - Admit the exact 1.0.42 upstream profile, retaining release/source commit, resolved executable paths, SHA-256, version banners and arguments. Use maintained `wasm-validate`, `wasm-objdump` and `wasm2wat`; no WASM binary parser or target interpreter is introduced. - Inspect stable selected bytes in a private read-only snapshot; recheck its digest before and after commands. Reuse owned subprocess cancellation, deadlines, output bounds and cleanup. Invalid/truncated modules retain upstream diagnostics and partial Evidence identifying the failed selected bytes. - Preserve full objdump output and extract exact top-level WABT WAT import/export forms. This avoids guessing identities from unescaped human-readable objdump names containing dots or newlines. - Reuse the existing Babel parser/traversal for selected glue literals. Preserve exact source coordinates, file identity, local path candidates, ambiguous URL/basename matches and unresolved references. - Add separate conditional real-tool and packaged-artifact verification lanes, public text fixtures, provenance and operator documentation. ## Contract and boundary impact - Semantic owner and earliest changed stage: WABT producer admission/output adapters own tool protocol parsing; the application service owns caller validation and CLI/MCP Evidence construction. - CLI and MCP/tool-catalog contract: additive command/tool, strict input/output schemas, effect metadata, optional capability availability and provider/catalog registration. No active binary target is required. - Provider, bridge, target-format, or platform compatibility: caller-supplied WABT 1.0.42 tools selected by absolute `REA_WABT_BIN_DIRECTORY`; unsupported/missing profiles return actionable unavailable outcomes. Other providers are unchanged. - Evidence, artifact, provenance, or reconstruction contract: selected byte/tool identities, complete producer text/WAT and failure diagnostics are retained; static candidate associations do not prove runtime loading or URL-to-file identity. - Process execution, authorization, cleanup, or containment impact: trusted caller-supplied tool execution through existing owned-process supervision; 30-second per-command deadlines and 32 MiB combined output budgets. Cleanup uncertainty is an error. No target execution, implicit fetch, tool installation or OS memory sandbox claim. - Generated metadata, package, or installation impact: authored skill version 36, generated package metadata, catalog source registration and packaged WABT provenance README. Ignored catalogs/build outputs and binaries are not committed; no runtime dependency is added. ## Evidence and regression coverage - Tests added or updated: producer framing and escaped WAT names; glue ambiguity; provider cancellation/deadline propagation, malformed output, snapshot mutation and cleanup uncertainty; application identity validation; actual MCP SDK schemas and session recording. Register the new adapter tests in the existing Vitest project. - Base reproduction or other evidence: #884 describes the missing integration; real WABT generates and validates the source-owned fixtures before inspection. - User-visible CLI/MCP output: the custom-section fixture reports 76 selected bytes, SHA-256 `fc147439b4861e92c2f3f203818dd7a05a0b3c31c76c4096c85fe8dc2b5743c8`, a `test` custom section, decoded `@custom "test" "payload"`, and exact escaped import/export forms. Invalid/truncated inputs return typed errors with captured upstream diagnostics and partial Evidence. - Remaining proof gaps: real-tool execution was verified on macOS arm64 with the official release archive digest checked. Linux/Windows need their own real-tool verification; dynamic/computed JS data flow and runtime behavior remain unproven. - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run check` — passed typecheck, lint, formatting, knip, metadata and architecture guards; lint has warnings and no errors. - `npm run docs:check` — passed generated catalog/skill/error metadata and documentation checks. - Focused contract, capability, WASM service/adapter, MCP SDK and owned-command tests — 83 passed, 3 existing platform-dependent skips across 11 files. - `npm run verify:test-discovery` — all 729 test files discovered exactly once. - `REA_WABT_BIN_DIRECTORY=... npm run verify:wasm:artifact -- --require-tools` — 18 real CLI/MCP cases passed, including exact output, Evidence IDs/readback, invalid/truncated bytes, custom sections and escaped names; verified empty remaining verifier descendants. - `REA_WABT_BIN_DIRECTORY=... npm run verify:wasm:package` — the same 18 real cases passed against a freshly packed package installed into an isolated temporary prefix with lifecycle scripts disabled. - `npm run verify:package` — general packaging, installed CLI/MCP, schemas/catalog, Evidence, skill and startup checks passed. - `npm run jscpd`, `npm run scan:todos`, `git diff --check` — passed. - Conditional real-tool invocation without configuration — explicit skip; the required-tools mode refuses missing configuration. ## Compatibility, safety, and release - Breaking changes or migration steps: none; this is an additive optional capability. - Real Hopper/Ghidra, browser, or OS coverage: those providers are not involved; real WABT verified on macOS arm64. - Package or release metadata impact: skill metadata increments; package release version remains unchanged. No WABT executables are bundled. - Security, privacy, process, or containment review: only caller-selected local files are inspected. Fixture binaries, temporary workspaces, downloaded verification tools and private data remain untracked. Caller-supplied executable hashes identify bytes, not publisher authenticity; there is no OS sandbox guarantee. ## Review checklist - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked. - [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-17 21:12:11 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#2951
No description provided.