Event Sourcing Handbook

Every write in Kumiko is stored as an event, an immutable record of what happened. Tables are derived from those events and can be rebuilt at any time. This gives you audit trails, time travel, undo, and realtime updates without separate write paths.

You do not need to understand event sourcing to ship. This handbook has four levels, and each is useful on its own. Move to the next level only when your app needs it.

Level	You learn	You need it when
1, CRUD, no jargon	r.crud, one call, full CRUD	Always. This is the default way to ship an entity.
2, Events & projections	Your own domain events and read models	Your domain has verbs beyond create/update/delete (“approve”, “pay”).
3, Evolution	Upcasters, snapshots, time travel	Your event shapes change, or aggregates grow long histories.
4, Scale & operations	Cross-aggregate read models, rebuilds, ops	You aggregate across entities, or you run this in production.

Every code block in this handbook is embedded from a tested, runnable recipe, the same files that run in CI: basic-entity and event-sourcing.

Prefer concepts over a guided path? Read How events work, the same model, explained top-down.