# 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.