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 {
+39 -2
View File
@@ -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,
},
};
};
+81 -5
View File
@@ -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 = (
+20 -6
View File
@@ -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,
+30 -3
View File
@@ -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",
},
};
};
};
+16
View File
@@ -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;