Skip to main content

Module engine

orcs_runtime

Module engine 

Source
Expand description

ORCS Engine - Runtime and EventBus.

This crate provides the core runtime infrastructure for ORCS (Orchestrated Runtime for Collaborative Systems).

§Architecture Overview

┌──────────────────────────────────────────────────────────────┐
│                     Human (Superpower)                       │
│              Veto / Sanction / Steer / Approve               │
└──────────────────────────────────────────────────────────────┘
                             │ Signal
                             ▼
┌──────────────────────────────────────────────────────────────┐
│                        OrcsEngine                            │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                      EventBus                          │  │
│  │   - Request/Response routing                           │  │
│  │   - Signal dispatch (highest priority)                 │  │
│  └────────────────────────────────────────────────────────┘  │
│                              │                                │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                       World                            │  │
│  │   - Channel spawn/kill                                 │  │
│  │   - Permission inheritance                             │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘
       │ EventBus
       ├──────────────┬──────────────┬──────────────┐
       ▼              ▼              ▼              ▼
 ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
 │   LLM    │   │  Tools   │   │   HIL    │   │  WASM    │
 │Component │   │Component │   │Component │   │Component │
 └──────────┘   └──────────┘   └──────────┘   └──────────┘

§Core Principles

§Human as Superpower

Human is NOT the LLM’s assistant - Human controls from above.

  • Veto: Stop everything immediately
  • Sanction: Stop specific processing
  • Steer: Intervene during execution
  • Approve/Reject: HIL (Human-in-the-Loop) approval

§EventBus Unified Communication

All Component communication flows through EventBus:

  • Request/Response: Synchronous queries
  • Signal: Human interrupts (highest priority)

§Component = Functional Domain Boundary

Components are flat but have clear responsibility separation. Engine focuses on infrastructure, guaranteeing Component implementation freedom.

§Main Types

§Error Handling

Engine operations return EngineError which implements orcs_types::ErrorCode. CLI/Application layer should convert these to user-facing errors.

Structs§

ComponentHandle
Handle for component to receive messages
EventBus
EventBus - routes messages between components and channels.
OrcsEngine
OrcsEngine - Main runtime for ORCS CLI.

Enums§

EngineError
Engine layer error.

Type Aliases§

SharedChannelHandles
Shared channel handles for event broadcasting.
SharedComponentChannelMap
Shared mapping from Component FQN to ChannelId for RPC routing.