zeph_config/durable.rs
1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Pure-data configuration for the durable execution layer (`[durable]`).
5//!
6//! These types mirror the `[durable]` TOML section and are the single source of truth for the
7//! durable execution configuration. They live in `zeph-config` (alongside every other subsystem
8//! config) so the aggregate [`Config`](crate::Config) can hold them without forcing the heavy
9//! `zeph-db`/`sqlx` dependency tree of `zeph-durable` onto the config layer. The `zeph-durable`
10//! crate re-exports these types and applies the AEAD enforcement policy (the `encryption_gate`)
11//! on top of them.
12//!
13//! Every field carries a spec default via the container-level `#[serde(default)]` attribute backed
14//! by [`Default`], so deserializing an empty table yields a fully-populated, spec-compliant
15//! configuration. No credentials appear inline — the AEAD key and any Restate endpoints are
16//! resolved from the vault by key name (spec-038 vault contract), never stored here.
17
18use serde::{Deserialize, Serialize};
19
20/// Which journal backend an execution uses.
21///
22/// `Restate` is only meaningful when the `restate` feature and an external Restate server are
23/// available; the variant is accepted in configuration regardless so a config can be authored
24/// ahead of the backend being compiled in.
25#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
26#[serde(rename_all = "lowercase")]
27pub enum DurableBackend {
28 /// Dedicated `durable.db` SQLite/Postgres file managed in-process. The default.
29 #[default]
30 Local,
31 /// External Restate server (feature-gated, server deployments only).
32 Restate,
33}
34
35/// Configuration for the durable execution layer (`[durable]`).
36///
37/// # Examples
38///
39/// ```
40/// use zeph_config::DurableConfig;
41///
42/// // An empty table deserializes to the spec defaults.
43/// let cfg: DurableConfig = toml::from_str("").unwrap();
44/// assert!(!cfg.enabled);
45/// assert_eq!(cfg.journal_ack_timeout_ms, 5000);
46/// assert_eq!(cfg.max_payload_bytes, 1_048_576);
47/// ```
48#[allow(clippy::struct_excessive_bools)] // config struct — boolean flags are idiomatic for TOML-deserialized configuration
49#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
50#[serde(default)]
51pub struct DurableConfig {
52 /// Master opt-in. When `false`, no journal is opened and behavior is identical to a build
53 /// without the durable layer.
54 pub enabled: bool,
55 /// Selected journal backend.
56 pub backend: DurableBackend,
57 /// Encrypt payloads with AEAD. A `false` value is a development-only override (it emits a
58 /// startup warning) and is forbidden for non-local backends (INV-8).
59 pub encrypt_payload: bool,
60 /// P1 adapter: wrap agent-loop steps in durable steps.
61 ///
62 /// When `true` (with `enabled = true`), every ordinary agent turn's LLM call is journaled
63 /// via a `DurableContext` opened lazily on the session's first turn (see
64 /// `zeph_core::agent::Agent::ensure_session_durable_ctx`, #5452). The execution is keyed on
65 /// the session's `ConversationId`, so this adapter requires semantic memory (`[memory]`) to
66 /// be enabled — without it, `conversation_id` is never set and the agent degrades to
67 /// non-durable with a one-time `tracing::warn!` at bootstrap, even though `agent_turns = true`
68 /// looks fully enabled in the config.
69 pub agent_turns: bool,
70 /// P2 adapter: journal the orchestration `/plan resume` replan budget.
71 pub orchestration: bool,
72 /// P3 adapter: exactly-once scheduler job fire.
73 pub scheduler: bool,
74 /// P4 adapter: durable promise for subagent spawn/await.
75 ///
76 /// Requires `agent_turns = true` as well: the durable seat is only attached when the
77 /// session's `DurableContext` (populated by the `agent_turns` adapter) is already `Some`
78 /// (#5452).
79 pub subagent: bool,
80 /// Group-commit interval for buffered appends, in milliseconds.
81 pub journal_flush_interval_ms: u64,
82 /// Timeout for an acknowledged append before degrading to non-durable mode, in milliseconds.
83 pub journal_ack_timeout_ms: u64,
84 /// In-execution step cap (soft fold at 90%, hard abort at 100%).
85 pub max_steps_per_execution: u32,
86 /// Maximum payload size in bytes, enforced on both append and read.
87 pub max_payload_bytes: u64,
88 /// Database fallback poll interval for parked promises, in seconds.
89 pub promise_poll_interval_secs: u64,
90 /// Above this many parked promises, resolution falls back to pure polling.
91 pub max_parked_promises: u32,
92 /// Journal retention and compaction policy (`[durable.retention]`).
93 pub retention: RetentionPolicy,
94}
95
96impl Default for DurableConfig {
97 fn default() -> Self {
98 Self {
99 enabled: false,
100 backend: DurableBackend::Local,
101 encrypt_payload: true,
102 agent_turns: true,
103 orchestration: true,
104 scheduler: true,
105 subagent: true,
106 journal_flush_interval_ms: 10,
107 journal_ack_timeout_ms: 5000,
108 max_steps_per_execution: 10_000,
109 max_payload_bytes: 1_048_576,
110 promise_poll_interval_secs: 2,
111 max_parked_promises: 1000,
112 retention: RetentionPolicy::default(),
113 }
114 }
115}
116
117/// Journal retention and compaction policy (`[durable.retention]`).
118///
119/// Drives the background prune sweep, which never runs on the dispatch hot path.
120///
121/// # Examples
122///
123/// ```
124/// use zeph_config::RetentionPolicy;
125///
126/// let policy = RetentionPolicy::default();
127/// assert_eq!(policy.ttl_completed_secs, 604_800); // 7 days
128/// assert_eq!(policy.ttl_failed_secs, 2_592_000); // 30 days
129/// ```
130#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
131#[serde(default)]
132pub struct RetentionPolicy {
133 /// Prune completed executions older than this, in seconds.
134 pub ttl_completed_secs: u64,
135 /// Prune failed or aborted executions older than this, in seconds.
136 pub ttl_failed_secs: u64,
137 /// LRU cap on the number of stored executions.
138 pub max_executions: u64,
139 /// Size cap on the journal in bytes; exceeding it triggers an LRU sweep.
140 pub max_journal_bytes: u64,
141 /// Rows deleted per transaction during a prune sweep; the task yields between batches.
142 pub prune_batch_size: u64,
143 /// Background prune poll interval, in seconds.
144 pub prune_interval_secs: u64,
145}
146
147impl Default for RetentionPolicy {
148 fn default() -> Self {
149 Self {
150 ttl_completed_secs: 604_800,
151 ttl_failed_secs: 2_592_000,
152 max_executions: 10_000,
153 max_journal_bytes: 1_073_741_824,
154 prune_batch_size: 500,
155 prune_interval_secs: 3600,
156 }
157 }
158}
159
160#[cfg(test)]
161mod tests {
162 use super::*;
163
164 #[test]
165 fn empty_table_yields_every_spec_default() {
166 let cfg: DurableConfig = toml::from_str("").unwrap();
167 assert!(!cfg.enabled);
168 assert_eq!(cfg.backend, DurableBackend::Local);
169 assert!(cfg.encrypt_payload);
170 assert!(cfg.agent_turns);
171 assert!(cfg.orchestration);
172 assert!(cfg.scheduler);
173 assert!(cfg.subagent);
174 assert_eq!(cfg.journal_flush_interval_ms, 10);
175 assert_eq!(cfg.journal_ack_timeout_ms, 5000);
176 assert_eq!(cfg.max_steps_per_execution, 10_000);
177 assert_eq!(cfg.max_payload_bytes, 1_048_576);
178 assert_eq!(cfg.promise_poll_interval_secs, 2);
179 assert_eq!(cfg.max_parked_promises, 1000);
180 }
181
182 #[test]
183 fn empty_table_yields_retention_defaults() {
184 let cfg: DurableConfig = toml::from_str("").unwrap();
185 assert_eq!(cfg.retention.ttl_completed_secs, 604_800);
186 assert_eq!(cfg.retention.ttl_failed_secs, 2_592_000);
187 assert_eq!(cfg.retention.max_executions, 10_000);
188 assert_eq!(cfg.retention.max_journal_bytes, 1_073_741_824);
189 assert_eq!(cfg.retention.prune_batch_size, 500);
190 assert_eq!(cfg.retention.prune_interval_secs, 3600);
191 }
192
193 #[test]
194 fn default_impl_matches_serde_default() {
195 let from_toml: DurableConfig = toml::from_str("").unwrap();
196 assert_eq!(from_toml, DurableConfig::default());
197 }
198
199 #[test]
200 fn partial_table_overrides_only_named_fields() {
201 let cfg: DurableConfig = toml::from_str(
202 r#"
203 enabled = true
204 backend = "restate"
205
206 [retention]
207 prune_batch_size = 999
208 "#,
209 )
210 .unwrap();
211 assert!(cfg.enabled);
212 assert_eq!(cfg.backend, DurableBackend::Restate);
213 // Untouched fields keep their defaults.
214 assert_eq!(cfg.journal_ack_timeout_ms, 5000);
215 assert_eq!(cfg.retention.prune_batch_size, 999);
216 assert_eq!(cfg.retention.ttl_completed_secs, 604_800);
217 }
218}