rea-agents 6.2.0 → 6.4.0

package/dist/artifacts/ArtifactProvider.js

@@ -14,10 +14,12 @@ 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 { ArtifactResourceScope } from "./ArtifactResourceScope.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";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 /** Read-only inventory and exclusively owned extraction provider. */
 export class ArtifactProvider {
     #capabilities;
@@ -29,7 +31,7 @@ export class ArtifactProvider {
         this.#platform = platform;
     }
     identity() {
-        return IDENTITY;
+        return ARTIFACT_GRAPH_PROVIDER;
     }
     capabilities() {
         return this.#capabilities;
@@ -42,6 +44,7 @@ class ArtifactClient {
     target;
     environment;
     platform;
+    #resourceScope = new ArtifactResourceScope();
     constructor(target, environment, platform) {
         this.target = target;
         this.environment = environment;
@@ -49,9 +52,9 @@ class ArtifactClient {
     }
     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);
@@ -69,7 +72,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",
@@ -108,7 +111,7 @@ class ArtifactClient {
                 });
                 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 }],
                 }));
@@ -125,27 +128,25 @@ class ArtifactClient {
                     inputFormat: this.target.format,
                     outputRoot: parsed.output_root,
                     environment: this.environment,
+                    integrityPolicy: parsed.integrity_policy,
+                    resourceScope: this.#resourceScope,
                 }, 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),
-                    locations: result.artifacts.map(({ relative_path: path }) => ({
-                        kind: "artifact-path",
-                        path,
-                    })),
+                    // Each extracted file's path is already in artifacts.
+                    locations: [],
                 }));
             }
             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),
-                locations: result.occurrences.map(({ logical_path: path }) => ({
-                    kind: "artifact-path",
-                    path,
-                })),
+                // Each occurrence's logical path is already in the result.
+                locations: [],
             }));
         }
         catch (cause) {
@@ -153,7 +154,13 @@ class ArtifactClient {
         }
     }
     close() {
-        return Promise.resolve(ok(null));
+        return this.#resourceScope.close().then(() => ok(null), (cause) => {
+            const failure = cause instanceof ArtifactReaderFailure ? cause : undefined;
+            return err(new ProviderCleanupError(ARTIFACT_GRAPH_PROVIDER.id, failure?.cleanup?.resources ?? ["artifact resources"], {
+                reason: failure?.cleanup?.reason ??
+                    (cause instanceof Error ? cause.message : String(cause)),
+            }, { cause, operation: "close_binary" }));
+        });
     }
     /** The active target's kind is outside this operation's supported targets. */
     unsupportedTarget(operation, reason) {
@@ -172,7 +179,7 @@ class ArtifactClient {
             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",
@@ -196,7 +203,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",
@@ -217,17 +224,14 @@ class ArtifactClient {
         });
         const inventory = await this.inventory(inventoryParameters, options);
         const subject = subjectFor(this.target.sourcePath ?? this.target.path, inventory.manifest);
-        const locations = inventory.occurrences.map(({ logical_path: path }) => ({
-            kind: "artifact-path",
-            path,
-        }));
-        const inventoryEvidence = createEvidence(subject, IDENTITY, {
+        const inventoryEvidence = createEvidence(subject, ARTIFACT_GRAPH_PROVIDER, {
             operation: "inventory_artifact",
             parameters: inventoryParameters,
             result: inventory,
             rawResult: null,
             limitations: inventory.limitations,
-            locations,
+            // The nested inventory already names every occurrence's logical path.
+            locations: [],
         });
         const result = createArtifactInspection(inventoryEvidence);
         await options?.progress?.report({
@@ -236,20 +240,19 @@ 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,
-            locations,
+            locations: [],
         }));
     }
     inventory(parsed, options) {
         return inventoryArtifact(this.target.sourcePath ?? this.target.path, {
+            resourceScope: this.#resourceScope,
             environment: this.environment,
             ...(options?.signal === undefined ? {} : { signal: options.signal }),
-            integrity: resolveArtifactIntegrityPolicy({
-                mode: parsed.integrity_policy,
-            }),
+            integrity: { mode: parsed.integrity_policy },
         });
     }
 }

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

