scientific-method-engine 0.8.0__tar.gz → 0.9.0__tar.gz

{scientific_method_engine-0.8.0 → scientific_method_engine-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scientific-method-engine
-Version: 0.8.0
+Version: 0.9.0
 Summary: Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code.
 Project-URL: Source, https://github.com/kibertoad/refurbished-dinosaurs-toolkit/tree/main/packages/scientific-method-engine
 Author: kibertoad
@@ -83,6 +83,7 @@ Exporting for comparison (each writes one file and refuses to overwrite where no
 |---|---|---|
 | `ExportBoundedFlow` | entry, instruction limit (1..10000), output path under `analysis/original/` | instruction metadata of one bounded flow as JSON |
 | `ExportFunctionInventory` | output TSV path (must not exist) | every function's start and body size |
+| `ExportCallEdges` | output JSON path (must not exist), function limit (1..128), one or more function entries | the call and tail-jump edges of the functions Ghidra reaches breadth-first from the entries, with file offsets, as the `ghidraCallEdges` input of `callees` |
 | `ExportFunctionFingerprints` | output TSV path | per-function and per-instruction fingerprints with addresses normalized, for matching functions across versions |
 
 Repairing the analysis (these change the Ghidra program, so run them before reports and keep the

{scientific_method_engine-0.8.0 → scientific_method_engine-0.9.0}/README.md

@@ -68,6 +68,7 @@ Exporting for comparison (each writes one file and refuses to overwrite where no
 |---|---|---|
 | `ExportBoundedFlow` | entry, instruction limit (1..10000), output path under `analysis/original/` | instruction metadata of one bounded flow as JSON |
 | `ExportFunctionInventory` | output TSV path (must not exist) | every function's start and body size |
+| `ExportCallEdges` | output JSON path (must not exist), function limit (1..128), one or more function entries | the call and tail-jump edges of the functions Ghidra reaches breadth-first from the entries, with file offsets, as the `ghidraCallEdges` input of `callees` |
 | `ExportFunctionFingerprints` | output TSV path | per-function and per-instruction fingerprints with addresses normalized, for matching functions across versions |
 
 Repairing the analysis (these change the Ghidra program, so run them before reports and keep the

{scientific_method_engine-0.8.0 → scientific_method_engine-0.9.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "scientific-method-engine"
 # The release workflow writes the published version from the package's release tag.
-version = "0.8.0"
+version = "0.9.0"
 description = "Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code."
 readme = "README.md"
 requires-python = ">=3.12"

{scientific_method_engine-0.8.0 → scientific_method_engine-0.9.0}/src/scientific_method_engine/cli.py

@@ -16,6 +16,7 @@ INSTRUCTION_SEMANTICS = f"pypcode {pypcode.__version__} (Ghidra SLEIGH x86)"
 USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bounds|owner|callees|trace|uses|arguments|"
          "effects|returns|memory|incoming|call-order|guards|allocation|dispatch> <config.json|->\n"
          "effects includes ordered path writes/calls and local restoration witnesses; transactionality remains unestablished.\n"
+         "callees compares its edges with an ExportCallEdges.java export given as ghidraCallEdges.\n"
          "Declared table continuations are separate conditional paths; ordinary computed transfers remain stopped.\n"
          "       scientific-method-engine ghidra-scripts")
 

scientific_method_engine-0.9.0/src/scientific_method_engine/ghidra/ExportCallEdges.java

@@ -0,0 +1,138 @@
+// Exports the call edges Ghidra recovers below given entries, as JSON for the engine's callees cross-check.
+// @category Restoration
+
+import java.io.BufferedWriter;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Set;
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.database.mem.AddressSourceInfo;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.listing.FunctionManager;
+import ghidra.program.model.listing.Instruction;
+import ghidra.program.model.listing.InstructionIterator;
+import ghidra.program.model.symbol.FlowType;
+
+public class ExportCallEdges extends GhidraScript {
+    private static final int MAX_FUNCTIONS = 128;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length < 3) {
+            throw new IllegalArgumentException(
+                "Supply an output JSON path, a function limit and at least one entry address.");
+        }
+        Path output = Path.of(arguments[0]).toAbsolutePath().normalize();
+        if (Files.exists(output)) {
+            throw new IllegalArgumentException("Call edge output already exists: " + output);
+        }
+        int functionLimit = Integer.parseInt(arguments[1]);
+        if (functionLimit < 1 || functionLimit > MAX_FUNCTIONS) {
+            throw new IllegalArgumentException("Function limit must be between 1 and " + MAX_FUNCTIONS + ".");
+        }
+
+        FunctionManager manager = currentProgram.getFunctionManager();
+        List<String> missing = new ArrayList<>();
+        Set<Function> queued = new LinkedHashSet<>();
+        ArrayDeque<Function> queue = new ArrayDeque<>();
+        for (int i = 2; i < arguments.length; i++) {
+            Address address = toAddr(arguments[i]);
+            Function function = address == null ? null : manager.getFunctionAt(address);
+            if (function == null) missing.add(arguments[i]);
+            else if (queued.add(function)) queue.add(function);
+        }
+
+        // Breadth first from the entries, so the function limit keeps the shallowest functions.
+        StringBuilder functions = new StringBuilder();
+        List<String> unread = new ArrayList<>();
+        int exported = 0;
+        while (!queue.isEmpty()) {
+            if (monitor.isCancelled()) throw new InterruptedException("Call edge export cancelled.");
+            Function function = queue.poll();
+            if (exported >= functionLimit) {
+                unread.add(quote(function.getEntryPoint().toString()));
+                continue;
+            }
+            List<String> edges = new ArrayList<>();
+            InstructionIterator instructions = currentProgram.getListing()
+                .getInstructions(function.getBody(), true);
+            while (instructions.hasNext()) {
+                Instruction instruction = instructions.next();
+                FlowType flow = instruction.getFlowType();
+                Address[] destinations = instruction.getFlows();
+                if (flow.isCall() && destinations.length == 0) {
+                    edges.add(edge(instruction, null, flow));
+                }
+                for (Address destination : destinations) {
+                    Function callee = manager.getFunctionAt(destination);
+                    // A jump counts when it enters another function at its entry: a tail transfer.
+                    if (!flow.isCall() && (callee == null || callee.equals(function))) continue;
+                    edges.add(edge(instruction, destination, flow));
+                    // An external function has no body to read; its edge keeps the external address.
+                    if (callee != null && !callee.isExternal() && queued.add(callee)) queue.add(callee);
+                }
+            }
+            if (functions.length() > 0) functions.append(",\n");
+            functions.append("    {\"entry\": ").append(offset(function.getEntryPoint()))
+                .append(", \"address\": ").append(quote(function.getEntryPoint().toString()))
+                .append(", \"edges\": [").append(String.join(", ", edges)).append("]}");
+            exported++;
+        }
+
+        Files.createDirectories(output.getParent());
+        Path temporary = Files.createTempFile(output.getParent(), "call-edges-", ".partial");
+        try {
+            try (BufferedWriter writer = Files.newBufferedWriter(temporary, StandardCharsets.UTF_8)) {
+                writer.write("{\n  \"format\": \"scientific-method-ghidra-call-edges\",\n  \"version\": 1,\n");
+                writer.write("  \"sha256\": " + quote(currentProgram.getExecutableSHA256()) + ",\n");
+                writer.write("  \"functionLimit\": " + functionLimit + ",\n");
+                writer.write("  \"missingEntries\": [" + quoteAll(missing) + "],\n");
+                writer.write("  \"unreadFunctions\": [" + String.join(", ", unread) + "],\n");
+                writer.write("  \"functions\": [\n" + functions + "\n  ]\n}\n");
+            }
+            Files.move(temporary, output); // No replacement, and no final file until the walk completes.
+        }
+        finally { Files.deleteIfExists(temporary); }
+        println("Exported the call edges of " + exported + " functions to " + output);
+    }
+
+    private String edge(Instruction instruction, Address target, FlowType flow) {
+        return "{\"site\": " + offset(instruction.getAddress())
+            + ", \"siteAddress\": " + quote(instruction.getAddress().toString())
+            + ", \"target\": " + (target == null ? "null" : offset(target))
+            + ", \"targetAddress\": " + (target == null ? "null" : quote(target.toString()))
+            + ", \"flow\": " + quote(flow.toString()) + "}";
+    }
+
+    // The file offset the engine uses for an address, or null when the address has no file bytes.
+    private String offset(Address address) {
+        AddressSourceInfo info = currentProgram.getMemory().getAddressSourceInfo(address);
+        if (info == null || info.getFileOffset() < 0) return "null";
+        return Long.toString(info.getFileOffset());
+    }
+
+    private static String quoteAll(List<String> values) {
+        List<String> quoted = new ArrayList<>();
+        for (String value : values) quoted.add(quote(value));
+        return String.join(", ", quoted);
+    }
+
+    private static String quote(String value) {
+        if (value == null) return "null";
+        StringBuilder result = new StringBuilder("\"");
+        for (char c : value.toCharArray()) {
+            if (c == '"' || c == '\\') result.append('\\').append(c);
+            else if (c < 0x20) result.append(String.format("\\u%04x", (int) c));
+            else result.append(c);
+        }
+        return result.append('"').toString();
+    }
+}

{scientific_method_engine-0.8.0 → scientific_method_engine-0.9.0}/src/scientific_method_engine/x86/reports.py

@@ -1,4 +1,5 @@
 """Focused reports derived from instruction paths and explicit source bounds."""
+import hashlib
 from bisect import bisect_right
 from collections import deque
 from capstone import CS_AC_READ, CS_AC_WRITE
@@ -859,8 +860,13 @@ def callees(image, config):
     depth_limit = integer(config.get("depthLimit", 16), 1, 128, "callee depth limit")
     instruction_limit = integer(config.get("instructionLimit", 10000), 1, 100000, "instruction limit")
     controls = config.get("controls", {})
-    if not isinstance(controls, dict) or set(controls) - {"sharedSites", "recursiveSites", "writeSites"}:
+    if not isinstance(controls, dict) or set(controls) - {"sharedSites", "recursiveSites", "writeSites", "ghidraAgreementSites"}:
         raise ValueError("Invalid callee controls")
+    export = config.get("ghidraCallEdges")
+    if export is not None:
+        export = _ghidra_call_edges(image, export)
+    elif "ghidraAgreementSites" in controls:
+        raise ValueError("ghidraAgreementSites needs ghidraCallEdges")
     nodes, edges, omitted = {}, [], []
 
     def read(entry):
@@ -984,15 +990,17 @@ def callees(image, config):
                 and not s["omittedRoutes"]
                 and not any(d.get("reason") in capped for at in s["entries"] for d in nodes[at]["dependencies"])
                 and not any(d.get("reason") in capped for i in s["dependencyEdges"] for d in edges[i]["dependencies"]))
+    cross_check = _ghidra_cross_check(export, nodes, outgoing, omitted) if export is not None else None
     known = {"sharedSites": {e["site"] for e in edges if shared_control(e)},
              "recursiveSites": {e["site"] for e in edges if e["classification"] == "recursivePath"},
-             "writeSites": {o["site"] for n in nodes.values() for o in n["memoryObservations"] if o["boundaryUsable"] and "write" in o["access"]}}
+             "writeSites": {o["site"] for n in nodes.values() for o in n["memoryObservations"] if o["boundaryUsable"] and "write" in o["access"]},
+             "ghidraAgreementSites": cross_check and cross_check["agreementSites"]}
     for kind, sites in controls.items():
         if not isinstance(sites, list) or len(sites) > 256 or any(type(at) is not int or at not in known[kind] for at in sites):
             raise ValueError("Callee positive control missed: " + kind)
     return {"root": root, "nodes": [{k: v for k, v in n.items() if k != "body"} | {"body": _body_report(n["body"])} for n in nodes.values()],
             "edges": edges, "calleeSummaries": list(summaries.values()), "omittedRoutes": omitted, "uncheckedEntries": unchecked,
-            "controls": controls,
+            "controls": controls, "ghidraCrossCheck": cross_check and {k: v for k, v in cross_check.items() if k != "agreementSites"},
             "completeWithinDeclaredGraph": not omitted and all(n["boundaryUsable"] for n in nodes.values()) and not any(e["dependencies"] for e in edges),
             "exclusions": ["implicit memory effects", "computed/unestablished targets", "argument-sensitive effects", "runtime reachability"],
             "interpretation": "Nodes are read breadth-first; path is the shortest read route to the caller. A recursivePath is a "
@@ -1000,6 +1008,100 @@ def callees(image, config):
                               "that does not. Neither proves runtime recursion."}
 
 
+GHIDRA_CALL_EDGES = "scientific-method-ghidra-call-edges"
+
+
+def _ghidra_call_edges(image, export):
+    """Validate an ExportCallEdges.java export against the image; returns its edges keyed by caller file offset."""
+    if not isinstance(export, dict) or export.get("format") != GHIDRA_CALL_EDGES or export.get("version") != 1:
+        raise ValueError("ghidraCallEdges must be an ExportCallEdges.java export, format version 1")
+    if not isinstance(export.get("sha256"), str) or export["sha256"].lower() != hashlib.sha256(image.data).hexdigest():
+        raise ValueError("ghidraCallEdges was exported from a different file")
+    functions = export.get("functions")
+    if not isinstance(functions, list) or len(functions) > 128:
+        raise ValueError("ghidraCallEdges functions must be a list of at most 128")
+    for key in ("missingEntries", "unreadFunctions"):
+        if not isinstance(export.get(key), list) or not all(isinstance(v, str) for v in export[key]):
+            raise ValueError(f"ghidraCallEdges {key} must be a list of addresses")
+
+    def offset(value, label):
+        if value is None:
+            return None
+        return integer(value, 0, len(image.data) - 1, "Ghidra " + label + " file offset")
+    callers, unmapped, total = {}, [], 0
+    for function in functions:
+        if not isinstance(function, dict) or not isinstance(function.get("address"), str) or not isinstance(function.get("edges"), list):
+            raise ValueError("Invalid ghidraCallEdges function")
+        total += len(function["edges"])
+        if total > 8192:
+            raise ValueError("ghidraCallEdges holds more than 8192 edges")
+        rows = []
+        for edge in function["edges"]:
+            if (not isinstance(edge, dict) or not isinstance(edge.get("siteAddress"), str) or not isinstance(edge.get("flow"), str)
+                    or not (edge.get("targetAddress") is None or isinstance(edge["targetAddress"], str))):
+                raise ValueError("Invalid ghidraCallEdges edge")
+            rows.append({"site": offset(edge.get("site"), "site"), "siteAddress": edge["siteAddress"],
+                         "target": offset(edge.get("target"), "target"), "targetAddress": edge["targetAddress"], "flow": edge["flow"]})
+        entry = offset(function.get("entry"), "entry")
+        if entry is None:
+            unmapped.append(function["address"])
+        elif entry in callers:
+            raise ValueError("ghidraCallEdges exports one function twice")
+        else:
+            callers[entry] = rows
+    return {"callers": callers, "unmappedFunctions": unmapped, "missingEntries": export["missingEntries"],
+            "unreadFunctions": export["unreadFunctions"]}
+
+
+def _ghidra_key(g):
+    """The (site, target) an exported edge matches on.
+
+    A null target matches the engine's unresolved call only when Ghidra resolved no address either;
+    a target address without file bytes (an import, uninitialized memory) matches nothing.
+    """
+    if g["target"] is None and g["targetAddress"] is not None:
+        return g["site"], ("withoutFileOffset", g["targetAddress"])
+    return g["site"], g["target"]
+
+
+def _ghidra_cross_check(export, nodes, outgoing, omitted):
+    """Compare the engine's edges with Ghidra's for each caller both read; a Ghidra-only edge stays unchecked."""
+    callers = export["callers"]
+    compared = sorted(nodes.keys() & callers.keys())
+    rows = []
+    for caller in compared:
+        ours = outgoing.get(caller, [])
+        theirs = callers[caller]
+        # A call neither analysis resolved matches on its site with no target.
+        flows = {_ghidra_key(g): g["flow"] for g in theirs if g["site"] is not None}
+        read = {(e["site"], e["target"]) for e in ours}
+        for e in ours:
+            flow = flows.get((e["site"], e["target"]))
+            rows.append({"caller": caller, "site": e["site"], "target": e["target"], "engineEdge": e["id"],
+                         "result": "engineOnly" if flow is None else "agreement", "ghidraFlow": flow})
+        for g in theirs:
+            if g["site"] is not None and _ghidra_key(g) in read:
+                continue
+            # Ghidra's edge is evidence the engine did not check; it never becomes an engine edge.
+            rows.append({"caller": caller, "site": g["site"], "target": g["target"], "siteAddress": g["siteAddress"],
+                         "targetAddress": g["targetAddress"], "ghidraFlow": g["flow"], "result": "ghidraOnly", "checked": False,
+                         "engineEdge": next((e["id"] for e in ours if g["site"] is not None and e["site"] == g["site"]), None)})
+    counts = {kind: sum(r["result"] == kind for r in rows) for kind in ("agreement", "engineOnly", "ghidraOnly")}
+    not_compared = {"engineCallers": sorted(nodes.keys() - callers.keys()), "ghidraCallers": sorted(callers.keys() - nodes.keys()),
+                    "unmappedGhidraFunctions": export["unmappedFunctions"], "missingGhidraEntries": export["missingEntries"],
+                    "unreadGhidraFunctions": export["unreadFunctions"],
+                    "omittedEngineRoutes": [o["id"] for o in omitted if o["entry"] in callers]}
+    # A site agrees only when every edge either analysis read there agrees.
+    disputed = {r["site"] for r in rows if r["result"] != "agreement"}
+    return {"comparedCallers": compared, "edges": rows, "counts": counts, "notCompared": not_compared,
+            "agreed": not counts["engineOnly"] and not counts["ghidraOnly"] and not any(not_compared.values()),
+            "agreementSites": {r["site"] for r in rows if r["result"] == "agreement"} - disputed,
+            "interpretation": "Edges of each caller that both the engine and the Ghidra export read, matched by site and target "
+                              "file offset; an unresolved call matches an unresolved call at its site, and a Ghidra target without a file offset "
+                              "matches no engine edge. A ghidraOnly edge is Ghidra's claim: the engine did not check it and never adds it to "
+                              "its graph. Agreement means both analyses read the edge, not that it executes."}
+
+
 # These branches test CX/ECX (LOOPE/LOOPNE also ZF), so an adjacent CMP/TEST never describes their predicate.
 COUNT_BRANCHES = frozenset(("jcxz", "jecxz", "jrcxz", "loop", "loope", "loopne", "loopz", "loopnz"))
 

{scientific_method_engine-0.8.0 → scientific_method_engine-0.9.0}/tests/test_x86.py

@@ -371,6 +371,114 @@ class CalleeGraphTests(unittest.TestCase):
         self.assertEqual([o["access"] for o in r["nodes"][0]["memoryObservations"]], [["write"], ["write"], ["read"]])
 
 
+def ghidra_export(data, functions, **extra):
+    """A synthetic ExportCallEdges.java export: functions maps an entry offset to (site, target, flow) edges."""
+    rows = [{"entry": entry, "address": "2000:0000" if entry is None else f"1000:{entry:04x}",
+             "edges": [{"site": site, "siteAddress": f"1000:{site:04x}", "target": target,
+                        "targetAddress": None if target is None else f"1000:{target:04x}", "flow": flow}
+                       for site, target, flow in edges]}
+            for entry, edges in functions.items()]
+    return {"format": "scientific-method-ghidra-call-edges", "version": 1, "sha256": hashlib.sha256(data).hexdigest(),
+            "functionLimit": 128, "missingEntries": [], "unreadFunctions": [], "functions": rows, **extra}
+
+
+class GhidraCrossCheckTests(unittest.TestCase):
+    # root: call a (site 0); call b (site 3); call bx (site 6); ret. a and b return.
+    code = Code().label("root").branch("e8", "a").branch("e8", "b").emit("ff d3 c3").label("a").emit("c3").label("b").emit("c3")
+
+    def cross(self, functions, controls=None, **extra):
+        data = self.code.bytes()
+        cfg = configuration(data, ghidraCallEdges=ghidra_export(data, functions, **extra), controls=controls or {})
+        cfg["regions"][0]["entries"] = [self.code.labels[n] for n in ("root", "a", "b")]
+        return run_report(data, cfg, "callees")
+
+    def test_each_edge_is_agreement_engine_only_or_unchecked_ghidra_only(self):
+        a, b = self.code.labels["a"], self.code.labels["b"]
+        r = self.cross({0: [(0, a, "UNCONDITIONAL_CALL"), (6, b, "COMPUTED_CALL")], b: []}, controls={"ghidraAgreementSites": [0]})
+        check = r["ghidraCrossCheck"]
+        rows = {(e["site"], e["target"], e["result"]) for e in check["edges"]}
+        self.assertEqual(rows, {(0, a, "agreement"), (3, b, "engineOnly"), (6, None, "engineOnly"), (6, b, "ghidraOnly")})
+        ghidra_only = next(e for e in check["edges"] if e["result"] == "ghidraOnly")
+        self.assertFalse(ghidra_only["checked"])
+        self.assertEqual(ghidra_only["engineEdge"], 2)
+        # Ghidra's computed target never becomes an engine edge.
+        self.assertIsNone(r["edges"][2]["target"])
+        self.assertEqual(r["edges"][2]["classification"], "unresolved")
+        self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 2, "ghidraOnly": 1})
+        self.assertEqual(check["comparedCallers"], [0, b])
+        self.assertEqual(check["notCompared"]["engineCallers"], [a])
+        self.assertFalse(check["agreed"])
+
+    def test_matching_graphs_agree_on_resolved_and_unresolved_calls(self):
+        # call 6; call bx; ret; ret
+        data = bytes.fromhex("e8 03 00 ff d3 c3 c3")
+        cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(0, 6, "UNCONDITIONAL_CALL"), (3, None, "COMPUTED_CALL")], 6: []}),
+                            controls={"ghidraAgreementSites": [0, 3]})
+        cfg["regions"][0]["entries"] = [0, 6]
+        r = run_report(data, cfg, "callees")
+        check = r["ghidraCrossCheck"]
+        self.assertTrue(check["agreed"])
+        self.assertEqual(check["counts"], {"agreement": 2, "engineOnly": 0, "ghidraOnly": 0})
+        # Agreement on an unresolved call leaves the engine's edge unresolved.
+        self.assertEqual(r["edges"][1]["classification"], "unresolved")
+
+    def test_a_ghidra_target_without_file_bytes_does_not_match_an_unresolved_call(self):
+        # call 6; call bx; ret; ret. Ghidra resolves call bx to an import, which has no file offset.
+        data = bytes.fromhex("e8 03 00 ff d3 c3 c3")
+        export = ghidra_export(data, {0: [(0, 6, "UNCONDITIONAL_CALL"), (3, None, "COMPUTED_CALL")], 6: []})
+        export["functions"][0]["edges"][1]["targetAddress"] = "EXTERNAL:00000001"
+        cfg = configuration(data, ghidraCallEdges=export)
+        cfg["regions"][0]["entries"] = [0, 6]
+        check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
+        self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 1, "ghidraOnly": 1})
+        self.assertFalse(check["agreed"])
+        cfg["controls"] = {"ghidraAgreementSites": [3]}
+        with self.assertRaisesRegex(ValueError, "positive control missed: ghidraAgreementSites"):
+            run_report(data, cfg, "callees")
+
+    def test_routes_the_edge_limit_omitted_are_not_compared(self):
+        # call 6; call bx; ret; ret. Ghidra misses call bx, and the engine omits it at the edge limit.
+        data = bytes.fromhex("e8 03 00 ff d3 c3 c3")
+        cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(0, 6, "UNCONDITIONAL_CALL")], 6: []}), edgeLimit=1)
+        cfg["regions"][0]["entries"] = [0, 6]
+        r = run_report(data, cfg, "callees")
+        check = r["ghidraCrossCheck"]
+        self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 0, "ghidraOnly": 0})
+        self.assertEqual(check["notCompared"]["omittedEngineRoutes"], [r["omittedRoutes"][0]["id"]])
+        self.assertFalse(check["agreed"])
+
+    def test_missed_agreement_control_fails(self):
+        a, b = self.code.labels["a"], self.code.labels["b"]
+        with self.assertRaisesRegex(ValueError, "positive control missed: ghidraAgreementSites"):
+            self.cross({0: [(0, a, "UNCONDITIONAL_CALL")], b: []}, controls={"ghidraAgreementSites": [3]})
+        # A site where Ghidra also reads a target the engine did not is disputed.
+        with self.assertRaisesRegex(ValueError, "positive control missed: ghidraAgreementSites"):
+            self.cross({0: [(0, a, "UNCONDITIONAL_CALL"), (0, b, "UNCONDITIONAL_CALL")], b: []},
+                       controls={"ghidraAgreementSites": [0]})
+        data = self.code.bytes()
+        with self.assertRaisesRegex(ValueError, "needs ghidraCallEdges"):
+            run_report(data, configuration(data, controls={"ghidraAgreementSites": [0]}), "callees")
+
+    def test_unmapped_missing_and_unread_functions_are_not_compared(self):
+        r = self.cross({0: [], None: []}, missingEntries=["1000:0100"], unreadFunctions=["1000:0200"])
+        left = r["ghidraCrossCheck"]["notCompared"]
+        self.assertEqual(left["unmappedGhidraFunctions"], ["2000:0000"])
+        self.assertEqual(left["missingGhidraEntries"], ["1000:0100"])
+        self.assertEqual(left["unreadGhidraFunctions"], ["1000:0200"])
+        self.assertFalse(r["ghidraCrossCheck"]["agreed"])
+
+    def test_export_from_another_file_or_format_is_rejected(self):
+        data = self.code.bytes()
+        for export, message in (({**ghidra_export(data, {}), "sha256": "0" * 64}, "different file"),
+                                ({**ghidra_export(data, {}), "version": 2}, "format version 1"),
+                                (ghidra_export(data, {len(data): []}), "file offset"),
+                                (ghidra_export(data, {0: [(0, None, 3)]}), "Invalid ghidraCallEdges edge"),
+                                ({**ghidra_export(data, {}), "functions": [{}] * 129}, "at most 128"),
+                                (ghidra_export(data, {0: [(0, None, "COMPUTED_CALL")] * 8193}), "more than 8192 edges")):
+            with self.subTest(message=message), self.assertRaisesRegex(ValueError, message):
+                run_report(data, configuration(data, ghidraCallEdges=export), "callees")
+
+
 class OperandCandidateTests(unittest.TestCase):
     def test_prefix_width_and_overlap_candidates_do_not_invent_a_second_use(self):
         data = bytes.fromhex("66 83 3e f6 02 00 c3")