clm-kernel 0.0.6

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Concurrent Coeffect Event Bus & Reactive Scheduler (CRD-03).
//!
//! Normative References:
//! - DoD-CRD-03-01: Zero-polling PENDING fiber state
//! - DoD-CRD-03-02: Reactive awakening (< 500us) upon service registration
//! - DoD-CRD-03-03: Spatial isolation preventing cross-context state leakage
//! - DoD-CRD-03-04: Merkle-DAG cut with verifiable orthogonal state roots
//! - DoD-CRD-03-06: Optional coeffects fallback without blocking activation
//! - DoD-CRD-03-07: Unmounting deactivation (ACTIVE -> UNLOADING -> DISPOSED) and re-arming

use super::context::{Context, Fiber, FiberState};
use dashmap::DashMap;
use sha2::{Digest, Sha256};
use std::any::Any;
use std::collections::HashSet;
use std::sync::Arc;
use std::time::Instant;

#[derive(Clone)]
pub struct CoeffectRequirement {
    pub name: String,
    pub optional: bool,
    pub fallback: Option<Arc<dyn Any + Send + Sync>>,
}

impl CoeffectRequirement {
    pub fn required(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            optional: false,
            fallback: None,
        }
    }

    pub fn optional_with_fallback(
        name: impl Into<String>,
        fallback: Arc<dyn Any + Send + Sync>,
    ) -> Self {
        Self {
            name: name.into(),
            optional: true,
            fallback: Some(fallback),
        }
    }
}

pub struct RegisteredFiberMeta {
    pub spec_id: String,
    pub fiber: Arc<Fiber>,
    pub required: HashSet<String>,
    pub optional: Vec<CoeffectRequirement>,
}

pub struct CoeffectBus {
    pub context: Context,
    fibers: Arc<DashMap<String, RegisteredFiberMeta>>,
    pending_requirements: Arc<DashMap<String, HashSet<String>>>, // service_name -> Set<spec_id>
}

impl CoeffectBus {
    pub fn new(context: Context) -> Self {
        Self {
            context,
            fibers: Arc::new(DashMap::new()),
            pending_requirements: Arc::new(DashMap::new()),
        }
    }

    /// Mounts an ambient service provider into the root context.
    /// Reactively awakens all dormant PENDING fibers waiting on this service.
    /// Returns awakening latency in microseconds.
    pub fn mount_service<T: Send + Sync + 'static>(&self, name: &str, service: Arc<T>) -> f64 {
        let t0 = Instant::now();
        self.context.services.insert(name.to_string(), service.clone());

        for fiber in self.context.fibers.iter() {
            if fiber.required_coeffects.contains(name) {
                fiber.satisfy_coeffect(name);
            }
        }

        // Reactively awaken dormant fibers whose dependencies are now fully satisfied
        if let Some((_, spec_ids)) = self.pending_requirements.remove(name) {
            for spec_id in spec_ids {
                if let Some(entry) = self.fibers.get(&spec_id) {
                    let meta = entry.value();
                    if meta.fiber.get_state() != FiberState::Pending {
                        continue;
                    }

                    // Check if all required services are now available
                    let mut all_satisfied = true;
                    for req in &meta.required {
                        if !self.context.require(req) {
                            all_satisfied = false;
                            break;
                        }
                    }

                    if all_satisfied {
                        // Apply any optional fallbacks if absent
                        for opt in &meta.optional {
                            if !self.context.require(&opt.name) {
                                if let Some(ref fallback) = opt.fallback {
                                    self.context.services.insert(opt.name.clone(), fallback.clone());
                                }
                            }
                        }

                        // Transition PENDING -> LOADING -> ACTIVE
                        let _ = meta.fiber.transition_to(FiberState::Loading);
                        let _ = meta.fiber.transition_to(FiberState::Active);
                    } else {
                        // Still waiting on other services: re-insert under missing
                        for req in &meta.required {
                            if !self.context.require(req) {
                                self.pending_requirements
                                    .entry(req.clone())
                                    .or_default()
                                    .insert(spec_id.clone());
                            }
                        }
                    }
                }
            }
        }

