Module retention 

Task 34 — unified retention (spec §9.7): one sweep across sessions (including compaction parents), memory records, derived memory indexes, traces, and logs, with max-age and disk budgets and headless inspect/export/forget operations.

Invariants:

• CHAIN INTEGRITY: a session that is the head of a named chain is never deleted by any sweep or forget — retention cannot leave a named chain pointing at a deleted session.
• Sessions age by their EMBEDDED updated_at (mtime fallback); memory records age by their embedded timestamps plus per-record retention; traces/logs age by file mtime.
• Memory files are compacted by atomic rewrite (expired + tombstoned records physically removed) rather than whole-file deletion; their derived index directories are dropped alongside (rebuildable state).
• The disk budget deletes oldest-first across whole-file artifacts (sessions/traces/logs/indexes), skipping protected chain heads.

Structs

DomainReport

ExportSummary

RetentionPolicy

Unified policy: maximum artifact age and total disk budget.

RetentionReport

RetentionRoots

Filesystem roots one retention pass operates over. Production callers use RetentionRoots::resolve; tests inject temp roots.

SweepOutcome

Enums

RetentionDomain

Artifact domains under unified retention.

RetentionError

Typed retention failure (CP-13 fix1 I4/M2).

Functions

export

Headless export: copy sessions, memory, traces (recursive), and logs to dest with no symlink surface, no check/use races, and private modes throughout (CP-13 fix2): every destination directory and file is created RELATIVE to held directory handles beneath the trusted export root — a planted or concurrently swapped ancestor symlink fails the export closed instead of being written through. Unix-only; other platforms fail closed.

forget

Headless forget: delete one artifact by domain and id. Session chain heads fail closed; memory ids use "<namespace>:<record-id>" and tombstone through the store.

inspect

Headless inspect: per-domain file counts and byte totals.

sweep

Production sweep at the current clock.

sweep_at

Unified sweep at an explicit clock (tests inject now_ms; production uses sweep). Applies max-age per domain, compacts memory files, then enforces the disk budget oldest-first — never touching chain heads.