clawft_kernel/

crossref.rs

//! Universal cross-references between forest structures.
//!
//! This module is compiled only when the `ecc` feature is enabled.
//! It provides [`UniversalNodeId`] (BLAKE3-hashed identity for any node),
//! [`CrossRef`] (a typed directed edge between two nodes), and
//! [`CrossRefStore`] (a concurrent forward/reverse index).

use std::fmt;
use std::sync::atomic::{AtomicU64, Ordering};

use dashmap::DashMap;
use serde::{Deserialize, Serialize};

// ---------------------------------------------------------------------------
// StructureTag
// ---------------------------------------------------------------------------

/// Identifies which forest structure a node belongs to.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum StructureTag {
    /// ExoChain ledger (0x01).
    ExoChain,
    /// Resource tree (0x02).
    ResourceTree,
    /// Causal graph (0x03).
    CausalGraph,
    /// HNSW vector index (0x04).
    HnswIndex,
    /// Domain-specific extension (0x10+).
    Custom(u8),
}

impl StructureTag {
    /// Returns the canonical byte discriminant.
    pub fn as_u8(&self) -> u8 {
        match self {
            Self::ExoChain => 0x01,
            Self::ResourceTree => 0x02,
            Self::CausalGraph => 0x03,
            Self::HnswIndex => 0x04,
            Self::Custom(v) => *v,
        }
    }
}

impl fmt::Display for StructureTag {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::ExoChain => write!(f, "ExoChain"),
            Self::ResourceTree => write!(f, "ResourceTree"),
            Self::CausalGraph => write!(f, "CausalGraph"),
            Self::HnswIndex => write!(f, "HnswIndex"),
            Self::Custom(v) => write!(f, "Custom(0x{v:02x})"),
        }
    }
}

// ---------------------------------------------------------------------------
// UniversalNodeId
// ---------------------------------------------------------------------------

/// A 32-byte BLAKE3 hash that uniquely identifies any node across all
/// forest structures.
#[derive(Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct UniversalNodeId(pub [u8; 32]);

impl UniversalNodeId {
    /// Derive a deterministic identity by hashing the concatenation of all
    /// constituent fields via BLAKE3.
    pub fn new(
        structure_tag: &StructureTag,
        context_id: &[u8],
        hlc_timestamp: u64,
        content_hash: &[u8],
        parent_id: &[u8],
    ) -> Self {
        let mut hasher = blake3::Hasher::new();
        hasher.update(&[structure_tag.as_u8()]);
        hasher.update(context_id);
        hasher.update(&hlc_timestamp.to_le_bytes());
        hasher.update(content_hash);
        hasher.update(parent_id);
        Self(*hasher.finalize().as_bytes())
    }

    /// The all-zeros sentinel ID.
    pub fn zero() -> Self {
        Self([0u8; 32])
    }

    /// Construct from a raw 32-byte array.
    pub fn from_bytes(bytes: [u8; 32]) -> Self {
        Self(bytes)
    }

    /// Borrow the inner bytes.
    pub fn as_bytes(&self) -> &[u8; 32] {
        &self.0
    }
}

impl fmt::Display for UniversalNodeId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        for b in &self.0 {
            write!(f, "{b:02x}")?;
        }
        Ok(())
    }
}

impl fmt::Debug for UniversalNodeId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "UniversalNodeId({self})")
    }
}

// ---------------------------------------------------------------------------
// CrossRefType
// ---------------------------------------------------------------------------

/// The semantic relationship carried by a [`CrossRef`].
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum CrossRefType {
    /// Source was triggered by target (0x01).
    TriggeredBy,
    /// Source is evidence for target (0x02).
    EvidenceFor,
    /// Source elaborates on target (0x03).
    Elaborates,
    /// Source is the emotional cause of target (0x04).
    EmotionCause,
    /// Source provides goal motivation for target (0x05).
    GoalMotivation,
    /// Scene boundary marker (0x06).
    SceneBoundary,
    /// Memory encoding link (0x09).
    MemoryEncoded,
    /// Theory-of-mind inference (0x0A).
    TomInference,
    /// Backchannel continuer (0x0B, ADR-062 D5): a "mm-hmm" linking a listener
    /// to the current speaker node **without** creating a turn node.
    Continuer,
    /// Per-speaker association (0x0C, ADR-062 §Architecture / ADR-046 forest
    /// join): links a turn node to the stable identity node of whoever produced
    /// it. Lets the forest walk recall a speaker's prior turns as cross-structure
    /// context, not by cosine alone.
    Speaker,
    /// Domain-specific extension.
    Custom(u8),
}

