#Persistence & Crash Recovery

Version: 0.51.0 Updated: 2026-07-16 Applies to: ranvier-runtime Category: Deep Dives

Production-grade workflow durability and saga-style compensation.

#Recovery Flow

1. Append: Runtime saves a checkpoint after every successful step.
2. Crash: External state remains committed; process state is lost.
3. Resume: Restarted process loads trace and resumes from the last cursor.

#Durable Adapters

#Saga Pattern

• Compensation: Define rollback hooks for irreversible side effects.
• Idempotency: Ensure compensation runs exactly once per trace.
• Auto-Trigger: Runtime kicks off hooks automatically on Fault.

#Quickstart

// Cargo.toml: feature persistence-postgres
let store = PostgresPersistenceStore::new(pool);
store.ensure_schema().await?;
bus.insert(PersistenceHandle::from_store(store));

#Workflows

1. Insert PersistenceHandle into Bus at ingress boundary.
2. Define CompensationHook for transitions with side effects.
3. Configure retention (TTL/Purge) based on compliance requirements.
4. Monitor checkpoint_failures_total metrics in production.

#Cancellation State and Migration

Cancellation-aware execution writes an ordinary Enter event first, then a Cancelled event with the fixed reason/timestamps. Successful external compensation appends Compensated; auto-completion marks the trace Cancelled or Compensated. Every built-in adapter rejects ordinary append and resume after any completion marker.

This is additive for 0.51.x: the durable cancelled completion value already exists, so no schema migration or downgrade rewrite is required. Rolling back an opt-in caller to execute() or legacy HTTP run() does not remove prior terminal events. Reopening a completed trace is intentionally unsupported; recovery tooling must use a future explicit recovery contract rather than clearing completion in place.

#Key Types