Skip to main content

spacedb_sim/
lib.rs

1#![forbid(unsafe_code)]
2//! # spacedb-sim — a deterministic digital twin of the database
3//!
4//! A discrete-event simulator that runs a population of **real** [`CrdtDoc`] replicas
5//! gossiping the **real** anti-entropy protocol over a modeled network — latency,
6//! jitter, packet loss, partitions, and churn — all driven by a single seeded
7//! [`Rng`]. The same [`Scenario`] and seed produce a byte-identical [`SimReport`], so
8//! the simulator is a reproducible instrument: you can ask "do 500 replicas still
9//! converge under 20% loss and a mid-run partition?" and get the same answer every
10//! time, then bisect a regression against it.
11//!
12//! It is a twin of the **database** only — open-core, no maestro/Iron-Bank (the full
13//! economic twin is a separate, proprietary system). Live state can be
14//! rendered through [`observations`] into the `spacedb-console` dashboard.
15//!
16//! ```
17//! use spacedb_sim::{Scenario, Simulation, NetworkModel};
18//! let mut sc = Scenario::new(7, 50);
19//! sc.network = NetworkModel::new(20, 10, 0.1); // 20±10 tick latency, 10% loss
20//! let report = Simulation::new(sc).run();
21//! assert!(report.converged);
22//! ```
23//!
24//! [`CrdtDoc`]: spacedb_crdt::CrdtDoc
25
26mod rng;
27pub use rng::Rng;
28
29mod scheduler;
30pub use scheduler::Scheduler;
31
32mod network;
33pub use network::{NetworkModel, Partition};
34
35mod sim;
36pub use sim::{OfflineSpec, PartitionSpec, Scenario, SimReport, Simulation};
37
38mod churn;
39pub use churn::{ChurnReport, ChurnScenario, ChurnSim};
40
41mod strong;
42pub use strong::{StrongReport, StrongScenario, StrongSim};
43
44mod causal;
45pub use causal::{CausalReport, CausalScenario, CausalSim};
46
47mod console;
48pub use console::{churn_observations, observations};
49
50/// Compiles the README's examples as doctests, so the documented API can never
51/// drift from the real one. Not part of the public API, and not rendered into
52/// the crate docs — it exists only under `cargo test --doc`.
53#[cfg(doctest)]
54#[doc = include_str!("../README.md")]
55pub struct ReadmeDoctests;