Module retention 

Grandfather-father-son (GFS) retention selection (ADR §4.4).

BackupConfig.spec.retention is the only successful-retention driver (SKILL “Retention is GFS-only”). The operator periodically runs this selection over the Backup CRs for one (identity, source) tuple and deletes the CRs that fall outside the kept set; each deleted CR’s deletionPolicy then governs the snapshot (§4.5). This module is the pure selection kernel — no kube types, no clock — so it’s unit-testable with lightweight fakes.

Algorithm (ADR-0001 §4.4, steps 2–4)

1. Sort candidates by end time, newest first.
2. Apply buckets in order: keepLatest, keepHourly, keepDaily, keepWeekly, keepMonthly, keepAnnual.
   • keepLatest: N keeps the N newest backups outright.
   • Each time bucket keeps the most recent backup within each distinct period (hour / day / ISO-week / month / year), up to its count N, walking newest→oldest.
3. A backup kept by any bucket survives (union). Everything else is deleted.

This is deliberately not a flat count: a backup that is the newest of its year is held by keepAnnual even if hundreds of newer dailies exist — the exact case a flat cap would silently drop (ADR §4.4 “Why not flat-count”).

Empty-policy semantics

An all-None Retention selects no buckets, so the kept set is empty and every backup is marked for deletion. The caller (controller) is responsible for only invoking GFS when a retention policy is actually configured; this function reports faithfully what the given policy implies. This is documented and tested.

Structs

KeptSet

The outcome of a GFS selection: which ids to keep and which to delete. Both are returned explicitly so callers never have to recompute the complement.

Traits

BackupLike

Anything that can stand in for a Backup during retention selection. Kept tiny so tests use trivial fakes instead of constructing full Backup CRs.

Functions

select_kept

Select the GFS-kept set from backups under policy (ADR §4.4).