calimero-node 0.10.0

Core Calimero infrastructure and tools
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

//! Sync Protocol Simulation Framework
//!
//! A deterministic, event-driven simulation framework for testing the Calimero
//! sync protocol under realistic distributed system conditions.
//!
//! See [Simulation Framework Spec](https://github.com/calimero-network/specs/blob/main/sync/simulation-framework.md)
//! for the complete specification, including:
//! - §2: Architecture Overview
//! - §3: Side-Effect Model (`SyncActions`)
//! - §4: Message Identity and Delivery Semantics
//! - §5: Deterministic Scheduling
//! - §6: Crash/Restart Semantics
//! - §7: State Digest and Hashing
//! - §8: Convergence Definition (C1-C5)
//! - §15: Protocol Negotiation Tests
//!
//! # Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────────┐
//! │                         Test Suite                               │
//! └─────────────────────────────────────────────────────────────────┘
//!                               │
//!                               ▼
//! ┌─────────────────────────────────────────────────────────────────┐
//! │                        SimRuntime                                │
//! │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
//! │  │  SimClock   │  │ EventQueue  │  │ ChaCha8Rng  │              │
//! │  │  (logical)  │  │ (time,seq)  │  │  (seeded)   │              │
//! │  └─────────────┘  └─────────────┘  └─────────────┘              │
//! └─────────────────────────────────────────────────────────────────┘
//!                               │
//!                               ▼
//! ┌─────────────────────────────────────────────────────────────────┐
//! │                        SimNetwork                                │
//! │  - Message routing with delivery scheduling                     │
//! │  - Fault injection (latency, loss, reorder, duplicate)          │
//! │  - Partition modeling (connectivity cuts)                       │
//! └─────────────────────────────────────────────────────────────────┘
//!                               │
//!               ┌───────────────┼───────────────┐
//!               ▼               ▼               ▼
//!        ┌──────────┐    ┌──────────┐    ┌──────────┐
//!        │ SimNode  │    │ SimNode  │    │ SimNode  │
//!        │ "alice"  │    │  "bob"   │    │"charlie" │
//!        └──────────┘    └──────────┘    └──────────┘
//! ```
//!
//! # Quick Start
//!
//! ```rust,ignore
//! use sync_sim::prelude::*;
//!
//! // Create runtime with seed for reproducibility
//! let mut rt = SimRuntime::new(42);
//!
//! // Add nodes
//! let alice = rt.add_node("alice");
//! let bob = rt.add_node("bob");
//!
//! // Set up initial state
//! rt.node_mut(&alice).unwrap().insert_entity(
//!     EntityId::from_u64(1),
//!     vec![1, 2, 3],
//!     CrdtType::lww_register("test"),
//! );
//!
//! // Run until convergence
//! let converged = rt.run_until_converged();
//! assert!(converged);
//! ```
//!
//! # Features
//!
//! - **Deterministic execution**: Same seed = same results
//! - **Event-driven**: Process events in (time, seq) order
//! - **Fault injection**: Latency, loss, reorder, duplicates
//! - **Partition modeling**: Network splits and heals
//! - **Crash/restart**: Node failure and recovery
//! - **Convergence checking**: Formal properties (C1-C5)
//! - **Metrics collection**: Protocol cost, work done, effects

pub mod actions;
#[macro_use]
pub mod assertions;
pub mod benchmarks;
pub mod convergence;
pub mod metrics;
pub mod metrics_adapter;
pub mod network;
pub mod node;
pub mod protocol;
pub mod runtime;
pub mod scenarios;
pub mod sim_runtime;
pub mod storage;
pub mod transport;
pub mod types;

/// Prelude for convenient imports.
pub mod prelude {
    pub use super::actions::{
        EntityMetadata, EntityTransfer, OutgoingMessage, SelectedProtocol, StorageOp, SyncActions,
        SyncMessage, TimerOp,
    };
    pub use super::assertions::{
        all_converged, divergence_percentage, majority_digest, nodes_converged,
    };
    pub use super::benchmarks::BenchmarkResult;
    pub use super::convergence::{
        check_convergence, is_deadlocked, ConvergenceInput, ConvergencePending,
        ConvergenceProperty, ConvergenceResult,
    };
    pub use super::metrics::{
        ConvergenceMetrics, EffectMetrics, NodeMetrics, ProtocolMetrics, SimMetrics, WorkMetrics,
    };
    pub use super::metrics_adapter::SimMetricsCollector;
    pub use super::network::{
        FaultConfig, NetworkRouter, PartitionManager, PartitionSpec, SimEvent,
    };
    pub use super::node::{SimNode, SyncState};
    pub use super::protocol::{execute_hash_comparison_sync, SimSyncStats};
    pub use super::runtime::{EventQueue, EventSeq, SimClock, SimDuration, SimRng, SimTime};
    pub use super::scenarios::{RandomScenario, Scenario};
    pub use super::sim_runtime::{SimConfig, SimRuntime, StopCondition};
    pub use super::storage::SimStorage;
    pub use super::transport::{SimStream, SimStreamSender};
    pub use super::types::{
        DeltaId, DigestEntity, EntityId, MessageId, NodeId, StateDigest, TimerId, TimerKind,
    };

    // Note: assertion macros (assert_converged!, assert_entity_count!, etc.) are available
    // via `#[macro_use]` on the assertions module and don't need explicit re-export.
}

// Re-export for external use
pub use prelude::*;