# HyperTwist — Comprehensive Reconstruction Roadmap
## Status: Live — Phase 1 and Phase 2 Reality-Aligned
## Date: 2026-06-10

## Reconstruction Starting Inventory (Authoritative Snapshot)

Source: `HYPERTWIST_REPO_STATE_BOARD_2026-05-11.md` and `HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md`

**Within the original 71-row shallow-eval set:**

| Category | Count |
|----------|-------|
| Implemented/live (all licenses) | 29 |
| **Selected, not live (permissive candidates)** | **29** |
| Reference / benchmark / discard | 13 |
| **Total non-live** | **42** |

**Outside the 71-row set:**

| Category | Count | Repos |
|----------|-------|-------|
| Speech rows (landed as attribution only) | 4 | `ggml-org/whisper.cpp`, `rhasspy/piper`, `SYSTRAN/faster-whisper`, `coqui-ai/TTS` |

**The 29 selected-not-live permissive candidates include:**
- `cahidenes/rubiks-cube-solver`
- `tentone/rubix-solver`
- `NuiLab/code-vr`
- `pissang/claygl`
- `pissang/clay-viewer`
- `pmndrs/postprocessing`, `pmndrs/react-postprocessing`, `pmndrs/drei`, `pmndrs/react-spring`, `@react-spring/*`, `pmndrs/three-stdlib`, `pmndrs/maath`, `pmndrs/uikit`, `pmndrs/zustand`, `pmndrs/leva`, `pmndrs/use-gesture`
- `ecomfe/zrender`, `ecomfe/echarts-gl`
- `KhronosGroup/glTF-Sample-Viewer`, `KhronosGroup/glTF-Sample-Renderer`
- `google/model-viewer/packages/*` (sub-packages)
- And others in the 0R-B backlog

This section records the starting reconstruction snapshot only.

The live Phase 1 source of truth is the checklist below: the accepted donor set
is now wired across native C++, IPC/sidecar, and `Content/Browser/` runtime
surfaces rather than remaining attribution-only.

---

---

## Executive Summary

This roadmap replaced the self-referential validation-ladder sequence with a
functional, repo-first reconstruction plan. The original audit snapshot
correctly identified the missing centerpieces: no classic-cube renderer, no
timer/HUD loop, and no real donor wiring. The current Phase 1 and Phase 2 lane
has now closed those gaps with a shipped classic-cube actor, timer/HUD game
mode, speech/solver surfaces, and a buildable embedded browser runtime.

**The new rule:** Repos are wired before features are claimed. Features are
playable before they are documented. Validation tests verify behavior, not
structural metadata.

---

## Phase 0: Foundation — Build Infrastructure for Repo Wiring

**Goal:** Enable actual donor code to be compiled, linked, and shipped.

**Deliverables:**
- [x] Create `.external/` directory with 23 git submodules
- [x] Create `ThirdParty/` directory for direct-source C++ integration
- [x] Add `.gitmodules` for the first wave of C++ donor repos
- [x] Add `Build.cs` rules in `UnrealHyperTwist.Build.cs` for `PublicIncludePaths`
- [x] Windows build validation after each sub-step (prove the linker sees donor symbols)

**Estimated actions:** ~15 build actions per sub-step
**Estimated time:** 2–3 hours per sub-step (infrastructure compiles fast)

---

## Phase 1: Wire All Donor Repos (Repo-First Constraint)

**Principle:** Repos are wired into the build BEFORE any feature claims them.
See `HYPERTWIST_UNWIRED_REPO_INVENTORY_AND_WIRING_SCHEDULE_2026-06-10.md`
for the full 29-repo queue and per-repo wiring posture.

### 1A — Solver Backend: `efrantar/rob-twophase` ✅ COMPLETE
- [x] Add submodule `mirrors/rob-twophase`
- [x] Copy source to `Private/ThirdParty/rob-twophase/`
- [x] Fix UE macro conflicts (`check`→`ValidateCube`, `UF`→`UF_EDGE`)
- [x] Add `msvc_compat.h` for POSIX `ffs`/`ffsll` on Windows
- [x] Fix `unistd.h` → `direct.h`/`io.h`, `qt_skip1` C4700
- [x] Windows build validated: 5 actions, 38.87s, exit code 0
- [x] Runtime test: feed a known scrambled state, assert solution length < 25 through `HyperTwist.Solver.SolveScrambledState`

### 1B — Speech-to-Text: `freestyle-voice/freestyle` (MIT) ✅ COMPLETE
- [x] Decision gate: `freestyle` remains a hotkey/cloud-client lane, so HyperTwist wires it as an external speech-session surface rather than pretending it is a native Unreal library.
- [x] Integration path A (recommended): Run `freestyle` as external sidecar process. UE communicates via local HTTP loopback or IPC.
- [x] Integration path B (fallback posture recorded): do not embed `freestyle` source into the Unreal binary unless a later packet explicitly widens into plugin-hosting work.
- [x] Expose `UHyperTwistSpeechLibrary::StartDictationSession()` / `EndDictationSession()`
- [x] Accept caller-owned utterance PCM through `FHyperTwistSpeechUtteranceEnvelope` and submit it through the active companion speech session boundary.
- [x] On release or utterance submission: receive transcript JSON, parse cleaned text, and expose it for move-notation or coach-command execution
- [x] **Audio Ducking**: when `bDictationActive = true`, duck all non-speech `UAudioComponent` volumes to 15% via managed component `VolumeMultiplier`
- [x] Restore full volume 200ms after `EndDictationSession()`
- [x] Automation test: simulate hotkey/session-open behavior, assert `VolumeMultiplier < 0.2f` on background music component; assert restoration after release

### 1C — Text-to-Speech: `rhasspy/piper` ✅ COMPLETE
- [x] Retain repo-backed `piper` source under `.external/piper` as the canonical donor lane for local/offline narration.
- [x] Keep `piper` in the accepted external-engine posture while exposing first-party synthesis through `UHyperTwistSpeechLibrary`.
- [x] Preserve the bounded local voice-model/runtime lane without forcing a large checked-in voice payload into repo authority.
- [x] Expose `UHyperTwistSpeechLibrary::Synthesize(FString Text, FString VoiceId)` → `TArray<uint8> PCM16`
- [x] Automation test: synthesize "hello", assert PCM output is non-empty and that the helper returns stripped PCM payload bytes

### 1D — Compact Solver Oracle: `brownan/Rubiks-Cube-Solver` (GPL-2.0)
- [x] Host as external IPC process (never link GPL into Unreal binary)
- [x] Expose `UHyperTwistSolverLibrary::VerifySolution(FString State, TArray<FString> Moves)` → `bool`

### 1E — glTF Reference Renderer: `KhronosGroup/glTF-Sample-Renderer` (Apache-2.0) ✅ COMPLETE
- [x] Retain repo-backed `glTF-Sample-Renderer` source under `.external/glTF-Sample-Renderer`
- [x] Evaluate the repo shape against the actual donor surface: the retained renderer is a browser/runtime module, not a useful Unreal static-link target in this packet
- [x] Wire the standards-aware runtime path through `Content/Browser/` using the published `@khronosgroup/gltf-viewer` package and browser-shell adapter manifest
- [x] Keep heavyweight comparison/editor workflows subordinate to the browser QA lane rather than fabricating a fake C++ link claim

### 1F — Solver Adjunct: `cahidenes/rubiks-cube-solver` (MIT)
- [x] Host as external IPC process (Python)
- [x] Expose comparison endpoint: same state to both solvers, assert identical solution length

### 1G — Browser Solver: `tentone/rubix-solver` (MIT) ✅ COMPLETE
- [x] Surface the donor in `Content/Browser/` as a native-sidecar adapter instead of misclassifying the OpenCV/C++ repo as an npm package
- [x] Load the fallback solver shell in embedded `UHyperTwistBrowserWidget` runtime with browser-to-Unreal request envelopes for the native lane

### 1H — Browser Spatial Stack (13 JS repos) ✅ COMPLETE
- [x] Add the browser-capable repos as npm dependencies or prebuilt runtime scripts in `Content/Browser/`
- [x] Repos: `NuiLab/code-vr`, `pissang/claygl`, `pissang/clay-viewer`, `pmndrs/postprocessing`, `pmndrs/react-postprocessing`, `pmndrs/drei`, `pmndrs/uikit`, `pmndrs/three-stdlib`, `pmndrs/maath`, `pmndrs/zustand`, `pmndrs/leva`, `pmndrs/use-gesture`, `pmndrs/react-spring` + sub-packages
- [x] Build the browser runtime bundle via npm into `Content/Browser/dist/browser-spatial-runtime.js`
- [x] Keep `Content/Browser/index.html` as the authoritative browser shell; it upgrades into the bundled runtime when present and remains runnable through the committed plain-JS fallback when build artifacts have been cleaned
- [x] Load the authoritative shell in `UHyperTwistBrowserWidget`
- [x] State bridge: embedded Unreal bridge object plus browser `postMessage` fallback for shell-state and command envelopes

