Module fep_prefetch 

FEP prefetch (#9): active-inference-style warmup.

The Free-Energy Principle frames cognition as minimizing expected surprise: an agent acts to make the world match its predictions. Applied to context, the cheapest way to avoid the surprise of a missing file is to surface the files most likely to be needed next — before they are asked for.

We estimate that likelihood from the persistent co-access graph (crate::core::cooccurrence, a Hebbian “files read together” memory) and pick the strongest associations that are not already in context. The selection is a deterministic argmax over learned association weight — no sampling — so it respects the determinism contract (#498). Prefetch is a suggestion (warmup hint), never an automatic read, so it can never change a tool’s output body.

Functions

prefetch_candidates

Deterministic expected-info-gain prefetch candidates for path: co-accessed files (by learned association weight, strongest first) that are NOT already loaded in ledger — an already-loaded file offers no information gain. Returns (path, weight) pairs, empty when nothing clears the threshold.

prefetch_hint

Format an FEP prefetch hint for the agent, or None when there is nothing worth warming. Registers activity (crate::core::introspect) only when a real suggestion is produced, so introspect cognition reflects genuine use.