rea-agents 2.2.0 → 2.3.0

package/dist/domain/processCaptureValidation.js

@@ -1,3 +1,4 @@
+import { replayMachineSchema } from "./replayMachine.js";
 import { digestProcessCommitment } from "./processScenario.js";
 const orderedTimestamps = (values) => values.every((value, index) => index === 0 || value.at_ms >= values[index - 1].at_ms);
 const validateCommitments = (capture, require) => {
@@ -23,6 +24,7 @@ const validateOrdering = (capture, require) => {
         ["interaction_events", capture.interaction_events],
         ["shim_events", capture.shim_events],
         ["protocol_events", capture.protocol_events],
+        ["replay_transitions", capture.replay_transitions],
     ])
         require(values.every(({ sequence }, index) => sequence === index), name, "sequence values must be contiguous from zero");
     for (const [name, values] of [
@@ -32,9 +34,40 @@ const validateOrdering = (capture, require) => {
         ["filesystem_checkpoints", capture.filesystem_checkpoints],
         ["shim_events", capture.shim_events],
         ["protocol_events", capture.protocol_events],
+        ["replay_transitions", capture.replay_transitions],
     ])
         require(orderedTimestamps(values), name, "timestamps must be ordered");
 };
+const journalCollectionSizes = (capture) => ({
+    frames: capture.frames.length,
+    rendered_frames: capture.rendered_frames.length,
+    interaction_events: capture.interaction_events.length,
+    lifecycle: 2,
+    process_samples: capture.process_samples.length,
+    filesystem_checkpoints: capture.filesystem_checkpoints.length,
+    shim_events: capture.shim_events.length,
+    protocol_events: capture.protocol_events.length,
+    replay_transitions: capture.replay_transitions.length,
+});
+const validateEventJournal = (capture, require) => {
+    const journal = capture.event_journal ?? [];
+    if (journal.length === 0)
+        return;
+    const sizes = journalCollectionSizes(capture);
+    const references = new Set();
+    for (const [position, entry] of journal.entries()) {
+        require(entry.capture_order ===
+            position, `event_journal.${String(position)}.capture_order`, "capture order must be contiguous from zero");
+        require(entry.index <
+            sizes[entry.collection], `event_journal.${String(position)}.index`, "journal reference is outside its capture collection");
+        const reference = `${entry.collection}:${String(entry.index)}`;
+        require(!references.has(reference), `event_journal.${String(position)}`, "journal references must be unique");
+        references.add(reference);
+    }
+    const expectedSize = Object.values(sizes).reduce((total, size) => total + size, 0);
+    require(journal.length ===
+        expectedSize, "event_journal", "nonempty journal must reference every captured observation");
+};
 const validateLifecycle = (capture, require) => {
     const checkpointNames = capture.filesystem_checkpoints.map(({ name }) => name);
     require(new Set(checkpointNames).size ===
@@ -89,23 +122,78 @@ const validateShimEvents = (capture, require) => {
             maximum, "shim_events", "matched shim events exceed the declared route max_calls");
     }
 };
