docs(linux): close Slice L0

2026-07-27 11:59:58 +02:00 · 2026-07-27 11:59:58 +02:00 · 07bb1c5a74
commit 07bb1c5a74
parent 66f114b258
9 changed files with 264 additions and 14 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -390,7 +390,17 @@ scheduler cadence, and every resource dimension inside its ceiling. SIGINT
 produced ACE-confirmed graceful logout for both accounts and a passing final
 `disposed` sample: two converged Runtime roots, zero entities/inventory/host
 or content leases, and disposed shared content. K4 and Slice K are closed;
-Slice L Linux graphical/platform work is active.
+Slice L Linux graphical/platform work is active. L0 completed at `66f114b2`:
+`ApplicationPathSet` is the shared XDG/Windows path authority;
+`GraphicalHostPlatformServices` owns one OS/architecture/RID, native manifest,
+and frame-waiter factory; Linux uses an absolute `CLOCK_MONOTONIC` wait;
+settings, keybindings, Studio, diagnostics, and user plugins consume portable
+paths with no-overwrite Windows migration; and the RID-safe App publish plus
+Ubuntu graphical CI/package gate pass. Windows passes 415 Runtime, 67
+Headless, 543 UI, and 3,736 App tests / 3 skips; the complete Release suite
+passes 8,799 / 5 skips. Native Ubuntu passes the portable closure, 14 L0 App
+tests, and exact `linux-x64` publish. L1 context/extension/native-backend
+validation is next.
 J0's rollback is
 `git revert b632672e5ccabfb44c551e08f1c411ab2669c44a`.
 J1's rollback is
@ -462,6 +472,8 @@ K4's current rollbacks, newest first, are
 `git revert bd236ce553718cfb1248703f4a2b17b35733b11c`,
 `git revert 97c174fbb2d72fb94e2fe07448bb257989ed8941`, then
 `git revert cb512fd0916fbf49285c9b64df1630c5a69a0d20`.
+L0's rollback is
+`git revert 66f114b258c0c37b51a7c0e04ca0d6441f4b1699`.
 Slice H's retained UI/frame, bounded-light, and pooled/borrowed/direct network
 work is complete; the exact seven-checkpoint connected lifecycle/reconnect gate
 passes. Slice I is closed in
@ -495,7 +507,9 @@ closeout is
 `docs/research/2026-07-27-slice-k1-single-session-headless.md`; K2 closeout is
 `docs/research/2026-07-27-slice-k2-deterministic-bot-parity.md`; Slice K is
 closed in `docs/plans/2026-07-26-modern-runtime-slice-k.md`; K4 evidence is
-`docs/research/2026-07-27-slice-k4-resource-telemetry-checkpoint.md`. The exact G4 visual
+`docs/research/2026-07-27-slice-k4-resource-telemetry-checkpoint.md`; Slice L
+executes from `docs/plans/2026-07-26-modern-runtime-slice-l.md`; L0 evidence is
+`docs/research/2026-07-27-slice-l0-platform-services.md`. The exact G4 visual
 rollback
 is `git revert ef1d263337997bb030eadb7b8e71d73dc659907a`; do not revert G3 or
 the portal-warmup corrections. Evidence:
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -388,7 +388,17 @@ scheduler cadence, and every resource dimension inside its ceiling. SIGINT
 produced ACE-confirmed graceful logout for both accounts and a passing final
 `disposed` sample: two converged Runtime roots, zero entities/inventory/host
 or content leases, and disposed shared content. K4 and Slice K are closed;
-Slice L Linux graphical/platform work is active.
+Slice L Linux graphical/platform work is active. L0 completed at `66f114b2`:
+`ApplicationPathSet` is the shared XDG/Windows path authority;
+`GraphicalHostPlatformServices` owns one OS/architecture/RID, native manifest,
+and frame-waiter factory; Linux uses an absolute `CLOCK_MONOTONIC` wait;
+settings, keybindings, Studio, diagnostics, and user plugins consume portable
+paths with no-overwrite Windows migration; and the RID-safe App publish plus
+Ubuntu graphical CI/package gate pass. Windows passes 415 Runtime, 67
+Headless, 543 UI, and 3,736 App tests / 3 skips; the complete Release suite
+passes 8,799 / 5 skips. Native Ubuntu passes the portable closure, 14 L0 App
+tests, and exact `linux-x64` publish. L1 context/extension/native-backend
+validation is next.
 J0's rollback is
 `git revert b632672e5ccabfb44c551e08f1c411ab2669c44a`.
 J1's rollback is
