enya-agent 0.1.0

package/crates/enact-core/src/kernel/error.rs

@@ -0,0 +1,1200 @@
+//! Execution Error Taxonomy - Deterministic Failure Semantics
+//!
+//! This module defines the formal `ExecutionError` model that allows the kernel
+//! to make deterministic decisions about retries, billing, and failure reporting.
+//!
+//! ## Design Principles
+//!
+//! 1. **No Generic Errors**: Every error MUST be categorized
+//! 2. **Retry Policies Are Explicit**: Each error declares its retry behavior
+//! 3. **Idempotency Is Tracked**: Side-effect operations declare idempotency requirements
+//! 4. **Backoff Is Deterministic**: Retry timing is calculated, not random
+//!
+//! ## Error Categories
+//!
+//! - `LlmError`: LLM provider errors (usually retryable with backoff)
+//! - `ToolError`: Tool execution errors (may be retryable)
+//! - `PolicyViolation`: Policy/guardrail violation (NEVER retryable)
+//! - `Timeout`: Execution timeout (retryable with extended timeout)
+//! - `QuotaExceeded`: Resource quota exceeded (NEVER retryable)
+//! - `KernelInternal`: Internal kernel error (NEVER retryable)
+//! - `ValidationError`: Input validation error (NEVER retryable)
+//! - `NetworkError`: Network/connectivity error (usually retryable)
+//!
+//! @see docs/feat-02-error-taxonomy.md
+//! @see packages/enact-schemas/src/execution.schemas.ts
+
+use super::ids::StepId;
+use serde::{Deserialize, Serialize};
+use std::time::Duration;
+
+// =============================================================================
+// Error Categories
+// =============================================================================
+
+/// High-level error categories for deterministic recovery
+///
+/// Categories determine retry behavior and are the primary classification
+/// for all execution failures.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "PascalCase")]
+pub enum ExecutionErrorCategory {
+    /// LLM provider error (rate limit, content filter, context overflow)
+    LlmError,
+    /// Tool execution error (tool crashed, invalid output)
+    ToolError,
+    /// Policy/guardrail violation (FATAL - never retry)
+    PolicyViolation,
+    /// Execution timeout (step or wall clock)
+    Timeout,
+    /// Resource quota exceeded (FATAL - never retry)
+    QuotaExceeded,
+    /// Internal kernel error (FATAL - never retry)
+    KernelInternal,
+    /// Input validation error (FATAL - never retry)
+    ValidationError,
+    /// Network/connectivity error (usually retryable)
+    NetworkError,
+}
+
+impl ExecutionErrorCategory {
+    /// Check if this category is fatal (never retryable)
+    pub fn is_fatal(&self) -> bool {
+        matches!(
+            self,
+            Self::PolicyViolation | Self::QuotaExceeded | Self::KernelInternal | Self::ValidationError
+        )
+    }
+
+    /// Get the default retry policy for this category
+    pub fn default_retry_policy(&self) -> RetryPolicy {
+        match self {
+            Self::LlmError => RetryPolicy {
+                retryable: true,
+                max_retries: 3,
+                backoff_strategy: BackoffStrategy::Exponential,
+                base_delay: Duration::from_millis(1000),
+                max_delay: Duration::from_millis(30000),
+                requires_idempotency_key: false,
+            },
+            Self::ToolError => RetryPolicy {
+                retryable: true,
+                max_retries: 2,
+                backoff_strategy: BackoffStrategy::Constant,
+                base_delay: Duration::from_millis(500),
+                max_delay: Duration::from_millis(5000),
+                requires_idempotency_key: true, // Tools may have side effects
+            },
+            Self::PolicyViolation => RetryPolicy::fatal(),
+            Self::Timeout => RetryPolicy {
+                retryable: true,
+                max_retries: 1,
+                backoff_strategy: BackoffStrategy::Constant,
+                base_delay: Duration::ZERO,
+                max_delay: Duration::ZERO,
+                requires_idempotency_key: true,
+            },
+            Self::QuotaExceeded => RetryPolicy::fatal(),
+            Self::KernelInternal => RetryPolicy::fatal(),
+            Self::ValidationError => RetryPolicy::fatal(),
+            Self::NetworkError => RetryPolicy {
+                retryable: true,
+                max_retries: 3,
+                backoff_strategy: BackoffStrategy::Exponential,
+                base_delay: Duration::from_millis(500),
+                max_delay: Duration::from_millis(15000),
+                requires_idempotency_key: true,
+            },
+        }
+    }
+}
+
+impl std::fmt::Display for ExecutionErrorCategory {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::LlmError => write!(f, "LlmError"),
+            Self::ToolError => write!(f, "ToolError"),
+            Self::PolicyViolation => write!(f, "PolicyViolation"),
+            Self::Timeout => write!(f, "Timeout"),
+            Self::QuotaExceeded => write!(f, "QuotaExceeded"),
+            Self::KernelInternal => write!(f, "KernelInternal"),
+            Self::ValidationError => write!(f, "ValidationError"),
+            Self::NetworkError => write!(f, "NetworkError"),
+        }
+    }
+}
+
+// =============================================================================
+// Backoff Strategy
+// =============================================================================
+
+/// How to space out retry attempts
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum BackoffStrategy {
+    /// No delay between retries
+    #[default]
+    None,
+    /// Fixed delay between retries
+    Constant,
+    /// Linearly increasing delay (base * attempt)
+    Linear,
+    /// Exponentially increasing delay (base * 2^(attempt-1))
+    Exponential,
+}
+
+impl BackoffStrategy {
+    /// Calculate delay for a given attempt number (1-indexed)
+    pub fn calculate_delay(&self, base: Duration, attempt: u32, max: Duration) -> Duration {
+        let delay = match self {
+            Self::None => Duration::ZERO,
+            Self::Constant => base,
+            Self::Linear => base * attempt,
+            Self::Exponential => {
+                let multiplier = 2u64.saturating_pow(attempt.saturating_sub(1));
+                base.saturating_mul(multiplier as u32)
+            }
+        };
+        std::cmp::min(delay, max)
+    }
+}
+
+// =============================================================================
+// Retry Policy
+// =============================================================================
+
+/// Deterministic retry behavior for an error
+///
+/// The kernel uses this to decide:
+/// 1. Should we retry? (retryable)
+/// 2. How many times? (max_retries)
+/// 3. How long to wait? (backoff_strategy + base_delay)
+/// 4. Is the operation idempotent? (requires_idempotency_key)
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct RetryPolicy {
+    /// Whether this error is retryable at all
+    pub retryable: bool,
+
+    /// Maximum number of retry attempts (0 = no retries)
+    pub max_retries: u32,
+
+    /// Backoff strategy for spacing retries
+    pub backoff_strategy: BackoffStrategy,
+
+    /// Base delay for backoff calculation
+    #[serde(with = "duration_millis")]
+    pub base_delay: Duration,
+
+    /// Maximum delay (caps exponential backoff)
+    #[serde(with = "duration_millis")]
+    pub max_delay: Duration,
+
+    /// Whether the operation requires an idempotency key for safe retry
+    /// If true, the kernel MUST generate an IdempotencyKey before retrying
+    pub requires_idempotency_key: bool,
+}
+
+impl RetryPolicy {
+    /// Create a fatal (non-retryable) policy
+    pub fn fatal() -> Self {
+        Self {
+            retryable: false,
+            max_retries: 0,
+            backoff_strategy: BackoffStrategy::None,
+            base_delay: Duration::ZERO,
+            max_delay: Duration::ZERO,
+            requires_idempotency_key: false,
+        }
+    }
+
+    /// Create a simple retryable policy
+    pub fn retryable(max_retries: u32) -> Self {
+        Self {
+            retryable: true,
+            max_retries,
+            backoff_strategy: BackoffStrategy::Exponential,
+            base_delay: Duration::from_millis(1000),
+            max_delay: Duration::from_millis(30000),
+            requires_idempotency_key: false,
+        }
+    }
+
+    /// Calculate delay for a given attempt number
+    pub fn delay_for_attempt(&self, attempt: u32) -> Duration {
+        self.backoff_strategy
+            .calculate_delay(self.base_delay, attempt, self.max_delay)
+    }
+
+    /// Check if a retry should be attempted for the given attempt number
+    pub fn should_retry(&self, attempt: u32) -> bool {
+        self.retryable && attempt <= self.max_retries
+    }
+}
+
+impl Default for RetryPolicy {
+    fn default() -> Self {
+        Self::fatal()
+    }
+}
+
+// =============================================================================
+// LLM Error Codes
+// =============================================================================
+
+/// Specific LLM provider error codes
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum LlmErrorCode {
+    /// 429 - Too many requests
+    RateLimit,
+    /// Context window exceeded
+    ContextOverflow,
+    /// Content blocked by safety filter
+    ContentFiltered,
+    /// Malformed request
+    InvalidRequest,
+    /// Authentication/authorization failed
+    AuthFailed,
+    /// Model not available
+    ModelUnavailable,
+    /// Generic provider error
+    ProviderError,
+}
+
+impl LlmErrorCode {
+    /// Check if this error code is typically retryable
+    pub fn is_retryable(&self) -> bool {
+        matches!(
+            self,
+            Self::RateLimit | Self::ModelUnavailable | Self::ProviderError
+        )
+    }
+}
+
+impl std::fmt::Display for LlmErrorCode {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::RateLimit => write!(f, "rate_limit"),
+            Self::ContextOverflow => write!(f, "context_overflow"),
+            Self::ContentFiltered => write!(f, "content_filtered"),
+            Self::InvalidRequest => write!(f, "invalid_request"),
+            Self::AuthFailed => write!(f, "auth_failed"),
+            Self::ModelUnavailable => write!(f, "model_unavailable"),
+            Self::ProviderError => write!(f, "provider_error"),
+        }
+    }
+}
+
+// =============================================================================
+// Tool Error Codes
+// =============================================================================
+
+/// Specific tool error codes
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ToolErrorCode {
+    /// Tool not registered
+    NotFound,
+    /// Tool not allowed by policy
+    PermissionDenied,
+    /// Invalid tool arguments
+    InvalidInput,
+    /// Tool crashed or returned error
+    ExecutionFailed,
+    /// Tool execution timed out
+    Timeout,
+    /// Tool returned invalid output
+    OutputInvalid,
+}
+
+impl ToolErrorCode {
+    /// Check if this error code is typically retryable
+    pub fn is_retryable(&self) -> bool {
+        matches!(self, Self::Timeout | Self::ExecutionFailed)
+    }
+}
+
+impl std::fmt::Display for ToolErrorCode {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::NotFound => write!(f, "not_found"),
+            Self::PermissionDenied => write!(f, "permission_denied"),
+            Self::InvalidInput => write!(f, "invalid_input"),
+            Self::ExecutionFailed => write!(f, "execution_failed"),
+            Self::Timeout => write!(f, "timeout"),
+            Self::OutputInvalid => write!(f, "output_invalid"),
+        }
+    }
+}
+
+// =============================================================================
+// Execution Error
+// =============================================================================
+
+/// The primary error type for all execution failures
+///
+/// This structured error enables:
+/// 1. Deterministic retry decisions
+/// 2. Accurate billing (distinguishes user errors from system errors)
+/// 3. Compliance narratives (full audit trail)
+/// 4. HTTP/gRPC status code mapping
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ExecutionError {
+    /// High-level error category
+    pub category: ExecutionErrorCategory,
+
+    /// Human-readable error message
+    pub message: String,
+
+    /// Retry policy for this error
+    pub retry_policy: RetryPolicy,
+
+    /// Specific error code within the category
+    pub code: Option<String>,
+
+    /// Attempt number (1-indexed, for tracking retries)
+    pub attempt: u32,
+
+    /// Step ID where the error occurred
+    pub step_id: Option<StepId>,
+
+    /// Provider name (for LLM/Tool errors)
+    pub provider: Option<String>,
+
+    /// HTTP status code (if applicable)
+    pub http_status: Option<u16>,
+
+    /// Additional structured details
+    pub details: Option<serde_json::Value>,
+
+    /// Timestamp when error occurred (milliseconds since epoch)
+    pub occurred_at: i64,
+}
+
+impl ExecutionError {
+    /// Create a new ExecutionError with default retry policy for the category
+    pub fn new(category: ExecutionErrorCategory, message: impl Into<String>) -> Self {
+        Self {
+            category,
+            message: message.into(),
+            retry_policy: category.default_retry_policy(),
+            code: None,
+            attempt: 1,
+            step_id: None,
+            provider: None,
+            http_status: None,
+            details: None,
+            occurred_at: chrono::Utc::now().timestamp_millis(),
+        }
+    }
+
+    // Builder methods
+
+    /// Set the error code
+    pub fn with_code(mut self, code: impl Into<String>) -> Self {
+        self.code = Some(code.into());
+        self
+    }
+
+    /// Set the attempt number
+    pub fn with_attempt(mut self, attempt: u32) -> Self {
+        self.attempt = attempt;
+        self
+    }
+
+    /// Set the step ID
+    pub fn with_step_id(mut self, step_id: StepId) -> Self {
+        self.step_id = Some(step_id);
+        self
+    }
+
+    /// Set the provider name
+    pub fn with_provider(mut self, provider: impl Into<String>) -> Self {
+        self.provider = Some(provider.into());
+        self
+    }
+
+    /// Set the HTTP status code
+    pub fn with_http_status(mut self, status: u16) -> Self {
+        self.http_status = Some(status);
+        self
+    }
+
+    /// Set additional details
+    pub fn with_details(mut self, details: serde_json::Value) -> Self {
+        self.details = Some(details);
+        self
+    }
+
+    /// Override the retry policy
+    pub fn with_retry_policy(mut self, policy: RetryPolicy) -> Self {
+        self.retry_policy = policy;
+        self
+    }
+
+    // Convenience constructors
+
+    /// Create an LLM error
+    pub fn llm(code: LlmErrorCode, message: impl Into<String>) -> Self {
+        Self::new(ExecutionErrorCategory::LlmError, message)
+            .with_code(code.to_string())
+    }
+
+    /// Create a tool error
+    pub fn tool(code: ToolErrorCode, message: impl Into<String>) -> Self {
+        Self::new(ExecutionErrorCategory::ToolError, message)
+            .with_code(code.to_string())
+    }
+
+    /// Create a policy violation error
+    pub fn policy_violation(message: impl Into<String>) -> Self {
+        Self::new(ExecutionErrorCategory::PolicyViolation, message)
+    }
+
+    /// Create a timeout error
+    pub fn timeout(message: impl Into<String>) -> Self {
+        Self::new(ExecutionErrorCategory::Timeout, message)
+    }
+
+    /// Create a quota exceeded error
+    pub fn quota_exceeded(message: impl Into<String>) -> Self {
+        Self::new(ExecutionErrorCategory::QuotaExceeded, message)
+    }
+
+    /// Create a kernel internal error
+    pub fn kernel_internal(message: impl Into<String>) -> Self {
+        Self::new(ExecutionErrorCategory::KernelInternal, message)
+    }
+
+    /// Create a validation error
+    pub fn validation(message: impl Into<String>) -> Self {
+        Self::new(ExecutionErrorCategory::ValidationError, message)
+    }
+
+    /// Create a network error
+    pub fn network(message: impl Into<String>) -> Self {
+        Self::new(ExecutionErrorCategory::NetworkError, message)
+    }
+
+    // Query methods
+
+    /// Check if this error is retryable
+    pub fn is_retryable(&self) -> bool {
+        self.retry_policy.retryable
+    }
+
+    /// Check if this error is fatal (will never be retried)
+    pub fn is_fatal(&self) -> bool {
+        self.category.is_fatal()
+    }
+
+    /// Check if a retry should be attempted
+    pub fn should_retry(&self) -> bool {
+        self.retry_policy.should_retry(self.attempt)
+    }
+
+    /// Get the delay before the next retry attempt
+    pub fn retry_delay(&self) -> Duration {
+        self.retry_policy.delay_for_attempt(self.attempt)
+    }
+
+    /// Create a new error for the next retry attempt
+    pub fn next_attempt(mut self) -> Self {
+        self.attempt += 1;
+        self.occurred_at = chrono::Utc::now().timestamp_millis();
+        self
+    }
+
+    /// Map to HTTP status code
+    pub fn to_http_status(&self) -> u16 {
+        if let Some(status) = self.http_status {
+            return status;
+        }
+
+        match self.category {
+            ExecutionErrorCategory::LlmError => 502, // Bad Gateway
+            ExecutionErrorCategory::ToolError => 500, // Internal Server Error
+            ExecutionErrorCategory::PolicyViolation => 403, // Forbidden
+            ExecutionErrorCategory::Timeout => 504, // Gateway Timeout
+            ExecutionErrorCategory::QuotaExceeded => 429, // Too Many Requests
+            ExecutionErrorCategory::KernelInternal => 500, // Internal Server Error
+            ExecutionErrorCategory::ValidationError => 400, // Bad Request
+            ExecutionErrorCategory::NetworkError => 503, // Service Unavailable
+        }
+    }
+}
+
+impl std::fmt::Display for ExecutionError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "[{}] {}", self.category, self.message)?;
+        if let Some(code) = &self.code {
+            write!(f, " ({})", code)?;
+        }
+        if self.attempt > 1 {
+            write!(f, " [attempt {}]", self.attempt)?;
+        }
+        Ok(())
+    }
+}
+
+impl std::error::Error for ExecutionError {}
+
+// Implement From for common error types
+
+impl From<reqwest::Error> for ExecutionError {
+    fn from(err: reqwest::Error) -> Self {
+        if err.is_timeout() {
+            Self::timeout(format!("HTTP request timed out: {}", err))
+        } else if err.is_connect() {
+            Self::network(format!("Connection failed: {}", err))
+        } else if err.is_status() {
+            let status = err.status().map(|s| s.as_u16()).unwrap_or(500);
+            Self::network(format!("HTTP error: {}", err))
+                .with_http_status(status)
+        } else {
+            Self::network(format!("HTTP error: {}", err))
+        }
+    }
+}
+
+impl From<serde_json::Error> for ExecutionError {
+    fn from(err: serde_json::Error) -> Self {
+        Self::validation(format!("JSON error: {}", err))
+    }
+}
+
+impl From<std::io::Error> for ExecutionError {
+    fn from(err: std::io::Error) -> Self {
+        match err.kind() {
+            std::io::ErrorKind::TimedOut => Self::timeout(format!("IO timeout: {}", err)),
+            std::io::ErrorKind::ConnectionRefused
+            | std::io::ErrorKind::ConnectionReset
+            | std::io::ErrorKind::ConnectionAborted => {
+                Self::network(format!("Connection error: {}", err))
+            }
+            _ => Self::kernel_internal(format!("IO error: {}", err)),
+        }
+    }
+}
+
+// =============================================================================
+// Serde helpers for Duration
+// =============================================================================
+
+mod duration_millis {
+    use serde::{Deserialize, Deserializer, Serializer};
+    use std::time::Duration;
+
+    pub fn serialize<S>(duration: &Duration, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        serializer.serialize_u64(duration.as_millis() as u64)
+    }
+
+    pub fn deserialize<'de, D>(deserializer: D) -> Result<Duration, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let millis = u64::deserialize(deserializer)?;
+        Ok(Duration::from_millis(millis))
+    }
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_error_categories_fatality() {
+        assert!(ExecutionErrorCategory::PolicyViolation.is_fatal());
+        assert!(ExecutionErrorCategory::QuotaExceeded.is_fatal());
+        assert!(ExecutionErrorCategory::KernelInternal.is_fatal());
+        assert!(ExecutionErrorCategory::ValidationError.is_fatal());
+
+        assert!(!ExecutionErrorCategory::LlmError.is_fatal());
+        assert!(!ExecutionErrorCategory::ToolError.is_fatal());
+        assert!(!ExecutionErrorCategory::Timeout.is_fatal());
+        assert!(!ExecutionErrorCategory::NetworkError.is_fatal());
+    }
+
+    #[test]
+    fn test_default_retry_policies() {
+        let llm_policy = ExecutionErrorCategory::LlmError.default_retry_policy();
+        assert!(llm_policy.retryable);
+        assert_eq!(llm_policy.max_retries, 3);
+        assert_eq!(llm_policy.backoff_strategy, BackoffStrategy::Exponential);
+
+        let fatal_policy = ExecutionErrorCategory::PolicyViolation.default_retry_policy();
+        assert!(!fatal_policy.retryable);
+        assert_eq!(fatal_policy.max_retries, 0);
+    }
+
+    #[test]
+    fn test_exponential_backoff() {
+        let strategy = BackoffStrategy::Exponential;
+        let base = Duration::from_millis(1000);
+        let max = Duration::from_millis(30000);
+
+        assert_eq!(strategy.calculate_delay(base, 1, max), Duration::from_millis(1000));
+        assert_eq!(strategy.calculate_delay(base, 2, max), Duration::from_millis(2000));
+        assert_eq!(strategy.calculate_delay(base, 3, max), Duration::from_millis(4000));
+        assert_eq!(strategy.calculate_delay(base, 4, max), Duration::from_millis(8000));
+        assert_eq!(strategy.calculate_delay(base, 5, max), Duration::from_millis(16000));
+        // Should cap at max
+        assert_eq!(strategy.calculate_delay(base, 6, max), Duration::from_millis(30000));
+    }
+
+    #[test]
+    fn test_execution_error_creation() {
+        let error = ExecutionError::llm(LlmErrorCode::RateLimit, "Too many requests")
+            .with_provider("azure")
+            .with_http_status(429);
+
+        assert_eq!(error.category, ExecutionErrorCategory::LlmError);
+        assert_eq!(error.code, Some("rate_limit".to_string()));
+        assert_eq!(error.provider, Some("azure".to_string()));
+        assert_eq!(error.http_status, Some(429));
+        assert!(error.is_retryable());
+        assert!(!error.is_fatal());
+    }
+
+    #[test]
+    fn test_should_retry() {
+        let mut error = ExecutionError::llm(LlmErrorCode::RateLimit, "Rate limited");
+
+        // Default max_retries is 3
+        assert!(error.should_retry()); // attempt 1
+        error = error.next_attempt();
+        assert!(error.should_retry()); // attempt 2
+        error = error.next_attempt();
+        assert!(error.should_retry()); // attempt 3
+        error = error.next_attempt();
+        assert!(!error.should_retry()); // attempt 4 - exceeds max
+    }
+
+    #[test]
+    fn test_fatal_error_never_retries() {
+        let error = ExecutionError::policy_violation("Content blocked");
+
+        assert!(!error.is_retryable());
+        assert!(error.is_fatal());
+        assert!(!error.should_retry());
+    }
+
+    #[test]
+    fn test_http_status_mapping() {
+        assert_eq!(ExecutionError::policy_violation("test").to_http_status(), 403);
+        assert_eq!(ExecutionError::quota_exceeded("test").to_http_status(), 429);
+        assert_eq!(ExecutionError::timeout("test").to_http_status(), 504);
+        assert_eq!(ExecutionError::validation("test").to_http_status(), 400);
+    }
+
+    #[test]
+    fn test_error_serialization() {
+        let error = ExecutionError::llm(LlmErrorCode::RateLimit, "Too many requests")
+            .with_provider("azure");
+
+        let json = serde_json::to_string(&error).unwrap();
+        let parsed: ExecutionError = serde_json::from_str(&json).unwrap();
+
+        assert_eq!(parsed.category, error.category);
+        assert_eq!(parsed.message, error.message);
+        assert_eq!(parsed.code, error.code);
+        assert_eq!(parsed.provider, error.provider);
+    }
+
+    // =========================================================================
+    // ExecutionErrorCategory Tests
+    // =========================================================================
+
+    #[test]
+    fn test_error_category_display() {
+        assert_eq!(format!("{}", ExecutionErrorCategory::LlmError), "LlmError");
+        assert_eq!(format!("{}", ExecutionErrorCategory::ToolError), "ToolError");
+        assert_eq!(format!("{}", ExecutionErrorCategory::PolicyViolation), "PolicyViolation");
+        assert_eq!(format!("{}", ExecutionErrorCategory::Timeout), "Timeout");
+        assert_eq!(format!("{}", ExecutionErrorCategory::QuotaExceeded), "QuotaExceeded");
+        assert_eq!(format!("{}", ExecutionErrorCategory::KernelInternal), "KernelInternal");
+        assert_eq!(format!("{}", ExecutionErrorCategory::ValidationError), "ValidationError");
+        assert_eq!(format!("{}", ExecutionErrorCategory::NetworkError), "NetworkError");
+    }
+
+    #[test]
+    fn test_error_category_serde() {
+        let categories = vec![
+            ExecutionErrorCategory::LlmError,
+            ExecutionErrorCategory::ToolError,
+            ExecutionErrorCategory::PolicyViolation,
+            ExecutionErrorCategory::Timeout,
+            ExecutionErrorCategory::QuotaExceeded,
+            ExecutionErrorCategory::KernelInternal,
+            ExecutionErrorCategory::ValidationError,
+            ExecutionErrorCategory::NetworkError,
+        ];
+
+        for cat in categories {
+            let json = serde_json::to_string(&cat).unwrap();
+            let parsed: ExecutionErrorCategory = serde_json::from_str(&json).unwrap();
+            assert_eq!(cat, parsed);
+        }
+    }
+
+    // =========================================================================
+    // BackoffStrategy Tests
+    // =========================================================================
+
+    #[test]
+    fn test_backoff_none() {
+        let strategy = BackoffStrategy::None;
+        let base = Duration::from_millis(1000);
+        let max = Duration::from_millis(30000);
+
+        assert_eq!(strategy.calculate_delay(base, 1, max), Duration::ZERO);
+        assert_eq!(strategy.calculate_delay(base, 5, max), Duration::ZERO);
+    }
+
+    #[test]
+    fn test_backoff_constant() {
+        let strategy = BackoffStrategy::Constant;
+        let base = Duration::from_millis(500);
+        let max = Duration::from_millis(10000);
+
+        assert_eq!(strategy.calculate_delay(base, 1, max), Duration::from_millis(500));
+        assert_eq!(strategy.calculate_delay(base, 5, max), Duration::from_millis(500));
+    }
+
+    #[test]
+    fn test_backoff_linear() {
+        let strategy = BackoffStrategy::Linear;
+        let base = Duration::from_millis(1000);
+        let max = Duration::from_millis(30000);
+
+        assert_eq!(strategy.calculate_delay(base, 1, max), Duration::from_millis(1000));
+        assert_eq!(strategy.calculate_delay(base, 2, max), Duration::from_millis(2000));
+        assert_eq!(strategy.calculate_delay(base, 3, max), Duration::from_millis(3000));
+        // Should cap at max
+        assert_eq!(strategy.calculate_delay(base, 100, max), Duration::from_millis(30000));
+    }
+
+    #[test]
+    fn test_backoff_default() {
+        assert_eq!(BackoffStrategy::default(), BackoffStrategy::None);
+    }
+
+    #[test]
+    fn test_backoff_serde() {
+        let strategies = vec![
+            BackoffStrategy::None,
+            BackoffStrategy::Constant,
+            BackoffStrategy::Linear,
+            BackoffStrategy::Exponential,
+        ];
+
+        for strat in strategies {
+            let json = serde_json::to_string(&strat).unwrap();
+            let parsed: BackoffStrategy = serde_json::from_str(&json).unwrap();
+            assert_eq!(strat, parsed);
+        }
+    }
+
+    // =========================================================================
+    // RetryPolicy Tests
+    // =========================================================================
+
+    #[test]
+    fn test_retry_policy_fatal() {
+        let policy = RetryPolicy::fatal();
+        assert!(!policy.retryable);
+        assert_eq!(policy.max_retries, 0);
+        assert!(!policy.should_retry(1));
+    }
+
+    #[test]
+    fn test_retry_policy_retryable() {
+        let policy = RetryPolicy::retryable(5);
+        assert!(policy.retryable);
+        assert_eq!(policy.max_retries, 5);
+        assert_eq!(policy.backoff_strategy, BackoffStrategy::Exponential);
+    }
+
+    #[test]
+    fn test_retry_policy_delay_for_attempt() {
+        let policy = RetryPolicy {
+            retryable: true,
+            max_retries: 3,
+            backoff_strategy: BackoffStrategy::Constant,
+            base_delay: Duration::from_millis(500),
+            max_delay: Duration::from_millis(5000),
+            requires_idempotency_key: false,
+        };
+
+        assert_eq!(policy.delay_for_attempt(1), Duration::from_millis(500));
+        assert_eq!(policy.delay_for_attempt(2), Duration::from_millis(500));
+    }
+
+    #[test]
+    fn test_retry_policy_should_retry() {
+        let policy = RetryPolicy::retryable(3);
+        assert!(policy.should_retry(1));
+        assert!(policy.should_retry(2));
+        assert!(policy.should_retry(3));
+        assert!(!policy.should_retry(4));
+    }
+
+    #[test]
+    fn test_retry_policy_default() {
+        let policy = RetryPolicy::default();
+        assert!(!policy.retryable);
+        assert_eq!(policy.max_retries, 0);
+    }
+
+    #[test]
+    fn test_retry_policy_serde() {
+        let policy = RetryPolicy::retryable(3);
+        let json = serde_json::to_string(&policy).unwrap();
+        let parsed: RetryPolicy = serde_json::from_str(&json).unwrap();
+        assert_eq!(policy.retryable, parsed.retryable);
+        assert_eq!(policy.max_retries, parsed.max_retries);
+    }
+
+    // =========================================================================
+    // LlmErrorCode Tests
+    // =========================================================================
+
+    #[test]
+    fn test_llm_error_code_retryable() {
+        assert!(LlmErrorCode::RateLimit.is_retryable());
+        assert!(LlmErrorCode::ModelUnavailable.is_retryable());
+        assert!(LlmErrorCode::ProviderError.is_retryable());
+
+        assert!(!LlmErrorCode::ContextOverflow.is_retryable());
+        assert!(!LlmErrorCode::ContentFiltered.is_retryable());
+        assert!(!LlmErrorCode::InvalidRequest.is_retryable());
+        assert!(!LlmErrorCode::AuthFailed.is_retryable());
+    }
+
+    #[test]
+    fn test_llm_error_code_display() {
+        assert_eq!(format!("{}", LlmErrorCode::RateLimit), "rate_limit");
+        assert_eq!(format!("{}", LlmErrorCode::ContextOverflow), "context_overflow");
+        assert_eq!(format!("{}", LlmErrorCode::ContentFiltered), "content_filtered");
+        assert_eq!(format!("{}", LlmErrorCode::InvalidRequest), "invalid_request");
+        assert_eq!(format!("{}", LlmErrorCode::AuthFailed), "auth_failed");
+        assert_eq!(format!("{}", LlmErrorCode::ModelUnavailable), "model_unavailable");
+        assert_eq!(format!("{}", LlmErrorCode::ProviderError), "provider_error");
+    }
+
+    #[test]
+    fn test_llm_error_code_serde() {
+        let codes = vec![
+            LlmErrorCode::RateLimit,
+            LlmErrorCode::ContextOverflow,
+            LlmErrorCode::ContentFiltered,
+            LlmErrorCode::InvalidRequest,
+            LlmErrorCode::AuthFailed,
+            LlmErrorCode::ModelUnavailable,
+            LlmErrorCode::ProviderError,
+        ];
+
+        for code in codes {
+            let json = serde_json::to_string(&code).unwrap();
+            let parsed: LlmErrorCode = serde_json::from_str(&json).unwrap();
+            assert_eq!(code, parsed);
+        }
+    }
+
+    // =========================================================================
+    // ToolErrorCode Tests
+    // =========================================================================
+
+    #[test]
+    fn test_tool_error_code_retryable() {
+        assert!(ToolErrorCode::Timeout.is_retryable());
+        assert!(ToolErrorCode::ExecutionFailed.is_retryable());
+
+        assert!(!ToolErrorCode::NotFound.is_retryable());
+        assert!(!ToolErrorCode::PermissionDenied.is_retryable());
+        assert!(!ToolErrorCode::InvalidInput.is_retryable());
+        assert!(!ToolErrorCode::OutputInvalid.is_retryable());
+    }
+
+    #[test]
+    fn test_tool_error_code_display() {
+        assert_eq!(format!("{}", ToolErrorCode::NotFound), "not_found");
+        assert_eq!(format!("{}", ToolErrorCode::PermissionDenied), "permission_denied");
+        assert_eq!(format!("{}", ToolErrorCode::InvalidInput), "invalid_input");
+        assert_eq!(format!("{}", ToolErrorCode::ExecutionFailed), "execution_failed");
+        assert_eq!(format!("{}", ToolErrorCode::Timeout), "timeout");
+        assert_eq!(format!("{}", ToolErrorCode::OutputInvalid), "output_invalid");
+    }
+
+    #[test]
+    fn test_tool_error_code_serde() {
+        let codes = vec![
+            ToolErrorCode::NotFound,
+            ToolErrorCode::PermissionDenied,
+            ToolErrorCode::InvalidInput,
+            ToolErrorCode::ExecutionFailed,
+            ToolErrorCode::Timeout,
+            ToolErrorCode::OutputInvalid,
+        ];
+
+        for code in codes {
+            let json = serde_json::to_string(&code).unwrap();
+            let parsed: ToolErrorCode = serde_json::from_str(&json).unwrap();
+            assert_eq!(code, parsed);
+        }
+    }
+
+    // =========================================================================
+    // ExecutionError Tests
+    // =========================================================================
+
+    #[test]
+    fn test_execution_error_new() {
+        let error = ExecutionError::new(ExecutionErrorCategory::LlmError, "Test message");
+        assert_eq!(error.category, ExecutionErrorCategory::LlmError);
+        assert_eq!(error.message, "Test message");
+        assert_eq!(error.attempt, 1);
+        assert!(error.retry_policy.retryable);
+    }
+
+    #[test]
+    fn test_execution_error_with_code() {
+        let error = ExecutionError::new(ExecutionErrorCategory::ToolError, "Test")
+            .with_code("custom_code");
+        assert_eq!(error.code, Some("custom_code".to_string()));
+    }
+
+    #[test]
+    fn test_execution_error_with_attempt() {
+        let error = ExecutionError::new(ExecutionErrorCategory::LlmError, "Test")
+            .with_attempt(3);
+        assert_eq!(error.attempt, 3);
+    }
+
+    #[test]
+    fn test_execution_error_with_step_id() {
+        let step_id = StepId::from_string("step_test");
+        let error = ExecutionError::new(ExecutionErrorCategory::ToolError, "Test")
+            .with_step_id(step_id.clone());
+        assert_eq!(error.step_id.unwrap().as_str(), "step_test");
+    }
+
+    #[test]
+    fn test_execution_error_with_provider() {
+        let error = ExecutionError::llm(LlmErrorCode::RateLimit, "Test")
+            .with_provider("openai");
+        assert_eq!(error.provider, Some("openai".to_string()));
+    }
+
+    #[test]
+    fn test_execution_error_with_details() {
+        let details = serde_json::json!({"key": "value"});
+        let error = ExecutionError::new(ExecutionErrorCategory::ToolError, "Test")
+            .with_details(details.clone());
+        assert_eq!(error.details, Some(details));
+    }
+
+    #[test]
+    fn test_execution_error_with_retry_policy() {
+        let policy = RetryPolicy::retryable(10);
+        let error = ExecutionError::new(ExecutionErrorCategory::ToolError, "Test")
+            .with_retry_policy(policy.clone());
+        assert_eq!(error.retry_policy.max_retries, 10);
+    }
+
+    #[test]
+    fn test_execution_error_convenience_constructors() {
+        let llm = ExecutionError::llm(LlmErrorCode::RateLimit, "LLM error");
+        assert_eq!(llm.category, ExecutionErrorCategory::LlmError);
+
+        let tool = ExecutionError::tool(ToolErrorCode::NotFound, "Tool error");
+        assert_eq!(tool.category, ExecutionErrorCategory::ToolError);
+
+        let policy = ExecutionError::policy_violation("Policy error");
+        assert_eq!(policy.category, ExecutionErrorCategory::PolicyViolation);
+
+        let timeout = ExecutionError::timeout("Timeout error");
+        assert_eq!(timeout.category, ExecutionErrorCategory::Timeout);
+
+        let quota = ExecutionError::quota_exceeded("Quota error");
+        assert_eq!(quota.category, ExecutionErrorCategory::QuotaExceeded);
+
+        let kernel = ExecutionError::kernel_internal("Kernel error");
+        assert_eq!(kernel.category, ExecutionErrorCategory::KernelInternal);
+
+        let validation = ExecutionError::validation("Validation error");
+        assert_eq!(validation.category, ExecutionErrorCategory::ValidationError);
+
+        let network = ExecutionError::network("Network error");
+        assert_eq!(network.category, ExecutionErrorCategory::NetworkError);
+    }
+
+    #[test]
+    fn test_execution_error_is_retryable() {
+        assert!(ExecutionError::llm(LlmErrorCode::RateLimit, "").is_retryable());
+        assert!(ExecutionError::tool(ToolErrorCode::Timeout, "").is_retryable());
+        assert!(ExecutionError::timeout("").is_retryable());
+        assert!(ExecutionError::network("").is_retryable());
+
+        assert!(!ExecutionError::policy_violation("").is_retryable());
+        assert!(!ExecutionError::quota_exceeded("").is_retryable());
+        assert!(!ExecutionError::kernel_internal("").is_retryable());
+        assert!(!ExecutionError::validation("").is_retryable());
+    }
+
+    #[test]
+    fn test_execution_error_is_fatal() {
+        assert!(!ExecutionError::llm(LlmErrorCode::RateLimit, "").is_fatal());
+        assert!(!ExecutionError::timeout("").is_fatal());
+
+        assert!(ExecutionError::policy_violation("").is_fatal());
+        assert!(ExecutionError::quota_exceeded("").is_fatal());
+        assert!(ExecutionError::kernel_internal("").is_fatal());
+        assert!(ExecutionError::validation("").is_fatal());
+    }
+
+    #[test]
+    fn test_execution_error_retry_delay() {
+        let error = ExecutionError::new(ExecutionErrorCategory::LlmError, "Test");
+        let delay = error.retry_delay();
+        assert!(delay > Duration::ZERO);
+    }
+
+    #[test]
+    fn test_execution_error_next_attempt() {
+        let error = ExecutionError::llm(LlmErrorCode::RateLimit, "Test");
+        assert_eq!(error.attempt, 1);
+
+        let error2 = error.next_attempt();
+        assert_eq!(error2.attempt, 2);
+
+        let error3 = error2.next_attempt();
+        assert_eq!(error3.attempt, 3);
+    }
+
+    #[test]
+    fn test_execution_error_to_http_status_all_categories() {
+        assert_eq!(ExecutionError::llm(LlmErrorCode::RateLimit, "").to_http_status(), 502);
+        assert_eq!(ExecutionError::tool(ToolErrorCode::NotFound, "").to_http_status(), 500);
+        assert_eq!(ExecutionError::policy_violation("").to_http_status(), 403);
+        assert_eq!(ExecutionError::timeout("").to_http_status(), 504);
+        assert_eq!(ExecutionError::quota_exceeded("").to_http_status(), 429);
+        assert_eq!(ExecutionError::kernel_internal("").to_http_status(), 500);
+        assert_eq!(ExecutionError::validation("").to_http_status(), 400);
+        assert_eq!(ExecutionError::network("").to_http_status(), 503);
+    }
+
+    #[test]
+    fn test_execution_error_to_http_status_override() {
+        let error = ExecutionError::network("Test").with_http_status(418);
+        assert_eq!(error.to_http_status(), 418);
+    }
+
+    #[test]
+    fn test_execution_error_display() {
+        let error = ExecutionError::llm(LlmErrorCode::RateLimit, "Too many requests");
+        let display = format!("{}", error);
+        assert!(display.contains("LlmError"));
+        assert!(display.contains("Too many requests"));
+        assert!(display.contains("rate_limit"));
+    }
+
+    #[test]
+    fn test_execution_error_display_with_attempt() {
+        let error = ExecutionError::llm(LlmErrorCode::RateLimit, "Test")
+            .with_attempt(3);
+        let display = format!("{}", error);
+        assert!(display.contains("[attempt 3]"));
+    }
+
+    #[test]
+    fn test_execution_error_display_no_attempt_shown_for_first() {
+        let error = ExecutionError::llm(LlmErrorCode::RateLimit, "Test");
+        let display = format!("{}", error);
+        assert!(!display.contains("attempt"));
+    }
+
+    // =========================================================================
+    // From Implementation Tests
+    // =========================================================================
+
+    #[test]
+    fn test_from_serde_json_error() {
+        let json_err = serde_json::from_str::<String>("invalid json").unwrap_err();
+        let error: ExecutionError = json_err.into();
+        assert_eq!(error.category, ExecutionErrorCategory::ValidationError);
+        assert!(error.message.contains("JSON error"));
+    }
+
+    #[test]
+    fn test_from_io_error_timeout() {
+        let io_err = std::io::Error::new(std::io::ErrorKind::TimedOut, "timed out");
+        let error: ExecutionError = io_err.into();
+        assert_eq!(error.category, ExecutionErrorCategory::Timeout);
+    }
+
+    #[test]
+    fn test_from_io_error_connection_refused() {
+        let io_err = std::io::Error::new(std::io::ErrorKind::ConnectionRefused, "refused");
+        let error: ExecutionError = io_err.into();
+        assert_eq!(error.category, ExecutionErrorCategory::NetworkError);
+    }
+
+    #[test]
+    fn test_from_io_error_connection_reset() {
+        let io_err = std::io::Error::new(std::io::ErrorKind::ConnectionReset, "reset");
+        let error: ExecutionError = io_err.into();
+        assert_eq!(error.category, ExecutionErrorCategory::NetworkError);
+    }
+
+    #[test]
+    fn test_from_io_error_connection_aborted() {
+        let io_err = std::io::Error::new(std::io::ErrorKind::ConnectionAborted, "aborted");
+        let error: ExecutionError = io_err.into();
+        assert_eq!(error.category, ExecutionErrorCategory::NetworkError);
+    }
+
+    #[test]
+    fn test_from_io_error_other() {
+        let io_err = std::io::Error::new(std::io::ErrorKind::NotFound, "not found");
+        let error: ExecutionError = io_err.into();
+        assert_eq!(error.category, ExecutionErrorCategory::KernelInternal);
+    }
+
+    // =========================================================================
+    // Default Retry Policy Tests
+    // =========================================================================
+
+    #[test]
+    fn test_default_retry_policy_tool_error() {
+        let policy = ExecutionErrorCategory::ToolError.default_retry_policy();
+        assert!(policy.retryable);
+        assert_eq!(policy.max_retries, 2);
+        assert_eq!(policy.backoff_strategy, BackoffStrategy::Constant);
+        assert!(policy.requires_idempotency_key);
+    }
+
+    #[test]
+    fn test_default_retry_policy_timeout() {
+        let policy = ExecutionErrorCategory::Timeout.default_retry_policy();
+        assert!(policy.retryable);
+        assert_eq!(policy.max_retries, 1);
+        assert!(policy.requires_idempotency_key);
+    }
+
+    #[test]
+    fn test_default_retry_policy_network() {
+        let policy = ExecutionErrorCategory::NetworkError.default_retry_policy();
+        assert!(policy.retryable);
+        assert_eq!(policy.max_retries, 3);
+        assert_eq!(policy.backoff_strategy, BackoffStrategy::Exponential);
+        assert!(policy.requires_idempotency_key);
+    }
+}