Layer 5 Retention and Rotation

Layer 5 — Retention and Rotation

Automatic version management that prevents unbounded growth of the magazine.

When It Runs

Retention runs automatically as the final step of every successful sv_save() (normal or forced) — never triggered by any other function.

How It Works

FIFO eviction: the oldest entry under that specific registration is deleted once retention_count is exceeded.

• retention_count == 0 means keep-forever, not "delete immediately" (consistent with the zero-default rule — zero is never destructive)
• retention_count == N means keep at most N entries per registration

Orphaned Entries

Orphaned entries (entries whose parent registration was deleted) are outside any registration's cap and are never auto-evicted. They persist until:

• Manually reparented via sv_reparent_entry()
• Explicitly deleted via sv_delete_entry()

Eviction Reporting

Rotation results are folded into sv_save_result_t so callers learn what was evicted without a separate call. The result includes:

• evicted_ids[] — IDs of entries evicted during this save
• evicted_count — number of evicted entries

Design Rationale

• FIFO is the simplest, most predictable policy — no complex LRU/metadata tracking needed
• Running only on save() means retention is predictable and auditable
• The zero-default (keep-forever) ensures the library never deletes data unless explicitly configured to do so

---

See also: Architecture-Overview | Layer-4-Local-Save-and-Pull | API-Reference