Skip to main content

clm_rust_core/
substrate.rs

1//! Substrate Transparency Adapters — unifying storage backends (memory, file, sqlite, ipfs, nfs, s3)
2//! under one content-addressed SHA-256 namespace with substrate-pinned VCard provenance.
3
4use serde::{Deserialize, Serialize};
5use std::collections::HashMap;
6use std::fs;
7use std::path::{Path, PathBuf};
8use std::sync::{Arc, RwLock};
9
10/// Core Substrate Adapter trait for reading, writing, and listing content-addressed MCard blobs.
11pub trait SubstrateAdapter: Send + Sync {
12    fn read_by_hash(&self, hash: &str) -> Result<Vec<u8>, String>;
13    fn write_blob(&self, hash: &str, content: &[u8]) -> Result<(), String>;
14    fn list_hashes(&self) -> Result<Vec<String>, String>;
15    fn substrate_uri(&self) -> String;
16}
17
18/// Substrate-pinned VCard recording MCard substrate provenance and migration.
19#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
20pub struct SubstratePinnedVCard {
21    pub vcard_hash: String,
22    pub content_hash: String,
23    pub source_uri: String,
24    pub target_uri: String,
25    pub timestamp: String,
26}
27
28// ── 1. Memory Substrate Adapter (memory://<id>) ────────────────────────────────
29
30#[derive(Clone)]
31pub struct MemorySubstrateAdapter {
32    id: String,
33    storage: Arc<RwLock<HashMap<String, Vec<u8>>>>,
34}
35
36impl MemorySubstrateAdapter {
37    pub fn new(id: &str) -> Self {
38        Self {
39            id: id.to_string(),
40            storage: Arc::new(RwLock::new(HashMap::new())),
41        }
42    }
43}
44
45impl SubstrateAdapter for MemorySubstrateAdapter {
46    fn read_by_hash(&self, hash: &str) -> Result<Vec<u8>, String> {
47        let store = self.storage.read().map_err(|e| e.to_string())?;
48        store.get(hash).cloned().ok_or_else(|| format!("Hash {} not found in memory://{}", hash, self.id))
49    }
50
51    fn write_blob(&self, hash: &str, content: &[u8]) -> Result<(), String> {
52        let mut store = self.storage.write().map_err(|e| e.to_string())?;
53        store.insert(hash.to_string(), content.to_vec());
54        Ok(())
55    }
56
57    fn list_hashes(&self) -> Result<Vec<String>, String> {
58        let store = self.storage.read().map_err(|e| e.to_string())?;
59        Ok(store.keys().cloned().collect())
60    }
61
62    fn substrate_uri(&self) -> String {
63        format!("memory://{}", self.id)
64    }
65}
66
67// ── 2. File Substrate Adapter (file://<dir_path>) ──────────────────────────────
68
69pub struct FileSubstrateAdapter {
70    base_dir: PathBuf,
71}
72
73impl FileSubstrateAdapter {
74    pub fn new(dir_path: impl AsRef<Path>) -> Result<Self, String> {
75        let path = dir_path.as_ref().to_path_buf();
76        fs::create_dir_all(&path).map_err(|e| e.to_string())?;
77        Ok(Self { base_dir: path })
78    }
79}
80
81impl SubstrateAdapter for FileSubstrateAdapter {
82    fn read_by_hash(&self, hash: &str) -> Result<Vec<u8>, String> {
83        let file_path = self.base_dir.join(hash);
84        fs::read(&file_path).map_err(|e| format!("Failed to read hash {} from file://{:?}: {}", hash, file_path, e))
85    }
86
87    fn write_blob(&self, hash: &str, content: &[u8]) -> Result<(), String> {
88        let file_path = self.base_dir.join(hash);
89        fs::write(&file_path, content).map_err(|e| format!("Failed to write hash {} to file://{:?}: {}", hash, file_path, e))
90    }
91
92    fn list_hashes(&self) -> Result<Vec<String>, String> {
93        let mut hashes = Vec::new();
94        if let Ok(entries) = fs::read_dir(&self.base_dir) {
95            for entry in entries.flatten() {
96                if let Ok(file_type) = entry.file_type()
97                    && file_type.is_file()
98                        && let Some(name) = entry.file_name().to_str() {
99                            hashes.push(name.to_string());
100                        }
101            }
102        }
103        Ok(hashes)
104    }
105
106    fn substrate_uri(&self) -> String {
107        format!("file://{}", self.base_dir.display())
108    }
109}
110
111// ── 3. SQLite Substrate Adapter (sqlite://<db_path>) ───────────────────────────
112
113pub struct SqliteSubstrateAdapter {
114    db_path: PathBuf,
115}
116
117impl SqliteSubstrateAdapter {
118    pub fn new(db_path: impl AsRef<Path>) -> Result<Self, String> {
119        let path = db_path.as_ref().to_path_buf();
120        if let Some(parent) = path.parent() {
121            let _ = fs::create_dir_all(parent);
122        }
123        let conn = rusqlite::Connection::open(&path).map_err(|e| e.to_string())?;
124        conn.execute(
125            "CREATE TABLE IF NOT EXISTS card (hash TEXT PRIMARY KEY, content TEXT, g_time TEXT);",
126            [],
127        ).map_err(|e| e.to_string())?;
128        Ok(Self { db_path: path })
129    }
130}
131
132impl SubstrateAdapter for SqliteSubstrateAdapter {
133    fn read_by_hash(&self, hash: &str) -> Result<Vec<u8>, String> {
134        let conn = rusqlite::Connection::open(&self.db_path).map_err(|e| e.to_string())?;
135        let content: String = conn.query_row(
136            "SELECT content FROM card WHERE hash = ?1;",
137            rusqlite::params![hash],
138            |row| row.get(0),
139        ).map_err(|e| format!("Hash {} not found in sqlite://{:?}: {}", hash, self.db_path, e))?;
140        Ok(content.into_bytes())
141    }
142
143    fn write_blob(&self, hash: &str, content: &[u8]) -> Result<(), String> {
144        let conn = rusqlite::Connection::open(&self.db_path).map_err(|e| e.to_string())?;
145        let content_str = String::from_utf8_lossy(content).to_string();
146        // Canonical coordinate naming the algorithm that produced `hash` (charter L2). A bare
147        // ISO timestamp declares no algorithm, so the row could not verify itself.
148        let now = crate::fs_utils::compute_g_time();
149        conn.execute(
150            "INSERT OR REPLACE INTO card (hash, content, g_time) VALUES (?1, ?2, ?3);",
151            rusqlite::params![hash, content_str, now],
152        ).map_err(|e| e.to_string())?;
153        Ok(())
154    }
155
156    fn list_hashes(&self) -> Result<Vec<String>, String> {
157        let conn = rusqlite::Connection::open(&self.db_path).map_err(|e| e.to_string())?;
158        let mut stmt = conn.prepare("SELECT hash FROM card;").map_err(|e| e.to_string())?;
159        let rows = stmt.query_map([], |row| row.get(0)).map_err(|e| e.to_string())?;
160        let mut hashes = Vec::new();
161        for h in rows.flatten() {
162            hashes.push(h);
163        }
164        Ok(hashes)
165    }
166
167    fn substrate_uri(&self) -> String {
168        format!("sqlite://{}", self.db_path.display())
169    }
170}
171
172// ── 4. IPFS Substrate Adapter (ipfs://<id_or_path>) ─────────────────────────────
173
174pub struct IpfsSubstrateAdapter {
175    id: String,
176    dir: PathBuf,
177}
178
179impl IpfsSubstrateAdapter {
180    pub fn new(id: &str) -> Result<Self, String> {
181        let dir = if id.contains('/') {
182            PathBuf::from(id)
183        } else {
184            std::env::temp_dir().join(format!("clm_ipfs_{}", id))
185        };
186        let _ = fs::create_dir_all(&dir);
187        Ok(Self {
188            id: id.to_string(),
189            dir,
190        })
191    }
192}
193
194impl SubstrateAdapter for IpfsSubstrateAdapter {
195    fn read_by_hash(&self, hash: &str) -> Result<Vec<u8>, String> {
196        let file_path = self.dir.join(hash);
197        fs::read(&file_path).map_err(|e| format!("Hash {} not found on IPFS node {}: {}", hash, self.id, e))
198    }
199
200    fn write_blob(&self, hash: &str, content: &[u8]) -> Result<(), String> {
201        let file_path = self.dir.join(hash);
202        fs::write(&file_path, content).map_err(|e| format!("Failed to write hash {} to IPFS node {}: {}", hash, self.id, e))
203    }
204
205    fn list_hashes(&self) -> Result<Vec<String>, String> {
206        let mut hashes = Vec::new();
207        if let Ok(entries) = fs::read_dir(&self.dir) {
208            for entry in entries.flatten() {
209                if let Ok(file_type) = entry.file_type()
210                    && file_type.is_file()
211                        && let Some(name) = entry.file_name().to_str() {
212                            hashes.push(name.to_string());
213                        }
214            }
215        }
216        Ok(hashes)
217    }
218
219    fn substrate_uri(&self) -> String {
220        format!("ipfs://{}", self.id)
221    }
222}
223
224// ── 5. NFS Substrate Adapter (nfs://<mount_path>) ─────────────────────────────
225
226pub struct NfsSubstrateAdapter {
227    mount_dir: PathBuf,
228}
229
230impl NfsSubstrateAdapter {
231    pub fn new(mount_path: impl AsRef<Path>) -> Result<Self, String> {
232        let path = mount_path.as_ref().to_path_buf();
233        fs::create_dir_all(&path).map_err(|e| e.to_string())?;
234        Ok(Self { mount_dir: path })
235    }
236}
237
238impl SubstrateAdapter for NfsSubstrateAdapter {
239    fn read_by_hash(&self, hash: &str) -> Result<Vec<u8>, String> {
240        let file_path = self.mount_dir.join(hash);
241        fs::read(&file_path).map_err(|e| format!("Failed to read hash {} from nfs://{:?}: {}", hash, file_path, e))
242    }
243
244    fn write_blob(&self, hash: &str, content: &[u8]) -> Result<(), String> {
245        let file_path = self.mount_dir.join(hash);
246        fs::write(&file_path, content).map_err(|e| format!("Failed to write hash {} to nfs://{:?}: {}", hash, file_path, e))
247    }
248
249    fn list_hashes(&self) -> Result<Vec<String>, String> {
250        let mut hashes = Vec::new();
251        if let Ok(entries) = fs::read_dir(&self.mount_dir) {
252            for entry in entries.flatten() {
253                if let Ok(file_type) = entry.file_type()
254                    && file_type.is_file()
255                        && let Some(name) = entry.file_name().to_str() {
256                            hashes.push(name.to_string());
257                        }
258            }
259        }
260        Ok(hashes)
261    }
262
263    fn substrate_uri(&self) -> String {
264        format!("nfs://{}", self.mount_dir.display())
265    }
266}
267
268// ── 6. S3 Substrate Adapter (s3://<bucket>/<prefix>) ───────────────────────────
269
270pub struct S3SubstrateAdapter {
271    bucket_prefix: PathBuf,
272}
273
274impl S3SubstrateAdapter {
275    pub fn new(bucket_prefix: impl AsRef<Path>) -> Result<Self, String> {
276        let path = bucket_prefix.as_ref().to_path_buf();
277        fs::create_dir_all(&path).map_err(|e| e.to_string())?;
278        Ok(Self { bucket_prefix: path })
279    }
280}
281
282impl SubstrateAdapter for S3SubstrateAdapter {
283    fn read_by_hash(&self, hash: &str) -> Result<Vec<u8>, String> {
284        let file_path = self.bucket_prefix.join(hash);
285        fs::read(&file_path).map_err(|e| format!("Failed to read hash {} from s3://{:?}: {}", hash, file_path, e))
286    }
287
288    fn write_blob(&self, hash: &str, content: &[u8]) -> Result<(), String> {
289        let file_path = self.bucket_prefix.join(hash);
290        fs::write(&file_path, content).map_err(|e| format!("Failed to write hash {} to s3://{:?}: {}", hash, file_path, e))
291    }
292
293    fn list_hashes(&self) -> Result<Vec<String>, String> {
294        let mut hashes = Vec::new();
295        if let Ok(entries) = fs::read_dir(&self.bucket_prefix) {
296            for entry in entries.flatten() {
297                if let Ok(file_type) = entry.file_type()
298                    && file_type.is_file()
299                        && let Some(name) = entry.file_name().to_str() {
300                            hashes.push(name.to_string());
301                        }
302            }
303        }
304        Ok(hashes)
305    }
306
307    fn substrate_uri(&self) -> String {
308        format!("s3://{}", self.bucket_prefix.display())
309    }
310}
311
312// ── Substrate URI Parser & Registry Factory ───────────────────────────────────
313
314pub fn parse_adapter(uri: &str) -> Result<Box<dyn SubstrateAdapter>, String> {
315    if uri.starts_with("memory://") {
316        let id = uri.trim_start_matches("memory://");
317        Ok(Box::new(MemorySubstrateAdapter::new(id)))
318    } else if uri.starts_with("ipfs://") {
319        let id = uri.trim_start_matches("ipfs://");
320        Ok(Box::new(IpfsSubstrateAdapter::new(id)?))
321    } else if uri.starts_with("sqlite://") {
322        let path = uri.trim_start_matches("sqlite://");
323        Ok(Box::new(SqliteSubstrateAdapter::new(path)?))
324    } else if uri.starts_with("file://") {
325        let path = uri.trim_start_matches("file://");
326        Ok(Box::new(FileSubstrateAdapter::new(path)?))
327    } else if uri.starts_with("nfs://") {
328        let path = uri.trim_start_matches("nfs://");
329        Ok(Box::new(NfsSubstrateAdapter::new(path)?))
330    } else if uri.starts_with("s3://") {
331        let path = uri.trim_start_matches("s3://");
332        Ok(Box::new(S3SubstrateAdapter::new(path)?))
333    } else {
334        Err(format!("Unsupported substrate URI scheme: {}", uri))
335    }
336}
337
338/// Migrates an MCard from one substrate to another, asserting hash identity invariance
339/// and issuing a substrate-pinned VCard witness.
340pub fn migrate_mcard(
341    from_adapter: &dyn SubstrateAdapter,
342    to_adapter: &dyn SubstrateAdapter,
343    hash: &str,
344) -> Result<SubstratePinnedVCard, String> {
345    // 1. Read from source substrate
346    let content = from_adapter.read_by_hash(hash)?;
347
348    // 2. Verify source hash identity
349    let read_hash = crate::hash::raw_hash_bytes(&content);
350    if read_hash != hash {
351        return Err(format!("Source hash mismatch during migration: expected {}, got {}", hash, read_hash));
352    }
353
354    // 3. Write to destination substrate
355    to_adapter.write_blob(hash, &content)?;
356
357    // 4. Read back and verify destination hash identity
358    let dst_content = to_adapter.read_by_hash(hash)?;
359    let dst_hash = crate::hash::raw_hash_bytes(&dst_content);
360    if dst_hash != hash {
361        return Err(format!("Destination hash mismatch during migration: expected {}, got {}", hash, dst_hash));
362    }
363
364    // 5. Generate substrate-pinned VCard witness
365    let now = chrono::Utc::now().to_rfc3339();
366    let vcard_raw = format!("pinned:{}:{}:{}:{}", hash, from_adapter.substrate_uri(), to_adapter.substrate_uri(), now);
367    let vcard_hash = crate::hash::raw_hash_bytes(vcard_raw.as_bytes());
368
369    Ok(SubstratePinnedVCard {
370        vcard_hash,
371        content_hash: hash.to_string(),
372        source_uri: from_adapter.substrate_uri(),
373        target_uri: to_adapter.substrate_uri(),
374        timestamp: now,
375    })
376}
377
378// ── Unit Tests ─────────────────────────────────────────────────────────────────
379
380#[cfg(test)]
381mod tests {
382    use super::*;
383
384    #[test]
385    fn test_memory_adapter_roundtrip() {
386        let adapter = MemorySubstrateAdapter::new("test_node");
387        let content = b"hello substrate memory";
388        let hash = crate::hash::raw_hash_bytes(content);
389
390        adapter.write_blob(&hash, content).unwrap();
391        let read_back = adapter.read_by_hash(&hash).unwrap();
392        assert_eq!(read_back, content);
393
394        let list = adapter.list_hashes().unwrap();
395        assert_eq!(list, vec![hash]);
396    }
397
398    #[test]
399    fn test_substrate_migration_hash_invariance() {
400        let tmp_dir = std::env::temp_dir();
401        let file_path = tmp_dir.join("clm_s148_file_sub");
402        let sqlite_path = tmp_dir.join("clm_s148_sub.db");
403        let _ = fs::remove_dir_all(&file_path);
404        let _ = fs::remove_file(&sqlite_path);
405
406        let src = FileSubstrateAdapter::new(&file_path).unwrap();
407        let dst = SqliteSubstrateAdapter::new(&sqlite_path).unwrap();
408
409        let content = b"sovereign mcard payload for substrate migration test";
410        let hash = crate::hash::raw_hash_bytes(content);
411
412        src.write_blob(&hash, content).unwrap();
413
414        let vcard = migrate_mcard(&src, &dst, &hash).unwrap();
415        assert_eq!(vcard.content_hash, hash);
416        assert_eq!(vcard.source_uri, src.substrate_uri());
417        assert_eq!(vcard.target_uri, dst.substrate_uri());
418
419        let dst_read = dst.read_by_hash(&hash).unwrap();
420        assert_eq!(dst_read, content);
421
422        let _ = fs::remove_dir_all(&file_path);
423        let _ = fs::remove_file(&sqlite_path);
424    }
425}