# ADR-0004: Embedding-space changes require explicit migration

**Status:** Accepted

## Decision

A deployment change for a vector-producing capability is `requires_reindex` unless compatibility has been explicitly proven by the capability contract.

## Required migration shape

1. create a shadow index/version;
2. backfill using the candidate embedding deployment;
3. validate corpus and counts;
4. execute project-specific retrieval benchmarks/shadow queries;
5. promote the new index atomically;
6. retain old index and deployment for rollback until retention expires.

Matching vector dimension alone is never evidence of semantic compatibility.