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 stable /api/search handling for temporary search index unavailability, returning HTTP 503 with SEARCH_INDEX_UNAVAILABLE.
• Bug Fixes
  • Improved behavior when the index is locked: avoids fallback when indexed results are sufficient and correctly merges fallback results when more are needed.
  • Prevents internal fallback error details from leaking in API responses.
• Documentation
  • Documented the new SEARCH_INDEX_UNAVAILABLE error code in the API reference.
• Tests
  • Added regression coverage for index-lock + fallback failure and updated search index expectations for the new result shape.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: fc889631-b9cc-433b-913f-d31c3a85e18e

📥 Commits

Reviewing files that changed from the base of the PR and between a61fc7b and c10114b.

📒 Files selected for processing (1)

• tests/test_error_codes.py

🚧 Files skipped from review as they are similar to previous changes (1)

• tests/test_error_codes.py

---

📝 Walkthrough

Walkthrough

Search execution now uses a structured index-search outcome, converts locked-index live-scan failures into SEARCH_INDEX_UNAVAILABLE, and returns HTTP 503 from /api/search. The new error code is documented, and tests were updated for the outcome shape and failure response.

Changes

Search index unavailable handling

Layer / File(s)	Summary
Outcome and error types for index search api/search.py	Adds _IndexSearchOutcome and _SearchIndexUnavailableError, and changes _search_via_index to return the structured outcome shape.
Lock-aware fallback and search resolution api/search.py	Marks locked index searches with no hits, adds the live-scan fallback wrapper, and rewrites _resolve_search_results to use the outcome object and fallback path.
Error code, route handler, and documentation api/search.py, models/error_codes.py, docs/api-reference.md	Adds SEARCH_INDEX_UNAVAILABLE, returns it from /api/search on the new exception path, and documents the 503 response.
Tests for outcome contract and unavailable error tests/test_error_codes.py, tests/test_error_propagation.py, tests/test_search.py, tests/test_search_index.py	Updates tests to consume _IndexSearchOutcome and adds coverage for the new 503 response and non-leaking error body behavior.

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

Possibly related PRs

• cppalliance/claude-code-chat-browser#120 — Introduces the index-first search flow and live-scan fallback that this PR extends with a new locked-index failure code.
• cppalliance/claude-code-chat-browser#121 — Modifies the same /api/search execution path and locked-index handling that this PR builds on.

Suggested reviewers: timon0305, wpak-ai

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and directly describes the new locked-index failure response.
Linked Issues check	✅ Passed	The PR adds the new error code, returns 503 on locked-index fallback failure, updates docs, and adds the requested tests.
Out of Scope Changes check	✅ Passed	The refactor and test updates support the stated search error-path change and do not introduce unrelated scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ 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.}