You compiled ledger.c with clang -O1, and you want to know what the machine code of percent_change does when before is 0. You can open the file in Ghidra and read the listing yourself. You can also ask rea, and rea asks Ghidra for you and returns one record that says what it found and how it knows. This section draws the line between the two programs.

When you finish this section, you can name what rea adds to Ghidra, what it never does, and which adapter to use for one question.

Three things rea standardizes

Evidence: the one record type that every successful analysis call returns. It is a strict object with 16 fields. The fields are evidence_id, subject, provider, analysis_profile, predicate_type, operation, parameters, raw_result, normalized_result, confidence, authority, environment, limitations, relationship_coverage, locations, and evidence_links.

The id is ev_ and a SHA-256 of the semantic content. The same observation of the same bytes gets the same id on any machine. When relationship_coverage is null, the id leaves it out. confidence is one of observed, derived, or inferred, and authority says what kind of source backs the fact.

The MCP docs state the rule for tools: "Evidence-producing tools return the complete canonical Evidence record in both text and structured content." mcp Tool results. Section 1.2 reads one record field by field, and Part 5 covers the record in full.

Provider: an analysis engine behind one interface. GhidraProvider implements AnalysisProviderCandidate and offers identity(), capabilities(), inspectAvailability(), inspectTargetSupport(target), resolveAnalysisProfile(...), and createClient(...). At 6.5.0 the session holds three deep providers, hopper, ghidra, and ida, plus auxiliary providers that need no engine. The registry sorts candidates by id and selects one without starting it, and "Registration order never affects selection or caller-visible output". Once bound, a provider stays bound: "A selected provider is never replaced automatically after a runtime failure." mcp Identity and discovery.

Adapter: the way a caller reaches the session. The one-shot CLI has 153 commands and one alias, and the MCP server has 207 tools and 6 prompts. The capture's server_identity.catalog.counts reports those numbers (capture/out/02-capabilities.json). Both adapters share one BinarySession, which "Owns the single active target shared by CLI and MCP adapters". CLI names use hyphens and MCP names use _ between words. The native family breaks the rule: rea function calls analyze_function, rea decompile calls procedure_pseudo_code, and rea analyze calls binary_overview.

The capture used both adapters on the same file:

$ rea doctor --provider ghidra --format json --filter-output healthy,environment_healthy,scope,scope_checks
[exit 0] (… s) -> 01-doctor-ghidra.json

$ rea capabilities --format json
[exit 0] (… s) -> 02-capabilities.json

$ rea inspect-artifact fixtures/ledger-arm64-O1 --format json
[exit 0] (… s) -> 03-inspect-artifact.json

$ rea inspect-binary-layout fixtures/ledger-x86_64-O1.o --format json
[exit 1] (… s) -> 04-inspect-binary-layout.json
…

The first three commands finish in about one second, because none of them starts Ghidra. The fourth fails, and section 3.2 explains why. Figure 1.1 places each name on its side of the line.

What rea leaves to Ghidra

rea has no disassembler and no decompiler of its own. For a native executable it starts analyzeHeadless on a fresh temporary project and imports a private copy of the file. It lets Ghidra's default auto-analysis run, and then it asks questions over a socket. The answers are Ghidra's. The function dossier "combines Ghidra FunctionManager, Listing, ReferenceManager, BasicBlockModel, and decompiler observations", as every analyze_function record says in its limitations (capture/out/06-function-percent-change.json). The provider docs draw the same line: "pseudocode is Ghidra decompiler output. Neither is original source" ghidra Admitted function-analysis semantics.

Bridge: ReaGhidraBridge.java, a GhidraScript that analyzeHeadless runs as its last post-script and that then serves requests on a Unix socket. A request is one JSON line, { id, token, method, params }, and a reply is { id, ok: true, result } or { id, ok: false, error }. The bridge answers 16 inventory methods and 13 function methods through one Java switch. Part 4 follows each of them.

Ghidra also owns the cost. Each one-shot command that needs Ghidra took 7 to 9 s on the capture Mac (capture/README.md, capture/out/00-commands.txt). The import and the auto-analysis take most of that time. Inside one MCP session the first Ghidra call took 5 to 7 s (capture/README.md, capture/out/10-mcp-session.txt). Every later call on the same file took under 100 ms.

What rea reads by itself

Before any engine runs, rea reads the file. It detects ELF from 7f 45 4c 46, MZ, and the four Mach-O magic values. It hashes every target with SHA-256 in 64 KiB chunks. It knows eight architectures: x86, x86_64, arm, arm64, mips, 6502, riscv, and powerpc. A raw binary has no header, so the caller names its architecture.

Two commands show the result without Java. rea inspect-artifact walks the file with the provider rea-artifact-graph and returns an Evidence record in under a second, without Java (capture/out/03-inspect-artifact.json). On macOS, rea inspect-macho runs the Xcode tools through xcrun and took about three seconds (capture/out/04-inspect-macho.json). Part 3 reads those records.

Formats beyond native code

Release 6.5.0 adds three readers. inspect-wasm-artifact reads a WebAssembly module through the WABT tools. inspect-go-binary reads Go build information. The raw-binary format opens a file that has no header, at an architecture that you name. The capture ran inspect-wasm-artifact on the fixture module, and the command exited 0 (capture/out/16-inspect-wasm-artifact.json). Section 6.2 reads that record.

Sources:mcp Tool results, Identity and discovery (rea docs/mcp-contracts.md); ghidra Admitted function-analysis semantics (rea docs/ghidra-provider.md); rea at 3b79af2: src/domain/evidence.ts, src/ghidra/GhidraProvider.ts, src/composition/binary.ts, src/application/binary/AnalysisProviderRegistry.ts, src/application/binary/BinarySession.ts, src/cliCommandNames.ts, src/ghidra/GhidraClient.ts, src/ghidra/GhidraClientWire.ts, src/ghidra/protocol.ts, src/ghidra/GhidraInventoryValues.ts, src/ghidra/GhidraFunctionValues.ts, bridge/ghidra/ReaGhidraBridge.java, src/domain/binaryTarget.ts, src/application/BinaryTargetResolver.ts, src/domain/binaryTargetTypes.ts, src/catalogIdentity.ts, src/go/GoBinaryProvider.ts, src/wasm/WabtArtifactProvider.ts, docs/architecture.mermaid; capture/README.md; capture/out/00-commands.txt, 00-fixtures.txt, 02-capabilities.json, 03-inspect-artifact.json, 04-inspect-macho.json, 05-analyze-arm64-O1.json, 06-function-percent-change.json, 10-mcp-session.txt, 16-inspect-wasm-artifact.json

You typed rea function fixtures/ledger-arm64-O1 _percent_change --provider ghidra --format json. About eight seconds later, 1881 lines of JSON arrived on stdout, and the exit status was 0. Somewhere in there is the answer to your question about before == 0, next to a decompiler artifact that the source never had.

When you finish this section, you can read every top-level field of that record and say which part of the system wrote it. You can also point at the one place where Ghidra's pseudocode and your C disagree.

The command

$ rea function fixtures/ledger-arm64-O1 _percent_change --provider ghidra --format json
[exit 0] (… s) -> 06-function-percent-change.json

function takes a path and a procedure, and it runs the MCP operation analyze_function with { procedure } as its parameters. --provider ghidra names the engine, and --format json and --filter-output are read at the executable boundary before the command runs. Without --format, the terminal output is TOON, and exit 0 means "The operation completed. Its result may include partial evidence, warnings or unresolved questions." cli Output and exit status. Figure 1.2 follows the call through the system.

From the command to the bridge

1. The session parses the Mach-O header, reads the architecture, and hashes the file. The record's subject carries the result: mach-o, arm64, and the SHA-256 that 00-fixtures.txt lists for ledger-arm64-O1.
2. The registry selects ghidra, because the command asked for it, and records selection_source: "request".
3. The provider builds the analysis profile, a list of versioned contract names such as function_body_evidence: "complete-inclusive-ranges-v1", and hashes it. The digest 966e6016… in the record is this hash.
4. The client makes a private runtime root and allocates bridge.sock. It copies the file as target-<sha256[0:12]>.bin while hashing it again. Then it launches java with ghidra.Ghidra ghidra.app.util.headless.AnalyzeHeadless, -import, -readOnly, and -deleteProject. The copy is target-01b5d08b08fb.bin, and the overview record shows that name as its document (capture/out/05-analyze-arm64-O1.json). The startup deadline is 330,000 ms.
5. The client sends ping. It accepts the session only when run_id, the token, the profile digest, the target SHA-256, and analysis_complete all match.
6. The client writes one JSON line that asks for analyze_function. Ghidra runs the analysis and writes one JSON line back.
7. rea adds the operation's limitation sentences to the answer and stores the result as one Evidence record.
8. The client sends shutdown with a 10 s deadline, and Ghidra deletes the project.

The record, field by field

