rusty_agent_runtime/state.rs
1//! Shared state, channels, and reducers.
2//!
3//! In Rusty Core (as in LangGraph) **every state key is a channel** and the
4//! channel's [`Reducer`] defines how node updates merge into the shared
5//! state. Nodes never call each other; they publish partial updates to
6//! channels, and the engine applies the per-channel reducer at the super-step
7//! barrier.
8//!
9//! Channel semantics modeled here:
10//!
11//! | Reducer | LangGraph analog | Multi-write per super-step? |
12//! |----------------|-----------------------------|-----------------------------|
13//! | [`Reducer::Overwrite`] | `LastValue` | **No** — second write is [`RustyError::InvalidUpdate`] |
14//! | [`Reducer::Append`] | `BinaryOperatorAggregate` (list concat) | Yes |
15//! | [`Reducer::DeepMerge`] | custom merge reducer | Yes |
16//! | [`Reducer::AddMessages`]| `add_messages` | Yes (ID-aware upsert + append) |
17//!
18//! [`StateSpec`] is the graph's state schema: channel name → reducer. It also
19//! performs super-step write validation in [`StateSpec::apply_super_step`].
20
21use std::collections::{BTreeMap, HashMap};
22use std::sync::Arc;
23
24use serde::ser::SerializeMap;
25use serde::{Deserialize, Deserializer, Serialize, Serializer};
26use serde_json::{Map, Value};
27
28use crate::error::{Result, RustyError};
29
30/// The channel map's concrete type. `BTreeMap`, not `serde_json::Map`:
31/// serde_json's `Map` is only fully implemented for `Map<String, Value>`,
32/// and without the `preserve_order` feature it is B-tree-backed — sorted
33/// iteration order identical to this one's, which is what keeps the custom
34/// serde impls below byte-identical to the pre-W4 transparent-Map shape.
35type ChannelMap = BTreeMap<String, Arc<Value>>;
36
37/// The shared graph state: channel name → value, with copy-on-write sharing
38/// at channel granularity (R0.7 wave 4).
39///
40/// This is the "untyped typed-dict" of the engine: nodes read the full state
41/// snapshot and return partial updates keyed by channel name. Type safety for
42/// concrete applications is layered on top via serde (de)serialization of
43/// individual channel values.
44///
45/// # Copy-on-write representation
46///
47/// Every channel value sits behind an [`Arc`], and the channel map itself
48/// behind another. Cloning a `State` — the executor's per-super-step
49/// snapshot, each node's private copy, the checkpoint's copy — is two
50/// refcount bumps, O(1) in the state's size, where it used to be a deep
51/// clone of every channel. A write (a reducer merge at the barrier, an
52/// engine [`State::insert`]) touches only what it must: the map is cloned
53/// shallowly when shared (one refcount bump per channel), and a channel's
54/// value is cloned only when some other `State` still shares it —
55/// `Arc::make_mut` semantics per channel. Unchanged channels stay shared
56/// between the pre- and post-step states and every node's snapshot, which is
57/// also what delta checkpoints diff against (see
58/// [`crate::checkpoint::encode_delta`]): sharing and deltas are the same
59/// structural observation.
60///
61/// The public contract is unchanged and pinned: [`State::get`] still returns
62/// `Option<&Value>`, serde still sees the same JSON object (the custom
63/// impls below serialize exactly like the previous transparent `Map`, so
64/// checkpoints, the wire, the SDKs, and golden files stay byte-identical),
65/// and reducer semantics are untouched. What changed is representation only.
66#[derive(Debug, Clone, Default, PartialEq)]
67pub struct State {
68 inner: Arc<ChannelMap>,
69}
70
71/// Serializes exactly like the `Map<String, Value>` this type used to wrap
72/// transparently: a JSON object of channel name → value. Byte-identity with
73/// the pre-W4 wire shape is the contract — checkpoints, goldens, and SDK
74/// payloads must not drift because the interior changed.
75impl Serialize for State {
76 fn serialize<S: Serializer>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error> {
77 let mut map = serializer.serialize_map(Some(self.inner.len()))?;
78 for (channel, value) in self.inner.iter() {
79 map.serialize_entry(channel, value.as_ref())?;
80 }
81 map.end()
82 }
83}
84
85/// Parses any JSON object, as the previous transparent `Map` did.
86impl<'de> Deserialize<'de> for State {
87 fn deserialize<D: Deserializer<'de>>(deserializer: D) -> std::result::Result<Self, D::Error> {
88 Ok(Self::from_map(Map::<String, Value>::deserialize(
89 deserializer,
90 )?))
91 }
92}
93
94impl State {
95 /// An empty state.
96 pub fn new() -> Self {
97 Self::default()
98 }
99
100 /// Wrap an existing JSON object.
101 pub fn from_map(inner: Map<String, Value>) -> Self {
102 Self {
103 inner: Arc::new(inner.into_iter().map(|(k, v)| (k, Arc::new(v))).collect()),
104 }
105 }
106
107 /// Build a state from any serializable value that is a JSON object.
108 pub fn from_value(value: Value) -> Result<Self> {
109 match value {
110 Value::Object(inner) => Ok(Self::from_map(inner)),
111 // Report only the type: the value itself may be a multi-MB blob.
112 other => Err(RustyError::InvalidUpdate(format!(
113 "state must be a JSON object, got {}",
114 json_type_name(&other)
115 ))),
116 }
117 }
118
119 /// Serialize the whole state back into a [`Value::Object`].
120 pub fn to_value(&self) -> Value {
121 Value::Object(
122 self.inner
123 .iter()
124 .map(|(k, v)| (k.clone(), v.as_ref().clone()))
125 .collect(),
126 )
127 }
128
129 /// Consume the state, returning the underlying map. Channel values that
130 /// no other state shares are unwrapped without copying; shared ones are
131 /// cloned (copy-on-write).
132 pub fn into_map(self) -> Map<String, Value> {
133 match Arc::try_unwrap(self.inner) {
134 Ok(map) => map
135 .into_iter()
136 .map(|(k, v)| (k, Arc::unwrap_or_clone(v)))
137 .collect(),
138 Err(shared) => shared
139 .iter()
140 .map(|(k, v)| (k.clone(), v.as_ref().clone()))
141 .collect(),
142 }
143 }
144
145 /// Iterate over `(channel, value)` pairs.
146 pub fn iter(&self) -> impl Iterator<Item = (&str, &Value)> {
147 self.inner.iter().map(|(k, v)| (k.as_str(), v.as_ref()))
148 }
149
150 /// Get a channel's current value.
151 pub fn get(&self, channel: &str) -> Option<&Value> {
152 self.inner.get(channel).map(Arc::as_ref)
153 }
154
155 /// `true` if the channel exists in the state (regardless of value).
156 pub fn contains(&self, channel: &str) -> bool {
157 self.inner.contains_key(channel)
158 }
159
160 /// Directly set a channel's value, bypassing reducer semantics.
161 ///
162 /// Intended for engine internals (initial state seeding, checkpoint
163 /// restore). Nodes should always go through reducers.
164 pub fn insert(&mut self, channel: impl Into<String>, value: Value) {
165 self.insert_shared(channel, Arc::new(value));
166 }
167
168 /// Deserialize a channel into a concrete type.
169 pub fn get_as<T: serde::de::DeserializeOwned>(&self, channel: &str) -> Result<Option<T>> {
170 match self.get(channel) {
171 None => Ok(None),
172 // `&Value` implements `Deserializer`; no need to clone first.
173 Some(v) => Ok(Some(T::deserialize(v)?)),
174 }
175 }
176
177 /// Number of channels currently present.
178 pub fn len(&self) -> usize {
179 self.inner.len()
180 }
181
182 /// `true` if no channels are present.
183 pub fn is_empty(&self) -> bool {
184 self.inner.is_empty()
185 }
186
187 /// A shared handle to one channel's value. Test-only: production code
188 /// reaches channels through `get` / `shared_channels`; the copy-on-write
189 /// tests use this to assert pointer-level sharing.
190 #[cfg(test)]
191 pub(crate) fn shared_channel(&self, channel: &str) -> Option<Arc<Value>> {
192 self.inner.get(channel).cloned()
193 }
194
195 /// All channels as shared values.
196 pub(crate) fn shared_channels(&self) -> impl Iterator<Item = (&str, &Arc<Value>)> {
197 self.inner.iter().map(|(k, v)| (k.as_str(), v))
198 }
199
200 /// Insert a channel value that is already shared, preserving sharing.
201 /// Clones the channel map shallowly when other states share it.
202 pub(crate) fn insert_shared(&mut self, channel: impl Into<String>, value: Arc<Value>) {
203 Arc::make_mut(&mut self.inner).insert(channel.into(), value);
204 }
205
206 /// Build a state from shared channel values (delta encoding/decoding in
207 /// `checkpoint.rs`), preserving sharing with the states they came from.
208 pub(crate) fn from_shared_channels<I, S>(channels: I) -> Self
209 where
210 I: IntoIterator<Item = (S, Arc<Value>)>,
211 S: Into<String>,
212 {
213 Self {
214 inner: Arc::new(channels.into_iter().map(|(k, v)| (k.into(), v)).collect()),
215 }
216 }
217
218 /// The channels whose values differ from `base`'s, as shared values —
219 /// the channel-level delta a W4 delta checkpoint persists. Pointer
220 /// equality short-circuits: a channel still shared with the base is
221 /// unchanged without a value walk. Value equality still dedupes channels
222 /// that were rebuilt with identical content (e.g. after a deserialize),
223 /// so equal bytes are never written twice.
224 pub(crate) fn channels_changed_since(&self, base: &State) -> Vec<(String, Arc<Value>)> {
225 self.shared_channels()
226 .filter(|(channel, value)| match base.inner.get(*channel) {
227 Some(base_value) if Arc::ptr_eq(value, base_value) => false,
228 Some(base_value) => value.as_ref() != base_value.as_ref(),
229 None => true,
230 })
231 .map(|(channel, value)| (channel.to_owned(), value.clone()))
232 .collect()
233 }
234}
235
236impl From<Map<String, Value>> for State {
237 fn from(inner: Map<String, Value>) -> Self {
238 Self::from_map(inner)
239 }
240}
241
242/// Per-channel merge semantics.
243///
244/// A reducer is conceptually a binary function
245/// `reduce(current: Option<&Value>, update: Value) -> Value`, mirroring
246/// LangGraph's `Annotated[T, reducer]` channel annotations.
247#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
248pub enum Reducer {
249 /// `LastValue` semantics: the update replaces the current value.
250 ///
251 /// **At most one write per super-step** — a second write to the same
252 /// channel within one super-step fails with
253 /// [`RustyError::InvalidUpdate`]. This is the default for any
254 /// channel and the classic production failure mode in parallel graphs;
255 /// if you need fan-in, use [`Reducer::Append`], [`Reducer::DeepMerge`],
256 /// or [`Reducer::AddMessages`].
257 #[default]
258 Overwrite,
259
260 /// List-concat semantics: the current value is treated as an array
261 /// (a missing current value starts as `[]`). If the update is an
262 /// array it is extended onto the current array; otherwise the update is
263 /// pushed as a single element.
264 ///
265 /// A **non-array current value** is rejected by
266 /// [`StateSpec::apply_super_step`] with [`RustyError::InvalidUpdate`];
267 /// only direct calls to [`Reducer::apply`] coerce it to `[]`.
268 Append,
269
270 /// Recursive object merge: two JSON objects are merged key-by-key
271 /// (nested objects merge recursively); any non-object pair resolves to
272 /// the update value. A missing current value resolves to the update.
273 DeepMerge,
274
275 /// LangGraph `add_messages` semantics over a message array.
276 ///
277 /// The current value is treated as an array of message objects. The
278 /// update may be a single message object or an array of messages. Each
279 /// incoming message is **upserted**: if it has an `"id"` field equal to
280 /// an existing message's `"id"`, the existing message is replaced in
281 /// place; otherwise the message is appended. Messages whose `"id"` is
282 /// present but not a string are treated as id-less (always appended).
283 ///
284 /// Like [`Reducer::Append`], a non-array current value is rejected by
285 /// [`StateSpec::apply_super_step`].
286 AddMessages,
287}
288
289impl Reducer {
290 /// Whether this channel accepts multiple writes within one super-step.
291 ///
292 /// Only `LastValue`-style channels ([`Reducer::Overwrite`]) are
293 /// single-write; aggregating reducers exist precisely to support
294 /// parallel fan-in.
295 pub fn allows_multiple_writes(self) -> bool {
296 !matches!(self, Reducer::Overwrite)
297 }
298
299 /// Apply one update to a channel's current value.
300 ///
301 /// `current` is `None` when the channel has never been written.
302 ///
303 /// For [`Reducer::Append`] and [`Reducer::AddMessages`], a non-array
304 /// `current` is treated as `[]` (the update starts a fresh array).
305 /// [`StateSpec::apply_super_step`] rejects that case with
306 /// [`RustyError::InvalidUpdate`] before reducers run; the coercion
307 /// here exists only for direct callers of this method.
308 pub fn apply(&self, current: Option<&Value>, update: Value) -> Value {
309 match self {
310 Reducer::Overwrite => update,
311 Reducer::Append => match current {
312 Some(Value::Array(existing)) => {
313 let mut out = existing.clone();
314 append_in_place(&mut out, update);
315 Value::Array(out)
316 }
317 _ => match update {
318 Value::Array(items) => Value::Array(items),
319 single => Value::Array(vec![single]),
320 },
321 },
322 Reducer::DeepMerge => match current {
323 Some(cur) => deep_merge(cur, &update),
324 None => update,
325 },
326 Reducer::AddMessages => add_messages(current, update),
327 }
328 }
329
330 /// The copy-on-write twin of [`Reducer::apply`]: identical semantics,
331 /// but operating on the channel's shared value so uniquely owned values
332 /// mutate in place.
333 ///
334 /// When no snapshot, checkpoint, or sibling state shares the current
335 /// value, an aggregating reducer (Append / DeepMerge / AddMessages)
336 /// merges into it directly — an Append push onto a uniquely owned array
337 /// is amortized O(1) instead of the O(N) clone [`Reducer::apply`] always
338 /// pays. When the value is shared, only this channel is cloned: the
339 /// merge never pays for channels it did not write, which is the whole
340 /// point of the W4 representation. The result is wrapped in a fresh
341 /// [`Arc`] only when a new value was produced; an in-place merge returns
342 /// the same allocation it was given.
343 pub(crate) fn apply_shared(&self, current: Option<Arc<Value>>, update: Value) -> Arc<Value> {
344 match self {
345 Reducer::Overwrite => Arc::new(update),
346 Reducer::Append => match current {
347 Some(mut shared) if shared.is_array() => match Arc::get_mut(&mut shared) {
348 Some(Value::Array(existing)) => {
349 append_in_place(existing, update);
350 shared
351 }
352 // Shared with a live snapshot or checkpoint: copy this
353 // channel only, then merge into the copy.
354 _ => {
355 let Value::Array(existing) = shared.as_ref() else {
356 unreachable!("guarded by is_array above")
357 };
358 let mut out = existing.clone();
359 append_in_place(&mut out, update);
360 Arc::new(Value::Array(out))
361 }
362 },
363 // Missing or non-array current (the latter is rejected by
364 // `apply_super_step` validation; direct callers get the same
365 // coercion `apply` documents): the update starts a fresh array.
366 _ => Arc::new(match update {
367 Value::Array(items) => Value::Array(items),
368 single => Value::Array(vec![single]),
369 }),
370 },
371 Reducer::DeepMerge => match current {
372 Some(mut shared) => match Arc::get_mut(&mut shared) {
373 Some(current) => {
374 deep_merge_in_place(current, &update);
375 shared
376 }
377 None => Arc::new(deep_merge(shared.as_ref(), &update)),
378 },
379 None => Arc::new(update),
380 },
381 Reducer::AddMessages => match current {
382 Some(mut shared) if shared.is_array() => match Arc::get_mut(&mut shared) {
383 Some(Value::Array(messages)) => {
384 upsert_messages_in_place(messages, update);
385 shared
386 }
387 _ => {
388 let Value::Array(existing) = shared.as_ref() else {
389 unreachable!("guarded by is_array above")
390 };
391 let mut messages = existing.clone();
392 upsert_messages_in_place(&mut messages, update);
393 Arc::new(Value::Array(messages))
394 }
395 },
396 _ => Arc::new(add_messages(None, update)),
397 },
398 }
399 }
400}
401
402impl std::fmt::Display for Reducer {
403 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
404 let name = match self {
405 Reducer::Overwrite => "overwrite",
406 Reducer::Append => "append",
407 Reducer::DeepMerge => "deep_merge",
408 Reducer::AddMessages => "add_messages",
409 };
410 f.write_str(name)
411 }
412}
413
414/// Short type name for error messages (avoids embedding the value itself).
415fn json_type_name(v: &Value) -> &'static str {
416 match v {
417 Value::Null => "null",
418 Value::Bool(_) => "bool",
419 Value::Number(_) => "number",
420 Value::String(_) => "string",
421 Value::Array(_) => "array",
422 Value::Object(_) => "object",
423 }
424}
425
426/// Recursive JSON object merge. Non-object pairs resolve to `b`.
427fn deep_merge(a: &Value, b: &Value) -> Value {
428 let mut merged = a.clone();
429 deep_merge_in_place(&mut merged, b);
430 merged
431}
432
433/// The in-place core of [`deep_merge`]: merge `b` into `a` without cloning
434/// `a` first. Shared by the copy-on-write merge path, which calls this
435/// directly when the channel value is uniquely owned.
436fn deep_merge_in_place(a: &mut Value, b: &Value) {
437 match (&mut *a, b) {
438 (Value::Object(x), Value::Object(y)) => {
439 for (k, v) in y {
440 match x.get_mut(k) {
441 Some(cur) => deep_merge_in_place(cur, v),
442 None => {
443 x.insert(k.clone(), v.clone());
444 }
445 }
446 }
447 }
448 _ => *a = b.clone(),
449 }
450}
451
452/// The in-place core of [`Reducer::Append`]'s merge: extend an existing
453/// array with the update (array updates concatenate; anything else pushes
454/// as a single element).
455fn append_in_place(existing: &mut Vec<Value>, update: Value) {
456 match update {
457 Value::Array(items) => existing.extend(items),
458 single => existing.push(single),
459 }
460}
461
462/// `add_messages` semantics: ID-aware upsert + append over a message array.
463///
464/// A message whose `"id"` is not a string (e.g. `{"id": 123}`) is treated as
465/// id-less and always appended — it can never match an existing message.
466fn add_messages(current: Option<&Value>, update: Value) -> Value {
467 let mut messages: Vec<Value> = match current {
468 Some(Value::Array(existing)) => existing.clone(),
469 _ => Vec::new(),
470 };
471 upsert_messages_in_place(&mut messages, update);
472 Value::Array(messages)
473}
474
475/// The in-place core of [`add_messages`]: upsert the update's messages into
476/// an existing array by `"id"`, appending id-less and unknown-id messages.
477fn upsert_messages_in_place(messages: &mut Vec<Value>, update: Value) {
478 let incoming: Vec<Value> = match update {
479 Value::Array(items) => items,
480 single => vec![single],
481 };
482 // One pass to index existing ids; the upsert loop then runs O(1) per
483 // incoming message instead of scanning the whole array each time.
484 let mut index_of: HashMap<String, usize> = HashMap::with_capacity(messages.len());
485 for (i, m) in messages.iter().enumerate() {
486 if let Some(id) = m.get("id").and_then(Value::as_str) {
487 index_of.entry(id.to_owned()).or_insert(i);
488 }
489 }
490 for msg in incoming {
491 let msg_id = msg.get("id").and_then(Value::as_str).map(str::to_owned);
492 match msg_id.as_deref().and_then(|id| index_of.get(id).copied()) {
493 Some(i) => messages[i] = msg,
494 None => {
495 if let Some(id) = msg_id {
496 index_of.insert(id, messages.len());
497 }
498 messages.push(msg);
499 }
500 }
501 }
502}
503
504/// The graph's state schema: channel name → [`Reducer`].
505///
506/// The spec serves two roles:
507///
508/// 1. **Merge semantics**: at each super-step barrier, node updates are
509/// merged into the shared state via the channel's reducer
510/// ([`StateSpec::apply_super_step`]).
511/// 2. **Write validation** (`LastValue` rule): within one super-step, a
512/// single-write channel may receive at most one write across *all*
513/// nodes that ran in parallel. A second write yields
514/// [`RustyError::InvalidUpdate`], mirroring LangGraph's
515/// `InvalidUpdateError: Can receive only one value per step`.
516///
517/// Writes to channels **not declared** in the spec are also rejected with
518/// [`RustyError::InvalidUpdate`]; the spec is the complete schema.
519#[derive(Debug, Clone, Default)]
520pub struct StateSpec {
521 channels: HashMap<String, Reducer>,
522}
523
524impl StateSpec {
525 /// An empty spec (no channels declared).
526 pub fn new() -> Self {
527 Self::default()
528 }
529
530 /// Builder-style: declare a channel with the given reducer.
531 pub fn channel(mut self, name: impl Into<String>, reducer: Reducer) -> Self {
532 self.channels.insert(name.into(), reducer);
533 self
534 }
535
536 /// Mutable variant of [`StateSpec::channel`].
537 pub fn add_channel(&mut self, name: impl Into<String>, reducer: Reducer) -> &mut Self {
538 self.channels.insert(name.into(), reducer);
539 self
540 }
541
542 /// The reducer for a channel, defaulting to [`Reducer::Overwrite`]
543 /// (`LastValue` semantics) for undeclared channels.
544 ///
545 /// The default is a convenience for contexts where the channel is known
546 /// to be declared. When the channel may be undeclared, use
547 /// [`StateSpec::try_reducer_for`] and handle `None` — silently treating
548 /// an undeclared channel as `Overwrite` is almost never the intent.
549 /// [`StateSpec::apply_super_step`] always validates channels first, so
550 /// the default is unreachable on that path.
551 pub fn reducer_for(&self, channel: &str) -> Reducer {
552 self.channels.get(channel).copied().unwrap_or_default()
553 }
554
555 /// The reducer for a channel, or `None` if the channel is not declared.
556 pub fn try_reducer_for(&self, channel: &str) -> Option<Reducer> {
557 self.channels.get(channel).copied()
558 }
559
560 /// All declared channel names.
561 pub fn channel_names(&self) -> impl Iterator<Item = &str> {
562 self.channels.keys().map(String::as_str)
563 }
564
565 /// `true` if the channel is declared in this spec.
566 pub fn has_channel(&self, channel: &str) -> bool {
567 self.channels.contains_key(channel)
568 }
569
570 /// Validate and merge **all writes of one super-step** into `state`.
571 ///
572 /// `writes` is the collection of `(node_name, updates)` pairs produced by
573 /// the nodes that ran in this super-step. Each entry is one node's
574 /// partial update map (`channel -> value`), as carried by
575 /// [`crate::node::NodeOutput::updates`].
576 ///
577 /// Semantics, in order:
578 ///
579 /// 1. Every written channel must be declared in this spec
580 /// ([`RustyError::InvalidUpdate`] otherwise).
581 /// 2. A channel whose reducer does **not** allow multiple writes
582 /// (i.e. [`Reducer::Overwrite`]) may appear in at most one node's
583 /// updates per super-step; a second write is
584 /// [`RustyError::InvalidUpdate`].
585 /// 3. For [`Reducer::Append`] and [`Reducer::AddMessages`] channels, the
586 /// current state value (if present) must be an array; a non-array
587 /// current value indicates a type bug in the graph spec and is
588 /// rejected with [`RustyError::InvalidUpdate`] rather than
589 /// silently discarded.
590 /// 4. Surviving writes are merged via the channel reducer in
591 /// **deterministic order: sorted by node name**. The executor
592 /// collects writes from concurrently completing tasks, so callers
593 /// cannot rely on input order; canonicalizing here keeps fan-in
594 /// results (and checkpoints derived from them) stable run-to-run.
595 ///
596 /// Validation completes before any mutation: on error the state is left
597 /// entirely unmodified and the caller (executor) should abort the
598 /// super-step — LangGraph treats a super-step as transactional.
599 pub fn apply_super_step<I, S>(&self, state: &mut State, writes: I) -> Result<()>
600 where
601 I: IntoIterator<Item = (S, HashMap<String, Value>)>,
602 S: AsRef<str>,
603 {
604 // Collect up front so the whole super-step is validated before a
605 // single channel is touched — that is what makes failure
606 // all-or-nothing. Also canonicalize the merge order: executors feed
607 // writes in task-completion order, which is nondeterministic.
608 let mut collected: Vec<(String, HashMap<String, Value>)> = writes
609 .into_iter()
610 .map(|(node, updates)| (node.as_ref().to_owned(), updates))
611 .collect();
612 collected.sort_by(|a, b| a.0.cmp(&b.0));
613
614 let mut write_counts: HashMap<&str, usize> = HashMap::new();
615 let mut first_writer: HashMap<&str, &str> = HashMap::new();
616
617 for (node, updates) in &collected {
618 for channel in updates.keys() {
619 let Some(reducer) = self.try_reducer_for(channel) else {
620 return Err(RustyError::InvalidUpdate(format!(
621 "node `{node}` wrote to undeclared channel `{channel}`; \
622 declare it in the StateSpec"
623 )));
624 };
625 // Aggregating-over-array reducers must not silently discard
626 // a mistyped current value; that is a spec bug, not data.
627 if matches!(reducer, Reducer::Append | Reducer::AddMessages) {
628 if let Some(current) = state.get(channel) {
629 if !current.is_array() {
630 return Err(RustyError::InvalidUpdate(format!(
631 "node `{node}` wrote to channel `{channel}` (reducer: \
632 {reducer}), but the current value is a {}; the \
633 reducer requires an array",
634 json_type_name(current)
635 )));
636 }
637 }
638 }
639 let count = write_counts.entry(channel.as_str()).or_insert(0);
640 *count += 1;
641 first_writer
642 .entry(channel.as_str())
643 .or_insert(node.as_str());
644 if *count > 1 && !reducer.allows_multiple_writes() {
645 return Err(RustyError::InvalidUpdate(format!(
646 "channel `{channel}` can receive only one value per super-step \
647 (reducer: {reducer}); already written by node `{}`, second write from \
648 node `{node}`. Use a multi-write reducer (Append/DeepMerge/\
649 AddMessages) to handle concurrent writes.",
650 first_writer[channel.as_str()],
651 )));
652 }
653 }
654 }
655
656 for (_node, updates) in collected {
657 for (channel, update) in updates {
658 let reducer = self.reducer_for(&channel);
659 // Copy-on-write merge: the channel is taken OUT of the map
660 // first, so a value no snapshot or checkpoint shares has
661 // refcount 1 here and the reducer merges into it in place;
662 // a shared value is cloned by the reducer — that channel
663 // alone, never the whole state.
664 let current = Arc::make_mut(&mut state.inner).remove(&channel);
665 let merged = reducer.apply_shared(current, update);
666 state.insert_shared(channel, merged);
667 }
668 }
669 Ok(())
670 }
671
672 /// Convenience: merge a single node's updates (e.g. outside the parallel
673 /// super-step path). Single-write validation trivially passes since only
674 /// one writer is involved.
675 pub fn apply_single(
676 &self,
677 state: &mut State,
678 node: &str,
679 updates: HashMap<String, Value>,
680 ) -> Result<()> {
681 self.apply_super_step(state, [(node, updates)])
682 }
683}
684
685#[cfg(test)]
686mod tests {
687 use super::*;
688 use serde_json::json;
689
690 fn updates(pairs: &[(&str, Value)]) -> HashMap<String, Value> {
691 pairs
692 .iter()
693 .map(|(k, v)| (k.to_string(), v.clone()))
694 .collect()
695 }
696
697 #[test]
698 fn overwrite_replaces() {
699 let mut state = State::new();
700 let spec = StateSpec::new().channel("x", Reducer::Overwrite);
701 spec.apply_single(&mut state, "n1", updates(&[("x", json!(1))]))
702 .unwrap();
703 spec.apply_single(&mut state, "n2", updates(&[("x", json!(2))]))
704 .unwrap();
705 assert_eq!(state.get("x"), Some(&json!(2)));
706 }
707
708 #[test]
709 fn last_value_double_write_fails() {
710 let mut state = State::new();
711 let spec = StateSpec::new().channel("x", Reducer::Overwrite);
712 let writes = vec![
713 ("a".to_string(), updates(&[("x", json!(1))])),
714 ("b".to_string(), updates(&[("x", json!(2))])),
715 ];
716 let err = spec.apply_super_step(&mut state, writes).unwrap_err();
717 assert!(matches!(err, RustyError::InvalidUpdate(_)));
718 }
719
720 #[test]
721 fn append_allows_fan_in() {
722 let mut state = State::new();
723 let spec = StateSpec::new().channel("xs", Reducer::Append);
724 let writes = vec![
725 ("a".to_string(), updates(&[("xs", json!([1, 2]))])),
726 ("b".to_string(), updates(&[("xs", json!(3))])),
727 ];
728 spec.apply_super_step(&mut state, writes).unwrap();
729 assert_eq!(state.get("xs"), Some(&json!([1, 2, 3])));
730 }
731
732 #[test]
733 fn deep_merge_is_recursive() {
734 let mut state = State::from_value(json!({"cfg": {"a": 1, "nested": {"x": 1}}})).unwrap();
735 let spec = StateSpec::new().channel("cfg", Reducer::DeepMerge);
736 spec.apply_single(
737 &mut state,
738 "n",
739 updates(&[("cfg", json!({"nested": {"y": 2}}))]),
740 )
741 .unwrap();
742 assert_eq!(
743 state.get("cfg"),
744 Some(&json!({"a": 1, "nested": {"x": 1, "y": 2}}))
745 );
746 }
747
748 #[test]
749 fn add_messages_upserts_by_id() {
750 let mut state = State::from_value(json!({
751 "messages": [{"id": "m1", "content": "old"}, {"content": "plain"}]
752 }))
753 .unwrap();
754 let spec = StateSpec::new().channel("messages", Reducer::AddMessages);
755 spec.apply_single(
756 &mut state,
757 "n",
758 updates(&[(
759 "messages",
760 json!([
761 {"id": "m1", "content": "new"},
762 {"content": "appended"}
763 ]),
764 )]),
765 )
766 .unwrap();
767 assert_eq!(
768 state.get("messages"),
769 Some(&json!([
770 {"id": "m1", "content": "new"},
771 {"content": "plain"},
772 {"content": "appended"}
773 ]))
774 );
775 }
776
777 #[test]
778 fn undeclared_channel_rejected() {
779 let mut state = State::new();
780 let spec = StateSpec::new().channel("x", Reducer::Overwrite);
781 let err = spec
782 .apply_single(&mut state, "n", updates(&[("y", json!(1))]))
783 .unwrap_err();
784 assert!(matches!(err, RustyError::InvalidUpdate(_)));
785 }
786
787 #[test]
788 fn fan_in_merge_order_is_deterministic() {
789 // The executor feeds writes in task-completion order; the merge must
790 // not depend on it.
791 let spec = StateSpec::new()
792 .channel("xs", Reducer::Append)
793 .channel("messages", Reducer::AddMessages);
794 let forward = vec![
795 (
796 "b".to_string(),
797 updates(&[("xs", json!([2])), ("messages", json!({"id": "b", "v": 2}))]),
798 ),
799 (
800 "a".to_string(),
801 updates(&[("xs", json!([1])), ("messages", json!({"id": "a", "v": 1}))]),
802 ),
803 ];
804 let mut reversed = forward.clone();
805 reversed.reverse();
806
807 let mut s1 = State::new();
808 let mut s2 = State::new();
809 spec.apply_super_step(&mut s1, forward).unwrap();
810 spec.apply_super_step(&mut s2, reversed).unwrap();
811 assert_eq!(s1, s2);
812 assert_eq!(s1.get("xs"), Some(&json!([1, 2])));
813 assert_eq!(
814 s1.get("messages"),
815 Some(&json!([{"id": "a", "v": 1}, {"id": "b", "v": 2}]))
816 );
817 }
818
819 #[test]
820 fn append_rejects_non_array_current_value() {
821 let mut state = State::from_value(json!({"xs": {"oops": "object"}})).unwrap();
822 let spec = StateSpec::new().channel("xs", Reducer::Append);
823 let err = spec
824 .apply_single(&mut state, "n", updates(&[("xs", json!([1]))]))
825 .unwrap_err();
826 assert!(matches!(err, RustyError::InvalidUpdate(_)));
827 // All-or-nothing: the failed super-step leaves state untouched.
828 assert_eq!(state.get("xs"), Some(&json!({"oops": "object"})));
829 }
830
831 #[test]
832 fn add_messages_rejects_non_array_current_value() {
833 let mut state = State::from_value(json!({"messages": 42})).unwrap();
834 let spec = StateSpec::new().channel("messages", Reducer::AddMessages);
835 let err = spec
836 .apply_single(
837 &mut state,
838 "n",
839 updates(&[("messages", json!({"id": "m1"}))]),
840 )
841 .unwrap_err();
842 assert!(matches!(err, RustyError::InvalidUpdate(_)));
843 assert_eq!(state.get("messages"), Some(&json!(42)));
844 }
845
846 // ---- Copy-on-write representation (R0.7 wave 4) ----
847
848 #[test]
849 fn clone_shares_channels_until_write() {
850 let mut state = State::from_value(json!({"a": [1, 2, 3], "b": {"x": 1}})).unwrap();
851 let snapshot = state.clone();
852
853 // Cloning shares every channel (pointer-identical, no copies).
854 for channel in ["a", "b"] {
855 assert!(Arc::ptr_eq(
856 &state.shared_channel(channel).unwrap(),
857 &snapshot.shared_channel(channel).unwrap()
858 ));
859 }
860
861 // A write to one channel copies only that channel; the other stays
862 // shared with the snapshot.
863 state.insert("a", json!([9]));
864 assert!(!Arc::ptr_eq(
865 &state.shared_channel("a").unwrap(),
866 &snapshot.shared_channel("a").unwrap()
867 ));
868 assert!(Arc::ptr_eq(
869 &state.shared_channel("b").unwrap(),
870 &snapshot.shared_channel("b").unwrap()
871 ));
872 // Isolation: the snapshot is untouched.
873 assert_eq!(snapshot.get("a"), Some(&json!([1, 2, 3])));
874 assert_eq!(state.get("a"), Some(&json!([9])));
875 }
876
877 #[test]
878 fn reducer_merge_is_copy_on_write_at_channel_granularity() {
879 let spec = StateSpec::new()
880 .channel("xs", Reducer::Append)
881 .channel("ys", Reducer::Append);
882 let mut state = State::from_value(json!({"xs": [1], "ys": ["keep"]})).unwrap();
883 let snapshot = state.clone();
884
885 // Merge into `xs` while `snapshot` is alive: `xs` is copied
886 // (snapshot keeps the old array), `ys` is never touched.
887 spec.apply_single(&mut state, "n", updates(&[("xs", json!(2))]))
888 .unwrap();
889 assert_eq!(state.get("xs"), Some(&json!([1, 2])));
890 assert_eq!(snapshot.get("xs"), Some(&json!([1])));
891 assert!(Arc::ptr_eq(
892 &state.shared_channel("ys").unwrap(),
893 &snapshot.shared_channel("ys").unwrap()
894 ));
895 }
896
897 #[test]
898 fn append_mutates_in_place_when_uniquely_owned() {
899 let spec = StateSpec::new().channel("xs", Reducer::Append);
900 let mut state = State::from_value(json!({"xs": [1]})).unwrap();
901 let before = Arc::as_ptr(&state.shared_channel("xs").unwrap());
902 spec.apply_single(&mut state, "n", updates(&[("xs", json!(2))]))
903 .unwrap();
904 // Unique ownership: the merge reused the same allocation instead of
905 // cloning the array.
906 assert_eq!(state.get("xs"), Some(&json!([1, 2])));
907 assert_eq!(before, Arc::as_ptr(&state.shared_channel("xs").unwrap()));
908 }
909
910 #[test]
911 fn deep_merge_mutates_in_place_when_uniquely_owned() {
912 let spec = StateSpec::new().channel("cfg", Reducer::DeepMerge);
913 let mut state = State::from_value(json!({"cfg": {"a": 1, "nested": {"x": 1}}})).unwrap();
914 let before = Arc::as_ptr(&state.shared_channel("cfg").unwrap());
915 spec.apply_single(
916 &mut state,
917 "n",
918 updates(&[("cfg", json!({"nested": {"y": 2}}))]),
919 )
920 .unwrap();
921 assert_eq!(
922 state.get("cfg"),
923 Some(&json!({"a": 1, "nested": {"x": 1, "y": 2}}))
924 );
925 assert_eq!(before, Arc::as_ptr(&state.shared_channel("cfg").unwrap()));
926 }
927
928 #[test]
929 fn serde_is_byte_identical_to_plain_map() {
930 let state = State::from_value(json!({
931 "blob": "payload",
932 "meta": {"kind": "test", "n": 42},
933 "list": [1, 2.5, null, true]
934 }))
935 .unwrap();
936 let plain = state.to_value();
937
938 // Compact and pretty forms both match the plain-Value serialization
939 // of the same object — the pre-W4 transparent-Map wire shape.
940 assert_eq!(
941 serde_json::to_string(&state).unwrap(),
942 serde_json::to_string(&plain).unwrap()
943 );
944 assert_eq!(
945 serde_json::to_string_pretty(&state).unwrap(),
946 serde_json::to_string_pretty(&plain).unwrap()
947 );
948
949 // Deserialize round-trips through both representations.
950 let from_state_json: State =
951 serde_json::from_str(&serde_json::to_string(&state).unwrap()).unwrap();
952 let from_value_json: State = serde_json::from_value(plain).unwrap();
953 assert_eq!(state, from_state_json);
954 assert_eq!(state, from_value_json);
955 }
956
957 #[test]
958 fn into_map_and_iter_round_trip() {
959 let state = State::from_value(json!({"a": 1, "b": [2]})).unwrap();
960 let iterated: HashMap<String, Value> = state
961 .iter()
962 .map(|(k, v)| (k.to_owned(), v.clone()))
963 .collect();
964 assert_eq!(iterated["a"], json!(1));
965 assert_eq!(iterated["b"], json!([2]));
966
967 // Shared with a clone: into_map still yields owned values.
968 let snapshot = state.clone();
969 let map = state.into_map();
970 assert_eq!(map["a"], json!(1));
971 assert_eq!(snapshot.get("b"), Some(&json!([2])));
972 }
973
974 #[test]
975 fn channels_changed_since_diffs_by_pointer_then_value() {
976 let base =
977 State::from_value(json!({"same": 1, "changed": [1], "gone_from_delta": true})).unwrap();
978 let mut next = base.clone();
979 next.insert("changed", json!([1, 2]));
980 next.insert("new", json!("hello"));
981 // Rebuilt with identical content: value-equal but not pointer-equal.
982 next.insert("same", json!(1));
983
984 let delta = next.channels_changed_since(&base);
985 let names: Vec<&str> = delta.iter().map(|(k, _)| k.as_str()).collect();
986 // `changed` (new value) and `new` (absent from base) are in; the
987 // value-equal rebuild of `same` is deduped; `gone_from_delta` is
988 // unchanged and channels are never deleted.
989 assert_eq!(names, ["changed", "new"]);
990
991 // Against an empty base every channel is a change.
992 assert_eq!(next.channels_changed_since(&State::new()).len(), 4);
993 }
994}