Measured, not asserted
Published
A loan payment is not one payment. It is a division between the obligations a borrower owes this month, and the order the note prescribes is invisible until a payment falls short by any amount at all.
The order is invisible until a payment is short
The sample owes $1,290.11 of interest, $560.00 of principal, $410.00 of escrow and a $95.00 fee. The note says a payment fills interest and principal before anything discretionary; the library's own default puts fees first. A borrower pays $2,260.11 -- exactly their statement, and not the fee they are disputing.
Under the note's order every scheduled obligation is met and the fee stays outstanding. The loan is CURRENT. Under the library's order the fee is taken first, and $465.00 of principal cannot be filled. Same payment, same total applied, same books, and the loan is PAST-DUE with suspense:$465.00.
This is the shape the previous pass named: the division always adds up, so a reconciliation between what arrived and what was applied balances under every order. What moves is which obligation went unmet -- and for a mortgage the answer to that question is not a bookkeeping detail, it is what gets reported to a credit bureau.
The note's own rule caught it, until the flag went too
The servicer here holds a rule of record: a payment order whose first bucket is not interest is not the order this note allows. Renaming allocationOrder alone hit that rule squarely and the engine refused outright -- order-rejected(note-order-check(interest and principal first)). Nothing was applied, the failure was immediate, and somebody would have to look at it the same day.
That rule sits behind an enabling flag, as almost every optional validation does. Renaming allocationOrder and requireOrderCheck together produced the silent version: fees first, principal unfilled, $465 in suspense, status past due, and a system that reported success.
It is the same structure this series has now measured in a dozen settings, and the summary keeps holding. Any reasoning of the form 'if this broke we would know' is only sound when the thing that would tell you is not downstream of the thing that broke.
The allocation was perfect and the loan was still reported late
The sharpest arm in this file is not the one where the money moved. Renaming bucket -- the field that names each obligation -- left the engine unable to recognise any bucket, so it filled them in the order they arrived, which in this file happens to be the note's order.
Every dollar landed exactly where it should have: interest $1,290.11, principal $560.00, escrow $410.00, fee nothing, suspense nothing. Perfect allocation. And the status came back PAST-DUE, because the test for whether the scheduled principal and interest were met is written over the same bucket names, and none of them matched.
The row after it is worse. The borrower who paid $2355.11, everything owed, in full, was also reported PAST-DUE. There is no money missing anywhere in that output. A ledger reconciliation passes, a payment-application report passes, and the derived status -- which is the thing that reaches the borrower's credit file -- is wrong for every account in the book.
The row that hides all of it
Both payments in this sample are worth having for a reason. The full payment produces CURRENT under the note's order, under the library's order, with partial fills allowed and with them forbidden. Every configuration agrees, because when there is enough money for everything the sequence stops mattering.
That is the structural blind spot in most test suites for this kind of code. Fixtures are written with round, sufficient payments, because those are the easy ones to write and the obvious ones to assert on. The order is only observable on a short payment, and short payments are the ones a real servicing book is full of.
The same point applies to the honest negatives. Renaming dueUsd or the payment amount produced non-finite-bucket and non-finite-payment, refused before anything was applied. Renaming the loan identifier was refused with an accurate reason. The amounts fail closed; the names that say what the amounts are FOR fail open.
What to do about it
None of this is an argument against protecting a servicing front end. Member renaming is opt-in, and the pattern is yours to write. Keep option keys read by an installed library out of it, and keep out the field names on records that cross into one.
Then take the specific lesson. Derive status from the same allocation you already reconciled, not from a second pass over the same names -- and if a bucket name cannot be recognised, refuse the payment rather than filling buckets in arrival order. An unrecognised bucket is not a new kind of obligation; it is a name you have lost.
And test the short payment. If your fixtures only ever pay in full, your test suite cannot observe the order at all, and the order is the entire reason this code exists.
Frequently asked questions
Does obfuscation change how a payment is applied?
Not on its own. Across five presets and five areas measured this pass, protection alone left every output identical -- twenty-five comparisons, no differences. What changed behaviour was member renaming, a separate opt-in option whose pattern you write yourself.
What actually went wrong in the measured case?
Renaming the option key carrying the allocation order, together with the flag in front of the note's own order rule, applied a $2,260.11 payment fees-first. The scheduled principal could not be filled, $465.00 went to suspense, and the loan was reported past due.
Do the books still balance when this happens?
Yes, exactly. The same total arrives and the same total is accounted for under every order, so a reconciliation between payment and application passes. What changes is which obligation was left unmet, which is what reaches the credit bureau.
What was the sharpest result?
An arm where every dollar was allocated correctly and the loan was still reported past due. Renaming the field that names each bucket left the amounts perfect but broke the test for whether scheduled principal and interest were met -- including for a borrower who paid in full.
Did anything catch it?
The note's own order rule did, on its own: renaming the order alone was refused outright before anything was applied. It stopped catching it once the enabling flag in front of it was renamed by the same pattern.
Why would a test suite miss this?
Because a payment that covers everything produces the same answer under every order. The sequence is only observable on a short payment, and test fixtures are usually written with round, sufficient amounts.
What is the practical mitigation?
Derive the delinquency status from the allocation you already reconciled rather than from a second pass over the same names, refuse a payment carrying a bucket you cannot recognise instead of filling in arrival order, and add a short-payment case to your fixtures.
Related reading