//! Engine 模块统一错误类型。

use thiserror::Error;

use crate::agent::error::AgentError;
use crate::memory::error::MemoryError;

/// Engine 模块错误枚举。
///
/// - `Session*` / `Checkpoint*`：engine 层独有的错误变体
/// - `Memory`：透传 `MemoryError`，与项目既有 `AgentError` 风格一致（对比 `AgentError::Memory`）
/// - `Serialization`：快照 JSON 解析失败
/// - `Agent`：透传 `AgentError`（后续 Stage 5/6 集成时需要）
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum EngineError {
    /// 指定 session_id 不存在。
    /// 适用场景：`get()` 内存未命中、`create_child()` parent 不存在、
    /// `recover()` 存储中查不到。
    ///
    /// **不适用** `destroy()`：`destroy()` 对不存在的 session 静默返回 `Ok(())`
    /// （幂等删除语义，调用方无需先检查）。
    #[error("Session not found: {0}")]
    SessionNotFound(String),

    /// 创建 session 时 ID 已存在（自动生成 UUID 时通常不会触发；当前主要在重复 `recover` 已存在 ID 时使用）。
    #[error("Session already exists: {0}")]
    SessionAlreadyExists(String),

    /// 指定 ckpt_id 不存在。
    #[error("Checkpoint not found: {0}")]
    CheckpointNotFound(String),

    /// 存储错误（透传 `MemoryError`）。
    /// Checkpointer 和 SessionManager 的所有 `MemoryStore` 操作通过此变体传播错误。
    #[error("存储错误: {0}")]
    Memory(#[from] MemoryError),

    /// 序列化/反序列化失败（serde_json / snapshot 格式错误）。
    #[error("序列化错误: {0}")]
    Serialization(String),

    /// Agent 错误（透传 `AgentError`，供后续 Stage 5/6 的 `recover`/`replace` 等集成入口使用）。
    #[error("Agent 错误: {0}")]
    Agent(#[from] AgentError),

    /// 子代理调度失败（`dispatch` 过程中遇到不可恢复错误，子 session 已被清理）。
    /// 调用方收到此错误时，子 session 已通过 `destroy()` 清理（SessionMeta + checkpoint 全部清空）。
    #[error("Dispatch failed: {0}")]
    DispatchFailed(String),
}