clm-kernel 0.0.23

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
#![allow(unused_imports)]
use crate::layer0::vocabulary::{HANDLE_MCARD};
use super::*;

/// INV-595: lock contention is SQLITE_BUSY or SQLITE_LOCKED by result code, never by message text.
/// (`db` is compiled only with the `native` or `db` feature, so no gate is needed here.)
#[cfg(test)]
pub(crate) fn is_sqlite_lock_error(error: &rusqlite::Error) -> bool {
    use crate::layer0::runtime_contract::{SQLITE_BUSY, SQLITE_LOCKED, SQLITE_PRIMARY_CODE_MASK};
    matches!(error, rusqlite::Error::SqliteFailure(failure, _)
        if [SQLITE_BUSY, SQLITE_LOCKED].contains(&(failure.extended_code & SQLITE_PRIMARY_CODE_MASK)))
}

/// The same predicate for a kernel error that wraps a SQLite failure.
#[cfg(test)]
pub(crate) fn is_clm_lock_error(error: &ClmError) -> bool {
    matches!(error, ClmError::Database(inner) if is_sqlite_lock_error(inner))
}

pub fn handle_register_batch(
    pillar: &str,
    clm_root: &str,
    handle: &str,
    hash_val: &str,
    content: &str,
) -> Result<()> {
    if is_membroker_backend() {
        return Err(ClmError::storage(StorageErrorCode::TransactionFailed, "broker row verification is unsupported"));
    }
    let now = crate::utils::now_iso8601();
    let algorithm = hash_val.split_once(':').map_or(crate::hash::config().active_algorithm, |(algorithm, _)| algorithm);
    let record = crate::layer0::mcard_record::MCardRecord {
        hash: hash_val.to_string(), content: content.as_bytes().to_vec(),
        g_time: crate::layer0::gtime::stamp_g_time(algorithm, None, None, None),
    };
    crate::layer2::record_store::require_verified(&record)?;

    #[cfg(any(feature = "native", feature = "db"))]
    let created_at_opt = {
        if let Ok(writer_arc) = get_writer_connection(pillar, clm_root) {
            let mut conn = writer_arc
                .lock()
                .map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
            let tx = conn.savepoint()?;
            {
                crate::layer2::record_store::insert_record(&tx, &record)?;

                let mut stmt_hist = tx.prepare_cached(
                    "INSERT INTO handle_history (handle, previous_hash, changed_at) \
                     SELECT hr.handle, hr.current_hash, ?1 FROM handle_registry hr \
                     JOIN card c ON c.hash = hr.current_hash \
                     WHERE hr.handle = ?2 AND hr.current_hash != ?3",
                )?;
                stmt_hist.execute(params![now, handle, hash_val])?;

                // ORC-23/27: `created_at` IS NOT A COLUMN. It is the FIRST history row for the
                // handle — which is exactly why the schema removed it. This function SELECTed
                // it and wrote it back, so it failed with "no such column: created_at" the
                // moment the column went. The kind of a fact does not decide where it lives;
                // the architecture does, and this one lives in the history.
                let mut stmt_reg = tx.prepare_cached(
                    "INSERT OR REPLACE INTO handle_registry (handle, current_hash, updated_at) \
                     VALUES (?1, ?2, ?3)",
                )?;
                stmt_reg.execute(params![handle, hash_val, now])?;
            }
            // DERIVED, not stored — the same value the column used to hold.
            let created_at: String = tx
                .query_row(
                    "SELECT MIN(changed_at) FROM handle_history WHERE handle = ?1",
                    params![handle],
                    |row| row.get(0),
                )
                .unwrap_or_else(|_| now.clone());
            tx.commit()?;
            Some(created_at)
        } else {
            None
        }
    };

    #[cfg(not(any(feature = "native", feature = "db")))]
    let created_at_opt: Option<String> = None;

    let _created_at = if let Some(ca) = created_at_opt {
        ca
    } else {
        let mut conn = get_connection(pillar, clm_root)?;
        let tx = conn.savepoint()?;
        {
                crate::layer2::record_store::insert_record(&tx, &record)?;

            let mut stmt_hist = tx.prepare_cached(
                "INSERT INTO handle_history (handle, previous_hash, changed_at) \
                 SELECT hr.handle, hr.current_hash, ?1 FROM handle_registry hr \
                 JOIN card c ON c.hash = hr.current_hash \
                 WHERE hr.handle = ?2 AND hr.current_hash != ?3",
            )?;
            stmt_hist.execute(params![now, handle, hash_val])?;

            // ORC-23/27: three columns. `created_at` is the FIRST history row, not a column.
            let mut stmt_reg = tx.prepare_cached(
                "INSERT OR REPLACE INTO handle_registry (handle, current_hash, updated_at) \
                 VALUES (?1, ?2, ?3)",
            )?;
            stmt_reg.execute(params![handle, hash_val, now])?;
        }
        // DERIVED, not stored — the same value the column used to hold.
        let created_at: String = tx
            .query_row(
                "SELECT MIN(changed_at) FROM handle_history WHERE handle = ?1",
                params![handle],
                |row| row.get(0),
            )
            .unwrap_or_else(|_| now.clone());
        tx.commit()?;
        created_at
    };


    Ok(())
}

