cadrumo.application.ledger.confirmation_record module

The persisted provenance of one human confirmation.

The review gate’s third rule, and the one that makes the other two auditable: a confirmation is itself a record, not merely an event that happened to an invoice. It names who confirmed, when, which fields they asserted values for, which findings they answered and how, and the content addresses of the evidence bytes and the transcription the decision was taken against.

A correction is an assertion, not an edit. When the operator overrides a field, the document-derived value is never overwritten in place. The draft’s envelope for that field is re-stamped OPERATOR — so nothing downstream can read an operator’s figure as something the document stated — while this record retains the PRIOR value and the PRIOR origin beside the asserted one. That pairing is the whole point: the record can always answer “what did the document say, and what did the operator assert instead”, and an override that merely overwrote could answer neither half.

Why the content addresses ride here. A consent withdrawal, or a later audit, re-derives what a confirmation was actually taken against. Naming the evidence and transcription by content address rather than by id means the re-derivation can prove the bytes are the same bytes; an id alone survives the artefact being replaced underneath it.

See also

ConfirmationBlocker

The findings whose resolutions this record carries.

InvoiceDraft

The reading the assertions are recorded against.

Invoice

The record the confirmation minted.

class FieldAssertion(**data)

Bases: BaseModel

One field the operator asserted a value for, beside what the document said.

Variables:

• field – Name of the InvoiceDraft field.

• asserted_value – The value the operator asserted, as printed. Always carried as a string: the record is about what was CLAIMED, and re-typing it into the field’s own type would re-run the parse the assertion exists to sit beside.

• prior_value – What the reading path proposed, or None when it proposed nothing — a supplied value where the document was silent is a different act from a correction, and the record distinguishes them.

• prior_origin – How the prior value was obtained, or None when there was no prior value. Retained rather than discarded: “the operator corrected an exactly-read structured field” and “the operator corrected a vision guess” are not the same event, and only this field can tell them apart after the fact.

• prior_grounding – What checking the prior value survived, or None.

Parameters:

data (Any)

field: str

asserted_value: str

prior_value: str | None

prior_origin: FieldOrigin | None

prior_grounding: FieldGroundingOutcome | None

class ResolvedFinding(**data)

Bases: BaseModel

One blocking finding paired with the answer that cleared it.

Stored as the pair rather than as the resolution alone. A resolution names a blocker by id, and an id whose blocker is not recorded beside it is unreadable the moment the draft is discarded — which is exactly when the audit happens.

Variables:

• blocker – The finding as the gate raised it.

• resolution – The operator’s explicit answer to it.

Parameters:

data (Any)

blocker: ConfirmationBlocker

resolution: FindingResolution

class InvoiceConfirmationRecord(**data)

Bases: BaseModel

The provenance of exactly one operator confirmation.

Variables:

• confirmation_id – Clock-free derived address, folding the confirmed outcome rather than the moment. A retried confirm of the same document by the same actor asserting the same values addresses the same record instead of accumulating near-duplicates.

• bucket_id – The bucket the confirmation happened in.

• invoice_id – The invoice the confirmation minted or matched.

• evidence_reference – The evidence or attachment id confirmed from.

• evidence_sha256 – Content address of the evidence bytes, so a later re-derivation can prove the same document was read.

• transcription_sha256 – Content address of the stage-one transcription the draft was read from, or None when the reading lane produced none (the vision lane reads image to fields in one call).

• extractor – Which reader produced the draft, so a confirmation taken against a superseded extractor is identifiable.

• confirmed_by – Who confirmed.

• confirmed_at – When.

• assertions – Every field the operator asserted a value for, each carrying the prior value and origin.

• resolutions – Every blocking finding and the answer that cleared it.

Parameters:

data (Any)

confirmation_id: str

bucket_id: BucketId

invoice_id: InvoiceId

evidence_reference: str

evidence_sha256: ContentDigest | None

transcription_sha256: ContentDigest | None

extractor: str

confirmed_by: str

confirmed_at: UtcInstant

assertions: tuple[FieldAssertion, ...]

resolutions: tuple[ResolvedFinding, ...]

checks_run: tuple[str, ...] | None

Which deterministic checks ran when this record was minted.

Derived from the one declaration the readers execute (DETERMINISTIC_CHECKS), never restated, so a check added there reaches every later record without a second place to remember.

None means the record makes NO CLAIM about which checks ran, and that is a third state rather than a shorthand for either extreme. Records minted before this field existed carry it, and they are not evidence that no check ran (a lie toward alarm) nor that every current check ran (a lie toward assurance) – a record attests what ran at its own minting, and one that never recorded the set simply does not say. An empty tuple is a different claim entirely: that the set was recorded and was empty.

Not backfilled, deliberately. The compatibility regime is pre-release, so reconstructing the set for existing records would be inventing a claim they never made – which is the exact misreading this field exists to prevent.

derive_confirmation_id(*, bucket_id, invoice_id, evidence_reference, confirmed_by, assertions, resolutions)

