# HyperTwist - ARCHITECTURE.md

## Product identity

HyperTwist is a native training environment for cubes and hypercubes.

Its special strength is that it joins:

- physical-world cube interaction and analysis
- virtual simulation and higher-dimensional training
- training/coaching orchestration
- bounded speech/voice and provider-backed sidecar contracts

## Canonical discovery surfaces

Use these alongside this document:

- `FEATURE_REGISTRY.md` for normalized feature families and confidence tiers
- `CAPABILITY_CONSOLIDATION_DOCTRINE.md` for lane consolidation
- `WORKBENCH_FEATURE_TARGETS.md` for cockpit/workbench targets
- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md`
  for memory-lane architecture
- `C:\HyperTwist\docs\ops\HYPERTWIST_CONTINUITY_LATTICE_AND_CONTEXT_ASSEMBLY_PROFILE_DOCTRINE_2026-05-23.md`
  for continuity substrate and context-assembly profiles
- `C:\HyperTwist\docs\VECTORSHELL_MEMORY_SYSTEM_IMPORT_AUTHORITY_FOR_HYPERTWIST_2026-05-25.md`
  for the live VectorShell-memory authority map and delta-sync rule
- `C:\HyperTwist\docs\ops\HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md`
  for optional assistive and off-state governance
- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md`
  for provider/BYOK architecture
- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md`
  for current landed runtime anchors

## Runtime center

The runtime center is Unreal Engine.

HyperTwist is not merely a trainer app. It wants:

- high-quality rendering
- embodied puzzle manipulation
- replay and inspection surfaces
- higher-dimensional spatial intuition
- future XR expansion

## Current landed architecture truth

HyperTwist already has real first-party runtime anchors in current code:

- `UHyperTwistTrainingSubsystem`
- `UHyperTwistTrainingRuntimeLibrary`
- `UHyperTwistTrainingPanelWidget`
- `AHyperTwistTrainingSessionActor`
- `UHyperTwistCoachDashboardWidget`
- `UHyperTwistTrainingCatalogLibrary`
- `UHyperTwistTrainingTilingLibrary`
- bounded provider/session clients for vision and speech

Do not treat the remaining retained portfolio as already architecturally
absorbed.

## Backbone language strategy

### C++

Use for:

- puzzle-state core
- renderer/runtime integration
- interaction hot paths
- replay engine
- native timer and analytics primitives
- topology/geometry logic

### Rust or C++

Use for:

- algorithm engines
- search/scoring
- serialization
- high-throughput replay/analytics pipelines

### Python / TypeScript

Keep bounded:

- Python for sidecar inference/service orchestration when still practical
- TypeScript/web only for thin adjunct surfaces

## Canonical product lanes

### 1. Physical cube pipeline

- camera/frame input
- calibration
- observation capture
- reconstruction
- correction UI
- replay generation

### 2. Training and coaching pipeline

- training sessions
- drills
- follow-up flows
- coach summaries
- analytics/reporting
- publication/social training surfaces

### 3. Hyper puzzle pipeline

- hyper puzzle catalog
- topology families
- notation/runtime contracts
- immersive/world presentation

### 4. Speech/provider sidecar pipeline

- speech transcript sessions
- provider-backed speech/vision health/session contracts
- later provider-neutral BYOK/profile model

## Subsystem posture

Recommended subsystem families remain:

- `HyperTwistCore`
- `HyperTwistSimulation`
- `HyperTwistRecognition`
- `HyperTwistReplay`
- `HyperTwistTraining`
- `HyperTwistCoach`
- `HyperTwistProgression`
- `HyperTwistXR`
- later bounded memory/provider/skill families where justified

## Provenance control plane

Architecture decisions must preserve three visible layers:

- landed/live first-party implementation
- retained donor backlog pending bounded implementation
- restrictive clean-room or benchmark/reference lanes

That provenance split is architecture, not just legal paperwork.

Companion trust surface:

- `PROVENANCE_AND_TRUST_MODEL.md`

## Memory and provider correction

Do not treat memory as one opaque monolith.

Do not treat provider-specific donors as top-level contract owners.

For cross-project memory synchronization, use:

- `C:\HyperTwist\docs\VECTORSHELL_MEMORY_SYSTEM_IMPORT_AUTHORITY_FOR_HYPERTWIST_2026-05-25.md`

as the live VectorShell-memory entrypoint.

This is a pointer-based synchronization surface, not a frozen local fork and
not a brand-new replacement memory spec.

Those two corrections are governed by:

- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_CONTINUITY_LATTICE_AND_CONTEXT_ASSEMBLY_PROFILE_DOCTRINE_2026-05-23.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md`

## Continuity substrate

HyperTwist's federated continuity and memory substrate is now referred to
internally as the `Continuity Lattice`.

That means:

- one federated substrate
- bounded `Memory Lanes`
- explicit provenance
- explicit custody
- two context-assembly profiles:
  - `Max-Retention Mode`
  - `Economic-Retention Mode`
- those profiles are preset-backed defaults for context assembly, not rigid
  bundles
- optional assistive components inside those profiles remain individually
  controllable
- the profiles may set defaults, but they must remain overrideable and must
  not weaken provenance, custody, lane separation, clean-room boundaries, or
  raw-authority preservation

It does not mean:

- one monolithic memory blob
- summary-first authority
- a second memory system competing with the established memory-lane doctrine

It also does not mean:

- automatic whole-repo absorption when a later donor wins one exact memory
  sub-slice
- silent architecture rewrite from one packet-local authority revision
- direct donor-code copying for an `R3` slice

If HyperTwist later needs a broader VectorShell-memory import, do it in this
order:

1. VectorShell doctrine and authority docs first
2. first-party VectorShell code and contract surfaces second
3. bounded donor-derived adjuncts third

Until VectorShell declares a stable export point, keep the synchronization
pointer-based and slice-local.

## Skillization correction

Do not let donor commands or optional skills become hidden product truth.

Future skill growth must follow:

- `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md`
