Hash-Total Validation Controls for Municipal Billing Batches

A billing batch does not stay still. The same set of charges is rated, folded into a balanced journal, serialized to a posting file, and finally written into an enterprise resource planning (ERP) general ledger — and every one of those hand-offs is a place where a record can quietly vanish, get counted twice, or have its amount rewritten by a mis-mapped field. This page sits inside Billing Reconciliation & Audit Logging, and it covers the specific detective control that proves the batch that left rating is byte-for-byte the same population that reached the ledger: batch control totals and hash totals. A control total is a small, independently recomputable summary of a batch — how many records it holds, what they sum to in exact Decimal money, and a single order-independent digest over the fields that must never change. Seal that summary at the source, recompute it after every transform, and compare. When the numbers agree at each boundary you have positive evidence that nothing was dropped, added, or altered; when they disagree the batch is held before it can post, not reconciled after a customer complains. This is a detection control, and it is deliberately distinct from the tamper-evident hash chaining used to protect an append-only log — that lives under GASB audit-trail compliance patterns and answers a different question, as the closing section explains.

# Prerequisites

Control totals only tell the truth if the primitives underneath them are deterministic. Version drift here silently changes what “the same batch” means.

• Python 3.11+. Required for StrEnum, zoneinfo, and the structured-concurrency and typing features the surrounding pipeline relies on. Never naive datetime on any record field that participates in a digest.
• decimal.Decimal for every monetary amount. Amount control totals are summed thousands of times across replays and reconciliations; binary float introduces sub-cent drift that makes a clean batch look tampered and a tampered batch look clean. Quantize once to a fixed exponent before any amount enters a total.
• A stable canonical field set per record. Decide explicitly which fields define record identity and value (bill id, account, service, quantized amount). Only those feed the digest; presentation fields that a downstream stage is allowed to add must be excluded.
• A durable place to persist each seal. The control-total record computed at the source must survive to be compared at the ERP boundary, so it is stored alongside the batch, not held in memory.
• Append-only audit storage for every seal and every comparison verdict, so a reviewer can reconstruct which boundary a batch failed at and when.
• A hold/quarantine path the pipeline can divert a batch into. A mismatch must be able to stop a posting, which means posting must be gated on the comparison, not run in parallel with it.
• Data-model assumption: a batch is a finite list of billing records with a unique per-record identifier; legitimate value-changing transforms (tax, rounding true-ups) are explicit and quantified, never incidental.

# Architecture Overview

Think of the control total as a sealed tag that travels with the batch. Rating produces the records and seals them; each later stage recomputes the tag from the records it actually holds and compares it to the tag it received. A pass-through stage such as manifest assembly must reproduce the tag exactly — same count, same amount total, same digest. A stage that legitimately changes value re-seals with a quantified, documented delta. Any unexplained difference diverts the whole batch to a hold lane and raises an alarm before a single line posts to the ledger.

Figure: The control total is sealed once at the source and independently recomputed at each boundary; a match is positive evidence of an intact batch, a mismatch holds the batch before it can post.

The discipline is deliberately blunt. The comparison does not try to repair a batch or reason about which record is wrong — that is the job of the difference report an operator reads later. Its only decision is binary: the recomputed total either equals the sealed total or it does not, and only the equal case is allowed to proceed. That bluntness is what makes it trustworthy as a control; a check that quietly corrected small discrepancies would be the very hole an auditor looks for. The deep mechanics of computing the digest itself — canonicalization, quantization, and a component-by-component diff — are covered in the companion walk-through, computing batch hash totals for billing runs; this page is about wiring that primitive into every stage boundary.

# Step-by-Step Implementation

# Step 1 — Define the ControlTotals record

The control total is three numbers that summarize a batch independently of its representation: how many records it holds, what they sum to in exact money, and a single digest over the fields that define each record. Modeling it as a frozen value object makes equality — the whole point of the control — a one-line comparison, and makes the record safe to persist and pass between stages without anyone mutating it in flight.

from dataclasses import dataclass
from decimal import Decimal

@dataclass(frozen=True, slots=True)
class ControlTotals:
    """An independently recomputable summary of one billing batch."""
    count: int              # how many records the batch holds
    amount_total: Decimal   # exact sum of quantized amounts, never float
    digest: str             # order-independent SHA-256 over canonical rows

    def matches(self, other: "ControlTotals") -> bool:
        # Frozen dataclass equality already compares all three fields;
        # naming the check makes the control's intent explicit at call sites.
        return self == other

