rea-agents 5.0.0 → 6.1.0

package/dist/application/javascript/JavaScriptSemanticGraphProjection.js

@@ -1,18 +1,124 @@
 import { compareCodePoints } from "../../domain/canonicalOrdering.js";
 import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES } from "../../domain/javascript/javascriptSemanticGraphSchemas.js";
-/** Find the innermost callable that contains one exact source range. */
-export const owningSemanticCallableNode = (location, ir, nodes) => {
-    if (location === null)
-        return undefined;
-    return ir.callables
-        .filter((callable) => contains(callable.location, location))
-        .sort((left, right) => compareCodePoints(positionKey(right.location), positionKey(left.location)))
-        .map(({ callableId }) => nodes.get(callableId))
-        .find((node) => node !== undefined);
+/** Index one immutable file IR; read retained callable membership at query time. */
+export const createSemanticCallableOwnerLookup = (ir, nodes) => {
+    const entries = ir.callables
+        .map((callable, order) => ({
+        callableId: callable.callableId,
+        range: callable.location,
+        order,
+        priority: positionKey(callable.location),
+    }))
+        .sort((left, right) => pointCompare(left.range.start, right.range.start) ||
+        left.order - right.order);
+    const tree = buildSourceIntervalTree(entries, 0, entries.length);
+    return (location) => {
+        if (location === null || tree === null || nodes.size === 0)
+            return undefined;
+        const pending = [tree];
+        let best;
+        let result;
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (current === undefined ||
+                pointCompare(current.minimumStart, location.start) > 0 ||
+                pointCompare(current.maximumEnd, location.end) < 0)
+                continue;
+            const candidate = current.entry;
+            if (contains(candidate.range, location)) {
+                const node = nodes.get(candidate.callableId);
+                const rank = best === undefined
+                    ? 1
+                    : compareCodePoints(candidate.priority, best.priority) ||
+                        best.order - candidate.order;
+                if (node !== undefined && rank > 0) {
+                    best = candidate;
+                    result = node;
+                }
+            }
+            if (current.left !== null)
+                pending.push(current.left);
+            if (current.right !== null)
+                pending.push(current.right);
+        }
+        return result;
+    };
 };
