explorer: search-results "50+" → real "N of M" count (closes #232)

[rdhyee]

Summary

Roadmap step 2 of #234 (#232 "50+" → real count, quick-win).

The in-map search-results line used to read 50+ results for "pottery" whenever the SELECT hit LIMIT 50, hiding whether the true result set is 51 or 50,000. For pottery Cyprus (world scope) the real count is ~7,124; users saw 50+ and couldn't gauge whether to refine.

Before: 50+ results for "pottery"
After: 50 of 7,124 results for "pottery"

Mirrors the pattern used to close #206 (real-count follow-up in loadViewportSamples()).

Approach

• When the SELECT cap is hit, fire a follow-up COUNT(*) with the same WHERE clause and replace the label.
• Below the cap, results.length IS the truth — no second scan.
• Initial render keeps 50+ while COUNT is in flight, so users see "more exist" signaling immediately.

Key implementation details

1. Effective query shape. The area-scope path can fall back to the world-mode SELECT when viewerBboxSQL() returns null. Track which shape actually ran (effectiveQueryShape / effectiveBboxSQL) so the COUNT uses the matching WHERE/JOIN. Keying off effectiveScope === 'area' would have generated a malformed COUNT in the fallback case.

2. Cancellation. A second search bumps _searchSeq. The COUNT guards against searchId !== _searchSeq so a stale COUNT can't overwrite a fresher search's text or pollute its structured log.

3. Failure handling. A COUNT error leaves the initial 50+ label in place — under-disclosure beats clearing the line. Logged via console.warn; count_ms is still recorded.

4. Structured log (Explorer FTS Track 1a: Browser perf-smoke baseline #167) additions. total_count (real count, or null when not computed) and count_ms (COUNT scan duration). elapsed_ms continues to mark end-of-handler so it remains an end-to-end "search complete" latency including the COUNT.

Test plan

• New spec tests/playwright/search-real-count.spec.js:
  • cap-hit case (pottery): initial 50+ then 50 of N (N>50), structured log carries total_count and count_ms > 0.
  • no-results case (xyzzyqqqplugh): still short-circuits to No results; COUNT not fired; total_count: null, count_ms: 0.
• Fault-injection: both new tests FAIL against pre-fix code, PASS against the fix.
• Local regression: search-real-count + url-roundtrip + facetnote-url-load → 9 passed (1.7m).
• Manual: verify against the cold-cache deploy that the COUNT scan time is acceptable for pottery / pottery Cyprus.

What's NOT in this PR

• Search-as-global-filter (A1) — that's step 5 of explorer: architectural direction — make filter semantics coherent across all surfaces #234, gated on FTS landing first.
• Pagination past 50 — out of scope per explorer: search-results '50+' label should show the real count #232.
• Real BM25/FTS substrate — Explorer FTS Track 2: search_index_v1 contract doc #169-Explorer FTS Track 5: GO/NO-GO decision gate #172 line of work.

Acceptance criteria (from #232)

• Search line reads 50 of N results for "term" when the cap is hit.
• Search line reads 12 results for "term" (unchanged) when below the cap.
• No regression in cancellation behavior when the user types quickly (guarded via _searchSeq invariant; covered conceptually rather than via a flaky two-SELECT race in Playwright).

🤖 Generated with Claude Code

[rdhyee]

Codex review iteration log (4 rounds → LGTM)

Round	Codex finding	Resolution	Commit
1	Stale _searchSeq guard placement: UI mutations + COUNT launch could fire for superseded searches before guard	Added early searchId !== _searchSeq check immediately after SELECT, before any UI write / panel render / fly-to / COUNT	27aa70f
1	Predicate not snapshotted: filter toggle mid-flight produces "50 of M" where M is for a different filter than the rendered 50	Snapshot sourceSQL / facetSQL once at search-fire time, reuse in SELECT (both shapes) and COUNT (both shapes)	27aa70f
2	Stale error UI write: catch block unconditionally overwrites live UI with Search error: … if a superseded SELECT later rejects	Guard the catch's searchResults.textContent write on searchId !== _searchSeq (sets wasSuperseded = true and logs the original error without UI mutation)	764ed63
2	DOM-live telemetry in finally: has_source_filter / has_facet_filter could reflect post-toggle state	Snapshot hadSourceFilter / hadFacetFilter at function scope at search-fire time, reused in finally	764ed63
3	Invalid-submit stale overwrite: empty/short term early-return didn't bump _searchSeq, so a prior search's rejection could overwrite "Type at least 2 characters"	Bump _searchSeq at the TOP of doSearch, before any guard — every submission supersedes in-flight work	5de9136
3	Race test timing-dependent: wait accepted either 50+ or final 50 of N, so the toggle could miss the window	Monkey-patch db.query with a 1.5s delay on COUNT(*) queries; wait for EXACT 50+ before toggling	5de9136

Round 4: LGTM (Codex)

The COUNT-delay test closes the round-3 coverage hole in practice: the patch is installed before the search, the test waits for exact 50+, and COUNT is held open before the final log. […] Round 4 verdict: LGTM.

Known follow-up filed as a TODO comment in the test:

• Independent has_source_filter snapshot coverage requires a non-Quarto fixture — Quarto's see-also rendering duplicates #sourceFilter checkboxes, so toggle-and-count assertions are ambiguous in preview. The production snapshot uses the same pre-await pattern as has_facet_filter, which IS covered.

Final test count: 8 passed (3 search-real-count + 5 url-roundtrip + 2 facetnote-url-load, total ~2 min) plus the fault-injection sanity check on every round.

Thanks codex for the four-round audit — the catch-path supersession (round 2) and invalid-submit window (round 3) were both real bugs I'd have missed.