Add History type and merge-commit model to graph-storage (#4238)

* Add History type and merge-commit model to graph-storage

* Add History::merge with canonical-sort convergence to graph-storage

* Append merge delta without re-sorting the whole history

* Resurrect across merges by searching all ancestors, not the primary chain

Author: TrueDoctor

document/graph-storage/src/crdt.rs

@@ -11,7 +11,8 @@ use serde::{Deserialize, Serialize};
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct Delta {
 	pub id: Rev,
-	pub parents: Vec<Rev>,
+	/// Primary parent; `None` for the root delta.
+	pub parent: Option<Rev>,
 	pub author: PeerId,
 	pub timestamp: TimeStamp,
 	pub kind: RegistryDelta,
@@ -24,11 +25,11 @@ pub struct Delta {
 }
 
 impl Delta {
-	pub fn new(parents: Vec<Rev>, author: PeerId, timestamp: TimeStamp, kind: RegistryDelta, reverse: RegistryDelta) -> Self {
-		let id = compute_rev(&parents, author, timestamp, &kind);
+	pub fn new(parent: Option<Rev>, author: PeerId, timestamp: TimeStamp, kind: RegistryDelta, reverse: RegistryDelta) -> Self {
+		let id = compute_rev(parent, author, timestamp, &kind);
 		Self {
 			id,
-			parents,
+			parent,
 			author,
 			timestamp,
 			kind,
@@ -37,6 +38,35 @@ impl Delta {
 		}
 	}
 
+	/// Build a merge delta joining `tips` into one node. See [`RegistryDelta::Merge`] for the semantics.
+	pub fn merge(tips: impl IntoIterator<Item = Rev>, author: PeerId, timestamp: TimeStamp) -> Self {
+		let mut parents: Vec<Rev> = tips.into_iter().collect();
+		parents.sort_unstable();
+		parents.dedup();
+		let parent = parents.first().copied();
+		let extra_parents = parents.split_first().map(|(_, rest)| rest.to_vec()).unwrap_or_default();
+		let kind = RegistryDelta::Merge { extra_parents };
+		let id = compute_rev(parent, author, timestamp, &kind);
+		Self {
+			id,
+			parent,
+			author,
+			timestamp,
+			reverse: kind.clone(),
+			kind,
+			attributes: Attributes::default(),
+		}
+	}
+
+	/// Every parent: the primary `parent` (absent for the root) plus a merge's `extra_parents`.
+	pub fn all_parents(&self) -> impl Iterator<Item = Rev> + '_ {
+		let extras = match &self.kind {
+			RegistryDelta::Merge { extra_parents } => extra_parents.as_slice(),
+			_ => &[],
+		};
+		self.parent.into_iter().chain(extras.iter().copied())
+	}
+
 	/// Mark this delta as the last op of a user interaction, so the undo cursor treats it as a checkpoint.
 	pub fn mark_interaction_end(&mut self, timestamp: TimeStamp) {
 		self.attributes.set(attr::delta::INTERACTION_END, serde_json::Value::Bool(true), timestamp);
@@ -47,9 +77,9 @@ impl Delta {
 	}
 
 	/// The content-addressed `Rev` this delta's identity fields hash to. Equals `id` for a delta built
-	/// via `new`; differs only if `id` was tampered with or the hash derivation changed.
+	/// via `new`/`merge`; differs only if `id` was tampered with or the hash derivation changed.
 	pub fn recomputed_id(&self) -> Rev {
-		compute_rev(&self.parents, self.author, self.timestamp, &self.kind)
+		compute_rev(self.parent, self.author, self.timestamp, &self.kind)
 	}
 
 	/// Whether `id` matches the recomputed content hash. `Delta` deserializes without checking this
@@ -148,6 +178,13 @@ pub enum RegistryDelta {
 	ChangeDocumentAttribute {
 		delta: AttributeDelta,
 	},
+	/// Joins divergent history tips into one shared node. A registry no-op on replay (it only collapses
+	/// tips so `head` stays a single `Rev`); the joined tips are `Delta::parent` (the lowest `Rev`) plus
+	/// these `extra_parents` (sorted). Identity is the parent set alone, so two peers merging the same
+	/// tips mint the identical delta and it dedups.
+	Merge {
+		extra_parents: Vec<Rev>,
+	},
 	// Allow for future delta types without a model change
 	Other(serde_json::Value),
 }

document/graph-storage/src/document.rs

@@ -1,8 +1,7 @@
 use crate::{
-	CrdtError, Delta, ExportSlot, HotOp, LamportClock, MAX_EXPORT_SLOTS, NetworkId, NodeId, NodeInput, PeerId, Registry, RegistryDelta, ResourceEntry, Rev, SourceValue, TimeStamp,
+	CrdtError, Delta, ExportSlot, History, HotOp, LamportClock, MAX_EXPORT_SLOTS, NetworkId, NodeId, NodeInput, PeerId, Registry, RegistryDelta, ResourceEntry, Rev, SourceValue, TimeStamp,
 	apply_attribute_delta, reverse_attribute_delta,
 };
-use std::collections::HashMap;
 
 #[derive(Clone, Debug)]
 pub struct Document {
@@ -20,9 +19,10 @@ pub struct Document {
 	/// working registry keeps the staging-time timestamps. Benign while the local monotonic clock makes
 	/// new edits win
 	pub(crate) retired_snapshot: Registry,
-	/// User's cursor in their local history chain.
-	pub(crate) head: Rev,
-	pub(crate) history: HashMap<Rev, Delta>,
+	/// User's cursor in their local history chain. `None` on an empty document (no commits yet).
+	pub(crate) head: Option<Rev>,
+	/// Retired delta DAG in topological (append) order. See [`History`](crate::History).
+	pub(crate) history: History,
 	/// Revs undone past (most-recent last), so `redo` can re-apply them. Local-view state the DAG can't
 	/// recover (a parent may have several children). A new edit while non-empty clears it.
 	pub(crate) redo_stack: Vec<Rev>,
@@ -52,34 +52,50 @@ impl Document {
 
 	pub(crate) fn restore_node_from_history(&mut self, target: RegistryTarget, node_id: NodeId) -> Result<(), CrdtError> {
 		let delta = self
-			.history_iter()
-			.find(|d| matches!(d.reverse, RegistryDelta::AddNode { id, .. } if id == node_id))
-			.ok_or(CrdtError::NodeNotInHistory(node_id))?
-			.clone();
+			.find_in_ancestry(|d| matches!(d.reverse, RegistryDelta::AddNode { id, .. } if id == node_id))
+			.ok_or(CrdtError::NodeNotInHistory(node_id))?;
 		self.revert_delta(target, delta)
 	}
 
 	pub(crate) fn restore_network_from_history(&mut self, target: RegistryTarget, network_id: NetworkId) -> Result<(), CrdtError> {
 		// Find the Delta whose forward op removed this network. Its `reverse` is `AddNetwork`,
 		// which is what we want to re-apply.
 		let delta = self
-			.history_iter()
-			.find(|d| matches!(d.reverse, RegistryDelta::AddNetwork { id, .. } if id == network_id))
-			.ok_or(CrdtError::NetworkNotInHistory(network_id))?
-			.clone();
+			.find_in_ancestry(|d| matches!(d.reverse, RegistryDelta::AddNetwork { id, .. } if id == network_id))
+			.ok_or(CrdtError::NetworkNotInHistory(network_id))?;
 		self.revert_delta(target, delta)
 	}
 
+	/// Search every delta reachable from `head` (following all parents, including a merge's
+	/// `extra_parents`) for the first matching `predicate`, breadth-first. Resurrection needs full
+	/// ancestry reachability, so a node added only on a merged-in branch is still found.
+	fn find_in_ancestry(&self, predicate: impl Fn(&Delta) -> bool) -> Option<Delta> {
+		let mut queue: std::collections::VecDeque<Rev> = self.head.into_iter().collect();
+		let mut seen: std::collections::HashSet<Rev> = self.head.into_iter().collect();
+		while let Some(rev) = queue.pop_front() {
+			let Some(delta) = self.history.get(rev) else { continue };
+			if predicate(delta) {
+				return Some(delta.clone());
+			}
+			for parent in delta.all_parents() {
+				if seen.insert(parent) {
+					queue.push_back(parent);
+				}
+			}
+		}
+		None
+	}
+
 	/// Apply a delta's `reverse` as the new forward op (silent-zone undo). Force-applied: structural
 	/// ops are idempotent, and LWW arms assign the reverse value unconditionally even though it carries
 	/// the same timestamp as the forward op it undoes.
 	pub(crate) fn revert_delta(&mut self, target: RegistryTarget, mut delta: Delta) -> Result<(), CrdtError> {
-		std::mem::swap(&mut delta.kind, &mut delta.reverse);
-		for parent in &delta.parents {
-			if !self.history.contains_key(parent) {
-				return Err(CrdtError::NotFoundInHistory(*parent));
+		for parent in delta.all_parents() {
+			if !self.history.contains(parent) {
+				return Err(CrdtError::NotFoundInHistory(parent));
 			}
 		}
+		std::mem::swap(&mut delta.kind, &mut delta.reverse);
 		self.apply_op_with(target, delta.kind, delta.timestamp, ApplyMode::Force)
 	}
 
@@ -104,13 +120,13 @@ impl Document {
 	/// targets, Remove on missing ones) since hot ops already produced the structural state.
 	/// The point is to bump field timestamps to T_retire via the LWW arms.
 	pub fn apply_delta(&mut self, delta: Delta) -> Result<(), CrdtError> {
-		for parent in &delta.parents {
-			if !self.history.contains_key(parent) {
-				return Err(CrdtError::NotFoundInHistory(*parent));
+		for parent in delta.all_parents() {
+			if !self.history.contains(parent) {
+				return Err(CrdtError::NotFoundInHistory(parent));
 			}
 		}
 		self.apply_op_idempotent(delta.kind.clone(), delta.timestamp)?;
-		self.history.insert(delta.id, delta);
+		self.history.push(delta);
 		Ok(())
 	}
 
@@ -271,7 +287,8 @@ impl Document {
 			RegistryDelta::ChangeDocumentAttribute { delta } => {
 				apply_attribute_delta(delta, timestamp, force, &mut registry.attributes);
 			}
-			RegistryDelta::Other(_) => {}
+			// Merge is a structural sync point only; it mutates no registry state.
+			RegistryDelta::Merge { .. } | RegistryDelta::Other(_) => {}
 		}
 		Ok(())
 	}
@@ -407,35 +424,10 @@ impl Document {
 				let snapshot = registry.resources.get(&id).cloned().unwrap_or_default();
 				RegistryDelta::AddResource { id, entry: snapshot }
 			}
+			RegistryDelta::Merge { extra_parents } => RegistryDelta::Merge { extra_parents: extra_parents.clone() },
 			&RegistryDelta::Other(_) => RegistryDelta::Other(serde_json::Value::Null),
 		})
 	}
-
-	/// Retired-only walk from `head` along first parents. Hot ops are excluded by design.
-	fn history_iter(&self) -> HistoryIter<'_> {
-		HistoryIter {
-			document: self,
-			parent_rev: self.head,
-		}
-	}
-}
-
-struct HistoryIter<'a> {
-	document: &'a Document,
-	parent_rev: Rev,
-}
-
-impl<'a> Iterator for HistoryIter<'a> {
-	type Item = &'a Delta;
-
-	fn next(&mut self) -> Option<Self::Item> {
-		let delta = self.document.history.get(&self.parent_rev)?;
-		// First parent only for now. Local-chain walking (filter by author) is a follow-up. The root
-		// delta has no parents, so fall back to the `0` sentinel: the next `get` misses and ends the
-		// walk *after* yielding the root (using `?` here would drop the root instead).
-		self.parent_rev = delta.parents.first().copied().unwrap_or(0);
-		Some(delta)
-	}
 }
 
 /// Which of a [`Document`]'s two registries an apply targets: the working copy (retired state plus