pub fn handle_delete_batch(pillar: &str, clm_root: &str, handle: &str) -> Result<()> {
    let now = crate::utils::now_iso8601();

    #[cfg(any(feature = "native", feature = "db"))]
    {
        if let Ok(writer_arc) = get_writer_connection(pillar, clm_root) {
            let mut conn = writer_arc
                .lock()
                .map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
            let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
            {
                let mut stmt_hist = tx.prepare_cached(
                    "INSERT INTO handle_history (handle, previous_hash, changed_at) \
                     SELECT hr.handle, hr.current_hash, ?1 FROM handle_registry hr \
                     JOIN card c ON c.hash = hr.current_hash \
                     WHERE hr.handle = ?2",
                )?;
                stmt_hist.execute(params![now, handle])?;

                let mut stmt_del_hist = tx.prepare_cached("DELETE FROM handle_history WHERE handle = ?1")?;
                stmt_del_hist.execute(params![handle])?;

                let mut stmt_del = tx.prepare_cached("DELETE FROM handle_registry WHERE handle = ?1")?;
                stmt_del.execute(params![handle])?;
            }
            tx.commit()?;
            return Ok(());
        }
    }

    let mut conn = get_connection(pillar, clm_root)?;
    let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
    {
        let mut stmt_hist = tx.prepare_cached(
            "INSERT INTO handle_history (handle, previous_hash, changed_at) \
             SELECT hr.handle, hr.current_hash, ?1 FROM handle_registry hr \
             JOIN card c ON c.hash = hr.current_hash \
             WHERE hr.handle = ?2",
        )?;
        stmt_hist.execute(params![now, handle])?;

        let mut stmt_del_hist = tx.prepare_cached("DELETE FROM handle_history WHERE handle = ?1")?;
        stmt_del_hist.execute(params![handle])?;

        let mut stmt_del = tx.prepare_cached("DELETE FROM handle_registry WHERE handle = ?1")?;
        stmt_del.execute(params![handle])?;
    }
    tx.commit()?;
    Ok(())
}

pub fn resolve_handle_hash(pillar: &str, clm_root: &str, handle: &str) -> Result<Option<String>> {
    #[cfg(any(feature = "native", feature = "db"))]
    {
        if let Ok(reader) = get_reader_connection(pillar, clm_root) {
            return resolve_handle_hash_cached(&reader, handle);
        }
    }
    let conn = get_connection(pillar, clm_root)?;
    resolve_handle_hash_cached(&conn, handle)
}

pub fn resolve_handle_content(
    pillar: &str,
    clm_root: &str,
    handle: &str,
) -> Result<Option<String>> {
    #[cfg(any(feature = "native", feature = "db"))]
    {
        if let Ok(reader) = get_reader_connection(pillar, clm_root) {
            return resolve_handle_content_cached(&reader, handle);
        }
    }
    let conn = get_connection(pillar, clm_root)?;
    resolve_handle_content_cached(&conn, handle)
}

pub fn card_exists(pillar: &str, clm_root: &str, hash: &str) -> Result<bool> {
    #[cfg(any(feature = "native", feature = "db"))]
    {
        if let Ok(reader) = get_reader_connection(pillar, clm_root) {
            return card_exists_cached(&reader, hash);
        }
    }
    let conn = get_connection(pillar, clm_root)?;
    card_exists_cached(&conn, hash)
}

