refactor(process): split trace comparison domain logic

This commit is contained in:
morluto
2026-07-23 05:27:49 +08:00
parent a32b988a35
commit 75d5a87054
3 changed files with 860 additions and 0 deletions
+53
View File
@@ -0,0 +1,53 @@
import type { ProcessCapture } from "./processCapture.js";
import {
evaluateProcessTraceSide,
processTraceComparisonResultSchema,
type ProcessTraceComparisonResult,
} from "./processTraceEvaluation.js";
import {
processTraceSpecificationSchema,
type ProcessTraceSpecification,
} from "./processTraceSpecification.js";
export {
processTraceComparisonResultSchema,
type ProcessTraceComparisonResult,
type ProcessTraceLocation,
} from "./processTraceEvaluation.js";
export {
processTraceSourceSchema,
processTraceSpecificationSchema,
type ProcessTraceSource,
type ProcessTraceSpecification,
} from "./processTraceSpecification.js";
/** Compare two captures against an explicit finite trace language. */
export const compareProcessTraces = (
left: ProcessCapture,
right: ProcessCapture,
specificationInput: ProcessTraceSpecification,
): ProcessTraceComparisonResult => {
const specification =
processTraceSpecificationSchema.parse(specificationInput);
const leftEvaluation = evaluateProcessTraceSide(left, specification);
const rightEvaluation = evaluateProcessTraceSide(right, specification);
const diagnostic =
leftEvaluation.diagnostic === null
? rightEvaluation.diagnostic === null
? null
: { side: "right" as const, ...rightEvaluation.diagnostic }
: { side: "left" as const, ...leftEvaluation.diagnostic };
return processTraceComparisonResultSchema.parse({
verdict:
leftEvaluation.result.status === "unknown" ||
rightEvaluation.result.status === "unknown"
? "unknown"
: leftEvaluation.result.status === "pass" &&
rightEvaluation.result.status === "pass"
? "equivalent"
: "different",
left: leftEvaluation.result,
right: rightEvaluation.result,
diagnostic,
});
};
+433
View File
@@ -0,0 +1,433 @@
import { z } from "zod";
import { jsonValueSchema, type JsonValue } from "./jsonValue.js";
import type { ProcessCapture } from "./processCapture.js";
import {
canonicalTraceJson,
processTraceCardinalityBounds,
type ProcessTraceSource,
type ProcessTraceSpecification,
} from "./processTraceSpecification.js";
const identifierSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._-]{0,63}$/u);
export type ProcessTraceLocation = {
readonly collection:
| "frames"
| "rendered_frames"
| "interaction_events"
| "lifecycle"
| "process_samples"
| "filesystem_checkpoints"
| "shim_events"
| "protocol_events"
| "replay_transitions";
readonly index: number;
readonly capture_order: number;
};
const locationSchema = z.strictObject({
collection: z.enum([
"frames",
"rendered_frames",
"interaction_events",
"lifecycle",
"process_samples",
"filesystem_checkpoints",
"shim_events",
"protocol_events",
"replay_transitions",
]),
index: z.number().int().nonnegative(),
capture_order: z.number().int().nonnegative(),
});
const matchedEventSchema = z.strictObject({
event_id: identifierSchema,
location: locationSchema,
});
const sideResultSchema = z.strictObject({
status: z.enum(["pass", "fail", "unknown"]),
matched_variant: identifierSchema.nullable(),
satisfied_constraints: z.array(z.string()),
raw_trace: z.array(matchedEventSchema),
});
const diagnosticSchema = z.strictObject({
kind: z.enum([
"journal",
"predicate",
"cardinality",
"edge",
"prefix",
"suffix",
"trace",
]),
side: z.enum(["left", "right"]),
message: z.string(),
event_ids: z.array(identifierSchema),
locations: z.array(locationSchema),
});
/** Structured verdict for one declared process trace language. */
export const processTraceComparisonResultSchema = z.strictObject({
verdict: z.enum(["equivalent", "different", "unknown"]),
left: sideResultSchema,
right: sideResultSchema,
diagnostic: diagnosticSchema.nullable(),
});
export type ProcessTraceComparisonResult = z.infer<
typeof processTraceComparisonResultSchema
>;
type TraceRecord = {
readonly source: ProcessTraceSource;
readonly payload: JsonValue;
readonly location: ProcessTraceLocation;
};
const recordAt = (
capture: ProcessCapture,
location: ProcessTraceLocation,
): Omit<TraceRecord, "location"> | null => {
const value = (() => {
switch (location.collection) {
case "frames":
return {
source: "terminal_raw" as const,
value: capture.frames[location.index],
};
case "rendered_frames":
return {
source: "terminal_rendered" as const,
value: capture.rendered_frames[location.index],
};
case "interaction_events":
return {
source: "interaction" as const,
value: capture.interaction_events[location.index],
};
case "lifecycle":
return location.index === 0
? {
source: "lifecycle" as const,
value: { event: "exit", ...capture.exit },
}
: location.index === 1
? {
source: "lifecycle" as const,
value: { event: "settlement", ...capture.settlement },
}
: null;
case "process_samples":
return {
source: "process" as const,
value: capture.process_samples[location.index],
};
case "filesystem_checkpoints":
return {
source: "filesystem" as const,
value: capture.filesystem_checkpoints[location.index],
};
case "shim_events":
return {
source: "shim" as const,
value: capture.shim_events[location.index],
};
case "protocol_events": {
const event = capture.protocol_events[location.index];
return event === undefined
? null
: { source: event.protocol, value: event };
}
case "replay_transitions":
return {
source: "replay_transition" as const,
value: capture.replay_transitions[location.index],
};
}
})();
if (value === null || value.value === undefined) return null;
return { source: value.source, payload: jsonValueSchema.parse(value.value) };
};
const scopesFor = (
sources: ReadonlySet<ProcessTraceSource>,
): ReadonlySet<string> =>
new Set(
[...sources].map((source) => {
if (source.startsWith("terminal_")) return "terminal";
if (source === "lifecycle") return "exit";
if (
source === "http" ||
source === "websocket" ||
source === "replay_transition"
)
return "protocol";
if (source === "filesystem") return "filesystem";
if (source === "process") return "process";
if (source === "shim") return "shim";
return "interaction";
}),
);
const unknownSide = (): z.infer<typeof sideResultSchema> => ({
status: "unknown",
matched_variant: null,
satisfied_constraints: [],
raw_trace: [],
});
export type EvaluatedSide = {
readonly result: z.infer<typeof sideResultSchema>;
readonly diagnostic: Omit<z.infer<typeof diagnosticSchema>, "side"> | null;
};
type FailureInput = {
readonly kind: z.infer<typeof diagnosticSchema>["kind"];
readonly message: string;
readonly eventIds: readonly string[];
readonly locations: readonly ProcessTraceLocation[];
readonly rawTrace: z.infer<typeof matchedEventSchema>[];
};
const failure = (input: FailureInput): EvaluatedSide => ({
result: {
status: "fail",
matched_variant: null,
satisfied_constraints: [],
raw_trace: input.rawTrace,
},
diagnostic: {
kind: input.kind,
message: input.message,
event_ids: [...input.eventIds],
locations: [...input.locations],
},
});
const evaluateFiniteTrace = (
ids: readonly string[],
specification: ProcessTraceSpecification,
): string | null => {
if (specification.language.kind !== "finite_traces") return null;
for (const variant of specification.language.variants) {
let offset = 0;
let accepted = true;
for (const token of variant.trace) {
if (typeof token === "string") {
if (ids[offset] !== token) accepted = false;
offset += 1;
continue;
}
const actual = ids.slice(offset, offset + token.unordered.length).sort();
const expected = [...token.unordered].sort();
if (canonicalTraceJson(actual) !== canonicalTraceJson(expected))
accepted = false;
offset += token.unordered.length;
}
if (accepted && offset === ids.length) return variant.id;
}
return null;
};
type MatchedTrace = {
readonly rawTrace: z.infer<typeof matchedEventSchema>[];
readonly locationsById: ReadonlyMap<string, ProcessTraceLocation[]>;
};
const collectRecords = (
capture: ProcessCapture,
sources: ReadonlySet<ProcessTraceSource>,
): readonly TraceRecord[] => {
const records: TraceRecord[] = [];
for (const location of capture.event_journal ?? []) {
const record = recordAt(capture, location);
if (record !== null && sources.has(record.source))
records.push({ ...record, location });
}
return records;
};
const matchRecords = (
records: readonly TraceRecord[],
specification: ProcessTraceSpecification,
): MatchedTrace | EvaluatedSide => {
const rawTrace: z.infer<typeof matchedEventSchema>[] = [];
const locationsById = new Map<string, ProcessTraceLocation[]>();
for (const record of records) {
const matches = specification.events.filter(
(event) =>
event.source === record.source &&
canonicalTraceJson(event.exact) === canonicalTraceJson(record.payload),
);
if (matches.length !== 1)
return failure({
kind: "predicate",
message:
matches.length === 0
? "Observed event does not match any declared exact predicate."
: "Observed event matches multiple predicates.",
eventIds: matches.map(({ id }) => id),
locations: [record.location],
rawTrace,
});
const match = matches[0];
if (match === undefined)
throw new TypeError("Unique trace match is missing");
rawTrace.push({ event_id: match.id, location: record.location });
const locations = locationsById.get(match.id) ?? [];
locations.push(record.location);
locationsById.set(match.id, locations);
}
return { rawTrace, locationsById };
};
const cardinalityFailure = (
trace: MatchedTrace,
specification: ProcessTraceSpecification,
): EvaluatedSide | null => {
for (const event of specification.events) {
const [minimum, maximum] = processTraceCardinalityBounds(event.cardinality);
const locations = trace.locationsById.get(event.id) ?? [];
if (locations.length < minimum || locations.length > maximum)
return failure({
kind: "cardinality",
message: `${event.id} observed ${String(locations.length)} times; expected ${String(minimum)}..${String(maximum)}.`,
eventIds: [event.id],
locations,
rawTrace: trace.rawTrace,
});
}
return null;
};
const evaluatePartialOrder = (
trace: MatchedTrace,
specification: ProcessTraceSpecification,
): EvaluatedSide => {
if (specification.language.kind !== "partial_order")
throw new TypeError("Expected a partial-order trace specification");
const satisfied: string[] = [];
for (const edge of specification.language.happens_before) {
const before = trace.locationsById.get(edge.before) ?? [];
const after = trace.locationsById.get(edge.after) ?? [];
const lastBefore = before.at(-1);
const firstAfter = after[0];
if (
lastBefore !== undefined &&
firstAfter !== undefined &&
lastBefore.capture_order >= firstAfter.capture_order
)
return failure({
kind: "edge",
message: `${edge.before} must happen before ${edge.after}.`,
eventIds: [edge.before, edge.after],
locations: [lastBefore, firstAfter],
rawTrace: trace.rawTrace,
});
satisfied.push(`happens_before:${edge.before}:${edge.after}`);
}
const ids = trace.rawTrace.map(({ event_id }) => event_id);
const prefix = specification.language.prefix;
if (
canonicalTraceJson(ids.slice(0, prefix.length)) !==
canonicalTraceJson(prefix)
)
return failure({
kind: "prefix",
message: "Observed trace does not satisfy the declared prefix.",
eventIds: prefix,
locations: trace.rawTrace
.slice(0, prefix.length)
.map(({ location }) => location),
rawTrace: trace.rawTrace,
});
const suffix = specification.language.suffix;
if (
canonicalTraceJson(suffix.length === 0 ? [] : ids.slice(-suffix.length)) !==
canonicalTraceJson(suffix)
)
return failure({
kind: "suffix",
message: "Observed trace does not satisfy the declared suffix.",
eventIds: suffix,
locations: trace.rawTrace
.slice(-suffix.length)
.map(({ location }) => location),
rawTrace: trace.rawTrace,
});
satisfied.push(
...specification.language.unordered_groups.map(
({ events }) => `unordered:${events.join(":")}`,
),
);
if (prefix.length > 0) satisfied.push(`prefix:${prefix.join(":")}`);
if (suffix.length > 0) satisfied.push(`suffix:${suffix.join(":")}`);
return {
result: {
status: "pass",
matched_variant: null,
satisfied_constraints: satisfied,
raw_trace: trace.rawTrace,
},
diagnostic: null,
};
};
const evaluateMatchedTrace = (
trace: MatchedTrace,
specification: ProcessTraceSpecification,
): EvaluatedSide => {
const invalidCardinality = cardinalityFailure(trace, specification);
if (invalidCardinality !== null) return invalidCardinality;
if (specification.language.kind === "partial_order")
return evaluatePartialOrder(trace, specification);
const ids = trace.rawTrace.map(({ event_id }) => event_id);
const variant = evaluateFiniteTrace(ids, specification);
return variant === null
? failure({
kind: "trace",
message: "Observed events do not match any finite trace variant.",
eventIds: ids,
locations: trace.rawTrace.map(({ location }) => location),
rawTrace: trace.rawTrace,
})
: {
result: {
status: "pass",
matched_variant: variant,
satisfied_constraints: [`variant:${variant}`],
raw_trace: trace.rawTrace,
},
diagnostic: null,
};
};
export const evaluateProcessTraceSide = (
capture: ProcessCapture,
specification: ProcessTraceSpecification,
): EvaluatedSide => {
const sources = new Set(specification.events.map(({ source }) => source));
const relevantScopes = scopesFor(sources);
if (
capture.truncated ||
capture.residual_unknowns.some(({ scope }) => relevantScopes.has(scope))
)
return { result: unknownSide(), diagnostic: null };
if ((capture.event_journal ?? []).length === 0)
return {
result: unknownSide(),
diagnostic: {
kind: "journal",
message: "Capture has no cross-source event journal.",
event_ids: [],
locations: [],
},
};
const matched = matchRecords(collectRecords(capture, sources), specification);
return "rawTrace" in matched
? evaluateMatchedTrace(matched, specification)
: matched;
};
+374
View File
@@ -0,0 +1,374 @@
import canonicalize from "canonicalize";
import { z } from "zod";
import { jsonValueSchema } from "./jsonValue.js";
const identifierSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._-]{0,63}$/u);
/** Process observation families admitted by a declared trace specification. */
export const processTraceSourceSchema = z.enum([
"terminal_raw",
"terminal_rendered",
"interaction",
"lifecycle",
"process",
"filesystem",
"http",
"websocket",
"shim",
"replay_transition",
]);
export type ProcessTraceSource = z.infer<typeof processTraceSourceSchema>;
const cardinalitySchema = z.discriminatedUnion("kind", [
z.strictObject({ kind: z.literal("required") }),
z.strictObject({ kind: z.literal("optional") }),
z.strictObject({
kind: z.literal("exact"),
count: z.number().int().min(0).max(10_000),
}),
z
.strictObject({
kind: z.literal("range"),
min: z.number().int().min(0).max(10_000),
max: z.number().int().min(0).max(10_000),
})
.refine(({ min, max }) => min <= max, {
message: "cardinality min must not exceed max",
path: ["min"],
}),
]);
const eventDeclarationSchema = z.strictObject({
id: identifierSchema,
source: processTraceSourceSchema,
exact: jsonValueSchema,
cardinality: cardinalitySchema.default({ kind: "required" }),
});
const partialOrderLanguageSchema = z.strictObject({
kind: z.literal("partial_order"),
happens_before: z
.array(
z.strictObject({
before: identifierSchema,
after: identifierSchema,
}),
)
.max(4_096)
.default([]),
unordered_groups: z
.array(
z.strictObject({ events: z.array(identifierSchema).min(2).max(256) }),
)
.max(256)
.default([]),
prefix: z.array(identifierSchema).max(4_096).default([]),
suffix: z.array(identifierSchema).max(4_096).default([]),
});
const finiteTraceTokenSchema = z.union([
identifierSchema,
z.strictObject({ unordered: z.array(identifierSchema).min(2).max(256) }),
]);
const finiteTraceLanguageSchema = z.strictObject({
kind: z.literal("finite_traces"),
variants: z
.array(
z.strictObject({
id: identifierSchema,
trace: z.array(finiteTraceTokenSchema).max(4_096),
}),
)
.min(1)
.max(64),
});
const specificationShapeSchema = z.strictObject({
version: z.literal(1),
events: z.array(eventDeclarationSchema).min(1).max(256),
language: z.discriminatedUnion("kind", [
partialOrderLanguageSchema,
finiteTraceLanguageSchema,
]),
});
export type ProcessTraceSpecification = z.infer<
typeof specificationShapeSchema
>;
type PartialOrderLanguage = z.infer<typeof partialOrderLanguageSchema>;
export const canonicalTraceJson = (value: unknown): string => {
const serialized = canonicalize(value);
if (serialized === undefined)
throw new TypeError("Trace specification contains a non-JSON value");
return serialized;
};
export const processTraceCardinalityBounds = (
cardinality: ProcessTraceSpecification["events"][number]["cardinality"],
): readonly [number, number] => {
switch (cardinality.kind) {
case "required":
return [1, 1];
case "optional":
return [0, 1];
case "exact":
return [cardinality.count, cardinality.count];
case "range":
return [cardinality.min, cardinality.max];
}
};
const addReferenceIssue = (
context: z.RefinementCtx,
known: ReadonlySet<string>,
id: string,
path: PropertyKey[],
): void => {
if (!known.has(id))
context.addIssue({
code: "custom",
message: `unknown event id: ${id}`,
path,
});
};
const pairKey = (left: string, right: string): string =>
[left, right].sort().join("\0");
const buildAdjacency = (
language: PartialOrderLanguage,
context: z.RefinementCtx,
known: ReadonlySet<string>,
): ReadonlyMap<string, Set<string>> => {
const adjacency = new Map([...known].map((id) => [id, new Set<string>()]));
for (const [index, edge] of language.happens_before.entries()) {
const path = ["language", "happens_before", index];
addReferenceIssue(context, known, edge.before, [...path, "before"]);
addReferenceIssue(context, known, edge.after, [...path, "after"]);
if (edge.before === edge.after)
context.addIssue({
code: "custom",
message: "happens-before edges must reference distinct events",
path,
});
adjacency.get(edge.before)?.add(edge.after);
}
return adjacency;
};
const graphHasCycle = (
ids: readonly string[],
adjacency: ReadonlyMap<string, ReadonlySet<string>>,
): boolean => {
const active = new Set<string>();
const complete = new Set<string>();
const visit = (current: string): boolean => {
if (active.has(current)) return true;
if (complete.has(current)) return false;
active.add(current);
const cyclic = [...(adjacency.get(current) ?? [])].some(visit);
active.delete(current);
complete.add(current);
return cyclic;
};
return ids.some(visit);
};
const computeReachability = (
ids: readonly string[],
adjacency: ReadonlyMap<string, ReadonlySet<string>>,
): ReadonlyMap<string, ReadonlySet<string>> => {
const reachable = new Map<string, Set<string>>();
for (const origin of ids) {
const seen = new Set<string>();
const pending = [...(adjacency.get(origin) ?? [])];
while (pending.length > 0) {
const current = pending.pop();
if (current === undefined || seen.has(current)) continue;
seen.add(current);
pending.push(...(adjacency.get(current) ?? []));
}
reachable.set(origin, seen);
}
return reachable;
};
const isOrdered = (
reachable: ReadonlyMap<string, ReadonlySet<string>>,
left: string,
right: string,
): boolean =>
reachable.get(left)?.has(right) === true ||
reachable.get(right)?.has(left) === true;
const validateUnorderedGroups = (
language: PartialOrderLanguage,
context: z.RefinementCtx,
known: ReadonlySet<string>,
reachable: ReadonlyMap<string, ReadonlySet<string>>,
): ReadonlySet<string> => {
const pairs = new Set<string>();
for (const [groupIndex, group] of language.unordered_groups.entries()) {
const path = ["language", "unordered_groups", groupIndex];
if (new Set(group.events).size !== group.events.length)
context.addIssue({
code: "custom",
message: "unordered groups must not repeat event ids",
path: [...path, "events"],
});
for (const [eventIndex, id] of group.events.entries())
addReferenceIssue(context, known, id, [...path, "events", eventIndex]);
for (const [leftIndex, leftId] of group.events.entries()) {
for (const rightId of group.events.slice(leftIndex + 1)) {
const key = pairKey(leftId, rightId);
if (pairs.has(key))
context.addIssue({
code: "custom",
message: "unordered event pairs must be declared once",
path,
});
pairs.add(key);
if (isOrdered(reachable, leftId, rightId))
context.addIssue({
code: "custom",
message: "ordered events cannot also be declared unordered",
path,
});
}
}
}
return pairs;
};
const validateCompletePairDeclarations = (
ids: readonly string[],
reachable: ReadonlyMap<string, ReadonlySet<string>>,
unorderedPairs: ReadonlySet<string>,
context: z.RefinementCtx,
): void => {
for (const [leftIndex, leftId] of ids.entries())
for (const rightId of ids.slice(leftIndex + 1))
if (
!isOrdered(reachable, leftId, rightId) &&
!unorderedPairs.has(pairKey(leftId, rightId))
)
context.addIssue({
code: "custom",
message: `event pair ${leftId}/${rightId} must be explicitly ordered or unordered`,
path: ["language"],
});
};
const validatePartialOrder = (
specification: ProcessTraceSpecification,
context: z.RefinementCtx,
): void => {
if (specification.language.kind !== "partial_order") return;
const ids = specification.events.map(({ id }) => id);
const known = new Set(ids);
const adjacency = buildAdjacency(specification.language, context, known);
if (graphHasCycle(ids, adjacency))
context.addIssue({
code: "custom",
message: "happens-before graph must be acyclic",
path: ["language", "happens_before"],
});
const reachable = computeReachability(ids, adjacency);
const unorderedPairs = validateUnorderedGroups(
specification.language,
context,
known,
reachable,
);
validateCompletePairDeclarations(ids, reachable, unorderedPairs, context);
for (const [kind, values] of [
["prefix", specification.language.prefix],
["suffix", specification.language.suffix],
] as const)
for (const [index, id] of values.entries())
addReferenceIssue(context, known, id, ["language", kind, index]);
};
const countVariantEvents = (
trace: readonly (string | { readonly unordered: readonly string[] })[],
): ReadonlyMap<string, number> => {
const counts = new Map<string, number>();
for (const token of trace)
for (const id of typeof token === "string" ? [token] : token.unordered)
counts.set(id, (counts.get(id) ?? 0) + 1);
return counts;
};
const validateFiniteTraces = (
specification: ProcessTraceSpecification,
context: z.RefinementCtx,
): void => {
if (specification.language.kind !== "finite_traces") return;
const known = new Set(specification.events.map(({ id }) => id));
const variantIds = new Set<string>();
for (const [
variantIndex,
variant,
] of specification.language.variants.entries()) {
const variantPath = ["language", "variants", variantIndex];
if (variantIds.has(variant.id))
context.addIssue({
code: "custom",
message: "finite trace variant ids must be unique",
path: [...variantPath, "id"],
});
variantIds.add(variant.id);
for (const [tokenIndex, token] of variant.trace.entries()) {
const values = typeof token === "string" ? [token] : token.unordered;
for (const [eventIndex, id] of values.entries())
addReferenceIssue(context, known, id, [
...variantPath,
"trace",
tokenIndex,
...(typeof token === "string" ? [] : ["unordered", eventIndex]),
]);
}
const counts = countVariantEvents(variant.trace);
for (const event of specification.events) {
const [minimum, maximum] = processTraceCardinalityBounds(
event.cardinality,
);
const count = counts.get(event.id) ?? 0;
if (count < minimum || count > maximum)
context.addIssue({
code: "custom",
message: `variant ${variant.id} violates ${event.id} cardinality`,
path: [...variantPath, "trace"],
});
}
}
};
/** Strict, bounded concurrency model for Process Capture observations. */
export const processTraceSpecificationSchema =
specificationShapeSchema.superRefine((specification, context) => {
const ids = new Set<string>();
const predicates = new Set<string>();
for (const [index, event] of specification.events.entries()) {
if (ids.has(event.id))
context.addIssue({
code: "custom",
message: "event ids must be unique",
path: ["events", index, "id"],
});
ids.add(event.id);
const predicate = `${event.source}\0${canonicalTraceJson(event.exact)}`;
if (predicates.has(predicate))
context.addIssue({
code: "custom",
message: "exact event predicates must not overlap",
path: ["events", index],
});
predicates.add(predicate);
}
validatePartialOrder(specification, context);
validateFiniteTraces(specification, context);
});