{
  "evidence_id": "ev_172d39ff…",
  "subject": {
    "name": "ledger-arm64-O1",
    "digest": {
      "sha256": "01b5d08b…"
    },
    "local_path": "$CAPTURE/fixtures/ledger-arm64-O1",
    "format": "mach-o",
    "architecture": "arm64"
  },
  "provider": {
    "id": "ghidra",
    "name": "Ghidra",
    "version": "12.1.4"
  },
…

evidence_id hashes the semantic content and leaves out subject.name and subject.local_path, so the same bytes under another path give the same id. provider names the engine and its version. The next field binds the answer to the engine's settings:

  "analysis_profile": {
    "provider": {
      "id": "ghidra",
      "name": "Ghidra",
      "version": "12.1.4"
    },
    "parameters": {
      "target_kind": "executable",
      "target_format": "mach-o",
      "architecture": "arm64",
      …
      "import_mode": "ephemeral-source-immutable",
      …
      "loader": "auto-from-header",
      …
    },
    "digest": "966e6016…"
  },
  "predicate_type": "rea.analysis",
  "operation": "analyze_function",
  "parameters": {
    "procedure": "_percent_change"
  },

Analysis profile: the provider's committed settings, hashed over RFC 8785 canonical JSON. Change one contract version and the digest changes, which is how rea refuses an old snapshot (section 5.3). predicate_type is the default tag rea.analysis, and operation is the MCP name. parameters is the caller's input, and it is part of the identity.

raw_result holds the provider-native dossier under value with its own empty limitations, and normalized_result holds the same dossier as the canonical result. confidence is observed and authority is shipped-artifact, the defaults for a static read of the file on disk. environment is null, because nothing ran.

limitations has ten strings: four that every Ghidra operation carries, five for analyze_function, and one for macOS about the native decompiler (capture/out/02-capabilities.json, 06-function-percent-change.json). locations and evidence_links are empty. relationship_coverage has the status complete, and its one diagnostic says that only resolved Ghidra call references are returned. Figure 1.3 lays the 16 fields out.

Inside normalized_result

Procedure: the function identity. _percent_change is at 0x100000500, its body is one range from 0x100000500 to 0x100000517 inclusive, 24 bytes, and contains_entry is true. The FunctionManager signature reads undefined _percent_change(), because Ghidra's symbol carries no types. The decompiler's view under native_api reads ulong _percent_change(ulong param_1,int param_2) with confidence: "low" on each parameter. Your source says int percent_change(int before, int after). Both are observations, as the limitation says: "Types and calling conventions are Ghidra decompiler observations, not source declarations."

    "assembly": [
      "0x100000500: cbz w0, 0x100000514",
      "0x100000504: sub w8, w1, w0",
      "0x100000508: mov w9, #0x64",
      "0x10000050c: mul w8, w8, w9",
      "0x100000510: sdiv w0, w8, w0",
      "0x100000514: ret"
    ],

Six instructions of four bytes each make the 24 bytes. cbz w0 is your if (before == 0) return 0;, with before in w0, and mov w9, #0x64 is the 100. The pseudocode tells a longer story:

ulong _percent_change(ulong param_1,int param_2)
{
  uint uVar1;
  int iVar2;
  iVar2 = (int)param_1;
  if (iVar2 != 0) {
    uVar1 = 0;
    if (iVar2 != 0) {
      uVar1 = ((param_2 - iVar2) * 100) / iVar2;
    }
    param_1 = (ulong)uVar1;
  }
  return param_1;
}

The outer if is your guard. The inner if is not in your source. native_value_flow shows where it comes from. The operations 0x100000510#7, #8, #9, and #10 are a COPY of the constant 0, an INT_NOTEQUAL, a CBRANCH, and an INT_SDIV. All four carry the address of the sdiv instruction. Ghidra's model of sdiv gives 0 when the divisor is 0, and the decompiler printed that model as a second check.

Both checks are correct, and one is redundant, and only the source tells you which. Section 4.6 and the lifting lesson go deeper.

References: the dossier lists two incoming references. One is an UNCONDITIONAL_CALL from 0x1000006a0 inside the function Ghidra names entry at 0x1000005d0, 368 bytes long. The other is a DATA reference from 0x100008118 with no owning procedure, inside the __LINKEDIT segment that the overview lists from 0x100008000 (capture/out/05-analyze-arm64-O1.json). The one outgoing reference is the CONDITIONAL_JUMP of cbz. callers names entry, and callees is empty, because the function calls nothing. unresolved_calls is empty, and facet_availability marks all eight facets of the dossier as available.

Basic blocks: three, at 0x100000500, 0x100000504, and 0x100000514, with exclusive end values. The body range uses inclusive ends, as its contract name complete-inclusive-ranges-v1 says. Keep the two conventions apart when you compare addresses.

native_value_flow holds 13 p-code operations and 13 def-use edges with truncated: false. Every operation carries is_dead: true, and the limitation explains that the flag mirrors the Java AST and that block_membership reports the real membership. Read the limitations before the numbers, every time.

Sources:cli Output and exit status (rea docs/cli.md); rea at 3b79af2: src/cli/coreBinaryCommands.ts, src/cliCommandNames.ts, src/cliOutput.ts, src/domain/binaryTarget.ts, src/application/BinaryTargetResolver.ts, src/application/binary/AnalysisProviderRegistry.ts, src/ghidra/GhidraAnalysisProfile.ts, src/ghidra/GhidraClient.ts, src/ghidra/GhidraTargetSnapshot.ts, src/ghidra/GhidraJavaLaunch.ts, src/ghidra/GhidraLauncher.ts, src/config/providerStartupTimeout.ts, src/ghidra/GhidraClientStartup.ts, src/ghidra/GhidraSessionValues.ts, src/ghidra/GhidraClientWire.ts, bridge/ghidra/ReaGhidraBridge.java, src/ghidra/GhidraProviderClient.ts, src/server/registerEvidenceTools.ts, src/domain/evidence.ts, src/domain/analysisProfile.ts, src/domain/relationshipCoverage.ts; capture/README.md; capture/fixtures/ledger.c; capture/out/00-commands.txt, 00-fixtures.txt, 02-capabilities.json, 05-analyze-arm64-O1.json, 06-function-percent-change.json

A vendor sent you a binary, and an agent at your side can decompile it in eight seconds. Before the first command, two questions stand. Who owns the program, and what does the law allow you to do with a copy you did not write? rea asks neither question. Its DISCLAIMER.md puts the answer on you, and the statutes and decisions below say what the answer has to contain.

When you finish this section, you can say which rule lets you analyze a program, and why every target in this manual passes that test. This section reads primary sources and gives no legal advice.

The use rule at the tag

The rule is a paragraph under the heading Responsible use in DISCLAIMER.md at the tag. The README has a Disclaimer heading that sends you to that file. It also says: "REA is for lawful research, education, interoperability, software preservation, and analysis of software you own or are authorized to examine." readme Disclaimer It adds that this position covers all REA versions and distribution channels.

DISCLAIMER.md also lists the uses that the project does not support. The first item is the circumvention of DRM, licence checks, anti-cheat systems, and other protection measures. Then come game cheats, the bypass of authentication or access controls, and copies of proprietary software. The last two items are the evasion of AI provider usage policies and the resale or sharing of AI accounts.

United States: 17 U.S.C. 1201

Circumvention: under 1201(a)(3)(A), "to descramble a scrambled work, to decrypt an encrypted work, or otherwise to avoid, bypass, remove, deactivate, or impair a technological measure, without the authority of the copyright owner" law 17 U.S.C. 1201(a)(3)(A). Section 1201(a)(1)(A) forbids it.

Section 1201(f) is the reverse engineering exception, and it stacks four limits. The person must have "lawfully obtained the right to use a copy of a computer program". The circumvention must be "for the sole purpose of identifying and analyzing those elements of the program that are necessary to achieve interoperability of an independently created computer program with other programs". Those elements must "have not previously been readily available to the person". The acts must not "constitute infringement under this title" law 17 U.S.C. 1201(f)(1).

Section 1201(f)(4) defines the key word: "the term 'interoperability' means the ability of computer programs to exchange information, and of such programs mutually to use the information which has been exchanged." law 17 U.S.C. 1201(f)(4). Section 1201(j) covers security testing, which it defines as "accessing a computer, computer system, or computer network, solely for the purpose of good faith testing, investigating, or correcting, a security flaw or vulnerability, with the authorization of the owner or operator" law 17 U.S.C. 1201(j)(1).

Section 1201(f) is an exception to the anti-circumvention rule only. It does not decide whether the copies you make while analyzing infringe copyright. Section 1201(c)(1) leaves that question to copyright law: "Nothing in this section shall affect rights, remedies, limitations, or defenses to copyright infringement, including fair use" law 17 U.S.C. 1201(c)(1). The two decisions below answer it.

European Union: Directive 2009/24/EC

Article 1(2) sets the ground: "Ideas and principles which underlie any element of a computer program, including those which underlie its interfaces, are not protected by copyright under this Directive." law Directive 2009/24/EC Article 1(2). Two articles then give a lawful user two rights.

Article 5(3) is the right to study a running program: "The person having a right to use a copy of a computer program shall be entitled, without the authorisation of the rightholder, to observe, study or test the functioning of the program in order to determine the ideas and principles which underlie any element of the program if he does so while performing any of the acts of loading, displaying, running, transmitting or storing the program which he is entitled to do." law Directive 2009/24/EC Article 5(3). The Court of Justice applied it in C-406/10. There a licensee studied the SAS System to reproduce its functionality in a second program, without decompilation, and did not infringe.

Article 6(1) is the decompilation right. It needs no authorisation "where reproduction of the code and translation of its form within the meaning of points (a) and (b) of Article 4(1) are indispensable to obtain the information necessary to achieve the interoperability of an independently created computer program with other programs" law Directive 2009/24/EC Article 6(1). Three conditions follow. First, the acts are done by a person with a right to use a copy. Second, "the information necessary to achieve interoperability has not previously been readily available" law Directive 2009/24/EC Article 6(1)(b). Third, "those acts are confined to the parts of the original program which are necessary in order to achieve interoperability" law Directive 2009/24/EC Article 6(1)(c).

Article 6(2)(c) then forbids using the result "for the development, production or marketing of a computer program substantially similar in its expression" law Directive 2009/24/EC Article 6(2)(c). A contract cannot take these rights away. Article 8 says: "Any contractual provisions contrary to Article 6 or to the exceptions provided for in Article 5(2) and (3) shall be null and void." law Directive 2009/24/EC Article 8. In C-13/20 the Court added a third route. A lawful purchaser can decompile to correct errors under Article 5(1), without the Article 6 conditions, but "only to the extent necessary to effect that correction" law C-13/20 ruling 2.

Two decisions: Sega v. Accolade and Sony v. Connectix

In Sega Enterprises Ltd. v. Accolade, Inc., 977 F.2d 1510 (9th Cir. 1992), Accolade bought a Genesis console and cartridges, disassembled the object code, wrote a manual of interface requirements, and then wrote its own games. The court held: "where disassembly is the only way to gain access to the ideas and functional elements embodied in a copyrighted computer program and where there is a legitimate reason for seeking such access, disassembly is a fair use of the copyrighted work, as a matter of law." law Sega v. Accolade, 977 F.2d at 1527-1528. The only code Accolade kept was a header of 20 to 25 bytes that the console required.

In Sony Computer Entertainment, Inc. v. Connectix Corp., 203 F.3d 596 (9th Cir. 2000), Connectix copied the PlayStation BIOS into memory many times while it built an emulator that contained none of Sony's code. The court held: "The intermediate copies made and used by Connectix during the course of its reverse engineering of the Sony BIOS were protected fair use, necessary to permit Connectix to make its non-infringing Virtual Game Station function with PlayStation games." law Sony v. Connectix, 203 F.3d 596.

The court listed four ways to reach the functional elements of a program. Two of them are the static examination of the instructions and the dynamic examination of a running program, and it called both disassembly. Both decisions protect the intermediate copies and say nothing about copied code in the finished product.

The rule of this manual

Every target in this manual is a program written for it. ledger.c and ledger-main.c are the C sources, js-app/ is a six-file application, and wasm/ledger.wat is a hand-written module. The capture kit records their hashes and sizes:

01b5d08b…   33872  fixtures/ledger-arm64-O1
…
8bbbaa58…   33872  fixtures/ledger-arm64-O2
…
80af384b…     743  fixtures/ledger-main.c
…
4564c3e7…     568  fixtures/ledger.c
…
699f6ff7…     290  fixtures/wasm/ledger.wasm
2e0b5792…    1841  fixtures/wasm/ledger.wat

For these files the five questions in figure 2.1 answer themselves. You hold the copy because you compiled it. The purpose is study. No other way is needed because the source is beside the binary, and the comparison of the two is the point. The whole program is yours, so the parts and the expression are yours.

This manual never analyzes a protection, a licence check, an anti-tamper scheme, a game, or a program you do not own. It never instruments a running program other than its own fixtures.

For any other program, answer the five questions first and write the answers down. Start from a copy you obtained lawfully. Name the purpose the law names. The law names interoperability under 1201(f) and Article 6, study under Article 5(3), and error correction under Article 5(1). It also names security testing with the owner's authorization under 1201(j).

Check that the facts are not already published. Confine the work to the parts you need, and make the final product your own expression. Where a licence or a contract says more, read it. Section 1201(f) does not override contract law, and Article 8 voids only terms contrary to Articles 5(2), 5(3), and 6.

Sources:readme Disclaimer (rea README.md); rea DISCLAIMER.md, Responsible use, at 3b79af2; law: 17 U.S.C. 1201(a)(1)(A), (a)(3)(A), (c)(1), (f)(1), (f)(4), (j)(1), Directive 2009/24/EC Articles 1(2), 5(1), 5(3), 6(1), 6(2)(c), 8, CJEU C-406/10 and C-13/20, Sega v. Accolade, 977 F.2d 1510, Sony v. Connectix, 203 F.3d 596; capture/out/00-fixtures.txt

You installed rea with npm and Ghidra with Homebrew, and your first rea function ended with provider_unavailable. The message tells you to run rea doctor. The report has nine checks for the Ghidra scope, each with a name, an ok flag, and the path or version it found. The first check that fails names the fix.

When you finish this section, you can read a doctor report, name the check that failed, and repair the install from its remediation text.

What the Ghidra provider needs

Ghidra provider: the rea adapter that drives an existing Ghidra install through analyzeHeadless. It needs two absolute paths from the environment, GHIDRA_INSTALL_DIR and JAVA_HOME, and it rejects relative ones. The policy fixes the versions: SUPPORTED_GHIDRA_VERSION = "12.1.4" and SUPPORTED_GHIDRA_JAVA_MAJOR = 21. The docs say what that means in practice: "It accepts Ghidra 12.1.x and the 64-bit full JDK declared by that installation's application.java.min and application.java.max." install Ghidra. The install must also hold the native decompiler for the host, under Ghidra/Features/Decompiler/os/<platform>/, and "REA does not build or install native tools, or change Gatekeeper quarantine settings." install Ghidra.

On the capture Mac, Homebrew put both tools in place:

…
GHIDRA_INSTALL_DIR=/opt/homebrew/Cellar/ghidra/12.1.4/libexec
application.build.date=2026-Sep-21 2017 GMT
application.version=12.1.4
application.release.name=PUBLIC

JAVA_HOME=/opt/homebrew/opt/openjdk@21
$ /opt/homebrew/opt/openjdk@21/bin/java -version
openjdk version "21.0.12.1" 2026-08-18
OpenJDK Runtime Environment Homebrew (build 21.0.12.1)
OpenJDK 64-Bit Server VM Homebrew (build 21.0.12.1, mixed mode, sharing)
[exit 0]
…

The install docs give the same shape for any host: "Extract Ghidra and install the JDK outside REA, then export absolute paths:" install Ghidra. On a Mac with Homebrew, that is:

export GHIDRA_INSTALL_DIR=/opt/homebrew/Cellar/ghidra/12.1.4/libexec
export JAVA_HOME=/opt/homebrew/opt/openjdk@21
rea doctor --provider ghidra --format json

--provider ghidra narrows the report to one scope. Without it, the report also covers the Hopper, IDA, and JADX providers, the installed skill, and the agent registrations on the machine.

The nine checks

{
  "healthy": true,
  "environment_healthy": false,
  "scope": {
    "mode": "explicit",
    "clients": [],
    "providers": [
      "ghidra"
    ],
    "skill": false,
    "target": null
  },
  "scope_checks": [
    {
      "name": "node",
      "ok": true,
      "classification": "healthy",
      "detail": "22.22.0",
      "details": {
        "runtime": "node",
        "version": "22.22.0"
      }
    },
    …
    {
      "name": "ghidra-native_decompiler",
      "ok": true,
      "classification": "healthy",
      "detail": "/opt/homebrew/Cellar/ghidra/12.1.4/libexec/Ghidra/Features/Decompiler/os/mac_arm_64/decompile reports mach-o arm64, which matches darwin/arm64"
    },
    {
      "name": "ghidra-java",
      "ok": true,
      "classification": "healthy",
      "detail": "21.0.12.1; 64-bit; JDK; /opt/homebrew/Cellar/openjdk@21/21.0.12.1/libexec/openjdk.jdk/Contents/Home; accepted a 64-bit full JDK 21 or newer"
    }
  ]
}

inspectGhidraInstallation runs the eight Ghidra checks without importing anything. Their order is configuration, platform, architecture, installation, version, headless, native_decompiler, and java, and the doctor prefixes each name with ghidra-. A node check comes first. The table names what each one reads and the code it returns when it fails.

The native decompiler check reads the executable header of the decompile binary and compares it with the host. A build for another platform is therefore "reported as incompatible instead of being admitted from its directory name" install Ghidra. The docs summarize the set: "Doctor validates the platform, architecture, Ghidra 12.1.x application version, support/analyzeHeadless or support/analyzeHeadless.bat, the installation's Java major range, 64-bit JDK bitness, and the presence of javac/javac.exe." install Ghidra. Figure 2.2 draws the nine in order.

healthy and environment_healthy

The report has two verdicts. healthy is the verdict for the selected scope, here explicit with providers: ["ghidra"], and scope_checks lists only the checks in that scope. environment_healthy is the verdict for the audit-wide set. It is true only when every check outside the providers passes, every configured provider passes, and at least one provider is available.

On the capture Mac healthy is true and environment_healthy is false. Hopper and IDA are not configured there, so the formula ignores them, and Ghidra is configured and passes. The false verdict therefore comes from a check outside the Ghidra scope. That check is in the set the capture's --filter-output left out, which names this user's skill install and agent registrations (capture/README.md). The exit status follows the scope: rea doctor returned 0 (capture/out/00-commands.txt), because "unavailable optional providers remain informational for unrelated tasks" cli Output and exit status.

When a check fails

The capture kit did not record a failing doctor, because Ghidra was installed. The source says what you would see. With GHIDRA_INSTALL_DIR unset, the configuration check fails with the detail GHIDRA_INSTALL_DIR is not set and the remediation Set GHIDRA_INSTALL_DIR to an extracted Ghidra 12.1.x release directory.. With a relative path, the detail is GHIDRA_INSTALL_DIR must be absolute.

A rea function --provider ghidra on such a machine fails selection with the code provider_unavailable, the category unavailable, and retryable: true. The message is The selected analysis provider is unavailable. Review the reported local diagnostics or run rea doctor, then retry.. Its details.rejections[].diagnostics.checks[] holds the same eight checks as the doctor. Section 2.3 shows those diagnostics inside rea capabilities, and the errors reference lists the codes.

One check has no fix in rea. Every Ghidra record on macOS carries the limitation that "macOS sessions require a matching executable Ghidra native decompiler; REA checks for it but does not build native components or change Gatekeeper quarantine state." (capture/out/06-function-percent-change.json). If the Homebrew build of decompile is missing or quarantined, you repair Ghidra, not rea.

Sources:install Ghidra (rea docs/installation.md); cli Output and exit status (rea docs/cli.md); rea at 3b79af2: src/config/environment.ts, src/ghidra/GhidraInstallationPolicy.ts, src/ghidra/GhidraInstallation.ts, src/ghidra/GhidraDoctor.ts, src/application/Doctor.ts, src/application/DoctorDiagnostics.ts, src/application/DoctorProviderIds.ts, src/domain/providerSelectionError.ts, src/domain/analysisErrorProjection.ts; capture/README.md; capture/out/00-commands.txt, 00-versions.txt, 01-doctor-ghidra.json, 06-function-percent-change.json

An agent is about to call a tool on a file you gave it. Some rea operations start a Java process, and some write a runtime directory. Three edit the names in the analysis database, and a Hopper operation would open a window. You want that list before the call, not after. rea capabilities prints it, and the same record reaches an agent as the MCP tool binary_session.

When you finish this section, you can read a capability group, name the seven effect flags, and pick the operations that change nothing.

The command and its record

capabilities and providers are registered together, and capabilities is described as "List provider capabilities and side effects". Both print the session status, the same object that binary_session returns over MCP. With no target open it starts open: false:

{
  "open": false,
  "capabilities": [
    {
      "provider": {
        "id": "native-macos",
        "name": "macOS native inspection utilities",
        "version": null
      },
      "shared_limitations": [
        "Availability and textual formats depend on the installed macOS/Xcode toolchain."
      ],
      "groups": [
        {
          "operations": [
            "capture_native_ui_scenario",
            "observe_native_calls"
          ],
          "effects": [
            "launches_process",
            "may_show_ui",
            "may_access_network",
            "may_write_filesystem"
          ],
          "limitations": [],
          "available": true,
          "reason": null,
          "availability_code": null
        },
        …
  ],
  "analysis_provider_binding": null,
  "analysis_provider_candidates": [
    {
      "provider": {
        "id": "ghidra",
        "name": "Ghidra",
        "version": null
      },
      "availability": {
        "status": "available",
…

The record has eight top-level fields in the capture: open, capabilities, analysis_provider_binding, analysis_provider_candidates, analysis_run, analysis_activity, provider_operation_health, and server_identity. capabilities holds the 19 operations that need no bound provider, in four provider blocks: native-macos, rea-artifact-graph, rea-dotnet-static, and sqlite. Examples are inspect_artifact, inspect_macho, and the managed .NET readers. analysis_provider_candidates holds the three deep providers with their availability and their own provider blocks. analysis_provider_binding is null because no target is open, and every candidate reports target_support.status: "unknown" with the reason No target is open..

One target-free operation is not available on the capture Mac. inspect_sqlite_database has available: false and the code unsupported_version. Its reason says that it needs Node.js 24.15 or a later 24.x release, or Node.js 26 or later. The capture Mac runs Node 22.22.0.

Capability group: a list of operations that share one available flag, one list of effects, and one list of limitations. The effects list names only the flags that are true. The full limitation list of an operation is the block's shared_limitations followed by the group's limitations. When a group is not available, reason and availability_code say why. The session builds the groups from each provider's descriptors, so the field names are the same for every provider. Figure 2.3 shows one.

The seven effects

The effects list of a group names flags from a fixed set of seven. A flag that the list does not name is false for every operation of the group.

Two flags need a second look. mutates_artifact sounds like a write to your file, and it is not. A shared limitation of the Ghidra block says: "The imported Program and temporary project are ephemeral and deleted on close. Annotation operations edit session database metadata; original executable bytes are never written." (capture/out/02-capabilities.json). The three operations that set it, annotate_native_function, set_address_name, and set_addresses_names, rename symbols in Ghidra's database, and the edit dies with the session.

may_write_filesystem is true for every Ghidra operation, even list_documents. The first call writes the runtime root, the private copy, and the project (section 1.2). Figure 2.4 counts the flags per provider.

Three candidates, one bound

    {
      "provider": {
        "id": "hopper",
        "name": "Hopper Disassembler",
        "version": null
      },
      "availability": {
        "status": "unavailable",
        "code": "executable_missing",
        "reason": "Hopper launcher is missing or not executable: /Applications/Hopper Disassembler.app/Contents/MacOS/hopper",
…
    {
      "provider": {
        "id": "ida",
        "name": "IDA MCP adapter",
        "version": "1"
      },
      "availability": {
        "status": "unavailable",
        "code": "not_configured",
        "reason": "Set REA_IDA_MCP_CONFIG to an upstream IDA MCP JSON registration; see docs/ida-provider.md.",
…

The ghidra candidate is available, and its diagnostics repeat the eight checks of section 2.2 with the same paths. hopper is unavailable with the code executable_missing, and ida with not_configured. Each unavailable candidate still lists its operations, 37 for Hopper and 13 for IDA. All of them have available: true except Hopper's search_bytes, which has available: false and the reason "Masked byte search has not been verified for Hopper.".

Availability of the engine and availability of an operation are two different facts. The docs put the rule in one sentence: "These commands describe binary-session providers and auxiliary capabilities." cli Choose a provider. With --provider ghidra or provider_id: "ghidra", only the Ghidra block applies.

Limitations are part of the declaration

Every Ghidra operation carries four shared limitations before its own. The session serves operations only after default auto-analysis completes. The Program and the project are ephemeral. Cancelling a request terminates the database and discards annotations. Addresses are lowercase 0x hexadecimal in the default space (capture/out/02-capabilities.json).

Then each group adds its own, and these are the sentences to read before you trust an empty list. list_strings says: "an empty search does not establish that text is absent from the artifact." procedure_callers declares no limitation of its own. Its answer carries relationship_coverage, and the Ghidra diagnostic in that field says that only resolved call references are returned and that "unresolved computed or indirect calls remain unknown" (capture/out/06-function-percent-change.json). The design rule behind all of them is "Missing coverage is unknown, not absence." design Define the contract.

A second vocabulary in tools/list

The record ends with server_identity. Its catalog holds two things: the counts, and three SHA-256 digests of the catalog:

    "catalog": {
      "counts": {
        "cli_commands": 153,
        "mcp_tools": 207,
        "mcp_prompts": 6
      },
      "digests": {
        "tools_sha256": "805433f1…",
        "prompts_sha256": "7152916a…",
        "combined_sha256": "405725e7…"
      }
    },

The catalog has no per-tool entries. The side effects of each MCP tool are in the tool annotations that tools/list returns:

        {
          "name": "xrefs",
          "title": "Xrefs",
          …
          "annotations": {
            "readOnlyHint": false,
            "destructiveHint": false,
            "idempotentHint": true,
            "openWorldHint": false
          },
          …

In the source, xrefs has mutatesSession: true, because each answer goes into the Evidence ledger. rea derives the annotations from those effects, so readOnlyHint is false. The provider capability of xrefs still does not name mutates_artifact. The two vocabularies answer two questions. The capability says what the engine does to your machine, and the annotations say what the tool does to the MCP session. Read the one that matches your question, and do not mix them.

Sources:cli Choose a provider (rea docs/cli.md); design Define the contract (rea docs/tool-design.md); rea at 3b79af2: src/cli/utilityCommands.ts, src/application/binary/BinarySessionStatus.ts, src/contracts/toolOutputSchemaPrimitives.ts, src/contracts/toolEffects.ts, src/serverIdentity.ts, src/catalogIdentity.ts, src/domain/relationshipCoverage.ts, bridge/ghidra/ReaGhidraBridge.java; capture/out/02-capabilities.json, 06-function-percent-change.json, 10-mcp-02-tools-list.json

You built ledger-arm64-O1 from ledger.c and ledger-main.c with clang. An agent is about to analyze it, and you want the first call to be cheap, offline, and honest about what it did not do. inspect-artifact is that call. It needs no Ghidra, it returns in about a second, and its record ends with the name of the next tool.

When you finish this section, you can run inspect-artifact on a file you built and read its manifest and its one occurrence. You can also say why the record names open_binary as the next probe.

One command, one record

$ rea inspect-artifact fixtures/ledger-arm64-O1 --format json
[exit 0] (…) -> 03-inspect-artifact.json

The record comes from the provider rea-artifact-graph, named "REA safe artifact graph provider", version 1. No analysis engine runs. The tool opens the file, hashes it, names the format from the header, and builds an inventory of the file as a container.

Artifact graph: the inventory rea builds of one file and the files inside it. A node is one distinct content, identified by its SHA-256. An occurrence is one place where that content appears, with a logical path. An edge joins a container to a member.

{
  "evidence_id": "ev_3823d30d…",
  "subject": {
    "name": "ledger-arm64-O1",
    "digest": {
      "sha256": "01b5d08b…"
    },
    "local_path": "$CAPTURE/fixtures/ledger-arm64-O1",
    "format": "mach-o",
    "architecture": null
  },
  "provider": {
    "id": "rea-artifact-graph",
    "name": "REA safe artifact graph provider",
    "version": "1"
  },
  …
  "operation": "inspect_artifact",
  "parameters": {
    "integrity_policy": "fail"
  },
  …
}

The SHA-256 is the one 00-fixtures.txt lists for the file, and every later record about this file carries the same digest. The format is mach-o, read from the magic bytes. The architecture is null. This provider does not read cputype, and the next section shows the tool that does. The one parameter is integrity_policy, set to fail.

The manifest and the occurrence

The record has one substep, inventory_artifact, with status: "completed" and its own Evidence record nested inside. Its manifest counts the graph.

"manifest": {
  "manifest_id": "agm_8e2e5c4c…",
  …
  "graph_sha256": "b6c8ab6f…",
  "node_count": 1,
  "occurrence_count": 1,
  "edge_count": 0
},
"nodes": [
  {
    "artifact_id": "art_8906b5a7…",
    "format": "mach-o",
    "sha256": "01b5d08b…",
    "size": 33872,
    …
    "content_state": "materialized",
    "limitations": []
  }
],
"occurrences": [
  {
    "occurrence_id": "occ_35a9bb48…",
    …
    "logical_path": ".",
    "entry_kind": "file",
    "artifact_kind": "executable",
    "artifact_format": "mach-o",
    "declared_size": 33872,
    …
    "executable": true,
    "encrypted": false,
    "hash_status": "verified",
    …
  }
],

One node, one occurrence, no edges. The executable is its own container and has no members. The limitation "Artifact has no child container entries." says the same in words. The node reports size: 33872, the byte count in 00-fixtures.txt, and content_state: "materialized". The occurrence has logical_path: ".", the root, and artifact_kind: "executable". For an .asar or a .zip, this is where every member file would appear with its own node and path.

Branches and the next probe

"unexplored_branches": [
  {
    "branch_id": "aib_38d39810…",
    "reason": "format-specific-analysis-required",
    "detail": "open_binary was not run by provider-neutral artifact inspection.",
    "next_probe": {
      "operation": "open_binary",
      "rationale": "Bind one deep native provider before function-level analysis.",
      "authority": "native-analysis-provider"
    },
    …
  }
],
…
"confidence": "observed",
"authority": "shipped-artifact",
"environment": null,
"limitations": [
  "Artifact has no child container entries.",
  "Inspection derives bounded static hypotheses and next probes; it does not execute the artifact or claim format-specific semantics."
],

rea builds one unexplored branch for every next probe it lists, with the reason format-specific-analysis-required. The second limitation is a constant in the same file. The record is observed with authority shipped-artifact: rea read the bytes of the file you gave it and derived nothing from another record. The coverage block reports complete-within-substeps with one substep, one observation, one branch, one probe, and nothing omitted.

What the record is not

The record is not a format parse. It holds no load commands, no sections, no symbols, and no entry point. For those, the next section runs inspect-macho. For a function, Part 4 binds Ghidra with open_binary, the tool the branch names. The whole record is 198 lines, and most of them repeat the subject digest. That repetition is the point: every nested record can stand alone and still name the same bytes.

Sources:capture/out/00-commands.txt, capture/out/00-fixtures.txt, capture/out/03-inspect-artifact.json; rea 6.5.0 at 3b79af2: src/application/InvestigationProviders.ts, src/domain/artifactInspection.ts, src/artifacts/inventory/reader.ts

You ran rea inspect-binary-layout fixtures/ledger-x86_64-O1.o --format json on the capture Mac. It exited 1 and printed a JSON error instead of a layout. Nothing is broken. rea 6.5.0 has two engine-free layout readers, and this one runs on Linux x64 only.

When you finish this section, you can read that error envelope and name the host rule behind it. You can also read the load image of ledger-arm64-O1 from inspect-macho: four segments, 17 load commands, six imports, and six exports.

The error envelope

{
  "code": "capability_unavailable",
  "category": "unsupported_provider",
  "message": "The initial real-verified pwntools artifact profile supports Linux x64 only.",
  "retryable": false,
  "remediation": {
    "action": "The initial real-verified pwntools artifact profile supports Linux x64 only."
  },
  "details": {
    "provider_id": "pwntools-elf",
    "operation": "inspect_binary_layout",
    "reason": "The initial real-verified pwntools artifact profile supports Linux x64 only."
  }
}

Every failure in rea has this shape: code, category, message, retryable, remediation.action, and an optional details object. The provider is pwntools-elf. Its decoder throws AnalysisCapabilityUnavailableError when process.platform is not linux or process.arch is not x64, before it looks for Python. The message is a constant in the same file. The MCP server lists the tool as unavailable unless the host is Linux x64 and REA_PWNTOOLS_PYTHON is an absolute path. The exit status follows the CLI rule: "The operation could not complete." cli §Output and exit status

The capture kit gave the tool the ELF object because inspect_binary_layout is written for ELF. On a Linux x64 host with pwntools 4.15.0 it returns sections, segments, symbols, and relocations. Section 2.3 shows how each operation declares its availability before you call it, and the reference lists every error code the captures produced.

inspect-macho and the tools it runs

inspect-macho is the macOS reader, from the provider native-macos, "macOS native inspection utilities". It runs seven host commands and records each one as provenance.

"provenance": [
  {
    "tool": "lipo",
    "command": [
      "/Library/Developer/CommandLineTools/usr/bin/lipo",
      "-detailed_info",
      "$ARTIFACT"
    ],
    …
  },
  {
    "tool": "otool",
    "command": [
      "/Library/Developer/CommandLineTools/usr/bin/llvm-otool",
      "-h",
      "-l",
      "$ARTIFACT"
    ],
    …
  },
  {
    "tool": "nm",
    …
  },
  {
    "tool": "dyld_info",
    "command": [
      "/Library/Developer/CommandLineTools/usr/bin/dyld_info",
      "-imports",
      "$ARTIFACT"
    ],
    …
  },
  {
    "tool": "dyld_info",
    …
  },
  {
    "tool": "dwarfdump",
    …
  },
  {
    "tool": "vtool",
    …
  }
],

The command list is fixed in the provider. It runs lipo -detailed_info to discover the slices. For each slice it runs otool -h -l, nm -gjU --no-dyldinfo, dyld_info -imports, dyld_info -exports, and dwarfdump --uuid. It runs vtool -show-build as an optional extra. The run starts no Java and takes a few seconds. Keep one limitation of the record in mind when a name you expect is missing: "Imports and exports combine dyld_info and nm; stripped or toolchain-hidden symbols may be absent."

The load image

"format": "mach-o",
"selected_architecture": {
  "name": "arm64",
  "container_file_offset": 0
},
"endian": "little",
"word_size": 64,
"file_type": "2",
"flags": [
  "0x00200085"
],
"uuid": "59A1CCA5-97D1-3661-99DA-666BC2BB38D7",
"entrypoints": {
  "items": [
    {
      "file_offset": 1488
    }
  ],
  …
},
…
"build_metadata": {
  "items": [
    {
      "platform": "MACOS",
      "minimum_os": "26.0",
      "sdk": "26.2",
      …

Load command: one record in the list that follows the Mach-O header, with a cmd type and a cmdsize. Apple publishes no prose specification, so the loader.h header in the XNU source is the reference. file_type 2 is MH_EXECUTE. The flags 0x00200085 are MH_NOUNDEFS 0x1, MH_DYLDLINK 0x4, MH_TWOLEVEL 0x80, and MH_PIE 0x200000 added together. The entry point comes from LC_MAIN, whose entryoff is 1488, or 0x5d0. Add it to the __TEXT address below and you get 0x1000005d0, the _main export.

The four LC_SEGMENT_64 commands are the load image. Each segment_command_64 names a vmaddr, a vmsize, a fileoff, a filesize, two protection fields, and nsects, and its section_64 records follow inside the same command.

{
  "name": "__TEXT",
  "vm_address": "0x100000000",
  "vm_size": 16384,
  "file_offset": 0,
  "file_size": 16384,
  …
  "sections": {
    "items": [
      {
        "segment": "__TEXT",
        "name": "__text",
        "address": "0x100000500",
        "size": 576,
        "file_offset": 1280,
        …
      },
      {
        "segment": "__TEXT",
        "name": "__stubs",
        "address": "0x100000740",
        "size": 48,
        "file_offset": 1856,
        …
      },
      {
        "segment": "__TEXT",
        "name": "__cstring",
        "address": "0x100000770",
        "size": 95,
        "file_offset": 1904,
        …
      },
      {
        "segment": "__TEXT",
        "name": "__const",
        "address": "0x1000007d0",
        "size": 64,
        "file_offset": 2000,
        …
      },
      {
        "segment": "__TEXT",
        "name": "__unwind_info",
        "address": "0x100000810",
        "size": 96,
        "file_offset": 2064,
        …
      }
    ],

__PAGEZERO reserves the first 4 GiB of the address space with no file bytes, so a null pointer never reaches mapped memory. __TEXT starts at 0x100000000 and maps the first 16384 bytes of the file. Its code section __text holds 576 bytes at 0x100000500, and Part 4 accounts for every one of them. __cstring holds the format strings and the five labels, and __const holds the two lookup tables that the jump table section reads.

The __LINKEDIT segment has no sections. Other load commands point into it by file offset.

The last command ends at 33872, the file size. In ELF the loader reads a program header table and the linker reads a section header table, two tables that the ELF header points to. In Mach-O there is one list, and LC_SEGMENT_64 carries its sections inside the command. Lesson 32 builds a reader for both formats from the specifications and lines up each load command with its ELF idea.

Imports and exports

"exports": {
  "items": [
    …
    {
      "name": "_grade",
      "address": "0x100000518",
      …
    },
    {
      "name": "_grade_label",
      "address": "0x100000588",
      …
    },
    {
      "name": "_main",
      "address": "0x1000005d0",
      …
    },
    {
      "name": "_percent_change",
      "address": "0x100000500",
      …
    },
    {
      "name": "_total",
      "address": "0x100000554",
      …
    }
  ],
  "total": null,
  "exhaustive": false,
  "limitations": [
    "Merged nm/dyld_info results may be incomplete for stripped binaries."
  ]
},

Six exports: the five functions and __mh_execute_header at 0x100000000. Six imports from libSystem: ___stack_chk_fail, ___stack_chk_guard, ___stderrp, _atoi, _fwrite, and _printf.

One dependency: /usr/lib/libSystem.B.dylib. rea lists only dylib load commands as dependencies. The dynamic linker /usr/lib/dyld stays in the LC_LOAD_DYLINKER row of the load commands.

Both the imports and the exports collections say exhaustive: false, because each merges the text of two tools. The record does not promise that the list is complete, and you should not promise it either. Section 4.2 shows the same names as Ghidra sees them, and the next section turns 0x100000518 into a file offset.

Sources:capture/out/00-commands.txt, capture/out/04-inspect-binary-layout.json, capture/out/04-inspect-macho.json; rea 6.5.0 at 3b79af2: src/contracts/errorSchemas.ts, src/native/pwntools/PwntoolsDecoder.ts, src/server/createServer.ts, src/native/NativeMachoInspection.ts, src/native/parsers/otool.ts; rea docs/cli.md

inspect-macho says _grade is exported at 0x100000518. You want to open ledger-arm64-O1 in a hex viewer and read those bytes, so you need the file offset of that address. One rea command answers that question, and the Mach-O load commands let you compute the same number without rea.

When you finish this section, you can turn an address into a file offset with rea address-to-file-offset. You can do the same arithmetic from the LC_SEGMENT_64 fields, and say when the two can disagree.

The command

$ rea address-to-file-offset fixtures/ledger-arm64-O1 0x100000518 --provider ghidra --format json
[exit 0] (…) -> 08-address-to-file-offset.json

The call took 7 to 9 s on the capture Mac. Every one-shot CLI call that needs Ghidra imports the target into a fresh headless project. Section 4.1 shows that cost in detail, and the same question costs under 100 ms inside an open MCP session.

"operation": "address_to_file_offset",
"parameters": {
  "address": "0x100000518"
},
"raw_result": {
  "address": "0x100000518",
  "file_offset": 1304
},
"normalized_result": {
  "address": "0x100000518",
  "file_offset": 1304
},
"confidence": "observed",
"authority": "shipped-artifact",
…
"limitations": [
  …
  "Offsets come from Ghidra source-byte mappings, not virtual-address arithmetic. Uninitialized memory, missing mappings and ambiguous mappings fail explicitly.",
  …
],

The answer is 1304. The record is observed: Ghidra reported which file byte it loaded at that address, and rea passed the number through.

The arithmetic from the load command

File offset: the position of a byte in the file, counted from zero. Virtual address: the position of the same byte in memory after the loader maps the segment that contains it. A segment maps filesize bytes starting at fileoff to vmsize bytes starting at vmaddr, so inside one segment the two positions differ by a constant.

From the previous section, __TEXT has vmaddr 0x100000000 and fileoff 0. The rule for any byte in that segment is offset = address - vmaddr + fileoff. For _grade, that is 0x100000518 - 0x100000000 + 0, which is 0x518, which is 1304.

The section gives a second check. __text has address 0x100000500 and file_offset 1280. The function starts 0x18 bytes, 24 bytes, after the section, so its offset is 1280 + 24, again 1304. Open the fixture at byte 1304 and you find e8 cc 8c 52. That is the little-endian encoding of mov w8, #0x6667, the first instruction of _grade in section 4.3.

The ELF rule has the same shape. For a loadable segment it is offset = address - p_vaddr + p_offset, and for a section it is sh_offset. Lesson 32 does that arithmetic on ledger-x86_64-O1.o. A relocatable object has no program header table, so no segment places it in memory. When section 3.4 shows .text of that object at 0x100000, the number is a placement Ghidra chose, not a fact in the file.

What Ghidra does instead

The bridge does not compute. addressToFileOffset asks Ghidra for the memory block at the address and requires an initialized block. Otherwise it fails with invalid_request and the message "Address has no initialized file-backed memory". It then walks the source mappings of the block. It keeps only a mapping whose FileBytes start at file offset 0 and whose original bytes have the SHA-256 of the admitted target. It requires exactly one such mapping, and it refuses an offset above 2^53 - 1.

The reply carries only address and file_offset. The output schema of rea also allows provider_file_offset, image_base_file_offset, and source_path, and the Ghidra provider at 6.5.0 leaves them out.

Three addresses show the three outcomes. The capture ran only the first row. The other two follow from the bridge code above.

This is why the limitation says the offsets are not virtual-address arithmetic. Your arithmetic and Ghidra's mapping agree for every byte of __TEXT, __DATA_CONST, and the 1104 used bytes of __LINKEDIT. They disagree where your formula still produces a number and Ghidra refuses. Those places are the 4 GiB of __PAGEZERO, the padding after byte 33872, and the EXTERNAL block of section 4.2.

Sources:capture/out/00-commands.txt, capture/out/04-inspect-macho.json, capture/out/08-address-to-file-offset.json, capture/fixtures/ledger-arm64-O1; rea 6.5.0 at 3b79af2: bridge/ghidra/ReaGhidraBridge.java, src/contracts/toolOutputSchemaGroups.ts

You have two builds of the same four functions: the arm64 executable ledger-arm64-O1 and the x86-64 object ledger-x86_64-O1.o. Before you read any function, you want one screen per build that says how big it is and what Ghidra made of it. rea analyze is that screen.

When you finish this section, you can run rea analyze on both builds and read the twelve and the ten segments. You can also explain why one build has 13 procedures and the other has 4.

One CLI verb, one composed operation

analyze and inspect are aliases of the MCP operation binary_overview. The operation is composed from three others. It calls list_segments, list_procedures, and list_strings on the bound provider at the same time. Then it returns the segments with their lengths and the two counts. The output schema has six fields: document, image_base, segments, segment_count, procedure_count, and string_count. Each segment can also carry image_base and address_space.

$ rea analyze fixtures/ledger-arm64-O1 --provider ghidra --format json
[exit 0] (…) -> 05-analyze-arm64-O1.json
$ rea analyze fixtures/ledger-x86_64-O1.o --provider ghidra --format json
[exit 0] (…) -> 05-analyze-x86_64-O1.json

Composed operation: a rea operation whose result is built from other operations. Its Evidence record names the provider rea-workflow, carries the Ghidra profile as upstream_analysis_profile, and has confidence: "derived". Its first limitation is "Derived by an REA composed workflow.", and the limitations of the Ghidra records follow it. A primitive operation such as list_procedures is observed.

"provider": {
  "id": "rea-workflow",
  "name": "REA composed investigation workflow",
  "version": "1"
},
"analysis_profile": {
  …
  "parameters": {
    "upstream_analysis_profile": {
      "provider": {
        "id": "ghidra",
        "name": "Ghidra",
        "version": "12.1.4"
      },
      "parameters": {
        "target_kind": "executable",
        "target_format": "mach-o",
        "architecture": "arm64",
        …
        "import_mode": "ephemeral-source-immutable",
        …
      },
      …
    },
    "workflow_revision": 3
  },
  …
},

The arm64 executable

"normalized_result": {
  "document": "target-01b5d08b08fb.bin",
  "image_base": "0x100000000",
  "segments": [
    {
      "name": "__TEXT",
      "start": "0x100000000",
      "end": "0x100000500",
      "length": 1280,
      "image_base": "0x100000000",
      "address_space": "ram"
    },
    {
      "name": "__text",
      "start": "0x100000500",
      "end": "0x100000740",
      "length": 576,
      "image_base": "0x100000000",
      "address_space": "ram"
    },
    …
    {
      "name": "EXTERNAL",
      "start": "0x10000c000",
      "end": "0x10000c200",
      "length": 512,
      "image_base": "0x100000000",
      "address_space": "ram"
    }
  ],
  "segment_count": 12,
  "procedure_count": 13,
  "string_count": 39
},
"confidence": "derived",
"authority": "shipped-artifact",
"environment": null,
"limitations": [
  "Derived by an REA composed workflow.",
  …
],

The document is not the file you named. It is target-01b5d08b08fb.bin, the private copy that rea makes under its runtime root. The name is target- plus the first twelve hex digits of the SHA-256. Section 4.1 shows that copy being made.

The twelve segments are Ghidra memory blocks. They are different from the four LC_SEGMENT_64 commands of section 3.2. Ghidra splits __TEXT into the 1280-byte header range and its five sections. It splits __DATA_CONST into __got, __const, and the 16296 bytes after them. It splits __LINKEDIT into the 1104 used bytes and the padding to the next page.

The ends are exclusive: __text runs from 0x100000500 to 0x100000740, and the next block starts at 0x100000740. The last block, EXTERNAL, is not in the file at all. Ghidra creates it for imported functions, and section 4.2 shows four of them living there.

The 13 procedures are the four functions of ledger.c, the entry function that LC_MAIN points to, four thunks, and four external functions. The thunks are in __stubs and the externals are in EXTERNAL. The 39 strings are everything Ghidra defined as string data, and section 4.5 places each one.

The x86-64 relocatable object

"normalized_result": {
  "document": "target-9a4a8082ba5e.o",
  "image_base": "0x100000",
  "segments": [
    {
      "name": ".text",
      "start": "0x100000",
      "end": "0x10009f",
      "length": 159,
      "image_base": "0x100000",
      "address_space": "ram"
    },
    {
      "name": ".rodata",
      "start": "0x1000a0",
      "end": "0x1000f0",
      "length": 80,
      "image_base": "0x100000",
      "address_space": "ram"
    },
    {
      "name": ".rodata.str1.1",
      "start": "0x1000f0",
      "end": "0x1000fa",
      "length": 10,
      "image_base": "0x100000",
      "address_space": "ram"
    },
    …
    {
      "name": "_elfSectionHeaders",
      "start": "_elfSectionHeaders:0x0",
      "end": "_elfSectionHeaders:0x2c0",
      "length": 704,
      "image_base": "0x100000",
      "address_space": "_elfSectionHeaders"
    }
  ],
  "segment_count": 10,
  "procedure_count": 4,
  "string_count": 20
},

The object has three loaded blocks and seven others. .text holds 159 bytes of code for the four functions. .rodata holds 80 bytes, with the value table of grade at 0x1000b4 and the offset table of grade_label. .rodata.str1.1 holds ten bytes: the five labels F, D, C, B, A, each with its terminator.

The other seven blocks live in their own address spaces. The record names each space in address_space and writes the addresses as .comment:0x0 or _elfSectionHeaders:0x0. That spelling is the rule from the Ghidra limitation that every record carries: "Default-space addresses use lowercase 0x-prefixed hexadecimal; other address spaces use <percent-encoded-space>:0x<hex>."

Four procedures, not 13. An object file has no main, no stubs, and no imports, so there is nothing external to list. The 704 bytes of _elfSectionHeaders are eleven section headers of 64 bytes, the table that lesson 32 parses first.

What the overview does not say

The record has no function sizes and no entry point. It reports the image base: 0x100000000 for the executable and 0x100000 for the object. For the object, that base is the placement that Ghidra chose.

For sizes, use the body of each function in section 4.2. For the entry point, use LC_MAIN in section 3.2. The two profile digests differ, 966e6016 against 9c7f6b24, because target_format and architecture are inside the profile parameters. Section 5.3 shows that a cached answer replays only when the whole digest matches.

Sources:capture/out/00-commands.txt, capture/out/05-analyze-arm64-O1.json, capture/out/05-analyze-x86_64-O1.json; rea 6.5.0 at 3b79af2: src/cliCommandNames.ts, src/application/InvestigationProviders.ts, src/application/EnhancedTools.ts, src/application/WorkflowEvidence.ts, src/contracts/toolOutputSchemaGroups.ts, src/contracts/toolOutputSchemaPrimitives.ts, src/ghidra/GhidraTargetSnapshot.ts

Your agent opened ledger-arm64-O1 over MCP in a few milliseconds and then waited several seconds for list_procedures. Nothing was wrong. The open call did not start Ghidra. The first question did, and every question after it came back in milliseconds.

When you finish this section, you can read the server log of a session and name the process that the first query started. You can also predict which calls will be slow.

open_binary

"method": "tools/call",
"params": {
  "name": "open_binary",
  "arguments": {
    "path": "$CAPTURE/fixtures/ledger-arm64-O1",
    "provider_id": "ghidra"
  }
}
…
"structuredContent": {
  "result": {
    "path": "$CAPTURE/fixtures/ledger-arm64-O1",
    "format": "mach-o",
    "kind": "executable",
    "sha256": "01b5d08b…",
    "architecture": "arm64"
  }
}

The handler calls session.open with the path and the provider id, then returns five fields: path, format, kind, sha256, and architecture. To fill them rea reads the magic bytes: 7f 45 4c 46 for ELF, MZ for DOS and PE, and four Mach-O values. It hashes the whole file in 64 KiB chunks. A file with no header needs an explicit format. With format: "raw-binary" you also give architecture and entry_point, and the result adds entry_point. rea refuses a WebAssembly module here and sends it to inspect_wasm_artifact. For every other target, rea selects the provider you asked for, and binary_session records that choice.

"open": true,
…
"analysis_provider_binding": {
  "provider": {
    "id": "ghidra",
    "name": "Ghidra",
    "version": "12.1.4"
  },
  "selection_source": "request",
  "analysis_profile": {
    …
    "digest": "966e6016…"
  }
},
…
"server_identity": {
  "package": {
    "name": "rea-agents",
    "version": "6.5.0",
    …
  },
  …
  "sdk": {
    "server": "2.3.1",
    …
  },
  "negotiated_protocol_version": "2025-06-18",
  …

selection_source: "request" says the agent chose Ghidra. The profile digest is the one every Ghidra record of this target carries. The docs state the limit of the open call in one sentence:

The first Ghidra-backed call

03  tools/call open_binary              ok     -> 10-mcp-03-open-binary-O1.json  (…)
04  tools/call binary_session           ok     -> 10-mcp-04-binary-session.json  (…)
05  tools/call list_procedures          ok     -> 10-mcp-05-list-procedures.json  (…)
06  tools/call procedure_assembly       ok     -> 10-mcp-06-procedure-assembly-grade.json  (…)
07  tools/call xrefs                    ok     -> 10-mcp-07-xrefs-grade.json  (…)
08  tools/call list_strings             ok     -> 10-mcp-08-list-strings.json  (…)

{"level":30,"time":…,"application":"rea","mode":"mcp","layer":"server","tool":"open_binary","durationMs":…,"status":"ok","msg":"MCP tool execution completed"}
{"level":30,"time":…,"application":"rea","mode":"mcp","layer":"server","tool":"list_procedures","durationMs":…,"status":"ok","msg":"MCP tool execution completed"}
{"level":30,"time":…,"application":"rea","mode":"mcp","layer":"server","tool":"procedure_assembly","durationMs":…,"status":"ok","msg":"MCP tool execution completed"}
{"level":30,"time":…,"application":"rea","mode":"mcp","layer":"server","tool":"xrefs","durationMs":…,"status":"ok","msg":"MCP tool execution completed"}
{"level":30,"time":…,"application":"rea","mode":"mcp","layer":"server","tool":"list_strings","durationMs":…,"status":"ok","msg":"MCP tool execution completed"}

The capture kit records the pattern in its README. The first Ghidra-backed call after open_binary takes 5 to 7 s. Every later call on the same target takes under 100 ms. The difference is the Ghidra start. GhidraClient.callTool awaits start() before it queues any request, so the first call pays for the whole sequence in #startWithin:

1. Create a private runtime root named rea-ghidra- and a random suffix under the session root.
2. Allocate the endpoint, a Unix socket on macOS and Linux.
3. Copy the target into the root as target-01b5d08b08fb.bin, hashing while copying, and refuse a digest mismatch.
4. Mint a 32-byte random token and a run id.
5. Write session.json with transport, endpoint_path, token, run_id, target_sha256, provider_version, and profile_digest.
6. Start Java and wait for the bridge to accept a connection.

Headless import: a Ghidra run with no window that imports one file into a project and runs the default analyzers. On macOS and Linux, rea does not run the analyzeHeadless shell script. It asks Ghidra's LaunchSupport.jar for the environment and the JVM arguments, then runs java itself. The heap is -Xmx2G unless GHIDRA_HEADLESS_MAXMEM or GHIDRA_MAXMEM is set. The command adds -Djava.awt.headless=true and names the class ghidra.Ghidra with ghidra.app.util.headless.AnalyzeHeadless. The docs give the reason: "Apple platform shell wrappers hide their environments from ownership inspection, so retaining those wrappers would prevent verified process-group cancellation during startup." install §Ghidra

The headless arguments come in one fixed order:

• the project root and the project name rea-project
• -import with the copied target
• -readOnly and -deleteProject
• -log and -scriptlog into the runtime root, and -scriptPath at the bridge directory
• -postScript ReaGhidraNoReturnFix.java
• -postScript ReaGhidraBridge.java with the path of session.json, last

Some targets and settings need more arguments. A raw binary, a DOS file, or a language override adds a loader and a processor. Seeds and disabled analyzers add pre-scripts. The fixtures of this manual need none of them.

The bridge on the Java side

ReaGhidraBridge.java is a Ghidra script that runs after the import and the analyzers. Its run() reads session.json and deletes it, then requires an imported program. It checks that the Ghidra version equals provider_version and compares the program's own SHA-256 with target_sha256 in constant time. It then ends the script transaction, initializes the decompiler, and serves. On a Unix socket it binds the path, sets the mode to rw-------, and accepts one client.

Each request is one JSON line, { id, token, method, params }. Each reply is { id, ok: true, result } or { id, ok: false, error: { code, message } }, and rea parses it with a strict schema. list_procedures was request number 2 on that socket, after the ping of the handshake, and it took the Java side a few milliseconds. The seconds before it were the import and the analyzers.

Deadlines and the close

rea allows 330,000 ms for the start, set by REA_GHIDRA_STARTUP_TIMEOUT_MS. On the capture Mac the start took 5 to 7 s, and the client limit is the one to watch: "The pinned client SDK 2.3.1 defaults to 60,000 ms and can cancel earlier than REA's startup deadline." mcp §Ghidra first-query deadlines and recovery

The docs record about 64 s on a Linux fixture and about 163 s on Windows. Set the client deadline from your own first run on your own machine.

close_binary takes a fraction of a second in the log. The client sends shutdown to the bridge with a 10 s limit, the bridge disposes the decompiler, and -deleteProject removes the project. The next open_binary on ledger-arm64-O2 took about a millisecond, and its first analyze_function again took seconds, because "Each new provider session still imports the target into a fresh temporary project." mcp §Ghidra first-query deadlines and recovery

Sources:capture/out/10-mcp-03-open-binary-O1.json, capture/out/10-mcp-04-binary-session.json, capture/out/10-mcp-session.txt, capture/out/10-mcp-server.log, capture/out/05-analyze-arm64-O1.json, capture/README.md; rea 6.5.0 at 3b79af2: src/server/registerSessionTools.ts, src/contracts/sessionLifecycleInputs.ts, src/domain/binaryTarget.ts, src/application/BinaryTargetResolver.ts, src/ghidra/GhidraClient.ts, src/ghidra/GhidraTransport.ts, src/ghidra/GhidraTargetSnapshot.ts, src/ghidra/GhidraLauncher.ts, src/ghidra/GhidraJavaLaunch.ts, src/ghidra/GhidraClientWire.ts, src/ghidra/protocol.ts, src/config/providerStartupTimeout.ts, bridge/ghidra/ReaGhidraBridge.java; rea docs/mcp-contracts.md, rea docs/installation.md

You wrote four functions and a main. Ghidra lists 13 procedures, four of them at addresses like EXTERNAL:0x1, and the one you called main is named entry. Each of those facts has a reason in the file, and the list is the place to learn them.

When you finish this section, you can account for all 13 procedures and tell a thunk from its external target. You can also read a function body as inclusive address ranges.

The inventory

"normalized_result": [
  {
    "address": "EXTERNAL:0x1",
    "value": "/usr/lib/libSystem.B.dylib::___stack_chk_fail",
    "procedure": {
      "external": true,
      "thunk": false,
      "thunk_target": null
    }
  },
  …
  {
    "address": "0x100000518",
    "value": "_grade",
    "procedure": {
      "external": false,
      "thunk": false,
      "thunk_target": null
    }
  },
  …
  {
    "address": "0x1000005d0",
    "value": "entry",
    "procedure": {
      "external": false,
      "thunk": false,
      "thunk_target": null
    }
  },
  {
    "address": "0x100000740",
    "value": "___stack_chk_fail",
    "procedure": {
      "external": false,
      "thunk": true,
      "thunk_target": "EXTERNAL:0x1"
    }
  },
  …
],

The bridge builds the list once per program from two Ghidra iterators, the internal functions and the external functions. It drops duplicates by entry address. For each function it records external, thunk, and the resolved thunk_target when there is one. The value is the qualified symbol name, which is why the external entries carry their library path. The record's limitation states the rule: "External functions and local thunks are distinct; procedure metadata identifies both and preserves a thunk target when Ghidra resolves one.".

Thunk: a small function whose only job is to transfer control to another function. The four thunks sit in __stubs, the 48-byte section at 0x100000740 from section 3.2. Each one is a 12-byte stub that reaches the real libSystem function. Ghidra represents that function as an entry in its EXTERNAL block, the last segment in section 3.4. The two imports that are not functions, ___stack_chk_guard and ___stderrp, do not appear here, because they are data.

entry is _main. inspect-macho exports _main at 0x1000005d0, and LC_MAIN points there with entryoff 1488. Ghidra names the entry point entry and keeps _main as a second symbol at the same address. The docs say that a secondary symbol at a function entry, such as an imported _main label, is accepted as a selector native §Exact CLI selectors, so rea function fixtures/ledger-arm64-O1 _main works.

Function bodies

The inventory has no sizes. The size of a function is in the procedure.body of its analyze_function dossier, and section 4.6 reads the rest of that record.

"procedure": {
  "address": "0x100000518",
  "name": "_grade",
  "classification": {
    "external": false,
    "thunk": false,
    "thunk_target": null,
    "provenance": "ghidra-function-manager"
  },
  "body": {
    "available": true,
    "provenance": "ghidra-function-body-address-set",
    "ranges": [
      {
        "start": "0x100000518",
        "end": "0x100000553"
      }
    ],
    "total_bytes": 60,
    "span_bytes": 60,
    "non_contiguous": false,
    "contains_entry": true
  },
  "signature": "undefined _grade()",
  "locals": []
},

Function body: the set of addresses Ghidra assigns to one function, reported as ranges with inclusive ends. _grade owns 0x100000518 to 0x100000553, 60 bytes, and _total starts at 0x100000554. The profile names this contract function_body_evidence: "complete-inclusive-ranges-v1". Three other fields in the record use exclusive ends: the segments of binary_overview, the basic_blocks of a dossier, and the memory blocks of list_segments. Read the field name before you add one.

The five internal bodies add up: 24 + 60 + 52 + 72 + 368 is 576, the size of __text. No byte of the code section belongs to two functions, and no byte belongs to none. span_bytes equals total_bytes and non_contiguous is false for all five. When they differ, the function has a gap, and the bytes in the gap are not owned by that function. The research notes a 16-bit case where a body of 503 bytes spans 517.

Selecting a procedure

Every function operation takes a procedure string. The rule for reading it:

A string with a 0x prefix or an address-space prefix is an address. Any other string is tried as a symbol name first. A name that matches more than one function fails with ambiguous and the list of entry addresses. A name that matches nothing fails with not_found, which section 4.6 shows as the MCP error invalid_request.

Sources:capture/out/10-mcp-05-list-procedures.json, capture/out/06-function-grade.json, capture/out/10-mcp-09-analyze-function-percent-change-O1.json, capture/out/10-mcp-11-analyze-function-total-O1.json, capture/out/10-mcp-12-analyze-function-grade-label-O1.json, capture/out/04-inspect-macho.json; rea 6.5.0 at 3b79af2: bridge/ghidra/ReaGhidraBridge.java, src/ghidra/GhidraProviderCapabilities.ts; rea docs/native-investigation.md

You want to see the division by ten in grade as the processor sees it. The C source says score / 10. The arm64 code has no divide instruction at all, and reading why is the first thing assembly teaches.

When you finish this section, you can read the 15 instructions of _grade, split them into three blocks, and explain the multiply by 0x66666667.

The call and the text

"name": "procedure_assembly",
"arguments": {
  "procedure": "_grade"
}
…
"normalized_result": "0x100000518: mov w8, #0x6667\n0x10000051c: movk w8, #0x6666, LSL #16\n…

The bridge resolves the procedure, scans its instructions with no limit, renders each one as text, and attaches any no-return call warnings. The record carries the limitation "Assembly is Ghidra Listing text and does not claim textual equivalence with Hopper output.". The text is Ghidra's rendering, so register names, immediates, and spacing follow Ghidra, not clang or llvm-objdump.

The dossier of section 4.6 carries the same lines as an array, which is easier to read.

"assembly": [
  "0x100000518: mov w8, #0x6667",
  "0x10000051c: movk w8, #0x6666, LSL #16",
  "0x100000520: smull x8, w0, w8",
  "0x100000524: lsr x9, x8, #0x3f",
  "0x100000528: asr x8, x8, #0x22",
  "0x10000052c: add w8, w8, w9",
  "0x100000530: sub w8, w8, #0x6",
  "0x100000534: cmp w8, #0x4",
  "0x100000538: b.hi 0x10000054c",
  "0x10000053c: adrp x9, 0x100000000",
  "0x100000540: add x9, x9, #0x7d0",
  "0x100000544: ldr w0, [x9, w8, UXTW #0x2]",
  "0x100000548: ret",
  "0x10000054c: mov w0, #0x0",
  "0x100000550: ret"
],

Reading the fifteen instructions

The argument score arrives in w0, the low 32 bits of x0, and the result leaves in w0. Read the text in four groups.

The first two lines build a constant. mov w8, #0x6667 sets the low half, and movk w8, #0x6666, LSL #16 inserts the high half, so w8 is 0x66666667.

The next four lines divide by ten without a divide. smull x8, w0, w8 multiplies the two 32-bit values into a 64-bit product. asr x8, x8, #0x22 shifts the product right by 34, and lsr x9, x8, #0x3f takes its sign bit. add w8, w8, w9 adds the sign bit, which corrects the rounding for a negative score. The result is score / 10 with C truncation. Lesson 34 proves that 0x66666667 and a shift of 34 give that quotient for every 32-bit int.

The next three lines are the switch. sub w8, w8, #0x6 turns the cases 6 to 10 into the indexes 0 to 4. cmp w8, #0x4 and b.hi 0x10000054c send any index above 4 to the default. The compare is unsigned, so a negative score, which gives a negative index, also goes to the default. That is one instruction doing the work of the default label and the cases below 6.

The last six lines are the two returns. adrp x9, 0x100000000 and add x9, x9, #0x7d0 form the address 0x1000007d0, the start of __TEXT,__const from section 3.2. ldr w0, [x9, w8, UXTW #0x2] loads the 32-bit word at that address plus four times the index. The 20 bytes at file offset 2000 are 1, 2, 3, 4, 4 as little-endian words, so the load returns the grade. The default path is mov w0, #0x0 and ret.

Basic block: a run of instructions with one entry at the top and one exit at the bottom. Control enters only at the first instruction and leaves only after the last. The dossier's basic_blocks lists three for _grade: 0x100000518 to 0x10000053c with successors 0x10000053c and 0x10000054c, and the two leaf blocks with no successors. Lesson 33 builds the decoder and the block splitter that produce the same partition from bytes.

The same function on x86-64

"assembly": [
  "0x100010: MOVSXD RAX, EDI",
  "0x100013: IMUL RAX, RAX, 0x66666667",
  "0x10001a: MOV RCX, RAX",
  "0x10001d: SAR RCX, 0x22",
  "0x100021: SHR RAX, 0x3f",
  "0x100025: ADD ECX, EAX",
  "0x100027: ADD ECX, -0x6",
  "0x10002a: XOR EAX, EAX",
  "0x10002c: CMP ECX, 0x4",
  "0x10002f: JA 0x0010003d",
  "0x100031: MOV EAX, ECX",
  "0x100033: LEA RCX, [0x1000b4]",
  "0x10003a: MOV EAX, dword ptr [RCX + RAX*0x4]",
  "0x10003d: RET"
],

Fourteen instructions, the same shape. The multiply is one instruction, IMUL RAX, RAX, 0x66666667, and the two shifts are 34 and 63 again. XOR EAX, EAX sets the default return value to zero before the compare, so the default path needs no extra block and the function has one RET. The table is at 0x1000b4, which is .rodata plus 0x14. The listing shows that address as a plain number because Ghidra applied the relocation when it loaded the object. Section 4.6 returns to the XOR line, because the decompiler wrote it in a way that hides the zero.

Where the no-return warnings go

raw_result.limitations is empty for _grade. When a function calls something Ghidra marked as never returning, the scan can stop there, and this list names the call site. On macOS and Linux, rea runs a repair script after the import. It clears wrong no-return flags on six common library names, so the bodies you read here are the repaired ones. The docs state the effect of a flag that stays: "An inferred no-return call can terminate that body before subsequent bytes." ghidra §Admitted function-analysis semantics

Sources:capture/out/10-mcp-06-procedure-assembly-grade.json, capture/out/06-function-grade.json, capture/out/06-function-grade-x86_64-O1.json, capture/out/04-inspect-macho.json, capture/fixtures/ledger-arm64-O1, capture/fixtures/ledger.c; rea 6.5.0 at 3b79af2: bridge/ghidra/ReaGhidraBridge.java, src/ghidra/GhidraProviderCapabilities.ts; rea docs/ghidra-provider.md

main calls grade_label, and grade_label calls grade. You ask xrefs who refers to _grade at 0x100000518 and get one address, 0x10000811a, which is not in any function. The answer is right, and it tells you two things about the build.

When you finish this section, you can read an xrefs result and find the kind of each reference in the dossier. You can also tell a jump table from a value table in two builds of grade.

The call

"name": "xrefs",
"arguments": {
  "address": "0x100000518"
}
…
"normalized_result": [
  "0x10000811a"
],
…
"limitations": [
  …
  "The direct address list projects exact Ghidra references to one address but does not expose their kinds; procedure_references and analyze_function preserve available kind metadata.",
  "Synthetic Ghidra entry-point references without actionable memory sources are omitted.",
  …
],

The bridge asks Ghidra's ReferenceManager for every reference to the address. It skips the synthetic entry-point references, collects the distinct source addresses, and sorts them. The result is addresses only. The incoming_references facet of the dossier keeps the kind of each reference, call, jump, or data.

What is at 0x10000811a

The address is in __LINKEDIT, which starts at 0x100008000 and maps file offset 32768. The difference 0x11a is 282, so the byte is at file offset 33050. Section 3.2 lists LC_FUNCTION_STARTS at offset 33048 with 8 bytes. The reference points into the function starts table.

Function starts: a table of unsigned LEB128 deltas, one per function, that dyld and debuggers use to find function entries in a stripped image. The eight bytes in the fixture are 80 0a 18 3c 34 48 00 00. The first delta is 0x500, which gives 0x100000500, _percent_change. The second, at offset 33050, is 0x18, which gives 0x100000518, _grade. Then 0x3c gives _total, 0x34 gives _grade_label, and 0x48 gives entry. Ghidra's Mach-O loader marks each entry as a data reference to the function it names, and the dossier shows exactly that.

"incoming_references": [
  {
    "source_address": "0x10000811a",
    "target_address": "0x100000518",
    "source_procedure": null,
    …
    "kind": {
      "available": true,
      "provenance": "ghidra-reference-manager",
      "type": "DATA",
      "flow": false,
      "call": false,
      "jump": false,
      "data": true,
      …
    }
  }
],

source_procedure is null because no function owns the table. The kind is DATA, and call is false. So nothing in the code calls _grade. Compare _grade_label, whose dossier lists two incoming references. One is an UNCONDITIONAL_CALL from 0x1000006ec inside entry. The other is a DATA reference from 0x10000811c, the fourth entry of the same table.

"source_address": "0x1000006ec",
"target_address": "0x100000588",
…
"type": "UNCONDITIONAL_CALL",
…
"source_address": "0x10000811c",
"target_address": "0x100000588",
"source_procedure": null,
…
"type": "DATA",

The call that the source makes, grade_label to grade, is gone. At -O1 clang inlined grade into grade_label. The assembly of _grade_label repeats the whole multiply and compare sequence of section 4.3 at 0x100000588 to 0x1000005a4. The dossier of _grade says the same from the other side: callers is an empty list, and relationship_coverage.status is complete. Ghidra returned every resolved call reference, and none of them targets _grade. _grade still exists as a function because it is exported, and the only thing that refers to it is a table the linker wrote.

The jump table that is not there

Every dossier in the captures has "jump_tables": [] in its native_api facet, and the profile names the contract jump_table_evidence: "typed-case-default-blocks-v1". Ghidra would fill the field if it found one. It found none, because at -O1 neither compiler emitted a jump table for the switch in grade. Both turned the five cases into a table of the five return values and one bounds check.

Jump table: a table of code addresses that an indirect jump indexes, so one instruction reaches one of several blocks. Value table: a table of data that a load indexes, so one instruction returns one of several values. The first changes the control-flow graph. The second changes one load. At -O0 the x86-64 object has the first, and in the object file its five entries are zero bytes with five relocations in .rela.rodata. At -O1 both builds have the second.

The outgoing_references of _grade name the two edges the dossier does see. One is a CONDITIONAL_JUMP from 0x100000538 to 0x10000054c. The other is a DATA read from 0x100000544 to 0x1000007d0. The referenced_names facet labels the targets LAB_10000054c and DAT_1000007d0. The decompiler in section 4.6 keeps the second as a byte address and never lists the five values.

Lesson 33 recovers the -O0 table from the relocations with the rule S + A - P. It shows the control-flow graph with and without the table: 8 blocks and 11 edges against 3 blocks and one unresolved jump.

When Ghidra does not resolve a jump table, the case blocks are missing from callers, callees, and basic_blocks. The dossier limitation says that unresolved computed flows are not represented as edges. The unresolved_calls facet lists each call site whose destination has no known procedure. An unresolved indirect jump through a table is not a call, so it does not appear in that facet. An empty jump_tables list does not prove the function has no switch. Read the transfer instruction and the table bytes, as you did here.

Sources:capture/out/10-mcp-07-xrefs-grade.json, capture/out/06-function-grade.json, capture/out/10-mcp-12-analyze-function-grade-label-O1.json, capture/out/10-mcp-09-analyze-function-percent-change-O1.json, capture/out/10-mcp-11-analyze-function-total-O1.json, capture/out/06-function-grade-x86_64-O1.json, capture/out/04-inspect-macho.json, capture/fixtures/ledger-arm64-O1; phases/13-tools-and-protocols/33-disassembly-and-control-flow/code/fixtures/ledger-x86_64-O0.objdump.txt; rea 6.5.0 at 3b79af2: bridge/ghidra/ReaGhidraBridge.java, src/ghidra/GhidraProviderCapabilities.ts

You expect five labels and three format strings. list_strings returns 39 items, among them /usr/lib/dyld, _label, _, and an empty string. Each one is a real run of bytes in the file. The list is complete for what Ghidra defined, and it is only that.

When you finish this section, you can place each of the 39 strings in its load command. You can also say what an empty result does and does not prove.

The call

"name": "list_strings",
"arguments": {}
…
{
  "address": "0x100000770",
  "value": "F",
  "string": {
    "encoding": "US-ASCII",
    "termination": "present_or_not_required",
    "byte_length": 2
  }
},
…
{
  "address": "0x1000007cf",
  "value": "",
  "string": {
    "encoding": "US-ASCII",
    "termination": "present_or_not_required",
    "byte_length": 1
  }
},
…
{
  "address": "0x1000080c7",
  "value": "_label",
  "string": {
    "encoding": "US-ASCII",
    "termination": "present_or_not_required",
    "byte_length": 7
  }
},
…
"limitations": [
  …
  "Only Ghidra-defined string Data is observed; packed or undefined string bytes may be absent. Completeness applies to that inventory, and an empty search does not establish that text is absent from the artifact. If an address is known, use read_bytes and xrefs to inspect bytes and references.",
  "Charset is reported, while a non-missing terminator cannot distinguish a present terminator from a fixed or Pascal layout.",
  …
],

The bridge walks every defined data item in the program and keeps the ones with a string value. For each it records the charset, whether a required terminator is missing, and the byte length. Each item is a Data object that Ghidra's loader or analyzers created. A run of printable bytes that no analyzer turned into Data is not in the list. The first limitation is fixed in rea, and the docs say the same:

termination has two values. missing means a string type that needs a null byte has none. present_or_not_required covers everything else, because Ghidra cannot tell a present terminator from a layout that needs none. byte_length counts the terminator: F is two bytes.

Thirty-nine strings in six places

Sort the 39 addresses and they fall into six runs. Each run is one load command from section 3.2.

The ten in __cstring are the program's own text. The section is 95 bytes, and Ghidra's block for it in section 3.4 is 96. The block runs to the start of __const at 0x1000007d0. The extra byte at 0x1000007cf is the alignment pad, and Ghidra defined it as an empty string of length 1. That item is real and harmless, and you will see pads like it in every linked image.

The export trie is a prefix tree of the exported names. Its edges carry shared prefixes once. Ghidra's string data therefore holds seven fragments, _, _label, _mh_execute_header, grade, main, percent_change, and total, and not the six export names. The string table of LC_SYMTAB holds the thirteen full names, which match the nsyms of 13. The last string is the code signature's identifier, the output file name that the linker embedded. That is why the capture kit warns that a different output name gives different bytes.

Strings a function refers to

The dossier of _grade_label has a referenced_strings facet with one item, F at 0x100000770, from the load at 0x1000005c8. The function does not load F. It loads a pointer from _labels at 0x100004030, the 40-byte __const in __DATA_CONST that holds five pointers to the five labels. Ghidra followed the first pointer and recorded the string behind it, and its referenced_names facet lists both _labels and s_F_100000770 from the same instruction. Read a referenced string as a string the function can reach, not as the only one.

In the x86-64 object the same five labels sit in .rodata.str1.1, the ten-byte block in section 3.4, and string_count is 20. Lesson 32 reads the ELF string tables that hold the other ten.

What the inventory cannot prove

The limit is in the first word of the rule: defined. Three kinds of text are not Data. A compiler can pack a string into a struct. The analyzer can skip a string without a terminator. A program can build a string at run time. The list has none of them.

The capture target has none of those, so the 39 items are the whole file. For a target you did not build, treat an absent string as unknown. When you know an address, read_bytes returns the bytes and xrefs returns who uses them, as the limitation says. Section 5.2 shows how rea records that kind of unknown.

Sources:capture/out/10-mcp-08-list-strings.json, capture/out/04-inspect-macho.json, capture/out/05-analyze-arm64-O1.json, capture/out/10-mcp-12-analyze-function-grade-label-O1.json, capture/fixtures/ledger-arm64-O1, capture/README.md; rea 6.5.0 at 3b79af2: bridge/ghidra/ReaGhidraBridge.java, src/ghidra/GhidraProviderCapabilities.ts; rea docs/ghidra-provider.md

You asked for percent_change and got a function that returns ulong and tests iVar2 != 0 twice. The source returns int and tests once. The instructions in the same record are right, and the text around them is a reading of those instructions. Learning to tell the two apart is what this section is for.

When you finish this section, you can read the sixteen facets of a dossier. You can mark which lines of pseudocode follow from an instruction and which are a guess. You can also read the error for a name that does not exist.

The dossier

rea function is the CLI name of analyze_function. The CLI run on _grade and the MCP call in the same session produced the same evidence_id, ev_15244427 and 56 more digits. The id is a hash of the record's semantic content, and the file path and the display name are left out of it. Section 5.1 reads every field of the record. This section reads its normalized_result, which has sixteen facets.

"pseudocode": "\nundefined4 _grade(int param_1)\n\n{\n  uint uVar1;\n  \n  uVar1 = param_1 / 10 - 6;\n  if (uVar1 < 5) {\n    return *(undefined4 *)(&DAT_1000007d0 + (ulong)uVar1 * 4);\n  }\n  return 0;\n}\n\n",
…
"basic_blocks": [
  {
    "start": "0x100000518",
    "end": "0x10000053c",
    "successors": [
      "0x10000053c",
      "0x10000054c"
    ]
  },
  …
],
"native_api": {
  "available": true,
  "provenance": "ghidra-high-function",
  "signature_source": "default",
  "calling_convention": "__cdecl",
  …
      "data_type": "undefined4",
      "size_bytes": 4,
      "storage": "w0:4",
      "confidence": "low",
  …
  "jump_tables": [],
  "pseudocode": {
    "classification": "decompiler-generated-non-source",
    "compilable": false
  },
  …
  "limitations": [
    "Types and calling conventions are Ghidra decompiler observations, not source declarations.",
    "Register variables, compiler-generated blocks, and pointer arithmetic remain decompiler artifacts.",
    "Pseudocode is neither original source nor guaranteed to compile."
  ]
},

The pseudocode is one JSON string. Decoded, it reads:

undefined4 _grade(int param_1)

{
  uint uVar1;
  
  uVar1 = param_1 / 10 - 6;
  if (uVar1 < 5) {
    return *(undefined4 *)(&DAT_1000007d0 + (ulong)uVar1 * 4);
  }
  return 0;
}

Dossier: rea's name for the composed record of one function. The bridge builds it from five Ghidra sources: the FunctionManager, the Listing, the ReferenceManager, the BasicBlockModel, and the decompiler. The record-level limitation names all five. The record carries ten limitations, the result four more, native_api three, and native_value_flow five. Read them once. They say in rea's words what this section shows with examples.

The signature facts are the first thing to read. signature_source is default, which means no analyzer or user set the prototype, and every parameter and the return value carry confidence: "low". The bridge gives medium only when the source is analysis. native_api.pseudocode.compilable is false, and the third native_api limitation is written into the Java source itself.

procedure_pseudo_code: the text alone

rea decompile is the CLI name of procedure_pseudo_code. It returns the text and nothing else.

"operation": "procedure_pseudo_code",
"parameters": {
  "procedure": "_total"
},
"raw_result": {
  "value": "\nint _total(int *param_1,uint param_2)\n\n{\n  int iVar1;\n  ulong uVar2;\n  \n  if (0 < (int)param_2) {\n…
  "limitations": []
},
…
"limitations": [
  …
  "Pseudocode is Ghidra decompiler output, not original source and not text-equivalent to Hopper output.",
  "External functions and functions without an analyzable body return null; other decompiler failures remain explicit.",
  …
],

int _total(int *param_1,uint param_2)

{
  int iVar1;
  ulong uVar2;
  
  if (0 < (int)param_2) {
    iVar1 = 0;
    uVar2 = (ulong)param_2;
    do {
      iVar1 = *param_1 + iVar1;
      uVar2 = uVar2 - 1;
      param_1 = param_1 + 1;
    } while (uVar2 != 0);
    return iVar1;
  }
  return 0;
}

The bridge opens one DecompInterface per program with C output, the syntax tree, and jump loads on, and no instruction limit. Each call is decompileFunction(function, 0, monitor), with no timeout, and an external or bodyless function returns null. The text is the getC() output of the result.

_total reads well. The do loop with uVar2 - 1 is the rotated loop that subs x9, x9, #0x1 and b.ne make in the assembly. The pointer type int *param_1 follows from the load ldr w10, [x0], #0x4. The one open question is uint param_2. The source says int count. The instructions compare w1 as signed once and then count it down in x9, so both types fit, and Ghidra picked one.

Where the text is incomplete or wrong

Decompiler artifact: a line of pseudocode that the decompiler needed to express the machine code and that no source line produced. The native_api limitations name three kinds: register variables, compiler-generated blocks, and pointer arithmetic. Three records in the captures show three kinds of gap between the text and the instructions.

"pseudocode": "\nulong _percent_change(ulong param_1,int param_2)\n\n{\n  uint uVar1;\n  int iVar2;\n  \n  iVar2 = (int)param_1;\n  if (iVar2 != 0) {\n    uVar1 = 0;\n    if (iVar2 != 0) {\n      uVar1 = ((param_2 - iVar2) * 100) / iVar2;\n    }\n    param_1 = (ulong)uVar1;\n  }\n  return param_1;\n}\n\n",
"assembly": [
  "0x100000500: cbz w0, 0x100000514",
  "0x100000504: sub w8, w1, w0",
  "0x100000508: mov w9, #0x64",
  "0x10000050c: mul w8, w8, w9",
  "0x100000510: sdiv w0, w8, w0",
  "0x100000514: ret"
],

Six instructions. cbz w0, 0x100000514 jumps to the ret when before is zero, and on that path w0 is zero and the function returns it. The other path computes (w1 - w0) * 100 and divides with sdiv w0, w8, w0. Both paths return 32 bits in w0.

The pseudocode says the function returns ulong, eight bytes, and returns param_1, the whole of x0. The ABI and the source say four bytes. Nothing in the text marks the difference. The record does: return_type.data_type is ulong, confidence is low, and signature_source is default. The second if (iVar2 != 0) repeats a test that one instruction made once. It changes no value, and it is not in the instructions.

_grade shows the second kind of gap. The decompiled text keeps the table as *(undefined4 *)(&DAT_1000007d0 + (ulong)uVar1 * 4). The address is right, the element size is right, and the five values are not there. Section 3.3 turns 0x1000007d0 into file offset 2000, and the 20 bytes there are 1, 2, 3, 4, 4. The return type is undefined4, four bytes of unknown meaning. The text is incomplete, and you complete it from the bytes.

The x86-64 build of grade shows the third kind. Its pseudocode has the line uVar1 = -(param_1 >> 0x1f) ^ (uint)((ulong)((long)param_1 * 0x66666667) >> 0x3f); for the default return value.

"value": "\nuint grade(int param_1)\n\n{\n  uint uVar1;\n  uint uVar2;\n  \n  uVar2 = param_1 / 10 - 6;\n  uVar1 = -(param_1 >> 0x1f) ^ (uint)((ulong)((long)param_1 * 0x66666667) >> 0x3f);\n…

The instruction behind that line is XOR EAX, EAX at 0x10002a in section 4.3. The register is zero. Ghidra wrote it as the sign of param_1 exclusive-or the sign bit of the product. Those are two spellings of the same bit, and the decompiler did not cancel them. The value is 0 for every int, so the text is not false. A reader who trusts the text believes the default depends on the score, which is false.

Lesson 34 compiles this text and tests it against the source over a grid. It then puts its own lifter output beside Ghidra's and accounts for every difference in percent_change, grade, and total.

The rule from the three cases is short. The assembly facet is observed. The pseudocode is observed text about a derived reading. Check a type against the storage, a constant against the bytes, and a branch against the blocks before you repeat what the text says.

A name that does not exist

"name": "analyze_function",
"arguments": {
  "procedure": "_nothing"
}
…
"isError": true
…
"decoded_text": {
  "error": {
    "code": "invalid_request",
    "category": "invalid_input",
    "message": "Analysis input is invalid. Check the arguments and try again.",
    "retryable": true,
    "remediation": {
      "action": "Correct the listed arguments and retry."
    },
    "details": {
      "operation": "analyze_function",
      "issues": [
        {
          "path": [],
          "reason": "invalid_value",
          "message": "Unknown Ghidra procedure name or address: _nothing"
        }
      ],
      …
    }
  }
}

The bridge tried _nothing as a symbol name, then as an address, and failed with not_found. The diagnostics object in the error shows the remote code not_found that the bridge sent. The client maps the remote codes invalid_request, not_found, and ambiguous to AnalysisInputError. That error projects to the code invalid_request. An error reaches the MCP client as text with isError: true and no result. The server log shows where the time went.

{"level":40,"time":…,"application":"rea","mode":"mcp","layer":"ghidra-bridge","method":"analyze_function","status":"error","msg":"Ghidra bridge request completed"}
{"level":40,"time":…,"application":"rea","mode":"mcp","layer":"server","tool":"analyze_function","durationMs":…,"status":"error","msg":"MCP tool execution completed"}

The lookup was a round trip on the socket to Ghidra, a couple of milliseconds in all. retryable is true: correct the name from section 4.2 and call again. The session stays open and the Ghidra project stays imported.

What to do with a dossier

Read the sixteen facets in this order. Start with procedure for the body and assembly for what the processor does. Then read basic_blocks for the shape and the references for the edges, and pseudocode last. Section 5.5 compares two dossiers of the same function from two builds. Section 7.2 shows the test that decides whether a rebuild from this text is equal to the original.

Sources:capture/out/06-function-grade.json, capture/out/10-mcp-10-analyze-function-grade-O1.json, capture/out/07-decompile-total.json, capture/out/07-decompile-grade-x86_64-O1.json, capture/out/10-mcp-09-analyze-function-percent-change-O1.json, capture/out/10-mcp-11-analyze-function-total-O1.json, capture/out/10-mcp-12-analyze-function-grade-label-O1.json, capture/out/10-mcp-13-analyze-function-missing.json, capture/out/10-mcp-server.log, capture/fixtures/ledger.c, capture/fixtures/ledger-arm64-O1; rea 6.5.0 at 3b79af2: src/cliCommandNames.ts, src/domain/evidence.ts, src/ghidra/GhidraProviderCapabilities.ts, src/ghidra/GhidraProviderClient.ts, src/domain/analysisErrorProjection.ts, src/server/toolResult.ts, bridge/ghidra/ReaGhidraBridge.java

An agent tells you that _percent_change returns 0 when before is 0. You want to know what rea observed, which engine said it, and whether the same claim from another machine would carry the same id. The capture holds the answer in capture/out/10-mcp-09-analyze-function-percent-change-O1.json: one Evidence record. When you finish this section, you can read all sixteen fields of an Evidence record and say which three carry the trust decision. You can also recompute an ev_ id from a captured record.

One record for every successful observation

Evidence record: the one record type that rea returns for a successful observation. The schema is one strict object with sixteen fields. A record with an extra field is rejected. A record that omits relationship_coverage gets null, so a record written before that field existed still reads. A record that omits any other field is rejected. The MCP server returns the record as structuredContent and as a text copy: "Evidence-producing tools return the complete canonical Evidence record in both text and structured content." mcp Tool results

"evidence_id": "ev_172d39ff37ab60d9e0e1dd33ba7486cb2ee789a46b00d600cd083a825edd1350",
"subject": {
  "name": "ledger-arm64-O1",
  "digest": {
    "sha256": "01b5d08b08fb94678be5919d0e753d44b505a53107c95b94634f0e5d41c9e375"
  },
  "format": "mach-o",
  "architecture": "arm64",
  "local_path": "$CAPTURE/fixtures/ledger-arm64-O1"
},
"provider": {
  "id": "ghidra",
  "name": "Ghidra",
  "version": "12.1.4"
},
"analysis_profile": {
  …
  "digest": "966e6016724421ad282356f583a9d5bf24577db4ac77a75c7099d236b88bcc28"
},
"predicate_type": "rea.analysis",
"operation": "analyze_function",
"parameters": {
  "procedure": "_percent_change"
},
"raw_result": {
  …
},
"normalized_result": {
  …
},
"confidence": "observed",
"authority": "shipped-artifact",
"environment": null,
"limitations": [
  "The session serves operations only after Ghidra reports default auto-analysis complete; incomplete analysis does not expose partial results.",
  …
],
"relationship_coverage": {
  "status": "complete",
  …
},
"locations": [],
"evidence_links": []

The subject format is one of 28 container names, from mach-o and elf to javascript and directory. The architecture is one of x86, x86_64, arm, arm64, mips, 6502, riscv, and powerpc. Only the raw-binary format can have the architecture 6502. A location has one of five shapes: address, address-range, artifact-path, file-offset, or file-offset-range.

The MCP handler can run a preflight check before the engine starts. It builds the record after the engine answers. It calls createEvidence with the active target, the provider, and the operation. The same call passes the parameters, the result, the profile, the raw result, the limitations, the locations, and the links.

Some tools give a reduced parameter set to the record. The handler records any source records first, then this record, then returns it. Inside a Ghidra session, the binary session makes the same call.

Three defaults fill in what a producer leaves out. When the producer names no confidence or authority, the record gets observed and shipped-artifact. The subject name is the last segment of the path. When there is no target at all, the record gets the limitation "Artifact identity is unavailable for this observation.".

Confidence and authority

Confidence: one of three words, observed, derived, or inferred. It is a category, never a number. Authority: the kind of source behind the fact, one of shipped-artifact, controlled-replay, historical-reference, external-service, or analyst-inference. The two fields are set by the producer, and the captures show four producers.

Read observed with care. In the dossier it means that rea recorded what Ghidra returned, with the bytes on disk as the authority. It does not mean that the pseudocode is the program's source. The provider documentation says so: "Assembly is complete Ghidra Listing text; pseudocode is Ghidra decompiler output." ghidra Admitted function-analysis semantics

The binary_overview record is derived, because a rea workflow computed it from provider calls. Its first limitation says so: "Derived by an REA composed workflow." The other ten are the Ghidra limitations it inherits (05-analyze-arm64-O1.json). Lesson 35 builds a ledger in plain Python with the same three words and the same five authorities.

Limitations, locations, and links

limitations is an array of plain strings, and a producer appends its own to the ones it inherits. The comparison record shows both kinds. Its first entry is the automatic one for a record without a subject. The next 26 are the dossier limitations of both sides, each prefixed with Left: or Right:.

"confidence": "derived",
"authority": "analyst-inference",
"environment": null,
"limitations": [
  "Artifact identity is unavailable for this observation.",
  "Left: Cancelling an active Ghidra request terminates its ephemeral database and discards session annotations. The selected target remains open; the next provider query imports the original artifact again.",
  …
],
"locations": [],
"evidence_links": [
  "ev_172d39ff37ab60d9e0e1dd33ba7486cb2ee789a46b00d600cd083a825edd1350",
  "ev_1f3bca22a69485fa2eaf7bdd59847e92fb77517bac6c01e657e143c14870013f"
]

evidence_links names the records a derived record was computed from. The comparison links the two dossiers it compared, and a view links its parent record. locations says where in the artifact the fact was seen. The JavaScript record in 15-js-app.json carries one artifact-path location, artifact-root. The Ghidra dossier carries none, because its addresses live inside normalized_result.

analysis_profile is part of the identity even when it is empty: "analysis_profile is always present: a concrete profile object or null; either value participates in semantic identity." mcp Tool results

A profile whose provider differs from the record's provider is rejected with "Analysis profile provider does not match Evidence provider". The profile digest is a SHA-256 over the canonical JSON of its provider and parameters. The snapshot cache uses the same digest as part of its key.

The id is a hash of the semantic content

Semantic projection: the view of the record that the id hashes. It keeps subject.digest, subject.format, and subject.architecture, and it drops subject.name and subject.local_path. It also drops relationship_coverage when its value is null, so a record without coverage keeps the id it had before that field existed. Every other field enters as it is.

The id is ev_ followed by the SHA-256 of that projection in canonical JSON. Object keys are sorted as RFC 8785 requires. parseEvidence recomputes the hash on every record it reads and rejects a mismatch with "Evidence semantic identifier does not match its record".

You can do the same check with a few lines of Node. The script below sorts keys, serializes without spaces, drops the two display fields, drops a null coverage field, and hashes.

import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";

const canonical = (value) => {
  if (value === null || typeof value !== "object") return JSON.stringify(value);
  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
};

const file = JSON.parse(readFileSync(process.argv[2], "utf8"));
const record = file.response ? file.response.result.structuredContent : file;
const { evidence_id, subject, relationship_coverage, ...rest } = record;
if (relationship_coverage !== null && relationship_coverage !== undefined) rest.relationship_coverage = relationship_coverage;
const projection = {
  subject: subject === null ? null : { digest: subject.digest, format: subject.format, architecture: subject.architecture },
  ...rest,
};
const digest = createHash("sha256").update(canonical(projection)).digest("hex");
console.log(evidence_id, evidence_id === `ev_${digest}` ? "match" : "mismatch");

Run on 05-analyze-arm64-O1.json, it prints ev_90e65378a5b1d958b02840bda801e5758d39ceb43acd0f4ed2d1a3ad7297588d match, the id on line 2 of that file. Run on 10-mcp-09-analyze-function-percent-change-O1.json, it matches ev_172d39ff37ab60d9e0e1dd33ba7486cb2ee789a46b00d600cd083a825edd1350. It also matches the comparison record in 10-mcp-20 and the first record inside 11-bundle-O1.json. The masked $CAPTURE path in subject.local_path changes nothing, because that field is outside the hash.

Two files in the capture do not match, and both teach the same rule. 15-js-app.json fails because the kit cut graph and semantic_graph out of normalized_result with --filter-output. 15-js-app-view-summary.json fails because the kit masked the capture directory as $CAPTURE inside normalized_result.summary.input_path and inside locations. A path in subject is outside the hash. A path anywhere else is inside it, and a record that carries one gets a different id on every machine.

Sources:capture/out/10-mcp-09-analyze-function-percent-change-O1.json, capture/out/10-mcp-20-compare-functions-percent-change.json, capture/out/05-analyze-arm64-O1.json, capture/out/15-js-app.json, capture/out/15-js-app-view-summary.json, capture/out/11-bundle-O1.json; phases/13-tools-and-protocols/35-evidence-confidence-and-unknowns; rea 6.5.0 at 3b79af2: src/domain/evidence.ts, src/domain/relationshipCoverage.ts, src/domain/canonicalDigest.ts, src/domain/analysisProfile.ts, src/domain/binaryTargetTypes.ts, src/server/registerEvidenceTools.ts, src/application/binary/BinarySession.ts, src/application/investigation/UnknownEvidence.ts; rea docs/mcp-contracts.md, rea docs/ghidra-provider.md

The _percent_change dossier in capture/out/10-mcp-09-analyze-function-percent-change-O1.json lists "callees": []. An agent reads that line and writes that the function calls nothing. The record supports less than that. It says which calls Ghidra resolved, and rea has a record type for what is still open. When you finish this section, you can read the fields of a ResidualUnknown, open one with record_unknown, and say what an empty list proves.

What an empty list proves

The dossier has an empty callees array and, 840 lines later, a limitation about it. Callees hold resolved targets only. The record says that this set is complete: relationship_coverage.status is complete, and unresolved_calls is empty. Complete means that Ghidra returned every resolved call reference. It does not mean that Ghidra found every call the program can make at run time.

"callees": [],
…
"Resolved reference metadata identifies computed, indirect, external, call, jump, and data edges; unresolved targetless flows remain unknown, and function classifications distinguish thunks and externals.",

The provider documentation states the same limit in one sentence: "Callers/callees contain only resolved functions." ghidra Admitted function-analysis semantics

The design rule behind every rea tool is shorter still: "Missing coverage is unknown, not absence." design Define the contract

Relationship coverage: the field relationship_coverage of an Evidence record, which states how complete the caller and callee sets are. Its status is complete, partial, or unknown. A partial value lists its limitations and can name the limited direction. An unknown value gives a reason. When a provider reports no coverage for procedure_callers or procedure_callees, rea writes unknown. A record of any other operation that reports no coverage has null.

Provider caveats stay in limitations and do not make the coverage partial. The same contract sets the limit of complete: "complete means that set was returned without a known read limit; it does not claim every possible runtime edge." design Define the contract

One part of the dossier does declare its coverage in numbers. The value flow reports whether it was truncated and how many operations, inputs, and edges it omitted. inspect-evidence-bundle repeats those numbers for every dossier in a bundle.

"native_dossier": {
  "available": true,
  "procedure_address": "0x100000500",
  "procedure_name": "_percent_change",
  "value_flow": {
    "status": "observed",
    "truncated": false,
    "omitted_operations_lower_bound": 0,
    "known_omitted_inputs": 0,
    "known_omitted_edges": 0
  }
}

A zero here is a count that rea stands behind. An empty array elsewhere is a count with no such statement. The contract says what those fields are for: "native_dossier.value_flow independently reports truncation, unavailable or unknown metadata." mcp Tool results

Two other empty lists in the capture carry the same lesson. rea compare in 14-compare-bundles.json lists ten records that are in one bundle only. It classifies every one as unknown with the conclusion kind unresolved_branch, because a bundle has no marker that says it is complete (compare). The JavaScript summary view in 15-js-app-view-summary.json reports "semantic_unknowns": 118 for a six-file application. It marks the semantic coverage unknown (the application graph). Figure 5.2 puts the three lists side by side.

The ResidualUnknown record

Residual unknown: a question that the evidence does not yet settle. It is kept as a record with an unk_ id, a revision chain, a status, and the evidence that would close it. A residual unknown has these fields.

The schema refuses a record that breaks one of eleven rules. Four of them keep the identity and the revision chain sound. The unknown id must match the hash of its own fields. The revision digest must match. Only revision 1 has no predecessor. Only a resolved unknown carries a resolution.

The other seven check the evidence and the links. A contradicted unknown needs contradicting evidence. An unknown cannot relate to itself, and no relationship can appear twice. No evidence id can appear twice in one list, and no id can both support and contradict the unknown. A comparison scope must name a comparison that supports or contradicts the unknown. It is allowed only in the function-comparison domain.

The id makes the question the identity. createResidualUnknown collapses whitespace in the question, then hashes canonical JSON of domain, question, scope_digest, and the comparison scope when the unknown has one. The same question in the same domain about the same target always has the same unk_ id. A second record_unknown with that question therefore answers already-exists. The first status is contradicted when the input names contradicting evidence, and open otherwise.

A change is a new revision, never an edit. update_unknown takes expected_revision and the complete new state. The ledger answers not-found for an unknown id and revision-conflict when the expected revision is stale. The new revision has revision plus one and the old revision_digest as its previous_revision_digest.

list_unknowns filters by status, severity, and domain, and returns the current heads in id order. It returns all of them by default. Give offset and limit to get one page. The result gives total and next_offset, which is null on the last page.

Every mutation is itself an Evidence record. Its provider is rea-unknown-registry version 1 and its predicate type is rea.residual-unknown-mutation. Its confidence is derived and its authority is analyst-inference. It carries one limitation: "Registry mutation evidence records analyst intent, not proof of the answer." The unknown's mutation_evidence_ids name those records, so the two ledgers share one hash-linked history.

Unknowns that rea opens itself

Agents open unknowns with record_unknown, and rea opens some on its own. compare_functions records one whenever its status is not unchanged. The domain is function-comparison. A changed comparison gets severity medium. Its supporting evidence is the left dossier and the comparison record, and its contradicting evidence is the right dossier, so its first status is contradicted.

An unknown comparison gets severity high, and all three records support it. Each unknown names the comparison and its changed dimensions in comparison_conclusion_scope, and an unknown comparison adds the dimension overall. Both ask for shipped-artifact authority and observed confidence, and both recommend one probe: analyze_function, with the rationale "Capture complete dossiers for both functions under the same target context."

The capture ran into this rule once. The _total comparison in 10-mcp-21-compare-functions-total.json was changed, so the connection that ran it held one unknown from that moment. No file shows it, because both bundle exports ran before any comparison. Every count in the capture therefore reads "unknowns": 0 or "unknown_revisions": 0. The rea compare summary keeps separate counters for unknown history, unknowns_added, unknowns_advanced, and unknowns_diverged (14-compare-bundles.json), and all of them are zero for the same reason.

Workflow tools do the same when they cannot finish. The user-visible error catalog at the tag lists the question each one records, for example "Does the reconstruction satisfy every declared claim?" for reconstruction verification. Lesson 35 builds the same ledger in Python, with the question as the identity and the required authority as the closing condition.

Sources:capture/out/10-mcp-09-analyze-function-percent-change-O1.json, capture/out/11-inspect-evidence-bundle-O1.json, capture/out/10-mcp-14-export-evidence-bundle-O1.json, capture/out/10-mcp-21-compare-functions-total.json, capture/out/14-compare-bundles.json, capture/out/15-js-app-view-summary.json; phases/13-tools-and-protocols/35-evidence-confidence-and-unknowns; rea 6.5.0 at 3b79af2: src/domain/residualUnknown.ts, src/domain/relationshipCoverage.ts, src/domain/evidence.ts, src/application/binary/BinarySession.ts, src/application/investigation/EvidenceLedger.ts, src/application/investigation/UnknownEvidence.ts, src/server/registerSessionRecordTools.ts, src/server/registerFunctionComparisonTool.ts, src/server/recordDerivedEvidence.ts, docs/user-visible-errors.csv; rea docs/ghidra-provider.md, rea docs/tool-design.md, rea docs/mcp-contracts.md

The capture ran rea function fixtures/ledger-arm64-O1 NAME --provider ghidra four times, once per function, and each run took between 7 and 8 seconds (capture/out/00-commands.txt). Every run imported the same 33,872 bytes into a fresh Ghidra project and threw the project away. You want the second question about the same file to be free. When you finish this section, you can say which calls a snapshot can answer and build the query id by hand. You can also predict when rea refuses to replay or to save.

Three things called a snapshot

The word covers three things in rea, and only one of them is a cache you can keep.

Target snapshot: the private copy of the input that the Ghidra launcher imports with -readOnly and -deleteProject. It is deleted when the session closes, and nothing of the analysis survives it: "Each new provider session still imports the target into a fresh temporary project." mcp Ghidra first-query deadlines and recovery

Analysis snapshot cache: the in-memory table of one session, AnalysisSnapshotCache, which holds up to 10,000 entries for one target identity. This is the cache this section is about.

Snapshot file: the JSON file that close_binary writes and open_binary reads. It holds the target identity, the provider binding, the cache entries, and the session's Evidence bundle. The CLI documentation says what it is and what it is not: "These are cached observations, not a saved provider database: only eligible exact queries can reuse a result, and new or live queries can still require provider startup." cli Save and reuse analysis snapshots

The query id

Query id: query_ followed by the SHA-256 of canonical JSON holding four things: the target, the binding, the operation, and the parameters. The target is the path-free identity, sha256, kind, format, and architecture. A raw-binary target also carries its entry_point. The binding is the provider and its analysis profile. For the capture that is the digest that starts 01b5d08b, executable, mach-o, arm64, Ghidra 12.1.4, and the profile below.

"upstream_analysis_profile": {
  "provider": {
    "id": "ghidra",
    "name": "Ghidra",
    "version": "12.1.4"
  },
  "parameters": {
    "target_kind": "executable",
    "target_format": "mach-o",
    "architecture": "arm64",
    …
    "function_references": "complete-body-and-entry-reference-manager-v2",
    …
    "analyzer_preset": "ghidra-default"
  },
  "digest": "966e6016…"
},

The parameters are version strings, one per observation contract that the Ghidra adapter makes. The digest is the SHA-256 of the canonical JSON of provider and parameters. A cache entry matches only when the binding's provider and digest equal the selected profile's. A release that moves function_references from -v2 to -v3 changes the digest. Every entry made under the old digest then stops matching. That is what exact means in the thesis of this section.

Version 6.5.0 is such a release. It added four contracts and moved function_boundary_observations from ghidra-terminal-call-limitations-v1 to ghidra-function-boundary-limitations-v3. No 6.4.0 snapshot entry matches a 6.5.0 session. One Ghidra session made all eight rows of the bundle summary, so all of them carry the digest 966e6016… (export and import).

Which calls the cache answers

isSnapshotCacheable decides, before any provider runs, whether a call can be answered from the cache. A call qualifies when all of these hold.

• The operation is not one of the stateful ones, health, current_address, current_procedure, current_document, goto_address, or list_documents.
• An operation that is scoped to a document names its document.
• An operation that defaults to the cursor, such as xrefs, names its address.
• The capability declares mutatesArtifact: false, a cachePolicy other than live, and no permission change.
• Its cachePolicy is snapshot, or it does not write to the file system.

The Ghidra adapter marks every operation except the mutating ones and list_documents with cachePolicy: "snapshot". prepareSessionExecution computes the id and looks it up. BinarySession returns a hit without touching the provider. The replayed answer carries one extra limitation: "Loaded from a local REA analysis snapshot; this call did not re-run the provider.".

The replayed record names the path of the target that is open now. The function rebindEvidenceToTargetPath writes that path into the stored record. The evidence_id does not change, because the path is outside the hash. On Windows, Ghidra must admit the source file before a replay, so a cache hit can still start the provider.

On a miss the provider runs, and the result is bound to the profile and the target. An Evidence record is then created and recorded, and a cache entry is stored under the id.

The capture shows no replay, because no two of its 25 MCP calls had the same operation and parameters. The first Ghidra-backed call after open_binary was list_procedures, and it took between 6 and 7 seconds while the headless import ran. Every later call on that target took under 100 ms (capture/out/10-mcp-session.txt). Those later calls were fast because the bridge was already running, not because of the cache. A repeat of analyze_function with "procedure": "_percent_change" would have been the first replay.

Save and load

close_binary takes snapshot_path and overwrite. closeWithSnapshot drains the calls in progress, exports the snapshot, writes the file, and closes the provider. Its receipt adds primitive_entries, workflow_entries, and evidence_records. open_binary takes snapshot_path too, reads the file before it opens the target, and imports the entries into the new session. The capture closed both targets without a path, so its two close_binary results are null (10-mcp-15-close-binary-O1.json, 10-mcp-25-close-binary-O2.json). On the CLI the flag is --snapshot: "An exact CLI cache hit is normally read before starting a provider process." cli Save and reuse analysis snapshots On Windows the Ghidra provider can start first, because it must admit the source file.

Loading a file is a full check. The entries must be in canonical id order, and every query id is recomputed and must match. No id appears twice. Every entry must have an Evidence record in the bundle with the same profile and the same result. A bundle record for another target fails the whole file.

Writing is atomic: the file is staged with mode 0600, synced, and renamed or hard-linked into place. Importing into a session whose target or profile differs fails with "Analysis snapshot profile_mismatch: target, provider, or analysis profile does not match the active binary".

Invalidation before a mutating call

Some Ghidra operations write to the session database, such as annotate_native_function, which renames a function or adds a comment. Each of them lists mutates_artifact in its effects, and each carries a limitation that names the consequence.

{
  "operations": [
    "annotate_native_function"
  ],
  "effects": [
    "mutates_artifact",
    "launches_process",
    "may_write_filesystem"
  ],
  "limitations": [
    …
    "Metadata edits invalidate immutable analysis snapshots and are discarded on close. CLI returns the updated dossier before session cleanup; this is not a saved Ghidra project."
  ],
  "available": true,
  "reason": null,
  "availability_code": null
}

Before rea sends such a call to the provider, BinarySession calls invalidateSnapshot. The cache is emptied and a flag is set. From then on every lookup returns nothing, every new result is not stored, and an export fails with "Analysis snapshots are unavailable because analysis metadata may have changed". The error adds the way out: export the Evidence with export_evidence_bundle, close the target without a snapshot, and reopen it. An import after a mutation is refused the same way.

At 6.5.0 the order is: invalidate, then call the provider. A failed reply cannot prove that the write did not reach Ghidra. So a mutating call that fails also turns the cache off. The 6.4.0 release used the other order and invalidated only after a successful call. The CLI documentation states the rule: "Dispatching a metadata write invalidates the active session's snapshot cache, even if its reply fails: the provider may already have applied the write." cli Save and reuse analysis snapshots

Sources:capture/README.md; capture/out/00-commands.txt, capture/out/05-analyze-arm64-O1.json, capture/out/10-mcp-04-binary-session.json, capture/out/10-mcp-09-analyze-function-percent-change-O1.json, capture/out/10-mcp-15-close-binary-O1.json, capture/out/10-mcp-25-close-binary-O2.json, capture/out/10-mcp-session.txt; rea 6.5.0 at 3b79af2: src/domain/analysisSnapshot.ts, src/domain/analysisProfile.ts, src/domain/evidence.ts, src/application/binary/AnalysisSnapshotCache.ts, src/application/binary/BinarySession.ts, src/application/binary/BinarySessionExecution.ts, src/application/binary/BinarySessionRecords.ts, src/application/JsonFiles.ts, src/server/registerCloseLifecycleTool.ts, src/server/registerSessionTools.ts, src/ghidra/GhidraLauncher.ts, src/ghidra/GhidraAnalysisProfile.ts, src/ghidra/GhidraProviderCapabilities.ts; rea docs/cli.md, rea docs/mcp-contracts.md

Your agent's MCP connection closes tonight, and with it the eight records it collected on ledger-arm64-O1. Tomorrow a colleague wants to check them on another Mac, without Ghidra. When you finish this section, you can export a session to a bundle and read its summary without an engine. You can also import it into a new session or a CLI check.

export_evidence_bundle

Evidence bundle: one JSON object with seven arrays. They are artifacts, providers, environments, scenarios, captures, unknowns, and records. The first five are built from the records themselves. They hold the distinct subjects as digest, format, and architecture, the distinct providers, and the distinct environments. Then come the controlled-replay records and the process-capture records. Records are sorted by evidence_id, and the order carries no meaning.

The MCP tool takes a path and an overwrite flag. It answers with the path, the byte count, and the record and unknown counts.

"structuredContent": {
  "result": {
    "path": "$WORK/bundle-O1.json",
    "bytes": 178629,
    "records": 8,
    "unknowns": 0
  }
}

The write is canonical and atomic. writeEvidenceBundle validates the bundle again and streams canonical JSON parts. writeTextParts creates a staging file with wx and mode 0600 and syncs it. It then renames the file over the destination when overwrite is true, or hard-links it when the destination must not exist. The contract says the same: "Complete bundle exports stream canonical JSON into an atomically published file." mcp Tool results

The capture copied the file the server wrote to 11-bundle-O1.json, with the capture directory masked and a newline added. Its seven arrays hold one artifact, one provider, no environments, no scenarios, no captures, no unknowns, and eight records.

5e912392…  178206  11-bundle-O1.json (the bytes export_evidence_bundle wrote, with the capture path masked and a newline added)
74f1d786…  286385  11-bundle-O2.json (the bytes export_evidence_bundle wrote, with the capture path masked and a newline added)

inspect-evidence-bundle

You do not need rea's engine, or a session, to read a bundle. rea inspect-evidence-bundle takes a JSON argument with path, detail, and optional filters and prints one row per record without the payloads. The MCP tool get_evidence_bundle shares the projection for the records of a live session.

{
  "kind": "evidence-bundle-summary",
  "filters": {},
  "total_retained_records": 8,
  "matching_records": 8,
  "unknown_revisions": 0,
  "records": [
    {
      "evidence_id": "ev_15244427…",
      …
      "operation": "analyze_function",
      "confidence": "observed",
      "authority": "shipped-artifact",
      "analysis_profile_digest": "966e6016…",
      "retention": "complete-record",
      "limitation_count": 10,
      "native_dossier": {
        "available": true,
        "procedure_address": "0x100000518",
        "procedure_name": "_grade",
        …

The eight rows name four analyze_function dossiers, _percent_change, _grade, _total, and _grade_label, and one record each for list_procedures, procedure_assembly, xrefs, and list_strings. Every row carries the same profile digest, 966e6016…, because one Ghidra session produced them all. The O2 bundle has two rows, the _total and _percent_change dossiers of the -O2 build (11-inspect-evidence-bundle-O2.json). The contract names the filters a summary accepts: "Optional filters match exact evidence_id, operation, target_sha256, analysis_profile_digest or procedure_address." mcp Tool results

evidence-export and evidence-import on the CLI

rea evidence-export SOURCE OUTPUT reads a bundle, validates it, and writes it again in canonical form. The answer is the path, the byte count, and the record count. The capture exported 11-bundle-O1.json to a work file and compared the digests.

5e912392…  178206  export_evidence_bundle over MCP, out/11-bundle-O1.json
5d058cb9…  178205  evidence-export over the CLI, $WORK/canonical-O1.json
same bytes as the MCP export: no
same JSON content as the MCP export: yes

The one byte of difference is the newline the kit appended to its copy. Strip it, and the copy has 178,205 bytes and the digest 5d058cb9, the digest of the CLI file. The MCP server and the CLI write the same canonical bytes for the same records, which is what the thesis of this section promised.

rea evidence-import PATH validates a bundle and reports its counts. On the CLI there is no session, so imported and total are both the number of records in the file: {"imported": 8, "unknowns_added": 0, "total": 8} in 13-evidence-import.json. The CLI documentation draws the line: "Separate CLI calls consume full saved records." cli Import, export and compare Evidence

import_evidence_bundle into a live session

In MCP the same verb merges into the connection's ledger. The handler reads and validates the file, calls importEvidenceBundle, and answers with the records added, the unknown revisions added, and the new total. The ledger adds each record it does not hold and keeps a record it already holds. It refuses a record whose id it holds with different content: "Conflicting evidence record".

"result": {
  "imported": 6,
  "unknowns_added": 0,
  "total": 14
}

Six of eight, and a total of fourteen. The session had closed O1 before, and close_binary empties the ledger: "close_binary clears them, even when no binary is active." mcp Retained application Evidence inputs Opening another target or restarting the current target keeps the records.

So the O1 records were gone when O2 opened. Then compare_functions ran twice, with the O1 dossiers of _percent_change and _total passed inline. The tool records both sides before its own result. Those two O1 records were back in the ledger, so the import added the other six.

The fourteen are the six new records and eight that were already there:

• The two O2 dossiers, from calls 17 and 18.
• The two O1 dossiers that the comparisons recorded as their sources.
• The two comparison records, from calls 20 and 21.
• The verify_reconstruction record, from call 22.
• The mutation record of the unknown that the _total comparison opened (residual unknowns).

Figure 5.5 follows the bundle from the session to its four readers.

Sources:capture/README.md; capture/out/10-mcp-14-export-evidence-bundle-O1.json, capture/out/10-mcp-23-import-evidence-bundle-O1.json, capture/out/11-bundle-O1.json, capture/out/11-bundles.txt, capture/out/11-inspect-evidence-bundle-O1.json, capture/out/11-inspect-evidence-bundle-O2.json, capture/out/12-evidence-export.json, capture/out/12-evidence-export.txt, capture/out/13-evidence-import.json; rea 6.5.0 at 3b79af2: src/domain/evidenceBundle.ts, src/server/registerSessionRecordTools.ts, src/application/EvidenceBundleFiles.ts, src/application/EvidenceBundleCommands.ts, src/application/JsonFiles.ts, src/cliEvidenceCommands.ts, src/cli/analysisViewCommands.ts, src/application/investigation/EvidenceLedger.ts, src/server/registerFunctionComparisonTool.ts, src/server/sessionEvidence.ts; rea docs/mcp-contracts.md, rea docs/cli.md

You rebuilt ledger.c at -O2 and want to know which functions the compiler changed before you trust a claim about the -O1 build. The capture asked rea that question for _percent_change and for _total, with the two builds open in turn. When you finish this section, you can read a comparison record and say what each of its eight dimensions compares. You can also name the limit that keeps a byte-level proof outside rea.

Two dossiers in, one derived record out

compare_functions takes two complete Evidence records as left and right. Each is parsed with parseEvidence, so a record with a tampered id is refused. Each must be an analyze_function record with predicate type rea.analysis, or the tool answers "Expected analyze_function Evidence". The capture passed the dossiers it had received a few calls earlier.

"name": "compare_functions",
"arguments": {
  "left": {
    "evidence_id": "ev_172d39ff…",
    "record": "<cut by run.py: the complete analyze_function record, see 10-mcp-09-analyze-function-percent-change-O1.json>"
  },
  "right": {
    "evidence_id": "ev_1f3bca22…",
    "record": "<cut by run.py: the complete analyze_function record, see 10-mcp-17-analyze-function-percent-change-O2.json>"
  }
}

The answer is a new Evidence record from provider rea-function-comparison version 1. Its predicate type is rea.function-comparison, its confidence derived, and its authority analyst-inference. Both input ids appear as parameters and as evidence_links. The record has no subject, so it carries the automatic limitation about artifact identity (the Evidence record). Before it is recorded, both inputs are recorded in the session ledger, which is why import later found two O1 records already present.

"normalized_result": {
  "status": "unchanged",
  "function_match": {
    "status": "matched",
    "method": "symbol",
    "left_name": "_percent_change",
    "right_name": "_percent_change"
  },
  "left_subject_sha256": "01b5d08b…",
  "right_subject_sha256": "8bbbaa58…",
  "summary": {
    "unchanged": 8,
    "changed": 0,
    "unknown": 0
  },

Function match: how rea decided that the two dossiers describe the same function. matched by symbol means the two procedure names are equal. A mismatched or ambiguous match is reported with method explicit, and an ambiguous match makes the whole comparison unknown.

The eight dimensions

compareDimensions runs eight comparisons in a fixed order: identity, pseudocode, assembly, comments, calls, references, strings_names, and cfg. Each dimension has a status of unchanged, changed, or unknown, and a left and right digest. It also has a left and right count, a text_delta for the two text dimensions, and a conclusion_kind. The overall status is unknown if any dimension is unknown, else changed if any dimension changed, else unchanged.

A dimension is also unknown, with null counts, when either dossier declares a needed facet unavailable in facet_availability. An empty facet with no declaration has the same effect. The call dimension also reads relationship_coverage.

The two text dimensions are line diffs with a budget: 100 ms and 10,000 edits. A diff that runs out of budget makes the dimension unknown with the limitation "Bounded line diff exceeded its time or edit-distance limit.". The counts are code points of the text. The text_delta reports added lines, removed lines, and hunks. Both text dimensions carry the limitation "Exact provider text is compared without address or generated-name normalization; layout-only differences do not establish a behavior change."

For _total, the pseudocode grew by 109 lines and lost 11 in 11 hunks (10-mcp-21-compare-functions-total.json). The assembly grew by 61 lines and lost 12 in 2 hunks. The -O2 build of _total has 16 basic blocks where the -O1 build has 5, and 13 references where it had 4. Those are the facts rea states, and the record stops there. Why the compiler made that change is your question to answer with the two assembly listings.

The assembly limit

Every assembly dimension carries two limitations, whether its status is unchanged or changed.

{
  "dimension": "assembly",
  "left_count": 336,
  "right_count": 1866,
  "evidence_links": [
    "ev_7c94981b…",
    "ev_a36b5090…"
  ],
  "limitations": [
    "Exact provider text is compared without address or generated-name normalization; layout-only differences do not establish a behavior change.",
    "Assembly is opaque provider text; relocation normalization is unavailable."
  ],
  "status": "changed",
  "left_digest": "40e2d441…",
  "right_digest": "e1140153…",
  "text_delta": {
    "added_lines": 61,
    "removed_lines": 12,
    "hunks": 2
  },
  "conclusion_kind": "derived_relationship"
},

rea attaches these strings before any diff runs. The dossier's assembly is Ghidra's listing text, with the addresses and the resolved operands inside the text. The tool compares that text line by line. It does not decode the instructions, it does not know which operand bytes a linker will patch, and it cannot mask them. Two copies of the same code at different addresses diff as changed, and a relocatable object compared with its linked image diffs as changed. The same holds across engines: when the two dossiers come from different providers, both text dimensions become unknown with "Exact text comparison requires one provider identity.".

An unchanged assembly dimension therefore means equal text from one engine, and a changed one means different text. Neither is a statement about bytes. The byte-level proof zeroes the relocation fields and compares the referenced table as well. Lesson 36 builds that proof, and Part 7 runs it against the same fixture. The references dimension has a limit of its own, because it compares the endpoints and not the kinds: "Reference endpoints differ independently of provider reference-kind metadata.".

rea compare on two bundles

rea compare LEFT RIGHT, also spelled rea compare-bundles, compares two bundle files without a session. It works by evidence_id: a record in both bundles is compared, and a record in one bundle only is an unresolved branch. The overall status is unknown as soon as one change is unresolved.

{
  "status": "unknown",
  "left_bundle_sha256": "5d058cb9…",
  "right_bundle_sha256": "f2c85212…",
  "summary": {
    "records_unchanged": 0,
    "records_added": 0,
    "records_removed": 0,
    "records_changed": 0,
    "unknowns_unchanged": 0,
    "unknowns_added": 0,
    "unknowns_removed": 0,
    "unknowns_advanced": 0,
    "unknowns_diverged": 0,
    "unresolved": 10
  },
  "changes": [
    {
      "entity": "evidence",
      "key": "ev_15244427…",
      "classification": "unknown",
      "conclusion_kind": "unresolved_branch",
      "left_evidence_ids": [
        "ev_15244427…"
      ],
      "right_evidence_ids": [],
      "left_digest": "15244427…",
      "right_digest": null,
      "limitations": [
        "EvidenceBundle has no inventory completeness marker; one-sided membership may reflect incomplete capture."
      ]
    },

Ten unresolved, none unchanged, none removed. The two bundles come from two different files, ledger-arm64-O1 and ledger-arm64-O2. No evidence_id is in both, and every one of the ten records is one-sided. The tool does not call a one-sided record removed, because a bundle has no marker of completeness.

The digests it reports are digests of the canonical bytes. 5d058cb9 is the digest of bundle O1 without the kit's trailing newline (export and import). rea compare answers the question "what changed in this evidence set" for two bundles of one build. For two builds, compare_functions is the tool, one function at a time.

Sources:capture/out/10-mcp-20-compare-functions-percent-change.json, capture/out/10-mcp-21-compare-functions-total.json, capture/out/14-compare-bundles.json, capture/out/12-evidence-export.txt; phases/13-tools-and-protocols/36-rebuild-and-prove-equal; rea 6.5.0 at 3b79af2: src/domain/functionComparisonSchemas.ts, src/domain/functionComparisonDimensions.ts, src/domain/functionComparisonNormalization.ts, src/domain/functionComparisonResults.ts, src/domain/bundleComparison.ts, src/server/registerFunctionComparisonTool.ts, src/cliEvidenceCommands.ts, src/application/EvidenceBundleCommands.ts; rea docs/mcp-contracts.md

You have a small Electron-style application, six files in capture/fixtures/js-app/. You want the map before you read code: which renderer talks to which main-process handler, and what leaves the machine. The analysis answers that without Ghidra and without running a line of the application. When you finish this section, you can run the analysis, read the record and its graph, and page through a large result with inspect-analysis-view.

The command and the record

The CLI command is rea analyze-javascript-application PATH. The plain rea analyze PATH reaches the same code for a directory: "Generic rea analyze PATH selects this workflow for directories and .asar files when neither --provider nor --snapshot is supplied." cli Run a command

The inputs are input_path, format as auto, asar, or directory, and integrity_policy. The optional source_paths input names exact inventoried files. rea then analyzes only those files, and the relationships of the other files stay unknown.

Four resource limits are optional. max_heap_mb is 1024 MiB by default, and analysis_timeout_ms is 300,000 ms by default. max_semantic_nodes is 100,000 by default, and max_semantic_nodes_per_file is 20,000. Over MCP, you can also set detail to complete or summary. The parser is @babel/parser. It runs with errorRecovery on, and it does not attach comments.

{
  "evidence_id": "ev_9151392a…",
  "subject": {
    "name": "js-app",
    "digest": {
      "sha256": "bb9f726c…"
    },
    "local_path": "$CAPTURE/fixtures/js-app",
    "format": "directory",
    "architecture": null
  },
  "provider": {
    "id": "rea-javascript-application",
    "name": "REA JavaScript application analyzer",
    "version": "1"
  },
  "analysis_profile": null,
  "predicate_type": "rea.javascript-application-analysis",
  "operation": "analyze_javascript_application",
  "parameters": {
    "format": "auto",
    "integrity_policy": "fail"
  },

This is an Evidence record like the ones in Part 5, with three differences from a Ghidra dossier. The provider is rea itself, rea-javascript-application version 1. The confidence is derived, because rea computed relationships from syntax, and the authority is shipped-artifact, because the six files on disk are the source. The subject is the directory, with the SHA-256 bb9f726c… of its inventory as the digest. The normalized_result has eleven fields: input_path, format, root_artifact_sha256, inventory_manifest_id, inventory_graph_sha256, integrity_contradictions, graph, summary, statistics, limitations, and semantic_graph. A twelfth field, source_selection, is present only when the request names source_paths.

"summary": {
  "browser_windows": 1,
  "explicit_web_preferences": 3,
  "preload_entrypoints": 1,
  "context_bridge_apis": 1,
  "exposed_api_members": 3,
  "ipc": {
    "operations": 6,
    "literal_channels": 3,
    "dynamic_channel_operations": 0,
    "renderer_transmissions": 3,
    "renderer_listeners": 0,
    "main_handlers": 3,
    "paired_renderer_transmissions": 3,
    "ambiguous_renderer_transmissions": 0,
    "unpaired_literal_renderer_transmissions": 0
  },
  …
},
"statistics": {
  "relevant_files": 6,
  "nested_asar_containers": 0,
  "text_bytes_read": 2888,
  "invalid_utf8_files": 0,
  "parsed_javascript_files": 4,
  "visited_ast_nodes": 424,
  "findings": 25,
  "modules": 0,
  "parse_failures": 0
},

Check the numbers against the source in capture/fixtures/js-app/. main.js creates one BrowserWindow with three explicit webPreferences, preload, contextIsolation, and nodeIntegration. preload.js exposes one contextBridge API, ledger, with three members. The six IPC operations are the two invoke and one send in preload.js, and the two handle and one on in main.js. They use three literal channels, and each channel is paired.

Four of the six files are JavaScript, 424 AST nodes were visited, and no file failed to parse. modules counts bundler modules, and this application has no bundle. While the command ran, rea wrote nineteen progress events to stderr, from inventory to the final hash of the record.

[stderr] {"rea_progress":{"phase":"analyze_javascript_application","completed":0,"total":1,"message":"Inventorying and parsing application artifacts","sequence":1}}
…
[stderr] {"rea_progress":{"phase":"parse_javascript_sources","completed":0,"total":1,"message":"Parsing and projecting 6 selected application source files","sequence":3}}
…
[stderr] {"rea_progress":{"phase":"analyze_javascript_application","completed":1,"total":1,"message":"Application graph and Electron boundaries reconstructed","terminal":true,"sequence":19}}

The graph

Application graph: the provider-neutral model of an application as nodes and directed edges, with an evidence block on every edge. The documentation fixes two rules. The graph is built from syntax alone: "It performs no filesystem or CDP I/O, does not evaluate JavaScript, and has no application-specific node kinds." jsgraph JavaScript Application Graph

The edges use a fixed vocabulary: "The directed relation vocabulary is contains, loads, imports, maps_to, exposes, sends, invokes, handles, calls, persists_to, observed_as, and changed_from." jsgraph Entities and relationships

The graph for ledger-desk in 15-js-app-graph.json has 42 nodes and 59 edges. Its own coverage is complete, and it omits nothing.

Every edge says how it was obtained. An AST fact has authority ast-static-analysis, state observed, confidence exact, and a source range. A relationship has authority static-relationship-inference, state inferred, and confidence high by default. It always carries the limitation "Static syntax does not prove that this relationship executes at runtime." The documentation states the rule for the Electron edges: "The loads, exposes, invokes, handles, and imports relationships remain static inferences." jsgraph Entities and relationships

{
  "source_node_id": "jag_node_c239425e…",
  "target_node_id": "jag_node_36721459…",
  "relation": "invokes",
  "properties": {
    "channel": "ledger:grade-label",
    "pairing_basis": "unique-exact-literal-channel",
    "handler_path": "main.js",
    "handler_operation": "handle"
  },
  "evidence": {
    "authority": "static-relationship-inference",
    "state": "inferred",
    "confidence": "high",
    …
    "location": {
      "available": true,
      "value": {
        "kind": "source-range",
        "source": "preload.js",
        "start": {
          "line": 7,
          "column": 25
        },
        "end": {
          "line": 7,
          "column": 72
        }
      }
    },
    …

Line 7 of preload.js, columns 25 to 72, is ipcRenderer.invoke("ledger:grade-label", score). The edge pairs this call with the ipcMain.handle in main.js, because the channel is one exact literal that appears once on each side. It is inferred, not observed, because nothing ran. The same pairing would be ambiguous if two handlers used the channel, and dynamic channel names get no pairing edge at all. Figure 6.1 draws the graph with the file names and channel names from the capture.

Views over a large record

Six files give a record of about 200 KB. The documentation warns about real applications: "The complete application Evidence can be hundreds of megabytes for a real application." cli Run a command

inspect-analysis-view reads a view out of a record that already exists, without running the analysis again. Its input is a source and a view. The source is the complete record inline, or a reference to a record the MCP session retains. The view is a summary, a page of a collection, or one module. The capture asked for the summary and for the first 32 items of the modules collection.

Each view is an Evidence record of its own, from provider rea-analysis-view. The parent id is in parameters.parent_evidence_id and in evidence_links, so the chain from view to analysis is explicit.

"coverage": {
  "application": {
    "status": "complete",
    "truncated": false,
    "omitted_count": 0,
    "limits": []
  },
  …
  "application_unknowns": 0,
  "semantic_unknowns": 118
},
"limitation_count": 7

The application graph is complete. The semantic graph, the second graph in the record, is not. Its coverage status is unknown, each of its twelve families is partial, and 118 semantic unknowns remain. The view lists that fact among its unknowns as semantic_graph.coverage.status is unknown. This is the rule from residual unknowns in a second shape. A graph that says it is partial is more useful than a graph that says nothing.

"items": [
  {
    "node_id": "jag_node_0fc7e361…",
    "kind": "javascript-asset",
    "path": "main.js"
  },
  {
    "node_id": "jag_node_19e7e901…",
    "kind": "javascript-module",
    "path": "main.js"
  },
  …
"coverage": {
  "status": "page",
  "examined": 15,
  "total": 15,
  "next_offset": null,
  "exhausted": true
},

A page says how much of the collection it covers: 15 of 15 items here, with no next offset. For a record with thousands of modules you would read next_offset and ask again. One last detail ties this section to the Evidence record. Both view records carry the application path inside normalized_result and locations. The masked $CAPTURE in the capture therefore changes their ids, and your own run will show different ids for the same views.

Sources:src/cli/electronCommands.ts, src/domain/javascript/javascriptApplicationAnalysis.ts, src/domain/javascript/javascriptAnalysisResourceControls.ts, src/domain/javascript/javascriptSourceParser.ts, src/contracts/javascript/electronToolContracts.ts, src/contracts/analysisViewToolContracts.ts, src/application/javascript/JavaScriptArtifactGraphEvidence.ts, src/domain/javascript/javascriptSourceSelection.ts at rea-agents-6.5.0 (3b79af2); rea docs/cli.md, docs/javascript-application-graph.md, docs/javascript-artifact-reconstruction.md (Select sources before analysis, What is reconstructed), docs/mcp-contracts.md; capture/README.md; capture/fixtures/js-app/main.js, preload.js, renderer.js, ledger.js, index.html, package.json; capture/out/00-commands.txt, 15-js-app.json, 15-js-app-graph.json, 15-js-app-view-summary.json, 15-js-app-view-modules.json

You wrote capture/fixtures/wasm/ledger.wat by hand, with the same four functions as ledger.c, and assembled it to ledger.wasm with wat2wasm. You ask rea 6.5.0 to inspect the module, on the CLI and over MCP, and both entry points return the same Evidence record. When you finish this section, you can set up the WABT provider and read the record. You can also say what the record does not prove.

Setup

WebAssembly is not a native target. open_binary on a module returns target_unavailable with the constraint wasm_requires_static_inspection, and the error names the inspect_wasm_artifact call to make. The tool needs three WABT programs that you install yourself. Set REA_WABT_BIN_DIRECTORY to the absolute directory that holds wasm-validate, wasm-objdump, and wasm2wat. The tool is available only when that variable is absolute, and binary_session reports that availability.

REA_WABT_BIN_DIRECTORY=/opt/homebrew/bin
$ /opt/homebrew/bin/wasm-validate --version
1.0.42
[exit 0]
$ /opt/homebrew/bin/wasm-objdump --version
1.0.42
[exit 0]
$ /opt/homebrew/bin/wasm2wat --version
1.0.42
[exit 0]

The command and the record

The CLI command is rea inspect-wasm-artifact PATH. In the capture it exited 0 after 1.5 s and printed one Evidence record.

$ rea inspect-wasm-artifact fixtures/wasm/ledger.wasm --format json
[exit 0] (1.5 s) -> 16-inspect-wasm-artifact.json

{
  "evidence_id": "ev_b50c217f…",
  "subject": {
    "name": "ledger.wasm",
    "digest": {
      "sha256": "699f6ff7…"
    },
    "local_path": "$CAPTURE/fixtures/wasm/ledger.wasm",
    "format": "file",
    "architecture": null
  },
  "provider": {
    "id": "wabt-artifact",
    "name": "REA WABT artifact adapter",
    "version": "wabt@1.0.42"
  },
  "analysis_profile": null,
  "predicate_type": "rea.analysis",
  "operation": "inspect_wasm_artifact",
  "parameters": {
    "path": "$CAPTURE/fixtures/wasm/ledger.wasm",
    "glue_paths": [],
    "candidate_paths": []
  },