Enforcing Invariants

caveat These scores compare mechanisms in the abstract and hide the only variable that decides real cases: how many writers you do not control. With one writer and a strong type system, the top two rows are sufficient and everything below is ceremony. With an admin tool issuing SQL, a batch partner and a decade of migration scripts, the third row is the only one that is a guarantee at all and its low flexibility score is the price of that. The matrix also cannot express failure *direction*: a type failing at compile time and a constraint failing at 3am in production are both "enforcement", and they are not remotely the same event.

// domain/order.ts
if (order.paymentStatus !== 'captured') throw new NotPaid()

// api/ship.ts  — written six months earlier
if (!['captured', 'settled'].includes(body.payment_status))
  return res.status(422).json({ error: 'unpaid' })

-- migration 0142
ALTER TABLE orders ADD CONSTRAINT ship_requires_payment
  CHECK (shipped_at IS NULL OR payment_status = 'captured');

// test/ship.test.ts
expect(() => ship(order({ paymentStatus: 'pending' }))).toThrow()

// Then: partial capture ships. Is 90% captured "paid"?
// Four places answer, and two of them already disagree
// about 'settled'.

// domain/payment-state.ts — the authority. Pure, no deps.
export function isPayableForShipping(p: PaymentState): boolean {
  if (p.reversedAt) return false
  return p.capturedMinor >= p.requiredMinor * 0.9
}

// domain/order.ts
if (!isPayableForShipping(order.payment)) throw new NotPaid()

// api/ship.ts — same function, different error shape
if (!isPayableForShipping(order.payment)) return unpaid422(res)

// test/ship.test.ts — tests the authority as a property,
// and each layer only for what IT adds (the 422, the throw).

-- migration: the constraint stays deliberately WEAKER —
-- it cannot see reversals, so it enforces the part it can.
CHECK (shipped_at IS NULL OR payment_status <> 'pending')
-- comment on constraint: "coarse net for writers that bypass
-- the domain; the authority is isPayableForShipping()."

The change that arrives — partial captures count, reversals do not — is one edit in the second version and four in the first, two of which nobody will remember to make. The second version also does something the first cannot: it lets the database layer be deliberately *weaker* than the authority and says so, which is the honest way to use a mechanism that cannot see enough context. What it costs is a shared pure module that four subsystems now depend on, and a discipline of routing every check through it that nothing but review enforces.

1// The invariant we can actually hold:
2//   "No order stays dispatched-and-unpaid for more than 15 minutes
3//    without a human being told."
4// Note that this is NOT the invariant we wanted. Say so.
5 
6export async function reconcileDispatched(now: Instant) {
7  const suspect = await orders.dispatchedButNotPayable({
8    olderThan: now.minus(Duration.minutes(15)),
9  })
10 
11  for (const o of suspect) {
12    // Remediation is part of the design, not of the runbook.
13    await holdShipment(o.id, 'payment_not_confirmed')
14    await alert.page('order.dispatched_unpaid', { orderId: o.id })
15  }
16 
17  // The metric matters more than the loop: a reconciliation that
18  // has never fired is indistinguishable from one that is broken.
19  metrics.gauge('orders.dispatched_unpaid', suspect.length)
20  metrics.counter('orders.reconcile_runs').inc()
21}

The two metrics at the bottom are the part that is usually missing, and they are what make this a design rather than a hope. A detection mechanism with no signal that it ran is the classic case of a mitigation with its own silent failure mode — and the run counter, not the violation gauge, is the one that catches it (Designing for Failure).