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, 91 insertions, 0 deletions

diff --git a/debug/risc-v-gsp-rm-vm/docs/46-SURGICAL-REHOST.md b/debug/risc-v-gsp-rm-vm/docs/46-SURGICAL-REHOST.md
new file mode 100644
index 0000000..e64be25
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/docs/46-SURGICAL-REHOST.md
@@ -0,0 +1,91 @@
+# 46 — Surgical rehost of firmware functions (in development)
+
+> **Status: in development (2026-10-06, rehost wave).** Documents
+> `harness/rehost.py`: run one bounded function of a real/modelled firmware
+> image on the native emulator, starting at a chosen entry with a crafted
+> register/memory state, and record a session + report. This is the workflow
+> the RE review ranks first for the live GR wall (docs/39 U2): answer
+> server-side hypotheses from rehosted execution with hooks/watchpoints/
+> memory tools instead of another static read or another hardware cycle.
+>
+> Development-only: executes firmware on the simulator. Never touches a GPU,
+> kernel module, mdev, guest or network. No timing/cycle claim (L0/L1).
+>
+> **See also:** `39-RE-WORKFLOW-REVIEW.md` (U2), `44-GMMU-ORACLE-AND-WORKFLOW.md`
+> (the same evidence discipline), `03-SCRIPTING.md` (hooks/watch/memory),
+> `16-CUSTOM-SIMULATOR.md` (backend design), `45-RM-RPC-CAPTURE-AND-REPLAY.md`
+> (the capture whose sequence a rehost can seed).
+
+## 1. What it does
+
+* Loads an ELF image into the native machine exactly like `sim.gsp_boot`
+  (device registry from the profile, optional boot shim, libos syscall model,
+  lenient MMIO).
+* Writes caller-supplied memory (`--mem addr=hex`), sets `a0..a7`
+  (`--arg`), installs a return trampoline (`ra` + `ebreak` sentinel) and a
+  private stack, and starts at `--entry` (hex address or ELF symbol).
+* Runs under `--budget` instructions and a wall-clock `--timeout`, stopping on
+  return (`R_BP` at the sentinel), fault, unhandled ecall, timeout or budget.
+* Snapshots regions before/after (`--snap addr:size`) with per-region changed
+  bytes, first-difference offset and sha256s; dumps nonzero registers on entry
+  and exit; records a `greeneye-session/1` directory and a
+  `greeneye-rehost/1` report.
+
+```
+python3 harness/rehost.py run --entry 0x5b01210 --arg 0 --budget 50000 \
+    --snap 0x1000000:64 --out dumps/rehost-gate
+python3 harness/rehost.py demo          # synthetic self-test (demo firmware)
+```
+
+## 2. Report schema (`greeneye-rehost/1`)
+
+`status` is one of `return | fault | ecall | timeout | budget`; `fault`
+carries the trap cause and `tval`; `retval` is `a0` at the stop; snapshots
+carry the before/after diff. The report states its limits explicitly: it is
+**not a boot** (the function ran with only the supplied state), a fault is the
+**first missing state observed**, not a product defect, and there is no
+timing claim.
+
+## 3. First probes on the 570.144 image (2026-10-06)
+
+All offline, one bounded call each, `a0=0`, budget 300k (numeric vaddrs from
+the campaign analysis):
+
+| entry | status | stop pc | `a0` at stop | insns | fault |
+|---|---|---|---|---|---|
+| GR per-buffer commit gate `0x5b01210` | fault | `0x0` | `0x40` | 24 | illegal @ `0x0` |
+| per-buffer commit `0x5b00d2c` | budget | `0x5b0110c` | `0x40` | 189 | — |
+| commit caller `0x5b00dd8` | budget | `0x5b0120c` | `0x40` | 110 | — |
+| engine-ctx memdesc install `0x514cab8` | fault | `0x0` | `0x429b450` | 97 | illegal @ `0x0` |
+| promote handler `0x526a530` | budget | `0x5244134` | `0x40` | 167 | — |
+| per-entry commit `0x5290a48` | budget | `0x5897fdc` | `0x40` | 258 | — |
+| engine-class commit `0x5350078` | budget | `0x5350484` | `0x40` | 197 | — |
+
+Reading: with no engine-context state, the whole gate family bottoms out in
+`NV_ERR_INVALID_STATE (0x40)` — the same family the live campaign observes —
+and the memdesc-install path faults on a NULL callback early. That is a
+reproduction of known behaviour, not an answer: the next step is to **seed the
+context objects** (from the B4 message-loop state or from crafted structures)
+and A/B the promote entry shapes against these entries.
+
+## 4. Admission record (draft — pending maintainer filing)
+
+Per the project admission rule (docs/eng-ops.md §2), all five fields:
+
+| Field | Value |
+|---|---|
+| Scenario | dynamic-RE loop: run the GR promote/commit functions of the real 570.144 image off-hardware at a chosen entry with crafted state, to answer server-side hypotheses (gate/entry/context requirements) without hardware cycles. |
+| Measurable outcome | sessions per hypothesis; wall time per probe; zero hardware cycles; rehost status/fault map. |
+| Baseline | the live campaign's modes 4–22 day (docs/39: 730+ lines of static RE, three wedge-reboot cycles for one accepted root cause). |
+| Evaluation threshold | ≥1 wall hypothesis answered with a session pair and **zero** hardware cycles; probe loop ≤ 2 minutes per entry (measured: ≈0.1 s per probe); deterministic status/`a0` across runs. |
+| Failure signal | a probe cannot be driven because required device semantics are absent, and crafted-state seeding cannot reach the failing branch after two bounded attempts → record the gap and fall back to static + physical. |
+
+## 5. Limits
+
+* Not a boot: entry-state dependence is the whole difficulty; a `budget` stop
+  usually means the entry is mid-function or the path loops without returning.
+* The first probes use caller-supplied `a0`; the real argument conventions and
+  context layouts are to be supplied by seeding (or by B4/B5 state).
+* Single hart, flat memory, no interrupts/scheduling; unknown MMIO is lenient
+  and counted, and can mask environment dependence.
+* No cycle/timing/security claim; L0/L1 fidelity only.