Event-Driven Replay Kernel for Ventute
Maxim Kushnir
Event-driven replay kernel
State is not stored. It is derived. A lightweight, domain-free async event-sourcing kernel where the single source of truth is an immutable, append-only event log, and any state — now, or "as of turn N" — is reconstructed by folding that log through a pure reducer. Replaying the same log always yields the identical state and the identical SHA-256 hash, on any machine, in any process.
About this project. A standalone, generalized extraction of an architecture pattern from Ventute — a production AI-driven business-simulation platform — distilled into self-contained, runnable form. Published as a portfolio piece demonstrating event-sourcing and deterministic, replayable systems design. Author: @m4xkushnir.
Pure reducer — every
(state, event) → state transition is context-free: no clock, no RNG, no I/O during replay.Immutable log — frozen Pydantic v2 events, monotonic per-stream sequence, no update and no delete.
Two interchangeable stores — in-memory and single-file SQLite, both behind one async interface.
Hash-verified determinism — bit-exactness is asserted, not assumed.
Zero domain — the example aggregate is a generic counter + label-set + turn clock. Swap it for yours; the kernel is untouched.
Bit-exact replay — what guarantees it
Bit-exactness is not a hope; it falls out of four concrete design rules, each backed by a test.
The guarantees the test-suite actually asserts:
Guarantee Test Same log → same hash across independent kernels
test_same_log_same_hash_across_two_kernels In-memory and SQLite agree byte-for-byte test_memory_and_sqlite_agree_bit_for_bit Replay is stable across repeated runs test_repeated_replay_is_stable A snapshot never changes the result (only the work) test_snapshot_replay_equals_zero_replay "State as of seq N" equals a prefix replay test_replay_until_matches_prefix_of_full_logSnapshots are an optimisation, never a source of truth
Folding from zero is O(N) in history length.
replay_from_snapshot folds a cached state plus only the tail of newer events. The suite asserts this yields a hash identical to replaying from zero — so snapshots can be discarded and rebuilt at any time without ever changing an answer.Defining your own domain
The kernel is agnostic to what your events mean. To model your own aggregate:
Give
AggregateState (in state.py) the fields you accumulate.Register pure handlers in
reducer.py with @handler("your_event_type").record those event types and replay — determinism, hashing, both stores, and snapshotting all keep working unchanged.Like this project
Posted Jul 31, 2026
Implemented a kernel demonstrating event-sourcing for an AI-driven platform.
