morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #4071] [MERGED] feat(kuna): add bounded call relationships and exact xrefs #6035

New issue

Closed

opened 2026-10-31 01:11:20 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:11:20 +00:00

Owner

📋 Pull Request Information

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

Base: main ← Head: feat/kuna-calls-xrefs-20261015

📝 Commits (5)

d104d69 feat(kuna): add bounded call relationships and exact xrefs
502efdd test(kuna): cover shared admission and retained cleanup leases
c80156a fix(kuna): preserve forwarding instruction addresses outside graph nodes
7f36f42 fix(kuna): preserve graph identity and coverage in composed workflows
7160965 chore(kuna): integrate current provider concurrency fixes

📊 Changes

22 files changed (+2342 additions, -246 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+6 -1)
📝 docs/kuna-provider.md (+22 -10)
📝 docs/testing.md (+6 -2)
➕ scripts/lib/kuna-native-reference-verifier.mjs (+46 -0)
➕ scripts/lib/kuna-reference-verifier.mjs (+109 -0)
📝 scripts/verify-real-kuna.mjs (+44 -6)
➕ src/kuna/KunaAddress.ts (+8 -0)
📝 src/kuna/KunaProvider.ts (+10 -3)
📝 src/kuna/KunaProviderCapabilities.ts (+15 -3)
➕ src/kuna/KunaReferenceFiles.ts (+253 -0)
➕ src/kuna/KunaReferenceQueries.ts (+403 -0)
📝 src/kuna/KunaRunSlots.ts (+6 -5)
📝 src/kuna/KunaSessionClient.ts (+274 -191)
➕ src/kuna/KunaTargetCommands.ts (+229 -0)
📝 tests/boundary/providers/kuna/fakeKuna.ts (+31 -1)
➕ tests/boundary/providers/kuna/kunaCommandLifetime.test.ts (+59 -0)
📝 tests/boundary/providers/kuna/kunaProvider.test.ts (+6 -4)
📝 tests/boundary/providers/kuna/kunaReaderCancellation.test.ts (+24 -10)
➕ tests/boundary/providers/kuna/kunaReferenceFiles.test.ts (+233 -0)
➕ tests/boundary/providers/kuna/kunaReferences.test.ts (+380 -0)

...and 2 more files

📄 Description

Summary

Kuna could decompile functions but could not answer who calls them, what they call, or where an address is referenced. Add procedure_callers, procedure_callees and exact incoming xrefs, enabling existing graph/path workflows and dossier neighbors without starting a C export. Follow-up to #3854; no separate issue.

Change and scope

Reuse existing contracts and Evidence; add no tool declarations. Separate native target/process ownership, reference parsing/indexes, and query sharing. Return selected addresses and provenance; retain exact u64 values and partial coverage for unresolved indirect calls. Keep current main's shared admission, warm-export initialization and retained-run leases (#4045, #4049, #4052). Graph-only entries resolve through the shared graph owner; dossiers retain directional coverage.

Graph JSON is capped at 32 MiB; xrefs at 16 MiB, with a session LRU capped at 16 MiB/128 entries and eight pending distinct queries. Reference commands run serially per session and share foreground admission with decompiles. Cancellation and failed cleanup retain resource owners and admission leases.

Contract and boundary impact

Semantic owner: Kuna adapter validates native facts once; domain/application and CLI/MCP schemas unchanged.
Scope decision: not applicable; existing static read-only provider. No target execution, injection, mutation or protection recovery.
Compatibility: existing documented formats/platforms; real coverage here is Linux x86_64/Kuna 1.833.
Evidence: source digests/counts, exact-address alias filtering, explicit uncertainty. Forwarding instruction addresses remain separate from function identity.
Selection/cleanup: digest-checked private target copy and existing process ownership primitives; unknown cleanup retains ownership.
Metadata/package: authored docs/skill updated; no dependencies, new installation behavior or generated outputs committed.

Expected effects: read local files, launch Kuna, and write/remove owned private copies/caches. Targets are never executed or modified.

Evidence and regression coverage

Real public MCP tests passed on system SQLite/zlib, matching native call/xref projections; source-owned and stripped fixtures; unresolved indirect calls; and an ELF above JavaScript's safe integer range. CLI name-based xrefs passed. Canonical verification passed C/assembly provenance, fresh-server reuse and complete cleanup.

SQLite revealed five forwarding addresses inside functions. Remove the incorrect node-membership invariant, preserve the addresses, and cover the failure with a regression and real rerun.

