rea-agents 6.3.0 → 6.5.0

package/dist/domain/offsetDateTime.js

@@ -15,3 +15,63 @@ import { z } from "zod";
 export const offsetDateTimeSchema = z
     .string()
     .regex(/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|(?:[+\x2d](?:[01]\d|2[0-3]):[0-5]\d)))$/u, "Use an ISO-8601 date-time with an explicit UTC offset");
+/** Parse an already validated offset timestamp without losing sub-millisecond precision. */
+export const parseOffsetDateTimeInstant = (value) => {
+    const match = /^(.*?)(?:\.(\d+))?(Z|[+\x2d]\d{2}:\d{2})$/u.exec(value);
+    if (match === null)
+        throw new TypeError("Expected a validated offset date-time.");
+    const [, dateTime, fractionalDigits, offset] = match;
+    if (dateTime === undefined || offset === undefined)
+        throw new TypeError("Expected a validated offset date-time.");
+    const wholeSecondMilliseconds = Date.parse(`${dateTime}${offset}`);
+    if (!Number.isSafeInteger(wholeSecondMilliseconds) ||
+        wholeSecondMilliseconds % 1000 !== 0)
+        throw new TypeError("Offset date-time is outside the supported time range.");
+    return {
+        epochSecond: wholeSecondMilliseconds / 1000,
+        fraction: fractionalDigits?.replace(/0+$/u, "") ?? "",
+    };
+};
+/** Convert a Date.now-style integer into the same exact comparison shape. */
+export const offsetDateTimeInstantFromEpochMilliseconds = (epochMilliseconds) => {
+    if (!Number.isFinite(epochMilliseconds))
+        throw new TypeError("Expected finite epoch milliseconds.");
+    if (Math.abs(epochMilliseconds) > Number.MAX_SAFE_INTEGER)
+        return { epochSecond: epochMilliseconds / 1000, fraction: "" };
+    const epochSecond = Math.floor(epochMilliseconds / 1000);
+    const millisecondsWithinSecond = epochMilliseconds - epochSecond * 1000;
+    return {
+        epochSecond,
+        fraction: fractionalSecondFromMilliseconds(millisecondsWithinSecond),
+    };
+};
+const fractionalSecondFromMilliseconds = (milliseconds) => {
+    if (milliseconds === 0)
+        return "";
+    const [coefficient = "", exponentText] = String(milliseconds)
+        .toLowerCase()
+        .split("e");
+    const exponent = exponentText === undefined ? 0 : Number(exponentText);
+    const point = coefficient.indexOf(".");
+    const decimalPosition = (point < 0 ? coefficient.length : point) + exponent - 3;
+    const digits = coefficient.replace(".", "");
+    const fraction = decimalPosition <= 0
+        ? `0.${"0".repeat(-decimalPosition)}${digits}`
+        : decimalPosition < digits.length
+            ? `${digits.slice(0, decimalPosition)}.${digits.slice(decimalPosition)}`
+            : `${digits}${"0".repeat(decimalPosition - digits.length)}`;
+    return (fraction.includes(".") ? fraction.slice(fraction.indexOf(".") + 1) : "").replace(/0+$/u, "");
+};
+/** Compare instants exactly while treating absent fraction digits as zeroes. */
+export const compareOffsetDateTimeInstants = (left, right) => {
+    if (left.epochSecond !== right.epochSecond)
+        return left.epochSecond < right.epochSecond ? -1 : 1;
+    const length = Math.max(left.fraction.length, right.fraction.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftDigit = left.fraction.charCodeAt(index) || 48;
+        const rightDigit = right.fraction.charCodeAt(index) || 48;
+        if (leftDigit !== rightDigit)
+            return leftDigit < rightDigit ? -1 : 1;
+    }
+    return 0;
+};

