path: root/docs/future-eng-ops.md

# Future engineering operations: risc-v-gsp-rm-debugger capabilities not yet earning their keep

> Companion to [`eng-ops.md`](eng-ops.md). That document records what the
> project uses now; this one records risc-v-gsp-rm-debugger capabilities that are built but
> unused, partially used, planned or research, each tied to an impending
> project need, scoped explicitly, and carrying an evaluation that can fail —
> plus a kill criterion if it never pays off. Nothing here is a product
> commitment, and no simulation observation becomes an accuracy claim without
> the physical-confirmation rules of
> [`06-ACCURACY.md`](../debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md).

Status snapshot: 2026-10-02. Sources are the risc-v-gsp-rm-debugger roadmap, tool docs
16–27, the `harness/` entry points and the tool audit (doc 27). The tool tree
is development-only: never shipped, never a dependency of `open-iov-vfio`,
never present in a guest. RM 610 work is gated by human approval
([`docs/21` §3](../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md),
[`docs/23`](../debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md)).

## 1. Status vocabulary

| Status | Meaning |
|---|---|
| `built, not used yet` | Implemented and tested, but no workflow calls it yet; the decision to keep is recorded. |
| `partially used` | Some pieces run in a real workflow; the capability as named is incomplete. |
| `planned` | Scoped in a roadmap/design document, not implemented. |
| `research` | No committed design; needs a funded use case before it becomes `planned`. |

Priority scale: **P1** do when the gate lands; **P2** next, capacity
permitting; **P3** when a consuming workflow exists; **P4** research or
funded-only. Effort is engineering-time for one developer familiar with the
tree, excluding multi-quarter research.

Every item below uses the same six fields: status, need, scope, evaluation
(metric / baseline / threshold / kill), gates, effort and priority.

## 2. Catalogue at a glance

| # | Capability | Status | Gate | Effort | Priority | Kill when |
|---|---|---|---|---|---|---|
| F1 | MCP automation of full port chains | `partially used` | CI pipeline (done), RM 610 approval | 1–2 wk | P2 | two releases show no MCP-only artifact |
| F2 | Multi-version driver port automation (540→current) | `partially used` | versioned inputs, anchor policy | 2–3 wk | P2 | two versions still need unabsorbed manual steps |
| F3 | Device-port automation scripts | `partially used` | reference device, GB10 availability | 1–2 wk | P2 | capture needs privileged/unsafe operations |
| F4 | Packing injected code and modified GSP images; trial bundles | `partially used` | H1.3, SDK | 2–3 wk | P3 | re-run needs host state or is non-deterministic |
| F5 | Control discovery against the real RM surface | `built, not used yet` | H1.3 + H2.2 | 1–2 wk | P1 | no dispatch table exposed after H2.2 |
| F6 | Value demos extended to rehosted uproc | `planned` | rehost shim (H2.3/R2) | 2–3 wk | P1 | fewer than 4 classes transfer |
| F7 | Native simulator M2+ (map DSL, snapshots, scheduler) | `partially used` | H2.2 exit (hard) | 24–36 wk | P1 | moments cannot restore identically by M3 |
| F8 | Adjacent-microcontroller models | `planned` | H2.2 | 6–10 wk | P2 | PMU/SEC2 semantics unprovable in one milestone |
| F9 | Performance analysis tooling (before/after) | `partially used` | H2.2 for real firmware | 2–3 wk | P3 | reports disagree with physical benchmarks |
| F10 | Guest/userspace friction: RDMA, shared page tables, peers | `research` | funded platform case | 8+ wk | P4 | no funded scenario at review |
| F11 | SIMD cores and CUDA kernel execution on device | `research` | H6/H3, funded reason | unbounded | P4 | first kernel prototype fails bit-exactness |
| F12 | FPGA soft-processor simulation | `planned` | H2/H3 proven, funded timing claim | multi-quarter | P4 | no funded timing claim at review |
| F13 | Verilog recreation of GSP components and NVRISC fabric | `research` | F12 progress, legal review | multi-quarter | P4 | accuracy cannot be bounded after first milestone |
| F14 | Hidden/undocumented/unauthorized-code discovery | `partially used` | H1.3 + H2.2 | 3–5 wk | P2 | two real releases yield no actionable finding |
| F15 | SBOM/architectural understanding from observations | `planned` | H2.2, legal review | 2–3 wk | P3 | observation rows rejected twice by SBOM review |

