Skip to main content

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