clm-kernel 0.0.24

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
use clm_rust_core::layer2::sync::{
    MCardRecord, MCardSyncEngine, SyncContractError, SyncFrameTransport, SyncOutboxEntry,
    SyncOutboxPort, TransferAttempt, TransferSendResult, TransitionPayload, frame_record,
};
use std::collections::BTreeMap;
use std::sync::Mutex;

const AUTHOR: &str = "did:clm:agent:test";
const HANDLE: &str = "workspace:test.md";

fn fixture() -> (MCardRecord, clm_rust_core::layer2::sync::RecordFrame, TransitionPayload) {
    let content = b"sync-contract-v1-durability-record".to_vec();
    let hash = blake3::hash(&content).to_hex().to_string();
    let record = MCardRecord {
        hash: hash.clone(),
        content,
        g_time: "blake3|2026-10-23T00:00:00.000Z|UTC".to_string(),
    };
    let mut clock = BTreeMap::new();
    clock.insert(AUTHOR.to_string(), 1);
    let transition = TransitionPayload {
        kind: "CREATE".to_string(),
        handle: HANDLE.to_string(),
        to_handle: None,
        from: None,
        to: Some(format!("blake3:{hash}")),
        meta: None,
        source_ref: None,
        branch_ref: None,
        clock,
        author: AUTHOR.to_string(),
    };
    let frame = frame_record(&record);
    (record, frame, transition)
}

struct MemoryOutboxPort {
    entries: Mutex<Vec<SyncOutboxEntry>>,
    fail_save: bool,
}

impl MemoryOutboxPort {
    fn new(entries: Vec<SyncOutboxEntry>, fail_save: bool) -> Self {
        Self { entries: Mutex::new(entries), fail_save }
    }
}

impl SyncOutboxPort for MemoryOutboxPort {
    fn load_outbox(&self) -> Result<Vec<SyncOutboxEntry>, String> {
        Ok(self.entries.lock().unwrap().clone())
    }
    fn save_outbox(&self, entries: &[SyncOutboxEntry]) -> Result<(), String> {
        if self.fail_save {
            return Err("save failed".to_string());
        }
        *self.entries.lock().unwrap() = entries.to_vec();
        Ok(())
    }
}

struct RecordingTransport {
    sent: Mutex<Vec<TransferAttempt>>,
    fail: bool,
}

impl SyncFrameTransport for RecordingTransport {
    fn send_transfer(
        &self,
        attempt: &TransferAttempt,
        _records: &[clm_rust_core::layer2::sync::RecordFrame],
    ) -> Result<TransferSendResult, String> {
        self.sent.lock().unwrap().push(attempt.clone());
        if self.fail {
            return Err("network down".to_string());
        }
        Ok(TransferSendResult { ok: true, committed: true, ..Default::default() })
    }
}

fn attempt(hash: &str, transitions: Vec<TransitionPayload>) -> TransferAttempt {
    TransferAttempt {
        transfer_id: "transfer-1".to_string(),
        delivery_id: "delivery-1".to_string(),
        source_node_id: "node-b".to_string(),
        target_node_id: "node-a".to_string(),
        record_hashes: vec![hash.to_string()],
        transitions,
        attempt_count: 1,
    }
}

#[test]
fn duplicate_enqueue_is_idempotent() {
    let (_, frame, transition) = fixture();
    let mut engine = MCardSyncEngine::new_with_ports(
        "node-a",
        None,
        Some(Box::new(MemoryOutboxPort::new(vec![], false))),
    );
    let first = engine
        .enqueue_transfer("node-b", vec![frame.clone()], vec![transition.clone()], "same")
        .expect("enqueue");
    let second = engine
        .enqueue_transfer("node-b", vec![frame], vec![transition], "same")
        .expect("enqueue");
    assert_eq!(first.delivery_id, second.delivery_id);
    assert_eq!(engine.outbox.len(), 1);
    assert_eq!(engine.transfer_marking.get("p_in_flight"), Some(&1));
}

#[test]
fn failed_save_rolls_back_marking_and_outbox() {
    let (_, frame, transition) = fixture();
    let mut engine = MCardSyncEngine::new_with_ports(
        "node-a",
        None,
        Some(Box::new(MemoryOutboxPort::new(vec![], true))),
    );
    let err: SyncContractError = engine
        .enqueue_transfer("node-b", vec![frame], vec![transition], "same")
        .expect_err("must abort");
    assert_eq!(err.error_code, "storage-aborted");
    assert!(engine.outbox.is_empty());
    assert_eq!(engine.transfer_marking.get("p_in_flight"), Some(&0));
}