### 1I — Analytics Stack (2 JS repos) ✅ COMPLETE
- [x] `ecomfe/zrender`, `ecomfe/echarts-gl`
- [x] Bundle into browser runtime; subordinate to already-landed `apache/echarts`
- [x] Expose the browser-shell analytics demo/adapter surface so Unreal-side analytics payloads can be rendered into the embedded shell

### 1J — Model-Viewer Sub-Packages (3 JS repos, runtime) ✅ COMPLETE
- [x] `google/model-viewer/packages/model-viewer-effects`, `space-opera`, `render-fidelity-tools`
- [x] Bundle the runtime-capable packages into `Content/Browser/` alongside already-landed `google/model-viewer`
- [x] Keep `space-opera` visible as an editor-sidecar and `render-fidelity-tools` visible as a QA-sidecar instead of pretending either is default gameplay runtime

### 1K — Authoritative Browser Shell & Clean-Checkout Runtime ✅ COMPLETE
- [x] Make `Content/Browser/index.html` the runtime authority instead of treating transient `dist/index.html` output as the shell
- [x] Add a bootstrap loader that prefers `dist/browser-spatial-runtime.js` and falls back to a committed plain-JS runtime when the bundle is absent
- [x] Queue early Unreal command and shell-state pushes during bootstrap so the browser lane remains deterministic even if the JS runtime finishes loading slightly later than the CEF widget
- [x] Add shell-verification coverage proving the authoritative shell, bootstrap script, and fallback runtime exist and no longer point directly at a TypeScript source entrypoint

**Phase 1 answer after repair:** the intended wiring set is complete on the accepted posture. The runtime/direct/sidecar lanes for `1A` through `1J` are present in current code and runtime manifests; support-only rows such as `modelviewer.dev`, `glTF-Sample-Viewer`, `space-opera`, `render-fidelity-tools`, and `@react-spring/types` remain intentionally subordinate or non-default rather than evidence of a missing gameplay integration.

`2026-07-23` exact-roster hardening: the historical Phase 1 queue now carries
an explicit `queuePosition` contract from `1` through `29` in both
`Content/Browser/src/runtime/registry.ts` and the clean-checkout fallback.
`verify-browser-shell.mjs` rejects missing, duplicate, or drifted rows, missing
retained source/sidecar evidence, missing direct runtime dependencies, and
missing locked React Spring dependency modules. This roster remains distinct
from the different original `29` implemented/live repository capability set.
The browser verifier and Vite production build are green; the latter
transformed `1,872` modules.

**Estimated actions:** 40–60 per repo (UHT regen on first include)
**Estimated time:** 1–2 days per repo (build-debug cycles)

---

## Phase 2: Core Puzzle Renderer — The Missing Centerpiece

**Goal:** HyperTwist becomes a visible, interactive product.

**Principle:** This is the highest-priority functional gap. It blocks every user-facing feature.

### 2A — Procedural Classic Cube Geometry ✅ COMPLETE
- [x] Create `AHyperTwistClassicCubeActor` : `AActor`
- [x] Generate 26 pieces (6 centers, 12 edges, 8 corners) as `UProceduralMeshComponent` instances
- [x] 6 sections per piece, one per face direction; materials assigned per section
- [x] Place pieces in solved-state positions in a 3×3×3 grid
- [x] Windows build validated: 4 actions, 38.38s, exit code 0, zero warnings
- [x] Editor-authored colored material family plus internal-face material created through `scripts/hypertwist_author_classic_cube_training_maps.py`

### 2B — Face Rotation Logic ✅ COMPLETE
- [x] `RotateFace(ECubeFace Face, ERotationDirection Dir)` with move queueing
- [x] Piece identity tracking (26 pieces with fixed colored-face identities)
- [x] Tick-based pivot animation with smooth-step interpolation
- [x] 0.15s quarter-turn duration
- [x] Verified permutation cycles for all 6 faces against standard cube notation
- [x] Windows build validated: 6 actions, 66.53s, exit code 0, zero warnings

### 2C — Mouse/Touch Input ✅ COMPLETE
- [x] `ProcessClick(RayOrigin, RayDirection, bCounterClockwise)` with line trace
- [x] Hit normal → cube face mapping (Up/Down/Front/Back/Left/Right)
- [x] Wired to `RotateFace()` for interactive manipulation
- [x] Left click = clockwise, right click / bool flag = counter-clockwise
- [x] Windows build validated: 6 actions, 68.48s, exit code 0, zero warnings

### 2D — Scramble Generation ✅ COMPLETE
- [x] `GenerateScramble(int32 Length)` → `TArray<FString>` WCA-style notation
- [x] `ApplyScramble(MoveStrings)` parsing with ', 2 suffixes
- [x] Queued through existing RotateFace() pipeline with sequential animation
- [x] Windows build validated: 6 actions, 95.39s, exit code 0, zero warnings

### 2E — Timer + HUD ✅ COMPLETE
- [x] Create `WBP_HyperTwistGameHUD`-equivalent first-party UMG runtime (`UHyperTwistClassicCubeHUDWidget`) plus `AHyperTwistClassicCubeGameMode`
- [x] Timer display (minutes:seconds.milliseconds)
- [x] Inspection countdown (15s standard)
- [x] Scramble notation panel
- [x] Bind timer start to first face turn, stop to solved-state detection

### 2F — First-Party Mouse/Touch Ownership Lane ✅ COMPLETE
- [x] Add `AHyperTwistClassicCubePlayerController` as the first-party click/touch owner instead of leaving `ProcessClick()` behind implied Blueprint glue
- [x] Bind left-click to clockwise turns, right-click to counter-clockwise turns, and touch press to clockwise turns
- [x] Default `AHyperTwistClassicCubeGameMode` to the first-party player controller so the classic cube loop is owned in code, not only in roadmap prose
- [x] Add focused coverage for face-resolution mapping and controller ownership defaults

### 2G — Loop Readiness Hardening ✅ COMPLETE
- [x] Add a visible control-hint line to the first-party HUD so the runtime communicates how to interact with the cube without requiring extra Blueprint notes
- [x] Bind `R` as a first-party fresh-attempt shortcut so the training loop can restart without waiting on a future content-only HUD button
- [x] Keep the packaged-loop next step narrowed to actual packaging/level/camera/material work instead of unfinished click ownership

**Estimated actions:** 80–120 (geometry + input + HUD)
**Estimated time:** 3–5 days

---

## Phase 3: First Playable Level

**Goal:** A level you can launch, scramble, solve, and time.

**Phase 3 separation (current doctrine):**
- Code-owned runtime closure: first-party game mode, player controller, HUD, orbit camera, runtime cube spawn, and package-gate boot route.
- Packaged gate: real Windows package + launch proof.
- Editor-owned presentation closure: dedicated `.umap`, authored lights, and material polish.

### 3A — Level Creation ✅ COMPLETE
- [x] Create `L_HyperTwist_ClassicTraining` (`.umap`)
- [x] Place `AHyperTwistClassicCubeActor` at world origin
- [x] Add directional light + ambient environment (basic, not immersive yet)
- [x] Keep the first-party runtime HUD auto-added to viewport; no extra `WBP_HyperTwistGameHUD` is required for functional closure
- [x] Add first-party orbit camera pawn with mouse-drag orbit and scroll-wheel zoom (`AHyperTwistClassicCubeOrbitPawn`) so camera interaction is owned in code before the `.umap` polish pass exists
- [x] Keep the source-owned runtime reachable on the generic validation map by spawning the cube above floor height and having the orbit pawn follow the active cube actor rather than assuming a hand-authored map origin

### 3B — Game Mode
- [x] Create first-party `AHyperTwistClassicCubeGameMode` : `AGameModeBase`
- [x] Handle game state across preparation, scramble playback, inspection, solving, and solved transitions
- [x] Default to the first-party `AHyperTwistClassicCubePlayerController` so click/touch interaction is owned in code
- [x] Add an in-HUD button for "New Scramble" alongside the keyboard shortcut so restart does not depend on remembering `R`

### 3C — Build & Package Validation
- [x] Add source-controlled Windows helper scripts for package and smoke-launch validation:
  - `scripts/Invoke-HyperTwistClassicCubePackage.ps1`
  - `scripts/Launch-HyperTwistClassicCubePackage.ps1`