        let elapsed = t0.elapsed();
        elapsed.as_secs_f64() * 1_000_000.0
    }

    /// Unmounts an ambient service provider.
    /// Deactivates dependent fibers ACTIVE -> UNLOADING -> DISPOSED,
    /// unwinds effect disposables, and re-arms a fresh fiber in PENDING.
    pub fn unmount_service(&self, name: &str) -> Vec<Arc<Fiber>> {
        self.context.services.remove(name);

        // Collect matching entries first to avoid DashMap iterator deadlock
        let to_deactivate: Vec<(String, RegisteredFiberMeta)> = self
            .fibers
            .iter()
            .filter(|e| e.value().required.contains(name) && e.value().fiber.get_state() == FiberState::Active)
            .map(|e| {
                let meta = e.value();
                (
                    e.key().clone(),
                    RegisteredFiberMeta {
                        spec_id: meta.spec_id.clone(),
                        fiber: meta.fiber.clone(),
                        required: meta.required.clone(),
                        optional: meta.optional.clone(),
                    },
                )
            })
            .collect();

        let mut disposed = Vec::new();
        for (spec_id, meta) in to_deactivate {
            let _ = meta.fiber.dispose();
            disposed.push(meta.fiber.clone());

            // Re-arm a fresh fiber in PENDING awaiting re-mount
            let fresh_id = format!("{}:rearmed:{}", meta.spec_id, uuid_or_nanos());
            let fresh_fiber = Arc::new(Fiber::new(fresh_id, meta.required.iter().cloned().collect()));

            self.pending_requirements
                .entry(name.to_string())
                .or_default()
                .insert(spec_id.clone());

            let new_meta = RegisteredFiberMeta {
                spec_id: meta.spec_id.clone(),
                fiber: fresh_fiber,
                required: meta.required,
                optional: meta.optional,
            };
            self.fibers.insert(spec_id, new_meta);
        }

        disposed
    }

    /// Registers a fiber with declared coeffects.
    /// If dependencies are missing, enters PENDING without busy waiting (DoD-CRD-03-01).
    pub fn register_fiber(
        &self,
        spec_id: &str,
        requirements: Vec<CoeffectRequirement>,
    ) -> Arc<Fiber> {
        let mut required_set = HashSet::new();
        let mut optional_list = Vec::new();

        for req in requirements {
            if req.optional {
                optional_list.push(req);
            } else {
                required_set.insert(req.name);
            }
        }

        let fiber = Arc::new(Fiber::new(spec_id, required_set.iter().cloned().collect()));
        let meta = RegisteredFiberMeta {
            spec_id: spec_id.to_string(),
            fiber: fiber.clone(),
            required: required_set.clone(),
            optional: optional_list.clone(),
        };
        self.fibers.insert(spec_id.to_string(), meta);

        // Check if all required coeffects are present
        let mut missing = Vec::new();
        for req in &required_set {
            if !self.context.require(req) {
                missing.push(req.clone());
            }
        }

        if !missing.is_empty() {
            // Enter PENDING without CPU polling
            for m in missing {
                self.pending_requirements
                    .entry(m)
                    .or_default()
                    .insert(spec_id.to_string());
            }
            return fiber;
        }

        // All required present! Check optional fallbacks
        for opt in &optional_list {
            if !self.context.require(&opt.name) {
                if let Some(ref fallback) = opt.fallback {
                    self.context.services.insert(opt.name.clone(), fallback.clone());
                }
            }
        }

        // Transition PENDING -> LOADING -> ACTIVE
        let _ = fiber.transition_to(FiberState::Loading);
        let _ = fiber.transition_to(FiberState::Active);

        fiber
    }

    pub fn get_fiber(&self, spec_id: &str) -> Option<Arc<Fiber>> {
        self.fibers.get(spec_id).map(|e| e.fiber.clone())
    }

    /// Computes the content-addressed Merkle-DAG state root of a Context.
    pub fn compute_merkle_state_root(ctx: &Context) -> String {
        let mut hasher = Sha256::new();
        hasher.update(format!("scope:{}", ctx.scope_id).as_bytes());

        let mut keys: Vec<String> = ctx.services.iter().map(|e| e.key().clone()).collect();
        keys.sort();

        for k in keys {
            hasher.update(b"|svc:");
            hasher.update(k.as_bytes());
        }

        hex::encode(hasher.finalize())
    }

    /// Performs an isolated Merkle-DAG cut on a Context.
    /// Excluded branches have zero reference sharing.
    /// Mutable services like SQLite pool are cloned to ensure strict spatial isolation.
    pub fn isolate_cut(&self, ctx: &Context, allowed: &[&str]) -> (Context, String) {
        let child = ctx.isolate(allowed);
        if let Some(pool) = child.get_service::<crate::services::sqlite_pool::InMemorySqlitePool>("sqlite_pool") {
            let cloned = Arc::new(pool.clone_pool());
            child.services.insert("sqlite_pool".to_string(), cloned);
        }
        let state_root = Self::compute_merkle_state_root(&child);
        (child, state_root)
    }
}

fn uuid_or_nanos() -> String {
    use std::time::{SystemTime, UNIX_EPOCH};
    let nanos = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_nanos())
        .unwrap_or(0);
    format!("{:x}", nanos)
}