orcs_runtime/engine/mod.rs
1//! ORCS Engine - Runtime and EventBus.
2//!
3//! This crate provides the core runtime infrastructure for ORCS
4//! (Orchestrated Runtime for Collaborative Systems).
5//!
6//! # Architecture Overview
7//!
8//! ```text
9//! ┌──────────────────────────────────────────────────────────────┐
10//! │ Human (Superpower) │
11//! │ Veto / Sanction / Steer / Approve │
12//! └──────────────────────────────────────────────────────────────┘
13//! │ Signal
14//! ▼
15//! ┌──────────────────────────────────────────────────────────────┐
16//! │ OrcsEngine │
17//! │ ┌────────────────────────────────────────────────────────┐ │
18//! │ │ EventBus │ │
19//! │ │ - Request/Response routing │ │
20//! │ │ - Signal dispatch (highest priority) │ │
21//! │ └────────────────────────────────────────────────────────┘ │
22//! │ │ │
23//! │ ┌────────────────────────────────────────────────────────┐ │
24//! │ │ World │ │
25//! │ │ - Channel spawn/kill │ │
26//! │ │ - Permission inheritance │ │
27//! │ └────────────────────────────────────────────────────────┘ │
28//! └──────────────────────────────────────────────────────────────┘
29//! │ EventBus
30//! ├──────────────┬──────────────┬──────────────┐
31//! ▼ ▼ ▼ ▼
32//! ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
33//! │ LLM │ │ Tools │ │ HIL │ │ WASM │
34//! │Component │ │Component │ │Component │ │Component │
35//! └──────────┘ └──────────┘ └──────────┘ └──────────┘
36//! ```
37//!
38//! # Core Principles
39//!
40//! ## Human as Superpower
41//!
42//! Human is NOT the LLM's assistant - Human controls from above.
43//!
44//! - **Veto**: Stop everything immediately
45//! - **Sanction**: Stop specific processing
46//! - **Steer**: Intervene during execution
47//! - **Approve/Reject**: HIL (Human-in-the-Loop) approval
48//!
49//! ## EventBus Unified Communication
50//!
51//! All Component communication flows through EventBus:
52//!
53//! - **Request/Response**: Synchronous queries
54//! - **Signal**: Human interrupts (highest priority)
55//!
56//! ## Component = Functional Domain Boundary
57//!
58//! Components are flat but have clear responsibility separation.
59//! Engine focuses on infrastructure, guaranteeing Component implementation freedom.
60//!
61//! # Main Types
62//!
63//! - [`OrcsEngine`]: Main runtime loop and lifecycle management
64//! - [`EventBus`]: Unified message routing between Components
65//! - [`ComponentHandle`]: Handle for Component to receive messages
66//! - [`EngineError`]: Engine layer errors (implements [`ErrorCode`])
67//!
68//! # Error Handling
69//!
70//! Engine operations return [`EngineError`] which implements [`orcs_types::ErrorCode`].
71//! CLI/Application layer should convert these to user-facing errors.
72//!
73//! [`ErrorCode`]: orcs_types::ErrorCode
74
75#[allow(clippy::module_inception)]
76mod engine;
77mod error;
78mod eventbus;
79
80pub use engine::OrcsEngine;
81pub use error::EngineError;
82pub use eventbus::{ComponentHandle, EventBus, SharedChannelHandles, SharedComponentChannelMap};