fix(vector): address PR review — wait=True backfill, batched writes, search helper

Addresses reviewer feedback on PR #773:

- Backfill set_payload now uses wait=True to avoid a race where
  _ensure_keyword_payload_indexes builds the KEYWORD index before
  fire-and-forget writes have committed, leaving int payloads
  invisible to filters.
- Batch points sharing the same int doc_id into a single set_payload
  call (one document → many chunks → one round-trip instead of N).
- Drop _has_int_doc_id_sample short-circuit. The sample's false-negative
  window (clean first 256 results, ints further in) is gone; full scroll
  is the dominant cost on first run anyway.
- Simplify _ensure_keyword_payload_indexes: the "already exists" 400
  branch was dead code (Qdrant returns 200 on identical re-create); any
  400 now logs a warning and continues.
- search/context.py: comment the broadened file-type guard. Add explicit
  not doc_id.isdigit() checks at the top of note/news_item/deck_card
  branches in _fetch_document_text so malformed payloads surface as
  warnings instead of being swallowed by the broad except.

Also extracts build_search_result_from_point into search/algorithms.py
to deduplicate the 71-line payload-extraction loop shared by
SemanticSearchAlgorithm and BM25HybridSearchAlgorithm. This fixes
SonarQube's quality-gate failure (4.0% new-code duplication, max 3%).

Test coverage:
- 7 new unit tests for build_search_result_from_point covering missing
  payload, note/file/deck_card metadata, int doc_id coercion, and
  metadata_extras merging.
- Replace _has_int_doc_id_sample tests with clean-collection no-op and
  per-batch grouping tests.
- Update set_payload assertions from wait=False to wait=True.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

nextcloud_mcp_server/search/semantic.py

@@ -8,7 +8,11 @@ from qdrant_client.models import FieldCondition, Filter, MatchValue
 from nextcloud_mcp_server.config import get_settings
 from nextcloud_mcp_server.embedding import get_embedding_service
 from nextcloud_mcp_server.observability.metrics import record_qdrant_operation
-from nextcloud_mcp_server.search.algorithms import SearchAlgorithm, SearchResult
+from nextcloud_mcp_server.search.algorithms import (
+    SearchAlgorithm,
+    SearchResult,
+    build_search_result_from_point,
+)
 from nextcloud_mcp_server.vector.placeholder import get_placeholder_filter
 from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
 
@@ -134,65 +138,20 @@ class SemanticSearchAlgorithm(SearchAlgorithm):
 
         # Deduplicate by (doc_id, doc_type, chunk_start, chunk_end)
         # This allows multiple chunks from same doc, but removes duplicate chunks
-        seen_chunks = set()
-        results = []
+        seen_chunks: set[tuple[str, str, Any, Any]] = set()
+        results: list[SearchResult] = []
 
-        for result in search_response.points:
-            if result.payload is None:
+        for point in search_response.points:
+            sr = build_search_result_from_point(point)
+            if sr is None:
                 continue
-            # doc_id is always str post-normalization, but defensively coerce
-            # legacy int payloads on read until the backfill has run everywhere.
-            doc_id = str(result.payload["doc_id"])
-            doc_type = result.payload.get("doc_type", "note")
-            chunk_start = result.payload.get("chunk_start_offset")
-            chunk_end = result.payload.get("chunk_end_offset")
-            chunk_key = (doc_id, doc_type, chunk_start, chunk_end)
 
-            # Skip if we've already seen this exact chunk
+            chunk_key = (sr.id, sr.doc_type, sr.chunk_start_offset, sr.chunk_end_offset)
             if chunk_key in seen_chunks:
                 continue
-
             seen_chunks.add(chunk_key)
 
-            # Build metadata dict with common fields
-            metadata = {
-                "chunk_index": result.payload.get("chunk_index"),
-                "total_chunks": result.payload.get("total_chunks"),
-            }
-
-            # Add file-specific metadata for PDF viewer
-            if doc_type == "file" and (path := result.payload.get("file_path")):
-                metadata["path"] = path
-
-            # Add deck_card-specific metadata for frontend URL construction
-            # and verify-on-read (ADR-019) — both board_id and stack_id are
-            # required to call deck.get_card without an O(boards × stacks)
-            # iteration fallback.
-            if doc_type == "deck_card":
-                if board_id := result.payload.get("board_id"):
-                    metadata["board_id"] = board_id
-                if stack_id := result.payload.get("stack_id"):
-                    metadata["stack_id"] = stack_id
-
-            # Return unverified results (verification happens at output stage)
-            results.append(
-                SearchResult(
-                    id=doc_id,
-                    doc_type=doc_type,
-                    title=result.payload.get("title", "Untitled"),
-                    excerpt=result.payload.get("excerpt", ""),
-                    score=result.score,
-                    metadata=metadata,
-                    chunk_start_offset=result.payload.get("chunk_start_offset"),
-                    chunk_end_offset=result.payload.get("chunk_end_offset"),
-                    page_number=result.payload.get("page_number"),
-                    page_count=result.payload.get("page_count"),
-                    chunk_index=result.payload.get("chunk_index", 0),
-                    total_chunks=result.payload.get("total_chunks", 1),
-                    point_id=str(result.id),  # Qdrant point ID for batch retrieval
-                )
-            )
-
+            results.append(sr)
             if len(results) >= limit:
                 break