reverseport 0.0.0-stage → 1.0.0

package/bin/reverseport.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// ReversePort — one command for everything.
+//
+//   reverseport setup                 connect your coding agents (MCP + skill), once
+//   reverseport scan ./MyGame         ReversePort's own commands: recon, builds, lookups, blueprints, porting
+//   reverseport analyze ./App         deep-analysis engine commands: decompile, xrefs, runtime evidence, …
+//   reverseport mcp                   one MCP server with every tool
+//
+// ReversePort's own commands need nothing but Node. The engine commands need the built engine (installed from npm
+// it is always built; in a git checkout run `npm ci && npm run build`).
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const VERSION = JSON.parse(readFileSync(path.join(REPO, 'package.json'), 'utf8')).version;
+const PORT_COMMANDS = new Set([
+  'scan', 'graph', 'symbols', 'scene', 'binary', 'bin', 'archive', 'pck', 'probe', 'extract', 'carve', 'diff',
+  'compare-builds', 'report', 'lookup', 'recon', 'web', 'blueprint', 'rebuild', 'map', 'convert', 'plan', 'unit',
+  'write', 'port-scene', 'copy-assets', 'status', 'verify', 'tools', 'serve', 'describe', 'feedback', 'connect',
+]);
+const ALWAYS_ENGINE = ['setup', 'doctor', 'update', 'uninstall', 'mcp', 'capabilities', 'providers', 'help'];
+
+/** Engine command names, read from the built engine or its source, so a typo is never mistaken for a missing build. */
+function engineCommands() {
+  for (const file of [path.join(REPO, 'src', 'cliCommandNames.ts'), path.join(REPO, 'dist', 'cliCommandNames.js')]) {
+    try { return new Set([...ALWAYS_ENGINE, ...[...readFileSync(file, 'utf8').matchAll(/:\s*"([a-z0-9-]+)"/g)].map(m => m[1])]); } catch {}
+  }
+  return null;
+}
+
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) { let prev = row[0]; row[0] = i; for (let j = 1; j <= b.length; j++) { const t = row[j]; row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1)); prev = t; } }
+  return row[b.length];
+}
+function suggestion(cmd, names) {
+  let best = null, d = 3;
+  for (const n of names) { const x = distance(cmd, n); if (x < d) { d = x; best = n; } }
+  return best;
+}
+
+const engineBuilt = () => existsSync(path.join(REPO, 'dist', 'cli-runtime', 'cli.js')) && existsSync(path.join(REPO, 'dist', 'mcp', 'main.js'));
+const ENGINE_MISSING = `The deep-analysis engine is not built in this copy of ReversePort.
+  Installed from npm?  npx -y reverseport@latest setup
+  Git checkout?        npm ci && npm run build      (Node ${'>='}22.19)
+ReversePort's own commands (scan, binary, archive, diff, lookup, blueprint, plan, …) work without it.
+`;
+
+function help() {
+  return `ReversePort ${VERSION} — reverse engineer anything. Port it anywhere.
+
+Start
+  reverseport setup                  connect Claude Code, Codex, Cursor, Gemini, Copilot, OpenCode and more (MCP + skill)
+  reverseport doctor                 check the installation, engines and agent registrations
+  reverseport mcp                    MCP server on stdio with every tool
+
+Understand anything (no build needed)
+  reverseport scan <folder>          engine + version, languages, entry points — projects and exported games
+  reverseport lookup "<name>"        no files: engine, stack, structure, remakes from public sources (--url, --github)
+  reverseport binary <file>          PE/.NET/ELF/Mach-O/wasm/class/dex at a glance
+  reverseport archive <file>         Godot .pck (also inside .exe), zip/apk/jar, tar.gz, asar — list or extract
+  reverseport diff <a> <b>           what changed between two builds, packs or binaries
+  reverseport report <folder>        ARCHITECTURE.md
+  reverseport port help              every ReversePort command and option
+
+Go deep (deep-analysis engine)
+  reverseport analyze <target>       open a binary/app and summarize it
+  reverseport decompile <target>     pseudocode for functions (Ghidra, Hopper or IDA)
+  reverseport xrefs | trace | search call graphs, references, strings
+  reverseport analyze-javascript-application <dir>   Electron / web apps
+  reverseport inspect-android-package <apk>          Android
+  reverseport engine --help          all engine commands
+
+Rebuild and port
+  reverseport blueprint --lookup-id <id>   clean-room rebuild spec + parity table + skeleton
+  reverseport plan <source> --to unity     port Godot ⇄ Unity, → Unreal, → three.js, → Godot C#, any language
+  reverseport verify <planId>              prove nothing was left behind
+
+Only analyse or port what you own or may legally use. https://github.com/laaielichter/reverseport
+`;
+}
+
+// Agents read stderr as JSON when they asked for JSON or are not a terminal; people get plain text.
+const wantsJson = () => process.argv.includes('--json') || !process.stderr.isTTY;
+function fail(code, message, action, exitCode) {
+  if (wantsJson()) process.stderr.write(`${JSON.stringify({ error: { code, category: code === 'UNKNOWN_COMMAND' ? 'invalid_input' : 'unavailable', retryable: false, message, remediation: { action } } })}\n`);
+  else process.stderr.write(`${message}\n${code === 'UNKNOWN_COMMAND' ? '' : `\n${ENGINE_MISSING}`}`);
+  process.exitCode = exitCode;
+}
+
+async function runEngine(args) {
+  if (!engineBuilt()) {
+    const known = engineCommands();
+    const cmd = args[0];
+    if (known && cmd && !cmd.startsWith('-') && !known.has(cmd)) {
+      const near = suggestion(cmd, [...PORT_COMMANDS, ...known]);
+      return fail('UNKNOWN_COMMAND', `Unknown command "${cmd}".${near ? ` Did you mean "${near}"?` : ''}`, 'Run `reverseport help` for the commands.', 2);
+    }
+    return fail('ENGINE_UNAVAILABLE', !cmd || cmd.startsWith('-') ? 'The deep-analysis engine commands need the built engine, which is not built in this copy.' : `"${cmd}" is a deep-analysis engine command and the engine is not built in this copy.`, 'Ask the user first, then `npx -y reverseport@latest setup`, or in this checkout `npm ci && npm run build`. ReversePort\'s own commands work without it.', 1);
+  }
+  // In-process, so agent registrations written by `setup` point at this command (process.argv[1]).
+  process.argv = [process.argv[0], process.argv[1], ...args];
+  await import(pathToFileURL(path.join(REPO, 'scripts', 'rea.mjs')).href);
+}
+
+async function runPort(args) {
+  const { main } = await import(pathToFileURL(path.join(REPO, 'port', 'cli.mjs')).href);
+  const code = await main(args);
+  if (code !== null) process.exitCode = code;
+}
+
+const argv = process.argv.slice(2);
+const [cmd, ...rest] = argv;
+
+if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') process.stdout.write(help());
+else if (cmd === '--version' || cmd === '-v' || cmd === 'version') process.stdout.write(`${VERSION}\n`);
+else if ((cmd === 'mcp' || cmd === '--mcp') && rest.length === 0) await import(pathToFileURL(path.join(REPO, 'port', 'mcp.mjs')).href);
+else if (cmd === 'port') await runPort(rest.length ? rest : ['help']);
+else if (cmd === 'engine') await runEngine(rest);
+else if (PORT_COMMANDS.has(cmd) || /^(re|port)_[a-z_]+$/.test(cmd)) await runPort(argv);
+else if (cmd === 'doctor' && !engineBuilt()) {
+  const { doctor } = await import(pathToFileURL(path.join(REPO, 'port', 'cli.mjs')).href);
+  const report = await doctor();
+  const ignored = argv.slice(1).filter(a => a !== '--json');
+  const out = { ...report, ok: false, reverseport: { ok: report.ok }, engine: { built: false, ok: false, remediation: ['npx -y reverseport@latest setup', 'npm ci && npm run build   (in this checkout)'] }, registration: 'Checking agent registrations needs the engine. Meanwhile `reverseport connect <client>` prints the configuration for any agent.', ...(ignored.length ? { ignoredOptions: ignored } : {}) };
+  process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+  if (!wantsJson()) process.stderr.write(`\n${ENGINE_MISSING}`);
+  process.exitCode = 1;
+} else await runEngine(argv);

