zeph_orchestration/
error.rs

1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4use zeph_subagent::SubAgentError;
5
6use super::lineage::LineageEntry;
7
8/// All error variants produced by the orchestration subsystem.
9///
10/// Variants are exhaustive — callers that match on this type should use a
11/// `_ => …` arm to stay robust against future additions.
12///
13/// # Fail-open policy
14///
15/// LLM-backed steps (verification, replan) are always fail-open: on failure
16/// they log a warning and continue rather than returning an error. Only
17/// structural invariant violations and hard configuration errors propagate as
18/// `Err`.
19///
20/// # Examples
21///
22/// ```rust
23/// use zeph_orchestration::OrchestrationError;
24///
25/// fn describe(err: &OrchestrationError) -> &'static str {
26///     match err {
27///         OrchestrationError::CycleDetected => "graph has a cycle",
28///         OrchestrationError::Disabled => "orchestration is off",
29///         _ => "other orchestration error",
30///     }
31/// }
32///
33/// let err = OrchestrationError::CycleDetected;
34/// assert_eq!(describe(&err), "graph has a cycle");
35/// ```
36#[derive(Debug, thiserror::Error)]
37#[non_exhaustive]
38pub enum OrchestrationError {
39    /// Orchestration is disabled in configuration.
40    #[error("orchestration is disabled")]
41    Disabled,
42
43    /// The LLM planner failed to produce a valid task graph.
44    #[error("planning failed: {0}")]
45    PlanningFailed(String),
46
47    /// The task graph structure is invalid (e.g. wrong task-id invariant, bad reference).
48    #[error("invalid graph: {0}")]
49    InvalidGraph(String),
50
51    /// A cycle was detected during topological sort of the task graph.
52    #[error("cycle detected in task graph")]
53    CycleDetected,
54
55    /// A `TaskId` or task title lookup yielded no result.
56    #[error("task not found: {0}")]
57    TaskNotFound(String),
58
59    /// No agent in the available pool can be routed to a task.
60    #[error("no agent available for task: {0}")]
61    NoAgentAvailable(String),
62
63    /// A `GraphId` could not be found in persistence.
64    #[error("graph not found: {0}")]
65    GraphNotFound(String),
66
67    /// An internal scheduler invariant was violated.
68    #[error("scheduler error: {0}")]
69    Scheduler(String),
70
71    /// Result aggregation failed and the fallback path also failed.
72    #[error("aggregation failed: {0}")]
73    AggregationFailed(String),
74
75    /// A database read/write or serialization error in graph persistence.
76    #[error("persistence error: {0}")]
77    Persistence(String),
78
79    /// A task exceeded its per-task wall-clock timeout.
80    #[error("task timed out: {0}")]
81    TaskTimeout(String),
82
83    /// The scheduler or a task was canceled by the caller.
84    #[error("canceled")]
85    Canceled,
86
87    /// A `/plan` CLI command could not be parsed.
88    #[error("invalid command: {0}")]
89    InvalidCommand(String),
90
91    /// Hard invariant violation during verification (e.g. cycle detected after `inject_tasks`).
92    ///
93    /// Never used for LLM call failures — those are fail-open and only log a warning.
94    #[error("verification failed: {0}")]
95    VerificationFailed(String),
96
97    /// A required configuration value is missing or out of range.
98    #[error("invalid configuration: {0}")]
99    InvalidConfig(String),
100
101    /// Propagated error from a sub-agent execution.
102    #[error(transparent)]
103    SubAgent(#[from] SubAgentError),
104
105    /// A `VerifyPredicate::Expression` was encountered; only `Natural` is
106    /// supported in v1.
107    #[error("predicate type not supported: {0}")]
108    PredicateNotSupported(String),
109
110    /// Predicate remediation could not be injected because the replan budget is exhausted.
111    #[error("replan budget exhausted for task {task_id}: {reason}")]
112    ReplanBudgetExhausted {
113        /// Task that triggered remediation.
114        task_id: String,
115        /// Human-readable reason (e.g. "predicate remediation").
116        reason: String,
117    },
118
119    /// The DAG was aborted because a consecutive error chain in a `depends_on` path
120    /// (or a region fan-out failure rate) exceeded the configured threshold.
121    ///
122    /// `chain_depth` in the display is `chain.len()` for quick log scanning; the full
123    /// [`LineageEntry`] list is emitted to the structured audit log.
124    #[error("cascade abort: root={root:?}, chain_depth={}", chain.len())]
125    CascadeAborted {
126        /// Root task ID where the failure chain began.
127        root: super::graph::TaskId,
128        /// Full lineage chain at the time of abort; earliest entry first.
129        chain: Vec<LineageEntry>,
130    },
131}
zeph_orchestration/error.rs

zeph_orchestration/
error.rs
