Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(process): introduce evidence-safe capture v4
morlutoee4d284597a3
diff --git a/src/application/CommandShimReplay.ts b/src/application/CommandShimReplay.tsindex 7d766da3d..ecd5868ec 100644--- a/src/application/CommandShimReplay.ts+++ b/src/application/CommandShimReplay.ts@@ -99,6 +99,8 @@ export const startCommandShimReplay = async (sequence: events.length,at_ms: Math.max(0, Date.now() - started),command: invocation.command,+ route_index:+ routeIndex !== undefined && routeIndex >= 0 ? routeIndex : null,arguments: invocation.arguments,working_directory: invocation.working_directory,outcome,diff --git a/src/application/EvidenceBundleFiles.ts b/src/application/EvidenceBundleFiles.tsindex f6e50449d..d3b4a3886 100644--- a/src/application/EvidenceBundleFiles.ts+++ b/src/application/EvidenceBundleFiles.ts@@ -11,6 +11,10 @@ import {} from "../domain/evidenceBundle.js";import { EvidenceFileError, EvidenceIntegrityError } from "../domain/errors.js";import { err, ok, type Result } from "../domain/result.js";+import {+ LEGACY_PROCESS_CAPTURE_MESSAGE,+ parseProcessCapture,+} from "../domain/processCapture.js";type EvidenceReadFailure = EvidenceFileError | EvidenceIntegrityError;type EvidenceWriteFailure = EvidenceFileError | EvidenceIntegrityError;@@ -42,7 +46,14 @@ export const readEvidenceBundle = async (const limits = validateJsonLimits(decoded, policy);if (!limits.ok) return limits;try {- return ok(parseEvidenceBundle(decoded));+ const bundle = parseEvidenceBundle(decoded);+ for (const record of bundle.records) {+ if (record.predicate_type === "rea.process-capture/v3")+ throw new TypeError(LEGACY_PROCESS_CAPTURE_MESSAGE);+ if (record.predicate_type === "rea.process-capture/v4")+ parseProcessCapture(record.normalized_result);+ }+ return ok(bundle);} catch (cause: unknown) {return err(new EvidenceIntegrityError("Evidence bundle validation failed", {diff --git a/src/application/ProcessCli.ts b/src/application/ProcessCli.tsindex d329821a2..75ee57637 100644--- a/src/application/ProcessCli.ts+++ b/src/application/ProcessCli.ts@@ -5,8 +5,9 @@ import { createEvidence, parseEvidence } from "../domain/evidence.js";import { jsonValueSchema } from "../domain/jsonValue.js";import {compareProcessCaptures,+ LEGACY_PROCESS_CAPTURE_MESSAGE,parseProcessScenario,- processCaptureSchema,+ parseProcessCapture,} from "../domain/processCapture.js";import { captureProcessScenario } from "./ProcessHarness.js";import {@@ -38,7 +39,7 @@ export const compareProcessEvidenceFiles = async (const right = parseCaptureEvidence(await readJson(rightPath));const comparison = compareProcessCaptures(left.capture, right.capture);return createEvidence(undefined, PROCESS_PROVIDER, {- predicateType: "rea.process-comparison/v2",+ predicateType: "rea.process-comparison/v3",operation: "compare_process_captures",parameters: {left_evidence_id: left.id,@@ -58,14 +59,17 @@ const parseCaptureEvidence = (input: unknown) => {const evidence = parseEvidence(input);if (evidence.operation !== "capture_process_scenario" ||- evidence.predicate_type !== "rea.process-capture/v3" ||+ evidence.predicate_type !== "rea.process-capture/v4" ||evidence.provider.id !== PROCESS_PROVIDER.id ||evidence.provider.version !== PROCESS_PROVIDER.version- )- throw new TypeError("Expected REA Process Capture v3 Evidence");+ ) {+ if (evidence.predicate_type === "rea.process-capture/v3")+ throw new TypeError(LEGACY_PROCESS_CAPTURE_MESSAGE);+ throw new TypeError("Expected REA Process Capture v4 Evidence");+ }return {id: evidence.evidence_id,- capture: processCaptureSchema.parse(evidence.normalized_result),+ capture: parseProcessCapture(evidence.normalized_result),};};diff --git a/src/application/ProcessEvidence.ts b/src/application/ProcessEvidence.tsindex 4819caf7f..4ab635ebe 100644--- a/src/application/ProcessEvidence.ts+++ b/src/application/ProcessEvidence.ts@@ -5,12 +5,13 @@ import type {ProcessCapture,ProcessScenario,} from "../domain/processCapture.js";+import { parseProcessCapture } from "../domain/processCapture.js";-/** Provider identity for controlled Process Capture v3 evidence. */+/** Provider identity for controlled Process Capture v4 evidence. */export const PROCESS_PROVIDER = {id: "rea-process",name: "REA deterministic process harness",- version: "2",+ version: "3",} as const;/** Project one process scenario into secret-free Evidence parameters. */@@ -26,16 +27,17 @@ const processEvidenceParameters = (normalization: scenario.normalization,});-/** Create one canonical observed Process Capture v3 Evidence record. */+/** Create one canonical observed Process Capture v4 Evidence record. */export const createProcessCaptureEvidence = (scenario: ProcessScenario,capture: ProcessCapture,-) =>- createEvidence(undefined, PROCESS_PROVIDER, {- predicateType: "rea.process-capture/v3",+) => {+ const validatedCapture = parseProcessCapture(capture);+ return createEvidence(undefined, PROCESS_PROVIDER, {+ predicateType: "rea.process-capture/v4",operation: "capture_process_scenario",parameters: processEvidenceParameters(scenario),- result: jsonValueSchema.parse(capture),+ result: jsonValueSchema.parse(validatedCapture),confidence: "observed",authority: "controlled-replay",environment: {@@ -44,5 +46,6 @@ export const createProcessCaptureEvidence = (architecture: process.arch,isolation: "process",},- limitations: capture.limitations,+ limitations: validatedCapture.limitations,});+};diff --git a/src/application/ProcessHarness.ts b/src/application/ProcessHarness.tsindex d1a6c84b3..21e37e025 100644--- a/src/application/ProcessHarness.ts+++ b/src/application/ProcessHarness.ts@@ -1,4 +1,5 @@-import { randomUUID } from "node:crypto";+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";@@ -12,11 +13,21 @@ import type {ProcessScenario,TerminalFrame,} from "../domain/processCapture.js";-import { authorizeProcessScenario } from "../domain/processCapture.js";+import {+ authorizeProcessScenario,+ digestProcessCommitment,+ processComparisonContract,+ processScenarioCommitment,+ 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 { startLoopbackReplay, type LoopbackReplay } from "./LoopbackReplay.js";-import { cleanupOwnedProcessGroup } from "./ProcessOwnership.js";+import {+ cleanupOwnedProcessGroup,+ observeOwnedProcessGroup,+} from "./ProcessOwnership.js";import { startProcessSampler } from "./ProcessSampling.js";import { snapshotRoots, type SnapshotResult } from "./FilesystemSnapshot.js";import {@@ -33,6 +44,7 @@ import {normalizeProcessText,redactProtocolEvents,} from "./ProcessNormalization.js";+import { PROCESS_PROVIDER } from "./ProcessEvidence.js";const isWithin = (candidate: string, root: string): boolean =>candidate === root ||@@ -249,19 +261,31 @@ interface CaptureResultOptions {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: 3,+ schema_version: 4,+ manifest: options.manifest,normalization: options.scenario.normalization,frames: options.frames,- rendered_frames: options.renderedFrames,+ 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.exitCode < 0 ? null : options.exit.exitCode,+ 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,@@ -304,6 +328,78 @@ const buildCaptureResult = (options: CaptureResultOptions): ProcessCapture => ({},});+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,@@ -523,6 +619,7 @@ const runProcessScenario = async (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;@@ -530,11 +627,16 @@ const runProcessScenario = async (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>();try {replay = await startLoopbackReplay(scenario);+ startedAt = new Date();started = Date.now();lastOutput = started;renderer = new TerminalRenderer({@@ -601,8 +703,15 @@ const runProcessScenario = async (checkpoints.trigger("root_exit");if (exitReason === "cancelled")throw new ProcessCaptureError("process capture was cancelled");- await new Promise((resolveSettle) =>- setTimeout(resolveSettle, scenario.settle_ms),+ 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;@@ -610,6 +719,7 @@ const runProcessScenario = async (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 ||@@ -649,6 +759,8 @@ const runProcessScenario = async (terminal?.pid ?? -1,),})),+ settlement: { ...settlement, cleanup_outcome: "not_required" },+ manifest,});} catch (cause: unknown) {terminal?.kill("SIGKILL");@@ -668,6 +780,25 @@ const runProcessScenario = async (process_group_id === null ? [] : [process_group_id],),});+ if (capture !== undefined) {+ capture = {+ ...capture,+ settlement: {+ ...capture.settlement,+ cleanup_outcome:+ capture.settlement.state === "quiesced"+ ? "not_required"+ : cleanupFailure === undefined+ ? "cleaned"+ : "failed",+ },+ };+ const issues = validateProcessCapture(capture);+ if (issues.length > 0)+ executionFailure = new ProcessCaptureError(+ `process capture validation failed: ${issues[0]!.path}: ${issues[0]!.message}`,+ );+ }return resolveProcessResult(capture, executionFailure, cleanupFailure);};diff --git a/src/application/ProcessOwnership.ts b/src/application/ProcessOwnership.tsindex 85e633d1e..7ce6ac02a 100644--- a/src/application/ProcessOwnership.ts+++ b/src/application/ProcessOwnership.ts@@ -34,6 +34,12 @@ export type ProcessCleanupResult =| { readonly cleaned: true; readonly signaled: boolean }| { readonly cleaned: false; readonly reason: string };+/** Token-verified liveness result used by post-root-exit settlement. */+export type ProcessGroupObservation =+ | { readonly state: "empty" }+ | { readonly state: "alive" }+ | { readonly state: "unverifiable"; readonly reason: string };+const parseEnvironment = (value: string): Readonly<Record<string, string>> =>Object.fromEntries(value@@ -146,6 +152,41 @@ export const cleanupOwnedProcessGroup = async (return { cleaned: true, signaled: true };};+/** Observe one group without signaling it, failing closed on identity doubt. */+export const observeOwnedProcessGroup = async (+ ownership: OwnedProcessGroup,+ host: ProcessOwnershipHost = systemHost,+): Promise<ProcessGroupObservation> => {+ let members: readonly ProcessGroupMember[];+ try {+ members = await host.listMembers(ownership.processGroupId);+ } catch {+ return {+ state: "unverifiable",+ reason: "process group could not be inspected",+ };+ }+ if (members.length === 0) return { state: "empty" };+ for (const member of members) {+ try {+ if (+ (await host.environment(member.pid)).REA_PROCESS_RUN_ID !==+ ownership.runId+ )+ return {+ state: "unverifiable",+ reason: "process ownership did not match",+ };+ } catch {+ return {+ state: "unverifiable",+ reason: "process ownership could not be revalidated",+ };+ }+ }+ return { state: "alive" };+};+const commandMatches = (actual: string, expected: string): boolean => {const normalizedActual = actual.trim();const normalizedExpected = expected.trim();diff --git a/src/cliProcessCommands.ts b/src/cliProcessCommands.tsindex a7beefcff..2c7696e28 100644--- a/src/cliProcessCommands.ts+++ b/src/cliProcessCommands.ts@@ -7,13 +7,13 @@ import {import { logCliCommand } from "./cliLogging.js";import type { Logger } from "./logger.js";-/** Register Process Capture v3 one-shot commands through shared application services. */+/** Register Process Capture v4 one-shot commands through shared application services. */export const registerProcessCommands = (cli: ReturnType<typeof Cli.create>,logger: Logger,): void => {cli.command("capture-process", {- description: "Capture one approved Process Capture v3 JSON scenario",+ description: "Capture one approved Process Capture v4 JSON scenario",args: z.object({ scenario: z.string().describe("Scenario JSON path") }),run: ({ args }) =>logCliCommand(logger, "capture-process", () =>@@ -21,7 +21,7 @@ export const registerProcessCommands = (),});cli.command("compare-process-captures", {- description: "Compare two Process Capture v3 Evidence JSON files",+ description: "Compare two Process Capture v4 Evidence JSON files",args: z.object({left: z.string().describe("Left capture Evidence JSON path"),right: z.string().describe("Right capture Evidence JSON path"),diff --git a/src/contracts/investigationExamples.ts b/src/contracts/investigationExamples.tsindex 0c4da92cf..6b74affc9 100644--- a/src/contracts/investigationExamples.ts+++ b/src/contracts/investigationExamples.ts@@ -45,12 +45,12 @@ export const FUNCTION_COMPARISON_EVIDENCE = createEvidence(const PROCESS_PROVIDER = {id: "rea-process",name: "REA deterministic process harness",- version: "2",+ version: "3",} as const;const capture = processCaptureSchema.parse(EMPTY_PROCESS_CAPTURE_EXAMPLE);const captureEvidence = (scenario: string) =>createEvidence(undefined, PROCESS_PROVIDER, {- predicateType: "rea.process-capture/v3",+ predicateType: "rea.process-capture/v4",operation: "capture_process_scenario",parameters: { scenario },result: jsonValueSchema.parse(capture),@@ -69,7 +69,7 @@ export const PROCESS_COMPARISON_EVIDENCE = createEvidence(undefined,PROCESS_PROVIDER,{- predicateType: "rea.process-comparison/v2",+ predicateType: "rea.process-comparison/v3",operation: "compare_process_captures",parameters: {left_evidence_id: PROCESS_CAPTURE_REFERENCE.evidence_id,diff --git a/src/contracts/processCaptureExample.ts b/src/contracts/processCaptureExample.tsindex 6bc8420ac..4572fda7d 100644--- a/src/contracts/processCaptureExample.ts+++ b/src/contracts/processCaptureExample.ts@@ -1,21 +1,61 @@import type { JsonValue } from "../domain/jsonValue.js";+import { digestProcessCommitment } from "../domain/processCapture.js";++const normalization = {+ paths: true,+ pids: true,+ ports: true,+ time_bucket_ms: 10,+ patterns: [],+};+const scenario = { executable_sha256: "0".repeat(64) };+const comparisonContract = {};+const shimPlan: JsonValue[] = [];+const replayPlan = {};/** Minimal valid process capture used only in public contract examples. */export const EMPTY_PROCESS_CAPTURE_EXAMPLE = {- schema_version: 3,- normalization: {- paths: true,- pids: true,- ports: true,- time_bucket_ms: 10,- patterns: [],+ schema_version: 4,+ manifest: {+ rea_version: "1.1.0",+ provider_version: "3",+ platform: "fixture",+ architecture: "fixture",+ pty_backend: "node-pty",+ started_at: "2026-01-01T00:00:00.000Z",+ completed_at: "2026-01-01T00:00:00.001Z",+ scenario,+ comparison_contract: comparisonContract,+ shim_plan: shimPlan,+ replay_plan: replayPlan,+ full_scenario_sha256: digestProcessCommitment(scenario),+ comparison_contract_sha256: digestProcessCommitment(comparisonContract),+ executable_sha256: "0".repeat(64),+ normalization_sha256: digestProcessCommitment(normalization),+ shim_plan_sha256: digestProcessCommitment(shimPlan),+ replay_plan_sha256: digestProcessCommitment(replayPlan),},+ normalization,frames: [],rendered_frames: [],interaction_events: [],exit: { code: 0, signal: null, reason: "exited" },+ settlement: {+ state: "quiesced",+ elapsed_ms: 50,+ cleanup_outcome: "not_required",+ },process_samples: [],- filesystem_checkpoints: [],+ filesystem_checkpoints: [+ { name: "before", at_ms: 0, files: [], effects: [], truncated: false },+ {+ name: "after_settlement",+ at_ms: 50,+ files: [],+ effects: [],+ truncated: false,+ },+ ],shim_events: [],protocol_events: [],files_before: [],diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.tsindex a990ec056..b2c4f0e9f 100644--- a/src/contracts/toolContracts.ts+++ b/src/contracts/toolContracts.ts@@ -432,17 +432,18 @@ export const SESSION_TOOL_CONTRACTS = [),session("capture_process_scenario",- "Run one bounded process under a PTY using operator-approved executable and working roots. Requires approved: true; unknown_registry_approved: true separately records capture residuals. Captures raw and xterm-rendered terminal frames, scripted interactions, lifecycle filesystem checkpoints, process ownership, declarative command shims, and loopback replay. Disabled unless operator policy enables it; not a security sandbox.",+ "Run one bounded process under a PTY using operator-approved executable and working roots. Produces Process Capture v4; legacy v3 captures cannot be upgraded and must be recaptured with this tool. Requires approved: true; unknown_registry_approved: true separately records capture residuals. Captures raw and xterm-rendered terminal frames, scripted interactions, lifecycle filesystem checkpoints, process ownership, declarative command shims, and loopback replay. Disabled unless operator policy enables it; not a security sandbox.",processScenarioSchema,),session("compare_process_captures",- "Compare two Process Capture v3 observations across terminal, interaction, exit, process, filesystem, command-shim, HTTP, and WebSocket evidence, returning the first bounded divergence. Missing or truncated observations are never treated as equivalent.",+ "Compare two compatible Process Capture v4 observations across terminal, interaction, exit, settlement, process, filesystem, command-shim, HTTP, and WebSocket evidence, returning the first bounded divergence. Process Capture v3 is unsupported and must be recaptured with capture_process_scenario. Missing or truncated observations are never treated as equivalent.",z.object({left_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),left: processCaptureSchema,right_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),right: processCaptureSchema,+ max_capture_age_ms: z.number().int().nonnegative().optional(),unknown_registry_approved: z.literal(true).optional()diff --git a/src/domain/changedBehavior.ts b/src/domain/changedBehavior.tsindex 09170ee35..b64e56cba 100644--- a/src/domain/changedBehavior.ts+++ b/src/domain/changedBehavior.ts@@ -64,10 +64,10 @@ type RuntimeStatus = z.infer<typeof processCaptureComparisonSchema>["status"];const EXPECTED_PROVIDERS = {compare_process_captures: {- predicate: "rea.process-comparison/v2",+ predicate: "rea.process-comparison/v3",id: "rea-process",name: "REA deterministic process harness",- version: "2",+ version: "3",},compare_artifacts: {predicate: "rea.artifact-comparison/v1",diff --git a/src/domain/processCapture.ts b/src/domain/processCapture.tsindex d172c331a..eb0becbc9 100644--- a/src/domain/processCapture.ts+++ b/src/domain/processCapture.ts@@ -1,4 +1,6 @@+import { createHash } from "node:crypto";import { resolve } from "node:path";+import canonicalize from "canonicalize";import { z } from "zod";const positiveBudget = z.number().int().positive();@@ -36,7 +38,57 @@ const outputChunkSchema = z.object({data: z.string().max(1_000_000),});-/** Exact boundary schema for bounded dynamic process scenarios. */+/** 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.@@ -313,7 +365,6 @@ export const processScenarioSchema = z});});-/** A parsed, bounded dynamic process observation scenario. *//** Parsed instructions and resource bounds for one process experiment. */export type ProcessScenario = z.infer<typeof processScenarioSchema>;@@ -321,7 +372,6 @@ export type ProcessScenario = z.infer<typeof processScenarioSchema>;export const parseProcessScenario = (input: unknown): ProcessScenario =>processScenarioSchema.parse(input);-/** Operator-owned policy for process capture. *//** Operator-owned ceiling applied in addition to per-scenario approval. */export interface ProcessExecutionPolicy {readonly enabled: boolean;@@ -331,7 +381,6 @@ export interface ProcessExecutionPolicy {readonly allowExternalNetwork: boolean;}-/** A safe, caller-visible process-policy decision. *//** Explicit authorization result; denial reasons are safe to show callers. */export type ProcessPolicyDecision =| { readonly allowed: true }@@ -395,7 +444,6 @@ export const authorizeProcessScenario = (return { allowed: true };};-/** One bounded terminal observation. *//** Normalized raw PTY chunk, preserving transport-level output differences. */export interface TerminalFrame {readonly sequence: number;@@ -403,7 +451,6 @@ export interface TerminalFrame {readonly data: string;}-/** One rendered terminal state after xterm has parsed a PTY chunk or resize. *//** Serialized terminal state after interpreting control and resize sequences. */export interface RenderedTerminalFrame {readonly sequence: number;@@ -417,7 +464,6 @@ export interface RenderedTerminalFrame {readonly serialized_state: string;}-/** One attempted scripted interaction with the PTY. *//** Scheduled input, resize, or signal with its observed dispatch outcome. */export interface InteractionEvent {readonly sequence: number;@@ -455,7 +501,6 @@ export interface ProcessSample {readonly session_id: number | null;}-/** A named filesystem observation captured during a process lifecycle. *//*** Named filesystem state whose effects are relative to the prior checkpoint.*/@@ -467,12 +512,12 @@ export interface FilesystemCheckpoint {readonly truncated: boolean;}-/** One invocation observed by the declarative command-shim replay adapter. *//** Recorded deterministic dependency invocation and route-match outcome. */export interface ShimEvent {readonly sequence: number;readonly at_ms: number;readonly command: string;+ readonly route_index: number | null;readonly arguments: readonly string[];readonly working_directory: string;readonly outcome: "matched" | "unmatched" | "exhausted";@@ -494,15 +539,33 @@ export interface ProtocolEvent {| "disconnected";}-/** A bounded process observation with explicit incompleteness metadata. *//**- * Process Capture v3 observation set.+ * Process Capture v4 observation set.** `truncated` and `residual_unknowns` are semantic evidence: consumers must not* infer equivalence from matching bounded observations when either is present.*/export interface ProcessCapture {- readonly schema_version: 3;+ readonly schema_version: 4;+ readonly manifest: {+ readonly rea_version: string;+ readonly provider_version: string;+ readonly platform: string;+ readonly architecture: string;+ readonly pty_backend: "node-pty";+ readonly started_at: string;+ readonly completed_at: string;+ readonly scenario: Readonly<Record<string, unknown>>;+ readonly comparison_contract: Readonly<Record<string, unknown>>;+ readonly shim_plan: readonly unknown[];+ readonly replay_plan: Readonly<Record<string, unknown>>;+ readonly full_scenario_sha256: string;+ readonly comparison_contract_sha256: string;+ readonly executable_sha256: string;+ readonly normalization_sha256: string;+ readonly shim_plan_sha256: string;+ readonly replay_plan_sha256: string;+ };readonly normalization: z.infer<typeof normalizationSchema>;readonly frames: readonly TerminalFrame[];readonly rendered_frames: readonly RenderedTerminalFrame[];@@ -512,6 +575,11 @@ export interface ProcessCapture {readonly signal: number | null;readonly reason: "exited" | "timeout" | "idle_timeout";};+ readonly settlement: {+ readonly state: "quiesced" | "alive_at_deadline" | "unverifiable";+ readonly elapsed_ms: number;+ readonly cleanup_outcome: "not_required" | "cleaned" | "failed";+ };readonly process_samples: readonly ProcessSample[];readonly filesystem_checkpoints: readonly FilesystemCheckpoint[];readonly shim_events: readonly ShimEvent[];@@ -558,7 +626,28 @@ const fileEffectSchema = z.object({/** Exact serialized shape of a bounded process capture. */export const processCaptureSchema: z.ZodType<ProcessCapture> = z.object({- schema_version: z.literal(3),+ schema_version: z.literal(4, {+ error: LEGACY_PROCESS_CAPTURE_MESSAGE,+ }),+ manifest: z.object({+ rea_version: z.string().min(1),+ provider_version: z.string().min(1),+ platform: z.string().min(1),+ architecture: z.string().min(1),+ pty_backend: z.literal("node-pty"),+ started_at: z.iso.datetime(),+ completed_at: z.iso.datetime(),+ scenario: z.record(z.string(), z.unknown()),+ comparison_contract: z.record(z.string(), z.unknown()),+ shim_plan: z.array(z.unknown()),+ replay_plan: z.record(z.string(), z.unknown()),+ full_scenario_sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ comparison_contract_sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ executable_sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ normalization_sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ shim_plan_sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ replay_plan_sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ }),normalization: normalizationSchema,frames: z.array(z.object({@@ -595,6 +684,11 @@ export const processCaptureSchema: z.ZodType<ProcessCapture> = z.object({signal: z.number().int().nullable(),reason: z.enum(["exited", "timeout", "idle_timeout"]),}),+ settlement: z.object({+ state: z.enum(["quiesced", "alive_at_deadline", "unverifiable"]),+ elapsed_ms: z.number().int().nonnegative(),+ cleanup_outcome: z.enum(["not_required", "cleaned", "failed"]),+ }),process_samples: z.array(z.object({at_ms: z.number().int().nonnegative(),@@ -619,6 +713,7 @@ export const processCaptureSchema: z.ZodType<ProcessCapture> = z.object({sequence: z.number().int().nonnegative(),at_ms: z.number().int().nonnegative(),command: z.string(),+ route_index: z.number().int().nonnegative().nullable(),arguments: z.array(z.string()),working_directory: z.string(),outcome: z.enum(["matched", "unmatched", "exhausted"]),@@ -666,6 +761,173 @@ 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;+};++/** Parse unknown input as v4 and reject invalid commitments or semantics. */+export const parseProcessCapture = (input: unknown): ProcessCapture => {+ if (+ typeof input === "object" &&+ input !== null &&+ "schema_version" in input &&+ input.schema_version === 3+ )+ throw new TypeError(LEGACY_PROCESS_CAPTURE_MESSAGE);+ const capture = processCaptureSchema.parse(input);+ const issues = validateProcessCapture(capture);+ if (issues.length > 0)+ throw new TypeError(+ `Invalid Process Capture v4: ${issues.map(({ path, message }) => `${path}: ${message}`).join("; ")}`,+ );+ return capture;+};+export {compareProcessCaptures,comparisonStatusSchema,diff --git a/src/domain/processComparison.ts b/src/domain/processComparison.tsindex e81a5939c..9f25e11a9 100644--- a/src/domain/processComparison.ts+++ b/src/domain/processComparison.ts@@ -1,6 +1,7 @@import { z } from "zod";import type { ProcessCapture } from "./processCapture.js";+import { validateProcessCapture } from "./processCapture.js";/** Comparison classification that never equates incomplete evidence. */export const comparisonStatusSchema = z.enum([@@ -198,7 +199,7 @@ const chooseFirstDivergence = (/** Compare bounded captures without equating missing or incompatible evidence. *//**- * Compare two Process Capture v3 observations without treating absence as proof.+ * 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.@@ -206,7 +207,36 @@ const chooseFirstDivergence = (export const compareProcessCaptures = (left: ProcessCapture,right: ProcessCapture,+ options: {+ readonly maxCaptureAgeMs?: number;+ readonly now?: () => number;+ } = {},): ProcessCaptureComparison => {+ const invalid = [+ ...validateProcessCapture(left),+ ...validateProcessCapture(right),+ ];+ if (invalid.length > 0)+ throw new TypeError(`Invalid Process Capture v4: ${invalid[0]!.path}`);+ if (+ left.schema_version !== right.schema_version ||+ left.manifest.comparison_contract_sha256 !==+ right.manifest.comparison_contract_sha256+ )+ 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,+ )+ )+ throw new TypeError("Process capture exceeds max_capture_age_ms");+ }if (left.truncated || right.truncated) {return {status: "truncated",@@ -247,7 +277,8 @@ export const compareProcessCaptures = (const exit =hasUnknown(left, "exit") || hasUnknown(right, "exit")? "unknown"- : JSON.stringify(left.exit) === JSON.stringify(right.exit)+ : JSON.stringify({ exit: left.exit, settlement: left.settlement }) ===+ JSON.stringify({ exit: right.exit, settlement: right.settlement })? "unchanged": "changed";const filesystem = classify(@@ -279,7 +310,11 @@ export const compareProcessCaptures = (left.interaction_events,right.interaction_events,),- firstCollectionDivergence("exit", [left.exit], [right.exit]),+ firstCollectionDivergence(+ "exit",+ [{ ...left.exit, settlement: left.settlement }],+ [{ ...right.exit, settlement: right.settlement }],+ ),firstCollectionDivergence("filesystem",filesystemObservations(left),diff --git a/src/domain/reconstructionVerification.ts b/src/domain/reconstructionVerification.tsindex c6d8a98b8..c9090b74b 100644--- a/src/domain/reconstructionVerification.ts+++ b/src/domain/reconstructionVerification.ts@@ -44,7 +44,7 @@ const MAX_CANONICAL_BYTES = 32 * 1024 * 1024;const providers = {behavioral: {operation: "compare_process_captures",- predicate: "rea.process-comparison/v2",+ predicate: "rea.process-comparison/v3",id: "rea-process",name: "REA deterministic process harness",},@@ -199,7 +199,7 @@ const validateSourceKinds = (): void => {const expected =claim.kind === "behavioral"- ? ["capture_process_scenario", "rea.process-capture/v3"]+ ? ["capture_process_scenario", "rea.process-capture/v4"]: claim.kind === "structural-function"? ["analyze_function", "rea.analysis/v2"]: ["inventory_artifact", "rea.analysis/v2"];@@ -230,7 +230,7 @@ const validateComparisonIdentity = (claim: Claim, evidence: Evidence): void => {evidence.predicate_type !== expected.predicate ||evidence.provider.id !== expected.id ||evidence.provider.name !== expected.name ||- evidence.provider.version !== (claim.kind === "behavioral" ? "2" : "1") ||+ evidence.provider.version !== (claim.kind === "behavioral" ? "3" : "1") ||evidence.confidence !== "derived" ||evidence.authority !== "analyst-inference" ||evidence.subject !== nulldiff --git a/src/domain/staticRuntimeCorrelation.ts b/src/domain/staticRuntimeCorrelation.tsindex 59d716536..eaea50856 100644--- a/src/domain/staticRuntimeCorrelation.ts+++ b/src/domain/staticRuntimeCorrelation.ts@@ -158,7 +158,7 @@ const EXPECTED = {"REA function comparison",],compare_process_captures: [- "rea.process-comparison/v2",+ "rea.process-comparison/v3","rea-process","REA deterministic process harness",],@@ -403,7 +403,7 @@ const assertComparisonIdentity = (evidence: Evidence): void => {evidence.provider.id !== expected[1] ||evidence.provider.name !== expected[2] ||evidence.provider.version !==- (evidence.operation === "compare_process_captures" ? "2" : "1") ||+ (evidence.operation === "compare_process_captures" ? "3" : "1") ||evidence.confidence !== "derived" ||evidence.authority !== "analyst-inference" ||evidence.subject !== null ||diff --git a/src/identity.ts b/src/identity.tsindex dc9889101..474cdc35d 100644--- a/src/identity.ts+++ b/src/identity.ts@@ -6,6 +6,7 @@export const PRODUCT_IDENTITY = {displayName: "REA",packageName: "rea-agents",+ packageVersion: "1.1.0",cliBinary: "rea",mcpCommand: "npx -y rea-agents mcp",mcpServerKey: "rea",diff --git a/src/server/registerProcessComparisonTool.ts b/src/server/registerProcessComparisonTool.tsindex 5089d9841..49c8c2cc9 100644--- a/src/server/registerProcessComparisonTool.ts+++ b/src/server/registerProcessComparisonTool.ts@@ -11,6 +11,7 @@ import type { RecordUnknownInput } from "../domain/residualUnknown.js";import {compareProcessCaptures,processCaptureSchema,+ validateProcessCapture,} from "../domain/processCapture.js";import { recordDerivedEvidence } from "./recordDerivedEvidence.js";import { err } from "../domain/result.js";@@ -23,6 +24,7 @@ export const registerProcessComparisonTool = (server: McpServer,session: BinarySessionPort,contract: (typeof SESSION_TOOL_CONTRACTS)[6],+ now: () => number = Date.now,): void => {server.registerTool(contract.name,@@ -34,14 +36,34 @@ export const registerProcessComparisonTool = (left: processCaptureSchema,right_evidence_id: z.string(),right: processCaptureSchema,+ max_capture_age_ms: z.number().int().nonnegative().optional(),unknown_registry_approved: z.literal(true).optional(),}).parse(input);const validated = validateCaptureSources(session, parsed);if (!validated.ok) return toCallToolResult(validated, contract);- const comparison = compareProcessCaptures(parsed.left, parsed.right);+ let comparison: ReturnType<typeof compareProcessCaptures>;+ try {+ comparison = compareProcessCaptures(parsed.left, parsed.right, {+ ...(parsed.max_capture_age_ms === undefined+ ? {}+ : { maxCaptureAgeMs: parsed.max_capture_age_ms }),+ now,+ });+ } catch (cause: unknown) {+ return toCallToolResult(+ err(+ new EvidenceIntegrityError(+ cause instanceof Error+ ? cause.message+ : "Invalid Process Capture v4",+ ),+ ),+ contract,+ );+ }const evidence = createEvidence(undefined, PROCESS_PROVIDER, {- predicateType: "rea.process-comparison/v2",+ predicateType: "rea.process-comparison/v3",operation: contract.name,parameters: {left_evidence_id: parsed.left_evidence_id,@@ -85,13 +107,15 @@ const validateCaptureSources = (if (evidence === undefined ||evidence.operation !== "capture_process_scenario" ||- evidence.predicate_type !== "rea.process-capture/v3" ||+ evidence.predicate_type !== "rea.process-capture/v4" ||evidence.provider.id !== PROCESS_PROVIDER.id ||evidence.provider.name !== PROCESS_PROVIDER.name ||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))return err(diff --git a/tests/changedBehavior.test.ts b/tests/changedBehavior.test.tsindex 6929cbfd7..57f6ebb40 100644--- a/tests/changedBehavior.test.ts+++ b/tests/changedBehavior.test.ts@@ -33,11 +33,11 @@ const comparison = (name: process? "REA deterministic process harness": "REA artifact comparison",- version: operation === "compare_process_captures" ? "2" : "1",+ version: operation === "compare_process_captures" ? "3" : "1",},{predicateType: process- ? "rea.process-comparison/v2"+ ? "rea.process-comparison/v3": "rea.artifact-comparison/v1",operation,parameters: {},diff --git a/tests/integration/serverIntegration.test.ts b/tests/integration/serverIntegration.test.tsindex a6ebb8054..45cf5153e 100644--- a/tests/integration/serverIntegration.test.ts+++ b/tests/integration/serverIntegration.test.ts@@ -283,7 +283,7 @@ describe("full MCP integration with multi-tool sequences", () => {});const captureEvidence = (capture: typeof left) =>createEvidence(undefined, PROCESS_PROVIDER, {- predicateType: "rea.process-capture/v3",+ predicateType: "rea.process-capture/v4",operation: "capture_process_scenario",parameters: {},result: jsonValueSchema.parse(capture),diff --git a/tests/processCapture.test.ts b/tests/processCapture.test.tsindex e3edd43bf..7c8804810 100644--- a/tests/processCapture.test.ts+++ b/tests/processCapture.test.ts@@ -16,7 +16,12 @@ import { snapshotRoots } from "../src/application/FilesystemSnapshot.js";import {authorizeProcessScenario,compareProcessCaptures,+ digestProcessCommitment,+ LEGACY_PROCESS_CAPTURE_MESSAGE,+ parseProcessCapture,parseProcessScenario,+ processCaptureSchema,+ type ProcessCapture,type ProcessExecutionPolicy,} from "../src/domain/processCapture.js";@@ -25,6 +30,75 @@ const processFixture = fileURLToPath();const execFileAsync = promisify(execFile);+const emptyCapture = (): ProcessCapture => {+ const normalization = {+ paths: true,+ pids: true,+ ports: true,+ time_bucket_ms: 10,+ patterns: [],+ };+ const scenario = { executable_sha256: "0".repeat(64) };+ const comparisonContract = {};+ const shimPlan: readonly unknown[] = [];+ const replayPlan = {};+ return {+ schema_version: 4,+ manifest: {+ rea_version: "test",+ provider_version: "3",+ platform: process.platform,+ architecture: process.arch,+ pty_backend: "node-pty",+ started_at: "2026-01-01T00:00:00.000Z",+ completed_at: "2026-01-01T00:00:00.001Z",+ scenario,+ comparison_contract: comparisonContract,+ shim_plan: shimPlan,+ replay_plan: replayPlan,+ full_scenario_sha256: digestProcessCommitment(scenario),+ comparison_contract_sha256: digestProcessCommitment(comparisonContract),+ executable_sha256: "0".repeat(64),+ normalization_sha256: digestProcessCommitment(normalization),+ shim_plan_sha256: digestProcessCommitment(shimPlan),+ replay_plan_sha256: digestProcessCommitment(replayPlan),+ },+ normalization,+ frames: [],+ rendered_frames: [],+ interaction_events: [],+ exit: { code: 0, signal: null, reason: "exited" },+ settlement: {+ state: "quiesced",+ elapsed_ms: 50,+ cleanup_outcome: "not_required",+ },+ process_samples: [],+ filesystem_checkpoints: [+ { name: "before", at_ms: 0, files: [], effects: [], truncated: false },+ {+ name: "after_settlement",+ at_ms: 50,+ files: [],+ effects: [],+ truncated: false,+ },+ ],+ shim_events: [],+ protocol_events: [],+ files_before: [],+ files_after: [],+ filesystem_effects: [],+ truncated: false,+ limitations: [],+ residual_unknowns: [],+ cleanup: {+ owned_process_group: "verified",+ temporary_root: "removed",+ },+ };+};+describe("process capture domain", () => {const base = {approved: true as const,@@ -107,7 +181,9 @@ describe("process capture domain", () => {it("never considers truncated captures equivalent", () => {const capture = {- schema_version: 3 as const,+ schema_version: 4 as const,+ manifest: emptyCapture().manifest,+ settlement: emptyCapture().settlement,normalization: {paths: true,pids: true,@@ -120,7 +196,7 @@ describe("process capture domain", () => {interaction_events: [],exit: { code: 0, signal: null, reason: "exited" as const },process_samples: [],- filesystem_checkpoints: [],+ filesystem_checkpoints: emptyCapture().filesystem_checkpoints,shim_events: [],protocol_events: [],files_before: [],@@ -137,9 +213,72 @@ describe("process capture domain", () => {expect(compareProcessCaptures(capture, capture).status).toBe("truncated");});+ it("rejects altered v4 commitments and accepts canonical key reordering", () => {+ const capture = emptyCapture();+ expect(parseProcessCapture(capture)).toEqual(capture);+ expect(digestProcessCommitment({ second: 2, first: 1 })).toBe(+ digestProcessCommitment({ first: 1, second: 2 }),+ );+ expect(() =>+ parseProcessCapture({+ ...capture,+ manifest: {+ ...capture.manifest,+ normalization_sha256: "f".repeat(64),+ },+ }),+ ).toThrow("normalization_sha256");+ expect(() =>+ parseProcessCapture({+ ...capture,+ manifest: {+ ...capture.manifest,+ executable_sha256: "f".repeat(64),+ },+ }),+ ).toThrow("executable_sha256");+ });++ it("tells agents and users to recapture unsupported v3 evidence", () => {+ const legacy = { ...emptyCapture(), schema_version: 3 };+ expect(() => parseProcessCapture(legacy)).toThrow(+ LEGACY_PROCESS_CAPTURE_MESSAGE,+ );+ const parsed = processCaptureSchema.safeParse(legacy);+ expect(parsed.success).toBe(false);+ if (parsed.success) throw new Error("expected legacy capture rejection");+ expect(parsed.error.issues[0]?.message).toBe(+ LEGACY_PROCESS_CAPTURE_MESSAGE,+ );+ });++ it("requires compatible contracts and enforces capture age through a clock seam", () => {+ const capture = emptyCapture();+ expect(() =>+ compareProcessCaptures(capture, {+ ...capture,+ manifest: {+ ...capture.manifest,+ comparison_contract: { changed: true },+ comparison_contract_sha256: digestProcessCommitment({+ changed: true,+ }),+ },+ }),+ ).toThrow("incompatible comparison contracts");+ expect(() =>+ compareProcessCaptures(capture, capture, {+ maxCaptureAgeMs: 1,+ now: () => Date.parse("2026-01-01T00:00:01.000Z"),+ }),+ ).toThrow("max_capture_age_ms");+ });+it("classifies missing observations as unknown and one-sided evidence as added", () => {const base = {- schema_version: 3 as const,+ schema_version: 4 as const,+ manifest: emptyCapture().manifest,+ settlement: emptyCapture().settlement,normalization: {paths: true,pids: true,@@ -152,7 +291,7 @@ describe("process capture domain", () => {interaction_events: [],exit: { code: 0, signal: null, reason: "exited" as const },process_samples: [],- filesystem_checkpoints: [],+ filesystem_checkpoints: emptyCapture().filesystem_checkpoints,shim_events: [],protocol_events: [],files_before: [],@@ -196,7 +335,9 @@ describe("process capture domain", () => {it("compares raw terminal chunks even when rendered states agree", () => {const capture = {- schema_version: 3 as const,+ schema_version: 4 as const,+ manifest: emptyCapture().manifest,+ settlement: emptyCapture().settlement,normalization: {paths: true,pids: true,@@ -209,7 +350,7 @@ describe("process capture domain", () => {interaction_events: [],exit: { code: 0, signal: null, reason: "exited" as const },process_samples: [],- filesystem_checkpoints: [],+ filesystem_checkpoints: emptyCapture().filesystem_checkpoints,shim_events: [],protocol_events: [],files_before: [],@@ -237,7 +378,9 @@ describe("process capture domain", () => {it("keeps filesystem evidence unknown when stable snapshots match", () => {const capture = {- schema_version: 3 as const,+ schema_version: 4 as const,+ manifest: emptyCapture().manifest,+ settlement: emptyCapture().settlement,normalization: {paths: true,pids: true,@@ -250,7 +393,7 @@ describe("process capture domain", () => {interaction_events: [],exit: { code: 0, signal: null, reason: "exited" as const },process_samples: [],- filesystem_checkpoints: [],+ filesystem_checkpoints: emptyCapture().filesystem_checkpoints,shim_events: [],protocol_events: [],files_before: [],@@ -275,6 +418,7 @@ describe("process capture domain", () => {const transient = compareProcessCaptures(complete, {...complete,filesystem_checkpoints: [+ { name: "before", at_ms: 0, files: [], effects: [], truncated: false },{name: "during_run",at_ms: 10,@@ -282,6 +426,13 @@ describe("process capture domain", () => {effects: [],truncated: false,},+ {+ name: "after_settlement",+ at_ms: 50,+ files: [],+ effects: [],+ truncated: false,+ },],});expect(transient.filesystem).toBe("changed");@@ -290,7 +441,9 @@ describe("process capture domain", () => {it("detects changes in normalized process sample metadata", () => {const capture = {- schema_version: 3 as const,+ schema_version: 4 as const,+ manifest: emptyCapture().manifest,+ settlement: emptyCapture().settlement,normalization: {paths: true,pids: true,@@ -312,7 +465,7 @@ describe("process capture domain", () => {command: "worker",},],- filesystem_checkpoints: [],+ filesystem_checkpoints: emptyCapture().filesystem_checkpoints,shim_events: [],protocol_events: [],files_before: [],@@ -618,7 +771,7 @@ describe("process capture adapter", () => {);expect(result.ok).toBe(true);if (!result.ok) throw result.error;- expect(result.value.schema_version).toBe(3);+ expect(result.value.schema_version).toBe(4);expect(result.value.rendered_frames.at(-1)?.lines.join("\n")).toContain("probe:codex 1.2.3",);diff --git a/tests/reconstructionVerification.test.ts b/tests/reconstructionVerification.test.tsindex e3d85dfcf..f362116f6 100644--- a/tests/reconstructionVerification.test.ts+++ b/tests/reconstructionVerification.test.ts@@ -33,7 +33,7 @@ const source = ({predicateType:authority === "controlled-replay"- ? "rea.process-capture/v3"+ ? "rea.process-capture/v4": "rea.analysis/v2",operation:authority === "controlled-replay"@@ -89,10 +89,10 @@ const processComparison = ({id: "rea-process",name: "REA deterministic process harness",- version: "2",+ version: "3",},{- predicateType: "rea.process-comparison/v2",+ predicateType: "rea.process-comparison/v3",operation: "compare_process_captures",parameters: {left_evidence_id: left.evidence_id,diff --git a/tests/staticRuntimeCorrelation.test.ts b/tests/staticRuntimeCorrelation.test.tsindex ee8c727c1..35640663d 100644--- a/tests/staticRuntimeCorrelation.test.ts+++ b/tests/staticRuntimeCorrelation.test.ts@@ -18,7 +18,7 @@ const capture = (digit: string): Evidence =>undefined,{ id: "fixture", name: "Fixture", version: "1" },{- predicateType: "rea.process-capture/v3",+ predicateType: "rea.process-capture/v4",operation: "capture_process_scenario",parameters: {},result: { digit },@@ -68,10 +68,10 @@ const processComparison = ({id: "rea-process",name: "REA deterministic process harness",- version: "2",+ version: "3",},{- predicateType: "rea.process-comparison/v2",+ predicateType: "rea.process-comparison/v3",operation: "compare_process_captures",parameters: {left_evidence_id: leftCapture.evidence_id,