Each field catches a different failure mode. The count catches a dropped or duplicated record even when amounts happen to net out. The amount_total catches a rewritten value even when the record population is unchanged. The digest catches a swap that keeps both the count and the sum identical — two records whose amounts were transposed, for instance. You need all three; any one alone has a blind spot the other two cover.

# Step 2 — Seal the batch at the source

Sealing happens once, at rating output, before the batch is handed to any other stage. The canonical row is the honest identity of a record: only the fields whose change would mean corruption. Amounts are quantized to a fixed exponent before they enter either the sum or the digest, so the same economic batch always seals to the same numbers regardless of how an upstream float or trailing zero was formatted.

import hashlib
from decimal import Decimal

CENTS = Decimal("0.01")

def canonical_row(rec: dict) -> str:
    """The identity-and-value fields that must never silently change."""
    amount = rec["amount"].quantize(CENTS)          # fixed exponent, deterministic
    return "|".join((rec["bill_id"], rec["account_id"], rec["service"], f"{amount}"))

def seal(records: list[dict]) -> ControlTotals:
    """Compute the control total for a batch. Independent of record order."""
    rows = sorted(canonical_row(r) for r in records)     # order-independent
    joined = "\n".join(rows).encode("utf-8")
    digest = hashlib.sha256(joined).hexdigest()
    total = sum((r["amount"].quantize(CENTS) for r in records), Decimal("0"))
    return ControlTotals(count=len(records), amount_total=total, digest=digest)

Sorting the canonical rows before hashing is what makes the digest order-independent: the manifest stage is free to reorder records for a balanced journal, and a parallel worker is free to emit them in a nondeterministic sequence, without changing the seal. Persist the returned ControlTotals next to the batch — it is the reference every later boundary compares against, so it must outlive the process that produced it.

# Step 3 — Recompute and compare at each stage boundary

Every stage that receives the batch reseals it from the records it actually holds and compares against the seal it was handed. A pass-through stage — one that reorders or reformats but must not change the population or the money — has to reproduce the seal exactly. This is the boundary the double-entry journal manifest generation stage must clear before its manifest is trusted.

class ControlTotalMismatch(Exception):
    """Raised when a recomputed control total diverges from its seal."""

def assert_no_drift(sealed: ControlTotals, present: ControlTotals, stage: str) -> None:
    """Guard a pass-through boundary: the batch must be identical across it."""
    if not sealed.matches(present):
        raise ControlTotalMismatch(
            f"{stage}: expected count={sealed.count} total={sealed.amount_total} "
            f"digest={sealed.digest[:12]}…, got count={present.count} "
            f"total={present.amount_total} digest={present.digest[:12]}…"
        )

The exception carries all three components of both sides, so the eventual difference report can point an operator at which dimension drifted — a count delta reads as a dropped or added record, an amount delta with an intact count reads as a rewritten value, and a digest-only delta reads as a same-count, same-sum alteration such as a field swap.

# Step 4 — Gate the ledger on the comparison and hold on mismatch

The comparison is only a control if posting cannot happen without it. The driver runs the stages in order, reseals at each boundary, and routes the entire batch to a hold on the first mismatch — it never posts a partial batch and never posts around a failed check. Because a mismatch stops the run, the same idempotency and dead-letter discipline used in error handling and retry workflows applies to the held batch, so a later replay after a fix cannot double-post.

from datetime import datetime, timezone

def run_with_controls(records: list[dict], manifest_stage, posting_stage,
                      hold, audit_log: list[dict]) -> bool:
    sealed = seal(records)                                  # Step 2: seal at source
    audit_log.append({"event": "sealed", "count": sealed.count,
                      "total": str(sealed.amount_total),
                      "ts": datetime.now(timezone.utc).isoformat()})

    manifest = manifest_stage(records)                     # pass-through transform
    try:
        assert_no_drift(sealed, seal(manifest), "manifest-boundary")
        assert_no_drift(sealed, seal(posting_stage(manifest)), "posting-boundary")
    except ControlTotalMismatch as exc:
        hold.quarantine(records, reason=str(exc))          # whole batch, not a row
        audit_log.append({"event": "held", "reason": str(exc),
                          "ts": datetime.now(timezone.utc).isoformat()})
        return False                                        # nothing posts

    audit_log.append({"event": "posted", "count": sealed.count,
                      "ts": datetime.now(timezone.utc).isoformat()})
    return True

