# HyperTwist Phase 4 gameplay workload/budget surface packet

Created on `2026-05-08`

Status:

- first-party HyperTwist packet
- bounded Phase `4` gameplay-facing consumer slice

## Purpose

This packet closes the next thin gameplay-facing consumer seam above the panel-widget and session-actor coach helpers by exposing one pure workload/budget summary surface over the already-landed primary coach CTA, queue-control, queue-recovery posture, handoff-continuation, and focus/provenance surfaces.

The open tasks were:

- stop forcing gameplay / Blueprint callers to read raw focus-case counts, signal counts, launch-budget counts, queue-entry counts, and pressure scores just to explain current coach workload
- expose one thin first-party workload/budget surface that summarizes focus pressure, queue load, launch-case budget, and live continuation / queue-pressure posture
- keep that surface derived from already-cached gameplay consumer state instead of widening into dashboard-only retained analytics or backend scheduling policy

It is not:

- a new coach scheduling or launch-budget policy packet
- a queue recovery selection-policy packet
- a dashboard workload migration
- a broader gameplay HUD composition pass

## Scope

Bounded lane:

- add a first-party workload/budget surface in shared training types
- add a coach-library helper that derives the surface from panel state, the displayed queue-recovery posture surface, the displayed handoff-continuation surface, and the displayed focus/provenance surface
- expose that derived workload/budget surface on `HyperTwistTrainingPanelWidget` and `HyperTwistTrainingSessionActor`
- keep the derivation presentation-only and rooted in already-cached gameplay consumer state

Out of scope:

- changing coach continuation branch order
- changing queue recovery or launch-budget policy
- importing dashboard-only retained workload analytics into gameplay consumers
- widening into higher-level gameplay UI composition in the same packet

## Why this was the right next packet

Before this slice:

- gameplay-facing panel/session consumers already exposed truthful primary CTA, queue-control, queue-recovery posture, handoff-continuation, and focus/provenance surfaces

But one thin consumer seam was still open:

- callers could bind actions, explain continuation, and narrate focus/provenance
- but they still had to inspect raw counts and budget fields to explain how much work was live, how much queue load remained, and why a given launch-case budget existed

That meant:

- action binding was thin
- continuation and provenance explanation were thin
- but workload and budget explanation still leaked raw panel-state values into callers

So the next bounded move was:

- keep the already-landed action, posture, continuation, and provenance surfaces unchanged
- and expose one narrow workload/budget summary surface above them

## What landed

Primary code changes:

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingTypes.h`
  - added `FHyperTwistTrainingCoachWorkloadBudgetSurface`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingCoachLibrary.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingCoachLibrary.cpp`
  - added `DeriveCoachWorkloadBudgetSurface(...)`
  - workload/budget is derived from existing panel-state, queue-recovery posture, handoff-continuation, and focus/provenance inputs
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingPanelWidget.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingPanelWidget.cpp`
  - added `GetDisplayedCoachWorkloadBudgetSurface()`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingSessionActor.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSessionActor.cpp`
  - added `GetDisplayedCoachWorkloadBudgetSurface()`

## Product effect

The gameplay-facing coach consumer layer is now more complete:

- gameplay / Blueprint callers can read one pure surface to describe focus pressure, queue load, launch-case budget, and live queue-pressure posture
- callers no longer need to inspect raw count fields, launch-budget fields, or queue-status fragments just to render workload narration
- the surface stays aligned with the already-landed primary CTA, queue-control, queue-recovery posture, handoff-continuation, and focus/provenance surfaces without importing dashboard-only retained workload analytics

## Acceptance criteria

- shared training types expose a narrow workload/budget surface
- coach-library derivation consumes already-cached gameplay consumer state rather than adding new runtime fetches
- panel-widget callers can fetch the displayed workload/budget surface directly
- session-actor callers can fetch the displayed workload/budget surface directly
- full product build succeeds

## Validation checklist

1. build `UnrealHyperTwist.sln` / `UnrealHyperTwistEditor`
2. confirm the new workload/budget surface compiles in shared types and coach library
3. confirm panel-widget getters compile and return the derived workload/budget surface
4. confirm session-actor getters compile and return the derived workload/budget surface
5. confirm no backend continuity or dashboard-only retained analytics work was pulled into the packet

## Validation result

- full `Development Editor|Win64` build succeeded on `2026-05-08`
- build completed with `0` warnings and `0` errors

## Next bounded follow-on slice

- stay on the same gameplay-facing consumer lane and expose one thin coach readiness/eligibility summary surface on `HyperTwistTrainingPanelWidget` and `HyperTwistTrainingSessionActor`, so gameplay callers can render what is actionable now, what is blocked, and why without reading raw booleans or suppression strings directly
