rea-agents 2.3.0 → 2.5.0

package/dist/domain/browserScenarioDiff.js

@@ -0,0 +1,324 @@
+import {} from "./browserScenarioCapture.js";
+import { browserScenarioDiffSchema, } from "./browserScenarioDiffValues.js";
+import { commitBrowserScenarioNormalization, digestCanonicalJson, digestNormalizedScenarioValue, } from "./browserScenarioNormalization.js";
+export { browserScenarioDiffSchema, compareBrowserScenariosInputSchema, } from "./browserScenarioDiffValues.js";
+/** Compare scenario steps by stable step ID and apply only committed literal rules. */
+export const compareBrowserScenarios = (input) => {
+    const normalization = commitBrowserScenarioNormalization(input.normalization);
+    const alignment = alignScenarioSteps(input.before_scenario, input.after_scenario);
+    const compared = compareAlignedSteps({
+        beforeCapture: input.before_scenario,
+        afterCapture: input.after_scenario,
+        alignment,
+        rules: normalization.rules,
+        maxChanges: input.max_changes,
+    });
+    const failures = [...alignment.failures, ...compared.failures];
+    const alignmentStatus = failures.length === 0
+        ? "aligned"
+        : compared.steps.length === 0
+            ? "failed"
+            : "partial";
+    const stepStatuses = compared.steps.map(({ status }) => status);
+    const equalityEligible = input.before_scenario.completeness.equality_eligible &&
+        input.after_scenario.completeness.equality_eligible &&
+        alignmentStatus === "aligned";
+    const overallStatus = stepStatuses.includes("changed")
+        ? "changed"
+        : stepStatuses.includes("unknown") || !equalityEligible
+            ? "unknown"
+            : "unchanged";
+    return browserScenarioDiffSchema.parse({
+        schema_version: 1,
+        comparison_kind: "browser_scenario",
+        overall_status: overallStatus,
+        normalization,
+        alignment: {
+            status: alignmentStatus,
+            aligned_steps: compared.steps.length,
+            before_only: alignment.beforeOnly,
+            after_only: alignment.afterOnly,
+            failures,
+        },
+        steps: compared.steps,
+        artifact_diffs: {
+            total: compared.totalArtifactDiffs,
+            retained: compared.totalArtifactDiffs -
+                Math.max(0, compared.totalArtifactDiffs - input.max_changes),
+            omitted: Math.max(0, compared.totalArtifactDiffs - input.max_changes),
+        },
+        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.",
+            "A changed status proves an observed normalized difference. Missing or truncated evidence, incompatible capture context, or alignment failure prevents an unchanged claim.",
+            ...(compared.totalArtifactDiffs > input.max_changes
+                ? [
+                    `${String(compared.totalArtifactDiffs - input.max_changes)} artifact difference record(s) were omitted by max_changes.`,
+                ]
+                : []),
+        ],
+    });
+};
+const alignScenarioSteps = (beforeCapture, afterCapture) => {
+    const beforeDuplicates = duplicateStepIds(beforeCapture.steps);
+    const afterDuplicates = duplicateStepIds(afterCapture.steps);
+    const before = uniqueSteps(beforeCapture.steps, beforeDuplicates);
+    const after = uniqueSteps(afterCapture.steps, afterDuplicates);
+    const beforeOnly = [...before.keys()]
+        .filter((stepId) => !after.has(stepId))
+        .sort();
+    const afterOnly = [...after.keys()]
+        .filter((stepId) => !before.has(stepId))
+        .sort();
+    const failures = [
+        ...duplicateFailures("before", beforeDuplicates),
+        ...duplicateFailures("after", afterDuplicates),
+        ...missingFailures("before", afterOnly),
+        ...missingFailures("after", beforeOnly),
+    ];
+    if (!captureContextsMatch(beforeCapture, afterCapture))
+        failures.push({
+            code: "capture_context_mismatch",
+            step_id: null,
+            reason: "Browser product/version or scenario origin scope differs between captures.",
+        });
+    return {
+        before,
+        after,
+        beforeOnly,
+        afterOnly,
+        failures,
+        orderedStepIds: beforeCapture.steps
+            .map(({ step_id }) => step_id)
+            .filter((stepId, index, values) => values.indexOf(stepId) === index &&
+            before.has(stepId) &&
+            after.has(stepId)),
+    };
+};
+const compareAlignedSteps = (input) => {
+    const remaining = { value: input.maxChanges };
+    let totalArtifactDiffs = 0;
+    const steps = [];
+    const failures = [];
+    for (const stepId of input.alignment.orderedStepIds) {
+        const beforeStep = input.alignment.before.get(stepId);
+        const afterStep = input.alignment.after.get(stepId);
+        if (beforeStep === undefined || afterStep === undefined)
+            continue;
+        if (beforeStep.action !== afterStep.action)
+            failures.push({
+                code: "action_mismatch",
+                step_id: stepId,
+                reason: `Aligned step action changed from ${beforeStep.action} to ${afterStep.action}.`,
+            });
+        const artifacts = compareStepArtifacts({
+            beforeCapture: input.beforeCapture,
+            beforeStep,
+            afterCapture: input.afterCapture,
+            afterStep,
+            rules: input.rules,
+        });
+        const reportable = artifacts.flatMap(({ diff }) => diff === null ? [] : [diff]);
+        totalArtifactDiffs += reportable.length;
+        const retained = reportable.slice(0, remaining.value);
+        remaining.value -= retained.length;
+        const statuses = artifacts.map(({ status }) => status);
+        steps.push({
+            step_id: stepId,
+            before_step_index: beforeStep.step_index,
+            after_step_index: afterStep.step_index,
+            before_action: beforeStep.action,
+            after_action: afterStep.action,
+            status: statuses.includes("changed")
+                ? "changed"
+                : statuses.includes("unknown")
+                    ? "unknown"
+                    : "unchanged",
+            artifact_diffs: retained,
+            omitted_artifact_diffs: reportable.length - retained.length,
+        });
+    }
+    return { steps, failures, totalArtifactDiffs };
+};
+const duplicateStepIds = (steps) => {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const { step_id: stepId } of steps) {
+        if (seen.has(stepId))
+            duplicates.add(stepId);
+        seen.add(stepId);
+    }
+    return duplicates;
+};
+const uniqueSteps = (steps, duplicates) => new Map(steps.flatMap((step) => duplicates.has(step.step_id) ? [] : [[step.step_id, step]]));
+const duplicateFailures = (side, duplicates) => [...duplicates].sort().map((stepId) => ({
+    code: side === "before"
+        ? "duplicate_before_step_id"
+        : "duplicate_after_step_id",
+    step_id: stepId,
+    reason: `${side} capture contains duplicate step_id ${stepId}.`,
+}));
+const missingFailures = (side, stepIds) => stepIds.map((stepId) => ({
+    code: side === "before" ? "missing_before_step" : "missing_after_step",
+    step_id: stepId,
+    reason: `Step ${stepId} is missing from the ${side} capture.`,
+}));
+const captureContextsMatch = (before, after) => before.browser.product === after.browser.product &&
+    before.browser.version === after.browser.version &&
+    before.scenario.start_origin === after.scenario.start_origin &&
+    digestCanonicalJson([...before.scenario.allowed_origins].sort()) ===
+        digestCanonicalJson([...after.scenario.allowed_origins].sort());
+const compareStepArtifacts = (input) => {
+    const common = {
+        beforeStep: input.beforeStep,
+        afterStep: input.afterStep,
+        rules: input.rules,
+    };
+    return [
+        compareCapturedValues({
+            ...common,
+            artifact: "action_state",
+            before: captured(actionState(input.beforeStep)),
+            after: captured(actionState(input.afterStep)),
+        }),
+        compareCapturedValues({
+            ...common,
+            artifact: "screenshot",
+            before: input.beforeStep.artifacts.screenshot,
+            after: input.afterStep.artifacts.screenshot,
+            project: screenshotProjection,
+        }),
+        compareCapturedValues({
+            ...common,
+            artifact: "dom",
+            before: input.beforeStep.artifacts.dom,
+            after: input.afterStep.artifacts.dom,
+            project: ({ text }) => text,
+        }),
+        compareCapturedValues({
+            ...common,
+            artifact: "accessibility",
+            before: input.beforeStep.artifacts.accessibility,
+            after: input.afterStep.artifacts.accessibility,
+            project: ({ text }) => text,
+        }),
+        compareCapturedValues({
+            ...common,
+            artifact: "url",
+            before: input.beforeStep.artifacts.url,
+            after: input.afterStep.artifacts.url,
+        }),
+        compareCapturedValues({
+            ...common,
+            artifact: "history",
+            before: input.beforeStep.artifacts.history,
+            after: input.afterStep.artifacts.history,
+        }),
+        compareCapturedValues({
+            ...common,
+            artifact: "storage",
+            before: input.beforeStep.artifacts.storage,
+            after: input.afterStep.artifacts.storage,
+        }),
+        compareCapturedValues({
+            ...common,
+            artifact: "events",
+            before: captured(eventsFor(input.beforeCapture, input.beforeStep.step_index)),
+            after: captured(eventsFor(input.afterCapture, input.afterStep.step_index)),
+            beforeState: eventEvidenceState(input.beforeCapture, input.beforeStep),
+            afterState: eventEvidenceState(input.afterCapture, input.afterStep),
+        }),
+    ];
+};
+const compareCapturedValues = (input) => {
+    const { artifact, before, after, beforeStep, afterStep, rules, project = (value) => value, } = 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)
+        : null;
+    const afterSha256 = afterState === "captured" && after.state === "captured"
+        ? digestNormalizedScenarioValue(project(after.value), artifact, rules)
+        : null;
+    if (beforeState !== "captured" ||
+        afterState !== "captured" ||
+        before.state !== "captured" ||
+        after.state !== "captured")
+        return {
+            artifact,
+            status: "unknown",
+            diff: {
+                artifact,
+                status: "unknown",
+                before_state: beforeState,
+                after_state: afterState,
+                before_sha256: beforeSha256,
+                after_sha256: afterSha256,
+                reason: `Artifact coverage is not comparable (${beforeState} before, ${afterState} after).`,
+            },
+        };
+    if (beforeSha256 === null || afterSha256 === null)
+        throw new TypeError("Captured artifact digest refinement failed");
+    if (beforeSha256 === afterSha256)
+        return { artifact, status: "unchanged", diff: null };
+    return {
+        artifact,
+        status: "changed",
+        diff: {
+            artifact,
+            status: "changed",
+            before_state: beforeState,
+            after_state: afterState,
+            before_sha256: beforeSha256,
+            after_sha256: afterSha256,
+            reason: null,
+        },
+    };
+};
+const artifactEvidenceState = (artifact, state, step) => {
+    if (state.state !== "captured")
+        return state.state;
+    const section = artifact === "action_state" ? "action" : artifact;
+    if (step.completeness.truncated_sections.includes(section))
+        return "truncated";
+    if (step.completeness.missing_sections.includes(section))
+        return "missing";
+    return "captured";
+};
+const eventEvidenceState = (capture, step) => {
+    const sections = [
+        "events",
+        "frames",
+        "workers",
+        "popups",
+        "websockets",
+    ];
+    if (capture.events.dropped > 0 ||
+        sections.some((section) => capture.completeness.truncated_sections.includes(section) ||
+            step.completeness.truncated_sections.includes(section)))
+        return "truncated";
+    if (sections.some((section) => capture.completeness.missing_sections.includes(section) ||
+        step.completeness.missing_sections.includes(section)))
+        return "missing";
+    return "captured";
+};
+const actionState = (step) => ({
+    action: step.action,
+    status: step.status,
+    before_url: step.before_url,
+    after_url: step.after_url,
+    error: step.error,
+});
+const eventsFor = (capture, stepIndex) => capture.events.items.flatMap(({ sequence: _sequence, step_index: eventStepIndex, ...event }) => eventStepIndex === stepIndex ? [event] : []);
+const captured = (value) => ({
+    state: "captured",
+    value,
+});
+const screenshotProjection = (screenshot) => ({
+    sha256: screenshot.sha256,
+    bytes: screenshot.bytes,
+    media_type: screenshot.media_type,
+});

