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