- [x] Define the temporary package-gate boot route explicitly as `/Engine/Maps/Templates/OpenWorld?game=/Script/UnrealHyperTwist.HyperTwistClassicCubeGameMode` until the dedicated `L_HyperTwist_ClassicTraining` map exists
- [x] Switch the helper defaults to the dedicated authored training maps once they exist; cook `L_HyperTwist_ClassicTraining` and `L_HyperTwist_FollowAlongTraining` by default
- [x] Package `UnrealHyperTwist` for Windows (not just Editor build)
- [x] Launch packaged build on Windows host
- [x] Verify: cube visible, clickable, scramble applies, timer works, solve detected
- [x] Validation evidence on `2026-06-11`: isolated Windows worktree `C:\HyperTwist_worktrees\phase3pkg`, reverse-SSH fallback lane `localhost:22023`, `Build.bat` editor build `Succeeded`, `BuildCookRun` `ExitCode=0`, archive output in `C:\HyperTwist_worktrees\phase3pkg_packaged`, and packaged smoke boot succeeded through `scripts/Launch-HyperTwistClassicCubePackage.ps1`
- [x] Validation evidence on `2026-06-12`: recovered isolated Windows worktree `C:\HyperTwist_worktrees\phase3to5`, authored dedicated maps plus material family, `BuildCookRun` `ExitCode=0`, archive output in `C:\HyperTwist_worktrees\phase3to5_packaged`, packaged smoke boot on `L_HyperTwist_ClassicTraining`, and explicit packaged smoke boot on `/Game/HyperTwistTraining/Maps/L_HyperTwist_FollowAlongTraining`

**Estimated actions:** 20–30
**Estimated time:** 1–2 days

---

## Phase 4: Wire Solver into Training Pipeline ✅ COMPLETE

**Prerequisite:** Phase 1A (rob-twophase) + Phase 2 (renderer) + Phase 3C packaged gate GREEN

**Closure read on `2026-06-12`:** the dedicated-map and material lane is now source-controlled and package-validated, so solver-guided training is no longer merely reopened. It is present in first-party runtime code, targeted automation, authored follow-along assets, and packaged smoke validation.

### 4A — Solver HUD Integration
- [x] Add "Hint" button to HUD
- [x] On click: query solver for next optimal move from current state
- [x] Glow the suggested face through the authored classic-cube material family
- [x] Option: show full solution sequence as notation list

### 4B — Training Mode: Follow-Along
- [x] Create `L_HyperTwist_FollowAlongTraining` (`.umap`)
- [x] Load a known scramble, show user the moves one at a time
- [x] User must match each move before advancing
- [x] Track accuracy and time

### 4C — Solver Verification
- [x] After user solve, verify state is actually solved (not just timer stopped)
- [x] If not solved, show "DNF" (Did Not Finish)

**Estimated actions:** 30–50
**Estimated time:** 2–3 days

---

## Phase 5: Speech Pipeline (STT + TTS) ✅ COMPLETE

**Prerequisite:** Phase 1B (freestyle) + Phase 1C (piper) + Phase 3C packaged gate GREEN

**Closure read on `2026-06-12`:** speech command input, narration, ducking, transcript parsing, and automation coverage are now present in first-party runtime code and validated alongside the dedicated-map package lane. This phase is no longer merely reopened; it is closed on the current simulator track.

### 5A — Voice Command Input
- [x] Add "Voice" button to HUD (or use freestyle global hotkey)
- [x] On hotkey hold: capture microphone audio → stream to the active speech-session boundary
- [x] On release: receive cleaned transcript from the active speech-session boundary
- [x] Parse transcript for move notation: "R", "R prime", "R2", "slice M", etc.
- [x] Execute parsed move on cube
- [x] **Audio ducking active during entire hold duration**

### 5B — Coach Narration Output
- [x] Add narration events covering "Scramble ready. Inspection time.", "Go!", "Solved!", plus coach-ready confirmation
- [x] Feed event text to piper → PCM16
- [x] Play PCM16 through UE `USoundWaveProcedural` or `FSoundSource`
- [x] Support multiple voice models (coach personality selection)
- [x] **Narration audio is NOT ducking candidate** — only background music/ambient

### 5C — Voice Session Tests
- [x] Automation test: simulate hotkey hold, assert background `VolumeMultiplier < 0.2f`
- [x] Automation test: assert transcript "R prime" → parsed move `ECubeFace::R, ERotationDirection::CounterClockwise`
- [x] Automation test: "Solved!" → piper → assert PCM length > 0

**Estimated actions:** 40–60
**Estimated time:** 2–3 days

---

## Phase 6: Hypercube Renderer (4D/5D)

**Prerequisite:** Phase 2 (classic renderer)

### 6A — 2×2×2×2 Projection
- [x] Port Melinda 2×2×2×2 state math (already exists) to visible geometry
- [x] Implement cell-first projection (8 cells, each a 3D cube)
- [x] Color visible cubie faces in each projected cell shell using exact permutation/orientation state
- [x] Mouse interaction: click cell + axis → twist

Closure read:
- first-party `HyperTwistSimulation` now owns exact cell-turn transform construction, the stable `melinda-2x2x2x2-cell-first-projection-v1` packet, and procedural projection actor/game-mode/controller/orbit surfaces
- the current owned visible shell is `8` projected cells, each with `8` cubies and `3` visible faces per cubie inside the cell-first runtime
- Windows `UE 5.7` build validation and targeted `Phase 6A` automation passed on `2026-06-12` through the live fallback reverse-SSH lane at `localhost:22023`

### 6B — 3×3×3×3 Projection
- [x] Extend to 3×3×3×3 (27 tesseracts, 81 cells visible in projection)
- [x] Use wireframe or transparent cells to avoid occlusion chaos
- [x] Keyboard shortcuts for axis rotation and slice twists

Closure read:
- first-party `HyperTwistSimulation` now owns a bounded exact virtual `3x3x3x3`
  runtime state, visible-slice projection contract, and procedural
  `AHyperTwistVirtual3333ProjectionActor` / `AHyperTwistVirtual3333ProjectionGameMode` /
  `AHyperTwistVirtual3333ProjectionPlayerController` /
  `AHyperTwistVirtual3333ProjectionOrbitPawn` packet
- the stable owned `Phase 6B` projection profile is
  `hypercube-3x3x3x3-visible-slice-projection-v1`, exposing `27` projected
  tesseracts and `81` visible cells for the current selected slice
- the default occlusion-management posture is visible-face-first projection with
  optional translucent shell rendering plus owned keyboard slice-axis, layer,
  rotation-axis, and twist controls
- Windows `UE 5.7` build validation and targeted `Phase 6B` automation passed
  on `2026-06-12` through the explicitly reverified fallback reverse-SSH lane
  at `localhost:22023`, using the isolated Windows tree
  `C:\Users\Anthracite Ace\HyperTwist_phase6a_validate`

