use crate::{domain::{MCard, MCardPayload}, layer0::vocabulary::{HANDLE_MCARD, HASH_PREFIX_BLAKE3}};
use crate::error::{ClmError, Result, StorageErrorCode};
use crate::types::{AgentDid, ContentHash};
use rusqlite::{params, Connection};
use serde::{Deserialize, Serialize};
use std::sync::{Arc, Mutex};
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MCardStat {
pub uri: String,
pub hash: ContentHash,
pub size_bytes: usize,
pub created_at: String,
pub updated_at: String,
}
pub use crate::layer2::vfs::{DirectoryManifest, DirectoryManifestEntry};
#[derive(Clone)]
pub struct MCardFileSystem {
pub(crate) conn: Arc<Mutex<Connection>>,
pub(crate) context_prefix: String,
}
const TOMBSTONE_KIND: &str = "TOMBSTONE";
fn head_is_tombstone(conn: &Connection, hash: &str) -> Result<bool> {
let mut stmt = conn.prepare_cached("SELECT content FROM card WHERE hash = ?1")?;
let content: Option<Vec<u8>> = stmt.query_row(params![hash], |row| row.get(0)).ok();
let Some(bytes) = content else {
return Ok(false);
};
if bytes.len() > 4096 {
return Ok(false);
}
Ok(serde_json::from_slice::<serde_json::Value>(&bytes)
.ok()
.and_then(|v| {
v.get("kind")
.and_then(|k| k.as_str())
.map(|k| k == TOMBSTONE_KIND)
})
.unwrap_or(false))
}
fn qualified_ref(conn: &Connection, hash: &str) -> Result<String> {
let mut stmt = conn.prepare_cached("SELECT content, g_time FROM card WHERE hash = ?1")?;
let row: Option<(Vec<u8>, String)> = stmt
.query_row(params![hash], |r| Ok((r.get(0)?, r.get(1)?)))
.ok();
let Some((content, g_time)) = row else {
return Ok(format!("{HASH_PREFIX_BLAKE3}{hash}"));
};
let record = crate::layer0::mcard_record::MCardRecord {
hash: hash.to_string(),
content,
g_time,
};
let algorithm = match crate::layer0::mcard_record::verify_record(&record) {
crate::layer0::mcard_record::RecordVerification::DeclaredOk { algorithm } => algorithm,
crate::layer0::mcard_record::RecordVerification::LegacyClassified { algorithm } => algorithm,
_ => crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3.to_string(),
};
Ok(format!("{algorithm}:{hash}"))
}
impl MCardFileSystem {
pub fn new_in_memory() -> Result<Self> {
let conn = Connection::open_in_memory()?;
Self::init_schema(&conn)?;
Ok(Self {
conn: Arc::new(Mutex::new(conn)),
context_prefix: String::new(),
})
}
pub fn new_in_memory_scoped(prefix: &str) -> Result<Self> {
let mut fs = Self::new_in_memory()?;
fs.context_prefix = prefix.trim_matches('/').to_string();
Ok(fs)
}
pub fn new(conn: Arc<Mutex<Connection>>, context_prefix: &str) -> Self {
Self {
conn,
context_prefix: context_prefix.trim_matches('/').to_string(),
}
}
pub fn with_connection(conn: Arc<Mutex<Connection>>) -> Result<Self> {
{
let locked = conn
.lock()
.map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
Self::init_schema(&locked)?;
}
Ok(Self {
conn,
context_prefix: String::new(),
})
}
pub fn with_prefix(&self, prefix: &str) -> Self {
Self {
conn: self.conn.clone(),
context_prefix: prefix.trim_matches('/').to_string(),
}
}
pub fn context_prefix(&self) -> &str {
&self.context_prefix
}
pub fn canonicalize_uri(&self, path: &str) -> String {
let clean = path.trim_start_matches('/');
if let Some(rest) = clean.strip_prefix(crate::layer0::vocabulary::HANDLE_MCARD) {
let rest_clean = rest.trim_start_matches('/');
if self.context_prefix.is_empty() {
format!("{HANDLE_MCARD}{}", rest_clean)
} else if rest_clean.starts_with(&self.context_prefix) {
format!("{HANDLE_MCARD}{}", rest_clean)
} else {
format!("{HANDLE_MCARD}{}/{}", self.context_prefix, rest_clean)
}
} else if self.context_prefix.is_empty() {
format!("{HANDLE_MCARD}{}", clean)
} else {
format!("{HANDLE_MCARD}{}/{}", self.context_prefix, clean)
}
}
pub fn ephemeral_mount(&self, fiber: &crate::fiber::context::Fiber, prefix: &str) -> Result<Self> {
let scoped_fs = self.with_prefix(prefix);
let prefix_clean = prefix.trim_matches('/').to_string();
let handle_pattern = if prefix_clean.is_empty() {
crate::layer0::vocabulary::HANDLE_MCARD_3.to_string()
} else {
format!("{HANDLE_MCARD}{}/%", prefix_clean)
};
let conn_clone = self.conn.clone();
fiber.register_disposable(move || {
let conn = conn_clone.lock().map_err(|e| e.to_string())?;
conn.execute(
"DELETE FROM handle_history WHERE handle LIKE ?1",
rusqlite::params![&handle_pattern],
)
.map_err(|e| e.to_string())?;
conn.execute(
"DELETE FROM handle_registry WHERE handle LIKE ?1",
rusqlite::params![&handle_pattern],
)
.map_err(|e| e.to_string())?;
Ok(())
});
Ok(scoped_fs)
}
fn init_schema(conn: &Connection) -> Result<()> {
conn.execute_batch(crate::layer0::runtime_contract::SQLITE_DDL_V3_1)?;
Ok(())
}
pub fn write_file(&self, uri: &str, payload: MCardPayload, author: AgentDid) -> Result<MCard> {
let canonical_uri = self.canonicalize_uri(uri);
let now = crate::utils::now_iso8601();
let mut conn = self
.conn
.lock()
.map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
let existing: Option<String> = {
let mut stmt = tx.prepare_cached(
"SELECT current_hash FROM handle_registry WHERE handle = ?1",
)?;
stmt.query_row(params![&canonical_uri], |row| row.get(0))
.ok()
};
let seq = match &existing {
Some(_) => {
let mut count_stmt = tx.prepare_cached(
"SELECT count(*) FROM handle_history WHERE handle = ?1",
)?;
let count: i64 = count_stmt.query_row(params![&canonical_uri], |row| row.get(0))?;
(count as u64) + 2
}
None => 1,
};
let mcard = MCard::new(&canonical_uri, payload, author, seq);
let envelope = crate::layer0::codec::canonical_json(&mcard).map_err(|e| e.to_string())?;
let record = crate::layer0::mcard_record::MCardRecord::create(envelope.as_bytes(), None)
.map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e))?;
let hash_str = record.hash.clone();
{
let mut stmt_card = tx.prepare_cached(
"INSERT OR IGNORE INTO card (hash, content, g_time) VALUES (?1, ?2, ?3)",
)?;
stmt_card.execute(params![&record.hash, &record.content, &record.g_time])?;
}
if let Some(prev_hash) = existing.as_ref().filter(|prev| **prev != hash_str) {
let mut stmt_hist = tx.prepare_cached(
"INSERT INTO handle_history (handle, previous_hash, changed_at) VALUES (?1, ?2, ?3)",
)?;
stmt_hist.execute(params![&canonical_uri, prev_hash, now])?;
}
{
let mut stmt_reg = tx.prepare_cached(
"INSERT OR REPLACE INTO handle_registry (handle, current_hash, updated_at) \
VALUES (?1, ?2, ?3)",
)?;
stmt_reg.execute(params![&canonical_uri, hash_str, now])?;
}
tx.commit()?;
Ok(mcard)
}
pub fn read_file(&self, uri: &str) -> Result<MCard> {
let canonical_uri = self.canonicalize_uri(uri);
let conn = self
.conn
.lock()
.map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
let current_hash: String = {
let mut stmt = conn.prepare_cached(
"SELECT current_hash FROM handle_registry WHERE handle = ?1",
)?;
stmt.query_row(params![&canonical_uri], |row| row.get(0)).map_err(|_| {
ClmError::storage(
StorageErrorCode::CardNotFound,
format!("Handle '{}' not found in MCardFs", canonical_uri),
)
})?
};
if head_is_tombstone(&conn, ¤t_hash)? {
return Err(ClmError::storage(
StorageErrorCode::CardNotFound,
format!("Handle '{}' is retired", canonical_uri),
));
}
let (content, g_time): (Vec<u8>, String) = {
let mut stmt = conn.prepare_cached("SELECT content, g_time FROM card WHERE hash = ?1")?;
stmt.query_row(params![current_hash], |row| Ok((row.get(0)?, row.get(1)?)))
.map_err(|_| {
ClmError::storage(
StorageErrorCode::CorruptedContent,
format!("Card content for hash '{}' not found", current_hash),
)
})?
};
let record = crate::layer0::mcard_record::MCardRecord {
hash: current_hash.clone(),
content: content.clone(),
g_time: g_time.clone(),
};
if !matches!(
crate::layer0::mcard_record::verify_record(&record),
crate::layer0::mcard_record::RecordVerification::DeclaredOk { .. }
) {
return Err(ClmError::storage(
StorageErrorCode::CorruptedContent,
format!("Cryptographic mismatch for handle '{}': stored row does not verify", canonical_uri),
));
}
let mcard: MCard = serde_json::from_slice(&content)?;
Ok(mcard)
}
pub fn exists(&self, uri: &str) -> Result<bool> {
let canonical_uri = self.canonicalize_uri(uri);
let conn = self
.conn
.lock()
.map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
let head: Option<String> = {
let mut stmt = conn.prepare_cached(
"SELECT current_hash FROM handle_registry WHERE handle = ?1",
)?;
stmt.query_row(params![&canonical_uri], |row| row.get(0)).ok()
};
match head {
Some(hash) => Ok(!head_is_tombstone(&conn, &hash)?),
None => Ok(false),
}
}
pub fn stat_file(&self, uri: &str) -> Result<MCardStat> {
let canonical_uri = self.canonicalize_uri(uri);
let conn = self
.conn
.lock()
.map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
let (hash_str, updated_at): (String, String) = {
let mut stmt = conn.prepare_cached(
"SELECT current_hash, updated_at FROM handle_registry WHERE handle = ?1",
)?;
stmt.query_row(params![&canonical_uri], |row| {
Ok((row.get(0)?, row.get(1)?))
})
.map_err(|_| {
ClmError::storage(
StorageErrorCode::CardNotFound,
format!("Handle '{}' not found", canonical_uri),
)
})?
};
if head_is_tombstone(&conn, &hash_str)? {
return Err(ClmError::storage(
StorageErrorCode::CardNotFound,
format!("Handle '{}' is retired", canonical_uri),
));
}
let created_at: String = {
let mut stmt = conn.prepare_cached(
"SELECT changed_at FROM handle_history WHERE handle = ?1 ORDER BY rowid ASC LIMIT 1",
)?;
stmt.query_row(params![&canonical_uri], |row| row.get(0))
.unwrap_or_else(|_| updated_at.clone())
};
let size_bytes: usize = {
let mut stmt = conn.prepare_cached("SELECT length(content) FROM card WHERE hash = ?1")?;
stmt.query_row(params![hash_str], |row| row.get::<_, i64>(0))
.unwrap_or(0) as usize
};
let hash = {
let mut stmt = conn.prepare_cached("SELECT content FROM card WHERE hash = ?1")?;
let body: Vec<u8> = stmt.query_row(params![hash_str], |row| row.get(0)).unwrap_or_default();
match serde_json::from_slice::<MCard>(&body) {
Ok(envelope) => ContentHash::parse(&envelope.hash)?,
Err(_) => ContentHash::parse(&hash_str)?,
}
};
Ok(MCardStat {
uri: canonical_uri,
hash,
size_bytes,
created_at,
updated_at,
})
}
pub fn list_dir(&self, prefix: &str) -> Result<Vec<String>> {
let conn = self
.conn
.lock()
.map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
let canonical_prefix = self.canonicalize_uri(prefix);
let pattern = if canonical_prefix.ends_with('/') {
format!("{}%", canonical_prefix)
} else if canonical_prefix == crate::layer0::vocabulary::HANDLE_MCARD {
crate::layer0::vocabulary::HANDLE_MCARD_3.to_string()
} else {
format!("{}/%", canonical_prefix)
};
let mut stmt = conn.prepare_cached(
"SELECT handle, current_hash FROM handle_registry WHERE handle LIKE ?1 ORDER BY handle ASC",
)?;
let rows = stmt.query_map(params![pattern], |row| {
Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
})?;
let mut handles = Vec::new();
for row in rows {
let (handle, head) = row?;
if !head_is_tombstone(&conn, &head)? {
handles.push(handle);
}
}
Ok(handles)
}
pub fn retire(&self, uri: &str, reason: Option<&str>, author: AgentDid) -> Result<()> {
let canonical_uri = self.canonicalize_uri(uri);
let now = crate::utils::now_iso8601();
let mut conn = self
.conn
.lock()
.map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e.to_string()))?;
let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
let previous_hash: String = {
let mut stmt = tx.prepare_cached(
"SELECT current_hash FROM handle_registry WHERE handle = ?1",
)?;
stmt.query_row(params![&canonical_uri], |row| row.get(0)).map_err(|_| {
ClmError::storage(
StorageErrorCode::CardNotFound,
format!("Handle '{}' not found for retirement", canonical_uri),
)
})?
};
let qualified_from = qualified_ref(&tx, &previous_hash)?;
let mut payload = serde_json::json!({
"kind": TOMBSTONE_KIND,
"handle": canonical_uri,
"from": qualified_from,
"to": serde_json::Value::Null,
"author": author.as_str(),
"retiredAt": now,
});
if let Some(reason) = reason {
payload["reason"] = serde_json::Value::String(reason.to_string());
}
let envelope = crate::layer0::codec::canonical_json(&payload).map_err(|e| e.to_string())?;
let record = crate::layer0::mcard_record::MCardRecord::create(envelope.as_bytes(), None)
.map_err(|e| ClmError::storage(StorageErrorCode::TransactionFailed, e))?;
tx.execute(
"INSERT OR IGNORE INTO card (hash, content, g_time) VALUES (?1, ?2, ?3)",
params![&record.hash, &record.content, &record.g_time],
)?;
tx.execute(
"INSERT INTO handle_history (handle, previous_hash, changed_at) VALUES (?1, ?2, ?3)",
params![&canonical_uri, &previous_hash, now],
)?;
tx.execute(
"UPDATE handle_registry SET current_hash = ?1, updated_at = ?2 WHERE handle = ?3",
params![&record.hash, now, &canonical_uri],
)?;
tx.commit()?;
Ok(())
}
pub fn delete_file(&self, uri: &str) -> Result<()> {
self.retire(uri, None, AgentDid::parse(crate::layer0::vocabulary_identities::DID_CLM_AGENT_DEFAULT)?)
}
}