Fix Gemini candidate cap causing search 500s

TODO.md

@@ -117,6 +117,17 @@
   - new service layer file: `backend/services/ranker.go`
   - handler is now thinner and less coupled to search internals
 
+## Current Session Update (2026-03-13, 500 Fix)
+- A server-side `request failed (500)` regression was found after the ranker split.
+- Root cause:
+  - Gemini candidate cap logic returned `12` even when only `9` ranked candidates existed
+  - Gemini batch slicing then attempted to read beyond the available slice bounds
+- Fix applied:
+  - `GeminiCandidateLimit` now never exceeds the real candidate count for totals up to 12
+  - Gemini evaluation now stays within valid ranked slice bounds
+- Effect:
+  - avoids backend 500 during the Gemini Vision evaluation stage for mid-sized result sets
+
 ## Local Self-Test Workflow
 - Primary command:
   - `bash scripts/selftest.sh`

backend/services/cse_test.go

@@ -63,3 +63,9 @@ func TestIsRenderableArtgridResultAcceptsArtlistCanonical(t *testing.T) {
 		t.Fatal("expected artlist canonical clip URL to be accepted for Artgrid collector")
 	}
 }
+
+func TestGeminiCandidateLimitNeverExceedsCandidates(t *testing.T) {
+	if got := GeminiCandidateLimit(9); got != 9 {
+		t.Fatalf("expected Gemini limit to stay within candidate count, got %d", got)
+	}
+}

backend/services/ranker.go

@@ -81,7 +81,7 @@ func RankSearchResults(query string, results []SearchResult) []SearchResult {
 
 func GeminiCandidateLimit(total int) int {
 	switch {
-	case total <= 8:
+	case total <= 12:
 		return total
 	case total <= 16:
 		return 12