When to Auto-Apply a Lost Scheme Callback, and When to Flag a Human

Automation in a payments system is a trust exercise. Fix too little by hand and you drown operators in busywork; fix too much automatically and you risk a machine confidently writing the wrong answer into a financial ledger. KibiPay's reconciliation engine draws a deliberate line: it will auto-apply a discrepancy only when the correct outcome is unambiguous, and it flags a human for everything else.

The lost callback problem

The common case that reconciliation catches is a lost scheme callback. A payment really did settle (or get rejected, or returned) at the rail, but the asynchronous notification that should have advanced our record never arrived — dropped webhook, adapter restart, a network blip. Our ledger says SUBMITTED; the scheme, if you ask it, says SETTLED. The truth exists and it's authoritative; we're just out of date.

Why this case is safe to automate

When the sweep queries the rail's adapter and gets back a terminal status that differs from ours, three things are true at once: the answer comes from the authoritative source (the scheme itself), the answer is final (a terminal state won't change again), and applying it only moves us forward along the payment lifecycle to where the payment already is. There's no judgement call. Recording "this payment settled" when the scheme says it settled isn't a risk; failing to record it is.

So when auto_apply is on (the default), a STATUS_MISMATCH break triggers an automatic resolution: the engine calls the internal status-update path to move the payment to the scheme's mapped terminal status, tags the payment's metadata as reconciled, writes the break with an auto_resolved marker, and then immediately closes that break with a resolution of auto. The sweep's counters bump both status_mismatch and auto_resolved so you can see, per run, how much healing happened without a human. The mapping from scheme codes to our states is a fixed table — settled-family codes like ACSC, COMMITTED or FULFILLED map to SETTLED; RJCT/AUDDIS/ADDACS to REJECTED; RTRN/ARUDD to RETURNED — so the translation is deterministic, not inferred.

Where the engine refuses to guess

Everything short of an unambiguous terminal answer stays with a human:

• A STUCK break — both sides in-flight — has no terminal truth to apply. Auto-applying would mean fabricating a state, so the engine won't.
• An UNRECONCILABLE break — a rail with no status enquiry — can't even be checked automatically, so there's nothing to apply.
• A POSITION_DRIFT break is an aggregate discrepancy whose root cause is unknown; you don't "resolve" a drift by having a machine adjust a balance, you investigate why the books diverged.

And there's a global escape hatch: run the sweep with auto_apply set to false and even the safe status-mismatch case is only raised, not applied. That's exactly what you want during an incident, a migration, or any time you'd rather have a human eyeball every change before it lands.

The principle

The line isn't arbitrary. Automate the cases where the answer is authoritative, terminal, and forward-only; escalate the cases that require judgement, an out-of-band check, or a root-cause hunt. That keeps the reconciliation queue focused on the problems that genuinely need a person, while the boring, unambiguous "the callback got lost" cases heal themselves — which is the whole point of running the sweep on a schedule.

What the counters tell you

Because each sweep returns a per-run tally, the ratio between its numbers is a live health signal for the whole payments estate. A healthy system shows a steady trickle of status_mismatch breaks that are almost entirely auto_resolved in the same run — lost callbacks, quietly healed. A sudden spike in auto-resolutions says an adapter's callback path is dropping messages and deserves a look even though reconciliation is papering over it. A rising count of stuck breaks that can't be auto-resolved points at a rail that's genuinely wedged. So the auto-apply mechanism does double duty: it fixes the safe cases, and its counters expose the unsafe ones. There's one more safeguard worth naming: when the engine auto-applies a terminal status it also stamps the payment's metadata as reconciled, which removes it from future candidate sweeps. That flag stops the engine re-examining a payment it has already healed, keeping each subsequent sweep focused on genuinely unresolved drift rather than re-litigating settled history.