clm-kernel 0.0.10

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Cross-Runtime SavepointGuard (CRD-04).
//! Canonical Path: kernel/clm_rust_core/src/fiber/savepoint_guard.rs
//!
//! Implements:
//! - DoD-CRD-04-01: Canonical SavepointGuard with begin(), commit(), rollback()
//! - DoD-CRD-04-02: Strict LIFO DisposableList unwinding before SQLite savepoint rollback
//! - DoD-CRD-04-03: Sub-millisecond rollback latency (< 1ms)
//! - DoD-CRD-04-06: Nested savepoint hierarchies

use super::disposable::DisposableList;
#[cfg(any(feature = "native", feature = "db"))]
use crate::types::domain::SavepointToken;
#[cfg(any(feature = "native", feature = "db"))]
use rusqlite::Connection;
use std::fmt;
#[cfg(any(feature = "native", feature = "db"))]
use std::sync::{Arc, Mutex};

/// Operational state of a SavepointGuard matching cross-runtime contract.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SavepointState {
    Idle,
    Active,
    Committed,
    RolledBack,
}

/// A transactional savepoint guard managed by a Cordis Fiber.
pub struct SavepointGuard {
    pub name: String,
    #[cfg(any(feature = "native", feature = "db"))]
    pub token: SavepointToken,
    #[cfg(any(feature = "native", feature = "db"))]
    pub conn: Option<Arc<Mutex<Connection>>>,
    pub disposables: DisposableList,
    pub state: SavepointState,
    pub rollback_duration_nanos: u128,
}

impl fmt::Debug for SavepointGuard {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("SavepointGuard")
            .field("name", &self.name)
            .field("state", &self.state)
            .field("disposables_pending", &self.disposables.len())
            .field("rollback_duration_nanos", &self.rollback_duration_nanos)
            .finish()
    }
}

impl SavepointGuard {
    /// Constructs a SavepointGuard in Idle state without beginning transaction.
    pub fn idle(
        #[cfg(any(feature = "native", feature = "db"))]
        conn: Option<Arc<Mutex<Connection>>>,
        name: impl Into<String>,
    ) -> Result<Self, String> {
        let raw_name = name.into();
        #[cfg(any(feature = "native", feature = "db"))]
        let token = SavepointToken::parse(&raw_name)
            .unwrap_or_else(|_| SavepointToken::generate(&raw_name));
        Ok(Self {
            name: raw_name,
            #[cfg(any(feature = "native", feature = "db"))]
            token,
            #[cfg(any(feature = "native", feature = "db"))]
            conn,
            disposables: DisposableList::new(),
            state: SavepointState::Idle,
            rollback_duration_nanos: 0,
        })
    }

    /// Begins a new SQLite savepoint and returns the active guard.
    #[cfg(any(feature = "native", feature = "db"))]
    pub fn new(conn: Arc<Mutex<Connection>>, name: impl Into<String>) -> Result<Self, String> {
        let mut guard = Self::idle(Some(conn), name)?;
        guard.begin()?;
        Ok(guard)
    }

    /// Begins a new SQLite savepoint using an explicit, validated SavepointToken.
    #[cfg(any(feature = "native", feature = "db"))]
    pub fn with_token(
        conn: Arc<Mutex<Connection>>,
        token: SavepointToken,
    ) -> Result<Self, String> {
        let token_str = token.as_str().to_string();
        let mut guard = Self {
            name: token_str,
            token,
            conn: Some(conn),
            disposables: DisposableList::new(),
            state: SavepointState::Idle,
            rollback_duration_nanos: 0,
        };
        guard.begin()?;
        Ok(guard)
    }

    /// Registers a cleanup closure to be executed upon rollback.
    pub fn add_disposer<F>(&mut self, cleanup: F)
    where
        F: FnOnce() -> Result<(), String> + Send + 'static,
    {
        self.disposables.push(cleanup);
    }

    /// Alias for add_disposer matching Cordis conventions.
    pub fn register<F>(&mut self, cleanup: F)
    where
        F: FnOnce() -> Result<(), String> + Send + 'static,
    {
        self.add_disposer(cleanup);
    }

