rea-agents 5.0.0 → 6.1.0

package/dist/domain/native/recordedCrash.js

@@ -0,0 +1,266 @@
+import { z } from "zod";
+import { recordedNoteCoverageIssues } from "./recordedCrashNoteCoverage.js";
+const hex = z.string().regex(/^0x(?:0|[1-9a-f][0-9a-f]{0,15})$/);
+const index = z.number().int().nonnegative();
+const signed32 = z.number().int().min(-2147483648).max(2147483647);
+const base64 = z
+    .string()
+    .regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/][AQgw]==|[A-Za-z0-9+/]{2}[AEIMQUYcgkosw048]=)?$/);
+const range = z.strictObject({ offset: hex, bytes: hex });
+const diagnostics = z.strictObject({
+    stdout: z.string(),
+    stderr: z.string(),
+    truncated: z.boolean(),
+});
+// Exact b"CORE\0"; a lossy display label cannot establish the Linux note ABI.
+const LINUX_CORE_OWNER_BASE64 = "Q09SRQA=";
+/** Complete register identities in the supported Linux amd64 PRSTATUS ABI order. */
+export const RECORDED_LINUX_AMD64_REGISTERS = [
+    "r15",
+    "r14",
+    "r13",
+    "r12",
+    "rbp",
+    "rbx",
+    "r11",
+    "r10",
+    "r9",
+    "r8",
+    "rax",
+    "rcx",
+    "rdx",
+    "rsi",
+    "rdi",
+    "orig_rax",
+    "rip",
+    "cs",
+    "eflags",
+    "rsp",
+    "ss",
+    "fs_base",
+    "gs_base",
+    "ds",
+    "es",
+    "fs",
+    "gs",
+];
+const supportedRegisters = new Set(RECORDED_LINUX_AMD64_REGISTERS);
+/** Select an explicit recording and optionally request debugger-derived mapping context. */
+export const inspectRecordedCrashInputSchema = z.strictObject({
+    path: z
+        .string()
+        .min(1)
+        .describe("Absolute filesystem path to a supplied Linux ELF core"),
+    include_debugger_context: z
+        .boolean()
+        .default(false)
+        .describe("Add core-only mapping candidates through caller-supplied GDB/pwndbg"),
+});
+/** Debugger map candidates preserve reported flags; zero does not establish absent permissions. */
+export const recordedCrashDebuggerSchema = z.discriminatedUnion("status", [
+    z.strictObject({ status: z.literal("not-requested") }),
+    z.strictObject({
+        status: z.literal("available"),
+        gdb_version: z.string().min(1),
+        pwndbg_version: z.string().min(1),
+        connection: z.literal("core"),
+        executable: z.null(),
+        historical_pid: signed32,
+        reported_limits: z.strictObject({
+            address_space_bytes: index,
+            cpu_seconds: index,
+            file_size_bytes: index,
+        }),
+        maps: z.array(z.strictObject({
+            start: hex,
+            end: hex,
+            offset: hex,
+            reported_flags: index,
+            permissions: z
+                .strictObject({
+                read: z.boolean(),
+                write: z.boolean(),
+                execute: z.boolean(),
+            })
+                .nullable(),
+            pathname_display: z.string(),
+            current_file_identity: z.literal("unknown"),
+        })),
+        confidence: z.literal("derived"),
+        completeness: z.literal("unknown"),
+        diagnostics,
+    }),
+]);
+/** Portable recorded observations; registers and source coordinates remain lossless. */
+const recordedCrashObjectSchema = z.strictObject({
+    artifact: z.strictObject({
+        path: z.string().min(1),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/),
+        bytes: index,
+    }),
+    format: z.literal("elf-core"),
+    architecture: z.literal("x86_64-little-endian"),
+    target_execution: z.literal("not-performed"),
+    live_process_identity: z.literal("unknown"),
+    segments: z.array(z.strictObject({
+        index,
+        type: z.union([z.string(), index]),
+        header_location: range,
+        offset: hex,
+        file_size: hex,
+        memory_size: hex,
+        virtual_address: hex,
+        physical_address: hex,
+        alignment: hex,
+        flags: hex,
+        file_backing: z.enum(["file", "none"]),
+    })),
+    notes: z.array(z.strictObject({
+        index,
+        segment_index: index,
+        type: z.union([z.string(), index]),
+        location: range,
+        owner_location: range,
+        owner_bytes_base64: base64,
+        owner_display: z.string().nullable(),
+        descriptor_location: range,
+        descriptor_bytes_base64: base64,
+    })),
+    note_padding: z.array(z.strictObject({
+        segment_index: index,
+        location: range,
+        bytes_base64: base64,
+    })),
+    threads: z.array(z.strictObject({
+        note_index: index,
+        historical_pid: signed32,
+        recorded_current_signal: z.number().int().min(-32768).max(32767),
+        registers: z.array(z.strictObject({
+            name: z.string().min(1),
+            value: hex,
+            location: range,
+        })),
+    })),
+    signals: z.array(z.strictObject({
+        note_index: index,
+        number: signed32,
+        code: signed32,
+        errno: signed32,
+        fault_address: hex.nullable(),
+        fault_address_meaning: z.enum(["recorded-sigsegv-address", "unknown"]),
+        thread_association: z.literal("unknown"),
+    })),
+    debugger: recordedCrashDebuggerSchema,
+    note_interpretation_completeness: z.literal("unknown"),
+    decoder_diagnostics: diagnostics,
+    diagnostics,
+    limitations: z.array(z.string()),
+});
+/** Provider payload excludes identity and diagnostics bound by the owned snapshot boundary. */
+export const recordedCrashPayloadSchema = recordedCrashObjectSchema.omit({
+    artifact: true,
+    diagnostics: true,
+    debugger: true,
+    decoder_diagnostics: true,
+});
+/** Validate the next consumer's file ranges, note links and register representations. */
+export const recordedCrashSchema = recordedCrashObjectSchema.superRefine((value, context) => {
+    const fail = (message) => context.addIssue({ code: "custom", message });
+    const within = (item, start = 0n, end = BigInt(value.artifact.bytes)) => {
+        const offset = BigInt(item.offset);
+        const bytes = BigInt(item.bytes);
+        return offset >= start && offset <= end && bytes <= end - offset;
+    };
+    for (const issue of recordedNoteCoverageIssues(value.segments, value.notes, value.note_padding))
+        fail(issue);
+    for (const [position, segment] of value.segments.entries()) {
+        if (position !== segment.index || !within(segment.header_location))
+            fail("Invalid original segment identity or header range.");
+        if (segment.file_backing === "file" &&
+            !within({ offset: segment.offset, bytes: segment.file_size }))
+            fail("Recorded segment exceeds artifact bytes.");
+        if (segment.type === "PT_LOAD" &&
+            BigInt(segment.file_size) > BigInt(segment.memory_size))
+            fail("Recorded PT_LOAD file size exceeds memory size.");
+    }
+    for (const [position, note] of value.notes.entries()) {
+        const segment = value.segments[note.segment_index];
+        if (position !== note.index || segment?.type !== "PT_NOTE") {
+            fail("Invalid original note identity or segment reference.");
+            continue;
+        }
+        const decodedLength = (raw) => BigInt((raw.length / 4) * 3 -
+            (raw.endsWith("==") ? 2 : raw.endsWith("=") ? 1 : 0));
+        if (decodedLength(note.owner_bytes_base64) !==
+            BigInt(note.owner_location.bytes) ||
+            decodedLength(note.descriptor_bytes_base64) !==
+                BigInt(note.descriptor_location.bytes))
+            fail("Raw note lengths differ from their source ranges.");
+        const start = BigInt(segment.offset);
+        const end = start + BigInt(segment.file_size);
+        if (!within(note.location, start, end) ||
+            !within(note.owner_location, BigInt(note.location.offset), BigInt(note.location.offset) + BigInt(note.location.bytes)) ||
+            !within(note.descriptor_location, BigInt(note.location.offset), BigInt(note.location.offset) + BigInt(note.location.bytes)))
+            fail("Note source ranges exceed their recorded segment.");
+    }
+    for (const padding of value.note_padding) {
+        const segment = value.segments[padding.segment_index];
+        if (segment?.type !== "PT_NOTE" ||
+            !within(padding.location, BigInt(segment.offset), BigInt(segment.offset) + BigInt(segment.file_size)))
+            fail("Invalid recorded note padding range.");
+    }
+    for (const [kind, rows] of [
+        ["NT_PRSTATUS", value.threads],
+        ["NT_SIGINFO", value.signals],
+    ]) {
+        const matchingNotes = value.notes.filter((note) => note.type === kind &&
+            note.owner_bytes_base64 === LINUX_CORE_OWNER_BASE64);
+        if (rows.length !== matchingNotes.length ||
+            new Set(rows.map(({ note_index }) => note_index)).size !== rows.length)
+            fail("Each supported raw note requires exactly one corresponding interpretation.");
+    }
+    for (const thread of value.threads) {
+        const note = value.notes[thread.note_index];
+        if (note?.type !== "NT_PRSTATUS" ||
+            note.owner_display !== "CORE" ||
+            note.owner_bytes_base64 !== LINUX_CORE_OWNER_BASE64) {
+            fail("Thread references a different note kind.");
+            continue;
+        }
+        if (thread.registers.length !== RECORDED_LINUX_AMD64_REGISTERS.length ||
+            !thread.registers.every(({ name }) => supportedRegisters.has(name)) ||
+            new Set(thread.registers.map(({ name }) => name)).size !==
+                thread.registers.length)
+            fail("Each recorded thread requires every supported register exactly once.");
+        for (const register of thread.registers)
+            if (BigInt(register.location.bytes) !== 8n ||
+                !within(register.location, BigInt(note.descriptor_location.offset), BigInt(note.descriptor_location.offset) +
+                    BigInt(note.descriptor_location.bytes)))
+                fail("Register source exceeds its descriptor.");
+    }
+    for (const signal of value.signals) {
+        if (value.notes[signal.note_index]?.type !== "NT_SIGINFO" ||
+            value.notes[signal.note_index]?.owner_display !== "CORE" ||
+            value.notes[signal.note_index]?.owner_bytes_base64 !==
+                LINUX_CORE_OWNER_BASE64)
+            fail("Signal references a different note kind.");
+        const known = signal.number === 11 && (signal.code === 1 || signal.code === 2);
+        if (known !== (signal.fault_address !== null) ||
+            (signal.fault_address !== null) !==
+                (signal.fault_address_meaning === "recorded-sigsegv-address"))
+            fail("Signal union meaning does not match recorded SIGSEGV code.");
+    }
+    if (value.debugger.status === "available")
+        for (const map of value.debugger.maps) {
+            if (BigInt(map.end) < BigInt(map.start))
+                fail("Debugger mapping end precedes its start.");
+            if (map.permissions !== null &&
+                (map.permissions.read !== Boolean(map.reported_flags & 4) ||
+                    map.permissions.write !== Boolean(map.reported_flags & 2) ||
+                    map.permissions.execute !== Boolean(map.reported_flags & 1)))
+                fail("Mapping permissions differ from reported flags.");
+            if ((map.reported_flags === 0 || map.reported_flags > 7) !==
+                (map.permissions === null))
+                fail("Unreported or unfamiliar map flags require unknown permissions.");
+        }
+});

