rea-agents 2.3.0 → 2.5.0

package/dist/application/JavaScriptSemanticGraphObjectProjection.js

@@ -0,0 +1,81 @@
+import { createJavaScriptSemanticGraphUnknown } from "../domain/javascriptSemanticGraph.js";
+import { addSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, constructSemanticGraphNode, } from "./JavaScriptSemanticGraphConstruction.js";
+import { unknownSemanticEvidence } from "./JavaScriptSemanticGraphEvidence.js";
+import { semanticPropertySlot } from "./JavaScriptSemanticGraphValueProjection.js";
+/** Project static object reads, writes, spreads, and destructuring. */
+export const projectSemanticObjects = (context) => {
+    for (const operation of context.ir.objectOperations) {
+        const occurrence = addObjectOccurrence(context, operation);
+        const slot = operation.objectBindingId === null || operation.propertyName === null
+            ? null
+            : semanticPropertySlot(context, operation.objectBindingId, operation.propertyName);
+        if (operation.kind === "read")
+            addSemanticGraphRelation(context.state, {
+                source: slot,
+                target: occurrence,
+                relation: "reads-property",
+                resolution: operation.resolution === "complete" ? "resolved" : "candidate",
+            });
+        else if (operation.kind === "write")
+            addSemanticGraphRelation(context.state, {
+                source: occurrence,
+                target: slot,
+                relation: "writes-property",
+                resolution: operation.resolution === "complete" ? "resolved" : "candidate",
+            });
+        else if (operation.kind === "destructure")
+            addSemanticGraphRelation(context.state, {
+                source: slot,
+                target: operation.targetBindingId === null
+                    ? undefined
+                    : context.bindingNodes.get(operation.targetBindingId),
+                relation: "destructures",
+                resolution: operation.resolution === "complete" ? "resolved" : "candidate",
+            });
+        else
+            addSemanticGraphRelation(context.state, {
+                source: operation.objectBindingId === null
+                    ? undefined
+                    : context.bindingNodes.get(operation.objectBindingId),
+                target: occurrence,
+                relation: "spreads",
+                resolution: operation.resolution === "complete" ? "resolved" : "candidate",
+            });
+        if (operation.resolution !== "complete")
+            addObjectUnknown(context, operation, slot ?? occurrence);
+    }
+};
+const addObjectOccurrence = (context, operation) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+    kind: "expression",
+    roleKey: operation.objectOperationId,
+    location: operation.location,
+    label: operation.propertyName === null
+        ? operation.kind
+        : `${operation.kind}:${operation.propertyName}`,
+    functionNodeId: operation.ownerCallableId === null
+        ? null
+        : (context.callableNodes.get(operation.ownerCallableId)?.node_id ??
+            null),
+    properties: {
+        operation_kind: operation.kind,
+        property_name: operation.propertyName,
+    },
+}, context.state));
+const addObjectUnknown = (context, operation, node) => {
+    const relation = operation.kind === "read"
+        ? "reads-property"
+        : operation.kind === "write"
+            ? "writes-property"
+            : operation.kind === "spread"
+                ? "spreads"
+                : "destructures";
+    addSemanticGraphUnknown(context.state, createJavaScriptSemanticGraphUnknown({
+        node_id: node?.node_id ?? null,
+        family: "object-flow",
+        relation_kinds: [relation],
+        reason: "ambiguous-target",
+        detail: `Static ${operation.kind} object identity is partial.`,
+        candidate_node_ids: [],
+        evidence: unknownSemanticEvidence(context.file, operation.location),
+    }));
+};

package/dist/application/JavaScriptSemanticGraphProjection.js

@@ -15,18 +15,25 @@ export const semanticNodesWithinRange = (nodes, range) => nodes.filter((node) =>
     contains(range, node.identity.source_range));
 /** Report extractor support without treating missing families as absence. */
 export const semanticFamilyStatus = (family, analysis, truncated) => {
-    if (!["call-flow", "closure", "data-flow", "object-flow"].includes(family))
+    if (![
+        "call-flow",
+        "boundary",
+        "child-process",
+        "closure",
+        "configuration",
+        "data-flow",
+        "event",
+        "object-flow",
+        "promise-ownership",
+        "request",
+        "resource-lifecycle",
+        "timer",
+    ].includes(family))
         return "unsupported";
     if (truncated)
         return "unknown";
     return analysis.truncated_scopes === 0 ? "partial" : "unknown";
 };
