spacedb-sim 0.7.3

A deterministic discrete-event simulator for SpaceDB — a population of real CRDT replicas gossiping the real SyncMessage protocol over a modeled network (latency, loss, partition, churn). Same seed -> identical run. Tests convergence, durability, and honest state under load and noise. Phase 1 SpaceDB Mission, spacedb-sim S1.
Documentation

spacedb-sim

crates.io docs.rs License: MIT OR Apache-2.0 Remade With Rust By Mata Network

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.

[dev-dependencies]

spacedb-sim = "0.7"

Convergence under a hostile network

use spacedb_sim::{NetworkModel, Scenario, Simulation};

let mut sc = Scenario::new(7, 50);                    // seed 7, 50 replicas
sc.network = NetworkModel::new(20, 10, 0.1);          // 20±10 tick latency, 10% loss
let report = Simulation::new(sc).run();

assert!(report.converged);
println!("converged at tick {:?} after {} sync rounds, {} msgs dropped",
         report.converged_at, report.sync_rounds, report.messages_dropped);

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 spacedb_sim::{observations, churn_observations};
use spacedb_console::{Config, Dashboard};
use spacedb_sim::{Scenario, Simulation};
let mut sim = Simulation::new(Scenario::new(1, 5));
let _report = sim.run();
let now = 1_700_000_000;

let dash = Dashboard::assemble(&observations(&sim), &Config::at(now));

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:

cargo test -p spacedb-sim --target aarch64-apple-darwin   # or 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.