reef-core 0.4.0

Provider-neutral primitives for building LLM agents: run lifecycle, transcript, tools, hooks
Documentation
//! Typed, reference-sharing state scoped to one run.
//!
//! Slot identity travels with the key: a fresh key is a fresh slot, while
//! cloning a key preserves the slot it already names.

use std::any::Any;
use std::collections::HashMap;
use std::fmt::{self, Debug, Formatter};
use std::hash::{Hash, Hasher};
use std::marker::PhantomData;
use std::sync::{Arc, Mutex};

use crate::redact::Locked;

struct KeyToken {
    _non_zero_sized: u8,
}

#[derive(Clone)]
struct SlotId(Arc<KeyToken>);

impl PartialEq for SlotId {
    fn eq(&self, other: &Self) -> bool {
        Arc::ptr_eq(&self.0, &other.0)
    }
}

impl Eq for SlotId {}

impl Hash for SlotId {
    fn hash<H: Hasher>(&self, state: &mut H) {
        Arc::as_ptr(&self.0).hash(state);
    }
}

/// A typed handle to one run-state slot.
///
/// Every call to [`Key::new`] allocates a distinct private identity. Cloning a
/// key preserves that identity. Keys cannot be copied, defaulted, retagged, or
/// constructed from a raw identifier.
pub struct Key<T> {
    token: Arc<KeyToken>,
    marker: PhantomData<fn(T) -> T>,
}

#[expect(
    clippy::new_without_default,
    reason = "ADR-006 forbids Default because every key creation must be explicit"
)]
impl<T> Key<T> {
    /// Allocates a fresh slot identity.
    #[must_use]
    pub fn new() -> Self {
        Self {
            token: Arc::new(KeyToken { _non_zero_sized: 0 }),
            marker: PhantomData,
        }
    }

    fn slot_id(&self) -> SlotId {
        SlotId(Arc::clone(&self.token))
    }
}

impl<T> Clone for Key<T> {
    fn clone(&self) -> Self {
        Self {
            token: Arc::clone(&self.token),
            marker: PhantomData,
        }
    }
}

impl<T> Debug for Key<T> {
    /// Prints the slot identity, which is the whole of what a key is.
    ///
    /// There is deliberately no `T: Debug` bound: a key names a slot and never
    /// holds a `T`, so requiring the value type to be printable would make the
    /// key unprintable for exactly the opaque payloads run state exists to
    /// carry. Clones share one address; independently created keys do not.
    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Key")
            .field("slot", &Arc::as_ptr(&self.token))
            .finish()
    }
}

impl<T> PartialEq for Key<T> {
    fn eq(&self, other: &Self) -> bool {
        Arc::ptr_eq(&self.token, &other.token)
    }
}

impl<T> Eq for Key<T> {}

impl<T> Hash for Key<T> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        Arc::as_ptr(&self.token).hash(state);
    }
}

type ErasedValue = Arc<dyn Any + Send + Sync>;

/// A synchronized collection of typed run-state slots.
///
/// Each operation is atomic for its slot. Stored values are immutable shared
/// [`Arc`] references; callers must put synchronization inside `T` when they
/// need interior mutation.
///
/// # Panics
///
/// Every method here can panic for the same two reasons, and neither is
/// reachable by any argument a caller can construct.
///
/// A poisoned slot lock is propagated rather than recovered, per the crate-level
/// [lock-poisoning contract](crate#lock-poisoning).
///
/// A slot holding a value whose type is not the one its [`Key`] names panics as
/// a core invariant violation rather than being reported as an ordinary slot
/// miss. A key is the only way to address a slot, and it carries the type, so
/// this state can only arise from a defect inside this crate.
pub struct Store {
    slots: Arc<Mutex<HashMap<SlotId, ErasedValue>>>,
    // Preserve the frozen auto-trait surface while crate-private handles share slots.
    _freeze: Mutex<()>,
}

impl Debug for Store {
    /// Counts occupied slots without touching the type-erased values in them.
    ///
    /// A stored value is an `Arc<dyn Any + Send + Sync>` with no `Debug` to
    /// call, so an occupancy count is both the most and the least a formatter
    /// can honestly report. The count is taken non-blockingly.
    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
        let mut store = formatter.debug_struct("Store");
        match self.slots.try_lock() {
            Ok(slots) => store.field("slots", &slots.len()),
            Err(_contended_or_poisoned) => store.field("slots", &Locked),
        }
        .finish()
    }
}

