Skip to main content

Checkpointer

Trait Checkpointer 

Source
pub trait Checkpointer: Send + Sync {
    // Required methods
    fn put<'life0, 'async_trait>(
        &'life0 self,
        checkpoint: Checkpoint,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get_latest<'life0, 'life1, 'async_trait>(
        &'life0 self,
        thread_id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Option<Checkpoint>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn list<'life0, 'life1, 'async_trait>(
        &'life0 self,
        thread_id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Checkpoint>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;

    // Provided methods
    fn get_by_id<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        thread_id: &'life1 str,
        checkpoint_id: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<Option<Checkpoint>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn fork_thread<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        &'life0 self,
        src_thread: &'life1 str,
        dst_thread: &'life2 str,
        at_checkpoint_id: Option<&'life3 str>,
    ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait { ... }
}
Expand description

The checkpointer interface (the LangGraph BaseCheckpointSaver analog).

Implementations must be safe to share across tasks (Send + Sync) and are typically held as Arc<dyn Checkpointer> by the executor.

Required Methods§

Source

fn put<'life0, 'async_trait>( &'life0 self, checkpoint: Checkpoint, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Persist a checkpoint. Implementations must not overwrite an existing checkpoint with the same id (ids are unique by construction).

The checkpoint handed to put is always a full snapshot; backends that opt into delta checkpoints (R0.7 wave 4) decide the encoding internally (encode_delta) — a caller-set Checkpoint::base is never honored.

Source

fn get_latest<'life0, 'life1, 'async_trait>( &'life0 self, thread_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Checkpoint>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

The most recent checkpoint for a thread, or None if the thread has never been checkpointed. Recency is defined by insertion (put) order — the last successfully stored checkpoint wins — not by super-step number: replay on the same thread legitimately appends checkpoints whose step is at or below the existing head, and a later resume must continue that newest timeline.

Backends without an explicit insertion sequence use created_at as the insertion proxy. That is exact as long as checkpoints are minted fresh (Checkpoint::new) when stored and forked histories are copied oldest-first, which Checkpointer::fork_thread does.

Source

fn list<'life0, 'life1, 'async_trait>( &'life0 self, thread_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<Checkpoint>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

All checkpoints for a thread, oldest first (time-travel listing).

The order is total and identical across backends — ascending (step, created_at, id) — so that Checkpointer::fork_thread’s truncation-by-position is deterministic even when replay has appended several checkpoints sharing the same step.

Provided Methods§

Source

fn get_by_id<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, thread_id: &'life1 str, checkpoint_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Checkpoint>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Fetch one specific checkpoint of a thread by id (time-travel handle).

The default implementation lists the thread and finds the id, which is correct (if not maximally efficient) for every reasonable backend. Returns None when the thread has no checkpoint with that id.

Source

fn fork_thread<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, src_thread: &'life1 str, dst_thread: &'life2 str, at_checkpoint_id: Option<&'life3 str>, ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Fork a thread’s history into a new thread (time travel).

Copies the source thread’s checkpoints — oldest first — into dst_thread, preserving each checkpoint’s id, step, state, next_nodes, and created_at; only the thread_id changes. When at_checkpoint_id is given, only checkpoints up to and including that checkpoint are copied (fork from a mid-history point); when None, the full history is copied. Returns the number of checkpoints copied.

The default implementation re-puts each selected checkpoint with the destination thread id. This is correct for every implementation whose put uniqueness scope is per-thread — including both built-in impls (InMemoryCheckpointer keys its map by thread, and JsonFileCheckpointer stores under {dir}/{thread_id}/), so reused ids cannot collide across threads. An implementation whose put enforces globally unique ids, or whose storage path ignores checkpoint.thread_id, must override this method (e.g. a SQL backend with a global primary key would mint fresh ids or insert with an explicit thread column).

Delta-checkpoint backends (R0.7 wave 4) additionally override this to write the forked checkpoints as full snapshots: a fork is a new timeline and the natural compaction point, so time-travel reads on the fork never fold a chain — and never another timeline’s.

Errors when the source thread has no checkpoints, when at_checkpoint_id does not exist on the source thread, or when src_thread == dst_thread (ids would collide within one thread).

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§