acdream/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-i8-frame-roots-session-start.md

# GameWindow Slice 8 — Checkpoint I.8 Frame Roots and Session Start

**Status:** Active — I.8a–I.8b complete; I.8c terminal start next

**Parent:** `2026-07-22-gamewindow-slice-8-checkpoint-i-ordered-composition.md`

**Scope:** Complete Phase 7's session-facing owners, then implement ordered
composition Phases 8 and 9.

## 1. Outcome

Finish the production startup graph without changing accepted input, update,
render, network, portal, or UI behavior:

1. complete Phase 7 before any frame root is visible;
2. construct update and render roots locally and publish the pair atomically;
3. start the optional live session as the absolute final startup operation.

The current ordering defect is structural: `GameWindow.OnLoad` publishes the
frame pair before the combat/diagnostic command targets and sole gameplay input
subscriber are attached. I.8 moves those pre-frame owners into the Phase-7
result, so native callbacks can never observe an incomplete input/command
graph.

This is an ownership move. Retail algorithms and wire behavior remain
unchanged, so no divergence-register row is added.

## 2. I.8a — complete session/player composition

**Completed 2026-07-22.** `LiveSessionRuntimeFactory` now owns the exact
reset/router/command graph without a window reference. Phase 7 publishes the
session host, exact-owner combat and diagnostic command bindings, and the sole
gameplay input subscriber before Phase 8 can expose a frame root. Desired
components have a focused canonical snapshot owner. The component-lifecycle
handoff into the earlier live-presentation phase is an exact, retryable
adoption lease, so any later Phase-7 fault rolls it back without stranding or
replaying teardown.

### 2.1 Focused session runtime factory

Add `LiveSessionRuntimeFactory` under `AcDream.App/Net`. It owns the existing
domain-specific construction of:

- `LiveSessionHostBindings`;
- reset manifest bindings;
- selection and entered-world callbacks;
- event and command routers;
- inventory, character, and social session bindings.

The factory receives focused owners and state slots, never `GameWindow` and
never a callback to a substantial window method. Move the existing reset and
router bodies verbatim. Preserve the exact reset order and the existing
retail citations around player-module identity/shortcut/component cleanup.

Add `DesiredComponentSnapshotState` beside `ShortcutSnapshotState` so session
routers mutate one focused state owner. `GameWindow.DesiredComponents` remains
an ABI-compatible read-only projection over that owner. Existing
`LocalPlayerIdentityState`, `LocalPlayerControllerSlot`, and
`ShortcutSnapshotState` remain canonical; no mirrored values are introduced.

### 2.2 Commands and sole gameplay subscriber

At the tail of `SessionPlayerCompositionPhase`, after player mode and teleport
exist but before result publication:

1. create `LiveSessionHost` through the focused factory;
2. create and bind `LiveCombatModeCommandController`;
3. create and bind `RuntimeDiagnosticCommandController`;
4. create `GameplayInputCommandController` and priority targets;
5. create and attach the sole `GameplayInputActionRouter`.

Add exact-owner `BindOwned` tokens to the combat and diagnostic command slots.
The existing gameplay router already owns both subscriptions transactionally;
Phase 7 scope-owns it immediately after construction and before `Attach`.

Extend `SessionPlayerResult` and its publication seam with the exact
`LiveSessionHost`, command owners, and optional gameplay router. Publication
rejects replacement before changing any field. Failure before publication
disposes the router, detaches command targets, and rolls back the existing
Phase-7 suffix in reverse order.

## 3. I.8b — atomic frame-root composition

**Completed 2026-07-22.** `FrameRootCompositionPhase` now constructs the
unchanged render and update graphs from explicit prior-phase results and
focused runtime owners. `GameFrameGraphSlot.PublishOwned` publishes and
withdraws one exact pair. Optional lifecycle automation has a Phase-8 binding
owner, and `WorldLifecycleResourceSnapshotSource` samples the same canonical
owners without window callbacks or mirrored counters. The Phase-8 contract now
receives the Phase-2 content result explicitly because scripts and particles
are real frame dependencies; this removes a hidden reach-back through the
window shell.

Add `FrameRootCompositionPhase` implementing the existing
`IFrameRootCompositionPhase` contract. Its dependencies are focused App owners;
prior phase results supply all resources created during startup.

Preserve the exact current construction order:

1. teleport/login/GL-state and render-live preparation;
2. render resource begin/clear/live phases;
3. weather, sky-PES, world environment, camera, visibility, settings preview,
   root, animated-object, and building sources;
4. terrain, PView, scene-pass, and world-scene diagnostics;
5. optional lifecycle automation;
6. retained/devtools/private presentation;
7. render orchestrator;
8. live-frame coordinator, camera frame, and update orchestrator;
9. atomic update/render pair publication as the final Phase-8 action.

