yvgude--lean-ctx/docs/premium-cache-heatmap.md

Premium Fix Plan: ctx_read Cache Correctness + Observatory File Heatmap (#166)

Ziel: Beide Bugs so fixen, dass sie nicht mehr LLM-Trial-and-Error provozieren, sondern sich korrekt und selbsterklaerend verhalten.

Premium-Kriterien (DoD)

• Cache correctness: Kein stale File-Content aus RAM-Cache, wenn Datei auf Disk neuer ist.
• No confusing stubs: Bei prompt-stale bekommt das Modell wieder echten Inhalt (statt „already in context“).
• Heatmap never blank: File Heatmap zeigt Aktivitaet oder einen Empty-State Text.
• Backwards-compatible: JSONL Events bleiben parsebar (keine harte Migration).
• Tested: Regression-Tests fuer beide Bugs.

---

A) ctx_read Cache Staleness (Greatness7)

A1) mtime im Cache speichern

Datei: rust/src/core/cache.rs

• CacheEntry erhaelt stored_mtime: Option<SystemTime>
• store() setzt stored_mtime via fs::metadata(path).modified()
• Helper is_stale(path, entry) -> bool vergleicht stored_mtime mit aktuellem mtime

A2) mtime-Validierung vor Cache-Use (alle non-full Modes)

Datei: rust/src/tools/ctx_read.rs (handle_with_options_resolved)

• Bevor existing.content fuer non-full zurueckgegeben wird: mtime validieren
• Wenn stale: cache.invalidate(path) und von Disk lesen (wie „first read“ Pfad)

A3) prompt-stale => fresh=true fuer full

Datei: rust/src/server/dispatch/read_tools.rs

Hintergrund: full kann bei Cache-Hit eine Stub-Antwort liefern (spart Tokens), ist aber genau dann verwirrend, wenn der Prompt-Cache stale ist und das Modell den Inhalt wieder braucht.

• Wenn stale == true und effective_mode == "full" und User nicht explizit fresh=true gesetzt hat: intern fresh=true erzwingen

A4) start_line impliziert fresh=true

Datei: rust/src/server/dispatch/read_tools.rs

• Wenn start_line gesetzt ist: fresh=true erzwingen (high-precision Snippet => niemals stale)
• Optional: gleiches fuer explizites mode Prefix lines:

A5) Docs/Tool Schema korrigieren

• rust/src/instructions.rs: Cache-Busting Guidance korrekt (mtime auto-validate, fresh=true als Force)
• rust/src/tool_defs/granular.rs: start_line Beschreibung an reales Verhalten anpassen

---

B) Observatory TUI: File Heatmap bleibt leer (GitHub #166)

B1) ToolCall Events muessen path enthalten (Root Cause Fix)

Root cause: emit_tool_call(..., None) in rust/src/tools/mod.rs, waehrend die TUI Heatmap nur ToolCall{path:Some} (oder CacheHit) aggregiert.

Premium-Ansatz (minimal-invasiv, kein globaler Refactor): In den Dispatchern, wo path sowieso existiert, zusaetzlich emit_tool_call(..., Some(path)) emittieren.

Konkrete Stellen (haben alle bereits eine path Variable):

• rust/src/server/dispatch/read_tools.rs: ctx_read, ctx_multi_read, ctx_smart_read, ctx_delta, ctx_edit
• rust/src/server/dispatch/utility_tools.rs: ctx_tree, ctx_outline, ctx_symbol, ctx_analyze

Hinweis: ctx_multi_read emittiert aktuell (noch) keinen per-file path im ToolCall-Event, weil das eine saubere Aufteilung der Token-Savings pro Datei erfordert. Fuer Issue #166 war entscheidend, dass ctx_read/ctx_edit etc. path liefern.

B2) EventTail nutzt lean_ctx_data_dir()

Datei: rust/src/tui/event_reader.rs

• Hardcoded ~/.lean-ctx/events.jsonl ersetzen durch lean_ctx_data_dir()?.join("events.jsonl")
• Fallback nur wenn lean_ctx_data_dir() nicht aufloesbar ist

B3) Compression-Events zaehlen als File-Aktivitaet (ohne Fake Token-Rechnung)

Datei: rust/src/tui/app.rs (ingest)

• EventKind::Compression { path, .. } => access_count += 1
• tokens_saved nicht aus Line-Deltas ableiten (waere irrefuehrend)

B4) Empty-State Text statt „blank“

Datei: rust/src/tui/app.rs (draw_heatmap)

• Wenn state.files.is_empty(): Paragraph("Waiting for file activity...") rendern

---

C) Tests

C1) Cache Tests

• Aenderung auf Disk => non-full liefert neuen Inhalt (nicht stale)
• prompt-stale full => liefert Inhalt/delta statt Stub
• start_line => liefert Disk-aktuellen Slice

C2) Heatmap Tests

• ingest(ToolCall{path:Some}) befuellt Heatmap
• ingest(Compression{path}) erhoeht access_count
• Empty-State wird gerendert wenn keine Files

---

GitLab Ticket-Schnitt (Parent + Subtickets)

• Parent: Premium: Cache correctness + Observatory File Heatmap (referenziert GitHub #166)
• Subtickets: cache-mtime, cache-validate, prompt-stale-fresh, start-line-fresh, heatmap-path, heatmap-eventtail, heatmap-compression, heatmap-placeholder, fix-docs, tests