# 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`
- `AHyperTwistPlayerControllerBase`
- `UHyperTwistPlayerSettingsLibrary`
- `UHyperTwistSettingsPanelWidget`
- `UHyperTwistCoachAssistantWidget`
- `UHyperTwistDictationCaptureComponent`
- bounded provider/session clients for vision and speech

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

### Native player experience and provider control

`AHyperTwistPlayerControllerBase` is the common player-facing owner for pause,
main-menu return, desktop exit, the fixed coach, global dictation, optional
coach narration, and runtime preference application across native puzzle
routes. Puzzle-specific controllers inherit that ownership rather than
reimplementing modal navigation or speech lifecycle independently.

`FHyperTwistPlayerPreferences` and `UHyperTwistPlayerSettingsLibrary` own the
persisted control-center contract:

- keyboard profile and conflict-checked remapping
- pointer, orbit, zoom, inversion, and touch preferences
- master, music, effects, and voice volume
- graphics quality, window mode, resolution scale, and VSync
- UI scale, reduced motion, high contrast, and subtitles
- separate AI, STT, and TTS provider, endpoint, model, and behavior settings
- explicit cloud-provider consent
- microphone selection and non-retaining device test
- current-Windows-user protected provider credentials

The provider endpoint boundary is local-first. Loopback HTTP is permitted;
remote providers require HTTPS and explicit cloud consent. Credentials are not
stored in the ordinary preference payload. AI, STT, and TTS are optional, and
the built-in guide remains available without a provider or API key.

`UHyperTwistCoachAssistantWidget` is a fixed native in-game panel, not a
floating operating-system window. It owns bounded session-only conversation,
quick prompts, local fallback guidance, optional generated replies, dictation
draft/submit, and narration status. `UHyperTwistDictationCaptureComponent`
owns microphone PCM capture, audio ducking, transient WAV submission, and
cleanup. The training subsystem can create a standalone `speech-global-*`
session when no training run exists, which keeps global dictation available on
4D, 5D, and 120-cell routes instead of coupling speech to Classic training.

This design was informed by a read-only FamiliarOS product-pattern review, but
the implementation is independent Unreal-native code. FamiliarOS renderer,
desktop-agent, transcript-history, and MCP ownership are not imported into the
game.

## 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

## Browser delivery boundary

Current shipping browser posture remains the landed embedded browser/CEF shell
inside Unreal through `UHyperTwistBrowserWidget` and the authoritative
`Content/Browser/index.html` surface.

That live shipping lane was further hardened on `2026-06-19`: Unreal-side
outbound command and shell-state payloads now queue until the first-party
browser runtime-ready bridge arrives, then flush shell state before queued
commands so the embedded browser lane stays deterministic across startup.

That same shipping lane was then hardened again on `2026-06-19`: the native
browser bridge now decodes and retains typed first-party
`browser-runtime-status` envelopes so Unreal owns the same runtime-health
snapshot the browser shell projects, and preserves the last valid snapshot
across later unrelated envelope traffic until explicit reset.

That same shipping lane was then hardened once more on `2026-06-19`: the
native browser bridge now also decodes and retains the typed first-party
`hypertwist-runtime-ready` handshake payload, so the original browser-ready
authority seam is no longer raw JSON only even though the existing queue flush
behavior remains unchanged.

That same shipping lane now also projects a compact native/operator-facing
waiting, ready, and live status surface from those retained typed caches,
including queue carryover, bridge receive counts, runtime mode, adapter count,
and shell authority, and clears retained runtime ownership whenever shell
authority changes so stale live state cannot survive a shell reload.

That same native/operator-facing seam is now also wired into small Unreal
training/operator HUD consumers: `UHyperTwistTrainingPanelWidget` can observe
an attached `UHyperTwistBrowserWidget`, and
`UHyperTwistCoachDashboardWidget` now surfaces a compact
`[Browser Runtime Diagnostics]` panel while keeping its inspect getter tied to
live browser-runtime ownership rather than cached rendered strings.

