refactor(search): address PR #750 round 7 review feedback

Round 7 raised 5 issues; this round addresses all of them and fixes
the underlying causes (not just the comments) where applicable so
they don't get re-flagged in future passes.

Critical:
- verified_count description in SemanticSearchResponse said "unique
  documents" but the value is len(verified_results), a chunk count.
  Description rewritten to accurately document chunk-level granularity
  AND explicitly call out the asymmetry with dropped_count (which
  counts unique (doc_id, doc_type) pairs).

- _verify_files false-eviction risk: the round-6 doc-only fix was
  re-flagged. Address at the source — widen WebDAVClient.get_file_info
  to raise HTTPStatusError on 404 (matching the rest of the client
  convention) and reserve None for the genuinely ambiguous
  malformed-PROPFIND case. _verify_files now keeps the result on None
  (cannot tell whether the file exists) and evicts only on a
  definitive HTTPStatusError 404. Tests updated; new test added for
  the malformed-XML keep-result path.

Non-critical:
- News verifier semaphore lifetime now explicitly documented: one
  slot held for one deduplicated fetch per search is the correct
  backpressure behaviour.

- Cross-reference comments in _verify_notes / _verify_deck_cards no
  longer claim "Mirrors X" pointing at functions defined later in
  the file; now use direction-neutral "parallel implementation in".

- accessible_by_type is mutated by concurrent run_verifier tasks; a
  comment explains why this is race-free under anyio's cooperative
  multitasking (distinct keys per task, no await between read and
  write) so a future reader doesn't add a redundant lock.

- Knock-on: tests/integration/test_rag.py wraps get_file_info in a
  try/except for the new contract.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Chris Coutinho
2026-05-01 21:15:39 +02:00
co-authored by Claude Opus 4.7
parent e8df6003c5
commit 3e981e647a
6 changed files with 123 additions and 57 deletions
+12 -6
View File
@@ -83,17 +83,23 @@ class SemanticSearchResponse(BaseResponse):
verified_count: int = Field(
default=0,
description=(
"Number of unique documents that passed verify-on-read access "
"checks (ADR-019). Equals len(results) before trimming to limit."
"Number of search result chunks that passed verify-on-read "
"access checks (ADR-019). Equals len(verified_results) before "
"trimming to limit. Note: multiple chunks of the same document "
"are counted separately here, whereas dropped_count counts "
"unique (doc_id, doc_type) pairs — the asymmetry is intentional "
"(verified_count is sized in result rows, dropped_count is "
"sized in unique ghost documents)."
),
)
dropped_count: int = Field(
default=0,
description=(
"Number of unique documents dropped as ghost records during "
"verify-on-read (ADR-019). A short result page (len(results) < "
"limit) combined with a non-zero dropped_count indicates ghost "
"density rather than scarcity of relevant content."
"Number of unique (doc_id, doc_type) pairs dropped as ghost "
"records during verify-on-read (ADR-019). A short result page "
"(len(results) < limit) combined with a non-zero dropped_count "
"indicates ghost density rather than scarcity of relevant "
"content."
),
)