clm-kernel 0.0.22

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Layer 2: CAS Retention, Anchors, and Eligibility (Sprint 552 / INV-552).
//!
//! Rust counterpart to TypeScript `casRetention.ts` and Python `cas_retention.py`.
//! Implements retention policy evaluation, reachability traversal, and anchor parsing.

use crate::layer0::mcard_record::MCardRecord;
use rusqlite::Connection;
use serde::{Deserialize, Serialize};
use std::collections::{HashMap, HashSet, VecDeque};

/// Retention policy specifying roots and time-to-live threshold.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct RetentionPolicy {
    pub tau_ms: u64,
    #[serde(default)]
    pub roots: Vec<String>,
    #[serde(default)]
    pub declared_roots_only: bool,
}

/// Outcome of retention eligibility evaluation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EligibilityResult {
    pub eligible: Vec<MCardRecord>,
    pub root_set: HashSet<String>,
    pub reachable: HashSet<String>,
    pub unreferenced: HashSet<String>,
}

/// Parsed lineage anchor payload.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AnchorPayload {
    pub kind: String,
    pub archive: String,
    pub pruned: Vec<String>,
    pub count: usize,
    pub predecessor: Option<String>,
    pub actor: String,
    pub reason: String,
    #[serde(default)]
    pub policy: serde_json::Value,
    #[serde(default)]
    pub successors: Vec<(String, String)>,
    #[serde(default)]
    pub derived: bool,
    #[serde(default)]
    pub time_unknown: Vec<String>,
}

/// Parsed lineage genesis payload.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GenesisPayload {
    pub kind: String,
    pub predecessor: Option<String>,
    pub actor: String,
    pub reason: String,
    #[serde(default = "default_algo")]
    pub algorithm: String,
    #[serde(default)]
    pub adopted: bool,
}

fn default_algo() -> String {
    crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3.to_string()
}

/// Parse and validate a lineage-anchor JSON string.
pub fn parse_anchor(json_str: &str) -> std::result::Result<AnchorPayload, String> {
    let payload: AnchorPayload =
        serde_json::from_str(json_str).map_err(|e| format!("Failed to parse anchor: {e}"))?;
    if payload.kind != "lineage-anchor" {
        return Err(format!("Expected kind 'lineage-anchor', got '{}'", payload.kind));
    }
    Ok(payload)
}

/// Parse and validate a lineage-genesis JSON string.
pub fn parse_genesis(json_str: &str) -> std::result::Result<GenesisPayload, String> {
    let payload: GenesisPayload =
        serde_json::from_str(json_str).map_err(|e| format!("Failed to parse genesis: {e}"))?;
    if payload.kind != "lineage-genesis" {
        return Err(format!("Expected kind 'lineage-genesis', got '{}'", payload.kind));
    }
    Ok(payload)
}

/// Extract all active handle hashes and history hashes from handle tables.
pub fn get_declared_roots(conn: &Connection) -> HashSet<String> {
    let mut roots = HashSet::new();

    if let Ok(mut stmt) = conn.prepare("SELECT current_hash FROM handle_registry") {
        if let Ok(rows) = stmt.query_map([], |row| row.get::<_, Option<String>>(0)) {
            for row in rows.flatten().flatten() {
                let h = row.split_once(':').map(|(_, h)| h).unwrap_or(&row);
                roots.insert(h.to_lowercase());
            }
        }
    }

    if let Ok(mut stmt) = conn.prepare("SELECT previous_hash FROM handle_history") {
        if let Ok(rows) = stmt.query_map([], |row| row.get::<_, Option<String>>(0)) {
            for row in rows.flatten().flatten() {
                let h = row.split_once(':').map(|(_, h)| h).unwrap_or(&row);
                roots.insert(h.to_lowercase());
            }
        }
    }

    roots
}

/// Read all card records from the database.
pub fn get_all_working_records(conn: &Connection) -> crate::error::Result<Vec<MCardRecord>> {
    let mut stmt = conn.prepare("SELECT hash FROM card")?;
    let rows = stmt.query_map([], |row| row.get::<_, String>(0))?;
    rows.map(|row| {
        crate::layer2::record_store::read_record(conn, &row?)?.ok_or_else(||
            crate::error::ClmError::storage(crate::error::StorageErrorCode::CorruptedContent, "retention row disappeared"))
    }).collect()
}

fn find_hash_references(val: &serde_json::Value, refs: &mut Vec<String>) {
    match val {
        serde_json::Value::String(s) => {
            if let Some((algo, hex)) = s.split_once(':') {
                if matches!(algo, crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3 | crate::layer0::vocabulary::HASH_ALGORITHM_SHA256 | crate::layer0::vocabulary::HASH_ALGORITHM_SHA512)
                    && (64..=128).contains(&hex.len())
                    && hex.chars().all(|c| c.is_ascii_hexdigit())
                {
                    refs.push(hex.to_lowercase());
                }
            }
        }
        serde_json::Value::Array(arr) => {
            for item in arr {
                find_hash_references(item, refs);
            }
        }
        serde_json::Value::Object(map) => {
            for v in map.values() {
                find_hash_references(v, refs);
            }
        }
        _ => {}
    }
}

fn compute_age_ms(record: &MCardRecord, now_ms: u64) -> Option<u64> {
    if record.g_time.is_empty() {
        return None;
    }
    let parts: Vec<&str> = record.g_time.split('|').collect();
    if parts.len() >= 2 {
        if let Ok(dt) = chrono::DateTime::parse_from_rfc3339(parts[1]) {
            let t_ms = dt.timestamp_millis() as u64;
            return Some(now_ms.saturating_sub(t_ms));
        }
    }
    None
}

/// Determine records eligible for pruning according to retention policy.
pub fn eligible(
    conn: &Connection,
    policy: &RetentionPolicy,
    now_ms: u64,
) -> crate::error::Result<EligibilityResult> {
    let records = get_all_working_records(conn)?;
    let mut root_set = HashSet::new();

    if !policy.declared_roots_only {
        root_set.extend(get_declared_roots(conn));
    }

    for r in &policy.roots {
        let raw = r.split_once(':').map(|(_, h)| h).unwrap_or(r);
        root_set.insert(raw.to_lowercase());
    }

    let record_map: HashMap<String, &MCardRecord> =
        records.iter().map(|r| (r.hash.to_lowercase(), r)).collect();

    let mut reachable = HashSet::new();
    let mut queue: VecDeque<String> = root_set.iter().cloned().collect();

    while let Some(curr) = queue.pop_front() {
        if reachable.contains(&curr) {
            continue;
        }
        reachable.insert(curr.clone());

        if let Some(rec) = record_map.get(&curr) {
            if let Ok(val) = serde_json::from_slice::<serde_json::Value>(&rec.content) {
                let mut refs = Vec::new();
                find_hash_references(&val, &mut refs);
                for ref_h in refs {
                    if !reachable.contains(&ref_h) && record_map.contains_key(&ref_h) {
                        queue.push_back(ref_h);
                    }
                }
            }
        }
    }

    let mut unreferenced = HashSet::new();
    let mut eligible_records = Vec::new();

    for r in records {
        let h = r.hash.to_lowercase();
        if !reachable.contains(&h) {
            unreferenced.insert(h);
            if policy.tau_ms == 0 {
                eligible_records.push(r);
            } else {
                let age = compute_age_ms(&r, now_ms);
                if age.is_none() || age.unwrap_or(0) >= policy.tau_ms {
                    eligible_records.push(r);
                }
            }
        }
    }

    Ok(EligibilityResult {
        eligible: eligible_records,
        root_set,
        reachable,
        unreferenced,
    })
}