Crate zeph_durable 

Native durable execution layer for Zeph.

zeph-durable is a Layer-0 infrastructure crate — analogous to zeph-db and zeph-common — that journals the control flow of an execution (individual steps, their inputs and outputs, promises, and timers) so a crashed or interrupted execution can resume at the point of failure rather than restart from scratch.

Architectural placement

Consumers of this crate span several layers (zeph-scheduler, zeph-subagent, zeph-orchestration, zeph-agent-tools), so the crate must sit at Layer 0. It is a pure infrastructure primitive: it sees opaque serialized payloads, never domain types, and it MUST NOT depend on zeph-llm, zeph-memory, zeph-core, zeph-sanitizer, or any business-layer crate (INV-1). Domain meaning lives in thin adapter modules inside each consuming crate.

Module map

Type-level foundation:

• ids — the journal-boundary newtypes (ExecutionId, StepId, JournalSeq, IdempotencyKey, PromiseId, TimerId) and the ExecutionKind discriminator.
• journal — the Journal trait plus the JournalEntry / EntryKind / ExecutionStatus data model.
• cipher — the PayloadCipher AEAD contract, PayloadAad binding, and the read-side max_payload guard. The concrete cipher lives in a consuming crate (INV-1).
• effect — the EffectClass side-effect contract referenced by journal entries.
• config — re-exports the pure-data DurableConfig and RetentionPolicy (which live in zeph-config) and owns the encryption_gate AEAD enforcement policy.
• error — the crate-wide DurableError.

Persistence engine:

• backend — the sealed ExecutionBackend trait, BackendCapabilities, the DurableBackendEnum enum dispatcher, and LocalBackend (a dedicated durable.db pool).
• writer — the background JournalWriter actor and its cloneable JournalWriterHandle: group-commit for buffered appends, flush-before-commit ACKs for exactly-once entries, and MAX(seq) restart resume.

Execution surface:

• step — the durable step typestate: StepDescriptor (with the construction-time ambiguity rule), StepHandle, StepError, StepOutcome, and DurableStep.
• handle — the &self DurableContext front door: deterministic step ids, replay with a BLAKE3 divergence guard, the exactly-once intent/result protocol, and ParallelScope for completion-order-independent parallel batches.

The promise, timer, and retention layers build on these in follow-up issues.

Schema ownership

zeph-durable owns no .sql files and no sqlx::migrate!. All durable schema (the four durable_* tables) lives as numbered migration files in zeph-db/migrations/{sqlite,postgres}/ and is applied via zeph_db::run_migrations against a dedicated durable.db pool (INV-14).

Examples

use zeph_durable::{ExecutionId, IdempotencyKey, StepId};

// Each execution gets a fresh, runtime-minted identity.
let execution = ExecutionId::new();

// Idempotency keys are domain-separated and deterministic for a given step.
let key = IdempotencyKey::derive(execution, StepId::new(0), b"tool:read_file");
assert_eq!(key, IdempotencyKey::derive(execution, StepId::new(0), b"tool:read_file"));

Re-exports

pub use backend::BackendCapabilities;

pub use backend::CancelOutcome;

pub use backend::DurableBackendEnum;

pub use backend::ExecutionBackend;

pub use backend::ExecutionLock;

pub use backend::ExecutionSummary;

pub use backend::LocalBackend;

pub use backend::RedactedEntry;

pub use cipher::CipherError;

pub use cipher::EntryKindTag;

pub use cipher::PayloadAad;

pub use cipher::PayloadCipher;

pub use cipher::ensure_payload_within_limit;

pub use config::EncryptionGate;

pub use config::encryption_gate;

pub use effect::EffectClass;

pub use effect::EffectIntentSubClass;

pub use effect::OnAmbiguous;

pub use error::DurableError;

pub use handle::DurableContext;

pub use handle::ParallelScope;

pub use ids::ExecutionId;

pub use ids::ExecutionKind;

pub use ids::IdempotencyKey;

pub use ids::JournalSeq;

pub use ids::PromiseId;

pub use ids::StepId;

pub use ids::TimerId;

pub use journal::EntryKind;

pub use journal::ExecutionStatus;

pub use journal::Journal;

pub use journal::JournalEntry;

pub use promise::DurableHandle;

pub use promise::DurablePromise;

pub use retention::DurableRetentionService;

pub use step::DurableStep;

pub use step::StepDescriptor;

pub use step::StepError;

pub use step::StepHandle;

pub use step::StepOutcome;

pub use timer::DurableTimerService;

pub use writer::JournalWriter;

pub use writer::JournalWriterHandle;

Modules

backend

The sealed execution-backend abstraction and its enum-dispatch front door.

cipher

The confidentiality and integrity boundary for journaled payloads.

config

Durable configuration and the AEAD enforcement gate.

effect

The per-step side-effect contract.

error

The crate-wide error type.

handle

The &self durable execution context.

ids

Journal-boundary newtypes.

journal

The append-only journal abstraction and its data model.

promise

Durable promises: externally-completed handles that survive a crash-resume.

retention

Journal retention, the background prune sweep, and the checkpoint-fold codec.

step

The durable step primitive and its typestate.

timer

Durable timers: wakes that survive a process restart.

writer

The background journal-writer actor.

Structs

DurableConfig

Configuration for the durable execution layer ([durable]).

RetentionPolicy

Journal retention and compaction policy ([durable.retention]).

Enums

DurableBackend

Which journal backend an execution uses.