package/dist/domain/browserScenarioDiffValues.js

@@ -0,0 +1,157 @@
+import { z } from "zod";
+import { browserScenarioCaptureSchema } from "./browserScenarioCapture.js";
+/** Scenario artifact families compared after step alignment. */
+export const browserScenarioArtifactKindSchema = z.enum([
+    "action_state",
+    "screenshot",
+    "dom",
+    "accessibility",
+    "url",
+    "history",
+    "storage",
+    "events",
+]);
+const normalizableArtifactKindSchema = z.enum([
+    "action_state",
+    "dom",
+    "accessibility",
+    "url",
+    "history",
+    "storage",
+    "events",
+]);
+const normalizationRuleSchema = z.strictObject({
+    rule_id: z
+        .string()
+        .trim()
+        .min(1)
+        .max(64)
+        .describe("Stable rule identity; rules execute in rule_id order."),
+    artifacts: z
+        .array(normalizableArtifactKindSchema)
+        .min(1)
+        .max(7)
+        .describe("Artifact families whose durable string fields use this rule."),
+    match: z
+        .string()
+        .min(1)
+        .max(4_096)
+        .describe("Exact public literal to replace; regular expressions are not used."),
+    replacement: z
+        .string()
+        .max(4_096)
+        .describe("Recorded replacement text used in normalized comparison."),
+});
+const normalizationInputSchema = z
+    .strictObject({
+    rules: z.array(normalizationRuleSchema).max(128).default([]),
+})
+    .superRefine((normalization, context) => {
+    const ruleIds = new Set();
+    for (const [index, rule] of normalization.rules.entries()) {
+        if (ruleIds.has(rule.rule_id))
+            context.addIssue({
+                code: "custom",
+                path: ["rules", index, "rule_id"],
+                message: "Normalization rule IDs must be unique",
+            });
+        ruleIds.add(rule.rule_id);
+        if (new Set(rule.artifacts).size !== rule.artifacts.length)
+            context.addIssue({
+                code: "custom",
+                path: ["rules", index, "artifacts"],
+                message: "Normalization rule artifact kinds must be unique",
+            });
+    }
+});
+/** Input for step-aligned comparison of two browser scenario captures. */
+export const compareBrowserScenariosInputSchema = z.strictObject({
+    before_scenario: browserScenarioCaptureSchema.describe("Earlier complete capture_browser_scenario result."),
+    after_scenario: browserScenarioCaptureSchema.describe("Later complete capture_browser_scenario result."),
+    normalization: normalizationInputSchema
+        .default({ rules: [] })
+        .describe("Bounded exact-literal rules committed in the comparison result."),
+    max_changes: z
+        .number()
+        .int()
+        .min(1)
+        .max(20_000)
+        .default(2_000)
+        .describe("Maximum changed or unknown artifact records to retain."),
+});
+const evidenceStateSchema = z.enum([
+    "captured",
+    "not_requested",
+    "missing",
+    "truncated",
+]);
+const artifactDiffSchema = z.strictObject({
+    artifact: browserScenarioArtifactKindSchema,
+    status: z.enum(["changed", "unknown"]),
+    before_state: evidenceStateSchema,
+    after_state: evidenceStateSchema,
+    before_sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    after_sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    reason: z.string().min(1).max(2_048).nullable(),
+});
+const alignmentFailureSchema = z.strictObject({
+    code: z.enum([
+        "duplicate_before_step_id",
+        "duplicate_after_step_id",
+        "missing_before_step",
+        "missing_after_step",
+        "action_mismatch",
+        "capture_context_mismatch",
+    ]),
+    step_id: z.string().min(1).max(64).nullable(),
+    reason: z.string().min(1).max(2_048),
+});
+const builtInNormalizationSchema = z.enum([
+    "ignore_step_elapsed_ms",
+    "ignore_event_sequence",
+    "ignore_event_step_index",
+    "compare_screenshot_content_digest",
+    "compare_normalized_text_content",
+]);
+/** Step alignment, recorded normalization, and bounded artifact differences. */
+export const browserScenarioDiffSchema = z.strictObject({
+    schema_version: z.literal(1),
+    comparison_kind: z.literal("browser_scenario"),
+    overall_status: z.enum(["changed", "unchanged", "unknown"]),
+    normalization: z.strictObject({
+        built_in_rules: z.array(builtInNormalizationSchema).length(5),
+        rules: z.array(normalizationRuleSchema).max(128),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    }),
+    alignment: z.strictObject({
+        status: z.enum(["aligned", "partial", "failed"]),
+        aligned_steps: z.number().int().min(0).max(129),
+        before_only: z.array(z.string().min(1).max(64)).max(129),
+        after_only: z.array(z.string().min(1).max(64)).max(129),
+        failures: z.array(alignmentFailureSchema).max(520),
+    }),
+    steps: z
+        .array(z.strictObject({
+        step_id: z.string().min(1).max(64),
+        before_step_index: z.number().int().min(0).max(128),
+        after_step_index: z.number().int().min(0).max(128),
+        before_action: z.string().min(1).max(64),
+        after_action: z.string().min(1).max(64),
+        status: z.enum(["changed", "unchanged", "unknown"]),
+        artifact_diffs: z.array(artifactDiffSchema).max(8),
+        omitted_artifact_diffs: z.number().int().min(0).max(8),
+    }))
+        .max(129),
+    artifact_diffs: z.strictObject({
+        total: z.number().int().min(0).max(1_032),
+        retained: z.number().int().min(0).max(1_032),
+        omitted: z.number().int().min(0).max(1_032),
+    }),
+    limitations: z.array(z.string().min(1).max(2_048)).max(64),
+});