That same native diagnostics seam now also carries the browser shell's typed
bootstrap/runtime-ready timestamps, last command/shell-state receipt facts,
and fallback reason through the Unreal-owned operator and training/dashboard
inspect surfaces, so native diagnostics stay closer to the authoritative
browser status surface without widening into a new browser topology.

The optional full-browser client path now exists only as a spec-defined
first-party branch:

- the browser client may own rendering, local presentation, and input
  composition
- Unreal remains authoritative for puzzle state, training session state,
  timer continuity, replay, and persistence through explicit backend seams
- request/response plus optional push/update transport stay first-party
  boundaries rather than implicit browser-shell inheritance
- the landed browser-state bridge should be reused only where its vocabulary is
  transport-neutral and still owned in first-party terms
- the currently accepted transport-neutral browser vocabulary is
  `hypertwist-command`, `hypertwist-shell-state`, `hypertwist-state`,
  `hypertwist-command-result`, `hypertwist-runtime-ready`, and
  `browser-runtime-status`
- any later implementation must stay inside explicit first-party seam families
  for catalog, session, action submission, state snapshot, continuity push,
  replay, persistence status, and runtime health
- any later implementation must also preserve the current first-party identity
  and freshness chain from the owned browser/runtime envelopes, including
  session identity, host decision identity, bridge contract identity,
  correlation posture, authoritative capture or emission timing, and
  runtime-health source facts
- the minimum owned payload anchors for that later branch are the current
  tiling state envelope plus the current `hypertwist-runtime-ready` and
  `browser-runtime-status` fact sets rather than a new browser-only schema
- reconnect must rehydrate from authoritative Unreal state; offline-first
  browser-side mutation authority remains deferred
- this is not current shipping posture, not a general browser-first rewrite,
  and not permission to widen into native `MagicTile` renderer-port work

Canonical spec note:

- `C:\HyperTwist\docs\arch\HYPERTWIST_PHASE8B_OPTIONAL_FULL_BROWSER_CLIENT_HTTP_BACKEND_PREPARATION_PACKET_2026-06-19.md`
- `C:\HyperTwist\docs\arch\HYPERTWIST_PHASE8B_BROWSER_CLIENT_SPEC_EVIDENCE_HARDENING_PACKET_2026-06-19.md`
- `C:\HyperTwist\docs\arch\HYPERTWIST_PHASE8B_BROWSER_CLIENT_BACKEND_CONTRACT_MATRIX_PACKET_2026-06-19.md`
- `C:\HyperTwist\docs\arch\HYPERTWIST_PHASE7D_MAGICTILE_RENDERER_PORT_DECISION_PACKET_2026-06-19.md`

The narrow first-party `MagicTile` native behavior proof is now landed as the
pre-renderer decision gate through the bundled tiling native-behavior proof
contract/probe seam in the training tiling/runtime libraries.

Any later native `MagicTile` renderer-port widening remains a separate explicit
decision beyond that now-landed `Phase 7C` proof seam, and the default posture
for that branch is now `No-Go` unless the separate `Phase 7D` decision packet
criteria are satisfied.

The adjacent `Phase 7D` evidence audit on `2026-06-19` kept that verdict in
force after reviewing the live browser shell, browser bridge, bundled/fallback
runtime path, host-bridge tests, and `Phase 7C` proof seam: the current lane
does not yet show a real browser-host insufficiency or a bounded renderer-only
target.

## 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

Current owned split inside that lane:

- `HyperTwistCore` carries exact Melinda `2x2x2x2` legality, transform, random-state,
  scramble-packet, and flat-projection ownership
- `HyperTwistSimulation` carries the visible cell-first runtime packet above that core,
  including procedural cell projection, click-to-twist interaction surfaces, and
  hyper-runtime scene-context composition
- `HyperTwistSimulation` now also carries a separate bounded virtual `3x3x3x3`
  visible-slice packet with exact slice-state updates, low-occlusion
  projection, keyboard interaction surfaces, and scene-context wiring
- the generalized 4D family now owns exact order-specific `N^4` state, legal
  turns, projection, persistence, dedicated game modes, and dedicated maps for
  orders `2` through `6`