package/dist/domain/pcap/pcapAnalysis.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { localPathStringSchema } from "../localPath.js";
+import { digestSchema } from "../digests.js";
+/**
+ * Caller intent for packet-capture analysis through caller-supplied tshark
+ * and capinfos. REA never installs Wireshark or its tools.
+ */
+export const pcapInputSchemas = {
+    inspect_pcap_client: z.strictObject({}),
+    inspect_pcap_capture: z.strictObject({
+        path: localPathStringSchema.describe("Local pcap or pcapng capture file to inspect"),
+    }),
+};
+/** Validate operation and input together so their types remain correlated. */
+export const pcapRequestSchema = z.discriminatedUnion("operation", [
+    z.strictObject({
+        operation: z.literal("inspect_pcap_client"),
+        input: pcapInputSchemas.inspect_pcap_client,
+    }),
+    z.strictObject({
+        operation: z.literal("inspect_pcap_capture"),
+        input: pcapInputSchemas.inspect_pcap_capture,
+    }),
+]);
+const client = z.strictObject({
+    tshark_command: z.string().min(1),
+    tshark_source: z.enum(["environment", "path"]),
+    tshark_version: z.string().min(1).nullable(),
+    capinfos_command: z.string().min(1),
+    capinfos_source: z.enum(["environment", "path"]),
+    capinfos_version: z.string().min(1).nullable(),
+});
+const endpoint = z.strictObject({
+    address: z.string().min(1),
+    port: z.number().int().positive().nullable(),
+    packet_count: z.number().int().positive(),
+});
+const dnsQuery = z.strictObject({
+    query: z.string().min(1),
+    response_addresses: z.array(z.string().min(1)),
+    response_address_count: z.number().int().nonnegative(),
+});
+const protocolCount = z.strictObject({
+    protocol: z.string().min(1),
+    packet_count: z.number().int().positive(),
+});
+/** Portable pcap observations with explicit coverage limitations. */
+export const pcapResultSchemas = {
+    inspect_pcap_client: z.strictObject({
+        client,
+    }),
+    inspect_pcap_capture: z.strictObject({
+        client,
+        target: z.strictObject({
+            path: localPathStringSchema,
+            bytes: z.number().int().nonnegative(),
+            sha256: digestSchema,
+        }),
+        /** File format as capinfos reports it (pcap vs pcapng). */
+        file_type: z.string().min(1).nullable(),
+        encapsulation: z.string().min(1).nullable(),
+        packet_count: z.number().int().nonnegative().nullable(),
+        capture_start: z.string().nullable(),
+        capture_end: z.string().nullable(),
+        capture_duration_seconds: z.number().nonnegative().nullable(),
+        snapshot_length: z.number().int().positive().nullable(),
+        /** Distinct endpoints with packet counts, bounded. */
+        endpoints: z.array(endpoint),
+        endpoint_count: z.number().int().nonnegative(),
+        /** DNS queries with resolved addresses, bounded. */
+        dns_queries: z.array(dnsQuery),
+        dns_query_count: z.number().int().nonnegative(),
+        /** TLS Server Name Indication values observed in handshakes. */
+        tls_sni_values: z.array(z.string().min(1)),
+        tls_sni_count: z.number().int().nonnegative(),
+        /** Protocol distribution (frame.protocols column counts). */
+        protocol_distribution: z.array(protocolCount),
+        protocol_count: z.number().int().nonnegative(),
+        /** HTTP request URIs seen on plain-text ports, bounded. */
+        http_request_uris: z.array(z.string().min(1)),
+        http_request_uri_count: z.number().int().nonnegative(),
+        http_uri_redaction_count: z.number().int().nonnegative(),
+        unattributed_dns_addresses: z.array(z.string().min(1)),
+        unattributed_dns_address_count: z.number().int().nonnegative(),
+        unattributed_dns_packet_count: z.number().int().nonnegative(),
+        coverage: z.enum(["complete", "partial"]),
+        diagnostics: z
+            .strictObject({ capinfos_stderr: z.string(), tshark_stderr: z.string() })
+            .optional(),
+    }),
+};

package/dist/domain/pcap/pcapEvidence.js

@@ -0,0 +1,15 @@
+import { createEvidence } from "../evidence.js";
+import { jsonObjectSchema } from "../jsonValue.js";
+/** One owner commits packet aggregation provenance and caller intent into Evidence. */
+export const createPcapEvidence = (request, observation) => createEvidence(observation.subject ?? undefined, observation.provider, {
+    operation: request.operation,
+    parameters: jsonObjectSchema.parse(request.input),
+    result: observation.result,
+    rawResult: observation.rawResult,
+    limitations: observation.limitations,
+    locations: observation.locations,
+    confidence: request.operation === "inspect_pcap_capture" ? "derived" : "observed",
+    ...(request.operation === "inspect_pcap_capture"
+        ? { authority: "historical-reference" }
+        : {}),
+});

package/dist/domain/peMachine.js

