rea-agents 6.2.0 → 6.3.0

package/dist/artifacts/NativeDmgOwnership.js

@@ -0,0 +1,109 @@
+import { relative, resolve, sep } from "node:path";
+import { parse } from "plist";
+import { z } from "zod";
+const systemEntitySchema = z.object({
+    "dev-entry": z.string().startsWith("/dev/"),
+    "mount-point": z.string().optional(),
+});
+const attachOutputSchema = z.object({
+    "system-entities": z.array(systemEntitySchema),
+});
+const infoOutputSchema = z.object({
+    images: z.array(z.object({
+        "system-entities": z.array(systemEntitySchema),
+    })),
+});
+/** Parse hdiutil's current image inventory. */
+export const parseNativeDmgInfo = (stdout) => infoOutputSchema.parse(parse(stdout));
+/** Parse hdiutil's attach response while preserving device and mount facts. */
+export const parseNativeDmgAttachOutput = (stdout) => attachOutputSchema.parse(parse(stdout));
+/** Classify only fresh image groups tied to the exclusively owned mount root. */
+export const resolveNativeDmgOwnership = (input) => {
+    const rootedImages = input.info.images.filter((image) => image["system-entities"].some(({ "mount-point": mountPoint }) => mountPoint !== undefined && isBelowRoot(input.mountRoot, mountPoint)));
+    if (rootedImages.length > 1)
+        return {
+            status: "unknown",
+            reason: "multiple hdiutil image groups report mounts beneath the owned root",
+        };
+    const rootedImage = rootedImages[0];
+    if (rootedImage !== undefined) {
+        const hasOutsideMount = rootedImage["system-entities"].some(({ "mount-point": mountPoint }) => mountPoint !== undefined && !isBelowRoot(input.mountRoot, mountPoint));
+        const groupDevices = rootedImage["system-entities"].map(({ "dev-entry": device }) => device);
+        const devices = topLevelDevices(groupDevices);
+        const overlapsBaseline = groupDevices.some((device) => input.baselineDevices.has(device));
+        if (hasOutsideMount || overlapsBaseline || devices.length === 0)
+            return {
+                status: "unknown",
+                reason: hasOutsideMount
+                    ? "the image group contains a mount outside the owned root"
+                    : overlapsBaseline
+                        ? "the image group includes a device present before attachment"
+                        : "the owned mount group contains no detachable device",
+            };
+        return { status: "owned", devices, source: "info" };
+    }
+    if (input.attachOutputReturned) {
+        const attachOwnership = ownershipFromAttachOutput(input.attachOutput, input.mountRoot, input.baselineDevices);
+        if (attachOwnership.status === "owned") {
+            return attachOwnership;
+        }
+        if (attachOwnership.status === "unknown")
+            return attachOwnership;
+    }
+    const newlyListedDevice = input.info.images.some((image) => image["system-entities"].some(({ "dev-entry": device }) => !input.baselineDevices.has(device)));
+    if (newlyListedDevice)
+        return {
+            status: "unknown",
+            reason: "hdiutil lists devices absent from the pre-attach baseline, but none is tied uniquely to the owned root; ownership is unknown",
+        };
+    return { status: "none" };
+};
+const ownershipFromAttachOutput = (output, mountRoot, baselineDevices) => {
+    if (output === undefined)
+        return {
+            status: "unknown",
+            reason: "hdiutil attach succeeded but its ownership facts were malformed",
+        };
+    const entities = output["system-entities"];
+    const hasRootMount = entities.some(({ "mount-point": mountPoint }) => mountPoint !== undefined && isBelowRoot(mountRoot, mountPoint));
+    const hasOutsideMount = entities.some(({ "mount-point": mountPoint }) => mountPoint !== undefined && !isBelowRoot(mountRoot, mountPoint));
+    const devices = entities.map(({ "dev-entry": device }) => device);
+    const uniqueDevices = topLevelDevices(devices);
+    const overlapsBaseline = devices.some((device) => baselineDevices.has(device));
+    if (hasRootMount) {
+        if (hasOutsideMount || overlapsBaseline || uniqueDevices.length === 0)
+            return {
+                status: "unknown",
+                reason: hasOutsideMount
+                    ? "the attach result includes a mount outside the owned root"
+                    : overlapsBaseline
+                        ? "the attach result includes a device present before attachment"
+                        : "the attach result's owned mount has no detachable device",
+            };
+        return { status: "owned", devices: uniqueDevices, source: "attach" };
+    }
+    if (devices.length === 0)
+        return {
+            status: "unknown",
+            reason: "hdiutil attach succeeded without reporting device ownership facts",
+        };
+    if (devices.some((device) => !baselineDevices.has(device)))
+        return {
+            status: "unknown",
+            reason: "the attach result reports new devices without a mount beneath the owned root",
+        };
+    return { status: "none" };
+};
+const topLevelDevices = (devices) => {
+    const unique = [...new Set(devices)];
+    return unique.filter((device) => !unique.some((parent) => /^\/dev\/disk\d+$/u.test(parent) &&
+        device.startsWith(`${parent}s`) &&
+        /^\d+$/u.test(device.slice(parent.length + 1))));
+};
+const isBelowRoot = (root, path) => {
+    const child = relative(root, resolve(path));
+    return (child !== "" &&
+        child !== "." &&
+        child !== ".." &&
+        !child.startsWith(`..${sep}`));
+};

