klieo-memory-graph 3.4.0

//! Retrieval-path types — graph-traversal output, optionally
//! enriched with a provenance anchor on each hop.
//!
//! Returned by [`crate::KnowledgeGraph::recall_paths`]. The default
//! [`PathHop::chain_entry`] is `None`; the
//! `ProvenanceKnowledgeGraph` wrapper in `klieo-memory-graph-rag`
//! populates the field by looking up each hop's `FactId` against a
//! `ProvenanceRepository`. `None` is the explicit signal of an
//! unsigned hop (e.g. fact indexed before the projector was
//! wrapped).
//!
//! ## Provenance feature gate
//!
//! `klieo-memory-graph` exposes the provenance anchor behind the
//! `provenance` feature (default ON). With the feature enabled,
//! `chain_entry` carries a real
//! [`klieo_provenance::ChainEntry`]. With `default-features =
//! false`, [`ChainEntry`] resolves to a unit-like placeholder so
//! the graph trait surface compiles without pulling the
//! audit-chain crate (`ed25519-dalek`, `sha2`, `hex`). The field
//! shape stays `Option<ChainEntry>` either way — adapters that
//! emit anchors must enable the feature.

use crate::types::EntityRef;
use klieo_core::ids::FactId;
use serde::{Deserialize, Serialize};

#[cfg(feature = "provenance")]
pub use klieo_provenance::ChainEntry;

/// Unit-like placeholder used when the `provenance` feature is
/// disabled. `Option<ChainEntry>` on [`PathHop`] resolves to this
/// type but is always `None` — no adapter can construct a value
/// of this shape without the feature.
#[cfg(not(feature = "provenance"))]
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct ChainEntry {}

/// One step along a retrieval traversal: an entity touched, the
/// fact it mentions, and (optionally) the signed chain entry that
/// proves the index call.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
#[allow(missing_docs)] // pub fields documented at the struct level above; per-field paraphrase is forbidden by the readability rubric
pub struct PathHop {
    pub entity: EntityRef,
    pub fact_id: FactId,
    pub chain_entry: Option<ChainEntry>,
}

impl PathHop {
    /// Returns a hop with no provenance anchor; the
    /// `ProvenanceKnowledgeGraph` wrapper assigns
    /// [`Self::chain_entry`] directly post-recall.
    pub fn new(entity: EntityRef, fact_id: FactId) -> Self {
        Self {
            entity,
            fact_id,
            chain_entry: None,
        }
    }
}

/// A single retrieval traversal — ordered hops from entry entity
/// to the deepest fact reached. Empty `hops` is a valid no-op
/// result (caller asked but the graph had no matching facts).
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[non_exhaustive]
#[allow(missing_docs)] // see PathHop above — pub fields documented at the struct level
pub struct RetrievalPath {
    pub hops: Vec<PathHop>,
}

impl RetrievalPath {
    /// Required because `#[non_exhaustive]` blocks external
    /// struct-literal construction.
    pub fn with_hops(hops: Vec<PathHop>) -> Self {
        Self { hops }
    }
}