Skip to main content

kernel/graph/
journal.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! The edit spine: mere's captured-delta stream over the substrate log.
5//!
6//! The graph's durable mutations already exist as a stream of [`CapturedDelta`]s
7//! (stable-id, serializable), emitted through the capture hook as each live
8//! [`GraphDelta`](super::apply::GraphDelta) applies (see `capture.rs`). This module
9//! gives that stream its principled home: a [`codicil::Codicil`] of captured
10//! deltas, the append-only log primitive shared across the Merely apps. The
11//! materialized graph is the *replay* of the journal, and because live editing and
12//! replay both funnel through `apply_graph_delta`, the two cannot diverge.
13//!
14//! This is the edit spine over the substrate. mere keeps its own rich edit
15//! vocabulary — `CapturedDelta` carries content edits (title, tags, body,
16//! navigation) that chartulary's topology-only `GraphEdit` deliberately cannot
17//! express — and codicil supplies the ordered, forkable, persistable log beneath
18//! it. Checkpointing reuses mere's existing `GraphSnapshot`: load a snapshot, then
19//! [`replay_from`](GraphJournal::replay_from) the journal tail past its sequence,
20//! mirroring `chartulary::GraphLog::load_checkpointed`.
21//!
22//! WASM-clean: codicil and muniment are the substrate's portable primitives (the
23//! same ones the browser persists through), so this module compiles to
24//! `wasm32-unknown-unknown` like the rest of `graph/`.
25
26use std::sync::{Arc, Mutex};
27
28use codicil::{Codicil, LogId, Provenance, Seq};
29use muniment::{Backend, Codec, SlotStore, StoreError};
30
31use rkyv::{Archive, Deserialize, Serialize};
32
33use super::Graph;
34use super::capture::{CapturedDelta, replay_captured_deltas, replay_captured_deltas_onto};
35use super::source_time::{SourceExtent, SourceTime};
36
37/// The author every trusted-UI edit records under. Denizen runs scope their
38/// own author (the subject's hex) via [`GraphJournal::set_author`]; entries
39/// migrated from pre-envelope logs carry `pre-gate` (chartulary's convention).
40pub const USER_AUTHOR: &str = "user";
41
42/// One journal entry: a captured delta in the attribution envelope — the
43/// participant-gate plan's B1 adoption of chartulary's `Batch { author, edits }`
44/// shape over mere's edit spine. WHO made a change rides the journal, so a
45/// denizen's edits read back attributed and compensable.
46#[derive(
47    Debug, Clone, PartialEq, Archive, Serialize, Deserialize, serde::Serialize, serde::Deserialize,
48)]
49pub struct AttributedDelta {
50    /// `user` for the trusted UI path, a denizen subject's hex for gated runs,
51    /// `pre-gate` for entries migrated from bare logs.
52    pub author: String,
53    pub delta: CapturedDelta,
54}
55
56/// An append-only journal of a graph's captured edits: the codicil-backed edit
57/// spine. The materialized [`Graph`] is the replay of this log; forking it forks
58/// the graph's whole history with provenance, and it persists whole through one
59/// muniment slot.
60#[derive(Clone, Debug)]
61pub struct GraphJournal {
62    log: Codicil<AttributedDelta>,
63    /// The author the next [`record`](Self::record) attributes — `user` by
64    /// default; a host scopes a denizen run with [`set_author`](Self::set_author)
65    /// and restores afterwards.
66    author: String,
67}
68
69impl Default for GraphJournal {
70    fn default() -> Self {
71        Self {
72            log: Codicil::default(),
73            author: USER_AUTHOR.to_string(),
74        }
75    }
76}
77
78impl GraphJournal {
79    /// A fresh, empty journal (author `user`).
80    pub fn new() -> Self {
81        Self::default()
82    }
83
84    /// A journal with a stable identity, so it can later be forked with
85    /// provenance pointing back at it.
86    pub fn with_id(id: LogId) -> Self {
87        Self {
88            log: Codicil::with_id(id),
89            author: USER_AUTHOR.to_string(),
90        }
91    }
92
93    /// Adopt an existing codicil of attributed deltas (e.g. one just loaded
94    /// from a store or received from a peer).
95    pub fn from_log(log: Codicil<AttributedDelta>) -> Self {
96        Self {
97            log,
98            author: USER_AUTHOR.to_string(),
99        }
100    }
101
102    /// The author subsequent [`record`](Self::record)s attribute.
103    pub fn author(&self) -> &str {
104        &self.author
105    }
106
107    /// Scope the recording author (a denizen run); the host restores `user`
108    /// when the run ends.
109    pub fn set_author(&mut self, author: impl Into<String>) {
110        self.author = author.into();
111    }
112
113    /// Append one captured edit under the current author, returning the [`Seq`]
114    /// it was stamped with. This is the write path: a live mutation's capture
115    /// lands here (usually via [`journal_capture_hook`]).
116    pub fn record(&mut self, delta: CapturedDelta) -> Seq {
117        let author = self.author.clone();
118        self.record_as(author, delta)
119    }
120
121    /// Append one captured edit under an explicit author (the gate path).
122    pub fn record_as(&mut self, author: impl Into<String>, delta: CapturedDelta) -> Seq {
123        self.log.append(AttributedDelta {
124            author: author.into(),
125            delta,
126        })
127    }
128
129    /// The underlying codicil, for cursors, replication, and persistence.
130    pub fn log(&self) -> &Codicil<AttributedDelta> {
131        &self.log
132    }
133
134    /// Every attributed edit, oldest first.
135    pub fn entries(&self) -> &[AttributedDelta] {
136        self.log.entries()
137    }
138
139    /// The number of edits recorded.
140    pub fn len(&self) -> usize {
141        self.log.len()
142    }
143
144    /// Whether the journal holds no edits.
145    pub fn is_empty(&self) -> bool {
146        self.log.is_empty()
147    }
148
149    /// The [`Seq`] the next recorded edit will receive — a durable cursor a
150    /// checkpoint can store to resume replay from.
151    pub fn next_seq(&self) -> Seq {
152        self.log.next_seq()
153    }
154
155    /// The earliest source-time cursor: the empty graph before the first
156    /// captured delta. Journal source time is a **prefix cursor**, so this is
157    /// intentionally `Seq(0)` even though no entry is addressed there yet.
158    pub const fn earliest_cursor(&self) -> Seq {
159        Seq(0)
160    }
161
162    /// The current live source-time cursor: the prefix immediately after the
163    /// newest captured delta. Appending later deltas never changes the graph a
164    /// previously returned cursor replays to.
165    pub fn live_cursor(&self) -> Seq {
166        self.next_seq()
167    }
168
169    /// Materialize graph truth at a journal prefix cursor without changing the
170    /// journal or its current live graph. `Seq(n)` replays exactly the first
171    /// `n` entries; `Seq(0)` is empty and [`live_cursor`](Self::live_cursor)
172    /// replays every current entry. A cursor beyond the known prefix is stale
173    /// and is refused rather than silently clamped to live.
174    pub fn snapshot_at(&self, cursor: Seq) -> Option<Graph> {
175        let end = cursor.index();
176        (end <= self.log.len()).then(|| {
177            replay_captured_deltas(
178                self.log.entries()[..end]
179                    .iter()
180                    .map(|entry| entry.delta.clone()),
181            )
182        })
183    }
184
185    /// Stable, evenly distributed prefix cursors for a compact scrubber. This
186    /// uses sequence order alone: journal history has no required wall-clock
187    /// timestamp. `max_points == 1` yields only the current live cursor;
188    /// larger requests always include both earliest and live when distinct.
189    pub fn sequence_ticks(&self, max_points: usize) -> Vec<Seq> {
190        let live = self.live_cursor();
191        if max_points == 0 {
192            return Vec::new();
193        }
194        if max_points == 1 || live.0 == 0 {
195            return vec![live];
196        }
197        let points = max_points.min(live.0 as usize + 1);
198        let denominator = (points - 1) as u64;
199        (0..points)
200            .map(|index| Seq((index as u64 * live.0) / denominator))
201            .collect()
202    }
203
204    /// This journal's log identity, if any.
205    pub fn id(&self) -> Option<&LogId> {
206        self.log.id()
207    }
208
209    /// Where this journal forked from, if it is a fork.
210    pub fn provenance(&self) -> Option<&Provenance> {
211        self.log.provenance()
212    }
213
214    /// Rebuild the whole graph by replaying every edit from empty (attribution
215    /// rides the journal, not the graph — replay strips the envelope).
216    pub fn replay(&self) -> Graph {
217        replay_captured_deltas(self.log.entries().iter().map(|e| e.delta.clone()))
218    }
219
220    /// Advance an already-materialized `graph` by the edits from `since` onward.
221    /// The checkpoint-plus-tail path: restore a `GraphSnapshot`, then apply only
222    /// the journal entries recorded after the snapshot's sequence. The incremental
223    /// twin of [`replay`](Self::replay).
224    pub fn replay_from(&self, since: Seq, graph: &mut Graph) {
225        replay_captured_deltas_onto(graph, self.log.from(since).iter().map(|e| e.delta.clone()));
226    }
227
228    /// Fork this journal under a new identity: copies the whole edit history and
229    /// records where it branched from, then diverges independently. The log-level
230    /// mirror of a graph fork; the fork replays to an identical graph and then
231    /// edits without touching the source.
232    pub fn fork(&self, new_id: LogId) -> Self {
233        Self {
234            log: self.log.fork(new_id),
235            author: self.author.clone(),
236        }
237    }
238
239    /// Write the whole journal to the muniment slot at `key`.
240    pub async fn save<B: Backend, C: Codec>(
241        &self,
242        slots: &SlotStore<B, C>,
243        key: &str,
244    ) -> Result<(), StoreError> {
245        self.log.save(slots, key).await
246    }
247
248    /// Load a journal from the muniment slot at `key`, or an empty journal if the
249    /// slot is absent.
250    pub async fn load<B: Backend, C: Codec>(
251        slots: &SlotStore<B, C>,
252        key: &str,
253    ) -> Result<Self, StoreError> {
254        Ok(Self::from_log(Codicil::load(slots, key).await?))
255    }
256
257    /// Adopt a pre-envelope codicil of bare [`CapturedDelta`]s, attributing
258    /// every entry `pre-gate` (chartulary's migration convention): the one-way
259    /// load-time migration for logs recorded before attribution existed.
260    pub fn migrate_bare_log(log: Codicil<CapturedDelta>) -> Self {
261        let mut journal = GraphJournal::new();
262        for delta in log.entries() {
263            journal.record_as("pre-gate", delta.clone());
264        }
265        journal
266    }
267}
268
269impl SourceTime for GraphJournal {
270    type Cursor = Seq;
271    type Snapshot = Graph;
272
273    fn source_extent(&self) -> SourceExtent<Self::Cursor> {
274        SourceExtent {
275            earliest: self.earliest_cursor(),
276            current: self.live_cursor(),
277        }
278    }
279
280    fn source_ticks(&self, max_points: usize) -> Vec<Self::Cursor> {
281        self.sequence_ticks(max_points)
282    }
283
284    fn source_snapshot(&self, cursor: &Self::Cursor) -> Option<Self::Snapshot> {
285        self.snapshot_at(*cursor)
286    }
287}
288
289/// A shared journal plus a capture hook that records every emitted
290/// [`CapturedDelta`] into it. Install the hook with
291/// [`set_captured_delta_hook`](super::set_captured_delta_hook) and keep the handle
292/// to replay or persist the journal:
293///
294/// ```ignore
295/// let (journal, hook) = journal_capture_hook();
296/// kernel::graph::set_captured_delta_hook(Some(hook));
297/// // ... drive live mutations through apply_graph_delta ...
298/// let restored = journal.lock().unwrap().replay();
299/// ```
300///
301/// The capture hook is one per-thread slot, so this replaces any previously
302/// installed hook. It is offered as the host's codicil-backed persistence path.
303pub fn journal_capture_hook() -> (
304    Arc<Mutex<GraphJournal>>,
305    Arc<dyn Fn(&CapturedDelta) + Send + Sync + 'static>,
306) {
307    let journal = Arc::new(Mutex::new(GraphJournal::new()));
308    let sink = Arc::clone(&journal);
309    let hook: Arc<dyn Fn(&CapturedDelta) + Send + Sync + 'static> = Arc::new(move |delta| {
310        if let Ok(mut journal) = sink.lock() {
311            journal.record(delta.clone());
312        }
313    });
314    (journal, hook)
315}
316
317#[cfg(test)]
318mod tests {
319    use super::*;
320    use crate::graph::apply::{GraphDelta, GraphDeltaResult, apply_graph_delta};
321    use crate::graph::set_captured_delta_hook;
322    use crate::graph::{EdgeAssertion, SemanticSubKind, SourceExtent, SourceTime};
323    use euclid::default::Point2D;
324    use uuid::Uuid;
325
326    fn add(id: u128, url: &str) -> CapturedDelta {
327        CapturedDelta::ReplayAddNodeWithIdIfMissing {
328            id: Uuid::from_u128(id).to_string(),
329            url: url.to_string(),
330            position: [0.0, 0.0],
331        }
332    }
333
334    /// A key-independent view: sorted node ids and sorted (from, to, kind) triples.
335    /// Two graphs are equal iff their fingerprints are, regardless of petgraph keys.
336    fn fingerprint(graph: &Graph) -> (Vec<String>, Vec<(String, String, String)>) {
337        let mut nodes: Vec<String> = graph.nodes().map(|(_, n)| n.id.to_string()).collect();
338        nodes.sort();
339        let mut edges: Vec<(String, String, String)> = graph
340            .relations()
341            .map(|rel| {
342                let from = graph
343                    .get_node(rel.from)
344                    .map(|n| n.id.to_string())
345                    .unwrap_or_default();
346                let to = graph
347                    .get_node(rel.to)
348                    .map(|n| n.id.to_string())
349                    .unwrap_or_default();
350                (from, to, format!("{:?}", rel.kind))
351            })
352            .collect();
353        edges.sort();
354        (nodes, edges)
355    }
356
357    /// The envelope: entries carry their author; the default is `user`, a
358    /// scoped author attributes a denizen run, and replay strips the envelope.
359    #[test]
360    fn entries_are_attributed_and_author_scoping_works() {
361        let mut journal = GraphJournal::new();
362        journal.record(add(1, "https://a.test/"));
363        journal.set_author("aa11");
364        journal.record(add(2, "https://b.test/"));
365        journal.set_author(USER_AUTHOR);
366        journal.record_as("gate", add(3, "https://c.test/"));
367
368        let authors: Vec<&str> = journal
369            .entries()
370            .iter()
371            .map(|e| e.author.as_str())
372            .collect();
373        assert_eq!(authors, ["user", "aa11", "gate"]);
374        assert_eq!(journal.author(), USER_AUTHOR, "scoping restored");
375        assert_eq!(
376            journal.replay().node_count(),
377            3,
378            "replay strips the envelope"
379        );
380    }
381
382    #[test]
383    fn source_time_contract_selects_immutable_journal_prefixes() {
384        let mut journal = GraphJournal::new();
385        journal.record(add(1, "https://one.test/"));
386        journal.record(add(2, "https://two.test/"));
387
388        assert_eq!(
389            journal.source_extent(),
390            SourceExtent {
391                earliest: Seq(0),
392                current: Seq(2),
393            }
394        );
395        assert_eq!(journal.source_ticks(3), [Seq(0), Seq(1), Seq(2)]);
396        assert_eq!(
397            journal
398                .source_snapshot(&Seq(1))
399                .expect("known source cursor")
400                .node_count(),
401            1
402        );
403        assert!(journal.source_snapshot(&Seq(3)).is_none());
404        assert_eq!(
405            journal.replay().node_count(),
406            2,
407            "scrubbing leaves live truth intact"
408        );
409    }
410
411    /// A pre-envelope bare log migrates one-way with the `pre-gate` author.
412    #[test]
413    fn a_bare_log_migrates_as_pre_gate() {
414        let mut bare = Codicil::<CapturedDelta>::default();
415        bare.append(add(1, "https://a.test/"));
416        bare.append(add(2, "https://b.test/"));
417        let journal = GraphJournal::migrate_bare_log(bare);
418        assert!(journal.entries().iter().all(|e| e.author == "pre-gate"));
419        assert_eq!(journal.replay().node_count(), 2);
420    }
421
422    #[test]
423    fn records_and_replays_reconstruct_the_graph() {
424        let mut journal = GraphJournal::new();
425        journal.record(add(1, "https://a.test/"));
426        journal.record(add(2, "https://b.test/"));
427        journal.record(CapturedDelta::ReplayAssertRelationByIds {
428            from_id: Uuid::from_u128(1).to_string(),
429            to_id: Uuid::from_u128(2).to_string(),
430            assertion: EdgeAssertion::Semantic {
431                sub_kind: SemanticSubKind::Cites,
432                label: None,
433                decay_progress: None,
434            },
435        });
436        journal.record(CapturedDelta::ReplaySetNodeTitleById {
437            node_id: Uuid::from_u128(1).to_string(),
438            title: "Paper A".to_string(),
439        });
440
441        let graph = journal.replay();
442        assert_eq!(graph.node_count(), 2);
443        assert_eq!(graph.relations().count(), 1, "the cites relation replayed");
444        let (_, node) = graph
445            .get_node_by_id(Uuid::from_u128(1))
446            .expect("node a present");
447        assert_eq!(node.title, "Paper A", "the content edit replayed too");
448    }
449
450    #[test]
451    fn prefix_cursors_replay_historical_graphs_without_touching_live_history() {
452        let mut journal = GraphJournal::new();
453        journal.record(add(1, "https://a.test/"));
454        journal.record(add(2, "https://b.test/"));
455        journal.record(CapturedDelta::ReplayAssertRelationByIds {
456            from_id: Uuid::from_u128(1).to_string(),
457            to_id: Uuid::from_u128(2).to_string(),
458            assertion: EdgeAssertion::Semantic {
459                sub_kind: SemanticSubKind::Cites,
460                label: None,
461                decay_progress: None,
462            },
463        });
464
465        assert_eq!(journal.earliest_cursor(), Seq(0));
466        assert_eq!(journal.live_cursor(), Seq(3));
467        assert_eq!(journal.snapshot_at(Seq(0)).unwrap().node_count(), 0);
468        assert_eq!(journal.snapshot_at(Seq(1)).unwrap().node_count(), 1);
469        let historical = journal.snapshot_at(Seq(2)).expect("known prefix");
470        assert_eq!(historical.node_count(), 2);
471        assert_eq!(historical.relations().count(), 0);
472        assert_eq!(journal.snapshot_at(Seq(3)).unwrap().relations().count(), 1);
473        assert!(
474            journal.snapshot_at(Seq(4)).is_none(),
475            "stale cursors refuse"
476        );
477        assert_eq!(
478            journal.replay().relations().count(),
479            1,
480            "live history remains live"
481        );
482        assert_eq!(journal.sequence_ticks(3), vec![Seq(0), Seq(1), Seq(3)]);
483    }
484
485    #[test]
486    fn fork_carries_history_then_diverges() {
487        let mut source = GraphJournal::with_id(LogId::new("source"));
488        source.record(add(1, "https://a.test/"));
489        source.record(add(2, "https://b.test/"));
490
491        let mut fork = source.fork(LogId::new("fork"));
492        assert_eq!(
493            fork.entries(),
494            source.entries(),
495            "the fork copies the history"
496        );
497        let provenance = fork.provenance().expect("a fork has provenance");
498        assert_eq!(provenance.source, Some(LogId::new("source")));
499        assert_eq!(provenance.at, Seq(source.len() as u64));
500
501        // Diverging the fork leaves the source untouched.
502        fork.record(add(3, "https://c.test/"));
503        assert_eq!(source.replay().node_count(), 2, "source unchanged");
504        assert_eq!(fork.replay().node_count(), 3);
505    }
506
507    #[test]
508    fn journal_round_trips_through_a_muniment_slot() {
509        use muniment::{JsonSlots, MemoryBackend};
510        pollster::block_on(async {
511            let slots = JsonSlots::new(MemoryBackend::new());
512
513            let mut journal = GraphJournal::new();
514            journal.record(add(1, "https://a.test/"));
515            journal.record(add(2, "https://b.test/"));
516            journal.save(&slots, "journal").await.unwrap();
517
518            let reloaded = GraphJournal::load(&slots, "journal").await.unwrap();
519            assert_eq!(reloaded.len(), 2, "the log survived the round trip");
520            assert_eq!(
521                fingerprint(&reloaded.replay()),
522                fingerprint(&journal.replay()),
523                "the reloaded journal replays to the same graph"
524            );
525        });
526    }
527
528    #[test]
529    fn the_capture_hook_feeds_the_journal_and_replay_matches_live() {
530        // The edit-spine invariant: a graph built by live mutation and one rebuilt
531        // by replaying the journal those mutations produced are identical.
532        let (journal, hook) = journal_capture_hook();
533        set_captured_delta_hook(Some(hook));
534
535        let mut live = Graph::new();
536        let a = match apply_graph_delta(
537            &mut live,
538            GraphDelta::AddNode {
539                id: Some(Uuid::from_u128(1)),
540                url: "https://a.test/".to_string(),
541                position: Point2D::new(0.0, 0.0),
542            },
543        ) {
544            GraphDeltaResult::NodeAdded(key) => key,
545            other => panic!("expected NodeAdded, got {other:?}"),
546        };
547        let b = match apply_graph_delta(
548            &mut live,
549            GraphDelta::AddNode {
550                id: Some(Uuid::from_u128(2)),
551                url: "https://b.test/".to_string(),
552                position: Point2D::new(1.0, 0.0),
553            },
554        ) {
555            GraphDeltaResult::NodeAdded(key) => key,
556            other => panic!("expected NodeAdded, got {other:?}"),
557        };
558        apply_graph_delta(
559            &mut live,
560            GraphDelta::AssertRelation {
561                from: a,
562                to: b,
563                assertion: EdgeAssertion::Semantic {
564                    sub_kind: SemanticSubKind::Cites,
565                    label: None,
566                    decay_progress: None,
567                },
568            },
569        );
570        apply_graph_delta(
571            &mut live,
572            GraphDelta::SetNodeTitle {
573                key: a,
574                title: "Paper A".to_string(),
575            },
576        );
577
578        set_captured_delta_hook(None);
579
580        let replayed = journal.lock().unwrap().replay();
581        assert_eq!(
582            fingerprint(&replayed),
583            fingerprint(&live),
584            "replay of the captured journal reconstructs the live graph"
585        );
586        let (_, node) = replayed.get_node_by_id(Uuid::from_u128(1)).expect("node a");
587        assert_eq!(node.title, "Paper A");
588    }
589}