Note that a held batch is quarantined whole. Posting the records that happen to reconcile while holding back the ones that do not would defeat the control, because a control total says something about the population, not about individual rows; splitting the batch would post an amount total no seal ever vouched for.

# Step 5 — Re-seal across a legitimate value-changing transform

Not every stage is pass-through. A tax stage, a rounding true-up, or a late adjustment legitimately changes the amount total, and a naive equality check would flag it as tampering. The rule is that any value change must be quantified in advance: the stage declares the delta it intends to apply, and the boundary asserts the observed change equals the declared one — count unchanged, amount total moved by exactly the expected amount — then re-seals for the next stage. This is the same principle the ERP general-ledger posting integration relies on when it maps net charges to debit and credit lines.

def reseal_after_transform(before: ControlTotals, after: ControlTotals,
                           expected_delta: Decimal, stage: str) -> ControlTotals:
    """Allow a transform to change amounts only by a pre-declared amount."""
    if after.count != before.count:                        # a value change must not
        raise ControlTotalMismatch(                        # add or drop records
            f"{stage}: count changed {before.count} → {after.count}")
    actual_delta = after.amount_total - before.amount_total
    if actual_delta != expected_delta:
        raise ControlTotalMismatch(
            f"{stage}: amount delta {actual_delta} != declared {expected_delta}")
    return after                                            # new seal for next stage

Requiring the delta up front converts an invisible mutation into an explicit, auditable event: the tax stage does not merely change the total, it commits to how much it will change the total, and the control proves it kept that promise. Anything else — a delta that is larger, smaller, or attached to a changed count — halts the batch exactly as an unexplained mutation would.

# Edge-Case Handling

The failures that make control totals lie are subtle and almost always about determinism. Each of these has quietly broken a real reconciliation.

• A float creeping into the amount total. If any amount reaches seal() as a binary float, the same economic batch can sum to 1234.5700000000001 on one side and 1234.57 on the other, and the amount control fails on a batch that is actually intact. Quantize to a fixed exponent as the value enters the total, and keep every amount a Decimal end to end — this is the same non-negotiable that governs step-rate and block-rate structure design.
• Ordering nondeterminism between stages. A parallel manifest builder or a set-backed collection can emit records in a different order on each run. The digest must be computed over sorted canonical rows so order cannot change the seal; if you hash in arrival order instead, every reorder looks like tampering and the control becomes noise operators learn to ignore.
• Null or None fields in the canonical row. A record with service = None and a record with service = "" must not canonicalize to the same string, or a genuine field loss will hide behind an unchanged digest. Serialize None to an explicit sentinel distinct from every real value before it joins the row, rather than letting str(None) collide with the literal text "None".
• A partial or truncated batch. If a stage receives a batch cut short by a failed read or an early break, the count control catches it immediately — but only if the seal was taken over the complete source population. Seal at the true source of record, before any filtering, so a downstream truncation shows up as a count delta rather than passing a reseal taken over the already-truncated set.
• Legitimately changed amounts mistaken for tampering. Tax, penalties, and rounding true-ups change the total on purpose. Route them through the declared-delta reseal of Step 5 rather than a plain equality check, so an intended change is proven correct and only undeclared changes trip the control.
• Duplicate records that are genuinely valid. Two identical line items (say, two equal service charges on one account) are a legitimate multiset, not a bug. Because the digest is built from sorted rows with duplicates retained, the count and digest both reflect the true multiplicity — so a later stage that de-duplicates them “helpfully” is correctly caught as an alteration.

# Verification and Audit Trail

A control total is only as credible as the evidence that it was actually computed and compared. Every seal, every boundary verdict, and every hold appends an entry to append-only audit storage, so a reviewer can reconstruct — without trusting the pipeline’s own success flag — which boundary a batch cleared, which one it failed, and by exactly how much. Two independent properties are worth asserting continuously against historical fixtures.

First, order independence: sealing a batch and sealing any shuffle of the same batch must yield an identical ControlTotals. If a reorder changes the seal, the digest is not canonical and every legitimate reordering will raise a false mismatch. Second, sensitivity: dropping one record, adding one, or altering a single amount by one cent must each change at least one of the three components. If any of those mutations slips through, the control has a blind spot.

from decimal import Decimal
import copy, random

def _fixture() -> list[dict]:
    return [
        {"bill_id": "B-1001", "account_id": "A-77", "service": "water",
         "amount": Decimal("42.50")},
        {"bill_id": "B-1002", "account_id": "A-77", "service": "sewer",
         "amount": Decimal("18.00")},
        {"bill_id": "B-1003", "account_id": "A-90", "service": "water",
         "amount": Decimal("42.50")},   # a legitimate duplicate amount
    ]

