feat(query): improve recall, intent routing, ranking, and performance

[forhappy]

Summary

• Hard-cut typed symbol search to deterministic query-ranker/2; v1 exists only as a frozen differential test.
• Add bounded multi-source recall across exact ID/name, normalized aliases, term postings, and low-confidence typo variants.
• Rank with lexical coverage, evidence confidence, candidate provenance, semantic kind, production-source preference, and stable tie-breaking.
• Enforce maxCandidates as the total recall-pool bound instead of inflating it to maxNodes; emit explicit truncation diagnostics.
• Add a graph-scoped 64-entry search-preparation LRU and deterministic partial top-k selection.
• Add local query-planner/1 routing for search, callers, callees, impact, and node trails.
• Wire natural queries through the production CLI and MCP entry points.
• Add an 80-question reviewed synthetic contract corpus and a 23-question production-shaped executable baseline.
• Add bounded, opt-in local query logging plus deterministic redaction and review-candidate preparation for corpus growth.
• Preserve Unicode/combining-mark normalization and JSON/store backend parity.

Production wiring

Entry point	Behavior
compass ask "..."	Always executes CodeQueryEngine::query_natural and returns compass.query/1.
compass query "..."	High-confidence current-graph intent routes to the typed planner; generic, contradictory, historical, or explicitly traversed requests retain text traversal.
MCP query_graph	High-confidence questions on typed graphs route to the same planner unless legacy traversal controls are supplied.
compass search / MCP search_symbols	Enter multi-source recall and unconditional ranker v2 directly.
Explicit callers/callees/impact/node tools	Continue to execute their existing typed operations.

All paths remain native, local-first, credential-free, deterministic, and bounded. Ambiguous symbols remain explicit; the planner never invents call direction.

Accuracy and recall evidence

• The 23 executable questions exercise real query_natural requests for search, callers, callees, impact, path, paraphrase, typo, Unicode, ambiguity, domain, and no-answer cases.
• The executable baseline requires perfect Success@1, intent macro-F1, edge-direction precision, path acceptance, and no-answer precision on its deliberately small reviewed graph.
• JSON, SQLite store, and repeated-store observations must match after measured timing is normalized away.
• A differential case proves v1 ranks generated test code first while v2 ranks the production implementation first.
• The larger 80-question corpus validates judgment schemas and relevance metrics without presenting synthetic identities as production execution evidence.

Performance and bounds

• Search preprocessing is cached in a bounded 64-entry engine-local LRU.
• Ranking uses partial top-k selection while preserving the full-sort prefix.
• maxCandidates now controls the total recall pool (20 by default, hard cap 256); maxNodes independently bounds returned nodes.
• Typo expansion and each recall channel have fixed budgets.
• The 100,000-node in-process ceiling now covers direct search and natural-query planning in addition to callers, impact, and node trails; the combined query section remains below five seconds in the debug qualification test.
• A 500,000-edge unit qualification verifies adjacency work scales with the response budget.

Corpus feedback loop

COMPASS_QUERY_LOG=<path> opt-in logging writes bounded local compass.query-log/1 JSONL and stops at 16 MiB. scripts/prepare_query_relevance_review.py validates, redacts, deduplicates, and produces a deterministic compass.query-review-candidates/1 review queue. It never uploads telemetry or generates judgments automatically. Real production samples still require privacy review and two-reviewer, graph-digest-pinned approval before entering the executable corpus.

Validation

• cargo fmt --all -- --check
• cargo clippy --workspace --lib --bins --locked -- -D warnings
• cargo test --workspace --lib --bins --locked
• cargo clippy -p compass-query --all-targets --all-features --locked -- -D warnings
• cargo test -p compass-query --locked
• cargo test -p compass-query --test code_query_scale --locked
• cargo test -p compass-cli --test code_query_cli --locked
• cargo test -p compass-mcp --test code_query_tools --locked
• python3 scripts/qualify_query_relevance.py
• cargo test -p compass-cli --test compass_product --locked
• sh scripts/check_product_boundary.sh

The prior architecture failures were reproduced locally and fixed on this branch. Universal framework facts now retain the pipeline-provided repository-relative source identity, restoring Route/Event/Message/Topic/Queue/Job publication; the Windows watcher test uses an independent bounded rebuild deadline. The current head is rerunning every GitHub check.

Additional validation for the CI repair:

• cargo test -p compass-languages --locked
• cargo test -p compass-core --test code_graph_v1_determinism --locked (13 passed)
• cargo test -p compass-core watch::tests::watch_rebuilds_code_and_flags_semantic_changes --locked
• cargo clippy -p compass-languages --all-targets --all-features --locked -- -D warnings
• cargo clippy -p compass-core --all-targets --all-features --locked -- -D warnings
• ./scripts/qualify_code_graph_v1.sh --fixtures-only

All Cargo verification used this worktree's dedicated target under /Volumes/Workspace/crabbuild-target.