@@ -0,0 +1,36 @@
+const architectureForMachine = (machine) => {
+    switch (machine) {
+        case 0x014c:
+            return "x86";
+        case 0x8664:
+            return "x86_64";
+        case 0x01c0:
+        case 0x01c2:
+        case 0x01c4:
+            return "arm";
+        case 0xaa64:
+            return "arm64";
+    }
+    return undefined;
+};
+/**
+ * ReadyToRun images compiled for a non-Windows OS store the COFF machine XORed
+ * with IMAGE_FILE_MACHINE_NATIVE_OS_OVERRIDE (dotnet/runtime
+ * src/coreclr/inc/pedecoder.h): Apple, FreeBSD, OpenBSD, Linux, NetBSD, SunOS.
+ */
+const NATIVE_OS_OVERRIDES = [0x4644, 0xadc4, 0xadc5, 0x7b79, 0x1993, 0x1992];
+/**
+ * Decode a COFF machine. Only managed images carry an OS override, so callers
+ * must reject `nativeOsOverride` when the image has no CLI header.
+ */
+export const decodePeMachine = (machine) => {
+    const direct = architectureForMachine(machine);
+    if (direct !== undefined)
+        return { architecture: direct, nativeOsOverride: false };
+    for (const override of NATIVE_OS_OVERRIDES) {
+        const architecture = architectureForMachine(machine ^ override);
+        if (architecture !== undefined)
+            return { architecture, nativeOsOverride: true };
+    }
+    return undefined;
+};

package/dist/domain/pngHeader.js

@@ -0,0 +1,18 @@
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+const IHDR_TYPE = Buffer.from("IHDR");
+/** Read screenshot dimensions from a byte-faithful PNG header, not a full image decode. */
+export const readPngHeaderDimensions = (bytes) => {
+    if (bytes.byteLength < 24 ||
+        !bytes.subarray(0, 8).equals(PNG_SIGNATURE) ||
+        bytes.readUInt32BE(8) !== 13 ||
+        !bytes.subarray(12, 16).equals(IHDR_TYPE))
+        return undefined;
+    const width = bytes.readUInt32BE(16);
+    const height = bytes.readUInt32BE(20);
+    return width === 0 ||
+        height === 0 ||
+        width > 0x7fff_ffff ||
+        height > 0x7fff_ffff
+        ? undefined
+        : { width, height };
+};

package/dist/domain/process/processCapture.js

@@ -1,7 +1,7 @@
 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, } from "./processCaptureCoverage.js";
 /** Capture collection whose members participate in global observation order. */
 export const PROCESS_CAPTURE_EVENT_COLLECTIONS = [
@@ -88,6 +88,40 @@ const processSettlementSchema = z.discriminatedUnion("state", [
     }),
 ]);
 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),
