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