Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

feat(process): compare declared concurrent traces

morlutod81745cb95b1
diff --git a/docs/process-capture.md b/docs/process-capture.md
index 3d7182951..cf6004ce9 100644
--- a/docs/process-capture.md
+++ b/docs/process-capture.md
@@ -158,6 +158,47 @@ Compare two saved Evidence records with:
rea compare-process-captures authority.json reconstruction.json
```
+Pass an optional third path, `rea compare-process-captures authority.json
+reconstruction.json trace.json`, when valid executions may differ in declared
+concurrent ordering. MCP callers pass the same object as `trace_spec` to
+`compare_process_captures`. A trace specification declares exact named events
+and chooses one language:
+
+- `partial_order` requires every event pair to be related by a
+ `happens_before` edge (including transitive edges) or an explicit
+ `unordered_groups` declaration. `not_before` expresses negative ordering
+ constraints without inferring causality. Optional `prefix` and `suffix`
+ arrays remain exact.
+- `finite_traces` lists the complete accepted variants. An `unordered` token
+ accepts permutations of exactly its declared event multiset; it does not
+ drop or broadly sort events.
+
+Each event uses one source family (`terminal_raw`, `terminal_rendered`,
+`interaction`, `lifecycle`, `process`, `filesystem`, `http`, `websocket`,
+`shim`, or `replay_transition`), an exact JSON payload, and a discriminated
+cardinality: `required`, `optional`, `exact`, or `range`. Specifications with
+duplicate or overlapping predicates, unknown references, cycles, implicit
+ordering gaps, ordered/unordered conflicts, or finite variants that violate
+cardinality are rejected before comparison.
+
+Event payloads are exact by default. To compare schedules whose recorder
+metadata necessarily changes, an event may explicitly list top-level
+`ignore_fields` from the bounded set `sequence`, `at_ms`, `scheduled_at_ms`,
+`dispatched_at_ms`, and `elapsed_ms`; its `exact` object must omit those fields.
+All predicates for one source use the same ignore set, so relaxed metadata
+cannot create declaration-order matching ambiguity. Other payload fields are
+never dropped or normalized by trace comparison.
+
+Process Capture records a monotonic `event_journal` at observation time. Trace
+comparison uses only this capture order for cross-source causality; timestamps
+are retained as event data but never promoted into happens-before evidence.
+Older captures without a complete journal, truncated captures, and relevant
+residual unknowns return a trace verdict of `unknown`. A passing result retains
+each side's raw journal locations and identifies either the matched finite
+variant or the complete satisfied constraint set. A failure returns the first
+declaration-ordered predicate, cardinality, edge, prefix, suffix, or language
+violation with its relevant event locations.
+
The result classifies terminal, interaction, exit, filesystem, protocol,
process, and shim behavior. `first_divergence` points to the earliest observed
difference. Residual unknowns prevent a claim of complete equivalence, but they
diff --git a/docs/product-catalog.json b/docs/product-catalog.json
index e98066928..db39b51a7 100644
--- a/docs/product-catalog.json
+++ b/docs/product-catalog.json
@@ -579,10 +579,10 @@
"mcp_resource_templates": 9
},
"digests": {
- "tools_sha256": "a41d2a1d614288008bf14486ad4c0a9e0abbb4f9c23790acf6493693afe0221e",
+ "tools_sha256": "cca8f06f796f8a95d2f2e46c0fb4176e0ae442081fe7bf992ee4526071fb0aa5",
"prompts_sha256": "f6da3ad38a1000c11364d1710f122ac4990551f04efd8c53ffb2e819b5cf5707",
"resources_sha256": "94bebbab1a1b3cf47644c38d3de6469de568caa7bd7b842f529ead8ad320a912",
- "combined_sha256": "d9fea48861c281b71d9061a0d8a701bb96726b0ac2afefcbfeda79eff5e8aaaf"
+ "combined_sha256": "3ce063a71e1e53c18094aca45df31840eff75f1eaded7cbd84a7ef48db279817"
}
}
}
diff --git a/docs/verification/managed-conformance-manifest.json b/docs/verification/managed-conformance-manifest.json
index 41f834bb5..7b4bc6cd7 100644
--- a/docs/verification/managed-conformance-manifest.json
+++ b/docs/verification/managed-conformance-manifest.json
@@ -1,6 +1,6 @@
{
"schema_version": 1,
- "manifest_id": "ecm_1e57c9db54aab5c777eb3efd823329546eef1099747daf49278bfe195dd9f0f6",
+ "manifest_id": "ecm_8ecf7db7dddcf68278e18291d8d5a4d352b807a55f8b10cd20ad893b3bf9a2ea",
"verifier": {
"id": "rea-managed-conformance",
"version": "1"
@@ -14,7 +14,7 @@
"skill_digests": [
{
"skill_id": "reverse-engineer-anything",
- "sha256": "09805a16a1bd039540fcf317426f7bc009853978f51745b5f290a3d20679cb1e"
+ "sha256": "718b929b39749da6416a45645db6ed4d0775548cfaa1443509066b5c8201015f"
}
],
"claims": [
diff --git a/skills/reverse-engineer-anything/SKILL.md b/skills/reverse-engineer-anything/SKILL.md
index ec2fcd2cf..268f0c446 100644
--- a/skills/reverse-engineer-anything/SKILL.md
+++ b/skills/reverse-engineer-anything/SKILL.md
@@ -4,7 +4,7 @@ description: Reverse engineer native, managed, Electron/JavaScript, packaged, an
metadata:
version: "23"
tool_count: 97
- catalog_digest: "d9fea48861c281b71d9061a0d8a701bb96726b0ac2afefcbfeda79eff5e8aaaf"
+ catalog_digest: "3ce063a71e1e53c18094aca45df31840eff75f1eaded7cbd84a7ef48db279817"
---
# REA
diff --git a/src/application/ProcessCli.ts b/src/application/ProcessCli.ts
index f41ded670..6aa2a2001 100644
--- a/src/application/ProcessCli.ts
+++ b/src/application/ProcessCli.ts
@@ -3,12 +3,15 @@ import { readFile } from "node:fs/promises";
import { parseConfig } from "../config.js";
import {
AnalysisError,
+ AnalysisInputError,
AnalysisProtocolError,
PermissionRequiredError,
projectAnalysisError,
} from "../domain/errors.js";
import { createEvidence, parseEvidence } from "../domain/evidence.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { processTraceSpecificationSchema } from "../domain/processTraceComparison.js";
import {
compareProcessCaptures,
LEGACY_PROCESS_CAPTURE_MESSAGE,
@@ -76,24 +79,41 @@ export const captureProcessScenarioFile = async (path: string) => {
export const compareProcessEvidenceFiles = async (
leftPath: string,
rightPath: string,
+ traceSpecPath?: string,
) => {
try {
const left = parseCaptureEvidence(await readJson(leftPath));
const right = parseCaptureEvidence(await readJson(rightPath));
- const comparison = compareProcessCaptures(left.capture, right.capture);
+ const traceSpecification =
+ traceSpecPath === undefined
+ ? undefined
+ : parseTraceSpecification(await readJson(traceSpecPath));
+ const comparison =
+ traceSpecification === undefined
+ ? compareProcessCaptures(left.capture, right.capture)
+ : compareProcessCaptures(left.capture, right.capture, {
+ traceSpecification,
+ });
return createEvidence(undefined, PROCESS_PROVIDER, {
- predicateType: "rea.process-comparison/v3",
+ predicateType:
+ traceSpecification === undefined
+ ? "rea.process-comparison/v3"
+ : "rea.process-comparison/v4",
operation: "compare_process_captures",
parameters: {
left_evidence_id: left.id,
right_evidence_id: right.id,
left_normalization: left.capture.normalization,
right_normalization: right.capture.normalization,
+ ...(traceSpecification === undefined
+ ? {}
+ : { trace_spec: jsonValueSchema.parse(traceSpecification) }),
},
result: jsonValueSchema.parse(comparison),
confidence: "derived",
authority: "analyst-inference",
limitations: comparison.limitations,
+ locations: [...left.locations, ...right.locations],
evidenceLinks: [left.id, right.id],
});
} catch (cause: unknown) {
@@ -128,12 +148,23 @@ const parseCaptureEvidence = (input: unknown) => {
return {
id: evidence.evidence_id,
capture: parseProcessCapture(evidence.normalized_result),
+ locations: evidence.locations,
};
} catch {
throw invalidCaptureEvidence();
}
};
+const parseTraceSpecification = (input: unknown) => {
+ const parsed = processTraceSpecificationSchema.safeParse(input);
+ if (parsed.success) return parsed.data;
+ throw new AnalysisInputError(
+ "compare-process-captures",
+ { cause: parsed.error },
+ projectInputIssues(parsed.error.issues, input),
+ );
+};
+
const invalidCaptureEvidence = (): ProcessCliFailure =>
new ProcessCliFailure(
"invalid_input",
diff --git a/src/cliProcessCommands.ts b/src/cliProcessCommands.ts
index 7521db103..9e0a36465 100644
--- a/src/cliProcessCommands.ts
+++ b/src/cliProcessCommands.ts
@@ -34,10 +34,14 @@ export const registerProcessCommands = (
args: z.object({
left: z.string().describe("Left capture Evidence JSON path"),
right: z.string().describe("Right capture Evidence JSON path"),
+ traceSpec: z
+ .string()
+ .optional()
+ .describe("Optional partial-order or finite-trace specification path"),
}),
run: ({ args }) =>
logCliCommand(logger, "compare-process-captures", () =>
- compareProcessEvidenceFiles(args.left, args.right),
+ compareProcessEvidenceFiles(args.left, args.right, args.traceSpec),
),
});
};
diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.ts
index fee395cef..90a7300ac 100644
--- a/src/contracts/toolContracts.ts
+++ b/src/contracts/toolContracts.ts
@@ -13,6 +13,7 @@ import { callPathInputSchema } from "../domain/callPath.js";
import { staticRuntimeCorrelationInputSchema } from "../domain/staticRuntimeCorrelation.js";
import { reconstructionVerificationInputSchema } from "../domain/reconstructionVerification.js";
import { replayMachineRunInputSchema } from "../domain/replayMachineRun.js";
+import { processTraceSpecificationSchema } from "../domain/processTraceComparison.js";
import { enhancedInputSchemas } from "./enhancedInputs.js";
import {
@@ -385,6 +386,7 @@ export const importEvidenceBundleInputSchema = z.strictObject({
export const processComparisonInputSchema = z.strictObject({
left_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
right_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
+ trace_spec: processTraceSpecificationSchema.optional(),
max_capture_age_ms: z.number().int().nonnegative().optional(),
unknown_registry_approved: z
.literal(true)
@@ -440,7 +442,7 @@ export const SESSION_TOOL_CONTRACTS = [
),
session(
"compare_process_captures",
- "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.",
+ "Compare two compatible Process Capture v4 observations across terminal, interaction, lifecycle, process, filesystem, command-shim, HTTP, and WebSocket evidence. Optional trace_spec validates exact events against an explicit partial order or finite trace language; concurrency is never inferred from timestamps or broad sorting. Missing, journal-free, or truncated observations are never treated as equivalent.",
processComparisonInputSchema,
),
session(
diff --git a/src/domain/changedBehavior.ts b/src/domain/changedBehavior.ts
index 1d8564123..eb7c1c8a6 100644
--- a/src/domain/changedBehavior.ts
+++ b/src/domain/changedBehavior.ts
@@ -84,25 +84,30 @@ type RuntimeStatus = z.infer<typeof processCaptureComparisonSchema>["status"];
const EXPECTED_PROVIDERS = {
compare_process_captures: {
- predicate: "rea.process-comparison/v3",
+ predicates: ["rea.process-comparison/v3", "rea.process-comparison/v4"],
id: "rea-process",
name: "REA deterministic process harness",
version: "3",
},
compare_artifacts: {
- predicate: "rea.artifact-comparison/v1",
+ predicates: ["rea.artifact-comparison/v1"],
id: "rea-artifact-comparison",
name: "REA artifact comparison",
version: "1",
},
compare_functions: {
- predicate: "rea.function-comparison/v1",
+ predicates: ["rea.function-comparison/v1"],
id: "rea-function-comparison",
name: "REA function comparison",
version: "1",
},
} as const;
+const acceptsPredicate = (
+ expected: readonly string[],
+ actual: string,
+): boolean => expected.some((predicate) => predicate === actual);
+
/** Find observed runtime changes and separately report static change candidates. */
export const findChangedBehavior = (
comparisonsInput: unknown,
@@ -182,7 +187,7 @@ const parseComparisonEvidence = (input: unknown): Evidence => {
.parse(evidence.operation);
const expected = EXPECTED_PROVIDERS[operation];
if (
- evidence.predicate_type !== expected.predicate ||
+ !acceptsPredicate(expected.predicates, evidence.predicate_type) ||
evidence.provider.id !== expected.id ||
evidence.provider.name !== expected.name ||
evidence.provider.version !== expected.version ||
diff --git a/src/domain/processComparison.ts b/src/domain/processComparison.ts
index ce4e42c4d..3f26d7271 100644
--- a/src/domain/processComparison.ts
+++ b/src/domain/processComparison.ts
@@ -5,10 +5,14 @@ import { validateProcessCapture } from "./processCapture.js";
import { jsonValueSchema } from "./jsonValue.js";
import {
compareProcessTraces,
+ processTraceOutcomesDiffer,
processTraceComparisonResultSchema,
- type ProcessTraceSource,
type ProcessTraceSpecification,
} from "./processTraceComparison.js";
+import {
+ dimensionsForTraceSources,
+ traceCoversObservedDimension,
+} from "./processTraceDimensionProjection.js";
/** Comparison classification that never equates incomplete evidence. */
export const comparisonStatusSchema = z.enum([
@@ -276,82 +280,19 @@ const truncatedComparison = (): ProcessCaptureComparison => ({
limitations: ["At least one capture is truncated."],
});
-const dimensionsForTraceSources = (
- sources: ReadonlySet<ProcessTraceSource>,
-): ReadonlySet<(typeof PROCESS_COMPARISON_DIMENSIONS)[number]> => {
- const dimensions = new Set<(typeof PROCESS_COMPARISON_DIMENSIONS)[number]>();
- for (const source of sources) {
- if (source.startsWith("terminal_")) dimensions.add("terminal");
- else if (source === "interaction") dimensions.add("interaction");
- else if (source === "lifecycle") dimensions.add("exit");
- else if (source === "filesystem") dimensions.add("filesystem");
- else if (
- source === "http" ||
- source === "websocket" ||
- source === "replay_transition"
- )
- dimensions.add("protocol");
- else if (source === "process") dimensions.add("process");
- else if (source === "shim") dimensions.add("shim");
- }
- return dimensions;
-};
-
-const traceCoversObservedDimension = (
- dimension: (typeof PROCESS_COMPARISON_DIMENSIONS)[number],
- sources: ReadonlySet<ProcessTraceSource>,
- left: ProcessCapture,
- right: ProcessCapture,
-): boolean => {
- const any = <Value>(
- leftValues: readonly Value[],
- rightValues: readonly Value[],
- ): boolean => leftValues.length > 0 || rightValues.length > 0;
- switch (dimension) {
- case "terminal":
- return (
- (!any(left.frames, right.frames) || sources.has("terminal_raw")) &&
- (!any(left.rendered_frames, right.rendered_frames) ||
- sources.has("terminal_rendered"))
- );
- case "interaction":
- return sources.has("interaction");
- case "exit":
- return sources.has("lifecycle");
- case "filesystem":
- return false;
- case "protocol":
- return (
- (![...left.protocol_events, ...right.protocol_events].some(
- ({ protocol }) => protocol === "http",
- ) ||
- sources.has("http")) &&
- (![...left.protocol_events, ...right.protocol_events].some(
- ({ protocol }) => protocol === "websocket",
- ) ||
- sources.has("websocket")) &&
- (!any(left.replay_transitions, right.replay_transitions) ||
- sources.has("replay_transition"))
- );
- case "process":
- return sources.has("process");
- case "shim":
- return sources.has("shim");
- }
-};
-
const applyTraceVerdict = (
dimensions: ComparisonDimensions,
specification: ProcessTraceSpecification,
trace: ReturnType<typeof compareProcessTraces>,
captures: readonly [left: ProcessCapture, right: ProcessCapture],
): ComparisonDimensions => {
- const traceStatus: ComparisonStatus =
- trace.verdict === "equivalent"
- ? "unchanged"
- : trace.verdict === "different"
- ? "changed"
- : "unknown";
+ const traceShowsDifference = processTraceOutcomesDiffer(trace);
+ const traceStatus =
+ trace.verdict === "unknown"
+ ? "unknown"
+ : trace.verdict === "equivalent" || !traceShowsDifference
+ ? "unchanged"
+ : "changed";
const sources = new Set(specification.events.map(({ source }) => source));
const covered = dimensionsForTraceSources(sources);
const statusFor = (
@@ -359,7 +300,8 @@ const applyTraceVerdict = (
): ComparisonStatus => {
const exact = dimensions[dimension];
if (!covered.has(dimension)) return exact;
- if (trace.verdict === "different") return "changed";
+ if (trace.verdict === "different")
+ return traceShowsDifference ? "changed" : exact;
if (
trace.verdict === "unknown" &&
["changed", "added", "removed"].includes(exact)
diff --git a/src/domain/processTraceComparison.ts b/src/domain/processTraceComparison.ts
index c03895388..1b30bee6a 100644
--- a/src/domain/processTraceComparison.ts
+++ b/src/domain/processTraceComparison.ts
@@ -51,3 +51,11 @@ export const compareProcessTraces = (
diagnostic,
});
};
+
+/** Whether trace conformance or raw declared order differs across captures. */
+export const processTraceOutcomesDiffer = (
+ comparison: ProcessTraceComparisonResult,
+): boolean =>
+ comparison.left.status !== comparison.right.status ||
+ JSON.stringify(comparison.left.raw_trace.map(({ event_id }) => event_id)) !==
+ JSON.stringify(comparison.right.raw_trace.map(({ event_id }) => event_id));
diff --git a/src/domain/processTraceDimensionProjection.ts b/src/domain/processTraceDimensionProjection.ts
new file mode 100644
index 000000000..1b8386b69
--- /dev/null
+++ b/src/domain/processTraceDimensionProjection.ts
@@ -0,0 +1,77 @@
+import type { ProcessCapture } from "./processCapture.js";
+import type { ProcessTraceSource } from "./processTraceSpecification.js";
+
+export type ProcessComparisonDimension =
+ | "terminal"
+ | "interaction"
+ | "exit"
+ | "filesystem"
+ | "protocol"
+ | "process"
+ | "shim";
+
+/** Map declared trace sources to legacy process-comparison dimensions. */
+export const dimensionsForTraceSources = (
+ sources: ReadonlySet<ProcessTraceSource>,
+): ReadonlySet<ProcessComparisonDimension> => {
+ const dimensions = new Set<ProcessComparisonDimension>();
+ for (const source of sources) {
+ if (source.startsWith("terminal_")) dimensions.add("terminal");
+ else if (source === "interaction") dimensions.add("interaction");
+ else if (source === "lifecycle") dimensions.add("exit");
+ else if (source === "filesystem") dimensions.add("filesystem");
+ else if (
+ source === "http" ||
+ source === "websocket" ||
+ source === "replay_transition"
+ )
+ dimensions.add("protocol");
+ else if (source === "process") dimensions.add("process");
+ else if (source === "shim") dimensions.add("shim");
+ }
+ return dimensions;
+};
+
+/** Whether a trace specification covers every observed source in a dimension. */
+export const traceCoversObservedDimension = (
+ dimension: ProcessComparisonDimension,
+ sources: ReadonlySet<ProcessTraceSource>,
+ left: ProcessCapture,
+ right: ProcessCapture,
+): boolean => {
+ const any = <Value>(
+ leftValues: readonly Value[],
+ rightValues: readonly Value[],
+ ): boolean => leftValues.length > 0 || rightValues.length > 0;
+ switch (dimension) {
+ case "terminal":
+ return (
+ (!any(left.frames, right.frames) || sources.has("terminal_raw")) &&
+ (!any(left.rendered_frames, right.rendered_frames) ||
+ sources.has("terminal_rendered"))
+ );
+ case "interaction":
+ return sources.has("interaction");
+ case "exit":
+ return sources.has("lifecycle");
+ case "filesystem":
+ return false;
+ case "protocol":
+ return (
+ (![...left.protocol_events, ...right.protocol_events].some(
+ ({ protocol }) => protocol === "http",
+ ) ||
+ sources.has("http")) &&
+ (![...left.protocol_events, ...right.protocol_events].some(
+ ({ protocol }) => protocol === "websocket",
+ ) ||
+ sources.has("websocket")) &&
+ (!any(left.replay_transitions, right.replay_transitions) ||
+ sources.has("replay_transition"))
+ );
+ case "process":
+ return sources.has("process");
+ case "shim":
+ return sources.has("shim");
+ }
+};
diff --git a/src/domain/processTraceSpecification.ts b/src/domain/processTraceSpecification.ts
index 92a06d44f..b597c62dc 100644
--- a/src/domain/processTraceSpecification.ts
+++ b/src/domain/processTraceSpecification.ts
@@ -43,6 +43,21 @@ const eventDeclarationSchema = z.strictObject({
id: identifierSchema,
source: processTraceSourceSchema,
exact: jsonValueSchema,
+ ignore_fields: z
+ .array(
+ z.enum([
+ "sequence",
+ "at_ms",
+ "scheduled_at_ms",
+ "dispatched_at_ms",
+ "elapsed_ms",
+ ]),
+ )
+ .max(5)
+ .refine((values) => new Set(values).size === values.length, {
+ message: "ignored event fields must be unique",
+ })
+ .optional(),
cardinality: cardinalitySchema.default({ kind: "required" }),
});
@@ -57,6 +72,15 @@ const partialOrderLanguageSchema = z.strictObject({
)
.max(4_096)
.default([]),
+ not_before: z
+ .array(
+ z.strictObject({
+ event: identifierSchema,
+ anchor: identifierSchema,
+ }),
+ )
+ .max(4_096)
+ .default([]),
unordered_groups: z
.array(
z.strictObject({ events: z.array(identifierSchema).min(2).max(256) }),
@@ -106,6 +130,23 @@ export const canonicalTraceJson = (value: unknown): string => {
return serialized;
};
+/** Remove only explicitly declared schedule metadata before exact matching. */
+export const comparableTracePayload = (
+ value: unknown,
+ ignoredFields: readonly string[] = [],
+): unknown => {
+ if (
+ ignoredFields.length === 0 ||
+ typeof value !== "object" ||
+ value === null ||
+ Array.isArray(value)
+ )
+ return value;
+ return Object.fromEntries(
+ Object.entries(value).filter(([name]) => !ignoredFields.includes(name)),
+ );
+};
+
export const processTraceCardinalityBounds = (
cardinality: ProcessTraceSpecification["events"][number]["cardinality"],
): readonly [number, number] => {
@@ -156,6 +197,18 @@ const buildAdjacency = (
});
adjacency.get(edge.before)?.add(edge.after);
}
+ for (const [index, constraint] of language.not_before.entries()) {
+ const path = ["language", "not_before", index];
+ addReferenceIssue(context, known, constraint.event, [...path, "event"]);
+ addReferenceIssue(context, known, constraint.anchor, [...path, "anchor"]);
+ if (constraint.event === constraint.anchor)
+ context.addIssue({
+ code: "custom",
+ message: "not-before constraints must reference distinct events",
+ path,
+ });
+ adjacency.get(constraint.anchor)?.add(constraint.event);
+ }
return adjacency;
};
@@ -274,7 +327,7 @@ const validatePartialOrder = (
context.addIssue({
code: "custom",
message: "happens-before graph must be acyclic",
- path: ["language", "happens_before"],
+ path: ["language"],
});
const reachable = computeReachability(ids, adjacency);
const unorderedPairs = validateUnorderedGroups(
@@ -309,6 +362,7 @@ const validateFiniteTraces = (
if (specification.language.kind !== "finite_traces") return;
const known = new Set(specification.events.map(({ id }) => id));
const variantIds = new Set<string>();
+ const variantTraces = new Set<string>();
for (const [
variantIndex,
variant,
@@ -321,6 +375,14 @@ const validateFiniteTraces = (
path: [...variantPath, "id"],
});
variantIds.add(variant.id);
+ const canonicalTrace = canonicalTraceJson(variant.trace);
+ if (variantTraces.has(canonicalTrace))
+ context.addIssue({
+ code: "custom",
+ message: "finite trace variants must not duplicate a trace",
+ path: [...variantPath, "trace"],
+ });
+ variantTraces.add(canonicalTrace);
for (const [tokenIndex, token] of variant.trace.entries()) {
const values = typeof token === "string" ? [token] : token.unordered;
for (const [eventIndex, id] of values.entries())
@@ -352,6 +414,7 @@ export const processTraceSpecificationSchema =
specificationShapeSchema.superRefine((specification, context) => {
const ids = new Set<string>();
const predicates = new Set<string>();
+ const ignoredFieldsBySource = new Map<string, string>();
for (const [index, event] of specification.events.entries()) {
if (ids.has(event.id))
context.addIssue({
@@ -360,7 +423,45 @@ export const processTraceSpecificationSchema =
path: ["events", index, "id"],
});
ids.add(event.id);
- const predicate = `${event.source}\0${canonicalTraceJson(event.exact)}`;
+ const ignoredFields = [...(event.ignore_fields ?? [])].sort();
+ if (
+ ignoredFields.length > 0 &&
+ (typeof event.exact !== "object" ||
+ event.exact === null ||
+ Array.isArray(event.exact))
+ )
+ context.addIssue({
+ code: "custom",
+ message: "ignored schedule fields require an exact object payload",
+ path: ["events", index, "ignore_fields"],
+ });
+ const ignoredKey = canonicalTraceJson(ignoredFields);
+ const priorIgnoredKey = ignoredFieldsBySource.get(event.source);
+ if (priorIgnoredKey !== undefined && priorIgnoredKey !== ignoredKey)
+ context.addIssue({
+ code: "custom",
+ message:
+ "events from one source must use the same ignored schedule fields",
+ path: ["events", index, "ignore_fields"],
+ });
+ ignoredFieldsBySource.set(event.source, ignoredKey);
+ if (
+ ignoredFields.some(
+ (field) =>
+ typeof event.exact === "object" &&
+ event.exact !== null &&
+ !Array.isArray(event.exact) &&
+ field in event.exact,
+ )
+ )
+ context.addIssue({
+ code: "custom",
+ message: "exact payload must omit every ignored schedule field",
+ path: ["events", index, "exact"],
+ });
+ const predicate = `${event.source}\0${canonicalTraceJson(
+ comparableTracePayload(event.exact, ignoredFields),
+ )}`;
if (predicates.has(predicate))
context.addIssue({
code: "custom",
diff --git a/src/domain/reconstructionVerification.ts b/src/domain/reconstructionVerification.ts
index 187b5dd61..78795812f 100644
--- a/src/domain/reconstructionVerification.ts
+++ b/src/domain/reconstructionVerification.ts
@@ -46,24 +46,29 @@ const MAX_CANONICAL_BYTES = 32 * 1024 * 1024;
const providers = {
behavioral: {
operation: "compare_process_captures",
- predicate: "rea.process-comparison/v3",
+ predicates: ["rea.process-comparison/v3", "rea.process-comparison/v4"],
id: "rea-process",
name: "REA deterministic process harness",
},
"structural-function": {
operation: "compare_functions",
- predicate: "rea.function-comparison/v1",
+ predicates: ["rea.function-comparison/v1"],
id: "rea-function-comparison",
name: "REA function comparison",
},
"structural-artifact": {
operation: "compare_artifacts",
- predicate: "rea.artifact-comparison/v1",
+ predicates: ["rea.artifact-comparison/v1"],
id: "rea-artifact-comparison",
name: "REA artifact comparison",
},
} as const;
+const acceptsPredicate = (
+ expected: readonly string[],
+ actual: string,
+): boolean => expected.some((predicate) => predicate === actual);
+
/** Verify only explicitly declared claims; no global equivalence is inferred. */
export const verifyReconstruction = (
specificationInput: unknown,
@@ -229,7 +234,7 @@ const validateComparisonIdentity = (claim: Claim, evidence: Evidence): void => {
const expected = providers[claim.kind];
if (
evidence.operation !== expected.operation ||
- evidence.predicate_type !== expected.predicate ||
+ !acceptsPredicate(expected.predicates, evidence.predicate_type) ||
evidence.provider.id !== expected.id ||
evidence.provider.name !== expected.name ||
evidence.provider.version !== (claim.kind === "behavioral" ? "3" : "1") ||
diff --git a/src/domain/staticRuntimeCorrelation.ts b/src/domain/staticRuntimeCorrelation.ts
index 6db63416f..123c1c007 100644
--- a/src/domain/staticRuntimeCorrelation.ts
+++ b/src/domain/staticRuntimeCorrelation.ts
@@ -160,7 +160,7 @@ const EXPECTED = {
"REA function comparison",
],
compare_process_captures: [
- "rea.process-comparison/v3",
+ ["rea.process-comparison/v3", "rea.process-comparison/v4"],
"rea-process",
"REA deterministic process harness",
],
@@ -405,7 +405,9 @@ const assertComparisonIdentity = (evidence: Evidence): void => {
const expected = EXPECTED[evidence.operation as keyof typeof EXPECTED];
if (
expected === undefined ||
- evidence.predicate_type !== expected[0] ||
+ !(Array.isArray(expected[0])
+ ? expected[0].includes(evidence.predicate_type)
+ : evidence.predicate_type === expected[0]) ||
evidence.provider.id !== expected[1] ||
evidence.provider.name !== expected[2] ||
evidence.provider.version !==
diff --git a/src/server/registerProcessComparisonTool.ts b/src/server/registerProcessComparisonTool.ts
index 848981a1a..951f7ee4e 100644
--- a/src/server/registerProcessComparisonTool.ts
+++ b/src/server/registerProcessComparisonTool.ts
@@ -5,7 +5,7 @@ import {
processComparisonInputSchema,
SESSION_TOOL_CONTRACTS,
} from "../contracts/toolContracts.js";
-import { createEvidence } from "../domain/evidence.js";
+import { createEvidence, type EvidenceLocation } from "../domain/evidence.js";
import { EvidenceIntegrityError } from "../domain/errors.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import type { RecordUnknownInput } from "../domain/residualUnknown.js";
@@ -22,6 +22,16 @@ import { runDerivedOperation } from "./runDerivedOperation.js";
import { safeParseToolInput } from "./toolInputValidation.js";
import { resolveSessionEvidenceIds } from "./sessionEvidence.js";
+const PROCESS_CAPTURE_EVIDENCE = {
+ operation: "capture_process_scenario",
+ predicate: "rea.process-capture/v4",
+} as const;
+
+const sourceLocations = (
+ left: readonly EvidenceLocation[] | undefined,
+ right: readonly EvidenceLocation[] | undefined,
+): readonly EvidenceLocation[] => [...(left ?? []), ...(right ?? [])];
+
/** Register deterministic process-capture comparison and contradiction tracking. */
export const registerProcessComparisonTool = (
server: McpServer,
@@ -40,20 +50,16 @@ export const registerProcessComparisonTool = (
);
if (!parsedInput.ok) return toCallToolResult(parsedInput, contract);
const parsed = parsedInput.value;
- const expected = {
- operation: "capture_process_scenario",
- predicate: "rea.process-capture/v4",
- };
const leftRecord = resolveSessionEvidenceIds(
session,
[parsed.left_evidence_id],
- expected,
+ PROCESS_CAPTURE_EVIDENCE,
);
if (!leftRecord.ok) return toCallToolResult(leftRecord, contract);
const rightRecord = resolveSessionEvidenceIds(
session,
[parsed.right_evidence_id],
- expected,
+ PROCESS_CAPTURE_EVIDENCE,
);
if (!rightRecord.ok) return toCallToolResult(rightRecord, contract);
let comparison: ReturnType<typeof compareProcessCaptures>;
@@ -71,6 +77,9 @@ export const registerProcessComparisonTool = (
...(parsed.max_capture_age_ms === undefined
? {}
: { maxCaptureAgeMs: parsed.max_capture_age_ms }),
+ ...(parsed.trace_spec === undefined
+ ? {}
+ : { traceSpecification: parsed.trace_spec }),
now,
}),
);
@@ -89,18 +98,28 @@ export const registerProcessComparisonTool = (
);
}
const evidence = createEvidence(undefined, PROCESS_PROVIDER, {
- predicateType: "rea.process-comparison/v3",
+ predicateType:
+ parsed.trace_spec === undefined
+ ? "rea.process-comparison/v3"
+ : "rea.process-comparison/v4",
operation: contract.name,
parameters: {
left_evidence_id: parsed.left_evidence_id,
right_evidence_id: parsed.right_evidence_id,
left_normalization: leftCapture.normalization,
right_normalization: rightCapture.normalization,
+ ...(parsed.trace_spec === undefined
+ ? {}
+ : { trace_spec: jsonValueSchema.parse(parsed.trace_spec) }),
},
result: jsonValueSchema.parse(comparison),
confidence: "derived",
authority: "analyst-inference",
limitations: comparison.limitations,
+ locations: sourceLocations(
+ leftRecord.value[0]?.locations,
+ rightRecord.value[0]?.locations,
+ ),
evidenceLinks: [parsed.left_evidence_id, parsed.right_evidence_id],
});
return toCallToolResult(
diff --git a/tests/changedBehavior.test.ts b/tests/changedBehavior.test.ts
index 8a41aa4e4..00776c3e3 100644
--- a/tests/changedBehavior.test.ts
+++ b/tests/changedBehavior.test.ts
@@ -24,6 +24,7 @@ const right = source("2");
const comparison = (
operation: "compare_process_captures" | "compare_artifacts",
result: JsonValue,
+ processPredicateVersion: "v3" | "v4" = "v3",
): Evidence => {
const process = operation === "compare_process_captures";
return createEvidence(
@@ -37,7 +38,7 @@ const comparison = (
},
{
predicateType: process
- ? "rea.process-comparison/v3"
+ ? `rea.process-comparison/${processPredicateVersion}`
: "rea.artifact-comparison/v1",
operation,
parameters: {},
@@ -123,6 +124,15 @@ const artifactResult = (
});
describe("changed behavior", () => {
+ it("accepts declared-trace process comparison Evidence v4", () => {
+ const result = findChangedBehavior(
+ [comparison("compare_process_captures", processResult(), "v4")],
+ 0,
+ 100,
+ );
+ expect(result.behavior_status).toBe("observed_unchanged");
+ });
+
it("reports interaction and shim-only process changes", () => {
const evidence = comparison(
"compare_process_captures",
diff --git a/tests/processTraceAdapters.test.ts b/tests/processTraceAdapters.test.ts
new file mode 100644
index 000000000..019ea8335
--- /dev/null
+++ b/tests/processTraceAdapters.test.ts
@@ -0,0 +1,361 @@
+import { rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { BinarySession } from "../src/application/BinarySession.js";
+import type { AnalysisClient } from "../src/application/AnalysisProvider.js";
+import { compareProcessEvidenceFiles } from "../src/application/ProcessCli.js";
+import { PROCESS_PROVIDER } from "../src/application/ProcessEvidence.js";
+import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../src/contracts/processCaptureExample.js";
+import { createEvidence, parseEvidence } from "../src/domain/evidence.js";
+import { jsonValueSchema } from "../src/domain/jsonValue.js";
+import {
+ compareProcessCaptures,
+ processCaptureSchema,
+} from "../src/domain/processCapture.js";
+import type { ProcessTraceSpecification } from "../src/domain/processTraceComparison.js";
+import { observed as ok } from "./fixtures/analysisExecution.js";
+import { createTestTempDirectory } from "./fixtures/temporaryDirectory.js";
+import { createServer } from "../src/server/createServer.js";
+
+const resources: Array<{ close(): Promise<void> }> = [];
+const temporaryRoots: string[] = [];
+const beforeCheckpoint = {
+ name: "before",
+ at_ms: 0,
+ files: [],
+ effects: [],
+ truncated: false,
+};
+const afterCheckpoint = {
+ name: "after_settlement",
+ at_ms: 50,
+ files: [],
+ effects: [],
+ truncated: false,
+};
+
+afterEach(async () => {
+ await Promise.all(resources.splice(0).map((resource) => resource.close()));
+ await Promise.all(
+ temporaryRoots
+ .splice(0)
+ .map((root) => rm(root, { recursive: true, force: true })),
+ );
+});
+
+const capture = {
+ ...EMPTY_PROCESS_CAPTURE_EXAMPLE,
+ event_journal: [
+ { capture_order: 0, collection: "filesystem_checkpoints", index: 0 },
+ { capture_order: 1, collection: "lifecycle", index: 0 },
+ { capture_order: 2, collection: "lifecycle", index: 1 },
+ { capture_order: 3, collection: "filesystem_checkpoints", index: 1 },
+ ],
+} as const;
+
+const traceSpecification: ProcessTraceSpecification = {
+ version: 1,
+ events: [
+ {
+ id: "before",
+ source: "filesystem",
+ exact: beforeCheckpoint,
+ cardinality: { kind: "required" },
+ },
+ {
+ id: "exit",
+ source: "lifecycle",
+ exact: { event: "exit", ...capture.exit },
+ cardinality: { kind: "required" },
+ },
+ {
+ id: "settlement",
+ source: "lifecycle",
+ exact: { event: "settlement", ...capture.settlement },
+ cardinality: { kind: "required" },
+ },
+ {
+ id: "after",
+ source: "filesystem",
+ exact: afterCheckpoint,
+ cardinality: { kind: "required" },
+ },
+ ],
+ language: {
+ kind: "finite_traces",
+ variants: [
+ {
+ id: "normal",
+ trace: ["before", "exit", "settlement", "after"],
+ },
+ ],
+ },
+};
+
+const captureEvidence = (side: "left" | "right") =>
+ createEvidence(undefined, PROCESS_PROVIDER, {
+ predicateType: "rea.process-capture/v4",
+ operation: "capture_process_scenario",
+ parameters: { side },
+ result: jsonValueSchema.parse(capture),
+ confidence: "observed",
+ authority: "controlled-replay",
+ locations: [{ kind: "artifact-path", path: `/fixture/${side}` }],
+ });
+
+describe("declared trace comparison adapters", () => {
+ it("treats only explicitly ignored schedule metadata as reorderable", () => {
+ const httpPayload = {
+ protocol: "http" as const,
+ direction: "request" as const,
+ method: "GET",
+ path: "/status",
+ data: "",
+ outcome: "unmatched" as const,
+ };
+ const websocketPayload = {
+ protocol: "websocket" as const,
+ direction: "received" as const,
+ method: null,
+ path: "/ws",
+ data: "done",
+ outcome: "matched" as const,
+ };
+ const scheduledCapture = (order: "http-first" | "websocket-first") => {
+ const protocolEvents =
+ order === "http-first"
+ ? [
+ { sequence: 0, at_ms: 1, ...httpPayload },
+ { sequence: 1, at_ms: 2, ...websocketPayload },
+ ]
+ : [
+ { sequence: 0, at_ms: 1, ...websocketPayload },
+ { sequence: 1, at_ms: 2, ...httpPayload },
+ ];
+ return processCaptureSchema.parse({
+ ...capture,
+ protocol_events: protocolEvents,
+ event_journal: [
+ {
+ capture_order: 0,
+ collection: "filesystem_checkpoints",
+ index: 0,
+ },
+ { capture_order: 1, collection: "protocol_events", index: 0 },
+ { capture_order: 2, collection: "protocol_events", index: 1 },
+ { capture_order: 3, collection: "lifecycle", index: 0 },
+ { capture_order: 4, collection: "lifecycle", index: 1 },
+ {
+ capture_order: 5,
+ collection: "filesystem_checkpoints",
+ index: 1,
+ },
+ ],
+ });
+ };
+ const specification: ProcessTraceSpecification = {
+ version: 1,
+ events: [
+ {
+ id: "status",
+ source: "http",
+ exact: httpPayload,
+ ignore_fields: ["sequence", "at_ms"],
+ cardinality: { kind: "required" },
+ },
+ {
+ id: "done",
+ source: "websocket",
+ exact: websocketPayload,
+ ignore_fields: ["sequence", "at_ms"],
+ cardinality: { kind: "required" },
+ },
+ ],
+ language: {
+ kind: "partial_order",
+ happens_before: [],
+ not_before: [],
+ unordered_groups: [{ events: ["status", "done"] }],
+ prefix: [],
+ suffix: [],
+ },
+ };
+
+ expect(
+ compareProcessCaptures(
+ scheduledCapture("http-first"),
+ scheduledCapture("websocket-first"),
+ { traceSpecification: specification },
+ ),
+ ).toMatchObject({
+ status: "unchanged",
+ protocol: "unchanged",
+ trace: {
+ verdict: "equivalent",
+ left: { raw_trace: [{ event_id: "status" }, { event_id: "done" }] },
+ right: { raw_trace: [{ event_id: "done" }, { event_id: "status" }] },
+ },
+ });
+ });
+
+ it("does not mask an unselected source in a covered legacy dimension", () => {
+ const http = {
+ sequence: 0,
+ at_ms: 1,
+ protocol: "http" as const,
+ direction: "request" as const,
+ method: "GET",
+ path: "/status",
+ data: "",
+ outcome: "unmatched" as const,
+ };
+ const websocket = (data: string) => ({
+ sequence: 1,
+ at_ms: 2,
+ protocol: "websocket" as const,
+ direction: "received" as const,
+ method: null,
+ path: "/ws",
+ data,
+ outcome: "matched" as const,
+ });
+ const withProtocol = (data: string) =>
+ processCaptureSchema.parse({
+ ...capture,
+ protocol_events: [http, websocket(data)],
+ event_journal: [
+ {
+ capture_order: 0,
+ collection: "filesystem_checkpoints",
+ index: 0,
+ },
+ { capture_order: 1, collection: "protocol_events", index: 0 },
+ { capture_order: 2, collection: "protocol_events", index: 1 },
+ { capture_order: 3, collection: "lifecycle", index: 0 },
+ { capture_order: 4, collection: "lifecycle", index: 1 },
+ {
+ capture_order: 5,
+ collection: "filesystem_checkpoints",
+ index: 1,
+ },
+ ],
+ });
+ const specification: ProcessTraceSpecification = {
+ version: 1,
+ events: [
+ {
+ id: "status",
+ source: "http",
+ exact: http,
+ cardinality: { kind: "required" },
+ },
+ ],
+ language: {
+ kind: "finite_traces",
+ variants: [{ id: "status", trace: ["status"] }],
+ },
+ };
+
+ expect(
+ compareProcessCaptures(withProtocol("left"), withProtocol("right"), {
+ traceSpecification: specification,
+ }),
+ ).toMatchObject({
+ status: "changed",
+ protocol: "changed",
+ trace: { verdict: "equivalent" },
+ });
+ });
+
+ it("does not call identical captures changed when both violate the language", () => {
+ const parsedCapture = processCaptureSchema.parse(capture);
+ const specification: ProcessTraceSpecification = {
+ ...traceSpecification,
+ language: {
+ kind: "finite_traces",
+ variants: [
+ {
+ id: "reversed",
+ trace: ["after", "settlement", "exit", "before"],
+ },
+ ],
+ },
+ };
+
+ expect(
+ compareProcessCaptures(parsedCapture, parsedCapture, {
+ traceSpecification: specification,
+ }),
+ ).toMatchObject({
+ status: "unchanged",
+ trace: { verdict: "different" },
+ });
+ });
+
+ it("returns identical CLI and MCP results and derived Evidence identity", async () => {
+ const left = captureEvidence("left");
+ const right = captureEvidence("right");
+ const root = await createTestTempDirectory("rea-trace-adapters-");
+ temporaryRoots.push(root);
+ const leftPath = join(root, "left.json");
+ const rightPath = join(root, "right.json");
+ const specificationPath = join(root, "trace.json");
+ await Promise.all([
+ writeFile(leftPath, JSON.stringify(left)),
+ writeFile(rightPath, JSON.stringify(right)),
+ writeFile(specificationPath, JSON.stringify(traceSpecification)),
+ ]);
+ const cliEvidence = parseEvidence(
+ await compareProcessEvidenceFiles(leftPath, rightPath, specificationPath),
+ );
+
+ const session = new BinarySession(
+ (_path) =>
+ ({
+ execute: () => Promise.resolve(ok(null)),
+ close: () => Promise.resolve(),
+ }) satisfies AnalysisClient,
+ );
+ expect(session.recordEvidence(left).ok).toBe(true);
+ expect(session.recordEvidence(right).ok).toBe(true);
+ const server = createServer(
+ { execute: () => Promise.resolve(ok(null)) },
+ session,
+ );
+ const client = new Client({ name: "trace-parity", version: "1" });
+ const [clientTransport, serverTransport] =
+ InMemoryTransport.createLinkedPair();
+ resources.push(client, server);
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+
+ const response = await client.callTool({
+ name: "compare_process_captures",
+ arguments: {
+ left_evidence_id: left.evidence_id,
+ right_evidence_id: right.evidence_id,
+ trace_spec: traceSpecification,
+ },
+ });
+ expect(response.isError).not.toBe(true);
+ expect(response.structuredContent).toMatchObject({
+ result: { trace: { verdict: "equivalent" } },
+ evidence_id: cliEvidence.evidence_id,
+ });
+ const structuredResult =
+ typeof response.structuredContent === "object" &&
+ response.structuredContent !== null
+ ? Reflect.get(response.structuredContent, "result")
+ : undefined;
+ expect(structuredResult).toEqual(cliEvidence.normalized_result);
+ expect(cliEvidence).toMatchObject({
+ predicate_type: "rea.process-comparison/v4",
+ locations: [
+ { kind: "artifact-path", path: "/fixture/left" },
+ { kind: "artifact-path", path: "/fixture/right" },
+ ],
+ });
+ });
+});
diff --git a/tests/processTraceComparison.test.ts b/tests/processTraceComparison.test.ts
new file mode 100644
index 000000000..8099e0d78
--- /dev/null
+++ b/tests/processTraceComparison.test.ts
@@ -0,0 +1,451 @@
+import { describe, expect, it } from "vitest";
+
+import type { ProcessCapture } from "../src/domain/processCapture.js";
+import {
+ compareProcessTraces,
+ processTraceSpecificationSchema,
+ type ProcessTraceSpecification,
+} from "../src/domain/processTraceComparison.js";
+
+const capture = (
+ values: Pick<
+ ProcessCapture,
+ | "frames"
+ | "process_samples"
+ | "filesystem_checkpoints"
+ | "protocol_events"
+ | "shim_events"
+ > & {
+ readonly event_journal: NonNullable<ProcessCapture["event_journal"]>;
+ },
+ options: {
+ readonly truncated?: boolean;
+ readonly residualUnknowns?: ProcessCapture["residual_unknowns"];
+ } = {},
+): ProcessCapture => ({
+ schema_version: 4,
+ manifest: {
+ rea_version: "test",
+ provider_version: "3",
+ platform: "linux",
+ architecture: "x64",
+ pty_backend: "node-pty",
+ started_at: "2026-01-01T00:00:00.000Z",
+ completed_at: "2026-01-01T00:00:01.000Z",
+ scenario: {},
+ comparison_contract: {},
+ shim_plan: [],
+ replay_plan: {},
+ full_scenario_sha256: "0".repeat(64),
+ comparison_contract_sha256: "1".repeat(64),
+ executable_sha256: "2".repeat(64),
+ normalization_sha256: "3".repeat(64),
+ shim_plan_sha256: "4".repeat(64),
+ replay_plan_sha256: "5".repeat(64),
+ },
+ normalization: {
+ paths: true,
+ pids: true,
+ ports: true,
+ time_bucket_ms: 10,
+ patterns: [],
+ },
+ frames: values.frames,
+ rendered_frames: [],
+ interaction_events: [],
+ exit: { code: 0, signal: null, reason: "exited" },
+ settlement: {
+ state: "quiesced",
+ elapsed_ms: 10,
+ cleanup_outcome: "not_required",
+ },
+ process_samples: values.process_samples,
+ filesystem_checkpoints: values.filesystem_checkpoints,
+ shim_events: values.shim_events,
+ protocol_events: values.protocol_events,
+ replay_transitions: [],
+ event_journal: values.event_journal,
+ files_before: [],
+ files_after: [],
+ filesystem_effects: [],
+ truncated: options.truncated ?? false,
+ limitations: [],
+ residual_unknowns: options.residualUnknowns ?? [],
+ cleanup: {
+ owned_process_group: "verified",
+ temporary_root: "removed",
+ },
+});
+
+const terminal = { sequence: 0, at_ms: 900, data: "Ready" };
+const processStarted = {
+ at_ms: 1,
+ pid: 1,
+ parent_pid: 0,
+ command: "worker",
+ process_group_id: 1,
+ session_id: 1,
+};
+const http = {
+ sequence: 0,
+ at_ms: 2,
+ protocol: "http" as const,
+ direction: "request" as const,
+ method: "GET",
+ path: "/status",
+ data: "",
+ outcome: "matched" as const,
+};
+const websocket = {
+ sequence: 1,
+ at_ms: 3,
+ protocol: "websocket" as const,
+ direction: "received" as const,
+ method: null,
+ path: "/ws",
+ data: "done",
+ outcome: "matched" as const,
+};
+
+const values = (
+ order: readonly ("terminal" | "process" | "http" | "websocket")[],
+): Parameters<typeof capture>[0] => ({
+ frames: [terminal],
+ process_samples: [processStarted],
+ filesystem_checkpoints: [],
+ protocol_events: [http, websocket],
+ shim_events: [],
+ event_journal: order.map((event, captureOrder) => ({
+ capture_order: captureOrder,
+ collection:
+ event === "terminal"
+ ? "frames"
+ : event === "process"
+ ? "process_samples"
+ : "protocol_events",
+ index: event === "websocket" ? 1 : 0,
+ })),
+});
+
+const partialSpecification = (): ProcessTraceSpecification => ({
+ version: 1,
+ events: [
+ {
+ id: "ready",
+ source: "terminal_raw",
+ exact: terminal,
+ cardinality: { kind: "required" },
+ },
+ {
+ id: "worker",
+ source: "process",
+ exact: processStarted,
+ cardinality: { kind: "required" },
+ },
+ {
+ id: "status",
+ source: "http",
+ exact: http,
+ cardinality: { kind: "required" },
+ },
+ {
+ id: "done",
+ source: "websocket",
+ exact: websocket,
+ cardinality: { kind: "required" },
+ },
+ ],
+ language: {
+ kind: "partial_order",
+ happens_before: [
+ { before: "ready", after: "worker" },
+ { before: "ready", after: "status" },
+ { before: "worker", after: "done" },
+ { before: "status", after: "done" },
+ ],
+ not_before: [{ event: "done", anchor: "ready" }],
+ unordered_groups: [{ events: ["worker", "status"] }],
+ prefix: ["ready"],
+ suffix: ["done"],
+ },
+});
+
+describe("process trace specification", () => {
+ it("rejects cycles, implicit concurrency, overlap, and unsatisfiable variants", () => {
+ const base = partialSpecification();
+ expect(
+ processTraceSpecificationSchema.safeParse({
+ ...base,
+ language: {
+ kind: "partial_order",
+ happens_before: [
+ { before: "ready", after: "worker" },
+ { before: "worker", after: "ready" },
+ ],
+ unordered_groups: [{ events: ["status", "done"] }],
+ },
+ }).success,
+ ).toBe(false);
+ expect(
+ processTraceSpecificationSchema.safeParse({
+ version: 1,
+ events: [
+ {
+ id: "invalid-ignore",
+ source: "terminal_raw",
+ exact: "ready",
+ ignore_fields: ["at_ms"],
+ },
+ ],
+ language: {
+ kind: "finite_traces",
+ variants: [{ id: "one", trace: ["invalid-ignore"] }],
+ },
+ }).success,
+ ).toBe(false);
+ expect(
+ processTraceSpecificationSchema.safeParse({
+ version: 1,
+ events: [
+ {
+ id: "invalid-ignore",
+ source: "terminal_raw",
+ exact: terminal,
+ ignore_fields: ["at_ms"],
+ },
+ ],
+ language: {
+ kind: "finite_traces",
+ variants: [{ id: "one", trace: ["invalid-ignore"] }],
+ },
+ }).success,
+ ).toBe(false);
+ expect(
+ processTraceSpecificationSchema.safeParse({
+ version: 1,
+ events: base.events.slice(0, 2),
+ language: { kind: "partial_order" },
+ }).success,
+ ).toBe(false);
+ expect(
+ processTraceSpecificationSchema.safeParse({
+ version: 1,
+ events: [base.events[0], { ...base.events[0], id: "duplicate" }],
+ language: {
+ kind: "partial_order",
+ unordered_groups: [{ events: ["ready", "duplicate"] }],
+ },
+ }).success,
+ ).toBe(false);
+ expect(
+ processTraceSpecificationSchema.safeParse({
+ version: 1,
+ events: [
+ {
+ ...base.events[0],
+ cardinality: { kind: "exact", count: 2 },
+ },
+ ],
+ language: {
+ kind: "finite_traces",
+ variants: [{ id: "once", trace: ["ready"] }],
+ },
+ }).success,
+ ).toBe(false);
+ expect(
+ processTraceSpecificationSchema.safeParse({
+ version: 1,
+ events: [base.events[0]],
+ language: {
+ kind: "finite_traces",
+ variants: [
+ { id: "first", trace: ["ready"] },
+ { id: "duplicate", trace: ["ready"] },
+ ],
+ },
+ }).success,
+ ).toBe(false);
+ });
+});
+
+describe("process trace comparison", () => {
+ it("accepts only explicitly declared concurrent schedules without timestamp causality", () => {
+ const left = capture(values(["terminal", "process", "http", "websocket"]));
+ const right = capture(values(["terminal", "http", "process", "websocket"]));
+ const comparison = compareProcessTraces(
+ left,
+ right,
+ partialSpecification(),
+ );
+
+ expect(comparison.verdict).toBe("equivalent");
+ expect(comparison.left.raw_trace.map(({ event_id }) => event_id)).toEqual([
+ "ready",
+ "worker",
+ "status",
+ "done",
+ ]);
+ expect(comparison.right.raw_trace.map(({ event_id }) => event_id)).toEqual([
+ "ready",
+ "status",
+ "worker",
+ "done",
+ ]);
+ expect(comparison.left.satisfied_constraints).toContain(
+ "unordered:worker:status",
+ );
+ });
+
+ it("returns the minimal journal slice for a reversed required edge", () => {
+ const baseline = capture(
+ values(["terminal", "process", "http", "websocket"]),
+ );
+ const reversed = capture(
+ values(["process", "terminal", "http", "websocket"]),
+ );
+ const comparison = compareProcessTraces(
+ baseline,
+ reversed,
+ partialSpecification(),
+ );
+
+ expect(comparison).toMatchObject({
+ verdict: "different",
+ diagnostic: {
+ kind: "edge",
+ side: "right",
+ event_ids: ["ready", "worker"],
+ locations: [{ capture_order: 1 }, { capture_order: 0 }],
+ },
+ });
+ });
+
+ it("enforces explicit negative not-before constraints", () => {
+ const specification: ProcessTraceSpecification = {
+ version: 1,
+ events: [
+ {
+ id: "ready",
+ source: "terminal_raw",
+ exact: terminal,
+ cardinality: { kind: "required" },
+ },
+ {
+ id: "done",
+ source: "websocket",
+ exact: websocket,
+ cardinality: { kind: "required" },
+ },
+ ],
+ language: {
+ kind: "partial_order",
+ happens_before: [],
+ not_before: [{ event: "done", anchor: "ready" }],
+ unordered_groups: [],
+ prefix: [],
+ suffix: [],
+ },
+ };
+ const normal = capture(
+ values(["terminal", "process", "http", "websocket"]),
+ );
+ const invalid = capture(
+ values(["websocket", "terminal", "process", "http"]),
+ );
+
+ expect(compareProcessTraces(normal, invalid, specification)).toMatchObject({
+ verdict: "different",
+ diagnostic: {
+ kind: "edge",
+ side: "right",
+ event_ids: ["done", "ready"],
+ },
+ });
+ });
+
+ it("supports declared optional events and bounded duplicates", () => {
+ const first = { sequence: 0, at_ms: 1, data: "tick" };
+ const second = { sequence: 1, at_ms: 2, data: "tick" };
+ const one = capture({
+ frames: [first],
+ process_samples: [],
+ filesystem_checkpoints: [],
+ protocol_events: [],
+ shim_events: [],
+ event_journal: [{ capture_order: 0, collection: "frames", index: 0 }],
+ });
+ const two = capture({
+ frames: [first, second],
+ process_samples: [],
+ filesystem_checkpoints: [],
+ protocol_events: [],
+ shim_events: [],
+ event_journal: [
+ { capture_order: 0, collection: "frames", index: 0 },
+ { capture_order: 1, collection: "frames", index: 1 },
+ ],
+ });
+ const specification: ProcessTraceSpecification = {
+ version: 1,
+ events: [
+ {
+ id: "tick1",
+ source: "terminal_raw",
+ exact: first,
+ cardinality: { kind: "required" },
+ },
+ {
+ id: "tick2",
+ source: "terminal_raw",
+ exact: second,
+ cardinality: { kind: "optional" },
+ },
+ ],
+ language: {
+ kind: "finite_traces",
+ variants: [
+ { id: "one", trace: ["tick1"] },
+ { id: "two", trace: ["tick1", "tick2"] },
+ ],
+ },
+ };
+
+ expect(compareProcessTraces(one, two, specification)).toMatchObject({
+ verdict: "equivalent",
+ left: { matched_variant: "one" },
+ right: { matched_variant: "two" },
+ });
+ });
+
+ it("never proves equivalence from truncated, unknown, or journal-free evidence", () => {
+ const complete = capture(
+ values(["terminal", "process", "http", "websocket"]),
+ );
+ const truncated = capture(
+ values(["terminal", "process", "http", "websocket"]),
+ { truncated: true },
+ );
+ expect(
+ compareProcessTraces(complete, truncated, partialSpecification()).verdict,
+ ).toBe("unknown");
+
+ const unknown = capture(
+ values(["terminal", "process", "http", "websocket"]),
+ { residualUnknowns: [{ scope: "protocol", reason: "gap" }] },
+ );
+ expect(
+ compareProcessTraces(complete, unknown, partialSpecification()).verdict,
+ ).toBe("unknown");
+
+ const noJournal = capture({ ...values([]), event_journal: [] });
+ const comparison = compareProcessTraces(
+ complete,
+ noJournal,
+ partialSpecification(),
+ );
+ expect(comparison).toMatchObject({
+ verdict: "unknown",
+ diagnostic: { kind: "journal", side: "right" },
+ });
+ });
+});