@ -460,6 +470,8 @@ K4's current rollbacks, newest first, are
 `git revert bd236ce553718cfb1248703f4a2b17b35733b11c`,
 `git revert 97c174fbb2d72fb94e2fe07448bb257989ed8941`, then
 `git revert cb512fd0916fbf49285c9b64df1630c5a69a0d20`.
+L0's rollback is
+`git revert 66f114b258c0c37b51a7c0e04ca0d6441f4b1699`.
 Slice H's retained UI/frame, bounded-light, and pooled/borrowed/direct network
 work is complete; the exact seven-checkpoint connected lifecycle/reconnect gate
 passes. Slice I is closed in
@ -493,7 +505,9 @@ closeout is
 `docs/research/2026-07-27-slice-k1-single-session-headless.md`; K2 closeout is
 `docs/research/2026-07-27-slice-k2-deterministic-bot-parity.md`; Slice K is
 closed in `docs/plans/2026-07-26-modern-runtime-slice-k.md`; K4 evidence is
-`docs/research/2026-07-27-slice-k4-resource-telemetry-checkpoint.md`. The exact G4 visual
+`docs/research/2026-07-27-slice-k4-resource-telemetry-checkpoint.md`; Slice L
+executes from `docs/plans/2026-07-26-modern-runtime-slice-l.md`; L0 evidence is
+`docs/research/2026-07-27-slice-l0-platform-services.md`. The exact G4 visual
 rollback
 is `git revert ef1d263337997bb030eadb7b8e71d73dc659907a`; do not revert G3 or
 the portal-warmup corrections. Evidence:
--- a/docs/architecture/acdream-architecture.md
+++ b/docs/architecture/acdream-architecture.md
@ -241,6 +241,9 @@ src/
    World/
      RuntimeWorldEnvironmentState.cs -> canonical calendar/time/weather owner
      RuntimeWorldTransitState.cs -> canonical reveal generation/readiness owner
+    Platform/
+      ApplicationPathSet.cs -> shared BCL-only XDG/Windows config, data,
+                               cache, plugin, screenshot, and diagnostic paths
    RuntimeGenerationReset.cs -> one retryable canonical-generation reset
    -> Slice J complete; graphical and no-window hosts share one GameRuntime
    -> may reference Core, Core.Net, Content, and Plugin.Abstractions only
@ -266,6 +269,11 @@ src/
    ISelectionService.cs      -> done
  
  AcDream.App/               Layer 1 + Layer 4 wiring
+    Platform/
+      GraphicalHostPlatformServices.cs -> one startup OS/architecture/RID,
+                                          native-manifest, path, pacing owner
+      GraphicalLegacyConfigurationMigrator.cs -> no-overwrite Windows
+                                                  LocalAppData migration
    Physics/
      ProjectileController.cs -> live-record projectile orchestration/corrections
      RemotePhysicsUpdater.cs -> ordinary/Hidden remote narrow-tick integration
@ -283,6 +291,8 @@ src/
      RetailLiveFrameCoordinator.cs -> object/physics-before-network frame barrier
    Rendering/
      GameWindow.cs           -> native composition/callback shell
+      FramePacingWaiterFactory.cs -> startup-selected Windows/Linux waiter
+      LinuxMonotonicFramePacingWaiter.cs -> absolute CLOCK_MONOTONIC sleep
      LiveEntityAnimationScheduler.cs -> canonical ordinary live-object workset
      RetailStaticAnimatingObjectScheduler.cs -> retail static-animation workset
      StaticLiveRootCommitter.cs -> static root pose/collision commit boundary
