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.

2 files changed, 47 insertions, 3 deletions

diff --git a/docs/05-operations/03-risc-v-gsp-rm-vm.md b/docs/05-operations/03-risc-v-gsp-rm-vm.md
index a55e3ac..b6e52db 100644
--- a/docs/05-operations/03-risc-v-gsp-rm-vm.md
+++ b/docs/05-operations/03-risc-v-gsp-rm-vm.md
@@ -67,6 +67,14 @@ run the same stimulus in risc-v-gsp-rm-debugger, and compare the recorded sessio
 `docs/06-ACCURACY.md`. Portability runs (new GSP, new device, GB10-class
 architecture) are described in `docs/07-PORTABILITY-PLAYBOOKS.md`.
 
+When the question is an accept/refuse predicate on a control or entry (e.g. a
+promote/shape the firmware keeps refusing), run the firmware's own validation
+branch offline first with `harness/valprobe.py` (crafted state, labelled
+outcome addresses, deterministic; `docs/47-VALIDATION-PREDICATE-PROBE.md`) —
+it answers in seconds what would otherwise cost a static guess or a supervised
+cycle. Use `harness/rehost.py` (`docs/46-SURGICAL-REHOST.md`) for a whole
+handler/function whose first missing state is itself the finding.
+
 ## 4. Quick start
 
 From the repository root:
@@ -93,8 +101,30 @@ hooks/breakpoints/watchpoints, memory tools, structure decoding, session
 recording and analysis, declarative probes, plugins, remote calls and
 run-to-cursor, the injection SDK with direct and firmware-dispatched service
 invocation, the Ghidra symbol/hit bridge and Ghidra control bridge, the
-real-firmware first-fault probe, and the TCG full-memory trace plugin. Not
-implemented: device model (R1), custom simulator (R2), MCP plugin (R3) — all
+real-firmware first-fault probe, and the TCG full-memory trace plugin.
+
+Standalone simulator increments (2026-10-06): the native RV64 machine with a
+GSP device model and a deterministic real-firmware boot ladder to **B3**
+(570.144 image, ~474k instructions, two-run identical), one-command release
+triage, GMMU/FBIF observe-only windows and the PTE/PDE decoder, the RM RPC
+capture decode/compare/stimulus tooling (`harness/rm_capture.py`, docs/45),
+surgical rehost (`harness/rehost.py`, docs/46) and the validation-predicate
+probe (`harness/valprobe.py`, docs/47). The predicate probe executes the
+shipped firmware's own accept/refuse branch offline with crafted state and
+labelled outcomes (seconds, deterministic) — the intended first stop for
+control/entry-shape questions before any supervised cycle. The functional
+GMMU page-table walker and launch memory-contract auditor
+(`sim/gmmu_walk.py`, `harness/launch_audit.py`, docs/48) resolve every
+engine-visible address of a submission (ring, inline-QMD destination,
+parameter/program pages, release slot) against captured page tables and
+classify mismatches, so "where would the engine read/write this VA?" is an
+offline question. The suite is at 489 tests.
+
+Limits: fidelity is instruction/memory semantics (L0/L1) — no timing (L2) and
+no device environment (L3); host message traffic (B4/B5) is not yet served,
+so sessions stay boot-state/predicate level; the GR engine and other GPU
+execution units are **not** modelled, so engine/silicon behaviour remains a
+hardware question. Not implemented: custom simulator (R2), MCP plugin (R3) —
 roadmap. The long-term program (adversarial navigation, adjacent
 microcontrollers, custom simulator, Verilog soft-core, agentic platform) is
 documented in `debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`.
diff --git a/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md b/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md
index d16da23..7055f0e 100644
--- a/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md
+++ b/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md
@@ -167,6 +167,10 @@ Run everything from `open-iov/debug/risc-v-gsp-rm-vm/` unless stated.
 | `ci_release.py` | version_diff → matrix → mutation smoke, hashed into one bundle |
 | `port_driver_versions.py`, `port_new_device.py`, `package_sim.py` | porting/packaging scaffolds (dry-run default; pilot status and evaluation in [docs/28](../../debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md), [docs/29](../../debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md)) |
 | `value_demos/run_all.py` | ten fixed scenarios s01–s10 with measured time-to-value |
