# HyperTwist Phase 3 linked-state rebuild closure packet

Created on `2026-05-06`

Status:

- first-party HyperTwist packet
- bounded persistence / integrity closure slice

## Purpose

This packet defines the next bounded Phase 3 closure task after the imported generated-mode executor landed.

The open task is:

- tighten repository integrity for coach queue history so persisted history still belongs to live queue state after rebuild
- widen round-trip verification so it proves rebuilt coach-linked state, not only raw repository JSON parity

It is not:

- a coaching UX redesign
- a broad training-backend refactor
- a new queue model
- a donor widening task

## Scope

Bounded lane:

- final Phase 3 linked-state / rebuild closure across persisted coaching queue history and derived coach-facing summaries

Required result:

- repository integrity detects orphaned coach queue history that no longer maps to a valid queue or queue entry
- repository repair drops orphaned coach queue history during normalization
- repository round-trip verification compares rebuilt first-party derived state across learner, review, coach, and queue execution surfaces

Out of scope:

- changing coach brief derivation behavior
- changing queue creation heuristics
- changing generated-mode executor behavior
- changing dashboard flows beyond exposing the new verification result

## Current owned product truth

These pieces are already live in first-party code:

- repository save / load / repair
- repository integrity reporting
- coach action-plan, closure-memory, recommendation-history, and queue-execution derivation
- dashboard display of repository round-trip status

What was still missing:

- queue-history linkage checks against actual stored queue state
- proof that save / load / repair preserves rebuilt coach-linked summaries, not only serialized repository state

## Implementation target

The slice should do the following:

1. detect queue-history entries whose `QueueId` no longer maps to a stored queue
2. detect queue-history entries whose `EntryId` no longer maps to a stored queue entry
3. drop those orphaned history rows during repair
4. verify derived parity across:
   - learner profile
   - review program summary
   - coach memory snapshot
   - coach action-plan summary
   - coach closure memory summary
   - coach recommendation history summary
   - coach carry-forward policy summary
   - coach archive policy summary
   - coach queue execution summary

## Suggested file ownership

Primary edit surfaces:

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingTypes.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingRepositoryLibrary.cpp`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingPersistenceLibrary.cpp`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistCoachDashboardWidget.cpp`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistBootstrap/HyperTwistContractLibrary.cpp`

## Acceptance criteria

- integrity report flags orphaned queue-history queue links
- integrity report flags orphaned queue-history entry links
- repair removes those orphaned queue-history rows
- round-trip verification fails if rebuilt derived coach-linked state diverges after save / load
- dashboard verification text surfaces the new derived parity result
- full UE build still succeeds

## Validation checklist

1. build `UnrealHyperTwist.sln`
2. confirm queue-history orphan cases appear in the sample integrity surface
3. confirm repair actions include dropping orphaned queue-history queue / entry links
4. confirm round-trip verification now tracks derived parity in addition to counts, state parity, and integrity parity

That is the packet.
