feat(search): route name-shaped queries to the symbol lane

[devin-ai-integration]

Summary

• An omitted prefer_symbol now lets the query's shape decide. Name-shaped queries such as getUserById, UserStore::getUserById, and where is parse_config called add the preferred-symbol route beside the strict query. Prose keeps the strict query alone.
• query_route on SearchCompleteV1 and ContextResultV1 discloses the decision, its margin, and who decided. Markdown gets a matching Query route: line.

Fixes #3013

Motivation

prefer_symbol was caller-only and defaulted to off, so name lookups ran the strict query alone. A qualified spelling the strict query cannot match, such as UserStore::getUserById, returned no results.

Changes

• crates/tracedecay-query/src/retrieval/lexical/routes.rs:
  • prefer_symbol is now SymbolRoutePreferenceV1, with the values ByQueryShape (the default), Always, and Never.
  • classify_query_shape counts content words, excluding stoplisted and one-character words. A word counts as a name when names_identifier matches the whole token or the trailing name of a.b and a::b. The query is Name when at least half its content words are names, so one incidental identifier in prose does not flip it.
  • The plan and LexicalRouteReceiptV1 carry LexicalRouteDecisionV1.
• crates/tracedecay-contracts: adds SearchQueryRouteV1 { route, margin, decided_by }:

  "query_route": { "route": "name", "margin": 0.5, "decided_by": "query_shape" }

  margin is the share of identifier-shaped content words minus one half, in [-0.5, 0.5]. It describes query shape only. Nothing reads it as an answerability or abstain signal.
• crates/tracedecay-mcp: passes prefer_symbol through as Option<bool>, fills in query_route, and renders it in markdown.
• Regenerated sdks/typescript/src/operations.ts and plugin/chatgpt-extension/embedded/server.mjs.

Test plan

• New name_shaped_queries_take_the_symbol_name_route_by_query_shape runs against a real index. With default routing, UserStore::getUserById and users.getUserById rank src/users.ts::getUserById first. Both returned no results before this change. A prose query reports prose, plans only the strict query, and ranks the same as prefer_symbol: false.
  • bash scripts/require-exact-test.sh cargo test -p tracedecay-code-index-runtime --lib code_index_scheduler::tests::serving::name_shaped_queries_take_the_symbol_name_route_by_query_shape -- --exact: 1 passed
• MCP suite: search_returns_the_named_symbol_and_refuses_arguments_outside_its_typed_request now also checks that ledger_post_entry without prefer_symbol plans the same routes as prefer_symbol: true and reports decided_by: query_shape. The forced call reports caller, and the prose miss reports prose with margin -0.5. 1 passed via require-exact-test.sh.
• cargo test --lib for tracedecay-query, tracedecay-contracts, tracedecay-mcp, and tracedecay-code-index-runtime: all pass
• cargo test -p tracedecay --lib mcp::tools::handlers: 84 passed
• cargo test -p tracedecay --features test-transport --test mcp_suite mcp_handler_test::: 484 passed. 4 failures come from the local environment: 3 need the host ast-grep CLI, and 1 needs the built tracedecay binary.
• cargo clippy -D warnings --all-targets passes on the four crates above and on tracedecay (--features test-transport).
• cargo fmt --all -- --check, python3 scripts/linux-test-partitions.py check, node scripts/lint-commit-range.mjs --repository . origin/master HEAD, sdks/codegen cargo test, sdks/typescript typecheck and test, and chatgpt-extension check:embedded all pass.
• I did not run the full cargo nextest run --workspace.

Checklist

• CHANGELOG.md updated: release-please generates it from the commit.
• No secrets, credentials, or .env files included
• Breaking changes: none for callers that set prefer_symbol. An omitted prefer_symbol now follows query shape instead of meaning false. query_route is a new optional response field.

Link to Devin session: https://app.devin.ai/sessions/2b6081c218314ac9bd2af0f9dcc3cb57
Open in Devin Desktop: https://app.devin.ai/desktop/session/2b6081c218314ac9bd2af0f9dcc3cb57?variant=devin
Requested by: @ScriptedAlchemy

---

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[changeset-bot]

⚠️ No Changeset found

Latest commit: 05f1337

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR