rea-agents 6.4.0 → 6.7.0

package/dist/artifacts/inventory/ArtifactGraphConstruction.js

@@ -1,14 +1,21 @@
 import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
+import { isJavaScriptSourcePath } from "../../domain/javascript/javascriptArtifactFiles.js";
 import { digestCanonicalValue } from "../../domain/canonicalDigest.js";
+import { hasBinaryPlistSignature, hasXmlPlistSignature, } from "../../domain/apple/appleArchiveFormat.js";
 import { artifactEdgeId, artifactIdForContent, occurrenceIdForLocation, } from "../../domain/artifactIdentity.js";
-import { hasZipSignature, zipPackageFormatForPath, } from "../../domain/zipPackageFormat.js";
-import { mzWindowsHeaderOffset, parseDosMzHeader } from "../../domain/dosMz.js";
-/** Index the first occurrence for each canonical logical path. */
+import { hasZipSignature, isZipPackageFormat, zipPackageFormatForPath, } from "../../domain/zipPackageFormat.js";
+import { observeMzWindowsHeader, parseDosMzHeader, } from "../../domain/dosMz.js";
+import { classifyFatContainerIdentity, readFatContainerHeader, } from "../../domain/apple/machoContainer.js";
+/** Index every occurrence by canonical logical path without choosing an owner. */
 export const indexOccurrencesByPath = (occurrences) => {
     const byPath = new Map();
-    for (const occurrence of occurrences)
-        if (!byPath.has(occurrence.logical_path))
-            byPath.set(occurrence.logical_path, occurrence);
+    for (const occurrence of occurrences) {
+        const matches = byPath.get(occurrence.logical_path);
+        if (matches === undefined)
+            byPath.set(occurrence.logical_path, [occurrence]);
+        else
+            matches.push(occurrence);
+    }
     return byPath;
 };
 /**
@@ -16,7 +23,7 @@ export const indexOccurrencesByPath = (occurrences) => {
  * container family until the bytes are classified, so a member named like a
  * container starts with an unknown format.
  */
