rfc: RFC 0047, search plan truth on engine v2

[ragnorc]

What this is

RFC 0047 is the correctness part of the search work. It removes every search query shape that gives a silent wrong answer, makes every search order a single total order, and makes every refused query explain itself.

It replaces the RFC 0047 text in #606. That text was written against engine v1. Since then engine v2 and the shared expression model landed on main, and since #795 engine v2 is the only query engine. This version is written from scratch against engine v2: every behavior it calls a defect was reproduced at b14c22c5 and checked again in code at baf10c94.

The problems

• A refused query does not say how to fix it. The most common agent mistake, query name { without (), gets parse error --> 1:1 … expected query_file.
• On engine v2, a query the planner refuses by design is reported as an internal error, HTTP 500 (A planner refusal by design is returned as an internal error (HTTP 500) #786).
• Full-text search on a property with no index falls back to a case-sensitive scan: "deep" and "Deep" match different rows (Unindexed full-text search is case-sensitive #747).
• Ranking a binding reached by a traversal fails when that binding is declared second (Ranking a traversal-introduced binding depends on declaration order #789).
• rrf() ignores the order keys after it (Order keys after rrf() are silently ignored #787), and a search-ordered aggregate applies no order, so limit keeps random groups (A search-ordered aggregate applies no order, so limit keeps arbitrary groups #788).
• A read does not say which retrieval produced its order or what a score column means.
• A slow served read cannot be attributed to a phase (Attribute the served read floor (~0.2 s server-side on a trivial read) and expose it as usage #752).

The proposal

1. Every refusal carries a code, a position or stage, what was expected, and one fix. A refusal by design is a 400 on every path.
2. Full-text search on a property without @index is a type error (T27); a declared index that is not built is refused at planning (FullTextIndexRequired).
3. The ranked binding becomes the root of its traversal component, so declaration order stops mattering on both engines.
4. Every search order sorts by score, then the remaining keys, then ids, and limit cuts rows. The fused rrf() score becomes a column you can return.
5. Reads report their retrievals and what each score column measures, derived from the plan that ran.
6. Served reads report time per phase.

Update (2026-09-29)

#795 made engine v2 the only query engine, with v1 kept only as a frozen reference for tests. So the RFC no longer asks engine v1 to refuse anything: the v1-door steps, the V… code group and the open question about them are removed, and the RFC has no unresolved questions. The rule that a planner refusal by design is a 400 with a diagnostic (step 2) stays. The branch also has main merged in.

Related

• compiler: the diagnostics contract for refused queries (RFC 0047, PR 1) #759 implements rollout step 1 (the diagnostics contract).
• RFC 0048, search contracts: rfc: search contracts on the shared expression model (RFC 0048) #793
• Analyzed lexical search: rfc: analyzed lexical search on the shared expression model #792
• Replaces the RFC 0047 part of rfc: search plan truth, retrieval algebra, analyzed lexical search, and the query kernel #606.

Checks: python3 scripts/check-docs.py, bash scripts/check-agents-md.sh, typos.