enact_core/kernel/
mod.rs

1//! Kernel - The Execution Engine
2//!
3//! The kernel is the heart of enact-core. It:
4//! - Defines the execution state machine
5//! - Applies all state transitions through a reducer
6//! - Provides the ExecutionKernel for running graphs
7//! - Enables replay from event logs
8//!
9//! ## Architecture
10//!
11//! ```text
12//! ┌─────────────────────────────────────────────┐
13//! │              ExecutionKernel                │
14//! │  ┌───────────────────────────────────────┐  │
15//! │  │           Execution State             │  │
16//! │  │  (ExecutionState, Steps, Artifacts)   │  │
17//! │  └───────────────────────────────────────┘  │
18//! │                     │                       │
19//! │                     ▼                       │
20//! │  ┌───────────────────────────────────────┐  │
21//! │  │              Reducer                  │  │
22//! │  │  (Action, State) → State              │  │
23//! │  └───────────────────────────────────────┘  │
24//! │                     │                       │
25//! │                     ▼                       │
26//! │  ┌───────────────────────────────────────┐  │
27//! │  │           Event Emitter               │  │
28//! │  │  (StreamEvent for UI/persistence)     │  │
29//! │  └───────────────────────────────────────┘  │
30//! └─────────────────────────────────────────────┘
31//! ```
32//!
33//! ## Key Invariants
34//!
35//! 1. **Single Source of Truth**: ExecutionKernel owns the Execution state
36//! 2. **Reducer-Only Transitions**: All state changes go through the reducer
37//! 3. **Deterministic**: Same actions → same state (enables replay)
38//! 4. **Observable**: All transitions emit events
39//!
40//! @see docs/TECHNICAL/01-EXECUTION-TELEMETRY.md
41
42pub mod artifact;
43pub mod cost;
44mod enforcement;
45mod error;
46mod event;
47mod execution_model;
48mod execution_state;
49mod execution_strategy;
50pub mod ids;
51mod interrupt;
52#[allow(clippy::module_inception)]
53mod kernel;
54pub mod persistence;
55mod reducer;
56mod replay;
57
58// =============================================================================
59// IDs - Source of Truth for all execution identifiers
60// =============================================================================
61pub use ids::{
62    // ID prefix constants
63    prefixes,
64    // Primary IDs
65    ArtifactId,
66    // Callable types (for billing/traceability)
67    CallableType,
68    CancellationPolicy,
69    ExecutionId,
70    GraphId,
71    // Message/Thread IDs (MessageStore)
72    MessageId,
73    NodeId,
74    // Parent linkage (causal tracing)
75    ParentLink,
76    ParentType,
77    RunId,
78    // SpawnMode (execution isolation control)
79    SpawnMode,
80    StepId,
81    // Step source (discovery tracking for agentic loops)
82    StepSource,
83    StepSourceType,
84    // Step/Node types
85    StepType,
86    TenantId,
87    ThreadId,
88    UserId,
89};
90
91// =============================================================================
92// Events - Source of Truth for all execution events
93// =============================================================================
94pub use event::{
95    // Control events
96    ControlAction,
97    ControlActor,
98    ControlEvent,
99    ControlOutcome,
100    // Decision audit
101    DecisionAlternative,
102    DecisionInput,
103    DecisionRecord,
104    DecisionType,
105    Event,
106    // Execution events
107    ExecutionContext,
108    ExecutionEvent,
109    ExecutionEventType,
110    ModelContext,
111};
112
113// =============================================================================
114// Core execution types
115// =============================================================================
116pub use execution_model::{Execution, Step};
117
118// State machine
119pub use execution_state::{ExecutionState, StepState, WaitReason};
120
121// Reducer
122pub use reducer::{reduce, ExecutionAction, ReducerError};
123
124// Replay
125pub use replay::{replay, EventLog, ReplayError};
126
127// The kernel itself
128pub use kernel::ExecutionKernel;
129
130// =============================================================================
131// Error Taxonomy (feat-02)
132// =============================================================================
133pub use error::{
134    // Retry policies
135    BackoffStrategy,
136    // Error categories
137    ExecutionError,
138    ExecutionErrorCategory,
139    // Specific error codes
140    LlmErrorCode,
141    RetryPolicy,
142    ToolErrorCode,
143};
144
145// =============================================================================
146// Enforcement & Limits (feat-03)
147// =============================================================================
148pub use enforcement::{
149    // Middleware
150    EnforcementMiddleware,
151    EnforcementPolicy,
152    // Enforcement results
153    EnforcementResult,
154    EnforcementViolation,
155    EnforcementWarning,
156    // Usage tracking
157    ExecutionUsage,
158    // Long-running execution policy (agentic DAG controls)
159    LongRunningExecutionPolicy,
160    // Timeout guard
161    StepTimeoutGuard,
162    UsageSnapshot,
163    ViolationType,
164};
165
166// =============================================================================
167// Execution strategy (parallel, interrupt handling)
168// =============================================================================
169pub use execution_strategy::{run_parallel, ParallelResult};
170pub use interrupt::{InterruptDecision, InterruptReason, InterruptableRunner};
171
172// =============================================================================
173// Persistence Layer (feat-05)
174// =============================================================================
175pub use persistence::{
176    // VectorStore
177    CollectionInfo,
178    // MessageStore
179    CostInfo,
180    DistanceMetric,
181    // EventStore
182    EventStore,
183    ExecutionEventData,
184    // StateStore
185    ExecutionSnapshot,
186    ExecutionStats,
187    FinishReason,
188    InMemoryMessageStore,
189    Message,
190    MessageMetadata,
191    MessagePart,
192    MessageRole,
193    MessageStore,
194    StateStore,
195    StateStoreJsonExt,
196    // Base trait
197    StorageBackend,
198    StoredEvent,
199    Thread,
200    TokenUsage,
201    VectorDocument,
202    VectorFilter,
203    VectorSearchResult,
204    VectorStore,
205};
206
207// =============================================================================
208// Cost & Usage Tracking (Observability)
209// =============================================================================
210pub use cost::{CostCalculator, ModelPricing, TokenUsage as LlmTokenUsage, UsageAccumulator};
enact_core/kernel/mod.rs

enact_core/kernel/
mod.rs
