ergo_runtime/lib.rs
1//! ergo_runtime
2//!
3//! Purpose:
4//! - Define the kernel-owned primitive ontology and the graph pipeline that
5//! turns a `ClusterDefinition` into an `ExecutionReport` (expand → validate
6//! → execute).
7//!
8//! Owns:
9//! - The four primitive trait families (source/compute/trigger/action) and
10//! their manifest types.
11//! - `CorePrimitiveCatalog`, `CoreRegistries`, and the stdlib primitive
12//! implementations registered through `build_core`.
13//! - Cluster expansion (`cluster::expand`), validation (`runtime::validate`),
14//! and synchronous execution (`runtime::execute_with_metadata`).
15//! - Typed runtime errors (`RuntimeError`, `ExecError`, `ValidationError`).
16//!
17//! Does not own:
18//! - The adapter contract, event binding, or runtime invoker handles
19//! (owned by `ergo_adapter`).
20//! - Episode scheduling, capture, or replay (owned by `ergo_supervisor`).
21//! - Host orchestration, I/O realization, or product-facing error shaping.
22//!
23//! Connects to:
24//! - `ergo_adapter`, which consumes catalogs/registries and re-exports
25//! `ExecutionContext` through its wrapper without redefining runtime
26//! meaning.
27//! - `ergo_supervisor`, which drives `execute_with_metadata` through a
28//! `RuntimeInvoker` and records decisions independently of runtime state.
29//!
30//! Safety notes:
31//! - The runtime is synchronous and single-threaded by construction. No
32//! concurrency primitive appears anywhere in this crate; adding one is a
33//! semantic change to the kernel threading model.
34//! - `CorePrimitiveCatalog` and `CoreRegistries` are build-once via
35//! `build_core` / `CatalogBuilder` and have no mutation API after
36//! construction; the `pub(crate) fn register_*` mutators are reachable
37//! only from `build_from_inventory`.
38//! - Three of the four primitive traits intentionally omit `Send + Sync`
39//! at v1; tightening those bounds is tracked in
40//! `docs/ledger/decisions/sdk-threading-send-sync.md` and would propagate
41//! structurally through `CoreRegistries`, `RuntimeState`, and every
42//! `*RuntimeHandle`.
43//! - Primitive `compute` accepts `Option<&mut PrimitiveState>` but the
44//! executor always passes `None`; statefulness is detected by
45//! capture/replay divergence rather than structural enforcement.
46
47pub const RUNTIME_VERSION: &str = env!("CARGO_PKG_VERSION");
48
49pub fn runtime_version() -> &'static str {
50 RUNTIME_VERSION
51}
52
53pub mod action;
54pub mod catalog;
55pub mod cluster;
56pub mod common;
57pub mod compute;
58pub mod provenance;
59pub mod runtime;
60pub mod source;
61pub mod trigger;