rea-agents 6.2.0 → 6.4.0

package/dist/artifacts/apple/MachoLoadCommandReader.js

@@ -29,6 +29,41 @@ const LC_VERSION_MIN_IPHONEOS = 0x25;
 const LC_VERSION_MIN_TVOS = 0x2f;
 const LC_VERSION_MIN_WATCHOS = 0x30;
 const LC_BUILD_VERSION = 0x32;
+// `mach-o/loader.h` `PLATFORM_*` numbers observed via Apple linker output.
+const PLATFORM_MACOS = 1;
+const PLATFORM_IOS = 2;
+const PLATFORM_TVOS = 3;
+const PLATFORM_WATCHOS = 4;
+const PLATFORM_IOSSIMULATOR = 7;
+const PLATFORM_TVOSSIMULATOR = 8;
+const PLATFORM_WATCHOSSIMULATOR = 9;
+const CPU_TYPE_I386 = 7;
+const CPU_TYPE_X86_64 = 0x01000007;
+/**
+ * Legacy `LC_VERSION_MIN_*` commands predate explicit simulator platform
+ * IDs. Per Apple's dyld rules the image CPU type distinguishes simulator
+ * from device: Intel images are simulator, ARM images are device
+ * (tvOS simulator applies to x86_64 only). `LC_BUILD_VERSION` platform
+ * numbers are preserved verbatim; unknown future numbers stay unknown
+ * downstream, never mapped to nearest.
+ */
+const legacyVersionMinPlatform = (command, cpuType) => {
+    const isIntel = cpuType === CPU_TYPE_I386 || cpuType === CPU_TYPE_X86_64;
+    switch (command) {
+        case LC_VERSION_MIN_MACOSX:
+            return PLATFORM_MACOS;
+        case LC_VERSION_MIN_IPHONEOS:
+            return isIntel ? PLATFORM_IOSSIMULATOR : PLATFORM_IOS;
+        case LC_VERSION_MIN_TVOS:
+            return cpuType === CPU_TYPE_X86_64
+                ? PLATFORM_TVOSSIMULATOR
+                : PLATFORM_TVOS;
+        case LC_VERSION_MIN_WATCHOS:
+            return isIntel ? PLATFORM_WATCHOSSIMULATOR : PLATFORM_WATCHOS;
+        default:
+            return undefined;
+    }
+};
 /** `mach-o/loader.h` `dylib_use_command`: `nameoff == 28` and this marker. */
 const DYLIB_USE_MARKER = 0x1a741800;
 const DYLIB_USE_WEAK_LINK = 0x1;
@@ -258,12 +293,7 @@ const decodeCommand = (command, body, index, slice) => {
         slice.platforms.push(platform);
         return;
     }