- `UHyperTwistMagic120CellRuntimeLibrary` owns an exact `7,560`-facelet
  permutation, `7,440` legal base moves, inverse/forward turns, focus,
  projection state, and persistence; its current scene remains a deliberately
  bounded representative `120`-center visualization
- `UHyperTwistMagicCube5DRuntimeLibrary` owns exact order-3 5D state with `243`
  cubies, `810` facelets, legal turns, focus, projection layers, and
  persistence

#### Immersive training environment lane

HyperTwist now carries one explicit first-party immersive lane with the
foundational `Phase I-A`, focus-presence `Phase I-B`, and teaching/staging
`Phase I-C`, reactive cue `Phase I-D`, and hardening `Phase I-E` slices landed
in current code:

- scenic virtual training environments and focus-presence shells

Architecturally, this should be interpreted as:

- a HyperTwist-native training/runtime environment layer
- a place for puzzle focus, replay staging, and spatial coaching
- a bounded immersive shell around the training runtime
- an already landed hardening layer for comfort-safe transitions,
  accessibility-legibility review, performance budgets, and reduced-effects
  fallback posture

It should not be interpreted as:

- a generic productivity workspace
- a virtual desktop or floating-monitor shell
- a VectorShell-derived cockpit architecture

Canonical scoping note:

- `C:\HyperTwist\docs\HYPERTWIST_VIRTUAL_TRAINING_ENVIRONMENT_AND_SCENIC_IMMERSION_SCOPING_NOTE_2026-05-31.md`

#### Validation and benchmarking lane