pub fn setter_card_batch(
    pillar: &str,
    clm_root: &str,
    hash: &str,
    content: &str,
    g_time: &str,
) -> Result<()> {
    setter_card_bytes_batch(pillar, clm_root, hash, content.as_bytes(), g_time)
}

pub fn setter_card_bytes_batch(pillar: &str, clm_root: &str, hash: &str, content: &[u8], g_time: &str) -> Result<()> {
    if is_membroker_backend() {
        return Err(ClmError::storage(StorageErrorCode::TransactionFailed, "broker row verification is unsupported"));
    }
    let record = crate::layer0::mcard_record::MCardRecord {
        hash: hash.to_string(), content: content.to_vec(), g_time: g_time.to_string(),
    };
    crate::layer2::record_store::require_verified(&record)?;
    if let Ok(writer_arc) = get_writer_connection(pillar, clm_root) {
        let conn = writer_arc.lock().map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
        crate::layer2::record_store::insert_record(&conn, &record)?;
    } else {
        crate::layer2::record_store::insert_record(&get_connection(pillar, clm_root)?, &record)?;
    }
    Ok(())
}

pub fn emit_exec_mcard(
    operation: &str,
    content_hash: &str,
    extra_yaml: &str,
    a_hash: &str,
    c_hash: &str,
    clm_root: &str,
) -> Result<String> {
    let is_sandbox = TEST_SANDBOX_ACTIVE.with(|active| active.get());
    let zero_fs = is_sandbox || crate::layer0::environment::var(crate::layer0::vocabulary_env::ENV_CLM_ZERO_FS).unwrap_or_default() == "true";
    let data_root = Path::new(clm_root).join("data");
    let mcard_dir = if zero_fs {
        let tmp_dir = crate::layer0::environment::var("TMPDIR").unwrap_or_else(|_| "/tmp".to_string());
        Path::new(&tmp_dir).join("data").join("execution_logs")
    } else {
        data_root.join("execution_logs")
    };

    if !zero_fs {
        let _ = fs::create_dir_all(&mcard_dir);
    }

    let now = chrono::Local::now();
    let g_time = crate::layer0::gtime::stamp_g_time(crate::hash::config().active_algorithm, None, None, None);
    let unix_ts = now.timestamp();

    let short_hash = if content_hash.len() >= 8 {
        &content_hash[0..8]
    } else {
        content_hash
    };
    let mcard_file = mcard_dir.join(format!("exec_{}_{}.yaml", unix_ts, short_hash));

    // Construct MCard content YAML
    let mut mcard_content = format!(
        "{HANDLE_MCARD}\n  g_time: \"{}\"\n  source_content_hash: \"{}\"\n  operation: \"{}\"\n  agent_did: \"{}\"\n",
        g_time, content_hash, operation, crate::layer0::environment::var("ACTIVE_AGENT_DID").unwrap_or_default()
    );

    if !extra_yaml.is_empty() {
        for line in extra_yaml.lines() {
            mcard_content.push_str(&format!("  {}\n", line));
        }
    }

    if !a_hash.is_empty() || !c_hash.is_empty() {
        mcard_content.push_str("  source:\n");
        if !a_hash.is_empty() {
            mcard_content.push_str(&format!("    a_hash: \"{}\"\n", a_hash));
        }
        if !c_hash.is_empty() {
            mcard_content.push_str(&format!("    c_hash: \"{}\"\n", c_hash));
        }
        mcard_content.push_str(&format!("    operation: \"{}\"\n", operation));
        
        if let Ok(runtime_facts) = crate::layer0::environment::var(crate::layer0::vocabulary_env::ENV_CLM_RUNTIME_FACTS)
            && !runtime_facts.is_empty() {
                mcard_content.push_str("    runtime_facts:\n");
                for line in runtime_facts.lines() {
                    mcard_content.push_str(&format!("      {}\n", line));
                }
            }
    } else {
        if let Ok(runtime_facts) = crate::layer0::environment::var(crate::layer0::vocabulary_env::ENV_CLM_RUNTIME_FACTS)
            && !runtime_facts.is_empty() {
                mcard_content.push_str("  runtime_facts:\n");
                for line in runtime_facts.lines() {
                    mcard_content.push_str(&format!("    {}\n", line));
                }
            }
    }

    if !zero_fs {
        fs::write(&mcard_file, &mcard_content)?;
    }

    let row_hash = crate::hash::raw_hash_bytes_for(crate::hash::config().active_algorithm, mcard_content.as_bytes())
        .map_err(|error| ClmError::storage(StorageErrorCode::CorruptedContent, error))?;
    setter_card_batch(crate::layer0::runtime_contract::TriDbPillar::ExecutionLog.canonical_name(),
        clm_root, &row_hash, &mcard_content, &g_time)?;

    Ok(mcard_file.to_string_lossy().to_string())
}