Status counts: `built, not used yet` ×1 (F5); `partially used` ×7 (F1, F2,
F3, F4, F7, F9, F14); `planned` ×4 (F6, F8, F12, F15); `research` ×3 (F10,
F11, F13). Each item carries exactly one evaluation criterion.

## 3. Items

### F1 — MCP automation of full port chains

| Field | Detail |
|---|---|
| **Status** | `partially used`. The MCP server is implemented and tested (24 tools, read/observe by default, writes and injection gated; [`20-MCP-SERVER.md`](../debug/risc-v-gsp-rm-vm/docs/20-MCP-SERVER.md)), and it exposes `probe_firmware`, `portability_matrix_run`, `mutation_run` and `compare_sessions`. No agent has driven a complete release chain through it, and `version_diff`/`ci_release` have no MCP tool. |
| **Need** | RM 610 readiness criteria C4/C5 require the MCP path and the release pipeline to be exercised, not merely present ([`23-RM610-READINESS.md`](../debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md)); every future GSP/driver release should be monitorable by an agent while a human keeps the merge gate. Waiting means each release is driven by hand and the 610 evidence pack stays unproven. |
| **Scope** | Does orchestrate the existing MCP tools plus a new `version_diff`/`ci_release` entry into one named, budgeted pipeline ending in a hashed bundle; does not add network transport, does not relax write/inject gating, does not approve product changes. |
| **Evaluation** | Metric: pipeline steps completed through MCP per release with a bundle manifest. Baseline: 0 complete chains (CLI only). Threshold: one 570.144 self-pair rehearsal completes probe → matrix → mutation → compare → bundle through MCP with artifact hashes equal to the CLI chain. Kill: if two releases produce no artifact the CLI chain lacks, retire the pipeline tool and keep MCP session-level only. |
| **Gates** | MCP server (done) and release pipeline (done, [`21`](../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md)); human approval before any RM 610 input; recorded session for every write. |
| **Effort / priority** | 1–2 engineering-weeks; **P2** (unblocks RM 610 C4/C5). |

### F2 — Multi-version driver port automation (540-series → 570.144 → 580/610)

| Field | Detail |
|---|---|
| **Status** | `partially used`. `cudatool.py info/delta/fdematch`, `diff_corpus.py`, `annotate_corpus.py` and `symbols export` are in production use for the 570.144 anchor, but the docs/22 §2 runbook is ten manual steps. A concurrent `harness/port_driver_versions.py` scaffold is landing as an unadmitted pilot (dry-run default; [`docs/28`](../debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md) §2); no chained multi-version run is admitted or exercised yet and there is no 540-era regression corpus in-tree. Evaluate `harness/port_driver_versions.py` as an extension of `ci_release.py` rather than a third orchestrator; the criterion for keeping it separate is that the sweep must meet the F2 threshold without a release bundle as a precondition, otherwise fold it into `ci_release.py`. |
| **Need** | The anchor is 570.144; deployed guests and the anticipated 580/610 families each repeat the same runbook, and wrapper re-resolution (~1% of wrapper names transfer by address) is a known trap ([`22-PORTING-CUDA-AND-DEVICES.md`](../debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md)). Each repeat costs days of human time and risks silently moving wrapper names. |
| **Scope** | Does chain the existing CUDA tools into one per-version report (exports, FDE transfer matrix, corpus delta, name map, symbol DB, smoke results) and diff reports across versions; does not decompile unknown binaries automatically, does not change the firmware anchor, does not run a guest smoke without a supervised guest. |
| **Evaluation** | Metric: wall-clock and human minutes per version triage to a complete evidence pack. Baseline: the recorded 570.144 → 570.211 manual runbook. Threshold: one rerun (or 540-era reference) triaged in ≤50% of the baseline human minutes with wrapper re-resolution warnings preserved. Kill: if two consecutive versions need manual steps the chain cannot absorb, drop the chain and keep per-step tools. |
| **Gates** | Versioned parallel directories and anchor policy ([`22`](../debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md) §1); RM 610 gate; no new acquisition policy. |
| **Effort / priority** | 2–3 engineering-weeks; **P2**. |

### F3 — Device-port automation scripts

