clm-kernel 0.0.12

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Reticulum Resource Protocol & MCard CAS Streaming for CLM Layer 3 Mesh.
//! Canonical Path: kernel/clm_rust_core/src/mesh/reticulum_resource.rs
//!
//! Implements:
//! - Resource protocol chunk slicing and windowed reassembly
//! - Content-addressed BLAKE3 CAS verification (INV-L3-RET-356-01)
//! - MCard composite DAG injection atomicity (INV-L3-RET-356-02)

use thiserror::Error;

#[derive(Error, Debug, PartialEq, Eq)]
pub enum ReticulumResourceError {
    #[error("Empty chunk list")]
    EmptyChunkList,

    #[error("Incomplete resource transfer: got {got} of {expected} parts")]
    IncompleteTransfer { expected: usize, got: usize },

    #[error("Missing chunk index {0}")]
    MissingChunkIndex(usize),

    #[error("BLAKE3 hash mismatch: expected {expected}, got {actual}")]
    HashMismatch { expected: String, actual: String },

    #[error("MCard injection rejected: composite child {0} not present in CAS")]
    ChildMissingInCas(String),
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResourceChunk {
    pub transfer_id: [u8; 16],
    pub part_index: u16,
    pub total_parts: u16,
    pub data: Vec<u8>,
}

/// Slices arbitrary binary payload into discrete resource chunks.
pub fn slice_into_chunks(payload: &[u8], chunk_size: usize, transfer_id: Option<[u8; 16]>) -> Vec<ResourceChunk> {
    let tid = transfer_id.unwrap_or_else(|| {
        let h = blake3::hash(payload);
        let mut out = [0u8; 16];
        out.copy_from_slice(&h.as_bytes()[..16]);
        out
    });

    let chunk_size = chunk_size.max(1);
    let total_parts = payload.len().div_ceil(chunk_size).max(1) as u16;
    let mut chunks = Vec::with_capacity(total_parts as usize);

    for i in 0..total_parts {
        let start = (i as usize) * chunk_size;
        let end = (start + chunk_size).min(payload.len());
        chunks.push(ResourceChunk {
            transfer_id: tid,
            part_index: i,
            total_parts,
            data: payload[start..end].to_vec(),
        });
    }

    chunks
}

/// Reassembles ordered resource chunks and validates BLAKE3 hash integrity (INV-L3-RET-356-01).
pub fn reassemble_chunks(
    chunks: &[ResourceChunk],
    expected_blake3: &str,
) -> Result<Vec<u8>, ReticulumResourceError> {
    if chunks.is_empty() {
        return Err(ReticulumResourceError::EmptyChunkList);
    }

    let clean_expected = expected_blake3
        .split(':')
        .next_back()
        .unwrap_or(expected_blake3)
        .to_lowercase();

    let mut sorted = chunks.to_vec();
    sorted.sort_by_key(|c| c.part_index);

    let total_parts = sorted[0].total_parts as usize;
    if sorted.len() != total_parts {
        return Err(ReticulumResourceError::IncompleteTransfer {
            expected: total_parts,
            got: sorted.len(),
        });
    }

    let mut out = Vec::new();
    for (idx, chunk) in sorted.iter().enumerate() {
        if chunk.part_index as usize != idx {
            return Err(ReticulumResourceError::MissingChunkIndex(idx));
        }
        out.extend_from_slice(&chunk.data);
    }

    let computed = blake3::hash(&out).to_hex().to_string().to_lowercase();
    if computed != clean_expected {
        return Err(ReticulumResourceError::HashMismatch {
            expected: clean_expected,
            actual: computed,
        });
    }

    Ok(out)
}

/// Enforces MCard injection atomicity on composite DAGs (INV-L3-RET-356-02).
pub fn check_injection_atomicity(
    child_hashes: &[&str],
    existing_cas_hashes: &[String],
) -> Result<(), ReticulumResourceError> {
    for child in child_hashes {
        let clean_child = child.split(':').next_back().unwrap_or(child).to_lowercase();
        let exists = existing_cas_hashes
            .iter()
            .any(|h| h.split(':').next_back().unwrap_or(h).to_lowercase() == clean_child);
        if !exists {
            return Err(ReticulumResourceError::ChildMissingInCas(clean_child));
        }
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_chunk_slice_and_reassemble() {
        let payload = b"Hello, sovereign mesh world! Testing chunk slicing in Rust.";
        let hash = blake3::hash(payload).to_hex().to_string();

        let chunks = slice_into_chunks(payload, 16, None);
        assert!(chunks.len() > 1);

        let reassembled = reassemble_chunks(&chunks, &hash).unwrap();
        assert_eq!(reassembled, payload);

        // Tamper test
        let mut tampered = chunks.clone();
        tampered[0].data[0] ^= 0xff;
        assert!(reassemble_chunks(&tampered, &hash).is_err());
    }

    #[test]
    fn test_injection_atomicity_verification() {
        let child1 = "blake3:aaaa1111222233334444555566667777888899990000aaaabbbbccccddddeeee";
        let child2 = "blake3:bbbb1111222233334444555566667777888899990000aaaabbbbccccddddeeee";

        let cas = vec![child1.to_string()];

        // child2 is missing
        let err = check_injection_atomicity(&[child1, child2], &cas);
        assert!(err.is_err());

        // child2 added
        let cas_complete = vec![child1.to_string(), child2.to_string()];
        assert!(check_injection_atomicity(&[child1, child2], &cas_complete).is_ok());
    }
}