Interface Checkpoint

A complete, serialisable snapshot of a graph run captured at a node boundary.

The store persists one Checkpoint per save() call and makes them queryable by runId (latest or by nodeId) so the runtime can restore execution state after a crash or perform time-travel debugging.

interface Checkpoint {
    id: string;
    graphId: string;
    runId: string;
    nodeId: string;
    timestamp: number;
    state: {
        input: unknown;
        scratch: unknown;
        artifacts: unknown;
        diagnostics: DiagnosticsView;
    };
    memorySnapshot?: {
        reads: {
            traceId: string;
            content: string;
            strength: number;
        }[];
        pendingWrites: {
            type: string;
            content: string;
            scope: string;
        }[];
    };
    nodeResults: Record<string, {
        effectClass: EffectClass;
        output: unknown;
        durationMs: number;
        routeTarget?: string;
    }>;
    visitedNodes: string[];
    skippedNodes?: string[];
    pendingEdges: string[];
}

Properties

id graphId runId nodeId timestamp state memorySnapshot? nodeResults visitedNodes skippedNodes? pendingEdges

Properties

id

id: string

Unique checkpoint identifier (UUIDv4 assigned by the runtime).

graphId

graphId: string

Id of the CompiledExecutionGraph being executed.

runId

runId: string

Id of the graph run that produced this checkpoint.

nodeId

nodeId: string

Id of the node at whose boundary this checkpoint was captured.

timestamp

timestamp: number

Unix epoch milliseconds when the checkpoint was persisted.

state

state: {
    input: unknown;
    scratch: unknown;
    artifacts: unknown;
    diagnostics: DiagnosticsView;
}

Serialised GraphState partitions captured at the checkpoint boundary. memory is excluded because it is always rehydrated fresh on resume.

Type declaration

  • input: unknown

    The original user-provided input frozen at graph start.

  • scratch: unknown

    Node-to-node communication bag value at the checkpoint boundary.

  • artifacts: unknown

    Accumulated external outputs at the checkpoint boundary.

  • diagnostics: DiagnosticsView

    Accumulated diagnostic telemetry up to this checkpoint.

Optional memorySnapshot

memorySnapshot?: {
    reads: {
        traceId: string;
        content: string;
        strength: number;
    }[];
    pendingWrites: {
        type: string;
        content: string;
        scope: string;
    }[];
}

Optional snapshot of the memory subsystem state at this checkpoint. When present the runtime can restore memory context without re-reading from the store.

Type declaration

  • reads: {
        traceId: string;
        content: string;
        strength: number;
    }[]

    Memory traces that were read before or during the checkpointed node.

  • pendingWrites: {
        type: string;
        content: string;
        scope: string;
    }[]

    Writes that were staged but not yet committed when the checkpoint was taken.

nodeResults

nodeResults: Record<string, {
    effectClass: EffectClass;
    output: unknown;
    durationMs: number;
    routeTarget?: string;
}>

Results recorded when this checkpoint was taken, keyed by node id: those of the nodes in visitedNodes and, in the checkpoint of a run that a node interrupted, that node's, as in the checkpoint saved before an expansion that came after a write, external or human node. A node that failed records none, so a resume runs it again.

Type declaration

  • effectClass: EffectClass

    The node's declared effect class.

  • output: unknown

    The output value produced by the node.

  • durationMs: number

    Wall-clock execution time in milliseconds.

  • Optional routeTarget?: string

    The target the node picked itself, as a router, a guardrail that reroutes or the exit of a voice node does. A resume that marks the node complete with this result, as it does a write, external or human node such as a voice node, goes there rather than evaluating the node's edges. routerNode() and guardrailNode() build pure nodes, which a resume never marks complete from a recorded result: one the checkpoint does not list as completed runs again and picks its target anew.

visitedNodes

visitedNodes: string[]

Ordered list of node ids that had completed execution when this checkpoint was taken.

Optional skippedNodes

skippedNodes?: string[]

Ordered list of node ids that were explicitly bypassed by routing decisions (for example, the non-selected arm of a conditional branch).

Persisting this list is required for correct resume semantics on branched graphs: otherwise a resumed run cannot distinguish "not run yet" from "intentionally skipped" and may stall on dead branches.

pendingEdges

pendingEdges: string[]

Ids of edges that had been emitted but whose target nodes had not yet started.

Settings

Member Visibility

Theme

On This Page

idgraphIdrunIdnodeIdtimestampstatememorySnapshotnodeResultsvisitedNodesskippedNodespendingEdges