rea-agents 6.2.0 → 6.4.0

package/dist/artifacts/inventory/classify.js

@@ -1,34 +1,96 @@
-import { open } from "node:fs/promises";
+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";
-const classifyContainerExtension = (path) => {
-    const lower = path.toLowerCase();
-    const zipPackage = zipPackageFormatForPath(lower);
-    if (zipPackage !== undefined)
-        return zipPackage;
-    for (const format of ["asar", "dmg", "pkg"])
-        if (lower.endsWith(`.${format}`))
-            return format;
-    return undefined;
+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) => {
+    return options.resourceScope.run(async () => {
+        const result = await classifyAndHashRootForInventory(path, directory, expectedMetadata, options);
+        const rootSource = result.rootSource;
+        if (rootSource !== undefined) {
+            const owner = {
+                kind: "file-handle",
+                handle: rootSource.owner,
+                resource: `root artifact descriptor for ${path}`,
+            };
+            const cleanupAttempt = await options.resourceScope.release(owner);
+            if (cleanupAttempt.kind === "failed")
+                throw ArtifactReaderFailure.withCleanup(cleanupAttempt.cause, ArtifactReaderFailure.cleanupObservation(cleanupAttempt.cause, owner.resource));
+        }
+        return { format: result.format, digest: result.digest };
+    });
 };
-export const classifyRoot = async (path, directory) => {
+/** Classify a root and retain its admitted ZIP descriptor for child inventory. */
+export const classifyAndHashRootForInventory = async (path, directory, expectedMetadata, options) => {
     if (directory)
-        return "directory";
-    const extensionFormat = classifyContainerExtension(path);
-    if (extensionFormat !== undefined)
-        return extensionFormat;
-    const handle = await open(path, "r");
+        return { format: "directory", digest: null, rootSource: undefined };
+    const ownedHandle = await openRootArtifact(path, options.resourceScope, options.signal);
+    const handle = ownedHandle.handle;
+    const owner = {
+        kind: "file-handle",
+        handle: ownedHandle,
+        resource: `root artifact descriptor for ${path}`,
+    };
+    let outcome;
     try {
-        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);
-        if (hasZipSignature(prefix))
-            return "zip";
-        return classifyArtifactContent(path, prefix, (await handle.stat()).size)
-            .format;
+        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 digest = await hashStableRootArtifactHandle(path, handle, initial, options.signal);
+        const retainSource = isZipFormat(format) || format === "mach-o-universal";
+        outcome = {
+            kind: "completed",
+            value: {
+                format,
+                digest,
+                rootSource: retainSource
+                    ? { handle, initial, owner: ownedHandle }
+                    : undefined,
+            },
+        };
+    }
+    catch (cause) {
+        outcome = { kind: "failed", cause };
     }
-    finally {
-        await handle.close();
+    if (outcome.kind === "failed" || outcome.value.rootSource === undefined) {
+        const cleanupAttempt = await options.resourceScope.release(owner);
+        if (cleanupAttempt.kind === "failed")
+            throw ArtifactReaderFailure.withCleanup(outcome.kind === "failed" ? outcome.cause : cleanupAttempt.cause, ArtifactReaderFailure.cleanupObservation(cleanupAttempt.cause, owner.resource));
     }
+    if (outcome.kind === "failed")
+        throw outcome.cause;
+    return outcome.value;
+};
+const isZipFormat = (format) => format === "zip" ||
+    format === "ipa" ||
+    format === "apk" ||
+    format === "msix" ||
+    format === "appx";
+const classifyRootFormat = async (path, handle) => {
+    const magic = Buffer.alloc(ARTIFACT_CLASSIFICATION_PREFIX_BYTES);
+    const observed = await handle.read(magic, 0, magic.length, 0);
+    const prefix = magic.subarray(0, observed.bytesRead);
+    const lower = path.toLowerCase();
+    if (hasZipSignature(prefix))
+        return zipPackageFormatForPath(lower) ?? "zip";
+    if (lower.endsWith(".pkg") &&
+        prefix.subarray(0, 4).toString("ascii") === "xar!")
+        return "pkg";
+    if (lower.endsWith(".dmg") && (await hasKolyTrailer(handle)))
+        return "dmg";
+    // ASAR is chosen from its header pickle; any other suffix is a role hint.
+    return classifyArtifactContent(path, prefix, (await handle.stat()).size)
+        .format;
+};
+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";
 };

