1use 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
37pub const USER_AUTHOR: &str = "user";
41
42#[derive(
47 Debug, Clone, PartialEq, Archive, Serialize, Deserialize, serde::Serialize, serde::Deserialize,
48)]
49pub struct AttributedDelta {
50 pub author: String,
53 pub delta: CapturedDelta,
54}
55
56#[derive(Clone, Debug)]
61pub struct GraphJournal {
62 log: Codicil<AttributedDelta>,
63 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 pub fn new() -> Self {
81 Self::default()
82 }
83
84 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 pub fn from_log(log: Codicil<AttributedDelta>) -> Self {
96 Self {
97 log,
98 author: USER_AUTHOR.to_string(),
99 }
100 }
101
102 pub fn author(&self) -> &str {
104 &self.author
105 }
106
107 pub fn set_author(&mut self, author: impl Into<String>) {
110 self.author = author.into();
111 }
112
113 pub fn record(&mut self, delta: CapturedDelta) -> Seq {
117 let author = self.author.clone();
118 self.record_as(author, delta)
119 }
120
121 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 pub fn log(&self) -> &Codicil<AttributedDelta> {
131 &self.log
132 }
133
134 pub fn entries(&self) -> &[AttributedDelta] {
136 self.log.entries()
137 }
138
139 pub fn len(&self) -> usize {
141 self.log.len()
142 }
143
144 pub fn is_empty(&self) -> bool {
146 self.log.is_empty()
147 }
148
149 pub fn next_seq(&self) -> Seq {
152 self.log.next_seq()
153 }
154
155 pub const fn earliest_cursor(&self) -> Seq {
159 Seq(0)
160 }
161
162 pub fn live_cursor(&self) -> Seq {
166 self.next_seq()
167 }
168
169 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 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 pub fn id(&self) -> Option<&LogId> {
206 self.log.id()
207 }
208
209 pub fn provenance(&self) -> Option<&Provenance> {
211 self.log.provenance()
212 }
213
214 pub fn replay(&self) -> Graph {
217 replay_captured_deltas(self.log.entries().iter().map(|e| e.delta.clone()))
218 }
219
220 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 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 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 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 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
289pub 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 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 #[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 #[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 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 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}