clm-kernel 0.0.18

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Multi-scale FractalMCard and conserved Colored Petri Net knowledge codec (INV-FRAC-01..04).

use std::collections::BTreeMap;
use serde::{Deserialize, Serialize};
use serde_json::Value;

pub const FRACTAL_ORDERS: [&str; 5] = ["token", "fiber", "collection", "unit", "program"];

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct KnowledgeTriadSpec {
    pub abstract_spec: Value,
    pub concrete_impl: Value,
    pub balanced_exp: Value,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FractalInterfaceSpec {
    pub inputs: Vec<String>,
    pub outputs: Vec<String>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct FiberTapeEvent {
    pub from: String,
    pub to: String,
    pub timestamp: i64,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct FiberCard {
    pub order: String,
    pub fiber: String,
    pub terminal: String,
    pub tape: Vec<FiberTapeEvent>,
    pub effects_settled: usize,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub children: Option<Vec<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub triad: Option<KnowledgeTriadSpec>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub interface: Option<FractalInterfaceSpec>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Compression {
    pub handle: String,
    pub hash: String,
    pub content: Vec<u8>,
    pub card: FiberCard,
}

pub type FractalMCard = Compression;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DecodedFractalCard {
    pub handle: String,
    pub hash: String,
    pub order: String,
    pub fiber: String,
    pub terminal: String,
    pub tape: Vec<FiberTapeEvent>,
    pub effects_settled: usize,
    pub children: Vec<String>,
    pub triad: Option<KnowledgeTriadSpec>,
    pub interface: Option<FractalInterfaceSpec>,
    pub payload: Value,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PlaceSpec {
    pub place_id: String,
    pub type_expr: String,
    pub role: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FractalPetriProjection {
    pub order: String,
    pub source_hash: String,
    pub place_specs: Vec<PlaceSpec>,
    pub topology: Value,
    pub p_invariant_weights: (i64, i64, i64),
}

pub fn is_fractal_order(val: &str) -> bool {
    FRACTAL_ORDERS.contains(&val)
}

pub fn hash_of(content: &[u8]) -> String {
    let mut hasher = blake3::Hasher::new();
    hasher.update(content);
    hasher.finalize().to_hex().to_string()
}

pub fn canonicalise(card: &FiberCard) -> Result<Vec<u8>, serde_json::Error> {
    let mut map = BTreeMap::new();
    map.insert("order", Value::String(card.order.clone()));
    map.insert("fiber", Value::String(card.fiber.clone()));
    map.insert("terminal", Value::String(card.terminal.clone()));

    let tape_vals: Vec<Value> = card
        .tape
        .iter()
        .map(|e| {
            let mut em = BTreeMap::new();
            em.insert("from", Value::String(e.from.clone()));
            em.insert("timestamp", Value::Number(serde_json::Number::from(e.timestamp)));
            em.insert("to", Value::String(e.to.clone()));
            Value::Object(em.into_iter().map(|(k, v)| (k.to_string(), v)).collect())
        })
        .collect();
    map.insert("tape", Value::Array(tape_vals));
    map.insert("effectsSettled", Value::Number(serde_json::Number::from(card.effects_settled)));

    if let Some(ref ch) = card.children {
        let mut sorted_ch = ch.clone();
        sorted_ch.sort();
        map.insert(
            "children",
            Value::Array(sorted_ch.into_iter().map(Value::String).collect()),
        );
    }

    if let Some(ref tr) = card.triad {
        let mut tm = BTreeMap::new();
        tm.insert("abstractSpec", tr.abstract_spec.clone());
        tm.insert("concreteImpl", tr.concrete_impl.clone());
        tm.insert("balancedExp", tr.balanced_exp.clone());
        map.insert("triad", Value::Object(tm.into_iter().map(|(k, v)| (k.to_string(), v)).collect()));
    }

    if let Some(ref iface) = card.interface {
        let mut im = BTreeMap::new();
        im.insert("inputs", Value::Array(iface.inputs.iter().cloned().map(Value::String).collect()));
        im.insert("outputs", Value::Array(iface.outputs.iter().cloned().map(Value::String).collect()));
        map.insert("interface", Value::Object(im.into_iter().map(|(k, v)| (k.to_string(), v)).collect()));
    }

    let json_str = serde_json::to_string(&map)?;
    Ok(json_str.into_bytes())
}

pub fn compress_fiber(
    fiber_id: &str,
    terminal: &str,
    tape: Vec<FiberTapeEvent>,
    effects_settled: usize,
    order: Option<&str>,
) -> Result<Compression, String> {
    if terminal != "disposed" {
        return Err(format!(
            "compress_fiber: refusing to compress a Fiber in state \"{}\" — INV-FRAC-02 requires terminal disposed",
            terminal
        ));
    }
    let ord = order.unwrap_or("fiber");
    let card = FiberCard {
        order: ord.to_string(),
        fiber: fiber_id.to_string(),
        terminal: terminal.to_string(),
        tape,
        effects_settled,
        children: None,
        triad: None,
        interface: None,
    };
    let content = canonicalise(&card).map_err(|e| e.to_string())?;
    let hash = hash_of(&content);
    Ok(Compression {
        handle: format!("urn:mcard:execution:{}:{}", ord, fiber_id),
        hash,
        content,
        card,
    })
}

pub fn compress_collection(
    name: &str,
    members: &[Compression],
    order: Option<&str>,
) -> Result<Compression, String> {
    let ord = order.unwrap_or("collection");
    let mut children: Vec<String> = members.iter().map(|m| m.hash.clone()).collect();
    children.sort();

    let mut map = BTreeMap::new();
    map.insert("children", Value::Array(children.iter().cloned().map(Value::String).collect()));
    map.insert("effectsSettled", Value::Number(serde_json::Number::from(members.len())));
    map.insert("fiber", Value::String(name.to_string()));
    map.insert("members", Value::Array(children.iter().cloned().map(Value::String).collect()));
    map.insert("order", Value::String(ord.to_string()));
    map.insert("tape", Value::Array(vec![]));
    map.insert("terminal", Value::String("disposed".to_string()));

    let json_str = serde_json::to_string(&map).map_err(|e| e.to_string())?;
    let content = json_str.into_bytes();
    let hash = hash_of(&content);

    let card = FiberCard {
        order: ord.to_string(),
        fiber: name.to_string(),
        terminal: "disposed".to_string(),
        tape: vec![],
        effects_settled: members.len(),
        children: Some(children),
        triad: None,
        interface: None,
    };

    Ok(Compression {
        handle: format!("urn:mcard:mcard:{}:{}", ord, name),
        hash,
        content,
        card,
    })
}

pub fn encode_knowledge_triad(
    id: &str,
    order: &str,
    triad: KnowledgeTriadSpec,
    interface: Option<FractalInterfaceSpec>,
    children: Option<Vec<Compression>>,
) -> Result<FractalMCard, String> {
    if !is_fractal_order(order) {
        return Err(format!("encode_knowledge_triad: unsupported FractalOrder \"{}\"", order));
    }
    let mut sorted_children = children
        .map(|cs| {
            let mut hashes: Vec<String> = cs.iter().map(|c| c.hash.clone()).collect();
            hashes.sort();
            hashes
        })
        .unwrap_or_default();
    sorted_children.sort();

    let effects_settled = sorted_children.len();
    let card = FiberCard {
        order: order.to_string(),
        fiber: id.to_string(),
        terminal: "disposed".to_string(),
        tape: vec![],
        effects_settled,
        children: Some(sorted_children),
        triad: Some(triad),
        interface,
    };
    let content = canonicalise(&card).map_err(|e| e.to_string())?;
    let hash = hash_of(&content);

    Ok(Compression {
        handle: format!("urn:mcard:knowledge:{}:{}", order, id),
        hash,
        content,
        card,
    })
}

pub fn decode_fractal_card(card: &FractalMCard) -> Result<DecodedFractalCard, String> {
    let actual_hash = hash_of(&card.content);
    if actual_hash != card.hash {
        return Err(format!(
            "decode_fractal_card: BLAKE3 content mismatch (expected {}, computed {})",
            card.hash, actual_hash
        ));
    }
    let parsed: Value = serde_json::from_slice(&card.content).map_err(|e| e.to_string())?;
    let obj = parsed.as_object().ok_or_else(|| "decode_fractal_card: root is not object".to_string())?;

    let order = obj.get("order").and_then(|v| v.as_str()).ok_or_else(|| "missing order".to_string())?;
    if !is_fractal_order(order) {
        return Err(format!("decode_fractal_card: invalid FractalOrder \"{}\"", order));
    }
    let fiber = obj.get("fiber").and_then(|v| v.as_str()).ok_or_else(|| "missing fiber".to_string())?;
    let terminal = obj.get("terminal").and_then(|v| v.as_str()).ok_or_else(|| "missing terminal".to_string())?;
    if terminal != "disposed" {
        return Err("decode_fractal_card: malformed terminal FiberCard payload".to_string());
    }

    let children = if let Some(ch) = obj.get("children").and_then(|v| v.as_array()) {
        ch.iter().filter_map(|v| v.as_str().map(String::from)).collect()
    } else if let Some(m) = obj.get("members").and_then(|v| v.as_array()) {
        m.iter().filter_map(|v| v.as_str().map(String::from)).collect()
    } else {
        vec![]
    };

    let effects_settled = obj
        .get("effectsSettled")
        .and_then(|v| v.as_u64())
        .map(|v| v as usize)
        .unwrap_or(children.len());

    let triad: Option<KnowledgeTriadSpec> = obj.get("triad").and_then(|t| serde_json::from_value(t.clone()).ok());
    let interface: Option<FractalInterfaceSpec> = obj.get("interface").and_then(|i| serde_json::from_value(i.clone()).ok());

    Ok(DecodedFractalCard {
        handle: card.handle.clone(),
        hash: card.hash.clone(),
        order: order.to_string(),
        fiber: fiber.to_string(),
        terminal: terminal.to_string(),
        tape: vec![],
        effects_settled,
        children,
        triad,
        interface,
        payload: parsed,
    })
}

pub fn project_fractal_petri_net(card: &FractalMCard) -> Result<FractalPetriProjection, String> {
    let decoded = decode_fractal_card(card)?;
    let place_specs = vec![
        PlaceSpec { place_id: "p_abstract".to_string(), type_expr: "structured".to_string(), role: "InitialBottom".to_string() },
        PlaceSpec { place_id: "p_concrete".to_string(), type_expr: "structured".to_string(), role: "Intermediate".to_string() },
        PlaceSpec { place_id: "p_verified".to_string(), type_expr: "structured".to_string(), role: "TerminalTop".to_string() },
    ];

    let topology = serde_json::json!({
        "name": format!("fractal_{}_{}", decoded.order, decoded.fiber),
        "places": [
            { "id": "p_abstract", "initialTokens": 1, "initialColor": decoded.hash, "capacity": 1 },
            { "id": "p_concrete", "initialTokens": 0, "capacity": 1 },
            { "id": "p_verified", "initialTokens": 0, "capacity": 1 }
        ],
        "transitions": [
            { "id": "t_realize", "inputs": ["p_abstract"], "outputs": ["p_concrete"] },
            { "id": "t_verify", "inputs": ["p_concrete"], "outputs": ["p_verified"] }
        ],
        "arcs": [
            { "source": "p_abstract", "target": "t_realize", "weight": 1 },
            { "source": "t_realize", "target": "p_concrete", "weight": 1 },
            { "source": "p_concrete", "target": "t_verify", "weight": 1 },
            { "source": "t_verify", "target": "p_verified", "weight": 1 }
        ],
        "assertions": {
            "fireCount": 2,
            "finalMarking": { "p_abstract": 0, "p_concrete": 0, "p_verified": 1 },
            "noetherianInvariants": {
                "pInvariants": [
                    {
                        "expectedConstant": 1,
                        "weights": { "p_abstract": 1, "p_concrete": 1, "p_verified": 1 }
                    }
                ]
            }
        }
    });

    Ok(FractalPetriProjection {
        order: decoded.order,
        source_hash: decoded.hash,
        place_specs,
        topology,
        p_invariant_weights: (1, 1, 1),
    })
}