1 files changed, 122 insertions, 0 deletions
diff --git a/debug/risc-v-gsp-rm-vm/docs/41-STABILITY-AND-TIME-TO-VALUE.md b/debug/risc-v-gsp-rm-vm/docs/41-STABILITY-AND-TIME-TO-VALUE.md
new file mode 100644
index 0000000..77e1298
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/docs/41-STABILITY-AND-TIME-TO-VALUE.md
@@ -0,0 +1,122 @@
+# 41 — Phased practical improvements to risc-v-gsp-rm-debugger: stability and time-to-value report
+
+> **Date:** 2026-10-03. **Scope:** the simulator/debugger workstream inside
+> `debug/risc-v-gsp-rm-vm/` only. **Verdict:** the minimum bar for marking the
+> *tool and standalone GSP simulator* as **stable (conditional)** is passed:
+> 298 tests green twice, deterministic real-firmware runs, an independently
+> reproduced A/B verdict "above the QEMU line", and reproducible value
+> measurements. Conditions are listed in §7 — chiefly that the device model
+> currently reaches boot rung B2 (not the message loop) and cycle numbers are
+> modelled, not silicon-calibrated.
+>
+> Local notes: `../../../../handoff-simulator.md` (directive ledger, top work),
+> `../LOCAL-REVIEW-NOTES.md` (local provenance). Public text describes
+> components and behaviour only.
+
+## 1. What we were doing before (the QEMU baseline)
+
+* The only execution engine was `qemu-system-riscv64` via the gdbstub. On the
+  real `gsp-570.144.fwimage.bin` it loaded flat, executed a handful of
+  instructions, faulted at firmware vaddr `0x4009014` reading
+  `0x2000000000000A00`, then looped on `mtvec=0`.
+* Questions about GSP boot progress could only be answered by static reading
+  of decompiled code; every dynamic question stalled at the first fault.
+* Tool runs produced sessions, but with no device semantics, no cycle context,
+  and no way to prove "the emulator knows more than the probe".
+* New-firmware triage was a manual sequence of probe + version diff + reading.
+
+## 2. What we are doing now (the upgrade, phased)
+
+| Phase | Improvement | Status |
+|---|---|---|
+| P1 | **GSP device model** (`sim/devices/`, `sim/profiles/`) with PMC/FALCON/PRISCV/timer/CSB/FWSEC/PMU/DMA/IRQ windows, versioned profile, boot shims | B2: 14,682 instr, fault `0x400EA0C`, 0 unknown MMIO, two-run identical |
+| P2 | **`sim.gsp_boot` boot-ladder runner** with rung classification and serialisable device state | B0–B2 (B3/B4 targets) |
+| P3 | **One-command release triage** (`./risc-v-gsp-rm-debugger.sh triage`) orchestrating identity/QEMU probe/native boot/A-B eval/version diff/readiness | 570.144 in ~2.7 s; baseline pair ~11.4 s |
+| P4 | **QEMU-line A/B evaluation harness** (`harness/sim_qemu_line.py`, frozen checks) | verdict `above`, all threshold checks computed from live runs |
+| P5 | **Real RE demonstration** (`harness/re_demo.py`) answering a concrete bootstrap question with simulator tools | PASS 5/5, 0.13 s vs 601 s baseline floor |
+| P6 | **MCP native-backend tools** (launch, cycles, device state, profile, regions, budgets) | 55 MCP tests green; read-only default preserved |
+| P7 | **Documentation and workflow review** (`docs/39`), docs 30–41, README/Makefile integration, link checks | 143 tool files link-checked, 0 broken |
+
+## 3. Proof of value (before → after)
+
+| Scenario | Before | Now | Evidence |
+|---|---|---|---|
+| What happens in GSP boot before the first wall? | QEMU: fault at `0x4009014`, stop | Device model serves the path; deterministic B2 fault `0x400EA0C`; unknown accesses 0 | `python3 -m sim.gsp_boot`; sessions `dumps/gsp-boot-b2-run1/2` |
+| Triage a new firmware image | manual probe + reading, ~1800 s estimated | one command, **2.68 s**, JSON+MD report with hashes | `./risc-v-gsp-rm-debugger.sh triage --firmware … --version 570.144` |
+| Is the emulator better than QEMU? | no mechanism | validators run both, compute rung/feature deltas; verdict `above` | `python3 harness/sim_qemu_line.py` |
+| Answer a bootstrap RE question | static reading only | 5/5 recorded answers in 0.13 s | `python3 harness/re_demo.py` |
+| Scripted/agent operation against the simulator | QEMU-only MCP | native backend tools tested | `tests/test_mcp.py` |
+
+Baselines are explicitly labelled estimates where they are not measured human
+studies (frozen thresholds: 600 s RE-time floor, 1800 s triage baseline); all
+wall times are labelled host-load dependent. Every number above has a
+one-line command in the report/doc that produced it.
+
+## 4. Stability evidence
+
+* `python3 -m unittest discover -s tests -t .` → **298 tests, OK**, twice
+  (rounded identity across runs); MCP 55, triage 14, device model 34 new
+  checks included.
+* Determinism: B1/B2 device-state SHA identical across runs; triage sessions
+  hashed; A/B harness repeats native runs and compares.
+* Back-compat: `Session`, `RspClient`, `SimClient` and CLI keep prior
+  behaviour; additions are keyword/default forms; QEMU path untouched
+  (toggle `--backend qemu|native`).
+* Boundary compliance: no writes outside the tool dir; no hardware, module,
+  guest, mdev, reboot or RM 610 action; MCP read/observe default unchanged.
+* Fidelity honesty: cycles are labelled *modeled*; L2 is not claimed
+  silicon-accurate; L3 device semantics are declared assumptions in-session;
+  "above QEMU" is computed against the frozen rung contract, not asserted.
+
+## 5. Adversarial review record
+
+* **Round 1** (review + fix): 3 P1s found and fixed — device model not wired
+  into the A/B harness/triage, dead PTIMER window offsets, MCP device-state
+  returning a non-JSON object. P2 backlog listed.
+* **Round 2** (independent, harsher): falsification runs confirmed all
+  headline numbers; 2 P1s found and fixed (docs/35 B1 overclaim; personal
+  host path in `gpgpu-sim/setup.sh`), 8 P2s fixed (timer opt-in, FWSEC state
+  derivation, DMA refusal counting, PMC chip-ID duplication, overlapping
+  window fallback, stale doc counts, `session_launch` documentation, docs/40
+  measurement labels). One latent item recorded: WPR2 window offsets versus
+  profile base (firmware never touches it in B0–B2).
+* Verdict after fixes: conditional stability as stated in §7; no unverified
+  "beats silicon" or "boots RM" statement anywhere.
+
+## 6. Top work for the next session (time-to-value first)
+
+1. **Push the device model to B3/B4** (CSB/TRANSCOM mailbox semantics,
+   DMEM runspace source, PMU/FWSEC stubs) — this is the gate to serving a
+   real RM message and the largest remaining time-to-value lever.
+2. **Surgical rehost of the live GR engine-context promote/commit wall**
+   (docs/39 top-3): convert the manual, multi-cycle physical campaign into
+   device-free hook/watch/compare sessions.
+3. **Physical-cycle capture → session → compare** helper (read-only), to cut
+   the dominant recorded cost of manual evidence assembly.
+4. Everything else remains in the private handoff: GPGPU-Sim board model,
+   VF bridge (`GREENEYE_GSP_EM_BRIDGE`, default OFF), VBIOS, fabric,
+   Ampere/Blackwell, and the "not useful yet" list.
+
+## 7. Conditions on the stability claim
+
+1. Device model ceiling is B2; B3/B4 pending profile semantics.
+2. Cycle counts are modelled defaults, not calibrated bands.
+3. Manual-baseline speedups use labelled estimates, not timed human studies.
+4. Cross-version triage was exercised as a self-diff rehearsal (no second
+   local firmware version); RM 610 remains human-gated.
+5. The stability claim covers the tool and its standalone GSP simulator, not
+   any GPGPU-Sim integration or silicon equivalence.
+
+## 8. Reproduce everything
+
+```bash
+cd open-iov/debug/risc-v-gsp-rm-vm
+python3 -m unittest discover -s tests -t .          # 298 tests
+python3 -m sim.gsp_boot                             # B2
+python3 -m sim.gsp_boot --no-shim                   # B1 budget stop
+python3 harness/sim_qemu_line.py                    # verdict "above"
+python3 harness/re_demo.py                          # PASS 5/5
+./risc-v-gsp-rm-debugger.sh triage \
+  --firmware ../../../firmware/57X-GSP/570.144/gsp-570.144.fwimage.bin \
+  --version 570.144 --out /tmp/triage-570.144
+```