| Field | Detail |
|---|---|
| **Status** | `partially used`. Probe first-touch, portability matrix and version diff exist for firmware targets, but the device profile fields of docs/22 §3.1 are collected by hand (`lspci`, sysfs, `rmtool` JSON, guest diagnostics) and `config/hardware/*.yaml` is a design target, not read by code. A concurrent `harness/port_new_device.py` scaffold is landing as an unadmitted pilot (dry-run default; [`docs/28`](../debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md) §3); it is not yet exercised and no profile capture has been automated in a workflow. |
| **Need** | TU104 → GB202/GB10-class ports each require the profile table plus a pairing check; a missed field surfaces later as an "emulation bug". Pairing errors are already a known failure mode (570.144 image vs 570.211 driver). |
| **Scope** | Does script the read-only profile capture (PCI IDs, BAR layout, FB geometry, engine inventory, MSI-X topology, ROM quirks, probe-time registers), verify firmware pairing, and run the matrix across reference and candidate to emit a candidate profile plus evidence. Does not bind drivers, does not write to the device, does not claim support. |
| **Evaluation** | Metric: profile fields captured automatically out of the eight in docs/22 §3.1. Baseline: fully manual table. Threshold: ≥7/8 fields plus a pairing verdict and matrix report from one command on the reference TU104. Kill: if any required capture needs privileged writes or is not read-only-safe, retire the script to the manual table. |
| **Gates** | Supervised access to the reference device; GB10 hardware availability; the 610 gate where labels match. |
| **Effort / priority** | 1–2 engineering-weeks; **P2**. |

### F4 — Packing injected code and modified GSP images; trial bundles

| Field | Detail |
|---|---|
| **Status** | `partially used`. The PIC service SDK, `./risc-v-gsp-rm-debugger.sh inject`, `elf.write_flat_kernel` and newly tested `write_relocated_elf` exist, and version diff already byte-patches an image ad hoc (docs/25 s07). A concurrent `harness/package_sim.py` scaffold is landing as an unadmitted pilot (trial directory plus `--pack-image`; [`docs/29`](../debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md)); no packer or trial bundle is admitted, hash-verified in CI, or used by a reviewer workflow yet. |
| **Need** | Injection experiments today are demo-slot recipes; RM-core injection (H1.3) and reviewer replay need a reproducible artifact, the docs/23 C8 evidence bundle needs one-command reproduction, and hand-built byte patches do not carry an ABI/version contract. |
| **Scope** | Does build a deterministic image-pack (input hash, relocation map, injected segments, patched dispatch entries, blob ABI version) and a trial bundle (tool revision, profile, stimulus, expected session); does not sign images, does not bypass firmware checks, does not make an image runnable on hardware, does not ship. |
| **Evaluation** | Metric: manual steps to reproduce a reviewer's injected-service run from the artifact. Baseline: the ad-hoc patch + inject recipe. Threshold: one command yields a bundle whose rerun reproduces a byte-identical session on a clean host. Kill: if a rerun depends on host-specific state or is non-deterministic, retire the pack format and keep sessions as the artifact. |
| **Gates** | H1.3 for RM dispatch patching; `make sdk`; the docs/12 blob contract; native M2 moments optional. |
| **Effort / priority** | 2–3 engineering-weeks; **P3**. |

### F5 — Control discovery against the real RM surface

| Field | Detail |
|---|---|
| **Status** | `built, not used yet`. The `Surface` abstraction, sweep, classification, reporting and determinism tests are complete; `--surface rm` exists but exits cleanly because no RM control/method entry point is exposed ([`19-CONTROL-DISCOVERY.md`](../debug/risc-v-gsp-rm-vm/docs/19-CONTROL-DISCOVERY.md) §5). |
| **Need** | Every new GSP image can add or re-point controls silently; static table reading is per-image work and does not reveal triggers or effects. Control inventory (M1) is the input surface the emulation must handle, and the RM 610 port will need it first. |
| **Scope** | Does sweep RM control/method IDs by class with deterministic argument patterns, capture handler entry, selected object, status and effect snapshots, and replay a found route via `reach.py`; does not call hardware or a live RM, does not treat unreachability as proof, does not mutate replies. |
| **Evaluation** | Metric: RM controls classified with handler entry and effect snapshot versus the `rmtool` host-oracle inventory. Baseline: demo-only sweep (189 probes ≈ 36 s, docs/19 §3.4). Threshold: after H1.3/H2.2, one real control space swept with ≥90% of oracle controls attributed or explicitly default-path, plus one previously unknown control reached and replayed with a recorded session. Kill: if H1.3/H2.2 do not expose a dispatch table, retire `--surface rm` and re-scope discovery to rehosted dispatch code. |
| **Gates** | H1.3 + H2.2 (hard); device map ([`24`](../debug/risc-v-gsp-rm-vm/docs/24-DEVICE-MAP.md)); human approval for 610. |
| **Effort / priority** | 1–2 engineering-weeks after the gates; **P1** when H2.2 lands. |

