Expose runtime coach queue recovery and handoff surfaces

UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingRuntimeLibrary.cpp

@@ -897,6 +897,63 @@ UHyperTwistTrainingRuntimeLibrary::GetActiveTrainingCoachQueueControlSurface(
 	return FHyperTwistTrainingCoachQueueControlSurface();
 }
 
+FHyperTwistTrainingCoachQueueRecoveryPostureSurface
+UHyperTwistTrainingRuntimeLibrary::GetActiveTrainingCoachQueueRecoveryPostureSurface(
+	UObject* WorldContextObject
+)
+{
+	if (UHyperTwistTrainingSubsystem* TrainingSubsystem = GetTrainingSubsystem(WorldContextObject))
+	{
+		const FHyperTwistTrainingCoachPanelState PanelState =
+			TrainingSubsystem->GetActiveCoachPanelState();
+		const FHyperTwistTrainingCoachPrimaryActionSurface PrimaryActionSurface =
+			GetActiveTrainingCoachPrimaryActionSurface(WorldContextObject);
+		const FHyperTwistTrainingCoachQueueControlSurface QueueControlSurface =
+			GetActiveTrainingCoachQueueControlSurface(WorldContextObject);
+		return UHyperTwistTrainingCoachLibrary::DeriveCoachQueueRecoveryPostureSurface(
+			TrainingSubsystem->GetActiveCoachSchedulePolicySummary(),
+			TrainingSubsystem->GetActiveCoachSessionQueueExecutionSummary(),
+			PanelState,
+			PrimaryActionSurface,
+			QueueControlSurface
+		);
+	}
+
+	return FHyperTwistTrainingCoachQueueRecoveryPostureSurface();
+}
+
+FHyperTwistTrainingCoachHandoffContinuationSurface
+UHyperTwistTrainingRuntimeLibrary::GetActiveTrainingCoachHandoffContinuationSurface(
+	UObject* WorldContextObject
+)
+{
+	if (UHyperTwistTrainingSubsystem* TrainingSubsystem = GetTrainingSubsystem(WorldContextObject))
+	{
+		const FHyperTwistTrainingCoachPanelState PanelState =
+			TrainingSubsystem->GetActiveCoachPanelState();
+		const FHyperTwistTrainingCoachPrimaryActionSurface PrimaryActionSurface =
+			GetActiveTrainingCoachPrimaryActionSurface(WorldContextObject);
+		const FHyperTwistTrainingCoachQueueControlSurface QueueControlSurface =
+			GetActiveTrainingCoachQueueControlSurface(WorldContextObject);
+		const FHyperTwistTrainingCoachQueueRecoveryPostureSurface QueueRecoveryPostureSurface =
+			UHyperTwistTrainingCoachLibrary::DeriveCoachQueueRecoveryPostureSurface(
+				TrainingSubsystem->GetActiveCoachSchedulePolicySummary(),
+				TrainingSubsystem->GetActiveCoachSessionQueueExecutionSummary(),
+				PanelState,
+				PrimaryActionSurface,
+				QueueControlSurface
+			);
+		return UHyperTwistTrainingCoachLibrary::DeriveCoachHandoffContinuationSurface(
+			PanelState,
+			PrimaryActionSurface,
+			QueueControlSurface,
+			QueueRecoveryPostureSurface
+		);
+	}
+
+	return FHyperTwistTrainingCoachHandoffContinuationSurface();
+}
+
 TArray<FHyperTwistTrainingMethodSegment> UHyperTwistTrainingRuntimeLibrary::GetActiveTrainingLearnerMethodSegments(UObject* WorldContextObject)
 {
 	if (UHyperTwistTrainingSubsystem* TrainingSubsystem = GetTrainingSubsystem(WorldContextObject))

UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingRuntimeLibrary.h

@@ -285,6 +285,14 @@ public:
 		UObject* WorldContextObject
 	);
 
+	UFUNCTION(BlueprintPure, Category = "HyperTwist|Training|Coach", meta = (WorldContext = "WorldContextObject"))
+	static FHyperTwistTrainingCoachQueueRecoveryPostureSurface
+	GetActiveTrainingCoachQueueRecoveryPostureSurface(UObject* WorldContextObject);
+
+	UFUNCTION(BlueprintPure, Category = "HyperTwist|Training|Coach", meta = (WorldContext = "WorldContextObject"))
+	static FHyperTwistTrainingCoachHandoffContinuationSurface
+	GetActiveTrainingCoachHandoffContinuationSurface(UObject* WorldContextObject);
+
 	UFUNCTION(BlueprintPure, Category = "HyperTwist|Training", meta = (WorldContext = "WorldContextObject"))
 	static TArray<FHyperTwistTrainingMethodSegment> GetActiveTrainingLearnerMethodSegments(UObject* WorldContextObject);
 

