directories #4232

New issue

Closed

opened 2026-10-31 00:47:55 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 00:47:55 +00:00

Owner

Originally created by @CassieFox23 on GitHub (Oct 23, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/6901

TL;DR: The architecture map is not stale, but it is incomplete. It names 30 of the 51 directories under src/ and leaves out 21, including Kuna, ADB, Frida and the GPU and model readers. I can send the edit as a PR if you like.

Before submitting

I searched the existing issues for a related documentation report.
I removed credentials, tokens, private paths, and sensitive target data.

Documentation location

docs/architecture.mermaid. CONTRIBUTING.md links to it. Look under "Choosing a contribution". AGENTS.md links to it too.

Problem

I read the file at main ef475fcf8b. Everything it names still exists. These src/ directories do not appear in it.

adb, apktool, captures, compression, cutter, electron, erlang
filesystem, flutter, frida, go, gpu, il2cpp, jeb
kuna, model, pcap, python, rust, signals, sqlite

Say someone follows CONTRIBUTING.md to the map. They want to see provider composition. They will not find Kuna there. It is missing from the deep analysis candidates. Kuna is built next to Hopper, Ghidra and IDA at src/composition/binary.ts line 56 and joins the provider list at line 71.

Expected content

The same file with the missing parts added in its own style. My proposal adds 7 nodes and 20 arrows and changes no existing line. The new nodes are:

KUNA: a deep candidate, next to IDA
ANDROID_TOOLS: adb, apktool, jeb
CAPTURE_TOOLS: captures, pcap, signals, sqlite
NATIVE_READERS: go, rust, il2cpp, flutter, gpu
FORMAT_READERS: model, python, erlang, electron
RUNTIME: frida, cutter
FILESYSTEM: a helper, beside PROCESS

The grouping is a suggestion. Split or fold it as you prefer.

Frida and Cutter are the odd two. The server and the CLI build them directly. There is no composition factory for them. See src/server/createServer.ts lines 521 and 541 to 542.

Supporting evidence

git ls-tree -d --name-only main:src/ gives 51 names. Checking each against the file leaves the 21 above.
Open PR #2791 moves this file. The new path is docs/architecture/architecture.mermaid. Its content is unchanged. I compared it with the file at its pinned base fb28ec1537. An edit would need to follow the file.
I found no open or closed issue about this. I searched for architecture.mermaid, mermaid and architecture diagram. No hit is about the missing directories. The closest are #626 (merged, a diagram fix on 5 October), #2791 and open PR #2418. That PR adds an angr node to this same file, so an edit would need to fit with it too.
I did not render the proposal in a Mermaid viewer. I checked that every node is defined, every arrow points at a defined node and the subgraphs balance. The new arrows rest on import counts per directory. I did not re-check the existing arrows.

Additional context

Nothing in the repo generates or checks the file. The file is edited by hand inside feature PRs, 27 commits since 1 October. The 21 directories were added between 10 and 24 October, and only one of those commits touched the file. That one, 4aa51bfe19 (#2799), added the objdump, Rizin and GDB nodes but not Cutter.

Proposed change (diff against main)

--- a/docs/architecture.mermaid
+++ b/docs/architecture.mermaid
@@ -35,6 +35,7 @@
         GHIDRA["src/ghidra/<br/>Ghidra discovery, profile & function analysis<br/>snapshot, Unix/Windows transport, bounded lifecycle"]
         IDA["src/ida/<br/>Upstream MCP contract adaptation<br/>live GUI binding or owned headless database"]
         IDA_MCP["External ida-pro-mcp<br/>GUI proxy or database supervisor<br/>upstream installation and engine lifecycle"]
+        KUNA["src/kuna/<br/>BYO Kuna decompiler, a deep analysis candidate<br/>discovery reads metadata only; version probe when a target opens"]
         AUX["src/artifacts/ + src/native/<br/>artifact inventory, bounded directory triage and extraction<br/>format readers and native capabilities"]
         BROWSER["src/browser/<br/>CDP / Playwright capture<br/>captured scripts and native module resolution<br/>execution/: coverage, listener and source attribution"]
         JS_CODEC["src/javascript/sourceMaps/<br/>pinned upstream map codec<br/>owned heap-limited Node process, complete point evidence"]
@@ -47,12 +48,19 @@
         FIRMWARE["src/firmware/<br/>Binwalk / Unblob adapters<br/>owned processes, report normalization, private extraction"]
         ANDROID["src/android/<br/>Static APK adapter<br/>owned SDK stdio, pinned headless JADX, normalization"]
         REFERENCE["src/reference/<br/>Filesystem reference-source reader<br/>bounded traversal, validation, errors"]
+
+        ANDROID_TOOLS["src/adb/ + src/apktool/ + src/jeb/<br/>BYO device, resource-decoding and JEB adapters<br/>owned adb and Apktool processes; JEB engine client over MCP"]
+        CAPTURE_TOOLS["src/captures/ + src/pcap/ + src/signals/ + src/sqlite/<br/>BYO tshark, pcap, sigrok and SQLite child inspection<br/>selected captures, recordings and databases; owned processes"]
+        NATIVE_READERS["src/go/ + src/rust/ + src/il2cpp/ + src/flutter/ + src/gpu/<br/>Bundled in-process binary metadata readers<br/>Go build info, Rust dependencies, IL2CPP, Dart build ID, GPU code objects<br/>src/compression/: shared codec-result helper for rust and gpu"]
+        FORMAT_READERS["src/model/ + src/python/ + src/erlang/ + src/electron/<br/>Bundled in-process format readers<br/>GGUF and safetensors headers, Python .pyc, Erlang BEAM, Electron fuses"]
+        RUNTIME["src/frida/ + src/cutter/<br/>Frida instrumentation sessions and live Cutter bridge client"]
     end
 
     subgraph "Provider Process Foundation"
         PROCESS["src/process/<br/>owned process groups, private roots<br/>deadlines, bounded file reads and diagnostics, cleanup"]
         WINDOWS["src/windows/<br/>Windows host boundary adapters<br/>package loader, opaque handles, owned jobs and private runtimes"]
         WINDOWS_NATIVE["native/windows/src/<br/>Node-API implementation<br/>NTFS admission, protected DACLs and atomic Job Object assignment"]
+        FILESYSTEM["src/filesystem/<br/>owned file and directory handles<br/>stable reads, staged output, caller paths"]
     end
 
     subgraph "Contracts Layer"
@@ -175,3 +183,23 @@
     APP -->|EVM interface port| EVM
     EVM --> PROCESS
     EVM --> DOMAIN
+    COMPOSITION --> KUNA
+    KUNA --> PROCESS
+    KUNA --> FILESYSTEM
+    KUNA --> DOMAIN
+    COMPOSITION --> ANDROID_TOOLS
+    ANDROID_TOOLS --> PROCESS
+    ANDROID_TOOLS --> DOMAIN
+    COMPOSITION --> CAPTURE_TOOLS
+    CAPTURE_TOOLS --> PROCESS
+    CAPTURE_TOOLS --> DOMAIN
+    COMPOSITION --> NATIVE_READERS
+    NATIVE_READERS --> DOMAIN
+    COMPOSITION --> FORMAT_READERS
+    FORMAT_READERS --> DOMAIN
+    SERVER --> RUNTIME
+    CLI --> RUNTIME
+    RUNTIME --> DOMAIN
+    PROCESS --> FILESYSTEM
+    AUX --> FILESYSTEM
+    APP --> FILESYSTEM

🤖 Written with Claude Code (Sonnet 5.5, verified by Opus 5.5), posted with my OK 🦊

Originally created by @CassieFox23 on GitHub (Oct 23, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/6901 **TL;DR:** The architecture map is not stale, but it is incomplete. It names 30 of the 51 directories under src/ and leaves out 21, including Kuna, ADB, Frida and the GPU and model readers. I can send the edit as a PR if you like. ### Before submitting - [x] I searched the existing issues for a related documentation report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Documentation location [docs/architecture.mermaid](https://github.com/morluto/rea/blob/main/docs/architecture.mermaid). CONTRIBUTING.md links to it. Look under "Choosing a contribution". AGENTS.md links to it too. ### Problem I read the file at main ef475fcf8b. Everything it names still exists. These src/ directories do not appear in it. - `adb`, `apktool`, `captures`, `compression`, `cutter`, `electron`, `erlang` - `filesystem`, `flutter`, `frida`, `go`, `gpu`, `il2cpp`, `jeb` - `kuna`, `model`, `pcap`, `python`, `rust`, `signals`, `sqlite` Say someone follows CONTRIBUTING.md to the map. They want to see provider composition. They will not find Kuna there. It is missing from the deep analysis candidates. Kuna is built next to Hopper, Ghidra and IDA at src/composition/binary.ts line 56 and joins the provider list at line 71. ### Expected content The same file with the missing parts added in its own style. My proposal adds 7 nodes and 20 arrows and changes no existing line. The new nodes are: - `KUNA`: a deep candidate, next to IDA - `ANDROID_TOOLS`: adb, apktool, jeb - `CAPTURE_TOOLS`: captures, pcap, signals, sqlite - `NATIVE_READERS`: go, rust, il2cpp, flutter, gpu - `FORMAT_READERS`: model, python, erlang, electron - `RUNTIME`: frida, cutter - `FILESYSTEM`: a helper, beside PROCESS The grouping is a suggestion. Split or fold it as you prefer. Frida and Cutter are the odd two. The server and the CLI build them directly. There is no composition factory for them. See src/server/createServer.ts lines 521 and 541 to 542. ### Supporting evidence - `git ls-tree -d --name-only main:src/` gives 51 names. Checking each against the file leaves the 21 above. - Open PR #2791 moves this file. The new path is `docs/architecture/architecture.mermaid`. Its content is unchanged. I compared it with the file at its pinned base fb28ec1537. An edit would need to follow the file. - I found no open or closed issue about this. I searched for `architecture.mermaid`, `mermaid` and `architecture diagram`. No hit is about the missing directories. The closest are #626 (merged, a diagram fix on 5 October), #2791 and open PR #2418. That PR adds an angr node to this same file, so an edit would need to fit with it too. - I did not render the proposal in a Mermaid viewer. I checked that every node is defined, every arrow points at a defined node and the subgraphs balance. The new arrows rest on import counts per directory. I did not re-check the existing arrows. ### Additional context Nothing in the repo generates or checks the file. The file is edited by hand inside feature PRs, 27 commits since 1 October. The 21 directories were added between 10 and 24 October, and only one of those commits touched the file. That one, 4aa51bfe19 (#2799), added the objdump, Rizin and GDB nodes but not Cutter. <details> <summary>Proposed change (diff against main)</summary> ```diff --- a/docs/architecture.mermaid +++ b/docs/architecture.mermaid @@ -35,6 +35,7 @@ GHIDRA["src/ghidra/ Ghidra discovery, profile & function analysis snapshot, Unix/Windows transport, bounded lifecycle"] IDA["src/ida/ Upstream MCP contract adaptation live GUI binding or owned headless database"] IDA_MCP["External ida-pro-mcp GUI proxy or database supervisor upstream installation and engine lifecycle"] + KUNA["src/kuna/ BYO Kuna decompiler, a deep analysis candidate discovery reads metadata only; version probe when a target opens"] AUX["src/artifacts/ + src/native/ artifact inventory, bounded directory triage and extraction format readers and native capabilities"] BROWSER["src/browser/ CDP / Playwright capture captured scripts and native module resolution execution/: coverage, listener and source attribution"] JS_CODEC["src/javascript/sourceMaps/ pinned upstream map codec owned heap-limited Node process, complete point evidence"] @@ -47,12 +48,19 @@ FIRMWARE["src/firmware/ Binwalk / Unblob adapters owned processes, report normalization, private extraction"] ANDROID["src/android/ Static APK adapter owned SDK stdio, pinned headless JADX, normalization"] REFERENCE["src/reference/ Filesystem reference-source reader bounded traversal, validation, errors"] + + ANDROID_TOOLS["src/adb/ + src/apktool/ + src/jeb/ BYO device, resource-decoding and JEB adapters owned adb and Apktool processes; JEB engine client over MCP"] + CAPTURE_TOOLS["src/captures/ + src/pcap/ + src/signals/ + src/sqlite/ BYO tshark, pcap, sigrok and SQLite child inspection selected captures, recordings and databases; owned processes"] + NATIVE_READERS["src/go/ + src/rust/ + src/il2cpp/ + src/flutter/ + src/gpu/ Bundled in-process binary metadata readers Go build info, Rust dependencies, IL2CPP, Dart build ID, GPU code objects src/compression/: shared codec-result helper for rust and gpu"] + FORMAT_READERS["src/model/ + src/python/ + src/erlang/ + src/electron/ Bundled in-process format readers GGUF and safetensors headers, Python .pyc, Erlang BEAM, Electron fuses"] + RUNTIME["src/frida/ + src/cutter/ Frida instrumentation sessions and live Cutter bridge client"] end subgraph "Provider Process Foundation" PROCESS["src/process/ owned process groups, private roots deadlines, bounded file reads and diagnostics, cleanup"] WINDOWS["src/windows/ Windows host boundary adapters package loader, opaque handles, owned jobs and private runtimes"] WINDOWS_NATIVE["native/windows/src/ Node-API implementation NTFS admission, protected DACLs and atomic Job Object assignment"] + FILESYSTEM["src/filesystem/ owned file and directory handles stable reads, staged output, caller paths"] end subgraph "Contracts Layer" @@ -175,3 +183,23 @@ APP -->|EVM interface port| EVM EVM --> PROCESS EVM --> DOMAIN + COMPOSITION --> KUNA + KUNA --> PROCESS + KUNA --> FILESYSTEM + KUNA --> DOMAIN + COMPOSITION --> ANDROID_TOOLS + ANDROID_TOOLS --> PROCESS + ANDROID_TOOLS --> DOMAIN + COMPOSITION --> CAPTURE_TOOLS + CAPTURE_TOOLS --> PROCESS + CAPTURE_TOOLS --> DOMAIN + COMPOSITION --> NATIVE_READERS + NATIVE_READERS --> DOMAIN + COMPOSITION --> FORMAT_READERS + FORMAT_READERS --> DOMAIN + SERVER --> RUNTIME + CLI --> RUNTIME + RUNTIME --> DOMAIN + PROCESS --> FILESYSTEM + AUX --> FILESYSTEM + APP --> FILESYSTEM ``` </details> 🤖 Written with Claude Code (Sonnet 5.5, verified by Opus 5.5), posted with my OK 🦊

bsakaguchi closed this issue

2026-10-31 00:47:55 +00:00

bsakaguchi referenced this issue

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

[PR #4238] [MERGED] fix(lifecycle): preserve ownership, cancellation, and cleanup outcomes #6141