punktfunk/design/windows-host-rewrite.md

Windows Host — Architecture, Status & Roadmap

Single source of truth for the punktfunk Windows streaming host: the all-Rust pf-vdisplay IddCx virtual-display driver + IDD-push zero-copy capture + NVENC/AMF/QSV encode, shipped as a signed Inno Setup installer with a LocalSystem SCM service. Live-validated on the RTX box through 5120×1440@240 HDR, the secure desktop (lock/UAC), and a fullscreen game.

This file is the consolidated Windows-host doc — it absorbs the rewrite design plan, the Goal-1 staged-refactor plan, the audit + remediation tracker, the fullscreen-game capture-bug analysis, and the durable rationale from the original windows-host.md implementation plan (now a stub). Last updated 2026-06-26. All of this work is merged to main (the windows-host-goal1 branch landed at 3e7c9bd).

---

1. Status at a glance

Goals 1–3 and milestones M0–M4 are complete and merged to main. The host has a clean, typed, layered architecture (HostConfig → SessionPlan → SessionContext, windows/+linux/ confinement, a single VirtualDisplayManager ownership model, EncoderCaps); the all-Rust IddCx pf-vdisplay driver loads self-signed under Secure Boot and does IDD-push zero-copy capture at 5K@240 HDR including the secure desktop (Winlogon/UAC/lock); SudoVDA is gone (84a3b95) — pf-vdisplay is the sole virtual-display backend; and the three UMDF drivers (pf-vdisplay, pf-dualsense, pf-xusb) now build from source in one unified packaging/windows/drivers/ workspace (M4, 92e6802). The shipped path (IDD-push + NVENC) is live-validated on glass; the AMF/QSV encode path is CI-green but not yet on-hardware (no AMD/Intel Windows box in the lab).

Ground the details against the code: crates/punktfunk-host/src/windows/, crates/punktfunk-host/src/{capture,encode,inject,audio,vdisplay}/windows/, and packaging/windows/drivers/.

What remains (all non-blocking): the pf-vdisplay slot-reclaim-on-REMOVE fix needs an on-glass reconnect-storm A/B (§4 P1.3); host-crate unsafe lint hygiene + old-monolith / bring-up-scaffolding cleanup (§4 P2); and the hardware-gated items — AMF/QSV on-glass, hybrid-GPU SET_RENDER_ADAPTER, the WGC/DDA fallback reshape, and true max_concurrent>1 (§4 P3). One framing note: the host was not greenfield-rebuilt — it was refactored in place via a staged, behavior-preserving sequence that kept the live host working at every step; only the driver was rebuilt fresh.

---

2. Architecture (what is on disk)

A ~1-page map; the empirical constraints these encode are in §3, the deep reference is in §6.

2.1 Layering & crates

• crates/punktfunk-host — one shared host crate (Linux + Windows; not split). Platform code is confined under per-module windows/+linux/ folders behind #[cfg] seams (capture/{windows,linux}/, encode/…, inject/…, audio/…, vdisplay/…, plus top-level src/windows/+src/linux/). Module names stay flat (#[path]), so caller paths are platform-agnostic.
• crates/punktfunk-core — the one linked protocol/FEC/crypto/QUIC core (unchanged here).
• crates/pf-driver-proto — the owned, no_std host↔driver ABI (frame ring + control plane + gamepad SHM), consumed by both the host crate and the driver workspace.
• packaging/windows/drivers/ — the unified driver workspace on microsoft/windows-drivers-rs (vendored 0.5.1 + an iddcx subset): pf-vdisplay (the IddCx display driver), pf-dualsense + pf-xusb (the gamepad drivers, folded in by M4), wdk-iddcx (typed IddCx DDI wrappers), wdk-probe (the CI link/surface gate), vendor/{wdk-build,wdk-sys}.

2.2 Session resolution, ownership, and seam traits (Goal-1)

