rea-agents 2.2.0 → 2.4.0

package/dist/domain/processCaptureReactiveValidation.js

@@ -0,0 +1,175 @@
+import canonicalize from "canonicalize";
+import { projectProcessObservation, } from "./processObservation.js";
+import { commitProcessReactiveProposal, createProcessReactiveSnapshot, reduceProcessReactiveScenario, } from "./processReactiveRuntime.js";
+import { processReactiveScenarioSchema, } from "./processReactiveScenario.js";
+const admittedCollection = (collection) => [
+    "frames",
+    "interaction_events",
+    "process_samples",
+    "filesystem_checkpoints",
+    "shim_events",
+    "protocol_events",
+].includes(collection);
+const reactiveObservations = (capture) => (capture.event_journal ?? []).flatMap((location) => {
+    if (!admittedCollection(location.collection))
+        return [];
+    const observation = projectProcessObservation(capture, location);
+    return observation === null ? [] : [observation];
+});
+const validateTransitionDeclaration = (transition, next, context) => {
+    const { index, scenario, require } = context;
+    const path = `reactive_run.transitions[${String(index)}]`;
+    const declared = scenario.states
+        .find(({ id }) => id === transition.state_before)
+        ?.on.find(({ id }) => id === transition.transition_id);
+    require(declared !==
+        undefined, path, "reactive transition is not declared by its recorded source state");
+    if (declared !== undefined) {
+        const stateAfter = declared.target.kind === "goto" ? declared.target.state : null;
+        const outcome = declared.target.kind === "finish" ? declared.target.outcome : null;
+        require(transition.state_after === stateAfter &&
+            transition.outcome ===
+                outcome, path, "reactive transition target or outcome differs from the committed graph");
+        require(canonicalize(transition.action_types) ===
+            canonicalize(declared.actions.map(({ type }) => type)), `${path}.action_types`, "reactive transition actions differ from the committed graph");
+    }
+    require(transition.sequence ===
+        index, `${path}.sequence`, "reactive transition sequence must be contiguous from zero");
+    if (next !== undefined)
+        require(transition.state_after ===
+            next.state_before, `reactive_run.transitions[${String(index + 1)}].state_before`, "reactive transition states must be contiguous");
+};
+const validateTransitionDeclarations = (run, scenario, require) => {
+    require(run.transitions[0]?.state_before === scenario.initial_state ||
+        run.transitions.length ===
+            0, "reactive_run.transitions[0].state_before", "reactive transition journal must start at the declared initial state");
+    for (const [index, transition] of run.transitions.entries())
+        validateTransitionDeclaration(transition, run.transitions[index + 1], {
+            index,
+            scenario,
+            require,
+        });
+};
+const commitRecordedEffects = (options) => commitProcessReactiveProposal(options.scenario, options.proposal, options.recordedFailure === undefined
+    ? options.proposal.effects.map((_, index) => {
+        const eventId = options.expected?.action_event_ids[index];
+        const observation = eventId === undefined
+            ? undefined
+            : options.observations.get(eventId);
+        return observation === undefined
+            ? { status: "rejected" }
+            : { status: "succeeded", observation };
+    })
+    : [
+        options.recordedFailure === "target_lost"
+            ? { status: "target_lost" }
+            : { status: "rejected" },
+    ], { committedSensitiveInputs: true });
+const replayTransitions = (scenario, run, observations, require) => {
+    const observationsById = new Map(observations.map((observation) => [observation.event_id, observation]));
+    let snapshot = createProcessReactiveSnapshot(scenario);
+    let transitionIndex = 0;
+    const advance = (input) => {
+        let decision = reduceProcessReactiveScenario(scenario, snapshot, input);
+        if (decision.kind === "proposal") {
+            const proposal = decision;
+            decision = commitRecordedEffects({
+                scenario,
+                proposal: decision,
+                expected: run.transitions[transitionIndex],
+                observations: observationsById,
+                recordedFailure: run.transitions[transitionIndex] === undefined &&
+                    decision.effects.length > 0 &&
+                    (run.outcome === "action_rejected" || run.outcome === "target_lost")
+                    ? run.outcome
+                    : undefined,
+            });
+            require(decision.kind !== "finished" ||
+                decision.outcome !== "action_rejected" ||
+                run.outcome ===
+                    "action_rejected", `reactive_run.transitions[${String(transitionIndex)}].action_event_ids`, `recorded action observations do not match proposed effects: ${canonicalize({
+                effects: proposal.effects,
+                observations: run.transitions[transitionIndex]?.action_event_ids.map((eventId) => observationsById.get(eventId)),
+            })}`);
+        }
+        if (decision.kind === "transition") {
+            const expected = run.transitions[transitionIndex];
+            require(expected !== undefined &&
+                canonicalize(decision.record) ===
+                    canonicalize(expected), `reactive_run.transitions[${String(transitionIndex)}]`, "reactive transition differs from deterministic journal replay");
+            transitionIndex += 1;
+        }
+        snapshot = decision.snapshot;
+    };
+    const advanceControl = (control, index) => {
+        require(snapshot.status !== "finished" ||
+            control.kind ===
+                "cleanup_failed", `reactive_run.controls[${String(index)}]`, "reactive control cannot follow a finished run");
+        advance(control.kind === "state_deadline"
+            ? {
+                kind: control.kind,
+                state_id: snapshot.active_state,
+                state_entry_capture_order: snapshot.state_entry_capture_order,
+            }
+            : { kind: control.kind });
+    };
+    let controlIndex = 0;
+    for (const observation of observations) {
+        while ((run.controls[controlIndex]?.after_capture_order ??
+            Number.MAX_SAFE_INTEGER) < observation.capture_order) {
+            const control = run.controls[controlIndex];
+            advanceControl(control, controlIndex);
+            controlIndex += 1;
+        }
+        advance({ kind: "observation", observation });
+    }
+    for (; controlIndex < run.controls.length; controlIndex += 1) {
+        const control = run.controls[controlIndex];
+        advanceControl(control, controlIndex);
+    }
+    require(transitionIndex ===
+        run.transitions
+            .length, "reactive_run.transitions", `reactive transition journal is not reproduced by deterministic replay (replayed ${String(transitionIndex)} of ${String(run.transitions.length)}; outcome ${snapshot.outcome})`);
+    return snapshot;
+};
+const validateControls = (run, observations, require) => {
+    const admittedOrders = new Set([
+        -1,
+        ...observations.map(({ capture_order }) => capture_order),
+    ]);
+    for (const [index, control] of run.controls.entries()) {
+        require(control.sequence ===
+            index, `reactive_run.controls[${String(index)}].sequence`, "reactive control sequence must be contiguous");
+        require(admittedOrders.has(control.after_capture_order), `reactive_run.controls[${String(index)}].after_capture_order`, "reactive control cutoff must identify the last admitted observation");
+        require(index === 0 ||
+            control.after_capture_order >=
+                run.controls[index - 1]
+                    .after_capture_order, `reactive_run.controls[${String(index)}].after_capture_order`, "reactive control cutoffs must be ordered");
+    }
+};
+/** Validate one capture's reactive journal by replaying the production reducer. */
+export const validateProcessCaptureReactiveRun = (capture, require) => {
+    const declared = capture.manifest.scenario["reactive"];
+    const run = capture.reactive_run;
+    const declaredReactive = declared !== undefined && declared !== null;
+    require(declaredReactive ===
+        (run !==
+            null), "reactive_run", "reactive result presence must match the committed scenario");
+    if (run === null)
+        return;
+    const parsed = processReactiveScenarioSchema.safeParse(declared);
+    require(parsed.success, "manifest.scenario.reactive", "committed reactive scenario does not satisfy its declared schema");
+    if (!parsed.success)
+        return;
+    require(run.status === "finished" &&
+        run.outcome !==
+            null, "reactive_run.outcome", "completed capture requires a finished reactive outcome");
+    validateTransitionDeclarations(run, parsed.data, require);
+    const observations = reactiveObservations(capture);
+    validateControls(run, observations, require);
+    const snapshot = replayTransitions(parsed.data, run, observations, require);
+    require(snapshot.outcome ===
+        run.outcome, "reactive_run.outcome", "reactive outcome differs from deterministic journal replay");
+    require(snapshot.active_state ===
+        run.active_state, "reactive_run.active_state", "reactive active state differs from deterministic journal replay");
+};

