From 5c955c36ecbb9c657076db17e7c5435dd978f296 Mon Sep 17 00:00:00 2001 From: Erik Date: Wed, 22 Jul 2026 20:52:25 +0200 Subject: [PATCH] docs(architecture): record GameWindow automated closeout Reconcile the architecture, roadmap, milestones, issue ledger, session instructions, and durable memory with the 1,622-line native shell, canonical soak evidence, connected framebuffer comparison, and sole remaining user visual gate. Co-authored-by: Codex --- AGENTS.md | 69 +++++-------------- CLAUDE.md | 69 +++++-------------- docs/ISSUES.md | 50 +++++--------- docs/architecture/acdream-architecture.md | 16 +++-- docs/architecture/code-structure.md | 41 ++++++----- docs/plans/2026-04-11-roadmap.md | 16 +++-- docs/plans/2026-05-12-milestones.md | 12 ++-- ...dow-slice-8-checkpoint-k-canonical-soak.md | 33 +++++++-- ...amewindow-slice-8-checkpoint-l-closeout.md | 40 ++++++++++- ...amewindow-slice-8-composition-lifecycle.md | 35 +++++++--- memory/project_gamewindow_decomposition.md | 59 +++++++++++----- 11 files changed, 239 insertions(+), 201 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 382b531a..d21a8163 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -115,57 +115,24 @@ and the final two-client portal-out/materialization observer flow are user-gated. Deterministic world-lifecycle automation protects fresh login, outdoor/world-edge/dungeon travel, same-location revisit, exact graceful disconnect, and uncapped fresh-process reconnect with JSON/PNG artifacts. -Release builds; Checkpoint H passes 61 focused ownership tests, 3,236 App tests -/ 3 skips, and 7,606 complete-solution tests / 5 skips. +Release builds; the automated structural closeout passes 293 focused tests, +3,451 App tests / 3 skips, and 7,823 complete-solution tests / 5 skips. -**Active prerequisite before new M4 subsystem work:** continue the -behavior-preserving `GameWindow` decomposition reconciled on 2026-07-21. -Selection/interaction Slice 1, live-animation-presentation Slice 2, complete -live-session ownership Slice 3, and live-entity App integration Slice 4 are -landed. Focused hydration, teardown, inbound-authority, network-update, and -motion-runtime owners now sit over canonical `LiveEntityRuntime` without a -second GUID dictionary. Slices 5–7 are complete: landblock presentation, -update-frame orchestration, and render-frame orchestration all have typed -owners. `GameWindow.OnUpdate` and `GameWindow.OnRender` are one-handoff methods; -the frame owners have no direct window or anonymous callback-bag ownership. -Slice 8 checkpoints A–H are also complete: dead host residue is removed, -native-window callback intake has reversible lifetime ownership, and -`LiveSessionHost` owns reset/binding composition over the sole canonical -session controller. `WorldEnvironmentController` solely owns the clock, DAT -sky/day group, weather, synchronization, and AdminEnvirons state. -`CameraPointerInputController` and `FramebufferResizeController` now own raw -camera input/focus/scroll and physical framebuffer publication. Silk, -dispatcher, retained-UI, and devtools device edges are reversible, -transactional, and terminal after disposal; live-session retirement precedes -physical callback removal. `GameplayInputActionRouter` now owns the sole -semantic action-priority -graph; typed owners route combat, diagnostics, and remaining commands, and the -retained-root item-drop edge is reversible. `GameWindow` was 4,057 raw lines / -198 fields / 54 methods at F. Checkpoint G adds the sole pre-window/runtime -settings owner, one immutable startup snapshot, ordered one-shot startup -application, and inert late target binding. `GameWindow` is now 3,663 raw lines / -162 fields / 37 methods, down 12,060 lines (76.7%) from the 15,723-line campaign -baseline. The 7,553-test / 5-skip Checkpoint G Release suite, 315.6-second -lifecycle/reconnect gate, and 395.2-second synchronized nine-stop soak pass. -Checkpoint H adds sole terrain/sky render-resource roots, one retained -Host/runtime lease, an atomic update/render frame-root pair, prepared portal -fallback/transfer, and checked retryable GL construction/state boundaries. -Checkpoint I now routes production through the same executable nine-phase -pipeline as its failure oracle, carries exact platform/settings results through -typed phase inputs, atomically publishes frame roots, and makes session start -terminal. `GameWindow` is 1,945 raw lines, down 13,778 lines (87.6%) from -baseline. App Release passes 3,431 tests / 3 skips and the complete Release -suite passes 7,803 / 5 skips. Checkpoint J moves the exact shutdown dependency -graph into `GameWindowLifetime`: immutable typed roots, retry/no-replay state, -hard session/GPU barriers, reportable physical callback cleanup, structured -terminal reporting, and native-window-last release now live outside the shell. -`GameWindow` is 1,625 raw lines, down 14,098 lines (89.7%) from baseline. App -Release passes 3,441 tests / 3 skips and the complete Release suite passes -7,813 / 5 skips. Checkpoints K–L—canonical soak snapshots and final connected -closeout—remain active. +**Structural prerequisite before new M4 subsystem work:** all eight +behavior-preserving `GameWindow` decomposition slices and the automated +closeout landed 2026-07-22. The class is now a 1,622-line native +composition/callback shell, down 14,101 lines (89.7%) from baseline. Ordered +startup, update/render frame graphs, native/input callbacks, settings, +session/reset wiring, canonical checkpoint capture, and retryable shutdown are +owned by focused typed collaborators without a service locator or stored +window back-reference. All 293 focused tests, App Release 3,451/3, the complete +Release suite 7,823/5, connected lifecycle/reconnect, two fresh-process +canonical nine-stop soaks, three corrected-diff reviews, and the exact Slice-7 +framebuffer comparison pass. Issue #232 is closed without loosening process +limits. Only the user's final connected visual matrix remains before M4 feature +bodies resume. See `docs/plans/2026-07-22-gamewindow-slice-8-composition-lifecycle.md` and -`docs/architecture/code-structure.md`. **Carried:** #232, #153, -#116, remaining +`docs/architecture/code-structure.md`. **Carried:** #153, #116, remaining R6 ownership cleanup, TS-50/TS-51/TS-53, Modern Pipeline MP1b+, and #225's lifestone/particle alpha visual gate. @@ -208,8 +175,8 @@ and to stop `GameWindow.cs` from continuing to grow into a 10k-line god object. The full rationale + the extraction sequence we're pursuing live in [`docs/architecture/code-structure.md`](docs/architecture/code-structure.md). -1. **No new substantial feature bodies in `GameWindow.cs`.** It is - already over 10,000 lines and owns runtime wiring. New runtime +1. **No new substantial feature bodies in `GameWindow.cs`.** It is now the + roughly 1,600-line native composition/callback shell. New runtime work goes into a dedicated controller / sink / orchestrator class in `src/AcDream.App/` (or deeper in `AcDream.Core` when it's pure logic). Adding a handful of fields and a one-paragraph method to diff --git a/CLAUDE.md b/CLAUDE.md index 4d7a99db..58d5cde5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -113,57 +113,24 @@ and the final two-client portal-out/materialization observer flow are user-gated. Deterministic world-lifecycle automation protects fresh login, outdoor/world-edge/dungeon travel, same-location revisit, exact graceful disconnect, and uncapped fresh-process reconnect with JSON/PNG artifacts. -Release builds; Checkpoint H passes 61 focused ownership tests, 3,236 App tests -/ 3 skips, and 7,606 complete-solution tests / 5 skips. +Release builds; the automated structural closeout passes 293 focused tests, +3,451 App tests / 3 skips, and 7,823 complete-solution tests / 5 skips. -**Active prerequisite before new M4 subsystem work:** continue the -behavior-preserving `GameWindow` decomposition reconciled on 2026-07-21. -Selection/interaction Slice 1, live-animation-presentation Slice 2, complete -live-session ownership Slice 3, and live-entity App integration Slice 4 are -landed. Focused hydration, teardown, inbound-authority, network-update, and -motion-runtime owners now sit over canonical `LiveEntityRuntime` without a -second GUID dictionary. Slices 5–7 are complete: landblock presentation, -update-frame orchestration, and render-frame orchestration all have typed -owners. `GameWindow.OnUpdate` and `GameWindow.OnRender` are one-handoff methods; -the frame owners have no direct window or anonymous callback-bag ownership. -Slice 8 checkpoints A–H are also complete: dead host residue is removed, -native-window callback intake has reversible lifetime ownership, and -`LiveSessionHost` owns reset/binding composition over the sole canonical -session controller. `WorldEnvironmentController` solely owns the clock, DAT -sky/day group, weather, synchronization, and AdminEnvirons state. -`CameraPointerInputController` and `FramebufferResizeController` now own raw -camera input/focus/scroll and physical framebuffer publication. Silk, -dispatcher, retained-UI, and devtools device edges are reversible, -transactional, and terminal after disposal; live-session retirement precedes -physical callback removal. `GameplayInputActionRouter` now owns the sole -semantic action-priority -graph; typed owners route combat, diagnostics, and remaining commands, and the -retained-root item-drop edge is reversible. `GameWindow` was 4,057 raw lines / -198 fields / 54 methods at F. Checkpoint G adds the sole pre-window/runtime -settings owner, one immutable startup snapshot, ordered one-shot startup -application, and inert late target binding. `GameWindow` is now 3,663 raw lines / -162 fields / 37 methods, down 12,060 lines (76.7%) from the 15,723-line campaign -baseline. The 7,553-test / 5-skip Checkpoint G Release suite, 315.6-second -lifecycle/reconnect gate, and 395.2-second synchronized nine-stop soak pass. -Checkpoint H adds sole terrain/sky render-resource roots, one retained -Host/runtime lease, an atomic update/render frame-root pair, prepared portal -fallback/transfer, and checked retryable GL construction/state boundaries. -Checkpoint I now routes production through the same executable nine-phase -pipeline as its failure oracle, carries exact platform/settings results through -typed phase inputs, atomically publishes frame roots, and makes session start -terminal. `GameWindow` is 1,945 raw lines, down 13,778 lines (87.6%) from -baseline. App Release passes 3,431 tests / 3 skips and the complete Release -suite passes 7,803 / 5 skips. Checkpoint J moves the exact shutdown dependency -graph into `GameWindowLifetime`: immutable typed roots, retry/no-replay state, -hard session/GPU barriers, reportable physical callback cleanup, structured -terminal reporting, and native-window-last release now live outside the shell. -`GameWindow` is 1,625 raw lines, down 14,098 lines (89.7%) from baseline. App -Release passes 3,441 tests / 3 skips and the complete Release suite passes -7,813 / 5 skips. Checkpoints K–L—canonical soak snapshots and final connected -closeout—remain active. +**Structural prerequisite before new M4 subsystem work:** all eight +behavior-preserving `GameWindow` decomposition slices and the automated +closeout landed 2026-07-22. The class is now a 1,622-line native +composition/callback shell, down 14,101 lines (89.7%) from baseline. Ordered +startup, update/render frame graphs, native/input callbacks, settings, +session/reset wiring, canonical checkpoint capture, and retryable shutdown are +owned by focused typed collaborators without a service locator or stored +window back-reference. All 293 focused tests, App Release 3,451/3, the complete +Release suite 7,823/5, connected lifecycle/reconnect, two fresh-process +canonical nine-stop soaks, three corrected-diff reviews, and the exact Slice-7 +framebuffer comparison pass. Issue #232 is closed without loosening process +limits. Only the user's final connected visual matrix remains before M4 feature +bodies resume. See `docs/plans/2026-07-22-gamewindow-slice-8-composition-lifecycle.md` and -`docs/architecture/code-structure.md`. **Carried:** #232, #153, -#116, remaining +`docs/architecture/code-structure.md`. **Carried:** #153, #116, remaining R6 ownership cleanup, TS-50/TS-51/TS-53, Modern Pipeline MP1b+, and #225's lifestone/particle alpha visual gate. @@ -206,8 +173,8 @@ and to stop `GameWindow.cs` from continuing to grow into a 10k-line god object. The full rationale + the extraction sequence we're pursuing live in [`docs/architecture/code-structure.md`](docs/architecture/code-structure.md). -1. **No new substantial feature bodies in `GameWindow.cs`.** It is - already over 10,000 lines and owns runtime wiring. New runtime +1. **No new substantial feature bodies in `GameWindow.cs`.** It is now the + roughly 1,600-line native composition/callback shell. New runtime work goes into a dedicated controller / sink / orchestrator class in `src/AcDream.App/` (or deeper in `AcDream.Core` when it's pure logic). Adding a handful of fields and a one-paragraph method to diff --git a/docs/ISSUES.md b/docs/ISSUES.md index bb6de5ec..e927a0de 100644 --- a/docs/ISSUES.md +++ b/docs/ISSUES.md @@ -26,29 +26,13 @@ What does NOT go here: ## Current queue — 2026-07-22 -- **Active structural work:** `GameWindow` decomposition. Slices 1–7 and Slice - 8 checkpoints A–H are complete; I.1–I.7 now own the executable ordered - startup path through retained UI and live presentation, including the - canonical runtime/world, selection/radar, landblock publishers, and - portal/sky/particle resources. - I.7 now owns streaming/session/hydration/local-player/teleport startup and - every late edge explicitly. I.8a now owns the focused session factory, - command targets, and sole gameplay input subscriber before frame publication. - I.8b now owns the complete update/render construction, exact atomic frame - publication, and lifecycle resource snapshot source. I.8c makes session - start the terminal `OnLoad` operation. I.9 corrected the production root to - invoke the exact tested pipeline and made every consumed platform/settings - result explicit. Checkpoint J moves the exact retryable shutdown graph into - `GameWindowLifetime`, including typed roots, hard session/GPU barriers, - reportable physical detach, structured terminal state, and native-window-last - release. `GameWindow.OnUpdate` and `GameWindow.OnRender` are typed - orchestration handoffs and the class is 1,625 raw lines. Checkpoints K–L—the - canonical soak snapshots and final closeout—remain active in - [`docs/architecture/code-structure.md`](architecture/code-structure.md). - This is the behavior-preserving prerequisite before new M4 feature bodies. -- **Connected-gate fidelity:** `#232` adds canonical managed/GPU/cache-owner - snapshots to the nine-stop soak so process-residency variance cannot be - mistaken for an owner leak or silently waved away. +- **Structural handoff:** all eight `GameWindow` decomposition slices and the + automated closeout are complete. The 1,622-line native shell has typed + startup, frame, callback, and shutdown owners; 293 focused tests, the + 7,823/5 Release suite, the lifecycle/reconnect route, two canonical + nine-stop soaks, and the Slice-7 framebuffer comparison pass. Only the + user's final connected visual matrix remains before the campaign is marked + complete in [`docs/architecture/code-structure.md`](architecture/code-structure.md). - **Separate rendering gate:** `#225`, lifestone/particle alpha ordering. Its connected performance, lifetime, and unattended portal routes pass. - **Carried behavior debt:** `#153` far-teleport unstreamed-edge arrival and @@ -122,7 +106,7 @@ attributes remain safely projected as zero. ## #232 — Nine-stop soak process-memory gate lacks canonical owner snapshots -**Status:** OPEN +**Status:** DONE (2026-07-22, `bca41487` + `6c5e0604`) **Severity:** LOW **Filed:** 2026-07-22 **Component:** connected automation / resource diagnostics @@ -135,13 +119,17 @@ growth of +240.9 MiB and +497.4 MiB; a third unchanged run passed at +85.7 MiB (private +59.3 MiB). Earlier Slice 6 development history also contains both a coarse-memory failure and subsequent clean runs. -**Root cause / status:** The current soak samples only process working set and -private bytes plus coarse world/title counters. Those totals combine live .NET -objects, committed-but-free GC segments, native allocations, mapped pages, and -GPU-driver residency, so a failed total cannot identify the owner that grew. -This is a diagnostic blind spot, not evidence that the threshold should be -raised. The unchanged gate produced a clean required closeout pass; no runtime -workaround or tolerance change was made. +**Root cause / status:** The old soak sampled only process working set/private +bytes plus coarse world/title counters. Those totals combine live .NET objects, +committed-but-free GC segments, native allocations, mapped pages, and GPU +driver residency, so a failed total could not identify the owner that grew. +Deferred acknowledged render-frame checkpoints now record the exact frame +outcome and canonical managed/GPU/cache/VFX/pending-work owners. Two fresh +403-second routes pass all nine ordered checkpoints, zero pending/staged/warmup +work, no unconfounded owner growth, graceful close, and the unchanged process +and performance limits. Legitimate owner retirement is allowed; growth becomes +a hard failure when workload is stable and a named warning when authoritative +or visible workload changed. **Files:** `tools/run-connected-r6-soak.ps1`; `src/AcDream.App/Diagnostics/WorldLifecycleAutomationController.cs`; diff --git a/docs/architecture/acdream-architecture.md b/docs/architecture/acdream-architecture.md index b4a3b69b..62f4d7a4 100644 --- a/docs/architecture/acdream-architecture.md +++ b/docs/architecture/acdream-architecture.md @@ -224,7 +224,7 @@ src/ LiveEntityTeardown.cs -> failure-isolated multi-owner lifecycle drain RetailLiveFrameCoordinator.cs -> object/physics-before-network frame barrier Rendering/ - GameWindow.cs -> still owns too much runtime wiring + GameWindow.cs -> native composition/callback shell LiveEntityAnimationScheduler.cs -> canonical ordinary live-object workset RetailStaticAnimatingObjectScheduler.cs -> retail static-animation workset StaticLiveRootCommitter.cs -> static root pose/collision commit boundary @@ -820,8 +820,9 @@ Current movement/collision ownership: - **M3 landed 2026-07-21** with connected magic/portal acceptance and the final two-client observer gate; Track LH is the future presentation-independent Linux/headless extraction. -- **The behavior-preserving thin-`GameWindow` ownership campaign is the active - prerequisite before new M4 subsystem bodies.** Selection/interaction Slice 1 +- **The behavior-preserving thin-`GameWindow` ownership campaign has completed + its implementation and automated closeout; only the user's final connected + visual matrix remains before new M4 subsystem bodies.** Selection/interaction Slice 1 landed with `WorldSelectionQuery`, `SelectionInteractionController`, and the shared retail inventory-request owner; Slice 2 moved final animation presentation into `LiveEntityAnimationPresenter`; Slice 3 moved the complete @@ -843,9 +844,12 @@ Current movement/collision ownership: production pipeline and terminal session start are complete. Checkpoint J moves the exact shutdown dependency graph into `GameWindowLifetime`, whose typed roots preserve hard session/GPU barriers, reportable physical detach, - retry/no-replay progress, and native-window-last release. `GameWindow` is - 1,625 raw lines; only the canonical soak instrumentation and final connected - closeout checkpoints remain. The reconciled ledger and sequence live in + retry/no-replay progress, and native-window-last release. Checkpoint K adds + deferred same-frame canonical resource snapshots and closes #232 through two + clean fresh-process nine-stop routes without weakening process limits. + `GameWindow` is 1,622 raw lines; 293 focused tests, the 7,823/5 Release suite, + connected lifecycle/reconnect, canonical soaks, corrected-diff reviews, and + the Slice-7 framebuffer comparison pass. The reconciled ledger lives in `docs/architecture/code-structure.md`. This decision does not reclassify the remaining L.2 conformance work or Track LH. diff --git a/docs/architecture/code-structure.md b/docs/architecture/code-structure.md index 9ef4f8a6..96d72b51 100644 --- a/docs/architecture/code-structure.md +++ b/docs/architecture/code-structure.md @@ -1,9 +1,9 @@ # acdream — code structure & extraction sequence **Status:** Living document. Created 2026-05-16; implementation reconciliation -completed 2026-07-21; Slices 1–7 landed by 2026-07-22. The final Slice 8 -composition/shutdown cleanup is active before new M4 subsystems enter the App -layer. +completed 2026-07-21; Slices 1–8 and their automated closeout landed by +2026-07-22. The final connected visual matrix remains before new M4 subsystems +enter the App layer. **Purpose:** Describe the desired structural state of the App layer, explain the rules we've adopted, and lay out the safe extraction sequence from today's reality (one 15,723-line `GameWindow.cs` at the @@ -37,9 +37,10 @@ after Slice 8 checkpoint F 4,057 lines / 198 fields / 54 method after Slice 8 checkpoint G 3,663 lines / 162 fields / 37 methods after Slice 8 checkpoint I 1,945 lines / startup composition shell after Slice 8 checkpoint J 1,625 lines / focused lifetime shell +after Slice 8 checkpoint K 1,622 lines / canonical soak shell ``` -`GameWindow` is the single object that: +At the campaign baseline, `GameWindow` was the single object that: - Owns the GL context, the window, input, and shaders. - Reads ~40 different environment variables across its lifetime. @@ -58,11 +59,11 @@ after Slice 8 checkpoint J 1,625 lines / focused lifetime shell `StreamingController` and `GpuWorldState` owners. - Wires up every plugin hook sink, every diagnostic, every panel. -The extracted controllers are valuable and tested, but line count alone proves -that creating collaborators has not yet made the window thin. A collaborator -is a completed extraction only when it owns the state and behavior body; -wrapping a `GameWindow` method in a delegate preserves ordering but remains a -partial extraction. +The completed slices moved those bodies into focused, tested owners. The rule +that governed the campaign still applies: a collaborator is a completed +extraction only when it owns the state and behavior body; wrapping a +`GameWindow` method in a delegate preserves ordering but remains a partial +extraction. The fix is **not** "rewrite `GameWindow` in one pass" — that is a high-risk change. The fix is to **extract one @@ -77,9 +78,9 @@ Recap of the rules from `CLAUDE.md` with the rationale: ### Rule 1: No new substantial feature bodies in `GameWindow.cs` -**Why:** Every line we add to `GameWindow` makes the eventual decomposition -harder. New features that "live in" `GameWindow` instead of being -extracted are the reason the file is 10k lines. +**Why:** New feature bodies in the native shell would reverse the ownership +campaign. Runtime work belongs in focused App owners, with only construction +and narrow callback handoffs retained here. **How to apply:** A new feature gets its own class under `src/AcDream.App//` (or deeper in `AcDream.Core` if it's pure @@ -685,7 +686,7 @@ Issue #232 records the coarse process-residency gate's run-to-run variance so future diagnostics can distinguish canonical owner growth from OS/driver/GC residency without weakening leak detection. -#### Slice 8 — composition and shutdown cleanup — ACTIVE (K–L remain) +#### Slice 8 — composition and shutdown cleanup — AUTOMATED COMPLETE Detailed execution ledger: [`docs/plans/2026-07-22-gamewindow-slice-8-composition-lifecycle.md`](../plans/2026-07-22-gamewindow-slice-8-composition-lifecycle.md). @@ -749,11 +750,15 @@ groups, retry/no-replay progress, structured reportable physical-detach failures, hard session/GPU barriers, and native-window-last release now live outside the host. The shell captures roots once and makes one lifetime call from Closing/Dispose; no shutdown stage remains in it. `GameWindow` is 1,625 -raw lines after J. The App gate passes 3,441 tests / 3 intentional skips and -the complete Release suite passes 7,813 tests / 5 intentional skips. The clean -solution build retains only the 17 test-project warnings tracked by #228; the -complete Checkpoint-J behavior, architecture, and adversarial corrected-diff -passes are clean. Checkpoints K–L remain active. +raw lines after J. Checkpoint K adds acknowledged same-frame canonical resource +checkpoints and leaves the shell at 1,622 lines. The App gate passes 3,451 tests +/ 3 intentional skips and the complete Release suite passes 7,823 / 5. Two +fresh-process nine-stop soaks and the connected lifecycle/reconnect route pass +with graceful exits; deterministic framebuffer captures preserve accepted +Slice 7 geometry, UI/paperdoll layering, private viewports, depth/alpha, and +reveal. The clean solution build retains only the 17 test-project warnings +tracked by #228, and all three final corrected-diff reviews are clean. Only the +user's final connected visual matrix remains. ### 4.4 Exit criteria diff --git a/docs/plans/2026-04-11-roadmap.md b/docs/plans/2026-04-11-roadmap.md index a52494b2..c4fad285 100644 --- a/docs/plans/2026-04-11-roadmap.md +++ b/docs/plans/2026-04-11-roadmap.md @@ -1,6 +1,6 @@ # acdream — strategic roadmap -**Status:** Living document. Updated 2026-07-22. **M3 landed; M4 is next after the active `GameWindow` structural prerequisite.** 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. The current program is the behavior-preserving ownership campaign in [`docs/architecture/code-structure.md`](../architecture/code-structure.md); Slices 1–7 and Slice 8 checkpoints A–J are complete, with only canonical soak instrumentation and final closeout checkpoints K–L active. New M4 quest/emote/character-creation feature bodies wait until that campaign is complete. Issue #225's lifestone/particle alpha comparison remains a separate rendering visual gate. +**Status:** Living document. Updated 2026-07-22. **M3 landed; M4 is next after the final `GameWindow` visual handoff.** 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) and their automated closeout are complete; only the user's connected visual matrix remains. 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. --- @@ -108,11 +108,15 @@ now 1,945 raw lines after I.9 makes production invoke the same typed pipeline as the failure oracle and keeps session start terminal. Checkpoint J extracts the exact shutdown dependency graph into `GameWindowLifetime`, with typed immutable roots, hard session/GPU barriers, reportable physical cleanup, -retry/no-replay state, and native-window-last terminal reporting. The host is -now 1,625 raw lines. Only canonical soak snapshots and closeout checkpoints -K–L remain. The App gate passes 3,441 tests / 3 intentional skips, the complete -Release suite passes 7,813 tests / 5 skips, and the complete Checkpoint-J -corrected-diff review is clean. +retry/no-replay state, and native-window-last terminal reporting. The host was +1,625 raw lines after J. + +Checkpoint K adds deferred, acknowledged, same-frame canonical resource +snapshots and closes #232 through two clean fresh-process nine-stop routes. +The shell is 1,622 raw lines. All 293 focused tests, App Release 3,451/3, the +complete Release suite 7,823/5, connected lifecycle/reconnect, both canonical +soaks, three corrected-diff reviews, and the exact Slice-7 framebuffer +comparison pass. Only the user's final connected visual matrix remains. This is a behavior-preserving structural program. Severe regressions still get root-cause fixes in separate commits; ordinary feature work resumes with M4 diff --git a/docs/plans/2026-05-12-milestones.md b/docs/plans/2026-05-12-milestones.md index 98390267..98eb1d46 100644 --- a/docs/plans/2026-05-12-milestones.md +++ b/docs/plans/2026-05-12-milestones.md @@ -68,10 +68,14 @@ tested pipeline with explicit prior-result dependencies. Checkpoint J adds the focused `GameWindowLifetime`, immutable typed shutdown roots, hard dependency barriers, structured report-and-continue physical cleanup, retry/no-replay state, and native-window-last terminal reporting. The host is now 1,625 raw -lines. Checkpoints K–L remain active; Issue #232 tracks process-residency -variance in the soak without loosening its leak threshold. The App gate passes -3,441 tests / 3 skips, the complete Release suite passes 7,813 tests / 5 skips, -and the complete Checkpoint-J corrected-diff review is clean. +lines after J. Checkpoint K adds deferred same-frame canonical owner snapshots +and closes #232 through two clean 403-second fresh-process nine-stop routes +without loosening the process thresholds. The automated Slice 8 closeout is +complete: `GameWindow` is 1,622 raw lines; 293 focused tests, App Release +3,451/3, the complete Release suite 7,823/5, lifecycle/reconnect, both +canonical soaks, all three corrected-diff reviews, and the Slice-7 framebuffer +comparison pass. Only the user's final connected visual matrix remains before +new M4 feature bodies begin. Carried: #153 far-teleport residual, #116 slide-response, the remaining R6 ownership cleanup plus diff --git a/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-k-canonical-soak.md b/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-k-canonical-soak.md index 4dc460b8..87790c6b 100644 --- a/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-k-canonical-soak.md +++ b/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-k-canonical-soak.md @@ -1,12 +1,13 @@ # GameWindow Slice 8 Checkpoint K — canonical soak snapshots -**Status:** Active 2026-07-22. +**Status:** Complete 2026-07-22 (`bca41487`, corrected gate semantics +`6c5e0604`). **Parent:** [`2026-07-22-gamewindow-slice-8-composition-lifecycle.md`](2026-07-22-gamewindow-slice-8-composition-lifecycle.md), Checkpoint K. -**Integrated baseline:** `31e6e192`; Checkpoints I–J are complete, -`GameWindow.cs` is 1,625 raw lines, App Release passes 3,441 tests / 3 skips, -and the complete Release suite passes 7,813 tests / 5 skips. +**Integrated result:** `GameWindow.cs` is 1,622 raw lines, App Release passes +3,451 tests / 3 skips, and the complete Release suite passes 7,823 tests / 5 +skips. **Issue:** [`#232`](../ISSUES.md#232--nine-stop-soak-process-memory-gate-lacks-canonical-owner-snapshots). **Behavior rule:** this checkpoint changes diagnostic capture and connected-gate evidence only. It does not change rendering, streaming, gameplay, resource @@ -198,3 +199,27 @@ for-byte unchanged as the secondary residency/performance guard. No visual gate is required for K because it changes diagnostic observation only. Checkpoint L owns the final connected framebuffer and user visual gate. + +## 6. Completion evidence + +The focused checkpoint suite passes 74 tests. The Release build succeeds with +only the 17 pre-existing test-project warnings tracked by #228. Two independent +fresh-process routes produced all nine ordered render-frame checkpoints and +closed gracefully: + +- `connected-r6-soak-20260722-201335.report.json`: 403.139 seconds; Caul + return-to-plateau working/private deltas +20.2/+10.3 MiB; update p95 1.5 ms. +- `connected-r6-soak-20260722-202025.report.json`: 403.021 seconds; Caul + return-to-plateau working/private deltas +165.0/+157.2 MiB; update p95 1.3 ms. + +Every checkpoint had zero pending teardown/retirement, staged upload work, and +composite warmup work. Neither run found unconfounded canonical owner growth, +and both passed the unchanged process-residency and performance limits. + +The first connected implementation run also proved that exact cache equality +was the wrong leak predicate: visible landblocks and authoritative entities +changed while mesh/GPU/cache owner counts decreased through legitimate +retirement. The corrected contract therefore hard-fails owner *growth* when +the workload is stable, reports named growth warnings when the authoritative +or visible workload changed, and permits shrinking. It does not weaken the +process limits or hide an identified owner leak. diff --git a/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-l-closeout.md b/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-l-closeout.md index a4c24a8d..0bb1d4be 100644 --- a/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-l-closeout.md +++ b/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-l-closeout.md @@ -1,14 +1,15 @@ # GameWindow Slice 8 Checkpoint L — campaign closeout -**Status:** Active 2026-07-22. +**Status:** Automated closeout complete 2026-07-22; final user visual matrix +pending. **Parent:** [`2026-07-22-gamewindow-slice-8-composition-lifecycle.md`](2026-07-22-gamewindow-slice-8-composition-lifecycle.md), -Checkpoint L. +Checkpoint L. **Integrated baseline:** `6c5e0604`; Checkpoints A–K are implemented. `GameWindow.cs` is 1,622 raw lines, App Release passes 3,451 tests / 3 intentional skips, and the complete Release suite passes 7,823 tests / 5 intentional skips. Two fresh-process canonical nine-stop soaks pass with -graceful exits and the unchanged residency/performance limits. +graceful exits and the unchanged residency/performance limits. **Behavior rule:** L proves and records the shipped ownership state. It may correct documentation, test/gate coverage, or a defect demonstrated by the audit, but it does not add gameplay, alter retail behavior, loosen a gate, or @@ -124,3 +125,36 @@ spellbook panel; outdoor/building/dungeon/portal/paperdoll/particle/alpha presentation; graceful close and fresh reconnect. Only that confirmation marks L and the overall structural campaign complete. +## 5. Automated closeout evidence + +- The final host is 1,622 raw lines. Source-boundary inspection finds no AC + algorithm, packet builder, entity scan, render graph, animation-part + composer, or stored `GameWindow` back-reference in an extracted owner. +- All 293 focused Slice 8 ownership, composition, callback, frame, lifetime, + automation, and source-boundary tests pass. App Release passes 3,451 tests / 3 + intentional skips; the complete Release suite passes 7,823 / 5. The build's + 17 test-project warnings are the unchanged #228 set. +- The connected lifecycle/reconnect gate passed in 314.4 seconds with graceful + capped and uncapped exits. Its uncapped reconnect reached 174.74 FPS / 5.72 + ms at the final checkpoint. All six PNG artifacts are valid; the only route + warning is the expected 25 world-edge empty-landblock misses. +- Both Checkpoint-K nine-stop reports passed in about 403 seconds, produced the + exact names/sequences/process identity, and found no unconfounded canonical + owner growth under the unchanged residency/performance limits. +- The six current lifecycle PNGs were compared against artifacts rebuilt from + exact accepted Slice 7 commit `9d7df1bf` in an isolated worktree. The five + deterministic destinations preserve geometry, UI/paperdoll layering, + private viewports, depth/alpha, and world reveal. Facility Hub was nearly + pixel-identical (mean absolute RGB delta 0.91/255); the Aerlinthe captures + were 3.42 and 3.87/255. Holtburg and reconnect differences are live + entities, particles, vitals, and sub-frame camera timing. Capped login used a + different server-saved location and was checked only for complete rendering + and presentation layering. +- Three corrected-diff reviews are clean: behavior/retail boundary, + architecture/ownership, and adversarial lifecycle/failure handling. The + divergence audit found no new runtime behavior in K or L and requires no + register change. + +The generated reports, screenshots, and disposable baseline worktree are +untracked evidence. The user's unrelated `TransitionTypes.cs` edit was not +modified or staged. diff --git a/docs/plans/2026-07-22-gamewindow-slice-8-composition-lifecycle.md b/docs/plans/2026-07-22-gamewindow-slice-8-composition-lifecycle.md index 59e880d3..da294d24 100644 --- a/docs/plans/2026-07-22-gamewindow-slice-8-composition-lifecycle.md +++ b/docs/plans/2026-07-22-gamewindow-slice-8-composition-lifecycle.md @@ -1,6 +1,7 @@ # GameWindow Slice 8 — composition and lifecycle shell -**Status:** Active 2026-07-22. +**Status:** Automated implementation and closeout complete 2026-07-22; final +user visual matrix pending. **Parent program:** [`docs/architecture/code-structure.md`](../architecture/code-structure.md), Slice 8. **Baseline:** `96f8bfcf`; `GameWindow.cs` is 4,666 raw lines, 196 fields, and 70 methods. The Release suite passes 7,341 tests / 5 fixture or environment @@ -35,19 +36,21 @@ audit. - [x] J — move the exact retryable shutdown manifest to a focused lifetime owner and prove all partial-load/reentrant/retry paths. Detailed plan: [`2026-07-22-gamewindow-slice-8-checkpoint-j-lifetime-shutdown.md`](2026-07-22-gamewindow-slice-8-checkpoint-j-lifetime-shutdown.md). -- [ ] K — in a separate #232 commit, add canonical owner snapshots to every soak +- [x] K — in separate #232 commits, add canonical owner snapshots to every soak checkpoint without weakening the process-memory guard. Detailed plan: [`2026-07-22-gamewindow-slice-8-checkpoint-k-canonical-soak.md`](2026-07-22-gamewindow-slice-8-checkpoint-k-canonical-soak.md). - [ ] L — corrected-diff reviews, focused and full Release gates, connected - lifecycle/soak, framebuffer comparison, documentation, memory, and final - visual handoff. Detailed plan: + lifecycle/soak, framebuffer comparison, documentation, and memory are + complete; only the final user visual handoff remains. Detailed plan: [`2026-07-22-gamewindow-slice-8-checkpoint-l-closeout.md`](2026-07-22-gamewindow-slice-8-checkpoint-l-closeout.md). -Checkpoint J leaves `GameWindow.cs` at 1,625 raw lines. The focused lifetime -owner now holds the typed shutdown roots, exact 18-stage dependency manifest, +Checkpoint K leaves `GameWindow.cs` at 1,622 raw lines. The focused lifetime +owner holds the typed shutdown roots, exact 18-stage dependency manifest, retry/no-replay state, structured soft-cleanup failures, hard-barrier fallback, -and native-window-last release. App Release passes 3,441 tests / 3 skips and -the complete Release suite passes 7,813 / 5 skips. Checkpoint K is next. +and native-window-last release. Deferred same-frame checkpoint capture and two +fresh-process nine-stop routes close #232 without weakening the residency +guard. App Release passes 3,451 tests / 3 skips and the complete Release suite +passes 7,823 / 5 skips. All automated Checkpoint-L gates are complete. Each checked checkpoint lands as a bisectable commit. A checkpoint is not done while a new class delegates a substantial body back into `GameWindow`, stores @@ -704,6 +707,14 @@ complete Release suite passes 7,813 / 5 skips. residency guard with unchanged thresholds. Require two fresh-process clean route runs before closing #232. +Result: deferred acknowledged checkpoints now drain after current-frame render +diagnostics, persist the exact frame outcome plus canonical resource owners, +and block the script until both artifacts commit. Seventy-four focused tests, +App Release, the full Release suite, and two 403-second fresh-process routes +pass. Every route produced the exact nine checkpoints, zero pending/staged/ +warmup work, no unconfounded canonical owner growth, graceful exit, and the +unchanged process/performance limits. Commits: `bca41487`, `6c5e0604`. + ### L — final closeout - Run three independent corrected-diff reviews: retail conformance, @@ -717,6 +728,14 @@ complete Release suite passes 7,813 / 5 skips. - Update architecture, milestones, roadmap, issues, AGENTS/CLAUDE, and durable memory with final metrics and exact gates. +Automated result: 293 focused tests and the 7,823/5 complete Release suite +pass. The 314.4-second capped/reconnect lifecycle route passes with six valid +PNGs and graceful exits. Its current deterministic frames preserve Slice 7 +commit `9d7df1bf` geometry, UI/paperdoll layering, private viewports, +depth/alpha, and reveal; live entity/particle/vitals/camera timing account for +the accepted differences. All three final corrected-diff reviews are clean. +The user's connected visual matrix is the sole remaining acceptance item. + ## 5. Automated acceptance - exact window callback attach order, reverse detach, rollback, reentrancy, and diff --git a/memory/project_gamewindow_decomposition.md b/memory/project_gamewindow_decomposition.md index cca15fc2..e9fea187 100644 --- a/memory/project_gamewindow_decomposition.md +++ b/memory/project_gamewindow_decomposition.md @@ -2,11 +2,12 @@ ## Current state -The behavior-preserving App ownership campaign is complete through Slice 7 and -Slice 8 checkpoints A–H. `GameWindow.cs` moved from the 2026-07-21 baseline of -15,723 lines / 278 fields / 205 methods to 3,689 lines / 162 fields / 37 -methods: 12,034 lines (76.5%) were removed without changing accepted gameplay -or rendering behavior. +All eight behavior-preserving App ownership slices and their automated closeout +are complete. `GameWindow.cs` moved from the 2026-07-21 baseline of 15,723 +lines / 278 fields / 205 methods to a 1,622-line native +composition/callback shell: 14,101 lines (89.7%) were removed without changing +accepted gameplay or rendering behavior. Only the user's final connected +visual matrix remains before the campaign is marked complete. | Slice | Ownership moved out | Closeout size | |---|---|---:| @@ -21,6 +22,9 @@ or rendering behavior. | 8 F | sole gameplay action route, typed commands, retained-root callback lifetime | 4,057 / 198 / 54 | | 8 G | pre-window/runtime settings ownership, one startup snapshot, inert late target binding | 3,663 / 162 / 37 | | 8 H | render/UI/frame/portal resource roots plus checked retryable GL leaves | 3,689 / 162 / 37 | +| 8 I | executable ordered startup composition and terminal session start | 1,945 / startup shell | +| 8 J | retryable typed lifetime/shutdown owner | 1,625 / lifetime shell | +| 8 K–L | acknowledged canonical soak capture and automated closeout | 1,622 / native shell | Slice 8 is an ordered checkpoint campaign rather than another feature-body move. A froze/pruned the shell boundary; B gave all nine native window callback @@ -141,6 +145,23 @@ review rule live in `docs/architecture/code-structure.md`. ## Accepted verification +- Final automated closeout: 293 focused Slice 8 tests pass; App Release passes + 3,451 / 3 intentional skips; the complete Release suite passes 7,823 / 5. + The Release build retains only the 17 pre-existing test-project warnings + tracked by #228. Behavior/retail, architecture/ownership, and adversarial + failure reviews are clean. +- Checkpoint K (`bca41487`, `6c5e0604`): two fresh-process 403-second + nine-stop soaks produce the exact ordered same-frame canonical checkpoints, + zero pending teardown/retirement/staging/warmup work, no unconfounded owner + growth, unchanged process/performance gates, and graceful exits. #232 is + closed. +- Checkpoint L connected lifecycle/reconnect passes in 314.4 seconds with six + valid PNGs and graceful capped/uncapped exits. The uncapped final checkpoint + is 174.74 FPS / 5.72 ms. Frames reconstructed from exact Slice 7 commit + `9d7df1bf` preserve deterministic geometry, UI/paperdoll layering, private + viewports, depth/alpha, and world reveal; remaining differences are live + entities, particles, vitals, and sub-frame camera timing. + - Slice 8 Checkpoint H: 61 focused ownership/lifetime tests pass; App Release passes 3,236 tests / 3 intentional skips. Four corrected-diff cycles closed every architecture, retail, and adversarial finding; all three final reviews @@ -177,11 +198,10 @@ review rule live in `docs/architecture/code-structure.md`. 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. +- Two Slice-7 identical-binary runs exceeded the coarse process-residency + threshold while deterministic ownership/lifecycle/timing checks passed. + Checkpoint K closed #232 by adding canonical owner snapshots; it did not + loosen the process threshold or treat residency alone as an identified leak. - The 18–33 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 @@ -189,13 +209,12 @@ review rule live in `docs/architecture/code-structure.md`. ## Next work -Slice 8 checkpoints I–L group the remaining ordered startup composition, -shutdown wiring, canonical soak snapshots, and closeout and reduce Silk callbacks to -narrow calls into input, update, render, resize, focus, and shutdown owners. -It removes leftover feature state only where Slices 1–7 already established a -canonical owner; it does not redesign gameplay, rendering, or resource lifetime. -The reviewed A–L execution ledger is -`docs/plans/2026-07-22-gamewindow-slice-8-composition-lifecycle.md`. +Run the final connected visual matrix: first login/radar; movement, mouse, +resize, focus, and combat; shared inventory/skills/spellbook panel; outdoor, +building, dungeon, portal, paperdoll, particle, and alpha presentation; then +graceful close and fresh reconnect. After user confirmation, mark Checkpoint L +and the campaign complete and resume M4. Full `GameEntity` aggregation remains +a separate migration and must not be folded into the visual handoff. ## Do not retry @@ -207,7 +226,9 @@ The reviewed A–L execution ledger is - 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. +- Do not revert Checkpoint K to exact cache equality: normal retirement may + shrink owners, and visible/server workload changes may change populations. + Hard-fail owner growth only when workload is stable, name workload-confounded + growth explicitly, and preserve the unchanged process-residency limits. - Small value/policy callbacks and diagnostics are acceptable only when they do not call a substantial window body or hide mutable ownership.