clm-kernel 0.0.14

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! MCard URI parsing and canonicalization utilities (INV-552).

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum McardUriType {
    Hash,
    Handle,
}

pub type McardUriKind = McardUriType;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ParsedMcardUri {
    pub uri_type: McardUriType,
    pub target: String,
    pub fragment: Option<String>,
    pub original: String,
}

pub type McardUri = ParsedMcardUri;

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TransclusionCycleError {
    pub cycle_path: Vec<String>,
}

impl std::fmt::Display for TransclusionCycleError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Transclusion cycle detected: {}", self.cycle_path.join(" -> "))
    }
}

impl std::error::Error for TransclusionCycleError {}

pub fn canonicalize_mcard_uri(path: &str, context_prefix: &str) -> String {
    let clean = path.trim_start_matches('/');
    let mut prefix = context_prefix.trim_matches('/');
    if prefix == "mcard" {
        prefix = "";
    }
    if let Some(rest) = clean.strip_prefix("mcard:") {
        let rest = rest.trim_start_matches('/');
        if prefix.is_empty() || rest == prefix || rest.starts_with(&format!("{prefix}/")) {
            return format!("mcard:{rest}");
        }
        return format!("mcard:{prefix}/{rest}");
    }
    if prefix.is_empty() {
        format!("mcard:{clean}")
    } else {
        format!("mcard:{prefix}/{clean}")
    }
}

pub fn is_qualified_hash(value: &str) -> bool {
    let Some((algo, hex)) = value.split_once(':') else {
        return false;
    };
    matches!(algo, "blake3" | "sha256" | "sha512" | "sha3-256" | "sha1" | "md5")
        && (32..=128).contains(&hex.len())
        && hex.chars().all(|c| c.is_ascii_hexdigit())
}

pub fn format_mcard_uri(parsed: &ParsedMcardUri) -> String {
    let frag = parsed
        .fragment
        .as_ref()
        .map(|f| format!("#{}", f.trim_start_matches('#')))
        .unwrap_or_default();
    let kind = match parsed.uri_type {
        McardUriType::Hash => "hash",
        McardUriType::Handle => "handle",
    };
    format!("mcard://{kind}/{}{frag}", parsed.target)
}

pub fn parse_mcard_uri(uri: &str) -> std::result::Result<ParsedMcardUri, String> {
    if uri.is_empty() {
        return Err("Invalid MCard URI: expected non-empty string".to_string());
    }
    let (base, fragment) = match uri.split_once('#') {
        Some((base, frag)) => (base, Some(frag.to_string())),
        None => (uri, None),
    };
    if let Some(target) = base.strip_prefix("mcard://hash/") {
        let target = target.trim_end_matches('/');
        if !target.contains(':') {
            return Err(format!("Malformed hash URI: expected '<algorithm>:<hex>', got '{target}'"));
        }
        return Ok(ParsedMcardUri {
            uri_type: McardUriType::Hash,
            target: target.to_string(),
            fragment,
            original: uri.to_string(),
        });
    }
    if let Some(rest) = base.strip_prefix("mcard://handle/") {
        let raw = rest.split('?').next().unwrap_or(rest).trim_end_matches('/');
        return Ok(ParsedMcardUri {
            uri_type: McardUriType::Handle,
            target: canonicalize_mcard_uri(raw, ""),
            fragment,
            original: uri.to_string(),
        });
    }
    if base.starts_with("mcard://receipts/") || base.starts_with("mcard://schemas/") {
        let raw = base.trim_start_matches("mcard://").trim_end_matches('/');
        return Ok(ParsedMcardUri {
            uri_type: McardUriType::Handle,
            target: canonicalize_mcard_uri(raw, ""),
            fragment,
            original: uri.to_string(),
        });
    }
    if let Some(raw) = base.strip_prefix("mcard://") {
        let raw = raw.trim_end_matches('/');
        if is_qualified_hash(raw) {
            return Ok(ParsedMcardUri {
                uri_type: McardUriType::Hash,
                target: raw.to_lowercase(),
                fragment,
                original: uri.to_string(),
            });
        }
        return Ok(ParsedMcardUri {
            uri_type: McardUriType::Handle,
            target: canonicalize_mcard_uri(raw, ""),
            fragment,
            original: uri.to_string(),
        });
    }
    Ok(ParsedMcardUri {
        uri_type: McardUriType::Handle,
        target: canonicalize_mcard_uri(base, ""),
        fragment,
        original: uri.to_string(),
    })
}

pub fn validate_transclusion_chain(
    chain: &[String],
    next_ref: &str,
) -> std::result::Result<(), TransclusionCycleError> {
    let next = next_ref.to_lowercase();
    if chain.iter().any(|ref_| ref_.to_lowercase() == next) {
        let mut cycle_path = chain.to_vec();
        cycle_path.push(next_ref.to_string());
        return Err(TransclusionCycleError { cycle_path });
    }
    Ok(())
}