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, churn — all driven by one seeded RNG. The same
scenario and seed produce a byte-identical report, so the simulator is a
reproducible instrument: ask "do 500 replicas still converge under 20% loss
and a mid-run partition?", get the same answer every time, and bisect a
regression against it.
Part of SpaceDB. Dual-licensed MIT OR Apache-2.0.
[]
= "0.7"
Convergence under a hostile network
use ;
let mut sc = new; // seed 7, 50 replicas
sc.network = new; // 20±10 tick latency, 10% loss
let report = new.run;
assert!;
println!;
Scenario also carries partition: Option<PartitionSpec> and
offline: Vec<OfflineSpec> so you can split the network mid-run and take
individual replicas down. SimReport is honest about the outcome: converged,
converged_at, worst_lag (how far the most-behind replica still is),
messages_sent / dropped / delivered, and final_value.
The other three sims
| Sim | Scenario | Reports |
|---|---|---|
ChurnSim |
homes failing and rejoining across failure domains, with erasure-coded shards, a repair loop and a reclaim loop | ChurnReport — did durability hold through the churn? |
StrongSim |
quorum members partitioning and healing | StrongReport — did the strong tier ever commit divergently? (it must not) |
CausalSim |
sessions reading across lagging replicas | CausalReport — were read-your-writes / monotonic reads ever violated? |
Feeding the console
use ;
use ;
use ;
let mut sim = new;
let _report = sim.run;
let now = 1_700_000_000;
let dash = assemble;
The simulator emits the same observation DTOs the real fleet does, so
spacedb-console renders a simulated fleet exactly as it
renders a live one.
Determinism
Rng is a seeded PRNG, Scheduler is a deterministic event queue, and nothing
in the crate reads a wall clock or OS entropy. Same seed → identical run, on any
machine. That is the whole value: a failure you can replay.
Scope
This is a twin of the database — open-core, no maestro / Iron Bank. The full economic twin is a separate, proprietary system.
Performance (0.7.2)
Measured on exact instruction counts (callgrind) with deterministic drivers
whose outputs did not change; release build, 0.7.1 -> 0.7.2:
ir_sim 1,665.1M -> 1,635.1M (-1.8%).
- No code change here: the gain is
spacedb-crdt's cheaper transactions.
Performance (0.7.0)
Measured on exact instruction counts (callgrind) with this crate's
deterministic driver, examples/ir_sim.rs; outputs unchanged by every change.
Release build, 0.6.0 -> 0.7.0: 2,060.5M -> 1,663.3M instructions (-19.3%); every report identical.
- Replicas are
CrdtDoc::new_unlogged(they sync by state vector or full state, so nothing drains a local-update log). - The churn twin skips a repair when health shows every shard reachable and a reclaim when there is no surplus - both would return empty reports.
- The strong twin formats its agent, username and member names once.
- Causal fan-out shares one encoded state between recipients.
- The simulator doubles as the instruction-count driver (
examples/ir_sim.rs) for the crates it runs: crdt, replica, consistency and durability.
Testing
The workspace defaults to wasm32; this crate is native. Test on your host
triple:
Suites: sim.rs (convergence, determinism, partition), churn.rs (durability
through failure + repair), stress.rs (large populations, heavy loss).
License
MIT OR Apache-2.0, at your option. See LICENSE-MIT and LICENSE-APACHE.