-    const legacyPlatform = new Map([
-        [LC_VERSION_MIN_MACOSX, 1],
-        [LC_VERSION_MIN_IPHONEOS, 2],
-        [LC_VERSION_MIN_TVOS, 3],
-        [LC_VERSION_MIN_WATCHOS, 4],
-    ]).get(command);
+    const legacyPlatform = legacyVersionMinPlatform(command, slice.cpu_type);
     if (legacyPlatform !== undefined) {
         if (body.byteLength < 16)
             throw new MachoFormatIssue("malformed", `load command ${index} is too short for a version-min command`);

package/dist/artifacts/extraction/ArtifactExtraction.js

@@ -1,50 +1,85 @@
 import { lstat, realpath } from "node:fs/promises";
-import { compareCodePoints } from "../../domain/canonicalOrdering.js";
-import { canonicalDigest } from "../../domain/comparisonSemantics.js";
+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
+import { digestCanonicalValue } from "../../domain/canonicalDigest.js";
 import { AsarArtifactReader } from "../AsarArtifactReader.js";
 import { ArtifactPathRegistry, normalizeArtifactPath, } from "../ArtifactPaths.js";
 import { ArtifactReaderFailure, } from "../ArtifactReader.js";
 import { abortIfNeeded } from "../ArtifactHash.js";
 import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
 import { SafeOutputTree } from "../SafeOutputTree.js";
+import { SafeOutputTreeCreationFailure } from "../SafeOutputTreeCreationFailure.js";
 import { ZipArtifactReader } from "../ZipArtifactReader.js";
 import { MachOSliceArtifactReader } from "../MachOSliceArtifactReader.js";
 import { artifactExtractionResultSchema, } from "../../domain/artifactGraph.js";
 import { AnalysisUnsupportedTargetError } from "../../domain/analysisErrorCore.js";
-import { scanArtifactInventory } from "../inventory/ArtifactInventory.js";
+import {} from "../ArtifactResourceScope.js";
+import { scanArtifactInventoryInScope } from "../inventory/ArtifactInventory.js";
 /** Extract every regular inventory occurrence into an exclusively owned absent root. */
-export const extractArtifact = async (input, signal) => {
+export const extractArtifact = async (input, signal) => input.resourceScope.run(() => extractArtifactInScope(input, signal));
+const extractArtifactInScope = async (input, signal) => {
     // Cancellation wins over every later refusal, including unsupported formats.
     abortIfNeeded(signal);
     const sourcePath = await realpath(input.inputPath);
     await requireExtractableFormat(sourcePath, input);
-    const snapshot = await scanArtifactInventory(sourcePath, {
+    const snapshot = await scanArtifactInventoryInScope(sourcePath, {
+        resourceScope: input.resourceScope,
         signal,
         environment: input.environment,
+        integrity: { mode: input.integrityPolicy },
     });
+    return materializeArtifactInventoryInScope(input, sourcePath, snapshot, signal);
+};
+/** Materialize a scanned inventory, verifying every current occurrence against it. */
+export const materializeArtifactInventory = async (input, sourcePath, snapshot, signal) => {
+    return input.resourceScope.run(() => materializeArtifactInventoryInScope(input, sourcePath, snapshot, signal));
+};
+const materializeArtifactInventoryInScope = async (input, sourcePath, snapshot, signal) => {
+    abortIfNeeded(signal);
     const selectedOccurrences = snapshot.occurrences.filter((occurrence) => (occurrence.entry_kind === "file" || occurrence.entry_kind === "slice") &&
         occurrence.logical_path !== ".");
-    const selectedIds = new Set(selectedOccurrences.map(({ occurrence_id: id }) => id));
-    const occurrences = new Map();
-    const neededNodes = new Set();
-    collectOccurrences(snapshot.occurrences, selectedIds, occurrences, neededNodes);
+    const regularPaths = new Set(selectedOccurrences.map(({ logical_path: path }) => path));
+    const activeOccurrences = selectedOccurrences.filter(({ logical_path }) => {
+        // Nested members remain represented by their containing regular file;
+        // only entries exposed by the active reader are materialized.
+        let path = logical_path;
+        for (let slash = path.lastIndexOf("/"); slash >= 0; slash = path.lastIndexOf("/")) {
+            path = path.slice(0, slash);
+            if (regularPaths.has(path))
+                return false;
+        }
+        return true;
+    });
+    const selectedIds = new Set(activeOccurrences.map(({ occurrence_id: id }) => id));
+    const neededNodes = new Set(activeOccurrences.map(({ artifact_id: id }) => id));
     const nodes = new Map();
-    collectNodes(snapshot.nodes, neededNodes, nodes);
+    for (const node of snapshot.nodes)
+        if (neededNodes.has(node.artifact_id))
+            nodes.set(node.artifact_id, node);
     const inventory = {
         manifest: snapshot.manifest,
-        occurrences,
-        nodes,
+        integrityContradictions: snapshot.integrity_contradictions.filter(({ occurrence_id: id }) => selectedIds.has(id)),
     };
-    const selected = selectedOccurrences.map((occurrence) => {
+    const selected = activeOccurrences.map((occurrence) => {
         // REA never decrypts archive entries, so an encrypted entry makes the
         // complete extraction unsupported rather than the archive invalid.
         if (occurrence.encrypted)
             throw new AnalysisUnsupportedTargetError("extract_artifact", input.inputPath, `Archive entry ${occurrence.logical_path} is encrypted; REA does not decrypt archive entries, so the archive cannot be extracted completely`);
+        // Inventory keeps an ASAR unpacked entry whose companion file is absent,
+        // but extraction cannot materialize bytes it never observed.
+        if (occurrence.entry_kind === "file" &&
+            occurrence.artifact_id === null &&
+            occurrence.hash_status === "unavailable")
+            throw new ArtifactReaderFailure("unavailable", `ASAR unpacked companion bytes are unavailable for ${occurrence.logical_path}`, undefined, {
+                logicalPath: occurrence.logical_path,
+                declaredSha256: null,
+                calculatedSha256: null,
+                unpacked: true,
+            });
         if ((occurrence.entry_kind !== "file" && occurrence.entry_kind !== "slice") ||
             occurrence.artifact_id === null ||
             occurrence.logical_path === ".")
             throw new ArtifactReaderFailure("format", `Selected occurrence is not an extractable regular child file: ${occurrence.logical_path} (${occurrence.occurrence_id})`);
-        const node = inventory.nodes.get(occurrence.artifact_id);
+        const node = nodes.get(occurrence.artifact_id);
         if (node === undefined)
             throw new ArtifactReaderFailure("integrity", `Selected occurrence has no inventory node: ${occurrence.occurrence_id}`);
         return { occurrence, node };
@@ -60,73 +95,36 @@ export const extractArtifact = async (input, signal) => {
 const materializeSelection = async ({ input, sourcePath, inventory, selected, signal, }) => {
     const byPath = new Map(selected.map((item) => [item.occurrence.logical_path, item]));
     const reader = await createReader(sourcePath, input);
+    const readerOwner = {
+        kind: "reader",
+        reader,
+        resource: `artifact reader for ${sourcePath}`,
+    };
+    let localReaderOwner = readerOwner;
     let output;
-    let readerCloseAttempted = false;
-    let readerClosed = false;
+    let completed;
     const extracted = [];
     try {
-        output = await SafeOutputTree.create(input.outputRoot);
-        const materialized = [];
-        const registry = new ArtifactPathRegistry();
-        for await (const entry of reader.entries(signal)) {
-            const path = normalizeArtifactPath(entry.path);
-            registry.add(path, entry.kind);
-            const selectedItem = byPath.get(path);
-            if (selectedItem === undefined) {
-                if (entry.kind === "file" || entry.kind === "slice")
-                    throw new ArtifactReaderFailure("integrity", `Regular artifact entry is missing from inventory: ${path}`);
-                continue;
-            }
-            preflight(entry);
-            const stream = await reader.open(entry, signal);
-            const written = await output.write(path, stream, selectedItem.node.sha256, signal);
-            extracted.push({
-                artifact_id: selectedItem.node.artifact_id,
-                relative_path: written.relativePath,
-                sha256: written.sha256,
-                bytes_written: written.bytesWritten,
-                created: true,
-            });
-            materialized.push(selectedItem);
+        try {
+            output = await SafeOutputTree.create(input.outputRoot);
+        }
+        catch (cause) {
+            if (cause instanceof SafeOutputTreeCreationFailure)
+                output = cause.tree;
+            throw cause;
         }
-        readerCloseAttempted = true;
-        await reader.close();
-        readerClosed = true;
-        extracted.sort((left, right) => compareCodePoints(left.relative_path, right.relative_path));
-        const result = createExtractionResult(input, inventory, materialized, extracted);
+        await writeSelectedEntries({ reader, output, byPath, extracted, signal });
+        localReaderOwner = undefined;
+        const closeAttempt = await input.resourceScope.release(readerOwner);
+        if (closeAttempt.kind === "failed")
+            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();
-        return result;
+        return completed;
     }
     catch (cause) {
-        const cleanupFailures = [];
-        if (readerCloseAttempted && !readerClosed)
-            cleanupFailures.push({
-                cause,
-                resource: `artifact reader for ${sourcePath}`,
-            });
-        if (!readerCloseAttempted) {
-            try {
-                readerCloseAttempted = true;
-                await reader.close();
-            }
-            catch (cleanupCause) {
-                cleanupFailures.push({
-                    cause: cleanupCause,
-                    resource: `artifact reader for ${sourcePath}`,
-                });
-            }
-        }
-        if (output !== undefined) {
-            try {
-                await output.rollback();
-            }
-            catch (cleanupCause) {
-                cleanupFailures.push({
-                    cause: cleanupCause,
-                    resource: input.outputRoot,
-                });
-            }
-        }
+        const cleanupFailures = await releaseExtractionOwners(input.resourceScope, localReaderOwner, output, input.outputRoot);
         if (cleanupFailures.length > 0) {
             const observations = cleanupFailures.map(({ cause: cleanupCause, resource }) => ArtifactReaderFailure.cleanupObservation(cleanupCause, resource));
             throw ArtifactReaderFailure.withCleanup(cause, {
@@ -134,50 +132,94 @@ const materializeSelection = async ({ input, sourcePath, inventory, selected, si
                 resources: [
                     ...new Set(observations.flatMap(({ resources }) => resources)),
                 ],
-            });
+            }, output?.published === true && completed !== undefined
+                ? { kind: "artifact-extraction", extraction: completed }
+                : undefined);
         }
+        if (output?.published === true && completed !== undefined)
+            return completed;
         throw cause;
     }
 };
+const writeSelectedEntries = async ({ reader, output, byPath, extracted, signal, }) => {
+    const registry = new ArtifactPathRegistry();
+    for await (const entry of reader.entries(signal)) {
+        const path = normalizeArtifactPath(entry.path);
+        registry.add(path, entry.kind);
+        const selectedItem = byPath.get(path);
+        if (selectedItem === undefined) {
+            if (entry.kind === "file" || entry.kind === "slice")
+                throw new ArtifactReaderFailure("integrity", `Regular artifact entry is missing from inventory: ${path}`);
+            continue;
+        }
+        preflight(entry);
+        const stream = await reader.open(entry, signal);
+        const written = await output.write(path, stream, {
+            sha256: selectedItem.node.sha256,
+            bytes: selectedItem.node.size,
+        }, signal);
+        extracted.push({
+            artifact_id: selectedItem.node.artifact_id,
+            relative_path: written.relativePath,
+            sha256: written.sha256,
+            bytes_written: written.bytesWritten,
+            created: true,
+        });
+        byPath.delete(path);
+    }
+    if (byPath.size > 0)
+        throw new ArtifactReaderFailure("integrity", `Inventoried regular artifact entries were not materialized: ${[...byPath.keys()].sort(compareUnicodeCodePoints).join(", ")}`);
+};
+const releaseExtractionOwners = async (resourceScope, readerOwner, output, outputRoot) => {
+    const failures = [];
+    if (readerOwner !== undefined) {
+        const attempt = await resourceScope.release(readerOwner);
+        if (attempt.kind === "failed")
+            failures.push({ cause: attempt.cause, resource: readerOwner.resource });
+    }
+    if (output !== undefined) {
+        const owner = {
+            kind: "output-tree",
+            tree: output,
+            resource: outputRoot,
+        };
+        const attempt = await resourceScope.release(owner);
+        if (attempt.kind === "failed")
+            failures.push({ cause: attempt.cause, resource: owner.resource });
+    }
+    return failures;
+};
 const createExtractionResult = (input, inventory, selected, extracted) => {
     const extractionSemantic = {
         source_manifest_id: inventory.manifest.manifest_id,
         selected_occurrence_ids: selected
             .map(({ occurrence }) => occurrence.occurrence_id)
-            .sort(compareCodePoints),
-        files_sha256: canonicalDigest(extracted, "Artifact"),
+            .sort(compareUnicodeCodePoints),
+        files_sha256: digestCanonicalValue(extracted, "Artifact"),
         output_root_alias: "$OUTPUT_ROOT",
     };
     return artifactExtractionResultSchema.parse({
         manifest: inventory.manifest,
         extraction_manifest: {
             ...extractionSemantic,
-            extraction_id: `aex_${canonicalDigest(extractionSemantic, "Artifact")}`,
+            extraction_id: `aex_${digestCanonicalValue(extractionSemantic, "Artifact")}`,
         },
         output_root: input.outputRoot,
         artifacts: extracted,
         containment_verified: true,
         cleanup: { attempted: false, verified: true, residual_paths: [] },
         provenance: [],
+        integrity_contradictions: inventory.integrityContradictions,
         limitations: [
             "All regular files in the active artifact were materialized; nested archive contents remain represented by their containing file.",
+            ...(inventory.integrityContradictions.length === 0
+                ? []
+                : [
+                    `${String(inventory.integrityContradictions.length)} extracted file(s) contradict declared integrity metadata; their bytes are observed-untrusted.`,
+                ]),
         ],
     });
 };
-const collectOccurrences = (items, selected, output, neededNodes) => {
-    for (const item of items) {
-        if (!selected.has(item.occurrence_id))
-            continue;
-        output.set(item.occurrence_id, item);
-        if (item.artifact_id !== null)
-            neededNodes.add(item.artifact_id);
-    }
-};
-const collectNodes = (items, selected, output) => {
-    for (const item of items)
-        if (selected.has(item.artifact_id))
-            output.set(item.artifact_id, item);
-};
 const ZIP_FORMATS = ["ipa", "apk", "msix", "appx", "zip"];
 const isZipFormat = (format) => ZIP_FORMATS.includes(format);
 /**

package/dist/artifacts/inventory/ArtifactGraphConstruction.js

@@ -1,5 +1,5 @@
-import { compareCodePoints } from "../../domain/canonicalOrdering.js";
-import { canonicalDigest } from "../../domain/comparisonSemantics.js";
+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
+import { digestCanonicalValue } from "../../domain/canonicalDigest.js";
 import { artifactEdgeId, artifactIdForContent, occurrenceIdForLocation, } from "../../domain/artifactIdentity.js";
 import { hasZipSignature, zipPackageFormatForPath, } from "../../domain/zipPackageFormat.js";
 import { mzWindowsHeaderOffset, parseDosMzHeader } from "../../domain/dosMz.js";
@@ -11,32 +11,55 @@ export const indexOccurrencesByPath = (occurrences) => {
             byPath.set(occurrence.logical_path, occurrence);
     return byPath;
 };
-export const createOccurrence = (entry, path, parent) => ({
-    occurrence_id: `occ_${canonicalDigest({ path, kind: entry.kind }, "Artifact")}`,
-    artifact_id: null,
-    parent_occurrence_id: parent,
-    logical_path: path,
-    entry_kind: entry.kind,
-    artifact_kind: entry.kind === "directory"
-        ? path.toLowerCase().endsWith(".framework")
-            ? "framework"
-            : "container"
-        : classifyArtifactPath(path).kind,
-    artifact_format: entry.kind === "directory"
-        ? "directory"
-        : classifyArtifactPath(path).format,
-    declared_size: entry.declaredSize,
-    compressed_size: entry.compressedSize,
-    executable: entry.executable,
-    encrypted: entry.encrypted,
-    hash_status: entry.encrypted ? "unavailable" : "not-hashed",
-    source_location: entry.byteOffset === null || entry.declaredSize === null
-        ? null
-        : { offset: entry.byteOffset, length: entry.declaredSize },
-    limitations: [...entry.limitations],
-});
+/**
+ * Create an occurrence before its bytes are read. A container suffix is not a
+ * 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) => {
+    const role = entry.kind === "directory"
+        ? {
+            kind: path.toLowerCase().endsWith(".framework")
+                ? "framework"
+                : "container",
+            format: "directory",
+        }
+        : containerSuffixFamily(path) === undefined
+            ? classifyArtifactPath(path)
+            : { kind: "unknown", format: "unknown" };
+    return {
+        occurrence_id: `occ_${digestCanonicalValue({ path, kind: entry.kind }, "Artifact")}`,
+        artifact_id: null,
+        parent_occurrence_id: parent,
+        logical_path: path,
+        entry_kind: entry.kind,
+        artifact_kind: role.kind,
+        artifact_format: role.format,
+        declared_size: entry.declaredSize,
+        compressed_size: entry.compressedSize,
+        executable: entry.executable,
+        encrypted: entry.encrypted,
+        hash_status: entry.encrypted ? "unavailable" : "not-hashed",
+        source_location: entry.byteOffset === null || entry.declaredSize === null
+            ? null
+            : { offset: entry.byteOffset, length: entry.declaredSize },
+        limitations: [...entry.limitations],
+    };
+};
+/** Record that an unread member's container suffix was not checked against bytes. */
+export const noteUnreadContainerSuffix = (occurrence) => {
+    if (occurrence.entry_kind === "directory")
+        return;
+    const family = containerSuffixFamily(occurrence.logical_path);
+    if (family === undefined)
+        return;
+    occurrence.limitations.push(`The path suffix suggests ${family.toUpperCase()}, but these bytes were not read, so the container family is unknown.`);
+};
+const containerSuffixFamily = (path) => {
+    const lower = path.toLowerCase();
+    return lower.endsWith(".asar") ? "asar" : zipPackageFormatForPath(lower);
+};
 /** Compare exact child names independently of host locale and traversal order. */
-export const compareDirectoryChildNames = compareCodePoints;
 export const materializeDirectoryNodes = (occurrences, nodes) => {
     const directories = occurrences
         .filter(({ entry_kind: kind }) => kind === "directory")
@@ -59,9 +82,9 @@ export const materializeDirectoryNodes = (occurrences, nodes) => {
             artifact_id,
             entry_kind,
         }))
-            .sort((left, right) => compareDirectoryChildNames(left.name, right.name));
+            .sort((left, right) => compareUnicodeCodePoints(left.name, right.name));
         const node = createArtifactNode({
-            sha256: canonicalDigest({ kind: "directory", children }, "Artifact"),
+            sha256: digestCanonicalValue({ kind: "directory", children }, "Artifact"),
             size: 0,
             format: "directory",
             contentState: "virtual",
@@ -73,14 +96,14 @@ export const materializeDirectoryNodes = (occurrences, nodes) => {
 };
 export const createRootNode = (input) => createArtifactNode({
     sha256: input.digest?.sha256 ??
-        canonicalDigest({
+        digestCanonicalValue({
             kind: "directory-root",
             children: input.occurrences
                 .map(({ logical_path, artifact_id }) => ({
                 logical_path,
                 artifact_id,
             }))
-                .sort((left, right) => compareDirectoryChildNames(left.logical_path, right.logical_path)),
+                .sort((left, right) => compareUnicodeCodePoints(left.logical_path, right.logical_path)),
         }, "Artifact"),
     size: input.digest?.bytes ?? 0,
     format: input.digest === null
@@ -154,15 +177,13 @@ export const createArtifactEdges = (rootArtifactId, occurrences, producer) => {
             rootArtifactId;
         const semantic = {
             parent_artifact_id: parentArtifactId,
-            child_artifact_id: occurrence.artifact_id,
             relation: occurrence.entry_kind === "slice"
                 ? "slice-of"
                 : relationFor(occurrence.logical_path),
             occurrence_id: occurrence.occurrence_id,
-            logical_path: occurrence.logical_path,
         };
         edges.push({
-            edge_id: artifactEdgeId(semantic),
+            edge_id: artifactEdgeId(semantic, occurrence),
             ...semantic,
             producer: occurrence.entry_kind === "slice" ? (producer ?? null) : null,
             ordinal: edges.length,
@@ -170,29 +191,55 @@ export const createArtifactEdges = (rootArtifactId, occurrences, producer) => {
     }
     return edges;
 };
-export const nearestParent = (path, occurrences, expandedContainerIds) => {
-    const parts = path.split("/");
-    while (parts.length > 1) {
-        parts.pop();
-        const candidate = occurrences.get(parts.join("/"));
-        if (candidate !== undefined &&
-            (candidate.entry_kind === "directory" ||
-                expandedContainerIds.has(candidate.occurrence_id)))
-            return candidate;
+/** 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))
+            continue;
+        let branch = root;
+        for (const segment of occurrence.logical_path.split("/")) {
+            let child = branch.children.get(segment);
+            if (child === undefined) {
+                child = { children: new Map() };
+                branch.children.set(segment, child);
+            }
+            branch = child;
+        }
+        branch.occurrence = occurrence;
+    }
+    for (const occurrence of occurrences) {
+        const path = occurrence.logical_path;
+        let branch = root;
+        let parent;
+        // Walk parent segments only. Stop scanning the path once no observed
+        // directory or expanded container can be an ancestor.
+        for (let start = 0;;) {
+            const slash = path.indexOf("/", start);
+            if (slash < 0)
+                break;
+            const segment = path.slice(start, slash);
+            const child = branch.children.get(segment);
+            if (child === undefined)
+                break;
+            branch = child;
+            parent = branch.occurrence ?? parent;
+            start = slash + 1;
+        }
+        occurrence.parent_occurrence_id = parent?.occurrence_id ?? null;
     }
-    return undefined;
 };
+/**
+ * Assign a path role hint. Container families are not path roles: ZIP and
+ * ASAR families are chosen only after their bytes have been classified.
+ */
 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))
         return { kind: "javascript", format: "javascript-bundle" };
-    if (lower.endsWith(".asar"))
-        return { kind: "container", format: "asar" };
-    const archiveFormat = zipPackageFormatForPath(lower);
-    if (archiveFormat !== undefined)
-        return { kind: "container", format: archiveFormat };
     if (/\.framework(?:\/|$)/u.test(lower))
         return { kind: "framework", format: "file" };
     if (/\.(?:node|dylib|so)$/u.test(lower))
@@ -208,7 +255,26 @@ export const classifyArtifactPath = (path) => {
 };
 /** Classify executable formats from bytes while retaining path-specific roles. */
 export const classifyArtifactContent = (path, prefix, fileSize = prefix.length) => {
-    return artifactRoleForFormat(path, classifyArtifactBytes(prefix, fileSize));
+    const format = classifyArtifactBytes(prefix, fileSize);
+    if (format === "file" &&
+        path.toLowerCase().endsWith(".asar") &&
+        hasAsarHeader(prefix))
+        return { kind: "container", format: "asar" };
+    return artifactRoleForFormat(path, format);
+};
+/**
+ * Electron ASAR starts with a size pickle whose payload is one uint32, then
+ * a header pickle whose payload begins with a JSON object.
+ */
+export const hasAsarHeader = (prefix) => {
+    if (prefix.length < 17 || prefix.readUInt32LE(0) !== 4)
+        return false;
+    const headerSize = prefix.readUInt32LE(4);
+    const payloadSize = prefix.readUInt32LE(8);
+    if (headerSize < 16 || payloadSize !== headerSize - 4)
+        return false;
+    const stringLength = prefix.readUInt32LE(12);
+    return (stringLength >= 2 && stringLength <= payloadSize - 4 && prefix[16] === 0x7b);
 };
 const artifactRoleForFormat = (path, format) => {
     const byPath = classifyArtifactPath(path);

package/dist/artifacts/inventory/ArtifactInventory.js

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