package/dist/domain/native/recordedCrashNoteCoverage.js

@@ -0,0 +1,73 @@
+const align = (size) => ((size + 3n) / 4n) * 4n;
+const layoutMatches = (note) => {
+    const start = BigInt(note.location.offset);
+    const owner = BigInt(note.owner_location.bytes);
+    const descriptor = BigInt(note.descriptor_location.bytes);
+    return (BigInt(note.owner_location.offset) === start + 12n &&
+        BigInt(note.descriptor_location.offset) === start + 12n + align(owner) &&
+        BigInt(note.location.bytes) === 12n + align(owner) + align(descriptor));
+};
+const paddingMatches = (item, segment) => {
+    const bytes = BigInt(item.location.bytes);
+    const decodedLength = (item.bytes_base64.length / 4) * 3 -
+        (item.bytes_base64.endsWith("==")
+            ? 2
+            : item.bytes_base64.endsWith("=")
+                ? 1
+                : 0);
+    return (bytes > 0n &&
+        bytes < 12n &&
+        BigInt(decodedLength) === bytes &&
+        /^A*={0,2}$/.test(item.bytes_base64) &&
+        segment !== undefined &&
+        BigInt(item.location.offset) + bytes ===
+            BigInt(segment.offset) + BigInt(segment.file_size));
+};
+/** Require exact aligned note layouts and one complete, nonoverlapping physical coverage. */
+export function recordedNoteCoverageIssues(segments, notes, padding) {
+    const issues = [];
+    const bySegment = new Map();
+    const all = [];
+    const add = (segment, range) => {
+        const ranges = bySegment.get(segment) ?? [];
+        ranges.push(range);
+        bySegment.set(segment, ranges);
+        all.push(range);
+    };
+    for (const note of notes) {
+        if (!layoutMatches(note))
+            issues.push("Recorded note layout differs from its aligned header/owner/descriptor ranges.");
+        add(note.segment_index, note.location);
+    }
+    for (const item of padding) {
+        if (!paddingMatches(item, segments[item.segment_index]))
+            issues.push("Recorded note padding must be a short zero-filled segment tail.");
+        add(item.segment_index, item.location);
+    }
+    const compare = (left, right) => BigInt(left.offset) < BigInt(right.offset)
+        ? -1
+        : BigInt(left.offset) > BigInt(right.offset)
+            ? 1
+            : 0;
+    let end = 0n;
+    for (const range of all.sort(compare)) {
+        const start = BigInt(range.offset);
+        if (start < end)
+            issues.push("Physical recorded note/padding ranges overlap or repeat.");
+        if (start + BigInt(range.bytes) > end)
+            end = start + BigInt(range.bytes);
+    }
+    for (const segment of segments) {
+        if (segment.type !== "PT_NOTE")
+            continue;
+        let cursor = BigInt(segment.offset);
+        for (const range of (bySegment.get(segment.index) ?? []).sort(compare)) {
+            if (BigInt(range.offset) !== cursor)
+                issues.push("Recorded note/padding ranges leave a gap or overlap in their segment.");
+            cursor = BigInt(range.offset) + BigInt(range.bytes);
+        }
+        if (cursor !== BigInt(segment.offset) + BigInt(segment.file_size))
+            issues.push("Recorded note/padding ranges do not completely cover their segment.");
+    }
+    return issues;
+}

