pe_core/

error.rs

//! Error taxonomy — complete set of errors the library produces.
//! Based on Group 7 of the pre-plan.

use thiserror::Error;

#[derive(Error, Debug, Clone)]
#[non_exhaustive]
pub enum PeError {
    // === Graph errors ===
    #[error("Graph recursion limit reached ({limit} supersteps)")]
    GraphRecursion { limit: u32 },

    #[error("Graph interrupt: {reason}")]
    GraphInterrupt { reason: String },

    #[error("Node interrupt: {reason}")]
    NodeInterrupt { reason: String },

    #[error("Invalid state update: {details}")]
    InvalidUpdate { details: String },

    #[error("Channel '{channel}' was never written")]
    EmptyChannel { channel: String },

    #[error("Invalid graph structure: {details}")]
    GraphValue { details: String },

    #[error("Node '{node}' is unreachable — no path from START")]
    UnreachableNode { node: String },

    #[error("Graph invoked with no input")]
    EmptyInput,

    #[error("Multiple subgraphs conflict: {details}")]
    MultipleSubgraphs { details: String },

    // === Agent errors ===
    #[error("Agent '{agent_id}' not found in registry")]
    AgentNotFound { agent_id: String },

    #[error("Agent '{agent_id}' is unreachable: {reason}")]
    AgentUnreachable { agent_id: String, reason: String },

    #[error("Handoff cycle detected: {path}")]
    HandoffCycle { path: String },

    #[error("Max handoffs ({max}) exceeded")]
    MaxHandoffs { max: u32 },

    // === Boundary errors ===
    #[error("Permission denied: {action}")]
    PermissionDenied { action: String },

    #[error("Tool '{tool}' denied by policy: {reason}")]
    ToolDenied { tool: String, reason: String },

    #[error("Communication with '{target}' blocked by rules")]
    CommunicationBlocked { target: String },

    #[error("Approval denied for '{action}': {reason}")]
    ApprovalDenied { action: String, reason: String },

    #[error("Approval required for '{action}', but no approval resolver is configured")]
    ApprovalRequired { action: String },

    #[error("Guardrail violated: {guardrail} — {details}")]
    GuardrailViolation { guardrail: String, details: String },

    #[error("Write governance violation on '{destination}': {reason}")]
    WriteGovernanceViolation { destination: String, reason: String },

    #[error("Inspection denied for '{root}': {reason}")]
    InspectionDenied { root: String, reason: String },

    #[error("Inspection failed for '{path}': {reason}")]
    InspectionFailed { path: String, reason: String },

    // === Tool errors ===
    #[error("Tool '{tool}' execution failed: {reason}")]
    ToolExecution { tool: String, reason: String },

    #[error("Tool '{tool}' not found in registry")]
    ToolNotFound { tool: String },

    #[error("Tool '{tool}' is already registered")]
    ToolAlreadyRegistered { tool: String },

    // === LLM errors ===
    #[error("LLM provider error: {details}")]
    LlmProvider { details: String },

    /// Authentication/authorization failed (HTTP 401/403). NOT retryable —
    /// a bad API key will never succeed on retry.
    #[error("LLM auth failed: {details}")]
    LlmAuth { details: String },

    /// Rate limited by the provider (HTTP 429). Retryable with backoff.
    #[error("LLM rate limited: {details}")]
    LlmRateLimit { details: String },

    #[error("LLM provider returned no response")]
    LlmEmpty,

    #[error("MockProvider response queue exhausted — add more responses with .respond_with()")]
    MockProviderExhausted,

    #[error("Embedding dimension mismatch: expected {expected}, got {actual}")]
    EmbeddingDimension { expected: usize, actual: usize },

    #[error("Structured output parse failed: {details}")]
    StructuredOutput { details: String },

    // === Storage errors ===
    #[error("Storage error: {details}")]
    Storage { details: String },

    #[error("Checkpoint not found for thread '{thread_id}'")]
    CheckpointNotFound { thread_id: String },

    // === Bus / Negotiation errors ===
    #[error("Bus error: {details}")]
    BusError { details: String },

    #[error("Negotiation failed: {reason}")]
    NegotiationFailed { reason: String },

    #[error("Negotiation interrupted: {reason}")]
    NegotiationInterrupted { reason: String },

    // === Execution errors ===
    #[error("Execution timeout after {seconds:.2}s")]
    Timeout { seconds: f64 },

