Skip to main content

clm_rust_core/layer2/
portable_sqlite.rs

1//! Layer 2: Portable SQLite Container Compilation and Parsing.
2//! Canonical Path: kernel/clm_rust_core/src/layer2/portable_sqlite.rs
3//! Parity: TypeScript `src/layer2/portableSqlite.ts`, Python `clm/layer2/portable_sqlite.py`
4
5#[cfg(any(feature = "native", feature = "db"))]
6pub use inner::*;
7
8#[cfg(any(feature = "native", feature = "db"))]
9mod inner {
10    use std::io::Write;
11    use rusqlite::{params, Connection};
12    use serde::{Deserialize, Serialize};
13
14    pub const SQLITE_HEADER: &[u8] = b"SQLite format 3\0";
15
16    /// The portable envelope after the Triad (INV-594): the Triad itself is the generated
17    /// `SQLITE_DDL_V3_1`, exactly as the TypeScript writer exports it. Foreign keys stay off:
18    /// an export may carry history whose cards it omits.
19    pub const PORTABLE_ENVELOPE: &str = "CREATE TABLE IF NOT EXISTS mcard_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL); PRAGMA foreign_keys = OFF;";
20
21    #[derive(Debug, Clone, Serialize, Deserialize)]
22    pub struct PortableSqliteCard {
23        pub hash: String,
24        pub content: Vec<u8>,
25        pub g_time: String,
26        pub handle: Option<String>,
27    }
28
29    #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
30    pub struct ParsedCard {
31        pub hash: String,
32        pub content: Vec<u8>,
33        pub g_time: String,
34    }
35
36    #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
37    pub struct ParsedHandle {
38        pub handle: String,
39        pub current_hash: String,
40        pub updated_at: String,
41    }
42
43    #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
44    pub struct ParsedHistory {
45        pub handle: String,
46        pub previous_hash: String,
47        pub changed_at: String,
48    }
49
50    #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
51    pub struct ParsedMeta {
52        pub key: String,
53        pub value: String,
54    }
55
56    #[derive(Debug, Clone, Serialize, Deserialize)]
57    pub struct ParsedPortableSqlite {
58        pub tables: Vec<String>,
59        pub cards: Vec<ParsedCard>,
60        pub handles: Vec<ParsedHandle>,
61        pub history: Vec<ParsedHistory>,
62        pub meta: Vec<ParsedMeta>,
63    }
64
65    pub fn compile_portable_sqlite(
66        cards: &[PortableSqliteCard],
67        schema_profile: Option<&str>,
68        exported_at: Option<&str>,
69        exported_by: Option<&str>,
70    ) -> Result<Vec<u8>, String> {
71        let temp_file = tempfile::NamedTempFile::new().map_err(|e| e.to_string())?;
72        let temp_path = temp_file.path();
73
74        {
75            let conn = Connection::open(temp_path).map_err(|e| e.to_string())?;
76            conn.execute_batch(crate::layer0::runtime_contract::SQLITE_DDL_V3_1).map_err(|e| e.to_string())?;
77            conn.execute_batch(PORTABLE_ENVELOPE).map_err(|e| e.to_string())?;
78
79            // Virtual column compatibility
80            let _ = conn.execute_batch(
81                "ALTER TABLE handle_registry ADD COLUMN hash TEXT GENERATED ALWAYS AS (current_hash) VIRTUAL;
82                 ALTER TABLE handle_history ADD COLUMN hash TEXT GENERATED ALWAYS AS (previous_hash) VIRTUAL;
83                 ALTER TABLE handle_history ADD COLUMN created_at TEXT GENERATED ALWAYS AS (changed_at) VIRTUAL;"
84            );
85
86            let profile = schema_profile.unwrap_or("portable-3.0.3");
87            let author = exported_by.unwrap_or("RustCLM");
88            let now = chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Millis, true);
89            let ts = exported_at.unwrap_or(&now);
90
91            conn.execute(
92                "INSERT OR REPLACE INTO mcard_meta (key, value) VALUES (?1, ?2), (?3, ?4), (?5, ?6), (?7, ?8);",
93                params![
94                    "schema_profile", profile,
95                    "exported_at", ts,
96                    "card_count", cards.len().to_string(),
97                    "exported_by", author
98                ],
99            ).map_err(|e| e.to_string())?;
100
101            let mut insert_handle = conn.prepare(
102                "INSERT OR REPLACE INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3);"
103            ).map_err(|e| e.to_string())?;
104
105            let mut insert_history = conn.prepare(
106                "INSERT INTO handle_history (handle, previous_hash, changed_at) VALUES (?1, ?2, ?3);"
107            ).map_err(|e| e.to_string())?;
108
109            for card in cards {
110                crate::layer2::record_store::insert_record(&conn, &crate::layer0::mcard_record::MCardRecord {
111                    hash: card.hash.clone(), content: card.content.clone(), g_time: card.g_time.clone(),
112                }).map_err(|e| e.to_string())?;
113                if let Some(ref h) = card.handle {
114                    insert_handle.execute(params![h, card.hash, card.g_time]).map_err(|e| e.to_string())?;
115                    insert_history.execute(params![h, card.hash, card.g_time]).map_err(|e| e.to_string())?;
116                }
117            }
118        }
119
120        std::fs::read(temp_path).map_err(|e| e.to_string())
121    }
122
123    pub fn parse_portable_sqlite(bytes: &[u8]) -> Result<ParsedPortableSqlite, String> {
124        if bytes.len() < 16 {
125            return Err("File too small to be a valid SQLite database".to_string());
126        }
127        if !bytes.starts_with(SQLITE_HEADER) {
128            return Err("Invalid SQLite 3 binary header (magic bytes mismatch)".to_string());
129        }
130
131        let mut temp_file = tempfile::NamedTempFile::new().map_err(|e| e.to_string())?;
132        temp_file.write_all(bytes).map_err(|e| e.to_string())?;
133        let temp_path = temp_file.path();
134
135        let conn = Connection::open(temp_path).map_err(|e| e.to_string())?;
136
137        let mut stmt = conn.prepare("SELECT name FROM sqlite_master WHERE type='table';").map_err(|e| e.to_string())?;
138        let table_iter = stmt.query_map([], |r| r.get::<_, String>(0)).map_err(|e| e.to_string())?;
139        let mut tables = Vec::new();
140        for t in table_iter {
141            tables.push(t.map_err(|e| e.to_string())?);
142        }
143
144        let mut cards = Vec::new();
145        if tables.contains(&"card".to_string()) {
146            let mut s = conn.prepare("SELECT hash, content, g_time FROM card;").map_err(|e| e.to_string())?;
147            let rows = s.query_map([], |r| {
148                Ok(ParsedCard {
149                    hash: r.get(0)?,
150                    content: r.get_ref(1)?.as_bytes()?.to_vec(),
151                    g_time: r.get(2)?,
152                })
153            }).map_err(|e| e.to_string())?;
154            for c in rows {
155                let card = c.map_err(|e| e.to_string())?;
156                crate::layer2::record_store::require_verified(&crate::layer0::mcard_record::MCardRecord {
157                    hash: card.hash.clone(), content: card.content.clone(), g_time: card.g_time.clone(),
158                }).map_err(|e| e.to_string())?;
159                cards.push(card);
160            }
161        }
162
163        let mut handles = Vec::new();
164        if tables.contains(&"handle_registry".to_string()) {
165            let mut s = conn.prepare("SELECT handle, current_hash, updated_at FROM handle_registry;").map_err(|e| e.to_string())?;
166            let rows = s.query_map([], |r| {
167                Ok(ParsedHandle {
168                    handle: r.get(0)?,
169                    current_hash: r.get(1)?,
170                    updated_at: r.get(2)?,
171                })
172            }).map_err(|e| e.to_string())?;
173            for h in rows {
174                handles.push(h.map_err(|e| e.to_string())?);
175            }
176        }
177
178        let mut history = Vec::new();
179        if tables.contains(&"handle_history".to_string()) {
180            let mut s = conn.prepare("SELECT handle, previous_hash, changed_at FROM handle_history;").map_err(|e| e.to_string())?;
181            let rows = s.query_map([], |r| {
182                Ok(ParsedHistory {
183                    handle: r.get(0)?,
184                    previous_hash: r.get(1)?,
185                    changed_at: r.get(2)?,
186                })
187            }).map_err(|e| e.to_string())?;
188            for h in rows {
189                history.push(h.map_err(|e| e.to_string())?);
190            }
191        }
192
193        let mut meta = Vec::new();
194        if tables.contains(&"mcard_meta".to_string()) {
195            let mut s = conn.prepare("SELECT key, value FROM mcard_meta;").map_err(|e| e.to_string())?;
196            let rows = s.query_map([], |r| {
197                Ok(ParsedMeta {
198                    key: r.get(0)?,
199                    value: r.get(1)?,
200                })
201            }).map_err(|e| e.to_string())?;
202            for m in rows {
203                meta.push(m.map_err(|e| e.to_string())?);
204            }
205        }
206
207        Ok(ParsedPortableSqlite {
208            tables,
209            cards,
210            handles,
211            history,
212            meta,
213        })
214    }
215}