acdream/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-h-resource-ownership.md

# GameWindow Slice 8 — Checkpoint H Resource Ownership Plan

## Objective

Replace the remaining implicit, constructor-local, and nullable-field resource
ownership in `GameWindow` with explicit single-owner transactions. This is a
behavior-preserving lifetime cutover: draw/update order, portal presentation,
retained UI behavior, settings behavior, and the frozen shutdown order do not
change.

Checkpoint H does not move the complete shutdown manifest; that is Checkpoint
J. It supplies the typed roots and retry semantics that J will consume.

## Frozen invariants

1. Every GL/kernel-owning object is published to exactly one owner immediately
   after successful construction.
2. Renderers borrow the terrain atlas and dedicated sky shader. They never
   dispose those resources. The renderer borrower retires before the sole
   resource owner releases the borrowed atlas/shader.
3. A leaf factory that throws before returning must release every GL name it
   created. Outer phase/lifetime rollback cannot recover a name that was never
   published.
4. Bindless residency is a resource prefix: partial handle acquisition rolls
   back, successful non-residency is not replayed after a later failure, and
   textures are not deleted while a resident handle remains.
5. Retained UI input is quiesced before the live-session barrier and physically
   detached afterward, independently of runtime/host disposal.
6. Exactly one retained-UI ownership chain exists. Before runtime construction
   the lease owns the `UiHost`; after a runtime object is published the lease
   retains that exact partial/full runtime and delegates final disposal to it.
   Constructor or initialization failure never leaves a host in a local only.
7. Update and render roots publish atomically as one frame graph. Silk callbacks
   resolve only through the slot; an empty/withdrawn slot is safely inert.
8. Portal tunnel ownership starts in one fallback slot. Transfer clears the
   fallback only after the complete local-teleport controller factory returns;
   any earlier failure leaves the same tunnel reachable by shutdown.
9. Successful disposal is never replayed. Failed disposal remains retryable.
   Terminal abandonment is explicit and retains references for native/process
   fallback rather than silently losing ownership.

## Typed owners

### `OwnedResourceSlot<T>` and `GameRenderResourceLifetime`

- `OwnedResourceSlot<T>` acquires through a factory, rejects duplicate
  publication, exposes a typed borrower, and clears ownership only after
  `Dispose` succeeds.
- `GameRenderResourceLifetime` contains separate slots for `TerrainAtlas` and
  the dedicated sky `Shader`.
- `GameWindow` acquires both through this owner. Shutdown releases the sky
  renderer and terrain renderer first, then the two resource slots, then GL.

### `RetailUiRuntimeLease`

- The lease exists before `OnLoad` and acquires the `UiHost` through a factory.
- Runtime construction and initialization are separate. The runtime is stored
  in the lease before initialization begins.
- Initialization failure attempts immediate cleanup. Successful cleanup
  rethrows the original initialization error; cleanup failure reports both and
  leaves the exact runtime in the lease for lifetime retry.
- The lease exposes idempotent `QuiesceInput` and retryable `DeactivateInput`
  operations against the retained host.
- If no runtime was constructed, lease disposal directly disposes the host. If
  a runtime exists, runtime disposal remains the one path that disposes the
  host. There are never two host disposers.
- Explicit terminal abandonment is allowed only after a failed disposal pass;
  it makes later disposal inert while retaining the unresolved references for
  the native/process fallback handled by Checkpoint J.

### `GameFrameGraphSlot`

- `IGameUpdateFrameRoot` and `IGameRenderFrameRoot` are the narrow frame seams.
- `UpdateFrameOrchestrator` and `RenderFrameOrchestrator` implement those seams.
- `Publish(update, render)` is atomic and one-shot until withdrawal.
- `Tick`/`Render` are inert before publication and after withdrawal.
- Shutdown withdraws the pair only after live-session convergence and before
  any frame borrower retires.

### `TransferableResourceSlot<T>`

- `Acquire` owns one fallback resource.
- `Transfer(factory)` retains fallback ownership while the complete destination
  factory runs and clears it only after that factory returns successfully.
- Failed acquisition, resource preparation, destination construction, binding,
  and normal shutdown prefixes are covered without double disposal.

## Exception-safe GL leaves

### Shader program construction

`ShaderProgramConstruction` uses a narrow `IShaderProgramBuildApi`. It tracks
the vertex shader, fragment shader, and linked program as soon as each name is
returned. Compile, attach, link, detach, or cleanup failure attempts every
remaining rollback operation. A clean rollback preserves the original failure;
rollback failures are aggregated with it. `Shader.Dispose` becomes idempotent
and retryable.

### Terrain atlas construction and residency

`GlTextureConstructionTransaction` tracks every texture name allocated by
terrain, alpha, and fallback paths. `TerrainAtlas.Build`, `BuildAlphaAtlas`, and
`BuildFallback` allocate only through that transaction. The transaction commits
only after the complete `TerrainAtlas` object exists; failure rolls back all
names in reverse acquisition order and reports cleanup failures with the
original error.