    #[error("Execution budget exceeded: {budget_type}")]
    BudgetExceeded { budget_type: String },

    // === Agent construction ===
    #[error("Invalid agent: {0}")]
    InvalidAgent(String),

    #[error("Manifest load failed: {0}")]
    ManifestLoad(String),

    #[error("Manifest parse failed: {0}")]
    ManifestParse(String),

    // === Delegation errors ===
    #[error("Cyclic delegation detected: {chain:?} → {attempted}")]
    CyclicDelegation {
        chain: Vec<String>,
        attempted: String,
    },

    // === Resume errors ===
    /// Resume point mismatch between checkpoint and command.
    #[error("Resume point mismatch: expected '{expected}', got '{actual}'")]
    ResumePointMismatch {
        /// The resume point stored in the checkpoint.
        expected: String,
        /// The resume point provided by the caller.
        actual: String,
    },

    /// Node expected human input on resume but none was provided.
    #[error("Missing human input — node expected HumanInput on resume but none was provided")]
    MissingHumanInput,

    // === Matrix errors ===
    #[error("Matrix dimension mismatch: expected {expected}, got {actual}")]
    MatrixDimensionMismatch { expected: usize, actual: usize },

    #[error("Node '{node}' not found in transition matrix")]
    NodeNotFound { node: String },

    #[error("Tensor constraint {constraint} violated: {detail}")]
    ConstraintViolation { constraint: String, detail: String },

    #[error("Tensor composition failed: {reason}")]
    CompositionError { reason: String },

    #[error("Invalid payload: {reason}")]
    InvalidPayload { reason: String },

    // === Cognitive errors ===
    /// Cognitive budget exhausted — lobes consumed all allocated tokens/time.
    #[error("Cognitive budget exhausted for agent '{agent_id}': used {tokens_used}/{limit} tokens")]
    CognitiveBudgetExhausted {
        agent_id: String,
        tokens_used: u32,
        limit: u32,
    },

    /// A lobe vetoed the output — blocks execution.
    #[error("Cognitive veto by lobe '{lobe}' for agent '{agent_id}': {reason}")]
    CognitiveSignalVeto {
        agent_id: String,
        lobe: String,
        reason: String,
    },

    /// A lobe failed to activate or process.
    ///
    /// This is a structural failure (not transient). Transient failures
    /// (e.g., model unavailable) should be reported as [`PeError::LlmProvider`] or
    /// [`PeError::Timeout`] by the lobe itself before returning this error.
    #[error("Lobe activation failed for '{lobe}': {reason}")]
    LobeActivationFailed { lobe: String, reason: String },

    // === Internal ===
    #[error("Internal error: {details}")]
    Internal { details: String },
}

impl PeError {
    /// Whether this error is retryable by a retry policy.
    ///
    /// Transient failures (timeouts, LLM provider errors, tool execution
    /// errors) are retryable. Structural errors (invalid graph, permission
    /// denied, missing input) are not.
    pub fn is_retryable(&self) -> bool {
        matches!(
            self,
            PeError::Timeout { .. }
                | PeError::LlmProvider { .. }
                | PeError::LlmRateLimit { .. }
                | PeError::LlmEmpty
                | PeError::ToolExecution { .. }
                | PeError::Storage { .. }
        )
        // Note: LlmAuth is NOT retryable — bad credentials never succeed on retry
    }

