From 3283a45d09457c79e3adadb50a48620926d4bc5b Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Fri, 9 Oct 2026 23:17:03 +0800 Subject: [PATCH] refactor(captures)!: require canonical producer metadata Require process retention accounting, browser network transaction identity, and all web comparison dimensions. Remove obsolete omission repairs and derive completeness from the owning producer facts. BREAKING CHANGE: Historical captures without current producer accounting or transaction identity, and web diffs missing accessibility or storage dimensions, are rejected. --- docs/browser-scenario-contract.md | 9 +- docs/process-capture.md | 4 +- src/browser/assets/ScenarioScriptCapture.ts | 19 +-- .../assets/ScriptCaptureAdapters.test.ts | 46 ++++-- src/domain/browserScenarioCapture.test.ts | 23 +++ src/domain/browserScenarioCaptureValues.ts | 4 +- src/domain/browserScenarioDiff.test.ts | 1 + .../process/processCapture.comparison.test.ts | 30 +++- src/domain/process/processCapture.fixture.ts | 74 +++++++++ src/domain/process/processCapture.ts | 50 +++--- .../process/processCapture.validation.test.ts | 43 ++--- src/domain/process/processCaptureCoverage.ts | 5 +- src/domain/process/processCaptureExample.ts | 43 +++++ .../process/processCaptureValidation.ts | 1 - src/domain/process/processComparison.ts | 26 --- .../process/processTraceAdapters.test.ts | 42 ++--- .../process/processTraceComparison.fixture.ts | 30 +++- .../process/processTraceComparison.test.ts | 2 +- src/domain/webCaptureDiffSchemas.ts | 11 +- src/domain/webScriptExport.ts | 2 +- src/process/capture/FilesystemSnapshot.ts | 17 +- .../capture/ProcessCaptureLifecycle.ts | 48 ++---- .../capture/ProcessCaptureObservation.test.ts | 78 ++++++++- .../capture/ProcessFilesystemEffects.ts | 6 +- src/process/capture/ProcessHarness.test.ts | 156 +++++++++++++++--- src/process/capture/ProcessHarness.ts | 31 +--- tests/boundary/browser/webCaptureDiff.test.ts | 15 +- tests/boundary/mcp/toolResult.test.ts | 36 ++-- .../boundary/process/ProcessEvidence.test.ts | 41 +++-- .../process/processCaptureLifecycle.test.ts | 10 +- .../processFilesystemCoverageAdapters.test.ts | 4 +- .../process/processPreparation.test.ts | 11 +- .../process/processTruncationAdapters.test.ts | 9 +- 33 files changed, 624 insertions(+), 303 deletions(-) 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",