clm-kernel 0.0.17

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
use crate::layer2::sync::codec::unframe_record;
use crate::layer2::sync::petri::{
    compute_marking_state_hash, evaluate_lifecycle_guard,
    resolve_concurrent_head_winner,
};
pub use crate::layer2::sync::types::{
    SyncContractError, SyncFrameTransport, SyncOutboxPort,
};
pub(crate) use crate::layer2::sync::types::{
    kind_to_lifecycle, normalize_qualified_hash, TERMINAL_ERROR_CODES,
};
use crate::layer2::sync::types::{
    MCardRecord, ReceiveOutcome, RecordFrame, SyncOutboxEntry, TransferAttempt,
    TransitionGateResult, TransitionPayload,
};
use std::collections::{BTreeMap, BTreeSet};

pub struct MCardSyncEngine {
    pub node_id: String,
    pub is_disposed: bool,
    pub records: BTreeMap<String, MCardRecord>,
    pub handle_markings: BTreeMap<String, BTreeMap<String, i64>>,
    pub handle_heads: BTreeMap<String, Option<String>>,
    pub handle_clocks: BTreeMap<String, BTreeMap<String, u64>>,
    pub transitions: Vec<TransitionPayload>,
    pub committed_transfers: BTreeSet<String>,
    pub outbox: BTreeMap<String, SyncOutboxEntry>,
    pub transfer_marking: BTreeMap<String, i64>,
    pub transport: Option<Box<dyn SyncFrameTransport>>,
    pub outbox_port: Option<Box<dyn SyncOutboxPort>>,
}

impl MCardSyncEngine {
    pub fn new(node_id: &str) -> Self {
        Self::new_with_ports(node_id, None, None)
    }

    pub fn new_with_ports(
        node_id: &str,
        transport: Option<Box<dyn SyncFrameTransport>>,
        outbox_port: Option<Box<dyn SyncOutboxPort>>,
    ) -> Self {
        let mut transfer_marking = BTreeMap::new();
        transfer_marking.insert("p_source".to_string(), 0);
        transfer_marking.insert("p_in_flight".to_string(), 0);
        transfer_marking.insert("p_target".to_string(), 0);
        transfer_marking.insert("p_rejected".to_string(), 0);
        let mut engine = Self {
            node_id: node_id.to_string(),
            is_disposed: false,
            records: BTreeMap::new(),
            handle_markings: BTreeMap::new(),
            handle_heads: BTreeMap::new(),
            handle_clocks: BTreeMap::new(),
            transitions: Vec::new(),
            committed_transfers: BTreeSet::new(),
            outbox: BTreeMap::new(),
            transfer_marking,
            transport,
            outbox_port,
        };
        if let Some(port) = engine.outbox_port.as_ref() {
            if let Ok(entries) = port.load_outbox() {
                for entry in entries {
                    let place = match entry.status.as_str() {
                        "queued" => "p_source",
                        "in_flight" => "p_in_flight",
                        "committed" => "p_target",
                        "rejected" => "p_rejected",
                        _ => "p_in_flight",
                    };
                    *engine.transfer_marking.entry(place.to_string()).or_insert(0) += 1;
                    engine.outbox.insert(entry.delivery_id.clone(), entry);
                }
            }
        }
        engine
    }

    pub fn default_lifecycle_marking() -> BTreeMap<String, i64> {
        let mut m = BTreeMap::new();
        m.insert("p_unborn".to_string(), 1);
        m.insert("p_active".to_string(), 0);
        m.insert("p_retired_tombstone".to_string(), 0);
        m.insert("p_conflict_quarantine".to_string(), 0);
        m
    }

    pub(crate) fn persist_outbox(&self) -> Result<(), String> {
        match self.outbox_port.as_ref() {
            Some(port) => {
                let entries: Vec<SyncOutboxEntry> = self.outbox.values().cloned().collect();
                port.save_outbox(&entries)
            }
            None => Ok(()),
        }
    }

    pub fn admit_record_frame(&mut self, frame: &RecordFrame) -> Result<(String, bool), (String, String)> {
        let (rec, q_hash) = unframe_record(frame, "blake3")?;
        let bare = q_hash.split(':').nth(1).unwrap_or("").to_string();
        let replayed = self.records.contains_key(&bare);
        if !replayed {
            self.records.insert(bare, rec);
        }
        Ok((q_hash, replayed))
    }

