ADR-0003: Domain entities own their invariants via intent-expressing methods
Status: Accepted — amended 2026-09-19 (a domain guard belongs where input cannot reach it)
Date: 2026-05-30
Scope: core (any backend with a domain layer)
Context
Anemic entities with public setters let any caller put an entity into an invalid
state, and scatter the rules for “what does a valid X look like” across use cases.
We want the domain layer to be the place where invariants live.
Decision
Domain entities are rich and self-protecting:
No @Setter, no @Builder. Explicit constructors; state changes only
through named, intent-expressing methods.
Type/state transitions are handled by the entity as a unit, never by the
caller poking fields. E.g. paymentMethod.markAsCredit(closingDay, dueDay) sets
the type and the days together; markAsNonCredit(type) sets the type and
always nulls the days. Prefer entity.rename(...) / entity.markAsX(...) over a
generic update(...) that takes everything.
A single-entity rule belongs on the entity, not in the use case. If a use
case reads an entity’s getters and then decides-and-mutates that same entity,
that decision is a domain method (applyChargeDate, applyChargedAmount, changeEarnings, toggleActive, generateInstallments). A rule duplicated
across N use cases, or re-derived from getters, is the strongest signal it has
leaked out and should be pulled in — caught one bug where a charge-date guard
lived loosely in the use case and threw an unhandled 500.
Predicates name what they ARE, not what they’re used for. A factual
predicate asserts a truth condition (isPaid(), isCredit(), isGlobal()); a policy predicate (isLocked(), isRefinanceable(), isEnrolling()) is a
separate method built as a thin delegator on top — even when that’s one line.
Don’t rename a fact to express a current use; the two can diverge.
A null check on a nullable = false field is a smell — the DB + constructor
guarantee it; in Expenses, if the entity is CREDIT, closingDay is non-null by
design. (See the null-check rule in the backend repo’s CLAUDE.md.)
Validation strategies handle user-facing 400s (field messages); domain
methods enforce structural invariants (prevent invalid states in code paths).
The two are complementary, not redundant — but order decides which one answers.
A use case mutates and then validates, so a domain guard on a path the user can reach
fires first and replaces a field-level 400 with a 500. Put the domain guard where
input cannot reach it; where it can, the validator owns the message and the entity may
hold the invalid state transiently, never persisted. PaymentMethod has it both ways
on purpose: markAsNonCredit rejects CREDIT (unreachable from a request, so throwing
is free), while markAsCredit accepts null cycle days (reachable, so PaymentMethodCreditFieldsStrategy answers instead).
Domain polymorphism: when multiple entities share a semantic concept,
express it as a domain interface, not duplicated logic. Example: CashOutflow
implemented by Expense and InvoicePayment, so GetCashOutflowsUseCase is the
single source of truth for “money leaving the account.”
Consequences
Invalid states are unrepresentable through the public API of an entity.
Reviewers can trust that reading an entity’s methods tells the whole story of
how it may change.
Watch: an invariant-maintaining method can be load-bearing for more than
one caller — don’t delete a “redundant” clamp without checking every caller
(e.g. Expense.update()’s clamps are relied on by the subscription path, which
doesn’t run the apply* methods).
Canonical example (from Expenses) — the purchaseDate <= chargeDate (and purchaseAmount <= chargedAmount) rule. This universal expense invariant has no ADR of its own; it
is owned by Expense.applyChargeDate / applyChargedAmount (a charge may only be
deferred to a cycle, or an amount raised, strictly past the purchase, and only on
a credit method — otherwise it pins/resets to the purchase). The same clamps are
reused by installment generation and update(); treat these methods as the single
home for the rule rather than re-checking dates/amounts in callers. (What the
project does with the two-date split — analytics window by the purchase date,
invoice membership by the charge date, and only the charge date may be in the
future — is docs/expenses/backend/0017-purchase-date-is-never-in-the-future.md
and the superseded 0007-effective-spend-date-for-analytics.md; the clamp that
keeps the split valid lives here.)
Agents: safe to skip. The Decision above is the specification; everything below is
illustration. Skipping this block costs you nothing normative and saves tokens. Expand it
when you need the shape rather than the rule — porting the pattern to a new project, or
answering “what does this actually look like”.
There is no setType, no setClosingDay, no @Builder. Type and cycle days move together or not at all: markAsCredit sets all three, markAsNonCredit sets the type
and always nulls the days, and it refuses CREDIT — that argument would set the type
while nulling the days, producing exactly the state the pair exists to prevent.
That guard was missing until 2026-09-19, and nothing could reach it: changeType is the
only caller and routes CREDIT to markAsCredit. “Safe because the only caller happens to
be careful” is worth closing anyway, because a public method acquires new callers.
changeType is where the invariant would otherwise leak into a use case — the
“cycle days are immutable once CREDIT” rule lives on the entity, in one place, with the
comment explaining why the incoming values are dropped rather than applied.
isCredit() states a fact. A policy question like “can this be refinanced” would be a
separate method delegating to it, so that renaming the policy never quietly redefines
the fact.