1use crate::sheaf::Marking;
8use serde::{Deserialize, Serialize};
9use std::collections::HashMap;
10
11#[cfg(feature = "native")]
12use crate::archive::{ArchiveManifest, ArchiveFileEntry};
13
14#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
15#[serde(rename_all = "snake_case")]
16pub enum PartialSharingMode {
17 ContentOnly,
18 ContentAndExecution,
19 FullSovereign,
20}
21
22impl Default for PartialSharingMode {
23 fn default() -> Self {
24 PartialSharingMode::FullSovereign
25 }
26}
27
28impl PartialSharingMode {
29 pub fn from_str(s: &str) -> Self {
30 match s {
31 "content_only" => PartialSharingMode::ContentOnly,
32 "content_and_execution" => PartialSharingMode::ContentAndExecution,
33 _ => PartialSharingMode::FullSovereign,
34 }
35 }
36}
37
38#[cfg(feature = "native")]
40pub fn compute_manifest_delta(
41 local_manifest: &ArchiveManifest,
42 peer_manifest: &ArchiveManifest,
43) -> Vec<ArchiveFileEntry> {
44 let local_hashes: std::collections::HashSet<&str> = local_manifest
45 .files
46 .iter()
47 .map(|f| f.sha256.as_str())
48 .collect();
49
50 peer_manifest
51 .files
52 .iter()
53 .filter(|f| !local_hashes.contains(f.sha256.as_str()))
54 .cloned()
55 .collect()
56}
57
58#[cfg(feature = "native")]
60pub fn merge_gset_cards(
61 target_db: &str,
62 clm_root: &str,
63 incoming_cards: &[(String, String, String)], sharing_mode: PartialSharingMode,
65) -> Result<usize, String> {
66 let mut count = 0;
67 for (hash, content, g_time) in incoming_cards {
68 let db_clean = target_db.to_lowercase();
70 if sharing_mode == PartialSharingMode::ContentOnly && !db_clean.contains("content_memory") {
71 continue;
72 }
73 if sharing_mode == PartialSharingMode::ContentAndExecution
74 && !db_clean.contains("content_memory")
75 && !db_clean.contains("execution_log")
76 {
77 continue;
78 }
79
80 if target_db.contains('/') || target_db.ends_with(".db") {
81 let path = std::path::Path::new(target_db);
82 if let Ok(conn) = rusqlite::Connection::open(path) {
83 let _ = conn.execute(
84 "CREATE TABLE IF NOT EXISTS card (hash TEXT PRIMARY KEY, content TEXT, g_time TEXT);",
85 [],
86 );
87 if let Ok(inserted) = conn.execute(
88 "INSERT OR IGNORE INTO card (hash, content, g_time) VALUES (?1, ?2, ?3);",
89 rusqlite::params![hash, content, g_time],
90 ) {
91 count += inserted;
92 }
93 }
94 } else {
95 let _ = crate::db::setter_card_batch(target_db, clm_root, hash, content, g_time);
96 count += 1;
97 }
98 }
99 Ok(count)
100}
101
102#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
103pub struct VectorClock {
104 pub entries: HashMap<String, u64>,
105}
106
107impl VectorClock {
108 pub fn new() -> Self {
109 Self::default()
110 }
111
112 pub fn increment(&mut self, node_id: &str) {
113 let counter = self.entries.entry(node_id.to_string()).or_insert(0);
114 *counter += 1;
115 }
116
117 pub fn merge(&self, other: &VectorClock) -> VectorClock {
118 let mut entries = self.entries.clone();
119 for (node, counter) in &other.entries {
120 let current = entries.entry(node.clone()).or_insert(0);
121 *current = (*current).max(*counter);
122 }
123 VectorClock { entries }
124 }
125
126 pub fn happened_before(&self, other: &VectorClock) -> bool {
129 let mut all_le = true;
130 let mut any_lt = false;
131 for (node, self_counter) in &self.entries {
132 let other_counter = other.entries.get(node).copied().unwrap_or(0);
133 if *self_counter > other_counter {
134 all_le = false;
135 }
136 if *self_counter < other_counter {
137 any_lt = true;
138 }
139 }
140 if other.entries.keys().any(|k| !self.entries.contains_key(k)) {
142 any_lt = true;
143 }
144 all_le && any_lt
145 }
146
147 pub fn is_concurrent_with(&self, other: &VectorClock) -> bool {
148 !self.happened_before(other) && !other.happened_before(self)
149 }
150}
151
152#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
153pub struct LearningEvent {
154 pub vcard_hash: String,
155 pub pcard_hash: String,
156 pub marking_delta: Marking,
157 pub agent_did: String,
158 pub timestamp: String,
159 pub vector_clock: VectorClock,
160}
161
162#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
163pub struct CrdtLog {
164 pub events: Vec<LearningEvent>,
165 pub clock: VectorClock,
166 pub node_id: String,
167}
168
169impl CrdtLog {
170 pub fn new(node_id: &str) -> Self {
171 Self {
172 events: Vec::new(),
173 clock: VectorClock::new(),
174 node_id: node_id.to_string(),
175 }
176 }
177
178 pub fn append(&mut self, mut event: LearningEvent) {
180 self.clock.increment(&self.node_id);
181 event.vector_clock = self.clock.clone();
182 self.events.push(event);
183 }
184
185 pub fn merge(&mut self, other: &CrdtLog) {
187 self.clock = self.clock.merge(&other.clock);
188 for event in &other.events {
189 if !self.events.iter().any(|e| e.vcard_hash == event.vcard_hash) {
190 self.events.push(event.clone());
191 }
192 }
193 self.events
194 .sort_by(|a, b| a.timestamp.cmp(&b.timestamp));
195 }
196
197 pub fn concurrent_pairs(&self) -> Vec<(&LearningEvent, &LearningEvent)> {
199 let mut pairs = Vec::new();
200 for i in 0..self.events.len() {
201 for j in (i + 1)..self.events.len() {
202 if self.events[i]
203 .vector_clock
204 .is_concurrent_with(&self.events[j].vector_clock)
205 {
206 pairs.push((&self.events[i], &self.events[j]));
207 }
208 }
209 }
210 pairs
211 }
212}
213
214#[cfg(any(feature = "native", feature = "db"))]
221pub fn persist_learning_event(
222 conn: &rusqlite::Connection,
223 event: &LearningEvent,
224 node_id: &str,
225) -> Result<(), String> {
226 let vc_json = serde_json::to_string(&event.vector_clock)
227 .map_err(|e| format!("Failed to serialize vector_clock: {}", e))?;
228 let marking_json = serde_json::to_string(&event.marking_delta)
229 .map_err(|e| format!("Failed to serialize marking_delta: {}", e))?;
230
231 conn.execute(
232 "INSERT OR IGNORE INTO learning_event \
233 (vcard_hash, pcard_hash, agent_did, timestamp, vector_clock, marking_delta, node_id, synced_at) \
234 VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
235 rusqlite::params![
236 event.vcard_hash,
237 event.pcard_hash,
238 event.agent_did,
239 event.timestamp,
240 vc_json,
241 marking_json,
242 node_id,
243 chrono::Utc::now().to_rfc3339(),
244 ],
245 ).map_err(|e| format!("Failed to persist learning event: {}", e))?;
246
247 Ok(())
248}
249
250#[cfg(any(feature = "native", feature = "db"))]
253pub fn load_learning_events(
254 conn: &rusqlite::Connection,
255 since: Option<&str>,
256) -> Result<Vec<LearningEvent>, String> {
257 let mut events = Vec::new();
258
259 let sql = if since.is_some() {
260 "SELECT vcard_hash, pcard_hash, agent_did, timestamp, vector_clock, marking_delta \
261 FROM learning_event WHERE timestamp > ?1 ORDER BY timestamp ASC"
262 } else {
263 "SELECT vcard_hash, pcard_hash, agent_did, timestamp, vector_clock, marking_delta \
264 FROM learning_event ORDER BY timestamp ASC"
265 };
266
267 let mut stmt = conn.prepare(sql)
268 .map_err(|e| format!("Failed to prepare query: {}", e))?;
269
270 let map_row = |row: &rusqlite::Row| -> rusqlite::Result<(String, String, String, String, String, String)> {
271 Ok((
272 row.get(0)?,
273 row.get(1)?,
274 row.get(2)?,
275 row.get(3)?,
276 row.get(4)?,
277 row.get(5)?,
278 ))
279 };
280
281 let rows = if let Some(since_ts) = since {
282 stmt.query_map(rusqlite::params![since_ts], map_row)
283 .map_err(|e| format!("Failed to query learning events: {}", e))?
284 } else {
285 stmt.query_map(rusqlite::params![], map_row)
286 .map_err(|e| format!("Failed to query learning events: {}", e))?
287 };
288
289 for row in rows {
290 let (vcard_hash, pcard_hash, agent_did, timestamp, vc_json, marking_json) = row
291 .map_err(|e| format!("Failed to read row: {}", e))?;
292 let vector_clock: VectorClock = serde_json::from_str(&vc_json)
293 .map_err(|e| format!("Failed to deserialize vector_clock: {}", e))?;
294 let marking_delta: Marking = serde_json::from_str(&marking_json)
295 .map_err(|e| format!("Failed to deserialize marking_delta: {}", e))?;
296 events.push(LearningEvent {
297 vcard_hash,
298 pcard_hash,
299 agent_did,
300 timestamp,
301 vector_clock,
302 marking_delta,
303 });
304 }
305
306 Ok(events)
307}
308
309#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
315pub struct SyncReport {
316 pub events_merged: usize,
317 pub events_appended: usize,
318 pub conflicts: Vec<String>,
319}
320
321#[cfg(any(feature = "native", feature = "db"))]
324pub fn sync_learning_events(
325 local: &mut CrdtLog,
326 remote: &CrdtLog,
327 conn: &rusqlite::Connection,
328) -> Result<SyncReport, String> {
329 let local_count_before = local.events.len();
330
331 local.merge(remote);
333
334 let events_appended = local.events.len() - local_count_before;
335
336 let conflicts: Vec<String> = local
338 .concurrent_pairs()
339 .iter()
340 .map(|(a, b)| {
341 format!(
342 "concurrent events: {} vs {} (vclock: {:?} vs {:?})",
343 a.vcard_hash, b.vcard_hash, a.vector_clock, b.vector_clock
344 )
345 })
346 .collect();
347
348 let events_merged = remote.events.len();
349
350 for event in &local.events {
352 persist_learning_event(conn, event, &local.node_id)?;
353 }
354
355 Ok(SyncReport {
356 events_merged,
357 events_appended,
358 conflicts,
359 })
360}
361
362#[cfg(test)]
363mod tests {
364 use super::*;
365
366 #[cfg_attr(not(target_arch = "wasm32"), test)]
367 #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
368 fn test_vector_clock_happened_before() {
369 let mut a = VectorClock::new();
370 a.increment("n1");
371 a.increment("n1");
372 let mut b = a.clone();
373 b.increment("n1");
374 assert!(a.happened_before(&b));
375 assert!(!b.happened_before(&a));
376 }
377
378 #[cfg_attr(not(target_arch = "wasm32"), test)]
379 #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
380 fn test_vector_clock_concurrent() {
381 let mut a = VectorClock::new();
382 a.increment("n1");
383 let mut b = VectorClock::new();
384 b.increment("n2");
385 assert!(a.is_concurrent_with(&b));
386 }
387
388 #[cfg_attr(not(target_arch = "wasm32"), test)]
389 #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
390 fn test_crdt_log_merge_idempotent() {
391 let mut log_a = CrdtLog::new("a");
392 log_a.append(LearningEvent {
393 vcard_hash: "h1".to_string(),
394 pcard_hash: "p1".to_string(),
395 marking_delta: Marking::new(),
396 agent_did: "did:key:a".to_string(),
397 timestamp: "t1".to_string(),
398 vector_clock: VectorClock::new(),
399 });
400 let mut log_b = CrdtLog::new("b");
401 log_b.merge(&log_a);
402 assert_eq!(log_b.events.len(), 1);
403 log_b.merge(&log_a);
404 assert_eq!(log_b.events.len(), 1);
405 }
406
407 #[cfg_attr(not(target_arch = "wasm32"), test)]
408 #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
409 fn test_crdt_log_detects_concurrent_events() {
410 let mut log_a = CrdtLog::new("a");
411 log_a.append(LearningEvent {
412 vcard_hash: "h1".to_string(),
413 pcard_hash: "p1".to_string(),
414 marking_delta: Marking::new(),
415 agent_did: "did:key:a".to_string(),
416 timestamp: "t1".to_string(),
417 vector_clock: VectorClock::new(),
418 });
419 let mut log_b = CrdtLog::new("b");
420 log_b.append(LearningEvent {
421 vcard_hash: "h2".to_string(),
422 pcard_hash: "p2".to_string(),
423 marking_delta: Marking::new(),
424 agent_did: "did:key:b".to_string(),
425 timestamp: "t2".to_string(),
426 vector_clock: VectorClock::new(),
427 });
428 let mut merged = CrdtLog::new("local");
429 merged.merge(&log_a);
430 merged.merge(&log_b);
431 assert_eq!(merged.concurrent_pairs().len(), 1);
432 }
433
434 #[cfg(not(target_arch = "wasm32"))]
435 #[test]
436 fn test_crdt_db_schema_creates_learning_event_table() {
437 let conn = rusqlite::Connection::open_in_memory().unwrap();
438 conn.execute_batch(
439 "CREATE TABLE IF NOT EXISTS learning_event (
440 vcard_hash TEXT PRIMARY KEY,
441 pcard_hash TEXT NOT NULL,
442 agent_did TEXT NOT NULL,
443 timestamp TEXT NOT NULL,
444 vector_clock TEXT NOT NULL,
445 marking_delta TEXT NOT NULL,
446 node_id TEXT NOT NULL,
447 synced_at TEXT
448 );",
449 ).unwrap();
450
451 let table_exists: bool = conn
452 .query_row(
453 "SELECT count(*) FROM sqlite_master WHERE type='table' AND name='learning_event';",
454 [],
455 |row| row.get(0),
456 )
457 .unwrap_or(0) > 0;
458 assert!(table_exists, "learning_event table should exist");
459 }
460
461 #[cfg(any(feature = "native", feature = "db"))]
462 #[test]
463 fn test_crdt_db_persist_and_load_learning_event() {
464 let conn = rusqlite::Connection::open_in_memory().unwrap();
465 conn.execute_batch(
466 "CREATE TABLE IF NOT EXISTS learning_event (
467 vcard_hash TEXT PRIMARY KEY,
468 pcard_hash TEXT NOT NULL,
469 agent_did TEXT NOT NULL,
470 timestamp TEXT NOT NULL,
471 vector_clock TEXT NOT NULL,
472 marking_delta TEXT NOT NULL,
473 node_id TEXT NOT NULL,
474 synced_at TEXT
475 );",
476 ).unwrap();
477
478 let event = LearningEvent {
479 vcard_hash: "vcard-hash-1".to_string(),
480 pcard_hash: "pcard-hash-1".to_string(),
481 marking_delta: Marking::new(),
482 agent_did: "did:key:node-a".to_string(),
483 timestamp: "2026-07-16T10:00:00Z".to_string(),
484 vector_clock: VectorClock::new(),
485 };
486
487 persist_learning_event(&conn, &event, "node-a").unwrap();
488
489 let loaded = load_learning_events(&conn, None).unwrap();
490 assert_eq!(loaded.len(), 1);
491 assert_eq!(loaded[0].vcard_hash, "vcard-hash-1");
492 assert_eq!(loaded[0].pcard_hash, "pcard-hash-1");
493 assert_eq!(loaded[0].agent_did, "did:key:node-a");
494 }
495
496 #[cfg(any(feature = "native", feature = "db"))]
497 #[test]
498 fn test_crdt_db_persist_is_idempotent() {
499 let conn = rusqlite::Connection::open_in_memory().unwrap();
500 conn.execute_batch(
501 "CREATE TABLE IF NOT EXISTS learning_event (
502 vcard_hash TEXT PRIMARY KEY,
503 pcard_hash TEXT NOT NULL,
504 agent_did TEXT NOT NULL,
505 timestamp TEXT NOT NULL,
506 vector_clock TEXT NOT NULL,
507 marking_delta TEXT NOT NULL,
508 node_id TEXT NOT NULL,
509 synced_at TEXT
510 );",
511 ).unwrap();
512
513 let event = LearningEvent {
514 vcard_hash: "vcard-dup".to_string(),
515 pcard_hash: "pcard-1".to_string(),
516 marking_delta: Marking::new(),
517 agent_did: "did:key:a".to_string(),
518 timestamp: "t1".to_string(),
519 vector_clock: VectorClock::new(),
520 };
521
522 persist_learning_event(&conn, &event, "node-a").unwrap();
523 persist_learning_event(&conn, &event, "node-a").unwrap();
524
525 let loaded = load_learning_events(&conn, None).unwrap();
526 assert_eq!(loaded.len(), 1, "duplicate persist should be idempotent");
527 }
528
529 #[cfg(any(feature = "native", feature = "db"))]
530 #[test]
531 fn test_crdt_db_load_returns_vector_clock_order() {
532 let conn = rusqlite::Connection::open_in_memory().unwrap();
533 conn.execute_batch(
534 "CREATE TABLE IF NOT EXISTS learning_event (
535 vcard_hash TEXT PRIMARY KEY,
536 pcard_hash TEXT NOT NULL,
537 agent_did TEXT NOT NULL,
538 timestamp TEXT NOT NULL,
539 vector_clock TEXT NOT NULL,
540 marking_delta TEXT NOT NULL,
541 node_id TEXT NOT NULL,
542 synced_at TEXT
543 );",
544 ).unwrap();
545
546 let event_b = LearningEvent {
548 vcard_hash: "vcard-b".to_string(),
549 pcard_hash: "pcard-b".to_string(),
550 marking_delta: Marking::new(),
551 agent_did: "did:key:b".to_string(),
552 timestamp: "2026-07-16T12:00:00Z".to_string(),
553 vector_clock: VectorClock::new(),
554 };
555 let event_a = LearningEvent {
556 vcard_hash: "vcard-a".to_string(),
557 pcard_hash: "pcard-a".to_string(),
558 marking_delta: Marking::new(),
559 agent_did: "did:key:a".to_string(),
560 timestamp: "2026-07-16T10:00:00Z".to_string(),
561 vector_clock: VectorClock::new(),
562 };
563
564 persist_learning_event(&conn, &event_b, "node-b").unwrap();
565 persist_learning_event(&conn, &event_a, "node-a").unwrap();
566
567 let loaded = load_learning_events(&conn, None).unwrap();
568 assert_eq!(loaded.len(), 2);
569 assert_eq!(loaded[0].vcard_hash, "vcard-a");
571 assert_eq!(loaded[1].vcard_hash, "vcard-b");
572 }
573
574 #[cfg(any(feature = "native", feature = "db"))]
575 #[test]
576 fn test_crdt_sync_merges_and_persists() {
577 let conn = rusqlite::Connection::open_in_memory().unwrap();
578 conn.execute_batch(
579 "CREATE TABLE IF NOT EXISTS learning_event (
580 vcard_hash TEXT PRIMARY KEY,
581 pcard_hash TEXT NOT NULL,
582 agent_did TEXT NOT NULL,
583 timestamp TEXT NOT NULL,
584 vector_clock TEXT NOT NULL,
585 marking_delta TEXT NOT NULL,
586 node_id TEXT NOT NULL,
587 synced_at TEXT
588 );",
589 ).unwrap();
590
591 let mut local = CrdtLog::new("node-local");
592 local.append(LearningEvent {
593 vcard_hash: "vcard-local".to_string(),
594 pcard_hash: "pcard-1".to_string(),
595 marking_delta: Marking::new(),
596 agent_did: "did:key:local".to_string(),
597 timestamp: "t1".to_string(),
598 vector_clock: VectorClock::new(),
599 });
600
601 let mut remote = CrdtLog::new("node-remote");
602 remote.append(LearningEvent {
603 vcard_hash: "vcard-remote".to_string(),
604 pcard_hash: "pcard-2".to_string(),
605 marking_delta: Marking::new(),
606 agent_did: "did:key:remote".to_string(),
607 timestamp: "t2".to_string(),
608 vector_clock: VectorClock::new(),
609 });
610
611 let report = sync_learning_events(&mut local, &remote, &conn).unwrap();
612 assert_eq!(report.events_merged, 1);
613 assert_eq!(report.events_appended, 1);
614 assert_eq!(local.events.len(), 2);
615
616 let loaded = load_learning_events(&conn, None).unwrap();
618 assert_eq!(loaded.len(), 2);
619 }
620
621 #[cfg(any(feature = "native", feature = "db"))]
622 #[test]
623 fn test_crdt_sync_survives_restart() {
624 let tmp_dir = std::env::temp_dir();
626 let db_path = tmp_dir.join("clm_crdt_restart_test.db");
627 let _ = std::fs::remove_file(&db_path);
628
629 {
631 let conn = rusqlite::Connection::open(&db_path).unwrap();
632 conn.execute_batch(
633 "CREATE TABLE IF NOT EXISTS learning_event (
634 vcard_hash TEXT PRIMARY KEY,
635 pcard_hash TEXT NOT NULL,
636 agent_did TEXT NOT NULL,
637 timestamp TEXT NOT NULL,
638 vector_clock TEXT NOT NULL,
639 marking_delta TEXT NOT NULL,
640 node_id TEXT NOT NULL,
641 synced_at TEXT
642 );",
643 ).unwrap();
644
645 let event = LearningEvent {
646 vcard_hash: "vcard-restart".to_string(),
647 pcard_hash: "pcard-1".to_string(),
648 marking_delta: Marking::new(),
649 agent_did: "did:key:restart".to_string(),
650 timestamp: "t-restart".to_string(),
651 vector_clock: VectorClock::new(),
652 };
653 persist_learning_event(&conn, &event, "node-restart").unwrap();
654 }
655
656 {
658 let conn = rusqlite::Connection::open(&db_path).unwrap();
659 let loaded = load_learning_events(&conn, None).unwrap();
660 assert_eq!(loaded.len(), 1);
661 assert_eq!(loaded[0].vcard_hash, "vcard-restart");
662 }
663
664 let _ = std::fs::remove_file(&db_path);
665 }
666
667 #[cfg(feature = "native")]
668 #[test]
669 fn test_manifest_delta_compute() {
670 let manifest_local = ArchiveManifest {
671 archive_id: "archive:local".to_string(),
672 g_time: "t1".to_string(),
673 files: vec![
674 ArchiveFileEntry { path: "f1.txt".to_string(), sha256: "hash1".to_string(), size: 10, mode: 0o644 },
675 ArchiveFileEntry { path: "f2.txt".to_string(), sha256: "hash2".to_string(), size: 20, mode: 0o644 },
676 ],
677 top_level_vcard_hash: None,
678 archiver_did: None,
679 compression: None,
680 };
681
682 let manifest_peer = ArchiveManifest {
683 archive_id: "archive:peer".to_string(),
684 g_time: "t2".to_string(),
685 files: vec![
686 ArchiveFileEntry { path: "f1.txt".to_string(), sha256: "hash1".to_string(), size: 10, mode: 0o644 },
687 ArchiveFileEntry { path: "f3.txt".to_string(), sha256: "hash3".to_string(), size: 30, mode: 0o644 },
688 ],
689 top_level_vcard_hash: None,
690 archiver_did: None,
691 compression: None,
692 };
693
694 let delta = compute_manifest_delta(&manifest_local, &manifest_peer);
695 assert_eq!(delta.len(), 1);
696 assert_eq!(delta[0].path, "f3.txt");
697 assert_eq!(delta[0].sha256, "hash3");
698 }
699}