Skip to main content

clm_rust_core/db/
compaction.rs

1//! Tri-DB Compaction, WAL Checkpointing, and Retention Pruning Engine.
2//!
3//! Enforces Invariant INV-417 (Zero-Copy Savepoint & Storage Bound):
4//! - Prunes historical execution receipts older than retention threshold.
5//! - Rebuilds and optimizes FTS5 index tables.
6//! - Checkpoints SQLite WAL with TRUNCATE and runs VACUUM to reclaim disk space.
7
8#[cfg(any(feature = "native", feature = "db"))]
9use rusqlite::Connection;
10#[cfg(any(feature = "native", feature = "db"))]
11use crate::error::Result;
12
13#[derive(Debug, Default, Clone, serde::Serialize, serde::Deserialize)]
14pub struct CompactionReport {
15    pub execution_log_initial_bytes: u64,
16    pub execution_log_final_bytes: u64,
17    pub cards_pruned: usize,
18    pub handles_pruned: usize,
19    pub history_pruned: usize,
20    pub documents_optimized: bool,
21    pub vacuumed: bool,
22}
23
24/// Prune execution logs older than `max_age_days` (or ephemeral test runs if max_age_days == 0).
25#[cfg(any(feature = "native", feature = "db"))]
26pub fn prune_execution_logs(clm_root: &str, max_age_days: u64) -> Result<CompactionReport> {
27    let mut report = CompactionReport::default();
28    let db_path = crate::db::get_db_path("execution_log", clm_root);
29    if !db_path.exists() {
30        return Ok(report);
31    }
32
33    report.execution_log_initial_bytes = std::fs::metadata(&db_path).map(|m| m.len()).unwrap_or(0);
34
35    let mut conn = Connection::open(&db_path)?;
36    conn.busy_timeout(std::time::Duration::from_secs(30))?;
37
38    // 1. Temporarily drop triggers to avoid O(M*N) full scans of FTS5 during bulk deletion
39    let _ = conn.execute_batch("
40        DROP TRIGGER IF EXISTS card_delete;
41        DROP TRIGGER IF EXISTS card_update;
42        PRAGMA foreign_keys = OFF;
43    ");
44
45    let tx = conn.transaction()?;
46
47    // 2. Delete ephemeral test handles or handles older than max_age_days
48    let handles_pruned = if max_age_days == 0 {
49        tx.execute(
50            "DELETE FROM handle_registry WHERE handle LIKE 'run:%' OR handle LIKE 'escalation:%' OR handle LIKE 'tests:%';",
51            [],
52        )?
53    } else {
54        tx.execute(
55            "DELETE FROM handle_registry WHERE (handle LIKE 'run:%' OR handle LIKE 'escalation:%' OR handle LIKE 'tests:%') AND created_at < datetime('now', '-' || ?1 || ' days');",
56            rusqlite::params![max_age_days],
57        )?
58    };
59    report.handles_pruned = handles_pruned;
60
61    // 3. Delete handle history for pruned handles or older than retention
62    let history_pruned = if max_age_days == 0 {
63        tx.execute(
64            "DELETE FROM handle_history WHERE handle NOT IN (SELECT handle FROM handle_registry);",
65            [],
66        )?
67    } else {
68        tx.execute(
69            "DELETE FROM handle_history WHERE handle NOT IN (SELECT handle FROM handle_registry) OR changed_at < datetime('now', '-' || ?1 || ' days');",
70            rusqlite::params![max_age_days],
71        )?
72    };
73    report.history_pruned = history_pruned;
74
75    // 4. Delete orphan cards not referenced in handle_registry
76    let cards_pruned = tx.execute(
77        "DELETE FROM card WHERE hash NOT IN (SELECT current_hash FROM handle_registry);",
78        [],
79    )?;
80    report.cards_pruned = cards_pruned;
81
82    tx.commit()?;
83
84    // 5. Rebuild documents cleanly from remaining cards if FTS5 documents table exists
85    let has_docs: bool = conn
86        .query_row(
87            "SELECT count(*) FROM sqlite_master WHERE type='table' AND name='documents';",
88            [],
89            |r| r.get(0),
90        )
91        .unwrap_or(0) > 0;
92
93    if has_docs {
94        let _ = conn.execute_batch("
95            DELETE FROM documents;
96            INSERT INTO documents(content) SELECT content FROM card;
97            INSERT INTO documents(documents) VALUES('optimize');
98        ");
99        report.documents_optimized = true;
100    }
101
102    // 6. Re-create triggers and index
103    let _ = conn.execute_batch("
104        CREATE TRIGGER IF NOT EXISTS card_update AFTER UPDATE ON card
105        BEGIN
106            UPDATE documents SET content = new.content
107            WHERE rowid = (SELECT rowid FROM documents WHERE content = old.content LIMIT 1);
108        END;
109
110        CREATE TRIGGER IF NOT EXISTS card_delete AFTER DELETE ON card
111        BEGIN
112            DELETE FROM documents WHERE content = old.content;
113        END;
114
115        CREATE INDEX IF NOT EXISTS idx_handle_history_prev_hash ON handle_history(previous_hash);
116        PRAGMA foreign_keys = ON;
117    ");
118
119    // 7. WAL checkpoint and VACUUM
120    let _ = conn.execute_batch("PRAGMA wal_checkpoint(TRUNCATE);");
121    let _ = conn.execute_batch("VACUUM;");
122    report.vacuumed = true;
123
124    drop(conn);
125
126    report.execution_log_final_bytes = std::fs::metadata(&db_path).map(|m| m.len()).unwrap_or(0);
127    Ok(report)
128}
129
130/// Run full compaction and vacuum across all three Tri-Database pillars.
131#[cfg(any(feature = "native", feature = "db"))]
132pub fn compact_all(clm_root: &str) -> Result<CompactionReport> {
133    let pillars = ["content_memory", "agent_identities", "execution_log"];
134    for pillar in &pillars {
135        let path = crate::db::get_db_path(pillar, clm_root);
136        if path.exists() {
137            if let Ok(conn) = Connection::open(&path) {
138                let _ = conn.busy_timeout(std::time::Duration::from_secs(30));
139                let _ = conn.execute_batch("PRAGMA wal_checkpoint(TRUNCATE);");
140                let _ = conn.execute_batch("VACUUM;");
141            }
142        }
143    }
144    prune_execution_logs(clm_root, 0)
145}