docs(linux): close Slice L0

docs/research/2026-07-27-slice-l0-platform-services.md

@@ -0,0 +1,121 @@
+# Slice L0 closeout — graphical platform services and Linux publish
+
+**Date:** 2026-07-27
+
+**Production commit:** `66f114b258c0c37b51a7c0e04ca0d6441f4b1699`
+**Status:** complete; Slice L1 is next
+
+## Outcome
+
+The existing `AcDream.App` now restores, builds, tests, and publishes as the
+same graphical client on Windows and `linux-x64`. This is not a second Linux
+renderer or gameplay host. `GameWindow`, retained UI, Runtime, rendering,
+shaders, and DAT behavior remain shared.
+
+L0 established four typed startup seams:
+
+- `GraphicalHostPlatformServices` owns the process OS, architecture,
+  supported RID, native-dependency manifest, portable paths, and frame-waiter
+  factory.
+- Runtime's `ApplicationPathSet` is the shared XDG/Windows path authority used
+  by graphical and headless hosts.
+- `PlatformFramePacingWaiterFactory` selects the existing Windows
+  high-resolution waitable timer or the new Linux absolute
+  `CLOCK_MONOTONIC` waiter. Frame policy and missed-deadline rebasing are
+  unchanged.
+- the App project owns RID-aware build and publish copying for the smoke
+  plugin, and Linux CI verifies the complete framework-dependent package
+  contract.
+
+Feature code no longer resolves `%LOCALAPPDATA%` itself. Settings, key
+bindings, UI Studio, texture diagnostics, and per-user plugin discovery
+receive canonical paths from the composition root. Windows preserves existing
+users through a no-overwrite migration of legacy LocalAppData settings and
+key bindings into the shared roaming configuration root. The packaged plugin
+root remains read-only and is scanned before the per-user plugin root.
+
+## Native and package gate
+
+An exact publish from the production commit succeeded:
+
+```text
+dotnet publish src/AcDream.App/AcDream.App.csproj \
+  -c Release -r linux-x64 --self-contained false
+```
+
+The artifact contains:
+
+- executable `AcDream.App` plus its managed closure;
+- `libglfw.so.3`, `libopenal.so`, and `libcimgui.so`;
+- the production shader tree;
+- `plugins/AcDream.Plugins.Smoke/AcDream.Plugins.Smoke.dll`;
+- the matching smoke-plugin manifest.
+
+`ldd` reports no unresolved direct dependency. The App build and publish use
+the same RID-aware smoke-plugin source; no Windows separator or hard-coded
+`net10.0` output assumption remains.
+
+The new Ubuntu CI lane independently builds and publishes `linux-x64`, runs
+the portable UI and L0 App tests, validates the package contents, and enforces
+source guards:
+
+- Windows kernel imports remain confined to the Windows waiter;
+- platform checks remain confined to typed platform owners;
+- App/UI feature code cannot reintroduce LocalAppData resolution;
+- normal frame pacing cannot directly construct the Windows waiter.
+
+## Automated evidence
+
+Windows Release:
+
+- Runtime: `415 / 415`
+- Headless: `67 / 67`
+- UI abstractions: `543 / 543`
+- App: `3,736 / 3 skips`
+- complete solution: `8,799 / 5 skips`
+- App build: zero warnings and zero errors
+
+Native Ubuntu/WSL:
+
+- Runtime: `415 / 415`
+- Headless: `67 / 67`
+- UI abstractions: `543 / 543`
+- L0 App platform/path/pacing tests: `14 / 14`
+- exact `linux-x64` build and framework-dependent publish: pass
+- real Linux five-millisecond absolute-monotonic wait: pass
+
+The broader Linux App run also passed 3,734 tests and the three existing
+explicit fixture skips. Two historical installed-DAT tests still hard-code
+`C:\Turbine\Asheron's Call`; they are not part of L0's portable gate and do
+not indicate a production Linux failure. L1/L2 test-fixture cleanup should
+remove that test-only Windows assumption before claiming the complete App
+suite on a clean Linux runner.
+
+## Behavior and ownership audit
+
+- Runtime/gameplay/network/physics/render algorithms are unchanged.
+- VSync still waits in swap; uncapped diagnostics still do not wait.
+- VSync-off normal play uses the same deadline/rebase policy with a
+  platform-owned kernel wait.
+- The Linux waiter retries `EINTR` against the original absolute deadline,
+  owns no native handle, and rejects use after disposal.
+- Existing Windows configuration is copied only when the canonical file is
+  absent; no existing destination is overwritten or deleted.
+- Package validation does not bundle DATs, `acdream.pak`, or credentials.
+- The four unrelated line-ending-only worktree files were excluded from the
+  commit.
+
+## Remaining Slice L work
+
+L0 proves build/publish and the typed platform boundary. It deliberately does
+not claim that a Linux GL window, input stack, audio device, or connected game
+route has passed. L1 must open the packaged client under X11 and Wayland,
+capture the mandatory OpenGL capability record, validate GLFW/input/OpenAL
+construction and teardown, render a smoke scene, capture a screenshot, and
+fail unsupported drivers with one actionable report.
+
+## Rollback
+
+```text
+git revert 66f114b258c0c37b51a7c0e04ca0d6441f4b1699
+```