#[test]
fn missing_durable_entry_does_not_send() {
    let port = MemoryOutboxPort::new(vec![], false);
    let transport = RecordingTransport { sent: Mutex::new(Vec::new()), fail: false };
    let mut engine = MCardSyncEngine::new_with_ports(
        "node-a",
        Some(Box::new(transport)),
        Some(Box::new(port)),
    );
    // Insert an entry only in memory (bypassing persistence) to simulate divergence.
    let ghost = SyncOutboxEntry {
        transfer_id: "ghost".to_string(),
        delivery_id: "ghost-delivery".to_string(),
        target_node_id: "node-b".to_string(),
        status: "in_flight".to_string(),
        attempt_count: 0,
        records: vec![],
        transitions: vec![],
        last_error: None,
        error_code: None,
        prior_transfer_id: None,
    };
    engine.outbox.insert("ghost-delivery".to_string(), ghost);
    *engine.transfer_marking.entry("p_in_flight".to_string()).or_insert(0) += 1;
    let err = engine.flush_outbox().expect_err("must abort");
    assert_eq!(err.error_code, "storage-aborted");
}

#[test]
fn transport_error_is_transient() {
    let (_, frame, transition) = fixture();
    let mut engine = MCardSyncEngine::new_with_ports(
        "node-a",
        Some(Box::new(RecordingTransport { sent: Mutex::new(Vec::new()), fail: true })),
        Some(Box::new(MemoryOutboxPort::new(vec![], false))),
    );
    let entry = engine
        .enqueue_transfer("node-b", vec![frame], vec![transition], "same")
        .expect("enqueue");
    engine.flush_outbox().expect("flush");
    let updated = engine.outbox.get(&entry.delivery_id).expect("entry");
    assert_eq!(updated.status, "in_flight");
    assert_eq!(updated.error_code.as_deref(), Some("transport-transient"));
    assert_eq!(engine.transfer_marking.get("p_in_flight"), Some(&1));
}

#[test]
fn receive_attempt_rejects_mismatched_hashes() {
    let (_, frame, transition) = fixture();
    let mut engine = MCardSyncEngine::new("node-a");
    let mut bad = attempt(&"0".repeat(64), vec![transition]);
    bad.record_hashes = vec!["0".repeat(64)];
    let outcome = engine.receive_attempt(&bad, &[frame]);
    assert!(!outcome.ok);
    assert!(!outcome.committed);
    assert_eq!(outcome.error_code.as_deref(), Some("declared-mismatch"));
    assert!(engine.records.is_empty());
}

#[test]
fn receive_attempt_rejects_invalid_transition() {
    let (record, frame, mut transition) = fixture();
    let mut engine = MCardSyncEngine::new("node-a");
    transition.from = Some(format!("blake3:{}", record.hash));
    let outcome = engine.receive_attempt(&attempt(&record.hash, vec![transition]), &[frame]);
    assert!(!outcome.ok);
    assert_eq!(outcome.error_code.as_deref(), Some("guard-rejected"));
    assert!(engine.records.is_empty());
}

#[test]
fn receive_attempt_admits_valid_attempt_once() {
    let (record, frame, transition) = fixture();
    let mut engine = MCardSyncEngine::new("node-a");
    let request = attempt(&record.hash, vec![transition]);
    let first = engine.receive_attempt(&request, std::slice::from_ref(&frame));
    assert!(first.ok && first.committed && !first.replayed);
    assert_eq!(engine.records.len(), 1);
    let replay = engine.receive_attempt(&request, &[frame]);
    assert!(replay.ok && replay.committed && replay.replayed);
    assert_eq!(engine.records.len(), 1);
}

#[test]
fn legacy_receive_transfer_remains_compatible() {
    let (_, frame, _) = fixture();
    let mut engine = MCardSyncEngine::new("node-a");
    let replayed = engine.receive_transfer("legacy-transfer", std::slice::from_ref(&frame)).expect("commit");
    assert!(!replayed);
    assert_eq!(engine.records.len(), 1);
    let replayed = engine.receive_transfer("legacy-transfer", &[frame]).expect("replay");
    assert!(replayed);
}