Skip to content
SwearTwPublic

About

Deterministic Simulation-Tested Distributed Key-Value Engine with Raft Consensus & MVCC LSM-Tree in Python (inspired by FoundationDB & TigerBeetle)

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

KRONOS

A deterministic, simulation-tested distributed key-value engine

CI Python License Tests Mutation Seeds

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.

Why KRONOS?

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.

Architecture

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
Loading

Quick start

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.py

The examples are intentionally local and deterministic; they do not require credentials, a database server, Docker or network access.

CLI

# 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.json

stress 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.

Final benchmark snapshot

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

Development and verification

python -m pytest
python tools/phase_gate.py --phase 12
python -m kronos.cli stress --scenario all --seeds 1000 --out reports/bench_final.json

The phase gate runs determinism lint, the phase tests, cumulative regression, test ledger checks and report generation. Read CONTRIBUTING.md before opening a pull request.

Project map

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

License

KRONOS is released under the MIT License.

About

Deterministic Simulation-Tested Distributed Key-Value Engine with Raft Consensus & MVCC LSM-Tree in Python (inspired by FoundationDB & TigerBeetle)

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages