enact-core 0.0.2

//! Execution & Telemetry IDs - Graph-centric observability identifiers
//!
//! This module defines the canonical ID types for the enact-core runtime,
//! aligned with the Execution/Step/Artifact hierarchy.
//!
//! ## ID Format
//! All IDs use prefixed KSUID (K-Sortable Unique IDentifier):
//! - `exec_[27 alphanumeric chars]` - ExecutionId
//! - `step_[27 alphanumeric chars]` - StepId
//! - `artifact_[27 alphanumeric chars]` - ArtifactId
//!
//! ## Hierarchy
//! ```text
//! ExecutionId (The Run)
//!   ├── StepId (Type: ToolNode) -> Artifacts
//!   ├── StepId (Type: LlmNode)  -> Artifacts
//!   └── StepId (Type: GraphNode "Sub-Agent")
//!         └── ExecutionId (Nested run)
//!               └── StepId...
//! ```
//!
//! @see docs/TECHNICAL/01-EXECUTION-TELEMETRY.md

use serde::{Deserialize, Serialize};
use std::fmt;
use svix_ksuid::{Ksuid, KsuidLike};

/// Generate a new KSUID
fn new_ksuid() -> String {
    Ksuid::new(None, None).to_string()
}

// =============================================================================
// ExecutionId - One run of a blueprint (Agent/Graph/Workflow)
// =============================================================================

/// ExecutionId - Identifies one run of a blueprint
///
/// This is the primary unit of billing and audit.
/// Produces an append-only stream of ExecutionEvents.
///
/// Format: `exec_[27-char KSUID]`
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct ExecutionId(String);

impl ExecutionId {
    /// Create a new ExecutionId with auto-generated KSUID
    pub fn new() -> Self {
        Self(format!("exec_{}", new_ksuid()))
    }

    /// Create from an existing string (useful for deserialization)
    pub fn from_string(s: impl Into<String>) -> Self {
        Self(s.into())
    }

    /// Get the ID as a string slice
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl Default for ExecutionId {
    fn default() -> Self {
        Self::new()
    }
}

impl fmt::Display for ExecutionId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl From<String> for ExecutionId {
    fn from(s: String) -> Self {
        Self(s)
    }
}

impl From<&str> for ExecutionId {
    fn from(s: &str) -> Self {
        Self(s.to_string())
    }
}

/// RunId - Alias for ExecutionId
pub type RunId = ExecutionId;

// =============================================================================
// StepId - A distinct action within an execution
// =============================================================================

/// StepId - Identifies a distinct action within an execution
///
/// In TUI/CLI, appears as a "Sub-Agent" or "Action" performing work.
/// Internally, this is a graph node execution.
///
/// Format: `step_[27-char KSUID]`
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct StepId(String);

impl StepId {
    /// Create a new StepId with auto-generated KSUID
    pub fn new() -> Self {
        Self(format!("step_{}", new_ksuid()))
    }

    /// Create from an existing string
    pub fn from_string(s: impl Into<String>) -> Self {
        Self(s.into())
    }

    /// Get the ID as a string slice
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl Default for StepId {
    fn default() -> Self {
        Self::new()
    }
}

impl fmt::Display for StepId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl From<String> for StepId {
    fn from(s: String) -> Self {
        Self(s)
    }
}

impl From<&str> for StepId {
    fn from(s: &str) -> Self {
        Self(s.to_string())
    }
}

/// NodeId - Alias for StepId
pub type NodeId = StepId;

// =============================================================================
// GraphId - Graph definition identifier (design-time)
// =============================================================================

/// GraphId - Graph definition identifier
///
/// Identifies a static execution blueprint (Nodes + Edges).
/// Versioned and immutable once published.
///
/// Format: `graph_[27-char KSUID]`
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct GraphId(String);

impl GraphId {
    pub fn new() -> Self {
        Self(format!("graph_{}", new_ksuid()))
    }

    pub fn from_string(s: impl Into<String>) -> Self {
        Self(s.into())
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl Default for GraphId {
    fn default() -> Self {
        Self::new()
    }
}

impl fmt::Display for GraphId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

// =============================================================================
// ArtifactId - Data produced by a step
// =============================================================================

/// ArtifactId - Identifies persisted output produced by a step
///
/// Examples: Generated Code, PDF Report, Search JSON, Image.
///
/// Format: `artifact_[27-char KSUID]`
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct ArtifactId(String);

impl ArtifactId {
    pub fn new() -> Self {
        Self(format!("artifact_{}", new_ksuid()))
    }

    pub fn from_string(s: impl Into<String>) -> Self {
        Self(s.into())
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl Default for ArtifactId {
    fn default() -> Self {
        Self::new()
    }
}

impl fmt::Display for ArtifactId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

// =============================================================================
// TenantId / UserId - Multi-tenant context
// =============================================================================

/// TenantId - Multi-tenant isolation identifier
///
/// Format: `tenant_[27-char KSUID]`
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct TenantId(String);

impl TenantId {
    pub fn new() -> Self {
        Self(format!("tenant_{}", new_ksuid()))
    }

    pub fn from_string(s: impl Into<String>) -> Self {
        Self(s.into())
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl Default for TenantId {
    fn default() -> Self {
        Self::new()
    }
}

impl fmt::Display for TenantId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl From<String> for TenantId {
    fn from(s: String) -> Self {
        Self(s)
    }
}

impl From<&str> for TenantId {
    fn from(s: &str) -> Self {
        Self(s.to_string())
    }
}

/// UserId - User identifier
///
/// Format: `user_[27-char KSUID]`
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct UserId(String);

impl UserId {
    pub fn new() -> Self {
        Self(format!("user_{}", new_ksuid()))
    }

    pub fn from_string(s: impl Into<String>) -> Self {
        Self(s.into())
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl Default for UserId {
    fn default() -> Self {
        Self::new()
    }
}

impl fmt::Display for UserId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl From<String> for UserId {
    fn from(s: String) -> Self {
        Self(s)
    }
}

impl From<&str> for UserId {
    fn from(s: &str) -> Self {
        Self(s.to_string())
    }
}

// =============================================================================
// StepType - What kind of step this is
// =============================================================================

/// StepType - Defines what the step *is* (internal: NodeType)
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "PascalCase")]
pub enum StepType {
    /// LLM call step
    LlmNode,
    /// Sub-agent / sub-graph execution
    GraphNode,
    /// Tool execution
    ToolNode,
    /// Deterministic code function
    FunctionNode,
    /// Routing decision node
    RouterNode,
    /// Conditional branch node
    BranchNode,
    /// Loop iteration node
    LoopNode,
}

impl fmt::Display for StepType {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            StepType::LlmNode => write!(f, "LlmNode"),
            StepType::GraphNode => write!(f, "GraphNode"),
            StepType::ToolNode => write!(f, "ToolNode"),
            StepType::FunctionNode => write!(f, "FunctionNode"),
            StepType::RouterNode => write!(f, "RouterNode"),
            StepType::BranchNode => write!(f, "BranchNode"),
            StepType::LoopNode => write!(f, "LoopNode"),
        }
    }
}

// =============================================================================
// CallableType - What kind of callable was invoked
// =============================================================================

/// CallableType - The type of callable that was invoked
///
/// Used for billing, traceability, and audit trails. Unlike `name` which can change,
/// `callable_id` + `callable_type` provide stable identifiers for cost attribution.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum CallableType {
    /// Single LLM call, no history
    Completion,
    /// Multi-turn conversation
    Chat,
    /// Goal-driven with tool use
    #[default]
    Agent,
    /// Compiled graph execution
    Workflow,
    /// Ephemeral tasks (title gen, summarization)
    Background,
    /// Callable that invokes other callables
    Composite,
    /// Tool execution (wraps a tool as callable)
    Tool,
    /// Custom/user-defined callable
    Custom,
}

impl fmt::Display for CallableType {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            CallableType::Completion => write!(f, "completion"),
            CallableType::Chat => write!(f, "chat"),
            CallableType::Agent => write!(f, "agent"),
            CallableType::Workflow => write!(f, "workflow"),
            CallableType::Background => write!(f, "background"),
            CallableType::Composite => write!(f, "composite"),
            CallableType::Tool => write!(f, "tool"),
            CallableType::Custom => write!(f, "custom"),
        }
    }
}

// =============================================================================
// Parent Linkage - Polymorphic root for causal tracing
// =============================================================================

/// ParentType - What kind of entity triggered this execution
///
/// Instead of many nullable root fields, we use a single parent pointer
/// to trace causal origin.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ParentType {
    /// User chatted in UI (e.g., msg_1234)
    UserMessage,
    /// Scheduled job (e.g., evt_cron_daily)
    ScheduleEvent,
    /// A parent agent invoked a sub-agent (e.g., step_abc_789)
    StepExecution,
    /// External system trigger (e.g., wh_stripe_hook)
    Webhook,
    /// Agent-to-agent request
    A2aRequest,
    /// System-initiated (startup, recovery)
    System,
    /// Assistant message in a thread
    AssistantMessage,
    /// Start of a thread (no parent)
    ThreadStart,
    /// Result of a tool execution
    ToolResult,
}

impl fmt::Display for ParentType {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            ParentType::UserMessage => write!(f, "user_message"),
            ParentType::ScheduleEvent => write!(f, "schedule_event"),
            ParentType::StepExecution => write!(f, "step_execution"),
            ParentType::Webhook => write!(f, "webhook"),
            ParentType::A2aRequest => write!(f, "a2a_request"),
            ParentType::System => write!(f, "system"),
            ParentType::AssistantMessage => write!(f, "assistant_message"),
            ParentType::ThreadStart => write!(f, "thread_start"),
            ParentType::ToolResult => write!(f, "tool_result"),
        }
    }
}

