[GH-ISSUE #491] [Feature] Inspect one native instruction with structured operand facts #266

New issue

Closed

opened 2026-10-15 18:23:12 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-15 18:23:12 +00:00

Owner

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

Current limitation

read_function_instructions returns raw instruction strings for an entire function, while procedure_assembly returns provider-specific text. Function dossiers provide useful aggregate control-flow and reference facts, but callers cannot request normalized instruction facts at one exact address. An analyst often has to fetch and parse a whole function listing to answer a local question about an operand, branch, or memory access.

Desired outcome

Add a read-only primitive for one explicit instruction address. Return the decoded instruction facts the provider can substantiate:

canonical artifact/program identity, address, bytes, architecture/mode, mnemonic, and instruction length;
ordered operands with kind and exact register, immediate, or memory-address components when available;
control-flow classification and direct destination candidates for calls, branches, and returns;
references associated with the instruction and their observed kinds, including unavailable kind data;
decode/provider limitations and any ambiguous or unresolved components.

This should answer for one instruction only. Keep provider-specific disassembly text available as a separate raw observation; do not infer high-level source semantics, expand a full function graph, or claim a computed target was resolved without evidence.

Acceptance criteria

Input identifies one reproducible address and analysis document/program.
Results preserve exact bytes, architecture, address, provider/version, and evidence for every decoded fact.
Invalid boundaries, data addresses, undecodable instructions, and unsupported architectures have distinct outcomes.
Direct and indirect calls, conditional branches, memory operands, and architecture-specific addressing modes have fixture coverage for supported providers.
Provider coverage is explicit and provider-neutral semantics do not imply identical decoder detail.
Existing full-function instruction and dossier operations remain composable with the primitive rather than being replaced by a large combined operation.

#54 Complete Hopper function dossiers with real references and CFG edges
#490 Resolve indirect call targets as a provider-neutral primitive

Originally created by @morluto on GitHub (Oct 1, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/491 ## Current limitation `read_function_instructions` returns raw instruction strings for an entire function, while `procedure_assembly` returns provider-specific text. Function dossiers provide useful aggregate control-flow and reference facts, but callers cannot request normalized instruction facts at one exact address. An analyst often has to fetch and parse a whole function listing to answer a local question about an operand, branch, or memory access. ## Desired outcome Add a read-only primitive for one explicit instruction address. Return the decoded instruction facts the provider can substantiate: - canonical artifact/program identity, address, bytes, architecture/mode, mnemonic, and instruction length; - ordered operands with kind and exact register, immediate, or memory-address components when available; - control-flow classification and direct destination candidates for calls, branches, and returns; - references associated with the instruction and their observed kinds, including unavailable kind data; - decode/provider limitations and any ambiguous or unresolved components. This should answer for one instruction only. Keep provider-specific disassembly text available as a separate raw observation; do not infer high-level source semantics, expand a full function graph, or claim a computed target was resolved without evidence. ## Acceptance criteria - Input identifies one reproducible address and analysis document/program. - Results preserve exact bytes, architecture, address, provider/version, and evidence for every decoded fact. - Invalid boundaries, data addresses, undecodable instructions, and unsupported architectures have distinct outcomes. - Direct and indirect calls, conditional branches, memory operands, and architecture-specific addressing modes have fixture coverage for supported providers. - Provider coverage is explicit and provider-neutral semantics do not imply identical decoder detail. - Existing full-function instruction and dossier operations remain composable with the primitive rather than being replaced by a large combined operation. ## Related - #54 Complete Hopper function dossiers with real references and CFG edges - #490 Resolve indirect call targets as a provider-neutral primitive

bsakaguchi

2026-10-15 18:23:12 +00:00

closed this issue
added the
area: native

enhancement
labels

bsakaguchi commented

2026-10-15 18:23:13 +00:00

Author

Owner

@morluto commented on GitHub (Oct 8, 2026):

Verified fixed on main (7a7460f0). Tool is in OFFICIAL_TOOL_CONTRACTS with schemas and Ghidra bridge dispatch (ReaGhidraBridge.java), satisfying the at-least-one-provider acceptance. contractSnapshot.test.ts passes. Closing per audit.

@morluto commented on GitHub (Oct 8, 2026): Verified fixed on main (7a7460f0). Tool is in OFFICIAL_TOOL_CONTRACTS with schemas and Ghidra bridge dispatch (ReaGhidraBridge.java), satisfying the at-least-one-provider acceptance. contractSnapshot.test.ts passes. Closing per audit.

bsakaguchi referenced this issue

2026-10-16 21:12:29 +00:00

[PR #274] [MERGED] feat(mcp)!: harden contracts and Evidence references #1918

bsakaguchi added

enhancement

and removed

enhancement

labels

2026-10-31 00:28:57 +00:00