rea-agents 6.1.0 → 6.3.0

package/dist/artifacts/inventory/scanCanonical.js

@@ -1,53 +1,79 @@
-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 = {}) => {
+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 reader = await createReader(path, rootFormat, 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);
-        return await buildInventorySnapshot({
-            path,
-            metadata,
-            rootFormat,
-            rootDigest,
-            reader,
-            signal: options.signal,
-            nodes,
-            occurrences,
-            pendingContradictions,
-        });
+        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({
+                path,
+                metadata,
+                rootFormat,
+                rootDigest,
+                reader,
+                signal: options.signal,
+                nodes,
+                occurrences,
+                pendingContradictions,
+            }),
+        };
     }
-    finally {
-        await reader?.close();
+    catch (cause) {
+        outcome = { kind: "failed", cause };
     }
+    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;
 };
 const buildInventorySnapshot = async (input) => {
     const { path, metadata, rootFormat, rootDigest, reader, signal } = input;
     materializeDirectoryNodes(input.occurrences, input.nodes);
     const rootNode = createRootNode({
-        path,
-        format: rootFormat,
-        directory: metadata.isDirectory(),
         digest: rootDigest,
         occurrences: input.occurrences,
     });
     input.nodes.set(rootNode.artifact_id, rootNode);
     rekeyOccurrences(rootNode.artifact_id, input.occurrences);
-    const rootOccurrence = rootOccurrenceFor(rootNode, metadata.size);
+    const rootOccurrence = rootOccurrenceFor(rootNode, {
+        size: metadata.size,
+        executable: (metadata.mode & 0o111) !== 0,
+        format: rootFormat,
+        path,
+    });
     for (const occurrence of input.occurrences)
         if (occurrence.parent_occurrence_id === null)
             occurrence.parent_occurrence_id = rootOccurrence.occurrence_id;
@@ -61,7 +87,10 @@ const buildInventorySnapshot = async (input) => {
     const edges = createArtifactEdges(rootNode.artifact_id, input.occurrences, reader?.provenance()[0]);
     const orderedNodes = sortNodes([...input.nodes.values()]);
     const orderedOccurrences = sortOccurrences(input.occurrences);
-    const orderedEdges = sortEdges(edges);
+    const orderedEdges = sortEdges(edges).map((edge, ordinal) => ({
+        ...edge,
+        ordinal,
+    }));
     await verifyRootDigest(path, rootDigest, signal);
     const graphSha256 = artifactGraphDigest({
         nodes: orderedNodes,
@@ -71,6 +100,7 @@ const buildInventorySnapshot = async (input) => {
     });
     const manifest = buildManifest({
         rootNode,
+        rootFormat,
         graphSha256,
         orderedNodes,
         orderedOccurrences,
@@ -118,19 +148,19 @@ 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) => left.artifact_id.localeCompare(right.artifact_id));
-const sortOccurrences = (occurrences) => occurrences.sort((left, right) => left.logical_path.localeCompare(right.logical_path, "en"));
-const sortEdges = (edges) => edges.sort((left, right) => left.edge_id.localeCompare(right.edge_id));
-const buildManifest = ({ rootNode, graphSha256, orderedNodes, orderedOccurrences, orderedEdges, }) => artifactInventoryResultSchema.shape.manifest.parse({
+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,
     root_sha256: rootNode.sha256,
-    root_format: rootNode.format,
+    root_format: rootFormat,
     graph_sha256: graphSha256,
     node_count: orderedNodes.length,
     occurrence_count: orderedOccurrences.length,

package/dist/artifacts/inventory/scanReader.js

@@ -2,12 +2,12 @@ import { isAbsolute } from "node:path";
 import { ArtifactPathRegistry, normalizeArtifactPath, } from "../ArtifactPaths.js";
 import { ArtifactReaderFailure, } from "../ArtifactReader.js";
 import { AsarArtifactReader } from "../AsarArtifactReader.js";
-import { classifyArtifactContent, createArtifactNode, createOccurrence, nearestParent, } from "./ArtifactGraphConstruction.js";
+import { classifyArtifactContent, classifyArtifactBytes, createArtifactNode, createOccurrence, nearestParent, } from "./ArtifactGraphConstruction.js";
 import { STRICT_INTEGRITY_POLICY, } from "./types.js";
 import { hashReadable } from "../ArtifactHash.js";
 const UNAVAILABLE_UNPACKED_LIMITATION = "ASAR unpacked companion bytes were unavailable; no content hash or child artifact was produced.";
 const emptyScan = () => ({ nodes: new Map(), occurrences: [], pendingContradictions: [] });
-export const scanReader = async (reader, signal, integrity = STRICT_INTEGRITY_POLICY) => {
+export const scanReader = async (reader, ownedReaders, signal, integrity = STRICT_INTEGRITY_POLICY) => {
     const { nodes, occurrences, pendingContradictions } = emptyScan();
     if (reader === undefined)
         return { nodes, occurrences, pendingContradictions };
@@ -21,6 +21,7 @@ export const scanReader = async (reader, signal, integrity = STRICT_INTEGRITY_PO
         occurrenceByPath: new Map(),
         registry: new ArtifactPathRegistry(),
         expandedContainerIds: new Set(),
+        ownedReaders,
     };
     await visitArtifactEntries(context, reader, "");
     // Archive directories may appear after their children. Resolve containment
@@ -36,7 +37,6 @@ const visitArtifactEntries = async (context, currentReader, prefix) => {
             reader: currentReader,
             prefix,
             iterator: currentReader.entries(context.signal)[Symbol.asyncIterator](),
-            owned: false,
         },
     ];
     try {
@@ -47,8 +47,6 @@ const visitArtifactEntries = async (context, currentReader, prefix) => {
             const next = await frame.iterator.next();
             if (next.done) {
                 stack.pop();
-                if (frame.owned)
-                    await frame.reader.close();
                 continue;
             }
             const entry = next.value;
@@ -71,6 +69,8 @@ const visitArtifactEntries = async (context, currentReader, prefix) => {
             if (digested !== undefined) {
                 context.nodes.set(digested.node.artifact_id, digested.node);
                 occurrence.artifact_id = digested.node.artifact_id;
+                occurrence.artifact_kind = digested.classification.kind;
+                occurrence.artifact_format = digested.classification.format;
                 occurrence.hash_status = digested.mismatched
                     ? "mismatched"
                     : "verified";
@@ -79,26 +79,24 @@ const visitArtifactEntries = async (context, currentReader, prefix) => {
             }
             context.occurrences.push(occurrence);
             context.occurrenceByPath.set(logicalPath, occurrence);
-            if (expandableAsar && digested?.mismatched !== true) {
+            if (expandableAsar && digested !== undefined && !digested.mismatched) {
                 const nested = new AsarArtifactReader(entry.adapterKey);
+                context.ownedReaders.push(nested);
+                await nested.prepareContainer(digested.node.sha256, context.signal);
                 // Only traversed containers can own members, not opaque ASAR-named files.
                 context.expandedContainerIds.add(occurrence.occurrence_id);
                 stack.push({
                     reader: nested,
                     prefix: logicalPath,
                     iterator: nested.entries(context.signal)[Symbol.asyncIterator](),
-                    owned: true,
                 });
             }
         }
     }
     finally {
-        await Promise.allSettled(stack
-            .filter(({ owned }) => owned)
-            .map(async ({ reader, iterator }) => {
+        // Readers remain owned by the inventory until its complete observation is built.
+        for (const { iterator } of stack)
             await iterator.return?.();
-            await reader.close();
-        }));
     }
 };
 const digestArtifactEntry = async (context, currentReader, entry, logicalPath) => {
@@ -129,17 +127,11 @@ const digestArtifactEntry = async (context, currentReader, entry, logicalPath) =
         node: createArtifactNode({
             sha256: digest.sha256,
             size: digest.bytes,
-            kind: classified.kind,
-            format: classified.format,
-            executable: entry.executable,
+            format: classifyArtifactBytes(digest.prefix, digest.bytes),
             contentState: "embedded",
-            limitations: mismatched
-                ? [
-                    "Observed content contradicts declared integrity metadata and is untrusted.",
-                ]
-                : [],
         }),
         mismatched,
+        classification: classified,
     };
 };
 const isExpandableAsar = (entry, logicalPath) => entry.kind === "file" &&

package/dist/artifacts/javascript/JavaScriptArtifactFiles.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { isAbsolute } from "node:path";
-import { compareCodePoints } from "../../domain/canonicalOrdering.js";
+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
 import { AsarArtifactReader } from "../AsarArtifactReader.js";
 import { ArtifactPathRegistry, normalizeArtifactPath, } from "../ArtifactPaths.js";
 import { ArtifactReaderFailure, } from "../ArtifactReader.js";
@@ -12,7 +12,7 @@ export const readJavaScriptArtifactFiles = async (reader, snapshot, signal) => {
         const root = snapshot.nodes.find(({ artifact_id }) => artifact_id === snapshot.manifest.root_artifact_id);
         if (root === undefined)
             throw new ArtifactReaderFailure("integrity", "Root artifact node is missing");
-        await verifyEntryBytes(reader.openContainer(signal), { path: ".", sha256: root.sha256, bytes: root.size }, signal);
+        await verifyEntryBytes(await reader.openContainer(signal), { path: ".", sha256: root.sha256, bytes: root.size }, signal);
     }
     const inventory = expectedInventory(snapshot);
     const expected = inventory.files;
@@ -27,11 +27,11 @@ export const readJavaScriptArtifactFiles = async (reader, snapshot, signal) => {
         invalidUtf8: 0,
     };
     await visitReader(reader, "", snapshot.manifest.root_sha256, context);
-    const files = context.files.sort((left, right) => compareCodePoints(left.path, right.path));
+    const files = context.files.sort((left, right) => compareUnicodeCodePoints(left.path, right.path));
     assertExpectedFilesWereVisited(expected, files);
     return {
         files,
-        containers: context.containers.sort((left, right) => compareCodePoints(left.path, right.path)),
+        containers: context.containers.sort((left, right) => compareUnicodeCodePoints(left.path, right.path)),
         text_bytes_read: context.textBytes,
         invalid_utf8_files: context.invalidUtf8,
     };
@@ -43,9 +43,10 @@ const visitReader = async (reader, prefix, containerSha256, context) => {
             prefix,
             containerSha256,
             iterator: reader.entries(context.signal)[Symbol.asyncIterator](),
-            owned: false,
         },
     ];
+    const ownedReaders = [];
+    let failure;
     try {
         while (stack.length > 0) {
             const frame = stack.at(-1);
@@ -54,8 +55,6 @@ const visitReader = async (reader, prefix, containerSha256, context) => {
             const next = await frame.iterator.next();
             if (next.done) {
                 stack.pop();
-                if (frame.owned)
-                    await frame.reader.close();
                 continue;
             }
             const entry = next.value;
@@ -64,17 +63,32 @@ const visitReader = async (reader, prefix, containerSha256, context) => {
             const nestedAsar = isFilesystemAsar(entry, path);
             context.registry.add(path, nestedAsar ? "directory" : entry.kind);
             if (nestedAsar) {
-                const inventory = expectedContainer(path, context);
+                const container = context.expectedContainers.get(path);
+                // Inventory deliberately does not expand unverified or unavailable
+                // nested archives. Keep the same boundary here when reconstruction
+                // reads the active entries again.
+                if (container === undefined)
+                    throw new ArtifactReaderFailure("integrity", `Nested ASAR was not present in inventory: ${path}`);
+                if (container.hash_status === "mismatched")
+                    continue;
+                if (container.hash_status === "unavailable")
+                    throw new ArtifactReaderFailure("unavailable", `Nested ASAR bytes were unavailable during inventory: ${path}`);
+                if (container.hash_status !== "verified")
+                    throw new ArtifactReaderFailure("integrity", `Nested ASAR was not integrity-verified: ${path}`);
+                const inventory = container.inventory;
+                if (inventory === null)
+                    throw new ArtifactReaderFailure("integrity", `Verified nested ASAR has no inventory node: ${path}`);
                 await verifyEntryBytes(await frame.reader.open(entry, context.signal), inventory, context.signal);
                 context.containers.push(inventory);
                 const nested = new AsarArtifactReader(entry.adapterKey);
+                ownedReaders.push(nested);
                 stack.push({
                     reader: nested,
                     prefix: path,
                     containerSha256: inventory.sha256,
                     iterator: nested.entries(context.signal)[Symbol.asyncIterator](),
-                    owned: true,
                 });
+                await nested.prepareContainer(inventory.sha256, context.signal);
                 continue;
             }
             const expected = context.expected.get(path);
@@ -97,20 +111,31 @@ const visitReader = async (reader, prefix, containerSha256, context) => {
             });
         }
     }
+    catch (cause) {
+        failure = { cause };
+    }
     finally {
-        await Promise.allSettled(stack
-            .filter(({ owned }) => owned)
-            .map(async ({ reader, iterator }) => {
-            await iterator.return?.();
-            await reader.close();
-        }));
+        for (const { iterator } of stack) {
+            try {
+                await iterator.return?.();
+            }
+            catch (cause) {
+                failure ??= { cause };
+            }
+        }
+        for (const owned of ownedReaders.reverse()) {
+            try {
+                await owned.close();
+            }
+            catch (cause) {
+                failure = {
+                    cause: ArtifactReaderFailure.withCleanup(failure?.cause ?? cause, ArtifactReaderFailure.cleanupObservation(cause, `nested ASAR reader for ${prefix}`)),
+                };
+            }
+        }
     }
-};
-const expectedContainer = (path, context) => {
-    const container = context.expectedContainers.get(path);
-    if (container === undefined)
-        throw new ArtifactReaderFailure("integrity", `Nested ASAR disappeared from inventory: ${path}`);
-    return container;
+    if (failure !== undefined)
+        throw failure.cause;
 };
 const readText = async (context, input) => {
     if (input.expected.kind === "native-addon") {
@@ -155,8 +180,18 @@ const expectedInventory = (snapshot) => {
     const files = new Map();
     const containers = new Map();
     for (const occurrence of snapshot.occurrences) {
-        if (occurrence.artifact_id === null || occurrence.logical_path === ".")
+        if (occurrence.logical_path === ".")
             continue;
+        const isNestedAsar = occurrence.entry_kind === "file" &&
+            occurrence.logical_path.toLowerCase().endsWith(".asar");
+        if (occurrence.artifact_id === null) {
+            if (isNestedAsar)
+                containers.set(occurrence.logical_path, {
+                    hash_status: occurrence.hash_status,
+                    inventory: null,
+                });
+            continue;
+        }
         const node = nodes.get(occurrence.artifact_id);
         if (node === undefined)
             throw new ArtifactReaderFailure("integrity", `Artifact inventory node is missing: ${occurrence.logical_path}`);
@@ -165,12 +200,15 @@ const expectedInventory = (snapshot) => {
         // node_modules/@zip.js remains a graph node and must never be opened.
         if (occurrence.entry_kind !== "file")
             continue;
-        if (occurrence.logical_path.toLowerCase().endsWith(".asar"))
+        if (isNestedAsar)
             containers.set(occurrence.logical_path, {
-                path: occurrence.logical_path,
-                sha256: node.sha256,
-                bytes: node.size,
-                inventory_artifact_id: node.artifact_id,
+                hash_status: occurrence.hash_status,
+                inventory: {
+                    path: occurrence.logical_path,
+                    sha256: node.sha256,
+                    bytes: node.size,
+                    inventory_artifact_id: node.artifact_id,
+                },
             });
         const kind = relevantKind(occurrence.logical_path);
         if (kind === undefined)

package/dist/browser/BrowserScenarioPartialObservation.js

@@ -0,0 +1,106 @@
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { BrowserObservationError } from "../domain/browserObservationError.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY } from "./providerIdentities.js";
+const OPERATION = "capture_browser_scenario";
+const browserScenarioLimitations = (session) => [
+    "Event sequence records provider receipt order; simultaneous browser causality is not inferred.",
+    "Network content is retained only when selected; response bytes are browser-decoded, not compressed wire bytes.",
+    "Request bytes are limited to what Playwright exposes; not_exposed does not establish body absence or multipart file coverage.",
+    "Network content reads settle within 5 seconds each and never wait for unfinished responses or refetch them.",
+    "Playwright scenario events do not expose request initiator stacks; receipt order does not prove causality.",
+    "Storage values are hashed only after declared-secret redaction.",
+    ...(session.eventLimitations?.() ?? []),
+    ...(session.mode === "connect"
+        ? [
+            "CDP attachment cannot recover pre-attach events or guarantee launch-time context options.",
+        ]
+        : []),
+];
+/** Project one session into the common capture fields used by success and failure. */
+export const browserScenarioCaptureData = (input) => ({
+    browser: {
+        mode: input.session.mode,
+        process_ownership: input.session.processOwnership,
+        cleanup: input.cleanup,
+        product: input.session.product,
+        version: input.session.version,
+    },
+    scenario: {
+        start_origin: new URL(input.scenario.start_url.url).origin,
+        action_count: input.scenario.actions.length,
+        secret_references: input.scenario.secrets
+            .map(({ secret_id: id }) => id)
+            .sort(),
+        network_content: input.scenario.capture.network,
+    },
+    duration_ms: Date.now() - input.startedAt,
+    steps: [...input.steps],
+    events: input.session.events(),
+    limitations: [
+        ...browserScenarioLimitations(input.session),
+        ...(input.limitations ?? []),
+    ],
+});
+/** Describe the cleanup failure without discarding its resource evidence. */
+export const browserScenarioCleanupObservation = (cause) => cause instanceof AnalysisError && cause.cleanup !== undefined
+    ? cause.cleanup
+    : {
+        reason: cause instanceof Error ? cause.message : String(cause),
+        resources: cause instanceof AnalysisError && cause.cleanupResources.length > 0
+            ? cause.cleanupResources
+            : ["browser_transport"],
+    };
+/** Retain operation diagnostics and capture data after cleanup settles. */
+export const browserScenarioOperationFailure = (cause, partialObservation, cleanupFailure) => {
+    const primary = cause instanceof AnalysisError
+        ? cause
+        : new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, OPERATION, { cause });
+    const primaryProjection = projectAnalysisError(primary);
+    const cleanupCause = cleanupFailure === undefined
+        ? undefined
+        : cleanupFailure.cause instanceof AnalysisError
+            ? cleanupFailure.cause
+            : new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, "close_browser_scenario", { cause: cleanupFailure.cause });
+    const cleanupObservation = cleanupFailure === undefined
+        ? undefined
+        : browserScenarioCleanupObservation(cleanupFailure.cause);
+    const retainedOptions = {
+        cause: primary,
+        partialObservation,
+        ...(primary.capturedOutput === undefined
+            ? {}
+            : { capturedOutput: primary.capturedOutput }),
+        ...(primary.cleanup === undefined ? {} : { cleanup: primary.cleanup }),
+    };
+    if (cleanupCause === undefined) {
+        if (primary instanceof AnalysisCancelledError)
+            return new AnalysisCancelledError(primary.operation, retainedOptions);
+        if (primary instanceof AnalysisTimeoutError)
+            return new AnalysisTimeoutError(primary.operation, primary.timeoutMs, retainedOptions);
+        if (primary instanceof BrowserObservationError)
+            return new BrowserObservationError(primary.operation, primary.reason, {
+                ...retainedOptions,
+                ...(primary.userMessage === undefined
+                    ? {}
+                    : { detail: primary.userMessage }),
+            });
+    }
+    const cleanup = cleanupObservation ?? primary.cleanup;
+    return new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, OPERATION, {
+        ...retainedOptions,
+        cause: cleanupCause === undefined
+            ? primary
+            : new AggregateError([primary, cleanupCause], "Browser scenario operation and cleanup both failed", { cause: primary }),
+        userMessage: primaryProjection.message,
+        ...(cleanup === undefined ? {} : { cleanup }),
+        diagnostics: {
+            primary_error: primaryProjection,
+            ...(cleanupCause === undefined
+                ? {}
+                : { cleanup_error: projectAnalysisError(cleanupCause) }),
+        },
+    });
+};

package/dist/browser/CdpBrowserProvider.js

@@ -1,4 +1,5 @@
-import { browserTargetListSchema, sanitizeBrowserUrl, webPageInspectionSchema, } from "../domain/browserObservation.js";
+import { sanitizeBrowserUrl, } from "../domain/browserObservation.js";
+import { browserTargetListSchema, webPageInspectionSchema, } from "../domain/browserObservationSchemas.js";
 import { analyzeCapturedWebBundle } from "../domain/webBundleAnalyzer.js";
 import { webBundleAnalysisSchema, } from "../domain/webBundleAnalysis.js";
 import { webObservationSessionSchema, } from "../domain/browserSession.js";
@@ -19,15 +20,12 @@ import { observeCdpSession } from "./CdpObservationSession.js";
 import { discoverWebMcp } from "./CdpWebMcpDiscovery.js";
 import { captureCdpScreenshot } from "./CdpScreenshot.js";
 import { comparePngScreenshots } from "./PngVisualDiff.js";
-/** Public identity committed by passive browser observations. */
-export { CDP_BROWSER_PROVIDER_IDENTITY } from "./providerIdentities.js";
 import { CDP_BROWSER_PROVIDER_IDENTITY } from "./providerIdentities.js";
-const IDENTITY = CDP_BROWSER_PROVIDER_IDENTITY;
 const CLEANUP_DOMAINS = ["Network", "Debugger", "Runtime", "Page"];
 /** Passive browser observation through a selected user-owned CDP endpoint. */
 export class CdpBrowserProvider {
     identity() {
-        return IDENTITY;
+        return CDP_BROWSER_PROVIDER_IDENTITY;
     }
     async listTargets(input, options = {}) {
         try {
@@ -263,4 +261,6 @@ const providerError = (cause, operation) => cause instanceof BrowserObservationE
     ? new BrowserObservationError(operation, cause.reason, { cause })
     : cause instanceof AnalysisError
         ? cause
-        : new ProviderAdapterError(IDENTITY.id, operation, { cause });
+        : new ProviderAdapterError(CDP_BROWSER_PROVIDER_IDENTITY.id, operation, {
+            cause,
+        });

package/dist/browser/CdpCaptureEventHandlers.js

@@ -1,6 +1,6 @@
 import { inferJsonShape } from "../domain/jsonShape.js";
 import { safeResponseMetadata } from "./CdpSafeMetadata.js";
-import { allowedSanitizedUrl, isHttpUrl, numberValue, recordValue, recordsValue, cdpStringValue, } from "./CdpCaptureValues.js";
+import { allowedSanitizedUrl, isHttpUrl, numberValue, recordValue, recordsValue, scriptMetadataValues, cdpStringValue, } from "./CdpCaptureValues.js";
 import { requestBodyShape, updateResponseBodyShape, } from "./CdpCaptureEventBodyShapes.js";
 import { consolePrimitive, decodeBase64, exclusionReasonForUrl, executionContextKey, firstCallFrame, initiatorLocation, integerOrNull, isJsonMediaType, isMainFrameNavigation, } from "./CdpCaptureEventHelpers.js";
 import { CDP_CAPTURE_SCRIPT_METADATA_LIMITS, } from "./CdpCaptureEventTypes.js";
@@ -44,9 +44,7 @@ export const handleScriptParsed = (state, params) => {
         rawUrl,
         url: sanitized.url,
         origin: sanitized.origin,
-        hash: cdpStringValue(params.hash) ?? "",
-        length: Math.max(0, Math.min(Number.MAX_SAFE_INTEGER, Math.trunc(numberValue(params.length) ?? 0))),
-        isModule: params.isModule === true,
+        ...scriptMetadataValues(params),
         language: cdpStringValue(params.scriptLanguage) ?? null,
         executionContextKey: executionContextKey(params.executionContextId),
     };

package/dist/browser/CdpCaptureEvents.js

@@ -3,7 +3,6 @@ import * as bodyShapes from "./CdpCaptureEventBodyShapes.js";
 import * as handlers from "./CdpCaptureEventHandlers.js";
 import { isJsonMediaType } from "./CdpCaptureEventHelpers.js";
 import { recordValue } from "./CdpCaptureValues.js";
-export {} from "./CdpCaptureEventTypes.js";
 /** Event accumulator that validates and normalizes payloads at ingestion. */
 export class CdpCaptureEvents {
     #scriptMetadataBudgetExclusionsRecorded = false;

package/dist/browser/CdpCaptureStorageFingerprints.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
-import { compareCodePoints } from "../domain/canonicalOrdering.js";
+import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
 import { CdpConnection } from "./CdpConnection.js";
 import { optionalCdpCommand } from "./CdpOptionalCommand.js";
 import { recordValue, recordsValue, cdpStringValue, } from "./CdpCaptureValues.js";
@@ -16,7 +16,7 @@ export const captureStorageFingerprints = async ({ context, origin, cookieUrl, l
     await addCookies(run, cookieUrl);
     await addIndexedDb(run, origin, indexedDbNames);
     await addCaches(run, caches);
-    state.items.sort((left, right) => compareCodePoints(`${left.scope}:${left.identity_sha256}`, `${right.scope}:${right.identity_sha256}`));
+    state.items.sort((left, right) => compareUnicodeCodePoints(`${left.scope}:${left.identity_sha256}`, `${right.scope}:${right.identity_sha256}`));
     const complete = state.complete && state.items.every(({ complete }) => complete);
     return { items: state.items, complete };
 };
@@ -282,7 +282,7 @@ const stableValue = (value) => {
         return String(value);
     return Object.fromEntries(Object.entries(record)
         .filter(([key]) => key !== "objectId" && key !== "customPreview")
-        .sort(([left], [right]) => compareCodePoints(left, right))
+        .sort(([left], [right]) => compareUnicodeCodePoints(left, right))
         .map(([key, item]) => [key, stableValue(item)]));
 };
 const stableValueComplete = (value) => {

package/dist/browser/CdpCaptureValues.js

@@ -13,12 +13,32 @@ export const recordsValue = (value) => Array.isArray(value)
     : [];
 export const cdpStringValue = (value) => typeof value === "string" ? value : undefined;
 export const numberValue = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+/** Preserve partial script declarations; omitted or invalid fields remain unknown. */
+export const scriptMetadataValues = (value) => {
+    const length = numberValue(value?.length);
+    return {
+        hash: cdpStringValue(value?.hash) ?? null,
+        length: length !== undefined && Number.isSafeInteger(length) && length >= 0
+            ? length
+            : null,
+        isModule: typeof value?.isModule === "boolean" ? value.isModule : null,
+    };
+};
 export const requiredRecord = (value) => {
     const record = recordValue(value);
     if (record === undefined)
         throw new BrowserObservationError("inspect_web_page", "protocol_error");
     return record;
 };
+/** Require producer source text; an absent source is distinct from an empty script. */
+export const requiredScriptSource = (value, operation) => {
+    const source = cdpStringValue(recordValue(value)?.scriptSource);
+    if (source === undefined)
+        throw new BrowserObservationError(operation, "protocol_error", {
+            detail: "Debugger.getScriptSource returned malformed source text: scriptSource must be a string.",
+        });
+    return source;
+};
 export const isHttpUrl = (value) => {
     if (value === undefined)
         return false;