HyperTwist now carries one explicit first-party validation and benchmarking
lane with the bounded `Phase J-A` foundation, `Phase J-B` regression/delta
follow-on, `Phase J-C` evidence/fixture follow-on, and `Phase J-D`
run-review follow-on, `Phase J-E` triage/sign-off follow-on, and `Phase J-F`
exception/closure follow-on, and `Phase J-G` carry-forward/continuity
follow-on, `Phase J-H` disposition/reopen follow-on, and `Phase J-I`
deferred-followup/revisit follow-on, and `Phase J-J`
completion/pending-clearance follow-on, and `Phase J-K`
dormant/resurfacing follow-on, and `Phase J-L`
return-readiness/wake-confirmation follow-on, and `Phase J-M`
resumed-state/continuation-attestation follow-on, and `Phase J-N`
stable-state/continuation-state-digest follow-on, and `Phase J-O`
settled-state/ongoing-state-confirmation follow-on, and `Phase J-P`
persistent-state/ongoing-state-acknowledgement follow-on, and `Phase J-Q`
durable-state/ongoing-state-attestation follow-on, and `Phase J-R`
enduring-state/ongoing-state-certification follow-on, and `Phase J-S`
sustained-state/ongoing-state-assurance follow-on, and `Phase J-T`
anchored-state/ongoing-state-affirmation follow-on, and `Phase J-U`
grounded-state/ongoing-state-endorsement follow-on, and `Phase J-V`
rooted-state/ongoing-state-ratification follow-on, and `Phase J-W`
embedded-state/ongoing-state-reconciliation follow-on, and `Phase J-X`
nested-state/ongoing-state-harmonization follow-on, and `Phase J-Y`
layered-state/ongoing-state-alignment follow-on, and `Phase J-Z`
stacked-state/ongoing-state-convergence follow-on, and `Phase J-AA`
composite-state/ongoing-state-synthesis follow-on, and `Phase J-AB`
aggregated-state/ongoing-state-consolidation follow-on, and `Phase J-AC`
integrated-state/ongoing-state-unification follow-on, and `Phase J-AD`
fused-state/ongoing-state-coherence follow-on, and `Phase J-AE`
merged-state/ongoing-state-concordance follow-on, and `Phase J-AF`
blended-state/ongoing-state-correspondence follow-on, and `Phase J-AG`
interlaced-state/ongoing-state-affinity follow-on, and `Phase J-AH`
woven-state/ongoing-state-resonance follow-on, and `Phase J-AI`
knotted-state/ongoing-state-harmonic follow-on, and `Phase J-AJ`
braided-state/ongoing-state-cadence follow-on, and `Phase J-AK`
looped-state/ongoing-state-refrain follow-on, and `Phase J-AL`
spiraled-state/ongoing-state-chorus follow-on, and `Phase J-AM`
coiled-state/ongoing-state-reprise follow-on, and `Phase J-AN`
helixed-state/ongoing-state-echo follow-on, and `Phase J-AO`
twisted-state/ongoing-state-reflection follow-on, and `Phase J-AP`
wound-state/ongoing-state-reverberation follow-on, and `Phase J-AQ`
folded-state/ongoing-state-aftertone follow-on, and `Phase J-AR`
creased-state/ongoing-state-residue follow-on, and `Phase J-AS`
pleated-state/ongoing-state-remnant follow-on, and `Phase J-AT`
crimped-state/ongoing-state-imprint follow-on, and `Phase J-AU`
corrugated-state/ongoing-state-trace follow-on, and `Phase J-AV`
ribbed-state/ongoing-state-signature follow-on, and `Phase J-AW`
fluted-state/ongoing-state-mark follow-on, and `Phase J-AX`
grooved-state/ongoing-state-seal follow-on, and `Phase J-AY`
ridged-state/ongoing-state-stamp follow-on, and `Phase J-AZ`
terraced-state/ongoing-state-impression follow-on, and `Phase J-BA`
buttressed-state/ongoing-state-etching follow-on, and `Phase J-BB`
bastioned-state/ongoing-state-engraving follow-on, and `Phase J-BC`
fortified-state/ongoing-state-carving follow-on, and `Phase J-BD`
bulwarked-state/ongoing-state-inscription follow-on, and `Phase J-BE`
rampart-state/ongoing-state-marking follow-on, and `Phase J-BF`
citadel-state/ongoing-state-tracing follow-on, and `Phase J-BG`
keep-state/ongoing-state-notation follow-on, and `Phase J-BH`
stronghold-state/ongoing-state-annotation follow-on, and `Phase J-BI`
watchtower-state/ongoing-state-gloss follow-on, and `Phase J-BJ`
battlement-state/ongoing-state-caption follow-on, and `Phase J-BK`
parapet-state/ongoing-state-legend follow-on, and `Phase J-BL`
merlon-state/ongoing-state-callout follow-on, and `Phase J-BM`
crenel-state/ongoing-state-marginalia follow-on, and `Phase J-BN`
embrasure-state/ongoing-state-sidenote follow-on, and `Phase J-BO`
machicolation-state/ongoing-state-footnote follow-on, and `Phase J-BP`
bartizan-state/ongoing-state-endnote follow-on, and `Phase J-BQ`
turret-state/ongoing-state-addendum follow-on, and `Phase J-BR`
barbican-state/ongoing-state-appendix follow-on, and `Phase J-BS`
gatehouse-state/ongoing-state-codicil follow-on, and `Phase J-BT`
portcullis-state/ongoing-state-postscript follow-on, and `Phase J-BU`
drawbridge-state/ongoing-state-afterword follow-on, and `Phase J-BV`
moat-state/ongoing-state-epilogue follow-on, and `Phase J-BW`
causeway-state/ongoing-state-coda follow-on, and `Phase J-BX`
viaduct-state/ongoing-state-encore follow-on, and `Phase J-BY`
aqueduct-state/ongoing-state-finale follow-on, and `Phase J-BZ`
trestle-state/ongoing-state-curtain-call follow-on, and `Phase J-CA`
span-state/ongoing-state-bow follow-on, and `Phase J-CB`
arch-state/ongoing-state-ovation follow-on, and `Phase J-CC`
vault-state/ongoing-state-applause follow-on, and `Phase J-CD`
keystone-state/ongoing-state-acclamation follow-on, and `Phase J-CE`
abutment-state/ongoing-state-commendation follow-on, and `Phase J-CF`
pier-state/ongoing-state-tribute follow-on, and `Phase J-CG`
footing-state/ongoing-state-homage follow-on, and `Phase J-CH`
pilaster-state/ongoing-state-salute follow-on, and `Phase J-CI`
column-state/ongoing-state-accolade follow-on, and `Phase J-CJ`
capital-state/ongoing-state-plaudit follow-on, and `Phase J-CK`
frieze-state/ongoing-state-laurel follow-on, and `Phase J-CL`
cornice-state/ongoing-state-honor follow-on, and `Phase J-CM`
pediment-state/ongoing-state-distinction follow-on, and `Phase J-CN`
entablature-state/ongoing-state-recognition follow-on, and `Phase J-CO`
architrave-state/ongoing-state-appreciation follow-on, and `Phase J-CP`
metope-state/ongoing-state-admiration follow-on, and `Phase J-CQ`
triglyph-state/ongoing-state-esteem follow-on, and `Phase J-CR`
regula-state/ongoing-state-regard follow-on, and `Phase J-CS`
guttae-state/ongoing-state-respect follow-on, and `Phase J-CT`
mutule-state/ongoing-state-deference follow-on, and `Phase J-CU`
taenia-state/ongoing-state-reverence follow-on, and `Phase J-CV`
cymatium-state/ongoing-state-veneration follow-on, and `Phase J-CW`
sima-state/ongoing-state-devotion follow-on, and `Phase J-CX`
corona-state/ongoing-state-adoration follow-on, and `Phase J-CY`
soffit-state/ongoing-state-praise follow-on, and `Phase J-CZ`
fascia-state/ongoing-state-exaltation follow-on, and `Phase J-DA`
fillet-state/ongoing-state-glorification follow-on, and `Phase J-DB`
bead-state/ongoing-state-celebration follow-on, and `Phase J-DC`
ovolo-state/ongoing-state-jubilation follow-on, and `Phase J-DD`
cavetto-state/ongoing-state-rejoicing follow-on, and `Phase J-DE`
torus-state/ongoing-state-exultation follow-on, and `Phase J-DF`
scotia-state/ongoing-state-elation follow-on, and `Phase J-DG`
cyma-state/ongoing-state-delight follow-on, and `Phase J-DH`
astragal-state/ongoing-state-gladness follow-on, and `Phase J-DI`
trochilus-state/ongoing-state-cheer follow-on, and `Phase J-DJ`
annulet-state/ongoing-state-joy follow-on, and `Phase J-DK`
listel-state/ongoing-state-merriment follow-on, and `Phase J-DL`
cincture-state/ongoing-state-gaiety follow-on, and `Phase J-DM`
girdle-state/ongoing-state-revelry follow-on, and `Phase J-DN`
collarino-state/ongoing-state-festivity follow-on, and `Phase J-DO`
apophyge-state/ongoing-state-conviviality follow-on, and `Phase J-DP`
doucine-state/ongoing-state-sociability follow-on, and `Phase J-DQ`
cyma-recta-state/ongoing-state-fellowship follow-on, and `Phase J-DR`
cyma-reversa-state/ongoing-state-camaraderie follow-on, and `Phase J-DS`
echinus-state/ongoing-state-companionship follow-on, and `Phase J-DT`
abacus-state/ongoing-state-fraternity follow-on, and `Phase J-DU`
necking-state/ongoing-state-solidarity follow-on, and `Phase J-DV`
hypotrachelion-state/ongoing-state-alliance follow-on, and `Phase J-DW`
gorgerin-state/ongoing-state-accord follow-on, and `Phase J-DX`
bolster-state/ongoing-state-concord follow-on, and `Phase J-DY`
taper-state/ongoing-state-harmony follow-on, and `Phase J-DZ`
shaft-state/ongoing-state-unity follow-on, and `Phase J-EA`
base-state/ongoing-state-union follow-on, and `Phase J-EB`
plinth-state/ongoing-state-coalition follow-on, and `Phase J-EC`
pedestal-state/ongoing-state-partnership follow-on, and `Phase J-ED`
stylobate-state/ongoing-state-consortium follow-on, and `Phase J-EE`
stereobate-state/ongoing-state-federation follow-on, and `Phase J-EF`
podium-state/ongoing-state-confederation follow-on, and `Phase J-EG`
dais-state/ongoing-state-league follow-on, and `Phase J-EH`
rostrum-state/ongoing-state-assembly follow-on, and `Phase J-EI`
tribune-state/ongoing-state-forum follow-on, and `Phase J-EJ`
lectern-state/ongoing-state-council follow-on, and `Phase J-EK`
pulpit-state/ongoing-state-caucus follow-on, and `Phase J-EL`
ambo-state/ongoing-state-quorum follow-on, and `Phase J-EM`
minbar-state/ongoing-state-conclave follow-on, and `Phase J-EN`
cathedra-state/ongoing-state-synod follow-on, and `Phase J-EO`
bema-state/ongoing-state-convocation follow-on, and `Phase J-EP`
sedilia-state/ongoing-state-chapter follow-on, and `Phase J-EQ`
choir-state/ongoing-state-vestry follow-on, and `Phase J-ER`
stall-state/ongoing-state-consistory follow-on, and `Phase J-ES`
pew-state/ongoing-state-presbytery follow-on, and `Phase J-ET`
nave-state/ongoing-state-transept follow-on, and `Phase J-EU`
aisle-state/ongoing-state-chancel follow-on, and `Phase J-EV`
sanctuary-state/ongoing-state-apse follow-on, and `Phase J-EW`
altar-state/ongoing-state-reredos follow-on landed in current code:
retable-state/ongoing-state-iconostasis follow-on landed in current code:
ciborium-state/ongoing-state-baldachin follow-on landed in current code:
predella-state/ongoing-state-dossal follow-on landed in current code:
frontal-state/ongoing-state-antependium follow-on landed in current code:
superfrontal-state/ongoing-state-fair-linen follow-on landed in current code:
corporal-state/ongoing-state-pall follow-on landed in current code:
purificator-state/ongoing-state-chalice-veil follow-on landed in current code:
paten-state/ongoing-state-burse follow-on landed in current code:
pyx-state/ongoing-state-monstrance follow-on landed in current code:
cruet-state/ongoing-state-lavabo follow-on landed in current code:
thurible-state/ongoing-state-navicula follow-on landed in current code:
aspergillum-state/ongoing-state-aspersorium follow-on landed in current code:
stoup-state/ongoing-state-font follow-on landed in current code:
piscina-state/ongoing-state-credence follow-on landed in current code:
aumbry-state/ongoing-state-tabernacle follow-on landed in current code:
sacrarium-state/ongoing-state-conopeum follow-on landed in current code:
lunette-state/ongoing-state-humeral-veil follow-on landed in current code:
custodia-state/ongoing-state-pyx-cloth follow-on landed in current code:
ostensorium-state/ongoing-state-velum follow-on landed in current code:
lunula-state/ongoing-state-cope follow-on landed in current code:
amice-state/ongoing-state-stole follow-on landed in current code:
alb-state/ongoing-state-chasuble follow-on landed in current code:
dalmatic-state/ongoing-state-tunicle follow-on landed in current code:
maniple-state/ongoing-state-fanon follow-on landed in current code:
mitre-state/ongoing-state-crosier follow-on landed in current code:
pectoral-cross-state/ongoing-state-ring follow-on landed in current code:
zucchetto-state/ongoing-state-biretta follow-on landed in current code:
mozzetta-state/ongoing-state-rochet follow-on landed in current code:
surplice-state/ongoing-state-tippet follow-on landed in current code:
chimere-state/ongoing-state-scarf follow-on landed in current code:
cassock-state/ongoing-state-rabat follow-on landed in current code:
camauro-state/ongoing-state-saturno follow-on landed in current code:
ferraiolo-state/ongoing-state-mantelletta follow-on landed in current code:
cappa-magna-state/ongoing-state-pellegrina follow-on landed in current code:
galero-state/ongoing-state-simar follow-on landed in current code:
tabarro-state/ongoing-state-gremiale follow-on landed in current code:
falda-state/ongoing-state-mantum follow-on landed in current code:
sakkos-state/ongoing-state-omophorion follow-on landed in current code:
epigonation-state/ongoing-state-epimanikia follow-on landed in current code:
orarion-state/ongoing-state-epitrachelion follow-on landed in current code:
sticharion-state/ongoing-state-zonarion follow-on landed in current code:
phelonion-state/ongoing-state-riassa follow-on landed in current code:
klobuk-state/ongoing-state-mandyas follow-on landed in current code:
kamelavkion-state/ongoing-state-epanokamelavkion follow-on landed in current code:
koukoulion-state/ongoing-state-paramandyas follow-on landed in current code:
analavos-state/ongoing-state-polystavrion follow-on landed in current code:
epanorion-state/ongoing-state-epirrhiptarion follow-on landed in current code:
engolpion-state/ongoing-state-panagia follow-on landed in current code:
dikerion-state/ongoing-state-trikerion follow-on landed in current code:
ripidion-state/ongoing-state-asteriskos follow-on landed in current code:
diskos-state/ongoing-state-kalymma follow-on landed in current code:
antimension-state/ongoing-state-eiliton follow-on landed in current code:
aer-state/ongoing-state-labis follow-on landed in current code:
diskarion-state/ongoing-state-zeon follow-on landed in current code:
lonche-state/ongoing-state-lance follow-on landed in current code:
lavida-state/ongoing-state-sudarion follow-on landed in current code:
hexapterygon-state/ongoing-state-cherubikon follow-on landed in current code:

