# Migrating workflows to version 0.5

Version 0.5 is backward compatible. Existing 0.4 node ids, positional outputs,
widget order, manifests, and checkpoints remain supported. Migration is
recommended for clearer graphs and model-free validation, but it is not
required merely to open or resume an older workflow.

## What changes

Version 0.5 uses one **Chain Policy** connection for normal authoring. It keeps
the audio and transition records independent inside the Plan/checkpoint
contract, but removes the need to wire two policy nodes.

| 0.4 audio mode | Final audio | Source reference | Generated continuity |
|---|---|---|---|
| `generated_audio` | generated | off | on |
| `source_track` | source | on | off |
| `source_plus_timeline` | source | on | on |

| 0.4 continuation | 0.5 transition | Default context |
|---|---|---:|
| guide with zero context | Cut | 0 frames |
| `guide` | Guide | 22 frames |
| `masked_av` | Hard AV | 39 frames |
| `audio_feathered_av` | Soft AV | 39 frames |
| any other implementation/context pair | Legacy 0.4 Policy Adapter | preserved exactly |

The compact presets derive generated-audio overlap from the same boundary: 0,
22, or 39 frames. A custom audio overlap, Tone/Latent/Detail Guide, Detail AV,
Drift-Control AV, old dual-stream Feathered AV, and other raw pairs migrate to
the single **Legacy 0.4 Policy Adapter** node instead. Nothing is approximated.
The semantic choice always describes the boundary entering a scene.

## Automatic migration

Back up a custom workflow, then run:

```bash
python tools/migrate_v05_workflows.py /path/to/workflow.json
```

Pass several paths to migrate them together. Use `--check` to report files that
would change without writing them:

```bash
python tools/migrate_v05_workflows.py --check /path/to/workflow.json
```

With no paths, the tool checks or migrates the maintained active examples. It
is idempotent: running it again does not add duplicate policy, preflight, or
timeline nodes. Exact 0.4 settings become one Chain Policy when they fit the
normal presets; other implementation/context pairs become one exact Legacy 0.4
Policy Adapter.

## Source-media rewiring

The old source-track graph repeated one full decoded AUDIO value:

```text
Load Audio ─┬→ Loop Start
            ├→ Current Shot
            ├→ Tagged Audio Ref
            └→ Assemble
```

The 0.5 graph registers media once:

```text
Load Video ─┐
            ├→ Source Timeline ─┬→ Preflight / Plan Studio
Load Audio ─┘                   └→ Loop Start → Current Shot
                                                   └→ scene slice → Tagged Audio Ref

Loop End manifest → Assemble
```

Path-backed media remains lazy. Current Shot requests only its active window,
and manifests carry the descriptor to recovery and assembly. If the only audio
input is a tensor, Loop Start materializes one normalized run-owned copy.

Do not return a Tagged Audio fingerprint derived from Current Shot to Plan;
that would create a graph cycle. Keep static picture/reference fingerprints on
Plan. Structured scene dependencies record the exact source PCM window used by
generation automatically.

## Preflight and resume

Normal workflows insert Chain Preflight before Loop Start. Studio workflows use
the same backend through Plan Studio. It validates duration, source windows,
references, compatibility, and resume eligibility without loading H3.

Version 0.5 stores structured per-scene dependencies. A change to the next
scene, its incoming transition, or assembly-only media does not invalidate an
already accepted predecessor. Old checkpoints without structured records keep
their generic hash fallback.

## Compatibility guarantee

The migration tool does not renumber the sampling body or change its node
types. Loop Start's original optional socket order is preserved so
numerical 0.4 workflow slots still deserialize correctly. Legacy full-AUDIO
fan-out, direct media paths, Plan widgets, and archived examples remain
accepted throughout the 0.5 release.