@@ -1,3 +1,26 @@
+/** Snapshot mutable entry metadata before the producer later validates open(). */
+export const copyArtifactEntry = (entry) => ({
+    ...entry,
+    limitations: [...entry.limitations],
+    ...(entry.sourceIdentity === undefined
+        ? {}
+        : { sourceIdentity: { ...entry.sourceIdentity } }),
+});
+/** Compare every portable and adapter-owned fact supplied with an entry. */
+export const sameArtifactEntry = (entry, produced) => entry.path === produced.path &&
+    entry.kind === produced.kind &&
+    entry.declaredSize === produced.declaredSize &&
+    entry.compressedSize === produced.compressedSize &&
+    entry.executable === produced.executable &&
+    entry.encrypted === produced.encrypted &&
+    entry.byteOffset === produced.byteOffset &&
+    entry.declaredSha256 === produced.declaredSha256 &&
+    entry.unpacked === produced.unpacked &&
+    entry.adapterKey === produced.adapterKey &&
+    entry.limitations.length === produced.limitations.length &&
+    entry.limitations.every((limitation, index) => limitation === produced.limitations[index]) &&
+    entry.sourceIdentity?.device === produced.sourceIdentity?.device &&
+    entry.sourceIdentity?.inode === produced.sourceIdentity?.inode;
 /** Typed adapter failure translated at provider boundary. */
 export class ArtifactReaderFailure extends Error {
     reason;

package/dist/artifacts/ArtifactResourceScope.js

@@ -0,0 +1,100 @@
+import { ArtifactReaderFailure } from "./ArtifactReader.js";
+/** Caller-owned scope that retains failed artifact cleanup for a later close. */
+export class ArtifactResourceScope {
+    #pending = new Set();
+    #active = new Set();
+    #draining;
+    #closed = false;
+    /** Admit a resource operation while the scope remains open. */
+    async run(operation) {
+        while (true) {
+            if (this.#closed)
+                throw new ArtifactReaderFailure("unavailable", "Artifact resource scope is closed");
+            if (this.#draining !== undefined)
+                await this.#draining;
+            if (this.#closed)
+                throw new ArtifactReaderFailure("unavailable", "Artifact resource scope is closed");
+            if (this.#pending.size > 0) {
+                await this.#retryCleanup();
+                continue;
+            }
+            const running = Promise.resolve().then(operation);
+            this.#active.add(running);
+            try {
+                return await running;
+            }
+            finally {
+                this.#active.delete(running);
+            }
+        }
+    }
+    /** Attempt cleanup now and retain the same owner if it fails. */
+    async release(owner) {
+        try {
+            await cleanup(owner);
+            this.#pending.delete(owner);
+            return { kind: "released" };
+        }
+        catch (cause) {
+            this.#pending.add(owner);
+            return { kind: "failed", cause };
+        }
+    }
+    /** Retry retained owners without closing resource admission. */
+    #retryCleanup() {
+        if (this.#draining !== undefined)
+            return this.#draining;
+        this.#draining = this.#drainAndRetry().finally(() => {
+            this.#draining = undefined;
+        });
+        return this.#draining;
+    }
+    /** Stop admission, wait for active operations, and retry every retained owner. */
+    close() {
+        this.#closed = true;
+        return this.#retryCleanup();
+    }
+    async #drainAndRetry() {
+        while (this.#active.size > 0)
+            await Promise.allSettled(this.#active);
+        const failures = [];
+        for (const owner of this.#pending) {
+            try {
+                await cleanup(owner);
+                this.#pending.delete(owner);
+            }
+            catch (cause) {
+                failures.push({ owner, cause });
+            }
+        }
+        if (failures.length === 0)
+            return;
+        const observations = failures.map(({ owner, cause }) => ArtifactReaderFailure.cleanupObservation(cause, owner.resource));
+        const resources = [
+            ...new Set(observations.flatMap(({ resources }) => resources)),
+        ];
+        throw new ArtifactReaderFailure("unavailable", `Artifact cleanup remains incomplete: ${resources.join(", ")}`, {
+            cause: new AggregateError(failures.map(({ cause }) => cause), "One or more artifact resources remain owned"),
+            cleanup: {
+                reason: observations.map(({ reason }) => reason).join("; "),
+                resources,
+            },
+        });
+    }
+}
+const cleanup = async (owner) => {
+    switch (owner.kind) {
+        case "javascript-source-analysis":
+            await owner.analysis.close();
+            return;
+        case "reader":
+            await owner.reader.close();
+            return;
+        case "file-handle":
+        case "directory-handle":
+            await owner.handle.close();
+            return;
+        case "output-tree":
+            await owner.tree.rollback();
+    }
+};