pub struct StateSpec { /* private fields */ }Expand description
The graph’s state schema: channel name → Reducer.
The spec serves two roles:
- Merge semantics: at each super-step barrier, node updates are
merged into the shared state via the channel’s reducer
(
StateSpec::apply_super_step). - Write validation (
LastValuerule): within one super-step, a single-write channel may receive at most one write across all nodes that ran in parallel. A second write yieldsRustyError::InvalidUpdate, mirroring LangGraph’sInvalidUpdateError: Can receive only one value per step.
Writes to channels not declared in the spec are also rejected with
RustyError::InvalidUpdate; the spec is the complete schema.
Implementations§
Source§impl StateSpec
impl StateSpec
Sourcepub fn channel(self, name: impl Into<String>, reducer: Reducer) -> Self
pub fn channel(self, name: impl Into<String>, reducer: Reducer) -> Self
Builder-style: declare a channel with the given reducer.
Sourcepub fn add_channel(
&mut self,
name: impl Into<String>,
reducer: Reducer,
) -> &mut Self
pub fn add_channel( &mut self, name: impl Into<String>, reducer: Reducer, ) -> &mut Self
Mutable variant of StateSpec::channel.
Sourcepub fn reducer_for(&self, channel: &str) -> Reducer
pub fn reducer_for(&self, channel: &str) -> Reducer
The reducer for a channel, defaulting to Reducer::Overwrite
(LastValue semantics) for undeclared channels.
The default is a convenience for contexts where the channel is known
to be declared. When the channel may be undeclared, use
StateSpec::try_reducer_for and handle None — silently treating
an undeclared channel as Overwrite is almost never the intent.
StateSpec::apply_super_step always validates channels first, so
the default is unreachable on that path.
Sourcepub fn try_reducer_for(&self, channel: &str) -> Option<Reducer>
pub fn try_reducer_for(&self, channel: &str) -> Option<Reducer>
The reducer for a channel, or None if the channel is not declared.
Sourcepub fn channel_names(&self) -> impl Iterator<Item = &str>
pub fn channel_names(&self) -> impl Iterator<Item = &str>
All declared channel names.
Sourcepub fn has_channel(&self, channel: &str) -> bool
pub fn has_channel(&self, channel: &str) -> bool
true if the channel is declared in this spec.
Sourcepub fn apply_super_step<I, S>(&self, state: &mut State, writes: I) -> Result<()>
pub fn apply_super_step<I, S>(&self, state: &mut State, writes: I) -> Result<()>
Validate and merge all writes of one super-step into state.
writes is the collection of (node_name, updates) pairs produced by
the nodes that ran in this super-step. Each entry is one node’s
partial update map (channel -> value), as carried by
crate::node::NodeOutput::updates.
Semantics, in order:
- Every written channel must be declared in this spec
(
RustyError::InvalidUpdateotherwise). - A channel whose reducer does not allow multiple writes
(i.e.
Reducer::Overwrite) may appear in at most one node’s updates per super-step; a second write isRustyError::InvalidUpdate. - For
Reducer::AppendandReducer::AddMessageschannels, the current state value (if present) must be an array; a non-array current value indicates a type bug in the graph spec and is rejected withRustyError::InvalidUpdaterather than silently discarded. - Surviving writes are merged via the channel reducer in deterministic order: sorted by node name. The executor collects writes from concurrently completing tasks, so callers cannot rely on input order; canonicalizing here keeps fan-in results (and checkpoints derived from them) stable run-to-run.
Validation completes before any mutation: on error the state is left entirely unmodified and the caller (executor) should abort the super-step — LangGraph treats a super-step as transactional.