### 6C — Magic120Cell & MagicCube5D
- [x] Resolve the Phase `6C` widening posture as an Unreal clean-room activation lane above the bounded retained `Magic120Cell` / `MagicCube5D` donor contracts and the retained `Hyperspeedcube` runtime anchor
- [x] Land a first-party higher-dimensional runtime-activation catalog with canonical `Magic120Cell` and `MagicCube5D` launch definitions, primary contract ids, default selection posture, and no external-process requirement
- `2026-06-13` continuation proof: current code now resolves the active higher-dimensional activation profile from training run state through both canonical puzzle ids and imported generated-mode `RuntimeModeId` fallback, then mirrors that resolved profile through the training runtime library plus the live training panel and session-actor caches
- `2026-06-13` Windows checkpoint: the primary reverse-SSH lane rebuilt the slice in isolated worktree `C:\HyperTwist_worktrees\phase10validate` with `Result: Succeeded` / UnrealBuildTool `Total execution time: 1061.50 seconds`, and targeted `UnrealEditor-Cmd` automation found `5` tests under `HyperTwist.FirstParty.HigherDimensional.Phase6C` and passed all `5`, including `RunStateActivationResolution`
- [x] Widen the owned activation lane into shared-map higher-dimensional launch, view-context, and generated-mode execution surfaces above the landed runtime-profile seams
- `2026-06-18` continuation proof: current code now bundles higher-dimensional launch and view-context catalogs for `Magic120Cell` and `MagicCube5D`, resolves those surfaces through the training runtime library plus the live training panel/session-actor caches, and executes the shared-map seed-run plus generated-mode owned-run bridge through the training subsystem while keeping automation on the owned mock speech/vision lane
- `2026-06-18` Windows checkpoint: after recovering an interrupted follow-up and re-proving the primary reverse-SSH lane, the same isolated worktree `C:\HyperTwist_worktrees\phase10validate` rebuilt the cleaned slice with `Result: Succeeded` / UnrealBuildTool `Total execution time: 124.81 seconds`, and targeted `UnrealEditor-Cmd` automation found `8` tests under `HyperTwist.FirstParty.HigherDimensional.Phase6C` and passed all `8`, including `LaunchCatalog`, `ViewContextCatalog`, `LaunchExecution`, and `RunStateActivationResolution`; the commandlet emitted `Ignoring very large delta of 499.13 seconds` during `LaunchExecution`, so that quiet interval is now known-good rather than a corruption signal
- `2026-06-18` continuation proof: current code now adds an explicit higher-dimensional host-surface catalog that records the preferred dedicated-family `Magic120Cell` / `MagicCube5D` host-map targets while keeping the current shared training-map host as the effective fallback, then mirrors that resolved host surface through the training runtime library plus the live training panel/session-actor caches and the launch/view-context surfaces themselves
- `2026-06-18` Windows checkpoint: the same isolated worktree `C:\HyperTwist_worktrees\phase10validate` rebuilt the widened host-surface slice with `Result: Succeeded` / UnrealBuildTool `Total execution time: 2858.02 seconds`, and targeted `UnrealEditor-Cmd` automation found `9` tests under `HyperTwist.FirstParty.HigherDimensional.Phase6C` and passed all `9`, including the new `HostCatalog`; `LaunchExecution` again emitted `Ignoring very large delta of 425.99 seconds`, confirming that long quiet interval remains a known-good characteristic rather than a corruption signal
- `2026-06-18` continuation proof: current code now adds an explicit higher-dimensional runtime-session catalog that merges the launch, host, and view-context seams into one executed family-owned session posture, threads that session surface through the training runtime library plus the live training panel/session-actor caches, and upgrades generated-mode deck lineage and start-time selector application to use the merged launch-plus-view defaults instead of only the narrower launch defaults
- `2026-06-18` Windows checkpoint: the same isolated worktree `C:\HyperTwist_worktrees\phase10validate` rebuilt the widened session-surface slice with `Result: Succeeded` / UnrealBuildTool `Total execution time: 3541.98 seconds`, and targeted `UnrealEditor-Cmd` automation found `10` tests under `HyperTwist.FirstParty.HigherDimensional.Phase6C` and passed all `10`, including the new `SessionCatalog`; `LaunchExecution` emitted `Ignoring very large delta of 573.84 seconds`, so that longer quiet interval also remains confirmed as known-good on this lane rather than a corruption signal
- `2026-06-18` continuation proof: current code now adds an explicit higher-dimensional interactive-scene catalog that promotes the landed `Magic120Cell` / `MagicCube5D` runtime-session seams into family-owned scene-context contracts, mirrors those scene surfaces through the training runtime library plus the live training panel/session-actor caches, and upgrades generated-mode lineage plus source attribution to record the explicit interactive scene surface and scene-context ids while dedicated maps and family-owned runtime state remain placeholder-backed
- `2026-06-18` Windows checkpoint: the same isolated worktree `C:\HyperTwist_worktrees\phase10validate` rebuilt the widened interactive-scene slice with `Result: Succeeded` / UnrealBuildTool `Total execution time: 3528.60 seconds`, and targeted `UnrealEditor-Cmd` automation found `11` tests under `HyperTwist.FirstParty.HigherDimensional.Phase6C` and passed all `11`, including the new `InteractiveSceneCatalog`; `LaunchExecution` emitted `Ignoring very large delta of 479.46 seconds`, so that quiet interval also remains confirmed as known-good on this lane rather than a corruption signal
- `2026-06-18` continuation proof: current code now replaces those placeholder `Magic120Cell` / `MagicCube5D` interactive-scene envelopes with family-owned runtime-state, projection, and persistence payloads, adds dedicated-family training-map assets plus dedicated host/launch/view-context/session surfaces, exposes explicit scene-envelope decoders through the runtime library, and batches start-time selector posture application so generated-mode launch execution no longer rebuilds repository views once per default selector
- `2026-06-18` Windows checkpoint: the same isolated worktree `C:\HyperTwist_worktrees\phase10validate` rebuilt the dedicated-family runtime-state slice with `Result: Succeeded` / UnrealBuildTool `Total execution time: 1648.33 seconds`; after the selector-batching hardening rebuild with `Result: Succeeded` / UnrealBuildTool `Total execution time: 93.44 seconds`, targeted `UnrealEditor-Cmd` automation exported `C:\HyperTwist_worktrees\phase10validate\UnrealHyperTwist\Saved\AutomationReports\Phase6C-DedicatedFamily-Optimized\index.json` with all `11` `HyperTwist.FirstParty.HigherDimensional.Phase6C` tests passing, `totalDuration` `196.08790588378906`, and `LaunchExecution` duration `195.65591430664062`; the commandlet still emitted `Ignoring very large delta of 195.58 seconds`, but that quiet interval is materially down from the immediately prior `385.00 seconds` proof on this lane while retaining `**** TEST COMPLETE. EXIT CODE: 0 ****`
- `2026-06-18` continuation proof: current code now also defers repository-view projection across the internal generated-mode launch handoff itself, so the seed-run, launch-request persistence, and generated-run transition keep their repository state intact without forcing intermediate view rebuilds that the caller never reads
- `2026-06-18` Windows checkpoint: after that projection-deferral hardening rebuild with `Result: Succeeded` / UnrealBuildTool `Total execution time: 400.77 seconds`, targeted `UnrealEditor-Cmd` automation exported `C:\HyperTwist_worktrees\phase10validate\UnrealHyperTwist\Saved\AutomationReports\Phase6C-DedicatedFamily-Optimized2\index.json` with all `11` `HyperTwist.FirstParty.HigherDimensional.Phase6C` tests passing, `totalDuration` `41.88494873046875`, and `LaunchExecution` duration `41.53509521484375`; the controller quiet interval fell again to `41.52 seconds` while retaining `**** TEST COMPLETE. EXIT CODE: 0 ****`
- `2026-06-18` recovery proof: current code now deterministically reauthors the dedicated-family `Magic120Cell` / `MagicCube5D` maps through `scripts/hypertwist_author_higher_dimensional_training_maps.py`, stamps `AHyperTwistCoachDashboardGameMode` plus manifest-backed `PlayerStart` ownership tags for activation, host, launch, view-context, session, interactive-scene, scene-context, puzzle, runtime-mode, projection, persistence, and dedicated-family ownership, and records the refreshed owned-map hashes in `docs/generated/higher_dimensional_training_maps/phase6c_dedicated_family_map_manifest.json`; the optional `AHyperTwistHigherDimensionalTrainingShellActor` remains available for manual/editor authoring, but the headless `UnrealEditor-Cmd` lane now intentionally skips spawning it because that path still crashes the commandlet with `EXCEPTION_INT_DIVIDE_BY_ZERO`
- `2026-06-18` Windows checkpoint: after patching the missing dedicated-anchor puzzle tag, the same isolated worktree `C:\HyperTwist_worktrees\phase10validate` reran `scripts\Invoke-HyperTwistHigherDimensionalMapAuthoring.ps1` to `Higher-dimensional authored maps verified.`, then targeted `UnrealEditor-Cmd` automation exported `C:\HyperTwist_worktrees\phase10validate\UnrealHyperTwist\Saved\AutomationReports\Phase6C-DedicatedMapOwnership\index.json`; the pulled local proof at `docs/generated/higher_dimensional_training_maps/phase6c_dedicated_map_ownership_automation_report.json` now shows all `13` `HyperTwist.FirstParty.HigherDimensional.Phase6C` tests passing, including `DedicatedMapAuthoringManifest` and `DedicatedMapOwnedShell`, with `**** TEST COMPLETE. EXIT CODE: 0 ****`
- `2026-06-22` Windows checkpoint: the same primary reverse-SSH `localhost:22022` lane then re-used isolated worktree `C:\HyperTwist_worktrees\phase10validate` for the maintained higher-dimensional package helper, ran `scripts\Invoke-HyperTwistHigherDimensionalPackage.ps1` in `-SkipBuild` mode against the existing target receipt, validated the manifest-backed `Magic120Cell` / `MagicCube5D` dedicated-family map hashes before cook, completed `BuildCookRun` with `ExitCode=0` and `BuildCookRun time: 118.53 s`, wrote archive output to `C:\HyperTwist_worktrees\phase10validate_packaged_phase6c_higherdim`, smoke-booted both `/Game/HyperTwistTraining/Maps/L_HyperTwist_Magic120CellTraining` and `/Game/HyperTwistTraining/Maps/L_HyperTwist_MagicCube5DTraining`, and pulled aggregate proof into `docs/generated/higher_dimensional_training_maps/phase6c_dedicated_family_package_validation_report.json`
- [x] Replace the current placeholder interactive-scene envelopes with full owned `120-cell` and `5D` simulation-state, projection, and persistence ownership in Unreal above the landed higher-dimensional scene-context catalog
- [x] Replace the current shared-map execution bridge with full owned dedicated-family interactive launch, map, and persistence surfaces for `120-cell` and `5D`
- `2026-07-23` exact-state correction: `UHyperTwistMagic120CellRuntimeLibrary`
  now owns a `7,560`-facelet permutation, `7,440` legal base moves,
  inverse/forward turn application, projection/focus state, and persistence;
  `UHyperTwistMagicCube5DRuntimeLibrary` now owns exact order-3 state with
  `243` cubies, `810` facelets, legal turns, projection/focus state, and
  persistence. Focused runtime contracts are green. The 120-cell scene remains
  a representative `120`-center visualization and must not be described as a
  full `7,560`-sticker renderer.

