Skip to content

armgit / rea

Public Imported from GitHub
0

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

refactor(captures)!: require canonical producer metadata

morluto3283a45d0945
diff --git a/docs/browser-scenario-contract.md b/docs/browser-scenario-contract.md
index 5bc4e8955..a0482f008 100644
--- a/docs/browser-scenario-contract.md
+++ b/docs/browser-scenario-contract.md
@@ -236,12 +236,13 @@ network metadata observation; listing `network` in `events` is then optional.
Each observed request object receives a capture-scoped `transaction_id`.
Requests sharing a URL remain distinct. Redirects link to the preceding
transaction only when it was observed; a null predecessor does not establish
-that no earlier hop existed. Older captures without IDs remain readable and
-their transaction association is unknown.
+that no earlier hop existed. Request events require both transaction fields;
+an absent ID is malformed capture data, while a null redirect predecessor is
+an explicit unknown.
`scenario.network_content` records the resolved content selection. Comparing
-captures with different selection, or legacy captures without that coverage
-information, reports network evidence as unknown with a recovery instruction.
+captures with different selections reports network evidence as unknown with a
+recovery instruction.
Capturing more data alone does not establish a website change.
`network-content` events reference the exact request or response event through
diff --git a/docs/process-capture.md b/docs/process-capture.md
index 24cdac571..b000994c0 100644
--- a/docs/process-capture.md
+++ b/docs/process-capture.md
@@ -130,7 +130,7 @@ run the same owned-process cleanup path. Settlement reports whether the
sampled process group quiesced or whether cleanup was needed or unverifiable;
sampling cannot prove that every short-lived or detached descendant was seen.
-New captures include `truncation_details`, with separate accounting for:
+Every capture requires `truncation_details`, with separate accounting for:
- `raw_terminal`: original UTF-8 PTY chunk bytes and observed/retained chunk
counts. A chunk that does not fit `limits.output_bytes` is omitted whole;
@@ -150,7 +150,7 @@ New captures include `truncation_details`, with separate accounting for:
- `process`: sampling limit and whether sampling ended partially. Coverage
remains `sampled`, including when that limit was not exhausted.
-The legacy `truncated` flag summarizes these observations. Comparisons retain
+The aggregate `truncated` flag summarizes these observations. Comparisons retain
results for unaffected dimensions and mark affected dimensions unknown; an
incomplete capture cannot locate the first divergence across all dimensions.
Trace assertions use coverage for the sources they select, so an assertion
diff --git a/src/browser/assets/ScenarioScriptCapture.ts b/src/browser/assets/ScenarioScriptCapture.ts
index b963aeaec..642dd01f9 100644
--- a/src/browser/assets/ScenarioScriptCapture.ts
+++ b/src/browser/assets/ScenarioScriptCapture.ts
@@ -34,12 +34,12 @@ const indexResponses = (
requests: new Map(),
};
for (const event of events) {
- if (event.kind === "request" && event.transaction_id !== undefined)
+ if (event.kind === "request")
index.requests.set(
event.transaction_id,
(index.requests.get(event.transaction_id) ?? 0) + 1,
);
- if (event.kind === "response" && event.transaction_id !== undefined)
+ if (event.kind === "response")
append(index.responses, event.transaction_id, event);
if (event.kind === "network-content" && event.phase === "response")
append(index.contents, event.source_event_sequence, event);
@@ -52,25 +52,23 @@ const projectRequest = (
index: ResponseIndex,
): CapturedWebScript => {
const id = request.transaction_id;
- const matches = id === undefined ? [] : (index.responses.get(id) ?? []);
+ const matches = index.responses.get(id) ?? [];
const response = matches.length === 1 ? matches[0] : undefined;
const bodies =
response === undefined ? [] : (index.contents.get(response.sequence) ?? []);
const body = bodies.length === 1 ? bodies[0]?.body : undefined;
const ambiguous =
- (id !== undefined && index.requests.get(id) !== 1) ||
- matches.length > 1 ||
- bodies.length > 1;
+ index.requests.get(id) !== 1 || matches.length > 1 || bodies.length > 1;
return {
source: {
kind: "scenario-response",
- transaction_id: id ?? null,
+ transaction_id: id,
request_sequence: request.sequence,
response_sequence: ambiguous ? null : (response?.sequence ?? null),
status: ambiguous ? null : (response?.status ?? null),
},
url: request.url.url,
- content: projectBody(body, id, ambiguous),
+ content: projectBody(body, ambiguous),
};
};
@@ -81,7 +79,6 @@ const unavailable = (
const projectBody = (
body: BrowserNetworkBody | undefined,
- transactionId: string | undefined,
ambiguous: boolean,
): CapturedWebScript["content"] => {
if (ambiguous)
@@ -91,9 +88,7 @@ const projectBody = (
);
if (body === undefined)
return unavailable(
- transactionId === undefined
- ? "transaction-identity-unavailable"
- : "response-content-not-retained",
+ "response-content-not-retained",
"No selected, completed script response bytes were retained for this request.",
);
if (body.state === "unavailable")
diff --git a/src/browser/assets/ScriptCaptureAdapters.test.ts b/src/browser/assets/ScriptCaptureAdapters.test.ts
index fb3f4cb87..6cb010fee 100644
--- a/src/browser/assets/ScriptCaptureAdapters.test.ts
+++ b/src/browser/assets/ScriptCaptureAdapters.test.ts
@@ -164,21 +164,39 @@ describe("script capture identity and response projection", () => {
});
});
- it("does not join legacy metadata by URL when transaction identity is absent", () => {
+ it("rejects captures without explicit transaction identity metadata", () => {
const capture = scriptScenarioFixture();
- capture.events.items = capture.events.items.filter(
- ({ kind }) => kind !== "network-content",
+ const request = capture.events.items.find(({ kind }) => kind === "request");
+ if (request?.kind !== "request") throw new Error("Missing request");
+ const { transaction_id: _transactionId, ...requestWithoutId } = request;
+ const withoutTransactionId: unknown = {
+ ...capture,
+ events: {
+ ...capture.events,
+ items: capture.events.items.map((event) =>
+ event === request ? requestWithoutId : event,
+ ),
+ },
+ };
+ expect(() => selectScriptCapture(withoutTransactionId)).toThrow(
+ "Expected a valid",
);
- for (const event of capture.events.items)
- if (event.kind === "request" || event.kind === "response")
- delete event.transaction_id;
- capture.events.retained = capture.events.items.length;
- expect(selectScriptCapture(capture).scripts[0]).toMatchObject({
- source: { transaction_id: null },
- content: {
- state: "unavailable",
- reason: "transaction-identity-unavailable",
+
+ const {
+ redirected_from_transaction_id: _redirect,
+ ...requestWithoutRedirect
+ } = request;
+ const withoutRedirectMetadata: unknown = {
+ ...capture,
+ events: {
+ ...capture.events,
+ items: capture.events.items.map((event) =>
+ event === request ? requestWithoutRedirect : event,
+ ),
},
- });
+ };
+ expect(() => selectScriptCapture(withoutRedirectMetadata)).toThrow(
+ "Expected a valid",
+ );
});
});
diff --git a/src/domain/browserScenarioCapture.test.ts b/src/domain/browserScenarioCapture.test.ts
index 020920a3e..8a7b39283 100644
--- a/src/domain/browserScenarioCapture.test.ts
+++ b/src/domain/browserScenarioCapture.test.ts
@@ -13,12 +13,35 @@ import { browserScenarioCaptureSchema } from "./browserScenarioCapture.js";
const networkEvent = {
sequence: 1,
step_index: 0,
+ transaction_id: "request-1",
+ redirected_from_transaction_id: null,
method: "GET",
url: sanitizeBrowserUrl("https://example.test/resource"),
resource_type: "document",
header_names: [],
} as const;
+it("requires transaction IDs and explicit unknown redirect predecessors", () => {
+ const request = {
+ ...networkEvent,
+ kind: "request",
+ status: null,
+ failure: null,
+ } as const;
+ expect(
+ browserScenarioEventSchema.safeParse({
+ ...request,
+ transaction_id: undefined,
+ }).success,
+ ).toBe(false);
+ expect(
+ browserScenarioEventSchema.safeParse({
+ ...request,
+ redirected_from_transaction_id: undefined,
+ }).success,
+ ).toBe(false);
+});
+
it("parses each network outcome without contradictory status or failure data", () => {
expect(
browserScenarioEventSchema.safeParse({
diff --git a/src/domain/browserScenarioCaptureValues.ts b/src/domain/browserScenarioCaptureValues.ts
index 9752cf97a..81fef0c15 100644
--- a/src/domain/browserScenarioCaptureValues.ts
+++ b/src/domain/browserScenarioCaptureValues.ts
@@ -127,8 +127,8 @@ const eventBase = {
const eventUrl = sanitizedBrowserUrlSchema.nullable();
const networkEventShape = {
...eventBase,
- transaction_id: z.string().min(1).optional(),
- redirected_from_transaction_id: z.string().min(1).nullable().optional(),
+ transaction_id: z.string().min(1),
+ redirected_from_transaction_id: z.string().min(1).nullable(),
method: z.string().min(1),
url: sanitizedBrowserUrlSchema,
resource_type: z.string().min(1),
diff --git a/src/domain/browserScenarioDiff.test.ts b/src/domain/browserScenarioDiff.test.ts
index 7b3824abb..4c5272b9c 100644
--- a/src/domain/browserScenarioDiff.test.ts
+++ b/src/domain/browserScenarioDiff.test.ts
@@ -28,6 +28,7 @@ const networkCapture = (sourceSequence: number, receiptStep: number) => {
},
resource_type: "fetch",
transaction_id: "request-1",
+ redirected_from_transaction_id: null,
header_names: [],
status: null,
failure: null,
diff --git a/src/domain/process/processCapture.comparison.test.ts b/src/domain/process/processCapture.comparison.test.ts
index 85fd98369..4d238da2d 100644
--- a/src/domain/process/processCapture.comparison.test.ts
+++ b/src/domain/process/processCapture.comparison.test.ts
@@ -1,10 +1,22 @@
import { expect, it } from "vitest";
import {
+ accountFullyObservedProcessCapture,
compareUnverifiedProcessCaptures as compareProcessCaptures,
emptyProcessCapture as emptyCapture,
} 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("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" };
@@ -16,11 +28,11 @@ it("compares normalized terminal facts while retaining different source text for
...capture,
frames: [{ ...frame, raw_data: "listen:9090 score=20" }],
};
- expect(compareProcessCaptures(left, right)).toMatchObject({
+ expect(compareFullyObserved(left, right)).toMatchObject({
terminal: "unchanged",
});
expect(
- compareProcessCaptures(left, {
+ compareFullyObserved(left, {
...right,
frames: [{ ...frame, data: "listen:<port> score=21" }],
}),
@@ -29,7 +41,7 @@ it("compares normalized terminal facts while retaining different source text for
it("distinguishes added evidence from unknown observations", () => {
const capture = emptyCapture();
- const added = compareProcessCaptures(capture, {
+ const added = compareFullyObserved(capture, {
...capture,
frames: [{ sequence: 0, at_ms: 0, data: "new" }],
rendered_frames: [
@@ -53,7 +65,7 @@ it("distinguishes added evidence from unknown observations", () => {
["interaction", "interaction"],
] as const) {
expect(
- compareProcessCaptures(
+ compareFullyObserved(
{
...capture,
residual_unknowns: [{ scope, reason: "observation was partial" }],
@@ -71,7 +83,7 @@ it("distinguishes added evidence from unknown observations", () => {
it("compares raw terminal and process observations while honoring normalization shape", () => {
const capture = emptyCapture();
expect(
- compareProcessCaptures(capture, {
+ compareFullyObserved(capture, {
...capture,
normalization: {
patterns: [],
@@ -86,7 +98,7 @@ it("compares raw terminal and process observations while honoring normalization
first_divergence: { status: "none" },
});
- const terminal = compareProcessCaptures(
+ const terminal = compareFullyObserved(
{ ...capture, frames: [{ sequence: 0, at_ms: 0, data: "bar" }] },
{ ...capture, frames: [{ sequence: 0, at_ms: 0, data: "foo\rbar" }] },
);
@@ -96,7 +108,7 @@ it("compares raw terminal and process observations while honoring normalization
});
expect(
- compareProcessCaptures(
+ compareFullyObserved(
{
...capture,
process_samples: [
@@ -135,7 +147,7 @@ it("keeps filesystem comparison unknown without coverage and reports observed ch
{ scope: "filesystem" as const, reason: "watcher unavailable" },
],
};
- expect(compareProcessCaptures(incomplete, incomplete)).toMatchObject({
+ expect(compareFullyObserved(incomplete, incomplete)).toMatchObject({
filesystem: "unknown",
status: "unknown",
});
@@ -149,7 +161,7 @@ it("keeps filesystem comparison unknown without coverage and reports observed ch
symlink_target: null,
};
expect(
- compareProcessCaptures(capture, {
+ compareFullyObserved(capture, {
...capture,
filesystem_checkpoints: [
{ name: "before", at_ms: 0, files: [], effects: [], truncated: false },
diff --git a/src/domain/process/processCapture.fixture.ts b/src/domain/process/processCapture.fixture.ts
index 9ea29421a..701e76e2a 100644
--- a/src/domain/process/processCapture.fixture.ts
+++ b/src/domain/process/processCapture.fixture.ts
@@ -1,6 +1,7 @@
import { compareProcessCaptures } from "./processComparison.js";
import { parseProcessCapture } from "./processCaptureParsing.js";
import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "./processCaptureExample.js";
+import { hasCaptureTruncation } from "./processCaptureCoverage.js";
import {
processCaptureSchema,
@@ -14,6 +15,79 @@ export const emptyProcessCapture = () =>
export const emptyUnverifiedProcessCapture = (): UnverifiedProcessCapture =>
processCaptureSchema.parse(EMPTY_PROCESS_CAPTURE_EXAMPLE);
+/** Account for every observation retained by a fully observed test fixture. */
+export const accountFullyObservedProcessCapture = (
+ capture: UnverifiedProcessCapture,
+): UnverifiedProcessCapture => {
+ const rawBytes = capture.frames.reduce(
+ (total, frame) => total + Buffer.byteLength(frame.raw_data ?? frame.data),
+ 0,
+ );
+ const renderedBytes = capture.rendered_frames.reduce(
+ (total, frame) =>
+ frame.lines.reduce(
+ (sum, line) => sum + Buffer.byteLength(line),
+ total + Buffer.byteLength(frame.serialized_state),
+ ),
+ 0,
+ );
+ const filesystemBefore = {
+ ...capture.truncation_details.filesystem_before,
+ hashed_bytes: capture.files_before
+ .filter((file) => file.type === "file" && file.sha256 !== null)
+ .reduce((total, file) => total + file.size, 0),
+ };
+ const filesystemAfter = {
+ ...capture.truncation_details.filesystem_after,
+ hashed_bytes: capture.files_after
+ .filter((file) => file.type === "file" && file.sha256 !== null)
+ .reduce((total, file) => total + file.size, 0),
+ };
+ const truncationDetails = {
+ ...capture.truncation_details,
+ raw_terminal: {
+ ...capture.truncation_details.raw_terminal,
+ observed_bytes: rawBytes,
+ retained_bytes: rawBytes,
+ observed_frames: capture.frames.length,
+ retained_frames: capture.frames.length,
+ },
+ rendered_terminal: {
+ ...capture.truncation_details.rendered_terminal,
+ observed_bytes: renderedBytes,
+ retained_bytes: renderedBytes,
+ observed_frames: capture.rendered_frames.length,
+ retained_frames: capture.rendered_frames.length,
+ },
+ filesystem_before: filesystemBefore,
+ filesystem_after: filesystemAfter,
+ process: {
+ ...capture.truncation_details.process,
+ sample_limit: Math.max(
+ capture.truncation_details.process.sample_limit,
+ capture.process_samples.length,
+ ),
+ retained_samples: capture.process_samples.length,
+ },
+ };
+ const filesystemCheckpoints = capture.filesystem_checkpoints.map(
+ (checkpoint, index) => {
+ const coverage = index === 0 ? filesystemBefore : filesystemAfter;
+ return {
+ ...checkpoint,
+ truncated:
+ coverage.enumeration_truncated || coverage.hash_omissions.length > 0,
+ };
+ },
+ );
+ return {
+ ...capture,
+ filesystem_checkpoints: filesystemCheckpoints,
+ truncation_details: truncationDetails,
+ truncated: hasCaptureTruncation(truncationDetails),
+ };
+};
+
/** Project validation failures without coupling tests to Zod internals. */
export const processCaptureIssues = (
capture: UnverifiedProcessCapture,
diff --git a/src/domain/process/processCapture.ts b/src/domain/process/processCapture.ts
index 044d6b54d..8cbfbd799 100644
--- a/src/domain/process/processCapture.ts
+++ b/src/domain/process/processCapture.ts
@@ -4,7 +4,9 @@ import { jsonValueSchema } from "../jsonValue.js";
import { normalizationSchema } from "./processScenario.js";
import { collectProcessCaptureIssues } from "./processCaptureValidation.js";
import {
+ filesystemCoverageSchema,
processCaptureTruncationDetailsSchema,
+ type FilesystemCoverage,
type ProcessCaptureTruncationDetails,
} from "./processCaptureCoverage.js";
@@ -66,6 +68,15 @@ export type FileState = FileStateIdentity &
}
);
+/** Complete metadata returned for one root-aliased filesystem checkpoint. */
+export interface ProcessFilesystemSnapshot {
+ readonly files: readonly FileState[];
+ readonly truncated: boolean;
+ /** Root aliases whose path enumeration was exhausted, regardless of hash coverage. */
+ readonly completeRoots: readonly string[];
+ readonly coverage: FilesystemCoverage;
+}
+
interface FileEffectIdentity {
readonly path: string;
}
@@ -208,8 +219,8 @@ export interface UnverifiedProcessCapture {
readonly files_after: readonly FileState[];
readonly filesystem_effects: readonly FileEffect[];
readonly truncated: boolean;
- /** Optional on older captures; identifies each producer's actual coverage. */
- readonly truncation_details?: ProcessCaptureTruncationDetails | undefined;
+ /** Per-source accounting for the producer's actual capture coverage. */
+ readonly truncation_details: ProcessCaptureTruncationDetails;
readonly limitations: readonly string[];
readonly residual_unknowns: readonly {
readonly scope:
@@ -265,14 +276,6 @@ export type PartialProcessObservationField<T> =
| { readonly state: "available"; readonly value: T }
| { readonly state: "unavailable"; readonly reason: string };
-/** Snapshot facts available before filesystem comparison can be completed. */
-/** Snapshot facts available before filesystem comparison can be completed. */
-export interface PartialFilesystemSnapshot {
- readonly files: readonly FileState[];
- readonly truncated: boolean;
-}
-
-/** Available and unavailable fields when a run never becomes a full capture. */
/** Available and unavailable fields when a run never becomes a full capture. */
export interface IncompleteProcessCaptureObservations {
readonly target_pid: PartialProcessObservationField<number>;
@@ -296,8 +299,8 @@ export interface IncompleteProcessCaptureObservations {
readonly ProcessSample[]
>;
readonly filesystem_snapshots: {
- readonly before: PartialProcessObservationField<PartialFilesystemSnapshot>;
- readonly after: PartialProcessObservationField<PartialFilesystemSnapshot>;
+ readonly before: PartialProcessObservationField<ProcessFilesystemSnapshot>;
+ readonly after: PartialProcessObservationField<ProcessFilesystemSnapshot>;
};
readonly event_journal: PartialProcessObservationField<
readonly ProcessCaptureEventJournalEntry[]
@@ -330,6 +333,13 @@ const fileStateSchema = z.discriminatedUnion("type", [
symlink_target: z.null(),
}),
]);
+/** Canonical checkpoint facts retained even when capture completion fails. */
+export const processFilesystemSnapshotSchema = z.strictObject({
+ files: z.array(fileStateSchema),
+ truncated: z.boolean(),
+ completeRoots: z.array(z.string()),
+ coverage: filesystemCoverageSchema,
+});
const fileEffectSchema = z.discriminatedUnion("status", [
z.object({
path: z.string(),
@@ -481,7 +491,7 @@ const processCaptureShapeSchema = z.strictObject({
files_after: z.array(fileStateSchema),
filesystem_effects: z.array(fileEffectSchema),
truncated: z.boolean(),
- truncation_details: processCaptureTruncationDetailsSchema.optional(),
+ truncation_details: processCaptureTruncationDetailsSchema,
limitations: z.array(z.string()),
residual_unknowns: z.array(
z.object({
@@ -545,18 +555,8 @@ const incompleteProcessCaptureObservationsSchema = z.strictObject({
processCaptureShapeSchema.shape.process_samples,
),
filesystem_snapshots: z.strictObject({
- before: partialObservationFieldSchema(
- z.strictObject({
- files: z.array(fileStateSchema),
- truncated: z.boolean(),
- }),
- ),
- after: partialObservationFieldSchema(
- z.strictObject({
- files: z.array(fileStateSchema),
- truncated: z.boolean(),
- }),
- ),
+ before: partialObservationFieldSchema(processFilesystemSnapshotSchema),
+ after: partialObservationFieldSchema(processFilesystemSnapshotSchema),
}),
event_journal: partialObservationFieldSchema(
processCaptureShapeSchema.shape.event_journal,
diff --git a/src/domain/process/processCapture.validation.test.ts b/src/domain/process/processCapture.validation.test.ts
index 80183aab7..0573c0052 100644
--- a/src/domain/process/processCapture.validation.test.ts
+++ b/src/domain/process/processCapture.validation.test.ts
@@ -9,35 +9,20 @@ import {
} from "./processCapture.fixture.js";
it("never considers truncated captures equivalent", () => {
+ const complete = emptyCapture();
const capture = {
- manifest: emptyCapture().manifest,
- settlement: emptyCapture().settlement,
- normalization: {
- paths: true,
- pids: true,
- ports: true,
- time_bucket_ms: 10,
- patterns: [],
- },
- frames: [],
- rendered_frames: [],
- interaction_events: [],
- exit: { code: 0, signal: null, reason: "exited" as const },
- process_samples: [],
- filesystem_checkpoints: emptyCapture().filesystem_checkpoints,
- event_journal: [],
- files_before: [],
- files_after: [],
- filesystem_effects: [],
+ ...complete,
truncated: true,
- limitations: [],
- residual_unknowns: [],
- cleanup: {
- owned_process_group: "verified" as const,
- temporary_root: "removed" as const,
+ truncation_details: {
+ ...complete.truncation_details,
+ raw_terminal: {
+ ...complete.truncation_details.raw_terminal,
+ observed_bytes: 1,
+ observed_frames: 1,
+ },
},
};
- expect(compareProcessCaptures(capture, capture).status).toBe("truncated");
+ expect(compareProcessCaptures(capture, capture).status).toBe("unknown");
});
it("rejects altered v4 commitments and accepts canonical key reordering", () => {
@@ -66,6 +51,14 @@ it("rejects altered v4 commitments and accepts canonical key reordering", () =>
).toThrow("executable_identity");
});
+it("requires producer coverage accounting in every parsed capture", () => {
+ const capture = emptyCapture();
+ const { truncation_details: _details, ...missingCoverage } = capture;
+ expect(() => parseProcessCapture(missingCoverage)).toThrow(
+ "truncation_details",
+ );
+});
+
it("rejects settlement and cleanup combinations that cannot occur", () => {
const capture = emptyCapture();
expect(() =>
diff --git a/src/domain/process/processCaptureCoverage.ts b/src/domain/process/processCaptureCoverage.ts
index 5365961ef..a93972912 100644
--- a/src/domain/process/processCaptureCoverage.ts
+++ b/src/domain/process/processCaptureCoverage.ts
@@ -63,7 +63,7 @@ const omitted = (retention: TerminalRetention): boolean =>
const filesystemTruncated = (coverage: FilesystemCoverage): boolean =>
coverage.enumeration_truncated || coverage.hash_omissions.length > 0;
-/** Derive the legacy aggregate flag from independent producer observations. */
+/** Derive the aggregate truncation flag from independent producer observations. */
export const hasCaptureTruncation = (
details: ProcessCaptureTruncationDetails,
): boolean =>
@@ -73,13 +73,12 @@ export const hasCaptureTruncation = (
filesystemTruncated(details.filesystem_after) ||
details.process.sampling_partial;
-/** Older truncated captures lack enough information to localize missing observations. */
+/** Whether producer accounting reports a gap in the selected observation source. */
export const processSourceTruncated = (
capture: UnverifiedProcessCapture,
source: ProcessObservationSource,
): boolean => {
const details = capture.truncation_details;
- if (details === undefined) return capture.truncated;
switch (source) {
case "terminal_raw":
return omitted(details.raw_terminal);
diff --git a/src/domain/process/processCaptureExample.ts b/src/domain/process/processCaptureExample.ts
index 91098581c..6c177a535 100644
--- a/src/domain/process/processCaptureExample.ts
+++ b/src/domain/process/processCaptureExample.ts
@@ -59,6 +59,49 @@ export const EMPTY_PROCESS_CAPTURE_EXAMPLE = {
files_after: [],
filesystem_effects: [],
truncated: false,
+ truncation_details: {
+ raw_terminal: {
+ budget_bytes: 1_000_000,
+ observed_bytes: 0,
+ retained_bytes: 0,
+ observed_frames: 0,
+ retained_frames: 0,
+ },
+ rendered_terminal: {
+ budget_bytes: 1_000_000,
+ observed_bytes: 0,
+ retained_bytes: 0,
+ observed_frames: 0,
+ retained_frames: 0,
+ },
+ filesystem_before: {
+ files_limit: 10_000,
+ depth_limit: 16,
+ enumeration_truncated: false,
+ enumeration_reasons: [],
+ hash_budget_bytes: 10_000_000,
+ hashed_bytes: 0,
+ hash_omissions: [],
+ },
+ filesystem_after: {
+ files_limit: 10_000,
+ depth_limit: 16,
+ enumeration_truncated: false,
+ enumeration_reasons: [],
+ hash_budget_bytes: 10_000_000,
+ hashed_bytes: 0,
+ hash_omissions: [],
+ },
+ process: {
+ sample_limit: 1_000,
+ sampling_partial: false,
+ retained_samples: 0,
+ sample_limit_reached: false,
+ sampling_failures: 0,
+ first_sampling_failure: null,
+ coverage: "sampled",
+ },
+ },
limitations: [],
residual_unknowns: [],
cleanup: {
diff --git a/src/domain/process/processCaptureValidation.ts b/src/domain/process/processCaptureValidation.ts
index b8bc953d3..fe5479689 100644
--- a/src/domain/process/processCaptureValidation.ts
+++ b/src/domain/process/processCaptureValidation.ts
@@ -127,7 +127,6 @@ const validateCoverage = (
require: RequireInvariant,
): void => {
const details = capture.truncation_details;
- if (details === undefined) return;
require(details.process.retained_samples === capture.process_samples.length &&
details.process.retained_samples <= details.process.sample_limit &&
details.process.sampling_partial ===
diff --git a/src/domain/process/processComparison.ts b/src/domain/process/processComparison.ts
index 47264ef46..9db90cfb7 100644
--- a/src/domain/process/processComparison.ts
+++ b/src/domain/process/processComparison.ts
@@ -291,20 +291,6 @@ const differingContractFields = (
)
.sort();
-const truncatedComparison = (): ProcessCaptureComparison => ({
- status: "truncated",
- terminal: "truncated",
- interaction: "truncated",
- exit: "truncated",
- filesystem: "truncated",
- process: "truncated",
- first_divergence: {
- status: "unknown",
- reason: "At least one capture is truncated.",
- },
- limitations: ["At least one capture is truncated."],
-});
-
const applyTraceVerdict = (
dimensions: ComparisonDimensions,
specification: ProcessTraceSpecification,
@@ -427,18 +413,6 @@ export const compareProcessCaptures = (
} = {},
): ProcessCaptureComparison => {
assertComparable(left, right, options);
- if (
- (left.truncated && left.truncation_details === undefined) ||
- (right.truncated && right.truncation_details === undefined)
- ) {
- const truncated = truncatedComparison();
- return options.traceSpecification === undefined
- ? truncated
- : {
- ...truncated,
- trace: compareProcessTraces(left, right, options.traceSpecification),
- };
- }
const sameNormalization = sameJsonValue(
left.normalization,
right.normalization,
diff --git a/src/domain/process/processTraceAdapters.test.ts b/src/domain/process/processTraceAdapters.test.ts
index 5589e40cb..18cdea5c6 100644
--- a/src/domain/process/processTraceAdapters.test.ts
+++ b/src/domain/process/processTraceAdapters.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it } from "vitest";
import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "./processCaptureExample.js";
+import { accountFullyObservedProcessCapture } from "./processCapture.fixture.js";
import { compareProcessCaptures } from "./processComparison.js";
import { parseProcessCapture } from "./processCaptureParsing.js";
import type { ProcessTraceSpecification } from "./processTraceSpecification.js";
@@ -94,26 +95,29 @@ describe("declared trace comparison nonconformance", () => {
});
it("does not mask distinct payloads when both traces are nonconforming", () => {
+ const parsedCapture = parseProcessCapture(capture);
const withTerminal = (data: string) =>
- parseProcessCapture({
- ...capture,
- frames: [{ sequence: 0, at_ms: 1, data }],
- event_journal: [
- {
- capture_order: 0,
- collection: "filesystem_checkpoints",
- index: 0,
- },
- { capture_order: 1, collection: "frames", index: 0 },
- { capture_order: 2, collection: "lifecycle", index: 0 },
- { capture_order: 3, collection: "lifecycle", index: 1 },
- {
- capture_order: 4,
- collection: "filesystem_checkpoints",
- index: 1,
- },
- ],
- });
+ parseProcessCapture(
+ accountFullyObservedProcessCapture({
+ ...parsedCapture,
+ frames: [{ sequence: 0, at_ms: 1, data }],
+ event_journal: [
+ {
+ capture_order: 0,
+ collection: "filesystem_checkpoints",
+ index: 0,
+ },
+ { capture_order: 1, collection: "frames", index: 0 },
+ { capture_order: 2, collection: "lifecycle", index: 0 },
+ { capture_order: 3, collection: "lifecycle", index: 1 },
+ {
+ capture_order: 4,
+ collection: "filesystem_checkpoints",
+ index: 1,
+ },
+ ],
+ }),
+ );
const specification: ProcessTraceSpecification = {
events: [
{
diff --git a/src/domain/process/processTraceComparison.fixture.ts b/src/domain/process/processTraceComparison.fixture.ts
index 244045e1c..b63f7e6c7 100644
--- a/src/domain/process/processTraceComparison.fixture.ts
+++ b/src/domain/process/processTraceComparison.fixture.ts
@@ -1,4 +1,5 @@
import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "./processCaptureExample.js";
+import { hasCaptureTruncation } from "./processCaptureCoverage.js";
import {
parseProcessCapture,
type ProcessCapture,
@@ -24,11 +25,30 @@ export const capture = (
>[];
},
options: {
- readonly truncated?: boolean;
+ readonly omittedTerminalFrame?: boolean;
readonly residualUnknowns?: ProcessCapture["residual_unknowns"];
} = {},
-): ProcessCapture =>
- parseProcessCapture({
+): ProcessCapture => {
+ const omittedTerminalFrame = options.omittedTerminalFrame ?? false;
+ const retainedBytes = values.frames.reduce(
+ (total, frame) => total + Buffer.byteLength(frame.raw_data ?? frame.data),
+ 0,
+ );
+ const truncationDetails = {
+ ...emptyCapture.truncation_details,
+ raw_terminal: {
+ ...emptyCapture.truncation_details.raw_terminal,
+ observed_bytes: retainedBytes + (omittedTerminalFrame ? 1 : 0),
+ retained_bytes: retainedBytes,
+ observed_frames: values.frames.length + (omittedTerminalFrame ? 1 : 0),
+ retained_frames: values.frames.length,
+ },
+ process: {
+ ...emptyCapture.truncation_details.process,
+ retained_samples: values.process_samples.length,
+ },
+ };
+ return parseProcessCapture({
...emptyCapture,
frames: values.frames,
process_samples: values.process_samples,
@@ -54,9 +74,11 @@ export const capture = (
index: 1,
},
],
- truncated: options.truncated ?? false,
+ truncated: hasCaptureTruncation(truncationDetails),
+ truncation_details: truncationDetails,
residual_unknowns: options.residualUnknowns ?? [],
});
+};
export const values = (
order: readonly ("terminal" | "process")[],
diff --git a/src/domain/process/processTraceComparison.test.ts b/src/domain/process/processTraceComparison.test.ts
index 0dffc404d..952bb9758 100644
--- a/src/domain/process/processTraceComparison.test.ts
+++ b/src/domain/process/processTraceComparison.test.ts
@@ -219,7 +219,7 @@ describe("unknown process trace evidence", () => {
it("never proves equivalence from truncated, unknown, or journal-free evidence", () => {
const complete = capture(values(["terminal", "process"]));
const truncated = capture(values(["terminal", "process"]), {
- truncated: true,
+ omittedTerminalFrame: true,
});
expect(
compareProcessTraces(complete, truncated, partialSpecification()).verdict,
diff --git a/src/domain/webCaptureDiffSchemas.ts b/src/domain/webCaptureDiffSchemas.ts
index b60827cb3..3efd74581 100644
--- a/src/domain/webCaptureDiffSchemas.ts
+++ b/src/domain/webCaptureDiffSchemas.ts
@@ -58,13 +58,6 @@ const dimensionSchema = z.union([
reason: z.string(),
}),
]);
-const legacyUnknownDimension: z.input<typeof dimensionSchema> = {
- status: "unknown",
- total_changes: 0,
- changes: [],
- reason: "Dimension was not recorded by this version 1 capture diff.",
-};
-
/** Completeness-aware changes across stable browser evidence dimensions. */
export const webCaptureDiffSchema = z
.object({
@@ -78,8 +71,8 @@ export const webCaptureDiffSchema = z
network: dimensionSchema,
metadata: dimensionSchema,
webmcp: dimensionSchema,
- accessibility: dimensionSchema.default(legacyUnknownDimension),
- storage: dimensionSchema.default(legacyUnknownDimension),
+ accessibility: dimensionSchema,
+ storage: dimensionSchema,
}),
limitations: z.array(z.string()),
})
diff --git a/src/domain/webScriptExport.ts b/src/domain/webScriptExport.ts
index 71b45cfaf..7e3dc36b8 100644
--- a/src/domain/webScriptExport.ts
+++ b/src/domain/webScriptExport.ts
@@ -34,7 +34,7 @@ const sourceSchema = z.discriminatedUnion("kind", [
}),
z.strictObject({
kind: z.literal("scenario-response"),
- transaction_id: z.string().nullable(),
+ transaction_id: z.string().min(1),
request_sequence: z.number().int().min(1),
response_sequence: z.number().int().min(1).nullable(),
status: z.number().nullable(),
diff --git a/src/process/capture/FilesystemSnapshot.ts b/src/process/capture/FilesystemSnapshot.ts
index f5b775bb0..281151afc 100644
--- a/src/process/capture/FilesystemSnapshot.ts
+++ b/src/process/capture/FilesystemSnapshot.ts
@@ -3,17 +3,12 @@ import { constants as fsConstants } from "node:fs";
import { lstat, open, readdir, readlink } from "node:fs/promises";
import { dirname, join, relative, resolve } from "node:path";
import type { ProcessScenario } from "../../domain/process/processScenario.js";
-import type { Stats } from "node:fs";
import type { FilesystemCoverage } from "../../domain/process/processCaptureCoverage.js";
-
-import type { FileState } from "../../domain/process/processCapture.js";
-export interface SnapshotResult {
- readonly files: readonly FileState[];
- readonly truncated: boolean;
- /** Root aliases whose path enumeration was exhausted, regardless of hash coverage. */
- readonly completeRoots: readonly string[];
- readonly coverage?: FilesystemCoverage;
-}
+import type { Stats } from "node:fs";
+import type {
+ FileState,
+ ProcessFilesystemSnapshot,
+} from "../../domain/process/processCapture.js";
const hasSameIdentity = (
before: Stats,
@@ -92,7 +87,7 @@ export const hashFile = async (
export const snapshotRoots = async (
scenario: ProcessScenario,
signal?: AbortSignal,
-): Promise<SnapshotResult> => {
+): Promise<ProcessFilesystemSnapshot> => {
const entries: FileState[] = [];
const completeRoots: string[] = [];
let remainingBytes = scenario.limits.file_bytes;
diff --git a/src/process/capture/ProcessCaptureLifecycle.ts b/src/process/capture/ProcessCaptureLifecycle.ts
index 14da87231..af439e9dd 100644
--- a/src/process/capture/ProcessCaptureLifecycle.ts
+++ b/src/process/capture/ProcessCaptureLifecycle.ts
@@ -15,7 +15,6 @@ import {
} from "../../domain/process/processScenario.js";
import { parseProcessCapture } from "../../domain/process/processCaptureParsing.js";
import { PRODUCT_IDENTITY } from "../../identity.js";
-import type { SnapshotResult } from "./FilesystemSnapshot.js";
import { snapshotRoots } from "./FilesystemSnapshot.js";
import { classifyFilesystemEffects } from "./ProcessFilesystemEffects.js";
import {
@@ -59,7 +58,7 @@ import type {
ProcessCaptureCleanupReport,
PartialProcessCaptureObservation,
IncompleteProcessCaptureObservations,
- PartialFilesystemSnapshot,
+ ProcessFilesystemSnapshot,
PartialProcessObservationField,
ProcessCaptureEventJournalEntry,
RecordProcessCaptureEvent,
@@ -86,10 +85,9 @@ interface CaptureResultOptions {
readonly reason: "exited" | "timeout" | "idle_timeout";
};
readonly samples: readonly ProcessSample[];
- readonly before: SnapshotResult;
- readonly after: SnapshotResult;
- readonly truncated: boolean;
- readonly truncationDetails?: ProcessCaptureTruncationDetails;
+ readonly before: ProcessFilesystemSnapshot;
+ readonly after: ProcessFilesystemSnapshot;
+ readonly truncationDetails: ProcessCaptureTruncationDetails;
readonly scenario: ProcessScenario;
readonly rootPid: number;
readonly samplingPartial: boolean;
@@ -134,8 +132,8 @@ export interface ProcessCaptureObservationBuffer {
settlement: IncompleteProcessCaptureObservations["settlement"];
process_samples: PartialProcessObservationField<readonly ProcessSample[]>;
filesystem_snapshots: {
- before: PartialProcessObservationField<PartialFilesystemSnapshot>;
- after: PartialProcessObservationField<PartialFilesystemSnapshot>;
+ before: PartialProcessObservationField<ProcessFilesystemSnapshot>;
+ after: PartialProcessObservationField<ProcessFilesystemSnapshot>;
};
event_journal: PartialProcessObservationField<
readonly ProcessCaptureEventJournalEntry[]
@@ -149,7 +147,7 @@ export const createProcessCaptureObservationBuffer = (options: {
readonly interactions: readonly InteractionEvent[];
readonly samples: readonly ProcessSample[];
readonly eventJournal: readonly ProcessCaptureEventJournalEntry[];
- readonly before: SnapshotResult;
+ readonly before: ProcessFilesystemSnapshot;
}): ProcessCaptureObservationBuffer => ({
target_pid: {
state: "unavailable",
@@ -175,10 +173,7 @@ export const createProcessCaptureObservationBuffer = (options: {
filesystem_snapshots: {
before: {
state: "available",
- value: {
- files: options.before.files,
- truncated: options.before.truncated,
- },
+ value: options.before,
},
after: {
state: "unavailable",
@@ -285,13 +280,8 @@ export const buildCaptureResult = (
files_before: options.before.files,
files_after: options.after.files,
filesystem_effects: filesystemEffects,
- truncated:
- options.truncationDetails === undefined
- ? options.truncated
- : hasCaptureTruncation(options.truncationDetails),
- ...(options.truncationDetails === undefined
- ? {}
- : { truncation_details: options.truncationDetails }),
+ truncated: hasCaptureTruncation(options.truncationDetails),
+ truncation_details: options.truncationDetails,
limitations: [
"The executable digest is a prelaunch file sample; matching path metadata immediately after spawn does not prove an atomic operating-system image binding.",
"Process trees are sampled and may omit short-lived descendants.",
@@ -302,11 +292,9 @@ export const buildCaptureResult = (
"Inherited host environment variables are not recorded and may affect results.",
...(!hasFilesystemObservations ? [filesystemObservationUnknown] : []),
...(hasUnknownFilesystemEffects ? [incompleteFilesystemUnknown] : []),
- ...(options.truncationDetails === undefined
- ? []
- : captureCoverageUnknowns(options.truncationDetails).map(
- ({ reason }) => reason,
- )),
+ ...captureCoverageUnknowns(options.truncationDetails).map(
+ ({ reason }) => reason,
+ ),
...(hasSensitiveScriptedInput ? [sensitiveInputUnknown] : []),
],
residual_unknowns: [
@@ -347,11 +335,9 @@ export const buildCaptureResult = (
...(hasSensitiveScriptedInput
? [{ scope: "interaction" as const, reason: sensitiveInputUnknown }]
: []),
- ...(options.truncationDetails === undefined
- ? []
- : captureCoverageUnknowns(options.truncationDetails).filter(
- ({ scope }) => scope !== "terminal",
- )),
+ ...captureCoverageUnknowns(options.truncationDetails).filter(
+ ({ scope }) => scope !== "terminal",
+ ),
],
};
};
@@ -1106,7 +1092,7 @@ export const prepareProcessCapture = async (
readonly temporaryRoot: string;
readonly runId: string;
readonly ownershipBaseline: ProcessOwnershipBaseline;
- readonly before: SnapshotResult;
+ readonly before: ProcessFilesystemSnapshot;
}> => {
assertNotCancelled(signal);
await host.prepareOwnershipInspector?.(signal);
diff --git a/src/process/capture/ProcessCaptureObservation.test.ts b/src/process/capture/ProcessCaptureObservation.test.ts
index 7a1ccd008..7bd54a124 100644
--- a/src/process/capture/ProcessCaptureObservation.test.ts
+++ b/src/process/capture/ProcessCaptureObservation.test.ts
@@ -6,6 +6,7 @@ import { isInitializedPtyRoot, readLinuxChildren } from "./ProcessSampling.js";
import { TerminalRenderer } from "./TerminalRenderer.js";
import { parseProcessScenario } from "../../domain/process/processScenario.js";
import { type ProcessCapture } from "../../domain/process/processCaptureParsing.js";
+import type { ProcessCaptureTruncationDetails } from "../../domain/process/processCaptureCoverage.js";
import { emptyProcessCapture as emptyCapture } from "../../domain/process/processCapture.fixture.js";
const base = {
@@ -13,6 +14,51 @@ const base = {
working_directory: "/tmp",
};
+const emptyFilesystemCoverage = () =>
+ emptyCapture().truncation_details.filesystem_before;
+
+const truncationDetails = (
+ frames: readonly ProcessCapture["frames"][number][],
+ renderedFrames: readonly ProcessCapture["rendered_frames"][number][],
+ samples: readonly ProcessCapture["process_samples"][number][],
+): ProcessCaptureTruncationDetails => {
+ const emptyDetails = emptyCapture().truncation_details;
+ const rawBytes = frames.reduce(
+ (total, frame) => total + Buffer.byteLength(frame.raw_data ?? frame.data),
+ 0,
+ );
+ const renderedBytes = renderedFrames.reduce(
+ (total, frame) =>
+ frame.lines.reduce(
+ (sum, line) => sum + Buffer.byteLength(line),
+ total + Buffer.byteLength(frame.serialized_state),
+ ),
+ 0,
+ );
+ return {
+ raw_terminal: {
+ ...emptyDetails.raw_terminal,
+ observed_bytes: rawBytes,
+ retained_bytes: rawBytes,
+ observed_frames: frames.length,
+ retained_frames: frames.length,
+ },
+ rendered_terminal: {
+ ...emptyDetails.rendered_terminal,
+ observed_bytes: renderedBytes,
+ retained_bytes: renderedBytes,
+ observed_frames: renderedFrames.length,
+ retained_frames: renderedFrames.length,
+ },
+ filesystem_before: emptyDetails.filesystem_before,
+ filesystem_after: emptyDetails.filesystem_after,
+ process: {
+ ...emptyDetails.process,
+ retained_samples: samples.length,
+ },
+ };
+};
+
it("returns detached terminal observations", async () => {
const observed: string[] = [];
const renderer = new TerminalRenderer({
@@ -72,9 +118,19 @@ it("preserves rendered observation order instead of timestamp sorting", () => {
frames: [],
exit: { exitCode: 0, reason: "exited" },
samples: [],
- before: { files: [], truncated: false, completeRoots: [] },
- after: { files: [], truncated: false, completeRoots: [] },
- truncated: false,
+ before: {
+ files: [],
+ truncated: false,
+ completeRoots: [],
+ coverage: emptyFilesystemCoverage(),
+ },
+ after: {
+ files: [],
+ truncated: false,
+ completeRoots: [],
+ coverage: emptyFilesystemCoverage(),
+ },
+ truncationDetails: truncationDetails([], renderedFrames, []),
scenario: parseProcessScenario(base),
rootPid: 1,
samplingPartial: false,
@@ -98,9 +154,19 @@ it("marks redacted scripted input as an interaction unknown", () => {
frames: [],
exit: { exitCode: 0, reason: "exited" },
samples: [],
- before: { files: [], truncated: false, completeRoots: [] },
- after: { files: [], truncated: false, completeRoots: [] },
- truncated: false,
+ before: {
+ files: [],
+ truncated: false,
+ completeRoots: [],
+ coverage: emptyFilesystemCoverage(),
+ },
+ after: {
+ files: [],
+ truncated: false,
+ completeRoots: [],
+ coverage: emptyFilesystemCoverage(),
+ },
+ truncationDetails: truncationDetails([], [], []),
scenario: parseProcessScenario({
...base,
events: [{ type: "input", at_ms: 0, data: "secret", sensitive: true }],
diff --git a/src/process/capture/ProcessFilesystemEffects.ts b/src/process/capture/ProcessFilesystemEffects.ts
index ec47c90ec..97ae578c4 100644
--- a/src/process/capture/ProcessFilesystemEffects.ts
+++ b/src/process/capture/ProcessFilesystemEffects.ts
@@ -1,9 +1,9 @@
import type {
FileState,
FilesystemCheckpoint,
+ ProcessFilesystemSnapshot,
} from "../../domain/process/processCapture.js";
import { sep } from "node:path";
-import type { SnapshotResult } from "./FilesystemSnapshot.js";
const unobservedAbsenceReason = (
path: string,
@@ -31,8 +31,8 @@ const unobservedAbsenceReason = (
/** Classify effects only when a snapshot establishes the missing path's absence. */
export const classifyFilesystemEffects = (
- before: SnapshotResult,
- after: SnapshotResult,
+ before: ProcessFilesystemSnapshot,
+ after: ProcessFilesystemSnapshot,
): FilesystemCheckpoint["effects"] => {
const beforeByPath = new Map(before.files.map((file) => [file.path, file]));
const afterByPath = new Map(after.files.map((file) => [file.path, file]));
diff --git a/src/process/capture/ProcessHarness.test.ts b/src/process/capture/ProcessHarness.test.ts
index c96964f67..65ca8d3d5 100644
--- a/src/process/capture/ProcessHarness.test.ts
+++ b/src/process/capture/ProcessHarness.test.ts
@@ -6,7 +6,10 @@ import { settleProcessCaptureJournal } from "./ProcessCaptureLifecycle.js";
import { parseProcessCapture } from "../../domain/process/processCaptureParsing.js";
import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../../domain/process/processCaptureExample.js";
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
-import { emptyProcessCapture } from "../../domain/process/processCapture.fixture.js";
+import {
+ accountFullyObservedProcessCapture,
+ emptyProcessCapture,
+} from "../../domain/process/processCapture.fixture.js";
import { analysisErrorProjectionSchema } from "../../contracts/errorSchemas.js";
import {
ProcessCaptureError,
@@ -15,6 +18,7 @@ import {
} from "./ProcessCaptureError.js";
import {
releaseProcessResources,
+ createProcessCaptureObservationBuffer,
prepareProcessCapture,
resolveProcessResult,
type ProcessCaptureCleanupHost,
@@ -25,6 +29,13 @@ import {
partialProcessCaptureObservationSchema,
processCaptureSchema,
} from "../../domain/process/processCapture.js";
+const emptyFilesystemCoverage =
+ emptyProcessCapture().truncation_details.filesystem_before;
+const incompleteFilesystemCoverage = {
+ ...emptyFilesystemCoverage,
+ enumeration_truncated: true,
+ enumeration_reasons: ["identity_changed"],
+} satisfies typeof emptyFilesystemCoverage;
it("retains cancellation and cleanup facts when ownership baseline inspection aborts", async () => {
const controller = new AbortController();
const scenario = processScenarioSchema.parse({
@@ -34,7 +45,12 @@ it("retains cancellation and cleanup facts when ownership baseline inspection ab
prepareProcessCapture(
scenario,
controller.signal,
- async () => ({ files: [], truncated: false, completeRoots: [] }),
+ async () => ({
+ files: [],
+ truncated: false,
+ completeRoots: [],
+ coverage: emptyFilesystemCoverage,
+ }),
{
createTemporaryRoot: async () => "/fixture/allocated-root",
captureOwnershipBaseline: async () => {
@@ -56,7 +72,12 @@ it("retains cancellation and cleanup facts when ownership baseline inspection ab
filesystem_snapshots: {
before: {
state: "available",
- value: { files: [], truncated: false },
+ value: {
+ files: [],
+ truncated: false,
+ completeRoots: [],
+ coverage: emptyFilesystemCoverage,
+ },
},
},
},
@@ -68,12 +89,18 @@ it("keeps prelaunch snapshot evidence and the ownership failure when root cleanu
const ownershipFailure = new Error("process identity baseline denied");
const scenario = processScenarioSchema.parse({
executable: process.execPath,
+ filesystem_observation_paths: ["/fixture/root"],
});
try {
await prepareProcessCapture(
scenario,
undefined,
- async () => ({ files: [], truncated: true, completeRoots: [] }),
+ async () => ({
+ files: [],
+ truncated: true,
+ completeRoots: [],
+ coverage: incompleteFilesystemCoverage,
+ }),
{
createTemporaryRoot: async () => "/fixture/allocated-root",
captureOwnershipBaseline: async () => {
@@ -102,7 +129,12 @@ it("keeps prelaunch snapshot evidence and the ownership failure when root cleanu
filesystem_snapshots: {
before: {
state: "available",
- value: { files: [], truncated: true },
+ value: {
+ files: [],
+ truncated: true,
+ completeRoots: [],
+ coverage: incompleteFilesystemCoverage,
+ },
},
},
},
@@ -112,6 +144,76 @@ it("keeps prelaunch snapshot evidence and the ownership failure when root cleanu
}
});
+it("projects complete after-snapshot metadata when a later capture stage fails", () => {
+ const scenario = processScenarioSchema.parse({
+ executable: process.execPath,
+ filesystem_observation_paths: ["/fixture/root"],
+ });
+ const observations = createProcessCaptureObservationBuffer({
+ frames: [],
+ interactions: [],
+ samples: [],
+ eventJournal: [],
+ before: {
+ files: [],
+ truncated: false,
+ completeRoots: [],
+ coverage: emptyFilesystemCoverage,
+ },
+ });
+ observations.filesystem_snapshots.after = {
+ state: "available",
+ value: {
+ files: [],
+ truncated: true,
+ completeRoots: [],
+ coverage: incompleteFilesystemCoverage,
+ },
+ };
+ const cleanup = {
+ owned_process_group: { state: "cleaned" as const, reason: null },
+ terminal_renderer: { state: "cleaned" as const, reason: null },
+ temporary_root: { state: "cleaned" as const, reason: null },
+ };
+
+ let error: ProcessCaptureError | undefined;
+ try {
+ resolveProcessResult(
+ undefined,
+ new Error("capture manifest failed after final snapshot"),
+ cleanup,
+ observations,
+ { scenario },
+ );
+ } catch (cause: unknown) {
+ if (!(cause instanceof ProcessCaptureError)) throw cause;
+ error = cause;
+ }
+ if (error === undefined) throw new Error("expected capture failure");
+
+ expect(
+ analysisErrorProjectionSchema.parse(projectAnalysisError(error)),
+ ).toMatchObject({
+ details: {
+ partial_observation: {
+ observations: {
+ filesystem_snapshots: {
+ after: {
+ state: "available",
+ value: {
+ files: [],
+ truncated: true,
+ completeRoots: [],
+ coverage: incompleteFilesystemCoverage,
+ },
+ },
+ },
+ },
+ },
+ },
+ });
+});
+
it("rejects legacy replay output instead of silently discarding it", () => {
expect(
processCaptureSchema.safeParse({
@@ -230,8 +332,10 @@ it.each(["termination", "verification"] as const)(
const executionFailure = new Error("capture snapshot failed");
const capture = parseProcessCapture({
- ...emptyProcessCapture(),
- frames: [{ sequence: 0, at_ms: 0, data: "collected before failure" }],
+ ...accountFullyObservedProcessCapture({
+ ...emptyProcessCapture(),
+ frames: [{ sequence: 0, at_ms: 0, data: "collected before failure" }],
+ }),
event_journal: [],
});
try {
@@ -441,18 +545,20 @@ it("passes sampled detached groups into cleanup even when their token is unknown
it("retains observations and both causes when process cleanup is unverifiable", () => {
const verified = emptyProcessCapture();
const capture = parseProcessCapture({
- ...verified,
- frames: [{ sequence: 0, at_ms: 0, data: "observed output" }],
- process_samples: [
- {
- at_ms: 1,
- pid: 654,
- parent_pid: 321,
- command: "sanitized-detached-child",
- process_group_id: 654,
- session_id: 654,
- },
- ],
+ ...accountFullyObservedProcessCapture({
+ ...verified,
+ frames: [{ sequence: 0, at_ms: 0, data: "observed output" }],
+ process_samples: [
+ {
+ at_ms: 1,
+ pid: 654,
+ parent_pid: 321,
+ command: "sanitized-detached-child",
+ process_group_id: 654,
+ session_id: 654,
+ },
+ ],
+ }),
event_journal: [],
});
const executionFailure = new Error("capture ended after a fixture error");
@@ -561,8 +667,10 @@ it("projects execution and cleanup failures when capture never completed", () =>
it("retains completed observations when finalization fails after clean cleanup", () => {
const capture = parseProcessCapture({
- ...emptyProcessCapture(),
- frames: [{ sequence: 0, at_ms: 0, data: "observed before finalization" }],
+ ...accountFullyObservedProcessCapture({
+ ...emptyProcessCapture(),
+ frames: [{ sequence: 0, at_ms: 0, data: "observed before finalization" }],
+ }),
event_journal: [],
});
const executionFailure = new Error("final filesystem snapshot failed");
@@ -614,8 +722,10 @@ it("retains completed observations when finalization fails after clean cleanup",
it("preserves cancellation while projecting observations and successful cleanup", () => {
const capture = parseProcessCapture({
- ...emptyProcessCapture(),
- frames: [{ sequence: 0, at_ms: 0, data: "observed before cancellation" }],
+ ...accountFullyObservedProcessCapture({
+ ...emptyProcessCapture(),
+ frames: [{ sequence: 0, at_ms: 0, data: "observed before cancellation" }],
+ }),
event_journal: [],
});
const cleanup = {
diff --git a/src/process/capture/ProcessHarness.ts b/src/process/capture/ProcessHarness.ts
index 9ffc882b6..f15210b15 100644
--- a/src/process/capture/ProcessHarness.ts
+++ b/src/process/capture/ProcessHarness.ts
@@ -333,7 +333,6 @@ const completeCapture = async (options: {
readonly exit: Awaited<ReturnType<typeof awaitTerminalExit>>;
readonly signal?: AbortSignal;
readonly captureSnapshot: typeof snapshotRoots;
- readonly initiallyTruncated: boolean;
readonly eventJournal: readonly ProcessCaptureEventJournalEntry[];
readonly observationBuffer: ProcessCaptureObservationBuffer;
readonly recordEvent: RecordProcessCaptureEvent;
@@ -385,7 +384,7 @@ const completeCapture = async (options: {
...options.observationBuffer.filesystem_snapshots,
after: {
state: "available",
- value: { files: after.files, truncated: after.truncated },
+ value: after,
},
};
options.recordEvent("filesystem_checkpoints", 1);
@@ -436,32 +435,19 @@ const completeCapture = async (options: {
throw cause;
}
options.observationBuffer.manifest = { state: "available", value: manifest };
- const truncated =
- options.initiallyTruncated ||
- after.truncated ||
- runtime.rawTerminalRetention().observed_frames >
- runtime.rawTerminalRetention().retained_frames ||
- checkpoints.some(({ truncated: partial }) => partial) ||
- samplingPartial ||
- runtime.renderer.truncated();
return buildCaptureResult({
frames: options.frames,
exit: { ...options.exit, reason },
samples: options.samples,
before: options.before,
after,
- truncated,
- ...(options.before.coverage === undefined || after.coverage === undefined
- ? {}
- : {
- truncationDetails: {
- raw_terminal: runtime.rawTerminalRetention(),
- rendered_terminal: runtime.renderer.retention(),
- filesystem_before: options.before.coverage,
- filesystem_after: after.coverage,
- process: sampling.coverage,
- },
- }),
+ truncationDetails: {
+ raw_terminal: runtime.rawTerminalRetention(),
+ rendered_terminal: runtime.renderer.retention(),
+ filesystem_before: options.before.coverage,
+ filesystem_after: after.coverage,
+ process: sampling.coverage,
+ },
scenario,
rootPid: runtime.terminal.pid,
samplingPartial,
@@ -558,7 +544,6 @@ const runProcessScenario = async (
samples,
interactions,
exit,
- initiallyTruncated: before.truncated,
eventJournal,
observationBuffer: observations,
recordEvent,
diff --git a/tests/boundary/browser/webCaptureDiff.test.ts b/tests/boundary/browser/webCaptureDiff.test.ts
index 8d59a1e3d..290e94550 100644
--- a/tests/boundary/browser/webCaptureDiff.test.ts
+++ b/tests/boundary/browser/webCaptureDiff.test.ts
@@ -91,17 +91,14 @@ describe("web capture diff", () => {
scripts: { ...result.dimensions.scripts, total_changes: 2 },
},
});
- const {
- accessibility: _accessibility,
- storage: _storage,
- ...legacy
- } = result.dimensions;
- const parsedLegacy = webCaptureDiffSchema.parse({
+ const { accessibility: _accessibility, ...missingAccessibility } =
+ result.dimensions;
+ expectInvalidDiff({
...result,
- dimensions: legacy,
+ dimensions: missingAccessibility,
});
- expect(parsedLegacy.dimensions.accessibility.status).toBe("unknown");
- expect(parsedLegacy.dimensions.storage.status).toBe("unknown");
+ const { storage: _storage, ...missingStorage } = result.dimensions;
+ expectInvalidDiff({ ...result, dimensions: missingStorage });
});
it("does not claim unchanged when a relevant section is incomplete", async () => {
diff --git a/tests/boundary/mcp/toolResult.test.ts b/tests/boundary/mcp/toolResult.test.ts
index 454e600a2..a71ac46f6 100644
--- a/tests/boundary/mcp/toolResult.test.ts
+++ b/tests/boundary/mcp/toolResult.test.ts
@@ -15,13 +15,25 @@ import { HopperProcessError } from "../../../src/domain/hopperErrors.js";
import { processScenarioSchema } from "../../../src/domain/process/processScenario.js";
import { ToolResultDelivery } from "../../../src/server/toolResult.js";
import { createEvidence, parseEvidence } from "../../../src/domain/evidence.js";
-import { emptyProcessCapture } from "../../../src/domain/process/processCapture.fixture.js";
+import {
+ accountFullyObservedProcessCapture,
+ emptyProcessCapture,
+} from "../../../src/domain/process/processCapture.fixture.js";
import type { JsonValue } from "../../../src/domain/jsonValue.js";
import { evidenceResultOf } from "../../../src/contracts/toolOutputSchemaPrimitives.js";
import { toolRegistrationOptions } from "../../../src/server/toolRegistrationOptions.js";
import type { IncompleteProcessCaptureObservations } from "../../../src/domain/process/processCapture.js";
const delivery = new ToolResultDelivery(STDIO_DEFAULT_MAX_BUFFER_SIZE);
+const emptyFilesystemCoverage =
+ emptyProcessCapture().truncation_details.filesystem_before;
+
+const captureWithObservedOutput = () =>
+ accountFullyObservedProcessCapture({
+ ...emptyProcessCapture(),
+ frames: [{ sequence: 0, at_ms: 0, data: "observed output" }],
+ event_journal: [],
+ });
const contract: ToolContract = {
name: "provider_neutral_fixture",
@@ -56,11 +68,7 @@ describe("completed partial process capture MCP projection", () => {
terminal_renderer: { state: "cleaned" as const, reason: null },
temporary_root: { state: "cleaned" as const, reason: null },
};
- const capture = {
- ...emptyProcessCapture(),
- frames: [{ sequence: 0, at_ms: 0, data: "observed output" }],
- event_journal: [],
- };
+ const capture = captureWithObservedOutput();
let failure: ProcessCaptureError | undefined;
try {
resolveProcessResult(
@@ -108,11 +116,7 @@ describe("completed partial process capture MCP projection", () => {
terminal_renderer: { state: "cleaned" as const, reason: null },
temporary_root: { state: "cleaned" as const, reason: null },
};
- const capture = {
- ...emptyProcessCapture(),
- frames: [{ sequence: 0, at_ms: 0, data: "observed output" }],
- event_journal: [],
- };
+ const capture = captureWithObservedOutput();
let failure: ProcessCaptureError | undefined;
try {
@@ -228,7 +232,15 @@ describe("incomplete partial process observations MCP projection", () => {
],
},
filesystem_snapshots: {
- before: { state: "available", value: { files: [], truncated: false } },
+ before: {
+ state: "available",
+ value: {
+ files: [],
+ truncated: false,
+ completeRoots: [],
+ coverage: emptyFilesystemCoverage,
+ },
+ },
after: {
state: "unavailable",
reason: "fixture final snapshot unavailable",
diff --git a/tests/boundary/process/ProcessEvidence.test.ts b/tests/boundary/process/ProcessEvidence.test.ts
index c2bf779ac..c7bd0ccaf 100644
--- a/tests/boundary/process/ProcessEvidence.test.ts
+++ b/tests/boundary/process/ProcessEvidence.test.ts
@@ -6,7 +6,10 @@ import {
observeLaunchedExecutable,
observeSelectedExecutable,
} from "../../../src/process/capture/ProcessCaptureLifecycle.js";
-import { emptyUnverifiedProcessCapture } from "../../../src/domain/process/processCapture.fixture.js";
+import {
+ accountFullyObservedProcessCapture,
+ emptyUnverifiedProcessCapture,
+} from "../../../src/domain/process/processCapture.fixture.js";
import { compareProcessCaptures } from "../../../src/domain/process/processComparison.js";
import { parseProcessCapture } from "../../../src/domain/process/processCaptureParsing.js";
import {
@@ -81,18 +84,20 @@ const captureEvidenceForEnvironmentSecret = async (value: string) => {
...manifest,
normalization_sha256: digestProcessCommitment(scenario.normalization),
};
- const capture = parseProcessCapture({
- ...base,
- normalization: scenario.normalization,
- frames: [{ sequence: 0, at_ms: 0, data: "observed-output" }],
- residual_unknowns: [
- {
- scope: "environment",
- reason: "Inherited host environment variables are not recorded.",
- },
- ],
- manifest: scenarioManifest,
- });
+ const capture = parseProcessCapture(
+ accountFullyObservedProcessCapture({
+ ...base,
+ normalization: scenario.normalization,
+ frames: [{ sequence: 0, at_ms: 0, data: "observed-output" }],
+ residual_unknowns: [
+ {
+ scope: "environment",
+ reason: "Inherited host environment variables are not recorded.",
+ },
+ ],
+ manifest: scenarioManifest,
+ }),
+ );
return createProcessCaptureEvidence(scenario, capture);
};
@@ -135,10 +140,12 @@ it("preserves selected local environment and input values", async () => {
rightCapture.manifest.comparison_contract_sha256,
);
- const changedOutput = parseProcessCapture({
- ...leftCapture,
- frames: [{ sequence: 0, at_ms: 0, data: "different-output" }],
- });
+ const changedOutput = parseProcessCapture(
+ accountFullyObservedProcessCapture({
+ ...leftCapture,
+ frames: [{ sequence: 0, at_ms: 0, data: "different-output" }],
+ }),
+ );
expect(compareProcessCaptures(leftCapture, changedOutput)).toMatchObject({
status: "changed",
terminal: "changed",
diff --git a/tests/boundary/process/processCaptureLifecycle.test.ts b/tests/boundary/process/processCaptureLifecycle.test.ts
index 72a355276..b3bfaea2e 100644
--- a/tests/boundary/process/processCaptureLifecycle.test.ts
+++ b/tests/boundary/process/processCaptureLifecycle.test.ts
@@ -18,6 +18,7 @@ import {
observeSelectedExecutable,
} from "../../../src/process/capture/ProcessCaptureLifecycle.js";
import { parseProcessScenario } from "../../../src/domain/process/processScenario.js";
+import { emptyProcessCapture } from "../../../src/domain/process/processCapture.fixture.js";
import { type ProcessCapture } from "../../../src/domain/process/processCaptureParsing.js";
const processFixture = fileURLToPath(
@@ -33,6 +34,8 @@ type PartialCapture = Extract<
NonNullable<ProcessCaptureError["partialObservation"]>,
{ readonly capture: unknown }
>["capture"];
+const emptyFilesystemCoverage =
+ emptyProcessCapture().truncation_details.filesystem_before;
const expectUnverifiedHostCleanup = (error: ProcessCaptureError): void => {
const report = error.cleanupReport;
expect(error.reason, error.message).toBe("cleanup_incomplete");
@@ -225,7 +228,12 @@ itWithCaptureCapability(
const captureSnapshot: typeof snapshotRoots = async () => {
snapshotCalls += 1;
if (snapshotCalls === 1)
- return { files: [], truncated: false, completeRoots: [] };
+ return {
+ files: [],
+ truncated: false,
+ completeRoots: [],
+ coverage: emptyFilesystemCoverage,
+ };
throw new Error("fixture final snapshot failure");
};
const cleanupHost: ProcessCaptureCleanupHost = {
diff --git a/tests/boundary/process/processFilesystemCoverageAdapters.test.ts b/tests/boundary/process/processFilesystemCoverageAdapters.test.ts
index 2b2b01f95..479380579 100644
--- a/tests/boundary/process/processFilesystemCoverageAdapters.test.ts
+++ b/tests/boundary/process/processFilesystemCoverageAdapters.test.ts
@@ -125,9 +125,7 @@ it.skipIf(CAPTURE_SKIP_REASON || process.platform === "win32")(
scope: "filesystem",
reason: expect.any(String),
});
- expect(["unknown", "truncated"]).toContain(
- compareProcessCaptures(capture, capture).filesystem,
- );
+ expect(compareProcessCaptures(capture, capture).filesystem).toBe("unknown");
},
20_000,
);
diff --git a/tests/boundary/process/processPreparation.test.ts b/tests/boundary/process/processPreparation.test.ts
index dcfae9f12..6cbb3630f 100644
--- a/tests/boundary/process/processPreparation.test.ts
+++ b/tests/boundary/process/processPreparation.test.ts
@@ -3,6 +3,10 @@ import { expect, it, vi } from "vitest";
import { snapshotRoots } from "../../../src/process/capture/FilesystemSnapshot.js";
import { prepareProcessCapture } from "../../../src/process/capture/ProcessCaptureLifecycle.js";
import { parseProcessScenario } from "../../../src/domain/process/processScenario.js";
+import { emptyProcessCapture } from "../../../src/domain/process/processCapture.fixture.js";
+
+const emptyFilesystemCoverage =
+ emptyProcessCapture().truncation_details.filesystem_before;
it("prepares ownership inspection before snapshotting or allocating a target run", async () => {
const failure = new Error("native process identity inspection unavailable");
@@ -53,7 +57,12 @@ it("cleans the temporary root when cancellation arrives during identity capture"
working_directory: "/tmp",
}),
controller.signal,
- async () => ({ files: [], truncated: false, completeRoots: [] }),
+ async () => ({
+ files: [],
+ truncated: false,
+ completeRoots: [],
+ coverage: emptyFilesystemCoverage,
+ }),
host,
),
).rejects.toThrow(/cancelled/u);
diff --git a/tests/boundary/process/processTruncationAdapters.test.ts b/tests/boundary/process/processTruncationAdapters.test.ts
index 701ae6d4d..bc317d317 100644
--- a/tests/boundary/process/processTruncationAdapters.test.ts
+++ b/tests/boundary/process/processTruncationAdapters.test.ts
@@ -116,12 +116,9 @@ itWithCaptureCapability.each(["cli", "mcp"] as const)(
expect(compareProcessTraces(result, result, specification).verdict).toBe(
"equivalent",
);
- const legacy = parseProcessCapture({
- ...result,
- truncation_details: undefined,
- });
- expect(compareProcessTraces(legacy, legacy, specification).verdict).toBe(
- "unknown",
+ const { truncation_details: _details, ...withoutCoverage } = result;
+ expect(() => parseProcessCapture(withoutCoverage)).toThrow(
+ "truncation_details",
);
expect(compareProcessCaptures(result, result)).toMatchObject({
terminal: "unknown",