[PR #2464] [MERGED] feat(wasm): compare retained core-module interfaces #5247

Closed
opened 2026-10-31 01:05:08 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

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

Base: main ← Head: codex/compare-wasm-interfaces


📝 Commits (2)

  • 4e4a262 feat(wasm): compare retained core-module interfaces
  • 01c8eb0 fix(wasm): keep unsupported one-sided interfaces unknown

📊 Changes

29 files changed (+1757 additions, -54 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/references/native-and-artifacts.md (+6 -0)
➕ docs/specs/2356-wasm-interface-comparison/plan.md (+10 -0)
➕ docs/specs/2356-wasm-interface-comparison/spec.md (+61 -0)
➕ docs/specs/2356-wasm-interface-comparison/tasks.md (+8 -0)
➕ docs/specs/2356-wasm-interface-comparison/verification.md (+47 -0)
📝 docs/wasm-artifacts.md (+43 -0)
📝 package.json (+1 -0)
📝 scripts/lib/catalog-builders.mjs (+3 -1)
📝 scripts/verify-wasm-artifact.mjs (+17 -1)
➕ scripts/verify-wasm-interface-comparison.mjs (+208 -0)
➕ src/application/wasm/WasmInterfaceComparisonService.test.ts (+198 -0)
➕ src/application/wasm/WasmInterfaceComparisonService.ts (+250 -0)
📝 src/cli/wasmCommands.ts (+26 -0)
📝 src/cliCommandNames.ts (+1 -0)
📝 src/contracts/toolEffects.test.ts (+2 -0)
📝 src/contracts/toolEffects.ts (+1 -0)
➕ src/contracts/wasm/wasmComparisonContracts.ts (+63 -0)
📝 src/contracts/wasm/wasmToolContracts.ts (+5 -1)
📝 src/domain/wasm/wasmArtifact.ts (+2 -0)
➕ src/domain/wasm/wasmInterface.ts (+109 -0)

...and 9 more files

📄 Description

Summary

Fixes #2356. Adds compare_wasm_interfaces / rea compare-wasm-interfaces to compare declared core-module imports and exports from two authenticated inspect_wasm_artifact Evidence records. Results preserve original artifact identities and distinguish added, removed, changed, unchanged and unknown observations.

Problem and expected behavior

Inspection previously retained exact WAT forms without a typed interface comparison. Byte differences or changed type indices cannot establish whether a function signature changed. The WABT producer now resolves typed interface facts once; comparison consumes those facts without rereading files or reparsing retained display text.

The input requires scope: imports | exports | both and accepts portable inline Evidence or exact current-session references. For example, two differently encoded modules can report unchanged interfaces despite different original SHA-256 digests; a changed parameter type reports changed. Duplicate names and incomplete inventories remain unknown.

Change and scope

  • Add optional producer-owned interface facts with exact decoded names, kinds, resolved function/tag signatures, table/memory limits, memory page size and global type/mutability. Original WAT forms remain intact; historical Evidence can omit the facet.
  • Preserve every duplicate occurrence and unsupported signature. Partial coverage cannot establish absence or per-key uniqueness.
  • Bound declaration allocation and repeated signature expansion; capacity refusal preserves bounded partial facts and the existing WAT observation. Comparison groups linearly and yields for cancellation.
  • Register shared CLI/MCP comparison, update documentation and add spec/plan/verification under docs/specs/2356-wasm-interface-comparison/.
  • Correct the existing real-WABT verifier's stale inline partial-observation assumption by resolving and authenticating the retained MCP record.

This is core-module comparison. #2406 separately adds component decoding; this patch neither depends on nor duplicates its component parser. No component ABI comparison, module instantiation or runtime-compatibility inference is added.

Contract and boundary impact

  • Semantic owner: WABT adapter owns typed decoding; shared application service authenticates and compares supplied Evidence.
  • Scope/maintainer decision: static analysis within existing inspection and artifact-comparison authority; no new provider or expanded target execution/mutation authority. Separate advance decision is not applicable.
  • CLI/MCP: additive comparison tool/command, required scope, optional inspection facet, validated advertised schemas.
  • Compatibility: existing inspection output and historical Evidence remain valid; unsupported signature semantics are explicit unknowns.
  • Provenance: both input Evidence IDs and original path/digest/length are retained; derived Evidence links to its authenticated sources.
  • Authority/cleanup: comparison consumes supplied data only; existing WABT snapshot/process ownership is reused by inspection.
  • Generated/package impact: authored contract/catalog/skill references and an optional verifier command are updated. Ignored generated catalogs, skills and binaries are not committed; no dependency or release-version change.

Expected effects:

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

  • Producer tests cover imported index spaces, escaped/BOM/empty names, all admitted kinds, recursive/unsupported types, memory page size and repeated type-use capacity.
  • Comparison tests cover all result states, duplicate ambiguity, historical/partial observations, tampered identity, retained lookup and cancellation.
  • Public compiled CLI/MCP tests validate advertised schemas, parity, source retention and derived Evidence links.
  • Independent review found and repaired custom page-size omission, shared-signature expansion undercounting, and partial singleton uniqueness. Final review reported no remaining actionable findings.
  • Real owned modules assembled with WABT cover padded LEB128 equivalence, signature/page-size changes, duplicate imports and unadmitted exception reference types. No module was instantiated or executed.

For evidence-bearing changes:

  • Observed and derived claims remain distinguishable.
  • Artifact identity, source provenance and failed attempts remain preserved.
  • Unsupported, partial and uncertain outcomes remain visible.

Validation performed

On main base a2d8b94dd50dab8d966239dd63ab84718aa8b4b4:

  • Focused parser/provider/service/contract/CLI/MCP selection: 56 tests passed in 8 files.
  • npm run check: passed, including typecheck, lint, formatting, knip and architecture guards; lint warnings remain.
  • npm run docs:generate and npm run docs:check: passed.
  • npm run verify:test-discovery: 1011 files, each discovered exactly once.
  • node scripts/verify-wasm-interface-comparison.mjs with WABT 1.0.42: passed through compiled CLI and stdio MCP.
  • node scripts/verify-wasm-artifact.mjs --require-tools: 42 real-tool cases passed.

Compatibility, safety, and release

No breaking change, migration, new dependency or release metadata change. Comparison reads only explicitly supplied Evidence; source acquisition and execution are not performed. Static equality is not runtime/ABI compatibility or successful linking. Real-tool verification covers macOS arm64; native Linux/Windows lanes remain unverified. Token usage and concurrent process-family peak memory are unmeasured. CI remains separate from local verification.

Before merge

  • This PR addresses a concrete enhancement and links its issue.
  • Material scope and authority questions are resolved for this static workflow.
  • One focused outcome with a Conventional Commit title.
  • Tests cover observable behavior and meaningful failure paths.
  • Owning docs, contracts and generated metadata are updated.
  • CLI/MCP parity and representative results are verified.
  • Final diff checked 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/2464 **Author:** [@thangldw](https://github.com/thangldw) **Created:** 10/13/2026 **Status:** ✅ Merged **Merged:** 10/13/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `codex/compare-wasm-interfaces` --- ### 📝 Commits (2) - [`4e4a262`](https://github.com/morluto/rea/commit/4e4a26248312a5050d30860ef324af12d315ff8f) feat(wasm): compare retained core-module interfaces - [`01c8eb0`](https://github.com/morluto/rea/commit/01c8eb023dea91a93574bb542c52f15d6429ce5e) fix(wasm): keep unsupported one-sided interfaces unknown ### 📊 Changes **29 files changed** (+1757 additions, -54 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md` (+6 -0) ➕ `docs/specs/2356-wasm-interface-comparison/plan.md` (+10 -0) ➕ `docs/specs/2356-wasm-interface-comparison/spec.md` (+61 -0) ➕ `docs/specs/2356-wasm-interface-comparison/tasks.md` (+8 -0) ➕ `docs/specs/2356-wasm-interface-comparison/verification.md` (+47 -0) 📝 `docs/wasm-artifacts.md` (+43 -0) 📝 `package.json` (+1 -0) 📝 `scripts/lib/catalog-builders.mjs` (+3 -1) 📝 `scripts/verify-wasm-artifact.mjs` (+17 -1) ➕ `scripts/verify-wasm-interface-comparison.mjs` (+208 -0) ➕ `src/application/wasm/WasmInterfaceComparisonService.test.ts` (+198 -0) ➕ `src/application/wasm/WasmInterfaceComparisonService.ts` (+250 -0) 📝 `src/cli/wasmCommands.ts` (+26 -0) 📝 `src/cliCommandNames.ts` (+1 -0) 📝 `src/contracts/toolEffects.test.ts` (+2 -0) 📝 `src/contracts/toolEffects.ts` (+1 -0) ➕ `src/contracts/wasm/wasmComparisonContracts.ts` (+63 -0) 📝 `src/contracts/wasm/wasmToolContracts.ts` (+5 -1) 📝 `src/domain/wasm/wasmArtifact.ts` (+2 -0) ➕ `src/domain/wasm/wasmInterface.ts` (+109 -0) _...and 9 more files_ </details> ### 📄 Description ## Summary Fixes #2356. Adds `compare_wasm_interfaces` / `rea compare-wasm-interfaces` to compare declared core-module imports and exports from two authenticated `inspect_wasm_artifact` Evidence records. Results preserve original artifact identities and distinguish added, removed, changed, unchanged and unknown observations. ## Problem and expected behavior Inspection previously retained exact WAT forms without a typed interface comparison. Byte differences or changed type indices cannot establish whether a function signature changed. The WABT producer now resolves typed interface facts once; comparison consumes those facts without rereading files or reparsing retained display text. The input requires `scope: imports | exports | both` and accepts portable inline Evidence or exact current-session references. For example, two differently encoded modules can report unchanged interfaces despite different original SHA-256 digests; a changed parameter type reports changed. Duplicate names and incomplete inventories remain unknown. ## Change and scope - Add optional producer-owned `interface` facts with exact decoded names, kinds, resolved function/tag signatures, table/memory limits, memory page size and global type/mutability. Original WAT forms remain intact; historical Evidence can omit the facet. - Preserve every duplicate occurrence and unsupported signature. Partial coverage cannot establish absence or per-key uniqueness. - Bound declaration allocation and repeated signature expansion; capacity refusal preserves bounded partial facts and the existing WAT observation. Comparison groups linearly and yields for cancellation. - Register shared CLI/MCP comparison, update documentation and add spec/plan/verification under `docs/specs/2356-wasm-interface-comparison/`. - Correct the existing real-WABT verifier's stale inline partial-observation assumption by resolving and authenticating the retained MCP record. This is core-module comparison. #2406 separately adds component decoding; this patch neither depends on nor duplicates its component parser. No component ABI comparison, module instantiation or runtime-compatibility inference is added. ## Contract and boundary impact - Semantic owner: WABT adapter owns typed decoding; shared application service authenticates and compares supplied Evidence. - Scope/maintainer decision: static analysis within existing inspection and artifact-comparison authority; no new provider or expanded target execution/mutation authority. Separate advance decision is not applicable. - CLI/MCP: additive comparison tool/command, required scope, optional inspection facet, validated advertised schemas. - Compatibility: existing inspection output and historical Evidence remain valid; unsupported signature semantics are explicit unknowns. - Provenance: both input Evidence IDs and original path/digest/length are retained; derived Evidence links to its authenticated sources. - Authority/cleanup: comparison consumes supplied data only; existing WABT snapshot/process ownership is reused by inspection. - Generated/package impact: authored contract/catalog/skill references and an optional verifier command are updated. Ignored generated catalogs, skills and binaries are not committed; no dependency or release-version change. Expected effects: - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Producer tests cover imported index spaces, escaped/BOM/empty names, all admitted kinds, recursive/unsupported types, memory page size and repeated type-use capacity. - Comparison tests cover all result states, duplicate ambiguity, historical/partial observations, tampered identity, retained lookup and cancellation. - Public compiled CLI/MCP tests validate advertised schemas, parity, source retention and derived Evidence links. - Independent review found and repaired custom page-size omission, shared-signature expansion undercounting, and partial singleton uniqueness. Final review reported no remaining actionable findings. - Real owned modules assembled with WABT cover padded LEB128 equivalence, signature/page-size changes, duplicate imports and unadmitted exception reference types. No module was instantiated or executed. For evidence-bearing changes: - [x] Observed and derived claims remain distinguishable. - [x] Artifact identity, source provenance and failed attempts remain preserved. - [x] Unsupported, partial and uncertain outcomes remain visible. ## Validation performed On main base `a2d8b94dd50dab8d966239dd63ab84718aa8b4b4`: - Focused parser/provider/service/contract/CLI/MCP selection: **56 tests passed in 8 files**. - `npm run check`: passed, including typecheck, lint, formatting, knip and architecture guards; lint warnings remain. - `npm run docs:generate` and `npm run docs:check`: passed. - `npm run verify:test-discovery`: **1011 files**, each discovered exactly once. - `node scripts/verify-wasm-interface-comparison.mjs` with WABT 1.0.42: passed through compiled CLI and stdio MCP. - `node scripts/verify-wasm-artifact.mjs --require-tools`: **42 real-tool cases passed**. ## Compatibility, safety, and release No breaking change, migration, new dependency or release metadata change. Comparison reads only explicitly supplied Evidence; source acquisition and execution are not performed. Static equality is not runtime/ABI compatibility or successful linking. Real-tool verification covers macOS arm64; native Linux/Windows lanes remain unverified. Token usage and concurrent process-family peak memory are unmeasured. CI remains separate from local verification. ## Before merge - [x] This PR addresses a concrete enhancement and links its issue. - [x] Material scope and authority questions are resolved for this static workflow. - [x] One focused outcome with a Conventional Commit title. - [x] Tests cover observable behavior and meaningful failure paths. - [x] Owning docs, contracts and generated metadata are updated. - [x] CLI/MCP parity and representative results are verified. - [x] Final diff checked 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:08 +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#5247
No description provided.