--- a/docs/plans/2026-04-11-roadmap.md
+++ b/docs/plans/2026-04-11-roadmap.md
@ -3,6 +3,12 @@
 **Status:** Living document. Updated 2026-07-27. **M3 landed; M4 is active.** M3's retail casting/UI, R6 locomotion/collision/projectile/teleport/radar rebaseline, deterministic fresh-login/portal world lifecycle, and final two-client portal observer flow are user-gated. All eight slices of the behavior-preserving ownership campaign in [`docs/architecture/code-structure.md`](../architecture/code-structure.md), their automated closeout, and the user's connected visual matrix are complete. Modern Runtime J3 canonical entity/object lifetime and J4 gameplay-state ownership are closed at `89e6b207`; J5.1 canonical selection/combat/target-mode ownership is closed at `b298f99f`, J5.2 interaction transactions at `f5f7b417`, J5.3 combat/magic intent at `20df9d15`, J5.4 local movement/outbound cadence at `aa3f4a60`, J5.5 per-session physics/remote simulation at `7e6033d0`, J5.6 projectile simulation at `2aee3356`, and J5.7 combined simulation closeout at `cdee7a4b`. J6.1 world-environment ownership is closed at `902076c0`; J6.2 canonical reveal generation and typed destination readiness is closed at `a6860d55` plus `acb845d8`; J6.3 exact F751/Position destination correlation is closed at `6a063a27`; J6.4 exact graphical-host acknowledgement and owner cleanup is closed at `18d17d8b`. J7's one graphical `GameRuntime` root is closed at `ce41efb9`, including the user's 2026-07-27 exact post-cutover visual acceptance. J8 closed Slice J at `a9a822f2` with one shared graphical/no-window root and generation-reset transaction. Slice K Linux headless/multi-session work is closed. K0's tested no-presentation Windows/Linux boundary closed at `aada8a37`, K1's portable single-session host at `f8cb840f`, K2's deterministic scheduler and shared bot API at `7e8acb74` plus `38e83640`, and K3's shared-content/isolation plus connected observer gate at `3f340125`. K4 closed through `776482da`: 1/5/10/30-root isolation and two-hour simulated endurance, death/randomized cancellation, committed resource ceilings, ten minutes of exact native Linux two-account connected sampling, ACE-confirmed graceful logout, and zero-debt Runtime/content convergence all pass. Slice L Linux graphical/platform work is active. Issue #225's lifestone/particle alpha comparison remains a separate rendering visual gate.
 **Purpose:** One source of truth for where the project is and where it's going. Every observed defect or missing feature has a named phase that owns it; when something looks wrong in-game, look here to find the phase that'll address it. Implementation details live in per-phase specs under `docs/superpowers/specs/`, not in this file.

+**Slice L checkpoint:** L0 closed at `66f114b2` with one typed graphical
+platform/native manifest, shared XDG/Windows paths, factory-selected
+Windows/Linux frame waits, portable persistence/plugin discovery, RID-safe
+App publish, and an Ubuntu graphical CI/package gate. Slice L1
+context/extension/native-backend validation is active.
+
 ---

 ## Current program: world interaction completion (M4 prelude)
@ -1816,7 +1822,7 @@ port in any phase — no separate listing here.
 > Headless tests pass 67/67 and the complete Release suite passes 8,784 / 5
 > skips. The exact two-account connected soak then passed 20 periodic samples,
 > ACE-confirmed graceful logout, and a zero-debt `disposed` record. Slice K is
-> closed and Slice L is active.
+> closed. Slice L0 completed at `66f114b2`; L1 is active.
 > The historical exact cutover
 > rollback remains
 > `git revert ef1d263337997bb030eadb7b8e71d73dc659907a`. Slice H is complete:
@ -1863,7 +1869,8 @@ hitch and follows.
 > no-window Linux host and approximately 30-session target from
 > [`2026-07-26-modern-runtime-slice-k.md`](2026-07-26-modern-runtime-slice-k.md);
 > Slice L executes the graphical Linux/platform work. K0-K4 and Slice K are
