Module retention 

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

SnapshotPolicy.spec.retention is the only successful-retention driver (SKILL “Retention is GFS-only”). The operator periodically runs this selection over the Snapshot 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.

SnapshotRetentionView

A minimal view of a Snapshot for retention selection: its CR name (the id used in delete decisions) and its snapshot end time (the GFS bucketing key).

Traits

SnapshotLike

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

Functions

retention_buckets

Pure. The GFS population of backups, bucketed exactly as a prune would bucket it.

retention_group_key

Pure. The retention bucket a Snapshot belongs to.

retention_view

Build a retention view from a Snapshot CR, using status.timing.endTime (falling back to the CR creation timestamp). Returns None if the backup is not in a terminal successful state — only successful snapshots participate in GFS (failures are bounded separately by failedJobsHistoryLimit).

select_kept

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