Event Sourcing Implementation Review Rules

Purpose

Use these rules when a change touches an event-sourced system. The goal is to keep the event log correct and replayable — events must be immutable facts, schema changes must not break existing projections, and handlers must produce the same state whether they process an event once or a hundred times.

This is a review policy, not an event-store tutorial. It tells reviewers what must be true about generated event types, handlers, and projections before the change is safe to merge.

Review Inputs

Collect enough context to know what the change affects and how it fits the event-sourcing model.

1. Change surface. Whether the change touches event types, command handlers, event apply methods, projections, snapshots, or event-store queries.
2. Schema compatibility. Whether new or changed event types are still readable by existing handlers and projections that process old events.
3. Idempotency. Whether event handlers and projections produce the same output when processing the same event more than once.
4. Aggregate boundary. Whether commands validate intent and emit events, and whether the apply method only rebuilds state without side effects.
5. Replay correctness. Whether replaying the event stream from scratch produces the same aggregate state as the current loaded state.

If the change cannot say whether an event schema change is backward-compatible or whether a handler is idempotent, require that context before reviewing the logic.

Event Immutability And Design Rules

• Treat every persisted event as an immutable, append-only record; never update or delete an event already written to the store.
• Include all information the event represents at the time it occurred, rather than referencing mutable state that may change later.
• Use past-tense names that describe what happened, not commands or intentions.
• Keep events self-contained so a handler can process them correctly without querying external state for information that should have been captured at publish time.
• Do not embed business logic in event types; they are data records, not behavior carriers.

Schema Evolution Rules

Projections and handlers must continue to work correctly when reading old events.

• Add new fields as optional with safe defaults so older events without the field are still processable.
• Never remove a required field, rename a field, or change a field's type in a way that breaks deserialization of existing stored events.
• Introduce a new event type version (such as v2 suffix or a version field) when a breaking change is unavoidable, and handle both versions in affected handlers.
• Test schema changes by replaying production-shaped events of the old version through the new handler and confirming the output is correct.
• Keep a schema registry or documentation that records what each event version contains so future handlers can be written correctly.

Idempotency And Handler Rules

• Make every event handler and projection idempotent by tracking the event id and skipping or merging duplicate processing.
• Do not rely on the event store to guarantee exactly-once delivery; assume at-least-once and design handlers accordingly.
• Perform side effects (writes to external systems, emails, notifications) only after confirming the event has not already been processed.
• Keep handler logic deterministic given the same event and prior state so replay always converges to the same result.
• Separate read-model updates from side-effect commands so projections can be rebuilt without re-triggering external actions.

Aggregate And Command-Handler Rules

• Validate command preconditions against current aggregate state before emitting events, and reject invalid commands before writing to the store.
• Let the aggregate's apply method rebuild state from events only; it must not call external services, write to stores, or produce side effects.
• Use optimistic concurrency (expected version) when appending events to prevent conflicting concurrent writes.
• Keep aggregates small and cohesive around a single consistency boundary.
• Load aggregates by replaying their event stream or from a snapshot plus subsequent events, not by reading projected read-model state.

Merge Blockers

Block merge until resolved when:

• a change mutates or deletes an already-persisted event;
• an event schema change removes, renames, or breaks a required field in a way that stops existing projections from deserializing old events;
• an event handler or projection is not idempotent and will produce incorrect state on replay or redelivery;
• an aggregate's apply method calls external services or produces side effects;
• snapshot state and full-replay state diverge in tests;
• a personal data field (password, payment data, health record) is embedded directly in an event payload instead of by reference.

Review Checklist

• {"task": "Events immutable", "description": "No persisted event is mutated or deleted; events record past facts as self-contained data"}
• {"task": "Schema backward-compatible", "description": "New or changed events can be read by existing handlers that process older versions"}
• {"task": "Handlers idempotent", "description": "Event handlers and projections produce the same result when processing the same event multiple times"}
• {"task": "Aggregate boundary correct", "description": "Apply methods only rebuild state; command handlers validate and emit; no side effects in apply"}
• {"task": "Replay consistent", "description": "Replaying the event stream produces the same aggregate state as the snapshot-plus-delta path"}
• {"task": "Privacy safe", "description": "Sensitive personal data is referenced, not embedded; the event log is treated as immutable personal-data history"}

AI Review Rules

AI assistants can review event-sourcing code, but they should show evidence.

• Ask the assistant to identify whether the change touches event types, handlers, projections, or aggregates before judging correctness.
• Require it to flag any event schema field that is removed or renamed, and confirm old event versions are still handled.
• Have the assistant check handler idempotency explicitly, not just assume it.
• Do not let the assistant assume snapshot and replay produce the same state without showing a test that confirms it.
• Re-run review after any change to event fields, handler logic, or snapshot creation.

Troubleshooting

• Replay produces different state than snapshot-plus-delta: check whether apply methods have hidden side effects or non-deterministic logic.
• A projection broke after a schema change: add backward-compatible defaults for new fields and preserve old field names; version the event if needed.
• A side effect ran twice on replay: track the event id and make the handler skip already-processed events.
• An aggregate query pulls the whole store: scope the stream read to the aggregate id and load only relevant events.
• Personal data must be deleted: implement encryption-key rotation or compaction, never delete the event itself.

Duplicate And History Check

Checked existing rules, hooks, statuslines, guides, collections, skills, open PRs, and closed PRs for event sourcing, CQRS, event store, event schema evolution, idempotent handlers, and aggregate design.

Adjacent content includes general architecture and API design rules, but no entry is a portable pre-merge review policy specifically for event-sourcing implementation correctness. This entry is distinct because it decides what must be true about event immutability, schema evolution safety, handler idempotency, and replay consistency before the change can merge.

No prior closed PR for this rule was found during the duplicate/history check.

Event Type Reference

The table below maps common event-sourcing concerns to the review question that surfaces them, following the pattern described in the sources.

Getting any one of these wrong can produce silent inconsistency that only surfaces under replay, recovery, or concurrent load.

Sources

• Martin Fowler — Event Sourcing: https://martinfowler.com/eaaDev/EventSourcing.html
• Martin Fowler — CQRS: https://martinfowler.com/bliki/CQRS.html
• Azure Architecture Center — Event Sourcing pattern: https://learn.microsoft.com/en-us/azure/architecture/patterns/event-sourcing
• EventStoreDB — What is event sourcing: https://www.eventstore.com/event-sourcing