/// ParentLink - Traces causal origin of an execution
///
/// Every execution has a parent link that describes what triggered it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ParentLink {
    /// The ID of the triggering entity
    pub parent_id: String,
    /// What kind of entity triggered this
    pub parent_type: ParentType,
}

impl ParentLink {
    /// Create a new ParentLink
    pub fn new(parent_id: impl Into<String>, parent_type: ParentType) -> Self {
        Self {
            parent_id: parent_id.into(),
            parent_type,
        }
    }

    /// Create a ParentLink for a user message trigger
    pub fn from_user_message(message_id: impl Into<String>) -> Self {
        Self::new(message_id, ParentType::UserMessage)
    }

    /// Create a ParentLink for a step execution (sub-agent) trigger
    pub fn from_step(step_id: &StepId) -> Self {
        Self::new(step_id.as_str(), ParentType::StepExecution)
    }

    /// Create a ParentLink for a parent execution (nested execution)
    pub fn execution(execution_id: ExecutionId) -> Self {
        Self::new(execution_id.as_str(), ParentType::StepExecution)
    }

    /// Create a ParentLink for a system trigger
    pub fn system() -> Self {
        Self::new("system", ParentType::System)
    }
}

// =============================================================================
// StepSource - Tracks why/how a step was created
// =============================================================================

/// StepSourceType - Why/how a step was created
///
/// Used to track the origin of each step for audit trails and replay.
/// Follows the same pattern as ParentType but at the step level.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum StepSourceType {
    /// Part of initial compiled graph (default)
    #[default]
    InitialPlan,
    /// Discovered during agentic execution
    Discovered,
    /// Retry of a failed step
    Retry,
    /// From user guidance via inbox
    UserGuidance,
    /// From tool result suggesting new work
    ToolResult,
    /// From LLM output suggesting new work
    LlmOutput,
    /// From external agent (A2A)
    A2aMessage,
}

impl fmt::Display for StepSourceType {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            StepSourceType::InitialPlan => write!(f, "initial_plan"),
            StepSourceType::Discovered => write!(f, "discovered"),
            StepSourceType::Retry => write!(f, "retry"),
            StepSourceType::UserGuidance => write!(f, "user_guidance"),
            StepSourceType::ToolResult => write!(f, "tool_result"),
            StepSourceType::LlmOutput => write!(f, "llm_output"),
            StepSourceType::A2aMessage => write!(f, "a2a_message"),
        }
    }
}

/// StepSource - Tracks the origin of a step
///
/// Every step can optionally track why it was created, enabling:
/// - Full audit trails for discovered steps
/// - Replay of agentic discovery sequences
/// - Understanding step chains and dependencies
///
/// @see packages/enact-schemas/src/execution.schemas.ts - stepSourceSchema
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct StepSource {
    /// Type of source (why was this step created)
    pub source_type: StepSourceType,
    /// ID of the step/entity that triggered this step (if any)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub triggered_by: Option<String>,
    /// Human-readable reason for step creation
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
    /// Discovery depth (for discovered steps - how deep in discovery chain)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub depth: Option<u32>,
    /// How this step was spawned (for spawned steps)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub spawn_mode: Option<SpawnMode>,
}

impl StepSource {
    /// Create a new StepSource
    pub fn new(source_type: StepSourceType) -> Self {
        Self {
            source_type,
            triggered_by: None,
            reason: None,
            depth: None,
            spawn_mode: None,
        }
    }

    /// Create a source for initial plan steps
    pub fn initial_plan() -> Self {
        Self::new(StepSourceType::InitialPlan)
    }

    /// Create a source for discovered steps
    pub fn discovered(triggered_by: &StepId, reason: impl Into<String>, depth: u32) -> Self {
        Self {
            source_type: StepSourceType::Discovered,
            triggered_by: Some(triggered_by.as_str().to_string()),
            reason: Some(reason.into()),
            depth: Some(depth),
            spawn_mode: None,
        }
    }

    /// Create a source for retry steps
    pub fn retry(original_step_id: &StepId) -> Self {
        Self {
            source_type: StepSourceType::Retry,
            triggered_by: Some(original_step_id.as_str().to_string()),
            reason: None,
            depth: None,
            spawn_mode: None,
        }
    }

