# V2 Horizontal Music Re-Sequencing

Phase 72.22.1.2 adds horizontal re-sequencing for Maya adaptive music. It
chooses authored music sections such as verse, chorus, and bridge from the
current adaptive music state and normalized intensity.

## Source Of Truth

- Contract:
  [HorizontalMusicResequencing_V2_Contract.json](../../ue/Content/V2/Audio/HorizontalMusicResequencing_V2_Contract.json)
- Runtime module: `V2Audio`
- Core types: `EV2HorizontalMusicSectionRole`, `FV2HorizontalMusicSection`,
  `FV2HorizontalMusicResequenceRule`, `FV2HorizontalMusicResequenceRequest`,
  `FV2ResolvedHorizontalMusicSection`, and
  `FV2HorizontalMusicResequencingArrangement`
- Builder:
  `UV2AudioBlueprintLibrary::BuildDefaultHorizontalMusicResequencingArrangement`
- Validator:
  `UV2AudioBlueprintLibrary::ValidateHorizontalMusicResequencingArrangement`
- Resolver: `UV2AudioBlueprintLibrary::ResolveHorizontalMusicSection`
- Registrar: `UV2AudioSubsystem::RegisterHorizontalMusicResequencingArrangement`
- Subsystem route: `UV2AudioSubsystem::EvaluateHorizontalMusicSection`
- State input:
  [adaptive-music-state-machine.md](adaptive-music-state-machine.md)

## Section Roles

The default arrangement contains verse, chorus, and bridge sections for
`Exploration`, `Tension`, and `Combat`. Menu, victory, and defeat have intro or
outro support so interrupt and result states still resolve to authored sections.

| State       | Low intensity | Mid intensity | High intensity |
| ----------- | ------------- | ------------- | -------------- |
| Exploration | Verse         | Chorus        | Bridge         |
| Tension     | Verse         | Chorus        | Bridge         |
| Combat      | Verse         | Chorus        | Bridge         |
| Menu        | Intro         | Intro         | Intro          |
| Victory     | Outro         | Outro         | Outro          |
| Defeat      | Outro         | Outro         | Outro          |

## Re-Sequencing Rules

Validated rules cover the requested verse-to-chorus-to-bridge flow:

- `ExplorationVerseToChorus`
- `ExplorationChorusToBridge`
- `TensionVerseToChorus`
- `TensionChorusToBridge`
- `CombatVerseToChorus`
- `CombatChorusToBridge`

Rules are intensity-gated and state-gated. Beat, bar, and phrase quantization
are intentionally left to the later beat-synchronized transition task; this task
only selects the next authored section.

## Runtime Evidence

`UV2AudioConfigAsset` owns the default
`FV2HorizontalMusicResequencingArrangement`. `UV2AudioSubsystem` registers it,
evaluates section changes, tracks `CurrentHorizontalMusicSectionId`, and exposes
section count, rule count, verse/chorus/bridge coverage, state coverage, and
registration status through `FV2AudioRuntimeSnapshot`.

## Validation Commands

```bash
python3 V2/ue/Tools/check-v2-horizontal-music-resequencing.py
python3 V2/ue/Tools/check-v2-adaptive-music-state-machine.py
python3 V2/ue/Tools/check-v2-audio-module.py
python3 -m json.tool V2/ue/Content/V2/Audio/HorizontalMusicResequencing_V2_Contract.json
python3 V2/tools/validate-v2-docs.py
```