Skip to main content

clm_rust_core/layer4/
mcard_fs.rs

1//! MCard Universal Virtual Filesystem Engine (Sprint 191).
2//!
3//! Enforces:
4//! 1. Zero-FS Hermeticity (INV-09): Operates in-memory or on SQLite CAS without host disk I/O.
5//! 2. Handle Registry Singularity (INV-04) & Tri-Database Separation (INV-05):
6//!    Directly wraps canonical `card`, `handle_registry`, and `handle_history` tables.
7//! 3. Content-Addressable Identity (INV-02): BLAKE3 hashes for all MCard payloads.
8//! 4. Spatiotemporal Compositionality: Mountable in Cordis Context for scoped fiber execution.
9
10use crate::{domain::{MCard, MCardPayload}, layer0::vocabulary::{HANDLE_MCARD, HASH_PREFIX_BLAKE3}};
11use crate::error::{ClmError, Result, StorageErrorCode};
12use crate::types::{AgentDid, ContentHash};
13use rusqlite::{params, Connection};
14use serde::{Deserialize, Serialize};
15use std::sync::{Arc, Mutex};
16
17/// File metadata stat for an MCard in the virtual filesystem.
18#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
19pub struct MCardStat {
20    pub uri: String,
21    pub hash: ContentHash,
22    pub size_bytes: usize,
23    pub created_at: String,
24    pub updated_at: String,
25}
26
27pub use crate::layer2::vfs::{DirectoryManifest, DirectoryManifestEntry};
28
29/// The universal immutable filesystem engine mapping URIs to content-addressed MCards.
30#[derive(Clone)]
31pub struct MCardFileSystem {
32    pub(crate) conn: Arc<Mutex<Connection>>,
33    pub(crate) context_prefix: String,
34}
35
36/// Kind marker for the record that retires a handle.
37const TOMBSTONE_KIND: &str = "TOMBSTONE";
38
39/// True when a handle head names a retirement record rather than live content.
40fn head_is_tombstone(conn: &Connection, hash: &str) -> Result<bool> {
41    let mut stmt = conn.prepare_cached("SELECT content FROM card WHERE hash = ?1")?;
42    let content: Option<Vec<u8>> = stmt.query_row(params![hash], |row| row.get(0)).ok();
43    let Some(bytes) = content else {
44        return Ok(false);
45    };
46    if bytes.len() > 4096 {
47        return Ok(false);
48    }
49    Ok(serde_json::from_slice::<serde_json::Value>(&bytes)
50        .ok()
51        .and_then(|v| {
52            v.get("kind")
53                .and_then(|k| k.as_str())
54                .map(|k| k == TOMBSTONE_KIND)
55        })
56        .unwrap_or(false))
57}
58
59/// Names a stored row the way a transition record does: `<algorithm>:<hex>`.
60fn qualified_ref(conn: &Connection, hash: &str) -> Result<String> {
61    let mut stmt = conn.prepare_cached("SELECT content, g_time FROM card WHERE hash = ?1")?;
62    let row: Option<(Vec<u8>, String)> = stmt
63        .query_row(params![hash], |r| Ok((r.get(0)?, r.get(1)?)))
64        .ok();
65    let Some((content, g_time)) = row else {
66        return Ok(format!("{HASH_PREFIX_BLAKE3}{hash}"));
67    };
68    let record = crate::layer0::mcard_record::MCardRecord {
69        hash: hash.to_string(),
70        content,
71        g_time,
72    };
73    let algorithm = match crate::layer0::mcard_record::verify_record(&record) {
74        crate::layer0::mcard_record::RecordVerification::DeclaredOk { algorithm } => algorithm,
75        crate::layer0::mcard_record::RecordVerification::LegacyClassified { algorithm } => algorithm,
76        _ => crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3.to_string(),
77    };
78    Ok(format!("{algorithm}:{hash}"))
79}
80
81impl MCardFileSystem {
82    /// Initializes an isolated, zero-disk in-memory MCard filesystem (INV-09).
83    pub fn new_in_memory() -> Result<Self> {
84        let conn = Connection::open_in_memory()?;
85        Self::init_schema(&conn)?;
86        Ok(Self {
87            conn: Arc::new(Mutex::new(conn)),
88            context_prefix: String::new(),
89        })
90    }
91
92    /// Initializes an in-memory MCard filesystem scoped to a specific context prefix.
93    pub fn new_in_memory_scoped(prefix: &str) -> Result<Self> {
94        let mut fs = Self::new_in_memory()?;
95        fs.context_prefix = prefix.trim_matches('/').to_string();
96        Ok(fs)
97    }
98
99    /// Wraps an existing SQLite connection manager or shared connection with an optional context prefix.
100    pub fn new(conn: Arc<Mutex<Connection>>, context_prefix: &str) -> Self {
101        Self {
102            conn,
103            context_prefix: context_prefix.trim_matches('/').to_string(),
104        }
105    }
106
107    /// Wraps an existing SQLite connection manager or shared connection (root prefix).
108    pub fn with_connection(conn: Arc<Mutex<Connection>>) -> Result<Self> {
109        {
110            let locked = conn
111                .lock()
112                .map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
113            Self::init_schema(&locked)?;
114        }
115        Ok(Self {
116            conn,
117            context_prefix: String::new(),
118        })
119    }
120
121    /// Returns a new `MCardFileSystem` handle sharing the same storage but isolated to `prefix`.
122    pub fn with_prefix(&self, prefix: &str) -> Self {
123        Self {
124            conn: self.conn.clone(),
125            context_prefix: prefix.trim_matches('/').to_string(),
126        }
127    }
128
129    /// Returns the active context prefix for this filesystem handle.
130    pub fn context_prefix(&self) -> &str {
131        &self.context_prefix
132    }
133
134    /// Resolves canonical URI with context prefix scoping (DOD-191-04).
135    pub fn canonicalize_uri(&self, path: &str) -> String {
136        let clean = path.trim_start_matches('/');
137        if let Some(rest) = clean.strip_prefix(crate::layer0::vocabulary::HANDLE_MCARD) {
138            let rest_clean = rest.trim_start_matches('/');
139            if self.context_prefix.is_empty() {
140                format!("{HANDLE_MCARD}{}", rest_clean)
141            } else if rest_clean.starts_with(&self.context_prefix) {
142                format!("{HANDLE_MCARD}{}", rest_clean)
143            } else {
144                format!("{HANDLE_MCARD}{}/{}", self.context_prefix, rest_clean)
145            }
146        } else if self.context_prefix.is_empty() {
147            format!("{HANDLE_MCARD}{}", clean)
148        } else {
149            format!("{HANDLE_MCARD}{}/{}", self.context_prefix, clean)
150        }
151    }
152
153    /// Ephemerally mounts a scoped MCardFileSystem on a Fiber, registering a LIFO unmount
154    /// callback on the fiber's DisposableList that cleans up all transient handles on disposal (DOD-191-07).
155    pub fn ephemeral_mount(&self, fiber: &crate::fiber::context::Fiber, prefix: &str) -> Result<Self> {
156        let scoped_fs = self.with_prefix(prefix);
157        let prefix_clean = prefix.trim_matches('/').to_string();
158        let handle_pattern = if prefix_clean.is_empty() {
159            crate::layer0::vocabulary::HANDLE_MCARD_3.to_string()
160        } else {
161            format!("{HANDLE_MCARD}{}/%", prefix_clean)
162        };
163        let conn_clone = self.conn.clone();
164
165        fiber.register_disposable(move || {
166            let conn = conn_clone.lock().map_err(|e| e.to_string())?;
167            conn.execute(
168                "DELETE FROM handle_history WHERE handle LIKE ?1",
169                rusqlite::params![&handle_pattern],
170            )
171            .map_err(|e| e.to_string())?;
172            conn.execute(
173                "DELETE FROM handle_registry WHERE handle LIKE ?1",
174                rusqlite::params![&handle_pattern],
175            )
176            .map_err(|e| e.to_string())?;
177            Ok(())
178        });
179
180        Ok(scoped_fs)
181    }
182
183    /// Ensures the canonical Tri-Database schema exists (INV-04, INV-05).
184    fn init_schema(conn: &Connection) -> Result<()> {
185        conn.execute_batch(crate::layer0::runtime_contract::SQLITE_DDL_V3_1)?;
186        Ok(())
187    }
188
189    /// Writes an MCard into the filesystem, content-addressing the payload and updating the handle registry.
190    pub fn write_file(&self, uri: &str, payload: MCardPayload, author: AgentDid) -> Result<MCard> {
191        let canonical_uri = self.canonicalize_uri(uri);
192        let now = crate::utils::now_iso8601();
193        let mut conn = self
194            .conn
195            .lock()
196            .map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
197
198        let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
199
200        // 1. Check existing handle state to maintain sequence
201        let existing: Option<String> = {
202            let mut stmt = tx.prepare_cached(
203                "SELECT current_hash FROM handle_registry WHERE handle = ?1",
204            )?;
205            stmt.query_row(params![&canonical_uri], |row| row.get(0))
206                .ok()
207        };
208
209        let seq = match &existing {
210            Some(_) => {
211                // Determine next sequence from history count
212                let mut count_stmt = tx.prepare_cached(
213                    "SELECT count(*) FROM handle_history WHERE handle = ?1",
214                )?;
215                let count: i64 = count_stmt.query_row(params![&canonical_uri], |row| row.get(0))?;
216                (count as u64) + 2
217            }
218            None => 1,
219        };
220
221        // 2. Construct canonical MCard and its envelope record. The handle binds the *file*, whose
222        // digest covers its own canonical bytes; the MCard identity it carries is the payload hash.
223        let mcard = MCard::new(&canonical_uri, payload, author, seq);
224        let envelope = crate::layer0::codec::canonical_json(&mcard).map_err(|e| e.to_string())?;
225        let record = crate::layer0::mcard_record::MCardRecord::create(envelope.as_bytes(), None)
226            .map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e))?;
227        let hash_str = record.hash.clone();
228
229        // 3. Insert the self-verifying envelope record (INV-02, INV-05)
230        {
231            let mut stmt_card = tx.prepare_cached(
232                "INSERT OR IGNORE INTO card (hash, content, g_time) VALUES (?1, ?2, ?3)",
233            )?;
234            stmt_card.execute(params![&record.hash, &record.content, &record.g_time])?;
235        }
236
237        // 4. Update handle history if previous hash exists and differs (G-Set tracking)
238        if let Some(prev_hash) = existing.as_ref().filter(|prev| **prev != hash_str) {
239            let mut stmt_hist = tx.prepare_cached(
240                "INSERT INTO handle_history (handle, previous_hash, changed_at) VALUES (?1, ?2, ?3)",
241            )?;
242            stmt_hist.execute(params![&canonical_uri, prev_hash, now])?;
243        }
244
245        // 5. Update or insert handle registry entry (INV-04)
246        {
247            let mut stmt_reg = tx.prepare_cached(
248                "INSERT OR REPLACE INTO handle_registry (handle, current_hash, updated_at) \
249                 VALUES (?1, ?2, ?3)",
250            )?;
251            stmt_reg.execute(params![&canonical_uri, hash_str, now])?;
252        }
253
254        tx.commit()?;
255        Ok(mcard)
256    }
257
258    /// Reads and cryptographically verifies an MCard by its URI handle (INV-02, INV-04).
259    pub fn read_file(&self, uri: &str) -> Result<MCard> {
260        let canonical_uri = self.canonicalize_uri(uri);
261        let conn = self
262            .conn
263            .lock()
264            .map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
265
266        // 1. Resolve handle to current hash
267        let current_hash: String = {
268            let mut stmt = conn.prepare_cached(
269                "SELECT current_hash FROM handle_registry WHERE handle = ?1",
270            )?;
271            stmt.query_row(params![&canonical_uri], |row| row.get(0)).map_err(|_| {
272                ClmError::storage(
273                    StorageErrorCode::CardNotFound,
274                    format!("Handle '{}' not found in MCardFs", canonical_uri),
275                )
276            })?
277        };
278
279        if head_is_tombstone(&conn, &current_hash)? {
280            return Err(ClmError::storage(
281                StorageErrorCode::CardNotFound,
282                format!("Handle '{}' is retired", canonical_uri),
283            ));
284        }
285
286        // 2. Fetch the stored row (content + coordinate)
287        let (content, g_time): (Vec<u8>, String) = {
288            let mut stmt = conn.prepare_cached("SELECT content, g_time FROM card WHERE hash = ?1")?;
289            stmt.query_row(params![current_hash], |row| Ok((row.get(0)?, row.get(1)?)))
290                .map_err(|_| {
291                    ClmError::storage(
292                        StorageErrorCode::CorruptedContent,
293                        format!("Card content for hash '{}' not found", current_hash),
294                    )
295                })?
296        };
297
298        // 3. Verify the row from the row alone, then deserialize the envelope.
299        let record = crate::layer0::mcard_record::MCardRecord {
300            hash: current_hash.clone(),
301            content: content.clone(),
302            g_time: g_time.clone(),
303        };
304        if !matches!(
305            crate::layer0::mcard_record::verify_record(&record),
306            crate::layer0::mcard_record::RecordVerification::DeclaredOk { .. }
307        ) {
308            return Err(ClmError::storage(
309                StorageErrorCode::CorruptedContent,
310                format!("Cryptographic mismatch for handle '{}': stored row does not verify", canonical_uri),
311            ));
312        }
313
314        let mcard: MCard = serde_json::from_slice(&content)?;
315        Ok(mcard)
316    }
317
318    /// Checks if an MCard exists by its handle URI.
319    pub fn exists(&self, uri: &str) -> Result<bool> {
320        let canonical_uri = self.canonicalize_uri(uri);
321        let conn = self
322            .conn
323            .lock()
324            .map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
325        let head: Option<String> = {
326            let mut stmt = conn.prepare_cached(
327                "SELECT current_hash FROM handle_registry WHERE handle = ?1",
328            )?;
329            stmt.query_row(params![&canonical_uri], |row| row.get(0)).ok()
330        };
331        match head {
332            Some(hash) => Ok(!head_is_tombstone(&conn, &hash)?),
333            None => Ok(false),
334        }
335    }
336
337    /// Returns stat metadata for a virtual file.
338    pub fn stat_file(&self, uri: &str) -> Result<MCardStat> {
339        let canonical_uri = self.canonicalize_uri(uri);
340        let conn = self
341            .conn
342            .lock()
343            .map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
344
345        let (hash_str, updated_at): (String, String) = {
346            let mut stmt = conn.prepare_cached(
347                "SELECT current_hash, updated_at FROM handle_registry WHERE handle = ?1",
348            )?;
349            stmt.query_row(params![&canonical_uri], |row| {
350                Ok((row.get(0)?, row.get(1)?))
351            })
352            .map_err(|_| {
353                ClmError::storage(
354                    StorageErrorCode::CardNotFound,
355                    format!("Handle '{}' not found", canonical_uri),
356                )
357            })?
358        };
359
360        if head_is_tombstone(&conn, &hash_str)? {
361            return Err(ClmError::storage(
362                StorageErrorCode::CardNotFound,
363                format!("Handle '{}' is retired", canonical_uri),
364            ));
365        }
366
367        let created_at: String = {
368            let mut stmt = conn.prepare_cached(
369                "SELECT changed_at FROM handle_history WHERE handle = ?1 ORDER BY rowid ASC LIMIT 1",
370            )?;
371            stmt.query_row(params![&canonical_uri], |row| row.get(0))
372                .unwrap_or_else(|_| updated_at.clone())
373        };
374
375        let size_bytes: usize = {
376            let mut stmt = conn.prepare_cached("SELECT length(content) FROM card WHERE hash = ?1")?;
377            stmt.query_row(params![hash_str], |row| row.get::<_, i64>(0))
378                .unwrap_or(0) as usize
379        };
380
381        // `stat.hash` names the MCard (the payload digest carried in the envelope record), not
382        // the envelope record's own digest.
383        let hash = {
384            let mut stmt = conn.prepare_cached("SELECT content FROM card WHERE hash = ?1")?;
385            let body: Vec<u8> = stmt.query_row(params![hash_str], |row| row.get(0)).unwrap_or_default();
386            match serde_json::from_slice::<MCard>(&body) {
387                Ok(envelope) => ContentHash::parse(&envelope.hash)?,
388                Err(_) => ContentHash::parse(&hash_str)?,
389            }
390        };
391        Ok(MCardStat {
392            uri: canonical_uri,
393            hash,
394            size_bytes,
395            created_at,
396            updated_at,
397        })
398    }
399
400    /// Lists all MCard handles sharing the specified URI prefix.
401    pub fn list_dir(&self, prefix: &str) -> Result<Vec<String>> {
402        let conn = self
403            .conn
404            .lock()
405            .map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
406
407        let canonical_prefix = self.canonicalize_uri(prefix);
408        let pattern = if canonical_prefix.ends_with('/') {
409            format!("{}%", canonical_prefix)
410        } else if canonical_prefix == crate::layer0::vocabulary::HANDLE_MCARD {
411            crate::layer0::vocabulary::HANDLE_MCARD_3.to_string()
412        } else {
413            format!("{}/%", canonical_prefix)
414        };
415
416        let mut stmt = conn.prepare_cached(
417            "SELECT handle, current_hash FROM handle_registry WHERE handle LIKE ?1 ORDER BY handle ASC",
418        )?;
419        let rows = stmt.query_map(params![pattern], |row| {
420            Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
421        })?;
422
423        let mut handles = Vec::new();
424        for row in rows {
425            let (handle, head) = row?;
426            if !head_is_tombstone(&conn, &head)? {
427                handles.push(handle);
428            }
429        }
430        Ok(handles)
431    }
432
433    /// Retires an MCard handle by appending a TOMBSTONE record and binding the head to it.
434    ///
435    /// Retirement is a name-plane event: the content card stays readable by hash, the handle row
436    /// and its history stay on the tape, and `current_hash` names the record that retired it.
437    pub fn retire(&self, uri: &str, reason: Option<&str>, author: AgentDid) -> Result<()> {
438        let canonical_uri = self.canonicalize_uri(uri);
439        let now = crate::utils::now_iso8601();
440        let mut conn = self
441            .conn
442            .lock()
443            .map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
444
445        let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
446
447        let previous_hash: String = {
448            let mut stmt = tx.prepare_cached(
449                "SELECT current_hash FROM handle_registry WHERE handle = ?1",
450            )?;
451            stmt.query_row(params![&canonical_uri], |row| row.get(0)).map_err(|_| {
452                ClmError::storage(
453                    StorageErrorCode::CardNotFound,
454                    format!("Handle '{}' not found for retirement", canonical_uri),
455                )
456            })?
457        };
458
459        let qualified_from = qualified_ref(&tx, &previous_hash)?;
460        let mut payload = serde_json::json!({
461            "kind": TOMBSTONE_KIND,
462            "handle": canonical_uri,
463            "from": qualified_from,
464            "to": serde_json::Value::Null,
465            "author": author.as_str(),
466            "retiredAt": now,
467        });
468        if let Some(reason) = reason {
469            payload["reason"] = serde_json::Value::String(reason.to_string());
470        }
471        let envelope = crate::layer0::codec::canonical_json(&payload).map_err(|e| e.to_string())?;
472        let record = crate::layer0::mcard_record::MCardRecord::create(envelope.as_bytes(), None)
473            .map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e))?;
474
475        tx.execute(
476            "INSERT OR IGNORE INTO card (hash, content, g_time) VALUES (?1, ?2, ?3)",
477            params![&record.hash, &record.content, &record.g_time],
478        )?;
479        tx.execute(
480            "INSERT INTO handle_history (handle, previous_hash, changed_at) VALUES (?1, ?2, ?3)",
481            params![&canonical_uri, &previous_hash, now],
482        )?;
483        // UPDATE, not REPLACE: a replace deletes the row the history row just references.
484        tx.execute(
485            "UPDATE handle_registry SET current_hash = ?1, updated_at = ?2 WHERE handle = ?3",
486            params![&record.hash, now, &canonical_uri],
487        )?;
488
489        tx.commit()?;
490        Ok(())
491    }
492
493    /// Retires an MCard handle, preserving the underlying immutable CAS blob (INV-04).
494    pub fn delete_file(&self, uri: &str) -> Result<()> {
495        self.retire(uri, None, AgentDid::parse(crate::layer0::vocabulary_identities::DID_CLM_AGENT_DEFAULT)?)
496    }
497}
498