Payroll & Benefit Reconciliation

Architecture

Key specifications

What it does for you

An employer runs one payroll a period, and that single register fans out to several benefit providers, to the general ledger and to cash. A 401(k) deferral withheld on the register has to reach both the recordkeeper and the custodian; an HSA deduction has to reach the HSA administrator; an FSA election has to reach the FSA administrator; the employer match has to recompute from the plan formula; and every dollar has to land in the ledger as a balanced entry whose benefit payable clears to zero once the money is remitted. Four failures hide inside that, and none of them look wrong in a stack of provider upload files. The hand-off drifts: a per-employee deduction is not the amount that reached the provider, or a plan ties to the recordkeeper but not the custodian, or the cash transfer is a dollar off the liability it settles. The employer match is wrong: the booked figure does not recompute from the formula on eligible compensation, or it was computed on compensation above the 401(a)(17) cap. A statutory limit is breached: an employee is over the 402(g) deferral limit, the HSA tier limit, an FSA cap or the 415(c) additions ceiling, and the per-period withholding no longer recomputes from the room that remains. The deposit is late: participant money reached the provider outside the DOL small-plan seven-business-day safe harbor, or the rollup calls a plan tied on a determination nobody recomputed from the evidence underneath it. None of these are judgment calls. They are equalities and comparisons -- a register total against a provider upload with exact ==, a deferral against a limit with >, a deposit against a pay date and a business-day count -- which a deterministic control settles better than a spreadsheet inherited by whoever reconciles benefits this period.

The seeded demo runs every control over every reconciliation file⁷. The CLI generates thirty-one fictional reconciliation files -- one clean baseline and one carrying each of the thirty planted defects -- then runs all twenty-nine controls over each. The clean file returns PASS with no flags; every defect file returns REVIEW or FAIL and names the control it tripped along with the reason that control exists.

The limit breach and the watch flag fire at different boundaries⁸. The 402(g) ceiling and the review watch band are seeded independently. One defect file lifts an employee's prior year-to-date deferral over the 402(g) limit and trips lim_402g_deferral as a FAIL, checked with exact >; another lifts it into the file's own watch band, still under the limit, and trips lim_deferral_watch as a REVIEW-only FLAG -- proving the ceiling is tested at its boundary and the review signal is independent of the breach.

The tie determination is recomputed, not read back⁹. A defect file flips the reconciliation report's stated tie flag for one plan to the opposite of the truth while leaving every leg intact. rpt_tie_status_recomputes rebuilds the determination from the register, every provider upload, the ledger liability credit and the cash transfer and fails on the contradiction, proving the tie flag is recomputed from the evidence beneath it rather than trusted as stated.

Functional block diagram

Instruction set

Benchmarks

Control characteristics

• Read-only: reconciliation files are parsed and never written back, so the engine cannot introduce the break it reports.
• Integer cents throughout, compared with exact ==; there is no tolerance band on a tie-out, and a cent off the recomputation is reported as a break.
• A figure that should be integer cents but is not produces an AMOUNT_INVALID finding contained to the one row it was read on, rather than being coerced into the number the engine is meant to audit.
• One reconcile kernel: the controls and the generator share the predicates in benefit_engine.reconcile, so a determination cannot disagree with the data that produced it.
• The 401(k) ties to two destinations: the register must reach both the recordkeeper and the custodian, so a plan that reaches one and misses the other is not reconciled.
• The deposit safe harbor is inclusive: a deposit on the seventh business day is timely and the eighth is late, measured against the file's own pay date, never the system clock.
• Deterministic and byte-stable: same inputs produce the same findings in the same order, with no timestamps or absolute paths in any output.
• Absent evidence is never a passing control; a missing artifact fails completeness rather than letting the controls that read it pass unread.

Operating limits

• The engine never runs payroll, moves money, funds a provider, files a return or writes to a source artifact. It reads the reconciliation file and stops.¹⁴
• It reads the eight artifacts one pay-period reconciliation emits. It does not connect to a payroll system, a recordkeeper, a custodian, an HSA or FSA administrator, a bank or the general ledger.¹⁵
• It proves the mechanical relationships hold -- the hand-offs tie, the match recomputes, the limits are met, the deposits are timely -- not that a provider actually received the money or that the underlying payroll was run correctly.¹⁶
• It re-derives the match, the limits and the deposit timing from the rate, ceilings and safe-harbor window the file carries; it does not decide whether those parameters are the correct ones for the plan year and taxpayer.¹⁷
• It takes the register, provider and ledger records at face value: it confirms they foot and reconcile, not that a deduction was authorized. All shipped data is fictional and the pay period is set in a fictional future.¹⁸

See it run

Integration

Distribution: public repository, MIT license.