rea-agents 6.4.0 → 6.5.0

package/dist/artifacts/apple/MachoLoadCommandReader.js

@@ -1,12 +1,7 @@
-import { readFatSliceDeclarations, validateFatSlice, } from "../../domain/apple/machoContainer.js";
+import { machoCpuSubtypeBase } from "../../domain/apple/machoCpuIdentity.js";
+import { classifyFatContainerIdentity, readFatContainerHeader, validateFatSliceIdentity, } from "../../domain/apple/machoContainer.js";
 /** Load commands larger than this are refused instead of buffered. */
 export const MAX_LOAD_COMMAND_BYTES = 16 * 1024 * 1024;
-/** Target opening accepts up to 128 FAT records; Java class files share the FAT magic. */
-const MAX_FAT_ARCHITECTURES = 128;
-/** CPU types of real Mach-O slices (x86, x86_64, arm, arm64, arm64_32, ppc, ppc64). */
-const KNOWN_CPU_TYPES = [
-    7, 0x01000007, 12, 0x0100000c, 0x0200000c, 18, 0x01000012,
-];
 const MH_MAGIC = 0xfeedface;
 const MH_MAGIC_64 = 0xfeedfacf;
 const MH_CIGAM = 0xcefaedfe;
@@ -112,49 +107,35 @@ export const readMachoImage = async (readAt, size) => {
                 : { status: "not-mach-o" };
         const view = viewOf(head);
         const magic = view.getUint32(0, false);
-        if ([FAT_MAGIC, FAT_MAGIC_64, FAT_CIGAM, FAT_CIGAM_64].includes(magic)) {
-            // FAT headers are big-endian; the swapped magics store them little-endian.
-            const littleEndian = magic === FAT_CIGAM || magic === FAT_CIGAM_64;
-            const count = view.getUint32(4, littleEndian);
-            const wide = magic === FAT_MAGIC_64 || magic === FAT_CIGAM_64;
-            // A Java class file's nonzero major version reads as the count, so an
-            // empty architecture table can only be a malformed universal header.
-            if (count === 0)
-                return {
-                    status: "malformed",
-                    reason: "FAT header declares no architectures",
-                };
-            if (count > MAX_FAT_ARCHITECTURES || 8 + count * (wide ? 32 : 20) > size)
+        let header = readFatContainerHeader(head, size);
+        if (header.state !== "not-fat") {
+            if (header.state === "needs-data") {
+                header = readFatContainerHeader(await readAt(0, header.requiredBytes), size);
+            }
+            if (header.state === "not-fat")
                 return { status: "not-mach-o" };
-            const tableBytes = await readExact(readAt, 8, count * (wide ? 32 : 20), "FAT table");
-            const declarations = readFatSliceDeclarations(tableBytes, {
-                count,
-                wide,
-                littleEndian,
-            });
-            if (declarations.status !== "parsed")
-                throw new MachoFormatIssue("malformed", declarations.reason);
-            // A Java class file's version fields read as a FAT count; its "table" names no CPU.
-            if (!declarations.slices.some(({ cpuType }) => KNOWN_CPU_TYPES.includes(cpuType))) {
-                let hasMachOSliceHeader = false;
-                for (const declaration of declarations.slices) {
-                    if (validateFatSlice(declaration, size, 8 + count * (wide ? 32 : 20)) !== null)
-                        continue;
-                    const bytes = await readAt(declaration.offset, 4);
-                    if (bytes.byteLength < 4)
-                        continue;
-                    const sliceMagic = viewOf(bytes).getUint32(0, false);
-                    if ([MH_MAGIC, MH_MAGIC_64, MH_CIGAM, MH_CIGAM_64].includes(sliceMagic)) {
-                        hasMachOSliceHeader = true;
-                        break;
-                    }
+            if (header.state === "needs-data")
+                throw new MachoFormatIssue("malformed", "FAT table is truncated");
+            if (header.state === "malformed")
+                throw new MachoFormatIssue("malformed", header.reason);
+            let identity = classifyFatContainerIdentity(header, () => undefined);
+            if (identity.state === "needs-slice-header") {
+                const sliceHeaders = new Map();
+                for (const offset of identity.offsets) {
+                    const bytes = await readAt(offset, 4);
+                    sliceHeaders.set(offset, bytes.byteLength < 4 ? null : viewOf(bytes).getUint32(0, false));
                 }
-                if (!hasMachOSliceHeader)
-                    return { status: "not-mach-o" };
+                identity = classifyFatContainerIdentity(header, (offset) => sliceHeaders.get(offset));
             }
+            if (identity.state === "not-mach-o")
+                return { status: "not-mach-o" };
+            if (identity.state === "malformed")
+                throw new MachoFormatIssue(identity.category, identity.reason);
+            if (identity.state === "needs-slice-header")
+                return { status: "not-mach-o" };
             return {
                 status: "parsed",
-                slices: await readFatSlices(readAt, size, 8 + count * (wide ? 32 : 20), declarations.slices),
+                slices: await readFatSlices(readAt, header.slices),
             };
         }
         if (magic === MH_CIGAM || magic === MH_CIGAM_64)
@@ -169,19 +150,29 @@ export const readMachoImage = async (readAt, size) => {
         throw cause;
     }
 };
-const readFatSlices = async (readAt, size, tableEnd, declarations) => {
+const readFatSlices = async (readAt, declarations) => {
     const slices = [];
+    // Keep validating after an unsupported slice so a later malformed slice is
+    // reported as malformed whatever the slice order.
+    let unsupported;
     for (const declaration of declarations) {
-        const { index, offset, size: length, cpuType, cpuSubtype } = declaration;
-        const rangeIssue = validateFatSlice(declaration, size, tableEnd);
-        if (rangeIssue !== null)
-            throw new MachoFormatIssue(rangeIssue.includes("unsupported") ? "unsupported" : "malformed", rangeIssue);
-        const slice = await readSlice(readAt, offset, length, {
-            fatCpuType: cpuType,
-            fatCpuSubtype: cpuSubtype,
-            alignmentExponent: declaration.alignmentExponent,
-        });
-        const identityIssue = validateFatSlice(declaration, size, tableEnd, {
+        const { offset, size: length, cpuType, cpuSubtype } = declaration;
+        let slice;
+        try {
+            slice = await readSlice(readAt, offset, length, {
+                fatCpuType: cpuType,
+                fatCpuSubtype: cpuSubtype,
+                alignmentExponent: declaration.alignmentExponent,
+            });
+        }
+        catch (cause) {
+            if (!(cause instanceof MachoFormatIssue) ||
+                cause.status !== "unsupported")
+                throw cause;
+            unsupported ??= cause;
+            continue;
+        }
+        const identityIssue = validateFatSliceIdentity(declaration, {
             cpuType: slice.cpu_type,
             cpuSubtype: slice.cpu_subtype,
         });
@@ -189,6 +180,8 @@ const readFatSlices = async (readAt, size, tableEnd, declarations) => {
             throw new MachoFormatIssue("malformed", identityIssue);
         slices.push(slice);
     }
+    if (unsupported !== undefined)
+        throw unsupported;
     return slices;
 };
 const readSlice = async (readAt, base, length, fat = null) => {
@@ -289,7 +282,11 @@ const decodeCommand = (command, body, index, slice) => {
     if (command === LC_BUILD_VERSION) {
         if (body.byteLength < 24)
             throw new MachoFormatIssue("malformed", `load command ${index} is too short for LC_BUILD_VERSION`);
-        const platform = viewOf(body).getUint32(8, true);
+        const view = viewOf(body);
+        const toolCount = view.getUint32(20, true);
+        if (toolCount > Math.floor((body.byteLength - 24) / 8))
+            throw new MachoFormatIssue("malformed", `load command ${index} LC_BUILD_VERSION tool records exceed cmdsize`);
+        const platform = view.getUint32(8, true);
         slice.platforms.push(platform);
         return;
     }
@@ -336,7 +333,8 @@ const commandString = (body, minimumOffset, index) => {
     if (end < 0)
         throw new MachoFormatIssue("malformed", `load command ${index} has an unterminated string`);
     try {
-        return new TextDecoder("utf-8", { fatal: true }).decode(body.subarray(offset, end));
+        // lc_str contains name/path data, so a leading U+FEFF is part of its identity.
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(body.subarray(offset, end));
     }
     catch {
         throw new MachoFormatIssue("malformed", `load command ${index} has a string that is not UTF-8`);
@@ -352,13 +350,16 @@ const CPU_ARCH_ABI64 = 0x01000000;
 const CPU_ARCH_ABI64_32 = 0x02000000;
 const CPU_TYPE_X86 = 7;
 const CPU_TYPE_ARM = 12;
-const CPU_SUBTYPE_MASK = 0xff000000;
 const CPU_SUBTYPE_ARM64E = 2;
+const CPU_SUBTYPE_ARM64E_X1 = 12;
 const CPU_SUBTYPE_X86_64_H = 8;
 const architectureName = (cpuType, cpuSubtype) => {
-    const subtype = cpuSubtype & ~CPU_SUBTYPE_MASK;
+    const subtype = machoCpuSubtypeBase(cpuSubtype);
     if (cpuType === (CPU_TYPE_ARM | CPU_ARCH_ABI64))
-        return subtype === CPU_SUBTYPE_ARM64E ? "arm64e" : "arm64";
+        // Both pointer-authentication subtypes belong to the arm64e family.
+        return subtype === CPU_SUBTYPE_ARM64E || subtype === CPU_SUBTYPE_ARM64E_X1
+            ? "arm64e"
+            : "arm64";
     if (cpuType === (CPU_TYPE_ARM | CPU_ARCH_ABI64_32))
         return "arm64_32";
     if (cpuType === (CPU_TYPE_X86 | CPU_ARCH_ABI64))

package/dist/artifacts/apple/NibArchive.js

@@ -1,10 +1,10 @@
+import { hasNibArchiveSignature } from "../../domain/apple/appleArchiveFormat.js";
 import { TextDecoder } from "node:util";
 import { InterfaceBuilderDecodeBudget, InterfaceBuilderDecodeBudgetExceeded, } from "./InterfaceBuilderDecodeBudget.js";
-const MAGIC = Buffer.from("NIBArchive", "ascii");
 const DEFAULT_DECODE_BUDGET_BYTES = 128 * 1024 * 1024;
 /** Decode Apple's length-prefixed NIBArchive representation without loading UI classes. */
 export const decodeNibArchive = (bytes, budget = new InterfaceBuilderDecodeBudget(DEFAULT_DECODE_BUDGET_BYTES)) => {
-    if (bytes.length < 50 || !bytes.subarray(0, MAGIC.length).equals(MAGIC))
+    if (bytes.length < 50 || !hasNibArchiveSignature(bytes))
         throw new TypeError("NIBArchive magic or header is invalid");
     const formatVersion = readU32(bytes, 10);
     const coderVersion = readU32(bytes, 14);
@@ -50,7 +50,13 @@ export const decodeNibArchive = (bytes, budget = new InterfaceBuilderDecodeBudge
                 continue;
             const key = keys[value.key_index];
             if (key !== undefined)
-                fields[key] = value.value;
+                // Archive keys are data, including the legacy __proto__ setter name.
+                Object.defineProperty(fields, key, {
+                    value: value.value,
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                });
         }
         return [{ id, class_name: className, values: fields }];
     });
@@ -296,7 +302,8 @@ const readU32 = (bytes, offset) => {
 };
 const decodeUtf8 = (bytes, start, end, label) => {
     try {
-        return new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(start, end));
+        // These are length-prefixed names, not standalone text documents.
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes.subarray(start, end));
     }
     catch (cause) {
         throw new TypeError(`NIBArchive ${label} is not valid UTF-8`, {

package/dist/artifacts/apple/PlistNumberLiterals.js

@@ -1,4 +1,5 @@
 import { decodeXmlText } from "../../domain/propertyListKeys.js";
+import { hasBinaryPlistSignature } from "../../domain/apple/appleArchiveFormat.js";
 const collector = () => {
     const integers = new Map();
     const reals = new Set();
@@ -106,8 +107,7 @@ export const xmlPlistNumberLiterals = (xml) => {
 /** Observe bounded binary number markers without changing primary decode acceptance. */
 export const binaryPlistNumberLiterals = (bytes) => {
     const output = collector();
-    if (bytes.length < 40 ||
-        bytes.subarray(0, 8).toString("ascii") !== "bplist00")
+    if (bytes.length < 40 || !hasBinaryPlistSignature(bytes))
         return output.result(true);
     const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
     const trailer = bytes.length - 32;

package/dist/artifacts/extraction/ArtifactExtraction.js

@@ -9,10 +9,11 @@ import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
 import { SafeOutputTree } from "../SafeOutputTree.js";
 import { SafeOutputTreeCreationFailure } from "../SafeOutputTreeCreationFailure.js";
 import { ZipArtifactReader } from "../ZipArtifactReader.js";
+import { isZipPackageFormat } from "../../domain/zipPackageFormat.js";
 import { MachOSliceArtifactReader } from "../MachOSliceArtifactReader.js";
 import { artifactExtractionResultSchema, } from "../../domain/artifactGraph.js";
 import { AnalysisUnsupportedTargetError } from "../../domain/analysisErrorCore.js";
-import {} from "../ArtifactResourceScope.js";
+import { isMachOFormat, } from "../../domain/binaryTargetTypes.js";
 import { scanArtifactInventoryInScope } from "../inventory/ArtifactInventory.js";
 /** Extract every regular inventory occurrence into an exclusively owned absent root. */
 export const extractArtifact = async (input, signal) => input.resourceScope.run(() => extractArtifactInScope(input, signal));
@@ -120,7 +121,7 @@ const materializeSelection = async ({ input, sourcePath, inventory, selected, si
             throw ArtifactReaderFailure.withCleanup(closeAttempt.cause, ArtifactReaderFailure.cleanupObservation(closeAttempt.cause, readerOwner.resource));
         extracted.sort((left, right) => compareUnicodeCodePoints(left.relative_path, right.relative_path));
         completed = createExtractionResult(input, inventory, selected, extracted);
-        await output.commit();
+        await output.commit(signal);
         return completed;
     }
     catch (cause) {
@@ -220,8 +221,6 @@ const createExtractionResult = (input, inventory, selected, extracted) => {
         ],
     });
 };
-const ZIP_FORMATS = ["ipa", "apk", "msix", "appx", "zip"];
-const isZipFormat = (format) => ZIP_FORMATS.includes(format);
 /**
  * Refuse a format without an extraction reader before inventory work starts.
  * The target kind, not the host, is unsupported by extraction. The error keeps
@@ -232,8 +231,8 @@ const requireExtractableFormat = async (path, input) => {
     const directory = (await lstat(path)).isDirectory();
     if (!directory &&
         format !== "asar" &&
-        format !== "mach-o" &&
-        !isZipFormat(format))
+        !isMachOFormat(format) &&
+        !isZipPackageFormat(format))
         throw new AnalysisUnsupportedTargetError("extract_artifact", input.inputPath, `Artifact format has no extraction reader: ${format}`);
     return directory;
 };
@@ -243,7 +242,7 @@ const createReader = async (path, input) => {
         return new DirectoryArtifactReader(path);
     if (format === "asar")
         return new AsarArtifactReader(path);
-    if (isZipFormat(format))
+    if (isZipPackageFormat(format))
         return new ZipArtifactReader(path, format);
     return new MachOSliceArtifactReader(path, input.environment);
 };

package/dist/artifacts/hostExecutableMarking.js

@@ -0,0 +1,16 @@
+import { extname } from "node:path";
+/** Extensions Windows launches directly through CreateProcess or cmd.exe. */
+const windowsLaunchableExtensions = new Set([".bat", ".cmd", ".com", ".exe"]);
+/**
+ * Whether a host filesystem entry carries the host's executable marking.
+ *
+ * POSIX hosts mark executability with permission bits. Windows has no execute
+ * bit (Node reports file modes from the read-only attribute alone), so it marks
+ * launchable files by extension instead.
+ */
+export const hostExecutableMarking = (path, metadata, platform = process.platform) => platform === "win32"
+    ? metadata.isFile() &&
+        windowsLaunchableExtensions.has(extname(path).toLowerCase())
+    : typeof metadata.mode === "bigint"
+        ? (metadata.mode & 73n) !== 0n
+        : (metadata.mode & 0o111) !== 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,36 @@ 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) {
+        const isSourceMap = occurrence.logical_path.toLowerCase().endsWith(".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 +217,9 @@ 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"
+                    : relationFor(occurrence.logical_path),
             occurrence_id: occurrence.occurrence_id,
         };
         edges.push({
@@ -189,17 +229,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 +258,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 +279,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 +312,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 +330,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 +380,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,21 +399,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 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";
+};
 const relationFor = (path) => {
     const lower = path.toLowerCase();
     if (lower.endsWith(".map"))

package/dist/artifacts/inventory/ArtifactInventory.js

@@ -1,11 +1,11 @@
 import { realpath } from "node:fs/promises";
-import { artifactInventoryResultSchema, } from "../../domain/artifactGraph.js";
+import { artifactInventoryOutputSchema, } from "../../domain/artifactGraph.js";
 import { abortIfNeeded } from "../ArtifactHash.js";
 import { scanCanonicalArtifactInventoryInScope } from "./scanCanonical.js";
 /** Inventory one local artifact and return every graph collection inline. */
 export const inventoryArtifact = async (inputPath, options) => {
     const snapshot = await scanArtifactInventory(inputPath, options);
-    return artifactInventoryResultSchema.parse(snapshot);
+    return artifactInventoryOutputSchema.parse(snapshot);
 };
 /** Scan an artifact once and retain the complete immutable graph for projection. */
 export const scanArtifactInventory = async (inputPath, options) => options.resourceScope.run(() => scanArtifactInventoryInScope(inputPath, options));