rea-agents 6.2.0 → 6.4.0

package/dist/ghidra/GhidraAnalysisSeeds.js

@@ -0,0 +1,211 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, realpath, writeFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { z } from "zod";
+import { ConfigurationError } from "../domain/configurationErrors.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { err, ok } from "../domain/result.js";
+/** Seed file format admitted by this adapter. */
+export const GHIDRA_SEED_FORMAT = "rea-ghidra-seeds-v1";
+export const GHIDRA_SEED_SCRIPT = "ReaGhidraApplySeeds.java";
+export const MAX_GHIDRA_SEED_BYTES = 32 * 1024 * 1024;
+export const MAX_GHIDRA_SEED_ENTRIES = 1_000_000;
+const MAX_SEED_NAME_LENGTH = 2000;
+const digest = z.string().regex(/^[a-f0-9]{64}$/u);
+const count = z.number().int().nonnegative();
+/** Caller-declared seeds committed into the analysis profile before import. */
+export const ghidraSeedCommitmentSchema = z.strictObject({
+    format: z.literal(GHIDRA_SEED_FORMAT),
+    path: z.string().refine(isAbsolute, "Seed path must be absolute"),
+    configured_path: z.string().refine(isAbsolute, "Seed path must be absolute"),
+    sha256: digest,
+    entries: z.strictObject({ function: count, code: count, label: count }),
+});
+/** What the pre-analysis script applied, as reported by the bridge handshake. */
+export const ghidraSeedReportSchema = z.strictObject({
+    format: z.literal(GHIDRA_SEED_FORMAT),
+    sha256: digest,
+    entries: count,
+    function_created: count,
+    function_existing: count,
+    function_failed: count,
+    code_decoded: count,
+    code_failed: count,
+    label_applied: count,
+    label_failed: count,
+    unmapped: count,
+});
+const seedLineError = (line, constraint) => new ConfigurationError("Invalid REA environment configuration", {
+    settings: [
+        {
+            setting: "REA_GHIDRA_SEED_FILE",
+            constraint: `line ${line}: ${constraint}`,
+        },
+    ],
+});
+/**
+ * Parse `address<TAB>kind[<TAB>name]` lines. Blank lines and `#` comments are
+ * ignored. Addresses are hexadecimal offsets in the default address space.
+ */
+export const parseGhidraSeeds = (text) => {
+    const entries = [];
+    const seen = new Set();
+    const lines = text.split("\n");
+    for (const [index, raw] of lines.entries()) {
+        const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+        if (line.trim() === "" || line.startsWith("#"))
+            continue;
+        const number = index + 1;
+        const fields = line.split("\t");
+        if (fields.length < 2 || fields.length > 3)
+            return err(seedLineError(number, "expected address<TAB>kind[<TAB>name]"));
+        const [address, kind, name] = fields;
+        if (address === undefined || !/^0x[0-9a-fA-F]{1,16}$/u.test(address))
+            return err(seedLineError(number, "address must be 0x-prefixed hex"));
+        if (kind !== "function" && kind !== "code" && kind !== "label")
+            return err(seedLineError(number, "kind must be function, code or label"));
+        if (name !== undefined &&
+            (name.length === 0 ||
+                name.length > MAX_SEED_NAME_LENGTH ||
+                /[\s\0]/u.test(name)))
+            return err(seedLineError(number, `name must be 1..${MAX_SEED_NAME_LENGTH} characters without whitespace`));
+        if (kind === "label" && name === undefined)
+            return err(seedLineError(number, "a label seed requires a name"));
+        if (kind === "code" && name !== undefined)
+            return err(seedLineError(number, "a code seed takes no name; add a label seed"));
+        const value = BigInt(address);
+        const key = `${value.toString(16)}:${kind}`;
+        if (seen.has(key))
+            return err(seedLineError(number, `duplicate ${kind} seed at ${address}`));
+        seen.add(key);
+        entries.push({
+            address: value,
+            kind,
+            ...(name === undefined ? {} : { name }),
+        });
+        if (entries.length > MAX_GHIDRA_SEED_ENTRIES)
+            return err(seedLineError(number, `more than ${MAX_GHIDRA_SEED_ENTRIES} seed entries`));
+    }
+    return ok(entries);
+};
+/** Canonical script input: lowercase addresses, fixed field order, LF endings. */
+const normalizedSeeds = (entries) => entries
+    .map((entry) => `0x${entry.address.toString(16)}\t${entry.kind}${entry.name === undefined ? "" : `\t${entry.name}`}\n`)
+    .join("");
+/** Read a bounded regular file through one handle without following links. */
+const readSeedFile = async (path) => {
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > MAX_GHIDRA_SEED_BYTES)
+            throw new Error(`Ghidra seed file must be a regular file of at most ${MAX_GHIDRA_SEED_BYTES} bytes: ${path}`);
+        const bytes = Buffer.alloc(stat.size);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const read = await file.read(bytes, offset, bytes.length - offset, offset);
+            if (read.bytesRead === 0)
+                throw new Error(`Incomplete Ghidra seed file read: ${path}`);
+            offset += read.bytesRead;
+        }
+        return bytes;
+    }
+    finally {
+        await file.close();
+    }
+};
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const decodeSeeds = (bytes) => {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return parseGhidraSeeds(text);
+};
+/** Resolve the configured seed file into an immutable profile commitment. */
+export const resolveGhidraAnalysisSeeds = async (configured) => {
+    if (configured === undefined)
+        return ok(undefined);
+    let bytes;
+    let path;
+    try {
+        path = await realpath(configured);
+        bytes = await readSeedFile(path);
+    }
+    catch (cause) {
+        return err(new ProviderAdapterError("ghidra", "resolve_analysis_profile", {
+            cause,
+            diagnostics: {
+                setting: "REA_GHIDRA_SEED_FILE",
+                path: configured,
+                reason: cause instanceof Error ? cause.message : String(cause),
+            },
+        }));
+    }
+    let parsed;
+    try {
+        parsed = decodeSeeds(bytes);
+    }
+    catch {
+        return err(seedLineError(0, "file is not valid UTF-8"));
+    }
+    if (!parsed.ok)
+        return parsed;
+    const normalized = normalizedSeeds(parsed.value);
+    const tally = { function: 0, code: 0, label: 0 };
+    for (const entry of parsed.value)
+        tally[entry.kind] += 1;
+    return ok({
+        format: GHIDRA_SEED_FORMAT,
+        path,
+        configured_path: configured,
+        sha256: sha256(normalized),
+        entries: tally,
+    });
+};
+/** Re-read the committed seeds and write the canonical copy the script applies. */
+export const snapshotGhidraAnalysisSeeds = async (commitment, runtimeRoot) => {
+    ghidraSeedCommitmentSchema.parse(commitment);
+    if ((await realpath(commitment.configured_path)) !== commitment.path)
+        throw new Error("Ghidra seed file resolved path differs from explicit configuration");
+    const parsed = decodeSeeds(await readSeedFile(commitment.path));
+    if (!parsed.ok)
+        throw parsed.error;
+    const normalized = normalizedSeeds(parsed.value);
+    if (sha256(normalized) !== commitment.sha256)
+        throw new Error(`Ghidra seed file changed after the analysis profile was committed: ${commitment.path}`);
+    const directory = join(runtimeRoot, "seeds");
+    await mkdir(directory, { mode: 0o700 });
+    const path = join(directory, "seeds.tsv");
+    await writeFile(path, normalized, { flag: "wx", mode: 0o600 });
+    return path;
+};
+const totalEntries = (commitment) => commitment.entries.function +
+    commitment.entries.code +
+    commitment.entries.label;
+/** Fail closed when the session did not apply exactly the committed seeds. */
+export const ghidraSeedFailure = (commitment, report, operation) => {
+    if (commitment === undefined && report === undefined)
+        return undefined;
+    const reason = commitment === undefined
+        ? "The Ghidra session reported analysis seeds that the profile did not commit."
+        : report === undefined
+            ? "The Ghidra session did not report the committed analysis seeds."
+            : report.sha256 !== commitment.sha256 ||
+                report.entries !== totalEntries(commitment)
+                ? "The Ghidra session applied analysis seeds that differ from the committed profile."
+                : undefined;
+    return reason === undefined
+        ? undefined
+        : new ProviderAdapterError("ghidra", operation, {
+            diagnostics: { reason },
+        });
+};
+/** Session limitations that keep seeded facts distinct from Ghidra discoveries. */
+export const ghidraSeedLimitations = (commitment, report) => commitment === undefined
+    ? []
+    : [
+        `Ghidra analysis was seeded before auto-analysis from ${commitment.path} (sha256 ${commitment.sha256}: ${commitment.entries.function} function, ${commitment.entries.code} code, ${commitment.entries.label} label entries). Seeded functions, code and names are caller assertions, not Ghidra discoveries.`,
+        ...(report === undefined
+            ? []
+            : [
+                `Seed outcome: ${report.function_created} functions created, ${report.function_existing} already present, ${report.function_failed} failed; ${report.code_decoded} code seeds decoded, ${report.code_failed} failed; ${report.label_applied} labels applied, ${report.label_failed} failed; ${report.unmapped} seeds outside initialized memory.`,
+            ]),
+    ];

