rea-agents 6.2.0 → 6.4.0

package/dist/domain/native/nativeCallObservation.js

@@ -3,7 +3,7 @@ import { localPathStringSchema } from "../localPath.js";
 const hexSchema = z.string().regex(/^0x[0-9a-f]+$/u);
 const nativeString = z
     .string()
-    .regex(/^[^\u0000]*$/u, "Native launch and breakpoint strings cannot contain NUL");
+    .regex(/^[^\x00]*$/u, "Native launch and breakpoint strings cannot contain NUL");
 /** Objective-C class names and selectors never contain spaces or brackets. */
 const objcName = nativeString
     .min(1)
@@ -46,9 +46,7 @@ export const nativeCallObservationInputSchema = z.strictObject({
         .record(z
         .string()
         .min(1)
-        .regex(/^[^=\u0000]+$/u, "Environment names cannot contain '=' or NUL"), z
-        .string()
-        .regex(/^[^\u0000]*$/u, "Environment values cannot contain NUL"))
+        .regex(/^[^=\x00]+$/u, "Environment names cannot contain '=' or NUL"), z.string().regex(/^[^\x00]*$/u, "Environment values cannot contain NUL"))
         .default({})
         .describe("Overrides on top of the environment REA runs with."),
     working_directory: localPathStringSchema.optional(),

package/dist/domain/native/nativeInstruction.js

@@ -12,6 +12,27 @@ const reference = z.strictObject({
     indirect: z.boolean(),
     computed: z.boolean(),
     operand_index: z.number().int(),
+    source_address: z.string().min(1).nullable().optional(),
+    data: z.boolean().nullable().optional(),
+    read: z.boolean().nullable().optional(),
+    write: z.boolean().nullable().optional(),
+    primary: z
+        .boolean()
+        .nullable()
+        .optional()
+        .describe("Provider primary-reference status, not proof of literal addressing or a runtime access. Null or omission means unavailable."),
+    provenance: z
+        .string()
+        .min(1)
+        .nullable()
+        .optional()
+        .describe("Provider subsystem reporting this reference; null or omission means unavailable."),
+    source: z
+        .string()
+        .min(1)
+        .nullable()
+        .optional()
+        .describe("Provider reference origin, such as analysis, default, imported or user_defined; null or omission means unavailable."),
 });
 /** Provider-decoded facts for one instruction; operand tokens preserve their native ordering. */
 export const nativeInstructionSchema = z.strictObject({

package/dist/domain/native/nativeMetadataRecovery.js

@@ -4,6 +4,8 @@ const relatedType = z.strictObject({ address, type: z.string().nullable() });
 /** Runtime-format metadata recovered in an analysis image, with explicit inference boundaries. */
 export const nativeMetadataRecoverySchema = z.strictObject({
     format: z.literal("dotnet-nativeaot"),
+    /** Identifies parser-only facts without claiming Ghidra defined a DataType. */
+    source: z.enum(["analysis-database", "read-only-derived-overlay"]).optional(),
     status: z.enum(["complete", "partial"]),
     header_address: address,
     format_major: z.number().int().nonnegative(),
@@ -21,18 +23,25 @@ export const nativeMetadataRecoverySchema = z.strictObject({
         procedure_name: z.string().nullable(),
         basis: z.literal("method-table-pointer"),
     })),
-    derived_memory: z.strictObject({
+    derived_memory: z
+        .strictObject({
         address,
         size_bytes: z.number().int().nonnegative(),
         sha256: z.string().regex(/^[a-f0-9]{64}$/u),
         file_offset: z.null(),
-    }),
+    })
+        .nullable(),
+    truncated: z.boolean().optional(),
+    virtual_slots_omitted: z.number().int().nonnegative().optional(),
+    interfaces_omitted: z.number().int().nonnegative().optional(),
+    output_budget_bytes: z.number().int().nonnegative().optional(),
     diagnostics: z.array(z.string()),
     limitations: z.array(z.string()),
 });
 /** Discover a recovered runtime format and reusable type identities from the loaded image. */
 export const nativeMetadataRecoverySummarySchema = z.strictObject({
     format: z.literal("dotnet-nativeaot"),
+    analysis_mode: z.literal("read-only-derived-overlay").optional(),
     status: z.enum(["complete", "partial", "not_applicable"]),
     reason: z.string().nullable(),
     analysis_artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
@@ -42,12 +51,76 @@ export const nativeMetadataRecoverySummarySchema = z.strictObject({
     format_minor: z.number().int().nonnegative().nullable(),
     method_tables: z.number().int().nonnegative(),
     types: z.array(relatedType),
-    derived_memory: nativeMetadataRecoverySchema.shape.derived_memory.nullable(),
+    frozen_strings: z
+        .array(z.strictObject({ address, value: z.string() }))
+        .optional(),
+    truncated: z.boolean().optional(),
+    types_omitted: z.number().int().nonnegative().optional(),
+    frozen_strings_omitted: z.number().int().nonnegative().optional(),
+    output_budget_bytes: z.number().int().nonnegative().optional(),
+    derived_overlay: z
+        .strictObject({
+        address,
+        size_bytes: z.number().int().nonnegative(),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    })
+        .nullable()
+        .optional(),
+    derived_memory: nativeMetadataRecoverySchema.shape.derived_memory,
     coverage: z
         .strictObject({
-        frozen_object_candidates: z.number().int().nonnegative(),
-        frozen_objects_annotated: z.number().int().nonnegative(),
-        basis: z.literal("rehydrated-pointer-candidates-and-committed-instance-types"),
+        frozen_object_candidates: z.number().int().nonnegative().optional(),
+        frozen_objects_annotated: z.number().int().nonnegative().optional(),
+        pointer_candidates_examined: z.number().int().nonnegative().optional(),
+        pointer_slots_examined: z.number().int().nonnegative().optional(),
+        scan_bytes_examined: z.number().int().nonnegative().optional(),
+        scan_bytes_omitted: z.number().int().nonnegative().optional(),
+        rtr_signature_scan_bytes_examined: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional(),
+        rtr_signature_scan_bytes_omitted: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional(),
+        method_table_validation_items_examined: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional(),
+        work_units_examined: z.number().int().nonnegative().optional(),
+        method_tables_recovered: z.number().int().nonnegative().optional(),
+        frozen_string_candidates: z.number().int().nonnegative().optional(),
+        frozen_scan_bytes_examined: z.number().int().nonnegative().optional(),
+        frozen_scan_bytes_omitted: z.number().int().nonnegative().optional(),
+        frozen_string_data_bytes_examined: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional(),
+        source_bytes_examined: z.number().int().nonnegative().optional(),
+        source_bytes_omitted: z.number().int().nonnegative().optional(),
+        source_byte_budget_bytes: z.number().int().nonnegative().optional(),
+        work_budget_units: z.number().int().nonnegative().optional(),
+        working_memory_budget_bytes: z.number().int().nonnegative().optional(),
+        working_memory_bytes_peak: z.number().int().nonnegative().optional(),
+        truncation_reason: z
+            .enum([
+            "source-byte-budget",
+            "work-unit-budget",
+            "working-memory-budget",
+            "response-budget",
+        ])
+            .optional(),
+        basis: z.enum([
+            "rehydrated-pointer-candidates-and-committed-instance-types",
+            "raw-image-pointer-scan",
+            "raw-image-and-rehydrated-pointer-scan",
+            "unsupported-layout",
+            "no-rtr-header",
+        ]),
     })
         .nullable(),
     diagnostics: z.array(z.string()),

package/dist/domain/native/nativeValueFlow.js

@@ -16,9 +16,7 @@ export const nativePcodeOperationSchema = z.strictObject({
     sequence: z.number().int().nonnegative(),
     opcode: z.string().min(1),
     is_dead: z.boolean(),
-    block_membership: z
-        .enum(["member", "detached", "unavailable"])
-        .default("unavailable"),
+    block_membership: z.enum(["member", "detached", "unavailable"]),
     inputs: z.array(nativeVarnodeSchema),
     output: nativeVarnodeSchema.nullable(),
 });
@@ -50,20 +48,16 @@ export const nativeValueFlowSchema = z.discriminatedUnion("available", [
         operations: z.array(nativePcodeOperationSchema),
         def_use: z.array(nativePcodeDefUseSchema),
         effects: z.array(nativePcodeEffectSchema),
-        parameters: z
-            .array(z.strictObject({
+        parameters: z.array(z.strictObject({
             ordinal: z.number().int().nonnegative(),
             name: z.string(),
             data_type: z.string(),
-        }))
-            .default([]),
-        parameter_uses: z
-            .array(z.strictObject({
+        })),
+        parameter_uses: z.array(z.strictObject({
             ordinal: z.number().int().nonnegative(),
             use: z.string(),
             input_index: z.number().int().nonnegative(),
-        }))
-            .default([]),
+        })),
         truncated: z.boolean(),
         omitted_operations_lower_bound: z.number().int().nonnegative(),
         known_omitted_inputs: z.number().int().nonnegative(),

package/dist/domain/native/objcSwiftMetadata.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { compareUnicodeCodePoints, compositeKey, } from "../unicodeCodePointOrder.js";
 /** Objective-C method type. */
 export const objcMethodTypeSchema = z.enum([
     "instance",
@@ -10,25 +11,22 @@ export const objcMethodTypeSchema = z.enum([
 export const objcPropertyAttributeSchema = z.strictObject({
     name: z.string().min(1),
     value: z.string(),
-    is_weak: z.boolean().default(false),
-    is_atomic: z.boolean().default(false),
-    is_copy: z.boolean().default(false),
-    is_strong: z.boolean().default(false),
 });
 /** Objective-C method metadata. */
 export const objcMethodSchema = z.strictObject({
     selector: z.string().min(1),
     method_type: objcMethodTypeSchema,
     address: z.number().int().nullable(),
-    is_required: z.boolean().default(false),
-    is_optional: z.boolean().default(false),
+    is_required: z.boolean().nullable(),
+    is_optional: z.boolean().nullable(),
 });
 /** Objective-C property metadata. */
 export const objcPropertySchema = z.strictObject({
     name: z.string().min(1),
     type_encoding: z.string().nullable(),
-    attributes: z.array(objcPropertyAttributeSchema).default([]),
-    is_readonly: z.boolean().default(false),
+    attributes: z.array(objcPropertyAttributeSchema),
+    atomicity: z.enum(["atomic", "nonatomic"]).nullable(),
+    is_readonly: z.boolean().nullable(),
     getter: z.string().nullable(),
     setter: z.string().nullable(),
 });
@@ -43,12 +41,12 @@ export const objcProtocolSchema = z.strictObject({
 export const objcClassSchema = z.strictObject({
     name: z.string().min(1),
     super_class: z.string().nullable(),
-    is_meta_class: z.boolean().default(false),
-    is_root_class: z.boolean().default(false),
+    is_meta_class: z.boolean().nullable(),
+    is_root_class: z.boolean().nullable(),
     methods: z.array(objcMethodSchema).default([]),
     properties: z.array(objcPropertySchema).default([]),
     protocols: z.array(z.string()).default([]),
-    ivar_count: z.number().int().nonnegative().default(0),
+    ivar_count: z.number().int().nonnegative().nullable(),
     instance_size: z.number().int().nonnegative().nullable(),
     location: z
         .object({
@@ -333,23 +331,23 @@ export const inspectNativeDispatchMetadata = (names, maxRecords = 5_000) => {
             selector: implementation.selector,
             method_type: implementation.method_type,
             address: parseMetadataAddress(implementation.implementation_address),
-            is_required: false,
-            is_optional: false,
+            is_required: null,
+            is_optional: null,
         });
         methodsByClass.set(implementation.class_name, methods);
     }
     const classes = [...classNames].sort().map((name) => ({
         name,
         super_class: null,
-        is_meta_class: false,
-        is_root_class: false,
+        is_meta_class: null,
+        is_root_class: null,
         methods: methodsByClass.get(name) ?? [],
         properties: [],
         protocols: [],
-        ivar_count: 0,
+        ivar_count: null,
         instance_size: null,
     }));
-    const decodedImplementations = [...implementations.values()].sort((left, right) => `${left.class_name}:${left.selector}`.localeCompare(`${right.class_name}:${right.selector}`));
+    const decodedImplementations = [...implementations.values()].sort((left, right) => compareUnicodeCodePoints(compositeKey([left.class_name, left.selector]), compositeKey([right.class_name, right.selector])));
     const swift = swiftSymbols.length > 0;
     return objcSwiftMetadataSchema.parse({
         objc_classes: classes,

package/dist/domain/native/peResources.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+const uint = z.number().int().min(0).max(0xffffffff);
+const range = z.strictObject({ offset: uint, bytes: uint });
+const identity = z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("id"), id: uint }),
+    z.strictObject({
+        kind: z.literal("name"),
+        name: z.string(),
+        utf16le_hex: z.string().regex(/^(?:[0-9a-f]{4})*$/),
+        location: range,
+    }),
+]);
+/** Complete bounded inspection of a caller-selected PE image, without execution. */
+export const inspectPeResourcesInputSchema = z.strictObject({
+    path: z.string().min(1).describe("Absolute filesystem path to a PE image"),
+    max_file_bytes: z
+        .number()
+        .int()
+        .min(64)
+        .max(536870912)
+        .default(67108864)
+        .describe("Maximum stable artifact bytes to read (default 64 MiB)"),
+    max_entries: z
+        .number()
+        .int()
+        .min(1)
+        .max(65536)
+        .default(4096)
+        .describe("Maximum resource directory entries to examine; exceeding the budget fails without partial success"),
+});
+/** Original file/RVA locations and resource identities; icon edges are static relationships. */
+export const peResourcesSchema = z.strictObject({
+    artifact: z.strictObject({
+        path: z.string().min(1),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/),
+        bytes: uint,
+    }),
+    format: z.enum(["pe32", "pe32-plus"]),
+    machine: uint,
+    directory: z
+        .strictObject({
+        rva: uint,
+        location: range,
+        data_directory_location: range,
+    })
+        .nullable(),
+    directories: z.array(z.strictObject({
+        location: range,
+        characteristics: uint,
+        timestamp: uint,
+        major_version: uint,
+        minor_version: uint,
+        named_entries: uint,
+        id_entries: uint,
+    })),
+    resources: z.array(z.strictObject({
+        index: uint,
+        type: identity,
+        name: identity,
+        language: identity,
+        entry_locations: z.array(range).length(3),
+        data_entry_location: range,
+        code_page: uint,
+        reserved: uint,
+        payload: z.strictObject({
+            rva: uint,
+            location: range,
+            sha256: z.string().regex(/^[a-f0-9]{64}$/),
+        }),
+    })),
+    icon_groups: z.array(z.strictObject({
+        resource_index: uint,
+        images: z.array(z.strictObject({
+            location: range,
+            width: uint,
+            height: uint,
+            color_count: uint,
+            reserved: uint,
+            planes: uint,
+            bit_count: uint,
+            declared_bytes: uint,
+            resource_id: uint,
+            candidate_resource_indices: z.array(uint),
+            same_language_resource_index: uint.nullable(),
+            size_matches: z.boolean().nullable(),
+        })),
+    })),
+    coverage: z.strictObject({
+        status: z.literal("complete"),
+        examined_entries: uint,
+        resources: uint,
+    }),
+    limitations: z.array(z.string()),
+});

package/dist/domain/nativeConvention.js

@@ -0,0 +1,33 @@
+/** Path-segment conventions. These are inferences, not observations of runtime behavior. */
+const foldSegment = (segment) => segment.toLocaleLowerCase("en-US");
+const REACT_NATIVE_SEGMENTS = new Set([
+    "react.framework",
+    "reactnative.framework",
+    "libreactnative.so",
+    "libreactnativejni.so",
+    "libhermes_executor.so",
+    "libhermes.so",
+    "hermes.framework",
+]);
+const FLUTTER_SEGMENTS = new Set(["libflutter.so", "flutter.framework"]);
+const UNITY_SEGMENTS = new Set(["libunity.so", "unityframework.framework"]);
+/**
+ * A runtime family named by one filename or directory segment.
+ * Only recognized complete library and framework names establish a convention.
+ */
+export const nativeRuntimeConvention = (path) => {
+    for (const segment of path.split("/")) {
+        const folded = foldSegment(segment);
+        if (REACT_NATIVE_SEGMENTS.has(folded))
+            return "react-native";
+        if (FLUTTER_SEGMENTS.has(folded))
+            return "flutter";
+        if (UNITY_SEGMENTS.has(folded))
+            return "unity";
+    }
+    return null;
+};
+/** Swift runtime libraries are `libswift*.dylib` segments, not every dynamic library. */
+export const isSwiftRuntimeLibrary = (path) => path
+    .split("/")
+    .some((segment) => /^libswift.+\.dylib$/u.test(foldSegment(segment)));

package/dist/domain/process/processCapture.js

@@ -1,8 +1,8 @@
 import { z } from "zod";
 import { jsonValueSchema } from "../jsonValue.js";
 import { normalizationSchema } from "./processScenario.js";
-import { collectProcessCaptureIssues } from "./processCaptureValidation.js";
-import { processCaptureTruncationDetailsSchema, } from "./processCaptureCoverage.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 = [
     "frames",
@@ -40,6 +40,13 @@ const fileStateSchema = z.discriminatedUnion("type", [
         symlink_target: z.null(),
     }),
 ]);
+/** Canonical checkpoint facts retained even when capture completion fails. */
+export const processFilesystemSnapshotSchema = z.strictObject({
+    files: z.array(fileStateSchema),
+    truncated: z.boolean(),
+    completeRoots: z.array(z.string()),
+    coverage: filesystemCoverageSchema,
+});
 const fileEffectSchema = z.discriminatedUnion("status", [
     z.object({
         path: z.string(),
@@ -81,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),
@@ -138,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({
@@ -175,7 +217,7 @@ const processCaptureShapeSchema = z.strictObject({
     files_after: z.array(fileStateSchema),
     filesystem_effects: z.array(fileEffectSchema),
     truncated: z.boolean(),
-    truncation_details: processCaptureTruncationDetailsSchema.optional(),
+    truncation_details: processCaptureTruncationDetailsSchema,
     limitations: z.array(z.string()),
     residual_unknowns: z.array(z.object({
         scope: z.enum([
@@ -214,21 +256,17 @@ 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(),
     })),
     process_samples: partialObservationFieldSchema(processCaptureShapeSchema.shape.process_samples),
     filesystem_snapshots: z.strictObject({
-        before: partialObservationFieldSchema(z.strictObject({
-            files: z.array(fileStateSchema),
-            truncated: z.boolean(),
-        })),
-        after: partialObservationFieldSchema(z.strictObject({
-            files: z.array(fileStateSchema),
-            truncated: z.boolean(),
-        })),
+        before: partialObservationFieldSchema(processFilesystemSnapshotSchema),
+        after: partialObservationFieldSchema(processFilesystemSnapshotSchema),
     }),
     event_journal: partialObservationFieldSchema(processCaptureShapeSchema.shape.event_journal),
     manifest: partialObservationFieldSchema(processCaptureShapeSchema.shape.manifest),
@@ -264,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

@@ -18,7 +18,12 @@ export const filesystemCoverageSchema = 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"]),
+        reason: z.enum([
+            "file_bytes_budget",
+            "file_changed_or_short_read",
+            "file_unavailable",
+        ]),
+        system_code: z.string().nullable(),
     })),
 });
 /** Actual budget accounting; rendered bytes count state and visible lines, not JSON. */
@@ -39,17 +44,15 @@ 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;
-/** Derive the legacy aggregate flag from independent producer observations. */
+/** Derive the aggregate truncation flag from independent producer observations. */
 export const hasCaptureTruncation = (details) => 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. */
+/** Whether producer accounting reports a gap in the selected observation source. */
 export const processSourceTruncated = (capture, source) => {
     const details = capture.truncation_details;
-    if (details === undefined)
-        return capture.truncated;
     switch (source) {
         case "terminal_raw":
             return omitted(details.raw_terminal);