zeph_orchestration/
error.rs

1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4use zeph_llm::LlmError;
5use zeph_subagent::SubAgentError;
6
7use super::lineage::LineageEntry;
8
9/// All error variants produced by the orchestration subsystem.
10///
11/// Variants are exhaustive — callers that match on this type should use a
12/// `_ => …` arm to stay robust against future additions.
13///
14/// # Fail-open policy
15///
16/// LLM-backed steps (verification, replan) are always fail-open: on failure
17/// they log a warning and continue rather than returning an error. Only
18/// structural invariant violations and hard configuration errors propagate as
19/// `Err`.
20///
21/// # Examples
22///
23/// ```rust
24/// use zeph_orchestration::OrchestrationError;
25///
26/// fn describe(err: &OrchestrationError) -> &'static str {
27///     match err {
28///         OrchestrationError::CycleDetected => "graph has a cycle",
29///         OrchestrationError::Disabled => "orchestration is off",
30///         _ => "other orchestration error",
31///     }
32/// }
33///
34/// let err = OrchestrationError::CycleDetected;
35/// assert_eq!(describe(&err), "graph has a cycle");
36/// ```
37#[derive(Debug, thiserror::Error)]
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    /// An LLM provider call failed in a context with no more specific variant.
106    ///
107    /// Existing call sites that map `LlmError` to `PlanningFailed` or other semantic
108    /// variants are intentional and should not be changed. This variant is for new code
109    /// and for callers in `zeph-core` that propagate raw LLM errors.
110    #[error("orchestration LLM call failed: {0}")]
111    Llm(#[from] LlmError),
112
113    /// A `VerifyPredicate::Expression` was encountered; only `Natural` is
114    /// supported in v1.
115    #[error("predicate type not supported: {0}")]
116    PredicateNotSupported(String),
117
118    /// Predicate remediation could not be injected because the replan budget is exhausted.
119    #[error("replan budget exhausted for task {task_id}: {reason}")]
120    ReplanBudgetExhausted {
121        /// Task that triggered remediation.
122        task_id: String,
123        /// Human-readable reason (e.g. "predicate remediation").
124        reason: String,
125    },
126
127    /// The DAG was aborted because a consecutive error chain in a `depends_on` path
128    /// (or a region fan-out failure rate) exceeded the configured threshold.
129    ///
130    /// `chain_depth` in the display is `chain.len()` for quick log scanning; the full
131    /// [`LineageEntry`] list is emitted to the structured audit log.
132    #[error("cascade abort: root={root:?}, chain_depth={}", chain.len())]
133    CascadeAborted {
134        /// Root task ID where the failure chain began.
135        root: super::graph::TaskId,
136        /// Full lineage chain at the time of abort; earliest entry first.
137        chain: Vec<LineageEntry>,
138    },
139}
zeph_orchestration/error.rs

zeph_orchestration/
error.rs