docs/HYPERTWIST_ROADMAP_OVERHAUL_EXPANSION_GUIDE.md

@@ -68,7 +68,7 @@ Current correction call from the source-exposed audit and current execution refr
   - the imported generated-mode gap is closed; request/config/selection plumbing and the bounded clean-room executor are already landed in first-party code
   - the latest landed bounded `Phase 4` packet closes the retained-idle comparison/outcome actionability gap at the end of the recognition-assisted coach-to-review continuity lane, and the final retained-surface confirmation pass now leaves that closure lane functionally complete
   - the retained idle widget surface now keeps retained comparison and decision history inspectable without continuing to advertise live launch or guidance-outcome actions once the coach-to-review loop has already collapsed to truthful closed-loop idle
-  - the latest landed bounded `Phase 4` packet deliberately starts the follow-on `UHyperTwistTrainingRuntimeLibrary` world-context consumer lane and adds active coach handoff/primary source-label resolvers, active primary coach CTA and queue-control surfaces, and displayed recommended/follow-up/primary/next-queued/active-queue-entry/defer/promote helpers so gameplay/Blueprint callers can use truthful coach runtime convenience entry points without reconstructing provenance or queue-target routing from raw coach state
+  - the latest landed bounded `Phase 4` packet stays on that same deliberate `UHyperTwistTrainingRuntimeLibrary` world-context consumer lane and adds active coach queue-recovery posture and handoff-continuation surfaces over the already-landed active primary coach CTA and queue-control surfaces, so gameplay/Blueprint callers can explain continue/defer/promote preference and queued-vs-follow-up-vs-recommended continuation posture without reading raw schedule-policy, queue-execution, suppression, or handoff state directly
   - the current next bounded packet should stay on that same runtime-library consumer lane only if a real world-context gameplay or Blueprint caller still needs one more thin derived coach/generated-mode display contract or displayed-action convenience helper over already-cached state; otherwise choose the next roadmap lane deliberately instead of extending runtime-consumer widening by drift
   - the current execution-discipline rule that broad refactor / monolith-splitting work should not interrupt the active bounded roadmap packet unless structure is actually blocking it
 

docs/arch/HYPERTWIST_PHASE4_RUNTIME_LIBRARY_COACH_QUEUE_RECOVERY_HANDOFF_CONTINUATION_SURFACE_PACKET_2026-05-09.md

@@ -0,0 +1,49 @@
+# HyperTwist Phase 4 runtime-library coach queue-recovery and handoff-continuation surface packet
+
+- bounded Phase `4` runtime-consumer slice
+- date: `2026-05-09`
+
+## Intent
+
+Stay on the deliberate `UHyperTwistTrainingRuntimeLibrary` world-context consumer lane and expose the next truthful coach display contracts above the already-landed active primary CTA and queue-control helpers.
+
+## Why this packet exists
+
+The previous runtime-library packet removed the provenance and queue-target glue around the common displayed coach action path. World-context callers could launch or mutate the common displayed coach actions, and they could read the active primary CTA and queue-control surfaces directly.
+
+But they still had to inspect raw schedule-policy, queue-execution, suppression, and handoff state if they needed to explain:
+
+- why continue, defer, or promote is preferred
+- whether the active continuation posture is queued, follow-up, or recommended
+
+That kept the runtime-library caller seam behind the already-landed panel-widget and session-actor display-contract lane.
+
+## What changed
+
+- added `GetActiveTrainingCoachQueueRecoveryPostureSurface()`
+- added `GetActiveTrainingCoachHandoffContinuationSurface()`
+- derived both surfaces from the same active coach panel state, schedule-policy summary, queue-execution summary, primary CTA surface, and queue-control surface already used by the panel-widget and session-actor helpers
+- kept the runtime-library lane purely compositional over already-cached active coach state without reopening backend derivation
+
+## 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 ask the runtime library for:
+
+- the truthful queue-recovery posture over the active coach CTA and queue-control state
+- the truthful queued-vs-follow-up-vs-recommended continuation posture over that same state
+
+without reading raw schedule-policy summaries, queue-execution counters, suppression strings, or handoff enums directly.
+
+## 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 focus/provenance and workload/budget surfaces, because those are the next truthful contracts above the newly-landed queue-recovery and handoff-continuation surfaces.