runWithCheckpoints() to save state after complete top-level Workflow steps. Use continueFromCheckpoint() to validate an existing version 2 record and execute its remaining steps with a fresh caller context. A graph, condition, parallel group or repeat forms one complete boundary.
Checkpoints retain state and step results. They do not record model/tool playback, recover mid-step work, restore pending approvals or guarantee exactly-once effects. Choose recoverable execution graphs when you need per-node journals and effect reconciliation.
Version the definition and validate state
This example uses process-local storage and no external service. Install matching core packages and Zod using installation, save it ascheckpoint.ts, and run npx tsx checkpoint.ts.
definitionVersion and validateCheckpointState together. The version must attest callable code, factories and captured dependencies; step names alone cannot identify those changes. Version 2 checkpoints contain workflow name, definition version, ordered top-level step names and an absolute cursor. The continuation API validates all of them, validates external state and clones it before effects. Incompatible or noncloneable state rejects with checkpoint_incompatible.
Keep context outside snapshots
Continuation gets a fresh run context. Explicit caller identity, signal, execution services, mode, metadata and supported key/dependency options are authoritative. Credentials, clients, callbacks and active services are not serialized in checkpoint state. JSON-backed stores require JSON-compatible validated state. Saved state/results are cloned. Later ordinary mutation cannot rewrite an earlier snapshot. New records retain cumulative results, absolute step indices,parentCheckpointId and parentRunId. Continuing a continuation skips every previously completed top-level step.
WorkflowCheckpointStore supplies save, load, list, latest and clear. StorageBackedCheckpointStore wraps a StorageDriver; the backing driver’s persistence decides whether records survive process loss. keepLastN provides best-effort retention after save. Hosts own storage lifecycle, backup and coordination.
Handle failure at the boundary
A checkpoint save failure rejects before the next step even when the completed step already applied an external effect. A crash, cancellation or failed save inside an unsaved graph/repeat may cause the whole boundary to run again from the prior checkpoint. Keep external operation identity and receipts separately; cancellation does not roll back effects. Ordinary Workflow retries and checkpoint continuation are fresh execution. They cannot infer whether a payment, write or notification accepted before a lost acknowledgment. Use the durable action contract and recovery guidance for those outcomes.Migrate legacy records explicitly
replay() and fork() are deprecated compatibility APIs. They execute later steps afresh and may repeat later effects. Legacy envelope acceptance remains through the current major, but cannot establish original callable identity. Version 2 records receive strict validation even through those wrappers.
For migration, stop writers and verify the original workflow, absolute step index, definition version and state offline. Write a corrected format version 2 record with ordered step names and validated state. The strict continuation API neither guesses the original cursor nor offers a blanket legacy bypass.
See the checkpoint types, Workflow graph boundaries, and recovery comparison.