Module retention 

Retention: what bounds the three stores that grow, and what it costs to bound them.

Three stores, two operations, because they are different shapes:

• A session directory — <workdir>/.murmur/<ses_…>/ — is an independent unit. Nothing references it and nothing spans two of them, so it is pruned by being deleted whole, taking its trace.jsonl and its blobs/ with it.
• A formation directory — ~/.murmur/formations/<frm_…>/ — holds one ended formation’s peer directories, and with them every peer’s sessions. It is the other half of the evidence whose first half is the entry member’s session in the project, so it is pruned whole, by the entry member’s trace.retain, and only by the launcher of a later formation from the same project once every member of that later one is reaped.
• A conversation record — ~/.murmur/conversations/<record>/<ctx>/conversation.jsonl — is one unit that grows. Deleting it destroys the conversation an operator wanted kept, so it is pruned by truncating its front: the oldest messages go, the recent ones stay, and every surviving message keeps the id it has always had.

Three properties hold across everything below:

• No defaults. Every entry point takes the policy it enforces. An absent policy is an absent call: nothing here has a fallback that deletes.
• No clock of its own. Every prune function takes now_ms, so age is a fixture’s to supply and a test never sleeps.
• No trace of its own. Every prune function returns what it removed and writes nothing; the caller holds the [crate::trace::TraceWriter] and records the deletion against the session that performed it, or reports it as the launcher that performed it.

Session and formation age is read out of the ses_ or frm_ id — a uuid v7 whose first 12 hex characters are a millisecond timestamp — so both policies are computed from one directory listing with no stat. Record age is the mtime of conversation.jsonl, because a context id is not necessarily a uuid and “untouched since” is the useful question for a record that spans weeks.

Structs

ContextContents

What one context directory holds, read the way the runtime reads it.

ContextDir

One context directory of the record store: a directory under a record store holding conversation.jsonl, harness-session.json, or both.

HarnessSessionEntry

One context’s harness session, as the file holds it.

MessageLocation

One record a message id was looked for in, and what that record had to say about it.

PrunedFormation

A formation directory that was removed, and why.

PrunedRecord

A context directory that was removed, and why.

PrunedSession

A session directory that was removed, and why.

RecordHeader

The first line of a record: a JSON object with a type key and no role.

RecordSummary

One context’s record, as mur conversation ls reports it.

RemovedRecord

A context directory mur conversation rm removed.

TruncationMarker

What one record has already dropped from its front.

TruncationOutcome

What one truncation dropped and what it left.

Enums

MessageStatus

Where one message id turned up, and in what state.

Functions

conversations_root

~/.murmur/conversations, resolved and not created.

find_context_dirs

Every context directory named context_id, in every record store, ordered by record store.

list_records

Every conversation record on this host, record store by record store.

locate_message

Every record that has something to say about message_id.

now_ms

Milliseconds since the epoch, for the callers that have no fixture to take a clock from.

prune_formations

Remove the formation directories under formations_dir that belong to project_dir and that policy — the entry member’s trace.retain — does not keep.

prune_records

Remove the context directories under record_root that policy.max_age_secs does not keep.

prune_sessions

Remove the sessions of one records group that policy does not keep: each pruned session’s records directory in records_group and, when created_workdirs is given ([created_workdirs]), the work folder of the same name the runtime created there, so a session goes whole.

read_context_dir

What the context directory dir holds: the header and messages of its conversation.jsonl and its harness session.

remove_record

Remove one context directory whole, and report what it held.

session_id_timestamp_ms

The millisecond timestamp inside a ses_ id, or None when the name is not one.

truncate_record

Drop everything before the newest keep messages of path, atomically.