-/** Find retained semantic nodes whose exact ranges are within one expression. */
-export const semanticNodesWithinRange = (nodes, range) => nodes.filter((node) => node.identity.source_range !== null &&
-    contains(range, node.identity.source_range));
+const buildSourceIntervalTree = (entries, start, end) => {
+    if (start >= end)
+        return null;
+    const middle = Math.floor((start + end) / 2);
+    const entry = entries[middle];
+    if (entry === undefined)
+        return null;
+    // This recursion follows a balanced index, not the producer's nesting depth.
+    const left = buildSourceIntervalTree(entries, start, middle);
+    const right = buildSourceIntervalTree(entries, middle + 1, end);
+    let minimumEnd = entry.range.end;
+    let maximumEnd = entry.range.end;
+    for (const child of [left, right]) {
+        if (child !== null && pointCompare(child.minimumEnd, minimumEnd) < 0)
+            minimumEnd = child.minimumEnd;
+        if (child !== null && pointCompare(child.maximumEnd, maximumEnd) > 0)
+            maximumEnd = child.maximumEnd;
+    }
+    return {
+        entry,
+        minimumStart: left?.minimumStart ?? entry.range.start,
+        maximumStart: right?.maximumStart ?? entry.range.start,
+        minimumEnd,
+        maximumEnd,
+        left,
+        right,
+    };
+};
+/** Index an immutable node list; return contained ranges in producer order. */
+export const createSemanticNodeRangeLookup = (nodes) => {
+    const entries = nodes
+        .flatMap((node, order) => {
+        const range = node.identity.source_range;
+        return range === null ? [] : [{ node, range, order }];
+    })
+        .sort((left, right) => pointCompare(left.range.start, right.range.start) ||
+        left.order - right.order);
+    const tree = buildSourceIntervalTree(entries, 0, entries.length);
+    return (range) => {
+        if (tree === null)
+            return [];
+        const pending = [tree];
+        const matches = [];
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (current === undefined ||
+                pointCompare(current.maximumStart, range.start) < 0 ||
+                pointCompare(current.minimumEnd, range.end) > 0)
+                continue;
+            if (contains(range, current.entry.range))
+                matches.push(current.entry);
+            if (current.left !== null)
+                pending.push(current.left);
+            if (current.right !== null)
+                pending.push(current.right);
+        }
+        return matches
+            .sort((left, right) => left.order - right.order)
+            .map(({ node }) => node);
+    };
+};
+/** Index exact call ranges, preserving the first producer occurrence. */
+export const createSemanticCallSiteLookup = (ir, nodes) => {
+    const identifiers = new Map();
+    for (const call of ir.callSites) {
+        const key = rangeKey(call.location);
+        if (!identifiers.has(key))
+            identifiers.set(key, call.callSiteId);
+    }
+    return (range) => {
+        const identifier = identifiers.get(rangeKey(range));
+        return identifier === undefined ? undefined : nodes.get(identifier);
+    };
+};
+const rangeKey = (range) => `${range.start.line}:${range.start.column}-${range.end.line}:${range.end.column}`;
 /** Report extractor support without treating missing families as absence. */
 export const semanticFamilyStatus = (family, analysis) => {
     if (![

package/dist/application/javascript/JavaScriptSemanticGraphResourceProjection.js

@@ -1,5 +1,5 @@
 import { createJavaScriptSemanticGraphUnknown } from "../../domain/javascript/javascriptSemanticGraph.js";
-import { addSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, constructSemanticGraphNode, } from "./JavaScriptSemanticGraphConstruction.js";
+import { retainSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
 import { unknownSemanticEvidence } from "./JavaScriptSemanticGraphEvidence.js";
 import { semanticCallSiteAt, } from "./JavaScriptSemanticGraphFlowProjection.js";
 /** Project built-in resource acquisition and exact local release handles. */
@@ -21,7 +21,7 @@ export const projectSemanticResources = (context) => {
         else
             projectRelease(context, operation, resourceNodes);
 };
-const addResourceNode = (context, operation) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+const addResourceNode = (context, operation) => retainSemanticGraphNode(context.state, context.file, {
     kind: "resource",
     roleKey: operation.resourceId,
     location: operation.location,
@@ -31,7 +31,7 @@ const addResourceNode = (context, operation) => addSemanticGraphNode(context.sta
         : (context.callableNodes.get(operation.ownerCallableId)?.node_id ??
             null),
     properties: { method: operation.method },
-}, context.state));
+});
 const projectRelease = (context, operation, resourceNodes) => {
     const callSite = semanticCallSiteAt(context, operation.location);
     const resources = operation.linkedResourceIds.flatMap((identifier) => {

package/dist/application/javascript/JavaScriptSemanticGraphValueProjection.js

@@ -1,4 +1,6 @@
-import { addSemanticGraphNode, addSemanticGraphRelation, constructSemanticGraphNode, } from "./JavaScriptSemanticGraphConstruction.js";
+import { createJavaScriptSemanticGraphUnknown } from "../../domain/javascript/javascriptSemanticGraph.js";
+import { retainSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
+import { observedSemanticEvidence } from "./JavaScriptSemanticGraphEvidence.js";
 /** Project bounded literal values and object slots for exact query seeds. */
 export const projectSemanticValues = (context) => {
     for (const binding of context.ir.bindings) {
@@ -54,17 +56,37 @@ const projectValue = (input) => {
                 role: `property:${property.name}`,
             });
         }
+    else if (value.status === "unknown" && value.resourceLimit !== undefined) {
+        const location = binding.definitions[0]?.location ?? null;
+        const evidence = observedSemanticEvidence(context.file, location);
+        const isPropertyValue = role.startsWith("property:");
+        addSemanticGraphUnknown(context.state, createJavaScriptSemanticGraphUnknown({
+            node_id: target.node_id,
+            family: isPropertyValue ? "object-flow" : "data-flow",
+            relation_kinds: [isPropertyValue ? "writes-property" : "defines"],
+            reason: "resource-limit",
+            detail: `${value.reason} Unknown value at ${role}.`,
+            candidate_node_ids: [target.node_id],
+            evidence: {
+                ...evidence,
+                authority: "unknown",
+                state: "unknown",
+                confidence: "unknown",
+                limitations: [value.reason],
+            },
+        }));
+    }
 };
-const addLiteralNode = (context, binding, value, role) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+const addLiteralNode = (context, binding, value, role) => retainSemanticGraphNode(context.state, context.file, {
     kind: "literal",
     roleKey: `literal:${binding.bindingId}:${role}:${JSON.stringify(value)}`,
     location: binding.definitions[0]?.location ?? null,
     label: JSON.stringify(value),
     functionNodeId: context.bindingNodes.get(binding.bindingId)?.function_node_id ?? null,
     properties: { value },
-}, context.state));
+});
 /** Create one canonical property slot for a binding/property identity. */
-export const semanticPropertySlot = (context, objectBindingId, name) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+export const semanticPropertySlot = (context, objectBindingId, name) => retainSemanticGraphNode(context.state, context.file, {
     kind: "property-slot",
     roleKey: `property:${objectBindingId}:${name}`,
     location: null,
@@ -74,4 +96,4 @@ export const semanticPropertySlot = (context, objectBindingId, name) => addSeman
         name,
         object_binding_id: objectBindingId,
     },
-}, context.state));
+});

