clm-kernel 0.0.22

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Carrier Collection interface for MCard operations across runtimes (Sprint 552 / INV-552).
//!
//! Exposes handle, raw-byte, and manifest operations aligned with TypeScript
//! `MCardCollection` and Python `CardCollection`.

use crate::error::Result;
use crate::layer0::mcard_record::MCardRecord;
use crate::layer2::vfs::{DirectoryManifest, MCardFileSystem};
use rusqlite::Connection;
use std::sync::{Arc, Mutex};

/// Carrier collection interface for MCard operations across runtimes (INV-552).
#[derive(Clone)]
pub struct MCardCollection {
    fs: MCardFileSystem,
}

impl MCardCollection {
    /// Create a collection wrapping an existing MCardFileSystem.
    pub fn new(fs: MCardFileSystem) -> Self {
        Self { fs }
    }

    /// Initializes an isolated, in-memory MCardCollection.
    pub fn new_in_memory() -> Result<Self> {
        let fs = MCardFileSystem::new_in_memory()?;
        Ok(Self { fs })
    }

    /// Wraps an existing shared SQLite connection.
    pub fn from_connection(conn: Arc<Mutex<Connection>>) -> Self {
        let fs = MCardFileSystem::new(conn, "");
        Self { fs }
    }

    /// Access the underlying MCardFileSystem.
    pub fn fs(&self) -> &MCardFileSystem {
        &self.fs
    }

    /// Writes raw content bytes into `card` and binds `uri` in `handle_registry` (`INV-510-01`, `INV-510-02`).
    pub fn write_raw_bytes(
        &self,
        uri: &str,
        content: &[u8],
        algorithm: Option<&str>,
    ) -> Result<MCardRecord> {
        self.fs.write_raw_bytes(uri, content, algorithm)
    }

    /// Reads and verifies exact raw bytes bound to `uri` (`INV-510-01`).
    pub fn read_raw_bytes(&self, uri: &str) -> Result<Vec<u8>> {
        self.fs.read_raw_bytes(uri)
    }

    /// Atomic Compare-and-Swap handle binding (`INV-510-03`).
    pub fn bind(&self, uri: &str, new_ref: &str, expected_old_ref: Option<&str>) -> Result<bool> {
        self.fs.bind(uri, new_ref, expected_old_ref)
    }

    /// Writes a `DirectoryManifest` `MCard` to `dir_uri` (`INV-510-04`).
    pub fn write_directory_manifest(
        &self,
        dir_uri: &str,
        manifest: &DirectoryManifest,
    ) -> Result<MCardRecord> {
        self.fs.write_directory_manifest(dir_uri, manifest)
    }

    /// Reads a `DirectoryManifest` `MCard` from `dir_uri` (`INV-510-04`).
    pub fn read_directory_manifest(&self, dir_uri: &str) -> Result<DirectoryManifest> {
        self.fs.read_directory_manifest(dir_uri)
    }
}