Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(process): harden capture validation and cleanup
morlutoac78de0a74b0
diff --git a/src/application/ProcessCaptureAuthority.ts b/src/application/ProcessCaptureAuthority.tsnew file mode 100644index 000000000..c33ce2954--- /dev/null+++ b/src/application/ProcessCaptureAuthority.ts@@ -0,0 +1,48 @@+import { realpath } from "node:fs/promises";++import type {+ ProcessExecutionPolicy,+ ProcessScenario,+} from "../domain/processCapture.js";+import { ProcessCaptureError } from "./ProcessCaptureError.js";++const isWithin = (candidate: string, root: string): boolean =>+ candidate === root ||+ candidate.startsWith(`${root.endsWith("/") ? root.slice(0, -1) : root}/`);++export const assertRealPathAuthority = async (+ scenario: ProcessScenario,+ policy: ProcessExecutionPolicy,+): Promise<void> => {+ const executable = await realpath(scenario.executable);+ const executableRoots = await Promise.all(+ policy.executableRoots.map((root) => realpath(root)),+ );+ if (!executableRoots.some((root) => isWithin(executable, root)))+ throw new ProcessCaptureError(+ "resolved executable is outside approved roots",+ );+ const workingDirectory = await realpath(scenario.working_directory);+ const workingRoots = await Promise.all(+ policy.workingRoots.map((root) => realpath(root)),+ );+ if (!workingRoots.some((root) => isWithin(workingDirectory, root)))+ throw new ProcessCaptureError(+ "resolved working directory is outside approved roots",+ );+ for (const root of scenario.filesystem_roots) {+ const resolvedRoot = await realpath(root);+ if (!workingRoots.some((approved) => isWithin(resolvedRoot, approved)))+ throw new ProcessCaptureError(+ "resolved filesystem root is outside approved roots",+ );+ }+};++/** Expected refusal or runtime failure from the process capture adapter. */+export const assertNotCancelled = (signal: AbortSignal | undefined): void => {+ if (signal?.aborted === true)+ throw new ProcessCaptureError("process capture was cancelled");+};++/** Runtime availability of the native PTY adapter on this host. */diff --git a/src/application/ProcessCaptureCapability.ts b/src/application/ProcessCaptureCapability.tsnew file mode 100644index 000000000..542fe9845--- /dev/null+++ b/src/application/ProcessCaptureCapability.ts@@ -0,0 +1,38 @@+import { tmpdir } from "node:os";+import { spawn } from "node-pty";++export type ProcessCaptureCapability =+ | { readonly available: true; readonly backend: "node-pty" }+ | {+ readonly available: false;+ readonly backend: "node-pty";+ readonly reason: string;+ };++/** Probe the actual native PTY seam instead of inferring support from the OS name. */+export const probeProcessCaptureCapability =+ async (): Promise<ProcessCaptureCapability> => {+ try {+ const terminal = spawn(+ process.platform === "win32" ? "cmd.exe" : "/bin/sh",+ process.platform === "win32" ? ["/c", "exit", "0"] : ["-c", "exit 0"],+ {+ cwd: tmpdir(),+ env: { HOME: tmpdir(), TERM: "xterm-256color" },+ cols: 80,+ rows: 24,+ name: "xterm-256color",+ },+ );+ await new Promise<void>((resolveExit) =>+ terminal.onExit(() => resolveExit()),+ );+ return { available: true, backend: "node-pty" };+ } catch {+ return {+ available: false,+ backend: "node-pty",+ reason: "the native PTY backend could not start a probe process",+ };+ }+ };diff --git a/src/application/ProcessCaptureError.ts b/src/application/ProcessCaptureError.tsnew file mode 100644index 000000000..17593e7d1--- /dev/null+++ b/src/application/ProcessCaptureError.ts@@ -0,0 +1,6 @@+import { AnalysisError } from "../domain/errors.js";++/** Typed application failure produced by controlled process capture. */+export class ProcessCaptureError extends AnalysisError {+ readonly _tag = "ProcessCaptureError";+}diff --git a/src/application/ProcessCaptureLifecycle.ts b/src/application/ProcessCaptureLifecycle.tsnew file mode 100644index 000000000..7470079fd--- /dev/null+++ b/src/application/ProcessCaptureLifecycle.ts@@ -0,0 +1,417 @@+import { createHash, randomUUID } from "node:crypto";+import { createReadStream } from "node:fs";+import { mkdtemp, rm } from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";+import type { IPty } from "node-pty";++import type {+ FilesystemCheckpoint,+ InteractionEvent,+ ProcessCapture,+ ProcessExecutionPolicy,+ ProcessSample,+ ProcessScenario,+ TerminalFrame,+} from "../domain/processCapture.js";+import {+ authorizeProcessScenario,+ digestProcessCommitment,+ processComparisonContract,+ processScenarioCommitment,+} from "../domain/processCapture.js";+import { PRODUCT_IDENTITY } from "../identity.js";+import type { SnapshotResult } from "./FilesystemSnapshot.js";+import { snapshotRoots } from "./FilesystemSnapshot.js";+import type { LoopbackReplay } from "./LoopbackReplay.js";+import {+ cleanupOwnedProcessGroup,+ observeOwnedProcessGroup,+} from "./ProcessOwnership.js";+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 type { CommandShimReplay } from "./CommandShimReplay.js";+import { PROCESS_PROVIDER } from "./ProcessEvidence.js";+import { TerminalRenderer } from "./TerminalRenderer.js";++interface TerminalExitOptions {+ readonly terminal: IPty;+ readonly scenario: ProcessScenario;+ readonly started: number;+ readonly lastOutput: () => number;+ readonly signal: AbortSignal | undefined;+ readonly timers: Set<NodeJS.Timeout>;+ readonly interactions: InteractionEvent[];+ readonly dispatchedEventIndexes: ReadonlySet<number>;+}++interface CaptureResultOptions {+ readonly frames: readonly TerminalFrame[];+ readonly exit: {+ readonly exitCode: number;+ readonly signal?: number;+ readonly reason: "exited" | "timeout" | "idle_timeout";+ };+ readonly samples: readonly ProcessSample[];+ readonly replay: LoopbackReplay;+ readonly before: SnapshotResult;+ readonly after: SnapshotResult;+ readonly truncated: boolean;+ readonly scenario: ProcessScenario;+ readonly rootPid: number;+ readonly samplingPartial: boolean;+ readonly renderedFrames: ProcessCapture["rendered_frames"];+ readonly interactions: readonly InteractionEvent[];+ readonly checkpoints: readonly FilesystemCheckpoint[];+ readonly shimEvents: ProcessCapture["shim_events"];+ readonly settlement: ProcessCapture["settlement"];+ readonly manifest: ProcessCapture["manifest"];+}++export const buildCaptureResult = (+ options: CaptureResultOptions,+): ProcessCapture => ({+ schema_version: 4,+ 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 })),+ interaction_events: options.interactions,+ exit: {+ code:+ options.exit.reason === "exited" && options.exit.exitCode >= 0+ ? options.exit.exitCode+ : null,+ signal: options.exit.signal ?? null,+ reason: options.exit.reason,+ },+ settlement: options.settlement,+ process_samples: normalizeProcessSamples(+ options.samples,+ options.scenario,+ options.rootPid,+ ),+ filesystem_checkpoints: options.checkpoints,+ shim_events: options.shimEvents,+ protocol_events: redactProtocolEvents(+ options.replay.events,+ options.scenario,+ ),+ files_before: options.before.files,+ files_after: options.after.files,+ filesystem_effects: classifyFilesystemEffects(+ options.before.files,+ options.after.files,+ ),+ truncated: options.truncated,+ limitations: [+ "Process trees are sampled and may omit short-lived descendants.",+ ...(options.samplingPartial+ ? ["Process-tree sampling ended with an incomplete observation."]+ : []),+ "Filesystem observations are before/after snapshots, not syscall traces.",+ "The harness does not enforce external network isolation.",+ ],+ residual_unknowns: [+ {+ scope: "process",+ reason: "Process trees are sampled and may omit short-lived descendants.",+ },+ {+ scope: "network",+ reason: "External network isolation is not enforced by this adapter.",+ },+ ],+ cleanup: {+ owned_process_group: "verified",+ temporary_root: "removed",+ },+});++const hashFile = async (path: string): Promise<string> => {+ const hash = createHash("sha256");+ for await (const chunk of createReadStream(path)) hash.update(chunk);+ return hash.digest("hex");+};++export const createRunManifest = async (+ scenario: ProcessScenario,+ startedAt: Date,+ completedAt: Date,+): Promise<ProcessCapture["manifest"]> => {+ const executableSha256 = await hashFile(scenario.executable);+ const scenarioCommitment = processScenarioCommitment(+ scenario,+ executableSha256,+ );+ const comparisonContract = processComparisonContract(scenario);+ return {+ rea_version: PRODUCT_IDENTITY.packageVersion,+ provider_version: PROCESS_PROVIDER.version,+ platform: process.platform,+ architecture: process.arch,+ pty_backend: "node-pty",+ started_at: startedAt.toISOString(),+ completed_at: completedAt.toISOString(),+ scenario: scenarioCommitment,+ comparison_contract: comparisonContract,+ shim_plan: scenario.command_shims,+ replay_plan: scenario.replay,+ full_scenario_sha256: digestProcessCommitment(scenarioCommitment),+ comparison_contract_sha256: digestProcessCommitment(comparisonContract),+ executable_sha256: executableSha256,+ normalization_sha256: digestProcessCommitment(scenario.normalization),+ shim_plan_sha256: digestProcessCommitment(scenario.command_shims),+ replay_plan_sha256: digestProcessCommitment(scenario.replay),+ };+};++export const observeSettlement = async (+ runId: string,+ processGroupIds: readonly number[],+ settleMs: number,+): Promise<Omit<ProcessCapture["settlement"], "cleanup_outcome">> => {+ if (process.platform === "win32")+ return { state: "unverifiable", elapsed_ms: 0 };+ const started = Date.now();+ let consecutiveEmpty = 0;+ let deadlineReached = false;+ while (!deadlineReached) {+ const observations = await Promise.all(+ [...new Set(processGroupIds)].map((processGroupId) =>+ observeOwnedProcessGroup({+ runId,+ leaderPid: processGroupId,+ processGroupId,+ }),+ ),+ );+ if (observations.some(({ state }) => state === "unverifiable"))+ return { state: "unverifiable", elapsed_ms: Date.now() - started };+ if (observations.every(({ state }) => state === "empty")) {+ consecutiveEmpty += 1;+ if (consecutiveEmpty >= 2)+ return { state: "quiesced", elapsed_ms: Date.now() - started };+ } else consecutiveEmpty = 0;+ deadlineReached = Date.now() - started >= settleMs;+ if (deadlineReached) break;+ await new Promise<void>((resolve) => setTimeout(resolve, 50));+ }+ return { state: "alive_at_deadline", elapsed_ms: Date.now() - started };+};++export const awaitTerminalExit = async ({+ terminal,+ scenario,+ started,+ lastOutput,+ signal,+ timers,+ interactions,+ dispatchedEventIndexes,+}: TerminalExitOptions): Promise<{+ exitCode: number;+ signal?: number;+ reason: "exited" | "timeout" | "idle_timeout" | "cancelled";+}> =>+ 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" | "timeout" | "idle_timeout" | "cancelled" = "exited";+ terminal.onExit((exit) => {+ for (const [eventIndex, event] of scenario.events.entries()) {+ if (dispatchedEventIndexes.has(eventIndex)) continue;+ interactions.push({+ sequence: interactions.length,+ scheduled_at_ms: event.at_ms,+ dispatched_at_ms: Math.max(0, Date.now() - started),+ type: event.type,+ data:+ event.type === "input"+ ? "<not-dispatched>"+ : event.type === "resize"+ ? `${String(event.columns)}x${String(event.rows)}`+ : event.signal,+ outcome: "target_exited",+ });+ }+ for (const timer of timers) {+ clearTimeout(timer);+ clearInterval(timer);+ }+ timers.clear();+ resolveExit({ ...exit, reason });+ });+ const timeout = setInterval(() => {+ if (signal?.aborted === true) {+ reason = "cancelled";+ terminal.kill("SIGKILL");+ } else if (Date.now() - started >= scenario.timeout_ms) {+ reason = "timeout";+ terminal.kill("SIGKILL");+ } else if (Date.now() - lastOutput() >= scenario.idle_timeout_ms) {+ reason = "idle_timeout";+ terminal.kill("SIGKILL");+ }+ }, 20);+ timers.add(timeout);+ });++export const releaseProcessResources = async (options: {+ readonly timers: ReadonlySet<NodeJS.Timeout>;+ readonly replay: LoopbackReplay | undefined;+ readonly terminal: IPty | undefined;+ readonly renderer: TerminalRenderer | undefined;+ readonly shimReplay: CommandShimReplay | undefined;+ readonly checkpoints: ProcessCheckpoints | undefined;+ readonly runId: string;+ readonly temporaryRoot: string;+ readonly sampledProcessGroupIds: readonly number[];+}): Promise<string | undefined> => {+ for (const timer of options.timers) clearTimeout(timer);+ let failure: string | undefined;+ try {+ await options.replay?.close();+ } catch {+ failure = "loopback replay cleanup failed";+ }+ try {+ await options.shimReplay?.close();+ } catch {+ failure ??= "command shim replay cleanup failed";+ }+ try {+ await options.renderer?.dispose();+ } catch {+ failure ??= "terminal renderer cleanup failed";+ }+ try {+ await options.checkpoints?.dispose();+ } catch {+ failure ??= "filesystem checkpoint cleanup failed";+ }+ if (options.terminal !== undefined && process.platform !== "win32") {+ const processGroupIds = new Set([+ options.terminal.pid,+ ...options.sampledProcessGroupIds,+ ]);+ for (const processGroupId of processGroupIds) {+ const cleaned = await cleanupOwnedProcessGroup({+ runId: options.runId,+ leaderPid: processGroupId,+ processGroupId,+ });+ if (!cleaned.cleaned) failure ??= cleaned.reason;+ }+ }+ try {+ await rm(options.temporaryRoot, { recursive: true, force: true });+ } catch {+ failure ??= "temporary process root cleanup failed";+ }+ return failure;+};++export const captureTerminalFrames = (options: {+ readonly terminal: IPty;+ readonly scenario: ProcessScenario;+ readonly frames: TerminalFrame[];+ readonly started: number;+ readonly temporaryRoot: string;+ readonly onOutput: () => void;+ readonly onFirstOutput: () => void;+ readonly renderer: TerminalRenderer;+ readonly checkpoints: ProcessCheckpoints;+}): (() => boolean) => {+ let outputBytes = 0;+ let truncated = false;+ options.terminal.onData((data) => {+ options.onFirstOutput();+ options.onOutput();+ const bytes = Buffer.byteLength(data);+ if (+ options.frames.length >= options.scenario.limits.frames ||+ outputBytes + bytes > options.scenario.limits.output_bytes+ ) {+ truncated = true;+ return;+ }+ outputBytes += bytes;+ const atMs =+ Math.floor(+ (Date.now() - options.started) /+ options.scenario.normalization.time_bucket_ms,+ ) * options.scenario.normalization.time_bucket_ms;+ const normalized = normalizeProcessText(+ data,+ options.scenario,+ options.temporaryRoot,+ options.terminal.pid,+ );+ options.frames.push({+ sequence: options.frames.length,+ at_ms: atMs,+ data: normalized,+ });+ options.renderer.write(data, atMs);+ options.checkpoints.observeTerminal(normalized);+ });+ return () => truncated;+};++export const resolveProcessResult = (+ capture: ProcessCapture | undefined,+ executionFailure: unknown,+ cleanupFailure: string | undefined,+): ProcessCapture => {+ if (executionFailure instanceof ProcessCaptureError) throw executionFailure;+ if (executionFailure !== undefined)+ throw new ProcessCaptureError("process capture failed", {+ cause: executionFailure,+ });+ if (cleanupFailure !== undefined)+ throw new ProcessCaptureError(cleanupFailure);+ if (capture === undefined)+ throw new ProcessCaptureError("process capture produced no result");+ return capture;+};++export const prepareProcessCapture = async (+ scenario: ProcessScenario,+ policy: ProcessExecutionPolicy,+ signal: AbortSignal | undefined,+): Promise<{+ readonly temporaryRoot: string;+ readonly runId: string;+ readonly home: string;+ readonly before: SnapshotResult;+}> => {+ const decision = authorizeProcessScenario(scenario, policy);+ if (!decision.allowed) throw new ProcessCaptureError(decision.reason);+ await assertRealPathAuthority(scenario, policy);+ assertNotCancelled(signal);+ const before = await snapshotRoots(scenario, signal);+ const temporaryRoot = await mkdtemp(join(tmpdir(), "rea-process-"));+ const runId = randomUUID();+ const home = join(temporaryRoot, "home");+ await import("node:fs/promises").then(({ mkdir }) => mkdir(home));+ return { temporaryRoot, runId, home, before };+};diff --git a/src/application/ProcessHarness.ts b/src/application/ProcessHarness.tsindex 21e37e025..986867a53 100644--- a/src/application/ProcessHarness.ts+++ b/src/application/ProcessHarness.ts@@ -1,11 +1,5 @@-import { createHash, randomUUID } from "node:crypto";-import { createReadStream } from "node:fs";-import { mkdtemp, realpath, rm } from "node:fs/promises";-import { tmpdir } from "node:os";-import { join } from "node:path";import { spawn, type IPty } from "node-pty";import type {- FilesystemCheckpoint,InteractionEvent,ProcessCapture,ProcessExecutionPolicy,@@ -13,118 +7,35 @@ import type {ProcessScenario,TerminalFrame,} from "../domain/processCapture.js";-import {- authorizeProcessScenario,- digestProcessCommitment,- processComparisonContract,- processScenarioCommitment,- validateProcessCapture,-} from "../domain/processCapture.js";+import { validateProcessCapture } from "../domain/processCapture.js";import { err, ok, type Result } from "../domain/result.js";-import { AnalysisError } from "../domain/errors.js";-import { PRODUCT_IDENTITY } from "../identity.js";+import { ProcessCaptureError } from "./ProcessCaptureError.js";++export { ProcessCaptureError } from "./ProcessCaptureError.js";import { startLoopbackReplay, type LoopbackReplay } from "./LoopbackReplay.js";-import {- cleanupOwnedProcessGroup,- observeOwnedProcessGroup,-} from "./ProcessOwnership.js";import { startProcessSampler } from "./ProcessSampling.js";-import { snapshotRoots, type SnapshotResult } from "./FilesystemSnapshot.js";-import {- classifyFilesystemEffects,- ProcessCheckpoints,-} from "./ProcessCheckpoints.js";+import { snapshotRoots } from "./FilesystemSnapshot.js";+import { ProcessCheckpoints } from "./ProcessCheckpoints.js";import { TerminalRenderer } from "./TerminalRenderer.js";import {startCommandShimReplay,type CommandShimReplay,} from "./CommandShimReplay.js";+import { normalizeProcessText } from "./ProcessNormalization.js";import {- normalizeProcessSamples,- normalizeProcessText,- redactProtocolEvents,-} from "./ProcessNormalization.js";-import { PROCESS_PROVIDER } from "./ProcessEvidence.js";+ awaitTerminalExit,+ buildCaptureResult,+ captureTerminalFrames,+ createRunManifest,+ observeSettlement,+ prepareProcessCapture,+ releaseProcessResources,+ resolveProcessResult,+} from "./ProcessCaptureLifecycle.js";+import { assertNotCancelled } from "./ProcessCaptureAuthority.js";-const isWithin = (candidate: string, root: string): boolean =>- candidate === root ||- candidate.startsWith(`${root.endsWith("/") ? root.slice(0, -1) : root}/`);--const assertRealPathAuthority = async (- scenario: ProcessScenario,- policy: ProcessExecutionPolicy,-): Promise<void> => {- const executable = await realpath(scenario.executable);- const executableRoots = await Promise.all(- policy.executableRoots.map((root) => realpath(root)),- );- if (!executableRoots.some((root) => isWithin(executable, root)))- throw new ProcessCaptureError(- "resolved executable is outside approved roots",- );- const workingDirectory = await realpath(scenario.working_directory);- const workingRoots = await Promise.all(- policy.workingRoots.map((root) => realpath(root)),- );- if (!workingRoots.some((root) => isWithin(workingDirectory, root)))- throw new ProcessCaptureError(- "resolved working directory is outside approved roots",- );- for (const root of scenario.filesystem_roots) {- const resolvedRoot = await realpath(root);- if (!workingRoots.some((approved) => isWithin(resolvedRoot, approved)))- throw new ProcessCaptureError(- "resolved filesystem root is outside approved roots",- );- }-};--/** Expected refusal or runtime failure from the process capture adapter. */-export class ProcessCaptureError extends AnalysisError {- readonly _tag = "ProcessCaptureError";-}--const assertNotCancelled = (signal: AbortSignal | undefined): void => {- if (signal?.aborted === true)- throw new ProcessCaptureError("process capture was cancelled");-};--/** Runtime availability of the native PTY adapter on this host. */-export type ProcessCaptureCapability =- | { readonly available: true; readonly backend: "node-pty" }- | {- readonly available: false;- readonly backend: "node-pty";- readonly reason: string;- };--/** Probe the actual native PTY seam instead of inferring support from the OS name. */-export const probeProcessCaptureCapability =- async (): Promise<ProcessCaptureCapability> => {- try {- const terminal = spawn(- process.platform === "win32" ? "cmd.exe" : "/bin/sh",- process.platform === "win32" ? ["/c", "exit", "0"] : ["-c", "exit 0"],- {- cwd: tmpdir(),- env: { HOME: tmpdir(), TERM: "xterm-256color" },- cols: 80,- rows: 24,- name: "xterm-256color",- },- );- await new Promise<void>((resolveExit) =>- terminal.onExit(() => resolveExit()),- );- return { available: true, backend: "node-pty" };- } catch {- return {- available: false,- backend: "node-pty",- reason: "the native PTY backend could not start a probe process",- };- }- };+export { probeProcessCaptureCapability } from "./ProcessCaptureCapability.js";+export type { ProcessCaptureCapability } from "./ProcessCaptureCapability.js";interface EnvironmentOptions {readonly scenario: ProcessScenario;@@ -231,235 +142,22 @@ const eventsRequireReadiness = (scenario: ProcessScenario): boolean =>(event) => event.type === "input" || event.type === "resize",);-interface TerminalExitOptions {+interface StartedCaptureRuntime {+ readonly replay: LoopbackReplay;+ readonly renderer: TerminalRenderer;+ readonly checkpoints: ProcessCheckpoints;+ readonly shimReplay: CommandShimReplay;readonly terminal: IPty;- readonly scenario: ProcessScenario;readonly started: number;+ readonly startedAt: Date;readonly lastOutput: () => number;- readonly signal: AbortSignal | undefined;- readonly timers: Set<NodeJS.Timeout>;- readonly interactions: InteractionEvent[];- readonly dispatchedEventIndexes: ReadonlySet<number>;+ readonly framesTruncated: () => boolean;+ readonly stopSampler: () => Promise<{ readonly partial: boolean }>;}-interface CaptureResultOptions {- readonly frames: readonly TerminalFrame[];- readonly exit: {- readonly exitCode: number;- readonly signal?: number;- readonly reason: "exited" | "timeout" | "idle_timeout";- };- readonly samples: readonly ProcessSample[];- readonly replay: LoopbackReplay;- readonly before: SnapshotResult;- readonly after: SnapshotResult;- readonly truncated: boolean;- readonly scenario: ProcessScenario;- readonly rootPid: number;- readonly samplingPartial: boolean;- readonly renderedFrames: ProcessCapture["rendered_frames"];- readonly interactions: readonly InteractionEvent[];- readonly checkpoints: readonly FilesystemCheckpoint[];- readonly shimEvents: ProcessCapture["shim_events"];- readonly settlement: ProcessCapture["settlement"];- readonly manifest: ProcessCapture["manifest"];-}--const buildCaptureResult = (options: CaptureResultOptions): ProcessCapture => ({- schema_version: 4,- 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 })),- interaction_events: options.interactions,- exit: {- code:- options.exit.reason === "exited" && options.exit.exitCode >= 0- ? options.exit.exitCode- : null,- signal: options.exit.signal ?? null,- reason: options.exit.reason,- },- settlement: options.settlement,- process_samples: normalizeProcessSamples(- options.samples,- options.scenario,- options.rootPid,- ),- filesystem_checkpoints: options.checkpoints,- shim_events: options.shimEvents,- protocol_events: redactProtocolEvents(- options.replay.events,- options.scenario,- ),- files_before: options.before.files,- files_after: options.after.files,- filesystem_effects: classifyFilesystemEffects(- options.before.files,- options.after.files,- ),- truncated: options.truncated,- limitations: [- "Process trees are sampled and may omit short-lived descendants.",- ...(options.samplingPartial- ? ["Process-tree sampling ended with an incomplete observation."]- : []),- "Filesystem observations are before/after snapshots, not syscall traces.",- "The harness does not enforce external network isolation.",- ],- residual_unknowns: [- {- scope: "process",- reason: "Process trees are sampled and may omit short-lived descendants.",- },- {- scope: "network",- reason: "External network isolation is not enforced by this adapter.",- },- ],- cleanup: {- owned_process_group: "verified",- temporary_root: "removed",- },-});--const hashFile = async (path: string): Promise<string> => {- const hash = createHash("sha256");- for await (const chunk of createReadStream(path)) hash.update(chunk);- return hash.digest("hex");-};--const createRunManifest = async (- scenario: ProcessScenario,- startedAt: Date,- completedAt: Date,-): Promise<ProcessCapture["manifest"]> => {- const executableSha256 = await hashFile(scenario.executable);- const scenarioCommitment = processScenarioCommitment(- scenario,- executableSha256,- );- const comparisonContract = processComparisonContract(scenario);- return {- rea_version: PRODUCT_IDENTITY.packageVersion,- provider_version: PROCESS_PROVIDER.version,- platform: process.platform,- architecture: process.arch,- pty_backend: "node-pty",- started_at: startedAt.toISOString(),- completed_at: completedAt.toISOString(),- scenario: scenarioCommitment,- comparison_contract: comparisonContract,- shim_plan: scenario.command_shims,- replay_plan: scenario.replay,- full_scenario_sha256: digestProcessCommitment(scenarioCommitment),- comparison_contract_sha256: digestProcessCommitment(comparisonContract),- executable_sha256: executableSha256,- normalization_sha256: digestProcessCommitment(scenario.normalization),- shim_plan_sha256: digestProcessCommitment(scenario.command_shims),- replay_plan_sha256: digestProcessCommitment(scenario.replay),- };-};--const observeSettlement = async (- runId: string,- processGroupIds: readonly number[],- settleMs: number,-): Promise<Omit<ProcessCapture["settlement"], "cleanup_outcome">> => {- if (process.platform === "win32")- return { state: "unverifiable", elapsed_ms: 0 };- const started = Date.now();- let consecutiveEmpty = 0;- let deadlineReached = false;- while (!deadlineReached) {- const observations = await Promise.all(- [...new Set(processGroupIds)].map((processGroupId) =>- observeOwnedProcessGroup({- runId,- leaderPid: processGroupId,- processGroupId,- }),- ),- );- if (observations.some(({ state }) => state === "unverifiable"))- return { state: "unverifiable", elapsed_ms: Date.now() - started };- if (observations.every(({ state }) => state === "empty")) {- consecutiveEmpty += 1;- if (consecutiveEmpty >= 2)- return { state: "quiesced", elapsed_ms: Date.now() - started };- } else consecutiveEmpty = 0;- deadlineReached = Date.now() - started >= settleMs;- if (deadlineReached) break;- await new Promise<void>((resolve) => setTimeout(resolve, 50));- }- return { state: "alive_at_deadline", elapsed_ms: Date.now() - started };-};--const awaitTerminalExit = async ({- terminal,- scenario,- started,- lastOutput,- signal,- timers,- interactions,- dispatchedEventIndexes,-}: TerminalExitOptions): Promise<{- exitCode: number;- signal?: number;- reason: "exited" | "timeout" | "idle_timeout" | "cancelled";-}> =>- 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" | "timeout" | "idle_timeout" | "cancelled" = "exited";- terminal.onExit((exit) => {- for (const [eventIndex, event] of scenario.events.entries()) {- if (dispatchedEventIndexes.has(eventIndex)) continue;- interactions.push({- sequence: interactions.length,- scheduled_at_ms: event.at_ms,- dispatched_at_ms: Math.max(0, Date.now() - started),- type: event.type,- data:- event.type === "input"- ? "<not-dispatched>"- : event.type === "resize"- ? `${String(event.columns)}x${String(event.rows)}`- : event.signal,- outcome: "target_exited",- });- }- for (const timer of timers) {- clearTimeout(timer);- clearInterval(timer);- }- timers.clear();- resolveExit({ ...exit, reason });- });- const timeout = setInterval(() => {- if (signal?.aborted === true) {- reason = "cancelled";- terminal.kill("SIGKILL");- } else if (Date.now() - started >= scenario.timeout_ms) {- reason = "timeout";- terminal.kill("SIGKILL");- } else if (Date.now() - lastOutput() >= scenario.idle_timeout_ms) {- reason = "idle_timeout";- terminal.kill("SIGKILL");- }- }, 20);- timers.add(timeout);- });--const releaseProcessResources = async (options: {- readonly timers: ReadonlySet<NodeJS.Timeout>;+const cleanupFailedStartup = async (options: {+ readonly cause: unknown;+ readonly timers: Set<NodeJS.Timeout>;readonly replay: LoopbackReplay | undefined;readonly terminal: IPty | undefined;readonly renderer: TerminalRenderer | undefined;@@ -467,319 +165,176 @@ const releaseProcessResources = async (options: {readonly checkpoints: ProcessCheckpoints | undefined;readonly runId: string;readonly temporaryRoot: string;- readonly sampledProcessGroupIds: readonly number[];-}): Promise<string | undefined> => {- for (const timer of options.timers) clearTimeout(timer);- let failure: string | undefined;- try {- await options.replay?.close();- } catch {- failure = "loopback replay cleanup failed";- }- try {- await options.shimReplay?.close();- } catch {- failure ??= "command shim replay cleanup failed";- }- try {- await options.renderer?.dispose();- } catch {- failure ??= "terminal renderer cleanup failed";- }- try {- await options.checkpoints?.dispose();- } catch {- failure ??= "filesystem checkpoint cleanup failed";- }- if (options.terminal !== undefined && process.platform !== "win32") {- const processGroupIds = new Set([- options.terminal.pid,- ...options.sampledProcessGroupIds,- ]);- for (const processGroupId of processGroupIds) {- const cleaned = await cleanupOwnedProcessGroup({- runId: options.runId,- leaderPid: processGroupId,- processGroupId,- });- if (!cleaned.cleaned) failure ??= cleaned.reason;- }- }- try {- await rm(options.temporaryRoot, { recursive: true, force: true });- } catch {- failure ??= "temporary process root cleanup failed";- }- return failure;-};--const captureTerminalFrames = (options: {- readonly terminal: IPty;- readonly scenario: ProcessScenario;- readonly frames: TerminalFrame[];- readonly started: number;- readonly temporaryRoot: string;- readonly onOutput: () => void;- readonly onFirstOutput: () => void;- readonly renderer: TerminalRenderer;- readonly checkpoints: ProcessCheckpoints;-}): (() => boolean) => {- let outputBytes = 0;- let truncated = false;- options.terminal.onData((data) => {- options.onFirstOutput();- options.onOutput();- const bytes = Buffer.byteLength(data);- if (- options.frames.length >= options.scenario.limits.frames ||- outputBytes + bytes > options.scenario.limits.output_bytes- ) {- truncated = true;- return;- }- outputBytes += bytes;- const atMs =- Math.floor(- (Date.now() - options.started) /- options.scenario.normalization.time_bucket_ms,- ) * options.scenario.normalization.time_bucket_ms;- const normalized = normalizeProcessText(- data,- options.scenario,- options.temporaryRoot,- options.terminal.pid,- );- options.frames.push({- sequence: options.frames.length,- at_ms: atMs,- data: normalized,- });- options.renderer.write(data, atMs);- options.checkpoints.observeTerminal(normalized);+}): Promise<never> => {+ options.terminal?.kill("SIGKILL");+ const cleanupFailure = await releaseProcessResources({+ ...options,+ sampledProcessGroupIds: [],});- return () => truncated;-};--const resolveProcessResult = (- capture: ProcessCapture | undefined,- executionFailure: unknown,- cleanupFailure: string | undefined,-): ProcessCapture => {- if (executionFailure instanceof ProcessCaptureError) throw executionFailure;- if (executionFailure !== undefined)- throw new ProcessCaptureError("process capture failed", {- cause: executionFailure,- });if (cleanupFailure !== undefined)- throw new ProcessCaptureError(cleanupFailure);- if (capture === undefined)- throw new ProcessCaptureError("process capture produced no result");- return capture;+ throw new ProcessCaptureError(cleanupFailure, { cause: options.cause });+ throw options.cause;};-const prepareProcessCapture = async (+const createTerminalRenderer = (scenario: ProcessScenario,- policy: ProcessExecutionPolicy,- signal: AbortSignal | undefined,-): Promise<{+ temporaryRoot: string,+ terminalPid: () => number,+): TerminalRenderer =>+ 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()),+ });++const startCaptureRuntime = async (options: {+ readonly scenario: ProcessScenario;+ readonly home: string;readonly temporaryRoot: string;readonly runId: string;- readonly home: string;- readonly before: SnapshotResult;-}> => {- const decision = authorizeProcessScenario(scenario, policy);- if (!decision.allowed) throw new ProcessCaptureError(decision.reason);- await assertRealPathAuthority(scenario, policy);- assertNotCancelled(signal);- const before = await snapshotRoots(scenario, signal);- const temporaryRoot = await mkdtemp(join(tmpdir(), "rea-process-"));- const runId = randomUUID();- const home = join(temporaryRoot, "home");- await import("node:fs/promises").then(({ mkdir }) => mkdir(home));- return { temporaryRoot, runId, home, before };-};--/** Execute one authorized scenario and return bounded observations. */-const runProcessScenario = async (- scenario: ProcessScenario,- policy: ProcessExecutionPolicy,- signal?: AbortSignal,-): Promise<ProcessCapture> => {- const { temporaryRoot, runId, home, before } = await prepareProcessCapture(- scenario,- policy,- signal,- );- const frames: TerminalFrame[] = [];- const samples: ProcessSample[] = [];- let truncated = before.truncated;- let terminal: IPty | undefined;+ readonly before: Awaited<ReturnType<typeof snapshotRoots>>;+ readonly frames: TerminalFrame[];+ readonly samples: ProcessSample[];+ readonly interactions: InteractionEvent[];+ readonly timers: Set<NodeJS.Timeout>;+ readonly dispatchedEventIndexes: Set<number>;+ readonly signal?: AbortSignal;+}): Promise<StartedCaptureRuntime> => {+ const { scenario } = options;let replay: LoopbackReplay | undefined;let renderer: TerminalRenderer | undefined;let checkpoints: ProcessCheckpoints | undefined;let shimReplay: CommandShimReplay | undefined;- let started = 0;- let startedAt = new Date(0);- let lastOutput = 0;- const timers = new Set<NodeJS.Timeout>();- let capture: ProcessCapture | undefined;- let executionFailure: unknown;- let framesTruncated = (): boolean => false;- let stopSampler = async () => ({ partial: false });- let samplingPartial = false;- let settlement: Omit<ProcessCapture["settlement"], "cleanup_outcome"> = {- state: "unverifiable",- elapsed_ms: 0,- };- const interactions: InteractionEvent[] = [];- const dispatchedEventIndexes = new Set<number>();-+ let terminal: IPty | undefined;try {replay = await startLoopbackReplay(scenario);- startedAt = new Date();- started = Date.now();- lastOutput = started;- renderer = 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,- terminal?.pid ?? -1,- ),- });- checkpoints = new ProcessCheckpoints(scenario, started, before, signal);- shimReplay = await startCommandShimReplay(scenario, temporaryRoot, started);+ 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,+ );terminal = spawn(scenario.executable, [...scenario.arguments], {cwd: scenario.working_directory,- env: makeEnvironment({ scenario, home, replay, shimReplay, runId }),+ env: makeEnvironment({ ...options, replay, shimReplay }),cols: scenario.terminal.columns,rows: scenario.terminal.rows,name: "xterm-256color",});const startEvents = startScenarioEvents({- scenario,+ ...options,getTerminal: () => terminal,- timers,- interactions,renderer,started,- dispatchedEventIndexes,});if (!eventsRequireReadiness(scenario)) startEvents();- framesTruncated = captureTerminalFrames({+ const framesTruncated = captureTerminalFrames({+ ...options,terminal,- scenario,- frames,started,- temporaryRoot,onOutput: () => (lastOutput = Date.now()),onFirstOutput: startEvents,renderer,checkpoints,});- stopSampler = startProcessSampler(+ const stopSampler = startProcessSampler(terminal.pid,started,scenario.limits.processes,- samples,+ options.samples,);- const exit = await awaitTerminalExit({+ return {+ replay,+ renderer,+ checkpoints,+ shimReplay,terminal,- scenario,started,+ startedAt,lastOutput: () => lastOutput,- signal,- timers,- interactions,- dispatchedEventIndexes,- });- const exitReason = exit.reason;- checkpoints.trigger("root_exit");- if (exitReason === "cancelled")- throw new ProcessCaptureError("process capture was cancelled");- settlement = await observeSettlement(- runId,- [- terminal.pid,- ...samples.flatMap(({ process_group_id }) =>- process_group_id === null ? [] : [process_group_id],- ),- ],- scenario.settle_ms,- );- checkpoints.trigger("settled");- samplingPartial = (await stopSampler()).partial;- assertNotCancelled(signal);- const after = await snapshotRoots(scenario, signal);- const renderedFrames = await renderer.frames();- const filesystemCheckpoints = await checkpoints.finish(after);- const manifest = await createRunManifest(scenario, startedAt, new Date());- truncated ||=- after.truncated ||- replay.truncated ||- shimReplay.truncated ||- framesTruncated() ||- filesystemCheckpoints.some(({ truncated: partial }) => partial) ||- samplingPartial;- truncated ||= renderer.truncated();- capture = buildCaptureResult({- frames,- exit: { ...exit, reason: exitReason },- samples,+ framesTruncated,+ stopSampler,+ };+ } catch (cause: unknown) {+ return cleanupFailedStartup({+ cause,+ timers: options.timers,replay,- before,- after,- truncated,- scenario,- rootPid: terminal.pid,- samplingPartial,- renderedFrames,- interactions,- checkpoints: filesystemCheckpoints,- shimEvents: shimReplay.events.map((event) => ({- ...event,- arguments: event.arguments.map((argument) =>- normalizeProcessText(- argument,- scenario,- temporaryRoot,- terminal?.pid ?? -1,- ),- ),- working_directory: normalizeProcessText(- event.working_directory,- scenario,- temporaryRoot,- terminal?.pid ?? -1,- ),- })),- settlement: { ...settlement, cleanup_outcome: "not_required" },- manifest,+ terminal,+ renderer,+ shimReplay,+ checkpoints,+ runId: options.runId,+ temporaryRoot: options.temporaryRoot,});- } catch (cause: unknown) {- terminal?.kill("SIGKILL");- executionFailure = cause;}- samplingPartial ||= (await stopSampler()).partial;+};++const normalizedShimEvents = (+ runtime: StartedCaptureRuntime,+ scenario: ProcessScenario,+ temporaryRoot: string,+): ProcessCapture["shim_events"] =>+ 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 finishProcessRun = async (options: {+ readonly runtime: StartedCaptureRuntime | undefined;+ readonly timers: Set<NodeJS.Timeout>;+ readonly runId: string;+ readonly temporaryRoot: string;+ readonly samples: readonly ProcessSample[];+ readonly stopSampler: () => Promise<{ readonly partial: boolean }>;+ readonly capture: ProcessCapture | undefined;+ readonly executionFailure: unknown;+}): Promise<ProcessCapture> => {+ await options.stopSampler();const cleanupFailure = await releaseProcessResources({- timers,- replay,- terminal,- renderer,- shimReplay,- checkpoints,- runId,- temporaryRoot,- sampledProcessGroupIds: samples.flatMap(({ process_group_id }) =>+ timers: options.timers,+ replay: options.runtime?.replay,+ terminal: options.runtime?.terminal,+ renderer: options.runtime?.renderer,+ shimReplay: options.runtime?.shimReplay,+ checkpoints: options.runtime?.checkpoints,+ runId: options.runId,+ temporaryRoot: options.temporaryRoot,+ sampledProcessGroupIds: options.samples.flatMap(({ process_group_id }) =>process_group_id === null ? [] : [process_group_id],),});+ let { capture, executionFailure } = options;if (capture !== undefined) {capture = {...capture,@@ -793,15 +348,158 @@ const runProcessScenario = async (: "failed",},};- const issues = validateProcessCapture(capture);- if (issues.length > 0)+ const issue = validateProcessCapture(capture)[0];+ if (issue !== undefined)executionFailure = new ProcessCaptureError(- `process capture validation failed: ${issues[0]!.path}: ${issues[0]!.message}`,+ `process capture validation failed: ${issue.path}: ${issue.message}`,);}return resolveProcessResult(capture, executionFailure, cleanupFailure);};+const completeCapture = async (options: {+ readonly scenario: ProcessScenario;+ readonly runtime: StartedCaptureRuntime;+ readonly runId: string;+ readonly temporaryRoot: string;+ readonly before: Awaited<ReturnType<typeof snapshotRoots>>;+ readonly frames: readonly TerminalFrame[];+ readonly samples: readonly ProcessSample[];+ readonly interactions: readonly InteractionEvent[];+ readonly exit: Awaited<ReturnType<typeof awaitTerminalExit>>;+ readonly signal?: AbortSignal;+ readonly initiallyTruncated: boolean;+}): Promise<ProcessCapture> => {+ const { runtime, scenario } = options;+ runtime.checkpoints.trigger("root_exit");+ const { reason } = options.exit;+ if (reason === "cancelled")+ throw new ProcessCaptureError("process capture was cancelled");+ const settlement = await observeSettlement(+ options.runId,+ [+ runtime.terminal.pid,+ ...options.samples.flatMap(({ process_group_id }) =>+ process_group_id === null ? [] : [process_group_id],+ ),+ ],+ scenario.settle_ms,+ );+ 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);+ const manifest = await createRunManifest(+ scenario,+ runtime.startedAt,+ new Date(),+ );+ const truncated =+ options.initiallyTruncated ||+ after.truncated ||+ runtime.replay.truncated ||+ runtime.shimReplay.truncated ||+ runtime.framesTruncated() ||+ checkpoints.some(({ truncated: partial }) => partial) ||+ samplingPartial ||+ runtime.renderer.truncated();+ return buildCaptureResult({+ frames: options.frames,+ exit: { ...options.exit, reason },+ samples: options.samples,+ replay: runtime.replay,+ before: options.before,+ after,+ truncated,+ scenario,+ rootPid: runtime.terminal.pid,+ samplingPartial,+ renderedFrames,+ interactions: options.interactions,+ checkpoints,+ shimEvents: normalizedShimEvents(runtime, scenario, options.temporaryRoot),+ settlement: { ...settlement, cleanup_outcome: "not_required" },+ manifest,+ });+};++/** Execute one authorized scenario and return bounded observations. */+const runProcessScenario = async (+ scenario: ProcessScenario,+ policy: ProcessExecutionPolicy,+ signal?: AbortSignal,+): Promise<ProcessCapture> => {+ const { temporaryRoot, runId, home, before } = await prepareProcessCapture(+ scenario,+ policy,+ signal,+ );+ const frames: TerminalFrame[] = [];+ const samples: ProcessSample[] = [];+ let runtime: StartedCaptureRuntime | undefined;+ const timers = new Set<NodeJS.Timeout>();+ let capture: ProcessCapture | undefined;+ let executionFailure: unknown;+ let stopSampler = async () => ({ partial: false });+ const interactions: InteractionEvent[] = [];+ const dispatchedEventIndexes = new Set<number>();++ try {+ runtime = await startCaptureRuntime({+ scenario,+ home,+ temporaryRoot,+ runId,+ before,+ frames,+ samples,+ interactions,+ timers,+ dispatchedEventIndexes,+ ...(signal === undefined ? {} : { signal }),+ });+ stopSampler = runtime.stopSampler;+ const exit = await awaitTerminalExit({+ terminal: runtime.terminal,+ scenario,+ started: runtime.started,+ lastOutput: runtime.lastOutput,+ signal,+ timers,+ interactions,+ dispatchedEventIndexes,+ });+ capture = await completeCapture({+ scenario,+ runtime,+ runId,+ temporaryRoot,+ before,+ frames,+ samples,+ interactions,+ exit,+ initiallyTruncated: before.truncated,+ ...(signal === undefined ? {} : { signal }),+ });+ } catch (cause: unknown) {+ runtime?.terminal.kill("SIGKILL");+ executionFailure = cause;+ }+ return finishProcessRun({+ runtime,+ timers,+ runId,+ temporaryRoot,+ samples,+ stopSampler,+ capture,+ executionFailure,+ });+};+/** Execute one scenario through a typed expected-failure channel. */export const captureProcessScenario = async (scenario: ProcessScenario,diff --git a/src/domain/processCapture.ts b/src/domain/processCapture.tsindex eb0becbc9..03d451408 100644--- a/src/domain/processCapture.ts+++ b/src/domain/processCapture.ts@@ -1,448 +1,11 @@-import { createHash } from "node:crypto";-import { resolve } from "node:path";-import canonicalize from "canonicalize";import { z } from "zod";-const positiveBudget = z.number().int().positive();-const timedEventBase = { at_ms: z.number().int().nonnegative() };-const environmentName = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u);-const reservedEnvironment = new Set([- "HOME",- "TERM",- "REA_PROCESS_RUN_ID",- "REA_REPLAY_HTTP_URL",- "REA_REPLAY_WEBSOCKET_URL",- "REA_SHIM_LEDGER_URL",-]);-const normalizationSchema = z.object({- paths: z.boolean(),- pids: z.boolean(),- ports: z.boolean(),- time_bucket_ms: positiveBudget.max(60_000),- patterns: z.array(- z.object({- pattern: z.string().max(500),- replacement: z.string().max(100),- }),- ),-});-const checkpointNameSchema = z- .string()- .regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/u);-const commandNameSchema = z- .string()- .regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u);-const outputChunkSchema = z.object({- at_ms: z.number().int().nonnegative().max(300_000),- stream: z.enum(["stdout", "stderr"]),- data: z.string().max(1_000_000),-});--/** Actionable refusal shared by CLI, MCP, and Evidence import boundaries. */-export const LEGACY_PROCESS_CAPTURE_MESSAGE =- "Process Capture v3 is unsupported. Re-run the scenario with this REA version using capture_process_scenario to produce Process Capture v4; captures cannot be upgraded because v4 requires new manifest and settlement evidence.";--const canonicalSha256 = (value: unknown): string => {- const serialized = canonicalize(value);- if (serialized === undefined)- throw new TypeError("Process capture commitment is not canonical JSON");- return createHash("sha256").update(serialized).digest("hex");-};--/** Build the secret-safe scenario projection committed by Process Capture v4. */-export const processScenarioCommitment = (- scenario: ProcessScenario,- executableSha256?: string,-): Readonly<Record<string, unknown>> => ({- ...scenario,- environment: Object.fromEntries(- Object.entries(scenario.environment).map(([name, value]) => [- name,- scenario.secret_aliases.includes(name) ? "<redacted-secret>" : value,- ]),- ),- unknown_registry_approved: scenario.unknown_registry_approved === true,- executable_sha256: executableSha256 ?? null,-});--/** Project observation settings shared by authority and reconstruction. */-export const processComparisonContract = (- scenario: ProcessScenario,-): Readonly<Record<string, unknown>> => ({- working_directory: scenario.working_directory,- inherit_environment: scenario.inherit_environment,- secret_aliases: scenario.secret_aliases,- network_access: scenario.network_access,- filesystem_roots: scenario.filesystem_roots,- terminal: scenario.terminal,- checkpoints: scenario.checkpoints,- events: scenario.events,- timeout_ms: scenario.timeout_ms,- idle_timeout_ms: scenario.idle_timeout_ms,- settle_ms: scenario.settle_ms,- limits: scenario.limits,- normalization: scenario.normalization,- command_shims: scenario.command_shims,- replay: scenario.replay,-});--/** Compute a canonical SHA-256 commitment independent of object key order. */-export const digestProcessCommitment = canonicalSha256;--/**- * Boundary schema for one explicitly approved, bounded process experiment.- * Defaults are part of the evidence contract and must remain deterministic.- */-export const processScenarioSchema = z- .object({- approved: z- .literal(true)- .describe(- "Explicit per-call acknowledgement that this operation launches the target",- ),- unknown_registry_approved: z- .literal(true)- .optional()- .describe("Explicit approval to record capture residuals durably"),- executable: z.string().startsWith("/"),- arguments: z.array(z.string()).max(256).default([]),- working_directory: z.string().startsWith("/"),- environment: z.record(environmentName, z.string()).default({}),- inherit_environment: z.array(environmentName).max(64).default([]),- secret_aliases: z.array(environmentName).max(64).default([]),- network_access: z.literal("host").default("host"),- filesystem_roots: z.array(z.string().startsWith("/")).max(16).default([]),- terminal: z- .object({- columns: z.number().int().min(1).max(1_000).default(80),- rows: z.number().int().min(1).max(1_000).default(24),- scrollback: z.number().int().min(0).max(10_000).default(1_000),- })- .default({ columns: 80, rows: 24, scrollback: 1_000 }),- checkpoints: z- .array(- z.object({- name: checkpointNameSchema,- trigger: z.discriminatedUnion("type", [- z.object({- type: z.literal("time"),- at_ms: z.number().int().nonnegative().max(300_000),- }),- z.object({- type: z.literal("terminal_literal"),- value: z.string().min(1).max(10_000),- occurrence: z.number().int().positive().max(1_000).default(1),- }),- z.object({ type: z.literal("root_exit") }),- z.object({ type: z.literal("settled") }),- ]),- }),- )- .max(64)- .default([]),- command_shims: z- .array(- z.object({- name: commandNameSchema,- routes: z- .array(- z.object({- arguments: z.array(z.string()).max(256),- outputs: z.array(outputChunkSchema).max(1_000).default([]),- termination: z.discriminatedUnion("type", [- z.object({- type: z.literal("exit"),- code: z.number().int().min(0).max(255),- }),- z.object({- type: z.literal("signal"),- signal: z.enum(["SIGINT", "SIGTERM", "SIGKILL"]),- }),- ]),- max_calls: z.number().int().positive().max(100).default(1),- }),- )- .min(1)- .max(100),- }),- )- .max(32)- .default([]),- events: z- .array(- z.discriminatedUnion("type", [- z.object({- ...timedEventBase,- type: z.literal("input"),- data: z.string(),- sensitive: z.boolean().default(false),- }),- z.object({- ...timedEventBase,- type: z.literal("resize"),- columns: z.number().int().min(1).max(1_000),- rows: z.number().int().min(1).max(1_000),- }),- z.object({- ...timedEventBase,- type: z.literal("signal"),- signal: z.enum(["SIGINT", "SIGTERM", "SIGKILL"]),- }),- ]),- )- .max(1_000)- .default([]),- timeout_ms: positiveBudget.max(300_000).default(30_000),- idle_timeout_ms: positiveBudget.max(300_000).default(30_000),- settle_ms: z.number().int().nonnegative().max(10_000).default(100),- limits: z- .object({- output_bytes: positiveBudget.max(10_000_000).default(1_000_000),- frames: positiveBudget.max(100_000).default(10_000),- files: positiveBudget.max(100_000).default(10_000),- file_bytes: positiveBudget.max(100_000_000).default(10_000_000),- processes: positiveBudget.max(10_000).default(1_000),- protocol_events: positiveBudget.max(100_000).default(10_000),- protocol_body_bytes: positiveBudget.max(10_000_000).default(1_000_000),- connections: positiveBudget.max(1_000).default(100),- filesystem_depth: z.number().int().min(1).max(64).default(16),- })- .default({- output_bytes: 1_000_000,- frames: 10_000,- files: 10_000,- file_bytes: 10_000_000,- processes: 1_000,- protocol_events: 10_000,- protocol_body_bytes: 1_000_000,- connections: 100,- filesystem_depth: 16,- }),- normalization: z- .object({- paths: z.boolean().default(true),- pids: z.boolean().default(true),- ports: z.boolean().default(true),- time_bucket_ms: positiveBudget.max(60_000).default(10),- patterns: z- .array(- z.object({- pattern: z.string().max(500),- replacement: z.string().max(100),- }),- )- .max(32)- .default([]),- })- .default({- paths: true,- pids: true,- ports: true,- time_bucket_ms: 10,- patterns: [],- }),- replay: z- .object({- http: z- .array(- z.object({- method: z.string().max(16),- path: z.string().startsWith("/"),- status: z.number().int().min(100).max(599),- body: z.string().max(1_000_000),- request_headers: z.record(z.string(), z.string()).default({}),- request_body: z.string().max(1_000_000).optional(),- response_headers: z.record(z.string(), z.string()).default({}),- delay_ms: z.number().int().nonnegative().max(30_000).default(0),- disconnect: z.boolean().default(false),- max_calls: z.number().int().min(1).max(100).default(1),- }),- )- .max(100)- .default([]),- websocket_messages: z- .array(z.string().max(1_000_000))- .max(100)- .default([]),- websocket_connections: z- .array(- z.object({- messages: z- .array(- z.object({- data: z.string().max(1_000_000),- delay_ms: z- .number()- .int()- .nonnegative()- .max(30_000)- .default(0),- }),- )- .max(100),- disconnect_after: z.boolean().default(false),- }),- )- .max(100)- .default([]),- })- .default({- http: [],- websocket_messages: [],- websocket_connections: [],- }),- })- .strict()- .superRefine((scenario, context) => {- for (let index = 1; index < scenario.events.length; index += 1) {- if (scenario.events[index]!.at_ms < scenario.events[index - 1]!.at_ms) {- context.addIssue({- code: "custom",- message: "events must be ordered by at_ms",- path: ["events", index],- });- }- }- const secrets = new Set(scenario.secret_aliases);- for (const alias of secrets) {- if (!(alias in scenario.environment)) {- context.addIssue({- code: "custom",- message: "secret alias has no environment value",- path: ["secret_aliases"],- });- }- }- const explicit = new Set(Object.keys(scenario.environment));- for (const name of [...explicit, ...scenario.inherit_environment]) {- if (reservedEnvironment.has(name)) {- context.addIssue({- code: "custom",- message: `${name} is reserved by the process adapter`,- path: ["environment", name],- });- }- }- for (const name of scenario.inherit_environment) {- if (explicit.has(name)) {- context.addIssue({- code: "custom",- message: "an environment name cannot be explicit and inherited",- path: ["inherit_environment"],- });- }- }- for (const event of scenario.events) {- if (event.at_ms > scenario.timeout_ms) {- context.addIssue({- code: "custom",- message: "event occurs after the scenario timeout",- path: ["events"],- });- }- }- const checkpointNames = scenario.checkpoints.map(({ name }) => name);- for (const [index, name] of checkpointNames.entries()) {- if (name === "before" || name === "after_settlement")- context.addIssue({- code: "custom",- message: "checkpoint name is reserved by the capture lifecycle",- path: ["checkpoints", index, "name"],- });- }- if (new Set(checkpointNames).size !== checkpointNames.length)- context.addIssue({- code: "custom",- message: "checkpoint names must be unique",- path: ["checkpoints"],- });- const shimNames = scenario.command_shims.map(({ name }) => name);- if (new Set(shimNames).size !== shimNames.length)- context.addIssue({- code: "custom",- message: "command shim names must be unique",- path: ["command_shims"],- });- });--/** Parsed instructions and resource bounds for one process experiment. */-export type ProcessScenario = z.infer<typeof processScenarioSchema>;+import {+ LEGACY_PROCESS_CAPTURE_MESSAGE,+ normalizationSchema,+} from "./processScenario.js";-/** Parse untrusted process scenario input and apply safe default budgets. */-export const parseProcessScenario = (input: unknown): ProcessScenario =>- processScenarioSchema.parse(input);--/** Operator-owned ceiling applied in addition to per-scenario approval. */-export interface ProcessExecutionPolicy {- readonly enabled: boolean;- readonly executableRoots: readonly string[];- readonly workingRoots: readonly string[];- readonly allowedEnvironment: readonly string[];- readonly allowExternalNetwork: boolean;-}--/** Explicit authorization result; denial reasons are safe to show callers. */-export type ProcessPolicyDecision =- | { readonly allowed: true }- | { readonly allowed: false; readonly reason: string };--const isWithin = (candidate: string, root: string): boolean =>- resolve(candidate) === resolve(root) ||- resolve(candidate).startsWith(- `${resolve(root)}${resolve(root).endsWith("/") ? "" : "/"}`,- );--/** Evaluate scenario authority before any process or filesystem side effect occurs. */-export const authorizeProcessScenario = (- scenario: ProcessScenario,- policy: ProcessExecutionPolicy,-): ProcessPolicyDecision => {- if (!policy.enabled)- return { allowed: false, reason: "process capture is disabled" };- if (scenario.network_access === "host" && !policy.allowExternalNetwork)- return {- allowed: false,- reason: "host network access is not approved by operator policy",- };- if (- !policy.executableRoots.some((root) => isWithin(scenario.executable, root))- ) {- return { allowed: false, reason: "executable is outside approved roots" };- }- if (- !policy.workingRoots.some((root) =>- isWithin(scenario.working_directory, root),- )- ) {- return {- allowed: false,- reason: "working directory is outside approved roots",- };- }- const requestedNames = [- ...Object.keys(scenario.environment),- ...scenario.inherit_environment,- ];- if (- requestedNames.some((name) => !policy.allowedEnvironment.includes(name))- ) {- return {- allowed: false,- reason: "scenario requests an environment variable not allowed by policy",- };- }- if (- scenario.filesystem_roots.some(- (path) => !policy.workingRoots.some((root) => isWithin(path, root)),- )- ) {- return {- allowed: false,- reason: "filesystem root is outside approved roots",- };- }- return { allowed: true };-};+export * from "./processScenario.js";/** Normalized raw PTY chunk, preserving transport-level output differences. */export interface TerminalFrame {@@ -761,154 +324,9 @@ export const processCaptureSchema: z.ZodType<ProcessCapture> = z.object({}),});-/** One pure semantic validation failure in an otherwise shaped v4 capture. */-export interface ProcessCaptureValidationIssue {- readonly path: string;- readonly message: string;-}--const orderedBy = <Value>(- values: readonly Value[],- project: (value: Value) => number,-): boolean =>- values.every(- (value, index) =>- index === 0 || project(value) >= project(values[index - 1]!),- );--const orderedTimestamps = (- values: readonly { readonly at_ms: number }[],-): boolean => orderedBy(values, ({ at_ms }) => at_ms);--/** Recompute v4 commitments and cross-field invariants without side effects. */-export const validateProcessCapture = (- capture: ProcessCapture,-): readonly ProcessCaptureValidationIssue[] => {- const issues: ProcessCaptureValidationIssue[] = [];- const require = (condition: boolean, path: string, message: string): void => {- if (!condition) issues.push({ path, message });- };- const { manifest } = capture;- require(manifest.scenario.executable_sha256 ===- manifest.executable_sha256, "manifest.executable_sha256", "executable commitment does not match the scenario projection");- const commitments = [- ["full_scenario_sha256", manifest.scenario],- ["comparison_contract_sha256", manifest.comparison_contract],- ["normalization_sha256", capture.normalization],- ["shim_plan_sha256", manifest.shim_plan],- ["replay_plan_sha256", manifest.replay_plan],- ] as const;- for (const [field, value] of commitments)- require(manifest[field] ===- canonicalSha256(- value,- ), `manifest.${field}`, "commitment does not match its canonical value");- require(Date.parse(manifest.started_at) <=- Date.parse(- manifest.completed_at,- ), "manifest.completed_at", "completion precedes start");- const sequences = [- ["frames", capture.frames],- ["rendered_frames", capture.rendered_frames],- ["interaction_events", capture.interaction_events],- ["shim_events", capture.shim_events],- ["protocol_events", capture.protocol_events],- ] as const;- for (const [name, values] of sequences) {- require(values.every(- ({ sequence }, index) => sequence === index,- ), name, "sequence values must be contiguous from zero");- }- for (const [name, values] of [- ["frames", capture.frames],- ["rendered_frames", capture.rendered_frames],- ["process_samples", capture.process_samples],- ["filesystem_checkpoints", capture.filesystem_checkpoints],- ["shim_events", capture.shim_events],- ["protocol_events", capture.protocol_events],- ] as const)- require(orderedTimestamps(values), name, "timestamps must be ordered");- const checkpointNames = capture.filesystem_checkpoints.map(- ({ name }) => name,- );- require(new Set(checkpointNames).size ===- checkpointNames.length, "filesystem_checkpoints", "checkpoint names must be unique");- require(checkpointNames[0] ===- "before", "filesystem_checkpoints", "first checkpoint must be before");- require(checkpointNames.at(-1) ===- "after_settlement", "filesystem_checkpoints", "last checkpoint must be after_settlement");- require(!capture.filesystem_checkpoints.some(({ truncated }) => truncated) ||- capture.truncated, "truncated", "checkpoint truncation must propagate to the capture");- require(capture.exit.reason === "exited" ||- capture.exit.code ===- null, "exit", "deadline termination cannot declare a normal exit code");- require(capture.settlement.state !== "quiesced" ||- capture.settlement.cleanup_outcome ===- "not_required", "settlement.cleanup_outcome", "quiesced settlement cannot require cleanup");- require(capture.settlement.state === "quiesced" ||- capture.settlement.cleanup_outcome !==- "not_required", "settlement.cleanup_outcome", "non-quiesced settlement must report cleanup");- const shimPlans = manifest.shim_plan.flatMap((shim) =>- typeof shim === "object" &&- shim !== null &&- "name" in shim &&- "routes" in shim &&- typeof shim.name === "string" &&- Array.isArray(shim.routes)- ? shim.routes.map((route, routeIndex) => ({- command: shim.name as string,- route,- routeIndex,- }))- : [],- );- for (const event of capture.shim_events) {- const declaredRoute = shimPlans.find(- ({ command, routeIndex }) =>- command === event.command && routeIndex === event.route_index,- );- require(event.outcome === "unmatched"- ? event.route_index === null- : declaredRoute !==- undefined, "shim_events", "shim event has no declared route");- }- for (const plan of shimPlans) {- const maximum =- typeof plan.route === "object" &&- plan.route !== null &&- "max_calls" in plan.route &&- typeof plan.route.max_calls === "number"- ? plan.route.max_calls- : 0;- require(capture.shim_events.filter(- (event) =>- event.command === plan.command &&- event.route_index === plan.routeIndex &&- event.outcome === "matched",- ).length <=- maximum, "shim_events", "matched shim events exceed the declared route max_calls");- }- const replayHttp =- "http" in manifest.replay_plan && Array.isArray(manifest.replay_plan.http)- ? manifest.replay_plan.http- : [];- for (const event of capture.protocol_events)- if (- event.protocol === "http" &&- event.direction === "request" &&- event.outcome === "matched"- )- require(replayHttp.some(- (route) =>- typeof route === "object" &&- route !== null &&- "method" in route &&- route.method === event.method &&- "path" in route &&- route.path === event.path,- ), "protocol_events", "matched HTTP event has no declared replay route");- return issues;-};+export { validateProcessCapture } from "./processCaptureValidation.js";+export type { ProcessCaptureValidationIssue } from "./processCaptureValidation.js";+import { validateProcessCapture } from "./processCaptureValidation.js";/** Parse unknown input as v4 and reject invalid commitments or semantics. */export const parseProcessCapture = (input: unknown): ProcessCapture => {diff --git a/src/domain/processCaptureValidation.ts b/src/domain/processCaptureValidation.tsnew file mode 100644index 000000000..571617746--- /dev/null+++ b/src/domain/processCaptureValidation.ts@@ -0,0 +1,190 @@+import type { ProcessCapture } from "./processCapture.js";+import { canonicalProcessSha256 } from "./processScenario.js";++/** One pure semantic validation failure in an otherwise shaped v4 capture. */+export interface ProcessCaptureValidationIssue {+ readonly path: string;+ readonly message: string;+}++type RequireInvariant = (+ condition: boolean,+ path: string,+ message: string,+) => void;++const orderedTimestamps = (+ values: readonly { readonly at_ms: number }[],+): boolean =>+ values.every(+ (value, index) => index === 0 || value.at_ms >= values[index - 1]!.at_ms,+ );++const validateCommitments = (+ capture: ProcessCapture,+ require: RequireInvariant,+): void => {+ const { manifest } = capture;+ require(manifest.scenario.executable_sha256 ===+ manifest.executable_sha256, "manifest.executable_sha256", "executable commitment does not match the scenario projection");+ for (const [field, value] of [+ ["full_scenario_sha256", manifest.scenario],+ ["comparison_contract_sha256", manifest.comparison_contract],+ ["normalization_sha256", capture.normalization],+ ["shim_plan_sha256", manifest.shim_plan],+ ["replay_plan_sha256", manifest.replay_plan],+ ] as const)+ require(manifest[field] ===+ canonicalProcessSha256(+ value,+ ), `manifest.${field}`, "commitment does not match its canonical value");+ require(Date.parse(manifest.started_at) <=+ Date.parse(+ manifest.completed_at,+ ), "manifest.completed_at", "completion precedes start");+};++const validateOrdering = (+ capture: ProcessCapture,+ require: RequireInvariant,+): void => {+ for (const [name, values] of [+ ["frames", capture.frames],+ ["rendered_frames", capture.rendered_frames],+ ["interaction_events", capture.interaction_events],+ ["shim_events", capture.shim_events],+ ["protocol_events", capture.protocol_events],+ ] as const)+ require(values.every(+ ({ sequence }, index) => sequence === index,+ ), name, "sequence values must be contiguous from zero");+ for (const [name, values] of [+ ["frames", capture.frames],+ ["rendered_frames", capture.rendered_frames],+ ["process_samples", capture.process_samples],+ ["filesystem_checkpoints", capture.filesystem_checkpoints],+ ["shim_events", capture.shim_events],+ ["protocol_events", capture.protocol_events],+ ] as const)+ require(orderedTimestamps(values), name, "timestamps must be ordered");+};++const validateLifecycle = (+ capture: ProcessCapture,+ require: RequireInvariant,+): void => {+ const checkpointNames = capture.filesystem_checkpoints.map(+ ({ name }) => name,+ );+ require(new Set(checkpointNames).size ===+ checkpointNames.length, "filesystem_checkpoints", "checkpoint names must be unique");+ require(checkpointNames[0] ===+ "before", "filesystem_checkpoints", "first checkpoint must be before");+ require(checkpointNames.at(-1) ===+ "after_settlement", "filesystem_checkpoints", "last checkpoint must be after_settlement");+ require(!capture.filesystem_checkpoints.some(({ truncated }) => truncated) ||+ capture.truncated, "truncated", "checkpoint truncation must propagate to the capture");+ require(capture.exit.reason === "exited" ||+ capture.exit.code ===+ null, "exit", "deadline termination cannot declare a normal exit code");+ require(capture.settlement.state !== "quiesced" ||+ capture.settlement.cleanup_outcome ===+ "not_required", "settlement.cleanup_outcome", "quiesced settlement cannot require cleanup");+ require(capture.settlement.state === "quiesced" ||+ capture.settlement.cleanup_outcome !==+ "not_required", "settlement.cleanup_outcome", "non-quiesced settlement must report cleanup");+};++const shimPlans = (capture: ProcessCapture) =>+ capture.manifest.shim_plan.flatMap((shim) =>+ typeof shim === "object" &&+ shim !== null &&+ "name" in shim &&+ "routes" in shim &&+ typeof shim.name === "string" &&+ Array.isArray(shim.routes)+ ? shim.routes.map((route, routeIndex) => ({+ command: shim.name as string,+ route,+ routeIndex,+ }))+ : [],+ );++const validateShimEvents = (+ capture: ProcessCapture,+ require: RequireInvariant,+): void => {+ const plans = shimPlans(capture);+ for (const event of capture.shim_events) {+ const declared = plans.some(+ ({ command, routeIndex }) =>+ command === event.command && routeIndex === event.route_index,+ );+ require(event.outcome === "unmatched"+ ? event.route_index === null+ : declared, "shim_events", "shim event has no declared route");+ }+ for (const plan of plans) {+ const maximum =+ typeof plan.route === "object" &&+ plan.route !== null &&+ "max_calls" in plan.route &&+ typeof plan.route.max_calls === "number"+ ? plan.route.max_calls+ : 0;+ const matches = capture.shim_events.filter(+ (event) =>+ event.command === plan.command &&+ event.route_index === plan.routeIndex &&+ event.outcome === "matched",+ ).length;+ require(matches <=+ maximum, "shim_events", "matched shim events exceed the declared route max_calls");+ }+};++const validateReplayEvents = (+ capture: ProcessCapture,+ require: RequireInvariant,+): void => {+ const { replay_plan: replayPlan } = capture.manifest;+ const routes =+ "http" in replayPlan && Array.isArray(replayPlan.http)+ ? replayPlan.http+ : [];+ 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");+ }+};++/** Recompute v4 commitments and cross-field invariants without side effects. */+export const validateProcessCapture = (+ capture: ProcessCapture,+): readonly ProcessCaptureValidationIssue[] => {+ const issues: ProcessCaptureValidationIssue[] = [];+ const require: RequireInvariant = (condition, path, message) => {+ if (!condition) issues.push({ path, message });+ };+ validateCommitments(capture, require);+ validateOrdering(capture, require);+ validateLifecycle(capture, require);+ validateShimEvents(capture, require);+ validateReplayEvents(capture, require);+ return issues;+};diff --git a/src/domain/processComparison.ts b/src/domain/processComparison.tsindex 9f25e11a9..0c9b3e105 100644--- a/src/domain/processComparison.ts+++ b/src/domain/processComparison.ts@@ -197,21 +197,11 @@ const chooseFirstDivergence = ();};-/** Compare bounded captures without equating missing or incompatible evidence. */-/**- * Compare two Process Capture v4 observations without treating absence as proof.- *- * Observed differences outrank residual unknowns. A capture may therefore be- * definitively changed in one dimension while completeness remains unknown.- */-export const compareProcessCaptures = (+const assertComparable = (left: ProcessCapture,right: ProcessCapture,- options: {- readonly maxCaptureAgeMs?: number;- readonly now?: () => number;- } = {},-): ProcessCaptureComparison => {+ options: { readonly maxCaptureAgeMs?: number; readonly now?: () => number },+): void => {const invalid = [...validateProcessCapture(left),...validateProcessCapture(right),@@ -226,36 +216,50 @@ export const compareProcessCaptures = (throw new TypeError("Process captures have incompatible comparison contracts",);- if (options.maxCaptureAgeMs !== undefined) {- const maxCaptureAgeMs = options.maxCaptureAgeMs;- const now = (options.now ?? Date.now)();- if (- [left, right].some(- ({ manifest }) =>- now - Date.parse(manifest.completed_at) > maxCaptureAgeMs,- )+ if (options.maxCaptureAgeMs === undefined) return;+ const maxCaptureAgeMs = options.maxCaptureAgeMs;+ const now = (options.now ?? Date.now)();+ if (+ [left, right].some(+ ({ manifest }) =>+ now - Date.parse(manifest.completed_at) > maxCaptureAgeMs,)- throw new TypeError("Process capture exceeds max_capture_age_ms");- }- if (left.truncated || right.truncated) {- return {- status: "truncated",- terminal: "truncated",- interaction: "truncated",- exit: "truncated",- filesystem: "truncated",- protocol: "truncated",- process: "truncated",- shim: "truncated",- first_divergence: {- status: "unknown",- reason: "At least one capture is truncated.",- },- limitations: ["At least one capture is truncated."],- };- }- const sameNormalization =- JSON.stringify(left.normalization) === JSON.stringify(right.normalization);+ )+ throw new TypeError("Process capture exceeds max_capture_age_ms");+};++const truncatedComparison = (): ProcessCaptureComparison => ({+ status: "truncated",+ terminal: "truncated",+ interaction: "truncated",+ exit: "truncated",+ filesystem: "truncated",+ protocol: "truncated",+ process: "truncated",+ shim: "truncated",+ first_divergence: {+ status: "unknown",+ reason: "At least one capture is truncated.",+ },+ limitations: ["At least one capture is truncated."],+});++type ComparisonDimensions = Pick<+ ProcessCaptureComparison,+ | "terminal"+ | "interaction"+ | "exit"+ | "filesystem"+ | "protocol"+ | "process"+ | "shim"+>;++const compareDimensions = (+ left: ProcessCapture,+ right: ProcessCapture,+ sameNormalization: boolean,+): ComparisonDimensions => {const classify = (scope: ProcessCapture["residual_unknowns"][number]["scope"],leftValues: readonly unknown[],@@ -264,41 +268,57 @@ export const compareProcessCaptures = (!sameNormalization || hasUnknown(left, scope) || hasUnknown(right, scope)? "unknown": classifyCollection(leftValues, rightValues);- const terminal = classify(- "terminal",- terminalObservations(left),- terminalObservations(right),- );- const interaction = classify(- "terminal",- left.interaction_events,- right.interaction_events,- );- const exit =- hasUnknown(left, "exit") || hasUnknown(right, "exit")- ? "unknown"- : JSON.stringify({ exit: left.exit, settlement: left.settlement }) ===- JSON.stringify({ exit: right.exit, settlement: right.settlement })- ? "unchanged"- : "changed";- const filesystem = classify(- "filesystem",- filesystemObservations(left),- filesystemObservations(right),- );- const protocol = classify(- "protocol",- left.protocol_events,- right.protocol_events,- );- const process = classify(- "process",- left.process_samples,- right.process_samples,- );- const shim = sameNormalization- ? classifyCollection(left.shim_events, right.shim_events)- : "unknown";+ return {+ terminal: classify(+ "terminal",+ terminalObservations(left),+ terminalObservations(right),+ ),+ interaction: classify(+ "terminal",+ left.interaction_events,+ right.interaction_events,+ ),+ exit:+ hasUnknown(left, "exit") || hasUnknown(right, "exit")+ ? "unknown"+ : JSON.stringify({ exit: left.exit, settlement: left.settlement }) ===+ JSON.stringify({ exit: right.exit, settlement: right.settlement })+ ? "unchanged"+ : "changed",+ filesystem: classify(+ "filesystem",+ filesystemObservations(left),+ filesystemObservations(right),+ ),+ protocol: classify("protocol", left.protocol_events, right.protocol_events),+ process: classify("process", left.process_samples, right.process_samples),+ shim: sameNormalization+ ? classifyCollection(left.shim_events, right.shim_events)+ : "unknown",+ };+};++/** Compare bounded captures without equating missing or incompatible evidence. */+/**+ * Compare two Process Capture v4 observations without treating absence as proof.+ *+ * Observed differences outrank residual unknowns. A capture may therefore be+ * definitively changed in one dimension while completeness remains unknown.+ */+export const compareProcessCaptures = (+ left: ProcessCapture,+ right: ProcessCapture,+ options: {+ readonly maxCaptureAgeMs?: number;+ readonly now?: () => number;+ } = {},+): ProcessCaptureComparison => {+ assertComparable(left, right, options);+ if (left.truncated || right.truncated) return truncatedComparison();+ const sameNormalization =+ JSON.stringify(left.normalization) === JSON.stringify(right.normalization);+ const dimensions = compareDimensions(left, right, sameNormalization);const observedFirstDivergence = chooseFirstDivergence([firstCollectionDivergence("terminal",@@ -346,21 +366,15 @@ export const compareProcessCaptures = (: observedFirstDivergence;return {status: comparisonStatus([- terminal,- interaction,- exit,- filesystem,- protocol,- process,- shim,+ dimensions.terminal,+ dimensions.interaction,+ dimensions.exit,+ dimensions.filesystem,+ dimensions.protocol,+ dimensions.process,+ dimensions.shim,]),- terminal,- interaction,- exit,- filesystem,- protocol,- process,- shim,+ ...dimensions,first_divergence: firstDivergence,limitations: [...left.limitations,diff --git a/src/domain/processScenario.ts b/src/domain/processScenario.tsnew file mode 100644index 000000000..5d7d5cea1--- /dev/null+++ b/src/domain/processScenario.ts@@ -0,0 +1,445 @@+import { createHash } from "node:crypto";+import { resolve } from "node:path";+import canonicalize from "canonicalize";+import { z } from "zod";++const positiveBudget = z.number().int().positive();+const timedEventBase = { at_ms: z.number().int().nonnegative() };+const environmentName = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u);+const reservedEnvironment = new Set([+ "HOME",+ "TERM",+ "REA_PROCESS_RUN_ID",+ "REA_REPLAY_HTTP_URL",+ "REA_REPLAY_WEBSOCKET_URL",+ "REA_SHIM_LEDGER_URL",+]);+export const normalizationSchema = z.object({+ paths: z.boolean(),+ pids: z.boolean(),+ ports: z.boolean(),+ time_bucket_ms: positiveBudget.max(60_000),+ patterns: z.array(+ z.object({+ pattern: z.string().max(500),+ replacement: z.string().max(100),+ }),+ ),+});+const checkpointNameSchema = z+ .string()+ .regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/u);+const commandNameSchema = z+ .string()+ .regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u);+const outputChunkSchema = z.object({+ at_ms: z.number().int().nonnegative().max(300_000),+ stream: z.enum(["stdout", "stderr"]),+ data: z.string().max(1_000_000),+});++/** Actionable refusal shared by CLI, MCP, and Evidence import boundaries. */+export const LEGACY_PROCESS_CAPTURE_MESSAGE =+ "Process Capture v3 is unsupported. Re-run the scenario with this REA version using capture_process_scenario to produce Process Capture v4; captures cannot be upgraded because v4 requires new manifest and settlement evidence.";++export const canonicalProcessSha256 = (value: unknown): string => {+ const serialized = canonicalize(value);+ if (serialized === undefined)+ throw new TypeError("Process capture commitment is not canonical JSON");+ return createHash("sha256").update(serialized).digest("hex");+};++/** Build the secret-safe scenario projection committed by Process Capture v4. */+export const processScenarioCommitment = (+ scenario: ProcessScenario,+ executableSha256?: string,+): Readonly<Record<string, unknown>> => ({+ ...scenario,+ environment: Object.fromEntries(+ Object.entries(scenario.environment).map(([name, value]) => [+ name,+ scenario.secret_aliases.includes(name) ? "<redacted-secret>" : value,+ ]),+ ),+ unknown_registry_approved: scenario.unknown_registry_approved === true,+ executable_sha256: executableSha256 ?? null,+});++/** Project observation settings shared by authority and reconstruction. */+export const processComparisonContract = (+ scenario: ProcessScenario,+): Readonly<Record<string, unknown>> => ({+ working_directory: scenario.working_directory,+ inherit_environment: scenario.inherit_environment,+ secret_aliases: scenario.secret_aliases,+ network_access: scenario.network_access,+ filesystem_roots: scenario.filesystem_roots,+ terminal: scenario.terminal,+ checkpoints: scenario.checkpoints,+ events: scenario.events,+ timeout_ms: scenario.timeout_ms,+ idle_timeout_ms: scenario.idle_timeout_ms,+ settle_ms: scenario.settle_ms,+ limits: scenario.limits,+ normalization: scenario.normalization,+ command_shims: scenario.command_shims,+ replay: scenario.replay,+});++/** Compute a canonical SHA-256 commitment independent of object key order. */+export const digestProcessCommitment = canonicalProcessSha256;++/**+ * Boundary schema for one explicitly approved, bounded process experiment.+ * Defaults are part of the evidence contract and must remain deterministic.+ */+export const processScenarioSchema = z+ .object({+ approved: z+ .literal(true)+ .describe(+ "Explicit per-call acknowledgement that this operation launches the target",+ ),+ unknown_registry_approved: z+ .literal(true)+ .optional()+ .describe("Explicit approval to record capture residuals durably"),+ executable: z.string().startsWith("/"),+ arguments: z.array(z.string()).max(256).default([]),+ working_directory: z.string().startsWith("/"),+ environment: z.record(environmentName, z.string()).default({}),+ inherit_environment: z.array(environmentName).max(64).default([]),+ secret_aliases: z.array(environmentName).max(64).default([]),+ network_access: z.literal("host").default("host"),+ filesystem_roots: z.array(z.string().startsWith("/")).max(16).default([]),+ terminal: z+ .object({+ columns: z.number().int().min(1).max(1_000).default(80),+ rows: z.number().int().min(1).max(1_000).default(24),+ scrollback: z.number().int().min(0).max(10_000).default(1_000),+ })+ .default({ columns: 80, rows: 24, scrollback: 1_000 }),+ checkpoints: z+ .array(+ z.object({+ name: checkpointNameSchema,+ trigger: z.discriminatedUnion("type", [+ z.object({+ type: z.literal("time"),+ at_ms: z.number().int().nonnegative().max(300_000),+ }),+ z.object({+ type: z.literal("terminal_literal"),+ value: z.string().min(1).max(10_000),+ occurrence: z.number().int().positive().max(1_000).default(1),+ }),+ z.object({ type: z.literal("root_exit") }),+ z.object({ type: z.literal("settled") }),+ ]),+ }),+ )+ .max(64)+ .default([]),+ command_shims: z+ .array(+ z.object({+ name: commandNameSchema,+ routes: z+ .array(+ z.object({+ arguments: z.array(z.string()).max(256),+ outputs: z.array(outputChunkSchema).max(1_000).default([]),+ termination: z.discriminatedUnion("type", [+ z.object({+ type: z.literal("exit"),+ code: z.number().int().min(0).max(255),+ }),+ z.object({+ type: z.literal("signal"),+ signal: z.enum(["SIGINT", "SIGTERM", "SIGKILL"]),+ }),+ ]),+ max_calls: z.number().int().positive().max(100).default(1),+ }),+ )+ .min(1)+ .max(100),+ }),+ )+ .max(32)+ .default([]),+ events: z+ .array(+ z.discriminatedUnion("type", [+ z.object({+ ...timedEventBase,+ type: z.literal("input"),+ data: z.string(),+ sensitive: z.boolean().default(false),+ }),+ z.object({+ ...timedEventBase,+ type: z.literal("resize"),+ columns: z.number().int().min(1).max(1_000),+ rows: z.number().int().min(1).max(1_000),+ }),+ z.object({+ ...timedEventBase,+ type: z.literal("signal"),+ signal: z.enum(["SIGINT", "SIGTERM", "SIGKILL"]),+ }),+ ]),+ )+ .max(1_000)+ .default([]),+ timeout_ms: positiveBudget.max(300_000).default(30_000),+ idle_timeout_ms: positiveBudget.max(300_000).default(30_000),+ settle_ms: z.number().int().nonnegative().max(10_000).default(100),+ limits: z+ .object({+ output_bytes: positiveBudget.max(10_000_000).default(1_000_000),+ frames: positiveBudget.max(100_000).default(10_000),+ files: positiveBudget.max(100_000).default(10_000),+ file_bytes: positiveBudget.max(100_000_000).default(10_000_000),+ processes: positiveBudget.max(10_000).default(1_000),+ protocol_events: positiveBudget.max(100_000).default(10_000),+ protocol_body_bytes: positiveBudget.max(10_000_000).default(1_000_000),+ connections: positiveBudget.max(1_000).default(100),+ filesystem_depth: z.number().int().min(1).max(64).default(16),+ })+ .default({+ output_bytes: 1_000_000,+ frames: 10_000,+ files: 10_000,+ file_bytes: 10_000_000,+ processes: 1_000,+ protocol_events: 10_000,+ protocol_body_bytes: 1_000_000,+ connections: 100,+ filesystem_depth: 16,+ }),+ normalization: z+ .object({+ paths: z.boolean().default(true),+ pids: z.boolean().default(true),+ ports: z.boolean().default(true),+ time_bucket_ms: positiveBudget.max(60_000).default(10),+ patterns: z+ .array(+ z.object({+ pattern: z.string().max(500),+ replacement: z.string().max(100),+ }),+ )+ .max(32)+ .default([]),+ })+ .default({+ paths: true,+ pids: true,+ ports: true,+ time_bucket_ms: 10,+ patterns: [],+ }),+ replay: z+ .object({+ http: z+ .array(+ z.object({+ method: z.string().max(16),+ path: z.string().startsWith("/"),+ status: z.number().int().min(100).max(599),+ body: z.string().max(1_000_000),+ request_headers: z.record(z.string(), z.string()).default({}),+ request_body: z.string().max(1_000_000).optional(),+ response_headers: z.record(z.string(), z.string()).default({}),+ delay_ms: z.number().int().nonnegative().max(30_000).default(0),+ disconnect: z.boolean().default(false),+ max_calls: z.number().int().min(1).max(100).default(1),+ }),+ )+ .max(100)+ .default([]),+ websocket_messages: z+ .array(z.string().max(1_000_000))+ .max(100)+ .default([]),+ websocket_connections: z+ .array(+ z.object({+ messages: z+ .array(+ z.object({+ data: z.string().max(1_000_000),+ delay_ms: z+ .number()+ .int()+ .nonnegative()+ .max(30_000)+ .default(0),+ }),+ )+ .max(100),+ disconnect_after: z.boolean().default(false),+ }),+ )+ .max(100)+ .default([]),+ })+ .default({+ http: [],+ websocket_messages: [],+ websocket_connections: [],+ }),+ })+ .strict()+ .superRefine((scenario, context) => {+ for (let index = 1; index < scenario.events.length; index += 1) {+ if (scenario.events[index]!.at_ms < scenario.events[index - 1]!.at_ms) {+ context.addIssue({+ code: "custom",+ message: "events must be ordered by at_ms",+ path: ["events", index],+ });+ }+ }+ const secrets = new Set(scenario.secret_aliases);+ for (const alias of secrets) {+ if (!(alias in scenario.environment)) {+ context.addIssue({+ code: "custom",+ message: "secret alias has no environment value",+ path: ["secret_aliases"],+ });+ }+ }+ const explicit = new Set(Object.keys(scenario.environment));+ for (const name of [...explicit, ...scenario.inherit_environment]) {+ if (reservedEnvironment.has(name)) {+ context.addIssue({+ code: "custom",+ message: `${name} is reserved by the process adapter`,+ path: ["environment", name],+ });+ }+ }+ for (const name of scenario.inherit_environment) {+ if (explicit.has(name)) {+ context.addIssue({+ code: "custom",+ message: "an environment name cannot be explicit and inherited",+ path: ["inherit_environment"],+ });+ }+ }+ for (const event of scenario.events) {+ if (event.at_ms > scenario.timeout_ms) {+ context.addIssue({+ code: "custom",+ message: "event occurs after the scenario timeout",+ path: ["events"],+ });+ }+ }+ const checkpointNames = scenario.checkpoints.map(({ name }) => name);+ for (const [index, name] of checkpointNames.entries()) {+ if (name === "before" || name === "after_settlement")+ context.addIssue({+ code: "custom",+ message: "checkpoint name is reserved by the capture lifecycle",+ path: ["checkpoints", index, "name"],+ });+ }+ if (new Set(checkpointNames).size !== checkpointNames.length)+ context.addIssue({+ code: "custom",+ message: "checkpoint names must be unique",+ path: ["checkpoints"],+ });+ const shimNames = scenario.command_shims.map(({ name }) => name);+ if (new Set(shimNames).size !== shimNames.length)+ context.addIssue({+ code: "custom",+ message: "command shim names must be unique",+ path: ["command_shims"],+ });+ });++/** Parsed instructions and resource bounds for one process experiment. */+export type ProcessScenario = z.infer<typeof processScenarioSchema>;++/** Parse untrusted process scenario input and apply safe default budgets. */+export const parseProcessScenario = (input: unknown): ProcessScenario =>+ processScenarioSchema.parse(input);++/** Operator-owned ceiling applied in addition to per-scenario approval. */+export interface ProcessExecutionPolicy {+ readonly enabled: boolean;+ readonly executableRoots: readonly string[];+ readonly workingRoots: readonly string[];+ readonly allowedEnvironment: readonly string[];+ readonly allowExternalNetwork: boolean;+}++/** Explicit authorization result; denial reasons are safe to show callers. */+export type ProcessPolicyDecision =+ | { readonly allowed: true }+ | { readonly allowed: false; readonly reason: string };++const isWithin = (candidate: string, root: string): boolean =>+ resolve(candidate) === resolve(root) ||+ resolve(candidate).startsWith(+ `${resolve(root)}${resolve(root).endsWith("/") ? "" : "/"}`,+ );++/** Evaluate scenario authority before any process or filesystem side effect occurs. */+export const authorizeProcessScenario = (+ scenario: ProcessScenario,+ policy: ProcessExecutionPolicy,+): ProcessPolicyDecision => {+ if (!policy.enabled)+ return { allowed: false, reason: "process capture is disabled" };+ if (scenario.network_access === "host" && !policy.allowExternalNetwork)+ return {+ allowed: false,+ reason: "host network access is not approved by operator policy",+ };+ if (+ !policy.executableRoots.some((root) => isWithin(scenario.executable, root))+ ) {+ return { allowed: false, reason: "executable is outside approved roots" };+ }+ if (+ !policy.workingRoots.some((root) =>+ isWithin(scenario.working_directory, root),+ )+ ) {+ return {+ allowed: false,+ reason: "working directory is outside approved roots",+ };+ }+ const requestedNames = [+ ...Object.keys(scenario.environment),+ ...scenario.inherit_environment,+ ];+ if (+ requestedNames.some((name) => !policy.allowedEnvironment.includes(name))+ ) {+ return {+ allowed: false,+ reason: "scenario requests an environment variable not allowed by policy",+ };+ }+ if (+ scenario.filesystem_roots.some(+ (path) => !policy.workingRoots.some((root) => isWithin(path, root)),+ )+ ) {+ return {+ allowed: false,+ reason: "filesystem root is outside approved roots",+ };+ }+ return { allowed: true };+};diff --git a/src/server/registerProcessComparisonTool.ts b/src/server/registerProcessComparisonTool.tsindex 49c8c2cc9..708859e51 100644--- a/src/server/registerProcessComparisonTool.ts+++ b/src/server/registerProcessComparisonTool.ts@@ -11,7 +11,7 @@ import type { RecordUnknownInput } from "../domain/residualUnknown.js";import {compareProcessCaptures,processCaptureSchema,- validateProcessCapture,+ parseProcessCapture,} from "../domain/processCapture.js";import { recordDerivedEvidence } from "./recordDerivedEvidence.js";import { err } from "../domain/result.js";@@ -103,7 +103,12 @@ const validateCaptureSources = ([parsed.right_evidence_id, parsed.right],] as const) {const evidence = session.evidenceById(evidenceId);- const result = processCaptureSchema.safeParse(evidence?.normalized_result);+ let evidenceCapture: z.infer<typeof processCaptureSchema> | undefined;+ try {+ evidenceCapture = parseProcessCapture(evidence?.normalized_result);+ } catch {+ evidenceCapture = undefined;+ }if (evidence === undefined ||evidence.operation !== "capture_process_scenario" ||@@ -113,10 +118,8 @@ const validateCaptureSources = (evidence.provider.version !== PROCESS_PROVIDER.version ||evidence.confidence !== "observed" ||evidence.authority !== "controlled-replay" ||- !result.success ||- (result.success && validateProcessCapture(result.data).length > 0) ||- validateProcessCapture(capture).length > 0 ||- canonicalJson(result.data) !== canonicalJson(capture)+ evidenceCapture === undefined ||+ canonicalJson(evidenceCapture) !== canonicalJson(capture))return err(new EvidenceIntegrityError(