diff --git a/docs/browser-scenario-contract.md b/docs/browser-scenario-contract.md index 5bc4e89554..a0482f008c 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 24cdac5719..b000994c00 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 b963aeaecd..642dd01f92 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 fb3f4cb87c..6cb010fee5 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", - ); - 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 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", + ); + + 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 020920a3ed..8a7b392830 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 9752cf97af..81fef0c15e 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 7b3824abba..4c5272b9c8 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 85fd98369e..4d238da2dd 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[0], + right: Parameters[1], + options?: Parameters[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: 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: 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 9ea29421af..701e76e2a2 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 044d6b54d5..8cbfbd7995 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 = | { 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; @@ -296,8 +299,8 @@ export interface IncompleteProcessCaptureObservations { readonly ProcessSample[] >; readonly filesystem_snapshots: { - readonly before: PartialProcessObservationField; - readonly after: PartialProcessObservationField; + readonly before: PartialProcessObservationField; + readonly after: PartialProcessObservationField; }; 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 80183aab70..0573c00528 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 5365961efb..a939729128 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 91098581c5..6c177a5356 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 b8bc953d30..fe54796897 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 47264ef466..9db90cfb75 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 5589e40cb8..18cdea5c6c 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 244045e1c4..b63f7e6c7c 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 0dffc404d8..952bb97586 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 b60827cb3d..3efd74581a 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 = { - 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 71b45cfaf3..7e3dc36b8b 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 f5b775bb09..281151afca 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 => { +): Promise => { 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 14da87231a..af439e9dd9 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; filesystem_snapshots: { - before: PartialProcessObservationField; - after: PartialProcessObservationField; + before: PartialProcessObservationField; + after: PartialProcessObservationField; }; 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 7a1ccd0082..7bd54a124c 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 ec47c90eca..97ae578c44 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 c96964f676..65ca8d3d59 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 9ffc882b60..f15210b155 100644 --- a/src/process/capture/ProcessHarness.ts +++ b/src/process/capture/ProcessHarness.ts @@ -333,7 +333,6 @@ const completeCapture = async (options: { readonly exit: Awaited>; 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 8d59a1e3d2..290e94550e 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 454e600a23..a71ac46f63 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 c2bf779ac0..c7bd0ccaf6 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 72a355276c..b3bfaea2e6 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, { 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 2b2b01f956..4793805792 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 dcfae9f126..6cbb3630fa 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 701ae6d4d1..bc317d3177 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",