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