-> complete through `776482da`. Its automated 1/5/10/30-root
+> complete through `776482da`. L0 is complete at `66f114b2`; L1 is active.
+> K's automated 1/5/10/30-root
 > isolation, two-hour simulated endurance, death/cancellation, and committed
 > resource-envelope gates pass; the exact two-account connected process added
 > ten minutes of passing samples, graceful logout, and complete terminal
--- a/docs/plans/2026-05-12-milestones.md
+++ b/docs/plans/2026-05-12-milestones.md
@ -317,6 +317,16 @@ residency is `0/0/0` at every stable checkpoint and teardown converges. Slice I
  logout for both accounts and a passing `disposed` record with two converged
  Runtime roots, zero entities/inventory/host/content leases, and disposed
  shared content. K4 and Slice K are closed; Slice L is active.
+  L0 completed at `66f114b2`: one startup-owned graphical platform/native
+  manifest, the shared Runtime XDG/Windows path set, factory-selected Windows
+  and absolute-monotonic Linux frame waits, portable settings/keybindings/
+  diagnostics/plugins, RID-safe plugin build/publish, and Ubuntu graphical CI
+  are in production. Windows passes 415 Runtime, 67 Headless, 543 UI, and
+  3,736 App tests / 3 skips; the complete Release suite passes 8,799 / 5
+  skips. Native Ubuntu passes the portable Runtime/Headless/UI and 14 L0 App
+  tests, and the exact `linux-x64` package contains resolved GLFW, OpenAL
+  Soft, cimgui, shaders, and smoke plugin. Slice L1 context/extension/native-
+  backend validation is next.
 Slice-I closeout evidence is
 [`../research/2026-07-25-slice-i7-closeout.md`](../research/2026-07-25-slice-i7-closeout.md).
 Slice-J2 closeout evidence is
--- a/docs/plans/2026-07-26-modern-runtime-slice-l.md
+++ b/docs/plans/2026-07-26-modern-runtime-slice-l.md
@ -1,6 +1,6 @@
 # Modern runtime Slice L — Linux graphical host and evidence-gated GPU work

-**Status:** PREPARED — BEGINS AFTER SLICE K CLOSEOUT
+**Status:** ACTIVE — L0 COMPLETE; L1 NEXT
 **Parent:** `2026-07-24-modern-runtime-architecture.md`, Slice L
 **Authorization:** the user approved Slices F–L on 2026-07-24
 **Purpose:** ship the existing modern OpenGL client on supported Linux drivers
@ -156,6 +156,15 @@ Provide:

 ### L0 — platform services and Linux build

+**Complete at `66f114b2` (2026-07-27).** Runtime now owns the shared
+XDG/Windows `ApplicationPathSet`; App owns one typed graphical platform/native
+manifest and factory-selected Windows/Linux kernel waiter. Settings,
+keybindings, Studio, diagnostics, and user plugins consume the portable paths,
+with no-overwrite Windows legacy migration. The RID-aware smoke-plugin build
+and publish paths and the Ubuntu graphical CI/package guard pass. Exact
+Windows/Linux evidence and rollback are recorded in
+[`../research/2026-07-27-slice-l0-platform-services.md`](../research/2026-07-27-slice-l0-platform-services.md).
+
 - Add Linux App build/publish jobs to CI after K's non-graphical Linux jobs.
 - Add typed platform capability, path, pacing, and native-dependency owners.
 - Implement the Linux monotonic frame waiter and factory selection.
