rea-agents 2.1.0 → 2.3.0

package/dist/application/ProcessCaptureJournal.js

@@ -0,0 +1,95 @@
+import { normalizeProcessElapsedTime, normalizeProcessText, } from "./ProcessNormalization.js";
+/** Create one monotonic event journal for a process capture. */
+export const createProcessCaptureJournal = () => {
+    const entries = [];
+    const listeners = new Set();
+    const notifications = [];
+    let delivering = false;
+    const deliverNotifications = () => {
+        if (delivering)
+            return;
+        delivering = true;
+        const failures = [];
+        try {
+            for (;;) {
+                const notification = notifications.shift();
+                if (notification === undefined)
+                    break;
+                for (const listener of Array.from(listeners))
+                    try {
+                        listener(notification);
+                    }
+                    catch (cause) {
+                        failures.push(cause);
+                    }
+            }
+        }
+        finally {
+            delivering = false;
+        }
+        if (failures.length > 0)
+            throw new AggregateError(failures, "process capture journal subscriber failed");
+    };
+    const record = (collection, index) => {
+        const entry = { capture_order: entries.length, collection, index };
+        entries.push(entry);
+        notifications.push(entry);
+        deliverNotifications();
+        return entry;
+    };
+    return {
+        entries,
+        record,
+        recordEvent: (collection, index) => void record(collection, index),
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+};
+/** Schedule scenario interactions and record each observed dispatch atomically. */
+export const scheduleScenarioInteractions = (options) => {
+    const { scenario, getTerminal, timers, interactions, renderer, started } = options;
+    for (const [eventIndex, event] of scenario.events.entries()) {
+        const timer = setTimeout(() => {
+            options.dispatchedEventIndexes.add(eventIndex);
+            const terminal = getTerminal();
+            const dispatchedAt = Math.max(0, Date.now() - started);
+            let outcome = "dispatched";
+            if (terminal === undefined)
+                outcome = "target_exited";
+            else {
+                try {
+                    if (event.type === "input")
+                        terminal.write(event.data);
+                    else if (event.type === "resize") {
+                        terminal.resize(event.columns, event.rows);
+                        renderer.resize(event.columns, event.rows, normalizeProcessElapsedTime(dispatchedAt, scenario.normalization.time_bucket_ms));
+                    }
+                    else
+                        terminal.kill(event.signal);
+                }
+                catch {
+                    outcome = "failed";
+                }
+            }
+            const sequence = interactions.length;
+            interactions.push({
+                sequence,
+                scheduled_at_ms: event.at_ms,
+                dispatched_at_ms: dispatchedAt,
+                type: event.type,
+                data: event.type === "input"
+                    ? event.sensitive
+                        ? `<redacted-input:${String(Buffer.byteLength(event.data))}-bytes>`
+                        : normalizeProcessText(event.data, scenario, "<no-temporary-root>", -1)
+                    : event.type === "resize"
+                        ? `${String(event.columns)}x${String(event.rows)}`
+                        : event.signal,
+                outcome,
+            });
+            options.recordEvent("interaction_events", sequence);
+        }, event.at_ms);
+        timers.add(timer);
+    }
+};

package/dist/application/ProcessCaptureLifecycle.js

@@ -10,7 +10,7 @@ import { cleanupOwnedProcessGroup, observeOwnedProcessGroup, } from "../process/
 import { classifyFilesystemEffects, ProcessCheckpoints, } from "./ProcessCheckpoints.js";
 import { ProcessCaptureError } from "./ProcessCaptureError.js";
 import { assertNotCancelled, assertRealPathAuthority, } from "./ProcessCaptureAuthority.js";
-import { normalizeProcessSamples, normalizeProcessText, redactProtocolEvents, } from "./ProcessNormalization.js";
+import { normalizeProcessElapsedTime, normalizeProcessSamples, normalizeProcessText, redactProtocolEvents, } from "./ProcessNormalization.js";
 import { PROCESS_PROVIDER } from "./ProcessEvidence.js";
 import { TerminalRenderer } from "./TerminalRenderer.js";
 export const buildCaptureResult = (options) => ({
@@ -18,9 +18,7 @@ export const buildCaptureResult = (options) => ({
     manifest: options.manifest,
     normalization: options.scenario.normalization,
     frames: options.frames,
-    rendered_frames: [...options.renderedFrames]
-        .sort((left, right) => left.at_ms - right.at_ms || left.sequence - right.sequence)
-        .map((frame, sequence) => ({ ...frame, sequence })),
+    rendered_frames: options.renderedFrames,
     interaction_events: options.interactions,
     exit: {
         code: options.exit.reason === "exited" && options.exit.exitCode >= 0
@@ -34,6 +32,8 @@ export const buildCaptureResult = (options) => ({
     filesystem_checkpoints: options.checkpoints,
     shim_events: options.shimEvents,
     protocol_events: redactProtocolEvents(options.replay.events, options.scenario),
+    replay_transitions: options.replay.transitions,
+    event_journal: options.eventJournal,
     files_before: options.before.files,
     files_after: options.after.files,
     filesystem_effects: classifyFilesystemEffects(options.before.files, options.after.files),
@@ -91,9 +91,11 @@ export const createRunManifest = async (scenario, startedAt, completedAt) => {
         replay_plan_sha256: digestProcessCommitment(scenario.replay),
     };
 };
-export const observeSettlement = async (runId, processGroupIds, settleMs) => {
-    if (process.platform === "win32")
+export const observeSettlement = async (runId, processGroupIds, settleMs, recordEvent = () => undefined) => {
+    if (process.platform === "win32") {
+        recordEvent("lifecycle", 1);
         return { state: "unverifiable", elapsed_ms: 0 };
+    }
     const started = Date.now();
     let consecutiveEmpty = 0;
     let deadlineReached = false;
@@ -103,12 +105,16 @@ export const observeSettlement = async (runId, processGroupIds, settleMs) => {
             leaderPid: processGroupId,
             processGroupId,
         })));
-        if (observations.some(({ state }) => state === "unverifiable"))
+        if (observations.some(({ state }) => state === "unverifiable")) {
+            recordEvent("lifecycle", 1);
             return { state: "unverifiable", elapsed_ms: Date.now() - started };
+        }
         if (observations.every(({ state }) => state === "empty")) {
             consecutiveEmpty += 1;
-            if (consecutiveEmpty >= 2)
+            if (consecutiveEmpty >= 2) {
+                recordEvent("lifecycle", 1);
                 return { state: "quiesced", elapsed_ms: Date.now() - started };
+            }
         }
         else
             consecutiveEmpty = 0;
@@ -117,19 +123,22 @@ export const observeSettlement = async (runId, processGroupIds, settleMs) => {
             break;
         await new Promise((resolve) => setTimeout(resolve, 50));
     }
+    recordEvent("lifecycle", 1);
     return { state: "alive_at_deadline", elapsed_ms: Date.now() - started };
 };
-export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutput, signal, timers, interactions, dispatchedEventIndexes, }) => new Promise((resolveExit) => {
+export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutput, signal, timers, interactions, dispatchedEventIndexes, recordEvent, }) => new Promise((resolveExit) => {
     // The kill caused by a deadline is observed later as an ordinary PTY exit.
     // Keep the initiating lifecycle reason so comparisons distinguish a target
     // exit from harness-owned timeout, idle-timeout, and cancellation cleanup.
     let reason = "exited";
     terminal.onExit((exit) => {
+        recordEvent("lifecycle", 0);
         for (const [eventIndex, event] of scenario.events.entries()) {
             if (dispatchedEventIndexes.has(eventIndex))
                 continue;
+            const sequence = interactions.length;
             interactions.push({
-                sequence: interactions.length,
+                sequence,
                 scheduled_at_ms: event.at_ms,
                 dispatched_at_ms: Math.max(0, Date.now() - started),
                 type: event.type,
@@ -140,6 +149,7 @@ export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutpu
                         : event.signal,
                 outcome: "target_exited",
             });
+            recordEvent("interaction_events", sequence);
         }
         for (const timer of timers) {
             clearTimeout(timer);
@@ -223,14 +233,15 @@ export const captureTerminalFrames = (options) => {
             return;
         }
         outputBytes += bytes;
-        const atMs = Math.floor((Date.now() - options.started) /
-            options.scenario.normalization.time_bucket_ms) * options.scenario.normalization.time_bucket_ms;
+        const atMs = normalizeProcessElapsedTime(Date.now() - options.started, options.scenario.normalization.time_bucket_ms);
         const normalized = normalizeProcessText(data, options.scenario, options.temporaryRoot, options.terminal.pid);
+        const sequence = options.frames.length;
         options.frames.push({
-            sequence: options.frames.length,
+            sequence,
             at_ms: atMs,
             data: normalized,
         });
+        options.recordEvent("frames", sequence);
         options.renderer.write(data, atMs);
         options.checkpoints.observeTerminal(normalized);
     });

package/dist/application/ProcessCheckpoints.js

@@ -22,17 +22,19 @@ export const classifyFilesystemEffects = (before, after) => {
 export class ProcessCheckpoints {
     scenario;
     started;
-    signal;
     #captures = [];
     #captured = new Set();
     #terminalCounts = new Map();
     #terminalTails = new Map();
     #timers = new Set();
+    #signal;
+    #recordEvent;
     #pending = Promise.resolve();
-    constructor(scenario, started, before, signal) {
+    constructor(scenario, started, before, options = { signal: undefined }) {
         this.scenario = scenario;
         this.started = started;
-        this.signal = signal;
+        this.#signal = options.signal;
+        this.#recordEvent = options.recordEvent ?? (() => undefined);
         this.#captures.push({
             name: "before",
             at_ms: 0,
@@ -40,6 +42,7 @@ export class ProcessCheckpoints {
             effects: [],
             truncated: before.truncated,
         });
+        this.#recordEvent("filesystem_checkpoints", 0);
         this.#captured.add("before");
         for (const checkpoint of scenario.checkpoints) {
             if (checkpoint.trigger.type !== "time")
@@ -74,6 +77,9 @@ export class ProcessCheckpoints {
     }
     /** Queue one idempotent named snapshot. */
     capture(name) {
+        this.#scheduleCapture(name, this.#signal);
+    }
+    #scheduleCapture(name, signal) {
         if (this.#captured.has(name))
             return;
         this.#captured.add(name);
@@ -81,8 +87,9 @@ export class ProcessCheckpoints {
         // together. Each effect set is intentionally relative to the immediately
         // preceding checkpoint, which preserves transient create/delete behavior.
         this.#pending = this.#pending.then(async () => {
-            const snapshot = await snapshotRoots(this.scenario, this.signal);
+            const snapshot = await snapshotRoots(this.scenario, signal);
             const previous = this.#captures.at(-1)?.files ?? [];
+            const index = this.#captures.length;
             this.#captures.push({
                 name,
                 at_ms: Math.max(0, Date.now() - this.started),
@@ -90,14 +97,32 @@ export class ProcessCheckpoints {
                 effects: classifyFilesystemEffects(previous, snapshot.files),
                 truncated: snapshot.truncated,
             });
+            this.#recordEvent("filesystem_checkpoints", index);
         });
     }
+    /** Queue one named snapshot and return its exact captured record. */
+    async captureAndRead(name, signal) {
+        const captureSignal = signal === undefined
+            ? this.#signal
+            : this.#signal === undefined
+                ? signal
+                : AbortSignal.any([this.#signal, signal]);
+        this.#scheduleCapture(name, captureSignal);
+        const scheduled = this.#pending;
+        await scheduled;
+        const index = this.#captures.findIndex(({ name: capturedName }) => capturedName === name);
+        const checkpoint = this.#captures[index];
+        if (index < 0 || checkpoint === undefined)
+            throw new Error(`filesystem checkpoint was not captured: ${name}`);
+        return { index, checkpoint: structuredClone(checkpoint) };
+    }
     /** Finish pending snapshots and return them in observation order. */
     async finish(after) {
         for (const timer of this.#timers)
             clearTimeout(timer);
         await this.#pending;
         const previous = this.#captures.at(-1)?.files ?? [];
+        const index = this.#captures.length;
         this.#captures.push({
             name: "after_settlement",
             at_ms: Math.max(0, Date.now() - this.started),
@@ -105,6 +130,7 @@ export class ProcessCheckpoints {
             effects: classifyFilesystemEffects(previous, after.files),
             truncated: after.truncated,
         });
+        this.#recordEvent("filesystem_checkpoints", index);
         return structuredClone(this.#captures);
     }
     /** Cancel scheduled captures and await any snapshot already in progress. */

package/dist/application/ProcessCli.js

@@ -1,8 +1,10 @@
 import { readFile } from "node:fs/promises";
 import { parseConfig } from "../config.js";
-import { AnalysisError, AnalysisProtocolError, PermissionRequiredError, projectAnalysisError, } from "../domain/errors.js";
+import { AnalysisError, AnalysisInputError, AnalysisProtocolError, PermissionRequiredError, projectAnalysisError, } from "../domain/errors.js";
 import { createEvidence, parseEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { processTraceSpecificationSchema } from "../domain/processTraceComparison.js";
 import { compareProcessCaptures, LEGACY_PROCESS_CAPTURE_MESSAGE, parseProcessScenario, parseProcessCapture, } from "../domain/processCapture.js";
 import { captureProcessScenario } from "./ProcessHarness.js";
 import { processCapturePermissionRequest } from "./ProcessCapturePermission.js";
@@ -43,24 +45,37 @@ export const captureProcessScenarioFile = async (path) => {
     }
 };
 /** Compare two capture Evidence files and emit derived comparison Evidence. */
-export const compareProcessEvidenceFiles = async (leftPath, rightPath) => {
+export const compareProcessEvidenceFiles = async (leftPath, rightPath, traceSpecPath) => {
     try {
         const left = parseCaptureEvidence(await readJson(leftPath));
         const right = parseCaptureEvidence(await readJson(rightPath));
-        const comparison = compareProcessCaptures(left.capture, right.capture);
+        const traceSpecification = traceSpecPath === undefined
+            ? undefined
+            : parseTraceSpecification(await readJson(traceSpecPath));
+        const comparison = traceSpecification === undefined
+            ? compareProcessCaptures(left.capture, right.capture)
+            : compareProcessCaptures(left.capture, right.capture, {
+                traceSpecification,
+            });
         return createEvidence(undefined, PROCESS_PROVIDER, {
-            predicateType: "rea.process-comparison/v3",
+            predicateType: traceSpecification === undefined
+                ? "rea.process-comparison/v3"
+                : "rea.process-comparison/v4",
             operation: "compare_process_captures",
             parameters: {
                 left_evidence_id: left.id,
                 right_evidence_id: right.id,
                 left_normalization: left.capture.normalization,
                 right_normalization: right.capture.normalization,
+                ...(traceSpecification === undefined
+                    ? {}
+                    : { trace_spec: jsonValueSchema.parse(traceSpecification) }),
             },
             result: jsonValueSchema.parse(comparison),
             confidence: "derived",
             authority: "analyst-inference",
             limitations: comparison.limitations,
+            locations: [...left.locations, ...right.locations],
             evidenceLinks: [left.id, right.id],
         });
     }
@@ -88,12 +103,19 @@ const parseCaptureEvidence = (input) => {
         return {
             id: evidence.evidence_id,
             capture: parseProcessCapture(evidence.normalized_result),
+            locations: evidence.locations,
         };
     }
     catch {
         throw invalidCaptureEvidence();
     }
 };
+const parseTraceSpecification = (input) => {
+    const parsed = processTraceSpecificationSchema.safeParse(input);
+    if (parsed.success)
+        return parsed.data;
+    throw new AnalysisInputError("compare-process-captures", { cause: parsed.error }, projectInputIssues(parsed.error.issues, input));
+};
 const invalidCaptureEvidence = () => new ProcessCliFailure("invalid_input", "Capture evidence is malformed. Create new capture evidence, then try again.");
 const readJson = async (path) => {
     let bytes;

package/dist/application/ProcessHarness.js

@@ -12,6 +12,7 @@ import { normalizeProcessText } from "./ProcessNormalization.js";
 import { selectCapturedProcessGroupIds } from "../process/ProcessOwnership.js";
 import { awaitTerminalExit, buildCaptureResult, captureTerminalFrames, createRunManifest, observeSettlement, prepareProcessCapture, releaseProcessResources, resolveProcessResult, } from "./ProcessCaptureLifecycle.js";
 import { assertNotCancelled } from "./ProcessCaptureAuthority.js";
+import { createProcessCaptureJournal, scheduleScenarioInteractions, } from "./ProcessCaptureJournal.js";
 export { probeProcessCaptureCapability } from "./ProcessCaptureCapability.js";
 const makeEnvironment = (options) => {
     const { scenario, home, replay, shimReplay, runId } = options;
@@ -38,49 +39,6 @@ const makeEnvironment = (options) => {
         .join(":");
     return environment;
 };
-const scheduleScenarioEvents = (options) => {
-    const { scenario, getTerminal, timers, interactions, renderer, started } = options;
-    for (const [eventIndex, event] of scenario.events.entries()) {
-        const timer = setTimeout(() => {
-            options.dispatchedEventIndexes.add(eventIndex);
-            const terminal = getTerminal();
-            const dispatchedAt = Math.max(0, Date.now() - started);
-            let outcome = "dispatched";
-            if (terminal === undefined)
-                outcome = "target_exited";
-            else {
-                try {
-                    if (event.type === "input")
-                        terminal.write(event.data);
-                    else if (event.type === "resize") {
-                        terminal.resize(event.columns, event.rows);
-                        renderer.resize(event.columns, event.rows, dispatchedAt);
-                    }
-                    else
-                        terminal.kill(event.signal);
-                }
-                catch {
-                    outcome = "failed";
-                }
-            }
-            interactions.push({
-                sequence: interactions.length,
-                scheduled_at_ms: event.at_ms,
-                dispatched_at_ms: dispatchedAt,
-                type: event.type,
-                data: event.type === "input"
-                    ? event.sensitive
-                        ? `<redacted-input:${String(Buffer.byteLength(event.data))}-bytes>`
-                        : normalizeProcessText(event.data, scenario, "<no-temporary-root>", -1)
-                    : event.type === "resize"
-                        ? `${String(event.columns)}x${String(event.rows)}`
-                        : event.signal,
-                outcome,
-            });
-        }, event.at_ms);
-        timers.add(timer);
-    }
-};
 const cleanupFailedStartup = async (options) => {
     options.terminal?.kill("SIGKILL");
     const cleanupFailure = await releaseProcessResources({
@@ -94,13 +52,14 @@ const cleanupFailedStartup = async (options) => {
         });
     throw options.cause;
 };
-const createTerminalRenderer = (scenario, temporaryRoot, terminalPid) => new TerminalRenderer({
+const createTerminalRenderer = (scenario, temporaryRoot, terminalPid, recordEvent) => new TerminalRenderer({
     columns: scenario.terminal.columns,
     rows: scenario.terminal.rows,
     scrollback: scenario.terminal.scrollback,
     maxFrames: scenario.limits.frames,
     maxBytes: scenario.limits.output_bytes,
     normalize: (value) => normalizeProcessText(value, scenario, temporaryRoot, terminalPid()),
+    recordEvent,
 });
 const startCaptureRuntime = async (options) => {
     const { scenario } = options;
@@ -111,13 +70,16 @@ const startCaptureRuntime = async (options) => {
     let terminal;
     try {
         const { spawn } = await import("@lydell/node-pty");
-        replay = await startLoopbackReplay(scenario);
+        replay = await startLoopbackReplay(scenario, options.recordEvent);
         const startedAt = new Date();
         const started = Date.now();
         let lastOutput = started;
-        renderer = createTerminalRenderer(scenario, options.temporaryRoot, () => terminal?.pid ?? -1);
-        checkpoints = new ProcessCheckpoints(scenario, started, options.before, options.signal);
-        shimReplay = await startCommandShimReplay(scenario, options.temporaryRoot, started);
+        renderer = createTerminalRenderer(scenario, options.temporaryRoot, () => terminal?.pid ?? -1, options.recordEvent);
+        checkpoints = new ProcessCheckpoints(scenario, started, options.before, {
+            signal: options.signal,
+            recordEvent: options.recordEvent,
+        });
+        shimReplay = await startCommandShimReplay(scenario, options.temporaryRoot, started, options.recordEvent);
         terminal = spawn(scenario.executable, [...scenario.arguments], {
             cwd: scenario.working_directory,
             env: makeEnvironment({ ...options, replay, shimReplay }),
@@ -133,7 +95,7 @@ const startCaptureRuntime = async (options) => {
             renderer,
             checkpoints,
         });
-        scheduleScenarioEvents({
+        scheduleScenarioInteractions({
             ...options,
             getTerminal: () => terminal,
             renderer,
@@ -145,6 +107,7 @@ const startCaptureRuntime = async (options) => {
             started,
             limit: scenario.limits.processes,
             samples: options.samples,
+            recordEvent: options.recordEvent,
         });
         return {
             replay,
@@ -218,13 +181,14 @@ const completeCapture = async (options) => {
     const { reason } = options.exit;
     if (reason === "cancelled")
         throw processCaptureCancelled();
-    const settlement = await observeSettlement(options.runId, selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples), scenario.settle_ms);
+    const settlement = await observeSettlement(options.runId, selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples), scenario.settle_ms, options.recordEvent);
     runtime.checkpoints.trigger("settled");
     const samplingPartial = (await runtime.stopSampler()).partial;
     assertNotCancelled(options.signal);
     const after = await snapshotRoots(scenario, options.signal);
     const renderedFrames = await runtime.renderer.frames();
     const checkpoints = await runtime.checkpoints.finish(after);
+    await runtime.replay.close();
     const manifest = await createRunManifest(scenario, runtime.startedAt, new Date());
     const truncated = options.initiallyTruncated ||
         after.truncated ||
@@ -251,6 +215,7 @@ const completeCapture = async (options) => {
         shimEvents: normalizedShimEvents(runtime, scenario, options.temporaryRoot),
         settlement: { ...settlement, cleanup_outcome: "not_required" },
         manifest,
+        eventJournal: options.eventJournal,
     });
 };
 /** Execute one authorized scenario and return bounded observations. */
@@ -258,6 +223,7 @@ const runProcessScenario = async (scenario, policy, signal) => {
     const { temporaryRoot, runId, home, before } = await prepareProcessCapture(scenario, policy, signal);
     const frames = [];
     const samples = [];
+    const { entries: eventJournal, recordEvent } = createProcessCaptureJournal();
     let runtime;
     const timers = new Set();
     let capture;
@@ -277,6 +243,7 @@ const runProcessScenario = async (scenario, policy, signal) => {
             interactions,
             timers,
             dispatchedEventIndexes,
+            recordEvent,
             ...(signal === undefined ? {} : { signal }),
         });
         stopSampler = runtime.stopSampler;
@@ -289,6 +256,7 @@ const runProcessScenario = async (scenario, policy, signal) => {
             timers,
             interactions,
             dispatchedEventIndexes,
+            recordEvent,
         });
         capture = await completeCapture({
             scenario,
@@ -301,6 +269,8 @@ const runProcessScenario = async (scenario, policy, signal) => {
             interactions,
             exit,
             initiallyTruncated: before.truncated,
+            eventJournal,
+            recordEvent,
             ...(signal === undefined ? {} : { signal }),
         });
     }

package/dist/application/ProcessNormalization.js

@@ -1,3 +1,5 @@
+/** Bucket one elapsed process-capture timestamp under scenario normalization. */
+export const normalizeProcessElapsedTime = (elapsedMs, timeBucketMs) => Math.floor(elapsedMs / timeBucketMs) * timeBucketMs;
 /** Normalize and redact one terminal/protocol payload under scenario rules. */
 export const normalizeProcessText = (value, scenario, temporaryRoot, pid) => {
     let normalized = value;
@@ -42,8 +44,7 @@ export const normalizeProcessSamples = (samples, scenario, rootPid) => {
             : normalized;
     };
     return samples.map((sample) => ({
-        at_ms: Math.floor(sample.at_ms / scenario.normalization.time_bucket_ms) *
-            scenario.normalization.time_bucket_ms,
+        at_ms: normalizeProcessElapsedTime(sample.at_ms, scenario.normalization.time_bucket_ms),
         pid: mapping.get(sample.pid) ?? 1,
         parent_pid: mapping.get(sample.parent_pid) ?? 0,
         process_group_id: sample.process_group_id === null

package/dist/application/ProcessPairedExperiment.js

@@ -0,0 +1,72 @@
+import { processCaptureCancelled, } from "./ProcessCaptureError.js";
+import { captureProcessScenario } from "./ProcessHarness.js";
+import { compareProcessCaptures } from "../domain/processComparison.js";
+import { PROCESS_COMPARISON_DIMENSIONS } from "../domain/processComparison.js";
+import { analyzeProcessRepeatability, bindProcessScenario, } from "../domain/processPairedExperiment.js";
+import { err, ok } from "../domain/result.js";
+const productionCapturePort = {
+    capture: captureProcessScenario,
+};
+const captureRepeats = async (input) => {
+    const captures = [];
+    for (let index = 0; index < input.repeatCount; index += 1) {
+        if (input.signal?.aborted === true)
+            return err(processCaptureCancelled());
+        const capture = await input.port.capture(input.scenario, input.policy, input.signal);
+        if (!capture.ok)
+            return err(capture.error);
+        captures.push(capture.value);
+    }
+    return ok(captures);
+};
+/** Execute repeatability-first authority/candidate captures under one contract. */
+export const runPairedProcessExperiment = async (experiment, policy, options = {}) => {
+    const port = options.capturePort ?? productionCapturePort;
+    const authorityScenario = bindProcessScenario(experiment.shared_scenario, experiment.authority);
+    const candidateScenario = bindProcessScenario(experiment.shared_scenario, experiment.candidate);
+    const authorityRuns = await captureRepeats({
+        scenario: authorityScenario,
+        repeatCount: experiment.repeat_count,
+        policy,
+        port,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    if (!authorityRuns.ok)
+        return authorityRuns;
+    const candidateRuns = await captureRepeats({
+        scenario: candidateScenario,
+        repeatCount: experiment.repeat_count,
+        policy,
+        port,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    if (!candidateRuns.ok)
+        return candidateRuns;
+    const authorityRepeatability = analyzeProcessRepeatability(authorityRuns.value, experiment.required_dimensions);
+    const candidateRepeatability = analyzeProcessRepeatability(candidateRuns.value, experiment.required_dimensions);
+    const stable = authorityRepeatability.stable && candidateRepeatability.stable;
+    const allDimensionsRequired = PROCESS_COMPARISON_DIMENSIONS.every((dimension) => experiment.required_dimensions.includes(dimension));
+    const authorityLatest = authorityRuns.value.at(-1);
+    const candidateLatest = candidateRuns.value.at(-1);
+    const crossSide = stable &&
+        allDimensionsRequired &&
+        authorityLatest !== undefined &&
+        candidateLatest !== undefined
+        ? compareProcessCaptures(authorityLatest, candidateLatest, {
+            maxCaptureAgeMs: experiment.freshness_policy.max_capture_age_ms,
+            ...(options.now === undefined ? {} : { now: options.now }),
+        })
+        : null;
+    return ok({
+        authority_runs: authorityRuns.value,
+        candidate_runs: candidateRuns.value,
+        authority_repeatability: authorityRepeatability,
+        candidate_repeatability: candidateRepeatability,
+        cross_side: crossSide,
+        cross_side_blocked_reason: crossSide !== null
+            ? null
+            : !allDimensionsRequired
+                ? "Cross-side comparison is blocked until every returned dimension is required and repeatable."
+                : "Cross-side comparison is blocked because a required same-side dimension is unstable.",
+    });
+};