rea-agents 6.1.0 → 6.2.0

package/dist/application/javascript/JavaScriptSemanticGraphChildProcessProjection.js

@@ -1,7 +1,6 @@
 import { createJavaScriptSemanticGraphUnknown } from "../../domain/javascript/javascriptSemanticGraph.js";
 import { retainSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
 import { unknownSemanticEvidence } from "./JavaScriptSemanticGraphEvidence.js";
-import { semanticCallSiteAt, } from "./JavaScriptSemanticGraphFlowProjection.js";
 /** Project child creation, argv/env/stdio, listeners, and signals. */
 export const projectSemanticChildProcesses = (context) => {
     const processNodes = new Map(context.ir.childProcessSpawns.flatMap((spawn) => {
@@ -34,7 +33,7 @@ const addChildProcessNode = (context, spawn) => retainSemanticGraphNode(context.
     },
 });
 const projectSpawn = (context, spawn, child) => {
-    const callSite = semanticCallSiteAt(context, spawn.location);
+    const callSite = context.callSiteAt(spawn.location);
     addSemanticGraphRelation(context.state, {
         source: callSite,
         target: child,

package/dist/application/javascript/JavaScriptSemanticGraphDataProjection.js

@@ -1,7 +1,6 @@
 import { createJavaScriptSemanticGraphUnknown } from "../../domain/javascript/javascriptSemanticGraph.js";
 import { retainSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
 import { unknownSemanticEvidence } from "./JavaScriptSemanticGraphEvidence.js";
-import { semanticCallSiteAt, } from "./JavaScriptSemanticGraphFlowProjection.js";
 /** Project environment, argv, file, default, and precedence candidates. */
 export const projectSemanticConfiguration = (context) => {
     const configNodes = new Map(context.ir.configurationOperations.flatMap((operation) => {
@@ -110,7 +109,7 @@ const addRequestNode = (context, operation) => retainSemanticGraphNode(context.s
     },
 });
 const projectRequestConstruction = (context, operation, request) => {
-    const callSite = semanticCallSiteAt(context, operation.location);
+    const callSite = context.callSiteAt(operation.location);
     addSemanticGraphRelation(context.state, {
         source: callSite,
         target: request,
@@ -142,7 +141,7 @@ const projectRequestConstruction = (context, operation, request) => {
 const projectResponseConsumer = (context, operation, response) => {
     addSemanticGraphRelation(context.state, {
         source: response,
-        target: semanticCallSiteAt(context, operation.location),
+        target: context.callSiteAt(operation.location),
         relation: "consumed-by",
         resolution: operation.resolution === "complete" ? "resolved" : "candidate",
         properties: { method: operation.method },

package/dist/application/javascript/JavaScriptSemanticGraphFlowProjection.js

@@ -2,10 +2,6 @@ import { createJavaScriptSemanticGraphUnknown } from "../../domain/javascript/ja
 import { sourceRangesEqual } from "../../domain/javascript/javascriptStaticAnalysisHelpers.js";
 import { retainSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
 import { inferredSemanticEvidenceAt, unknownSemanticEvidence, } from "./JavaScriptSemanticGraphEvidence.js";
-/** Find the retained call-site node at one exact semantic source range. */
-export const semanticCallSiteAt = (context, location) => {
-    return context.callSiteAt(location);
-};
 /** Project explicit static Promise/task ownership without runtime claims. */
 export const projectSemanticPromises = (context) => {
     const promiseNodes = new Map(context.ir.promiseOperations.flatMap((operation) => {
@@ -46,7 +42,7 @@ const projectPromiseCreation = (context, operation, promise) => {
     if (operation.kind === "awaited-expression")
         return;
     addSemanticGraphRelation(context.state, {
-        source: semanticCallSiteAt(context, operation.location),
+        source: context.callSiteAt(operation.location),
         target: promise,
         relation: "creates-promise",
         resolution: operation.kind === "chain" || operation.sourceResolution !== "complete"

package/dist/application/javascript/JavaScriptSemanticGraphObjectProjection.js

@@ -1,80 +1,109 @@
+import { semanticSlotAtPath, semanticContainer, semanticPropertyPointer, } from "../../domain/javascript/javascriptSemanticSlots.js";
 import { createJavaScriptSemanticGraphUnknown } from "../../domain/javascript/javascriptSemanticGraph.js";
 import { retainSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
 import { unknownSemanticEvidence } from "./JavaScriptSemanticGraphEvidence.js";
 import { semanticPropertySlot } from "./JavaScriptSemanticGraphValueProjection.js";
 /** Project static object reads, writes, spreads, and destructuring. */
 export const projectSemanticObjects = (context) => {
+    const values = new Map(context.ir.bindings.map((binding) => [binding.bindingId, binding.value]));
     for (const operation of context.ir.objectOperations) {
         const occurrence = addObjectOccurrence(context, operation);
-        const slot = operation.objectBindingId === null || operation.propertyName === null
-            ? null
-            : semanticPropertySlot(context, operation.objectBindingId, operation.propertyName);
-        if (operation.kind === "read")
-            addSemanticGraphRelation(context.state, {
-                source: slot,
-                target: occurrence,
-                relation: "reads-property",
-                resolution: operation.resolution === "complete" ? "resolved" : "candidate",
-            });
-        else if (operation.kind === "write")
-            addSemanticGraphRelation(context.state, {
-                source: occurrence,
-                target: slot,
-                relation: "writes-property",
-                resolution: operation.resolution === "complete" ? "resolved" : "candidate",
-            });
-        else if (operation.kind === "destructure")
-            addSemanticGraphRelation(context.state, {
-                source: slot,
+        const target = objectTarget(context, values, operation);
+        const ends = objectRelationEnds(context, operation, occurrence, target);
+        const resolved = operation.resolution === "complete" &&
+            (operation.kind === "write"
+                ? target.receiverResolved
+                : target.presence === "present");
+        addSemanticGraphRelation(context.state, {
+            ...ends,
+            relation: OBJECT_RELATIONS[operation.kind],
+            resolution: resolved ? "resolved" : "candidate",
+        });
+        if (!resolved)
+            addObjectUnknown(context, operation, target.slot ?? occurrence, target);
+    }
+};
+const OBJECT_RELATIONS = {
+    read: "reads-property",
+    write: "writes-property",
+    destructure: "destructures",
+    spread: "spreads",
+};
+const objectTarget = (context, values, operation) => {
+    const binding = operation.objectBindingId === null
+        ? undefined
+        : context.bindingNodes.get(operation.objectBindingId);
+    const value = operation.objectBindingId === null
+        ? undefined
+        : values.get(operation.objectBindingId);
+    if (operation.objectBindingId === null ||
+        operation.propertyPath === null ||
+        value === undefined)
+        return {
+            objectNode: binding,
+            slot: null,
+            presence: "unknown-coverage",
+            receiverResolved: false,
+        };
+    const fact = semanticSlotAtPath(value, operation.propertyPath);
+    if (operation.propertyPath.length === 0)
+        return {
+            objectNode: binding,
+            slot: null,
+            presence: fact.presence,
+            receiverResolved: semanticContainer(value) !== null,
+        };
+    const slot = semanticPropertySlot(context, operation.objectBindingId, operation.propertyPath, fact);
+    const receiver = semanticSlotAtPath(value, operation.propertyPath.slice(0, -1));
+    return {
+        objectNode: slot,
+        slot,
+        presence: fact.presence,
+        receiverResolved: receiver.presence === "present" &&
+            semanticContainer(receiver.value) !== null,
+    };
+};
+const objectRelationEnds = (context, operation, occurrence, target) => {
+    switch (operation.kind) {
+        case "read":
+            return { source: target.slot, target: occurrence };
+        case "write":
+            return { source: occurrence, target: target.slot };
+        case "destructure":
+            return {
+                source: target.slot,
                 target: operation.targetBindingId === null
                     ? undefined
                     : context.bindingNodes.get(operation.targetBindingId),
-                relation: "destructures",
-                resolution: operation.resolution === "complete" ? "resolved" : "candidate",
-            });
-        else
-            addSemanticGraphRelation(context.state, {
-                source: operation.objectBindingId === null
-                    ? undefined
-                    : context.bindingNodes.get(operation.objectBindingId),
-                target: occurrence,
-                relation: "spreads",
-                resolution: operation.resolution === "complete" ? "resolved" : "candidate",
-            });
-        if (operation.resolution !== "complete")
-            addObjectUnknown(context, operation, slot ?? occurrence);
+            };
+        case "spread":
+            return { source: target.objectNode, target: occurrence };
     }
 };
 const addObjectOccurrence = (context, operation) => retainSemanticGraphNode(context.state, context.file, {
     kind: "expression",
     roleKey: operation.objectOperationId,
     location: operation.location,
-    label: operation.propertyName === null
+    label: operation.propertyPath === null
         ? operation.kind
-        : `${operation.kind}:${operation.propertyName}`,
+        : `${operation.kind}:${semanticPropertyPointer(operation.propertyPath)}`,
     functionNodeId: operation.ownerCallableId === null
         ? null
         : (context.callableNodes.get(operation.ownerCallableId)?.node_id ??
             null),
     properties: {
         operation_kind: operation.kind,
-        property_name: operation.propertyName,
+        property_path: operation.propertyPath === null ? null : [...operation.propertyPath],
     },
 });
-const addObjectUnknown = (context, operation, node) => {
-    const relation = operation.kind === "read"
-        ? "reads-property"
-        : operation.kind === "write"
-            ? "writes-property"
-            : operation.kind === "spread"
-                ? "spreads"
-                : "destructures";
+const addObjectUnknown = (context, operation, node, target) => {
+    const relation = OBJECT_RELATIONS[operation.kind];
     addSemanticGraphUnknown(context.state, createJavaScriptSemanticGraphUnknown({
         node_id: node?.node_id ?? null,
         family: "object-flow",
         relation_kinds: [relation],
         reason: "ambiguous-target",
-        detail: `Static ${operation.kind} object identity is partial.`,
+        detail: `Static ${operation.kind} property ${operation.propertyPath === null ? "path is unresolved" : semanticPropertyPointer(operation.propertyPath)} has ${target.presence} presence; its receiver is ${target.receiverResolved ? "a retained container" : "unresolved or not a retained container"}; object identity is ${operation.resolution}.`,
         candidate_node_ids: [],
         evidence: unknownSemanticEvidence(context.file, operation.location),
     }));

package/dist/application/javascript/JavaScriptSemanticGraphResourceProjection.js

@@ -1,7 +1,6 @@
 import { createJavaScriptSemanticGraphUnknown } from "../../domain/javascript/javascriptSemanticGraph.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. */
 export const projectSemanticResources = (context) => {
     const resourceNodes = new Map(context.ir.resourceOperations.flatMap((operation) => {
@@ -13,7 +12,7 @@ export const projectSemanticResources = (context) => {
     for (const operation of context.ir.resourceOperations)
         if (operation.kind === "acquire")
             addSemanticGraphRelation(context.state, {
-                source: semanticCallSiteAt(context, operation.location),
+                source: context.callSiteAt(operation.location),
                 target: resourceNodes.get(operation.resourceId),
                 relation: "acquires",
                 resolution: "resolved",
@@ -33,7 +32,7 @@ const addResourceNode = (context, operation) => retainSemanticGraphNode(context.
     properties: { method: operation.method },
 });
 const projectRelease = (context, operation, resourceNodes) => {
-    const callSite = semanticCallSiteAt(context, operation.location);
+    const callSite = context.callSiteAt(operation.location);
     const resources = operation.linkedResourceIds.flatMap((identifier) => {
         const resource = resourceNodes.get(identifier);
         return resource === undefined ? [] : [resource];

package/dist/application/javascript/JavaScriptSemanticGraphValueProjection.js

@@ -1,6 +1,7 @@
+import { semanticContainer, semanticPropertyPointer, } from "../../domain/javascript/javascriptSemanticSlots.js";
 import { createJavaScriptSemanticGraphUnknown } from "../../domain/javascript/javascriptSemanticGraph.js";
 import { retainSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
-import { observedSemanticEvidence } from "./JavaScriptSemanticGraphEvidence.js";
+import { observedSemanticEvidence, unknownSemanticEvidence, } 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) {
@@ -12,12 +13,13 @@ export const projectSemanticValues = (context) => {
             binding,
             value: binding.value,
             target: bindingNode,
-            role: "binding",
+            path: [],
         });
     }
 };
 const projectValue = (input) => {
-    const { context, binding, value, target, role } = input;
+    const { context, binding, value, target, path } = input;
+    const role = path.length === 0 ? "binding" : `property:${semanticPropertyPointer(path)}`;
     if (target === null)
         return;
     if (value.status === "literal") {
@@ -39,23 +41,39 @@ const projectValue = (input) => {
                 resolution: "candidate",
             });
         }
-    else if (value.status === "object")
-        for (const property of value.properties) {
-            const slot = semanticPropertySlot(context, binding.bindingId, property.name);
+    else if (value.status === "object" || value.status === "array") {
+        const container = semanticContainer(value);
+        for (const property of container.slots) {
+            const propertyPath = [...path, property.name];
+            const slot = semanticPropertySlot(context, binding.bindingId, propertyPath, property);
+            if (property.presence === "absent")
+                continue;
             addSemanticGraphRelation(context.state, {
                 source: target,
                 target: slot,
                 relation: "writes-property",
-                resolution: value.unknownProperties ? "candidate" : "resolved",
-            });
-            projectValue({
-                context,
-                binding,
-                value: property.value,
-                target: slot,
-                role: `property:${property.name}`,
+                resolution: property.presence === "present" ? "resolved" : "candidate",
             });
+            if (property.presence === "present")
+                projectValue({
+                    context,
+                    binding,
+                    value: property.value,
+                    target: slot,
+                    path: propertyPath,
+                });
         }
+        if (container.coverage.status === "partial")
+            addSemanticGraphUnknown(context.state, createJavaScriptSemanticGraphUnknown({
+                node_id: target.node_id,
+                family: "object-flow",
+                relation_kinds: ["writes-property"],
+                reason: "ambiguous-target",
+                detail: `Initializer container has unknown ${value.status === "object" ? "properties" : "items"}${container.coverage.omitted === null ? " with an unknown omitted count" : `; ${container.coverage.omitted} omitted`}.`,
+                candidate_node_ids: [target.node_id],
+                evidence: unknownSemanticEvidence(context.file, binding.definitions[0]?.location ?? null),
+            }));
+    }
     else if (value.status === "unknown" && value.resourceLimit !== undefined) {
         const location = binding.definitions[0]?.location ?? null;
         const evidence = observedSemanticEvidence(context.file, location);
@@ -85,15 +103,20 @@ const addLiteralNode = (context, binding, value, role) => retainSemanticGraphNod
     functionNodeId: context.bindingNodes.get(binding.bindingId)?.function_node_id ?? null,
     properties: { value },
 });
-/** Create one canonical property slot for a binding/property identity. */
-export const semanticPropertySlot = (context, objectBindingId, name) => retainSemanticGraphNode(context.state, context.file, {
+/** Create one canonical slot for a root binding and exact static property path. */
+export const semanticPropertySlot = (context, objectBindingId, path, fact) => retainSemanticGraphNode(context.state, context.file, {
     kind: "property-slot",
-    roleKey: `property:${objectBindingId}:${name}`,
+    roleKey: `property:${JSON.stringify([objectBindingId, path])}`,
     location: null,
-    label: name,
+    label: fact.name,
     functionNodeId: context.bindingNodes.get(objectBindingId)?.function_node_id ?? null,
     properties: {
-        name,
+        name: fact.name,
+        property_path: [...path],
+        property_pointer: semanticPropertyPointer(path),
         object_binding_id: objectBindingId,
+        presence: fact.presence,
+        value_status: fact.value.status,
+        value_coverage: semanticContainer(fact.value)?.coverage ?? null,
     },
 });

package/dist/application/managed/ManagedMemberComparisonService.js

@@ -1,7 +1,8 @@
 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 { compareManagedMembers, managedMemberComparisonResultSchema, } from "../../domain/managed/managedMemberComparison.js";
+import { parseManagedMemberEvidence } from "../../domain/managed/managedMemberComparisonMatch.js";
 import { AnalysisProtocolError } from "../../domain/analysisErrorCore.js";
 import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
 import {} from "../../domain/analysisErrorBase.js";

package/dist/application/managed/ManagedNativeVerificationService.js

@@ -3,10 +3,11 @@ 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 { managedNativeVerificationInputSchema, } from "../../domain/managed/managedNativeVerificationSchemas.js";
 import { err, ok } from "../../domain/result.js";
 import { MANAGED_WORKFLOW_PROVIDER } from "../InvestigationProviders.js";
 import { requestInputError, workflowInputError, } from "../workflowInputError.js";
+import { verifyManagedNativeBoundaries } from "../../domain/managed/managedNativeVerification.js";
 const OPERATION = "verify_managed_native_boundaries";
 /** Verify managed/native boundary declarations against native Evidence. */
 export const verifyManagedNativeBoundariesEvidence = (rawInput) => {

package/dist/application/process/ProcessCli.js

@@ -7,11 +7,13 @@ 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 { processTraceSpecificationSchema } from "../../domain/process/processTraceSpecification.js";
 import { processScenarioSchema } from "../../domain/process/processScenario.js";
-import { compareProcessCaptures, parseProcessCapture, } from "../../domain/process/processCapture.js";
+import { compareProcessCaptures } from "../../domain/process/processComparison.js";
+import { parseProcessCapture } from "../../domain/process/processCaptureParsing.js";
 import { captureProcessScenario } from "../../process/capture/ProcessHarness.js";
-import { PROCESS_PROVIDER, createProcessCaptureEvidence, } from "./ProcessEvidence.js";
+import { PROCESS_PROVIDER } from "../../domain/process/processEvidenceProvider.js";
+import { createProcessCaptureEvidence } from "./ProcessEvidence.js";
 /** Identify the process workflow's typed diagnostic result for CLI exit status. */
 export const isProcessCliFailure = (value) => typeof value === "object" &&
     value !== null &&
@@ -22,13 +24,13 @@ export const isProcessCliFailure = (value) => typeof value === "object" &&
     "message" in value &&
     typeof value.message === "string";
 /** Capture one JSON scenario through the shared process harness and Evidence contract. */
-export const captureProcessScenarioFile = async (path, environment = process.env) => {
+export const captureProcessScenarioFile = async (path, environment = process.env, signal) => {
     try {
         const input = await readJson(path);
         const parsed = processScenarioSchema.safeParse(input);
         if (!parsed.success)
             throw analysisInputErrorFromIssues("capture_process_scenario", parsed.error.issues, input, { cause: parsed.error });
-        const captured = await captureProcessScenario(parsed.data, undefined, process.platform, environment);
+        const captured = await captureProcessScenario(parsed.data, signal, process.platform, environment);
         if (!captured.ok)
             return cliAnalysisError(captured.error);
         return createProcessCaptureEvidence(parsed.data, captured.value);
@@ -118,8 +120,7 @@ const readJson = async (path) => {
         bytes = await readFile(path);
     }
     catch (cause) {
-        void cause;
-        throw new ProcessCliFailure("invalid_input", "Process input file could not be read. Check that the path exists and is readable.");
+        throw new ProcessCliFailure("invalid_input", `Process input file could not be read: ${path} (${describeValidationFailure(cause)}). Check the reported filesystem constraint and retry.`);
     }
     try {
         const text = new TextDecoder("utf-8", {
@@ -130,8 +131,7 @@ const readJson = async (path) => {
         return parsed;
     }
     catch (cause) {
-        void cause;
-        throw new ProcessCliFailure("invalid_input", "Process input file is not valid JSON. Repair the file, then try again.");
+        throw new ProcessCliFailure("invalid_input", `Process input file is not valid UTF-8 JSON: ${path} (${describeValidationFailure(cause)}). Repair the file, then try again.`);
     }
 };
 class ProcessCliFailure extends Error {
@@ -147,7 +147,7 @@ const cliAnalysisError = (error) => ({
     error: "Process command failed",
     ...projectAnalysisError(error),
 });
-/** Project any process CLI failure without exposing its cause. */
+/** Preserve typed failures and local diagnostics at the process CLI boundary. */
 export const projectProcessCliError = (cause) => {
     if (cause instanceof ProcessCliFailure)
         return {
@@ -160,6 +160,6 @@ export const projectProcessCliError = (cause) => {
     return {
         error: "Process command failed",
         category: "execution_failure",
-        message: "Process command could not complete. Check the input files and run `rea doctor`, then try again.",
+        message: `Process command could not complete: ${describeValidationFailure(cause)}`,
     };
 };

package/dist/application/process/ProcessEvidence.js

@@ -2,7 +2,6 @@ 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, platform) => ({
     executable_name: (platform === "win32" ? win32 : posix).basename(scenario.executable),

package/dist/artifacts/ArtifactProvider.js

@@ -1,3 +1,4 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
 import { inspectBundleKeyedArchive } from "./apple/KeyedArchiveReader.js";
 import { traceDylibResolution } from "./apple/DylibResolutionReader.js";
@@ -7,7 +8,7 @@ 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, AnalysisInputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
 import { ArtifactOperationError } from "../domain/artifactOperationError.js";
 import {} from "../domain/analysisErrorBase.js";
 import { interfaceBuilderLimitsSchema } from "../domain/apple/interfaceBuilderGraph.js";
@@ -20,8 +21,12 @@ import { resolveArtifactIntegrityPolicy } from "./inventory/policy.js";
 /** Read-only inventory and exclusively owned extraction provider. */
 export class ArtifactProvider {
     #capabilities;
-    constructor(platform = process.platform) {
+    #platform;
+    environment;
+    constructor(environment, platform = process.platform) {
+        this.environment = snapshotEnvironment(environment, platform);
         this.#capabilities = artifactCapabilities(platform);
+        this.#platform = platform;
     }
     identity() {
         return IDENTITY;
@@ -30,13 +35,17 @@ export class ArtifactProvider {
         return this.#capabilities;
     }
     createClient(target) {
-        return new ArtifactClient(target);
+        return new ArtifactClient(target, this.environment, this.#platform);
     }
 }
 class ArtifactClient {
     target;
-    constructor(target) {
+    environment;
+    platform;
+    constructor(target, environment, platform) {
         this.target = target;
+        this.environment = environment;
+        this.platform = platform;
     }
     async execute(operation, parameters, options) {
         if (operation === "health")
@@ -52,7 +61,7 @@ class ArtifactClient {
                 if (this.target.kind !== "executable" ||
                     this.target.sourcePath === undefined ||
                     !this.target.sourcePath.toLowerCase().endsWith(".app"))
-                    throw new ArtifactReaderFailure("unavailable", "decode_interface_builder requires an active .app bundle target");
+                    throw this.unsupportedTarget(operation, "decode_interface_builder requires an active .app bundle target");
                 const limits = interfaceBuilderLimitsSchema.parse(parameters);
                 const result = await analyzeInterfaceBuilderBundle({
                     bundlePath: this.target.sourcePath,
@@ -87,13 +96,14 @@ class ArtifactClient {
                     : this.target.sourcePath;
                 if (bundlePath === undefined ||
                     (!standalone && !bundlePath.toLowerCase().endsWith(".app")))
-                    throw new ArtifactReaderFailure("unavailable", "inspect_keyed_archive requires an active plist or .app bundle");
+                    throw this.unsupportedTarget(operation, "inspect_keyed_archive requires an active plist or .app bundle");
                 const result = await inspectBundleKeyedArchive({
                     bundlePath,
                     targetSha256: this.target.sha256,
                     parameters: standalone
                         ? { ...parameters, path: basename(this.target.path) }
                         : parameters,
+                    platform: this.platform,
                     ...(options?.signal === undefined ? {} : { signal: options.signal }),
                 });
                 if (standalone && result.archive_sha256 !== this.target.sha256)
@@ -114,6 +124,7 @@ class ArtifactClient {
                     inputPath: this.target.sourcePath ?? this.target.path,
                     inputFormat: this.target.format,
                     outputRoot: parsed.output_root,
+                    environment: this.environment,
                 }, options?.signal);
                 return ok(createAnalysisExecution(result, IDENTITY, {
                     rawResult: null,
@@ -138,19 +149,24 @@ class ArtifactClient {
             }));
         }
         catch (cause) {
-            return err(translateFailure(operation, cause));
+            return err(translateArtifactFailure(operation, cause));
         }
     }
     close() {
-        return Promise.resolve();
+        return Promise.resolve(ok(null));
+    }
+    /** The active target's kind is outside this operation's supported targets. */
+    unsupportedTarget(operation, reason) {
+        return new AnalysisUnsupportedTargetError(operation, this.target.sourcePath ?? this.target.path, reason);
     }
     async inspectAssetCatalog(parameters, options) {
         const bundlePath = this.target.sourcePath;
         if (this.target.kind !== "executable" ||
             bundlePath === undefined ||
             !bundlePath.toLowerCase().endsWith(".app"))
-            throw new ArtifactReaderFailure("unavailable", "inspect_asset_catalog requires an active .app bundle target");
+            throw this.unsupportedTarget("inspect_asset_catalog", "inspect_asset_catalog requires an active .app bundle target");
         const result = await analyzeAppleAssetCatalogs({
+            environment: this.environment,
             bundlePath,
             targetSha256: this.target.sha256,
             page: parameters,
@@ -166,7 +182,7 @@ 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");
+            throw this.unsupportedTarget("trace_dylib_resolution", "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
@@ -229,6 +245,7 @@ class ArtifactClient {
     }
     inventory(parsed, options) {
         return inventoryArtifact(this.target.sourcePath ?? this.target.path, {
+            environment: this.environment,
             ...(options?.signal === undefined ? {} : { signal: options.signal }),
             integrity: resolveArtifactIntegrityPolicy({
                 mode: parsed.integrity_policy,
@@ -237,11 +254,19 @@ class ArtifactClient {
     }
 }
 const isArtifactOperation = (operation) => ARTIFACT_ANALYSIS_OPERATIONS.includes(operation);
-const translateFailure = (operation, cause) => {
+/** Translate one artifact boundary failure while retaining cleanup evidence. */
+export const translateArtifactFailure = (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 new ArtifactOperationError(operation, cause.reason, cause.details, cause.message, {
+            ...(cause.cleanup === undefined ? {} : { cleanup: cause.cleanup }),
+            ...(cause.partialObservation === undefined
+                ? {}
+                : { partialObservation: cause.partialObservation }),
+        });
+    // Caller-selection and unsupported-target failures are already typed; keep
+    // their correction details instead of reducing them to an I/O failure.
+    if (cause instanceof AnalysisInputError ||
+        cause instanceof AnalysisUnsupportedTargetError)
         return cause;
     return new ArtifactOperationError(operation, "io");
 };

package/dist/artifacts/ArtifactReader.js

@@ -2,10 +2,41 @@
 export class ArtifactReaderFailure extends Error {
     reason;
     details;
+    cleanup;
+    partialObservation;
     constructor(reason, message, options, details) {
         super(message, options);
         this.reason = reason;
         this.details = details;
         this.name = "ArtifactReaderFailure";
+        this.cleanup = options?.cleanup;
+        this.partialObservation = options?.partialObservation;
+    }
+    /** Preserve the primary failure while attaching cleanup and any complete observation. */
+    static withCleanup(cause, cleanup, partialObservation) {
+        const primary = cause instanceof ArtifactReaderFailure
+            ? cause
+            : new ArtifactReaderFailure("io", errorMessage(cause), { cause });
+        const mergedObservation = partialObservation ?? primary.partialObservation;
+        return new ArtifactReaderFailure(primary.reason, primary.message, {
+            cause: primary,
+            cleanup: combineCleanup(primary.cleanup, cleanup),
+            ...(mergedObservation === undefined
+                ? {}
+                : { partialObservation: mergedObservation }),
+        }, primary.details);
+    }
+    /** Give otherwise opaque cleanup failures a concrete owned resource. */
+    static cleanupObservation(cause, resource) {
+        if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined)
+            return cause.cleanup;
+        return { reason: errorMessage(cause), resources: [resource] };
     }
 }
+const combineCleanup = (primary, cleanup) => primary === undefined || primary === cleanup
+    ? cleanup
+    : {
+        reason: `${primary.reason}; ${cleanup.reason}`,
+        resources: [...new Set([...primary.resources, ...cleanup.resources])],
+    };
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);