-/** Compare two exact semantic source ranges. */
-export const semanticRangesEqual = (left, right) => left !== null &&
-    left.start.line === right.start.line &&
-    left.start.column === right.start.column &&
-    left.end.line === right.end.line &&
-    left.end.column === right.end.column;
 const contains = (outer, inner) => pointCompare(outer.start, inner.start) <= 0 &&
     pointCompare(outer.end, inner.end) >= 0;
 const pointCompare = (left, right) => left.line - right.line || left.column - right.column;

package/dist/application/JavaScriptSemanticGraphResourceProjection.js

@@ -0,0 +1,59 @@
+import { createJavaScriptSemanticGraphUnknown } from "../domain/javascriptSemanticGraph.js";
+import { addSemanticGraphNode, addSemanticGraphRelation, addSemanticGraphUnknown, constructSemanticGraphNode, } from "./JavaScriptSemanticGraphConstruction.js";
+import { unknownSemanticEvidence } from "./JavaScriptSemanticGraphEvidence.js";
+import { semanticCallSiteAt, } from "./JavaScriptSemanticGraphFlowProjection.js";
+/** Project built-in resource acquisition and exact local release handles. */
+export const projectSemanticResources = (context) => {
+    const resourceNodes = new Map(context.ir.resourceOperations.flatMap((operation) => {
+        if (operation.kind !== "acquire")
+            return [];
+        const node = addResourceNode(context, operation);
+        return node === null ? [] : [[operation.resourceId, node]];
+    }));
+    for (const operation of context.ir.resourceOperations)
+        if (operation.kind === "acquire")
+            addSemanticGraphRelation(context.state, {
+                source: semanticCallSiteAt(context, operation.location),
+                target: resourceNodes.get(operation.resourceId),
+                relation: "acquires",
+                resolution: "resolved",
+            });
+        else
+            projectRelease(context, operation, resourceNodes);
+};
+const addResourceNode = (context, operation) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+    kind: "resource",
+    roleKey: operation.resourceId,
+    location: operation.location,
+    label: operation.method,
+    functionNodeId: operation.ownerCallableId === null
+        ? null
+        : (context.callableNodes.get(operation.ownerCallableId)?.node_id ??
+            null),
+    properties: { method: operation.method },
+}, context.state));
+const projectRelease = (context, operation, resourceNodes) => {
+    const callSite = semanticCallSiteAt(context, operation.location);
+    const resources = operation.linkedResourceIds.flatMap((identifier) => {
+        const resource = resourceNodes.get(identifier);
+        return resource === undefined ? [] : [resource];
+    });
+    for (const resource of resources)
+        addSemanticGraphRelation(context.state, {
+            source: callSite,
+            target: resource,
+            relation: "releases",
+            resolution: operation.resolution === "complete" ? "resolved" : "candidate",
+        });
+    if (operation.resolution === "complete")
+        return;
+    addSemanticGraphUnknown(context.state, createJavaScriptSemanticGraphUnknown({
+        node_id: callSite?.node_id ?? null,
+        family: "resource-lifecycle",
+        relation_kinds: ["releases"],
+        reason: "ambiguous-target",
+        detail: `Static ${operation.method} resource ownership is ambiguous.`,
+        candidate_node_ids: resources.map(({ node_id: identifier }) => identifier),
+        evidence: unknownSemanticEvidence(context.file, operation.location),
+    }));
+};

package/dist/application/JavaScriptSemanticGraphValueProjection.js