- replay integrity and validation benchmark foundations
- regression snapshots and cross-run benchmark deltas
- validation evidence exports and benchmark fixture packets
- validation run summaries and operator review packets
- validation triage queues and manual sign-off notes
- validation exception waivers and bounded handoff closures
- validation carry-forward ledgers and reviewer continuity digests
- validation disposition snapshots and bounded reopen notes
- validation deferred follow-up bundles and bounded revisit cues
- validation revisit completion receipts and bounded pending-state clearances
- validation dormant-state ledgers and bounded resurfacing cues
- validation return-readiness packets and bounded wake-state confirmations
- validation resumed-state checkpoints and bounded continuation attestations
- validation stable-state ledgers and bounded continuation-state digests
- validation settled-state packets and bounded ongoing-state confirmations
- validation persistent-state ledgers and bounded ongoing-state acknowledgements
- validation durable-state packets and bounded ongoing-state attestations
- validation enduring-state ledgers and bounded ongoing-state certifications
- validation sustained-state packets and bounded ongoing-state assurances
- validation anchored-state ledgers and bounded ongoing-state affirmations
- validation grounded-state packets and bounded ongoing-state endorsements
- validation rooted-state ledgers and bounded ongoing-state ratifications
- validation embedded-state packets and bounded ongoing-state reconciliations
- validation nested-state ledgers and bounded ongoing-state harmonizations
- validation layered-state packets and bounded ongoing-state alignments
- validation stacked-state ledgers and bounded ongoing-state convergences
- validation composite-state packets and bounded ongoing-state syntheses
- validation aggregated-state ledgers and bounded ongoing-state consolidations
- validation integrated-state packets and bounded ongoing-state unifications

