rea-agents 6.4.0 → 6.5.0

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) => {
@@ -39,9 +39,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: {
@@ -65,32 +65,49 @@ export const classifyAndHashRootForInventory = async (path, directory, expectedM
         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/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."],
+    };
 };

package/dist/artifacts/inventory/scanCanonical.js

@@ -3,12 +3,12 @@ import { AsarArtifactReader } from "../AsarArtifactReader.js";
 import { lstat } from "node:fs/promises";
 import { ArtifactReaderFailure, } from "../ArtifactReader.js";
 import { artifactInventoryResultSchema, } from "../../domain/artifactGraph.js";
-import { createArtifactEdges, createRootNode, indexOccurrencesByPath, materializeDirectoryNodes, rekeyOccurrences, rootOccurrenceFor, } from "./ArtifactGraphConstruction.js";
+import { createArtifactEdges, createRootNode, materializeDirectoryNodes, rekeyOccurrences, rootOccurrenceFor, } from "./ArtifactGraphConstruction.js";
 import { artifactContradictionId, artifactGraphDigest, artifactManifestId, } from "../../domain/artifactIdentity.js";
 import { classifyAndHashRootForInventory } from "./classify.js";
-import {} from "../ArtifactHash.js";
+import { hostExecutableMarking } from "../hostExecutableMarking.js";
 import { hashStableRootArtifact, hashStableRootArtifactHandle, } from "./hashStableRootArtifact.js";
-import { createReader, inventoryLimitations } from "./reader.js";
+import { createReader, inventoryCoverage } from "./reader.js";
 import { scanReader, } from "./scanReader.js";
 import { STRICT_INTEGRITY_POLICY, } from "./types.js";
 export const scanCanonicalArtifactInventory = async (path, options, readerFactory = createReader) => options.resourceScope.run(() => scanCanonicalArtifactInventoryInScope(path, options, readerFactory));
@@ -31,7 +31,7 @@ export const scanCanonicalArtifactInventoryInScope = async (path, options, reade
             throw readerCreationFailure.cause;
         if (reader instanceof AsarArtifactReader)
             await reader.prepareContainer(rootDigest?.sha256, options.signal);
-        const { nodes, occurrences, pendingContradictions, caseCollisionLimitation, } = await scanReader(reader, ownedReaders, options.signal, integrity);
+        const { nodes, occurrences, pendingContradictions, caseCollisionLimitation, unknownParentOccurrences, traversal, } = await scanReader(reader, ownedReaders, options.signal, integrity);
         outcome = {
             kind: "completed",
             snapshot: await buildInventorySnapshot({
@@ -47,6 +47,8 @@ export const scanCanonicalArtifactInventoryInScope = async (path, options, reade
                 occurrences,
                 pendingContradictions,
                 caseCollisionLimitation,
+                unknownParentOccurrences,
+                traversal,
             }),
         };
     }
@@ -104,21 +106,22 @@ const buildInventorySnapshot = async (input) => {
     rekeyOccurrences(rootNode.artifact_id, input.occurrences);
     const rootOccurrence = rootOccurrenceFor(rootNode, {
         size: metadata.size,
-        executable: (metadata.mode & 0o111) !== 0,
+        executable: hostExecutableMarking(path, metadata),
         format: rootFormat,
         path,
     });
     for (const occurrence of input.occurrences)
-        if (occurrence.parent_occurrence_id === null)
+        if (occurrence.parent_occurrence_id === null &&
+            !input.unknownParentOccurrences.has(occurrence))
             occurrence.parent_occurrence_id = rootOccurrence.occurrence_id;
     input.occurrences.unshift(rootOccurrence);
     const occurrenceById = new Map(input.occurrences.map((occurrence) => [
         occurrence.occurrence_id,
         occurrence,
     ]));
-    const occurrenceByPath = indexOccurrencesByPath(input.occurrences);
-    const integrityContradictions = buildIntegrityContradictions(input.pendingContradictions, occurrenceByPath, occurrenceById, rootNode);
-    const edges = createArtifactEdges(rootNode.artifact_id, input.occurrences, reader?.provenance()[0]);
+    const integrityContradictions = buildIntegrityContradictions(input.pendingContradictions, occurrenceById, rootNode);
+    const edgeResult = createArtifactEdges(rootNode.artifact_id, input.occurrences, reader?.provenance()[0]);
+    const { edges } = edgeResult;
     const orderedNodes = sortNodes([...input.nodes.values()]);
     const orderedOccurrences = sortOccurrences(input.occurrences);
     const orderedEdges = sortEdges(edges).map((edge, ordinal) => ({
@@ -140,6 +143,10 @@ const buildInventorySnapshot = async (input) => {
         orderedOccurrences,
         orderedEdges,
     });
+    const traversal = inventoryCoverage(rootFormat, reader, input.traversal);
+    const coverage = edgeResult.limitations.length === 0
+        ? traversal.coverage
+        : { ...traversal.coverage, status: "unknown" };
     return {
         manifest,
         nodes: orderedNodes,
@@ -147,13 +154,13 @@ const buildInventorySnapshot = async (input) => {
         edges: orderedEdges,
         provenance: reader?.provenance() ?? [],
         integrity_contradictions: integrityContradictions,
-        limitations: buildLimitations(rootFormat, reader, integrityContradictions, input.caseCollisionLimitation),
+        coverage,
+        coverage_status: coverage.status === "complete" ? "complete" : "partial",
+        limitations: buildLimitations([...traversal.limitations, ...edgeResult.limitations], integrityContradictions, input.caseCollisionLimitation),
     };
 };
-const buildIntegrityContradictions = (pending, occurrenceByPath, occurrenceById, rootNode) => pending.map((contradiction) => {
-    const occurrence = occurrenceByPath.get(contradiction.logicalPath);
-    if (occurrence === undefined)
-        throw new ArtifactReaderFailure("integrity", "Integrity contradiction lost its graph occurrence");
+const buildIntegrityContradictions = (pending, occurrenceById, rootNode) => pending.map((contradiction) => {
+    const occurrence = contradiction.occurrence;
     const parent = occurrence.parent_occurrence_id === null
         ? undefined
         : occurrenceById.get(occurrence.parent_occurrence_id);
@@ -161,13 +168,13 @@ const buildIntegrityContradictions = (pending, occurrenceByPath, occurrenceById,
     return {
         contradiction_id: artifactContradictionId({
             rootArtifactId: rootNode.artifact_id,
-            logicalPath: contradiction.logicalPath,
+            logicalPath: occurrence.logical_path,
             declaredSha256: contradiction.declaredSha256,
             observedSha256: contradiction.observedSha256,
         }),
         occurrence_id: occurrence.occurrence_id,
         parent_artifact_id: parentArtifactId,
-        logical_path: contradiction.logicalPath,
+        logical_path: occurrence.logical_path,
         declared_sha256: contradiction.declaredSha256,
         observed_sha256: contradiction.observedSha256,
         entry_kind: contradiction.entryKind,
@@ -202,8 +209,8 @@ const buildManifest = ({ rootNode, rootFormat, graphSha256, orderedNodes, ordere
     occurrence_count: orderedOccurrences.length,
     edge_count: orderedEdges.length,
 });
-const buildLimitations = (rootFormat, reader, integrityContradictions, caseCollisionLimitation) => [
-    ...inventoryLimitations(rootFormat, reader),
+const buildLimitations = (scopeLimitations, integrityContradictions, caseCollisionLimitation) => [
+    ...scopeLimitations,
     ...(caseCollisionLimitation === undefined ? [] : [caseCollisionLimitation]),
     ...(integrityContradictions.length === 0
         ? []

package/dist/artifacts/inventory/scanReader.js

@@ -2,7 +2,8 @@ import { isAbsolute } from "node:path";
 import { annotateEnglishUnicodeCaseCollisions, ArtifactPathRegistry, normalizeArtifactPath, } from "../ArtifactPaths.js";
 import { ArtifactReaderFailure, } from "../ArtifactReader.js";
 import { AsarArtifactReader } from "../AsarArtifactReader.js";
-import { classifyArtifactContent, classifyArtifactBytes, createArtifactNode, createOccurrence, noteUnreadContainerSuffix, resolveOccurrenceParents, } from "./ArtifactGraphConstruction.js";
+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
+import { classifyArtifactContent, classifyArtifactBytes, createArtifactNode, createOccurrence, noteUnreadContainerSuffix, indexOccurrencesByPath, resolveOccurrenceParents, } from "./ArtifactGraphConstruction.js";
 import { STRICT_INTEGRITY_POLICY, } from "./types.js";
 import { hashReadable } from "../ArtifactHash.js";
 const UNAVAILABLE_UNPACKED_LIMITATION = "ASAR unpacked companion bytes were unavailable; no content hash or child artifact was produced.";
@@ -15,6 +16,8 @@ export const scanReader = async (reader, ownedReaders, signal, integrity = STRIC
             occurrences,
             pendingContradictions,
             caseCollisionLimitation: undefined,
+            unknownParentOccurrences: new Set(),
+            traversal: { status: "complete", limitations: [] },
         };
     const context = {
         reader,
@@ -23,28 +26,50 @@ export const scanReader = async (reader, ownedReaders, signal, integrity = STRIC
         nodes,
         occurrences,
         pendingContradictions,
-        occurrenceByPath: new Map(),
+        occurrenceCountByPath: new Map(),
         registry: new ArtifactPathRegistry(),
         expandedContainerIds: new Set(),
         ownedReaders,
+        omissions: [],
     };
     await visitArtifactEntries(context, reader, "");
     // Archive directories may appear after their children. Resolve containment
     // against the complete index before directory identities are materialized.
-    resolveOccurrenceParents(occurrences, context.occurrenceByPath, context.expandedContainerIds);
+    const byPath = indexOccurrencesByPath(occurrences);
+    const parentResolution = resolveOccurrenceParents(occurrences, byPath, context.expandedContainerIds);
+    const structuralLimitations = [...parentResolution.limitations];
     return {
         nodes,
         occurrences,
         pendingContradictions,
         caseCollisionLimitation: annotateEnglishUnicodeCaseCollisions(occurrences),
+        unknownParentOccurrences: parentResolution.unknownParentOccurrences,
+        traversal: {
+            status: context.omissions.length === 0 && structuralLimitations.length === 0
+                ? "complete"
+                : "unknown",
+            limitations: [
+                ...new Set([
+                    ...context.omissions.map(({ path, kind }) => `Artifact traversal omitted ${kind} at ${JSON.stringify(path)}.`),
+                    ...structuralLimitations,
+                ]),
+            ].sort(compareUnicodeCodePoints),
+        },
     };
 };
+const inventoryEntries = (context, reader, prefix) => reader
+    .entries(context.signal, {
+    onOmission: (omission) => context.omissions.push({
+        ...omission,
+        path: normalizeArtifactPath(prefix.length === 0 ? omission.path : `${prefix}/${omission.path}`),
+    }),
+})[Symbol.asyncIterator]();
 const visitArtifactEntries = async (context, currentReader, prefix) => {
     const stack = [
         {
             reader: currentReader,
             prefix,
-            iterator: currentReader.entries(context.signal)[Symbol.asyncIterator](),
+            iterator: inventoryEntries(context, currentReader, prefix),
         },
     ];
     let failure;
@@ -64,10 +89,12 @@ const visitArtifactEntries = async (context, currentReader, prefix) => {
                 : `${frame.prefix}/${entry.path}`);
             const expandableAsar = isExpandableAsar(entry, logicalPath);
             context.registry.add(logicalPath, expandableAsar ? "directory" : entry.kind);
-            const occurrence = createOccurrence(entry, logicalPath, null);
+            const duplicateOrdinal = context.occurrenceCountByPath.get(logicalPath) ?? 0;
+            context.occurrenceCountByPath.set(logicalPath, duplicateOrdinal + 1);
+            const occurrence = createOccurrence(entry, logicalPath, null, duplicateOrdinal);
             let digested;
             try {
-                digested = await digestArtifactEntry(context, frame.reader, entry, logicalPath);
+                digested = await digestArtifactEntry(context, frame.reader, entry, logicalPath, occurrence);
             }
             catch (cause) {
                 if (!isUnavailableUnpackedEntry(cause, entry))
@@ -89,7 +116,6 @@ const visitArtifactEntries = async (context, currentReader, prefix) => {
                     occurrence.limitations.push("Declared integrity metadata contradicts observed bytes.");
             }
             context.occurrences.push(occurrence);
-            context.occurrenceByPath.set(logicalPath, occurrence);
             if (expandableAsar &&
                 digested !== undefined &&
                 digested.classification.format === "asar" &&
@@ -102,7 +128,7 @@ const visitArtifactEntries = async (context, currentReader, prefix) => {
                 stack.push({
                     reader: nested,
                     prefix: logicalPath,
-                    iterator: nested.entries(context.signal)[Symbol.asyncIterator](),
+                    iterator: inventoryEntries(context, nested, logicalPath),
                 });
             }
         }
@@ -126,7 +152,7 @@ const visitArtifactEntries = async (context, currentReader, prefix) => {
     if (failure !== undefined)
         throw failure.cause;
 };
-const digestArtifactEntry = async (context, currentReader, entry, logicalPath) => {
+const digestArtifactEntry = async (context, currentReader, entry, logicalPath, occurrence) => {
     if ((entry.kind !== "file" && entry.kind !== "slice") || entry.encrypted)
         return undefined;
     const digest = await hashReadable(await currentReader.open(entry, context.signal), context.signal);
@@ -140,7 +166,7 @@ const digestArtifactEntry = async (context, currentReader, entry, logicalPath) =
                 unpacked: entry.unpacked,
             });
         context.pendingContradictions.push({
-            logicalPath,
+            occurrence,
             declaredSha256: entry.declaredSha256,
             observedSha256: digest.sha256,
             entryKind: entry.kind,

package/dist/artifacts/javascript/JavaScriptArtifactFiles.js

@@ -6,16 +6,37 @@ import { ArtifactPathRegistry, normalizeArtifactPath, } from "../ArtifactPaths.j
 import { ArtifactReaderFailure, } from "../ArtifactReader.js";
 import { streamChunkToBuffer } from "../StreamBytes.js";
 import { hashReadable } from "../ArtifactHash.js";
-/** Read all relevant textual entries through an already-inventoried reader. */
-export const readJavaScriptArtifactFiles = async (reader, snapshot, resources, signal) => {
+import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
+import { isJavaScriptSourcePath } from "../../domain/javascript/javascriptArtifactFiles.js";
+/** Verify inventoried entries; acquire text only inside the caller's scope. */
+export const readJavaScriptArtifactFiles = async (reader, snapshot, resources, signal, sourcePaths) => {
+    const inventory = expectedInventory(snapshot);
+    const expected = inventory.files;
+    const selectedPaths = sourcePaths === undefined
+        ? undefined
+        : new Map([...new Set(sourcePaths)].map((path, index) => [path, index]));
+    const issues = (sourcePaths ?? []).flatMap((path, index) => expected.has(path) || inventory.unavailableFiles.has(path)
+        ? []
+        : [
+            {
+                path: ["source_paths", index],
+                reason: "invalid_value",
+                message: "Select an exact relevant file path from the artifact inventory; no globs or path aliases.",
+            },
+        ]);
+    if (issues.length > 0)
+        throw new AnalysisInputError("analyze_javascript_application", undefined, issues);
+    const unavailablePath = sourcePaths?.find((path) => inventory.unavailableFiles.has(path));
+    if (unavailablePath !== undefined)
+        throw new ArtifactReaderFailure("unavailable", `Selected inventoried source bytes are unavailable: ${unavailablePath}`, {
+            partialObservation: { kind: "artifact-inventory", inventory: snapshot },
+        });
     if (reader instanceof AsarArtifactReader) {
         const root = snapshot.nodes.find(({ artifact_id }) => artifact_id === snapshot.manifest.root_artifact_id);
         if (root === undefined)
             throw new ArtifactReaderFailure("integrity", "Root artifact node is missing");
         await verifyEntryBytes(await reader.openContainer(signal), { path: ".", sha256: root.sha256, bytes: root.size }, signal);
     }
-    const inventory = expectedInventory(snapshot);
-    const expected = inventory.files;
     const context = {
         resources,
         expected,
@@ -24,17 +45,41 @@ export const readJavaScriptArtifactFiles = async (reader, snapshot, resources, s
         files: [],
         containers: [],
         signal,
+        selectedPaths,
         textBytes: 0,
         invalidUtf8: 0,
     };
     await visitReader(reader, "", snapshot.manifest.root_sha256, context);
-    const files = context.files.sort((left, right) => compareUnicodeCodePoints(left.path, right.path));
+    const files = context.files.sort((left, right) => {
+        const leftPriority = selectedPaths?.get(left.path) ?? Infinity;
+        const rightPriority = selectedPaths?.get(right.path) ?? Infinity;
+        if (leftPriority !== rightPriority)
+            return leftPriority - rightPriority;
+        return compareUnicodeCodePoints(left.path, right.path);
+    });
+    const unanalyzedFiles = createUnanalyzedArtifactLookup(snapshot, context.containers);
+    const unavailableRelevantFiles = [...inventory.unavailableFiles]
+        .sort(compareUnicodeCodePoints)
+        .flatMap((path) => {
+        const unavailable = unanalyzedFiles.get(path);
+        return unavailable === undefined ? [] : [unavailable];
+    });
     assertExpectedFilesWereVisited(expected, files);
     return {
         files,
+        unanalyzed_files: unanalyzedFiles,
+        unavailable_relevant_files: unavailableRelevantFiles,
         containers: context.containers.sort((left, right) => compareUnicodeCodePoints(left.path, right.path)),
         text_bytes_read: context.textBytes,
         invalid_utf8_files: context.invalidUtf8,
+        ...(sourcePaths === undefined
+            ? {}
+            : {
+                source_selection: {
+                    requested_paths: [...sourcePaths],
+                    unselected_files: files.filter(({ text }) => !text.included && text.reason === "outside-analysis-scope").length,
+                },
+            }),
     };
 };
 const visitReader = async (reader, prefix, containerSha256, context) => {
@@ -76,6 +121,10 @@ const visitReader = async (reader, prefix, containerSha256, context) => {
                     throw new ArtifactReaderFailure("unavailable", `Nested ASAR bytes were unavailable during inventory: ${path}`);
                 if (container.hash_status !== "verified")
                     throw new ArtifactReaderFailure("integrity", `Nested ASAR was not integrity-verified: ${path}`);
+                // Inventory expands an ASAR-named file only when its bytes are an
+                // ASAR. One it recorded as ordinary bytes has no members to read.
+                if (container.format !== "asar")
+                    continue;
                 const inventory = container.inventory;
                 if (inventory === null)
                     throw new ArtifactReaderFailure("integrity", `Verified nested ASAR has no inventory node: ${path}`);
@@ -144,6 +193,13 @@ const visitReader = async (reader, prefix, containerSha256, context) => {
         throw failure.cause;
 };
 const readText = async (context, input) => {
+    if (context.selectedPaths !== undefined &&
+        !context.selectedPaths.has(input.expected.path)) {
+        // Keep the inventory/acquisition identity check without allocating or
+        // decoding an unrelated source's text.
+        await verifyEntryBytes(await input.reader.open(input.entry, context.signal), input.expected, context.signal);
+        return { included: false, reason: "outside-analysis-scope" };
+    }
     if (input.expected.kind === "native-addon") {
         await verifyEntryBytes(await input.reader.open(input.entry, context.signal), input.expected, context.signal);
         return { included: false, reason: "not-applicable" };
@@ -185,15 +241,20 @@ const expectedInventory = (snapshot) => {
     const nodes = new Map(snapshot.nodes.map((node) => [node.artifact_id, node]));
     const files = new Map();
     const containers = new Map();
+    const unavailableFiles = new Set();
     for (const occurrence of snapshot.occurrences) {
         if (occurrence.logical_path === ".")
             continue;
         const isNestedAsar = occurrence.entry_kind === "file" &&
             occurrence.logical_path.toLowerCase().endsWith(".asar");
         if (occurrence.artifact_id === null) {
+            if (occurrence.entry_kind === "file" &&
+                relevantKind(occurrence.logical_path) !== undefined)
+                unavailableFiles.add(occurrence.logical_path);
             if (isNestedAsar)
                 containers.set(occurrence.logical_path, {
                     hash_status: occurrence.hash_status,
+                    format: occurrence.artifact_format,
                     inventory: null,
                 });
             continue;
@@ -209,6 +270,7 @@ const expectedInventory = (snapshot) => {
         if (isNestedAsar)
             containers.set(occurrence.logical_path, {
                 hash_status: occurrence.hash_status,
+                format: occurrence.artifact_format,
                 inventory: {
                     path: occurrence.logical_path,
                     sha256: node.sha256,
@@ -227,7 +289,101 @@ const expectedInventory = (snapshot) => {
             kind,
         });
     }
-    return { files, containers };
+    return { files, containers, unavailableFiles };
+};
+/** Canonical snapshot arrays are already ordered by code-point identity. */
+const lowerBound = (rows, key, identity) => {
+    let low = 0;
+    let high = rows.length;
+    while (low < high) {
+        const middle = low + Math.floor((high - low) / 2);
+        const row = rows[middle];
+        if (row !== undefined && compareUnicodeCodePoints(identity(row), key) < 0)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    return low;
+};
+const createUnanalyzedArtifactLookup = (snapshot, containers) => {
+    const requested = new Map();
+    const directories = new Map();
+    const containerIds = new Map(containers.map((container) => [container.path, container.sha256]));
+    const containerFor = (path) => {
+        let prefix = path;
+        for (;;) {
+            const slash = prefix.lastIndexOf("/");
+            if (slash < 0)
+                return snapshot.manifest.root_sha256;
+            prefix = prefix.slice(0, slash);
+            const sha256 = containerIds.get(prefix);
+            if (sha256 !== undefined)
+                return sha256;
+        }
+    };
+    const isOpaque = (occurrence) => occurrence.entry_kind === "file" &&
+        relevantKind(occurrence.logical_path) === undefined;
+    const isUnavailableRelevant = (occurrence) => occurrence.entry_kind === "file" &&
+        occurrence.artifact_id === null &&
+        relevantKind(occurrence.logical_path) !== undefined;
+    return {
+        get(path) {
+            if (requested.has(path))
+                return requested.get(path);
+            const occurrence = snapshot.occurrences[lowerBound(snapshot.occurrences, path, (entry) => entry.logical_path)];
+            const kind = relevantKind(path);
+            const id = occurrence?.logical_path === path &&
+                (isOpaque(occurrence) || isUnavailableRelevant(occurrence))
+                ? occurrence.artifact_id
+                : undefined;
+            const candidate = id == null
+                ? undefined
+                : snapshot.nodes[lowerBound(snapshot.nodes, id, (entry) => entry.artifact_id)];
+            const node = candidate?.artifact_id === id ? candidate : undefined;
+            const file = occurrence?.logical_path !== path ||
+                (!isOpaque(occurrence) && !isUnavailableRelevant(occurrence))
+                ? undefined
+                : {
+                    path,
+                    container_sha256: containerFor(path),
+                    sha256: node?.sha256 ?? null,
+                    bytes: node?.size ?? occurrence.declared_size,
+                    inventory_artifact_id: occurrence.artifact_id,
+                    inventory_occurrence_id: occurrence.occurrence_id,
+                    ...(kind === undefined ? {} : { kind }),
+                    artifact_kind: occurrence.artifact_kind,
+                    hash_status: occurrence.hash_status,
+                    limitations: occurrence.limitations,
+                };
+            requested.set(path, file);
+            return file;
+        },
+        hasDirectory(path, containerSha256) {
+            let results = directories.get(path);
+            const previous = results?.get(containerSha256);
+            if (previous !== undefined)
+                return previous;
+            const prefix = `${path}/`;
+            let present = false;
+            for (let index = lowerBound(snapshot.occurrences, prefix, (entry) => entry.logical_path); index < snapshot.occurrences.length; index += 1) {
+                const entry = snapshot.occurrences[index];
+                if (entry === undefined || !entry.logical_path.startsWith(prefix))
+                    break;
+                if ((isOpaque(entry) || isUnavailableRelevant(entry)) &&
+                    (containerSha256 === undefined ||
+                        containerFor(entry.logical_path) === containerSha256)) {
+                    present = true;
+                    break;
+                }
+            }
+            if (results === undefined) {
+                results = new Map();
+                directories.set(path, results);
+            }
+            results.set(containerSha256, present);
+            return present;
+        },
+    };
 };
 const readAll = async (stream, signal) => {
     const chunks = [];
@@ -252,7 +408,7 @@ const relevantKind = (path) => {
         return "package-json";
     if (lower.endsWith(".json"))
         return "json";
-    if (/\.(?:cjs|cts|mjs|mts|js|jsx|ts|tsx)$/u.test(lower))
+    if (isJavaScriptSourcePath(path))
         return "javascript";
     if (/\.html?$/u.test(lower))
         return "html";