enya-agent 0.1.0

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

@@ -0,0 +1,1394 @@
+//! Execution Events for telemetry and audit
+//!
+//! This module defines all event types emitted during graph execution.
+//! Events provide observability into execution progress, decisions,
+//! and control signals.
+//!
+//! ## Event Types
+//! - `ExecutionEvent` - Base event for all execution events
+//! - `DecisionRecord` - Audit trail for decisions
+//! - `ControlEvent` - Governance and intervention signals
+//!
+//! @see docs/TECHNICAL/01-EXECUTION-TELEMETRY.md
+
+use super::ids::{ArtifactId, ExecutionId, ParentLink, StepId, StepType, TenantId, UserId};
+use serde::{Deserialize, Serialize};
+use svix_ksuid::{Ksuid, KsuidLike};
+
+/// Generate a new event ID
+fn new_event_id() -> String {
+    format!("evt_{}", Ksuid::new(None, None))
+}
+
+// =============================================================================
+// Event Types
+// =============================================================================
+
+/// ExecutionEventType - All event types in the execution lifecycle
+///
+/// Naming convention: `<entity>.<action>`
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ExecutionEventType {
+    // Execution lifecycle
+    ExecutionStart,
+    ExecutionEnd,
+    ExecutionFailed,
+    ExecutionCancelled,
+
+    // Step lifecycle
+    StepStart,
+    StepEnd,
+    StepFailed,
+    StepDiscovered,
+
+    // Artifact events
+    ArtifactCreated,
+
+    // State snapshots
+    StateSnapshot,
+
+    // Decision audit
+    DecisionMade,
+
+    // Control signals
+    ControlPause,
+    ControlResume,
+    ControlCancel,
+
+    // Inbox messages (INV-INBOX-003: audit trail)
+    InboxMessage,
+
+    // Tool execution
+    ToolCallStart,
+    ToolCallEnd,
+
+    // Agentic loop events
+    CheckpointSaved,
+    GoalEvaluated,
+}
+
+impl ExecutionEventType {
+    /// Get the event type as a string (e.g., "execution.start")
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::ExecutionStart => "execution.start",
+            Self::ExecutionEnd => "execution.end",
+            Self::ExecutionFailed => "execution.failed",
+            Self::ExecutionCancelled => "execution.cancelled",
+            Self::StepStart => "step.start",
+            Self::StepEnd => "step.end",
+            Self::StepFailed => "step.failed",
+            Self::StepDiscovered => "step.discovered",
+            Self::ArtifactCreated => "artifact.created",
+            Self::StateSnapshot => "state.snapshot",
+            Self::DecisionMade => "decision.made",
+            Self::ControlPause => "control.pause",
+            Self::ControlResume => "control.resume",
+            Self::ControlCancel => "control.cancel",
+            Self::InboxMessage => "inbox.message",
+            Self::ToolCallStart => "tool.start",
+            Self::ToolCallEnd => "tool.end",
+            Self::CheckpointSaved => "state.checkpoint",
+            Self::GoalEvaluated => "goal.evaluated",
+        }
+    }
+}
+
+// =============================================================================
+// Execution Context (attached to all events)
+// =============================================================================
+
+/// ExecutionContext - Minimal context attached to every event
+///
+/// Replaces the old BaseIdHierarchy with a simpler structure.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ExecutionContext {
+    /// Required: The execution this event belongs to
+    pub execution_id: ExecutionId,
+
+    /// Optional: The specific step
+    pub step_id: Option<StepId>,
+
+    /// Optional: The artifact produced
+    pub artifact_id: Option<ArtifactId>,
+
+    /// Parent linkage (causal origin)
+    pub parent: Option<ParentLink>,
+
+    /// Tenant context
+    pub tenant_id: Option<TenantId>,
+    pub user_id: Option<UserId>,
+}
+
+impl ExecutionContext {
+    /// Create a new ExecutionContext for an execution
+    pub fn new(execution_id: ExecutionId) -> Self {
+        Self {
+            execution_id,
+            step_id: None,
+            artifact_id: None,
+            parent: None,
+            tenant_id: None,
+            user_id: None,
+        }
+    }
+
+    /// Add step context
+    pub fn with_step(mut self, step_id: StepId) -> Self {
+        self.step_id = Some(step_id);
+        self
+    }
+
+    /// Add artifact context
+    pub fn with_artifact(mut self, artifact_id: ArtifactId) -> Self {
+        self.artifact_id = Some(artifact_id);
+        self
+    }
+
+    /// Add parent linkage
+    pub fn with_parent(mut self, parent: ParentLink) -> Self {
+        self.parent = Some(parent);
+        self
+    }
+
+    /// Add tenant context
+    pub fn with_tenant(mut self, tenant_id: TenantId, user_id: Option<UserId>) -> Self {
+        self.tenant_id = Some(tenant_id);
+        self.user_id = user_id;
+        self
+    }
+}
+
+// =============================================================================
+// Execution Event (Base Event Type)
+// =============================================================================
+
+/// ExecutionEvent - Base event schema for all execution events
+///
+/// All events include execution context for traceability.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ExecutionEvent {
+    /// Unique event ID
+    pub event_id: String,
+
+    /// Event type
+    pub event_type: ExecutionEventType,
+
+    /// Execution context
+    pub context: ExecutionContext,
+
+    /// Timestamp
+    pub timestamp: chrono::DateTime<chrono::Utc>,
+
+    /// Duration in milliseconds (for start/end pairs)
+    pub duration_ms: Option<u64>,
+
+    /// Event-specific payload
+    pub payload: Option<serde_json::Value>,
+}
+
+impl ExecutionEvent {
+    /// Create a new ExecutionEvent
+    pub fn new(event_type: ExecutionEventType, context: ExecutionContext) -> Self {
+        Self {
+            event_id: new_event_id(),
+            event_type,
+            context,
+            timestamp: chrono::Utc::now(),
+            duration_ms: None,
+            payload: None,
+        }
+    }
+
+    /// Add duration
+    pub fn with_duration(mut self, ms: u64) -> Self {
+        self.duration_ms = Some(ms);
+        self
+    }
+
+    /// Add payload
+    pub fn with_payload(mut self, payload: serde_json::Value) -> Self {
+        self.payload = Some(payload);
+        self
+    }
+
+    // --- Factory methods for common events ---
+
+    /// Create an execution.start event
+    pub fn execution_start(execution_id: ExecutionId, parent: Option<ParentLink>) -> Self {
+        let mut ctx = ExecutionContext::new(execution_id);
+        if let Some(p) = parent {
+            ctx = ctx.with_parent(p);
+        }
+        Self::new(ExecutionEventType::ExecutionStart, ctx)
+    }
+
+    /// Create an execution.end event
+    pub fn execution_end(execution_id: ExecutionId, duration_ms: Option<u64>) -> Self {
+        let ctx = ExecutionContext::new(execution_id);
+        let mut event = Self::new(ExecutionEventType::ExecutionEnd, ctx);
+        event.duration_ms = duration_ms;
+        event
+    }
+
+    /// Create a step.start event
+    pub fn step_start(
+        execution_id: ExecutionId,
+        step_id: StepId,
+        step_type: StepType,
+        name: &str,
+    ) -> Self {
+        let ctx = ExecutionContext::new(execution_id).with_step(step_id);
+        Self::new(ExecutionEventType::StepStart, ctx).with_payload(serde_json::json!({
+            "step_type": step_type.to_string(),
+            "name": name,
+        }))
+    }
+
+    /// Create a step.end event
+    pub fn step_end(execution_id: ExecutionId, step_id: StepId, duration_ms: u64) -> Self {
+        let ctx = ExecutionContext::new(execution_id).with_step(step_id);
+        Self::new(ExecutionEventType::StepEnd, ctx).with_duration(duration_ms)
+    }
+
+    /// Create an artifact.created event
+    pub fn artifact_created(
+        execution_id: ExecutionId,
+        step_id: StepId,
+        artifact_id: ArtifactId,
+        artifact_type: &str,
+    ) -> Self {
+        let ctx = ExecutionContext::new(execution_id)
+            .with_step(step_id)
+            .with_artifact(artifact_id);
+        Self::new(ExecutionEventType::ArtifactCreated, ctx).with_payload(serde_json::json!({
+            "artifact_type": artifact_type,
+        }))
+    }
+}
+
+// =============================================================================
+// Decision Record (Audit Trail)
+// =============================================================================
+
+/// DecisionType - Types of decisions made during execution
+///
+/// @see packages/enact-schemas/src/streaming.schemas.ts - decisionEventDataSchema.type
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DecisionType {
+    /// Route selection (which agent/node to call)
+    Routing,
+    /// Conditional branch decision
+    Branch,
+    /// HITL approval decision
+    Approval,
+    /// Escalate to human
+    Escalation,
+    /// Retry failed operation
+    Retry,
+    /// Use fallback strategy
+    Fallback,
+    /// Policy evaluation decision
+    PolicyEvaluation,
+    /// Tool selection decision
+    ToolSelection,
+    /// Rejection decision
+    Rejection,
+}
+
+/// DecisionInput - Inputs that informed the decision
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DecisionInput {
+    /// Facts used in decision
+    pub facts: Vec<String>,
+    /// Constraints applied
+    pub constraints: Vec<String>,
+    /// Evidence IDs (artifacts, memory, RAG results)
+    pub evidence_ids: Vec<String>,
+}
+
+/// DecisionAlternative - An alternative option that was not chosen
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DecisionAlternative {
+    /// Name/ID of the alternative
+    pub option: String,
+    /// Confidence score (0-1)
+    pub score: f64,
+    /// Why it was rejected
+    pub rejected_reason: String,
+}
+
+/// ModelContext - Model configuration used for decision
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ModelContext {
+    /// Provider (e.g., 'openai', 'anthropic')
+    pub provider: String,
+    /// Model (e.g., 'gpt-4', 'claude-3-opus')
+    pub model: String,
+    /// Model version
+    pub version: Option<String>,
+    /// Temperature
+    pub temperature: Option<f64>,
+    /// Max tokens
+    pub max_tokens: Option<u32>,
+}
+
+/// DecisionRecord - Audit trail for decisions made during execution
+///
+/// Records what decision was made, why, what alternatives were considered,
+/// and what context/model was used.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DecisionRecord {
+    /// Unique decision ID
+    pub decision_id: String,
+
+    /// Execution context
+    pub execution_id: ExecutionId,
+    pub step_id: Option<StepId>,
+
+    /// Decision metadata
+    pub decision_type: DecisionType,
+    pub timestamp: chrono::DateTime<chrono::Utc>,
+
+    /// Decision outcome
+    pub outcome: String,
+    /// Confidence in decision (0-1)
+    pub confidence: f64,
+
+    /// Decision inputs
+    pub inputs: DecisionInput,
+
+    /// Alternatives considered
+    pub alternatives: Option<Vec<DecisionAlternative>>,
+
+    /// Model context (if LLM was used)
+    pub model_context: Option<ModelContext>,
+
+    /// Reasoning trace (optional explanation)
+    pub reasoning: Option<String>,
+}
+
+impl DecisionRecord {
+    /// Create a new DecisionRecord
+    pub fn new(
+        decision_type: DecisionType,
+        execution_id: ExecutionId,
+        outcome: impl Into<String>,
+        confidence: f64,
+        inputs: DecisionInput,
+    ) -> Self {
+        Self {
+            decision_id: format!("dec_{}", Ksuid::new(None, None)),
+            execution_id,
+            step_id: None,
+            decision_type,
+            timestamp: chrono::Utc::now(),
+            outcome: outcome.into(),
+            confidence,
+            inputs,
+            alternatives: None,
+            model_context: None,
+            reasoning: None,
+        }
+    }
+
+    /// Add step context
+    pub fn with_step(mut self, step_id: StepId) -> Self {
+        self.step_id = Some(step_id);
+        self
+    }
+
+    /// Add alternatives
+    pub fn with_alternatives(mut self, alternatives: Vec<DecisionAlternative>) -> Self {
+        self.alternatives = Some(alternatives);
+        self
+    }
+
+    /// Add model context
+    pub fn with_model_context(mut self, model_context: ModelContext) -> Self {
+        self.model_context = Some(model_context);
+        self
+    }
+
+    /// Add reasoning
+    pub fn with_reasoning(mut self, reasoning: impl Into<String>) -> Self {
+        self.reasoning = Some(reasoning.into());
+        self
+    }
+}
+
+// =============================================================================
+// Control Events (Governance)
+// =============================================================================
+
+/// ControlActor - Who/what initiated the control action
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ControlActor {
+    /// System-initiated (timeout, policy)
+    System,
+    /// User-initiated (button click)
+    User,
+    /// Agent-initiated (self-regulation)
+    Agent,
+    /// Policy engine decision
+    PolicyEngine,
+}
+
+/// ControlAction - What control action was requested
+///
+/// @see packages/enact-schemas/src/streaming.schemas.ts - controlSignalTypeSchema
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ControlAction {
+    /// Stop execution completely
+    Stop,
+    /// Pause execution
+    Pause,
+    /// Resume execution
+    Resume,
+    /// Cancel execution
+    Cancel,
+    /// Approve HITL request
+    Approve,
+    /// Deny HITL request
+    Deny,
+    /// Escalate to human
+    Escalate,
+}
+
+/// ControlOutcome - What happened as a result of the control action
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ControlOutcome {
+    /// Action was allowed and applied
+    Allowed,
+    /// Action was denied by policy
+    Denied,
+    /// Action was modified/adapted
+    Modified,
+    /// Action was escalated for approval
+    Escalated,
+}
+
+/// ControlEvent - Governance event for control signals
+///
+/// Records who requested what action, why, and what the outcome was.
+/// Used for audit trails and compliance.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ControlEvent {
+    /// Unique event ID
+    pub event_id: String,
+
+    /// Execution context
+    pub execution_id: ExecutionId,
+    pub step_id: Option<StepId>,
+
+    /// Control metadata
+    pub timestamp: chrono::DateTime<chrono::Utc>,
+    pub actor: ControlActor,
+    pub action: ControlAction,
+
+    /// Reasoning
+    pub reason: String,
+
+    /// Outcome
+    pub outcome: ControlOutcome,
+
+    /// Actor details (User ID, agent ID, etc.)
+    pub actor_id: Option<String>,
+}
+
+impl ControlEvent {
+    /// Create a new ControlEvent
+    pub fn new(
+        actor: ControlActor,
+        action: ControlAction,
+        execution_id: ExecutionId,
+        reason: impl Into<String>,
+        outcome: ControlOutcome,
+    ) -> Self {
+        Self {
+            event_id: format!("ctrl_{}", Ksuid::new(None, None)),
+            execution_id,
+            step_id: None,
+            timestamp: chrono::Utc::now(),
+            actor,
+            action,
+            reason: reason.into(),
+            outcome,
+            actor_id: None,
+        }
+    }
+
+    /// Add step context
+    pub fn with_step(mut self, step_id: StepId) -> Self {
+        self.step_id = Some(step_id);
+        self
+    }
+
+    /// Add actor ID
+    pub fn with_actor_id(mut self, actor_id: impl Into<String>) -> Self {
+        self.actor_id = Some(actor_id.into());
+        self
+    }
+
+    // --- Factory methods for common control events ---
+
+    /// Create a pause control event
+    pub fn pause(
+        execution_id: ExecutionId,
+        actor: ControlActor,
+        reason: impl Into<String>,
+    ) -> Self {
+        Self::new(
+            actor,
+            ControlAction::Pause,
+            execution_id,
+            reason,
+            ControlOutcome::Allowed,
+        )
+    }
+
+    /// Create a resume control event
+    pub fn resume(
+        execution_id: ExecutionId,
+        actor: ControlActor,
+        reason: impl Into<String>,
+    ) -> Self {
+        Self::new(
+            actor,
+            ControlAction::Resume,
+            execution_id,
+            reason,
+            ControlOutcome::Allowed,
+        )
+    }
+
+    /// Create a cancel control event
+    pub fn cancel(
+        execution_id: ExecutionId,
+        actor: ControlActor,
+        reason: impl Into<String>,
+    ) -> Self {
+        Self::new(
+            actor,
+            ControlAction::Cancel,
+            execution_id,
+            reason,
+            ControlOutcome::Allowed,
+        )
+    }
+}
+
+// =============================================================================
+// Legacy Event (Backward Compatibility)
+// =============================================================================
+
+/// Event - Alias for ExecutionEvent
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Event {
+    /// Event ID
+    pub id: String,
+    /// Run context (now ExecutionId)
+    pub run_id: ExecutionId,
+    /// Node context (now StepId)
+    pub node_id: Option<StepId>,
+    /// Event author (agent name, tool name, etc.)
+    pub author: String,
+    /// Timestamp
+    pub timestamp: chrono::DateTime<chrono::Utc>,
+    /// Event content
+    pub content: Option<String>,
+    /// Is this the final response?
+    pub is_final: bool,
+}
+
+impl Event {
+    pub fn new(run_id: ExecutionId, author: impl Into<String>) -> Self {
+        Self {
+            id: new_event_id(),
+            run_id,
+            node_id: None,
+            author: author.into(),
+            timestamp: chrono::Utc::now(),
+            content: None,
+            is_final: false,
+        }
+    }
+
+    pub fn with_content(mut self, content: impl Into<String>) -> Self {
+        self.content = Some(content.into());
+        self
+    }
+
+    pub fn with_node(mut self, node_id: StepId) -> Self {
+        self.node_id = Some(node_id);
+        self
+    }
+
+    pub fn final_response(mut self) -> Self {
+        self.is_final = true;
+        self
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // =========================================================================
+    // ExecutionEventType Tests
+    // =========================================================================
+
+    #[test]
+    fn test_execution_event_type_as_str_execution_start() {
+        assert_eq!(
+            ExecutionEventType::ExecutionStart.as_str(),
+            "execution.start"
+        );
+    }
+
+    #[test]
+    fn test_execution_event_type_as_str_execution_end() {
+        assert_eq!(ExecutionEventType::ExecutionEnd.as_str(), "execution.end");
+    }
+
+    #[test]
+    fn test_execution_event_type_as_str_execution_failed() {
+        assert_eq!(
+            ExecutionEventType::ExecutionFailed.as_str(),
+            "execution.failed"
+        );
+    }
+
+    #[test]
+    fn test_execution_event_type_as_str_execution_cancelled() {
+        assert_eq!(
+            ExecutionEventType::ExecutionCancelled.as_str(),
+            "execution.cancelled"
+        );
+    }
+
+    #[test]
+    fn test_execution_event_type_as_str_step_start() {
+        assert_eq!(ExecutionEventType::StepStart.as_str(), "step.start");
+    }
+
+    #[test]
+    fn test_execution_event_type_as_str_step_end() {
+        assert_eq!(ExecutionEventType::StepEnd.as_str(), "step.end");
+    }
+
+    #[test]
+    fn test_execution_event_type_as_str_step_failed() {
+        assert_eq!(ExecutionEventType::StepFailed.as_str(), "step.failed");
+    }
+
+    #[test]
+    fn test_execution_event_type_as_str_artifact_created() {
+        assert_eq!(
+            ExecutionEventType::ArtifactCreated.as_str(),
+            "artifact.created"
+        );
+    }
+
+    #[test]
+    fn test_execution_event_type_as_str_state_snapshot() {
+        assert_eq!(ExecutionEventType::StateSnapshot.as_str(), "state.snapshot");
+    }
+
+    #[test]
+    fn test_execution_event_type_as_str_decision_made() {
+        assert_eq!(ExecutionEventType::DecisionMade.as_str(), "decision.made");
+    }
+
+    #[test]
+    fn test_execution_event_type_as_str_control_pause() {
+        assert_eq!(ExecutionEventType::ControlPause.as_str(), "control.pause");
+    }
+
+    #[test]
+    fn test_execution_event_type_as_str_control_resume() {
+        assert_eq!(ExecutionEventType::ControlResume.as_str(), "control.resume");
+    }
+
+    #[test]
+    fn test_execution_event_type_as_str_control_cancel() {
+        assert_eq!(ExecutionEventType::ControlCancel.as_str(), "control.cancel");
+    }
+
+    #[test]
+    fn test_execution_event_type_serde() {
+        let event_type = ExecutionEventType::ExecutionStart;
+        let json = serde_json::to_string(&event_type).unwrap();
+        let parsed: ExecutionEventType = serde_json::from_str(&json).unwrap();
+        assert_eq!(event_type, parsed);
+    }
+
+    #[test]
+    fn test_execution_event_type_equality() {
+        assert_eq!(ExecutionEventType::StepStart, ExecutionEventType::StepStart);
+        assert_ne!(ExecutionEventType::StepStart, ExecutionEventType::StepEnd);
+    }
+
+    // =========================================================================
+    // ExecutionContext Tests
+    // =========================================================================
+
+    #[test]
+    fn test_execution_context_new() {
+        let exec_id = ExecutionId::from_string("exec_test");
+        let ctx = ExecutionContext::new(exec_id.clone());
+        assert_eq!(ctx.execution_id.as_str(), "exec_test");
+        assert!(ctx.step_id.is_none());
+        assert!(ctx.artifact_id.is_none());
+        assert!(ctx.parent.is_none());
+        assert!(ctx.tenant_id.is_none());
+        assert!(ctx.user_id.is_none());
+    }
+
+    #[test]
+    fn test_execution_context_with_step() {
+        let exec_id = ExecutionId::from_string("exec_test");
+        let step_id = StepId::from_string("step_test");
+        let ctx = ExecutionContext::new(exec_id).with_step(step_id.clone());
+        assert!(ctx.step_id.is_some());
+        assert_eq!(ctx.step_id.unwrap().as_str(), "step_test");
+    }
+
+    #[test]
+    fn test_execution_context_with_artifact() {
+        let exec_id = ExecutionId::from_string("exec_test");
+        let artifact_id = ArtifactId::from_string("artifact_test");
+        let ctx = ExecutionContext::new(exec_id).with_artifact(artifact_id);
+        assert!(ctx.artifact_id.is_some());
+        assert_eq!(ctx.artifact_id.unwrap().as_str(), "artifact_test");
+    }
+
+    #[test]
+    fn test_execution_context_with_parent() {
+        let exec_id = ExecutionId::from_string("exec_test");
+        let parent = ParentLink::from_user_message("msg_123");
+        let ctx = ExecutionContext::new(exec_id).with_parent(parent);
+        assert!(ctx.parent.is_some());
+        assert_eq!(ctx.parent.unwrap().parent_id, "msg_123");
+    }
+
+    #[test]
+    fn test_execution_context_with_tenant() {
+        let exec_id = ExecutionId::from_string("exec_test");
+        let tenant_id = TenantId::from_string("tenant_test");
+        let user_id = UserId::from_string("user_test");
+        let ctx = ExecutionContext::new(exec_id).with_tenant(tenant_id, Some(user_id));
+        assert!(ctx.tenant_id.is_some());
+        assert!(ctx.user_id.is_some());
+        assert_eq!(ctx.tenant_id.unwrap().as_str(), "tenant_test");
+        assert_eq!(ctx.user_id.unwrap().as_str(), "user_test");
+    }
+
+    #[test]
+    fn test_execution_context_builder_chain() {
+        let exec_id = ExecutionId::from_string("exec_chain");
+        let step_id = StepId::from_string("step_chain");
+        let artifact_id = ArtifactId::from_string("artifact_chain");
+        let parent = ParentLink::system();
+        let tenant_id = TenantId::from_string("tenant_chain");
+
+        let ctx = ExecutionContext::new(exec_id)
+            .with_step(step_id)
+            .with_artifact(artifact_id)
+            .with_parent(parent)
+            .with_tenant(tenant_id, None);
+
+        assert!(ctx.step_id.is_some());
+        assert!(ctx.artifact_id.is_some());
+        assert!(ctx.parent.is_some());
+        assert!(ctx.tenant_id.is_some());
+        assert!(ctx.user_id.is_none());
+    }
+
+    #[test]
+    fn test_execution_context_serde() {
+        let exec_id = ExecutionId::from_string("exec_serde");
+        let ctx = ExecutionContext::new(exec_id);
+        let json = serde_json::to_string(&ctx).unwrap();
+        let parsed: ExecutionContext = serde_json::from_str(&json).unwrap();
+        assert_eq!(ctx.execution_id.as_str(), parsed.execution_id.as_str());
+    }
+
+    // =========================================================================
+    // ExecutionEvent Tests
+    // =========================================================================
+
+    #[test]
+    fn test_execution_event_new() {
+        let ctx = ExecutionContext::new(ExecutionId::from_string("exec_test"));
+        let event = ExecutionEvent::new(ExecutionEventType::ExecutionStart, ctx);
+        assert!(event.event_id.starts_with("evt_"));
+        assert_eq!(event.event_type, ExecutionEventType::ExecutionStart);
+        assert!(event.duration_ms.is_none());
+        assert!(event.payload.is_none());
+    }
+
+    #[test]
+    fn test_execution_event_with_duration() {
+        let ctx = ExecutionContext::new(ExecutionId::from_string("exec_test"));
+        let event = ExecutionEvent::new(ExecutionEventType::StepEnd, ctx).with_duration(1500);
+        assert_eq!(event.duration_ms, Some(1500));
+    }
+
+    #[test]
+    fn test_execution_event_with_payload() {
+        let ctx = ExecutionContext::new(ExecutionId::from_string("exec_test"));
+        let payload = serde_json::json!({"key": "value"});
+        let event =
+            ExecutionEvent::new(ExecutionEventType::StepStart, ctx).with_payload(payload.clone());
+        assert!(event.payload.is_some());
+        assert_eq!(event.payload.unwrap(), payload);
+    }
+
+    #[test]
+    fn test_execution_event_execution_start() {
+        let exec_id = ExecutionId::from_string("exec_start");
+        let event = ExecutionEvent::execution_start(exec_id, None);
+        assert_eq!(event.event_type, ExecutionEventType::ExecutionStart);
+        assert!(event.context.parent.is_none());
+    }
+
+    #[test]
+    fn test_execution_event_execution_start_with_parent() {
+        let exec_id = ExecutionId::from_string("exec_start");
+        let parent = ParentLink::from_user_message("msg_trigger");
+        let event = ExecutionEvent::execution_start(exec_id, Some(parent));
+        assert_eq!(event.event_type, ExecutionEventType::ExecutionStart);
+        assert!(event.context.parent.is_some());
+    }
+
+    #[test]
+    fn test_execution_event_execution_end() {
+        let exec_id = ExecutionId::from_string("exec_end");
+        let event = ExecutionEvent::execution_end(exec_id, Some(5000));
+        assert_eq!(event.event_type, ExecutionEventType::ExecutionEnd);
+        assert_eq!(event.duration_ms, Some(5000));
+    }
+
+    #[test]
+    fn test_execution_event_step_start() {
+        let exec_id = ExecutionId::from_string("exec_step");
+        let step_id = StepId::from_string("step_start");
+        let event = ExecutionEvent::step_start(exec_id, step_id, StepType::LlmNode, "test_step");
+        assert_eq!(event.event_type, ExecutionEventType::StepStart);
+        assert!(event.payload.is_some());
+        let payload = event.payload.unwrap();
+        assert_eq!(payload["name"], "test_step");
+    }
+
+    #[test]
+    fn test_execution_event_step_end() {
+        let exec_id = ExecutionId::from_string("exec_step");
+        let step_id = StepId::from_string("step_end");
+        let event = ExecutionEvent::step_end(exec_id, step_id, 1000);
+        assert_eq!(event.event_type, ExecutionEventType::StepEnd);
+        assert_eq!(event.duration_ms, Some(1000));
+    }
+
+    #[test]
+    fn test_execution_event_artifact_created() {
+        let exec_id = ExecutionId::from_string("exec_artifact");
+        let step_id = StepId::from_string("step_artifact");
+        let artifact_id = ArtifactId::from_string("artifact_created");
+        let event = ExecutionEvent::artifact_created(exec_id, step_id, artifact_id, "code");
+        assert_eq!(event.event_type, ExecutionEventType::ArtifactCreated);
+        assert!(event.context.artifact_id.is_some());
+        assert!(event.payload.is_some());
+        assert_eq!(event.payload.unwrap()["artifact_type"], "code");
+    }
+
+    #[test]
+    fn test_execution_event_serde() {
+        let ctx = ExecutionContext::new(ExecutionId::from_string("exec_serde"));
+        let event = ExecutionEvent::new(ExecutionEventType::ExecutionStart, ctx);
+        let json = serde_json::to_string(&event).unwrap();
+        let parsed: ExecutionEvent = serde_json::from_str(&json).unwrap();
+        assert_eq!(event.event_type, parsed.event_type);
+    }
+
+    // =========================================================================
+    // DecisionType Tests
+    // =========================================================================
+
+    #[test]
+    fn test_decision_type_variants() {
+        let variants = vec![
+            DecisionType::Routing,
+            DecisionType::Branch,
+            DecisionType::Approval,
+            DecisionType::Escalation,
+            DecisionType::Retry,
+            DecisionType::Fallback,
+            DecisionType::PolicyEvaluation,
+            DecisionType::ToolSelection,
+            DecisionType::Rejection,
+        ];
+        for variant in variants {
+            let json = serde_json::to_string(&variant).unwrap();
+            let parsed: DecisionType = serde_json::from_str(&json).unwrap();
+            assert_eq!(variant, parsed);
+        }
+    }
+
+    #[test]
+    fn test_decision_type_equality() {
+        assert_eq!(DecisionType::Routing, DecisionType::Routing);
+        assert_ne!(DecisionType::Routing, DecisionType::Branch);
+    }
+
+    // =========================================================================
+    // DecisionInput Tests
+    // =========================================================================
+
+    #[test]
+    fn test_decision_input_creation() {
+        let input = DecisionInput {
+            facts: vec!["fact1".to_string(), "fact2".to_string()],
+            constraints: vec!["constraint1".to_string()],
+            evidence_ids: vec!["ev_123".to_string()],
+        };
+        assert_eq!(input.facts.len(), 2);
+        assert_eq!(input.constraints.len(), 1);
+        assert_eq!(input.evidence_ids.len(), 1);
+    }
+
+    #[test]
+    fn test_decision_input_serde() {
+        let input = DecisionInput {
+            facts: vec!["fact1".to_string()],
+            constraints: vec![],
+            evidence_ids: vec![],
+        };
+        let json = serde_json::to_string(&input).unwrap();
+        let parsed: DecisionInput = serde_json::from_str(&json).unwrap();
+        assert_eq!(input.facts, parsed.facts);
+    }
+
+    // =========================================================================
+    // DecisionAlternative Tests
+    // =========================================================================
+
+    #[test]
+    fn test_decision_alternative_creation() {
+        let alt = DecisionAlternative {
+            option: "option_b".to_string(),
+            score: 0.75,
+            rejected_reason: "Lower confidence".to_string(),
+        };
+        assert_eq!(alt.option, "option_b");
+        assert_eq!(alt.score, 0.75);
+    }
+
+    #[test]
+    fn test_decision_alternative_serde() {
+        let alt = DecisionAlternative {
+            option: "alt".to_string(),
+            score: 0.5,
+            rejected_reason: "reason".to_string(),
+        };
+        let json = serde_json::to_string(&alt).unwrap();
+        let parsed: DecisionAlternative = serde_json::from_str(&json).unwrap();
+        assert_eq!(alt.option, parsed.option);
+        assert_eq!(alt.score, parsed.score);
+    }
+
+    // =========================================================================
+    // ModelContext Tests
+    // =========================================================================
+
+    #[test]
+    fn test_model_context_creation() {
+        let ctx = ModelContext {
+            provider: "anthropic".to_string(),
+            model: "claude-3-opus".to_string(),
+            version: Some("2024".to_string()),
+            temperature: Some(0.7),
+            max_tokens: Some(1000),
+        };
+        assert_eq!(ctx.provider, "anthropic");
+        assert_eq!(ctx.model, "claude-3-opus");
+        assert!(ctx.temperature.is_some());
+    }
+
+    #[test]
+    fn test_model_context_minimal() {
+        let ctx = ModelContext {
+            provider: "openai".to_string(),
+            model: "gpt-4".to_string(),
+            version: None,
+            temperature: None,
+            max_tokens: None,
+        };
+        assert!(ctx.version.is_none());
+        assert!(ctx.temperature.is_none());
+    }
+
+    #[test]
+    fn test_model_context_serde() {
+        let ctx = ModelContext {
+            provider: "test".to_string(),
+            model: "test-model".to_string(),
+            version: None,
+            temperature: Some(0.5),
+            max_tokens: None,
+        };
+        let json = serde_json::to_string(&ctx).unwrap();
+        let parsed: ModelContext = serde_json::from_str(&json).unwrap();
+        assert_eq!(ctx.provider, parsed.provider);
+        assert_eq!(ctx.temperature, parsed.temperature);
+    }
+
+    // =========================================================================
+    // DecisionRecord Tests
+    // =========================================================================
+
+    #[test]
+    fn test_decision_record_new() {
+        let exec_id = ExecutionId::from_string("exec_decision");
+        let input = DecisionInput {
+            facts: vec!["fact".to_string()],
+            constraints: vec![],
+            evidence_ids: vec![],
+        };
+        let record = DecisionRecord::new(DecisionType::Routing, exec_id, "agent_a", 0.95, input);
+        assert!(record.decision_id.starts_with("dec_"));
+        assert_eq!(record.decision_type, DecisionType::Routing);
+        assert_eq!(record.outcome, "agent_a");
+        assert_eq!(record.confidence, 0.95);
+    }
+
+    #[test]
+    fn test_decision_record_with_step() {
+        let exec_id = ExecutionId::from_string("exec_decision");
+        let step_id = StepId::from_string("step_decision");
+        let input = DecisionInput {
+            facts: vec![],
+            constraints: vec![],
+            evidence_ids: vec![],
+        };
+        let record = DecisionRecord::new(DecisionType::Branch, exec_id, "yes", 0.8, input)
+            .with_step(step_id);
+        assert!(record.step_id.is_some());
+    }
+
+    #[test]
+    fn test_decision_record_with_alternatives() {
+        let exec_id = ExecutionId::from_string("exec_decision");
+        let input = DecisionInput {
+            facts: vec![],
+            constraints: vec![],
+            evidence_ids: vec![],
+        };
+        let alternatives = vec![DecisionAlternative {
+            option: "option_b".to_string(),
+            score: 0.6,
+            rejected_reason: "Lower score".to_string(),
+        }];
+        let record = DecisionRecord::new(DecisionType::Routing, exec_id, "option_a", 0.9, input)
+            .with_alternatives(alternatives);
+        assert!(record.alternatives.is_some());
+        assert_eq!(record.alternatives.unwrap().len(), 1);
+    }
+
+    #[test]
+    fn test_decision_record_with_model_context() {
+        let exec_id = ExecutionId::from_string("exec_decision");
+        let input = DecisionInput {
+            facts: vec![],
+            constraints: vec![],
+            evidence_ids: vec![],
+        };
+        let model_ctx = ModelContext {
+            provider: "anthropic".to_string(),
+            model: "claude".to_string(),
+            version: None,
+            temperature: None,
+            max_tokens: None,
+        };
+        let record = DecisionRecord::new(DecisionType::Approval, exec_id, "approved", 1.0, input)
+            .with_model_context(model_ctx);
+        assert!(record.model_context.is_some());
+    }
+
+    #[test]
+    fn test_decision_record_with_reasoning() {
+        let exec_id = ExecutionId::from_string("exec_decision");
+        let input = DecisionInput {
+            facts: vec![],
+            constraints: vec![],
+            evidence_ids: vec![],
+        };
+        let record =
+            DecisionRecord::new(DecisionType::Escalation, exec_id, "escalated", 0.5, input)
+                .with_reasoning("Confidence too low for autonomous action");
+        assert!(record.reasoning.is_some());
+        assert!(record.reasoning.unwrap().contains("Confidence"));
+    }
+
+    #[test]
+    fn test_decision_record_serde() {
+        let exec_id = ExecutionId::from_string("exec_serde");
+        let input = DecisionInput {
+            facts: vec!["f".to_string()],
+            constraints: vec![],
+            evidence_ids: vec![],
+        };
+        let record = DecisionRecord::new(DecisionType::Retry, exec_id, "retry", 0.7, input);
+        let json = serde_json::to_string(&record).unwrap();
+        let parsed: DecisionRecord = serde_json::from_str(&json).unwrap();
+        assert_eq!(record.decision_type, parsed.decision_type);
+    }
+
+    // =========================================================================
+    // ControlActor Tests
+    // =========================================================================
+
+    #[test]
+    fn test_control_actor_variants() {
+        let variants = vec![
+            ControlActor::System,
+            ControlActor::User,
+            ControlActor::Agent,
+            ControlActor::PolicyEngine,
+        ];
+        for variant in variants {
+            let json = serde_json::to_string(&variant).unwrap();
+            let parsed: ControlActor = serde_json::from_str(&json).unwrap();
+            assert_eq!(variant, parsed);
+        }
+    }
+
+    #[test]
+    fn test_control_actor_equality() {
+        assert_eq!(ControlActor::System, ControlActor::System);
+        assert_ne!(ControlActor::System, ControlActor::User);
+    }
+
+    // =========================================================================
+    // ControlAction Tests
+    // =========================================================================
+
+    #[test]
+    fn test_control_action_variants() {
+        let variants = vec![
+            ControlAction::Stop,
+            ControlAction::Pause,
+            ControlAction::Resume,
+            ControlAction::Cancel,
+            ControlAction::Approve,
+            ControlAction::Deny,
+            ControlAction::Escalate,
+        ];
+        for variant in variants {
+            let json = serde_json::to_string(&variant).unwrap();
+            let parsed: ControlAction = serde_json::from_str(&json).unwrap();
+            assert_eq!(variant, parsed);
+        }
+    }
+
+    // =========================================================================
+    // ControlOutcome Tests
+    // =========================================================================
+
+    #[test]
+    fn test_control_outcome_variants() {
+        let variants = vec![
+            ControlOutcome::Allowed,
+            ControlOutcome::Denied,
+            ControlOutcome::Modified,
+            ControlOutcome::Escalated,
+        ];
+        for variant in variants {
+            let json = serde_json::to_string(&variant).unwrap();
+            let parsed: ControlOutcome = serde_json::from_str(&json).unwrap();
+            assert_eq!(variant, parsed);
+        }
+    }
+
+    // =========================================================================
+    // ControlEvent Tests
+    // =========================================================================
+
+    #[test]
+    fn test_control_event_new() {
+        let exec_id = ExecutionId::from_string("exec_ctrl");
+        let event = ControlEvent::new(
+            ControlActor::User,
+            ControlAction::Pause,
+            exec_id,
+            "User requested pause",
+            ControlOutcome::Allowed,
+        );
+        assert!(event.event_id.starts_with("ctrl_"));
+        assert_eq!(event.actor, ControlActor::User);
+        assert_eq!(event.action, ControlAction::Pause);
+        assert_eq!(event.outcome, ControlOutcome::Allowed);
+    }
+
+    #[test]
+    fn test_control_event_with_step() {
+        let exec_id = ExecutionId::from_string("exec_ctrl");
+        let step_id = StepId::from_string("step_ctrl");
+        let event = ControlEvent::new(
+            ControlActor::System,
+            ControlAction::Cancel,
+            exec_id,
+            "Timeout",
+            ControlOutcome::Allowed,
+        )
+        .with_step(step_id);
+        assert!(event.step_id.is_some());
+    }
+
+    #[test]
+    fn test_control_event_with_actor_id() {
+        let exec_id = ExecutionId::from_string("exec_ctrl");
+        let event = ControlEvent::new(
+            ControlActor::User,
+            ControlAction::Approve,
+            exec_id,
+            "Approved by admin",
+            ControlOutcome::Allowed,
+        )
+        .with_actor_id("user_admin_123");
+        assert!(event.actor_id.is_some());
+        assert_eq!(event.actor_id.unwrap(), "user_admin_123");
+    }
+
+    #[test]
+    fn test_control_event_pause_factory() {
+        let exec_id = ExecutionId::from_string("exec_pause");
+        let event = ControlEvent::pause(exec_id, ControlActor::User, "Pausing for review");
+        assert_eq!(event.action, ControlAction::Pause);
+        assert_eq!(event.actor, ControlActor::User);
+        assert_eq!(event.outcome, ControlOutcome::Allowed);
+    }
+
+    #[test]
+    fn test_control_event_resume_factory() {
+        let exec_id = ExecutionId::from_string("exec_resume");
+        let event = ControlEvent::resume(exec_id, ControlActor::User, "Resuming after review");
+        assert_eq!(event.action, ControlAction::Resume);
+    }
+
+    #[test]
+    fn test_control_event_cancel_factory() {
+        let exec_id = ExecutionId::from_string("exec_cancel");
+        let event = ControlEvent::cancel(exec_id, ControlActor::System, "System timeout");
+        assert_eq!(event.action, ControlAction::Cancel);
+        assert_eq!(event.actor, ControlActor::System);
+    }
+
+    #[test]
+    fn test_control_event_serde() {
+        let exec_id = ExecutionId::from_string("exec_serde");
+        let event = ControlEvent::pause(exec_id, ControlActor::Agent, "Self-regulation");
+        let json = serde_json::to_string(&event).unwrap();
+        let parsed: ControlEvent = serde_json::from_str(&json).unwrap();
+        assert_eq!(event.action, parsed.action);
+        assert_eq!(event.actor, parsed.actor);
+    }
+
+    // =========================================================================
+    // Legacy Event Tests
+    // =========================================================================
+
+    #[test]
+    fn test_event_new() {
+        let run_id = ExecutionId::from_string("exec_legacy");
+        let event = Event::new(run_id, "test_author");
+        assert!(event.id.starts_with("evt_"));
+        assert_eq!(event.author, "test_author");
+        assert!(!event.is_final);
+        assert!(event.content.is_none());
+        assert!(event.node_id.is_none());
+    }
+
+    #[test]
+    fn test_event_with_content() {
+        let run_id = ExecutionId::from_string("exec_legacy");
+        let event = Event::new(run_id, "author").with_content("Hello, world!");
+        assert!(event.content.is_some());
+        assert_eq!(event.content.unwrap(), "Hello, world!");
+    }
+
+    #[test]
+    fn test_event_with_node() {
+        let run_id = ExecutionId::from_string("exec_legacy");
+        let node_id = StepId::from_string("step_legacy");
+        let event = Event::new(run_id, "author").with_node(node_id.clone());
+        assert!(event.node_id.is_some());
+        assert_eq!(event.node_id.unwrap().as_str(), "step_legacy");
+    }
+
+    #[test]
+    fn test_event_final_response() {
+        let run_id = ExecutionId::from_string("exec_legacy");
+        let event = Event::new(run_id, "author").final_response();
+        assert!(event.is_final);
+    }
+
+    #[test]
+    fn test_event_builder_chain() {
+        let run_id = ExecutionId::from_string("exec_chain");
+        let node_id = StepId::from_string("step_chain");
+        let event = Event::new(run_id, "test")
+            .with_content("Content here")
+            .with_node(node_id)
+            .final_response();
+        assert!(event.content.is_some());
+        assert!(event.node_id.is_some());
+        assert!(event.is_final);
+    }
+
+    #[test]
+    fn test_event_serde() {
+        let run_id = ExecutionId::from_string("exec_serde");
+        let event = Event::new(run_id, "author").with_content("test");
+        let json = serde_json::to_string(&event).unwrap();
+        let parsed: Event = serde_json::from_str(&json).unwrap();
+        assert_eq!(event.author, parsed.author);
+    }
+
+    // =========================================================================
+    // Event ID Format Tests
+    // =========================================================================
+
+    #[test]
+    fn test_event_id_format() {
+        let ctx = ExecutionContext::new(ExecutionId::from_string("exec_test"));
+        let event = ExecutionEvent::new(ExecutionEventType::ExecutionStart, ctx);
+        assert!(event.event_id.starts_with("evt_"));
+        // evt_ (4 chars) + KSUID (27 chars) = 31 chars
+        assert_eq!(event.event_id.len(), 31);
+    }
+
+    #[test]
+    fn test_decision_id_format() {
+        let exec_id = ExecutionId::from_string("exec_test");
+        let input = DecisionInput {
+            facts: vec![],
+            constraints: vec![],
+            evidence_ids: vec![],
+        };
+        let record = DecisionRecord::new(DecisionType::Routing, exec_id, "outcome", 0.9, input);
+        assert!(record.decision_id.starts_with("dec_"));
+    }
+
+    #[test]
+    fn test_control_event_id_format() {
+        let exec_id = ExecutionId::from_string("exec_test");
+        let event = ControlEvent::pause(exec_id, ControlActor::User, "test");
+        assert!(event.event_id.starts_with("ctrl_"));
+    }
+}