Expose runtime coach focus and workload surfaces

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

@@ -954,6 +954,93 @@ UHyperTwistTrainingRuntimeLibrary::GetActiveTrainingCoachHandoffContinuationSurf
 	return FHyperTwistTrainingCoachHandoffContinuationSurface();
 }
 
+FHyperTwistTrainingCoachFocusProvenanceSurface
+UHyperTwistTrainingRuntimeLibrary::GetActiveTrainingCoachFocusProvenanceSurface(
+	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
+			);
+		const FHyperTwistTrainingCoachHandoffContinuationSurface HandoffContinuationSurface =
+			UHyperTwistTrainingCoachLibrary::DeriveCoachHandoffContinuationSurface(
+				PanelState,
+				PrimaryActionSurface,
+				QueueControlSurface,
+				QueueRecoveryPostureSurface
+			);
+		return UHyperTwistTrainingCoachLibrary::DeriveCoachFocusProvenanceSurface(
+			PanelState,
+			PrimaryActionSurface,
+			QueueControlSurface,
+			QueueRecoveryPostureSurface,
+			HandoffContinuationSurface
+		);
+	}
+
+	return FHyperTwistTrainingCoachFocusProvenanceSurface();
+}
+
+FHyperTwistTrainingCoachWorkloadBudgetSurface
+UHyperTwistTrainingRuntimeLibrary::GetActiveTrainingCoachWorkloadBudgetSurface(
+	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
+			);
+		const FHyperTwistTrainingCoachHandoffContinuationSurface HandoffContinuationSurface =
+			UHyperTwistTrainingCoachLibrary::DeriveCoachHandoffContinuationSurface(
+				PanelState,
+				PrimaryActionSurface,
+				QueueControlSurface,
+				QueueRecoveryPostureSurface
+			);
+		const FHyperTwistTrainingCoachFocusProvenanceSurface FocusProvenanceSurface =
+			UHyperTwistTrainingCoachLibrary::DeriveCoachFocusProvenanceSurface(
+				PanelState,
+				PrimaryActionSurface,
+				QueueControlSurface,
+				QueueRecoveryPostureSurface,
+				HandoffContinuationSurface
+			);
+		return UHyperTwistTrainingCoachLibrary::DeriveCoachWorkloadBudgetSurface(
+			PanelState,
+			QueueRecoveryPostureSurface,
+			HandoffContinuationSurface,
+			FocusProvenanceSurface
+		);
+	}
+
+	return FHyperTwistTrainingCoachWorkloadBudgetSurface();
+}
+
 TArray<FHyperTwistTrainingMethodSegment> UHyperTwistTrainingRuntimeLibrary::GetActiveTrainingLearnerMethodSegments(UObject* WorldContextObject)
 {
 	if (UHyperTwistTrainingSubsystem* TrainingSubsystem = GetTrainingSubsystem(WorldContextObject))

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

@@ -293,6 +293,14 @@ public:
 	static FHyperTwistTrainingCoachHandoffContinuationSurface
 	GetActiveTrainingCoachHandoffContinuationSurface(UObject* WorldContextObject);
 
+	UFUNCTION(BlueprintPure, Category = "HyperTwist|Training|Coach", meta = (WorldContext = "WorldContextObject"))
+	static FHyperTwistTrainingCoachFocusProvenanceSurface
+	GetActiveTrainingCoachFocusProvenanceSurface(UObject* WorldContextObject);
+
+	UFUNCTION(BlueprintPure, Category = "HyperTwist|Training|Coach", meta = (WorldContext = "WorldContextObject"))
+	static FHyperTwistTrainingCoachWorkloadBudgetSurface
+	GetActiveTrainingCoachWorkloadBudgetSurface(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 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 latest landed bounded `Phase 4` packet stays on that same deliberate `UHyperTwistTrainingRuntimeLibrary` world-context consumer lane and adds active coach focus/provenance and workload/budget surfaces over the already-landed active primary coach CTA, queue-control, queue-recovery, and handoff-continuation surfaces, so gameplay/Blueprint callers can explain the active coach target, upstream recommendation provenance, launch case budget, queue load, and focus pressure without reading raw focus ids, source labels, counts, or budget fields 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_FOCUS_PROVENANCE_WORKLOAD_BUDGET_SURFACE_PACKET_2026-05-09.md

@@ -0,0 +1,48 @@
+# HyperTwist Phase 4 runtime-library coach focus-provenance and workload-budget 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, queue-control, queue-recovery, and handoff-continuation surfaces.
+
+## Why this packet exists
+
+The prior runtime-library packet let world-context callers explain continuation posture and queue-recovery preference without reading raw schedule-policy, queue-execution, suppression, or handoff state. But callers still had to inspect raw focus ids, source labels, counts, and budget fields if they needed to explain:
+
+- what the active coach target actually is
+- what upstream path produced that target
+- what launch case budget and queue pressure the active posture is carrying
+
+That kept the runtime-library caller seam behind the already-landed panel-widget and session-actor display-contract lane.
+
+## What changed
+
+- added `GetActiveTrainingCoachFocusProvenanceSurface()`
+- added `GetActiveTrainingCoachWorkloadBudgetSurface()`
+- derived both surfaces from the same active coach panel state and already-landed runtime-library CTA, queue-control, queue-recovery, and handoff-continuation chain
+- 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 active coach target and upstream recommendation provenance
+- the truthful launch case budget, queue load, and focus pressure posture
+
+without reading raw focus deck ids, focus method-segment ids, source-label strings, counts, or budget fields 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 readiness/eligibility and verification/recognition/review-policy context surfaces, because those are the next truthful contracts above the newly-landed focus/provenance and workload/budget surfaces.