clm-kernel 0.0.12

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
//! CRDT-backed learning event sync scaffold for Stage 7.
//!
//! Implements vector-clock-ordered `LearningEvent`s and a per-node `CrdtLog`
//! that can be merged across PKC boundaries. Conflicts are surfaced to the
//! sheaf gluing engine (`crate::sheaf`) for topological resolution.

use crate::sheaf::Marking;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;

#[cfg(feature = "native")]
use crate::archive::{ArchiveManifest, ArchiveFileEntry};

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[derive(Default)]
pub enum PartialSharingMode {
    ContentOnly,
    ContentAndExecution,
    #[default]
    FullSovereign,
}


impl PartialSharingMode {
    pub fn from_str(s: &str) -> Self {
        match s {
            "content_only" => PartialSharingMode::ContentOnly,
            "content_and_execution" => PartialSharingMode::ContentAndExecution,
            _ => PartialSharingMode::FullSovereign,
        }
    }
}

/// Computes set difference Delta = H_peer \ H_local between two archive manifests.
#[cfg(feature = "native")]
pub fn compute_manifest_delta(
    local_manifest: &ArchiveManifest,
    peer_manifest: &ArchiveManifest,
) -> Vec<ArchiveFileEntry> {
    let local_hashes: std::collections::HashSet<&str> = local_manifest
        .files
        .iter()
        .map(|f| f.sha256.as_str())
        .collect();

    peer_manifest
        .files
        .iter()
        .filter(|f| !local_hashes.contains(f.sha256.as_str()))
        .cloned()
        .collect()
}

/// G-Set CRDT merge: merges missing cards into target database with growth-only append semantics.
#[cfg(feature = "native")]
pub fn merge_gset_cards(
    target_db: &str,
    clm_root: &str,
    incoming_cards: &[(String, String, String)], // (hash, content, g_time)
    sharing_mode: PartialSharingMode,
) -> Result<usize, String> {
    let mut count = 0;
    for (hash, content, g_time) in incoming_cards {
        // Apply partial sharing filter
        let db_clean = target_db.to_lowercase();
        if sharing_mode == PartialSharingMode::ContentOnly && !db_clean.contains("content_memory") {
            continue;
        }
        if sharing_mode == PartialSharingMode::ContentAndExecution
            && !db_clean.contains("content_memory")
            && !db_clean.contains("execution_log")
        {
            continue;
        }

        if target_db.contains('/') || target_db.ends_with(".db") {
            let path = std::path::Path::new(target_db);
            if let Ok(conn) = rusqlite::Connection::open(path) {
                let _ = conn.execute(
                    "CREATE TABLE IF NOT EXISTS card (hash TEXT PRIMARY KEY, content TEXT, g_time TEXT);",
                    [],
                );
                if let Ok(inserted) = conn.execute(
                    "INSERT OR IGNORE INTO card (hash, content, g_time) VALUES (?1, ?2, ?3);",
                    rusqlite::params![hash, content, g_time],
                ) {
                    count += inserted;
                }
            }
        } else {
            let _ = crate::db::setter_card_batch(target_db, clm_root, hash, content, g_time);
            count += 1;
        }
    }
    Ok(count)
}

#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
// ORC-18: TRANSPARENT. TypeScript's `toJSON()` returns the BARE MAP; the derived Rust serde
// emitted `{"entries": {...}}`. Two runtimes cannot exchange an event if their wire formats
// differ, and this is the mesh's own clock.
#[serde(transparent)]
pub struct VectorClock {
    pub entries: HashMap<String, u64>,
}

impl VectorClock {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn increment(&mut self, node_id: &str) {
        let counter = self.entries.entry(node_id.to_string()).or_insert(0);
        *counter += 1;
    }

    pub fn merge(&self, other: &VectorClock) -> VectorClock {
        let mut entries = self.entries.clone();
        for (node, counter) in &other.entries {
            let current = entries.entry(node.clone()).or_insert(0);
            *current = (*current).max(*counter);
        }
        VectorClock { entries }
    }