+| `rm_capture.py` | real-client GSP RPC capture: decode, compare, replay prep ([docs/45](../../debug/risc-v-gsp-rm-vm/docs/45-RM-RPC-CAPTURE-AND-REPLAY.md)) |
+| `rehost.py` | run one bounded firmware function with crafted state and before/after snapshots ([docs/46](../../debug/risc-v-gsp-rm-vm/docs/46-SURGICAL-REHOST.md)) |
+| `valprobe.py` | run one firmware validation branch with crafted state and labelled outcome addresses (offline predicate probe; [docs/47](../../debug/risc-v-gsp-rm-vm/docs/47-VALIDATION-PREDICATE-PROBE.md)) |
+| `launch_audit.py` | audit a submission's engine-visible memory contract against captured page tables: `ok`/`pa_mismatch`/`unmapped`/`access_denied` per leg ([docs/48](../../debug/risc-v-gsp-rm-vm/docs/48-GMMU-WALK-AND-LAUNCH-AUDIT.md)) |
 | `common.py` | shared helpers (flat relocation, sessions, bounded log reads) |
 
 ### 4.3 Native simulator, plugins, host oracle, bridges
@@ -174,6 +178,7 @@ Run everything from `open-iov/debug/risc-v-gsp-rm-vm/` unless stated.
 | Tool | One-line purpose |
 |---|---|
 | `sim/` (`--backend native`, `--trace`) | deterministic RV64IMAC interpreter with exec/access trace and lenient MMIO |
+| `sim/gmmu_walk.py` | functional GMMU page-table walker over captured/constructed tables (VER2 4K/2M validated; 64K modelled) |
 | `python3 -m greeneye.device_map harvest\|show\|merge\|demo` | first-touch MMIO map: authoring, inspection, merge |
 | `qemu/greeneye_trace.c` (`make -C qemu`) | full TCG exec/access JSONL trace with `start=`/`end=` filters |
 | `plugins/example_plugin.py` | plugin authoring reference |
@@ -200,9 +205,18 @@ Run everything from `open-iov/debug/risc-v-gsp-rm-vm/` unless stated.
 | "Explore MMIO the firmware touches first" | `probe` → `python3 -m greeneye.device_map` | versioned JSON; feeds the device model |
 | "Triage a release end to end" | `harness/ci_release.py` | always `--dry-run` first |
 | "Let an agent monitor a run" | `plugins/mcp_server.py` | read/observe by default; writes gated |
+| **"Which control/entry shape does the firmware accept, and why?"** | `harness/valprobe.py` | offline predicate branch with crafted state + labelled outcomes; deterministic, seconds; [docs/47](../../debug/risc-v-gsp-rm-vm/docs/47-VALIDATION-PREDICATE-PROBE.md) |
+| **"A handler/function early-outs on state we don't have"** | `harness/rehost.py` | bounded call with crafted state; the first missing state is the finding; [docs/46](../../debug/risc-v-gsp-rm-vm/docs/46-SURGICAL-REHOST.md) |
+| "Decode/compare the real client's GSP RPCs" | `harness/rm_capture.py` | offline decode/stimulus; consumption awaits the message-injection rung; [docs/45](../../debug/risc-v-gsp-rm-vm/docs/45-RM-RPC-CAPTURE-AND-REPLAY.md) |
+| **"Where would the engine read/write this VA?"** | `sim/gmmu_walk.py`, `harness/launch_audit.py` | walk captured/constructed page tables offline; per-leg `ok`/`pa_mismatch`/`unmapped`/`access_denied`; [docs/48](../../debug/risc-v-gsp-rm-vm/docs/48-GMMU-WALK-AND-LAUNCH-AUDIT.md) |
 
 Decision rule: static reading is a hypothesis; a recorded session is evidence;
-at least an A/B pair is a conclusion.
+at least an A/B pair is a conclusion. If the question is "what will this
+firmware branch do with input/state X?", probe it offline first
+(`valprobe`/`rehost`, seconds, deterministic) and spend supervised cycles only
+on what the probe cannot see (engine/silicon behaviour); if it is "what does
+the silicon do?" or "does the run survive?", it is a hardware question and the
+simulator makes no L2/L3 claims.
 
 ## 6. Sessions as evidence