package/dist/domain/browserScenarioNormalization.js

@@ -0,0 +1,45 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+const BUILT_IN_RULES = [
+    "ignore_step_elapsed_ms",
+    "ignore_event_sequence",
+    "ignore_event_step_index",
+    "compare_screenshot_content_digest",
+    "compare_normalized_text_content",
+];
+/** Canonically order and commit a parsed browser scenario normalization policy. */
+export const commitBrowserScenarioNormalization = (input) => {
+    const rules = [...input.rules]
+        .map((rule) => ({
+        ...rule,
+        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 };
+    return { ...commitment, sha256: digestCanonicalJson(commitment) };
+};
+/** Digest one artifact after applying committed exact-literal rules. */
+export const digestNormalizedScenarioValue = (value, artifact, rules) => digestCanonicalJson(normalize(value, artifact, rules));
+/** Compute a canonical SHA-256 commitment for JSON-compatible domain data. */
+export const digestCanonicalJson = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Expected canonical JSON");
+    return createHash("sha256").update(encoded).digest("hex");
+};
+const normalize = (value, artifact, rules) => {
+    if (artifact === "screenshot")
+        return value;
+    if (typeof value === "string")
+        return 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));
+    if (typeof value !== "object" || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        normalize(item, artifact, rules),
+    ]));
+};