# Migration engine

M13 promotes stateful capability change to a first-class, immutable `MigrationPlan`. A plan binds an
exact project binding, capability contract, source and target identities, adapter fingerprint,
validation-policy revision, M12 approval, rollback target, execution bounds and environment
fingerprint. Approval facts are rechecked immediately before cutover.

The guarded state graph is implemented in `migration_contracts.py`. Every transition adds a bounded,
append-only `MigrationEvent` containing identities, actor, policy, generation, reason and evidence
references. Mutable progress uses database compare-and-swap on `version`; adapter results also carry a
64-bit generation. Production permits at most one non-terminal migration per project/capability.

Core never runs migration code from payloads. An adapter contract is a fingerprinted set of known
operations. M13's first concrete operational contract is `examplerag.qdrant-reindex`; ExampleRAG owns
enumeration, deterministic chunk identities, Gateway calls, Qdrant writes and alias inspection. Core
does not assume Qdrant and stores no vectors, document bodies, queries or secrets.

The earlier M6 `EmbeddingMigration` remains evaluation/backfill evidence. M13 layers lifecycle,
cutover, rollback and reconciliation above that proven project-owned mechanism instead of replacing
or weakening it.
## M14 operational integration

Migration plan states, validation/manual-intervention failures and rollback failures are observed
from the M13 journal. `migration.production.reliability` evaluates terminal correctness over seven
days and `MIGRATION_FAILURE`/`ROLLBACK_FAILURE` preserve an explicit lifecycle. Monitoring never
changes a plan generation, resumes backfill or mutates an external alias.