rea-agents 6.4.0 → 6.5.0

package/dist/artifacts/NativeDmgArtifactReader.js

@@ -6,16 +6,21 @@ import { DirectoryArtifactReader } from "./DirectoryArtifactReader.js";
 import { execFileOutput, execFileOutputFailure, } from "../process/ExecFileOutput.js";
 import { parseNativeDmgAttachOutput, parseNativeDmgInfo, resolveNativeDmgOwnership, } from "./NativeDmgOwnership.js";
 const HDIUTIL_COMMAND_TIMEOUT_MS = 120_000;
+const VERIFY_SETTLE_DELAYS_MS = [250, 500];
 // APFS ejects and busy reporting can lag a detach attempt.
 const DETACH_SETTLE_DELAYS_MS = [250, 500, 1000];
 const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
 class NativeDmgCommandFailure extends ArtifactReaderFailure {
     stdout;
     processNotStarted;
-    constructor(reason, message, stdout, options) {
-        super(reason, message, options?.cause === undefined ? undefined : { cause: options.cause });
+    verifyDiagnostic;
+    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.exitCode = options?.exitCode ?? null;
     }
 }
 const createSystemHost = (environment) => ({
@@ -33,7 +38,7 @@ const createSystemHost = (environment) => ({
         catch (cause) {
             const output = execFileOutputFailure(cause);
             if (cause instanceof Error && cause.name === "AbortError")
-                throw new NativeDmgCommandFailure("cancelled", "DMG operation cancelled", output?.stdout ?? "", { cause });
+                throw new NativeDmgCommandFailure({ reason: "cancelled" }, "DMG operation cancelled", output?.stdout ?? "", { cause });
             const exitCode = typeof output?.code === "number" ? output.code : processExitCode(cause);
             if (exitCode !== undefined)
                 return {
@@ -42,7 +47,7 @@ const createSystemHost = (environment) => ({
                     exitCode,
                     cause,
                 };
-            throw new NativeDmgCommandFailure(commandFailureReason(cause, arguments_[0]), `hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(cause, arguments_)}`, output?.stdout ?? "", { cause, processNotStarted: processNotStarted(cause) });
+            throw new NativeDmgCommandFailure(classifyCommandFailure(cause, arguments_[0]), `hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(cause, arguments_)}`, output?.stdout ?? "", { cause, processNotStarted: processNotStarted(cause) });
         }
     },
 });
@@ -64,25 +69,48 @@ export class NativeDmgArtifactReader {
     #ownershipUncertainty;
     #closed = false;
     #closePromise;
+    #activeDirectoryOperations = new Set();
     constructor(path, environment, host) {
         this.path = path;
         if (process.platform !== "darwin" && host === undefined)
             throw new ArtifactReaderFailure("unavailable", "Native DMG traversal is available only on macOS");
         this.host = host ?? createSystemHost(environment);
     }
-    async *entries(signal) {
+    async *entries(signal, options) {
         await this.#ensureAttached(signal);
-        if (this.#directory === undefined)
+        const directory = this.#directory;
+        if (directory === undefined)
             throw new ArtifactReaderFailure("unavailable", "DMG is not attached");
         const prefix = basename(this.path);
-        for await (const entry of this.#directory.entries(signal))
-            yield { ...entry, path: `${prefix}/${entry.path}` };
+        const entries = directory
+            .entries(signal, {
+            onOmission: (omission) => options?.onOmission?.({
+                ...omission,
+                path: `${prefix}/${omission.path}`,
+            }),
+        })[Symbol.asyncIterator]();
+        try {
+            for (;;) {
+                if (this.#closed)
+                    return;
+                const next = await this.#trackDirectoryOperation(() => entries.next());
+                if (this.#closed)
+                    return;
+                if (next.done)
+                    return;
+                yield { ...next.value, path: `${prefix}/${next.value.path}` };
+            }
+        }
+        finally {
+            await entries.return?.();
+        }
     }
     async open(entry, signal) {
         await this.#ensureAttached(signal);
-        if (this.#directory === undefined)
+        const directory = this.#directory;
+        if (directory === undefined)
             throw new ArtifactReaderFailure("unavailable", "DMG is not attached");
-        return this.#directory.open(entry, signal);
+        return this.#trackDirectoryOperation(() => directory.open(entry, signal));
     }
     provenance() {
         return structuredClone(this.#provenance);
@@ -97,6 +125,42 @@ export class NativeDmgArtifactReader {
     }
     async #closeOwnedResources() {
         await this.#initialization?.catch(() => undefined);
+        await Promise.allSettled(this.#activeDirectoryOperations);
+        await this.#closeMountedDirectory();
+        let detachFailure = await this.#detachOwnedDevices();
+        if (this.#devices.length === 0 &&
+            this.#mountRoot !== undefined &&
+            !this.#attachMayHaveMounted)
+            await rm(this.#mountRoot, { recursive: true, force: true }).then(() => {
+                this.#mountRoot = undefined;
+                this.#directory = undefined;
+            }, (cause) => {
+                detachFailure ??= cause;
+            });
+        if (this.#attachMayHaveMounted) {
+            detachFailure ??= new Error(this.#ownershipUncertainty ??
+                "hdiutil attachment ownership remains unknown");
+        }
+        if (detachFailure !== undefined)
+            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.#attachMayHaveMounted
+                            ? [
+                                `DMG attachment ownership unknown at mount root ${this.#mountRoot ?? this.path}`,
+                            ]
+                            : []),
+                        ...(this.#mountRoot === undefined
+                            ? []
+                            : [`DMG mount root ${this.#mountRoot}`]),
+                    ],
+                },
+            });
+    }
+    async #detachOwnedDevices() {
         let detachFailure = await this.#reconcileAttachState();
         let remainingDevices = [];
         for (const device of [...this.#devices].reverse()) {
@@ -126,37 +190,26 @@ export class NativeDmgArtifactReader {
         if (remainingDevices.length === 0)
             detachFailure = undefined;
         this.#devices = remainingDevices.reverse();
-        if (this.#devices.length === 0 &&
-            this.#mountRoot !== undefined &&
-            !this.#attachMayHaveMounted)
-            await rm(this.#mountRoot, { recursive: true, force: true }).then(() => {
-                this.#mountRoot = undefined;
+        return detachFailure;
+    }
+    async #closeMountedDirectory() {
+        if (this.#directory !== undefined) {
+            try {
+                await this.#directory.close();
                 this.#directory = undefined;
-            }, (cause) => {
-                detachFailure ??= cause;
-            });
-        if (this.#attachMayHaveMounted) {
-            detachFailure ??= new Error(this.#ownershipUncertainty ??
-                "hdiutil attachment ownership remains unknown");
-        }
-        if (detachFailure !== undefined)
-            throw new ArtifactReaderFailure("unavailable", `DMG detach or mount-root cleanup failed for ${JSON.stringify(this.path)}: ${failureMessage(detachFailure)}`, {
-                cause: detachFailure,
-                cleanup: {
-                    reason: failureMessage(detachFailure),
+            }
+            catch (cause) {
+                const mountRoot = this.#mountRoot ?? this.path;
+                throw ArtifactReaderFailure.withCleanup(cause, {
+                    reason: `DMG mounted directory remains owned: ${failureMessage(cause)}`,
                     resources: [
+                        `DMG mounted directory at ${mountRoot}`,
+                        `DMG mount root ${mountRoot}`,
                         ...this.#devices.map((device) => `DMG device ${device}`),
-                        ...(this.#attachMayHaveMounted
-                            ? [
-                                `DMG attachment ownership unknown at mount root ${this.#mountRoot ?? this.path}`,
-                            ]
-                            : []),
-                        ...(this.#mountRoot === undefined
-                            ? []
-                            : [`DMG mount root ${this.#mountRoot}`]),
                     ],
-                },
-            });
+                });
+            }
+        }
     }
     /** Detach one device; return the failure only while it remains attached. */
     async #detach(device) {
@@ -206,9 +259,20 @@ export class NativeDmgArtifactReader {
         if (this.#closed)
             throw new ArtifactReaderFailure("unavailable", "DMG reader is closed");
     }
+    async #trackDirectoryOperation(operation) {
+        if (this.#closed)
+            throw new ArtifactReaderFailure("unavailable", "DMG reader is closed");
+        const running = Promise.resolve().then(operation);
+        this.#activeDirectoryOperations.add(running);
+        try {
+            return await running;
+        }
+        finally {
+            this.#activeDirectoryOperations.delete(running);
+        }
+    }
     async #attach(signal) {
-        await runChecked(this.host, ["verify", this.path], signal);
-        this.#provenance.push(command(["verify", this.path], ["read"]));
+        await this.#verify(signal);
         const baseline = await this.#readInfo();
         this.#baselineDevices = new Set(baseline.images.flatMap((image) => image["system-entities"].map(({ "dev-entry": device }) => device)));
         const mountRoot = await realpath(await mkdtemp(join(tmpdir(), "rea-dmg-")));
@@ -268,6 +332,35 @@ export class NativeDmgArtifactReader {
             throw cause;
         }
     }
+    async #verify(signal) {
+        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 });
+            try {
+                await runChecked(this.host, arguments_, signal, {
+                    timeoutMs: Math.max(1, Math.ceil(deadline - performance.now())),
+                });
+                this.#provenance.push(command(arguments_, ["read"]));
+                return;
+            }
+            catch (cause) {
+                if (!(cause instanceof NativeDmgCommandFailure))
+                    throw cause;
+                this.#provenance.push(command(arguments_, ["read"], 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" ||
+                    delayMs === undefined ||
+                    deadline - performance.now() <= delayMs)
+                    throw cause;
+                await (this.host.delay ?? delay)(delayMs);
+                if (performance.now() >= deadline)
+                    throw cause;
+            }
+        }
+    }
     async #readInfo() {
         const info = await runChecked(this.host, ["info", "-plist"], undefined, {
             timeoutMs: HDIUTIL_COMMAND_TIMEOUT_MS,
@@ -328,9 +421,9 @@ const runChecked = async (host, arguments_, signal, options) => {
         if (cause instanceof ArtifactReaderFailure)
             throw cause;
         if (cause instanceof Error && cause.name === "AbortError")
-            throw new NativeDmgCommandFailure("cancelled", "DMG operation cancelled", execFileOutputFailure(cause)?.stdout ?? "", { cause });
+            throw new NativeDmgCommandFailure({ reason: "cancelled" }, "DMG operation cancelled", execFileOutputFailure(cause)?.stdout ?? "", { cause });
         const output = execFileOutputFailure(cause);
-        throw new NativeDmgCommandFailure(commandFailureReason(cause, arguments_[0]), `hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(cause, arguments_)}`, output?.stdout ?? "", { cause, processNotStarted: processNotStarted(cause) });
+        throw new NativeDmgCommandFailure(classifyCommandFailure(cause, arguments_[0]), `hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(cause, arguments_)}`, output?.stdout ?? "", { cause, processNotStarted: processNotStarted(cause) });
     }
     if (result.exitCode !== 0) {
         const failure = {
@@ -342,12 +435,12 @@ const runChecked = async (host, arguments_, signal, options) => {
             stdout: result.stdout,
             ...(result.stderr === undefined ? {} : { stderr: result.stderr }),
         };
-        const reason = commandFailureReason(failure, arguments_[0]);
+        const classification = classifyCommandFailure(failure, arguments_[0]);
         const details = describeCommandFailure(failure, arguments_);
-        const unknownVerifyFailure = arguments_[0] === "verify" && reason === "unavailable";
-        throw new NativeDmgCommandFailure(reason, unknownVerifyFailure
+        const unknownVerifyFailure = arguments_[0] === "verify" && classification.reason === "unavailable";
+        throw new NativeDmgCommandFailure(classification, unknownVerifyFailure
             ? `hdiutil verify failed; captured diagnostics do not establish the failure cause: ${details}`
-            : `hdiutil ${arguments_[0] ?? "operation"} failed: ${details}`, result.stdout, { cause: result.cause ?? failure });
+            : `hdiutil ${arguments_[0] ?? "operation"} failed: ${details}`, result.stdout, { cause: result.cause ?? failure, exitCode: result.exitCode });
     }
     return { stdout: result.stdout, exitCode: 0 };
 };
@@ -395,18 +488,27 @@ const processOutput = (cause, field) => {
     const value = Reflect.get(cause, field);
     return typeof value === "string" ? value : "";
 };
-const commandFailureReason = (cause, operation) => {
+const classifyCommandFailure = (cause, operation) => {
     if (typeof cause !== "object" || cause === null)
-        return "unavailable";
+        return { reason: "unavailable" };
     const code = Reflect.get(cause, "code");
     const exitCode = Reflect.get(cause, "exitCode");
-    if (typeof code === "number" || typeof exitCode === "number")
-        return operation === "verify" ? verifyFailureReason(cause) : "unavailable";
+    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 }),
+        };
+    }
     if (code === "ENOENT") {
         const syscall = Reflect.get(cause, "syscall");
-        return typeof syscall === "string" && syscall.startsWith("spawn")
-            ? "unavailable"
-            : "io";
+        return {
+            reason: typeof syscall === "string" && syscall.startsWith("spawn")
+                ? "unavailable"
+                : "io",
+        };
     }
     if (code === "EACCES" ||
         code === "EPERM" ||
@@ -417,13 +519,14 @@ const commandFailureReason = (cause, operation) => {
         code === "EROFS" ||
         code === "EMFILE" ||
         code === "ENFILE")
-        return "io";
-    return "unavailable";
+        return { reason: "io" };
+    return { reason: "unavailable" };
 };
-const verifyFailureReason = (cause) => {
-    const diagnostic = verifyFailureDiagnostic(processOutput(cause, "stdout"), processOutput(cause, "stderr"));
+const verifyFailureReason = (diagnostic) => {
     switch (diagnostic) {
+        // hdiutil follows AppleLanguages, so en-GB and en-AU spell it "recognised".
         case "image not recognized":
+        case "image not recognised":
             return "format";
         case "invalid checksum":
         case "image data corrupted":
@@ -444,11 +547,11 @@ const verifyFailureDiagnostic = (stdout, stderr) => {
         .find((line) => line.startsWith(prefix))
         ?.slice(prefix.length);
 };
-const command = (arguments_, effects) => ({
+const command = (arguments_, effects, exitCode = 0) => ({
     tool: "/usr/bin/hdiutil",
     arguments: [...arguments_],
     tool_version: null,
     executable_sha256: null,
-    exit_code: 0,
+    exit_code: exitCode,
     effects,
 });

package/dist/artifacts/OrderedReads.js

@@ -0,0 +1,57 @@
+/**
+ * Overlap independent reads with an enumeration while consuming their results
+ * in enumeration order. `read` returns undefined for items it skips. At most
+ * `width` reads are in flight. A failure is reported as a one-at-a-time loop
+ * would report it: an earlier item's read or consume failure wins over a
+ * later read failure or an enumeration failure. Every started read settles
+ * before this returns or throws, and an enumeration left early is closed as
+ * `for await` would close it.
+ */
+export const consumeWithOrderedReads = async (items, width, read, consume) => {
+    const pending = [];
+    const consumeNext = async () => {
+        const next = pending.shift();
+        if (next === undefined)
+            return;
+        const result = await next.result;
+        if (!result.ok)
+            throw result.error;
+        await consume(next.item, result.value);
+    };
+    const iterator = items[Symbol.asyncIterator]();
+    let iterating = true;
+    try {
+        while (iterating) {
+            let step;
+            try {
+                step = await iterator.next();
+            }
+            catch (cause) {
+                iterating = false;
+                while (pending.length > 0)
+                    await consumeNext();
+                throw cause;
+            }
+            if (step.done === true) {
+                iterating = false;
+                break;
+            }
+            const started = read(step.value);
+            if (started === undefined)
+                continue;
+            pending.push({
+                item: step.value,
+                result: started.then((value) => ({ ok: true, value }), (error) => ({ ok: false, error })),
+            });
+            if (pending.length >= width)
+                await consumeNext();
+        }
+        while (pending.length > 0)
+            await consumeNext();
+    }
+    finally {
+        if (iterating)
+            await iterator.return?.().catch(() => undefined);
+        await Promise.all(pending.map(({ result }) => result));
+    }
+};

package/dist/artifacts/SafeOutputTree.js

@@ -166,9 +166,11 @@ export class SafeOutputTree {
         }
     }
     /** Sync the owned output tree and prevent further writes through this instance. */
-    async commit() {
+    async commit(signal) {
         this.#assertWritable();
+        abortIfNeeded(signal);
         await this.#assertOwnedDirectories();
+        abortIfNeeded(signal);
         // Windows has no directory fsync; file contents are already synced in write().
         if (this.platform === "win32") {
             this.#published = true;
@@ -182,6 +184,7 @@ export class SafeOutputTree {
             await assertHandleIdentity(output.handle, this.#requireRootIdentity(), this.#outputRoot);
             await output.handle.sync();
             await parent.handle.sync();
+            abortIfNeeded(signal);
             this.#published = true;
         }
         catch (cause) {
@@ -196,12 +199,19 @@ export class SafeOutputTree {
         if (closeFailures.length > 0) {
             const closeFailure = new AggregateError(closeFailures, "Extraction output directory handles could not be closed");
             const cleanup = ArtifactReaderFailure.cleanupObservation(closeFailure, this.#outputRoot);
-            if (sync.kind === "failed")
-                throw ArtifactReaderFailure.withCleanup(new ArtifactReaderFailure("path", "Could not durably sync extraction output", { cause: sync.cause }), cleanup);
+            if (sync.kind === "failed") {
+                const primary = isCancellationFailure(sync.cause)
+                    ? sync.cause
+                    : new ArtifactReaderFailure("path", "Could not durably sync extraction output", { cause: sync.cause });
+                throw ArtifactReaderFailure.withCleanup(primary, cleanup);
+            }
             throw ArtifactReaderFailure.withCleanup(closeFailure, cleanup);
         }
-        if (sync.kind === "failed")
+        if (sync.kind === "failed") {
+            if (isCancellationFailure(sync.cause))
+                throw sync.cause;
             throw new ArtifactReaderFailure("path", "Could not durably sync extraction output", { cause: sync.cause });
+        }
     }
     /** Remove only this operation's unsealed tree and verify absence. */
     async rollback() {
@@ -373,14 +383,19 @@ const writeAll = async (handle, chunk) => {
 };
 const normalizeDestinationPath = (relativePath, platform) => {
     const path = normalizeArtifactPath(relativePath);
+    if (platform === "win32" && path.includes("\\"))
+        throw new ArtifactReaderFailure("path", `Windows destination cannot materialize artifact path: ${JSON.stringify(path)}; backslashes denote path separators.`);
     if (platform === "win32" && path.includes(":"))
         throw new ArtifactReaderFailure("path", `Windows destination cannot materialize artifact path as a regular file: ${path}; ':' denotes alternate data stream syntax.`);
+    if (platform === "win32" && /[\u0001-\u001f]/u.test(path))
+        throw new ArtifactReaderFailure("path", `Windows destination cannot materialize artifact path: ${JSON.stringify(path)}; Windows names cannot contain U+0001-U+001F.`);
     return path;
 };
 const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)
         throw new ArtifactReaderFailure("cancelled", "Artifact extraction cancelled");
 };
+const isCancellationFailure = (cause) => cause instanceof ArtifactReaderFailure && cause.reason === "cancelled";
 const isAlreadyExists = (cause) => cause instanceof Error && "code" in cause && cause.code === "EEXIST";
 /** Fail when this directory already holds another spelling of the requested segment. */
 const throwIfDestinationCaseCollision = async (parentDirectory, logicalPath, cause) => {

package/dist/artifacts/ZipArtifactReader.js

@@ -1,9 +1,14 @@
 import { PassThrough } from "node:stream";
 import { once } from "node:events";
-import { Reader, ZipReader } from "@zip.js/zip.js";
+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";
 import { ArtifactReaderFailure, copyArtifactEntry, sameArtifactEntry, } from "./ArtifactReader.js";
+import { ARTIFACT_DECOMPRESSION_RATIO, artifactDecompressionBudgetBytes, MINIMUM_ARTIFACT_DECOMPRESSION_BYTES, } from "../domain/artifactDecompressionBudget.js";
 import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
 import { NonRegularFileReadError, RegularFileAdmissionFailure, openRegularFile, sameRegularFileState, } from "../filesystem/RegularFile.js";
+const ZIP_UTF8_DECODER = new TextDecoder("utf-8", {
+    fatal: true,
+    ignoreBOM: true,
+});
 class NodeFileReader extends Reader {
     path;
     maximumReadBytes;
@@ -86,19 +91,42 @@ export class ZipArtifactReader {
         this.#reader = new ZipReader(this.#source, {
             checkSignature: true,
             checkOverlappingEntry: true,
+            // Unflagged names use the ZIP legacy encoding (CP437); the UTF-8 flag
+            // and validated Unicode Path extra fields remain authoritative.
+            filenameEncoding: "cp437",
             // REA applies its own provider-neutral path validation in scanReader and
             // must preserve that typed failure instead of zip.js rejecting first.
             filenameValidation: "tolerant",
         });
     }
     async *entries(signal) {
-        for await (const entry of this.#reader.getEntriesGenerator()) {
+        let index = 0;
+        // 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);
-            const metadata = projectZipEntry(entry);
-            this.#entries.set(entry.filename, {
-                source: entry,
-                metadata: copyArtifactEntry(metadata),
-            });
+            // ZIP member identity is its directory occurrence, not its filename.
+            // Logical path uniqueness belongs to the artifact inventory boundary.
+            const metadata = projectZipEntry(entry, index++);
+            // zip.js enforces each member's declared output size, so this sum bounds streamed work.
+            if (metadata.kind === "file" &&
+                !metadata.encrypted &&
+                metadata.declaredSize !== null &&
+                Number.isSafeInteger(metadata.declaredSize) &&
+                metadata.declaredSize >= 0) {
+                declaredFileBytes += metadata.declaredSize;
+                const budget = artifactDecompressionBudgetBytes(this.#source.size);
+                if (declaredFileBytes > budget)
+                    throw new ArtifactReaderFailure("limit", `ZIP entries declare ${String(declaredFileBytes)} uncompressed bytes, exceeding this archive's ${String(budget)}-byte decompression budget (${String(MINIMUM_ARTIFACT_DECOMPRESSION_BYTES)}-byte minimum, ${String(ARTIFACT_DECOMPRESSION_RATIO)}x archive size); a small archive cannot expand this far`);
+            }
+            const stored = this.#entries.get(metadata.adapterKey);
+            if (stored !== undefined && !sameArtifactEntry(metadata, stored.metadata))
+                throw new ArtifactReaderFailure("integrity", `ZIP member identity changed during enumeration: ${entry.filename}`);
+            if (stored === undefined)
+                this.#entries.set(metadata.adapterKey, {
+                    source: entry,
+                    metadata: copyArtifactEntry(metadata),
+                });
             yield metadata;
         }
     }
@@ -123,10 +151,10 @@ export class ZipArtifactReader {
         return [];
     }
 }
-const projectZipEntry = (entry) => {
+const projectZipEntry = (entry, index) => {
     const symlink = isSymlink(entry);
     return {
-        path: entry.filename,
+        path: zipEntryPath(entry),
         kind: entry.directory ? "directory" : symlink ? "symlink" : "file",
         declaredSize: entry.directory ? null : entry.uncompressedSize,
         compressedSize: entry.directory ? null : entry.compressedSize,
@@ -136,9 +164,43 @@ const projectZipEntry = (entry) => {
         declaredSha256: null,
         unpacked: false,
         limitations: symlink ? ["Archive symlink target was not read."] : [],
-        adapterKey: entry.filename,
+        adapterKey: `zip-entry:${index}`,
     };
 };
+const decodeZipEntryText = (bytes, encoding, type) => {
+    if (type !== "filename")
+        return undefined;
+    if (encoding === "utf-8")
+        return decodeStrictZipUtf8(bytes, "ZIP filename is not valid UTF-8");
+    return encoding === "cp437" ? decodeCp437(bytes) : undefined;
+};
+/** CP437 characters for bytes 0x80-0xFF. */
+const CP437_HIGH_HALF = "ÇüéâäàåçêëèïîìÄÅÉæÆôöòûùÿÖÜ¢£¥₧ƒáíóúñѪº¿⌐¬½¼¡«»░▒▓│┤╡╢╖╕╣║╗╝╜╛┐└┴┬├─┼╞╟╚╔╩╦╠═╬╧╨╤╥╙╘╒╓╫╪┘┌█▄▌▐▀αßΓπΣσµτΦΘΩδ∞φε∩≡±≥≤⌠⌡÷≈°∙·√ⁿ²■\u00A0";
+/**
+ * Decode a legacy ZIP name with the Unicode CP437 mapping, which Python's
+ * zipfile also uses: bytes below 0x80 are ASCII. zip.js shows 0x01-0x1F and
+ * 0x7F as IBM PC display glyphs, which turns the macOS folder icon file
+ * `Icon\r` into `Icon♪`.
+ */
+const decodeCp437 = (bytes) => Array.from(bytes, (byte) => byte < 0x80
+    ? String.fromCharCode(byte)
+    : CP437_HIGH_HALF.charAt(byte - 0x80)).join("");
+const zipEntryPath = (entry) => {
+    const field = entry.extraFieldUnicodePath;
+    if (field?.valid !== true)
+        return entry.filename;
+    return decodeStrictZipUtf8(field.data.subarray(5), "ZIP Unicode Path extra field is not valid UTF-8");
+};
+const decodeStrictZipUtf8 = (bytes, message) => {
+    try {
+        // Keep the adapter's path semantics aligned with zip.js's default decoder:
+        // a leading U+FEFF is part of a member name, not a transport signature.
+        return ZIP_UTF8_DECODER.decode(bytes);
+    }
+    catch (cause) {
+        throw new ArtifactReaderFailure("format", message, { cause });
+    }
+};
 const extractStream = (entry, signal) => {
     const output = new PassThrough();
     const controller = new AbortController();
@@ -167,7 +229,7 @@ const extractStream = (entry, signal) => {
             output.end();
         },
         abort: (reason) => {
-            output.destroy(toError(reason));
+            output.destroy(toError(typedZipFailure(reason)));
         },
     });
     void entry
@@ -177,9 +239,52 @@ const extractStream = (entry, signal) => {
         checkOverlappingEntry: true,
         onprogress: () => abortIfNeeded(signal),
     })
-        .catch((cause) => output.destroy(toError(cause)));
+        .catch((cause) => output.destroy(toError(typedZipFailure(cause))));
     return output;
 };
+/** zip.js reports archive faults as plain errors identified by message. */
+const ZIP_FAILURE_REASONS = new Map([
+    ...[
+        ERR_AMBIGUOUS_ARCHIVE,
+        ERR_BAD_FORMAT,
+        ERR_CENTRAL_DIRECTORY_NOT_FOUND,
+        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_UNSUPPORTED_UINT64,
+    ].map((message) => [message, "format"]),
+    ...[
+        ERR_ENCRYPTED_CENTRAL_DIRECTORY,
+        ERR_SPLIT_ZIP_FILE,
+        ERR_UNSUPPORTED_COMPRESSION,
+        ERR_UNSUPPORTED_ENCRYPTION,
+    ].map((message) => [message, "unavailable"]),
+]);
+/** Type a zip.js archive fault so consumers do not report it as file I/O. */
+const typedZipFailure = (cause) => {
+    if (!(cause instanceof Error) || cause instanceof ArtifactReaderFailure)
+        return cause;
+    const reason = ZIP_FAILURE_REASONS.get(cause.message);
+    if (reason === undefined)
+        return cause;
+    return new ArtifactReaderFailure(reason, reason === "format"
+        ? `ZIP archive is malformed: ${cause.message}`
+        : `ZIP archive uses an unsupported feature: ${cause.message}`, { cause });
+};
+async function* typedZipFailures(source) {
+    try {
+        yield* source;
+    }
+    catch (cause) {
+        throw typedZipFailure(cause);
+    }
+}
 const isSymlink = (entry) => entry.unixMode !== undefined && (entry.unixMode & 0o170000) === 0o120000;
 const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)