agent's batch job failed: processed statements out of order and matched January payments to December invoices

TL;DR

Matching is period-aware by design: an invoice raised in December is settled by a payment in January, and each side belongs to its own statement period. Processing statements out of order let January payments meet December's open items as if both were December. Rebuild the run as a sequence: sort statements by period, match within and across periods deliberately with the direction recorded, and re-run the affected months. Then fix the scheduler so statements always process in chronological order.

agent's batch job failed: processed statements out of order and matched January payments to December invoices

Use this when

• Match results pair payments and invoices across periods in ways that ignore the payment direction in time.
• The job processed statements in an arbitrary or parallel order.
• Re-running one month changes the next month's match results unexpectedly.

Not for this skill when

• A payment genuinely settles an invoice from a prior period. That is normal AR or AP ageing, handled inside an ordered pipeline, not this bug.
• The periods in question are both open and the business wants one combined view. Then define the combined period explicitly instead of letting random order create it.

Steps

1. List the statements the job processed with their periods and the order they actually ran. Verify: the out-of-order sequence is documented from run logs
2. Identify the affected matches: pairs where the period assignment of payment or invoice is wrong, starting with the January to December examples. Verify: affected pairs are enumerated, not just sampled
3. Unmatch or reverse the wrongly assigned pairs in the affected periods. Verify: both periods return to pre-run open item state before reprocessing
4. Rebuild the job to process statements strictly in chronological order, with cross-period applications applied deliberately and labelled by direction. Verify: a test run with deliberately shuffled input still processes in period order
5. Re-run the affected periods in order and reconcile each period's closing open items. Verify: each period's rec now agrees and cross-period applications are explainable

Variant phrasings

agent batch job processed statements out of order period mismatch

The out-of-order phrasing.

January payments matched December invoices period sequencing

Searching by the misassignment symptom.

Compatibility: Agent batch matching over monthly statement periods with cross-period settlement logic.

Why it happens

Ledgers are temporal: an open item exists in a period, and payments move items across periods forward in time. A matcher that ignores processing order implicitly rewrites history, letting future cash settle past items within the past period's books. The results look almost right because the pairings are real, but period balances, ageing, and cut-off all corrupt silently. Ordering is not an optimisation; it is a correctness property of period accounting.

Edge cases / pitfalls

• Parallelising by period is still possible, but the cross-period application phase must run as a separate ordered step after all periods are matched.
• Backdated corrections need the same discipline: process them in the corrected order, not in arrival order.
• Keep the processing order in the run metadata; a future debugger will thank you when results look strange.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_jv2zC2EzcXUb9uGruaG4sA