**Estimated actions:** 100–200
**Estimated time:** 1–2 weeks

---

## Phase 7: Non-Euclidean Puzzles (MagicTile)

**Prerequisite:** Phase 6 (hypercube renderer)

### 7A — MagicTile Host Decision
- [x] Evaluate: port MagicTile Java/OpenTK to Unreal vs. host in embedded browser
- [x] If browser: wire `react-three-fiber` + `three.js` into embedded CEF
- [ ] If port: implement spherical/hyperbolic tiling math from spec
- Landed posture on `2026-06-19`: first-party `MagicTile` routing now chooses the already-landed embedded browser/CEF shell with retained `three.js` and `react-three-fiber` substrate above the bounded topology and macro lanes, while native spherical/hyperbolic renderer ownership and the legacy `WinForms` / `OpenTK` host shell remain explicitly deferred

### 7B — Puzzle State Bridge
- [x] Unreal ↔ MagicTile state serialization
- [x] Shared scramble notation parser
- [x] Unified timer across puzzle types
- Landed bridge on `2026-06-19`: first-party tiling state envelopes and bridge contracts now connect the runtime library, browser widget, and browser bridge surfaces with shared scramble normalization plus unified training-timer continuity

### 7C — Native Behavior Proof Spike
- [x] Land a first-party native behavior proof for selected-cell focus, candidate-twist disambiguation, preview, commit or cancel, and timer continuity above the landed browser host decision and state bridge
- [x] Reuse the landed tiling state-envelope vocabulary only where it remains transport-neutral and first-party owned
- [x] Keep renderer-port ownership, `WinForms` / `OpenTK` host-shell ownership, and generic non-Euclidean runtime-base replacement explicitly deferred
- Landed proof on `2026-06-19`: current code now adds a bounded tiling native-behavior proof contract and proof probe, threads them through the training tiling/runtime libraries with normalization plus JSON round-trip helpers, and closes the pre-renderer interaction gap without claiming renderer ownership
- Validation evidence on `2026-06-19`: the primary reverse-SSH `localhost:22022` lane rebuilt isolated worktree `C:\HyperTwist_worktrees\phase10validate` with `Result: Succeeded` and UnrealBuildTool `Total execution time: 3069.89 seconds`, then exported green automation reports for `7` `HyperTwist.FirstParty.MagicTile.*` tests at `Saved\AutomationReports\Phase7-MagicTile`, `4` `HyperTwist.Browser.*` tests at `Saved\AutomationReports\Browser-Rerun`, and `6` `HyperTwist.Permissive.MagicTile.*` tests at `Saved\AutomationReports\Phase7-Permissive-MagicTile-Rerun`

### 7D — Renderer-Port Decision Gate
- [x] Freeze a spec-only first-party decision packet that turns the landed `Phase 7C` proof seam into explicit go/no-go criteria for any future native renderer widening
- [x] Require any later native renderer request to prove a real browser-host insufficiency, bounded owned-surface scope, `Phase 7C` behavior parity, and a full Windows validation plan before widening can reopen
- [x] Keep the default posture explicit `No-Go` for broad non-Euclidean interaction-shell replacement, `WinForms` / `OpenTK` host-shell reopening, or generic runtime-base replacement
- Spec-only decision gate frozen on `2026-06-19`: `docs/arch/HYPERTWIST_PHASE7D_MAGICTILE_RENDERER_PORT_DECISION_PACKET_2026-06-19.md` now records the authoritative future renderer-port criteria; `Phase 7C` alone no longer implies widening permission
- Evidence audit frozen on `2026-06-19`: `docs/arch/HYPERTWIST_PHASE7D_MAGICTILE_RENDERER_PORT_EVIDENCE_AUDIT_2026-06-19.md` scored the live browser shell, bridge, and `Phase 7C` proof seam against the gate and kept the branch hard `No-Go` because no real browser-host insufficiency or bounded renderer target is currently demonstrated

**Estimated actions:** 80–150
**Estimated time:** 1–2 weeks

---

## Phase 8: Browser-Based Renderer

**Prerequisite:** Phase 2 (classic renderer)

### 8A — Embedded Browser Runtime
- [x] Add `WebBrowserWidget` plugin to `.uproject`
- [x] Create `UHyperTwistBrowserWidget` wrapping `SWebBrowser`
- [x] Load the authoritative local browser shell in `Content/Browser/index.html`, with bundled-runtime upgrade plus clean-checkout plain-JS fallback
- [x] Queue outbound Unreal command and shell-state payloads until the embedded browser runtime reports ready, then flush shell state before queued commands
- Hardening continuation on `2026-06-19`: current code now keeps the live embedded browser lane deterministic above the already-landed shell/bootstrap path by retaining pending widget outbound traffic until the first-party runtime-ready bridge fires, then flushing the latest shell-state payload before queued commands through the browser runtime
- Validation evidence on `2026-06-19`: the primary reverse-SSH `localhost:22022` lane rebuilt isolated worktree `C:\HyperTwist_worktrees\phase10validate` with `Result: Succeeded` and UnrealBuildTool `Total execution time: 96.96 seconds`, then exported green automation reports for `6` `HyperTwist.Browser.*` tests at `Saved\AutomationReports\Browser-Hardening-Verify`, `7` `HyperTwist.FirstParty.MagicTile.*` tests at `Saved\AutomationReports\Phase7-MagicTile-BrowserHardening`, and `6` `HyperTwist.Permissive.MagicTile.*` tests at `Saved\AutomationReports\Phase7-Permissive-MagicTile-BrowserHardening`
- Status-surface continuation on `2026-06-19`: current code now adds shared browser boot-state ownership plus a compact `Browser Runtime Status` surface in both the authoritative bundled shell and the clean-checkout fallback shell, surfacing runtime mode, bootstrap/runtime-ready timestamps, startup queue carryover, bridge traffic counts, and latest command or shell-state receipt facts while keeping the existing embedded browser/CEF posture intact
- Validation evidence on `2026-06-19`: local `npm --prefix Content/Browser run verify:shell` passed and `npm --prefix Content/Browser run build` succeeded, then the primary reverse-SSH `localhost:22022` lane rebuilt isolated worktree `C:\HyperTwist_worktrees\phase10validate` with `Result: Succeeded` and UnrealBuildTool `Total execution time: 160.16 seconds`, and `Automation RunTests HyperTwist.Browser` found `7` `HyperTwist.Browser.*` tests and passed all `7` at `Saved\AutomationReports\Browser-StatusSurface-Verify`
- Native-capture continuation on `2026-06-19`: current code now closes the remaining authority gap below that status surface by decoding first-party `browser-runtime-status` envelopes into typed Unreal-owned structs, retaining the last valid runtime-status snapshot through `UHyperTwistBrowserBridgeObject` and `UHyperTwistBrowserWidget`, and preserving that snapshot across later unrelated envelope traffic until explicit reset
- Validation evidence on `2026-06-19`: the same primary reverse-SSH `localhost:22022` lane rebuilt isolated worktree `C:\HyperTwist_worktrees\phase10validate` with `Result: Succeeded` and UnrealBuildTool `Total execution time: 111.69 seconds`, then `Automation RunTests HyperTwist.Browser` found `8` `HyperTwist.Browser.*` tests and passed all `8` at `Saved\AutomationReports\Browser-RuntimeStatusNativeCapture-Verify`
- Runtime-ready continuation on `2026-06-19`: current code now closes the adjacent handshake gap as well by decoding first-party `hypertwist-runtime-ready` payloads into typed Unreal-owned structs, retaining the last valid runtime-ready payload through `UHyperTwistBrowserBridgeObject` and `UHyperTwistBrowserWidget`, and keeping the existing browser-ready queue-flush behavior intact
- Validation evidence on `2026-06-19`: the same primary reverse-SSH `localhost:22022` lane rebuilt isolated worktree `C:\HyperTwist_worktrees\phase10validate` with `Result: Succeeded` and UnrealBuildTool `Total execution time: 88.20 seconds`, then `Automation RunTests HyperTwist.Browser` found `9` `HyperTwist.Browser.*` tests and passed all `9` at `Saved\AutomationReports\Browser-RuntimeReadyPayload-Verify`
- Native operator-surface continuation on `2026-06-19`: current code now projects a compact native/operator-facing browser runtime status surface from the typed Unreal-owned runtime-ready and runtime-status caches, exposing waiting/ready/live stages, queue carryover, bridge receive counts, runtime mode, adapter count, and shell authority while clearing retained runtime ownership whenever shell authority changes so stale live state cannot survive a browser reload
- Native diagnostics-panel continuation on `2026-06-19`: current implementation now wires that typed browser runtime operator surface into `UHyperTwistTrainingPanelWidget` and `UHyperTwistCoachDashboardWidget`, adds explicit observed-browser attachment control plus a compact `[Browser Runtime Diagnostics]` native dashboard section, and keeps the dashboard inspect seam live-authoritative even before presentation refresh so operators can read waiting/ready/live browser state without opening the embedded browser shell
- Validation evidence on `2026-06-19`: the same primary reverse-SSH `localhost:22022` lane rebuilt isolated worktree `C:\HyperTwist_worktrees\phase10validate` with `Result: Succeeded` and UnrealBuildTool `Total execution time: 3258.26 seconds`, then `Automation RunTests HyperTwist.Browser` exported `Saved\AutomationReports\Browser-NativeOperatorDiagnosticsPanel-Verify\index.json` with `14` `HyperTwist.Browser.*` tests succeeded and `0` failed, including `CoachDashboard.RuntimeInspectSurface` and `TrainingPanel.RuntimeInspectSurface`
- Native diagnostics-fidelity continuation on `2026-06-19`: current code now carries typed browser bootstrap/runtime-ready timestamps, last command and shell-state receipt timestamps, and fallback reason through `FHyperTwistBrowserOperatorStatusSurface` plus the native training/dashboard inspect seams, so Unreal-side diagnostics mirror the authoritative browser runtime status surface more faithfully without reopening topology
- Validation evidence on `2026-06-19`: the same primary reverse-SSH `localhost:22022` lane rebuilt isolated worktree `C:\HyperTwist_worktrees\phase10validate` with `Result: Succeeded` and UnrealBuildTool `Total execution time: 3261.17 seconds`, then `Automation RunTests HyperTwist.Browser` exported `Saved\AutomationReports\Browser-NativeOperatorTimelineFidelity-Verify\index.json` with `14` `HyperTwist.Browser.*` tests succeeded and `0` failed, including `CoachDashboard.RuntimeInspectSurface`, `TrainingPanel.RuntimeInspectSurface`, and `Widget.OperatorStatusSurfaceLive`
- Validation evidence on `2026-06-19`: the same primary reverse-SSH `localhost:22022` lane rebuilt isolated worktree `C:\HyperTwist_worktrees\phase10validate` with `Result: Succeeded` and UnrealBuildTool `Total execution time: 59.53 seconds`, then `Automation RunTests HyperTwist.Browser` exported `Saved\AutomationReports\Browser-NativeOperatorStatusSurface-Reset-Verify\index.json` with `12` `HyperTwist.Browser.*` tests succeeded and `0` failed, including `Widget.OperatorStatusSurfaceWaiting`, `Widget.OperatorStatusSurfaceLive`, and `Widget.OperatorStatusSurfaceResetOnShellChange`

