add-reducer

Adding a Reducer (IReducerFor<T>)

A reducer is the last-resort way to build a read model — "current state + event → next state" with real C# control flow. Reach for it only when the projection ladder can't express the shape. A reducer that could have been a projection is a projection that was never written, and will be flagged for conversion in review.

Admission checklist — all three must be true before writing a reducer

1. Model-bound attributes can't express it — not [FromEvent<T>], [SetFrom<T>], [SetFromContext<T>], [ChildrenFrom<T>], [RemovedWith<T>], [Nested], [ClearWith<T>], counters ([Increment<T>]/[Count<T>]), or [FromAll].
2. Fluent IProjectionFor<T> can't express it — not UsingKey/UsingParentKey/UsingCompositeKey/UsingConstantKey, Join, .NotRewindable(), or a supported conditional setter.
3. The remainder needs real control flow — branching on prior state, loops, or accumulated-state calculations the declarative APIs don't have.

If all three hold, write the reducer and carry an inline justification comment on the class naming the specific limitation that ruled out a projection:

// Reducer required: next balance depends on prior balance with a per-event cap that
// no counter/projection attribute expresses.
public class AccountBalanceReducer : IReducerFor<AccountBalance>
{
    public AccountBalance Opened(DebitAccountOpened @event, AccountBalance? current, EventContext context)
        => new(0m, context.Occurred);

    public AccountBalance Deposited(FundsDeposited @event, AccountBalance? current, EventContext context)
        => (current ?? new(0m, context.Occurred)) with { Balance = (current?.Balance ?? 0m) + @event.Amount };
}

Method signatures

Each public method's first parameter is the event type it handles (dispatch is by type, not name):

Signature	Meaning
T On(TEvent @event, T? current)	next state from current (null on first event)
T On(TEvent @event, T current)	non-nullable current when the model is always seeded first
+ EventContext context	add the context as a trailing parameter when you need Occurred/metadata
Task<T> On(...)	async when the computation awaits
return T?/null	treat the event as a no-op for this model