Embedding Pipeline Service  ·  View 16 of 22  ·  Runtime

Critical Flow — Contract Migration and Alias Cutover

The seventeen messages that turn a model upgrade into a build, a measurement and an alias write.

Editable source SVG draw.io All views
Platform engineer Contract registry Migration orchestrator Embedding fleet Shadow index Serving index Index catalogue Quality harness 1. register contract C2 (digest pinned) 2. price: chunks, GPU hours, storage 3. estimate: 14 d / 72 h, +60% storage 4. accept, background rate 5. provision index under C2 6. enable dual-write 7. re-embed ledger under C2 8. vectors (C2 only) 9. live edits continue 10. oldest unmigrated chunk: 4 h 11. score frozen set on C2 12. recall@10 +4.1 pts: gate passed 13. flip alias, tenant wave 1 14. serving C2 15. regression on wave 1? 16. flip back (alias write) 17. retire after 21 days Critical Flow — Contract Migration and Alias Cutover Message 16 is the whole payoff: rollback is one alias write against an index that is still built, still fed and still measured. v 1.0 · owner Data & AI Platform Architecture · date 2026-10

The payoff

  • Message 16 is the point of the whole architecture: rollback is one alias write against an index that is still built, still live-fed and still measured.
  • Dual-write is enabled before re-embedding starts, so the shadow index is never behind on live edits and "complete" means complete.
  • The gate at message 12 is a quality comparison, not a completeness check. An index can be 100% built and still not be allowed to serve.

Cost is accepted before it is spent

  • Messages 2 and 3 price the migration — chunks, GPU hours, peak storage, duration at both rates — and a human accepts it. A migration that nobody priced is a migration nobody can stop.
  • Progress is reported as the oldest unmigrated chunk rather than a percentage, because a percentage hides a stalled tail.
  • The superseded index is retained 21 days, which is the real length of the storage doubling.

Risks

  • A per-tenant wave means the estate is split across two contracts for days. Any cross-tenant quality comparison during that window is invalid.
  • If the shadow build outruns the retained-text window for old documents, those documents re-enter at the fetch stage and load the source systems.
◀  Retrieval Paths All views Deployment Architecture  ▶
Solution Architecture v1.0 · open source, self-hosted on Kubernetes · Data & AI Platform Architecture · 2026-10 · 22 views · 17 architecture decision records16-contract-migration