consortium_fanout_sim/lib.rs
1//! # consortium-fanout-sim
2//!
3//! Deterministic in-process simulator for the [cascade
4//! primitive](consortium_nix::cascade). Computes per-edge durations
5//! from `closure_size / bandwidth + latency`, applies failure
6//! schedules, and returns results to the cascade coordinator.
7//!
8//! No real networking, no async runtime, no SSH. Each `Scenario` is
9//! reproducible from a `u64` seed — same seed produces identical
10//! `CascadeResult` including round count and error tree shape.
11//!
12//! ## Layout
13//!
14//! - [`executor::DeterministicExecutor`] — implements
15//! [`RoundExecutor`](consortium_nix::cascade::RoundExecutor) with
16//! bandwidth/latency-driven timing and an injectable failure schedule.
17//! - [`fixtures`] — generators for seed sets, bandwidth distributions,
18//! and failure schedules. Each takes `&mut StdRng` for reproducibility.
19//! - [`scenario::Scenario`] — high-level wrapper that builds a
20//! complete cascade run (nodes + seeded set + network + executor +
21//! strategy) from a seed and a few descriptors.
22//!
23//! ## Quick start
24//!
25//! ```
26//! use consortium_fanout_sim::scenario::{Scenario, ScenarioConfig};
27//! use consortium_fanout_sim::fixtures::BandwidthDistribution;
28//! use consortium_nix::cascade::Log2FanOut;
29//!
30//! let cfg = ScenarioConfig {
31//! seed: 0xc0ffee,
32//! n_nodes: 64,
33//! seed_fraction: 0.0,
34//! closure_bytes: 100 * 1024 * 1024,
35//! bandwidth: BandwidthDistribution::Uniform(100 * 1024 * 1024),
36//! uplinks: None,
37//! failures: Default::default(),
38//! max_rounds: 32,
39//! };
40//! let result = Scenario::new(cfg).run(&Log2FanOut);
41//! assert!(result.is_success());
42//! assert_eq!(result.converged.len(), 64);
43//! ```
44
45pub mod executor;
46pub mod fixtures;
47pub mod scenario;
48
49pub use executor::DeterministicExecutor;
50pub use fixtures::{BandwidthDistribution, FailureSchedule, SeedDistribution, UplinkDistribution};
51pub use scenario::{Scenario, ScenarioConfig};