Amplituhedron Liquid Memory

Module: src/amplituhedron.rs
Companion to: AMPLITUHEDRON_PLAN.md, FORMAL_LEDGER.md § Categorical Geometric Langlands
Lean covenant: Gnosis/LiquidMemoryTopology.lean — liquid_memory_conservation

What Changed and Why

The AmplituhedronCache previously evicted the coldest entry (pure LRU). This is thermodynamically wrong.

A frozen KV volume is not equivalent to an arbitrary file in a page cache. Its value is the prefill computation it eliminates — proportional to how much of the Grassmannian it covers (prefix length) and how many sessions have already validated it (replay hit count). LRU ignores both. A 512-token system-prompt volume that goes quiet for one session is not cheaper to recompute than a 16-token stub that was touched yesterday.

The fix: evict by information density, not recency.

The Density Formula

density(v) = v.prefix_len × (v.hit_count + 1)

• prefix_len — tokens covered. Proportional to the Grassmannian volume encoded: a longer prefix spans more cells in Gr(k,n), costs more to recompute on a miss, and should be the last to go.
• hit_count + 1 — replays accumulated. The +1 floor prevents a never-replayed entry from having zero density, so a long cold entry still beats a short cold entry. Each replay is a proof of value: another session confirmed this volume is on the O(1) Amplituhedron trajectory.
• On a density tie, LRU (last_used) breaks it — recency is the final word among entries of equal information content.

God Formula Connection

From LiquidMemoryTopology.lean:

def memHeld (capacity ventRate : Nat) : Nat :=
  capacity - Nat.min ventRate capacity + 1

theorem liquid_memory_conservation (R v : Nat) :
    memHeld R v + memVent R v = R + 2

The AmplituhedronCache is a single-node liquid memory system:

When entries.len() == max_volumes the cache is at its ceiling (memHeld R 0 = R + 1). Every capture() that triggers eviction is one vent step: the lowest-density entry is released as Landauer heat, making room for the incoming volume.

Static LRU holds everything until the ceiling and then discards blindly. Liquid eviction holds structurally dense volumes preferentially — the cache breathes.

New API Surface

memory_pressure() → u64

Percentage [0, 100] of max_volumes currently occupied.

let pct = cache.memory_pressure();  // 75 → 75 % full

Use this to decide whether to route the session to a less-loaded worker before calling capture(). At 100 the next capture will evict; at 0 there is free headroom.

heat_released() → u64

Cumulative density discarded by eviction since the cache was created (or last cleared). Density unit = prefix_len × (hit_count + 1).

let (hits, misses, evictions) = cache.stats();
let heat = cache.heat_released();

A rising heat_released with a stable hits / (hits + misses) ratio means the cache is under sustained pressure but serving well — volumes are cycling without degrading hit rate. A rising heat_released with a falling hit rate signals the cache is too small: raise max_volumes or reduce the prefix diversity hitting this station.

Eviction Walk-Through

Before (LRU):

entries: [A(last=10), B(last=5), C(last=8)]
evict → B (coldest tick)

After (liquid density):

entries:
  A: prefix_len=512, hit_count=10  → density = 512 × 11 = 5632
  B: prefix_len=16,  hit_count=0   → density =  16 ×  1 =   16
  C: prefix_len=64,  hit_count=3   → density =  64 ×  4 =  256
evict → B (lowest density, regardless of last_used)
heat_released += 16

Entry B encodes a tiny, cold volume. Its eviction costs almost nothing to recompute. Entry A encodes the bulk of a long system prompt that twelve sessions have already proven they need. It stays.

Lean Covenants Discharged

Tests

All 29 existing amplituhedron* lib tests pass unchanged. The existing lru_evicts_coldest test still passes because at hit_count=0 for all entries the density tiebreak falls through to last_used, recovering pure LRU behavior for cold caches.