Debug truncated candidates and exact-ID misses

Map failure classes for POST /v1/search/rerank: retryable vs fatal vs needs-human. Retries need budgets, jitter, and idempotency rules aligned to top-1 after rerank must beat BM25-only nDCG@5 on gold; latency budget ≤ 120ms for rerank. The chapter’s signature failure — reranker scores all candidates near 0.5 — order equals retrieve order — must take a deliberate branch, not a generic catch-all.

Implement the degrade/rollback/refuse behavior support agent asking about E_CONN_RESET wording variants needs when RERANK-FLAT-55 repeats. Prefer scoped controls (one flag, one weight, one tenant, one secret version) over fleet-wide restarts. Preserve evidence; do not delete logs to “clean the demo.”

After containment, check nDCG@5 and rerank_ms p95 moves in the safe direction and watch for retry amplification. Write the stop condition that ends the incident response for this lab.

Chaos note: inject only one fault class at a time and restore fixtures after. Watch for dual failures — dependency down and retry amplifier — which is how reranker scores all candidates near 0.5 — order equals retrieve order becomes an outage. Customer communication templates (even if only for the drill) beat silence. If you queue deferred work, define poison-message handling. Budget documents should state the maximum extra spend allowed during retries. Close the loop by linking the containment action to a dashboard panel for nDCG@5 and rerank_ms p95.

Draw a state diagram for degrade modes and put it in the repo as ASCII if needed. Cap concurrent retries across the process, not only per request. Ensure cancellation propagates to downstream HTTP clients. When failing closed, choose a user-visible message that does not leak internals. Practice the single command that flips the kill switch or weight to zero. After recovery, drain or inspect deferred work before declaring green. In this chapter the product is hybrid BM25+vector retrieve then cross-encoder rerank for error-code FAQs, the human stakeholder is support agent asking about E_CONN_RESET wording variants, and the incident id you design against is RERANK-FLAT-55. Re-state the oracle in your notes — query 'connection reset while uploading' ranks doc:e-conn-reset #1 after rerank — and keep the invariant visible: top-1 after rerank must beat BM25-only nDCG@5 on gold; latency budget ≤ 120ms for rerank. Track nDCG@5 and rerank_ms p95 as the scoreboard. Surface under change control: POST /v1/search/rerank. If you only have forty minutes, finish the fixture for reranker scores all candidates near 0.5 — order equals retrieve order before polishing UI. Promotion language stays ternary: promote, hold, or roll back based on evidence, not hope.