Module 4, Lesson 225 min

Time travel, and the Ark mapping

Time travel means reading and forking history.

Reading and forking checkpoint history

const snapshot = await graph.getState(config);           // latest state + next node
for await (const s of graph.getStateHistory(config)) {}  // walk every checkpoint

// re-enter at a specific past checkpoint:
const past = { configurable: { thread_id: "…", checkpoint_id: "…" } };
await graph.getState(past);

// fork: write new values onto a checkpoint, creating a new branch:
await graph.updateState(config, { retryCount: 0 });

getState returns the state and what node runs next. getStateHistory is the full lineage. updateState forks: it writes a new checkpoint with your override, which is how you replay from a modified past.

In your codebase: Ark maps almost one-to-one

Ark (~/dev/lumiere/apps/ark) is hand-rolled continuity, and it maps almost one-to-one onto these primitives. state/session.json (status active/retired/crashed, boot_phase) is the thread: the identity a resume attaches to. The PreCompact hook triggers /ark:continuity-writeback, and post-compact /ark:boot re-reads state -- that writeback is a checkpoint: the deliberate save before context loss. state/incident-log.jsonl (append-only forensic log) is the checkpoint history: the ordered record you walk to reconstruct what happened. SdkSession (src/sdk-session.ts) wraps the Agent SDK's query() with a PushAsyncIterable so the subprocess stays alive between turns; inject(text) is a whisper. That "stay alive between turns" is exactly what a thread plus checkpointer gives you declaratively.

The build's written mapping is the deliverable: session.json maps to thread, writeback maps to checkpoint, incident-log maps to history. Once you have built it, you can say whether Ark's bespoke files are earning their keep or reinventing the checkpointer.

Practice

Try it yourself

Quiz

What forking actually means

updateState is described as "forking". What actually forks, and how does that differ from getState with a checkpoint_id?

Recall

The honest equivalent to Ark's incident log

The mapping is close enough to be useful and wrong enough to be worth naming. Both halves are the answer.

What is the LangGraph equivalent of Ark's incident-log.jsonl, and what's the limit of that analogy?

Add a Postgres checkpointer, then kill and resume mid-run

Put persistence under the module 3 impulse graph and prove it survives a crash.

Extend ~/dev/groundschool/builds/m3-impulse-graph with a PostgresSaver checkpointer.
Compile the graph with { checkpointer } and run checkpointer.setup() once.
Start a run with a fixed thread_id, then kill the process partway through (e.g. mid-modulate).
Start a new process with the same thread_id and config, and invoke with null inputs to resume.
Confirm the run completes as a resume, not a fresh run from START.
Walk graph.getStateHistory(config) and annotate: which checkpoint is the writeback equivalent, which is the boot equivalent.
Write the mapping: session.json -> thread, writeback -> checkpoint, incident-log -> history.

Tick every step to confirm you did it.

Check

Mid-run kill and resume verified

Confirm the resume behavior after a mid-run process kill.

You should see

Killing the process mid-graph and resuming with the same thread_id completes the same thread (not a fresh run), and the checkpoint lineage is annotated with which checkpoint corresponds to a writeback and which to a boot.