@@ -0,0 +1,77 @@
+import { addSemanticGraphNode, addSemanticGraphRelation, constructSemanticGraphNode, } from "./JavaScriptSemanticGraphConstruction.js";
+/** Project bounded literal values and object slots for exact query seeds. */
+export const projectSemanticValues = (context) => {
+    for (const binding of context.ir.bindings) {
+        const bindingNode = context.bindingNodes.get(binding.bindingId);
+        if (bindingNode === undefined)
+            continue;
+        projectValue({
+            context,
+            binding,
+            value: binding.value,
+            target: bindingNode,
+            role: "binding",
+        });
+    }
+};
+const projectValue = (input) => {
+    const { context, binding, value, target, role } = input;
+    if (target === null)
+        return;
+    if (value.status === "literal") {
+        const literal = addLiteralNode(context, binding, value.value, role);
+        addSemanticGraphRelation(context.state, {
+            source: literal,
+            target,
+            relation: "defines",
+            resolution: "resolved",
+        });
+    }
+    else if (value.status === "union")
+        for (const primitive of value.values) {
+            const literal = addLiteralNode(context, binding, primitive, role);
+            addSemanticGraphRelation(context.state, {
+                source: literal,
+                target,
+                relation: "defines",
+                resolution: "candidate",
+            });
+        }
+    else if (value.status === "object")
+        for (const property of value.properties) {
+            const slot = semanticPropertySlot(context, binding.bindingId, property.name);
+            addSemanticGraphRelation(context.state, {
+                source: target,
+                target: slot,
+                relation: "writes-property",
+                resolution: value.unknownProperties ? "candidate" : "resolved",
+            });
+            projectValue({
+                context,
+                binding,
+                value: property.value,
+                target: slot,
+                role: `property:${property.name}`,
+            });
+        }
+};
+const addLiteralNode = (context, binding, value, role) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+    kind: "literal",
+    roleKey: `literal:${binding.bindingId}:${role}:${JSON.stringify(value)}`,
+    location: binding.definitions[0]?.location ?? null,
+    label: JSON.stringify(value),
+    functionNodeId: context.bindingNodes.get(binding.bindingId)?.function_node_id ?? null,
+    properties: { value },
+}, context.state));
+/** Create one canonical property slot for a binding/property identity. */
+export const semanticPropertySlot = (context, objectBindingId, name) => addSemanticGraphNode(context.state, constructSemanticGraphNode(context.file, {
+    kind: "property-slot",
+    roleKey: `property:${objectBindingId}:${name}`,
+    location: null,
+    label: name,
+    functionNodeId: context.bindingNodes.get(objectBindingId)?.function_node_id ?? null,
+    properties: {
+        name,
+        object_binding_id: objectBindingId,
+    },
+}, context.state));

package/dist/application/ProcessCaptureEnvironment.js

@@ -0,0 +1,26 @@
+/** Build the explicitly admitted environment for a captured process. */
+export const makeProcessCaptureEnvironment = (options) => {
+    const { scenario, home, replay, shimReplay, runId } = options;
+    const environment = {
+        ...scenario.environment,
+        HOME: home,
+        TERM: "xterm-256color",
+        REA_PROCESS_RUN_ID: runId,
+    };
+    for (const name of scenario.inherit_environment) {
+        const value = process.env[name];
+        if (value !== undefined)
+            environment[name] = value;
+    }
+    environment.REA_REPLAY_HTTP_URL = replay.httpUrl;
+    environment.REA_REPLAY_WEBSOCKET_URL = replay.websocketUrl;
+    environment.REA_SHIM_LEDGER_URL = shimReplay.url;
+    // PATH is evidence-producing input. Inheriting the host PATH here would let
+    // the authority and reconstruction probe different tools without recording
+    // that difference. Scenarios must opt in through environment or
+    // inherit_environment; deterministic shims always take precedence.
+    environment.PATH = [shimReplay.binPath, environment.PATH ?? ""]
+        .filter((part) => part.length > 0)
+        .join(":");
+    return environment;
+};

package/dist/application/ProcessCaptureLifecycle.js

