Struct State 

pub struct State { /* private fields */ }

A concurrent, type-safe state container that agents read from and write to.

By default, set() writes directly to the inner store. When delta tracking is enabled via with_delta_tracking(), writes go to a separate delta map (with tombstones) that can be atomically committed or rolled back.

Implementations

impl State

pub fn new() -> Self

Create a new empty state container.

pub fn with_delta_tracking(&self) -> State

Create a new State with delta tracking enabled. Writes go to the delta map; reads check delta first, then inner.

pub fn set_journal_sink(&self, sink: Arc<dyn JournalSink>)

Install a durable JournalSink that receives every state mutation.

The sink is shared with all clones and delta views of this State (like the in-memory ring) and is invoked synchronously on the write path — keep it cheap. The in-memory ring keeps serving recent_mutations/evidence; the sink adds unbounded durability.

pub fn with_journal_sink(self, sink: Arc<dyn JournalSink>) -> Self

Builder-style variant of set_journal_sink.

pub fn set_clock(&self, clock: SharedClock)

Replace the Clock this state and everything sharing it read the time from. Defaults to the system clock.

The clock is shared with every clone and delta view, like the journal sink. Swap it before a session starts; components that captured an instant from the old clock compare it against the new one.

pub fn with_clock(self, clock: SharedClock) -> Self

Builder-style variant of set_clock.

pub fn clock(&self) -> SharedClock

The clock this state reads the time from.

pub fn redact_keys<I, S>(&self, keys: I)

where I: IntoIterator<Item = S>, S: Into<String>,

Mark keys as sensitive: wherever this state’s values leave the process, a redacted key’s value is replaced by REDACTED. That covers the durable journal sink, persistence snapshots (to_redacted_hashmap) and the runtime’s extraction events. Reads inside the process (get, guards, tools) still see the real value.

A key k also covers its scoped forms: app:k, user:k, state_meta:k, and any other prefix:k. Shared with clones and delta views. Adds to the keys already marked.

pub fn redacted_keys(&self) -> BTreeSet<String>

The keys marked sensitive with redact_keys.

pub fn is_redacted(&self, key: &str) -> bool

Whether key (or the base key under its scope prefix) is marked sensitive.

pub fn redact_value(&self, key: &str, value: &Value) -> Value

value as it may leave the process under key.

pub fn redact_fields(&self, value: &Value) -> Value

Mask the redacted fields of a JSON object (one level deep); other values pass through.

pub fn to_redacted_hashmap(&self) -> HashMap<String, Value>

to_hashmap with redacted keys masked: what a persistence snapshot or an export should hold.

pub fn get<T: DeserializeOwned>(&self, key: &str) -> Option<T>

Get a value by key, attempting to deserialize to the requested type. When delta tracking is enabled, checks delta first, then inner.

This is the lenient read: a value that is present but of the wrong type is reported as None, indistinguishable from an absent key. Use try_get when that distinction matters.

pub fn try_get<T: DeserializeOwned>( &self, key: &str, ) -> Result<Option<T>, StateError>

Get a value by key, distinguishing “absent” from “present but the wrong type”.

Returns Ok(None) when no value is stored at key (after the same delta → inner → derived: lookup as get), Ok(Some(v)) when the stored value deserializes to T, and StateError::WrongType when a value exists but does not. This is the strict read; get is the lenient form that folds the error case into None.

pub fn with<F, R>(&self, key: &str, f: F) -> Option<R>

where F: FnOnce(&Value) -> R,

Borrow a value by key without cloning, applying f to the reference.

This is the zero-copy alternative to get_raw(). The closure receives a &Value directly from the DashMap ref-guard, avoiding the Value::clone() + serde_json::from_value() overhead of get().

Lookup order: delta (if tracking) → inner → derived fallback.

pub fn get_raw(&self, key: &str) -> Option<Value>

Get a raw JSON value by key. When delta tracking is enabled, checks delta first, then inner. If the key is not found and doesn’t contain a prefix, also checks derived:{key} as a transparent fallback for computed variables.

pub fn get_key<T: DeserializeOwned>(&self, key: &StateKey<T>) -> Option<T>

Get a typed value using a StateKey<T> (lenient — a wrong-typed value reads as None; see get).

pub fn try_get_key<T: DeserializeOwned>( &self, key: &StateKey<T>, ) -> Result<Option<T>, StateError>

Get a typed value using a StateKey<T>, distinguishing “absent” from “present but the wrong type” (see try_get).

pub fn set_key<T: Serialize>( &self, key: &StateKey<T>, value: T, ) -> Result<(), StateError>

Set a typed value using a StateKey<T>.

Returns StateError if value cannot be serialized to JSON.

pub fn with_key<T, F, R>(&self, key: &StateKey<T>, f: F) -> Option<R>

where F: FnOnce(&Value) -> R,

Zero-copy borrow using a StateKey<T>.

pub fn set( &self, key: impl Into<String>, value: impl Serialize, ) -> Result<(), StateError>

Set a value by key.

When delta tracking is enabled, writes to the delta view instead of the committed store. Returns StateError if value cannot be serialized to JSON — a public SDK write never panics on caller data.