package/dist/ghidra/GhidraClient.js

@@ -9,7 +9,8 @@ import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
 import { ProviderRunLineage } from "../process/ProviderRunLineage.js";
 import { ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
 import { DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS } from "../config/ghidraStartupTimeout.js";
-import { createGhidraDiagnostics } from "./GhidraDiagnostics.js";
+import { createGhidraDiagnostics, GHIDRA_PROCESS_DIAGNOSTIC_BYTES, } from "./GhidraDiagnostics.js";
+import { GhidraLaunchError } from "./GhidraLauncher.js";
 import { GhidraResponseBuffer } from "./GhidraResponseBuffer.js";
 import { GhidraResponseRouter } from "./GhidraResponseRouter.js";
 import { GhidraRequestQueue } from "./GhidraRequestQueue.js";
@@ -17,6 +18,9 @@ import { bindGhidraSessionFailure, GhidraSessionError, } from "./GhidraSessionEr
 import { isGhidraShutdownAcknowledgement, parseGhidraSessionInfo, } from "./GhidraSessionValues.js";
 import { createGhidraTargetSnapshot } from "./GhidraTargetSnapshot.js";
 import { readFile } from "node:fs/promises";
+import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
+import { openRegularFile, RegularFileChangedError, sameRegularFileState, } from "../filesystem/RegularFile.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
 import { connectGhidraSocket } from "./GhidraSocketConnection.js";
 import { createGhidraEndpoint, } from "./GhidraTransport.js";
 import { GhidraWire } from "./GhidraClientWire.js";
@@ -37,6 +41,7 @@ export class GhidraClient {
     #socketRoot;
     #endpointPath;
     #snapshotPath;
+    #snapshotOwners = new Set();
     #targetAdmission;
     #token;
     // Retain authentication identities for diagnostics from late request settlement.
@@ -146,14 +151,76 @@ export class GhidraClient {
         return this.#requestQueue.run(operation, parameters, options.signal === undefined ? {} : { signal: options.signal });
     }
     /** Read the private immutable source for independent import verification. */
-    async readTargetSnapshot() {
+    async readTargetSnapshot(maximumBytes, signal) {
         if (this.#snapshotPath === undefined)
             return err(this.#failure("protocol", "Ghidra target snapshot is unavailable before startup or after close"));
         try {
-            return ok(await readFile(this.#snapshotPath));
+            if (maximumBytes !== undefined) {
+                signal?.throwIfAborted();
+                if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 0)
+                    throw new RangeError("Snapshot byte limit must be a safe integer");
+                const handle = await openRegularFile(this.#snapshotPath, {
+                    symlinks: "reject",
+                });
+                const owner = new OwnedFileHandle(handle);
+                this.#snapshotOwners.add(owner);
+                let result;
+                let readFailure;
+                try {
+                    const metadata = await handle.stat();
+                    signal?.throwIfAborted();
+                    if (metadata.size > maximumBytes)
+                        result = {
+                            kind: "over-capacity",
+                            sourceBytesAtLeast: metadata.size,
+                            maximumBytes,
+                        };
+                    else {
+                        const bytes = await readBoundedFileBytes(handle, maximumBytes, signal, metadata.size);
+                        signal?.throwIfAborted();
+                        const after = await handle.stat();
+                        if (bytes !== undefined &&
+                            bytes.length === metadata.size &&
+                            sameRegularFileState(metadata, after)) {
+                            result = { kind: "captured", bytes };
+                        }
+                        else if (bytes === undefined &&
+                            after.isFile() &&
+                            after.size > maximumBytes) {
+                            result = {
+                                kind: "over-capacity",
+                                sourceBytesAtLeast: after.size,
+                                maximumBytes,
+                            };
+                        }
+                        else {
+                            throw new RegularFileChangedError(this.#snapshotPath);
+                        }
+                    }
+                }
+                catch (cause) {
+                    readFailure = cause;
+                }
+                try {
+                    await owner.close();
+                    this.#snapshotOwners.delete(owner);
+                }
+                catch (closeFailure) {
+                    throw new AggregateError(readFailure === undefined
+                        ? [closeFailure]
+                        : [readFailure, closeFailure], "Ghidra target snapshot read or descriptor cleanup failed");
+                }
+                if (readFailure !== undefined)
+                    throw readFailure;
+                return ok(result);
+            }
+            return ok({
+                kind: "captured",
+                bytes: await readFile(this.#snapshotPath),
+            });
         }
         catch (cause) {
-            return err(this.#failure("protocol", "Ghidra target snapshot could not be read for load-image verification", cause));
+            return err(this.#failure(signal?.aborted === true ? "cancelled" : "protocol", "Ghidra target snapshot could not be read for load-image verification", cause));
         }
     }
     /** Stop the owned process group and remove all project/runtime artifacts. */
@@ -290,8 +357,18 @@ export class GhidraClient {
         }, { signal: deadline.signal })
             .catch((cause) => err(this.#failure("start", "Ghidra launcher failed", cause)));
         if (!launched.ok) {
+            const partialLaunch = launched.error instanceof GhidraLaunchError
+                ? launched.error.partialLaunch
+                : undefined;
+            if (partialLaunch !== undefined) {
+                this.#launch = partialLaunch;
+                this.#process = new ProviderProcessSupervisor(partialLaunch, {
+                    maxDiagnosticBytes: GHIDRA_PROCESS_DIAGNOSTIC_BYTES,
+                    onDiagnostic: (event) => this.#onProcessDiagnostic(event),
+                });
+            }
             const failure = deadline.signal.aborted
-                ? this.#interruptionFailure(deadline)
+                ? this.#interruptionFailure(deadline, launched.error)
                 : launched.error instanceof GhidraSessionError
                     ? launched.error
                     : this.#failure("start", launched.error.message, launched.error);
@@ -299,6 +376,7 @@ export class GhidraClient {
         }
         this.#launch = launched.value;
         this.#process = new ProviderProcessSupervisor(launched.value, {
+            maxDiagnosticBytes: GHIDRA_PROCESS_DIAGNOSTIC_BYTES,
             onDiagnostic: (event) => this.#onProcessDiagnostic(event),
         });
         const connected = await this.#connect(endpoint, deadline);
@@ -423,6 +501,10 @@ export class GhidraClient {
             this.#lastDiagnostics = this.#diagnostics();
             this.#process = undefined;
             this.#launch = undefined;
+            for (const owner of this.#snapshotOwners) {
+                await owner.close();
+                this.#snapshotOwners.delete(owner);
+            }
             try {
                 await this.#removeRuntimeRoots();
             }
@@ -519,10 +601,10 @@ export class GhidraClient {
         const failure = this.#interruptionFailure(deadline);
         return this.#startupFailure(failure);
     }
-    #interruptionFailure(deadline) {
+    #interruptionFailure(deadline, cause) {
         return deadline.interruption === "cancelled"
-            ? this.#failure("cancelled", "Ghidra startup was cancelled")
-            : this.#failure("timeout", "Ghidra startup deadline elapsed", undefined, {
+            ? this.#failure("cancelled", "Ghidra startup was cancelled", cause)
+            : this.#failure("timeout", "Ghidra startup deadline elapsed", cause, {
                 timeoutMs: deadline.timeoutMs,
             });
     }

package/dist/ghidra/GhidraDiagnostics.js

@@ -1,12 +1,12 @@
+import { redactCapturedTransportCredential } from "../process/ProviderDiagnosticRedaction.js";
+/** Aggregate in-memory retention budget for this provider's launcher output. */
+export const GHIDRA_PROCESS_DIAGNOSTIC_BYTES = 8 * 1024 * 1024;
 /** Preserve actionable runtime coordinates after cleanup and redact bearer data. */
 export const createGhidraDiagnostics = (options) => {
     if (options.runtimeRoot === undefined &&
         options.launch === undefined &&
         Object.keys(options.previous).length > 0)
         return options.previous;
-    const redacted = (value) => options.token === undefined
-        ? value
-        : value.replaceAll(options.token, "[REDACTED]");
     return {
         target_path: options.targetPath,
         target_sha256: options.targetSha256,
@@ -39,12 +39,15 @@ export const createGhidraDiagnostics = (options) => {
             : {
                 exit_code: options.snapshot.exitCode ?? null,
                 exit_signal: options.snapshot.signal ?? null,
-                stdout: boundedStream(options.snapshot.stdout, redacted),
-                stderr: boundedStream(options.snapshot.stderr, redacted),
+                diagnostic_truncated: options.snapshot.diagnosticTruncated === true,
+                stdout: boundedStream(options.snapshot.stdout, options.token),
+                stderr: boundedStream(options.snapshot.stderr, options.token),
             }),
     };
 };
-const boundedStream = (stream, redact) => ({
-    text: redact(stream.text),
-    bytes: stream.bytes,
+const boundedStream = (stream, token) => ({
+    text: redactCapturedTransportCredential(stream, token, "[REDACTED]"),
+    // Preserve the historical total-byte counter; text is now bounded separately.
+    bytes: stream.observedBytes,
+    retained_bytes: stream.bytes,
 });

package/dist/ghidra/GhidraFunctionValues.js

@@ -285,11 +285,35 @@ const resultSchemas = {
     procedure_references: procedureReferences,
     xrefs: z.array(ghidraCanonicalAddressSchema),
 };
+const functionBoundaryObservationOperations = new Set([
+    "analyze_function",
+    "procedure_assembly",
+    "procedure_info",
+    "procedure_pseudo_code",
+    "read_function_instructions",
+]);
+const functionObservationEnvelope = z.strictObject({
+    value: z.unknown(),
+    limitations: z.array(z.string()),
+});
 /** Require exact, bounded Java-bridge function output before creating Evidence. */
 export const parseGhidraFunctionResult = (operation, value) => {
-    const parsed = resultSchemas[operation].safeParse(value);
+    let observation;
+    if (functionBoundaryObservationOperations.has(operation)) {
+        const envelope = functionObservationEnvelope.safeParse(value);
+        if (!envelope.success)
+            return err(new AnalysisOutputError(operation, "Ghidra bridge omitted the function observation envelope", { cause: envelope.error }));
+        observation = envelope.data;
+    }
+    else {
+        observation = { value, limitations: [] };
+    }
+    const parsed = resultSchemas[operation].safeParse(observation.value);
     return parsed.success
-        ? ok(jsonValueSchema.parse(parsed.data))
+        ? ok({
+            value: jsonValueSchema.parse(parsed.data),
+            limitations: observation.limitations,
+        })
         : err(new AnalysisOutputError(operation, "Ghidra bridge output did not match the function-analysis contract", { cause: parsed.error }));
 };
 const referenceAddresses = (edge) => [

package/dist/ghidra/GhidraInstallation.js

@@ -1,14 +1,84 @@
 import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { spawnSync } from "node:child_process";
 import { constants } from "node:fs";
-import { accessSync, readFileSync } from "node:fs";
+import { accessSync, closeSync, fstatSync, openSync, readFileSync, readSync, statSync, } from "node:fs";
 import { posix, win32 } from "node:path";
+import { parseExecutableHeader, } from "../domain/binaryTarget.js";
 import { ghidraApplicationProperties, ghidraJavaMajorAccepted, ghidraJavaRangeLabel, ghidraJavaRequirement, ghidraReleaseAccepted, ghidraReleaseCompatibility, ghidraReleaseLine, ghidraVersionDetail, SUPPORTED_GHIDRA_JAVA_MAJOR, SUPPORTED_GHIDRA_VERSION, } from "./GhidraInstallationPolicy.js";
 const NATIVE_PLATFORMS = {
     linux: { x64: "linux_x86_64", arm64: "linux_arm_64" },
     darwin: { x64: "mac_x86_64", arm64: "mac_arm_64" },
     win32: { x64: "win_x86_64" },
 };
+/** Executable format each supported host runs its own Ghidra native tools as. */
+const NATIVE_TOOL_FORMATS = {
+    linux: "elf",
+    darwin: "mach-o",
+    win32: "pe",
+};
+/** Node architecture identifiers as the executable-header parser reports them. */
+const NATIVE_ARCHITECTURES = [
+    { node: "x64", binary: "x86_64" },
+    { node: "ia32", binary: "x86" },
+    { node: "arm", binary: "arm" },
+    { node: "arm64", binary: "arm64" },
+];
+/** Bound installation discovery reads; larger headers remain unknown. */
+const EXECUTABLE_HEADER_PROBE_BYTES = 4096;
+/**
+ * Judge a native decompiler by its own executable header instead of the
+ * directory name that admits it.
+ *
+ * Only a header that positively contradicts the host is `incompatible`. An
+ * absent, unreadable, truncated, or unrecognized header stays `unknown`, so a
+ * file the other checks already accept is never refused on missing evidence.
+ */
+const assessNativeDecompiler = (path, platform, architecture, probe) => {
+    const expectedFormat = NATIVE_TOOL_FORMATS[platform];
+    const expectedArchitecture = NATIVE_ARCHITECTURES.find(({ node }) => node === architecture)?.binary;
+    if (expectedFormat === undefined || expectedArchitecture === undefined)
+        return {
+            status: "unknown",
+            detail: `${path} is executable, but no native tool format is defined for ${platform}/${architecture}`,
+        };
+    let parsed = probe === undefined
+        ? undefined
+        : parseExecutableHeader(probe.bytes, architecture, probe.size);
+    if (probe !== undefined && parsed !== undefined && !parsed.ok) {
+        // FAT parsing selects a host slice. A validated foreign slice can still
+        // prove that its complete architecture table excludes this host. If the
+        // host is listed but its slice is malformed, preserve the unknown outcome.
+        for (const { node } of NATIVE_ARCHITECTURES) {
+            if (node === architecture)
+                continue;
+            const alternative = parseExecutableHeader(probe.bytes, node, probe.size);
+            if (alternative.ok &&
+                !alternative.value.availableArchitectures.some((available) => available === expectedArchitecture)) {
+                parsed = alternative;
+                break;
+            }
+        }
+    }
+    if (parsed === undefined || !parsed.ok)
+        return {
+            status: "unknown",
+            detail: `${path} is executable, but its executable format for ${platform}/${architecture} could not be established`,
+        };
+    const observed = `${parsed.value.format} ${parsed.value.architecture}`;
+    const expected = `${expectedFormat} ${expectedArchitecture}`;
+    if (observed === expected)
+        return {
+            status: "compatible",
+            detail: `${path} reports ${observed}, which matches ${platform}/${architecture}`,
+        };
+    const nativeDirectory = NATIVE_PLATFORMS[platform]?.[architecture];
+    const executable = platform === "win32" ? "decompile.exe" : "decompile";
+    return {
+        status: "incompatible",
+        detail: `${path} reports ${observed}, but ${platform}/${architecture} requires ${expected}`,
+        remediation: `Provide an executable Ghidra/Features/Decompiler/os/${nativeDirectory ?? "<platform>"}/${executable} built for ${expected}, or its build/os equivalent. REA does not build or install native tools.`,
+    };
+};
 /** Inspect an installation without importing a target or modifying Ghidra. */
 export const inspectGhidraInstallation = (options, host = systemGhidraInstallationHost()) => {
     const platform = options.platform ?? process.platform;
@@ -137,14 +207,7 @@ const installationChecks = ({ coordinates, platform, architecture, javaHome, hos
         detail: coordinates.analyzeHeadlessPath ?? "analyzeHeadless unavailable",
         remediation: "Restore support/analyzeHeadless or support/analyzeHeadless.bat from the official Ghidra release.",
     }),
-    installationCheck({
-        name: "native_decompiler",
-        passed: coordinates.nativeDecompilerPath !== null,
-        code: "executable_missing",
-        detail: coordinates.nativeDecompilerPath ??
-            `Matching native decompiler for ${platform}/${architecture} was not found`,
-        remediation: `Provide an executable Ghidra/Features/Decompiler/os/${NATIVE_PLATFORMS[platform]?.[architecture] ?? "<platform>"}/${platform === "win32" ? "decompile.exe" : "decompile"}, or its build/os equivalent. REA does not build or install native tools.`,
-    }),
+    nativeDecompilerCheck({ coordinates, platform, architecture, host }),
     javaCheck(coordinates.java, coordinates.javaCommand, javaHome, coordinates.properties),
 ];
 /**
@@ -226,6 +289,23 @@ const installationCheck = (options) => options.passed
         detail: options.detail,
         remediation: options.remediation,
     };
+/** Require a present native decompiler without positively incompatible bytes. */
+const nativeDecompilerCheck = ({ coordinates, platform, architecture, host, }) => {
+    const path = coordinates.nativeDecompilerPath;
+    const compatibility = path === null
+        ? undefined
+        : assessNativeDecompiler(path, platform, architecture, host.executableHeader?.(path));
+    return installationCheck({
+        name: "native_decompiler",
+        passed: path !== null && compatibility?.status !== "incompatible",
+        code: "executable_missing",
+        detail: compatibility?.detail ??
+            `Matching native decompiler for ${platform}/${architecture} was not found`,
+        remediation: compatibility?.status === "incompatible"
+            ? compatibility.remediation
+            : `Provide an executable Ghidra/Features/Decompiler/os/${NATIVE_PLATFORMS[platform]?.[architecture] ?? "<platform>"}/${platform === "win32" ? "decompile.exe" : "decompile"}, or its build/os equivalent. REA does not build or install native tools.`,
+    });
+};
 const versionCheck = (properties) => {
     const raw = properties?.providerVersion;
     return installationCheck({
@@ -280,10 +360,31 @@ const systemGhidraInstallationHost = () => ({
             return undefined;
         }
     },
+    executableHeader(path) {
+        let handle;
+        try {
+            handle = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOCTTY);
+            const metadata = fstatSync(handle);
+            if (!metadata.isFile())
+                return undefined;
+            const bytes = Buffer.alloc(EXECUTABLE_HEADER_PROBE_BYTES);
+            const read = readSync(handle, bytes, 0, bytes.length, 0);
+            return { bytes: bytes.subarray(0, read), size: metadata.size };
+        }
+        catch (cause) {
+            // best-effort cleanup: a header that cannot be read stays unknown.
+            void cause;
+            return undefined;
+        }
+        finally {
+            if (handle !== undefined)
+                closeSync(handle);
+        }
+    },
     executable(path) {
         try {
             accessSync(path, constants.X_OK);
-            return true;
+            return statSync(path).isFile();
         }
         catch (cause) {
             // best-effort cleanup: optional executable probing; failure means missing.

package/dist/ghidra/GhidraInventoryValues.js

@@ -5,7 +5,10 @@ import { functionBodySchema, functionBodyEntryAgrees, } from "../domain/hopperVa
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
 import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
-/** Read-only direct inventory operations admitted by the Ghidra adapter. */
+/**
+ * Direct inventory operations admitted by the Ghidra adapter. All are reads
+ * except the naming operations, which edit the ephemeral session database.
+ */
 export const GHIDRA_INVENTORY_OPERATIONS = [
     "inspect_native_load_image",
     "read_bytes",
@@ -20,6 +23,13 @@ export const GHIDRA_INVENTORY_OPERATIONS = [
     "resolve_containing_procedure",
     "search_procedures",
     "search_strings",
+    "set_address_name",
+    "set_addresses_names",
+];
+/** Inventory operations that write analyst names into the session database. */
+export const GHIDRA_NAMING_OPERATIONS = [
+    "set_address_name",
+    "set_addresses_names",
 ];
 const operationSet = new Set(GHIDRA_INVENTORY_OPERATIONS);
 /** Narrow an application operation to the Ghidra inventory surface. */
@@ -62,6 +72,16 @@ const inputSchemas = {
         .strict(),
     search_procedures: z.object(searchInput).strict(),
     search_strings: z.object(searchInput).strict(),
+    set_address_name: z
+        .object({ document, address: explicitAddress, name: z.string().min(1) })
+        .strict(),
+    set_addresses_names: z
+        .object({
+        document,
+        names: z.record(explicitAddress, z.string().min(1)),
+    })
+        .strict()
+        .refine((value) => Object.keys(value.names).length > 0, "Supply at least one address name"),
 };
 /** Validate and default one provider request before it crosses the socket. */
 export const parseGhidraInventoryInput = (operation, value) => {
@@ -230,6 +250,8 @@ const resultSchemas = {
     resolve_containing_procedure: containingProcedure,
     search_procedures: z.array(searchItem),
     search_strings: z.array(searchItem),
+    set_address_name: z.boolean(),
+    set_addresses_names: z.record(z.string(), z.boolean()),
 };
 /** Validate exact Java-bridge output before creating Evidence. */
 export const parseGhidraInventoryResult = (operation, value) => {