Architecturally, this should be interpreted as:

- a correctness and replay-integrity layer around the training runtime
- a bounded benchmark-profile and scorecard surface
- a bounded regression-snapshot and cross-run delta surface
- a bounded evidence-export and fixture-packet surface
- a bounded run-summary and operator-review surface
- a bounded validation-triage and manual sign-off surface
- a bounded exception-waiver and handoff-closure surface
- a bounded carry-forward-ledger and reviewer-continuity-digest surface
- a bounded disposition-snapshot and reopen-note surface
- a bounded deferred-followup-bundle and revisit-cue surface
- a bounded revisit-completion-receipt and pending-state-clearance surface
- a bounded dormant-state-ledger and resurfacing-cue surface
- a bounded return-readiness-packet and wake-state-confirmation surface
- a bounded resumed-state-checkpoint and continuation-attestation surface
- a bounded stable-state-ledger and continuation-state-digest surface
- a bounded settled-state-packet and ongoing-state-confirmation surface
- a bounded persistent-state-ledger and ongoing-state-acknowledgement surface
- a bounded durable-state-packet and ongoing-state-attestation surface
- a bounded enduring-state-ledger and ongoing-state-certification surface
- a bounded sustained-state-packet and ongoing-state-assurance surface
- a bounded anchored-state-ledger and ongoing-state-affirmation surface
- a bounded grounded-state-packet and ongoing-state-endorsement surface
- a bounded rooted-state-ledger and ongoing-state-ratification surface
- a bounded embedded-state-packet and ongoing-state-reconciliation surface
- a bounded nested-state-ledger and ongoing-state-harmonization surface
- a bounded layered-state-packet and ongoing-state-alignment surface
- a bounded stacked-state-ledger and ongoing-state-convergence surface
- a bounded composite-state-packet and ongoing-state-synthesis surface
- a bounded aggregated-state-ledger and ongoing-state-consolidation surface
- a bounded integrated-state-packet and ongoing-state-unification surface
- a first-party evidence lane above existing replay analytics and puzzle-state
  validation primitives

