Skip to main content

clm_rust_core/layer4/
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 crate::layer0::vocabulary::{HANDLE_FILE};
5use serde::{Deserialize, Serialize};
6use std::collections::HashMap;
7use std::fs;
8use std::path::{Path, PathBuf};
9use std::sync::{Arc, RwLock};
10
11/// Core Substrate Adapter trait for reading, writing, and listing content-addressed MCard blobs.
12pub trait SubstrateAdapter: Send + Sync {
13    fn read_by_hash(&self, hash: &str) -> Result<Vec<u8>, String>;
14    fn write_blob(&self, hash: &str, content: &[u8]) -> Result<(), String>;
15    fn list_hashes(&self) -> Result<Vec<String>, String>;
16    fn substrate_uri(&self) -> String;
17}
18
19/// Substrate-pinned VCard recording MCard substrate provenance and migration.
20#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
21pub struct SubstratePinnedVCard {
22    pub vcard_hash: String,
23    pub content_hash: String,
24    pub source_uri: String,
25    pub target_uri: String,
26    pub timestamp: String,
27}
28
29// ── 1. Memory Substrate Adapter (memory://<id>) ────────────────────────────────
30
31#[derive(Clone)]
32pub struct MemorySubstrateAdapter {
33    id: String,
34    storage: Arc<RwLock<HashMap<String, Vec<u8>>>>,
35}
36
37impl MemorySubstrateAdapter {
38    pub fn new(id: &str) -> Self {
39        Self {
40            id: id.to_string(),
41            storage: Arc::new(RwLock::new(HashMap::new())),
42        }
43    }
44}
45
46impl SubstrateAdapter for MemorySubstrateAdapter {
47    fn read_by_hash(&self, hash: &str) -> Result<Vec<u8>, String> {
48        let store = self.storage.read().map_err(|e| e.to_string())?;
49        store.get(hash).cloned().ok_or_else(|| format!("Hash {} not found in memory://{}", hash, self.id))
50    }
51
52    fn write_blob(&self, hash: &str, content: &[u8]) -> Result<(), String> {
53        let mut store = self.storage.write().map_err(|e| e.to_string())?;
54        store.insert(hash.to_string(), content.to_vec());
55        Ok(())
56    }
57
58    fn list_hashes(&self) -> Result<Vec<String>, String> {
59        let store = self.storage.read().map_err(|e| e.to_string())?;
60        Ok(store.keys().cloned().collect())
61    }
62
63    fn substrate_uri(&self) -> String {
64        format!("memory://{}", self.id)
65    }
66}
67
68// ── 2. File Substrate Adapter (file://<dir_path>) ──────────────────────────────
69
70pub struct FileSubstrateAdapter {
71    base_dir: PathBuf,
72}
73
74impl FileSubstrateAdapter {
75    pub fn new(dir_path: impl AsRef<Path>) -> Result<Self, String> {
76        let path = dir_path.as_ref().to_path_buf();
77        fs::create_dir_all(&path).map_err(|e| e.to_string())?;
78        Ok(Self { base_dir: path })
79    }
80}
81
82impl SubstrateAdapter for FileSubstrateAdapter {
83    fn read_by_hash(&self, hash: &str) -> Result<Vec<u8>, String> {
84        let file_path = self.base_dir.join(hash);
85        fs::read(&file_path).map_err(|e| format!("Failed to read hash {} from file://{:?}: {}", hash, file_path, e))
86    }
87
88    fn write_blob(&self, hash: &str, content: &[u8]) -> Result<(), String> {
89        let file_path = self.base_dir.join(hash);
90        fs::write(&file_path, content).map_err(|e| format!("Failed to write hash {} to file://{:?}: {}", hash, file_path, e))
91    }
92
93    fn list_hashes(&self) -> Result<Vec<String>, String> {
94        let mut hashes = Vec::new();
95        if let Ok(entries) = fs::read_dir(&self.base_dir) {
96            for entry in entries.flatten() {
97                if let Ok(file_type) = entry.file_type()
98                    && file_type.is_file()
99                        && let Some(name) = entry.file_name().to_str() {
100                            hashes.push(name.to_string());
101                        }
102            }
103        }
104        Ok(hashes)
105    }
106
107    fn substrate_uri(&self) -> String {
108        format!("{HANDLE_FILE}{}", self.base_dir.display())
109    }
110}
111
112// ── 3. SQLite Substrate Adapter (sqlite://<db_path>) ───────────────────────────
113
114pub struct SqliteSubstrateAdapter {
115    db_path: PathBuf,
116}
117
118impl SqliteSubstrateAdapter {
119    pub fn new(db_path: impl AsRef<Path>) -> Result<Self, String> {
120        let path = db_path.as_ref().to_path_buf();
121        if let Some(parent) = path.parent() {
122            let _ = fs::create_dir_all(parent);
123        }
124        let conn = rusqlite::Connection::open(&path).map_err(|e| e.to_string())?;
125        conn.execute_batch(crate::layer0::runtime_contract::SQLITE_DDL_V3_1).map_err(|e| e.to_string())?;
126        Ok(Self { db_path: path })
127    }
128}
129
130impl SubstrateAdapter for SqliteSubstrateAdapter {
131    fn read_by_hash(&self, hash: &str) -> Result<Vec<u8>, String> {
132        let conn = rusqlite::Connection::open(&self.db_path).map_err(|e| e.to_string())?;
133        let content: String = conn.query_row(
134            "SELECT content FROM card WHERE hash = ?1;",
135            rusqlite::params![hash],
136            |row| row.get(0),
137        ).map_err(|e| format!("Hash {} not found in sqlite://{:?}: {}", hash, self.db_path, e))?;
138        Ok(content.into_bytes())
139    }
140
141    fn write_blob(&self, hash: &str, content: &[u8]) -> Result<(), String> {
142        let conn = rusqlite::Connection::open(&self.db_path).map_err(|e| e.to_string())?;
143        let content_str = String::from_utf8_lossy(content).to_string();
144        // Canonical coordinate naming the algorithm that produced `hash` (charter L2). A bare
145        // ISO timestamp declares no algorithm, so the row could not verify itself.
146        let now = crate::fs_utils::compute_g_time();
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(crate::layer0::vocabulary::URI_SCHEME_MEMORY) {
314        let id = uri.trim_start_matches(crate::layer0::vocabulary::URI_SCHEME_MEMORY);
315        Ok(Box::new(MemorySubstrateAdapter::new(id)))
316    } else if uri.starts_with(crate::layer0::vocabulary::URI_SCHEME_IPFS) {
317        let id = uri.trim_start_matches(crate::layer0::vocabulary::URI_SCHEME_IPFS);
318        Ok(Box::new(IpfsSubstrateAdapter::new(id)?))
319    } else if uri.starts_with(crate::layer0::vocabulary::URI_SCHEME_SQLITE) {
320        let path = uri.trim_start_matches(crate::layer0::vocabulary::URI_SCHEME_SQLITE);
321        Ok(Box::new(SqliteSubstrateAdapter::new(path)?))
322    } else if uri.starts_with(crate::layer0::vocabulary::HANDLE_FILE) {
323        let path = uri.trim_start_matches(crate::layer0::vocabulary::HANDLE_FILE);
324        Ok(Box::new(FileSubstrateAdapter::new(path)?))
325    } else if uri.starts_with(crate::layer0::vocabulary::URI_SCHEME_NFS) {
326        let path = uri.trim_start_matches(crate::layer0::vocabulary::URI_SCHEME_NFS);
327        Ok(Box::new(NfsSubstrateAdapter::new(path)?))
328    } else if uri.starts_with(crate::layer0::vocabulary::URI_SCHEME_S3) {
329        let path = uri.trim_start_matches(crate::layer0::vocabulary::URI_SCHEME_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}