ModelForge/docs/architecture/adr/0004-embedding-upgrades-require-migration.md

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.