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 let record = crate::layer0::mcard_record::MCardRecord {
79 hash: hash.clone(), content: content.as_bytes().to_vec(), g_time: g_time.clone(),
80 };
81 crate::layer2::record_store::require_verified(&record).map_err(|e| e.to_string())?;
82 if target_db.contains('/') || target_db.ends_with(".db") {
83 let conn = rusqlite::Connection::open(target_db).map_err(|e| e.to_string())?;
84 conn.execute_batch(crate::layer0::runtime_contract::SQLITE_DDL_V3_1).map_err(|e| e.to_string())?;
85 count += usize::from(crate::layer2::record_store::insert_record(&conn, &record).map_err(|e| e.to_string())?);
86 } else {
87 crate::db::setter_card_batch(target_db, clm_root, hash, content, g_time).map_err(|e| e.to_string())?;
88 count += 1;
89 }
90 }
91 Ok(count)
92}
93
94#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
95#[serde(transparent)]
99pub struct VectorClock {
100 pub entries: HashMap<String, u64>,
101}
102
103impl VectorClock {
104 pub fn new() -> Self {
105 Self::default()
106 }
107
108 pub fn increment(&mut self, node_id: &str) {
109 let counter = self.entries.entry(node_id.to_string()).or_insert(0);
110 *counter += 1;
111 }
112
113 pub fn merge(&self, other: &VectorClock) -> VectorClock {
114 let mut entries = self.entries.clone();
115 for (node, counter) in &other.entries {
116 let current = entries.entry(node.clone()).or_insert(0);
117 *current = (*current).max(*counter);
118 }
119 VectorClock { entries }
120 }
121
122 pub fn happened_before(&self, other: &VectorClock) -> bool {
125 let mut all_le = true;
126 let mut any_lt = false;
127 for (node, self_counter) in &self.entries {
128 let other_counter = other.entries.get(node).copied().unwrap_or(0);
129 if *self_counter > other_counter {
130 all_le = false;
131 }
132 if *self_counter < other_counter {
133 any_lt = true;
134 }
135 }
136 if other.entries.keys().any(|k| !self.entries.contains_key(k)) {
138 any_lt = true;
139 }
140 all_le && any_lt
141 }
142
143 pub fn is_concurrent_with(&self, other: &VectorClock) -> bool {
144 !self.happened_before(other) && !other.happened_before(self)
145 }
146}
147
148#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
149pub struct LearningEvent {
150 pub vcard_hash: String,
151 pub pcard_hash: String,
152 pub marking_delta: Marking,
153 pub agent_did: String,
154 pub timestamp: String,
155 pub vector_clock: VectorClock,
156}
157
158#[derive(Debug, Clone, Serialize, Deserialize)]
161pub struct TelemetryEventPayload {
162 pub vcard_hash: String,
163 pub pcard_hash: String,
164 pub agent_did: String,
165 pub timestamp: String,
166 pub vector_clock: VectorClock,
167 pub marking_delta: Marking,
168}
169
170#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
171pub struct CrdtLog {
172 pub events: Vec<LearningEvent>,
173 pub clock: VectorClock,
174 pub node_id: String,
175}
176
177impl CrdtLog {
178 pub fn new(node_id: &str) -> Self {
179 Self {
180 events: Vec::new(),
181 clock: VectorClock::new(),
182 node_id: node_id.to_string(),
183 }
184 }
185
186 pub fn append(&mut self, mut event: LearningEvent) {
188 self.clock.increment(&self.node_id);
189 event.vector_clock = self.clock.clone();
190 self.events.push(event);
191 }
192
193 pub fn merge(&mut self, other: &CrdtLog) {
195 self.clock = self.clock.merge(&other.clock);
196 for event in &other.events {
197 if !self.events.iter().any(|e| e.vcard_hash == event.vcard_hash) {
198 self.events.push(event.clone());
199 }
200 }
201 self.events
202 .sort_by(|a, b| a.timestamp.cmp(&b.timestamp));
203 }
204
205 pub fn concurrent_pairs(&self) -> Vec<(&LearningEvent, &LearningEvent)> {
207 let mut pairs = Vec::new();
208 for i in 0..self.events.len() {
209 for j in (i + 1)..self.events.len() {
210 if self.events[i]
211 .vector_clock
212 .is_concurrent_with(&self.events[j].vector_clock)
213 {
214 pairs.push((&self.events[i], &self.events[j]));
215 }
216 }
217 }
218 pairs
219 }
220}
221
222#[cfg(any(feature = "native", feature = "db"))]
229pub fn persist_learning_event(
230 conn: &rusqlite::Connection,
231 event: &LearningEvent,
232 node_id: &str,
233) -> Result<(), String> {
234 let payload = TelemetryEventPayload {
239 vcard_hash: event.vcard_hash.clone(),
240 pcard_hash: event.pcard_hash.clone(),
241 agent_did: event.agent_did.clone(),
242 timestamp: event.timestamp.clone(),
243 vector_clock: event.vector_clock.clone(),
244 marking_delta: event.marking_delta.clone(),
245 };
246 let content = serde_json::to_vec(&payload)
247 .map_err(|e| format!("Failed to serialize the event card: {}", e))?;
248 let hash = {
249 use sha2::{Digest, Sha256};
250 let mut h = Sha256::new();
251 h.update(&content);
252 format!("{:x}", h.finalize())
253 };
254 crate::layer2::record_store::insert_new_content(conn, &hash, &content, crate::layer0::vocabulary::HASH_ALGORITHM_SHA256)
255 .map_err(|e| e.to_string())?;
256 let handle = format!("{HANDLE_URN_MCARD_TELEMETRY_EVENT}{}:{}", node_id, &hash[..16]);
261 conn.execute(
262 "INSERT OR REPLACE INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3)",
263 rusqlite::params![handle, hash, event.timestamp],
264 )
265 .map_err(|e| format!("Failed to register the event handle: {}", e))?;
266 conn.execute(
267 "INSERT INTO handle_history (handle, previous_hash, changed_at) VALUES (?1, ?2, ?3)",
268 rusqlite::params![handle, hash, event.timestamp],
269 )
270 .map_err(|e| format!("Failed to record the event history: {}", e))?;
271
272 Ok(())
273}
274
275#[cfg(any(feature = "native", feature = "db"))]
278pub fn load_learning_events(
279 conn: &rusqlite::Connection,
280 since: Option<&str>,
281) -> Result<Vec<LearningEvent>, String> {
282 let mut events = Vec::new();
283
284 let mut stmt = conn.prepare("SELECT current_hash FROM handle_registry WHERE handle LIKE 'urn:mcard:telemetry:event:%'")
285 .map_err(|e| e.to_string())?;
286 let rows = stmt.query_map([], |row| row.get::<_, String>(0)).map_err(|e| e.to_string())?;
287 for row in rows {
288 let hash = row.map_err(|e| e.to_string())?;
289 let record = crate::layer2::record_store::read_record(conn, &hash).map_err(|e| e.to_string())?
290 .ok_or_else(|| "learning event points to missing card".to_string())?;
291 let payload: TelemetryEventPayload = serde_json::from_slice(&record.content).map_err(|e| e.to_string())?;
292 if since.is_some_and(|start| payload.timestamp.as_str() <= start) { continue; }
293 events.push(LearningEvent {
294 vcard_hash: payload.vcard_hash,
295 pcard_hash: payload.pcard_hash,
296 agent_did: payload.agent_did,
297 timestamp: payload.timestamp,
298 vector_clock: payload.vector_clock,
299 marking_delta: payload.marking_delta,
300 });
301 }
302
303 events.sort_by(|a, b| a.timestamp.cmp(&b.timestamp));
304 Ok(events)
305}
306
307#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
313pub struct SyncReport {
314 pub events_merged: usize,
315 pub events_appended: usize,
316 pub conflicts: Vec<String>,
317}
318
319#[cfg(any(feature = "native", feature = "db"))]
322pub fn sync_learning_events(
323 local: &mut CrdtLog,
324 remote: &CrdtLog,
325 conn: &rusqlite::Connection,
326) -> Result<SyncReport, String> {
327 let local_count_before = local.events.len();
328
329 local.merge(remote);
331
332 let events_appended = local.events.len() - local_count_before;
333
334 let conflicts: Vec<String> = local
336 .concurrent_pairs()
337 .iter()
338 .map(|(a, b)| {
339 format!(
340 "concurrent events: {} vs {} (vclock: {:?} vs {:?})",
341 a.vcard_hash, b.vcard_hash, a.vector_clock, b.vector_clock
342 )
343 })
344 .collect();
345
346 let events_merged = remote.events.len();
347
348 for event in &local.events {
350 persist_learning_event(conn, event, &local.node_id)?;
351 }
352
353 Ok(SyncReport {
354 events_merged,
355 events_appended,
356 conflicts,
357 })
358}
359
360#[cfg(test)]
366const CANONICAL_DDL: &str = include_str!("../../../../schema/mcard_schema.sql");
367
368#[cfg(test)]
369#[path = "crdt_tests.rs"]
370mod tests;
371
372#[cfg(all(test, any(feature = "native", feature = "db")))]
377mod orc18_round_trip {
378 use super::*;
379
380 #[test]
381 fn the_platform_writes_and_the_kernel_reads() {
382 let conn = rusqlite::Connection::open_in_memory().unwrap();
383 conn.execute_batch(CANONICAL_DDL).unwrap();
384
385 let body = serde_json::json!({
387 "kind": "MESH_EVENT",
388 "sprint": "ORC-18",
389 "vcard_hash": "v-seal-1",
390 "pcard_hash": "clm",
391 "agent_did": "did:key:z6MkRoot",
392 "timestamp": "2026-10-08T00:00:00Z",
393 "vector_clock": {"root": 3},
394 "marking_delta": {"sealed": ["clm"]},
395 });
396 let content = serde_json::to_vec(&body).unwrap();
397 let hash = {
398 use sha2::{Digest, Sha256};
399 let mut h = Sha256::new();
400 h.update(&content);
401 format!("{:x}", h.finalize())
402 };
403 conn.execute(
404 "INSERT INTO card (hash, content, g_time) VALUES (?1, ?2, ?3)",
405 rusqlite::params![hash, content, "sha256|2026-10-08T00:00:00Z|UTC"],
406 )
407 .unwrap();
408 conn.execute(
409 "INSERT INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3)",
410 rusqlite::params!["urn:mcard:telemetry:event:root:1", hash, "2026-10-08T00:00:00Z"],
411 )
412 .unwrap();
413
414 let events = load_learning_events(&conn, None).expect("the loader must read the tape");
415 assert_eq!(events.len(), 1, "exactly one event");
416 let e = &events[0];
417 assert_eq!(e.agent_did, "did:key:z6MkRoot");
418 assert_eq!(e.pcard_hash, "clm");
419 assert_eq!(e.timestamp, "2026-10-08T00:00:00Z");
420 assert_eq!(
421 serde_json::to_value(&e.vector_clock).unwrap()["root"], 3,
422 "the CLOCK round-trips intact"
423 );
424 }
425}
426