Explicit domain state

In plain language

Most systems answer "what is going on with this record?" by reading several fields and combining them in your head. Is it cancelled? Well, cancelledAt is set, but active is still true, and there is a replacedBy pointing at something. Somebody knew what that meant once.

Explicit state replaces that inference with a name. The record is Recorded, or Voided, or Superseded. There is no combination to decode, because the states are the thing stored, not a consequence of other things stored.

Precisely

A semantic state is a named, explicit representation of what can be true, as opposed to an inferred combination of flags and nulls. The set of states is closed: adding one is a change to the model, which is the point, because it makes every place that must now handle it into a place the compiler can find.

The strongest form goes further: data that belongs to one state is only constructible in that state. A field meaningful only when superseded does not type-exist on a recorded entry.

In real code

A time-entry system built twice, independently, from the same frozen requirements. Both builds arrived at the same three states and the same four transitions:

The measured structure of one of those builds:

Twenty-four distinguishable rejection states is the number worth pausing on. Each is a named reason the system can refuse an action — a value, not a thrown exception and not a null. "It didn't work" is not a state this system can be in.

The divergence, and why it is the interesting part

The two independent builds modelled illegal states differently, and both were right about their own tradeoff.

One used a discriminated union keyed by status, so supersededBy only exists on the superseded branch and the compiler refuses it everywhere else. It cost nothing extra: the union was designed in from the start.

The other used one flat record with optional fields, and prevented the illegal combination with construction discipline — only transition functions ever build an entry — plus a load-time validator that rejects a tampered or corrupted file exhibiting the inconsistency. Its own self-review names this, unprompted, as the most honest limitation it found in itself, and its reasoning for not refactoring is sound: the retrofit cost was already high, and the defect class was already covered.

Two defensible points in one design space. What separates them is not care; it is when the decision was made.