rea-agents 6.1.0 → 6.2.0

package/dist/artifacts/DirectoryArtifactReader.js

@@ -1,6 +1,7 @@
 import { constants } from "node:fs";
 import { lstat, open, opendir, realpath } from "node:fs/promises";
 import { isAbsolute, join, relative, sep } from "node:path";
+import { compareCodePoints } from "../domain/canonicalOrdering.js";
 import { ArtifactReaderFailure, } from "./ArtifactReader.js";
 /** Deterministic, non-symlink-following directory reader. */
 export class DirectoryArtifactReader {
@@ -38,7 +39,7 @@ export class DirectoryArtifactReader {
                 await handle.close().catch(() => undefined);
             }
             await withDirectoryIoContext("inspect directory", directory, () => assertContainedDirectory(root, directory));
-            children.sort((left, right) => left.localeCompare(right, "en"));
+            children.sort(compareCodePoints);
             const directories = [];
             for (const name of children) {
                 abortIfNeeded(signal);

package/dist/artifacts/MachOSliceArtifactReader.js

@@ -12,7 +12,7 @@ export class MachOSliceArtifactReader {
     runner;
     format = "file";
     #command;
-    constructor(path, runner = new XcrunCommandRunner()) {
+    constructor(path, environment, runner = new XcrunCommandRunner(environment)) {
         this.path = path;
         this.runner = runner;
     }
@@ -175,7 +175,7 @@ const lipoMatchesSlice = (reported, observed, structurallyUnique) => {
         reported.cpu_type_code !== null ||
         reported.cpu_subtype_code !== null;
     return ((hasPhysicalIdentity || structurallyUnique) &&
-        reported.name === observed.architecture &&
+        lipoNameMatches(reported.name, observed.architecture) &&
         (reported.file_offset === null ||
             reported.file_offset === observed.slice_offset) &&
         (reported.size === null || reported.size === observed.slice_size) &&
@@ -187,6 +187,13 @@ const lipoMatchesSlice = (reported, observed, structurallyUnique) => {
             observed.fat_alignment_exponent === null ||
             reported.alignment === 2 ** observed.fat_alignment_exponent));
 };
+/**
+ * Newer lipo names an arm64e ABI variant `arm64e.<variant>` (for example
+ * `arm64e.v1` for pointer-auth ABI version 1). The FAT table names that slice
+ * `arm64e`; its physical identity is still compared field by field.
+ */
+const lipoNameMatches = (reported, observed) => reported === observed ||
+    (observed === "arm64e" && /^arm64e\.[A-Za-z0-9_]+$/u.test(reported));
 const parseSliceKeyInteger = (value) => {
     if (value === undefined || !/^\d+$/u.test(value))
         return null;

package/dist/artifacts/NativeDmgArtifactReader.js

@@ -7,6 +7,13 @@ import { ArtifactReaderFailure, } from "./ArtifactReader.js";
 import { DirectoryArtifactReader } from "./DirectoryArtifactReader.js";
 import { execFileOutput } from "../process/ExecFileOutput.js";
 const DETACH_TIMEOUT_MS = 120_000;
+/**
+ * Waits before rechecking devices whose detach failed. A related device's
+ * later detach can eject one, `hdiutil info` can still list an ejected device
+ * briefly, and a volume can report busy just after it was read.
+ */
+const DETACH_SETTLE_DELAYS_MS = [250, 500, 1000];
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
 const attachOutputSchema = z.object({
     "system-entities": z.array(z.object({
         "dev-entry": z.string().startsWith("/dev/"),
@@ -18,10 +25,12 @@ const infoOutputSchema = z.object({
         "system-entities": z.array(z.object({ "dev-entry": z.string() })),
     })),
 });
-const systemHost = {
+const createSystemHost = (environment) => ({
+    delay,
     async run(arguments_, signal, options) {
         try {
             const { stdout, stderr } = await execFileOutput("/usr/bin/hdiutil", [...arguments_], {
+                env: environment,
                 ...(options === undefined ? {} : { timeout: options.timeoutMs }),
                 ...(signal === undefined ? {} : { signal }),
             });
@@ -41,7 +50,7 @@ const systemHost = {
             throw new ArtifactReaderFailure(commandFailureReason(cause, arguments_[0]), `hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(cause, arguments_)}`, { cause });
         }
     },
-};
+});
 /** Read-only macOS DMG adapter that owns attachment and reverse-order detach. */
 export class NativeDmgArtifactReader {
     path;
@@ -56,10 +65,10 @@ export class NativeDmgArtifactReader {
         this.host = host;
     }
     /** Verify and attach one image beneath an exclusively owned temporary root. */
-    static async create(path, signal, host = systemHost) {
-        if (process.platform !== "darwin" && host === systemHost)
+    static async create(path, environment, signal, host) {
+        if (process.platform !== "darwin" && host === undefined)
             throw new ArtifactReaderFailure("unavailable", "Native DMG traversal is available only on macOS");
-        const reader = new NativeDmgArtifactReader(path, host);
+        const reader = new NativeDmgArtifactReader(path, host ?? createSystemHost(environment));
         await reader.attach(signal);
         return reader;
     }
@@ -80,24 +89,36 @@ export class NativeDmgArtifactReader {
     }
     async close() {
         let detachFailure;
-        const remainingDevices = [];
+        let remainingDevices = [];
         for (const device of [...this.#devices].reverse()) {
-            try {
-                await runChecked(this.host, ["detach", device], undefined, {
-                    timeoutMs: DETACH_TIMEOUT_MS,
-                });
-                this.#provenance.push(command(["detach", device], ["mount"]));
+            const failure = await this.#detach(device);
+            if (failure !== undefined) {
+                remainingDevices.push(device);
+                detachFailure ??= failure;
             }
-            catch (cause) {
-                // Detaching a synthesized APFS container also ejects the image that
-                // backs it, so a later whole disk of the same image may already be
-                // gone. Only a device that is still attached is a cleanup failure.
-                if (await this.#isAttached(device)) {
-                    remainingDevices.push(device);
-                    detachFailure ??= cause;
+        }
+        // Detaching a synthesized APFS container also ejects the image that backs
+        // it, so a device whose own detach failed may be gone by the end of the
+        // pass, and hdiutil can list an ejected device or report busy briefly.
+        // Only a device that stays attached through every recheck is a failure.
+        for (const delayMs of DETACH_SETTLE_DELAYS_MS) {
+            if (remainingDevices.length === 0)
+                break;
+            await (this.host.delay ?? delay)(delayMs);
+            const stillAttached = [];
+            for (const device of remainingDevices) {
+                if (!(await this.#isAttached(device)))
+                    continue;
+                const failure = await this.#detach(device);
+                if (failure !== undefined) {
+                    stillAttached.push(device);
+                    detachFailure = failure;
                 }
             }
+            remainingDevices = stillAttached;
         }
+        if (remainingDevices.length === 0)
+            detachFailure = undefined;
         this.#devices = remainingDevices.reverse();
         if (this.#devices.length === 0 && this.#mountRoot !== undefined)
             await rm(this.#mountRoot, { recursive: true, force: true }).then(() => {
@@ -107,7 +128,31 @@ export class NativeDmgArtifactReader {
                 detachFailure ??= cause;
             });
         if (detachFailure !== undefined)
-            throw new ArtifactReaderFailure("unavailable", `DMG detach or mount-root cleanup failed for ${JSON.stringify(this.path)}: ${failureMessage(detachFailure)}`, { cause: detachFailure });
+            throw new ArtifactReaderFailure("unavailable", `DMG detach or mount-root cleanup failed for ${JSON.stringify(this.path)}: ${failureMessage(detachFailure)}`, {
+                cause: detachFailure,
+                cleanup: {
+                    reason: failureMessage(detachFailure),
+                    resources: [
+                        ...this.#devices.map((device) => `DMG device ${device}`),
+                        ...(this.#mountRoot === undefined
+                            ? []
+                            : [`DMG mount root ${this.#mountRoot}`]),
+                    ],
+                },
+            });
+    }
+    /** Detach one device; return the failure only while it remains attached. */
+    async #detach(device) {
+        try {
+            await runChecked(this.host, ["detach", device], undefined, {
+                timeoutMs: DETACH_TIMEOUT_MS,
+            });
+            this.#provenance.push(command(["detach", device], ["mount"]));
+            return undefined;
+        }
+        catch (cause) {
+            return (await this.#isAttached(device)) ? cause : undefined;
+        }
     }
     /**
      * Report whether hdiutil still lists a device; unknown state counts as
@@ -175,7 +220,7 @@ export class NativeDmgArtifactReader {
                 cleanupFailure = cleanupCause;
             }
             if (cleanupFailure !== undefined)
-                throw new ArtifactReaderFailure("unavailable", `DMG attach failed and cleanup could not detach every device: ${failureMessage(cause)}; cleanup: ${failureMessage(cleanupFailure)}`, { cause: new AggregateError([cause, cleanupFailure]) });
+                throw ArtifactReaderFailure.withCleanup(cause, ArtifactReaderFailure.cleanupObservation(cleanupFailure, `DMG mount root ${this.#mountRoot ?? this.path}`));
             throw cause;
         }
     }

package/dist/artifacts/SafeOutputTree.js

@@ -129,7 +129,13 @@ export class SafeOutputTree {
     async rollback() {
         if (this.#published)
             return structuredClone(this.#cleanup);
-        await rm(this.#outputRoot, { recursive: true, force: true });
+        let removalFailure;
+        try {
+            await rm(this.#outputRoot, { recursive: true, force: true });
+        }
+        catch (cause) {
+            removalFailure = cause;
+        }
         const absent = await isAbsent(this.#outputRoot);
         this.#cleanup = absent
             ? { status: "complete", residualPaths: [] }
@@ -138,7 +144,15 @@ export class SafeOutputTree {
                 residualPaths: [basename(this.#outputRoot)],
             };
         if (!absent)
-            throw new ArtifactReaderFailure("integrity", "Extraction output cleanup could not be verified");
+            throw new ArtifactReaderFailure("integrity", `Extraction output cleanup could not be verified${removalFailure === undefined ? "" : `: ${removalFailure instanceof Error ? removalFailure.message : String(removalFailure)}`}`, {
+                cause: removalFailure,
+                cleanup: {
+                    reason: removalFailure instanceof Error
+                        ? removalFailure.message
+                        : "Extraction output root remains after rollback",
+                    resources: [this.#outputRoot],
+                },
+            });
         return structuredClone(this.#cleanup);
     }
     async #prepareParent(relativePath) {

package/dist/artifacts/ZipArtifactReader.js

@@ -5,10 +5,12 @@ import { Reader, ZipReader } from "@zip.js/zip.js";
 import { ArtifactReaderFailure, } from "./ArtifactReader.js";
 class NodeFileReader extends Reader {
     path;
+    maximumReadBytes;
     #handle;
-    constructor(path) {
+    constructor(path, maximumReadBytes) {
         super(path);
         this.path = path;
+        this.maximumReadBytes = maximumReadBytes;
     }
     async init() {
         this.#handle = await open(this.path, "r");
@@ -18,7 +20,11 @@ class NodeFileReader extends Reader {
         const handle = this.#handle;
         if (handle === undefined)
             throw new Error("ZIP reader is not initialized");
-        const bytes = Buffer.alloc(Math.min(length, this.size - index));
+        const readBytes = Math.min(length, this.size - index);
+        if (this.maximumReadBytes !== undefined &&
+            readBytes > this.maximumReadBytes)
+            throw new ArtifactReaderFailure("limit", `ZIP metadata read requires ${readBytes} bytes, exceeding the ${this.maximumReadBytes}-byte read budget`);
+        const bytes = Buffer.alloc(readBytes);
         const read = await handle.read(bytes, 0, bytes.length, index);
         return bytes.subarray(0, read.bytesRead);
     }
@@ -33,9 +39,10 @@ export class ZipArtifactReader {
     #source;
     #reader;
     #entries = new Map();
-    constructor(path, format) {
+    /** Optionally bound each metadata read before allocating its backing buffer. */
+    constructor(path, format, maximumMetadataReadBytes) {
         this.format = format;
-        this.#source = new NodeFileReader(path);
+        this.#source = new NodeFileReader(path, maximumMetadataReadBytes);
         this.#reader = new ZipReader(this.#source, {
             checkSignature: true,
             checkOverlappingEntry: true,

package/dist/artifacts/apple/AppleAssetCatalogAnalysis.js

@@ -39,7 +39,8 @@ export const analyzeAppleAssetCatalogs = async (input) => {
             const inspected = await inspectAssetCatalogEntry({
                 reader,
                 entry,
-                runAssetUtil: input.runAssetUtil ?? runAssetUtil,
+                runAssetUtil: input.runAssetUtil ??
+                    ((path, signal) => runAssetUtil(path, input.environment, signal)),
                 ...(input.signal === undefined ? {} : { signal: input.signal }),
             });
             totalMetadataBytes += inspected.metadataBytes;
@@ -150,9 +151,10 @@ export const collectInterfaceBuilderResourceKeys = (nodes) => nodes.flatMap((nod
         ]
         : []);
 });
-const runAssetUtil = async (path, signal) => {
+const runAssetUtil = async (path, environment, signal) => {
     try {
         return (await execFileOutput(ASSETUTIL, ["--info", path], {
+            env: environment,
             timeout: 60_000,
             maxBuffer: MAX_CATALOG_BYTES,
             ...(signal === undefined ? {} : { signal }),

package/dist/artifacts/apple/DylibResolutionReader.js

@@ -2,11 +2,14 @@ import { createHash } from "node:crypto";
 import { constants } from "node:fs";
 import { lstat, open, readlink, realpath } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
+import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
 import { resolveTreePath } from "../../domain/apple/dyldPaths.js";
 import { dylibResolutionInputSchema, dylibResolutionResultSchema, traceDylibLoading, } from "../../domain/apple/dylibResolution.js";
+import { projectInputIssues } from "../../domain/inputIssueProjection.js";
 import { ArtifactReaderFailure } from "../ArtifactReader.js";
 import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
 import { hasMachoMagic, readMachoImage } from "./MachoLoadCommandReader.js";
+const OPERATION = "trace_dylib_resolution";
 const HASH_CHUNK_BYTES = 1024 * 1024;
 /** Lazily probed, symlink-preserving view of one analyzed directory. */
 class FilesystemTreeView {
@@ -64,7 +67,7 @@ class FilesystemTreeView {
 export const traceDylibResolution = async (options) => {
     const parsed = dylibResolutionInputSchema.safeParse(options.parameters);
     if (!parsed.success)
-        throw new ArtifactReaderFailure("path", "roots must be normalized paths relative to the analyzed root");
+        throw new AnalysisInputError(OPERATION, { cause: parsed.error }, projectInputIssues(parsed.error.issues, options.parameters));
     // Canonicalization is inside the translated region: a revoked permission
     // keeps its reason and path.
     let root = options.rootPath;
@@ -79,7 +82,7 @@ export const traceDylibResolution = async (options) => {
             : options.enumerateRoots
                 ? await executableRoots(root, view, options.signal)
                 : { roots: [target], unclassified: [] };
-        const roots = await requireMachoRoots(view, requested);
+        const roots = await requireMachoRoots(view, requested, parsed.data.roots !== undefined);
         const trace = await traceDylibLoading(view, {
             roots,
             unclassified,
@@ -151,17 +154,24 @@ const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
 /**
  * Resolve each root segment by segment, as dependency candidates are, so a
  * symlink in an intermediate directory cannot lead outside the analyzed root.
+ * A root the caller selected that fails is an input error on that root; a
+ * root REA derived itself keeps reporting an artifact failure.
  */
-const requireMachoRoots = async (view, roots) => {
+const requireMachoRoots = async (view, roots, callerSelected) => {
     const resolved = [];
-    for (const path of roots) {
+    for (const [index, path] of roots.entries()) {
+        const reject = (reason, message) => callerSelected
+            ? new AnalysisInputError(OPERATION, undefined, [
+                { path: ["roots", index], reason: "invalid_value", message },
+            ])
+            : new ArtifactReaderFailure(reason, message);
         const lookup = await resolveTreePath(view, path);
         if (lookup.kind === "escapes")
-            throw new ArtifactReaderFailure("path", `Root ${path} resolves outside the analyzed root`);
+            throw reject("path", `Root ${path} resolves outside the analyzed root`);
         if (lookup.kind !== "file")
-            throw new ArtifactReaderFailure("path", `Root ${path} is not a regular file in the analyzed root`);
+            throw reject("path", `Root ${path} is not a regular file in the analyzed root`);
         if ((await view.image(lookup.path)).status === "not-mach-o")
-            throw new ArtifactReaderFailure("format", `Root ${path} is not a Mach-O image`);
+            throw reject("format", `Root ${path} is not a Mach-O image`);
         if (!resolved.includes(lookup.path))
             resolved.push(lookup.path);
     }

package/dist/artifacts/apple/KeyedArchiveReader.js

@@ -1,12 +1,13 @@
 import { createHash } from "node:crypto";
+import { join } from "node:path";
 import { parseBinary } from "plist";
 import { z } from "zod";
-import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
+import { AnalysisInputError, AnalysisUnsupportedTargetError, } from "../../domain/analysisErrorCore.js";
 import { projectPlistValue } from "../../domain/apple/plistValue.js";
 import { createPlistNumberProjection } from "../../domain/apple/plistNumbers.js";
 import { binaryPlistNumberLiterals, xmlPlistNumberLiterals, } from "./PlistNumberLiterals.js";
 import { omittedPrototypeKeysLimitation, parseXmlPropertyList, } from "../../domain/propertyListKeys.js";
-import { keyedArchiveInputSchema, keyedArchiveResultSchema, projectKeyedArchive, } from "../../domain/apple/keyedArchive.js";
+import { KeyedArchiveKindError, keyedArchiveInputSchema, keyedArchiveResultSchema, projectKeyedArchive, } from "../../domain/apple/keyedArchive.js";
 import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
 import { ArtifactReaderFailure } from "../ArtifactReader.js";
 import { decodeXmlPlistText } from "../../domain/propertyListXmlText.js";
@@ -16,7 +17,7 @@ export const decodeKeyedArchiveBytes = (bytes, selection) => {
     if (bytes.length > MAX_BYTES)
         throw new RangeError("Keyed archive exceeds 64 MiB");
     if (bytes.subarray(0, 10).toString("ascii") === "NIBArchive")
-        throw new TypeError("Selected file is a compiled NIBArchive, not a Foundation plist archive; decode it with decode_interface_builder");
+        throw new KeyedArchiveKindError("Selected file is a compiled NIBArchive, not a Foundation plist archive; decode it with decode_interface_builder", "nib-archive");
     const binary = bytes.subarray(0, 8).toString("ascii") === "bplist00";
     const xmlText = binary ? undefined : decodeXmlPlistText(bytes);
     const parsed = binary
@@ -56,6 +57,17 @@ const normalizePlist = (value) => {
         throw new RangeError("Keyed archive contains a non-finite real");
     return projected.value;
 };
+/**
+ * Point to the workflow that reads the selected kind of file on this host.
+ * decode_interface_builder is portable; inspect_plist requires macOS.
+ */
+const keyedArchiveKindRemediation = (kind, platform) => {
+    if (kind === "nib-archive")
+        return "Decode compiled NIBArchive files with decode_interface_builder on the app bundle.";
+    return platform === "darwin"
+        ? "Inspect an ordinary property list with inspect_plist; inspect_keyed_archive decodes NSKeyedArchiver archives only."
+        : "Select an NSKeyedArchiver archive; inspect_keyed_archive decodes only those. inspect_plist, which reads ordinary property lists, requires a macOS host.";
+};
 /** Read exactly one regular, contained bundle entry without following symlinks. */
 export const inspectBundleKeyedArchive = async (input) => {
     const selected = keyedArchiveInputSchema.parse(input.parameters);
@@ -103,6 +115,12 @@ export const inspectBundleKeyedArchive = async (input) => {
             catch (cause) {
                 if (cause instanceof AnalysisInputError)
                     throw cause;
+                // An intact file of another kind is not a damaged archive.
+                if (cause instanceof KeyedArchiveKindError)
+                    throw new AnalysisUnsupportedTargetError("inspect_keyed_archive", join(input.bundlePath, entry.path), cause.message, {
+                        cause,
+                        remediationAction: keyedArchiveKindRemediation(cause.kind, input.platform ?? process.platform),
+                    });
                 throw new ArtifactReaderFailure(cause instanceof RangeError ? "limit" : "format", `Cannot decode selected Foundation keyed archive: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
             }
         }

package/dist/artifacts/extraction/ArtifactExtraction.js

@@ -1,19 +1,26 @@
 import { lstat, realpath } from "node:fs/promises";
+import { compareCodePoints } from "../../domain/canonicalOrdering.js";
 import { canonicalDigest } from "../../domain/comparisonSemantics.js";
 import { AsarArtifactReader } from "../AsarArtifactReader.js";
 import { ArtifactPathRegistry, normalizeArtifactPath, } from "../ArtifactPaths.js";
 import { ArtifactReaderFailure, } from "../ArtifactReader.js";
+import { abortIfNeeded } from "../ArtifactHash.js";
 import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
 import { SafeOutputTree } from "../SafeOutputTree.js";
 import { ZipArtifactReader } from "../ZipArtifactReader.js";
 import { MachOSliceArtifactReader } from "../MachOSliceArtifactReader.js";
 import { artifactExtractionResultSchema, } from "../../domain/artifactGraph.js";
+import { AnalysisUnsupportedTargetError } from "../../domain/analysisErrorCore.js";
 import { scanArtifactInventory } from "../inventory/ArtifactInventory.js";
 /** Extract every regular inventory occurrence into an exclusively owned absent root. */
 export const extractArtifact = async (input, signal) => {
+    // Cancellation wins over every later refusal, including unsupported formats.
+    abortIfNeeded(signal);
     const sourcePath = await realpath(input.inputPath);
+    await requireExtractableFormat(sourcePath, input);
     const snapshot = await scanArtifactInventory(sourcePath, {
         signal,
+        environment: input.environment,
     });
     const selectedOccurrences = snapshot.occurrences.filter((occurrence) => (occurrence.entry_kind === "file" || occurrence.entry_kind === "slice") &&
         occurrence.logical_path !== ".");
@@ -29,11 +36,14 @@ export const extractArtifact = async (input, signal) => {
         nodes,
     };
     const selected = selectedOccurrences.map((occurrence) => {
+        // REA never decrypts archive entries, so an encrypted entry makes the
+        // complete extraction unsupported rather than the archive invalid.
+        if (occurrence.encrypted)
+            throw new AnalysisUnsupportedTargetError("extract_artifact", input.inputPath, `Archive entry ${occurrence.logical_path} is encrypted; REA does not decrypt archive entries, so the archive cannot be extracted completely`);
         if ((occurrence.entry_kind !== "file" && occurrence.entry_kind !== "slice") ||
             occurrence.artifact_id === null ||
-            occurrence.encrypted ||
             occurrence.logical_path === ".")
-            throw new ArtifactReaderFailure("format", `Selected occurrence is not an extractable regular child file: ${occurrence.occurrence_id}`);
+            throw new ArtifactReaderFailure("format", `Selected occurrence is not an extractable regular child file: ${occurrence.logical_path} (${occurrence.occurrence_id})`);
         const node = inventory.nodes.get(occurrence.artifact_id);
         if (node === undefined)
             throw new ArtifactReaderFailure("integrity", `Selected occurrence has no inventory node: ${occurrence.occurrence_id}`);
@@ -49,11 +59,13 @@ export const extractArtifact = async (input, signal) => {
 };
 const materializeSelection = async ({ input, sourcePath, inventory, selected, signal, }) => {
     const byPath = new Map(selected.map((item) => [item.occurrence.logical_path, item]));
-    const reader = await createReader(sourcePath, input.inputFormat);
-    const output = await SafeOutputTree.create(input.outputRoot);
+    const reader = await createReader(sourcePath, input);
+    let output;
+    let readerCloseAttempted = false;
     let readerClosed = false;
     const extracted = [];
     try {
+        output = await SafeOutputTree.create(input.outputRoot);
         const materialized = [];
         const registry = new ArtifactPathRegistry();
         for await (const entry of reader.entries(signal)) {
@@ -77,20 +89,53 @@ const materializeSelection = async ({ input, sourcePath, inventory, selected, si
             });
             materialized.push(selectedItem);
         }
+        readerCloseAttempted = true;
         await reader.close();
         readerClosed = true;
-        extracted.sort((left, right) => left.relative_path.localeCompare(right.relative_path, "en"));
+        extracted.sort((left, right) => compareCodePoints(left.relative_path, right.relative_path));
         const result = createExtractionResult(input, inventory, materialized, extracted);
         await output.commit();
         return result;
     }
     catch (cause) {
-        if (!readerClosed)
-            await reader.close().catch((cause) => {
-                // best-effort cleanup: reader close must not mask the extraction failure.
-                void cause;
+        const cleanupFailures = [];
+        if (readerCloseAttempted && !readerClosed)
+            cleanupFailures.push({
+                cause,
+                resource: `artifact reader for ${sourcePath}`,
             });
-        await output.rollback();
+        if (!readerCloseAttempted) {
+            try {
+                readerCloseAttempted = true;
+                await reader.close();
+            }
+            catch (cleanupCause) {
+                cleanupFailures.push({
+                    cause: cleanupCause,
+                    resource: `artifact reader for ${sourcePath}`,
+                });
+            }
+        }
+        if (output !== undefined) {
+            try {
+                await output.rollback();
+            }
+            catch (cleanupCause) {
+                cleanupFailures.push({
+                    cause: cleanupCause,
+                    resource: input.outputRoot,
+                });
+            }
+        }
+        if (cleanupFailures.length > 0) {
+            const observations = cleanupFailures.map(({ cause: cleanupCause, resource }) => ArtifactReaderFailure.cleanupObservation(cleanupCause, resource));
+            throw ArtifactReaderFailure.withCleanup(cause, {
+                reason: observations.map(({ reason }) => reason).join("; "),
+                resources: [
+                    ...new Set(observations.flatMap(({ resources }) => resources)),
+                ],
+            });
+        }
         throw cause;
     }
 };
@@ -99,7 +144,7 @@ const createExtractionResult = (input, inventory, selected, extracted) => {
         source_manifest_id: inventory.manifest.manifest_id,
         selected_occurrence_ids: selected
             .map(({ occurrence }) => occurrence.occurrence_id)
-            .sort((left, right) => left.localeCompare(right)),
+            .sort(compareCodePoints),
         files_sha256: canonicalDigest(extracted, "Artifact"),
         output_root_alias: "$OUTPUT_ROOT",
     };
@@ -133,20 +178,32 @@ const collectNodes = (items, selected, output) => {
         if (selected.has(item.artifact_id))
             output.set(item.artifact_id, item);
 };
-const createReader = async (path, format) => {
-    if ((await lstat(path)).isDirectory())
+const ZIP_FORMATS = ["ipa", "apk", "msix", "appx", "zip"];
+const isZipFormat = (format) => ZIP_FORMATS.includes(format);
+/**
+ * Refuse a format without an extraction reader before inventory work starts.
+ * The target kind, not the host, is unsupported by extraction. The error keeps
+ * the caller's spelling of the path; I/O uses the canonical path.
+ */
+const requireExtractableFormat = async (path, input) => {
+    const format = input.inputFormat;
+    const directory = (await lstat(path)).isDirectory();
+    if (!directory &&
+        format !== "asar" &&
+        format !== "mach-o" &&
+        !isZipFormat(format))
+        throw new AnalysisUnsupportedTargetError("extract_artifact", input.inputPath, `Artifact format has no extraction reader: ${format}`);
+    return directory;
+};
+const createReader = async (path, input) => {
+    const format = input.inputFormat;
+    if (await requireExtractableFormat(path, input))
         return new DirectoryArtifactReader(path);
     if (format === "asar")
         return new AsarArtifactReader(path);
-    if (format === "ipa" ||
-        format === "apk" ||
-        format === "msix" ||
-        format === "appx" ||
-        format === "zip")
+    if (isZipFormat(format))
         return new ZipArtifactReader(path, format);
-    if (format === "mach-o")
-        return new MachOSliceArtifactReader(path);
-    throw new ArtifactReaderFailure("unavailable", `Artifact format has no extraction reader: ${format}`);
+    return new MachOSliceArtifactReader(path, input.environment);
 };
 const preflight = (entry) => {
     if ((entry.kind !== "file" && entry.kind !== "slice") || entry.encrypted)