cadrumo.application.ledger.grounded_reading module

Upgrade a read draft’s unverified claims into checked provenance.

The seam between the reading stage and the grounding stage, and the module that makes the anchor check reachable at all.

A reader returns a draft whose every FieldProvenance envelope is UNANCHORED while carrying the anchor the model reported. That is a deliberate under-claim on the reader’s part rather than a placeholder: the model REPORTING a printed form is a claim about the document, and the check that would turn it into a fact needs the transcription the reading stage does not hold. A check that did not run did not pass.

This module holds the transcription, so it runs the check. Every envelope is re-evaluated against the document text, and the outcome the reader could not justify becomes one it can: ANCHORED where the printed form is really there and parses to the value, CONTRADICTED where it is there and parses to something else, UNANCHORED where it is not there at all. That upgrade is what the wiring buys – before it, the envelopes were honest and empty.

The vision lane is deliberately NOT upgraded here. It produces no independent transcription, so its anchor is self-reported by the same model that produced the value and there is nothing to check it against; those envelopes keep the anchor_self_reported flag and their unverified outcome. Passing a model-produced text off as a transcription would make the check verify a model against itself, which is the failure this whole apparatus is arranged against.

Two further stages run here because they need the whole draft rather than one field: the arithmetic identities (closure_findings()) and, when the caller supplies the filer’s own identifier, counterparty role resolution.

See also

evaluate_anchor()

The per-field check this module applies across a draft.

closure_findings()

The arithmetic identities appended as discrepancies.

resolve_counterparty_identity()

Role resolution, run only when the filer’s identity is known.

GROUNDABLE_ORIGINS

Origins whose anchors can be checked against an independent transcription.

Derived as a named set rather than an inline test so the exclusion is auditable. VISION is present because the vision lane now transcribes and interprets in SEPARATE calls: stage one turns pixels into a transcription and reads no fields, stage two proposes values from that text, and the anchor check runs against stage one’s output. That is the same independence the text lane has – a different reader produced the text the anchor is searched in – so excluding it would now withhold a verdict a real check had earned. It was excluded while one call went image-to-fields, because the only thing an anchor could then be compared against was the reply that asserted it, and a fabricating model is self-consistent. OPERATOR is absent because an operator-supplied value is not a reading of the document at all. DERIVED is absent for a sharper reason than either: a derived value was never printed, so there is no anchor to check and the envelope refuses to carry one. What makes it auditable is its recorded input set, and those inputs are anchored in their own right by whichever origin read them.

verified_provenance(*, draft, transcription)[source]

Return draft’s envelopes with every groundable anchor actually checked.

Parameters:

  • draft (InvoiceDraft) – The read draft, whose envelopes carry reader-reported anchors.

  • transcription (DocumentTranscription) – The independently produced document text.

Return type:

tuple[FieldProvenance, ...]

Returns:

The envelopes, in their original order, each either upgraded by the anchor check or passed through unchanged where no check applies, and each per-party address envelope additionally stamped with whether anything verified the party it was filed under.

ground_draft_against_transcription(*, draft, transcription, legends, operation, taxpayer_tax_id=None)[source]

Return draft with its provenance verified and its findings attached.

The single entry point the router uses after a reader returns. Deterministic and side-effect free: it reads the draft and the transcription and returns a new draft.

Parameters:

  • draft (InvoiceDraft) – The draft a reader produced.

  • transcription (DocumentTranscription) – The independently produced document text the anchors are checked against.

  • legends (tuple[RegimeLegend, ...]) – The dated registry declarations selected by the enclosing pinned authority operation. They are passed to the deterministic regime check without resolving an ambient vocabulary here.

  • operation (PinnedAuthorityOperation) – The caller-owned pinned authority operation used by the deterministic country and territory checks.

  • taxpayer_tax_id (str | None) – The filer’s own identifier, when known. Supplied only so it can be EXCLUDED from counterparty candidacy; role resolution is skipped entirely when it is unknown, because resolving without it would let the filer’s own identifier win the counterparty role.

Return type:

InvoiceDraft

Returns:

A new draft carrying verified envelopes and every deterministic finding.