docs(windows-host-goal1): Stage 5 tightening 3 (EncoderCaps) DONE; refresh Remaining

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) <noreply@anthropic.com>
This commit is contained in:
2026-06-25 21:28:30 +00:00
parent 0ccd0fe676
commit bf57aa4000
+28 -20
View File
@@ -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 **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. 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** — > **Status (2026-06-25):** all six staged stages, §2.5 (the ownership-model rewrite), **and** all three
> each is code + box-`cargo check --features nvenc` + (where it touches the deployed path) on-glass > Stage-5 seam-trait tightenings (incl. `EncoderCaps`, `0ccd0fe`) are **DONE** — each is code +
> validated. Work lives on branch **`windows-host-goal1`** (off `main`, **not merged**). What's left is > box-`cargo check --features nvenc` + (where it touches the deployed path) on-glass validated, except the
> small and non-blocking — see [Remaining (next session)](#remaining-next-session) at the end. > 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) ## 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 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. 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: 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 - **(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 "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 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<dyn VirtualLease>` is the `sudovda::wait_for_monitor_released` free fn), and the keepalive becoming `Box<dyn VirtualLease>` is the
ownership-model change. It belongs with the `VirtualDisplayManager`/`MonitorLease` work, not bolted on here. 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 - **(3) `EncoderCaps` ✅ (`0ccd0fe`)** — `Encoder::caps() -> EncoderCaps { supports_rfi, supports_hdr_metadata }`,
no-ops); not blocking. Tracked for the next seam pass. 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 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). 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) ## 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 1. **Optional `crate::*::windows::` namespace collapse**Stage 6 confined the platform files into
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
`windows/`/`linux/` folders via `#[path]` (flat module names, zero reference churn); the deeper rename to `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. real `crate::capture::windows::` paths is optional cleanup, not required. **Decision: skip** — pure churn
3. **Merge `windows-host-goal1` → `main`** — the branch is off `main` and **not merged**; local `main` is for no behavior/clarity gain, and it would touch every `super::`/`crate::` path in the moved files.
also ~20 commits ahead of `origin/main` with unpushed audit/Stage work. Land both when ready (the 2. **Merge `windows-host-goal1` → `main`** — the branch is off `main` and **not merged**; local `main` is
[Work-on-main] habit otherwise applies). also ~20 commits ahead of `origin/main` with unpushed audit/Stage work. Outward-facing (a 30+-commit push
4. **(driver — NOT the host refactor) pf-vdisplay slot reclaim** — surfaced on-glass: sustained ADD/REMOVE 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 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 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/reset-pf-vdisplay.ps1`; the real fix lives in the driver WIP. **This belongs to the
(`packaging/windows/drivers/pf-vdisplay/src/{control,adapter}.rs`). Dev-iteration helpers greenfield driver rewrite, not the Goal-1 host refactor** — tracked in
`reset-pf-vdisplay.ps1` + `redeploy-pf-vdisplay.ps1` are committed under `packaging/windows/` (validated [`windows-host-rewrite.md`](windows-host-rewrite.md) (alongside the fullscreen-game capture bug).
live). Dev-iteration helpers `reset-pf-vdisplay.ps1` + `redeploy-pf-vdisplay.ps1` are committed under
`packaging/windows/` (validated live).
## Guardrails (mandatory, plan §14) ## Guardrails (mandatory, plan §14)