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