cadrumo.application.ledger.evidence_input module

In-memory evidence-input representation for on-host LLM reading.

A transient, in-process container for the decrypted bytes of a transaction’s attached evidence (a purchase invoice or a linked attachment), read from secure storage so an on-host reader – the in-tree text-layer or a local vision model – can consume it.

CRITICAL (sensitive-financial-data-secure-storage-only): this object holds decrypted FINANCIAL bytes in process memory ONLY. It MUST NEVER be persisted, serialized to disk, written to a temp file, embedded in a persisted document, or logged. It carries no JSON serializer; EvidenceInput.model_dump and EvidenceInput.model_dump_json are overridden to raise so a stray persistence call fails loudly rather than leaking bytes out of secure storage. The raw data field is excluded from repr for the same reason.

class EvidenceInput(**data)[source]

Bases: BaseModel

Transient in-memory evidence bytes plus the provenance needed to cite them.

Built by the resolver from evidence already held in secure storage. The bytes live only for the duration of a single on-host read; this model is never persisted (see the module docstring and the overridden dump methods).

Variables:

  • mime_type – Concrete MIME type as recorded on the storage manifest (e.g. application/pdf). Carried as provenance and for the vision reader, which needs a concrete image MIME. It is the producer’s LABEL and decides nothing about how the bytes are read; that is document_shape, which is probed from the bytes themselves.

  • document_shape – Content-derived document shape, computed by the required evidence-input capability before this DTO is created.

  • data – The decrypted evidence bytes, in memory only. Excluded from repr.

  • content_sha256 – 64-character lowercase hex SHA-256 of data; the content address the bytes were read under. Enforced to match data.

  • evidence_id – Originating purchase-invoice evidence_id when the bytes came from a PurchaseInvoiceEvidence record, else None.

  • attachment_id – Originating attachment_id when the bytes came from an Attachment, else None.

Parameters:

data (bytes)

mime_type: str
document_shape: DocumentShape
data: bytes
content_sha256: ContentDigest
evidence_id: str | None
attachment_id: str | None
resolve_attachment_evidence_input(attachment_id, *, store, ports, evidence_id=None)[source]

Read stored evidence bytes from secure storage into an EvidenceInput.

The single read path for every evidence byte payload: bytes live in exactly one place (the content-addressed AttachmentStoreProtocol blob for the active bucket), so both evidence tiers reach them through this one function. Loads the attachment manifest and its encrypted blob into memory. No file is written.

Parameters:

  • attachment_id (str) – Content-addressed id of the stored bytes.

  • store (AttachmentStoreProtocol) – Attachment store bound to the operation’s secure-storage bucket.

  • ports (EvidenceInputPorts) – Required application capability for deriving the document shape from the resolved bytes.

  • evidence_id (str | None) – Originating PurchaseInvoiceEvidence record id when the caller reached these bytes through an evidence record, else None for a bare linked attachment. Recorded on the result purely as provenance; it never selects the bytes.

Returns:

In-memory bytes plus provenance, for an on-host read.

Return type:

EvidenceInput

Raises:

PurchaseInvoiceEvidenceInputError – If the bytes match no readable document shape. Judged on the bytes, so the stored MIME type can be wrong in either direction without changing the verdict.

resolve_purchase_invoice_evidence_input(evidence, *, store, ports)[source]

Read a purchase-invoice evidence record’s bytes from secure storage.

The provenance-binding adapter over resolve_attachment_evidence_input(): a PurchaseInvoiceEvidence record holds no bytes of its own, only the attachment_id naming their in-store home written at add time, so the read delegates to the one attachment read path. Reading through this function rather than calling the attachment resolver directly is what guarantees the originating evidence_id is stamped on the result, so a record read can never lose its provenance.

No byte-custody guard is needed or possible: attachment_id is a required field, so a record that reached secure storage has an in-store byte home by construction, and a byte-less record is refused at model validation rather than here. The cleartext source_path is never a fallback byte source (sensitive-financial-data-secure-storage-only).

Parameters:
Returns:

In-memory bytes plus provenance, for an on-host read.

Return type:

EvidenceInput