Financial and quota invariants

Financial & Quota Properties

Use this skill when verifying credit wallets, usage quotas, billing calculations, payments, reservations/holds, refunds, discounts, or ledger accounting.

Credit, Wallet & Quota State-Machine Invariants

Model credit and quota lifecycles with explicit generated operations (Credit, Reserve, Capture, Release, Refund, Expire, RetryWithSameKey) and verify:

1. Conservation of Balance (Zero Unaccounted Drift):
   • At every state: $$\text{total_granted} - \text{total_captured} + \text{total_refunded} - \text{total_expired} = \text{available} + \text{reserved}$$
   • Every balance change must correspond to an immutable ledger entry; summing ledger entries from genesis must equal the current materialized balance.
2. Non-Negativity & Quota Enforcement:
   • Available balance or remaining quota never drops below the allowed floor (typically $0$) under any sequence of reservations, direct debits, or expired grants.
   • A reservation $R$ can be captured or released at most once, and $\text{captured}(R) + \text{released}(R) \le \text{reserved}(R)$.
3. Idempotency & Replay Immunity (No Double-Spend / Double-Debit):
   • Replaying any Credit, Reserve, Capture, Release, or Refund with the same idempotency_key or provider event_id must return the original outcome and never debit or credit a second time.
4. Refund & Adjustment Bounds:
   • Cumulative refunds across any number of partial refund calls for payment/charge $P$ must never exceed the net captured amount: $\sum \text{refunds}(P) \le \text{captured}(P)$.
   • Refunding a discounted or taxed order must allocate tax and discount reversals consistently so partial refunds summing to 100% of items equal 100% of the original charge.

Arithmetic, Rounding & Proration Properties

• Exact Minor-Unit Arithmetic: Represent all monetary values in integer minor units (e.g., cents, fillér) or exact fixed-point decimals. Never tolerate floating-point drift.
• Allocation Without Penny Loss or Gain:
  • Splitting an amount $A$ across $N$ line items, installments, or revenue shares must satisfy $\sum_{i=1}^N \text{share}_i = A$, with remainders distributed deterministically according to the specified rounding rule.
• Invoice Line-Item Consistency:
  • For every generated invoice or order: $\text{subtotal} - \text{discount_total} + \text{tax_total} = \text{grand_total}$.

Checklist

• Does the property suite verify exact conservation between ledger entries, reserved holds, and available balance after every operation?
• Are duplicate requests and webhook replays tested with identical idempotency keys to rule out double-charging or double-crediting?
• Are partial reservations, partial captures, and multi-step partial refunds constrained so cumulative totals never exceed the source amount?
• Do multi-way splits, discounts, taxes, and prorations sum to the exact total without losing or inventing minor units?