# HyperTwist Phase 4R Packet 4R-A cubing.js Adapter Implementation

Created on `2026-05-13`

## Status

`Phase 4R / Packet 4R-A` is now `closed`.

This packet converts the retained boundary-sensitive `cubing/cubing.js` row from a queued `MPL`-aware adapter candidate into a landed first-party HyperTwist classic-cubing semantic and runtime adapter lane.

It does not reopen `Phase 0R`, `Phase 1R`, `Phase 2R`, or the permissive `Phase 3R` packets.

Those earlier packets still own:

- source-value extraction
- retained-set routing
- ownership and acceptance boundaries
- landed permissive widening decisions

This packet owns the next question instead:

- what first-party classic-cubing implementation actually landed
- how the `MPL`-aware boundary was preserved
- which retained cubing.js value is now live
- what remains explicitly out of scope for this lane
- what validation was completed
- what the next bounded implementation move is after this landing

## Authority order

For future work on the classic-cubing boundary-sensitive lane, read in this order:

1. this packet for first-party landing scope, `MPL` boundary result, and validation result
2. [HYPERTWIST_LIVE_LANES_SOURCE_AND_PRESERVATION_AUDIT_2026-05-13.md](C:/HyperTwist/docs/HYPERTWIST_LIVE_LANES_SOURCE_AND_PRESERVATION_AUDIT_2026-05-13.md:1) for live-lane preserve posture
3. [HYPERTWIST_PHASE_1R_RETAINED_SET_CONTRACT_AND_HANDOFF_2026-05-13.md](C:/HyperTwist/docs/HYPERTWIST_PHASE_1R_RETAINED_SET_CONTRACT_AND_HANDOFF_2026-05-13.md:1) for retained-set routing
4. [HYPERTWIST_PHASE_0R_PACKET_0R_C_EVALUATION_2026-05-12.md](C:/HyperTwist/docs/HYPERTWIST_PHASE_0R_PACKET_0R_C_EVALUATION_2026-05-12.md:1) for source-value extraction and non-promotion rationale
5. [HYPERTWIST_MODEL_A_MAX_VALUE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md](C:/HyperTwist/docs/HYPERTWIST_MODEL_A_MAX_VALUE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md:1) for the canonical interpretation rule that keeps future `Model A` boundary-sensitive extraction rich rather than shallow
6. [REPO_LICENSE_TRACKING.md](C:/HyperTwist/docs/REPO_LICENSE_TRACKING.md:1) for license, notice, and provenance obligations

## Packet licensing snapshot

Owner row widened by this packet:

- `cubing/cubing.js`: `MPL-2.0 OR GPL-3.0-or-later`

Checked local notice surfaces:

- [package.json](C:/Workspaces/HyperTwist/mirrors/permissive/cubing/cubing.js/package.json:1)
- [README.md](C:/Workspaces/HyperTwist/mirrors/permissive/cubing/cubing.js/README.md:1)
- [LICENSE-MPL.md](C:/Workspaces/HyperTwist/mirrors/permissive/cubing/cubing.js/LICENSE-MPL.md:1)
- [LICENSE-GPL.md](C:/Workspaces/HyperTwist/mirrors/permissive/cubing/cubing.js/LICENSE-GPL.md:1)

Boundary result:

- no upstream `cubing.js` source files were modified in this packet
- no donor app shell, docs shell, or Twizzle shell was landed
- the landed surface remains a first-party compiled contract and reference bundle that records an `MPL`-aware dependency or adapter posture

## Packet result

`4R-A` lands the classic-cubing row as:

- `cubing/cubing.js` -> `implemented_live_boundary_sensitive`

Current portfolio effect:

- curated HyperTwist shallow-eval set: `71`
- currently verified live in checked Unreal surfaces: `15`
- live permissive lanes: `13`
- live boundary-sensitive adapter lanes: `1`
- live restrictive clean-room lanes: `1`
- active non-live implementation-board rows: `44`

## Donor source surfaces read