package/bridge/android/ReaJadxBridge.java

@@ -0,0 +1,270 @@
+import com.atxx.jhmcp.*;
+import com.google.gson.*;
+import io.modelcontextprotocol.kotlin.sdk.server.*;
+import io.modelcontextprotocol.kotlin.sdk.types.*;
+import jadx.api.*;
+import jadx.core.dex.nodes.*;
+import java.io.PrintStream;
+import java.util.*;
+import java.util.concurrent.CountDownLatch;
+import java.util.stream.Collectors;
+import kotlin.Unit;
+import kotlin.coroutines.EmptyCoroutineContext;
+import kotlinx.coroutines.BuildersKt;
+import kotlinx.io.CoreKt;
+import kotlinx.io.JvmCoreKt;
+import kotlinx.serialization.json.JsonObject;
+
+/** REA-owned metadata boundary for the unmodified jadx-headless-mcp 0.7.1 JAR. */
+class ReaJadxBridge {
+  private static final Gson JSON = new Gson();
+  private final SessionHolder holder;
+  private JadxSession indexedSession;
+  private Map<String, List<ClassSnapshot>> classes = Map.of();
+
+  private record MethodSnapshot(String name, String shortId, Map<String, Object> summary) {}
+  private record ClassSnapshot(JavaClass node, List<MethodSnapshot> methods, Map<String, Object> summary) {}
+
+  private static final class InputFailure extends IllegalArgumentException {
+    final String field;
+    InputFailure(String field, String message) { super(message); this.field = field; }
+  }
+
+  private ReaJadxBridge(SessionHolder holder) { this.holder = holder; }
+
+  private static CallToolResult text(String value, boolean failed) {
+    return new CallToolResult(List.of(new TextContent(value, null, null)), failed, null, null);
+  }
+
+  private static CallToolResult json(Object value) { return text(JSON.toJson(value), false); }
+
+  private static String string(JsonObject args, String name) {
+    JsonElement value = JsonParser.parseString(args.toString()).getAsJsonObject().get(name);
+    if (value == null || !value.isJsonPrimitive() || !value.getAsJsonPrimitive().isString())
+      throw new IllegalArgumentException(name + " must be a string");
+    return value.getAsString();
+  }
+
+  private static int integer(JsonObject args, String name, int fallback) {
+    JsonElement value = JsonParser.parseString(args.toString()).getAsJsonObject().get(name);
+    if (value == null) return fallback;
+    if (!value.isJsonPrimitive() || !value.getAsJsonPrimitive().isNumber())
+      throw new IllegalArgumentException(name + " must be a nonnegative integer");
+    try {
+      int result = value.getAsBigDecimal().intValueExact();
+      if (result < 0) throw new ArithmeticException();
+      return result;
+    } catch (ArithmeticException error) {
+      throw new IllegalArgumentException(name + " must be a nonnegative integer", error);
+    }
+  }
+
+  private JadxSession session() {
+    JadxSession current = holder.current();
+    if (current == null) throw new IllegalArgumentException("No APK loaded");
+    return current;
+  }
+
+  private ClassSnapshot selected(JsonObject args) {
+    JadxSession current = session();
+    if (indexedSession != current) {
+      Map<String, List<ClassSnapshot>> index = new LinkedHashMap<>();
+      if (!current.getClasses().isEmpty()) {
+        JadxDecompiler decompiler = current.getClasses().get(0).getClassNode().root().getDecompiler();
+        // JavaClass.getMethods/getFields/getInnerClasses all load code. Raw nodes do not.
+        // Snapshot every identity before code generation can rewrite aliases or members.
+        for (JavaClass cls : decompiler.getClassesWithInners()) {
+          ClassNode node = cls.getClassNode();
+          List<MethodNode> ordered = new ArrayList<>(node.getMethods());
+          ordered.sort(Comparator.comparing(MethodNode::getAlias));
+          List<MethodSnapshot> methods = ordered.stream().map(method -> {
+            String name = method.getAlias();
+            String signature = name + "(" + method.getArgTypes().stream()
+                .map(Object::toString).collect(Collectors.joining(", "))
+                + "): " + method.getReturnType().toString();
+            return new MethodSnapshot(name, method.getMethodInfo().getShortId(), Map.of(
+                "name", name, "signature", signature,
+                "is_constructor", method.isConstructor(), "def_pos", 0));
+          }).toList();
+          List<Map<String, Object>> fields = node.getFields().stream()
+              .sorted(Comparator.comparing(FieldNode::getAlias))
+              .map(field -> Map.<String, Object>of("name", field.getAlias(),
+                  "type", field.getType().toString(), "def_pos", 0)).toList();
+          List<String> inner = node.getInnerClasses().stream().map(ClassNode::getFullName).toList();
+          Map<String, Object> summary = Map.of(
+              "full_name", cls.getFullName(), "name", cls.getName(),
+              "method_count", methods.size(), "field_count", fields.size(),
+              "inner_class_count", inner.size(), "inner_classes", inner,
+              "methods", methods.stream().map(MethodSnapshot::summary).toList(), "fields", fields);
+          index.computeIfAbsent(cls.getFullName(), ignored -> new ArrayList<>())
+              .add(new ClassSnapshot(cls, methods, summary));
+        }
+      }
+      classes = Collections.unmodifiableMap(index);
+      indexedSession = current;
+    }
+    String name = string(args, "class_name");
+    List<ClassSnapshot> candidates = classes.get(name);
+    if (candidates == null) throw new InputFailure("class_name", "Exact class not found: " + name
+        + "; use search_android_classes to discover fully qualified names.");
+    if (candidates.size() != 1) throw new InputFailure("class_name", "Ambiguous metadata class identity: " + name
+        + "; raw identities: " + candidates.stream().map(candidate -> candidate.node().getRawName()).toList());
+    return candidates.get(0);
+  }
+
+  private List<MethodSnapshot> methods(ClassSnapshot cls, JsonObject args) {
+    String name = string(args, "method_name");
+    List<MethodSnapshot> result = cls.methods().stream().filter(method -> method.name().equals(name)).toList();
+    if (result.isEmpty()) throw new InputFailure("method_name", "Method not found: " + name
+        + "; use inspect_android_class to discover available methods.");
+    return result;
+  }
+
+  private JavaMethod method(ClassSnapshot cls, MethodSnapshot selected) {
+    JavaMethod result = cls.node().searchMethodByShortId(selected.shortId());
+    if (result == null) throw new IllegalArgumentException("Method identity no longer available: " + selected.shortId());
+    return result;
+  }
+
+  private JadxSession.SmartCode methodBody(JadxSession current, ClassSnapshot cls,
+      MethodSnapshot selected, JavaMethod method) {
+    if (!selected.shortId().equals("<clinit>()V"))
+      return current.getMethodBodySmart(method, current.getMaxSourceBytes(), true);
+    // Java code generation can fold all or part of <clinit> into field declarations.
+    // Its method text cannot establish coverage, even when a static block remains.
+    JadxSession.MethodSmali smali = current.getMethodSmali(cls.node(), method.getName());
+    if (!smali.getFound() || smali.getBlocks().size() != 1)
+      throw new IllegalArgumentException("Static initializer disassembly requires one exact method: " + selected.shortId());
+    return new JadxSession.SmartCode(
+        TextUtilKt.truncateToBytes(smali.getBlocks().get(0), current.getMaxSourceBytes()),
+        "smali", true, List.of("static_initializer_disassembly"));
+  }
+
+  private CallToolResult handle(String name, JsonObject args) {
+    if (name.equals("rea_jvm_status")) return json(Map.of(
+        "engine_reported_version", BuildInfo.VERSION,
+        "max_heap_bytes", Runtime.getRuntime().maxMemory(),
+        "available_processors", Runtime.getRuntime().availableProcessors(),
+        "java_version", System.getProperty("java.version"),
+        "metadata_scope", "parsed_members"));
+    JadxSession current = session();
+    if (name.equals("list_classes")) {
+      List<String> names = current.getClassFqns();
+      int offset = integer(args, "offset", 0);
+      int limit = integer(args, "limit", 200);
+      int start = Math.min(offset, names.size());
+      int end = (int) Math.min((long) start + limit, names.size());
+      return json(Map.of("total", names.size(), "offset", offset, "limit", limit,
+          "items", names.subList(start, end)));
+    }
+    ClassSnapshot cls = selected(args);
+    if (name.equals("get_class_summary")) return json(cls.summary());
+    if (name.equals("get_method_body")) {
+      List<MethodSnapshot> overloads = methods(cls, args);
+      int index = integer(args, "overload_index", 0);
+      if (index >= overloads.size()) throw new InputFailure("overload_index", "overload_index out of range: " + index);
+      JavaMethod method = method(cls, overloads.get(index));
+      JadxSession.SmartCode code = methodBody(current, cls, overloads.get(index), method);
+      return json(Map.of("class_name", cls.summary().get("full_name"),
+          "method_name", overloads.get(index).name(), "full_name", method.getFullName(),
+          "overload_index", index, "overload_count", overloads.size(),
+          "mode", code.getKind(), "fell_back", code.getFellBack(),
+          "markers", code.getMarkers(), "body", code.getText()));
+    }
+    List<JavaNode> uses;
+    String target = string(args, "class_name");
+    if (name.equals("get_xrefs_to_class")) uses = cls.node().getUseIn();
+    else {
+      List<MethodSnapshot> overloads = methods(cls, args);
+      if (overloads.size() != 1) throw new InputFailure("method_name", "Method references require a unique overload");
+      target += "." + overloads.get(0).name();
+      uses = method(cls, overloads.get(0)).getUseIn();
+    }
+    // REA consumes all references without materializing source line information.
+    List<Map<String, Object>> items = uses.stream().map(node -> current.describeUsage(node, false)).toList();
+    return json(Map.of("target", target, "total", uses.size(), "count", items.size(),
+        "resolve_line", false, "items", items));
+  }
+
+  public static void main(String[] args) throws Exception {
+    PrintStream protocolOut = System.out;
+    System.setOut(System.err);
+    SessionHolder holder = new SessionHolder(new SessionConfig(
+        1048576, 0, 90000L, 1, List.of(), List.of(), 64, ResourceMode.FULL));
+    ServerCapabilities capabilities = new ServerCapabilities(
+        new ServerCapabilities.Tools(null), null, null, null, null, null, null, Map.of());
+    Server server = new Server(new Implementation("rea-jadx-bridge", "1", null, null, null),
+        new ServerOptions(capabilities), "", ignored -> Unit.INSTANCE);
+    SessionToolsKt.registerSessionTools(server, holder);
+    ManifestToolsKt.registerManifestTools(server, holder);
+    ClassToolsKt.registerClassTools(server, holder);
+    MethodToolsKt.registerMethodTools(server, holder);
+    XrefToolsKt.registerXrefTools(server, holder);
+    ReaJadxBridge bridge = new ReaJadxBridge(holder);
+    Set<String> consumed = Set.of("load_apk", "get_app_info", "get_android_manifest",
+        "list_classes", "get_class_summary", "get_method_body",
+        "get_xrefs_to_class", "get_xrefs_to_method");
+    for (String name : new ArrayList<>(server.getTools().keySet()))
+      if (!consumed.contains(name)) server.removeTool(name);
+    Tool diagnostics = new Tool("rea_jvm_status",
+        new ToolSchema(null, new JsonObject(Map.of()), List.of(), null),
+        "Observed worker JVM and metadata scope", null, null, null, null, null, null);
+    server.addTool(diagnostics, (connection, request, continuation) -> bridge.handle("rea_jvm_status", request.getArguments()));
+    for (String name : List.of("list_classes", "get_class_summary",
+        "get_method_body", "get_xrefs_to_class", "get_xrefs_to_method")) {
+      Tool tool = server.getTools().get(name).getTool();
+      server.removeTool(name);
+      List<String> fields = switch (name) {
+        case "list_classes" -> List.of("offset", "limit");
+        case "get_method_body" -> List.of("class_name", "method_name", "overload_index");
+        case "get_xrefs_to_method" -> List.of("class_name", "method_name");
+        default -> List.of("class_name");
+      };
+      Map<String, kotlinx.serialization.json.JsonElement> properties = new LinkedHashMap<>();
+      for (String field : fields) properties.put(field, tool.getInputSchema().getProperties().get(field));
+      String description = switch (name) {
+        case "list_classes" -> "Indexed pages of all top-level class names, with offset and limit.";
+        case "get_class_summary" -> "Parsed member metadata for one exact class name; no source generation.";
+        case "get_method_body" -> "Source for an exact class and stable same-name overload index; static initializers use smali to preserve folded field initialization.";
+        default -> "Complete static references to an exact class or unique method; source lines are unresolved.";
+      };
+      Tool narrowed = new Tool(name, new ToolSchema(null, new JsonObject(properties),
+          tool.getInputSchema().getRequired(), null), description, null, null, null, null, null, null);
+      server.addTool(narrowed, (connection, request, continuation) -> {
+        try { return bridge.handle(name, request.getArguments()); }
+        catch (InputFailure error) { return text(JSON.toJson(Map.of(
+            "kind", "invalid-input", "field", error.field, "message", error.getMessage())), true); }
+        catch (IllegalArgumentException error) { return text(error.getMessage(), true); }
+      });
+    }
+    CountDownLatch done = new CountDownLatch(1);
+    server.onClose(() -> { done.countDown(); return Unit.INSTANCE; });
+    StdioServerTransport transport = new StdioServerTransport(
+        CoreKt.buffered(JvmCoreKt.asSource(System.in)),
+        CoreKt.buffered(JvmCoreKt.asSink(protocolOut)));
+    transport.onClose(() -> { done.countDown(); return Unit.INSTANCE; });
+    ServerSession connection = null;
+    try {
+      connection = BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
+          (scope, continuation) -> server.createSession(transport, continuation));
+      done.await();
+    } finally {
+      try {
+        if (connection != null) {
+          ServerSession connected = connection;
+          // Unsubscribe the connection before the SDK joins its notification service.
+          BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
+              (scope, continuation) -> connected.close(continuation));
+        }
+      } finally {
+        try {
+          BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
+              (scope, continuation) -> server.close(continuation));
+        } finally {
+          BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
+              (scope, continuation) -> holder.unload(continuation));
+        }
+      }
+    }
+  }
+}

