[PR #1540] [MERGED] fix(javascript): accept the Wakaru 1.x release line and verify 1.14.0 #2956

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

📋 Pull Request Information

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

Base: main ← Head: fix/wakaru-release-line


📝 Commits (3)

  • 5e7bee7 fix(javascript): accept the Wakaru 1.x release line and verify 1.14.0
  • 1cd1e2f fix(javascript): project known Wakaru warning fields
  • b691b8b Merge remote-tracking branch 'origin/main' into HEAD

📊 Changes

16 files changed (+272 additions, -66 deletions)

View changed files

📝 .github/workflows/real-javascript-recovery.yml (+2 -2)
📝 docs/javascript-recovery.md (+34 -7)
📝 docs/testing.md (+4 -2)
📝 scripts/verify/javascript/recovery.mjs (+3 -3)
📝 src/application/CapabilityInventory.ts (+1 -1)
📝 src/contracts/javascript/javascriptRecoveryToolContracts.ts (+1 -1)
📝 src/javascript/recovery/WakaruCommand.ts (+1 -1)
📝 src/javascript/recovery/WakaruExecution.ts (+36 -32)
📝 src/javascript/recovery/WakaruPublication.ts (+17 -3)
📝 src/javascript/recovery/WakaruRelease.ts (+11 -3)
📝 src/javascript/recovery/WakaruReport.ts (+12 -7)
➕ src/javascript/recovery/WakaruVersion.test.ts (+39 -0)
➕ src/javascript/recovery/WakaruVersion.ts (+39 -0)
📝 tests/boundary/javascript-recovery/wakaruIntegration.test.ts (+38 -0)
📝 tests/fixtures/javascript-recovery/producer.mjs (+33 -3)
📝 third_party/wakaru (+1 -1)

📄 Description

Summary

I maintain Wakaru. The recovery adapter from #848 only runs with Wakaru 1.13.0. It rejects every other build by exact --version equality, and z.strictObject rejects any field Wakaru adds to its reports. So each Wakaru release breaks recover_javascript_sources until REA re-pins.

Wakaru 1.14.0 is out. Starting with that release, Wakaru documents a compatibility policy for its machine-readable output: within a major version, --version, --json, provenance.json and the exit status rules change only by addition (new fields, and new values for category fields such as kind and status). Wakaru's own tests lock the current key sets.

This PR applies the release-line pattern from #844 (Binwalk/Unblob) and #840 (Ghidra) to Wakaru, and moves the verified build to 1.14.0.

Problem and expected behavior

  • Trigger: set REA_WAKARU_COMMAND to any Wakaru build other than 1.13.0, such as 1.14.0.
  • Before: capability_unavailable, "This adapter requires Wakaru 1.13.0".
  • After: 1.14.0 is verified. Any other ^1.13.0 release is compatible: it is accepted, Evidence reports the observed version instead of the pinned constant, and a limitation says the parser was not verified against that release. Other versions are still refused, with the accepted range in the message.

First-time users also had no install hint. The refusal now points to a new "Install Wakaru" section with the release-binary and npm commands. A user write-up on rea-agents@5.0.0 (ai-100days day 010) hit this and had to guess npm install wakaru@1.13.0, then find the platform binary inside node_modules by hand.

Change and scope

  • WakaruVersion.ts: admitWakaruVersion returns verified / compatible / unsupported, like admitFirmwareVersion. It uses the existing semver dependency. The accepted range is a major line (^1.13.0), not major.minor: Wakaru ships a minor release every one to three weeks and never ships patch releases, so a minor line would still be an exact pin in practice. The upstream policy above is what makes the major line safe.
  • WakaruReport.ts: z.strictObject → z.looseObject, so unknown fields are kept in raw_result, not stripped. modules[].status is now a string; it was already exposed as reported_status: string. kind stays "javascript": REA never passes --vue-sfc, so another kind would mean a non-JS artifact that REA should not publish as a module.
  • Unchanged: module path normalization, input-snapshot binding, UTF-8 range checks, the reported-vs-observed file set (extra-file, extra-provenance), symlink rejection, source-map validation, and engine/input digest re-checks.
  • Pin moves: WAKARU_RELEASE, third_party/wakaru (8219bf50, v1.14.0), the CI download and SHA-256, and verify:javascript:recovery.
  • Not included: macOS/Windows hosts, multi-file inputs, bun extract. I can open issues for those if you're interested.

Contract and boundary impact

  • Semantic owner and earliest changed stage: Wakaru adapter version admission (src/javascript/recovery/).
  • CLI and MCP/tool-catalog contract: the tool description and the provider_missing remediation now name ^1.13.0 (verified with 1.14.0). Input and output schemas are unchanged.
  • Provider, bridge, target-format, or platform compatibility: accepts Wakaru ^1.13.0; verified build 1.14.0. Still Linux x64 only.
  • Evidence, artifact, provenance, or reconstruction contract: engine.version and the provider version are now the observed version, not the pinned constant. Compatible releases add one limitation. audited_source_revision is still the pinned revision.
  • Process execution, authorization, cleanup, or containment impact: none.
  • Generated metadata, package, or installation impact: metadata:generate and docs:generate produced no tracked changes. No package changes.

Evidence and regression coverage

  • Tests added or updated:
    • WakaruVersion.test.ts: verified 1.14.0; compatible 1.13.0 and 1.15.2; rejects 1.12.0, 2.0.0, prerelease, v-prefixed, bare and empty banners.
    • wakaruIntegration.test.ts + producer.mjs: a new additive mode reports wakaru 1.99.0, unknown fields at every report and provenance level, and an unknown module status. The test expects complete, the observed version in engine.version and provider.version, the compatibility limitation, and the unknown field preserved in reports/stdout.json. On the base revision, this mode would fail at the version check, and then at strict parsing (source-derived; not run).
  • Base reproduction or other evidence: I ran REA's five verification fixtures (built with esbuild 0.25.10 and webpack 5.101.3 via buildRecoveryFixtures) through the darwin-arm64 builds of Wakaru 1.13.0 and 1.14.0 with the adapter's exact arguments. Both versions gave the same report keys, module kinds and statuses, formats, module counts, and safety, and the recovered entry passed the fixture oracle for every non-inspection case. The Linux x64 1.14.0 binary from the release tarball and from @wakaru/cli-linux-x64@1.14.0 on npm have the same SHA-256 (664fa067…).
  • User-visible CLI/MCP output: refusal message "Provide an absolute REA_WAKARU_COMMAND pointing to a Wakaru ^1.13.0 Linux x64 binary (verified with 1.14.0); no tool is installed by REA. See docs/javascript-recovery.md#install-wakaru."
  • Remaining proof gaps: I could not run verify:javascript:recovery with the real Linux x64 binary; real-javascript-recovery.yml covers that on this PR. The Linux-only boundary suite ran in an arm64 node:24.18.0 container with the platform guard lifted locally; that change is not part of this PR.

For evidence-bearing changes:

  • 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

  • npx vitest run src/javascript/recovery/WakaruVersion.test.ts (macOS): 9 passed
  • npx vitest run tests/boundary/javascript-recovery src/javascript/recovery (Linux arm64 container, node:24.18.0, platform guard lifted locally): 40 passed
  • npx vitest run src/application src/contracts src/javascript tests/acceptance/nonBinaryComposition.test.ts (macOS): 707 passed, 5 skipped
  • npm run check:fast: passed
  • npm run docs:check: passed
  • npm run verify:test-discovery: passed
  • oxfmt --check on changed files: passed

Compatibility, safety, and release

  • Breaking changes or migration steps: none. 1.13.0 is still accepted, now as compatible.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable; the real Wakaru lane runs in CI on Linux x64.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: admission now runs untested parser paths for releases in the accepted range. Every safety check on paths, ranges, files and digests is unchanged, and each run records the executed binary's SHA-256.

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, or the reason for not linking one is stated above. (Follows #827/#848; same pattern as #844 and #840.)
  • 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/1540 **Author:** [@pionxzh](https://github.com/pionxzh) **Created:** 10/10/2026 **Status:** ✅ Merged **Merged:** 10/10/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `fix/wakaru-release-line` --- ### 📝 Commits (3) - [`5e7bee7`](https://github.com/morluto/rea/commit/5e7bee772160b8c15db71f1bad413f953be598d9) fix(javascript): accept the Wakaru 1.x release line and verify 1.14.0 - [`1cd1e2f`](https://github.com/morluto/rea/commit/1cd1e2f35ba9ff3801e08adfbf0b11931a29d567) fix(javascript): project known Wakaru warning fields - [`b691b8b`](https://github.com/morluto/rea/commit/b691b8bc851d916c9a76ea9ff786d16101bd5ba5) Merge remote-tracking branch 'origin/main' into HEAD ### 📊 Changes **16 files changed** (+272 additions, -66 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/real-javascript-recovery.yml` (+2 -2) 📝 `docs/javascript-recovery.md` (+34 -7) 📝 `docs/testing.md` (+4 -2) 📝 `scripts/verify/javascript/recovery.mjs` (+3 -3) 📝 `src/application/CapabilityInventory.ts` (+1 -1) 📝 `src/contracts/javascript/javascriptRecoveryToolContracts.ts` (+1 -1) 📝 `src/javascript/recovery/WakaruCommand.ts` (+1 -1) 📝 `src/javascript/recovery/WakaruExecution.ts` (+36 -32) 📝 `src/javascript/recovery/WakaruPublication.ts` (+17 -3) 📝 `src/javascript/recovery/WakaruRelease.ts` (+11 -3) 📝 `src/javascript/recovery/WakaruReport.ts` (+12 -7) ➕ `src/javascript/recovery/WakaruVersion.test.ts` (+39 -0) ➕ `src/javascript/recovery/WakaruVersion.ts` (+39 -0) 📝 `tests/boundary/javascript-recovery/wakaruIntegration.test.ts` (+38 -0) 📝 `tests/fixtures/javascript-recovery/producer.mjs` (+33 -3) 📝 `third_party/wakaru` (+1 -1) </details> ### 📄 Description ## Summary I maintain Wakaru. The recovery adapter from #848 only runs with Wakaru 1.13.0. It rejects every other build by exact `--version` equality, and `z.strictObject` rejects any field Wakaru adds to its reports. So each Wakaru release breaks `recover_javascript_sources` until REA re-pins. Wakaru 1.14.0 is out. Starting with that release, Wakaru documents a [compatibility policy for its machine-readable output](https://github.com/pionxzh/wakaru/blob/v1.14.0/docs/cli.md#machine-readable-output-compatibility): within a major version, `--version`, `--json`, `provenance.json` and the exit status rules change only by addition (new fields, and new values for category fields such as `kind` and `status`). Wakaru's own tests lock the current key sets. This PR applies the release-line pattern from #844 (Binwalk/Unblob) and #840 (Ghidra) to Wakaru, and moves the verified build to 1.14.0. ## Problem and expected behavior - Trigger: set `REA_WAKARU_COMMAND` to any Wakaru build other than 1.13.0, such as 1.14.0. - Before: `capability_unavailable`, "This adapter requires Wakaru 1.13.0". - After: 1.14.0 is `verified`. Any other `^1.13.0` release is `compatible`: it is accepted, Evidence reports the observed version instead of the pinned constant, and a limitation says the parser was not verified against that release. Other versions are still refused, with the accepted range in the message. First-time users also had no install hint. The refusal now points to a new "Install Wakaru" section with the release-binary and npm commands. A user write-up on `rea-agents@5.0.0` ([ai-100days day 010](https://github.com/Matsushima-A-830/ai-100days/blob/main/articles/day-010-rea-reverse-engineering-mcp-limits.md)) hit this and had to guess `npm install wakaru@1.13.0`, then find the platform binary inside `node_modules` by hand. ## Change and scope - `WakaruVersion.ts`: `admitWakaruVersion` returns `verified` / `compatible` / `unsupported`, like `admitFirmwareVersion`. It uses the existing `semver` dependency. The accepted range is a major line (`^1.13.0`), not major.minor: Wakaru ships a minor release every one to three weeks and never ships patch releases, so a minor line would still be an exact pin in practice. The upstream policy above is what makes the major line safe. - `WakaruReport.ts`: `z.strictObject` → `z.looseObject`, so unknown fields are kept in `raw_result`, not stripped. `modules[].status` is now a string; it was already exposed as `reported_status: string`. `kind` stays `"javascript"`: REA never passes `--vue-sfc`, so another kind would mean a non-JS artifact that REA should not publish as a module. - Unchanged: module path normalization, input-snapshot binding, UTF-8 range checks, the reported-vs-observed file set (`extra-file`, `extra-provenance`), symlink rejection, source-map validation, and engine/input digest re-checks. - Pin moves: `WAKARU_RELEASE`, `third_party/wakaru` (`8219bf50`, v1.14.0), the CI download and SHA-256, and `verify:javascript:recovery`. - Not included: macOS/Windows hosts, multi-file inputs, `bun extract`. I can open issues for those if you're interested. ## Contract and boundary impact - Semantic owner and earliest changed stage: Wakaru adapter version admission (`src/javascript/recovery/`). - CLI and MCP/tool-catalog contract: the tool description and the `provider_missing` remediation now name `^1.13.0 (verified with 1.14.0)`. Input and output schemas are unchanged. - Provider, bridge, target-format, or platform compatibility: accepts Wakaru `^1.13.0`; verified build 1.14.0. Still Linux x64 only. - Evidence, artifact, provenance, or reconstruction contract: `engine.version` and the provider version are now the observed version, not the pinned constant. Compatible releases add one limitation. `audited_source_revision` is still the pinned revision. - Process execution, authorization, cleanup, or containment impact: none. - Generated metadata, package, or installation impact: `metadata:generate` and `docs:generate` produced no tracked changes. No package changes. ## Evidence and regression coverage - Tests added or updated: - `WakaruVersion.test.ts`: verified 1.14.0; compatible 1.13.0 and 1.15.2; rejects 1.12.0, 2.0.0, prerelease, `v`-prefixed, bare and empty banners. - `wakaruIntegration.test.ts` + `producer.mjs`: a new `additive` mode reports `wakaru 1.99.0`, unknown fields at every report and provenance level, and an unknown module status. The test expects `complete`, the observed version in `engine.version` and `provider.version`, the compatibility limitation, and the unknown field preserved in `reports/stdout.json`. On the base revision, this mode would fail at the version check, and then at strict parsing (source-derived; not run). - Base reproduction or other evidence: I ran REA's five verification fixtures (built with esbuild 0.25.10 and webpack 5.101.3 via `buildRecoveryFixtures`) through the darwin-arm64 builds of Wakaru 1.13.0 and 1.14.0 with the adapter's exact arguments. Both versions gave the same report keys, module kinds and statuses, formats, module counts, and `safety`, and the recovered entry passed the fixture oracle for every non-inspection case. The Linux x64 1.14.0 binary from the release tarball and from `@wakaru/cli-linux-x64@1.14.0` on npm have the same SHA-256 (`664fa067…`). - User-visible CLI/MCP output: refusal message "Provide an absolute REA_WAKARU_COMMAND pointing to a Wakaru ^1.13.0 Linux x64 binary (verified with 1.14.0); no tool is installed by REA. See docs/javascript-recovery.md#install-wakaru." - Remaining proof gaps: I could not run `verify:javascript:recovery` with the real Linux x64 binary; `real-javascript-recovery.yml` covers that on this PR. The Linux-only boundary suite ran in an arm64 `node:24.18.0` container with the platform guard lifted locally; that change is not part of this PR. For evidence-bearing changes: - [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 - `npx vitest run src/javascript/recovery/WakaruVersion.test.ts` (macOS): 9 passed - `npx vitest run tests/boundary/javascript-recovery src/javascript/recovery` (Linux arm64 container, `node:24.18.0`, platform guard lifted locally): 40 passed - `npx vitest run src/application src/contracts src/javascript tests/acceptance/nonBinaryComposition.test.ts` (macOS): 707 passed, 5 skipped - `npm run check:fast`: passed - `npm run docs:check`: passed - `npm run verify:test-discovery`: passed - `oxfmt --check` on changed files: passed ## Compatibility, safety, and release - Breaking changes or migration steps: none. 1.13.0 is still accepted, now as `compatible`. - Real Hopper/Ghidra, browser, or OS coverage: not applicable; the real Wakaru lane runs in CI on Linux x64. - Package or release metadata impact: none. - Security, privacy, process, or containment review: admission now runs untested parser paths for releases in the accepted range. Every safety check on paths, ranges, files and digests is unchanged, and each run records the executed binary's SHA-256. ## 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, or the reason for not linking one is stated above. (Follows #827/#848; same pattern as #844 and #840.) - [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:14 +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#2956
No description provided.