    /// Create a source for user guidance steps
    pub fn user_guidance(message_id: impl Into<String>, reason: impl Into<String>) -> Self {
        Self {
            source_type: StepSourceType::UserGuidance,
            triggered_by: Some(message_id.into()),
            reason: Some(reason.into()),
            depth: None,
            spawn_mode: None,
        }
    }

    /// Create a source for LLM output discovery
    pub fn llm_output(step_id: &StepId, reason: impl Into<String>, depth: u32) -> Self {
        Self {
            source_type: StepSourceType::LlmOutput,
            triggered_by: Some(step_id.as_str().to_string()),
            reason: Some(reason.into()),
            depth: Some(depth),
            spawn_mode: None,
        }
    }

    /// Create a source for tool result discovery
    pub fn tool_result(step_id: &StepId, reason: impl Into<String>, depth: u32) -> Self {
        Self {
            source_type: StepSourceType::ToolResult,
            triggered_by: Some(step_id.as_str().to_string()),
            reason: Some(reason.into()),
            depth: Some(depth),
            spawn_mode: None,
        }
    }

    /// Set the spawn_mode field
    pub fn with_spawn_mode(mut self, spawn_mode: SpawnMode) -> Self {
        self.spawn_mode = Some(spawn_mode);
        self
    }

    /// Set the triggered_by field
    pub fn with_triggered_by(mut self, triggered_by: impl Into<String>) -> Self {
        self.triggered_by = Some(triggered_by.into());
        self
    }

    /// Set the reason field
    pub fn with_reason(mut self, reason: impl Into<String>) -> Self {
        self.reason = Some(reason.into());
        self
    }

    /// Set the depth field
    pub fn with_depth(mut self, depth: u32) -> Self {
        self.depth = Some(depth);
        self
    }
}

impl Default for StepSource {
    fn default() -> Self {
        Self::initial_plan()
    }
}

// =============================================================================
// SpawnMode - Execution Isolation Control
// =============================================================================

/// SpawnMode - How a callable spawns child work
///
/// Controls execution isolation, inbox routing, and cancellation behavior.
/// Every callable can spawn children - SpawnMode determines HOW.
///
/// @see packages/enact-schemas/src/execution.schemas.ts - spawnModeSchema
/// @see docs/TECHNICAL/32-SPAWN-MODE.md
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(tag = "mode", rename_all = "snake_case")]
pub enum SpawnMode {
    /// Child work joins parent's pending_steps queue (same ExecutionId)
    /// - Same execution context
    /// - Same inbox
    /// - Same policies
    #[default]
    Inline,

    /// Child work runs as isolated execution (new ExecutionId with ParentLink)
    Child {
        /// Run in background (don't block parent)
        #[serde(default)]
        background: bool,

        /// Inherit parent's inbox (forward messages)
        #[serde(default)]
        inherit_inbox: bool,

        /// Override policies for child (JSON object)
        #[serde(skip_serializing_if = "Option::is_none")]
        policies: Option<serde_json::Value>,
    },
}

impl SpawnMode {
    /// Create inline spawn mode (default)
    pub fn inline() -> Self {
        SpawnMode::Inline
    }

    /// Create child spawn mode with options
    pub fn child(background: bool, inherit_inbox: bool) -> Self {
        SpawnMode::Child {
            background,
            inherit_inbox,
            policies: None,
        }
    }

    /// Create child spawn mode with custom policies
    pub fn child_with_policies(
        background: bool,
        inherit_inbox: bool,
        policies: serde_json::Value,
    ) -> Self {
        SpawnMode::Child {
            background,
            inherit_inbox,
            policies: Some(policies),
        }
    }

    /// Check if this is inline mode
    pub fn is_inline(&self) -> bool {
        matches!(self, SpawnMode::Inline)
    }

    /// Check if this is child mode
    pub fn is_child(&self) -> bool {
        matches!(self, SpawnMode::Child { .. })
    }

    /// Check if child should run in background
    pub fn is_background(&self) -> bool {
        matches!(
            self,
            SpawnMode::Child {
                background: true,
                ..
            }
        )
    }

    /// Check if child should inherit parent's inbox
    pub fn inherits_inbox(&self) -> bool {
        matches!(
            self,
            SpawnMode::Child {
                inherit_inbox: true,
                ..
            }
        )
    }
}

impl fmt::Display for SpawnMode {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            SpawnMode::Inline => write!(f, "inline"),
            SpawnMode::Child {
                background,
                inherit_inbox,
                ..
            } => {
                write!(
                    f,
                    "child(background={}, inherit_inbox={})",
                    background, inherit_inbox
                )
            }
        }
    }
}

// =============================================================================
// CancellationPolicy - Child Execution Lifecycle
// =============================================================================

/// CancellationPolicy - What happens to children when parent is cancelled
///
/// Controls the lifecycle relationship between parent and child executions.
///
/// @see packages/enact-schemas/src/execution.schemas.ts - cancellationPolicySchema
/// @see docs/TECHNICAL/32-SPAWN-MODE.md
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum CancellationPolicy {
    /// Cancel all children when parent cancelled (default)
    #[default]
    CascadeCancel,

    /// Let children complete, parent waits for them
    WaitForChildren,

    /// Detach children (they continue independently)
    Detach,
}

impl fmt::Display for CancellationPolicy {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            CancellationPolicy::CascadeCancel => write!(f, "cascade_cancel"),
            CancellationPolicy::WaitForChildren => write!(f, "wait_for_children"),
            CancellationPolicy::Detach => write!(f, "detach"),
        }
    }
}

// =============================================================================
// ThreadId / MessageId - Conversation hierarchy
// =============================================================================

/// ThreadId - Conversation thread identifier
///
/// Groups messages into a single conversation context.
///
/// Format: `thread_[27-char KSUID]`
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct ThreadId(String);

impl ThreadId {
    pub fn new() -> Self {
        Self(format!("thread_{}", new_ksuid()))
    }