    /// Begins transactional savepoint boundary.
    pub fn begin(&mut self) -> Result<(), String> {
        if self.state != SavepointState::Idle {
            return Err(format!("SavepointGuard [{}]: cannot begin from state {:?}", self.name, self.state));
        }
        #[cfg(any(feature = "native", feature = "db"))]
        if let Some(ref conn) = self.conn {
            let c = conn.lock().map_err(|e| e.to_string())?;
            c.execute_batch(&format!("SAVEPOINT {};", self.token.as_str()))
                .map_err(|e| format!("Failed to create savepoint {}: {}", self.token.as_str(), e))?;
        }
        self.state = SavepointState::Active;
        Ok(())
    }

    /// Commits the savepoint, releasing it without rolling back.
    /// Does NOT run disposers (they are cleanup for rollback).
    pub fn commit(&mut self) -> Result<(), String> {
        if self.state != SavepointState::Active {
            return Err(format!("SavepointGuard [{}]: cannot commit from state {:?}", self.name, self.state));
        }
        self.state = SavepointState::Committed;
        #[cfg(any(feature = "native", feature = "db"))]
        if let Some(ref conn) = self.conn {
            let c = conn.lock().map_err(|e| e.to_string())?;
            c.execute_batch(&format!("RELEASE SAVEPOINT {};", self.token.as_str()))
                .map_err(|e| format!("Failed to release savepoint {}: {}", self.token.as_str(), e))?;
        }
        Ok(())
    }

    /// Explicitly rolls back the savepoint.
    /// Unwinds all in-memory disposables in strict LIFO order before rolling back SQLite savepoint.
    /// Satisfies DoD-CRD-04-02.
    pub fn rollback(&mut self) -> Result<(), String> {
        if self.state != SavepointState::Active {
            return Err(format!("SavepointGuard [{}]: cannot rollback from state {:?}", self.name, self.state));
        }
        self.state = SavepointState::RolledBack;

        let t0 = std::time::Instant::now();
        // 1. Unwind in-memory disposables in strict LIFO order
        let disposables = std::mem::take(&mut self.disposables);
        let mut errors = Vec::new();
        if let Err(disposer_errs) = disposables.dispose() {
            errors.extend(disposer_errs);
        }

        // 2. Rollback and release the SQLite savepoint
        #[cfg(any(feature = "native", feature = "db"))]
        if let Some(ref conn) = self.conn {
            if let Ok(c) = conn.lock() {
                let res = c.execute_batch(&format!(
                    "ROLLBACK TO SAVEPOINT {}; RELEASE SAVEPOINT {};",
                    self.token.as_str(),
                    self.token.as_str()
                ));
                if let Err(e) = res {
                    errors.push(format!("Failed to rollback savepoint {}: {}", self.token.as_str(), e));
                }
            } else {
                errors.push("Failed to acquire connection lock for rollback".to_string());
            }
        }
        self.rollback_duration_nanos = t0.elapsed().as_nanos();

        if errors.is_empty() {
            Ok(())
        } else {
            Err(errors.join("; "))
        }
    }

    pub fn is_active(&self) -> bool {
        self.state == SavepointState::Active
    }

    pub fn is_committed(&self) -> bool {
        self.state == SavepointState::Committed
    }

    pub fn is_rolled_back(&self) -> bool {
        self.state == SavepointState::RolledBack
    }

    /// Backwards compatibility alias for commit.
    pub fn release(&mut self) -> Result<(), String> {
        self.commit()
    }
}

impl Drop for SavepointGuard {
    fn drop(&mut self) {
        if self.state == SavepointState::Active {
            if let Err(e) = self.rollback() {
                eprintln!("[SavepointGuard] rollback-on-drop failed for '{}': {}", self.name, e);
            }
        }
    }
}

/// Transactional guard across all Tri-Database pillars.
///
/// Note (`INV-492`, `AC-492-03`): Coordinating independent SQLite files in WAL mode
/// provides in-process savepoint rollback across enlisted stores; it is not a
/// cross-file crash-atomic commit protocol.
#[cfg(any(feature = "native", feature = "db"))]
pub struct TriDbSavepointGuard {
    pub clm_root: String,
    pub sp_name: String,
    pub guards: Vec<SavepointGuard>,
    pub disposables: DisposableList,
    pub state: SavepointState,
}

