Bill references need deterministic normalization

What the public implementation shows

The BillReferenceMapper recognizes BILL-prefixed invoice references and obvious UPR values, populates the corresponding canonical fields, and preserves or normalizes remittance information under explicit tests.

The mapper sits between ISO remittance content and the CoreBank payment DTO used to associate a transfer with a government obligation. This is the implementation fact behind the note; the architectural reading begins from that visible boundary rather than from an assumed production story.

Operating principleReference extraction should add structure while preserving the evidence supplied by the payer.

The decision behind the mechanism

Only recognizable formats become structured invoice or UPR values; unknown text remains remittance rather than being guessed into a financial identifier.

Aggressive parsing can attach a payment to the wrong bill, while no normalization forces every CoreBank integration to reinterpret the same reference syntax. The mechanism matters because it gives that failure a named boundary, durable evidence, and a controlled response instead of leaving the outcome to timing or operator guesswork.

• Recognize only documented prefixes and shapes.
• Preserve original remittance evidence.
• Populate invoice and UPR fields mutually and deliberately.
• Route ambiguous references to controlled exception handling.

How the control should be operated

Reference rules should be versioned, case-aware, whitespace-safe, and tested with valid, empty, ambiguous, and legacy forms.

Government payment matching becomes predictable without losing the payer-provided text needed for exception handling. The reusable lesson is not to copy a class or endpoint in isolation, but to preserve the relationship between identity, state, authority, evidence, and operational ownership.