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")]
16#[derive(Default)]
17pub enum PartialSharingMode {
18 ContentOnly,
19 ContentAndExecution,
20 #[default]
21 FullSovereign,
22}
23
24
25impl PartialSharingMode {
26 pub fn from_str(s: &str) -> Self {
27 match s {
28 "content_only" => PartialSharingMode::ContentOnly,
29 "content_and_execution" => PartialSharingMode::ContentAndExecution,
30 _ => PartialSharingMode::FullSovereign,
31 }
32 }
33}
34
35#[cfg(feature = "native")]
37pub fn compute_manifest_delta(
38 local_manifest: &ArchiveManifest,
39 peer_manifest: &ArchiveManifest,
40) -> Vec<ArchiveFileEntry> {
41 let local_hashes: std::collections::HashSet<&str> = local_manifest
42 .files
43 .iter()
44 .map(|f| f.sha256.as_str())
45 .collect();
46
47 peer_manifest
48 .files
49 .iter()
50 .filter(|f| !local_hashes.contains(f.sha256.as_str()))
51 .cloned()
52 .collect()
53}
54
55#[cfg(feature = "native")]
57pub fn merge_gset_cards(
58 target_db: &str,
59 clm_root: &str,
60 incoming_cards: &[(String, String, String)], sharing_mode: PartialSharingMode,
62) -> Result<usize, String> {
63 let mut count = 0;
64 for (hash, content, g_time) in incoming_cards {
65 let db_clean = target_db.to_lowercase();
67 if sharing_mode == PartialSharingMode::ContentOnly && !db_clean.contains("content_memory") {
68 continue;
69 }
70 if sharing_mode == PartialSharingMode::ContentAndExecution
71 && !db_clean.contains("content_memory")
72 && !db_clean.contains("execution_log")
73 {
74 continue;
75 }
76
77 if target_db.contains('/') || target_db.ends_with(".db") {
78 let path = std::path::Path::new(target_db);
79 if let Ok(conn) = rusqlite::Connection::open(path) {
80 let _ = conn.execute(
81 "CREATE TABLE IF NOT EXISTS card (hash TEXT PRIMARY KEY, content TEXT, g_time TEXT);",
82 [],
83 );
84 if let Ok(inserted) = conn.execute(
85 "INSERT OR IGNORE INTO card (hash, content, g_time) VALUES (?1, ?2, ?3);",
86 rusqlite::params![hash, content, g_time],
87 ) {
88 count += inserted;
89 }
90 }
91 } else {
92 let _ = crate::db::setter_card_batch(target_db, clm_root, hash, content, g_time);
93 count += 1;
94 }
95 }
96 Ok(count)
97}
98
99#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
100#[serde(transparent)]
104pub struct VectorClock {
105 pub entries: HashMap<String, u64>,
106}
107
108impl VectorClock {
109 pub fn new() -> Self {
110 Self::default()
111 }
112
113 pub fn increment(&mut self, node_id: &str) {
114 let counter = self.entries.entry(node_id.to_string()).or_insert(0);
115 *counter += 1;
116 }
117
118 pub fn merge(&self, other: &VectorClock) -> VectorClock {
119 let mut entries = self.entries.clone();
120 for (node, counter) in &other.entries {
121 let current = entries.entry(node.clone()).or_insert(0);
122 *current = (*current).max(*counter);
123 }
124 VectorClock { entries }
125 }
126
127 pub fn happened_before(&self, other: &VectorClock) -> bool {
130 let mut all_le = true;
131 let mut any_lt = false;
132 for (node, self_counter) in &self.entries {
133 let other_counter = other.entries.get(node).copied().unwrap_or(0);
134 if *self_counter > other_counter {
135 all_le = false;
136 }
137 if *self_counter < other_counter {
138 any_lt = true;
139 }
140 }
141 if other.entries.keys().any(|k| !self.entries.contains_key(k)) {
143 any_lt = true;
144 }
145 all_le && any_lt
146 }
147
148 pub fn is_concurrent_with(&self, other: &VectorClock) -> bool {
149 !self.happened_before(other) && !other.happened_before(self)
150 }
151}
152
153#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
154pub struct LearningEvent {
155 pub vcard_hash: String,
156 pub pcard_hash: String,
157 pub marking_delta: Marking,
158 pub agent_did: String,
159 pub timestamp: String,
160 pub vector_clock: VectorClock,
161}
162
163#[derive(Debug, Clone, Serialize, Deserialize)]
166pub struct TelemetryEventPayload {
167 pub vcard_hash: String,
168 pub pcard_hash: String,
169 pub agent_did: String,
170 pub timestamp: String,
171 pub vector_clock: VectorClock,
172 pub marking_delta: Marking,
173}
174
175#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
176pub struct CrdtLog {
177 pub events: Vec<LearningEvent>,
178 pub clock: VectorClock,
179 pub node_id: String,
180}
181
182impl CrdtLog {
183 pub fn new(node_id: &str) -> Self {
184 Self {
185 events: Vec::new(),
186 clock: VectorClock::new(),
187 node_id: node_id.to_string(),
188 }
189 }
190
191 pub fn append(&mut self, mut event: LearningEvent) {
193 self.clock.increment(&self.node_id);
194 event.vector_clock = self.clock.clone();
195 self.events.push(event);
196 }
197
198 pub fn merge(&mut self, other: &CrdtLog) {
200 self.clock = self.clock.merge(&other.clock);
201 for event in &other.events {
202 if !self.events.iter().any(|e| e.vcard_hash == event.vcard_hash) {
203 self.events.push(event.clone());
204 }
205 }
206 self.events
207 .sort_by(|a, b| a.timestamp.cmp(&b.timestamp));
208 }
209
210 pub fn concurrent_pairs(&self) -> Vec<(&LearningEvent, &LearningEvent)> {
212 let mut pairs = Vec::new();
213 for i in 0..self.events.len() {
214 for j in (i + 1)..self.events.len() {
215 if self.events[i]
216 .vector_clock
217 .is_concurrent_with(&self.events[j].vector_clock)
218 {
219 pairs.push((&self.events[i], &self.events[j]));
220 }
221 }
222 }
223 pairs
224 }
225}
226
227#[cfg(any(feature = "native", feature = "db"))]
234pub fn persist_learning_event(
235 conn: &rusqlite::Connection,
236 event: &LearningEvent,
237 node_id: &str,
238) -> Result<(), String> {
239 let payload = TelemetryEventPayload {
244 vcard_hash: event.vcard_hash.clone(),
245 pcard_hash: event.pcard_hash.clone(),
246 agent_did: event.agent_did.clone(),
247 timestamp: event.timestamp.clone(),
248 vector_clock: event.vector_clock.clone(),
249 marking_delta: event.marking_delta.clone(),
250 };
251 let content = serde_json::to_vec(&payload)
252 .map_err(|e| format!("Failed to serialize the event card: {}", e))?;
253 let hash = {
254 use sha2::{Digest, Sha256};
255 let mut h = Sha256::new();
256 h.update(&content);
257 format!("{:x}", h.finalize())
258 };
259 conn.execute(
260 "INSERT OR IGNORE INTO card (hash, content, g_time) VALUES (?1, ?2, ?3)",
261 rusqlite::params![hash, content, event.timestamp],
262 )
263 .map_err(|e| format!("Failed to persist the event card: {}", e))?;
264 let handle = format!("urn:mcard:telemetry:event:{}:{}", node_id, &hash[..16]);
269 conn.execute(
270 "INSERT OR REPLACE INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3)",
271 rusqlite::params![handle, hash, event.timestamp],
272 )
273 .map_err(|e| format!("Failed to register the event handle: {}", e))?;
274 conn.execute(
275 "INSERT INTO handle_history (handle, previous_hash, changed_at) VALUES (?1, ?2, ?3)",
276 rusqlite::params![handle, hash, event.timestamp],
277 )
278 .map_err(|e| format!("Failed to record the event history: {}", e))?;
279
280 Ok(())
281}
282
283#[cfg(any(feature = "native", feature = "db"))]
286pub fn load_learning_events(
287 conn: &rusqlite::Connection,
288 since: Option<&str>,
289) -> Result<Vec<LearningEvent>, String> {
290 let mut events = Vec::new();
291
292 let sql = if since.is_some() {
295 "SELECT c.content FROM handle_registry r JOIN card c ON c.hash = r.current_hash \
296 WHERE r.handle LIKE 'urn:mcard:telemetry:event:%' AND c.g_time > ?1 \
297 ORDER BY c.g_time ASC"
298 } else {
299 "SELECT c.content FROM handle_registry r JOIN card c ON c.hash = r.current_hash \
300 WHERE r.handle LIKE 'urn:mcard:telemetry:event:%' ORDER BY c.g_time ASC"
301 };
302 let mut stmt = conn
303 .prepare(sql)
304 .map_err(|e| format!("Failed to prepare query: {}", e))?;
305 let map_row = |row: &rusqlite::Row| -> rusqlite::Result<Vec<u8>> { row.get(0) };
307 let rows = if let Some(since_ts) = since {
308 stmt.query_map(rusqlite::params![since_ts], map_row)
309 .map_err(|e| format!("Failed to query learning events: {}", e))?
310 } else {
311 stmt.query_map(rusqlite::params![], map_row)
312 .map_err(|e| format!("Failed to query learning events: {}", e))?
313 };
314 for row in rows {
315 let content = row.map_err(|e| format!("Failed to read row: {}", e))?;
316 let payload: TelemetryEventPayload = serde_json::from_slice(&content)
317 .map_err(|e| format!("Failed to deserialize the event card: {}", e))?;
318 events.push(LearningEvent {
319 vcard_hash: payload.vcard_hash,
320 pcard_hash: payload.pcard_hash,
321 agent_did: payload.agent_did,
322 timestamp: payload.timestamp,
323 vector_clock: payload.vector_clock,
324 marking_delta: payload.marking_delta,
325 });
326 }
327
328 Ok(events)
329}
330
331#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
337pub struct SyncReport {
338 pub events_merged: usize,
339 pub events_appended: usize,
340 pub conflicts: Vec<String>,
341}
342
343#[cfg(any(feature = "native", feature = "db"))]
346pub fn sync_learning_events(
347 local: &mut CrdtLog,
348 remote: &CrdtLog,
349 conn: &rusqlite::Connection,
350) -> Result<SyncReport, String> {
351 let local_count_before = local.events.len();
352
353 local.merge(remote);
355
356 let events_appended = local.events.len() - local_count_before;
357
358 let conflicts: Vec<String> = local
360 .concurrent_pairs()
361 .iter()
362 .map(|(a, b)| {
363 format!(
364 "concurrent events: {} vs {} (vclock: {:?} vs {:?})",
365 a.vcard_hash, b.vcard_hash, a.vector_clock, b.vector_clock
366 )
367 })
368 .collect();
369
370 let events_merged = remote.events.len();
371
372 for event in &local.events {
374 persist_learning_event(conn, event, &local.node_id)?;
375 }
376
377 Ok(SyncReport {
378 events_merged,
379 events_appended,
380 conflicts,
381 })
382}
383
384#[cfg(test)]
390const CANONICAL_DDL: &str = include_str!("../../../schema/mcard_schema.sql");
391
392#[cfg(test)]
393#[path = "crdt_tests.rs"]
394mod tests;
395
396#[cfg(all(test, any(feature = "native", feature = "db")))]
401mod orc18_round_trip {
402 use super::*;
403
404 #[test]
405 fn the_platform_writes_and_the_kernel_reads() {
406 let conn = rusqlite::Connection::open_in_memory().unwrap();
407 conn.execute_batch(CANONICAL_DDL).unwrap();
408
409 let body = serde_json::json!({
411 "kind": "MESH_EVENT",
412 "sprint": "ORC-18",
413 "vcard_hash": "v-seal-1",
414 "pcard_hash": "clm",
415 "agent_did": "did:key:z6MkRoot",
416 "timestamp": "2026-10-08T00:00:00Z",
417 "vector_clock": {"root": 3},
418 "marking_delta": {"sealed": ["clm"]},
419 });
420 let content = serde_json::to_vec(&body).unwrap();
421 let hash = {
422 use sha2::{Digest, Sha256};
423 let mut h = Sha256::new();
424 h.update(&content);
425 format!("{:x}", h.finalize())
426 };
427 conn.execute(
428 "INSERT INTO card (hash, content, g_time) VALUES (?1, ?2, ?3)",
429 rusqlite::params![hash, content, "2026-10-08T00:00:00Z"],
430 )
431 .unwrap();
432 conn.execute(
433 "INSERT INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3)",
434 rusqlite::params!["urn:mcard:telemetry:event:root:1", hash, "2026-10-08T00:00:00Z"],
435 )
436 .unwrap();
437
438 let events = load_learning_events(&conn, None).expect("the loader must read the tape");
439 assert_eq!(events.len(), 1, "exactly one event");
440 let e = &events[0];
441 assert_eq!(e.agent_did, "did:key:z6MkRoot");
442 assert_eq!(e.pcard_hash, "clm");
443 assert_eq!(e.timestamp, "2026-10-08T00:00:00Z");
444 assert_eq!(
445 serde_json::to_value(&e.vector_clock).unwrap()["root"], 3,
446 "the CLOCK round-trips intact"
447 );
448 }
449}
450