risc-v-gsp-rm-debugger: land docs 45-53 + harness/sim tool set with tests

rm_capture (chunked decode), launch_audit, state_seed/state_decode,
valprobe, rehost, contracts+run_contracts, host_traffic, gmmu_walk,
msgq_attach, libos_port, log_decode, server_snapshot; doc index updates
in the tool overview, operations pages and the repo README.

1 files changed, 80 insertions, 0 deletions

diff --git a/debug/risc-v-gsp-rm-vm/docs/49-SIMULATION-SURFACE-MAP.md b/debug/risc-v-gsp-rm-vm/docs/49-SIMULATION-SURFACE-MAP.md
new file mode 100644
index 0000000..f3de0c9
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/docs/49-SIMULATION-SURFACE-MAP.md
@@ -0,0 +1,80 @@
+# 49 — Simulation Surface Map and Handoff-vGPU Value Case
+
+Status: session 12 assessment (2026-10-06). Scope: the simulator workstream
+(`open-iov/debug/risc-v-gsp-rm-vm/`) and what it offers the GR campaign.
+Rule: nothing goes to `Handoff-vGPU-IO.md` unless a past wall proves it saved
+time. This document is that proof table and the coverage map for future walls.
+
+## 1. What the emulator is for (and is not)
+
+It boots the **real 570.144 blob** to `B3` (474k insns, deterministic, device
+model + LIBOS + MPU, `greeneye-session/1` recordings) and provides
+dump/inspect/inject around it. It is **not** a GR/PBDMA engine model: engine
+questions are answered by hardware captures + the GMMU/launch audit, never by
+simulation (L2/L3 absent, docs/06). Fidelity claims are L0/L1 only.
+
+## 2. Coverage map — what exists per subsystem
+
+| Subsystem (future-bug surface) | Tool / entry | Standard format | Status |
+|---|---|---|---|
+| Image/boot/portability | `sim/gsp_boot.py`, `harness/probe*`, `triage.py`, `version_diff.py` | `greeneye-session/1` | built, B3 ceiling |
+| Device windows / MMIO / BARs | `sim/devices`, `harness/gmmu_debug.py`, device-map | device-map JSON + sessions | built |
+| LIBOS/RTOS services, MPU | `sim/libos.py`, `sim/mpu.py` | sessions | built |
+| GMMU PTE/PDE (VER2/4K/2M/64K) | `sim/gmmu_pte.py`, `gmmu_walk.py`, `gmmu_oracle.py` | walk reports | built, live 5/5 fixture |
+| Launch memory contract (QMD/param/program/sem legs) | `harness/launch_audit.py` | `greeneye-launch-audit-spec/1` | built; awaiting supervised trace |
+| Validation predicates / gates | `harness/valprobe.py` | valprobe spec + labelled outcomes | built (FECS 15/15, seconds) |
+| Whole-function exec with crafted state | `harness/rehost.py` + snapshots | sessions | built; queued for construct gate |
+| Client RPC traffic (decode/replay-prep) | `harness/rm_capture.py` | capture JSON + compare | built; decode from logs |
+| Client↔server live traffic loop | **B4/B5 — missing** | (rm_capture stimulus) | strategic build |
+| RM object state (clients/channels/contexts) | **state-seeding fixture — missing** | (sessions) | campaign ask #1 |
+| Engine method execution (GR/PBDMA) | **not simulated by design** | captures + `launch_audit` | out of scope, L2/L3 absent |
+| Instrumentation/injection | hooks/watchpoints/snapshots, SDK, MCP, Ghidra bridge | `events.jsonl`, blobs, hits TSV | built |
+
+## 3. Standard capture formats (already unified)
+
+* `greeneye-session/1`: `session.json` + `events.jsonl` + `snapshots/` +
+  `blobs/` + `summary.md`; render with `analyze`, diff with `compare`.
+* `rm_capture` JSON: real client RPC decode/compare/stimulus preparation.
+* `greeneye-launch-audit-spec/1`: `pdb_pa` + `contract[]`
+  (label/va/access/expect_pa) + raw table pages → per-leg verdicts
+  (`ok`/`pa_mismatch`/`unmapped`/`access_denied`).
+* valprobe spec: crafted state + labelled outcomes → accepted/refused matrix.
+* symbols DB (export) and device map (harvest/query) schemas.
+
+## 4. Value-to-Handoff proof (do not add unproven tooling)
+
+| Past wall | Emulator contribution | Measured value | Verdict |
+|---|---|---|---|
+| FECS `0x1f` one-shot rule | `valprobe` predicate matrix, offline | matrix in seconds vs hours of static/log work; closed lane (a) | **proven, adopted** |
+| Fetch-state hypothesis (userd ctl/GET/PUT) | whole-image access scan | zero accesses proven exhaustively without a hardware cycle | **proven, closed §6** |
+| GMMU/QMD mapping forks | live 5/5 channel-PDB fixture + walker | fixture and verdict classes without silicon | **proven for audit input** |
+| Launch silence (`qmd_rel=5`) | `launch_audit` fork partitioned (`ok`/`pa_mismatch`/`unmapped`) | single spec run classifies the fork once trace exists | **ready, pending supervised spec** |
+| Golden-channel construct `-110`/`0x52a8b04` | rehost/probe queued; static analysis answered first | honest counter-example: analysis beat emulator here | **no claim yet** |
+| Engine execution/shape mismatches | none | captures + audit answer it | **never promise emulation** |
+
+Rule: a capability is added to Handoff-vGPU only with a row in §4 and an
+eng-ops admission (scenario + metric + baseline + threshold + failure signal).
+
+## 5. When the campaign should consult the emulator (and when not)
+
+| Wall type | Consult simulator? | Tool |
+|---|---|---|
+| Validation/refusal predicate, unknown gate | yes, first (seconds) | `valprobe` |
+| Address translation / PDB / launch contract | yes | `gmmu_walk`, `launch_audit` |
+| "Does the server read/write address X?" | yes | access scan / watchpoints |
+| Full client traffic interaction with server | only after B4/B5 | rm_capture + sessions |
+| RM `-110` deadlock with live objects | rehost if state can be crafted; else source | `rehost` |
+| Engine/silicon timing, PBDMA behaviour, real dispatch | no | hardware captures + audit |
+
+## 6. Queued build order (each needs the §4 admission before Handoff mention)
+
+1. **B4/B5 host-traffic message loop** — replay `rm_capture` stimulus into the
+   real blob, dump every reply/write: the generic tool for the wall class the
+   campaign keeps hitting ("what does the server do with our traffic").
+2. **RM-object state-seeding fixture** — execute whole construct/handler paths
+   with crafted channels/contexts (campaign ask #1).
+3. **Per-version golden matrices** — promote stable probe/audit runs to CI so
+   firmware bumps are regression-checked.
+
+Do **not** build: GR/PBDMA engine model, speculative backends, or any tool
+without a wall scenario it demonstrably solves faster.