# Project Plan

> **Scope.** The sequence of work: the phases, the gates that close them, what
> comes next, and how the plan itself is maintained. This is the *roadmap*
> view — [`Project-Goals.md`](Project-Goals.md) says what the project is for,
> [`Project-Status.md`](Project-Status.md) says where it stands today, and this
> page says in what order the remaining work happens and what must be true
> before each step. Canonical sources: the compute milestone ladder in
> [`../docs/04-implementation/03-execution-frontier.md`](../docs/04-implementation/03-execution-frontier.md),
> the graphics ladder in
> [`../docs/04-implementation/05-graphics-execution-plan.md`](../docs/04-implementation/05-graphics-execution-plan.md),
> the five-rung evaluation ladder in
> [`../docs/05-operations/01-performance-correctness-security.md`](../docs/05-operations/01-performance-correctness-security.md),
> and the porting sequence in
> [`../docs/06-portability/03-device-validation-and-porting-sequence.md`](../docs/06-portability/03-device-validation-and-porting-sequence.md);
> the docs tree wins on disagreement.

Status: 2026-10-30, tree `master @ b4930168`. Tags: `[done]`, `[active]`,
`[ahead]` — the plan's own state vocabulary, distinct from the goal tags.

## 1. How the plan works

Five rules shape every phase below, and they are the project's contract with
itself:

1. **Every milestone has a gate and an acceptance signal, named before the
   work starts.** A wall is closed only by its acceptance signal — not by an
   intention, a decompiler reading, or a lucky run.
2. **The evaluation ladder is the spine.** A platform advances
   initialization → runtime start → execution → sustained → multi-tenant, and
   nothing claims a rung it has not reached and reproduced.
3. **Correctness before speed; no number without methodology.** Performance
   claims carry their harness, versions and A/B baseline.
4. **Default-off until validated.** New mechanisms land behind parameters
   (the forwarding and graphics seams today) and graduate only after their
   gate passes; graduation replaces the knob with documented configuration.
5. **No patches anywhere, and profiles over rewrites.** Guest drivers, host
   drivers, firmware and hypervisors stay stock; a new driver, firmware or GPU
   enters the plan as a *profile plus a measured delta*.

## 2. The phases

| Phase | What it delivers | Exit gate | State (2026-10-30) |
|---|---|---|---|
| **P0 — Platform** | Emulated vGPU device, GSP boot and GSP-RM emulation, stock guest driver initialisation | Driver-API smoke green (`ALL OK`) = evaluation rung 2 | `[done]` |
| **P1 — First execution (compute)** | Guest CUDA kernels executing on the physical GPU, with engine-authored completions; then hardening | Verified clients + engine-authored completion = rung 3 core; hardening: staged-transfer class, every-boot acceptance, per-guest isolation | `[active]` — execution green; hardening in progress |
| **P2 — Graphics execution** | OpenGL/Vulkan draw commands executed by the physical 3D pipeline and delivered as readable pixels | The graphics ladder: M-GL1 client context-init executes; M-GL2 `glxgears` non-black; M-GL3 GZDoom GL non-black through the mdev | `[active]` — between M-GL1 and M-GL2; the pixel walls are named |
| **P3 — Sustained and multi-tenant** | Frame rates without assistance; multiple VMs sharing the GPU with measured fairness; soak-stable operation | Graphics M-GL4 (60 fps, no forcing) and M-GL5 (two VMs, two mdevs); CUDA battery + soak; per-guest execution isolation = rungs 4/5 | `[ahead]` |
| **P4 — Breadth** | Video (NVENC/NVDEC), Windows/DirectX guests, live migration, non-KVM hypervisor transports | Per-case bring-up gates plus the matrix's evidence expectations | `[ahead]` |
| **P5 — Scale and portability** | New GPU generations and driver families carried forward; published performance programme | A profile + measured delta per version, validated on hardware; A/B numbers published per the measurement contract | `[ahead]` |

The phases overlap on purpose: the graphics workstream is what unblocks P3's
first exit gate, and portability work starts from whichever hardware becomes
available (P5 runs across the whole plan).

## 3. Where the plan stands, and what is next

Ranked, in dependency order:

1. **Graphics pixels (P2).** Three walls, each with a named next fix: the GL
   client's submissions; program (SASS) delivery plus program-VA mapping; then
   non-black frames. Full detail:
   [`Graphics-Execution.md`](Graphics-Execution.md) §6.
