Skip to main content

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}