Struct LocalBackend 

pub struct LocalBackend { /* private fields */ }

The always-compiled durable backend that journals to a dedicated durable.db.

Construct it from a zeph_db::DbPool (or open one with LocalBackend::open), then attach an optional PayloadCipher and HMAC key with the builder methods. Call LocalBackend::init once before use to apply the schema migrations.

Examples

use zeph_durable::LocalBackend;

// 1 MiB payload ceiling, matching the spec default.
let backend = LocalBackend::open("durable.db", 1_048_576).await?;
backend.init().await?;

Implementations

impl LocalBackend

pub fn new(pool: DbPool, max_payload_bytes: u64) -> Self

Wrap an existing zeph_db::DbPool as a local backend with the given payload ceiling.

Call LocalBackend::init before any journal operation to apply the schema. Attach a cipher and HMAC key with with_cipher and with_hmac_key.

pub async fn open( path: &str, max_payload_bytes: u64, ) -> Result<Self, DurableError>

Open (or create) a backend on a dedicated durable.db file (or :memory:).

Connecting also applies the schema migrations, so a freshly opened backend is ready to use; init may still be called and is idempotent.

Errors

Returns DurableError::Storage if the pool cannot be opened or migrations fail.

pub fn with_cipher(self, cipher: Arc<dyn PayloadCipher>) -> Self

Inject the AEAD payload cipher used to seal and open payload-bearing entries.

pub fn with_hmac_key(self, key: [u8; 32]) -> Self

Configure the keyed-BLAKE3 HMAC key stamped over control entries on shared-database deployments.

pub fn pool(&self) -> &DbPool

Borrow the underlying pool (for tests and adapters that need direct access).

pub async fn init(&self) -> Result<(), DurableError>

Apply the durable schema migrations to the backing pool.

Idempotent: safe to call repeatedly. The schema is owned by zeph-db, not this crate.

Errors

Returns DurableError::Storage if a migration fails.

pub async fn list_executions( &self, status: Option<&str>, kind: Option<&str>, limit: i64, ) -> Result<Vec<ExecutionSummary>, DurableError>

List execution summaries for operability surfaces (the zeph durable CLI and TUI).

Returns at most limit executions, newest first, optionally filtered by status and kind (each is matched against the raw column tag; None disables that filter). Only execution-level metadata is read — never payload bytes or resolver tokens (INV-5). The per-execution step count is the number of journal entries recorded for it.

Span: durable.backend.list.

Errors

Returns DurableError::Storage if the query fails, or DurableError::Decode if a stored id or status cannot be reconstructed (schema corruption — the status column is CHECK-constrained, so this is a fail-closed guard rather than a routine path).

pub async fn read_execution_redacted( &self, id: ExecutionId, ) -> Result<Vec<RedactedEntry>, DurableError>

Read one execution’s journal entries as redaction-safe metadata, without decrypting payloads.

Unlike read_execution, this never touches the cipher, so it works against a journal whose AEAD key is unavailable and never exposes plaintext (INV-5). It backs the default (redacted) zeph durable show/inspect output. Entries are returned in append order.

Span: durable.backend.read_redacted.

Errors

Returns DurableError::Storage if the query fails.

pub async fn count_prunable( &self, policy: &RetentionPolicy, ) -> Result<u64, DurableError>

Count terminal executions a prune sweep would delete under policy.

Read-only: backs zeph durable prune --dry-run. It applies the same TTL cutoffs as the delete path, so the count is exactly what a real sweep would remove now.

Errors

Returns DurableError::Storage if the query fails.

pub async fn open_execution( &self, id: ExecutionId, kind: ExecutionKind, ) -> Result<bool, DurableError>

Ensure a durable_executions row exists for id, returning whether this is a resume.

Inserts a fresh running row for a new execution (returning false) or detects an existing row for a resumed one (returning true). The journal’s foreign key requires this row before any entry is appended, so callers open the execution first.

Span: durable.backend.open.

Errors

Returns DurableError::Storage if the lookup or insert fails.

Trait Implementations

impl Debug for LocalBackend

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Redacts the cipher and HMAC key — never print key material or a cipher handle.

impl ExecutionBackend for LocalBackend

fn capabilities(&self) -> BackendCapabilities

Return this backend’s stable capability description.

async fn lookup_committed_result( &self, id: ExecutionId, idem_key: IdempotencyKey, ) -> Result<Option<JournalEntry>, DurableError>

Look up a committed StepResult anywhere in an execution by its IdempotencyKey.

impl Journal for LocalBackend

async fn append(&self, entry: JournalEntry) -> Result<JournalSeq, DurableError>

Append an entry and return its database-assigned global sequence number.

async fn read_execution( &self, id: ExecutionId, ) -> Result<Vec<JournalEntry>, DurableError>

Read every entry of an execution in append order.

async fn read_execution_range( &self, id: ExecutionId, from_step_id: u32, limit: usize, ) -> Result<Vec<JournalEntry>, DurableError>

Read up to limit entries of an execution starting at from_step_id.

async fn finalize( &self, id: ExecutionId, status: ExecutionStatus, ) -> Result<(), DurableError>

Transition an execution to a terminal status.

async fn prune(&self, policy: &RetentionPolicy) -> Result<u64, DurableError>

Prune terminal executions according to policy and return the number of rows deleted.