scientific-method-engine 0.1.0__tar.gz

scientific_method_engine-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.config/
+.idea/
+.vs/
+**/bin/
+**/obj/
+artifacts/
+template-next/
+TestResults/
+*.user
+*.suo
+
+__pycache__/
+*.pyc
+.venv/
+analysis/original/
+node_modules/
+dist/
+packages/*/LICENSE
+# The reader's command-line entry point is source, unlike .NET build output.
+!packages/executable-reader/bin/

scientific_method_engine-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scientific_method_engine-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: scientific-method-engine
+Version: 0.1.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
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: capstone==5.0.7
+Description-Content-Type: text/markdown
+
+# scientific-method-engine
+
+Bounded instruction-derived x86 evidence reports for segmented 16-bit MZ/FBOV code and
+PE32/i386 code. The engine decodes instructions with Capstone, follows bounded paths and emits
+`bounded-x86-v1` JSON. It never runs the original program.
+
+```sh
+uv add --group research scientific-method-engine     # or: pip install scientific-method-engine
+```
+
+For original MZ/FBOV executables, run reports through
+[`@scientific-method/executable-reader`](https://www.npmjs.com/package/@scientific-method/executable-reader). The
+reader derives relocation, fixup and trampoline data from the hash-checked source and pipes a
+prepared config to this engine. Running the engine directly trusts whatever relocation data the
+config supplies, so use it directly only for synthetic inputs, PE32 sources and checked mappings:
+
+```sh
+scientific-method-engine trace analysis/query.json
+python -m scientific_method_engine trace analysis/query.json
+```
+
+The package also carries the shared Ghidra headless scripts. `scientific-method-engine
+ghidra-scripts` prints their directory, for Ghidra's `-scriptPath`:
+
+```powershell
+& "$env:GHIDRA_HOME/support/analyzeHeadless.bat" $project $name -process GAME.EXE -noanalysis `
+  -scriptPath (scientific-method-engine ghidra-scripts) -postScript ReportReferences.java 0x1234
+```
+
+Addresses are Ghidra addresses (`0x00401000`, or `1028:d820` for segmented programs). Report scripts
+print to the analyzer log and cap their output. The scripts compile against Ghidra 12.1.
+
+Reading code and data:
+
+| Script | Arguments | Prints |
+|---|---|---|
+| `ReportInstructionContext` | one or more instruction addresses | a bounded instruction window around each |
+| `ReportInstructionWindow` | address, instruction count | instructions from the address onward |
+| `ReportDataBytes` | address, byte count (1..256) | the bytes at the address |
+| `ReportFunctionSummary` | one or more addresses | focused decompiler output of each containing function |
+| `ReportDecompileWindow` | address, first line (1-based), line count | a window of one function's decompilation |
+| `ReportDecompileMatches` | address, one or more literal text patterns | decompilation lines around each match |
+| `ReportMemoryBlocks` | nothing, `page <start> <count>`, or `name <exact-name>` | memory block indexes, names, ranges and sizes, never bytes |
+| `ReportFilePatternInMemory` | file offset (hex), optional pattern length (default 8) | where the bytes at that file offset occur in loaded memory |
+| `ReportMemoryBlockForFileOffset` | one or more file offsets (hex) | the memory block and instructions where each offset's bytes are loaded |
+
+Finding references and calls:
+
+| Script | Arguments | Prints |
+|---|---|---|
+| `ReportReferences` | one or more addresses | references to each, with the referring instruction and function |
+| `ReportStringReferences` | one or more literal string fragments | strings containing a fragment and their references |
+| `ReportSymbolReferences` | one or more symbol-name fragments | matching symbols and their references |
+| `ReportScalarConstants` | one or more scalar values | instructions using any of them, unsigned or signed |
+| `ReportFunctionScalarConstants` | function address, one or more scalar values | instructions inside one function using any of them, compared unsigned |
+| `ReportCallArguments` | callee address | the three nearest pushed arguments at every direct call |
+| `ReportCallSitesWithScalars` | callee address, one or more scalar values | calls whose argument setup contains a requested value |
+| `ReportConstantFirstArgumentCalls` | callee address, constant | cdecl calls whose first argument is the constant |
+| `ReportFirstArgumentCallSummary` | callee address | the literal first argument of every call, and calls without one |
+| `ReportCallsToRange` | start address, end address (inclusive) | calls and jumps whose target lies in the range |
+| `ReportCallPaths` | start function, target function, maximum depth | direct-call paths between the two |
+| `ReportRandomnessCandidates` | none | references to C runtime and Windows random and timing functions |
+
+Exporting for comparison (each writes one file and refuses to overwrite where noted):
+
+| Script | Arguments | Writes |
+|---|---|---|
+| `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 |
+| `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
+argument lists with the evidence that justifies them):
+
+| Script | Arguments | Changes |
+|---|---|---|
+| `CreateFunctions` | one or more entry addresses | creates functions at indirect-call targets Ghidra missed |
+| `RecoverCitedFunctions` | file of 8-digit hex addresses, optional CSV column | disassembles and creates a function at each address inside executable memory |
+| `ClearNoReturnFunctions` | one or more addresses | clears a wrong no-return flag on each containing function |
+| `RepairReturningCallers` | callee entry, caller entry, verified call addresses | checks each call targets the callee from inside the caller, clears the callee's no-return flag and the calls' flow overrides, disassembles each continuation and recomputes the caller's body |
+| `MergeFallThroughFragment` | parent entry, fragment entry | merges an orphan fragment reached by the parent's fall-through into the parent |
+
+Restoration tools that build report configs can import the parsers directly, for example to
+derive a PE32 source's executable sections:
+
+```python
+from scientific_method_engine.x86.pe import pe32
+
+sections = [s for s in pe32(data)["sections"] if s["executable"]]
+```
+
+`scientific_method_engine.x86.pe.pe32` and `scientific_method_engine.x86.image.read_source` are
+supported imports and change only in a major release. Other modules are internal.
+
+Commands, inputs, limits and acceptance rules are in
+[the bounded evidence reporter guide](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md).
+The reader and engine check that they speak the same prepared-config protocol and refuse to run
+otherwise.

scientific_method_engine-0.1.0/README.md

@@ -0,0 +1,98 @@
+# scientific-method-engine
+
+Bounded instruction-derived x86 evidence reports for segmented 16-bit MZ/FBOV code and
+PE32/i386 code. The engine decodes instructions with Capstone, follows bounded paths and emits
+`bounded-x86-v1` JSON. It never runs the original program.
+
+```sh
+uv add --group research scientific-method-engine     # or: pip install scientific-method-engine
+```
+
+For original MZ/FBOV executables, run reports through
+[`@scientific-method/executable-reader`](https://www.npmjs.com/package/@scientific-method/executable-reader). The
+reader derives relocation, fixup and trampoline data from the hash-checked source and pipes a
+prepared config to this engine. Running the engine directly trusts whatever relocation data the
+config supplies, so use it directly only for synthetic inputs, PE32 sources and checked mappings:
+
+```sh
+scientific-method-engine trace analysis/query.json
+python -m scientific_method_engine trace analysis/query.json
+```
+
+The package also carries the shared Ghidra headless scripts. `scientific-method-engine
+ghidra-scripts` prints their directory, for Ghidra's `-scriptPath`:
+
+```powershell
+& "$env:GHIDRA_HOME/support/analyzeHeadless.bat" $project $name -process GAME.EXE -noanalysis `
+  -scriptPath (scientific-method-engine ghidra-scripts) -postScript ReportReferences.java 0x1234
+```
+
+Addresses are Ghidra addresses (`0x00401000`, or `1028:d820` for segmented programs). Report scripts
+print to the analyzer log and cap their output. The scripts compile against Ghidra 12.1.
+
+Reading code and data:
+
+| Script | Arguments | Prints |
+|---|---|---|
+| `ReportInstructionContext` | one or more instruction addresses | a bounded instruction window around each |
+| `ReportInstructionWindow` | address, instruction count | instructions from the address onward |
+| `ReportDataBytes` | address, byte count (1..256) | the bytes at the address |
+| `ReportFunctionSummary` | one or more addresses | focused decompiler output of each containing function |
+| `ReportDecompileWindow` | address, first line (1-based), line count | a window of one function's decompilation |
+| `ReportDecompileMatches` | address, one or more literal text patterns | decompilation lines around each match |
+| `ReportMemoryBlocks` | nothing, `page <start> <count>`, or `name <exact-name>` | memory block indexes, names, ranges and sizes, never bytes |
+| `ReportFilePatternInMemory` | file offset (hex), optional pattern length (default 8) | where the bytes at that file offset occur in loaded memory |
+| `ReportMemoryBlockForFileOffset` | one or more file offsets (hex) | the memory block and instructions where each offset's bytes are loaded |
+
+Finding references and calls:
+
+| Script | Arguments | Prints |
+|---|---|---|
+| `ReportReferences` | one or more addresses | references to each, with the referring instruction and function |
+| `ReportStringReferences` | one or more literal string fragments | strings containing a fragment and their references |
+| `ReportSymbolReferences` | one or more symbol-name fragments | matching symbols and their references |
+| `ReportScalarConstants` | one or more scalar values | instructions using any of them, unsigned or signed |
+| `ReportFunctionScalarConstants` | function address, one or more scalar values | instructions inside one function using any of them, compared unsigned |
+| `ReportCallArguments` | callee address | the three nearest pushed arguments at every direct call |
+| `ReportCallSitesWithScalars` | callee address, one or more scalar values | calls whose argument setup contains a requested value |
+| `ReportConstantFirstArgumentCalls` | callee address, constant | cdecl calls whose first argument is the constant |
+| `ReportFirstArgumentCallSummary` | callee address | the literal first argument of every call, and calls without one |
+| `ReportCallsToRange` | start address, end address (inclusive) | calls and jumps whose target lies in the range |
+| `ReportCallPaths` | start function, target function, maximum depth | direct-call paths between the two |
+| `ReportRandomnessCandidates` | none | references to C runtime and Windows random and timing functions |
+
+Exporting for comparison (each writes one file and refuses to overwrite where noted):
+
+| Script | Arguments | Writes |
+|---|---|---|
+| `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 |
+| `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
+argument lists with the evidence that justifies them):
+
+| Script | Arguments | Changes |
+|---|---|---|
+| `CreateFunctions` | one or more entry addresses | creates functions at indirect-call targets Ghidra missed |
+| `RecoverCitedFunctions` | file of 8-digit hex addresses, optional CSV column | disassembles and creates a function at each address inside executable memory |
+| `ClearNoReturnFunctions` | one or more addresses | clears a wrong no-return flag on each containing function |
+| `RepairReturningCallers` | callee entry, caller entry, verified call addresses | checks each call targets the callee from inside the caller, clears the callee's no-return flag and the calls' flow overrides, disassembles each continuation and recomputes the caller's body |
+| `MergeFallThroughFragment` | parent entry, fragment entry | merges an orphan fragment reached by the parent's fall-through into the parent |
+
+Restoration tools that build report configs can import the parsers directly, for example to
+derive a PE32 source's executable sections:
+
+```python
+from scientific_method_engine.x86.pe import pe32
+
+sections = [s for s in pe32(data)["sections"] if s["executable"]]
+```
+
+`scientific_method_engine.x86.pe.pe32` and `scientific_method_engine.x86.image.read_source` are
+supported imports and change only in a major release. Other modules are internal.
+
+Commands, inputs, limits and acceptance rules are in
+[the bounded evidence reporter guide](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md).
+The reader and engine check that they speak the same prepared-config protocol and refuse to run
+otherwise.

scientific_method_engine-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "scientific-method-engine"
+# The release workflow writes the published version from the package's release tag.
+version = "0.1.0"
+description = "Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "kibertoad" }]
+dependencies = ["capstone==5.0.7"]
+
+[project.scripts]
+scientific-method-engine = "scientific_method_engine.cli:run"
+
+[project.urls]
+Source = "https://github.com/kibertoad/refurbished-dinosaurs-toolkit/tree/main/packages/scientific-method-engine"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/scientific_method_engine"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "pyproject.toml"]

scientific_method_engine-0.1.0/src/scientific_method_engine/__init__.py

@@ -0,0 +1,5 @@
+"""Bounded instruction-derived x86 evidence reports."""
+
+# The reader passes this number with every prepared config it pipes to the engine. A reader and
+# engine that disagree on it refuse to run instead of exchanging relocation data in another shape.
+PREPARED_PROTOCOL = 1

scientific_method_engine-0.1.0/src/scientific_method_engine/__main__.py

@@ -0,0 +1,3 @@
+from .cli import run
+
+run()

scientific_method_engine-0.1.0/src/scientific_method_engine/cli.py

@@ -0,0 +1,75 @@
+"""Read-only bounded x86 evidence reports. Keep configs and reports in GAME_DIR, uncommitted."""
+import json
+import sys
+from pathlib import Path
+
+from . import PREPARED_PROTOCOL
+
+CONFIG_LIMIT = 1024 * 1024
+PREPARED_CONFIG_LIMIT = 16 * 1024 * 1024
+USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bounds|owner|callees|trace|uses|arguments|"
+         "effects|returns|memory|incoming|guards|allocation|dispatch> <config.json|->\n"
+         "       scientific-method-engine ghidra-scripts")
+
+
+def ghidra_scripts():
+    """The directory to pass to Ghidra's analyzeHeadless -scriptPath."""
+    return Path(__file__).resolve().parent / "ghidra"
+
+
+def main(argv):
+    """Run one command (``argv`` excludes the program name) and print its JSON report."""
+    from .x86.image import read_source
+    from .x86.reports import run_report
+    if argv == ["ghidra-scripts"]:
+        print(ghidra_scripts())
+        return
+    if len(argv) != 2:
+        raise ValueError(USAGE)
+    command, config_path = argv
+    reject_derived = False
+    if config_path == "-":
+        # The reader caps its input at 1 MiB, then adds every source relocation.
+        limit, label = PREPARED_CONFIG_LIMIT, "Prepared config exceeds 16 MiB"
+        text = sys.stdin.read(limit + 1)
+        base = Path.cwd()
+    else:
+        limit, label = CONFIG_LIMIT, "Config exceeds 1 MiB"
+        path = Path(config_path).resolve()
+        if path.stat().st_size > limit:
+            raise ValueError(label)
+        text, base = path.read_text(encoding="utf-8"), path.parent
+        reject_derived = True
+    if len(text.encode("utf-8")) > limit:
+        raise ValueError(label)
+    config = json.loads(text)
+    if not isinstance(config, dict):
+        raise ValueError("Config must be an object")
+    if reject_derived and "overlayExports" in config:
+        # Only the reader's MZ/FBOV loader (stdin mode) derives overlay exports from source tables.
+        raise ValueError("overlayExports is source-derived and cannot be supplied")
+    if config_path == "-":
+        protocol = config.pop("preparedProtocol", None)
+        if protocol != PREPARED_PROTOCOL:
+            raise ValueError(f"Reader sent prepared config protocol {protocol}; this engine reads protocol "
+                             f"{PREPARED_PROTOCOL}. Install matching @scientific-method/executable-reader and "
+                             "scientific-method-engine releases.")
+    elif "preparedProtocol" in config:
+        raise ValueError("preparedProtocol is set by the reader and cannot be supplied")
+    data, identity = read_source(config, base)
+    result = run_report(data, config, command)
+    print(json.dumps({"schema": "bounded-x86-v1", "decoder": "capstone 5.0.7", "sourceIdentity": identity,
+                      "status": "Conditional static report; never promotes an evidence entry", **result}, indent=2))
+
+
+def run():
+    """Entry point of the ``scientific-method-engine`` command; exits with 1 on any error."""
+    try:
+        main(sys.argv[1:])
+    except (ValueError, TypeError, KeyError, OSError, ImportError) as error:
+        print("Evidence report: " + str(error), file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    run()

scientific_method_engine-0.1.0/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java

@@ -0,0 +1,22 @@
+// Clears incorrect no-return markings at explicitly supplied function addresses.
+// @category Restoration
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Function;
+
+public class ClearNoReturnFunctions extends GhidraScript {
+    @Override
+    protected void run() throws Exception {
+        for (String argument : getScriptArgs()) {
+            Address address = toAddr(argument);
+            Function function = getFunctionContaining(address);
+            if (function == null) {
+                printerr("No function contains " + address);
+                continue;
+            }
+            function.setNoReturn(false);
+            println("Cleared no-return on " + function.getName() + " at " + function.getEntryPoint());
+        }
+    }
+}

scientific_method_engine-0.1.0/src/scientific_method_engine/ghidra/CreateFunctions.java

@@ -0,0 +1,27 @@
+// Creates functions at explicitly supplied indirect-call targets.
+// @category Restoration
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Function;
+
+public class CreateFunctions extends GhidraScript {
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length == 0) {
+            printerr("Pass one or more function entry addresses.");
+            return;
+        }
+        for (String argument : arguments) {
+            Address address = toAddr(argument);
+            Function function = getFunctionAt(address);
+            if (function == null) function = createFunction(address, null);
+            if (function == null) {
+                printerr("Could not create function at " + address);
+                continue;
+            }
+            println("FUNCTION " + function.getName() + " " + function.getEntryPoint());
+        }
+    }
+}

scientific_method_engine-0.1.0/src/scientific_method_engine/ghidra/ExportBoundedFlow.java

@@ -0,0 +1,59 @@
+// Exports instruction metadata for one entry. Output belongs in ignored analysis/original/.
+// @category Restoration
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Instruction;
+import ghidra.program.model.listing.Function;
+import java.nio.file.*;
+import java.nio.charset.StandardCharsets;
+import java.util.*;
+
+public class ExportBoundedFlow extends GhidraScript {
+    @Override protected void run() throws Exception {
+        String[] args = getScriptArgs();
+        if (args.length != 3) throw new IllegalArgumentException("Supply entry, instruction limit (1..10000), ignored analysis/original/output.json");
+        Address entry = toAddr(args[0]);
+        int limit = Integer.parseInt(args[1]);
+        if (limit < 1 || limit > 10000) throw new IllegalArgumentException("Limit must be 1..10000");
+        Path output = Path.of(args[2]).toAbsolutePath().normalize();
+        if (!output.toString().replace('\\', '/').contains("/analysis/original/")) throw new IllegalArgumentException("Flow reports stay under ignored analysis/original/");
+        Set<Address> visited = new HashSet<>();
+        Deque<Address> pending = new ArrayDeque<>();
+        List<String> rows = new ArrayList<>();
+        Set<Long> entries = new TreeSet<>();
+        entries.add(entry.getOffset()); pending.push(entry);
+        while (!pending.isEmpty()) {
+            if (monitor.isCancelled()) throw new InterruptedException("Cancelled");
+            Address at = pending.pop();
+            if (visited.contains(at)) continue;
+            if (visited.size() >= limit) break; // Missing edge targets remain explicit review gaps.
+            visited.add(at);
+            Function owner = currentProgram.getFunctionManager().getFunctionContaining(at);
+            Function exact = currentProgram.getFunctionManager().getFunctionAt(at);
+            if (!at.equals(entry) && exact != null) { entries.add(at.getOffset()); continue; }
+            Instruction ins = currentProgram.getListing().getInstructionAt(at);
+            if (ins == null) continue;
+            List<Long> next = new ArrayList<>(), calls = new ArrayList<>();
+            var type = ins.getFlowType();
+            Address fall = ins.getFallThrough();
+            if (fall != null) { next.add(fall.getOffset()); pending.push(fall); }
+            for (Address target : ins.getFlows()) {
+                if (type.isCall()) calls.add(target.getOffset());
+                else { next.add(target.getOffset()); pending.push(target); }
+            }
+            String kind = type.isComputed() ? "indirect" : type.isCall() ? "call" : type.isTerminal() ? "terminal" : type.isJump() ? "branch" : "ordinary";
+            // A terminal mnemonic alone is insufficient to identify interrupt/OS semantics.
+            String mnemonic = ins.getMnemonicString().toUpperCase(Locale.ROOT);
+            if (mnemonic.startsWith("RET")) kind = "return";
+            boolean hardware = mnemonic.matches("(?:IN|OUT)(?:S[BDW]?)?(?:\\.REP\\w*)?|INT(?:[13O])?|HLT");
+            rows.add("{\"start\":" + at.getOffset() + ",\"size\":" + ins.getLength()
+                + ",\"kind\":\"" + kind + "\",\"next\":" + next + ",\"calls\":" + calls
+                + ",\"externalEffects\":" + (hardware ? "[\"instruction requires hardware/OS review\"]" : "[]")
+                + ",\"owner\":" + (owner == null ? "null" : owner.getEntryPoint().getOffset()) + "}");
+        }
+        Files.createDirectories(output.getParent());
+        String text = "{\"entries\":" + entries + ",\"instructions\":[" + String.join(",", rows) + "]}";
+        Files.writeString(output, text, StandardCharsets.UTF_8, StandardOpenOption.CREATE_NEW);
+        println("Exported " + rows.size() + " instruction metadata records. Ghidra addresses are view-specific; retain the import mapping separately.");
+    }
+}

scientific_method_engine-0.1.0/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java

@@ -0,0 +1,135 @@
+// Exports normalized function and instruction fingerprints for cross-version mapping.
+// @category Restoration
+
+import java.io.BufferedWriter;
+import java.io.File;
+import java.io.FileWriter;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.ArrayList;
+import java.util.List;
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.lang.Register;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.listing.FunctionIterator;
+import ghidra.program.model.listing.Instruction;
+import ghidra.program.model.listing.InstructionIterator;
+import ghidra.program.model.scalar.Scalar;
+
+public class ExportFunctionFingerprints extends GhidraScript {
+    @Override
+    protected void run() throws Exception {
+        String[] args = getScriptArgs();
+        if (args.length != 1) {
+            throw new IllegalArgumentException("Expected output TSV path.");
+        }
+
+        File output = new File(args[0]);
+        File parent = output.getParentFile();
+        if (parent != null) {
+            parent.mkdirs();
+        }
+
+        try (BufferedWriter writer = new BufferedWriter(new FileWriter(output, StandardCharsets.UTF_8))) {
+            writer.write("kind\tfunction\taddress\tend\tsize\tinstructionCount\tfingerprint\tsignature\n");
+            FunctionIterator functions = currentProgram.getFunctionManager().getFunctions(true);
+            while (functions.hasNext() && !monitor.isCancelled()) {
+                Function function = functions.next();
+                List<Instruction> instructions = new ArrayList<>();
+                InstructionIterator iterator = currentProgram.getListing()
+                    .getInstructions(function.getBody(), true);
+                StringBuilder functionSignature = new StringBuilder();
+                while (iterator.hasNext()) {
+                    Instruction instruction = iterator.next();
+                    instructions.add(instruction);
+                    functionSignature.append(normalize(instruction)).append(';');
+                }
+
+                String entry = hex(function.getEntryPoint());
+                writer.write(String.join("\t",
+                    "F", entry, entry, hex(function.getBody().getMaxAddress()),
+                    Long.toString(function.getBody().getNumAddresses()),
+                    Integer.toString(instructions.size()), sha256(functionSignature.toString()),
+                    functionSignature.toString()));
+                writer.newLine();
+
+                for (Instruction instruction : instructions) {
+                    String signature = normalize(instruction);
+                    writer.write(String.join("\t",
+                        "I", entry, hex(instruction.getAddress()),
+                        hex(instruction.getMaxAddress()), Integer.toString(instruction.getLength()),
+                        "1", sha256(signature), signature));
+                    writer.newLine();
+                }
+            }
+
+            InstructionIterator allInstructions = currentProgram.getListing().getInstructions(true);
+            while (allInstructions.hasNext() && !monitor.isCancelled()) {
+                Instruction instruction = allInstructions.next();
+                Function function = currentProgram.getFunctionManager()
+                    .getFunctionContaining(instruction.getAddress());
+                String owner = function == null ? "" : hex(function.getEntryPoint());
+                String signature = normalize(instruction);
+                writer.write(String.join("\t",
+                    "A", owner, hex(instruction.getAddress()),
+                    hex(instruction.getMaxAddress()), Integer.toString(instruction.getLength()),
+                    "1", sha256(signature), signature));
+                writer.newLine();
+            }
+        }
+        println("Wrote " + output.getAbsolutePath());
+    }
+
+    // A scalar that names an address in the program is relocatable between versions, so it is
+    // fingerprinted as an address rather than by value.
+    private boolean isProgramAddress(long value) {
+        try {
+            return currentProgram.getMemory().contains(toAddr(value));
+        } catch (RuntimeException outOfRange) {
+            return false;
+        }
+    }
+
+    private String normalize(Instruction instruction) {
+        StringBuilder result = new StringBuilder(instruction.getMnemonicString().toLowerCase());
+        for (int operand = 0; operand < instruction.getNumOperands(); operand++) {
+            result.append('|');
+            Object[] objects = instruction.getOpObjects(operand);
+            for (Object object : objects) {
+                if (object instanceof Register register) {
+                    result.append('R').append(register.getName().toLowerCase());
+                } else if (object instanceof Address address) {
+                    result.append(address.isMemoryAddress() ? "A" : "X");
+                } else if (object instanceof Scalar scalar) {
+                    long value = scalar.getSignedValue();
+                    long unsigned = scalar.getUnsignedValue();
+                    if (instruction.getFlowType().isFlow() || isProgramAddress(unsigned)) {
+                        result.append('A');
+                    } else {
+                        result.append('S').append(value);
+                    }
+                } else {
+                    result.append('O').append(object.getClass().getSimpleName());
+                }
+                result.append(',');
+            }
+        }
+        return result.toString();
+    }
+
+    private static String hex(Address address) {
+        return String.format("%08x", address.getOffset());
+    }
+
+    private static String sha256(String value) throws Exception {
+        MessageDigest digest = MessageDigest.getInstance("SHA-256");
+        byte[] hash = digest.digest(value.getBytes(StandardCharsets.UTF_8));
+        StringBuilder text = new StringBuilder(hash.length * 2);
+        for (byte b : hash) {
+            text.append(String.format("%02x", b & 0xff));
+        }
+        return text.toString();
+    }
+}