Module mru 

MRU (frecency) index for picker candidates.

This module is the picker-owned, source-agnostic ranking signal. Sources never opt in or out – the picker derives identity from each candidate’s RoutingPayload via routing_identity and records a frecency entry against (source_id, identity) on every accept. Refilter combines the matcher’s string score with the frecency bonus so recently-used candidates float to the top within a tier – mirroring vertico + prescient’s “most-recent on top” UX that this design is modelled on.

Identity derivation

routing_identity is a pure function of RoutingPayload. Variants with a stable identity (OpenFile { path }, Buffer { id }, InvokeCommand { id }, PasteRegister, ExpandSnippet, JumpToMark) return Some(key); variants whose payload drifts with edits or is per-request (JumpInBuffer, JumpToLocation, LspCompletion, LspCodeAction) return None. The picker silently skips None candidates for both record + lookup – those rows never participate in MRU.

Frecency formula

Recency-dominant, frequency tiebreaker:

decay = 0.5 ^ (age / half_life)
bonus = decay * RECENCY_WEIGHT + ln(use_count + 1) * FREQUENCY_WEIGHT

Numbers (RECENCY_WEIGHT = 100.0, FREQUENCY_WEIGHT = 10.0, DEFAULT_HALF_LIFE = 7 days) are tunable via typed options (slice 14c). The shape is fixed.

Persistence

Slice 14b adds save_to / load_from using bincode. This file holds the in-memory shape only; persistence is a thin wrapper around entries + a schema version byte.

Structs

MruEntry

One MRU record: when the candidate was last accepted and how many times total. Frecency combines both terms.

PickerMruIndex

Picker-owned MRU index. Stored host-side as Arc<RwLock<PickerMruIndex>>; sources never touch it. record mutates; lookup is read-only.

Enums

MruPersistError

Errors from MRU index persistence. The host (slice 14c) decides whether to discard + start fresh, retry, or surface to the user. Default policy: discard on VersionMismatch / Decode; log + retry on Io (write); never block boot.

Constants

DEFAULT_CAP_PER_NAMESPACE

Default LRU cap per (source_id, identity) namespace. Above this, the lowest-frecency entry is evicted on each record call.

DEFAULT_HALF_LIFE

Default half-life for the recency decay term. Tuned to “yesterday’s choices still rank meaningfully; last week’s fade out by half.” picker.mru.recency-half-life overrides.

FREQUENCY_WEIGHT

Frequency contribution weight. ln(use_count + 1) * 10 adds ~10 at use_count=1, ~23 at use_count=10, ~46 at use_count=100 – a slow ramp that keeps frequent items sticky without overwhelming recency.

RECENCY_WEIGHT

Recency contribution ceiling. The decay term 0.5^(age/HL) is in [0, 1]; multiplied by this constant the recency bonus tops out at ~100 for a just-used entry.

Functions

bonus_of

Frecency bonus calculation. Pure function on the entry + reference time + decay half-life. Exposed for benches + the App-side snapshot pass.

default_persist_path

Default path the host’s boot uses for the MRU cache. ~/.config/lattice/cache/picker-mru.bincode (honouring $XDG_CONFIG_HOME), under the config home like every other lattice path. Returns None when no config home resolves (e.g. sandboxed embedded runs); the host treats this as “persistence disabled” and runs MRU in-memory only.

routing_identity

Derive the MRU identity for a routing payload. None means “no stable identity” – the picker correctly skips MRU for these (LSP locations have drifting line/col, LSP code-action / completion indices are per-request).

Type Aliases

MruKey

(source_id, identity) – the index key. Source id namespaces the MRU so opening a file via :picker files and switching to it via :picker buffers count separately. Identity is derived from RoutingPayload.