fix(process): localize capture truncation diagnostics (#1284)
Report per-source capture coverage and existing file-hash omissions while preserving comparable observations in unaffected dimensions. Keep legacy truncated captures conservative and retain known partial trace events. Closes #1250 Partially addresses #1251; independent hashing remains out of scope.
This commit is contained in:
@@ -3,6 +3,10 @@ import { jsonValueSchema } from "../jsonValue.js";
|
||||
|
||||
import { normalizationSchema } from "./processScenario.js";
|
||||
import { collectProcessCaptureIssues } from "./processCaptureValidation.js";
|
||||
import {
|
||||
processCaptureTruncationDetailsSchema,
|
||||
type ProcessCaptureTruncationDetails,
|
||||
} from "./processCaptureCoverage.js";
|
||||
|
||||
export * from "./processScenario.js";
|
||||
|
||||
@@ -206,6 +210,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;
|
||||
readonly limitations: readonly string[];
|
||||
readonly residual_unknowns: readonly {
|
||||
readonly scope:
|
||||
@@ -477,6 +483,7 @@ const processCaptureShapeSchema = z.strictObject({
|
||||
files_after: z.array(fileStateSchema),
|
||||
filesystem_effects: z.array(fileEffectSchema),
|
||||
truncated: z.boolean(),
|
||||
truncation_details: processCaptureTruncationDetailsSchema.optional(),
|
||||
limitations: z.array(z.string()),
|
||||
residual_unknowns: z.array(
|
||||
z.object({
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
import { z } from "zod";
|
||||
import type { UnverifiedProcessCapture } from "./processCapture.js";
|
||||
import type { ProcessObservationSource } from "./processObservation.js";
|
||||
|
||||
const byteRetentionSchema = z.strictObject({
|
||||
budget_bytes: z.number().int().nonnegative(),
|
||||
observed_bytes: z.number().int().nonnegative(),
|
||||
retained_bytes: z.number().int().nonnegative(),
|
||||
observed_frames: z.number().int().nonnegative(),
|
||||
retained_frames: z.number().int().nonnegative(),
|
||||
});
|
||||
|
||||
/** Filesystem enumeration and whole-file digest coverage for one checkpoint. */
|
||||
export const filesystemCoverageSchema = z.strictObject({
|
||||
files_limit: z.number().int().nonnegative(),
|
||||
depth_limit: z.number().int().nonnegative(),
|
||||
enumeration_truncated: z.boolean(),
|
||||
enumeration_reasons: z.array(
|
||||
z.enum(["files_limit", "depth_limit", "identity_changed"]),
|
||||
),
|
||||
hash_budget_bytes: z.number().int().nonnegative(),
|
||||
hashed_bytes: z.number().int().nonnegative(),
|
||||
hash_omissions: z.array(
|
||||
z.strictObject({
|
||||
path: z.string(),
|
||||
size_bytes: z.number().int().nonnegative(),
|
||||
remaining_budget_bytes: z.number().int().nonnegative(),
|
||||
reason: z.enum(["file_bytes_budget", "file_changed_or_short_read"]),
|
||||
}),
|
||||
),
|
||||
});
|
||||
export type FilesystemCoverage = z.infer<typeof filesystemCoverageSchema>;
|
||||
|
||||
/** Actual budget accounting; rendered bytes count state and visible lines, not JSON. */
|
||||
export const processCaptureTruncationDetailsSchema = z.strictObject({
|
||||
raw_terminal: byteRetentionSchema.describe(
|
||||
"UTF-8 bytes of original PTY chunks; whole chunks are retained or omitted.",
|
||||
),
|
||||
rendered_terminal: byteRetentionSchema.describe(
|
||||
"Cumulative UTF-8 bytes of serialized state plus visible lines, evaluated from retained PTY input; whole frames are retained or omitted.",
|
||||
),
|
||||
filesystem_before: filesystemCoverageSchema,
|
||||
filesystem_after: filesystemCoverageSchema,
|
||||
process: z.strictObject({
|
||||
sample_limit: z.number().int().nonnegative(),
|
||||
sampling_partial: z.boolean(),
|
||||
retained_samples: z.number().int().nonnegative(),
|
||||
sample_limit_reached: z.boolean(),
|
||||
sampling_failures: z.number().int().nonnegative(),
|
||||
first_sampling_failure: z.string().nullable(),
|
||||
coverage: z.literal("sampled"),
|
||||
}),
|
||||
});
|
||||
export type ProcessCaptureTruncationDetails = z.infer<
|
||||
typeof processCaptureTruncationDetailsSchema
|
||||
>;
|
||||
export type TerminalRetention = ProcessCaptureTruncationDetails["raw_terminal"];
|
||||
export type ProcessSamplingCoverage =
|
||||
ProcessCaptureTruncationDetails["process"];
|
||||
|
||||
const omitted = (retention: TerminalRetention): boolean =>
|
||||
retention.observed_frames > retention.retained_frames;
|
||||
const filesystemTruncated = (coverage: FilesystemCoverage): boolean =>
|
||||
coverage.enumeration_truncated || coverage.hash_omissions.length > 0;
|
||||
|
||||
/** Derive the legacy aggregate flag from independent producer observations. */
|
||||
export const hasCaptureTruncation = (
|
||||
details: ProcessCaptureTruncationDetails,
|
||||
): boolean =>
|
||||
omitted(details.raw_terminal) ||
|
||||
omitted(details.rendered_terminal) ||
|
||||
filesystemTruncated(details.filesystem_before) ||
|
||||
filesystemTruncated(details.filesystem_after) ||
|
||||
details.process.sampling_partial;
|
||||
|
||||
/** Older truncated captures lack enough information to localize missing observations. */
|
||||
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);
|
||||
case "terminal_rendered":
|
||||
return (
|
||||
omitted(details.raw_terminal) || omitted(details.rendered_terminal)
|
||||
);
|
||||
case "filesystem":
|
||||
return (
|
||||
filesystemTruncated(details.filesystem_before) ||
|
||||
filesystemTruncated(details.filesystem_after)
|
||||
);
|
||||
case "process":
|
||||
return details.process.sampling_partial;
|
||||
case "interaction":
|
||||
case "lifecycle":
|
||||
return false;
|
||||
}
|
||||
};
|
||||
@@ -1,5 +1,6 @@
|
||||
import type { UnverifiedProcessCapture } from "./processCapture.js";
|
||||
import { digestProcessCommitment } from "./processScenario.js";
|
||||
import { hasCaptureTruncation } from "./processCaptureCoverage.js";
|
||||
|
||||
/** One pure semantic validation failure in a shaped process capture. */
|
||||
export interface ProcessCaptureValidationIssue {
|
||||
@@ -121,6 +122,81 @@ const validateLifecycle = (
|
||||
null, "exit", "deadline termination cannot declare a normal exit code");
|
||||
};
|
||||
|
||||
const validateCoverage = (
|
||||
capture: UnverifiedProcessCapture,
|
||||
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 ===
|
||||
(details.process.sample_limit_reached ||
|
||||
details.process.sampling_failures > 0) &&
|
||||
(details.process.sampling_failures === 0) ===
|
||||
(details.process.first_sampling_failure ===
|
||||
null), "truncation_details.process", "sampling coverage must agree with retained samples and observed failures");
|
||||
require(capture.truncated ===
|
||||
hasCaptureTruncation(
|
||||
details,
|
||||
), "truncation_details", "aggregate truncation must match producer coverage");
|
||||
for (const [name, retention, count] of [
|
||||
["raw_terminal", details.raw_terminal, capture.frames.length],
|
||||
[
|
||||
"rendered_terminal",
|
||||
details.rendered_terminal,
|
||||
capture.rendered_frames.length,
|
||||
],
|
||||
] as const) {
|
||||
require(retention.retained_frames === count &&
|
||||
retention.observed_frames >= count &&
|
||||
retention.observed_bytes >= retention.retained_bytes &&
|
||||
retention.retained_bytes <=
|
||||
retention.budget_bytes, `truncation_details.${name}`, "retained observations and budget accounting do not agree");
|
||||
}
|
||||
for (const [name, coverage, files, checkpoint] of [
|
||||
[
|
||||
"filesystem_before",
|
||||
details.filesystem_before,
|
||||
capture.files_before,
|
||||
capture.filesystem_checkpoints[0],
|
||||
],
|
||||
[
|
||||
"filesystem_after",
|
||||
details.filesystem_after,
|
||||
capture.files_after,
|
||||
capture.filesystem_checkpoints[1],
|
||||
],
|
||||
] as const) {
|
||||
const unhashedFiles = new Map(
|
||||
files
|
||||
.filter((file) => file.type === "file" && file.sha256 === null)
|
||||
.map((file) => [file.path, file]),
|
||||
);
|
||||
require(coverage.hash_omissions.length === unhashedFiles.size &&
|
||||
new Set(coverage.hash_omissions.map(({ path }) => path)).size ===
|
||||
unhashedFiles.size &&
|
||||
coverage.hash_omissions.every(
|
||||
(omission) =>
|
||||
unhashedFiles.get(omission.path)?.size === omission.size_bytes &&
|
||||
omission.remaining_budget_bytes <= coverage.hash_budget_bytes,
|
||||
), `truncation_details.${name}.hash_omissions`, "every retained regular file without a digest must have one matching omission reason");
|
||||
require(coverage.hashed_bytes ===
|
||||
files
|
||||
.filter((file) => file.type === "file" && file.sha256 !== null)
|
||||
.reduce((sum, file) => sum + file.size, 0) &&
|
||||
coverage.hashed_bytes <= coverage.hash_budget_bytes &&
|
||||
files.length <=
|
||||
coverage.files_limit, `truncation_details.${name}`, "filesystem budget accounting does not match retained observations");
|
||||
require(coverage.enumeration_truncated ===
|
||||
coverage.enumeration_reasons.length > 0 &&
|
||||
checkpoint?.truncated ===
|
||||
(coverage.enumeration_truncated ||
|
||||
coverage.hash_omissions.length >
|
||||
0), `truncation_details.${name}`, "filesystem checkpoint truncation must match enumeration and digest coverage");
|
||||
}
|
||||
};
|
||||
|
||||
/** Recompute commitments and cross-field invariants without side effects. */
|
||||
export const collectProcessCaptureIssues = (
|
||||
capture: UnverifiedProcessCapture,
|
||||
@@ -133,5 +209,6 @@ export const collectProcessCaptureIssues = (
|
||||
validateOrdering(capture, require);
|
||||
validateEventJournal(capture, require);
|
||||
validateLifecycle(capture, require);
|
||||
validateCoverage(capture, require);
|
||||
return issues;
|
||||
};
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
import canonicalize from "canonicalize";
|
||||
import { z } from "zod";
|
||||
import { processSourceTruncated } from "./processCaptureCoverage.js";
|
||||
import type { ProcessObservationSource } from "./processObservation.js";
|
||||
|
||||
import type { ProcessCapture } from "./processCapture.js";
|
||||
import { comparableTerminalFrame } from "./processObservation.js";
|
||||
@@ -363,8 +365,13 @@ const compareDimensions = (
|
||||
scope: ProcessCapture["residual_unknowns"][number]["scope"],
|
||||
leftValues: readonly unknown[],
|
||||
rightValues: readonly unknown[],
|
||||
source: ProcessObservationSource,
|
||||
): ComparisonStatus =>
|
||||
!sameNormalization || hasUnknown(left, scope) || hasUnknown(right, scope)
|
||||
!sameNormalization ||
|
||||
hasUnknown(left, scope) ||
|
||||
hasUnknown(right, scope) ||
|
||||
processSourceTruncated(left, source) ||
|
||||
processSourceTruncated(right, source)
|
||||
? "unknown"
|
||||
: classifyCollection(leftValues, rightValues);
|
||||
return {
|
||||
@@ -372,11 +379,13 @@ const compareDimensions = (
|
||||
"terminal",
|
||||
terminalObservations(left),
|
||||
terminalObservations(right),
|
||||
"terminal_rendered",
|
||||
),
|
||||
interaction: classify(
|
||||
"interaction",
|
||||
left.interaction_events,
|
||||
right.interaction_events,
|
||||
"interaction",
|
||||
),
|
||||
exit:
|
||||
hasUnknown(left, "exit") || hasUnknown(right, "exit")
|
||||
@@ -391,8 +400,14 @@ const compareDimensions = (
|
||||
"filesystem",
|
||||
filesystemObservations(left),
|
||||
filesystemObservations(right),
|
||||
"filesystem",
|
||||
),
|
||||
process: classify(
|
||||
"process",
|
||||
left.process_samples,
|
||||
right.process_samples,
|
||||
"process",
|
||||
),
|
||||
process: classify("process", left.process_samples, right.process_samples),
|
||||
};
|
||||
};
|
||||
|
||||
@@ -412,7 +427,10 @@ export const compareProcessCaptures = (
|
||||
} = {},
|
||||
): ProcessCaptureComparison => {
|
||||
assertComparable(left, right, options);
|
||||
if (left.truncated || right.truncated) {
|
||||
if (
|
||||
(left.truncated && left.truncation_details === undefined) ||
|
||||
(right.truncated && right.truncation_details === undefined)
|
||||
) {
|
||||
const truncated = truncatedComparison();
|
||||
return options.traceSpecification === undefined
|
||||
? truncated
|
||||
@@ -438,11 +456,13 @@ export const compareProcessCaptures = (
|
||||
right,
|
||||
]);
|
||||
const divergenceCandidates = PROCESS_COMPARISON_DIMENSIONS.map((dimension) =>
|
||||
firstCollectionDivergence(
|
||||
dimension,
|
||||
processDimensionObservations(left, dimension),
|
||||
processDimensionObservations(right, dimension),
|
||||
),
|
||||
dimensions[dimension] === "unknown"
|
||||
? null
|
||||
: firstCollectionDivergence(
|
||||
dimension,
|
||||
processDimensionObservations(left, dimension),
|
||||
processDimensionObservations(right, dimension),
|
||||
),
|
||||
);
|
||||
const observedFirstDivergence = chooseFirstDivergence(
|
||||
divergenceCandidates.map((candidate) =>
|
||||
@@ -454,22 +474,30 @@ export const compareProcessCaptures = (
|
||||
),
|
||||
);
|
||||
const firstDivergence =
|
||||
trace?.verdict === "equivalent" &&
|
||||
deriveProcessComparisonStatus(
|
||||
PROCESS_COMPARISON_DIMENSIONS.map((dimension) => dimensions[dimension]),
|
||||
) === "unchanged"
|
||||
? ({ status: "none" } as const)
|
||||
: observedFirstDivergence.status === "found"
|
||||
? observedFirstDivergence
|
||||
: !sameNormalization ||
|
||||
left.residual_unknowns.length > 0 ||
|
||||
right.residual_unknowns.length > 0
|
||||
? ({
|
||||
status: "unknown",
|
||||
reason:
|
||||
"Residual unknowns prevent proving that no divergence occurred.",
|
||||
} as const)
|
||||
: observedFirstDivergence;
|
||||
left.truncated || right.truncated
|
||||
? ({
|
||||
status: "unknown",
|
||||
reason:
|
||||
"Incomplete observations prevent locating the first divergence; unaffected dimensions retain their comparisons.",
|
||||
} as const)
|
||||
: trace?.verdict === "equivalent" &&
|
||||
deriveProcessComparisonStatus(
|
||||
PROCESS_COMPARISON_DIMENSIONS.map(
|
||||
(dimension) => dimensions[dimension],
|
||||
),
|
||||
) === "unchanged"
|
||||
? ({ status: "none" } as const)
|
||||
: observedFirstDivergence.status === "found"
|
||||
? observedFirstDivergence
|
||||
: !sameNormalization ||
|
||||
left.residual_unknowns.length > 0 ||
|
||||
right.residual_unknowns.length > 0
|
||||
? ({
|
||||
status: "unknown",
|
||||
reason:
|
||||
"Residual unknowns prevent proving that no divergence occurred.",
|
||||
} as const)
|
||||
: observedFirstDivergence;
|
||||
const observedStatus = deriveProcessComparisonStatus(
|
||||
PROCESS_COMPARISON_DIMENSIONS.map((dimension) => dimensions[dimension]),
|
||||
);
|
||||
|
||||
@@ -2,6 +2,7 @@ import { z } from "zod";
|
||||
|
||||
import type { JsonValue } from "../jsonValue.js";
|
||||
import type { ProcessCapture } from "./processCapture.js";
|
||||
import { processSourceTruncated } from "./processCaptureCoverage.js";
|
||||
import {
|
||||
processObservationLocationSchema,
|
||||
projectProcessObservation,
|
||||
@@ -414,7 +415,7 @@ export const evaluateProcessTraceSide = (
|
||||
const sources = new Set(specification.events.map(({ source }) => source));
|
||||
const relevantScopes = scopesFor(sources);
|
||||
const incomplete =
|
||||
capture.truncated ||
|
||||
[...sources].some((source) => processSourceTruncated(capture, source)) ||
|
||||
capture.residual_unknowns.some(({ scope }) => relevantScopes.has(scope));
|
||||
if (capture.event_journal.length === 0)
|
||||
return {
|
||||
|
||||
@@ -7,12 +7,14 @@ import type {
|
||||
ProcessScenario,
|
||||
} from "../../domain/process/processCapture.js";
|
||||
import type { Stats } from "node:fs";
|
||||
import type { FilesystemCoverage } from "../../domain/process/processCaptureCoverage.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;
|
||||
}
|
||||
|
||||
const hasSameIdentity = (
|
||||
@@ -97,6 +99,10 @@ export const snapshotRoots = async (
|
||||
const completeRoots: string[] = [];
|
||||
let remainingBytes = scenario.limits.file_bytes;
|
||||
let truncated = false;
|
||||
const enumerationReasons = new Set<
|
||||
FilesystemCoverage["enumeration_reasons"][number]
|
||||
>();
|
||||
const hashOmissions: FilesystemCoverage["hash_omissions"] = [];
|
||||
const visit = async (
|
||||
root: string,
|
||||
rootAlias: string,
|
||||
@@ -109,6 +115,10 @@ export const snapshotRoots = async (
|
||||
depth > scenario.limits.filesystem_depth
|
||||
) {
|
||||
truncated = true;
|
||||
if (entries.length >= scenario.limits.files)
|
||||
enumerationReasons.add("files_limit");
|
||||
if (depth > scenario.limits.filesystem_depth)
|
||||
enumerationReasons.add("depth_limit");
|
||||
return false;
|
||||
}
|
||||
const stats = await lstatIfPresent(path);
|
||||
@@ -119,6 +129,7 @@ export const snapshotRoots = async (
|
||||
const afterRead = await lstat(path);
|
||||
if (!hasSameIdentity(stats, afterRead, "symlink")) {
|
||||
truncated = true;
|
||||
enumerationReasons.add("identity_changed");
|
||||
return false;
|
||||
}
|
||||
entries.push({
|
||||
@@ -137,7 +148,18 @@ export const snapshotRoots = async (
|
||||
? await hashFile(path, stats, remainingBytes, signal)
|
||||
: null;
|
||||
remainingBytes -= sha256 === null ? 0 : stats.size;
|
||||
if (sha256 === null) truncated = true;
|
||||
if (sha256 === null) {
|
||||
truncated = true;
|
||||
hashOmissions.push({
|
||||
path: `${rootAlias}:${relativePath}`,
|
||||
size_bytes: stats.size,
|
||||
remaining_budget_bytes: remainingBytes,
|
||||
reason:
|
||||
remainingBytes < stats.size
|
||||
? "file_bytes_budget"
|
||||
: "file_changed_or_short_read",
|
||||
});
|
||||
}
|
||||
entries.push({
|
||||
path: `${rootAlias}:${relativePath}`,
|
||||
type: "file",
|
||||
@@ -162,6 +184,7 @@ export const snapshotRoots = async (
|
||||
const afterRead = await lstat(path);
|
||||
if (!hasSameIdentity(stats, afterRead, "directory")) {
|
||||
truncated = true;
|
||||
enumerationReasons.add("identity_changed");
|
||||
return false;
|
||||
}
|
||||
let complete = true;
|
||||
@@ -179,5 +202,19 @@ export const snapshotRoots = async (
|
||||
}
|
||||
if (await visit(root, alias, root, 0)) completeRoots.push(alias);
|
||||
}
|
||||
return { files: entries, truncated, completeRoots };
|
||||
return {
|
||||
files: entries,
|
||||
truncated,
|
||||
completeRoots,
|
||||
coverage: {
|
||||
files_limit: scenario.limits.files,
|
||||
depth_limit: scenario.limits.filesystem_depth,
|
||||
enumeration_truncated:
|
||||
completeRoots.length !== scenario.filesystem_observation_paths.length,
|
||||
enumeration_reasons: [...enumerationReasons],
|
||||
hash_budget_bytes: scenario.limits.file_bytes,
|
||||
hashed_bytes: scenario.limits.file_bytes - remainingBytes,
|
||||
hash_omissions: hashOmissions,
|
||||
},
|
||||
};
|
||||
};
|
||||
|
||||
@@ -59,6 +59,11 @@ import {
|
||||
} from "./ProcessNormalization.js";
|
||||
import { PROCESS_PROVIDER } from "../../domain/process/processEvidenceProvider.js";
|
||||
import { TerminalRenderer } from "./TerminalRenderer.js";
|
||||
import {
|
||||
hasCaptureTruncation,
|
||||
type TerminalRetention,
|
||||
type ProcessCaptureTruncationDetails,
|
||||
} from "../../domain/process/processCaptureCoverage.js";
|
||||
import { scheduleProcessInterval, type ProcessTimer } from "./ProcessTimer.js";
|
||||
|
||||
interface TerminalExitOptions {
|
||||
@@ -84,6 +89,7 @@ interface CaptureResultOptions {
|
||||
readonly before: SnapshotResult;
|
||||
readonly after: SnapshotResult;
|
||||
readonly truncated: boolean;
|
||||
readonly truncationDetails?: ProcessCaptureTruncationDetails;
|
||||
readonly scenario: ProcessScenario;
|
||||
readonly rootPid: number;
|
||||
readonly samplingPartial: boolean;
|
||||
@@ -279,7 +285,13 @@ export const buildCaptureResult = (
|
||||
files_before: options.before.files,
|
||||
files_after: options.after.files,
|
||||
filesystem_effects: filesystemEffects,
|
||||
truncated: options.truncated,
|
||||
truncated:
|
||||
options.truncationDetails === undefined
|
||||
? options.truncated
|
||||
: hasCaptureTruncation(options.truncationDetails),
|
||||
...(options.truncationDetails === undefined
|
||||
? {}
|
||||
: { 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.",
|
||||
@@ -290,6 +302,11 @@ 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,
|
||||
)),
|
||||
...(hasSensitiveScriptedInput ? [sensitiveInputUnknown] : []),
|
||||
],
|
||||
residual_unknowns: [
|
||||
@@ -330,10 +347,61 @@ export const buildCaptureResult = (
|
||||
...(hasSensitiveScriptedInput
|
||||
? [{ scope: "interaction" as const, reason: sensitiveInputUnknown }]
|
||||
: []),
|
||||
...(options.truncationDetails === undefined
|
||||
? []
|
||||
: captureCoverageUnknowns(options.truncationDetails).filter(
|
||||
({ scope }) => scope !== "terminal",
|
||||
)),
|
||||
],
|
||||
};
|
||||
};
|
||||
|
||||
const captureCoverageUnknowns = (
|
||||
details: ProcessCaptureTruncationDetails,
|
||||
): UnverifiedProcessCapture["residual_unknowns"] => {
|
||||
const unknowns: Array<UnverifiedProcessCapture["residual_unknowns"][number]> =
|
||||
[];
|
||||
if (
|
||||
details.raw_terminal.observed_frames > details.raw_terminal.retained_frames
|
||||
)
|
||||
unknowns.push({
|
||||
scope: "terminal",
|
||||
reason:
|
||||
"Raw PTY chunks exceeded output_bytes and were omitted; rendered states also lack those inputs. See truncation_details.raw_terminal.",
|
||||
});
|
||||
if (
|
||||
details.rendered_terminal.observed_frames >
|
||||
details.rendered_terminal.retained_frames
|
||||
)
|
||||
unknowns.push({
|
||||
scope: "terminal",
|
||||
reason:
|
||||
"Cumulative rendered state and visible-line bytes exceeded output_bytes; whole rendered frames were omitted. Raw PTY coverage is reported separately. See truncation_details.rendered_terminal.",
|
||||
});
|
||||
for (const [name, coverage] of [
|
||||
["before", details.filesystem_before],
|
||||
["after_settlement", details.filesystem_after],
|
||||
] as const) {
|
||||
if (coverage.enumeration_truncated)
|
||||
unknowns.push({
|
||||
scope: "filesystem",
|
||||
reason: `Filesystem ${name} path enumeration was incomplete: ${coverage.enumeration_reasons.join(", ")}. See truncation_details.`,
|
||||
});
|
||||
if (coverage.hash_omissions.length > 0)
|
||||
unknowns.push({
|
||||
scope: "filesystem",
|
||||
reason: `Filesystem ${name} omitted ${String(coverage.hash_omissions.length)} whole-file digests; per-path reasons and remaining file_bytes budget are in truncation_details.`,
|
||||
});
|
||||
}
|
||||
if (details.process.sampling_partial)
|
||||
unknowns.push({
|
||||
scope: "process",
|
||||
reason:
|
||||
"Process sampling stopped with incomplete observations; sample_limit is reported in truncation_details.process.",
|
||||
});
|
||||
return unknowns;
|
||||
};
|
||||
|
||||
interface ExecutableFileIdentity {
|
||||
readonly dev: bigint;
|
||||
readonly ino: bigint;
|
||||
@@ -840,14 +908,16 @@ export const captureTerminalFrames = (options: {
|
||||
readonly onOutput: () => void;
|
||||
readonly renderer: TerminalRenderer;
|
||||
readonly recordEvent: RecordProcessCaptureEvent;
|
||||
}): (() => boolean) => {
|
||||
}): (() => TerminalRetention) => {
|
||||
let outputBytes = 0;
|
||||
let truncated = false;
|
||||
let observedBytes = 0;
|
||||
let observedFrames = 0;
|
||||
options.terminal.onData((data) => {
|
||||
options.onOutput();
|
||||
const bytes = Buffer.byteLength(data);
|
||||
observedBytes += bytes;
|
||||
observedFrames += 1;
|
||||
if (outputBytes + bytes > options.scenario.limits.output_bytes) {
|
||||
truncated = true;
|
||||
return;
|
||||
}
|
||||
outputBytes += bytes;
|
||||
@@ -871,7 +941,13 @@ export const captureTerminalFrames = (options: {
|
||||
options.renderer.write(data, atMs);
|
||||
options.recordEvent("frames", sequence);
|
||||
});
|
||||
return () => truncated;
|
||||
return () => ({
|
||||
budget_bytes: options.scenario.limits.output_bytes,
|
||||
observed_bytes: observedBytes,
|
||||
retained_bytes: outputBytes,
|
||||
observed_frames: observedFrames,
|
||||
retained_frames: options.frames.length,
|
||||
});
|
||||
};
|
||||
|
||||
export const resolveProcessResult = (
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import type { IPty } from "@lydell/node-pty";
|
||||
import type { TerminalRetention } from "../../domain/process/processCaptureCoverage.js";
|
||||
import type {
|
||||
InteractionEvent,
|
||||
ProcessCapture,
|
||||
@@ -65,8 +66,8 @@ interface StartedCaptureRuntime {
|
||||
readonly startedAt: Date;
|
||||
readonly executableIdentity: ReturnType<typeof observeLaunchedExecutable>;
|
||||
readonly lastOutput: () => number;
|
||||
readonly framesTruncated: () => boolean;
|
||||
readonly stopSampler: () => Promise<{ readonly partial: boolean }>;
|
||||
readonly rawTerminalRetention: () => TerminalRetention;
|
||||
readonly stopSampler: ReturnType<typeof startProcessSampler>;
|
||||
}
|
||||
|
||||
const cleanupFailedStartup = async (options: {
|
||||
@@ -200,7 +201,7 @@ const startCaptureRuntime = async (
|
||||
scenario.executable,
|
||||
selectedExecutable,
|
||||
);
|
||||
const framesTruncated = captureTerminalFrames({
|
||||
const rawTerminalRetention = captureTerminalFrames({
|
||||
...options,
|
||||
terminal,
|
||||
started,
|
||||
@@ -228,7 +229,7 @@ const startCaptureRuntime = async (
|
||||
startedAt,
|
||||
executableIdentity,
|
||||
lastOutput: () => lastOutput,
|
||||
framesTruncated,
|
||||
rawTerminalRetention,
|
||||
stopSampler,
|
||||
};
|
||||
} catch (cause: unknown) {
|
||||
@@ -365,7 +366,8 @@ const completeCapture = async (options: {
|
||||
state: "available",
|
||||
value: settlement,
|
||||
};
|
||||
const samplingPartial = (await runtime.stopSampler()).partial;
|
||||
const sampling = await runtime.stopSampler();
|
||||
const samplingPartial = sampling.partial;
|
||||
await settleProcessCaptureJournal(options.eventJournal);
|
||||
assertNotCancelled(options.signal);
|
||||
let after: Awaited<ReturnType<typeof snapshotRoots>>;
|
||||
@@ -439,7 +441,8 @@ const completeCapture = async (options: {
|
||||
const truncated =
|
||||
options.initiallyTruncated ||
|
||||
after.truncated ||
|
||||
runtime.framesTruncated() ||
|
||||
runtime.rawTerminalRetention().observed_frames >
|
||||
runtime.rawTerminalRetention().retained_frames ||
|
||||
checkpoints.some(({ truncated: partial }) => partial) ||
|
||||
samplingPartial ||
|
||||
runtime.renderer.truncated();
|
||||
@@ -450,6 +453,17 @@ const completeCapture = async (options: {
|
||||
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,
|
||||
},
|
||||
}),
|
||||
scenario,
|
||||
rootPid: runtime.terminal.pid,
|
||||
samplingPartial,
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { readFile, readdir } from "node:fs/promises";
|
||||
import type { ProcessSamplingCoverage } from "../../domain/process/processCaptureCoverage.js";
|
||||
import type {
|
||||
ProcessSample,
|
||||
RecordProcessCaptureEvent,
|
||||
@@ -455,7 +456,10 @@ export const startProcessSampler = (options: {
|
||||
readonly limit: number;
|
||||
readonly samples: ProcessSample[];
|
||||
readonly recordEvent?: RecordProcessCaptureEvent;
|
||||
}): (() => Promise<{ readonly partial: boolean }>) => {
|
||||
}): (() => Promise<{
|
||||
readonly partial: boolean;
|
||||
readonly coverage: ProcessSamplingCoverage;
|
||||
}>) => {
|
||||
const { rootPid, runId, started, limit, samples } = options;
|
||||
const identities = new Map<number, string>();
|
||||
const lastObservations = new Map<number, string>();
|
||||
@@ -463,6 +467,9 @@ export const startProcessSampler = (options: {
|
||||
let stopped = false;
|
||||
let abortCurrent: (() => void) | undefined;
|
||||
let partial = false;
|
||||
let limitReached = false;
|
||||
let samplingFailures = 0;
|
||||
let firstSamplingFailure: string | null = null;
|
||||
let rootInitialized = false;
|
||||
|
||||
const sample = (): void => {
|
||||
@@ -501,6 +508,7 @@ export const startProcessSampler = (options: {
|
||||
if (lastObservations.get(value.pid) === observation) continue;
|
||||
if (samples.length >= limit) {
|
||||
partial = true;
|
||||
limitReached = true;
|
||||
continue;
|
||||
}
|
||||
lastObservations.set(value.pid, observation);
|
||||
@@ -510,8 +518,16 @@ export const startProcessSampler = (options: {
|
||||
}
|
||||
})
|
||||
.catch((cause: unknown) => {
|
||||
if (!(cause instanceof Error && cause.name === "AbortError"))
|
||||
if (!(cause instanceof Error && cause.name === "AbortError")) {
|
||||
partial = true;
|
||||
samplingFailures += 1;
|
||||
firstSamplingFailure ??=
|
||||
cause instanceof Error
|
||||
? `${cause.name}: ${cause.message}`
|
||||
: typeof cause === "string"
|
||||
? cause
|
||||
: `Unexpected sampling rejection (${typeof cause})`;
|
||||
}
|
||||
})
|
||||
.then(() => {
|
||||
abortCurrent = undefined;
|
||||
@@ -527,6 +543,17 @@ export const startProcessSampler = (options: {
|
||||
clearInterval(timer);
|
||||
abortCurrent?.();
|
||||
await pending;
|
||||
return { partial };
|
||||
return {
|
||||
partial,
|
||||
coverage: {
|
||||
sample_limit: limit,
|
||||
sampling_partial: partial,
|
||||
retained_samples: samples.length,
|
||||
sample_limit_reached: limitReached,
|
||||
sampling_failures: samplingFailures,
|
||||
first_sampling_failure: firstSamplingFailure,
|
||||
coverage: "sampled",
|
||||
},
|
||||
};
|
||||
};
|
||||
};
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { createRequire } from "node:module";
|
||||
import type { TerminalRetention } from "../../domain/process/processCaptureCoverage.js";
|
||||
|
||||
import type {
|
||||
RecordProcessCaptureEvent,
|
||||
@@ -36,6 +37,8 @@ export class TerminalRenderer {
|
||||
readonly #frames: RenderedTerminalFrame[] = [];
|
||||
#pending: Promise<void> = Promise.resolve();
|
||||
#capturedBytes = 0;
|
||||
#observedBytes = 0;
|
||||
#observedFrames = 0;
|
||||
#truncated = false;
|
||||
|
||||
constructor(private readonly options: TerminalRendererOptions) {
|
||||
@@ -80,6 +83,17 @@ export class TerminalRenderer {
|
||||
return this.#truncated;
|
||||
}
|
||||
|
||||
/** Budget accounting after awaiting queued writes with frames(). */
|
||||
retention(): TerminalRetention {
|
||||
return {
|
||||
budget_bytes: this.options.maxBytes,
|
||||
observed_bytes: this.#observedBytes,
|
||||
retained_bytes: this.#capturedBytes,
|
||||
observed_frames: this.#observedFrames,
|
||||
retained_frames: this.#frames.length,
|
||||
};
|
||||
}
|
||||
|
||||
/** Release addon and terminal resources after all writes settle. */
|
||||
async dispose(): Promise<void> {
|
||||
await this.#pending;
|
||||
@@ -107,6 +121,8 @@ export class TerminalRenderer {
|
||||
const bytes =
|
||||
Buffer.byteLength(serializedState) +
|
||||
lines.reduce((total, line) => total + Buffer.byteLength(line), 0);
|
||||
this.#observedBytes += bytes;
|
||||
this.#observedFrames += 1;
|
||||
if (this.#capturedBytes + bytes > this.options.maxBytes) {
|
||||
this.#truncated = true;
|
||||
return;
|
||||
|
||||
Reference in New Issue
Block a user