Operations

Maintenance the runtime never does on its own. The retold CLI is a thin front over this class; the low-level design lists every command.

retold.operations

Trusted operator maintenance: expiry, transcript retention, erasure, re-embedding, and snapshots.

These are administrative operations over one store. None of them is reachable from a model-facing tool. Erasure is the one irreversible operation and it is complete by construction: it walks every table that can hold a user's text, replaces the text with tombstone markers that keep ids, kinds, and timestamps, and then compacts the database file so freed pages carry no residue.

OperationRefused

Bases: RuntimeError

The operation would be unsafe or meaningless as requested; nothing was changed.

Operations

Every method appends the events that make the change auditable.

expire

expire() -> list[str]

Mark every active record past its expiry as expired, one event each; retrieval already ignored them.

retain

retain() -> list[str]

Blank the transcripts of extracted sessions older than sessions.retain_days; never an unextracted one.

erase_record

erase_record(
    record_id: str, *, reason: str
) -> ErasureReport

Erase one record's durable content; the tombstone row, its id, and its audit trail remain.

erase_session

erase_session(
    session_id: str, *, reason: str
) -> ErasureReport

Blank one transcript, keep the turn rows so source references still resolve to a tombstone.

erase_user

erase_user(user_id: str, *, reason: str) -> ErasureReport

Remove every place a user's text can reach: transcripts, records, evidence, indexes, logs, events, aliases.

Covered, in this order: every session for the user; every record in the user scope and in every private agent:<agent>/<user> scope; the content and evidence of any record in any scope whose source reference points at one of those sessions; the user's search logs and turn decisions; the payload of every event about an erased record, entity, or session; and the entities and aliases in the user's scopes. Rows, ids, kinds, and timestamps remain as tombstones.

reembed

reembed(embedder: Embedder) -> int

Re-embed every record with embedder and drop the old vectors; refused until floors were recalibrated.

The gate floors are calibrated per embedding model. If the latest logged search ran under a different embedding version with the same dense floors this configuration still carries, nobody has recalibrated, and re-embedding would silently move every score under floors chosen for another model.

snapshot_load

snapshot_load(
    path: str | Path, store_path: str | Path
) -> Path

Replace the store file with a snapshot. The caller must have closed every connection first.