Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(kuna): serve procedures, pseudocode and assembly from Kuna exports (#3854)
Kaoru0822c1fd496e6a1d
diff --git a/.agents/skills/reverse-engineer-anything/SKILL.md b/.agents/skills/reverse-engineer-anything/SKILL.mdindex 426a05ae5..d0f2f640a 100644--- a/.agents/skills/reverse-engineer-anything/SKILL.md+++ b/.agents/skills/reverse-engineer-anything/SKILL.md@@ -59,7 +59,7 @@ availability have different remedies; avoid repeating setup for all of them.absent, inspect the client's MCP launch error rather than repeating setup.REA setup never installs or upgrades Node.js, npm, Homebrew, Java, Ghidra, IDA,-JADX, Binwalk, or Unblob. Use existing prerequisites; do not install unrelated+JADX, Kuna, Binwalk, or Unblob. Use existing prerequisites; do not install unrelatedsoftware to repairMCP registration. For an unsupported client, use manual stdio registrationwith a version-pinned `rea-agents` package or continue through the CLI.@@ -79,7 +79,7 @@ is within the authorized scope, use `npx -y rea-agents@latest` in its place.Configuration repair starts with a read-only setup plan; show paths, backups andskill replacement before applying authorized changes. Preserve existing approvaland target-execution boundaries. REA setup never installs or upgrades unrelated-software, including Node.js, npm, Homebrew, Java, Ghidra, IDA, JADX, Binwalk or Unblob.+software, including Node.js, npm, Homebrew, Java, Ghidra, IDA, JADX, Kuna, Binwalk or Unblob.## Route the target first@@ -215,6 +215,15 @@ after opening; IDA does not supply `binary_overview`. Consult session availabiliwhen composing broader workflows. Modern direct callers and unsupported dossierfacets remain unknown; live IDA results are not replayed from snapshots.+With `REA_KUNA_COMMAND` configured, `provider_id: "kuna"` answers procedure+lists, lookups, pseudocode, assembly and `analyze_function` from Kuna's cached+whole-program export; it has no cross-references, callers or CFG. A cold first+answer can come from a single-function run (its limitations say so); assembly+waits for the export. For pseudocode and assembly, `raw_result.source` names the+cached `.c`/`.asm` file and byte span, which you may search directly instead of+calling per function. See the+[Kuna provider guide](https://github.com/morluto/rea/blob/main/docs/kuna-provider.md).+If the user says only "my app" without a name, path, or target already selectedfor this task, ask which app before searching for artifacts. Paths in unrelatedsaved reports and nearby test fixtures do not select the user's target. Resolvediff --git a/README.md b/README.mdindex 0cf0c68de..89a53ff75 100644--- a/README.md+++ b/README.md@@ -205,7 +205,8 @@ or update either provider.Native formats and host support vary by provider. See[Hopper and Ghidra setup](docs/installation.md#hopper), the-[IDA guide](docs/ida-provider.md) (including an optional native MCP bridge), and+[IDA guide](docs/ida-provider.md) (including an optional native MCP bridge), the+[Kuna decompiler guide](docs/kuna-provider.md), and[experimental Windows Ghidra support](docs/windows-ghidra-p0.md).Ghidra also supports [16-bit DOS analysis](docs/ghidra-dos.md).For large binaries, raise the provider's startup deadline withdiff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.mdindex 5fceaaa47..2648af329 100644--- a/THIRD_PARTY_NOTICES.md+++ b/THIRD_PARTY_NOTICES.md@@ -58,6 +58,7 @@ pin inspection sources; they are not included in the npm package.| ghidra-nativeaot | [MIT](https://github.com/Washi1337/ghidra-nativeaot/blob/effeb734fc570c32650f88b159608979dc7b423e/LICENSE.md) | Pinned inspection source; derived parser attribution above. || JADX | [Apache-2.0](https://github.com/skylot/jadx/blob/v1.5.6/LICENSE) | The audited jadx-headless-mcp source uses JADX 1.5.6 for Android decompilation; the engine JAR is separately supplied. || jadx-headless-mcp | [Apache-2.0](https://github.com/1013503897/jadx-headless-mcp/blob/5844800a486d2248fa949b74c9896285f5b54de2/LICENSE) | v0.7.1; pinned submodule and user-supplied JAR. |+| Kuna | [Apache-2.0](https://github.com/Noelo-Lab/kuna/blob/v1.833/LICENSE), with its [NOTICE](https://github.com/Noelo-Lab/kuna/blob/v1.833/NOTICE) | Bring your own `kuna`; REA verified 1.833 and never downloads, installs or bundles it. REA invokes it as a separate process. || Apktool | [Apache-2.0](https://github.com/iBotPeaches/Apktool/blob/master/LICENSE.md) | User-supplied Android resource decoder. || Binwalk | [MIT](https://github.com/ReFirmLabs/binwalk/blob/4fdab3d464d97b68e0af9088df3f9e2e1545b21c/LICENSE) | v3.1.0; pinned submodule and user-supplied firmware engine. || Unblob | [MIT](https://github.com/onekey-sec/unblob/blob/1fcc7a0a584a70a96c31f5a276c20944d199a089/LICENSE) | 26.6.4; pinned submodule and user-supplied firmware engine. |diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex 440338f98..0c00bb997 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -60,6 +60,7 @@ export default defineConfig({collapsed: true,items: [{ text: "IDA", link: "/ida-provider" },+ { text: "Kuna", link: "/kuna-provider" },{ text: "Ghidra on Windows", link: "/windows-ghidra-p0" },{ text: "Ghidra DOS analysis", link: "/ghidra-dos" },{ text: "Ghidra raw binary", link: "/raw-binary" },diff --git a/docs/cli.md b/docs/cli.mdindex 0922f584a..b087b1b90 100644--- a/docs/cli.md+++ b/docs/cli.md@@ -95,8 +95,9 @@ dependency edges, and the section's file range. A missing `.dep-v0` section isnull metadata, not proof that the binary has no dependencies. See[Rust binaries](rust-binaries.md).-Configure [Hopper or Ghidra](installation.md#hopper), or the-[IDA adapter](ida-provider.md), before analyzing a native target. Substitute+Configure [Hopper or Ghidra](installation.md#hopper), the+[IDA adapter](ida-provider.md), or [Kuna](kuna-provider.md) before analyzing a+native target. Substituteyour target, search text and function name or address in these examples:```bashdiff --git a/docs/index.md b/docs/index.mdindex 5acee1b55..fbdc936b1 100644--- a/docs/index.md+++ b/docs/index.md@@ -50,7 +50,7 @@ For runtime instrumentation, see the [Frida guide](./frida-instrumentation.md).| Task | Guides || --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || Inspect native functions, references, or types | [Native binaries](native-investigation.md), [Go metadata](go-binaries.md), [Rust dependencies](rust-binaries.md), [offline ELF layout](binary-diagnostics.md), [recorded crashes](recorded-crashes.md) |-| Select a native provider or import format | [Ghidra semantics](ghidra-provider.md), [Windows](windows-ghidra-p0.md), [DOS](ghidra-dos.md), [raw bytes](raw-binary.md), [MIPS](ghidra-mips.md), [PSP](ghidra-psp.md), [NativeAOT](ghidra-nativeaot.md), [IDA](ida-provider.md), [JEB](jeb-analysis.md) |+| Select a native provider or import format | [Ghidra semantics](ghidra-provider.md), [Windows](windows-ghidra-p0.md), [DOS](ghidra-dos.md), [raw bytes](raw-binary.md), [MIPS](ghidra-mips.md), [PSP](ghidra-psp.md), [NativeAOT](ghidra-nativeaot.md), [IDA](ida-provider.md), [Kuna](kuna-provider.md), [JEB](jeb-analysis.md) || Analyze JavaScript or Electron artifacts | [Static analysis](javascript-artifact-reconstruction.md), [tracing and comparisons](javascript-application-workflows.md), [application graph](javascript-application-graph.md), [source recovery](javascript-recovery.md) || Compare static JavaScript with runtime observations | [Runtime attribution](javascript-runtime-observation.md), [reconciliation](javascript-runtime-reconciliation.md), [Electron observation](electron-observation.md), [Electron fuses](electron-fuses.md) || Inspect assemblies, packages, or firmware | [.NET](managed-code-analysis.md), [Android](android-analysis.md), [Apktool resources](apktool-resource-analysis.md), [ADB acquisition](adb-device-analysis.md), [Apple](apple-application-analysis.md), [Harmony](harmony-analysis.md), [firmware](firmware-analysis.md), [WASM](wasm-artifacts.md), [EVM](evm-bytecode.md) |diff --git a/docs/installation.md b/docs/installation.mdindex 527014e54..b057b981e 100644--- a/docs/installation.md+++ b/docs/installation.md@@ -3,13 +3,13 @@Run REA, connect your selected agents, and check the tools needed for your task.Setup previews configuration changes and asks for approval before applying them.-| Task | Section |-| --------------------------------- | ------------------------------------------------------------------------- |-| Connect an agent | [Start setup](#start-setup), then [review changes](#review-setup-changes) |-| Diagnose one task | [Scoped readiness checks](#check-readiness-for-your-task) |-| Configure an analysis engine | [Hopper](#hopper), [Ghidra](#ghidra), or the [IDA guide](ida-provider.md) |-| Update or remove REA | [Maintenance](#diagnose-update-and-remove) |-| Resolve a client-specific problem | [Client configuration](client-configuration.md) |+| Task | Section |+| --------------------------------- | --------------------------------------------------------------------------------------------------- |+| Connect an agent | [Start setup](#start-setup), then [review changes](#review-setup-changes) |+| Diagnose one task | [Scoped readiness checks](#check-readiness-for-your-task) |+| Configure an analysis engine | [Hopper](#hopper), [Ghidra](#ghidra), the [IDA guide](ida-provider.md), or [Kuna](kuna-provider.md) |+| Update or remove REA | [Maintenance](#diagnose-update-and-remove) |+| Resolve a client-specific problem | [Client configuration](client-configuration.md) |## Start setupdiff --git a/docs/kuna-provider.md b/docs/kuna-provider.mdnew file mode 100644index 000000000..67cbe8b2e--- /dev/null+++ b/docs/kuna-provider.md@@ -0,0 +1,84 @@+# Kuna provider++[Kuna](https://github.com/Noelo-Lab/kuna) is an Apache-2.0 decompiler distributed as one `kuna` executable. REA uses a `kuna` you supply. It does not download, install, update or bundle Kuna. REA verified this provider with Kuna 1.833; it accepts other releases and reports them as unverified in `rea doctor` and in each analysis profile.++Kuna is static: it reads the selected image and never executes it.++## Configure++```bash+export REA_KUNA_COMMAND=/absolute/path/to/kuna+rea doctor --provider kuna+```++Select it explicitly with `--provider kuna`, MCP's `open_binary.provider_id: "kuna"`, or `REA_ANALYSIS_PROVIDER=kuna`. With Kuna and another provider configured for the same target, `auto` reports `ambiguous` instead of choosing one.++| Setting | Default | Meaning |+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `REA_KUNA_COMMAND` | none (required) | Absolute path of the `kuna` executable. |+| `REA_KUNA_CACHE_DIR` | `~/Library/Caches/rea/kuna` (macOS), `$XDG_CACHE_HOME/rea/kuna` (Linux; `~/.cache/rea/kuna` when `XDG_CACHE_HOME` is unset or relative) | Absolute directory REA owns for project exports. Kuna's own spec cache also lives here, not in your Kuna cache. |+| `REA_KUNA_CACHE_MAX_BYTES` | 4 GiB | Size cap; least recently used exports are evicted above it. |+| `REA_KUNA_PROJECT_TIMEOUT_MS` | 30 minutes | Deadline for one project export. |+| `REA_KUNA_TIMEOUT_MS` | 120 s | Deadline for one single-function decompile. |+| `REA_KUNA_JOBS` | 1 | `decompile-project --jobs`. 1 is Kuna's reference answer; more jobs finish sooner but lose callee-first prototypes, and change about 40–60% of function bodies on the measured binaries. |++Windows is not supported yet. Supported targets are ELF and thin Mach-O executables for x86-64, AArch64 and ARM; PE and universal Mach-O are rejected with a typed reason.++## What Kuna answers++| Tool | Source |+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |+| `list_procedures`, `search_procedures`, `procedure_address` | Kuna's callable inventory (`kuna functions --json`), including import slots it does not decompile |+| `address_name` | Function entries, then the data labels Kuna's export assigns |+| `procedure_pseudo_code`, `batch_decompile` | The project export, or a single-function run while the export builds |+| `procedure_assembly` | The project export's labeled listing |+| `analyze_function` | Pseudocode and assembly from the export; callers, callees, references, comments, strings and CFG are declared unavailable |++Cross-references, callers, callees and basic blocks are not available from this provider. Use another provider when you need them.++## How answers are produced++The first analysis request in a session looks for this target's export in the cache. `list_documents` reads the selected path without initializing analysis. The export is keyed by the target's SHA-256, the Kuna executable's SHA-256, its version and `--jobs`.++- **Warm cache:** analysis reads reuse the verified export. A fresh server verifies its file digests; that cost scales with export size.+- **Cold cache:**+ - REA starts `kuna decompile-project` in the background on a private copy of the target.+ - Meanwhile, pseudocode comes from one `kuna decompile --addr` run, and listings from `kuna functions --json`.+ - Assembly and data names wait for the export; progress notifications report the wait every ten seconds.+ - A single-function answer says so in its limitations. It lacks the export's whole-program prototypes, so a later request can return different text for the same function.++Pseudocode, assembly, `analyze_function` and data-name answers record where their text came from in `raw_result.source`: `single-function`, or `project-export` with the cache directory. `procedure_pseudo_code` and `procedure_assembly` answers from the export also name the file, byte span and the file's SHA-256. Combined `analyze_function` answers retain both facet records in `raw_result.source.files`, each with its file, digest and byte span. Both texts come from one export; losing that project retries the complete report. Listings and procedure lookups carry no `raw_result`. Agents can open or search the export's `.c` and `.asm` there directly when that is cheaper than calling a tool per function. Text read that way is target-derived, like any decompiler output, but it bypasses the untrusted-content marker that REA's tool results carry.++The background export belongs to the session. `close_binary`, or the end of a CLI command, cancels it unless another session still waits for it. A one-shot CLI decompile therefore answers from a single-function run; any request that needs the export, such as `procedure_assembly` or `analyze_function`, keeps it.++Regex procedure search uses ECMAScript Unicode matching in a cancellable worker with a five-second matching deadline. Literal matching remains the default. Cancellation or a matching deadline leaves the session available.++Single-function subprocess output and each cached source facet share a 16 MiB buffered-text capacity. Cached spans are checked before allocation; larger text remains in the local export and the error identifies the file and range. `analyze_function` initially returns the complete dossier, which can still be large; later retained views do not remove that first transfer. Prefer the individual text tools for a focused question.++## Provenance and limitations++- Addresses and bytes are Kuna's observations of the image. Procedure entries and extents are its derivations: extents are upper bounds clipped at the next entry, and Kuna can split one function at an entry its own analysis infers. Pseudocode is its reconstruction, never original source.+- Pseudocode and assembly are exact Kuna text; text from Kuna and from another provider is not comparable as equal or different.+- Results are re-read rather than replayed from REA's analysis snapshots, because a cold answer can differ from the export's.++## Cache ownership++REA writes Kuna's exports only inside `REA_KUNA_CACHE_DIR`:++- `projects/<key>/` holds published, immutable exports with a manifest of file digests.+- `staging/` holds builds whose processes may still be live.+- `trash/` holds retired builds and evicted exports awaiting removal.+- `home/` is Kuna's HOME.++Builds publish by one rename, so a reader sees a complete export or none. A session keeps the export it uses from eviction only within its own REA process. If another REA process sharing the cache evicts it, the session rebuilds it; meanwhile pseudocode falls back to single-function runs. A damaged or edited export is removed and rebuilt. Staging moves to `trash/` for removal only after REA proves its Kuna process stopped. Staging of a process it cannot prove stopped is never swept; REA keeps it owned, retries the stop on `close_binary`, and reports it until the stop is proven. Failed file removal also stays bound to its export and is retried by `close_binary`; closing does not report success while that cleanup remains. `rea doctor --provider kuna` reports the cache directory without creating it.++## Verify with a real Kuna++```bash+REA_KUNA_COMMAND=/absolute/path/to/kuna npm run verify:kuna+# Compare with Ghidra on caller-built binaries+REA_KUNA_COMMAND=/absolute/path/to/kuna GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra \+ npm run verify:kuna -- --targets DIR --functions inflate,crc32 --compare-ghidra+```++The lane compiles a small source-owned fixture with the host C compiler and verifies the MCP workflow end to end. `--targets DIR --functions a,b` adds caller-built binaries. `--compare-ghidra` (with `GHIDRA_INSTALL_DIR`) runs those same functions through Ghidra; it requires `--targets` and `--functions` and refuses empty matrices or requested function names missing from every target. See [testing](testing.md#kuna-lane) for coverage.diff --git a/docs/readme/README_ar.md b/docs/readme/README_ar.mdindex 3e483ea9b..c207ad00b 100644--- a/docs/readme/README_ar.md+++ b/docs/readme/README_ar.md@@ -166,7 +166,7 @@ npx rea-agents@latest setup<a id="choosing-a-deep-analysis-provider"></a>-تختلف صيغ ملفات الشيفرة الأصلية والأنظمة المضيفة المدعومة باختلاف الموفّر. راجع [إعداد Hopper وGhidra](../installation.md#hopper)، و[دليل IDA](../ida-provider.md)، و[دعم Ghidra التجريبي على Windows](../windows-ghidra-p0.md). يدعم Ghidra أيضًا [تحليل DOS ذي 16 بت](../ghidra-dos.md). لاختيار الموفّر، راجع [دليل CLI](../cli.md#choose-a-provider). تحقّق من [توفر الميزات في الإصدارات](../installation.md#released-package-and-main) للميزات المضافة بعد أحدث إصدار على npm.+تختلف صيغ ملفات الشيفرة الأصلية والأنظمة المضيفة المدعومة باختلاف الموفّر. راجع [إعداد Hopper وGhidra](../installation.md#hopper)، و[دليل IDA](../ida-provider.md)، [Kuna](../kuna-provider.md)، و[دعم Ghidra التجريبي على Windows](../windows-ghidra-p0.md). يدعم Ghidra أيضًا [تحليل DOS ذي 16 بت](../ghidra-dos.md). لاختيار الموفّر، راجع [دليل CLI](../cli.md#choose-a-provider). تحقّق من [توفر الميزات في الإصدارات](../installation.md#released-package-and-main) للميزات المضافة بعد أحدث إصدار على npm.## دراسات الحالةdiff --git a/docs/readme/README_de.md b/docs/readme/README_de.mdindex 014b9d21b..d069bd075 100644--- a/docs/readme/README_de.md+++ b/docs/readme/README_de.md@@ -166,7 +166,7 @@ Statische JavaScript- und .NET-Untersuchungen lesen die bereitgestellten Dateien<a id="choosing-a-deep-analysis-provider"></a>-Native Formate und unterstützte Hostsysteme unterscheiden sich je nach Provider. Siehe [Hopper- und Ghidra-Einrichtung](../installation.md#hopper), den [IDA-Leitfaden](../ida-provider.md) und die [experimentelle Ghidra-Unterstützung unter Windows](../windows-ghidra-p0.md). Ghidra unterstützt auch [16-Bit-DOS-Analyse](../ghidra-dos.md). Die Provider-Auswahl beschreibt der [CLI-Leitfaden](../cli.md#choose-a-provider). Prüfe die [Verfügbarkeit in Releases](../installation.md#released-package-and-main) für Funktionen, die seit der neuesten npm-Version hinzugekommen sind.+Native Formate und unterstützte Hostsysteme unterscheiden sich je nach Provider. Siehe [Hopper- und Ghidra-Einrichtung](../installation.md#hopper), den [IDA-Leitfaden](../ida-provider.md), [Kuna](../kuna-provider.md) und die [experimentelle Ghidra-Unterstützung unter Windows](../windows-ghidra-p0.md). Ghidra unterstützt auch [16-Bit-DOS-Analyse](../ghidra-dos.md). Die Provider-Auswahl beschreibt der [CLI-Leitfaden](../cli.md#choose-a-provider). Prüfe die [Verfügbarkeit in Releases](../installation.md#released-package-and-main) für Funktionen, die seit der neuesten npm-Version hinzugekommen sind.## Fallstudiendiff --git a/docs/readme/README_el.md b/docs/readme/README_el.mdindex 7e7c53487..83ac1a962 100644--- a/docs/readme/README_el.md+++ b/docs/readme/README_el.md@@ -179,7 +179,7 @@ npx rea-agents@latest setup<a id="choosing-a-deep-analysis-provider"></a>-Οι μορφές κώδικα μηχανής και τα υποστηριζόμενα συστήματα διαφέρουν ανά πάροχο ανάλυσης. Δες τη [ρύθμιση Hopper και Ghidra](../installation.md#hopper), τον [οδηγό IDA](../ida-provider.md) (που περιλαμβάνει προαιρετική γέφυρα MCP για κώδικα μηχανής) και την [πειραματική υποστήριξη Ghidra στα Windows](../windows-ghidra-p0.md). Το Ghidra υποστηρίζει επίσης [ανάλυση DOS 16 bit](../ghidra-dos.md). Για μεγάλα δυαδικά αρχεία, αύξησε το χρονικό όριο εκκίνησης του παρόχου με `REA_GHIDRA_STARTUP_TIMEOUT_MS` ή `REA_HOPPER_STARTUP_TIMEOUT_MS`. Για την επιλογή παρόχου, δες τον [οδηγό CLI](../cli.md#choose-a-provider). Έλεγξε τη [διαθεσιμότητα ανά έκδοση](../installation.md#released-package-and-main) για λειτουργίες που προστέθηκαν μετά την τελευταία έκδοση στο npm.+Οι μορφές κώδικα μηχανής και τα υποστηριζόμενα συστήματα διαφέρουν ανά πάροχο ανάλυσης. Δες τη [ρύθμιση Hopper και Ghidra](../installation.md#hopper), τον [οδηγό IDA](../ida-provider.md) (που περιλαμβάνει προαιρετική γέφυρα MCP για κώδικα μηχανής), [Kuna](../kuna-provider.md) και την [πειραματική υποστήριξη Ghidra στα Windows](../windows-ghidra-p0.md). Το Ghidra υποστηρίζει επίσης [ανάλυση DOS 16 bit](../ghidra-dos.md). Για μεγάλα δυαδικά αρχεία, αύξησε το χρονικό όριο εκκίνησης του παρόχου με `REA_GHIDRA_STARTUP_TIMEOUT_MS` ή `REA_HOPPER_STARTUP_TIMEOUT_MS`. Για την επιλογή παρόχου, δες τον [οδηγό CLI](../cli.md#choose-a-provider). Έλεγξε τη [διαθεσιμότητα ανά έκδοση](../installation.md#released-package-and-main) για λειτουργίες που προστέθηκαν μετά την τελευταία έκδοση στο npm.## Μελέτες περίπτωσηςdiff --git a/docs/readme/README_es.md b/docs/readme/README_es.mdindex b218c4e22..9ef6032d8 100644--- a/docs/readme/README_es.md+++ b/docs/readme/README_es.md@@ -166,7 +166,7 @@ La inspección estática de JavaScript y .NET lee los archivos suministrados sin<a id="choosing-a-deep-analysis-provider"></a>-Los formatos nativos y los sistemas anfitriones compatibles varían según el proveedor. Consulta [configuración de Hopper y Ghidra](../installation.md#hopper), la [guía de IDA](../ida-provider.md) y la [compatibilidad experimental de Ghidra en Windows](../windows-ghidra-p0.md). Ghidra también admite [análisis de DOS de 16 bits](../ghidra-dos.md). Para elegir un proveedor, consulta la [guía de CLI](../cli.md#choose-a-provider). Comprueba la [disponibilidad por versión](../installation.md#released-package-and-main) de las funciones añadidas después de la última versión publicada en npm.+Los formatos nativos y los sistemas anfitriones compatibles varían según el proveedor. Consulta [configuración de Hopper y Ghidra](../installation.md#hopper), la [guía de IDA](../ida-provider.md), [Kuna](../kuna-provider.md) y la [compatibilidad experimental de Ghidra en Windows](../windows-ghidra-p0.md). Ghidra también admite [análisis de DOS de 16 bits](../ghidra-dos.md). Para elegir un proveedor, consulta la [guía de CLI](../cli.md#choose-a-provider). Comprueba la [disponibilidad por versión](../installation.md#released-package-and-main) de las funciones añadidas después de la última versión publicada en npm.## Casos prácticosdiff --git a/docs/readme/README_fa.md b/docs/readme/README_fa.mdindex c7f3d2d7d..fe9e68fdc 100644--- a/docs/readme/README_fa.md+++ b/docs/readme/README_fa.md@@ -158,7 +158,7 @@ REA به Node.js 22.x (>=22.19)، 24.x (>=24.11) یا 26+، بههمراه np<a id="choosing-a-deep-analysis-provider"></a>-فرمتهای بومی و پشتیبانی سیستم میزبان بر اساس ارائهدهنده متفاوتاند. [راهاندازی Hopper و Ghidra](../installation.md#hopper)، [راهنمای IDA](../ida-provider.md) و [پشتیبانی آزمایشی Ghidra در ویندوز](../windows-ghidra-p0.md) را ببینید. Ghidra همچنین از [تحلیل DOS شانزدهبیتی](../ghidra-dos.md) پشتیبانی میکند. برای انتخاب ارائهدهنده، به [راهنمای CLI](../cli.md#choose-a-provider) مراجعه کنید. برای قابلیتهایی که پس از آخرین انتشار npm اضافه شدهاند، [وضعیت انتشار](../installation.md#released-package-and-main) را بررسی کنید.+فرمتهای بومی و پشتیبانی سیستم میزبان بر اساس ارائهدهنده متفاوتاند. [راهاندازی Hopper و Ghidra](../installation.md#hopper)، [راهنمای IDA](../ida-provider.md)، [Kuna](../kuna-provider.md) و [پشتیبانی آزمایشی Ghidra در ویندوز](../windows-ghidra-p0.md) را ببینید. Ghidra همچنین از [تحلیل DOS شانزدهبیتی](../ghidra-dos.md) پشتیبانی میکند. برای انتخاب ارائهدهنده، به [راهنمای CLI](../cli.md#choose-a-provider) مراجعه کنید. برای قابلیتهایی که پس از آخرین انتشار npm اضافه شدهاند، [وضعیت انتشار](../installation.md#released-package-and-main) را بررسی کنید.## نمونههای عملیdiff --git a/docs/readme/README_fr.md b/docs/readme/README_fr.mdindex a5fbe8eb9..bde58fa38 100644--- a/docs/readme/README_fr.md+++ b/docs/readme/README_fr.md@@ -170,7 +170,7 @@ L'inspection statique JavaScript et .NET lit les fichiers fournis sans exécuter<a id="choosing-a-deep-analysis-provider"></a>-Les formats natifs et les hôtes pris en charge varient selon le fournisseur. Consultez [la configuration de Hopper et Ghidra](../installation.md#hopper), le [guide IDA](../ida-provider.md) et [la prise en charge expérimentale de Ghidra sous Windows](../windows-ghidra-p0.md). Ghidra prend aussi en charge [l'analyse DOS 16 bits](../ghidra-dos.md). Pour les gros binaires, augmentez son délai de démarrage avec `REA_GHIDRA_STARTUP_TIMEOUT_MS`. Pour le choix du fournisseur, consultez le [guide CLI](../cli.md#choose-a-provider). Vérifiez la [disponibilité dans les versions publiées](../installation.md#released-package-and-main) pour les fonctionnalités ajoutées depuis la dernière version npm.+Les formats natifs et les hôtes pris en charge varient selon le fournisseur. Consultez [la configuration de Hopper et Ghidra](../installation.md#hopper), le [guide IDA](../ida-provider.md), [Kuna](../kuna-provider.md) et [la prise en charge expérimentale de Ghidra sous Windows](../windows-ghidra-p0.md). Ghidra prend aussi en charge [l'analyse DOS 16 bits](../ghidra-dos.md). Pour les gros binaires, augmentez son délai de démarrage avec `REA_GHIDRA_STARTUP_TIMEOUT_MS`. Pour le choix du fournisseur, consultez le [guide CLI](../cli.md#choose-a-provider). Vérifiez la [disponibilité dans les versions publiées](../installation.md#released-package-and-main) pour les fonctionnalités ajoutées depuis la dernière version npm.## Études de casdiff --git a/docs/readme/README_id.md b/docs/readme/README_id.mdindex 2fbc3ba71..6f1eba103 100644--- a/docs/readme/README_id.md+++ b/docs/readme/README_id.md@@ -173,7 +173,7 @@ Pemeriksaan JavaScript dan .NET statis membaca berkas yang disediakan tanpa menj<a id="choosing-a-deep-analysis-provider"></a>-Format native dan dukungan sistem host berbeda-beda menurut penyedia. Lihat [penyiapan Hopper dan Ghidra](../installation.md#hopper), [panduan IDA](../ida-provider.md), dan [dukungan eksperimental Ghidra di Windows](../windows-ghidra-p0.md).+Format native dan dukungan sistem host berbeda-beda menurut penyedia. Lihat [penyiapan Hopper dan Ghidra](../installation.md#hopper), [panduan IDA](../ida-provider.md), [Kuna](../kuna-provider.md), dan [dukungan eksperimental Ghidra di Windows](../windows-ghidra-p0.md).Ghidra juga mendukung [analisis DOS 16-bit](../ghidra-dos.md).diff --git a/docs/readme/README_it.md b/docs/readme/README_it.mdindex ae163e83a..551332171 100644--- a/docs/readme/README_it.md+++ b/docs/readme/README_it.md@@ -170,7 +170,7 @@ L'ispezione statica di JavaScript e .NET legge i file forniti senza eseguire l'a<a id="choosing-a-deep-analysis-provider"></a>-I formati nativi e il supporto host variano in base al provider. Vedi la [configurazione di Hopper e Ghidra](../installation.md#hopper), la [guida IDA](../ida-provider.md) e il [supporto sperimentale Windows Ghidra](../windows-ghidra-p0.md). Ghidra supporta anche l'[analisi DOS a 16 bit](../ghidra-dos.md). Per binari di grandi dimensioni, aumenta il timeout di avvio con `REA_GHIDRA_STARTUP_TIMEOUT_MS`. Per la selezione del provider, vedi la [guida CLI](../cli.md#choose-a-provider). Controlla la [disponibilità delle release](../installation.md#released-package-and-main) per le funzionalità aggiunte dall'ultima release npm.+I formati nativi e il supporto host variano in base al provider. Vedi la [configurazione di Hopper e Ghidra](../installation.md#hopper), la [guida IDA](../ida-provider.md), [Kuna](../kuna-provider.md) e il [supporto sperimentale Windows Ghidra](../windows-ghidra-p0.md). Ghidra supporta anche l'[analisi DOS a 16 bit](../ghidra-dos.md). Per binari di grandi dimensioni, aumenta il timeout di avvio con `REA_GHIDRA_STARTUP_TIMEOUT_MS`. Per la selezione del provider, vedi la [guida CLI](../cli.md#choose-a-provider). Controlla la [disponibilità delle release](../installation.md#released-package-and-main) per le funzionalità aggiunte dall'ultima release npm.## Showcasediff --git a/docs/readme/README_ja.md b/docs/readme/README_ja.mdindex 1d2aec01c..53745cadc 100644--- a/docs/readme/README_ja.md+++ b/docs/readme/README_ja.md@@ -166,7 +166,7 @@ REA には Node.js 22.x(>=22.19)、24.x(>=24.11)、または 26+ と npm<a id="choosing-a-deep-analysis-provider"></a>-対応するネイティブ形式とホストは、プロバイダーによって異なります。[Hopper と Ghidra のセットアップ](../installation.md#hopper)、[IDA ガイド](../ida-provider.md)、[Windows 向け Ghidra の実験的対応](../windows-ghidra-p0.md)を参照してください。Ghidra は [16 ビット DOS 分析](../ghidra-dos.md)にも対応しています。プロバイダーの選択は [CLI ガイド](../cli.md#choose-a-provider)を参照してください。最新の npm リリース以降に追加された機能については、[リリースでの利用可否](../installation.md#released-package-and-main)を確認してください。+対応するネイティブ形式とホストは、プロバイダーによって異なります。[Hopper と Ghidra のセットアップ](../installation.md#hopper)、[IDA ガイド](../ida-provider.md)、[Kuna](../kuna-provider.md)、[Windows 向け Ghidra の実験的対応](../windows-ghidra-p0.md)を参照してください。Ghidra は [16 ビット DOS 分析](../ghidra-dos.md)にも対応しています。プロバイダーの選択は [CLI ガイド](../cli.md#choose-a-provider)を参照してください。最新の npm リリース以降に追加された機能については、[リリースでの利用可否](../installation.md#released-package-and-main)を確認してください。## 事例diff --git a/docs/readme/README_ko.md b/docs/readme/README_ko.mdindex c6c499056..1411688c1 100644--- a/docs/readme/README_ko.md+++ b/docs/readme/README_ko.md@@ -175,7 +175,7 @@ REA에는 Node.js 22.x(>=22.19), 24.x(>=24.11) 또는 26+와 npm이 필요합니<a id="choosing-a-deep-analysis-provider"></a>-지원하는 네이티브 형식과 호스트는 제공자마다 다릅니다. [Hopper 및 Ghidra 설정](../installation.md#hopper), [IDA 가이드](../ida-provider.md)(선택 사항인 네이티브 MCP 브리지 포함), [실험적 Windows Ghidra 지원](../windows-ghidra-p0.md)을 참고하세요. Ghidra는 [16비트 DOS 분석](../ghidra-dos.md)도 지원합니다. 큰 바이너리를 분석할 때는 `REA_GHIDRA_STARTUP_TIMEOUT_MS` 또는 `REA_HOPPER_STARTUP_TIMEOUT_MS`로 제공자의 시작 제한 시간을 늘리세요. 제공자 선택은 [CLI 가이드](../cli.md#choose-a-provider)를 참고하세요. 최신 npm 릴리스 이후 추가된 기능은 [릴리스에서의 사용 가능 여부](../installation.md#released-package-and-main)를 확인하세요.+지원하는 네이티브 형식과 호스트는 제공자마다 다릅니다. [Hopper 및 Ghidra 설정](../installation.md#hopper), [IDA 가이드](../ida-provider.md)(선택 사항인 네이티브 MCP 브리지 포함), [Kuna](../kuna-provider.md), [실험적 Windows Ghidra 지원](../windows-ghidra-p0.md)을 참고하세요. Ghidra는 [16비트 DOS 분석](../ghidra-dos.md)도 지원합니다. 큰 바이너리를 분석할 때는 `REA_GHIDRA_STARTUP_TIMEOUT_MS` 또는 `REA_HOPPER_STARTUP_TIMEOUT_MS`로 제공자의 시작 제한 시간을 늘리세요. 제공자 선택은 [CLI 가이드](../cli.md#choose-a-provider)를 참고하세요. 최신 npm 릴리스 이후 추가된 기능은 [릴리스에서의 사용 가능 여부](../installation.md#released-package-and-main)를 확인하세요.## 사례diff --git a/docs/readme/README_pl.md b/docs/readme/README_pl.mdindex bb32355f9..3102f2784 100644--- a/docs/readme/README_pl.md+++ b/docs/readme/README_pl.md@@ -166,7 +166,7 @@ Statyczna analiza JavaScript i .NET odczytuje dostarczone pliki bez uruchamiania<a id="choosing-a-deep-analysis-provider"></a>-Obsługiwane formaty natywne i platformy zależą od dostawcy analizy. Zobacz [konfigurację Hoppera i Ghidry](../installation.md#hopper), [przewodnik IDA](../ida-provider.md) oraz [eksperymentalną obsługę Ghidry w systemie Windows](../windows-ghidra-p0.md). Ghidra obsługuje też [analizę 16-bitowego DOS-a](../ghidra-dos.md). Wybór dostawcy opisuje [przewodnik CLI](../cli.md#choose-a-provider). Sprawdź [dostępność w wydaniach](../installation.md#released-package-and-main) dla funkcji dodanych po najnowszym wydaniu npm.+Obsługiwane formaty natywne i platformy zależą od dostawcy analizy. Zobacz [konfigurację Hoppera i Ghidry](../installation.md#hopper), [przewodnik IDA](../ida-provider.md), [Kuna](../kuna-provider.md) oraz [eksperymentalną obsługę Ghidry w systemie Windows](../windows-ghidra-p0.md). Ghidra obsługuje też [analizę 16-bitowego DOS-a](../ghidra-dos.md). Wybór dostawcy opisuje [przewodnik CLI](../cli.md#choose-a-provider). Sprawdź [dostępność w wydaniach](../installation.md#released-package-and-main) dla funkcji dodanych po najnowszym wydaniu npm.## Przykłady zastosowańdiff --git a/docs/readme/README_pt-BR.md b/docs/readme/README_pt-BR.mdindex 9802205ed..c52429eff 100644--- a/docs/readme/README_pt-BR.md+++ b/docs/readme/README_pt-BR.md@@ -166,7 +166,7 @@ A inspeção estática de JavaScript e .NET lê os arquivos fornecidos sem execu<a id="choosing-a-deep-analysis-provider"></a>-Os formatos nativos e os sistemas anfitriões compatíveis variam por provedor. Consulte [configuração do Hopper e Ghidra](../installation.md#hopper), o [guia do IDA](../ida-provider.md) e o [suporte experimental ao Ghidra no Windows](../windows-ghidra-p0.md). O Ghidra também oferece [análise de DOS de 16 bits](../ghidra-dos.md). Para selecionar um provedor, consulte o [guia da CLI](../cli.md#choose-a-provider). Verifique a [disponibilidade nas versões](../installation.md#released-package-and-main) das funcionalidades adicionadas após a versão mais recente no npm.+Os formatos nativos e os sistemas anfitriões compatíveis variam por provedor. Consulte [configuração do Hopper e Ghidra](../installation.md#hopper), o [guia do IDA](../ida-provider.md), [Kuna](../kuna-provider.md) e o [suporte experimental ao Ghidra no Windows](../windows-ghidra-p0.md). O Ghidra também oferece [análise de DOS de 16 bits](../ghidra-dos.md). Para selecionar um provedor, consulte o [guia da CLI](../cli.md#choose-a-provider). Verifique a [disponibilidade nas versões](../installation.md#released-package-and-main) das funcionalidades adicionadas após a versão mais recente no npm.## Casos de usodiff --git a/docs/readme/README_ru.md b/docs/readme/README_ru.mdindex 502583328..96a6d14d6 100644--- a/docs/readme/README_ru.md+++ b/docs/readme/README_ru.md@@ -166,7 +166,7 @@ REA требует Node.js 22.x (>=22.19), 24.x (>=24.11) или 26+, а так<a id="choosing-a-deep-analysis-provider"></a>-Нативные форматы и поддерживаемые системы различаются у разных провайдеров. См. [настройку Hopper и Ghidra](../installation.md#hopper), [руководство по IDA](../ida-provider.md) и [экспериментальную поддержку Ghidra в Windows](../windows-ghidra-p0.md). Ghidra также поддерживает [анализ 16-битного DOS](../ghidra-dos.md). Выбор провайдера описан в [руководстве по CLI](../cli.md#choose-a-provider). Для функций, добавленных после последней версии в npm, проверьте [доступность в релизах](../installation.md#released-package-and-main).+Нативные форматы и поддерживаемые системы различаются у разных провайдеров. См. [настройку Hopper и Ghidra](../installation.md#hopper), [руководство по IDA](../ida-provider.md), [Kuna](../kuna-provider.md) и [экспериментальную поддержку Ghidra в Windows](../windows-ghidra-p0.md). Ghidra также поддерживает [анализ 16-битного DOS](../ghidra-dos.md). Выбор провайдера описан в [руководстве по CLI](../cli.md#choose-a-provider). Для функций, добавленных после последней версии в npm, проверьте [доступность в релизах](../installation.md#released-package-and-main).## Примерыdiff --git a/docs/readme/README_th.md b/docs/readme/README_th.mdindex 747a4c1ad..4ee882aed 100644--- a/docs/readme/README_th.md+++ b/docs/readme/README_th.md@@ -166,7 +166,7 @@ REA ต้องใช้ Node.js 22.x (>=22.19), 24.x (>=24.11) หรือ 26<a id="choosing-a-deep-analysis-provider"></a>-รูปแบบไบนารีเนทีฟและแพลตฟอร์มที่รองรับแตกต่างกันตามผู้ให้บริการวิเคราะห์ ดู[การตั้งค่า Hopper และ Ghidra](../installation.md#hopper), [คู่มือ IDA](../ida-provider.md) และ[การรองรับ Ghidra บน Windows แบบทดลอง](../windows-ghidra-p0.md) Ghidra ยังรองรับ[การวิเคราะห์ DOS แบบ 16 บิต](../ghidra-dos.md) สำหรับการเลือกผู้ให้บริการ ดู[คู่มือ CLI](../cli.md#choose-a-provider) ตรวจสอบ[ความพร้อมใช้งานในแต่ละรุ่น](../installation.md#released-package-and-main) สำหรับฟีเจอร์ที่เพิ่มหลังรุ่นล่าสุดบน npm+รูปแบบไบนารีเนทีฟและแพลตฟอร์มที่รองรับแตกต่างกันตามผู้ให้บริการวิเคราะห์ ดู[การตั้งค่า Hopper และ Ghidra](../installation.md#hopper), [คู่มือ IDA](../ida-provider.md) [Kuna](../kuna-provider.md) และ[การรองรับ Ghidra บน Windows แบบทดลอง](../windows-ghidra-p0.md) Ghidra ยังรองรับ[การวิเคราะห์ DOS แบบ 16 บิต](../ghidra-dos.md) สำหรับการเลือกผู้ให้บริการ ดู[คู่มือ CLI](../cli.md#choose-a-provider) ตรวจสอบ[ความพร้อมใช้งานในแต่ละรุ่น](../installation.md#released-package-and-main) สำหรับฟีเจอร์ที่เพิ่มหลังรุ่นล่าสุดบน npm## ตัวอย่างการใช้งานdiff --git a/docs/readme/README_tr.md b/docs/readme/README_tr.mdindex 6562b4796..5ba33b34f 100644--- a/docs/readme/README_tr.md+++ b/docs/readme/README_tr.md@@ -171,7 +171,7 @@ Statik JavaScript ve .NET incelemesi, uygulamayı çalıştırmadan sağlanan do<a id="choosing-a-deep-analysis-provider"></a>-Yerel makine kodu içeren ikili dosya biçimleri ve ana bilgisayar desteği sağlayıcıya göre değişir. [Hopper ve Ghidra kurulumu](../installation.md#hopper), isteğe bağlı native MCP bridge'i de açıklayan [IDA rehberi](../ida-provider.md) ve [Windows için deneysel Ghidra desteği](../windows-ghidra-p0.md) belgelerine bakın. Ghidra ayrıca [16 bit DOS analizini](../ghidra-dos.md) destekler. Büyük ikili dosyalar için sağlayıcının başlatma zaman aşımını `REA_GHIDRA_STARTUP_TIMEOUT_MS` veya `REA_HOPPER_STARTUP_TIMEOUT_MS` ile artırın. Sağlayıcı seçimi için [CLI rehberine](../cli.md#choose-a-provider) bakın. En son npm sürümünden sonra eklenen özellikler için [sürümlerde kullanılabilirliği](../installation.md#released-package-and-main) kontrol edin.+Yerel makine kodu içeren ikili dosya biçimleri ve ana bilgisayar desteği sağlayıcıya göre değişir. [Hopper ve Ghidra kurulumu](../installation.md#hopper), isteğe bağlı native MCP bridge'i de açıklayan [IDA rehberi](../ida-provider.md), [Kuna](../kuna-provider.md) ve [Windows için deneysel Ghidra desteği](../windows-ghidra-p0.md) belgelerine bakın. Ghidra ayrıca [16 bit DOS analizini](../ghidra-dos.md) destekler. Büyük ikili dosyalar için sağlayıcının başlatma zaman aşımını `REA_GHIDRA_STARTUP_TIMEOUT_MS` veya `REA_HOPPER_STARTUP_TIMEOUT_MS` ile artırın. Sağlayıcı seçimi için [CLI rehberine](../cli.md#choose-a-provider) bakın. En son npm sürümünden sonra eklenen özellikler için [sürümlerde kullanılabilirliği](../installation.md#released-package-and-main) kontrol edin.## Örnek çalışmalardiff --git a/docs/readme/README_uk.md b/docs/readme/README_uk.mdindex cd28f22d0..232ced41f 100644--- a/docs/readme/README_uk.md+++ b/docs/readme/README_uk.md@@ -166,7 +166,7 @@ REA потребує Node.js 22.x (>=22.19), 24.x (>=24.11) або 26+, а та<a id="choosing-a-deep-analysis-provider"></a>-Нативні формати й підтримка систем відрізняються залежно від провайдера. Дивіться [налаштування Hopper і Ghidra](../installation.md#hopper), [посібник IDA](../ida-provider.md) та [експериментальну підтримку Ghidra у Windows](../windows-ghidra-p0.md). Ghidra також підтримує [аналіз 16-бітного DOS](../ghidra-dos.md). Для вибору провайдера дивіться [посібник CLI](../cli.md#choose-a-provider). Для функцій, доданих після найновішої версії в npm, перевірте [доступність у випусках](../installation.md#released-package-and-main).+Нативні формати й підтримка систем відрізняються залежно від провайдера. Дивіться [налаштування Hopper і Ghidra](../installation.md#hopper), [посібник IDA](../ida-provider.md), [Kuna](../kuna-provider.md) та [експериментальну підтримку Ghidra у Windows](../windows-ghidra-p0.md). Ghidra також підтримує [аналіз 16-бітного DOS](../ghidra-dos.md). Для вибору провайдера дивіться [посібник CLI](../cli.md#choose-a-provider). Для функцій, доданих після найновішої версії в npm, перевірте [доступність у випусках](../installation.md#released-package-and-main).## Прикладиdiff --git a/docs/readme/README_vi.md b/docs/readme/README_vi.mdindex 829d9395a..8cadf6f2f 100644--- a/docs/readme/README_vi.md+++ b/docs/readme/README_vi.md@@ -166,7 +166,7 @@ Kiểm tra tĩnh JavaScript và .NET đọc các tệp được cung cấp mà k<a id="choosing-a-deep-analysis-provider"></a>-Định dạng mã máy và nền tảng chạy REA được hỗ trợ khác nhau tùy trình phân tích. Xem [thiết lập Hopper và Ghidra](../installation.md#hopper), [hướng dẫn IDA](../ida-provider.md) và [hỗ trợ Ghidra thử nghiệm trên Windows](../windows-ghidra-p0.md). Ghidra cũng hỗ trợ [phân tích DOS 16 bit](../ghidra-dos.md). Để chọn trình phân tích, xem [hướng dẫn CLI](../cli.md#choose-a-provider). Kiểm tra [khả năng sử dụng theo bản phát hành](../installation.md#released-package-and-main) đối với tính năng được bổ sung sau phiên bản npm mới nhất.+Định dạng mã máy và nền tảng chạy REA được hỗ trợ khác nhau tùy trình phân tích. Xem [thiết lập Hopper và Ghidra](../installation.md#hopper), [hướng dẫn IDA](../ida-provider.md), [Kuna](../kuna-provider.md) và [hỗ trợ Ghidra thử nghiệm trên Windows](../windows-ghidra-p0.md). Ghidra cũng hỗ trợ [phân tích DOS 16 bit](../ghidra-dos.md). Để chọn trình phân tích, xem [hướng dẫn CLI](../cli.md#choose-a-provider). Kiểm tra [khả năng sử dụng theo bản phát hành](../installation.md#released-package-and-main) đối với tính năng được bổ sung sau phiên bản npm mới nhất.## Các nghiên cứu điển hìnhdiff --git a/docs/readme/README_zh-TW.md b/docs/readme/README_zh-TW.mdindex e18576f56..173e9e078 100644--- a/docs/readme/README_zh-TW.md+++ b/docs/readme/README_zh-TW.md@@ -170,7 +170,7 @@ REA 需要 Node.js 22.x(>=22.19)、24.x(>=24.11)或 26+,以及 npm。<a id="choosing-a-deep-analysis-provider"></a>-不同提供者支援的原生格式和主機系統有所不同。請參閱 [Hopper 與 Ghidra 設定](../installation.md#hopper)、[IDA 指南](../ida-provider.md)和[實驗性 Windows Ghidra 支援](../windows-ghidra-p0.md)。Ghidra 也支援 [16 位 DOS 分析](../ghidra-dos.md)。提供者選擇見 [CLI 指南](../cli.md#choose-a-provider)。對於最新 npm 版本發佈後新增的功能,請查看[發佈可用性](../installation.md#released-package-and-main)。+不同提供者支援的原生格式和主機系統有所不同。請參閱 [Hopper 與 Ghidra 設定](../installation.md#hopper)、[IDA 指南](../ida-provider.md)、[Kuna](../kuna-provider.md)和[實驗性 Windows Ghidra 支援](../windows-ghidra-p0.md)。Ghidra 也支援 [16 位 DOS 分析](../ghidra-dos.md)。提供者選擇見 [CLI 指南](../cli.md#choose-a-provider)。對於最新 npm 版本發佈後新增的功能,請查看[發佈可用性](../installation.md#released-package-and-main)。## 案例diff --git a/docs/readme/README_zh.md b/docs/readme/README_zh.mdindex 06db6238f..bf1257ead 100644--- a/docs/readme/README_zh.md+++ b/docs/readme/README_zh.md@@ -170,7 +170,7 @@ REA 需要 Node.js 22.x(>=22.19)、24.x(>=24.11)或 26+,以及 npm。<a id="choosing-a-deep-analysis-provider"></a>-不同提供方支持的原生格式和主机系统有所不同。请参阅 [Hopper 与 Ghidra 设置](../installation.md#hopper)、[IDA 指南](../ida-provider.md)和[实验性 Windows Ghidra 支持](../windows-ghidra-p0.md)。Ghidra 也支持 [16 位 DOS 分析](../ghidra-dos.md)。提供方选择见 [CLI 指南](../cli.md#choose-a-provider)。对于最新 npm 版本发布后新增的功能,请查看[发布可用性](../installation.md#released-package-and-main)。+不同提供方支持的原生格式和主机系统有所不同。请参阅 [Hopper 与 Ghidra 设置](../installation.md#hopper)、[IDA 指南](../ida-provider.md)、[Kuna](../kuna-provider.md)和[实验性 Windows Ghidra 支持](../windows-ghidra-p0.md)。Ghidra 也支持 [16 位 DOS 分析](../ghidra-dos.md)。提供方选择见 [CLI 指南](../cli.md#choose-a-provider)。对于最新 npm 版本发布后新增的功能,请查看[发布可用性](../installation.md#released-package-and-main)。## 案例diff --git a/docs/testing.md b/docs/testing.mdindex 93a65ffcc..daf5c80b7 100644--- a/docs/testing.md+++ b/docs/testing.md@@ -817,6 +817,34 @@ Native IDA MCP verification uses `"protocol": "native"` with an already-runningThe initial Linux x64 IDA Free 9.4 run used native MCP 1.1.2 with a local navigation correction. Windows x64 verification uses **IDA Pro 9.3**, the two-function public fixture, and the shipped Windows `whoami.exe` application. The native plugin was built from upstream `c9d15d98e8a143fc74f6e14037c48f63889b6d6c`, including the merged navigation fix, with a local loopback-listener change. Production CLI/MCP parity, switching, identity and cleanup passed. Correctness and performance measurements are recorded in the [Windows native verification notes](https://github.com/morluto/rea/blob/main/experiments/analysis-efficiency/ida-native-windows.md). Stock 1.1.2 switching, native macOS, and Windows IDA Free remain unverified. See the [native bridge prerequisites](ida-provider.md#optional-native-ida-mcp-bridge).+## Kuna lane++`npm run verify:kuna` requires a caller-supplied `kuna` in `REA_KUNA_COMMAND`+and a host C compiler (`REA_CC`, default `cc`) with `strip` and `nm`. It builds a+source-owned fixture with symbols and stripped, then verifies through MCP that+the first cold pseudocode answer comes from a single-function run or an export+that already finished, assembly waits for and serves from that export, and+pseudocode and both dossier facets match their recorded file spans and digests,+a fresh server reuses the export without rebuilding it, staging is empty after+a completed export, and no owned process survives. Pass+`--targets DIR --functions a,b` to add caller-built binaries laid out as+`DIR/<flavor>/<name>` beside `<name>.stripped`; addresses come from the+symbol-bearing build. `--compare-ghidra` with `GHIDRA_INSTALL_DIR` runs those+caller-built functions through Ghidra (it refuses to run without `--targets` and+`--functions`, an empty matrix, or names missing from every supplied target) and+reports latency, sampled process-tree CPU and peak memory, UTF-8 response size,+and goto and warning-marker counts. Those counts are not a correctness judgement,+and model tokens are not measured. `--report PATH` writes the JSON report.++The first matrix run used Kuna 1.833 and Ghidra 12.1.4 with JDK 21 on macOS+arm64. It covered zlib 1.3.2 `minigzip`, coreutils 9.9 `sort` and the sqlite+3.54.0 shell, built at `-O2` for ELF x86-64, ELF AArch64, Mach-O arm64 and+Mach-O x86-64, each with symbols and stripped. A separate Linux x86-64 run verified+the fixture and system zlib 1.2.13 / SQLite 3.40.1 libraries through MCP, including+cached byte spans and a Ghidra comparison. See the [Linux report](https://github.com/morluto/rea/pull/3854#issuecomment-6185870391)+for measured scope and limitations. Windows, PE and universal Mach-O remain+unverified by this lane.+## DOS Ghidra analysis`npm run verify:ghidra:dos` requires the supported Ghidra and JDK installationdiff --git a/package.json b/package.jsonindex 305c0bd4f..330d0d91b 100644--- a/package.json+++ b/package.json@@ -194,6 +194,7 @@"verify:ghidra:swift": "npm run build:cached && node scripts/verify-real-ghidra-swift.mjs","verify:ida": "npm run build:cached && node scripts/verify-real-ida.mjs","verify:ghidra:switch": "npm run build:cached && node scripts/verify-real-ghidra-switch.mjs",+ "verify:kuna": "npm run build:cached && node scripts/verify-real-kuna.mjs","verify:ghidra:dos": "npm run build:cached && node scripts/verify-real-ghidra-dos.mjs","verify:ghidra:com": "npm run build:cached && node scripts/verify-real-ghidra-com.mjs","verify:ghidra:raw": "npm run build:cached && node scripts/verify-real-ghidra-raw.mjs",diff --git a/scripts/lib/catalog-builders.mjs b/scripts/lib/catalog-builders.mjsindex 64296b3ce..4e8e10f1b 100644--- a/scripts/lib/catalog-builders.mjs+++ b/scripts/lib/catalog-builders.mjs@@ -218,6 +218,13 @@ export const providerCatalog = (sources) => {identity: sources.idaProvider.IDA_PROVIDER_IDENTITY,contracts: declaredContracts("ida", sources.idaProvider.IDA_OPERATIONS),},+ {+ identity: sources.kunaProvider.KUNA_PROVIDER_IDENTITY,+ contracts: declaredContracts(+ "kuna",+ sources.kunaProvider.KUNA_OPERATIONS,+ ),+ },{identity: sources.nativeProvider.NATIVE_MACOS_PROVIDER_IDENTITY,contracts: sources.nativeContracts.NATIVE_TOOL_CONTRACTS,diff --git a/scripts/lib/catalog-core.mjs b/scripts/lib/catalog-core.mjsindex 2cdfb64d2..afa8bbcb5 100644--- a/scripts/lib/catalog-core.mjs+++ b/scripts/lib/catalog-core.mjs@@ -109,6 +109,7 @@ const SOURCE_PATHS = {hopperProvider: "dist/hopper/HopperProviderCapabilities.js",ghidraProvider: "dist/ghidra/GhidraProviderCapabilities.js",idaProvider: "dist/ida/IdaProviderCapabilities.js",+ kunaProvider: "dist/kuna/KunaProviderCapabilities.js",nativeProvider: "dist/native/NativeMacOSProviderMetadata.js",artifactProviders: "dist/application/InvestigationProviders.js",browserIdentities: "dist/browser/providerIdentities.js",diff --git a/scripts/verify-real-kuna.mjs b/scripts/verify-real-kuna.mjsnew file mode 100644index 000000000..a59b6858d--- /dev/null+++ b/scripts/verify-real-kuna.mjs@@ -0,0 +1,458 @@+#!/usr/bin/env node+// Real Kuna provider lane. Requires a caller-supplied kuna (REA_KUNA_COMMAND)+// and a host C compiler; REA installs neither. The default run builds a+// source-owned fixture, with symbols and stripped, and verifies the public MCP+// workflow: cold single-function pseudocode, the project export, warm reuse+// from a fresh server, and cleanup. `--targets DIR --functions a,b` adds+// caller-built binaries (DIR/<flavor>/<name> plus <name>.stripped).+// `--compare-ghidra` runs the same functions through a bring-your-own Ghidra+// and reports latency, CPU, memory, output size and simple quality signals.+import assert from "node:assert/strict";+import { execFile } from "node:child_process";+import { createHash } from "node:crypto";+import {+ mkdir,+ mkdtemp,+ readFile,+ readdir,+ rm,+ stat,+ writeFile,+} from "node:fs/promises";+import { tmpdir } from "node:os";+import { join, resolve } from "node:path";+import { fileURLToPath } from "node:url";+import { parseArgs, promisify } from "node:util";+import { Client } from "@modelcontextprotocol/client";+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";+import { requireMcpOperationResult } from "./lib/mcp-verifier-results.mjs";+import {+ assertVerifierCleanupComplete,+ completeVerifierRun,+ createVerifierRun,+} from "./lib/verifier-run.mjs";++const exec = promisify(execFile);+const { values } = parseArgs({+ options: {+ targets: { type: "string" },+ functions: { type: "string" },+ "compare-ghidra": { type: "boolean", default: false },+ report: { type: "string" },+ entrypoint: { type: "string" },+ },+});+const entrypoint =+ values.entrypoint === undefined+ ? fileURLToPath(new URL("./rea.mjs", import.meta.url))+ : resolve(values.entrypoint);+const kuna = process.env.REA_KUNA_COMMAND;+assert.ok(+ kuna !== undefined && kuna.startsWith("/"),+ "Kuna lane prerequisite missing: REA_KUNA_COMMAND must name a caller-supplied kuna by absolute path (bring your own)",+);+if (values["compare-ghidra"]) {+ // The comparison runs on caller-built targets only; the fixture has none.+ assert.ok(+ values.targets !== undefined && values.functions !== undefined,+ "--compare-ghidra compares caller-built targets: pass --targets DIR --functions a,b as well",+ );+ assert.ok(+ process.env.GHIDRA_INSTALL_DIR,+ "Ghidra comparison prerequisite missing: GHIDRA_INSTALL_DIR (bring your own Ghidra 12.1.4 and JDK 21)",+ );+}+const kunaVersion = (await exec(kuna, ["--version"])).stdout.trim();+const run = createVerifierRun();+const workspace = await mkdtemp(join(tmpdir(), "rea-kuna-lane-"));+const cacheRoot = join(workspace, "cache");++const FIXTURE_SOURCE = String.raw`+#include <stdio.h>+#include <stdlib.h>+#include <string.h>+unsigned rea_checksum(const unsigned char *p, size_t n) {+ unsigned h = 2166136261u;+ for (size_t i = 0; i < n; i++) h = (h ^ p[i]) * 16777619u;+ return h;+}+int rea_classify(int c) {+ switch (c) {+ case 'a': return 1; case 'e': return 2; case 'i': return 3;+ case 'o': return 4; case 'u': return 5; default: return c > 'z' ? -1 : 0;+ }+}+int main(int argc, char **argv) {+ if (argc < 2) return 2;+ printf("%u %d\n", rea_checksum((const unsigned char *)argv[1], strlen(argv[1])),+ rea_classify(argv[1][0]));+ return 0;+}+`;++/** Resolve function entry addresses from a symbol-bearing build. */+const symbolAddresses = async (binary, names) => {+ const { stdout } = await exec(process.env.REA_NM ?? "nm", [binary]);+ const found = new Map();+ for (const line of stdout.split("\n")) {+ const [address, type, symbol] = line.trim().split(/\s+/u);+ if (symbol === undefined || !/^[tT]$/u.test(type ?? "")) continue;+ const plain = symbol.startsWith("_") ? symbol.slice(1) : symbol;+ for (const name of names)+ if ((symbol === name || plain === name) && !found.has(name))+ found.set(name, `0x${BigInt(`0x${address}`).toString(16)}`);+ }+ return found;+};++/** Sum the resident memory and CPU time of a process and its descendants. */+const sampleTree = async (root) => {+ const { stdout } = await exec("ps", ["-A", "-o", "pid=,ppid=,rss=,time="]);+ const rows = stdout+ .trim()+ .split("\n")+ .map((line) => line.trim().split(/\s+/u))+ .map(([pid, ppid, rss, time]) => ({+ pid: Number(pid),+ ppid: Number(ppid),+ rssKiB: Number(rss),+ cpuSeconds: (time ?? "0:0")+ .split(/[:-]/u)+ .map(Number)+ .reduce((total, part) => total * 60 + part, 0),+ }));+ const members = new Set([root]);+ for (let grew = true; grew;) {+ grew = false;+ for (const row of rows)+ if (!members.has(row.pid) && members.has(row.ppid)) {+ members.add(row.pid);+ grew = true;+ }+ }+ const tree = rows.filter(({ pid }) => members.has(pid));+ return {+ rssKiB: tree.reduce((total, row) => total + row.rssKiB, 0),+ cpu: new Map(tree.map((row) => [row.pid, row.cpuSeconds])),+ };+};++/** One MCP server with a selected provider, sampled while it runs. */+const openServer = async (provider) => {+ const transport = new StdioClientTransport({+ command: process.execPath,+ args: [entrypoint, "--mcp"],+ env: {+ PATH: process.env.PATH ?? "/usr/bin:/bin",+ HOME: process.env.HOME ?? workspace,+ REA_LOG_LEVEL: "silent",+ REA_PROCESS_RUN_ID: run.run_id,+ REA_KUNA_COMMAND: kuna,+ REA_KUNA_CACHE_DIR: cacheRoot,+ ...(process.env.GHIDRA_INSTALL_DIR === undefined+ ? {}+ : { GHIDRA_INSTALL_DIR: process.env.GHIDRA_INSTALL_DIR }),+ ...(process.env.JAVA_HOME === undefined+ ? {}+ : { JAVA_HOME: process.env.JAVA_HOME }),+ },+ stderr: "ignore",+ });+ const client = new Client({ name: "rea-real-kuna", version: "1" });+ await client.connect(transport);+ const pid = transport.pid;+ let peakKiB = 0;+ const cpu = new Map();+ const sample = async () => {+ if (pid === null) return;+ const observed = await sampleTree(pid).catch(() => undefined);+ if (observed === undefined) return;+ peakKiB = Math.max(peakKiB, observed.rssKiB);+ for (const [member, seconds] of observed.cpu)+ cpu.set(member, Math.max(cpu.get(member) ?? 0, seconds));+ };+ const timer = setInterval(() => void sample(), 200);+ const call = async (name, arguments_ = {}) => {+ const started = performance.now();+ const result = await client.callTool(+ { name, arguments: arguments_ },+ { timeout: 3_600_000 },+ );+ const ms = Math.round(performance.now() - started);+ const bytes = Buffer.byteLength(JSON.stringify(result));+ return {+ ms,+ bytes,+ value: requireMcpOperationResult(result, name),+ structured: result.structuredContent,+ };+ };+ const close = async () => {+ await sample();+ clearInterval(timer);+ try {+ await call("close_binary");+ } finally {+ await client.close();+ await transport.close();+ }+ return {+ peak_rss_mib: Math.round(peakKiB / 1024),+ cpu_seconds: [...cpu.values()].reduce((total, value) => total + value, 0),+ };+ };+ try {+ await call("open_binary", {+ path: provider.path,+ provider_id: provider.id,+ });+ } catch (cause) {+ // A rejected target still owns the client, transport and sampler.+ clearInterval(timer);+ await client.close().catch(() => undefined);+ await transport.close().catch(() => undefined);+ throw cause;+ }+ return { call, close };+};++/** Count structuring and diagnostic markers in provider pseudocode. */+const quality = (text) => ({+ bytes: text === null ? 0 : Buffer.byteLength(text),+ gotos: text === null ? 0 : (text.match(/\bgoto\b/gu) ?? []).length,+ warnings:+ text === null ? 0 : (text.match(/WARNING|\/\/ warn:/gu) ?? []).length,+});++/** Verify Kuna on one binary and measure its cold and warm answers. */+const verifyKuna = async (path, functions) => {+ const sha256 = createHash("sha256")+ .update(await readFile(path))+ .digest("hex");+ const cold = await openServer({ path, id: "kuna" });+ const answers = [];+ try {+ const listed = await cold.call("list_procedures");+ for (const [name, address] of functions) {+ assert.ok(+ listed.value.some((entry) => entry.address === address),+ `${name} at ${address} is missing from Kuna's procedure list for ${path}`,+ );+ const pseudocode = await cold.call("procedure_pseudo_code", {+ procedure: address,+ });+ assert.equal(pseudocode.structured.subject.digest.sha256, sha256);+ assert.equal(pseudocode.structured.provider.id, "kuna");+ const source = pseudocode.structured.raw_result?.source?.kind;+ // A fast export can finish before the first request reaches the+ // decompile path; both sources are valid answers. The single-function+ // fallback itself is covered by the provider's boundary tests.+ assert.ok(+ source === "single-function" || source === "project-export",+ `Unexpected pseudocode source ${String(source)}`,+ );+ const assembly = await cold.call("procedure_assembly", {+ procedure: address,+ });+ assert.equal(+ assembly.structured.raw_result.source.kind,+ "project-export",+ );+ assert.match(assembly.value, new RegExp(`: ; ${address}\\n`, "u"));+ const exported = await cold.call("procedure_pseudo_code", {+ procedure: address,+ });+ const recorded = exported.structured.raw_result.source;+ assert.equal(recorded.kind, "project-export");+ const block = (await readFile(join(recorded.directory, recorded.file)))+ .subarray(+ recorded.byte_offset,+ recorded.byte_offset + recorded.byte_length,+ )+ .toString("utf8");+ assert.ok(+ exported.value === null || block.includes(exported.value),+ "Served pseudocode differs from the recorded export span",+ );+ const dossier = await cold.call("analyze_function", {+ procedure: address,+ });+ const combined = dossier.structured.raw_result.source;+ assert.equal(combined.kind, "project-export");+ assert.deepEqual(+ combined.files.map(({ facet }) => facet),+ ["pseudocode", "assembly"],+ );+ for (const file of combined.files) {+ const bytes = await readFile(join(combined.directory, file.file));+ assert.equal(+ createHash("sha256").update(bytes).digest("hex"),+ file.file_sha256,+ );+ const span = bytes+ .subarray(file.byte_offset, file.byte_offset + file.byte_length)+ .toString("utf8");+ const facet = dossier.value[file.facet];+ assert.ok(+ span.includes(Array.isArray(facet) ? facet.join("\n") : facet),+ );+ }+ answers.push({+ name,+ address,+ cold_source: source,+ cold_ms: pseudocode.ms,+ export_wait_ms: assembly.ms,+ warm_same_session_ms: exported.ms,+ response_bytes: exported.bytes,+ dossier_response_bytes: dossier.bytes,+ ...quality(exported.value),+ });+ }+ } finally {+ answers.push({ cold_server: await cold.close() });+ }+ const staging = await readdir(join(cacheRoot, "staging"));+ assert.deepEqual(staging, [], "Kuna staging survived a completed export");+ // A fresh server reuses the export immediately.+ const warm = await openServer({ path, id: "kuna" });+ try {+ for (const answer of answers)+ if (answer.address !== undefined) {+ const reread = await warm.call("procedure_pseudo_code", {+ procedure: answer.address,+ });+ assert.equal(+ reread.structured.raw_result.source.kind,+ "project-export",+ );+ answer.warm_fresh_server_ms = reread.ms;+ }+ } finally {+ answers.push({ warm_server: await warm.close() });+ }+ return answers;+};++/** Measure Ghidra on the same functions through the same public workflow. */+const measureGhidra = async (path, functions) => {+ const server = await openServer({ path, id: "ghidra" });+ const answers = [];+ try {+ for (const [name, address] of functions) {+ const cold = await server.call("procedure_pseudo_code", {+ procedure: address,+ });+ const warm = await server.call("procedure_pseudo_code", {+ procedure: address,+ });+ answers.push({+ name,+ address,+ first_call_ms: cold.ms,+ repeat_ms: warm.ms,+ response_bytes: cold.bytes,+ ...quality(cold.value),+ });+ }+ } finally {+ answers.push({ server: await server.close() });+ }+ return answers;+};++/** Symbol-bearing caller binaries with the requested functions, beside their stripped copies. */+const targetPairs = async (root, names) => {+ const pairs = [];+ for (const flavor of (await readdir(root)).sort()) {+ const directory = join(root, flavor);+ if (!(await stat(directory)).isDirectory()) continue;+ for (const file of (await readdir(directory)).sort()) {+ if (file.endsWith(".stripped")) continue;+ const symbols = await symbolAddresses(join(directory, file), names);+ if (symbols.size > 0) pairs.push({ flavor, directory, file, symbols });+ }+ }+ return pairs;+};++/** Verify Kuna, and optionally measure Ghidra, on one binary of a pair. */+const verifyVariant = async ({ flavor, directory, symbols }, variant) => {+ const path = join(directory, variant);+ const entry = { binary: `${flavor}/${variant}` };+ entry.kuna = await verifyKuna(path, [...symbols]);+ if (values["compare-ghidra"])+ entry.ghidra = await measureGhidra(path, [...symbols]);+ process.stderr.write(`verified ${entry.binary}\n`);+ return entry;+};++const results = [];+try {+ let callerPairs = [];+ if (values.targets !== undefined) {+ const names = (values.functions ?? "").split(",").filter(Boolean);+ assert.ok(names.length > 0, "--targets requires --functions");+ callerPairs = await targetPairs(values.targets, names);+ assert.ok(+ callerPairs.length > 0,+ `No caller-built targets contain the requested functions in ${values.targets}`,+ );+ const found = new Set(+ callerPairs.flatMap(({ symbols }) => [...symbols.keys()]),+ );+ const missing = names.filter((name) => !found.has(name));+ assert.deepEqual(+ missing,+ [],+ "Requested functions were not found in any caller-built target",+ );+ }++ // Source-owned fixture: always built and verified.+ const fixtureDir = join(workspace, "fixture");+ await mkdir(fixtureDir);+ const source = join(fixtureDir, "fixture.c");+ await writeFile(source, FIXTURE_SOURCE);+ const built = join(fixtureDir, "rea-kuna-fixture");+ await exec(process.env.REA_CC ?? "cc", ["-O2", "-o", built, source]);+ const stripped = `${built}.stripped`;+ await writeFile(stripped, await readFile(built));+ await exec(process.env.REA_STRIP ?? "strip", [stripped]);+ const fixtureFunctions = await symbolAddresses(built, [+ "rea_checksum",+ "rea_classify",+ ]);+ assert.equal(fixtureFunctions.size, 2, "Fixture symbols were not found");+ for (const binary of [built, stripped])+ results.push({+ binary: binary.slice(workspace.length + 1),+ kuna: await verifyKuna(binary, [...fixtureFunctions]),+ });++ // Caller-built matrix.+ for (const pair of callerPairs)+ for (const variant of [pair.file, `${pair.file}.stripped`])+ results.push(await verifyVariant(pair, variant));+} finally {+ await rm(workspace, { recursive: true, force: true });+}+const lifecycle = await completeVerifierRun(run);+assertVerifierCleanupComplete(lifecycle.process_lineage);+const report = {+ lane: "kuna",+ kuna_version: kunaVersion,+ platform: `${process.platform}/${process.arch}`,+ verifier_run: lifecycle,+ results,+ limitations: [+ "Targets are analyzed statically; they are never executed.",+ "Memory is the sampled peak resident set of the MCP server process tree; CPU is its sampled cumulative time. A short-lived peak between 200 ms samples is not observed.",+ "Quality signals count gotos and warning markers only; they are not a correctness judgement and not a DecBench reproduction.",+ "Response bytes are UTF-8 serialization sizes. Model token usage, tool schema costs and agent task completion were not measured.",+ ],+ cleanup: "complete",+};+if (values.report !== undefined)+ await writeFile(values.report, `${JSON.stringify(report, null, 2)}\n`);+process.stdout.write(`${JSON.stringify(report)}\n`);diff --git a/src/composition/binary.ts b/src/composition/binary.tsindex 0cb438cb3..2986d9343 100644--- a/src/composition/binary.ts+++ b/src/composition/binary.ts@@ -4,6 +4,7 @@ import type { BinarySession } from "../application/binary/BinarySession.js";import { HopperProvider } from "../hopper/HopperProvider.js";import { GhidraProvider } from "../ghidra/GhidraProvider.js";import { IdaProvider } from "../ida/IdaProvider.js";+import { KunaProvider } from "../kuna/KunaProvider.js";import type { Logger } from "pino";import { auxiliaryAnalysisProviderDeclarations } from "./auxiliaryAnalysisProviders.js";import { AnalysisProviderRegistry } from "../application/binary/AnalysisProviderRegistry.js";@@ -25,9 +26,10 @@ export const createBinarySession = (const hopper = new HopperProvider(config, logger, environment);const ghidra = new GhidraProvider(config, logger, environment);const ida = new IdaProvider(config, environment);+ const kuna = new KunaProvider(environment);return composeBinarySession(new AnalysisProviderRegistry(- [hopper, ghidra, ida],+ [hopper, ghidra, ida, kuna],config.analysisProvider,),auxiliaryAnalysisProviderDeclarations(environment).map(diff --git a/src/domain/analysisSearch.ts b/src/domain/analysisSearch.tsnew file mode 100644index 000000000..4dd2d9193--- /dev/null+++ b/src/domain/analysisSearch.ts@@ -0,0 +1,33 @@+import { z } from "zod";++import { analysisSearchInput } from "../contracts/analysisSearchContract.js";+import { AnalysisInputError } from "./analysisErrorCore.js";++/** Parsed `search_procedures`/`search_strings` query shared by providers that match in REA. */+export const analysisSearchQuerySchema = z.object(analysisSearchInput);++export type AnalysisSearchQuery = z.infer<typeof analysisSearchQuerySchema>;++/**+ * Match names the way the search contract describes: a literal substring by+ * default, or a Unicode regular expression, case-insensitive unless requested.+ * An invalid pattern is the caller's input error.+ */+export const analysisSearchPredicate = (+ query: AnalysisSearchQuery,+): ((value: string) => boolean) => {+ if (query.mode === "regex") {+ let regex: RegExp;+ try {+ regex = new RegExp(query.pattern, query.case_sensitive ? "u" : "iu");+ } catch (cause: unknown) {+ throw new AnalysisInputError("search", { cause });+ }+ return (value) => regex.test(value);+ }+ const needle = query.case_sensitive+ ? query.pattern+ : query.pattern.toLowerCase();+ return (value) =>+ (query.case_sensitive ? value : value.toLowerCase()).includes(needle);+};diff --git a/src/hopper/HopperProviderCapabilities.ts b/src/hopper/HopperProviderCapabilities.tsindex 2dbac4659..ac514adfd 100644--- a/src/hopper/HopperProviderCapabilities.ts+++ b/src/hopper/HopperProviderCapabilities.ts@@ -1,3 +1,4 @@+import { REGEX_MATCHING_LIMITATION } from "../process/RegexMatcher.js";import type {CapabilityDescriptor,ProviderIdentity,@@ -90,7 +91,7 @@ export const CAPABILITIES: readonly CapabilityDescriptor[] = Object.freeze(: []),...(operation === "search_strings" || operation === "search_procedures"? [- "Regex mode uses ECMAScript Unicode semantics in a supervised worker with a five-second matching deadline. Cancellation or deadline failure stops matching without blocking Hopper; literal mode retains native casefold semantics.",+ `${REGEX_MATCHING_LIMITATION} Literal mode retains native casefold semantics.`,]: []),...(operation === "list_strings" ||diff --git a/src/hopper/HopperRegexSearch.ts b/src/hopper/HopperRegexSearch.tsindex c1a0db109..39ddd0e24 100644--- a/src/hopper/HopperRegexSearch.ts+++ b/src/hopper/HopperRegexSearch.ts@@ -1,4 +1,3 @@-import { Worker } from "node:worker_threads";import { z } from "zod";import type { ExecutionOptions } from "../application/AnalysisProvider.js";@@ -6,7 +5,6 @@ import type { AnalysisError } from "../domain/analysisErrorBase.js";import {AnalysisCancelledError,AnalysisOutputError,- AnalysisResourceConstraintError,} from "../domain/analysisErrorCore.js";import { analysisStringSchema } from "../domain/hopperValues.js";import { HopperRemoteError } from "../domain/hopperErrors.js";@@ -14,20 +12,12 @@ import type { JsonValue } from "../domain/jsonValue.js";import { err, ok, type Result } from "../domain/result.js";import { analysisSearchInput } from "../contracts/analysisSearchContract.js";import type { HopperClient } from "./HopperClient.js";+import { matchRegexValues } from "../process/RegexMatcher.js";-const MATCHING_DEADLINE_MS = 5_000;const inputSchema = z.strictObject({...analysisSearchInput,mode: z.literal("regex"),});-const replySchema = z.discriminatedUnion("status", [- z.strictObject({- status: z.literal("matched"),- indices: z.array(z.number().int().nonnegative()),- }),- z.strictObject({ status: z.literal("invalid_pattern"), reason: z.string() }),-]);-/** Match collected native facts off Hopper's API thread, with cancellable lifetime. */export class HopperRegexSearch {readonly #active = new Map<@@ -35,7 +25,7 @@ export class HopperRegexSearch {Promise<Result<JsonValue, AnalysisError>>>();- constructor(private readonly client: HopperClient) {}+ constructor(private readonly client: Pick<HopperClient, "callTool">) {}execute(operation: "search_strings" | "search_procedures",@@ -125,117 +115,20 @@ export class HopperRegexSearch {.catch(() => undefined);if (options.signal?.aborted)return err(new AnalysisCancelledError(operation));- let worker: Worker;- try {- worker = new Worker(new URL("./HopperRegexWorker.js", import.meta.url), {- workerData: {- pattern: input.data.pattern,- caseSensitive: input.data.case_sensitive,- values: parsed.data.map((item) => item.value),- },- });- } catch (cause: unknown) {- return err(- new AnalysisOutputError(+ const matched = await matchRegexValues({+ operation,+ pattern: input.data.pattern,+ caseSensitive: input.data.case_sensitive,+ values: parsed.data.map((item) => item.value),+ signal: options.signal,+ invalidPattern: (reason) =>+ new HopperRemoteError(-32000, `Invalid regex pattern: ${reason}`, {+ diagnosticType: "invalid_request",operation,- `Cannot start regex worker: ${cause instanceof Error ? cause.message : String(cause)}`,- { cause },- ),- );- }- try {- return await new Promise<Result<JsonValue, AnalysisError>>((resolve) => {- const finish = (result: Result<JsonValue, AnalysisError>): void => {- clearTimeout(timer);- options.signal?.removeEventListener("abort", onAbort);- resolve(result);- };- const onAbort = (): void =>- finish(err(new AnalysisCancelledError(operation)));- const timer = setTimeout(- () =>- finish(- err(- new AnalysisResourceConstraintError(- operation,- "cpu",- "Regex matching exceeded its supervised deadline; the Hopper API thread remains available.",- { matching_deadline_ms: MATCHING_DEADLINE_MS },- {- remediationAction:- "Simplify the ECMAScript Unicode regex or use literal mode, then retry in the same session.",- },- ),- ),- ),- MATCHING_DEADLINE_MS,- );- options.signal?.addEventListener("abort", onAbort, { once: true });- if (options.signal?.aborted) onAbort();- worker.once("message", (message: unknown) => {- const reply = replySchema.safeParse(message);- if (!reply.success)- return finish(- err(- new AnalysisOutputError(- operation,- "Regex worker reply is malformed",- ),- ),- );- if (reply.data.status === "invalid_pattern")- return finish(- err(- new HopperRemoteError(- -32000,- `Invalid regex pattern: ${reply.data.reason}`,- { diagnosticType: "invalid_request", operation },- ),- ),- );- const indices = reply.data.indices;- if (- indices.some(- (index, position) =>- index >= parsed.data.length ||- (position > 0 && index <= (indices[position - 1] ?? -1)),- )- )- return finish(- err(- new AnalysisOutputError(- operation,- "Regex worker returned invalid inventory indices",- ),- ),- );- const selected = new Set(indices);- finish(ok(parsed.data.filter((_, index) => selected.has(index))));- });- worker.once("error", (cause: Error) =>- finish(- err(- new AnalysisOutputError(- operation,- `Regex worker failed: ${cause.message}`,- { cause },- ),- ),- ),- );- worker.once("exit", (code) =>- finish(- err(- new AnalysisOutputError(- operation,- `Regex worker exited without a result (${code})`,- ),- ),- ),- );- });- } finally {- await worker.terminate();- }+ }),+ });+ if (!matched.ok) return matched;+ const selected = new Set(matched.value);+ return ok(parsed.data.filter((_, index) => selected.has(index)));}}diff --git a/src/hopper/HopperRegexWorker.ts b/src/hopper/HopperRegexWorker.tsdeleted file mode 100644index 71fd79b50..000000000--- a/src/hopper/HopperRegexWorker.ts+++ /dev/null@@ -1,27 +0,0 @@-import { parentPort, workerData } from "node:worker_threads";-import { z } from "zod";--const input = z- .strictObject({- pattern: z.string().min(1),- caseSensitive: z.boolean(),- values: z.array(z.string()),- })- .parse(workerData);--let expression: RegExp | undefined;-try {- expression = new RegExp(input.pattern, input.caseSensitive ? "u" : "iu");-} catch (cause: unknown) {- parentPort?.postMessage({- status: "invalid_pattern",- reason: cause instanceof Error ? cause.message : String(cause),- });-}-if (expression !== undefined) {- const indices = [];- for (const [index, value] of input.values.entries()) {- if (expression.test(value)) indices.push(index);- }- parentPort?.postMessage({ status: "matched", indices });-}diff --git a/src/ida/IdaOperationRunner.ts b/src/ida/IdaOperationRunner.tsindex 252bdbe3a..f7cf5ae2b 100644--- a/src/ida/IdaOperationRunner.ts+++ b/src/ida/IdaOperationRunner.ts@@ -7,7 +7,10 @@ import {nativeLiteralSearchPattern,nativeStringsSchema,} from "./IdaNativeProtocol.js";-import { analysisSearchInput } from "../contracts/analysisSearchContract.js";+import {+ analysisSearchPredicate,+ analysisSearchQuerySchema,+} from "../domain/analysisSearch.js";import {AnalysisInputError,AnalysisCancelledError,@@ -82,7 +85,6 @@ const MISSING_PROCEDURE_ANSWERS: ReadonlySet<string> = new Set([]);const lines = (asm: IdaDisassembly) =>asm.lines.map(({ address, instruction }) => `${address}: ${instruction}`);-const searchQuerySchema = z.object(analysisSearchInput);/** Translate explicit analyst questions into a closed set of read-only upstream requests. */export class IdaOperationRunner {@@ -581,10 +583,10 @@ export class IdaOperationRunner {): Promise<JsonValue> {const query =operation === "search_procedures" || operation === "search_strings"- ? searchQuerySchema.parse(parameters)+ ? analysisSearchQuerySchema.parse(parameters): undefined;const matches =- query === undefined ? undefined : this.searchPredicate(query);+ query === undefined ? undefined : analysisSearchPredicate(query);if (operation === "list_procedures" || operation === "search_procedures") {const items = (await this.functions()).map((fn) => ({address: fn.address,@@ -660,30 +662,6 @@ export class IdaOperationRunner {}}- private searchPredicate(- query: z.infer<typeof searchQuerySchema>,- ): (value: string) => boolean {- let matches: (value: string) => boolean;- if (query.mode === "regex") {- try {- const regex = new RegExp(- query.pattern,- query.case_sensitive ? "u" : "iu",- );- matches = (value) => regex.test(value);- } catch (cause: unknown) {- throw new AnalysisInputError("search", { cause });- }- } else {- const needle = query.case_sensitive- ? query.pattern- : query.pattern.toLowerCase();- matches = (value) =>- (query.case_sensitive ? value : value.toLowerCase()).includes(needle);- }- return matches;- }-private async dossier(fn: IdaFunction): Promise<JsonValue> {const asm = await this.assembly(fn);const pseudocode = await this.pseudocode(fn);diff --git a/src/kuna/KunaCommand.ts b/src/kuna/KunaCommand.tsnew file mode 100644index 000000000..c8e4b7e76--- /dev/null+++ b/src/kuna/KunaCommand.ts@@ -0,0 +1,267 @@+import { createHash, randomUUID } from "node:crypto";+import { createReadStream, createWriteStream } from "node:fs";+import { stat } from "node:fs/promises";+import { Transform } from "node:stream";+import { pipeline } from "node:stream/promises";++import type { AnalysisError } from "../domain/analysisErrorBase.js";+import {+ AnalysisCancelledError,+ AnalysisResourceConstraintError,+ AnalysisTimeoutError,+} from "../domain/analysisErrorCore.js";+import { ProviderAdapterError } from "../domain/providerAdapterError.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import {+ OwnedCommandFailure,+ runOwnedCommand,+} from "../process/OwnedCommand.js";+import { hashStableFile } from "../filesystem/StableFileHash.js";+import type {+ OwnedProviderProcessSpawnOptions,+ ProviderProcessSnapshot,+ ProviderProcessSupervisor,+ SpawnedOwnedProviderProcess,+} from "../process/ProviderProcess.js";+import {+ kunaChildEnvironment,+ type KunaInstallation,+} from "./KunaInstallation.js";+import { KUNA_PROVIDER_ID } from "./KunaRelease.js";++/**+ * `kuna functions --json` costs ~210 bytes per function; this admits about+ * 600,000 functions, above the 392,814 of the largest image Kuna documents.+ */+export const KUNA_INVENTORY_OUTPUT_BYTES = 128 * 1024 * 1024;++/** Test seam for the owned process launcher; production uses the default. */+export type KunaProcessLauncher = (+ options: OwnedProviderProcessSpawnOptions,+) => Promise<SpawnedOwnedProviderProcess>;++/** One bounded Kuna run inside a private workspace. */+export interface KunaCommandRequest {+ readonly installation: KunaInstallation;+ readonly arguments: readonly string[];+ /** Private directory used as the working and temporary directory. */+ readonly workspace: string;+ /** Operation named by every failure this run reports. */+ readonly operation: string;+ readonly timeoutMs: number;+ /** The deadline callers configured, reported when the run times out. */+ readonly reportedTimeoutMs: number;+ readonly outputBytes: number;+ readonly signal: AbortSignal;+ readonly launcher?: KunaProcessLauncher | undefined;+}++/**+ * How a Kuna run ended. `retained` means the process tree could not be proven+ * stopped, so it may still write into the workspace, which therefore stays+ * with the caller's cleanup owner.+ */+export type KunaCommandOutcome =+ | { readonly kind: "ok"; readonly snapshot: ProviderProcessSnapshot }+ | { readonly kind: "failed"; readonly error: AnalysisError }+ | {+ readonly kind: "retained";+ readonly error: ProviderCleanupError;+ /** The supervisor that can retry stopping the process tree, when one exists. */+ readonly owner: ProviderProcessSupervisor | undefined;+ };++const message = (cause: unknown): string =>+ cause instanceof Error ? cause.message : String(cause);++/** File metadata that, unchanged, lets a verified digest stand without re-hashing. */+const verifiedExecutables = new Map<+ string,+ { readonly identity: string; readonly sha256: string }+>();++/**+ * Confirm the executable still has the digest its analysis profile committed,+ * so no answer names one Kuna build while another produced it.+ */+const verifyExecutable = async (+ installation: KunaInstallation,+ signal: AbortSignal,+): Promise<string | undefined> => {+ const status = await stat(installation.executable, { bigint: true });+ const identity = [+ status.dev,+ status.ino,+ status.size,+ status.mtimeNs,+ status.ctimeNs,+ ].join(":");+ const known = verifiedExecutables.get(installation.executable);+ let sha256 = known?.identity === identity ? known.sha256 : undefined;+ if (sha256 === undefined) {+ sha256 = (await hashStableFile(installation.executable, signal)).sha256;+ verifiedExecutables.set(installation.executable, { identity, sha256 });+ }+ return sha256 === installation.sha256 ? undefined : sha256;+};++/** Run Kuna under an owned process group with REA's environment and limits. */+export const runKunaCommand = async (+ request: KunaCommandRequest,+): Promise<KunaCommandOutcome> => {+ const { installation } = request;+ try {+ const changed = await verifyExecutable(installation, request.signal);+ if (changed !== undefined)+ return {+ kind: "failed",+ error: new ProviderAdapterError(KUNA_PROVIDER_ID, request.operation, {+ userMessage: `${installation.executable} changed after this target was opened; reopen the target so REA probes the current Kuna executable.`,+ diagnostics: {+ expected_sha256: installation.sha256,+ observed_sha256: changed,+ },+ }),+ };+ } catch (cause: unknown) {+ return {+ kind: "failed",+ error: request.signal.aborted+ ? new AnalysisCancelledError(request.operation, { cause })+ : new ProviderAdapterError(KUNA_PROVIDER_ID, request.operation, {+ cause,+ userMessage: `Cannot verify ${installation.executable}: ${message(cause)}`,+ }),+ };+ }+ try {+ const snapshot = await runOwnedCommand(+ {+ command: installation.executable,+ arguments: request.arguments,+ runId: `rea-kuna-${randomUUID()}`,+ // A script's process reports its interpreter, not the configured path.+ ...(installation.script ? { expectedCommand: null } : {}),+ cwd: request.workspace,+ hostEnvironment: kunaChildEnvironment(installation.configuration),+ env: { TMPDIR: request.workspace },+ },+ {+ timeoutMs: Math.max(1, request.timeoutMs),+ diagnosticBytes: request.outputBytes,+ },+ {+ signal: request.signal,+ ...(request.launcher === undefined+ ? {}+ : { launcher: request.launcher }),+ },+ );+ return { kind: "ok", snapshot };+ } catch (cause: unknown) {+ return commandFailure(cause, request);+ }+};++/** Copy a file and return the SHA-256 of exactly the bytes copied. */+export const copyAndHash = async (+ source: string,+ destination: string,+ signal: AbortSignal,+): Promise<string> => {+ const hash = createHash("sha256");+ await pipeline(+ createReadStream(source),+ new Transform({+ transform(chunk: Buffer, _encoding, callback) {+ hash.update(chunk);+ callback(null, chunk);+ },+ }),+ createWriteStream(destination, { flags: "wx", mode: 0o600 }),+ { signal },+ );+ return hash.digest("hex");+};++/** Map an owned-command failure to its typed error, keeping unproven cleanup owned. */+const commandFailure = (+ cause: unknown,+ request: KunaCommandRequest,+): KunaCommandOutcome => {+ const { operation } = request;+ const subcommand = request.arguments[0] ?? "";+ if (!(cause instanceof OwnedCommandFailure))+ return {+ kind: "failed",+ error: request.signal.aborted+ ? new AnalysisCancelledError(operation, { cause })+ : new ProviderAdapterError(KUNA_PROVIDER_ID, operation, {+ cause,+ userMessage: `Cannot run ${request.installation.executable}: ${message(cause)}`,+ }),+ };+ const snapshot = cause.snapshot;+ const capturedOutput =+ snapshot === null+ ? undefined+ : {+ // Output can be evidence-sized, not diagnostic-sized; keep only its tail.+ stdout: snapshot.stdout.text.slice(-4096),+ stderr: snapshot.stderr.text,+ truncated:+ snapshot.diagnosticTruncated === true ||+ snapshot.outputIncomplete === true ||+ snapshot.stdout.text.length > 4096,+ exit_code: snapshot.exitCode ?? null,+ signal: snapshot.signal ?? null,+ };+ const details = {+ cause,+ ...(capturedOutput === undefined ? {} : { capturedOutput }),+ };+ if (cause.cleanupFailure !== null)+ return {+ kind: "retained",+ error: new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ [...cause.resources, request.workspace],+ { reason: cause.cleanupFailure },+ { operation, cause },+ ),+ owner: cause.cleanupOwner,+ };+ if (cause.reason === "cancelled")+ return {+ kind: "failed",+ error: new AnalysisCancelledError(operation, details),+ };+ if (cause.reason === "timeout")+ return {+ kind: "failed",+ error: new AnalysisTimeoutError(+ operation,+ request.reportedTimeoutMs,+ details,+ ),+ };+ if (cause.reason === "output-limit")+ return {+ kind: "failed",+ error: new AnalysisResourceConstraintError(+ operation,+ "capacity",+ `kuna ${subcommand} wrote more than ${String(request.outputBytes)} bytes of output.`,+ { output_limit_bytes: request.outputBytes },+ details,+ ),+ };+ const exitCode = capturedOutput?.exit_code;+ return {+ kind: "failed",+ error: new ProviderAdapterError(KUNA_PROVIDER_ID, operation, {+ ...details,+ userMessage: `kuna ${subcommand} failed${exitCode === undefined || exitCode === null ? "" : ` with exit code ${String(exitCode)}`}: ${capturedOutput?.stderr.trim().split("\n").at(-1) ?? cause.message}`,+ }),+ };+};diff --git a/src/kuna/KunaConfiguration.ts b/src/kuna/KunaConfiguration.tsindex 48fe41864..7de37b635 100644--- a/src/kuna/KunaConfiguration.ts+++ b/src/kuna/KunaConfiguration.ts@@ -18,6 +18,9 @@ const MAX_KUNA_JOBS = 32;*/const DEFAULT_PROJECT_TIMEOUT_MS = 30 * 60 * 1000;+/** One function decompiles in well under a second; sqlite3VdbeExec (42 KB) took 15-25 s. */+const DEFAULT_FUNCTION_TIMEOUT_MS = 120_000;+/*** A serial (`--jobs 1`) export is Kuna's reference answer: it decompiles* callees before callers, which recovers prototypes that parallel workers@@ -39,6 +42,8 @@ export interface KunaConfiguration {readonly cacheRoot: string;readonly cacheMaxBytes: number;readonly projectTimeoutMs: number;+ /** Deadline for one single-function `kuna decompile` run. */+ readonly functionTimeoutMs: number;readonly jobs: number;}@@ -125,6 +130,18 @@ export const readKunaConfiguration = ("REA_KUNA_PROJECT_TIMEOUT_MS",);+ const rawFunctionTimeout = environment.REA_KUNA_TIMEOUT_MS;+ const functionTimeout =+ rawFunctionTimeout === undefined+ ? undefined+ : providerStartupTimeoutSchema.safeParse(rawFunctionTimeout);+ if (functionTimeout !== undefined && !functionTimeout.success)+ return failure(+ "open_options_invalid",+ `REA_KUNA_TIMEOUT_MS must be a decimal millisecond count from 1 to 2147483647; received ${String(rawFunctionTimeout)}.`,+ "REA_KUNA_TIMEOUT_MS",+ );+const rawJobs = environment.REA_KUNA_JOBS;const jobs = rawJobs === undefined ? DEFAULT_JOBS : positiveInteger(rawJobs);if (jobs === undefined || jobs > MAX_KUNA_JOBS)@@ -139,6 +156,7 @@ export const readKunaConfiguration = (cacheRoot: cacheRoot ?? defaultCacheRoot(environment, platform),cacheMaxBytes,projectTimeoutMs: timeout?.data ?? DEFAULT_PROJECT_TIMEOUT_MS,+ functionTimeoutMs: functionTimeout?.data ?? DEFAULT_FUNCTION_TIMEOUT_MS,jobs,});};diff --git a/src/kuna/KunaDoctor.ts b/src/kuna/KunaDoctor.tsindex 4c3488dfb..e8166b216 100644--- a/src/kuna/KunaDoctor.ts+++ b/src/kuna/KunaDoctor.ts@@ -25,6 +25,7 @@ const REGISTRATION_SETTINGS = ["REA_KUNA_CACHE_DIR","REA_KUNA_CACHE_MAX_BYTES","REA_KUNA_PROJECT_TIMEOUT_MS",+ "REA_KUNA_TIMEOUT_MS","REA_KUNA_JOBS",] as const;diff --git a/src/kuna/KunaLimits.ts b/src/kuna/KunaLimits.tsnew file mode 100644index 000000000..ae2ceb48c--- /dev/null+++ b/src/kuna/KunaLimits.ts@@ -0,0 +1,2 @@+/** Shared buffered-text capacity for a subprocess answer or one cached source facet. */+export const KUNA_FUNCTION_TEXT_BYTES = 16 * 1024 * 1024;diff --git a/src/kuna/KunaProjectCache.ts b/src/kuna/KunaProjectCache.tsindex 9bdcb406f..29a0f1e95 100644--- a/src/kuna/KunaProjectCache.ts+++ b/src/kuna/KunaProjectCache.ts@@ -31,8 +31,9 @@ import {readKunaExport,type KunaExport,type KunaExportStatus,- type KunaProcessLauncher,} from "./KunaProjectExport.js";+import type { ProviderProcessSupervisor } from "../process/ProviderProcess.js";+import type { KunaProcessLauncher } from "./KunaCommand.js";import type {KunaInventoryFunction,KunaProjectFunction,@@ -129,6 +130,15 @@ export interface KunaProjectRequest {readonly onStatus?: (status: KunaExportStatus) => void;}+/** One build whose process tree REA could not prove stopped. */+interface RetainedProcess {+ readonly key: string;+ readonly error: ProviderCleanupError;+ /** Retries stopping the process tree, when the launcher left one. */+ readonly owner: ProviderProcessSupervisor | undefined;+ readonly staging: string;+}+interface StagedResult {readonly result: Result<KunaProject, AnalysisError>;/** Set when an owned process may still write into staging. */@@ -205,9 +215,13 @@ export class KunaProjectCache {#capacity: "within_limit" | "pinned" | "building" = "within_limit";#maintenance: Promise<void> | undefined;#maintenanceRequested = false;- readonly #retainedProcesses: ProviderCleanupError[] = [];+ /** Builds whose process tree could not be proven stopped; their staging stays. */+ readonly #retainedProcesses: RetainedProcess[] = [];/** Only resources whose process cleanup is proven may be retried as files. */- readonly #retainedFiles = new Map<string, ProviderCleanupError>();+ readonly #retainedFiles = new Map<+ string,+ { readonly key: string | null; readonly error: ProviderCleanupError }+ >();constructor(root: string,@@ -341,33 +355,81 @@ export class KunaProjectCache {return this.#await(created, request);}+ /**+ * Wait until a build that every waiter abandoned has stopped its Kuna+ * process and removed its staging. A build another request still waits for+ * keeps running and is not awaited.+ */+ async settled(key: string): Promise<Result<null, ProviderCleanupError>> {+ await Promise.allSettled(+ [...this.#unfinished]+ .filter((entry) => entry.key === key && entry.controller.signal.aborted)+ .map((entry) => entry.promise),+ );+ await this.#retryProcesses((retained) => retained.key === key);+ await this.#retryFiles(key);+ return cleanupResult(+ [...this.#retainedProcesses, ...this.#retainedFiles.values()]+ .filter((retained) => retained.key === key)+ .map(({ error }) => error),+ );+ }+/** Wait for builds, retry safe file removal, and report unresolved cleanup. */async close(): Promise<Result<null, ProviderCleanupError>> {await Promise.allSettled([...this.#unfinished].map((entry) => entry.promise),);while (this.#maintenance !== undefined) await this.#maintenance;- for (const path of [...this.#retainedFiles.keys()])- await this.#removeRetired(path).catch(() => undefined);- const retained = [- ...this.#retainedProcesses,- ...this.#retainedFiles.values(),- ];- if (retained.length === 0) return ok(null);- return err(- new ProviderCleanupError(- KUNA_PROVIDER_ID,- retained.flatMap((entry) => entry.cleanupResources),- {- reason: retained- .map((entry) =>- String(entry.diagnostics?.["reason"] ?? entry.message),- )- .join("; "),- },- { operation: KUNA_EXPORT_OPERATION },- ),- );+ await this.#retryProcesses(() => true);+ await this.#retryFiles();+ return cleanupResult([+ ...this.#retainedProcesses.map(({ error }) => error),+ ...[...this.#retainedFiles.values()].map(({ error }) => error),+ ]);+ }++ /** Retry stopping retained process trees; retire the staging of each one proven stopped. */+ async #retryProcesses(+ selected: (retained: RetainedProcess) => boolean,+ ): Promise<void> {+ for (const retained of this.#retainedProcesses.filter(selected)) {+ const stopped = await retained.owner?.stop();+ if (stopped === undefined || stopped.status === "incomplete") continue;+ this.#retainedProcesses.splice(+ this.#retainedProcesses.indexOf(retained),+ 1,+ );+ await this.#retireStaging(retained.staging, retained.key);+ }+ }++ /** Retry only stopped file resources belonging to the closing task, or all. */+ async #retryFiles(key?: string): Promise<void> {+ for (const [path, retained] of [...this.#retainedFiles])+ if (key === undefined || retained.key === key)+ await this.#removeRetired(path).catch(() => undefined);+ }++ /**+ * Move proven-stopped staging into trash and remove it. A failed removal+ * stays owned as a file cleanup that close retries.+ */+ async #retireStaging(+ staging: string,+ key: string,+ ): Promise<ProviderCleanupError | undefined> {+ let cleanupPath = staging;+ try {+ const retired = join(this.#root, "trash", `build-${randomUUID()}`);+ await rename(staging, retired);+ cleanupPath = retired;+ await this.#removeRetired(retired, key);+ return undefined;+ } catch (cause: unknown) {+ if (cause instanceof ProviderCleanupError) return cause;+ return this.#retainFileCleanup(cleanupPath, cause, key);+ }}#await(@@ -437,18 +499,10 @@ export class KunaProjectCache {retainStaging: false,}));if (built.retainStaging) return built.result;- let cleanupPath = staging;- try {- // Only a proven-stopped build may enter trash. A failed write, crash or- // lost cleanup identity therefore never makes live staging reclaimable.- const retired = join(this.#root, "trash", `build-${randomUUID()}`);- await rename(staging, retired);- cleanupPath = retired;- await this.#removeRetired(retired);- } catch (cause: unknown) {- if (cause instanceof ProviderCleanupError) return err(cause);- return err(this.#retainFileCleanup(cleanupPath, cause));- }+ // Only a proven-stopped build may enter trash. A failed write, crash or+ // lost cleanup identity therefore never makes live staging reclaimable.+ const retired = await this.#retireStaging(staging, key);+ if (retired !== undefined) return err(retired);if (built.result.ok)// The entry is published either way; a failed eviction retries on the next publish.await this.#evict(key).catch(() => undefined);@@ -473,7 +527,12 @@ export class KunaProjectCache {launcher: this.#launcher,});if (outcome.kind === "retained") {- this.#retainedProcesses.push(outcome.error);+ this.#retainedProcesses.push({+ key,+ error: outcome.error,+ owner: outcome.owner,+ staging,+ });return { result: err(outcome.error), retainStaging: true };}return {@@ -643,16 +702,16 @@ export class KunaProjectCache {if (isMissing(cause)) return;throw cause;}- await this.#removeRetired(trash);+ await this.#removeRetired(trash, key);}/** Keep each failed removal owned until that path is successfully removed. */- async #removeRetired(path: string): Promise<void> {+ async #removeRetired(path: string, key?: string): Promise<void> {try {await rm(path, { recursive: true, force: true });this.#retainedFiles.delete(path);} catch (cause: unknown) {- throw this.#retainFileCleanup(path, cause);+ throw this.#retainFileCleanup(path, cause, key);}}@@ -677,14 +736,42 @@ export class KunaProjectCache {return readFile(path, "utf8");}- #retainFileCleanup(path: string, cause: unknown): ProviderCleanupError {+ #retainFileCleanup(+ path: string,+ cause: unknown,+ key?: string,+ ): ProviderCleanupError {const error = new ProviderCleanupError(KUNA_PROVIDER_ID,[path],{ reason: cause instanceof Error ? cause.message : String(cause) },{ operation: KUNA_EXPORT_OPERATION, cause },);- this.#retainedFiles.set(path, error);+ this.#retainedFiles.set(path, {+ key: key ?? this.#retainedFiles.get(path)?.key ?? null,+ error,+ });return error;}}++/** One cleanup error aggregating what remains owned, or success when nothing does. */+const cleanupResult = (+ remaining: readonly ProviderCleanupError[],+): Result<null, ProviderCleanupError> => {+ if (remaining.length === 0) return ok(null);+ return err(+ new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ remaining.flatMap((entry) => entry.cleanupResources),+ {+ reason: remaining+ .map((entry) =>+ String(entry.diagnostics?.["reason"] ?? entry.message),+ )+ .join("; "),+ },+ { operation: KUNA_EXPORT_OPERATION },+ ),+ );+};diff --git a/src/kuna/KunaProjectExport.ts b/src/kuna/KunaProjectExport.tsindex 7b45f1c87..a782cdecc 100644--- a/src/kuna/KunaProjectExport.ts+++ b/src/kuna/KunaProjectExport.ts@@ -1,35 +1,25 @@-import { createHash, randomUUID } from "node:crypto";-import { createReadStream, createWriteStream } from "node:fs";+import { createReadStream } from "node:fs";import { lstat, mkdir, readFile, writeFile } from "node:fs/promises";import { basename, join } from "node:path";-import { Transform } from "node:stream";-import { pipeline } from "node:stream/promises";import { AnalysisError } from "../domain/analysisErrorBase.js";import {AnalysisArtifactChangedError,AnalysisCancelledError,- AnalysisResourceConstraintError,- AnalysisTimeoutError,} from "../domain/analysisErrorCore.js";import { ProviderAdapterError } from "../domain/providerAdapterError.js";-import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import type { ProviderCleanupError } from "../domain/providerCleanupError.js";import { err, ok, type Result } from "../domain/result.js";import { hashStableFile } from "../filesystem/StableFileHash.js";-import {- OwnedCommandFailure,- runOwnedCommand,-} from "../process/OwnedCommand.js";import { prepareProcessOwnershipInspection } from "../process/ProcessOwnershipObservation.js";-import type {- OwnedProviderProcessSpawnOptions,- ProviderProcessSnapshot,- SpawnedOwnedProviderProcess,-} from "../process/ProviderProcess.js";+import type { ProviderProcessSupervisor } from "../process/ProviderProcess.js";import {- kunaChildEnvironment,- type KunaInstallation,-} from "./KunaInstallation.js";+ copyAndHash,+ KUNA_INVENTORY_OUTPUT_BYTES,+ runKunaCommand,+ type KunaProcessLauncher,+} from "./KunaCommand.js";+import type { KunaInstallation } from "./KunaInstallation.js";import {parseKunaExportSummary,parseKunaInventory,@@ -46,12 +36,6 @@ export const KUNA_EXPORT_OPERATION = "kuna:decompile-project";/** Kuna prints one summary line per export; notes on a large image stay far below this. */const DIAGNOSTIC_BYTES = 8 * 1024 * 1024;-/**- * `kuna functions --json` costs ~210 bytes per function; this admits about- * 600,000 functions, above the 392,814 of the largest image Kuna documents.- */-const INVENTORY_BYTES = 128 * 1024 * 1024;-const INVENTORY_FILE = "functions.json";/** Identity of one file an export consists of. */@@ -87,11 +71,6 @@ export interface KunaExportStatus {readonly inventoryFunctions: number | null;}-/** Test seam for the owned process launcher; production uses the default. */-export type KunaProcessLauncher = (- options: OwnedProviderProcessSpawnOptions,-) => Promise<SpawnedOwnedProviderProcess>;-/*** How an export ended. `retained` means an owned Kuna process could not be* proven stopped, so it may still write into the workspace, which therefore@@ -102,7 +81,11 @@ export type KunaExportOutcome =readonly kind: "done";readonly result: Result<KunaExport, AnalysisError>;}- | { readonly kind: "retained"; readonly error: ProviderCleanupError };+ | {+ readonly kind: "retained";+ readonly error: ProviderCleanupError;+ readonly owner: ProviderProcessSupervisor | undefined;+ };/** One export of a target into a private workspace. */export interface KunaExportRequest {@@ -197,11 +180,38 @@ export const exportKunaProject = async (),};await prepareProcessOwnershipInspection(signal);- const run = (arguments_: readonly string[], diagnosticBytes: number) =>- runKuna(request, arguments_, { deadline, diagnosticBytes });+ const run = async (arguments_: readonly string[], outputBytes: number) => {+ const outcome = await runKunaCommand({+ installation,+ arguments: arguments_,+ workspace: request.workspace,+ operation: KUNA_EXPORT_OPERATION,+ timeoutMs: deadline - Date.now(),+ reportedTimeoutMs: configuration.projectTimeoutMs,+ outputBytes,+ signal,+ launcher: request.launcher,+ });+ if (outcome.kind === "ok")+ return { ok: true as const, snapshot: outcome.snapshot };+ return {+ ok: false as const,+ outcome:+ outcome.kind === "retained"+ ? ({+ kind: "retained",+ error: outcome.error,+ owner: outcome.owner,+ } as const)+ : ({ kind: "done", result: err(outcome.error) } as const),+ };+ };request.onStatus({ phase: "inventory", inventoryFunctions: null });- const listed = await run(["functions", input, "--json"], INVENTORY_BYTES);+ const listed = await run(+ ["functions", input, "--json"],+ KUNA_INVENTORY_OUTPUT_BYTES,+ );if (!listed.ok) return listed.outcome;const inventory = parseKunaInventory(listed.snapshot.stdout.text);if (!inventory.ok) return unusable(inventory.error);@@ -309,158 +319,3 @@ export const readKunaExport = async (if (!inventory.ok) return inventory;return ok({ functions: functions.value, inventory: inventory.value });};--const runKuna = async (- request: KunaExportRequest,- arguments_: readonly string[],- limits: { readonly deadline: number; readonly diagnosticBytes: number },-): Promise<- | { readonly ok: true; readonly snapshot: ProviderProcessSnapshot }- | { readonly ok: false; readonly outcome: KunaExportOutcome }-> => {- const { installation, signal } = request;- try {- const identity = await verifyKunaExecutable(installation, signal);- if (!identity.ok)- return { ok: false, outcome: { kind: "done", result: identity } };- const snapshot = await runOwnedCommand(- {- command: installation.executable,- arguments: arguments_,- runId: `rea-kuna-${randomUUID()}`,- // A script's process reports its interpreter, not the configured path.- ...(installation.script ? { expectedCommand: null } : {}),- cwd: request.workspace,- hostEnvironment: kunaChildEnvironment(installation.configuration),- env: { TMPDIR: request.workspace },- },- {- timeoutMs: Math.max(1, limits.deadline - Date.now()),- diagnosticBytes: limits.diagnosticBytes,- },- {- signal,- ...(request.launcher === undefined- ? {}- : { launcher: request.launcher }),- },- );- return { ok: true, snapshot };- } catch (cause: unknown) {- return {- ok: false,- outcome: commandFailure(cause, request, arguments_[0] ?? "", limits),- };- }-};--/** Copy the target into the workspace and return the SHA-256 of exactly the bytes copied. */-const copyAndHash = async (- source: string,- destination: string,- signal: AbortSignal,-): Promise<string> => {- const hash = createHash("sha256");- await pipeline(- createReadStream(source),- new Transform({- transform(chunk: Buffer, _encoding, callback) {- hash.update(chunk);- callback(null, chunk);- },- }),- createWriteStream(destination, { flags: "wx", mode: 0o600 }),- { signal },- );- return hash.digest("hex");-};--/** Map an owned-command failure to its typed error, keeping unproven cleanup owned. */-const commandFailure = (- cause: unknown,- request: KunaExportRequest,- subcommand: string,- limits: { readonly diagnosticBytes: number },-): KunaExportOutcome => {- const { installation, signal } = request;- if (!(cause instanceof OwnedCommandFailure))- return {- kind: "done",- result: err(- signal.aborted- ? new AnalysisCancelledError(KUNA_EXPORT_OPERATION, { cause })- : new ProviderAdapterError(KUNA_PROVIDER_ID, KUNA_EXPORT_OPERATION, {- cause,- userMessage: `Cannot run ${installation.executable}: ${message(cause)}`,- }),- ),- };- const snapshot = cause.snapshot;- const capturedOutput =- snapshot === null- ? undefined- : {- // An inventory is evidence-sized, not diagnostic-sized; keep only its tail.- stdout: snapshot.stdout.text.slice(-4096),- stderr: snapshot.stderr.text,- truncated:- snapshot.diagnosticTruncated === true ||- snapshot.outputIncomplete === true ||- snapshot.stdout.text.length > 4096,- exit_code: snapshot.exitCode ?? null,- signal: snapshot.signal ?? null,- };- const details = {- cause,- ...(capturedOutput === undefined ? {} : { capturedOutput }),- };- if (cause.cleanupFailure !== null)- return {- kind: "retained",- error: new ProviderCleanupError(- KUNA_PROVIDER_ID,- [...cause.resources, request.workspace],- { reason: cause.cleanupFailure },- { operation: KUNA_EXPORT_OPERATION, cause },- ),- };- if (cause.reason === "cancelled")- return {- kind: "done",- result: err(new AnalysisCancelledError(KUNA_EXPORT_OPERATION, details)),- };- if (cause.reason === "timeout")- return {- kind: "done",- result: err(- new AnalysisTimeoutError(- KUNA_EXPORT_OPERATION,- installation.configuration.projectTimeoutMs,- details,- ),- ),- };- if (cause.reason === "output-limit")- return {- kind: "done",- result: err(- new AnalysisResourceConstraintError(- KUNA_EXPORT_OPERATION,- "capacity",- `kuna ${subcommand} wrote more than ${String(limits.diagnosticBytes)} bytes of output; the export was not retained.`,- { output_limit_bytes: limits.diagnosticBytes },- details,- ),- ),- };- const exitCode = capturedOutput?.exit_code;- return {- kind: "done",- result: err(- new ProviderAdapterError(KUNA_PROVIDER_ID, KUNA_EXPORT_OPERATION, {- ...details,- userMessage: `kuna ${subcommand} failed${exitCode === undefined || exitCode === null ? "" : ` with exit code ${String(exitCode)}`}: ${capturedOutput?.stderr.trim().split("\n").at(-1) ?? cause.message}`,- }),- ),- };-};diff --git a/src/kuna/KunaProjectFiles.ts b/src/kuna/KunaProjectFiles.tsindex 9f0714f58..5d8974c0a 100644--- a/src/kuna/KunaProjectFiles.ts+++ b/src/kuna/KunaProjectFiles.ts@@ -41,50 +41,37 @@ export const parseKunaExportSummary = (return { decompiled: Number(match[1]), failed: Number(match[2]) };};-/** A header line longer than this is not one Kuna wrote. */-const MAX_HEADER_BYTES = 64 * 1024;-const PREFIX_BYTES = Buffer.from(HEADER_PREFIX);+/** A structural line longer than this is not one Kuna wrote. */+const MAX_KEPT_LINE_BYTES = 64 * 1024;-interface Header {- readonly name: string;- readonly address: string;- readonly error: string | null;+/** One line a scan kept: where it starts in the file and its text. */+interface KeptLine {readonly offset: number;+ readonly text: string;}/**- * Split a finished export's `.c` into its function blocks, reading it as a- * stream so a very large export is never held in memory.- *- * The `#include` preamble precedes the first header. The header count must- * equal the functions Kuna reported, and every address must be distinct; an- * export that fails either check is not a usable function inventory.+ * Stream a file's lines, keeping the text of only the lines whose first+ * `headBytes` bytes `keep` accepts. Every other line is skipped without being+ * buffered, so a large export is never held in memory.*/-export const scanKunaProjectSource = async (+const scanLines = async (chunks: AsyncIterable<Buffer>,- summary: KunaExportSummary,-): Promise<Result<readonly KunaProjectFunction[], string>> => {- const headers: Header[] = [];+ headBytes: number,+ keep: (head: Buffer) => boolean,+): Promise<+ Result<+ { readonly lines: readonly KeptLine[]; readonly bytes: number },+ string+ >+> => {+ const lines: KeptLine[] = [];let offset = 0;let lineStart = 0;- // Bytes of the current line, kept only while it may still be a header.+ // The current line's bytes while it is undecided or kept; undefined once skipped.let line: Buffer[] | undefined = [];let lineBytes = 0;- const endLine = (): string | undefined => {- if (line === undefined) return undefined;- const text = Buffer.concat(line).toString("utf8");- if (!text.startsWith(HEADER_PREFIX)) return undefined;- const match = HEADER.exec(text);- if (match?.[1] === undefined || match[2] === undefined)- return `unrecognized function header at byte ${String(lineStart)}`;- headers.push({- name: match[1],- address: match[2],- error: match[3] ?? null,- offset: lineStart,- });- return undefined;- };+ let decided = false;for await (const chunk of chunks) {let position = 0;while (position < chunk.length) {@@ -94,27 +81,71 @@ export const scanKunaProjectSource = async (const segment = chunk.subarray(position, end);line.push(segment);lineBytes += segment.length;- const seen = Buffer.concat(line).subarray(0, PREFIX_BYTES.length);- if (!PREFIX_BYTES.subarray(0, seen.length).equals(seen))- line = undefined;- else if (lineBytes > MAX_HEADER_BYTES)- return err(- `function header at byte ${String(lineStart)} is too long`,- );+ if (!decided && (lineBytes >= headBytes || newline !== -1)) {+ decided = true;+ if (!keep(Buffer.concat(line).subarray(0, headBytes)))+ line = undefined;+ }+ if (line !== undefined && lineBytes > MAX_KEPT_LINE_BYTES)+ return err(`the line at byte ${String(lineStart)} is too long`);}if (newline === -1) break;- const failure = endLine();- if (failure !== undefined) return err(failure);+ if (line !== undefined)+ lines.push({+ offset: lineStart,+ text: Buffer.concat(line).toString("utf8"),+ });position = newline + 1;lineStart = offset + position;line = [];lineBytes = 0;+ decided = false;}offset += chunk.length;}- const failure = endLine();- if (failure !== undefined) return err(failure);- const total = offset;+ if (line !== undefined && lineBytes > 0) {+ const head = Buffer.concat(line);+ if (decided || keep(head.subarray(0, headBytes)))+ lines.push({ offset: lineStart, text: head.toString("utf8") });+ }+ return ok({ lines, bytes: offset });+};++const HEADER_PREFIX_BYTES = Buffer.from(HEADER_PREFIX);++/**+ * Split a finished export's `.c` into its function blocks.+ *+ * The `#include` preamble precedes the first header. The header count must+ * equal the functions Kuna reported, and every address must be distinct; an+ * export that fails either check is not a usable function inventory.+ */+export const scanKunaProjectSource = async (+ chunks: AsyncIterable<Buffer>,+ summary: KunaExportSummary,+): Promise<Result<readonly KunaProjectFunction[], string>> => {+ const scanned = await scanLines(chunks, HEADER_PREFIX_BYTES.length, (head) =>+ head.equals(HEADER_PREFIX_BYTES),+ );+ if (!scanned.ok) return scanned;+ const headers: {+ readonly name: string;+ readonly address: string;+ readonly error: string | null;+ readonly offset: number;+ }[] = [];+ for (const { offset, text } of scanned.value.lines) {+ const match = HEADER.exec(text);+ if (match?.[1] === undefined || match[2] === undefined)+ return err(`unrecognized function header at byte ${String(offset)}`);+ headers.push({+ name: match[1],+ address: match[2],+ error: match[3] ?? null,+ offset,+ });+ }+ const total = scanned.value.bytes;const expected = summary.decompiled + summary.failed;if (headers.length !== expected)return err(@@ -187,3 +218,68 @@ export const parseKunaInventory = (})),);};++/** One labeled span of an export's `.asm`. */+export interface KunaAssemblySpan {+ readonly name: string;+ readonly address: string;+ readonly offset: number;+ readonly length: number;+}++/** Function listings and data labels found in an export's `.asm`. */+export interface KunaAssemblyIndex {+ /** Code labels, which name the same functions as the `.c`, by address. */+ readonly code: ReadonlyMap<string, KunaAssemblySpan>;+ /** Labels in the `; --- data ---` tail: named globals and Kuna's `dat_`/`s_` names. */+ readonly data: ReadonlyMap<string, string>;+}++// Rendered by kuna-console: `{name}: ; 0x{addr:x}` at column 0, optionally+// followed by ` = dat_{addr:x}` in the data tail. A code label's listing runs+// to the next label, the next `; --- ` section marker, or the end of the file.+const LABEL = /^(.+): ; (0x[0-9a-f]+)(?: = dat_[0-9a-f]+)?$/u;+const SECTION_MARKER = "; --- ";+const DATA_MARKER = "; --- data ---";+const SPACE = 0x20;+const TAB = 0x09;++/** Index the labels of an export's `.asm` without holding the file in memory. */+export const scanKunaAssembly = async (+ chunks: AsyncIterable<Buffer>,+): Promise<Result<KunaAssemblyIndex, string>> => {+ const scanned = await scanLines(+ chunks,+ 1,+ (head) => head[0] !== SPACE && head[0] !== TAB && head.length > 0,+ );+ if (!scanned.ok) return scanned;+ const code = new Map<string, KunaAssemblySpan>();+ const data = new Map<string, string>();+ let inData = false;+ let open: { name: string; address: string; offset: number } | undefined;+ const close = (end: number) => {+ if (open === undefined) return;+ code.set(open.address, { ...open, length: end - open.offset });+ open = undefined;+ };+ for (const { offset, text } of scanned.value.lines) {+ if (text.startsWith(SECTION_MARKER)) {+ close(offset);+ if (text.startsWith(DATA_MARKER)) inData = true;+ continue;+ }+ const match = LABEL.exec(text);+ if (match?.[1] === undefined || match[2] === undefined) continue;+ if (inData) {+ if (!data.has(match[2])) data.set(match[2], match[1]);+ continue;+ }+ close(offset);+ if (code.has(match[2]))+ return err(`the .asm repeats code address ${match[2]}`);+ open = { name: match[1], address: match[2], offset };+ }+ close(scanned.value.bytes);+ return ok({ code, data });+};diff --git a/src/kuna/KunaProjectReader.ts b/src/kuna/KunaProjectReader.tsnew file mode 100644index 000000000..ba5f983a2--- /dev/null+++ b/src/kuna/KunaProjectReader.ts@@ -0,0 +1,180 @@+import { createReadStream } from "node:fs";+import { open } from "node:fs/promises";+import { join } from "node:path";++import type { AnalysisError } from "../domain/analysisErrorBase.js";+import {+ AnalysisCapabilityUnavailableError,+ AnalysisResourceConstraintError,+} from "../domain/analysisErrorCore.js";+import { ProviderAdapterError } from "../domain/providerAdapterError.js";+import { err, ok, type Result } from "../domain/result.js";+import type { KunaProject } from "./KunaProjectCache.js";+import {+ scanKunaAssembly,+ type KunaAssemblyIndex,+ type KunaProjectFunction,+} from "./KunaProjectFiles.js";+import { KUNA_PROVIDER_ID } from "./KunaRelease.js";+import { KUNA_FUNCTION_TEXT_BYTES } from "./KunaLimits.js";++/** The exact producing range for one facet, including a failed C block. */+export interface KunaProjectFileSpan {+ readonly facet: "pseudocode" | "assembly";+ readonly path: string;+ readonly byteOffset: number;+ readonly byteLength: number;+}++export interface KunaProjectText {+ readonly result: string | null;+ readonly files?: readonly KunaProjectFileSpan[];+ readonly limitations: readonly string[];+}++const readSpan = async (+ operation: string,+ path: string,+ offset: number,+ length: number,+): Promise<Result<string, AnalysisError>> => {+ if (length > KUNA_FUNCTION_TEXT_BYTES)+ return err(+ new AnalysisResourceConstraintError(+ operation,+ "capacity",+ "Kuna's function text exceeds the buffered source-facet capacity; the complete export remains accessible locally.",+ {+ limit_bytes: KUNA_FUNCTION_TEXT_BYTES,+ requested_bytes: length,+ file: path,+ byte_offset: offset,+ },+ ),+ );+ const handle = await open(path, "r");+ try {+ const buffer = Buffer.alloc(length);+ const { bytesRead } = await handle.read(buffer, 0, length, offset);+ if (bytesRead !== length)+ throw new Error(`${path} is shorter than its recorded span`);+ return ok(buffer.toString("utf8"));+ } finally {+ await handle.close();+ }+};++/** One immutable export owns both its text ranges and its parsed label indexes. */+export class KunaProjectReader {+ #blocks: ReadonlyMap<string, KunaProjectFunction> | undefined;+ #assembly: Promise<Result<KunaAssemblyIndex, string>> | undefined;++ constructor(readonly project: KunaProject) {}++ async pseudocode(+ address: string,+ operation: string,+ ): Promise<Result<KunaProjectText, AnalysisError>> {+ this.#blocks ??= new Map(+ this.project.functions.map((block) => [block.address, block]),+ );+ const block = this.#blocks.get(address);+ if (block === undefined)+ return ok({+ result: null,+ limitations: [+ "Kuna's export decompiles code entries only; this inventory entry, such as an import slot, has no body.",+ ],+ });+ const files = [+ {+ facet: "pseudocode" as const,+ path: this.project.manifest.files.c.path,+ byteOffset: block.cOffset,+ byteLength: block.cLength,+ },+ ];+ if (block.error !== null)+ return ok({+ result: null,+ files,+ limitations: [`Kuna could not decompile this function: ${block.error}`],+ });+ const text = await readSpan(+ operation,+ join(this.project.directory, this.project.manifest.files.c.path),+ block.cOffset,+ block.cLength,+ );+ if (!text.ok) return text;+ return ok({+ result: text.value+ .slice(text.value.indexOf("\n") + 1)+ .replace(/\n+$/u, ""),+ files,+ limitations: [],+ });+ }++ async assembly(+ address: string,+ operation: string,+ ): Promise<Result<KunaProjectText, AnalysisError>> {+ const index = await this.#index(operation);+ if (!index.ok) return index;+ const span = index.value.code.get(address);+ if (span === undefined)+ return err(+ new AnalysisCapabilityUnavailableError(+ KUNA_PROVIDER_ID,+ operation,+ `Kuna's export lists no code at ${address}; import slots and data entries have no listing.`,+ ),+ );+ const text = await readSpan(+ operation,+ join(this.project.directory, this.project.manifest.files.asm.path),+ span.offset,+ span.length,+ );+ if (!text.ok) return text;+ return ok({+ result: text.value.replace(/\n+$/u, ""),+ files: [+ {+ facet: "assembly",+ path: this.project.manifest.files.asm.path,+ byteOffset: span.offset,+ byteLength: span.length,+ },+ ],+ limitations: [],+ });+ }++ async dataName(+ address: string,+ operation: string,+ ): Promise<Result<string | null, AnalysisError>> {+ const index = await this.#index(operation);+ return index.ok ? ok(index.value.data.get(address) ?? null) : index;+ }++ async #index(+ operation: string,+ ): Promise<Result<KunaAssemblyIndex, AnalysisError>> {+ this.#assembly ??= scanKunaAssembly(+ createReadStream(+ join(this.project.directory, this.project.manifest.files.asm.path),+ ),+ );+ const index = await this.#assembly;+ return index.ok+ ? index+ : err(+ new ProviderAdapterError(KUNA_PROVIDER_ID, operation, {+ userMessage: `Kuna's .asm cannot be indexed: ${index.error}`,+ }),+ );+ }+}diff --git a/src/kuna/KunaProvider.ts b/src/kuna/KunaProvider.tsnew file mode 100644index 000000000..4f79acab2--- /dev/null+++ b/src/kuna/KunaProvider.ts@@ -0,0 +1,224 @@+import { accessSync, constants, statSync } from "node:fs";++import type {+ AnalysisClient,+ AnalysisProfileResolutionOptions,+ AnalysisProviderCandidate,+ ProviderAvailability,+ ProviderTargetSupport,+} from "../application/AnalysisProvider.js";+import {+ AnalysisCancelledError,+ AnalysisCapabilityUnavailableError,+} from "../domain/analysisErrorCore.js";+import {+ createAnalysisProfile,+ type AnalysisProfileCommitment,+} from "../domain/analysisProfile.js";+import type { BinaryTarget } from "../domain/binaryTargetTypes.js";+import { err, ok } from "../domain/result.js";+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";+import type { KunaProcessLauncher } from "./KunaCommand.js";+import {+ readKunaConfiguration,+ type KunaConfiguration,+} from "./KunaConfiguration.js";+import { inspectKunaInstallation } from "./KunaInstallation.js";+import { KunaProjectCache } from "./KunaProjectCache.js";+import {+ KUNA_PROVIDER_IDENTITY,+ kunaCapabilities,+} from "./KunaProviderCapabilities.js";+import { KUNA_COMMAND_REMEDIATION, KUNA_PROVIDER_ID } from "./KunaRelease.js";+import { KunaSessionClient } from "./KunaSessionClient.js";++/** Architectures REA verified Kuna on: x86-64 and AArch64 ELF and Mach-O, plus ARM Thumb. */+const VERIFIED_ARCHITECTURES: ReadonlySet<string> = new Set([+ "x86_64",+ "arm64",+ "arm",+]);++/**+ * Bring-your-own Kuna candidate. Discovery reads configuration and the+ * executable's metadata only; the version probe runs when a target is opened.+ */+export class KunaProvider implements AnalysisProviderCandidate {+ readonly #environment: Readonly<NodeJS.ProcessEnv>;+ readonly #platform: NodeJS.Platform;+ readonly #launcher: KunaProcessLauncher | undefined;+ #cache: KunaProjectCache | undefined;++ constructor(+ environment: Readonly<NodeJS.ProcessEnv>,+ options: {+ readonly platform?: NodeJS.Platform;+ readonly launcher?: KunaProcessLauncher;+ } = {},+ ) {+ this.#platform = options.platform ?? process.platform;+ this.#environment = snapshotEnvironment(environment, this.#platform);+ this.#launcher = options.launcher;+ }++ identity() {+ return KUNA_PROVIDER_IDENTITY;+ }++ capabilities() {+ const availability = this.inspectAvailability();+ return kunaCapabilities(+ availability.status === "available"+ ? { available: true }+ : {+ available: false,+ reason: availability.reason,+ code: availability.code,+ },+ );+ }++ inspectAvailability(): ProviderAvailability {+ const configuration = readKunaConfiguration(+ this.#environment,+ this.#platform,+ );+ if (!configuration.ok)+ return {+ status: "unavailable",+ code: configuration.error.code,+ reason: configuration.error.reason,+ diagnostics: {+ configured: configuration.error.code !== "not_configured",+ version_probed: false,+ },+ };+ const { command } = configuration.value;+ try {+ accessSync(command, constants.X_OK);+ if (!statSync(command).isFile()) throw new Error("not a regular file");+ } catch (cause: unknown) {+ return {+ status: "unavailable",+ code: "executable_missing",+ reason: `Cannot execute REA_KUNA_COMMAND ${command}: ${cause instanceof Error ? cause.message : String(cause)}. ${KUNA_COMMAND_REMEDIATION}`,+ diagnostics: { configured: true, command, version_probed: false },+ };+ }+ return {+ status: "available",+ code: null,+ reason: null,+ diagnostics: {+ configured: true,+ command,+ cache_root: configuration.value.cacheRoot,+ jobs: configuration.value.jobs,+ version_probed: false,+ },+ };+ }++ inspectTargetSupport(target: BinaryTarget): ProviderTargetSupport {+ const diagnostics = {+ target_kind: target.kind,+ target_format: target.format,+ };+ if (target.kind !== "executable")+ return {+ status: "unsupported",+ code: "target_kind_unsupported",+ reason: "Kuna decompiles executable images, not databases or archives.",+ diagnostics,+ };+ if (target.format !== "elf" && target.format !== "mach-o")+ return {+ status: "unsupported",+ code: "target_format_unsupported",+ reason:+ target.format === "mach-o-universal"+ ? "REA's Kuna provider has no verified universal Mach-O slice selection yet; open a thin slice or use another provider."+ : `REA verified the Kuna provider on ELF and thin Mach-O images; ${target.format} is not admitted yet.`,+ diagnostics,+ };+ if (!VERIFIED_ARCHITECTURES.has(target.architecture))+ return {+ status: "unsupported",+ code: "architecture_unsupported",+ reason: `REA verified the Kuna provider on x86-64, AArch64 and ARM; ${target.architecture} is not admitted yet.`,+ diagnostics: { ...diagnostics, architecture: target.architecture },+ };+ return { status: "supported", code: null, reason: null, diagnostics };+ }++ async resolveAnalysisProfile(+ _target: BinaryTarget,+ options?: AnalysisProfileResolutionOptions,+ ) {+ if (options?.signal?.aborted === true)+ return err(new AnalysisCancelledError("kuna:profile"));+ const installation = await inspectKunaInstallation(this.#environment, {+ platform: this.#platform,+ ...(options?.signal === undefined ? {} : { signal: options.signal }),+ });+ if (!installation.ok)+ return err(+ new AnalysisCapabilityUnavailableError(+ KUNA_PROVIDER_ID,+ "open_binary",+ installation.error.reason,+ { userMessage: installation.error.reason },+ ),+ );+ const { value } = installation;+ return ok({+ profile: createAnalysisProfile(+ { ...KUNA_PROVIDER_IDENTITY, version: value.version },+ {+ kuna_version: value.version,+ kuna_sha256: value.sha256,+ verified_release: value.verified,+ jobs: value.configuration.jobs,+ export: "decompile-project",+ cache_policy: "live",+ },+ ),+ });+ }++ createClient(+ target: BinaryTarget,+ profile?: AnalysisProfileCommitment,+ ): AnalysisClient {+ const configuration = readKunaConfiguration(+ this.#environment,+ this.#platform,+ );+ if (!configuration.ok)+ return {+ execute: async (operation) =>+ err(+ new AnalysisCapabilityUnavailableError(+ KUNA_PROVIDER_ID,+ operation,+ configuration.error.reason,+ ),+ ),+ close: async () => ok(null),+ };+ return new KunaSessionClient(target, profile, {+ cache: this.#projectCache(configuration.value),+ environment: this.#environment,+ ...(this.#launcher === undefined ? {} : { launcher: this.#launcher }),+ });+ }++ /** One cache per provider, so sessions of one server share exports in flight. */+ #projectCache(configuration: KunaConfiguration): KunaProjectCache {+ this.#cache ??= new KunaProjectCache(configuration.cacheRoot, {+ maxBytes: configuration.cacheMaxBytes,+ ...(this.#launcher === undefined ? {} : { launcher: this.#launcher }),+ });+ return this.#cache;+ }+}diff --git a/src/kuna/KunaProviderCapabilities.ts b/src/kuna/KunaProviderCapabilities.tsnew file mode 100644index 000000000..00baf6113--- /dev/null+++ b/src/kuna/KunaProviderCapabilities.ts@@ -0,0 +1,115 @@+import type {+ AnalysisOperation,+ CapabilityDescriptor,+} from "../application/AnalysisProvider.js";+import type { ProviderRejectionCode } from "../contracts/providerSelection.js";+import { KUNA_PROVIDER_ID } from "./KunaRelease.js";+import { REGEX_MATCHING_LIMITATION } from "../process/RegexMatcher.js";+import { KUNA_FUNCTION_TEXT_BYTES } from "./KunaLimits.js";++/** Static identity; the observed Kuna release is reported in each analysis profile. */+export const KUNA_PROVIDER_IDENTITY = Object.freeze({+ id: KUNA_PROVIDER_ID,+ name: "Kuna",+ version: null,+});++/** Analyst outcomes Kuna's inventory and project export can answer. */+export const KUNA_OPERATIONS = Object.freeze([+ "list_documents",+ "list_procedures",+ "search_procedures",+ "procedure_address",+ "address_name",+ "procedure_pseudo_code",+ "procedure_assembly",+ "analyze_function",+] as const satisfies readonly Exclude<AnalysisOperation, "health">[]);+export type KunaOperation = (typeof KUNA_OPERATIONS)[number];++/** Whether an operation is one Kuna answers. */+export const isKunaOperation = (+ operation: AnalysisOperation,+): operation is KunaOperation =>+ (KUNA_OPERATIONS as readonly string[]).includes(operation);++/** How to read every Kuna answer. */+const KUNA_PROVENANCE =+ "Kuna static analysis: addresses and bytes are its observations, procedure entries and extents its derivations, and pseudocode its reconstruction, never original source.";++/** Entries come from Kuna's own discovery. */+const KUNA_ENTRY_LIMITATION =+ "Kuna may split one function at an entry its own analysis infers; entry extents are upper bounds.";++/** Provider text is not comparable across providers. */+const KUNA_TEXT_LIMITATION =+ "Pseudocode and assembly are exact Kuna text, not comparable as equal or different with another provider's text.";+const KUNA_TEXT_CAPACITY_LIMITATION = `Each buffered source facet admits at most ${String(KUNA_FUNCTION_TEXT_BYTES)} bytes before allocation; larger text stays accessible in the local project export.`;++/** The limitations that apply to one operation's answer, and only those. */+export const kunaLimitations = (+ operation: KunaOperation,+): readonly string[] => {+ switch (operation) {+ case "list_documents":+ return [];+ case "list_procedures":+ case "procedure_address":+ case "address_name":+ return [KUNA_PROVENANCE, KUNA_ENTRY_LIMITATION];+ case "search_procedures":+ return [+ KUNA_PROVENANCE,+ KUNA_ENTRY_LIMITATION,+ REGEX_MATCHING_LIMITATION,+ ];+ case "procedure_pseudo_code":+ case "procedure_assembly":+ case "analyze_function":+ return [+ KUNA_PROVENANCE,+ KUNA_TEXT_LIMITATION,+ KUNA_TEXT_CAPACITY_LIMITATION,+ ];+ }+};++/** Pseudocode answered before the project export finishes differs from the export's. */+export const KUNA_SINGLE_FUNCTION_LIMITATION =+ "This pseudocode came from a single-function `kuna decompile` run while the project export was still building. It lacks the export's whole-program prototypes, and a later request for the same procedure can return the export's text.";++/** Advertise Kuna's static, process-launching operations truthfully. */+export const kunaCapabilities = (+ availability:+ | { readonly available: true }+ | {+ readonly available: false;+ readonly reason: string;+ readonly code: ProviderRejectionCode;+ },+): readonly CapabilityDescriptor[] =>+ KUNA_OPERATIONS.map((operation) => ({+ provider: KUNA_PROVIDER_IDENTITY,+ operation,+ ...(availability.available+ ? ({ available: true, reason: null } as const)+ : ({+ available: false,+ reason: availability.reason,+ availabilityCode: availability.code,+ } as const)),+ // A cold answer can come from the single-function path and differ from the+ // export's later answer, so results are re-read rather than replayed. The+ // project cache already serves warm reads in milliseconds.+ cachePolicy: "live",+ effects: {+ mutatesArtifact: false,+ launchesProcess: true,+ mayShowUi: false,+ mayAccessNetwork: false,+ mayWriteFilesystem: true,+ changesPermissions: false,+ requiresRoot: false,+ },+ limitations: kunaLimitations(operation),+ }));diff --git a/src/kuna/KunaSessionClient.ts b/src/kuna/KunaSessionClient.tsnew file mode 100644index 000000000..233873e08--- /dev/null+++ b/src/kuna/KunaSessionClient.ts@@ -0,0 +1,1060 @@+import { basename, join } from "node:path";++import { z } from "zod";++import {+ createAnalysisExecution,+ type AnalysisClient,+ type AnalysisExecution,+ type AnalysisOperation,+ type ExecutionOptions,+} from "../application/AnalysisProvider.js";+import { AnalysisError } from "../domain/analysisErrorBase.js";+import {+ AnalysisArtifactChangedError,+ AnalysisCancelledError,+ AnalysisCapabilityUnavailableError,+ AnalysisInputError,+} from "../domain/analysisErrorCore.js";+import type { AnalysisProfileCommitment } from "../domain/analysisProfile.js";+import {+ analysisSearchPredicate,+ analysisSearchQuerySchema,+} from "../domain/analysisSearch.js";+import type { BinaryTarget } from "../domain/binaryTargetTypes.js";+import type { EvidenceLocation } from "../domain/evidence.js";+import { functionDossierSchema } from "../domain/hopperValues.js";+import type { JsonValue } from "../domain/jsonValue.js";+import { ProviderAdapterError } from "../domain/providerAdapterError.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { err, ok, type Result } from "../domain/result.js";+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";+import { matchRegexValues } from "../process/RegexMatcher.js";+import { prepareProcessOwnershipInspection } from "../process/ProcessOwnershipObservation.js";+import type { ProviderProcessSupervisor } from "../process/ProviderProcess.js";+import {+ copyAndHash,+ KUNA_INVENTORY_OUTPUT_BYTES,+ runKunaCommand,+ type KunaProcessLauncher,+} from "./KunaCommand.js";+import {+ inspectKunaInstallation,+ type KunaInstallation,+} from "./KunaInstallation.js";+import {+ kunaProjectKey,+ type KunaProject,+ type KunaProjectCache,+} from "./KunaProjectCache.js";+import type { KunaExportStatus } from "./KunaProjectExport.js";+import {+ parseKunaInventory,+ type KunaInventoryFunction,+} from "./KunaProjectFiles.js";+import {+ isKunaOperation,+ KUNA_SINGLE_FUNCTION_LIMITATION,+ kunaLimitations,+ type KunaOperation,+} from "./KunaProviderCapabilities.js";+import { KUNA_PROVIDER_ID } from "./KunaRelease.js";+import { KUNA_FUNCTION_TEXT_BYTES } from "./KunaLimits.js";+import {+ KunaProjectReader,+ type KunaProjectFileSpan,+} from "./KunaProjectReader.js";++/** How often a request waiting on the project export reports that it still waits. */+const WAIT_PROGRESS_INTERVAL_MS = 10_000;++const HEX_ADDRESS = /^0x[0-9a-f]+$/iu;++/** Where one answer's text came from, recorded in its raw result. */+type AnswerSource =+ | { readonly kind: "project-export"; readonly project: KunaProject }+ | { readonly kind: "single-function" };++interface InventoryIndex {+ readonly inventory: readonly KunaInventoryFunction[];+ readonly byAddress: ReadonlyMap<string, KunaInventoryFunction>;+ readonly byName: ReadonlyMap<string, readonly KunaInventoryFunction[]>;+}++interface Answer {+ readonly result: JsonValue;+ readonly source: AnswerSource | null;+ readonly files?: readonly KunaProjectFileSpan[];+ readonly locations: readonly EvidenceLocation[];+ readonly limitations: readonly string[];+}++/**+ * Wait for work this session owns, stopping only this caller's wait when its+ * signal aborts; the work itself continues for other callers.+ */+const waitFor = <T>(+ work: Promise<Result<T, AnalysisError>>,+ signal: AbortSignal | undefined,+ operation: string,+): Promise<Result<T, AnalysisError>> => {+ if (signal === undefined) return work;+ if (signal.aborted)+ return Promise.resolve(err(new AnalysisCancelledError(operation)));+ return new Promise((resolve) => {+ const onAbort = () => resolve(err(new AnalysisCancelledError(operation)));+ signal.addEventListener("abort", onAbort, { once: true });+ void work.then((result) => {+ signal.removeEventListener("abort", onAbort);+ resolve(result);+ });+ });+};++/** A file the adopted export named is gone, e.g. evicted by another REA process. */+const isMissing = (cause: unknown): boolean =>+ cause instanceof Error &&+ "code" in cause &&+ (cause.code === "ENOENT" || cause.code === "ENOTDIR");++/** Read through a call so a check before an await does not narrow later ones. */+const cancelled = (signal: AbortSignal | undefined): boolean =>+ signal?.aborted === true;++const message = (cause: unknown): string =>+ cause instanceof Error ? cause.message : String(cause);++const failure = (operation: string, cause: unknown): AnalysisError =>+ cause instanceof AnalysisError+ ? cause+ : new ProviderAdapterError(KUNA_PROVIDER_ID, operation, {+ cause,+ userMessage: `Kuna ${operation} failed: ${message(cause)}`,+ });++/** Kuna names a procedure by its inventory entry or by an exact entry address. */+const procedureSelectorSchema = z.string().min(1);++/**+ * One Kuna analysis session for one target.+ *+ * Reads come from the verified project export in REA's cache. Until that+ * export exists, listings use a quick `kuna functions` inventory and+ * pseudocode a single-function `kuna decompile`, while the export builds in+ * the background; assembly waits for it. Kuna always runs on a private copy+ * whose digest matches the selected target.+ */+export class KunaSessionClient implements AnalysisClient {+ readonly #target: BinaryTarget;+ readonly #profile: AnalysisProfileCommitment | undefined;+ readonly #cache: KunaProjectCache;+ readonly #environment: Readonly<NodeJS.ProcessEnv>;+ readonly #launcher: KunaProcessLauncher | undefined;+ /** Owns background work: aborting it cancels this session's export interest. */+ readonly #session = new AbortController();+ /** Requests keep their workspaces and process cleanup owned until they settle. */+ readonly #requests = new Set<+ Promise<Result<AnalysisExecution, AnalysisError>>+ >();+ /** Single-function runs that could not be proven stopped, with their retry owners. */+ readonly #retained: {+ readonly error: ProviderCleanupError;+ owner: ProviderProcessSupervisor | undefined;+ }[] = [];+ /** Private roots whose removal failed during setup or close. */+ readonly #leakedRoots: PrivateRuntimeRoot[] = [];+ #installation: Promise<Result<KunaInstallation, AnalysisError>> | undefined;+ #workspace:+ | Promise<+ Result<+ { readonly root: PrivateRuntimeRoot; readonly input: string },+ AnalysisError+ >+ >+ | undefined;+ #inventory:+ | Promise<Result<readonly KunaInventoryFunction[], AnalysisError>>+ | undefined;+ #project: Promise<Result<KunaProject, AnalysisError>> | undefined;+ #reader: KunaProjectReader | undefined;+ #inventoryIndex: InventoryIndex | undefined;+ #status: KunaExportStatus | undefined;+ #key: string | undefined;+ #exportFailure: string | undefined;+ #releasePin: (() => void) | undefined;+ /** Set once close starts; new requests are refused from then on. */+ #closing = false;+ /** Set only when close has released every owned resource. */+ #closed = false;++ constructor(+ target: BinaryTarget,+ profile: AnalysisProfileCommitment | undefined,+ dependencies: {+ readonly cache: KunaProjectCache;+ readonly environment: Readonly<NodeJS.ProcessEnv>;+ readonly launcher?: KunaProcessLauncher;+ },+ ) {+ this.#target = target;+ this.#profile = profile;+ this.#cache = dependencies.cache;+ this.#environment = dependencies.environment;+ this.#launcher = dependencies.launcher;+ }++ async execute(+ operation: AnalysisOperation,+ parameters: Readonly<Record<string, JsonValue>>,+ options: ExecutionOptions = {},+ ): Promise<Result<AnalysisExecution, AnalysisError>> {+ if (this.#closing)+ return err(+ new AnalysisCapabilityUnavailableError(+ KUNA_PROVIDER_ID,+ operation,+ "This Kuna session is closed.",+ ),+ );+ const request = this.#execute(operation, parameters, {+ ...options,+ signal:+ options.signal === undefined+ ? this.#session.signal+ : AbortSignal.any([this.#session.signal, options.signal]),+ });+ this.#requests.add(request);+ try {+ return await request;+ } finally {+ this.#requests.delete(request);+ }+ }++ async #execute(+ operation: AnalysisOperation,+ parameters: Readonly<Record<string, JsonValue>>,+ options: ExecutionOptions,+ ): Promise<Result<AnalysisExecution, AnalysisError>> {+ if (cancelled(options.signal))+ return err(new AnalysisCancelledError(operation));+ if (operation !== "health" && !isKunaOperation(operation))+ return err(+ new AnalysisCapabilityUnavailableError(+ KUNA_PROVIDER_ID,+ operation,+ "Kuna answers procedure listings, lookups, pseudocode and assembly; this operation needs another provider.",+ ),+ );+ const document = parameters.document;+ if (document !== undefined && document !== this.#target.path)+ return err(+ new AnalysisInputError(+ operation,+ {+ userMessage:+ "A Kuna session analyzes one program; omit document or pass the selected target path.",+ },+ [+ {+ path: ["document"],+ reason: "invalid_value",+ expected: this.#target.path,+ },+ ],+ ),+ );+ const installation = await this.#ensureInstallation();+ if (!installation.ok) return installation;+ try {+ if (operation === "health")+ return ok(+ this.#execution([], installation.value, {+ result: {+ ready: true,+ kuna: {+ version: installation.value.version,+ verified: installation.value.verified,+ sha256: installation.value.sha256,+ },+ },+ source: null,+ locations: [],+ limitations: [],+ }),+ );+ if (operation !== "list_documents")+ await this.#startProject(installation.value);+ const answer = await this.#answer(+ operation,+ parameters,+ installation.value,+ options,+ );+ if (!answer.ok) return answer;+ if (cancelled(options.signal))+ return err(new AnalysisCancelledError(operation));+ return ok(+ this.#execution(+ kunaLimitations(operation),+ installation.value,+ answer.value,+ ),+ );+ } catch (cause: unknown) {+ if (cancelled(options.signal))+ return err(new AnalysisCancelledError(operation, { cause }));+ return err(failure(operation, cause));+ }+ }++ /**+ * Release everything this session owns. A failed close keeps reporting its+ * failure, and each later call retries the cleanup that remains.+ */+ async close(): Promise<Result<null, AnalysisError>> {+ if (this.#closed) return ok(null);+ if (!this.#closing) {+ this.#closing = true;+ this.#session.abort();+ }+ // Cancellation starts process shutdown; its completion proves whether it+ // is safe to remove private copies and exposes any retained cleanup owner.+ await Promise.allSettled(this.#requests);+ await this.#project;+ await this.#inventory;+ const failures: ProviderCleanupError[] = [];+ // Kuna runs in its own process group; an export no other session wants+ // must stop before this session reports itself closed.+ if (this.#key !== undefined) {+ const settled = await this.#cache.settled(this.#key);+ if (!settled.ok) failures.push(settled.error);+ }+ for (const retained of [...this.#retained]) {+ const stopped = await retained.owner?.stop();+ if (stopped !== undefined && stopped.status !== "incomplete")+ this.#retained.splice(this.#retained.indexOf(retained), 1);+ }+ failures.push(...this.#retained.map(({ error }) => error));+ const workspace = await this.#workspace;+ // A single-function run that may still be running keeps its copy.+ if (this.#retained.length === 0) {+ if (workspace?.ok === true) {+ this.#leakedRoots.push(workspace.value.root);+ this.#workspace = undefined;+ }+ for (const root of [...this.#leakedRoots])+ try {+ await root.close();+ this.#leakedRoots.splice(this.#leakedRoots.indexOf(root), 1);+ } catch (cause: unknown) {+ failures.push(+ new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ [root.path],+ { reason: message(cause) },+ { cause },+ ),+ );+ }+ }+ if (failures.length > 0)+ return err(+ new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ failures.flatMap((failed) => failed.cleanupResources),+ {+ reason: failures+ .map((failed) =>+ String(failed.diagnostics?.["reason"] ?? failed.message),+ )+ .join("; "),+ },+ ),+ );+ this.#releasePin?.();+ this.#releasePin = undefined;+ this.#closed = true;+ return ok(null);+ }++ #execution(+ operationLimitations: readonly string[],+ installation: KunaInstallation,+ answer: Answer,+ ): AnalysisExecution {+ const source = answer.source;+ const files =+ source?.kind !== "project-export"+ ? []+ : (answer.files ?? []).map((file) => ({+ facet: file.facet,+ file: file.path,+ file_sha256:+ Object.values(source.project.manifest.files).find(+ ({ path }) => path === file.path,+ )?.sha256 ?? null,+ byte_offset: file.byteOffset,+ byte_length: file.byteLength,+ }));+ // Preserve the direct text source shape; combined answers retain every+ // component once, including its producing file digest and byte range.+ const recordedFiles =+ files.length === 1 ? files[0] : files.length === 0 ? {} : { files };+ return createAnalysisExecution(+ answer.result,+ {+ id: KUNA_PROVIDER_ID,+ name: "Kuna",+ version: installation.version,+ },+ {+ // Kuna's identity is in the analysis profile; the raw result records+ // only where file-backed text came from.+ ...(source === null+ ? {}+ : {+ rawResult: {+ source:+ source.kind === "single-function"+ ? { kind: "single-function" }+ : {+ kind: "project-export",+ key: source.project.key,+ directory: source.project.directory,+ ...recordedFiles,+ },+ project_export: this.#exportState(),+ },+ }),+ limitations: [...operationLimitations, ...answer.limitations],+ locations: [+ { kind: "artifact-path", path: this.#target.path },+ ...answer.locations,+ ],+ ...(this.#profile === undefined+ ? {}+ : { analysisProfile: this.#profile }),+ },+ );+ }++ /** Where the background export stands, for callers deciding whether to wait. */+ #exportState(): JsonValue {+ if (this.#reader !== undefined)+ return { state: "ready", key: this.#reader.project.key };+ if (this.#project === undefined) return { state: "not-started" };+ if (this.#exportFailure !== undefined)+ return { state: "failed", reason: this.#exportFailure };+ return {+ state: "building",+ phase: this.#status?.phase ?? null,+ inventory_functions: this.#status?.inventoryFunctions ?? null,+ };+ }++ async #answer(+ operation: KunaOperation,+ parameters: Readonly<Record<string, JsonValue>>,+ installation: KunaInstallation,+ options: ExecutionOptions,+ ): Promise<Result<Answer, AnalysisError>> {+ if (operation === "list_documents")+ return ok({+ result: [this.#target.path],+ source: null,+ locations: [],+ limitations: [],+ });+ const inventory = await this.#ensureInventory(installation, options);+ if (!inventory.ok) return inventory;+ if (operation === "list_procedures" || operation === "search_procedures") {+ const items = inventory.value.map(({ address, name }) => ({+ address,+ value: name,+ }));+ let selected = items;+ if (operation === "search_procedures") {+ const query = analysisSearchQuerySchema.parse(parameters);+ if (query.mode === "regex") {+ const matches = await matchRegexValues({+ operation,+ pattern: query.pattern,+ caseSensitive: query.case_sensitive,+ values: items.map(({ value }) => value),+ signal: options.signal,+ });+ if (!matches.ok) return matches;+ const indices = new Set(matches.value);+ selected = items.filter((_, index) => indices.has(index));+ } else {+ const matches = analysisSearchPredicate(query);+ selected = items.filter(({ value }) => matches(value));+ }+ }+ return ok({+ result: selected,+ source: null,+ locations: [],+ limitations: [],+ });+ }+ if (operation === "address_name")+ return this.#addressName(+ parameters,+ inventory.value,+ installation,+ options,+ );+ const entry = this.#resolve(operation, parameters, inventory.value);+ if (!entry.ok) return entry;+ const locations = [+ { kind: "address", address: entry.value.address } as const,+ ];+ switch (operation) {+ case "procedure_address":+ return ok({+ result: entry.value.address,+ source: null,+ locations,+ limitations: [],+ });+ case "procedure_pseudo_code": {+ const pseudocode = await this.#pseudocode(+ operation,+ entry.value,+ installation,+ options,+ );+ if (!pseudocode.ok) return pseudocode;+ return ok({ ...pseudocode.value, locations });+ }+ case "procedure_assembly": {+ const assembly = await this.#assemblyText(+ operation,+ entry.value,+ installation,+ options,+ );+ if (!assembly.ok) return assembly;+ return ok({ ...assembly.value, locations });+ }+ case "analyze_function":+ return this.#withProject(operation, installation, options, (reader) =>+ this.#dossier(operation, entry.value, reader),+ );+ }+ }++ /** Resolve an exact inventory name, alias or entry address. */+ #resolve(+ operation: string,+ parameters: Readonly<Record<string, JsonValue>>,+ inventory: readonly KunaInventoryFunction[],+ ): Result<KunaInventoryFunction, AnalysisError> {+ const parsed = procedureSelectorSchema.safeParse(parameters.procedure);+ if (!parsed.success)+ return err(+ new AnalysisInputError(+ operation,+ { userMessage: "procedure is required." },+ [{ path: ["procedure"], reason: "missing_argument" }],+ ),+ );+ const selector = parsed.data;+ if (HEX_ADDRESS.test(selector)) {+ const address = `0x${BigInt(selector).toString(16)}`;+ const entry = this.#index(inventory).byAddress.get(address);+ return entry === undefined+ ? err(+ new AnalysisInputError(operation, {+ userMessage: `${address} is not a procedure entry Kuna found; list_procedures shows the entries it found.`,+ }),+ )+ : ok(entry);+ }+ const matches = this.#index(inventory).byName.get(selector) ?? [];+ if (matches.length === 1 && matches[0] !== undefined) return ok(matches[0]);+ return err(+ new AnalysisInputError(operation, {+ userMessage:+ matches.length === 0+ ? `Kuna found no procedure named ${selector}; search_procedures finds similar names.`+ : `${selector} names ${String(matches.length)} Kuna entries (${matches.map(({ address }) => address).join(", ")}); select one by address.`,+ }),+ );+ }++ async #addressName(+ parameters: Readonly<Record<string, JsonValue>>,+ inventory: readonly KunaInventoryFunction[],+ installation: KunaInstallation,+ options: ExecutionOptions,+ ): Promise<Result<Answer, AnalysisError>> {+ const raw = parameters.address;+ if (typeof raw !== "string" || !HEX_ADDRESS.test(raw))+ return err(+ new AnalysisInputError(+ "address_name",+ {+ userMessage:+ "Kuna has no cursor; pass an explicit 0x-prefixed address.",+ },+ [{ path: ["address"], reason: "invalid_format" }],+ ),+ );+ const address = `0x${BigInt(raw).toString(16)}`;+ const locations = [{ kind: "address", address } as const];+ const entry = this.#index(inventory).byAddress.get(address);+ if (entry !== undefined)+ return ok({+ result: entry.name,+ source: null,+ locations,+ limitations: [],+ });+ return this.#withProject(+ "address_name",+ installation,+ options,+ async (reader) => {+ const name = await reader.dataName(address, "address_name");+ if (!name.ok) return name;+ return ok({+ result: name.value,+ source: { kind: "project-export", project: reader.project },+ locations,+ limitations: [+ "Kuna names function entries and the data its export references; null means Kuna assigned no name at this address, not that no symbol exists.",+ ],+ });+ },+ );+ }++ async #pseudocode(+ operation: string,+ entry: KunaInventoryFunction,+ installation: KunaInstallation,+ options: ExecutionOptions,+ ): Promise<Result<Omit<Answer, "locations">, AnalysisError>> {+ for (let attempt = 0; this.#reader !== undefined; attempt += 1) {+ const reader = this.#reader;+ try {+ const text = await reader.pseudocode(entry.address, operation);+ if (!text.ok) return text;+ return ok({+ ...text.value,+ source: { kind: "project-export", project: reader.project },+ });+ } catch (cause: unknown) {+ if (!isMissing(cause) || attempt !== 0) throw cause;+ this.#invalidateProject(reader);+ await this.#startProject(installation);+ }+ }+ const workspace = await this.#ensureWorkspace();+ if (!workspace.ok) return workspace;+ const run = await runKunaCommand({+ installation,+ arguments: ["decompile", workspace.value.input, entry.address, "--addr"],+ workspace: workspace.value.root.path,+ operation,+ timeoutMs: installation.configuration.functionTimeoutMs,+ reportedTimeoutMs: installation.configuration.functionTimeoutMs,+ outputBytes: KUNA_FUNCTION_TEXT_BYTES,+ signal: options.signal ?? this.#session.signal,+ launcher: this.#launcher,+ });+ if (run.kind === "retained") {+ this.#retained.push({ error: run.error, owner: run.owner });+ return err(run.error);+ }+ if (run.kind === "failed") return err(run.error);+ const exportFailure = await this.#settledExportFailure();+ return ok({+ result: run.snapshot.stdout.text.replace(/\n+$/u, ""),+ source: { kind: "single-function" },+ limitations: [+ KUNA_SINGLE_FUNCTION_LIMITATION,+ ...(exportFailure === undefined+ ? []+ : [+ `The project export failed, so later requests also use single-function runs: ${exportFailure}`,+ ]),+ ],+ });+ }++ async #assemblyText(+ operation: string,+ entry: KunaInventoryFunction,+ installation: KunaInstallation,+ options: ExecutionOptions,+ ): Promise<Result<Omit<Answer, "locations">, AnalysisError>> {+ return this.#withProject(+ operation,+ installation,+ options,+ async (reader) => {+ const text = await reader.assembly(entry.address, operation);+ return text.ok+ ? ok({+ ...text.value,+ source: { kind: "project-export", project: reader.project },+ })+ : text;+ },+ );+ }++ async #dossier(+ operation: string,+ entry: KunaInventoryFunction,+ reader: KunaProjectReader,+ ): Promise<Result<Answer, AnalysisError>> {+ const assembly = await reader.assembly(entry.address, operation);+ if (!assembly.ok) return assembly;+ const pseudocode = await reader.pseudocode(entry.address, operation);+ if (!pseudocode.ok) return pseudocode;+ const text =+ typeof pseudocode.value.result === "string"+ ? pseudocode.value.result+ : null;+ const unavailable = (reason: string) =>+ ({ available: false, reason }) as const;+ const dossier = functionDossierSchema.parse({+ procedure: {+ address: entry.address,+ name: entry.name,+ classification: null,+ body: unavailable(+ "Kuna reports an inventory extent that is an upper bound, not observed body ranges.",+ ),+ signature: null,+ locals: [],+ },+ pseudocode: text ?? "",+ assembly:+ typeof assembly.value.result === "string"+ ? assembly.value.result.split("\n")+ : [],+ comments: [],+ callers: [],+ callees: [],+ incoming_references: [],+ outgoing_references: [],+ referenced_strings: [],+ referenced_names: [],+ basic_blocks: [],+ native_api: null,+ native_value_flow: null,+ facet_availability: {+ pseudocode:+ text === null+ ? unavailable(+ pseudocode.value.limitations.at(-1) ??+ "Kuna did not supply pseudocode.",+ )+ : { available: true },+ assembly: { available: true },+ comments: unavailable("Kuna exports no analyst comments."),+ callers: unavailable(+ "This provider does not report Kuna cross-references.",+ ),+ callees: unavailable(+ "This provider does not report Kuna cross-references.",+ ),+ references: unavailable(+ "This provider does not report typed references.",+ ),+ strings_names: unavailable(+ "This provider does not report function-referenced strings and names.",+ ),+ cfg: unavailable("Kuna exports no basic blocks."),+ },+ limitations: [+ ...kunaLimitations("analyze_function"),+ ...pseudocode.value.limitations,+ ],+ });+ return ok({+ result: dossier,+ source: { kind: "project-export", project: reader.project },+ files: [+ ...(pseudocode.value.files ?? []),+ ...(assembly.value.files ?? []),+ ],+ locations: [{ kind: "address", address: entry.address }],+ limitations: pseudocode.value.limitations,+ });+ }++ /** Address and name lookups over one inventory, built once. */+ #index(inventory: readonly KunaInventoryFunction[]): InventoryIndex {+ if (this.#inventoryIndex?.inventory === inventory)+ return this.#inventoryIndex;+ const byAddress = new Map<string, KunaInventoryFunction>();+ const byName = new Map<string, KunaInventoryFunction[]>();+ for (const entry of inventory) {+ byAddress.set(entry.address, entry);+ for (const name of new Set([entry.name, ...entry.aliases])) {+ const named = byName.get(name);+ if (named === undefined) byName.set(name, [entry]);+ else named.push(entry);+ }+ }+ this.#inventoryIndex = { inventory, byAddress, byName };+ return this.#inventoryIndex;+ }++ async #ensureInstallation(): Promise<+ Result<KunaInstallation, AnalysisError>+ > {+ this.#installation ??= inspectKunaInstallation(this.#environment).then(+ (inspected): Result<KunaInstallation, AnalysisError> => {+ if (!inspected.ok)+ return err(+ new AnalysisCapabilityUnavailableError(+ KUNA_PROVIDER_ID,+ "health",+ inspected.error.reason,+ { userMessage: inspected.error.reason },+ ),+ );+ const committed = this.#profile?.parameters["kuna_sha256"];+ if (committed !== undefined && committed !== inspected.value.sha256)+ return err(+ new ProviderAdapterError(KUNA_PROVIDER_ID, "health", {+ userMessage:+ "The Kuna executable changed after this target was opened; reopen the target to analyze it with the current executable.",+ diagnostics: {+ committed_sha256: committed,+ observed_sha256: inspected.value.sha256,+ },+ }),+ );+ return ok(inspected.value);+ },+ );+ return this.#installation;+ }++ /** Reuse a verified export, or start building one in the background. */+ async #startProject(installation: KunaInstallation): Promise<void> {+ if (this.#project !== undefined) return;+ const key = kunaProjectKey({+ targetSha256: this.#target.sha256,+ kunaSha256: installation.sha256,+ kunaVersion: installation.version,+ jobs: installation.configuration.jobs,+ });+ this.#key = key;+ const cached = await this.#cache.lookup(key, this.#session.signal);+ if (cached !== undefined) {+ this.#adopt(cached);+ this.#project = Promise.resolve(ok(cached));+ return;+ }+ this.#project = this.#cache+ .build({+ installation,+ targetPath: this.#target.path,+ targetSha256: this.#target.sha256,+ signal: this.#session.signal,+ onStatus: (status) => {+ this.#status = status;+ },+ })+ .then((result) => {+ if (result.ok && !this.#closing) this.#adopt(result.value);+ else if (!result.ok && !this.#closing)+ this.#exportFailure =+ result.error.userMessage ?? result.error.message;+ return result;+ });+ }++ /** Retry the complete read when its immutable project disappears, never just one facet. */+ async #withProject<T>(+ operation: string,+ installation: KunaInstallation,+ options: ExecutionOptions,+ read: (reader: KunaProjectReader) => Promise<Result<T, AnalysisError>>,+ ): Promise<Result<T, AnalysisError>> {+ for (let attempt = 0; ; attempt += 1) {+ const reader = await this.#awaitProject(operation, options);+ if (!reader.ok) return reader;+ try {+ return await read(reader.value);+ } catch (cause: unknown) {+ if (!isMissing(cause) || attempt !== 0) throw cause;+ this.#invalidateProject(reader.value);+ await this.#startProject(installation);+ }+ }+ }++ #invalidateProject(reader: KunaProjectReader): void {+ // Another request may already have replaced this reader and its build.+ if (this.#reader !== reader) return;+ this.#releasePin?.();+ this.#releasePin = undefined;+ this.#reader = undefined;+ this.#project = undefined;+ this.#status = undefined;+ this.#exportFailure = undefined;+ }++ #adopt(project: KunaProject): void {+ this.#reader = this.#readerFor(project);+ this.#releasePin ??= this.#cache.pin(project.key);+ }++ #readerFor(project: KunaProject): KunaProjectReader {+ return this.#reader?.project === project+ ? this.#reader+ : new KunaProjectReader(project);+ }++ /** The export's failure once it has settled; undefined while it builds or after success. */+ async #settledExportFailure(): Promise<string | undefined> {+ const settled = await Promise.race([+ this.#project,+ Promise.resolve(undefined),+ ]);+ if (settled === undefined || settled.ok) return undefined;+ return settled.error.userMessage ?? settled.error.message;+ }++ /** Wait for the export, reporting progress, without cancelling it for other callers. */+ async #awaitProject(+ operation: string,+ options: ExecutionOptions,+ ): Promise<Result<KunaProjectReader, AnalysisError>> {+ if (this.#reader !== undefined) return ok(this.#reader);+ const project = this.#project;+ if (project === undefined)+ return err(+ new ProviderAdapterError(KUNA_PROVIDER_ID, operation, {+ userMessage: "The Kuna project export was never started.",+ }),+ );+ const started = Date.now();+ const progress = options.progress;+ // Report waiting only; Kuna exposes no measure of completed export work.+ const timer = setInterval(() => {+ void progress+ ?.report({+ phase: "kuna_export",+ completed: 0,+ total: null,+ message: `Waiting for Kuna's project export (${this.#status?.phase ?? "starting"}, ${String(Math.floor((Date.now() - started) / 1000))}s elapsed); it serves this request and every later one`,+ })+ .catch(() => undefined);+ }, WAIT_PROGRESS_INTERVAL_MS);+ try {+ const built = await waitFor(project, options.signal, operation);+ if (!built.ok) return built;+ return ok(this.#readerFor(built.value));+ } finally {+ clearInterval(timer);+ }+ }++ /** The export's inventory when ready, otherwise one quick `kuna functions` run. */+ async #ensureInventory(+ installation: KunaInstallation,+ options: ExecutionOptions,+ ): Promise<Result<readonly KunaInventoryFunction[], AnalysisError>> {+ if (this.#reader !== undefined) return ok(this.#reader.project.inventory);+ if (this.#inventory === undefined) {+ // The session owns the shared run; each caller only stops waiting.+ const run = this.#listInventory(installation);+ this.#inventory = run;+ void run.then((listed) => {+ // A failed quick listing is retried by the next request.+ if (!listed.ok && this.#inventory === run) this.#inventory = undefined;+ });+ }+ return waitFor(this.#inventory, options.signal, "list_procedures");+ }++ async #listInventory(+ installation: KunaInstallation,+ ): Promise<Result<readonly KunaInventoryFunction[], AnalysisError>> {+ const workspace = await this.#ensureWorkspace();+ if (!workspace.ok) return workspace;+ const run = await runKunaCommand({+ installation,+ arguments: ["functions", workspace.value.input, "--json"],+ workspace: workspace.value.root.path,+ operation: "list_procedures",+ timeoutMs: installation.configuration.functionTimeoutMs,+ reportedTimeoutMs: installation.configuration.functionTimeoutMs,+ outputBytes: KUNA_INVENTORY_OUTPUT_BYTES,+ signal: this.#session.signal,+ launcher: this.#launcher,+ });+ if (run.kind === "retained") {+ this.#retained.push({ error: run.error, owner: run.owner });+ return err(run.error);+ }+ if (run.kind === "failed") return err(run.error);+ const inventory = parseKunaInventory(run.snapshot.stdout.text);+ return inventory.ok+ ? ok(inventory.value)+ : err(+ new ProviderAdapterError(KUNA_PROVIDER_ID, "list_procedures", {+ userMessage: `Kuna's function inventory is not usable: ${inventory.error}`,+ }),+ );+ }++ /** A private, digest-verified copy of the target for single-function runs. */+ async #ensureWorkspace(): Promise<+ Result<+ { readonly root: PrivateRuntimeRoot; readonly input: string },+ AnalysisError+ >+ > {+ this.#workspace ??= (async () => {+ const root = await PrivateRuntimeRoot.create({ prefix: "rea-kuna-" });+ try {+ const input = join(root.path, basename(this.#target.path));+ const digest = await copyAndHash(+ this.#target.path,+ input,+ this.#session.signal,+ );+ if (digest !== this.#target.sha256) {+ await this.#release(root);+ return err(+ new AnalysisArtifactChangedError(+ "kuna:workspace",+ this.#target.path,+ "the target no longer matches the digest selected for analysis",+ ),+ );+ }+ await prepareProcessOwnershipInspection(this.#session.signal);+ return ok({ root, input });+ } catch (cause: unknown) {+ await this.#release(root);+ throw cause;+ }+ })().catch((cause: unknown) => err(failure("kuna:workspace", cause)));+ const workspace = await this.#workspace;+ if (!workspace.ok) this.#workspace = undefined;+ return workspace;+ }++ /** Remove a private root, keeping it for close to retry when removal fails. */+ async #release(root: PrivateRuntimeRoot): Promise<void> {+ try {+ await root.close();+ } catch {+ this.#leakedRoots.push(root);+ }+ }+}diff --git a/src/process/RegexMatcher.ts b/src/process/RegexMatcher.tsnew file mode 100644index 000000000..215c4bdfb--- /dev/null+++ b/src/process/RegexMatcher.ts@@ -0,0 +1,176 @@+import { Worker } from "node:worker_threads";++import { z } from "zod";++import type { AnalysisError } from "../domain/analysisErrorBase.js";+import {+ AnalysisCancelledError,+ AnalysisInputError,+ AnalysisOutputError,+ AnalysisResourceConstraintError,+} from "../domain/analysisErrorCore.js";+import { err, ok, type Result } from "../domain/result.js";++const MATCHING_DEADLINE_MS = 5_000;+const WORKER_HEAP_MIB = 128;+/** Shared capability text for the supervised ECMAScript matching boundary. */+export const REGEX_MATCHING_LIMITATION = `Regex mode uses ECMAScript Unicode semantics in a cancellable worker with a ${String(MATCHING_DEADLINE_MS / 1000)}-second matching deadline; matching failure leaves the service available.`;+const replySchema = z.discriminatedUnion("status", [+ z.strictObject({+ status: z.literal("matched"),+ indices: z.array(z.number().int().nonnegative()),+ }),+ z.strictObject({ status: z.literal("invalid_pattern"), reason: z.string() }),+]);++// Code is constant; caller patterns and target strings cross only workerData.+const WORKER_SOURCE = String.raw`+(async () => {+const { parentPort, workerData } = await import("node:worker_threads");+let expression;+try {+ expression = new RegExp(workerData.pattern, workerData.caseSensitive ? "u" : "iu");+} catch (cause) {+ parentPort.postMessage({ status: "invalid_pattern", reason: cause instanceof Error ? cause.message : String(cause) });+}+if (expression !== undefined) {+ const indices = [];+ for (const [index, value] of workerData.values.entries())+ if (expression.test(value)) indices.push(index);+ parentPort.postMessage({ status: "matched", indices });+}+})();+`;++/** Match an inventory off the service thread, and prove worker exit before returning. */+export const matchRegexValues = async (input: {+ readonly operation: string;+ readonly pattern: string;+ readonly caseSensitive: boolean;+ readonly values: readonly string[];+ readonly signal?: AbortSignal | undefined;+ readonly invalidPattern?: (reason: string) => AnalysisError;+}): Promise<Result<readonly number[], AnalysisError>> => {+ if (input.signal?.aborted)+ return err(new AnalysisCancelledError(input.operation));+ let worker: Worker;+ try {+ worker = new Worker(WORKER_SOURCE, {+ eval: true,+ workerData: {+ pattern: input.pattern,+ caseSensitive: input.caseSensitive,+ values: input.values,+ },+ resourceLimits: { maxOldGenerationSizeMb: WORKER_HEAP_MIB },+ });+ } catch (cause: unknown) {+ return err(+ new AnalysisOutputError(input.operation, "Cannot start regex worker", {+ cause,+ }),+ );+ }+ try {+ return await new Promise((resolve) => {+ let settled = false;+ const finish = (result: Result<readonly number[], AnalysisError>) => {+ if (settled) return;+ settled = true;+ clearTimeout(timer);+ input.signal?.removeEventListener("abort", onAbort);+ resolve(result);+ };+ const onAbort = () =>+ finish(err(new AnalysisCancelledError(input.operation)));+ const timer = setTimeout(+ () =>+ finish(+ err(+ new AnalysisResourceConstraintError(+ input.operation,+ "cpu",+ "Regex matching exceeded its supervised deadline; the service remains available.",+ { matching_deadline_ms: MATCHING_DEADLINE_MS },+ {+ remediationAction:+ "Simplify the ECMAScript Unicode regex or use literal mode, then retry in the same session.",+ },+ ),+ ),+ ),+ MATCHING_DEADLINE_MS,+ );+ input.signal?.addEventListener("abort", onAbort, { once: true });+ if (input.signal?.aborted) onAbort();+ worker.once("message", (message: unknown) => {+ const reply = replySchema.safeParse(message);+ if (!reply.success)+ return finish(+ err(+ new AnalysisOutputError(+ input.operation,+ "Regex worker reply is malformed",+ ),+ ),+ );+ if (reply.data.status === "invalid_pattern")+ return finish(+ err(+ input.invalidPattern?.(reply.data.reason) ??+ new AnalysisInputError(input.operation, {+ userMessage: `Invalid regex pattern: ${reply.data.reason}`,+ }),+ ),+ );+ if (+ reply.data.indices.some(+ (index, position, indices) =>+ index >= input.values.length ||+ (position > 0 && index <= (indices[position - 1] ?? -1)),+ )+ )+ return finish(+ err(+ new AnalysisOutputError(+ input.operation,+ "Regex worker returned invalid inventory indices",+ ),+ ),+ );+ finish(ok(reply.data.indices));+ });+ worker.once("error", (cause: Error & { code?: string }) =>+ finish(+ err(+ cause.code === "ERR_WORKER_OUT_OF_MEMORY"+ ? new AnalysisResourceConstraintError(+ input.operation,+ "memory",+ "Regex worker exhausted its heap budget",+ { worker_heap_mib: WORKER_HEAP_MIB },+ { cause },+ )+ : new AnalysisOutputError(+ input.operation,+ `Regex worker failed: ${cause.message}`,+ { cause },+ ),+ ),+ ),+ );+ worker.once("exit", (code) =>+ finish(+ err(+ new AnalysisOutputError(+ input.operation,+ `Regex worker exited without a result (${String(code)})`,+ ),+ ),+ ),+ );+ });+ } finally {+ await worker.terminate();+ }+};diff --git a/tests/boundary/filesystem/directAnalysisPermissions.test.ts b/tests/boundary/filesystem/directAnalysisPermissions.test.tsindex 26e308c44..e9e183828 100644--- a/tests/boundary/filesystem/directAnalysisPermissions.test.ts+++ b/tests/boundary/filesystem/directAnalysisPermissions.test.ts@@ -50,7 +50,7 @@ describe("direct analysis snapshot files", () => {details: {selection_reason: "unknown_provider",requested_provider_id: "request-provider",- candidate_ids: ["ghidra", "hopper", "ida"],+ candidate_ids: ["ghidra", "hopper", "ida", "kuna"],},});});diff --git a/tests/boundary/process/regexMatcher.test.ts b/tests/boundary/process/regexMatcher.test.tsnew file mode 100644index 000000000..0666faf15--- /dev/null+++ b/tests/boundary/process/regexMatcher.test.ts@@ -0,0 +1,50 @@+import { expect, it } from "vitest";++import { ok } from "../../../src/domain/result.js";+import { HopperRegexSearch } from "../../../src/hopper/HopperRegexSearch.js";+import { matchRegexValues } from "../../../src/process/RegexMatcher.js";++it("preserves Unicode matching order and refuses a pre-cancelled match", async () => {+ expect(+ await matchRegexValues({+ operation: "search_procedures",+ pattern: "^δ",+ caseSensitive: false,+ values: ["Δelta", "delta", "δίκη"],+ }),+ ).toEqual(ok([0, 2]));+ expect(+ await matchRegexValues({+ operation: "search_procedures",+ pattern: ".",+ caseSensitive: true,+ values: ["value"],+ signal: AbortSignal.abort(),+ }),+ ).toMatchObject({ ok: false, error: { _tag: "AnalysisCancelledError" } });+});++it("keeps Hopper's result projection and invalid-pattern contract with the shared worker", async () => {+ const search = new HopperRegexSearch({+ callTool: async () =>+ ok([+ { address: "0x10", value: "Δelta" },+ { address: "0x20", value: "other" },+ ]),+ });+ expect(+ await search.execute("search_strings", { pattern: "^δ", mode: "regex" }),+ ).toEqual(ok([{ address: "0x10", value: "Δelta" }]));+ expect(+ await search.execute("search_strings", { pattern: "[", mode: "regex" }),+ ).toMatchObject({+ ok: false,+ error: {+ _tag: "HopperRemoteError",+ code: -32000,+ diagnosticType: "invalid_request",+ operation: "search_strings",+ },+ });+ await search.close();+});diff --git a/tests/boundary/providers/kuna/fakeKuna.ts b/tests/boundary/providers/kuna/fakeKuna.tsindex 24c04b1a9..0195cb9d3 100644--- a/tests/boundary/providers/kuna/fakeKuna.ts+++ b/tests/boundary/providers/kuna/fakeKuna.ts@@ -26,6 +26,11 @@ export interface FakeKunaBehavior {readonly functions?: readonly FakeKunaFunction[];/** Extra `.asm` bytes, for capacity tests. */readonly asmPadding?: number;+ /** Extra C comment bytes inside each exported body, for buffered-read capacity. */+ readonly cPadding?: number;+ readonly decompile?: "ok" | "hang";+ /** Milliseconds `functions --json` takes before printing. */+ readonly inventoryDelayMs?: number;/** Milliseconds the export takes before writing its files. */readonly delayMs?: number;}@@ -55,7 +60,7 @@ if (args[0] === "--version") {else if (mode === "not-json") process.stdout.write("functions: 2\n");else {const listed = [...functions, { name: "puts", addr: "0x2000" }].map((fn) => ({ name: fn.name, address: parseInt(fn.addr, 16), address_hex: fn.addr, aliases: [], object_location: null, size: fn.name === "puts" ? 0 : 16 }));- process.stdout.write(JSON.stringify({ binary: args[1], count: listed.length, total: listed.length, error: null, functions: listed }, null, 2) + "\n");+ setTimeout(() => process.stdout.write(JSON.stringify({ binary: args[1], count: listed.length, total: listed.length, error: null, functions: listed }, null, 2) + "\n"), behavior.inventoryDelayMs ?? 0);}} else if (args[0] === "decompile-project") {const input = args[1];@@ -69,12 +74,15 @@ if (args[0] === "--version") {let c = '#include "' + stem + '.h"\n\n';functions.forEach((fn, index) => {c += fn.error === undefined- ? "// Function: " + fn.name + " @ " + fn.addr + "\nint " + fn.name + "(void)\n{\n return " + index + ";\n}\n\n"+ ? "// Function: " + fn.name + " @ " + fn.addr + "\nint " + fn.name + "(void)\n{\n return " + index + ";\n" + (behavior.cPadding ? " /*" + "x".repeat(behavior.cPadding) + "*/\n" : "") + "}\n\n": "// Function: " + fn.name + " @ " + fn.addr + " (error: " + fn.error + ")\n\n";});fs.writeFileSync(path.join(output, stem + ".c"), c);fs.writeFileSync(path.join(output, stem + ".h"), "#pragma once\n");- fs.writeFileSync(path.join(output, stem + ".asm"), "; asm\n" + "x".repeat(behavior.asmPadding ?? 0));+ let asm = "; kuna decompile-project — " + stem + "\n\n; --- code section 0x1000..0x2000 ---\n\n";+ functions.forEach((fn) => { asm += fn.name + ": ; " + fn.addr + "\n " + fn.addr.slice(2).padStart(8, "0") + ": c3 RET\n\n"; });+ asm += "; --- data ---\n\ndat_3000: ; 0x3000 = dat_3000\n 00003000: 00\n\ng_table: ; 0x3010\n 00003010: 01\n" + "x".repeat(behavior.asmPadding ?? 0);+ fs.writeFileSync(path.join(output, stem + ".asm"), asm);fs.writeFileSync(path.join(output, "README.md"), "# " + stem + "\n");// Occupy the manifest path so REA's publication write fails.if (mode === "block-manifest") fs.mkdirSync(path.join(output, "..", "manifest.json"));@@ -82,6 +90,12 @@ if (args[0] === "--version") {const reported = mode === "miscounted" ? functions.length + 1 : functions.length - failed;if (mode !== "silent") process.stdout.write("wrote " + output + ": " + stem + ".c (" + c.length + " bytes); functions: " + reported + " ok, " + failed + " failed\n");}, behavior.delayMs ?? 0);+} else if (args[0] === "decompile") {+ // decompile <input> <0xaddr> --addr: the single-function path.+ const fn = functions.find((candidate) => candidate.addr === args[2]);+ if (behavior.decompile === "hang") hang();+ else if (fn === undefined) { process.stderr.write("error: no function at " + args[2] + "\n"); process.exit(1); }+ else process.stdout.write("int " + fn.name + "(void) // single-function\n{\n return 0;\n}\n");} else {process.stderr.write("unexpected command\n");process.exit(2);diff --git a/tests/boundary/providers/kuna/kunaInstallation.test.ts b/tests/boundary/providers/kuna/kunaInstallation.test.tsindex 13b98bcba..51bc52450 100644--- a/tests/boundary/providers/kuna/kunaInstallation.test.ts+++ b/tests/boundary/providers/kuna/kunaInstallation.test.ts@@ -145,6 +145,7 @@ it("parses cache, timeout and job settings at the configuration boundary", () =>cacheRoot: "/home/analyst/.cache/rea/kuna",cacheMaxBytes: 4 * 1024 ** 3,projectTimeoutMs: 1_800_000,+ functionTimeoutMs: 120_000,// Kuna's reference answer is a serial export; more jobs change results.jobs: 1,},@@ -164,18 +165,25 @@ it("parses cache, timeout and job settings at the configuration boundary", () =>...environment,REA_KUNA_CACHE_MAX_BYTES: "2097152",REA_KUNA_PROJECT_TIMEOUT_MS: "60000",+ REA_KUNA_TIMEOUT_MS: "5000",REA_KUNA_JOBS: "3",},"linux",),).toMatchObject({- value: { cacheMaxBytes: 2097152, projectTimeoutMs: 60000, jobs: 3 },+ value: {+ cacheMaxBytes: 2097152,+ projectTimeoutMs: 60000,+ functionTimeoutMs: 5000,+ jobs: 3,+ },});for (const [setting, value] of [["REA_KUNA_CACHE_DIR", "relative/cache"],["REA_KUNA_CACHE_MAX_BYTES", "1024"],["REA_KUNA_CACHE_MAX_BYTES", "4GiB"],["REA_KUNA_PROJECT_TIMEOUT_MS", "0"],+ ["REA_KUNA_TIMEOUT_MS", "-1"],["REA_KUNA_JOBS", "33"],["REA_KUNA_JOBS", "0"],] as const)diff --git a/tests/boundary/providers/kuna/kunaProjectFiles.test.ts b/tests/boundary/providers/kuna/kunaProjectFiles.test.tsindex b39dbb574..9c173b9ac 100644--- a/tests/boundary/providers/kuna/kunaProjectFiles.test.ts+++ b/tests/boundary/providers/kuna/kunaProjectFiles.test.ts@@ -3,6 +3,7 @@ import { expect, it } from "vitest";import {parseKunaExportSummary,parseKunaInventory,+ scanKunaAssembly,scanKunaProjectSource,} from "../../../../src/kuna/KunaProjectFiles.js";@@ -162,3 +163,45 @@ it("reads the callable inventory, ignoring fields a later release adds", () => {parseKunaInventory(JSON.stringify({ functions: [{ name: "x" }] })),).toMatchObject({ ok: false });});++it("indexes code listings and data labels in Kuna's .asm", async () => {+ const asm = [+ "; kuna decompile-project — a.out",+ "; arch: x86:LE:64:default:gcc",+ "",+ "; --- code section 0x1000..0x1020 ---",+ "",+ "main: ; 0x1000",+ "; arg: param_1 (int)",+ " 00001000: c3 RET",+ "",+ "operator new(unsigned long): ; 0x1010",+ " 00001010: c3 RET",+ "",+ "; --- data ---",+ "",+ "dat_3000: ; 0x3000 = dat_3000",+ " 00003000: 00",+ "",+ "",+ ].join("\n");+ const scanned = await scanKunaAssembly(chunked(asm, 5));+ if (!scanned.ok) throw new Error(scanned.error);+ const main = scanned.value.code.get("0x1000");+ // Offsets are bytes; the header's em dash is three of them.+ expect(+ Buffer.from(asm)+ .subarray(main?.offset, (main?.offset ?? 0) + (main?.length ?? 0))+ .toString(),+ ).toBe(+ "main: ; 0x1000\n; arg: param_1 (int)\n 00001000: c3 RET\n\n",+ );+ expect(scanned.value.code.get("0x1010")?.name).toBe(+ "operator new(unsigned long)",+ );+ expect([...scanned.value.code.keys()]).toEqual(["0x1000", "0x1010"]);+ expect([...scanned.value.data]).toEqual([["0x3000", "dat_3000"]]);+ expect(+ await scanKunaAssembly(chunked("a: ; 0x10\n\nb: ; 0x10\n", 64)),+ ).toEqual({ ok: false, error: "the .asm repeats code address 0x10" });+});diff --git a/tests/boundary/providers/kuna/kunaProjectReaderConcurrency.test.ts b/tests/boundary/providers/kuna/kunaProjectReaderConcurrency.test.tsnew file mode 100644index 000000000..f7743c15c--- /dev/null+++ b/tests/boundary/providers/kuna/kunaProjectReaderConcurrency.test.ts@@ -0,0 +1,132 @@+import { readdir, rename } from "node:fs/promises";+import { join } from "node:path";++import { afterEach, expect, it as test, vi } from "vitest";++import { spawnOwnedProviderProcess } from "../../../../src/process/ProviderProcess.js";+import { run, session } from "./kunaSessionFixture.js";++const reading = vi.hoisted(() => ({+ asm: "",+ c: "",+ held: false,+ gate: undefined as Promise<void> | undefined,+ missing: 0,+ onMissing: undefined as (() => void) | undefined,+}));++vi.mock("node:fs/promises", async (importOriginal) => {+ const actual = await importOriginal<typeof import("node:fs/promises")>();+ return {+ ...actual,+ open: async (...args: Parameters<typeof actual.open>) => {+ try {+ const handle = await actual.open(...args);+ if (String(args[0]) !== reading.asm || reading.held) return handle;+ return new Proxy(handle, {+ get(target, key) {+ if (key === "read")+ return async (...readArgs: unknown[]) => {+ const result: unknown = await Reflect.apply(+ target.read,+ target,+ readArgs,+ );+ reading.held = true;+ await reading.gate;+ return result;+ };+ const value: unknown = Reflect.get(target, key, target);+ return typeof value === "function" ? value.bind(target) : value;+ },+ });+ } catch (cause: unknown) {+ if (String(args[0]) === reading.c) {+ reading.missing += 1;+ if (reading.missing === 2) reading.onMissing?.();+ }+ throw cause;+ }+ },+ };+});++afterEach(() => {+ reading.asm = "";+ reading.c = "";+ reading.held = false;+ reading.gate = undefined;+ reading.missing = 0;+ reading.onMissing = undefined;+});++const barrier = () => {+ let release = () => {};+ const promise = new Promise<void>((resolve) => {+ release = resolve;+ });+ return { promise, release };+};++test.skipIf(process.platform === "win32")(+ "retries the whole dossier when another read loses its project",+ async () => {+ const assembly = barrier();+ const rebuild = barrier();+ const missing = barrier();+ let exports = 0;+ const { cacheRoot, open } = await session(+ "rea-kuna-reader-eviction-",+ {},+ {},+ async (options) => {+ if (options.arguments[0] === "decompile-project" && ++exports === 2)+ await rebuild.promise;+ return spawnOwnedProviderProcess(options);+ },+ );+ const client = open();+ let dossier: ReturnType<typeof run> | undefined;+ try {+ await run(client, "procedure_assembly", { procedure: "main" });+ const [key] = await readdir(join(cacheRoot, "projects"));+ const project = join(cacheRoot, "projects", key ?? "");+ reading.asm = join(project, "project", "program.asm");+ reading.c = join(project, "project", "program.c");+ reading.gate = assembly.promise;+ reading.onMissing = missing.release;+ dossier = run(client, "analyze_function", { procedure: "main" });+ await expect.poll(() => reading.held).toBe(true);+ await rename(project, join(cacheRoot, "trash", "evicted-elsewhere"));++ const fallback = await run(client, "procedure_pseudo_code", {+ procedure: "parse",+ });+ expect(fallback.rawResult).toMatchObject({+ source: { kind: "single-function" },+ });+ await expect.poll(() => exports).toBe(2);+ assembly.release();+ // The fixed reader attempts the missing C before retrying the entire+ // report. The old reader instead completes with a single-function source.+ await Promise.race([dossier, missing.promise]);+ rebuild.release();+ const result = await dossier;+ expect(result.rawResult).toMatchObject({+ source: {+ kind: "project-export",+ files: [{ facet: "pseudocode" }, { facet: "assembly" }],+ },+ });+ expect(result.result).toMatchObject({+ pseudocode: "int main(void)\n{\n return 0;\n}",+ assembly: ["main: ; 0x1000", " 00001000: c3 RET"],+ });+ } finally {+ assembly.release();+ rebuild.release();+ await dossier?.catch(() => undefined);+ expect(await client.close()).toEqual({ ok: true, value: null });+ }+ },+);diff --git a/tests/boundary/providers/kuna/kunaProvider.test.ts b/tests/boundary/providers/kuna/kunaProvider.test.tsnew file mode 100644index 000000000..9c27530c2--- /dev/null+++ b/tests/boundary/providers/kuna/kunaProvider.test.ts@@ -0,0 +1,787 @@+import { createHash } from "node:crypto";+import {+ appendFile,+ chmod,+ mkdir,+ readdir,+ readFile,+ rename,+ writeFile,+} from "node:fs/promises";+import { join } from "node:path";++import { expect, it as test } from "vitest";++import type { BinaryTarget } from "../../../../src/domain/binaryTargetTypes.js";+import type { JsonValue } from "../../../../src/domain/jsonValue.js";+import type { KunaProcessLauncher } from "../../../../src/kuna/KunaCommand.js";+import { KunaProvider } from "../../../../src/kuna/KunaProvider.js";+import { KUNA_FUNCTION_TEXT_BYTES } from "../../../../src/kuna/KunaLimits.js";+import { cleanupOwnedProcessGroup } from "../../../../src/process/ProcessOwnership.js";+import { spawnOwnedProviderProcess } from "../../../../src/process/ProviderProcess.js";+import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js";+import {+ fakeKunaCalls,+ setFakeKunaBehavior,+ writeFakeKuna,+} from "./fakeKuna.js";++import { session, run, exportsOf, FUNCTIONS } from "./kunaSessionFixture.js";++const it = test.skipIf(process.platform === "win32");++it("discovers configuration without probing and admits only verified targets", async () => {+ const root = await createTestTempDirectory("rea-kuna-discovery-");+ const kuna = await writeFakeKuna(root);+ const configured = new KunaProvider({ REA_KUNA_COMMAND: kuna });++ expect(new KunaProvider({}).inspectAvailability()).toMatchObject({+ status: "unavailable",+ code: "not_configured",+ });+ expect(+ new KunaProvider({+ REA_KUNA_COMMAND: join(root, "absent"),+ }).inspectAvailability(),+ ).toMatchObject({ status: "unavailable", code: "executable_missing" });+ expect(configured.inspectAvailability()).toMatchObject({+ status: "available",+ diagnostics: { version_probed: false },+ });+ expect(await fakeKunaCalls(kuna)).toEqual([]);+ expect(+ configured+ .capabilities()+ .every(+ ({ available, cachePolicy }) => available && cachePolicy === "live",+ ),+ ).toBe(true);++ const executable = (+ format: "elf" | "mach-o" | "pe" | "mach-o-universal",+ architecture: "x86_64" | "arm64" | "arm" | "x86",+ ) =>+ ({+ path: "/tmp/fixture",+ sha256: "a".repeat(64),+ kind: "executable",+ format,+ architecture,+ availableArchitectures: [architecture],+ }) as unknown as BinaryTarget;+ expect(+ configured.inspectTargetSupport(executable("elf", "x86_64")).status,+ ).toBe("supported");+ expect(+ configured.inspectTargetSupport(executable("mach-o", "arm64")).status,+ ).toBe("supported");+ expect(+ configured.inspectTargetSupport(executable("pe", "x86_64")),+ ).toMatchObject({ status: "unsupported", code: "target_format_unsupported" });+ expect(+ configured.inspectTargetSupport(executable("mach-o-universal", "arm64")),+ ).toMatchObject({ code: "target_format_unsupported" });+ expect(+ configured.inspectTargetSupport(executable("elf", "x86")),+ ).toMatchObject({+ code: "architecture_unsupported",+ });+});++it("commits the observed Kuna release and digest to the analysis profile", async () => {+ const { profile } = await session("rea-kuna-profile-");++ expect(profile).toMatchObject({+ provider: { id: "kuna", name: "Kuna", version: "1.833" },+ parameters: {+ kuna_version: "1.833",+ kuna_sha256: expect.stringMatching(/^[0-9a-f]{64}$/u),+ verified_release: true,+ jobs: 1,+ cache_policy: "live",+ },+ });+});++it("lists the selected document without starting target analysis", async () => {+ const { kuna, target, cacheRoot, open } = await session(+ "rea-kuna-document-metadata-",+ { project: "hang" },+ );+ const client = open();+ try {+ expect((await run(client, "list_documents")).result).toEqual([target.path]);+ expect(+ (await fakeKunaCalls(kuna)).every(({ argv }) => argv[0] === "--version"),+ ).toBe(true);+ await expect(readdir(cacheRoot)).rejects.toMatchObject({ code: "ENOENT" });+ } finally {+ await client.close();+ }+});++it("answers a cold request from one function, then serves the finished export", async () => {+ const { kuna, cacheRoot, open } = await session("rea-kuna-cold-", {+ delayMs: 300,+ });+ const client = open();++ const cold = await run(client, "procedure_pseudo_code", {+ procedure: "main",+ });+ expect(cold.result).toBe(+ "int main(void) // single-function\n{\n return 0;\n}",+ );+ expect(cold.rawResult).toMatchObject({+ source: { kind: "single-function" },+ project_export: { state: "building" },+ });+ expect(cold.limitations.at(-1)).toContain("single-function `kuna decompile`");++ // Assembly waits for the export, which then serves every later request.+ const assembly = await run(client, "procedure_assembly", {+ procedure: "0x1000",+ });+ expect(assembly.result).toBe("main: ; 0x1000\n 00001000: c3 RET");+ const warm = await run(client, "procedure_pseudo_code", {+ procedure: "main",+ });+ expect(warm.result).toBe("int main(void)\n{\n return 0;\n}");+ expect(warm.rawResult).toMatchObject({+ source: {+ kind: "project-export",+ directory: expect.stringContaining(join(cacheRoot, "projects")),+ file: "program.c",+ file_sha256: expect.stringMatching(/^[0-9a-f]{64}$/u),+ },+ project_export: { state: "ready" },+ });+ // The recorded span is exactly the function's block in the cached .c.+ const source = warm.rawResult as {+ source: { directory: string; byte_offset: number; byte_length: number };+ };+ const c = await readFile(join(source.source.directory, "program.c"));+ expect(+ c+ .subarray(+ source.source.byte_offset,+ source.source.byte_offset + source.source.byte_length,+ )+ .toString(),+ ).toBe("// Function: main @ 0x1000\nint main(void)\n{\n return 0;\n}\n\n");+ expect(await exportsOf(kuna)).toHaveLength(1);+ expect(await client.close()).toEqual({ ok: true, value: null });++ // A new session over a warm cache never takes the single-function path.+ const again = open();+ expect(+ await run(again, "procedure_pseudo_code", { procedure: "parse" }),+ ).toMatchObject({+ result: "int parse(void)\n{\n return 1;\n}",+ rawResult: { source: { kind: "project-export" } },+ });+ expect(+ (await fakeKunaCalls(kuna)).filter(({ argv }) => argv[0] === "decompile"),+ ).toHaveLength(1);+ await again.close();+});++it("lists, searches and resolves procedures from Kuna's inventory", async () => {+ const { open } = await session("rea-kuna-inventory-");+ const client = open();++ expect((await run(client, "list_procedures")).result).toEqual([+ { address: "0x1000", value: "main" },+ { address: "0x1040", value: "parse" },+ { address: "0x1080", value: "broken" },+ { address: "0x2000", value: "puts" },+ ]);+ expect(+ (await run(client, "search_procedures", { pattern: "^p", mode: "regex" }))+ .result,+ ).toEqual([+ { address: "0x1040", value: "parse" },+ { address: "0x2000", value: "puts" },+ ]);+ expect(+ (await run(client, "procedure_address", { procedure: "0X1040" })).result,+ ).toBe("0x1040");+ for (const procedure of ["missing", "0x1044"])+ expect(+ await client.execute("procedure_address", { procedure }),+ ).toMatchObject({ ok: false, error: { _tag: "AnalysisInputError" } });+ await client.close();+});++it("rejects a name that identifies several entries", async () => {+ const { open } = await session("rea-kuna-ambiguous-", {+ functions: [+ { name: "init", addr: "0x1000" },+ { name: "init", addr: "0x1040" },+ ],+ });+ const client = open();++ expect(+ await client.execute("procedure_address", { procedure: "init" }),+ ).toMatchObject({+ ok: false,+ error: {+ _tag: "AnalysisInputError",+ userMessage: expect.stringContaining("0x1000, 0x1040"),+ },+ });+ await client.close();+});++it("names function entries and the data Kuna's export labels", async () => {+ const { open } = await session("rea-kuna-names-");+ const client = open();++ expect(+ (await run(client, "address_name", { address: "0x1040" })).result,+ ).toBe("parse");+ expect(+ (await run(client, "address_name", { address: "0x3000" })).result,+ ).toBe("dat_3000");+ expect(+ (await run(client, "address_name", { address: "0x3010" })).result,+ ).toBe("g_table");+ const unnamed = await run(client, "address_name", { address: "0x9999" });+ expect(unnamed.result).toBeNull();+ expect(unnamed.limitations.at(-1)).toContain("not that no symbol exists");+ await client.close();+});++it("reports a failed function and an import slot as unavailable text, not errors", async () => {+ const { open } = await session("rea-kuna-unavailable-");+ const client = open();+ await run(client, "procedure_assembly", { procedure: "main" });++ const broken = await run(client, "procedure_pseudo_code", {+ procedure: "broken",+ });+ expect(broken.result).toBeNull();+ expect(broken.limitations.at(-1)).toBe(+ "Kuna could not decompile this function: Flow exceeded maximum instructions",+ );+ const imported = await run(client, "procedure_pseudo_code", {+ procedure: "puts",+ });+ expect(imported.result).toBeNull();+ expect(+ await client.execute("procedure_assembly", { procedure: "puts" }),+ ).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisCapabilityUnavailableError" },+ });+ await client.close();+});++it("builds a dossier with pseudocode and assembly, and the rest explicitly unavailable", async () => {+ const { open } = await session("rea-kuna-dossier-");+ const client = open();++ const dossier = await run(client, "analyze_function", { procedure: "main" });++ expect(dossier.rawResult).toMatchObject({+ source: {+ kind: "project-export",+ files: [+ {+ facet: "pseudocode",+ file_sha256: expect.stringMatching(/^[0-9a-f]{64}$/u),+ },+ {+ facet: "assembly",+ file_sha256: expect.stringMatching(/^[0-9a-f]{64}$/u),+ },+ ],+ },+ });+ const { source } = dossier.rawResult as {+ source: {+ directory: string;+ files: {+ facet: "pseudocode" | "assembly";+ file: string;+ file_sha256: string;+ byte_offset: number;+ byte_length: number;+ }[];+ };+ };+ for (const file of source.files) {+ const bytes = await readFile(join(source.directory, file.file));+ expect(createHash("sha256").update(bytes).digest("hex")).toBe(+ file.file_sha256,+ );+ const text = bytes+ .subarray(file.byte_offset, file.byte_offset + file.byte_length)+ .toString("utf8");+ const facet = (dossier.result as Record<string, JsonValue>)[file.facet];+ expect(text).toContain(Array.isArray(facet) ? facet.join("\n") : facet);+ }++ expect(dossier.result).toMatchObject({+ procedure: {+ address: "0x1000",+ name: "main",+ body: { available: false },+ },+ pseudocode: "int main(void)\n{\n return 0;\n}",+ assembly: ["main: ; 0x1000", " 00001000: c3 RET"],+ facet_availability: {+ pseudocode: { available: true },+ assembly: { available: true },+ callers: { available: false },+ callees: { available: false },+ references: { available: false },+ cfg: { available: false },+ },+ });+ await client.close();+});++it("rejects oversized cached text before buffering while retaining its full export", async () => {+ const { cacheRoot, open } = await session("rea-kuna-text-capacity-", {+ functions: [{ name: "main", addr: "0x1000" }],+ cPadding: KUNA_FUNCTION_TEXT_BYTES,+ });+ const client = open();+ try {+ await run(client, "procedure_assembly", { procedure: "main" });+ for (const operation of [+ "procedure_pseudo_code",+ "analyze_function",+ ] as const) {+ const result = await client.execute(operation, { procedure: "main" });+ expect(result.ok).toBe(false);+ if (!result.ok)+ expect(result.error).toMatchObject({+ _tag: "AnalysisResourceConstraintError",+ resource: "capacity",+ reportedLimits: { limit_bytes: KUNA_FUNCTION_TEXT_BYTES },+ });+ }+ const [key] = await readdir(join(cacheRoot, "projects"));+ const bytes = await readFile(+ join(cacheRoot, "projects", key ?? "", "project", "program.c"),+ );+ expect(bytes.length).toBeGreaterThan(KUNA_FUNCTION_TEXT_BYTES);+ } finally {+ await client.close();+ }+});++it("keeps answering pseudocode one function at a time when the export fails", async () => {+ const { open } = await session("rea-kuna-export-failed-", {+ project: "exit-failure",+ });+ const client = open();++ expect(+ await client.execute("procedure_assembly", { procedure: "main" }),+ ).toMatchObject({+ ok: false,+ error: {+ userMessage: expect.stringContaining(+ "not in recognized object file format",+ ),+ },+ });+ const pseudocode = await run(client, "procedure_pseudo_code", {+ procedure: "main",+ });+ expect(pseudocode.rawResult).toMatchObject({+ source: { kind: "single-function" },+ });+ expect(pseudocode.limitations.at(-1)).toContain("The project export failed");+ await client.close();+});++it("stops waiting for the export when the caller cancels, without abandoning it", async () => {+ const { open } = await session("rea-kuna-wait-cancel-", { delayMs: 1500 });+ const client = open();+ const caller = new AbortController();++ const waiting = client.execute(+ "procedure_assembly",+ { procedure: "main" },+ { signal: caller.signal },+ );+ setTimeout(() => caller.abort(), 200);+ expect(await waiting).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisCancelledError" },+ });+ // The session's export continues and serves the next request.+ expect(+ (await run(client, "procedure_assembly", { procedure: "main" })).rawResult,+ ).toMatchObject({ source: { kind: "project-export" } });+ await client.close();+});++it("stops the export it alone wanted before reporting itself closed", async () => {+ const { kuna, cacheRoot, open } = await session("rea-kuna-close-", {+ project: "hang",+ });+ const client = open();+ await run(client, "procedure_pseudo_code", { procedure: "main" });+ await expect.poll(() => exportsOf(kuna)).toHaveLength(1);+ const pid = (await exportsOf(kuna))[0]?.pid ?? 0;++ expect(await client.close()).toEqual({ ok: true, value: null });++ expect(() => process.kill(pid, 0)).toThrow();+ expect(await readdir(join(cacheRoot, "staging"))).toEqual([]);+ expect(await client.close()).toEqual({ ok: true, value: null });+ expect(+ await client.execute("procedure_pseudo_code", { procedure: "main" }),+ ).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisCapabilityUnavailableError" },+ });+});++it.each([false, true])(+ "drains an active single-function request before close (caller signal: %s)",+ async (withCallerSignal) => {+ const { kuna, open } = await session("rea-kuna-close-active-", {+ project: "hang",+ decompile: "hang",+ });+ const client = open();+ const caller = new AbortController();+ const request = client.execute(+ "procedure_pseudo_code",+ { procedure: "main" },+ withCallerSignal ? { signal: caller.signal } : {},+ );+ try {+ await expect+ .poll(async () =>+ (await fakeKunaCalls(kuna)).filter(+ ({ argv }) => argv[0] === "decompile",+ ),+ )+ .toHaveLength(1);+ const call = (await fakeKunaCalls(kuna)).find(+ ({ argv }) => argv[0] === "decompile",+ );+ expect(await client.close()).toEqual({ ok: true, value: null });+ expect(() => process.kill(call?.pid ?? 0, 0)).toThrow();+ expect(await request).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisCancelledError" },+ });+ } finally {+ caller.abort();+ await request;+ await client.close();+ }+ },+);++it("refuses another document, an unsupported operation and a replaced executable", async () => {+ const { kuna, open } = await session("rea-kuna-refusals-");+ const client = open();++ expect(+ await client.execute("procedure_pseudo_code", {+ procedure: "main",+ document: "/other/program",+ }),+ ).toMatchObject({ ok: false, error: { _tag: "AnalysisInputError" } });+ expect(await client.execute("xrefs", { address: "0x1000" })).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisCapabilityUnavailableError" },+ });+ await client.close();++ await appendFile(kuna, "\n// replaced\n");+ await setFakeKunaBehavior(kuna, { functions: FUNCTIONS });+ const replaced = open();+ expect(+ await replaced.execute("procedure_pseudo_code", { procedure: "main" }),+ ).toMatchObject({+ ok: false,+ error: {+ _tag: "ProviderAdapterError",+ userMessage: expect.stringContaining(+ "changed after this target was opened",+ ),+ },+ });+ await replaced.close();+});++/**+ * Launch for real, but have cleanup of the selected subcommand report an+ * unproven stop until `release` is called, as a lost ownership proof would.+ */+const unprovenCleanupLauncher = (subcommand: string) => {+ let proven = false;+ const launcher: KunaProcessLauncher = async (options) => {+ const spawned = await spawnOwnedProviderProcess(options);+ if (options.arguments[0] !== subcommand) return spawned;+ return {+ ...spawned,+ cleanup: async () => {+ const cleaned = await cleanupOwnedProcessGroup(spawned.ownership);+ return proven+ ? cleaned+ : { cleaned: false, reason: `${subcommand} stop unproven` };+ },+ };+ };+ return { launcher, release: () => (proven = true) };+};++it("retains an active request's workspace when close cannot prove its stop", async () => {+ const unproven = unprovenCleanupLauncher("decompile");+ const { kuna, open } = await session(+ "rea-kuna-close-active-unproven-",+ { project: "hang", decompile: "hang" },+ {},+ unproven.launcher,+ );+ const client = open();+ const caller = new AbortController();+ const request = client.execute(+ "procedure_pseudo_code",+ { procedure: "main" },+ { signal: caller.signal },+ );+ try {+ await expect+ .poll(async () =>+ (await fakeKunaCalls(kuna)).filter(+ ({ argv }) => argv[0] === "decompile",+ ),+ )+ .toHaveLength(1);+ const closed = await client.close();+ expect(closed).toMatchObject({+ ok: false,+ error: { cleanupIncomplete: true },+ });+ expect(await request).toMatchObject({+ ok: false,+ error: { cleanupIncomplete: true },+ });+ const input = (await fakeKunaCalls(kuna)).find(+ ({ argv }) => argv[0] === "decompile",+ )?.argv[1];+ expect(await readFile(input ?? "", "utf8")).toBe("program bytes");+ } finally {+ caller.abort();+ await request;+ unproven.release();+ expect(await client.close()).toEqual({ ok: true, value: null });+ }+});++it("keeps reporting a failed close and succeeds once a retry proves the stop", async () => {+ const unproven = unprovenCleanupLauncher("decompile");+ const { open } = await session(+ "rea-kuna-close-retry-",+ { project: "hang", decompile: "hang" },+ { REA_KUNA_TIMEOUT_MS: "300" },+ unproven.launcher,+ );+ const client = open();++ expect(+ await client.execute("procedure_pseudo_code", { procedure: "main" }),+ ).toMatchObject({ ok: false, error: { cleanupIncomplete: true } });+ const first = await client.close();+ expect(first).toMatchObject({+ ok: false,+ error: { diagnostics: { reason: "decompile stop unproven" } },+ });+ // A retry that still cannot prove the stop keeps failing.+ expect((await client.close()).ok).toBe(false);++ unproven.release();+ expect(await client.close()).toEqual({ ok: true, value: null });+ expect(await client.close()).toEqual({ ok: true, value: null });+});++it("reports an abandoned export's unproven cleanup from close", async () => {+ const unproven = unprovenCleanupLauncher("decompile-project");+ const { kuna, open } = await session(+ "rea-kuna-close-export-",+ { project: "hang" },+ {},+ unproven.launcher,+ );+ const client = open();+ await run(client, "procedure_pseudo_code", { procedure: "main" });+ await expect.poll(() => exportsOf(kuna)).toHaveLength(1);++ expect(await client.close()).toMatchObject({+ ok: false,+ error: { diagnostics: { reason: "decompile-project stop unproven" } },+ });+ unproven.release();+ expect(await client.close()).toEqual({ ok: true, value: null });+});++it("retries the abandoned export's file cleanup before reporting close success", async () => {+ const launcher: KunaProcessLauncher = async (options) => {+ const spawned = await spawnOwnedProviderProcess(options);+ if (options.arguments[0] !== "decompile-project") return spawned;+ return {+ ...spawned,+ cleanup: async () => {+ const stopped = await cleanupOwnedProcessGroup(spawned.ownership);+ // The child is stopped, but its private input cannot yet be removed.+ await chmod(options.cwd ?? "", 0o500);+ return stopped;+ },+ };+ };+ const { kuna, cacheRoot, open } = await session(+ "rea-kuna-close-export-files-",+ { project: "hang" },+ {},+ launcher,+ );+ const client = open();+ try {+ await run(client, "procedure_pseudo_code", { procedure: "main" });+ await expect.poll(() => exportsOf(kuna)).toHaveLength(1);+ expect(await client.close()).toMatchObject({+ ok: false,+ error: { cleanupIncomplete: true },+ });+ expect((await client.close()).ok).toBe(false);+ } finally {+ const restore = async (directory: string): Promise<void> => {+ await chmod(directory, 0o700);+ for (const entry of await readdir(directory, { withFileTypes: true }))+ if (entry.isDirectory()) await restore(join(directory, entry.name));+ };+ await restore(cacheRoot);+ expect(await client.close()).toEqual({ ok: true, value: null });+ }+ expect(await readdir(join(cacheRoot, "staging"))).toEqual([]);+ expect(await readdir(join(cacheRoot, "trash"))).toEqual([]);+});++it("refuses to launch an executable replaced after the target was opened", async () => {+ const { kuna, open } = await session("rea-kuna-swapped-", {+ project: "exit-failure",+ });+ const client = open();+ await run(client, "procedure_pseudo_code", { procedure: "main" });++ await appendFile(kuna, "\n// replaced mid-session\n");+ expect(+ await client.execute("procedure_pseudo_code", { procedure: "parse" }),+ ).toMatchObject({+ ok: false,+ error: {+ _tag: "ProviderAdapterError",+ userMessage: expect.stringContaining(+ "changed after this target was opened",+ ),+ },+ });+ await client.close();+});++it("recovers when another server evicts the export this session adopted", async () => {+ const { cacheRoot, open } = await session("rea-kuna-evicted-");+ const client = open();+ await run(client, "procedure_assembly", { procedure: "main" });+ const [key] = await readdir(join(cacheRoot, "projects"));+ await mkdir(join(cacheRoot, "trash"), { recursive: true });+ await rename(+ join(cacheRoot, "projects", key ?? ""),+ join(cacheRoot, "trash", "elsewhere"),+ );++ // Pseudocode falls back while the export rebuilds; assembly waits for it.+ const pseudocode = await run(client, "procedure_pseudo_code", {+ procedure: "parse",+ });+ expect(pseudocode.result).toContain("parse");+ const assembly = await run(client, "procedure_assembly", {+ procedure: "parse",+ });+ expect(assembly.rawResult).toMatchObject({+ source: { kind: "project-export" },+ });+ expect(await readdir(join(cacheRoot, "projects"))).toEqual([key]);+ await client.close();+});++it("reports a failed export as failed rather than building", async () => {+ const { open } = await session("rea-kuna-failed-state-", {+ project: "exit-failure",+ });+ const client = open();+ await client.execute("procedure_assembly", { procedure: "main" });++ expect(+ (await run(client, "procedure_pseudo_code", { procedure: "main" }))+ .rawResult,+ ).toMatchObject({+ project_export: {+ state: "failed",+ reason: expect.stringContaining("not in recognized object file format"),+ },+ });+ await client.close();+});++it("lets one caller stop waiting for the shared inventory without failing another", async () => {+ const { open } = await session("rea-kuna-shared-inventory-", {+ inventoryDelayMs: 700,+ });+ const client = open();+ const first = new AbortController();++ const cancelled = client.execute(+ "list_procedures",+ {},+ { signal: first.signal },+ );+ const waiting = client.execute("search_procedures", { pattern: "main" });+ setTimeout(() => first.abort(), 100);++ expect(await cancelled).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisCancelledError" },+ });+ expect(await waiting).toMatchObject({+ ok: true,+ value: { result: [{ address: "0x1000", value: "main" }] },+ });+ await client.close();+});++it("leaves no private copy behind when workspace setup fails", async () => {+ const { target, open } = await session("rea-kuna-workspace-leak-", {+ project: "hang",+ });+ const runtime = await createTestTempDirectory("rea-kuna-runtime-");+ const previous = process.env.TMPDIR;+ process.env.TMPDIR = runtime;+ try {+ const client = open();+ // A vanished target makes the copy itself throw mid-setup.+ await rename(target.path, `${target.path}.moved`);++ expect(+ await client.execute("procedure_pseudo_code", { procedure: "main" }),+ ).toMatchObject({ ok: false });+ expect(await readdir(runtime)).toEqual([]);+ expect(await client.close()).toEqual({ ok: true, value: null });+ } finally {+ if (previous === undefined) delete process.env.TMPDIR;+ else process.env.TMPDIR = previous;+ }+});diff --git a/tests/boundary/providers/kuna/kunaRegexSearch.test.ts b/tests/boundary/providers/kuna/kunaRegexSearch.test.tsnew file mode 100644index 000000000..f62f96ef0--- /dev/null+++ b/tests/boundary/providers/kuna/kunaRegexSearch.test.ts@@ -0,0 +1,66 @@+import { spawnSync } from "node:child_process";+import { resolve } from "node:path";+import { pathToFileURL } from "node:url";++import { expect, it as test } from "vitest";++import { session } from "./kunaSessionFixture.js";++const it = test.skipIf(process.platform === "win32");++it.each(["cancel", "deadline"])(+ "keeps regex %s bounded and the same session usable",+ async (mode) => {+ const { kuna, target, cacheRoot, profile } = await session(+ "rea-kuna-regex-",+ {+ functions: [+ { name: `${"a".repeat(40)}!`, addr: "0x1000" },+ { name: "Δelta", addr: "0x1040" },+ ],+ },+ );+ // A parent watchdog bounds this regression even if matching freezes the+ // child's event loop. All Kuna commands finish before adversarial matching.+ const script = `+import assert from "node:assert/strict";+import { KunaProvider } from ${JSON.stringify(pathToFileURL(resolve("dist/kuna/KunaProvider.js")).href)};+const provider = new KunaProvider(${JSON.stringify({ REA_KUNA_COMMAND: kuna, REA_KUNA_CACHE_DIR: cacheRoot })});+const client = provider.createClient(${JSON.stringify(target)}, ${JSON.stringify(profile)});+try {+ assert.equal((await client.execute("procedure_assembly", {procedure:"0x1000"})).ok, true);+ const options = ${mode === "cancel" ? "{signal:AbortSignal.timeout(100)}" : "{}"};+ const matched = await client.execute("search_procedures", {pattern:"^(a+)+$",mode:"regex"}, options);+ assert.equal(matched.ok, false);+ assert.equal(matched.error._tag, ${JSON.stringify(mode === "cancel" ? "AnalysisCancelledError" : "AnalysisResourceConstraintError")});+ if (${JSON.stringify(mode)} === "deadline") assert.equal(matched.error.reportedLimits.matching_deadline_ms, 5000);+ assert.equal((await client.execute("health", {})).ok, true);+ const unicode = await client.execute("search_procedures", {pattern:"^δ",mode:"regex"});+ assert.equal(unicode.ok, true);+ assert.deepEqual(unicode.value.result, [{address:"0x1040",value:"Δelta"}]);+ const invalid = await client.execute("search_procedures", {pattern:"[",mode:"regex"});+ assert.equal(invalid.ok, false);+ assert.equal(invalid.error._tag, "AnalysisInputError");+ const literal = await client.execute("search_procedures", {pattern:"^(a+)+$"});+ assert.equal(literal.ok, true);+ assert.deepEqual(literal.value.result, []);+} finally {+ assert.equal((await client.close()).ok, true);+}+console.log("bounded and healthy");+`;+ const result = spawnSync(+ process.execPath,+ ["--input-type=module", "-e", script],+ {+ encoding: "utf8",+ timeout: 25_000,+ killSignal: "SIGKILL",+ },+ );+ expect(result.error).toBeUndefined();+ expect(result.stderr).toBe("");+ expect(result.status).toBe(0);+ expect(result.stdout.trim()).toBe("bounded and healthy");+ },+);diff --git a/tests/boundary/providers/kuna/kunaSessionFixture.ts b/tests/boundary/providers/kuna/kunaSessionFixture.tsnew file mode 100644index 000000000..36f904c11--- /dev/null+++ b/tests/boundary/providers/kuna/kunaSessionFixture.ts@@ -0,0 +1,78 @@+import { createHash } from "node:crypto";+import { writeFile } from "node:fs/promises";+import { join } from "node:path";+import type { AnalysisClient } from "../../../../src/application/AnalysisProvider.js";+import type { BinaryTarget } from "../../../../src/domain/binaryTargetTypes.js";+import type { JsonValue } from "../../../../src/domain/jsonValue.js";+import type { KunaProcessLauncher } from "../../../../src/kuna/KunaCommand.js";+import { KunaProvider } from "../../../../src/kuna/KunaProvider.js";+import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js";+import {+ fakeKunaCalls,+ writeFakeKuna,+ type FakeKunaBehavior,+} from "./fakeKuna.js";++export const FUNCTIONS = [+ { name: "main", addr: "0x1000" },+ { name: "parse", addr: "0x1040" },+ {+ name: "broken",+ addr: "0x1080",+ error: "Flow exceeded maximum instructions",+ },+] as const;++export const session = async (+ prefix: string,+ behavior: FakeKunaBehavior = {},+ environment: Readonly<Record<string, string>> = {},+ launcher?: KunaProcessLauncher,+) => {+ const root = await createTestTempDirectory(prefix);+ const kuna = await writeFakeKuna(root, { functions: FUNCTIONS, ...behavior });+ const targetPath = join(root, "program");+ await writeFile(targetPath, "program bytes");+ const target: BinaryTarget = {+ path: targetPath,+ sha256: createHash("sha256").update("program bytes").digest("hex"),+ kind: "executable",+ format: "elf",+ architecture: "x86_64",+ availableArchitectures: ["x86_64"],+ };+ const cacheRoot = join(root, "cache");+ const provider = new KunaProvider(+ { REA_KUNA_COMMAND: kuna, REA_KUNA_CACHE_DIR: cacheRoot, ...environment },+ {+ platform: process.platform,+ ...(launcher === undefined ? {} : { launcher }),+ },+ );+ const profile = await provider.resolveAnalysisProfile(target);+ if (!profile.ok || profile.value.profile === null)+ throw new Error("profile did not resolve");+ const resolved = profile.value.profile;+ const open = () => provider.createClient(target, resolved);+ return { root, kuna, target, cacheRoot, provider, profile: resolved, open };+};++export const run = async (+ client: AnalysisClient,+ operation: Parameters<AnalysisClient["execute"]>[0],+ parameters: Readonly<Record<string, JsonValue>> = {},+ signal?: AbortSignal,+) => {+ const result = await client.execute(+ operation,+ parameters,+ signal === undefined ? {} : { signal },+ );+ if (!result.ok) throw result.error;+ return result.value;+};++export const exportsOf = async (kuna: string) =>+ (await fakeKunaCalls(kuna)).filter(+ ({ argv }) => argv[0] === "decompile-project",+ );diff --git a/tests/boundary/providers/kuna/kunaVerifier.test.ts b/tests/boundary/providers/kuna/kunaVerifier.test.tsnew file mode 100644index 000000000..a83a32740--- /dev/null+++ b/tests/boundary/providers/kuna/kunaVerifier.test.ts@@ -0,0 +1,73 @@+import { spawnSync } from "node:child_process";+import { mkdir, writeFile } from "node:fs/promises";+import { join } from "node:path";++import { expect, it as test } from "vitest";++import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js";+import { fakeKunaCalls, writeFakeKuna } from "./fakeKuna.js";++const it = test.skipIf(process.platform === "win32");++it.each([+ { populated: false, names: "main", reason: "No caller-built targets" },+ { populated: true, names: "typo", reason: "No caller-built targets" },+ {+ populated: true,+ names: "main,typo",+ reason: "Requested functions were not found",+ },+])(+ "rejects an unverified caller matrix: $names, populated=$populated",+ async ({ populated, names, reason }) => {+ const root = await createTestTempDirectory("rea-kuna-verifier-selection-");+ const kuna = await writeFakeKuna(root);+ const targets = join(root, "targets");+ await mkdir(targets);+ if (populated) {+ const flavor = join(targets, "linux");+ await mkdir(flavor);+ await writeFile(join(flavor, "program"), "not analyzed");+ await writeFile(join(flavor, "program.stripped"), "not analyzed");+ }+ // Only symbol discovery is simulated; no provider workflow should start.+ const nm = join(root, "nm");+ await writeFile(+ nm,+ `#!${process.execPath}\nprocess.stdout.write("00001000 T main\\n");\n`,+ {+ mode: 0o755,+ },+ );+ const result = spawnSync(+ process.execPath,+ [+ "scripts/verify-real-kuna.mjs",+ "--targets",+ targets,+ "--functions",+ names,+ "--compare-ghidra",+ ],+ {+ encoding: "utf8",+ timeout: 10_000,+ env: {+ PATH: process.env.PATH,+ HOME: root,+ REA_KUNA_COMMAND: kuna,+ REA_NM: nm,+ REA_CC: join(root, "compiler-must-not-run"),+ GHIDRA_INSTALL_DIR: join(root, "ghidra-must-not-run"),+ },+ },+ );+ expect(result.error).toBeUndefined();+ expect(result.status).toBe(1);+ expect(result.stderr).toContain(reason);+ expect(result.stderr).not.toContain("compiler-must-not-run");+ expect((await fakeKunaCalls(kuna)).map(({ argv }) => argv)).toEqual([+ ["--version"],+ ]);+ },+);