# HyperTwist Phase 4 recognition runtime handoff packet

Created on `2026-05-06`

Status:

- first-party HyperTwist packet
- bounded Phase `4` recognition runtime-handoff slice

## Purpose

This packet closes the first honest runtime handoff after the provider-backed recognition client landed.

The open task is:

- move recognition from a sidecar contract plus standalone client into owned training runtime state, replay state, and coaching refresh flow

It is not:

- a large recognition UI pass
- a websocket/live-stream rewrite
- a speech or simulation packet
- a broad refactor of the training subsystem

## Scope

Bounded lane:

- complete recognition session lifecycle ownership in `HyperTwistTraining`
- expose runtime open / preview / commit / finalize / close surfaces through the subsystem, runtime library, panel widget, and session actor
- append normalized recognition replay events into the active run packet
- refresh repository/coaching derived state after replay mutation so existing replay-to-coach logic can wake up on live recognition data

Out of scope:

- broad dashboard redesign
- provider-specific protocol expansion beyond the current HTTP sidecar contract
- new gameplay content or speech flows
- exact puzzle-state engine deepening

## Why this was the right next packet

Before this slice:

- the repo had a provider-backed recognition client
- replay review analytics and recognition replay summaries already existed
- coach-signal derivation already reacted to recognition replay ambiguity and correction pressure

But recognition still did not flow through the owned training runtime.

So the missing bridge was:

- own the recognition session in `HyperTwistTraining`
- append replay events from recognition runtime activity
- let the existing replay/training/coaching stack consume those events without inventing a second parallel lane

## What landed

Primary code changes:

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistRecognition/HyperTwistVisionClient.h`
  - added explicit `CloseVisionSession(...)` to the owned vision-client contract
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistRecognition/HyperTwistMockVisionClient.cpp`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistRecognition/HyperTwistHttpVisionClient.cpp`
- `UnrealHyperTwist/Config/DefaultGame.ini`
  - completed close-session support for both mock and provider-backed client implementations
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingTypes.h`
  - added `FHyperTwistTrainingRecognitionSessionState`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingSubsystem.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSubsystem.cpp`
  - added owned runtime methods for:
    - open active recognition session
    - submit active recognition frame
    - commit active recognition observation
    - finalize active recognition session
    - close active recognition session
  - added owned recognition session state, provider-health refresh, replay-event append, and replay-mutation synchronization helpers
  - recognition replay mutation now records run state and refreshes repository/coaching views in the same subsystem pass
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingRuntimeLibrary.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingRuntimeLibrary.cpp`
  - exposed the new recognition runtime lane through the existing world-context runtime surface
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingPanelWidget.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingPanelWidget.cpp`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingSessionActor.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSessionActor.cpp`
  - added thin runtime-consumer wrappers and cached recognition session state

## Runtime behavior now

The active training runtime now owns:

- recognition session open/closed state
- provider-health inspection state
- last preview / commit / finalize results
- cumulative frame / commit / correction / finalize counters

Recognition runtime activity now mutates the active replay packet through owned event types:

- first frame -> `RecognitionPreview`
- later frames -> `RecognitionScan`
- commit warnings / missing units -> `RecognitionCorrection`
- commit results -> `RecognitionCommit`
- finalize outputs -> replay-seed recognition events when provided, otherwise a synthesized final commit

After replay mutation:

- the active run summary is refreshed
- run state is persisted back into the training repository
- repository-derived replay review analytics, recognition replay summaries, and coach signals are rebuilt in the existing same-pass flow

## Acceptance criteria

- recognition session lifecycle is now owned by first-party training runtime code
- provider-backed and mock clients both satisfy the full open/submit/commit/finalize/close contract
- recognition runtime events reach the active replay packet
- replay mutation wakes up the existing repository/coaching refresh path
- the panel widget and session actor can consume the runtime lane without bypassing the subsystem
- full product build succeeds

## Validation checklist

1. build `UnrealHyperTwist.sln` / `UnrealHyperTwistEditor`
2. confirm the subsystem, runtime library, panel widget, and session actor all compile together
3. confirm no Phase `3` generated-mode packet was reopened
4. confirm the provider-backed client lane remains bounded to the owned vision contract

That is the packet.
