acdream/docs/plans/2026-07-20-automated-world-lifecycle-gate.md

# Automated world-lifecycle gate

**Status:** In progress (2026-07-20)
**Owner:** M3 stabilization / R6 rendering-lifecycle rebaseline
**Depends on:** `WorldRevealReadinessBarrier`, retained-UI automation,
`FrameProfiler`, connected local ACE

## Outcome

Create a deterministic connected Release gate that catches the structural
failures which previously required someone to stare at the client for several
minutes:

- the first login frame cannot expose world geometry before the destination's
  render meshes, composite textures, and collision data are all ready;
- every portal/recall lifetime crosses the same readiness edge, materializes
  once, and returns to the normal viewport once;
- dungeon entry and exit use the same lifecycle without grey frames,
  stale-source geometry, or an uncollidable destination;
- graceful logout followed by a fresh reconnect starts a new reveal lifetime
  and cannot inherit readiness or resources from the previous process;
- repeated destinations do not cause cumulative memory, owner-count,
  allocation, update-time, or GPU-time growth;
- each stable checkpoint produces machine-readable state plus a screenshot for
  later human comparison.

This is a correctness and resource-lifetime gate. Screenshots preserve visual
evidence, but automation does **not** claim retail visual equivalence. Color,
composition, animation feel, and subtle geometry artifacts remain user gates.

## Canonical runtime contract

`WorldRevealReadinessBarrier` remains the only definition of destination
readiness. It will expose a structured snapshot rather than forcing telemetry
to repeat the readiness formula. A snapshot records the destination cell,
indoor/outdoor classification, required radius, render publication, composite
texture readiness, collision readiness, an impossible/unhydratable claim, and
the final `Ready` result.

A focused App-layer `WorldRevealLifecycleTelemetry` owns diagnostic reveal
generations. It has no GL calls and no knowledge of `GameWindow`. For each
login or portal generation it records:

1. begin;
2. destination acquisition;
3. each distinct readiness transition;
4. the first frame where the normal world viewport is actually eligible to
   draw;
5. completion or cancellation.

Making the normal viewport visible before `Ready` is a hard invariant failure,
not a warning. A newer generation retires the older one, so stale asynchronous
completion cannot satisfy the new destination.

`GameWindow` only supplies facts and invokes the controller at existing
lifecycle seams. It does not gain a new feature body.

## Production automation seam

The retained-UI automation runner gains runtime commands through an injected
interface:

- `wait world-ready [timeout-ms]` waits on canonical lifecycle state instead
  of a guessed sleep;
- `wait materialized <occurrence> [timeout-ms]` waits for the authoritative
  portal completion count;
- `checkpoint <name>` emits one JSON record containing reveal state,
  landblock/entity/animation and resource-owner counts, managed memory, and
  the latest frame-profiler summary;
- `screenshot <name> [timeout-ms]` queues a default-framebuffer capture after
  the complete world and retained UI have drawn, then waits for the render
  thread to finish the PNG;
- existing `input` commands perform deterministic turns and movement through
  `InputDispatcher`.

All state mutation and GL readback stay on the update/render thread. The
external gate only launches the process, observes files/logs and OS process
metrics, and requests normal `WM_CLOSE` shutdown.

## Connected route

The gate runs two capped/uncapped-aware sessions against local ACE:

1. fresh login → wait for canonical readiness → checkpoint + screenshot;
2. outdoor dense scene → turn → stable checkpoint + screenshot;
3. world-edge scene → turn → stable checkpoint;
4. known dungeon destination → checkpoint + screenshot → local movement;
5. return outdoors → checkpoint + screenshot;
6. revisit the first dense scene → stable resource comparison;
7. graceful close;
8. reconnect the same account → repeat the fresh-login readiness and
   screenshot gate → graceful close.

The existing seven-destination R6 soak remains the longer performance route.
The lifecycle gate is shorter and more diagnostic; it composes with that soak
rather than replacing it.

## Hard failures

- world viewport observed before the active reveal snapshot is ready;
- destination never reaches readiness or materialization within the bounded
  connected test timeout;
- missing or duplicate reveal/materialization/completion edges;
- missing checkpoint JSON or screenshot, zero-sized/corrupt screenshot;
- absent required destination landblock/EnvCell/collision readiness;
- retained per-owner resources after delete/session teardown in deterministic
  tests;
- same-location resource counts or memory/per-frame allocation grow beyond the
  route's documented relative tolerance;
- unhandled exception, access violation, OOM, GL/device loss, disconnect,
  unexpected WeenieError, nonzero exit, or failure of graceful shutdown.

Absolute FPS is recorded, never compared across local and RDP sessions. The
gate compares like-for-like samples within one process and reports CPU and GPU
frame time separately.

## Implementation sequence

1. Add a structured readiness snapshot and exhaustive barrier tests.
2. Add lifecycle telemetry as a pure App owner with stale-generation,
   cancellation, duplicate, and early-visible tests.
3. Add the automation runtime interface, deterministic waits, checkpoints, and
   screenshot request/completion protocol.
4. Add the render-thread screenshot owner and structured resource snapshots.
5. Wire the owners at login, F751 portal start, TAS placement/completion, world
   draw eligibility, and session teardown.
6. Add the connected route and PowerShell report/gate orchestration.
7. Run capped and uncapped Release gates, fix root causes, and retain artifacts.
8. Extract the now-protected streaming/portal/reveal frame orchestration from
   `GameWindow` without changing the accepted lifecycle trace.
9. Run focused tests, full Release build/test, connected gates, graceful-close
   verification, and documentation reconciliation.

## Completion evidence

- focused App tests for every lifecycle invariant;
- full Release solution build and test suite;
- two-process connected lifecycle report with screenshots and JSONL timeline;
- accepted capped and uncapped same-session metrics;
- `GameWindow` extraction retains the exact accepted lifecycle trace;
- roadmap, issues, architecture, divergence register, memory, `AGENTS.md`, and
  `CLAUDE.md` agree on the resulting ownership and remaining visual gates.