### F6 — Value demos extended to rehosted uproc

| Field | Detail |
|---|---|
| **Status** | `planned`. s01–s10 run and are measured on the bundled `uproc_demo`; every real-firmware case in [`25-VALUE-VALIDATION.md`](../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md) is labelled blocked or projected. No demo runs on a rehosted GSP-derived uproc build. |
| **Need** | The value claim is currently analog-only. Reviewers, the RM 610 C8 evidence pack and the project's "hours, not weeks" success criterion need the same ten question classes answered on NVIDIA-derived code before the physical path is required. |
| **Scope** | Does port the demo classes (reply consumer, counter publication, unknown commands, run-until, snapshot diff, injection, version diff, mutation, Ghidra join, evidence pack) to a rehosted uproc ELF with identical success/failure tables; does not require the full image to boot, does not claim GSP-RM fidelity beyond the rehosted subset. |
| **Evaluation** | Metric: demos passing against a rehosted uproc with the expected outcome. Baseline: 10/10 on the demo analog only. Threshold: ≥6/10 on rehosted uproc, the remainder explicitly device-model-blocked with reasons, per-demo wall clock ≤2× analog. Kill: if fewer than four classes transfer, keep the demo corpus as a tooling regression suite, stop calling it value validation and re-scope docs/25. |
| **Gates** | A rehost shim and a stable symbol DB for the rehosted build (roadmap R2/H2.3). |
| **Effort / priority** | 2–3 engineering-weeks; **P1**. |

### F7 — Native simulator M2+ (map DSL, snapshots/time-travel, deterministic scheduler)

| Field | Detail |
|---|---|
| **Status** | `partially used`. M1 (RV64IMAC interpreter + `Session` parity) and M1.5 (native exec/access trace) are implemented and differential-tested; the device map and lenient MMIO mode exist. M2–M6 — map DSL, falcon/CSB/PTIMER devices, moments, deterministic scheduler, injection ABI, performance hardening — are designed but not built ([`16-CUSTOM-SIMULATOR.md`](../debug/risc-v-gsp-rm-vm/docs/16-CUSTOM-SIMULATOR.md)). |
| **Need** | QEMU has no cheap snapshots, deterministic replay or in-process device callbacks, so the fuzzing and discovery harnesses pay a fresh session per probe (measured ~36 s/189 probes) and branch exploration is impossible. H4/H5 work and the R5 fuzzing corpus are gated on cheap forks and replay. |
| **Scope** | Does M2 map DSL + falcon/CSB/PTIMER + moments; M3 deterministic scheduler + event log/replay; M4 device-model parity with H2.2; M5 injection ABI/interception; M6 performance and CLI. Does not claim L2 timing or cycle accuracy, does not replace QEMU before M4, no realtime behaviour. |
| **Evaluation** | Metric: (a) double-run canonical hash equality, (b) moment save/restore latency against the docs/16 §14 targets (≤100 ms save / ≤50 ms restore at 256 MiB sparse), (c) rehosted boot from a profile plus restore reproducing the event-stream hash. Baseline: fresh-session cost and QEMU. Threshold: all M2/M3 exit criteria in docs/16 §13 met on the rehosted uproc. Kill: if moments cannot restore byte-identical sessions by the M3 exit, drop snapshots and keep deterministic replay-only. |
| **Gates** | H2.2 exit (hard, cannot start before); docs/16 §13. |
| **Effort / priority** | 24–36 engineering-weeks for M2–M6; **P1** after H2.2, not before. |

### F8 — Adjacent-microcontroller models

