rea-agents 6.3.0 → 6.4.0

package/dist/browser/PngVisualDiff.js

@@ -1,9 +1,17 @@
-import { inflateSync } from "node:zlib";
+import { constants as zlibConstants, crc32, inflateSync } from "node:zlib";
+import { AnalysisResourceConstraintError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
 import { decodeCanonicalBase64 } from "../domain/webScreenshot.js";
+/** Conservative allowance for the simultaneously live PNG comparison buffers. */
+const PNG_COMPARISON_WORKING_MEMORY_BYTES = 256 * 1024 * 1024;
+const PNG_INFLATE_CHUNK_BYTES = zlibConstants.Z_DEFAULT_CHUNK;
 /** Compare two validated screenshots using deterministic RGBA metrics. */
 export const comparePngScreenshots = (input) => {
-    const before = decodePng(input.before);
-    const after = decodePng(input.after);
+    admitEncodedInputPair(input.before, input.after);
+    const beforePlan = parsePng(input.before, "before");
+    const afterPlan = parsePng(input.after, "after");
+    admitPngPair(beforePlan, afterPlan);
+    const before = decodePng(beforePlan);
+    const after = decodePng(afterPlan);
     if (before.width !== after.width || before.height !== after.height)
         return {
             status: "dimension_mismatch",
@@ -57,7 +65,7 @@ export const comparePngScreenshots = (input) => {
         changed_ratio: changedPixels / pixels,
     };
 };
-const decodePng = (artifact) => {
+const parsePng = (artifact, field) => {
     const bytes = decodeCanonicalBase64(artifact.data_base64);
     if (bytes === undefined || !bytes.subarray(0, 8).equals(PNG_SIGNATURE))
         throw new TypeError("Invalid PNG signature");
@@ -65,68 +73,229 @@ const decodePng = (artifact) => {
     let header;
     const compressed = [];
     let sawEnd = false;
+    let sawPalette = false;
+    let imageDataEnded = false;
+    let paletteEntries = 0;
     let transparentColor;
+    let sawTransparency = false;
+    let unsupportedReason;
     while (offset < bytes.length) {
         if (offset + 12 > bytes.length)
             throw new TypeError("Truncated PNG chunk");
         const length = bytes.readUInt32BE(offset);
-        const type = bytes.subarray(offset + 4, offset + 8).toString("ascii");
+        if (length > 0x7fffffff)
+            throw new TypeError("Invalid PNG chunk length");
+        const type = bytes.subarray(offset + 4, offset + 8).toString("latin1");
         const dataStart = offset + 8;
         const dataEnd = dataStart + length;
         if (dataEnd + 4 > bytes.length)
             throw new TypeError("Truncated PNG data");
         const data = bytes.subarray(dataStart, dataEnd);
-        if (type === "IHDR")
+        if (crc32(bytes.subarray(offset + 4, dataEnd)) !== bytes.readUInt32BE(dataEnd))
+            throw new TypeError("Invalid PNG chunk checksum");
+        if (!/^[A-Za-z]{4}$/u.test(type) || type[2] !== type[2]?.toUpperCase())
+            throw new TypeError("Invalid PNG chunk type");
+        if (type !== "IDAT" && compressed.length > 0)
+            imageDataEnded = true;
+        if (type === "IHDR") {
+            if (offset !== 8 || header !== undefined)
+                throw new TypeError("Invalid PNG header order");
             header = parseHeader(data);
+        }
+        else if (header === undefined)
+            throw new TypeError("Invalid PNG header order");
         else if (type === "tRNS") {
-            if (header?.channels !== 3 || data.length !== 6)
+            if (sawTransparency || compressed.length > 0)
+                throw new TypeError("Invalid PNG transparency order");
+            sawTransparency = true;
+            if (header.colorType === 2 && data.length === 6) {
+                transparentColor = [
+                    data.readUInt16BE(0),
+                    data.readUInt16BE(2),
+                    data.readUInt16BE(4),
+                ];
+            }
+            else if ((header.colorType === 0 && data.length === 2) ||
+                (header.colorType === 3 &&
+                    sawPalette &&
+                    data.length > 0 &&
+                    data.length <= paletteEntries)) {
+                unsupportedReason ??=
+                    "PNG transparency for this color type is not supported.";
+            }
+            else {
                 throw new TypeError("Unsupported PNG transparency");
-            transparentColor = [
-                data.readUInt16BE(0),
-                data.readUInt16BE(2),
-                data.readUInt16BE(4),
-            ];
+            }
+        }
+        else if (type === "PLTE") {
+            if (sawPalette ||
+                sawTransparency ||
+                compressed.length > 0 ||
+                length === 0 ||
+                length > 768 ||
+                length % 3 !== 0 ||
+                (header.colorType === 3 && length / 3 > 2 ** header.bitDepth) ||
+                (header.colorType !== 2 &&
+                    header.colorType !== 3 &&
+                    header.colorType !== 6))
+                throw new TypeError("Invalid PNG palette");
+            sawPalette = true;
+            paletteEntries = length / 3;
         }
-        else if (type === "IDAT")
+        else if (type === "IDAT") {
+            if (imageDataEnded)
+                throw new TypeError("Nonconsecutive PNG image data");
             compressed.push(data);
+        }
         else if (type === "IEND") {
+            if (length !== 0 || dataEnd + 4 !== bytes.length)
+                throw new TypeError("Invalid PNG end chunk");
             sawEnd = true;
             break;
         }
+        else if (/^[A-Z]/u.test(type)) {
+            unsupportedReason ??= `Unsupported critical PNG chunk ${type}.`;
+        }
         offset = dataEnd + 4;
     }
     if (header === undefined || !sawEnd || compressed.length === 0)
         throw new TypeError("Incomplete PNG");
-    const rowBytes = header.width * header.channels;
-    const expected = (rowBytes + 1) * header.height;
-    const raw = inflateSync(Buffer.concat(compressed), {
-        maxOutputLength: expected + 1,
-    });
-    if (raw.byteLength !== expected)
-        throw new TypeError("Unexpected PNG size");
+    if (header.colorType === 3 && !sawPalette)
+        throw new TypeError("Missing PNG palette");
+    if (unsupportedReason !== undefined)
+        throw new AnalysisUnsupportedTargetError("compare_web_screenshots", field, unsupportedReason);
+    if (!header.supported)
+        throw new AnalysisUnsupportedTargetError("compare_web_screenshots", field, "PNG encoding is not supported for pixel comparison.");
+    const pixels = BigInt(header.width) * BigInt(header.height);
+    const expectedRawBytes = (BigInt(header.width) * BigInt(header.channels) + 1n) *
+        BigInt(header.height);
     return {
+        bytes,
         width: header.width,
         height: header.height,
-        rgba: expandRgba(unfilter(raw, header.width, header.height, header.channels), header.channels, transparentColor),
+        channels: header.channels,
+        compressed,
+        transparentColor,
+        expectedRawBytes,
+        unfilteredBytes: pixels * BigInt(header.channels),
+        rgbaBytes: pixels * 4n,
+    };
+};
+const decodePng = (plan) => {
+    const expected = Number(plan.expectedRawBytes);
+    const raw = inflatePng(Buffer.concat(plan.compressed), expected + 1);
+    if (raw.byteLength !== expected)
+        throw new TypeError("Unexpected PNG size");
+    return {
+        width: plan.width,
+        height: plan.height,
+        rgba: expandRgba(unfilter(raw, plan.width, plan.height, plan.channels), plan.channels, plan.transparentColor),
     };
 };
+const admitEncodedInputPair = (before, after) => {
+    const sourceBytes = BigInt(before.bytes) + BigInt(after.bytes);
+    if (sourceBytes > BigInt(PNG_COMPARISON_WORKING_MEMORY_BYTES))
+        throw pngWorkingMemoryError(sourceBytes, null, null);
+};
+const admitPngPair = (before, after) => {
+    // Input buffers remain live for both plans. For each decode, count the
+    // concatenated IDAT, rounded zlib output chunks, any concatenated output and
+    // unfiltered rows, plus RGB-to-RGBA output. The first completed RGBA image
+    // remains live while the second is decoded.
+    const inputBytes = BigInt(before.bytes.byteLength + after.bytes.byteLength);
+    const estimate = (current, retained) => {
+        const compressedBytes = current.compressed.reduce((total, chunk) => total + BigInt(chunk.byteLength), 0n);
+        const rgbaExpansion = current.channels === 3 ? current.rgbaBytes : 0n;
+        return (inputBytes +
+            (retained?.rgbaBytes ?? 0n) +
+            compressedBytes +
+            inflateBufferAllowance(current.expectedRawBytes) +
+            current.unfilteredBytes +
+            rgbaExpansion);
+    };
+    const estimateBytes = [
+        estimate(before, undefined),
+        estimate(after, before),
+    ].reduce((maximum, value) => (value > maximum ? value : maximum), 0n);
+    if (estimateBytes > BigInt(PNG_COMPARISON_WORKING_MEMORY_BYTES))
+        throw pngWorkingMemoryError(estimateBytes, before, after);
+};
+const inflateBufferAllowance = (expectedRawBytes) => {
+    const chunkBytes = BigInt(PNG_INFLATE_CHUNK_BYTES);
+    const maximumOutputBytes = expectedRawBytes + 1n;
+    const roundUpToChunk = (bytes) => ((bytes + chunkBytes - 1n) / chunkBytes) * chunkBytes;
+    // Node checks maxOutputLength after writing a chunk, so a rejected stream can
+    // retain one chunk's worth of output past the limit before it throws.
+    const rejectedOutputChunks = roundUpToChunk(maximumOutputBytes + chunkBytes - 1n);
+    // Sync zlib retains each output chunk while Buffer.concat creates the final
+    // result. A full final chunk also allocates the next scratch chunk first.
+    const returnedOutputChunks = roundUpToChunk(maximumOutputBytes);
+    const scratchChunk = expectedRawBytes % chunkBytes === 0n ||
+        maximumOutputBytes % chunkBytes === 0n
+        ? chunkBytes
+        : 0n;
+    const concatenatedOutput = maximumOutputBytes > chunkBytes ? maximumOutputBytes : 0n;
+    const returnedOutput = returnedOutputChunks + scratchChunk + concatenatedOutput;
+    return rejectedOutputChunks > returnedOutput
+        ? rejectedOutputChunks
+        : returnedOutput;
+};
+const pngWorkingMemoryError = (estimateBytes, before, after) => new AnalysisResourceConstraintError("compare_web_screenshots", "memory", "Screenshot comparison exceeds REA's 256 MiB estimated working-memory budget.", {
+    boundary: "png-screenshot-comparison",
+    estimated_working_memory_bytes: estimateBytes.toString(),
+    maximum_working_memory_bytes: PNG_COMPARISON_WORKING_MEMORY_BYTES,
+    before_dimensions: before === null ? null : { width: before.width, height: before.height },
+    after_dimensions: after === null ? null : { width: after.width, height: after.height },
+}, {
+    remediationAction: "Compare smaller screenshots or reduce their viewport dimensions before capture.",
+});
+const inflatePng = (compressed, maxOutputLength) => {
+    try {
+        return inflateSync(compressed, {
+            maxOutputLength,
+            chunkSize: PNG_INFLATE_CHUNK_BYTES,
+        });
+    }
+    catch (cause) {
+        if (cause instanceof Error &&
+            "code" in cause &&
+            (cause.code === "Z_DATA_ERROR" ||
+                cause.code === "Z_BUF_ERROR" ||
+                cause.code === "ERR_BUFFER_TOO_LARGE"))
+            throw new TypeError("Invalid PNG image data", { cause });
+        throw cause;
+    }
+};
 const parseHeader = (data) => {
     if (data.byteLength !== 13)
         throw new TypeError("Invalid PNG header");
     const width = data.readUInt32BE(0);
     const height = data.readUInt32BE(4);
-    const bitDepth = data[8];
-    const colorType = data[9];
+    const bitDepth = data[8] ?? 0;
+    const colorType = data[9] ?? -1;
+    const validDepth = (colorType === 0 && [1, 2, 4, 8, 16].includes(bitDepth)) ||
+        (colorType === 2 && [8, 16].includes(bitDepth)) ||
+        (colorType === 3 && [1, 2, 4, 8].includes(bitDepth)) ||
+        (colorType === 4 && [8, 16].includes(bitDepth)) ||
+        (colorType === 6 && [8, 16].includes(bitDepth));
     if (width === 0 ||
         height === 0 ||
-        !Number.isSafeInteger(width * height) ||
-        bitDepth !== 8 ||
-        (colorType !== 2 && colorType !== 6) ||
+        width > 0x7fffffff ||
+        height > 0x7fffffff ||
+        !validDepth ||
         data[10] !== 0 ||
         data[11] !== 0 ||
-        data[12] !== 0)
-        throw new TypeError("Unsupported PNG");
-    return { width, height, channels: colorType === 6 ? 4 : 3 };
+        (data[12] !== 0 && data[12] !== 1))
+        throw new TypeError("Invalid PNG header");
+    return {
+        width,
+        height,
+        colorType,
+        bitDepth,
+        interlace: data[12],
+        channels: colorType === 6 ? 4 : 3,
+        supported: bitDepth === 8 && (colorType === 2 || colorType === 6) && data[12] === 0,
+    };
 };
 const unfilter = (raw, width, height, channels) => {
     const rowBytes = width * channels;

package/dist/browser/WebSourceMapFetcher.js

@@ -9,7 +9,7 @@ import { webSourceMapsSchema } from "../domain/webBundleAnalysis.js";
 import { createWebTextArtifact } from "../domain/webContentArtifact.js";
 import { safeParseJson } from "../domain/safeJson.js";
 import { jsonParts } from "../domain/jsonSerialization.js";
-import { inspectSourceMapValue, SourceMapFormatFailure, } from "../javascript/sourceMaps/SourceMapFormat.js";
+import { inspectSourceMapValue, sourceMapJsonText, SourceMapFormatFailure, } from "../javascript/sourceMaps/SourceMapFormat.js";
 import { WEB_SOURCE_MAP_LIMITS } from "../domain/webSourceLocation.js";
 // Source maps are normally fetched as a small part of a larger inspection.
 // Bound a stalled server to 30 seconds and bound raw map input retained for
@@ -235,7 +235,7 @@ const readBoundedText = async (response, budget, maxBytes, signal) => {
         offset += chunk.byteLength;
     }
     try {
-        return new TextDecoder("utf-8", { fatal: true }).decode(joined);
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(joined);
     }
     catch {
         throw new SourceMapEncodingError();
@@ -314,7 +314,7 @@ const promiseWithAbort = (promise, signal) => {
     });
 };
 const normalizeSourceMap = (request, text, fetchedUrl, context) => {
-    const parsedJson = safeParseJson(text);
+    const parsedJson = safeParseJson(sourceMapJsonText(text));
     if (!parsedJson.ok)
         return emptySourceMapItem(request, "invalid", "Source-map JSON is not a version 3 map.");
     const retainedBytesBeforeMap = context.budget.expandedBytes;

package/dist/browser/assets/LocalWebScriptArtifacts.js

@@ -17,6 +17,7 @@ export class LocalWebScriptArtifacts {
     async load(input, options) {
         let field = ["manifest_path"];
         let targetPath = input.manifest_path;
+        let callerSelected = true;
         try {
             const manifestBytes = await readWebArtifactJson(input.manifest_path, 32 * 1024 * 1024, options?.signal);
             const manifest = webScriptExportManifestSchema.parse(manifestBytes.value);
@@ -34,6 +35,7 @@ export class LocalWebScriptArtifacts {
             const root = resolve(dirname(input.manifest_path));
             const sourcePath = join(root, "files", portable);
             targetPath = sourcePath;
+            callerSelected = false;
             await assertContained(root, sourcePath);
             const sourceBytes = await readStableArtifact(sourcePath, 16 * 1024 * 1024, options?.signal);
             await assertContained(root, sourcePath);
@@ -62,7 +64,7 @@ export class LocalWebScriptArtifacts {
             });
         }
         catch (cause) {
-            return err(webArtifactReadError(cause, { operation: this.operation, field, targetPath }, options?.signal));
+            return err(webArtifactReadError(cause, { operation: this.operation, field, targetPath, callerSelected }, options?.signal));
         }
     }
 }

package/dist/browser/assets/PublishWebScripts.js

@@ -1,24 +1,34 @@
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { Readable } from "node:stream";
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
+import { DESTINATION_CASE_COLLISION_PREFIX } from "../../artifacts/ArtifactPaths.js";
 import { SafeOutputTree } from "../../artifacts/SafeOutputTree.js";
+import { SafeOutputTreeCreationFailure } from "../../artifacts/SafeOutputTreeCreationFailure.js";
 import { webScriptExportManifestSchema, webScriptExportResultSchema, } from "../../domain/webScriptExport.js";
-import { planWebScriptExport } from "../../domain/webScriptExportPlan.js";
+import { planWebScriptExport, } from "../../domain/webScriptExportPlan.js";
 import { WebScriptExportError } from "../../domain/webScriptExportError.js";
 const LIMITATIONS = [
     "Only script bytes retained in this capture are exported. Sources are not refetched or executed, and a response or Debugger source does not prove execution.",
-    "Ordinary unambiguous URL paths preserve relative module layouts by origin. Query variants, collisions, inline sources, and unrepresentable paths are isolated; their browser module relationships remain unknown.",
+    "Ordinary unambiguous URL paths preserve relative module layouts by origin, including case-distinct spellings. Query variants, exact path collisions, file/directory prefixes, inline sources, and unrepresentable paths are isolated. A case-distinct pair is isolated only when the destination filesystem cannot store both spellings; the record names that pair. Browser module relationships of isolated paths remain unknown.",
     "Local JavaScript analysis does not implement browser import maps, root-relative URL resolution, remote URL loading, or browser runtime behavior. It may strip import queries and fragments; isolated variants are not canonical targets.",
     "Source-map declarations are retained as metadata. No source maps or missing dependencies are fetched or reconstructed.",
     "Captured response bytes are browser-decoded bytes; Debugger sources are the exposed text encoded as UTF-8. Redacted bytes are exported exactly as retained, and may no longer parse as JavaScript.",
 ];
 /** Exclusively publish verified bytes and a manifest, rolling back partial work. */
-export const publishWebScripts = async (input, capture, captureSha256, signal) => {
+export const publishWebScripts = async (input, capture, captureSha256, options) => options.resources.run(async () => {
     const planned = planWebScriptExport(capture.scripts);
-    const tree = await SafeOutputTree.create(input.output_directory);
+    let tree;
+    let result;
     try {
-        signal?.throwIfAborted();
-        const records = planned.map(({ record }) => record);
+        tree = await SafeOutputTree.create(input.output_directory);
+        options.signal?.throwIfAborted();
+        const records = [];
+        for (const [index, item] of planned.entries()) {
+            options.signal?.throwIfAborted();
+            records.push(await publishPlannedScript(tree, item, index, options.signal));
+        }
         const manifest = webScriptExportManifestSchema.parse({
             capture_path: input.capture_path,
             capture_sha256: captureSha256,
@@ -42,7 +52,7 @@ export const publishWebScripts = async (input, capture, captureSha256, signal) =
         });
         const bytes = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
         const digest = createHash("sha256").update(bytes).digest("hex");
-        const result = webScriptExportResultSchema.parse({
+        result = webScriptExportResultSchema.parse({
             ...manifest,
             manifest: {
                 path: join(tree.outputRoot, "manifest.json"),
@@ -50,25 +60,70 @@ export const publishWebScripts = async (input, capture, captureSha256, signal) =
                 bytes: bytes.length,
             },
         });
-        for (const { script, record } of planned) {
-            signal?.throwIfAborted();
-            if (script.content.state === "captured" &&
-                record.content.state === "exported")
-                await tree.write(`files/${record.content.relative_path}`, Readable.from([script.content.bytes]), script.content.sha256, signal);
-        }
-        await tree.write("manifest.json", Readable.from([bytes]), digest, signal);
-        signal?.throwIfAborted();
+        await tree.write("manifest.json", Readable.from([bytes]), { sha256: digest, bytes: bytes.byteLength }, options.signal);
+        options.signal?.throwIfAborted();
         await tree.commit();
         return result;
     }
     catch (cause) {
-        try {
-            await tree.rollback();
-        }
-        catch (cleanupCause) {
-            throw new WebScriptExportError("io", tree.outputRoot, `Publication failed (${message(cause)}); rollback failed (${message(cleanupCause)}). Remove the residual output directory before retrying.`, [tree.outputRoot]);
+        if (cause instanceof SafeOutputTreeCreationFailure)
+            tree = cause.tree;
+        if (tree !== undefined) {
+            const cleanup = await options.resources.release({
+                kind: "output-tree",
+                resource: tree.outputRoot,
+                tree,
+            });
+            if (cleanup.kind === "failed") {
+                const cleanupCause = cleanup.cause;
+                const diagnostic = tree.published
+                    ? `Publication completed, but descriptor cleanup failed (${message(cleanupCause)}). The published output remains available.`
+                    : `Publication failed (${message(cause)}); rollback failed (${message(cleanupCause)}). Remove the residual output directory before retrying.`;
+                const error = new WebScriptExportError(cause instanceof ArtifactReaderFailure ? cause.reason : "io", tree.outputRoot, diagnostic, { residualPaths: [tree.outputRoot] });
+                if (tree.published && result !== undefined)
+                    error.retainPartialObservation({
+                        kind: "web-script-export",
+                        result,
+                    });
+                throw error;
+            }
+            if (tree.published && result !== undefined)
+                return result;
         }
         throw cause;
     }
+});
+const publishPlannedScript = async (tree, item, index, signal) => {
+    const { script, record } = item;
+    const content = script.content;
+    if (content.state !== "captured" || record.content.state !== "exported")
+        return record;
+    const write = (relativePath) => tree.write(`files/${relativePath}`, Readable.from([content.bytes]), { sha256: content.sha256, bytes: content.bytes.byteLength }, signal);
+    try {
+        await write(record.content.relative_path);
+        return record;
+    }
+    catch (cause) {
+        const collision = destinationCollisionReason(cause);
+        if (collision === undefined || record.content.layout !== "url-path")
+            throw cause;
+        const relativePath = isolatedScriptPath(script, index);
+        await write(relativePath);
+        return {
+            ...record,
+            content: {
+                ...record.content,
+                relative_path: relativePath,
+                layout: "isolated",
+                layout_reason: collision,
+            },
+        };
+    }
 };
+const isolatedScriptPath = (script, index) => `isolated/source-${index + 1}-${createHash("sha256").update(JSON.stringify(script.source)).digest("hex")}.js`;
+const destinationCollisionReason = (cause) => cause instanceof ArtifactReaderFailure &&
+    cause.reason === "path" &&
+    cause.message.startsWith(DESTINATION_CASE_COLLISION_PREFIX)
+    ? cause.message
+    : undefined;
 const message = (cause) => cause instanceof Error ? cause.message : "Unknown publication failure";

package/dist/browser/assets/WebArtifactReads.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
 import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
-import { AnalysisCancelledError, AnalysisInputError, } from "../../domain/analysisErrorCore.js";
+import { AnalysisAccessDeniedError, AnalysisCancelledError, AnalysisInputError, } from "../../domain/analysisErrorCore.js";
 import { ArtifactOperationError } from "../../domain/artifactOperationError.js";
 import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
 import { safeParseJson } from "../../domain/safeJson.js";
@@ -29,6 +29,11 @@ export const readWebArtifactJson = async (path, maximumBytes, signal) => {
 export const webArtifactReadError = (cause, context, signal) => {
     if (signal?.aborted === true)
         return new AnalysisCancelledError(context.operation);
+    const selection = context.callerSelected
+        ? selectedFileError(cause, context)
+        : undefined;
+    if (selection !== undefined)
+        return selection;
     if (cause instanceof ArtifactReaderFailure)
         return new ArtifactOperationError(context.operation, cause.reason, cause.details, cause.message);
     if (cause instanceof Error &&
@@ -54,3 +59,20 @@ export const webArtifactReadError = (cause, context, signal) => {
         },
     });
 };
+/**
+ * Report a missing, non-regular or unreadable caller-selected file as the
+ * caller's selection or a host permission denial, not an artifact fault.
+ */
+const selectedFileError = (cause, context) => {
+    const selected = (message) => new AnalysisInputError(context.operation, { cause }, [
+        { path: context.field, reason: "invalid_value", message },
+    ]);
+    if (cause instanceof ArtifactReaderFailure)
+        return cause.reason === "path" ? selected(cause.message) : undefined;
+    const code = cause instanceof Error && "code" in cause ? String(cause.code) : "";
+    if (code === "EACCES" || code === "EPERM")
+        return new AnalysisAccessDeniedError(context.operation, context.targetPath, code, { cause });
+    if (code === "ENOENT" || code === "ENOTDIR")
+        return selected(`Selected file could not be read (${code}): ${context.targetPath}`);
+    return undefined;
+};

package/dist/browser/assets/WebSourceLocationArtifacts.js

@@ -34,6 +34,7 @@ export class LocalWebSourceLocationArtifacts {
                 operation: "trace_web_source_location",
                 field: ["source_map", "path"],
                 targetPath: input.source_map.path,
+                callerSelected: true,
             }, options?.signal));
         }
     }

package/dist/browser/execution/CdpExecutionCapture.js

@@ -69,9 +69,9 @@ export const captureWebExecution = async (input, sources) => {
         sources.check();
         const verifiedRequests = requests.result();
         const verifiedMainScripts = mainScripts.filter((id) => sources.belongsToDocument(id));
-        const sample = raw === undefined
-            ? undefined
-            : normalizePreciseCoverage(raw, sources, retained);
+        const sample = parsed?.success === true
+            ? normalizePreciseCoverage(parsed.data, sources, retained)
+            : undefined;
         await session.options.progress?.report({
             phase: "browser_execution",
             completed: 2,

package/dist/browser/execution/CdpPreciseCoverage.js

@@ -1,18 +1,15 @@
 import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
-import { preciseCoverageSchema } from "./CdpRuntimeProtocol.js";
 /** Validate source-range bounds against exact retained UTF-16 text without flattening nested counts. */
-export const normalizePreciseCoverage = (raw, sources, retained) => {
-    const parsed = preciseCoverageSchema.safeParse(raw);
-    if (!parsed.success)
-        throw new AnalysisOutputError(sources.session.operation, `Malformed precise coverage: ${parsed.error.message}`);
+export const normalizePreciseCoverage = (parsed, sources, retained) => {
+    const retainedSources = new Map(retained.map(({ script_id, source }) => [script_id, source]));
     const scripts = [];
     let excluded = 0;
-    for (const script of parsed.data.result) {
+    for (const script of parsed.result) {
         if (!sources.belongsToDocument(script.scriptId)) {
             excluded += 1;
             continue;
         }
-        const source = retained.find((item) => item.script_id === script.scriptId)?.source;
+        const source = retainedSources.get(script.scriptId);
         scripts.push({
             script_id: script.scriptId,
             reported_url: sources.sourceUrl(script.scriptId, script.url),
@@ -35,7 +32,7 @@ export const normalizePreciseCoverage = (raw, sources, retained) => {
         });
     }
     return {
-        timestamp: parsed.data.timestamp,
+        timestamp: parsed.timestamp,
         coverage: {
             state: "captured",
             reason: null,

package/dist/browser/history/HarCapture.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { TextDecoder } from "node:util";
 import { isSafeNumber, LosslessNumber } from "lossless-json";
 import { parseHarJson } from "./HarJson.js";
 import { WEB_NETWORK_CAPTURE_LIMITS, } from "../../domain/webNetworkCapture.js";
@@ -6,6 +7,19 @@ import { CaptureFormatError } from "./CaptureFormatError.js";
 import { CaptureRedaction, captureObject, capturePointer, } from "./CaptureRedaction.js";
 import { createHarValidator } from "./HarSchema.js";
 import { HAR_CAPTURE_PROVIDER_IDENTITY } from "./CaptureRelease.js";
+/**
+ * Decode retained HAR bytes as UTF-8. HAR 1.2 lets writers emit a byte-order
+ * mark and requires readers to ignore it, so one leading BOM is skipped.
+ */
+export const decodeHarText = (bytes) => {
+    try {
+        // ignoreBOM: false (the default) is what skips the mark; true keeps it.
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new CaptureFormatError("format", "HAR is not valid UTF-8 JSON.");
+    }
+};
 /** Decode a retained HAR with exact numeric lexemes and unchanged upstream schema validation. */
 export const decodeHarCapture = (text, sensitiveValues) => {
     const raw = parseHarJson(text);

package/dist/browser/history/HarCaptureProcess.js

@@ -1,10 +1,9 @@
 import { readFile, writeFile } from "node:fs/promises";
-import { TextDecoder } from "node:util";
 import { z } from "zod";
 import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
 import { WEB_NETWORK_CAPTURE_LIMITS } from "../../domain/webNetworkCapture.js";
 import { CaptureFormatError } from "./CaptureFormatError.js";
-import { decodeHarCapture } from "./HarCapture.js";
+import { decodeHarCapture, decodeHarText } from "./HarCapture.js";
 const requestSchema = z.strictObject({
     snapshot_path: z.string(),
     reply_path: z.string(),
@@ -16,16 +15,9 @@ const main = async () => {
     let reply;
     try {
         const snapshot = await readStableArtifact(request.snapshot_path, WEB_NETWORK_CAPTURE_LIMITS.inputBytes);
-        let text;
-        try {
-            text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(snapshot.bytes);
-        }
-        catch {
-            throw new CaptureFormatError("format", "HAR is not valid UTF-8 JSON.");
-        }
         reply = {
             ok: true,
-            value: decodeHarCapture(text, request.sensitive_values),
+            value: decodeHarCapture(decodeHarText(snapshot.bytes), request.sensitive_values),
         };
     }
     catch (cause) {

package/dist/browser/history/MitmproxyCaptureAdapter.js

@@ -1,4 +1,4 @@
-import { access } from "node:fs/promises";
+import { access, stat } from "node:fs/promises";
 import { constants } from "node:fs";
 import { isAbsolute } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -22,6 +22,8 @@ export class MitmproxyCaptureAdapter {
             throw new AnalysisCapabilityUnavailableError("mitmproxy", OPERATION, MITMDUMP_REQUIREMENT, { userMessage: MITMDUMP_REQUIREMENT });
         try {
             await access(command, constants.R_OK | constants.X_OK);
+            if (!(await stat(command)).isFile())
+                throw new TypeError("Configured path is not a regular file");
         }
         catch (cause) {
             const reason = `Configured mitmdump executable is unavailable: ${command}.`;

package/dist/browser/modules/WebModuleArtifacts.js

@@ -34,6 +34,7 @@ export class LocalWebModuleArtifacts {
                 operation: "trace_web_module_imports",
                 field: ["import_map", "path"],
                 targetPath: selected.path,
+                callerSelected: true,
             }, options?.signal));
         }
     }