SEARCH_INDEX_UNAVAILABLE for locked-index fallback failure

[clean6378-max-it]

Closes #114
Small follow-up after #121.

#121 already falls back to live-scan when the FTS index is locked, and still returns partial hits if it got some before the lock. Here we handle the case it didn't cover: index locked with no hits, and live-scan fails too. That gets 503 SEARCH_INDEX_UNAVAILABLE instead of a generic 500.

We log the real exception in the wrapper before mapping it to the 503. The JSON response keeps a fixed message. Tests also assert that live-scan error text doesn't end up in the body.

Touched error_codes.py, search.py, api-reference, and the search/error tests. pytest and ruff clean on what changed.

Summary by CodeRabbit

• New Features

  • Added a new search error response for cases where the index is temporarily unavailable and the fallback search also fails.
  • Search results now handle index-locked situations more gracefully, with clearer fallback behavior.

• Bug Fixes

  • Prevented internal search errors from leaking into the response body.
  • Kept search behavior consistent when partial indexed results are available.

• Documentation

  • Updated the API reference with the new search error code and HTTP 503 response.

[coderabbitai]

📝 Walkthrough

Walkthrough

Refactors search index querying into a structured _IndexSearchOutcome NamedTuple and adds a _SearchIndexUnavailableError raised when the index is locked with no hits and the live-scan fallback fails. Adds a corresponding SEARCH_INDEX_UNAVAILABLE error code, route handler returning 503, documentation, and updated tests.

Changes

Search index unavailable handling

Layer / File(s)	Summary
Outcome and error types api/search.py	Adds _IndexSearchOutcome NamedTuple (hits, fts_exhausted, index_locked_without_hits) and _SearchIndexUnavailableError exception.
Index search and live-scan fallback logic api/search.py	Updates _search_via_index to return the outcome type, marks index_locked_without_hits when locked with no results, and adds _live_scan_with_index_lock_fallback converting live-scan failures into _SearchIndexUnavailableError.
Search resolution and route wiring api/search.py, models/error_codes.py, docs/api-reference.md	Rewrites _resolve_search_results to use the outcome type and fallback wrapper, adds SEARCH_INDEX_UNAVAILABLE enum member, a dedicated exception handler in the search() route returning 503, and documents the new error code.
Test updates for new contract tests/test_error_codes.py, tests/test_error_propagation.py, tests/test_search.py, tests/test_search_index.py	Updates existing tests to mock/consume _IndexSearchOutcome, and adds new tests asserting 503 SEARCH_INDEX_UNAVAILABLE responses without leaking internal error messages.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant SearchRoute
  participant SearchViaIndex
  participant LiveScanFallback

  Client->>SearchRoute: GET /api/search
  SearchRoute->>SearchViaIndex: _search_via_index()
  SearchViaIndex-->>SearchRoute: _IndexSearchOutcome(index_locked_without_hits=True)
  SearchRoute->>LiveScanFallback: _live_scan_with_index_lock_fallback()
  LiveScanFallback->>LiveScanFallback: run live scan
  LiveScanFallback--xSearchRoute: raise _SearchIndexUnavailableError
  SearchRoute-->>Client: 503 SEARCH_INDEX_UNAVAILABLE

Loading

Suggested reviewers: timon0305, wpak-ai

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the new error code and the locked-index fallback failure it handles.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/search-errors-ux-polish

---

_{Comment @coderabbitai help to get the list of available commands.}