package/bridge/ghidra/ReaGhidraAnalysisOptions.java

@@ -0,0 +1,38 @@
+import java.util.Map;
+
+import ghidra.app.plugin.core.analysis.AutoAnalysisManager;
+import ghidra.app.util.headless.HeadlessScript;
+
+/** Disable the named auto-analyzers before default auto-analysis. */
+public final class ReaGhidraAnalysisOptions extends HeadlessScript {
+    @Override
+    public void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length != 1 || arguments[0].isBlank()) {
+            throw new IllegalArgumentException(
+                "ReaGhidraAnalysisOptions requires one comma-separated analyzer-name argument");
+        }
+        String[] names = arguments[0].split(",");
+        AutoAnalysisManager analysis = AutoAnalysisManager.getAnalysisManager(currentProgram);
+        Map<String, String> options = getCurrentAnalysisOptionsAndValues(currentProgram);
+        for (String requestedName : names) {
+            monitor.checkCancelled();
+            String name = requestedName.trim();
+            if (analysis.getAnalyzer(name) == null || !options.containsKey(name)) {
+                throw new IllegalArgumentException("Unknown Ghidra analyzer for this program: " + name);
+            }
+        }
+        for (String requestedName : names) {
+            monitor.checkCancelled();
+            setAnalysisOption(currentProgram, requestedName.trim(), "false");
+        }
+        options = getCurrentAnalysisOptionsAndValues(currentProgram);
+        for (String requestedName : names) {
+            monitor.checkCancelled();
+            String name = requestedName.trim();
+            if (!"false".equals(options.get(name))) {
+                throw new IllegalStateException("Ghidra analyzer remained enabled: " + name);
+            }
+        }
+    }
+}

