feat(process): bound a finalization interval before forced capture timeout
Add optional finalization_ms to keep observing a captured root after SIGTERM, record the actual finalizer exit and each signal attempt, and escalate once when needed. Bind the initial root identity to captured ownership and preserve observations through cleanup uncertainty. Fixes #1253. Co-authored-by: Mykola Dementiev <16836724+nikolay-dementiev@users.noreply.github.com> Co-authored-by: N0zoM1z0 <161784452+N0zoM1z0@users.noreply.github.com>
This commit is contained in:
co-authored by
Mykola Dementiev
N0zoM1z0
parent
1e51c732bb
commit
c1efa6467d
@@ -2,7 +2,12 @@ import { z } from "zod";
|
||||
import { jsonValueSchema } from "../jsonValue.js";
|
||||
|
||||
import { normalizationSchema } from "./processScenario.js";
|
||||
import { collectProcessCaptureIssues } from "./processCaptureValidation.js";
|
||||
import {
|
||||
collectProcessCaptureIssues,
|
||||
finalizationAgreementIssue,
|
||||
finalizationConsistencyIssue,
|
||||
finalizationManifestIssue,
|
||||
} from "./processCaptureValidation.js";
|
||||
import {
|
||||
filesystemCoverageSchema,
|
||||
processCaptureTruncationDetailsSchema,
|
||||
@@ -42,6 +47,21 @@ export interface InteractionEvent {
|
||||
readonly outcome: "dispatched" | "target_exited" | "failed";
|
||||
}
|
||||
|
||||
/** Observed finalization attempts after a deadline fired. */
|
||||
export interface ProcessCaptureFinalization {
|
||||
readonly requested_ms: number;
|
||||
readonly elapsed_ms: number | null;
|
||||
/** Code the PTY reported for an exit not caused by a signal; otherwise null. */
|
||||
readonly exit_code: number | null;
|
||||
readonly signals: readonly {
|
||||
readonly signal: "SIGTERM" | "SIGKILL";
|
||||
readonly sent_at_ms: number;
|
||||
readonly delivery: "signaled" | "gone" | "identity-changed" | "unverified";
|
||||
/** Why delivery could not be verified; present only for unverified attempts. */
|
||||
readonly reason?: string | undefined;
|
||||
}[];
|
||||
}
|
||||
|
||||
/** One filesystem state used for before/after comparison. */
|
||||
interface FileStateIdentity {
|
||||
readonly path: string;
|
||||
@@ -209,6 +229,7 @@ export interface UnverifiedProcessCapture {
|
||||
readonly code: number | null;
|
||||
readonly signal: number | null;
|
||||
readonly reason: "exited" | "timeout" | "idle_timeout";
|
||||
readonly finalization?: ProcessCaptureFinalization | undefined;
|
||||
};
|
||||
readonly settlement: VerifiedProcessSettlement;
|
||||
readonly process_samples: readonly ProcessSample[];
|
||||
@@ -290,7 +311,11 @@ export interface IncompleteProcessCaptureObservations {
|
||||
readonly code: number | null;
|
||||
readonly signal: number | null;
|
||||
readonly reason: "exited" | "timeout" | "idle_timeout" | "cancelled";
|
||||
readonly finalization?: ProcessCaptureFinalization | undefined;
|
||||
}>;
|
||||
readonly finalization?:
|
||||
| PartialProcessObservationField<ProcessCaptureFinalization>
|
||||
| undefined;
|
||||
readonly settlement: PartialProcessObservationField<{
|
||||
readonly state: "quiesced" | "alive_at_deadline" | "unverifiable";
|
||||
readonly elapsed_ms: number;
|
||||
@@ -385,6 +410,44 @@ const unverifiedCleanupProcessesSchema = z.array(
|
||||
z.strictObject({ pid: z.number().int().positive(), reason: z.string() }),
|
||||
);
|
||||
|
||||
const processCaptureFinalizationSchema = z
|
||||
.strictObject({
|
||||
requested_ms: z.number().int().safe().positive(),
|
||||
elapsed_ms: z.number().int().nonnegative().nullable(),
|
||||
exit_code: z.number().int().nonnegative().nullable(),
|
||||
signals: z
|
||||
.array(
|
||||
z.strictObject({
|
||||
signal: z.enum(["SIGTERM", "SIGKILL"]),
|
||||
sent_at_ms: z.number().int().nonnegative(),
|
||||
delivery: z.enum([
|
||||
"signaled",
|
||||
"gone",
|
||||
"identity-changed",
|
||||
"unverified",
|
||||
]),
|
||||
reason: z.string().min(1).optional(),
|
||||
}),
|
||||
)
|
||||
.min(1),
|
||||
})
|
||||
.superRefine((finalization, context) => {
|
||||
if (finalization.exit_code !== null && finalization.elapsed_ms === null)
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["exit_code"],
|
||||
message: "finalization exit_code requires an observed exit",
|
||||
});
|
||||
for (const [index, attempt] of finalization.signals.entries())
|
||||
if (attempt.reason !== undefined && attempt.delivery !== "unverified")
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["signals", index, "reason"],
|
||||
message:
|
||||
"finalization reason is only allowed for an unverified delivery",
|
||||
});
|
||||
});
|
||||
|
||||
const processCaptureShapeSchema = z.strictObject({
|
||||
manifest: z.strictObject({
|
||||
rea_version: z.string().min(1),
|
||||
@@ -448,6 +511,7 @@ const processCaptureShapeSchema = z.strictObject({
|
||||
code: z.number().int().nullable(),
|
||||
signal: z.number().int().nullable(),
|
||||
reason: z.enum(["exited", "timeout", "idle_timeout"]),
|
||||
finalization: processCaptureFinalizationSchema.optional(),
|
||||
}),
|
||||
settlement: z.discriminatedUnion("state", [
|
||||
z.object({
|
||||
@@ -543,8 +607,12 @@ const incompleteProcessCaptureObservationsSchema = z.strictObject({
|
||||
code: z.number().int().nullable(),
|
||||
signal: z.number().int().nullable(),
|
||||
reason: z.enum(["exited", "timeout", "idle_timeout", "cancelled"]),
|
||||
finalization: processCaptureFinalizationSchema.optional(),
|
||||
}),
|
||||
),
|
||||
finalization: partialObservationFieldSchema(
|
||||
processCaptureFinalizationSchema,
|
||||
).optional(),
|
||||
settlement: partialObservationFieldSchema(
|
||||
z.strictObject({
|
||||
state: z.enum(["quiesced", "alive_at_deadline", "unverifiable"]),
|
||||
@@ -606,6 +674,84 @@ export const partialProcessCaptureObservationSchema = z
|
||||
"partial observations require incomplete cleanup or an execution failure",
|
||||
});
|
||||
|
||||
const observedExit =
|
||||
"capture" in partial
|
||||
? partial.capture.exit
|
||||
: partial.observations.exit.state === "available"
|
||||
? partial.observations.exit.value
|
||||
: undefined;
|
||||
const observedFinalization =
|
||||
"observations" in partial &&
|
||||
partial.observations.finalization?.state === "available"
|
||||
? partial.observations.finalization.value
|
||||
: undefined;
|
||||
const committedManifest =
|
||||
"capture" in partial
|
||||
? partial.capture.manifest
|
||||
: partial.observations.manifest.state === "available"
|
||||
? partial.observations.manifest.value
|
||||
: undefined;
|
||||
const manifestFinalizationIssue = finalizationManifestIssue(
|
||||
committedManifest?.scenario,
|
||||
committedManifest?.comparison_contract,
|
||||
);
|
||||
const exitFinalizationIssue =
|
||||
manifestFinalizationIssue ??
|
||||
(observedExit === undefined
|
||||
? undefined
|
||||
: finalizationConsistencyIssue(
|
||||
observedExit,
|
||||
committedManifest?.scenario,
|
||||
committedManifest?.comparison_contract,
|
||||
));
|
||||
const incompleteFinalizationIssue =
|
||||
manifestFinalizationIssue ??
|
||||
(observedFinalization === undefined
|
||||
? undefined
|
||||
: finalizationConsistencyIssue(
|
||||
observedExit === undefined
|
||||
? undefined
|
||||
: { reason: observedExit.reason, signal: observedExit.signal },
|
||||
committedManifest?.scenario,
|
||||
committedManifest?.comparison_contract,
|
||||
{ finalization: observedFinalization, allowNullElapsedMs: true },
|
||||
));
|
||||
if (exitFinalizationIssue !== undefined)
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["exit"],
|
||||
message: exitFinalizationIssue,
|
||||
});
|
||||
if (incompleteFinalizationIssue !== undefined)
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["finalization"],
|
||||
message: incompleteFinalizationIssue,
|
||||
});
|
||||
|
||||
const agreementIssue = finalizationAgreementIssue(
|
||||
observedExit?.finalization,
|
||||
observedFinalization,
|
||||
);
|
||||
if (agreementIssue !== undefined)
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["finalization"],
|
||||
message: agreementIssue,
|
||||
});
|
||||
if (
|
||||
"observations" in partial &&
|
||||
partial.observations.exit.state === "unavailable" &&
|
||||
observedFinalization !== undefined &&
|
||||
observedFinalization?.elapsed_ms !== null
|
||||
)
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["finalization"],
|
||||
message:
|
||||
"finalization elapsed_ms must be null when the exit observation is unavailable",
|
||||
});
|
||||
|
||||
if ("observations" in partial) {
|
||||
const { observations } = partial;
|
||||
if (
|
||||
|
||||
@@ -2,6 +2,9 @@ import { expect, it } from "vitest";
|
||||
|
||||
import { digestProcessCommitment } from "./processScenario.js";
|
||||
import { parseProcessCapture } from "./processCaptureParsing.js";
|
||||
import { partialProcessCaptureObservationSchema } from "./processCapture.js";
|
||||
import { FINALIZED_PROCESS_CAPTURE_EXAMPLE } from "./processCaptureExample.js";
|
||||
import { finalizationConsistencyIssue } from "./processCaptureValidation.js";
|
||||
import {
|
||||
compareUnverifiedProcessCaptures as compareProcessCaptures,
|
||||
emptyUnverifiedProcessCapture as emptyCapture,
|
||||
@@ -83,6 +86,645 @@ it("rejects settlement and cleanup combinations that cannot occur", () => {
|
||||
).toThrow("cleanup_outcome");
|
||||
});
|
||||
|
||||
it("rejects finalization evidence that no deadline could have produced", () => {
|
||||
const capture = emptyCapture();
|
||||
const finalization = {
|
||||
requested_ms: 500,
|
||||
exit_code: null,
|
||||
signals: [
|
||||
{
|
||||
signal: "SIGTERM" as const,
|
||||
sent_at_ms: 0,
|
||||
delivery: "signaled" as const,
|
||||
},
|
||||
],
|
||||
elapsed_ms: 10,
|
||||
};
|
||||
expect(
|
||||
() =>
|
||||
parseProcessCapture({
|
||||
...capture,
|
||||
exit: { code: 0, signal: null, reason: "exited", finalization },
|
||||
}),
|
||||
"an exit without a deadline cannot carry a finalization record",
|
||||
).toThrow("finalization");
|
||||
});
|
||||
|
||||
it("rejects a finalization reason on a verified delivery", () => {
|
||||
const finalization = {
|
||||
requested_ms: 500,
|
||||
exit_code: null,
|
||||
elapsed_ms: 10,
|
||||
signals: [
|
||||
{
|
||||
signal: "SIGTERM" as const,
|
||||
sent_at_ms: 0,
|
||||
delivery: "signaled" as const,
|
||||
reason: "should not be retained",
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
expect(
|
||||
() =>
|
||||
parseProcessCapture({
|
||||
...withCommittedFinalization(500, {
|
||||
code: null,
|
||||
signal: null,
|
||||
reason: "timeout",
|
||||
finalization,
|
||||
}),
|
||||
}),
|
||||
"a finalization reason is reserved for unverified delivery",
|
||||
).toThrow("finalization");
|
||||
});
|
||||
|
||||
const withCommittedFinalization = (
|
||||
committed: number | undefined,
|
||||
exit: Record<string, unknown>,
|
||||
comparisonCommitted: number | "same" | "absent" = "same",
|
||||
) => {
|
||||
const capture = emptyCapture();
|
||||
const scenario = {
|
||||
...capture.manifest.scenario,
|
||||
...(committed === undefined ? {} : { finalization_ms: committed }),
|
||||
};
|
||||
const comparisonContract = {
|
||||
...capture.manifest.comparison_contract,
|
||||
...(comparisonCommitted === "absent"
|
||||
? {}
|
||||
: comparisonCommitted === "same"
|
||||
? committed === undefined
|
||||
? {}
|
||||
: { finalization_ms: committed }
|
||||
: { finalization_ms: comparisonCommitted }),
|
||||
};
|
||||
return {
|
||||
...capture,
|
||||
manifest: {
|
||||
...capture.manifest,
|
||||
scenario,
|
||||
comparison_contract: comparisonContract,
|
||||
full_scenario_sha256: digestProcessCommitment(scenario),
|
||||
comparison_contract_sha256: digestProcessCommitment(comparisonContract),
|
||||
},
|
||||
exit,
|
||||
};
|
||||
};
|
||||
|
||||
it("binds finalization evidence to the committed finalization interval", () => {
|
||||
const finalization = {
|
||||
requested_ms: 500,
|
||||
exit_code: null,
|
||||
signals: [
|
||||
{
|
||||
signal: "SIGTERM" as const,
|
||||
sent_at_ms: 0,
|
||||
delivery: "signaled" as const,
|
||||
},
|
||||
],
|
||||
elapsed_ms: 10,
|
||||
};
|
||||
const exit = { code: null, signal: null, reason: "timeout", finalization };
|
||||
|
||||
expect(
|
||||
parseProcessCapture(withCommittedFinalization(500, exit)).exit,
|
||||
"a record matching the committed interval is accepted",
|
||||
).toMatchObject({ finalization });
|
||||
expect(
|
||||
() => parseProcessCapture(withCommittedFinalization(700, exit)),
|
||||
"a different committed interval contradicts the record",
|
||||
).toThrow("finalization");
|
||||
expect(
|
||||
() => parseProcessCapture(withCommittedFinalization(undefined, exit)),
|
||||
"a scenario that committed no interval cannot have finalized",
|
||||
).toThrow("finalization");
|
||||
expect(
|
||||
() =>
|
||||
parseProcessCapture(
|
||||
withCommittedFinalization(500, {
|
||||
...exit,
|
||||
finalization: { ...finalization, elapsed_ms: null },
|
||||
}),
|
||||
),
|
||||
"a complete capture requires an observed finalization exit time",
|
||||
).toThrow("finalization");
|
||||
});
|
||||
|
||||
it("validates finalization signal observations", () => {
|
||||
const finalization = {
|
||||
requested_ms: 500,
|
||||
exit_code: null,
|
||||
signals: [
|
||||
{
|
||||
signal: "SIGTERM" as const,
|
||||
sent_at_ms: 0,
|
||||
delivery: "signaled" as const,
|
||||
},
|
||||
],
|
||||
elapsed_ms: 10,
|
||||
};
|
||||
expect(
|
||||
finalizationConsistencyIssue({
|
||||
reason: "exited",
|
||||
finalization,
|
||||
}),
|
||||
"an exited reason cannot carry finalization",
|
||||
).toContain("finalization");
|
||||
expect(
|
||||
finalizationConsistencyIssue({
|
||||
reason: "timeout",
|
||||
finalization: {
|
||||
...finalization,
|
||||
signals: [{ signal: "SIGKILL", sent_at_ms: 500 }],
|
||||
},
|
||||
}),
|
||||
"the first attempt is SIGTERM",
|
||||
).toContain("SIGTERM");
|
||||
expect(
|
||||
finalizationConsistencyIssue({
|
||||
reason: "timeout",
|
||||
finalization: {
|
||||
...finalization,
|
||||
signals: [
|
||||
{ signal: "SIGTERM", sent_at_ms: 0 },
|
||||
{ signal: "SIGKILL", sent_at_ms: 500 },
|
||||
{ signal: "SIGKILL", sent_at_ms: 600 },
|
||||
],
|
||||
},
|
||||
}),
|
||||
"only one SIGKILL is allowed",
|
||||
).toContain("one final SIGKILL");
|
||||
expect(
|
||||
finalizationConsistencyIssue({
|
||||
reason: "timeout",
|
||||
finalization: {
|
||||
...finalization,
|
||||
signals: [
|
||||
{ signal: "SIGTERM", sent_at_ms: 10 },
|
||||
{ signal: "SIGKILL", sent_at_ms: 5 },
|
||||
],
|
||||
},
|
||||
}),
|
||||
"attempt times stay ordered",
|
||||
).toContain("must not decrease");
|
||||
expect(
|
||||
finalizationConsistencyIssue({
|
||||
reason: "timeout",
|
||||
finalization: {
|
||||
...finalization,
|
||||
signals: [
|
||||
{ signal: "SIGTERM", sent_at_ms: 0 },
|
||||
{ signal: "SIGKILL", sent_at_ms: 499 },
|
||||
],
|
||||
},
|
||||
}),
|
||||
"a non-cancelled early SIGKILL is rejected",
|
||||
).toContain("requested interval");
|
||||
expect(
|
||||
finalizationConsistencyIssue({
|
||||
reason: "cancelled",
|
||||
finalization: {
|
||||
...finalization,
|
||||
signals: [
|
||||
{ signal: "SIGTERM", sent_at_ms: 0 },
|
||||
{ signal: "SIGKILL", sent_at_ms: 1 },
|
||||
],
|
||||
},
|
||||
}),
|
||||
"a cancelled early SIGKILL is accepted",
|
||||
).toBeUndefined();
|
||||
expect(
|
||||
finalizationConsistencyIssue({
|
||||
reason: "timeout",
|
||||
finalization: {
|
||||
...finalization,
|
||||
signals: [{ signal: "SIGTERM", sent_at_ms: 1 }],
|
||||
elapsed_ms: 0,
|
||||
},
|
||||
}),
|
||||
"the observed exit cannot precede the first attempt",
|
||||
).toContain("elapsed_ms");
|
||||
expect(
|
||||
finalizationConsistencyIssue({
|
||||
reason: "timeout",
|
||||
finalization: { ...finalization, elapsed_ms: null },
|
||||
}),
|
||||
"an observed exit requires elapsed time",
|
||||
).toContain("elapsed_ms");
|
||||
expect(
|
||||
finalizationConsistencyIssue(
|
||||
{ reason: "timeout" },
|
||||
{ finalization_ms: 500 },
|
||||
),
|
||||
"a deadline exit with a committed interval must carry the record",
|
||||
).toContain("finalization evidence");
|
||||
});
|
||||
|
||||
it("validates finalization evidence in partial captures and rejects malformed records", () => {
|
||||
const { cleanup: _cleanup, ...completed } = emptyCapture();
|
||||
const partial = (exit: Record<string, unknown>) =>
|
||||
partialProcessCaptureObservationSchema.safeParse({
|
||||
capture: { ...completed, exit },
|
||||
cleanup: {
|
||||
owned_process_group: { state: "cleaned", reason: null },
|
||||
terminal_renderer: { state: "cleaned", reason: null },
|
||||
temporary_root: { state: "cleaned", reason: null },
|
||||
},
|
||||
execution_failure: "capture ended after a fixture error",
|
||||
});
|
||||
const partialWithCommittedFinalization = (exit: Record<string, unknown>) => {
|
||||
const { cleanup: _cleanup, ...completed } = withCommittedFinalization(500, {
|
||||
code: null,
|
||||
signal: null,
|
||||
reason: "timeout",
|
||||
});
|
||||
return partialProcessCaptureObservationSchema.safeParse({
|
||||
capture: { ...completed, exit },
|
||||
cleanup: {
|
||||
owned_process_group: { state: "cleaned", reason: null },
|
||||
terminal_renderer: { state: "cleaned", reason: null },
|
||||
temporary_root: { state: "cleaned", reason: null },
|
||||
},
|
||||
execution_failure: "capture ended after a fixture error",
|
||||
});
|
||||
};
|
||||
const finalization = {
|
||||
requested_ms: 500,
|
||||
exit_code: null,
|
||||
signals: [
|
||||
{
|
||||
signal: "SIGTERM" as const,
|
||||
sent_at_ms: 0,
|
||||
delivery: "signaled" as const,
|
||||
},
|
||||
],
|
||||
elapsed_ms: 10,
|
||||
};
|
||||
|
||||
expect(
|
||||
partial({ code: null, signal: null, reason: "timeout" }).success,
|
||||
"a partial exit without finalization stays valid",
|
||||
).toBe(true);
|
||||
expect(
|
||||
partial({ code: 0, signal: null, reason: "exited", finalization }).success,
|
||||
"a partial exit cannot finalize without a deadline",
|
||||
).toBe(false);
|
||||
expect(
|
||||
partial({
|
||||
code: null,
|
||||
signal: null,
|
||||
reason: "timeout",
|
||||
finalization: { ...finalization, requested_ms: 700 },
|
||||
}).success,
|
||||
"a partial record must match the committed interval",
|
||||
).toBe(false);
|
||||
expect(
|
||||
partialWithCommittedFinalization({
|
||||
code: null,
|
||||
signal: null,
|
||||
reason: "timeout",
|
||||
finalization: { ...finalization, elapsed_ms: null },
|
||||
})
|
||||
.error?.issues.map(({ message }) => message)
|
||||
.join("; "),
|
||||
"a capture variant requires an observed finalization exit time",
|
||||
).toContain("elapsed_ms");
|
||||
expect(
|
||||
() =>
|
||||
parseProcessCapture(
|
||||
withCommittedFinalization(500, {
|
||||
code: null,
|
||||
signal: null,
|
||||
reason: "timeout",
|
||||
finalization: {
|
||||
...finalization,
|
||||
signals: [
|
||||
{ signal: "SIGINT", sent_at_ms: 0, delivery: "signaled" },
|
||||
],
|
||||
},
|
||||
}),
|
||||
),
|
||||
"only SIGTERM can start finalization",
|
||||
).toThrow();
|
||||
expect(
|
||||
() =>
|
||||
parseProcessCapture(
|
||||
withCommittedFinalization(500, {
|
||||
code: null,
|
||||
signal: null,
|
||||
reason: "timeout",
|
||||
finalization: { ...finalization, elapsed_ms: -1 },
|
||||
}),
|
||||
),
|
||||
"elapsed time cannot be negative",
|
||||
).toThrow();
|
||||
});
|
||||
|
||||
it("binds the comparison contract to the committed finalization interval", () => {
|
||||
const exit = { code: 0, signal: null, reason: "exited" };
|
||||
|
||||
expect(
|
||||
() => parseProcessCapture(withCommittedFinalization(500, exit, "absent")),
|
||||
"a scenario interval missing from the comparison contract is contradictory",
|
||||
).toThrow("comparison_contract");
|
||||
expect(
|
||||
() => parseProcessCapture(withCommittedFinalization(500, exit, 900)),
|
||||
"a different comparison interval is contradictory",
|
||||
).toThrow("comparison_contract");
|
||||
expect(
|
||||
() => parseProcessCapture(withCommittedFinalization(undefined, exit, 500)),
|
||||
"a comparison interval the scenario never committed is contradictory",
|
||||
).toThrow("comparison_contract");
|
||||
});
|
||||
|
||||
// This single scenario shares one deliberately complete incomplete-capture fixture.
|
||||
// oxlint-disable-next-line max-lines-per-function
|
||||
it("validates finalization evidence in incomplete observations", () => {
|
||||
const finalization = {
|
||||
requested_ms: 500,
|
||||
exit_code: null,
|
||||
signals: [
|
||||
{
|
||||
signal: "SIGTERM" as const,
|
||||
sent_at_ms: 0,
|
||||
delivery: "signaled" as const,
|
||||
},
|
||||
],
|
||||
elapsed_ms: 10,
|
||||
};
|
||||
const unavailable = { state: "unavailable", reason: "not observed" };
|
||||
const incomplete = (
|
||||
exit: Record<string, unknown> | undefined,
|
||||
manifest: ReturnType<typeof withCommittedFinalization>["manifest"],
|
||||
incompleteFinalization: Record<string, unknown> | undefined = undefined,
|
||||
) => {
|
||||
const result = partialProcessCaptureObservationSchema.safeParse({
|
||||
observations: {
|
||||
target_pid: unavailable,
|
||||
frames: { state: "available", value: [] },
|
||||
rendered_frames: unavailable,
|
||||
interaction_events: unavailable,
|
||||
exit:
|
||||
exit === undefined
|
||||
? unavailable
|
||||
: { state: "available", value: exit },
|
||||
finalization:
|
||||
incompleteFinalization === undefined
|
||||
? unavailable
|
||||
: { state: "available", value: incompleteFinalization },
|
||||
settlement: unavailable,
|
||||
process_samples: unavailable,
|
||||
filesystem_snapshots: { before: unavailable, after: unavailable },
|
||||
event_journal: unavailable,
|
||||
manifest: { state: "available", value: manifest },
|
||||
},
|
||||
cleanup: {
|
||||
owned_process_group: { state: "cleaned", reason: null },
|
||||
terminal_renderer: { state: "cleaned", reason: null },
|
||||
temporary_root: { state: "cleaned", reason: null },
|
||||
},
|
||||
execution_failure: "capture ended after a fixture error",
|
||||
});
|
||||
return {
|
||||
success: result.success,
|
||||
messages: result.success
|
||||
? ""
|
||||
: result.error.issues.map(({ message }) => message).join("; "),
|
||||
};
|
||||
};
|
||||
const timeout = { code: null, signal: null, reason: "timeout" };
|
||||
const normal = { code: 0, signal: null, reason: "exited" };
|
||||
const committed = withCommittedFinalization(500, timeout).manifest;
|
||||
|
||||
expect(
|
||||
incomplete({ ...timeout, finalization }, committed).success,
|
||||
"a consistent incomplete record is accepted",
|
||||
).toBe(true);
|
||||
expect(
|
||||
incomplete({ ...timeout, finalization }, committed, { ...finalization })
|
||||
.success,
|
||||
"matching exit and sibling finalization observations are accepted",
|
||||
).toBe(true);
|
||||
const disagreement = incomplete({ ...timeout, finalization }, committed, {
|
||||
...finalization,
|
||||
elapsed_ms: 11,
|
||||
});
|
||||
expect(
|
||||
disagreement.success,
|
||||
"conflicting finalization observations are rejected",
|
||||
).toBe(false);
|
||||
expect(disagreement.messages, "the conflict names finalization").toContain(
|
||||
"finalization observation must agree",
|
||||
);
|
||||
expect(
|
||||
incomplete(undefined, committed, { ...finalization, elapsed_ms: null })
|
||||
.success,
|
||||
"a finalization observed without an exit permits null elapsed time",
|
||||
).toBe(true);
|
||||
const unavailableExitElapsed = incomplete(undefined, committed, finalization);
|
||||
expect(
|
||||
unavailableExitElapsed.success,
|
||||
"a finalization without an exit rejects a claimed elapsed time",
|
||||
).toBe(false);
|
||||
expect(
|
||||
unavailableExitElapsed.messages,
|
||||
"the unavailable-exit rule names elapsed_ms",
|
||||
).toContain("elapsed_ms");
|
||||
const sigkillFirst = incomplete(undefined, committed, {
|
||||
...finalization,
|
||||
elapsed_ms: null,
|
||||
signals: [{ signal: "SIGKILL", sent_at_ms: 0, delivery: "signaled" }],
|
||||
});
|
||||
expect(
|
||||
sigkillFirst.success,
|
||||
"an incomplete finalization still starts with SIGTERM",
|
||||
).toBe(false);
|
||||
expect(
|
||||
sigkillFirst.messages,
|
||||
"only the SIGTERM-first rule fires, not the null-elapsed rule",
|
||||
).toContain("start with SIGTERM");
|
||||
expect(
|
||||
incomplete(normal, withCommittedFinalization(undefined, normal).manifest)
|
||||
.success,
|
||||
"an incomplete capture that never committed an interval is accepted",
|
||||
).toBe(true);
|
||||
expect(
|
||||
incomplete(
|
||||
{ code: 0, signal: null, reason: "exited", finalization },
|
||||
committed,
|
||||
).success,
|
||||
"an incomplete exit cannot finalize without a deadline",
|
||||
).toBe(false);
|
||||
expect(
|
||||
incomplete(
|
||||
{ ...timeout, finalization: { ...finalization, requested_ms: 700 } },
|
||||
committed,
|
||||
).success,
|
||||
"an incomplete record must match the committed interval",
|
||||
).toBe(false);
|
||||
const scenarioOnly = withCommittedFinalization(
|
||||
500,
|
||||
normal,
|
||||
"absent",
|
||||
).manifest;
|
||||
const comparisonOnly = withCommittedFinalization(
|
||||
undefined,
|
||||
normal,
|
||||
500,
|
||||
).manifest;
|
||||
const differing = withCommittedFinalization(500, normal, 900).manifest;
|
||||
for (const [label, manifest] of [
|
||||
["a scenario interval missing from the comparison contract", scenarioOnly],
|
||||
["a comparison interval the scenario never committed", comparisonOnly],
|
||||
["differing intervals", differing],
|
||||
] as const) {
|
||||
const verdict = incomplete(normal, manifest);
|
||||
expect(verdict.success, `${label} is rejected`).toBe(false);
|
||||
expect(
|
||||
verdict.messages,
|
||||
`${label} is rejected for the comparison contract`,
|
||||
).toContain("comparison_contract");
|
||||
}
|
||||
const earlyKill = {
|
||||
requested_ms: 500,
|
||||
exit_code: null,
|
||||
elapsed_ms: 600,
|
||||
signals: [
|
||||
{ signal: "SIGTERM", sent_at_ms: 0, delivery: "signaled" },
|
||||
{ signal: "SIGKILL", sent_at_ms: 40, delivery: "unverified" },
|
||||
],
|
||||
};
|
||||
expect(
|
||||
incomplete(
|
||||
{
|
||||
code: null,
|
||||
signal: null,
|
||||
reason: "cancelled",
|
||||
finalization: earlyKill,
|
||||
},
|
||||
committed,
|
||||
earlyKill,
|
||||
).success,
|
||||
"a cancellation may keep an early SIGKILL attempt",
|
||||
).toBe(true);
|
||||
const earlyKillDeadline = incomplete(
|
||||
{ ...timeout, finalization: earlyKill },
|
||||
committed,
|
||||
earlyKill,
|
||||
);
|
||||
expect(
|
||||
earlyKillDeadline.success,
|
||||
"a deadline exit cannot carry a SIGKILL before the requested interval",
|
||||
).toBe(false);
|
||||
expect(
|
||||
earlyKillDeadline.messages,
|
||||
"the early SIGKILL negative isolates the requested interval rule",
|
||||
).toContain("requested interval");
|
||||
expect(
|
||||
incomplete(undefined, differing).success,
|
||||
"an unavailable exit still cannot hide a contradictory manifest",
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects chronologically impossible or repeated finalization attempts", () => {
|
||||
const attempt = (signal: "SIGTERM" | "SIGKILL", sent_at_ms: number) => ({
|
||||
signal,
|
||||
sent_at_ms,
|
||||
delivery: "signaled" as const,
|
||||
});
|
||||
const exit = (
|
||||
elapsed_ms: number | null,
|
||||
signals: ReturnType<typeof attempt>[],
|
||||
) => ({
|
||||
reason: "timeout",
|
||||
finalization: { requested_ms: 500, elapsed_ms, exit_code: null, signals },
|
||||
});
|
||||
|
||||
expect(
|
||||
finalizationConsistencyIssue(
|
||||
exit(10, [attempt("SIGTERM", 0), attempt("SIGKILL", 500)]),
|
||||
),
|
||||
"an exit cannot be observed before the last recorded attempt",
|
||||
).toContain("elapsed_ms");
|
||||
expect(
|
||||
finalizationConsistencyIssue(
|
||||
exit(600, [attempt("SIGTERM", 0), attempt("SIGTERM", 10)]),
|
||||
),
|
||||
"SIGTERM is attempted once",
|
||||
).toContain("finalization");
|
||||
expect(
|
||||
finalizationConsistencyIssue(
|
||||
exit(600, [attempt("SIGTERM", 0), attempt("SIGKILL", 500)]),
|
||||
),
|
||||
"a consistent record is accepted",
|
||||
).toBeUndefined();
|
||||
});
|
||||
|
||||
it("keeps the finalization exit code tied to an observed exit not caused by a signal", () => {
|
||||
const attempt = {
|
||||
signal: "SIGTERM" as const,
|
||||
sent_at_ms: 0,
|
||||
delivery: "signaled" as const,
|
||||
};
|
||||
const record = (
|
||||
elapsed_ms: number | null,
|
||||
exit_code: number | null,
|
||||
signal?: number | null,
|
||||
) => ({
|
||||
reason: "timeout",
|
||||
...(signal === undefined ? {} : { signal }),
|
||||
finalization: {
|
||||
requested_ms: 500,
|
||||
elapsed_ms,
|
||||
exit_code,
|
||||
signals: [attempt],
|
||||
},
|
||||
});
|
||||
|
||||
expect(
|
||||
finalizationConsistencyIssue(record(10, 3, 0)),
|
||||
"a code reported for an exit without a signal is accepted",
|
||||
).toBeUndefined();
|
||||
expect(
|
||||
finalizationConsistencyIssue(record(10, 3, 9)),
|
||||
"a code cannot accompany an exit ended by a signal",
|
||||
).toContain("exit_code");
|
||||
expect(
|
||||
finalizationConsistencyIssue(record(10, null, 9)),
|
||||
"a signal exit records a null code",
|
||||
).toBeUndefined();
|
||||
|
||||
const schemaFinalization = {
|
||||
requested_ms: 500,
|
||||
elapsed_ms: null,
|
||||
exit_code: 3,
|
||||
signals: [attempt],
|
||||
};
|
||||
expect(
|
||||
() =>
|
||||
parseProcessCapture(
|
||||
withCommittedFinalization(500, {
|
||||
code: null,
|
||||
signal: null,
|
||||
reason: "timeout",
|
||||
finalization: schemaFinalization,
|
||||
}),
|
||||
),
|
||||
"an exit code needs an observed exit",
|
||||
).toThrow("exit_code");
|
||||
});
|
||||
|
||||
it("accepts the canonical finalized capture example", () => {
|
||||
expect(
|
||||
parseProcessCapture(FINALIZED_PROCESS_CAPTURE_EXAMPLE).exit,
|
||||
"the advertised finalized example is a valid capture",
|
||||
).toMatchObject({
|
||||
reason: "timeout",
|
||||
finalization: { requested_ms: 1_500, signals: [{ signal: "SIGTERM" }] },
|
||||
});
|
||||
});
|
||||
|
||||
it("requires an explicit journal and validates complete journals", () => {
|
||||
const capture = emptyCapture();
|
||||
const { event_journal: _eventJournal, ...oldCapture } = capture;
|
||||
|
||||
@@ -109,3 +109,31 @@ export const EMPTY_PROCESS_CAPTURE_EXAMPLE = {
|
||||
temporary_root: "removed",
|
||||
},
|
||||
} satisfies JsonValue;
|
||||
|
||||
const finalizedScenario = { ...scenario, finalization_ms: 1_500 };
|
||||
const finalizedComparisonContract = { finalization_ms: 1_500 };
|
||||
|
||||
/** Valid capture of a timeout that finalized: SIGTERM delivered, exit observed. */
|
||||
export const FINALIZED_PROCESS_CAPTURE_EXAMPLE = {
|
||||
...EMPTY_PROCESS_CAPTURE_EXAMPLE,
|
||||
manifest: {
|
||||
...EMPTY_PROCESS_CAPTURE_EXAMPLE.manifest,
|
||||
scenario: finalizedScenario,
|
||||
comparison_contract: finalizedComparisonContract,
|
||||
full_scenario_sha256: digestProcessCommitment(finalizedScenario),
|
||||
comparison_contract_sha256: digestProcessCommitment(
|
||||
finalizedComparisonContract,
|
||||
),
|
||||
},
|
||||
exit: {
|
||||
code: null,
|
||||
signal: 0,
|
||||
reason: "timeout",
|
||||
finalization: {
|
||||
requested_ms: 1_500,
|
||||
elapsed_ms: 12,
|
||||
exit_code: 0,
|
||||
signals: [{ signal: "SIGTERM", sent_at_ms: 0, delivery: "signaled" }],
|
||||
},
|
||||
},
|
||||
} satisfies JsonValue;
|
||||
|
||||
@@ -1,7 +1,10 @@
|
||||
import { digestProcessCommitment } from "./processScenario.js";
|
||||
import { hasCaptureTruncation } from "./processCaptureCoverage.js";
|
||||
|
||||
import type { UnverifiedProcessCapture } from "./processCapture.js";
|
||||
import type {
|
||||
ProcessCaptureFinalization,
|
||||
UnverifiedProcessCapture,
|
||||
} from "./processCapture.js";
|
||||
/** One pure semantic validation failure in a shaped process capture. */
|
||||
export interface ProcessCaptureValidationIssue {
|
||||
readonly path: string;
|
||||
@@ -106,6 +109,136 @@ const validateEventJournal = (
|
||||
expectedSize, "event_journal", "nonempty journal must reference every captured observation");
|
||||
};
|
||||
|
||||
/**
|
||||
* The committed comparison contract carries `finalization_ms` exactly when the
|
||||
* committed scenario does, with the same value. Independent of the exit, so a
|
||||
* partial capture with an unavailable exit is still checked.
|
||||
*/
|
||||
export const finalizationManifestIssue = (
|
||||
committedScenario?: Readonly<Record<string, unknown>>,
|
||||
committedComparison?: Readonly<Record<string, unknown>>,
|
||||
): string | undefined =>
|
||||
committedScenario !== undefined &&
|
||||
committedComparison !== undefined &&
|
||||
committedScenario["finalization_ms"] !==
|
||||
committedComparison["finalization_ms"]
|
||||
? "comparison_contract finalization_ms must match the committed scenario"
|
||||
: undefined;
|
||||
|
||||
type FinalizationAttempts = Pick<
|
||||
ProcessCaptureFinalization,
|
||||
"requested_ms" | "elapsed_ms" | "exit_code"
|
||||
> & {
|
||||
readonly signals: readonly Pick<
|
||||
ProcessCaptureFinalization["signals"][number],
|
||||
"signal" | "sent_at_ms"
|
||||
>[];
|
||||
};
|
||||
|
||||
/** Ensure incomplete exit and sibling finalization observations preserve one fact. */
|
||||
export const finalizationAgreementIssue = (
|
||||
exitFinalization: ProcessCaptureFinalization | undefined,
|
||||
observedFinalization: ProcessCaptureFinalization | undefined,
|
||||
): string | undefined =>
|
||||
exitFinalization !== undefined &&
|
||||
observedFinalization !== undefined &&
|
||||
JSON.stringify(exitFinalization) !== JSON.stringify(observedFinalization)
|
||||
? "exit finalization and finalization observation must agree"
|
||||
: undefined;
|
||||
|
||||
/**
|
||||
* Cross-field rule for `exit.finalization`, shared by complete and partial
|
||||
* captures. Returns the violated rule, or undefined when the record is
|
||||
* consistent.
|
||||
*/
|
||||
export const finalizationConsistencyIssue = (
|
||||
exit:
|
||||
| {
|
||||
readonly reason: string;
|
||||
readonly signal?: number | null | undefined;
|
||||
readonly finalization?: FinalizationAttempts | undefined;
|
||||
}
|
||||
| undefined,
|
||||
committedScenario?: Readonly<Record<string, unknown>>,
|
||||
committedComparison?: Readonly<Record<string, unknown>>,
|
||||
options?: {
|
||||
readonly finalization?: FinalizationAttempts;
|
||||
readonly allowNullElapsedMs?: boolean;
|
||||
},
|
||||
): string | undefined => {
|
||||
const manifestIssue = finalizationManifestIssue(
|
||||
committedScenario,
|
||||
committedComparison,
|
||||
);
|
||||
if (manifestIssue !== undefined) return manifestIssue;
|
||||
const finalization = exit?.finalization ?? options?.finalization;
|
||||
if (finalization === undefined) {
|
||||
// A deadline that fired under a committed interval must have attempted
|
||||
// finalization; cancellation before the deadline legitimately has none.
|
||||
const committed = committedScenario?.["finalization_ms"];
|
||||
return (exit?.reason === "timeout" || exit?.reason === "idle_timeout") &&
|
||||
typeof committed === "number" &&
|
||||
committed > 0
|
||||
? "a deadline exit under a committed finalization_ms requires finalization evidence"
|
||||
: undefined;
|
||||
}
|
||||
if (exit?.reason === "exited")
|
||||
return "finalization requires a deadline exit reason";
|
||||
const first = finalization.signals[0];
|
||||
if (first?.signal !== "SIGTERM")
|
||||
return "finalization signals must start with SIGTERM";
|
||||
const killIndexes = finalization.signals.flatMap(({ signal }, index) =>
|
||||
signal === "SIGKILL" ? [index] : [],
|
||||
);
|
||||
if (
|
||||
killIndexes.length > 1 ||
|
||||
(killIndexes[0] !== undefined &&
|
||||
killIndexes[0] !== finalization.signals.length - 1)
|
||||
)
|
||||
return "finalization may contain at most one final SIGKILL";
|
||||
if (
|
||||
!finalization.signals.every(({ sent_at_ms }, index) => {
|
||||
const previous = finalization.signals[index - 1];
|
||||
return previous === undefined || sent_at_ms >= previous.sent_at_ms;
|
||||
})
|
||||
)
|
||||
return "finalization signal attempt times must not decrease";
|
||||
if (
|
||||
finalization.signals.filter(({ signal }) => signal === "SIGTERM").length !==
|
||||
1
|
||||
)
|
||||
return "finalization must attempt SIGTERM exactly once";
|
||||
const kill = finalization.signals.find(({ signal }) => signal === "SIGKILL");
|
||||
if (
|
||||
kill !== undefined &&
|
||||
kill.sent_at_ms < finalization.requested_ms &&
|
||||
exit !== undefined &&
|
||||
exit.reason !== "cancelled"
|
||||
)
|
||||
return "finalization SIGKILL cannot precede the requested interval";
|
||||
if (finalization.elapsed_ms === null && options?.allowNullElapsedMs !== true)
|
||||
return "finalization requires an observed elapsed_ms";
|
||||
if (
|
||||
finalization.exit_code !== null &&
|
||||
exit?.signal !== undefined &&
|
||||
exit.signal !== null &&
|
||||
exit.signal !== 0
|
||||
)
|
||||
return "finalization exit_code requires an exit not caused by a signal";
|
||||
if (
|
||||
finalization.elapsed_ms !== null &&
|
||||
finalization.elapsed_ms <
|
||||
(finalization.signals.at(-1)?.sent_at_ms ?? first.sent_at_ms)
|
||||
)
|
||||
return "finalization elapsed_ms cannot precede the last signal attempt";
|
||||
if (
|
||||
committedScenario !== undefined &&
|
||||
committedScenario["finalization_ms"] !== finalization.requested_ms
|
||||
)
|
||||
return "finalization must match the committed finalization_ms";
|
||||
return undefined;
|
||||
};
|
||||
|
||||
const validateLifecycle = (
|
||||
capture: UnverifiedProcessCapture,
|
||||
require: RequireInvariant,
|
||||
@@ -120,6 +253,12 @@ const validateLifecycle = (
|
||||
require(capture.exit.reason === "exited" ||
|
||||
capture.exit.code ===
|
||||
null, "exit", "deadline termination cannot declare a normal exit code");
|
||||
const finalizationIssue = finalizationConsistencyIssue(
|
||||
capture.exit,
|
||||
capture.manifest.scenario,
|
||||
capture.manifest.comparison_contract,
|
||||
);
|
||||
require(finalizationIssue === undefined, "exit", finalizationIssue ?? "");
|
||||
};
|
||||
|
||||
const validateCoverage = (
|
||||
|
||||
@@ -1,11 +1,137 @@
|
||||
import { expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
digestProcessCommitment,
|
||||
parseProcessScenario,
|
||||
PROCESS_TERMINAL_CELL_BUDGET,
|
||||
processComparisonContract,
|
||||
processScenarioCommitment,
|
||||
processScenarioSchema,
|
||||
} from "./processScenario.js";
|
||||
|
||||
const baseScenario = { executable: "/usr/bin/true" };
|
||||
|
||||
it("defaults the finalization interval to zero without changing committed identity", () => {
|
||||
const scenario = parseProcessScenario(baseScenario);
|
||||
|
||||
expect(scenario, "parsed scenario carries the default").toMatchObject({
|
||||
finalization_ms: 0,
|
||||
});
|
||||
expect(
|
||||
Object.hasOwn(processScenarioCommitment(scenario), "finalization_ms"),
|
||||
"full scenario commitment omits a zero interval",
|
||||
).toBe(false);
|
||||
expect(
|
||||
Object.hasOwn(processComparisonContract(scenario), "finalization_ms"),
|
||||
"comparison contract omits a zero interval",
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("accepts an explicit zero finalization interval", () => {
|
||||
expect(
|
||||
parseProcessScenario({ ...baseScenario, finalization_ms: 0 }),
|
||||
"zero is the immediate-kill default, not an invalid budget",
|
||||
).toMatchObject({ finalization_ms: 0 });
|
||||
});
|
||||
|
||||
it("commits a positive finalization interval in both identity projections", () => {
|
||||
const scenario = parseProcessScenario({
|
||||
...baseScenario,
|
||||
finalization_ms: 500,
|
||||
});
|
||||
|
||||
expect(
|
||||
processScenarioCommitment(scenario),
|
||||
"full scenario commitment records the interval",
|
||||
).toMatchObject({ finalization_ms: 500 });
|
||||
expect(
|
||||
processComparisonContract(scenario),
|
||||
"comparison contract records the interval",
|
||||
).toMatchObject({ finalization_ms: 500 });
|
||||
});
|
||||
|
||||
it.each([-1, 1.5, Number.MAX_SAFE_INTEGER + 1])(
|
||||
"rejects the finalization interval %j",
|
||||
(finalization_ms) => {
|
||||
expect(() =>
|
||||
parseProcessScenario({ ...baseScenario, finalization_ms }),
|
||||
).toThrow();
|
||||
},
|
||||
);
|
||||
|
||||
it("accepts a combined lifecycle budget up to the safe-integer limit", () => {
|
||||
const limit = Number.MAX_SAFE_INTEGER;
|
||||
const accepted = parseProcessScenario({
|
||||
...baseScenario,
|
||||
timeout_ms: limit - 100,
|
||||
idle_timeout_ms: 1,
|
||||
settle_ms: 90,
|
||||
finalization_ms: 10,
|
||||
});
|
||||
|
||||
expect(
|
||||
accepted.timeout_ms + accepted.finalization_ms + accepted.settle_ms,
|
||||
"a total exactly at the representable limit is accepted",
|
||||
).toBe(limit);
|
||||
expect(
|
||||
parseProcessScenario(baseScenario),
|
||||
"the default scenario stays far below the limit",
|
||||
).toMatchObject({ timeout_ms: 30_000, settle_ms: 100, finalization_ms: 0 });
|
||||
});
|
||||
|
||||
it.each([
|
||||
["timeout alone over the sum", { timeout_ms: Number.MAX_SAFE_INTEGER }],
|
||||
[
|
||||
"components that only overflow together",
|
||||
{
|
||||
timeout_ms: Number.MAX_SAFE_INTEGER - 10,
|
||||
settle_ms: 6,
|
||||
finalization_ms: 5,
|
||||
},
|
||||
],
|
||||
[
|
||||
"a large settle and finalization",
|
||||
{
|
||||
timeout_ms: 5,
|
||||
settle_ms: Number.MAX_SAFE_INTEGER,
|
||||
finalization_ms: 1,
|
||||
},
|
||||
],
|
||||
])("rejects %s with a representability message", (_label, budget) => {
|
||||
const parse = () =>
|
||||
parseProcessScenario({ ...baseScenario, idle_timeout_ms: 1, ...budget });
|
||||
|
||||
expect(parse, "the combined budget is rejected").toThrow(
|
||||
"timeout_ms + finalization_ms + settle_ms",
|
||||
);
|
||||
expect(parse, "the message names the representability limit").toThrow(
|
||||
"exactly representable",
|
||||
);
|
||||
});
|
||||
|
||||
it("keeps the committed identity of a scenario without finalization byte for byte", () => {
|
||||
const scenario = parseProcessScenario({
|
||||
executable: "/usr/bin/true",
|
||||
arguments: ["-x"],
|
||||
working_directory: "/tmp",
|
||||
environment: { A: "b" },
|
||||
filesystem_observation_paths: ["/tmp"],
|
||||
timeout_ms: 5_000,
|
||||
idle_timeout_ms: 2_000,
|
||||
settle_ms: 50,
|
||||
});
|
||||
|
||||
// Digests computed from the compiled base commit before finalization_ms existed.
|
||||
expect(
|
||||
digestProcessCommitment(processScenarioCommitment(scenario)),
|
||||
"the full scenario commitment is unchanged",
|
||||
).toBe("b50005d26269bd1db4a49c79e05bca67c3a18d837b45cd1c8ff591c01eb7623a");
|
||||
expect(
|
||||
digestProcessCommitment(processComparisonContract(scenario)),
|
||||
"the comparison contract commitment is unchanged",
|
||||
).toBe("675b759347a737a4f1cbfbf2fc759258d9c877216513f2f4dad3ed1e9e6e7631");
|
||||
});
|
||||
|
||||
it("admits the default and the exact combined terminal-cell budget", () => {
|
||||
expect(parseProcessScenario({ executable: "/bin/true" }).terminal).toEqual({
|
||||
columns: 80,
|
||||
|
||||
@@ -95,11 +95,17 @@ const committedScenarioEvents = (
|
||||
export const processScenarioCommitment = (
|
||||
scenario: ProcessScenario,
|
||||
executableSha256?: string,
|
||||
): Readonly<Record<string, unknown>> => ({
|
||||
...scenario,
|
||||
events: committedScenarioEvents(scenario.events, true),
|
||||
executable_sha256: executableSha256 ?? null,
|
||||
});
|
||||
): Readonly<Record<string, unknown>> => {
|
||||
// A zero interval is today's immediate kill; leaving it out keeps the
|
||||
// committed identity of every scenario that predates the field unchanged.
|
||||
const { finalization_ms: finalizationMs, ...committed } = scenario;
|
||||
return {
|
||||
...committed,
|
||||
...(finalizationMs > 0 ? { finalization_ms: finalizationMs } : {}),
|
||||
events: committedScenarioEvents(scenario.events, true),
|
||||
executable_sha256: executableSha256 ?? null,
|
||||
};
|
||||
};
|
||||
|
||||
/** Project observation settings shared by capture and reconstruction. */
|
||||
export const processComparisonContract = (
|
||||
@@ -117,6 +123,9 @@ export const processComparisonContract = (
|
||||
timeout_ms: scenario.timeout_ms,
|
||||
idle_timeout_ms: scenario.idle_timeout_ms,
|
||||
settle_ms: scenario.settle_ms,
|
||||
...(scenario.finalization_ms > 0
|
||||
? { finalization_ms: scenario.finalization_ms }
|
||||
: {}),
|
||||
limits: scenario.limits,
|
||||
normalization: scenario.normalization,
|
||||
...(scenario.normalization.ports
|
||||
@@ -177,6 +186,15 @@ export const processScenarioSchema = z
|
||||
timeout_ms: positiveBudget.default(30_000),
|
||||
idle_timeout_ms: positiveBudget.default(30_000),
|
||||
settle_ms: z.number().int().safe().nonnegative().default(100),
|
||||
finalization_ms: z
|
||||
.number()
|
||||
.int()
|
||||
.safe()
|
||||
.nonnegative()
|
||||
.default(0)
|
||||
.describe(
|
||||
"Milliseconds a target may keep running after SIGTERM when timeout_ms or idle_timeout_ms fires, before SIGKILL; 0 sends SIGKILL immediately. Both signals reach the captured root only while its launch-time start identity still matches; cancellation ends the run at once.",
|
||||
),
|
||||
limits: z
|
||||
.strictObject({
|
||||
output_bytes: positiveBudget.default(1_000_000),
|
||||
@@ -221,6 +239,18 @@ export const processScenarioSchema = z
|
||||
}),
|
||||
})
|
||||
.superRefine((scenario, context) => {
|
||||
// Each budget is a safe integer, but their sum is not checked anywhere
|
||||
// else. BigInt keeps the comparison exact beyond the representable range.
|
||||
const lifecycleBudget =
|
||||
BigInt(scenario.timeout_ms) +
|
||||
BigInt(scenario.finalization_ms) +
|
||||
BigInt(scenario.settle_ms);
|
||||
if (lifecycleBudget > BigInt(Number.MAX_SAFE_INTEGER))
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
message: `timeout_ms + finalization_ms + settle_ms must stay at or below ${String(Number.MAX_SAFE_INTEGER)} ms, the largest total exactly representable as a JavaScript number`,
|
||||
path: ["timeout_ms"],
|
||||
});
|
||||
if (
|
||||
!fitsProcessTerminalCellBudget(
|
||||
scenario.terminal.columns,
|
||||
|
||||
Reference in New Issue
Block a user