Module retention 

Time-Machine-style retention thinning for Tier-2 version history.

Named versions (those with a label) and the latest version are kept forever; all other versions are thinned by age into coarser buckets the older they get (all recent, then hourly, daily, weekly). Thinning rewrites versions.jsonl and re-links each kept version’s parent to the previous kept version so that @head~N walks remain valid. Object GC and storage caps are separate passes.

Structs

CapReport

Outcome of an apply_caps pass.

MaintainReport

Combined outcome of a maintain pass.

RetentionPolicy

Controls the age windows used by thin_versions to decide which versions survive thinning.

ThinReport

Outcome of an apply_thinning pass.

Functions

apply_caps

Enforce the per-doc count and size caps: drop the OLDEST unnamed, non-latest versions until at most max_versions remain AND the total compressed size of objects referenced by retained versions is at most max_object_bytes. Named versions and the latest version are never dropped. Rewrites versions.jsonl (re-linking parents). Orphaned objects are reclaimed by a later gc pass.

apply_thinning

Apply policy to doc_id’s versions: drop thinned-out versions and rewrite versions.jsonl, re-linking each kept version’s parent to the previous kept version.

maintain

Full durable-retention pass for doc_id: thin by age, enforce caps, then garbage-collect now-unreferenced objects. The single entry point a host calls periodically (e.g. on close or on a timer).

thin_versions

Return the set of version ids to KEEP under policy given the current time.