Making Illegal States Unrepresentable

1// representable and illegal:
2//   struct Order { status: Status, paid_at: Option<DateTime>, capture_id: Option<CaptureId> }
3//   -> status = Paid with paid_at = None compiles, and 30 rows did exactly that
4 
5enum Payment {
6    Unpaid,
7    Paid    { at: DateTime, capture: CaptureId },
8    Refunded{ at: DateTime, capture: CaptureId, refund: RefundId },
9}
10 
11fn days_since_payment(p: &Payment, now: DateTime) -> Option<i64> {
12    match p {
13        Payment::Unpaid              => None,
14        Payment::Paid { at, .. }     => Some((now - *at).num_days()),
15        Payment::Refunded { at, .. } => Some((now - *at).num_days()),
16    }
17    // add a fourth variant and this fails to compile,
18    // here and at every other consumer. That list is the value.
19}

There is no null check in days_since_payment and there cannot be one, because there is no value of Payment that means "paid, timestamp missing". The dashboard crash is not fixed; it is unwriteable. The cost is visible in the same snippet: the wire format is still flat JSON, so somewhere at the edge there is a parser mapping three nullable fields onto this enum and rejecting the combinations that do not fit — and that parser is now the only place the check exists.

type Payment =
  | { kind: 'unpaid' }
  | { kind: 'paid'; at: Date; capture: CaptureId }

// looks safe, is not:
const order = JSON.parse(body) as Order
//                              ^^ the 30 bad rows arrive here
//                                 wearing a legal type

if (order.payment.kind === 'paid') {
  daysSince(order.payment.at)   // undefined at runtime
}

function parsePayment(raw: unknown): Result<Payment, Invalid> {
  if (raw.status === 'unpaid') return Ok({ kind: 'unpaid' })
  if (raw.status === 'paid') {
    if (!raw.paid_at || !raw.capture_id)
      return Err({ code: 'paid-without-evidence', raw })
    return Ok({ kind: 'paid', at: new Date(raw.paid_at), capture: raw.capture_id })
  }
  return Err({ code: 'unknown-status', raw })
}

// every entry point calls this; a test asserts that.
// downstream code never checks again.

The difference is not the type — both files declare the same union. It is that in the second version there is exactly one function that can produce a Payment, so the invariant is established once and every consumer inherits it. In the first version the type is a comment that the compiler happens to read. The thirty rows are also now visible as paid-without-evidence errors at the boundary rather than as a crash in a dashboard three systems away, which is what turns a mystery into a fixable bug (Error Boundaries).

caveat The scores are for a system whose invariants are stable. The axis that actually decides is not on the table: how confident you are that the invariant is permanent. "Paid implies a timestamp" has been true since the first commit and will be true forever, so encoding it structurally is safe. "Every shipped order has a tracking number" feels equally solid right up until a courier partner is onboarded who does not issue them — and at that moment the maximally-precise model requires a migration, a model change and an edit at every consumer, while the loose model requires a nullable column. Encode what is definitional, not what is merely currently true.