package/dist/artifacts/inventory/hashStableRootArtifact.js

@@ -0,0 +1,70 @@
+import { lstat } from "node:fs/promises";
+import { readFileHandleChunks } from "../../filesystem/readFileHandleChunks.js";
+import { OwnedFileHandle } from "../../filesystem/OwnedFileHandle.js";
+import { ArtifactReaderFailure } from "../ArtifactReader.js";
+import { NonRegularFileReadError, RegularFileAdmissionFailure, openRegularFile, sameRegularFileState, } from "../../filesystem/RegularFile.js";
+import { abortIfNeeded, hashReadable, } from "../ArtifactHash.js";
+/** Admit a root descriptor without losing ownership when validation cleanup fails. */
+export const openRootArtifact = async (path, resourceScope, signal) => {
+    try {
+        return new OwnedFileHandle(await openRegularFile(path, { symlinks: "reject", signal }));
+    }
+    catch (cause) {
+        const primary = cause instanceof RegularFileAdmissionFailure ? cause.cause : cause;
+        const failure = primary instanceof NonRegularFileReadError
+            ? new ArtifactReaderFailure("format", `Artifact root is not a regular file: ${path}`, { cause: primary })
+            : primary;
+        if (cause instanceof RegularFileAdmissionFailure) {
+            const resource = `root artifact descriptor for ${path}`;
+            const cleanup = await resourceScope.release({
+                kind: "file-handle",
+                resource,
+                handle: cause.owner,
+            });
+            if (cleanup.kind === "failed")
+                throw ArtifactReaderFailure.withCleanup(failure, ArtifactReaderFailure.cleanupObservation(cleanup.cause, resource));
+        }
+        throw failure;
+    }
+};
+/** Hash one stable regular root file from the same descriptor that was checked. */
+export const hashStableRootArtifact = async (path, resourceScope, signal) => {
+    const owner = await openRootArtifact(path, resourceScope, signal);
+    const handle = owner.handle;
+    let outcome;
+    try {
+        const initial = await handle.stat();
+        outcome = {
+            kind: "completed",
+            value: await hashStableRootArtifactHandle(path, handle, initial, signal),
+        };
+    }
+    catch (cause) {
+        outcome = { kind: "failed", cause };
+    }
+    const resource = `root artifact descriptor for ${path}`;
+    const cleanup = await resourceScope.release({
+        kind: "file-handle",
+        resource,
+        handle: owner,
+    });
+    if (cleanup.kind === "failed")
+        throw ArtifactReaderFailure.withCleanup(outcome.kind === "failed" ? outcome.cause : cleanup.cause, ArtifactReaderFailure.cleanupObservation(cleanup.cause, resource));
+    if (outcome.kind === "failed")
+        throw outcome.cause;
+    return outcome.value;
+};
+/** Hash and revalidate the same open descriptor used for root classification. */
+export const hashStableRootArtifactHandle = async (path, handle, initial, signal) => {
+    const digest = await hashReadable(
+    // Read at most the admitted extent plus one byte to detect growth without
+    // following an actively appended file indefinitely.
+    readFileHandleChunks(handle, { start: 0, end: initial.size }), signal);
+    abortIfNeeded(signal);
+    const [opened, currentPath] = await Promise.all([handle.stat(), lstat(path)]);
+    if (!sameRegularFileState(initial, opened) ||
+        !sameRegularFileState(initial, currentPath) ||
+        digest.bytes !== initial.size)
+        throw new ArtifactReaderFailure("integrity", `Root artifact changed during inventory: ${path}`);
+    return digest;
+};

package/dist/artifacts/inventory/reader.js

