From ed9dc36643be230135c94fbd4b94b97da44573ed Mon Sep 17 00:00:00 2001 From: Erik Date: Tue, 21 Jul 2026 12:44:48 +0200 Subject: [PATCH] docs(architecture): close live-session ownership slice --- AGENTS.md | 18 ++++--- CLAUDE.md | 18 ++++--- docs/ISSUES.md | 3 +- docs/architecture/acdream-architecture.md | 12 +++-- docs/architecture/code-structure.md | 47 ++++++++++++------- docs/plans/2026-04-11-roadmap.md | 16 +++++-- docs/plans/2026-05-12-milestones.md | 7 +-- ...6-07-21-gamewindow-slice-3-live-session.md | 9 +++- 8 files changed, 80 insertions(+), 50 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6a5b179b..898b51c1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -115,19 +115,17 @@ 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; 6,575 tests pass / 5 skip (17 tracked warnings, #228). +Release builds; 6,714 tests pass / 5 skip. **Active prerequisite before new M4 subsystem work:** continue the behavior-preserving `GameWindow` decomposition reconciled on 2026-07-21. -Selection/interaction Slice 1 is complete: `WorldSelectionQuery` and -`SelectionInteractionController` own the domain, exact-incarnation queued work, -and retail's shared inventory-request transaction. Live-animation-presentation -Slice 2 is also complete: `LiveEntityAnimationPresenter` owns final visual and -rigid PartArray composition, effect poses, and MotionDone; scheduler handoffs -are incarnation-, clock-, projection-, and appearance-bound. `GameWindow` is -14,546 lines, 277 fields, and 190 methods. Slice 3 completes live-session -ownership next; later slices finish live-entity App integration, landblock -presentation, update/render orchestration, and composition cleanup. +Selection/interaction Slice 1, live-animation-presentation Slice 2, and +complete live-session ownership Slice 3 are landed. `LiveSessionController` +now owns the exact resolve/connect/enter/tick/reconnect/graceful-close +generation; GameWindow has no parallel session/router/command fields or old +lifecycle bodies. `GameWindow` is 14,310 lines, 274 fields, and 190 methods. +Slice 4 extracts live-entity App integration next; later slices finish +landblock presentation, update/render orchestration, and composition cleanup. See `docs/architecture/code-structure.md`. **Carried:** #153, #116, remaining R6 ownership cleanup, TS-50/TS-51, Modern Pipeline MP1b+, and #225's lifestone/particle alpha visual gate. diff --git a/CLAUDE.md b/CLAUDE.md index 2ed93be2..a1743ce6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -113,19 +113,17 @@ 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; 6,575 tests pass / 5 skip (17 tracked warnings, #228). +Release builds; 6,714 tests pass / 5 skip. **Active prerequisite before new M4 subsystem work:** continue the behavior-preserving `GameWindow` decomposition reconciled on 2026-07-21. -Selection/interaction Slice 1 is complete: `WorldSelectionQuery` and -`SelectionInteractionController` own the domain, exact-incarnation queued work, -and retail's shared inventory-request transaction. Live-animation-presentation -Slice 2 is also complete: `LiveEntityAnimationPresenter` owns final visual and -rigid PartArray composition, effect poses, and MotionDone; scheduler handoffs -are incarnation-, clock-, projection-, and appearance-bound. `GameWindow` is -14,546 lines, 277 fields, and 190 methods. Slice 3 completes live-session -ownership next; later slices finish live-entity App integration, landblock -presentation, update/render orchestration, and composition cleanup. +Selection/interaction Slice 1, live-animation-presentation Slice 2, and +complete live-session ownership Slice 3 are landed. `LiveSessionController` +now owns the exact resolve/connect/enter/tick/reconnect/graceful-close +generation; GameWindow has no parallel session/router/command fields or old +lifecycle bodies. `GameWindow` is 14,310 lines, 274 fields, and 190 methods. +Slice 4 extracts live-entity App integration next; later slices finish +landblock presentation, update/render orchestration, and composition cleanup. See `docs/architecture/code-structure.md`. **Carried:** #153, #116, remaining R6 ownership cleanup, TS-50/TS-51, Modern Pipeline MP1b+, and #225's lifestone/particle alpha visual gate. diff --git a/docs/ISSUES.md b/docs/ISSUES.md index b988fa83..e4ba7c64 100644 --- a/docs/ISSUES.md +++ b/docs/ISSUES.md @@ -27,7 +27,8 @@ What does NOT go here: ## Current queue — 2026-07-21 - **Active structural work:** `GameWindow` decomposition. Selection/interaction - ownership is complete; Slice 2 live animation presentation is next in + ownership, live animation presentation, and complete live-session ownership + are landed; Slice 4 live-entity App integration is next in [`docs/architecture/code-structure.md`](architecture/code-structure.md). This is the behavior-preserving prerequisite before new M4 feature bodies. - **Separate rendering gate:** `#225`, lifestone/particle alpha ordering. Its diff --git a/docs/architecture/acdream-architecture.md b/docs/architecture/acdream-architecture.md index 97e0556f..1b2c5e75 100644 --- a/docs/architecture/acdream-architecture.md +++ b/docs/architecture/acdream-architecture.md @@ -834,11 +834,13 @@ Current movement/collision ownership: Linux/headless extraction. - **The behavior-preserving thin-`GameWindow` ownership campaign is the active prerequisite before new M4 subsystem bodies.** Selection/interaction Slice 1 - landed 2026-07-21 with `WorldSelectionQuery`, - `SelectionInteractionController`, and the shared retail inventory-request - owner; live animation presentation is next. The reconciled ledger and - sequence live in `docs/architecture/code-structure.md`. This decision does - not reclassify the remaining L.2 conformance work or Track LH. + landed with `WorldSelectionQuery`, `SelectionInteractionController`, and the + shared retail inventory-request owner; Slice 2 moved final animation + presentation into `LiveEntityAnimationPresenter`; Slice 3 moved the complete + session generation into `LiveSessionController` plus its focused host and + routers. Slice 4 live-entity App integration is next. The reconciled ledger + and sequence live in `docs/architecture/code-structure.md`. This decision + does not reclassify the remaining L.2 conformance work or Track LH. Full `GameEntity` type aggregation remains a separate, higher-risk target after the thin-`GameWindow` campaign. The current campaign reuses canonical diff --git a/docs/architecture/code-structure.md b/docs/architecture/code-structure.md index cb96795c..0f1e6591 100644 --- a/docs/architecture/code-structure.md +++ b/docs/architecture/code-structure.md @@ -1,7 +1,7 @@ # acdream — code structure & extraction sequence **Status:** Living document. Created 2026-05-16; implementation reconciliation -completed 2026-07-21; Slices 1 and 2 landed the same day. This is the active +completed 2026-07-21; Slices 1–3 landed the same day. This is the active structural program 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 @@ -25,15 +25,16 @@ The structural debt is concentrated in **one file**: baseline cf50ee3d 15,723 lines / 278 fields / 205 methods after Slice 1 14,912 lines / 278 fields / 191 methods after Slice 2 14,546 lines / 277 fields / 190 methods +after Slice 3 14,310 lines / 274 fields / 190 methods ``` `GameWindow` is the single object that: - Owns the GL context, the window, input, and shaders. - Reads ~40 different environment variables across its lifetime. -- Still owns live-session bootstrap, character entry, roughly 440 lines of - event subscription, and most App-side packet handlers even though - `LiveSessionController` owns the socket/session shell. +- Composes the shipped `LiveSessionController`/host/router boundary; it no + longer owns a parallel session, command bus, subscription lifetime, connect, + character-entry, reconnect, or graceful-close body. - Owns the adapters that hydrate canonical `LiveEntityRuntime` records into animation, collision, rendering, and DAT-backed appearance resources. - Composes the shipped `WorldSelectionQuery` and @@ -187,6 +188,7 @@ src/AcDream.App/ │ └── Vfx/ # (already exists) ├── Net/ │ ├── LiveSessionController.cs # owns complete WorldSession connect/enter/logout/reconnect lifecycle +│ ├── LiveSessionLifecycleHost.cs # narrow App composition + exact borrowed-session attachment │ └── LiveSessionEventRouter.cs # typed subscriptions → focused domain handlers ├── Physics/ │ ├── ProjectileController.cs # canonical live-record projectile orchestration @@ -387,7 +389,7 @@ useful ordering seam, but its ownership status is **partial**. | Area | Status | Current truth | |---|---|---| | Startup options | **Complete** | `RuntimeOptions` owns startup configuration (`eda936dc`). Remaining direct environment reads are legacy runtime diagnostics, not startup configuration. | -| Network session | **Partial** | `LiveSessionController` owns endpoint resolution, `WorldSession` construction, ticking, and disposal (`0b25df53`). `TryStartLiveSession`, character choice/entry, session clearing, about 440 lines of subscriptions, and most App packet handlers remain in `GameWindow`. | +| Network session | **Complete** | `LiveSessionController` owns resolve/create/bind/Connect/selection/EnterWorld/Tick/stop/reconnect/disposal; `LiveSessionLifecycleHost` is the narrow App composition boundary; `LiveSessionEventRouter` and `LiveSessionCommandRouter` own exact inbound/outbound lifetimes. `GameWindow` retains one controller field and focused domain sink factories only (`d9ccf8a6`, `6a5d9e2e`). | | Live identity/lifetime | **Complete core owner** | `LiveEntityRuntime` owns incarnation identity, accepted snapshots/timestamps, runtime components, logical/spatial lifetime, and teardown. `GameWindow` still owns large hydration and wire-to-presentation adapter bodies. | | Inbound/object-frame order | **Partial** | `RetailInboundEventDispatcher`, `RetailLiveFrameCoordinator`, `LiveEntityAnimationScheduler`, `LiveEntityAnimationPresenter`, static scheduler, remote/projectile updaters, and teleport owners are shipped. `AdvanceLiveObjectRuntimeCore` retains the visible cross-owner order until Slice 6. | | World reveal | **Complete** | `WorldRevealCoordinator` owns login/portal readiness and reveal lifetime (`a4ef5788`). The accepted deterministic lifecycle trace did not change after extraction. | @@ -468,19 +470,32 @@ rigid trailing poses. `GameWindow` lost 366 lines, two methods, and one net field. Three independent retail, architecture, and adversarial review loops finished clean; focused App/Core tests and the complete App suite pass. -#### Slice 3 — complete live-session ownership — NEXT +#### Slice 3 — complete live-session ownership — COMPLETE 2026-07-21 -Expand `LiveSessionController` to own connect, character-list validation, -character selection, EnterWorld, graceful character logout, reconnect, and -session-scoped disposal. Add `LiveSessionEventRouter` for typed subscriptions; -it routes events to focused domain handlers and owns unsubscription, but owns -no entity or UI state. +Detailed execution plan: +[`docs/plans/2026-07-21-gamewindow-slice-3-live-session.md`](../plans/2026-07-21-gamewindow-slice-3-live-session.md). -Move `TryStartLiveSession`, `ClearInboundEntityState`, and -`WireLiveSessionEvents` out of `GameWindow`. Do not create a giant context bag -or a second world-state owner. The connected gate must prove login, fresh world -reveal, command/chat, portal, exact `0xF653` logout, ACE endpoint disconnect, -and fresh-process reconnect. +`LiveSessionController` now owns the complete resolve/create/bind/Connect/ +CharacterList/select/EnterWorld/Tick/stop/reconnect/dispose transaction. Exact +generation and operation-depth gates prevent synchronous lifecycle callbacks +from resurrecting a superseded session. Staged teardown makes commands inert, +detaches events, gracefully disposes the exact `WorldSession`, detaches the +host, and runs the full reset manifest to convergence before reuse. + +`LiveSessionLifecycleHost` is the narrow App adapter; the router and command +owners are transactional and session-bound. `GameWindow` lost `_liveSession`, +the router/command fields, and the old startup/reset/wiring/disposal methods. +Both UI stacks resolve `controller.Commands`; direct feature sends borrow +`CurrentSession` at call time. Forty-seven controller cases plus host, +transport-allocation, and structural gates cover failure/reentrancy/reuse. +Three independent retail, architecture, and adversarial reviews finished +clean. The Release suite passes 6,714 tests with five intentional skips. The +306-second connected lifecycle gate passed capped login, five travel/revisit +checkpoints, exact graceful close, and uncapped fresh-process reconnect; both +client processes exited normally. + +`GameWindow` fell another 236 lines and three fields to 14,310 lines / 274 +fields / 190 methods. Slice 4 is next. #### Slice 4 — extract live-entity App integration diff --git a/docs/plans/2026-04-11-roadmap.md b/docs/plans/2026-04-11-roadmap.md index f9353755..9deb537e 100644 --- a/docs/plans/2026-04-11-roadmap.md +++ b/docs/plans/2026-04-11-roadmap.md @@ -28,9 +28,19 @@ projection, object-clock, and appearance-revision tokens reject stale work; ordinary/static frame handoffs own their buffers; retail short AnimFrames retain trailing visible and rigid poses. `GameWindow` is now 14,546 lines. -**Next:** Slice 3 completes live-session ownership by moving connection, -character entry, typed event subscriptions, graceful logout, reconnect, and -session-scoped cleanup behind `LiveSessionController`/`LiveSessionEventRouter`. +Slice 3 complete live-session ownership landed 2026-07-21: one +`LiveSessionController` now owns resolve through graceful teardown/reconnect, +with exact-generation reentrancy gates, transactional typed routing, dynamic +UI command publication, and convergent session reset. The old GameWindow +session/router/command fields and lifecycle bodies are gone. `GameWindow` is +now 14,310 lines, 274 fields, and 190 methods; the Release suite passes 6,714 +tests with five intentional skips. Its connected gate passed capped login, +five travel/revisit checkpoints, graceful close, and uncapped fresh-process +reconnect in 306 seconds. + +**Next:** Slice 4 extracts live-entity App integration into focused hydration +and network-update controllers over the existing canonical +`LiveEntityRuntime`, without adding a second GUID or resource owner. 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 009d6bc8..51a2bb13 100644 --- a/docs/plans/2026-05-12-milestones.md +++ b/docs/plans/2026-05-12-milestones.md @@ -17,9 +17,10 @@ layer, the active structural prerequisite is the behavior-preserving `GameWindow` decomposition in [`docs/architecture/code-structure.md`](../architecture/code-structure.md). The 2026-07-21 audit baseline was 15,723 lines, 278 fields, and 205 methods. -Selection/interaction Slice 1 and live-animation-presentation Slice 2 are -complete. `GameWindow` is now 14,546 lines, 277 fields, and 190 methods. Slice 3 -— complete live-session ownership — is next. +Selection/interaction Slice 1, live-animation-presentation Slice 2, and +complete live-session ownership Slice 3 are complete. `GameWindow` is now +14,310 lines, 274 fields, and 190 methods. Slice 4 — live-entity App +integration — is active next. Carried: #153 far-teleport residual, #116 slide-response, the remaining R6 ownership cleanup plus diff --git a/docs/plans/2026-07-21-gamewindow-slice-3-live-session.md b/docs/plans/2026-07-21-gamewindow-slice-3-live-session.md index b4fc6b7c..d05095fd 100644 --- a/docs/plans/2026-07-21-gamewindow-slice-3-live-session.md +++ b/docs/plans/2026-07-21-gamewindow-slice-3-live-session.md @@ -1,6 +1,6 @@ # GameWindow Slice 3 — complete live-session ownership -**Status:** Active 2026-07-21. +**Status:** Complete 2026-07-21. **Parent program:** [`docs/architecture/code-structure.md`](../architecture/code-structure.md), Slice 3. **Baseline:** `9a150e24`; `GameWindow.cs` is 14,546 lines, 277 fields, and 190 methods before this slice. @@ -47,7 +47,12 @@ character-selection UI or redesign the transport. unified shutdown, and structural regression gates proving the displaced fields and lifecycle bodies remain absent. Three-agent review clean. Release: 6,714 passed / 5 skipped. -- [ ] F — final review, connected gate, and documentation closeout (in progress). +- [x] F — final review, connected gate, and documentation closeout. All three + independent review tracks finished clean. Release: 6,714 passed / 5 skipped. + The 306-second connected lifecycle gate passed capped login, five travel/ + revisit checkpoints, exact graceful exit, and uncapped fresh-process + reconnect; both client processes exited normally. The sole warning was 25 + expected world-edge landblock misses already classified by the gate. ## 1. Outcome