docs(architecture): close GameWindow render slice

Record the clean Release, lifecycle, soak, and framebuffer gates for Slice 7, advance the structural program to Slice 8, and preserve the observed process-residency diagnostic gap as issue 232 rather than weakening its leak threshold.\n\nCo-authored-by: Codex <codex@openai.com>
This commit is contained in:
Erik 2026-07-22 08:40:52 +02:00
parent 9d7df1bfc5
commit 96f8bfcfa8
8 changed files with 176 additions and 64 deletions

View file

@ -2,9 +2,9 @@
## Current state
The behavior-preserving App ownership campaign is complete through Slice 6.
The behavior-preserving App ownership campaign is complete through Slice 7.
`GameWindow.cs` moved from the 2026-07-21 baseline of 15,723 lines / 278 fields /
205 methods to 7,026 lines / 241 fields / 108 methods: 8,697 lines (55.3%) were
205 methods to 4,666 lines / 196 fields / 70 methods: 11,057 lines (70.3%) were
removed without changing accepted gameplay or rendering behavior.
| Slice | Ownership moved out | Closeout size |
@ -15,11 +15,14 @@ removed without changing accepted gameplay or rendering behavior.
| 4 | live-entity hydration, teardown, and network presentation | 10,301 / 267 / 163 |
| 5 | landblock build, publication, retirement, and shared-origin lifetime | 8,811 / 247 / 153 |
| 6 | complete update-frame orchestration | 7,026 / 241 / 108 |
| 7 | complete render-frame orchestration and failure recovery | 4,666 / 196 / 70 |
Slice 6 implementation commits are `99a3e819`, `4e4aac2c`, `0bc9fda9`,
`c5570383`, `eeb0f6b4`, `947c61d2`, and production cutover `e91f3102`.
The detailed ledgers and earlier commit sets live under `docs/plans/2026-07-21-
gamewindow-slice-*.md` and `docs/architecture/code-structure.md`.
Slice 7 implementation commits are `7e4cfb37`, `733126a2`, `bc6f09f9`,
`6d6e5b5f`, `85239fb3`, `28e1cf80`, and production cutover `9d7df1bf`.
The detailed ledgers live under `docs/plans/2026-07-2*-gamewindow-slice-*.md` and
`docs/architecture/code-structure.md`.
## Frozen update graph
@ -45,40 +48,70 @@ the session generation. Extracted phase owners query these typed runtimes and
must not create replacement dictionaries, service locators, or callback
facades into substantial `GameWindow` methods.
## Frozen render graph
`GameWindow.OnRender` creates one value-only `RenderFrameInput` and calls
`RenderFrameOrchestrator.Render`. The accepted healthy order is:
1. begin the GPU-flight transaction;
2. begin/reset frame resources, clear, and publish live resources;
3. begin the optional ImGui frame;
4. advance weather display preparation;
5. draw the complete world/PView/shared-alpha/particle/debug scene;
6. draw the portal/private viewport using the pre-private foundation snapshot;
7. refresh/draw paperdoll, retained gameplay UI, then submit ImGui;
8. capture a requested screenshot;
9. publish title/resource/frame diagnostics;
10. close the GPU-flight transaction.
Recovery is one reverse-lifetime transaction. An active ImGui frame closes
through the owning Silk controller, and text rendering restores exact borrowed
GL state on success or failure. The orchestrator and its immediate phase owners
retain no direct `GameWindow` or anonymous callback bag. Recursive reachability
through canonical UI/input owners is not frame ownership; the known paths and
review rule live in `docs/architecture/code-structure.md`.
## Accepted verification
- Release suite: 7,182 passed / 5 fixture or environment skips.
- Connected lifecycle/reconnect: 314.195 seconds, graceful close and fresh
process reconnect passed; only 25 expected world-edge empty landblocks.
- Synchronized nine-stop resource soak: 393.581 seconds, graceful exit; stable
21,025 entity and 13 animation-owner counts at the Caul return and Caul
plateau; update p95 0.8 ms. Working/private memory delta was +112.2/+111.0
MiB, inside the gate.
- The 35 missing VFX table/emitter diagnostics are known DAT-driven records,
not a Slice 6 regression.
- TS-50, TS-51, and TS-53 remain registered; Slice 6 introduced no new retail
- Release suite: 7,341 passed / 5 fixture or environment skips.
- Connected lifecycle/reconnect: 315.6 seconds, graceful capped close and fresh
process uncapped reconnect passed; only 25 expected world-edge empty
landblocks.
- The six lifecycle PNGs preserve Slice 6 world geometry, depth, UI/paperdoll,
private viewport, and presentation. Differences are live weather/particles,
authoritative vitals, and small scripted camera settling.
- Synchronized nine-stop resource soak: 395.2 seconds, nine materializations,
all movement/jump/combat exercises, and graceful exit passed; update p95 was
at or below 0.8 ms. Caul return → plateau working/private delta was
+85.7/+59.3 MiB, inside the unchanged gate.
- Two immediately preceding identical-binary runs exceeded the coarse process-
residency threshold while deterministic ownership/lifecycle/timing checks
passed. #232 adds canonical resource-owner snapshots; do not solve this by
loosening the process-memory threshold or treating residency alone as an
identified owner leak.
- The 1833 missing VFX table/emitter diagnostics are known DAT-driven records,
not a Slice 7 regression.
- TS-50, TS-51, and TS-53 remain registered; Slice 7 introduced no new retail
divergence.
## Next work
Slice 7 extracts `RenderFrameOrchestrator`: the modern draw graph, portal/PView
visibility routing, landscape/opaque/shared-alpha flushes, particles, debug
draw, paperdoll, retained UI, frame fences, and reusable frame-local scratch.
It must keep the exact accepted order and use a small immutable service set plus
explicit per-frame input. It may not become a GL service locator or call
substantial draw bodies back on `GameWindow`.
Slice 8 then groups composition and shutdown wiring and reduces Silk callbacks
to narrow calls into input, update, render, resize, focus, and shutdown owners.
Slice 8 groups composition and shutdown wiring and reduces Silk callbacks to
narrow calls into input, update, render, resize, focus, and shutdown owners.
It removes leftover feature state only where Slices 17 already established a
canonical owner; it does not redesign gameplay, rendering, or resource lifetime.
## Do not retry
- Do not reintroduce delegate facades into `GameWindow`; an ordering wrapper is
not an extraction until the state and behavior body move.
- Do not reorder the frozen update graph during structural work. TS-53 records
the known retail host-order difference for a separate evidence-backed port.
- Do not reorder the frozen update or render graphs during structural work.
TS-53 records the known retail host-order difference for a separate evidence-
backed port.
- Do not add a second GUID, session, spatial, or resource owner.
- Do not fold full `GameEntity` aggregation into this campaign; evaluate it
after Slice 8.
- Do not loosen the soak process-memory threshold to hide #232. Add canonical
owner snapshots and preserve process residency as a secondary guard.
- Small value/policy callbacks and diagnostics are acceptable only when they do
not call a substantial window body or hide mutable ownership.