pub fn get_card_content(pillar: &str, clm_root: &str, hash: &str) -> Result<Option<String>> {
    #[cfg(any(feature = "native", feature = "db"))]
    {
        if let Ok(reader) = get_reader_connection(pillar, clm_root) {
            return get_card_cached(&reader, hash);
        }
    }
    let conn = get_connection(pillar, clm_root)?;
    get_card_cached(&conn, hash)
}

pub fn backup_db(pillar: &str, clm_root: &str) -> Result<Connection> {
    let src = get_connection(pillar, clm_root)?;
    let mut dst = Connection::open_in_memory()?;
    {
        let backup = rusqlite::backup::Backup::new(&src, &mut dst)?;
        backup.run_to_completion(10_000, std::time::Duration::ZERO, None)?;
    }
    crate::layer2::cas_retention::get_all_working_records(&dst)?;
    crate::layer2::record_sqlite_guard::install(&dst)?;
    Ok(dst)
}

pub fn restore_db(pillar: &str, clm_root: &str, backup_conn: &Connection) -> Result<()> {
    let mut snapshot = Connection::open_in_memory()?;
    {
        let backup = rusqlite::backup::Backup::new(backup_conn, &mut snapshot)?;
        backup.run_to_completion(10_000, std::time::Duration::ZERO, None)?;
    }
    crate::layer2::cas_retention::get_all_working_records(&snapshot)?;
    let mut dst = get_connection(pillar, clm_root)?;
    {
        let backup = rusqlite::backup::Backup::new(&snapshot, &mut dst)?;
        backup.run_to_completion(10_000, std::time::Duration::ZERO, None)?;
    }
    Ok(())
}

/// Offloads synchronous blocking database operations from Tokio worker threads
/// to Tokio's dedicated thread pool, protecting the Satori event loop from starvation.
#[cfg(any(feature = "native", all(feature = "db", feature = "async")))]
pub async fn query_db_async<F, R>(f: F) -> Result<R>
where
    F: FnOnce() -> Result<R> + Send + 'static,
    R: Send + 'static,
{
    tokio::task::spawn_blocking(f)
        .await
        .map_err(|join_err| ClmError::Storage(crate::error::StorageErrorCode::QueryFailed, format!("Tokio worker join error: {}", join_err)))?
}


#[cfg(test)]
mod lock_error_tests {
    use super::{is_clm_lock_error, is_sqlite_lock_error};
    use crate::error::ClmError;

    #[test]
    fn real_write_lock_contention_is_a_lock_error_by_code() {
        let file = tempfile::NamedTempFile::new().unwrap();
        let holder = rusqlite::Connection::open(file.path()).unwrap();
        holder.execute_batch("BEGIN IMMEDIATE;").unwrap();
        let contender = rusqlite::Connection::open(file.path()).unwrap();
        contender.busy_timeout(std::time::Duration::ZERO).unwrap();
        let error = contender.execute_batch("BEGIN IMMEDIATE;").unwrap_err();
        assert!(is_sqlite_lock_error(&error), "{error:?}");
        assert!(is_clm_lock_error(&ClmError::Database(error)));
    }

    #[test]
    fn other_failures_are_not_lock_errors_whatever_they_say() {
        let conn = rusqlite::Connection::open_in_memory().unwrap();
        let error = conn.execute_batch("SELECT * FROM locked;").unwrap_err();
        assert!(!is_sqlite_lock_error(&error), "{error:?}");
    }
}