package/dist/domain/processCaptureValidation.js

@@ -1,3 +1,5 @@
+import { validateProcessCaptureReactiveRun } from "./processCaptureReactiveValidation.js";
+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 +25,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 +35,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 +123,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,8 +206,10 @@ export const validateProcessCapture = (capture) => {
     };
     validateCommitments(capture, require);
     validateOrdering(capture, require);
+    validateEventJournal(capture, require);
     validateLifecycle(capture, require);
     validateShimEvents(capture, require);
     validateReplayEvents(capture, require);
+    validateProcessCaptureReactiveRun(capture, require);
     return issues;
 };

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,162 @@
+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;
+};
+/** Derive the stable capture-local identity for one normalized observation. */
+export const processObservationSubject = (source, value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    if (source === "process" && "pid" in value && typeof value.pid === "number")
+        return `process:${String(value.pid)}`;
+    if (source === "filesystem" &&
+        "name" in value &&
+        typeof value.name === "string")
+        return `checkpoint:${value.name}`;
+    if (source === "shim" &&
+        "command" in value &&
+        typeof value.command === "string")
+        return "route_index" in value && typeof value.route_index === "number"
+            ? `shim:${value.command}:route:${String(value.route_index)}`
+            : `shim:${value.command}:unmatched`;
+    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: processObservationSubject(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,
+    });
+};