Executable business rules

Business Invariants & Contracts

Use this skill when turning product requirements, domain specifications, or API contracts into executable property-based and model-based checks.

Core Principles

1. Ground Every Property in an Approved Rule: Never invent business invariants from guesswork or current implementation accidents. Derive every property from documented specifications, domain contracts, regulatory rules, or explicit clarification with the product analyst and domain specialists.
2. State the Rule in Plain Domain Language First: Express the invariant as a falsifiable domain sentence before writing code: "Under precondition $P$, for any valid inputs/operations $X$ in domain $D$, postcondition/invariant $Q$ holds, unless documented exception $E$ applies."
3. Design by Contract (Meyer): Separate every rule into three explicit parts:
   • Preconditions (requires): What must hold before the operation is invoked.
   • Postconditions (ensures): What the operation guarantees upon completion (return value, state delta, emitted events, or clean rejection).
   • Invariants (invariant): What must remain true across every reachable state before and after any sequence of valid or rejected operations.

Taxonomy of Business Properties

• Conservation & Accounting Laws: Total value is conserved across splits, transfers, allocations, and state transitions ($\sum \text{credits} - \sum \text{debits} = \text{balance}$; reserved + available = total).
• Bounds & Monotonicity: Balances, quotas, stock quantities, and counters never cross forbidden floors or ceilings; monotonic sequences (audit IDs, version numbers, finalized ledger totals) never move backward.
• Idempotency & Deduplication: Repeating a request with the same idempotency key or event ID produces the exact same domain state and side-effect count as executing it once: $f(f(s, x)) = f(s, x)$.
• Structural & State-Machine Validity: Entities only inhabit declared states, transition only along legal edges, and maintain required cross-field relationships (e.g., refunded_amount <= captured_amount).
• Isolation & Non-Interference: Operations performed by actor $A$ or in tenant $T_1$ never alter or expose records belonging to unauthorized actor $B$ or tenant $T_2$.

Domain Boundaries, Numeric Precision & Exceptions

• Clarify Numeric Domains Up Front: Identify the exact representation (minor-unit integers, fixed-scale Decimal, BigInt), currency codes, rounding mode (half-even, half-up, floor), minimum/maximum bounds, and tax/discount application order.
• Verify Algebraic Preconditions: Never assume operations commute or associate when rounding, tiered pricing, caps, or fee floors are involved. For example, $\text{round}(a) + \text{round}(b) \neq \text{round}(a + b)$, and applying a percentage discount before a fixed cap differs from applying it after.
• Test Valid and Invalid Inputs Separately:
  • Valid-domain properties generate legal business states and inputs and assert state transitions and postconditions.
  • Rejection properties generate out-of-range, malformed, unauthorized, or state-violating inputs and assert that the system rejects them cleanly with zero partial state mutation.

Checklist

• Is the property traced to an explicit business rule, specification, or confirmed domain contract?
• Is the invariant written in clear domain prose above or inside the test before the code assertion?
• Are numeric precision, currency units, rounding rules, and documented exceptions explicitly modeled?
• Are valid-input postconditions and invalid-input rejection guarantees separated so neither masks the other?