Decision traces: 15 architectural traces for Hypatia pre-warming

Crawled 007-lang repo and produced structured decision traces capturing:
- Harvard architecture (why, alternatives, evidence from code)
- Branch strategy pattern (pluggable trait, Layer 4 plug-in)
- Trace system design (append-only, monotonicity, hermeneutic context)
- BEAM codegen target (structural isomorphism with OTP)
- Type system Kategoria (10 layers, implementation gaps noted)
- Agent runtime model (single-thread cooperative, signal propagation)
- Grammar design (Pest PEG, zero-ambiguity over brevity)
- Mandatory given clause (telescope always on, parabasis available)
- Linear handles with exchange (Ephapax influence)
- Module organisation (core/cli split, size distribution)
- Agent API design (machine-first JSON interface)
- Five Facets convergence (philosophical grounding)
- Sentinel integrity (supply chain trust chain)
- Token economics (budget as linear resource, Eclexia pricing)
- Data language constraints (addition-only, totality by construction)

Each trace follows the TraceRecord schema: branch_id, branch_options,
given_contexts (with evidence from actual source), chosen, reason,
trace_report (with hesitations and improvement opportunities).

Also includes trace_cache module (user addition).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

crates/oo7-core/src/lib.rs

@@ -25,6 +25,7 @@ pub mod parser;
 #[cfg(test)]
 mod parser_tests;
 pub mod trace;
+pub mod trace_cache;
 pub mod typechecker;
 pub mod verisimdb;
 
