cadrumo.adapters.outbound.llm.retention module

Canonical two-stage retention selection for the LLM secure-object stores.

The response cache (LLMCache), the usage ledger (UsageRecorder), and the run-telemetry recorder (LLMRunTelemetryRecorder) each bound their store under one operational obligation: an age cutoff, then an oldest-first record-count cap. The namespaces, the settings that supply the bounds, and the record timestamp field differ per store by design – the cache and the usage ledger stamp created_at at write time while a run record carries its own started_at. The ordering and boundary policy is not a per-store choice, so it lives here once and each store supplies its timestamp as a projection.

Deletion stays with the caller: each store owns its own secure-object namespace and its own missing-key contract, so this module selects keys and never removes anything.

select_retention_removal_keys(rows, *, cutoff, max_records, timestamp)[source]

Select object keys to delete under the two-stage retention/count bound.

Parameters:

  • rows (Sequence[tuple[TypeVar(RecordT), str]]) – (record, object_key) pairs sorted oldest-first. The oldest-first order is what makes the count cap evict the oldest excess rather than an arbitrary slice; an unsorted input silently evicts the wrong records.

  • cutoff (datetime) – Age boundary. A record strictly older than cutoff is selected for removal; a record exactly at cutoff is retained, so the boundary is exclusive.

  • max_records (int) – Maximum number of records to retain after the age cutoff has been applied. When more than max_records survive the cutoff, the oldest excess survivors are selected too.

  • timestamp (Callable[[TypeVar(RecordT)], datetime]) – Projection returning the record’s retention timestamp – created_at for cache and usage records, started_at for run telemetry.

Return type:

list[str]

Returns:

Object keys to delete, age-expired first then count-capped. The two stages cannot overlap, so no key is returned twice.