Keep payroll arithmetic deterministic, preserve its dependencies, and let AI explain results within the reader’s permissions.
A payroll result is useful only if you can explain where it came from. Given a disputed deduction or a corrected timesheet, an engineer should be able to recover the inputs, run the applicable calculation, and identify precisely what changed. A persuasive explanation cannot substitute for that evidence.
This article was drafted with AI assistance, then fact-checked and edited by the developer behind WorkBento.
The engineering boundary is straightforward: deterministic code calculates payroll; an assistant explains recorded results. The difficult work lies underneath that boundary. Employee records change, attendance arrives late, rules acquire new effective dates, and software deployments replace yesterday’s implementation. Reproducibility requires preserving the dependencies of a calculation, not merely improving the prompt that describes it.
The calculation is a function of a preserved world
Consider a salaried employee with an approved unpaid absence and a recurring deduction. Even this modest calculation depends on more than a salary field. It needs a pay period, a compensation agreement, the absence record, the relevant proration policy, the deduction schedule, and rounding rules.
Reading those values from current tables creates a moving target. If someone corrects the absence tomorrow, a rerun may return a different amount while claiming to represent the same payroll run. A rule identifier is equally weak if the rule’s contents can change under that identifier.
I would define a payroll calculation as a function of three preserved dependencies:
- An input snapshot containing the facts used for that calculation.
- A rule bundle containing the applicable policies, parameters, and effective-date decisions.
- A calculator artifact identifying the implementation that executed those rules.
The output should include line items and calculation evidence, not just a net amount. A deduction line can record the input references, rule reference, intermediate amounts, and rounding operation that produced it. That gives both a human reviewer and an explanation service something concrete to inspect.
Determinism also requires controlling hidden dependencies. The calculator should not consult the current clock, fetch a live rate, or read a mutable employee record halfway through execution. Resolve those dependencies before calculation and include their values in the snapshot. Where dates matter, preserve the payroll calendar and timezone interpretation as well.
Version the facts, rules, and implementation separately
A single version number for the payroll service cannot describe everything that changed. An unchanged binary may calculate different results because a compensation agreement changed. An unchanged input snapshot may produce different results because the rule bundle changed. Those are different causes, and an audit should distinguish them.
The input snapshot needs the values actually consumed: compensation terms, attendance and leave quantities, applicable deductions, currency, period boundaries, and any external parameters. Preserve units. A quantity of 8 is ambiguous unless its meaning is recorded as hours, days, or another defined unit. Keep source record identifiers and revision references alongside copied values so a reviewer can trace their origin.
Rules need both identity and content. Preserve the selected rule bundle, its effective interval, and the resolved parameters. If a policy chooses a divisor based on a calendar, retaining only the policy name leaves a dependency missing. The calculation must retain the calendar or the resolved divisor and sufficient evidence of its selection.
The implementation needs more than a Git commit if the executable depends on libraries or build configuration. An immutable build artifact, dependency lockfile, and relevant runtime configuration make a stronger execution record. An artifact digest identifies what ran; it does not by itself ensure that the artifact remains available. Retention is part of the design.
Finally, preserve the results and the review history. Approval should refer to the exact calculation being approved, including its manifest and result digests. Otherwise an input edit can quietly detach the approved amount from the amount subsequently released.
This does not require copying an entire HR database for every employee. Store the calculation’s dependency closure: the facts and artifacts it actually used. Shared immutable rule bundles can be referenced by many runs. Sensitive snapshots still need access controls and a retention policy; reproducibility is not a reason to retain unrelated personal data.
Give each run a small, explicit manifest
The manifest ties these dependencies together. It is an execution record, not a substitute for the referenced data. A compact example might look like this:
{
"schema_version": 1,
"run_id": "payrun-2026-09-r2",
"supersedes": "payrun-2026-09-r1",
"period": {"start": "2026-09-01", "end_exclusive": "2026-10-01"},
"currency": "USD",
"input_snapshot_id": "inputs-184",
"rule_bundle_id": "rules-27",
"calculator_artifact_id": "calculator-12",
"rounding_policy_id": "rounding-3",
"result_id": "result-184"
}
Here, every referenced identifier must resolve to an immutable stored object. The period uses an explicit exclusive end to remove a common boundary ambiguity. The supersedes field records a correction without overwriting its predecessor. The identifiers are illustrative; a production implementation should also retain verified content digests and the serialization scheme used to compute them.
Serialization matters because equivalent data can have different byte representations. Define field ordering, date formats, decimal encoding, and schema versions before hashing a manifest. Use decimal arithmetic or appropriately scaled integers for money, with explicit rounding at the stages required by the applicable rules. A digest cannot repair an unspecified rounding policy.
There is a practical tradeoff here. Storing resolved values simplifies replay but duplicates data. Storing references reduces duplication but makes replay depend on reliable historical storage. I prefer immutable references for shared artifacts and explicit snapshots for employee-specific calculation facts. The important property is that neither path silently resolves to the latest value.
Approval must bind to a calculation, not a period
A useful main state model is Prepared → Calculated → Approved → Released. Each state describes a different kind of evidence.
Prepared means the manifest and its dependencies have been assembled and frozen. Calculated means the engine has produced a stored result against that manifest. Approved means an authorized reviewer has accepted that exact manifest and result. Released means the approved result has been handed to the configured downstream process, with a release record identifying what was sent.
Release does not automatically mean that money settled successfully. If the system needs settlement tracking, model it separately using evidence from the payment process. Avoid giving a local state a stronger meaning than its evidence supports.
Any calculation-affecting correction creates a successor run at Prepared. It should not move an Approved run backward while replacing its contents. The successor can refer to the predecessor and explain the changed inputs. Whether a correction requires a replacement payment or an adjustment in another period depends on the applicable process; preserve that decision rather than burying it in arithmetic.
A review screen should show the difference between runs at the line-item level. “Net pay changed” is insufficient. A reviewer needs to see that an absence quantity changed, which rule consumed it, and which amounts consequently changed. The comparison itself should be reproducible from the two preserved results.
Test this contract with known calculation fixtures and replay tests. Also test the failure boundaries: a missing artifact should fail replay explicitly; changing an input should invalidate an existing approval reference; repeated release requests should not create duplicate downstream work. These tests exercise the lifecycle around the arithmetic, where otherwise-correct payroll engines can lose their audit trail.
Let AI explain evidence without becoming a dependency
An assistant can help answer “Why is this deduction higher than last period?” It should retrieve the relevant stored line items, their rule references, and the authorized comparison data. It can then turn that evidence into readable prose.
It should not invent a missing rule, infer an unrecorded agreement, or calculate an authoritative replacement amount from a conversation. If the stored result lacks enough evidence, the useful answer identifies what is missing. Fluency is not a reason to fill the gap.
Permissions apply before retrieval. An employee may be allowed to inspect their own payslip while a payroll reviewer can inspect a wider set of records. The explanation path should receive only the evidence permitted for the requesting user. Restricting the final wording after unrestricted retrieval is a fragile boundary, especially when comparisons involve other employees.
Keep the assistant outside the calculation state machine. Generating an explanation must not approve a run, change an input, or release a payment. A failed explanation request should have no effect on the stored payroll result.
There are also two different reproducibility goals. The financial result should replay from its preserved dependencies. Generated prose may vary across model versions or inference settings. If an explanation must be audited, retain the displayed text, evidence references, requesting identity, model identifier, and relevant prompt configuration under an appropriate retention policy. Recording a prompt alone does not guarantee identical future prose.
I would start with deterministic explanations for common line items and use AI where questions span multiple records or need contextual phrasing. That keeps routine payslip evidence available even when the assistant is disabled.
Applying the boundary in an HR platform
My own product, WorkBento — Python HR and Payroll Platform, is a concrete setting for this separation. It is a self-hosted FastAPI and React platform using PostgreSQL with pgvector, MongoDB, and Meilisearch. Its modules include employees, attendance, shifts, leave approvals, and payroll, among other business functions. Those domains illustrate why a calculation must preserve its dependencies across mutable operational records.
WorkBento’s optional assistant answers questions from company data through a guarded read-only SQL layer and applies the requesting user’s permissions. That provides a concrete retrieval boundary for an explanation service. It does not, by itself, establish deterministic payroll replay or approval binding; those require the manifest, immutable dependencies, and lifecycle contracts described above.
Docker Compose deployment and full source code are included, allowing builders to inspect how the platform is assembled and evaluate the boundaries for their own requirements.
Top comments (0)