rea-agents 6.0.0 → 6.2.0

package/dist/domain/artifactGraph.js

@@ -55,6 +55,19 @@ const artifactFormatSchema = z.enum([
     "file",
     "unknown",
 ]);
+/** Formats established from bytes or a virtual directory tree, independent of path roles. */
+const artifactContentFormatSchema = artifactFormatSchema.extract([
+    "zip",
+    "mach-o-universal",
+    "mach-o",
+    "elf",
+    "pe",
+    "dos-mz",
+    "plist",
+    "directory",
+    "file",
+    "unknown",
+]);
 /** File byte interval for an artifact derived without writing it to disk. */
 const artifactByteRangeSchema = z.object({
     offset: z.number().int().min(0),
@@ -72,13 +85,11 @@ const artifactCommandSchema = z.object({
 /** One content-addressed application artifact in deterministic manifest order. */
 const artifactNodeSchema = z.object({
     artifact_id: artifactIdSchema,
-    kind: artifactKindSchema,
-    format: artifactFormatSchema,
+    format: artifactContentFormatSchema,
     sha256: sha256Schema,
     size: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
     media_type: z.string().min(1).nullable(),
     architecture: z.string().min(1).nullable(),
-    executable: z.boolean(),
     content_state: z.enum(["materialized", "embedded", "virtual"]),
     limitations: z.array(z.string()),
 });
@@ -89,6 +100,8 @@ const artifactOccurrenceSchema = z.object({
     parent_occurrence_id: occurrenceIdSchema.nullable(),
     logical_path: boundedRelativePathSchema,
     entry_kind: z.enum(["file", "directory", "symlink", "slice"]),
+    artifact_kind: artifactKindSchema,
+    artifact_format: artifactFormatSchema,
     declared_size: z
         .number()
         .int()

package/dist/domain/artifactIdentity.js

@@ -0,0 +1,29 @@
+import { canonicalDigest } from "./comparisonSemantics.js";
+/** Content-address an artifact independently of where it was observed. */
+export const artifactIdForContent = (sha256) => `art_${canonicalDigest({ sha256 }, "Artifact")}`;
+/** Identify an occurrence by its root and exact logical location. */
+export const occurrenceIdForLocation = (input) => input.logicalPath === "."
+    ? `occ_${canonicalDigest({ root: input.rootArtifactId }, "Artifact")}`
+    : `occ_${canonicalDigest({
+        root_artifact_id: input.rootArtifactId,
+        logical_path: input.logicalPath,
+        entry_kind: input.entryKind,
+    }, "Artifact")}`;
+/** Commit to graph members in the ordering established by the inventory owner. */
+export const artifactGraphDigest = (input) => canonicalDigest({
+    nodes: input.nodes,
+    occurrences: input.occurrences,
+    edges: input.edges,
+    integrity_contradictions: input.contradictions,
+}, "Artifact");
+/** Bind a root artifact to its graph commitment. */
+export const artifactManifestId = (rootArtifactId, graphSha256) => `agm_${canonicalDigest({ root_artifact_id: rootArtifactId, graph_sha256: graphSha256 }, "Artifact")}`;
+/** Identify one integrity disagreement at its observed logical path. */
+export const artifactContradictionId = (input) => `ic_${canonicalDigest({
+    root_artifact_id: input.rootArtifactId,
+    logical_path: input.logicalPath,
+    declared_sha256: input.declaredSha256,
+    observed_sha256: input.observedSha256,
+}, "Artifact")}`;
+/** Identify an edge by its semantic relationship and exact occurrence. */
+export const artifactEdgeId = (semantic) => `edge_${canonicalDigest(semantic, "Artifact")}`;

package/dist/domain/artifactInventoryEvidence.js

@@ -1,8 +1,9 @@
 import { artifactInventoryResultSchema, } from "./artifactGraph.js";
-import { canonicalDigest, canonicalJson } from "./comparisonSemantics.js";
+import { compareCodePoints } from "./canonicalOrdering.js";
+import { canonicalJson } from "./comparisonSemantics.js";
+import { artifactContradictionId, artifactEdgeId, artifactGraphDigest, artifactIdForContent, artifactManifestId, occurrenceIdForLocation, } from "./artifactIdentity.js";
 import { parseEvidence } from "./evidence.js";
 import { artifactInspectionResultSchema } from "./artifactInspection.js";
-import { err, ok } from "./result.js";
 /** Parse, merge, and verify inventory Evidence pages. */
 export const parseArtifactInventoryEvidence = (input) => assembleInventorySet((Array.isArray(input) ? input : [input]).map((value) => {
     const evidence = parseEvidence(value);
@@ -29,21 +30,9 @@ const validateInventoryPage = (inventory) => {
     assertUnique(inventory.occurrences.map(({ logical_path: path }) => path), "logical path");
     assertUnique(inventory.edges.map(({ edge_id: id }) => id), "edge ID");
     for (const node of inventory.nodes)
-        if (node.artifact_id !==
-            `art_${canonicalDigest({ sha256: node.sha256 }, "Artifact inventory")}`)
+        if (node.artifact_id !== artifactIdForContent(node.sha256))
             throw new TypeError("Artifact node ID is not content-addressed");
 };
-/**
- * Result-returning seam for the empty-pages leaf. Other assembly failures
- * still throw TypeError (migration in progress); parseArtifactInventoryEvidence
- * keeps its throwing contract until callers switch.
- */
-export const tryAssembleInventorySet = (pages) => pages.length === 0
-    ? err({
-        code: "empty",
-        message: "Artifact inventory requires Evidence pages",
-    })
-    : ok(assembleInventorySet(pages));
 const assembleInventorySet = (pages) => {
     const first = pages[0];
     if (first === undefined)
@@ -79,9 +68,9 @@ const assembleInventorySet = (pages) => {
     return { evidence: pages.map(({ evidence }) => evidence), inventory };
 };
 const orderedInventory = (first, pages, values) => {
-    const nodes = [...values.nodes.values()].sort((left, right) => left.artifact_id.localeCompare(right.artifact_id));
-    const occurrences = [...values.occurrences.values()].sort((left, right) => left.logical_path.localeCompare(right.logical_path, "en"));
-    const edges = [...values.edges.values()].sort((left, right) => left.edge_id.localeCompare(right.edge_id));
+    const nodes = [...values.nodes.values()].sort((left, right) => compareCodePoints(left.artifact_id, right.artifact_id));
+    const occurrences = [...values.occurrences.values()].sort((left, right) => compareCodePoints(left.logical_path, right.logical_path));
+    const edges = [...values.edges.values()].sort((left, right) => compareCodePoints(left.edge_id, right.edge_id));
     return {
         manifest: first.manifest,
         nodes,
@@ -90,7 +79,7 @@ const orderedInventory = (first, pages, values) => {
         integrityContradictions: first.integrity_contradictions,
         limitations: [
             ...new Set(pages.flatMap(({ inventory }) => inventory.limitations)),
-        ].sort((left, right) => left.localeCompare(right)),
+        ].sort(compareCodePoints),
         complete: nodes.length === first.manifest.node_count &&
             occurrences.length === first.manifest.occurrence_count &&
             edges.length === first.manifest.edge_count,
@@ -102,6 +91,10 @@ const validateCompleteInventory = (inventory) => {
     const rootNode = inventory.nodes.find(({ artifact_id: id }) => id === inventory.manifest.root_artifact_id);
     if (rootNode?.sha256 !== inventory.manifest.root_sha256)
         throw new TypeError("Artifact root node does not match its manifest digest");
+    const rootOccurrence = inventory.occurrences.find(({ logical_path }) => logical_path === ".");
+    if (rootOccurrence?.artifact_id !== inventory.manifest.root_artifact_id ||
+        rootOccurrence.artifact_format !== inventory.manifest.root_format)
+        throw new TypeError("Artifact root occurrence does not match its manifest representation");
     for (const occurrence of inventory.occurrences)
         validateOccurrence(occurrence, inventory, nodeIds, occurrenceIds);
     for (const edge of inventory.edges)
@@ -110,27 +103,24 @@ const validateCompleteInventory = (inventory) => {
         if (!nodeIds.has(contradiction.parent_artifact_id) ||
             !occurrenceIds.has(contradiction.occurrence_id))
             throw new TypeError("Integrity contradiction references a missing graph member");
-        const expectedId = `ic_${canonicalDigest({
-            root_artifact_id: inventory.manifest.root_artifact_id,
-            logical_path: contradiction.logical_path,
-            declared_sha256: contradiction.declared_sha256,
-            observed_sha256: contradiction.observed_sha256,
-        }, "Artifact inventory")}`;
+        const expectedId = artifactContradictionId({
+            rootArtifactId: inventory.manifest.root_artifact_id,
+            logicalPath: contradiction.logical_path,
+            declaredSha256: contradiction.declared_sha256,
+            observedSha256: contradiction.observed_sha256,
+        });
         if (contradiction.contradiction_id !== expectedId)
             throw new TypeError("Integrity contradiction ID does not match its identity");
     }
-    const graphSha256 = canonicalDigest({
+    const graphSha256 = artifactGraphDigest({
         nodes: inventory.nodes,
         occurrences: inventory.occurrences,
         edges: inventory.edges,
-        integrity_contradictions: inventory.integrityContradictions,
-    }, "Artifact inventory");
+        contradictions: inventory.integrityContradictions,
+    });
     if (graphSha256 !== inventory.manifest.graph_sha256)
         throw new TypeError("Artifact graph commitment does not match its members");
-    const manifestId = `agm_${canonicalDigest({
-        root_artifact_id: inventory.manifest.root_artifact_id,
-        graph_sha256: graphSha256,
-    }, "Artifact inventory")}`;
+    const manifestId = artifactManifestId(inventory.manifest.root_artifact_id, graphSha256);
     if (manifestId !== inventory.manifest.manifest_id)
         throw new TypeError("Artifact manifest ID does not match its commitment");
 };
@@ -140,13 +130,11 @@ const validateOccurrence = (occurrence, inventory, nodeIds, occurrenceIds) => {
     if (occurrence.parent_occurrence_id !== null &&
         !occurrenceIds.has(occurrence.parent_occurrence_id))
         throw new TypeError("Artifact occurrence references a missing parent");
-    const expectedId = occurrence.logical_path === "."
-        ? `occ_${canonicalDigest({ root: inventory.manifest.root_artifact_id }, "Artifact inventory")}`
-        : `occ_${canonicalDigest({
-            root_artifact_id: inventory.manifest.root_artifact_id,
-            logical_path: occurrence.logical_path,
-            entry_kind: occurrence.entry_kind,
-        }, "Artifact inventory")}`;
+    const expectedId = occurrenceIdForLocation({
+        rootArtifactId: inventory.manifest.root_artifact_id,
+        logicalPath: occurrence.logical_path,
+        entryKind: occurrence.entry_kind,
+    });
     if (occurrence.occurrence_id !== expectedId)
         throw new TypeError("Artifact occurrence ID does not match its identity");
 };
@@ -162,7 +150,7 @@ const validateEdge = (edge, nodeIds, occurrenceIds) => {
         occurrence_id: edge.occurrence_id,
         logical_path: edge.logical_path,
     };
-    if (edge.edge_id !== `edge_${canonicalDigest(semantic, "Artifact inventory")}`)
+    if (edge.edge_id !== artifactEdgeId(semantic))
         throw new TypeError("Artifact edge ID does not match its identity");
 };
 const mergeExact = (output, key, value, label) => {

package/dist/domain/artifactOperationError.js

@@ -1,4 +1,4 @@
-import { AnalysisError } from "./analysisErrorBase.js";
+import { AnalysisError, } from "./analysisErrorBase.js";
 /** Artifact inventory or extraction failed a typed safety boundary. */
 export class ArtifactOperationError extends AnalysisError {
     operation;
@@ -8,10 +8,10 @@ export class ArtifactOperationError extends AnalysisError {
     _tag = "ArtifactOperationError";
     constructor(operation, reason, artifactDetails, 
     /** The specific constraint that failed, such as the colliding path. */
-    detail) {
+    detail, options) {
         super(artifactDetails === undefined
             ? `Artifact ${operation} failed: ${reason}`
-            : `Artifact ${operation} failed: ${reason} at ${artifactDetails.logicalPath} (declared_sha256=${artifactDetails.declaredSha256 ?? "unavailable"}, calculated_sha256=${artifactDetails.calculatedSha256 ?? "unavailable"}, unpacked=${String(artifactDetails.unpacked)})`);
+            : `Artifact ${operation} failed: ${reason} at ${artifactDetails.logicalPath} (declared_sha256=${artifactDetails.declaredSha256 ?? "unavailable"}, calculated_sha256=${artifactDetails.calculatedSha256 ?? "unavailable"}, unpacked=${String(artifactDetails.unpacked)})`, options);
         this.operation = operation;
         this.reason = reason;
         this.artifactDetails = artifactDetails;

package/dist/domain/artifactPartialObservation.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/artifactPathSyntax.js

@@ -24,3 +24,52 @@ export const stripQueryAndFragment = (value) => value.split("#", 1)[0]?.split("?
 export const admitsCanonicalPathSyntax = (value) => !value.includes("\0") &&
     !value.includes("\\") &&
     !/%(?:2e|2f|5c)/iu.test(value);
+/** C0 controls and space, which the URL parser strips around its input. */
+const isUrlTrimmed = (code) => code <= 0x20;
+/**
+ * The URL text a browser parses from an HTML URL attribute: HTML strips
+ * surrounding ASCII whitespace, and the URL parser strips surrounding C0
+ * controls and spaces and removes every tab and newline.
+ */
+export const htmlUrlText = (value) => {
+    let start = 0;
+    let end = value.length;
+    while (start < end && isUrlTrimmed(value.charCodeAt(start)))
+        start += 1;
+    while (end > start && isUrlTrimmed(value.charCodeAt(end - 1)))
+        end -= 1;
+    return value.slice(start, end).replace(/[\t\n\r]/gu, "");
+};
+const UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+const UTF8_ENCODER = new TextEncoder();
+/**
+ * Percent-decode a URL path as the URL standard does: valid `%XX` sequences
+ * become bytes and any other `%` stays literal. Returns null when the bytes
+ * are not UTF-8 or include NUL, because no canonical artifact path can match
+ * them. Callers refuse encoded dot and separator bytes before decoding.
+ */
+export const percentDecodeUrlPath = (value) => {
+    if (!/%[0-9a-f]{2}/iu.test(value))
+        return value;
+    const bytes = [];
+    for (let index = 0; index < value.length;) {
+        const escape = value.slice(index, index + 3);
+        if (/^%[0-9a-f]{2}$/iu.test(escape)) {
+            bytes.push(Number.parseInt(escape.slice(1), 16));
+            index += 3;
+            continue;
+        }
+        const character = String.fromCodePoint(value.codePointAt(index) ?? 0);
+        bytes.push(...UTF8_ENCODER.encode(character));
+        index += character.length;
+    }
+    try {
+        const decoded = UTF8.decode(new Uint8Array(bytes));
+        return decoded.includes("\0") ? null : decoded;
+    }
+    catch (cause) {
+        // Invalid UTF-8 cannot name an inventoried path.
+        void cause;
+        return null;
+    }
+};

package/dist/domain/binaryTarget.js

@@ -7,32 +7,38 @@ import { mzWindowsHeaderOffset, parseDosMzHeader } from "./dosMz.js";
 export const parseExecutableHeader = (bytes, hostArchitecture, fileSize = bytes.length) => {
     if (bytes.length >= 4 &&
         bytes.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])))
-        return parseElf(bytes);
+        return parseElf(bytes, fileSize);
     if (bytes.length >= 2 && bytes[0] === 0x4d && bytes[1] === 0x5a)
         return parseMz(bytes, fileSize);
     if (bytes.length < 8)
         return err("truncated or unsupported binary header");
     const magic = bytes.readUInt32BE(0);
     if ([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic))
-        return parseThinMachO(bytes, magic);
+        return parseThinMachO(bytes, magic, fileSize);
     if ([0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic))
-        return parseFatMachO(bytes, magic, hostArchitecture);
+        return parseFatMachO(bytes, magic, hostArchitecture, fileSize);
     return err("unsupported binary format");
 };
-const parseThinMachO = (bytes, magic) => {
-    if (bytes.length < 8)
-        return err("truncated Mach-O header");
+const parseThinMachO = (bytes, magic, fileSize) => {
+    const is64 = magic === 0xfeedfacf || magic === 0xcffaedfe;
+    const headerSize = is64 ? 32 : 28;
+    if (bytes.length < headerSize)
+        return err(`truncated Mach-O header: a ${is64 ? 64 : 32}-bit header needs ${headerSize} bytes; the file has ${fileSize}`);
     const little = magic === 0xcefaedfe || magic === 0xcffaedfe;
-    const architecture = machArchitecture(little ? bytes.readUInt32LE(4) : bytes.readUInt32BE(4));
+    const read = (offset) => little ? bytes.readUInt32LE(offset) : bytes.readUInt32BE(offset);
+    const architecture = machArchitecture(read(4));
     if (architecture === undefined)
         return err("unsupported Mach-O architecture");
+    const commandBytes = read(20);
+    if (headerSize + commandBytes > fileSize)
+        return err(`truncated Mach-O load commands: the header declares ${commandBytes} bytes after its ${headerSize}-byte header; the file has ${fileSize}`);
     return ok({
         format: "mach-o",
         architecture,
         availableArchitectures: [architecture],
     });
 };
-const parseFatMachO = (bytes, magic, host) => {
+const parseFatMachO = (bytes, magic, host, fileSize) => {
     const little = magic === 0xbebafeca || magic === 0xbfbafeca;
     const is64 = magic === 0xcafebabf || magic === 0xbfbafeca;
     if (bytes.length < 8)
@@ -43,10 +49,24 @@ const parseFatMachO = (bytes, magic, host) => {
     if (count === 0 || count > 128 || bytes.length < 8 + count * entrySize)
         return err("truncated or invalid FAT architecture table");
     const architectures = [];
+    const sliceEnds = new Map();
     for (let index = 0; index < count; index += 1) {
-        const architecture = machArchitecture(read(8 + index * entrySize));
-        if (architecture !== undefined && !architectures.includes(architecture))
-            architectures.push(architecture);
+        const entry = 8 + index * entrySize;
+        const architecture = machArchitecture(read(entry));
+        if (architecture === undefined || architectures.includes(architecture))
+            continue;
+        architectures.push(architecture);
+        const offset = is64
+            ? little
+                ? bytes.readBigUInt64LE(entry + 8)
+                : bytes.readBigUInt64BE(entry + 8)
+            : BigInt(read(entry + 8));
+        const size = is64
+            ? little
+                ? bytes.readBigUInt64LE(entry + 16)
+                : bytes.readBigUInt64BE(entry + 16)
+            : BigInt(read(entry + 12));
+        sliceEnds.set(architecture, offset + size);
     }
     const preferred = host === "arm64"
         ? "arm64"
@@ -59,20 +79,26 @@ const parseFatMachO = (bytes, magic, host) => {
                     : undefined;
     if (preferred === undefined || !architectures.includes(preferred))
         return err(`FAT binary has no host-compatible ${host} architecture`);
+    const sliceEnd = sliceEnds.get(preferred) ?? 0n;
+    if (sliceEnd > BigInt(fileSize))
+        return err(`truncated FAT slice: the ${preferred} slice ends at byte ${sliceEnd}; the file has ${fileSize}`);
     return ok({
         format: "mach-o",
         architecture: preferred,
         availableArchitectures: architectures,
     });
 };
-const parseElf = (bytes) => {
-    if (bytes.length < 20)
+const parseElf = (bytes, fileSize) => {
+    if (bytes.length < 6)
         return err("truncated ELF header");
     if (bytes[4] !== 1 && bytes[4] !== 2)
         return err("unsupported ELF class");
     const little = bytes[5] === 1;
     if (!little && bytes[5] !== 2)
         return err("unsupported ELF endianness");
+    const headerSize = bytes[4] === 1 ? 52 : 64;
+    if (bytes.length < headerSize)
+        return err(`truncated ELF header: an ELF${bytes[4] === 1 ? 32 : 64} header needs ${headerSize} bytes; the file has ${fileSize}`);
     const machine = little ? bytes.readUInt16LE(18) : bytes.readUInt16BE(18);
     const architecture = elfArchitecture(machine);
     if (architecture === undefined)

package/dist/domain/bridgeCandidateProjection.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+/** Coverage metadata for the bounded projection of candidate relationships. */
+export const bridgeCandidateCoverageSchema = z.strictObject({
+    status: z.enum(["complete", "partial"]),
+    total_candidates: z.number().int().nonnegative(),
+    emitted_candidates: z.number().int().nonnegative(),
+    omitted_candidates: z.number().int().nonnegative(),
+});
+// The serialized candidate array is the retained representation; accounting
+// its exact UTF-8 JSON size bounds both array objects and repeated path strings.
+/** Maximum UTF-8 JSON size of a retained candidate array. */
+export const MAX_BRIDGE_CANDIDATE_JSON_BYTES = 2 * 1024 * 1024;
+const jsonText = (value) => {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined)
+        throw new TypeError("Bridge candidate is not JSON serializable");
+    return serialized;
+};
+/** Retain a deterministic prefix of grouped Cartesian candidates within a byte budget. */
+export const projectCartesianCandidates = (input) => {
+    const total = input.groups.reduce((sum, group) => sum + group.left.length * group.right.length, 0);
+    const preparedGroups = input.groups.map((group) => ({
+        left: group.left.map((value) => ({
+            value,
+            pathBytes: Buffer.byteLength(jsonText(value.path)),
+        })),
+        right: group.right.map((value) => {
+            const emptyLeftCandidate = jsonText(input.createCandidate("", value));
+            return {
+                value,
+                rowOverhead: Buffer.byteLength(emptyLeftCandidate) - 2,
+            };
+        }),
+    }));
+    let estimatedFullBytes = 2 + Math.max(0, total - 1); // JSON array brackets and commas.
+    for (const group of preparedGroups) {
+        estimatedFullBytes +=
+            group.left.length *
+                group.right.reduce((sum, { rowOverhead }) => sum + rowOverhead, 0) +
+                group.right.length *
+                    group.left.reduce((sum, { pathBytes }) => sum + pathBytes, 0);
+    }
+    const shouldEmitAll = estimatedFullBytes <= MAX_BRIDGE_CANDIDATE_JSON_BYTES;
+    const candidates = [];
+    let estimatedRetainedBytes = 2;
+    candidateLoop: for (const group of preparedGroups) {
+        for (const left of group.left) {
+            for (const right of group.right) {
+                const candidateBytes = right.rowOverhead + left.pathBytes;
+                const additionalBytes = candidateBytes + (candidates.length > 0 ? 1 : 0);
+                if (!shouldEmitAll &&
+                    estimatedRetainedBytes + additionalBytes >
+                        MAX_BRIDGE_CANDIDATE_JSON_BYTES)
+                    break candidateLoop;
+                candidates.push(input.createCandidate(left.value.path, right.value));
+                estimatedRetainedBytes += additionalBytes;
+            }
+        }
+    }
+    return {
+        candidates,
+        coverage: {
+            status: candidates.length === total
+                ? "complete"
+                : "partial",
+            total_candidates: total,
+            emitted_candidates: candidates.length,
+            omitted_candidates: total - candidates.length,
+        },
+    };
+};

package/dist/domain/browserCaptureComparison.js

@@ -1,41 +1,14 @@
 import { z } from "zod";
-import { browserScenarioDiffSchema, compareBrowserScenarios, compareBrowserScenariosInputSchema, } from "./browserScenarioDiff.js";
-import { compareWebCaptures, captureSnapshotSchema, webCaptureDiffSchema, } from "./webCaptureDiff.js";
-/** Caller-visible object schema for passive and scenario capture comparisons. */
-export const browserCaptureComparisonInputSchema = z
-    .strictObject({
-    before: captureSnapshotSchema
-        .optional()
-        .describe("Earlier passive web-page capture."),
-    after: captureSnapshotSchema
-        .optional()
-        .describe("Later passive web-page capture."),
-    before_scenario: compareBrowserScenariosInputSchema.shape.before_scenario
-        .optional()
-        .describe("Earlier browser scenario capture."),
-    after_scenario: compareBrowserScenariosInputSchema.shape.after_scenario
-        .optional()
-        .describe("Later browser scenario capture."),
-    normalization: compareBrowserScenariosInputSchema.shape.normalization
-        .unwrap()
-        .optional()
-        .describe("Exact-literal normalization policy."),
-})
-    .superRefine((input, context) => {
-    const passive = input.before !== undefined && input.after !== undefined;
-    const scenario = input.before_scenario !== undefined && input.after_scenario !== undefined;
-    const passiveFieldsPresent = input.before !== undefined || input.after !== undefined;
-    const scenarioFieldsPresent = input.before_scenario !== undefined ||
-        input.after_scenario !== undefined ||
-        input.normalization !== undefined;
-    if (passive && !scenarioFieldsPresent)
-        return;
-    if (scenario && !passiveFieldsPresent)
-        return;
-    context.addIssue({
-        code: "custom",
-        message: "Provide before and after passive captures, or before_scenario, after_scenario, and normalization; do not mix comparison types.",
-    });
+import { compareBrowserScenarios } from "./browserScenarioDiff.js";
+import { compareWebCaptures } from "./webCaptureDiff.js";
+import { browserScenarioDiffSchema, compareBrowserScenariosInputSchema, } from "./browserScenarioDiffValues.js";
+import { compareWebCapturesInputSchema, webCaptureDiffSchema, } from "./webCaptureDiffSchemas.js";
+/** Mutually exclusive passive and scenario capture comparison inputs. */
+export const browserCaptureComparisonInputSchema = z.union([compareWebCapturesInputSchema, compareBrowserScenariosInputSchema], {
+    // Standard Schema clients expose the union message, not its branch errors.
+    error: (issue) => issue.code === "invalid_union"
+        ? z.prettifyError(new z.ZodError(issue.errors.flat()))
+        : undefined,
 });
 /** Result from passive page or browser scenario comparison. */
 export const browserCaptureComparisonSchema = z.union([
@@ -43,15 +16,6 @@ export const browserCaptureComparisonSchema = z.union([
     webCaptureDiffSchema,
 ]);
 /** Dispatch a parsed capture comparison to its pure domain comparator. */
-export const compareBrowserCaptures = (input) => isScenarioComparison(input)
-    ? compareBrowserScenarios({
-        ...input,
-        normalization: input.normalization ?? { rules: [] },
-    })
-    : compareWebCaptures(toPassiveComparison(input));
-const isScenarioComparison = (input) => input.before_scenario !== undefined && input.after_scenario !== undefined;
-const toPassiveComparison = (input) => {
-    if (input.before === undefined || input.after === undefined)
-        throw new Error("Validated passive comparison is missing a capture");
-    return { before: input.before, after: input.after };
-};
+export const compareBrowserCaptures = (input) => "before_scenario" in input
+    ? compareBrowserScenarios(input)
+    : compareWebCaptures(input);

package/dist/domain/browserCompleteness.js

@@ -33,6 +33,7 @@ const browserExclusionReasonSchema = z.enum([
     "out_of_target_scope",
     "provider_unavailable",
     "invalid_protocol_value",
+    "resource_budget_exhausted",
 ]);
 const browserExclusionSchema = z.object({
     section: browserSectionSchema,

package/dist/domain/browserNetworkEvidence.js

@@ -1,13 +1,19 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
-/** Caller-selected network content; omission retains metadata alone. */
+/** Resolved network content selection recorded by a capture. */
 export const browserNetworkContentSelectionValuesSchema = z.strictObject({
+    request_body: z.boolean(),
+    response_body: z.boolean(),
+    header_values: z.boolean(),
+});
+/** Caller omission selects metadata alone; individual content facets remain optional. */
+export const browserNetworkContentSelectionSchema = browserNetworkContentSelectionValuesSchema
+    .extend({
     request_body: z.boolean().default(false),
     response_body: z.boolean().default(false),
     header_values: z.boolean().default(false),
-});
-/** Input omission selects metadata without defaulting legacy capture coverage. */
-export const browserNetworkContentSelectionSchema = browserNetworkContentSelectionValuesSchema.default({
+})
+    .default({
     request_body: false,
     response_body: false,
     header_values: false,

package/dist/domain/browserObservation.js

@@ -1,5 +1,4 @@
 import { z } from "zod";
-export { browserTargetListSchema, webPageInspectionSchema, } from "./browserObservationSchemas.js";
 const parseExactOrigin = (value) => {
     let url;
     try {

package/dist/domain/browserObservationError.js

@@ -1,4 +1,4 @@
-import { AnalysisError } from "./analysisErrorBase.js";
+import { AnalysisError, } from "./analysisErrorBase.js";
 import { AnalysisCancelledError } from "./analysisErrorCore.js";
 /** A bounded passive browser observation failed at its CDP boundary. */
 export class BrowserObservationError extends AnalysisError {
@@ -13,13 +13,32 @@ export class BrowserObservationError extends AnalysisError {
         super(`Browser observation ${operation} failed: ${reason}`, options);
         this.operation = operation;
         this.reason = reason;
-        this.userMessage = options?.detail;
-        this.cleanupIncomplete = reason === "cleanup_failed";
+        this.userMessage =
+            options?.detail ?? observationFailureMessage(operation, reason);
+        this.cleanupIncomplete =
+            this.cleanup !== undefined || reason === "cleanup_failed";
         this.cleanupResources =
-            reason === "cleanup_failed" ? ["browser_transport"] : [];
+            this.cleanup?.resources ??
+                (reason === "cleanup_failed" ? ["browser_transport"] : []);
         this.userCategory =
-            reason === "cancelled" || options?.cause instanceof AnalysisCancelledError
+            reason === "cancelled" ||
+                options?.cause instanceof AnalysisCancelledError ||
+                (options?.cause instanceof AnalysisError &&
+                    options.cause.userCategory === "cancelled")
                 ? "cancelled"
                 : undefined;
     }
 }
+const observationFailureMessage = (operation, reason) => {
+    if (reason === "cancelled")
+        return `${operation} was cancelled. Collected observations and cleanup status are reported when available.`;
+    if (reason === "timeout")
+        return `${operation} exceeded its execution deadline. Review the target's responsiveness and retained observations before retrying.`;
+    if (reason === "endpoint_unreachable")
+        return `${operation} could not reach the selected loopback debugging endpoint. Verify that the target process is running with debugging enabled and that the endpoint's port matches it, then retry.`;
+    if (reason === "target_not_found")
+        return `${operation} could not find the selected target at the debugging endpoint. Refresh target discovery for that endpoint and retry with a returned target ID.`;
+    if (reason === "disconnected")
+        return `${operation} lost its debugging connection. Verify that the target process is still running, refresh target discovery, and retry the observation.`;
+    return undefined;
+};

package/dist/domain/browserObservationSchemas.js

@@ -81,9 +81,20 @@ const browserScriptSchema = z.object({
     frame_id: z.string().nullable().default(null),
     url: z.string(),
     origin: z.string().nullable(),
-    cdp_hash: z.string(),
-    length: z.number().int().min(0),
-    is_module: z.boolean(),
+    cdp_hash: z
+        .string()
+        .nullable()
+        .describe("Producer-reported script hash; null when unavailable."),
+    length: z
+        .number()
+        .int()
+        .min(0)
+        .nullable()
+        .describe("Producer-reported script length; null when unavailable."),
+    is_module: z
+        .boolean()
+        .nullable()
+        .describe("Producer-reported module classification; null when unavailable."),
     language: z.string().nullable(),
     source_map_url: z.string().nullable(),
     resource_reconciliation: browserResourceReconciliationSchema,

package/dist/domain/browserScenario.js

@@ -1,6 +1,5 @@
 import { z } from "zod";
 import { browserScenarioActionSchema, browserScenarioBrowserSchema, browserScenarioCaptureSchema, browserScenarioEnvironmentSchema, browserScenarioSecretSchema, browserScenarioStorageSchema, browserScenarioUrlSchema, } from "./browserScenarioValues.js";
-export {} from "./browserScenarioValues.js";
 export const browserScenarioInputSchema = z.strictObject({
     browser: browserScenarioBrowserSchema.describe("Required launch/connect selection. Launch uses the selected executable and an owned temporary profile; connect uses one loopback CDP endpoint and target."),
     start_url: browserScenarioUrlSchema.describe("Required initial HTTP(S) URL. Query values must be declared separately as public literals or secret references."),