@@ -33,6 +33,7 @@ export const buildCaptureResult = (options) => ({
     shim_events: options.shimEvents,
     protocol_events: redactProtocolEvents(options.replay.events, options.scenario),
     replay_transitions: options.replay.transitions,
+    reactive_run: options.reactiveRun,
     event_journal: options.eventJournal,
     files_before: options.before.files,
     files_after: options.after.files,

package/dist/application/ProcessCheckpoints.js

@@ -79,6 +79,11 @@ export class ProcessCheckpoints {
     capture(name) {
         this.#scheduleCapture(name, this.#signal);
     }
+    /** Read one committed checkpoint for synchronous journal projection. */
+    at(index) {
+        const checkpoint = this.#captures[index];
+        return checkpoint === undefined ? undefined : structuredClone(checkpoint);
+    }
     #scheduleCapture(name, signal) {
         if (this.#captured.has(name))
             return;

package/dist/application/ProcessHarness.js

@@ -8,37 +8,14 @@ import { snapshotRoots } from "./FilesystemSnapshot.js";
 import { ProcessCheckpoints } from "./ProcessCheckpoints.js";
 import { TerminalRenderer } from "./TerminalRenderer.js";
 import { startCommandShimReplay, } from "./CommandShimReplay.js";
-import { normalizeProcessText } from "./ProcessNormalization.js";
+import { normalizeProcessShimEvent, 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";
+import { assertSupportedReactiveScenario, projectProcessReactiveRun, startProcessReactiveHarness, } from "./ProcessReactiveHarness.js";
+import { makeProcessCaptureEnvironment } from "./ProcessCaptureEnvironment.js";
 export { probeProcessCaptureCapability } from "./ProcessCaptureCapability.js";
-const makeEnvironment = (options) => {
-    const { scenario, home, replay, shimReplay, runId } = options;
-    const environment = {
-        ...scenario.environment,
-        HOME: home,
-        TERM: "xterm-256color",
-        REA_PROCESS_RUN_ID: runId,
-    };
-    for (const name of scenario.inherit_environment) {
-        const value = process.env[name];
-        if (value !== undefined)
-            environment[name] = value;
-    }
-    environment.REA_REPLAY_HTTP_URL = replay.httpUrl;
-    environment.REA_REPLAY_WEBSOCKET_URL = replay.websocketUrl;
-    environment.REA_SHIM_LEDGER_URL = shimReplay.url;
-    // PATH is evidence-producing input. Inheriting the host PATH here would let
-    // the authority and reconstruction probe different tools without recording
-    // that difference. Scenarios must opt in through environment or
-    // inherit_environment; deterministic shims always take precedence.
-    environment.PATH = [shimReplay.binPath, environment.PATH ?? ""]
-        .filter((part) => part.length > 0)
-        .join(":");
-    return environment;
-};
 const cleanupFailedStartup = async (options) => {
     options.terminal?.kill("SIGKILL");
     const cleanupFailure = await releaseProcessResources({
@@ -61,6 +38,11 @@ const createTerminalRenderer = (scenario, temporaryRoot, terminalPid, recordEven
     normalize: (value) => normalizeProcessText(value, scenario, temporaryRoot, terminalPid()),
     recordEvent,
 });
+const reactiveCapture = (options, protocolEvents) => ({
+    ...options,
+    processSamples: options.samples,
+    protocolEvents,
+});
 const startCaptureRuntime = async (options) => {
     const { scenario } = options;
     let replay;
@@ -68,6 +50,7 @@ const startCaptureRuntime = async (options) => {
     let checkpoints;
     let shimReplay;
     let terminal;
+    let reactive;
     try {
         const { spawn } = await import("@lydell/node-pty");
         replay = await startLoopbackReplay(scenario, options.recordEvent);
@@ -82,7 +65,7 @@ const startCaptureRuntime = async (options) => {
         shimReplay = await startCommandShimReplay(scenario, options.temporaryRoot, started, options.recordEvent);
         terminal = spawn(scenario.executable, [...scenario.arguments], {
             cwd: scenario.working_directory,
-            env: makeEnvironment({ ...options, replay, shimReplay }),
+            env: makeProcessCaptureEnvironment({ ...options, replay, shimReplay }),
             cols: scenario.terminal.columns,
             rows: scenario.terminal.rows,
             name: "xterm-256color",
@@ -95,6 +78,15 @@ const startCaptureRuntime = async (options) => {
             renderer,
             checkpoints,
         });
+        reactive = startProcessReactiveHarness({
+            capture: reactiveCapture(options, () => replay?.events ?? []),
+            scenario,
+            terminal: () => terminal,
+            renderer,
+            checkpoints,
+            shimReplay,
+            started,
+        });
         scheduleScenarioInteractions({
             ...options,
             getTerminal: () => terminal,
@@ -120,9 +112,12 @@ const startCaptureRuntime = async (options) => {
             lastOutput: () => lastOutput,
             framesTruncated,
             stopSampler,
+            reactive,
         };
     }
     catch (cause) {
+        reactive?.unsubscribe();
+        await reactive?.coordinator.close();
         return cleanupFailedStartup({
             cause,
             timers: options.timers,
@@ -136,12 +131,9 @@ const startCaptureRuntime = async (options) => {
         });
     }
 };
-const normalizedShimEvents = (runtime, scenario, temporaryRoot) => runtime.shimReplay.events.map((event) => ({
-    ...event,
-    arguments: event.arguments.map((argument) => normalizeProcessText(argument, scenario, temporaryRoot, runtime.terminal.pid)),
-    working_directory: normalizeProcessText(event.working_directory, scenario, temporaryRoot, runtime.terminal.pid),
-}));
+const normalizedShimEvents = (runtime, scenario, temporaryRoot) => runtime.shimReplay.events.map((event) => normalizeProcessShimEvent(event, scenario, temporaryRoot, runtime.terminal.pid));
 const finishProcessRun = async (options) => {
+    options.runtime?.reactive?.unsubscribe();
     await options.stopSampler();
     const cleanupFailure = await releaseProcessResources({
         timers: options.timers,
@@ -156,10 +148,16 @@ const finishProcessRun = async (options) => {
             ? []
             : selectCapturedProcessGroupIds(options.runtime.terminal.pid, options.samples),
     });
+    if (cleanupFailure !== undefined)
+        await options.runtime?.reactive?.coordinator.submit({
+            kind: "cleanup_failed",
+        });
+    await options.runtime?.reactive?.coordinator.close();
     let { capture, executionFailure } = options;
     if (capture !== undefined) {
         capture = {
             ...capture,
+            reactive_run: projectProcessReactiveRun(options.runtime?.reactive),
             settlement: {
                 ...capture.settlement,
                 cleanup_outcome: capture.settlement.state === "quiesced"
@@ -179,8 +177,17 @@ const completeCapture = async (options) => {
     const { runtime, scenario } = options;
     runtime.checkpoints.trigger("root_exit");
     const { reason } = options.exit;
-    if (reason === "cancelled")
+    if (reason === "cancelled") {
+        if (runtime.reactive !== undefined) {
+            await runtime.reactive.coordinator.submit({ kind: "cancelled" });
+            runtime.reactive.unsubscribe();
+        }
         throw processCaptureCancelled();
+    }
+    if (runtime.reactive !== undefined) {
+        await runtime.reactive.coordinator.submit({ kind: "target_lost" });
+        runtime.reactive.unsubscribe();
+    }
     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;
@@ -203,6 +210,7 @@ const completeCapture = async (options) => {
         exit: { ...options.exit, reason },
         samples: options.samples,
         replay: runtime.replay,
+        reactiveRun: projectProcessReactiveRun(runtime.reactive),
         before: options.before,
         after,
         truncated,
@@ -220,10 +228,12 @@ const completeCapture = async (options) => {
 };
 /** Execute one authorized scenario and return bounded observations. */
 const runProcessScenario = async (scenario, policy, signal) => {
+    assertSupportedReactiveScenario(scenario);
     const { temporaryRoot, runId, home, before } = await prepareProcessCapture(scenario, policy, signal);
     const frames = [];
     const samples = [];
-    const { entries: eventJournal, recordEvent } = createProcessCaptureJournal();
+    const journal = createProcessCaptureJournal();
+    const { entries: eventJournal, recordEvent } = journal;
     let runtime;
     const timers = new Set();
     let capture;
@@ -244,6 +254,7 @@ const runProcessScenario = async (scenario, policy, signal) => {
             timers,
             dispatchedEventIndexes,
             recordEvent,
+            journal,
             ...(signal === undefined ? {} : { signal }),
         });
         stopSampler = runtime.stopSampler;

package/dist/application/ProcessNormalization.js

@@ -54,6 +54,12 @@ export const normalizeProcessSamples = (samples, scenario, rootPid) => {
         command: normalizeCommand(sample.command),
     }));
 };
+/** Normalize one shim observation identically for live matching and capture. */
+export const normalizeProcessShimEvent = (event, scenario, temporaryRoot, rootPid) => ({
+    ...event,
+    arguments: event.arguments.map((argument) => normalizeProcessText(argument, scenario, temporaryRoot, rootPid)),
+    working_directory: normalizeProcessText(event.working_directory, scenario, temporaryRoot, rootPid),
+});
 const normalizePidTokens = (value, identifiers) => {
     const tokens = [...new Set(identifiers)]
         .filter((identifier) => Number.isSafeInteger(identifier) && identifier > 0)

package/dist/application/ProcessReactiveCoordinator.js

@@ -153,7 +153,7 @@ export class ProcessReactiveCoordinator {
             decision = commitProcessReactiveProposal(this.#scenario, decision, effectResults);
         }
         this.#snapshot = decision.snapshot;
-        this.#onDecision?.(decision);
+        this.#onDecision?.(decision, input);
         if (this.#snapshot.status === "finished")
             this.#clearTimers();
         else if (this.#accepting &&
@@ -162,16 +162,23 @@ export class ProcessReactiveCoordinator {
                     this.#snapshot.state_entry_capture_order))
             this.#scheduleStateDeadline();
         for (const result of effectResults)
-            if (result.status === "succeeded")
+            if (result.status === "succeeded" &&
+                !this.#hasObservation(result.observation.event_id))
                 this.#enqueueOwned({
                     kind: "observation",
                     observation: result.observation,
                 });
     }
+    #hasObservation(eventId) {
+        return (this.#snapshot.observations.some((observation) => observation.event_id === eventId) ||
+            this.#pendingInputs.some((input) => input.kind === "observation" &&
+                input.observation.event_id === eventId));
+    }
     #interruptsEffects(input) {
         if (input.kind === "cancelled" ||
             input.kind === "cleanup_failed" ||
-            input.kind === "scenario_deadline")
+            input.kind === "scenario_deadline" ||
+            input.kind === "target_lost")
             return true;
         return (input.kind === "state_deadline" &&
             input.state_id === this.#snapshot.active_state &&

package/dist/application/ProcessReactiveEffects.js

@@ -7,6 +7,8 @@ const interactionData = (action) => {
             : action.data;
     if (action.type === "resize")
         return `${String(action.columns)}x${String(action.rows)}`;
+    if (action.type === "close_stdin")
+        return "";
     return action.signal;
 };
 const interactionType = (action) => {
@@ -14,6 +16,8 @@ const interactionType = (action) => {
         return "input";
     if (action.type === "resize")
         return "resize";
+    if (action.type === "close_stdin")
+        return "stdin_close";
     return "signal";
 };
 const performTerminalAction = (terminal, renderer, action, atMs) => {
@@ -23,6 +27,8 @@ const performTerminalAction = (terminal, renderer, action, atMs) => {
         terminal.resize(action.columns, action.rows);
         renderer.resize(action.columns, action.rows, atMs);
     }
+    else if (action.type === "close_stdin")
+        terminal.closeInput();
     else
         terminal.kill(action.signal);
 };
@@ -109,7 +115,15 @@ const triggerSources = (trigger) => {
     if (trigger.kind === "terminal_text")
         return [];
     if (trigger.kind === "event")
-        return ["terminal_raw", "interaction", "filesystem"].includes(trigger.source)
+        return [
+            "terminal_raw",
+            "interaction",
+            "process",
+            "filesystem",
+            "http",
+            "websocket",
+            "shim",
+        ].includes(trigger.source)
             ? []
             : [trigger.source];
     return trigger.kind === "repeat"

package/dist/application/ProcessReactiveHarness.js

@@ -0,0 +1,100 @@
+import { ProcessCaptureError } from "./ProcessCaptureError.js";
+import { ProcessReactiveCoordinator } from "./ProcessReactiveCoordinator.js";
+import { executeProcessReactiveEffects, unsupportedProcessReactiveFeatures, } from "./ProcessReactiveEffects.js";
+import { subscribeProcessReactiveObservations } from "./ProcessReactiveObservations.js";
+import { normalizeProcessSamples, normalizeProcessShimEvent, redactProtocolEvents, } from "./ProcessNormalization.js";
+const reactiveTerminalFor = (terminal) => {
+    if (terminal === undefined)
+        return undefined;
+    return {
+        write: (data) => terminal.write(data),
+        resize: (columns, rows) => terminal.resize(columns, rows),
+        closeInput: () => {
+            const end = Reflect.get(terminal, "end");
+            if (typeof end !== "function")
+                throw new ProcessCaptureError("PTY backend does not expose an stdin-close operation");
+            Reflect.apply(end, terminal, []);
+        },
+        kill: (signal) => terminal.kill(signal),
+    };
+};
+const controlKind = (input) => input.kind === "observation" ? undefined : input.kind;
+/** Reject reactive declarations the current process adapter cannot execute. */
+export const assertSupportedReactiveScenario = (scenario) => {
+    if (scenario.reactive === null)
+        return;
+    const unsupported = unsupportedProcessReactiveFeatures(scenario.reactive);
+    if (unsupported.length === 0)
+        return;
+    throw new ProcessCaptureError(`reactive scenario requests unsupported features: ${unsupported.join(", ")}`);
+};
+/**
+ * Attach the serialized reactive runtime once the target PID is available.
+ *
+ * Subscription replays journal entries admitted during launcher startup before
+ * observing new records, so PID-dependent normalization cannot drop them.
+ */
+export const startProcessReactiveHarness = (options) => {
+    if (options.scenario.reactive === null)
+        return undefined;
+    const controls = [];
+    const coordinator = new ProcessReactiveCoordinator({
+        scenario: options.scenario.reactive,
+        executor: {
+            execute: (actions, signal) => executeProcessReactiveEffects({
+                terminal: () => reactiveTerminalFor(options.terminal()),
+                renderer: options.renderer,
+                checkpoints: options.checkpoints,
+                interactions: options.capture.interactions,
+                journal: options.capture.journal,
+                startedAtMs: options.started,
+                now: Date.now,
+            }, actions, signal),
+        },
+        onDecision: (decision, input) => {
+            const kind = controlKind(input);
+            if (kind === undefined || decision.kind !== "finished")
+                return;
+            controls.push({
+                sequence: controls.length,
+                kind,
+                after_capture_order: decision.snapshot.observations.at(-1)?.capture_order ?? -1,
+            });
+        },
+    });
+    return {
+        coordinator,
+        controls,
+        unsubscribe: subscribeProcessReactiveObservations({
+            journal: options.capture.journal,
+            frames: options.capture.frames,
+            interactions: options.capture.interactions,
+            checkpointAt: (index) => options.checkpoints.at(index),
+            processSampleAt: (index) => {
+                const rootPid = options.terminal()?.pid;
+                return rootPid === undefined
+                    ? undefined
+                    : normalizeProcessSamples(options.capture.processSamples, options.scenario, rootPid)[index];
+            },
+            protocolEventAt: (index) => redactProtocolEvents(options.capture.protocolEvents().slice(index, index + 1), options.scenario)[0],
+            shimEventAt: (index) => {
+                const event = options.shimReplay.events[index];
+                const rootPid = options.terminal()?.pid;
+                return event === undefined || rootPid === undefined
+                    ? undefined
+                    : normalizeProcessShimEvent(event, options.scenario, options.capture.temporaryRoot, rootPid);
+            },
+            sink: coordinator,
+        }),
+    };
+};
+/** Project internal reducer state into the stable Process Capture shape. */
+export const projectProcessReactiveRun = (harness) => harness === undefined
+    ? null
+    : {
+        status: harness.coordinator.snapshot.status,
+        outcome: harness.coordinator.snapshot.outcome,
+        active_state: harness.coordinator.snapshot.active_state,
+        transitions: harness.coordinator.snapshot.transitions,
+        controls: harness.controls,
+    };