| Field | Detail |
|---|---|
| **Status** | `planned`. H5 defines PMU/SEC2/ACR/SOE inventory, per-controller maps and cross-controller scenarios; none is modelled. H2.2 will force partial PMU/SEC2 stubs to pass early GSP init. |
| **Need** | GSP-RM early init reads PMU identity/clock provisioning and SEC2 state; GB10-class and confidential-compute partitions follow the Init → ACR → RM ordering. Cross-controller regressions are invisible until a hardware cycle fails, which is exactly the expensive class this tool exists to remove. |
| **Scope** | Does per-controller memory maps, mailbox protocols and boot state machines as versioned profile data, plus recorded cross-controller sessions; does not fully model the security chain, does not make confidentiality or attestation claims, does not run real ACR/SOE. |
| **Evaluation** | Metric: cross-controller exchanges reproduced and compared against hardware evidence. Baseline: 0. Threshold: one exchange (GSP ↔ PMU identity/clock) reproduced with an A/B session pair reaching the same state as the hardware reference under the docs/06 metric table. Kill: if PMU/SEC2 semantics cannot be established from public evidence within one milestone, keep only documented H2.3 shims and mark adjacent-controller claims out of scope. |
| **Gates** | H2.2; public/authorised source material; a hardware reference capture; docs/23 gate for any 610-family controller. |
| **Effort / priority** | 6–10 engineering-weeks for PMU/SEC2 stubs; **P2**. |

### F9 — Performance analysis tooling (profiling path, before/after methodology)

| Field | Detail |
|---|---|
| **Status** | `partially used`. `sim_bench.py`, the trace-overhead measurements (docs/16 §1.1a, docs/25 §6) and the product A/B methodology in [`01-performance-correctness-security.md`](05-operations/01-performance-correctness-security.md) §3 exist. There is no risc-v-gsp-rm-debugger path that profiles a product run off-hardware or produces an automated before/after report. |
| **Need** | Every emulation change is measured against docs/05 targets (e.g. init within 2× native) using physical cycles and a manual harness; pre-screening structural regressions off-hardware would reduce failed physical cycles. M7 timing is never claimed, so the useful signal is structural (instruction/event counts, session bytes, written pages), not wall clock. |
| **Scope** | Does capture deterministic structural metrics per session and diff them before/after with an explicit fidelity label; does not make timing or wall-clock claims about silicon, does not replace the physical benchmark in docs/05. |
| **Evaluation** | Metric: fraction of perf-sensitive emulation changes that receive a risc-v-gsp-rm-debugger before/after report before the physical benchmark. Baseline: 0. Threshold: five consecutive changes carry a report, and structural regressions ≥10% are flagged before the hardware run. Kill: if reports agree with the physical benchmark less than 50% of the time, retire them to debug annotations only. |
| **Gates** | H2.2 for real firmware; docs/06 M7 rule; docs/05 methodology is authoritative. |
| **Effort / priority** | 2–3 engineering-weeks; **P3**. |

### F10 — Guest/userspace compatibility friction: RDMA, shared page tables, simulated peers

| Field | Detail |
|---|---|
| **Status** | `research`. No peer-device simulation (DPU/NIC/NVMe), no RDMA path; page-table work exists only on the product GMMU/IOMMU side and in the physical-backend wiring. |
| **Need** | Edge-AI platforms place GPU, networking and storage VMs in one trust domain with device-to-device data paths ([`haaeep-and-collaboration.md`](08-ecosystem/haaeep-and-collaboration.md)); guest RDMA and shared-page-table flows are a known friction class, and failures are expensive to debug on hardware. A simulated peer would let the page-table contract be regression-tested early. |
| **Scope** | Does model DPU/NIC/NVMe peers enough to exercise page-table sharing and a GPUDirect-style map → peer DMA → completion path against the simulated GSP; does not implement real network/storage protocols, does not claim performance, does not modify guests. |
| **Evaluation** | Metric: peer-interaction failure classes reproduced off-hardware that matched a hardware capture. Baseline: 0. Threshold: one page-table-sharing interaction reproduced and compared against hardware. Kill: if no funded platform scenario needs it at the next review, keep it as a design note and delete the experiment scaffolding. |
| **Gates** | H2.2/H3; a funded platform use case; no confidential-compute claim; a hardware reference capture. |
| **Effort / priority** | 8+ engineering-weeks; **P4** research. |

### F11 — SIMD cores and CUDA kernel execution on device

