rea-agents 4.1.0 → 5.0.0

package/dist/domain/apple/interfaceBuilderKeyedArchive.js

@@ -0,0 +1,411 @@
+import { z } from "zod";
+import { jsonValueSchema } from "../jsonValue.js";
+const recordSchema = z.record(z.string(), z.unknown());
+const objectNode = z.strictObject({
+    id: z.string().min(1),
+    kind: z.enum([
+        "view_controller",
+        "view",
+        "control",
+        "constraint",
+        "layout_guide",
+        "resource",
+        "placeholder",
+        "external_object",
+        "other",
+    ]),
+    class_name: z.string().nullable(),
+    name: z.string().min(1),
+    attributes: z.record(z.string(), jsonValueSchema),
+});
+const connection = z.strictObject({
+    id: z.string().min(1),
+    kind: z.enum(["outlet", "action", "segue", "other"]),
+    source_id: z.string().min(1),
+    destination_id: z.string().nullable(),
+    label: z.string().nullable(),
+    attributes: z.record(z.string(), jsonValueSchema),
+});
+/** Parse ibtool dictionaries or compiled keyed archives into typed records. */
+export const parseInterfaceBuilderRecords = (value) => {
+    const root = record(value);
+    const keyed = parseKeyedArchive(root);
+    if (keyed !== null)
+        return keyed;
+    const objectsRaw = record(root["com.apple.ibtool.document.objects"]);
+    const connectionsRaw = record(root["com.apple.ibtool.document.connections"]);
+    const hierarchyRaw = root["com.apple.ibtool.document.hierarchy"];
+    const classesRaw = record(root["com.apple.ibtool.document.classes"]);
+    const objects = [];
+    const connections = [];
+    let omittedConnections = 0;
+    const objectEntries = Object.entries(objectsRaw);
+    for (const [id, raw] of objectEntries.slice(0, 20_000)) {
+        const attributes = record(raw);
+        const className = firstString(attributes["customClass"], attributes["class"], attributes["isa"]);
+        const label = firstString(attributes["label"], attributes["title"], attributes["name"], className);
+        objects.push(objectNode.parse({
+            id,
+            kind: classifyObject(className),
+            class_name: className,
+            name: label ?? id,
+            attributes: jsonSafeRecord(attributes),
+        }));
+    }
+    for (const [sourceId, rawConnections] of Object.entries(connectionsRaw)) {
+        if (!Array.isArray(rawConnections))
+            continue;
+        for (const [index, raw] of rawConnections.entries()) {
+            if (connections.length >= 40_000) {
+                omittedConnections += rawConnections.length - index;
+                break;
+            }
+            const item = record(raw);
+            const type = firstString(item.type, item.connectionType) ?? "unknown";
+            const destination = firstString(item["destination-id"], item.destinationId);
+            const label = firstString(item.label, item.selector, item.identifier);
+            connections.push(connection.parse({
+                id: `${sourceId}:connection:${index}`,
+                kind: classifyConnection(type),
+                source_id: sourceId,
+                destination_id: destination,
+                label,
+                attributes: jsonSafeRecord(item),
+            }));
+        }
+    }
+    return {
+        objects,
+        connections,
+        hierarchy: Array.isArray(hierarchyRaw) ? hierarchyRaw.slice(0, 20_000) : [],
+        classes: classesRaw,
+        objectCount: objectEntries.length,
+        omittedObjects: Math.max(0, objectEntries.length - 20_000),
+        omittedConnections,
+    };
+};
+/**
+ * A UID decodes as a one-key `UID` (binary) or `CF$UID` (XML) dictionary with
+ * an integer value. Any other dictionary is ordinary archive data.
+ */
+const archiveUid = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    if (Object.keys(value).length !== 1)
+        return undefined;
+    const item = record(value);
+    const marker = Object.hasOwn(item, "UID") ? item.UID : item["CF$UID"];
+    return typeof marker === "number" && Number.isInteger(marker)
+        ? marker
+        : undefined;
+};
+const HIERARCHY_KEY = /(?:subviews|contentview|childviewcontrollers|children|views)$/iu;
+/**
+ * Read an NSKeyedArchiver object table without expanding it into a tree.
+ * Archived objects reference each other freely, including cycles such as a
+ * view and its superview, so inlining every reference grows exponentially.
+ * A reference instead resolves to the referenced string, or to a stub that
+ * names the referenced object; the hierarchy walk visits each object once.
+ */
+const keyedArchiveTable = (objectTable) => {
+    const classNameOf = (value) => {
+        const classReference = record(value).$class;
+        const uid = archiveUid(classReference);
+        return firstString(record(uid === undefined ? classReference : objectTable[uid]).$classname);
+    };
+    /** The string an archived string object holds, if it is one. */
+    const archivedString = (target) => {
+        if (typeof target === "string")
+            return target;
+        const text = record(target)["NS.string"];
+        return typeof text === "string" &&
+            /^NS(?:Mutable)?String$/u.test(classNameOf(target) ?? "")
+            ? text
+            : undefined;
+    };
+    const text = (value) => {
+        const uid = archiveUid(value);
+        return firstString(uid === undefined ? value : archivedString(objectTable[uid]));
+    };
+    const authoredId = (item) => firstString(text(item.objectID), text(item["object-id"]));
+    const reference = (uid) => {
+        // UID 0 is the archived nil.
+        const target = uid === 0 ? null : objectTable[uid];
+        if (target === undefined || target === null)
+            return null;
+        if (typeof target !== "object")
+            return target;
+        const string = archivedString(target);
+        if (string !== undefined)
+            return string;
+        const objectId = authoredId(record(target));
+        return {
+            archiveUID: uid,
+            ...(objectId === null ? {} : { objectID: objectId }),
+            className: classNameOf(target),
+        };
+    };
+    /** Resolve one object's own fields, leaving references to other objects as stubs. */
+    const resolve = (value) => {
+        const uid = archiveUid(value);
+        if (uid !== undefined)
+            return reference(uid);
+        if (Array.isArray(value))
+            return value.map(resolve);
+        if (typeof value !== "object" || value === null)
+            return value;
+        const output = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (key === "$class")
+                output.className = classNameOf(value);
+            else
+                output[key] = resolve(child);
+        }
+        return output;
+    };
+    const hierarchy = (start) => {
+        const visited = new Set();
+        const root = [];
+        const pending = [
+            { value: start, output: root },
+        ];
+        const appendNode = (item, uid, output) => {
+            const objectId = firstString(authoredId(item), text(item.id), uid === undefined ? null : String(uid));
+            if (objectId === null) {
+                for (const [key, child] of Object.entries(item).reverse())
+                    if (HIERARCHY_KEY.test(key))
+                        pending.push({ value: child, output });
+                return;
+            }
+            const children = [];
+            output.push({ objectID: objectId, children });
+            for (const [key, child] of Object.entries(item).reverse())
+                if (HIERARCHY_KEY.test(key))
+                    pending.push({ value: child, output: children });
+        };
+        while (pending.length > 0) {
+            const entry = pending.pop();
+            if (entry === undefined)
+                break;
+            const { value, output } = entry;
+            const uid = archiveUid(value);
+            if (uid !== undefined) {
+                if (visited.has(uid))
+                    continue;
+                visited.add(uid);
+                const target = objectTable[uid];
+                if (Array.isArray(target)) {
+                    for (let index = target.length - 1; index >= 0; index -= 1) {
+                        const child = target[index];
+                        if (child !== undefined)
+                            pending.push({ value: child, output });
+                    }
+                    continue;
+                }
+                if (typeof target !== "object" || target === null)
+                    continue;
+                const item = record(target);
+                if (archivedArrayClass(item.$class)) {
+                    const members = item["NS.objects"];
+                    if (Array.isArray(members))
+                        for (let index = members.length - 1; index >= 0; index -= 1) {
+                            const child = members[index];
+                            if (child !== undefined)
+                                pending.push({ value: child, output });
+                        }
+                    continue;
+                }
+                appendNode(item, uid, output);
+                continue;
+            }
+            if (Array.isArray(value)) {
+                for (let index = value.length - 1; index >= 0; index -= 1) {
+                    const child = value[index];
+                    if (child !== undefined)
+                        pending.push({ value: child, output });
+                }
+            }
+            else if (typeof value === "object" && value !== null) {
+                appendNode(record(value), undefined, output);
+            }
+        }
+        return root;
+    };
+    const archivedArrayClass = (classReference) => {
+        const uid = archiveUid(classReference);
+        const descriptor = record(uid === undefined ? classReference : objectTable[uid]);
+        const classNames = Array.isArray(descriptor.$classes)
+            ? descriptor.$classes.filter((name) => typeof name === "string")
+            : [];
+        return (classNames.includes("NSArray") || classNames.includes("NSMutableArray"));
+    };
+    return { resolve, hierarchy };
+};
+/** Project class and connection objects from an NSKeyedArchiver object table. */
+const parseKeyedArchive = (root) => {
+    if (root.$archiver !== "NSKeyedArchiver" || !Array.isArray(root.$objects))
+        return null;
+    const objectTable = root.$objects;
+    const { resolve, hierarchy: toHierarchy } = keyedArchiveTable(objectTable);
+    const objects = [];
+    const connections = [];
+    let objectCount = 0;
+    let omittedConnections = 0;
+    for (const [index, raw] of objectTable.entries()) {
+        if (index === 0)
+            continue;
+        const resolved = record(resolve(raw));
+        const className = firstString(resolved.className);
+        if (className === null)
+            continue;
+        objectCount += 1;
+        const fields = Object.fromEntries(Object.entries(resolved).filter(([key]) => key !== "className"));
+        const authoredId = firstString(fields.objectID, fields["object-id"]);
+        const objectId = authoredId ??
+            (typeof fields.archiveUID === "number"
+                ? String(fields.archiveUID)
+                : String(index));
+        const kind = classifyObject(className);
+        if (objects.length < 20_000)
+            objects.push(objectNode.parse({
+                id: objectId,
+                kind,
+                class_name: className,
+                name: firstString(fields.label, fields.title, fields.identifier, fields.accessibilityLabel, className) ?? `object ${String(index)}`,
+                attributes: jsonSafeRecord(fields),
+            }));
+        if (/(?:Outlet|Connection|Segue|ActionConnection|ControlConnector)/iu.test(className)) {
+            const controlAction = /ControlConnector/iu.test(className);
+            // AppKit connectors (NSNibOutletConnector, NSNibControlConnector)
+            // archive NSSource as the outlet owner or sending control and
+            // NSDestination as the outlet value or action target, so they are read
+            // in that order without the inversion the unprefixed fields use.
+            const source = firstObjectReference(controlAction ? fields.destination : fields.source, archivedObjectReference(fields.NSSource), controlAction ? fields.to : fields.from, controlAction ? fields.target : fields.owner);
+            if (source === null)
+                continue;
+            const kind = controlAction ? "action" : classifyConnection(className);
+            const parsedConnection = connection.parse({
+                id: `archive:${objectId}`,
+                kind,
+                source_id: source,
+                destination_id: firstObjectReference(controlAction ? fields.source : fields.destination, archivedObjectReference(fields.NSDestination), controlAction ? fields.from : fields.to, controlAction ? fields.owner : fields.target),
+                label: firstString(fields.label, fields.NSLabel, fields.selector, fields.identifier, fields.action),
+                attributes: jsonSafeRecord(fields),
+            });
+            if (connections.length < 40_000)
+                connections.push(parsedConnection);
+            else
+                omittedConnections += 1;
+        }
+    }
+    const top = record(root.$top);
+    const hierarchy = toHierarchy(top.root ?? top.UITopLevelObjectsKey);
+    const classes = Object.fromEntries(objectTable.flatMap((raw) => {
+        const item = record(raw);
+        const name = firstString(item.$classname);
+        return name === null
+            ? []
+            : [
+                [
+                    name,
+                    {
+                        superclasses: Array.isArray(item.$classes) ? item.$classes : [],
+                    },
+                ],
+            ];
+    }));
+    return {
+        objects,
+        connections,
+        hierarchy,
+        classes,
+        objectCount,
+        omittedObjects: Math.max(0, objectCount - 20_000),
+        omittedConnections,
+    };
+};
+/** Coerce unknown values to a string-keyed record; non-objects become `{}`. */
+export const record = (value) => recordSchema.safeParse(value).data ?? {};
+/** First non-empty string among the candidates, otherwise null. */
+export const firstString = (...values) => {
+    for (const value of values)
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    return null;
+};
+/**
+ * The node identity of a resolved archive reference: its authored object ID,
+ * otherwise its archive UID, which is how the referenced object's node is keyed.
+ */
+const archivedObjectReference = (value) => {
+    const item = record(value);
+    if (typeof item.archiveUID !== "number")
+        return null;
+    return (firstString(item.objectID, item["object-id"]) ?? String(item.archiveUID));
+};
+const firstObjectReference = (...values) => {
+    for (const value of values) {
+        const direct = firstString(value);
+        if (direct !== null)
+            return direct;
+        const item = record(value);
+        const objectId = firstString(item.objectID, item["object-id"], item.id, item.identifier, typeof item.archiveUID === "number" ? String(item.archiveUID) : null);
+        if (objectId !== null)
+            return objectId;
+    }
+    return null;
+};
+const classifyObject = (className) => {
+    const value = className?.toLowerCase() ?? "";
+    if (value.includes("constraint"))
+        return "constraint";
+    if (value.includes("layoutguide"))
+        return "layout_guide";
+    if (value.includes("placeholder") ||
+        value.includes("firstresponder") ||
+        value === "uiproxyobject")
+        return "placeholder";
+    if (value.includes("image") ||
+        value.includes("color") ||
+        value.includes("font"))
+        return "resource";
+    if (value.includes("external"))
+        return "external_object";
+    if (value.includes("viewcontroller") || value.includes("windowcontroller"))
+        return "view_controller";
+    if (value.includes("button") ||
+        value.includes("control") ||
+        value.includes("textfield") ||
+        value.includes("slider") ||
+        value.includes("menuitem"))
+        return "control";
+    if (value.includes("view") ||
+        value.includes("window") ||
+        value.includes("cell"))
+        return "view";
+    return "other";
+};
+const classifyConnection = (type) => {
+    const value = type.toLowerCase();
+    if (value.includes("outlet"))
+        return "outlet";
+    if (value.includes("action"))
+        return "action";
+    if (value.includes("segue"))
+        return "segue";
+    return "other";
+};
+const jsonSafeRecord = (value) => Object.fromEntries(Object.entries(value).flatMap(([key, item]) => {
+    try {
+        const serialized = JSON.stringify(item);
+        if (serialized === undefined)
+            return [];
+        const parsed = jsonValueSchema.safeParse(JSON.parse(serialized));
+        return parsed.success ? [[key, parsed.data]] : [];
+    }
+    catch (cause) {
+        // Unserializable entries are omitted from the record.
+        void cause;
+        return [];
+    }
+}));