    /// Causal ordering: returns true iff every entry in self is <= other and
    /// at least one entry is strictly less.
    pub fn happened_before(&self, other: &VectorClock) -> bool {
        let mut all_le = true;
        let mut any_lt = false;
        for (node, self_counter) in &self.entries {
            let other_counter = other.entries.get(node).copied().unwrap_or(0);
            if *self_counter > other_counter {
                all_le = false;
            }
            if *self_counter < other_counter {
                any_lt = true;
            }
        }
        // Also ensure other has entries that self does not (so other is strictly after).
        if other.entries.keys().any(|k| !self.entries.contains_key(k)) {
            any_lt = true;
        }
        all_le && any_lt
    }

    pub fn is_concurrent_with(&self, other: &VectorClock) -> bool {
        !self.happened_before(other) && !other.happened_before(self)
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct LearningEvent {
    pub vcard_hash: String,
    pub pcard_hash: String,
    pub marking_delta: Marking,
    pub agent_did: String,
    pub timestamp: String,
    pub vector_clock: VectorClock,
}

/// The mesh event AS A CARD PAYLOAD — the NORMATIVE field names, so the loader
/// deserializes directly rather than translating `target` into `pcard_hash`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TelemetryEventPayload {
    pub vcard_hash: String,
    pub pcard_hash: String,
    pub agent_did: String,
    pub timestamp: String,
    pub vector_clock: VectorClock,
    pub marking_delta: Marking,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CrdtLog {
    pub events: Vec<LearningEvent>,
    pub clock: VectorClock,
    pub node_id: String,
}

impl CrdtLog {
    pub fn new(node_id: &str) -> Self {
        Self {
            events: Vec::new(),
            clock: VectorClock::new(),
            node_id: node_id.to_string(),
        }
    }

    /// Append a locally generated learning event.
    pub fn append(&mut self, mut event: LearningEvent) {
        self.clock.increment(&self.node_id);
        event.vector_clock = self.clock.clone();
        self.events.push(event);
    }

    /// Merge another node's CRDT log into this one.
    pub fn merge(&mut self, other: &CrdtLog) {
        self.clock = self.clock.merge(&other.clock);
        for event in &other.events {
            if !self.events.iter().any(|e| e.vcard_hash == event.vcard_hash) {
                self.events.push(event.clone());
            }
        }
        self.events
            .sort_by(|a, b| a.timestamp.cmp(&b.timestamp));
    }

    /// Detect concurrent events that require sheaf gluing resolution.
    pub fn concurrent_pairs(&self) -> Vec<(&LearningEvent, &LearningEvent)> {
        let mut pairs = Vec::new();
        for i in 0..self.events.len() {
            for j in (i + 1)..self.events.len() {
                if self.events[i]
                    .vector_clock
                    .is_concurrent_with(&self.events[j].vector_clock)
                {
                    pairs.push((&self.events[i], &self.events[j]));
                }
            }
        }
        pairs
    }
}

// ---------------------------------------------------------------------------
// DB Persistence (Story 140.4.2) — native only (rusqlite not available on WASM)
// ---------------------------------------------------------------------------

/// Persist a single learning event to the execution_log DB.
/// Uses INSERT OR IGNORE for idempotency (duplicate vcard_hash is a no-op).
#[cfg(any(feature = "native", feature = "db"))]
pub fn persist_learning_event(
    conn: &rusqlite::Connection,
    event: &LearningEvent,
    node_id: &str,
) -> Result<(), String> {
    // ORC-18: THE EVENT IS A CARD, on the write side too. `learning_event` was dropped by
    // ORC-23, so the producer writes what the loader reads. HALF A MIGRATION — a loader that
    // reads cards and a writer that writes a table — passes the round-trip test and fails the
    // three tests that exercise the producer. They land together.
    let payload = TelemetryEventPayload {
        vcard_hash: event.vcard_hash.clone(),
        pcard_hash: event.pcard_hash.clone(),
        agent_did: event.agent_did.clone(),
        timestamp: event.timestamp.clone(),
        vector_clock: event.vector_clock.clone(),
        marking_delta: event.marking_delta.clone(),
    };
    let content = serde_json::to_vec(&payload)
        .map_err(|e| format!("Failed to serialize the event card: {}", e))?;
    let hash = {
        use sha2::{Digest, Sha256};
        let mut h = Sha256::new();
        h.update(&content);
        format!("{:x}", h.finalize())
    };
    conn.execute(
        "INSERT OR IGNORE INTO card (hash, content, g_time) VALUES (?1, ?2, ?3)",
        rusqlite::params![hash, content, event.timestamp],
    )
    .map_err(|e| format!("Failed to persist the event card: {}", e))?;
    // THE HANDLE IS DERIVED FROM THE CONTENT, not from a counter. A sequence makes a
    // duplicate persist create a NEW handle, so re-persisting the same event is not
    // idempotent — the property the original `learning_event` PRIMARY KEY provided. It also
    // means the handle recorded the CLOCK rather than the event, which ORC-28 forbids.
    let handle = format!("urn:mcard:telemetry:event:{}:{}", node_id, &hash[..16]);
    conn.execute(
        "INSERT OR REPLACE INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3)",
        rusqlite::params![handle, hash, event.timestamp],
    )
    .map_err(|e| format!("Failed to register the event handle: {}", e))?;
    conn.execute(
        "INSERT INTO handle_history (handle, previous_hash, changed_at) VALUES (?1, ?2, ?3)",
        rusqlite::params![handle, hash, event.timestamp],
    )
    .map_err(|e| format!("Failed to record the event history: {}", e))?;

    Ok(())
}

/// Load learning events from the DB, optionally filtered by timestamp.
/// Returns events sorted by timestamp (vector-clock order).
#[cfg(any(feature = "native", feature = "db"))]
pub fn load_learning_events(
    conn: &rusqlite::Connection,
    since: Option<&str>,
) -> Result<Vec<LearningEvent>, String> {
    let mut events = Vec::new();

    // ORC-18: THE EVENT IS A CARD. A compatibility VIEW named `learning_event` was
    // REJECTED — it would recreate the table the Triad forbids, under a new name.
    let sql = if since.is_some() {
        "SELECT c.content FROM handle_registry r JOIN card c ON c.hash = r.current_hash \
         WHERE r.handle LIKE 'urn:mcard:telemetry:event:%' AND c.g_time > ?1 \
         ORDER BY c.g_time ASC"
    } else {
        "SELECT c.content FROM handle_registry r JOIN card c ON c.hash = r.current_hash \
         WHERE r.handle LIKE 'urn:mcard:telemetry:event:%' ORDER BY c.g_time ASC"
    };
    let mut stmt = conn
        .prepare(sql)
        .map_err(|e| format!("Failed to prepare query: {}", e))?;
    // ONE closure, reused: two identical closures are two DISTINCT types in Rust.
    let map_row = |row: &rusqlite::Row| -> rusqlite::Result<Vec<u8>> { row.get(0) };
    let rows = if let Some(since_ts) = since {
        stmt.query_map(rusqlite::params![since_ts], map_row)
            .map_err(|e| format!("Failed to query learning events: {}", e))?
    } else {
        stmt.query_map(rusqlite::params![], map_row)
            .map_err(|e| format!("Failed to query learning events: {}", e))?
    };
    for row in rows {
        let content = row.map_err(|e| format!("Failed to read row: {}", e))?;
        let payload: TelemetryEventPayload = serde_json::from_slice(&content)
            .map_err(|e| format!("Failed to deserialize the event card: {}", e))?;
        events.push(LearningEvent {
            vcard_hash: payload.vcard_hash,
            pcard_hash: payload.pcard_hash,
            agent_did: payload.agent_did,
            timestamp: payload.timestamp,
            vector_clock: payload.vector_clock,
            marking_delta: payload.marking_delta,
        });
    }

    Ok(events)
}

// ---------------------------------------------------------------------------
// Sync Report (Story 140.4.3)
// ---------------------------------------------------------------------------

/// Report from a CRDT sync operation between two nodes.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SyncReport {
    pub events_merged: usize,
    pub events_appended: usize,
    pub conflicts: Vec<String>,
}

/// Sync learning events between local and remote CRDT logs.
/// Merges remote events into local log and persists all events to DB.
#[cfg(any(feature = "native", feature = "db"))]
pub fn sync_learning_events(
    local: &mut CrdtLog,
    remote: &CrdtLog,
    conn: &rusqlite::Connection,
) -> Result<SyncReport, String> {
    let local_count_before = local.events.len();

    // Merge remote into local
    local.merge(remote);

    let events_appended = local.events.len() - local_count_before;

    // Detect conflicts (concurrent pairs)
    let conflicts: Vec<String> = local
        .concurrent_pairs()
        .iter()
        .map(|(a, b)| {
            format!(
                "concurrent events: {} vs {} (vclock: {:?} vs {:?})",
                a.vcard_hash, b.vcard_hash, a.vector_clock, b.vector_clock
            )
        })
        .collect();

    let events_merged = remote.events.len();

    // Persist all local events to DB
    for event in &local.events {
        persist_learning_event(conn, event, &local.node_id)?;
    }

    Ok(SyncReport {
        events_merged,
        events_appended,
        conflicts,
    })
}

/// THE CANONICAL DECLARATION, INCLUDED rather than restated. Six fixtures used to carry
/// their own copy of the dropped `learning_event` schema; a fixture that RESTATES the schema
/// can drift from it, and one that INCLUDES it cannot. This is `ORC-27`'s "four copies
/// byte-identical" applied to the tests — and it removes the duplication rather than
/// migrating it. Declared at module scope so every test module includes the SAME one.
#[cfg(test)]
const CANONICAL_DDL: &str = include_str!("../../../schema/mcard_schema.sql");

#[cfg(test)]
#[path = "crdt_tests.rs"]
mod tests;

/// ORC-18 — THE PLATFORM WRITES, THE KERNEL READS. A DEVELOPMENT-SUBSTRATE test, labelled as
/// such: it uses the NORMATIVE payload shape `scripts/orc/mesh_node.py` emits, so the two
/// runtimes' wire formats are exercised against each other rather than against a fixture
/// only this crate can produce.
#[cfg(all(test, any(feature = "native", feature = "db")))]
mod orc18_round_trip {
    use super::*;