The old ~40-knob PUNKTFUNK_* env soup (re-read and recomputed in three places) is replaced by a resolve-once pipeline: config.rs HostConfig (typed, parsed once) → session_plan.rs SessionPlan (a Copy plan resolved once per session — CaptureBackend::resolve() picks IddPush | Dda | Wgc, resolve_topology picks SingleProcess | TwoProcessRelay; this killed the latent capture/encode backend-disagreement bug) → SessionContext (bundles the ~13 session args + plane receivers, moved into the stream thread).

Ownership is a single OnceLock VirtualDisplayManager (vdisplay/windows/manager.rs) owning a typed Arc<OwnedHandle> control-device handle (no raw-isize cross-thread smuggle), a refcounted Idle/Active/Lingering state machine, and the monitor generation; a per-session MonitorLease's Drop releases the refcount (a stale lease can't tear down a fresh monitor). This deleted a fistful of CURRENT_MON_GEN/MGR/IDD_* globals and validated on glass at 0 leaked monitors across a reconnect storm, A/B-equivalent to the shipping host.

The seam traits (VirtualDisplay/VirtualOutput/VirtualLease, Capturer, Encoder, AudioCapturer/VirtualMic/InputInjector/PadManager) got two tightenings: the capturer takes the desired OutputFormat { gpu, hdr } in (killing the capture → encode::windows_resolved_backend() back-reference), and Encoder::caps() -> EncoderCaps (§2.4) lets the session glue route loss-recovery by query.

2.3 Capture — IDD-push primary (normal and secure desktop), WGC/DDA fallback, GB1 recovery

IDD-push is the universal primary path. Capture comes straight from the driver's shared keyed-mutex texture ring (capture/windows/idd_push.rs) — no Desktop Duplication, no win32u reparenting hook. The host creates the ring; the driver opens it (permissive D:(A;;GA;;;WD) SDDL). The generation-tagged latest = gen<<40 | seq<<8 | slot stale-ring reject kills the HDR-flip garbage frame; a host-owned 3-slot OUT_RING rotated per frame is the texture-ownership contract that enables pipeline_depth=2 (convert/copy on the 3D engine overlapping NVENC on the ASIC). It captures the secure desktop (Winlogon/UAC/lock) directly (validated 2026-06-25), so there is no separate secure capturer in the primary path.

