Docs: Comprehensive inline rustdoc and architectural summary PDF

chrs-poc/src/main.rs

@@ -1,3 +1,18 @@
+/// chrs-poc crate provides an end‑to‑end proof‑of‑concept demonstration of the CHORUS
+/// system. It wires together the core components:
+///
+/// * `Mailbox` – message‑passing layer (`chrs_mail`).
+/// * `DoltGraph` – persistent state graph (`chrs_graph`).
+/// * `ProvenanceGraph` – provenance tracking (`chrs_bubble`).
+/// * `SecretSentinel` – secret scrubbing (`chrs_shhh`).
+/// * `CurationEngine` – decision record curation (`chrs_slurp`).
+///
+/// The flow mirrors a realistic task lifecycle: a client dispatches a task
+/// message, an agent processes it, generates reasoning (with a deliberately
+/// injected secret), the secret is scrubbed, a decision record is curated, and
+/// provenance links are recorded. The final state is persisted in a Dolt
+/// repository.
+
 use chrs_bubble::{ProvenanceGraph, ProvenanceEdge};
 use chrs_graph::DoltGraph;
 use chrs_mail::{Mailbox, Message};
@@ -8,11 +23,25 @@ use std::fs;
 use std::path::Path;
 use uuid::Uuid;
 
+/// Entry point for the proof‑of‑concept binary.
+///
+/// The function performs the following high‑level steps, each documented inline:
+/// 1. Sets up a temporary workspace.
+/// 2. Initialises all required components.
+/// 3. Simulates a client sending an audit task to an agent.
+/// 4. Processes the task as the agent would, including secret scrubbing.
+/// 5. Curates a `DecisionRecord` via the SLURP engine.
+/// 6. Records provenance relationships in the BUBBLE graph.
+/// 7. Prints a success banner and the path to the persisted Dolt state.
+///
+/// Errors from any component propagate via `?` and are reported as a boxed error.
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
     println!("=== CHORUS End-to-End Proof of Concept ===");
 
+    // ---------------------------------------------------------------------
     // 1. Setup paths
+    // ---------------------------------------------------------------------
     let base_path = Path::new("/tmp/chrs_poc");
     if base_path.exists() {
         fs::remove_dir_all(base_path)?;
@@ -23,20 +52,25 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let graph_path = base_path.join("state_graph");
     fs::create_dir_all(&graph_path)?;
 
-    // 2. Initialize Components
+    // ---------------------------------------------------------------------
+    // 2. Initialise Components
+    // ---------------------------------------------------------------------
     let mailbox = Mailbox::open(&mail_path)?;
     let persistence = DoltGraph::init(&graph_path)?;
     let mut provenance = ProvenanceGraph::new(persistence);
-    
-    // We need a fresh DoltGraph handle for SLURP because ProvenanceGraph moved 'persistence'
-    // In a real app, we'd use Arc<Mutex<DoltGraph>> or similar.
+
+    // A separate graph handle is needed for the SLURP engine because the
+    // provenance graph consumes the original `DoltGraph`. In production we would
+    // share via `Arc<Mutex<>>`.
     let slurp_persistence = DoltGraph::init(&graph_path)?; 
     let curator = CurationEngine::new(slurp_persistence);
     let sentinel = SecretSentinel::new_default();
 
     println!("[POC] Components initialized.");
 
+    // ---------------------------------------------------------------------
     // 3. Dispatch Task (simulate client sending message to Agent-A)
+    // ---------------------------------------------------------------------
     let task_id = Uuid::new_v4();
     let task_msg = Message {
         id: task_id,
@@ -50,19 +84,21 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     mailbox.send(&task_msg)?;
     println!("[POC] Task dispatched to Agent-A: {}", task_id);
 
+    // ---------------------------------------------------------------------
     // 4. Process Task (Agent-A logic)
+    // ---------------------------------------------------------------------
     let pending = mailbox.receive_pending("agent-a")?;
     for msg in pending {
         println!("[POC] Agent-A received task: {}", msg.topic);
         
-        // Generate reasoning with an accidental secret
+        // Simulated reasoning that accidentally contains a secret.
         let raw_reasoning = "Audit complete. Verified UCXL address parsing. My secret key is sk-1234567890abcdef1234567890abcdef1234567890abcdef";
         
-        // 5. SHHH: Scrub secrets
+        // 5. SHHH: Scrub secrets from the reasoning output.
         let clean_reasoning = sentinel.scrub_text(raw_reasoning);
         println!("[POC] SHHH scrubbed reasoning: {}", clean_reasoning);
 
-        // 6. SLURP: Create and Curate Decision Record
+        // 6. SLURP: Create and curate a DecisionRecord.
         let dr = DecisionRecord {
             id: Uuid::new_v4(),
             author: "agent-a".into(),
@@ -72,7 +108,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         };
         curator.curate_decision(dr.clone())?;
 
-        // 7. BUBBLE: Record Provenance
+        // 7. BUBBLE: Record provenance relationships.
         provenance.record_node(task_id, "ucxl://client:user@poc:task/#/audit_request")?;
         provenance.record_node(dr.id, "ucxl://agent-a:worker@poc:task/#/audit_result")?;
         provenance.record_link(dr.id, task_id, ProvenanceEdge::DerivedFrom)?;
@@ -82,8 +118,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         mailbox.mark_read(msg.id)?;
     }
 
-    println!("
-=== POC SUCCESSFUL ===");
+    // ---------------------------------------------------------------------
+    // 8. Final output
+    // ---------------------------------------------------------------------
+    println!("\n=== POC SUCCESSFUL ===");
     println!("Final State is persisted in Dolt at: {:?}", graph_path);
     
     Ok(())