Add `GameFrameGraphSlot.PublishOwned`. Its lease withdraws only the exact pair
it published, is idempotent, and cannot withdraw a later replacement. Scope-own
the lease immediately. A failure before publication leaves the slot empty; a
failure after publication withdraws the exact pair unless result publication
has transferred lifetime to the window shutdown owner.

### 3.1 Automation and resource snapshots

Add `WorldLifecycleResourceSnapshotSource` now rather than retaining
`CaptureWorldLifecycleResourceSnapshot` on the window. It samples the same
canonical world, live-runtime, effect, particle, light, script, mesh, texture,
GPU-memory, managed-memory, render-diagnostic, and frame-profiler owners.

This advances the owner-extraction portion of Checkpoint K; K still changes
checkpoint timing, acknowledgement barriers, JSONL validation, and soak
comparison. No checkpoint semantics change in I.8.

`FrameRootRuntimeBindings` owns the optional automation late binding and any
other Phase-8 external edge. It uses reverse, retryable, no-replay cleanup.
Shutdown withdraws the frame graph first, then detaches these frame-owned
bindings before borrowed session/presentation owners retire.

### 3.2 Publication

`FrameRootResult` contains:

- exact update and render roots;
- optional lifecycle automation owner;
- Phase-8 runtime bindings;
- the `LiveSessionHost` borrowed from Phase 7 for terminal start.

`IGameWindowFrameRootPublication` stores only owners needed by steady-state or
shutdown. Replacement is rejected atomically.

## 4. I.8c — terminal start and window cutover

Add `SessionStartCompositionPhase` implementing
`ISessionStartCompositionPhase<FrameRootResult>`. It invokes only
`LiveSessionHost.Start(RuntimeOptions)` and preserves the existing diagnostics
for missing credentials and failed startup.

`GameWindow.OnLoad` ends with:

```text
Phase 7 Compose
Phase 8 Compose and atomic pair publication
Phase 9 Start
return
```

There is no callback attachment, binding, publication, diagnostics setup, or
other work after Phase 9. Delete the old inline frame construction, session
factory/reset/router methods, snapshot method, and terminal status switch.

The existing typed nine-phase `GameWindowCompositionPipeline` remains the
executable order/failure oracle. Production `OnLoad` uses the same phase
interfaces and result chain explicitly because later-phase dependency records
are assembled from earlier concrete results; it must not introduce a retained
mega-context, service locator, or delegate façade around `GameWindow`.

## 5. Ownership and rollback order

Before frame publication, Phase-7 rollback is:

1. gameplay router detach;
2. diagnostic and combat command unbind;
3. remaining session/player bindings;
4. teleport, live session, and streamer teardown.

After frame publication, Phase-8 rollback is:

1. exact frame-pair withdrawal;
2. automation/other frame binding detach;
3. no disposal of resources borrowed from earlier successful phases.

Normal shutdown retains the frozen barrier order:

1. logical input/command quiescence;
2. live-session convergence;
3. physical input callback detach;
4. frame-pair withdrawal;
5. frame then session/player late-binding detach;
6. remaining session, live-entity, effect, render, content, GL, and native
   owners.

## 6. Automated gates

### Session/runtime

- exact live-session host construction and reset trace;
- no `GameWindow` field or delegate capture in the focused factory;
- exact-owner combat/diagnostic bind, competing-owner rejection, idempotent
  release, and rebind;
- gameplay router attaches before frame publication and rolls back from either
  partial subscription;
- failed Phase-7 publication leaves no command/input/session target behind.

### Frame roots

- exact render/update leaf construction order;
- frame slot is empty at every pre-publication fault;
- exact pair publishes once and both native callbacks see the same generation;
- rollback withdraws only the published pair and never a later replacement;
- automation disabled path acquires nothing;
- automation enabled path binds once, detaches exactly, and samples the same
  resource values as the former window method;
- frame result publication rejects replacement atomically.

### Terminal start and structure

- terminal start runs only after frame publication and every input/command
  attachment;
- missing credentials and failed starts preserve current diagnostics;
- no operation follows `Start`;
- `GameWindow` contains no live-session binding factory, frame-root
  construction body, resource-snapshot algorithm, or direct frame-pair
  publication;
- no backend dependency enters Core and panels remain on UI abstractions;
- App Release tests, clean solution Release build, and complete Release suite
  pass;
- behavior/order, architecture/ownership, and adversarial failure reviews are
  clean.

## 7. Commit sequence

1. `docs(architecture): plan frame roots and terminal session start`
2. `refactor(app): complete session startup composition`
3. `refactor(app): compose atomic frame roots`
4. `refactor(app): make session start terminal`

Each implementation commit is independently buildable and preserves the
protected pre-existing `TransitionTypes.cs`, `.test-out/`, and `logs/` changes.
I.9 performs the complete Checkpoint-I corrected-diff review and documentation
closeout after these cuts land.