# How must an instance scope partial-payment allocation order across principal, interest, and fees?

**Date of Record:** 2026 November 2

**Scope:** Applies to payments that are smaller than the total amount due and must be allocated across multiple obligation categories (principal, interest, fees, penalties) where the allocation order affects the remaining balance. Does not apply to payments that satisfy the total balance in full.

## Core Distinction

A partial payment must be allocated to specific categories. The allocation order is a choice: fees-first minimises the creditor's exposure but maximises the borrower's obligation; principal-first minimises the borrower's exposure but leaves interest accruing. The order is not a computation detail — it changes who pays what.

**Invariant.** Allocation is agreed if and only if the order is a total order over categories, stated in the contract, and identical on both sides' ledgers. `order ∈ {fees_first, interest_first, principal_first, pro_rata}`, and the chosen order is applied uniformly.

**Violation.** The **Allocation Ambiguity**. The contract is silent or ambiguous on allocation order, one party applies fees-first and the other applies principal-first, and the resulting remaining balances diverge after the first partial payment. Neither party's application is wrong in the absence of a stated order — but the divergence compounds with every subsequent payment.

**Asymmetry.** Each partial payment is a valid receipt. The remaining balance is a computation. Only the balance comparison surfaces the divergence, and by then the divergence has compounded across multiple payments.

**Recorded elements.** The `allocation-order-receipt` (which order, explicit), the `partial-payment-receipt` (the amount and the categories it was applied against), and the `remaining-balance-signature` (principal, interest, and fees as three separate figures) together make the divergence checkable at every payment.

## What Was Observed

**Signature.** Remaining principal differing between lender and borrower after a series of partial payments. Each party's ledger is internally consistent; the divergence grows with each payment. Reconciliations that compare total balance only (rather than the three components separately) can miss the divergence if the total happens to match by chance on a given payment.

**Trace.** Total due $10,000: $8,000 principal, $1,500 interest, $500 fees. Payment $3,000. Fees-first: fees cleared, interest partially cleared, principal untouched — remaining $8,000 principal. Principal-first: principal reduced to $5,000, interest and fees untouched — remaining $5,000 principal + $1,500 interest + $500 fees. Both totals are $7,000. The components diverge by $3,000, and interest continues to accrue on the larger principal.

**Why monitoring stays green.** Total balance agrees at $7,000. Each party's ledger is internally consistent. Component-level comparison is not run because the total matches.

## Condition of Validity

The instance must ensure at least one holds before it applies a partial-payment allocation:

1. **Must have an explicit total order.** The order is stated in the contract as a total order over categories; ambiguity is not resolved by convention.
2. **Must compare components, not totals.** Reconciliation compares principal, interest, and fees as three separate figures; total-only comparison cannot detect allocation divergence.
3. **Must record allocation per payment.** Each partial payment's receipt records the amount allocated to each category, so divergence is traceable to the payment that introduced it.

## Decision Boundary

- Explicit total order in contract, applied identically: allocation is agreed.
- Order stated in one party's system but not the contract: allocation is that party's choice, not agreement.
- No order stated: apply a default from local regulation or convention, and disclose to the counterparty; do not assume the counterparty shares the default.
- Order stated but components not compared: unknown whether diverging; compare components before assuming agreement.

## Operational Effect

The invariant couples a sequence of payments to a decision that is applied silently at each step. The instance's correct posture is to state the order in the contract, and to reconcile components rather than totals.

**Trap.** Reconcile the total balance. Total balance is the sum of components; if fees-first and principal-first happen to sum to the same total, the divergence is invisible. Component reconciliation is the only reliable check.

```python
from dataclasses import dataclass


class AllocationAmbiguityError(RuntimeError):
    """Raised when partial-payment allocation order is ambiguous between parties."""


VALID_ORDERS = ("fees_first", "interest_first", "principal_first", "pro_rata")


@dataclass(frozen=True)
class AllocationGate:
    contract_order: str  # "" if unspecified
    instance_order: str
    counterparty_order: str

    def verify(self) -> bool:
        if not self.contract_order:
            raise AllocationAmbiguityError(
                "no allocation order in contract: each party defaults independently"
            )
        if self.contract_order not in VALID_ORDERS:
            raise AllocationAmbiguityError(
                f"unknown allocation order {self.contract_order!r}"
            )
        if self.instance_order != self.counterparty_order:
            raise AllocationAmbiguityError(
                f"order mismatch instance={self.instance_order} "
                f"counterparty={self.counterparty_order}"
            )
        return True


def dispatch_allocation_mode(gate: AllocationGate) -> str:
    try:
        gate.verify()
    except AllocationAmbiguityError:
        return "reconcile-components-escalate"
    return "apply-allocation"
```