package/dist/domain/{keyedArchive.js → apple/keyedArchive.js}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { jsonValueSchema } from "./jsonValue.js";
+import { jsonValueSchema } from "../jsonValue.js";
 /** Select one archive within the active bundle and optionally one named root. */
 export const keyedArchiveInputSchema = z.strictObject({
     path: z.string().min(1).default("."),
@@ -47,11 +47,17 @@ export const keyedArchiveResultSchema = z.strictObject({
 const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
     ? value
     : undefined;
+/**
+ * A UID decodes as a one-key `UID` (binary) or `CF$UID` (XML) dictionary with
+ * a numeric value. Any other value means an ordinary dictionary, such as a
+ * `$top` that holds a root encoded under the key `UID`.
+ */
 const uid = (value) => {
     const object = record(value);
     if (object === undefined || Object.keys(object).length !== 1)
         return undefined;
-    return Object.hasOwn(object, "UID") ? object.UID : object["CF$UID"];
+    const marker = Object.hasOwn(object, "UID") ? object.UID : object["CF$UID"];
+    return typeof marker === "number" ? marker : undefined;
 };
 /** Interpret serialized Foundation references without instantiating archive classes. */
 export const projectKeyedArchive = (value, selection) => {
@@ -84,10 +90,7 @@ export const projectKeyedArchive = (value, selection) => {
                 throw new RangeError("Archive exceeds 200000 values per object or 128 nesting levels");
             const target = uid(item.value);
             if (target !== undefined) {
-                const valid = typeof target === "number" &&
-                    Number.isSafeInteger(target) &&
-                    target >= 0;
-                const index = valid ? target : null;
+                const index = Number.isSafeInteger(target) && target >= 0 ? target : null;
                 references.push({
                     source,
                     path: item.path,
@@ -127,9 +130,7 @@ export const projectKeyedArchive = (value, selection) => {
         scan(id, value);
         const fields = record(value);
         const classUid = uid(fields?.$class);
-        const classId = typeof classUid === "number" &&
-            Number.isSafeInteger(classUid) &&
-            classUid >= 0
+        const classId = classUid !== undefined && Number.isSafeInteger(classUid) && classUid >= 0
             ? classUid
             : null;
         const descriptor = classId === null ? undefined : record(table[classId]);

package/dist/domain/apple/plistValue.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+const MAX_PLIST_DEPTH = 128;
+/**
+ * Project a decoded plist into JSON. Data and dates become explicit
+ * `$plist_type` objects; a non-finite real becomes an explicit unknown
+ * because the XML decoder reports NaN and ±infinity alike.
+ */
+export const projectPlistValue = (value) => {
+    let unknownRealCount = 0;
+    const project = (item, depth) => {
+        if (depth > MAX_PLIST_DEPTH)
+            throw new RangeError(`Plist exceeds ${String(MAX_PLIST_DEPTH)} nesting levels`);
+        if (item instanceof Uint8Array)
+            return {
+                $plist_type: "data",
+                base64: Buffer.from(item).toString("base64"),
+            };
+        if (item instanceof Date)
+            return { $plist_type: "date", iso8601: item.toISOString() };
+        if (typeof item === "number" && !Number.isFinite(item)) {
+            unknownRealCount += 1;
+            return { $plist_type: "real", value: null };
+        }
+        if (Array.isArray(item))
+            return item.map((entry) => project(entry, depth + 1));
+        if (item !== null && typeof item === "object")
+            return Object.fromEntries(Object.entries(item).map(([key, entry]) => [
+                key,
+                project(entry, depth + 1),
+            ]));
+        return z.union([z.string(), z.number(), z.boolean(), z.null()]).parse(item);
+    };
+    const projected = project(value, 0);
+    return { value: projected, unknownRealCount };
+};

package/dist/domain/artifactInventoryEvidence.js

@@ -2,6 +2,7 @@ import { artifactInventoryResultSchema, } from "./artifactGraph.js";
 import { canonicalDigest, canonicalJson } from "./comparisonSemantics.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);
@@ -32,9 +33,18 @@ const validateInventoryPage = (inventory) => {
             `art_${canonicalDigest({ sha256: node.sha256 }, "Artifact inventory")}`)
             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) => {
-    if (pages.length === 0)
-        throw new TypeError("Artifact inventory requires Evidence pages");
     const first = pages[0];
     if (first === undefined)
         throw new TypeError("Artifact inventory requires Evidence pages");

package/dist/domain/artifactInventorySnapshot.js

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

package/dist/domain/artifactOperationError.js

@@ -4,13 +4,17 @@ export class ArtifactOperationError extends AnalysisError {
     operation;
     reason;
     artifactDetails;
+    detail;
     _tag = "ArtifactOperationError";
-    constructor(operation, reason, artifactDetails) {
+    constructor(operation, reason, artifactDetails, 
+    /** The specific constraint that failed, such as the colliding path. */
+    detail) {
         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)})`);
         this.operation = operation;
         this.reason = reason;
         this.artifactDetails = artifactDetails;
+        this.detail = detail;
     }
 }

package/dist/domain/artifactPathSyntax.js

@@ -0,0 +1,26 @@
+/**
+ * Pure string predicates for artifact path syntax. The local artifact
+ * resolver, the Electron native specifier check, and (by reference) the
+ * live-DOM and source-map URL handling share these character-level rules.
+ *
+ * Policy divergence (deliberate, not yet unified):
+ * - Local artifact paths resolve against an inventoried container root and
+ *   report rejected | external | not-found. Confinement is lexical
+ *   (posix.normalize must stay inside the root).
+ * - Live DOM destinations resolve against the document base URL and report
+ *   approved | outside_policy | unsupported against allowedOrigins
+ *   (see CdpCaptureDocuments.domDestination).
+ * - Source-map fetches require exact-origin http(s) without credentials
+ *   (see WebSourceMapFetcher.approvedUrl).
+ * Unifying those outcome vocabularies is a separate, observable change.
+ */
+/** Whether a reference carries a URI scheme (`https:`, `file:`, …). */
+export const hasScheme = (value) => /^[A-Za-z][A-Za-z+.-]*:/u.test(value);
+/** Whether a reference is scheme-qualified or protocol-relative. */
+export const looksExternal = (value) => hasScheme(value) || value.startsWith("//");
+/** Drop any query string and fragment from a declared reference. */
+export const stripQueryAndFragment = (value) => value.split("#", 1)[0]?.split("?", 1)[0] ?? "";
+/** Path syntax admitted for a canonical artifact path. */
+export const admitsCanonicalPathSyntax = (value) => !value.includes("\0") &&
+    !value.includes("\\") &&
+    !/%(?:2e|2f|5c)/iu.test(value);

package/dist/domain/browserNetworkEvidence.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+/** Caller-selected network content; omission retains metadata alone. */
+export const browserNetworkContentSelectionValuesSchema = z.strictObject({
+    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({
+    request_body: false,
+    response_body: false,
+    header_values: false,
+});
+/** Self-verifying retained bytes, after any declared-secret redaction. */
+export const browserNetworkBodySchema = z.union([
+    z.strictObject({ state: z.literal("not_requested") }),
+    z.strictObject({ state: z.literal("not_exposed") }),
+    z.strictObject({
+        state: z.literal("unavailable"),
+        reason: z.enum([
+            "request-failed",
+            "response-unfinished",
+            "body-read-failed",
+            "body-read-timeout",
+            "cancelled",
+            "capture-ended",
+        ]),
+        message: z.string().min(1),
+    }),
+    z
+        .strictObject({
+        state: z.literal("captured"),
+        representation: z.enum([
+            "browser-exposed-request-bytes",
+            "browser-decoded-response-bytes",
+        ]),
+        encoding: z.literal("base64"),
+        content: z.string(),
+        bytes: z.number().int().min(0),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        media_type: z.string().nullable(),
+        redacted: z.boolean(),
+    })
+        .superRefine((artifact, context) => {
+        const bytes = Buffer.from(artifact.content, "base64");
+        if (bytes.toString("base64") !== artifact.content)
+            context.addIssue({
+                code: "custom",
+                path: ["content"],
+                message: "Network body must use canonical base64",
+            });
+        if (bytes.length !== artifact.bytes)
+            context.addIssue({
+                code: "custom",
+                path: ["bytes"],
+                message: "Network body byte count disagrees with retained bytes",
+            });
+        if (createHash("sha256").update(bytes).digest("hex") !== artifact.sha256)
+            context.addIssue({
+                code: "custom",
+                path: ["sha256"],
+                message: "Network body digest disagrees with retained bytes",
+            });
+    }),
+]);
+/** Headers retain producer order and duplicates, with credential values removed. */
+export const browserNetworkHeadersSchema = z.union([
+    z.strictObject({ state: z.literal("not_requested") }),
+    z.strictObject({
+        state: z.literal("unavailable"),
+        message: z.string().min(1),
+    }),
+    z.strictObject({
+        state: z.literal("captured"),
+        items: z.array(z.strictObject({
+            name: z.string().min(1),
+            value: z.string().nullable(),
+            redacted: z.boolean(),
+        })),
+    }),
+]);

package/dist/domain/browserObservationError.js

@@ -8,10 +8,12 @@ export class BrowserObservationError extends AnalysisError {
     cleanupIncomplete;
     cleanupResources;
     userCategory;
+    userMessage;
     constructor(operation, reason, options) {
         super(`Browser observation ${operation} failed: ${reason}`, options);
         this.operation = operation;
         this.reason = reason;
+        this.userMessage = options?.detail;
         this.cleanupIncomplete = reason === "cleanup_failed";
         this.cleanupResources =
             reason === "cleanup_failed" ? ["browser_transport"] : [];