Return the clock-free derived address for one confirmation.

Folds the OUTCOME — who confirmed what, against which evidence, asserting which values, answering which findings — and never the clock. A derived id that folded the timestamp would make an idempotent retry address a new record, which is the shape that lets one operator decision be counted twice.

Return type:

str

Parameters:

• bucket_id (str)

• invoice_id (str)

• evidence_reference (str)

• confirmed_by (str)

• assertions (Sequence[FieldAssertion])

• resolutions (Sequence[ResolvedFinding])

class ConfirmationRecordDocument(**data)

Bases: BaseModel

One bucket’s confirmation provenance records.

Parameters:

data (Any)

bucket_id: BucketId

records: tuple[InvoiceConfirmationRecord, ...]

confirmation_record_object_key(document)

Return the bucket-scoped natural key for one confirmation document.

Return type:

str

Parameters:

document (ConfirmationRecordDocument)

class ConfirmationRecordRepositoryProtocol(*args, **kwargs)

Bases: Protocol

Persistence operations required by confirmation-record policy.

load(identifier)

Load the document stored under identifier, when present.

Return type:

ConfirmationRecordDocument | None

Parameters:

identifier (str)

save(payload)

Persist one complete confirmation-record document.

Return type:

None

Parameters:

payload (ConfirmationRecordDocument)

class ConfirmationRecordRepositoryFactory(*args, **kwargs)

Bases: Protocol

Construct a confirmation repository for one bucket and storage configuration.

bind_confirmation_record_repository_factory(factory)

Bind one outward-composed confirmation repository factory.

Return type:

Generator[ConfirmationRecordRepositoryFactory]

Parameters:

factory (ConfirmationRecordRepositoryFactory)

load_confirmation_records(bucket_id, settings=None)

Load a bucket’s confirmation records, or an empty document when none exist.

Return type:

ConfirmationRecordDocument

Parameters:

• bucket_id (str)

• settings (Settings | None)

write_confirmation_record(*, record, settings=None)

Persist one confirmation record, idempotently on its derived id.

A retry of the same confirmation — same actor, same evidence, same assertions, same resolutions — addresses the record already stored and returns it unchanged rather than appending a second account of one human decision.

Return type:

InvoiceConfirmationRecord

Parameters:

• record (InvoiceConfirmationRecord)

• settings (Settings | None)

field_assertions(*, draft, overrides)

Return one assertion per field the operator actually supplied a value for.

Parameters:

• draft (InvoiceDraft) – The reading the assertions are recorded against, supplying the prior value and the envelope that says how it was obtained.

• overrides (Mapping[str, object | None]) – Operator-supplied values keyed by draft field name. A None entry means the operator supplied nothing for that field and is skipped — silence is not an assertion.

Return type:

tuple[FieldAssertion, ...]

Returns:

Assertions in draft-field declaration order, so two confirmations of the same document derive the same id regardless of how the caller ordered its overrides.

re_stamped_provenance(*, draft, assertions)

Return draft’s envelopes with every asserted field re-stamped OPERATOR.

The other half of “a correction is an assertion”. The prior envelope is REPLACED here rather than kept beside the new one, and that is deliberate: a draft field carries exactly one envelope, so leaving the document’s envelope on a field the operator overrode would tell every downstream consumer the operator’s figure was read from the document. The prior value and origin are not lost — they are in the InvoiceConfirmationRecord, which is the record that exists to hold them.

An asserted field’s outcome is UNANCHORED and never ANCHORED: an operator’s value is not a reading of the document at all, so there is no verbatim occurrence it could be anchored to, and stamping one would launder an assertion into a corroborated reading.

Parameters:

• draft (InvoiceDraft) – The reading whose envelopes are being re-stamped.

• assertions (Sequence[FieldAssertion]) – The operator’s assertions, one per overridden field.

Return type:

tuple[FieldProvenance, ...]

Returns:

The envelope tuple, in the input order, with asserted fields replaced.

build_confirmation_record(*, bucket_id, invoice_id, evidence_reference, evidence_sha256, draft, extractor, confirmed_by, overrides, blockers=(), resolutions=())

Assemble the confirmation record for one confirmed draft.

Parameters:

• bucket_id (str) – The bucket the confirmation happened in.

• invoice_id (str) – The invoice minted or matched.

• evidence_reference (str) – The evidence or attachment id confirmed from.

• evidence_sha256 (str | None) – Content address of the evidence bytes, when known.

• draft (InvoiceDraft) – The reading confirmed, supplying prior values and the transcription address.

• extractor (str) – Which reader produced the draft.

• confirmed_by (str) – Who confirmed.

• overrides (Mapping[str, object | None]) – Operator-supplied values keyed by draft field name.

• blockers (Sequence[ConfirmationBlocker]) – The blocking findings the gate raised.

• resolutions (Sequence[FindingResolution]) – The operator’s answers, one per blocker.

Return type:

InvoiceConfirmationRecord

Returns:

The assembled record, not yet persisted.