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            // ORC-23/27: `created_at` IS NOT A COLUMN — IT IS THE FIRST HISTORY ROW.
56            //
57            // This read `created_at` directly, so the retention pass either failed or silently
58            // pruned nothing the moment the column went. The translation is not `updated_at`:
59            // that answers "not touched recently", and this asks "created long ago". The first
60            // history row is what the column MEANT, so it is what the query uses.
61            "DELETE FROM handle_registry WHERE (handle LIKE 'run:%' OR handle LIKE 'escalation:%' OR handle LIKE 'tests:%') \
62             AND handle IN (SELECT handle FROM handle_history GROUP BY handle \
63                            HAVING MIN(changed_at) < datetime('now', '-' || ?1 || ' days'));",
64            rusqlite::params![max_age_days],
65        )?
66    };
67    report.handles_pruned = handles_pruned;
68
69    // 3. Delete handle history for pruned handles or older than retention
70    let history_pruned = if max_age_days == 0 {
71        tx.execute(
72            "DELETE FROM handle_history WHERE handle NOT IN (SELECT handle FROM handle_registry);",
73            [],
74        )?
75    } else {
76        tx.execute(
77            "DELETE FROM handle_history WHERE handle NOT IN (SELECT handle FROM handle_registry) OR changed_at < datetime('now', '-' || ?1 || ' days');",
78            rusqlite::params![max_age_days],
79        )?
80    };
81    report.history_pruned = history_pruned;
82
83    // 4. Delete orphan cards not referenced in handle_registry
84    let cards_pruned = tx.execute(
85        "DELETE FROM card WHERE hash NOT IN (SELECT current_hash FROM handle_registry);",
86        [],
87    )?;
88    report.cards_pruned = cards_pruned;
89
90    tx.commit()?;
91
92    // 5. Rebuild documents cleanly from remaining cards if FTS5 documents table exists
93    let has_docs: bool = conn
94        .query_row(
95            "SELECT count(*) FROM sqlite_master WHERE type='table' AND name='documents';",
96            [],
97            |r| r.get(0),
98        )
99        .unwrap_or(0) > 0;
100
101    if has_docs {
102        let _ = conn.execute_batch("
103            DELETE FROM documents;
104            INSERT INTO documents(content) SELECT content FROM card;
105            INSERT INTO documents(documents) VALUES('optimize');
106        ");
107        report.documents_optimized = true;
108    }
109
110    // 6. Re-create triggers and index
111    let _ = conn.execute_batch("
112        CREATE TRIGGER IF NOT EXISTS card_update AFTER UPDATE ON card
113        BEGIN
114            UPDATE documents SET content = new.content
115            WHERE rowid = (SELECT rowid FROM documents WHERE content = old.content LIMIT 1);
116        END;
117
118        CREATE TRIGGER IF NOT EXISTS card_delete AFTER DELETE ON card
119        BEGIN
120            DELETE FROM documents WHERE content = old.content;
121        END;
122
123        CREATE INDEX IF NOT EXISTS idx_handle_history_prev_hash ON handle_history(previous_hash);
124        PRAGMA foreign_keys = ON;
125    ");
126
127    // 7. WAL checkpoint and VACUUM
128    let _ = conn.execute_batch("PRAGMA wal_checkpoint(TRUNCATE);");
129    let _ = conn.execute_batch("VACUUM;");
130    report.vacuumed = true;
131
132    drop(conn);
133
134    report.execution_log_final_bytes = std::fs::metadata(&db_path).map(|m| m.len()).unwrap_or(0);
135    Ok(report)
136}
137
138/// Run full compaction and vacuum across all three Tri-Database pillars.
139#[cfg(any(feature = "native", feature = "db"))]
140pub fn compact_all(clm_root: &str) -> Result<CompactionReport> {
141    let pillars = ["content_memory", "agent_identities", "execution_log"];
142    for pillar in &pillars {
143        let path = crate::db::get_db_path(pillar, clm_root);
144        if path.exists()
145            && let Ok(conn) = Connection::open(&path) {
146                let _ = conn.busy_timeout(std::time::Duration::from_secs(30));
147                let _ = conn.execute_batch("PRAGMA wal_checkpoint(TRUNCATE);");
148                let _ = conn.execute_batch("VACUUM;");
149            }
150    }
151    prune_execution_logs(clm_root, 0)
152}