Measured serially under 2 CPU/3 GiB runtime limits: SQLite completed its calls/xrefs/repeats/additional-functions/path task in 19.71 s, 23.95 s CPU, 739.7 MiB sampled family peak; first graph query 7.93 s, subsequent calls 6.7–10.7 ms. zlib graph/path workflow: 10.92 s, 14.27 s CPU, 674.0 MiB. An identical-head SQLite repeat took 11.24 s, with 3–6 ms warm queries; the variation is not diagnosed. The validation comment records all runs and native controls. Detailed measurements, token estimates and limitations.

Validation performed

Build and npm run docs:check: passed, including five README tests.
npm run typecheck -- --checkers 1, lint, format, knip and architecture guards: passed. Default parallel check:fast is not claimed.
Final Vitest Kuna/process suite: 136 tests/16 files passed.
Real verify-real-kuna.mjs with independent native-site and dossier-coverage checks: passed with complete cleanup; additional public MCP/CLI probes passed. A negative MCP proxy test rejects unrelated xref sites.

Compatibility, safety, and release

No breaking change. No new Ghidra/IDA/macOS/Windows runtime verification. Typed references, CFG, raw memory, annotations, strings and type recovery remain unsupported. Cold graph queries still analyze the image; session caches expire on close. RSS sampling can miss brief peaks; model billing/client filtering were not measured. Existing whole-catalog overhead is unchanged.

Author readiness

Human owner: @N0zoM1z0. Publication, ready status and continued merge are explicitly authorized. Unchecked declarations do not attest that human review occurred.

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

