morluto/rea

Fork 0

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

[PR #3832] [MERGED] feat(kuna): add Kuna readiness, doctor and owned project cache #5932

New issue

Closed

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

bsakaguchi commented

2026-10-31 01:10:33 +00:00

Owner

📋 Pull Request Information

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

Base: main ← Head: feat/kuna-project-cache

📝 Commits (9)

79739bb feat(kuna): add Kuna readiness, doctor and owned project cache
a578931 style(kuna): format the export module with oxfmt
398f00c fix(kuna): close review gaps in the project cache and readiness checks
35f6819 fix(kuna): retire workspaces only after proven process cleanup
70c2e5a fix(kuna): clear recovered file cleanup failures
2d23b43 fix(kuna): protect concurrent exports and waiter progress
7b1b81a chore(kuna): refresh main for final Linux verification
0a20486 fix(kuna): verify exports and finish deferred eviction
ca24750 fix(kuna): protect requests arriving during eviction

📊 Changes

16 files changed (+3530 additions, -1 deletions)

View changed files

📝 src/application/DoctorProviderIds.ts (+7 -1)
📝 src/doctorRuntime.test.ts (+21 -0)
📝 src/doctorRuntime.ts (+2 -0)
➕ src/kuna/KunaConfiguration.ts (+144 -0)
➕ src/kuna/KunaDoctor.ts (+211 -0)
➕ src/kuna/KunaInstallation.ts (+191 -0)
➕ src/kuna/KunaProjectCache.ts (+690 -0)
➕ src/kuna/KunaProjectExport.ts (+466 -0)
➕ src/kuna/KunaProjectFiles.ts (+189 -0)
➕ src/kuna/KunaRelease.ts (+16 -0)
➕ tests/boundary/providers/kuna/fakeKuna.ts (+125 -0)
➕ tests/boundary/providers/kuna/kunaDoctor.test.ts (+136 -0)
➕ tests/boundary/providers/kuna/kunaInstallation.test.ts (+212 -0)
➕ tests/boundary/providers/kuna/kunaProjectCache.test.ts (+704 -0)
➕ tests/boundary/providers/kuna/kunaProjectConcurrency.test.ts (+252 -0)
➕ tests/boundary/providers/kuna/kunaProjectFiles.test.ts (+164 -0)

📄 Description

Summary

First PR of the Kuna provider series. Refs #1957.

It adds the parts every later Kuna operation depends on: a caller-supplied kuna executable selected by REA_KUNA_COMMAND, a readiness probe, rea doctor --provider kuna, and an REA-owned on-disk cache of kuna decompile-project exports. No analysis tool uses Kuna yet; PR2 wires the provider operations on top of this cache.

Problem and expected behavior

Kuna's tested path is a whole-program decompile-project export (see @mahaloz's comments in #1957). REA must not dump that export into an agent's context, and should not re-run a minutes-long export for every function. The cache runs one export per (target digest, Kuna digest, Kuna version, --jobs), keeps it on disk and verified, and lets PR2 answer one function at a time from it.

Change and scope

src/kuna/KunaConfiguration.ts: parses REA_KUNA_COMMAND (absolute; opt-in), REA_KUNA_CACHE_DIR (default ~/Library/Caches/rea/kuna or $XDG_CACHE_HOME/rea/kuna), REA_KUNA_CACHE_MAX_BYTES (default 4 GiB), REA_KUNA_PROJECT_TIMEOUT_MS (default 30 min) and REA_KUNA_JOBS (default 1). Windows is declared unsupported in v1.
src/kuna/KunaInstallation.ts: resolves the executable, probes kuna --version (10 s, 64 KiB), records its SHA-256 and whether it is a #! script (for process-ownership matching). A release other than 1.833 is accepted but reported as unverified.
src/kuna/KunaProjectExport.ts: runs kuna functions --json, then kuna decompile-project --jobs N, both under owned process groups (runOwnedCommand) with one shared deadline, on a copy of the target hashed while copying. It validates the export against Kuna's own functions: N ok, M failed summary.
src/kuna/KunaProjectFiles.ts: the single parser for Kuna's .c // Function: headers (streamed, so a large export is never held in memory), its stdout summary, and the functions --json inventory.
src/kuna/KunaProjectCache.ts: a content-addressed store:
- Private staging, then publication by one rename. Concurrent publishers keep the first.
- Digests are recorded once at publish and checked on each first read; a damaged entry is removed.
- Concurrent requests for one key share one Kuna run, and the run is cancelled only when every waiter is cancelled.
- Least-recently-used eviction above the cap; entries pinned by this process are kept.
- Kuna's own spec cache is kept under the same root (home/) instead of the user's.
src/kuna/KunaDoctor.ts and src/doctorRuntime.ts: doctor inspection. Explicitly set REA_KUNA_* settings are published to client registrations once the installation validates.

Follow-ups by @N0zoM1z0, with Linux verification in the PR conversation:

Staging is never swept by age; only a proven-stopped build moves to trash/. The age option and the .retained marker are gone.
Failed file removals stay owned until close() removes them.
Eviction decisions are serialized, protect unfinished builds and pins, and coalesce a deferred size check.
One listener registration per waiter.
The executable is verified before each command and before publication.

Not included: provider selection, CLI/MCP operations, real-provider lane (PR2), docs, notices and catalog (PR3).

Spike findings (Kuna v1.833, tag `fe01d6294eb0`, built from source; `kuna --version` → `kuna 1.833`)

Matrix: zlib 1.3.2 minigzip, sqlite 3.54.0 shell, coreutils 9.9 sort, each with symbols and stripped, built at -O2 for ELF x86-64, ELF AArch64, Mach-O arm64 and Mach-O x86_64. There is also one ARM Thumb ELF for the Thumb-bit question. Host: Apple M-series, macOS 26.7.1.

CLI behavior

Version probe: kuna --version prints kuna 1.833 and exits 0.
Missing function: exits 1 with a message.
File offsets: --addr with a file offset exits 1 with address … is not mapped.

Addresses

--addr takes link-time virtual addresses.
ELF PIE uses its link-time base with no rebasing, so nm/objdump addresses pass through unchanged.
Mach-O addresses include 0x100000000.
On ARM Thumb, --addr accepts the address with or without the Thumb bit and lists the even address.

Selectors

Selecting by name and by address can print different names (inflate versus _inflate), so PR2 resolves names through the inventory and always decompiles by address.

Spec cache

Kuna unpacks its specs (15 MB) into $HOME/Library/Caches/kuna or $XDG_CACHE_HOME/kuna. REA points HOME and XDG_CACHE_HOME at <cache>/home, so nothing is written to the user's cache.

Procedure list

kuna functions --json is a reliable callable inventory that includes imports, at 0.1–1.6 s and about 210 bytes per function.
The export .c header count matched Kuna's summary on all 24 binaries.
Sizes are upper bounds.
In the arm64 Mach-O zlib build, Kuna lists _inflate as 252 bytes followed by a separate sub_1000070e8, an entry its own analysis invented, with no symbol there. Bounds are therefore reported as Kuna derivations, not ground truth.

Determinism and export mode

A serial non-stream export (--jobs 1) is byte-identical across repeat runs.
A streamed --jobs 6 export is identical per function across runs, but only 35–60% of its functions match the serial export.
The difference is quality: the streamed export loses recovered return values (for example unsigned long __isoc23_strtoul becomes void). In coreutils sort, 149 of 162 differing functions differ in their body.
Kuna's docs name the serial non-stream export as the reference answer, so this PR uses it by default. REA_KUNA_JOBS trades fidelity for speed, and the cache key includes it.
A single-function kuna decompile matches neither export, because it lacks whole-program prototypes. PR2 records which path produced each answer.

Cost of a serial export, Kuna process family (sampled every 100 ms)

Target	Wall	Peak RSS
zlib	1.9–2.9 s	120–225 MiB
coreutils `sort`	5–16 s	220–420 MiB
sqlite3	66–120 s	0.9–1.6 GiB

Cost of a streamed --jobs 6 export

Target	Wall	CPU	Peak RSS
sqlite3	20–45 s	83–146 s	1.9–2.7 GiB

Export size

sqlite3: 4.6–7.0 MiB of .c and 17–22 MiB of .asm.

Contract and boundary impact

Semantic owner and earliest changed stage:
- src/kuna/KunaProjectFiles.ts owns Kuna's file formats.
- src/kuna/KunaProjectCache.ts owns the cache layout and lifetime.
Contribution scope fit and linked maintainer decision: Kuna is static decompilation, which CONTRIBUTING lists as in scope. The operator explicitly authorized this task’s limited static CLI/readiness/cache scope, follow-ups and merge; see the verification/scope record. Broader provider operations remain a separate step tracked by #1957.
CLI and MCP/tool-catalog contract:
- rea doctor --provider accepts kuna.
- No tool, schema or catalog change.
Provider, bridge, target-format, or platform compatibility: Linux and macOS. Windows is unsupported in v1.
Evidence, artifact, provenance, or reconstruction contract: none yet. The manifest records the target digest, Kuna's digest and version, and --jobs.
Target selection, authority, upstream behavior, and cleanup details:
- Kuna runs only on a staged copy of the selected target.
- A process REA cannot prove stopped keeps its staging directory owned and is reported by close().
- REA never installs, downloads or updates Kuna.
Generated metadata, package, or installation impact: none.
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. (Writes only inside the REA-owned Kuna cache directory.)
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

Tests added or updated: tests/boundary/providers/kuna/, 43 tests against a scripted fake kuna.
- Readiness: version, unverified release, garbled output, failed probe, missing or non-executable command, unset versus invalid settings, Windows.
- Parsers: chunk-boundary header scanning, names containing @, failed-function headers, count mismatches, malformed and overlong headers, inventory schema.
- Cache, part 1: publish and reuse, shared run, cancellation by every waiter (process stopped), a single deadline over both commands, failed export, missing summary, miscount, invalid inventory.
- Cache, part 2: target changed after digest, vanished target, tampered entry, LRU with pins, capacity, cross-process publish race, build phases, staging sweep, unproven-cleanup retention.
- Review regressions: a version probe that ignores SIGTERM, an entry evicted by another instance, a replaced abandoned build reported by close(), retained staging never swept, failed publication cleanup, an uncreatable cache root.
- Doctor and setup: src/doctorRuntime.test.ts adds Kuna registration propagation.

Base reproduction or other evidence: a real kuna 1.833 run through the built cache.

Target	Cold build	Warm (fresh instance, verifying digests)	Warm (same instance)	Entry size	REA CPU	REA peak RSS
ELF x86-64 sqlite3	78.6 s	46 ms	0 ms	24.7 MB	0.27 s	81 MiB
Mach-O arm64 stripped sqlite3	88.1 s	58 ms	0 ms	29.2 MB	0.27 s	93 MiB
AArch64 zlib, stripped	2.2 s	4 ms
Mach-O x86-64 sort	6.5 s	5 ms

The cached .c is byte-identical to Kuna's own serial export (31caf8d7… for AArch64 zlib, stripped).

User-visible CLI output: rea doctor --provider kuna --format json reports kuna-installation (version 1.833, sha256) and kuna-cache, both healthy. With Kuna unconfigured, kuna-installation is missing_analysis_engine, the same as the other optional engines in audit-wide mode.
Remaining proof gaps:
- Windows is not supported or tested.
- Linux x86-64 is now verified separately with official Kuna 1.833 musl on Debian 12: five real target families, 5,207 function spans, lifecycle checks and cold/warm/family-resource measurements; see the Linux report. Native Linux arm64 host behavior was not tested.
- The cache has no production consumer until PR2.

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

Latest follow-up ca24750b2: 50 Kuna boundary tests + 4 doctor runtime tests and npm run check passed. Real executable-replacement, concurrent eviction, deferred capacity recovery and progress/cancellation probes passed. The Linux report distinguishes current checks from earlier cold timing observations. Original author validation follows:

npm run check:fast — typecheck and lint passed.
CI on the review-fix head: see checks below (the first run failed format:check on an oxfmt difference, fixed in eb0fd4a2a).
npx vitest run --project boundary tests/boundary/providers/kuna/ — 43 passed; repeated twice after the review fixes with no flakes.
npx vitest run --project adapters src/doctorRuntime.test.ts — 4 passed.
npm run test:focused -- tests/boundary/cli/cliSetup.test.ts tests/boundary/cli/doctorHopperDiscovery.test.ts tests/boundary/cli/mcpDoctorHelpCli.test.ts — passed.
npx knip, npm run format:check, npm run docs:check, npm run metadata:check — passed.
Real Kuna 1.833 cache runs as in the table above.

Compatibility, safety, and release

Breaking changes or migration steps: none.
Real Hopper/Ghidra, browser, or OS coverage: real Kuna 1.833 on macOS arm64 (author) and Debian 12 Linux x86-64 (follow-up). Ghidra is not involved until PR2.
Package or release metadata impact: none.
Security, privacy, process, or containment review:
- Kuna runs with only HOME, XDG_CACHE_HOME, TMPDIR, NO_COLOR and REA's run ID set; no PATH is inherited.
- Cache directories are created with mode 0700.

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/3832 **Author:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Created:** 10/15/2026 **Status:** ✅ Merged **Merged:** 10/15/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `feat/kuna-project-cache` --- ### 📝 Commits (9) - [`79739bb`](https://github.com/morluto/rea/commit/79739bb3e9ab39cb5f8b62f17a4dd4e160012b97) feat(kuna): add Kuna readiness, doctor and owned project cache - [`a578931`](https://github.com/morluto/rea/commit/a578931849ce2cc4906c627248712fe297dba0c7) style(kuna): format the export module with oxfmt - [`398f00c`](https://github.com/morluto/rea/commit/398f00cf12c1194b264e1e5b235902e96723987e) fix(kuna): close review gaps in the project cache and readiness checks - [`35f6819`](https://github.com/morluto/rea/commit/35f681976a52473e456300a403b25e2e634c2f17) fix(kuna): retire workspaces only after proven process cleanup - [`70c2e5a`](https://github.com/morluto/rea/commit/70c2e5a47e0b9940e9d29f55ffae4cf2e46d894f) fix(kuna): clear recovered file cleanup failures - [`2d23b43`](https://github.com/morluto/rea/commit/2d23b430fdd92cec6770583d680fdfd2b785922c) fix(kuna): protect concurrent exports and waiter progress - [`7b1b81a`](https://github.com/morluto/rea/commit/7b1b81a3e3dd4fd8b8ebdc302d7e5bdb7c7c4f2c) chore(kuna): refresh main for final Linux verification - [`0a20486`](https://github.com/morluto/rea/commit/0a204864e653fa6cae2f770fa86d513980e84514) fix(kuna): verify exports and finish deferred eviction - [`ca24750`](https://github.com/morluto/rea/commit/ca24750b2c0c998f0d2a24f6bc778260c7089501) fix(kuna): protect requests arriving during eviction ### 📊 Changes **16 files changed** (+3530 additions, -1 deletions) <details> <summary>View changed files</summary> 📝 `src/application/DoctorProviderIds.ts` (+7 -1) 📝 `src/doctorRuntime.test.ts` (+21 -0) 📝 `src/doctorRuntime.ts` (+2 -0) ➕ `src/kuna/KunaConfiguration.ts` (+144 -0) ➕ `src/kuna/KunaDoctor.ts` (+211 -0) ➕ `src/kuna/KunaInstallation.ts` (+191 -0) ➕ `src/kuna/KunaProjectCache.ts` (+690 -0) ➕ `src/kuna/KunaProjectExport.ts` (+466 -0) ➕ `src/kuna/KunaProjectFiles.ts` (+189 -0) ➕ `src/kuna/KunaRelease.ts` (+16 -0) ➕ `tests/boundary/providers/kuna/fakeKuna.ts` (+125 -0) ➕ `tests/boundary/providers/kuna/kunaDoctor.test.ts` (+136 -0) ➕ `tests/boundary/providers/kuna/kunaInstallation.test.ts` (+212 -0) ➕ `tests/boundary/providers/kuna/kunaProjectCache.test.ts` (+704 -0) ➕ `tests/boundary/providers/kuna/kunaProjectConcurrency.test.ts` (+252 -0) ➕ `tests/boundary/providers/kuna/kunaProjectFiles.test.ts` (+164 -0) </details> ### 📄 Description ## Summary First PR of the Kuna provider series. Refs #1957. It adds the parts every later Kuna operation depends on: a caller-supplied `kuna` executable selected by `REA_KUNA_COMMAND`, a readiness probe, `rea doctor --provider kuna`, and an REA-owned on-disk cache of `kuna decompile-project` exports. No analysis tool uses Kuna yet; PR2 wires the provider operations on top of this cache. ## Problem and expected behavior Kuna's tested path is a whole-program `decompile-project` export (see @mahaloz's comments in #1957). REA must not dump that export into an agent's context, and should not re-run a minutes-long export for every function. The cache runs one export per (target digest, Kuna digest, Kuna version, `--jobs`), keeps it on disk and verified, and lets PR2 answer one function at a time from it. ## Change and scope - `src/kuna/KunaConfiguration.ts`: parses `REA_KUNA_COMMAND` (absolute; opt-in), `REA_KUNA_CACHE_DIR` (default `~/Library/Caches/rea/kuna` or `$XDG_CACHE_HOME/rea/kuna`), `REA_KUNA_CACHE_MAX_BYTES` (default 4 GiB), `REA_KUNA_PROJECT_TIMEOUT_MS` (default 30 min) and `REA_KUNA_JOBS` (default 1). Windows is declared unsupported in v1. - `src/kuna/KunaInstallation.ts`: resolves the executable, probes `kuna --version` (10 s, 64 KiB), records its SHA-256 and whether it is a `#!` script (for process-ownership matching). A release other than 1.833 is accepted but reported as unverified. - `src/kuna/KunaProjectExport.ts`: runs `kuna functions --json`, then `kuna decompile-project --jobs N`, both under owned process groups (`runOwnedCommand`) with one shared deadline, on a copy of the target hashed while copying. It validates the export against Kuna's own `functions: N ok, M failed` summary. - `src/kuna/KunaProjectFiles.ts`: the single parser for Kuna's `.c` `// Function:` headers (streamed, so a large export is never held in memory), its stdout summary, and the `functions --json` inventory. - `src/kuna/KunaProjectCache.ts`: a content-addressed store: - Private staging, then publication by one rename. Concurrent publishers keep the first. - Digests are recorded once at publish and checked on each first read; a damaged entry is removed. - Concurrent requests for one key share one Kuna run, and the run is cancelled only when every waiter is cancelled. - Least-recently-used eviction above the cap; entries pinned by this process are kept. - Kuna's own spec cache is kept under the same root (`home/`) instead of the user's. - `src/kuna/KunaDoctor.ts` and `src/doctorRuntime.ts`: doctor inspection. Explicitly set `REA_KUNA_*` settings are published to client registrations once the installation validates. Follow-ups by @N0zoM1z0, with Linux verification in the PR conversation: - Staging is never swept by age; only a proven-stopped build moves to `trash/`. The age option and the `.retained` marker are gone. - Failed file removals stay owned until `close()` removes them. - Eviction decisions are serialized, protect unfinished builds and pins, and coalesce a deferred size check. - One listener registration per waiter. - The executable is verified before each command and before publication. Not included: provider selection, CLI/MCP operations, real-provider lane (PR2), docs, notices and catalog (PR3). ## Spike findings (Kuna v1.833, tag `fe01d6294eb0`, built from source; `kuna --version` → `kuna 1.833`) Matrix: zlib 1.3.2 `minigzip`, sqlite 3.54.0 shell, coreutils 9.9 `sort`, each with symbols and stripped, built at -O2 for ELF x86-64, ELF AArch64, Mach-O arm64 and Mach-O x86_64. There is also one ARM Thumb ELF for the Thumb-bit question. Host: Apple M-series, macOS 26.7.1. **CLI behavior** - **Version probe:** `kuna --version` prints `kuna 1.833` and exits 0. - **Missing function:** exits 1 with a message. - **File offsets:** `--addr` with a file offset exits 1 with `address … is not mapped`. **Addresses** - `--addr` takes link-time virtual addresses. - ELF PIE uses its link-time base with no rebasing, so `nm`/objdump addresses pass through unchanged. - Mach-O addresses include `0x100000000`. - On ARM Thumb, `--addr` accepts the address with or without the Thumb bit and lists the even address. **Selectors** - Selecting by name and by address can print different names (`inflate` versus `_inflate`), so PR2 resolves names through the inventory and always decompiles by address. **Spec cache** - Kuna unpacks its specs (15 MB) into `$HOME/Library/Caches/kuna` or `$XDG_CACHE_HOME/kuna`. REA points HOME and XDG_CACHE_HOME at `<cache>/home`, so nothing is written to the user's cache. **Procedure list** - `kuna functions --json` is a reliable callable inventory that includes imports, at 0.1–1.6 s and about 210 bytes per function. - The export `.c` header count matched Kuna's summary on all 24 binaries. - Sizes are upper bounds. - In the arm64 Mach-O zlib build, Kuna lists `_inflate` as 252 bytes followed by a separate `sub_1000070e8`, an entry its own analysis invented, with no symbol there. Bounds are therefore reported as Kuna derivations, not ground truth. **Determinism and export mode** - A serial non-stream export (`--jobs 1`) is byte-identical across repeat runs. - A streamed `--jobs 6` export is identical per function across runs, but only 35–60% of its functions match the serial export. - The difference is quality: the streamed export loses recovered return values (for example `unsigned long __isoc23_strtoul` becomes `void`). In coreutils `sort`, 149 of 162 differing functions differ in their body. - Kuna's docs name the serial non-stream export as the reference answer, so this PR uses it by default. `REA_KUNA_JOBS` trades fidelity for speed, and the cache key includes it. - A single-function `kuna decompile` matches neither export, because it lacks whole-program prototypes. PR2 records which path produced each answer. **Cost of a serial export, Kuna process family (sampled every 100 ms)** | Target | Wall | CPU | Peak RSS | |---|---|---|---| | zlib | 1.9–2.9 s | | 120–225 MiB | | coreutils `sort` | 5–16 s | | 220–420 MiB | | sqlite3 | 66–120 s | | 0.9–1.6 GiB | **Cost of a streamed `--jobs 6` export** | Target | Wall | CPU | Peak RSS | |---|---|---|---| | sqlite3 | 20–45 s | 83–146 s | 1.9–2.7 GiB | **Export size** - sqlite3: 4.6–7.0 MiB of `.c` and 17–22 MiB of `.asm`. ## Contract and boundary impact - **Semantic owner and earliest changed stage:** - `src/kuna/KunaProjectFiles.ts` owns Kuna's file formats. - `src/kuna/KunaProjectCache.ts` owns the cache layout and lifetime. - **Contribution scope fit and linked maintainer decision:** Kuna is static decompilation, which CONTRIBUTING lists as in scope. The operator explicitly authorized this task’s limited static CLI/readiness/cache scope, follow-ups and merge; see the [verification/scope record](https://github.com/morluto/rea/pull/3832#issuecomment-6184746570). Broader provider operations remain a separate step tracked by #1957. - **CLI and MCP/tool-catalog contract:** - `rea doctor --provider` accepts `kuna`. - No tool, schema or catalog change. - **Provider, bridge, target-format, or platform compatibility:** Linux and macOS. Windows is unsupported in v1. - **Evidence, artifact, provenance, or reconstruction contract:** none yet. The manifest records the target digest, Kuna's digest and version, and `--jobs`. - **Target selection, authority, upstream behavior, and cleanup details:** - Kuna runs only on a staged copy of the selected target. - A process REA cannot prove stopped keeps its staging directory owned and is reported by `close()`. - REA never installs, downloads or updates Kuna. - **Generated metadata, package, or installation impact:** none. - [x] Read existing files or captured data. - [x] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [x] Change process memory, registers, files, or configuration. (Writes only inside the REA-owned Kuna cache directory.) - [ ] 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 - **Tests added or updated:** `tests/boundary/providers/kuna/`, 43 tests against a scripted fake `kuna`. - Readiness: version, unverified release, garbled output, failed probe, missing or non-executable command, unset versus invalid settings, Windows. - Parsers: chunk-boundary header scanning, names containing ` @ `, failed-function headers, count mismatches, malformed and overlong headers, inventory schema. - Cache, part 1: publish and reuse, shared run, cancellation by every waiter (process stopped), a single deadline over both commands, failed export, missing summary, miscount, invalid inventory. - Cache, part 2: target changed after digest, vanished target, tampered entry, LRU with pins, capacity, cross-process publish race, build phases, staging sweep, unproven-cleanup retention. - Review regressions: a version probe that ignores SIGTERM, an entry evicted by another instance, a replaced abandoned build reported by `close()`, retained staging never swept, failed publication cleanup, an uncreatable cache root. - Doctor and setup: `src/doctorRuntime.test.ts` adds Kuna registration propagation. - **Base reproduction or other evidence:** a real `kuna` 1.833 run through the built cache. | Target | Cold build | Warm (fresh instance, verifying digests) | Warm (same instance) | Entry size | REA CPU | REA peak RSS | |---|---|---|---|---|---|---| | ELF x86-64 sqlite3 | 78.6 s | 46 ms | 0 ms | 24.7 MB | 0.27 s | 81 MiB | | Mach-O arm64 stripped sqlite3 | 88.1 s | 58 ms | 0 ms | 29.2 MB | 0.27 s | 93 MiB | | AArch64 zlib, stripped | 2.2 s | 4 ms | | | | | | Mach-O x86-64 sort | 6.5 s | 5 ms | | | | | The cached `.c` is byte-identical to Kuna's own serial export (`31caf8d7…` for AArch64 zlib, stripped). - **User-visible CLI output:** `rea doctor --provider kuna --format json` reports `kuna-installation` (version 1.833, sha256) and `kuna-cache`, both healthy. With Kuna unconfigured, `kuna-installation` is `missing_analysis_engine`, the same as the other optional engines in audit-wide mode. - **Remaining proof gaps:** - Windows is not supported or tested. - Linux x86-64 is now verified separately with official Kuna 1.833 musl on Debian 12: five real target families, 5,207 function spans, lifecycle checks and cold/warm/family-resource measurements; see the [Linux report](https://github.com/morluto/rea/pull/3832#issuecomment-6184746570). Native Linux arm64 host behavior was not tested. - The cache has no production consumer until PR2. 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 Latest follow-up `ca24750b2`: 50 Kuna boundary tests + 4 doctor runtime tests and `npm run check` passed. Real executable-replacement, concurrent eviction, deferred capacity recovery and progress/cancellation probes passed. The [Linux report](https://github.com/morluto/rea/pull/3832#issuecomment-6184746570) distinguishes current checks from earlier cold timing observations. Original author validation follows: - `npm run check:fast` — typecheck and lint passed. - CI on the review-fix head: see checks below (the first run failed `format:check` on an oxfmt difference, fixed in eb0fd4a2a). - `npx vitest run --project boundary tests/boundary/providers/kuna/` — 43 passed; repeated twice after the review fixes with no flakes. - `npx vitest run --project adapters src/doctorRuntime.test.ts` — 4 passed. - `npm run test:focused -- tests/boundary/cli/cliSetup.test.ts tests/boundary/cli/doctorHopperDiscovery.test.ts tests/boundary/cli/mcpDoctorHelpCli.test.ts` — passed. - `npx knip`, `npm run format:check`, `npm run docs:check`, `npm run metadata:check` — passed. - Real Kuna 1.833 cache runs as in the table above. ## Compatibility, safety, and release - **Breaking changes or migration steps:** none. - **Real Hopper/Ghidra, browser, or OS coverage:** real Kuna 1.833 on macOS arm64 (author) and Debian 12 Linux x86-64 (follow-up). Ghidra is not involved until PR2. - **Package or release metadata impact:** none. - **Security, privacy, process, or containment review:** - Kuna runs with only HOME, XDG_CACHE_HOME, TMPDIR, NO_COLOR and REA's run ID set; no PATH is inherited. - Cache directories are created with mode 0700. ## 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](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:33 +00:00