rea-agents 6.3.0 → 6.4.0

package/dist/artifacts/extraction/ArtifactExtraction.js

@@ -7,25 +7,33 @@ 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 materializeArtifactInventory(input, sourcePath, snapshot, signal);
+    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 !== ".");
@@ -42,26 +50,36 @@ export const materializeArtifactInventory = async (input, sourcePath, snapshot,
         return true;
     });
     const selectedIds = new Set(activeOccurrences.map(({ occurrence_id: id }) => id));
-    const occurrences = new Map();
-    const neededNodes = new Set();
-    collectOccurrences(snapshot.occurrences, selectedIds, occurrences, neededNodes);
+    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 = 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 };
@@ -77,74 +95,36 @@ export const materializeArtifactInventory = async (input, sourcePath, snapshot,
 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 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,
-            });
-            byPath.delete(path);
+        try {
+            output = await SafeOutputTree.create(input.outputRoot);
+        }
+        catch (cause) {
+            if (cause instanceof SafeOutputTreeCreationFailure)
+                output = cause.tree;
+            throw cause;
         }
-        if (byPath.size > 0)
-            throw new ArtifactReaderFailure("integrity", `Inventoried regular artifact entries were not materialized: ${[...byPath.keys()].sort(compareUnicodeCodePoints).join(", ")}`);
-        readerCloseAttempted = true;
-        await reader.close();
-        readerClosed = true;
+        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));
-        const result = createExtractionResult(input, inventory, selected, extracted);
+        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, {
@@ -152,11 +132,63 @@ 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,
@@ -177,25 +209,17 @@ const createExtractionResult = (input, inventory, selected, 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

@@ -11,30 +11,54 @@ export const indexOccurrencesByPath = (occurrences) => {
             byPath.set(occurrence.logical_path, occurrence);
     return byPath;
 };
-export const createOccurrence = (entry, path, parent) => ({
-    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: 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 materializeDirectoryNodes = (occurrences, nodes) => {
     const directories = occurrences
@@ -153,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,
@@ -169,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))
@@ -207,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);
 };

package/dist/artifacts/inventory/classify.js

@@ -1,53 +1,96 @@
-import { NonRegularFileReadError, openRegularFile, sameRegularFileState, } from "../../filesystem/RegularFile.js";
+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 { ArtifactReaderFailure } from "../ArtifactReader.js";
-import { hashStableRootArtifactHandle } from "./hashStableRootArtifact.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 {} 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, signal) => {
+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 };
+    });
+};
+/** Classify a root and retain its admitted ZIP descriptor for child inventory. */
+export const classifyAndHashRootForInventory = async (path, directory, expectedMetadata, options) => {
     if (directory)
-        return { format: "directory", digest: null };
-    const handle = await openRootFile(path, signal);
+        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 initial = await handle.stat();
         if (!sameRegularFileState(expectedMetadata, initial))
             throw new ArtifactReaderFailure("integrity", `Root artifact changed before inventory: ${path}`);
-        const format = classifyContainerExtension(path) ??
-            (await classifyOpenedRoot(path, handle));
-        const digest = await hashStableRootArtifactHandle(path, handle, initial, signal);
-        return { format, digest };
-    }
-    finally {
-        await handle.close();
-    }
-};
-const openRootFile = async (path, signal) => {
-    try {
-        return await openRegularFile(path, { symlinks: "reject", signal });
+        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) {
-        if (cause instanceof NonRegularFileReadError)
-            throw new ArtifactReaderFailure("format", `Artifact root is not a regular file: ${path}`, { cause });
-        throw cause;
+        outcome = { kind: "failed", cause };
+    }
+    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 classifyOpenedRoot = async (path, handle) => {
+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 "zip";
+        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";
+};