Crate mongreldb_sim 

MongrelDB deterministic test simulator (spec section 9.5, FND-005).

A seeded, reproducible environment for consensus and distributed-transaction tests: a virtual clock with per-node skew schedules, deterministic cooperative task scheduling, virtual network links with delay/drop/duplication/reordering and partition/heal, virtual durable disks with write/fsync/torn-write faults, and process crash/restart that preserves exactly the fsynced prefix.

Determinism contract

Same seed ⇒ identical event order and identical outcomes. The contract rests on four rules the whole crate follows:

• Every random decision flows through SimRng, seeded once from the scenario Seed. Subsystems receive independent streams via SimRng::fork / SimRng::fork_label, so drawing extra numbers in one subsystem never perturbs another.
• Time is virtual microseconds; the simulator never reads the wall clock. The clock advances only when no task can run (“advance-on-idle”), jumping straight to the next timer or message delivery.
• Scheduling is cooperative and single-threaded. When several tasks are ready, the runtime’s seeded stream picks the next one, fixing the interleaving.
• Only BTreeMap/BTreeSet are iterated on behavior-affecting paths, so hash-randomized iteration order can never leak into a run.

Why no async runtime

The executor is deliberately std-only: no tokio, no other runtime. A production executor schedules on OS threads and reads the real clock, which makes runs irreproducible. Here a task is a boxed closure state machine (TaskBody) polled step by step by the seeded cooperative executor in runtime, so every interleaving decision and every timer fires under simulator control.

Failure artifacts

When a run fails (deadlock, step-limit exhaustion, or a task panic), Scenario::run / Scenario::run_with persist the seed and the full event log as JSON to $MONGRELDB_SIM_FAILURES (default target/sim-failures/) so CI can archive the exact repro.

Re-exports

pub use clock::Clock;

pub use clock::ClockError;

pub use clock::Micros;

pub use clock::SkewSchedule;

pub use disk::DiskError;

pub use disk::VirtualDisk;

pub use network::Delivery;

pub use network::DeliveryOutcome;

pub use network::DropReason;

pub use network::LinkConfig;

pub use network::Message;

pub use network::Network;

pub use network::NetworkStats;

pub use network::NodeId;

pub use network::SendOutcome;

pub use rng::Seed;

pub use rng::SimRng;

pub use runtime::NodeContext;

pub use runtime::Runtime;

pub use runtime::TaskBody;

pub use runtime::TaskId;

pub use runtime::TaskState;

pub use scenario::failure_dir;

pub use scenario::persist_failure_report;

pub use scenario::Event;

pub use scenario::RunOutcome;

pub use scenario::Scenario;

pub use scenario::ScenarioError;

Modules

clock

Virtual time in microseconds with per-node skew schedules (spec section 9.5, FND-005).

disk

Virtual durable store with injectable faults (spec section 9.5, FND-005).

network

Virtual network links between addressed nodes (spec section 9.5, FND-005).

rng

Seeded pseudo-random streams (spec section 9.5, FND-005).

runtime

Deterministic cooperative task scheduling (spec section 9.5, FND-005).

scenario

Scenario runner: schedule driving, fault orchestration, the event log, and failure artifacts (spec section 9.5, FND-005).