mdcs_delta/
lib.rs

1//! MDCS Delta - Delta-state CRDT machinery
2//!
3//! This crate implements the δ-CRDT framework including:
4//! - Delta buffers for grouping and batching
5//! - Delta-mutators for each CRDT type
6//! - Anti-entropy Algorithm 1 (convergence mode)
7//! - Anti-entropy Algorithm 2 (causal consistency mode)
8//!
9//! # δ-CRDT Framework
10//!
11//! The δ-CRDT (delta-state CRDT) framework provides efficient synchronization
12//! by only transmitting the changes (deltas) rather than full state.
13//!
14//! ## Key Concepts
15//!
16//! - **Delta-mutator**: A function `mδ` such that `m(X) = X ⊔ mδ(X)`
17//! - **Delta buffer**: Accumulates deltas for batched transmission
18//! - **Anti-entropy**: Protocol for eventually consistent synchronization
19//!
20//! ## Algorithm 1: Convergence Mode
21//!
22//! Guarantees eventual convergence without causal ordering.
23//!
24//! ```text
25//! On local mutation m:
26//!   d = mδ(X)     // compute delta
27//!   X = X ⊔ d     // apply to local state
28//!   D.push(d)     // buffer for sending
29//!
30//! On send to peer j:
31//!   send D[acked[j]..] to j
32//!
33//! On receive delta d from peer i:
34//!   X = X ⊔ d     // apply (idempotent!)
35//!   send ack(seq) to i
36//! ```
37//!
38//! ## Algorithm 2: Causal Consistency Mode
39//!
40//! Guarantees causal ordering of delta delivery using delta-intervals.
41//!
42//! ```text
43//! Durable state: (Xᵢ, cᵢ)  - survives crashes
44//! Volatile state: (Dᵢ, Aᵢ) - lost on crash
45//!
46//! On local mutation m:
47//!   cᵢ := cᵢ + 1
48//!   d := mδ(Xᵢ)
49//!   Xᵢ := Xᵢ ⊔ d
50//!   ∀j: Dᵢ[j] := Dᵢ[j] ⊔ d
51//!
52//! On send to peer j:
53//!   send ⟨Dᵢ[j], Aᵢ[j]+1, cᵢ⟩ to j
54//!
55//! On receive ⟨d, n, m⟩ from peer j:
56//!   if n = Aᵢ[j] + 1 then   // causally ready
57//!     Xᵢ := Xᵢ ⊔ d
58//!     Aᵢ[j] := m
59//!     send ack(m) to j
60//!   else
61//!     buffer for later
62//! ```
63//!
64//! # Example
65//!
66//! ```rust,ignore
67//! use mdcs_delta::buffer::DeltaReplica;
68//! use mdcs_core::gset::GSet;
69//!
70//! let mut replica: DeltaReplica<GSet<i32>> = DeltaReplica::new("replica1");
71//!
72//! // Mutate using delta-mutator
73//! replica.mutate(|_state| {
74//!     let mut delta = GSet::new();
75//!     delta.insert(42);
76//!     delta
77//! });
78//!
79//! assert!(replica.state().contains(&42));
80//! ```
81
82pub mod anti_entropy;
83pub mod buffer;
84pub mod causal;
85pub mod mutators;
86
87// Re-export main types for convenience
88pub use buffer::{AckTracker, DeltaBuffer, DeltaReplica, ReplicaId, SeqNo, TaggedDelta};
89
90pub use anti_entropy::{AntiEntropyCluster, AntiEntropyMessage, NetworkConfig, NetworkSimulator};
91
92pub use causal::{
93    CausalCluster, CausalMessage, CausalNetworkSimulator, CausalReplica, DeltaInterval,
94    DurableState, DurableStorage, IntervalAck, MemoryStorage, PeerDeltaBuffer, StorageError,
95    VolatileState,
96};
97
98pub use mutators::{gset as gset_mutators, orset as orset_mutators};
mdcs_delta/lib.rs

mdcs_delta/
lib.rs
