From d81745cb95b1564b94bf260d4f737d03b4625849 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Wed, 22 Jul 2026 20:48:34 +0000 Subject: [PATCH] feat(process): compare declared concurrent traces --- docs/process-capture.md | 41 ++ docs/product-catalog.json | 4 +- .../managed-conformance-manifest.json | 4 +- skills/reverse-engineer-anything/SKILL.md | 2 +- src/application/ProcessCli.ts | 35 +- src/cliProcessCommands.ts | 6 +- src/contracts/toolContracts.ts | 4 +- src/domain/changedBehavior.ts | 13 +- src/domain/processComparison.ts | 86 +--- src/domain/processTraceComparison.ts | 8 + src/domain/processTraceDimensionProjection.ts | 77 +++ src/domain/processTraceSpecification.ts | 105 +++- src/domain/reconstructionVerification.ts | 13 +- src/domain/staticRuntimeCorrelation.ts | 6 +- src/server/registerProcessComparisonTool.ts | 35 +- tests/changedBehavior.test.ts | 12 +- tests/processTraceAdapters.test.ts | 361 ++++++++++++++ tests/processTraceComparison.test.ts | 451 ++++++++++++++++++ 18 files changed, 1161 insertions(+), 102 deletions(-) create mode 100644 src/domain/processTraceDimensionProjection.ts create mode 100644 tests/processTraceAdapters.test.ts create mode 100644 tests/processTraceComparison.test.ts 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["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, -): 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, - left: ProcessCapture, - right: ProcessCapture, -): boolean => { - const any = ( - 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, 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, +): ReadonlySet => { + const dimensions = new Set(); + 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, + left: ProcessCapture, + right: ProcessCapture, +): boolean => { + const any = ( + 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(); + const variantTraces = new Set(); 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(); const predicates = new Set(); + const ignoredFieldsBySource = new Map(); 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; @@ -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 }> = []; +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; + }, + 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[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" }, + }); + }); +});