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:
Ysopwnable
2026-10-09 21:56:43 +08:00
committed by GitHub
parent 7e96f25f8b
commit 33bf585185
14 changed files with 739 additions and 50 deletions
+7
View File
@@ -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;
};
+52 -24
View File
@@ -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 -1
View File
@@ -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 {