rea-agents 6.4.0 → 6.5.0

package/dist/application/BinaryTargetResolver.js

@@ -6,12 +6,15 @@ import { BinaryTargetError } from "../domain/configurationErrors.js";
 import { openRegularFile, sameRegularFileState, } from "../filesystem/RegularFile.js";
 import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { err, ok } from "../domain/result.js";
-import { readMipsElfAbiFlags } from "./MipsElfAbiFlags.js";
+import { readMipsElfMetadata } from "./MipsElfMetadata.js";
 import { resolveAppBundleExecutable, } from "./AppBundleExecutable.js";
 import { validateDosComLength, } from "../domain/dosCom.js";
-import { mzWindowsHeaderOffset } from "../domain/dosMz.js";
-import { hasZipSignature, zipPackageFormatForPath, } from "../domain/zipPackageFormat.js";
-import { parseExecutableHeader, parsePeRecord, } from "../domain/binaryTarget.js";
+import { admitRawBinary, rawBinarySelectionError, } from "../domain/rawBinary.js";
+import { observeMzWindowsHeader } from "../domain/dosMz.js";
+import { createXmlPlistSignatureProbe, hasBinaryPlistSignature, MAX_XML_PLIST_PROBE_BYTES, } from "../domain/apple/appleArchiveFormat.js";
+import { hasZipSignature, isZipPackageFormat, zipPackageFormatForPath, } from "../domain/zipPackageFormat.js";
+import { parseCodeViewData, parseExecutableHeader, parsePeRecord, peDebugDirectoryEntry, peRvaToFileOffset, } from "../domain/binaryTarget.js";
+const XML_PLIST_PROBE_CHUNK_BYTES = 64 * 1024;
 /**
  * Resolve and classify a readable local target before a provider is selected.
  * FAT Mach-O inputs select only a host-compatible architecture so setup remains
@@ -20,13 +23,15 @@ import { parseExecutableHeader, parsePeRecord, } from "../domain/binaryTarget.js
 export const parseBinaryTarget = async (input, options = {}) => {
     const cwd = options.cwd ?? process.cwd();
     const hostArchitecture = options.hostArchitecture ?? process.arch;
-    const { targetKind, formatHint, signal } = options;
+    const { targetKind, formatHint, signal, architecture, entryPoint } = options;
     const candidate = isAbsolute(input) ? input : resolve(cwd, input);
     try {
         throwIfTargetResolutionCancelled(signal);
         await access(candidate, constants.R_OK);
         throwIfTargetResolutionCancelled(signal);
         const canonical = await realpath(candidate);
+        // Windows native admission must inspect the caller-selected reparse components.
+        const sourcePath = process.platform === "win32" ? candidate : canonical;
         throwIfTargetResolutionCancelled(signal);
         const resolved = await resolveAppBundle(canonical);
         throwIfTargetResolutionCancelled(signal);
@@ -42,15 +47,50 @@ export const parseBinaryTarget = async (input, options = {}) => {
             throwIfTargetResolutionCancelled(signal);
             const metadata = await handle.stat();
             throwIfTargetResolutionCancelled(signal);
+            if (formatHint === "raw-binary") {
+                if (targetKind !== undefined && targetKind !== "executable")
+                    return err(new BinaryTargetError(path, "raw-binary format requires an executable target kind", { constraint: "load_selection_rejected" }));
+                const admitted = admitRawBinary({
+                    architecture,
+                    entryPoint,
+                    fileBytes: metadata.size,
+                });
+                if (!admitted.ok)
+                    return err(new BinaryTargetError(path, admitted.error.reason, {
+                        constraint: admitted.error.constraint,
+                    }));
+                return ok({
+                    path,
+                    sourcePath,
+                    sha256: await sha256Handle(handle, path, metadata, signal),
+                    kind: "executable",
+                    format: "raw-binary",
+                    architecture: admitted.value.architecture,
+                    availableArchitectures: [admitted.value.architecture],
+                    entryPoint: admitted.value.entryPoint,
+                    entryPointSource: admitted.value.entryPointSource,
+                });
+            }
+            const pairing = rawBinarySelectionError({
+                ...(formatHint === undefined ? {} : { format: formatHint }),
+                architecture,
+                entryPoint,
+            });
+            if (pairing !== undefined)
+                return err(new BinaryTargetError(path, pairing, {
+                    constraint: "load_selection_rejected",
+                }));
             if (formatHint === "dos-com") {
                 if (targetKind !== undefined && targetKind !== "executable")
-                    return err(new BinaryTargetError(path, "DOS COM format requires an executable target kind"));
+                    return err(new BinaryTargetError(path, "DOS COM format requires an executable target kind", { constraint: "load_selection_rejected" }));
                 const length = validateDosComLength(metadata.size);
                 if (!length.ok)
-                    return err(new BinaryTargetError(path, length.error));
+                    return err(new BinaryTargetError(path, length.error, {
+                        constraint: "file_format_rejected",
+                    }));
                 return ok({
                     path,
-                    sourcePath: canonical,
+                    sourcePath,
                     sha256: await sha256Handle(handle, path, metadata, signal),
                     kind: "executable",
                     format: "dos-com",
@@ -58,20 +98,24 @@ export const parseBinaryTarget = async (input, options = {}) => {
                     availableArchitectures: ["x86"],
                 });
             }
+            // Probe WASM content before suffix-only database routing; an explicit
+            // database selection keeps the caller's chosen interpretation.
+            const artifactFormat = targetKind === "database"
+                ? undefined
+                : await detectArtifactFormat(path, handle, signal);
             if (targetKind === "database" ||
                 (targetKind === undefined && path.toLowerCase().endsWith(".hop")))
                 return ok({
                     path,
-                    sourcePath: process.platform === "win32" ? candidate : canonical,
+                    sourcePath,
                     sha256: await sha256Handle(handle, path, metadata, signal),
                     kind: "database",
                     format: "analysis-database",
                 });
-            const artifactFormat = await detectArtifactFormat(path, handle, signal);
             if (artifactFormat !== undefined) {
                 const identity = {
                     path,
-                    sourcePath: process.platform === "win32" ? candidate : canonical,
+                    sourcePath,
                     sha256: await sha256Handle(handle, path, metadata, signal),
                 };
                 return isArchiveFormat(artifactFormat)
@@ -80,10 +124,12 @@ export const parseBinaryTarget = async (input, options = {}) => {
             }
             const detected = await readExecutableMetadata(handle, hostArchitecture, signal);
             if (!detected.ok)
-                return err(new BinaryTargetError(path, detected.error));
+                return err(new BinaryTargetError(path, detected.error, {
+                    constraint: "file_format_rejected",
+                }));
             return ok({
                 path,
-                sourcePath: process.platform === "win32" ? candidate : canonical,
+                sourcePath,
                 ...bundle,
                 sha256: await sha256Handle(handle, path, metadata, signal),
                 kind: "executable",
@@ -97,16 +143,29 @@ export const parseBinaryTarget = async (input, options = {}) => {
     catch (cause) {
         if (cause instanceof AnalysisCancelledError)
             return err(cause);
+        if (signal?.aborted === true && cause === signal.reason)
+            return err(new AnalysisCancelledError("resolve_binary_target", { cause }));
         if (cause instanceof BinaryTargetError)
             return err(cause);
         if (!(cause instanceof Error))
             throw cause;
-        const code = filesystemErrorCode(cause);
-        if (code === undefined)
+        const failure = classifyBinaryTargetFilesystemFailure(candidate, cause);
+        if (failure === undefined)
             throw cause;
-        return err(new BinaryTargetError(candidate, targetFailureReason(code, cause.message), { cause }));
+        return err(failure);
     }
 };
+/** Classify a filesystem failure while reading a previously selected target. */
+export const classifyBinaryTargetFilesystemFailure = (path, cause) => {
+    if (!(cause instanceof Error))
+        return undefined;
+    const code = filesystemErrorCode(cause);
+    return code === undefined
+        ? undefined
+        : new BinaryTargetError(path, targetFailureReason(code, cause.message), {
+            cause,
+        });
+};
 const filesystemErrorCode = (cause) => {
     const code = Reflect.get(cause, "code");
     return typeof code === "string" ? code : undefined;
@@ -136,18 +195,28 @@ const throwIfTargetResolutionCancelled = (signal) => {
 const detectArtifactFormat = async (path, handle, signal) => {
     throwIfTargetResolutionCancelled(signal);
     const lower = path.toLowerCase();
-    const magic = Buffer.alloc(8);
+    const magic = Buffer.alloc(4096);
     const observed = await handle.read(magic, 0, magic.length, 0);
     throwIfTargetResolutionCancelled(signal);
+    if (observed.bytesRead >= 8 &&
+        magic.subarray(0, 8).equals(Buffer.from([0, 0x61, 0x73, 0x6d, 1, 0, 0, 0])))
+        throw new BinaryTargetError(path, "WebAssembly v1 artifacts are not supported by the native opening route", { constraint: "wasm_requires_static_inspection" });
     if (hasZipSignature(magic.subarray(0, observed.bytesRead))) {
+        // The HarmonyOS App Pack suffix `.app` is a root-input concept; a nested
+        // ZIP member ending in `.app` keeps the generic zip classification.
+        if (lower.endsWith(".app"))
+            return "app-pack";
         return zipPackageFormatForPath(lower) ?? "zip";
     }
+    // Binary plists, including keyed archives, often use other extensions.
+    if (hasBinaryPlistSignature(magic.subarray(0, observed.bytesRead)))
+        return "plist";
     const named = namedArtifactFormat(lower);
     if (named !== undefined)
         return named;
     if (lower.endsWith(".pkg") &&
         observed.bytesRead >= 4 &&
-        magic.subarray(0, 4).toString("ascii") === "xar!")
+        magic.subarray(0, 4).equals(Buffer.from("xar!")))
         return "pkg";
     if (lower.endsWith(".dmg")) {
         throwIfTargetResolutionCancelled(signal);
@@ -157,10 +226,35 @@ const detectArtifactFormat = async (path, handle, signal) => {
             const trailer = Buffer.alloc(4);
             const read = await handle.read(trailer, 0, trailer.length, size - 512);
             throwIfTargetResolutionCancelled(signal);
-            if (read.bytesRead === 4 && trailer.toString("ascii") === "koly")
+            if (read.bytesRead === 4 && trailer.equals(Buffer.from("koly")))
                 return "dmg";
         }
     }
+    // XML property lists can use archive-specific suffixes such as .archive.
+    // The named-format check above keeps .js, .map, and .asar classifications.
+    const xmlProbe = createXmlPlistSignatureProbe();
+    let xmlState = xmlProbe.write(magic.subarray(0, observed.bytesRead));
+    if (xmlState === "matched")
+        return "plist";
+    const chunk = Buffer.alloc(XML_PLIST_PROBE_CHUNK_BYTES);
+    let bytesRead = observed.bytesRead;
+    while (xmlState === "pending" && bytesRead < MAX_XML_PLIST_PROBE_BYTES) {
+        throwIfTargetResolutionCancelled(signal);
+        const read = await handle.read(chunk, 0, Math.min(chunk.length, MAX_XML_PLIST_PROBE_BYTES - bytesRead), bytesRead);
+        throwIfTargetResolutionCancelled(signal);
+        if (read.bytesRead === 0)
+            break;
+        bytesRead += read.bytesRead;
+        xmlState = xmlProbe.write(chunk.subarray(0, read.bytesRead));
+        if (xmlState === "matched")
+            return "plist";
+    }
+    if (bytesRead === MAX_XML_PLIST_PROBE_BYTES) {
+        const { size } = await handle.stat();
+        throwIfTargetResolutionCancelled(signal);
+        if (size > bytesRead)
+            throw new BinaryTargetError(path, "XML plist prolog was not found within the 1 MiB format probe limit", { constraint: "file_format_rejected" });
+    }
     return undefined;
 };
 const namedArtifactFormat = (lowerPath) => {
@@ -172,7 +266,7 @@ const namedArtifactFormat = (lowerPath) => {
         return "source-map";
     return /\.(?:m?js|cjs)$/u.test(lowerPath) ? "javascript" : undefined;
 };
-const isArchiveFormat = (format) => ["zip", "ipa", "apk", "msix", "appx", "asar", "dmg", "pkg"].includes(format);
+const isArchiveFormat = (format) => isZipPackageFormat(format) || ["asar", "dmg", "pkg"].includes(format);
 const sha256Handle = async (handle, path, initial, signal) => {
     const hash = createHash("sha256");
     const chunk = Buffer.allocUnsafe(64 * 1024);
@@ -217,11 +311,20 @@ const readExecutableMetadata = async (handle, hostArchitecture, signal) => {
     const fileSize = (await handle.stat()).size;
     throwIfTargetResolutionCancelled(signal);
     if (bytes.length >= 2 && bytes[0] === 0x4d && bytes[1] === 0x5a) {
-        const offset = mzWindowsHeaderOffset(bytes);
-        if (offset !== null) {
-            if (offset < 64)
+        let windowsHeader = observeMzWindowsHeader(bytes, fileSize);
+        let signatureBytes;
+        if (windowsHeader.state === "signature-needed") {
+            const { offset } = windowsHeader;
+            const signature = Buffer.alloc(Math.min(4, fileSize - offset));
+            const observedSignature = await handle.read(signature, 0, signature.length, offset);
+            throwIfTargetResolutionCancelled(signal);
+            signatureBytes = signature.subarray(0, observedSignature.bytesRead);
+            windowsHeader = observeMzWindowsHeader(bytes, fileSize, signatureBytes);
+        }
+        if (windowsHeader.state === "declared") {
+            if (windowsHeader.offset < 64)
                 return err("invalid Windows new-header offset in MZ image");
-            return readPeMetadata(handle, offset, signal);
+            return readPeMetadata(handle, windowsHeader.offset, bytes, fileSize, signal);
         }
         // MZ relocation records may extend past the initial probe; their format
         // bounds are at most 65535 records inside a 65535-paragraph header.
@@ -237,7 +340,7 @@ const readExecutableMetadata = async (handle, hostArchitecture, signal) => {
             throwIfTargetResolutionCancelled(signal);
             return parseExecutableHeader(table.subarray(0, observed.bytesRead), hostArchitecture, fileSize);
         }
-        return parseExecutableHeader(bytes, hostArchitecture, fileSize);
+        return parseExecutableHeader(bytes, hostArchitecture, fileSize, signatureBytes);
     }
     if (bytes.length >= 8) {
         const magic = bytes.readUInt32BE(0);
@@ -258,37 +361,91 @@ const readExecutableMetadata = async (handle, hostArchitecture, signal) => {
         parsed.value.architecture !== "mips" ||
         parsed.value.mips.elfClass !== 32)
         return parsed;
-    const abiFlags = await readMipsElfAbiFlags(handle, parsed.value.mips, () => throwIfTargetResolutionCancelled(signal));
-    if (!abiFlags.ok)
-        return abiFlags;
+    const declarations = await readMipsElfMetadata(handle, parsed.value.mips, () => throwIfTargetResolutionCancelled(signal));
+    if (!declarations.ok)
+        return declarations;
     return ok({
         ...parsed.value,
         mips: {
             ...parsed.value.mips,
-            abiFlags: abiFlags.value.abiFlags,
-            ...(abiFlags.value.limitations.length === 0
+            abiFlags: declarations.value.abiFlags,
+            gnuAttributes: declarations.value.gnuAttributes,
+            ...(declarations.value.sharedLoad === undefined
+                ? {}
+                : { sharedLoad: declarations.value.sharedLoad }),
+            ...(declarations.value.limitations.length === 0
                 ? {}
-                : { limitations: abiFlags.value.limitations }),
+                : { limitations: declarations.value.limitations }),
         },
     });
 };
-const readPeMetadata = async (handle, offset, signal) => {
+const readPeMetadata = async (handle, offset, mzPrefix, fileSize, signal) => {
     throwIfTargetResolutionCancelled(signal);
     const fileHeader = Buffer.alloc(24);
     const fileHeaderRead = await handle.read(fileHeader, 0, fileHeader.length, offset);
     throwIfTargetResolutionCancelled(signal);
     if (fileHeaderRead.bytesRead !== fileHeader.length)
         return err("invalid or truncated PE header");
-    const signature = fileHeader.toString("ascii", 0, 2);
-    if (["NE", "LE", "LX"].includes(signature))
-        return err(`unsupported ${signature} executable in MZ image`);
+    const windowsHeader = observeMzWindowsHeader(mzPrefix, fileSize, fileHeader.subarray(0, 4));
+    if (windowsHeader.state !== "declared")
+        return err("invalid Windows new-header signature in MZ image");
+    if (["NE", "LE", "LX"].includes(windowsHeader.signature))
+        return err(`unsupported ${windowsHeader.signature} executable in MZ image`);
     const optionalHeaderSize = fileHeader.readUInt16LE(20);
     if (optionalHeaderSize > 4096)
         return err("invalid PE optional header size");
+    const numberOfSections = fileHeader.readUInt16LE(6);
     const record = Buffer.alloc(24 + optionalHeaderSize);
     const recordRead = await handle.read(record, 0, record.length, offset);
     throwIfTargetResolutionCancelled(signal);
-    return recordRead.bytesRead === record.length
-        ? parsePeRecord(record)
-        : err("invalid or truncated PE header");
+    if (recordRead.bytesRead !== record.length)
+        return err("invalid or truncated PE header");
+    const codeView = await readPeCodeView(handle, offset, numberOfSections, record.subarray(24), optionalHeaderSize, signal);
+    return parsePeRecord(record, codeView);
+};
+const readPeCodeView = async (handle, peOffset, numberOfSections, optionalHeader, optionalHeaderSize, signal) => {
+    throwIfTargetResolutionCancelled(signal);
+    const debugDir = peDebugDirectoryEntry(optionalHeader);
+    if (debugDir === undefined || numberOfSections > 96)
+        return undefined;
+    const sectionTableOffset = peOffset + 24 + optionalHeaderSize;
+    const sectionTableSize = numberOfSections * 40;
+    const sectionTable = Buffer.alloc(sectionTableSize);
+    const sectionRead = await handle.read(sectionTable, 0, sectionTableSize, sectionTableOffset);
+    throwIfTargetResolutionCancelled(signal);
+    if (sectionRead.bytesRead !== sectionTableSize)
+        return undefined;
+    const debugFileOffset = peRvaToFileOffset(debugDir.debugRva, sectionTable, numberOfSections, debugDir.sizeOfHeaders, Math.min(debugDir.debugSize, 4096));
+    if (debugFileOffset === undefined)
+        return undefined;
+    const maxDebugSize = Math.min(debugDir.debugSize, 4096);
+    const debugDirectoryBuffer = Buffer.alloc(maxDebugSize);
+    const debugDirRead = await handle.read(debugDirectoryBuffer, 0, maxDebugSize, debugFileOffset);
+    throwIfTargetResolutionCancelled(signal);
+    const numEntries = Math.floor(debugDirRead.bytesRead / 28);
+    for (let j = 0; j < numEntries; j++) {
+        const entryOffset = j * 28;
+        const type = debugDirectoryBuffer.readUInt32LE(entryOffset + 12);
+        if (type !== 2)
+            continue; // IMAGE_DEBUG_TYPE_CODEVIEW
+        const sizeOfData = debugDirectoryBuffer.readUInt32LE(entryOffset + 16);
+        let pointerToRawData = debugDirectoryBuffer.readUInt32LE(entryOffset + 24);
+        if (pointerToRawData === 0) {
+            const addressOfRawData = debugDirectoryBuffer.readUInt32LE(entryOffset + 20);
+            const mapped = peRvaToFileOffset(addressOfRawData, sectionTable, numberOfSections, debugDir.sizeOfHeaders, Math.min(sizeOfData, 4096));
+            if (mapped === undefined)
+                continue;
+            pointerToRawData = mapped;
+        }
+        if (sizeOfData < 16)
+            continue;
+        const maxCodeViewRead = Math.min(sizeOfData, 4096);
+        const codeViewBuffer = Buffer.alloc(maxCodeViewRead);
+        const codeViewRead = await handle.read(codeViewBuffer, 0, maxCodeViewRead, pointerToRawData);
+        throwIfTargetResolutionCancelled(signal);
+        const parsed = parseCodeViewData(codeViewBuffer.subarray(0, codeViewRead.bytesRead), sizeOfData);
+        if (parsed !== undefined)
+            return parsed;
+    }
+    return undefined;
 };

package/dist/application/BrowserEvidence.js

@@ -53,7 +53,7 @@ const browserParameters = (input, result) => {
     }
     const observedOrigin = browserResultTargetOrigin(result);
     const scope = {
-        cdp_endpoint: input.cdp_endpoint,
+        cdp_endpoint: input.cdp_endpoint.recorded,
         allowed_origins: input.allowed_origins.length > 0
             ? input.allowed_origins
             : "target_id" in input && observedOrigin !== undefined

package/dist/application/BrowserObservationService.js

@@ -1,5 +1,4 @@
-import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
-import {} from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
 import { err, ok } from "../domain/result.js";
 import { createBrowserEvidence } from "./BrowserEvidence.js";
 /** List browser targets within the endpoint and origin scope in the request. */
@@ -8,6 +7,8 @@ export const listBrowserTargets = async (browser, input, options = {}) => {
     if (!ready.ok)
         return ready;
     const result = await ready.value.listTargets(input, options);
+    if (result.ok && options.signal?.aborted === true)
+        return err(new AnalysisCancelledError("list_browser_targets"));
     return result.ok
         ? ok(createBrowserEvidence("list_browser_targets", input, result.value, ready.value.identity()))
         : result;
@@ -18,6 +19,8 @@ export const inspectWebPage = async (browser, input, options = {}) => {
     if (!ready.ok)
         return ready;
     const result = await ready.value.inspectPage(input, options);
+    if (result.ok && options.signal?.aborted === true)
+        return err(new AnalysisCancelledError("inspect_web_page"));
     return result.ok
         ? ok(createBrowserEvidence("inspect_web_page", input, result.value, ready.value.identity()))
         : result;
@@ -28,6 +31,8 @@ export const analyzeWebBundle = async (browser, input, options = {}) => {
     if (!ready.ok)
         return ready;
     const analyzed = await ready.value.analyzeBundle(input, options);
+    if (analyzed.ok && options.signal?.aborted === true)
+        return err(new AnalysisCancelledError("analyze_web_bundle"));
     if (!analyzed.ok)
         return analyzed;
     return ok(createBrowserEvidence("analyze_web_bundle", input, analyzed.value, ready.value.identity()));
@@ -38,6 +43,8 @@ export const observeWebSession = async (browser, input, options = {}) => {
     if (!ready.ok)
         return ready;
     const observed = await ready.value.observeSession(input, options);
+    if (observed.ok && options.signal?.aborted === true)
+        return err(new AnalysisCancelledError("observe_web_session"));
     return observed.ok
         ? ok(createBrowserEvidence("observe_web_session", input, observed.value, ready.value.identity()))
         : observed;
@@ -48,6 +55,8 @@ export const discoverWebMcpTools = async (browser, input, options = {}) => {
     if (!ready.ok)
         return ready;
     const discovered = await ready.value.discoverWebMcpTools(input, options);
+    if (discovered.ok && options.signal?.aborted === true)
+        return err(new AnalysisCancelledError("discover_webmcp_tools"));
     return discovered.ok
         ? ok(createBrowserEvidence("discover_webmcp_tools", input, discovered.value, ready.value.identity()))
         : discovered;
@@ -68,6 +77,8 @@ export const captureWebScreenshot = async (browser, input, options = {}) => {
     if (!ready.ok)
         return ready;
     const captured = await ready.value.captureScreenshot(input, options);
+    if (captured.ok && options.signal?.aborted === true)
+        return err(new AnalysisCancelledError("capture_web_screenshot"));
     return captured.ok
         ? ok(createBrowserEvidence("capture_web_screenshot", input, captured.value, ready.value.identity()))
         : captured;

package/dist/application/BrowserScenarioCaptureService.js

@@ -1,6 +1,5 @@
 import { createBrowserScenarioEvidence } from "./BrowserScenarioEvidence.js";
 import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
-import {} from "../domain/analysisErrorBase.js";
 import { err } from "../domain/result.js";
 const OPERATION = "capture_browser_scenario";
 const PROVIDER_ID = "rea-playwright-browser-scenario";

package/dist/application/CallPathTracing.js

@@ -1,10 +1,10 @@
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
-import {} from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { parseRelatedAddresses } from "../domain/hopperValues.js";
-import { ok } from "../domain/result.js";
+import { err, ok } from "../domain/result.js";
 import { resolveProcedureAddress } from "./ProcedureAddressResolution.js";
 /** Trace direct caller/callee relationships until the graph is exhausted or the goal is reached. */
-export const traceCallPath = async (call, input, signal) => {
+export const traceCallPath = async (call, callRelationship, input, signal) => {
     const start = await resolveProcedureAddress(call, input.start, signal);
     if (!start.ok)
         return start;
@@ -20,25 +20,33 @@ export const traceCallPath = async (call, input, signal) => {
         ...(goal === undefined ? {} : { goal }),
         direction: input.direction,
     };
+    if (isAborted(signal))
+        return err(new AnalysisCancelledError("trace_call_path"));
     const state = createTraceState(resolvedInput);
     while (state.queueIndex < state.queue.length &&
         state.traversalPath.length === 0) {
+        if (isAborted(signal))
+            return err(new AnalysisCancelledError("trace_call_path"));
         const address = state.queue[state.queueIndex++];
         if (address === undefined)
             break;
         const current = state.visited.get(address);
         if (current === undefined)
             continue;
-        const found = await expandAddress(call, {
+        const expanded = await expandAddress(callRelationship, {
             input: resolvedInput,
             state,
             address,
             current,
             ...(signal === undefined ? {} : { signal }),
         });
-        if (found)
+        if (!expanded.ok)
+            return expanded;
+        if (expanded.value)
             break;
     }
+    if (isAborted(signal))
+        return err(new AnalysisCancelledError("trace_call_path"));
     return ok(projectTrace(resolvedInput, state));
 };
 const createTraceState = (input) => ({
@@ -47,6 +55,8 @@ const createTraceState = (input) => ({
     edges: new Map(),
     failures: [],
     residual: new Set(),
+    limitations: new Set(),
+    relationshipCoverage: new Map(),
     queueIndex: 0,
     traversalPath: input.goal === input.start ? [input.start] : [],
 });
@@ -54,24 +64,48 @@ const expandAddress = async (call, expansion) => {
     const { input, state, address, current, signal } = expansion;
     const relation = input.direction === "forward" ? "callees" : "callers";
     const tool = input.direction === "forward" ? "procedure_callees" : "procedure_callers";
-    const result = await call(tool, { procedure: address }, signal);
+    const result = await call(tool, { procedure: address }, signal, "provider");
+    if (!result.ok) {
+        if (result.error._tag === "AnalysisCancelledError" ||
+            signal?.aborted === true)
+            return result;
+    }
+    if (isAborted(signal))
+        return err(new AnalysisCancelledError("trace_call_path"));
     if (!result.ok) {
         state.failures.push({
             address,
             error: projectAnalysisError(result.error),
         });
         state.residual.add(`Call relationships were unavailable for ${address}.`);
-        return false;
+        return ok(false);
     }
-    const related = parseRelatedAddresses(result.value, relation);
+    const related = parseRelatedAddresses(result.value.result, relation, tool);
     if (!related.ok) {
         state.failures.push({
             address,
             error: projectAnalysisError(related.error),
         });
         state.residual.add(`Call relationships were unreadable for ${address}.`);
-        return false;
+        return ok(false);
     }
+    for (const limitation of result.value.limitations)
+        state.limitations.add(limitation);
+    const coverage = result.value.relationshipCoverage ?? {
+        status: "unknown",
+        reason: "Provider did not report relationship coverage.",
+    };
+    state.relationshipCoverage.set(address, coverage);
+    for (const diagnostic of "diagnostics" in coverage &&
+        Array.isArray(coverage.diagnostics)
+        ? coverage.diagnostics
+        : [])
+        state.limitations.add(diagnostic);
+    if (coverage.status === "partial")
+        for (const limitation of coverage.limitations)
+            state.residual.add(`Call relationships for ${address} are limited: ${limitation}`);
+    else if (coverage.status === "unknown")
+        state.residual.add(`Call relationship coverage is unknown for ${address}: ${coverage.reason}`);
     for (const relatedAddress of sortedUniqueAddresses(related.value)) {
         recordEdge(input, state, {
             address,
@@ -85,7 +119,7 @@ const expandAddress = async (call, expansion) => {
         if (state.visited.has(relatedAddress)) {
             if (relatedAddress === input.goal) {
                 state.traversalPath = path;
-                return true;
+                return ok(true);
             }
             continue;
         }
@@ -95,11 +129,11 @@ const expandAddress = async (call, expansion) => {
         });
         if (relatedAddress === input.goal) {
             state.traversalPath = path;
-            return true;
+            return ok(true);
         }
         state.queue.push(relatedAddress);
     }
-    return false;
+    return ok(false);
 };
 const recordEdge = (input, state, edge) => {
     const sourceAddress = input.direction === "forward" ? edge.address : edge.relatedAddress;
@@ -121,7 +155,9 @@ const projectTrace = (input, state) => ({
         ? "not_requested"
         : state.traversalPath.length > 0
             ? "reached"
-            : "not_reached",
+            : state.residual.size > 0
+                ? "unknown"
+                : "not_reached",
     nodes: [...state.visited.entries()]
         .map(([address, { depth }]) => ({ address, depth }))
         .sort((left, right) => left.depth - right.depth || compareAddress(left.address, right.address)),
@@ -133,11 +169,14 @@ const projectTrace = (input, state) => ({
     traversal: {
         nodes_visited: state.visited.size,
     },
+    relationship_coverage: Object.fromEntries([...state.relationshipCoverage.entries()].sort(([left], [right]) => compareAddress(left, right))),
     truncated: state.residual.size > 0,
     residual_unknowns: [...state.residual],
     limitations: [
         "Direct provider call relationships may omit unresolved indirect calls.",
+        ...state.limitations,
     ],
 });
 const compareAddress = (left, right) => left < right ? -1 : left > right ? 1 : 0;
 const sortedUniqueAddresses = (addresses) => [...new Set(addresses)].sort(compareAddress);
+const isAborted = (signal) => signal?.aborted === true;