chronon 0.1.0

Deterministic execution kernel with crash-safe replication and exactly-once side effects
Documentation 
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

# Chronon

[![CI](https://github.com/abokhalill/chr2/actions/workflows/ci.yml/badge.svg)](https://github.com/abokhalill/chr2/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/chronon.svg)](https://crates.io/crates/chronon)
[![Documentation](https://docs.rs/chronon/badge.svg)](https://docs.rs/chronon)
[![License](https://img.shields.io/crates/l/chronon.svg)](LICENSE-MIT)

Deterministic execution kernel with crash-safe replication and exactly-once side effects.

## Guarantees

| Property | Mechanism |
|----------|-----------|
| Durability | Quorum writes survive f failures in 2f+1 cluster |
| Consistency | Linearizable via VSR consensus |
| Exactly-once | Durable outbox with fenced execution |
| Determinism | Hash-chained log, consensus timestamps |

## Architecture

```
┌──────────────────────────────────────────────────────────────┐
│                        Chronon Node                          │
├──────────────────────────────────────────────────────────────┤
│  VsrNode ──> Executor ──> ChrApplication                     │
│     │           │              │                             │
│     ▼           ▼              ▼                             │
│  VirtualDisk  Snapshots    Outbox                            │
│  (barrier)   (compaction)  (side effects)                    │
└──────────────────────────────────────────────────────────────┘
```

Control plane (heartbeats, elections) is decoupled from data plane (writes, durability). Disk stalls don't trigger elections.

## Components

### `engine/`

| Module | Purpose |
|--------|---------|
| `VirtualDisk` | Unified durability trait. Writes speculative until `barrier()` |
| `SyncDisk` | O_DSYNC pwritev. Implicit barrier per write |
| `IoUringDisk` | io_uring + O_DIRECT. Explicit fsync barrier |
| `LogWriter` | Single-writer append-only log with hash chain |
| `DurabilityWorker` | Background thread, accepts `Box<dyn VirtualDisk>` |
| `CommitIndex` | Type-safe commit tracking. Distinguishes `None` from `At(0)` |

### `vsr/`

| Module | Purpose |
|--------|---------|
| `VsrNode` | VSR primary/backup with view changes |
| `QuorumTracker` | Per-index ack tracking for commit advancement |
| `Manifest` | Durable view/vote state. Fences zombie leaders |

### `kernel/`

| Module | Purpose |
|--------|---------|
| `Executor` | Deterministic state machine driver |
| `VsrAuthority` | Durable fencing for side effect execution |
| `SideEffectManager` | Executes outbox under Primary authority |
| `ChrApplication` | Your application trait |

### `chaos/`

Jepsen-style testing: partitions, kills, clock skew.

## Usage

```rust
use chronon::kernel::traits::{ChrApplication, ApplyContext, Event, SideEffect, SnapshotStream};

struct MyApp;

impl ChrApplication for MyApp {
    type State = MyState;
    type QueryRequest = MyQuery;
    type QueryResponse = MyResponse;
    type Error = MyError;

    fn apply(
        &self,
        state: &Self::State,
        event: Event,
        ctx: &ApplyContext,
    ) -> Result<(Self::State, Vec<SideEffect>), Self::Error> {
        let new_state = state.clone();
        Ok((new_state, vec![]))
    }

    fn query(&self, state: &Self::State, request: Self::QueryRequest) -> Self::QueryResponse {
        todo!()
    }

    fn snapshot(&self, state: &Self::State) -> SnapshotStream {
        todo!()
    }

    fn restore(&self, stream: SnapshotStream) -> Result<Self::State, Self::Error> {
        todo!()
    }

    fn genesis(&self) -> Self::State {
        MyState::default()
    }
}
```

## Build

```bash
cargo build --release
cargo build --release --features io_uring  # Linux 5.1+
cargo test
```

## Principles

- **Crash-only**: No graceful shutdown. Crash anywhere, recover everywhere.
- **Hash chains**: Every entry links to predecessor. Corruption detectable.
- **Explicit durability**: `barrier()` or it didn't happen.
- **Fencing**: View numbers gate all leader operations. Zombies die fast.