rea-agents 6.3.0 → 6.5.0

package/dist/domain/browserObservationSchemas.js

@@ -17,7 +17,10 @@ const browserTargetSchema = z.object({
     title: z.string(),
     url: z.string(),
     origin: z.string(),
-    attached: z.boolean(),
+    attached: z
+        .boolean()
+        .nullable()
+        .describe("Discovery-reported debugger attachment state; null means unknown"),
 });
 /** Complete policy-filtered browser target discovery result. */
 export const browserTargetListSchema = z.object({
@@ -159,11 +162,10 @@ const browserConsoleEventSchema = z.object({
         retained_bytes: z.number().int().min(0),
     }),
 });
-const browserWebSocketEventSchema = z.object({
-    request_id: z.string(),
+const browserWebSocketFrameSchema = z.object({
     direction: z.enum(["sent", "received"]),
     opcode: z.number().int().min(0),
-    payload_bytes: z.number().int().min(0),
+    payload_bytes: z.number().int().min(0).nullable(),
     payload_shape: z
         .object({
         format: z.enum(["json", "text", "binary"]),
@@ -171,6 +173,11 @@ const browserWebSocketEventSchema = z.object({
     })
         .nullable(),
 });
+const browserWebSocketConnectionSchema = z.object({
+    request_id: z.string(),
+    url: z.string(),
+    events: z.array(browserWebSocketFrameSchema),
+});
 const browserWorkerSchema = z.object({
     target_id: z.string(),
     type: z.string(),
@@ -275,7 +282,7 @@ export const webPageInspectionSchema = z.object({
     resources: z.array(browserResourceSchema),
     network: z.object({
         requests: z.array(browserNetworkRequestSchema),
-        websocket_events: z.array(browserWebSocketEventSchema),
+        websocket_connections: z.array(browserWebSocketConnectionSchema),
         coverage_started_at: z.iso.datetime(),
         prior_activity_available: z.literal(false),
     }),

package/dist/domain/browserScenarioCapture.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { browserNetworkContentSelectionValuesSchema } from "./browserNetworkEvidence.js";
-import { browserScenarioCompletenessSchema, browserScenarioEventSchema, browserScenarioStepSchema, } from "./browserScenarioCaptureValues.js";
+import { browserScenarioCompletenessSchema, browserScenarioEventFamilySchema, browserScenarioEventSchema, browserScenarioStepSchema, } from "./browserScenarioCaptureValues.js";
 /** Step-indexed browser scenario observation. */
 export const browserScenarioCaptureSchema = z
     .strictObject({
@@ -16,6 +16,7 @@ export const browserScenarioCaptureSchema = z
         action_count: z.number().int().min(1),
         secret_references: z.array(z.string().min(1)),
         network_content: browserNetworkContentSelectionValuesSchema,
+        event_families: z.array(browserScenarioEventFamilySchema).optional(),
     }),
     duration_ms: z.number().int().min(0),
     steps: z.array(browserScenarioStepSchema).min(1),

package/dist/domain/browserScenarioCaptureValues.js

@@ -96,6 +96,17 @@ export const browserStepArtifactsSchema = z.strictObject({
     history: captureStateSchema(historySchema),
     storage: captureStateSchema(storageSnapshotSchema),
 });
+/** Event families a scenario can select for capture. */
+export const browserScenarioEventFamilySchema = z.enum([
+    "console",
+    "page-errors",
+    "network",
+    "websockets",
+    "frames",
+    "workers",
+    "popups",
+    "downloads",
+]);
 const eventBase = {
     sequence: z.number().int().min(1),
     step_index: z.number().int().min(0),
@@ -105,6 +116,8 @@ const networkEventShape = {
     ...eventBase,
     transaction_id: z.string().min(1),
     redirected_from_transaction_id: z.string().min(1).nullable(),
+    /** Distinguishes a captured root from an unobserved predecessor for null links. */
+    redirected_from_transaction_state: z.enum(["root", "unknown"]).optional(),
     method: z.string().min(1),
     url: sanitizedBrowserUrlSchema,
     resource_type: z.string().min(1),
@@ -117,7 +130,8 @@ const webSocketFrameShape = {
     payload_bytes: z.number().int().min(0),
     truncated: z.boolean(),
 };
-export const browserScenarioEventSchema = z.union([
+export const browserScenarioEventSchema = z
+    .union([
     z.strictObject({
         ...eventBase,
         kind: z.literal("console"),
@@ -206,7 +220,17 @@ export const browserScenarioEventSchema = z.union([
         suggested_filename: z.string(),
         url: sanitizedBrowserUrlSchema,
     }),
-]);
+])
+    .superRefine((event, context) => {
+    if ("redirected_from_transaction_id" in event &&
+        event.redirected_from_transaction_id !== null &&
+        event.redirected_from_transaction_state !== undefined)
+        context.addIssue({
+            code: "custom",
+            message: "Redirect state is valid only when the predecessor transaction ID is null",
+            path: ["redirected_from_transaction_state"],
+        });
+});
 const completenessSectionSchema = z.enum([
     "action",
     "screenshot",

package/dist/domain/browserScenarioDiff.js

@@ -1,15 +1,25 @@
-import { actionState, artifactEvidenceState, captured, eventEvidenceState, eventsFor, networkContentCoverageReason, screenshotProjection, } from "./browserScenarioDiffEvidence.js";
+import { z } from "zod";
+import { digestCanonicalValue } from "./canonicalDigest.js";
+import { actionState, artifactEvidenceState, captured, eventEvidenceState, eventFamilyCoverageReason, prepareScenarioEvents, networkContentCoverageReason, screenshotProjection, } from "./browserScenarioDiffEvidence.js";
 import { browserScenarioDiffSchema, } from "./browserScenarioDiffValues.js";
-import { commitBrowserScenarioNormalization, digestNormalizedScenarioValue, } from "./browserScenarioNormalization.js";
+import { commitBrowserScenarioNormalization, digestNormalizedScenarioValue, normalizeScenarioValue, } from "./browserScenarioNormalization.js";
+const scenarioEventsValueSchema = z.strictObject({
+    events: z.array(z.unknown()),
+    network_transactions: z.array(z.string()),
+});
 /** Compare scenario steps by stable step ID and apply only committed literal rules. */
 export const compareBrowserScenarios = (input) => {
     const normalization = commitBrowserScenarioNormalization(input.normalization);
+    const beforeEvents = prepareScenarioEvents(input.before_scenario, normalization.rules);
+    const afterEvents = prepareScenarioEvents(input.after_scenario, normalization.rules);
     const alignment = alignScenarioSteps(input.before_scenario, input.after_scenario);
     const compared = compareAlignedSteps({
         beforeCapture: input.before_scenario,
         afterCapture: input.after_scenario,
         alignment,
         rules: normalization.rules,
+        beforeEvents,
+        afterEvents,
     });
     const failures = [...alignment.failures, ...compared.failures];
     const alignmentStatus = failures.length === 0
@@ -44,7 +54,7 @@ export const compareBrowserScenarios = (input) => {
         limitations: [
             "Steps align only by exact, unique step_id; missing, duplicate, or action-mismatched steps are reported and prevent an unchanged claim.",
             "Only declared literal normalization rules are applied, in canonical rule_id order, to already-redacted durable capture fields.",
-            "Elapsed time and event sequence/index values are excluded as volatile; screenshot bytes are compared by content digest.",
+            "Elapsed time, event sequence/index values and capture-local transaction IDs are excluded as volatile; network transactions are compared as an unordered collection in the step that sent their request; screenshot bytes are compared by content digest.",
             "A changed status proves an observed normalized difference. Missing or truncated evidence, incompatible capture context, or alignment failure prevents an unchanged claim.",
         ],
     });
@@ -106,6 +116,8 @@ const compareAlignedSteps = (input) => {
             afterCapture: input.afterCapture,
             afterStep,
             rules: input.rules,
+            beforeEvents: input.beforeEvents,
+            afterEvents: input.afterEvents,
         });
         const reportable = artifacts.flatMap(({ diff }) => diff === null ? [] : [diff]);
         totalArtifactDiffs += reportable.length;
@@ -204,28 +216,121 @@ const compareStepArtifacts = (input) => {
             before: input.beforeStep.artifacts.storage,
             after: input.afterStep.artifacts.storage,
         }),
-        compareCapturedValues({
+        compareScenarioEvents({
             ...common,
             artifact: "events",
-            before: captured(eventsFor(input.beforeCapture, input.beforeStep.step_index)),
-            after: captured(eventsFor(input.afterCapture, input.afterStep.step_index)),
+            before: captured(input.beforeEvents.forStep(input.beforeStep.step_index)),
+            after: captured(input.afterEvents.forStep(input.afterStep.step_index)),
             beforeState: eventEvidenceState(input.beforeCapture, input.beforeStep),
             afterState: eventEvidenceState(input.afterCapture, input.afterStep),
-            incomparableReason: networkContentCoverageReason(input.beforeCapture, input.afterCapture),
+            incomparableReason: eventCoverageReason(input.beforeCapture, input.afterCapture, input.beforeEvents.coverageReason, input.afterEvents.coverageReason),
+            familyIncomparableReason: eventFamilyCoverageReason(input.beforeCapture, input.afterCapture),
         }),
     ];
 };
+const compareScenarioEvents = (input) => {
+    const beforeState = input.beforeState ??
+        artifactEvidenceState(input.artifact, input.before, input.beforeStep);
+    const afterState = input.afterState ??
+        artifactEvidenceState(input.artifact, input.after, input.afterStep);
+    if (beforeState === "not_requested" && afterState === "not_requested")
+        return { artifact: input.artifact, status: "not_compared", diff: null };
+    const beforeValue = input.before.state === "captured" ? input.before.value : undefined;
+    const afterValue = input.after.state === "captured" ? input.after.value : undefined;
+    const isCaptured = beforeState === "captured" &&
+        afterState === "captured" &&
+        beforeValue !== undefined &&
+        afterValue !== undefined;
+    const ordinaryBeforeDigest = beforeValue === undefined
+        ? null
+        : digestCanonicalValue(normalizeScenarioValue(beforeValue.events, "events", input.rules), "Browser scenario");
+    const ordinaryAfterDigest = afterValue === undefined
+        ? null
+        : digestCanonicalValue(normalizeScenarioValue(afterValue.events, "events", input.rules), "Browser scenario");
+    const beforeSha256 = beforeState === "captured" && beforeValue !== undefined
+        ? digestScenarioEvents(beforeValue, ordinaryBeforeDigest)
+        : null;
+    const afterSha256 = afterState === "captured" && afterValue !== undefined
+        ? digestScenarioEvents(afterValue, ordinaryAfterDigest)
+        : null;
+    const changedOrdinaryEvents = isCaptured && ordinaryBeforeDigest !== ordinaryAfterDigest;
+    if (changedOrdinaryEvents && input.familyIncomparableReason === undefined)
+        return {
+            artifact: input.artifact,
+            status: "changed",
+            diff: {
+                artifact: input.artifact,
+                status: "changed",
+                before_state: beforeState,
+                after_state: afterState,
+                before_sha256: beforeSha256,
+                after_sha256: afterSha256,
+                reason: input.incomparableReason ?? null,
+            },
+        };
+    if (!isCaptured ||
+        input.incomparableReason !== undefined ||
+        input.familyIncomparableReason !== undefined)
+        return {
+            artifact: input.artifact,
+            status: "unknown",
+            diff: {
+                artifact: input.artifact,
+                status: "unknown",
+                before_state: beforeState,
+                after_state: afterState,
+                before_sha256: beforeSha256,
+                after_sha256: afterSha256,
+                reason: joinIncomparableReasons(input.familyIncomparableReason, input.incomparableReason) ??
+                    `Artifact coverage is not comparable (${beforeState} before, ${afterState} after).`,
+            },
+        };
+    if (beforeSha256 === null || afterSha256 === null)
+        throw new TypeError("Captured event digest refinement failed");
+    if (beforeSha256 === afterSha256)
+        return { artifact: input.artifact, status: "unchanged", diff: null };
+    return {
+        artifact: input.artifact,
+        status: "changed",
+        diff: {
+            artifact: input.artifact,
+            status: "changed",
+            before_state: beforeState,
+            after_state: afterState,
+            before_sha256: beforeSha256,
+            after_sha256: afterSha256,
+            reason: null,
+        },
+    };
+};
+const digestScenarioEvents = (value, ordinaryEventsDigest) => {
+    const parsed = scenarioEventsValueSchema.parse(value);
+    return digestCanonicalValue({
+        ordinary_events_sha256: ordinaryEventsDigest,
+        // These are already normalized SHA-256 transaction fingerprints.
+        network_transactions: parsed.network_transactions,
+    }, "Browser scenario");
+};
+const eventCoverageReason = (before, after, beforeNetworkReason, afterNetworkReason) => {
+    const reasons = [
+        eventFamilyCoverageReason(before, after),
+        networkContentCoverageReason(before, after),
+        beforeNetworkReason,
+        afterNetworkReason,
+    ].filter((reason) => reason !== undefined);
+    return reasons.length === 0 ? undefined : reasons.join(" ");
+};
 const compareCapturedValues = (input) => {
-    const { artifact, before, after, beforeStep, afterStep, rules, project = (value) => value, } = input;
+    const { artifact, before, after, beforeStep, afterStep, rules, project = (value) => value, order, } = input;
     const beforeState = input.beforeState ?? artifactEvidenceState(artifact, before, beforeStep);
     const afterState = input.afterState ?? artifactEvidenceState(artifact, after, afterStep);
     if (beforeState === "not_requested" && afterState === "not_requested")
         return { artifact, status: "not_compared", diff: null };
     const beforeSha256 = beforeState === "captured" && before.state === "captured"
-        ? digestNormalizedScenarioValue(project(before.value), artifact, rules)
+        ? digestNormalizedScenarioValue(project(before.value), artifact, rules, order)
         : null;
     const afterSha256 = afterState === "captured" && after.state === "captured"
-        ? digestNormalizedScenarioValue(project(after.value), artifact, rules)
+        ? digestNormalizedScenarioValue(project(after.value), artifact, rules, order)
         : null;
     if (beforeState !== "captured" ||
         afterState !== "captured" ||
@@ -242,7 +347,7 @@ const compareCapturedValues = (input) => {
                 after_state: afterState,
                 before_sha256: beforeSha256,
                 after_sha256: afterSha256,
-                reason: input.incomparableReason ??
+                reason: joinIncomparableReasons(input.familyIncomparableReason, input.incomparableReason) ??
                     `Artifact coverage is not comparable (${beforeState} before, ${afterState} after).`,
             },
         };
@@ -264,3 +369,7 @@ const compareCapturedValues = (input) => {
         },
     };
 };
+const joinIncomparableReasons = (...reasons) => {
+    const present = reasons.filter((reason) => reason !== undefined);
+    return present.length === 0 ? undefined : [...new Set(present)].join(" ");
+};

package/dist/domain/browserScenarioDiffEvidence.js

@@ -1,3 +1,4 @@
+import { fingerprintScenarioNetworkTransactions, scenarioNetworkTransactions, scenarioNetworkCoverageReason, } from "./browserScenarioNetworkComparison.js";
 const includesCompletenessSection = (completeness, collection, section) => {
     const sections = completeness[collection];
     return sections.includes(section);
@@ -36,19 +37,37 @@ export const actionState = (step) => ({
     after_url: step.after_url,
     error: step.error,
 });
-/** Select events attributed to one scenario step without sequence metadata. */
-export const eventsFor = (capture, stepIndex) => {
-    const sourceSteps = new Map(capture.events.items.map(({ sequence, step_index }) => [
-        sequence,
-        step_index,
-    ]));
-    return capture.events.items.flatMap(({ sequence: _sequence, step_index: eventStepIndex, ...event }) => {
-        if (event.kind === "network-content") {
-            const { source_event_sequence: sourceSequence, ...content } = event;
-            return sourceSteps.get(sourceSequence) === stepIndex ? [content] : [];
-        }
-        return eventStepIndex === stepIndex ? [event] : [];
-    });
+/** Build one graph and fingerprint index per capture, then select in linear total work. */
+export const prepareScenarioEvents = (capture, rules) => {
+    const eventsByStep = new Map();
+    for (const { sequence: _sequence, step_index, ...event } of capture.events
+        .items) {
+        if ("transaction_id" in event)
+            continue;
+        const events = eventsByStep.get(step_index) ?? [];
+        events.push(event);
+        eventsByStep.set(step_index, events);
+    }
+    const nodes = scenarioNetworkTransactions(capture);
+    const fingerprints = fingerprintScenarioNetworkTransactions(nodes, rules);
+    const networkByStep = new Map();
+    for (const [index, node] of nodes.entries()) {
+        const step = networkByStep.get(node.step_index) ?? [];
+        const fingerprint = fingerprints[index];
+        if (fingerprint === undefined)
+            throw new Error("Network comparison node has no fingerprint");
+        step.push(fingerprint);
+        networkByStep.set(node.step_index, step);
+    }
+    for (const fingerprintsForStep of networkByStep.values())
+        fingerprintsForStep.sort();
+    return {
+        coverageReason: scenarioNetworkCoverageReason(capture, nodes),
+        forStep: (stepIndex) => ({
+            events: eventsByStep.get(stepIndex) ?? [],
+            network_transactions: networkByStep.get(stepIndex) ?? [],
+        }),
+    };
 };
 /** Different content selection is missing comparability, not an observed website change. */
 export const networkContentCoverageReason = (before, after) => {
@@ -60,6 +79,20 @@ export const networkContentCoverageReason = (before, after) => {
         ? "Network content selections differ; capture both sides with matching content selection before comparing network evidence."
         : undefined;
 };
+/** Different or unrecorded event-family selection is missing comparability, not an observed website change. */
+export const eventFamilyCoverageReason = (before, after) => {
+    const left = before.scenario.event_families;
+    const right = after.scenario.event_families;
+    if (left === undefined || right === undefined)
+        return "Event family selection is unknown in a legacy capture; capture both sides with matching event families before comparing event evidence.";
+    const leftFamilies = new Set(left);
+    const rightFamilies = new Set(right);
+    return leftFamilies.size === rightFamilies.size &&
+        [...leftFamilies].every((family) => rightFamilies.has(family))
+        ? undefined
+        : `Event family selections differ (${familyList(leftFamilies)} before, ${familyList(rightFamilies)} after); capture both sides with matching event families before comparing event evidence.`;
+};
+const familyList = (families) => families.size === 0 ? "none" : [...families].sort().join(", ");
 /** Wrap one value as captured comparison evidence. */
 export const captured = (value) => ({
     state: "captured",

package/dist/domain/browserScenarioDiffValues.js

@@ -101,19 +101,26 @@ const alignmentFailureSchema = z.strictObject({
     step_id: z.string().min(1).nullable(),
     reason: z.string().min(1),
 });
-const builtInNormalizationSchema = z.enum([
+export const BROWSER_SCENARIO_BUILT_IN_NORMALIZATION_RULES = [
     "ignore_step_elapsed_ms",
     "ignore_event_sequence",
     "ignore_event_step_index",
     "compare_screenshot_content_digest",
     "compare_normalized_text_content",
-]);
+    "ignore_capture_local_network_transaction_ids",
+    "attribute_network_transactions_to_request_step",
+    "compare_network_transactions_as_unordered_collection",
+    "preserve_redirect_transaction_ancestry",
+];
+const builtInNormalizationSchema = z.enum(BROWSER_SCENARIO_BUILT_IN_NORMALIZATION_RULES);
 /** Step alignment, recorded normalization, and inline artifact differences. */
 export const browserScenarioDiffSchema = z.strictObject({
     comparison_kind: z.literal("browser_scenario"),
     overall_status: z.enum(["changed", "unchanged", "unknown"]),
     normalization: z.strictObject({
-        built_in_rules: z.array(builtInNormalizationSchema).length(5),
+        built_in_rules: z
+            .array(builtInNormalizationSchema)
+            .length(BROWSER_SCENARIO_BUILT_IN_NORMALIZATION_RULES.length),
         rules: z.array(normalizationRuleSchema),
         sha256: z.string().regex(/^[a-f0-9]{64}$/u),
     }),

package/dist/domain/browserScenarioNetworkComparison.js

@@ -0,0 +1,158 @@
+import { z } from "zod";
+import { digestCanonicalValue } from "./canonicalDigest.js";
+import { normalizeScenarioValue } from "./browserScenarioNormalization.js";
+/** Numeric links are temporary local indices, never durable transaction identity. */
+export const scenarioNetworkTransactionSchema = z.strictObject({
+    events: z.array(z.unknown()),
+    predecessor: z.number().int().min(-2),
+    step_index: z.number().int().min(0),
+});
+/** Project each transaction once, retaining ancestry as references rather than nested copies. */
+export const scenarioNetworkTransactions = (capture) => {
+    const sourceSteps = new Map(capture.events.items.map((event) => [event.sequence, event.step_index]));
+    const requests = new Map(capture.events.items.flatMap((event) => event.kind === "request" ? [[event.transaction_id, event]] : []));
+    const grouped = new Map();
+    for (const { sequence: _sequence, step_index: step, ...event } of capture
+        .events.items) {
+        if (!("transaction_id" in event))
+            continue;
+        const id = event.transaction_id;
+        const request = requests.get(id);
+        const receiptStep = event.kind === "network-content"
+            ? sourceSteps.get(event.source_event_sequence)
+            : step;
+        const requestStep = request?.step_index ?? receiptStep;
+        let evidence;
+        let predecessor;
+        let predecessorState;
+        if (event.kind === "network-content") {
+            const { transaction_id: _id, source_event_sequence: _source, ...content } = event;
+            evidence = content;
+            predecessor = request?.redirected_from_transaction_id ?? null;
+            predecessorState = request?.redirected_from_transaction_state;
+        }
+        else {
+            const { transaction_id: _id, redirected_from_transaction_id: parent, redirected_from_transaction_state: _state, ...network } = event;
+            evidence = network;
+            predecessor =
+                request === undefined ? parent : request.redirected_from_transaction_id;
+            predecessorState =
+                request === undefined
+                    ? event.redirected_from_transaction_state
+                    : request.redirected_from_transaction_state;
+        }
+        const previous = grouped.get(id);
+        if (previous === undefined)
+            grouped.set(id, {
+                events: [evidence],
+                predecessor,
+                predecessorState,
+                predecessorConflict: event.kind !== "network-content" &&
+                    request !== undefined &&
+                    ((event.redirected_from_transaction_id !== null &&
+                        event.redirected_from_transaction_id !==
+                            request.redirected_from_transaction_id) ||
+                        (event.redirected_from_transaction_state === "root" &&
+                            request.redirected_from_transaction_id !== null)),
+                stepIndex: requestStep ?? step,
+            });
+        else {
+            previous.events.push(evidence);
+            if (event.kind !== "network-content") {
+                const parent = event.redirected_from_transaction_id;
+                const state = event.redirected_from_transaction_state;
+                const knownParent = previous.predecessor;
+                if (parent !== null &&
+                    (knownParent !== null
+                        ? parent !== knownParent
+                        : previous.predecessorState === "root"))
+                    previous.predecessorConflict = true;
+                else if (parent !== null && knownParent === null) {
+                    previous.predecessor = parent;
+                    previous.predecessorState = state;
+                }
+                else if (parent === null && state === "root" && knownParent !== null)
+                    previous.predecessorConflict = true;
+                else if (parent === null &&
+                    state === "root" &&
+                    previous.predecessorState !== "root")
+                    previous.predecessorState = "root";
+            }
+        }
+    }
+    const indices = new Map([...grouped.keys()].map((id, index) => [id, index]));
+    return [...grouped.values()].map((node) => ({
+        events: node.events,
+        predecessor: node.predecessorConflict
+            ? -2
+            : node.predecessor === null
+                ? node.predecessorState === "root"
+                    ? -1
+                    : -2
+                : (indices.get(node.predecessor) ?? -2),
+        step_index: node.stepIndex,
+    }));
+};
+/** Missing or cyclic ancestry cannot support an unchanged claim. */
+export const scenarioNetworkCoverageReason = (capture, nodes = scenarioNetworkTransactions(capture)) => {
+    const finished = new Set();
+    for (let start = 0; start < nodes.length; start += 1) {
+        const path = new Set();
+        let index = start;
+        while (index >= 0 && !finished.has(index)) {
+            if (path.has(index))
+                return "Redirect ancestry contains a cycle; network transaction identity remains unknown.";
+            path.add(index);
+            const node = nodes[index];
+            if (node === undefined)
+                return "Redirect predecessor evidence is missing; network transaction identity remains unknown.";
+            index = node.predecessor;
+        }
+        if (index === -2)
+            return "Redirect predecessor evidence is missing; network transaction identity remains unknown.";
+        for (const item of path)
+            finished.add(item);
+    }
+    return undefined;
+};
+/** Hash normalized own evidence and its complete parent fingerprint in linear graph space. */
+export const fingerprintScenarioNetworkTransactions = (nodes, rules = []) => {
+    const own = nodes.map((node) => node.events
+        .map((event) => digestCanonicalValue(normalizeScenarioValue(event, "events", rules), "Browser scenario"))
+        .sort());
+    const fingerprints = new Map();
+    for (let start = 0; start < nodes.length; start += 1) {
+        const path = [];
+        const positions = new Map();
+        let index = start;
+        while (index >= 0 &&
+            nodes[index] !== undefined &&
+            !fingerprints.has(index)) {
+            const position = positions.get(index);
+            if (position !== undefined) {
+                // These captures are incomparable; retain an explicit cycle observation.
+                for (const member of path.slice(position))
+                    fingerprints.set(member, digestCanonicalValue({ events: own[member], redirected_from: { state: "cycle" } }, "Browser scenario"));
+                break;
+            }
+            positions.set(index, path.length);
+            path.push(index);
+            index = nodes[index]?.predecessor ?? -2;
+        }
+        for (const member of path.reverse()) {
+            if (fingerprints.has(member))
+                continue;
+            const predecessor = nodes[member]?.predecessor ?? -2;
+            const parent = predecessor === -1
+                ? null
+                : (fingerprints.get(predecessor) ?? { state: "missing" });
+            fingerprints.set(member, digestCanonicalValue({ events: own[member], redirected_from: parent }, "Browser scenario"));
+        }
+    }
+    return nodes.map((_, index) => {
+        const fingerprint = fingerprints.get(index);
+        if (fingerprint === undefined)
+            throw new Error("Network comparison node has no fingerprint");
+        return fingerprint;
+    });
+};

package/dist/domain/browserScenarioNormalization.js

@@ -1,11 +1,5 @@
 import { digestCanonicalValue } from "./canonicalDigest.js";
-const BUILT_IN_RULES = [
-    "ignore_step_elapsed_ms",
-    "ignore_event_sequence",
-    "ignore_event_step_index",
-    "compare_screenshot_content_digest",
-    "compare_normalized_text_content",
-];
+import { BROWSER_SCENARIO_BUILT_IN_NORMALIZATION_RULES, } from "./browserScenarioDiffValues.js";
 /** Canonically order and commit a parsed browser scenario normalization policy. */
 export const commitBrowserScenarioNormalization = (input) => {
     const rules = [...input.rules]
@@ -14,15 +8,18 @@ export const commitBrowserScenarioNormalization = (input) => {
         artifacts: [...rule.artifacts].sort(),
     }))
         .sort((left, right) => left.rule_id < right.rule_id ? -1 : left.rule_id > right.rule_id ? 1 : 0);
-    const commitment = { built_in_rules: [...BUILT_IN_RULES], rules };
+    const commitment = {
+        built_in_rules: [...BROWSER_SCENARIO_BUILT_IN_NORMALIZATION_RULES],
+        rules,
+    };
     return {
         ...commitment,
         sha256: digestCanonicalValue(commitment, "Browser scenario"),
     };
 };
-/** Digest one artifact after applying committed exact-literal rules. */
-export const digestNormalizedScenarioValue = (value, artifact, rules) => digestCanonicalValue(normalize(value, artifact, rules), "Browser scenario");
-const normalize = (value, artifact, rules) => {
+/** Digest one artifact after applying committed exact-literal rules, then any artifact ordering. */
+export const digestNormalizedScenarioValue = (value, artifact, rules, order = (normalized) => normalized) => digestCanonicalValue(order(normalizeScenarioValue(value, artifact, rules)), "Browser scenario");
+export const normalizeScenarioValue = (value, artifact, rules) => {
     if (artifact === "screenshot")
         return value;
     if (typeof value === "string")
@@ -30,11 +27,11 @@ const normalize = (value, artifact, rules) => {
             .filter(({ artifacts }) => artifacts.includes(artifact))
             .reduce((normalized, rule) => normalized.split(rule.match).join(rule.replacement), value);
     if (Array.isArray(value))
-        return value.map((item) => normalize(item, artifact, rules));
+        return value.map((item) => normalizeScenarioValue(item, artifact, rules));
     if (typeof value !== "object" || value === null)
         return value;
     return Object.fromEntries(Object.entries(value).map(([key, item]) => [
         key,
-        normalize(item, artifact, rules),
+        normalizeScenarioValue(item, artifact, rules),
     ]));
 };

package/dist/domain/browserScenarioValues.js

@@ -3,6 +3,7 @@ import { isAbsolute } from "node:path";
 import { IDENTIFIER_PATTERN } from "./stringPatterns.js";
 import { localPathStringSchema } from "./localPath.js";
 import { browserNetworkContentSelectionSchema } from "./browserNetworkEvidence.js";
+import { browserScenarioEventFamilySchema } from "./browserScenarioCaptureValues.js";
 import { browserEndpointSchema, browserOriginSchema, } from "./browserObservation.js";
 export const scenarioIdentifierSchema = z.string().regex(IDENTIFIER_PATTERN);
 const browserExecutablePathSchema = localPathStringSchema.refine(isAbsolute, {
@@ -241,18 +242,7 @@ export const browserScenarioCaptureSchema = z
     .strictObject({
     after_each_step: z.array(snapshotKindSchema).default([]),
     at_end: z.array(snapshotKindSchema).default(["url"]),
-    events: z
-        .array(z.enum([
-        "console",
-        "page-errors",
-        "network",
-        "websockets",
-        "frames",
-        "workers",
-        "popups",
-        "downloads",
-    ]))
-        .default([]),
+    events: z.array(browserScenarioEventFamilySchema).default([]),
     network: browserNetworkContentSelectionSchema,
 })
     .default({