The source read for this widening remained bounded to semantic state, geometry, viewer, device, search, bridge, and compliance seams:

- [package.json](C:/Workspaces/HyperTwist/mirrors/permissive/cubing/cubing.js/package.json:1)
- [README.md](C:/Workspaces/HyperTwist/mirrors/permissive/cubing/cubing.js/README.md:1)
- [src/cubing/kpuzzle/index.ts](C:/Workspaces/HyperTwist/mirrors/permissive/cubing/cubing.js/src/cubing/kpuzzle/index.ts:1)
- [src/cubing/puzzle-geometry/index.ts](C:/Workspaces/HyperTwist/mirrors/permissive/cubing/cubing.js/src/cubing/puzzle-geometry/index.ts:1)
- [src/cubing/twisty/index.ts](C:/Workspaces/HyperTwist/mirrors/permissive/cubing/cubing.js/src/cubing/twisty/index.ts:1)
- [src/cubing/protocol/index.ts](C:/Workspaces/HyperTwist/mirrors/permissive/cubing/cubing.js/src/cubing/protocol/index.ts:1)
- [src/cubing/bluetooth/index.ts](C:/Workspaces/HyperTwist/mirrors/permissive/cubing/cubing.js/src/cubing/bluetooth/index.ts:1)
- [src/cubing/search/index.ts](C:/Workspaces/HyperTwist/mirrors/permissive/cubing/cubing.js/src/cubing/search/index.ts:1)
- [src/cubing/puzzles/index.ts](C:/Workspaces/HyperTwist/mirrors/permissive/cubing/cubing.js/src/cubing/puzzles/index.ts:1)
- [src/cubing/puzzles/implementations/melindas2x2x2x2/index.ts](C:/Workspaces/HyperTwist/mirrors/permissive/cubing/cubing.js/src/cubing/puzzles/implementations/melindas2x2x2x2/index.ts:1)

## First-party landing surfaces

The landed first-party Unreal surfaces are:

- [HyperTwistTrainingClassicCubingLibrary.h](C:/HyperTwist/UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingClassicCubingLibrary.h:1)
- [HyperTwistTrainingClassicCubingLibrary.cpp](C:/HyperTwist/UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingClassicCubingLibrary.cpp:1)
- [HyperTwistTrainingRuntimeLibrary.h](C:/HyperTwist/UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingRuntimeLibrary.h:1)
- [HyperTwistTrainingRuntimeLibrary.cpp](C:/HyperTwist/UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingRuntimeLibrary.cpp:1)
- [hypertwist-reference-incorporation-targets.json](C:/HyperTwist/UnrealHyperTwist/Content/HyperTwistTraining/MaterializedCatalog/hypertwist-reference-incorporation-targets.json:1)
- [hypertwist-catalog-materialization-summary.json](C:/HyperTwist/UnrealHyperTwist/Content/HyperTwistTraining/MaterializedCatalog/hypertwist-catalog-materialization-summary.json:1)
- [cubing-cubing-js-reference-pages.jsonl](C:/HyperTwist/UnrealHyperTwist/Content/HyperTwistTraining/MaterializedCatalog/raw-extracts/cubing-cubing-js-reference-pages.jsonl:1)

## Landed implementation scope

What landed:

- a first-party compiled classic-cubing package ledger that records the bounded `MPL`-aware roles for `kpuzzle`, `notation`, `puzzle-geometry`, `twisty`, `puzzles`, `protocol`, `bluetooth`, `search`, and `scramble`
- a first-party semantic contract for classic-cubing state, transformations, notation, and protocol interop
- a first-party geometry contract for named-puzzle resolution, description parsing, notation mapping, and geometry-backed construction
- a first-party viewer adapter contract for embedded `TwistyPlayer`, algorithm viewer/editor, and bounded player lifecycle seams
- a first-party device adapter boundary for smart puzzle, smart timer, smart robot, keyboard puzzle, and binary protocol translation seams
- a first-party search and scramble contract for random-state helpers, solve-helper entry points, and scramble-routing seams
- a first-party `MPL` compliance boundary that records allowed use, notice retention, and publication duties if upstream-covered files are ever modified directly later
- first-party runtime-library accessors and TSV checklist export for the new classic-cubing bundle
- bundled first-party reference targets and raw source-reference capture for semantics, geometry, viewer adapters, device adapters, search, the Melinda bridge, and the `MPL` boundary

