ADR-0001: Lifecycle status is an explicit enum, not derived at runtime
Status: Accepted
Date: 2026-05-30
Scope: core (any backend with domain lifecycles)
Context
Domain entities with a lifecycle (in Expenses: invoices, installment series,
subscriptions, …) need to express what state they’re in. It is tempting to derive that state
at display time from runtime conditions — e.g. treating PARTIALLY_PAID && cycleEnd < today
as “closed-and-partial”, or computing “refinanced” from related rows. Deriving
status this way couples display logic to date semantics, makes persistence
queries awkward (you can’t filter on a state that doesn’t exist as a column),
and lets the same status mean different things in different views.
Decision
When the domain gains a meaningful new lifecycle state, encode it as a status enum value with explicit transitions on the entity. Do not infer it
from runtime conditions.
New distinction the user describes → a new enum value + explicit transition
method on the entity (intent-expressing, not a raw setter).
Backfill existing rows via a Flyway migration so historical data matches the
new model.
Reserve runtime checks only for things the enum genuinely doesn’t carry —
e.g. “is this overdue right now”, which is a function of today’s date and
needn’t be persisted.
Consequences
Status means the same thing in every view and is directly queryable.
One migration per new state (accepted cost; keeps data honest).
Pairs with the broader DDD stance that entities own their invariants through
intent-expressing methods rather than exposing setters.
Example
Real code from the repos — optional
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”.
public enum InvoiceStatus { OPEN, CLOSED, PARTIALLY_PAID, CLOSED_PARTIALLY_PAID, INSTALLMENTED, INSTALLMENTED_PARTIALLY_PAID, PAID, SETTLED; /** Statuses in which the cardholder owes no outstanding balance directly * against the invoice. Single source of truth for Invoice#isResolved() AND * its JPQL mirror, so the two can never drift. */ public static final Set<InvoiceStatus> RESOLVED = EnumSet.of(PAID, SETTLED, INSTALLMENTED, INSTALLMENTED_PARTIALLY_PAID);}
Eight states, each one a distinction a user actually describes — “I paid part of it”,
“I refinanced it into installments” — rather than something derived at read time from
amounts and dates.
The RESOLVED set is the rule’s sharp edge: the same grouping is needed in Java and in
JPQL, so it is declared once and referenced from both. Re-listing those constants inline
in a query is how the two silently diverge.
Note what is not in the enum. “Is this overdue right now” is a function of today’s
date, so it stays a runtime check — persisting it would mean a row whose truth expires.
Origin (Expenses): the user rejected a PARTIALLY_PAID && cycleEnd < today runtime scheme
— “if most of the invoice stats depend on dynamic and runtime conditions, then
they are useless… we should have clearness as much as possible.”