Skip to main content

clm_rust_core/layer2/
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::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/// Computes set difference Delta = H_peer \ H_local between two archive manifests.
37#[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/// G-Set CRDT merge: merges missing cards into target database with growth-only append semantics.
57#[cfg(feature = "native")]
58pub fn merge_gset_cards(
59    target_db: &str,
60    clm_root: &str,
61    incoming_cards: &[(String, String, String)], // (hash, content, g_time)
62    sharing_mode: PartialSharingMode,
63) -> Result<usize, String> {
64    let mut count = 0;
65    for (hash, content, g_time) in incoming_cards {
66        // Apply partial sharing filter
67        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// ORC-18: TRANSPARENT. TypeScript's `toJSON()` returns the BARE MAP; the derived Rust serde
99// emitted `{"entries": {...}}`. Two runtimes cannot exchange an event if their wire formats
100// differ, and this is the mesh's own clock.
101#[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    /// Causal ordering: returns true iff every entry in self is <= other and
126    /// at least one entry is strictly less.
127    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        // Also ensure other has entries that self does not (so other is strictly after).
140        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/// The mesh event AS A CARD PAYLOAD — the NORMATIVE field names, so the loader
162/// deserializes directly rather than translating `target` into `pcard_hash`.
163#[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    /// Append a locally generated learning event.
190    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    /// Merge another node's CRDT log into this one.
197    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    /// Detect concurrent events that require sheaf gluing resolution.
209    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// ---------------------------------------------------------------------------
226// DB Persistence (Story 140.4.2) — native only (rusqlite not available on WASM)
227// ---------------------------------------------------------------------------
228
229/// Persist a single learning event to the execution_log DB.
230/// Uses INSERT OR IGNORE for idempotency (duplicate vcard_hash is a no-op).
231#[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    // ORC-18: THE EVENT IS A CARD, on the write side too. `learning_event` was dropped by
238    // ORC-23, so the producer writes what the loader reads. HALF A MIGRATION — a loader that
239    // reads cards and a writer that writes a table — passes the round-trip test and fails the
240    // three tests that exercise the producer. They land together.
241    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    // THE HANDLE IS DERIVED FROM THE CONTENT, not from a counter. A sequence makes a
263    // duplicate persist create a NEW handle, so re-persisting the same event is not
264    // idempotent — the property the original `learning_event` PRIMARY KEY provided. It also
265    // means the handle recorded the CLOCK rather than the event, which ORC-28 forbids.
266    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/// Load learning events from the DB, optionally filtered by timestamp.
282/// Returns events sorted by timestamp (vector-clock order).
283#[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    // ORC-18: THE EVENT IS A CARD. A compatibility VIEW named `learning_event` was
291    // REJECTED — it would recreate the table the Triad forbids, under a new name.
292    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    // ONE closure, reused: two identical closures are two DISTINCT types in Rust.
304    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// ---------------------------------------------------------------------------
330// Sync Report (Story 140.4.3)
331// ---------------------------------------------------------------------------
332
333/// Report from a CRDT sync operation between two nodes.
334#[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/// Sync learning events between local and remote CRDT logs.
342/// Merges remote events into local log and persists all events to DB.
343#[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    // Merge remote into local
352    local.merge(remote);
353
354    let events_appended = local.events.len() - local_count_before;
355
356    // Detect conflicts (concurrent pairs)
357    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    // Persist all local events to DB
371    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/// THE CANONICAL DECLARATION, INCLUDED rather than restated. Six fixtures used to carry
383/// their own copy of the dropped `learning_event` schema; a fixture that RESTATES the schema
384/// can drift from it, and one that INCLUDES it cannot. This is `ORC-27`'s "four copies
385/// byte-identical" applied to the tests — and it removes the duplication rather than
386/// migrating it. Declared at module scope so every test module includes the SAME one.
387#[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/// ORC-18 — THE PLATFORM WRITES, THE KERNEL READS. A DEVELOPMENT-SUBSTRATE test, labelled as
395/// such: it uses the NORMATIVE payload shape `scripts/orc/mesh_node.py` emits, so the two
396/// runtimes' wire formats are exercised against each other rather than against a fixture
397/// only this crate can produce.
398#[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        // exactly the shape scripts/orc/mesh_node.py emits
408        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