impl fmt::Display for CrossRefType {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::TriggeredBy => write!(f, "TriggeredBy"),
            Self::EvidenceFor => write!(f, "EvidenceFor"),
            Self::Elaborates => write!(f, "Elaborates"),
            Self::EmotionCause => write!(f, "EmotionCause"),
            Self::GoalMotivation => write!(f, "GoalMotivation"),
            Self::SceneBoundary => write!(f, "SceneBoundary"),
            Self::MemoryEncoded => write!(f, "MemoryEncoded"),
            Self::TomInference => write!(f, "TomInference"),
            Self::Continuer => write!(f, "Continuer"),
            Self::Speaker => write!(f, "Speaker"),
            Self::Custom(v) => write!(f, "Custom(0x{v:02x})"),
        }
    }
}

// ---------------------------------------------------------------------------
// CrossRef
// ---------------------------------------------------------------------------

/// A directed, typed cross-reference between two universal nodes.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CrossRef {
    /// The originating node.
    pub source: UniversalNodeId,
    /// Which structure the source lives in.
    pub source_structure: StructureTag,
    /// The destination node.
    pub target: UniversalNodeId,
    /// Which structure the target lives in.
    pub target_structure: StructureTag,
    /// Semantic relationship type.
    pub ref_type: CrossRefType,
    /// HLC timestamp at creation.
    pub created_at: u64,
    /// ExoChain sequence number for provenance.
    pub chain_seq: u64,
}

// ---------------------------------------------------------------------------
// CrossRefStore
// ---------------------------------------------------------------------------

/// Concurrent forward/reverse index of [`CrossRef`] edges.
pub struct CrossRefStore {
    forward: DashMap<UniversalNodeId, Vec<CrossRef>>,
    reverse: DashMap<UniversalNodeId, Vec<CrossRef>>,
    count: AtomicU64,
}

impl CrossRefStore {
    /// Create an empty store.
    pub fn new() -> Self {
        Self {
            forward: DashMap::new(),
            reverse: DashMap::new(),
            count: AtomicU64::new(0),
        }
    }

    /// Insert a cross-reference, indexing it in both directions.
    pub fn insert(&self, crossref: CrossRef) {
        self.forward
            .entry(crossref.source.clone())
            .or_default()
            .push(crossref.clone());
        self.reverse
            .entry(crossref.target.clone())
            .or_default()
            .push(crossref);
        self.count.fetch_add(1, Ordering::Relaxed);
    }

    /// All cross-refs originating from `id`.
    pub fn get_forward(&self, id: &UniversalNodeId) -> Vec<CrossRef> {
        self.forward
            .get(id)
            .map(|v| v.value().clone())
            .unwrap_or_default()
    }

    /// All cross-refs pointing *to* `id`.
    pub fn get_reverse(&self, id: &UniversalNodeId) -> Vec<CrossRef> {
        self.reverse
            .get(id)
            .map(|v| v.value().clone())
            .unwrap_or_default()
    }

    /// All cross-refs where `id` appears as source **or** target.
    pub fn get_all(&self, id: &UniversalNodeId) -> Vec<CrossRef> {
        let mut out = self.get_forward(id);
        out.extend(self.get_reverse(id));
        out
    }

    /// Total number of cross-refs inserted.
    pub fn count(&self) -> u64 {
        self.count.load(Ordering::Relaxed)
    }

    /// Filter cross-refs involving `id` (either direction) by relationship type.
    pub fn by_type(&self, id: &UniversalNodeId, ref_type: &CrossRefType) -> Vec<CrossRef> {
        self.get_all(id)
            .into_iter()
            .filter(|cr| &cr.ref_type == ref_type)
            .collect()
    }

