claw_core/

engine.rs

//! Main engine entry point for claw-core.
//!
//! [`ClawEngine`] is the primary handle through which callers interact with the
//! embedded SQLite database. It owns the SQLx connection pool, an internal LRU
//! cache for [`MemoryRecord`]s, applies migrations on startup (when
//! `auto_migrate` is enabled), and exposes methods for interacting with the
//! various store modules.

use std::path::Path;
use std::sync::Arc;

use sqlx::SqlitePool;
use tokio::sync::Mutex;
use uuid::Uuid;

use crate::cache::{CacheStats, ClawCache};
use crate::config::ClawConfig;
use crate::error::{ClawError, ClawResult};
use crate::snapshot::{SnapshotManifest, SnapshotMeta, Snapshotter};
use crate::store::memory::{ListOptions, MemoryRecord, MemoryStore, MemoryType};
use crate::store::session_lifecycle::{Session, SessionLifecycleStore};
use crate::store::tool_output::{ToolOutputRecord, ToolOutputStore};

/// Database-level statistics for a [`ClawEngine`] instance.
///
/// Retrieve via [`ClawEngine::db_stats`].
///
/// # Example
///
/// ```rust,no_run
/// # use claw_core::ClawEngine;
/// # async fn example() -> claw_core::ClawResult<()> {
/// # let engine = ClawEngine::open_default().await?;
/// let stats = engine.db_stats().await?;
/// println!("memories: {}", stats.memory_count);
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct DbStats {
    /// Total number of memory records in the database.
    pub memory_count: u64,
    /// Total number of sessions in the database.
    pub session_count: u64,
    /// Total number of tool-output records in the database.
    pub tool_output_count: u64,
}

/// Comprehensive runtime statistics for a [`ClawEngine`] instance.
///
/// Retrieve via [`ClawEngine::stats`].
///
/// # Example
///
/// ```rust,no_run
/// # use claw_core::ClawEngine;
/// # async fn example() -> claw_core::ClawResult<()> {
/// # let engine = ClawEngine::open_default().await?;
/// let s = engine.stats().await?;
/// println!("hit rate (last 1 000 ops): {:.1}%", s.cache_hit_rate * 100.0);
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct ClawStats {
    /// Total number of memory records currently stored.
    pub total_memories: u64,
    /// Cache hit rate over the most recent 1 000 lookup operations (0.0 – 1.0).
    pub cache_hit_rate: f64,
    /// Timestamp of the most recently created snapshot, or `None` if no
    /// snapshot has been taken during this engine session.
    pub last_snapshot_at: Option<chrono::DateTime<chrono::Utc>>,
    /// Size of the main database file in bytes.
    pub db_size_bytes: u64,
    /// Size of the WAL file in bytes (0 if WAL is not enabled or not present).
    pub wal_size_bytes: u64,
}

/// The main entry point for claw-core.
///
/// Construct a [`ClawEngine`] via [`ClawEngine::open`] or
/// [`ClawEngine::open_default`], passing a validated [`ClawConfig`]. The engine
/// holds the underlying SQLx [`SqlitePool`], an internal LRU memory cache, and
/// serves as the root accessor for all store, transaction, and snapshot APIs.
///
/// # Example
///
/// ```rust,no_run
/// use claw_core::{ClawEngine, ClawConfig};
///
/// # async fn example() -> claw_core::ClawResult<()> {
/// let config = ClawConfig::builder()
///     .db_path("/tmp/my_agent.db")
///     .build()?;
/// let engine = ClawEngine::open(config).await?;
/// engine.close().await;
/// # Ok(())
/// # }
/// ```
#[derive(Debug)]
pub struct ClawEngine {
    /// Validated runtime configuration.
    pub(crate) config: ClawConfig,
    /// SQLx connection pool backed by SQLite.
    pub(crate) pool: SqlitePool,
    /// In-memory LRU cache for [`MemoryRecord`]s.
    cache: Arc<Mutex<ClawCache<Uuid, MemoryRecord>>>,
    /// Running cache statistics (includes rolling hit-rate window).
    stats: Arc<Mutex<CacheStats>>,
    /// Timestamp of the last successful snapshot taken during this session.
    last_snapshot_at: Arc<Mutex<Option<chrono::DateTime<chrono::Utc>>>>,
}