#[cfg(any(feature = "native", feature = "db"))]
impl TriDbSavepointGuard {
    pub fn new(clm_root: &str, sp_name: &str, _is_rust: bool) -> Result<Self, String> {
        Self::with_pillars(clm_root, sp_name, &["content_memory", "agent_identities", "execution_log"])
    }

    pub fn with_pillars(clm_root: &str, sp_name: &str, pillars: &[&str]) -> Result<Self, String> {
        let mut guards = Vec::with_capacity(pillars.len());
        for &pillar in pillars {
            let conn = crate::db::get_writer_connection(pillar, clm_root)
                .map_err(|e| e.to_string())?;
            let token = SavepointToken::generate(&format!("{}_{}", sp_name, pillar));
            let g = SavepointGuard::with_token(conn, token)?;
            guards.push(g);
        }

        Ok(Self {
            clm_root: clm_root.to_string(),
            sp_name: sp_name.to_string(),
            guards,
            disposables: DisposableList::new(),
            state: SavepointState::Active,
        })
    }

    pub fn with_connections(
        sp_name: &str,
        connections: Vec<(&str, Arc<Mutex<Connection>>)>,
    ) -> Result<Self, String> {
        let mut guards = Vec::with_capacity(connections.len());
        for (label, conn) in connections {
            if label.is_empty()
                || !label
                    .chars()
                    .all(|c| c.is_ascii_alphanumeric() || c == '_')
            {
                return Err(format!(
                    "TriDbSavepointGuard [{}]: invalid store label '{}'",
                    sp_name, label
                ));
            }
            let token = SavepointToken::generate(&format!("{}_{}", sp_name, label));
            let g = SavepointGuard::with_token(conn, token)?;
            guards.push(g);
        }

        Ok(Self {
            clm_root: String::new(),
            sp_name: sp_name.to_string(),
            guards,
            disposables: DisposableList::new(),
            state: SavepointState::Active,
        })
    }

    pub fn add_disposer<F>(&mut self, cleanup: F)
    where
        F: FnOnce() -> Result<(), String> + Send + 'static,
    {
        self.disposables.push(cleanup);
    }

    pub fn is_active(&self) -> bool {
        self.state == SavepointState::Active
    }

    pub fn is_committed(&self) -> bool {
        self.state == SavepointState::Committed
    }

    pub fn is_rolled_back(&self) -> bool {
        self.state == SavepointState::RolledBack
    }

    pub fn commit(&mut self) -> Result<(), String> {
        if self.state != SavepointState::Active {
            return Err(format!("TriDbSavepointGuard [{}]: cannot commit from state {:?}", self.sp_name, self.state));
        }
        self.state = SavepointState::Committed;
        for g in &mut self.guards {
            g.commit()?;
        }
        Ok(())
    }

    pub fn rollback(&mut self) -> Result<(), String> {
        if self.state != SavepointState::Active {
            return Err(format!("TriDbSavepointGuard [{}]: cannot rollback from state {:?}", self.sp_name, self.state));
        }
        self.state = SavepointState::RolledBack;

        // 1. Unwind disposables in strict LIFO order
        let disposables = std::mem::take(&mut self.disposables);
        let mut errors = Vec::new();
        if let Err(disposer_errs) = disposables.dispose() {
            errors.extend(disposer_errs);
        }

        // 2. Rollback guards in strict reverse registration order
        for g in self.guards.iter_mut().rev() {
            if g.is_active() {
                if let Err(e) = g.rollback() {
                    errors.push(e);
                }
            }
        }

        if errors.is_empty() {
            Ok(())
        } else {
            Err(errors.join("; "))
        }
    }
}

#[cfg(any(feature = "native", feature = "db"))]
impl Drop for TriDbSavepointGuard {
    fn drop(&mut self) {
        if self.state == SavepointState::Active {
            if let Err(e) = self.rollback() {
                eprintln!("[TriDbSavepointGuard] rollback-on-drop failed for '{}': {}", self.sp_name, e);
            }
        }
    }
}