clm-kernel 0.0.18

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Layer 0: canonical state-transition grammar (Sprint 530).
//!
//! `CHANGE_CALCULUS`, `TransitionPayload` and their validation were defined three
//! times in this crate: in `handle_kind.rs`, in `layer2/sync/types.rs`, and inline
//! in `layer2/sync/codec.rs`. They are Layer 0 primitives, so they live here and the
//! other modules re-export them.

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

/// The closed set of transition kinds (`INV-TAPE-04`). The KIND of a change is card
/// content in the lifecycle sidecar, never a column.
pub const CHANGE_CALCULUS: &[&str] = &[
    "CREATE", "UPDATE", "SEAL", "RELOCATE", "ROTATE", "TOMBSTONE",
    "SEED", "FORK", "PIN", "CONFLICT_BRANCH",
];

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TransitionPayload {
    pub kind: String,
    pub handle: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub to_handle: Option<String>,
    pub from: Option<String>,
    pub to: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub meta: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source_ref: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub branch_ref: Option<String>,
    pub clock: BTreeMap<String, u64>,
    pub author: String,
}

/// A reference is a qualified hash when it is `blake3:` or `sha256:` plus 64 hex digits.
pub fn is_qualified_hash(val: &str) -> bool {
    val.split_once(':')
        .map(|(a, h)| (a == "blake3" || a == "sha256") && h.len() == 64 && h.chars().all(|c| c.is_ascii_hexdigit()))
        .unwrap_or(false)
}

pub fn validate_transition_payload(payload: &TransitionPayload) -> Result<(), String> {
    if !CHANGE_CALCULUS.contains(&payload.kind.as_str()) {
        return Err(format!("Invalid transition kind: {}", payload.kind));
    }
    if payload.handle.is_empty() || payload.author.is_empty() {
        return Err("Transition handle and author must be non-empty".to_string());
    }
    for r in [&payload.from, &payload.to, &payload.meta, &payload.source_ref].into_iter().flatten() {
        if !is_qualified_hash(r) {
            return Err(format!("Reference must be a qualified hash: {r}"));
        }
    }
    if payload.kind == "CREATE" && payload.from.is_some() {
        return Err("CREATE transition must have from=null".to_string());
    }
    if payload.kind == "TOMBSTONE" && payload.to.is_some() {
        return Err("TOMBSTONE transition must have to=null".to_string());
    }
    if payload.kind == "RELOCATE" && payload.to_handle.as_deref().unwrap_or("").is_empty() {
        return Err("RELOCATE transition requires toHandle".to_string());
    }
    if payload.kind == "SEED" {
        if payload.from.is_some() {
            return Err("SEED transition must have from=null".to_string());
        }
        if payload.to.is_none() || payload.source_ref.is_none() {
            return Err("SEED transition requires qualified to and sourceRef".to_string());
        }
    }
    if payload.kind == "FORK" {
        if payload.from.is_none() || payload.to.is_none() {
            return Err("FORK transition requires active from and to hashes".to_string());
        }
        if payload.to_handle.as_deref().unwrap_or("").is_empty() {
            return Err("FORK transition requires toHandle".to_string());
        }
        if payload.source_ref.is_none() {
            return Err("FORK transition requires sourceRef provenance".to_string());
        }
    }
    if payload.kind == "PIN" && (payload.from.is_none() || payload.to.is_none() || payload.from != payload.to) {
        return Err("PIN transition requires active from and to hashes equal to current head".to_string());
    }
    if payload.kind == "CONFLICT_BRANCH" {
        if payload.from.is_none() || payload.to.is_none() {
            return Err("CONFLICT_BRANCH transition requires active from and to hashes".to_string());
        }
        if payload.branch_ref.as_deref().unwrap_or("").is_empty() {
            return Err("CONFLICT_BRANCH transition requires non-empty branchRef".to_string());
        }
    }
    Ok(())
}