    #[test]
    fn the_platform_writes_and_the_kernel_reads() {
        let conn = rusqlite::Connection::open_in_memory().unwrap();
        conn.execute_batch(CANONICAL_DDL).unwrap();

        // exactly the shape scripts/orc/mesh_node.py emits
        let body = serde_json::json!({
            "kind": "MESH_EVENT",
            "sprint": "ORC-18",
            "vcard_hash": "v-seal-1",
            "pcard_hash": "clm",
            "agent_did": "did:key:z6MkRoot",
            "timestamp": "2026-10-08T00:00:00Z",
            "vector_clock": {"root": 3},
            "marking_delta": {"sealed": ["clm"]},
        });
        let content = serde_json::to_vec(&body).unwrap();
        let hash = {
            use sha2::{Digest, Sha256};
            let mut h = Sha256::new();
            h.update(&content);
            format!("{:x}", h.finalize())
        };
        conn.execute(
            "INSERT INTO card (hash, content, g_time) VALUES (?1, ?2, ?3)",
            rusqlite::params![hash, content, "2026-10-08T00:00:00Z"],
        )
        .unwrap();
        conn.execute(
            "INSERT INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3)",
            rusqlite::params!["urn:mcard:telemetry:event:root:1", hash, "2026-10-08T00:00:00Z"],
        )
        .unwrap();

        let events = load_learning_events(&conn, None).expect("the loader must read the tape");
        assert_eq!(events.len(), 1, "exactly one event");
        let e = &events[0];
        assert_eq!(e.agent_did, "did:key:z6MkRoot");
        assert_eq!(e.pcard_hash, "clm");
        assert_eq!(e.timestamp, "2026-10-08T00:00:00Z");
        assert_eq!(
            serde_json::to_value(&e.vector_clock).unwrap()["root"], 3,
            "the CLOCK round-trips intact"
        );
    }
}