clm-kernel 0.0.21

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! PyO3 Native Acceleration Bindings for CLM.
//!
//! Provides in-memory zero-copy Rust acceleration for hashing, CRDT state merge,
//! CDC boundary scanning, and Cordis CPN-VM evaluation with GIL-release guards.

#![allow(clippy::useless_conversion)]
#![allow(unsafe_op_in_unsafe_fn)]

use pyo3::prelude::*;
use pyo3::exceptions::{PyIOError, PyRuntimeError, PyValueError};
use crate::error::ClmError;

/// Maps a native Rust `ClmError` to a structured Python exception in `clm.layer0.exceptions`.
#[allow(dead_code)]
pub fn map_clm_error(py: Python<'_>, err: &ClmError) -> PyErr {
    if let Ok(exc_mod) = py.import_bound("clm.layer0.exceptions") {
        let (exc_name, msg) = match err {
            ClmError::Storage(_, msg) => ("DatabaseError", msg.clone()),
            ClmError::Evaluator(_, msg) | ClmError::Evaluation(msg) => ("ExecutionError", msg.clone()),
            ClmError::Auth(_, msg) => ("GatewayError", msg.clone()),
            ClmError::Manifest(_, msg) => ("TypeValidationError", msg.clone()),
            ClmError::Io(io_err) => return PyIOError::new_err(io_err.to_string()),
            _ => ("CLMError", err.to_string()),
        };

        if let Ok(exc_cls) = exc_mod.getattr(exc_name)
            && let Ok(inst) = exc_cls.call1((msg,)) {
                return PyErr::from_value_bound(inst);
            }
    }
    PyRuntimeError::new_err(err.to_string())
}

#[inline]
fn fast_active_hash(data: &[u8]) -> String {
    if crate::hash::config().active_algorithm == crate::layer0::vocabulary::HASH_PREFIX_BLAKE3 {
        blake3::hash(data).to_hex().to_string()
    } else {
        crate::hash::raw_hash_bytes(data)
    }
}

/// Compute raw cryptographic hash over byte buffer, releasing the Python GIL for large payloads.
#[pyfunction]
pub fn blake3_hash_bytes(py: Python<'_>, data: &[u8]) -> PyResult<String> {
    if data.len() > 65536 {
        Ok(py.allow_threads(|| fast_active_hash(data)))
    } else {
        Ok(fast_active_hash(data))
    }
}

/// Scan deterministic `clm-cdc-v1` chunk end offsets over a byte slice without GIL contention.
#[pyfunction]
#[pyo3(signature = (data, min_size=64, avg_size=256, max_size=1024))]
pub fn scan_cdc_boundaries(
    py: Python<'_>,
    data: &[u8],
    min_size: usize,
    avg_size: usize,
    max_size: usize,
) -> Vec<usize> {
    py.allow_threads(|| {
        crate::layer2::chunk_manifest::cdc_split_boundaries(data, min_size, avg_size, max_size)
            .into_iter()
            .map(|(offset, length)| offset + length)
            .collect()
    })
}

/// Split `data` via `clm-cdc-v1` and hash each slice with SIMD BLAKE3 in a single GIL-free pass.
#[pyfunction]
#[pyo3(signature = (data, min_size=64, avg_size=256, max_size=1024))]
pub fn chunk_bytes_fast(
    py: Python<'_>,
    data: &[u8],
    min_size: usize,
    avg_size: usize,
    max_size: usize,
) -> Vec<(usize, usize, String)> {
    py.allow_threads(|| {
        crate::layer2::chunk_manifest::cdc_split_boundaries(data, min_size, avg_size, max_size)
            .into_iter()
            .map(|(offset, length)| {
                let digest = blake3::hash(&data[offset..offset + length]).to_hex().to_string();
                (offset, length, digest)
            })
            .collect()
    })
}

/// Compute content hash for a file, releasing the Python GIL during filesystem I/O.
#[pyfunction]
pub fn clm_hash_file(py: Python<'_>, path: &str) -> PyResult<String> {
    py.allow_threads(|| {
        let p = std::path::Path::new(path);
        if !p.exists() {
            return Err(PyIOError::new_err(format!("File not found: {}", path)));
        }
        Ok(crate::fs_utils::compute_content_hash(path))
    })
}

/// Merge two CRDT event logs idempotently and return the updated log JSON.
#[cfg(feature = "crdt")]
#[pyfunction]
pub fn crdt_merge(py: Python<'_>, log_a_json: &str, log_b_json: &str) -> PyResult<String> {
    py.allow_threads(|| {
        let mut log_a: crate::crdt::CrdtLog = serde_json::from_str(log_a_json)
            .map_err(|e| PyValueError::new_err(format!("Invalid log_a JSON: {}", e)))?;
        let log_b: crate::crdt::CrdtLog = serde_json::from_str(log_b_json)
            .map_err(|e| PyValueError::new_err(format!("Invalid log_b JSON: {}", e)))?;

        log_a.merge(&log_b);
        serde_json::to_string(&log_a)
            .map_err(|e| PyRuntimeError::new_err(format!("Serialization failure: {}", e)))
    })
}