#[expect(
    clippy::new_without_default,
    reason = "the frozen API exposes explicit Store::new without Default"
)]
impl Store {
    /// Creates an empty run-state store.
    #[must_use]
    pub fn new() -> Self {
        Self {
            slots: Arc::new(Mutex::new(HashMap::new())),
            _freeze: Mutex::new(()),
        }
    }

    /// Clones this store's identity for a crate-managed callback owner.
    pub(crate) fn clone_handle(&self) -> Self {
        Self {
            slots: Arc::clone(&self.slots),
            _freeze: Mutex::new(()),
        }
    }

    /// Loads the shared value in `key`, or returns `None` when the slot is absent.
    ///
    /// A key cannot be used with a value of another type:
    ///
    /// ```compile_fail
    /// use reef_core::state::run_state;
    /// use std::sync::Arc;
    /// fn wrong_type(
    ///     store: &run_state::Store,
    ///     key: &run_state::Key<u8>,
    ///     value: Arc<u16>,
    /// ) {
    ///     store.set(key, value);
    /// }
    /// ```
    ///
    /// # Panics
    ///
    /// On a poisoned slot lock or a violated slot type invariant, as
    /// [the store's panic conditions](Store#panics) describe.
    #[must_use]
    pub fn load<T>(&self, key: &Key<T>) -> Option<Arc<T>>
    where
        T: Send + Sync + 'static,
    {
        let erased = self
            .slots
            .lock()
            .expect("run-state lock poisoned")
            .get(&key.slot_id())
            .cloned()?;
        Some(downcast(erased))
    }

    /// Replaces the value in `key`, returning the prior shared value when present.
    ///
    /// # Panics
    ///
    /// On a poisoned slot lock or a violated slot type invariant, as
    /// [the store's panic conditions](Store#panics) describe.
    pub fn set<T>(&self, key: &Key<T>, value: Arc<T>) -> Option<Arc<T>>
    where
        T: Send + Sync + 'static,
    {
        self.slots
            .lock()
            .expect("run-state lock poisoned")
            .insert(key.slot_id(), value)
            .map(downcast)
    }

    /// Loads the existing value or stores `value` when the slot is absent.
    ///
    /// The boolean is `true` when an existing value won and `false` when this
    /// call inserted `value`.
    ///
    /// # Panics
    ///
    /// On a poisoned slot lock or a violated slot type invariant, as
    /// [the store's panic conditions](Store#panics) describe.
    pub fn load_or_store<T>(&self, key: &Key<T>, value: Arc<T>) -> (Arc<T>, bool)
    where
        T: Send + Sync + 'static,
    {
        let mut slots = self.slots.lock().expect("run-state lock poisoned");
        if let Some(existing) = slots.get(&key.slot_id()).cloned() {
            (downcast(existing), true)
        } else {
            slots.insert(key.slot_id(), value.clone());
            (value, false)
        }
    }

    /// Deletes `key`, returning the prior shared value when present.
    ///
    /// # Panics
    ///
    /// On a poisoned slot lock or a violated slot type invariant, as
    /// [the store's panic conditions](Store#panics) describe.
    pub fn delete<T>(&self, key: &Key<T>) -> Option<Arc<T>>
    where
        T: Send + Sync + 'static,
    {
        self.slots
            .lock()
            .expect("run-state lock poisoned")
            .remove(&key.slot_id())
            .map(downcast)
    }
}

/// Holds the slot lock so a `Debug` must observe contention.
#[cfg(test)]
pub(super) fn hold_slot_lock(
    store: &Store,
    held: &std::sync::Barrier,
    release: &std::sync::Barrier,
) {
    let _guard = store.slots.lock().expect("run-state lock poisoned");
    held.wait();
    release.wait();
}

#[cfg(test)]
pub(super) fn corrupt<T, U>(store: &Store, key: &Key<T>, value: Arc<U>)
where
    U: Send + Sync + 'static,
{
    store
        .slots
        .lock()
        .expect("run-state lock poisoned")
        .insert(key.slot_id(), value);
}

fn downcast<T>(value: ErasedValue) -> Arc<T>
where
    T: Send + Sync + 'static,
{
    value
        .downcast::<T>()
        .unwrap_or_else(|_| panic!("run-state slot type invariant violated"))
}