zeph_memory/

recall_view.rs

// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
// SPDX-License-Identifier: MIT OR Apache-2.0

//! View-aware recall types for `MemCoT` graph retrieval (issues #3574 / #3575).
//!
//! [`RecallView`] selects the enrichment level applied to the raw graph recall results.
//! [`RecalledFact`] is the unified fact type returned by [`crate::semantic::SemanticMemory::recall_graph_view`].

use crate::graph::types::GraphFact;
use crate::types::MessageId;

pub use zeph_common::memory::RecallView;

/// A graph fact returned by the view-aware recall path.
///
/// Wraps a base [`GraphFact`] and carries optional enrichment fields populated
/// depending on the [`RecallView`] in use.
///
/// # Examples
///
/// ```
/// use zeph_memory::{RecalledFact, RecallView};
/// use zeph_memory::graph::types::GraphFact;
/// use zeph_memory::graph::EdgeType;
///
/// let base = GraphFact {
///     entity_name: "Rust".to_string(),
///     relation: "uses".to_string(),
///     target_name: "LLVM".to_string(),
///     fact: "Rust uses LLVM for code generation".to_string(),
///     entity_match_score: 0.9,
///     hop_distance: 0,
///     confidence: 0.95,
///     valid_from: None,
///     edge_type: EdgeType::Semantic,
///     retrieval_count: 1,
///     edge_id: None,
/// };
/// let recalled = RecalledFact::from_graph_fact(base);
/// assert!(recalled.activation_score.is_none());
/// assert!(recalled.provenance_message_id.is_none());
/// assert!(recalled.neighbors.is_empty());
/// ```
#[derive(Debug, Clone)]
pub struct RecalledFact {
    /// The base graph fact (text, relation, confidence, `edge_type`, `hop_distance`).
    pub fact: GraphFact,
    /// Spreading-activation score. `Some` when the SA path was used; `None` for plain BFS.
    ///
    /// Used by the assembler to render `(activation: X)` suffix and preserve
    /// current output bytes when `view = Head`.
    pub activation_score: Option<f32>,
    /// Source-message ID for the edge (Zoom-In only).
    pub provenance_message_id: Option<MessageId>,
    /// ≤200-char snippet from the source message, with `\n\r<>` scrubbed (Zoom-In only).
    pub provenance_snippet: Option<String>,
    /// 1-hop neighbor facts deduped against the head set (Zoom-Out only).
    pub neighbors: Vec<GraphFact>,
}

impl RecalledFact {
    /// Wrap a plain `GraphFact` with no enrichment fields set.
    #[must_use]
    pub fn from_graph_fact(fact: GraphFact) -> Self {
        Self {
            fact,
            activation_score: None,
            provenance_message_id: None,
            provenance_snippet: None,
            neighbors: Vec::new(),
        }
    }

    /// Wrap a SYNAPSE spreading-activation result, preserving its activation score and
    /// source-message provenance.
    ///
    /// `entity_name`/`target_name` are left empty because spreading activation does not
    /// resolve entity names — callers format the fact via `edge.fact` instead.
    #[must_use]
    pub fn from_activated_fact(af: crate::graph::activation::ActivatedFact) -> Self {
        let activation_score = af.activation_score;
        let edge = af.edge;
        let fact = GraphFact {
            entity_name: String::new(),
            relation: edge.canonical_relation.clone(),
            target_name: String::new(),
            fact: edge.fact.clone(),
            entity_match_score: activation_score,
            hop_distance: 0,
            confidence: edge.confidence,
            valid_from: if edge.valid_from.is_empty() {
                None
            } else {
                Some(edge.valid_from.clone())
            },
            edge_type: edge.edge_type,
            retrieval_count: edge.retrieval_count,
            edge_id: Some(edge.id),
        };
        Self {
            fact,
            activation_score: Some(activation_score),
            provenance_message_id: edge.source_message_id,
            provenance_snippet: None,
            neighbors: Vec::new(),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::graph::types::{EdgeType, GraphFact};
    use crate::types::MessageId;

    fn make_fact() -> GraphFact {
        GraphFact {
            entity_name: "Rust".to_string(),
            relation: "uses".to_string(),
            target_name: "LLVM".to_string(),
            fact: "Rust uses LLVM".to_string(),
            entity_match_score: 0.9,
            hop_distance: 0,
            confidence: 0.95,
            valid_from: None,
            edge_type: EdgeType::Semantic,
            retrieval_count: 0,
            edge_id: None,
        }
    }

    #[test]
    fn from_graph_fact_no_enrichment() {
        let rf = RecalledFact::from_graph_fact(make_fact());
        assert!(rf.activation_score.is_none());
        assert!(rf.provenance_message_id.is_none());
        assert!(rf.provenance_snippet.is_none());
        assert!(rf.neighbors.is_empty());
    }

    #[test]
    fn recall_view_default_is_head() {
        assert_eq!(RecallView::default(), RecallView::Head);
    }

    // ── Snapshot tests: Head / ZoomIn / ZoomOut output shape ─────────────────

    fn head_fact() -> RecalledFact {
        RecalledFact::from_graph_fact(GraphFact {
            entity_name: "Rust".to_string(),
            relation: "uses".to_string(),
            target_name: "LLVM".to_string(),
            fact: "Rust uses LLVM for code generation".to_string(),
            entity_match_score: 0.9,
            hop_distance: 0,
            confidence: 0.95,
            valid_from: Some("2026-01-01".to_string()),
            edge_type: EdgeType::Semantic,
            retrieval_count: 1,
            edge_id: Some(10),
        })
    }

    #[test]
    fn snapshot_head_no_enrichment() {
        let rf = head_fact();
        insta::assert_debug_snapshot!("head_view", rf);
    }

    #[test]
    fn snapshot_zoom_in_with_provenance() {
        let mut rf = head_fact();
        rf.provenance_message_id = Some(MessageId(42));
        rf.provenance_snippet = Some("The Rust compiler uses LLVM as its backend".to_string());
        insta::assert_debug_snapshot!("zoom_in_view", rf);
    }

    #[test]
    fn snapshot_zoom_out_with_neighbors() {
        let mut rf = head_fact();
        rf.neighbors.push(GraphFact {
            entity_name: "LLVM".to_string(),
            relation: "supports".to_string(),
            target_name: "WebAssembly".to_string(),
            fact: "LLVM supports WebAssembly output".to_string(),
            entity_match_score: 0.5,
            hop_distance: 1,
            confidence: 0.8,
            valid_from: None,
            edge_type: EdgeType::Semantic,
            retrieval_count: 0,
            edge_id: Some(11),
        });
        insta::assert_debug_snapshot!("zoom_out_view", rf);
    }

    #[test]
    fn snapshot_sa_fact_with_activation_score() {
        // Simulate an SA-path fact: activation_score is Some, entity names are empty.
        let rf = RecalledFact {
            fact: GraphFact {
                entity_name: String::new(),
                relation: "uses".to_string(),
                target_name: String::new(),
                fact: "Rust uses LLVM for compilation".to_string(),
                entity_match_score: 0.82,
                hop_distance: 0,
                confidence: 0.9,
                valid_from: Some("2026-01-01".to_string()),
                edge_type: EdgeType::Semantic,
                retrieval_count: 0,
                edge_id: Some(55),
            },
            activation_score: Some(0.82),
            provenance_message_id: None,
            provenance_snippet: None,
            neighbors: Vec::new(),
        };
        insta::assert_debug_snapshot!("sa_head_view", rf);
    }
}