# Sequencer Serialization

This document records the `TODOS.phase-72.72.15.1.12` cinematic sequencer
save/load serialization contract. Sequence serialization captures deterministic
payload metadata, embedded sequence data, schema versioning, storage path, and a
checksum so snapshots can be validated before loading.

## Runtime Ownership

- Runtime module: `V2Cinematics`
- Snapshot spec: `FV2SequencerSequenceSnapshotSpec`
- Serialization result: `FV2SequencerSerializationResult`
- Issue enum: `EV2SequencerSerializationIssueType`
- Issue struct: `FV2SequencerSerializationIssue`
- Automation: `V2.Cinematics.Sequencer.Serialization`
- CI checker: `V2/ue/Tools/check-v2-sequencer-serialization.py`

## Snapshot Model

`FV2SequencerSequenceSnapshotSpec` stores a snapshot id, sequence id, schema
version, storage path, deterministic payload, payload checksum, compression
flag, deterministic flag, and the embedded `FV2SequencerSequenceSpec`. The
embedded sequence data gives load a full in-memory restore target while the
payload/checksum fields provide deterministic save/load validation.

`BuildDefaultSequencerSerializedPayload` emits a compact deterministic payload
for identity, timing, binding count, track count, sub-sequence count, and
keyframe count. `FV2SequencerSequenceSnapshotSpec::ComputeChecksum` calculates a
stable checksum for that payload.

## Save/Load Flow

`SaveSequencerSequenceSnapshot` creates a `Snapshot.<SequenceId>.Schema1`
snapshot, writes schema version `1`, records the requested storage path, embeds
the source sequence data, and validates the result.

`LoadSequencerSequenceSnapshot` validates snapshot id, sequence id, storage
path, schema version, serialized payload, payload checksum, and embedded
sequence id before copying the embedded sequence into the output sequence.

The default fixture round-trips `Seq.DataModel.CouncilIntro` at
`/Game/Cinematics/Sequences/CouncilIntro.v2seq` with three bindings, three
tracks, and four keyframes. The composition fixture preserves two nested
sub-sequences.

## Validation

Serialization reports blocking issues for missing snapshot ids, missing sequence
ids, missing storage paths, missing serialized payloads, unsupported schema
versions, invalid checksums, and payload sequence mismatches.

## Verification

Run:

```bash
python3 V2/ue/Tools/check-v2-sequencer-serialization.py
```

Adjacent verification should include
`python3 V2/ue/Tools/check-v2-sequencer-gameplay-blend.py`,
`python3 V2/ue/Tools/check-v2-sequencer-sub-sequence-composition.py`,
`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`.