rea-agents 6.5.0 → 6.7.0

package/dist/artifacts/MachOSliceArtifactReader.js

@@ -1,3 +1,4 @@
+import { assertArtifactReadActive } from "./ArtifactFileOperation.js";
 import { lstat } from "node:fs/promises";
 import { Readable } from "node:stream";
 import { XcrunCommandRunner, } from "../native/CommandRunner.js";
@@ -8,7 +9,7 @@ import { readMachoImage } from "./apple/MachoLoadCommandReader.js";
 import { ArtifactReaderFailure, copyArtifactEntry, sameArtifactEntry, } from "./ArtifactReader.js";
 import { streamChunkToBuffer } from "./StreamBytes.js";
 import { NonRegularFileReadError, RegularFileAdmissionFailure, openRegularFile, sameRegularFileState, } from "../filesystem/RegularFile.js";
-import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
+import { readArtifactFileChunks } from "./readArtifactFileChunks.js";
 /** Read-only universal Mach-O slice reader backed by native lipo metadata. */
 export class MachOSliceArtifactReader {
     path;
@@ -156,7 +157,9 @@ export class MachOSliceArtifactReader {
     }
     async open(entry, signal) {
         if (signal?.aborted === true)
-            return Promise.reject(new ArtifactReaderFailure("cancelled", "Mach-O slice read cancelled"));
+            return Promise.reject(new ArtifactReaderFailure("cancelled", "Mach-O slice read cancelled", {
+                cause: signal.reason,
+            }));
         const produced = this.#entries.get(entry.adapterKey);
         if (produced === undefined || !sameArtifactEntry(entry, produced))
             throw new ArtifactReaderFailure("integrity", "Mach-O slice entry metadata does not match this reader's inventory");
@@ -174,34 +177,88 @@ export class MachOSliceArtifactReader {
         if (!Number.isSafeInteger(offset + size) ||
             offset + size > source.initial.size)
             throw new ArtifactReaderFailure("integrity", `Mach-O slice range is outside the artifact: ${entry.path}`);
-        const sourceStream = readFileHandleChunks(source.handle, {
+        const sourceStream = readArtifactFileChunks(source.handle, {
             start: offset,
             end: offset + size - 1,
             ...(signal === undefined ? {} : { signal }),
         });
         const verifySource = () => this.#verifySource(source);
-        return Readable.from((async function* () {
-            let observedBytes = 0;
+        let validatingSource = false;
+        const completionFailure = () => {
+            const coverage = sourceStream.readCoverage();
+            if (coverage.kind !== "complete")
+                return new ArtifactReaderFailure("integrity", `Mach-O slice read coverage is incomplete: ${entry.path}`);
+            if (coverage.bytes !== BigInt(size))
+                return new ArtifactReaderFailure("integrity", `Mach-O slice size disagrees with lipo metadata: ${entry.path}`);
+            if (signal?.aborted)
+                return new ArtifactReaderFailure("cancelled", "Mach-O slice read cancelled", { cause: signal.reason });
+            return undefined;
+        };
+        const output = Readable.from((async function* () {
             try {
                 for await (const raw of sourceStream) {
                     const chunk = streamChunkToBuffer(raw);
-                    observedBytes += chunk.byteLength;
-                    if (observedBytes > size)
-                        throw new ArtifactReaderFailure("integrity", `Mach-O slice exceeded its reported size: ${entry.path}`);
+                    if (sourceStream.readCoverage().kind === "complete" &&
+                        signal?.aborted) {
+                        const failure = completionFailure();
+                        if (failure !== undefined)
+                            throw failure;
+                    }
                     yield chunk;
                 }
             }
             catch (cause) {
                 if (cause instanceof ArtifactReaderFailure)
                     throw cause;
-                if (signal?.aborted === true)
-                    throw new ArtifactReaderFailure("cancelled", "Mach-O slice read cancelled", { cause });
                 throw new ArtifactReaderFailure("integrity", `Could not read Mach-O slice range: ${entry.path}`, { cause });
             }
-            if (observedBytes !== size)
-                throw new ArtifactReaderFailure("integrity", `Mach-O slice size disagrees with lipo metadata: ${entry.path}`);
-            await verifySource();
+            validatingSource = true;
+            const failure = completionFailure();
+            if (failure !== undefined)
+                throw failure;
+            try {
+                await verifySource();
+                assertArtifactReadActive(signal);
+            }
+            finally {
+                validatingSource = false;
+            }
         })());
+        const onSourceError = (cause) => {
+            const completedCancellation = cause instanceof ArtifactReaderFailure &&
+                cause.reason === "cancelled" &&
+                sourceStream.readCoverage().kind === "complete" &&
+                !validatingSource
+                ? completionFailure()
+                : undefined;
+            output.destroy(completedCancellation ??
+                (cause instanceof ArtifactReaderFailure
+                    ? cause
+                    : new ArtifactReaderFailure("integrity", `Could not read Mach-O slice range: ${entry.path}`, { cause })));
+        };
+        sourceStream.on("error", onSourceError);
+        sourceStream.once("close", () => sourceStream.removeListener("error", onSourceError));
+        const onAbort = () => {
+            if (sourceStream.readCoverage().kind === "complete" &&
+                (sourceStream.errored === null ||
+                    (sourceStream.errored instanceof ArtifactReaderFailure &&
+                        sourceStream.errored.reason === "cancelled")) &&
+                !validatingSource &&
+                !output.destroyed) {
+                const failure = completionFailure();
+                if (failure !== undefined)
+                    output.destroy(failure);
+            }
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        output.once("close", () => {
+            signal?.removeEventListener("abort", onAbort);
+            if (!sourceStream.destroyed)
+                sourceStream.destroy();
+        });
+        if (signal?.aborted)
+            onAbort();
+        return output;
     }
     provenance() {
         return this.#command === undefined ? [] : [structuredClone(this.#command)];

package/dist/artifacts/NativeDmgArtifactReader.js

@@ -1,8 +1,11 @@
+import { regularFileCancellation } from "../filesystem/OwnedRegularFile.js";
 import { mkdtemp, realpath, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { ArtifactReaderFailure, } from "./ArtifactReader.js";
 import { DirectoryArtifactReader } from "./DirectoryArtifactReader.js";
+import { NonRegularFileReadError, RegularFileAdmissionFailure, openRegularFile, } from "../filesystem/RegularFile.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
 import { execFileOutput, execFileOutputFailure, } from "../process/ExecFileOutput.js";
 import { parseNativeDmgAttachOutput, parseNativeDmgInfo, resolveNativeDmgOwnership, } from "./NativeDmgOwnership.js";
 const HDIUTIL_COMMAND_TIMEOUT_MS = 120_000;
@@ -14,12 +17,14 @@ class NativeDmgCommandFailure extends ArtifactReaderFailure {
     stdout;
     processNotStarted;
     verifyDiagnostic;
+    unrecognizedImage;
     exitCode;
     constructor(failure, message, stdout, options) {
         super(failure.reason, message, options?.cause === undefined ? undefined : { cause: options.cause });
         this.stdout = stdout;
         this.processNotStarted = options?.processNotStarted ?? false;
         this.verifyDiagnostic = failure.verifyDiagnostic;
+        this.unrecognizedImage = failure.unrecognizedImage ?? false;
         this.exitCode = options?.exitCode ?? null;
     }
 }
@@ -70,6 +75,7 @@ export class NativeDmgArtifactReader {
     #closed = false;
     #closePromise;
     #activeDirectoryOperations = new Set();
+    #verificationProbeHandle;
     constructor(path, environment, host) {
         this.path = path;
         if (process.platform !== "darwin" && host === undefined)
@@ -126,6 +132,7 @@ export class NativeDmgArtifactReader {
     async #closeOwnedResources() {
         await this.#initialization?.catch(() => undefined);
         await Promise.allSettled(this.#activeDirectoryOperations);
+        await this.#closeVerificationProbeHandle();
         await this.#closeMountedDirectory();
         let detachFailure = await this.#detachOwnedDevices();
         if (this.#devices.length === 0 &&
@@ -160,6 +167,18 @@ export class NativeDmgArtifactReader {
                 },
             });
     }
+    async #closeVerificationProbeHandle() {
+        const owner = this.#verificationProbeHandle;
+        if (owner === undefined)
+            return;
+        try {
+            await owner.close();
+            this.#verificationProbeHandle = undefined;
+        }
+        catch (cause) {
+            throw ArtifactReaderFailure.withCleanup(cause, ArtifactReaderFailure.cleanupObservation(cause, `DMG verification target descriptor ${this.path}`));
+        }
+    }
     async #detachOwnedDevices() {
         let detachFailure = await this.#reconcileAttachState();
         let remainingDevices = [];
@@ -336,8 +355,7 @@ export class NativeDmgArtifactReader {
         const arguments_ = ["verify", this.path];
         const deadline = performance.now() + HDIUTIL_COMMAND_TIMEOUT_MS;
         for (let attempt = 0;; attempt += 1) {
-            if (signal?.aborted === true)
-                throw new NativeDmgCommandFailure({ reason: "cancelled" }, "DMG operation cancelled", "", { cause: signal.reason });
+            this.#throwIfVerificationCancelled(signal);
             try {
                 await runChecked(this.host, arguments_, signal, {
                     timeoutMs: Math.max(1, Math.ceil(deadline - performance.now())),
@@ -349,9 +367,22 @@ export class NativeDmgArtifactReader {
                 if (!(cause instanceof NativeDmgCommandFailure))
                     throw cause;
                 this.#provenance.push(command(arguments_, ["read"], cause.exitCode));
+                if (cause.unrecognizedImage) {
+                    const unreadable = await this.#isUnreadableTarget(signal, cause);
+                    this.#throwIfVerificationCancelled(signal);
+                    if (unreadable)
+                        throw new NativeDmgCommandFailure({ reason: "io" }, cause.message, cause.stdout, {
+                            cause: cause.cause,
+                            ...(cause.exitCode === null
+                                ? {}
+                                : { exitCode: cause.exitCode }),
+                        });
+                }
                 const delayMs = VERIFY_SETTLE_DELAYS_MS[attempt];
-                // Retry only the producer's explicit transient diagnostic, before any mount.
-                if (cause.verifyDiagnostic !== "Resource temporarily unavailable" ||
+                // Retry only the producer's explicit transient diagnostic, or a localized
+                // refusal of a readable target that may be the same, before any mount.
+                if ((cause.verifyDiagnostic !== "Resource temporarily unavailable" &&
+                    !cause.unrecognizedImage) ||
                     delayMs === undefined ||
                     deadline - performance.now() <= delayMs)
                     throw cause;
@@ -398,6 +429,52 @@ export class NativeDmgArtifactReader {
         this.#devices = [];
         return "none";
     }
+    #cancelledVerification(cause) {
+        return new NativeDmgCommandFailure({ reason: "cancelled" }, "DMG operation cancelled", "", { cause });
+    }
+    #throwIfVerificationCancelled(signal) {
+        if (signal?.aborted === true)
+            throw this.#cancelledVerification(signal.reason);
+    }
+    async #isUnreadableTarget(signal, primaryFailure) {
+        let handle;
+        try {
+            handle = await openRegularFile(this.path, {
+                symlinks: "follow",
+                ...(signal === undefined ? {} : { signal }),
+            });
+        }
+        catch (cause) {
+            if (cause instanceof RegularFileAdmissionFailure) {
+                this.#verificationProbeHandle = cause.owner;
+                const cancellation = regularFileCancellation(cause.cause);
+                const failure = cancellation === undefined
+                    ? primaryFailure
+                    : this.#cancelledVerification(cancellation.reason);
+                throw ArtifactReaderFailure.withCleanup(failure, ArtifactReaderFailure.cleanupObservation(cause.cleanupCause, `DMG verification target descriptor ${this.path}`));
+            }
+            const cancellation = regularFileCancellation(cause);
+            if (cancellation !== undefined)
+                throw this.#cancelledVerification(cancellation.reason);
+            if (cause instanceof NonRegularFileReadError)
+                return false;
+            return classifyCommandFailure(cause, undefined).reason === "io";
+        }
+        const owner = new OwnedFileHandle(handle);
+        this.#verificationProbeHandle = owner;
+        try {
+            await owner.close();
+            this.#verificationProbeHandle = undefined;
+        }
+        catch (cause) {
+            throw ArtifactReaderFailure.withCleanup(signal?.aborted === true
+                ? this.#cancelledVerification(signal.reason)
+                : primaryFailure, ArtifactReaderFailure.cleanupObservation(cause, `DMG verification target descriptor ${this.path}`));
+        }
+        if (signal?.aborted === true)
+            throw this.#cancelledVerification(signal.reason);
+        return false;
+    }
 }
 const failureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
 const processNotStarted = (cause) => {
@@ -496,11 +573,7 @@ const classifyCommandFailure = (cause, operation) => {
     if (typeof code === "number" || typeof exitCode === "number") {
         if (operation !== "verify")
             return { reason: "unavailable" };
-        const diagnostic = verifyFailureDiagnostic(processOutput(cause, "stdout"), processOutput(cause, "stderr"));
-        return {
-            reason: verifyFailureReason(diagnostic),
-            ...(diagnostic === undefined ? {} : { verifyDiagnostic: diagnostic }),
-        };
+        return classifyVerifyFailure(processOutput(cause, "stdout"), processOutput(cause, "stderr"));
     }
     if (code === "ENOENT") {
         const syscall = Reflect.get(cause, "syscall");
@@ -522,6 +595,18 @@ const classifyCommandFailure = (cause, operation) => {
         return { reason: "io" };
     return { reason: "unavailable" };
 };
+const classifyVerifyFailure = (stdout, stderr) => {
+    const diagnostic = verifyFailureDiagnostic(stdout, stderr);
+    const reason = verifyFailureReason(diagnostic);
+    const untranslated = reason === undefined
+        ? untranslatedVerifyFailure(stdout, stderr)
+        : undefined;
+    return {
+        ...untranslated,
+        reason: reason ?? untranslated?.reason ?? "unavailable",
+        ...(diagnostic === undefined ? {} : { verifyDiagnostic: diagnostic }),
+    };
+};
 const verifyFailureReason = (diagnostic) => {
     switch (diagnostic) {
         // hdiutil follows AppleLanguages, so en-GB and en-AU spell it "recognised".
@@ -535,18 +620,32 @@ const verifyFailureReason = (diagnostic) => {
         case "Permission denied":
         case "Input/output error":
             return "io";
-        default:
+        case "Resource temporarily unavailable":
             return "unavailable";
+        default:
+            return undefined;
     }
 };
 const verifyFailureDiagnostic = (stdout, stderr) => {
     const prefix = "hdiutil: verify failed - ";
-    return `${stdout}\n${stderr}`
-        .split(/\r?\n/u)
-        .map((line) => line.trim())
+    return outputLines(stdout, stderr)
         .find((line) => line.startsWith(prefix))
         ?.slice(prefix.length);
 };
+// hdiutil localizes the trailing failure reason but not its own status lines.
+const INVALID_CHECKSUM_LINE = /^hdiutil: verify: checksum of ".*" is INVALID$/u;
+const UNRECOGNIZED_IMAGE_LINE = /^hdiutil: verify: unable to recognize ".*" as a disk image\./u;
+const untranslatedVerifyFailure = (stdout, stderr) => {
+    const lines = outputLines(stdout, stderr);
+    if (lines.some((line) => INVALID_CHECKSUM_LINE.test(line)))
+        return { reason: "integrity" };
+    // Malformed, unreadable and transiently busy targets all produce this line;
+    // only the localized reason distinguishes them, so the cause stays unknown.
+    if (lines.some((line) => UNRECOGNIZED_IMAGE_LINE.test(line)))
+        return { reason: "unavailable", unrecognizedImage: true };
+    return undefined;
+};
+const outputLines = (stdout, stderr) => `${stdout}\n${stderr}`.split(/\r?\n/u).map((line) => line.trim());
 const command = (arguments_, effects, exitCode = 0) => ({
     tool: "/usr/bin/hdiutil",
     arguments: [...arguments_],

package/dist/artifacts/SafeOutputTree.js

@@ -1,10 +1,11 @@
 import { createHash } from "node:crypto";
 import { constants } from "node:fs";
 import { mkdir, open, readdir, realpath, } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join } from "node:path";
 import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
 import { streamChunkToBuffer } from "./StreamBytes.js";
 import { ArtifactPathRegistry, destinationCaseCollisionMessage, normalizeArtifactPath, } from "./ArtifactPaths.js";
+import { absoluteCallerPath } from "../filesystem/callerPath.js";
 import { ArtifactReaderFailure } from "./ArtifactReader.js";
 import { SafeOutputTreeCreationFailure } from "./SafeOutputTreeCreationFailure.js";
 import { hashOutputFile } from "./SafeOutputTreeReadback.js";
@@ -44,7 +45,8 @@ export class SafeOutputTree {
     static async create(outputRoot, platform = process.platform) {
         if (!isAbsolute(outputRoot))
             throw new ArtifactReaderFailure("path", "Extraction output root must be absolute");
-        const requested = resolve(outputRoot);
+        // Path syntax follows the host; `platform` selects only the name policy.
+        const requested = absoluteCallerPath(outputRoot);
         const name = basename(requested);
         if (name === "." || name === "..")
             throw new ArtifactReaderFailure("path", "Invalid extraction output root");
@@ -393,7 +395,7 @@ const normalizeDestinationPath = (relativePath, platform) => {
 };
 const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)
-        throw new ArtifactReaderFailure("cancelled", "Artifact extraction cancelled");
+        throw new ArtifactReaderFailure("cancelled", "Artifact extraction cancelled", { cause: signal.reason });
 };
 const isCancellationFailure = (cause) => cause instanceof ArtifactReaderFailure && cause.reason === "cancelled";
 const isAlreadyExists = (cause) => cause instanceof Error && "code" in cause && cause.code === "EEXIST";

package/dist/artifacts/SafeOutputTreeCreationFailure.js

@@ -8,6 +8,7 @@ export class SafeOutputTreeCreationFailure extends ArtifactReaderFailure {
             : new ArtifactReaderFailure("io", errorMessage(cause), { cause });
         super(primary.reason, primary.message, {
             cause: primary,
+            cancellation: primary.cancellation,
             ...(primary.cleanup === undefined ? {} : { cleanup: primary.cleanup }),
             ...(primary.partialObservation === undefined
                 ? {}

package/dist/artifacts/SafeOutputTreeReadback.js

@@ -1,10 +1,12 @@
 import { createHash } from "node:crypto";
-import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
+import { readArtifactFileChunks } from "./readArtifactFileChunks.js";
+import { assertArtifactReadActive } from "./ArtifactFileOperation.js";
 import { streamChunkToBuffer } from "./StreamBytes.js";
 import { ArtifactReaderFailure } from "./ArtifactReader.js";
 import { assertFilePathIdentity, readFileIdentity, } from "./SafeOutputTreeIdentity.js";
 /** Hash one retained readback descriptor and confirm it still names the output file. */
 export const hashOutputFile = async (owner, path, identity, options) => {
+    assertArtifactReadActive(options.signal);
     const admittedIdentity = await readFileIdentity(owner.handle, path);
     await assertFilePathIdentity(path, identity);
     if (admittedIdentity.dev !== identity.dev ||
@@ -12,22 +14,14 @@ export const hashOutputFile = async (owner, path, identity, options) => {
         throw new ArtifactReaderFailure("path", `Extraction file identity changed: ${path}`);
     const hash = createHash("sha256");
     let bytes = 0;
-    try {
-        for await (const raw of readFileHandleChunks(owner.handle, options)) {
-            if (options.signal?.aborted === true)
-                throw new ArtifactReaderFailure("cancelled", "Artifact extraction cancelled");
-            const chunk = streamChunkToBuffer(raw);
-            bytes += chunk.length;
-            if (bytes > options.maximum)
-                throw new ArtifactReaderFailure("integrity", "Readback exceeded the bytes written");
-            hash.update(chunk);
-        }
-    }
-    catch (cause) {
-        if (options.signal?.aborted === true)
-            throw new ArtifactReaderFailure("cancelled", "Artifact extraction cancelled", { cause });
-        throw cause;
+    for await (const raw of readArtifactFileChunks(owner.handle, options)) {
+        const chunk = streamChunkToBuffer(raw);
+        bytes += chunk.length;
+        if (bytes > options.maximum)
+            throw new ArtifactReaderFailure("integrity", "Readback exceeded the bytes written");
+        hash.update(chunk);
     }
     await assertFilePathIdentity(path, identity);
+    assertArtifactReadActive(options.signal);
     return { sha256: hash.digest("hex"), bytes };
 };

package/dist/artifacts/ZipArtifactReader.js

@@ -1,3 +1,4 @@
+import { assertArtifactReadActive } from "./ArtifactFileOperation.js";
 import { PassThrough } from "node:stream";
 import { once } from "node:events";
 import { ERR_AMBIGUOUS_ARCHIVE, ERR_BAD_FORMAT, ERR_CENTRAL_DIRECTORY_NOT_FOUND, ERR_ENCRYPTED_CENTRAL_DIRECTORY, ERR_ENTRY_DATA_OUT_OF_BOUNDS, ERR_EOCDR_LOCATOR_ZIP64_NOT_FOUND, ERR_EOCDR_NOT_FOUND, ERR_EXTRAFIELD_ZIP64_NOT_FOUND, ERR_INVALID_COMPRESSED_DATA, ERR_INVALID_CRC32, ERR_INVALID_UNCOMPRESSED_SIZE, ERR_LOCAL_FILE_HEADER_NOT_FOUND, ERR_OVERLAPPING_ENTRY, ERR_SPLIT_ZIP_FILE, ERR_UNSUPPORTED_COMPRESSION, ERR_UNSUPPORTED_ENCRYPTION, ERR_UNSUPPORTED_UINT64, Reader, ZipReader, } from "@zip.js/zip.js";
@@ -60,6 +61,10 @@ class NodeFileReader extends Reader {
         if (handle === undefined)
             throw new Error("ZIP reader is not initialized");
         const readBytes = Math.min(length, this.size - index);
+        // A central-directory offset can point past EOF. Type that malformed ZIP
+        // read before a negative size reaches Buffer.alloc and becomes an I/O error.
+        if (readBytes < 0)
+            throw new ArtifactReaderFailure("format", `ZIP archive is malformed: read at ${index} extends beyond the ${this.size}-byte archive`);
         if (this.maximumReadBytes !== undefined &&
             readBytes > this.maximumReadBytes)
             throw new ArtifactReaderFailure("limit", `ZIP metadata read requires ${readBytes} bytes, exceeding the ${this.maximumReadBytes}-byte read budget`);
@@ -104,10 +109,12 @@ export class ZipArtifactReader {
         // A traversal owns its accounting, including overlapping or repeated passes.
         let declaredFileBytes = 0;
         for await (const entry of typedZipFailures(this.#reader.getEntriesGenerator({ decodeText: decodeZipEntryText }))) {
-            abortIfNeeded(signal);
+            assertArtifactReadActive(signal);
             // ZIP member identity is its directory occurrence, not its filename.
             // Logical path uniqueness belongs to the artifact inventory boundary.
             const metadata = projectZipEntry(entry, index++);
+            if (metadata === undefined)
+                continue;
             // zip.js enforces each member's declared output size, so this sum bounds streamed work.
             if (metadata.kind === "file" &&
                 !metadata.encrypted &&
@@ -131,7 +138,7 @@ export class ZipArtifactReader {
         }
     }
     open(entry, signal) {
-        abortIfNeeded(signal);
+        assertArtifactReadActive(signal);
         const stored = this.#entries.get(entry.adapterKey);
         if (stored === undefined || !sameArtifactEntry(entry, stored.metadata))
             return Promise.reject(new ArtifactReaderFailure("integrity", "ZIP entry metadata does not match this reader's inventory"));
@@ -152,18 +159,35 @@ export class ZipArtifactReader {
     }
 }
 const projectZipEntry = (entry, index) => {
-    const symlink = isSymlink(entry);
+    const kind = isSymlink(entry)
+        ? "symlink"
+        : entry.directory
+            ? "directory"
+            : "file";
+    const sourcePath = zipEntryPath(entry);
+    const path = sourcePath.replace(/^(?:\.\/)+/u, "");
+    // Root directory markers carry no inventory occurrence. A file with this
+    // spelling is still passed to the shared path validator and rejected there.
+    if (kind === "directory" && (path === "" || path === "."))
+        return undefined;
     return {
-        path: zipEntryPath(entry),
-        kind: entry.directory ? "directory" : symlink ? "symlink" : "file",
-        declaredSize: entry.directory ? null : entry.uncompressedSize,
-        compressedSize: entry.directory ? null : entry.compressedSize,
+        path,
+        kind,
+        declaredSize: kind === "directory" ? null : entry.uncompressedSize,
+        compressedSize: kind === "directory" ? null : entry.compressedSize,
         executable: entry.executable,
         encrypted: entry.encrypted,
         byteOffset: null,
         declaredSha256: null,
         unpacked: false,
-        limitations: symlink ? ["Archive symlink target was not read."] : [],
+        limitations: [
+            ...(kind === "symlink" ? ["Archive symlink target was not read."] : []),
+            ...(path === sourcePath
+                ? []
+                : [
+                    `ZIP member name ${JSON.stringify(sourcePath)} has a leading current-directory prefix omitted from its logical path.`,
+                ]),
+        ],
         adapterKey: `zip-entry:${index}`,
     };
 };
@@ -221,7 +245,7 @@ const extractStream = (entry, signal) => {
     });
     const writable = new WritableStream({
         write: async (chunk) => {
-            abortIfNeeded(signal);
+            assertArtifactReadActive(signal);
             if (!output.write(Buffer.from(chunk)))
                 await once(output, "drain", { signal: controller.signal });
         },
@@ -237,7 +261,7 @@ const extractStream = (entry, signal) => {
         signal: controller.signal,
         checkSignature: true,
         checkOverlappingEntry: true,
-        onprogress: () => abortIfNeeded(signal),
+        onprogress: () => assertArtifactReadActive(signal),
     })
         .catch((cause) => output.destroy(toError(typedZipFailure(cause))));
     return output;
@@ -286,8 +310,4 @@ async function* typedZipFailures(source) {
     }
 }
 const isSymlink = (entry) => entry.unixMode !== undefined && (entry.unixMode & 0o170000) === 0o120000;
-const abortIfNeeded = (signal) => {
-    if (signal?.aborted === true)
-        throw new ArtifactReaderFailure("cancelled", "ZIP operation cancelled");
-};
 const toError = (cause) => cause instanceof Error ? cause : new Error("ZIP extraction failed");

package/dist/artifacts/apple/AppleAssetCatalogAnalysis.js

@@ -79,7 +79,9 @@ const collectAssetCatalogs = async (input) => {
     let totalMetadataBytes = 0;
     try {
         for await (const entry of reader.entries(input.signal)) {
-            if (!entry.path.endsWith("Assets.car"))
+            // Reader paths are `/`-separated; only an entry named exactly
+            // Assets.car is a compiled catalog, not e.g. NotAssets.car.
+            if (entry.path.split("/").at(-1) !== "Assets.car")
                 continue;
             if (entry.kind !== "file") {
                 uninspected.push(`${entry.path} (${entry.kind})`);

package/dist/artifacts/apple/DylibFileAccess.js

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { isAbsolute, relative, sep } from "node:path";
+import { NonRegularFileReadError, sameRegularFileState, } from "../../filesystem/RegularFile.js";
+import { ArtifactReaderFailure, sameArtifactSourceIdentity, } from "../ArtifactReader.js";
+import { assertArtifactReadActive, mapArtifactFileFailure, withArtifactRegularFile, } from "../ArtifactFileOperation.js";
+import { readArtifactFileChunks } from "../readArtifactFileChunks.js";
+import { hasMachoMagic, readMachoImage } from "./MachoLoadCommandReader.js";
+/** One owner for dyld descriptor admission, physical identity and finalization. */
+export class DylibFileAccess {
+    resources;
+    root;
+    signal;
+    constructor(resources, root, signal) {
+        this.resources = resources;
+        this.root = root;
+        this.signal = signal;
+    }
+    startsWithMachoMagic(entry) {
+        return this.#read(entry.adapterKey, async (file, initial) => {
+            if (!sameArtifactSourceIdentity(entry.sourceIdentity, initial))
+                throw changed(entry.adapterKey);
+            const bytes = new Uint8Array(4);
+            const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
+            return hasMachoMagic(bytes.subarray(0, bytesRead));
+        });
+    }
+    image(path) {
+        return this.#read(path, async (file, identity) => {
+            const size = Number(identity.size);
+            if (!Number.isSafeInteger(size))
+                throw new ArtifactReaderFailure("limit", `Mach-O file extent is not safely addressable: ${path}`);
+            const facts = await readMachoImage(async (offset, length) => {
+                assertArtifactReadActive(this.signal);
+                const bytes = new Uint8Array(Math.max(0, Math.min(length, size - offset)));
+                const { bytesRead } = await file.read(bytes, 0, bytes.length, offset);
+                assertArtifactReadActive(this.signal);
+                return bytes.subarray(0, bytesRead);
+            }, size);
+            return { facts, identity };
+        });
+    }
+    sha256(path, expected) {
+        return this.#read(path, async (file, initial) => {
+            if (expected !== undefined && !sameRegularFileState(expected, initial))
+                throw changed(path);
+            const hash = createHash("sha256");
+            // Admit the extent plus one byte to detect growth without following an
+            // actively appended file indefinitely. The descriptor remains owned.
+            const source = readArtifactFileChunks(file, {
+                end: initial.size,
+                signal: this.signal,
+            });
+            for await (const chunk of source)
+                hash.update(chunk);
+            const coverage = source.readCoverage();
+            if (coverage.kind !== "complete" || coverage.bytes !== initial.size)
+                throw changed(path);
+            return hash.digest("hex");
+        });
+    }
+    async #read(path, operation) {
+        try {
+            return await withArtifactRegularFile(path, this.resources, this.signal, async (file) => {
+                const initial = await file.stat({ bigint: true });
+                assertArtifactReadActive(this.signal);
+                const result = await operation(file, initial);
+                // Parsed headers, magic and digest must refer to the same physical
+                // version still selected by the pathname when the read completes.
+                const opened = await file.stat({ bigint: true });
+                const named = await lstat(path, { bigint: true });
+                if (!sameRegularFileState(initial, opened) ||
+                    !sameRegularFileState(initial, named))
+                    throw changed(path);
+                assertArtifactReadActive(this.signal);
+                return result;
+            });
+        }
+        catch (cause) {
+            throw classifyDylibReadFailure(this.root, cause);
+        }
+    }
+}
+/** Normalize dyld admission and permission facts inside their physical outcome. */
+export const classifyDylibReadFailure = (root, cause) => mapArtifactFileFailure(cause, (primary) => {
+    if (primary instanceof NonRegularFileReadError)
+        return new ArtifactReaderFailure("format", `Dyld input is not a regular file: ${primary.path}`, { cause: primary });
+    if (primary instanceof Error &&
+        "code" in primary &&
+        (primary.code === "EACCES" || primary.code === "EPERM")) {
+        const path = "path" in primary && typeof primary.path === "string"
+            ? primary.path
+            : undefined;
+        const display = path === undefined
+            ? "a file in the analyzed root"
+            : deniedDisplayPath(root, path);
+        return new ArtifactReaderFailure("unavailable", `Permission denied (${primary.code}) reading ${display}`, { cause: primary });
+    }
+    return primary;
+});
+const deniedDisplayPath = (root, path) => {
+    const inside = relative(root, path);
+    const outside = isAbsolute(inside) || inside === ".." || inside.startsWith(`..${sep}`);
+    return inside === "" || outside ? path : inside;
+};
+const changed = (path) => new ArtifactReaderFailure("integrity", `${path} changed while its dyld load commands were traced`);