From 4cc10edf4d264e4a3872568485d69e251072b849 Mon Sep 17 00:00:00 2001 From: axiomlogicnexus Date: Tue, 5 May 2026 20:20:54 +0200 Subject: [PATCH] Add clean-room packet for generated-mode executor --- docs/MODEL_B_SOURCE_ACCESS_BOUNDARY.md | 2 + ...NERATED_MODE_EXECUTOR_PACKET_2026-05-05.md | 184 ++++++++++++++++++ 2 files changed, 186 insertions(+) create mode 100644 docs/arch/HYPERTWIST_IMPORTED_GENERATED_MODE_EXECUTOR_PACKET_2026-05-05.md diff --git a/docs/MODEL_B_SOURCE_ACCESS_BOUNDARY.md b/docs/MODEL_B_SOURCE_ACCESS_BOUNDARY.md index f2b9c0a..7f589cd 100644 --- a/docs/MODEL_B_SOURCE_ACCESS_BOUNDARY.md +++ b/docs/MODEL_B_SOURCE_ACCESS_BOUNDARY.md @@ -15,6 +15,7 @@ Purpose: - curated first-party docs in: - `C:\HyperTwist\docs\MODEL_B_SOURCE_ACCESS_BOUNDARY.md` - `C:\HyperTwist\docs\REPO_LICENSE_TRACKING.md` + - `C:\HyperTwist\docs\arch\HYPERTWIST_IMPORTED_GENERATED_MODE_EXECUTOR_PACKET_2026-05-05.md` - `C:\HyperTwist\docs\v6_5_deep_manual_pack\README.md` - `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\AGENTS.md` - `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\API.md` @@ -62,6 +63,7 @@ Purpose: - benchmark oracles remain source-forbidden to `Model B` - this rule still applies when the upstream repo says `all rights reserved`, has no explicit license, or contains contradictory license notices; those repos may still inform `Model A`, but never become direct `Model B` source input - if a repo mixes permissive and restricted trees, default to forbidding the whole mirrored repo to `Model B` unless a narrower allowlist has been explicitly created in writing +- for the imported generated-mode executor packet, `Model B` should implement from owned `HyperTwistTraining` runtime/request contracts rather than from donor-facing raw extract files or bundled intake JSON unless those assets were separately scrubbed and allowlisted ## Current topology default diff --git a/docs/arch/HYPERTWIST_IMPORTED_GENERATED_MODE_EXECUTOR_PACKET_2026-05-05.md b/docs/arch/HYPERTWIST_IMPORTED_GENERATED_MODE_EXECUTOR_PACKET_2026-05-05.md new file mode 100644 index 0000000..61b20c8 --- /dev/null +++ b/docs/arch/HYPERTWIST_IMPORTED_GENERATED_MODE_EXECUTOR_PACKET_2026-05-05.md @@ -0,0 +1,184 @@ +# HyperTwist imported generated-mode executor packet + +Created on `2026-05-05` + +Status: + +- safe for clean-room `Model B` +- derived from first-party HyperTwist code and first-party governance docs + +## Purpose + +This packet defines the remaining bounded product task for the imported generated-mode lane without requiring a clean implementation instance to read restrictive mirrors, restrictive dossiers, or donor-derived extract notes. + +The open task is: + +- consume the owned imported generated-mode launch request +- produce owned generated training case state that the existing HyperTwist runtime can execute + +It is not: + +- a broad training-backend redesign +- a generic cube engine project +- a catalog-materialization rewrite +- a donor-structure port + +## Scope + +Bounded lane: + +- imported `roux-and-blockbuilding-systems` generated-mode continuation + +Required result: + +- a first-party executor path inside `HyperTwistTraining` that turns a structurally valid generated-mode launch request into a structurally valid owned training deck or case set that can be started through the existing training runtime + +Out of scope: + +- changing finite imported deck materialization +- changing selector-catalog runtime behavior +- changing dashboard request inspection behavior +- broad repository refactors +- generic move-engine or solver work + +## Current owned product truth + +These pieces are already live in first-party code: + +- generated-mode deck materialization into a synthetic launch deck with imported runtime surface metadata +- active imported runtime selection state on runs +- generated-mode selector-choice capture on active runs +- derived generated-mode launch config construction +- owned generated-mode launch request creation and persistence +- latest persisted launch-request query surfaces +- dashboard-facing inspection of the latest persisted launch request + +What is still missing: + +- the executor that consumes the owned request and produces playable/generated owned training content + +## Current owned contracts + +Primary structs: + +- `FHyperTwistTrainingImportedRuntimeSelectionState` +- `FHyperTwistTrainingImportedGeneratedModeLaunchConfig` +- `FHyperTwistTrainingImportedGeneratedModeLaunchRequest` +- `FHyperTwistTrainingDeck` +- `FHyperTwistTrainingCase` +- `FHyperTwistTrainingRunState` + +Primary product entry points: + +- `UHyperTwistTrainingCatalogLibrary::TryBuildImportedGeneratedModeLaunchConfig(...)` +- `UHyperTwistTrainingSubsystem::TryGetActiveImportedGeneratedModeLaunchConfig(...)` +- `UHyperTwistTrainingSubsystem::CreateActiveImportedGeneratedModeLaunchRequest(...)` +- `UHyperTwistTrainingSubsystem::ApplyActiveImportedGeneratedModeSelectorChoice(...)` +- `UHyperTwistTrainingSubsystem::StartTrainingRunFromDeck(...)` +- `UHyperTwistTrainingRepositoryLibrary::TryGetLatestGeneratedModeLaunchRequestForDeck(...)` + +Important product behavior already established: + +- launch-config construction fails until every selector on the generated-mode runtime surface has a stored valid choice +- launch requests are already persisted into run records +- summaries and replay payloads already carry imported runtime selection state + +## Clean-room boundary for this packet + +`Model B` should implement against owned HyperTwist contracts and owned first-party code only. + +`Model B` does not need to inspect: + +- restrictive mirrors +- restrictive dossiers +- donor-backed oracle notes +- product-side raw extract files under `Content/HyperTwistTraining/MaterializedCatalog/raw-extracts` +- product-side bundled import specs or materialization JSON unless those assets are separately scrubbed and allowlisted + +The executor should rely on the owned runtime/request surfaces that already exist in `HyperTwistTraining`, not on donor-facing intake artifacts. + +## Practical implementation target + +The executor should do the following in owned product terms: + +1. validate that the active run and generated-mode launch request are structurally valid +2. validate that the active deck is a generated-mode imported deck and that the stored selection state matches the active runtime surface +3. build one or more owned `FHyperTwistTrainingCase` values from the owned request +4. materialize an owned executable deck from those cases +5. start or restart the run through the existing owned runtime path so repository, summary, and dashboard behavior stay coherent + +## Preferred integration shape + +Preferred shape for the first bounded slice: + +- keep the executor inside `HyperTwistTraining` +- expose it through `UHyperTwistTrainingSubsystem` +- mirror it through `UHyperTwistTrainingRuntimeLibrary` only if Blueprint/runtime callers need it immediately +- use a one-case scripted deck first unless the owned implementation clearly requires multiple generated cases +- reuse `StartTrainingRunFromDeck(...)` or an equivalent owned run-start path instead of bypassing existing run initialization, summary refresh, and repository recording flow + +Why this is the preferred shape: + +- HyperTwist already uses the same restart pattern for selector-catalog option application +- it preserves the existing repository and coach/dashboard wiring +- it avoids inventing a parallel execution path during an otherwise bounded product slice + +## Suggested file ownership for the clean implementation instance + +Most likely edit surfaces: + +- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingSubsystem.h` +- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSubsystem.cpp` +- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingRuntimeLibrary.h` +- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingRuntimeLibrary.cpp` +- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingTypes.h` only if a small owned executor result contract is actually needed + +Possible but not automatically required: + +- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingLibrary.cpp` +- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingCatalogLibrary.cpp` + +Avoid unless the slice truly needs it: + +- coach-memory logic +- repository integrity normalization logic +- dashboard rendering surfaces + +## Acceptance criteria + +Minimum acceptance criteria for the bounded slice: + +- invalid or incomplete generated-mode requests fail cleanly without mutating unrelated run state +- a valid generated-mode request produces structurally valid owned training content +- the resulting active run remains structurally valid +- imported runtime selection state remains available after execution +- the generated-mode launch request remains queryable as the latest request for the deck +- finite imported decks still behave exactly as before +- selector-catalog option application still behaves exactly as before +- no restrictive or donor-derived implementation material is introduced + +## Validation checklist + +The clean implementation instance should validate at least these points: + +1. build the project successfully after the executor slice +2. confirm a generated-mode deck still reaches a valid launch request only after all selectors are filled +3. execute the new executor path on a valid active generated-mode run +4. confirm the returned active run has a structurally valid deck and at least one structurally valid case +5. confirm the imported runtime selection state and latest launch request are still queryable +6. confirm selector-catalog decks and finite imported decks still start normally + +## Short implementer brief + +Treat this as a bounded product integration task, not as a research task. + +The hard boundary is provenance, not product complexity. + +The product-side problem is straightforward: + +- HyperTwist already has request capture +- HyperTwist already has persistence +- HyperTwist already has runtime start plumbing +- the missing piece is the original first-party translation from request to owned generated case content + +That is the packet.