/// Helper: evaluate CLM manifest in-memory and return a deterministic JSON evaluation receipt.
pub fn evaluate_manifest_in_memory_json(
    manifest_yaml: &str,
    context_json: Option<&str>,
) -> Result<String, String> {
    let ast = crate::layer0::ClmLoader::load_from_str(manifest_yaml)
        .map_err(|e| format!("Failed to parse CLM manifest: {}", e))?;

    let context_val: Option<serde_json::Value> = match context_json {
        Some(raw) if !raw.trim().is_empty() => {
            Some(serde_json::from_str(raw).map_err(|e| format!("Invalid context JSON: {}", e))?)
        }
        _ => None,
    };

    let content_hash = crate::hash::raw_hash_string(manifest_yaml);
    let receipt = serde_json::json!({
        "status": "evaluated",
        "content_hash": content_hash,
        "version": ast.version.as_deref().unwrap_or("1.0"),
        "chapter": ast.chapter.as_ref().map(|c| serde_json::to_value(c).unwrap_or_default()),
        "preconditions_count": ast.preconditions.len(),
        "postconditions_count": ast.postconditions.len(),
        "context": context_val,
        "evaluated_at": chrono::Utc::now().to_rfc3339(),
    });

    serde_json::to_string(&receipt)
        .map_err(|e| format!("Failed to serialize receipt JSON: {}", e))
}

/// Evaluate a CLM manifest with Cordis context forwarding and GIL release.
#[pyfunction]
#[pyo3(signature = (manifest_yaml, context_json=None))]
pub fn evaluate_manifest_fast(
    py: Python<'_>,
    manifest_yaml: &str,
    context_json: Option<&str>,
) -> PyResult<String> {
    py.allow_threads(|| evaluate_manifest_in_memory_json(manifest_yaml, context_json))
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Parse a CLM chapter YAML string into a canonical JSON AST.
#[pyfunction]
pub fn py_parse_chapter(py: Python<'_>, yaml_str: &str) -> PyResult<String> {
    py.allow_threads(|| {
        let ast = crate::layer0::ClmLoader::load_from_str(yaml_str)
            .map_err(|e| PyValueError::new_err(format!("Failed to parse CLM chapter: {}", e)))?;
        serde_json::to_string(&ast)
            .map_err(|e| PyRuntimeError::new_err(format!("Failed to serialize parsed AST: {}", e)))
    })
}

/// Execute a Petri Net JSON description for up to `max_steps` steps and return execution result JSON.
#[pyfunction]
#[pyo3(signature = (net_json, max_steps=100))]
pub fn py_execute_net(py: Python<'_>, net_json: &str, max_steps: usize) -> PyResult<String> {
    py.allow_threads(|| {
        let net: crate::layer1::types::PetriNet = serde_json::from_str(net_json)
            .map_err(|e| PyValueError::new_err(format!("Invalid PetriNet JSON: {}", e)))?;
        let mut vm = crate::layer1::ColoredPetriVM::new(net);
        let executed_steps = vm.run_to_completion(max_steps);
        let result = serde_json::json!({
            "steps": executed_steps,
            "fire_history": vm.fire_history,
            "marking": vm.marking,
        });
        serde_json::to_string(&result)
            .map_err(|e| PyRuntimeError::new_err(format!("Serialization failure: {}", e)))
    })
}

/// Verify if an incidence matrix has valid P-invariants satisfying x^T * D = 0^T.
#[pyfunction]
pub fn py_verify_invariants(py: Python<'_>, net_json: &str) -> PyResult<bool> {
    py.allow_threads(|| {
        let net: crate::layer1::types::PetriNet = serde_json::from_str(net_json)
            .map_err(|e| PyValueError::new_err(format!("Invalid PetriNet JSON: {}", e)))?;
        let matrix = crate::layer1::IncidenceMatrix::from_net(&net);
        let invariants = matrix.p_invariants();
        for inv in &invariants {
            if !matrix.verify_invariant(inv) {
                return Ok(false);
            }
        }
        Ok(!invariants.is_empty())
    })
}

/// Direct in-process evaluation of a CLM manifest or polyglot action without process forks.
#[pyfunction]
#[pyo3(signature = (clm_root, clm_file, payload=None))]
pub fn evaluate_in_process(
    py: Python<'_>,
    clm_root: &str,
    clm_file: &str,
    payload: Option<&str>,
) -> PyResult<(i32, String)> {
    py.allow_threads(|| {
        let root = std::path::Path::new(clm_root);
        if let Ok((rc, out)) = crate::polyglot::exec_polyglot(clm_file, payload, clm_root) {
            Ok((rc, out))
        } else {
            match crate::evaluator::run_evaluation(root, Some(clm_file), payload, None, true, None) {
                Ok(rc) => Ok((rc, String::new())),
                Err(e) => Ok((1, e)),
            }
        }
    })
}

/// Native Rust TypeInterpreter judgment bridge.
#[pyfunction]
#[pyo3(signature = (data=None, filename=None, ext_hint=None))]
pub fn py_judge_type(
    py: Python<'_>,
    data: Option<&[u8]>,
    filename: Option<&str>,
    ext_hint: Option<&str>,
) -> PyResult<String> {
    py.allow_threads(|| {
        let interpreter = crate::type_interpreter::TypeInterpreter::create_default();
        let judgment = interpreter.judge(data, filename, ext_hint);
        serde_json::to_string(&judgment)
            .map_err(|e| pyo3::exceptions::PyRuntimeError::new_err(format!("Serialization failure: {}", e)))
    })
}

/// Detect MIME type and extension using native Rust TypeInterpreter.
#[pyfunction]
#[pyo3(signature = (data, ext_hint=None))]
pub fn detect_content_type(
    py: Python<'_>,
    data: &[u8],
    ext_hint: Option<&str>,
) -> PyResult<(String, String)> {
    py.allow_threads(|| {
        let interpreter = crate::type_interpreter::TypeInterpreter::create_default();
        Ok(interpreter.detect_content_type(data, ext_hint))
    })
}

/// Check if byte content is binary using native Rust TypeInterpreter.
#[pyfunction]
pub fn is_binary_content(py: Python<'_>, data: &[u8]) -> PyResult<bool> {
    py.allow_threads(|| {
        let interpreter = crate::type_interpreter::TypeInterpreter::create_default();
        Ok(interpreter.is_binary_content(data))
    })
}

/// Native Rust TypedValue canonical JSON serialization and validation bridge.
#[pyfunction]
#[pyo3(signature = (mime, universe, data_json, schema_ref=None, metadata_json=None))]
pub fn py_typed_value_to_json(
    _py: Python<'_>,
    mime: &str,
    universe: &str,
    data_json: &str,
    schema_ref: Option<&str>,
    metadata_json: Option<&str>,
) -> PyResult<String> {
    let data: serde_json::Value = serde_json::from_str(data_json)
        .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("Invalid data JSON: {}", e)))?;

    let metadata: Option<std::collections::BTreeMap<String, serde_json::Value>> = match metadata_json {
        Some(s) => Some(serde_json::from_str(s).map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!("Invalid metadata JSON: {}", e))
        })?),
        None => None,
    };

    let tv = crate::typed_value::TypedValue::new(
        mime,
        universe,
        data,
        schema_ref.map(|s| s.to_string()),
        metadata,
    )
    .map_err(|e| pyo3::exceptions::PyValueError::new_err(e.to_string()))?;

    tv.to_json()
        .map_err(|e| pyo3::exceptions::PyRuntimeError::new_err(e.to_string()))
}

