Files
reverse-engineering-anything/src/domain/process/processCapture.comparison.test.ts
T
吴佳浩Albenandmorluto 1e0f3348a7 fix(process): name the fields a located divergence compared (#11813)
* fix(process): name the fields a located divergence compared

`first_divergence` handed back the whole observation on each side, so a
caller that saw `changed` had to diff two large objects by hand to learn
what the comparison actually judged. Reported in #8204: the same
deterministic CLI captured twice reports `terminal`, `exit`, and
`filesystem` changed, and the report names no field.

A located divergence now carries `fields`, the sorted leaf paths that
differ in the projection the comparison judged, for example
`files[3].path`, `pid`, `process_samples[0].pid`, or `$` when a whole
observation is present on one side only. Positions are bracketed array
indices; the list is bounded to eight names because the report names a
difference rather than copying the observation, and `left` and `right`
still retain both complete observations.

The list is computed from the comparable projection, not the observed
values, so capture-local timing (`at_ms`, `dispatched_at_ms`,
`elapsed_ms`, `sent_at_ms`) is never named unless a `trace_spec`
explicitly selects it. That keeps the names honest about what the
comparison measured.

Naming a volatile value is not a claim of equivalence. A per-run
temporary root or PID still counts as a difference; the exclusion path
remains capture-time normalization (`normalization.paths`,
`normalization.pids`, `normalization.patterns`), which must match on both
sides because comparison refuses captures under different rules.

`fields` is optional in the contract. `readComparisonResult` re-validates
`normalized_result` of authenticated Evidence, so a required field would
reject records written before this change. Producing code always
populates it.

Validation: `tsc --noEmit` clean; `oxlint` reports only the four
pre-existing complexity/length warnings this file already carried;
`scripts/ci/static-check-report.mjs lint` 0 errors; module boundaries and
architecture guards pass; `oxfmt --check` clean on the touched files;
`completeness-enum-guard`, `optional-fact-default-guard`, and
`rea-numeric-limits` pass; `scan:todos` and `verify-test-discovery`
clean; jscpd within budget. 194 focused domain tests passed, including
five new cases covering a temporary-path leaf inside a filesystem
checkpoint, a fully populated process sample, the eight-name bound,
one-sided presence as `$`, and an authenticated payload without
`fields`. No live process capture was exercised on this host.

Refs #8204

* fix(process): honor trace timing policy in divergence fields

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
2026-11-18 15:05:59 -05:00

1340 lines
37 KiB
TypeScript

import { expect, it } from "vitest";
import { jsonValueSchema } from "../jsonValue.js";
import {
processScenarioSchema,
processScenarioCommitment,
processComparisonContract,
digestProcessCommitment,
} from "./processScenario.js";
import { parseProcessCapture } from "./processCaptureParsing.js";
import type { FileState } from "./processCapture.js";
import {
PROCESS_COMPARISON_DIMENSIONS,
processCaptureComparisonSchema,
} from "./processComparison.js";
import {
accountFullyObservedProcessCapture,
compareUnverifiedProcessCaptures as compareProcessCaptures,
emptyProcessCapture as emptyCapture,
FINALIZED_PROCESS_CAPTURE_EXAMPLE,
} from "./processCapture.fixture.js";
const compareFullyObserved = (
left: Parameters<typeof compareProcessCaptures>[0],
right: Parameters<typeof compareProcessCaptures>[1],
options?: Parameters<typeof compareProcessCaptures>[2],
) =>
compareProcessCaptures(
accountFullyObservedProcessCapture(left),
accountFullyObservedProcessCapture(right),
options,
);
it("ignores capture-local timing when every observed behavior is identical", () => {
const base = parseProcessCapture(FINALIZED_PROCESS_CAPTURE_EXAMPLE);
const finalization = base.exit.finalization;
if (finalization === undefined)
throw new Error("Finalization fixture must retain its deadline outcome");
const capture = (atMs: number) => ({
...base,
frames: [{ sequence: 0, at_ms: atMs, data: "deterministic output" }],
rendered_frames: [
{
sequence: 0,
at_ms: atMs,
columns: 20,
rows: 1,
cursor_x: 20,
cursor_y: 0,
active_buffer: "normal" as const,
lines: ["deterministic output"],
serialized_state: "deterministic output",
},
],
interaction_events: [
{
sequence: 0,
scheduled_at_ms: 5,
dispatched_at_ms: atMs + 5,
type: "input" as const,
data: "request",
outcome: "dispatched" as const,
},
],
exit: {
...base.exit,
finalization: {
...finalization,
elapsed_ms: atMs + 12,
signals: finalization.signals.map((signal) => ({
...signal,
sent_at_ms: atMs,
})),
},
},
settlement: { ...base.settlement, elapsed_ms: atMs + 50 },
process_samples: [
{
at_ms: atMs + 10,
pid: 1,
parent_pid: 0,
process_group_id: 1,
session_id: 1,
command: "deterministic-cli",
},
],
filesystem_checkpoints: base.filesystem_checkpoints.map(
(checkpoint, index) => ({
...checkpoint,
at_ms: index === 0 ? 0 : atMs + 50,
}),
),
});
expect(compareFullyObserved(capture(10), capture(30))).toMatchObject({
status: "unchanged",
terminal: "unchanged",
interaction: "unchanged",
exit: "unchanged",
filesystem: "unchanged",
process: "unchanged",
first_divergence: { status: "none" },
});
});
it("still reports semantic differences when capture-local timing also differs", () => {
const base = emptyCapture();
const file = (sha256: string) => ({
path: "root_0:result.txt",
type: "file" as const,
mode: 0o644,
size: 6,
sha256,
symlink_target: null,
});
const capture = (side: "left" | "right") => {
const atMs = side === "left" ? 10 : 30;
const observedFile = file((side === "left" ? "a" : "b").repeat(64));
return {
...base,
frames: [
{
sequence: 0,
at_ms: atMs,
data: side === "left" ? "left output" : "right output",
},
],
interaction_events: [
{
sequence: 0,
scheduled_at_ms: 5,
dispatched_at_ms: atMs + 5,
type: "input" as const,
data: "request",
outcome:
side === "left" ? ("dispatched" as const) : ("failed" as const),
},
],
exit: { ...base.exit, code: side === "left" ? 0 : 2 },
settlement: { ...base.settlement, elapsed_ms: atMs + 50 },
process_samples: [
{
at_ms: atMs + 10,
pid: 1,
parent_pid: 0,
process_group_id: 1,
session_id: 1,
command: side === "left" ? "worker-a" : "worker-b",
},
],
files_before: [observedFile],
files_after: [observedFile],
filesystem_checkpoints: base.filesystem_checkpoints.map(
(checkpoint, index) => ({
...checkpoint,
at_ms: index === 0 ? 0 : atMs + 50,
files: [observedFile],
}),
),
};
};
expect(compareFullyObserved(capture("left"), capture("right"))).toMatchObject(
{
status: "changed",
terminal: "changed",
interaction: "changed",
exit: "changed",
filesystem: "changed",
process: "changed",
first_divergence: { status: "found" },
},
);
});
it("reports an earlier rendered divergence before a later raw divergence", () => {
const base = emptyCapture();
const rendered = (side: "left" | "right") => ({
sequence: 0,
at_ms: 10,
columns: 5,
rows: 1,
cursor_x: 5,
cursor_y: 0,
active_buffer: "normal" as const,
lines: [side],
serialized_state: side,
});
const capture = (side: "left" | "right") => ({
...base,
frames: [{ sequence: 0, at_ms: 50, data: `raw-${side}` }],
rendered_frames: [rendered(side)],
});
expect(compareFullyObserved(capture("left"), capture("right"))).toMatchObject(
{
terminal: "changed",
first_divergence: {
status: "found",
dimension: "terminal",
index: 0,
left_at_ms: 10,
right_at_ms: 10,
left: { kind: "rendered", serialized_state: "left" },
right: { kind: "rendered", serialized_state: "right" },
},
},
);
});
it("does not report timing ignored by one terminal trace source", () => {
const base = emptyCapture();
const capture = (rawAtMs: number, renderedAtMs: number) => ({
...base,
frames: [{ sequence: 0, at_ms: rawAtMs, data: "ready" }],
rendered_frames: [
{
sequence: 0,
at_ms: renderedAtMs,
columns: 5,
rows: 1,
cursor_x: 5,
cursor_y: 0,
active_buffer: "normal" as const,
lines: ["ready"],
serialized_state: "ready",
},
],
event_journal: [
{
capture_order: 0,
collection: "filesystem_checkpoints" as const,
index: 0,
},
{ capture_order: 1, collection: "frames" as const, index: 0 },
{ capture_order: 2, collection: "rendered_frames" as const, index: 0 },
{ capture_order: 3, collection: "lifecycle" as const, index: 0 },
{ capture_order: 4, collection: "lifecycle" as const, index: 1 },
{
capture_order: 5,
collection: "filesystem_checkpoints" as const,
index: 1,
},
],
});
const left = capture(50, 10);
const right = capture(60, 20);
const { at_ms: _ignoredAtMs, ...renderedExact } =
left.rendered_frames[0] ?? {};
expect(
compareFullyObserved(left, right, {
traceSpecification: {
events: [
{
id: "raw",
source: "terminal_raw",
exact: jsonValueSchema.parse(left.frames[0]),
cardinality: { kind: "required" },
},
{
id: "rendered",
source: "terminal_rendered",
exact: jsonValueSchema.parse(renderedExact),
ignore_fields: ["at_ms"],
cardinality: { kind: "required" },
},
],
language: {
kind: "finite_traces",
variants: [{ id: "terminal", trace: ["raw", "rendered"] }],
},
},
}),
).toMatchObject({
trace: { verdict: "different" },
terminal: "changed",
first_divergence: {
status: "found",
dimension: "terminal",
left_at_ms: 50,
right_at_ms: 60,
// The trace made the raw at_ms part of the question, so the field list
// names exactly that timing value and nothing else.
fields: ["at_ms"],
left: { kind: "raw" },
right: { kind: "raw" },
},
});
});
it("names compared lifecycle timing and retains ignored settlement timing as evidence", () => {
const base = parseProcessCapture(FINALIZED_PROCESS_CAPTURE_EXAMPLE);
const finalization = base.exit.finalization;
if (finalization === undefined || finalization.elapsed_ms === null)
throw new Error("Finalization fixture must retain its deadline outcome");
const elapsedMs = finalization.elapsed_ms;
const capture = (offset: number) => ({
...base,
exit: {
...base.exit,
finalization: {
...finalization,
elapsed_ms: elapsedMs + offset,
},
},
settlement: {
...base.settlement,
elapsed_ms: base.settlement.elapsed_ms + offset,
},
event_journal: [
{
capture_order: 0,
collection: "filesystem_checkpoints" as const,
index: 0,
},
{ capture_order: 1, collection: "lifecycle" as const, index: 0 },
{ capture_order: 2, collection: "lifecycle" as const, index: 1 },
{
capture_order: 3,
collection: "filesystem_checkpoints" as const,
index: 1,
},
],
});
const left = capture(0);
const right = capture(10);
const { elapsed_ms: _ignoredElapsedMs, ...settlementExact } = left.settlement;
expect(
compareFullyObserved(left, right, {
traceSpecification: {
events: [
{
id: "exit",
source: "lifecycle",
exact: jsonValueSchema.parse({ event: "exit", ...left.exit }),
ignore_fields: ["elapsed_ms"],
cardinality: { kind: "required" },
},
{
id: "settlement",
source: "lifecycle",
exact: jsonValueSchema.parse({
event: "settlement",
...settlementExact,
}),
ignore_fields: ["elapsed_ms"],
cardinality: { kind: "required" },
},
],
language: {
kind: "finite_traces",
variants: [{ id: "lifecycle", trace: ["exit", "settlement"] }],
},
},
}),
).toMatchObject({
trace: { verdict: "different" },
exit: "changed",
first_divergence: {
status: "found",
dimension: "exit",
fields: ["finalization.elapsed_ms"],
left: { settlement: left.settlement },
right: { settlement: right.settlement },
},
});
});
it("reports compared dispatch timing when the trace ignores the interaction schedule", () => {
const base = emptyCapture();
const interaction = {
sequence: 0,
type: "input" as const,
data: "request",
outcome: "dispatched" as const,
};
const capture = (scheduledMs: number, dispatchedMs: number) => ({
...base,
interaction_events: [
{
...interaction,
scheduled_at_ms: scheduledMs,
dispatched_at_ms: dispatchedMs,
},
],
event_journal: (
[
{ collection: "filesystem_checkpoints", index: 0 },
{ collection: "interaction_events", index: 0 },
{ collection: "lifecycle", index: 0 },
{ collection: "lifecycle", index: 1 },
{ collection: "filesystem_checkpoints", index: 1 },
] as const
).map(({ collection, index }, capture_order) => ({
collection,
index,
capture_order,
})),
});
const left = capture(5, 10);
const right = capture(8, 20);
expect(compareFullyObserved(left, right).first_divergence).toMatchObject({
status: "found",
dimension: "interaction",
fields: ["scheduled_at_ms"],
});
expect(
compareFullyObserved(left, right, {
traceSpecification: {
events: [
{
id: "request",
source: "interaction",
exact: { ...interaction, dispatched_at_ms: 10 },
ignore_fields: ["scheduled_at_ms"],
cardinality: { kind: "required" },
},
],
language: {
kind: "finite_traces",
variants: [{ id: "interaction", trace: ["request"] }],
},
},
}),
).toMatchObject({
trace: { verdict: "different" },
interaction: "changed",
first_divergence: {
status: "found",
dimension: "interaction",
fields: ["dispatched_at_ms"],
left: { scheduled_at_ms: 5 },
right: { scheduled_at_ms: 8 },
},
});
});
it("does not turn unresolved filesystem effects into equality or a definite change", () => {
const capture = emptyCapture();
const file = {
path: "root_0:created.txt",
type: "file" as const,
mode: 0o644,
size: 4,
sha256: "a".repeat(64),
symlink_target: null,
};
const known = {
path: file.path,
status: "created" as const,
before: null,
after: file,
};
const unknown = {
...known,
status: "unknown" as const,
reason: "Prior scope was not observed.",
};
const withEffect = (effect: typeof known | typeof unknown) => ({
...capture,
files_after: [file],
filesystem_effects: [effect],
filesystem_checkpoints: capture.filesystem_checkpoints.map((checkpoint) =>
checkpoint.name === "after_settlement"
? { ...checkpoint, files: [file], effects: [effect] }
: checkpoint,
),
});
const unknownCapture = withEffect(unknown);
const knownCapture = withEffect(known);
for (const [left, right] of [
[unknownCapture, unknownCapture],
[unknownCapture, knownCapture],
[knownCapture, unknownCapture],
] as const)
expect(compareFullyObserved(left, right)).toMatchObject({
status: "unknown",
filesystem: "unknown",
first_divergence: { status: "unknown" },
});
expect(compareFullyObserved(knownCapture, knownCapture)).toMatchObject({
status: "unchanged",
filesystem: "unchanged",
first_divergence: { status: "none" },
});
});
it("preserves independently observed file changes alongside an unknown effect", () => {
const base = emptyCapture();
const link = {
path: "root_0:legacy-link",
type: "symlink" as const,
mode: 0o777,
size: 1,
sha256: null,
symlink_target: null,
symlink_target_hex: "ff",
};
const unknown = {
path: link.path,
status: "unknown" as const,
before: link,
after: link,
reason: "Target bytes were not retained.",
};
const make = (sha256: string) => {
const file = {
path: "root_0:known.txt",
type: "file" as const,
mode: 0o644,
size: 4,
sha256,
symlink_target: null,
};
const files = [link, file];
return {
...base,
files_before: files,
files_after: files,
filesystem_effects: [unknown],
filesystem_checkpoints: base.filesystem_checkpoints.map((checkpoint) => ({
...checkpoint,
files,
effects: checkpoint.name === "after_settlement" ? [unknown] : [],
})),
};
};
const left = make("a".repeat(64));
const right = make("b".repeat(64));
const traceSpecification = {
events: [
{
id: "before",
source: "filesystem" as const,
exact: jsonValueSchema.parse(left.filesystem_checkpoints[0]),
cardinality: { kind: "required" as const },
},
],
language: {
kind: "finite_traces" as const,
variants: [{ id: "v", trace: ["before"] }],
},
};
for (const [a, b] of [
[left, right],
[right, left],
] as const) {
for (const options of [undefined, { traceSpecification }])
expect(compareFullyObserved(a, b, options)).toMatchObject({
filesystem: "changed",
status: "changed",
first_divergence: { status: "unknown" },
});
}
});
it("compares exact symlink bytes beside an unrelated unknown effect", () => {
const base = emptyCapture();
const link = {
path: "root_0:link",
type: "symlink" as const,
mode: 0o777,
size: 1,
sha256: null,
symlink_target: null,
symlink_target_hex: "ff",
};
const make = (target: Extract<FileState, { type: "symlink" }>) => {
const effect = {
path: "root_0:unobserved",
status: "unknown" as const,
before: null,
after: null,
reason: "The selected subtree was not observed.",
};
return {
...base,
filesystem_effects: [effect],
files_before: [target],
files_after: [target],
filesystem_checkpoints: base.filesystem_checkpoints.map((checkpoint) => ({
...checkpoint,
files: [target],
effects: checkpoint.name === "after_settlement" ? [effect] : [],
})),
};
};
const modern = make(link);
const other = make({ ...link, symlink_target_hex: "fe" });
for (const [left, right] of [
[modern, other],
[other, modern],
] as const)
expect(compareFullyObserved(left, right)).toMatchObject({
filesystem: "changed",
first_divergence: { status: "unknown" },
});
expect(compareFullyObserved(modern, modern)).toMatchObject({
filesystem: "unknown",
status: "unknown",
});
});
it("preserves a definite attributed filesystem trace failure beside unknown effects", () => {
const base = emptyCapture();
const unknown = {
path: "root_0:link",
status: "unknown" as const,
before: null,
after: null,
reason: "Unobserved target.",
};
const make = (time: number) => ({
...base,
event_journal: [
{
capture_order: 0,
collection: "filesystem_checkpoints" as const,
index: 0,
},
{ capture_order: 1, collection: "lifecycle" as const, index: 0 },
{ capture_order: 2, collection: "lifecycle" as const, index: 1 },
{
capture_order: 3,
collection: "filesystem_checkpoints" as const,
index: 1,
},
],
filesystem_effects: [unknown],
filesystem_checkpoints: base.filesystem_checkpoints.map((checkpoint) =>
checkpoint.name === "after_settlement"
? { ...checkpoint, at_ms: time, effects: [unknown] }
: checkpoint,
),
});
const left = make(50);
const right = make(60);
const traceSpecification = {
events: [
{
id: "before",
source: "filesystem" as const,
exact: jsonValueSchema.parse(left.filesystem_checkpoints[0]),
cardinality: { kind: "required" as const },
},
{
id: "final",
source: "filesystem" as const,
exact: jsonValueSchema.parse(left.filesystem_checkpoints[1]),
cardinality: { kind: "required" as const },
},
],
language: {
kind: "finite_traces" as const,
variants: [{ id: "v", trace: ["before", "final"] }],
},
};
expect(
compareFullyObserved(left, right, { traceSpecification }),
).toMatchObject({
status: "changed",
filesystem: "changed",
first_divergence: { status: "unknown" },
trace: { verdict: "different" },
});
});
it("preserves proven file additions and removals beside an unrelated unknown effect", () => {
const base = emptyCapture();
const root = {
path: "root_0:.",
type: "directory" as const,
mode: 0o755,
size: 0,
sha256: null,
symlink_target: null,
};
const link = {
path: "root_0:legacy-link",
type: "symlink" as const,
mode: 0o777,
size: 1,
sha256: null,
symlink_target: null,
symlink_target_hex: "ff",
};
const file = {
path: "root_0:output.txt",
type: "file" as const,
mode: 0o644,
size: 4,
sha256: "a".repeat(64),
symlink_target: null,
};
const unknown = {
path: link.path,
status: "unknown" as const,
before: link,
after: link,
reason: "Target bytes were not retained.",
};
const created = {
path: file.path,
status: "created" as const,
before: null,
after: file,
};
const make = (withFile: boolean, unobserved: boolean) => {
const before = [root, link];
const after = withFile ? [...before, file] : before;
const effects = withFile ? [unknown, created] : [unknown];
return {
...base,
files_before: before,
files_after: after,
filesystem_effects: effects,
filesystem_checkpoints: base.filesystem_checkpoints.map((checkpoint) => ({
...checkpoint,
files: checkpoint.name === "before" ? before : after,
effects: checkpoint.name === "before" ? [] : effects,
})),
truncation_details: {
...base.truncation_details,
filesystem_before: {
...base.truncation_details.filesystem_before,
unobserved_subtrees: [],
},
filesystem_after: {
...base.truncation_details.filesystem_after,
unobserved_subtrees: unobserved
? [{ path: root.path, reason: "observer_owned" as const }]
: [],
},
},
};
};
const withFile = make(true, false);
const absent = make(false, false);
const unobserved = make(false, true);
const { unobserved_subtrees: _subtrees, ...legacyCoverage } =
absent.truncation_details.filesystem_after;
const legacy = {
...absent,
truncation_details: {
...absent.truncation_details,
filesystem_after: legacyCoverage,
},
};
const traceSpecification = {
events: [
{
id: "before",
source: "filesystem" as const,
exact: jsonValueSchema.parse(withFile.filesystem_checkpoints[0]),
cardinality: { kind: "required" as const },
},
],
language: {
kind: "finite_traces" as const,
variants: [{ id: "v", trace: ["before"] }],
},
};
for (const [left, right] of [
[withFile, absent],
[absent, withFile],
] as const) {
for (const options of [undefined, { traceSpecification }])
expect(compareFullyObserved(left, right, options)).toMatchObject({
filesystem: "changed",
status: "changed",
first_divergence: { status: "unknown" },
});
}
for (const [left, right] of [
[withFile, unobserved],
[unobserved, withFile],
[withFile, legacy],
[legacy, withFile],
] as const)
expect(compareFullyObserved(left, right)).toMatchObject({
filesystem: "unknown",
status: "unknown",
});
});
it.each(PROCESS_COMPARISON_DIMENSIONS)(
"requires a contradiction aggregate for a contradictory %s dimension",
(dimension) => {
const baseline = compareFullyObserved(emptyCapture(), emptyCapture());
const result = { ...baseline, [dimension]: "contradiction" as const };
expect(processCaptureComparisonSchema.safeParse(result).success).toBe(
false,
);
expect(
processCaptureComparisonSchema.parse({
...result,
status: "contradiction",
}),
).toMatchObject({ status: "contradiction", [dimension]: "contradiction" });
},
);
it.each([
["unchanged", "contradiction"],
["added", "contradiction"],
["removed", "contradiction"],
["changed", "contradiction"],
["unknown", "contradiction"],
["contradiction", "contradiction"],
["truncated", "truncated"],
] as const)(
"combines contradiction with %s as %s independently of dimension order",
(other, expected) => {
for (const [terminal, interaction] of [
["contradiction", other],
[other, "contradiction"],
] as const) {
expect(
processCaptureComparisonSchema.parse({
...compareFullyObserved(emptyCapture(), emptyCapture()),
terminal,
interaction,
status: expected,
}),
).toMatchObject({ status: expected });
expect(
processCaptureComparisonSchema.safeParse({
...compareFullyObserved(emptyCapture(), emptyCapture()),
terminal,
interaction,
status: expected === "truncated" ? "contradiction" : "truncated",
}).success,
).toBe(false);
}
},
);
it("compares normalized terminal facts while retaining different source text for audit", () => {
const capture = emptyCapture();
const frame = { sequence: 0, at_ms: 0, data: "listen:<port> score=20" };
const left = {
...capture,
frames: [{ ...frame, raw_data: "listen:8080 score=20" }],
};
const right = {
...capture,
frames: [{ ...frame, raw_data: "listen:9090 score=20" }],
};
expect(compareFullyObserved(left, right)).toMatchObject({
terminal: "unchanged",
});
expect(
compareFullyObserved(left, {
...right,
frames: [{ ...frame, data: "listen:<port> score=21" }],
}),
).toMatchObject({ terminal: "changed" });
});
it("distinguishes added evidence from unknown observations", () => {
const capture = emptyCapture();
const added = compareFullyObserved(capture, {
...capture,
frames: [{ sequence: 0, at_ms: 0, data: "new" }],
rendered_frames: [
{
sequence: 0,
at_ms: 0,
columns: 3,
rows: 1,
cursor_x: 3,
cursor_y: 0,
active_buffer: "normal",
lines: ["new"],
serialized_state: "new",
},
],
});
expect(added).toMatchObject({ terminal: "added", status: "changed" });
for (const [scope, dimension] of [
["process", "process"],
["interaction", "interaction"],
] as const) {
expect(
compareFullyObserved(
{
...capture,
residual_unknowns: [{ scope, reason: "observation was partial" }],
},
capture,
),
).toMatchObject({
status: "unknown",
[dimension]: "unknown",
terminal: "unchanged",
});
}
});
it("compares raw terminal and process observations while honoring normalization shape", () => {
const capture = emptyCapture();
expect(
compareFullyObserved(capture, {
...capture,
normalization: {
patterns: [],
time_bucket_ms: 10,
ports: true,
pids: true,
paths: true,
},
}),
).toMatchObject({
status: "unchanged",
first_divergence: { status: "none" },
});
const terminal = compareFullyObserved(
{ ...capture, frames: [{ sequence: 0, at_ms: 0, data: "bar" }] },
{ ...capture, frames: [{ sequence: 0, at_ms: 0, data: "foo\rbar" }] },
);
expect(terminal).toMatchObject({
terminal: "changed",
first_divergence: { status: "found", dimension: "terminal" },
});
expect(
compareFullyObserved(
{
...capture,
process_samples: [
{
at_ms: 10,
pid: 1,
parent_pid: 0,
process_group_id: 1,
session_id: 1,
command: "worker",
},
],
},
{
...capture,
process_samples: [
{
at_ms: 20,
pid: 1,
parent_pid: 2,
process_group_id: 1,
session_id: 1,
command: "worker",
},
],
},
),
).toMatchObject({ process: "changed", status: "changed" });
});
it("names the compared field that differed inside a filesystem checkpoint", () => {
const capture = (root: string) => {
const base = emptyCapture();
const file = {
path: `${root}:out.txt`,
type: "file" as const,
mode: 0o644,
size: 4,
sha256: "a".repeat(64),
symlink_target: null,
};
return {
...base,
files_after: [file],
filesystem_checkpoints: base.filesystem_checkpoints.map((checkpoint) => ({
...checkpoint,
files: checkpoint.name === "before" ? [] : [file],
})),
};
};
expect(
compareFullyObserved(capture("root_0"), capture("root_1")),
).toMatchObject({
filesystem: "changed",
first_divergence: {
status: "found",
dimension: "filesystem",
index: 1,
fields: ["files[0].path"],
},
});
});
it("names every differing field of one observation in sorted order", () => {
const capture = (side: "left" | "right") => ({
...emptyCapture(),
process_samples: [
{
at_ms: 10,
pid: side === "left" ? 2 : 3,
parent_pid: side === "left" ? 1 : 4,
process_group_id: side === "left" ? 2 : 5,
session_id: side === "left" ? 2 : 6,
command: side === "left" ? "worker-a" : "worker-b",
},
],
});
expect(compareFullyObserved(capture("left"), capture("right"))).toMatchObject(
{
process: "changed",
first_divergence: {
status: "found",
dimension: "process",
index: 0,
fields: [
"command",
"parent_pid",
"pid",
"process_group_id",
"session_id",
],
},
},
);
});
it("bounds the field list when a wide observation differs throughout", () => {
const capture = (root: string) => {
const base = emptyCapture();
const files = Array.from({ length: 10 }, (_entry, index) => ({
path: `${root}:f${index}.txt`,
type: "file" as const,
mode: 0o644,
size: 1,
sha256: "a".repeat(64),
symlink_target: null,
}));
return {
...base,
files_after: files,
filesystem_checkpoints: base.filesystem_checkpoints.map((checkpoint) => ({
...checkpoint,
files: checkpoint.name === "before" ? [] : files,
})),
};
};
const divergence = compareFullyObserved(
capture("root_0"),
capture("root_1"),
).first_divergence;
if (divergence.status !== "found")
throw new Error("A differing file set must locate a divergence");
expect(divergence.fields).toStrictEqual(
Array.from({ length: 8 }, (_entry, index) => `files[${index}].path`),
);
});
it("reports an observation that is present on one side only as the whole field", () => {
const sample = {
at_ms: 10,
pid: 1,
parent_pid: 0,
process_group_id: 1,
session_id: 1,
command: "worker",
};
const withSample = { ...emptyCapture(), process_samples: [sample] };
expect(compareFullyObserved(withSample, emptyCapture())).toMatchObject({
process: "removed",
first_divergence: {
status: "found",
dimension: "process",
index: 0,
fields: ["$"],
},
});
});
it("accepts a divergence recorded before the compared field list existed", () => {
const capture = (pid: number) => ({
...emptyCapture(),
process_samples: [
{
at_ms: 10,
pid,
parent_pid: 0,
process_group_id: 1,
session_id: 1,
command: "worker",
},
],
});
const comparison = compareFullyObserved(capture(1), capture(2));
const divergence = comparison.first_divergence;
if (divergence.status !== "found")
throw new Error("A differing PID must locate a divergence");
const { fields: _compared, ...legacyDivergence } = divergence;
expect(
processCaptureComparisonSchema.parse({
...comparison,
first_divergence: legacyDivergence,
}),
).toMatchObject({ status: "changed", process: "changed" });
});
it("keeps filesystem comparison unknown without coverage and reports observed changes", () => {
const capture = emptyCapture();
const incomplete = {
...capture,
residual_unknowns: [
{ scope: "filesystem" as const, reason: "watcher unavailable" },
],
};
expect(compareFullyObserved(incomplete, incomplete)).toMatchObject({
filesystem: "unknown",
status: "unknown",
});
const finalFile = {
path: "root_0:created.txt",
type: "file" as const,
mode: 0o644,
size: 4,
sha256: "a".repeat(64),
symlink_target: null,
};
expect(
compareFullyObserved(capture, {
...capture,
filesystem_checkpoints: [
{ name: "before", at_ms: 0, files: [], effects: [], truncated: false },
{
name: "after_settlement",
at_ms: 10,
files: [finalFile],
effects: [
{
path: finalFile.path,
status: "created",
before: null,
after: finalFile,
},
],
truncated: false,
},
],
files_after: [finalFile],
filesystem_effects: [
{
path: finalFile.path,
status: "created",
before: null,
after: finalFile,
},
],
}),
).toMatchObject({ filesystem: "changed", status: "changed" });
});
it.each([
[500, "interaction", 6],
[4, "process", 4],
] as const)(
"orders an interaction difference by its dispatch time (process sample at %i ms)",
(processTime, dimension, at) => {
const capture = (side: "left" | "right") => {
const base = emptyCapture();
const journal = [
{ collection: "filesystem_checkpoints" as const, index: 0 },
...(processTime < 6
? [{ collection: "process_samples" as const, index: 0 }]
: []),
{ collection: "interaction_events" as const, index: 0 },
...(processTime >= 6
? [{ collection: "process_samples" as const, index: 0 }]
: []),
{ collection: "lifecycle" as const, index: 0 },
{ collection: "lifecycle" as const, index: 1 },
{ collection: "filesystem_checkpoints" as const, index: 1 },
].map((entry, capture_order) => ({ ...entry, capture_order }));
return {
...base,
manifest: {
...base.manifest,
completed_at: "2026-01-01T00:00:01.000Z",
},
settlement: { ...base.settlement, elapsed_ms: 1000 },
filesystem_checkpoints: base.filesystem_checkpoints.map(
(checkpoint, index) => ({
...checkpoint,
at_ms: index === 0 ? 0 : 1000,
}),
),
interaction_events: [
{
sequence: 0,
scheduled_at_ms: 5,
dispatched_at_ms: 6,
type: "input" as const,
data: "hello",
outcome:
side === "left" ? ("dispatched" as const) : ("failed" as const),
},
],
process_samples: [
{
at_ms: processTime,
pid: 2,
parent_pid: 1,
command: side === "left" ? "worker-a" : "worker-b",
process_group_id: 1,
session_id: 1,
},
],
event_journal: journal,
};
};
const comparison = compareFullyObserved(capture("left"), capture("right"));
expect(comparison).toMatchObject({
interaction: "changed",
process: "changed",
first_divergence: {
status: "found",
dimension,
left_at_ms: at,
right_at_ms: at,
},
});
},
);
it("refuses mixed terminal observation versions even with PID and port rules disabled", () => {
const base = emptyCapture();
const scenario = processScenarioSchema.parse({
executable: "/usr/bin/true",
normalization: { pids: false, ports: false },
});
const committed = processScenarioCommitment(
scenario,
base.manifest.selected_executable_sha256 ?? undefined,
);
const contract = processComparisonContract(scenario);
expect(contract).not.toHaveProperty("pid_normalization_version");
expect(contract).not.toHaveProperty("port_normalization_version");
expect(contract.terminal_observation_version).toBe(
"deferred-rendered-journal-v1",
);
const capture = parseProcessCapture({
...base,
normalization: scenario.normalization,
manifest: {
...base.manifest,
scenario: committed,
full_scenario_sha256: digestProcessCommitment(committed),
normalization_sha256: digestProcessCommitment(scenario.normalization),
root_process: {
state: "unknown",
reason: "the fixture launched no process",
},
comparison_contract: contract,
comparison_contract_sha256: digestProcessCommitment(contract),
},
});
const legacyContract = { ...contract };
delete legacyContract.terminal_observation_version;
const legacy = parseProcessCapture({
...capture,
manifest: {
...capture.manifest,
comparison_contract: legacyContract,
comparison_contract_sha256: digestProcessCommitment(legacyContract),
},
});
expect(() => compareProcessCaptures(capture, legacy)).toThrow(
expect.objectContaining({
issues: [
expect.objectContaining({ expected: ["terminal_observation_version"] }),
],
}),
);
});
it("refuses mixed path normalization versions even with PID and port rules disabled", () => {
const base = emptyCapture();
const scenario = processScenarioSchema.parse({
executable: "/usr/bin/true",
normalization: { pids: false, ports: false, paths: true },
});
const committed = processScenarioCommitment(
scenario,
base.manifest.selected_executable_sha256 ?? undefined,
);
const contract = processComparisonContract(scenario);
expect(contract.path_normalization_version).toBe(
"path-component-boundaries-v4",
);
const capture = parseProcessCapture({
...base,
normalization: scenario.normalization,
manifest: {
...base.manifest,
scenario: committed,
full_scenario_sha256: digestProcessCommitment(committed),
normalization_sha256: digestProcessCommitment(scenario.normalization),
root_process: {
state: "unknown",
reason: "the fixture launched no process",
},
comparison_contract: contract,
comparison_contract_sha256: digestProcessCommitment(contract),
},
});
const legacyContract = {
...contract,
path_normalization_version: "path-component-boundaries-v3",
};
const legacy = parseProcessCapture({
...capture,
manifest: {
...capture.manifest,
comparison_contract: legacyContract,
comparison_contract_sha256: digestProcessCommitment(legacyContract),
},
});
expect(() => compareProcessCaptures(capture, legacy)).toThrow(
expect.objectContaining({
issues: [
expect.objectContaining({ expected: ["path_normalization_version"] }),
],
}),
);
});