package/bridge/ghidra/ReaGhidraApplySeeds.java

@@ -0,0 +1,151 @@
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.address.AddressSpace;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.listing.Program;
+import ghidra.program.model.mem.MemoryBlock;
+import ghidra.program.model.symbol.SourceType;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.LinkOption;
+import java.nio.file.Path;
+import java.security.MessageDigest;
+import java.util.ArrayList;
+import java.util.HexFormat;
+import java.util.List;
+
+/**
+ * Apply caller-declared analysis seeds before default auto-analysis.
+ *
+ * The single argument is REA's canonical seed snapshot: one
+ * {@code 0x<hex>\t(function|code|label)[\tname]} line per seed. Code seeds are
+ * applied after functions (highest address first), then labels. The outcome is stored as a
+ * program property that the bridge reports during its handshake.
+ */
+public final class ReaGhidraApplySeeds extends GhidraScript {
+    static final String REPORT_OPTION = "REA analysis seeds";
+
+    private record Seed(Address address, String kind, String name) {}
+
+    @Override
+    public void run() throws Exception {
+        String[] args = getScriptArgs();
+        if (args.length != 1) {
+            throw new IllegalArgumentException("REA seed script requires exactly one seed file");
+        }
+        Path path = Path.of(args[0]);
+        if (!Files.isRegularFile(path, LinkOption.NOFOLLOW_LINKS)) {
+            throw new IllegalArgumentException("REA seed file is not a regular file");
+        }
+        byte[] bytes = Files.readAllBytes(path);
+        String sha256 = HexFormat.of().formatHex(
+            MessageDigest.getInstance("SHA-256").digest(bytes)
+        );
+        AddressSpace space = currentProgram.getAddressFactory().getDefaultAddressSpace();
+        List<Seed> seeds = new ArrayList<>();
+        for (String line : new String(bytes, StandardCharsets.UTF_8).split("\n")) {
+            if (line.isEmpty()) continue;
+            String[] fields = line.split("\t", -1);
+            if (fields.length < 2 || fields.length > 3 || !fields[0].startsWith("0x")) {
+                throw new IllegalArgumentException("REA seed snapshot is malformed");
+            }
+            Address address;
+            try {
+                address = space.getAddress(Long.parseUnsignedLong(fields[0].substring(2), 16));
+            } catch (ghidra.program.model.address.AddressOutOfBoundsException e) {
+                address = null;
+            }
+            seeds.add(new Seed(address, fields[1], fields.length == 3 ? fields[2] : null));
+        }
+
+        // Highest address first: a function body computed before analysis stops at
+        // an existing function entry, so later creations cannot swallow earlier ones.
+        seeds.sort((left, right) -> {
+            if (left.address() == null) return right.address() == null ? 0 : 1;
+            if (right.address() == null) return -1;
+            return right.address().compareTo(left.address());
+        });
+        int unmapped = 0;
+        int logged = 0;
+        int codeDecoded = 0, codeFailed = 0;
+        int functionCreated = 0, functionExisting = 0, functionFailed = 0;
+        int labelApplied = 0, labelFailed = 0;
+        for (String pass : new String[] { "function", "code", "label" }) {
+            for (Seed seed : seeds) {
+                if (!seed.kind().equals(pass)) continue;
+                monitor.checkCancelled();
+                MemoryBlock block = seed.address() == null
+                    ? null
+                    : currentProgram.getMemory().getBlock(seed.address());
+                if (block == null || (!pass.equals("label") && !block.isInitialized())) {
+                    unmapped++;
+                    continue;
+                }
+                switch (pass) {
+                    case "code" -> {
+                        if (decoded(seed.address())) codeDecoded++;
+                        else {
+                            codeFailed++;
+                            if (logged++ < 20) println("REA seed failed: code " + seed.address() + " " + why(seed.address()));
+                        }
+                    }
+                    case "function" -> {
+                        Function existing = getFunctionAt(seed.address());
+                        if (existing != null) {
+                            functionExisting++;
+                            if (seed.name() != null) {
+                                existing.setName(seed.name(), SourceType.USER_DEFINED);
+                            }
+                        } else if (decoded(seed.address()) &&
+                            createFunction(seed.address(), seed.name()) != null) {
+                            functionCreated++;
+                        } else {
+                            functionFailed++;
+                            if (logged++ < 20) println("REA seed failed: function " + seed.address() + " " + why(seed.address()));
+                        }
+                    }
+                    default -> {
+                        try {
+                            createLabel(seed.address(), seed.name(), true, SourceType.USER_DEFINED);
+                            labelApplied++;
+                        } catch (Exception e) {
+                            labelFailed++;
+                        }
+                    }
+                }
+            }
+        }
+        String report = "{\"format\":\"rea-ghidra-seeds-v1\",\"sha256\":\"" + sha256 + "\"" +
+            ",\"entries\":" + seeds.size() +
+            ",\"function_created\":" + functionCreated +
+            ",\"function_existing\":" + functionExisting +
+            ",\"function_failed\":" + functionFailed +
+            ",\"code_decoded\":" + codeDecoded +
+            ",\"code_failed\":" + codeFailed +
+            ",\"label_applied\":" + labelApplied +
+            ",\"label_failed\":" + labelFailed +
+            ",\"unmapped\":" + unmapped + "}";
+        currentProgram.getOptions(Program.PROGRAM_INFO).setString(REPORT_OPTION, report);
+        println("REA seeds applied: " + report);
+    }
+
+    private String why(Address address) {
+        if (getDataAt(address) != null) return "defined data " + getDataAt(address).getDataType().getName();
+        var containing = getInstructionContaining(address);
+        if (containing != null && !containing.getAddress().equals(address))
+            return "inside instruction at " + containing.getAddress();
+        Function owner = getFunctionContaining(address);
+        if (owner != null) return "inside function " + owner.getEntryPoint();
+        return getInstructionAt(address) == null ? "undecodable" : "function creation refused";
+    }
+
+    /** Decode one instruction flow at an address, keeping an existing decode. */
+    private boolean decoded(Address address) {
+        if (getInstructionAt(address) != null) return true;
+        if (getDataAt(address) != null || getInstructionContaining(address) != null) {
+            return false;
+        }
+        disassemble(address);
+        return getInstructionAt(address) != null;
+    }
+}