Complete empty cross-checked fields from master data at emission time

[jbagsik]

Part of

Field fidelity and validation of parsed e-invoices — using what corroboration already knows, instead of leaving a conformance gap for a human to close by hand.

Context

Corroboration compares parsed values against the matched debtor's master data and reports where they disagree (#46). It deliberately never changes a value: the query is derived-only and a match can be flagged, never overturned (ADR 0003). So today a field that the document does not print, or that the parser read incompletely, stays empty all the way into the artifact — even when the matched master-data record holds exactly that value, and even when its absence breaks a conformance rule. BR-11 makes the buyer country mandatory, and BR-57 makes the country mandatory wherever an address is emitted.

This ticket closes that gap at emission time only. Nothing is written back into the invoice.

What to build

A resolver in the artifact path that completes empty cross-checked fields from the matched master-data record when the match is unambiguous, records what it completed, and leaves the persisted invoice untouched.

Acceptance criteria

• Completion is applied when the model is translated into the converter contract (the adapter seam), not when the invoice is persisted. No path writes a master-data value into an invoice column.
• The eligible field set is the configured cross-checked set — no second list — and it reuses the field → master-data attribute mapping of Master-data divergence query service (derived, per field) #46, so a field the mapping does not know is reported rather than silently skipped.
• Only an empty field is completed. A field that carries a parsed value is never replaced, even when master data disagrees; that case stays a divergence.
• Completion requires an unambiguous match: exactly one attributed record, and for an address exactly one candidate on that record or within its company tree. Two or more candidates produce no completion.
• A completed field carries its own status, distinct from parsed and db_validated, and counts against the score as a finding rather than as a clean reading.
• A completed field does not block dispatch when the resulting artifact is conformant.
• Provenance is recorded per completed field on the document — which value, from which record, when — so an archived artifact stays explainable without re-deriving it.
• Where the completion is what makes an address emittable, the emitted address carries the country (BR-57); where no completion was possible, the address group is omitted rather than emitted incomplete.
• Pest tests: empty field completed on a single match; two candidates produce no completion; a populated field is never overwritten; the invoice row is unchanged after artifact generation; the completed field is not counted as clean; provenance is readable after the fact; a field absent from the Master-data divergence query service (derived, per field) #46 mapping is reported.
• Documentation updated in the same PR (README / docs/ / CHANGELOG), or explicitly stated why none was needed.

Notes

The rule this implements: a master-data value may complete a fact the document already asserts; it may not introduce a fact the document is silent about. Completing the country of a printed address is allowed. Assembling a whole consignee out of the buyer address is not — that stays forbidden.

Line-level fields are out of scope: the mapping of #46 is document-scoped. Line consignees keep their own path.

Blocked by

• Master-data divergence query service (derived, per field) #46 — master-data divergence query service (supplies the field → attribute mapping).
• Delivery becomes a party with a name invoice#8 — delivery becomes a party with a name (supplies the field this first applies to).