@@ -36,4 +37,5 @@ pub use eval::{AgentInstance, BranchStrategy, Env, Evaluator, PredicateFirstStra
 pub use parser::{parse_program, ParseError};
 pub use trace::{DecisionTrace, TraceRecord};
 pub use typechecker::{check_program, Type, TypeError};
+pub use trace_cache::{CacheStats, CachedDecision, TraceCache};
 pub use verisimdb::{resolve_program_refs, resolve_ref, RefResolutionResult, ResolvedRef};

crates/oo7-core/src/trace_cache.rs

@@ -0,0 +1,370 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+//
+// 007 Agent Meta-Language — Three-Tier Trace Cache
+//
+// Three tiers:
+//   HOT:  In-process HashMap — microsecond lookup for `cached` branches
+//   WARM: VeriSimDB HTTP — millisecond lookup for @ref, agent API
+//   COLD: VeriSimDB bulk — batch export for Hypatia training
+//
+// The evaluator hits HOT. The agent API hits WARM. Hypatia hits COLD.
+// Sync: HOT loads from WARM on startup, flushes to WARM on shutdown.
+//
+// Harvard note: traces are DATA (immutable, deterministic to produce).
+// The cache itself is Control (effectful: I/O, mutation). But what it
+// STORES is Data. This is the telescope's filing cabinet.
+
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+use crate::eval::RtValue;
+use crate::verisimdb;
+
+/// A cached decision — the result of a traced branch evaluation.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CachedDecision {
+    /// The branch label (from `traced "label"`)
+    pub label: String,
+    /// Serialised given context (the cache key component)
+    pub given_context: String,
+    /// Which arm was chosen
+    pub chosen_arm: String,
+    /// The result value (serialised)
+    pub result_json: String,
+    /// Timestamp of the decision
+    pub timestamp: String,
+    /// Which agent made this decision
+    pub agent_id: Option<String>,
+    /// Token cost of the original evaluation
+    pub token_cost: Option<i64>,
+}
+
+/// Three-tier trace cache.
+///
+/// HOT tier: in-process HashMap for microsecond branch cache lookups.
+/// WARM/COLD tiers: VeriSimDB (via verisimdb module) for persistence.
+pub struct TraceCache {
+    /// HOT tier — keyed by "label:given_context_hash"
+    hot: HashMap<String, CachedDecision>,
+    /// VeriSimDB base URL for WARM/COLD tiers
+    verisimdb_url: String,
+    /// Whether VeriSimDB is reachable
+    verisimdb_healthy: bool,
+    /// Dirty entries — written to HOT but not yet flushed to WARM
+    dirty: Vec<String>,
+    /// Stats
+    pub hits: u64,
+    pub misses: u64,
+    pub stores: u64,
+}
+
+impl Default for TraceCache {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl TraceCache {
+    /// Create a new trace cache. Does NOT connect to VeriSimDB yet.
+    pub fn new() -> Self {
+        TraceCache {
+            hot: HashMap::new(),
+            verisimdb_url: verisimdb::verisimdb_url(),
+            verisimdb_healthy: false,
+            dirty: Vec::new(),
+            hits: 0,
+            misses: 0,
+            stores: 0,
+        }
+    }
+
+    /// Create a cache key from branch label + serialised given context.
+    pub fn cache_key(label: &str, given_context: &str) -> String {
+        format!("{}:{}", label, given_context)
+    }
+
+    /// HOT tier lookup — microseconds. Used by evaluator for `cached` branches.
+    pub fn get(&mut self, label: &str, given_context: &str) -> Option<&CachedDecision> {
+        let key = Self::cache_key(label, given_context);
+        if let Some(decision) = self.hot.get(&key) {
+            self.hits += 1;
+            Some(decision)
+        } else {
+            self.misses += 1;
+            None
+        }
+    }
+
+    /// Store a decision in HOT tier. Marks as dirty for later WARM flush.
+    pub fn store(&mut self, decision: CachedDecision) {
+        let key = Self::cache_key(&decision.label, &decision.given_context);
+        self.dirty.push(key.clone());
+        self.hot.insert(key, decision);
+        self.stores += 1;
+    }
+
+    /// Store from evaluator's existing cache format (label, chosen_arm, RtValue).
+    pub fn store_from_eval(
+        &mut self,
+        label: &str,
+        given_context: &str,
+        chosen_arm: &str,
+        result: &RtValue,
+    ) {
+        let result_json = serde_json::to_string(result).unwrap_or_else(|_| "null".to_string());
+        let decision = CachedDecision {
+            label: label.to_string(),
+            given_context: given_context.to_string(),
+            chosen_arm: chosen_arm.to_string(),
+            result_json,
+            timestamp: chrono::Utc::now().to_rfc3339(),
+            agent_id: None,
+            token_cost: None,
+        };
+        self.store(decision);
+    }
+
+    /// Load HOT tier from VeriSimDB (WARM tier).
+    /// Called once at evaluator startup to pre-warm the cache.
+    pub fn load_from_verisimdb(&mut self) -> usize {
+        self.verisimdb_healthy = verisimdb::health_check(&self.verisimdb_url);
+        if !self.verisimdb_healthy {
+            return 0;
+        }
+
+        // Query all 007-trace octads from VeriSimDB
+        let url = format!(
+            "{}/api/v1/search/text?q=007-trace",
+            self.verisimdb_url
+        );
+
+        let resp = match ureq::get(&url).call() {
+            Ok(r) => r,
+            Err(_) => return 0,
+        };
+
+        if resp.status() != 200 {
+            return 0;
+        }
+
+        #[derive(Deserialize)]
+        struct TraceItem {
+            name: Option<String>,
+            document: Option<serde_json::Value>,
+        }
+        #[derive(Deserialize)]
+        struct TraceList {
+            items: Option<Vec<TraceItem>>,
+        }
+
+        let list: TraceList = match resp.into_body().read_json() {
+            Ok(l) => l,
+            Err(_) => return 0,
+        };
+
+        let mut loaded = 0;
+        if let Some(items) = list.items {
+            for item in items {
+                if let Some(doc) = item.document {
+                    if let Some(content_str) = doc.get("content").and_then(|c| c.as_str()) {
+                        if let Ok(decision) =
+                            serde_json::from_str::<CachedDecision>(content_str)
+                        {
+                            let key = Self::cache_key(
+                                &decision.label,
+                                &decision.given_context,
+                            );
+                            self.hot.insert(key, decision);
+                            loaded += 1;
+                        }
+                    }
+                }
+            }
+        }
+
+        loaded
+    }
+
+    /// Flush dirty entries from HOT to WARM (VeriSimDB).
+    /// Called periodically or on evaluator shutdown.
+    pub fn flush_to_verisimdb(&mut self) -> usize {
+        if !self.verisimdb_healthy {
+            self.verisimdb_healthy = verisimdb::health_check(&self.verisimdb_url);
+            if !self.verisimdb_healthy {
+                return 0;
+            }
+        }
+
+        let mut flushed = 0;
+        let dirty_keys: Vec<String> = self.dirty.drain(..).collect();
+
+        for key in &dirty_keys {
+            if let Some(decision) = self.hot.get(key) {
+                let trace_json =
+                    serde_json::to_string(decision).unwrap_or_else(|_| "{}".to_string());
+                match verisimdb::store_trace(
+                    &self.verisimdb_url,
+                    &trace_json,
+                    &decision.label,
+                ) {
+                    Ok(_) => flushed += 1,
+                    Err(_) => {
+                        // Re-add to dirty for next flush attempt
+                        self.dirty.push(key.clone());
+                    }
+                }
+            }
+        }
+
+        flushed
+    }
+
+    /// Export all cached decisions as JSONL for Hypatia training (COLD tier).
+    pub fn export_for_training(&self) -> String {
+        self.hot
+            .values()
+            .map(|d| serde_json::to_string(d).unwrap_or_else(|_| "{}".to_string()))
+            .collect::<Vec<_>>()
+            .join("\n")
+    }
+
+    /// Get cache statistics.
+    pub fn stats(&self) -> CacheStats {
+        CacheStats {
+            hot_entries: self.hot.len(),
+            dirty_entries: self.dirty.len(),
+            hits: self.hits,
+            misses: self.misses,
+            stores: self.stores,
+            hit_rate: if self.hits + self.misses > 0 {
+                self.hits as f64 / (self.hits + self.misses) as f64
+            } else {
+                0.0
+            },
+            verisimdb_healthy: self.verisimdb_healthy,
+        }
+    }
+
+    /// Number of entries in HOT tier.
+    pub fn len(&self) -> usize {
+        self.hot.len()
+    }
+
+    /// Whether HOT tier is empty.
+    pub fn is_empty(&self) -> bool {
+        self.hot.is_empty()
+    }
+}
+
+/// Cache statistics for monitoring.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CacheStats {
+    pub hot_entries: usize,
+    pub dirty_entries: usize,
+    pub hits: u64,
+    pub misses: u64,
+    pub stores: u64,
+    pub hit_rate: f64,
+    pub verisimdb_healthy: bool,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn cache_key_format() {
+        let key = TraceCache::cache_key("triage", "priority:5");
+        assert_eq!(key, "triage:priority:5");
+    }
+
+    #[test]
+    fn store_and_get() {
+        let mut cache = TraceCache::new();
+        cache.store(CachedDecision {
+            label: "triage".to_string(),
+            given_context: "priority:5".to_string(),
+            chosen_arm: "urgent".to_string(),
+            result_json: "\"escalated\"".to_string(),
+            timestamp: "2026-03-24T18:00:00Z".to_string(),
+            agent_id: None,
+            token_cost: Some(3),
+        });
+
+        let result = cache.get("triage", "priority:5");
+        assert!(result.is_some());
+        assert_eq!(result.unwrap().chosen_arm, "urgent");
+    }
+
+    #[test]
+    fn cache_miss() {
+        let mut cache = TraceCache::new();
+        let result = cache.get("nonexistent", "context");
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn store_from_eval_format() {
+        let mut cache = TraceCache::new();
+        cache.store_from_eval(
+            "review",
+            "confidence:0.8",
+            "accept",
+            &RtValue::String("approved".to_string()),
+        );
+
+        let result = cache.get("review", "confidence:0.8");
+        assert!(result.is_some());
+        assert_eq!(result.unwrap().chosen_arm, "accept");
+        assert!(result.unwrap().result_json.contains("approved"));
+    }
+
+    #[test]
+    fn stats_tracking() {
+        let mut cache = TraceCache::new();
+        cache.store_from_eval("a", "ctx1", "arm1", &RtValue::Int(1));
+        cache.get("a", "ctx1"); // hit
+        cache.get("a", "ctx2"); // miss
+        cache.get("b", "ctx1"); // miss
+
+        let stats = cache.stats();
+        assert_eq!(stats.stores, 1);
+        assert_eq!(stats.hits, 1);
+        assert_eq!(stats.misses, 2);
+        assert!((stats.hit_rate - 0.333).abs() < 0.01);
+    }
+
+    #[test]
+    fn export_for_training() {
+        let mut cache = TraceCache::new();
+        cache.store_from_eval("a", "ctx1", "arm1", &RtValue::Int(1));
+        cache.store_from_eval("b", "ctx2", "arm2", &RtValue::Int(2));
+
+        let export = cache.export_for_training();
+        let lines: Vec<&str> = export.lines().collect();
+        assert_eq!(lines.len(), 2);
+        assert!(export.contains("arm1"));
+        assert!(export.contains("arm2"));
+    }
+
+    #[test]
+    fn dirty_tracking() {
+        let mut cache = TraceCache::new();
+        cache.store_from_eval("a", "ctx1", "arm1", &RtValue::Int(1));
+        assert_eq!(cache.dirty.len(), 1);
+
+        // Flush to unreachable VeriSimDB — dirty entries should remain
+        let flushed = cache.flush_to_verisimdb();
+        assert_eq!(flushed, 0);
+    }
+
+    #[test]
+    fn load_from_unreachable_verisimdb() {
+        let mut cache = TraceCache::new();
+        // Default URL is localhost:8094 — may or may not be running
+        let loaded = cache.load_from_verisimdb();
+        // Either loads something or 0 — shouldn't panic
+        assert!(loaded == 0 || loaded > 0);
+    }
+}