@@ -145,6 +179,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({
@@ -221,7 +256,9 @@ 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"]),
         elapsed_ms: z.number().int().nonnegative(),
@@ -265,6 +302,59 @@ export const partialProcessCaptureObservationSchema = z
             path: ["execution_failure"],
             message: "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 (![

package/dist/domain/process/processCaptureCoverage.js

@@ -5,13 +5,24 @@ const byteRetentionSchema = z.strictObject({
     retained_bytes: z.number().int().nonnegative(),
     observed_frames: z.number().int().nonnegative(),
     retained_frames: z.number().int().nonnegative(),
+    unknown_size_frames: z.number().int().nonnegative().optional(),
 });
 /** 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"])),
+    enumeration_reasons: z.array(z.enum([
+        "files_limit",
+        "depth_limit",
+        "identity_changed",
+        "directory_unavailable",
+    ])),
+    enumeration_omissions: z.array(z.strictObject({
+        path: z.string(),
+        reason: z.literal("directory_unavailable"),
+        system_code: z.string().nullable(),
+    })),
     hash_budget_bytes: z.number().int().nonnegative(),
     hashed_bytes: z.number().int().nonnegative(),
     hash_omissions: z.array(z.strictObject({
@@ -29,7 +40,15 @@ export const filesystemCoverageSchema = z.strictObject({
 /** 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."),
+    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. When normalization exceeds a bound before the frame size is known, observed_bytes contains the exact total for size-known frames and unknown_size_frames counts the other omissions."),
+    normalized_terminal: z
+        .strictObject({
+        budget_bytes: z.number().int().nonnegative(),
+        retained_bytes: z.number().int().nonnegative(),
+        omitted_frames: z.number().int().nonnegative(),
+    })
+        .optional()
+        .describe("UTF-8 bytes of normalized raw-chunk text retained under output_bytes; omitted frames can have unknown final size when normalization exceeded an intermediate bound."),
     filesystem_before: filesystemCoverageSchema,
     filesystem_after: filesystemCoverageSchema,
     process: z.strictObject({
@@ -43,10 +62,14 @@ export const processCaptureTruncationDetailsSchema = z.strictObject({
     }),
 });
 const omitted = (retention) => retention.observed_frames > retention.retained_frames;
-const filesystemTruncated = (coverage) => coverage.enumeration_truncated || coverage.hash_omissions.length > 0;
+const filesystemTruncated = (coverage) => coverage.enumeration_truncated ||
+    coverage.enumeration_omissions.length > 0 ||
+    coverage.hash_omissions.length > 0;
 /** Derive the aggregate truncation flag from independent producer observations. */
 export const hasCaptureTruncation = (details) => omitted(details.raw_terminal) ||
     omitted(details.rendered_terminal) ||
+    (details.normalized_terminal?.omitted_frames ?? 0) > 0 ||
+    (details.rendered_terminal.unknown_size_frames ?? 0) > 0 ||
     filesystemTruncated(details.filesystem_before) ||
     filesystemTruncated(details.filesystem_after) ||
     details.process.sampling_partial;

package/dist/domain/process/processCaptureExample.js

@@ -76,6 +76,7 @@ export const EMPTY_PROCESS_CAPTURE_EXAMPLE = {
             depth_limit: 16,
             enumeration_truncated: false,
             enumeration_reasons: [],
+            enumeration_omissions: [],
             hash_budget_bytes: 10_000_000,
             hashed_bytes: 0,
             hash_omissions: [],
@@ -85,6 +86,7 @@ export const EMPTY_PROCESS_CAPTURE_EXAMPLE = {
             depth_limit: 16,
             enumeration_truncated: false,
             enumeration_reasons: [],
+            enumeration_omissions: [],
             hash_budget_bytes: 10_000_000,
             hashed_bytes: 0,
             hash_omissions: [],
@@ -106,3 +108,27 @@ export const EMPTY_PROCESS_CAPTURE_EXAMPLE = {
         temporary_root: "removed",
     },
 };
+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" }],
+        },
+    },
+};

package/dist/domain/process/processCaptureValidation.js

@@ -1,8 +1,8 @@
-import { digestProcessCommitment } from "./processScenario.js";
+import { digestProcessCommitment, processScenarioOutputBudgetProjectionSchema, } from "./processScenario.js";
 import { hasCaptureTruncation } from "./processCaptureCoverage.js";
 const orderedTimestamps = (values) => values.every((value, index) => {
     const previous = values[index - 1];
-    return previous === undefined || value.at_ms >= previous.at_ms;
+    return previous === undefined || value >= previous;
 });
 const validateCommitments = (capture, require) => {
     const { manifest } = capture;
@@ -21,8 +21,6 @@ const validateCommitments = (capture, require) => {
     ])
         require(manifest[field] ===
             digestProcessCommitment(value), `manifest.${field}`, "commitment does not match its canonical value");
