Search for the words, not the exact string

[rutgerhofste]

The bug

Searching a mailbox for a contact's name came back empty. The signature carries a second space between two of its words:

Iris  van 't Klooster

The whole query went out as one IMAP TEXT key, which is a substring match over the raw message — so Iris van 't Klooster is genuinely not in there. The same literal would equally have missed a header fold between the words, a curly apostrophe, or a sender who writes Klooster, Iris.

Worse, what happened instead was undefined. RFC 3501 explicitly lets a server "implement flexible matching" for TEXT. Checked against three real accounts: one IMAP host word-matches and ignores order, another does strict substring, and Graph runs KQL keywords. The same tool meant three different things depending on who answered — the divergence the attachment and meeting seams are already held against.

The fix

A backend-neutral query layer, squirrel_mcp/search_query.py, parsed once and compiled by each backend (IMAP into search keys here; the admin package's Graph provider into KQL, in its companion PR).

iris klooster           both words, anywhere, any order   ← the default now
"fiscal localization"   those words together, in order
from:iris               the sender, not every mention
to: cc: subject: body:  the other fields
-newsletter             must not appear
invoice OR factuur      either one
has:attachment          only messages carrying a file

Unquoted words AND as separate keys rather than forming a phrase — Gmail's and Outlook's convention, which every model prompting them already assumes, and the whole fix for the spacing bug. Case, accents and apostrophe flavours fold.

Three rules keep the backends honest

The compiled query is always at least as broad as what was asked. No server will fold accents in a mailbox for us and neither spelling of a name finds the other, so a term that cannot be sent faithfully is widened (José leaves as Jos), never narrowed.

Anything a summary can prove is verified exactly, taking that breadth back — sender, recipients, subject, attachment flag. What a summary cannot carry (the body, cc) stays the server's word, because a 200-character preview of a body that may be megabytes refutes nothing, and filtering on it would drop the matches this exists to find.

Widening is reported, never silent. A query matching nothing widens rather than returning an empty page that reads as "you have no mail from her": one term given up at a time, with matched / dropped_terms on SearchResult saying which.

The ladder tries each term in turn rather than guessing once. Dropping only the least distinctive term looks right and is not: the absent word is usually the rarest one, so a single guess keeps the missing word and stays empty. ORing everything together is deliberately not on the ladder — it always "works" and never informs.

Compatibility

parsed is an additive keyword on MailProvider.search, offered via signature inspection. A backend written before it keeps its raw query and answers exactly as it used to — tests/test_mail_search.py pins that with the conftest fixture's old-signature provider.

Tests

• tests/test_search_query.py — folding, the grammar, verification, the ladder
• tests/test_mail_search.py — the IMAP keys that leave, and the widening policy end to end
• GreenMail e2e — a real IMAP server finds the awkwardly-spaced name, honours a scoped term and an exclusion

make test 205 passed · make lint clean. The integration layer needs Docker, which this session had no daemon for, so those three run first in CI.

---

Generated by Claude Code