Promote a compatible retrieval system as one immutable snapshot

A manifest should identify the query and document encoder versions, tokenization and text preprocessing, pooling, dimension, dtype, normalization, score metric, and any learned transform. For an IVF or PQ index it also identifies the trained coarse and product codebooks. Include stable document-ID mapping, corpus versions, metadata or visibility boundary, and required search parameters. A checksum establishes artifact identity, while a schema and compatibility check establish what those bytes mean together.

Equal dimensions are necessary for vector arithmetic but insufficient for model compatibility. Two encoders can both emit four coordinates while assigning completely different meanings to each direction. A rollback that loads an old index but keeps a new query encoder can therefore return confidently wrong neighbors without any shape error. Some systems deliberately use distinct query and document encoders; preserve that trained pairing rather than requiring identical binaries or assuming either side can be swapped independently.

Construct a candidate snapshot away from live traffic, verify artifact integrity, and check dimensions, item counts, stable IDs, and version-watermark coverage. Faiss I/O documentation explicitly makes callers responsible for loading trusted, unaltered index artifacts; deserialization is not a semantic compatibility validator. Run exact-reference recall checks, filter and deletion tests, and resource measurements using the candidate’s own compatible query pipeline. A file that loads successfully can still contain the wrong model’s vectors or an incomplete corpus.

An application can publish a new manifest identifier through an atomic pointer or compare-and-swap operation, while each query captures one manifest for its whole request. Load and validate the referenced artifacts before making that pointer visible. Keep old artifacts alive while in-flight requests still hold them. The exact storage primitive depends on the deployment platform; the lesson’s invariant is that one query must not mix encoder A, index B, and metadata C merely because those components refreshed at different moments.

A canary should compare complete bundles on a declared query sample, record their artifact IDs with latency and result metrics, and avoid changing the evaluation population mid-comparison. Test rollback before relying on it: confirm that the previous encoder, index, codebooks, and ID mapping remain available and loadable. If the previous snapshot predates important deletions or updates, define how current visibility overlays or replayed deltas are applied before sending its results to users.

Keep the promotion record small and auditable: candidate identity, source watermark, validation outputs, selected configuration, and previous pointer. Rollback is not a substitute for discovering why the candidate failed; preserve its artifacts and query traces for diagnosis. Rebuilding from source should be reproducible enough to explain differences, but retaining the exact validated bytes avoids assuming a stochastic graph builder will recreate an identical artifact. The operational unit is the compatible bundle that was actually tested.