1use 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#[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#[derive(Clone)]
31pub struct MCardFileSystem {
32 pub(crate) conn: Arc<Mutex<Connection>>,
33 pub(crate) context_prefix: String,
34}
35
36const TOMBSTONE_KIND: &str = "TOMBSTONE";
38
39fn 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
59fn 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 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 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 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 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 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 pub fn context_prefix(&self) -> &str {
131 &self.context_prefix
132 }
133
134 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 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 fn init_schema(conn: &Connection) -> Result<()> {
185 conn.execute_batch(crate::layer0::runtime_contract::SQLITE_DDL_V3_1)?;
186 Ok(())
187 }
188
189 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 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 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 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 {
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 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 {
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 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 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, ¤t_hash)? {
280 return Err(ClmError::storage(
281 StorageErrorCode::CardNotFound,
282 format!("Handle '{}' is retired", canonical_uri),
283 ));
284 }
285
286 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 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 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 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 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 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 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 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 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