Yeah, you nailed it. "The true filtered-nearest was never in the pool" is the part that makes it invisible, and honestly you said it cleaner than I did.

That ordering is right, and it's basically the set of options the tool picks between. The thing I kept running into - and why I gave up on just writing down the ladder - is that the rung you want depends on how sparse the filter is right around the query, and that changes query to query. ef_search helps, but if the filter is basically absent near the query you'd need it around k / local_selectivity to get enough survivors, which is just a scan with extra steps. Iterative scan is the real fix most of the time, agreed, but its cost climbs the same ~1/selectivity way and max_scan_tuples caps it, so once you're sparse enough a plain exact filtered scan is actually faster and can't come back short. So there's a crossover, and it moves around. Working out which side of it you're on for a given query is the whole thing I'm trying to automate.

And yeah - the LIMIT check is the best free canary there is. Tenant has at least LIMIT rows and you got fewer back? Something's off. That's literally one of the two numbers I report (returns-k rate) for exactly that reason. Mind if I steal that framing for the README as the "no tool needed" check? Happy to credit you.

Anyway, thanks. Comments like this are why it's worth writing these up.