impl ClawEngine {
    /// Open (or create) the database at the path specified in `config`.
    ///
    /// When `config.auto_migrate` is `true`, any pending embedded migrations
    /// are applied before the engine is returned.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the pool cannot be created or migrations fail.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::{ClawEngine, ClawConfig};
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// let config = ClawConfig::builder()
    ///     .db_path("/tmp/claw.db")
    ///     .build()?;
    /// let engine = ClawEngine::open(config).await?;
    /// engine.close().await;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn open(config: ClawConfig) -> ClawResult<Self> {
        use sqlx::sqlite::{SqliteConnectOptions, SqliteJournalMode, SqlitePoolOptions};
        use std::str::FromStr;

        let db_url = format!("sqlite:{}", config.db_path.display());

        let journal_mode = match config.journal_mode {
            crate::config::JournalMode::WAL => SqliteJournalMode::Wal,
            crate::config::JournalMode::Delete => SqliteJournalMode::Delete,
            crate::config::JournalMode::Truncate => SqliteJournalMode::Truncate,
        };

        let connect_options = SqliteConnectOptions::from_str(&db_url)
            .map_err(|e| ClawError::Config(format!("invalid database URL: {e}")))?
            .create_if_missing(true)
            .journal_mode(journal_mode);

        let pool = SqlitePoolOptions::new()
            .max_connections(config.max_connections)
            .connect_with(connect_options)
            .await?;

        // When the "encryption" feature is enabled and a key is provided,
        // apply `PRAGMA key` immediately after connecting.  This requires a
        // SQLCipher build of SQLite (not the default bundled libsqlite3).
        #[cfg(feature = "encryption")]
        if let Some(key) = &config.encryption_key {
            let hex: String = key.iter().map(|b| format!("{b:02x}")).collect();
            sqlx::query(&format!("PRAGMA key = \"x'{hex}'\""))
                .execute(&pool)
                .await?;
        }

        // Estimate ~512 bytes per MemoryRecord; minimum 64 entries.
        let cache_cap = ((config.cache_size_mb * 1024 * 1024) / 512).max(64);
        let cache = Arc::new(Mutex::new(ClawCache::new(cache_cap)?));
        let stats = Arc::new(Mutex::new(CacheStats::new()));

        let engine = ClawEngine {
            config,
            pool,
            cache,
            stats,
            last_snapshot_at: Arc::new(Mutex::new(None)),
        };

        if engine.config.auto_migrate {
            engine.migrate().await?;
        }

