aura_composition/lib.rs
1//! # Aura Composition - Layer 3: Implementation (Handler Composition)
2//!
3//! **Purpose**: Assemble individual handlers into cohesive effect systems.
4//!
5//! This crate provides effect handler composition, registry, and builder infrastructure
6//! for assembling stateless handlers from the effects crate into runnable effect systems.
7//!
8//! # Architecture Constraints
9//!
10//! **Layer 3 depends only on aura-core and the effects implementations** (foundation + implementation).
11//! - MUST handle composition of effect handlers (not implementation)
12//! - MUST provide registry and builder patterns for handler assembly
13//! - MUST manage effect system lifecycle (initialization, shutdown)
14//! - MUST NOT implement effect handlers (that's the effects crate)
15//! - MUST NOT do multi-party coordination (that's aura-protocol)
16//! - MUST NOT depend on domain crates or higher layers
17//!
18//! # Key Components
19//!
20//! - EffectRegistry: Type-indexed storage of handler instances
21//! - EffectSystemBuilder: Builder pattern for composing handlers
22//! - EffectContainer: Runtime container managing handler lifecycle
23//! - Handler lifecycle management (start/stop/configure)
24//!
25//! # What Belongs Here
26//!
27//! Handler composition and assembly infrastructure:
28//! - Effect registry and lookup by type
29//! - Builder patterns for effect system construction
30//! - Handler composition utilities
31//! - Lifecycle management (initialization, shutdown)
32//!
33//! # What Does NOT Belong Here
34//!
35//! - Individual handler implementations (that's the effects crate)
36//! - Multi-party protocol logic (that's aura-protocol)
37//! - Runtime-specific concerns like signal handling (that's aura-agent)
38//! - Application lifecycle management (that's aura-agent)
39//!
40//! # Usage Pattern
41//!
42//! Feature crates compose handlers without pulling in full runtime infrastructure:
43//!
44//! ```rust,ignore
45//! use aura_composition::{EffectSystemBuilder};
46//! use aura_effects::RealCryptoHandler;
47//!
48//! let effects = EffectSystemBuilder::new()
49//! .with_handler(Arc::new(RealCryptoHandler::new()))
50//! .build()
51//! .await?;
52//! ```
53
54#![allow(missing_docs)]
55
56pub mod adapters;
57pub mod composite;
58pub mod registry;
59pub mod view_delta;
60
61// Re-export core types for convenience
62pub use registry::{
63 EffectCapability, EffectRegistry, Handler, HandlerContext, HandlerError, RegisterAllOptions,
64 RegistrableHandler, RegistryCapabilities, RegistryError,
65};
66
67pub use composite::{
68 CompositeError, CompositeHandler, CompositeHandlerAdapter, CompositeHandlerBuilder,
69};
70
71pub use adapters::{
72 ConsoleHandlerAdapter, CryptoHandlerAdapter, LoggingSystemHandlerAdapter, RandomHandlerAdapter,
73 StorageHandlerAdapter, TimeHandlerAdapter, TraceHandlerAdapter, TransportHandlerAdapter,
74};
75
76pub use view_delta::{
77 compact_deltas, downcast_delta, downcast_delta_owned, ComposableDelta, IntoViewDelta,
78 ViewDelta, ViewDeltaReducer, ViewDeltaRegistry,
79};