diff --git a/docs/api/classes/application_ProcessCheckpoints.ProcessCheckpoints.html b/docs/api/classes/application_ProcessCheckpoints.ProcessCheckpoints.html index 01b732a78..cb38fb733 100644 --- a/docs/api/classes/application_ProcessCheckpoints.ProcessCheckpoints.html +++ b/docs/api/classes/application_ProcessCheckpoints.ProcessCheckpoints.html @@ -80,7 +80,7 @@

Returns Promise<void>

+
  • Defined in src/application/ProcessCheckpoints.ts:133

    • Returns Promise<readonly FilesystemCheckpoint[]>

    +
  • Defined in src/application/ProcessCheckpoints.ts:116

    • Class TerminalRenderer

    -

    Owns one headless terminal and serializes writes into deterministic frames.

    +

    Reconstructs bounded terminal states while raw PTY chunks remain authoritative.

    +

    Rendered frames answer what an operator saw after control-sequence handling; +raw frames preserve byte/chunk differences that can render identically. +Comparisons retain both because neither representation subsumes the other.

    +
  • Defined in src/application/TerminalRenderer.ts:30
    • @@ -48,7 +51,7 @@
  • options: TerminalRendererOptions

    • Returns TerminalRenderer

    +
  • Defined in src/application/TerminalRenderer.ts:38
    • @@ -62,7 +65,7 @@

    Returns Promise<void>

    +
  • Defined in src/application/TerminalRenderer.ts:81
    • +
  • Defined in src/application/TerminalRenderer.ts:70

    • Returns void

    +
  • Defined in src/application/TerminalRenderer.ts:62
    • +
  • Defined in src/application/TerminalRenderer.ts:76

    • Returns void

    +
  • Defined in src/application/TerminalRenderer.ts:49
    • diff --git a/docs/api/functions/application_CommandShimReplay.startCommandShimReplay.html b/docs/api/functions/application_CommandShimReplay.startCommandShimReplay.html index a25bd23ac..586a177c3 100644 --- a/docs/api/functions/application_CommandShimReplay.startCommandShimReplay.html +++ b/docs/api/functions/application_CommandShimReplay.startCommandShimReplay.html @@ -17,6 +17,9 @@

    Start bounded executable replay wrappers and their private invocation ledger.

    +

    Exact argument matching is deliberate: a fallback to the host executable +would make an unmatched dependency call look authoritative. Unmatched and +exhausted routes therefore fail visibly and remain part of the capture.

    Parameters

    @@ -26,7 +29,7 @@
  • started: number

    • Returns Promise<CommandShimReplay>

    +
  • Defined in src/application/CommandShimReplay.ts:51
    • diff --git a/docs/api/functions/application_ProcessHarness.captureProcessScenario.html b/docs/api/functions/application_ProcessHarness.captureProcessScenario.html index 5a1cde037..13d22f802 100644 --- a/docs/api/functions/application_ProcessHarness.captureProcessScenario.html +++ b/docs/api/functions/application_ProcessHarness.captureProcessScenario.html @@ -26,7 +26,7 @@
  • Optionalsignal: AbortSignal

    • Returns Promise<Result<ProcessCapture, ProcessCaptureError>>

    +
  • Defined in src/application/ProcessHarness.ts:675
    • diff --git a/docs/api/functions/application_ProcessOwnership.cleanupOwnedProcessGroup.html b/docs/api/functions/application_ProcessOwnership.cleanupOwnedProcessGroup.html index 8469e41cb..b233fdd5d 100644 --- a/docs/api/functions/application_ProcessOwnership.cleanupOwnedProcessGroup.html +++ b/docs/api/functions/application_ProcessOwnership.cleanupOwnedProcessGroup.html @@ -17,6 +17,9 @@

    Verify run-token ownership before signaling a POSIX process group.

    +

    Process IDs and group IDs can be reused. REA therefore re-reads every live +member's environment immediately before signaling and fails closed if any +member cannot be inspected or lacks the per-capture run token.

    Parameters

    @@ -25,7 +28,7 @@
  • host: ProcessOwnershipHost = systemHost

    • Returns Promise<ProcessCleanupResult>

    +
  • Defined in src/application/ProcessOwnership.ts:91
    • diff --git a/docs/api/functions/domain_processCapture.authorizeProcessScenario.html b/docs/api/functions/domain_processCapture.authorizeProcessScenario.html index c6aad6d6a..d48e353cb 100644 --- a/docs/api/functions/domain_processCapture.authorizeProcessScenario.html +++ b/docs/api/functions/domain_processCapture.authorizeProcessScenario.html @@ -25,7 +25,7 @@
  • policy: ProcessExecutionPolicy

    • Returns ProcessPolicyDecision

    +
  • Defined in src/domain/processCapture.ts:347
    • diff --git a/docs/api/functions/domain_processCapture.parseProcessScenario.html b/docs/api/functions/domain_processCapture.parseProcessScenario.html index b243aa460..eea1736cb 100644 --- a/docs/api/functions/domain_processCapture.parseProcessScenario.html +++ b/docs/api/functions/domain_processCapture.parseProcessScenario.html @@ -24,7 +24,7 @@
  • input: unknown

    • Returns {
        approved: true;
        arguments: string[];
        checkpoints: {
            name: string;
            trigger:
                | { at_ms: number; type: "time" }
                | { occurrence: number; type: "terminal_literal"; value: string }
                | { type: "root_exit" }
                | { type: "settled" };
        }[];
        command_shims: {
            name: string;
            routes: {
                arguments: string[];
                max_calls: number;
                outputs: { at_ms: number; data: string; stream: "stdout"
                | "stderr" }[];
                termination:
                    | { code: number; type: "exit" }
                    | { signal: "SIGINT" | "SIGTERM" | "SIGKILL"; type: "signal" };
            }[];
        }[];
        environment: Record<string, string>;
        events: (
            | { at_ms: number; data: string; sensitive: boolean; type: "input" }
            | { at_ms: number; columns: number; rows: number; type: "resize" }
            | {
                at_ms: number;
                signal: "SIGINT" | "SIGTERM" | "SIGKILL";
                type: "signal";
            }
        )[];
        executable: string;
        filesystem_roots: string[];
        idle_timeout_ms: number;
        inherit_environment: string[];
        limits: {
            connections: number;
            file_bytes: number;
            files: number;
            filesystem_depth: number;
            frames: number;
            output_bytes: number;
            processes: number;
            protocol_body_bytes: number;
            protocol_events: number;
        };
        network_access: "host";
        normalization: {
            paths: boolean;
            patterns: { pattern: string; replacement: string }[];
            pids: boolean;
            ports: boolean;
            time_bucket_ms: number;
        };
        replay: {
            http: {
                body: string;
                delay_ms: number;
                disconnect: boolean;
                max_calls: number;
                method: string;
                path: string;
                request_body?: string;
                request_headers: Record<string, string>;
                response_headers: Record<string, string>;
                status: number;
            }[];
            websocket_connections: {
                disconnect_after: boolean;
                messages: { data: string; delay_ms: number }[];
            }[];
            websocket_messages: string[];
        };
        secret_aliases: string[];
        settle_ms: number;
        terminal: { columns: number; rows: number; scrollback: number };
        timeout_ms: number;
        unknown_registry_approved?: true;
        working_directory: string;
    }

    +
  • Defined in src/domain/processCapture.ts:321
    • diff --git a/docs/api/functions/domain_processComparison.compareProcessCaptures.html b/docs/api/functions/domain_processComparison.compareProcessCaptures.html index ba8e8484f..2a27a868d 100644 --- a/docs/api/functions/domain_processComparison.compareProcessCaptures.html +++ b/docs/api/functions/domain_processComparison.compareProcessCaptures.html @@ -16,7 +16,9 @@
  • -

    Compare bounded captures without equating missing or incompatible evidence.

    +

    Compare two Process Capture v3 observations without treating absence as proof.

    +

    Observed differences outrank residual unknowns. A capture may therefore be +definitively changed in one dimension while completeness remains unknown.

    Parameters

    @@ -25,7 +27,7 @@
  • right: ProcessCapture

    • Returns {
        exit:
            | "unknown"
            | "unchanged"
            | "added"
            | "removed"
            | "changed"
            | "truncated";
        filesystem: | "unknown"
        | "unchanged"
        | "added"
        | "removed"
        | "changed"
        | "truncated";
        first_divergence: | { status: "none" }
        | { reason: string; status: "unknown" }
        | {
            dimension:
                | "protocol"
                | "terminal"
                | "interaction"
                | "exit"
                | "filesystem"
                | "process"
                | "shim";
            index: number;
            left: unknown;
            left_at_ms: number
            | null;
            right: unknown;
            right_at_ms: number | null;
            status: "found";
        };
        interaction: | "unknown"
        | "unchanged"
        | "added"
        | "removed"
        | "changed"
        | "truncated";
        limitations: string[];
        process: | "unknown"
        | "unchanged"
        | "added"
        | "removed"
        | "changed"
        | "truncated";
        protocol: | "unknown"
        | "unchanged"
        | "added"
        | "removed"
        | "changed"
        | "truncated";
        shim: | "unknown"
        | "unchanged"
        | "added"
        | "removed"
        | "changed"
        | "truncated";
        status: | "unknown"
        | "unchanged"
        | "added"
        | "removed"
        | "changed"
        | "truncated";
        terminal: | "unknown"
        | "unchanged"
        | "added"
        | "removed"
        | "changed"
        | "truncated";
    }

    +
  • Defined in src/domain/processComparison.ts:206
    • diff --git a/docs/api/interfaces/application_ProcessOwnership.OwnedProcessGroup.html b/docs/api/interfaces/application_ProcessOwnership.OwnedProcessGroup.html index 634a54053..b52585267 100644 --- a/docs/api/interfaces/application_ProcessOwnership.OwnedProcessGroup.html +++ b/docs/api/interfaces/application_ProcessOwnership.OwnedProcessGroup.html @@ -11,9 +11,12 @@
  • application/ProcessOwnership
  • OwnedProcessGroup

    • Interface OwnedProcessGroup

    +
    +

    Identity proof required before REA may signal a captured process group.

    +
    interface OwnedProcessGroup {
        expectedCommand?: string;
        expectedParentPid?: number;
        leaderPid: number;
        processGroupId: number;
        runId: string;
    }
    +
  • Defined in src/application/ProcessOwnership.ts:8
    • @@ -36,29 +39,29 @@

    Expected launcher identity, checked only while the leader exists.

    +
  • Defined in src/application/ProcessOwnership.ts:13
    • expectedParentPid?: number

    Expected launcher parent, checked only while the leader exists.

    +
  • Defined in src/application/ProcessOwnership.ts:15
    • leaderPid: number
    +
  • Defined in src/application/ProcessOwnership.ts:10
    • processGroupId: number
    +
  • Defined in src/application/ProcessOwnership.ts:11
    • runId: string
    +
  • Defined in src/application/ProcessOwnership.ts:9
    • diff --git a/docs/api/interfaces/application_ProcessOwnership.ProcessOwnershipHost.html b/docs/api/interfaces/application_ProcessOwnership.ProcessOwnershipHost.html index add74ca57..7aa62aec9 100644 --- a/docs/api/interfaces/application_ProcessOwnership.ProcessOwnershipHost.html +++ b/docs/api/interfaces/application_ProcessOwnership.ProcessOwnershipHost.html @@ -11,9 +11,12 @@
  • application/ProcessOwnership
  • ProcessOwnershipHost

    • Interface ProcessOwnershipHost

    +
    +

    Narrow operating-system seam used to inspect and signal process groups.

    +
    interface ProcessOwnershipHost {
        environment(pid: number): Promise<Readonly<Record<string, string>>>;
        listMembers(processGroupId: number): Promise<readonly ProcessGroupMember[]>;
        signalGroup(processGroupId: number, signal: Signals): void;
    }
    +
  • Defined in src/application/ProcessOwnership.ts:26
    • @@ -40,7 +43,7 @@
  • pid: number

    • Returns Promise<Readonly<Record<string, string>>>

    +
  • Defined in src/application/ProcessOwnership.ts:28

    • Returns Promise<readonly ProcessGroupMember[]>

    +
  • Defined in src/application/ProcessOwnership.ts:27

    • Returns void

    +
  • Defined in src/application/ProcessOwnership.ts:29
    • diff --git a/docs/api/interfaces/domain_processCapture.FileState.html b/docs/api/interfaces/domain_processCapture.FileState.html index 91fc964f9..b091236c2 100644 --- a/docs/api/interfaces/domain_processCapture.FileState.html +++ b/docs/api/interfaces/domain_processCapture.FileState.html @@ -16,7 +16,7 @@
    interface FileState {
        mode: number;
        path: string;
        sha256: string | null;
        size: number;
        symlink_target: string | null;
        type: "file" | "directory" | "symlink" | "other";
    }
    +
  • Defined in src/domain/processCapture.ts:432
    • @@ -38,32 +38,32 @@
    mode: number
    +
  • Defined in src/domain/processCapture.ts:435
    • path: string
    +
  • Defined in src/domain/processCapture.ts:433
    • sha256: string | null
    +
  • Defined in src/domain/processCapture.ts:437
    • size: number
    +
  • Defined in src/domain/processCapture.ts:436
    • symlink_target: string | null
    +
  • Defined in src/domain/processCapture.ts:438
    • type: "file" | "directory" | "symlink" | "other"
    +
  • Defined in src/domain/processCapture.ts:434
    • diff --git a/docs/api/interfaces/domain_processCapture.FilesystemCheckpoint.html b/docs/api/interfaces/domain_processCapture.FilesystemCheckpoint.html index d5015dcd3..ee5c0356d 100644 --- a/docs/api/interfaces/domain_processCapture.FilesystemCheckpoint.html +++ b/docs/api/interfaces/domain_processCapture.FilesystemCheckpoint.html @@ -12,11 +12,11 @@
  • FilesystemCheckpoint

    • Interface FilesystemCheckpoint

    -

    A named filesystem observation captured during a process lifecycle.

    +

    Named filesystem state whose effects are relative to the prior checkpoint.

    interface FilesystemCheckpoint {
        at_ms: number;
        effects: readonly FileEffect[];
        files: readonly FileState[];
        name: string;
        truncated: boolean;
    }
    +
  • Defined in src/domain/processCapture.ts:462
    • @@ -37,27 +37,27 @@
    at_ms: number
    +
  • Defined in src/domain/processCapture.ts:464
    • effects: readonly FileEffect[]
    +
  • Defined in src/domain/processCapture.ts:466
    • files: readonly FileState[]
    +
  • Defined in src/domain/processCapture.ts:465
    • name: string
    +
  • Defined in src/domain/processCapture.ts:463
    • truncated: boolean
    +
  • Defined in src/domain/processCapture.ts:467
    • diff --git a/docs/api/interfaces/domain_processCapture.InteractionEvent.html b/docs/api/interfaces/domain_processCapture.InteractionEvent.html index af592c824..a043e8ec8 100644 --- a/docs/api/interfaces/domain_processCapture.InteractionEvent.html +++ b/docs/api/interfaces/domain_processCapture.InteractionEvent.html @@ -12,11 +12,11 @@
  • InteractionEvent

    • Interface InteractionEvent

    -

    One attempted scripted interaction with the PTY.

    +

    Scheduled input, resize, or signal with its observed dispatch outcome.

    interface InteractionEvent {
        data: string;
        dispatched_at_ms: number;
        outcome: "failed" | "dispatched" | "target_exited";
        scheduled_at_ms: number;
        sequence: number;
        type: "signal" | "input" | "resize";
    }
    +
  • Defined in src/domain/processCapture.ts:422
    • @@ -38,32 +38,32 @@
    data: string
    +
  • Defined in src/domain/processCapture.ts:427
    • dispatched_at_ms: number
    +
  • Defined in src/domain/processCapture.ts:425
    • outcome: "failed" | "dispatched" | "target_exited"
    +
  • Defined in src/domain/processCapture.ts:428
    • scheduled_at_ms: number
    +
  • Defined in src/domain/processCapture.ts:424
    • sequence: number
    +
  • Defined in src/domain/processCapture.ts:423
    • type: "signal" | "input" | "resize"
    +
  • Defined in src/domain/processCapture.ts:426
    • diff --git a/docs/api/interfaces/domain_processCapture.ProcessCapture.html b/docs/api/interfaces/domain_processCapture.ProcessCapture.html index b86c1a4e5..b74802090 100644 --- a/docs/api/interfaces/domain_processCapture.ProcessCapture.html +++ b/docs/api/interfaces/domain_processCapture.ProcessCapture.html @@ -12,11 +12,13 @@
  • ProcessCapture

    • Interface ProcessCapture

    -

    A bounded process observation with explicit incompleteness metadata.

    +

    Process Capture v3 observation set.

    +

    truncated and residual_unknowns are semantic evidence: consumers must not +infer equivalence from matching bounded observations when either is present.

    interface ProcessCapture {
        cleanup: { owned_process_group: "verified"; temporary_root: "removed" };
        exit: {
            code: number | null;
            reason: "exited" | "timeout" | "idle_timeout";
            signal: number | null;
        };
        files_after: readonly FileState[];
        files_before: readonly FileState[];
        filesystem_checkpoints: readonly FilesystemCheckpoint[];
        filesystem_effects: readonly FileEffect[];
        frames: readonly TerminalFrame[];
        interaction_events: readonly InteractionEvent[];
        limitations: readonly string[];
        normalization: {
            paths: boolean;
            patterns: { pattern: string; replacement: string }[];
            pids: boolean;
            ports: boolean;
            time_bucket_ms: number;
        };
        process_samples: readonly ProcessSample[];
        protocol_events: readonly ProtocolEvent[];
        rendered_frames: readonly RenderedTerminalFrame[];
        residual_unknowns: readonly {
            reason: string;
            scope: | "protocol"
            | "terminal"
            | "exit"
            | "filesystem"
            | "process"
            | "cleanup"
            | "network";
        }[];
        schema_version: 3;
        shim_events: readonly ShimEvent[];
        truncated: boolean;
    }
    +
  • Defined in src/domain/processCapture.ts:504
    • @@ -49,87 +51,87 @@
    cleanup: { owned_process_group: "verified"; temporary_root: "removed" }
    +
  • Defined in src/domain/processCapture.ts:535
    • exit: {
        code: number | null;
        reason: "exited" | "timeout" | "idle_timeout";
        signal: number | null;
    }
    +
  • Defined in src/domain/processCapture.ts:510
    • files_after: readonly FileState[]
    +
  • Defined in src/domain/processCapture.ts:520
    • files_before: readonly FileState[]
    +
  • Defined in src/domain/processCapture.ts:519
    • filesystem_checkpoints: readonly FilesystemCheckpoint[]
    +
  • Defined in src/domain/processCapture.ts:516
    • filesystem_effects: readonly FileEffect[]
    +
  • Defined in src/domain/processCapture.ts:521
    • frames: readonly TerminalFrame[]
    +
  • Defined in src/domain/processCapture.ts:507
    • interaction_events: readonly InteractionEvent[]
    +
  • Defined in src/domain/processCapture.ts:509
    • limitations: readonly string[]
    +
  • Defined in src/domain/processCapture.ts:523
    • normalization: {
        paths: boolean;
        patterns: { pattern: string; replacement: string }[];
        pids: boolean;
        ports: boolean;
        time_bucket_ms: number;
    }
    +
  • Defined in src/domain/processCapture.ts:506
    • process_samples: readonly ProcessSample[]
    +
  • Defined in src/domain/processCapture.ts:515
    • protocol_events: readonly ProtocolEvent[]
    +
  • Defined in src/domain/processCapture.ts:518
    • rendered_frames: readonly RenderedTerminalFrame[]
    +
  • Defined in src/domain/processCapture.ts:508
    • residual_unknowns: readonly {
        reason: string;
        scope:
            | "protocol"
            | "terminal"
            | "exit"
            | "filesystem"
            | "process"
            | "cleanup"
            | "network";
    }[]
    +
  • Defined in src/domain/processCapture.ts:524
    • schema_version: 3
    +
  • Defined in src/domain/processCapture.ts:505
    • shim_events: readonly ShimEvent[]
    +
  • Defined in src/domain/processCapture.ts:517
    • truncated: boolean
    +
  • Defined in src/domain/processCapture.ts:522
    • diff --git a/docs/api/interfaces/domain_processCapture.ProcessExecutionPolicy.html b/docs/api/interfaces/domain_processCapture.ProcessExecutionPolicy.html index a5eb71c7a..b95dea5db 100644 --- a/docs/api/interfaces/domain_processCapture.ProcessExecutionPolicy.html +++ b/docs/api/interfaces/domain_processCapture.ProcessExecutionPolicy.html @@ -12,11 +12,11 @@
  • ProcessExecutionPolicy

    • Interface ProcessExecutionPolicy

    -

    Operator-owned policy for process capture.

    +

    Operator-owned ceiling applied in addition to per-scenario approval.

    interface ProcessExecutionPolicy {
        allowedEnvironment: readonly string[];
        allowExternalNetwork: boolean;
        enabled: boolean;
        executableRoots: readonly string[];
        workingRoots: readonly string[];
    }
    +
  • Defined in src/domain/processCapture.ts:326
    • @@ -37,27 +37,27 @@
    allowedEnvironment: readonly string[]
    +
  • Defined in src/domain/processCapture.ts:330
    • allowExternalNetwork: boolean
    +
  • Defined in src/domain/processCapture.ts:331
    • enabled: boolean
    +
  • Defined in src/domain/processCapture.ts:327
    • executableRoots: readonly string[]
    +
  • Defined in src/domain/processCapture.ts:328
    • workingRoots: readonly string[]
    +
  • Defined in src/domain/processCapture.ts:329
    • diff --git a/docs/api/interfaces/domain_processCapture.ProcessSample.html b/docs/api/interfaces/domain_processCapture.ProcessSample.html index 9aed63e73..3b39f2f34 100644 --- a/docs/api/interfaces/domain_processCapture.ProcessSample.html +++ b/docs/api/interfaces/domain_processCapture.ProcessSample.html @@ -16,7 +16,7 @@
    interface ProcessSample {
        at_ms: number;
        command: string;
        parent_pid: number;
        pid: number;
        process_group_id: number | null;
        session_id: number | null;
    }
    +
  • Defined in src/domain/processCapture.ts:449
    • @@ -38,32 +38,32 @@
    at_ms: number
    +
  • Defined in src/domain/processCapture.ts:450
    • command: string
    +
  • Defined in src/domain/processCapture.ts:453
    • parent_pid: number
    +
  • Defined in src/domain/processCapture.ts:452
    • pid: number
    +
  • Defined in src/domain/processCapture.ts:451
    • process_group_id: number | null
    +
  • Defined in src/domain/processCapture.ts:454
    • session_id: number | null
    +
  • Defined in src/domain/processCapture.ts:455
    • diff --git a/docs/api/interfaces/domain_processCapture.ProtocolEvent.html b/docs/api/interfaces/domain_processCapture.ProtocolEvent.html index 2fdd82e34..fe4d2c123 100644 --- a/docs/api/interfaces/domain_processCapture.ProtocolEvent.html +++ b/docs/api/interfaces/domain_processCapture.ProtocolEvent.html @@ -16,7 +16,7 @@
    interface ProtocolEvent {
        at_ms: number;
        data: string;
        direction: "request" | "response" | "received" | "sent";
        method: string | null;
        outcome: "matched" | "unmatched" | "script_exhausted" | "disconnected";
        path: string | null;
        protocol: "http" | "websocket";
        sequence: number;
    }
    +
  • Defined in src/domain/processCapture.ts:482
    • @@ -40,42 +40,42 @@
    at_ms: number
    +
  • Defined in src/domain/processCapture.ts:484
    • data: string
    +
  • Defined in src/domain/processCapture.ts:489
    • direction: "request" | "response" | "received" | "sent"
    +
  • Defined in src/domain/processCapture.ts:486
    • method: string | null
    +
  • Defined in src/domain/processCapture.ts:487
    • outcome: "matched" | "unmatched" | "script_exhausted" | "disconnected"
    +
  • Defined in src/domain/processCapture.ts:490
    • path: string | null
    +
  • Defined in src/domain/processCapture.ts:488
    • protocol: "http" | "websocket"
    +
  • Defined in src/domain/processCapture.ts:485
    • sequence: number
    +
  • Defined in src/domain/processCapture.ts:483
    • diff --git a/docs/api/interfaces/domain_processCapture.RenderedTerminalFrame.html b/docs/api/interfaces/domain_processCapture.RenderedTerminalFrame.html index e515d1c05..4cb9c9aae 100644 --- a/docs/api/interfaces/domain_processCapture.RenderedTerminalFrame.html +++ b/docs/api/interfaces/domain_processCapture.RenderedTerminalFrame.html @@ -12,11 +12,11 @@
  • RenderedTerminalFrame

    • Interface RenderedTerminalFrame

    -

    One rendered terminal state after xterm has parsed a PTY chunk or resize.

    +

    Serialized terminal state after interpreting control and resize sequences.

    interface RenderedTerminalFrame {
        active_buffer: "normal" | "alternate";
        at_ms: number;
        columns: number;
        cursor_x: number;
        cursor_y: number;
        lines: readonly string[];
        rows: number;
        sequence: number;
        serialized_state: string;
    }
    +
  • Defined in src/domain/processCapture.ts:408
    • @@ -41,47 +41,47 @@
    active_buffer: "normal" | "alternate"
    +
  • Defined in src/domain/processCapture.ts:415
    • at_ms: number
    +
  • Defined in src/domain/processCapture.ts:410
    • columns: number
    +
  • Defined in src/domain/processCapture.ts:411
    • cursor_x: number
    +
  • Defined in src/domain/processCapture.ts:413
    • cursor_y: number
    +
  • Defined in src/domain/processCapture.ts:414
    • lines: readonly string[]
    +
  • Defined in src/domain/processCapture.ts:416
    • rows: number
    +
  • Defined in src/domain/processCapture.ts:412
    • sequence: number
    +
  • Defined in src/domain/processCapture.ts:409
    • serialized_state: string
    +
  • Defined in src/domain/processCapture.ts:417
    • diff --git a/docs/api/interfaces/domain_processCapture.ShimEvent.html b/docs/api/interfaces/domain_processCapture.ShimEvent.html index 5efda0e56..d519e8e9a 100644 --- a/docs/api/interfaces/domain_processCapture.ShimEvent.html +++ b/docs/api/interfaces/domain_processCapture.ShimEvent.html @@ -12,11 +12,11 @@
  • ShimEvent

    • Interface ShimEvent

    -

    One invocation observed by the declarative command-shim replay adapter.

    +

    Recorded deterministic dependency invocation and route-match outcome.

    interface ShimEvent {
        arguments: readonly string[];
        at_ms: number;
        command: string;
        outcome: "matched" | "unmatched" | "exhausted";
        sequence: number;
        working_directory: string;
    }
    +
  • Defined in src/domain/processCapture.ts:472
    • @@ -38,32 +38,32 @@
    arguments: readonly string[]
    +
  • Defined in src/domain/processCapture.ts:476
    • at_ms: number
    +
  • Defined in src/domain/processCapture.ts:474
    • command: string
    +
  • Defined in src/domain/processCapture.ts:475
    • outcome: "matched" | "unmatched" | "exhausted"
    +
  • Defined in src/domain/processCapture.ts:478
    • sequence: number
    +
  • Defined in src/domain/processCapture.ts:473
    • working_directory: string
    +
  • Defined in src/domain/processCapture.ts:477
    • diff --git a/docs/api/interfaces/domain_processCapture.TerminalFrame.html b/docs/api/interfaces/domain_processCapture.TerminalFrame.html index d4f6bab39..021f9129e 100644 --- a/docs/api/interfaces/domain_processCapture.TerminalFrame.html +++ b/docs/api/interfaces/domain_processCapture.TerminalFrame.html @@ -12,11 +12,11 @@
  • TerminalFrame

    • Interface TerminalFrame

    -

    One bounded terminal observation.

    +

    Normalized raw PTY chunk, preserving transport-level output differences.

    interface TerminalFrame {
        at_ms: number;
        data: string;
        sequence: number;
    }
    +
  • Defined in src/domain/processCapture.ts:400
    • @@ -35,17 +35,17 @@
    at_ms: number
    +
  • Defined in src/domain/processCapture.ts:402
    • data: string
    +
  • Defined in src/domain/processCapture.ts:403
    • sequence: number
    +
  • Defined in src/domain/processCapture.ts:401
    • diff --git a/docs/api/types/application_ProcessOwnership.ProcessCleanupResult.html b/docs/api/types/application_ProcessOwnership.ProcessCleanupResult.html index 793637bd3..42668bd08 100644 --- a/docs/api/types/application_ProcessOwnership.ProcessCleanupResult.html +++ b/docs/api/types/application_ProcessOwnership.ProcessCleanupResult.html @@ -11,9 +11,11 @@
  • application/ProcessOwnership
  • ProcessCleanupResult

    • Type Alias ProcessCleanupResult

    -
    ProcessCleanupResult:
        | { cleaned: true; signaled: boolean }
        | { cleaned: false; reason: string }
    +
  • Defined in src/application/ProcessOwnership.ts:33
    • diff --git a/docs/api/types/domain_processCapture.ProcessPolicyDecision.html b/docs/api/types/domain_processCapture.ProcessPolicyDecision.html index 312d33ffa..41e6586f9 100644 --- a/docs/api/types/domain_processCapture.ProcessPolicyDecision.html +++ b/docs/api/types/domain_processCapture.ProcessPolicyDecision.html @@ -12,10 +12,10 @@
  • ProcessPolicyDecision

    • Type Alias ProcessPolicyDecision

    ProcessPolicyDecision: { allowed: true } | { allowed: false; reason: string }
    -

    A safe, caller-visible process-policy decision.

    +

    Explicit authorization result; denial reasons are safe to show callers.

    +
  • Defined in src/domain/processCapture.ts:336
    • diff --git a/docs/api/types/domain_processCapture.ProcessScenario.html b/docs/api/types/domain_processCapture.ProcessScenario.html index 54e571d00..f5d962fa8 100644 --- a/docs/api/types/domain_processCapture.ProcessScenario.html +++ b/docs/api/types/domain_processCapture.ProcessScenario.html @@ -12,10 +12,10 @@
  • ProcessScenario

    • Type Alias ProcessScenario

    ProcessScenario: z.infer<typeof processScenarioSchema>
    -

    A parsed, bounded dynamic process observation scenario.

    +

    Parsed instructions and resource bounds for one process experiment.

    +
  • Defined in src/domain/processCapture.ts:318
    • diff --git a/docs/api/variables/domain_processCapture.processCaptureSchema.html b/docs/api/variables/domain_processCapture.processCaptureSchema.html index 3179ae4a2..f4d13df78 100644 --- a/docs/api/variables/domain_processCapture.processCaptureSchema.html +++ b/docs/api/variables/domain_processCapture.processCaptureSchema.html @@ -15,7 +15,7 @@

    Exact serialized shape of a bounded process capture.

    +
  • Defined in src/domain/processCapture.ts:560
    • diff --git a/docs/api/variables/domain_processCapture.processScenarioSchema.html b/docs/api/variables/domain_processCapture.processScenarioSchema.html index 8363d3a4d..649e4cd45 100644 --- a/docs/api/variables/domain_processCapture.processScenarioSchema.html +++ b/docs/api/variables/domain_processCapture.processScenarioSchema.html @@ -12,10 +12,11 @@
  • processScenarioSchema

    • Variable processScenarioSchemaConst

    processScenarioSchema: ZodObject<
        {
            approved: ZodLiteral<true>;
            arguments: ZodDefault<ZodArray<ZodString>>;
            checkpoints: ZodDefault<
                ZodArray<
                    ZodObject<
                        {
                            name: ZodString;
                            trigger: ZodDiscriminatedUnion<
                                [
                                    ZodObject<{ at_ms: ZodNumber; type: ZodLiteral<(...)> }, $strip>,
                                    ZodObject<
                                        {
                                            occurrence: ZodDefault<(...)>;
                                            type: ZodLiteral<(...)>;
                                            value: ZodString;
                                        },
                                        $strip,
                                    >,
                                    ZodObject<{ type: ZodLiteral<(...)> }, $strip>,
                                    ZodObject<{ type: ZodLiteral<(...)> }, $strip>,
                                ],
                                "type",
                            >;
                        },
                        $strip,
                    >,
                >,
            >;
            command_shims: ZodDefault<
                ZodArray<
                    ZodObject<
                        {
                            name: ZodString;
                            routes: ZodArray<
                                ZodObject<
                                    {
                                        arguments: ZodArray<ZodString>;
                                        max_calls: ZodDefault<ZodNumber>;
                                        outputs: ZodDefault<ZodArray<(...)>>;
                                        termination: ZodDiscriminatedUnion<[(...), (...)], "type">;
                                    },
                                    $strip,
                                >,
                            >;
                        },
                        $strip,
                    >,
                >,
            >;
            environment: ZodDefault<ZodRecord<ZodString, ZodString>>;
            events: ZodDefault<
                ZodArray<
                    ZodDiscriminatedUnion<
                        [
                            ZodObject<
                                {
                                    at_ms: ZodNumber;
                                    data: ZodString;
                                    sensitive: ZodDefault<ZodBoolean>;
                                    type: ZodLiteral<"input">;
                                },
                                $strip,
                            >,
                            ZodObject<
                                {
                                    at_ms: ZodNumber;
                                    columns: ZodNumber;
                                    rows: ZodNumber;
                                    type: ZodLiteral<"resize">;
                                },
                                $strip,
                            >,
                            ZodObject<
                                {
                                    at_ms: ZodNumber;
                                    signal: ZodEnum<
                                        { SIGINT: "SIGINT"; SIGKILL: "SIGKILL"; SIGTERM: "SIGTERM" },
                                    >;
                                    type: ZodLiteral<"signal">;
                                },
                                $strip,
                            >,
                        ],
                        "type",
                    >,
                >,
            >;
            executable: ZodString;
            filesystem_roots: ZodDefault<ZodArray<ZodString>>;
            idle_timeout_ms: ZodDefault<ZodNumber>;
            inherit_environment: ZodDefault<ZodArray<ZodString>>;
            limits: ZodDefault<
                ZodObject<
                    {
                        connections: ZodDefault<ZodNumber>;
                        file_bytes: ZodDefault<ZodNumber>;
                        files: ZodDefault<ZodNumber>;
                        filesystem_depth: ZodDefault<ZodNumber>;
                        frames: ZodDefault<ZodNumber>;
                        output_bytes: ZodDefault<ZodNumber>;
                        processes: ZodDefault<ZodNumber>;
                        protocol_body_bytes: ZodDefault<ZodNumber>;
                        protocol_events: ZodDefault<ZodNumber>;
                    },
                    $strip,
                >,
            >;
            network_access: ZodDefault<ZodLiteral<"host">>;
            normalization: ZodDefault<
                ZodObject<
                    {
                        paths: ZodDefault<ZodBoolean>;
                        patterns: ZodDefault<
                            ZodArray<
                                ZodObject<{ pattern: ZodString; replacement: ZodString }, $strip>,
                            >,
                        >;
                        pids: ZodDefault<ZodBoolean>;
                        ports: ZodDefault<ZodBoolean>;
                        time_bucket_ms: ZodDefault<ZodNumber>;
                    },
                    $strip,
                >,
            >;
            replay: ZodDefault<
                ZodObject<
                    {
                        http: ZodDefault<
                            ZodArray<
                                ZodObject<
                                    {
                                        body: ZodString;
                                        delay_ms: ZodDefault<ZodNumber>;
                                        disconnect: ZodDefault<ZodBoolean>;
                                        max_calls: ZodDefault<ZodNumber>;
                                        method: ZodString;
                                        path: ZodString;
                                        request_body: ZodOptional<ZodString>;
                                        request_headers: ZodDefault<ZodRecord<(...), (...)>>;
                                        response_headers: ZodDefault<ZodRecord<(...), (...)>>;
                                        status: ZodNumber;
                                    },
                                    $strip,
                                >,
                            >,
                        >;
                        websocket_connections: ZodDefault<
                            ZodArray<
                                ZodObject<
                                    {
                                        disconnect_after: ZodDefault<ZodBoolean>;
                                        messages: ZodArray<ZodObject<(...), (...)>>;
                                    },
                                    $strip,
                                >,
                            >,
                        >;
                        websocket_messages: ZodDefault<ZodArray<ZodString>>;
                    },
                    $strip,
                >,
            >;
            secret_aliases: ZodDefault<ZodArray<ZodString>>;
            settle_ms: ZodDefault<ZodNumber>;
            terminal: ZodDefault<
                ZodObject<
                    {
                        columns: ZodDefault<ZodNumber>;
                        rows: ZodDefault<ZodNumber>;
                        scrollback: ZodDefault<ZodNumber>;
                    },
                    $strip,
                >,
            >;
            timeout_ms: ZodDefault<ZodNumber>;
            unknown_registry_approved: ZodOptional<ZodLiteral<true>>;
            working_directory: ZodString;
        },
        $strict,
    > = ...
    -

    Exact boundary schema for bounded dynamic process scenarios.

    +

    Boundary schema for one explicitly approved, bounded process experiment. +Defaults are part of the evidence contract and must remain deterministic.

    +
  • Defined in src/domain/processCapture.ts:44
    • diff --git a/src/application/CommandShimReplay.ts b/src/application/CommandShimReplay.ts index 6aa006057..7d766da3d 100644 --- a/src/application/CommandShimReplay.ts +++ b/src/application/CommandShimReplay.ts @@ -41,7 +41,13 @@ else process.exit(route.termination.code); const shellQuote = (value: string): string => `'${value.replaceAll("'", `'\\''`)}'`; -/** Start bounded executable replay wrappers and their private invocation ledger. */ +/** + * Start bounded executable replay wrappers and their private invocation ledger. + * + * Exact argument matching is deliberate: a fallback to the host executable + * would make an unmatched dependency call look authoritative. Unmatched and + * exhausted routes therefore fail visibly and remain part of the capture. + */ export const startCommandShimReplay = async ( scenario: ProcessScenario, temporaryRoot: string, diff --git a/src/application/ProcessCheckpoints.ts b/src/application/ProcessCheckpoints.ts index ebb11e5eb..f439f38e6 100644 --- a/src/application/ProcessCheckpoints.ts +++ b/src/application/ProcessCheckpoints.ts @@ -96,6 +96,9 @@ export class ProcessCheckpoints { capture(name: string): void { if (this.#captured.has(name)) return; this.#captured.add(name); + // Serialize scans even when time, terminal, and lifecycle triggers fire + // together. Each effect set is intentionally relative to the immediately + // preceding checkpoint, which preserves transient create/delete behavior. this.#pending = this.#pending.then(async () => { const snapshot = await snapshotRoots(this.scenario, this.signal); const previous = this.#captures.at(-1)?.files ?? []; diff --git a/src/application/ProcessHarness.ts b/src/application/ProcessHarness.ts index 51ff54df1..d1a6c84b3 100644 --- a/src/application/ProcessHarness.ts +++ b/src/application/ProcessHarness.ts @@ -1,7 +1,7 @@ import { randomUUID } from "node:crypto"; import { mkdtemp, realpath, rm } from "node:fs/promises"; import { tmpdir } from "node:os"; -import { dirname, join } from "node:path"; +import { join } from "node:path"; import { spawn, type IPty } from "node-pty"; import type { FilesystemCheckpoint, @@ -139,6 +139,10 @@ const makeEnvironment = ( environment.REA_REPLAY_HTTP_URL = replay.httpUrl; environment.REA_REPLAY_WEBSOCKET_URL = replay.websocketUrl; environment.REA_SHIM_LEDGER_URL = shimReplay.url; + // PATH is evidence-producing input. Inheriting the host PATH here would let + // the authority and reconstruction probe different tools without recording + // that difference. Scenarios must opt in through environment or + // inherit_environment; deterministic shims always take precedence. environment.PATH = [shimReplay.binPath, environment.PATH ?? ""] .filter((part) => part.length > 0) .join(":"); @@ -315,6 +319,9 @@ const awaitTerminalExit = async ({ reason: "exited" | "timeout" | "idle_timeout" | "cancelled"; }> => new Promise((resolveExit) => { + // The kill caused by a deadline is observed later as an ordinary PTY exit. + // Keep the initiating lifecycle reason so comparisons distinguish a target + // exit from harness-owned timeout, idle-timeout, and cancellation cleanup. let reason: "exited" | "timeout" | "idle_timeout" | "cancelled" = "exited"; terminal.onExit((exit) => { for (const [eventIndex, event] of scenario.events.entries()) { diff --git a/src/application/ProcessOwnership.ts b/src/application/ProcessOwnership.ts index b1de0c3c6..85e633d1e 100644 --- a/src/application/ProcessOwnership.ts +++ b/src/application/ProcessOwnership.ts @@ -4,6 +4,7 @@ import { promisify } from "node:util"; const execFileAsync = promisify(execFile); +/** Identity proof required before REA may signal a captured process group. */ export interface OwnedProcessGroup { readonly runId: string; readonly leaderPid: number; @@ -21,12 +22,14 @@ interface ProcessGroupMember { readonly command: string; } +/** Narrow operating-system seam used to inspect and signal process groups. */ export interface ProcessOwnershipHost { listMembers(processGroupId: number): Promise; environment(pid: number): Promise>>; signalGroup(processGroupId: number, signal: NodeJS.Signals): void; } +/** Cleanup succeeds only when the group is absent or every member is owned. */ export type ProcessCleanupResult = | { readonly cleaned: true; readonly signaled: boolean } | { readonly cleaned: false; readonly reason: string }; @@ -78,7 +81,13 @@ const systemHost: ProcessOwnershipHost = { }, }; -/** Verify run-token ownership before signaling a POSIX process group. */ +/** + * Verify run-token ownership before signaling a POSIX process group. + * + * Process IDs and group IDs can be reused. REA therefore re-reads every live + * member's environment immediately before signaling and fails closed if any + * member cannot be inspected or lacks the per-capture run token. + */ export const cleanupOwnedProcessGroup = async ( ownership: OwnedProcessGroup, host: ProcessOwnershipHost = systemHost, diff --git a/src/application/TerminalRenderer.ts b/src/application/TerminalRenderer.ts index 4737b7d0d..caf14ed3d 100644 --- a/src/application/TerminalRenderer.ts +++ b/src/application/TerminalRenderer.ts @@ -20,6 +20,13 @@ interface TerminalRendererOptions { } /** Owns one headless terminal and serializes writes into deterministic frames. */ +/** + * Reconstructs bounded terminal states while raw PTY chunks remain authoritative. + * + * Rendered frames answer what an operator saw after control-sequence handling; + * raw frames preserve byte/chunk differences that can render identically. + * Comparisons retain both because neither representation subsumes the other. + */ export class TerminalRenderer { readonly #terminal: InstanceType; readonly #serializeAddon = new SerializePackage.SerializeAddon(); diff --git a/src/artifacts/AsarArtifactReader.ts b/src/artifacts/AsarArtifactReader.ts index e16ce624b..698bc4ac3 100644 --- a/src/artifacts/AsarArtifactReader.ts +++ b/src/artifacts/AsarArtifactReader.ts @@ -8,7 +8,13 @@ import { type ArtifactReader, } from "./ArtifactReader.js"; -/** Official Electron ASAR adapter. Individual files remain caller-bounded. */ +/** + * Official Electron ASAR adapter. Individual files remain caller-bounded. + * + * An entry marked `unpacked` is metadata, not an integrity exemption: Electron + * stores its bytes beside the archive in `.unpacked`, and callers must + * hash those companion bytes against the archive's declared integrity value. + */ export class AsarArtifactReader implements ArtifactReader { readonly format = "asar" as const; diff --git a/src/domain/processCapture.ts b/src/domain/processCapture.ts index 771d25cc3..d172c331a 100644 --- a/src/domain/processCapture.ts +++ b/src/domain/processCapture.ts @@ -37,6 +37,10 @@ const outputChunkSchema = z.object({ }); /** Exact boundary schema for bounded dynamic process scenarios. */ +/** + * Boundary schema for one explicitly approved, bounded process experiment. + * Defaults are part of the evidence contract and must remain deterministic. + */ export const processScenarioSchema = z .object({ approved: z @@ -310,6 +314,7 @@ export const processScenarioSchema = z }); /** A parsed, bounded dynamic process observation scenario. */ +/** Parsed instructions and resource bounds for one process experiment. */ export type ProcessScenario = z.infer; /** Parse untrusted process scenario input and apply safe default budgets. */ @@ -317,6 +322,7 @@ export const parseProcessScenario = (input: unknown): ProcessScenario => processScenarioSchema.parse(input); /** Operator-owned policy for process capture. */ +/** Operator-owned ceiling applied in addition to per-scenario approval. */ export interface ProcessExecutionPolicy { readonly enabled: boolean; readonly executableRoots: readonly string[]; @@ -326,6 +332,7 @@ export interface ProcessExecutionPolicy { } /** A safe, caller-visible process-policy decision. */ +/** Explicit authorization result; denial reasons are safe to show callers. */ export type ProcessPolicyDecision = | { readonly allowed: true } | { readonly allowed: false; readonly reason: string }; @@ -389,6 +396,7 @@ export const authorizeProcessScenario = ( }; /** One bounded terminal observation. */ +/** Normalized raw PTY chunk, preserving transport-level output differences. */ export interface TerminalFrame { readonly sequence: number; readonly at_ms: number; @@ -396,6 +404,7 @@ export interface TerminalFrame { } /** One rendered terminal state after xterm has parsed a PTY chunk or resize. */ +/** Serialized terminal state after interpreting control and resize sequences. */ export interface RenderedTerminalFrame { readonly sequence: number; readonly at_ms: number; @@ -409,6 +418,7 @@ export interface RenderedTerminalFrame { } /** One attempted scripted interaction with the PTY. */ +/** Scheduled input, resize, or signal with its observed dispatch outcome. */ export interface InteractionEvent { readonly sequence: number; readonly scheduled_at_ms: number; @@ -446,6 +456,9 @@ export interface ProcessSample { } /** A named filesystem observation captured during a process lifecycle. */ +/** + * Named filesystem state whose effects are relative to the prior checkpoint. + */ export interface FilesystemCheckpoint { readonly name: string; readonly at_ms: number; @@ -455,6 +468,7 @@ export interface FilesystemCheckpoint { } /** One invocation observed by the declarative command-shim replay adapter. */ +/** Recorded deterministic dependency invocation and route-match outcome. */ export interface ShimEvent { readonly sequence: number; readonly at_ms: number; @@ -481,6 +495,12 @@ export interface ProtocolEvent { } /** A bounded process observation with explicit incompleteness metadata. */ +/** + * Process Capture v3 observation set. + * + * `truncated` and `residual_unknowns` are semantic evidence: consumers must not + * infer equivalence from matching bounded observations when either is present. + */ export interface ProcessCapture { readonly schema_version: 3; readonly normalization: z.infer; diff --git a/src/domain/processComparison.ts b/src/domain/processComparison.ts index e28eb7a6f..e81a5939c 100644 --- a/src/domain/processComparison.ts +++ b/src/domain/processComparison.ts @@ -197,6 +197,12 @@ const chooseFirstDivergence = ( }; /** Compare bounded captures without equating missing or incompatible evidence. */ +/** + * Compare two Process Capture v3 observations without treating absence as proof. + * + * Observed differences outrank residual unknowns. A capture may therefore be + * definitively changed in one dimension while completeness remains unknown. + */ export const compareProcessCaptures = ( left: ProcessCapture, right: ProcessCapture,