# HyperTwist Phase 4 runtime-library coach displayed-action and queue-control helper packet

- bounded Phase `4` runtime-consumer slice
- date: `2026-05-09`

## Intent

Start the deliberate follow-on `UHyperTwistTrainingRuntimeLibrary` world-context consumer lane above the already-landed coach scheduling and recommendation state.

## Why this packet exists

The panel-widget and session-actor gameplay consumer lane is already far enough along that callers can read truthful displayed coach contracts and execute the common coach actions without stitching together raw cached state. The world-context runtime surface still lagged behind that convenience layer:

- it exposed the low-level coach launch and queue-mutation entry points
- it exposed the raw active coach panel state and queue state
- but it still forced world-context callers to reconstruct source-label routing and displayed queue-target selection for the common displayed-action path

That left runtime-library callers with the same provenance and queue-target glue that the panel/session consumer lane had already removed.

## What changed

- added active coach handoff and primary-action source-label resolvers on `UHyperTwistTrainingRuntimeLibrary`
- added active primary coach CTA and queue-control surfaces on `UHyperTwistTrainingRuntimeLibrary`
- added displayed world-context launch helpers for:
  - recommended coach run
  - follow-up coach run
  - primary coach action
  - next queued coach run
  - active queue-entry coach run
- added displayed world-context queue helpers for:
  - defer displayed queue entry
  - promote displayed queue entry
- kept the routing aligned with the same active coach panel-state provenance order already used by `UHyperTwistTrainingPanelWidget` and `AHyperTwistTrainingSessionActor`

## Files

- `C:\HyperTwist\UnrealHyperTwist\Source\UnrealHyperTwist\Public\HyperTwistTraining\HyperTwistTrainingRuntimeLibrary.h`
- `C:\HyperTwist\UnrealHyperTwist\Source\UnrealHyperTwist\Private\HyperTwistTraining\HyperTwistTrainingRuntimeLibrary.cpp`
- `C:\HyperTwist\docs\HYPERTWIST_ROADMAP_OVERHAUL_EXPANSION_GUIDE.md`

## Outcome

World-context gameplay and Blueprint callers can now use truthful runtime-library coach convenience entry points without reconstructing:

- preferred handoff provenance
- primary-action source-label routing
- active queue-entry selection
- displayed defer/promote queue targets

The backend continuity stays unchanged. This packet only widens the already-stabilized runtime consumer contract.

## Validation

- full `Development Editor | Win64` MSBuild on `UnrealHyperTwist.sln`

## Next clean slice

Stay on this runtime-library consumer lane only if a real world-context caller still needs one more thin derived coach/generated-mode display contract or displayed-action convenience helper over already-cached state. The next best bounded move inside that lane would be the runtime-library queue-recovery posture and handoff-continuation surfaces, because those are the next truthful display contracts above the newly-landed primary CTA and queue-control helpers.