It should not be interpreted as:

- a public leaderboard platform
- a cross-product telemetry system
- a release-gate automation authority

### 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`
- a live first-party `Phase 6R-M1` contract/ledger layer over current memory
  evidence surfaces
- a live first-party `Phase 6R-M2` chronicle/continuity layer over that landed
  ledger seam
- a live first-party `Phase 6R-M3` recall/shared-context layer over those
  landed seams
- a live first-party `Phase 6R-M4` cognitive-consolidation layer over those
  landed seams
- a live first-party `Phase 6R-M5` knowledge-promotion and note-posture layer
  over those landed seams
- a live first-party `Phase 6R-M6` derived-memory and optional-adjunct layer
  over those landed seams
- 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`
- the bounded first-party `Phase S1-A` registry/manifest seam is now the live
  product base for skill status, command binding, permission, and provenance
  declarations
- the bounded first-party `Phase S1-B` control seam is now the live product
  base for durable off-state behavior and family visibility grouping
- the bounded first-party `Phase S1-C` invocation/provenance/audit-ledger
  seam is now the live product base for traceable skill output, failure, and
  cancel recording
- the bounded first-party `Phase S1-D` authoring/examples/validation-harness
  seam is now the live product base for adding new skills without inventing
  fresh structure
- the bounded first-party `Phase S2-A` permissive analyzer wrapper seam is
  now the live product base before restrictive command-spec widening
- the bounded first-party `Phase S2-B` clean-room command-contract seam is now
  the live spec-only safety layer before restrictive skill-spec widening
- the bounded first-party `Phase S2-C` clean-room skill-spec seam is now the
  live spec-only product layer before any separately justified restrictive
  runtime implementation
- the bounded first-party `Phase S3-A` continuity and resume seam is now the
  live product base for `resume-session` and `search-history` over
  authoritative memory stores, while `capture-note` remains explicit and
  non-live under separate owner activation
- the bounded first-party `Phase S3-B` recall and compact-view seam is now the
  live product base for `recall-memory` and optional `generate-compact-view`
  output over the landed recall and derived adjunct memory seams, while compact
  views stay linked back to authoritative sources
- the bounded first-party `Phase S3-C` workflow-memory capture seam is now the
  live product base for `capture-session-template` and
  `capture-follow-up-routine` over authoritative procedural workflow ledger
  entities plus review/queue continuity evidence, while remaining separate from
  user-authored note capture and opaque summary collapse
- the bounded first-party `Phase S4-A` extraction seam is now the live product
  base for `extract-docs` and `extract-design-spec` over authoritative
  first-party docs/design source surfaces
- the bounded first-party `Phase S4-B` browser diagnostics seam is now the
  live product base for `capture-browser-trace` and `discover-browser-api`
  over authoritative first-party browser/service source surfaces, while
  remaining separate from generic browser-shell orchestration
- the bounded first-party `Phase S4-C` design shell seam is now the live
  product base for `translate-design-shell` and
  `translate-design-interaction` over authoritative first-party docs, design,
  browser, and packet source surfaces, while remaining separate from generic
  browser-shell orchestration
