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 {
|
||||
|
||||
Reference in New Issue
Block a user