    pub fn from_string(s: impl Into<String>) -> Self {
        Self(s.into())
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl Default for ThreadId {
    fn default() -> Self {
        Self::new()
    }
}

impl fmt::Display for ThreadId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl From<String> for ThreadId {
    fn from(s: String) -> Self {
        Self(s)
    }
}

impl From<&str> for ThreadId {
    fn from(s: &str) -> Self {
        Self(s.to_string())
    }
}

/// MessageId - Individual message identifier
///
/// Identifies a single message within a thread.
///
/// Format: `msg_[27-char KSUID]`
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct MessageId(String);

impl MessageId {
    pub fn new() -> Self {
        Self(format!("msg_{}", new_ksuid()))
    }

    pub fn from_string(s: impl Into<String>) -> Self {
        Self(s.into())
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl Default for MessageId {
    fn default() -> Self {
        Self::new()
    }
}

impl fmt::Display for MessageId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl From<String> for MessageId {
    fn from(s: String) -> Self {
        Self(s)
    }
}

impl From<&str> for MessageId {
    fn from(s: &str) -> Self {
        Self(s.to_string())
    }
}

// =============================================================================
// ID Prefix Constants
// =============================================================================

/// ID prefix constants for validation and generation
pub mod prefixes {
    pub const EXECUTION: &str = "exec_";
    pub const STEP: &str = "step_";
    pub const ARTIFACT: &str = "artifact_";
    pub const GRAPH: &str = "graph_";
    pub const TENANT: &str = "tenant_";
    pub const USER: &str = "user_";
    pub const EVENT: &str = "evt_";
    pub const DECISION: &str = "dec_";
    pub const CONTROL: &str = "ctrl_";
    pub const THREAD: &str = "thread_";
    pub const MESSAGE: &str = "msg_";
}

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

    // =========================================================================
    // ExecutionId Tests
    // =========================================================================

    #[test]
    fn test_execution_id_new_has_correct_prefix() {
        let id = ExecutionId::new();
        assert!(
            id.as_str().starts_with("exec_"),
            "ExecutionId should start with 'exec_'"
        );
    }

    #[test]
    fn test_execution_id_new_unique() {
        let id1 = ExecutionId::new();
        let id2 = ExecutionId::new();
        assert_ne!(id1, id2, "Each new ExecutionId should be unique");
    }

    #[test]
    fn test_execution_id_from_string() {
        let id = ExecutionId::from_string("exec_custom123");
        assert_eq!(id.as_str(), "exec_custom123");
    }

    #[test]
    fn test_execution_id_from_string_owned() {
        let id = ExecutionId::from_string(String::from("exec_owned"));
        assert_eq!(id.as_str(), "exec_owned");
    }

    #[test]
    fn test_execution_id_display() {
        let id = ExecutionId::from_string("exec_display_test");
        assert_eq!(format!("{}", id), "exec_display_test");
    }

    #[test]
    fn test_execution_id_default() {
        let id = ExecutionId::default();
        assert!(id.as_str().starts_with("exec_"));
    }

    #[test]
    fn test_execution_id_from_string_trait() {
        let id: ExecutionId = String::from("exec_from_string").into();
        assert_eq!(id.as_str(), "exec_from_string");
    }

    #[test]
    fn test_execution_id_from_str_trait() {
        let id: ExecutionId = "exec_from_str".into();
        assert_eq!(id.as_str(), "exec_from_str");
    }

    #[test]
    fn test_execution_id_clone() {
        let id1 = ExecutionId::new();
        let id2 = id1.clone();
        assert_eq!(id1, id2);
    }

    #[test]
    fn test_execution_id_hash() {
        let id1 = ExecutionId::from_string("exec_hash_test");
        let id2 = ExecutionId::from_string("exec_hash_test");
        let mut set = HashSet::new();
        set.insert(id1);
        assert!(set.contains(&id2));
    }

    #[test]
    fn test_execution_id_debug() {
        let id = ExecutionId::from_string("exec_debug");
        let debug_str = format!("{:?}", id);
        assert!(debug_str.contains("exec_debug"));
    }

    #[test]
    fn test_execution_id_serde() {
        let id = ExecutionId::from_string("exec_serde_test");
        let serialized = serde_json::to_string(&id).unwrap();
        let deserialized: ExecutionId = serde_json::from_str(&serialized).unwrap();
        assert_eq!(id, deserialized);
    }

    // =========================================================================
    // StepId Tests
    // =========================================================================

    #[test]
    fn test_step_id_new_has_correct_prefix() {
        let id = StepId::new();
        assert!(
            id.as_str().starts_with("step_"),
            "StepId should start with 'step_'"
        );
    }

    #[test]
    fn test_step_id_new_unique() {
        let id1 = StepId::new();
        let id2 = StepId::new();
        assert_ne!(id1, id2);
    }

    #[test]
    fn test_step_id_from_string() {
        let id = StepId::from_string("step_custom");
        assert_eq!(id.as_str(), "step_custom");
    }

    #[test]
    fn test_step_id_display() {
        let id = StepId::from_string("step_display");
        assert_eq!(format!("{}", id), "step_display");
    }

    #[test]
    fn test_step_id_default() {
        let id = StepId::default();
        assert!(id.as_str().starts_with("step_"));
    }

    #[test]
    fn test_step_id_from_traits() {
        let id1: StepId = String::from("step_string").into();
        let id2: StepId = "step_str".into();
        assert_eq!(id1.as_str(), "step_string");
        assert_eq!(id2.as_str(), "step_str");
    }

    #[test]
    fn test_step_id_hash() {
        let id = StepId::from_string("step_hash");
        let mut set = HashSet::new();
        set.insert(id.clone());
        assert!(set.contains(&id));
    }

    #[test]
    fn test_step_id_serde() {
        let id = StepId::from_string("step_serde");
        let json = serde_json::to_string(&id).unwrap();
        let parsed: StepId = serde_json::from_str(&json).unwrap();
        assert_eq!(id, parsed);
    }

    // =========================================================================
    // GraphId Tests
    // =========================================================================

    #[test]
    fn test_graph_id_new_has_correct_prefix() {
        let id = GraphId::new();
        assert!(id.as_str().starts_with("graph_"));
    }

    #[test]
    fn test_graph_id_new_unique() {
        let id1 = GraphId::new();
        let id2 = GraphId::new();
        assert_ne!(id1, id2);
    }

    #[test]
    fn test_graph_id_from_string() {
        let id = GraphId::from_string("graph_custom");
        assert_eq!(id.as_str(), "graph_custom");
    }

    #[test]
    fn test_graph_id_display() {
        let id = GraphId::from_string("graph_display");
        assert_eq!(format!("{}", id), "graph_display");
    }

    #[test]
    fn test_graph_id_default() {
        let id = GraphId::default();
        assert!(id.as_str().starts_with("graph_"));
    }

    #[test]
    fn test_graph_id_serde() {
        let id = GraphId::from_string("graph_serde");
        let json = serde_json::to_string(&id).unwrap();
        let parsed: GraphId = serde_json::from_str(&json).unwrap();
        assert_eq!(id, parsed);
    }

    // =========================================================================
    // ArtifactId Tests
    // =========================================================================

    #[test]
    fn test_artifact_id_new_has_correct_prefix() {
        let id = ArtifactId::new();
        assert!(id.as_str().starts_with("artifact_"));
    }

    #[test]
    fn test_artifact_id_new_unique() {
        let id1 = ArtifactId::new();
        let id2 = ArtifactId::new();
        assert_ne!(id1, id2);
    }

    #[test]
    fn test_artifact_id_from_string() {
        let id = ArtifactId::from_string("artifact_custom");
        assert_eq!(id.as_str(), "artifact_custom");
    }

    #[test]
    fn test_artifact_id_display() {
        let id = ArtifactId::from_string("artifact_display");
        assert_eq!(format!("{}", id), "artifact_display");
    }

    #[test]
    fn test_artifact_id_default() {
        let id = ArtifactId::default();
        assert!(id.as_str().starts_with("artifact_"));
    }

    #[test]
    fn test_artifact_id_serde() {
        let id = ArtifactId::from_string("artifact_serde");
        let json = serde_json::to_string(&id).unwrap();
        let parsed: ArtifactId = serde_json::from_str(&json).unwrap();
        assert_eq!(id, parsed);
    }

    // =========================================================================
    // TenantId Tests
    // =========================================================================

    #[test]
    fn test_tenant_id_new_has_correct_prefix() {
        let id = TenantId::new();
        assert!(id.as_str().starts_with("tenant_"));
    }

    #[test]
    fn test_tenant_id_new_unique() {
        let id1 = TenantId::new();
        let id2 = TenantId::new();
        assert_ne!(id1, id2);
    }

    #[test]
    fn test_tenant_id_from_string() {
        let id = TenantId::from_string("tenant_custom");
        assert_eq!(id.as_str(), "tenant_custom");
    }

    #[test]
    fn test_tenant_id_display() {
        let id = TenantId::from_string("tenant_display");
        assert_eq!(format!("{}", id), "tenant_display");
    }

    #[test]
    fn test_tenant_id_default() {
        let id = TenantId::default();
        assert!(id.as_str().starts_with("tenant_"));
    }

    #[test]
    fn test_tenant_id_from_traits() {
        let id1: TenantId = String::from("tenant_string").into();
        let id2: TenantId = "tenant_str".into();
        assert_eq!(id1.as_str(), "tenant_string");
        assert_eq!(id2.as_str(), "tenant_str");
    }

    #[test]
    fn test_tenant_id_serde() {
        let id = TenantId::from_string("tenant_serde");
        let json = serde_json::to_string(&id).unwrap();
        let parsed: TenantId = serde_json::from_str(&json).unwrap();
        assert_eq!(id, parsed);
    }

    // =========================================================================
    // UserId Tests
    // =========================================================================

    #[test]
    fn test_user_id_new_has_correct_prefix() {
        let id = UserId::new();
        assert!(id.as_str().starts_with("user_"));
    }

    #[test]
    fn test_user_id_new_unique() {
        let id1 = UserId::new();
        let id2 = UserId::new();
        assert_ne!(id1, id2);
    }

    #[test]
    fn test_user_id_from_string() {
        let id = UserId::from_string("user_custom");
        assert_eq!(id.as_str(), "user_custom");
    }

    #[test]
    fn test_user_id_display() {
        let id = UserId::from_string("user_display");
        assert_eq!(format!("{}", id), "user_display");
    }

    #[test]
    fn test_user_id_default() {
        let id = UserId::default();
        assert!(id.as_str().starts_with("user_"));
    }

    #[test]
    fn test_user_id_from_traits() {
        let id1: UserId = String::from("user_string").into();
        let id2: UserId = "user_str".into();
        assert_eq!(id1.as_str(), "user_string");
        assert_eq!(id2.as_str(), "user_str");
    }

    #[test]
    fn test_user_id_serde() {
        let id = UserId::from_string("user_serde");
        let json = serde_json::to_string(&id).unwrap();
        let parsed: UserId = serde_json::from_str(&json).unwrap();
        assert_eq!(id, parsed);
    }

    // =========================================================================
    // StepType Tests
    // =========================================================================

    #[test]
    fn test_step_type_display_llm_node() {
        assert_eq!(format!("{}", StepType::LlmNode), "LlmNode");
    }

    #[test]
    fn test_step_type_display_graph_node() {
        assert_eq!(format!("{}", StepType::GraphNode), "GraphNode");
    }

    #[test]
    fn test_step_type_display_tool_node() {
        assert_eq!(format!("{}", StepType::ToolNode), "ToolNode");
    }

    #[test]
    fn test_step_type_display_function_node() {
        assert_eq!(format!("{}", StepType::FunctionNode), "FunctionNode");
    }

    #[test]
    fn test_step_type_display_router_node() {
        assert_eq!(format!("{}", StepType::RouterNode), "RouterNode");
    }

    #[test]
    fn test_step_type_display_branch_node() {
        assert_eq!(format!("{}", StepType::BranchNode), "BranchNode");
    }

    #[test]
    fn test_step_type_display_loop_node() {
        assert_eq!(format!("{}", StepType::LoopNode), "LoopNode");
    }

    #[test]
    fn test_step_type_serde_llm_node() {
        let step = StepType::LlmNode;
        let json = serde_json::to_string(&step).unwrap();
        assert_eq!(json, "\"LlmNode\"");
        let parsed: StepType = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed, StepType::LlmNode);
    }

    #[test]
    fn test_step_type_serde_all_variants() {
        let variants = vec![
            StepType::LlmNode,
            StepType::GraphNode,
            StepType::ToolNode,
            StepType::FunctionNode,
            StepType::RouterNode,
            StepType::BranchNode,
            StepType::LoopNode,
        ];
        for variant in variants {
            let json = serde_json::to_string(&variant).unwrap();
            let parsed: StepType = serde_json::from_str(&json).unwrap();
            assert_eq!(parsed, variant);
        }
    }

    #[test]
    fn test_step_type_equality() {
        assert_eq!(StepType::LlmNode, StepType::LlmNode);
        assert_ne!(StepType::LlmNode, StepType::ToolNode);
    }

    #[test]
    fn test_step_type_clone() {
        let step = StepType::GraphNode;
        let cloned = step.clone();
        assert_eq!(step, cloned);
    }

    // =========================================================================
    // CallableType Tests (for billing/traceability)
    // =========================================================================

    #[test]
    fn test_callable_type_display_all() {
        assert_eq!(format!("{}", CallableType::Completion), "completion");
        assert_eq!(format!("{}", CallableType::Chat), "chat");
        assert_eq!(format!("{}", CallableType::Agent), "agent");
        assert_eq!(format!("{}", CallableType::Workflow), "workflow");
        assert_eq!(format!("{}", CallableType::Background), "background");
        assert_eq!(format!("{}", CallableType::Composite), "composite");
        assert_eq!(format!("{}", CallableType::Tool), "tool");
        assert_eq!(format!("{}", CallableType::Custom), "custom");
    }

    #[test]
    fn test_callable_type_default() {
        let default_type = CallableType::default();
        assert_eq!(default_type, CallableType::Agent);
    }

    #[test]
    fn test_callable_type_serde_all_variants() {
        let variants = vec![
            CallableType::Completion,
            CallableType::Chat,
            CallableType::Agent,
            CallableType::Workflow,
            CallableType::Background,
            CallableType::Composite,
            CallableType::Tool,
            CallableType::Custom,
        ];
        for variant in variants {
            let json = serde_json::to_string(&variant).unwrap();
            let parsed: CallableType = serde_json::from_str(&json).unwrap();
            assert_eq!(parsed, variant);
        }
    }

    #[test]
    fn test_callable_type_serde_snake_case() {
        // Verify snake_case serialization
        let json = serde_json::to_string(&CallableType::Background).unwrap();
        assert_eq!(json, "\"background\"");

        let json = serde_json::to_string(&CallableType::Workflow).unwrap();
        assert_eq!(json, "\"workflow\"");
    }

    #[test]
    fn test_callable_type_equality() {
        assert_eq!(CallableType::Agent, CallableType::Agent);
        assert_ne!(CallableType::Agent, CallableType::Chat);
    }

    #[test]
    fn test_callable_type_clone() {
        let callable = CallableType::Workflow;
        let cloned = callable.clone();
        assert_eq!(callable, cloned);
    }

    #[test]
    fn test_callable_type_hash() {
        use std::collections::HashSet;
        let mut set = HashSet::new();
        set.insert(CallableType::Agent);
        set.insert(CallableType::Chat);
        set.insert(CallableType::Agent); // duplicate
        assert_eq!(set.len(), 2);
    }

    // =========================================================================
    // ParentType Tests
    // =========================================================================

    #[test]
    fn test_parent_type_display_user_message() {
        assert_eq!(format!("{}", ParentType::UserMessage), "user_message");
    }

    #[test]
    fn test_parent_type_display_schedule_event() {
        assert_eq!(format!("{}", ParentType::ScheduleEvent), "schedule_event");
    }

    #[test]
    fn test_parent_type_display_step_execution() {
        assert_eq!(format!("{}", ParentType::StepExecution), "step_execution");
    }

    #[test]
    fn test_parent_type_display_webhook() {
        assert_eq!(format!("{}", ParentType::Webhook), "webhook");
    }

    #[test]
    fn test_parent_type_display_a2a_request() {
        assert_eq!(format!("{}", ParentType::A2aRequest), "a2a_request");
    }

    #[test]
    fn test_parent_type_display_system() {
        assert_eq!(format!("{}", ParentType::System), "system");
    }

    #[test]
    fn test_parent_type_serde_all_variants() {
        let variants = vec![
            ParentType::UserMessage,
            ParentType::ScheduleEvent,
            ParentType::StepExecution,
            ParentType::Webhook,
            ParentType::A2aRequest,
            ParentType::System,
        ];
        for variant in variants {
            let json = serde_json::to_string(&variant).unwrap();
            let parsed: ParentType = serde_json::from_str(&json).unwrap();
            assert_eq!(parsed, variant);
        }
    }

    #[test]
    fn test_parent_type_equality() {
        assert_eq!(ParentType::System, ParentType::System);
        assert_ne!(ParentType::System, ParentType::Webhook);
    }

    // =========================================================================
    // ParentLink Tests
    // =========================================================================

    #[test]
    fn test_parent_link_new() {
        let link = ParentLink::new("msg_123", ParentType::UserMessage);
        assert_eq!(link.parent_id, "msg_123");
        assert_eq!(link.parent_type, ParentType::UserMessage);
    }

    #[test]
    fn test_parent_link_new_with_string() {
        let link = ParentLink::new(String::from("wh_456"), ParentType::Webhook);
        assert_eq!(link.parent_id, "wh_456");
        assert_eq!(link.parent_type, ParentType::Webhook);
    }

    #[test]
    fn test_parent_link_from_user_message() {
        let link = ParentLink::from_user_message("msg_user_789");
        assert_eq!(link.parent_id, "msg_user_789");
        assert_eq!(link.parent_type, ParentType::UserMessage);
    }

    #[test]
    fn test_parent_link_from_step() {
        let step_id = StepId::from_string("step_abc123");
        let link = ParentLink::from_step(&step_id);
        assert_eq!(link.parent_id, "step_abc123");
        assert_eq!(link.parent_type, ParentType::StepExecution);
    }

    #[test]
    fn test_parent_link_execution() {
        let exec_id = ExecutionId::from_string("exec_parent");
        let link = ParentLink::execution(exec_id);
        assert_eq!(link.parent_id, "exec_parent");
        assert_eq!(link.parent_type, ParentType::StepExecution);
    }

    #[test]
    fn test_parent_link_system() {
        let link = ParentLink::system();
        assert_eq!(link.parent_id, "system");
        assert_eq!(link.parent_type, ParentType::System);
    }

    #[test]
    fn test_parent_link_serde() {
        let link = ParentLink::new("test_id", ParentType::A2aRequest);
        let json = serde_json::to_string(&link).unwrap();
        let parsed: ParentLink = serde_json::from_str(&json).unwrap();
        assert_eq!(link, parsed);
    }

    #[test]
    fn test_parent_link_equality() {
        let link1 = ParentLink::new("same_id", ParentType::System);
        let link2 = ParentLink::new("same_id", ParentType::System);
        let link3 = ParentLink::new("different_id", ParentType::System);
        assert_eq!(link1, link2);
        assert_ne!(link1, link3);
    }

    #[test]
    fn test_parent_link_clone() {
        let link = ParentLink::from_user_message("msg_clone");
        let cloned = link.clone();
        assert_eq!(link, cloned);
    }

    // =========================================================================
    // Prefixes Tests
    // =========================================================================

    #[test]
    fn test_prefix_execution() {
        assert_eq!(prefixes::EXECUTION, "exec_");
    }

    #[test]
    fn test_prefix_step() {
        assert_eq!(prefixes::STEP, "step_");
    }

    #[test]
    fn test_prefix_artifact() {
        assert_eq!(prefixes::ARTIFACT, "artifact_");
    }

    #[test]
    fn test_prefix_graph() {
        assert_eq!(prefixes::GRAPH, "graph_");
    }

    #[test]
    fn test_prefix_tenant() {
        assert_eq!(prefixes::TENANT, "tenant_");
    }

    #[test]
    fn test_prefix_user() {
        assert_eq!(prefixes::USER, "user_");
    }

    #[test]
    fn test_prefix_event() {
        assert_eq!(prefixes::EVENT, "evt_");
    }

    #[test]
    fn test_prefix_decision() {
        assert_eq!(prefixes::DECISION, "dec_");
    }

    #[test]
    fn test_prefix_control() {
        assert_eq!(prefixes::CONTROL, "ctrl_");
    }

    // =========================================================================
    // Type Alias Tests
    // =========================================================================

    #[test]
    fn test_run_id_alias() {
        let exec_id = ExecutionId::from_string("exec_alias");
        let run_id: RunId = exec_id.clone();
        assert_eq!(exec_id.as_str(), run_id.as_str());
    }

    #[test]
    fn test_node_id_alias() {
        let step_id = StepId::from_string("step_alias");
        let node_id: NodeId = step_id.clone();
        assert_eq!(step_id.as_str(), node_id.as_str());
    }

    // =========================================================================
    // KSUID Format Tests
    // =========================================================================

    #[test]
    fn test_execution_id_ksuid_length() {
        let id = ExecutionId::new();
        // exec_ (5 chars) + KSUID (27 chars) = 32 chars
        assert_eq!(id.as_str().len(), 32);
    }

    #[test]
    fn test_step_id_ksuid_length() {
        let id = StepId::new();
        // step_ (5 chars) + KSUID (27 chars) = 32 chars
        assert_eq!(id.as_str().len(), 32);
    }

    #[test]
    fn test_graph_id_ksuid_length() {
        let id = GraphId::new();
        // graph_ (6 chars) + KSUID (27 chars) = 33 chars
        assert_eq!(id.as_str().len(), 33);
    }

    #[test]
    fn test_artifact_id_ksuid_length() {
        let id = ArtifactId::new();
        // artifact_ (9 chars) + KSUID (27 chars) = 36 chars
        assert_eq!(id.as_str().len(), 36);
    }

    #[test]
    fn test_tenant_id_ksuid_length() {
        let id = TenantId::new();
        // tenant_ (7 chars) + KSUID (27 chars) = 34 chars
        assert_eq!(id.as_str().len(), 34);
    }

    #[test]
    fn test_user_id_ksuid_length() {
        let id = UserId::new();
        // user_ (5 chars) + KSUID (27 chars) = 32 chars
        assert_eq!(id.as_str().len(), 32);
    }

    // =========================================================================
    // Sortability Tests (KSUIDs are time-sorted)
    // =========================================================================

    #[test]
    fn test_execution_ids_sortable() {
        // Generate multiple IDs quickly and verify they're all unique
        let mut ids: Vec<ExecutionId> = (0..10).map(|_| ExecutionId::new()).collect();
        let original_count = ids.len();

        // Deduplicate to check uniqueness
        ids.sort_by(|a, b| a.as_str().cmp(b.as_str()));
        ids.dedup_by(|a, b| a.as_str() == b.as_str());
        assert_eq!(
            ids.len(),
            original_count,
            "All generated IDs should be unique"
        );
    }

    #[test]
    fn test_ksuid_contains_alphanumeric() {
        let id = ExecutionId::new();
        let ksuid_part = &id.as_str()[5..]; // After "exec_"
        assert!(ksuid_part.chars().all(|c| c.is_ascii_alphanumeric()));
    }

    // =========================================================================
    // ThreadId Tests
    // =========================================================================

    #[test]
    fn test_thread_id_new_has_correct_prefix() {
        let id = ThreadId::new();
        assert!(
            id.as_str().starts_with("thread_"),
            "ThreadId should start with 'thread_'"
        );
    }

    #[test]
    fn test_thread_id_new_unique() {
        let id1 = ThreadId::new();
        let id2 = ThreadId::new();
        assert_ne!(id1, id2, "Each new ThreadId should be unique");
    }

    #[test]
    fn test_thread_id_from_string() {
        let id = ThreadId::from_string("thread_custom123");
        assert_eq!(id.as_str(), "thread_custom123");
    }

    #[test]
    fn test_thread_id_display() {
        let id = ThreadId::from_string("thread_display_test");
        assert_eq!(format!("{}", id), "thread_display_test");
    }

    #[test]
    fn test_thread_id_default() {
        let id = ThreadId::default();
        assert!(id.as_str().starts_with("thread_"));
    }

    #[test]
    fn test_thread_id_from_traits() {
        let id1: ThreadId = String::from("thread_string").into();
        let id2: ThreadId = "thread_str".into();
        assert_eq!(id1.as_str(), "thread_string");
        assert_eq!(id2.as_str(), "thread_str");
    }

    #[test]
    fn test_thread_id_hash() {
        let id = ThreadId::from_string("thread_hash");
        let mut set = HashSet::new();
        set.insert(id.clone());
        assert!(set.contains(&id));
    }

    #[test]
    fn test_thread_id_serde() {
        let id = ThreadId::from_string("thread_serde");
        let json = serde_json::to_string(&id).unwrap();
        let parsed: ThreadId = serde_json::from_str(&json).unwrap();
        assert_eq!(id, parsed);
    }

    #[test]
    fn test_thread_id_ksuid_length() {
        let id = ThreadId::new();
        // thread_ (7 chars) + KSUID (27 chars) = 34 chars
        assert_eq!(id.as_str().len(), 34);
    }

    // =========================================================================
    // MessageId Tests
    // =========================================================================

    #[test]
    fn test_message_id_new_has_correct_prefix() {
        let id = MessageId::new();
        assert!(
            id.as_str().starts_with("msg_"),
            "MessageId should start with 'msg_'"
        );
    }

    #[test]
    fn test_message_id_new_unique() {
        let id1 = MessageId::new();
        let id2 = MessageId::new();
        assert_ne!(id1, id2, "Each new MessageId should be unique");
    }

    #[test]
    fn test_message_id_from_string() {
        let id = MessageId::from_string("msg_custom123");
        assert_eq!(id.as_str(), "msg_custom123");
    }

    #[test]
    fn test_message_id_display() {
        let id = MessageId::from_string("msg_display_test");
        assert_eq!(format!("{}", id), "msg_display_test");
    }

    #[test]
    fn test_message_id_default() {
        let id = MessageId::default();
        assert!(id.as_str().starts_with("msg_"));
    }

    #[test]
    fn test_message_id_from_traits() {
        let id1: MessageId = String::from("msg_string").into();
        let id2: MessageId = "msg_str".into();
        assert_eq!(id1.as_str(), "msg_string");
        assert_eq!(id2.as_str(), "msg_str");
    }

    #[test]
    fn test_message_id_hash() {
        let id = MessageId::from_string("msg_hash");
        let mut set = HashSet::new();
        set.insert(id.clone());
        assert!(set.contains(&id));
    }

    #[test]
    fn test_message_id_serde() {
        let id = MessageId::from_string("msg_serde");
        let json = serde_json::to_string(&id).unwrap();
        let parsed: MessageId = serde_json::from_str(&json).unwrap();
        assert_eq!(id, parsed);
    }

    #[test]
    fn test_message_id_ksuid_length() {
        let id = MessageId::new();
        // msg_ (4 chars) + KSUID (27 chars) = 31 chars
        assert_eq!(id.as_str().len(), 31);
    }

    // =========================================================================
    // Prefix Tests for new IDs
    // =========================================================================

    #[test]
    fn test_prefix_thread() {
        assert_eq!(prefixes::THREAD, "thread_");
    }

    #[test]
    fn test_prefix_message() {
        assert_eq!(prefixes::MESSAGE, "msg_");
    }

    // =========================================================================
    // SpawnMode Tests
    // =========================================================================

    #[test]
    fn test_spawn_mode_inline_default() {
        // Inline is not the default since we use Option<SpawnMode>
        // but we can still test the variant
        let mode = SpawnMode::Inline;
        assert_eq!(mode, SpawnMode::Inline);
    }

    #[test]
    fn test_spawn_mode_child_default_fields() {
        let mode = SpawnMode::Child {
            background: false,
            inherit_inbox: false,
            policies: None,
        };
        if let SpawnMode::Child {
            background,
            inherit_inbox,
            policies,
        } = mode
        {
            assert!(!background, "default background should be false");
            assert!(!inherit_inbox, "default inherit_inbox should be false");
            assert!(policies.is_none(), "default policies should be None");
        } else {
            panic!("Expected SpawnMode::Child");
        }
    }

    #[test]
    fn test_spawn_mode_child_with_inherit_inbox() {
        let mode = SpawnMode::Child {
            background: false,
            inherit_inbox: true,
            policies: None,
        };
        if let SpawnMode::Child { inherit_inbox, .. } = mode {
            assert!(inherit_inbox, "inherit_inbox should be true");
        } else {
            panic!("Expected SpawnMode::Child");
        }
    }

    #[test]
    fn test_spawn_mode_child_background() {
        let mode = SpawnMode::Child {
            background: true,
            inherit_inbox: false,
            policies: None,
        };
        if let SpawnMode::Child { background, .. } = mode {
            assert!(background, "background should be true");
        } else {
            panic!("Expected SpawnMode::Child");
        }
    }

    #[test]
    fn test_spawn_mode_serde_inline() {
        let mode = SpawnMode::Inline;
        let json = serde_json::to_string(&mode).unwrap();
        assert!(
            json.contains("\"mode\":\"inline\""),
            "Inline should serialize with mode tag"
        );
        let parsed: SpawnMode = serde_json::from_str(&json).unwrap();
        assert_eq!(mode, parsed);
    }

    #[test]
    fn test_spawn_mode_serde_child() {
        let mode = SpawnMode::Child {
            background: true,
            inherit_inbox: true,
            policies: None,
        };
        let json = serde_json::to_string(&mode).unwrap();
        assert!(
            json.contains("\"mode\":\"child\""),
            "Child should serialize with mode tag"
        );
        assert!(
            json.contains("\"background\":true"),
            "background should be serialized"
        );
        assert!(
            json.contains("\"inherit_inbox\":true"),
            "inherit_inbox should be serialized"
        );
        let parsed: SpawnMode = serde_json::from_str(&json).unwrap();
        assert_eq!(mode, parsed);
    }

    #[test]
    fn test_spawn_mode_serde_child_with_policies() {
        let policies = serde_json::json!({
            "max_steps": 100,
            "max_tokens": 10000
        });
        let mode = SpawnMode::Child {
            background: false,
            inherit_inbox: true,
            policies: Some(policies.clone()),
        };
        let json = serde_json::to_string(&mode).unwrap();
        let parsed: SpawnMode = serde_json::from_str(&json).unwrap();
        assert_eq!(mode, parsed);
        if let SpawnMode::Child {
            policies: Some(p), ..
        } = parsed
        {
            assert_eq!(p["max_steps"], 100);
        } else {
            panic!("Expected SpawnMode::Child with policies");
        }
    }

    #[test]
    fn test_spawn_mode_equality() {
        let mode1 = SpawnMode::Inline;
        let mode2 = SpawnMode::Inline;
        let mode3 = SpawnMode::Child {
            background: false,
            inherit_inbox: false,
            policies: None,
        };
        assert_eq!(mode1, mode2);
        assert_ne!(mode1, mode3);
    }

    #[test]
    fn test_spawn_mode_clone() {
        let mode = SpawnMode::Child {
            background: true,
            inherit_inbox: true,
            policies: Some(serde_json::json!({"key": "value"})),
        };
        let cloned = mode.clone();
        assert_eq!(mode, cloned);
    }

    // =========================================================================
    // CancellationPolicy Tests
    // =========================================================================

    #[test]
    fn test_cancellation_policy_default() {
        let policy = CancellationPolicy::default();
        assert_eq!(policy, CancellationPolicy::CascadeCancel);
    }

    #[test]
    fn test_cancellation_policy_variants() {
        let cascade = CancellationPolicy::CascadeCancel;
        let wait = CancellationPolicy::WaitForChildren;
        let detach = CancellationPolicy::Detach;

        assert_ne!(cascade, wait);
        assert_ne!(wait, detach);
        assert_ne!(cascade, detach);
    }

    #[test]
    fn test_cancellation_policy_serde_cascade() {
        let policy = CancellationPolicy::CascadeCancel;
        let json = serde_json::to_string(&policy).unwrap();
        assert_eq!(json, "\"cascade_cancel\"");
        let parsed: CancellationPolicy = serde_json::from_str(&json).unwrap();
        assert_eq!(policy, parsed);
    }

    #[test]
    fn test_cancellation_policy_serde_wait() {
        let policy = CancellationPolicy::WaitForChildren;
        let json = serde_json::to_string(&policy).unwrap();
        assert_eq!(json, "\"wait_for_children\"");
        let parsed: CancellationPolicy = serde_json::from_str(&json).unwrap();
        assert_eq!(policy, parsed);
    }

    #[test]
    fn test_cancellation_policy_serde_detach() {
        let policy = CancellationPolicy::Detach;
        let json = serde_json::to_string(&policy).unwrap();
        assert_eq!(json, "\"detach\"");
        let parsed: CancellationPolicy = serde_json::from_str(&json).unwrap();
        assert_eq!(policy, parsed);
    }

    #[test]
    fn test_cancellation_policy_all_variants_serde() {
        let variants = vec![
            CancellationPolicy::CascadeCancel,
            CancellationPolicy::WaitForChildren,
            CancellationPolicy::Detach,
        ];
        for variant in variants {
            let json = serde_json::to_string(&variant).unwrap();
            let parsed: CancellationPolicy = serde_json::from_str(&json).unwrap();
            assert_eq!(parsed, variant);
        }
    }

    #[test]
    fn test_cancellation_policy_clone() {
        let policy = CancellationPolicy::WaitForChildren;
        let cloned = policy.clone();
        assert_eq!(policy, cloned);
    }

    #[test]
    fn test_cancellation_policy_hash() {
        let policy = CancellationPolicy::Detach;
        let mut set = HashSet::new();
        set.insert(policy.clone());
        assert!(set.contains(&policy));
    }

    // =========================================================================
    // StepSource with SpawnMode Tests
    // =========================================================================

    #[test]
    fn test_step_source_with_spawn_mode() {
        let source = StepSource {
            source_type: StepSourceType::Discovered,
            triggered_by: Some("step_parent".to_string()),
            reason: Some("test spawn".to_string()),
            depth: Some(1),
            spawn_mode: Some(SpawnMode::Child {
                background: false,
                inherit_inbox: true,
                policies: None,
            }),
        };
        assert!(source.spawn_mode.is_some());
        if let Some(SpawnMode::Child { inherit_inbox, .. }) = source.spawn_mode {
            assert!(inherit_inbox);
        }
    }

    #[test]
    fn test_step_source_discovered_default_spawn_mode() {
        let spawner = StepId::new();
        let source = StepSource::discovered(&spawner, "test reason", 1);
        assert!(
            source.spawn_mode.is_none(),
            "discovered() should default to None spawn_mode"
        );
    }

    #[test]
    fn test_step_source_serde_with_spawn_mode() {
        let source = StepSource {
            source_type: StepSourceType::Discovered,
            triggered_by: Some("step_123".to_string()),
            reason: Some("test reason".to_string()),
            depth: Some(2),
            spawn_mode: Some(SpawnMode::Inline),
        };
        let json = serde_json::to_string(&source).unwrap();
        let parsed: StepSource = serde_json::from_str(&json).unwrap();
        assert_eq!(source, parsed);
    }
}