    /// Every cross-ref in the store, each yielded exactly once.
    ///
    /// The forward index holds one copy of each cross-ref under its `source`
    /// key (the reverse index is the mirror), so flattening the forward map
    /// enumerates the store without duplication. Ordering is unspecified
    /// (`DashMap` iteration order). Intended for whole-store projections such as
    /// the `conversation.graph` RPC, which scopes the result to a conversation
    /// by intersecting each cross-ref's endpoints against that conversation's
    /// node UID set (there is no `conv_id` on a [`CrossRef`] to filter by
    /// directly).
    pub fn all(&self) -> Vec<CrossRef> {
        self.forward
            .iter()
            .flat_map(|entry| entry.value().clone())
            .collect()
    }

    /// Remove all entries (useful for calibration resets).
    pub fn clear(&self) {
        self.forward.clear();
        self.reverse.clear();
        self.count.store(0, Ordering::Relaxed);
    }
}

impl Default for CrossRefStore {
    fn default() -> Self {
        Self::new()
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;

    fn make_id(tag: &StructureTag, ctx: &[u8], ts: u64) -> UniversalNodeId {
        UniversalNodeId::new(tag, ctx, ts, b"hash", b"parent")
    }

    fn sample_crossref(src: UniversalNodeId, tgt: UniversalNodeId, rt: CrossRefType) -> CrossRef {
        CrossRef {
            source: src,
            source_structure: StructureTag::ExoChain,
            target: tgt,
            target_structure: StructureTag::ResourceTree,
            ref_type: rt,
            created_at: 1000,
            chain_seq: 42,
        }
    }

    #[test]
    fn universal_node_id_creation() {
        let id = make_id(&StructureTag::ExoChain, b"ctx", 1);
        assert_ne!(id.as_bytes(), &[0u8; 32]);
    }

    #[test]
    fn universal_node_id_deterministic() {
        let a = make_id(&StructureTag::ExoChain, b"ctx", 1);
        let b = make_id(&StructureTag::ExoChain, b"ctx", 1);
        assert_eq!(a, b);

        let c = make_id(&StructureTag::ExoChain, b"ctx", 2);
        assert_ne!(a, c);
    }

    #[test]
    fn universal_node_id_display_hex() {
        let id = UniversalNodeId::zero();
        let s = format!("{id}");
        assert_eq!(s.len(), 64);
        assert!(s.chars().all(|c| c.is_ascii_hexdigit()));
        assert_eq!(s, "0".repeat(64));
    }

    #[test]
    fn universal_node_id_zero() {
        let z = UniversalNodeId::zero();
        assert_eq!(z.as_bytes(), &[0u8; 32]);
        assert_eq!(z, UniversalNodeId::from_bytes([0u8; 32]));
    }

    #[test]
    fn structure_tag_as_u8() {
        assert_eq!(StructureTag::ExoChain.as_u8(), 0x01);
        assert_eq!(StructureTag::ResourceTree.as_u8(), 0x02);
        assert_eq!(StructureTag::CausalGraph.as_u8(), 0x03);
        assert_eq!(StructureTag::HnswIndex.as_u8(), 0x04);
        assert_eq!(StructureTag::Custom(0x10).as_u8(), 0x10);
    }

    #[test]
    fn structure_tag_display() {
        assert_eq!(StructureTag::ExoChain.to_string(), "ExoChain");
        assert_eq!(StructureTag::ResourceTree.to_string(), "ResourceTree");
        assert_eq!(StructureTag::Custom(0x10).to_string(), "Custom(0x10)");
    }

    #[test]
    fn crossref_type_display() {
        assert_eq!(CrossRefType::TriggeredBy.to_string(), "TriggeredBy");
        assert_eq!(CrossRefType::EvidenceFor.to_string(), "EvidenceFor");
        assert_eq!(CrossRefType::TomInference.to_string(), "TomInference");
        assert_eq!(CrossRefType::Custom(0xff).to_string(), "Custom(0xff)");
    }

    #[test]
    fn crossref_store_insert_and_get_forward() {
        let store = CrossRefStore::new();
        let src = make_id(&StructureTag::ExoChain, b"a", 1);
        let tgt = make_id(&StructureTag::ResourceTree, b"b", 2);
        store.insert(sample_crossref(src.clone(), tgt, CrossRefType::TriggeredBy));

        let fwd = store.get_forward(&src);
        assert_eq!(fwd.len(), 1);
        assert_eq!(fwd[0].ref_type, CrossRefType::TriggeredBy);
    }

    #[test]
    fn crossref_store_insert_and_get_reverse() {
        let store = CrossRefStore::new();
        let src = make_id(&StructureTag::ExoChain, b"a", 1);
        let tgt = make_id(&StructureTag::ResourceTree, b"b", 2);
        store.insert(sample_crossref(src, tgt.clone(), CrossRefType::EvidenceFor));

        let rev = store.get_reverse(&tgt);
        assert_eq!(rev.len(), 1);
        assert_eq!(rev[0].ref_type, CrossRefType::EvidenceFor);
    }

    #[test]
    fn crossref_store_get_all_both_directions() {
        let store = CrossRefStore::new();
        let a = make_id(&StructureTag::ExoChain, b"a", 1);
        let b = make_id(&StructureTag::ResourceTree, b"b", 2);
        let c = make_id(&StructureTag::CausalGraph, b"c", 3);

        // a -> b
        store.insert(sample_crossref(
            a.clone(),
            b.clone(),
            CrossRefType::TriggeredBy,
        ));
        // c -> a
        store.insert(sample_crossref(c, a.clone(), CrossRefType::Elaborates));

        let all = store.get_all(&a);
        assert_eq!(all.len(), 2);
        assert_eq!(store.count(), 2);
    }

    #[test]
    fn crossref_store_by_type() {
        let store = CrossRefStore::new();
        let a = make_id(&StructureTag::ExoChain, b"a", 1);
        let b = make_id(&StructureTag::ResourceTree, b"b", 2);
        let c = make_id(&StructureTag::CausalGraph, b"c", 3);

        store.insert(sample_crossref(a.clone(), b, CrossRefType::TriggeredBy));
        store.insert(sample_crossref(a.clone(), c, CrossRefType::EvidenceFor));

        let triggered = store.by_type(&a, &CrossRefType::TriggeredBy);
        assert_eq!(triggered.len(), 1);

        let evidence = store.by_type(&a, &CrossRefType::EvidenceFor);
        assert_eq!(evidence.len(), 1);

        let none = store.by_type(&a, &CrossRefType::SceneBoundary);
        assert!(none.is_empty());
    }

    #[test]
    fn crossref_store_resolves_continuer() {
        // ADR-062 D5: a backchannel is a Continuer cross-ref from listener to
        // the current speaker node, resolvable via by_type.
        let store = CrossRefStore::new();
        let listener = make_id(&StructureTag::CausalGraph, b"listener", 1);
        let speaker = make_id(&StructureTag::CausalGraph, b"speaker", 2);
        store.insert(sample_crossref(
            listener.clone(),
            speaker.clone(),
            CrossRefType::Continuer,
        ));
        // Unrelated edge that must not match.
        let other = make_id(&StructureTag::CausalGraph, b"other", 3);
        store.insert(sample_crossref(
            listener.clone(),
            other,
            CrossRefType::Elaborates,
        ));

        let continuers = store.by_type(&listener, &CrossRefType::Continuer);
        assert_eq!(continuers.len(), 1);
        assert_eq!(continuers[0].target, speaker);
        assert_eq!(continuers[0].ref_type, CrossRefType::Continuer);
        assert_eq!(CrossRefType::Continuer.to_string(), "Continuer");
    }

    #[test]
    fn crossref_store_clear() {
        let store = CrossRefStore::new();
        let a = make_id(&StructureTag::ExoChain, b"a", 1);
        let b = make_id(&StructureTag::ResourceTree, b"b", 2);
        store.insert(sample_crossref(a.clone(), b, CrossRefType::TriggeredBy));
        assert_eq!(store.count(), 1);

        store.clear();
        assert_eq!(store.count(), 0);
        assert!(store.get_forward(&a).is_empty());
    }
}