docs(windows-rewrite): mark game-capture bug FIXED + bring rewrite status current (§15)

The fullscreen-game-breaks-IDD-push bug is FIXED by the resolution-listening
recovery (c87bfe0: the 250ms poll now follows the display's actual resolution
and recreates the ring on any descriptor change, recover-or-drop), backed by
open-time first-frame DDA failover (f98ab07) and the driver publish() width/
height guard + flushed logging (789ad49). No protocol bump was needed — the host
reads the real resolution straight from Windows (CCD/GDI), so the bug doc's
Stage-1 composing capturer + Stage-2 protocol bump were unnecessary. Bug doc
marked FIXED with a Resolution section; the staged plan kept as superseded record.

windows-host-rewrite.md: the progress log was stale (ended at "M1 cont."). Added
§15 Current status — the driver STEP 0-8 port landed on main on-glass HDR-
validated; the host was refactored *in place* via windows-host-goal1 (not the §10
greenfield rebuild); §2.5 ownership model resolved the swap-chain-reuse / monitor-
leak open item; iddcx + /INTEGRITYCHECK CI-green. Remaining: the secure-desktop
on-glass gate (the single biggest unproven claim), M4 gamepad-driver migration,
M5/M6 cleanup, and the pf-vdisplay slot-reclaim driver fix. Top Status flipped
proposed → largely implemented.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-25 21:35:55 +00:00
parent bf57aa4000
commit 48202a0f89
2 changed files with 321 additions and 4 deletions
+61 -4
View File
@@ -1,9 +1,11 @@
# Windows Host Rewrite — Design & Plan
Status: **proposed** (2026-06-24). This plan takes the current, hard-won Windows host (pf-vdisplay
all-Rust IddCx driver + IDD-push zero-copy capture, live-validated 5120×1440@240 HDR on the RTX box)
as a *knowledge base* and re-derives a clean, stable, well-layered architecture from it. It drops all
SudoVDA back-compat (we own both ends now) and drives `unsafe` to a contained minimum.
Status: **largely implemented** (updated 2026-06-25 — see [§15 Current status](#15-current-status-2026-06-25)
for the milestone-by-milestone state; §0–§14 below are the original design and remain the reference). This
plan takes the current, hard-won Windows host (pf-vdisplay all-Rust IddCx driver + IDD-push zero-copy
capture, live-validated 5120×1440@240 HDR on the RTX box) as a *knowledge base* and re-derives a clean,
stable, well-layered architecture from it. It drops all SudoVDA back-compat (we own both ends now) and
drives `unsafe` to a contained minimum.
It supersedes the stale conclusion in `docs/windows-virtual-display-rust-port.md` ("IDD-push not
viable") — that verdict was written in the *same commit* (`e2c9bfd`) that shipped the working
@@ -778,3 +780,58 @@ IddPushCapturer captures the lock/UAC secure desktop directly (IDD-push is opt-i
`PUNKTFUNK_IDD_PUSH`). Make it a blocking on-glass gate (step 6) and keep the WGC relay recoverable for one
release. Other defined-failure-branch items: monitor `EvtCleanupCallback` firing, IDD_PERSIST/Reconfigure,
concurrent-monitor device sharing, host↔driver `protocol_version` lockstep.
---
## 15. Current status (2026-06-25)
The rewrite is **largely implemented**. The new all-Rust `pf-vdisplay` driver (the M0 long pole — `iddcx`
on `windows-drivers-rs` + `/INTEGRITYCHECK` — and the §14 STEP 08 port) **landed on `main`, on-glass HDR
validated**, and the host was decomposed into the clean layered architecture. One important deviation from
the plan: **the host was refactored *in place* via a staged, behavior-preserving plan
([`windows-host-goal1-plan.md`](windows-host-goal1-plan.md)), not greenfield-rebuilt** — the §10 "rebuild
fresh, keep old as reference" framing was superseded because staging preserved the live-validated host at
every step (lower regression risk than a big-bang M2 rebuild). The §2.3/§2.4/§2.5 design (seam traits,
`SessionPlan`/`SessionFactory`/`SessionContext`, the `VirtualDisplayManager` ownership model) is realized in
that branch's commits, not the M2 greenfield tree the build order imagined.
### Milestone / step status
| Item | Status | Evidence |
|---|---|---|
| **M0** — proto crate, driver workspace, `iddcx` binding, `/INTEGRITYCHECK` | ✅ **DONE** | `pf-vdisplay-proto`; `packaging/windows/drivers/`; `clear-force-integrity.ps1`; CI-green (§13) |
| **§14 STEP 08** — pf-vdisplay driver port (device→adapter→control→swap-chain→frame transport→HDR→.inx→unsafe pass) | ✅ **DONE** | `d7a9fbf``cd59151`; on-glass HDR (`6399d28`: "Mac connects WITH HDR") |
| **M1/M2** — IDD-push capture + NVENC glass-to-glass | ✅ **DONE** | new driver tree + the existing host IDD-push path; 5K@240 HDR zero-copy on-glass |
| **§2.5** — ownership-model rewrite (`VirtualDisplayManager`/`MonitorLease`); swap-chain-reuse / monitor-leak | ✅ **DONE / RESOLVED** | `windows-host-goal1` §2.5 (`1520201``683c81b`); reconnect-leak A/B: 0 leaked monitors |
| **Goal-1 host refactor** (the in-place §2.22.5 realization, incl. `EncoderCaps`) | ✅ **DONE** | `windows-host-goal1` branch — all 6 stages + §2.5 + 3 seam tightenings |
| **Game-capture bug (GB1)** — fullscreen game breaks IDD-push | ✅ **FIXED** | `c87bfe0`/`f98ab07`/`789ad49`; see [game-capture-bug.md](windows-host-rewrite-game-capture-bug.md) |
| **M3** — service / input / audio cleanup | 🟡 code present (largely via the existing host + goal1) | — |
| **M4** — gamepad drivers (`pf_dualsense`/`pf_xusb`) onto the unified stack, WDF device contexts (true multi-pad) | ❌ **NOT STARTED** | old gamepad-driver crates still separate |
| **M5** — demoted WGC/DDA fallback port + GameStream-on-`session/pipeline` + AMF/QSV (no hw) | 🟡 **PARTIAL** | fallbacks exist; not re-shaped onto the new seams |
| **M6** — cut over + delete the old monoliths | 🟡 **PARTIAL** | old `vdisplay-driver/` tree deleted (`a2bd0cd`); host monoliths remain |
### What genuinely remains
1. **Secure-desktop on-glass gate (the single biggest open risk, §14 STEP 6 critique).** IDD-push capturing
the lock screen / UAC with `serve` in the console session is **asserted, not yet locked on glass**. Until
it passes, keep the WGC-relay / secure-DDA path recoverable. Hardware-gated (RTX box; ephemeral).
2. **M4 — gamepad-driver migration** onto `windows-drivers-rs` (WDF device contexts → true multi-pad). The
proven recipe exists; ~23 days, hardware-gated.
3. **M5/M6 cleanup** — re-shape the WGC/DDA fallback + GameStream onto `session/pipeline`, then delete the
old Windows monoliths. Low priority; AMF/QSV stays CI-only (no lab hw).
4. **pf-vdisplay driver slot reclaim** — sustained ADD/REMOVE churn wedges the driver (`ADD →
0x80070490 ERROR_NOT_FOUND`): it doesn't reclaim IddCx monitor slots on REMOVE (ghost nodes accumulate).
Recovery today is `packaging/windows/reset-pf-vdisplay.ps1`; the real fix is in the driver
(`control.rs`/`adapter.rs`). Dev helpers `reset-pf-vdisplay.ps1` + `redeploy-pf-vdisplay.ps1` are committed.
### Resolved since the original §11 open items
- **Driver swap-chain reuse** — the clean ownership model (`EvtCleanupCallback` + DeviceContext-owned state +
single `Monitor` identity) is in; §2.5's reconnect-leak A/B shows **0 leaked active monitors**. The
per-frame `CURRENT_MON_GEN` "monitor-gen bail" turned out to have been **write-only** (never wired), so the
"carry the gen through `WinCaptureTarget`" item was dropped; the gen lives on the manager + lease only.
- **`/INTEGRITYCHECK` + `iddcx` on `wdk-sys`** — both proven CI-green (§13).
Box reminder: the RTX box (`ssh "Enrico Bühler"@…`) is **ephemeral** (boots to Proxmox on reboot; IP floats
on DHCP — has been `.173`/`.158`); the windows-amd64 CI runner is the persistent validator. On-glass gates
are opportunistic.