package/dist/artifacts/apple/KeyedArchiveReader.js

@@ -23,7 +23,8 @@ export const decodeKeyedArchiveBytes = (bytes, selection) => {
     const parsed = binary
         ? { value: parseBinary(bytes), omittedPrototypeKeys: 0 }
         : parseXmlPropertyList(xmlText ?? "");
-    const graph = projectKeyedArchive(normalizePlist(parsed.value), selection);
+    const { value: plistValue, unknownRealCount } = projectPlistValue(parsed.value);
+    const graph = projectKeyedArchive(plistValue, selection);
     const numbers = createPlistNumberProjection(binary
         ? binaryPlistNumberLiterals(bytes)
         : xmlPlistNumberLiterals(xmlText ?? ""));
@@ -48,15 +49,14 @@ export const decodeKeyedArchiveBytes = (bytes, selection) => {
             ...(parsed.omittedPrototypeKeys === 0
                 ? []
                 : [omittedPrototypeKeysLimitation(parsed.omittedPrototypeKeys)]),
+            ...(unknownRealCount === 0
+                ? []
+                : [
+                    `${String(unknownRealCount)} non-finite real value(s) are reported as { "$plist_type": "real", "value": null } because JSON evidence cannot preserve NaN vs infinity.`,
+                ]),
         ],
     };
 };
