rea-agents 6.3.0 → 6.4.0

package/dist/ghidra/GhidraAnalysisProfile.js

@@ -1,24 +1,45 @@
 import { createAnalysisProfile } from "../domain/analysisProfile.js";
-import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import {} from "../domain/analysisErrorBase.js";
 import { err, ok } from "../domain/result.js";
+import { ghidraMipsProfileParameters, ghidraMipsUnsupportedReason, } from "./GhidraMipsProfile.js";
+import { NATIVE_AOT_MAX_REPORT_BYTES, NATIVE_AOT_MAX_SOURCE_BYTES, NATIVE_AOT_MAX_WORKING_MEMORY_BYTES, NATIVE_AOT_MAX_WORK_UNITS, NATIVE_AOT_PROFILE_CONTRACT_REVISION, } from "../domain/native/nativeAotPe.js";
 /** Resolve version-bound, deterministic semantics before Ghidra imports a target. */
-export const resolveGhidraAnalysisProfile = (target, identity, installation, signal) => {
+export const resolveGhidraAnalysisProfile = (target, identity, installation, signal, languageOverride) => {
     if (signal?.aborted === true)
         return Promise.resolve(err(new AnalysisCancelledError("open_binary")));
     if (target.kind !== "executable")
         return Promise.resolve(ok({ profile: null }));
     if (installation.status === "unavailable")
         return Promise.resolve(err(new ProviderAdapterError(identity.id, "resolve_analysis_profile")));
+    const mipsReason = ghidraMipsUnsupportedReason(target);
+    if (mipsReason !== null)
+        return Promise.resolve(err(new AnalysisUnsupportedTargetError("resolve_analysis_profile", target.path, mipsReason)));
     const provider = { ...identity, version: installation.providerVersion };
     const dosMz = target.format === "dos-mz";
     const dosCom = target.format === "dos-com";
     const dos = dosMz || dosCom;
+    // DOS imports already force an admitted loader, language, and context.
+    if (dos && languageOverride !== undefined)
+        return Promise.resolve(err(new AnalysisUnsupportedTargetError("resolve_analysis_profile", target.path, "REA_GHIDRA_LANGUAGE_ID cannot override the admitted DOS real-mode import.")));
     return Promise.resolve(ok({
         profile: createAnalysisProfile(provider, {
             target_kind: target.kind,
             target_format: target.format,
+            ...(target.format === "pe"
+                ? {
+                    executable_role: target.executableRole ?? null,
+                    managed: target.managed ?? null,
+                    native_aot_metadata: {
+                        contract_revision: NATIVE_AOT_PROFILE_CONTRACT_REVISION,
+                        source_bytes: NATIVE_AOT_MAX_SOURCE_BYTES,
+                        work_units: NATIVE_AOT_MAX_WORK_UNITS,
+                        working_memory_bytes: NATIVE_AOT_MAX_WORKING_MEMORY_BYTES,
+                        report_bytes: NATIVE_AOT_MAX_REPORT_BYTES,
+                    },
+                }
+                : {}),
             architecture: target.architecture ?? null,
             available_architectures: [
                 ...(target.availableArchitectures ?? []),
@@ -28,8 +49,13 @@ export const resolveGhidraAnalysisProfile = (target, identity, installation, sig
             load_image_observations: "source-mappings-entry-context-v2",
             function_body_evidence: "complete-inclusive-ranges-v1",
             function_references: "complete-body-and-entry-reference-manager-v2",
+            string_inventory_evidence: "defined-data-coverage-v1",
             location_resolution: "explicit-address-exact-entry-symbol-first-v3",
             instruction_flow_evidence: "decoded-return-pcode-v1",
+            function_boundary_observations: "ghidra-terminal-call-limitations-v1",
+            no_return_repair: installation.platform === "win32"
+                ? "disabled-windows-p0"
+                : "returning-imports-decoded-return-v2",
             process_launch: installation.platform === "win32"
                 ? "official-headless-script-v1"
                 : "inspected-jvm-launch-support-v1",
@@ -47,8 +73,17 @@ export const resolveGhidraAnalysisProfile = (target, identity, installation, sig
                 : dosCom
                     ? "BinaryLoader"
                     : "auto-from-header",
-            language_id: dos ? "x86:LE:16:Real Mode" : "auto-from-header",
-            compiler_spec_id: dos ? "default" : "auto-default",
+            language_id: dos
+                ? "x86:LE:16:Real Mode"
+                : (languageOverride?.languageId ?? "auto-from-header"),
+            compiler_spec_id: dos
+                ? "default"
+                : languageOverride === undefined
+                    ? "auto-default"
+                    : (languageOverride.compilerSpecId ?? "language-default"),
+            ...(languageOverride === undefined
+                ? {}
+                : { language_selection: "configured-v1" }),
             ...(dos
                 ? {
                     load_segment: "0x1000",
@@ -68,6 +103,22 @@ export const resolveGhidraAnalysisProfile = (target, identity, installation, sig
                 }
                 : {}),
             analyzer_preset: "ghidra-default",
+            ...ghidraMipsProfileParameters(target),
         }),
     }));
 };
+/** Read the import-language commitment back from a resolved profile. */
+export const ghidraProfileLanguageOverride = (parameters) => {
+    if (parameters.language_selection !== "configured-v1")
+        return undefined;
+    const languageId = parameters.language_id;
+    const compilerSpecId = parameters.compiler_spec_id;
+    if (typeof languageId !== "string" || typeof compilerSpecId !== "string")
+        return undefined;
+    return compilerSpecId === "language-default"
+        ? { languageId }
+        : { languageId, compilerSpecId };
+};
+/** Whether a committed profile and the active configuration select the same language. */
+export const sameGhidraLanguageOverride = (left, right) => left?.languageId === right?.languageId &&
+    left?.compilerSpecId === right?.compilerSpecId;

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,7 @@ 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";
@@ -18,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";
@@ -38,6 +41,7 @@ export class GhidraClient {
     #socketRoot;
     #endpointPath;
     #snapshotPath;
+    #snapshotOwners = new Set();
     #targetAdmission;
     #token;
     // Retain authentication identities for diagnostics from late request settlement.
@@ -147,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. */
@@ -297,6 +363,7 @@ export class GhidraClient {
             if (partialLaunch !== undefined) {
                 this.#launch = partialLaunch;
                 this.#process = new ProviderProcessSupervisor(partialLaunch, {
+                    maxDiagnosticBytes: GHIDRA_PROCESS_DIAGNOSTIC_BYTES,
                     onDiagnostic: (event) => this.#onProcessDiagnostic(event),
                 });
             }
@@ -309,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);
@@ -433,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();
             }

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

@@ -53,7 +53,7 @@ const assessNativeDecompiler = (path, platform, architecture, probe) => {
                 continue;
             const alternative = parseExecutableHeader(probe.bytes, node, probe.size);
             if (alternative.ok &&
-                !alternative.value.availableArchitectures.includes(expectedArchitecture)) {
+                !alternative.value.availableArchitectures.some((available) => available === expectedArchitecture)) {
                 parsed = alternative;
                 break;
             }

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) => {