Module reference_tracker 

Reference tracker — lightweight side-channel that records when each lifecycle memory record was last retrieved (referenced). Lives outside the append-only ledger as a mutable JSON file at <lifecycle_root>/reference-tracker.json.

Used by the staleness detection subsystem (Phase 4 Round 17) to apply a scoring penalty to memories that haven’t been retrieved in a long time.

Concurrency

Uses fs2::FileExt::lock_exclusive (POSIX flock) to serialize mutations. Same model as distill_queue.rs.

Structs

ReferenceEntry

ReferenceMap

Constants

TRACKER_FILE_NAME

Functions

age_days

Parse last_referenced_at and return days elapsed since then. Returns None if parse fails.

read

Load and parse the tracker file. Returns empty map if file missing or corrupt.

staleness_penalty

Apply the staleness decay curve:

touch

Load tracker, update last_referenced_at to now (UTC ISO 8601) and increment count for each record_id. Creates file if absent. Uses file locking for concurrent safety. Errors are swallowed (eprintln

tracker_path

Resolve the tracker file path under <root>/reference-tracker.json.