RAG evidence window: cap media by its own slots, not inside the top-k cut
Bug pattern from a hybrid (vector + FTS, RRF-fused) retriever that added image/PDF records to the same fused ranking as text.
First attempt: window = fused[:max_records], then walk the window keeping at most max_media media and skipping the rest. The bug is that skipped media had already used a window position. Text ranked just after it was pushed out as record_limit, so the cap bounded how many media were KEPT, not how many text slots media CONSUMED. Repro: 5 images whose filenames match the query outrank 4 text records; with max_records=4 and max_media=1, the LLM got 1 of 4 text records.
Fix: partition the fused list by modality first. Fill max_records text slots in fused order, keep up to max_media media on top, and skip the remaining media without giving it a position. Keep the original fused rank on every record for reporting.
Watch out: any validator that bounds skip ranks by max_records (e.g. "budget skips rank <= max_records") breaks once media can sit above the text. Rephrase it relative to the first record_limit skip instead.
A related candidate-stage issue: search text with media excluded and run a separate media-only pass, then merge each list by raw score (distance ascending, bm25 ascending), so media cannot starve the text candidate top-k either.