mdcs_core/lib.rs
1//! # mdcs-core
2//!
3//! Core CRDT types and traits for the **Carnelia** Merkle-Delta CRDT Store.
4//!
5//! This crate provides the foundational building blocks for conflict-free
6//! replicated data types (CRDTs). Every type implements the [`Lattice`] trait,
7//! which models a join-semilattice and guarantees **Strong Eventual Consistency**:
8//! all replicas converge to the same state regardless of message order.
9//!
10//! ## Mathematical Foundation
11//!
12//! A join-semilattice $(S, \sqcup)$ satisfies three properties:
13//!
14//! | Property | Definition |
15//! |---|---|
16//! | **Commutativity** | $a \sqcup b = b \sqcup a$ |
17//! | **Associativity** | $(a \sqcup b) \sqcup c = a \sqcup (b \sqcup c)$ |
18//! | **Idempotence** | $a \sqcup a = a$ |
19//!
20//! These guarantees mean that updates can be applied in **any order**, **any
21//! number of times**, and the result is always deterministic.
22//!
23//! ## CRDT Types
24//!
25//! | Type | Module | Description |
26//! |---|---|---|
27//! | [`GSet`] | [`gset`] | Grow-only set — elements can only be added |
28//! | [`ORSet`] | [`orset`] | Observed-Remove set — add-wins semantics |
29//! | [`PNCounter`] | [`pncounter`] | Increment/decrement counter |
30//! | [`LWWRegister`] | [`lwwreg`] | Last-Writer-Wins register |
31//! | [`MVRegister`] | [`mvreg`] | Multi-Value register — preserves concurrent writes |
32//! | [`CRDTMap`] | [`map`] | Composable map with shared causal context |
33//!
34//! ## Quick Start
35//!
36//! ```rust
37//! use mdcs_core::prelude::*;
38//!
39//! // Create two replicas of a grow-only set
40//! let mut a = GSet::new();
41//! let mut b = GSet::new();
42//!
43//! a.insert(1);
44//! b.insert(2);
45//!
46//! // Merge — order doesn't matter
47//! let merged = a.join(&b);
48//! assert!(merged.contains(&1));
49//! assert!(merged.contains(&2));
50//! ```
51//!
52//! ## Feature: Delta-State Support
53//!
54//! Types that implement [`DeltaCRDT`] support efficient delta-state
55//! replication. Instead of shipping full state, only incremental changes
56//! (deltas) are transmitted. See the [`mdcs-delta`](https://docs.rs/mdcs-delta)
57//! crate for the anti-entropy protocol that drives synchronization.
58
59pub mod gset;
60pub mod lattice;
61pub mod lwwreg;
62pub mod map;
63pub mod mvreg;
64pub mod orset;
65pub mod pncounter;
66
67// Re-exports for convenience
68pub use gset::GSet;
69pub use lattice::{DeltaCRDT, Lattice};
70pub use lwwreg::LWWRegister;
71pub use map::{CRDTMap, CausalContext, MapValue};
72pub use mvreg::MVRegister;
73pub use orset::ORSet;
74pub use pncounter::PNCounter;
75
76/// Prelude module — import everything you need with `use mdcs_core::prelude::*`.
77pub mod prelude {
78 pub use crate::gset::GSet;
79 pub use crate::lattice::{DeltaCRDT, Lattice};
80 pub use crate::lwwreg::LWWRegister;
81 pub use crate::map::{CRDTMap, CausalContext, MapValue};
82 pub use crate::mvreg::MVRegister;
83 pub use crate::orset::ORSet;
84 pub use crate::pncounter::PNCounter;
85}