# V1 migration guide

Phase 182, `182.C.39.08`. For callers of the existing avatar, voice and
image-to-video flows — and for Veritas callers, whose surface is deferred.

## The one-sentence version

**Migrating is not a rename, because the new flow makes promises the old one
never made, and those promises need inputs the old request does not carry.**

## What the old flows actually guarantee

| Flow                         | Exact dialogue | Measured sync | Identity bound to an authorization |
| ---------------------------- | -------------- | ------------- | ---------------------------------- |
| `text-to-video`              | no             | no            | no                                 |
| `image-to-video`             | no             | no            | no                                 |
| `human-video-exact-dialogue` | **yes**        | **yes**       | **yes**                            |

The legacy flows are not broken and they are not being switched off. They have
never had an exact-dialogue guarantee; what changed is that we now know what
that guarantee would require, so continuing to ship them **silently** would be a
different thing than shipping them before we knew
(`human-video-legacy-flows.ts`).

Two consequences you will see in reporting before you see them anywhere else:

- **A flow that does not measure speech is not a flow that failed the gate.**
  Those are opposite findings and one word covers both. Legacy jobs report
  `not-applicable`, and that word appears nowhere near `passed` — reporting them
  as failures fills a dashboard with red nobody can act on; reporting them as
  passes claims a measurement nobody made.
- **A legacy job that routes through a lane with a lip-sync model does not
  acquire the guarantee.** It produces a mouth that matches _something_, nobody
  measured what, and a customer reasonably concludes the words are theirs.
  Reporting a sync or speech verdict on a flow that never had one is refused.

## What you must supply to move

| Moving from      | You must add                                                                                         |
| ---------------- | ---------------------------------------------------------------------------------------------------- |
| `text-to-video`  | an approved script; an authorization for the person depicted                                         |
| `image-to-video` | an approved script; an authorization for the person in the image; the reference role the image plays |

**There is no one-click upgrade**, and the reason is not ergonomic: a system
that offers one produces jobs whose authorization was invented at the moment of
the click. "Upgrade this job" is a different request with inputs the caller has
to supply.

## You cannot migrate consent

This is the part that surprises integrators, so it is the part to plan around.

`referenceImage: 'https://cdn/seed.png'` says nothing about **role**, nothing
about **whose face it is**, and nothing about **whether anybody agreed**. The
new contract makes an identity reference without an authorization a parse error,
on purpose. So a stored reference has exactly two honest destinations
(`human-video-reference-migration.ts`):

1. **`first-frame`** — which requires no authorization and is a faithful
   translation of what the old image-to-video path did with the string: seed the
   first rendered frame.
2. **Refuse**, and ask the owner what the image is.

**Never `identity`.** Upgrading the field into an identity reference means
synthesising an authorization nobody gave — the exact thing this phase exists to
prevent, arrived at through a data migration instead of a decision.

So the migration plan for a library of existing references is a **people plan**,
not a data plan: every subject whose likeness you intend to keep using has to
enrol, and enrolment binds an authorization to the digests of specific files.
Budget for that first; it is the long pole and no amount of engineering shortens
it.

## Order of work

1. Inventory stored `referenceImage` values; map the ones you know to be
   non-identity to `first-frame`, and set the rest aside.
2. Re-enrol subjects for the set aside, with proof (`182.C.26.02`), which
   produces authorizations bound to file digests.
3. Lock scripts for the calls that need exact words; anything that does not can
   stay on a legacy flow indefinitely.
4. Approve the audio those scripts will be measured against.
5. Move call sites, and expect new refusals — `hv.consent.missing` (403) is the
   first one most integrations meet. See `api-guide.md`.

## Veritas callers

**Not yet, and this guide will not pretend otherwise.** Veritas and Metis are
deferred to V1.2: their domain services, adapters and route handlers stay
registered, and the member-facing surface returns a 404 carrying a
machine-readable deferral reason rather than data a client has no route to
render (`apps/oshun/bff/src/middleware/release-scope.ts`). Operator, admin and
studio paths are deliberately exempt, because governance still reviews Veritas
retraction queues while the room is hidden.

Two phase-182 items are gated on that release and remain open: `182.C.13.02`
(wire the Veritas unified provider deliberately or retire it — do not leave
unreachable HeyGen/Tavus/D-ID adapters presented as runtime capabilities) and
`182.C.31.07` (consolidate the Veritas surface). Until one of those closes,
**there is no Veritas migration path to document**, and writing one would
describe a surface a caller cannot reach.

## What this guide does not do

It does not give you a code sample against a running server: nothing in this
phase is mounted, and `api-guide.md` explains how to tell a captured response
from a schema-derived one.