KRONOS is an educational distributed KV engine built around Deterministic Simulation Testing (DST). The cluster, network, disks, clocks, faults and randomness run inside one reproducible Python process. A failing scenario is a seed, not a flaky incident.
Status: Phase 0–12 complete. 97 tests green, mutation score 14/14, and the final 1,000-seed sweep completed with 0 failures.
Production systems inspired by FoundationDB and TigerBeetle make rare distributed failures reproducible through deterministic simulation. KRONOS applies the same discipline to a compact, readable Python implementation:
- no real sockets, threads, wall-clock time or global random state in core code;
- virtual microsecond time and named SplitMix64 streams;
- Raft replication, snapshots, PreVote, ReadIndex and membership changes;
- MVCC + LSM storage with WAL, SSTables, compaction and crash recovery;
- an independent Wing–Gong–Lowe linearizability checker;
- transaction isolation, bank invariants and snapshot oracles;
- a 14-mutant self-checking gauntlet and reproducible benchmark reports.
flowchart TB
SIM["Deterministic Simulation\nvirtual clock + SplitMix64"]
NET["SimNetwork\ndrop / dup / reorder / partition"]
DISK["SimDisk\nfsync / torn write / bit rot"]
RAFT["Raft\nelection / replication / snapshots"]
KV["KV State Machine\nexactly-once sessions"]
TXN["MVCC Transactions\nSI / Serializable"]
LSM["LSM Storage\nWAL / MemTable / SSTable"]
VERIFY["Independent Verification\nWGL / bank / snapshot oracle"]
SIM --> NET --> RAFT
SIM --> DISK --> LSM
RAFT --> KV --> TXN --> LSM
KV --> VERIFY
RAFT --> VERIFY
Requires Python 3.11+ and pytest for development. Runtime code uses only the Python standard library.
python -m venv .venv
# Windows: .venv\\Scripts\\activate
# POSIX: source .venv/bin/activate
python -m pip install -e .
python -m pip install pytest
# Installed console entrypoint:
kronos mutants --seeds 20 --output reports/mutants.json
python examples/quickstart.py
python examples/chaos_demo.pyThe examples are intentionally local and deterministic; they do not require credentials, a database server, Docker or network access.
# Final benchmark: all S1–S8 scenarios, 1,000 seeds
kronos stress --scenario all --seeds 1000 --out reports/bench_final.json
# Log-friendly benchmark output
kronos stress --scenario S2 --seeds 50 --no-ansi --out reports/bench_s2.json
# Self-test the verification suite
kronos mutants --seeds 300 --output reports/mutants.jsonstress writes the requested JSON plus reports/BENCH_REPORT.md. mutants
returns a non-zero status if any mutant survives. The historical replay
interface remains available through python -m kronos.cli as the CLI evolves.
Measured by Phase 12 on the deterministic local workload; values are evidence
from reports/bench_final.json, not hardware-independent performance claims.
| Metric | Result |
|---|---|
| Accuracy gate | PASSED |
| Seed sweep | 1000/1000 OK |
| Virtual TPS | 94.95 |
| p50 latency | 549 µs |
| p95 latency | 954 µs |
| p99 latency | 990 µs |
| p99.9 latency | 998 µs |
| p95 recovery | 1,895 µs |
| Determinism proof | IDENTICAL trace hash ×2 |
python -m pytest
python tools/phase_gate.py --phase 12
python -m kronos.cli stress --scenario all --seeds 1000 --out reports/bench_final.jsonThe phase gate runs determinism lint, the phase tests, cumulative regression, test ledger checks and report generation. Read CONTRIBUTING.md before opening a pull request.
kronos/sim/ virtual time, RNG, network, disk and nemesis
kronos/storage/ codec, WAL, MVCC keys, MemTable, SSTable and LSM
kronos/raft/ Raft core, snapshots, membership and monitors
kronos/kv/ commands, state machine, client and cluster harness
kronos/txn/ snapshot isolation and serializable transactions
kronos/verify/ WGL, history, bank and snapshot oracles
kronos/faults/ M1–M14 mutation gauntlet
kronos/bench/ metrics, stress scenarios and reporter
examples/ runnable quickstart and chaos demonstrations
tests/ phase-by-phase executable specification
KRONOS is released under the MIT License.