ADR 4: Declarative Aggregate Root and Domain Event Strictness
Summary
Declarative @handles decorators, single-source wire names, and strict event validation.
Context
Event schemas and handler dispatch can rot if event types are decoupled from classes or if unknown attributes are silently accepted. In an event-sourced system, corrupt or ambiguous stored events corrupt the database forever.
Decision
- Declarative aggregates support
@handlesdecorators with class-definition-time signature and duplicate handler validation. DomainEventenforces Pydanticextra="forbid", mandating explicit attribute declarations.- Every event carries non-null UUID
event_id, integerversion, and UTCoccurred_at. - Event wire type names are derived deterministically or declared explicitly single-source.
- All library domain exceptions derive from universal base
EventSourceError.
Consequences
- Prevents silent attribute dropping or misspelled payload fields.
- Immediate class loading failures if handler signatures are invalid.
- Guaranteed schema integrity across persistent event streams.