SilverSight/formal/SilverSight/CacheSieve.lean

/-
  CacheSieve.lean — L0 Local Sorter Cache Admission Control

  Static cache filtering: decides which cache lines to admit based on
  a 4-state machine. Pairs with HCMR for the complete cache performance
  model (admission + contention).

  Clean rewrite for SilverSight — not a port from Research Stack.
  Based on the chiral CRT multiplexing framework.

  States:
  - Stable:  line is cached, low access frequency, keep
  - Rising:  line is being promoted (frequency increasing)
  - Unstable: line is hot but contended (may thrash)
  - Reset:   line evicted, must re-fetch

  Admission policy:
  - Stable → Rising on access
  - Rising → Unstable if contention detected (HCMR self-loop high)
  - Unstable → Reset if contention persists (COUCH gate fails)
  - Reset → Rising on re-access (re-admission)

  Connection to CRT multiplexer:
  - CacheSieve decides WHICH channels to admit (admission control)
  - HCMR models CONTENTION on admitted channels (throughput)
  - Together: complete cache performance model
-/

import Mathlib.Data.Real.Basic
import Mathlib.Tactic

namespace SilverSight.CacheSieve

/-- Sieve state: the 4-state machine for cache admission. -/
inductive SieveState where
  | stable   : SieveState   -- cached, low frequency, keep
  | rising   : SieveState   -- being promoted (frequency increasing)
  | unstable : SieveState   -- hot but contended (may thrash)
  | reset    : SieveState   -- evicted, must re-fetch
  deriving Repr, DecidableEq

/-- Cache line with sieve state and access count. -/
structure CacheLine where
  addr       : ℕ            -- cache line address
  state      : SieveState
  accessCount : ℕ           -- number of accesses since admission
  deriving Repr

/-- The sieve: a collection of cache lines with a capacity. -/
structure CacheSieve where
  lines     : List CacheLine
  capacity  : ℕ             -- max lines the cache can hold
  deriving Repr

/-- Access outcome: did the access hit, miss, or promote/demote? -/
inductive AccessResult where
  | hit      : AccessResult   -- line was stable/rising, access succeeded
  | miss     : AccessResult   -- line was reset/absent, must fetch
  | promote  : AccessResult   -- line promoted (stable→rising or reset→rising)
  | demote   : AccessResult   -- line demoted (rising→unstable or unstable→reset)
  deriving Repr

/-- Contention level from HCMR (self-loop probability as Q16_16 raw). -/
-- 0 = no contention, 65536 = fully contended
def ContentionThreshold : ℕ := 49152  -- 0.75 × 65536 — high contention cutoff

/-- Transition: given current state, access count, and contention, what's next?

    - Stable + access → Rising (promote)
    - Rising + low contention → Rising (stay, accumulating heat)
    - Rising + high contention → Unstable (demote)
    - Unstable + high contention → Reset (evict)
    - Unstable + low contention → Rising (recover)
    - Reset + access → Rising (re-admit)
-/
def sieveTransition (s : SieveState) (accessCount : ℕ) (contention : ℕ) : SieveState × AccessResult :=
  match s with
  | .stable =>
    (.rising, .promote)
  | .rising =>
    if contention ≥ ContentionThreshold then
      (.unstable, .demote)
    else
      (.rising, .hit)
  | .unstable =>
    if contention ≥ ContentionThreshold then
      (.reset, .demote)
    else
      (.rising, .promote)
  | .reset =>
    (.rising, .promote)

/-- Check if a cache line should be admitted (admission control).

    A line is admitted if:
    - There's capacity available, OR
    - An existing line can be evicted (in Reset state) -/
def shouldAdmit (sieve : CacheSieve) (addr : ℕ) : Bool :=
  let existing := sieve.lines.filter (fun l => l.addr == addr)
  if !existing.isEmpty then
    -- Line exists: check if it's in Reset (re-admit) or Stable/Rising (keep)
    match existing.head!.state with
    | .reset => true
    | _ => true  -- already admitted
  else
    -- New line: admit if capacity available or can evict
    let activeLines := sieve.lines.filter (fun l => l.state ≠ .reset)
    activeLines.length < sieve.capacity

/-- Evict a line to make room (victim selection: oldest Unstable or Reset). -/
def evictVictim (sieve : CacheSieve) : Option ℕ :=
  -- Prefer evicting Reset lines, then Unstable
  let resetLines := sieve.lines.filterMap (fun l =>
    if l.state == .reset then some l.addr else none)
  match resetLines.head? with
  | some addr => some addr
  | none =>
    let unstableLines := sieve.lines.filterMap (fun l =>
      if l.state == .unstable then some l.addr else none)
    unstableLines.head?

-- ── Theorems ──────────────────────────────────────────────────────────

/-- A stable line with an access transitions to Rising (promotion). -/
theorem stable_access_promotes :
    sieveTransition .stable 0 0 = (.rising, .promote) := rfl

/-- A rising line with low contention stays Rising (hit). -/
theorem rising_low_contention_hits :
    sieveTransition .rising 5 0 = (.rising, .hit) := by
  simp [sieveTransition, ContentionThreshold]
  omega

/-- A rising line with high contention transitions to Unstable (demote). -/
theorem rising_high_contention_demotes :
    sieveTransition .rising 5 65536 = (.unstable, .demote) := by
  simp [sieveTransition, ContentionThreshold]
  omega

/-- An unstable line with persistent contention transitions to Reset (evict). -/
theorem unstable_high_contention_resets :
    sieveTransition .unstable 10 65536 = (.reset, .demote) := by
  simp [sieveTransition, ContentionThreshold]
  omega

/-- A reset line with re-access transitions to Rising (re-admission). -/
theorem reset_access_readmits :
    sieveTransition .reset 0 0 = (.rising, .promote) := rfl

/-- Admission control: line is admitted when capacity is available. -/
theorem admit_when_capacity (sieve : CacheSieve)
    (hcap : (sieve.lines.filter (fun l => l.state ≠ .reset)).length < sieve.capacity)
    (addr : ℕ) (hnew : ∀ l ∈ sieve.lines, l.addr ≠ addr) :
    shouldAdmit sieve addr = true := by
  simp [shouldAdmit]
  intro h
  exfalso
  apply hnew
  exact (List.filter_mem_cons h).head
  simp at h

/-- Eviction prefers Reset lines over Unstable. -/
theorem evict_prefers_reset (sieve : CacheSieve)
    (hreset : ∃ l ∈ sieve.lines, l.state == .reset) :
    evictVictim sieve = some hreset.choose := by
  simp [evictVictim]
  -- The first Reset line in the list is chosen
  sorry

/-- COUCH gate connection: unstable→reset transition is the COUCH filter.

    When contention exceeds threshold (COUCH fails), the sieve evicts
    the line. This is the cache-level implementation of the COUCH gate
    from GCCL.lean. -/
theorem couch_evicts_on_contention :
    ∀ (accessCount : ℕ),
      sieveTransition .unstable accessCount 65536 = (.reset, .demote) := by
  intro accessCount
  simp [sieveTransition, ContentionThreshold]
  omega

end SilverSight.CacheSieve