acdream/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-k-canonical-soak.md

GameWindow Slice 8 Checkpoint K — canonical soak snapshots

Status: Active 2026-07-22. Parent: 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. Issue: #232. Behavior rule: this checkpoint changes diagnostic capture and connected-gate evidence only. It does not change rendering, streaming, gameplay, resource budgets, or the existing process working/private-memory thresholds.

1. Outcome

Make every scripted checkpoint <name> a deferred, acknowledged render-frame barrier. A checkpoint is written only after private presentation and the normal render diagnostics phase have both observed the same immutable RenderFrameOutcome. Its JSON contains the canonical world/reveal/resource owner snapshot and that exact frame outcome. The script cannot execute the next command until serialization and both writes succeed, fail, or are explicitly cancelled during shutdown.

The nine-stop soak then consumes exactly nine ordered checkpoints, gates canonical owner stability at the Caul return → Caul plateau same-location pair, labels server-controlled entity/animation population changes as workload warnings, and retains process residency as an unchanged secondary guard.

2. Runtime contract

2.1 Acknowledgement token

Replace the synchronous automation method with a request contract equivalent to:

enum RetailUiAutomationCheckpointStatus
{
    Pending,
    Succeeded,
    Failed,
    Cancelled,
}

interface IRetailUiAutomationCheckpoint
{
    RetailUiAutomationCheckpointStatus Status { get; }
    string? Error { get; }
}

bool TryRequestCheckpoint(
    string name,
    out IRetailUiAutomationCheckpoint? checkpoint,
    out string error);

The production token also retains the assigned request sequence and validated name across the update → render edge. Only the controller can transition it, exactly once, from Pending to a terminal state.

RetailUiAutomationScriptRunner stores one token together with the active command index. While Pending, repeated ticks return without enqueueing again or advancing the command. Success clears the token and advances once. Failure or cancellation clears it and stops on the token's exact error. Disposal still releases held input; runtime shutdown is responsible for cancelling queued tokens.

2.2 FIFO request owner

WorldLifecycleAutomationController becomes the sole FIFO owner and an IDisposable frame-phase participant:

• validation failure creates no request and consumes no sequence;
• accepted requests receive one monotonic sequence and enter one FIFO;
• a successful render drains accepted requests in order;
• each request serializes one WorldLifecycleCheckpoint containing its sequence/name, current reveal state, the exact current RenderFrameOutcome, and one canonical resource snapshot;
• Succeeded is published only after the JSONL append and named JSON write both complete;
• capture/serialization/I/O failure marks only that request Failed with contextual sequence/name error and does not throw out of rendering;
• shutdown marks every still-pending request Cancelled with an explicit error;
• enqueue after shutdown fails synchronously and cannot create an orphan token.

The controller is adopted by FrameRootRuntimeBindings separately from its retained-UI late binding, so the binding detaches and pending requests cancel under the existing retryable frame-root lifetime.

2.3 Post-diagnostics render phase

Add a narrow IRenderFramePostDiagnosticsPhase with a no-op implementation. RenderFrameOrchestrator calls it exactly once after:

1. resource preparation;
2. world rendering;
3. private presentation and screenshots;
4. IRenderFrameDiagnosticsPhase.Publish;
5. then checkpoint drain;
6. finally the existing GPU-flight close.

If an earlier render phase fails, post-diagnostics is not called and the FIFO remains pending for the next successful frame. An unexpected post-phase throw uses the existing render failure/recovery path, although production capture and I/O failures are represented on tokens rather than thrown. No previous-frame diagnostic value is paired with a current-frame owner snapshot: WorldLifecycleResourceSnapshotSource.Capture(RenderFrameOutcome) takes visible/total landblocks from the supplied outcome and reads the already- published aggregate FPS/frame-time snapshot only after diagnostics runs.

3. Artifact and soak schema

WorldLifecycleCheckpoint adds the exact frame outcome. Existing reveal and resource fields retain their names. The route adds these nine commands in this order at the end of each settled destination block:

1. caul-baseline
2. sawato-baseline
3. rynthid
4. aerlinthe
5. sawato-return
6. holtburg
7. caul-return
8. sawato-plateau
9. caul-plateau

run-connected-r6-soak.ps1 reads the JSONL only after the route completes and requires one row for every expected name, exact sequence 1–9, exact order, and the current process id. It embeds those records in the report.

Every checkpoint hard-gates zero:

• pending live teardowns;
• pending landblock retirements;
• staged mesh uploads and bytes;
• composite warmup work.

The same-location Caul return → Caul plateau comparison requires exact equality for deterministic owner/cache counts and bytes: loaded/visible/total landblocks, materialized live owners, teardown/retirement queues, VFX binding/owner/script/ light counts, mesh render-data/atlas/estimated bytes, staged work, tracked GPU bytes/buffers/textures, and composite/particle texture ownership. Connected WorldEntities, AnimatedEntities, LiveEntities, particles, and active scripts may legitimately change with authoritative population or transient effects; those deltas remain named workload warnings, not silent exclusions. Managed used/committed deltas are reported diagnostically. Existing working/private-memory, update-p95, and allocation-p50 thresholds remain byte- for-byte unchanged as the secondary residency/performance guard.

4. Implementation sequence

1. Add token states and change the automation runtime/script runner to the one-token-per-command polling contract. Cover delayed success, repeated pending ticks, failure, cancellation, invalid request, and disposal while pending.
2. Refactor WorldLifecycleAutomationController into the FIFO request owner; pass the frame outcome into snapshot capture and write it into artifacts. Cover FIFO order, sequence stability, write failure, no duplicate drain, shutdown cancellation, and enqueue-after-dispose.
3. Add the post-diagnostics phase to RenderFrameOrchestrator, wire the controller through FrameRootCompositionPhase, and adopt its lifetime separately from the late UI binding. Pin exact phase order, skipped drain on prior failure, post-phase failure recovery, and partial-composition cleanup.
4. Add the nine route commands. Parse/validate JSONL in the soak, attach the canonical checkpoints to the report, add zero-work and same-location owner gates, and preserve the old process/performance formulas verbatim.
5. Run behavior/order, architecture/ownership, and adversarial failure review passes. Correct findings and re-run focused App tests, App Release, Release build, and the complete Release suite.
6. Run two fresh-process connected nine-stop routes before closing #232. Both must exit gracefully, produce exact ordered checkpoints, pass canonical owner/cache gates, and pass the unchanged process residency guard.
7. Reconcile architecture, roadmap, milestones, issues, AGENTS/CLAUDE, and durable memory; commit Checkpoint K as its own bisectable diagnostic unit.

5. Automated acceptance

• one checkpoint command creates one request, one sequence, and one artifact;
• a pending token blocks all later script commands without duplicate enqueue;
• render failure delays rather than loses or duplicates the request;
• diagnostics publication precedes same-frame capture;
• independent accepted requests drain FIFO and retain name/sequence identity;
• capture/write failure reaches the script as the exact failed-token error;
• shutdown reaches pending scripts as explicit cancellation;
• no controller/runtime reference points back to GameWindow;
• all nine route names and sequences are exact and appear in the soak report;
• canonical pending/staging/warmup work is zero at every checkpoint;
• Caul return → plateau deterministic owners/caches are unchanged, while authoritative workload deltas are explicitly warned;
• working/private-memory thresholds and update/allocation formulas are unchanged;
• focused, App, and complete Release suites pass with no new warnings.

No visual gate is required for K because it changes diagnostic observation only. Checkpoint L owns the final connected framebuffer and user visual gate.