From bf57aa40002564ad1efc4c81017280165d0f6a13 Mon Sep 17 00:00:00 2001 From: enricobuehler Date: Thu, 25 Jun 2026 21:28:30 +0000 Subject: [PATCH] docs(windows-host-goal1): Stage 5 tightening 3 (EncoderCaps) DONE; refresh Remaining MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Goal-1 host refactor is now functionally complete — all 6 stages, §2.5, and all three Stage-5 seam-trait tightenings have landed (EncoderCaps = 0ccd0fe). Remaining is non-blocking: the optional namespace collapse (decision: skip — pure churn), the merge to main (confirm with the user — outward-facing), and the pf-vdisplay slot-reclaim driver fix (reassigned to windows-host-rewrite.md, the greenfield driver rewrite, alongside the fullscreen-game capture bug). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/windows-host-goal1-plan.md | 48 +++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/docs/windows-host-goal1-plan.md b/docs/windows-host-goal1-plan.md index 03c2bb6..6cfedcd 100644 --- a/docs/windows-host-goal1-plan.md +++ b/docs/windows-host-goal1-plan.md @@ -6,10 +6,12 @@ NVENC + IDD-push on-glass) and Goal-1 rewires its session/config/dispatch flow **preserve behavior**, compile + box-verify on its own, and be committed before the next starts. The plan's own §14 makes the §1 preservation checklist a mandatory per-module assert contract; honour it. -> **Status (2026-06-25):** all six staged stages **and** §2.5 (the ownership-model rewrite) are **DONE** — -> each is code + box-`cargo check --features nvenc` + (where it touches the deployed path) on-glass -> validated. Work lives on branch **`windows-host-goal1`** (off `main`, **not merged**). What's left is -> small and non-blocking — see [Remaining (next session)](#remaining-next-session) at the end. +> **Status (2026-06-25):** all six staged stages, §2.5 (the ownership-model rewrite), **and** all three +> Stage-5 seam-trait tightenings (incl. `EncoderCaps`, `0ccd0fe`) are **DONE** — each is code + +> box-`cargo check --features nvenc` + (where it touches the deployed path) on-glass validated, except the +> Windows-only `EncoderCaps` NVENC override which is Linux-clippy-clean + CI-gated. Work lives on branch +> **`windows-host-goal1`** (off `main`, **not merged**). The Goal-1 host refactor is **functionally +> complete**; what's left is non-blocking — see [Remaining (next session)](#remaining-next-session). ## Why staged (not one big rewrite) @@ -96,7 +98,7 @@ explicit), and it is the validated shipping path. Wrapping the deployed reconfig the concrete, safe arg-bundling. Risk: low (behavior-identical). Verify: Linux + box build (the relay destructure is the only Windows-only piece); the teardown on-glass gate moves to the §2.5 work. -**Stage 5 — seam-trait tightenings (plan §2.3). 🟡 Tightening 1 ✅ DONE (box-build validated); 2→§2.5, 3 follow-on.** +**Stage 5 — seam-trait tightenings (plan §2.3). ✅ Tightening 1 + 3 DONE; 2 folded into §2.5.** The three §2.3 tightenings have different coupling, so they split: - **(1) `OutputFormat` into the capturer ✅** — the headline (the explicit Stage-3 deferral; §5's "highest-severity coupling"). New `capture::OutputFormat { gpu, hdr }`, resolved once per session and @@ -109,8 +111,13 @@ The three §2.3 tightenings have different coupling, so they split: monitor-generation carried *on the lease* (today it's the `CURRENT_MON_GEN` global + the `sudovda::wait_for_monitor_released` free fn), and the keepalive becoming `Box` is the ownership-model change. It belongs with the `VirtualDisplayManager`/`MonitorLease` work, not bolted on here. -- **(3) `EncoderCaps`** — small additive follow-on (query optional encoder capabilities instead of default - no-ops); not blocking. Tracked for the next seam pass. +- **(3) `EncoderCaps` ✅ (`0ccd0fe`)** — `Encoder::caps() -> EncoderCaps { supports_rfi, supports_hdr_metadata }`, + a default-`false` query (so every SDR/libavcodec backend — Linux NVENC, VAAPI, AMF/QSV, software — is + unchanged); only the Windows direct-NVENC path overrides it, reporting the real `rfi_supported` (probed + once at open) + `hdr`. Consumer: the GameStream encode loop hoists `supports_rfi` once and gates the + loss-recovery path on it — `!(supports_rfi && invalidate_ref_frames(..))` forces a keyframe directly on + non-RFI encoders instead of an always-`false` call every loss event (behavior-preserving, intent + explicit). Linux `clippy -D warnings` clean; the NVENC override is Windows-only → CI/on-glass gate. Risk: medium (Tightening 1 is behavior-preserving + Windows-only → box-compile is the gate; on-glass parity is the same env-limited story as Stage 3). @@ -170,23 +177,24 @@ Verified live on the **IDD-push zero-copy path** (`new_fps ~200` @5120×1440@240 ## Remaining (next session) -Small, non-blocking follow-ons — the layered architecture is in place: +The layered architecture is **complete**: all 6 staged stages, §2.5, **and** the three Stage-5 seam-trait +tightenings have landed. What's left is non-blocking: -1. **`EncoderCaps` (Stage 5 tightening 3)** — query optional encoder capabilities behind a small trait - instead of the default no-ops; additive, low-risk. The last seam-trait tightening. -2. **Optional `crate::*::windows::` namespace collapse** — Stage 6 confined the platform files into +1. **Optional `crate::*::windows::` namespace collapse** — Stage 6 confined the platform files into `windows/`/`linux/` folders via `#[path]` (flat module names, zero reference churn); the deeper rename to - real `crate::capture::windows::` paths is optional cleanup, not required. -3. **Merge `windows-host-goal1` → `main`** — the branch is off `main` and **not merged**; local `main` is - also ~20 commits ahead of `origin/main` with unpushed audit/Stage work. Land both when ready (the - [Work-on-main] habit otherwise applies). -4. **(driver — NOT the host refactor) pf-vdisplay slot reclaim** — surfaced on-glass: sustained ADD/REMOVE + real `crate::capture::windows::` paths is optional cleanup, not required. **Decision: skip** — pure churn + for no behavior/clarity gain, and it would touch every `super::`/`crate::` path in the moved files. +2. **Merge `windows-host-goal1` → `main`** — the branch is off `main` and **not merged**; local `main` is + also ~20 commits ahead of `origin/main` with unpushed audit/Stage work. Outward-facing (a 30+-commit push + to `origin`) → **confirm with the user before landing**; the [Work-on-main] habit otherwise applies. +3. **(driver — NOT the host refactor) pf-vdisplay slot reclaim** — surfaced on-glass: sustained ADD/REMOVE churn wedges the driver (`ADD → 0x80070490 ERROR_NOT_FOUND`) because it doesn't reclaim IddCx monitor slots on REMOVE (ghost monitor nodes accumulate, `target_id`s climb). Recovery today is - `packaging/windows/reset-pf-vdisplay.ps1`; the real fix lives in the driver WIP - (`packaging/windows/drivers/pf-vdisplay/src/{control,adapter}.rs`). Dev-iteration helpers - `reset-pf-vdisplay.ps1` + `redeploy-pf-vdisplay.ps1` are committed under `packaging/windows/` (validated - live). + `packaging/windows/reset-pf-vdisplay.ps1`; the real fix lives in the driver WIP. **This belongs to the + greenfield driver rewrite, not the Goal-1 host refactor** — tracked in + [`windows-host-rewrite.md`](windows-host-rewrite.md) (alongside the fullscreen-game capture bug). + Dev-iteration helpers `reset-pf-vdisplay.ps1` + `redeploy-pf-vdisplay.ps1` are committed under + `packaging/windows/` (validated live). ## Guardrails (mandatory, plan §14)