-const validateReplayEvents = (capture, require) => {
-    const { replay_plan: replayPlan } = capture.manifest;
-    const routes = "http" in replayPlan && Array.isArray(replayPlan.http)
-        ? replayPlan.http
-        : [];
+const isRecord = (value) => typeof value === "object" && value !== null;
+const machinePlan = (replayPlan) => {
+    const parsed = replayMachineSchema.safeParse(replayPlan["machine"]);
+    return parsed.success ? parsed.data : undefined;
+};
+const matchesHttpPlan = (value, event) => {
+    if (!isRecord(value))
+        return false;
+    const route = isRecord(value["trigger"]) ? value["trigger"] : value;
+    return ((route["protocol"] === undefined || route["protocol"] === "http") &&
+        route["method"] === event.method &&
+        route["path"] === event.path);
+};
+const validateMatchedHttpEvents = (capture, plans, require) => {
     for (const event of capture.protocol_events) {
         if (event.protocol !== "http" ||
             event.direction !== "request" ||
             event.outcome !== "matched")
             continue;
-        const declared = routes.some((route) => typeof route === "object" &&
-            route !== null &&
-            "method" in route &&
-            route.method === event.method &&
-            "path" in route &&
-            route.path === event.path);
-        require(declared, "protocol_events", "matched HTTP event has no declared replay route");
+        require(plans.some((plan) => matchesHttpPlan(plan, event)), "protocol_events", "matched HTTP event has no declared replay route");
+    }
+};
+const validateReplayEvents = (capture, require) => {
+    const replayPlan = capture.manifest.replay_plan;
+    const routes = Array.isArray(replayPlan["http"]) ? replayPlan["http"] : [];
+    const machine = machinePlan(replayPlan);
+    require(replayPlan["machine"] === undefined ||
+        replayPlan["machine"] === null ||
+        machine !==
+            undefined, "manifest.replay_plan.machine", "replay machine does not satisfy its declared schema");
+    validateMatchedHttpEvents(capture, [...routes, ...(machine?.transitions ?? [])], require);
+    const plans = new Map((machine?.transitions ?? []).map((transition) => [
+        transition.id,
+        transition,
+    ]));
+    const transitionUses = new Map();
+    const stateVisits = new Map();
+    if (machine !== undefined)
+        stateVisits.set(machine.initial_state, 1);
+    require(machine === undefined ||
+        capture.replay_transitions.length <=
+            machine.max_transitions, "replay_transitions", "replay transition journal exceeds the declared machine limit");
+    for (const [index, transition] of capture.replay_transitions.entries()) {
+        const plan = plans.get(transition.transition_id);
+        require(plan !==
+            undefined, "replay_transitions", "replay transition has no declared machine transition");
+        if (plan === undefined)
+            continue;
+        require(transition.state_before === plan.from &&
+            transition.state_after ===
+                plan.to, "replay_transitions", "replay transition states do not match the declared transition");
+        require(JSON.stringify(transition.sensitive_aliases) ===
+            JSON.stringify(plan.captures
+                .filter(({ sensitive }) => sensitive)
+                .map(({ variable }) => variable)
+                .sort()), "replay_transitions", "replay transition sensitive aliases do not match the declared captures");
+        const uses = (transitionUses.get(plan.id) ?? 0) + 1;
+        transitionUses.set(plan.id, uses);
+        require(uses <=
+            plan.max_uses, "replay_transitions", "replay transition journal exceeds the transition use limit");
+        const visits = (stateVisits.get(transition.state_after) ?? 0) + 1;
+        stateVisits.set(transition.state_after, visits);
+        const state = machine?.states.find(({ name }) => name === transition.state_after);
+        require(state === undefined ||
+            visits <=
+                state.max_visits, "replay_transitions", "replay transition journal exceeds the state visit limit");
+        if (index === 0)
+            require(transition.state_before ===
+                machine?.initial_state, "replay_transitions", "first replay transition does not start at the declared initial state");
+        if (index > 0)
+            require(capture.replay_transitions[index - 1].state_after ===
+                transition.state_before, "replay_transitions", "replay transition states are not contiguous");
     }
 };
 /** Recompute v4 commitments and cross-field invariants without side effects. */
@@ -117,6 +205,7 @@ export const validateProcessCapture = (capture) => {
     };
     validateCommitments(capture, require);
     validateOrdering(capture, require);
+    validateEventJournal(capture, require);
     validateLifecycle(capture, require);
     validateShimEvents(capture, require);
     validateReplayEvents(capture, require);

package/dist/domain/processComparison.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { validateProcessCapture } from "./processCapture.js";
 import { jsonValueSchema } from "./jsonValue.js";
+import { compareProcessTraces, processTraceOutcomesDiffer, processTraceComparisonResultSchema, } from "./processTraceComparison.js";
+import { dimensionsForTraceSources, traceCoversObservedDimension, } from "./processTraceDimensionProjection.js";
 /** Comparison classification that never equates incomplete evidence. */
 export const comparisonStatusSchema = z.enum([
     "unchanged",
@@ -61,6 +63,7 @@ export const processCaptureComparisonSchema = z
             right: jsonValueSchema.nullable(),
         }),
     ]),
