chrs_slurp/

lib.rs

//! # chrs-slurp
//!
//! **Intelligence Crate** – Provides the *curation* layer for the CHORUS system.
//!
//! The purpose of this crate is to take **Decision Records** generated by autonomous
//! agents, validate them, and persist them into the graph database.  It isolates the
//! validation and storage concerns so that other components (e.g. provenance, security)
//! can work with a clean, audited data model.
//!
//! ## Architectural Rationale
//!
//! * **Separation of concerns** – Agents produce raw decisions; this crate is the
//!   single source of truth for how those decisions are stored.
//! * **Auditability** – By persisting to a Dolt‑backed graph each decision is versioned
//!   and can be replay‑backed, satisfying CHORUS’s requirement for reproducible
//!   reasoning.
//! * **Extensibility** – The `CurationEngine` can be extended with additional validation
//!   steps (e.g. policy checks) without touching the agents themselves.
//!
//! The crate depends on:
//! * `chrs-graph` – a thin wrapper around a Dolt‑backed graph implementation.
//! * `ucxl` – for addressing external knowledge artefacts.
//! * `chrono`, `serde`, `uuid` – standard utilities for timestamps, (de)serialization
//!   and unique identifiers.
//!
//! ---
//!
//! # Public API
//!
//! The public surface consists of three items:
//!
//! * `DecisionRecord` – data structure representing a curated decision.
//! * `SlurpError` – enumeration of possible errors while curating.
//! * `CurationEngine` – the engine that validates and persists `DecisionRecord`s.
//!
//! Each item is documented in‑line below.

use chrono::{DateTime, Utc};
use chrs_graph::{DoltGraph, GraphError};
use serde::{Deserialize, Serialize};
use thiserror::Error;
use ucxl::UCXLAddress;
use uuid::Uuid;

/// A record representing a curated decision within the CHORUS system.
///
/// # What
///
/// This struct captures the essential metadata of a decision made by an
/// autonomous agent, including who authored it, the reasoning behind it, any
/// citations to external knowledge, and a timestamp.
///
/// # Why
///
/// Decision records are persisted in the graph database so that downstream
/// components (e.g., provenance analysis) can reason about the provenance and
/// justification of actions. Storing them as a dedicated table enables
/// reproducibility and auditability across the CHORUS architecture.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct DecisionRecord {
    /// Unique identifier for the decision.
    pub id: Uuid,
    /// Identifier of the agent or human that authored the decision.
    pub author: String,
    /// Free‑form textual reasoning explaining the decision.
    pub reasoning: String,
    /// Serialized UCXL addresses that serve as citations for the decision.
    /// Each entry should be a valid `UCXLAddress` string.
    pub citations: Vec<String>,
    /// The moment the decision was created.
    pub timestamp: DateTime<Utc>,
}

/// Errors that can arise while slurping (curating) a decision record.
///
/// * `Graph` – underlying graph database operation failed.
/// * `Serde` – (de)serialization of the decision data failed.
/// * `ValidationError` – a supplied citation could not be parsed as a
///   `UCXLAddress`.
#[derive(Debug, Error)]
pub enum SlurpError {
    #[error("Graph error: {0}")]
    Graph(#[from] GraphError),
    #[error("Serialization error: {0}")]
    Serde(#[from] serde_json::Error),
    #[error("Validation error: {0}")]
    ValidationError(String),
}

/// Core engine that validates and persists `DecisionRecord`s into the
/// Dolt‑backed graph.
///
/// # Why
///
/// Centralising curation logic ensures a single place for validation and
/// storage semantics, keeping the rest of the codebase agnostic of the graph
/// implementation details.
pub struct CurationEngine {
    graph: DoltGraph,
}

impl CurationEngine {
    /// Creates a new `CurationEngine` bound to the supplied `DoltGraph`.
    ///
    /// The engine holds a reference to the graph for the lifetime of the
    /// instance; callers are responsible for providing a correctly initialised
    /// graph.
    pub fn new(graph: DoltGraph) -> Self {
        Self { graph }
    }

    /// Validates the citations in `dr` and persists the decision into the
    /// graph.
    ///
    /// The method performs three steps:
    /// 1. **Citation validation** – each citation string is parsed into a
    ///    `UCXLAddress`. Invalid citations produce a `ValidationError`.
    /// 2. **Table assurance** – attempts to create the `curated_decisions`
    ///    table if it does not already exist. Errors are ignored because the
    ///    table may already be present.
    /// 3. **Insertion & commit** – the decision is serialised to JSON and
    ///    inserted as a node, then the graph transaction is committed.
    ///
    /// # Errors
    /// Propagates any `GraphError`, `serde_json::Error`, or custom
    /// validation failures.
    pub fn curate_decision(&self, dr: DecisionRecord) -> Result<(), SlurpError> {
        // 1. Validate Citations
        for citation in &dr.citations {
            use std::str::FromStr;
            UCXLAddress::from_str(citation).map_err(|e| {
                SlurpError::ValidationError(format!("Invalid citation {}: {}", citation, e))
            })?;
        }

        // 2. Ensure the table exists; ignore error if it already does.
        let _ = self.graph.create_table(
            "curated_decisions",
            "id VARCHAR(255) PRIMARY KEY, author TEXT, reasoning TEXT, citations TEXT, curated_at TEXT",
        );

        // 3. Serialize the record and insert it.
        let data = serde_json::json!({
            "id": dr.id.to_string(),
            "author": dr.author,
            "reasoning": dr.reasoning,
            "citations": serde_json::to_string(&dr.citations)?,
            "curated_at": dr.timestamp.to_rfc3339(),
        });

        self.graph.insert_node("curated_decisions", data)?;
        self.graph
            .commit(&format!("Curation complete for DR: {}", dr.id))?;
        Ok(())
    }
}

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

    /// Integration test that exercises the full curation flow on a temporary
    /// Dolt graph.
    #[test]
    fn test_curation_flow() {
        let dir = TempDir::new().unwrap();
        let graph = DoltGraph::init(dir.path()).expect("graph init failed");
        let engine = CurationEngine::new(graph);

        let dr = DecisionRecord {
            id: Uuid::new_v4(),
            author: "agent-001".into(),
            reasoning: "Tested the implementation of SLURP.".into(),
            citations: vec!["ucxl://system:watcher@local:filesystem/#/UCXL/src/lib.rs".into()],
            timestamp: Utc::now(),
        };

        engine.curate_decision(dr).expect("curation failed");
    }
}