ADR 0007: Query language comparison and full queryability¶

Boolean composition without a field predicate¶

Boolean operators, grouping, and quoted phrases engage the parser whether or not a field predicate is present. A cheap, dependency-free heuristic decides whether input carries query syntax (a field colon, an uppercase boolean keyword, a parenthesis, or a quote) so that plain bare-term queries keep the legacy fast path and the cold-start budget in ADR 0006.

Phrase queries¶

A quoted value ("deploy v1") is a phrase: its internal whitespace is collapsed and it matches as a single casefolded substring of the record text. A phrase is a text term for every downstream purpose — prefilter, relevance ranking, and matching — so it carries no scoring semantics beyond ordered adjacency within the substring.

Field-exists¶

field:* matches records or sources where the field has a non-empty value. An empty string counts as absent. Negation uses the existing NOT / - forms (-model:*).

Wildcards on text and string fields¶

A field value containing * or ? matches by anchored, casefolded glob (fnmatch) rather than substring. Wildcards apply to field values only, never to bare terms, and never to enum or date fields. The path field keeps its existing case-sensitive glob.

Matching semantics¶

• Bare terms match as casefolded substrings and combine with implicit AND.

• Phrases match as a single casefolded substring with collapsed internal whitespace.

• Field-exists is true when the field value is non-empty; for source-prunable fields it resolves at the source layer, for record fields it resolves after parsing.

• Wildcard field values match by anchored casefolded glob; users who want substring semantics write *value*.

Discoverability¶

• The query language must be discoverable from CLI help examples, the MCP server instructions, MCP tool and parameter descriptions, and a machine-readable MCP resource, consistent with the registry-backed discovery direction in ADR 0006.

• Field and operator descriptions derive from the field registry so the surfaces cannot drift from the compiler.

Tests¶

• Parser, compiler, and engine behavior are covered by fast, pure tests with no subprocess or home-directory access, following the existing parametrized case-table pattern.

• A guard test proves that plain bare-term queries never import the query module, protecting cold start.

Positive¶

• Boolean queries, phrases, field-exists, and wildcards are reachable from the input users actually type.

• One registry feeds the compiler, CLI help, and MCP hints, so discovery and behavior stay aligned.

• The substring model stays the single semantic source of truth; no index or native dependency is introduced.

Behavior changes¶

Input that previously searched for the literal words OR, AND, or NOT, or for literal parentheses or quotes, now parses as a query. For example search OR raises a parse error rather than searching for the substring OR. The escape valves are lowercase keywords (or, and, not remain literal terms) and quoting ("OR" searches for the literal text). Users of a published release experienced the old colon-gated behavior, so this is a documented behavior change rather than branch-internal narrative.

Tradeoffs and asymmetries¶

• Wildcards apply to field values only, never to bare terms. A bare c*x stays a literal substring.

• The path field keeps case-sensitive glob (filesystem semantics) while text and string field wildcards are casefolded (text semantics). This asymmetry is intentional.

• field:* is field-exists, but field:** is a wildcard. The distinction is the exact value *.

Risks¶

• Heuristic over-engagement: a positional that looks like a field predicate engages the parser. The heuristic matches only registry-shaped identifiers, and unknown fields raise a clean parse error rather than searching silently.

• Generated-description drift: registry-backed help can still drift if generation is partial. Drift-guard tests compare the rendered field list against the registry.