| Field | Detail |
|---|---|
| **Status** | `research`. The native core is scalar RV64IMAC; there is no SM/SIMT or vector execution model. The product's guest-to-physical execution wiring is in progress ([`11-physical-backend-guest-wiring.md`](03-architecture/11-physical-backend-guest-wiring.md)), so command streams exist but nothing executes kernels off-hardware. |
| **Need** | Executing a real CUDA kernel against a device model would validate the command/memory path beyond copy-engine correctness and enable fail-closed testing of kernel submissions without a physical cycle. Waiting is acceptable while hardware backends exist, which is why this stays research. |
| **Scope** | Does explore a device-side execution model (SIMT/SIMD core plus memory model) able to run a minimal kernel from an emulation-produced command stream; does not claim performance or cycle accuracy, does not replace hardware for CUDA, not on the critical path. |
| **Evaluation** | Metric: vectorAdd-class kernels producing byte-identical results to a hardware reference. Baseline: 0. Threshold: one deterministic kernel correct on the simulator from an emulation-produced command stream. Kill: if the first bounded prototype cannot produce bit-identical results for a 64-element vectorAdd, stop and record why; only a funded cycle-accuracy or thesis use case may restart it. |
| **Gates** | H6/H3; a funded reason; simulator-security posture (docs/16 §16). |
| **Effort / priority** | Unbounded research; **P4**. |

### F12 — FPGA soft-processor simulation

| Field | Detail |
|---|---|
| **Status** | `planned`, far later. The H6 annex defines an RTL RV64 core with TCM/MPU/timers, falcon/CSB/ACR windows, DMA and WPR2/FWSEC state, Verilator and FPGA run modes, and a co-simulation bridge. Nothing is built or started. |
| **Need** | When a funded timing/interoperability claim appears (customer-facing timing, hardware validation of an emulated behaviour), functional models are insufficient. Until then, starting would be effort creep against the roadmap's explicit non-critical-path note. |
| **Scope** | Does build/choose an RV64 core and device fabric, pure-RTL simulation for determinism, FPGA for speed, and a `Backend` bridge so the same hooks, sessions and comparisons apply; does not claim confidentiality or isolation, does not ship, never present in a guest. |
| **Evaluation** | Metric: cycle accounting agreement between RTL and a hardware capture on a bounded scenario. Baseline: none. Threshold: one bounded scenario (e.g. mailbox round trip) cycle-accounted within a declared tolerance, or the variance fully explained. Kill: if no funded timing claim exists at the next review, keep the design annex and close the effort without building. |
| **Gates** | H2/H3 proven; validated device map; explicit funded reason; docs/16 §16 H6.3. |
| **Effort / priority** | Multi-quarter; **P4**, funded-only. |

### F13 — Verilog recreation of GSP-interacting components and the NVRISC fabric

| Field | Detail |
|---|---|
| **Status** | `research`. H6.1 names the GSP-interacting blocks, but there is no model of the NVRISC environment, interconnect ordering, interrupt fabric or doorbell/mailbox races, and no tracked public design to build one from without a provenance review. |
| **Need** | Deep timing, security and interoperability questions (interconnect ordering, boot-order races, doorbell semantics) cannot be answered by functional models; a documented recreation is the only off-hardware route to them. No funded scenario exists yet, so it is research. |
| **Scope** | Does define and build behavioural/cycle-aware RTL for GSP-interacting blocks and the NVRISC fabric environment with a declared accuracy envelope; does not reproduce secret silicon internals, does not claim confidentiality/attestation, never on the critical path. |
| **Evaluation** | Metric: interconnect-order or race observations reproduced against hardware captures within the stated envelope. Baseline: 0. Threshold: one documented race/ordering case explained and validated on hardware. Kill: if accuracy cannot be stated as a bounded envelope after the first milestone, retire to a paper design and record the decision. |
| **Gates** | F12 progress; a funded reason; legal review (tracked docs describe behaviour only). |
| **Effort / priority** | Multi-quarter research; **P4**. |

### F14 — Hidden/undocumented/unauthorized-code discovery

| Field | Detail |
|---|---|
| **Status** | `partially used`. Control discovery, reachability and seeded mutation are built and measured on the demo (injected-slot aliases, default-path `~id`, sentinel-pointer faults; [`19-CONTROL-DISCOVERY.md`](../debug/risc-v-gsp-rm-vm/docs/19-CONTROL-DISCOVERY.md)). Capability inference is designed, decoy/anti-analysis handling is unbuilt, and no real image can be swept before H2.2. |
| **Need** | Firmware is stripped and signed; new images can add handlers, re-route dispatch entries, or insert anti-analysis checks. A missed handler is a silent emulation regression, and the fail-closed rules the product needs come from error paths that only adversarial input reaches. |
| **Scope** | Does sweep inputs, classify unknown/default paths, infer capabilities from watchpoints and trace, catalogue observed anti-analysis techniques and feed fail-closed rules; does not bypass hardware protections, does not attack a live device or guest, does not publish exploit material. |
| **Evaluation** | Metric: hidden/undocumented behaviours found per image that changed a modelling or security decision. Baseline: demo findings only. Threshold: ≥1 new real-image behaviour per release that lands with a replayable probe spec and a recorded emulation/security decision. Kill: if two real-image releases yield no actionable finding, reduce to the fast CI inventory smoke and stop the broader campaign. |
| **Gates** | H1.3/H2.2; docs/14 ethics and safety rules; human review before publication. |
| **Effort / priority** | 3–5 engineering-weeks plus campaign time; **P2**. |

