rea-agents 6.3.0 → 6.4.0

package/dist/application/native/NativeValueTrace.js

@@ -8,6 +8,7 @@ import { err, ok } from "../../domain/result.js";
 export const traceNativeValues = async (analysis, parameters, signal) => {
     const input = nativeValueTraceInputSchema.parse(parameters);
     const nodes = [];
+    const nodeIds = new Set();
     const edges = [];
     const procedures = [];
     const unknowns = [];
@@ -116,24 +117,27 @@ export const traceNativeValues = async (analysis, parameters, signal) => {
             bytes += size;
             ids.add(operation.id);
             nodes.push(node);
+            nodeIds.add(node.id);
         }
         for (const parameter of flow.parameters) {
             if (nodes.length >= input.max_nodes) {
                 truncated = true;
                 break;
             }
+            const id = `${address}/parameter:${parameter.ordinal}`;
             nodes.push({
-                id: `${address}/parameter:${parameter.ordinal}`,
+                id,
                 procedure: address,
                 evidence_id: evidenceId,
                 kind: "parameter",
                 operation: null,
                 parameter,
             });
+            nodeIds.add(id);
         }
         for (const use of flow.parameter_uses) {
             if (!ids.has(use.use) ||
-                !nodes.some((node) => node.id === `${address}/parameter:${use.ordinal}`))
+                !nodeIds.has(`${address}/parameter:${use.ordinal}`))
                 continue;
             if (edges.length >= input.max_edges) {
                 truncated = true;
@@ -243,8 +247,23 @@ export const traceNativeValues = async (analysis, parameters, signal) => {
     }
     if (targetSha256 === undefined)
         return err(new AnalysisOutputError("trace_native_values", "No seed function could be analyzed"));
+    const parametersByProcedure = new Map();
+    const returnsByProcedure = new Map();
+    for (const node of nodes) {
+        if (node.kind === "parameter") {
+            const parameters = parametersByProcedure.get(node.procedure) ?? [];
+            parameters.push(node);
+            parametersByProcedure.set(node.procedure, parameters);
+        }
+        else if (node.operation?.opcode === "RETURN" &&
+            node.operation.inputs.length > 1) {
+            const returns = returnsByProcedure.get(node.procedure) ?? [];
+            returns.push(node);
+            returnsByProcedure.set(node.procedure, returns);
+        }
+    }
     for (const binding of callBindings) {
-        const parameters = nodes.filter((node) => node.procedure === binding.callee && node.kind === "parameter");
+        const parameters = parametersByProcedure.get(binding.callee) ?? [];
         if (parameters.length === 0)
             unknowns.push({
                 procedure: binding.caller,
@@ -275,9 +294,7 @@ export const traceNativeValues = async (analysis, parameters, signal) => {
             });
         }
         if (binding.output)
-            for (const node of nodes.filter((node) => node.procedure === binding.callee &&
-                node.operation?.opcode === "RETURN" &&
-                node.operation.inputs.length > 1)) {
+            for (const node of returnsByProcedure.get(binding.callee) ?? []) {
                 if (edges.length >= input.max_edges) {
                     truncated = true;
                     break;

package/dist/application/process/ProcessCli.js

@@ -1,4 +1,3 @@
-import { readFile } from "node:fs/promises";
 import { z } from "zod";
 import { AnalysisError } from "../../domain/analysisErrorBase.js";
 import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
@@ -11,9 +10,12 @@ import { processTraceSpecificationSchema } from "../../domain/process/processTra
 import { processScenarioSchema } from "../../domain/process/processScenario.js";
 import { compareProcessCaptures } from "../../domain/process/processComparison.js";
 import { parseProcessCapture } from "../../domain/process/processCaptureParsing.js";
+import { createProgressReporter } from "../ProgressReporter.js";
 import { captureProcessScenario } from "../../process/capture/ProcessHarness.js";
+import { ProcessCaptureResourceScope } from "../../process/capture/ProcessCaptureLifecycle.js";
 import { PROCESS_PROVIDER } from "../../domain/process/processEvidenceProvider.js";
 import { createProcessCaptureEvidence } from "./ProcessEvidence.js";
+import { readJsonFile } from "../JsonFiles.js";
 /** Identify the process workflow's typed diagnostic result for CLI exit status. */
 export const isProcessCliFailure = (value) => typeof value === "object" &&
     value !== null &&
@@ -30,7 +32,19 @@ export const captureProcessScenarioFile = async (path, environment = process.env
         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, signal, process.platform, environment);
+        const progress = createProgressReporter(async (update) => {
+            process.stderr.write(`${JSON.stringify({ rea_progress: update })}\n`);
+        }, { minimumIntervalMs: 100 });
+        const resourceScope = new ProcessCaptureResourceScope();
+        const captured = await captureProcessScenario(parsed.data, signal, process.platform, environment, undefined, undefined, progress, resourceScope);
+        try {
+            await resourceScope.close();
+        }
+        catch (cause) {
+            if (!captured.ok)
+                return cliAnalysisError(captured.error);
+            throw cause;
+        }
         if (!captured.ok)
             return cliAnalysisError(captured.error);
         return createProcessCaptureEvidence(parsed.data, captured.value);
@@ -115,24 +129,15 @@ const parseTraceSpecification = (input) => {
 };
 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 {
-        bytes = await readFile(path);
-    }
-    catch (cause) {
-        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", {
-            fatal: true,
-            ignoreBOM: true,
-        }).decode(bytes);
-        const parsed = JSON.parse(text);
-        return parsed;
-    }
-    catch (cause) {
-        throw new ProcessCliFailure("invalid_input", `Process input file is not valid UTF-8 JSON: ${path} (${describeValidationFailure(cause)}). Repair the file, then try again.`);
-    }
+    const loaded = await readJsonFile(path);
+    if (loaded.ok)
+        return loaded.value;
+    if (loaded.error._tag !== "EvidenceFileError")
+        throw loaded.error;
+    const detail = describeValidationFailure(loaded.error.cause);
+    throw new ProcessCliFailure("invalid_input", loaded.error.reason === "invalid-json"
+        ? `Process input file is not valid UTF-8 JSON: ${path} (${detail}). Repair the file, then try again.`
+        : `Process input file could not be read: ${path} (${detail}). Check the reported filesystem constraint and retry.`);
 };
 class ProcessCliFailure extends Error {
     category;

package/dist/artifacts/ArtifactPaths.js

@@ -1,6 +1,17 @@
 import { posix } from "node:path";
+import { logicalPathNfc } from "../domain/artifactIdentity.js";
+import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
 import { ArtifactReaderFailure } from "./ArtifactReader.js";
 const DRIVE_OR_UNC = /^(?:[A-Za-z]:|\\|\/\/)/u;
+/**
+ * English Unicode case folding used only to describe logical names a
+ * case-insensitive destination might collapse. It is not a filesystem case table.
+ */
+const ENGLISH_UNICODE_CASE_NOTE = "This comparison is not a filesystem observation.";
+/** Inventory limitation when logical names collide under English Unicode case folding. */
+export const ENGLISH_UNICODE_CASE_INVENTORY_LIMITATION = `Logical archive names collide under English (en-US) Unicode case folding; a case-insensitive destination cannot store both spellings. ${ENGLISH_UNICODE_CASE_NOTE}`;
+/** User-facing prefix for a destination that cannot keep two logical spellings. */
+export const DESTINATION_CASE_COLLISION_PREFIX = "Destination filesystem cannot store both ";
 /** Normalize an untrusted logical archive path without touching filesystem. */
 export const normalizeArtifactPath = (input) => {
     if (input.includes("\0") ||
@@ -8,7 +19,7 @@ export const normalizeArtifactPath = (input) => {
         input.startsWith("/") ||
         DRIVE_OR_UNC.test(input))
         throw new ArtifactReaderFailure("path", `Artifact path is absolute or unsafe: ${JSON.stringify(input)}`);
-    const normalized = input.normalize("NFC").replace(/\/+$/u, "");
+    const normalized = logicalPathNfc(input).replace(/\/+$/u, "");
     const parts = normalized.split("/");
     if (normalized.length === 0 ||
         parts.some((part) => part === "" || part === "." || part === "..") ||
@@ -16,7 +27,7 @@ export const normalizeArtifactPath = (input) => {
         throw new ArtifactReaderFailure("path", `Artifact path is not normalized: ${JSON.stringify(input)}`);
     return normalized;
 };
-/** Reject exact, Unicode-normalized, case-folded, and prefix collisions. */
+/** Reject exact and same-spelling prefix collisions. Case-distinct names stay distinct. */
 export class ArtifactPathRegistry {
     #root = { kind: undefined, children: new Map() };
     add(path, kind) {
@@ -25,13 +36,10 @@ export class ArtifactPathRegistry {
         for (const [index, part] of parts.entries()) {
             if (node.kind !== undefined && node.kind !== "directory")
                 throw new ArtifactReaderFailure("path", `Artifact prefix conflict: ${path}`);
-            const foldedPart = part.toLocaleLowerCase("en-US");
-            let child = node.children.get(foldedPart);
-            if (child !== undefined && child.spelling !== part)
-                throw new ArtifactReaderFailure("path", `Artifact path collision: ${path} differs only in case from ${[...parts.slice(0, index), child.spelling].join("/")}`);
+            let child = node.children.get(part);
             if (child === undefined) {
-                child = { spelling: part, kind: undefined, children: new Map() };
-                node.children.set(foldedPart, child);
+                child = { kind: undefined, children: new Map() };
+                node.children.set(part, child);
             }
             node = child;
             if (index === parts.length - 1) {
@@ -44,3 +52,116 @@ export class ArtifactPathRegistry {
         node.kind = kind;
     }
 }
+const emptyCaseNode = () => ({
+    bySpelling: new Map(),
+    spellingsByFold: new Map(),
+    terminals: [],
+});
+const englishCaseFold = (part) => part.toLocaleLowerCase("en-US");
+/**
+ * Record English (en-US) Unicode case collisions on each affected occurrence.
+ * Returns the inventory limitation when any logical names collide.
+ */
+export const annotateEnglishUnicodeCaseCollisions = (occurrences) => {
+    const collisions = englishUnicodeCaseCollisions(occurrences.map(({ logical_path }) => logical_path));
+    if (collisions.size === 0)
+        return undefined;
+    for (const occurrence of occurrences)
+        for (const collision of collisions.get(occurrence.logical_path) ?? [])
+            occurrence.limitations.push(caseCollisionLimitation(occurrence.logical_path, collision));
+    return ENGLISH_UNICODE_CASE_INVENTORY_LIMITATION;
+};
+const caseCollisionLimitation = (path, { prefix, other, additional }) => {
+    const others = additional === 0
+        ? other
+        : `${other} and ${String(additional)} other spelling${additional === 1 ? "" : "s"}`;
+    const subject = prefix === path
+        ? `Logical path ${path} collides`
+        : `Logical path ${path} is under ${prefix}, which collides`;
+    return `${subject} under English (en-US) Unicode case folding with ${others}; a case-insensitive destination cannot store both. ${ENGLISH_UNICODE_CASE_NOTE}`;
+};
+/**
+ * Name the directory-listing spelling that differs from the requested segment
+ * only by English (en-US) Unicode case. Exact matches are the same logical name.
+ */
+export const destinationCaseCollisionMessage = (requestedPath, existingNames) => {
+    const slash = requestedPath.lastIndexOf("/");
+    const segment = slash < 0 ? requestedPath : requestedPath.slice(slash + 1);
+    if (existingNames.includes(segment))
+        return undefined;
+    const folded = englishCaseFold(segment);
+    const existing = existingNames
+        .filter((name) => englishCaseFold(name) === folded)
+        .sort(compareUnicodeCodePoints)[0];
+    if (existing === undefined)
+        return undefined;
+    const parent = slash < 0 ? "" : requestedPath.slice(0, slash + 1);
+    return `${DESTINATION_CASE_COLLISION_PREFIX}${requestedPath} and ${parent}${existing}; inventory retains both logical names.`;
+};
+const englishUnicodeCaseCollisions = (paths) => {
+    const root = emptyCaseNode();
+    for (const path of paths) {
+        if (path.length === 0 || path === ".")
+            continue;
+        let node = root;
+        for (const part of path.split("/")) {
+            let child = node.bySpelling.get(part);
+            if (child === undefined) {
+                const folded = englishCaseFold(part);
+                const spellings = node.spellingsByFold.get(folded);
+                if (spellings === undefined)
+                    node.spellingsByFold.set(folded, [part]);
+                else
+                    spellings.push(part);
+                child = emptyCaseNode();
+                node.bySpelling.set(part, child);
+            }
+            node = child;
+        }
+        node.terminals.push(path);
+    }
+    // A collision is recorded once, at the segment where spellings diverge, and
+    // shared down the subtree. Pairing every descendant of one spelling with
+    // every descendant of another grew quadratically with the subtree sizes.
+    // The walk is iterative because a ZIP name can hold more components than
+    // the call stack allows.
+    const collisions = new Map();
+    const pending = [{ node: root, prefix: undefined, chain: undefined }];
+    for (let item = pending.pop(); item !== undefined; item = pending.pop()) {
+        const { node, prefix, chain } = item;
+        if (chain !== undefined)
+            for (const path of node.terminals)
+                collisions.set(path, collisionsAlong(chain));
+        for (const spellings of node.spellingsByFold.values())
+            spellings.sort(compareUnicodeCodePoints);
+        for (const [spelling, child] of node.bySpelling) {
+            const childPrefix = prefix === undefined ? spelling : `${prefix}/${spelling}`;
+            const spellings = node.spellingsByFold.get(englishCaseFold(spelling)) ?? [];
+            const other = spellings[0] === spelling ? spellings[1] : spellings[0];
+            pending.push({
+                node: child,
+                prefix: childPrefix,
+                chain: other === undefined
+                    ? chain
+                    : {
+                        collision: {
+                            prefix: childPrefix,
+                            other: prefix === undefined ? other : `${prefix}/${other}`,
+                            additional: spellings.length - 2,
+                        },
+                        parent: chain,
+                    },
+            });
+        }
+    }
+    return collisions;
+};
+const collisionsAlong = (chain) => {
+    const collisions = [];
+    let link = chain;
+    while (link !== undefined) {
+        collisions.push(link.collision);
+        link = link.parent;
+    }
+    return collisions.reverse();
+};

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 { 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 { ProviderCleanupError } from "../domain/providerCleanupError.js";
 /** Read-only inventory and exclusively owned extraction provider. */
 export class ArtifactProvider {
     #capabilities;
@@ -42,6 +44,7 @@ class ArtifactClient {
     target;
     environment;
     platform;
+    #resourceScope = new ArtifactResourceScope();
     constructor(target, environment, platform) {
         this.target = target;
         this.environment = environment;
@@ -125,15 +128,15 @@ 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, 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);
@@ -142,10 +145,8 @@ class ArtifactClient {
                 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) {
@@ -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, 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({
@@ -240,11 +244,12 @@ class ArtifactClient {
             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: { mode: parsed.integrity_policy },

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();
+    }
+};