docs/index.html: fold BLER mechanism into P6 card; status doc: RLLA root cause

docs/index.html: mirrors README.md (c012148) -- extends P6's card with the
same BLER-vs-target finding (RLLA 0.13x-0.17x, LTSLA on-target at 3 km/h
but 1.57x-2.07x at 30/120 km/h) instead of leaving the bare gain figures
unexplained, using the file's own metric-span + status-doc-link convention.

P6_reaudit_status.md SS9: identifies the specific mechanism behind RLLA's
BLER undershoot (SS8), not just that it's miscalibrated. EpsilonGreedyRLLA's
optimistic init (0.9) is set exactly equal to its own feasibility threshold
(1-target_bler=0.90), so a single NACK on any untried arm drops it just
below the cutoff, permanently blocking greedy re-selection except via rare,
slow epsilon-driven recovery. A throwaway single-seed trace (not committed,
no changes to rl_core.py/runner.py) confirms this empirically: mean
selected MCS converges to ~5.6-5.9 regardless of speed (3 km/h and 30 km/h
land on nearly the same steady state), ruling out a Doppler-tracking
explanation and pointing at the bandit's own estimation dynamics instead.
Design/calibration issue, not a coding bug or deliberate reward shaping;
no fix attempted, per scope.

Author: karrthikmohank

docs/index.html

@@ -362,7 +362,9 @@ <h3>Reinforcement-Learning Link Adaptation</h3>
         <span class="metric">LTSLA −1.60% mean / +10.06% best-config vs OLLA (n=5 seeds, N_TTIS=30000)</span>
         <span class="metric">Not clearly distinguishable from zero overall — favorable only at 3 km/h</span>
         <span class="metric">Thompson sampling · ε-greedy · Bayesian SINR posterior</span>
-        <span class="metric">RLLA −37.40% mean; see docs/redesign/P6_reaudit_status.md</span>
+        <span class="metric">RLLA −37.40% mean — BLER 0.13×–0.17× of the 10% target at every config (OLLA validated at 0.99×–1.01×): massive conservatism, likely an EpsilonGreedyRLLA MCS-selection calibration issue, not a weaker-algorithm story</span>
+        <span class="metric">LTSLA BLER on-target at 3 km/h (genuine efficiency win) but 1.57×–2.07× of target at 30/120 km/h, worsening monotonically with speed — an under-regulated reliability problem there, not just a suboptimal-but-safe MCS choice</span>
+        <span class="metric">Open question, not concluded: the live-Doppler forgetting factor may itself be under-compensating as speed increases — full BLER table & methodology: <a href="https://github.com/karrthikmohank/5g-nr-mac-simulator/blob/main/docs/redesign/P6_reaudit_status.md" target="_blank">status doc §8 ↗</a> (covers only P6's own 6-config × 3-arm grid — no other project's committed data has an equivalent check)</span>
       </div>
     </div>
 

docs/redesign/P6_reaudit_status.md

