clm-kernel 0.0.21

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Layer 3 Data Transport as Place-to-Place `TokenMCard` Mobility (Sprint 511)
//! Canonical Path: kernel/clm_rust_core/src/layer3/petri_comm.rs

use crate::cpn::mcard_token::{PlaceMCard, TokenMCard, TransitionMCard};
use crate::cpn::token_namespace::{FiringReceiptMCard, MCardMarking, MCardTokenNamespace};
use std::collections::BTreeMap;
use crate::cpn::place_type_lattice::PlaceRole;
use crate::layer1::fractal_net_harness::{register_place_specs, PlaceSpec};

/// Type alias for a Layer 3 communication Petri Net Place.
pub type CommPlaceMCard = PlaceMCard;
/// Type alias for a Layer 3 communication Petri Net Transition.
pub type CommTransitionPCard = TransitionMCard;

/// Outcome of a Layer 3 Petri Net token transport transition (`t_comm_move`).
#[derive(Debug, Clone)]
pub struct CommTransferResult {
    /// True if the token arrived at `p_remote_inbox` with hash & sheaf verification.
    pub delivered: bool,
    /// True if a link drop or sheaf failure routed the token to `p_comm_exception`.
    pub trapped_to_exception: bool,
    /// Resulting Petri Net marking after transport.
    pub marking: MCardMarking,
    /// Sealed `FiringReceiptMCard` from the 5-state Cordis `Fiber`.
    pub receipt: FiringReceiptMCard,
}

/// Layer 3 communication Petri Net orchestrating place-to-place `TokenMCard` mobility.
pub struct Layer3CommPetriNet {
    /// Underlying `MCardTokenNamespace` hosting `p_local_outbox`, `p_in_transit`, `p_remote_inbox`, and `p_comm_exception`.
    pub namespace: MCardTokenNamespace,
}

impl Default for Layer3CommPetriNet {
    fn default() -> Self {
        Self::new()
    }
}

impl Layer3CommPetriNet {
    /// Creates a new `Layer3CommPetriNet` with canonical communication places registered.
    pub fn new() -> Self {
        let mut namespace = MCardTokenNamespace::new("layer3_comm");
        // Sprint 533: place table replaces the build-and-register loop.
        let specs = [
            PlaceSpec::new("p_local_outbox", "any", PlaceRole::Intermediate),
            PlaceSpec::new("p_in_transit", "any", PlaceRole::Intermediate),
            PlaceSpec::new("p_remote_inbox", "any", PlaceRole::Intermediate),
            PlaceSpec::new("p_comm_exception", "any", PlaceRole::Intermediate),
        ];
        register_place_specs(&mut namespace, &specs).expect("valid comm places");
        Self { namespace }
    }

    /// Transports `token` from `p_local_outbox` to `p_remote_inbox` (or `p_comm_exception` on drop).
    pub fn transport_token(
        &mut self,
        _marking: &MCardMarking,
        token: &TokenMCard,
        simulate_drop: bool,
    ) -> CommTransferResult {
        let _ = self
            .namespace
            .deposit_token("p_local_outbox", token.clone(), None, None);
        let tid = format!("t_comm_move:{}", token.qualified_hash());
        let transition = TransitionMCard::create(
            &tid,
            vec!["p_local_outbox".to_string()],
            vec!["p_remote_inbox".to_string()],
            &token.color_type,
            &token.color_type,
            Some(BTreeMap::new()),
            "sheaf_meet_and_verify_hash",
            Some(crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3),
            None,
        )
        .expect("transition");
        self.namespace.register_transition(transition);

        let (receipt, verdict) = self
            .namespace
            .fire_in_cordis_fiber(
                &tid,
                None,
                Some("p_comm_exception"),
                None,
                |inputs| {
                    if simulate_drop {
                        return Err("Simulated Reticulum link drop".to_string());
                    }
                    Ok(inputs[0].clone())
                },
                Some(crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3),
            )
            .expect("fiber execution");
        let committed = matches!(verdict, crate::domain::BailVerdict::Pass);
        CommTransferResult {
            delivered: committed,
            trapped_to_exception: !committed,
            marking: self.namespace.marking.clone(),
            receipt,
        }
    }
}