-const normalizePlist = (value) => {
-    const projected = projectPlistValue(value);
-    if (projected.unknownRealCount > 0)
-        throw new RangeError("Keyed archive contains a non-finite real");
-    return projected.value;
-};
 /**
  * Point to the workflow that reads the selected kind of file on this host.
  * decode_interface_builder is portable; inspect_plist requires macOS.
@@ -80,51 +80,59 @@ export const inspectBundleKeyedArchive = async (input) => {
             : `Archive path must be a canonical relative bundle path without empty, '.', or '..' segments: ${selected.path}`);
     const reader = new DirectoryArtifactReader(input.bundlePath);
     try {
+        // Match inventory spelling while retaining the raw path for I/O and evidence.
+        const wanted = selected.path.normalize("NFC");
+        const matches = [];
         for await (const entry of reader.entries(input.signal)) {
-            if (entry.path !== selected.path)
+            if (entry.path.normalize("NFC") !== wanted)
                 continue;
-            if (entry.kind !== "file")
-                throw archivePathError("invalid_value", `Archive path selects a ${entry.kind}, not a regular file: ${selected.path}`);
-            if ((entry.declaredSize ?? 0) > MAX_BYTES)
+            matches.push(entry);
+        }
+        if (matches.length > 1)
+            throw archivePathError("invalid_value", `Archive path matches ${String(matches.length)} Unicode-equivalent bundle entries; selection is ambiguous: ${selected.path}`);
+        const entry = matches[0];
+        if (entry === undefined)
+            throw archivePathError("invalid_value", `No regular file exists at ${selected.path} in the active app bundle.`);
+        if (entry.kind !== "file")
+            throw archivePathError("invalid_value", `Archive path selects a ${entry.kind}, not a regular file: ${selected.path}`);
+        if ((entry.declaredSize ?? 0) > MAX_BYTES)
+            throw new ArtifactReaderFailure("limit", "Keyed archive exceeds 64 MiB");
+        const stream = await reader.open(entry, input.signal);
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of stream) {
+            if (input.signal?.aborted) {
+                stream.destroy();
+                throw new ArtifactReaderFailure("cancelled", "Archive inspection cancelled");
+            }
+            const bytes = z.instanceof(Buffer).parse(chunk);
+            size += bytes.length;
+            if (size > MAX_BYTES) {
+                stream.destroy();
                 throw new ArtifactReaderFailure("limit", "Keyed archive exceeds 64 MiB");
-            const stream = await reader.open(entry, input.signal);
-            const chunks = [];
-            let size = 0;
-            for await (const chunk of stream) {
-                if (input.signal?.aborted) {
-                    stream.destroy();
-                    throw new ArtifactReaderFailure("cancelled", "Archive inspection cancelled");
-                }
-                const bytes = z.instanceof(Buffer).parse(chunk);
-                size += bytes.length;
-                if (size > MAX_BYTES) {
-                    stream.destroy();
-                    throw new ArtifactReaderFailure("limit", "Keyed archive exceeds 64 MiB");
-                }
-                chunks.push(bytes);
             }
-            const bytes = Buffer.concat(chunks, size);
-            try {
-                return keyedArchiveResultSchema.parse({
-                    target_sha256: input.targetSha256,
-                    archive_path: entry.path,
-                    archive_sha256: createHash("sha256").update(bytes).digest("hex"),
-                    ...decodeKeyedArchiveBytes(bytes, selected),
+            chunks.push(bytes);
+        }
+        const bytes = Buffer.concat(chunks, size);
+        try {
+            return keyedArchiveResultSchema.parse({
+                target_sha256: input.targetSha256,
+                archive_path: entry.path,
+                archive_sha256: createHash("sha256").update(bytes).digest("hex"),
+                ...decodeKeyedArchiveBytes(bytes, selected),
+            });
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisInputError)
+                throw cause;
+            // An intact file of another kind is not a damaged archive.
+            if (cause instanceof KeyedArchiveKindError)
+                throw new AnalysisUnsupportedTargetError("inspect_keyed_archive", join(input.bundlePath, entry.path), cause.message, {
+                    cause,
+                    remediationAction: keyedArchiveKindRemediation(cause.kind, input.platform ?? process.platform),
                 });
-            }
-            catch (cause) {
-                if (cause instanceof AnalysisInputError)
-                    throw cause;
-                // An intact file of another kind is not a damaged archive.
-                if (cause instanceof KeyedArchiveKindError)
-                    throw new AnalysisUnsupportedTargetError("inspect_keyed_archive", join(input.bundlePath, entry.path), cause.message, {
-                        cause,
-                        remediationAction: keyedArchiveKindRemediation(cause.kind, input.platform ?? process.platform),
-                    });
-                throw new ArtifactReaderFailure(cause instanceof RangeError ? "limit" : "format", `Cannot decode selected Foundation keyed archive: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
-            }
+            throw new ArtifactReaderFailure(cause instanceof RangeError ? "limit" : "format", `Cannot decode selected Foundation keyed archive: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
         }
-        throw archivePathError("invalid_value", `No regular file exists at ${selected.path} in the active app bundle.`);
     }
     finally {
         await reader.close();

package/dist/artifacts/apple/MachoLoadCommandReader.js

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

package/dist/artifacts/extraction/ArtifactExtraction.js

@@ -1,6 +1,6 @@
 import { lstat, realpath } from "node:fs/promises";
-import { compareCodePoints } from "../../domain/canonicalOrdering.js";
-import { canonicalDigest } from "../../domain/comparisonSemantics.js";
+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
+import { digestCanonicalValue } from "../../domain/canonicalDigest.js";
 import { AsarArtifactReader } from "../AsarArtifactReader.js";
 import { ArtifactPathRegistry, normalizeArtifactPath, } from "../ArtifactPaths.js";
 import { ArtifactReaderFailure, } from "../ArtifactReader.js";
@@ -22,9 +22,26 @@ export const extractArtifact = async (input, signal) => {
         signal,
         environment: input.environment,
     });
+    return materializeArtifactInventory(input, sourcePath, snapshot, signal);
+};
+/** Materialize a scanned inventory, verifying every current occurrence against it. */
+export const materializeArtifactInventory = async (input, sourcePath, snapshot, signal) => {
+    abortIfNeeded(signal);
     const selectedOccurrences = snapshot.occurrences.filter((occurrence) => (occurrence.entry_kind === "file" || occurrence.entry_kind === "slice") &&
         occurrence.logical_path !== ".");
-    const selectedIds = new Set(selectedOccurrences.map(({ occurrence_id: id }) => id));
+    const regularPaths = new Set(selectedOccurrences.map(({ logical_path: path }) => path));
+    const activeOccurrences = selectedOccurrences.filter(({ logical_path }) => {
+        // Nested members remain represented by their containing regular file;
+        // only entries exposed by the active reader are materialized.
+        let path = logical_path;
+        for (let slash = path.lastIndexOf("/"); slash >= 0; slash = path.lastIndexOf("/")) {
+            path = path.slice(0, slash);
+            if (regularPaths.has(path))
+                return false;
+        }
+        return true;
+    });
+    const selectedIds = new Set(activeOccurrences.map(({ occurrence_id: id }) => id));
     const occurrences = new Map();
     const neededNodes = new Set();
     collectOccurrences(snapshot.occurrences, selectedIds, occurrences, neededNodes);
@@ -35,7 +52,7 @@ export const extractArtifact = async (input, signal) => {
         occurrences,
         nodes,
     };
-    const selected = selectedOccurrences.map((occurrence) => {
+    const selected = activeOccurrences.map((occurrence) => {
         // REA never decrypts archive entries, so an encrypted entry makes the
         // complete extraction unsupported rather than the archive invalid.
         if (occurrence.encrypted)
@@ -66,7 +83,6 @@ const materializeSelection = async ({ input, sourcePath, inventory, selected, si
     const extracted = [];
     try {
         output = await SafeOutputTree.create(input.outputRoot);
-        const materialized = [];
         const registry = new ArtifactPathRegistry();
         for await (const entry of reader.entries(signal)) {
             const path = normalizeArtifactPath(entry.path);
@@ -87,13 +103,15 @@ const materializeSelection = async ({ input, sourcePath, inventory, selected, si
                 bytes_written: written.bytesWritten,
                 created: true,
             });
-            materialized.push(selectedItem);
+            byPath.delete(path);
         }
+        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;
-        extracted.sort((left, right) => compareCodePoints(left.relative_path, right.relative_path));
-        const result = createExtractionResult(input, inventory, materialized, extracted);
+        extracted.sort((left, right) => compareUnicodeCodePoints(left.relative_path, right.relative_path));
+        const result = createExtractionResult(input, inventory, selected, extracted);
         await output.commit();
         return result;
     }
@@ -144,15 +162,15 @@ const createExtractionResult = (input, inventory, selected, extracted) => {
         source_manifest_id: inventory.manifest.manifest_id,
         selected_occurrence_ids: selected
             .map(({ occurrence }) => occurrence.occurrence_id)
-            .sort(compareCodePoints),
-        files_sha256: canonicalDigest(extracted, "Artifact"),
+            .sort(compareUnicodeCodePoints),
+        files_sha256: digestCanonicalValue(extracted, "Artifact"),
         output_root_alias: "$OUTPUT_ROOT",
     };
     return artifactExtractionResultSchema.parse({
         manifest: inventory.manifest,
         extraction_manifest: {
             ...extractionSemantic,
-            extraction_id: `aex_${canonicalDigest(extractionSemantic, "Artifact")}`,
+            extraction_id: `aex_${digestCanonicalValue(extractionSemantic, "Artifact")}`,
         },
         output_root: input.outputRoot,
         artifacts: extracted,

package/dist/artifacts/inventory/ArtifactGraphConstruction.js

@@ -1,5 +1,5 @@
-import { compareCodePoints } from "../../domain/canonicalOrdering.js";
-import { canonicalDigest } from "../../domain/comparisonSemantics.js";
+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
+import { digestCanonicalValue } from "../../domain/canonicalDigest.js";
 import { artifactEdgeId, artifactIdForContent, occurrenceIdForLocation, } from "../../domain/artifactIdentity.js";
 import { hasZipSignature, zipPackageFormatForPath, } from "../../domain/zipPackageFormat.js";
 import { mzWindowsHeaderOffset, parseDosMzHeader } from "../../domain/dosMz.js";
@@ -12,7 +12,7 @@ export const indexOccurrencesByPath = (occurrences) => {
     return byPath;
 };
 export const createOccurrence = (entry, path, parent) => ({
-    occurrence_id: `occ_${canonicalDigest({ path, kind: entry.kind }, "Artifact")}`,
+    occurrence_id: `occ_${digestCanonicalValue({ path, kind: entry.kind }, "Artifact")}`,
     artifact_id: null,
     parent_occurrence_id: parent,
     logical_path: path,
@@ -36,7 +36,6 @@ export const createOccurrence = (entry, path, parent) => ({
     limitations: [...entry.limitations],
 });
 /** Compare exact child names independently of host locale and traversal order. */
-export const compareDirectoryChildNames = compareCodePoints;
 export const materializeDirectoryNodes = (occurrences, nodes) => {
     const directories = occurrences
         .filter(({ entry_kind: kind }) => kind === "directory")
@@ -59,9 +58,9 @@ export const materializeDirectoryNodes = (occurrences, nodes) => {
             artifact_id,
             entry_kind,
         }))
-            .sort((left, right) => compareDirectoryChildNames(left.name, right.name));
+            .sort((left, right) => compareUnicodeCodePoints(left.name, right.name));
         const node = createArtifactNode({
-            sha256: canonicalDigest({ kind: "directory", children }, "Artifact"),
+            sha256: digestCanonicalValue({ kind: "directory", children }, "Artifact"),
             size: 0,
             format: "directory",
             contentState: "virtual",
@@ -73,14 +72,14 @@ export const materializeDirectoryNodes = (occurrences, nodes) => {
 };
 export const createRootNode = (input) => createArtifactNode({
     sha256: input.digest?.sha256 ??
-        canonicalDigest({
+        digestCanonicalValue({
             kind: "directory-root",
             children: input.occurrences
                 .map(({ logical_path, artifact_id }) => ({
                 logical_path,
                 artifact_id,
             }))
-                .sort((left, right) => compareDirectoryChildNames(left.logical_path, right.logical_path)),
+                .sort((left, right) => compareUnicodeCodePoints(left.logical_path, right.logical_path)),
         }, "Artifact"),
     size: input.digest?.bytes ?? 0,
     format: input.digest === null

package/dist/artifacts/inventory/classify.js

@@ -1,7 +1,9 @@
-import { open } from "node:fs/promises";
+import { NonRegularFileReadError, openRegularFile, 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);
@@ -12,23 +14,40 @@ const classifyContainerExtension = (path) => {
             return format;
     return undefined;
 };
-export const classifyRoot = async (path, directory) => {
+/** Classify and hash one file root through the same stable open descriptor. */
+export const classifyAndHashRoot = async (path, directory, expectedMetadata, signal) => {
     if (directory)
-        return "directory";
-    const extensionFormat = classifyContainerExtension(path);
-    if (extensionFormat !== undefined)
-        return extensionFormat;
-    const handle = await open(path, "r");
+        return { format: "directory", digest: null };
+    const handle = await openRootFile(path, signal);
     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 = 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 });
+    }
+    catch (cause) {
+        if (cause instanceof NonRegularFileReadError)
+            throw new ArtifactReaderFailure("format", `Artifact root is not a regular file: ${path}`, { cause });
+        throw cause;
+    }
+};
+const classifyOpenedRoot = 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);
+    if (hasZipSignature(prefix))
+        return "zip";
+    return classifyArtifactContent(path, prefix, (await handle.stat()).size)
+        .format;
+};

package/dist/artifacts/inventory/hashStableRootArtifact.js

@@ -0,0 +1,37 @@
+import { lstat } from "node:fs/promises";
+import { ArtifactReaderFailure } from "../ArtifactReader.js";
+import { NonRegularFileReadError, 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;
+    try {
+        handle = 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;
+    }
+    try {
+        const initial = await handle.stat();
+        return await hashStableRootArtifactHandle(path, handle, initial, signal);
+    }
+    finally {
+        await handle.close();
+    }
+};
+/** 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);
+    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/scanCanonical.js

@@ -1,26 +1,27 @@
-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 { classifyAndHashRoot } from "./classify.js";
+import {} from "../ArtifactHash.js";
+import { hashStableRootArtifact } 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) => {
     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 { format: rootFormat, digest: rootDigest } = await classifyAndHashRoot(path, metadata.isDirectory(), metadata, options.signal);
     const reader = await readerFactory(path, rootFormat, options.environment ?? {}, options.signal);
+    const ownedReaders = reader === undefined ? [] : [reader];
     let outcome;
     try {
-        const { nodes, occurrences, pendingContradictions } = await scanReader(reader, options.signal, integrity);
+        if (reader instanceof AsarArtifactReader)
+            await reader.prepareContainer(rootDigest?.sha256, options.signal);
+        const { nodes, occurrences, pendingContradictions } = await scanReader(reader, ownedReaders, options.signal, integrity);
         outcome = {
             kind: "completed",
             snapshot: await buildInventorySnapshot({
@@ -39,16 +40,21 @@ export const scanCanonicalArtifactInventory = async (path, options = {}, readerF
     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);
+    let cleanupFailure;
+    for (const owned of ownedReaders.reverse()) {
+        try {
+            await owned.close();
+        }
+        catch (cleanupCause) {
+            const cleanup = ArtifactReaderFailure.cleanupObservation(cleanupCause, `artifact reader for ${path}`);
+            cleanupFailure = ArtifactReaderFailure.withCleanup(cleanupFailure ??
+                (outcome.kind === "failed" ? outcome.cause : cleanupCause), cleanup, outcome.kind === "completed"
+                ? { kind: "artifact-inventory", inventory: outcome.snapshot }
+                : undefined);
+        }
     }
+    if (cleanupFailure !== undefined)
+        throw cleanupFailure;
     if (outcome.kind === "failed")
         throw outcome.cause;
     return outcome.snapshot;
@@ -142,14 +148,14 @@ const buildIntegrityContradictions = (pending, occurrenceByPath, occurrenceById,
 const verifyRootDigest = async (path, rootDigest, signal) => {
     if (rootDigest === null)
         return;
-    const verified = await hashReadable(createReadStream(path), signal);
+    const verified = await hashStableRootArtifact(path, 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,