    /// Whether this error represents a transient condition that may resolve later.
    ///
    /// Transient errors are temporary — the same operation might succeed on retry
    /// or after a delay. Permanent errors indicate structural problems that will
    /// never resolve without code/config changes.
    ///
    /// `is_retryable()` is a subset of `is_transient()`: all retryable errors are
    /// transient, but some transient errors (like `BusError`) may not benefit from
    /// immediate retry.
    pub fn is_transient(&self) -> bool {
        matches!(
            self,
            PeError::Timeout { .. }
                | PeError::LlmProvider { .. }
                | PeError::LlmRateLimit { .. }
                | PeError::LlmEmpty
                | PeError::ToolExecution { .. }
                | PeError::Storage { .. }
                | PeError::BusError { .. }
                | PeError::NegotiationFailed { .. }
                | PeError::MockProviderExhausted
        )
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Exhaustive classification of every PeError variant.
    /// If a new variant is added, this function will fail to compile
    /// until updated — ensuring classification stays complete.
    fn classify_all_variants() -> Vec<(PeError, bool, bool)> {
        // (error, expected_transient, expected_retryable)
        vec![
            // Transient + retryable
            (PeError::Timeout { seconds: 30.0 }, true, true),
            (
                PeError::LlmProvider {
                    details: "rate limited".into(),
                },
                true,
                true,
            ),
            (PeError::LlmEmpty, true, true),
            (
                PeError::LlmAuth {
                    details: "invalid api key".into(),
                },
                false, // NOT retryable — bad credentials never succeed
                false, // NOT transient — structural problem
            ),
            (
                PeError::LlmRateLimit {
                    details: "too many requests".into(),
                },
                true, // retryable with backoff
                true, // transient
            ),
            (
                PeError::ToolExecution {
                    tool: "search".into(),
                    reason: "network error".into(),
                },
                true,
                true,
            ),
            (
                PeError::Storage {
                    details: "connection refused".into(),
                },
                true,
                true,
            ),
            // Transient but not immediately retryable
            (
                PeError::BusError {
                    details: "disconnected".into(),
                },
                true,
                false,
            ),
            (
                PeError::NegotiationFailed {
                    reason: "timeout".into(),
                },
                true,
                false,
            ),
            (PeError::MockProviderExhausted, true, false),
            // Permanent (not transient, not retryable)
            (PeError::GraphRecursion { limit: 25 }, false, false),
            (
                PeError::GraphInterrupt {
                    reason: "paused".into(),
                },
                false,
                false,
            ),
            (
                PeError::NodeInterrupt {
                    reason: "paused".into(),
                },
                false,
                false,
            ),
            (
                PeError::InvalidUpdate {
                    details: "bad field".into(),
                },
                false,
                false,
            ),
            (
                PeError::EmptyChannel {
                    channel: "msgs".into(),
                },
                false,
                false,
            ),
            (
                PeError::GraphValue {
                    details: "no edges".into(),
                },
                false,
                false,
            ),
            (
                PeError::UnreachableNode {
                    node: "orphan".into(),
                },
                false,
                false,
            ),
            (PeError::EmptyInput, false, false),
            (
                PeError::MultipleSubgraphs {
                    details: "conflict".into(),
                },
                false,
                false,
            ),
            (
                PeError::AgentNotFound {
                    agent_id: "x".into(),
                },
                false,
                false,
            ),
            (
                PeError::AgentUnreachable {
                    agent_id: "x".into(),
                    reason: "no bus".into(),
                },
                false,
                false,
            ),
            (
                PeError::HandoffCycle {
                    path: "a->b->a".into(),
                },
                false,
                false,
            ),
            (PeError::MaxHandoffs { max: 10 }, false, false),
            (
                PeError::PermissionDenied {
                    action: "write".into(),
                },
                false,
                false,
            ),
            (
                PeError::ToolDenied {
                    tool: "rm".into(),
                    reason: "blocked".into(),
                },
                false,
                false,
            ),
            (
                PeError::CommunicationBlocked {
                    target: "agent-b".into(),
                },
                false,
                false,
            ),
            (
                PeError::ApprovalDenied {
                    action: "tool:shell_exec".into(),
                    reason: "host denied".into(),
                },
                false,
                false,
            ),
            (
                PeError::ApprovalRequired {
                    action: "tool:shell_exec".into(),
                },
                false,
                false,
            ),
            (
                PeError::GuardrailViolation {
                    guardrail: "safety".into(),
                    details: "toxic".into(),
                },
                false,
                false,
            ),
            (
                PeError::WriteGovernanceViolation {
                    destination: "db".into(),
                    reason: "denied".into(),
                },
                false,
                false,
            ),
            (
                PeError::InspectionDenied {
                    root: ".".into(),
                    reason: "blocked".into(),
                },
                false,
                false,
            ),
            (
                PeError::InspectionFailed {
                    path: "missing.txt".into(),
                    reason: "not found".into(),
                },
                false,
                false,
            ),
            (
                PeError::ToolNotFound {
                    tool: "missing".into(),
                },
                false,
                false,
            ),
            (
                PeError::ToolAlreadyRegistered {
                    tool: "search".into(),
                },
                false,
                false,
            ),
            (
                PeError::EmbeddingDimension {
                    expected: 768,
                    actual: 512,
                },
                false,
                false,
            ),
            (
                PeError::StructuredOutput {
                    details: "parse fail".into(),
                },
                false,
                false,
            ),
            (
                PeError::CheckpointNotFound {
                    thread_id: "t1".into(),
                },
                false,
                false,
            ),
            (
                PeError::NegotiationInterrupted {
                    reason: "timeout".into(),
                },
                false,
                false,
            ),
            (
                PeError::BudgetExceeded {
                    budget_type: "tokens".into(),
                },
                false,
                false,
            ),
            (PeError::InvalidAgent("bad config".into()), false, false),
            (PeError::ManifestLoad("not found".into()), false, false),
            (PeError::ManifestParse("invalid yaml".into()), false, false),
            (
                PeError::CyclicDelegation {
                    chain: vec!["a".into(), "b".into()],
                    attempted: "a".into(),
                },
                false,
                false,
            ),
            (
                PeError::ResumePointMismatch {
                    expected: "x".into(),
                    actual: "y".into(),
                },
                false,
                false,
            ),
            (PeError::MissingHumanInput, false, false),
            (
                PeError::MatrixDimensionMismatch {
                    expected: 3,
                    actual: 5,
                },
                false,
                false,
            ),
            (
                PeError::NodeNotFound {
                    node: "ghost".into(),
                },
                false,
                false,
            ),
            (
                PeError::ConstraintViolation {
                    constraint: "C4".into(),
                    detail: "sum > 1".into(),
                },
                false,
                false,
            ),
            (
                PeError::CompositionError {
                    reason: "incompatible".into(),
                },
                false,
                false,
            ),
            (
                PeError::InvalidPayload {
                    reason: "negative probability".into(),
                },
                false,
                false,
            ),
            (
                PeError::CognitiveBudgetExhausted {
                    agent_id: "agent-1".into(),
                    tokens_used: 2000,
                    limit: 2000,
                },
                false,
                false,
            ),
            (
                PeError::CognitiveSignalVeto {
                    agent_id: "agent-1".into(),
                    lobe: "safety".into(),
                    reason: "dangerous".into(),
                },
                false,
                false,
            ),
            (
                PeError::LobeActivationFailed {
                    lobe: "critic".into(),
                    reason: "model unavailable".into(),
                },
                false,
                false,
            ),
            (
                PeError::Internal {
                    details: "bug".into(),
                },
                false,
                false,
            ),
        ]
    }

    #[test]
    fn test_is_transient_exhaustive() {
        for (error, expected_transient, _) in classify_all_variants() {
            assert_eq!(
                error.is_transient(),
                expected_transient,
                "Wrong is_transient() for: {error}"
            );
        }
    }

    #[test]
    fn test_is_retryable_exhaustive() {
        for (error, _, expected_retryable) in classify_all_variants() {
            assert_eq!(
                error.is_retryable(),
                expected_retryable,
                "Wrong is_retryable() for: {error}"
            );
        }
    }

    #[test]
    fn test_retryable_is_subset_of_transient() {
        for (error, _, _) in classify_all_variants() {
            if error.is_retryable() {
                assert!(
                    error.is_transient(),
                    "Retryable error should also be transient: {error}"
                );
            }
        }
    }

    #[test]
    fn test_transient_errors_are_retryable_or_bus() {
        let transient = vec![
            PeError::Timeout { seconds: 30.0 },
            PeError::LlmProvider {
                details: "500".into(),
            },
            PeError::LlmEmpty,
            PeError::ToolExecution {
                tool: "api".into(),
                reason: "timeout".into(),
            },
            PeError::Storage {
                details: "conn reset".into(),
            },
        ];
        for err in transient {
            assert!(err.is_transient(), "Expected transient: {err}");
            assert!(err.is_retryable(), "Expected retryable: {err}");
        }
    }

    #[test]
    fn test_permanent_errors_are_not_retryable() {
        let permanent = vec![
            PeError::GraphRecursion { limit: 25 },
            PeError::AgentNotFound {
                agent_id: "x".into(),
            },
            PeError::PermissionDenied {
                action: "write".into(),
            },
            PeError::Internal {
                details: "bug".into(),
            },
        ];
        for err in permanent {
            assert!(!err.is_transient(), "Expected permanent: {err}");
            assert!(!err.is_retryable(), "Expected not retryable: {err}");
        }
    }
}