# HyperTwist Phase 4 provider-backed recognition packet

Created on `2026-05-06`

Status:

- first-party HyperTwist packet
- bounded Phase `4` recognition productionization slice

## Purpose

This packet closes the first honest recognition-productionization move after the orchestration entry lane landed.

The open task is:

- add one provider-backed recognition client behind the existing `IHyperTwistVisionClient` contract

It is not:

- a gameplay-facing recognition UX packet
- a speech or simulation packet
- a provider lock-in decision
- a websocket/live-stream packet

## Scope

Bounded lane:

- keep the existing mock client intact
- add a local-first HTTP sidecar implementation over the same vision contract
- make the provider-backed client config-driven from the Unreal project config
- surface enough health metadata to inspect which provider lane is active and whether transport failed

Out of scope:

- changing coach/training consumers to depend on recognition now
- broad recognition UI
- websocket grammar or continuous frame streaming
- exact state-validation deepening inside `HyperTwistCore`

## Why this is the right next packet

Current code reality before this packet:

- `HyperTwistRecognition` already had an owned sidecar contract
- replay-facing recognition summary derivation already existed
- the only runtime implementation was the in-process mock client

That meant recognition was contract-strong but still not provider-backed.

The bounded fix is:

- add one real sidecar transport implementation without changing the owned contract shape

## What landed

Primary code changes:

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistRecognition/HyperTwistRecognitionTypes.h`
  - expanded `FHyperTwistVisionServiceHealth` with:
    - `ProviderLabel`
    - `ServiceEndpoint`
    - `LastError`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistRecognition/HyperTwistVisionClient.h`
  - added `UHyperTwistHttpVisionClient`
  - class is `Config=Game` / `DefaultConfig`
  - config surface includes:
    - `ServiceBaseUrl`
    - operation paths
    - timeout
    - optional bearer token
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistRecognition/HyperTwistHttpVisionClient.cpp`
  - added the provider-backed implementation
  - uses Unreal HTTP plus JSON struct serialization
  - posts the existing owned request payloads and reads the existing owned response payloads
  - keeps transport synchronous and bounded for the current non-streaming contract stage
- `UnrealHyperTwist/Config/DefaultGame.ini`
  - added the initial local-first sidecar config section
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistRecognition/HyperTwistMockVisionClient.cpp`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistBootstrap/HyperTwistContractLibrary.cpp`
  - refreshed mock health metadata so mock and provider-backed health share the same inspection fields
- `UnrealHyperTwist/Source/UnrealHyperTwist/UnrealHyperTwist.Build.cs`
  - added the Unreal `HTTP` module dependency

## Transport decision

The sidecar contract already said:

- websocket preferred for live frame flow
- HTTP acceptable for batch or non-streaming calls

This packet intentionally chooses:

- HTTP

because it is the smallest productionization move that:

- keeps the local-first sidecar boundary
- preserves provider neutrality
- does not widen into a live-streaming runtime rewrite

## Acceptance criteria

- `IHyperTwistVisionClient` still owns the recognition boundary
- a provider-backed implementation now exists in first-party code
- the provider-backed implementation is config-driven rather than hard-coded into a consumer
- the mock client still works
- full product build succeeds

## Validation checklist

1. build `UnrealHyperTwist.sln`
2. confirm the new HTTP client compiles and links
3. confirm the mock health shape still compiles with the expanded metadata
4. confirm no first-party training/coaching packet was reopened

That is the packet.
