Expand description
§spacedb-sim — a deterministic digital twin of the database
A discrete-event simulator that runs a population of real CrdtDoc replicas
gossiping the real anti-entropy protocol over a modeled network — latency,
jitter, packet loss, partitions, and churn — all driven by a single seeded
Rng. The same Scenario and seed produce a byte-identical SimReport, so
the simulator is a reproducible instrument: you can ask “do 500 replicas still
converge under 20% loss and a mid-run partition?” and get the same answer every
time, then bisect a regression against it.
It is a twin of the database only — open-core, no maestro/Iron-Bank (the full
economic twin is a separate, proprietary system). Live state can be
rendered through observations into the spacedb-console dashboard.
use spacedb_sim::{Scenario, Simulation, NetworkModel};
let mut sc = Scenario::new(7, 50);
sc.network = NetworkModel::new(20, 10, 0.1); // 20±10 tick latency, 10% loss
let report = Simulation::new(sc).run();
assert!(report.converged);Structs§
- Causal
Report - The outcome of a causal stress run.
- Causal
Scenario - Everything that defines a causal stress run.
- Causal
Sim - A running causal-consistency stress simulation.
- Churn
Report - The outcome of a churn run — identical for any two runs of the same scenario.
- Churn
Scenario - Everything that defines a churn run.
- Churn
Sim - A running durability-under-churn simulation.
- Network
Model - Per-message network behaviour.
- Offline
Spec - A window during which one replica is offline (it still writes locally — local-first — and re-syncs on return).
- Partition
- A two-sided network partition: replicas on different sides cannot reach each other until it heals.
- Partition
Spec - A network partition window splitting
group_afrom everyone else. - Rng
- A deterministic random source.
- Scenario
- Everything that defines a run. Same scenario + same seed ⇒ identical result.
- Scheduler
- A virtual-time event scheduler.
- SimReport
- The outcome of a run — the same for any two runs of the same scenario.
- Simulation
- A running simulation.
- Strong
Report - The outcome of a strong-tier stress run.
- Strong
Scenario - Everything that defines a strong-tier stress run.
- Strong
Sim - A running strong-tier stress simulation.
Functions§
- churn_
observations - Build a console snapshot of a churn simulation: each home, and the sealed
snapshot as one shard entry whose reachable/target/floor map to the durability
layer’s
(reachable, n, k)— so the console’s own under-replicated / at-risk / lost logic reports the snapshot’s health. - observations
- Build a console snapshot of the current simulation state: each replica as a home, and the worst convergence lag as the shared collection’s lag.