reverseport 0.0.0-stage → 1.2.0

package/dist/domain/browserScenarioCaptureValues.js

@@ -0,0 +1,292 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { emptyArraySchema } from "./emptyArraySchema.js";
+import { browserNetworkBodySchema, browserNetworkHeadersSchema, } from "./browserNetworkEvidence.js";
+import { sanitizedBrowserUrlSchema } from "./browserObservation.js";
+import { webScreenshotArtifactSchema } from "./webScreenshot.js";
+import { digestSchema } from "./../domain/digests.js";
+const textArtifactSchema = z
+    .strictObject({
+    sha256: digestSchema,
+    bytes: z.number().int().min(0),
+    text: z.string(),
+})
+    .superRefine((artifact, context) => {
+    const bytes = Buffer.from(artifact.text);
+    const sha256 = createHash("sha256").update(bytes).digest("hex");
+    if (bytes.byteLength !== artifact.bytes || sha256 !== artifact.sha256)
+        context.addIssue({
+            code: "custom",
+            message: "Text artifact digest or size mismatch",
+        });
+});
+export const captureStateSchema = (value) => z.discriminatedUnion("state", [
+    z.strictObject({ state: z.literal("captured"), value }),
+    z.strictObject({
+        state: z.literal("not_requested"),
+    }),
+    z.strictObject({
+        state: z.literal("missing"),
+        reason: z.string().min(1),
+    }),
+    z.strictObject({
+        state: z.literal("truncated"),
+        observed: z.number().int().min(0),
+        retained: z.number().int().min(0),
+        reason: z.string().min(1),
+    }),
+]);
+const historySchema = z.strictObject({
+    length: z.number().int().min(0),
+    current_url: sanitizedBrowserUrlSchema,
+    navigation_entries: z.array(z.strictObject({
+        type: z.enum([
+            "navigate",
+            "reload",
+            "back_forward",
+            "prerender",
+            "unknown",
+        ]),
+        name: sanitizedBrowserUrlSchema,
+    })),
+});
+const hashedStorageValueShape = {
+    value_state: z.literal("hashed"),
+    value_sha256: digestSchema,
+};
+const redactedStorageValueShape = {
+    value_state: z.literal("redacted-secret"),
+    value_sha256: z.null(),
+};
+const storageValueFingerprintSchema = z.discriminatedUnion("value_state", [
+    z.strictObject(hashedStorageValueShape),
+    z.strictObject(redactedStorageValueShape),
+]);
+const storageValueSchema = z.discriminatedUnion("value_state", [
+    z.strictObject({
+        name: z.string(),
+        ...hashedStorageValueShape,
+    }),
+    z.strictObject({
+        name: z.string(),
+        ...redactedStorageValueShape,
+    }),
+]);
+const cookieShape = {
+    name: z.string(),
+    domain: z.string(),
+    path: z.string(),
+    secure: z.boolean(),
+    http_only: z.boolean(),
+    same_site: z.enum(["Strict", "Lax", "None"]),
+};
+const storageSnapshotSchema = z.strictObject({
+    cookies: z.array(z.discriminatedUnion("value_state", [
+        z.strictObject({ ...cookieShape, ...hashedStorageValueShape }),
+        z.strictObject({ ...cookieShape, ...redactedStorageValueShape }),
+    ])),
+    local_storage: z.array(storageValueSchema),
+    session_storage: z.array(storageValueSchema),
+});
+export const browserStepArtifactsSchema = z.strictObject({
+    screenshot: captureStateSchema(webScreenshotArtifactSchema),
+    dom: captureStateSchema(textArtifactSchema),
+    accessibility: captureStateSchema(textArtifactSchema),
+    url: captureStateSchema(sanitizedBrowserUrlSchema),
+    history: captureStateSchema(historySchema),
+    storage: captureStateSchema(storageSnapshotSchema),
+});
+const eventBase = {
+    sequence: z.number().int().min(1),
+    step_index: z.number().int().min(0),
+};
+const eventUrl = sanitizedBrowserUrlSchema.nullable();
+const networkEventShape = {
+    ...eventBase,
+    transaction_id: z.string().min(1),
+    redirected_from_transaction_id: z.string().min(1).nullable(),
+    method: z.string().min(1),
+    url: sanitizedBrowserUrlSchema,
+    resource_type: z.string().min(1),
+    header_names: z.array(z.string()),
+};
+const webSocketFrameShape = {
+    ...eventBase,
+    kind: z.enum(["websocket-frame-sent", "websocket-frame-received"]),
+    url: sanitizedBrowserUrlSchema,
+    payload_bytes: z.number().int().min(0),
+    truncated: z.boolean(),
+};
+export const browserScenarioEventSchema = z.union([
+    z.strictObject({
+        ...eventBase,
+        kind: z.literal("console"),
+        level: z.string().min(1),
+        text: z.string(),
+        url: eventUrl,
+    }),
+    z.strictObject({
+        ...eventBase,
+        kind: z.literal("page-error"),
+        message: z.string(),
+        stack: z.string().nullable(),
+    }),
+    z.strictObject({
+        ...networkEventShape,
+        kind: z.literal("request"),
+        status: z.null(),
+        failure: z.null(),
+    }),
+    z.strictObject({
+        ...networkEventShape,
+        kind: z.literal("response"),
+        status: z.number().int().min(100).max(599),
+        failure: z.null(),
+    }),
+    z.strictObject({
+        ...networkEventShape,
+        kind: z.literal("request-failed"),
+        status: z.null(),
+        failure: z.string().min(1),
+    }),
+    z.strictObject({
+        ...networkEventShape,
+        kind: z.literal("request-finished"),
+        status: z.null(),
+        failure: z.null(),
+    }),
+    z.strictObject({
+        ...networkEventShape,
+        kind: z.literal("request-unfinished"),
+        status: z.null(),
+        failure: z.null(),
+        reason: z.enum(["capture-ended", "cancelled"]),
+    }),
+    z.strictObject({
+        ...eventBase,
+        kind: z.literal("network-content"),
+        transaction_id: z.string().min(1),
+        source_event_sequence: z.number().int().min(1),
+        phase: z.enum(["request", "response"]),
+        headers: browserNetworkHeadersSchema,
+        body: browserNetworkBodySchema,
+    }),
+    z.strictObject({
+        ...eventBase,
+        kind: z.enum(["websocket-opened", "websocket-closed"]),
+        url: sanitizedBrowserUrlSchema,
+    }),
+    z.strictObject({
+        ...webSocketFrameShape,
+        payload_type: z.literal("text"),
+        payload_text: z.string(),
+    }),
+    z.strictObject({
+        ...webSocketFrameShape,
+        payload_type: z.literal("binary"),
+        payload_text: z.null(),
+    }),
+    z.strictObject({
+        ...eventBase,
+        kind: z.enum([
+            "frame-attached",
+            "frame-detached",
+            "frame-navigated",
+            "worker-created",
+            "worker-closed",
+            "popup-opened",
+            "popup-closed",
+        ]),
+        url: eventUrl,
+        name: z.string().nullable(),
+    }),
+    z.strictObject({
+        ...eventBase,
+        kind: z.literal("download-cancelled"),
+        suggested_filename: z.string(),
+        url: sanitizedBrowserUrlSchema,
+    }),
+]);
+const completenessSectionSchema = z.enum([
+    "action",
+    "screenshot",
+    "dom",
+    "accessibility",
+    "url",
+    "history",
+    "storage",
+    "events",
+    "frames",
+    "workers",
+    "popups",
+    "websockets",
+]);
+export const browserScenarioCompletenessSchema = z.discriminatedUnion("status", [
+    z.strictObject({
+        status: z.literal("complete"),
+        equality_eligible: z.literal(true),
+        missing_sections: emptyArraySchema,
+        truncated_sections: emptyArraySchema,
+    }),
+    z.strictObject({
+        status: z.literal("incomplete"),
+        equality_eligible: z.literal(false),
+        missing_sections: z.array(completenessSectionSchema).min(1),
+        truncated_sections: emptyArraySchema,
+    }),
+    z.strictObject({
+        status: z.literal("truncated"),
+        equality_eligible: z.literal(false),
+        missing_sections: z.array(completenessSectionSchema),
+        truncated_sections: z.array(completenessSectionSchema).min(1),
+    }),
+]);
+/** Classify canonical browser-scenario completeness from section accounting. */
+export const classifyBrowserScenarioCompleteness = (missing, truncated) => {
+    const missingSections = [...new Set(missing)].sort();
+    const truncatedSections = [...new Set(truncated)].sort();
+    if (truncatedSections.length > 0)
+        return browserScenarioCompletenessSchema.parse({
+            status: "truncated",
+            equality_eligible: false,
+            missing_sections: missingSections,
+            truncated_sections: truncatedSections,
+        });
+    if (missingSections.length > 0)
+        return browserScenarioCompletenessSchema.parse({
+            status: "incomplete",
+            equality_eligible: false,
+            missing_sections: missingSections,
+            truncated_sections: [],
+        });
+    return {
+        status: "complete",
+        equality_eligible: true,
+        missing_sections: [],
+        truncated_sections: [],
+    };
+};
+const browserScenarioStepShape = {
+    step_index: z.number().int().min(0),
+    step_id: z.string().min(1),
+    action: z.string().min(1),
+    elapsed_ms: z.number().int().min(0),
+    before_url: sanitizedBrowserUrlSchema,
+    after_url: sanitizedBrowserUrlSchema,
+    event_sequence_start: z.number().int().min(1),
+    event_sequence_end: z.number().int().min(0),
+    artifacts: browserStepArtifactsSchema,
+    completeness: browserScenarioCompletenessSchema,
+};
+export const browserScenarioStepSchema = z.union([
+    z.strictObject({
+        ...browserScenarioStepShape,
+        status: z.literal("completed"),
+        error: z.null(),
+    }),
+    z.strictObject({
+        ...browserScenarioStepShape,
+        status: z.enum(["failed", "cancelled"]),
+        error: z.string(),
+    }),
+]);

