Design: Command Objects, DeciderAggregate, and Dogfooding the Decider Style

Date: 2026-07-30 Status: Approved (brainstormed with Ty; see PR #79/#80 for the docs groundwork) Target release: 0.8.0

Context

PRs #79 and #80 documented the decider pattern (pure decide/evolve functions behind a thin AggregateRoot shell) and made it the README's featured alternative. Benchmarks from that work: ~1.5x on the command path (~8 Β΅s/order absolute, invisible next to event construction at ~11 Β΅s/event and millisecond-scale store appends), ~1.06x wash on replay. Conclusion reached: maintainability, not performance, is the deciding factor.

Two gaps remain. First, the userland shell has a real footgun — AggregateRoot._state is None until the first event and nothing calls _get_initial_state(), so a naive decider rejects its first command — plus per-shell version-stamping boilerplate. Second, DomainEvent carries correlation_id/causation_id/actor_id/tenant_id but nothing originates that chain: with_causation() only links event→event. In CQRS the originator is the command.

This design ships the pattern first-class and adopts it as the library's primary showcased style β€” dogfooded across examples, tutorials, test fixtures, the BDD harness, and the benchmark domain.

Decisions (made during brainstorm)

  1. Positioning: primary style. Tutorials, examples, and general-purpose fixtures lead with the decider. Imperative and declarative each keep one worked reference example and remain fully documented in docs/explanation/aggregate-styles.md.
  2. decide returns events; the shell stamps. The classic literature signature decide(command, state) -> list[DomainEvent], matching the README and explanation doc. The provenance stamp subsumes the version re-stamp in a single model_copy per event. The faster event-spec contract (1.29x) was considered and rejected: non-standard signature, awkward test assertions, and the perf delta is noise.
  3. Staging: three PRs. Core feature β†’ dogfood wave β†’ BDD harness (details below).

Component 1: `DomainCommand` (entities ring)

New package src/eventsource/commands/ beside events/ β€” pure (stdlib + pydantic only); the import-linter entities-ring contract is extended to include it.


class DomainCommand(BaseModel):
    model_config = ConfigDict(frozen=True)

    command_id: UUID = Field(default_factory=uuid4)
    issued_at: datetime  # default_factory: timezone-aware utcnow, same idiom as DomainEvent.occurred_at
    correlation_id: UUID = Field(default_factory=uuid4)
    actor_id: str | None = None
    tenant_id: UUID | None = None

Component 2: `DeciderAggregate` (aggregates)


class DeciderAggregate(AggregateRoot[TState]):
    @staticmethod
    @abstractmethod
    def initial_state(aggregate_id: UUID) -> TState: ...

    @staticmethod
    @abstractmethod
    def decide(command: Any, state: TState) -> list[DomainEvent]: ...

    @staticmethod
    @abstractmethod
    def evolve(state: TState, event: DomainEvent) -> TState: ...

Base-class behavior:

Static methods (not free functions passed to a factory) keep the three functions importable and testable standalone while giving the repository a normal class to construct.

Note on aggregate_id: DomainEvent.aggregate_id is a required field, so decide must set it β€” which it can, because initial_state(aggregate_id) receives the id precisely so state carries the aggregate's identity (e.g. OrderState.order_id). This is a documented contract requirement of the pattern, not something the shell can stamp after the fact.

Component 3: Provenance for the other styles

create_event(...) gains an optional command= keyword. When passed a DomainCommand, the same provenance fields are stamped with the same precedence rules. Imperative and declarative aggregates get identical audit-trail benefits without adopting the decider.

Component 4: `CommandRejectedError`

Added to exceptions.py: CommandRejectedError(EventSourceError) with a message and an optional command attribute. It is a convention, not a requirement β€” decide may raise anything (existing ValueError examples remain legal). All dogfood surfaces raise it, and application code gets one catchable type meaning "the domain said no" as distinct from a bug.

Component 5: BDD harness extension (`testing/bdd.py`)

DeciderScenario β€” synchronous, no store, no event loop:


(DeciderScenario(OrderAggregate)          # or (decide, evolve, initial_state)
    .given(OrderPlaced(...))              # folds via evolve from initial_state
    .when(ShipOrder(tracking_number="T")) # runs decide, captures events or exception
    .then_events(OrderShipped)            # assert produced event types/fields
    # or .then_rejected(CommandRejectedError, match="must be placed"))

then_rejected() defaults to CommandRejectedError but accepts any exception type. Reuses the existing bdd.py assertion vocabulary so both harnesses feel like one family.

Dogfood conversion map (PR 2 unless noted)

Surface Change
examples/basic_usage.py Converts to decider + DomainCommand (bank account as commands-as-values).
examples/imperative_example.py (new) Receives the current imperative BankAccountAggregate β€” the imperative style reference survives here.
examples/aggregate_example.py Stays declarative β€” the @handles style reference.
docs/explanation/aggregate-styles.md File-path references updated to imperative_example.py; gains pointer to the shipped DeciderAggregate.
docs/explanation/decider-pattern.md Drops the "no first-class abstraction" caveat; features the shipped class; userland-shell section becomes a "how it works underneath" appendix.
Tutorial 03-first-aggregate.md Teaches decider first; closes with an "other styles" pointer. Other tutorials update mechanically.
tests/fixtures/aggregates.py General-purpose counter fixtures convert to DeciderAggregate (whole unit suite exercises the feature). Fixtures that specifically test AggregateRoot/DeclarativeAggregate behavior stay on their styles.
bench/core/domain.py Gains a decider variant so imperative-vs-decider becomes a maintained benchmark in the matrix harness.
README.md Light touch: decider section adopts DomainCommand (bulk already landed in PR #80).

One converted example (basic_usage.py) is built inside PR 1 as an ergonomics smoke test, then the remainder of the wave lands in PR 2.

Testing strategy

ADR Impact (per definition-of-done)

Staging plan

  1. PR 1 β€” core feature: commands/ package, DeciderAggregate, CommandRejectedError, create_event(command=), ADR-0022, unit tests, public exports (DomainCommand, DeciderAggregate, CommandRejectedError from eventsource), basic_usage.py conversion as smoke test, import-linter update.
  2. PR 2 β€” dogfood wave: remaining conversion map (examples, tutorials, fixtures, bench, doc updates).
  3. PR 3 β€” BDD harness: DeciderScenario in testing/bdd.py, exported from eventsource.testing, with tests and a testing-guide docs update.

Out of scope