rea-agents 6.3.0 → 6.5.0

package/dist/ghidra/GhidraClient.js

@@ -1,6 +1,7 @@
-import { randomBytes, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { providerRetryAction, } from "../domain/providerOperationHealth.js";
 import { err, ok } from "../domain/result.js";
 import { silentLogger } from "../logger.js";
 import { PendingOperations } from "../process/PendingOperations.js";
@@ -8,8 +9,8 @@ import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 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 { DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS } from "../config/providerStartupTimeout.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";
@@ -17,7 +18,11 @@ import { GhidraRequestQueue } from "./GhidraRequestQueue.js";
 import { bindGhidraSessionFailure, GhidraSessionError, } from "./GhidraSessionError.js";
 import { isGhidraShutdownAcknowledgement, parseGhidraSessionInfo, } from "./GhidraSessionValues.js";
 import { createGhidraTargetSnapshot } from "./GhidraTargetSnapshot.js";
-import { readFile } from "node:fs/promises";
+import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
+import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
+import { openRegularFile, RegularFileChangedError, RegularFileAdmissionFailure, sameRegularFileState, } from "../filesystem/RegularFile.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { redactCapturedTransportCredential } from "../process/ProviderDiagnosticRedaction.js";
 import { connectGhidraSocket } from "./GhidraSocketConnection.js";
 import { createGhidraEndpoint, } from "./GhidraTransport.js";
 import { GhidraWire } from "./GhidraClientWire.js";
@@ -38,6 +43,7 @@ export class GhidraClient {
     #socketRoot;
     #endpointPath;
     #snapshotPath;
+    #snapshotOwners = new Set();
     #targetAdmission;
     #token;
     // Retain authentication identities for diagnostics from late request settlement.
@@ -50,8 +56,9 @@ export class GhidraClient {
     #lastDiagnostics = {};
     #startupController;
     #startPromise;
+    #ready = false;
     #closePromise;
-    #failure = bindGhidraSessionFailure(() => this.#diagnostics(), (value) => this.#redactAuthentication(value));
+    #failure = bindGhidraSessionFailure(() => this.#diagnostics(), (value, incomplete) => this.#redactAuthentication(value, incomplete));
     #wire;
     #requestQueue;
     #responseRouter = new GhidraResponseRouter({
@@ -92,7 +99,9 @@ export class GhidraClient {
         this.#requestQueue = new GhidraRequestQueue((method, parameters, requestOptions) => this.#wire.request(method, parameters, requestOptions), (kind, message, cause) => this.#failure(kind, message, cause), () => this.#stopAfterActiveCancellation());
     }
     /** Launch Ghidra once and require its exact post-analysis handshake. */
-    start(signal) {
+    start(signal, progress) {
+        if (progress !== undefined)
+            return this.#reportStartupWait(this.start(signal), signal, progress);
         if (this.#closePromise !== undefined)
             return this.#closePromise.then(() => this.start(signal), (cause) => err(new GhidraSessionError("process", "Ghidra cleanup remains incomplete", this.#diagnostics(), { cause, cleanupFailure: this.#cleanupError(cause) })));
         if (this.#startPromise !== undefined) {
@@ -121,7 +130,9 @@ export class GhidraClient {
         };
         void started.then((result) => {
             signal?.removeEventListener("abort", onAbort);
-            if (!result.ok)
+            if (result.ok)
+                this.#ready = true;
+            else
                 reset();
         }, (cause) => {
             this.#logger.debug({ error: cause instanceof Error ? cause.message : String(cause) }, "Ghidra startup promise rejected during bookkeeping");
@@ -129,6 +140,39 @@ export class GhidraClient {
         });
         return started;
     }
+    async #reportStartupWait(started, signal, progress) {
+        const startedAt = performance.now();
+        let active = true;
+        let reporting = false;
+        const timer = setInterval(() => {
+            if (!active || reporting || signal?.aborted)
+                return;
+            reporting = true;
+            void Promise.resolve()
+                .then(() => {
+                if (!active || signal?.aborted)
+                    return;
+                return progress.report({
+                    phase: "ghidra_startup",
+                    completed: 0,
+                    total: null,
+                    message: `Waiting for Ghidra startup (${String(Math.floor((performance.now() - startedAt) / 1000))}s elapsed); import, auto-analysis and bridge readiness may still be pending`,
+                });
+            })
+                // Notification failure does not release the owned startup process.
+                .catch(() => { })
+                .finally(() => {
+                reporting = false;
+            });
+        }, 10_000);
+        try {
+            return await started;
+        }
+        finally {
+            active = false;
+            clearInterval(timer);
+        }
+    }
     /** Revalidate live bridge, provider, run, and profile metadata. */
     async ping(options = {}) {
         const started = await this.start(options.signal);
@@ -141,20 +185,97 @@ export class GhidraClient {
     }
     /** Execute one admitted operation through the serial per-Program queue. */
     async callTool(operation, parameters, options = {}) {
-        const started = await this.start(options.signal);
+        const started = await this.start(options.signal, options.progress);
         if (!started.ok)
             return started;
         return this.#requestQueue.run(operation, parameters, options.signal === undefined ? {} : { signal: options.signal });
     }
-    /** Read the private immutable source for independent import verification. */
-    async readTargetSnapshot() {
-        if (this.#snapshotPath === undefined)
+    /** Dispatch against the connected bridge without invoking startup or retry. */
+    callToolIfReady(operation, parameters, options = {}) {
+        if (!this.isReady())
+            return Promise.resolve(undefined);
+        return this.#requestQueue.run(operation, parameters, options.signal === undefined ? {} : { signal: options.signal });
+    }
+    /** Read the private immutable source for format parsers that require captured bytes. */
+    readTargetSnapshot(maximumBytes, signal) {
+        return this.#withTargetSnapshot(async (handle, initial, path) => {
+            if (maximumBytes !== undefined &&
+                (!Number.isSafeInteger(maximumBytes) || maximumBytes < 0))
+                throw new RangeError("Snapshot byte limit must be a safe integer");
+            if (maximumBytes !== undefined && initial.size > maximumBytes)
+                return {
+                    kind: "over-capacity",
+                    sourceBytesAtLeast: initial.size,
+                    maximumBytes,
+                };
+            const bytes = await readBoundedFileBytes(handle, maximumBytes ?? initial.size, signal, initial.size);
+            if (bytes === undefined || bytes.length !== initial.size)
+                throw new RegularFileChangedError(path);
+            return { kind: "captured", bytes };
+        }, signal);
+    }
+    /** Measure the complete snapshot identity without retaining its bytes in memory. */
+    hashTargetSnapshot(signal) {
+        return this.#withTargetSnapshot(async (handle, initial, path) => {
+            const hash = createHash("sha256");
+            let bytes = 0;
+            for await (const chunk of readFileHandleChunks(handle, {
+                end: initial.size,
+                signal,
+            })) {
+                bytes += chunk.length;
+                if (bytes > initial.size)
+                    throw new RegularFileChangedError(path);
+                hash.update(chunk);
+            }
+            if (bytes !== initial.size)
+                throw new RegularFileChangedError(path);
+            return { sha256: hash.digest("hex"), bytes };
+        }, signal);
+    }
+    async #withTargetSnapshot(read, signal) {
+        const path = this.#snapshotPath;
+        if (path === undefined)
             return err(this.#failure("protocol", "Ghidra target snapshot is unavailable before startup or after close"));
         try {
-            return ok(await readFile(this.#snapshotPath));
+            const handle = await openRegularFile(path, {
+                symlinks: "reject",
+                signal,
+            });
+            const owner = new OwnedFileHandle(handle);
+            this.#snapshotOwners.add(owner);
+            let result;
+            try {
+                const initial = await handle.stat();
+                signal?.throwIfAborted();
+                if (!Number.isSafeInteger(initial.size) || initial.size < 0)
+                    throw new RangeError("Snapshot size must be a safe integer");
+                const value = await read(handle, initial, path);
+                signal?.throwIfAborted();
+                const after = await handle.stat();
+                signal?.throwIfAborted();
+                if (!sameRegularFileState(initial, after))
+                    throw new RegularFileChangedError(path);
+                result = ok(value);
+            }
+            catch (cause) {
+                result = err(cause);
+            }
+            try {
+                await owner.close();
+                this.#snapshotOwners.delete(owner);
+            }
+            catch (closeFailure) {
+                throw new AggregateError(result.ok ? [closeFailure] : [result.error, closeFailure], "Ghidra target snapshot read or descriptor cleanup failed");
+            }
+            if (!result.ok)
+                throw result.error;
+            return result;
         }
         catch (cause) {
-            return err(this.#failure("protocol", "Ghidra target snapshot could not be read for load-image verification", cause));
+            if (cause instanceof RegularFileAdmissionFailure)
+                this.#snapshotOwners.add(cause.owner);
+            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. */
@@ -167,6 +288,13 @@ export class GhidraClient {
             return err(this.#cleanupError(cause));
         }
     }
+    /** True only after the authenticated startup handshake has completed. */
+    isReady() {
+        return (this.#ready &&
+            this.#socket !== undefined &&
+            !this.#socket.destroyed &&
+            this.#closePromise === undefined);
+    }
     #cleanupError(cause) {
         if (cause instanceof AnalysisError && cause.cleanupIncomplete)
             return cause;
@@ -197,6 +325,7 @@ export class GhidraClient {
         }
     }
     #requestClose(forceStop) {
+        this.#ready = false;
         const starting = this.#startPromise;
         const controller = this.#startupController;
         controller?.abort();
@@ -209,6 +338,31 @@ export class GhidraClient {
             throw cause;
         });
     }
+    /** Observed failures that prevent a retained session from being reused. */
+    operationHealthSnapshot() {
+        const exit = this.#process?.observedExit();
+        const state = exit !== undefined
+            ? "exited"
+            : this.#socket?.destroyed === true
+                ? "unreachable"
+                : this.#startPromise === undefined &&
+                    (this.#process !== undefined ||
+                        this.#socket !== undefined ||
+                        this.#runtimeRoot !== undefined ||
+                        this.#socketRoot !== undefined ||
+                        this.#snapshotOwners.size > 0)
+                    ? "unknown"
+                    : undefined;
+        if (state === undefined)
+            return undefined;
+        return {
+            state,
+            stage: null,
+            retryAction: providerRetryAction(state),
+            exitCode: exit?.code ?? null,
+            requests: [],
+        };
+    }
     /** Latest bounded local diagnostics, with bearer material redacted. */
     diagnostics() {
         return structuredClone(this.#diagnostics());
@@ -297,6 +451,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,33 +464,51 @@ 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);
-        if (!connected.ok) {
-            const failure = connected.error;
-            return this.#startupFailure(failure);
-        }
-        const completed = await completeGhidraStartupHandshake({
-            deadline,
-            request: (method, params, requestOptions) => this.#wire.request(method, params, requestOptions),
-            parseSessionInfo: (value) => this.#parseSessionInfo(value),
-            failure: this.#failure,
-            startupTimeoutMs: this.#options.startupTimeoutMs,
-        });
+        const completed = await this.#connectAndHandshake(endpoint, deadline);
         if (!completed.ok)
             return this.#startupFailure(completed.error);
         await this.#lineage.observe(this.#launch);
         this.#requestQueue.reopen();
         return completed;
     }
+    async #connectAndHandshake(endpoint, deadline) {
+        // Retry only a dropped loopback transport, never identity or protocol failures.
+        for (let attempt = 0;; attempt += 1) {
+            const connected = await this.#connect(endpoint, deadline);
+            if (!connected.ok)
+                return connected;
+            const completed = await completeGhidraStartupHandshake({
+                deadline,
+                request: (method, params, requestOptions) => this.#wire.request(method, params, requestOptions),
+                parseSessionInfo: (value) => this.#parseSessionInfo(value),
+                failure: this.#failure,
+                startupTimeoutMs: this.#options.startupTimeoutMs,
+            });
+            if (completed.ok ||
+                completed.error.kind !== "process" ||
+                endpoint.transport !== "authenticated-loopback-tcp" ||
+                attempt >= 2 ||
+                deadline.signal.aborted ||
+                this.#closing ||
+                this.#process?.observedExit() !== undefined)
+                return completed;
+            this.#detachSocket?.();
+            this.#detachSocket = undefined;
+            this.#socket?.destroy();
+            this.#socket = undefined;
+            this.#responseBuffer.reset();
+        }
+    }
     async #connect(endpoint, deadline) {
         const connected = await connectGhidraSocket({
             endpoint,
             deadline,
             failure: this.#failure,
             isClosed: () => this.#closing,
-            processExited: () => this.#process?.snapshot().exitCode !== undefined,
+            processExited: () => this.#process?.observedExit() !== undefined,
             startupTimeoutMs: this.#options.startupTimeoutMs,
             handlers: {
                 data: this.#onSocketData,
@@ -433,6 +606,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();
             }
@@ -490,9 +667,11 @@ export class GhidraClient {
                 failures: leftovers.map(({ path, reason }) => `${path}: ${reason}`),
             }, { cause: firstCause });
     }
-    #redactAuthentication(value) {
-        for (const token of this.#authenticationTokens)
-            value = value.replaceAll(token, "[REDACTED]");
+    #redactAuthentication(value, incomplete = false) {
+        for (const token of this.#authenticationTokens) {
+            const bytes = Buffer.byteLength(value);
+            value = redactCapturedTransportCredential({ text: value, bytes, observedBytes: bytes + (incomplete ? 1 : 0) }, token, "[REDACTED]");
+        }
         return value;
     }
     #onProcessDiagnostic(event) {

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,
@@ -33,18 +33,28 @@ export const createGhidraDiagnostics = (options) => {
                 ghidra_log_path: options.launch.ghidraLogPath,
                 script_log_path: options.launch.scriptLogPath,
                 process_id: options.launch.process.pid ?? null,
+                ...(options.launch.launchSupport === undefined
+                    ? {}
+                    : {
+                        launch_support: options.launch.launchSupport.map((output) => ({
+                            ...output,
+                        })),
+                    }),
             }),
         ...(options.snapshot === undefined
             ? {}
             : {
                 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/GhidraDoctor.js

@@ -1,10 +1,11 @@
-import { hasWindowsNativeAuthority, windowsNativeAuthorityUnavailableReason, } from "../process/WindowsAuthority.js";
+import { inspectWindowsNativeReadiness } from "../process/WindowsAuthority.js";
 import { inspectGhidraInstallation, } from "./GhidraInstallation.js";
 /** Project installation and runtime-authority facts into the doctor contract. */
 export const projectGhidraDoctorInspection = (inspection) => {
-    const windowsAuthorityUnavailable = inspection.status === "available" &&
-        inspection.platform === "win32" &&
-        !hasWindowsNativeAuthority(inspection.platform);
+    const readiness = inspection.status === "available" && inspection.platform === "win32"
+        ? inspectWindowsNativeReadiness(inspection.platform)
+        : undefined;
+    const windowsAuthorityUnavailable = readiness?.available === false;
     return {
         id: "ghidra",
         configured: inspection.installDir !== null,
@@ -18,19 +19,21 @@ export const projectGhidraDoctorInspection = (inspection) => {
             : {},
         checks: [
             ...selectedChecks(inspection).map((check) => projectCheck(check, inspection.installDir !== null)),
-            ...(inspection.status === "available" && inspection.platform === "win32"
+            ...(readiness !== undefined
                 ? [
                     {
                         name: "native_authority",
                         ok: !windowsAuthorityUnavailable,
-                        code: windowsAuthorityUnavailable ? "unsupported_host" : null,
-                        detail: windowsAuthorityUnavailable
-                            ? windowsNativeAuthorityUnavailableReason(inspection.platform)
+                        code: !readiness.available ? readiness.code : null,
+                        detail: !readiness.available
+                            ? readiness.reason
                             : "Verified Windows native Job Object, private DACL, and reparse-safe handle controls; local NTFS only.",
-                        remediation: windowsAuthorityUnavailable
-                            ? "Use the matching Windows x64 REA package with its bundled native addon and a writable local NTFS temporary directory. The native failure above identifies the failed constraint; Ghidra installation or registration changes cannot enable a missing native backend."
-                            : null,
-                        classification: "unsupported_host",
+                        remediation: !readiness.available ? readiness.remediation : null,
+                        classification: !readiness.available && readiness.code === "runtime_unavailable"
+                            ? "runtime_failure"
+                            : !readiness.available && readiness.code === "runtime_missing"
+                                ? "missing_dependency"
+                                : "unsupported_host",
                     },
                 ]
                 : []),

package/dist/ghidra/GhidraFunctionValues.js

@@ -7,6 +7,7 @@ import { functionBodyEntryAgrees, functionInstructionWindowSchema, functionDossi
 import { jsonObjectSchema, jsonValueSchema, } from "../domain/jsonValue.js";
 import { nativeApiBoundarySchema } from "../domain/native/nativeApiBoundary.js";
 import { nativeValueFlowSchema } from "../domain/native/nativeValueFlow.js";
+import { relationshipCoverageSchema, } from "../domain/relationshipCoverage.js";
 import { err, ok } from "../domain/result.js";
 import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { ghidraIdentifierSchema, ghidraInputAddressSchema, ghidraCanonicalAddressSchema, ghidraFunctionClassificationSchema as classification, ghidraFunctionBodySchema as ghidraFunctionBody, ghidraProcedureIdentitySchema as procedureIdentity, } from "./GhidraInventoryValues.js";
@@ -209,11 +210,18 @@ const ghidraFunctionDossier = functionDossierSchema
 })
     .strict()
     .superRefine((value, context) => {
+    if ((value.swift_string_literals === undefined) !==
+        (value.swift_string_literal_omissions === undefined))
+        context.addIssue({
+            code: "custom",
+            message: "Ghidra dossier must record Swift literals and their omissions together",
+        });
     const addresses = [
         value.procedure.address,
         ...value.comments.map(({ address }) => address),
         ...value.callers.map(({ address }) => address),
         ...value.callees.map(({ address }) => address),
+        ...(value.unresolved_calls ?? []).map(({ address }) => address),
         ...value.incoming_references.flatMap(referenceAddresses),
         ...value.outgoing_references.flatMap(referenceAddresses),
         ...value.referenced_strings.flatMap(({ address, source_address }) => [
@@ -224,6 +232,8 @@ const ghidraFunctionDossier = functionDossierSchema
             address,
             source_address,
         ]),
+        ...(value.swift_string_literals ?? []).flatMap(({ address, source_address }) => address === null ? [source_address] : [address, source_address]),
+        ...(value.swift_string_literal_omissions ?? []).flatMap(({ address, source_address }) => address === null ? [source_address] : [address, source_address]),
         ...value.basic_blocks.flatMap(({ start, end, successors }) => [
             start,
             end,
@@ -285,11 +295,72 @@ const resultSchemas = {
     procedure_references: procedureReferences,
     xrefs: z.array(ghidraCanonicalAddressSchema),
 };
+const functionBoundaryObservationOperations = new Set([
+    "analyze_function",
+    "procedure_assembly",
+    "procedure_callees",
+    "procedure_callers",
+    "procedure_info",
+    "procedure_pseudo_code",
+    "read_function_instructions",
+]);
+const functionObservationEnvelope = z.strictObject({
+    value: z.unknown(),
+    limitations: z.array(z.string()),
+    relationship_coverage: relationshipCoverageSchema.exactOptional(),
+    selection: z
+        .strictObject({
+        file_offset: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+        mapped_address: ghidraCanonicalAddressSchema,
+        procedure_address: ghidraCanonicalAddressSchema,
+    })
+        .exactOptional(),
+});
 /** 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 ||
+            (operation !== "analyze_function" &&
+                operation !== "procedure_callers" &&
+                operation !== "procedure_callees" &&
+                envelope.data.relationship_coverage !== undefined) ||
+            (operation !== "procedure_pseudo_code" &&
+                envelope.data.selection !== undefined))
+            return err(new AnalysisOutputError(operation, "Ghidra bridge returned an invalid function observation envelope for this operation", envelope.success ? undefined : { 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,
+            ...(observation.relationship_coverage === undefined
+                ? {}
+                : { relationshipCoverage: observation.relationship_coverage }),
+            ...(observation.selection === undefined
+                ? {}
+                : {
+                    locations: [
+                        {
+                            kind: "file-offset",
+                            offset: observation.selection.file_offset,
+                        },
+                        {
+                            kind: "address",
+                            address: observation.selection.mapped_address,
+                        },
+                        {
+                            kind: "address",
+                            address: observation.selection.procedure_address,
+                        },
+                    ],
+                }),
+        })
         : err(new AnalysisOutputError(operation, "Ghidra bridge output did not match the function-analysis contract", { cause: parsed.error }));
 };
 const referenceAddresses = (edge) => [