@@ -3,7 +3,8 @@ import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
 import { MachOSliceArtifactReader } from "../MachOSliceArtifactReader.js";
 import { NativeDmgArtifactReader } from "../NativeDmgArtifactReader.js";
 import { ZipArtifactReader } from "../ZipArtifactReader.js";
-export const createReader = async (path, format, environment, signal) => {
+import { ZIP_NON_ENTRY_TAIL_LIMITATION } from "../../domain/zipPackageFormat.js";
+export const createReader = (path, format, environment, rootSource) => {
     switch (format) {
         case "directory":
             return new DirectoryArtifactReader(path);
@@ -12,24 +13,31 @@ export const createReader = async (path, format, environment, signal) => {
         case "apk":
         case "msix":
         case "appx":
-            return new ZipArtifactReader(path, format);
+            return new ZipArtifactReader(path, format, undefined, rootSource);
         case "asar":
             return new AsarArtifactReader(path);
         case "mach-o-universal":
             return process.platform === "darwin"
-                ? new MachOSliceArtifactReader(path, environment)
+                ? new MachOSliceArtifactReader(path, environment, undefined, rootSource)
                 : undefined;
         case "dmg":
             if (process.platform !== "darwin")
                 return undefined;
-            return NativeDmgArtifactReader.create(path, environment, signal);
+            return new NativeDmgArtifactReader(path, environment);
         default:
             return undefined;
     }
 };
 export const inventoryLimitations = (format, reader) => {
     if (reader !== undefined)
-        return [];
+        return reader.format === "zip" ||
+            reader.format === "ipa" ||
+            reader.format === "apk" ||
+            reader.format === "msix" ||
+            reader.format === "appx"
+            ? [ZIP_NON_ENTRY_TAIL_LIMITATION]
+            : [];
+    // 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.`,

package/dist/artifacts/inventory/scanCanonical.js

@@ -1,26 +1,37 @@
-import { compareCodePoints } from "../../domain/canonicalOrdering.js";
-import { createReadStream } from "node:fs";
+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
+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 { artifactContradictionId, artifactGraphDigest, artifactManifestId, } from "../../domain/artifactIdentity.js";
-import { classifyRoot } from "./classify.js";
-import { hashReadable } from "../ArtifactHash.js";
+import { classifyAndHashRootForInventory } from "./classify.js";
+import {} from "../ArtifactHash.js";
+import { hashStableRootArtifact, hashStableRootArtifactHandle, } from "./hashStableRootArtifact.js";
 import { createReader, inventoryLimitations } from "./reader.js";
 import { scanReader, } from "./scanReader.js";
 import { STRICT_INTEGRITY_POLICY, } from "./types.js";
-export const scanCanonicalArtifactInventory = async (path, options = {}, readerFactory = createReader) => {
+export const scanCanonicalArtifactInventory = async (path, options, readerFactory = createReader) => options.resourceScope.run(() => scanCanonicalArtifactInventoryInScope(path, options, readerFactory));
+export const scanCanonicalArtifactInventoryInScope = async (path, options, readerFactory = createReader) => {
     const integrity = options.integrity ?? STRICT_INTEGRITY_POLICY;
     const metadata = await lstat(path);
-    const rootFormat = await classifyRoot(path, metadata.isDirectory());
-    const rootDigest = metadata.isDirectory()
-        ? null
-        : await hashReadable(createReadStream(path), options.signal);
-    const reader = await readerFactory(path, rootFormat, options.environment ?? {}, options.signal);
+    const { format: rootFormat, digest: rootDigest, rootSource, } = await classifyAndHashRootForInventory(path, metadata.isDirectory(), metadata, options);
+    let reader;
+    let readerCreationFailure;
+    try {
+        reader = readerFactory(path, rootFormat, options.environment ?? {}, rootSource);
+    }
+    catch (cause) {
+        readerCreationFailure = { cause };
+    }
+    const ownedReaders = reader === undefined ? [] : [reader];
     let outcome;
     try {
-        const { nodes, occurrences, pendingContradictions } = await scanReader(reader, options.signal, integrity);
+        if (readerCreationFailure !== undefined)
+            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);
         outcome = {
             kind: "completed",
             snapshot: await buildInventorySnapshot({
@@ -28,33 +39,62 @@ export const scanCanonicalArtifactInventory = async (path, options = {}, readerF
                 metadata,
                 rootFormat,
                 rootDigest,
+                rootSource,
+                resourceScope: options.resourceScope,
                 reader,
                 signal: options.signal,
                 nodes,
                 occurrences,
                 pendingContradictions,
+                caseCollisionLimitation,
             }),
         };
     }
     catch (cause) {
         outcome = { kind: "failed", cause };
     }
-    try {
-        await reader?.close();
-    }
-    catch (cleanupCause) {
-        const cleanup = ArtifactReaderFailure.cleanupObservation(cleanupCause, `artifact reader for ${path}`);
-        const primary = outcome.kind === "failed" ? outcome.cause : cleanupCause;
-        throw ArtifactReaderFailure.withCleanup(primary, cleanup, outcome.kind === "completed"
-            ? { kind: "artifact-inventory", inventory: outcome.snapshot }
-            : undefined);
-    }
+    const cleanupFailure = await cleanupInventoryOwners({
+        path,
+        options,
+        rootSource,
+        ownedReaders,
+        outcome,
+    });
+    if (cleanupFailure !== undefined)
+        throw cleanupFailure;
     if (outcome.kind === "failed")
         throw outcome.cause;
     return outcome.snapshot;
 };
+const cleanupInventoryOwners = async ({ path, options, rootSource, ownedReaders, outcome, }) => {
+    let cleanupFailure;
+    const owners = [...ownedReaders]
+        .reverse()
+        .map((reader) => ({
+        kind: "reader",
+        reader,
+        resource: `artifact reader for ${path}`,
+    }));
+    if (rootSource !== undefined)
+        owners.push({
+            kind: "file-handle",
+            handle: rootSource.owner,
+            resource: `root artifact descriptor for ${path}`,
+        });
+    for (const owner of owners) {
+        const attempt = await options.resourceScope.release(owner);
+        if (attempt.kind === "released")
+            continue;
+        const primary = cleanupFailure ??
+            (outcome.kind === "failed" ? outcome.cause : attempt.cause);
+        cleanupFailure = ArtifactReaderFailure.withCleanup(primary, ArtifactReaderFailure.cleanupObservation(attempt.cause, owner.resource), outcome.kind === "completed"
+            ? { kind: "artifact-inventory", inventory: outcome.snapshot }
+            : undefined);
+    }
+    return cleanupFailure;
+};
 const buildInventorySnapshot = async (input) => {
-    const { path, metadata, rootFormat, rootDigest, reader, signal } = input;
+    const { path, metadata, rootFormat, rootDigest, rootSource, reader, signal } = input;
     materializeDirectoryNodes(input.occurrences, input.nodes);
     const rootNode = createRootNode({
         digest: rootDigest,
@@ -85,7 +125,7 @@ const buildInventorySnapshot = async (input) => {
         ...edge,
         ordinal,
     }));
-    await verifyRootDigest(path, rootDigest, signal);
+    await verifyRootDigest(path, rootDigest, rootSource, input.resourceScope, signal);
     const graphSha256 = artifactGraphDigest({
         nodes: orderedNodes,
         occurrences: orderedOccurrences,
@@ -107,7 +147,7 @@ const buildInventorySnapshot = async (input) => {
         edges: orderedEdges,
         provenance: reader?.provenance() ?? [],
         integrity_contradictions: integrityContradictions,
-        limitations: buildLimitations(rootFormat, reader, integrityContradictions),
+        limitations: buildLimitations(rootFormat, reader, integrityContradictions, input.caseCollisionLimitation),
     };
 };
 const buildIntegrityContradictions = (pending, occurrenceByPath, occurrenceById, rootNode) => pending.map((contradiction) => {
@@ -139,17 +179,19 @@ const buildIntegrityContradictions = (pending, occurrenceByPath, occurrenceById,
         ],
     };
 });
-const verifyRootDigest = async (path, rootDigest, signal) => {
+const verifyRootDigest = async (path, rootDigest, rootSource, resourceScope, signal) => {
     if (rootDigest === null)
         return;
-    const verified = await hashReadable(createReadStream(path), signal);
+    const verified = rootSource === undefined
+        ? await hashStableRootArtifact(path, resourceScope, signal)
+        : await hashStableRootArtifactHandle(path, rootSource.handle, rootSource.initial, signal);
     if (verified.sha256 !== rootDigest.sha256 ||
         verified.bytes !== rootDigest.bytes)
         throw new ArtifactReaderFailure("integrity", "Root artifact changed during inventory");
 };
-const sortNodes = (nodes) => nodes.sort((left, right) => compareCodePoints(left.artifact_id, right.artifact_id));
-const sortOccurrences = (occurrences) => occurrences.sort((left, right) => compareCodePoints(left.logical_path, right.logical_path));
-const sortEdges = (edges) => edges.sort((left, right) => compareCodePoints(left.edge_id, right.edge_id));
+const sortNodes = (nodes) => nodes.sort((left, right) => compareUnicodeCodePoints(left.artifact_id, right.artifact_id));
+const sortOccurrences = (occurrences) => occurrences.sort((left, right) => compareUnicodeCodePoints(left.logical_path, right.logical_path));
+const sortEdges = (edges) => edges.sort((left, right) => compareUnicodeCodePoints(left.edge_id, right.edge_id));
 const buildManifest = ({ rootNode, rootFormat, graphSha256, orderedNodes, orderedOccurrences, orderedEdges, }) => artifactInventoryResultSchema.shape.manifest.parse({
     manifest_id: artifactManifestId(rootNode.artifact_id, graphSha256),
     root_artifact_id: rootNode.artifact_id,
@@ -160,8 +202,9 @@ const buildManifest = ({ rootNode, rootFormat, graphSha256, orderedNodes, ordere
     occurrence_count: orderedOccurrences.length,
     edge_count: orderedEdges.length,
 });
-const buildLimitations = (rootFormat, reader, integrityContradictions) => [
+const buildLimitations = (rootFormat, reader, integrityContradictions, caseCollisionLimitation) => [
     ...inventoryLimitations(rootFormat, reader),
+    ...(caseCollisionLimitation === undefined ? [] : [caseCollisionLimitation]),
     ...(integrityContradictions.length === 0
         ? []
         : [

package/dist/artifacts/inventory/scanReader.js

@@ -1,16 +1,21 @@
 import { isAbsolute } from "node:path";
-import { ArtifactPathRegistry, normalizeArtifactPath, } from "../ArtifactPaths.js";
+import { annotateEnglishUnicodeCaseCollisions, ArtifactPathRegistry, normalizeArtifactPath, } from "../ArtifactPaths.js";
 import { ArtifactReaderFailure, } from "../ArtifactReader.js";
 import { AsarArtifactReader } from "../AsarArtifactReader.js";
-import { classifyArtifactContent, classifyArtifactBytes, createArtifactNode, createOccurrence, nearestParent, } from "./ArtifactGraphConstruction.js";
+import { classifyArtifactContent, classifyArtifactBytes, createArtifactNode, createOccurrence, noteUnreadContainerSuffix, 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.";
 const emptyScan = () => ({ nodes: new Map(), occurrences: [], pendingContradictions: [] });
-export const scanReader = async (reader, signal, integrity = STRICT_INTEGRITY_POLICY) => {
+export const scanReader = async (reader, ownedReaders, signal, integrity = STRICT_INTEGRITY_POLICY) => {
     const { nodes, occurrences, pendingContradictions } = emptyScan();
     if (reader === undefined)
-        return { nodes, occurrences, pendingContradictions };
+        return {
+            nodes,
+            occurrences,
+            pendingContradictions,
+            caseCollisionLimitation: undefined,
+        };
     const context = {
         reader,
         signal,
@@ -21,14 +26,18 @@ export const scanReader = async (reader, signal, integrity = STRICT_INTEGRITY_PO
         occurrenceByPath: new Map(),
         registry: new ArtifactPathRegistry(),
         expandedContainerIds: new Set(),
+        ownedReaders,
     };
     await visitArtifactEntries(context, reader, "");
     // Archive directories may appear after their children. Resolve containment
     // against the complete index before directory identities are materialized.
-    for (const occurrence of occurrences)
-        occurrence.parent_occurrence_id =
-            nearestParent(occurrence.logical_path, context.occurrenceByPath, context.expandedContainerIds)?.occurrence_id ?? null;
-    return { nodes, occurrences, pendingContradictions };
+    resolveOccurrenceParents(occurrences, context.occurrenceByPath, context.expandedContainerIds);
+    return {
+        nodes,
+        occurrences,
+        pendingContradictions,
+        caseCollisionLimitation: annotateEnglishUnicodeCaseCollisions(occurrences),
+    };
 };
 const visitArtifactEntries = async (context, currentReader, prefix) => {
     const stack = [
@@ -36,9 +45,9 @@ const visitArtifactEntries = async (context, currentReader, prefix) => {
             reader: currentReader,
             prefix,
             iterator: currentReader.entries(context.signal)[Symbol.asyncIterator](),
-            owned: false,
         },
     ];
+    let failure;
     try {
         while (stack.length > 0) {
             const frame = stack.at(-1);
@@ -47,8 +56,6 @@ const visitArtifactEntries = async (context, currentReader, prefix) => {
             const next = await frame.iterator.next();
             if (next.done) {
                 stack.pop();
-                if (frame.owned)
-                    await frame.reader.close();
                 continue;
             }
             const entry = next.value;
@@ -68,7 +75,9 @@ const visitArtifactEntries = async (context, currentReader, prefix) => {
                 occurrence.hash_status = "unavailable";
                 occurrence.limitations.push(UNAVAILABLE_UNPACKED_LIMITATION);
             }
-            if (digested !== undefined) {
+            if (digested === undefined)
+                noteUnreadContainerSuffix(occurrence);
+            else {
                 context.nodes.set(digested.node.artifact_id, digested.node);
                 occurrence.artifact_id = digested.node.artifact_id;
                 occurrence.artifact_kind = digested.classification.kind;
@@ -81,27 +90,41 @@ const visitArtifactEntries = async (context, currentReader, prefix) => {
             }
             context.occurrences.push(occurrence);
             context.occurrenceByPath.set(logicalPath, occurrence);
-            if (expandableAsar && digested?.mismatched !== true) {
+            if (expandableAsar &&
+                digested !== undefined &&
+                digested.classification.format === "asar" &&
+                !digested.mismatched) {
                 const nested = new AsarArtifactReader(entry.adapterKey);
+                context.ownedReaders.push(nested);
+                await nested.prepareContainer(digested.node.sha256, context.signal);
                 // Only traversed containers can own members, not opaque ASAR-named files.
                 context.expandedContainerIds.add(occurrence.occurrence_id);
                 stack.push({
                     reader: nested,
                     prefix: logicalPath,
                     iterator: nested.entries(context.signal)[Symbol.asyncIterator](),
-                    owned: true,
                 });
             }
         }
     }
+    catch (cause) {
+        failure = { cause };
+    }
     finally {
-        await Promise.allSettled(stack
-            .filter(({ owned }) => owned)
-            .map(async ({ reader, iterator }) => {
-            await iterator.return?.();
-            await reader.close();
-        }));
+        // Readers remain owned by the inventory until its complete observation is built.
+        for (const { iterator, prefix, reader } of stack.reverse()) {
+            try {
+                await iterator.return?.();
+            }
+            catch (cause) {
+                failure = {
+                    cause: ArtifactReaderFailure.withCleanup(failure === undefined ? cause : failure.cause, ArtifactReaderFailure.cleanupObservation(cause, `artifact traversal for ${prefix || reader.format}`)),
+                };
+            }
+        }
     }
+    if (failure !== undefined)
+        throw failure.cause;
 };
 const digestArtifactEntry = async (context, currentReader, entry, logicalPath) => {
     if ((entry.kind !== "file" && entry.kind !== "slice") || entry.encrypted)