rea-agents 6.3.0 → 6.5.0

package/dist/artifacts/inventory/ArtifactGraphConstruction.js

@@ -1,44 +1,77 @@
 import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
+import { isJavaScriptSourcePath } from "../../domain/javascript/javascriptArtifactFiles.js";
 import { digestCanonicalValue } from "../../domain/canonicalDigest.js";
+import { hasBinaryPlistSignature, hasXmlPlistSignature, } from "../../domain/apple/appleArchiveFormat.js";
 import { artifactEdgeId, artifactIdForContent, occurrenceIdForLocation, } from "../../domain/artifactIdentity.js";
-import { hasZipSignature, zipPackageFormatForPath, } from "../../domain/zipPackageFormat.js";
-import { mzWindowsHeaderOffset, parseDosMzHeader } from "../../domain/dosMz.js";
-/** Index the first occurrence for each canonical logical path. */
+import { hasZipSignature, isZipPackageFormat, zipPackageFormatForPath, } from "../../domain/zipPackageFormat.js";
+import { observeMzWindowsHeader, parseDosMzHeader, } from "../../domain/dosMz.js";
+import { classifyFatContainerIdentity, readFatContainerHeader, } from "../../domain/apple/machoContainer.js";
+/** Index every occurrence by canonical logical path without choosing an owner. */
 export const indexOccurrencesByPath = (occurrences) => {
     const byPath = new Map();
-    for (const occurrence of occurrences)
-        if (!byPath.has(occurrence.logical_path))
-            byPath.set(occurrence.logical_path, occurrence);
+    for (const occurrence of occurrences) {
+        const matches = byPath.get(occurrence.logical_path);
+        if (matches === undefined)
+            byPath.set(occurrence.logical_path, [occurrence]);
+        else
+            matches.push(occurrence);
+    }
     return byPath;
 };