`BindlessTexturePair` owns the terrain/alpha residency pair. Partial acquisition
releases the first handle. Release attempts both handles, remembers successful
substeps, and is retryable. `TerrainAtlas.Dispose` releases residency first,
then independently deletes both texture names through the existing retryable
shutdown transaction.

## Production integration order

1. Construct render-resource lifetime, UI lease, frame slot, and portal
   fallback slot before `Window.Create`/`OnLoad` acquisitions.
2. Acquire the atlas through `GameRenderResourceLifetime`; construct
   `TerrainModernRenderer` as a borrower.
3. Acquire `UiHost` through `RetailUiRuntimeLease`, wire input/assets, construct
   and publish `RetailUiRuntime` before initialization, then expose host/runtime
   only as borrower aliases.
4. Acquire/prepare portal presentation in the fallback slot.
5. Acquire the dedicated sky shader through the render-resource lifetime, then
   construct `SkyRenderer` as a borrower.
6. Transfer the portal fallback only through the complete
   `LocalPlayerTeleportController` factory.
7. Construct update/render roots as locals and publish them atomically through
   `GameFrameGraphSlot`.
8. Update/render callbacks resolve only through the slot.
9. Shutdown quiesces/deactivates UI through the lease, withdraws frame roots,
   disposes the UI lease and renderer borrowers, releases atlas/sky roots, then
   reaches GL.

## Automated gates

- owned-resource acquire/borrow/release, duplicate acquire, transient failure,
  retry, and no replay;
- UI host acquisition, runtime constructor failure, Initialize failure with
  successful cleanup, transient cleanup then lifetime retry, persistent cleanup
  then explicit abandonment, separate input quiescence/deactivation, and exact
  host disposal count;
- frame pair atomic publication, duplicate publication, update/render routing,
  withdrawal, pre-publication/post-withdrawal silence, and republish policy;
- portal fallback acquisition/preparation/transfer failures plus successful
  transfer and every shutdown prefix, with exact one-resource disposal;
- vertex/fragment compile failure, program creation/link failure, and cleanup
  failure after every created shader/program name;
- terrain/alpha/fallback texture allocation and upload failure after every
  created name, reverse rollback, cleanup aggregation, and committed-name
  non-deletion;
- bindless first/second acquisition failure, release partial failure/retry, and
  no deletion before residency release;
- source boundary proves direct frame-root fields, constructor-local atlas/sky
  ownership, direct UI host/runtime ownership, and nullable portal fallback are
  removed from `GameWindow`;
- focused App tests, production App Release build, solution Release build, and
  complete Release suite.

## Review and commit gate

The existing architecture/integration, retail-conformance, and adversarial
reviewers inspect the complete tracked and untracked diff independently. Every
confirmed finding is corrected and all three repeat until clean. Architecture,
roadmap, milestones, issues, memory, `CLAUDE.md`, and `AGENTS.md` are reconciled
in the same bisectable Checkpoint H commit.

## Implementation result — 2026-07-22

Checkpoint H landed the planned ownership graph without changing the accepted
update/render order or gameplay behavior:

- `GameRenderResourceLifetime` owns the terrain atlas and dedicated sky shader;
  renderers borrow them and retire first.
- `RetailUiRuntimeLease` owns Host/runtime construction, initialization, input
  cutoff, retryable disposal, and explicit terminal abandonment as one chain.
- `GameFrameGraphSlot` publishes update/render roots atomically and makes empty
  or withdrawn callbacks inert.
- `TransferableResourceSlot.AcquirePrepared` publishes the portal presentation
  before mesh preparation, retries the same partial resource, and refuses
  transfer until preparation has committed.
- GL name creation records the returned name before post-command validation.
  Shader/program, texture, text-renderer, buffer/VAO, bindless-residency, and
  texture-binding operations advance ownership only after an always-on checked
  GL commit boundary.
- Failed construction cleanup is retained by `GlConstructionCleanupLedger`;
  exact pending names and binding-restore obligations remain retryable, while
  successful cleanup stages never replay.

Four corrected-diff cycles closed issues found by the architecture, retail,
and adversarial reviewers: partial bindless mutation, lost GL rollback names,
constructor-local text resources, reentrant UI ownership, portal preparation,
unchecked production GL calls, leaked texture binding, and the bindless post-
commit verification gap. All three final reviews are clean.

Automated acceptance:

- focused Checkpoint H ownership/lifetime gate: 61 passed;
- App Release suite: 3,236 passed / 3 intentional skips;
- production App Release build: zero warnings and zero errors;
- complete solution Release suite: 7,606 passed / 5 intentional skips; solution
  build has zero errors and the 17 existing test-project warnings tracked by
  #228;
- `GameWindow.cs`: 3,689 raw lines / 162 fields / 37 methods, versus 15,723 /
  278 / 205 at the campaign baseline.

No AC-specific algorithm or intended retail behavior changed, so Checkpoint H
adds no retail-divergence row. Checkpoint I is the next active unit.