# Sequencer Sub-Sequence Composition

This document records the `TODOS.phase-72.72.15.1.10` cinematic sequencer
sub-sequence composition contract. Parent sequences can nest reusable child
sequences, retime them on the parent timeline, inherit or override actor
bindings, and pass parameterized sub-sequences into child tracks or bindings.

## Runtime Ownership

- Runtime module: `V2Cinematics`
- Parameter spec: `FV2SequencerSubSequenceParameterSpec`
- Sub-sequence spec: `FV2SequencerSubSequenceSpec`
- Resolved instance spec: `FV2SequencerResolvedSubSequence`
- Composition evaluation: `FV2SequencerSubSequenceEvaluation`
- Issue enum: `EV2SequencerSubSequenceIssueType`
- Issue struct: `FV2SequencerSubSequenceIssue`
- Automation: `V2.Cinematics.Sequencer.SubSequenceComposition`
- CI checker: `V2/ue/Tools/check-v2-sequencer-sub-sequence-composition.py`

## Composition Model

`FV2SequencerSequenceSpec` now owns a `SubSequences` array. Each
`FV2SequencerSubSequenceSpec` stores an instance id, referenced child sequence
id, parent start frame, parent duration, source start frame, playback rate,
looping flag, binding-inheritance flag, binding overrides, and parameter
overrides.

`FV2SequencerSubSequenceParameterSpec` carries typed parameter values and
targets them at a binding id, track id, or both. This lets a reusable child
sequence keep stable authoring data while the parent composition passes values
such as `Param.Cassia.Intensity` or `Param.Camera.Mode`.

## Default Fixture

`BuildDefaultSequencerSubSequenceComposition` creates
`Seq.Composition.CouncilTrial` with two child instances of
`Seq.DataModel.CouncilIntro`:

- `SubSeq.CouncilIntro.OpeningBeat` runs from parent frame `0` through `120` at
  normal speed and passes `Param.Cassia.Intensity`.
- `SubSeq.CouncilIntro.ReplayInsert` runs from parent frame `120` through `210`
  from child source frame `30` at half-rate playback and passes
  `Param.Camera.Mode` as `CameraMode.ReplayCloseup`.

At parent frame `30`, the opening beat maps to child frame `30`. At parent frame
`150`, the replay insert maps to child frame `45`.

## Validation

`EvaluateSequencerSubSequenceComposition` validates missing or duplicate
instance ids, missing child sequence ids, unavailable child sequence references,
invalid frame ranges, invalid playback rates, missing or duplicate parameter
names, missing parameter targets, invalid parameter value types, and recursive
composition cycles. The result lists every resolved child instance and the
active instance ids for the evaluated parent frame.

## Verification

Run:

```bash
python3 V2/ue/Tools/check-v2-sequencer-sub-sequence-composition.py
```

Adjacent verification should include
`python3 V2/ue/Tools/check-v2-sequencer-actor-bindings.py`,
`python3 V2/ue/Tools/check-v2-sequencer-camera-tracks.py`,
`python3 V2/ue/Tools/check-v2-sequencer-event-tracks.py`,
`python3 V2/ue/Tools/check-v2-sequencer-audio-tracks.py`,
`python3 V2/ue/Tools/check-v2-sequencer-animation-clip-tracks.py`,
`python3 V2/ue/Tools/check-v2-sequencer-property-tracks.py`,
`python3 V2/ue/Tools/check-v2-sequencer-keyframe-interpolation.py`,
`python3 V2/ue/Tools/check-v2-sequencer-timeline-playback.py`,
`python3 V2/ue/Tools/check-v2-sequencer-data-model.py`, and
`python3 V2/ue/Tools/check-v2-cinematics-module.py`.