package/dist/domain/{processCapture.js → process/processCapture.js}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { jsonValueSchema } from "./jsonValue.js";
+import { jsonValueSchema } from "../jsonValue.js";
 import { normalizationSchema } from "./processScenario.js";
 import { collectProcessCaptureIssues } from "./processCaptureValidation.js";
 export * from "./processScenario.js";
@@ -61,6 +61,19 @@ const fileEffectSchema = z.discriminatedUnion("status", [
     }),
 ]);
 /** Exact serialized shape of a process capture. */
+const processSettlementSchema = z.discriminatedUnion("state", [
+    z.object({
+        state: z.literal("quiesced"),
+        elapsed_ms: z.number().int().nonnegative(),
+        cleanup_outcome: z.enum(["not_required", "failed"]),
+    }),
+    z.object({
+        state: z.enum(["alive_at_deadline", "unverifiable"]),
+        elapsed_ms: z.number().int().nonnegative(),
+        cleanup_outcome: z.enum(["cleaned", "failed"]),
+    }),
+]);
+const unverifiedCleanupProcessesSchema = z.array(z.strictObject({ pid: z.number().int().positive(), reason: z.string() }));
 const processCaptureShapeSchema = z.strictObject({
     manifest: z.strictObject({
         rea_version: z.string().min(1),
@@ -74,7 +87,22 @@ const processCaptureShapeSchema = z.strictObject({
         comparison_contract: z.record(z.string(), jsonValueSchema),
         full_scenario_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
         comparison_contract_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
-        executable_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        selected_executable_sha256: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/u)
+            .nullable(),
+        executable_sha256: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/u)
+            .nullable(),
+        legacy_executable_sha256: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/u)
+            .optional(),
+        executable_identity: z.strictObject({
+            state: z.enum(["path_metadata_unchanged", "unknown"]),
+            reason: z.string().nullable(),
+        }),
         normalization_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
     }),
     normalization: normalizationSchema,
@@ -162,11 +190,124 @@ const processCaptureShapeSchema = z.strictObject({
     cleanup: z.object({
         owned_process_group: z.literal("verified"),
         temporary_root: z.literal("removed"),
+        unverified_processes: unverifiedCleanupProcessesSchema.optional(),
     }),
 });
+const processCleanupResourceSchema = z.strictObject({
+    state: z.enum(["cleaned", "failed", "unverified", "not_required"]),
+    reason: z.string().nullable(),
+    unverified_processes: unverifiedCleanupProcessesSchema.optional(),
+});
+const partialObservationFieldSchema = (value) => z.discriminatedUnion("state", [
+    z.strictObject({ state: z.literal("available"), value }),
+    z.strictObject({ state: z.literal("unavailable"), reason: z.string() }),
+]);
+const incompleteProcessCaptureObservationsSchema = z.strictObject({
+    target_pid: partialObservationFieldSchema(z.number().int().positive()),
+    frames: partialObservationFieldSchema(processCaptureShapeSchema.shape.frames),
+    rendered_frames: partialObservationFieldSchema(processCaptureShapeSchema.shape.rendered_frames),
+    interaction_events: partialObservationFieldSchema(processCaptureShapeSchema.shape.interaction_events),
+    exit: partialObservationFieldSchema(z.strictObject({
+        code: z.number().int().nullable(),
+        signal: z.number().int().nullable(),
+        reason: z.enum(["exited", "timeout", "idle_timeout", "cancelled"]),
+    })),
+    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(),
+        })),
+    }),
+    event_journal: partialObservationFieldSchema(processCaptureShapeSchema.shape.event_journal),
+    manifest: partialObservationFieldSchema(processCaptureShapeSchema.shape.manifest),
+});
+const partialCleanupReportSchema = z.strictObject({
+    owned_process_group: processCleanupResourceSchema,
+    terminal_renderer: processCleanupResourceSchema,
+    temporary_root: processCleanupResourceSchema,
+});
+const partialObservationMetadataSchema = z.strictObject({
+    cleanup: partialCleanupReportSchema,
+    execution_failure: z.string().nullable(),
+});
+const completedCaptureObservationSchema = z.strictObject({
+    capture: processCaptureShapeSchema
+        .omit({ cleanup: true })
+        .extend({ settlement: processSettlementSchema }),
+});
+const incompleteCaptureObservationSchema = z.strictObject({
+    observations: incompleteProcessCaptureObservationsSchema,
+});
+/** Validated, non-comparable process observations attached to execution or cleanup errors. */
+export const partialProcessCaptureObservationSchema = z
+    .union([
+    completedCaptureObservationSchema.extend(partialObservationMetadataSchema.shape),
+    incompleteCaptureObservationSchema.extend(partialObservationMetadataSchema.shape),
+])
+    .superRefine((partial, context) => {
+    const cleanupIncomplete = Object.values(partial.cleanup).some(({ state }) => state === "failed" || state === "unverified");
+    if (!cleanupIncomplete && partial.execution_failure === null)
+        context.addIssue({
+            code: "custom",
+            path: ["execution_failure"],
+            message: "partial observations require incomplete cleanup or an execution failure",
+        });
+    if ("observations" in partial) {
+        const { observations } = partial;
+        if (![
+            observations.frames,
+            observations.interaction_events,
+            observations.process_samples,
+            observations.filesystem_snapshots.before,
+            observations.event_journal,
+        ].some(({ state }) => state === "available"))
+            context.addIssue({
+                code: "custom",
+                path: ["observations"],
+                message: "incomplete observations contain no collected evidence",
+            });
+        return;
+    }
+    const { capture } = partial;
+    const settlement = capture.settlement.state === "quiesced"
+        ? {
+            ...capture.settlement,
+            cleanup_outcome: "not_required",
+        }
+        : { ...capture.settlement, cleanup_outcome: "cleaned" };
+    const validationCapture = {
+        ...capture,
+        settlement,
+        cleanup: {
+            owned_process_group: "verified",
+            temporary_root: "removed",
+        },
+    };
+    for (const issue of collectProcessCaptureIssues(validationCapture))
+        context.addIssue({
+            code: "custom",
+            path: ["capture", ...issue.path.split(".")],
+            message: issue.message,
+        });
+});
 /** Exact serialized shape plus all process-capture semantic invariants. */
 export const processCaptureSchema = processCaptureShapeSchema
     .superRefine((capture, context) => {
+    if (capture.settlement.cleanup_outcome === "failed")
+        context.addIssue({
+            code: "custom",
+            path: ["settlement", "cleanup_outcome"],
+            message: "verified captures cannot contain failed cleanup",
+        });
     for (const issue of collectProcessCaptureIssues(capture))
         context.addIssue({
             code: "custom",

package/dist/domain/{processCaptureExample.js → process/processCaptureExample.js}

@@ -22,7 +22,12 @@ export const EMPTY_PROCESS_CAPTURE_EXAMPLE = {
         comparison_contract: comparisonContract,
         full_scenario_sha256: digestProcessCommitment(scenario),
         comparison_contract_sha256: digestProcessCommitment(comparisonContract),
+        selected_executable_sha256: "0".repeat(64),
         executable_sha256: "0".repeat(64),
+        executable_identity: {
+            state: "path_metadata_unchanged",
+            reason: null,
+        },
         normalization_sha256: digestProcessCommitment(normalization),
     },
     normalization,

package/dist/domain/process/processCaptureParsing.js

@@ -0,0 +1,54 @@
+import { processCaptureSchema, } from "./processCapture.js";
+import { z } from "zod";
+const verifiedCaptures = new WeakSet();
+const isVerifiedCapture = (capture) => verifiedCaptures.has(capture);
+const attachProof = (capture) => {
+    verifiedCaptures.add(capture);
+    if (isVerifiedCapture(capture))
+        return capture;
+    throw new TypeError("Process Capture proof ownership failed");
+};
+const recordSchema = z.record(z.string(), z.unknown());
+const LEGACY_EXECUTABLE_IDENTITY_REASON = "Legacy v3 capture did not distinguish selected and launch executable digests";
+const migrateLegacyV3Capture = (input) => {
+    const capture = recordSchema.safeParse(input);
+    if (!capture.success)
+        return input;
+    const manifest = recordSchema.safeParse(capture.data.manifest);
+    if (!manifest.success)
+        return input;
+    if (manifest.data.provider_version !== "3" ||
+        "selected_executable_sha256" in manifest.data ||
+        "executable_identity" in manifest.data ||
+        "legacy_executable_sha256" in manifest.data)
+        return input;
+    const { executable_sha256 } = manifest.data;
+    if (typeof executable_sha256 !== "string" ||
+        !/^[a-f0-9]{64}$/u.test(executable_sha256))
+        return input;
+    return {
+        ...capture.data,
+        manifest: {
+            ...manifest.data,
+            selected_executable_sha256: null,
+            executable_sha256: null,
+            executable_identity: {
+                state: "unknown",
+                reason: LEGACY_EXECUTABLE_IDENTITY_REASON,
+            },
+            legacy_executable_sha256: executable_sha256,
+        },
+    };
+};
+/** Parse unknown input and reject invalid commitments or semantics. */
+export const parseProcessCapture = (input) => {
+    const parsed = processCaptureSchema.safeParse(migrateLegacyV3Capture(input));
+    if (parsed.success)
+        return attachProof(parsed.data);
+    const issues = parsed.error.issues.flatMap((issue) => issue.code === "custom"
+        ? [{ path: issue.path.join("."), message: issue.message }]
+        : []);
+    if (issues.length > 0)
+        throw new TypeError(`Invalid process capture: ${issues.map(({ path, message }) => `${path}: ${message}`).join("; ")}`);
+    throw parsed.error;
+};

package/dist/domain/{processCaptureValidation.js → process/processCaptureValidation.js}

@@ -5,8 +5,24 @@ const orderedTimestamps = (values) => values.every((value, index) => {
 });
 const validateCommitments = (capture, require) => {
     const { manifest } = capture;
-    require(manifest.scenario.executable_sha256 ===
-        manifest.executable_sha256, "manifest.executable_sha256", "executable commitment does not match the scenario projection");
+    if (manifest.legacy_executable_sha256 !== undefined) {
+        require(manifest.selected_executable_sha256 === null &&
+            manifest.executable_sha256 === null &&
+            manifest.executable_identity.state === "unknown" &&
+            manifest.executable_identity.reason !== null &&
+            manifest.scenario.executable_sha256 ===
+                manifest.legacy_executable_sha256, "manifest.legacy_executable_sha256", "legacy executable digest must remain distinct from unknown selected and launch digests");
+    }
+    else {
+        require(manifest.scenario.executable_sha256 ===
+            manifest.selected_executable_sha256, "manifest.selected_executable_sha256", "selected executable commitment does not match the scenario projection");
+    }
+    require(manifest.executable_identity.state === "path_metadata_unchanged"
+        ? manifest.executable_sha256 === manifest.selected_executable_sha256 &&
+            manifest.executable_identity.reason === null
+        : manifest.executable_sha256 === null &&
+            manifest.executable_identity.reason !==
+                null, "manifest.executable_identity", "launch identity and executable digest do not agree");
     for (const [field, value] of [
         ["full_scenario_sha256", manifest.scenario],
         ["comparison_contract_sha256", manifest.comparison_contract],

package/dist/domain/{processComparison.js → process/processComparison.js}

@@ -1,8 +1,10 @@
 import canonicalize from "canonicalize";
 import { z } from "zod";
-import { jsonValueSchema } from "./jsonValue.js";
+import { AnalysisInputError } from "../analysisErrorCore.js";
+import { jsonValueSchema } from "../jsonValue.js";
 import { compareProcessTraces, processTraceOutcomesDiffer, processTraceComparisonResultSchema, } from "./processTraceComparison.js";
 import { dimensionsForTraceSources, traceCoversObservedDimension, } from "./processTraceDimensionProjection.js";
+const OPERATION = "compare_process_captures";
 /** Comparison classification that never equates incomplete evidence. */
 export const comparisonStatusSchema = z.enum([
     "unchanged",
@@ -152,15 +154,47 @@ const chooseFirstDivergence = (candidates) => {
 };
 const assertComparable = (left, right, options) => {
     if (left.manifest.comparison_contract_sha256 !==
-        right.manifest.comparison_contract_sha256)
-        throw new TypeError("Process captures have incompatible comparison contracts");
+        right.manifest.comparison_contract_sha256) {
+        const fields = differingContractFields(left.manifest.comparison_contract, right.manifest.comparison_contract);
+        throw new AnalysisInputError(OPERATION, undefined, [
+            {
+                path: ["right"],
+                reason: "invalid_value",
+                message: `Process captures have incompatible comparison contracts${fields.length === 0 ? "" : `; these scenario fields differ: ${fields.join(", ")}`}. Capture both scenarios with the same values for these fields, then compare them.`,
+                expected: fields,
+            },
+        ]);
+    }
     if (options.maxCaptureAgeMs === undefined)
         return;
     const maxCaptureAgeMs = options.maxCaptureAgeMs;
     const now = (options.now ?? Date.now)();
-    if ([left, right].some(({ manifest }) => now - Date.parse(manifest.completed_at) > maxCaptureAgeMs))
-        throw new TypeError("Process capture exceeds max_capture_age_ms");
+    const stale = [
+        ["left", left],
+        ["right", right],
+    ].flatMap(([side, { manifest }]) => {
+        const age = now - Date.parse(manifest.completed_at);
+        return age > maxCaptureAgeMs
+            ? [
+                `${side} completed at ${manifest.completed_at} (${String(age)} ms ago)`,
+            ]
+            : [];
+    });
+    if (stale.length > 0)
+        throw new AnalysisInputError(OPERATION, undefined, [
+            {
+                path: ["max_capture_age_ms"],
+                reason: "out_of_range",
+                message: `Process capture exceeds max_capture_age_ms ${String(maxCaptureAgeMs)}: ${stale.join("; ")}. Recapture the stale scenario or raise max_capture_age_ms.`,
+            },
+        ]);
 };
+/** Name top-level contract fields whose canonical values differ. */
+const differingContractFields = (left, right) => [...new Set([...Object.keys(left), ...Object.keys(right)])]
+    .filter((field) => !Object.hasOwn(left, field) ||
+    !Object.hasOwn(right, field) ||
+    canonicalize(left[field]) !== canonicalize(right[field]))
+    .sort();
 const truncatedComparison = () => ({
     status: "truncated",
     terminal: "truncated",