package/dist/application/managed/ManagedApplicationGraphService.js

@@ -1,24 +1,25 @@
 import { z } from "zod";
-import { AnalysisInputError, AnalysisProtocolError, } from "../../domain/analysisErrorCore.js";
+import { AnalysisProtocolError } from "../../domain/analysisErrorCore.js";
 import {} from "../../domain/analysisErrorBase.js";
 import { createEvidence } from "../../domain/evidence.js";
 import { jsonValueSchema } from "../../domain/jsonValue.js";
 import { managedApplicationGraphResultSchema, projectManagedApplicationGraph, projectManagedApplicationGraphInputSchema, } from "../../domain/managed/managedApplicationGraph.js";
 import { err, ok } from "../../domain/result.js";
 import { MANAGED_WORKFLOW_PROVIDER } from "../InvestigationProviders.js";
+import { requestInputError, workflowInputError, } from "../workflowInputError.js";
 const OPERATION = "project_managed_application_graph";
 /** Project authenticated managed Evidence into a provider-neutral graph. */
 export const projectManagedApplicationGraphEvidence = (rawInput) => {
     const parsed = projectManagedApplicationGraphInputSchema.safeParse(rawInput);
     if (!parsed.success)
-        return err(new AnalysisInputError(OPERATION, { cause: parsed.error }));
+        return err(requestInputError(OPERATION, parsed.error, rawInput));
     try {
         const result = projectManagedApplicationGraph(parsed.data);
         return ok(createManagedApplicationGraphEvidence(parsed.data, result));
     }
     catch (cause) {
         return err(cause instanceof TypeError || cause instanceof z.ZodError
-            ? new AnalysisInputError(OPERATION, { cause })
+            ? workflowInputError(OPERATION, cause)
             : new AnalysisProtocolError("Managed application graph projection produced an invalid result", { cause }));
     }
 };

package/dist/application/managed/ManagedMemberComparisonService.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { z } from "zod";
 import { compareManagedMembers, managedMemberComparisonResultSchema, parseManagedMemberEvidence, } from "../../domain/managed/managedMemberComparison.js";
-import { AnalysisInputError, AnalysisProtocolError, } from "../../domain/analysisErrorCore.js";
+import { AnalysisProtocolError } from "../../domain/analysisErrorCore.js";
 import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
 import {} from "../../domain/analysisErrorBase.js";
 import { createEvidence } from "../../domain/evidence.js";
@@ -11,6 +11,7 @@ import { parseBinaryTarget } from "../BinaryTargetResolver.js";
 import { err, ok } from "../../domain/result.js";
 import { inspectManagedMembersBytes } from "../../dotnet/ManagedMemberInspector.js";
 import { MANAGED_STATIC_PROVIDER, MANAGED_WORKFLOW_PROVIDER, } from "../InvestigationProviders.js";
+import { workflowInputError } from "../workflowInputError.js";
 /** Compare managed members from input parsed by a trusted adapter. */
 export const compareManagedMembersEvidenceValidated = (input) => {
     const operation = "compare_managed_members";
@@ -36,10 +37,12 @@ export const compareManagedMemberPaths = async (input, dependencies = DEFAULT_PA
             dependencies.resolveTarget(input.leftPath),
             dependencies.resolveTarget(input.rightPath),
         ]);
