Order-independent installation: runtime, vendor plug-in, vendor platform/conversion runtimes, any order, install and uninstall

[dfattal]

Goal

The DisplayXR stack must install and uninstall in any order, with or without the 3D display connected:

1. the vendor platform runtime (tracking/weaving platform),
2. the vendor conversion runtime (2D→3D, consumed by XR_DXR_lift),
3. the DisplayXR bundle = runtime + vendor plug-in + service start.

Design approved 2026-10-02.

Hard constraints

• C1. The DisplayXR runtime (and the bundle) must not know about any vendor (no vendor paths, names, registry keys).
• C2. The vendor platform runtime and the vendor conversion runtime must not know about DisplayXR.
• C3. The vendor plug-in may know about its vendor platform and conversion runtimes.

Current behaviour (verified by code reading + box logs, 2026-10-02)

Order / state	What happens today
Bundle, then vendor platform runtime	The plug-in DLL statically imports the platform DLLs, found only via the machine PATH. Without the platform: LoadLibrary err=126 → silent sim-display fallback (anaglyph, no tracking). After the platform is installed the running service keeps its old PATH, so every re-probe fails again until the service restarts.
Bundle on a box without the vendor platform	The bundle pre-selects the vendor plug-in only if the platform's DLLs exist at a vendor path → a silent bundle never installs the plug-in; installing the platform later installs nothing. Violates C1.
Vendor platform, then bundle	Works. The standalone plug-in installer restarts the service ELEVATED (plain Exec) → normal-integrity apps cannot reach it; the bundle uses explorer.exe (ok).
Platform present, platform service down at DisplayXR service start	Plug-in declines; refresh re-probes on the next client connect / compositor create and adopts it (seen in a real log: 6 s later). Adoption is partial: weaving DP + geometry switch, the head device object stays sim-display's.
Vendor platform upgraded under a running service	Mapped platform DLLs stale; D3D11 weaver reconnects, D3D12/GL/VK only detect; log says restart.
Vendor platform uninstalled while the service runs	Untracked weave (DEGRADED); next restart → err=126 → sim-display, silently.
Screen not connected at start, connected later	With the platform present and no EDID match the probe BLOCKS up to 20 s, then declines. Re-probe only on the next client connect (no WM_DISPLAYCHANGE / WM_DEVICECHANGE anywhere); each retry can stall 20 s again.
Screen disconnected while running	Nothing invalidates the cached geometry; the plug-in then claims the PRIMARY monitor as VERIFIED → weave on a normal monitor.
Vendor conversion runtime installed after the bundle	Lift "absent" state is permanent per process; registry never re-read → no lift until service restart.
Conversion runtime upgrade/uninstall while loaded	Files locked by the service. Fix in flight: Restart-Manager-aware service (PR #1793) + the vendor installer must call RmShutdown(RmForceShutdown).
Runtime uninstall	Kills the service, runs each plug-in's UninstallString (ExecWait without _?= → probably not awaited), then deletes the whole DisplayProcessors key (installer/DisplayXRInstaller.nsi:1281-1325, :1335). If the plug-in uninstall fails its files + ARP entry survive UNREGISTERED and a later bundle version-skips it.
Plug-in before runtime	Plug-in installer exits 4 (runtime absent) / 5 (runtime below MIN_RUNTIME_VERSION).
Any degraded state	No tray / Control Panel signal; only displayxr-cli selftest (exit 8 VENDOR_DP_REJECTED) and logs.

Root causes

• (a) Load-time coupling of the vendor plug-in to its vendor platform.
• (b) Selection re-evaluated only on client events; probe() may block ~20 s.
• (c) Frozen process environment (PATH) in the long-lived service.
• (d) Installers encode order (bundle sniffs vendor paths, plug-in requires the runtime, runtime uninstaller owns + destroys plug-in registrations).
• (e) No state surfacing.

Target contract

Runtime (vendor-agnostic)

• R-a. A registered plug-in is a fact, not a decision. The runtime uninstaller deletes only its own DisplayProcessors\sim-display subkey and /ifempty the parent; it never runs vendor uninstallers and never deletes vendor entries. Orphan entries (Binary missing) are skipped with one WARN.
• R-b. Every plug-in must be LOADABLE without its platform, and reports a generic state through a new append-only ADR-020 slot: READY | PLATFORM_ABSENT | PLATFORM_NOT_RUNNING | NO_DISPLAY | INCOMPATIBLE + a short vendor-provided hint string. The runtime never interprets vendor specifics; it only displays the hint. probe() must return within ~100 ms and never block on the platform (documented in docs/specs/runtime/plugin-discovery.md).
• R-c. Selection is re-evaluated on WORLD events, not client events: WM_DISPLAYCHANGE / WM_DEVICECHANGE (DBT_DEVNODES_CHANGED) received by the service's hidden session window (DisplayXRServiceSession, PR feat(service): Restart Manager support so installers can close and restart the service #1793), RegNotifyChangeKeyValue on HKLM\Software\DisplayXR\DisplayProcessors, and a slow timer (10 s) while the active DP is the fallback. Adoption must be COMPLETE (head device, display info, eye tracking, weaving DP).
• R-d. No live swap: while a vendor DP is active and reports NO_DISPLAY the runtime keeps it, surfaces the state, and the DP passes pixels through unwoven. Adopt a better plug-in only when the active one is the fallback (sim-display).
• R-e. Surface the state: tray tooltip/icon, Control Panel, displayxr-cli selftest / info, e.g. "Vendor plug-in '' installed — platform missing: ".
• R-f. Installers: start the service via explorer.exe always (never elevated); a failed child in the bundle must not skip the final service restart; never a modal under /S (/SD).
• R-g. Resolve vendor dependency DLLs without relying on the service's PATH snapshot: the vendor plug-in resolves them itself; the runtime does nothing vendor-specific here.

Bundle (knows the component list, not vendor paths)

• B-a. Always install the vendor plug-in (it is inert without its platform); remove the vendor-path sniffing and the "(… not detected)" label. Order inside the bundle stays runtime → plug-in but nothing depends on it.
• B-b. /SD on every abort MessageBox; a child failure still runs the finalize section (service restart via explorer.exe) and records the failure.

Vendor plug-in (P-a … P-e)

Delay-load + self-resolve its platform DLLs (P-a), cheap non-blocking probe() reporting state + hint (P-b), display-change invalidation (P-c), conversion-runtime re-probe (P-d), an installer with no runtime/platform prerequisite and Restart-Manager service handling (P-e). Tracked in the vendor plug-in repo — see the task list.

Vendor asks (vendor platform + vendor conversion runtime installers — know nothing about DisplayXR)

• V-a. Vendor installers should use Windows Restart Manager (RmStartSession / RmRegisterResources / RmGetList / RmShutdown(RmForceShutdown) / RmRestart) to close and restart whatever holds their files, instead of move-aside + delete-at-reboot. The DisplayXR service registers for restart and exits on the close query (PR feat(service): Restart Manager support so installers can close and restart the service #1793).
• V-b. The vendor conversion runtime should publish its version in its registry entry.
• V-c. The vendor conversion runtime must not own a hidden top-level window on a non-pumping thread (it blocks non-forced RM shutdown of any host).

Decisions taken (2026-10-02)

• No live DP swap while a vendor DP is active: adopt a better plug-in only when the active one is the fallback; otherwise surface NO_DISPLAY.
• The vendor plug-in is installable without the runtime.
• One epic here, mirrored items in the vendor plug-in repo, vendor asks for the platform/conversion installers, and a vendor-neutral ADR ("plug-ins are always loadable and report platform state").

Prerequisite (merged 2026-10-02, main 74022ab)

• feat(service): Restart Manager support so installers can close and restart the service #1793 — Restart Manager support in the service (hidden session window, restart registration, exit on close query). Prerequisite for the vendor asks and for the world-event re-probe. Tick when merged.

Task list

Runtime (this repo):

• Plug-in state slot: always-loadable plug-ins report READY / PLATFORM_ABSENT / PLATFORM_NOT_RUNNING / NO_DISPLAY / INCOMPATIBLE + hint, surfaced in CLI, tray and Control Panel #1804 — plug-in state slot + surfacing + ADR (R-b, R-e)
• Re-probe display processors on world events (display/device/registry change, fallback timer) with complete adoption; no live swap away from an active vendor DP #1805 — world-event re-probe, complete adoption, no live swap (R-c, R-d)
• Runtime uninstaller must not cascade into vendor plug-ins or delete the DisplayProcessors key; loader skips orphan registrations #1806 — uninstaller stops cascading / deleting DisplayProcessors; loader skips orphans (R-a, R-f)

Bundle:

• Bundle: always install the vendor plug-in (no vendor-path sniffing), /SD on abort dialogs, finalize runs after a child failure displayxr-installer#74 — always install the vendor plug-in, /SD, finalize after child failure (B-a, B-b)

Vendor plug-in:

• Delay-load the SR platform DLLs (registry-resolved hook) and make probe() non-blocking with state/hint reporting displayxr-leia-plugin#287 — delay-load + registry-resolved hook, non-blocking probe + state/hint (P-a, P-b; depends on Plug-in state slot: always-loadable plug-ins report READY / PLATFORM_ABSENT / PLATFORM_NOT_RUNNING / NO_DISPLAY / INCOMPATIBLE + hint, surfaced in CLI, tray and Control Panel #1804)
• Installer: no runtime/SR prerequisite, Restart Manager service stop/restart (explorer.exe fallback), clean uninstall with or without the runtime, no modal under /S displayxr-leia-plugin#288 — installer: no prerequisites, Restart Manager, clean uninstall, no modal under /S (P-e)
• Display hot-plug invalidation (no primary-monitor claim after unplug) and NeurD re-probe after ABSENT/FAILED or DLL change displayxr-leia-plugin#289 — display hot-plug invalidation + conversion-runtime re-probe (P-c, P-d)
• Vendor asks (relay to SR platform + NeurD teams): Restart Manager in installers, NeurD Version value, NeurD non-pumping hidden window displayxr-leia-plugin#290 — vendor asks, relayed to the vendor teams (V-a, V-b, V-c)

Not part of this epic (box hygiene, found during investigation)

• The vendor plug-in ships a vendor Vulkan weaver DLL older than the installed vendor platform.
• A vendor beta DLL lives in the runtime directory (ADR-019 violation).
• ~15 hand-made .bak / .devtt DLL copies in Program Files.
• Two orphaned old vendor conversion-runtime MSI entries + a leftover install directory.
• The bundle's ARP entry reports a stale version (2.4.6).

[dfattal]

Status 2026-10-03 — all implementation PRs merged and released.

Work item	PR	Released in
2 + 3 — plug-in platform-state slot, world-event re-probe, complete adoption (self-restart), no live swap, ADR-045	#1808	runtime v2.24.0
4 — uninstaller no longer cascades into vendor plug-ins / deletes DisplayProcessors	#1807	runtime v2.24.0
prerequisite — Restart-Manager-aware service	#1793	runtime v2.24.0
6 — bundle always installs the vendor plug-in, /SD, finalize always runs	displayxr-installer#76 (+ #77 workflow fix)	bundle v2.5.5
1 + 7a — vendor plug-in loads without its platform (delay-load), non-blocking probe, state reporting, display-change handling	vendor plug-in repo PR 292	vendor plug-in v2.9.0 (runtime pin v2.24.0, PR 293)
5 + 7b — plug-in installer without prerequisites, Restart Manager stop/restart, conversion-runtime re-probe	vendor plug-in repo PR 291	vendor plug-in v2.9.0

Next: the install/uninstall stress test on a real box (install orders × uninstall orders, with the vendor platform and conversion runtime installed before/after), with a design-vs-observed report posted here.

[dfattal]

Install/uninstall stress test — 2026-10-03, real box (laptop with the built-in 3D panel)

Under test: runtime v2.24.0, vendor plug-in v2.9.0, bundle v2.5.5, vendor platform runtime 1.38.0+1863 (release candidate), vendor conversion runtime 0.4.6. Harness: 11 scenarios + final baseline assertion, every step silent (/S), state snapshot after each step (registry, files, ARP, services, service process integrity, displayxr-cli info/selftest run non-elevated, service-log signatures). Box ended on the full baseline (all services up, selftest PASS, ActiveRuntime + Run key intact).

Design vs observed

Scenario (design line)	Result	Observed
S2 plug-in installed before the runtime (P-e, R-a)	PASS 19/19	plug-in installer exits 0 with no runtime (was exit 4), writes DisplayProcessors\<id>, starts nothing; runtime install then adopts it at service start; service at Medium; selftest 0
S7 plug-in reinstall over a running service (P-e, #1793)	PASS 6/6	RmShutdown(RmForceShutdown) success in 297 ms, RmRestart success; old service exits on WM_QUERYENDSESSION, successor Started by a Restart Manager restart (… elevated=0), back on the vendor DP
S8 plug-in uninstall under a running service, then reinstall (P-e, R-c)	PASS 10/10	DLL really deleted (no delete-at-reboot), service RM-restarted onto the fallback; reinstall → display re-probe (plug-in registration changed): adopted → one adoption restart (--adoption-restart-after-pid) → vendor DP, Medium
S4 bundle on a box without the vendor platform (B-a, B-b, P-a, P-b, R-b, R-e)	PASS 15/15	bundle exit 0, plug-in installed + registered, no LastChildFailure; no err=126 (delay-loaded platform DLLs); probe took 1.5 ms; cli/log show PLATFORM_ABSENT with the vendor hint; selftest 0 (declined ≠ rejected); service on the fallback at Medium
S5 vendor platform installed after the bundle, service running (R-c, R-g, P-a)	PASS 10/10	platform services up 0 s after installer exit; display re-probe (fallback timer) adopted the vendor DP ~20 s later, adoption restart completed, successor Medium on the vendor DP; platform DLLs resolved by full path from the vendor registry key (no PATH dependency); selftest 0
S10 bundle uninstall (reverse chain) then bundle install (U8, C1, B-b)	PASS 14/14	all bundle-owned ARP entries, DP key, service, Run key gone; vendor platform and conversion runtime untouched; fresh bundle: exit 0, Run key + ActiveRuntime both views, vendor DP, selftest 0
S3 runtime uninstall must not cascade (R-a)	FAIL 4	plug-in files + ARP survive and the runtime's sim-display entry is removed as designed, but the whole DisplayProcessors key is still deleted → runtime reinstall comes up on the fallback. Cause: a second, unconditional DeleteRegKey survived #1807 (v2.24.0 script line 1320). Fix: #1813 (one line).
S6 conversion runtime uninstall/reinstall under a running service (P-d, V-a)	FAIL 4 (3 vendor, 1 ours)	vendor uninstaller: exit 0 in 2 s but leaves the DLL + 7 dependencies, the ARP entry and the registry key, queues reboot-time deletes of the live files (would have deleted the reinstalled files at next reboot — cleaned by hand); no Restart Manager use; reinstall exit 0 after 78 s. Ours: displayxr-cli lift caps hung 60 s × 3 against the half-removed install → #1812. P-d (re-detect after absent) could not be exercised because the DLL never disappeared.
S9 vendor platform uninstalled while everything runs, then reinstalled (R-d)	PASS 6 / 1 harness glitch	no live swap: service keeps the vendor DP, [HEALTH] dp=ok; after reinstall the D3D11 DP re-binds in place (same pid); the one FAIL is the harness mis-parsing info (plugins list shows the vendor DP ACTIVE/READY, selftest 0)
S11 platform service stopped at service start, started later (P-b, R-c)	FAIL 4	plug-in reported READY (service=1) with the platform service stopped: its "service running" signal is a shared-memory section that other platform clients keep alive → bound to the vendor DP instead of the fallback, so the fallback-timer adoption had nothing to do. Plug-in repo issue filed (use the SCM state).
FINAL baseline	PASS 12 / 1	the only FAIL was the vendor conversion runtime's queued reboot-time deletes of its live files (see S6)

Not testable on this box: display unplug/replug (built-in panel) → WM_DISPLAYCHANGE re-probe, NO_DISPLAY + unwoven pass-through; reboot-dependent vendor cleanup; the bundle's forced-failure paths (need stub children on a VM).

Follow-ups

• fix(installer): drop the stray DisplayProcessors key delete left by #1807 #1813 — uninstaller: remove the stray DisplayProcessors delete (then runtime v2.24.1 + bundle).
• lift: 'displayxr-cli lift caps' hangs 60 s+ after the vendor conversion runtime is uninstalled/reinstalled under a running service #1812 — lift caps must be bounded while the conversion module is in a broken/half-installed state.
• vendor plug-in: PLATFORM_NOT_RUNNING must use the platform service's SCM state, not the shared-memory section.
• vendor asks (sent to the conversion-runtime owner today): Restart Manager with the force flag; never queue reboot-time deletes of paths an upgrade rewrites; remove ARP/registry only when files are gone; write a Version value; fix the hidden non-pumping window.
• after the first (aborted) run the vendor platform's service was once left registered-but-stopped for 10+ min after a silent reinstall; reported to the platform session.

Harness + artifacts live on the win box (scratchpad/install-order/stress/, artifacts-20261003-113132, report-20261003-113132.md).

[dfattal]

Correction to the report above: the note "the vendor platform's service was once left registered-but-stopped for 10+ min after a silent reinstall" is withdrawn. The platform's own logs show its service ran healthily after that reinstall and was stopped at 11:28:56 by my harness's S11 step (Stop-Service … -Force), which then aborted on the harness bug before its restart step. Not a vendor installer defect.