[PR #3854] [MERGED] feat(kuna): serve procedures, pseudocode and assembly from Kuna exports #5950

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

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/3854
Author: @kaoru0822-kitauji
Created: 10/15/2026
Status: ✅ Merged
Merged: 10/15/2026
Merged by: @kaoru0822-kitauji

Base: main ← Head: feat/kuna-provider


📝 Commits (10+)

  • be04f6e feat(kuna): serve procedures, pseudocode and assembly from Kuna exports
  • 80ce90d fix(kuna): refuse a Ghidra comparison without caller-built targets
  • d762f24 fix(kuna): retry owned cleanup and keep answers bound to the opened Kuna
  • 1b85cef fix(kuna): drain session requests before releasing workspaces
  • 46bac90 perf(kuna): keep document metadata reads free of target analysis
  • ac698eb fix(kuna): reject verification matrices with missing functions
  • 1d1590a fix(kuna): retain component provenance in function dossiers
  • 43e68c1 fix(kuna): keep retired file cleanup bound to its export
  • ef82a84 docs(kuna): document the Kuna provider and list it in the catalog (#3855)
  • b8fc27c fix(kuna): supervise regex and bind reads to one export

📊 Changes

60 files changed (+4297 additions, -493 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+11 -2)
📝 README.md (+2 -1)
📝 THIRD_PARTY_NOTICES.md (+1 -0)
📝 docs/.vitepress/config.ts (+1 -0)
📝 docs/cli.md (+3 -2)
📝 docs/index.md (+1 -1)
📝 docs/installation.md (+7 -7)
➕ docs/kuna-provider.md (+84 -0)
📝 docs/readme/README_ar.md (+1 -1)
📝 docs/readme/README_de.md (+1 -1)
📝 docs/readme/README_el.md (+1 -1)
📝 docs/readme/README_es.md (+1 -1)
📝 docs/readme/README_fa.md (+1 -1)
📝 docs/readme/README_fr.md (+1 -1)
📝 docs/readme/README_id.md (+1 -1)
📝 docs/readme/README_it.md (+1 -1)
📝 docs/readme/README_ja.md (+1 -1)
📝 docs/readme/README_ko.md (+1 -1)
📝 docs/readme/README_pl.md (+1 -1)
📝 docs/readme/README_pt-BR.md (+1 -1)

...and 40 more files

📄 Description

Summary

Register caller-supplied Kuna as a static analysis provider selected by --provider kuna, open_binary.provider_id: "kuna", or REA_ANALYSIS_PROVIDER=kuna. Builds on merged #3832; includes the documentation/catalog work merged into this branch by #3855. Refs #1957.

Kuna answers existing document/procedure listings, search, address/name lookup, pseudocode, assembly and function dossiers; batch_decompile composes the existing tools. No tool/input/output schemas change. ELF and thin Mach-O x86-64, AArch64 and ARM are admitted on Linux/macOS; Windows, PE and universal Mach-O are not admitted. Callers, callees, xrefs and CFG are not implemented by this provider yet.

Behavior and boundaries

  • Cold pseudocode can use one single-function run while the whole-program export builds. Warm answers reuse the verified export. Each answer identifies its source; combined dossiers retain both files/digests/byte ranges and read one immutable project. Losing it retries the complete report.
  • KunaProjectReader owns export parsing/index reuse. Shared process/RegexMatcher owns cancellable ECMAScript matching with a five-second deadline; Hopper reuses it while preserving its error contract. Literal searches stay on their direct path. The unchanged legacy IDA matcher is outside this fix.
  • close_binary combines caller/session cancellation, drains active work, and retains/retries unproven process cleanup and failed file removal by export key. Document metadata does not start target analysis.
  • Cached text and single-function capture share a 16 MiB buffered-facet budget checked before allocation. Complete exports stay local. The first analyze_function response still contains the full dossier; later paging does not remove that initial transfer.
  • Kuna runs only on digest-verified private copies, under owned process supervision and a minimal child environment. The target is never executed or modified. Executable SHA-256/version/jobs remain in the profile; changed executables are refused. Auto selection remains ambiguous if multiple providers admit the target.
  • The operator explicitly authorized this static provider scope, follow-ups and integration; scope/coordination. Writes and process launches are confined to provider/cache/runtime machinery; no target injection, mutation, network workflow or protection recovery is added.

Performed validation

  • npm run check: passed, including module boundaries and architecture guards.
  • npx vitest run tests/boundary/providers/kuna tests/boundary/process/regexMatcher.test.ts src/ida src/doctorRuntime.test.ts: 406 passed in 28 files. Covers malformed output, cancellation/deadline, ownership recovery, parallel eviction, source coherence, capacity and negative matrix selection.
  • npm run docs:check: passed, including generated catalog/skill validation and five README consistency tests after integrating #3855.
  • Real Linux Kuna 1.833 MCP: source-owned symbol-bearing/stripped fixtures, system zlib 1.2.13 and SQLite 3.40.1, cold/export/fresh-server paths, exact exported spans/digests and stopped process lineage. Ghidra 12.1.4 / JDK 21 compared the same system functions. Measurements and limitations, cleanup fault injection.
  • After the reader refactor, real fixtures and the SQLite dossier passed again: 126847 pseudocode bytes, 7277 assembly lines; warm MCP call 462 ms, serialized reply 1273372 UTF-8 bytes. One observation on a shared host, not a speedup claim.
  • Both new review findings were reproduced: the old regex predicate exceeded a 1.5 s watchdog; a barrier-driven eviction test produced mixed sources. Fixed tests verify bounded matching and complete-report retry. Regex fix, reader fix.

The original author's macOS matrix also covered ELF/Mach-O x86-64/AArch64; this independent Linux run covers ELF x86-64. No real IDA/Hopper, Linux ARM, Windows or semantic-equivalence claim is made. Response bytes and marker counts do not measure model tokens or whole-agent performance. The verifier rejects empty/unmatched/partly matched caller matrices before running providers. Final-head CI/review are in progress.

Author readiness

Human owner:

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

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.

🤖 Generated with Claude Code


🔄 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/3854 **Author:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Created:** 10/15/2026 **Status:** ✅ Merged **Merged:** 10/15/2026 **Merged by:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Base:** `main` ← **Head:** `feat/kuna-provider` --- ### 📝 Commits (10+) - [`be04f6e`](https://github.com/morluto/rea/commit/be04f6e65c8c1f7e73b432274feaffae69daf55a) feat(kuna): serve procedures, pseudocode and assembly from Kuna exports - [`80ce90d`](https://github.com/morluto/rea/commit/80ce90d107d6b9f2db1b44b3d772ae25031a389f) fix(kuna): refuse a Ghidra comparison without caller-built targets - [`d762f24`](https://github.com/morluto/rea/commit/d762f2430c9e05bef7fa8ea35df2856aaca2cec5) fix(kuna): retry owned cleanup and keep answers bound to the opened Kuna - [`1b85cef`](https://github.com/morluto/rea/commit/1b85cefdd88c75e8b42160cf42f2de90cb8e1ed7) fix(kuna): drain session requests before releasing workspaces - [`46bac90`](https://github.com/morluto/rea/commit/46bac90e75589e81d4ed92bc03167634fc2c2457) perf(kuna): keep document metadata reads free of target analysis - [`ac698eb`](https://github.com/morluto/rea/commit/ac698eb7f1f362f345100c3fc9d598e63f02445b) fix(kuna): reject verification matrices with missing functions - [`1d1590a`](https://github.com/morluto/rea/commit/1d1590a5900d1a9587dfb694f951f667c7432b07) fix(kuna): retain component provenance in function dossiers - [`43e68c1`](https://github.com/morluto/rea/commit/43e68c1df04f7accff50890222bf4234467f0425) fix(kuna): keep retired file cleanup bound to its export - [`ef82a84`](https://github.com/morluto/rea/commit/ef82a84a0d9136e663e9f3bfcf76b2b3dc434af6) docs(kuna): document the Kuna provider and list it in the catalog (#3855) - [`b8fc27c`](https://github.com/morluto/rea/commit/b8fc27c9a1e128577c316b017fec24fdf674e3ac) fix(kuna): supervise regex and bind reads to one export ### 📊 Changes **60 files changed** (+4297 additions, -493 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+11 -2) 📝 `README.md` (+2 -1) 📝 `THIRD_PARTY_NOTICES.md` (+1 -0) 📝 `docs/.vitepress/config.ts` (+1 -0) 📝 `docs/cli.md` (+3 -2) 📝 `docs/index.md` (+1 -1) 📝 `docs/installation.md` (+7 -7) ➕ `docs/kuna-provider.md` (+84 -0) 📝 `docs/readme/README_ar.md` (+1 -1) 📝 `docs/readme/README_de.md` (+1 -1) 📝 `docs/readme/README_el.md` (+1 -1) 📝 `docs/readme/README_es.md` (+1 -1) 📝 `docs/readme/README_fa.md` (+1 -1) 📝 `docs/readme/README_fr.md` (+1 -1) 📝 `docs/readme/README_id.md` (+1 -1) 📝 `docs/readme/README_it.md` (+1 -1) 📝 `docs/readme/README_ja.md` (+1 -1) 📝 `docs/readme/README_ko.md` (+1 -1) 📝 `docs/readme/README_pl.md` (+1 -1) 📝 `docs/readme/README_pt-BR.md` (+1 -1) _...and 40 more files_ </details> ### 📄 Description ## Summary Register caller-supplied Kuna as a static analysis provider selected by `--provider kuna`, `open_binary.provider_id: "kuna"`, or `REA_ANALYSIS_PROVIDER=kuna`. Builds on merged #3832; includes the documentation/catalog work merged into this branch by #3855. Refs #1957. Kuna answers existing document/procedure listings, search, address/name lookup, pseudocode, assembly and function dossiers; `batch_decompile` composes the existing tools. No tool/input/output schemas change. ELF and thin Mach-O x86-64, AArch64 and ARM are admitted on Linux/macOS; Windows, PE and universal Mach-O are not admitted. Callers, callees, xrefs and CFG are not implemented by this provider yet. ## Behavior and boundaries - Cold pseudocode can use one single-function run while the whole-program export builds. Warm answers reuse the verified export. Each answer identifies its source; combined dossiers retain both files/digests/byte ranges and read one immutable project. Losing it retries the complete report. - `KunaProjectReader` owns export parsing/index reuse. Shared `process/RegexMatcher` owns cancellable ECMAScript matching with a five-second deadline; Hopper reuses it while preserving its error contract. Literal searches stay on their direct path. The unchanged legacy IDA matcher is outside this fix. - `close_binary` combines caller/session cancellation, drains active work, and retains/retries unproven process cleanup and failed file removal by export key. Document metadata does not start target analysis. - Cached text and single-function capture share a 16 MiB buffered-facet budget checked before allocation. Complete exports stay local. The first `analyze_function` response still contains the full dossier; later paging does not remove that initial transfer. - Kuna runs only on digest-verified private copies, under owned process supervision and a minimal child environment. The target is never executed or modified. Executable SHA-256/version/jobs remain in the profile; changed executables are refused. Auto selection remains ambiguous if multiple providers admit the target. - The operator explicitly authorized this static provider scope, follow-ups and integration; [scope/coordination](https://github.com/morluto/rea/pull/3854#issuecomment-6185688836). Writes and process launches are confined to provider/cache/runtime machinery; no target injection, mutation, network workflow or protection recovery is added. ## Performed validation - `npm run check`: passed, including module boundaries and architecture guards. - `npx vitest run tests/boundary/providers/kuna tests/boundary/process/regexMatcher.test.ts src/ida src/doctorRuntime.test.ts`: **406 passed** in 28 files. Covers malformed output, cancellation/deadline, ownership recovery, parallel eviction, source coherence, capacity and negative matrix selection. - `npm run docs:check`: passed, including generated catalog/skill validation and five README consistency tests after integrating #3855. - Real Linux Kuna 1.833 MCP: source-owned symbol-bearing/stripped fixtures, system zlib 1.2.13 and SQLite 3.40.1, cold/export/fresh-server paths, exact exported spans/digests and stopped process lineage. Ghidra 12.1.4 / JDK 21 compared the same system functions. [Measurements and limitations](https://github.com/morluto/rea/pull/3854#issuecomment-6185870391), [cleanup fault injection](https://github.com/morluto/rea/pull/3854#issuecomment-6186252006). - After the reader refactor, real fixtures and the SQLite dossier passed again: 126847 pseudocode bytes, 7277 assembly lines; warm MCP call 462 ms, serialized reply 1273372 UTF-8 bytes. One observation on a shared host, not a speedup claim. - Both new review findings were reproduced: the old regex predicate exceeded a 1.5 s watchdog; a barrier-driven eviction test produced mixed sources. Fixed tests verify bounded matching and complete-report retry. [Regex fix](https://github.com/morluto/rea/pull/3854#discussion_r4280237081), [reader fix](https://github.com/morluto/rea/pull/3854#discussion_r4280237080). The original author's macOS matrix also covered ELF/Mach-O x86-64/AArch64; this independent Linux run covers ELF x86-64. No real IDA/Hopper, Linux ARM, Windows or semantic-equivalence claim is made. Response bytes and marker counts do not measure model tokens or whole-agent performance. The verifier rejects empty/unmatched/partly matched caller matrices before running providers. Final-head CI/review are in progress. ## Author readiness Human owner: <!-- @GitHub-handle --> - [ ] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [ ] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [ ] I declare this PR ready for initial maintainer review. ## 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. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-10-31 01:10:40 +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#5950
No description provided.