--- a/docs/research/2026-07-27-slice-l0-platform-services.md
+++ b/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
+```
--- a/memory/project_linux_graphical.md
+++ b/memory/project_linux_graphical.md
@ -0,0 +1,65 @@
+# Modern Runtime Linux graphical continuation
+
+## Current checkpoint
+
+Slice L0 completed at
+`66f114b258c0c37b51a7c0e04ca0d6441f4b1699`.
+
+The same `AcDream.App` now builds and publishes for `linux-x64`; there is no
+Linux gameplay or renderer fork.
+
+Canonical seams:
+
+- `AcDream.Runtime.Platform.ApplicationPathSet` owns XDG/Windows config, data,
+  cache, plugin, screenshot, and diagnostic paths for graphical and headless
+  hosts.
+- `AcDream.App.Platform.GraphicalHostPlatformServices` owns one startup OS,
+  architecture, RID, native-dependency manifest, path set, and pacing factory.
+- `PlatformFramePacingWaiterFactory` selects the existing Windows
+  high-resolution waitable timer or Linux
+  `LinuxMonotonicFramePacingWaiter`.
+- Linux waiting uses absolute `CLOCK_MONOTONIC` +
+  `clock_nanosleep(TIMER_ABSTIME)`, retries `EINTR`, does not busy-spin, and
+  rejects use after disposal.
+- Windows legacy `%LOCALAPPDATA%\acdream\settings.json` and
+  `keybinds.json` are copied only when the new roaming destination is absent.
+- bundled plugins are read beside the binary; user plugins are read from the
+  portable data root. A successful bundled ID wins; a failed load does not
+  reserve the ID.
+
+Exact L0 evidence:
+
+- Windows: Runtime 415, Headless 67, UI 543, App 3,736 / 3 skips, complete
+  Release 8,799 / 5 skips.
+- native Ubuntu/WSL: Runtime 415, Headless 67, UI 543, 14 L0 App tests.
+- exact framework-dependent `linux-x64` publish contains executable, managed
+  closure, GLFW, OpenAL Soft, cimgui, shaders, and smoke plugin/manifest;
+  direct `ldd` has no unresolved dependency.
+- closeout:
+  `docs/research/2026-07-27-slice-l0-platform-services.md`.
+
+Rollback:
+
+```text
+git revert 66f114b258c0c37b51a7c0e04ca0d6441f4b1699
+```
+
+## Next work — L1
+
+Do not claim Linux graphical support merely from publish success. L1 must:
+
+1. start the exact package under the available X11 and Wayland sessions;
+2. capture OS/display/compositor/GPU/driver/OpenGL vendor, renderer, version,
+   mandatory extensions, swap interval, refresh, DPI, and audio backend before
+   renderer construction;
+3. create the OpenGL 4.3 core context and reject missing bindless texture or
+   shader draw parameters with one actionable report;
+4. validate GLFW window/input callbacks, relative mouse/focus, framebuffer
+   sizing, clipboard, and monitor facts;
+5. initialize OpenAL fail-open exactly as current Windows behavior permits;
+6. render a packaged smoke scene, capture a screenshot, and close with zero
+   GL/OpenAL/window debt.
+
+Historical test-only issue: two installed-DAT App tests still hard-code
+`C:\Turbine\Asheron's Call`. They are not production blockers, but clean them
+before claiming the complete App test suite on a clean Linux runner.
--- a/memory/project_modern_runtime_headless.md
+++ b/memory/project_modern_runtime_headless.md
@ -70,13 +70,13 @@ zero entities/inventory/host/content leases, disposed shared content, and
 ## Next work

 Slice L is active under
-`docs/plans/2026-07-26-modern-runtime-slice-l.md`. The initial read-only L0
-probe already proves framework-dependent `linux-x64` App publish succeeds and
-ships resolved GLFW, OpenAL Soft, and cimgui native libraries. The smoke plugin
-is missing from the publish because its copy target uses Windows-shaped paths.
-Frame pacing still directly constructs the Windows waitable-timer owner, and
-App/UI persistence still defaults to Windows `LocalApplicationData`; those
-are the first L0 implementation seams.
+`docs/plans/2026-07-26-modern-runtime-slice-l.md`. L0 completed at
+`66f114b2`: the shared path owner, graphical platform/native manifest,
+factory-selected Linux wait, portable persistence/plugins, RID-safe publish,
+and Ubuntu graphical package gate pass. Continue from
+`memory/project_linux_graphical.md`; L1 must prove the actual Linux
+window/context/input/audio lifecycle rather than revisiting headless
+ownership.

 Final K3 automated counts: Runtime 412, Headless 47, App 3,722 / 3 skips,
 complete Release 8,764 / 5 skips.