Skip to main content

clm_rust_core/
crdt.rs

1//! CRDT-backed learning event sync scaffold for Stage 7.
2//!
3//! Implements vector-clock-ordered `LearningEvent`s and a per-node `CrdtLog`
4//! that can be merged across PKC boundaries. Conflicts are surfaced to the
5//! sheaf gluing engine (`crate::sheaf`) for topological resolution.
6
7use 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/// Computes set difference Delta = H_peer \ H_local between two archive manifests.
36#[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/// G-Set CRDT merge: merges missing cards into target database with growth-only append semantics.
56#[cfg(feature = "native")]
57pub fn merge_gset_cards(
58    target_db: &str,
59    clm_root: &str,
60    incoming_cards: &[(String, String, String)], // (hash, content, g_time)
61    sharing_mode: PartialSharingMode,
62) -> Result<usize, String> {
63    let mut count = 0;
64    for (hash, content, g_time) in incoming_cards {
65        // Apply partial sharing filter
66        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// ORC-18: TRANSPARENT. TypeScript's `toJSON()` returns the BARE MAP; the derived Rust serde
101// emitted `{"entries": {...}}`. Two runtimes cannot exchange an event if their wire formats
102// differ, and this is the mesh's own clock.
103#[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    /// Causal ordering: returns true iff every entry in self is <= other and
128    /// at least one entry is strictly less.
129    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        // Also ensure other has entries that self does not (so other is strictly after).
142        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/// The mesh event AS A CARD PAYLOAD — the NORMATIVE field names, so the loader
164/// deserializes directly rather than translating `target` into `pcard_hash`.
165#[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    /// Append a locally generated learning event.
192    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    /// Merge another node's CRDT log into this one.
199    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    /// Detect concurrent events that require sheaf gluing resolution.
211    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// ---------------------------------------------------------------------------
228// DB Persistence (Story 140.4.2) — native only (rusqlite not available on WASM)
229// ---------------------------------------------------------------------------
230
231/// Persist a single learning event to the execution_log DB.
232/// Uses INSERT OR IGNORE for idempotency (duplicate vcard_hash is a no-op).
233#[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    // ORC-18: THE EVENT IS A CARD, on the write side too. `learning_event` was dropped by
240    // ORC-23, so the producer writes what the loader reads. HALF A MIGRATION — a loader that
241    // reads cards and a writer that writes a table — passes the round-trip test and fails the
242    // three tests that exercise the producer. They land together.
243    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    // THE HANDLE IS DERIVED FROM THE CONTENT, not from a counter. A sequence makes a
265    // duplicate persist create a NEW handle, so re-persisting the same event is not
266    // idempotent — the property the original `learning_event` PRIMARY KEY provided. It also
267    // means the handle recorded the CLOCK rather than the event, which ORC-28 forbids.
268    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/// Load learning events from the DB, optionally filtered by timestamp.
284/// Returns events sorted by timestamp (vector-clock order).
285#[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    // ORC-18: THE EVENT IS A CARD. A compatibility VIEW named `learning_event` was
293    // REJECTED — it would recreate the table the Triad forbids, under a new name.
294    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    // ONE closure, reused: two identical closures are two DISTINCT types in Rust.
306    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// ---------------------------------------------------------------------------
332// Sync Report (Story 140.4.3)
333// ---------------------------------------------------------------------------
334
335/// Report from a CRDT sync operation between two nodes.
336#[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/// Sync learning events between local and remote CRDT logs.
344/// Merges remote events into local log and persists all events to DB.
345#[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    // Merge remote into local
354    local.merge(remote);
355
356    let events_appended = local.events.len() - local_count_before;
357
358    // Detect conflicts (concurrent pairs)
359    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    // Persist all local events to DB
373    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/// THE CANONICAL DECLARATION, INCLUDED rather than restated. Six fixtures used to carry
385/// their own copy of the dropped `learning_event` schema; a fixture that RESTATES the schema
386/// can drift from it, and one that INCLUDES it cannot. This is `ORC-27`'s "four copies
387/// byte-identical" applied to the tests — and it removes the duplication rather than
388/// migrating it. Declared at module scope so every test module includes the SAME one.
389#[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/// ORC-18 — THE PLATFORM WRITES, THE KERNEL READS. A DEVELOPMENT-SUBSTRATE test, labelled as
397/// such: it uses the NORMATIVE payload shape `scripts/orc/mesh_node.py` emits, so the two
398/// runtimes' wire formats are exercised against each other rather than against a fixture
399/// only this crate can produce.
400#[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        // exactly the shape scripts/orc/mesh_node.py emits
410        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