What that means in practice:

- `cubing/cubing.js` now owns the landed boundary-sensitive classic-cubing semantic and runtime adapter preserve lane in HyperTwist
- the landed surface is a first-party Unreal contract and runtime API, not a vague future donor note
- the practical path remains `MPL`-aware dependency or adapter consumption rather than an invisible private fork of upstream files
- the retained solver benchmarks, `Hyperspeedcube` runtime anchor, `magiccube4d` attributed lane, and restrictive clean-room lanes remain distinct and are not flattened into this packet

## Preserved landed value

The donor value that was actually promoted is:

- explicit classic-cubing state, orbit-definition, pattern, and transformation boundaries
- explicit classic notation, binary interchange, and Twizzle or Reid protocol translation seams
- explicit named-puzzle, description-string, and geometry-backed construction boundaries
- explicit embedded viewer, player, editor, and indexer adapter surfaces beneath first-party shells
- explicit smart-device and protocol adapter seams beneath first-party timer, replay, and recognition flows
- explicit search, random-state, and scramble-routing seams while keeping retained solver benchmarks separate
- explicit `MPL` compliance boundary language so later widening does not silently slide into an untracked fork posture

## Excluded or non-promotion boundary

Do not promote this packet into:

- a private fork of upstream `cubing.js` source files
- a replacement for the `Hyperspeedcube` hyper runtime anchor
- a replacement for the restrictive `twisty.js` clean-room lane
- a claim that retained solver benchmarks are no longer needed
- donor docs, demo shells, or Twizzle shell ownership

Rationale:

- this packet was retained and widened because `cubing.js` is the strongest classic-cubing semantic/runtime donor in the set
- its highest value is bounded state, geometry, player, interop, and device seams
- the right legal path is an explicit `MPL`-aware adapter posture, not pretending it is just another ordinary permissive row

## Acceptance markers satisfied

The `0R-C` and `Phase 1R` retained-value markers for this lane are now satisfied in first-party Unreal surfaces:

- a first-party classic-cubing semantic contract exists for `KPuzzle`, `KPattern`, `KTransformation`, notation, and protocol interop seams
- a first-party geometry contract exists for named-puzzle resolution, description parsing, `PGNotation`, and geometry-backed construction
- a first-party viewer adapter contract exists for embedded player, editor, and indexer behavior
- a first-party smart-device boundary exists for puzzle, timer, robot, keyboard, and protocol adapter seams
- a first-party search contract exists for solve-helper, random-state, and scramble-routing behavior
- a first-party `MPL` compliance boundary exists for notice retention and future source-file modification duties

## Validation

Validation completed for this packet:

- `git diff --check` passed apart from CRLF conversion warnings
- JSON validation passed for the updated materialized-catalog files and workspace manifest
- Unreal build succeeded with:
  - `C:\Program Files\Epic Games\UE_5.7\Engine\Build\BatchFiles\Build.bat UnrealHyperTwistEditor Win64 Development C:\HyperTwist\UnrealHyperTwist\UnrealHyperTwist.uproject -WaitMutex -NoHotReloadFromIDE`

Build result:

- `Succeeded` on `2026-05-13`

## Next move

The next bounded move is `Phase 4R-B`:

- widen `cutelyaware/magiccube4d` as the retained attributed legacy `4D` interaction, history, and macro lane beneath the `Hyperspeedcube` anchor
- keep the optional `Phase 3R-G` `pissang/claygl` and `pissang/clay-viewer` comparison lane deferred unless the landed primary browser spatial stack exposes a real gap