@@ -776,3 +776,198 @@ It does **not** resolve the equivalent gap for:
 | Test suite result after the change | 235 passed, 0 failed (`pytest tests/`) |
 | HEAD at start of this section | `81c76bb` (this document's own §7 commit) |
 | This section | Drafted 2026-07-18, same session as the diagnostic run |
+
+## 9. RLLA mechanism — why is realized BLER 0.13×–0.17× of target, specifically?
+
+Continues §8 (same commit lineage: `81c76bb`, `5e40240`, `c012148`). §8 established
+*that* RLLA's BLER is far under target; this section identifies *why*, from
+`EpsilonGreedyRLLA`'s code (`projects/p6_rl_link_adapt/rl_core.py`, lines
+178–264, read in full this session) plus a throwaway empirical trace. No
+committed file was modified to reach this conclusion (confirmed: `git diff
+--stat projects/p6_rl_link_adapt/rl_core.py projects/p6_rl_link_adapt/runner.py`
+returns empty at the time of writing).
+
+### 9.1 Part 1 — code reading
+
+**1. Action space / MCS range — ruled out as a cause.** `_MCS_INDICES =
+sorted(NRConstants.MCS_TABLE.keys())` (`rl_core.py` line 61) — confirmed via
+`nr_simulator/constants.py` line 111 (`N_MCS = len(MCS_TABLE)   # 29  (0..28)`)
+this is the full 0–28 range. `EpsilonGreedyRLLA.select_mcs` draws
+exploration arms from `_MCS_INDICES` directly (line 232: `self._rng.choice
+(_MCS_INDICES)`) and scans the same set for the greedy choice (line 240:
+`for mcs in _MCS_INDICES`) — identical to the shared `_MCS_INDICES` global
+that `ThompsonSamplingLA`/`_best_mcs_for_sinr` (LTSLA) also uses (`rl_core.py`
+line 71). `BanditLAController.select_mcs`'s `np.clip(mcs, 0,
+NRConstants.N_MCS - 1)` (line 451) is a no-op defensive clip, not a range
+restriction. **No off-by-one or truncated range** — RLLA can structurally
+reach every MCS OLLA/LTSLA can.
+
+**2. Initial value estimates — optimistic, but exactly at the feasibility
+cutoff.** Line 219: `self._p_success: Dict[int, float] = {m: 0.9 for m in
+_MCS_INDICES}` — every arm (MCS 0 through 28 alike) starts at the *same*
+optimistic estimate, 0.9, with the comment (line 218) confirming intent:
+"Optimistic init: assume each arm succeeds, encourages exploration." The
+critical detail: `target_bler` defaults to `NRConstants.TARGET_BLER` = 0.10
+(`constants.py` line 128), so the feasibility test in `select_mcs` (line
+242: `if p >= (1.0 - self.target_bler)`) requires `p >= 0.90` — **exactly
+equal to the optimistic initial value**, not comfortably above it.
+
+**3. Exploration schedule.** `epsilon=0.10`, `epsilon_decay=0.9995`,
+`epsilon_min=0.01` (lines 205–207), decayed once per `update()` call (line
+259: `self.epsilon = max(self.epsilon_min, self.epsilon * self.epsilon_decay)`).
+Solving `0.10 × 0.9995^N = 0.01` gives `N ≈ 4603` updates — at roughly one
+scheduled update per TTI per UE, epsilon reaches its floor well inside the
+first ~15% of a 30000-TTI run, then stays at the 1% floor (not zero) for
+the remainder. Exploration never fully stops, but becomes rare early on.
+
+**4. Reward/update rule — plain unweighted running average, no explicit
+asymmetric penalty.** `update()` (lines 253–259): `target = 1.0 if is_ack
+else 0.0; self._p_success[mcs] += self.lr * (target - self._p_success[mcs])`
+(`lr=0.05`, line 208). This is a plain exponential running average of the
+raw ACK/NACK bit — **not** throughput-weighted, and there is no explicit
+NACK-penalty coefficient anywhere in this update. Any apparent asymmetry
+between "cost of a NACK" and "benefit of a higher MCS" is not written into
+the reward function directly — it would have to emerge from the interaction
+of items 2+3 with the hard threshold in `select_mcs`, not from a deliberate
+reward-shaping choice. This distinguishes the finding from "RLLA's authors
+chose a conservative reward on purpose" — nothing in the code sets out to
+do that.
+
+**Most likely explanation from code alone, before the empirical check:**
+items 2+3 together create a specific, quantifiable failure mode. Starting
+at `p=0.9` and drawing one NACK gives `p = 0.9 + 0.05×(0 − 0.9) = 0.855`
+— **below the 0.90 cutoff after exactly one failure**, regardless of an
+arm's true long-run success rate. Once below 0.90, the greedy branch (lines
+236–247) can never re-select that arm (it only iterates `p >= 0.90`
+arms) — the *only* path back is an epsilon-triggered uniform draw over all
+29 arms (line 232, not weighted toward near-threshold arms), each such
+event nudging `p` by only `lr × (target − p)`, i.e. slow, and needing
+several consecutive lucky successes to climb back above 0.90 from 0.855.
+This reads as a **calibration issue** in how three otherwise-reasonable
+choices interact (optimistic init exactly at the threshold, a hard
+pass/fail cutoff, slow+rare recovery) rather than a coding bug (no
+incorrect logic) or a deliberate reward-shaping choice (no throughput/
+penalty weighting exists to shape). Confirming this requires seeing actual
+selection behavior over time — code reading alone can't distinguish "gets
+stuck at an early unlucky estimate and never recovers" from "explores fine
+but something else makes low MCS genuinely optimal" — hence Part 2.
+
+### 9.2 Part 2 — empirical trace
+
+**Method.** A throwaway script (not committed; scratchpad only) instantiated
+`BanditLAController(method="epsilon_greedy", ...)` and drove it through the
+same `_run_rl`-style loop (`CellLayout` → `ProportionalFairScheduler` →
+`ctrl.select_mcs`/`ctrl.update`), recording every returned `mcs` in call
+order (aggregated across all UEs — an initial attempt to track a single
+UE's trajectory found that UE 0 was scheduled rarely under this seed/PF
+combination, so tracking switched to all scheduled events instead, which
+also better matches "does the bandit population as a whole ever try/
+abandon higher MCS"). Bucketed into 1000-event windows. Two configs, one
+seed (42): 3 km/h/CDL-A (favorable, §7/§8) and 30 km/h/CDL-A (unfavorable).
+No `rl_core.py`/`runner.py` code was touched — only the existing public
+`select_mcs`/`update` API was called from the external script.
+
+**Result — both configs, essentially identical pattern:**
+
+| Config | Mean MCS, first 1000 events | Mean MCS, last 1000 events | Realized BLER (this single-seed run) |
+|---|---|---|---|
+| 3 km/h, CDL-A | 10.74 | 5.63 | 0.0178 |
+| 30 km/h, CDL-A | 9.89 | 5.73 | 0.0194 |
+
+(Single-seed values here differ slightly from §8's 5-seed means — 0.0143
+at 3 km/h-A, 0.0159 at 30 km/h-A — as expected for one seed vs. a 5-seed
+average; same order of magnitude, same conclusion.)
+
+- Both configs start with a mean selected MCS around 10–11 (consistent with
+  the optimistic-init greedy branch initially favoring high-spec-eff,
+  as-yet-untried arms) and decline over the run to a **steady state around
+  5.6–5.9 — nearly identical between 3 km/h and 30 km/h**, not a
+  monotonic straight-line drop: the 3 km/h trace shows a partial rebound
+  around events 6000–10000 (mean rising back to ~8.5) before settling down
+  again by the end. This is consistent with a stochastic
+  equilibrium-seeking process (arms near the 0.90 cutoff randomly crossing
+  above and below it), not a one-shot collapse.
+- **MCS 28 (the ceiling) is drawn in nearly every 1000-event bucket, all
+  the way to the final bucket of the run, in both configs** — the bandit
+  never permanently loses access to the top of the range; the epsilon
+  floor (1%, uniform over 29 arms, ≈0.03% per event) keeps sampling it
+  throughout, exactly as item 3 predicts. This is why "highest MCS ever
+  tried" and "max in final 1000 events" are both 28 in every trace — a
+  low-rate noise artifact of `min`/`max`, not evidence the ceiling is
+  reachable *and stable*: the **mean** is the signal that matters, and it
+  settles low regardless.
+- **The key discriminating result: 3 km/h and 30 km/h converge to nearly
+  the same final mean MCS (5.63 vs. 5.73)**, despite very different fading
+  dynamics between the two configs. If the mechanism were Doppler/speed-
+  tracking-related (the way LTSLA's §8 finding is), the two configs would
+  be expected to diverge, not converge to nearly the same value. They
+  don't — this is direct evidence against a speed-dependent explanation
+  and points at something intrinsic to the bandit's own estimation
+  dynamics, common to both configs.
+
+### 9.3 Part 3 — conclusion
+
+**The evidence (code + empirical trace) converges on a single, specific
+mechanism, not an unresolved choice between candidates:**
+
+`EpsilonGreedyRLLA`'s optimistic initial value (0.9) is set **exactly
+equal to** its own feasibility threshold (`1 − target_bler` = 0.90, since
+`target_bler` defaults to the same 10% used everywhere else in this
+project). Because of this exact equality, a single NACK on any untried arm
+— including an arm whose *true* long-run success rate is close to the
+target's own 90% — immediately drops that arm's estimate to 0.855, below
+the cutoff, disqualifying it from ever being greedily re-selected until a
+rare (≈0.03%-per-event, uniform-over-29-arms) exploration event re-tries
+it, which then needs *sustained* luck (several consecutive successes
+against the slow `lr=0.05` running average) to climb back above 0.90.
+Arms whose true success rate sits *near* 90% are the least likely to
+survive this process, because they fail roughly 1 time in 10 by
+definition — almost exactly as often as it takes to trigger the
+disqualification — while arms with a true success rate *safely above* 90%
+(i.e., meaningfully more conservative than the 10% BLER target) are the
+only ones stable enough to survive an initial unlucky run and remain the
+long-run greedy choice. This produces a systematic downward bias toward
+BLER well under target, **independent of channel speed** — confirmed
+empirically by the near-identical steady-state mean MCS at 3 km/h and
+30 km/h (§9.2), which specifically rules out a Doppler/speed-tracking
+explanation (the mechanism behind LTSLA's §8 finding) as the cause here.
+
+This is a **design/calibration issue**, not a coding bug (no incorrect
+logic, no off-by-one, confirmed in §9.1 item 1) and not a deliberate
+reward-shaping choice (the update rule is an unweighted ACK/NACK running
+average with no asymmetric penalty term, confirmed in §9.1 item 4) —
+specifically, the calibration issue is the coincidence of the optimistic
+initial value and the feasibility threshold being set to the *same*
+number, combined with a hard binary cutoff and a slow, rare recovery path.
+
+**What this does not establish**: this conclusion rests on code analysis
+plus a single-seed, two-config empirical trace (per this task's own scope
+— not a fresh 5-seed/6-config campaign). The qualitative mechanism (the
+arithmetic of `p0=0.9`, `threshold=0.90`, `lr=0.05` interacting with a hard
+cutoff) does not depend on seed or config, so there is no specific reason
+to expect other seeds/configs to tell a different story — but this was not
+verified beyond the two configs and one seed traced here. No fix was
+attempted or evaluated (out of scope per the task's own STOP condition);
+this section identifies the mechanism, it does not remediate it.
+
+### 9.4 Recommendation for a follow-up task (not done here)
+
+`README.md` and `docs/index.html` (commits `c012148` and the prior,
+still-uncommitted `docs/index.html` edit) currently describe this as
+"likely a design/calibration issue in `EpsilonGreedyRLLA`'s MCS selection"
+— deliberately unspecific at the time. Given §9.3's conclusion is now
+specific and code-cited, a follow-up documentation task could tighten that
+wording to name the actual mechanism (optimistic-init-equals-threshold
+plus hard-cutoff-with-slow-recovery). Not done as part of this task, which
+was scoped to identification only, and per the task's own instruction not
+to edit `README.md`/`docs/index.html` here.
+
+### 9.5 Provenance for this section
+
+| Artifact | Location |
+|---|---|
+| Code read this session | `projects/p6_rl_link_adapt/rl_core.py` lines 61, 71, 178–264, 451; `nr_simulator/constants.py` lines 111, 128 |
+| Empirical trace script | Throwaway, scratchpad-only, not committed — calls only `BanditLAController`'s existing public API |
+| Confirmation no algorithm file was left modified | `git diff --stat projects/p6_rl_link_adapt/rl_core.py projects/p6_rl_link_adapt/runner.py` → empty, this session |
+| HEAD at start of this section | `81c76bb` / `5e40240` / `c012148` (no new commits from this section's own work — documentation-only append) |
+| This section | Drafted 2026-07-18, same session as the code review and trace |