-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, duplicateOrdinal = 0) => {
+    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(duplicateOrdinal === 0
+            ? { path, kind: entry.kind }
+            : { path, kind: entry.kind, duplicate_ordinal: duplicateOrdinal }, "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
-        .filter(({ entry_kind: kind }) => kind === "directory")
+        .filter(({ entry_kind: kind, hash_status }) => kind === "directory" && hash_status !== "unavailable")
         .sort((left, right) => depth(right.logical_path) - depth(left.logical_path));
     const childrenByParent = new Map();
     for (const occurrence of occurrences) {
@@ -108,7 +141,8 @@ export const rootOccurrenceFor = (node, metadata) => ({
     logical_path: ".",
     entry_kind: metadata.format === "directory" ? "directory" : "file",
     artifact_kind: metadata.format === "directory" ||
-        ["zip", "ipa", "apk", "msix", "appx", "asar", "dmg", "pkg"].includes(metadata.format)
+        isZipPackageFormat(metadata.format) ||
+        ["asar", "dmg", "pkg"].includes(metadata.format)
         ? "container"
         : artifactRoleForFormat(metadata.path, metadata.format).kind,
     artifact_format: metadata.format,
@@ -122,12 +156,17 @@ export const rootOccurrenceFor = (node, metadata) => ({
 });
 export const rekeyOccurrences = (rootArtifactId, occurrences) => {
     const replacements = new Map();
-    for (const occurrence of occurrences)
+    const ordinalByPath = new Map();
+    for (const occurrence of occurrences) {
+        const ordinal = ordinalByPath.get(occurrence.logical_path) ?? 0;
+        ordinalByPath.set(occurrence.logical_path, ordinal + 1);
         replacements.set(occurrence.occurrence_id, occurrenceIdForLocation({
             rootArtifactId,
             logicalPath: occurrence.logical_path,
             entryKind: occurrence.entry_kind,
+            ...(ordinal === 0 ? {} : { duplicateOrdinal: ordinal }),
         }));
+    }
     for (const occurrence of occurrences) {
         occurrence.occurrence_id =
             replacements.get(occurrence.occurrence_id) ?? occurrence.occurrence_id;
@@ -141,57 +180,140 @@ export const createArtifactEdges = (rootArtifactId, occurrences, producer) => {
     const byId = new Map(occurrences.map((item) => [item.occurrence_id, item]));
     const byPath = indexOccurrencesByPath(occurrences);
     const edges = [];
+    const limitations = [];
     for (const occurrence of occurrences) {
+        const isSourceMap = occurrence.logical_path.toLowerCase().endsWith(".map");
+        const sourcePath = isSourceMap
+            ? occurrence.logical_path.slice(0, -".map".length)
+            : undefined;
+        const sourceCandidates = sourcePath === undefined ? [] : (byPath.get(sourcePath) ?? []);
+        const mappedSource = sourceCandidates.length === 1 && sourceCandidates[0]?.artifact_id !== null
+            ? sourceCandidates[0]
+            : undefined;
+        if (sourcePath !== undefined) {
+            const unknownMapping = sourceCandidates.length > 1
+                ? {
+                    occurrence: `Source-map target is unknown because multiple occurrences share ${JSON.stringify(sourcePath)}.`,
+                    coverage: `Source-map relationships are unknown because multiple occurrences share ${JSON.stringify(sourcePath)}.`,
+                }
+                : sourceCandidates.length === 1 && mappedSource === undefined
+                    ? {
+                        occurrence: `Source-map target identity is unknown because the matching occurrence at ${JSON.stringify(sourcePath)} has no content identity.`,
+                        coverage: `Source-map relationships are unknown because the matching occurrence at ${JSON.stringify(sourcePath)} has no content identity.`,
+                    }
+                    : undefined;
+            if (unknownMapping !== undefined) {
+                occurrence.limitations.push(unknownMapping.occurrence);
+                limitations.push(unknownMapping.coverage);
+            }
+        }
         if (occurrence.parent_occurrence_id === null ||
             occurrence.artifact_id === null)
             continue;
-        const mappedSource = occurrence.logical_path.toLowerCase().endsWith(".map")
-            ? byPath.get(occurrence.logical_path.slice(0, -".map".length))
-            : undefined;
         const parentArtifactId = mappedSource?.artifact_id ??
             byId.get(occurrence.parent_occurrence_id)?.artifact_id ??
             rootArtifactId;
         const semantic = {
             parent_artifact_id: parentArtifactId,
-            child_artifact_id: occurrence.artifact_id,
             relation: occurrence.entry_kind === "slice"
                 ? "slice-of"
-                : relationFor(occurrence.logical_path),
+                : isSourceMap && mappedSource === undefined
+                    ? "contains"
+                    : 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,
         });
     }
-    return edges;
+    return { edges, limitations };
 };
-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 matches of byPath.values()) {
+        const parents = matches.filter((occurrence) => occurrence.entry_kind === "directory" ||
+            expandedContainerIds.has(occurrence.occurrence_id));
+        if (parents.length === 0)
+            continue;
+        if (parents.length > 1)
+            for (const parent of parents)
+                if (parent.entry_kind === "directory") {
+                    parent.artifact_id = null;
+                    parent.hash_status = "unavailable";
+                    parent.limitations.push("This directory occurrence cannot be materialized because multiple directory entries share its logical path.");
+                }
+        const path = matches[0]?.logical_path;
+        if (path === undefined)
+            continue;
+        let branch = root;
+        for (const segment of path.split("/")) {
+            let child = branch.children.get(segment);
+            if (child === undefined) {
+                child = { children: new Map() };
+                branch.children.set(segment, child);
+            }
+            branch = child;
+        }
+        branch.occurrences = parents;
+    }
+    const limitations = new Set();
+    const unknownParentOccurrences = new Set();
+    for (const occurrence of occurrences) {
+        const path = occurrence.logical_path;
+        let branch = root;
+        let parent;
+        let ambiguousParentPath;
+        let prefix = "";
+        // Walk parent segments only. Stop scanning the path once no observed
+        // directory or expanded container can be an ancestor.
+        for (let start = 0;;) {
+            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;
+            prefix = prefix.length === 0 ? segment : `${prefix}/${segment}`;
+            const candidates = branch.occurrences ?? [];
+            if (candidates.length === 1) {
+                parent = candidates[0];
+                ambiguousParentPath = undefined;
+            }
+            else if (candidates.length > 1) {
+                parent = undefined;
+                ambiguousParentPath = prefix;
+            }
+            start = slash + 1;
+        }
+        occurrence.parent_occurrence_id = parent?.occurrence_id ?? null;
+        if (ambiguousParentPath !== undefined) {
+            const limitation = `The parent occurrence for ${JSON.stringify(path)} is unknown because multiple observed directory or container occurrences share ${JSON.stringify(ambiguousParentPath)}.`;
+            occurrence.limitations.push(limitation);
+            limitations.add(limitation);
+            unknownParentOccurrences.add(occurrence);
+        }
     }
-    return undefined;
+    return {
+        limitations: [...limitations].sort(compareUnicodeCodePoints),
+        unknownParentOccurrences,
+    };
 };
+/**
+ * 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))
+    if (isJavaScriptSourcePath(path))
         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 +329,32 @@ 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);
+    const byPath = classifyArtifactPath(path);
+    if (format === "plist" &&
+        !hasBinaryPlistSignature(prefix) &&
+        (["javascript", "source-map", "entitlements"].includes(byPath.kind) ||
+            path.toLowerCase().endsWith(".asar")))
+        return byPath;
+    if (format === "file" &&
+        path.toLowerCase().endsWith(".asar") &&
+        hasAsarHeader(prefix))
+        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);
@@ -233,12 +380,15 @@ const artifactRoleForFormat = (path, format) => {
 export const classifyArtifactBytes = (prefix, fileSize = prefix.length) => {
     if (hasZipSignature(prefix))
         return "zip";
-    if (prefix.subarray(0, 8).equals(Buffer.from("bplist00")))
+    if (hasBinaryPlistSignature(prefix))
+        return "plist";
+    if (hasXmlPlistSignature(prefix))
         return "plist";
+    const fatFormat = classifyFatArtifact(prefix, fileSize);
+    if (fatFormat !== null)
+        return fatFormat;
     if (prefix.length >= 4) {
         const magic = prefix.readUInt32BE(0);
-        if ([0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic))
-            return "mach-o-universal";
         if ([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic))
             return "mach-o";
         if (prefix.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])))
@@ -249,21 +399,38 @@ export const classifyArtifactBytes = (prefix, fileSize = prefix.length) => {
             fileSize < prefix.length ||
             prefix.length < Math.min(fileSize, 64))
             return "unknown";
-        const windowsOffset = mzWindowsHeaderOffset(prefix);
-        if (windowsOffset !== null) {
-            if (windowsOffset >= 64 &&
-                windowsOffset <= prefix.length - 4 &&
-                prefix
-                    .subarray(windowsOffset, windowsOffset + 4)
-                    .equals(Buffer.from([0x50, 0x45, 0, 0])))
+        const windowsHeader = observeMzWindowsHeader(prefix, fileSize);
+        if (windowsHeader.state === "signature-needed")
+            return "unknown";
+        if (windowsHeader.state === "declared") {
+            const windowsOffset = windowsHeader.offset;
+            if (windowsHeader.signature === "PE" &&
+                windowsOffset >= 64 &&
+                windowsOffset <= prefix.length - 4)
                 return "pe";
+            return "unknown";
         }
-        else if (parseDosMzHeader(prefix, fileSize).ok)
+        if (parseDosMzHeader(prefix, fileSize).ok)
             return "dos-mz";
         return "unknown";
     }
     return "file";
 };
+const classifyFatArtifact = (prefix, fileSize) => {
+    const fatHeader = readFatContainerHeader(prefix, fileSize);
+    if (fatHeader.state === "needs-data" || fatHeader.state === "malformed")
+        return "unknown";
+    if (fatHeader.state === "not-fat")
+        return null;
+    const identity = classifyFatContainerIdentity(fatHeader, (offset) => {
+        if (offset >= prefix.length)
+            return undefined;
+        if (offset + 4 > prefix.length)
+            return null;
+        return prefix.readUInt32BE(offset);
+    });
+    return identity.state === "mach-o" ? "mach-o-universal" : "unknown";
+};
 const relationFor = (path) => {
     const lower = path.toLowerCase();
     if (lower.endsWith(".map"))

package/dist/artifacts/inventory/ArtifactInventory.js

@@ -1,15 +1,16 @@
 import { realpath } from "node:fs/promises";
-import { artifactInventoryResultSchema, } from "../../domain/artifactGraph.js";
+import { artifactInventoryOutputSchema, } 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);
+    return artifactInventoryOutputSchema.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,113 @@
-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 { 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 { 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 { 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, options.signal);
+        const digest = await hashStableRootArtifactHandle(path, handle, initial, options.signal);
+        const retainSource = isZipPackageFormat(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 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 "zip";
+        return zipRootPackageFormat(lower);
+    if (lower.endsWith(".pkg") &&
+        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.equals(Buffer.from("koly"));
+};

package/dist/artifacts/inventory/hashStableRootArtifact.js

@@ -1,32 +1,65 @@
 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, openRegularFile, sameRegularFileState, } from "../../filesystem/RegularFile.js";
+import { NonRegularFileReadError, RegularFileAdmissionFailure, openRegularFile, sameRegularFileState, } from "../../filesystem/RegularFile.js";
 import { abortIfNeeded, hashReadable, } from "../ArtifactHash.js";
-/** Hash one stable regular root file from the same descriptor that was checked. */
-export const hashStableRootArtifact = async (path, signal) => {
-    let handle;
+/** Admit a root descriptor without losing ownership when validation cleanup fails. */
+export const openRootArtifact = async (path, resourceScope, signal) => {
     try {
-        handle = await openRegularFile(path, {
-            symlinks: "reject",
-            signal,
-        });
+        return new OwnedFileHandle(await openRegularFile(path, { symlinks: "reject", signal }));
     }
     catch (cause) {
-        if (cause instanceof NonRegularFileReadError)
-            throw new ArtifactReaderFailure("format", `Artifact root is not a regular file: ${path}`, { cause });
-        throw 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();
-        return await hashStableRootArtifactHandle(path, handle, initial, signal);
+        outcome = {
+            kind: "completed",
+            value: await hashStableRootArtifactHandle(path, handle, initial, signal),
+        };
     }
-    finally {
-        await handle.close();
+    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(handle.createReadStream({ autoClose: false }), 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) ||