rea-agents 2.1.0 → 2.3.0

package/dist/domain/processTraceComparison.js

@@ -0,0 +1,43 @@
+import { validateProcessCapture } from "./processCaptureValidation.js";
+import { evaluateProcessTraceSide, processTraceComparisonResultSchema, } from "./processTraceEvaluation.js";
+import { processTraceSpecificationSchema, } from "./processTraceSpecification.js";
+export { processTraceComparisonResultSchema, } from "./processTraceEvaluation.js";
+export { processTraceSourceSchema, processTraceSpecificationSchema, } from "./processTraceSpecification.js";
+/** Compare two captures against an explicit finite trace language. */
+export const compareProcessTraces = (left, right, specificationInput) => {
+    const captureIssues = [
+        ...validateProcessCapture(left),
+        ...validateProcessCapture(right),
+    ];
+    if (captureIssues.length > 0)
+        throw new TypeError(`Invalid Process Capture v4: ${captureIssues[0].path}`);
+    const specification = processTraceSpecificationSchema.parse(specificationInput);
+    const leftEvaluation = evaluateProcessTraceSide(left, specification);
+    const rightEvaluation = evaluateProcessTraceSide(right, specification);
+    const diagnostic = leftEvaluation.diagnostic === null
+        ? rightEvaluation.diagnostic === null
+            ? null
+            : { side: "right", ...rightEvaluation.diagnostic }
+        : { side: "left", ...leftEvaluation.diagnostic };
+    const outcomesDiffer = leftEvaluation.result.status !== rightEvaluation.result.status ||
+        JSON.stringify(leftEvaluation.result.raw_trace.map(({ event_id }) => event_id)) !==
+            JSON.stringify(rightEvaluation.result.raw_trace.map(({ event_id }) => event_id));
+    return processTraceComparisonResultSchema.parse({
+        verdict: leftEvaluation.result.status === "unknown" ||
+            rightEvaluation.result.status === "unknown"
+            ? "unknown"
+            : leftEvaluation.result.status === "pass" &&
+                rightEvaluation.result.status === "pass"
+                ? "equivalent"
+                : outcomesDiffer
+                    ? "different"
+                    : "nonconforming",
+        left: leftEvaluation.result,
+        right: rightEvaluation.result,
+        diagnostic,
+    });
+};
+/** Whether trace conformance or raw declared order differs across captures. */
+export const processTraceOutcomesDiffer = (comparison) => comparison.left.status !== comparison.right.status ||
+    JSON.stringify(comparison.left.raw_trace.map(({ event_id }) => event_id)) !==
+        JSON.stringify(comparison.right.raw_trace.map(({ event_id }) => event_id));

package/dist/domain/processTraceDimensionProjection.js

@@ -0,0 +1,50 @@
+/** Map declared trace sources to legacy process-comparison dimensions. */
+export const dimensionsForTraceSources = (sources) => {
+    const dimensions = new Set();
+    for (const source of sources) {
+        if (source.startsWith("terminal_"))
+            dimensions.add("terminal");
+        else if (source === "interaction")
+            dimensions.add("interaction");
+        else if (source === "lifecycle")
+            dimensions.add("exit");
+        else if (source === "filesystem")
+            dimensions.add("filesystem");
+        else if (source === "http" ||
+            source === "websocket" ||
+            source === "replay_transition")
+            dimensions.add("protocol");
+        else if (source === "process")
+            dimensions.add("process");
+        else if (source === "shim")
+            dimensions.add("shim");
+    }
+    return dimensions;
+};
+/** Whether a trace specification covers every observed source in a dimension. */
+export const traceCoversObservedDimension = (dimension, sources, left, right) => {
+    const any = (leftValues, rightValues) => leftValues.length > 0 || rightValues.length > 0;
+    switch (dimension) {
+        case "terminal":
+            return ((!any(left.frames, right.frames) || sources.has("terminal_raw")) &&
+                (!any(left.rendered_frames, right.rendered_frames) ||
+                    sources.has("terminal_rendered")));
+        case "interaction":
+            return sources.has("interaction");
+        case "exit":
+            return sources.has("lifecycle");
+        case "filesystem":
+            return false;
+        case "protocol":
+            return ((![...left.protocol_events, ...right.protocol_events].some(({ protocol }) => protocol === "http") ||
+                sources.has("http")) &&
+                (![...left.protocol_events, ...right.protocol_events].some(({ protocol }) => protocol === "websocket") ||
+                    sources.has("websocket")) &&
+                (!any(left.replay_transitions, right.replay_transitions) ||
+                    sources.has("replay_transition")));
+        case "process":
+            return sources.has("process");
+        case "shim":
+            return sources.has("shim");
+    }
+};

