From 5abd568209d3a7ce7c7792ca929a7cc27fa6b425 Mon Sep 17 00:00:00 2001
From: Trenton Holmes <797416+stumpylog@users.noreply.github.com>
Date: Tue, 18 Aug 2026 14:14:57 -0700
Subject: [PATCH] docs(search): document the quote-blindness trade-off in the
 pre-parse rewrites

_quote_date_keyword_phrases and _rewrite_bare_json_field_prefixes both
regex-match anywhere in raw_query, with no awareness of whether the match
falls inside an already-quoted phrase on an unrelated field. Unlikely in
practice and not fixed (quote-aware scanning is real work for an edge
case), but now called out explicitly like this file's other accepted
trade-offs, instead of being the one undocumented one.
---
 src/documents/search/_query.py | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/src/documents/search/_query.py b/src/documents/search/_query.py
index 8da2470c4..793deabe3 100644
--- a/src/documents/search/_query.py
+++ b/src/documents/search/_query.py
@@ -72,6 +72,12 @@ def _quote_date_keyword_phrases(raw_query: str) -> str:
     quoted spellings, TEXT fields, and standalone words are untouched.
     Only quoting happens here - every date computation stays in
     whoosh-compat's grammar.
+
+    Not quote-aware: matches anywhere in raw_query, including inside an
+    existing quoted phrase (e.g. ``title:"see added:previous month
+    notes"`` would get quotes inserted mid-phrase). Accepted as an
+    unlikely-in-practice edge case rather than implementing quote-aware
+    scanning.
     """
     return _DATE_KEYWORD_PHRASE_RE.sub(
         r'\1:"\2"',
@@ -95,7 +101,12 @@ _BARE_JSON_PREFIX_RES: Final = (
 
 def _rewrite_bare_json_field_prefixes(raw_query: str) -> str:
     """Rewrite bare ``notes:``/``custom_fields:`` prefixes to their
-    subpath equivalents. Prefix substitution only, values untouched."""
+    subpath equivalents. Prefix substitution only, values untouched.
+
+    Not quote-aware, same accepted trade-off as
+    _quote_date_keyword_phrases: a literal ``notes:`` inside an existing
+    quoted phrase on an unrelated field would also get rewritten.
+    """
     for pattern, replacement in _BARE_JSON_PREFIX_RES:
         raw_query = pattern.sub(replacement, raw_query, timeout=_REGEX_TIMEOUT)
     return raw_query