Implementation status
The architecture documents define the target. The current implementation runs recovery through the server and CLI.
Implemented
- Static Ghidra evidence, type context, call edges, and SCC membership.
- Explicit import-thunk and non-executable entry classification before paid analysis.
- Component dependency barriers for queued, running, batched, and uncertain callee work.
- Runtime trace validation, idempotent ingestion, observed call edges, and citable runtime artifacts.
- A managed Frida recorder with launch/attach, markers, manual Stop, automatic import, and recorded-function analysis.
- Durable journals, interrupted-session recovery, and native Ghidra coverage bookmarks with save verification.
- Selected argument slots, returns, allocation lifetimes, snapshots, calls, blocks, and bounded x86-64 MOV memory observations.
- Coverage reports with per-scenario marginal coverage and unresolved-region ranking.
- Structured structures, enums, pointers, arrays, function pointers, and method signatures.
- Layout validation, evidence-linked proposals, Jev assessment, and bounded provider accounting.
- Optional provider JSON Schema responses and numbered evidence for citation checks.
- Exact Ghidra previews, transactional type changes, class namespaces, and operation reconciliation.
- Refreshed decompilation without loss of historical evidence, reviews, or accounting.
- Evidence-driven recovery passes with fixed context budgets and early stopping when native type, execution, and runtime evidence is unchanged.
- Persistent iteration status through
recovery-status. - C++ pointer-table and RTTI evidence, runtime virtual dispatch, base layouts, typed vtable data, and stable local-variable refinement.
- Native Ghidra desktop ownership, save verification, and reopening saved projects without replaying definitions.
- Bounded function, caller, cross-reference, memory and pointer-table queries through MCP, stdio and the CLI.
- Durable research annotations and type previews with saved markers, conflict checks and cancellation reconciliation.
- Build-pinned PE x64 instruction fixtures with Unicorn, Capstone and exact translation comparisons.
- Live extraction and analysis reports, measured estimates, and downloadable status snapshots.
Current boundaries
The integrated recover command processes components in dependency order and runs members of a component concurrently.
The ordinary analysis scheduler can also run independent ready components concurrently.
Parallel component recovery with coordinated type writes remains an optimization.
Type application currently re-exports the whole Ghidra program. Only changed evidence invalidates prior results, but targeted export remains an optimization for large programs.
The collector targets one main module. Configured allocator profiles use allocation/release functions with explicit argument slots. Memory instruction tracing currently covers scalar x86-64 MOV operations. Other instructions and architectures need adapters. Multi-module capture, floating-point argument decoding, and arbitrary allocator contracts remain extensions.
Type recovery supports explicit base subobjects, multiple vptrs, typed vtable bindings, and local refinements. Unions, bitfields, overlapping base layouts, and explicit parameter storage remain unsupported. See C++ recovery for evidence, writeback, and platform limits. The system preserves unresolved facts rather than manufacturing these layouts.
Runtime session management and recorded-function analysis have web controls. The server applies supported fields and runs bounded reanalysis automatically. The CLI uses the same durable recovery phases. Parameter candidates now receive isolated native trials after type writeback. AI names and types are tested independently, and direct-call constraints supply additional candidates. See parameter experiments. Uncertain fields are deferred without manual review. Provider errors and unreconciled writeback failures remain explicit operational failures.
Validation
Focused research tests cover both headless Ghidra and its live CodeBrowser connection. They verify queries, saved annotations, stale preview rejection, type writeback and exact-operation retries. MCP tests cover protocol negotiation, shared writer ownership and cancellation cleanup.
PISTON_TEST_GHIDRA_HOME=/path/to/ghidra \
cargo test --lib research::tests::native_focused -- --ignored
Set PISTON_TEST_GHIDRA_DESKTOP=1 to run this fixture through the live desktop bridge on a test display.
The focused research round trip has passed on Linux with Ghidra 12.0.4 and JDK 25.
The synthetic native-runner tests run in CI on Ubuntu, Windows and macOS.
These jobs verify instruction fixtures, rather than native game joins on those platforms.
Targeted tests cover dependency barriers, recursive snapshots, runtime identity, allocation bounds, idempotent import, and invalid layouts. A real Ghidra round trip creates a structure, applies a method signature, and re-decompiles field accesses. The optional recovery integration test uses real Ghidra with local deterministic model responses. It does not spend OpenRouter credits.
PISTON_TEST_GHIDRA_HOME=/path/to/ghidra \
cargo test --test recovery real_ghidra -- --ignored --nocapture
Set PISTON_TEST_GHIDRA_DESKTOP=1 to test the native desktop connection as well.
This test saves recovered definitions, terminates that Ghidra process, and opens a new process against the same project.
It verifies preserved fields, method namespace, and decompilation without importing or applying the type plan again.
Run it on a test display when available to avoid interrupting desktop work.
Run the C++ integration test with the recorder’s Python environment:
PISTON_TEST_GHIDRA_HOME=/path/to/ghidra \
PISTON_TEST_PYTHON=/path/to/python-with-frida \
cargo test --test cpp native_cpp -- --ignored
This test uses both symbol-bearing and stripped C++ fixtures. It verifies secondary base pointers, adjustor thunks, and saved refinements without provider calls.