hypertwist/docs/ops/HYPERTWIST_REFACTORING_TOOLCHAIN_2026-06-22.md

HyperTwist Refactoring Toolchain

Created on 2026-06-22.

Purpose

This note gives HyperTwist its own bounded refactor/analyzer posture instead of leaving sentrux and GitNexus as cross-repo memory from ScriptoriumAI or VectorShell.

Current posture

• sentrux = permissive structural gate and source-health sensor
• GitNexus = analysis-only graph/impact tool
• neither tool is a shipped HyperTwist runtime dependency
• generated .gitnexus/ state and the disposable .gitnexus-source-only-root/ mirror are repo-local analysis outputs and must stay out of commits

Landed HyperTwist-owned entry points

• .sentrux/rules.toml
• scripts/run-hypertwist-sentrux-source-only.sh
• scripts/run-hypertwist-gitnexus-analyze.sh
• scripts/run-hypertwist-gitnexus-status.sh

Why these routes exist

HyperTwist spans three materially different code families:

• Unreal native/runtime code under UnrealHyperTwist/Source/
• embedded simulator-side browser runtime under Content/Browser/
• public/auth/distribution website code under website/

The toolchain needs to understand that structure without pretending the whole repo is one flat JavaScript app.

sentrux usage

The HyperTwist source-only wrapper intentionally mirrors only the high-signal source families into a temporary root before running sentrux check:

• UnrealHyperTwist/Source
• Content/Browser/src
• website/src
• website/server/src
• scripts

Run:

scripts/run-hypertwist-sentrux-source-only.sh

Resolution order for the analyzer binary is now HyperTwist-owned first:

• HYPERTWIST_SENTRUX_BINARY if explicitly provided
• repo-local ./sentrux or ./sentrux.exe if present
• sentrux on PATH
• the retained local fallback under /home/dev/src/VectorShell/sentrux

Current rules enforce:

• no cycles
• bounded function complexity and size
• browser client must not import website auth-server implementation
• embedded simulator browser runtime must not couple to website auth-server internals
• automation scripts must not import browser app internals

GitNexus usage

HyperTwist should use GitNexus as a deeper graph/impact surface before larger refactors, renames, or subsystem splits.

Run:

scripts/run-hypertwist-gitnexus-analyze.sh
scripts/run-hypertwist-gitnexus-status.sh

Behavior:

• mirrors only the high-signal HyperTwist source families into .gitnexus-source-only-root/ before analysis
• bootstraps that disposable mirror as a lightweight git repository so analyze and status can run against the same bounded root
• records a local disposable snapshot commit inside that mirror so GitNexus status output stays clean instead of reporting an empty HEAD
• deletes copied files above the default 256 KB ceiling so giant Unreal generated/runtime files do not destabilize the native worker path
• prefers the local retained working reference at mirrors/GitNexus/gitnexus/dist/cli/index.js
• if the retained local node/native payload is not runnable on the current host (for example a cross-platform LadybugDB binary mismatch), the wrapper falls back automatically to npx -y gitnexus@latest
• the wrapper suppresses the retained-CLI native-loader stderr spew and the benign empty-HEAD stderr noise that upstream status can emit on bounded disposable mirrors, while preserving the actual status result
• falls back to npx -y gitnexus@latest only if the local retained CLI is not available or is not runnable
• always uses --skip-agents-md so HyperTwist authority files are not rewritten just to refresh analysis state

Working-reference note

The retained HyperTwist mirrors/GitNexus working reference already contains the newer stack-overflow and cycle-hardening work recorded in its CHANGELOG.md, including:

• iterative stdio newline handling to prevent stack overflow on empty-line bursts
• broader cycle-safe traversal and depth-limited graph/type processing

That retained working reference is acceptable as an external analysis surface. It is not a signal to absorb GitNexus runtime code into the shipped product.

Recommended refactor loop

1. run scripts/run-hypertwist-gitnexus-analyze.sh
2. review impact/freshness through scripts/run-hypertwist-gitnexus-status.sh
3. run scripts/run-hypertwist-sentrux-source-only.sh for a structural baseline
4. make the bounded packet
5. rerun scripts/run-hypertwist-sentrux-source-only.sh
6. rerun product tests for the affected lane

Current findings snapshot

Validated on 2026-06-22:

• npm run verify:shell in Content/Browser/ passed
• npm run build in Content/Browser/ passed after installing local package dependencies for the validation pass
• scripts/run-hypertwist-gitnexus-analyze.sh completed successfully on the bounded source-only mirror
• scripts/run-hypertwist-gitnexus-status.sh reported the bounded mirror as up to date after the wrapper hardening pass

Most important structural result:

• the browser runtime mega-function debt was removed from the sentrux max function-length report after the runtime/shell.ts and browser-spatial-runtime-fallback.js ownership split
• the HyperTwistCoreTypes.h structural-validator debt was then removed from both the sentrux max complexity and max function-length reports by lifting the melinda-state, scramble-packet, and flat-projection checks into bounded inline helpers
• the training/catalog circular dependency was removed by moving classic sample content-pack ownership into UHyperTwistTrainingCatalogLibrary
• the virtual-3333 and melinda projection-family simulation cycles were removed by cutting game-mode shortcuts out of the pawn/controller lane
• the final classic-cube simulation cycle was removed by introducing the dedicated HyperTwistClassicCubeOperatorSurface interface so the HUD and player controller no longer reach directly back into AHyperTwistClassicCubeGameMode, while the orbit pawn now resolves its focus actor without a game-mode shortcut

Current highest-signal structural result:

• scripts/run-hypertwist-sentrux-source-only.sh now reports Quality: 5900
• max_cycles is now clear
• remaining sentrux debt is narrowed to:
  • two large HyperTwistSkillTypes.h IsStructurallyValid() functions
  • one large HyperTwistRecognitionTypes.h IsStructurallyValid() function

Current validation truth for the latest Unreal C++ slice:

• the primary reverse-SSH tunnel on localhost:22022 remained healthy
• the Windows-side safe reverse-sync script still updates C:\HyperTwist, but that path is currently only a partial mirror and is not sufficient as the authoritative Unreal build root
• the maintained validation root remained C:\HyperTwist_worktrees\phase10validate
• the touched classic-cube files were hash-matched into that worktree before the build rerun
• the first rerun truthfully failed at UHT because BlueprintPure is not allowed on interface functions
• after removing that invalid specifier from HyperTwistClassicCubeOperatorSurface.h, the same worktree rebuilt with: Result: Succeeded
• UnrealBuildTool total execution time for that successful rerun was 656.71 seconds on 2026-06-22
• the later widened same-day rerun against the maintained validation root C:\HyperTwist_worktrees\phase10validate also succeeded after the HyperTwistCoreTypes.h, HyperTwistRecognitionTypes.h, HyperTwistTrainingCatalogLibrary, and classic-cube operator-surface continuation packet, with Result: Succeeded, parallel executor time 6173.85 seconds, and total execution time 6198.45 seconds
• that later proof is the current authoritative Windows confirmation that the retained HyperTwistRecognitionTypes.h helperization and classic-cube operator-surface decoupling are compile-safe on the real Unreal lane

Remaining highest-signal debt after the latest pass:

• large Unreal inline IsStructurallyValid() ownership in: HyperTwistSkillTypes.h and HyperTwistRecognitionTypes.h

Follow-up tool refresh on 2026-06-22:

• scripts/run-hypertwist-gitnexus-analyze.sh re-indexed the bounded source-only mirror successfully at 16,020 nodes, 37,409 edges, 646 clusters, and 300 flows
• scripts/run-hypertwist-gitnexus-status.sh then reported the bounded mirror Status: up-to-date
• scripts/run-hypertwist-sentrux-source-only.sh remained at Quality: 5900 after the public-website/manual widening, so the remaining structural debt is still isolated to the same Unreal validator seams rather than the browser or website lane

Important nuance from the 2026-06-22 follow-up:

• a helper-only readability pass on HyperTwistSkillTypes.h was tested and intentionally not retained, because it made sentrux function grouping worse instead of better
• the truthful next repair for that file is a larger out-of-struct validator migration packet rather than another small helper-only extraction pass
• direct inspection of the remaining HyperTwistSkillTypes.h functions also suggests the current sentrux report is now being amplified by repeated inline same-name IsStructurallyValid() methods living in one header rather than by one obviously giant monolithic function body, which reinforces the need for an out-of-line or out-of-struct migration packet instead of more local boolean/helper reshuffling
• the adjacent likely follow-up, if we continue this lane later, is deeper family extraction or multi-header ownership separation for the remaining validator clusters rather than more in-place header-local helperization

Out of scope

This note does not:

• make GitNexus a product runtime dependency
• claim sentrux replaces product validation
• widen HyperTwist into a generic code-intelligence product