package/dist/domain/processTraceEvaluation.js

@@ -0,0 +1,312 @@
+import { z } from "zod";
+import { processObservationLocationSchema, projectProcessObservation, } from "./processObservation.js";
+import { canonicalTraceJson, comparableTracePayload, processTraceCardinalityBounds, } from "./processTraceSpecification.js";
+const identifierSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._-]{0,63}$/u);
+const locationSchema = processObservationLocationSchema;
+const matchedEventSchema = z.strictObject({
+    event_id: identifierSchema,
+    location: locationSchema,
+});
+const sideResultSchema = z.strictObject({
+    status: z.enum(["pass", "fail", "unknown"]),
+    matched_variant: identifierSchema.nullable(),
+    satisfied_constraints: z.array(z.string()),
+    raw_trace: z.array(matchedEventSchema),
+});
+const diagnosticSchema = z.strictObject({
+    kind: z.enum([
+        "journal",
+        "predicate",
+        "cardinality",
+        "edge",
+        "prefix",
+        "suffix",
+        "trace",
+    ]),
+    side: z.enum(["left", "right"]),
+    message: z.string(),
+    event_ids: z.array(identifierSchema),
+    locations: z.array(locationSchema),
+});
+/** Structured verdict for one declared process trace language. */
+export const processTraceComparisonResultSchema = z.strictObject({
+    verdict: z.enum(["equivalent", "different", "nonconforming", "unknown"]),
+    left: sideResultSchema,
+    right: sideResultSchema,
+    diagnostic: diagnosticSchema.nullable(),
+});
+const scopesFor = (sources) => new Set([...sources].map((source) => {
+    if (source.startsWith("terminal_"))
+        return "terminal";
+    if (source === "lifecycle")
+        return "exit";
+    if (source === "http" ||
+        source === "websocket" ||
+        source === "replay_transition")
+        return "protocol";
+    if (source === "filesystem")
+        return "filesystem";
+    if (source === "process")
+        return "process";
+    if (source === "shim")
+        return "shim";
+    return "interaction";
+}));
+const unknownSide = () => ({
+    status: "unknown",
+    matched_variant: null,
+    satisfied_constraints: [],
+    raw_trace: [],
+});
+const failure = (input) => ({
+    result: {
+        status: "fail",
+        matched_variant: null,
+        satisfied_constraints: [],
+        raw_trace: input.rawTrace,
+    },
+    diagnostic: {
+        kind: input.kind,
+        message: input.message,
+        event_ids: [...input.eventIds],
+        locations: [...input.locations],
+    },
+});
+const evaluateFiniteTrace = (ids, specification) => {
+    if (specification.language.kind !== "finite_traces")
+        return null;
+    for (const variant of specification.language.variants) {
+        let offset = 0;
+        let accepted = true;
+        for (const token of variant.trace) {
+            if (typeof token === "string") {
+                if (ids[offset] !== token)
+                    accepted = false;
+                offset += 1;
+                continue;
+            }
+            const actual = ids.slice(offset, offset + token.unordered.length).sort();
+            const expected = [...token.unordered].sort();
+            if (canonicalTraceJson(actual) !== canonicalTraceJson(expected))
+                accepted = false;
+            offset += token.unordered.length;
+        }
+        if (accepted && offset === ids.length)
+            return variant.id;
+    }
+    return null;
+};
+const collectRecords = (capture, sources) => {
+    const records = [];
+    for (const location of capture.event_journal ?? []) {
+        const record = projectProcessObservation(capture, location);
+        if (record !== null && sources.has(record.source))
+            records.push({
+                source: record.source,
+                payload: record.payload,
+                location,
+            });
+    }
+    return records;
+};
+const matchRecords = (records, specification) => {
+    const rawTrace = [];
+    const locationsById = new Map();
+    const ignoredFieldsBySource = new Map();
+    const eventsByKey = new Map();
+    for (const event of specification.events) {
+        const ignoredFields = event.ignore_fields ?? [];
+        ignoredFieldsBySource.set(event.source, ignoredFields);
+        eventsByKey.set(`${event.source}\0${canonicalTraceJson(comparableTracePayload(event.exact, ignoredFields))}`, event);
+    }
+    for (const record of records) {
+        const match = eventsByKey.get(`${record.source}\0${canonicalTraceJson(comparableTracePayload(record.payload, ignoredFieldsBySource.get(record.source)))}`);
+        if (match === undefined)
+            return failure({
+                kind: "predicate",
+                message: "Observed event does not match any declared exact predicate.",
+                eventIds: [],
+                locations: [record.location],
+                rawTrace,
+            });
+        rawTrace.push({ event_id: match.id, location: record.location });
+        const locations = locationsById.get(match.id) ?? [];
+        locations.push(record.location);
+        locationsById.set(match.id, locations);
+    }
+    return { rawTrace, locationsById };
+};
+const cardinalityFailure = (trace, specification) => {
+    for (const event of specification.events) {
+        const [minimum, maximum] = processTraceCardinalityBounds(event.cardinality);
+        const locations = trace.locationsById.get(event.id) ?? [];
+        if (locations.length < minimum || locations.length > maximum)
+            return failure({
+                kind: "cardinality",
+                message: `${event.id} observed ${String(locations.length)} times; expected ${String(minimum)}..${String(maximum)}.`,
+                eventIds: [event.id],
+                locations,
+                rawTrace: trace.rawTrace,
+            });
+    }
+    return null;
+};
+const evaluateOrderingConstraints = (trace, language) => {
+    const satisfied = [];
+    for (const edge of language.happens_before) {
+        const before = trace.locationsById.get(edge.before) ?? [];
+        const after = trace.locationsById.get(edge.after) ?? [];
+        const lastBefore = before.at(-1);
+        const firstAfter = after[0];
+        if (lastBefore === undefined && firstAfter !== undefined)
+            return {
+                failure: failure({
+                    kind: "edge",
+                    message: `${edge.before} is required when ${edge.after} occurs.`,
+                    eventIds: [edge.before, edge.after],
+                    locations: [firstAfter],
+                    rawTrace: trace.rawTrace,
+                }),
+                satisfied,
+            };
+        if (lastBefore !== undefined &&
+            firstAfter !== undefined &&
+            lastBefore.capture_order >= firstAfter.capture_order)
+            return {
+                failure: failure({
+                    kind: "edge",
+                    message: `${edge.before} must happen before ${edge.after}.`,
+                    eventIds: [edge.before, edge.after],
+                    locations: [lastBefore, firstAfter],
+                    rawTrace: trace.rawTrace,
+                }),
+                satisfied,
+            };
+        satisfied.push(`happens_before:${edge.before}:${edge.after}`);
+    }
+    for (const constraint of language.not_before) {
+        const events = trace.locationsById.get(constraint.event) ?? [];
+        const anchors = trace.locationsById.get(constraint.anchor) ?? [];
+        const firstEvent = events[0];
+        const firstAnchor = anchors[0];
+        if (firstEvent !== undefined && firstAnchor === undefined)
+            return {
+                failure: failure({
+                    kind: "edge",
+                    message: `${constraint.anchor} is required when ${constraint.event} occurs.`,
+                    eventIds: [constraint.event, constraint.anchor],
+                    locations: [firstEvent],
+                    rawTrace: trace.rawTrace,
+                }),
+                satisfied,
+            };
+        if (firstEvent !== undefined &&
+            firstAnchor !== undefined &&
+            firstEvent.capture_order < firstAnchor.capture_order)
+            return {
+                failure: failure({
+                    kind: "edge",
+                    message: `${constraint.event} must not occur before ${constraint.anchor}.`,
+                    eventIds: [constraint.event, constraint.anchor],
+                    locations: [firstEvent, firstAnchor],
+                    rawTrace: trace.rawTrace,
+                }),
+                satisfied,
+            };
+        satisfied.push(`not_before:${constraint.event}:${constraint.anchor}`);
+    }
+    return { failure: null, satisfied };
+};
+const boundaryFailure = (trace, kind, expected) => {
+    const ids = trace.rawTrace.map(({ event_id }) => event_id);
+    const actual = kind === "prefix"
+        ? ids.slice(0, expected.length)
+        : expected.length === 0
+            ? []
+            : ids.slice(-expected.length);
+    if (canonicalTraceJson(actual) === canonicalTraceJson(expected))
+        return null;
+    const locations = kind === "prefix"
+        ? trace.rawTrace.slice(0, expected.length)
+        : trace.rawTrace.slice(-expected.length);
+    return failure({
+        kind,
+        message: `Observed trace does not satisfy the declared ${kind}.`,
+        eventIds: expected,
+        locations: locations.map(({ location }) => location),
+        rawTrace: trace.rawTrace,
+    });
+};
+const evaluatePartialOrder = (trace, language) => {
+    const ordering = evaluateOrderingConstraints(trace, language);
+    if (ordering.failure !== null)
+        return ordering.failure;
+    const prefixFailure = boundaryFailure(trace, "prefix", language.prefix);
+    if (prefixFailure !== null)
+        return prefixFailure;
+    const suffixFailure = boundaryFailure(trace, "suffix", language.suffix);
+    if (suffixFailure !== null)
+        return suffixFailure;
+    const satisfied = ordering.satisfied;
+    satisfied.push(...language.unordered_groups.map(({ events }) => `unordered:${events.join(":")}`));
+    if (language.prefix.length > 0)
+        satisfied.push(`prefix:${language.prefix.join(":")}`);
+    if (language.suffix.length > 0)
+        satisfied.push(`suffix:${language.suffix.join(":")}`);
+    return {
+        result: {
+            status: "pass",
+            matched_variant: null,
+            satisfied_constraints: satisfied,
+            raw_trace: trace.rawTrace,
+        },
+        diagnostic: null,
+    };
+};
+const evaluateMatchedTrace = (trace, specification) => {
+    const invalidCardinality = cardinalityFailure(trace, specification);
+    if (invalidCardinality !== null)
+        return invalidCardinality;
+    if (specification.language.kind === "partial_order")
+        return evaluatePartialOrder(trace, specification.language);
+    const ids = trace.rawTrace.map(({ event_id }) => event_id);
+    const variant = evaluateFiniteTrace(ids, specification);
+    return variant === null
+        ? failure({
+            kind: "trace",
+            message: "Observed events do not match any finite trace variant.",
+            eventIds: ids,
+            locations: trace.rawTrace.map(({ location }) => location),
+            rawTrace: trace.rawTrace,
+        })
+        : {
+            result: {
+                status: "pass",
+                matched_variant: variant,
+                satisfied_constraints: [`variant:${variant}`],
+                raw_trace: trace.rawTrace,
+            },
+            diagnostic: null,
+        };
+};
+export const evaluateProcessTraceSide = (capture, specification) => {
+    const sources = new Set(specification.events.map(({ source }) => source));
+    const relevantScopes = scopesFor(sources);
+    if (capture.truncated ||
+        capture.residual_unknowns.some(({ scope }) => relevantScopes.has(scope)))
+        return { result: unknownSide(), diagnostic: null };
+    if ((capture.event_journal ?? []).length === 0)
+        return {
+            result: unknownSide(),
+            diagnostic: {
+                kind: "journal",
+                message: "Capture has no cross-source event journal.",
+                event_ids: [],
+                locations: [],
+            },
+        };
+    const matched = matchRecords(collectRecords(capture, sources), specification);
+    return "rawTrace" in matched
+        ? evaluateMatchedTrace(matched, specification)
+        : matched;
+};