### 8B — State Synchronization
- [x] Bridge UE cube state to browser via embedded Unreal bridge object plus JavaScript `postMessage` fallback
- [x] Browser shell surfaces adapter, analytics, viewer, and native-sidecar request flows while UE retains native input, game state, and puzzle logic ownership
- [ ] Alternative: full browser client with HTTP API to UE backend
- Spec-only branch frozen on `2026-06-19`: `docs/arch/HYPERTWIST_PHASE8B_OPTIONAL_FULL_BROWSER_CLIENT_HTTP_BACKEND_PREPARATION_PACKET_2026-06-19.md` now defines this as an optional first-party browser-owned client above explicit Unreal backend authority; the currently landed shipping posture remains the embedded browser/CEF shell, the adjacent `Phase 7C` native behavior proof is now landed separately, and any later full-browser-client implementation stays deferred on a branch that remains separate from the `Phase 7D` native renderer-port decision gate
- Spec/evidence continuation on `2026-06-19`: `docs/arch/HYPERTWIST_PHASE8B_BROWSER_CLIENT_SPEC_EVIDENCE_HARDENING_PACKET_2026-06-19.md` now tightens that optional branch into explicit first-party seam families for catalog, session, action, state, continuity push, replay, persistence status, and runtime-health transport, reuses the currently owned transport-neutral browser vocabulary only where it remains first-party, and keeps offline-first, public-hosted, and native-renderer widening posture explicitly deferred
- Backend-contract continuation on `2026-06-19`: `docs/arch/HYPERTWIST_PHASE8B_BROWSER_CLIENT_BACKEND_CONTRACT_MATRIX_PACKET_2026-06-19.md` now fixes the transport-neutral operation labels, minimum identity or correlation facts, state freshness and reconnect rules, and the code-grounded payload anchors for state snapshot, runtime-ready, and runtime-health ownership that any later full-browser-client implementation must preserve

**Estimated actions:** 50–80
**Estimated time:** 3–5 days

---

## Phase 9: Social & Export

**Prerequisite:** Phase 3 (playable level)

### 9A — Replay Recording
- [x] Record move sequence + timestamps during solve
- [x] Export to `.json` replay file
- [x] Load replay, reconstruct animation
- [x] Legacy-safe replay packet consumers now preserve current behavior without depending on hand-curated local state ordering
- [x] Replay save, load, and viewer-import paths now repair schema-light packet version, ids, monotonic event ordering, monotonic timestamps, and derived replay summary during normalization

### 9B — Media Export
- [x] Use UE `MovieRenderQueue` as the primary video-export route; treat `remotion-dev/remotion` only as restrictive-custody reference context unless a later clean-room/specification pass explicitly reopens it
- [x] Export solve animation as MP4
- [x] Export scramble + time as shareable image
- [x] Validation evidence on `2026-06-13`: primary reverse-SSH `localhost:22022` lane, isolated Windows worktree `C:\HyperTwist_worktrees\phase10validate`, authoritative `LS_HyperTwist_ClassicReplayCapture` asset authored through `scripts/hypertwist_author_classic_cube_export_assets.py`, offscreen `MovieRenderQueue` export via `scripts/Invoke-HyperTwistClassicCubeMediaExport.ps1` plus `HyperTwistMoviePipelineReplayExecutor.py`, aggregate export report at `Saved\MediaExport\ClassicCube\validation\classic-cube-classic-cube-integration-replay-report.json`, canonical MP4 at `video\classic-cube-classic-cube-integration-replay.mp4`, still at `still\classic-cube-classic-cube-integration-replay-still.png`, share card at `classic-cube-classic-cube-integration-replay-share.png`, and post-proof `ffprobe` sanity confirming `1280x720`, `30 fps`, `85` frames, and `2.8333 s` duration after aligning the authored sequence display rate to the export frame rate

Routing correction:
- `2026-06-12`: `remotion-dev/remotion` is no longer an unproblematic direct widening lane for Phase `9B`; preserve the already-landed first-party `Phase 4R-F` outputs, but route any new donor-backed widening through restrictive custody and prefer Unreal-native export for fresh shipping work

### 9C — Leaderboard Stub
- [x] Local SQLite or JSON leaderboard (no backend yet)
- [x] Store best times per puzzle type + scramble length
- [x] Display in HUD
- [x] Normalize schema-light or duplicate local JSON buckets before resolving the displayed best time
- [x] Centralize the displayed leaderboard status line so legacy-bucket repair and HUD best-time wording resolve through the same deterministic path

**Estimated actions:** 40–60
**Estimated time:** 2–3 days

---

## Phase 10: Validation Reconstruction

**Principle:** Validation only verifies what actually exists.

### 10A — Deprecate Structural-Only Tests
- [x] Mark all Phase J tests that only verify contract ID stability as `Deprecated`
- [x] Do not delete (preserves build history), but stop adding new ones
- Evidence on `2026-06-19`: `221` retained `Phase J` files now carry `443` deprecated validation identifiers plus `443` disabled flags, with `0` remaining live `HyperTwist.Validation.*` or `HyperTwist.FirstParty.Validation.*` names

### 10B — Behavior-Based Validation Tests
- [x] `FHyperTwistClassicCubeRotationTest`: Rotate R face, assert piece positions updated
- [x] `FHyperTwistClassicCubeSolveTest`: Apply known solution, assert solved-state
- [x] `FHyperTwistSolverAccuracyTest`: Validate 100 deterministic runtime-exported classic-cube states through exact inverse-scramble verification plus runtime round-trip, while dedicated native solver search stays covered by `HyperTwist.Solver.*` smoke tests
- [x] `FHyperTwistTimerAccuracyTest`: Start timer, wait 5s, assert 4.9s < elapsed < 5.1s
- [x] `FHyperTwistSpeechTranscriptionTest`: Synthetic PCM "R prime" → assert move parsed

