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        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// ORC-18: TRANSPARENT. TypeScript's `toJSON()` returns the BARE MAP; the derived Rust serde
96// emitted `{"entries": {...}}`. Two runtimes cannot exchange an event if their wire formats
97// differ, and this is the mesh's own clock.
98#[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    /// Causal ordering: returns true iff every entry in self is <= other and
123    /// at least one entry is strictly less.
124    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        // Also ensure other has entries that self does not (so other is strictly after).
137        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/// The mesh event AS A CARD PAYLOAD — the NORMATIVE field names, so the loader
159/// deserializes directly rather than translating `target` into `pcard_hash`.
160#[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    /// Append a locally generated learning event.
187    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    /// Merge another node's CRDT log into this one.
194    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    /// Detect concurrent events that require sheaf gluing resolution.
206    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// ---------------------------------------------------------------------------
223// DB Persistence (Story 140.4.2) — native only (rusqlite not available on WASM)
224// ---------------------------------------------------------------------------
225
226/// Persist a single learning event to the execution_log DB.
227/// Uses INSERT OR IGNORE for idempotency (duplicate vcard_hash is a no-op).
228#[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    // ORC-18: THE EVENT IS A CARD, on the write side too. `learning_event` was dropped by
235    // ORC-23, so the producer writes what the loader reads. HALF A MIGRATION — a loader that
236    // reads cards and a writer that writes a table — passes the round-trip test and fails the
237    // three tests that exercise the producer. They land together.
238    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    // THE HANDLE IS DERIVED FROM THE CONTENT, not from a counter. A sequence makes a
257    // duplicate persist create a NEW handle, so re-persisting the same event is not
258    // idempotent — the property the original `learning_event` PRIMARY KEY provided. It also
259    // means the handle recorded the CLOCK rather than the event, which ORC-28 forbids.
260    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/// Load learning events from the DB, optionally filtered by timestamp.
276/// Returns events sorted by timestamp (vector-clock order).
277#[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// ---------------------------------------------------------------------------
308// Sync Report (Story 140.4.3)
309// ---------------------------------------------------------------------------
310
311/// Report from a CRDT sync operation between two nodes.
312#[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/// Sync learning events between local and remote CRDT logs.
320/// Merges remote events into local log and persists all events to DB.
321#[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    // Merge remote into local
330    local.merge(remote);
331
332    let events_appended = local.events.len() - local_count_before;
333
334    // Detect conflicts (concurrent pairs)
335    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    // Persist all local events to DB
349    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/// THE CANONICAL DECLARATION, INCLUDED rather than restated. Six fixtures used to carry
361/// their own copy of the dropped `learning_event` schema; a fixture that RESTATES the schema
362/// can drift from it, and one that INCLUDES it cannot. This is `ORC-27`'s "four copies
363/// byte-identical" applied to the tests — and it removes the duplication rather than
364/// migrating it. Declared at module scope so every test module includes the SAME one.
365#[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/// ORC-18 — THE PLATFORM WRITES, THE KERNEL READS. A DEVELOPMENT-SUBSTRATE test, labelled as
373/// such: it uses the NORMATIVE payload shape `scripts/orc/mesh_node.py` emits, so the two
374/// runtimes' wire formats are exercised against each other rather than against a fixture
375/// only this crate can produce.
376#[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        // exactly the shape scripts/orc/mesh_node.py emits
386        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