Concrete enhancement; static scope resolved; focused conventional title; related PR linked.
Behavior, malformed input, cancellation, capacity, ownership and cleanup covered.
Docs/skill, representative output and proof gaps recorded.
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/4071 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/15/2026 **Status:** ✅ Merged **Merged:** 10/15/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `feat/kuna-calls-xrefs-20261015` --- ### 📝 Commits (5) - [`d104d69`](https://github.com/morluto/rea/commit/d104d6993e8ce5819d1d9dc1b7773952cc00f906) feat(kuna): add bounded call relationships and exact xrefs - [`502efdd`](https://github.com/morluto/rea/commit/502efdd87910761230cbe588619675cbc6010f1b) test(kuna): cover shared admission and retained cleanup leases - [`c80156a`](https://github.com/morluto/rea/commit/c80156a260b067eb506423afcdf3dbcf3b03eda7) fix(kuna): preserve forwarding instruction addresses outside graph nodes - [`7f36f42`](https://github.com/morluto/rea/commit/7f36f42ecb12b18e63d4c5ca82d1e2ad88dc648b) fix(kuna): preserve graph identity and coverage in composed workflows - [`7160965`](https://github.com/morluto/rea/commit/7160965d7254c7f64a9d2e5376c4f7e901e9114f) chore(kuna): integrate current provider concurrency fixes ### 📊 Changes **22 files changed** (+2342 additions, -246 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+6 -1) 📝 `docs/kuna-provider.md` (+22 -10) 📝 `docs/testing.md` (+6 -2) ➕ `scripts/lib/kuna-native-reference-verifier.mjs` (+46 -0) ➕ `scripts/lib/kuna-reference-verifier.mjs` (+109 -0) 📝 `scripts/verify-real-kuna.mjs` (+44 -6) ➕ `src/kuna/KunaAddress.ts` (+8 -0) 📝 `src/kuna/KunaProvider.ts` (+10 -3) 📝 `src/kuna/KunaProviderCapabilities.ts` (+15 -3) ➕ `src/kuna/KunaReferenceFiles.ts` (+253 -0) ➕ `src/kuna/KunaReferenceQueries.ts` (+403 -0) 📝 `src/kuna/KunaRunSlots.ts` (+6 -5) 📝 `src/kuna/KunaSessionClient.ts` (+274 -191) ➕ `src/kuna/KunaTargetCommands.ts` (+229 -0) 📝 `tests/boundary/providers/kuna/fakeKuna.ts` (+31 -1) ➕ `tests/boundary/providers/kuna/kunaCommandLifetime.test.ts` (+59 -0) 📝 `tests/boundary/providers/kuna/kunaProvider.test.ts` (+6 -4) 📝 `tests/boundary/providers/kuna/kunaReaderCancellation.test.ts` (+24 -10) ➕ `tests/boundary/providers/kuna/kunaReferenceFiles.test.ts` (+233 -0) ➕ `tests/boundary/providers/kuna/kunaReferences.test.ts` (+380 -0) _...and 2 more files_ </details> ### 📄 Description ## Summary Kuna could decompile functions but could not answer who calls them, what they call, or where an address is referenced. Add `procedure_callers`, `procedure_callees` and exact incoming `xrefs`, enabling existing graph/path workflows and dossier neighbors without starting a C export. Follow-up to #3854; no separate issue. ## Change and scope Reuse existing contracts and Evidence; add no tool declarations. Separate native target/process ownership, reference parsing/indexes, and query sharing. Return selected addresses and provenance; retain exact u64 values and partial coverage for unresolved indirect calls. Keep current main's shared admission, warm-export initialization and retained-run leases (#4045, #4049, #4052). Graph-only entries resolve through the shared graph owner; dossiers retain directional coverage. Graph JSON is capped at 32 MiB; xrefs at 16 MiB, with a session LRU capped at 16 MiB/128 entries and eight pending distinct queries. Reference commands run serially per session and share foreground admission with decompiles. Cancellation and failed cleanup retain resource owners and admission leases. ## Contract and boundary impact - Semantic owner: Kuna adapter validates native facts once; domain/application and CLI/MCP schemas unchanged. - Scope decision: not applicable; existing static read-only provider. No target execution, injection, mutation or protection recovery. - Compatibility: existing documented formats/platforms; real coverage here is Linux x86_64/Kuna 1.833. - Evidence: source digests/counts, exact-address alias filtering, explicit uncertainty. Forwarding instruction addresses remain separate from function identity. - Selection/cleanup: digest-checked private target copy and existing process ownership primitives; unknown cleanup retains ownership. - Metadata/package: authored docs/skill updated; no dependencies, new installation behavior or generated outputs committed. Expected effects: read local files, launch Kuna, and write/remove owned private copies/caches. Targets are never executed or modified. ## Evidence and regression coverage Real public MCP tests passed on system SQLite/zlib, matching native call/xref projections; source-owned and stripped fixtures; unresolved indirect calls; and an ELF above JavaScript's safe integer range. CLI name-based xrefs passed. Canonical verification passed C/assembly provenance, fresh-server reuse and complete cleanup. SQLite revealed five forwarding addresses inside functions. Remove the incorrect node-membership invariant, preserve the addresses, and cover the failure with a regression and real rerun. Measured serially under 2 CPU/3 GiB runtime limits: SQLite completed its calls/xrefs/repeats/additional-functions/path task in **19.71 s**, **23.95 s CPU**, **739.7 MiB sampled family peak**; first graph query **7.93 s**, subsequent calls **6.7–10.7 ms**. zlib graph/path workflow: **10.92 s**, **14.27 s CPU**, **674.0 MiB**. An identical-head SQLite repeat took 11.24 s, with 3–6 ms warm queries; the variation is not diagnosed. The validation comment records all runs and native controls. [Detailed measurements, token estimates and limitations](https://github.com/morluto/rea/pull/4071#issuecomment-6189866330). ## Validation performed - Build and `npm run docs:check`: passed, including five README tests. - `npm run typecheck -- --checkers 1`, lint, format, knip and architecture guards: passed. Default parallel `check:fast` is not claimed. - Final Vitest Kuna/process suite: **136 tests/16 files passed**. - Real `verify-real-kuna.mjs` with independent native-site and dossier-coverage checks: passed with complete cleanup; additional public MCP/CLI probes passed. A negative MCP proxy test rejects unrelated xref sites. ## Compatibility, safety, and release No breaking change. No new Ghidra/IDA/macOS/Windows runtime verification. Typed references, CFG, raw memory, annotations, strings and type recovery remain unsupported. Cold graph queries still analyze the image; session caches expire on close. RSS sampling can miss brief peaks; model billing/client filtering were not measured. Existing whole-catalog overhead is unchanged. ## Author readiness Human owner: @N0zoM1z0. Publication, ready status and continued merge are explicitly authorized. Unchecked declarations do not attest that human review occurred. - [ ] 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. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] Concrete enhancement; static scope resolved; focused conventional title; related PR linked. - [x] Behavior, malformed input, cancellation, capacity, ownership and cleanup covered. - [x] Docs/skill, representative output and proof gaps recorded. - [x] 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:11:20 +00:00

closed this issue
added the
pull-request
label

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#6035

No description provided.

Rows
Columns