### 10C — Integration Tests
- [x] Launch `L_HyperTwist_ClassicTraining`, simulate 10 moves, verify no crash
- [x] Package build test: verify `UnrealHyperTwist.exe` launches and cube is visible
- [x] The packaged validation helper now smoke-boots every cooked classic-cube training map by default instead of depending on a remembered second manual launch
- [x] Validation evidence on `2026-06-13`: primary reverse-SSH `localhost:22022` lane, isolated Windows worktree `C:\HyperTwist_worktrees\phase10validate`, commandlet-safe `UnrealMCP` and `UnrealMCPChong` guards landed for unattended cook, `BuildCookRun` `ExitCode=0` with `BuildCookRun time: 164.59 s`, archive output in `C:\HyperTwist_worktrees\phase10validate_packaged`, packaged smoke boot on `L_HyperTwist_ClassicTraining`, and explicit packaged smoke boot on `/Game/HyperTwistTraining/Maps/L_HyperTwist_FollowAlongTraining`
- [x] Repair validation evidence on `2026-06-13`: the maintained helper itself was re-run on the same primary reverse-SSH `localhost:22022` lane against isolated worktree `C:\HyperTwist_worktrees\phase10validate`, wrote archive output to `C:\HyperTwist_worktrees\phase10validate_packaged_repair`, completed `BuildCookRun` with `ExitCode=0` and `BuildCookRun time: 116.89 s`, then default-smoke-launched both `/Game/HyperTwistTraining/Maps/L_HyperTwist_ClassicTraining` and `/Game/HyperTwistTraining/Maps/L_HyperTwist_FollowAlongTraining` without a manual second launch step
- [x] Focused validation evidence on `2026-06-19`: the same primary reverse-SSH `localhost:22022` lane rebuilt isolated worktree `C:\HyperTwist_worktrees\phase10validate` with `Result: Succeeded` and UnrealBuildTool `Total execution time: 3069.89 seconds`, then exported green automation reports for `7` `HyperTwist.FirstParty.MagicTile.*` tests, `4` `HyperTwist.Browser.*` tests, and `6` `HyperTwist.Permissive.MagicTile.*` tests while closing the bounded `Phase 7C` native behavior proof slice
- [x] Continuation evidence on `2026-06-13`: after a prior aborted broad tar sync corrupted remote `HyperTwistWhisperCppPhase6RESpeechTranscriptContractTest.cpp`, the primary reverse-SSH `localhost:22022` lane hash-matched the changed slice files back into `C:\HyperTwist_worktrees\phase10validate`, completed the canonical `Build.bat` pass with `Result: Succeeded` and UnrealBuildTool `Total execution time: 2029.78 seconds`, passed all `7` `HyperTwist.Integration.ClassicCube` tests including `ReplayPersistenceNormalization`, `LeaderboardNormalization`, and `LeaderboardStatusLine`, refreshed `Phase 10B` coverage through green `Rotation`, `Solve`, `RandomClassicStates`, `Timer.Accuracy`, and `ClassicCubeMoveParsing` commandlet passes, and revalidated the maintained package helper in `-SkipBuild` mode with `BuildCookRun time: 69.16 s`, archive output in `C:\HyperTwist_worktrees\phase10validate_packaged_phase10b10c9a9c`, aggregate JSON at `validation\classic-cube-package-validation-report.json`, per-map smoke JSON under `validation\smoke\`, and successful smoke boots on both classic-cube training maps
- [x] Hardening slice on `2026-06-18`: replay normalization now repairs missing replay/session ids, duplicate event ids, out-of-order sequences, and monotonic timestamp drift before persisted packets are reused; leaderboard normalization now repairs schema-light entries before best-time/status resolution; and the maintained package helper now fails fast on missing smoke JSON, unparseable smoke JSON, non-`passed` smoke results, or unexpected `mapUrl` drift.
- [x] Validation evidence on `2026-06-18`: the same primary reverse-SSH `localhost:22022` lane rebuilt isolated worktree `C:\HyperTwist_worktrees\phase10validate` after the Phase 10B truthfulness correction and solver-wrapper distribution hardening, then refreshed `20` relevant tests with `0` failures in `134.97 s`, including green `HyperTwist.Simulation.ClassicCube.Behavior.*`, `HyperTwist.Solver.*`, `HyperTwist.Training.Timer.Accuracy`, `HyperTwist.Speech.Transcription.ClassicCubeMoveParsing`, and all `11` `HyperTwist.Integration.ClassicCube.*` cases. `RandomClassicStates` now records runtime facelet export, exact inverse-scramble verification, and runtime round-trip solve instead of pretending the native solver lane is a bounded 100-state benchmark; `Timer.Accuracy` remained green with environment-only unresolved `vision`/`speech` hostname warnings in the unattended lane.
- [x] Package evidence on `2026-06-18`: the same primary reverse-SSH `localhost:22022` lane then re-ran the maintained helper on isolated worktree `C:\HyperTwist_worktrees\phase10validate` with explicit runtime-only cooker exclusions `-DisablePlugins=MovieRenderPipeline` and `-SkipCookingEditorContent`, clearing the editor-only `MovieRenderPipeline` blueprint contamination that had blocked the first repair attempt. `BuildCookRun` completed with `ExitCode=0`, `BuildCookRun time: 1381.37 s`, archive output in `C:\HyperTwist_worktrees\phase10validate_packaged_phase10b10c_repair4`, aggregate validation JSON at `validation\classic-cube-package-validation-report.json` with `result: passed`, per-map smoke JSON under `validation\smoke\`, and successful packaged smoke boots on both `/Game/HyperTwistTraining/Maps/L_HyperTwist_ClassicTraining` and `/Game/HyperTwistTraining/Maps/L_HyperTwist_FollowAlongTraining`.
- [x] Shipping Alpha repair evidence on `2026-07-23`: the maintained
  `localhost:22023` reverse-SSH lane rebuilt the current first-party source in
  `C:\HyperTwist_worktrees\phase10validate`, passed all `5`
  `HyperTwist.FirstRun` tests, and produced Release 17 at
  `C:\HyperTwist_worktrees\phase10validate_packaged_alpha_release17_20260723`.
  The package now resolves nondefault startup through strict registered
  `-HyperTwistStartupRoute` ids instead of ineffective raw map arguments,
  writes first-party direct diagnostics in stock Shipping, and carries
  compile-time-disabled trace control plus verified outer-bootstrap
  `-notraceserver -traceautostart=0` arguments.
- [x] Release 17 package semantics on `2026-07-23`: all four fresh smokes
  passed with exact `MapReady` evidence; Classic and Follow-Along each exposed
  `26` renderable cubies and settled valid state, Magic120Cell exposed exactly
  `120` canonical elements with `6` layer materials, and MagicCube5D exposed
  exactly `242` canonical elements with `6` layer materials. No package-owned
  listener, trace-control endpoint, or fatal signature was observed.
- [x] Release 17 visual/distribution proof on `2026-07-23`: the exact final
  Downloads executable rendered a fresh semantic first-run frame with
  `launch-menu-renderable`; a real client-window message on the visible
  Classic button produced `map-route-opened`, the exact Classic map, 26
  renderable cubies, orbit camera, HUD, and settled valid state. The delivered
  folder at
  `C:\Users\Anthracite Ace\Downloads\HyperTwist-Alpha-Test-20260723` contains
  `103` files and the verified sibling ZIP contains `103` entries,
  `1082134734` bytes, SHA-256
  `1ad8e1c0fc967b227ca09fb68c515ed644eca3e4bda07fdf8c378b438000fc42`.
  The ZIP was reopened and all seven critical payloads were independently
  stream-hashed. Durable proof lives under
  `docs/generated/alpha_test_20260723`.
- [ ] Operator-connected dashboard visual follow-up: the final Shipping
  executable already accepts and opens the registered `coach-dashboard` route
  under direct NullRHI diagnostics, but a fresh dashboard screenshot must wait
  for an unlocked/live Windows desktop. Disconnected-session exit or
  desktop-copy output must remain a rejected visual rather than a false green.
- [x] Release 19 combined package gate on `2026-07-23`: the exact source
  containing the eight native puzzle entries, Learning Studio, player-facing
  settings, Account/About surfaces, fixed coach, exact 4D/5D/120-cell
  runtimes, and strengthened Phase 1 browser roster completed a fresh Shipping
  build/cook/archive. The package verified staged browser assets and the exact
  solver table, passed all `9` native route smokes, reopened and hashed a
  `167`-entry ZIP, hash-matched all `173` delivered folder files, and passed
  independent semantic `launch-menu-renderable` gates from both the validation
  archive and the exact Downloads executable.
- [x] Release 19 global-assistant repair on `2026-07-23`: standalone speech
  sessions no longer require an active Classic training run, so the fixed
  coach can own global STT on 4D, 5D, and 120-cell routes. The UE 5.7 rebuild
  succeeded in `60.93` seconds and all `5`
  `HyperTwist.PlayerExperience` tests passed, including
  `GlobalAssistantSpeechSession`.
- [x] Release 19 Windows installer and isolated-host lifecycle gate on
  `2026-07-26`: a first-party NSIS installer now owns x64/Windows preflight,
  the signed Microsoft Visual C++ runtime, a complete `143`-file SHA-256
  manifest, safe install-root and marker/registry ownership, resolved
  shortcuts, readiness reporting, in-place upgrade, and uninstall that
  preserves user data. The final `851049086`-byte installer passed first
  install, full parity, stock-Shipping launch, upgrade, second parity,
  uninstall, and cleanup from a path containing spaces. Durable proof lives in
  `docs/generated/alpha_test_20260726_installer`.

**Estimated actions:** 20–30
**Estimated time:** 1–2 days

---

## Cross-Cutting Concerns

### Licensing & Attribution
- Each wired repo gets a `LICENSE.thirdparty` entry
- GPL repos (brownan) remain IPC-only; never linked
- MIT/Apache repos compile and link directly
- Attribution bundles updated from metadata-only to runtime-provenance

### Build Validation Doctrine
- Every phase requires Windows Unreal build validation
- Phase 0–1: expect 50–100 actions (infrastructure)
- Phase 2–3: expect 150–250 actions (geometry + input)
- Phase 4+: expect 80–150 actions (feature wiring)
- Package validation (Phase 3C) is the real gate, not Editor build

### Documentation Rule
- Docs describe what IS implemented, not what MIGHT be
- No new "packet" files for scaffolding
- Architecture docs updated only after functional code is merged

---

## Summary: What Changes vs. Old Roadmap

| Old Approach | New Approach |
|--------------|--------------|
| Add struct pairs (J-HG → J-HM) | Wire repos (freestyle, piper, rob-twophase) |
| Tests verify contract IDs | Tests verify cube rotation, solve accuracy, speech |
| Docs claim features are "landed" | Features are playable before documented |
| 318 test files, 0 gameplay | 30+ targeted tests, 1 controller-owned classic-cube runtime loop |
| 1,142 docs, 20 content assets | Docs trimmed to functional truth |
| No donor repos linked | C++ repos compiled and linked |
| No .uasset, .umap | Dedicated `.umap` assets plus authored classic-cube material family are now source-controlled, and packaged validation is green for both classic and follow-along training maps |

---

## Immediate Next Step

**Current Alpha next move (`2026-07-26`):** Release 19 is now the current
portable and installed-Alpha authority at
`C:\Users\Anthracite Ace\Downloads\HyperTwist-Alpha-Test-20260723-R19` and
`C:\Users\Anthracite Ace\Downloads\HyperTwist-Alpha-Test-20260723-R19-Setup.exe`,
while Release 17 remains rollback authority until operator acceptance.
Installer/uninstaller and isolated-current-host prerequisite proof are closed.
Prioritize trusted Authenticode signing, a genuinely fresh Windows VM install,
entitlement-backed public release URLs, and update-channel/rollback rollout
proof next. Separately retain the real-hardware XR/controller observation and
configured-provider AI/STT/TTS audible smoke as external-condition gates. Do
not reopen MagicTile native-renderer widening or unrelated simulator topology
to perform this release engineering.

**Phase 1 through Phase 5 are now closed on the intended simulator lane:** repo wiring, the
classic-cube renderer/runtime loop, dedicated training maps and materials, solver-guided training,
and speech command or narration surfaces are implemented and validated through Windows build,
automation, and packaged smoke evidence.

Already-proven dedicated-map package lane:
- `localhost:22023` fallback reverse-SSH lane
- isolated Windows worktree `C:\HyperTwist_worktrees\phase3to5`
- durable authoring through `scripts/Invoke-HyperTwistClassicCubeMapAuthoring.ps1` and `scripts/hypertwist_author_classic_cube_training_maps.py`
- packaged archive in `C:\HyperTwist_worktrees\phase3to5_packaged`
- packaged smoke launch succeeded for both `/Game/HyperTwistTraining/Maps/L_HyperTwist_ClassicTraining` and `/Game/HyperTwistTraining/Maps/L_HyperTwist_FollowAlongTraining`

Recommended next widening order:
- `Phase 6C` decision gate and bounded runtime widening for `Magic120Cell` /
  `MagicCube5D` now that the visible `3x3x3x3` packet is landed and validated
- `2026-06-13`: `Phase 6C` entered the owned clean-room lane through a new
  first-party higher-dimensional runtime-activation catalog that resolves
  canonical `polychoron/magic120cell` and `hypercube/magiccube5d/order3`
  puzzle definitions, primary donor-boundary contract ids, and default
  launch-selection posture without widening into an external-process bridge
- `2026-06-13`: the next `Phase 6C` continuation widened that owned activation
  lane into active run-state/runtime surfaces by resolving higher-dimensional
  activation through both puzzle-id and imported generated-mode
  `RuntimeModeId` paths, mirroring the result into the training panel/session
  caches, and validating the slice on `localhost:22022` with `5` passing
  `HyperTwist.FirstParty.HigherDimensional.Phase6C` tests
- `2026-06-18`: the next `Phase 6C` continuation widened that same lane again
  into bundled launch and view-context catalogs plus owned shared-map launch
  and generated-mode execution surfaces, then revalidated the cleaned code on
  `localhost:22022` with `8` passing
  `HyperTwist.FirstParty.HigherDimensional.Phase6C` tests; the long quiet
  `LaunchExecution` interval is now known to be healthy rather than a stall
- `2026-06-18`: the next `Phase 6C` continuation added an explicit
  higher-dimensional host-surface catalog that preserves preferred dedicated
  `Magic120Cell` / `MagicCube5D` host-map targets above the current shared-map
  fallback, mirrors that host seam into the launch/view-context surfaces plus
  the training panel/session caches, and revalidated the widened slice on
  `localhost:22022` with `9` passing
  `HyperTwist.FirstParty.HigherDimensional.Phase6C` tests, including the new
  `HostCatalog`
- `2026-06-18`: the next `Phase 6C` continuation added an explicit
  higher-dimensional runtime-session catalog that merges the launch, host, and
  view-context seams into one executed family-owned session posture, upgrades
  generated-mode lineage plus start-time selector application to use the
  merged launch-plus-view defaults, and revalidated the widened slice on
  `localhost:22022` with `10` passing
  `HyperTwist.FirstParty.HigherDimensional.Phase6C` tests, including the new
  `SessionCatalog`
- `2026-06-18`: the next `Phase 6C` continuation added an explicit
  higher-dimensional interactive-scene catalog that promotes the landed
  `Magic120Cell` / `MagicCube5D` runtime-session seams into family-owned
  scene-context contracts, mirrors those surfaces through the training runtime
  library plus the live training panel/session caches, upgrades generated-mode
  lineage plus source attribution to record the scene-surface and scene-context
  ids, and revalidated the widened slice on `localhost:22022` with `11`
  passing `HyperTwist.FirstParty.HigherDimensional.Phase6C` tests, including
  the new `InteractiveSceneCatalog`
- `2026-06-18`: the next `Phase 6C` continuation then closed the previously
  open ownership gap by replacing the placeholder `Magic120Cell` /
  `MagicCube5D` interactive-scene envelopes with family-owned runtime-state,
  projection, and persistence payloads, swapping the shared-map bridge for
  dedicated-family training-map assets plus dedicated host/launch/view-context/
  session surfaces, and tightening generated-mode selector application so the
  rerun on `localhost:22022` still passed all `11`
  `HyperTwist.FirstParty.HigherDimensional.Phase6C` tests while dropping the
  long `LaunchExecution` quiet interval from `385.00` to `195.58` seconds
- `2026-06-18`: the next `Phase 6C` hardening pass then deferred repository-
  view projection across the internal generated-mode launch handoff itself, and
  the same `localhost:22022` lane still passed all `11`
  `HyperTwist.FirstParty.HigherDimensional.Phase6C` tests while dropping the
  `LaunchExecution` quiet interval again from `195.58` to `41.52` seconds
- `2026-06-18`: the next `Phase 6C` recovery-proof pass then turned the new
  dedicated-family maps into deterministically regenerated headless-owned
  artifacts through `scripts/hypertwist_author_higher_dimensional_training_maps.py`,
  stamped explicit `PlayerStart` puzzle and ownership tags plus the rest of
  the higher-dimensional ownership contract into those maps, preserved the
  optional `AHyperTwistHigherDimensionalTrainingShellActor` only for manual or
  editor authoring because `UnrealEditor-Cmd` still crashes when spawning it,
  and revalidated the corrected slice on `localhost:22022` with all `13`
  `HyperTwist.FirstParty.HigherDimensional.Phase6C` tests passing, including
  `DedicatedMapAuthoringManifest` and `DedicatedMapOwnedShell`; pulled proof
  now lives in `docs/generated/higher_dimensional_training_maps/phase6c_dedicated_family_map_manifest.json`
  and `docs/generated/higher_dimensional_training_maps/phase6c_dedicated_map_ownership_automation_report.json`
- later classic-cube polish only when a concrete presentation gap remains, not as the default next move
