event-sourcing

Define immutable past-tense events as frozen dataclasses, build an aggregate that emits events through command handlers, and persist events to an append-only store. State is reconstructed by replaying events through the aggregate's apply methods.

Use event sourcing when you need a complete audit log, temporal queries, or multiple read models from the same write data. Avoid it for simple CRUD without history requirements, since the learning curve and operational overhead are significant.

The event store checks that the aggregate's current version matches the caller's expected_version before appending. A UNIQUE(aggregate_id, version) constraint enforces this at the database level, raising an OptimisticConcurrencyError on conflicts.

Truncate the read model table, load all events from the event store in order, and pass each through the projection's event handlers. Projections are disposable derived data, so they can be rebuilt from scratch anytime.

Event schema migration is difficult, so events should be versioned from day one. Long-lived aggregates accumulate thousands of events, requiring snapshots to avoid slow replays, and projection handlers must be idempotent to tolerate duplicate delivery.