gemini_adk_rs/
primitives.rs

1//! # The L1 contract — the conversation runtime
2//!
3//! This module is the *engineered surface* of the runtime layer: the closed
4//! set of primitives L1 exposes upward, curated and named. L0 moves frames;
5//! this layer gives those frames meaning — and enforces it.
6//!
7//! **L1 promises:** a concurrent session runtime over the L0 stream — typed
8//! shared [`State`], tool dispatch, governed flows with load-time compilation
9//! and a self-explaining monitor, out-of-band extraction that fills the state
10//! guards read, phases and watchers, transcripts, persistence, and a
11//! [`LiveHandle`] that can always answer *why* (`explain`, truth traces)
12//! and steer *now* (`update_step_posture`).
13//!
14//! **L1 never:** opens its own idea of a socket beyond L0's transport,
15//! renders application prose, or hides an enforcement decision — every denial
16//! carries its reason, every stuck guard can print its atoms.
17//!
18//! The primitives, by concern:
19//!
20//! | Concern | Primitives |
21//! |---|---|
22//! | Shared truth | [`State`], [`StateKey`], [`PrefixedState`] |
23//! | Capability | [`ToolFunction`], [`SimpleTool`], [`TypedTool`], [`ToolDispatcher`] |
24//! | Governance | [`Flow`], [`Step`], [`Guard`], [`Pred`], [`Constraint`], [`CompiledFlow`], [`FlowMonitor`], [`Enforcement`], [`Marking`], [`Verdict`] |
25//! | Explanation | [`FlowExplanation`], [`GuardTrace`], [`Violation`] |
26//! | Understanding | [`TurnExtractor`], [`LlmExtractor`], [`FieldPromotion`], [`ExtractionTrigger`] |
27//! | Steering | [`Phase`], [`PhaseMachine`], [`Transition`], [`InstructionModifier`], [`Watcher`] |
28//! | The session | [`LiveSessionBuilder`], [`LiveHandle`], [`LiveEvent`], [`EventCallbacks`], [`TranscriptBuffer`] |
29//! | Memory of it | [`SessionPersistence`], [`SessionSnapshot`], [`FsPersistence`], [`MemoryPersistence`] |
30//! | Models | [`BaseLlm`], [`LlmRequest`], [`LlmResponse`] |
31
32pub use crate::state::{PrefixedState, State, StateKey};
33
34pub use crate::tool::{SimpleTool, ToolDispatcher, ToolFunction, TypedTool};
35
36pub use crate::flow::{
37    CompiledFlow, Constraint, Enforcement, Flow, FlowExplanation, FlowMonitor, Guard, GuardTrace,
38    Marking, Pred, Step, Verdict, Violation,
39};
40
41pub use crate::live::extractor::{ExtractionTrigger, FieldPromotion, LlmExtractor, TurnExtractor};
42
43pub use crate::live::builder::LiveSessionBuilder;
44pub use crate::live::callbacks::EventCallbacks;
45pub use crate::live::events::LiveEvent;
46pub use crate::live::handle::LiveHandle;
47pub use crate::live::phase::{InstructionModifier, Phase, PhaseMachine, Transition};
48pub use crate::live::transcript::TranscriptBuffer;
49pub use crate::live::watcher::Watcher;
50
51pub use crate::live::persistence::{
52    FsPersistence, MemoryPersistence, SessionPersistence, SessionSnapshot,
53};
54
55pub use crate::llm::{BaseLlm, LlmRequest, LlmResponse};
56
57#[cfg(test)]
58mod contract {
59    //! The drift guard: every primitive the module docs name must exist and
60    //! be reachable from this path.
61    #[test]
62    fn every_named_primitive_is_reachable() {
63        use super::*;
64        fn is_type<T: ?Sized>() {}
65        is_type::<State>();
66        is_type::<StateKey<u32>>();
67        is_type::<PrefixedState>();
68        is_type::<dyn ToolFunction>();
69        is_type::<SimpleTool>();
70        #[derive(serde::Deserialize, schemars::JsonSchema)]
71        struct Args {}
72        is_type::<TypedTool<Args>>();
73        is_type::<ToolDispatcher>();
74        is_type::<Flow>();
75        is_type::<Step>();
76        is_type::<Guard>();
77        is_type::<Pred>();
78        is_type::<Constraint>();
79        is_type::<CompiledFlow>();
80        is_type::<FlowMonitor>();
81        is_type::<Enforcement>();
82        is_type::<Marking>();
83        is_type::<Verdict>();
84        is_type::<FlowExplanation>();
85        is_type::<GuardTrace>();
86        is_type::<Violation>();
87        is_type::<dyn TurnExtractor>();
88        is_type::<LlmExtractor>();
89        is_type::<FieldPromotion>();
90        is_type::<ExtractionTrigger>();
91        is_type::<Phase>();
92        is_type::<PhaseMachine>();
93        is_type::<Transition>();
94        is_type::<InstructionModifier>();
95        is_type::<Watcher>();
96        is_type::<LiveSessionBuilder>();
97        is_type::<LiveHandle>();
98        is_type::<LiveEvent>();
99        is_type::<EventCallbacks>();
100        is_type::<TranscriptBuffer>();
101        is_type::<dyn SessionPersistence>();
102        is_type::<SessionSnapshot>();
103        is_type::<FsPersistence>();
104        is_type::<MemoryPersistence>();
105        is_type::<dyn BaseLlm>();
106        is_type::<LlmRequest>();
107        is_type::<LlmResponse>();
108    }
109}
gemini_adk_rs/primitives.rs

gemini_adk_rs/
primitives.rs