        Ok(engine)
    }

    /// Open the database using the default [`ClawConfig`].
    ///
    /// The database is created at `$XDG_DATA_HOME/clawdb/claw.db` (or
    /// platform equivalent). All migrations are applied automatically.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the pool cannot be created or migrations fail.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use claw_core::ClawEngine;
    ///
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// let engine = ClawEngine::open_default().await?;
    /// engine.close().await;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn open_default() -> ClawResult<Self> {
        ClawEngine::open(ClawConfig::default()).await
    }

    /// Apply any pending embedded SQL migrations.
    ///
    /// # Errors
    ///
    /// Returns [`ClawError::Migration`] if a migration step fails.
    pub async fn migrate(&self) -> ClawResult<()> {
        crate::schema::migrations::run_migrations(&self.pool).await
    }

    /// Return a reference to the underlying [`SqlitePool`].
    pub fn pool(&self) -> &SqlitePool {
        &self.pool
    }

    /// Return a reference to the engine's [`ClawConfig`].
    pub fn config(&self) -> &ClawConfig {
        &self.config
    }

    /// Close the connection pool, waiting for in-flight queries to complete.
    pub async fn close(self) {
        self.pool.close().await;
    }

    // ── Memory API ────────────────────────────────────────────────────────────

    /// Insert a new [`MemoryRecord`] into the database.
    ///
    /// The record is also inserted into the in-memory LRU cache.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the SQL execution fails.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::{ClawEngine, MemoryRecord, MemoryType};
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let record = MemoryRecord::new("hello world", MemoryType::Semantic, vec![], None);
    /// let id = engine.insert_memory(&record).await?;
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip(self, record), fields(memory_id = %record.id))]
    pub async fn insert_memory(&self, record: &MemoryRecord) -> ClawResult<Uuid> {
        MemoryStore::new(&self.pool).insert(record).await?;
        let mut cache = self.cache.lock().await;
        let mut stats = self.stats.lock().await;
        cache.insert(record.id, record.clone());
        stats.insert_count += 1;
        Ok(record.id)
    }

    /// Retrieve a [`MemoryRecord`] by its UUID.
    ///
    /// Results are served from the in-memory LRU cache when available.
    ///
    /// # Errors
    ///
    /// Returns [`ClawError::NotFound`] if no record with the given `id` exists.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::{ClawEngine, MemoryRecord, MemoryType};
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let record = MemoryRecord::new("hello", MemoryType::Semantic, vec![], None);
    /// let id = engine.insert_memory(&record).await?;
    /// let fetched = engine.get_memory(id).await?;
    /// assert_eq!(fetched.content, "hello");
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip(self), fields(memory_id = %id))]
    pub async fn get_memory(&self, id: Uuid) -> ClawResult<MemoryRecord> {
        {
            let mut cache = self.cache.lock().await;
            let mut stats = self.stats.lock().await;
            if let Some(record) = cache.get(&id) {
                stats.record_hit();
                return Ok(record.clone());
            }
            stats.record_miss();
        }

        let record = MemoryStore::new(&self.pool).get(id).await?;
        let mut cache = self.cache.lock().await;
        cache.insert(record.id, record.clone());
        Ok(record)
    }

    /// Update the content of an existing [`MemoryRecord`].
    ///
    /// The `updated_at` timestamp is set to the current UTC time. The cache
    /// entry is invalidated so the next read fetches fresh data.
    ///
    /// # Errors
    ///
    /// Returns [`ClawError::NotFound`] if no record with the given `id` exists.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::{ClawEngine, MemoryRecord, MemoryType};
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let record = MemoryRecord::new("old content", MemoryType::Semantic, vec![], None);
    /// let id = engine.insert_memory(&record).await?;
    /// engine.update_memory(id, "new content").await?;
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip(self), fields(memory_id = %id))]
    pub async fn update_memory(&self, id: Uuid, content: &str) -> ClawResult<()> {
        let updated_at = chrono::Utc::now();
        MemoryStore::new(&self.pool)
            .update_content(id, content, updated_at)
            .await?;
        let mut cache = self.cache.lock().await;
        cache.invalidate(&id);
        Ok(())
    }

    /// Delete a [`MemoryRecord`] from the database by its UUID.
    ///
    /// The cache entry is also invalidated.
    ///
    /// # Errors
    ///
    /// Returns [`ClawError::NotFound`] if no record with the given `id` exists.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::{ClawEngine, MemoryRecord, MemoryType};
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let record = MemoryRecord::new("to delete", MemoryType::Episodic, vec![], None);
    /// let id = engine.insert_memory(&record).await?;
    /// engine.delete_memory(id).await?;
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip(self), fields(memory_id = %id))]
    pub async fn delete_memory(&self, id: Uuid) -> ClawResult<()> {
        MemoryStore::new(&self.pool).delete(id).await?;
        let mut cache = self.cache.lock().await;
        cache.invalidate(&id);
        Ok(())
    }

    /// List all [`MemoryRecord`]s, optionally filtered by [`MemoryType`].
    ///
    /// Results are ordered by `created_at` ascending.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the query fails.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::{ClawEngine, MemoryType};
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let all = engine.list_memories(None).await?;
    /// let semantic = engine.list_memories(Some(MemoryType::Semantic)).await?;
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip(self))]
    pub async fn list_memories(
        &self,
        type_filter: Option<MemoryType>,
    ) -> ClawResult<Vec<MemoryRecord>> {
        MemoryStore::new(&self.pool)
            .list(type_filter.as_ref())
            .await
    }

    /// List memories with keyset pagination.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the query fails.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::{ClawEngine, ListOptions, MemoryType};
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let (page, cursor) = engine.list_memories_paginated(
    ///     Some(MemoryType::Semantic),
    ///     ListOptions { limit: 50, cursor: None },
    /// ).await?;
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip(self))]
    pub async fn list_memories_paginated(
        &self,
        type_filter: Option<MemoryType>,
        opts: ListOptions,
    ) -> ClawResult<(Vec<MemoryRecord>, Option<String>)> {
        MemoryStore::new(&self.pool)
            .list_paginated(type_filter.as_ref(), &opts)
            .await
    }

    /// Search for [`MemoryRecord`]s whose tag list contains `tag`.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the query fails.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::ClawEngine;
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let results = engine.search_by_tag("important").await?;
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip(self))]
    pub async fn search_by_tag(&self, tag: &str) -> ClawResult<Vec<MemoryRecord>> {
        MemoryStore::new(&self.pool).search_by_tag(tag).await
    }

    /// Full-text search over all [`MemoryRecord`] contents using SQLite FTS5.
    ///
    /// The `query` string follows FTS5 query syntax (e.g. `"hello world"` for
    /// phrase search, `hello AND world` for AND search).
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the query fails.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::ClawEngine;
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let results = engine.fts_search("hello world").await?;
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip(self))]
    pub async fn fts_search(&self, query: &str) -> ClawResult<Vec<MemoryRecord>> {
        MemoryStore::new(&self.pool).fts_search(query).await
    }

    /// Expire all [`MemoryRecord`]s whose TTL has elapsed.
    ///
    /// Returns the number of records deleted. The cache is cleared if any
    /// records were deleted, since we do not know which IDs were affected.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the underlying deletion fails.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::ClawEngine;
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let expired = engine.expire_ttl_memories().await?;
    /// println!("deleted {expired} expired records");
    /// # Ok(())
    /// # }
    /// ```
    pub async fn expire_ttl_memories(&self) -> ClawResult<u64> {
        let deleted = MemoryStore::new(&self.pool).expire_ttl().await?;
        if deleted > 0 {
            let mut cache = self.cache.lock().await;
            cache.clear();
        }
        Ok(deleted)
    }

    // ── Session API ───────────────────────────────────────────────────────────

    /// Start a new session and return its unique ID.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the SQL execution fails.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::ClawEngine;
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let session_id = engine.start_session().await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn start_session(&self) -> ClawResult<String> {
        SessionLifecycleStore::new(&self.pool).start().await
    }

    /// Mark the session identified by `session_id` as ended.
    ///
    /// # Errors
    ///
    /// Returns [`ClawError::NotFound`] if the session does not exist.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::ClawEngine;
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let sid = engine.start_session().await?;
    /// engine.end_session(&sid).await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn end_session(&self, session_id: &str) -> ClawResult<()> {
        SessionLifecycleStore::new(&self.pool).end(session_id).await
    }

    /// Retrieve the [`Session`] record for `session_id`.
    ///
    /// # Errors
    ///
    /// Returns [`ClawError::NotFound`] if the session does not exist.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::ClawEngine;
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let sid = engine.start_session().await?;
    /// let session = engine.get_session(&sid).await?;
    /// assert!(session.ended_at.is_none());
    /// # Ok(())
    /// # }
    /// ```
    pub async fn get_session(&self, session_id: &str) -> ClawResult<Session> {
        SessionLifecycleStore::new(&self.pool).get(session_id).await
    }

    /// List all sessions, ordered by `started_at` descending.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the query fails.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::ClawEngine;
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let sessions = engine.list_sessions().await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn list_sessions(&self) -> ClawResult<Vec<Session>> {
        SessionLifecycleStore::new(&self.pool).list().await
    }

    // ── Tool Output API ───────────────────────────────────────────────────────

    /// Record a tool-output entry.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the SQL execution fails.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::{ClawEngine, ToolOutput};
    /// # use uuid::Uuid;
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let output = ToolOutput {
    ///     id: Uuid::new_v4(),
    ///     session_id: "sess-1".to_string(),
    ///     tool_name: "my_tool".to_string(),
    ///     output: serde_json::json!({"result": 42}),
    ///     success: true,
    ///     created_at: chrono::Utc::now(),
    /// };
    /// engine.record_tool_output(&output).await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn record_tool_output(&self, output: &ToolOutputRecord) -> ClawResult<()> {
        ToolOutputStore::new(&self.pool).insert(output).await
    }

    /// List all tool-output records for a given `session_id`.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the query fails.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::ClawEngine;
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let outputs = engine.list_tool_outputs("sess-1").await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn list_tool_outputs(&self, session_id: &str) -> ClawResult<Vec<ToolOutputRecord>> {
        ToolOutputStore::new(&self.pool)
            .get_by_session(session_id)
            .await
    }

    // ── Transaction API ───────────────────────────────────────────────────────

    /// Begin a new [`crate::transaction::ClawTransaction`] against this engine.
    ///
    /// # Errors
    ///
    /// Returns [`ClawError::Transaction`] if the pool cannot start a transaction.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::{ClawEngine, MemoryRecord, MemoryType};
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let mut tx = engine.transaction().await?;
    /// let r = MemoryRecord::new("hello", MemoryType::Semantic, vec![], None);
    /// tx.insert_memory(&r).await?;
    /// tx.commit().await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn transaction(&self) -> ClawResult<crate::transaction::ClawTransaction<'_>> {
        crate::transaction::ClawTransaction::begin(self).await
    }

    /// Begin a new [`crate::transaction::ClawTransaction`] against this engine.
    ///
    /// This is an alias for [`ClawEngine::transaction`].
    ///
    /// # Errors
    ///
    /// Returns [`ClawError::Transaction`] if the pool cannot start a transaction.
    pub async fn begin_transaction(&self) -> ClawResult<crate::transaction::ClawTransaction<'_>> {
        crate::transaction::ClawTransaction::begin(self).await
    }

    // ── Snapshot API ──────────────────────────────────────────────────────────

    /// Create a snapshot of the current database state.
    ///
    /// Requires `config.snapshot_dir` to be set. A WAL checkpoint is performed
    /// before the file copy to ensure all committed data is in the main DB file.
    ///
    /// # Errors
    ///
    /// Returns [`ClawError::Config`] if no snapshot directory is configured, or
    /// [`ClawError::Snapshot`] if the snapshot file cannot be written.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::{ClawEngine, ClawConfig};
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let config = ClawConfig::builder()
    /// #     .db_path("/tmp/claw.db")
    /// #     .snapshot_dir("/tmp/snaps")
    /// #     .build()?;
    /// # let engine = ClawEngine::open(config).await?;
    /// let meta = engine.snapshot_create().await?;
    /// println!("snapshot at {}", meta.path.display());
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip(self))]
    pub async fn snapshot_create(&self) -> ClawResult<SnapshotMeta> {
        let snap_dir = self.config.snapshot_dir.as_ref().ok_or_else(|| {
            ClawError::Config("snapshot_dir must be set to use snapshot_create".to_string())
        })?;
        // Flush WAL pages into the main DB file before copying.
        sqlx::query("PRAGMA wal_checkpoint(FULL)")
            .execute(&self.pool)
            .await?;
        let snapshotter = Snapshotter::new(snap_dir)?;
        let meta = snapshotter.take(&self.config.db_path)?;
        *self.last_snapshot_at.lock().await = Some(meta.created_at);
        Ok(meta)
    }

    /// Restore the database from a snapshot file.
    ///
    /// This method validates the snapshot is a genuine SQLite 3 file, closes
    /// the connection pool, replaces the live database, removes stale WAL/SHM
    /// sidecars, re-opens the pool, re-runs migrations, and clears the LRU
    /// cache.
    ///
    /// # Errors
    ///
    /// Returns [`ClawError::Snapshot`] if the snapshot is invalid or the copy
    /// fails, or a database error if the pool cannot be re-opened.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::{ClawEngine, ClawConfig};
    /// # use std::path::Path;
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let config = ClawConfig::builder()
    /// #     .db_path("/tmp/claw.db")
    /// #     .snapshot_dir("/tmp/snaps")
    /// #     .build()?;
    /// # let mut engine = ClawEngine::open(config).await?;
    /// engine.restore(Path::new("/tmp/snaps/snapshot.db")).await?;
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip(self), fields(snapshot = %snapshot_path.display()))]
    pub async fn restore(&mut self, snapshot_path: &Path) -> ClawResult<()> {
        use sqlx::sqlite::{SqliteConnectOptions, SqlitePoolOptions};
        use std::str::FromStr;

        // 1. Validate SQLite magic bytes.
        Self::validate_sqlite_magic(snapshot_path)?;

        // 2. Close the existing connection pool.
        self.pool.close().await;

        // 3. Overwrite the live database with the snapshot.
        std::fs::copy(snapshot_path, &self.config.db_path)
            .map_err(|e| ClawError::Snapshot(format!("failed to restore snapshot: {e}")))?;

        // 4. Remove stale WAL / SHM sidecar files.
        let db_name = self
            .config
            .db_path
            .file_name()
            .unwrap_or_default()
            .to_string_lossy()
            .into_owned();
        let db_parent = self
            .config
            .db_path
            .parent()
            .unwrap_or(std::path::Path::new("."));
        for suffix in &["-wal", "-shm"] {
            let sidecar = db_parent.join(format!("{db_name}{suffix}"));
            if sidecar.exists() {
                let _ = std::fs::remove_file(&sidecar);
            }
        }

        // 5. Re-open the connection pool.
        let db_url = format!("sqlite:{}", self.config.db_path.display());
        let connect_options = SqliteConnectOptions::from_str(&db_url)
            .map_err(|e| ClawError::Config(format!("invalid database URL: {e}")))?
            .create_if_missing(false);
        self.pool = SqlitePoolOptions::new()
            .max_connections(self.config.max_connections)
            .connect_with(connect_options)
            .await?;

        // Re-apply encryption key if required.
        #[cfg(feature = "encryption")]
        if let Some(key) = &self.config.encryption_key {
            let hex: String = key.iter().map(|b| format!("{b:02x}")).collect();
            sqlx::query(&format!("PRAGMA key = \"x'{hex}'\""))
                .execute(&self.pool)
                .await?;
        }

        // 6. Apply pending migrations.
        self.migrate().await?;

        // 7. Clear stale LRU cache entries.
        self.cache.lock().await.clear();

        tracing::info!(
            snapshot = %snapshot_path.display(),
            db = %self.config.db_path.display(),
            "database restored from snapshot"
        );
        Ok(())
    }

    /// Load the [`SnapshotManifest`] from the configured snapshot directory.
    ///
    /// Returns an empty manifest if no snapshot has been taken yet.
    ///
    /// # Errors
    ///
    /// Returns [`ClawError::Config`] if no `snapshot_dir` is configured.
    pub fn snapshot_manifest(&self) -> ClawResult<SnapshotManifest> {
        let snap_dir = self
            .config
            .snapshot_dir
            .as_ref()
            .ok_or_else(|| ClawError::Config("snapshot_dir must be set".to_string()))?;
        Snapshotter::new(snap_dir)?.load_manifest()
    }

    /// Rotate the SQLCipher encryption key using `PRAGMA rekey`.
    ///
    /// Only available with the `encryption` Cargo feature.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the PRAGMA execution fails.
    #[cfg(feature = "encryption")]
    pub async fn rotate_key(&self, _old_key: [u8; 32], new_key: [u8; 32]) -> ClawResult<()> {
        let hex: String = new_key.iter().map(|b| format!("{b:02x}")).collect();
        sqlx::query(&format!("PRAGMA rekey = \"x'{hex}'\""))
            .execute(&self.pool)
            .await?;
        Ok(())
    }

    // ── Cache & Stats API ─────────────────────────────────────────────────────

    /// Return a snapshot of the current in-memory cache statistics.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::ClawEngine;
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let stats = engine.cache_stats().await;
    /// println!("hits: {}, misses: {}", stats.hit_count, stats.miss_count);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn cache_stats(&self) -> CacheStats {
        self.stats.lock().await.clone()
    }

    /// Return comprehensive runtime statistics.
    ///
    /// Reports the total memory count, rolling cache hit rate (last 1000 ops),
    /// last snapshot timestamp, and on-disk database/WAL sizes.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the memory count query fails.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::ClawEngine;
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let s = engine.stats().await?;
    /// println!("hit rate: {:.1}%", s.cache_hit_rate * 100.0);
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip(self))]
    pub async fn stats(&self) -> ClawResult<ClawStats> {
        let (total_memories,): (i64,) = sqlx::query_as("SELECT COUNT(*) FROM memories")
            .fetch_one(&self.pool)
            .await?;
        let cache_hit_rate = self.stats.lock().await.rolling_hit_rate();
        let last_snapshot_at = *self.last_snapshot_at.lock().await;
        let db_size_bytes = std::fs::metadata(&self.config.db_path)
            .map(|m| m.len())
            .unwrap_or(0);
        let wal_path = {
            let p = self.config.db_path.to_string_lossy();
            std::path::PathBuf::from(format!("{p}-wal"))
        };
        let wal_size_bytes = std::fs::metadata(&wal_path).map(|m| m.len()).unwrap_or(0);
        Ok(ClawStats {
            total_memories: total_memories as u64,
            cache_hit_rate,
            last_snapshot_at,
            db_size_bytes,
            wal_size_bytes,
        })
    }

    /// Return database-level statistics.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if any of the count queries fail.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use claw_core::ClawEngine;
    /// # async fn example() -> claw_core::ClawResult<()> {
    /// # let engine = ClawEngine::open_default().await?;
    /// let stats = engine.db_stats().await?;
    /// println!("memories: {}", stats.memory_count);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn db_stats(&self) -> ClawResult<DbStats> {
        let (mc,): (i64,) = sqlx::query_as("SELECT COUNT(*) FROM memories")
            .fetch_one(&self.pool)
            .await?;
        let (sc,): (i64,) = sqlx::query_as("SELECT COUNT(*) FROM sessions")
            .fetch_one(&self.pool)
            .await?;
        let (tc,): (i64,) = sqlx::query_as("SELECT COUNT(*) FROM tool_output")
            .fetch_one(&self.pool)
            .await?;
        Ok(DbStats {
            memory_count: mc as u64,
            session_count: sc as u64,
            tool_output_count: tc as u64,
        })
    }

    // ── Helpers ───────────────────────────────────────────────────────────────

    fn validate_sqlite_magic(path: &Path) -> ClawResult<()> {
        use std::io::Read;
        const SQLITE_MAGIC: &[u8; 16] = b"SQLite format 3\0";
        let mut header = [0u8; 16];
        let mut file = std::fs::File::open(path)
            .map_err(|e| ClawError::Snapshot(format!("cannot open snapshot: {e}")))?;
        file.read_exact(&mut header)
            .map_err(|e| ClawError::Snapshot(format!("cannot read snapshot header: {e}")))?;
        if &header != SQLITE_MAGIC {
            return Err(ClawError::Snapshot(
                "file does not have a valid SQLite 3 header".to_string(),
            ));
        }
        Ok(())
    }
}