rea-agents 6.1.0 → 6.3.0

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,32 +41,51 @@ 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,
+                });
         }
-    else if (value.status === "unknown" && value.resourceLimit !== undefined) {
+        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),
+            }, context.state.evidenceContexts));
+    }
+    else if (value.status === "unknown" ||
+        value.status === "ambiguous" ||
+        value.status === "cycle") {
         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",
+            family: "data-flow",
+            relation_kinds: ["defines"],
+            reason: value.resourceLimit === undefined
+                ? "unknown-value"
+                : "resource-limit",
             detail: `${value.reason} Unknown value at ${role}.`,
             candidate_node_ids: [target.node_id],
             evidence: {
@@ -74,7 +95,7 @@ const projectValue = (input) => {
                 confidence: "unknown",
                 limitations: [value.reason],
             },
-        }));
+        }, context.state.evidenceContexts));
     }
 };
 const addLiteralNode = (context, binding, value, role) => retainSemanticGraphNode(context.state, context.file, {
@@ -85,15 +106,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/javascript/JavaScriptSemanticTraceService.js

@@ -1,25 +1,30 @@
 import { z } from "zod";
 import { AnalysisInputError, AnalysisProtocolError, } from "../../domain/analysisErrorCore.js";
 import {} from "../../domain/analysisErrorBase.js";
+import { applicationGraphEvidenceInputError, parseApplicationGraphEvidence, } from "./JavaScriptApplicationEvidenceGraph.js";
 import { jsonValueSchema } from "../../domain/jsonValue.js";
 import { queryJavaScriptSemanticGraph } from "../../domain/javascript/javascriptSemanticQuery.js";
 import { javaScriptSemanticTraceResultSchema, traceJavaScriptSemanticsInputSchema, } from "../../domain/javascript/javascriptSemanticTraceSchemas.js";
 import { err, ok } from "../../domain/result.js";
-import { parseApplicationGraphEvidence } from "./JavaScriptApplicationEvidenceGraph.js";
 import { createJavaScriptSemanticTraceEvidence } from "./JavaScriptApplicationWorkflowEvidence.js";
 const OPERATION = "trace_javascript_semantics";
 /** Trace semantic relations from input already parsed by a trusted adapter. */
 export const traceJavaScriptSemanticsEvidenceValidated = (input) => {
+    const sourceResult = parseApplicationGraphEvidence(input.application, [
+        "application",
+    ]);
+    if (!sourceResult.ok)
+        return err(applicationGraphEvidenceInputError(OPERATION, sourceResult.error));
+    const source = sourceResult.value;
+    if (source.semanticGraph === null)
+        return err(new AnalysisInputError(OPERATION, undefined, [
+            {
+                path: ["application"],
+                reason: "invalid_value",
+                expected: "inline Evidence from analyze_javascript_application with a semantic graph",
+            },
+        ]));
     try {
-        const source = parseApplicationGraphEvidence(input.application);
-        if (source.semanticGraph === null)
-            return err(new AnalysisInputError(OPERATION, undefined, [
-                {
-                    path: ["application"],
-                    reason: "invalid_value",
-                    expected: "inline Evidence from analyze_javascript_application with a semantic graph",
-                },
-            ]));
         const query = queryJavaScriptSemanticGraph(source.semanticGraph, input.query);
         const result = javaScriptSemanticTraceResultSchema.parse({
             ...query,

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/native/NativeCallRoutes.js

@@ -3,16 +3,14 @@ import { parseRelatedAddresses, referenceKindSchema, } from "../../domain/hopper
 import { err, ok } from "../../domain/result.js";
 import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
 const referencesSchema = z.object({
-    reference_kinds_available: z.boolean().optional(),
+    reference_kinds_available: z.boolean(),
     references: z.array(z.object({
         source_address: z.string(),
         target_address: z.string(),
         target_procedure: z.object({ address: z.string() }).nullable(),
         kind: referenceKindSchema,
     })),
-    unresolved_calls: z
-        .array(z.object({ address: z.string(), reason: z.string() }))
-        .default([]),
+    unresolved_calls: z.array(z.object({ address: z.string(), reason: z.string() })),
 });
 /** Prefer typed static call references, preserving computed targets and targetless sites. */
 export const readNativeCallRoutes = async (analysis, procedure, signal) => {

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,42 +8,50 @@ 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";
 import { err, ok } from "../domain/result.js";
 import { ArtifactReaderFailure } from "./ArtifactReader.js";
-import { ARTIFACT_PROVIDER_IDENTITY as IDENTITY, artifactCapabilities, } from "./ArtifactProviderMetadata.js";
+import { artifactCapabilities } from "./ArtifactProviderMetadata.js";
+import { ARTIFACT_GRAPH_PROVIDER } from "../application/InvestigationProviders.js";
 import { createEvidence } from "../domain/evidence.js";
 import { createArtifactInspection } from "../domain/artifactInspection.js";
-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;
+        return ARTIFACT_GRAPH_PROVIDER;
     }
     capabilities() {
         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")
-            return ok(createAnalysisExecution(null, IDENTITY));
+            return ok(createAnalysisExecution(null, ARTIFACT_GRAPH_PROVIDER));
         if (!isArtifactOperation(operation))
-            return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, "Operation is not implemented by artifact graph provider."));
+            return err(new AnalysisCapabilityUnavailableError(ARTIFACT_GRAPH_PROVIDER.id, operation, "Operation is not implemented by artifact graph provider."));
         try {
             if (operation === "inspect_artifact") {
                 const inspected = await this.inspectArtifact(parameters, options);
@@ -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,
@@ -60,7 +69,7 @@ class ArtifactClient {
                     limits,
                     ...(options?.signal === undefined ? {} : { signal: options.signal }),
                 });
-                return ok(createAnalysisExecution(result, IDENTITY, {
+                return ok(createAnalysisExecution(result, ARTIFACT_GRAPH_PROVIDER, {
                     limitations: result.limitations,
                     locations: result.documents.map(({ relative_path: path }) => ({
                         kind: "artifact-path",
@@ -87,18 +96,19 @@ 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)
                     throw new ArtifactReaderFailure("integrity", `Active archive digest changed: expected ${this.target.sha256}, observed ${result.archive_sha256}`);
-                return ok(createAnalysisExecution(result, IDENTITY, {
+                return ok(createAnalysisExecution(result, ARTIFACT_GRAPH_PROVIDER, {
                     limitations: result.limitations,
                     locations: [{ kind: "artifact-path", path: result.archive_path }],
                 }));
@@ -114,8 +124,9 @@ 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, {
+                return ok(createAnalysisExecution(result, ARTIFACT_GRAPH_PROVIDER, {
                     rawResult: null,
                     limitations: result.limitations,
                     subject: subjectFor(this.target.sourcePath ?? this.target.path, result.manifest),
@@ -127,7 +138,7 @@ class ArtifactClient {
             }
             const parsed = artifactInventoryInputSchema.parse(parameters);
             const result = await this.inventory(parsed, options);
-            return ok(createAnalysisExecution(result, IDENTITY, {
+            return ok(createAnalysisExecution(result, ARTIFACT_GRAPH_PROVIDER, {
                 rawResult: null,
                 limitations: result.limitations,
                 subject: subjectFor(this.target.sourcePath ?? this.target.path, result.manifest),
@@ -138,25 +149,30 @@ 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,
             ...(options?.signal === undefined ? {} : { signal: options.signal }),
         });
-        return ok(createAnalysisExecution(result, IDENTITY, {
+        return ok(createAnalysisExecution(result, ARTIFACT_GRAPH_PROVIDER, {
             limitations: result.limitations,
             locations: result.catalogs.map(({ path }) => ({
                 kind: "artifact-path",
@@ -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
@@ -180,7 +196,7 @@ class ArtifactClient {
             parameters,
             ...(options?.signal === undefined ? {} : { signal: options.signal }),
         });
-        return ok(createAnalysisExecution(result, IDENTITY, {
+        return ok(createAnalysisExecution(result, ARTIFACT_GRAPH_PROVIDER, {
             limitations: result.limitations,
             locations: result.images.map(({ path }) => ({
                 kind: "artifact-path",
@@ -205,7 +221,7 @@ class ArtifactClient {
             kind: "artifact-path",
             path,
         }));
-        const inventoryEvidence = createEvidence(subject, IDENTITY, {
+        const inventoryEvidence = createEvidence(subject, ARTIFACT_GRAPH_PROVIDER, {
             operation: "inventory_artifact",
             parameters: inventoryParameters,
             result: inventory,
@@ -220,7 +236,7 @@ class ArtifactClient {
             total: 1,
             message: "inventory substep completed",
         });
-        return ok(createAnalysisExecution(result, IDENTITY, {
+        return ok(createAnalysisExecution(result, ARTIFACT_GRAPH_PROVIDER, {
             rawResult: null,
             limitations: result.limitations,
             subject,
@@ -229,19 +245,26 @@ 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,
-            }),
+            integrity: { mode: parsed.integrity_policy },
         });
     }
 }
 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/ArtifactProviderMetadata.js

@@ -1,12 +1,9 @@
 import { ARTIFACT_GRAPH_PROVIDER } from "../application/InvestigationProviders.js";
 import { ARTIFACT_ANALYSIS_OPERATIONS } from "../contracts/artifactToolContracts.js";
-/** Identity of artifact inventory and owned extraction observations. */
-export const ARTIFACT_PROVIDER_IDENTITY = Object.freeze(ARTIFACT_GRAPH_PROVIDER);
-const IDENTITY = ARTIFACT_PROVIDER_IDENTITY;
 /** Declare artifact coverage without constructing readers or acquiring resources. */
 export const artifactCapabilities = (platform = process.platform) => Object.freeze(ARTIFACT_ANALYSIS_OPERATIONS.map((operation) => {
     const common = {
-        provider: IDENTITY,
+        provider: ARTIFACT_GRAPH_PROVIDER,
         operation,
         effects: Object.freeze({
             mutatesArtifact: false,

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);