### F15 — SBOM/architectural understanding from observations

| Field | Detail |
|---|---|
| **Status** | `planned`. The repository has a tracked SBOM ([`SBOM.md`](../SBOM.md), CycloneDX) and the wiki GPU SBOM is superseded; there is no observation-derived inventory per firmware image that links services, symbols and dispatch tables to the SBOM and architecture docs. |
| **Need** | Version bumps change firmware components and external tooling dependencies; provenance, license and vulnerability response need to know what an image contains and what changed. The architecture docs drift from the binary until a costly re-analysis rediscovers the delta. |
| **Scope** | Does derive an observation-backed component/capability inventory per image (hashes, symbols, services, dispatch tables, external dependencies) and link it to SBOM/architecture updates; does not assert legal conclusions, does not name source locations, does not auto-publish un-reviewed findings. |
| **Evaluation** | Metric: SBOM/architecture deltas per release that are observation-derived and reviewable. Baseline: manual entries. Threshold: one release where every added/removed firmware component row carries a hash plus evidence link from a risc-v-gsp-rm-debugger session. Kill: if observation rows are rejected by SBOM review twice, drop to a provenance annex inside the session evidence. |
| **Gates** | H2.2 for real images; legal-and-licensing review ([`legal-and-licensing.md`](09-reference/legal-and-licensing.md)); provenance rules. |
| **Effort / priority** | 2–3 engineering-weeks; **P3**. |

## 4. Pruning and retirement

An item is retired at the review where its evaluation fails or its gate has
not landed for two consecutive reviews. Retirement is a recorded action, not a
silent drift:

| Outcome | Trigger | Action | Record |
|---|---|---|---|
| **Prune** | Threshold missed, or gate unlanded after two reviews, with no funded exception | Delete the code path and its tests; mark the capability `retired` here; remove it from roadmap commitments | Decision log row with date, evidence link, owner |
| **Demote** | Need is real but not now | Move the item to a research appendix; stop maintaining scaffolding; keep the design pointer | Decision log row |
| **Keep** | Evaluation passes, or a named funded exception exists | Retain with owner and next check date; state the exception's expiry | Decision log row |

No item has been retired yet (first review pending). The smallest
`built, not used yet` surface found by the tool audit (`Session.symbol_at`, an
alias with no caller) is the first prune candidate: if it still has no caller
at the first review, delete it rather than documenting API symmetry.

## 5. Review cadence

| Trigger | Who | What is re-checked |
|---|---|---|
| H2.2 exit | risc-v-gsp-rm-debugger maintainer + eng-ops owner | F5, F6, F7, F8, F14, F15 gates open; statuses move to `partially used`/`planned` execution |
| Each GSP/driver release | risc-v-gsp-rm-debugger maintainer | F1/F2/F3 chain cost, F14 findings, F15 SBOM deltas; kill criteria evaluated |
| RM 610 approval request | project lead + maintainer | F1 evidence (C4/C5), bundles for C8; no 610 input before approval |
| Quarterly | eng-ops owner | Re-run or explicitly defer every evaluation; prune/demote/keep decisions recorded in §4 |
| New funded use case | project lead | Admit a new item with the same six fields; research items become `planned` only with funding |

The doc is reviewed against the tool audit ([`27-TOOL-AUDIT.md`](../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md))
and the roadmap ([`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md))
so the "what we use now / not yet" split stays true.

<!-- change (2026-10-02): point F2–F4 at the landed docs 28/29 scaffolds so the
catalogue entries and the tree agree; scope: F2/F3/F4 status rows only;
benefit: a reader can find the pilot code and its evaluation from the catalogue
without treating it as admitted tooling. -->