    pub fn apply_transition(
        &mut self,
        transition_id: &str,
        payload: &TransitionPayload,
        record_frames: &[RecordFrame],
    ) -> TransitionGateResult {
        let current = self
            .handle_markings
            .get(&payload.handle)
            .cloned()
            .unwrap_or_else(Self::default_lifecycle_marking);

        let mut verified = Vec::new();
        for frame in record_frames {
            match unframe_record(frame, "blake3") {
                Ok((rec, q_hash)) => {
                    let bare = q_hash.split(':').nth(1).unwrap_or("").to_string();
                    verified.push((bare, rec));
                }
                Err((err_code, reason)) => {
                    let pre_hash = compute_marking_state_hash(&current);
                    return TransitionGateResult {
                        enabled: false,
                        transition_id: transition_id.to_string(),
                        pre_marking: current.clone(),
                        post_marking: current,
                        pre_state_hash: pre_hash.clone(),
                        post_state_hash: pre_hash,
                        error_code: Some(err_code),
                        reason: Some(reason),
                    };
                }
            }
        }

        let gate = evaluate_lifecycle_guard(&current, transition_id, Some(payload));
        if !gate.enabled {
            return gate;
        }

        for (bare, rec) in verified {
            self.records.insert(bare, rec);
        }
        self.handle_markings
            .insert(payload.handle.clone(), gate.post_marking.clone());
        let prev_clock = self.handle_clocks.get(&payload.handle).cloned().unwrap_or_default();
        let prev_head = self.handle_heads.get(&payload.handle).and_then(|h| h.as_deref());
        let (_, winner, _, merged_clock) = resolve_concurrent_head_winner(
            prev_head,
            payload.to.as_deref(),
            &prev_clock,
            &payload.clock,
        );
        self.handle_heads.insert(
            payload.handle.clone(),
            if payload.kind == "TOMBSTONE" { None } else { winner },
        );
        self.handle_clocks.insert(payload.handle.clone(), merged_clock);
        self.transitions.push(payload.clone());
        gate
    }

    pub fn receive_attempt(
        &mut self,
        attempt: &TransferAttempt,
        records: &[RecordFrame],
    ) -> ReceiveOutcome {
        if self.committed_transfers.contains(&attempt.transfer_id) {
            return ReceiveOutcome { ok: true, committed: true, replayed: true, ..Default::default() };
        }
        let verified = match self.validate_inbound_attempt(attempt, records) {
            Ok(v) => v,
            Err((code, reason)) => {
                return ReceiveOutcome {
                    ok: false,
                    committed: false,
                    replayed: false,
                    error_code: Some(code),
                    reason: Some(reason),
                }
            }
        };
        for (bare, rec, _) in verified {
            self.records.insert(bare, rec);
        }
        self.committed_transfers.insert(attempt.transfer_id.clone());
        ReceiveOutcome { ok: true, committed: true, replayed: false, ..Default::default() }
    }

    /// Legacy inbound API preserved for backward compatibility. Prefer
    /// `receive_attempt` for full declared-hash and transition validation.
    pub fn receive_transfer(
        &mut self,
        transfer_id: &str,
        records: &[RecordFrame],
    ) -> Result<bool, (String, String)> {
        let mut hashes = Vec::with_capacity(records.len());
        for frame in records {
            let (_, q_hash) = unframe_record(frame, "blake3")?;
            hashes.push(q_hash);
        }
        let attempt = TransferAttempt {
            transfer_id: transfer_id.to_string(),
            delivery_id: format!("legacy:{transfer_id}"),
            source_node_id: String::new(),
            target_node_id: self.node_id.clone(),
            record_hashes: hashes,
            transitions: Vec::new(),
            attempt_count: 1,
        };
        let outcome = self.receive_attempt(&attempt, records);
        if outcome.ok {
            Ok(outcome.replayed)
        } else {
            Err((
                outcome.error_code.unwrap_or_else(|| "malformed".to_string()),
                outcome.reason.unwrap_or_else(|| "inbound rejected".to_string()),
            ))
        }
    }

    pub fn dispose(&mut self) {
        self.is_disposed = true;
    }
}

impl Drop for MCardSyncEngine {
    fn drop(&mut self) {
        self.dispose();
    }
}