-    require(Date.parse(manifest.started_at) <=
-        Date.parse(manifest.completed_at), "manifest.completed_at", "completion precedes start");
 };
 const validateOrdering = (capture, require) => {
     for (const [name, values] of [
@@ -36,7 +34,10 @@ const validateOrdering = (capture, require) => {
         ["rendered_frames", capture.rendered_frames],
         ["process_samples", capture.process_samples],
     ])
-        require(orderedTimestamps(values), name, "timestamps must be ordered");
+        require(orderedTimestamps(values.map(({ at_ms }) => at_ms)), name, "timestamps must be ordered");
+    // Interactions are dispatched in sequence, so their recorded dispatch
+    // times cannot decrease; comparison ranks a changed interaction by it.
+    require(orderedTimestamps(capture.interaction_events.map(({ dispatched_at_ms }) => dispatched_at_ms)), "interaction_events", "dispatch timestamps must be ordered");
 };
 const validateEventJournal = (capture, require) => {
     const journal = capture.event_journal;
@@ -64,15 +65,94 @@ const validateEventJournal = (capture, require) => {
     require(journal.length ===
         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, committedComparison) => committedScenario !== undefined &&
+    committedComparison !== undefined &&
+    committedScenario["finalization_ms"] !==
+        committedComparison["finalization_ms"]
+    ? "comparison_contract finalization_ms must match the committed scenario"
+    : undefined;
+/** Ensure incomplete exit and sibling finalization observations preserve one fact. */
+export const finalizationAgreementIssue = (exitFinalization, observedFinalization) => 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, committedScenario, committedComparison, options) => {
+    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, require) => {
     require(capture.filesystem_checkpoints.map(({ name }) => name).join(",") ===
         "before,after_settlement", "filesystem_checkpoints", "capture must include initial and final filesystem snapshots");
-    require(orderedTimestamps(capture.filesystem_checkpoints), "filesystem_checkpoints", "filesystem snapshot times must be ordered");
+    require(orderedTimestamps(capture.filesystem_checkpoints.map(({ at_ms }) => at_ms)), "filesystem_checkpoints", "filesystem snapshot times must be ordered");
     require(!capture.filesystem_checkpoints.some(({ truncated }) => truncated) ||
         capture.truncated, "truncated", "filesystem snapshot truncation must propagate to the capture");
     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 = (capture, require) => {
     const details = capture.truncation_details;
@@ -108,8 +188,25 @@ const validateCoverage = (capture, require) => {
             retention.observed_bytes >= retention.retained_bytes &&
             (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");
+            retention.retained_bytes <= retention.budget_bytes &&
+            (retention.unknown_size_frames ?? 0) <=
+                retention.observed_frames -
+                    retention.retained_frames, `truncation_details.${name}`, "retained observations and budget accounting do not agree");
+    }
+    const normalized = details.normalized_terminal;
+    if (normalized !== undefined) {
+        const committedOutputBudget = processScenarioOutputBudgetProjectionSchema.safeParse(capture.manifest.scenario["limits"]);
+        require(committedOutputBudget.success, "manifest.scenario.limits.output_bytes", "committed process scenario must include an explicit valid output_bytes budget");
+        const retainedBytes = capture.frames.reduce((total, frame) => total + Buffer.byteLength(frame.data), 0);
+        if (committedOutputBudget.success)
+            require(normalized.budget_bytes ===
+                committedOutputBudget.data.output_bytes &&
+                normalized.retained_bytes === retainedBytes &&
+                normalized.retained_bytes <= normalized.budget_bytes &&
+                normalized.omitted_frames <=
+                    details.raw_terminal.observed_frames -
+                        details.raw_terminal
+                            .retained_frames, "truncation_details.normalized_terminal", "normalized terminal retention must agree with the committed budget and retained frames");
     }
     for (const [name, coverage, files, checkpoint] of [
         [
@@ -128,6 +225,7 @@ const validateCoverage = (capture, require) => {
         const unhashedFiles = new Map(files
             .filter((file) => file.type === "file" && file.sha256 === null)
             .map((file) => [file.path, file]));
+        const directories = new Set(files.filter((file) => file.type === "directory").map(({ path }) => path));
         require(coverage.hash_omissions.length === unhashedFiles.size &&
             new Set(coverage.hash_omissions.map(({ path }) => path)).size ===
                 unhashedFiles.size &&
@@ -136,6 +234,11 @@ const validateCoverage = (capture, require) => {
                 (omission.reason === "file_unavailable"
                     ? omission.system_code !== null
                     : omission.system_code === null)), `truncation_details.${name}.hash_omissions`, "every retained regular file without a digest must have one matching omission reason");
+        require(new Set(coverage.enumeration_omissions.map(({ path }) => path))
+            .size === coverage.enumeration_omissions.length &&
+            (coverage.enumeration_omissions.length === 0 ||
+                coverage.enumeration_reasons.includes("directory_unavailable")) &&
+            coverage.enumeration_omissions.every((omission) => directories.has(omission.path) && omission.system_code !== null), `truncation_details.${name}.enumeration_omissions`, "every directory enumeration omission must identify one retained directory and its system error");
         require(coverage.hashed_bytes ===
             files
                 .filter((file) => file.type === "file" && file.sha256 !== null)
@@ -147,6 +250,7 @@ const validateCoverage = (capture, require) => {
             coverage.enumeration_reasons.length > 0 &&
             checkpoint?.truncated ===
                 (coverage.enumeration_truncated ||
+                    coverage.enumeration_omissions.length > 0 ||
                     coverage.hash_omissions.length >
                         0), `truncation_details.${name}`, "filesystem checkpoint truncation must match enumeration and digest coverage");
     }