pub fn set_committed( &self, key: impl Into<String>, value: impl Serialize, ) -> Result<(), StateError>

Set a value directly in the committed store, bypassing delta tracking.

Returns StateError if value cannot be serialized to JSON.

pub fn modify<T, F>(&self, key: &str, default: T, f: F) -> Result<T, StateError>

where T: Serialize + DeserializeOwned, F: FnOnce(T) -> T,

Atomically read-modify-write a value under a per-key lock.

If the key doesn’t exist, default is used as the initial value. The function f receives the current value and returns the new value. The read-modify-write is performed while holding the map shard for key, so concurrent modify calls on the same key do not lose updates. Returns the new value, or StateError if it cannot be serialized.

pub fn contains(&self, key: &str) -> bool

Check if a key exists (in delta or inner).

Applies the same transparent derived: fallback as Self::get, Self::get_raw and Self::with: an unprefixed key also matches the computed variable derived:{key}. Flow predicates (is_set, captured) evaluate through this method, so without the fallback a computed value would read as permanently unknown while get returned it fine.

pub fn remove(&self, key: &str) -> Option<Value>

Remove a key.

In delta-tracking mode this records a tombstone in the delta view and leaves the committed store untouched, so a subsequent rollback() fully restores the base state. Returns the value that was visible before removal.

pub fn keys(&self) -> Vec<String>

Get all keys (from both inner and delta when tracking).

Keys tombstoned in the delta are excluded.

pub fn pick(&self, keys: &[&str]) -> State

Create a new State containing only the specified keys.

pub fn merge(&self, other: &State)

Merge another state into this one (other’s values overwrite on conflict).

pub fn rename(&self, from: &str, to: &str)

Rename a key.

pub fn is_tracking_delta(&self) -> bool

Whether delta tracking is enabled.

pub fn has_delta(&self) -> bool

Whether there are uncommitted delta changes.

pub fn delta(&self) -> HashMap<String, Value>

Get a snapshot of the current delta’s pending writes (tombstones omitted).

pub fn commit(&self)

Commit delta changes into the inner store, then clear the delta.

Pending puts are applied and tombstones remove the committed key, so a removal made under delta tracking becomes durable only at commit time.

pub fn rollback(&self)

Discard all uncommitted delta changes, restoring the committed base state.

Because removals and prefix clears under delta tracking only write tombstones (never mutating inner), dropping the delta is sufficient to restore the base — including keys that were removed in the transaction.

pub fn app(&self) -> PrefixedState<'_>

Access state with the app: prefix scope.

pub fn user(&self) -> PrefixedState<'_>

Access state with the user: prefix scope.

pub fn temp(&self) -> PrefixedState<'_>

Access state with the temp: prefix scope.

pub fn session(&self) -> PrefixedState<'_>

Access state with the session: prefix scope (auto-tracked signals).

pub fn turn(&self) -> PrefixedState<'_>

Access state with the turn: prefix scope (reset each turn).

pub fn bg(&self) -> PrefixedState<'_>

Access state with the bg: prefix scope (background tasks).

pub fn derived(&self) -> ReadOnlyPrefixedState<'_>

Access read-only state with the derived: prefix scope (computed vars only).

pub fn snapshot_values(&self, keys: &[&str]) -> HashMap<String, Value>

Snapshot the values of specific keys. Returns HashMap of key -> current value. Used by watchers to capture state before mutations.

pub fn diff_values( &self, prev: &HashMap<String, Value>, keys: &[&str], ) -> Vec<(String, Value, Value)>

Diff current state against a previous snapshot. Returns Vec of (key, old_value, new_value) for keys that changed.

pub fn to_hashmap(&self) -> HashMap<String, Value>

Export all state as a HashMap (for persistence/serialization).

pub fn from_hashmap(&self, map: HashMap<String, Value>)

Restore state from a HashMap (for persistence/deserialization).

pub fn clear_prefix(&self, prefix: &str)

Remove all keys with the given prefix.

In delta-tracking mode this writes tombstones for matching keys (from both the committed store and pending delta puts) without mutating the committed store, so rollback() restores everything that was cleared.

pub fn recent_mutations(&self) -> Vec<StateMutation>

Return a snapshot of recent state mutations.

pub fn mutation_cursor(&self) -> u64

Return the current monotonic cursor for the mutation journal.

pub fn mutations_since(&self, cursor: u64) -> Vec<StateMutation>

Return mutations appended after a previously captured cursor.

pub fn try_mutations_since(&self, cursor: u64) -> Option<Vec<StateMutation>>

Mutations appended after cursor, or None if the bounded journal has already dropped some of them.

A consumer that must see every change (a derived-value cache, say) uses this instead of mutations_since and falls back to a full rescan on None.

pub fn drain_mutations(&self) -> Vec<StateMutation>

Drain and return all recorded state mutations.

pub fn evidence(&self, key: &str) -> SlotEvidence

Aggregate the SlotEvidence for a key: its current value, provenance (state_meta:{key}), confidence, and most-recent journal write.

Trait Implementations

impl Clone for State

fn clone(&self) -> State

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for State

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for State

fn default() -> Self

Returns the “default value” for a type.