# Consistency: writes then reads

## The reality

Upsert acknowledges the write; queryability of the new vectors can lag by seconds. Test suites and ingest-then-query scripts that assert immediately are flaky by construction.

## Patterns

1. **Settle wait.** After a bulk upsert, sleep briefly (tens of seconds, scaled to batch size) before verification queries. Crude but effective for scripts.
2. **Fetch-based confirmation.** `fetch` on the new ids: when the ids are fetchable, the write landed. Poll fetch with a timeout instead of sleeping blind.
3. **Stats-based gate.** Poll `describe_index_stats` until totals reflect the ingest, then run verification queries.
4. **Separate the paths.** In production, the write path and read path are different requests minutes apart; consistency lag is invisible. Only scripts and tests that write-then-read in one flow need the handling.

## Traps

1. Asserting query results immediately after upsert in CI: flaky tests that erode trust in the suite. Gate on fetch or stats first.
2. Confusing lag with loss: vectors missing at second 2 and present at second 20 were never lost. Check timing before declaring data loss.
3. Over-waiting in production code: a 30-second sleep in a request handler is a latency bug. Keep settle logic in scripts and tests, not serving paths.