+        // Report an unopenable path like every other path-based command does,
+        // with the failed path and constraint, rather than a bare input error.
         if (!leftTarget.ok)
-            return err(new AnalysisInputError(operation, { cause: leftTarget.error }));
+            return err(leftTarget.error);
         if (!rightTarget.ok)
-            return err(new AnalysisInputError(operation, { cause: rightTarget.error }));
+            return err(rightTarget.error);
         const [leftBytes, rightBytes] = await Promise.all([
             dependencies.readBytes(leftTarget.value.path),
             dependencies.readBytes(rightTarget.value.path),
@@ -103,5 +106,5 @@ const createManagedMemberComparisonEvidence = (parameters, result) => createEvid
     evidenceLinks: result.evidence_links,
 });
 const workflowFailure = (operation, cause) => err(cause instanceof z.ZodError || cause instanceof TypeError
-    ? new AnalysisInputError(operation, { cause })
+    ? workflowInputError(operation, cause)
     : new AnalysisProtocolError("Managed member comparison produced an invalid result", { cause }));

package/dist/application/managed/ManagedNativeVerificationService.js

@@ -1,24 +1,25 @@
 import { z } from "zod";
-import { AnalysisInputError, AnalysisProtocolError, } from "../../domain/analysisErrorCore.js";
+import { AnalysisProtocolError } from "../../domain/analysisErrorCore.js";
 import {} from "../../domain/analysisErrorBase.js";
 import { createEvidence } from "../../domain/evidence.js";
 import { jsonValueSchema } from "../../domain/jsonValue.js";
 import { managedNativeVerificationInputSchema, verifyManagedNativeBoundaries, } from "../../domain/managed/managedNativeVerification.js";
 import { err, ok } from "../../domain/result.js";
 import { MANAGED_WORKFLOW_PROVIDER } from "../InvestigationProviders.js";
+import { requestInputError, workflowInputError, } from "../workflowInputError.js";
 const OPERATION = "verify_managed_native_boundaries";
 /** Verify managed/native boundary declarations against native Evidence. */
 export const verifyManagedNativeBoundariesEvidence = (rawInput) => {
     const parsed = managedNativeVerificationInputSchema.safeParse(rawInput);
     if (!parsed.success)
-        return err(new AnalysisInputError(OPERATION, { cause: parsed.error }));
+        return err(requestInputError(OPERATION, parsed.error, rawInput));
     try {
         const result = verifyManagedNativeBoundaries(parsed.data);
         return ok(createManagedNativeVerificationEvidence(parsed.data, result));
     }
     catch (cause) {
         return err(cause instanceof TypeError || cause instanceof z.ZodError
-            ? new AnalysisInputError(OPERATION, { cause })
+            ? workflowInputError(OPERATION, cause)
             : new AnalysisProtocolError("Managed/native verification produced an invalid result", { cause }));
     }
 };

package/dist/application/managed/ManagedReconstructionService.js

@@ -1,17 +1,18 @@
 import { z } from "zod";
-import { AnalysisInputError, AnalysisProtocolError, } from "../../domain/analysisErrorCore.js";
+import { AnalysisProtocolError } from "../../domain/analysisErrorCore.js";
 import {} from "../../domain/analysisErrorBase.js";
 import { createEvidence } from "../../domain/evidence.js";
 import { jsonValueSchema } from "../../domain/jsonValue.js";
 import { importManagedReconstruction, managedReconstructionImportInputSchema, } from "../../domain/managed/managedReconstruction.js";
 import { err, ok } from "../../domain/result.js";
 import { MANAGED_WORKFLOW_PROVIDER } from "../InvestigationProviders.js";
+import { requestInputError, workflowInputError, } from "../workflowInputError.js";
 const OPERATION = "import_managed_reconstruction";
 /** Authenticate and import managed decompiler reconstruction as Evidence. */
 export const importManagedReconstructionEvidence = (rawInput) => {
     const parsed = managedReconstructionImportInputSchema.safeParse(rawInput);
     if (!parsed.success)
-        return err(new AnalysisInputError(OPERATION, { cause: parsed.error }));
+        return err(requestInputError(OPERATION, parsed.error, rawInput));
     return importManagedReconstructionEvidenceValidated(parsed.data);
 };
 /** Import reconstruction from input parsed by a trusted adapter. */
