Why might a domain model raise a specific event like 'CustomerAddressChanged' or 'CustomerEmailVerified' instead of a single generic 'CustomerUpdated' event carrying a diff of changed fields? What's the trade-off?

## What "modeling intent" means "Modeling intent" in the domain-events context means designing events around the **business reason** something changed, not just around the technical fact that a field's value is now different. This matters because a database column changing value and a business-meaningful event happening are not the same thing, even though the former often triggers the latter. A customer's `shippingAddress` can change: - because they moved house; - because a support agent fixed a typo; - or because a fraud check overwrote it. Technically the same field mutation, but each is a different business event with different downstream consequences. `AddressCorrected` probably doesn't need to trigger "re-verify this customer's region for tax purposes"; `CustomerRelocated` probably does. ## Where the intent actually lives The mechanism for doing this well is to have the aggregate's business methods decide which event to raise, because the aggregate is the only place with direct access to **why** the change is happening — it's the caller's intent, expressed as which method was invoked. A method named `correctAddress(newAddress)` raises `AddressCorrected`; a method named `relocate(newAddress)` raises `CustomerRelocated`. Both might set the same underlying field, but the aggregate's API surface, not a diff of before/after state, determines the event. You can't reliably reconstruct intent-revealing events from outside the aggregate by comparing snapshots — the information about why only exists at the moment the business operation is invoked, and is lost once you're just looking at old-value/new-value. ## The generic alternative, and who pays for it The alternative — one generic `Updated` event per aggregate type, carrying the full new state or a diff — exists because it's **cheap**: one event type per aggregate, ever, and any new kind of change automatically produces an event without a developer defining a new type. Some teams deliberately choose this for aggregates with many rarely-differentiated fields, or as a stopgap early in a system's life when downstream consumers aren't known yet. The real trade-off is not correctness but where the cost of interpretation lands: | Approach | Who pays the interpretation cost | |---|---| | Intent-revealing events | paid upfront by whoever writes the aggregate: more design work, more types to maintain | | A generic `Updated` event | deferred to every future listener, each independently re-deriving "did the thing I care about actually change, and why" from a diff — duplicated work, easy to get subtly wrong | ## The fat generic event A concrete failure mode of the generic approach: as more listeners subscribe to `CustomerUpdated` for different reasons, the diff payload has to carry more fields "just in case", grows large and coupled to every field any consumer might want, and adding a genuinely new field risks silently triggering existing listeners that pattern-match loosely on the diff. This is the **"fat generic event" anti-pattern** — superficially decoupled, actually more tightly coupled, because every listener's correctness depends on the full shape of the diff rather than a narrow, stable contract. ## The opposite failure mode: sprawl The opposite failure mode is **event-type sprawl**: an aggregate raising a distinct event for every conceivable field mutation (`CustomerFirstNameChanged`, `CustomerLastNameChanged`, `CustomerPhoneChanged`...) when nothing downstream actually needs that granularity produces dozens of types with one listener or none, adding maintenance burden without adding clarity, because the "intent" being captured isn't actually business-meaningfully distinct. ## Where mature models land The practical resolution most mature domain models converge on: raise intent-revealing events at aggregate method boundaries where the business genuinely distinguishes cases, and don't manufacture separate event types for changes nothing downstream differentiates. In a billing domain, `SubscriptionUpgraded(planId)` and `SubscriptionDowngraded(planId)` are typically kept distinct from a generic `SubscriptionPlanChanged` because upgrade and downgrade trigger materially different consequences: - prorated billing direction; - feature-flag ordering; - dunning logic. So the extra type is worth its cost, whereas a field like marketing opt-in preference rarely needs its own dedicated event type beyond a generic `PreferencesUpdated`, because nothing currently reacts differently based on which preference changed.