+    trace: processTraceComparisonResultSchema.optional(),
     limitations: z.array(z.string()),
 })
     .superRefine((comparison, context) => {
@@ -106,7 +109,7 @@ export const processDimensionObservations = (capture, dimension) => {
         case "filesystem":
             return filesystemObservations(capture);
         case "protocol":
-            return capture.protocol_events;
+            return [...capture.protocol_events, ...capture.replay_transitions];
         case "process":
             return capture.process_samples;
         case "shim":
@@ -193,6 +196,40 @@ const truncatedComparison = () => ({
     },
     limitations: ["At least one capture is truncated."],
 });
+const applyTraceVerdict = (dimensions, specification, trace, captures) => {
+    const traceShowsDifference = processTraceOutcomesDiffer(trace);
+    const traceStatus = trace.verdict === "unknown"
+        ? "unknown"
+        : trace.verdict === "equivalent" || !traceShowsDifference
+            ? "unchanged"
+            : "changed";
+    const sources = new Set(specification.events.map(({ source }) => source));
+    const covered = dimensionsForTraceSources(sources);
+    const statusFor = (dimension) => {
+        const exact = dimensions[dimension];
+        if (!covered.has(dimension))
+            return exact;
+        if (trace.verdict === "nonconforming")
+            return exact;
+        if (trace.verdict === "different")
+            return traceShowsDifference ? "changed" : exact;
+        if (trace.verdict === "unknown" &&
+            ["changed", "added", "removed"].includes(exact))
+            return exact;
+        return traceCoversObservedDimension(dimension, sources, captures[0], captures[1])
+            ? traceStatus
+            : exact;
+    };
+    return {
+        terminal: statusFor("terminal"),
+        interaction: statusFor("interaction"),
+        exit: statusFor("exit"),
+        filesystem: statusFor("filesystem"),
+        protocol: statusFor("protocol"),
+        process: statusFor("process"),
+        shim: statusFor("shim"),
+    };
+};
 const compareDimensions = (left, right, sameNormalization) => {
     const classify = (scope, leftValues, rightValues) => !sameNormalization || hasUnknown(left, scope) || hasUnknown(right, scope)
         ? "unknown"
@@ -207,12 +244,11 @@ const compareDimensions = (left, right, sameNormalization) => {
                 ? "unchanged"
                 : "changed",
         filesystem: classify("filesystem", filesystemObservations(left), filesystemObservations(right)),
-        protocol: classify("protocol", left.protocol_events, right.protocol_events),
+        protocol: classify("protocol", [...left.protocol_events, ...left.replay_transitions], [...right.protocol_events, ...right.replay_transitions]),
         process: classify("process", left.process_samples, right.process_samples),
         shim: classify("shim", left.shim_events, right.shim_events),
     };
 };
-/** Compare bounded captures without equating missing or incompatible evidence. */
 /**
  * Compare two Process Capture v4 observations without treating absence as proof.
  *
@@ -221,33 +257,50 @@ const compareDimensions = (left, right, sameNormalization) => {
  */
 export const compareProcessCaptures = (left, right, options = {}) => {
     assertComparable(left, right, options);
-    if (left.truncated || right.truncated)
-        return truncatedComparison();
+    if (left.truncated || right.truncated) {
+        const truncated = truncatedComparison();
+        return options.traceSpecification === undefined
+            ? truncated
+            : {
+                ...truncated,
+                trace: compareProcessTraces(left, right, options.traceSpecification),
+            };
+    }
     const sameNormalization = JSON.stringify(left.normalization) === JSON.stringify(right.normalization);
-    const dimensions = compareDimensions(left, right, sameNormalization);
-    const observedFirstDivergence = chooseFirstDivergence([
-        firstCollectionDivergence("terminal", terminalObservations(left), terminalObservations(right)),
-        firstCollectionDivergence("interaction", left.interaction_events, right.interaction_events),
-        firstCollectionDivergence("exit", [{ ...left.exit, settlement: left.settlement }], [{ ...right.exit, settlement: right.settlement }]),
-        firstCollectionDivergence("filesystem", filesystemObservations(left), filesystemObservations(right)),
-        firstCollectionDivergence("protocol", left.protocol_events, right.protocol_events),
-        firstCollectionDivergence("process", left.process_samples, right.process_samples),
-        firstCollectionDivergence("shim", left.shim_events, right.shim_events),
-    ]);
-    const firstDivergence = observedFirstDivergence.status === "found"
-        ? observedFirstDivergence
-        : !sameNormalization ||
-            left.residual_unknowns.length > 0 ||
-            right.residual_unknowns.length > 0
-            ? {
-                status: "unknown",
-                reason: "Residual unknowns prevent proving that no divergence occurred.",
-            }
-            : observedFirstDivergence;
+    const exactDimensions = compareDimensions(left, right, sameNormalization);
+    const trace = options.traceSpecification === undefined
+        ? undefined
+        : compareProcessTraces(left, right, options.traceSpecification);
+    const dimensions = trace === undefined || options.traceSpecification === undefined
+        ? exactDimensions
+        : applyTraceVerdict(exactDimensions, options.traceSpecification, trace, [
+            left,
+            right,
+        ]);
+    const divergenceCandidates = PROCESS_COMPARISON_DIMENSIONS.map((dimension) => firstCollectionDivergence(dimension, processDimensionObservations(left, dimension), processDimensionObservations(right, dimension)));
+    const observedFirstDivergence = chooseFirstDivergence(divergenceCandidates.map((candidate) => candidate !== null &&
+        trace?.verdict === "equivalent" &&
+        dimensions[candidate.dimension] === "unchanged"
+        ? null
+        : candidate));
+    const firstDivergence = trace?.verdict === "equivalent" &&
+        deriveProcessComparisonStatus(PROCESS_COMPARISON_DIMENSIONS.map((dimension) => dimensions[dimension])) === "unchanged"
+        ? { status: "none" }
+        : observedFirstDivergence.status === "found"
+            ? observedFirstDivergence
+            : !sameNormalization ||
+                left.residual_unknowns.length > 0 ||
+                right.residual_unknowns.length > 0
+                ? {
+                    status: "unknown",
+                    reason: "Residual unknowns prevent proving that no divergence occurred.",
+                }
+                : observedFirstDivergence;
     return {
         status: deriveProcessComparisonStatus(PROCESS_COMPARISON_DIMENSIONS.map((dimension) => dimensions[dimension])),
         ...dimensions,
         first_divergence: firstDivergence,
+        ...(trace === undefined ? {} : { trace }),
         limitations: [
             ...left.limitations,
             ...right.limitations,

package/dist/domain/processObservation.js

@@ -0,0 +1,153 @@
+import { z } from "zod";
+import { jsonValueSchema } from "./jsonValue.js";
+/** Process-capture observation families shared by live drivers and trace assertions. */
+export const processObservationSourceSchema = z.enum([
+    "terminal_raw",
+    "terminal_rendered",
+    "interaction",
+    "lifecycle",
+    "process",
+    "filesystem",
+    "http",
+    "websocket",
+    "shim",
+    "replay_transition",
+]);
+/** Stable raw-record location within one Process Capture observation journal. */
+export const processObservationLocationSchema = z.strictObject({
+    collection: z.enum([
+        "frames",
+        "rendered_frames",
+        "interaction_events",
+        "lifecycle",
+        "process_samples",
+        "filesystem_checkpoints",
+        "shim_events",
+        "protocol_events",
+        "replay_transitions",
+    ]),
+    index: z.number().int().nonnegative(),
+    capture_order: z.number().int().nonnegative(),
+});
+/** Remove only explicitly declared top-level volatile fields before matching. */
+export const comparableProcessObservationPayload = (value, ignoredFields = []) => {
+    if (ignoredFields.length === 0 ||
+        typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).filter(([name]) => !ignoredFields.includes(name)));
+};
+/** Construct a validated observation from one live producer record. */
+export const createProcessObservation = (input) => ({
+    event_id: `obs.${input.location.collection}.${String(input.location.index)}`,
+    source: input.source,
+    source_sequence: input.source_sequence,
+    capture_order: input.location.capture_order,
+    captured_at_ms: input.captured_at_ms,
+    subject_id: input.subject_id,
+    location: input.location,
+    payload: jsonValueSchema.parse(input.payload),
+});
+const atMilliseconds = (value) => {
+    if (typeof value !== "object" || value === null)
+        return null;
+    for (const name of ["at_ms", "dispatched_at_ms"])
+        if (name in value) {
+            const candidate = value[name];
+            if (typeof candidate === "number" && Number.isSafeInteger(candidate))
+                return candidate;
+        }
+    return null;
+};
+const subjectFor = (source, value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    if (source === "process" && typeof value["pid"] === "number")
+        return `process:${String(value["pid"])}`;
+    if (source === "filesystem" && typeof value["name"] === "string")
+        return `checkpoint:${value["name"]}`;
+    return null;
+};
+const projectedRecord = (capture, location) => {
+    const projected = (() => {
+        switch (location.collection) {
+            case "frames":
+                return {
+                    source: "terminal_raw",
+                    value: capture.frames[location.index],
+                };
+            case "rendered_frames":
+                return {
+                    source: "terminal_rendered",
+                    value: capture.rendered_frames[location.index],
+                };
+            case "interaction_events":
+                return {
+                    source: "interaction",
+                    value: capture.interaction_events[location.index],
+                };
+            case "lifecycle":
+                return location.index === 0
+                    ? {
+                        source: "lifecycle",
+                        value: { event: "exit", ...capture.exit },
+                    }
+                    : location.index === 1
+                        ? {
+                            source: "lifecycle",
+                            value: { event: "settlement", ...capture.settlement },
+                        }
+                        : null;
+            case "process_samples":
+                return {
+                    source: "process",
+                    value: capture.process_samples[location.index],
+                };
+            case "filesystem_checkpoints":
+                return {
+                    source: "filesystem",
+                    value: capture.filesystem_checkpoints[location.index],
+                };
+            case "shim_events":
+                return {
+                    source: "shim",
+                    value: capture.shim_events[location.index],
+                };
+            case "protocol_events": {
+                const event = capture.protocol_events[location.index];
+                return event === undefined
+                    ? null
+                    : { source: event.protocol, value: event };
+            }
+            case "replay_transitions":
+                return {
+                    source: "replay_transition",
+                    value: capture.replay_transitions[location.index],
+                };
+        }
+    })();
+    if (projected === null || projected.value === undefined)
+        return null;
+    const payload = jsonValueSchema.parse(projected.value);
+    return {
+        source: projected.source,
+        captured_at_ms: atMilliseconds(payload),
+        subject_id: subjectFor(projected.source, payload),
+        payload,
+    };
+};
+/** Project one validated capture-journal reference into the shared observation shape. */
+export const projectProcessObservation = (capture, location) => {
+    const projected = projectedRecord(capture, location);
+    if (projected === null)
+        return null;
+    return createProcessObservation({
+        source: projected.source,
+        source_sequence: location.index,
+        captured_at_ms: projected.captured_at_ms,
+        subject_id: projected.subject_id,
+        location,
+        payload: projected.payload,
+    });
+};

package/dist/domain/processReactiveCheckpointDataflow.js

@@ -0,0 +1,32 @@
+/** Checkpoints guaranteed on every known path entering each reactive state. */
+export const definitelyAvailableCheckpoints = (scenario) => {
+    const available = new Map([
+        [scenario.initial_state, new Set()],
+    ]);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const state of scenario.states) {
+            const before = available.get(state.id);
+            if (before === undefined)
+                continue;
+            for (const transition of state.on) {
+                if (transition.target.kind !== "goto")
+                    continue;
+                const after = new Set(before);
+                for (const name of transition.actions.flatMap((action) => action.type === "checkpoint" ? [action.name] : []))
+                    after.add(name);
+                const prior = available.get(transition.target.state);
+                const next = prior === undefined
+                    ? after
+                    : new Set([...prior].filter((name) => after.has(name)));
+                if (prior !== undefined && setsEqual(prior, next))
+                    continue;
+                available.set(transition.target.state, next);
+                changed = true;
+            }
+        }
+    }
+    return available;
+};
+const setsEqual = (left, right) => left.size === right.size && [...left].every((value) => right.has(value));