-export const createOccurrence = (entry, path, parent) => {
+export const createOccurrence = (entry, path, parent, duplicateOrdinal = 0) => {
     const role = entry.kind === "directory"
         ? {
             kind: path.toLowerCase().endsWith(".framework")
@@ -28,7 +35,9 @@ export const createOccurrence = (entry, path, parent) => {
             ? classifyArtifactPath(path)
             : { kind: "unknown", format: "unknown" };
     return {
-        occurrence_id: `occ_${digestCanonicalValue({ path, kind: entry.kind }, "Artifact")}`,
+        occurrence_id: `occ_${digestCanonicalValue(duplicateOrdinal === 0
+            ? { path, kind: entry.kind }
+            : { path, kind: entry.kind, duplicate_ordinal: duplicateOrdinal }, "Artifact")}`,
         artifact_id: null,
         parent_occurrence_id: parent,
         logical_path: path,
@@ -62,7 +71,7 @@ const containerSuffixFamily = (path) => {
 /** Compare exact child names independently of host locale and traversal order. */
 export const materializeDirectoryNodes = (occurrences, nodes) => {
     const directories = occurrences
-        .filter(({ entry_kind: kind }) => kind === "directory")
+        .filter(({ entry_kind: kind, hash_status }) => kind === "directory" && hash_status !== "unavailable")
         .sort((left, right) => depth(right.logical_path) - depth(left.logical_path));
     const childrenByParent = new Map();
     for (const occurrence of occurrences) {
@@ -132,7 +141,8 @@ export const rootOccurrenceFor = (node, metadata) => ({
     logical_path: ".",
     entry_kind: metadata.format === "directory" ? "directory" : "file",
     artifact_kind: metadata.format === "directory" ||
-        ["zip", "ipa", "apk", "msix", "appx", "asar", "dmg", "pkg"].includes(metadata.format)
+        isZipPackageFormat(metadata.format) ||
+        ["asar", "dmg", "pkg"].includes(metadata.format)
         ? "container"
         : artifactRoleForFormat(metadata.path, metadata.format).kind,
     artifact_format: metadata.format,
@@ -146,12 +156,17 @@ export const rootOccurrenceFor = (node, metadata) => ({
 });
 export const rekeyOccurrences = (rootArtifactId, occurrences) => {
     const replacements = new Map();
-    for (const occurrence of occurrences)
+    const ordinalByPath = new Map();
+    for (const occurrence of occurrences) {
+        const ordinal = ordinalByPath.get(occurrence.logical_path) ?? 0;
+        ordinalByPath.set(occurrence.logical_path, ordinal + 1);
         replacements.set(occurrence.occurrence_id, occurrenceIdForLocation({
             rootArtifactId,
             logicalPath: occurrence.logical_path,
             entryKind: occurrence.entry_kind,
+            ...(ordinal === 0 ? {} : { duplicateOrdinal: ordinal }),
         }));
+    }
     for (const occurrence of occurrences) {
         occurrence.occurrence_id =
             replacements.get(occurrence.occurrence_id) ?? occurrence.occurrence_id;
@@ -165,13 +180,38 @@ export const createArtifactEdges = (rootArtifactId, occurrences, producer) => {
     const byId = new Map(occurrences.map((item) => [item.occurrence_id, item]));
     const byPath = indexOccurrencesByPath(occurrences);
     const edges = [];
+    const limitations = [];
     for (const occurrence of occurrences) {
+        // Use the occurrence's own classification: a directory named `x.map` is
+        // a container, not a source map of its sibling.
+        const isSourceMap = occurrence.artifact_kind === "source-map";
+        const sourcePath = isSourceMap
+            ? occurrence.logical_path.slice(0, -".map".length)
+            : undefined;
+        const sourceCandidates = sourcePath === undefined ? [] : (byPath.get(sourcePath) ?? []);
+        const mappedSource = sourceCandidates.length === 1 && sourceCandidates[0]?.artifact_id !== null
+            ? sourceCandidates[0]
+            : undefined;
+        if (sourcePath !== undefined) {
+            const unknownMapping = sourceCandidates.length > 1
+                ? {
+                    occurrence: `Source-map target is unknown because multiple occurrences share ${JSON.stringify(sourcePath)}.`,
+                    coverage: `Source-map relationships are unknown because multiple occurrences share ${JSON.stringify(sourcePath)}.`,
+                }
+                : sourceCandidates.length === 1 && mappedSource === undefined
+                    ? {
+                        occurrence: `Source-map target identity is unknown because the matching occurrence at ${JSON.stringify(sourcePath)} has no content identity.`,
+                        coverage: `Source-map relationships are unknown because the matching occurrence at ${JSON.stringify(sourcePath)} has no content identity.`,
+                    }
+                    : undefined;
+            if (unknownMapping !== undefined) {
+                occurrence.limitations.push(unknownMapping.occurrence);
+                limitations.push(unknownMapping.coverage);
+            }
+        }
         if (occurrence.parent_occurrence_id === null ||
             occurrence.artifact_id === null)
             continue;
-        const mappedSource = occurrence.logical_path.toLowerCase().endsWith(".map")
-            ? byPath.get(occurrence.logical_path.slice(0, -".map".length))
-            : undefined;
         const parentArtifactId = mappedSource?.artifact_id ??
             byId.get(occurrence.parent_occurrence_id)?.artifact_id ??
             rootArtifactId;
@@ -179,7 +219,11 @@ export const createArtifactEdges = (rootArtifactId, occurrences, producer) => {
             parent_artifact_id: parentArtifactId,
             relation: occurrence.entry_kind === "slice"
                 ? "slice-of"
-                : relationFor(occurrence.logical_path),
+                : isSourceMap
+                    ? mappedSource === undefined
+                        ? "contains"
+                        : "maps-source"
+                    : relationFor(occurrence.logical_path),
             occurrence_id: occurrence.occurrence_id,
         };
         edges.push({
@@ -189,17 +233,28 @@ export const createArtifactEdges = (rootArtifactId, occurrences, producer) => {
             ordinal: edges.length,
         });
     }
-    return edges;
+    return { edges, limitations };
 };
 /** Resolve strict observed ancestors without rebuilding every path prefix. */
 export const resolveOccurrenceParents = (occurrences, byPath, expandedContainerIds) => {
     const root = { children: new Map() };
-    for (const occurrence of byPath.values()) {
-        if (occurrence.entry_kind !== "directory" &&
-            !expandedContainerIds.has(occurrence.occurrence_id))
+    for (const matches of byPath.values()) {
+        const parents = matches.filter((occurrence) => occurrence.entry_kind === "directory" ||
+            expandedContainerIds.has(occurrence.occurrence_id));
+        if (parents.length === 0)
+            continue;
+        if (parents.length > 1)
+            for (const parent of parents)
+                if (parent.entry_kind === "directory") {
+                    parent.artifact_id = null;
+                    parent.hash_status = "unavailable";
+                    parent.limitations.push("This directory occurrence cannot be materialized because multiple directory entries share its logical path.");
+                }
+        const path = matches[0]?.logical_path;
+        if (path === undefined)
             continue;
         let branch = root;
-        for (const segment of occurrence.logical_path.split("/")) {
+        for (const segment of path.split("/")) {
             let child = branch.children.get(segment);
             if (child === undefined) {
                 child = { children: new Map() };
@@ -207,12 +262,16 @@ export const resolveOccurrenceParents = (occurrences, byPath, expandedContainerI
             }
             branch = child;
         }
-        branch.occurrence = occurrence;
+        branch.occurrences = parents;
     }
+    const limitations = new Set();
+    const unknownParentOccurrences = new Set();
     for (const occurrence of occurrences) {
         const path = occurrence.logical_path;
         let branch = root;
         let parent;
+        let ambiguousParentPath;
+        let prefix = "";
         // Walk parent segments only. Stop scanning the path once no observed
         // directory or expanded container can be an ancestor.
         for (let start = 0;;) {
@@ -224,11 +283,30 @@ export const resolveOccurrenceParents = (occurrences, byPath, expandedContainerI
             if (child === undefined)
                 break;
             branch = child;
-            parent = branch.occurrence ?? parent;
+            prefix = prefix.length === 0 ? segment : `${prefix}/${segment}`;
+            const candidates = branch.occurrences ?? [];
+            if (candidates.length === 1) {
+                parent = candidates[0];
+                ambiguousParentPath = undefined;
+            }
+            else if (candidates.length > 1) {
+                parent = undefined;
+                ambiguousParentPath = prefix;
+            }
             start = slash + 1;
         }
         occurrence.parent_occurrence_id = parent?.occurrence_id ?? null;
+        if (ambiguousParentPath !== undefined) {
+            const limitation = `The parent occurrence for ${JSON.stringify(path)} is unknown because multiple observed directory or container occurrences share ${JSON.stringify(ambiguousParentPath)}.`;
+            occurrence.limitations.push(limitation);
+            limitations.add(limitation);
+            unknownParentOccurrences.add(occurrence);
+        }
     }
+    return {
+        limitations: [...limitations].sort(compareUnicodeCodePoints),
+        unknownParentOccurrences,
+    };
 };
 /**
  * Assign a path role hint. Container families are not path roles: ZIP and
@@ -238,7 +316,7 @@ export const classifyArtifactPath = (path) => {
     const lower = path.toLowerCase();
     if (lower.endsWith(".map"))
         return { kind: "source-map", format: "source-map" };
-    if (/\.(?:m?js|cjs)$/u.test(lower))
+    if (isJavaScriptSourcePath(path))
         return { kind: "javascript", format: "javascript-bundle" };
     if (/\.framework(?:\/|$)/u.test(lower))
         return { kind: "framework", format: "file" };
@@ -256,6 +334,12 @@ export const classifyArtifactPath = (path) => {
 /** Classify executable formats from bytes while retaining path-specific roles. */
 export const classifyArtifactContent = (path, prefix, fileSize = prefix.length) => {
     const format = classifyArtifactBytes(prefix, fileSize);
+    const byPath = classifyArtifactPath(path);
+    if (format === "plist" &&
+        !hasBinaryPlistSignature(prefix) &&
+        (["javascript", "source-map", "entitlements"].includes(byPath.kind) ||
+            path.toLowerCase().endsWith(".asar")))
+        return byPath;
     if (format === "file" &&
         path.toLowerCase().endsWith(".asar") &&
         hasAsarHeader(prefix))
@@ -300,12 +384,15 @@ const artifactRoleForFormat = (path, format) => {
 export const classifyArtifactBytes = (prefix, fileSize = prefix.length) => {
     if (hasZipSignature(prefix))
         return "zip";
-    if (prefix.subarray(0, 8).equals(Buffer.from("bplist00")))
+    if (hasBinaryPlistSignature(prefix))
         return "plist";
+    if (hasXmlPlistSignature(prefix))
+        return "plist";
+    const fatFormat = classifyFatArtifact(prefix, fileSize);
+    if (fatFormat !== null)
+        return fatFormat;
     if (prefix.length >= 4) {
         const magic = prefix.readUInt32BE(0);
-        if ([0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic))
-            return "mach-o-universal";
         if ([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic))
             return "mach-o";
         if (prefix.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])))
@@ -316,27 +403,38 @@ export const classifyArtifactBytes = (prefix, fileSize = prefix.length) => {
             fileSize < prefix.length ||
             prefix.length < Math.min(fileSize, 64))
             return "unknown";
-        const windowsOffset = mzWindowsHeaderOffset(prefix);
-        if (windowsOffset !== null) {
-            if (windowsOffset >= 64 &&
-                windowsOffset <= prefix.length - 4 &&
-                prefix
-                    .subarray(windowsOffset, windowsOffset + 4)
-                    .equals(Buffer.from([0x50, 0x45, 0, 0])))
+        const windowsHeader = observeMzWindowsHeader(prefix, fileSize);
+        if (windowsHeader.state === "signature-needed")
+            return "unknown";
+        if (windowsHeader.state === "declared") {
+            const windowsOffset = windowsHeader.offset;
+            if (windowsHeader.signature === "PE" &&
+                windowsOffset >= 64 &&
+                windowsOffset <= prefix.length - 4)
                 return "pe";
+            return "unknown";
         }
-        else if (parseDosMzHeader(prefix, fileSize).ok)
+        if (parseDosMzHeader(prefix, fileSize).ok)
             return "dos-mz";
         return "unknown";
     }
     return "file";
 };
-const relationFor = (path) => {
-    const lower = path.toLowerCase();
-    if (lower.endsWith(".map"))
-        return "maps-source";
-    if (lower.includes(".framework/"))
-        return "embeds";
-    return "contains";
+const classifyFatArtifact = (prefix, fileSize) => {
+    const fatHeader = readFatContainerHeader(prefix, fileSize);
+    if (fatHeader.state === "needs-data" || fatHeader.state === "malformed")
+        return "unknown";
+    if (fatHeader.state === "not-fat")
+        return null;
+    const identity = classifyFatContainerIdentity(fatHeader, (offset) => {
+        if (offset >= prefix.length)
+            return undefined;
+        if (offset + 4 > prefix.length)
+            return null;
+        return prefix.readUInt32BE(offset);
+    });
+    return identity.state === "mach-o" ? "mach-o-universal" : "unknown";
 };
+/** Relation of a non-source-map occurrence to its parent. */
+const relationFor = (path) => path.toLowerCase().includes(".framework/") ? "embeds" : "contains";
 const depth = (path) => path.split("/").length;

package/dist/artifacts/inventory/classify.js

@@ -1,9 +1,9 @@
 import { sameRegularFileState } from "../../filesystem/RegularFile.js";
 import { classifyArtifactContent } from "./ArtifactGraphConstruction.js";
-import { ARTIFACT_CLASSIFICATION_PREFIX_BYTES } from "../ArtifactHash.js";
-import { hasZipSignature, zipPackageFormatForPath, } from "../../domain/zipPackageFormat.js";
+import { abortIfNeeded, ARTIFACT_CLASSIFICATION_PREFIX_BYTES, } from "../ArtifactHash.js";
+import { createXmlPlistSignatureProbe, MAX_XML_PLIST_PROBE_BYTES, } from "../../domain/apple/appleArchiveFormat.js";
+import { hasZipSignature, isZipPackageFormat, zipPackageFormatForPath, } from "../../domain/zipPackageFormat.js";
 import { ArtifactReaderFailure } from "../ArtifactReader.js";
-import {} from "../ArtifactResourceScope.js";
 import { hashStableRootArtifactHandle, openRootArtifact, } from "./hashStableRootArtifact.js";
 /** Classify and hash one file root through the same stable open descriptor. */
 export const classifyAndHashRoot = async (path, directory, expectedMetadata, options) => {
@@ -18,7 +18,9 @@ export const classifyAndHashRoot = async (path, directory, expectedMetadata, opt
             };
             const cleanupAttempt = await options.resourceScope.release(owner);
             if (cleanupAttempt.kind === "failed")
-                throw ArtifactReaderFailure.withCleanup(cleanupAttempt.cause, ArtifactReaderFailure.cleanupObservation(cleanupAttempt.cause, owner.resource));
+                throw options.resourceScope.cleanupFailure({ kind: "completed" }, [
+                    cleanupAttempt,
+                ]);
         }
         return { format: result.format, digest: result.digest };
     });
@@ -39,9 +41,9 @@ export const classifyAndHashRootForInventory = async (path, directory, expectedM
         const initial = await handle.stat();
         if (!sameRegularFileState(expectedMetadata, initial))
             throw new ArtifactReaderFailure("integrity", `Root artifact changed before inventory: ${path}`);
-        const format = await classifyRootFormat(path, handle);
+        const format = await classifyRootFormat(path, handle, options.signal);
         const digest = await hashStableRootArtifactHandle(path, handle, initial, options.signal);
-        const retainSource = isZipFormat(format) || format === "mach-o-universal";
+        const retainSource = isZipPackageFormat(format) || format === "mach-o-universal";
         outcome = {
             kind: "completed",
             value: {
@@ -59,38 +61,55 @@ export const classifyAndHashRootForInventory = async (path, directory, expectedM
     if (outcome.kind === "failed" || outcome.value.rootSource === undefined) {
         const cleanupAttempt = await options.resourceScope.release(owner);
         if (cleanupAttempt.kind === "failed")
-            throw ArtifactReaderFailure.withCleanup(outcome.kind === "failed" ? outcome.cause : cleanupAttempt.cause, ArtifactReaderFailure.cleanupObservation(cleanupAttempt.cause, owner.resource));
+            throw options.resourceScope.cleanupFailure(outcome, [cleanupAttempt]);
     }
     if (outcome.kind === "failed")
         throw outcome.cause;
     return outcome.value;
 };
-const isZipFormat = (format) => format === "zip" ||
-    format === "ipa" ||
-    format === "apk" ||
-    format === "msix" ||
-    format === "appx";
-const classifyRootFormat = async (path, handle) => {
+const classifyRootFormat = async (path, handle, signal) => {
     const magic = Buffer.alloc(ARTIFACT_CLASSIFICATION_PREFIX_BYTES);
     const observed = await handle.read(magic, 0, magic.length, 0);
-    const prefix = magic.subarray(0, observed.bytesRead);
+    let prefix = magic.subarray(0, observed.bytesRead);
     const lower = path.toLowerCase();
     if (hasZipSignature(prefix))
-        return zipPackageFormatForPath(lower) ?? "zip";
+        return zipRootPackageFormat(lower);
     if (lower.endsWith(".pkg") &&
-        prefix.subarray(0, 4).toString("ascii") === "xar!")
+        prefix.subarray(0, 4).equals(Buffer.from("xar!")))
         return "pkg";
     if (lower.endsWith(".dmg") && (await hasKolyTrailer(handle)))
         return "dmg";
+    const xmlProbe = createXmlPlistSignatureProbe();
+    xmlProbe.write(prefix);
+    const chunks = [prefix];
+    let prefixBytes = prefix.length;
+    while (xmlProbe.state === "pending" &&
+        prefixBytes < MAX_XML_PLIST_PROBE_BYTES) {
+        abortIfNeeded(signal);
+        const chunk = Buffer.alloc(Math.min(64 * 1024, MAX_XML_PLIST_PROBE_BYTES - prefixBytes));
+        const read = await handle.read(chunk, 0, chunk.length, prefixBytes);
+        abortIfNeeded(signal);
+        if (read.bytesRead === 0)
+            break;
+        const selected = chunk.subarray(0, read.bytesRead);
+        chunks.push(selected);
+        prefixBytes += selected.length;
+        xmlProbe.write(selected);
+    }
+    prefix = Buffer.concat(chunks);
     // ASAR is chosen from its header pickle; any other suffix is a role hint.
     return classifyArtifactContent(path, prefix, (await handle.stat()).size)
         .format;
 };
+/** App Pack is a verified ZIP root role; nested .app members retain their observed format. */
+const zipRootPackageFormat = (lower) => lower.endsWith(".app")
+    ? "app-pack"
+    : (zipPackageFormatForPath(lower) ?? "zip");
 const hasKolyTrailer = async (handle) => {
     const size = (await handle.stat()).size;
     if (size < 512)
         return false;
     const trailer = Buffer.alloc(4);
     const read = await handle.read(trailer, 0, trailer.length, size - 512);
-    return read.bytesRead === 4 && trailer.toString("ascii") === "koly";
+    return read.bytesRead === 4 && trailer.equals(Buffer.from("koly"));
 };

package/dist/artifacts/inventory/hashStableRootArtifact.js

@@ -1,5 +1,6 @@
+import { regularFileCancellation } from "../../filesystem/OwnedRegularFile.js";
 import { lstat } from "node:fs/promises";
-import { readFileHandleChunks } from "../../filesystem/readFileHandleChunks.js";
+import { readArtifactFileChunks } from "../readArtifactFileChunks.js";
 import { OwnedFileHandle } from "../../filesystem/OwnedFileHandle.js";
 import { ArtifactReaderFailure } from "../ArtifactReader.js";
 import { NonRegularFileReadError, RegularFileAdmissionFailure, openRegularFile, sameRegularFileState, } from "../../filesystem/RegularFile.js";
@@ -11,9 +12,12 @@ export const openRootArtifact = async (path, resourceScope, signal) => {
     }
     catch (cause) {
         const primary = cause instanceof RegularFileAdmissionFailure ? cause.cause : cause;
-        const failure = primary instanceof NonRegularFileReadError
-            ? new ArtifactReaderFailure("format", `Artifact root is not a regular file: ${path}`, { cause: primary })
-            : primary;
+        const cancellation = regularFileCancellation(primary);
+        const failure = cancellation !== undefined
+            ? new ArtifactReaderFailure("cancelled", "Artifact admission cancelled", { cause: cancellation.reason })
+            : primary instanceof NonRegularFileReadError
+                ? new ArtifactReaderFailure("format", `Artifact root is not a regular file: ${path}`, { cause: primary })
+                : primary;
         if (cause instanceof RegularFileAdmissionFailure) {
             const resource = `root artifact descriptor for ${path}`;
             const cleanup = await resourceScope.release({
@@ -22,7 +26,9 @@ export const openRootArtifact = async (path, resourceScope, signal) => {
                 handle: cause.owner,
             });
             if (cleanup.kind === "failed")
-                throw ArtifactReaderFailure.withCleanup(failure, ArtifactReaderFailure.cleanupObservation(cleanup.cause, resource));
+                throw resourceScope.cleanupFailure({ kind: "failed", cause: failure }, [
+                    cleanup,
+                ]);
         }
         throw failure;
     }
@@ -49,7 +55,7 @@ export const hashStableRootArtifact = async (path, resourceScope, signal) => {
         handle: owner,
     });
     if (cleanup.kind === "failed")
-        throw ArtifactReaderFailure.withCleanup(outcome.kind === "failed" ? outcome.cause : cleanup.cause, ArtifactReaderFailure.cleanupObservation(cleanup.cause, resource));
+        throw resourceScope.cleanupFailure(outcome, [cleanup]);
     if (outcome.kind === "failed")
         throw outcome.cause;
     return outcome.value;
@@ -59,12 +65,13 @@ export const hashStableRootArtifactHandle = async (path, handle, initial, signal
     const digest = await hashReadable(
     // Read at most the admitted extent plus one byte to detect growth without
     // following an actively appended file indefinitely.
-    readFileHandleChunks(handle, { start: 0, end: initial.size }), signal);
+    readArtifactFileChunks(handle, { start: 0, end: initial.size, signal }), signal);
     abortIfNeeded(signal);
     const [opened, currentPath] = await Promise.all([handle.stat(), lstat(path)]);
     if (!sameRegularFileState(initial, opened) ||
         !sameRegularFileState(initial, currentPath) ||
         digest.bytes !== initial.size)
         throw new ArtifactReaderFailure("integrity", `Root artifact changed during inventory: ${path}`);
+    abortIfNeeded(signal);
     return digest;
 };

package/dist/artifacts/inventory/reader.js

@@ -3,17 +3,13 @@ import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
 import { MachOSliceArtifactReader } from "../MachOSliceArtifactReader.js";
 import { NativeDmgArtifactReader } from "../NativeDmgArtifactReader.js";
 import { ZipArtifactReader } from "../ZipArtifactReader.js";
-import { ZIP_NON_ENTRY_TAIL_LIMITATION } from "../../domain/zipPackageFormat.js";
+import { isZipPackageFormat, ZIP_NON_ENTRY_LIMITATION, } from "../../domain/zipPackageFormat.js";
 export const createReader = (path, format, environment, rootSource) => {
+    if (isZipPackageFormat(format))
+        return new ZipArtifactReader(path, format, undefined, rootSource);
     switch (format) {
         case "directory":
             return new DirectoryArtifactReader(path);
-        case "zip":
-        case "ipa":
-        case "apk":
-        case "msix":
-        case "appx":
-            return new ZipArtifactReader(path, format, undefined, rootSource);
         case "asar":
             return new AsarArtifactReader(path);
         case "mach-o-universal":
@@ -28,21 +24,40 @@ export const createReader = (path, format, environment, rootSource) => {
             return undefined;
     }
 };
-export const inventoryLimitations = (format, reader) => {
+/** Decide traversal scope and availability once, independently of diagnostic wording. */
+export const inventoryCoverage = (format, reader, traversal) => {
     if (reader !== undefined)
-        return reader.format === "zip" ||
-            reader.format === "ipa" ||
-            reader.format === "apk" ||
-            reader.format === "msix" ||
-            reader.format === "appx"
-            ? [ZIP_NON_ENTRY_TAIL_LIMITATION]
-            : [];
+        return {
+            coverage: { scope: "container-entries", status: traversal.status },
+            limitations: [
+                ...(isZipPackageFormat(reader.format)
+                    ? [ZIP_NON_ENTRY_LIMITATION]
+                    : []),
+                ...traversal.limitations,
+            ],
+        };
     // dmg and pkg reach here only after classifyRootFormat matched their bytes.
     if (format === "dmg" || format === "pkg")
-        return [
-            `${format.toUpperCase()} root hash is observed; child inventory requires a native macOS adapter.`,
-        ];
-    if (format === "mach-o-universal" && process.platform !== "darwin")
-        return ["Universal Mach-O slices require the native macOS lipo adapter."];
-    return ["Artifact has no child container entries."];
+        return {
+            coverage: { scope: "container-entries", status: "unknown" },
+            limitations: [
+                `${format.toUpperCase()} root hash is observed; child inventory requires a native macOS adapter.`,
+            ],
+        };
+    if (format === "mach-o-universal")
+        return {
+            coverage: { scope: "container-entries", status: "unknown" },
+            limitations: [
+                "Universal Mach-O slices require the native macOS lipo adapter.",
+            ],
+        };
+    if (isZipPackageFormat(format) || format === "directory" || format === "asar")
+        return {
+            coverage: { scope: "container-entries", status: "unknown" },
+            limitations: [`${format} child inventory reader is unavailable.`],
+        };
+    return {
+        coverage: { scope: "root", status: "complete" },
+        limitations: ["Artifact has no child container entries."],
+    };
 };