2. **Compute hardening (P1).** The staged-transfer class (failure modes proven,
   fixes in flight); the every-boot acceptance campaign; per-guest execution
   isolation. Detail:
   [`Execution-Frontier.md`](Execution-Frontier.md).
3. **The visible sequence after these**: first non-black frame → 60 fps in one
   VM with no forcing → two VMs on two mdevs → the CUDA battery 15/15 plus a
   soak → video → Windows.
4. **Then P4/P5 row by row**: each item ships with its own gate, profile and
   evidence, and only then moves in the matrix.

Recently closed, as evidence the gates work: the boot-poisoning defect and the
post-reboot client-stall defect (compute reproducibility); the X/GL wall (the
X server and GLX run on the emulated vGPU); the engine executing the real GL
method stream; and the guest Vulkan pipeline running end to end.

## 4. The gates

Each gate's full text lives in its canonical document; this is the map:

| Gate | What must be true | Where it is defined |
|---|---|---|
| **Rung gate** | The previous rung is green and reproducible for this platform before the next is claimed | Evaluation ladder |
| **Execution gate** | Engine-authored release plus verified guest results, reproduced across fresh boots | Execution frontier |
| **Graphics gate** | Milestone definitions: capture shows motion, no forcing, no diagnostic mirror, renderer is the NVIDIA driver | Graphics plan (§C) |
| **Performance gate** | A/B ratios from the published harness; no absolute numbers; variance and run counts reported | Measurement contract |
| **Portability gate** | Profile fields recorded, firmware/device pairing hashed, first-touch differences explained, supervised physical validation done | Porting sequence + matrix |
| **Isolation gate** | Fail-closed enforcement; fairness measured before any multi-tenant claim | Security document |
| **Security gate** | Adversarial review before multi-tenant or production claims | Security document |

## 5. Workstreams (always on)

| Workstream | What it does | Entry point |
|---|---|---|
| Correctness and acceptance | The regression battery, battery-first ordering, regression gates | [`Execution-Frontier.md`](Execution-Frontier.md) |
| Graphics execution | The execution lanes, capture/decode, the M-GL ladder | [`Graphics-Execution.md`](Graphics-Execution.md) |
| Performance measurement | Microbenchmarks first, then the A/B corpus, then structural optimisation | [`Performance.md`](Performance.md) |
| Portability and versions | Profiles, measured deltas, the validation sequence; new driver/firmware families behind a review gate | [`Hardware-Software-Matrix.md`](Hardware-Software-Matrix.md) |
| Developer tooling | The firmware workbench: recorded sessions as evidence, offline-first investigation of walls | [`Riscv-GSP-RM-Debugger.md`](Riscv-GSP-RM-Debugger.md) |
| Security and isolation | Threat model, audits, fail-closed posture | [`../docs/05-operations/01-performance-correctness-security.md`](../docs/05-operations/01-performance-correctness-security.md) |
| Documentation and evidence | Docs tree canonical; dated status; replayable evidence for every claim | [`../docs/README.md`](../docs/README.md) |

## 6. Contributing to the plan

* **The unit of contribution is a profile plus evidence**, evaluated through
  the five-rung ladder — see "Adding a new combination" in
  [`Hardware-Software-Matrix.md`](Hardware-Software-Matrix.md) and the porting
  sequence document.
* **Nasty bugs** (non-reproducible, cross-subsystem, blocking a gate) get a
  tracked issue in the repository; ordinary work stays in the live handoffs.
* **Support claims** are made only by recording hardware + driver + firmware +
  rung + date in the matrix with the evidence bundle behind them.

## 7. How this plan is maintained

The plan is a living sequence, not a dated roadmap: each milestone's gate is
owned by its canonical document, the current state is tracked on
[`Project-Status.md`](Project-Status.md), and the plan changes only when a gate
is named and its evidence rules are written down. When a wall closes, the
canonical doc is updated first and the site pages follow on the next refresh.

## 8. Related pages

* [`Project-Goals.md`](Project-Goals.md) — the goals and their status.
* [`Project-Status.md`](Project-Status.md) — the dated milestone ladder.
* [`Execution-Frontier.md`](Execution-Frontier.md) — the compute frontier and
  its gates.
* [`Graphics-Execution.md`](Graphics-Execution.md) — the graphics frontier and
  the M-GL ladder.
* [`Performance.md`](Performance.md) — the measurement programme.
* [`Hardware-Software-Matrix.md`](Hardware-Software-Matrix.md) — the
  portability plan and support ladder.
* [`../docs/README.md`](../docs/README.md) — the documentation front door and
  the project's own status table.