use std::sync::{Arc, Mutex};
use muniment::{Backend, Codec, SlotStore, StoreError};
use muniment::{Journal, LogId, Provenance, Seq};
use rkyv::{Archive, Deserialize, Serialize};
use super::Graph;
use super::capture::{
CapturedDelta, DeltaRecorder, OnRefusal, ReplayAttribution, ReplayRefused,
replay_attributed_deltas_onto, replay_outcomes_onto,
};
use super::source_time::{SourceExtent, SourceTime};
pub const USER_AUTHOR: &str = "user";
#[derive(
Debug,
Clone,
Copy,
PartialEq,
Eq,
Hash,
Archive,
Serialize,
Deserialize,
serde::Serialize,
serde::Deserialize,
)]
#[serde(rename_all = "snake_case")]
pub enum AuthorKind {
Person,
Rule,
Script,
Engine,
}
#[derive(
Debug,
Clone,
PartialEq,
Eq,
Hash,
Archive,
Serialize,
Deserialize,
serde::Serialize,
serde::Deserialize,
)]
pub struct Author {
pub kind: AuthorKind,
pub id: String,
pub version: Option<String>,
pub via: Option<String>,
}
impl Author {
pub fn asserter_iri(&self) -> String {
if self.kind == AuthorKind::Person
&& !self.id.chars().any(|c| c.is_whitespace() || c.is_control())
&& url::Url::parse(&self.id).is_ok()
{
return self.id.clone();
}
let kind = match self.kind {
AuthorKind::Person => "person",
AuthorKind::Rule => "rule",
AuthorKind::Script => "script",
AuthorKind::Engine => "engine",
};
let encoded: String = url::form_urlencoded::byte_serialize(self.id.as_bytes()).collect();
format!("https://mere.computer/ns/agent#{kind}/{encoded}")
}
pub fn person(id: impl Into<String>) -> Self {
Self::new(AuthorKind::Person, id, None)
}
pub fn user() -> Self {
Self::person(USER_AUTHOR)
}
pub fn rule(id: impl Into<String>, version: impl Into<String>) -> Self {
Self::new(AuthorKind::Rule, id, Some(version.into()))
}
pub fn script(id: impl Into<String>, version: impl Into<String>) -> Self {
Self::new(AuthorKind::Script, id, Some(version.into()))
}
pub fn engine(id: impl Into<String>, version: impl Into<String>) -> Self {
Self::new(AuthorKind::Engine, id, Some(version.into()))
}
fn new(kind: AuthorKind, id: impl Into<String>, version: Option<String>) -> Self {
Self {
kind,
id: id.into(),
version,
via: None,
}
}
pub fn via(mut self, application: impl Into<String>) -> Self {
self.via = Some(application.into());
self
}
}
impl std::fmt::Display for Author {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let kind = match self.kind {
AuthorKind::Person => "person",
AuthorKind::Rule => "rule",
AuthorKind::Script => "script",
AuthorKind::Engine => "engine",
};
write!(f, "{kind} {}", self.id)?;
if let Some(version) = &self.version {
write!(f, " {version}")?;
}
if let Some(via) = &self.via {
write!(f, " via {via}")?;
}
Ok(())
}
}
#[derive(
Debug, Clone, PartialEq, Archive, Serialize, Deserialize, serde::Serialize, serde::Deserialize,
)]
pub struct AttributedDelta {
pub author: Author,
pub delta: CapturedDelta,
}
#[derive(Clone, Debug)]
pub struct GraphJournal {
log: Journal<AttributedDelta>,
author: Author,
}
impl Default for GraphJournal {
fn default() -> Self {
Self {
log: Journal::default(),
author: Author::user(),
}
}
}
impl GraphJournal {
pub fn new() -> Self {
Self::default()
}
pub fn with_id(id: LogId) -> Self {
Self {
log: Journal::with_id(id),
author: Author::user(),
}
}
pub fn starting_from(id: LogId, provenance: Provenance) -> Self {
Self::from_log(Journal::starting_from(id, provenance))
}
pub fn from_log(log: Journal<AttributedDelta>) -> Self {
Self {
log,
author: Author::user(),
}
}
pub fn author(&self) -> &Author {
&self.author
}
pub fn set_author(&mut self, author: Author) {
self.author = author;
}
pub fn record(&mut self, delta: CapturedDelta) -> Seq {
let author = self.author.clone();
self.record_as(author, delta)
}
pub fn record_as(&mut self, author: Author, delta: CapturedDelta) -> Seq {
self.log.append(AttributedDelta { author, delta })
}
pub fn log(&self) -> &Journal<AttributedDelta> {
&self.log
}
pub fn entries(&self) -> &[AttributedDelta] {
self.log.entries()
}
pub fn len(&self) -> usize {
self.log.len()
}
pub fn is_empty(&self) -> bool {
self.log.is_empty()
}
pub fn next_seq(&self) -> Seq {
self.log.next_seq()
}
pub const fn earliest_cursor(&self) -> Seq {
Seq(0)
}
pub fn live_cursor(&self) -> Seq {
self.next_seq()
}
pub fn snapshot_at(&self, cursor: Seq) -> Result<Option<Graph>, ReplayRefused> {
self.snapshot_at_from(&Graph::new(), cursor)
}
pub fn snapshot_at_from(
&self,
baseline: &Graph,
cursor: Seq,
) -> Result<Option<Graph>, ReplayRefused> {
let end = cursor.index();
if end > self.log.len() {
return Ok(None);
}
let mut graph = baseline.clone();
replay_entries_onto(&mut graph, &self.log.entries()[..end], OnRefusal::Stop)?;
Ok(Some(graph))
}
pub fn migrated_prefix_at_from(
&self,
baseline: &Graph,
cursor: Seq,
) -> Result<
Option<super::legacy_resource_migration::MigratedReplay>,
super::legacy_resource_migration::LegacyMigrationError,
> {
let end = cursor.index();
if end > self.log.len() {
return Ok(None);
}
super::legacy_resource_migration::migrate_legacy_prefix(
baseline,
&self.log.entries()[..end],
)
.map(Some)
}
pub fn migrated_prefix_at_from_with_resolutions(
&self,
baseline: &Graph,
cursor: Seq,
resolutions: &[super::legacy_resource_migration::LegacyResourceOriginResolution],
) -> Result<
Option<super::legacy_resource_migration::MigratedReplay>,
super::legacy_resource_migration::LegacyMigrationError,
> {
use super::legacy_resource_migration::{
migrate_legacy_prefix_with_resolutions, probe_legacy_mint_links,
validate_legacy_origin_resolutions,
};
let end = cursor.index();
if end > self.log.len() {
return Ok(None);
}
validate_legacy_origin_resolutions(baseline, self.log.entries(), resolutions)?;
let prefix = &self.log.entries()[..end];
let ids: std::collections::BTreeSet<_> = probe_legacy_mint_links(baseline, prefix)?
.into_iter()
.map(|diagnostic| diagnostic.statement_id)
.collect();
let relevant: Vec<_> = resolutions
.iter()
.filter(|choice| ids.contains(&choice.statement_id))
.cloned()
.collect();
migrate_legacy_prefix_with_resolutions(baseline, prefix, &relevant).map(Some)
}
pub fn migrated_snapshot_at_from_with_resolutions(
&self,
baseline: &Graph,
cursor: Seq,
resolutions: &[super::legacy_resource_migration::LegacyResourceOriginResolution],
) -> Result<Option<Graph>, super::legacy_resource_migration::LegacyMigrationError> {
self.migrated_prefix_at_from_with_resolutions(baseline, cursor, resolutions)
.map(|replay| replay.map(|replay| replay.graph))
}
pub fn migrated_snapshot_at_from(
&self,
baseline: &Graph,
cursor: Seq,
) -> Result<Option<Graph>, super::legacy_resource_migration::LegacyMigrationError> {
self.migrated_prefix_at_from(baseline, cursor)
.map(|replay| replay.map(|replay| replay.graph))
}
pub fn migrated_replay_from_with_baseline(
&self,
since: Seq,
graph: &mut Graph,
baseline: &Graph,
) -> Result<(), super::legacy_resource_migration::LegacyMigrationError> {
self.migrated_replay_from_with_baseline_and_resolutions(since, graph, baseline, &[])
}
pub fn migrated_replay_from_with_baseline_and_resolutions(
&self,
since: Seq,
graph: &mut Graph,
baseline: &Graph,
resolutions: &[super::legacy_resource_migration::LegacyResourceOriginResolution],
) -> Result<(), super::legacy_resource_migration::LegacyMigrationError> {
if since.index() > self.log.len() {
return Err(super::legacy_resource_migration::LegacyMigrationError(
"legacy checkpoint cursor is beyond retained history".into(),
));
}
let mut replay = self
.migrated_prefix_at_from_with_resolutions(baseline, self.live_cursor(), resolutions)?
.expect("live cursor exists");
replay.graph.recorder.0 = graph.recorder.0.take();
replay.graph.write_author = graph.write_author.clone();
replay.graph.current_session = graph.current_session;
replay.graph.revision = replay.graph.revision.max(graph.revision).saturating_add(1);
replay.graph.url_grouping_revision = replay
.graph
.url_grouping_revision
.max(graph.url_grouping_revision)
.saturating_add(1);
*graph = replay.graph;
Ok(())
}
pub fn sequence_ticks(&self, max_points: usize) -> Vec<Seq> {
let live = self.live_cursor();
if max_points == 0 {
return Vec::new();
}
if max_points == 1 || live.0 == 0 {
return vec![live];
}
let points = max_points.min(live.0 as usize + 1);
let denominator = (points - 1) as u64;
(0..points)
.map(|index| Seq((index as u64 * live.0) / denominator))
.collect()
}
pub fn id(&self) -> Option<&LogId> {
self.log.id()
}
pub fn provenance(&self) -> Option<&Provenance> {
self.log.provenance()
}
pub fn replay(&self) -> Graph {
let mut graph = Graph::new();
let _ = replay_entries_onto(&mut graph, self.log.entries(), OnRefusal::Drop);
graph
}
pub fn replay_from(&self, since: Seq, graph: &mut Graph) -> Result<(), ReplayRefused> {
replay_outcomes_onto(
graph,
self.log
.from(since)
.iter()
.map(|entry| entry.delta.replay_as(&entry.author)),
OnRefusal::Stop,
)
}
pub fn replay_from_with_baseline(
&self,
since: Seq,
graph: &mut Graph,
baseline: &Graph,
) -> Result<(), ReplayRefused> {
let mut attribution = ReplayAttribution::from_baseline(baseline);
let mut shadow = baseline.clone();
replay_attributed_deltas_onto(
&mut shadow,
&mut attribution,
self.log.entries().iter().take(since.index()),
OnRefusal::Stop,
)?;
attribution.repair_checkpoint(graph);
replay_attributed_deltas_onto(
graph,
&mut attribution,
self.log.from(since),
OnRefusal::Stop,
)
}
pub fn fork(&self, new_id: LogId) -> Self {
Self {
log: self.log.fork(new_id),
author: self.author.clone(),
}
}
pub async fn save<B: Backend, C: Codec>(
&self,
slots: &SlotStore<B, C>,
key: &str,
) -> Result<(), StoreError> {
self.log.save(slots, key).await
}
pub async fn load<B: Backend, C: Codec>(
slots: &SlotStore<B, C>,
key: &str,
) -> Result<Self, StoreError> {
Ok(Self::from_log(Journal::load(slots, key).await?))
}
}
fn replay_entries_onto<'a, I>(
graph: &mut Graph,
entries: I,
on_refusal: OnRefusal,
) -> Result<(), ReplayRefused>
where
I: IntoIterator<Item = &'a AttributedDelta>,
{
let mut attribution = ReplayAttribution::from_baseline(graph);
replay_attributed_deltas_onto(graph, &mut attribution, entries, on_refusal)
}
impl SourceTime for GraphJournal {
type Cursor = Seq;
type Snapshot = Graph;
fn source_extent(&self) -> SourceExtent<Self::Cursor> {
SourceExtent {
earliest: self.earliest_cursor(),
current: self.live_cursor(),
}
}
fn source_ticks(&self, max_points: usize) -> Vec<Self::Cursor> {
self.sequence_ticks(max_points)
}
fn source_snapshot(&self, cursor: &Self::Cursor) -> Option<Self::Snapshot> {
self.snapshot_at(*cursor).ok().flatten()
}
}
pub fn journal_capture_hook() -> (Arc<Mutex<GraphJournal>>, DeltaRecorder) {
let journal = Arc::new(Mutex::new(GraphJournal::new()));
let sink = Arc::clone(&journal);
let hook: DeltaRecorder = Arc::new(move |delta| {
if let Ok(mut journal) = sink.lock() {
journal.record(delta.clone());
}
});
(journal, hook)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::graph::apply::{GraphDelta, GraphDeltaResult, apply_graph_delta};
use crate::graph::capture::{replay_captured_deltas, replay_captured_deltas_onto};
use crate::graph::set_captured_delta_hook;
use crate::graph::{EdgeAssertion, SemanticSubKind, SourceExtent, SourceTime};
use euclid::default::Point2D;
use uuid::Uuid;
#[test]
fn assertion_attribution_ignores_automated_versions_and_recording_application() {
for kind in [AuthorKind::Rule, AuthorKind::Script, AuthorKind::Engine] {
let v1 = Author::new(kind, "extractor", Some("1".into())).via("turnstone");
let v2 = Author::new(kind, "extractor", Some("2".into())).via("knot");
assert_ne!(v1, v2, "the journal keeps version and application metadata");
assert_eq!(v1.asserter_iri(), v2.asserter_iri());
assert_ne!(
v1.asserter_iri(),
Author::new(kind, "another-extractor", Some("1".into())).asserter_iri(),
"different names still identify different asserters"
);
}
let kinds = [
Author::person("extractor"),
Author::rule("extractor", "1"),
Author::script("extractor", "1"),
Author::engine("extractor", "1"),
];
let identities: std::collections::BTreeSet<_> =
kinds.iter().map(Author::asserter_iri).collect();
assert_eq!(identities.len(), kinds.len());
}
#[test]
fn assertion_attribution_keeps_person_iris_and_encodes_opaque_ids() {
for iri in [
"https://people.test/alice",
"did:key:z6MkAlice",
"urn:uuid:058e1fe2-851b-4f1c-bbf0-0cbf74fe7727",
] {
assert_eq!(Author::person(iri).asserter_iri(), iri);
}
let person = Author::person("alice /+?#%名字");
assert_eq!(
person.asserter_iri(),
"https://mere.computer/ns/agent#person/alice+%2F%2B%3F%23%25%E5%90%8D%E5%AD%97"
);
assert_eq!(
person.asserter_iri(),
person.clone().via("knot").asserter_iri()
);
assert!(url::Url::parse(&person.asserter_iri()).is_ok());
assert_ne!(
Author::person("alice /+?#%名字").asserter_iri(),
Author::person("alice +?#%名字").asserter_iri()
);
assert_ne!(
Author::person(".").asserter_iri(),
Author::person("..").asserter_iri(),
"opaque dot segments are preserved in the fragment"
);
assert_eq!(
Author::person(" https://people.test/alice ").asserter_iri(),
"https://mere.computer/ns/agent#person/+https%3A%2F%2Fpeople.test%2Falice+"
);
}
fn add(id: u128, url: &str) -> CapturedDelta {
CapturedDelta::ReplayAddNodeWithIdIfMissing {
id: Uuid::from_u128(id).to_string(),
url: url.to_string(),
position: [0.0, 0.0],
}
}
fn assert_live_add_captures(deltas: &[CapturedDelta], id: u128, url: &str) {
let resource = super::super::ResourceNode::new(url);
assert_eq!(deltas.len(), 4);
assert_eq!(deltas[0], add(id, url));
assert!(
matches!(&deltas[1], CapturedDelta::ReplayTouchNodeLastVisitedById {
node_id, ..
} if node_id == &Uuid::from_u128(id).to_string())
);
assert_eq!(
deltas[2],
CapturedDelta::ReplaySetResourceRecordById {
resource_id: resource.id().to_string(),
record: Some(crate::persistence::PersistedResourceRecord {
canonical_iri: resource.canonical_iri().into(),
facets: vec![],
}),
}
);
assert_eq!(
deltas[3],
CapturedDelta::ReplaySetShownResourceById {
surface_id: Uuid::from_u128(id).to_string(),
resource_id: Some(resource.id().to_string()),
}
);
}
#[test]
fn legacy_journal_assertions_use_each_entry_author_on_full_and_prefix_replay() {
let mut journal = GraphJournal::new();
journal.record(add(1, "https://a.test/"));
journal.record(add(2, "https://b.test/"));
let recognized = CapturedDelta::ReplayAssertRelationByIds {
from_id: Uuid::from_u128(1).to_string(),
to_id: Uuid::from_u128(2).to_string(),
assertion: EdgeAssertion::Semantic {
sub_kind: SemanticSubKind::Cites,
label: None,
},
};
let open = CapturedDelta::ReplayAssertSemanticPredicateByIds {
from_id: Uuid::from_u128(1).to_string(),
to_id: Uuid::from_u128(2).to_string(),
predicate: "https://vocab.test/mentions".into(),
};
let alice = Author::person("https://people.test/alice");
let bob = Author::person("https://people.test/bob");
for author in [&alice, &bob] {
journal.record_as(author.clone(), recognized.clone());
journal.record_as(author.clone(), open.clone());
}
let attributions = |graph: &Graph| {
let a = graph.get_node_key_by_id(Uuid::from_u128(1)).unwrap();
let b = graph.get_node_key_by_id(Uuid::from_u128(2)).unwrap();
let edge = graph.find_edge_key(a, b).unwrap();
let mut values: Vec<_> = graph
.get_edge(edge)
.unwrap()
.semantic_statements()
.iter()
.map(|statement| {
(
statement.predicate.clone(),
statement.provenance_iri.clone().unwrap(),
)
})
.collect();
values.sort();
values
};
let full = journal.replay();
let full_attributions = attributions(&full);
assert_eq!(full_attributions.len(), 4);
for author in [&alice, &bob] {
assert_eq!(
full_attributions
.iter()
.filter(|(_, iri)| iri == &author.asserter_iri())
.count(),
2
);
}
let mut prefix = journal.snapshot_at(Seq(4)).unwrap().unwrap();
let prefix_attributions = attributions(&prefix);
assert_eq!(prefix_attributions.len(), 2);
assert!(
prefix_attributions
.iter()
.all(|(_, iri)| iri == &alice.asserter_iri())
);
journal.replay_from(Seq(4), &mut prefix).unwrap();
assert_eq!(attributions(&prefix), full_attributions);
let unattributed =
replay_captured_deltas(journal.entries().iter().map(|entry| entry.delta.clone()));
let legacy_attributions = attributions(&unattributed);
assert_eq!(
legacy_attributions.len(),
2,
"without envelopes attribution remains unknown"
);
assert!(
legacy_attributions
.iter()
.all(|(_, iri)| iri == crate::graph::edge_data::UNKNOWN_LEGACY_ASSERTER_IRI)
);
}
#[test]
fn exact_statement_capture_preserves_source_over_journal_recorder() {
let mut source =
replay_captured_deltas([add(1, "https://a.test/"), add(2, "https://b.test/")]);
let a = source.get_node_key_by_id(Uuid::from_u128(1)).unwrap();
let b = source.get_node_key_by_id(Uuid::from_u128(2)).unwrap();
let source_iri = "https://source.test/page";
source
.assert_surface_semantic_statement(
a,
b,
super::super::SemanticStatementSpec {
predicate: super::super::predicate_iri(SemanticSubKind::Cites).into(),
recognized_sub_kind: Some(SemanticSubKind::Cites),
provenance_iri: Some(source_iri.into()),
asserted_at_ms: Some(100),
..Default::default()
},
)
.unwrap();
let expected = source.persisted_edges_between(a, b);
let exact = CapturedDelta::ReplaySetEdgesByIds {
from_id: Uuid::from_u128(1).to_string(),
to_id: Uuid::from_u128(2).to_string(),
edges: expected.clone(),
};
let recorder = Author::engine("extractor", "9");
assert_ne!(source_iri, recorder.asserter_iri());
let mut journal = GraphJournal::new();
journal.record(add(1, "https://a.test/"));
journal.record(add(2, "https://b.test/"));
journal.record_as(recorder.clone(), exact.clone());
let restored = journal.replay();
let restored_a = restored.get_node_key_by_id(Uuid::from_u128(1)).unwrap();
let restored_b = restored.get_node_key_by_id(Uuid::from_u128(2)).unwrap();
assert_eq!(
restored.persisted_edges_between(restored_a, restored_b),
expected
);
let mut direct = Graph::new();
crate::graph::capture::replay_captured_deltas_as_onto(
&mut direct,
&recorder,
[add(1, "https://a.test/"), add(2, "https://b.test/"), exact],
);
let direct_a = direct.get_node_key_by_id(Uuid::from_u128(1)).unwrap();
let direct_b = direct.get_node_key_by_id(Uuid::from_u128(2)).unwrap();
assert_eq!(direct.persisted_edges_between(direct_a, direct_b), expected);
}
#[test]
fn legacy_exact_capture_attribution_matches_checkpoint_replay() {
use crate::graph::SemanticStatementSpec;
let recorder = Author::engine("legacy-extractor", "1");
for source in [Some("https://source.test/page"), None] {
let mut template =
replay_captured_deltas([add(1, "https://a.test/"), add(2, "https://b.test/")]);
let from = template.get_node_key_by_id(Uuid::from_u128(1)).unwrap();
let to = template.get_node_key_by_id(Uuid::from_u128(2)).unwrap();
template
.assert_surface_semantic_statement(
from,
to,
SemanticStatementSpec {
predicate: super::super::predicate_iri(SemanticSubKind::Cites).into(),
recognized_sub_kind: Some(SemanticSubKind::Cites),
provenance_iri: Some("https://template.test/".into()),
asserted_at_ms: Some(100),
..Default::default()
},
)
.unwrap();
let mut old_edges = template.persisted_edges_between(from, to);
let old_statement = &mut old_edges[0].retained_assertions_mut()[0];
old_statement.statement_id = "legacy-exact-handle".into();
old_statement.provenance_iri = source.map(str::to_owned);
if source.is_none() {
let exact = CapturedDelta::ReplaySetEdgesByIds {
from_id: Uuid::from_u128(1).to_string(),
to_id: Uuid::from_u128(2).to_string(),
edges: old_edges.clone(),
};
let mut baseline = template.clone();
super::super::capture::replay_captured_deltas_onto(&mut baseline, [exact.clone()]);
let mut baseline_journal = GraphJournal::new();
baseline_journal.record_as(recorder.clone(), exact);
baseline_journal.replay_from(Seq(0), &mut baseline).unwrap();
assert_eq!(
baseline.persisted_edges_between(from, to)[0].retained_assertions()[0]
.provenance_iri
.as_deref(),
Some(super::super::edge_data::UNKNOWN_LEGACY_ASSERTER_IRI),
"an unattributed baseline handle stays unknown"
);
}
let mut journal = GraphJournal::new();
journal.record(add(1, "https://a.test/"));
journal.record(add(2, "https://b.test/"));
journal.record_as(
recorder.clone(),
CapturedDelta::ReplayAssertRelationByIds {
from_id: Uuid::from_u128(1).to_string(),
to_id: Uuid::from_u128(2).to_string(),
assertion: EdgeAssertion::Semantic {
sub_kind: SemanticSubKind::Cites,
label: None,
},
},
);
let prefix = journal.snapshot_at(Seq(3)).unwrap().unwrap();
let prefix_edges = prefix.persisted_edges_between(from, to);
assert_eq!(
prefix_edges[0].retained_assertions()[0].provenance_iri,
Some(recorder.asserter_iri()),
"the raw historical assertion first recovers its recorder"
);
journal.record_as(
recorder.clone(),
CapturedDelta::ReplaySetEdgesByIds {
from_id: Uuid::from_u128(1).to_string(),
to_id: Uuid::from_u128(2).to_string(),
edges: old_edges,
},
);
let full = journal.replay();
let expected = full.persisted_edges_between(from, to);
let statements = &expected[0].retained_assertions();
assert_eq!(statements.len(), 1);
assert_eq!(statements[0].statement_id, "legacy-exact-handle");
assert_eq!(statements[0].asserted_at_ms, Some(100));
assert_eq!(
statements[0].provenance_iri.as_deref(),
Some(
source
.map(str::to_owned)
.unwrap_or_else(|| recorder.asserter_iri())
.as_str()
),
"a minted handle recovers its Author; a known source remains unchanged"
);
let mut checkpoint = Graph::from_snapshot(&prefix.to_snapshot());
journal
.replay_from_with_baseline(Seq(3), &mut checkpoint, &Graph::new())
.unwrap();
assert_eq!(checkpoint.persisted_edges_between(from, to), expected);
let reopened = Graph::from_snapshot(&full.to_snapshot());
assert_eq!(reopened.persisted_edges_between(from, to), expected);
}
}
#[test]
fn legacy_checkpoint_empty_tail_recovers_proven_minting_attribution() {
use crate::graph::{SemanticStatementSpec, edge_data::UNKNOWN_LEGACY_ASSERTER_IRI};
let mut template =
replay_captured_deltas([add(1, "https://a.test/"), add(2, "https://b.test/")]);
let from = template.get_node_key_by_id(Uuid::from_u128(1)).unwrap();
let to = template.get_node_key_by_id(Uuid::from_u128(2)).unwrap();
template.assert_surface_semantic_statement(
from,
to,
SemanticStatementSpec {
predicate: super::super::predicate_iri(SemanticSubKind::Cites).into(),
recognized_sub_kind: Some(SemanticSubKind::Cites),
provenance_iri: Some("https://template.test/".into()),
asserted_at_ms: Some(100),
..Default::default()
},
);
let mut edges = template.persisted_edges_between(from, to);
let mut unknown = edges[0].retained_assertions()[0].clone();
unknown.statement_id = "baseline-unknown".into();
unknown.provenance_iri = None;
let mut known = unknown.clone();
known.statement_id = "baseline-source".into();
known.provenance_iri = Some("https://source.test/page".into());
known.asserted_at_ms = Some(101);
*edges[0].assertions.as_mut().unwrap() = vec![unknown.clone(), known];
let capture = |edges| CapturedDelta::ReplaySetEdgesByIds {
from_id: Uuid::from_u128(1).to_string(),
to_id: Uuid::from_u128(2).to_string(),
edges,
};
let mut baseline = template;
super::super::capture::replay_captured_deltas_onto(&mut baseline, [capture(edges.clone())]);
let mut minted = unknown;
minted.statement_id = "minted-handle".into();
minted.asserted_at_ms = Some(200);
edges[0].assertions.as_mut().unwrap().push(minted);
let minter = Author::engine("first-extractor", "1");
let mut journal = GraphJournal::new();
journal.record_as(minter.clone(), capture(edges));
let mut checkpoint = baseline.clone();
super::super::capture::replay_captured_deltas_onto(
&mut checkpoint,
journal.entries().iter().map(|entry| entry.delta.clone()),
);
let old = checkpoint.persisted_edges_between(from, to);
let old_statements = &old[0].retained_assertions();
assert_eq!(old_statements.len(), 3);
assert_eq!(
old_statements[0].provenance_iri.as_deref(),
Some(UNKNOWN_LEGACY_ASSERTER_IRI)
);
assert_eq!(
old_statements[1].provenance_iri.as_deref(),
Some("https://source.test/page")
);
assert_eq!(
old_statements[2].provenance_iri.as_deref(),
Some(UNKNOWN_LEGACY_ASSERTER_IRI)
);
checkpoint = Graph::from_snapshot(&checkpoint.to_snapshot());
let before_revision = checkpoint.revision();
let captured = Arc::new(Mutex::new(Vec::new()));
let sink = captured.clone();
checkpoint.set_recorder(Some(Arc::new(move |delta| {
sink.lock().unwrap().push(delta.clone());
})));
journal
.replay_from_with_baseline(Seq(1), &mut checkpoint, &baseline)
.unwrap();
let repaired = checkpoint.persisted_edges_between(from, to);
let statements = &repaired[0].retained_assertions();
assert_eq!(statements[2].provenance_iri, Some(minter.asserter_iri()));
assert_eq!(statements[2].statement_id, "minted-handle");
assert_eq!(statements[2].asserted_at_ms, Some(200));
assert_eq!(statements[0], old_statements[0]);
assert_eq!(statements[1], old_statements[1]);
assert!(checkpoint.revision() > before_revision);
assert!(captured.lock().unwrap().is_empty());
let full = journal
.snapshot_at_from(&baseline, Seq(1))
.unwrap()
.unwrap();
assert_eq!(repaired, full.persisted_edges_between(from, to));
}
#[test]
fn exact_capture_attribution_survives_later_authors_and_absent_checkpoint_handles() {
use crate::graph::{SemanticStatementSpec, edge_data::UNKNOWN_LEGACY_ASSERTER_IRI};
let mut template =
replay_captured_deltas([add(1, "https://a.test/"), add(2, "https://b.test/")]);
let from = template.get_node_key_by_id(Uuid::from_u128(1)).unwrap();
let to = template.get_node_key_by_id(Uuid::from_u128(2)).unwrap();
template.assert_surface_semantic_statement(
from,
to,
SemanticStatementSpec {
predicate: super::super::predicate_iri(SemanticSubKind::Cites).into(),
recognized_sub_kind: Some(SemanticSubKind::Cites),
provenance_iri: Some("https://template.test/".into()),
asserted_at_ms: Some(100),
..Default::default()
},
);
let mut edges = template.persisted_edges_between(from, to);
let mut unknown = edges[0].retained_assertions()[0].clone();
unknown.statement_id = "baseline-unknown".into();
unknown.provenance_iri = None;
let mut known = unknown.clone();
known.statement_id = "baseline-source".into();
known.provenance_iri = Some("https://source.test/page".into());
*edges[0].assertions.as_mut().unwrap() = vec![unknown.clone(), known.clone()];
let capture = |edges| CapturedDelta::ReplaySetEdgesByIds {
from_id: Uuid::from_u128(1).to_string(),
to_id: Uuid::from_u128(2).to_string(),
edges,
};
let mut baseline = template;
super::super::capture::replay_captured_deltas_onto(&mut baseline, [capture(edges.clone())]);
let minter = Author::engine("first-extractor", "1");
let updater = Author::script("later-update", "1");
let undoer = Author::rule("undo", "1");
let mut minted = unknown.clone();
minted.statement_id = "minted-handle".into();
minted.asserted_at_ms = Some(200);
edges[0].assertions.as_mut().unwrap().push(minted);
let mut journal = GraphJournal::new();
journal.record_as(minter.clone(), capture(edges.clone()));
edges[0].retained_assertions_mut()[2].asserted_at_ms = Some(201);
journal.record_as(updater.clone(), capture(edges.clone()));
let mut withdrawn = edges.clone();
*withdrawn[0].assertions.as_mut().unwrap() = vec![known];
journal.record_as(updater, capture(withdrawn));
edges[0].retained_assertions_mut()[2].asserted_at_ms = Some(202);
edges[0].retained_assertions_mut()[1].provenance_iri = None;
journal.record_as(undoer, capture(edges));
let full = journal
.snapshot_at_from(&baseline, Seq(4))
.unwrap()
.unwrap();
let expected = full.persisted_edges_between(from, to);
let statements = &expected[0].retained_assertions();
assert_eq!(statements.len(), 3);
assert_eq!(statements[0].statement_id, "baseline-unknown");
assert_eq!(statements[0].asserted_at_ms, Some(100));
assert_eq!(
statements[0].provenance_iri.as_deref(),
Some(UNKNOWN_LEGACY_ASSERTER_IRI)
);
assert_eq!(statements[1].statement_id, "baseline-source");
assert_eq!(
statements[1].provenance_iri.as_deref(),
Some("https://source.test/page")
);
assert_eq!(statements[2].statement_id, "minted-handle");
assert_eq!(statements[2].asserted_at_ms, Some(202));
assert_eq!(statements[2].provenance_iri, Some(minter.asserter_iri()));
for cursor in 0..=4 {
let prefix = journal
.snapshot_at_from(&baseline, Seq(cursor))
.unwrap()
.unwrap();
let mut checkpoint = Graph::from_snapshot(&prefix.to_snapshot());
journal
.replay_from_with_baseline(Seq(cursor), &mut checkpoint, &baseline)
.unwrap();
assert_eq!(checkpoint.persisted_edges_between(from, to), expected);
}
let withdrawn = journal
.snapshot_at_from(&baseline, Seq(3))
.unwrap()
.unwrap();
assert_eq!(
withdrawn.persisted_edges_between(from, to)[0]
.retained_assertions()
.len(),
1
);
let mut without_baseline = Graph::from_snapshot(&withdrawn.to_snapshot());
journal.replay_from(Seq(3), &mut without_baseline).unwrap();
let conservative = without_baseline.persisted_edges_between(from, to);
assert_eq!(
conservative[0].retained_assertions()[2]
.provenance_iri
.as_deref(),
Some(UNKNOWN_LEGACY_ASSERTER_IRI)
);
}
fn fingerprint(graph: &Graph) -> (Vec<String>, Vec<(String, String, String)>) {
let mut nodes: Vec<String> = graph.nodes().map(|(_, n)| n.id.to_string()).collect();
nodes.sort();
let mut edges: Vec<(String, String, String)> = graph
.relations()
.map(|rel| {
let from = graph
.get_node(rel.from)
.map(|n| n.id.to_string())
.unwrap_or_default();
let to = graph
.get_node(rel.to)
.map(|n| n.id.to_string())
.unwrap_or_default();
(from, to, format!("{:?}", rel.kind))
})
.collect();
edges.sort();
(nodes, edges)
}
#[test]
fn entries_are_attributed_and_author_scoping_works() {
let mut journal = GraphJournal::new();
journal.record(add(1, "https://a.test/"));
journal.set_author(Author::person("aa11"));
journal.record(add(2, "https://b.test/"));
journal.set_author(Author::user());
journal.record_as(
Author::engine("tarot-shuffle", "1.2").via("cleromancy"),
add(3, "https://c.test/"),
);
let authors: Vec<String> = journal
.entries()
.iter()
.map(|e| e.author.to_string())
.collect();
assert_eq!(
authors,
[
"person user",
"person aa11",
"engine tarot-shuffle 1.2 via cleromancy"
]
);
assert_eq!(journal.author(), &Author::user(), "scoping restored");
assert_eq!(
journal.replay().node_count(),
3,
"replay strips the envelope"
);
}
#[test]
fn source_time_contract_selects_immutable_journal_prefixes() {
let mut journal = GraphJournal::new();
journal.record(add(1, "https://one.test/"));
journal.record(add(2, "https://two.test/"));
assert_eq!(
journal.source_extent(),
SourceExtent {
earliest: Seq(0),
current: Seq(2),
}
);
assert_eq!(journal.source_ticks(3), [Seq(0), Seq(1), Seq(2)]);
assert_eq!(
journal
.source_snapshot(&Seq(1))
.expect("known source cursor")
.node_count(),
1
);
assert!(journal.source_snapshot(&Seq(3)).is_none());
assert_eq!(
journal.replay().node_count(),
2,
"scrubbing leaves live truth intact"
);
}
#[test]
fn an_author_writes_every_field() {
let author = Author::rule("promote-on-tag", "3").via("turnstone");
let json = serde_json::to_string(&author).unwrap();
assert_eq!(
json,
r#"{"kind":"rule","id":"promote-on-tag","version":"3","via":"turnstone"}"#
);
assert_eq!(serde_json::from_str::<Author>(&json).unwrap(), author);
let person = serde_json::to_string(&Author::user()).unwrap();
assert_eq!(
person,
r#"{"kind":"person","id":"user","version":null,"via":null}"#
);
}
#[test]
fn a_graph_records_its_own_deltas_and_a_clone_does_not() {
let seen = Arc::new(Mutex::new(Vec::new()));
let sink = Arc::clone(&seen);
let mut session = Graph::new();
session.set_recorder(Some(Arc::new(move |delta: &CapturedDelta| {
sink.lock().unwrap().push(delta.clone());
})));
assert!(session.is_recording());
let add_node = |graph: &mut Graph, id: u128| {
apply_graph_delta(
graph,
GraphDelta::AddNode {
id: Some(Uuid::from_u128(id)),
url: format!("https://{id}.test/"),
position: Point2D::new(0.0, 0.0),
},
)
};
add_node(&mut session, 1);
let mut copy = session.clone();
assert!(!copy.is_recording());
add_node(&mut copy, 2);
add_node(&mut Graph::new(), 3);
let seen = seen.lock().unwrap();
assert_live_add_captures(&seen, 1, "https://1.test/");
}
#[test]
fn replay_reproduces_visit_stamps_and_statement_ids() {
let (journal, hook) = journal_capture_hook();
set_captured_delta_hook(Some(hook));
let mut live = Graph::new();
let key = |graph: &mut Graph, id: u128| match apply_graph_delta(
graph,
GraphDelta::AddNode {
id: Some(Uuid::from_u128(id)),
url: format!("https://{id}.test/"),
position: Point2D::new(0.0, 0.0),
},
) {
GraphDeltaResult::NodeAdded(key) => key,
other => panic!("expected NodeAdded, got {other:?}"),
};
let a = key(&mut live, 1);
std::thread::sleep(std::time::Duration::from_millis(2));
let b = key(&mut live, 2);
apply_graph_delta(
&mut live,
GraphDelta::AssertRelation {
asserter_iri: crate::graph::journal::Author::user().asserter_iri(),
from: a,
to: b,
assertion: EdgeAssertion::Semantic {
sub_kind: SemanticSubKind::Cites,
label: None,
},
},
);
apply_graph_delta(
&mut live,
GraphDelta::AssertSemanticPredicate {
asserter_iri: crate::graph::journal::Author::user().asserter_iri(),
from: b,
to: a,
predicate: "https://schema.org/about".into(),
},
);
set_captured_delta_hook(None);
std::thread::sleep(std::time::Duration::from_millis(2));
let replayed = journal.lock().unwrap().replay();
for id in [1u128, 2] {
let visited = |graph: &Graph| {
let (key, _) = graph.get_node_by_id(Uuid::from_u128(id)).unwrap();
graph.node_last_visited(key)
};
assert!(
visited(&live).is_some(),
"creating node {id} stamped a visit"
);
assert_eq!(
visited(&replayed),
visited(&live),
"node {id}'s visit stamp"
);
}
let key_of = |graph: &Graph, key| {
let id = live.get_node(key).unwrap().id;
graph.get_node_key_by_id(id).unwrap()
};
for (from, to) in [(a, b), (b, a)] {
let resource_pair = (
live.shown_resource_id(from).unwrap(),
live.shown_resource_id(to).unwrap(),
);
assert!(live.persisted_edges_between(from, to).is_empty());
assert!(
!live
.persisted_resource_edges_between(resource_pair.0, resource_pair.1)
.is_empty(),
"the live Resource graph holds a minted statement there"
);
assert_eq!(
replayed.shown_resource_id(key_of(&replayed, from)),
Some(resource_pair.0)
);
assert_eq!(
replayed.shown_resource_id(key_of(&replayed, to)),
Some(resource_pair.1)
);
assert_eq!(
replayed.persisted_resource_edges_between(resource_pair.0, resource_pair.1),
live.persisted_resource_edges_between(resource_pair.0, resource_pair.1),
"statement ids survive replay"
);
}
}
#[test]
fn replay_records_nothing() {
let (hooked, hook) = journal_capture_hook();
set_captured_delta_hook(Some(hook));
let seen = Arc::new(Mutex::new(0usize));
let sink = Arc::clone(&seen);
let mut session = Graph::new();
session.set_recorder(Some(Arc::new(move |_: &CapturedDelta| {
*sink.lock().unwrap() += 1;
})));
apply_graph_delta(
&mut session,
GraphDelta::AddNode {
id: Some(Uuid::from_u128(1)),
url: "https://a.test/".to_string(),
position: Point2D::new(0.0, 0.0),
},
);
assert_live_add_captures(
&hooked
.lock()
.unwrap()
.entries()
.iter()
.map(|entry| entry.delta.clone())
.collect::<Vec<_>>(),
1,
"https://a.test/",
);
assert_eq!(
hooked.lock().unwrap().len(),
4,
"the thread hook sees live edits"
);
assert_eq!(
*seen.lock().unwrap(),
4,
"the graph's recorder sees live edits"
);
let history = hooked.lock().unwrap().clone();
let scrubbed = history.snapshot_at(history.live_cursor()).unwrap().unwrap();
replay_captured_deltas_onto(&mut session, [add(2, "https://b.test/")]);
assert_eq!(scrubbed.node_count(), 1);
assert_eq!(session.node_count(), 2);
assert_eq!(
hooked.lock().unwrap().len(),
4,
"replay reached the thread hook"
);
assert_eq!(
*seen.lock().unwrap(),
4,
"replay reached the graph's recorder"
);
assert!(session.is_recording());
apply_graph_delta(
&mut session,
GraphDelta::AddNode {
id: Some(Uuid::from_u128(3)),
url: "https://c.test/".to_string(),
position: Point2D::new(0.0, 0.0),
},
);
let captures = hooked
.lock()
.unwrap()
.entries()
.iter()
.map(|entry| entry.delta.clone())
.collect::<Vec<_>>();
assert_eq!(captures.len(), 8);
assert_live_add_captures(&captures[4..], 3, "https://c.test/");
assert_eq!(*seen.lock().unwrap(), 8);
set_captured_delta_hook(None);
}
#[test]
fn records_and_replays_reconstruct_the_graph() {
let mut journal = GraphJournal::new();
journal.record(add(1, "https://a.test/"));
journal.record(add(2, "https://b.test/"));
journal.record(CapturedDelta::ReplayAssertRelationByIds {
from_id: Uuid::from_u128(1).to_string(),
to_id: Uuid::from_u128(2).to_string(),
assertion: EdgeAssertion::Semantic {
sub_kind: SemanticSubKind::Cites,
label: None,
},
});
journal.record(CapturedDelta::ReplaySetNodeTitleById {
node_id: Uuid::from_u128(1).to_string(),
title: "Paper A".to_string(),
});
let graph = journal.replay();
assert_eq!(graph.node_count(), 2);
assert_eq!(graph.relations().count(), 1, "the cites relation replayed");
let (_, node) = graph
.get_node_by_id(Uuid::from_u128(1))
.expect("node a present");
assert_eq!(node.title, "Paper A", "the content edit replayed too");
}
#[test]
fn prefix_cursors_replay_historical_graphs_without_touching_live_history() {
let mut journal = GraphJournal::new();
journal.record(add(1, "https://a.test/"));
journal.record(add(2, "https://b.test/"));
journal.record(CapturedDelta::ReplayAssertRelationByIds {
from_id: Uuid::from_u128(1).to_string(),
to_id: Uuid::from_u128(2).to_string(),
assertion: EdgeAssertion::Semantic {
sub_kind: SemanticSubKind::Cites,
label: None,
},
});
assert_eq!(journal.earliest_cursor(), Seq(0));
assert_eq!(journal.live_cursor(), Seq(3));
assert_eq!(
journal.snapshot_at(Seq(0)).unwrap().unwrap().node_count(),
0
);
assert_eq!(
journal.snapshot_at(Seq(1)).unwrap().unwrap().node_count(),
1
);
let historical = journal.snapshot_at(Seq(2)).unwrap().expect("known prefix");
assert_eq!(historical.node_count(), 2);
assert_eq!(historical.relations().count(), 0);
assert_eq!(
journal
.snapshot_at(Seq(3))
.unwrap()
.unwrap()
.relations()
.count(),
1
);
assert!(
journal.snapshot_at(Seq(4)).unwrap().is_none(),
"stale cursors refuse"
);
assert_eq!(
journal.replay().relations().count(),
1,
"live history remains live"
);
assert_eq!(journal.sequence_ticks(3), vec![Seq(0), Seq(1), Seq(3)]);
}
#[test]
fn fork_carries_history_then_diverges() {
let mut source = GraphJournal::with_id(LogId::new("source"));
source.record(add(1, "https://a.test/"));
source.record(add(2, "https://b.test/"));
let mut fork = source.fork(LogId::new("fork"));
assert_eq!(
fork.entries(),
source.entries(),
"the fork copies the history"
);
let provenance = fork.provenance().expect("a fork has provenance");
assert_eq!(provenance.source, Some(LogId::new("source")));
assert_eq!(provenance.at, Seq(source.len() as u64));
fork.record(add(3, "https://c.test/"));
assert_eq!(source.replay().node_count(), 2, "source unchanged");
assert_eq!(fork.replay().node_count(), 3);
}
#[test]
fn journal_round_trips_through_a_muniment_slot() {
use muniment::{JsonSlots, MemoryBackend};
pollster::block_on(async {
let slots = JsonSlots::new(MemoryBackend::new());
let mut journal = GraphJournal::new();
journal.record(add(1, "https://a.test/"));
journal.record(add(2, "https://b.test/"));
journal.save(&slots, "journal").await.unwrap();
let reloaded = GraphJournal::load(&slots, "journal").await.unwrap();
assert_eq!(reloaded.len(), 2, "the log survived the round trip");
assert_eq!(
fingerprint(&reloaded.replay()),
fingerprint(&journal.replay()),
"the reloaded journal replays to the same graph"
);
});
}
#[test]
fn the_capture_hook_feeds_the_journal_and_replay_matches_live() {
let (journal, hook) = journal_capture_hook();
set_captured_delta_hook(Some(hook));
let mut live = Graph::new();
let a = match apply_graph_delta(
&mut live,
GraphDelta::AddNode {
id: Some(Uuid::from_u128(1)),
url: "https://a.test/".to_string(),
position: Point2D::new(0.0, 0.0),
},
) {
GraphDeltaResult::NodeAdded(key) => key,
other => panic!("expected NodeAdded, got {other:?}"),
};
let b = match apply_graph_delta(
&mut live,
GraphDelta::AddNode {
id: Some(Uuid::from_u128(2)),
url: "https://b.test/".to_string(),
position: Point2D::new(1.0, 0.0),
},
) {
GraphDeltaResult::NodeAdded(key) => key,
other => panic!("expected NodeAdded, got {other:?}"),
};
apply_graph_delta(
&mut live,
GraphDelta::AssertRelation {
asserter_iri: crate::graph::journal::Author::user().asserter_iri(),
from: a,
to: b,
assertion: EdgeAssertion::Semantic {
sub_kind: SemanticSubKind::Cites,
label: None,
},
},
);
apply_graph_delta(
&mut live,
GraphDelta::SetNodeTitle {
key: a,
title: "Paper A".to_string(),
},
);
set_captured_delta_hook(None);
let replayed = journal.lock().unwrap().replay();
assert_eq!(
fingerprint(&replayed),
fingerprint(&live),
"replay of the captured journal reconstructs the live graph"
);
let (_, node) = replayed.get_node_by_id(Uuid::from_u128(1)).expect("node a");
assert_eq!(node.title, "Paper A");
}
}