package/dist/domain/browserScenarioDiff.js

@@ -0,0 +1,266 @@
+import { actionState, artifactEvidenceState, captured, eventEvidenceState, eventsFor, networkContentCoverageReason, screenshotProjection, } from "./browserScenarioDiffEvidence.js";
+import { browserScenarioDiffSchema, } from "./browserScenarioDiffValues.js";
+import { commitBrowserScenarioNormalization, digestNormalizedScenarioValue, } from "./browserScenarioNormalization.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,
+    });
+    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({
+        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,
+        },
+        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.",
+        ],
+    });
+};
+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) => {
+    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 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: reportable,
+        });
+    }
+    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;
+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),
+            incomparableReason: networkContentCoverageReason(input.beforeCapture, input.afterCapture),
+        }),
+    ];
+};
+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" ||
+        input.incomparableReason !== undefined)
+        return {
+            artifact,
+            status: "unknown",
+            diff: {
+                artifact,
+                status: "unknown",
+                before_state: beforeState,
+                after_state: afterState,
+                before_sha256: beforeSha256,
+                after_sha256: afterSha256,
+                reason: input.incomparableReason ??
+                    `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,
+        },
+    };
+};

package/dist/domain/browserScenarioDiffEvidence.js

@@ -0,0 +1,73 @@
+const includesCompletenessSection = (completeness, collection, section) => {
+    const sections = completeness[collection];
+    return sections.includes(section);
+};
+/** Project one captured artifact through its step-level completeness ledger. */
+export const artifactEvidenceState = (artifact, state, step) => {
+    if (state.state !== "captured")
+        return state.state;
+    const section = artifact === "action_state" ? "action" : artifact;
+    if (includesCompletenessSection(step.completeness, "truncated_sections", section))
+        return "truncated";
+    return includesCompletenessSection(step.completeness, "missing_sections", section)
+        ? "missing"
+        : "captured";
+};
+const EVENT_SECTIONS = [
+    "events",
+    "frames",
+    "workers",
+    "popups",
+    "websockets",
+];
+/** Project event evidence through capture- and step-level completeness. */
+export const eventEvidenceState = (capture, step) => {
+    const listed = (collection) => EVENT_SECTIONS.some((section) => includesCompletenessSection(capture.completeness, collection, section) ||
+        includesCompletenessSection(step.completeness, collection, section));
+    if (capture.events.dropped > 0 || listed("truncated_sections"))
+        return "truncated";
+    return listed("missing_sections") ? "missing" : "captured";
+};
+/** Select stable action fields for normalized comparison. */
+export const actionState = (step) => ({
+    action: step.action,
+    status: step.status,
+    before_url: step.before_url,
+    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] : [];
+    });
+};
+/** Different content selection is missing comparability, not an observed website change. */
+export const networkContentCoverageReason = (before, after) => {
+    const left = before.scenario.network_content;
+    const right = after.scenario.network_content;
+    return left.request_body !== right.request_body ||
+        left.response_body !== right.response_body ||
+        left.header_values !== right.header_values
+        ? "Network content selections differ; capture both sides with matching content selection before comparing network evidence."
+        : undefined;
+};
+/** Wrap one value as captured comparison evidence. */
+export const captured = (value) => ({
+    state: "captured",
+    value,
+});
+/** Retain stable screenshot identity without embedding image bytes. */
+export const screenshotProjection = (screenshot) => ({
+    sha256: screenshot.sha256,
+    bytes: screenshot.bytes,
+    media_type: screenshot.media_type,
+});