@@ -22,7 +23,7 @@ export const importManagedReconstructionEvidenceValidated = (input) => {
     }
     catch (cause) {
         return err(cause instanceof TypeError || cause instanceof z.ZodError
-            ? new AnalysisInputError(OPERATION, { cause })
+            ? workflowInputError(OPERATION, cause)
             : new AnalysisProtocolError("Managed reconstruction import produced an invalid result", { cause }));
     }
 };

package/dist/application/{ProcessCli.js → process/ProcessCli.js}

@@ -1,14 +1,16 @@
 import { readFile } from "node:fs/promises";
-import { AnalysisError } from "../domain/analysisErrorBase.js";
-import { AnalysisInputError } from "../domain/analysisErrorCore.js";
-import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
-import { createEvidence, parseEvidence } from "../domain/evidence.js";
-import { jsonValueSchema } from "../domain/jsonValue.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
-import { processTraceSpecificationSchema } from "../domain/processTraceComparison.js";
-import { processScenarioSchema } from "../domain/processScenario.js";
-import { compareProcessCaptures, parseProcessCapture, } from "../domain/processCapture.js";
-import { captureProcessScenario } from "./ProcessHarness.js";
+import { z } from "zod";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
+import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
+import { createEvidence, parseEvidence } from "../../domain/evidence.js";
+import { describeValidationFailure } from "../../domain/evidenceBundle.js";
+import { jsonValueSchema } from "../../domain/jsonValue.js";
+import { analysisInputErrorFromIssues, projectInputIssues, } from "../../domain/inputIssueProjection.js";
+import { processTraceSpecificationSchema } from "../../domain/process/processTraceComparison.js";
+import { processScenarioSchema } from "../../domain/process/processScenario.js";
+import { compareProcessCaptures, parseProcessCapture, } from "../../domain/process/processCapture.js";
+import { captureProcessScenario } from "../../process/capture/ProcessHarness.js";
 import { PROCESS_PROVIDER, createProcessCaptureEvidence, } from "./ProcessEvidence.js";
 /** Identify the process workflow's typed diagnostic result for CLI exit status. */
 export const isProcessCliFailure = (value) => typeof value === "object" &&
@@ -25,7 +27,7 @@ export const captureProcessScenarioFile = async (path, environment = process.env
         const input = await readJson(path);
         const parsed = processScenarioSchema.safeParse(input);
         if (!parsed.success)
-            throw new AnalysisInputError("capture_process_scenario", { cause: parsed.error }, projectInputIssues(parsed.error.issues, input));
+            throw analysisInputErrorFromIssues("capture_process_scenario", parsed.error.issues, input, { cause: parsed.error });
         const captured = await captureProcessScenario(parsed.data, undefined, process.platform, environment);
         if (!captured.ok)
             return cliAnalysisError(captured.error);
@@ -78,7 +80,9 @@ const parseCaptureEvidence = (input) => {
         evidence = parseEvidence(input);
     }
     catch (cause) {
-        throw invalidCaptureEvidence();
+        if (cause instanceof z.ZodError)
+            throw new AnalysisInputError("compare_process_captures", { cause }, projectInputIssues(cause.issues, input));
+        throw invalidCaptureEvidence(cause);
     }
     if (evidence.operation !== "capture_process_scenario" ||
         evidence.predicate_type !== "rea.process-capture" ||
@@ -94,16 +98,20 @@ const parseCaptureEvidence = (input) => {
         };
     }
     catch (cause) {
-        throw invalidCaptureEvidence();
+        throw invalidCaptureEvidence(cause);
     }
 };
 const parseTraceSpecification = (input) => {
     const parsed = processTraceSpecificationSchema.safeParse(input);
     if (parsed.success)
         return parsed.data;
-    throw new AnalysisInputError("compare-process-captures", { cause: parsed.error }, projectInputIssues(parsed.error.issues, input));
+    // Match the MCP boundary: the operation name and a trace_spec-rooted path.
+    throw new AnalysisInputError("compare_process_captures", { cause: parsed.error }, projectInputIssues(parsed.error.issues, input).map((issue) => ({
+        ...issue,
+        path: ["trace_spec", ...issue.path],
+    })));
 };