def test_order_independent() -> None:
    batch = _fixture()
    shuffled = random.sample(batch, k=len(batch))
    assert seal(batch) == seal(shuffled)                  # reorder must not matter

def test_detects_drop_add_and_alter() -> None:
    base = seal(_fixture())

    dropped = _fixture()[:-1]
    assert seal(dropped).count != base.count              # a lost record shows up

    altered = copy.deepcopy(_fixture())
    altered[0]["amount"] = Decimal("42.51")               # one-cent change
    changed = seal(altered)
    assert changed.amount_total != base.amount_total
    assert changed.digest != base.digest                  # amount and digest both move

    swapped = copy.deepcopy(_fixture())
    swapped[0]["amount"], swapped[1]["amount"] = (
        swapped[1]["amount"], swapped[0]["amount"])        # transpose two amounts
    tswap = seal(swapped)
    assert tswap.count == base.count and tswap.amount_total == base.amount_total
    assert tswap.digest != base.digest                     # only the digest catches it

Run these against fixtures drawn from real historical batches — including the awkward ones with duplicates, zero-amount adjustments, and mid-cycle tax changes — before any change to a stage’s transform logic ships. The swap case is the one that justifies carrying a digest at all: it is invisible to both the count and the amount total, and only the order-independent hash total detects it.

# Troubleshooting

# Frequently Asked Questions

# How is a hash total different from a hash-chained audit log?

They answer different questions. A hash total is a detective control over a batch: it summarizes a whole population into a count, an amount total, and one order-independent digest, so recomputing it at a later stage proves no record was dropped, added, or altered in transit. A hash chain is a tamper-evidence control over a log: each entry embeds the hash of its predecessor, so any retroactive edit to the sequence breaks the links. One proves a batch survived a hand-off intact; the other proves a historical record was not rewritten after the fact. The hash-chaining pattern is covered separately under GASB audit-trail compliance patterns.

# Why compute three separate totals instead of just one hash?

Because each catches a failure the others miss, and the diagnostics matter. A count delta immediately says “a record was dropped or duplicated”; an amount delta with an intact count says “a value was rewritten”; a digest-only delta says “the population and sum held, but a field changed — likely a swap.” A single digest would catch all three but tell you nothing about which happened, turning every mismatch into a blind investigation. Carrying all three turns a mismatch into a pointed difference report.

# Why must the digest be order-independent?

Because legitimate stages reorder records. A manifest builder groups lines for a balanced journal, a parallel worker emits results in nondeterministic order, and a database read returns rows in whatever order the planner chose. If the digest depended on order, every one of those harmless reorderings would raise a false mismatch and operators would quickly learn to override the control — which is worse than not having it. Sorting the canonical rows before hashing makes the seal a property of the set of records, not the sequence.

# What should happen when a control total mismatches?

The whole batch is held before it posts, an alarm fires, and a difference report is generated from the two ControlTotals records. Nothing posts — not even the records that happen to reconcile — because a control total is a statement about the population, and posting a subset would post an amount no seal ever vouched for. After the root cause is fixed, the batch is replayed through the same idempotent posting path so the correction cannot double-post.

# Can I use hash totals to reconcile against the general ledger?

Partly. The amount control total is exactly the figure you compare against the ledger’s posted sum for the batch, and a count control confirms the right number of records landed. But full ledger reconciliation also matches debits to credits and ties each line back to its source, which is a broader activity than a batch control total performs. Use hash totals as the fast, per-boundary gate that stops a corrupted batch from ever reaching the ledger, and reconcile the posted result against the ledger as the independent second check.

# Related Topics

• Billing Reconciliation & Audit Logging — the subsystem these batch controls protect end to end.
• Computing Batch Hash Totals for Billing Runs — the focused walk-through of the fingerprint function and its canonicalization.
• Double-Entry Journal Manifest Generation — the pass-through stage that must reproduce the seal exactly.
• ERP General-Ledger Posting Integration — the posting boundary the control gates before anything reaches the ledger.
• GASB Audit-Trail Compliance Patterns — the distinct hash-chaining control for tamper-evident logs.
• Error Handling & Retry Workflows — the idempotent replay discipline a held batch is resubmitted through.

Up one level: Billing Reconciliation & Audit Logging · Return to the utilitybilling.org home.