rea-agents 6.3.0 → 6.5.0

package/dist/artifacts/ArtifactPaths.js

@@ -1,14 +1,22 @@
 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;
-/** Normalize an untrusted logical archive path without touching filesystem. */
+const DRIVE_PREFIX = /^[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 slash-separated logical names; backslashes are literal components. */
 export const normalizeArtifactPath = (input) => {
-    if (input.includes("\0") ||
-        input.includes("\\") ||
-        input.startsWith("/") ||
-        DRIVE_OR_UNC.test(input))
+    if (input.includes("\0") || input.startsWith("/") || DRIVE_PREFIX.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 +24,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,17 +33,14 @@ 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) {
-                if (node.kind !== undefined)
+                if (node.kind !== undefined && node.kind !== kind)
                     throw new ArtifactReaderFailure("path", `Artifact path collision: ${path}`);
                 if (kind !== "directory" && node.children.size > 0)
                     throw new ArtifactReaderFailure("path", `Artifact prefix conflict: ${path}`);
@@ -44,3 +49,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

@@ -8,16 +8,19 @@ 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 { isMachOFormat, } from "../domain/binaryTargetTypes.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 { ArtifactResourceScope } from "./ArtifactResourceScope.js";
 import { artifactCapabilities } from "./ArtifactProviderMetadata.js";
 import { ARTIFACT_GRAPH_PROVIDER } from "../application/InvestigationProviders.js";
 import { createEvidence } from "../domain/evidence.js";
+import { freezeJsonSnapshot } from "../domain/immutableJson.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 +45,7 @@ class ArtifactClient {
     target;
     environment;
     platform;
+    #resourceScope = new ArtifactResourceScope();
     constructor(target, environment, platform) {
         this.target = target;
         this.environment = environment;
@@ -125,15 +129,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 +146,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 +155,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) {
@@ -181,7 +189,7 @@ class ArtifactClient {
         }));
     }
     async traceDylibResolution(parameters, options) {
-        if (this.target.kind !== "executable" || this.target.format !== "mach-o")
+        if (this.target.kind !== "executable" || !isMachOFormat(this.target.format))
             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.
@@ -215,21 +223,21 @@ class ArtifactClient {
             total: 1,
             message: "inventory substep started",
         });
-        const inventory = await this.inventory(inventoryParameters, options);
+        // The freshly parsed inventory is exclusively owned here. Sealing it lets
+        // the nested Evidence share it instead of cloning and re-digesting it.
+        const inventory = freezeJsonSnapshot(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);
+        // The returned execution and its Evidence then reuse this owned report.
+        const result = freezeJsonSnapshot(createArtifactInspection(inventoryEvidence));
         await options?.progress?.report({
             phase: "inspect_artifact.inventory",
             completed: 1,
@@ -240,11 +248,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,38 @@
+/** Compare captured filesystem identity and mutable metadata at a read boundary. */
+export const sameArtifactSourceIdentity = (expected, observed) => expected !== undefined &&
+    observed.dev === expected.device &&
+    observed.ino === expected.inode &&
+    observed.size === expected.size &&
+    observed.mode === expected.mode &&
+    observed.mtimeNs === expected.mtimeNs &&
+    observed.ctimeNs === expected.ctimeNs;
+/** 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 &&
+    entry.sourceIdentity?.size === produced.sourceIdentity?.size &&
+    entry.sourceIdentity?.mode === produced.sourceIdentity?.mode &&
+    entry.sourceIdentity?.mtimeNs === produced.sourceIdentity?.mtimeNs &&
+    entry.sourceIdentity?.ctimeNs === produced.sourceIdentity?.ctimeNs;
 /** Typed adapter failure translated at provider boundary. */
 export class ArtifactReaderFailure extends Error {
     reason;

package/dist/artifacts/ArtifactResourceScope.js

@@ -0,0 +1,109 @@
+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;
+    get hasPending() {
+        return this.#pending.size > 0;
+    }
+    /** 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();
+            return;
+        case "staged-output":
+            await owner.output.close();
+            return;
+        case "private-runtime-root":
+            await owner.root.close();
+    }
+};