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        let now = chrono::Utc::now().to_rfc3339();
147        conn.execute(
148            "INSERT OR REPLACE INTO card (hash, content, g_time) VALUES (?1, ?2, ?3);",
149            rusqlite::params![hash, content_str, now],
150        ).map_err(|e| e.to_string())?;
151        Ok(())
152    }
153
154    fn list_hashes(&self) -> Result<Vec<String>, String> {
155        let conn = rusqlite::Connection::open(&self.db_path).map_err(|e| e.to_string())?;
156        let mut stmt = conn.prepare("SELECT hash FROM card;").map_err(|e| e.to_string())?;
157        let rows = stmt.query_map([], |row| row.get(0)).map_err(|e| e.to_string())?;
158        let mut hashes = Vec::new();
159        for h in rows.flatten() {
160            hashes.push(h);
161        }
162        Ok(hashes)
163    }
164
165    fn substrate_uri(&self) -> String {
166        format!("sqlite://{}", self.db_path.display())
167    }
168}
169
170// ── 4. IPFS Substrate Adapter (ipfs://<id_or_path>) ─────────────────────────────
171
172pub struct IpfsSubstrateAdapter {
173    id: String,
174    dir: PathBuf,
175}
176
177impl IpfsSubstrateAdapter {
178    pub fn new(id: &str) -> Result<Self, String> {
179        let dir = if id.contains('/') {
180            PathBuf::from(id)
181        } else {
182            std::env::temp_dir().join(format!("clm_ipfs_{}", id))
183        };
184        let _ = fs::create_dir_all(&dir);
185        Ok(Self {
186            id: id.to_string(),
187            dir,
188        })
189    }
190}
191
192impl SubstrateAdapter for IpfsSubstrateAdapter {
193    fn read_by_hash(&self, hash: &str) -> Result<Vec<u8>, String> {
194        let file_path = self.dir.join(hash);
195        fs::read(&file_path).map_err(|e| format!("Hash {} not found on IPFS node {}: {}", hash, self.id, e))
196    }
197
198    fn write_blob(&self, hash: &str, content: &[u8]) -> Result<(), String> {
199        let file_path = self.dir.join(hash);
200        fs::write(&file_path, content).map_err(|e| format!("Failed to write hash {} to IPFS node {}: {}", hash, self.id, e))
201    }
202
203    fn list_hashes(&self) -> Result<Vec<String>, String> {
204        let mut hashes = Vec::new();
205        if let Ok(entries) = fs::read_dir(&self.dir) {
206            for entry in entries.flatten() {
207                if let Ok(file_type) = entry.file_type()
208                    && file_type.is_file()
209                        && let Some(name) = entry.file_name().to_str() {
210                            hashes.push(name.to_string());
211                        }
212            }
213        }
214        Ok(hashes)
215    }
216
217    fn substrate_uri(&self) -> String {
218        format!("ipfs://{}", self.id)
219    }
220}
221
222// ── 5. NFS Substrate Adapter (nfs://<mount_path>) ─────────────────────────────
223
224pub struct NfsSubstrateAdapter {
225    mount_dir: PathBuf,
226}
227
228impl NfsSubstrateAdapter {
229    pub fn new(mount_path: impl AsRef<Path>) -> Result<Self, String> {
230        let path = mount_path.as_ref().to_path_buf();
231        fs::create_dir_all(&path).map_err(|e| e.to_string())?;
232        Ok(Self { mount_dir: path })
233    }
234}
235
236impl SubstrateAdapter for NfsSubstrateAdapter {
237    fn read_by_hash(&self, hash: &str) -> Result<Vec<u8>, String> {
238        let file_path = self.mount_dir.join(hash);
239        fs::read(&file_path).map_err(|e| format!("Failed to read hash {} from nfs://{:?}: {}", hash, file_path, e))
240    }
241
242    fn write_blob(&self, hash: &str, content: &[u8]) -> Result<(), String> {
243        let file_path = self.mount_dir.join(hash);
244        fs::write(&file_path, content).map_err(|e| format!("Failed to write hash {} to nfs://{:?}: {}", hash, file_path, e))
245    }
246
247    fn list_hashes(&self) -> Result<Vec<String>, String> {
248        let mut hashes = Vec::new();
249        if let Ok(entries) = fs::read_dir(&self.mount_dir) {
250            for entry in entries.flatten() {
251                if let Ok(file_type) = entry.file_type()
252                    && file_type.is_file()
253                        && let Some(name) = entry.file_name().to_str() {
254                            hashes.push(name.to_string());
255                        }
256            }
257        }
258        Ok(hashes)
259    }
260
261    fn substrate_uri(&self) -> String {
262        format!("nfs://{}", self.mount_dir.display())
263    }
264}
265
266// ── 6. S3 Substrate Adapter (s3://<bucket>/<prefix>) ───────────────────────────
267
268pub struct S3SubstrateAdapter {
269    bucket_prefix: PathBuf,
270}
271
272impl S3SubstrateAdapter {
273    pub fn new(bucket_prefix: impl AsRef<Path>) -> Result<Self, String> {
274        let path = bucket_prefix.as_ref().to_path_buf();
275        fs::create_dir_all(&path).map_err(|e| e.to_string())?;
276        Ok(Self { bucket_prefix: path })
277    }
278}
279
280impl SubstrateAdapter for S3SubstrateAdapter {
281    fn read_by_hash(&self, hash: &str) -> Result<Vec<u8>, String> {
282        let file_path = self.bucket_prefix.join(hash);
283        fs::read(&file_path).map_err(|e| format!("Failed to read hash {} from s3://{:?}: {}", hash, file_path, e))
284    }
285
286    fn write_blob(&self, hash: &str, content: &[u8]) -> Result<(), String> {
287        let file_path = self.bucket_prefix.join(hash);
288        fs::write(&file_path, content).map_err(|e| format!("Failed to write hash {} to s3://{:?}: {}", hash, file_path, e))
289    }
290
291    fn list_hashes(&self) -> Result<Vec<String>, String> {
292        let mut hashes = Vec::new();
293        if let Ok(entries) = fs::read_dir(&self.bucket_prefix) {
294            for entry in entries.flatten() {
295                if let Ok(file_type) = entry.file_type()
296                    && file_type.is_file()
297                        && let Some(name) = entry.file_name().to_str() {
298                            hashes.push(name.to_string());
299                        }
300            }
301        }
302        Ok(hashes)
303    }
304
305    fn substrate_uri(&self) -> String {
306        format!("s3://{}", self.bucket_prefix.display())
307    }
308}
309
310// ── Substrate URI Parser & Registry Factory ───────────────────────────────────
311
312pub fn parse_adapter(uri: &str) -> Result<Box<dyn SubstrateAdapter>, String> {
313    if uri.starts_with("memory://") {
314        let id = uri.trim_start_matches("memory://");
315        Ok(Box::new(MemorySubstrateAdapter::new(id)))
316    } else if uri.starts_with("ipfs://") {
317        let id = uri.trim_start_matches("ipfs://");
318        Ok(Box::new(IpfsSubstrateAdapter::new(id)?))
319    } else if uri.starts_with("sqlite://") {
320        let path = uri.trim_start_matches("sqlite://");
321        Ok(Box::new(SqliteSubstrateAdapter::new(path)?))
322    } else if uri.starts_with("file://") {
323        let path = uri.trim_start_matches("file://");
324        Ok(Box::new(FileSubstrateAdapter::new(path)?))
325    } else if uri.starts_with("nfs://") {
326        let path = uri.trim_start_matches("nfs://");
327        Ok(Box::new(NfsSubstrateAdapter::new(path)?))
328    } else if uri.starts_with("s3://") {
329        let path = uri.trim_start_matches("s3://");
330        Ok(Box::new(S3SubstrateAdapter::new(path)?))
331    } else {
332        Err(format!("Unsupported substrate URI scheme: {}", uri))
333    }
334}
335
336/// Migrates an MCard from one substrate to another, asserting hash identity invariance
337/// and issuing a substrate-pinned VCard witness.
338pub fn migrate_mcard(
339    from_adapter: &dyn SubstrateAdapter,
340    to_adapter: &dyn SubstrateAdapter,
341    hash: &str,
342) -> Result<SubstratePinnedVCard, String> {
343    // 1. Read from source substrate
344    let content = from_adapter.read_by_hash(hash)?;
345
346    // 2. Verify source hash identity
347    let read_hash = crate::hash::raw_hash_bytes(&content);
348    if read_hash != hash {
349        return Err(format!("Source hash mismatch during migration: expected {}, got {}", hash, read_hash));
350    }
351
352    // 3. Write to destination substrate
353    to_adapter.write_blob(hash, &content)?;
354
355    // 4. Read back and verify destination hash identity
356    let dst_content = to_adapter.read_by_hash(hash)?;
357    let dst_hash = crate::hash::raw_hash_bytes(&dst_content);
358    if dst_hash != hash {
359        return Err(format!("Destination hash mismatch during migration: expected {}, got {}", hash, dst_hash));
360    }
361
362    // 5. Generate substrate-pinned VCard witness
363    let now = chrono::Utc::now().to_rfc3339();
364    let vcard_raw = format!("pinned:{}:{}:{}:{}", hash, from_adapter.substrate_uri(), to_adapter.substrate_uri(), now);
365    let vcard_hash = crate::hash::raw_hash_bytes(vcard_raw.as_bytes());
366
367    Ok(SubstratePinnedVCard {
368        vcard_hash,
369        content_hash: hash.to_string(),
370        source_uri: from_adapter.substrate_uri(),
371        target_uri: to_adapter.substrate_uri(),
372        timestamp: now,
373    })
374}
375
376// ── Unit Tests ─────────────────────────────────────────────────────────────────
377
378#[cfg(test)]
379mod tests {
380    use super::*;
381
382    #[test]
383    fn test_memory_adapter_roundtrip() {
384        let adapter = MemorySubstrateAdapter::new("test_node");
385        let content = b"hello substrate memory";
386        let hash = crate::hash::raw_hash_bytes(content);
387
388        adapter.write_blob(&hash, content).unwrap();
389        let read_back = adapter.read_by_hash(&hash).unwrap();
390        assert_eq!(read_back, content);
391
392        let list = adapter.list_hashes().unwrap();
393        assert_eq!(list, vec![hash]);
394    }
395
396    #[test]
397    fn test_substrate_migration_hash_invariance() {
398        let tmp_dir = std::env::temp_dir();
399        let file_path = tmp_dir.join("clm_s148_file_sub");
400        let sqlite_path = tmp_dir.join("clm_s148_sub.db");
401        let _ = fs::remove_dir_all(&file_path);
402        let _ = fs::remove_file(&sqlite_path);
403
404        let src = FileSubstrateAdapter::new(&file_path).unwrap();
405        let dst = SqliteSubstrateAdapter::new(&sqlite_path).unwrap();
406
407        let content = b"sovereign mcard payload for substrate migration test";
408        let hash = crate::hash::raw_hash_bytes(content);
409
410        src.write_blob(&hash, content).unwrap();
411
412        let vcard = migrate_mcard(&src, &dst, &hash).unwrap();
413        assert_eq!(vcard.content_hash, hash);
414        assert_eq!(vcard.source_uri, src.substrate_uri());
415        assert_eq!(vcard.target_uri, dst.substrate_uri());
416
417        let dst_read = dst.read_by_hash(&hash).unwrap();
418        assert_eq!(dst_read, content);
419
420        let _ = fs::remove_dir_all(&file_path);
421        let _ = fs::remove_file(&sqlite_path);
422    }
423}