layer0/
lib.rs

1//! # layer0 — Protocol traits for composable agentic AI systems
2//!
3//! This crate defines the four protocol boundaries and two cross-cutting
4//! interfaces that compose to form any agentic AI system.
5//!
6//! ## The Protocols
7//!
8//! | Protocol | Trait | What it does |
9//! |----------|-------|-------------|
10//! | ① Operator | [`Operator`] | What one operator does per cycle |
11//! | ② Orchestration | [`Orchestrator`] | How operators compose + durability |
12//! | ③ State | [`StateStore`] | How data persists across turns |
13//! | ④ Environment | [`Environment`] | Isolation, credentials, resources |
14//!
15//! ## The Interfaces
16//!
17//! | Interface | Types | What it does |
18//! |-----------|-------|-------------|
19//! | ⑤ Middleware | [`DispatchMiddleware`], [`StoreMiddleware`], [`ExecMiddleware`] | Interception + policy |
20//! | ⑥ Lifecycle | [`BudgetEvent`], [`CompactionEvent`] | Cross-layer coordination |
21//!
22//! ## Design Principle
23//!
24//! Every protocol trait is operation-defined, not mechanism-defined.
25//! [`Operator::execute`] means "cause this agent to process one cycle" —
26//! not "make an API call" or "run a subprocess." This is what makes
27//! implementations swappable: a Temporal workflow, a function call,
28//! and a future system that doesn't exist yet all implement the same trait.
29//!
30//! ## Companion Documents
31//!
32//! - See `ARCHITECTURE.md` for design rationale
33//!
34//! ## Dependency Notes
35//!
36//! This crate depends on `serde_json::Value` for extension data fields
37//! (metadata, tool inputs, custom payloads). This is an intentional choice:
38//! JSON is the universal interchange format for agentic systems, and
39//! `serde_json::Value` is the de facto standard in the Rust ecosystem.
40//! The alternative (generic `T: Serialize`) would complicate trait object
41//! safety without practical benefit.
42//!
43//! ## Future: Native Async Traits
44//!
45//! Protocol traits currently use `async-trait` (heap-allocated futures).
46//! When Rust stabilizes `async fn in dyn Trait` with `Send` bounds,
47//! these traits will migrate to native async. This will be a breaking
48//! change in a minor version bump before v1.0.
49
50#![deny(missing_docs)]
51
52pub mod content;
53pub mod context;
54pub mod duration;
55pub mod effect;
56pub mod environment;
57pub mod error;
58pub mod id;
59pub mod lifecycle;
60pub mod middleware;
61pub mod operator;
62pub mod orchestrator;
63pub mod secret;
64pub mod state;
65
66#[cfg(feature = "test-utils")]
67pub mod test_utils;
68
69// Re-exports for convenience
70pub use content::{Content, ContentBlock};
71pub use context::{
72    Context, ContextError, ContextMessage, ContextSnapshot, ContextWatcher, Message, MessageMeta,
73    OperatorContext, Position, Role, WatcherVerdict,
74};
75pub use duration::DurationMs;
76pub use effect::{Effect, Scope, SignalPayload};
77pub use environment::{Environment, EnvironmentSpec};
78pub use error::{EnvError, OperatorError, OrchError, StateError};
79pub use id::{OperatorId, ScopeId, SessionId, WorkflowId};
80pub use lifecycle::{BudgetEvent, CompactionEvent, CompactionPolicy};
81pub use middleware::{
82    DispatchMiddleware, DispatchNext, DispatchStack, ExecMiddleware, ExecNext, ExecStack,
83    StoreMiddleware, StoreReadNext, StoreStack, StoreWriteNext,
84};
85pub use operator::{
86    ExitReason, Operator, OperatorConfig, OperatorInput, OperatorMetadata, OperatorOutput,
87    SubDispatchRecord, ToolMetadata,
88};
89pub use orchestrator::{Orchestrator, QueryPayload};
90pub use secret::{SecretAccessEvent, SecretAccessOutcome, SecretSource};
91pub use state::{
92    ContentKind, Lifetime, MemoryLink, MemoryTier, SearchOptions, SearchResult, StateReader,
93    StateStore, StoreOptions,
94};
layer0/lib.rs

layer0/
lib.rs
