cadrumo.adapters.persistence.llm.consent_ledger module

The off-host evidence-consent audit ledger.

Persists one EvidenceConsentLedgerEntry per off-host evidence dispatch that a consent token permitted, to encrypted secure-object storage under LLM_EVIDENCE_CONSENT_LEDGER_NAMESPACE. The entry is appended by LLMClient at the same choke point that HONOURS the token, before the cache read and before any adapter exists, so a dispatch that cannot append refuses rather than transmitting unrecorded. Completeness is therefore a property of the code path rather than of a caller remembering to log.

It records that a transmission was consented, never what was transmitted. The entry carries the evidence’s SHA-256 content ADDRESS, the resolved provider and model, the operator surface that took the acknowledgement, and the timestamp – never the document bytes, the prompt, or the response. That is the same “the address, never the bytes” line EvidenceConsentToken already draws, and it is what keeps the audit trail from becoming a second copy of the confidentiality problem it exists to document.

It is deliberately not pruned. Its three sibling LLM stores (cache, usage, run-telemetry) are swept by _sweep_retention_stores() because they are diagnostic and regenerable. This one is neither: a consent withdrawal reads it to enumerate which artefacts depend on a cloud read, so an entry aged out of existence would make that withdrawal silently incomplete.

See also

cloud_evidence_read_permitted()

The gate whose honoured decisions this ledger records.

EvidenceConsentToken

The per-invocation carrier proving the gate ran; never persisted itself, its two fields are copied into the entry.

LLM_EVIDENCE_CONSENT_LEDGER_NAMESPACE

Secure-object namespace used for the encrypted local store.

evidence_consent

Owns the entry’s record shape and its natural key grammar, so a consumer inside the application layer can recover a stored row’s key without importing this outbound adapter.

class EvidenceConsentLedger

Bases: object

Append-and-read access to the off-host evidence-consent audit trail.

append() is called from the dispatch choke point and raises on ANY failure, so the caller’s refusal is the only possible outcome of a failed write. That is the opposite of record()’s best-effort posture, and deliberately: run-telemetry losing a row costs a diagnostic, this losing a row costs the audit trail its completeness claim.

append(*, evidence_content_address, provider, model, surface)

Record one honoured off-host consent decision.

Parameters:

• evidence_content_address (str) – SHA-256 content address from the token.

• provider (str) – Resolved off-host provider label.

• model (str) – Resolved model identifier.

• surface (str) – Operator surface that took the acknowledgement.

Return type:

EvidenceConsentLedgerEntry

Returns:

The appended EvidenceConsentLedgerEntry.

Raises:

LLMConsentError – When no bucket session is bound (nothing to record against) or the encrypted write fails. The caller MUST let this propagate: an unrecorded off-host dispatch is exactly what this ledger exists to make impossible.

load_entries()

Load every consent entry for the active profile, oldest first.

Return type:

tuple[EvidenceConsentLedgerEntry, ...]

Returns:

The profile’s consent history, the enumeration a withdrawal reads.