• Open-time fallback: IddPushCapturer::open waits a bounded ~4 s for a first frame (not just DRV_STATUS_OPENED); on attach failure it returns the keepalive back so capture.rs opens DDA on the same WinCaptureTarget — never a 20 s black bail (ed58365/f98ab07).
• Mid-session game mode-set recovery (GB1, fixed): the 250 ms poll follows the display's actual resolution (win_display::active_resolution, CCD/GDI) and recreates the ring on any descriptor change (size or HDR) → the driver re-attaches → frames resume at the game's mode, no reconnect. If a change is unrecoverable (e.g. an exclusive flip), a recovering_since clock drops the session after 3 s so the client reconnects cleanly. No protocol bump was needed — the host reads the resolution straight from Windows (c87bfe0; the driver's publish() width/height guard + flushed log is 789ad49).
• WGC + DDA stay as demoted fallbacks for non-IddCx hardware (wgc.rs/dxgi.rs). The two-process WGC secure-desktop relay (wgc_relay.rs) is no longer load-bearing now that IDD-push handles the secure desktop; it is kept recoverable but slated for M5/M6 cleanup. (Its constraint analysis is archived in archive/windows-secure-desktop.md.)

2.4 Encode — NVENC / AMF / QSV / software; EncoderCaps; HDR

encode/windows/ dispatches per DXGI adapter vendor (open_video): NVENC (NVIDIA, direct SDK, nvenc.rs — caps-probe-before-configure, bitrate-clamp binary search, true RFI over the DPB, in-band ST.2086/CLL SEI), AMF/QSV (AMD/Intel via libavcodec, ffmpeg_win.rs — system-readback default, opt-in zero-copy D3D11; CI-only, no lab hardware), or software H.264 (sw.rs). HDR (10-bit) forces HEVC Main10 + BT.2020 PQ; the client auto-detects PQ from the VUI. The encoder adapts to a mid-session size/format/HDR change per frame (tears down + re-inits), so the GB1 capturer's resolution changes are handled downstream with no API change.

Encoder::caps() -> EncoderCaps { supports_rfi, supports_hdr_metadata } lets the session glue route loss-recovery by query (only Windows direct-NVENC overrides it; the GameStream loop gates the RFI path on supports_rfi rather than hard-coding per-backend knowledge into the glue).

2.5 Host↔driver ABI & the pf-vdisplay driver

pf-driver-proto is one no_std crate in both build graphs. It owns the frame plane (FrameToken

• Global\pfvd-* names), the control plane (a fresh interface GUID — not SudoVDA's e5bcc234; contiguous 0x900 IOCTL ops; a GET_INFO version handshake the host asserts + bails on mismatch), and the gamepad SHM (XusbShm/PadShm incl. device_type). bytemuck-Pod + size_of and offset_of! asserts make ABI drift a compile error.

The driver (packaging/windows/drivers/pf-vdisplay/src/) is an all-Rust UMDF IddCx driver on windows-drivers-rs + the iddcx wdk-sys subset; the STEP 0–8 build is the checklist in §6.3, its internals are the invariants in §3, and it loads self-signed under Secure Boot (FORCE_INTEGRITY cleared post-link, §6.1). Known gaps: ownership state is still partly process-global with EvtCleanupCallback on the WDFDEVICE (a deliberate, sound choice — E1 in §4); and slot-reclaim-on-REMOVE (§4 P1.3).

2.6 Service, packaging, installer

A LocalSystem SCM supervisor (windows/service.rs) token-retargets and CreateProcessAsUserWs serve into the console session (so SendInput reaches both the streamed and the secure desktop), relaunches on session-change, and kills-on-close via a Job Object — the Sunshine/Apollo model (rationale: windows-service.md). Shipped as a signed Inno Setup setup.exe (packaging/windows/, windows-host.yml) that builds + signs all three drivers from source, bundles them + the FFmpeg DLLs, and delegates to service install. GameStream (Moonlight) is kept, but the installer/service default to secure serve (GameStream opt-in).

---

3. Validated invariants — preserve, do not regress

These are expensive empirical wins; keep them intact when touching the code:

• Frame transport: host-creates/driver-opens keyed-mutex ring; generation-tagged stale-ring reject; 0 ms try-acquire / drop-on-full publish (never block the swap-chain thread); the OUT_RING rotation + pipeline_depth=2 overlap; repeat_last rotates into a fresh out-ring slot (depth-safe).
• Driver internals: edid.rs (128-byte EDID + CTA-861.3 HDR block, dual checksums); the FP16 HDR recipe (CAN_PROCESS_FP16 + the *2 DDIs + gamma/HDR accept-stubs + HIGH_COLOR_SPACE); DEVICE_POOL per render-LUID (NVIDIA UMD/VRAM leak fix); target-id stamped on the monitor context; the two swap-chain leak fixes (borrow IDXGIDevice across SetDevice retries; check terminate at the loop top).
• Monitor lifecycle: serialized ADD/REMOVE/teardown; restore CCD topology before REMOVE; the generation-stamped lease (a stale lease can't tear down a fresh monitor); 0-leak across reconnects.
• HDR color math: hdr.rs (pure, unit-tested, ST.2086 + big-endian SEI); the FP16→P010/Rgb10a2 converters + hdr_p010_selftest; the cursor decomposition.
• NVENC tuning: caps-probe-before-configure (10-bit→8-bit graceful downgrade); bitrate-clamp binary search (each GPU's real ceiling); true RFI over the DPB; CBR / infinite-GOP / P-only / ~1-frame VBV.
• Gamepad recipe: the SwDeviceCreate identity (enumerator with no _; mandatory completion callback; synthesized DS5 compat-ids; non-null per-pad ContainerId); one pf_dualsense serving DualSense+DS4 via a device_type byte; XUSB declining WAIT_*; per-pad index via pszDeviceLocation.
• Session glue: the trait seam + RAII keepalive teardown; host-lifetime shared services + per-session gamepads; the encode|send split + microburst pacing; build_pipeline_with_retry permanent-vs-transient classification; the GameStream VideoPacketizer (GF8 Cauchy, Moonlight byte-exact); the pairing/trust handshake.
• Core discipline: no async on the per-frame path; pf-driver-proto is the single ABI source (drift = compile error); the version handshake the host asserts.

---

4. Open work / next tasks (prioritized)

P1 — ship-readiness / correctness

1. Goal-1 → main merge — ✅ DONE. The windows-host-goal1 branch is merged (tip 3e7c9bd); the full Windows CI matrix (incl. the amf-qsv encode path that local checks skip) runs on push.
2. IDD-push default — ✅ resolved via host.env. The shipped default host.env sets PUNKTFUNK_IDD_PUSH=1, so a fresh install runs the validated IDD-push path (with the WGC/DDA fallback in place). The bare in-code default (config.rs) is still false (the dev / non-pf-driver default); flipping it to follow the deployed default is an optional tidy.
3. pf-vdisplay slot reclaim on REMOVE (driver robustness) — 🟡 fix landed, on-glass-validation pending. Sustained ADD/REMOVE churn wedged the driver (ADD → 0x80070490 ERROR_NOT_FOUND) because the monitor id (EDID serial / ConnectorIndex / container GUID) was a monotonic NEXT_ID, never reclaimed → IddCx accumulated a new OS target slot per cycle until exhaustion. monitor.rs now allocates the lowest free id (alloc_monitor_id), reused on REMOVE, so a fresh ADD reuses the departed monitor's target slot instead of orphaning it. CI-compile-gated; the wedge only reproduces under sustained churn on the RTX box, so this needs an on-glass reconnect-storm A/B to confirm (the box is ephemeral). Keep packaging/windows/reset-pf-vdisplay.ps1 as the recovery until validated.

P2 — hygiene / architecture completion 4. D1-host — host-crate P0 lints — deferred (low value / high churn). A crate-wide #![deny(unsafe_op_in_unsafe_fn)] produced 100+ FFI-wrap sites across the Linux modules; it wraps unsafe (discipline) rather than reducing it and doesn't improve stability, so it was deprioritized vs the OwnedHandle/RAII reductions (which are complete — idd_push.rs, service.rs, the three gamepad backends via a shared gamepad_raii.rs, the SCM STOP/SESSION events as OnceLock<OwnedHandle>, the hot-loop KeyedMutexGuard, and the driver's pod_init!; all box-validated, clean sc stop in ~1 s). The driver already has the deny. Revisit D1-host as a final discipline pass (staged per-module) if desired. 5. M6 scaffolding cleanup — delete the bring-up diagnostics (spawn_observer/DebugBlock in idd_push.rs) and, once full parity is proven on glass, the host monoliths.

Explicitly NOT doing (stability decision): E1 — driver DeviceContext ownership + per-IDDCX_MONITOR EvtCleanupCallback. The current process-global design is sound: IddCx DDIs receive only an IDDCX_MONITOR handle (never the WDFDEVICE/context), and ProcessSharingDisabled makes one devnode = one host process that dies with the device. A "device-owned" variant would add a use-after-free window (the watchdog races device cleanup) for no gain, and the per-monitor cleanup callback isn't reliably reachable on this UMDF/IddCx stack. Cleanup is already deterministic (WDFDEVICE EvtCleanupCallback + cleanup_for_device_removal + the host-gone watchdog). Revisit only if max_concurrent>1 on Windows is actually needed. (monitor.rs documents this rationale at the MONITOR_MODES static.)

P3 — larger, mostly hardware-gated 6. M4 — gamepad-driver unification — ✅ substantially DONE (92e6802). pf-dualsense (DualSense / DualShock 4) and pf-xusb (Xbox 360 / XInput) now live in the unified packaging/windows/drivers/ workspace and build from source per release against the vendored wdk-sys, exactly like pf-vdisplay; build-gamepad-drivers.ps1 signs them with the shared cert. Remaining: point the driver side at pf_driver_proto::gamepad::{PadShm,XusbShm} (the host side already does — the device_type-at-offset hand-duplication is the last ABI-drift hazard), add WDF device contexts for true multi-pad, and confirm the source build matches the prior shipped binaries. 7. M5 — reshape WGC/DDA + GameStream onto session/pipeline, then delete the old relay/monoliths. AMF/QSV stays CI-only (no lab hardware). 8. On-glass behavioral validation of the committed-but-unexercised fixes: the watchdog reaping on host-kill, SET_RENDER_ADAPTER on a hybrid box (the lab box is single-dGPU), the IDD-push→DDA fallback trigger, HDR-ring sizing + out-ring repeat under real HDR/static-desktop pipelining, and the AMF/QSV encode path on real AMD/Intel hardware.

---

5. Operations

5.1 RTX box on-glass recipe

The persistent on-glass validator is the RTX box (ssh "Enrico Bühler"@<ip>, ENRICOS-DESKTOP, RTX 4090, PS shell). The IP FLOATS (DHCP; boots to Proxmox on reboot → ephemeral, unreachable after a reboot; recently .173/.158 — confirm current first; never reboot it, never depend on it surviving). It has WDK 26100 + LLVM 21.1.2 + the Rust toolchain; build clone at C:\Users\Public\pf-rewrite (the user's active driver-dev tree — don't clobber uncommitted WIP; use a worktree). Username has a ü → quote it; it only breaks SDL3/client builds, not the host. To validate a host branch: worktree-checkout, build with CARGO_TARGET_DIR=C:\t-goal1, then stop the PunktfunkHost service, back up the binary + %ProgramData%\punktfunk\host.env, copy your build in, restart, drive punktfunk-probe.exe loopback, then restore + git worktree remove. Drive over ssh via powershell -EncodedCommand <base64 UTF-16LE> (plain quoting mangles; prefer Write-Output/file-redirect for clean output). Driver redeploy: packaging/windows/redeploy-pf-vdisplay.ps1; ghost-monitor recovery: reset-pf-vdisplay.ps1.

5.2 CI / validation

The persistent build validator is the windows-amd64 CI runner (no GPU — fine for builds / iddcx link / /INTEGRITYCHECK self-sign / the surface-asserts; live NVENC encode + on-glass defers to the RTX box). Workflows: windows-host.yml (the host installer), windows-drivers.yml (the driver workspace build + FORCE_INTEGRITY clear), windows-drivers-provision.yml (WDK/LLVM toolchain), windows-msix.yml (the client). A single Windows runner serializes the whole fleet; a Cargo.toml touch costs ~25 min of queue, so driver pushes that avoid Cargo.toml skip the fleet serialization.

Local pre-push checks (this Linux box can't compile the Windows paths):

cargo test  -p pf-driver-proto                 # the ABI crate (cross-platform)
cargo check -p punktfunk-host                     # Linux paths; win_* mods are #[cfg(windows)]
cargo clippy -p punktfunk-host --all-targets -- -D warnings
# Windows host clippy (on the box): PUNKTFUNK_NVENC_LIB_DIR=C:\t\nvenc;
#   cargo clippy -p punktfunk-host --features nvenc --target x86_64-pc-windows-msvc -- -D warnings
# Driver build (on the box): cd packaging/windows/drivers; Version_Number=10.0.26100.0;
#   LIBCLANG_PATH='C:\Program Files\LLVM\bin'; cargo build

Note: a pre-existing rustfmt-version drift exists in some Windows-only files (this box's rustfmt 1.9.0 wraps offset_of!/unsafe fn differently than the runner's) — don't reformat unrelated files to chase it.

5.3 Env knobs (Windows host)

PUNKTFUNK_IDD_PUSH=1 (capture from the driver ring; shipped host.env default on, in-code default off), PUNKTFUNK_ENCODER=auto|nvenc (auto → vendor-detect), PUNKTFUNK_10BIT=1 + PUNKTFUNK_HDR_SHADER_P010=1 (HDR), PUNKTFUNK_SECURE_DDA=1, PUNKTFUNK_NO_WGC=1 (pure DDA), PUNKTFUNK_ZEROCOPY=1, PUNKTFUNK_MONITOR_LINGER_MS, PFVD_DEBUG_LOG=1 (driver file log — release builds are silent without it). Config lives in %ProgramData%\punktfunk\host.env; logs in %ProgramData%\punktfunk\logs\host.log.

5.4 Build / deploy / packaging

x64-only by design (no ARM64 NVIDIA driver). The installer is the thin-.iss / fat-binary model delegating to service install; tag host-win-vX.Y.Z. The drivers are built + FORCE_INTEGRITY-cleared + signed + Inf2Cat'd in CI from source. DriverVer must bump on any driver change; create the ROOT devnode via nefcon (devgen is forbidden).

---

6. Reference (hard-won — keep)

6.1 The /INTEGRITYCHECK answer

wdk-build emits cargo::rustc-cdylib-link-arg=/INTEGRITYCHECK unconditionally (no cfg/env/Config opt-out), so a self-signed driver can't load (CodeIntegrity 3004/3089). The fix: a deterministic, idempotent post-link step packaging/windows/clear-force-integrity.ps1 clears the PE FORCE_INTEGRITY bit (0x0080 @ e_lfanew+0x5e) + verifies (CI-proven 0x01E0 → 0x0160), before signing. Packaging order: cargo build → clear-force-integrity → sign .dll → Inf2Cat → sign .cat. (A public build would use real attestation signing, which satisfies /INTEGRITYCHECK legitimately.)

6.2 The iddcx binding on wdk-sys (the make-or-break — proven, the 6 bindgen knobs)

IddCx DDIs are function-table dispatched (IddFunctions[] indexed by _IDDFUNCENUM::<Name>TableIndex, IddDriverGlobals implicit arg 1) — the same model wdk-sys already implements for WDF. The vendored windows-drivers-rs 0.5.1 (packaging/windows/drivers/vendor/, [patch.crates-io]'d) gets a first-class ApiSubset::Iddcx that bindgens iddcx/1.10/IddCx.h reusing the identical wdk_default(config) baseline (so WDF/DXGI types resolve to, not redefine, wdk-sys's — type-identity by construction). The six knobs generate_iddcx needed (each a real gotcha, all CI-proven):

1. --language=c++ — wdk_default parses C; IddCx.h's IDARG_* typedefs need C++ (else a "must use 'struct' tag" cascade).
2. -DIDD_STUB — table-dispatch mode; skips IddCxFuncEnum.h's #error IDDCX_VERSION_MAJOR not defined. Do NOT add WDF_STUB (would desync the shared WDF type-identity).
3. allowlist_recursively(false) + allowlist_file("(?i).*iddcx.*"), full codegen (no .complement()) — emit ONLY IddCx items; WDF/Win types resolve via use crate::types::*.
4. allowlist_type("_?DXGI_.*" / "IDXGI.*" / "_?OPM_.*" / "_?D3DCOLORVALUE") — emit the non-WDF types wdk-sys doesn't bindgen, locally. The _? is load-bearing (typedef struct _OPM_X {} OPM_X needs the tag AND the alias).
5. pub type UINT = ::core::ffi::c_uint; in src/iddcx.rs — UINT is absent from crate::types.
6. translate_enum_integer_types(true) — emit native u32 reprs for the DXGI/OPM ModuleConsts enums (nested modules can't see a parent UINT).

Wrapper note: table dispatch via _IDDFUNCENUM::<Name>TableIndex as usize (the ModuleConsts const, not a NewType .0); NTSTATUS is plain i32 (wdk_sys::NT_SUCCESS). The driver build.rs adds the IddCxStub link-search (the import lib is under iddcx\1.0\ even though headers are 1.10) + #[no_mangle] pub static IddMinimumVersionRequired: ULONG = 4. The versioned IDD_STRUCTURE_SIZE! path is dropped — the WDK links the iddcx 1.0 stub (lacks the version table); we target 1.10 vs a current framework, so size_of is exactly correct.

6.3 Driver port checklist (STEP 0–8, as landed)

0. workspace pf-vdisplay(cdylib)+wdk-iddcx; prove std::thread+OwnedHandle link under UMDF (done).
1. wdk-iddcx: 11 typed DDI wrappers via one dispatch macro + re-export the inbound PFN_* types.
2. DriverEntry + IDD_CX_CLIENT_CONFIG (15 callbacks) + DeviceInitConfig + WdfDeviceCreate + CreateDeviceInterface (the owned pf GUID) + DeviceInitialize; edid.rs salvaged verbatim.
3. DeviceContext + WDF_DECLARE_CONTEXT_TYPE blob; init_adapter in D0Entry (caps + FP16) → AdapterInitAsync; the *2 mode DDIs + query_target_info + gamma/HDR accept-stubs. (Box gate: loads under Secure Boot, enumerates as an IddCx adapter, Status OK.)
4. control plane (GET_INFO version handshake the host asserts, ADD/REMOVE/SET_RENDER_ADAPTER/PING/ CLEAR_ALL) + create_monitor + real mode DDIs + watchdog + mode bounds; host switched to pf_driver_proto.
5. Direct3DDevice + assign/unassign + SwapChainProcessor (worker, SetDevice 60×@50 ms single-borrow retry, top-of-loop terminate, ReleaseAndAcquireBuffer2, from_raw_borrowed).
6. FramePublisher on pf_driver_proto::frame + keyed-mutex RAII guard; wire into run_core. (Box: full IDD-push glass-to-glass + the secure-desktop gate — validated 2026-06-25.)
7. HDR / FP16 ring (validated: Mac connects WITH HDR).
8. its own .inx + an unsafe-reduction pass (deny(unsafe_op_in_unsafe_fn), per-site // SAFETY:).

Remaining driver work beyond STEP 8: E1 (DeviceContext-owned state + per-IDDCX_MONITOR EvtCleanupCallback → unblock max_concurrent>1 — see §4 for why it's deliberately deferred), the slot-reclaim-on-REMOVE fix (§4 P1.3), and folding the gamepad-driver side onto pf_driver_proto (M4 tail, §4 P3).

6.4 Resolved product decisions (the five forks)

A the host was refactored in place (staged, behavior-preserving), not greenfield-rebuilt — the driver was rebuilt fresh. B IDD-push primary for everything incl. the secure desktop (validated); WGC+DDA demoted to non-IddCx fallbacks. C all drivers on microsoft/windows-drivers-rs (+ the iddcx subset; /INTEGRITYCHECK solved) — done for pf-vdisplay and now for the gamepad drivers (M4, 92e6802). D keep GameStream (Moonlight), default to secure serve. E concurrent sessions: the host-side preempt dance was removed by the ownership-model work, but true max_concurrent>1 on Windows stays blocked on the E1 driver swap-chain-reuse work (deliberately deferred, §4). Rejected: DeviceContext-per-monitor ownership — see the E1 stability decision in §4 (it would add a use-after-free window for no gain under ProcessSharingDisabled).

---

Origins & design rationale (from the original plan)

This folds in the durable rationale from the original Windows host + client plan (windows-host.md, now a stub; full original text in git history). The Windows host began (2026-06-10 to 2026-06-14) as a "add backends behind the existing traits" job, not a parallel port — punktfunk-core and the whole control plane are platform-agnostic, and the host already compiled on non-Linux (macOS) thanks to existing cfg(target_os) gating. These framing decisions shaped what shipped and still explain why the code is the way it is:

• Build order: host-first. A user preference (the research had recommended client-first, since the client is unblocked by the no-GPU problem and becomes the host's test endpoint). The trade-off held — the GPU-gated steps were the only ones that stalled GPU-less.
• Trait-based abstraction → ~95% reuse. punktfunk-core (protocol/FEC/crypto/session/transport/QUIC/ C ABI), the GameStream wire logic (mDNS, serverinfo, pairing, RTSP, ENet), the management REST API + native_pairing/discovery, and the punktfunk1/spike/pipeline orchestration all carried over unchanged — only the OS-touching backends behind Capturer/Encoder/VirtualDisplay/InputInjector/ AudioCapturer/VirtualMic are new #[cfg(windows)] code. Getting to MSVC needed only ~3 cfg-gates (gate the std::os::fd/OwnedFd unix-isms in main.rs/vdisplay.rs).
• The no-GPU dev strategy. Most of the port was built + validated on a GPU-less Windows VM: the MSVC compile, the virtual-display control path (WARP), the openh264 software-encode pipeline (full capture→encode→FEC→UDP transport minus HW), SendInput injection + interactive-session/desktop-reattach, gamepad + rumble, and the entire client (software-decode loopback). Only NVENC-D3D11 zero-copy, the DDA-vs-WGC bake-off, split-encode/bitrate-ceiling, and all glass-to-glass numbers deferred to a real NVIDIA box (no perf claim transfers from Linux).
• Windows-specific structural issues (no Linux precedent) — these are the gotchas that drove the service + capture design and remain true:
  • Interactive session, not a Session-0 service. SendInput can't reach the desktop from Session 0; Desktop Duplication / capture need the interactive session. Hence the SYSTEM-in-interactive-session supervisor (§2.6, windows-service.md) and the OpenInputDesktop/ SetThreadDesktop re-attach to survive UAC/lock desktop switches.
  • Clock epoch. The skew handshake assumes both ends read the same realtime epoch in ns — the Windows host must emit timestamps from GetSystemTimePreciseAsFileTime→Unix-epoch-ns, or cross-machine latency
    • ClockProbe/ClockEcho break (std SystemTime on Windows is historically coarser).
  • No audio endpoint on a headless IDD. WASAPI loopback needs a real/virtual render device; the virtual mic (client→host) has no clean user-mode path — deferred.
  • Color/range. All clients assume BT.709 limited-range; the BGRA→I420/NV12 path must match or colors wash out — validated against the existing decoders.

SudoVDA → pf-vdisplay evolution. The original plan was built around SudoVDA, an off-the-shelf indirect display driver (the same IDD Apollo ships) — chosen to avoid writing/WHQL-signing a driver and to get arbitrary WxH@Hz modes on the fly. It carried the host all the way to live-validated NVENC on a real RTX 4090. It was then replaced by the all-Rust pf-vdisplay IddCx driver (which solved /INTEGRITYCHECK self-signing, §6.1, and gave us the IDD-push zero-copy capture path that captures the secure desktop directly) and deleted in commit 84a3b95 — pf-vdisplay is now the sole virtual-display backend. The full SudoVDA control protocol (IOCTL layout, watchdog keepalive, GDI-name resolution) lives in git history if ever needed as a reference.