/// PyO3 entry point for the `make build-rust` artifact (`kernel/clm_py_core/clm_rust_core.so` / `.pyd`).
#[pymodule]
pub fn clm_rust_core(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
    register_module(m)
}

/// PyO3 entry point for maturin wheels (`[tool.maturin] module-name = "clm._rust"`).
/// Same library, same functions: `PyInit__rust` must exist or the wheel cannot import.
#[pymodule]
#[pyo3(name = "_rust")]
pub fn clm_rust_wheel(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
    register_module(m)
}

/// The single function list both entry points expose.
fn register_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(blake3_hash_bytes, m)?)?;
    m.add_function(wrap_pyfunction!(scan_cdc_boundaries, m)?)?;
    m.add_function(wrap_pyfunction!(chunk_bytes_fast, m)?)?;
    m.add_function(wrap_pyfunction!(crate::layer4::pyo3_bench::bench_rust_chunking, m)?)?;
    m.add_function(wrap_pyfunction!(crate::layer4::pyo3_bench::bench_rust_lattice_40p_39t, m)?)?;
    m.add_function(wrap_pyfunction!(crate::layer4::pyo3_bench::bench_rust_handles_sqlite, m)?)?;
    m.add_function(wrap_pyfunction!(crate::layer4::pyo3_bench::bench_rust_sync, m)?)?;
    m.add_function(wrap_pyfunction!(clm_hash_file, m)?)?;
    #[cfg(feature = "crdt")]
    m.add_function(wrap_pyfunction!(crdt_merge, m)?)?;
    m.add_function(wrap_pyfunction!(evaluate_manifest_fast, m)?)?;
    m.add_function(wrap_pyfunction!(evaluate_in_process, m)?)?;
    m.add_function(wrap_pyfunction!(py_parse_chapter, m)?)?;
    m.add_function(wrap_pyfunction!(py_execute_net, m)?)?;
    m.add_function(wrap_pyfunction!(py_verify_invariants, m)?)?;
    m.add_function(wrap_pyfunction!(py_judge_type, m)?)?;
    m.add_function(wrap_pyfunction!(detect_content_type, m)?)?;
    m.add_function(wrap_pyfunction!(is_binary_content, m)?)?;
    m.add_function(wrap_pyfunction!(py_typed_value_to_json, m)?)?;
    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
    m.add("HAS_NATIVE_ACCELERATION", true)?;
    Ok(())
}