# Embedding migrations

An `EmbeddingMigration` names source/target spaces, source collection, distinct shadow collection,
pinned corpus revision and background execution bounds. Supported lifecycle:

```text
PLANNED -> PREFLIGHT -> BACKFILLING -> VALIDATING -> READY_FOR_EVALUATION
                                                -> FAILED / CANCELLED
READY_FOR_EVALUATION -> EVALUATED -> PROMOTION_ELIGIBLE / NOT_ELIGIBLE
```

Preflight must prove current health, authoritative corpus availability, scoped Gateway access,
target space/dimension/distance, Qdrant reachability, storage and collection non-conflict before a
vector write. ExampleRAG checkpoints after successful Qdrant batches only. Resume validates and skips
matching point fingerprints; mismatches fail closed. Cancellation is observed between batches and
retains the shadow for inspection/resume. Validation checks count, missing/duplicate/malformed and
fingerprint evidence plus source-alias equality. No M6 endpoint performs alias cutover.

M13 retains this M6 project-owned backfill mechanism and adds the generic control-plane layer in
`MIGRATION_ENGINE.md`: immutable lifecycle intent, richer durable checkpoints, versioned validation,
shadow evidence, external-truth cutover/rollback and recovery. The old endpoint still cannot cut over;
there is no bypass from an M6 migration record to production.