-const invalidCaptureEvidence = () => new ProcessCliFailure("invalid_input", "Capture evidence is malformed. Create new capture evidence, then try again.");
+const invalidCaptureEvidence = (cause) => new ProcessCliFailure("invalid_input", `Capture evidence is malformed (${describeValidationFailure(cause)}). Create new capture evidence, then try again.`);
 const readJson = async (path) => {
     let bytes;
     try {

package/dist/application/{ProcessEvidence.js → process/ProcessEvidence.js}

@@ -1,10 +1,11 @@
-import { createEvidence } from "../domain/evidence.js";
-import { PROCESS_PROVIDER } from "../domain/processEvidenceProvider.js";
-import { jsonValueSchema } from "../domain/jsonValue.js";
-export { PROCESS_PROVIDER } from "../domain/processEvidenceProvider.js";
+import { posix, win32 } from "node:path";
+import { createEvidence } from "../../domain/evidence.js";
+import { PROCESS_PROVIDER } from "../../domain/process/processEvidenceProvider.js";
+import { jsonValueSchema } from "../../domain/jsonValue.js";
+export { PROCESS_PROVIDER } from "../../domain/process/processEvidenceProvider.js";
 /** Project one process scenario into secret-free Evidence parameters. */
-const processEvidenceParameters = (scenario) => ({
-    executable_name: scenario.executable.split("/").at(-1) ?? scenario.executable,
+const processEvidenceParameters = (scenario, platform) => ({
+    executable_name: (platform === "win32" ? win32 : posix).basename(scenario.executable),
     argument_count: scenario.arguments.length,
     event_count: scenario.events.length,
     filesystem_observation_path_count: scenario.filesystem_observation_paths.length,
@@ -15,7 +16,7 @@ export const createProcessCaptureEvidence = (scenario, capture) => {
     return createEvidence(undefined, PROCESS_PROVIDER, {
         predicateType: "rea.process-capture",
         operation: "capture_process_scenario",
-        parameters: processEvidenceParameters(scenario),
+        parameters: processEvidenceParameters(scenario, capture.manifest.platform),
         result: jsonValueSchema.parse(capture),
         confidence: "observed",
         authority: "controlled-replay",

package/dist/application/workflowInputError.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
+/** Project schema issues of the raw request onto their request paths. */
+export const requestInputError = (operation, cause, input) => analysisInputErrorFromIssues(operation, cause.issues, input, { cause });
+/**
+ * Keep the failed constraint when a parsed request is rejected later. Nested
+ * values such as Evidence results are parsed on their own, so their issue
+ * paths are relative to that value and are reported in the message, not as
+ * request paths.
+ */
+export const workflowInputError = (operation, cause) => new AnalysisInputError(operation, { cause }, cause instanceof z.ZodError
+    ? cause.issues.map((issue) => ({
+        path: [],
+        reason: "invalid_value",
+        message: `A nested value failed validation at ${issue.path.length === 0 ? "its root" : issue.path.map(String).join(".")}: ${issue.message}`,
+    }))
+    : [{ path: [], reason: "invalid_value", message: cause.message }]);

package/dist/artifacts/ArtifactProvider.js

@@ -1,12 +1,13 @@
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
 import { inspectBundleKeyedArchive } from "./apple/KeyedArchiveReader.js";
+import { traceDylibResolution } from "./apple/DylibResolutionReader.js";
 import { basename, dirname } from "node:path";
-import { inventoryArtifact } from "../application/ArtifactInventory.js";
-import { extractArtifact } from "../application/ArtifactExtraction.js";
+import { inventoryArtifact } from "./inventory/ArtifactInventory.js";
+import { extractArtifact } from "./extraction/ArtifactExtraction.js";
 import { analyzeInterfaceBuilderBundle } from "./apple/InterfaceBuilderAnalysis.js";
 import { analyzeAppleAssetCatalogs } from "./apple/AppleAssetCatalogAnalysis.js";
 import { ARTIFACT_ANALYSIS_OPERATIONS, artifactInventoryInputSchema, artifactExtractionExecutionSchema, } from "../contracts/artifactToolContracts.js";
-import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+import { AnalysisCapabilityUnavailableError, AnalysisInputError, } from "../domain/analysisErrorCore.js";
 import { ArtifactOperationError } from "../domain/artifactOperationError.js";
 import {} from "../domain/analysisErrorBase.js";
 import { interfaceBuilderLimitsSchema } from "../domain/apple/interfaceBuilderGraph.js";
@@ -15,7 +16,7 @@ import { ArtifactReaderFailure } from "./ArtifactReader.js";
 import { ARTIFACT_PROVIDER_IDENTITY as IDENTITY, artifactCapabilities, } from "./ArtifactProviderMetadata.js";
 import { createEvidence } from "../domain/evidence.js";
 import { createArtifactInspection } from "../domain/artifactInspection.js";
-import { resolveArtifactIntegrityPolicy } from "../application/ArtifactInventory/policy.js";
+import { resolveArtifactIntegrityPolicy } from "./inventory/policy.js";
 /** Read-only inventory and exclusively owned extraction provider. */
 export class ArtifactProvider {
     #capabilities;
@@ -73,7 +74,14 @@ class ArtifactClient {
                     parameters.path !== undefined &&
                     parameters.path !== "." &&
                     parameters.path !== basename(this.target.path))
-                    throw new ArtifactReaderFailure("path", "For an active plist, path must select that archive (omit path or use its basename)");
+                    throw new AnalysisInputError(operation, undefined, [
+                        {
+                            path: ["path"],
+                            reason: "invalid_value",
+                            message: "For an active plist, path must select that archive (omit path or use its basename).",
+                            expected: basename(this.target.path),
+                        },
+                    ]);
                 const bundlePath = standalone
                     ? dirname(this.target.path)
                     : this.target.sourcePath;
@@ -98,6 +106,8 @@ class ArtifactClient {
             if (operation === "inspect_asset_catalog") {
                 return await this.inspectAssetCatalog(parameters, options);
             }
+            if (operation === "trace_dylib_resolution")
+                return await this.traceDylibResolution(parameters, options);
             if (operation === "extract_artifact") {
                 const parsed = artifactExtractionExecutionSchema.parse(parameters);
                 const result = await extractArtifact({
@@ -154,6 +164,30 @@ class ArtifactClient {
             })),
         }));
     }
+    async traceDylibResolution(parameters, options) {
+        if (this.target.kind !== "executable" || this.target.format !== "mach-o")
+            throw new ArtifactReaderFailure("unavailable", "trace_dylib_resolution requires an active Mach-O or .app bundle target");
+        // Only a target opened from an app bundle directory carries its Info.plist;
+        // a regular file whose name ends in .app is a standalone image.
+        const bundle = this.target.bundleInfoPlist === undefined
+            ? undefined
+            : this.target.sourcePath;
+        const result = await traceDylibResolution({
+            rootPath: bundle ?? dirname(this.target.path),
+            targetPath: this.target.path,
+            targetSha256: this.target.sha256,
+            enumerateRoots: bundle !== undefined,
+            parameters,
+            ...(options?.signal === undefined ? {} : { signal: options.signal }),
+        });
+        return ok(createAnalysisExecution(result, IDENTITY, {
+            limitations: result.limitations,
+            locations: result.images.map(({ path }) => ({
+                kind: "artifact-path",
+                path,
+            })),
+        }));
+    }
     async inspectArtifact(parameters, options) {
         const parsed = artifactInventoryInputSchema.parse(parameters);
         const inventoryParameters = {
@@ -206,6 +240,9 @@ const isArtifactOperation = (operation) => ARTIFACT_ANALYSIS_OPERATIONS.includes
 const translateFailure = (operation, cause) => {
     if (cause instanceof ArtifactReaderFailure)
         return new ArtifactOperationError(operation, cause.reason, cause.details, cause.message);
+    // Caller-selection failures are already typed; keep their correction details.
+    if (cause instanceof AnalysisInputError)
+        return cause;
     return new ArtifactOperationError(operation, "io");
 };
 const subjectFor = (path, manifest) => ({

package/dist/artifacts/ArtifactProviderMetadata.js

@@ -11,7 +11,8 @@ export const artifactCapabilities = (platform = process.platform) => Object.free
         effects: Object.freeze({
             mutatesArtifact: false,
             launchesProcess: operation !== "decode_interface_builder" &&
-                operation !== "inspect_keyed_archive",
+                operation !== "inspect_keyed_archive" &&
+                operation !== "trace_dylib_resolution",
             mayShowUi: false,
             mayAccessNetwork: false,
             mayWriteFilesystem: operation === "extract_artifact" ||