test(router): add explicit coverage for non-explicit LLM routing to semantic

[mfittko]

Summary

Add explicit automated coverage for non-explicit llm -> semantic routing in api/src/services/query-router.test.ts, with one required generic path test and one preferred OpenAI parsing parity test.

Problem Statement

Current router tests cover llm -> metadata/graph, fallback/circuit behavior, and OpenAI model-selection behavior, but do not directly assert that semantic is accepted when returned by LLM on a low-confidence rule path.

Without this, regressions could silently reject or bias away from semantic while still passing existing tests.

Scope

In scope

• Test-only updates in api/src/services/query-router.test.ts.
• Required: generic/Ollama-path llm -> semantic assertion.
• Preferred: OpenAI chat-completions llm -> semantic parsing assertion.

Out of scope

• Production code changes in router implementation.
• Routing threshold/circuit-breaker behavior changes.
• API contract changes.

Implementation Approach (Single Issue)

Use one tightly-coupled implementation pass in the same test file:

1. Add required generic/Ollama-path regression test:

   • Query triggers low-confidence rule path (e.g., entity pattern).
   • Mocked LLM returns valid JSON with strategy="semantic", confidence=0.8.
   • Assert:
     • result.method === "llm"
     • result.strategy === "semantic"
     • result.confidence === 0.8

2. Add preferred OpenAI provider parity test:

   • OpenAI chat-completions response content contains JSON with strategy="semantic", confidence=0.8.
   • Assert same routing outcome (method, strategy, confidence).

Dependencies

• Parent epic: EPIC(feat): Hybrid Query Router — metadata, graph, and semantic query strategies #109
• Router contract baseline: feat(query): Router and classifier (rules + LLM fallback) #112 and PR feat(api+cli+docs): unified query response contract for multi-strategy routing #122

Validation Plan

• cd api && npm test -- src/services/query-router.test.ts

Risks and Mitigations

• Risk: test accidentally uses non-LLM path.
  • Mitigation: use low-confidence rule query and assert method === "llm".
• Risk: OpenAI mock shape mismatch.
  • Mitigation: use current parser shape (choices[].message.content).
• Risk: environment leakage across tests.
  • Mitigation: rely on existing env/global reset hooks in test suite.

Decision Log (assumption -> resolution)

Assumption	Resolution
Work should be split for tracking	Not needed; requirements are tightly coupled and belong in one issue.
OpenAI branch can be ignored	Kept as preferred parity check, still same issue and same PR.
Code changes may be required	Explicitly prohibited; test-only delivery.

Proposed Definition of Done

• Required generic/Ollama-path unit test proves llm -> semantic on low-confidence rule path.
• Preferred OpenAI provider unit test proves semantic acceptance from chat-completions payload.
• api/src/services/query-router.test.ts passes locally/CI with added tests.
• No production file changes outside tests.
• PR/issue includes short validation evidence (command + pass summary).

AC/DoD/Non-goal Coverage Matrix

Item	Type (AC/DoD/Non-goal)	Status (Met/Partial/Unmet/Unverified)	Evidence (spec/tests/behavior)	Notes
Unit test fails if llm -> semantic path regresses	AC	Unverified	Planned test additions in api/src/services/query-router.test.ts	Required item
Test passes for both generic LLM fallback and (optionally) OpenAI provider branch	AC	Partial	Required generic + preferred OpenAI parity test in same issue	OpenAI remains preferred per original scope
No behavior changes required; test-only PR is acceptable	AC	Unverified	Scope and DoD constraints	Validate at PR diff
Required generic/Ollama-path unit test proves llm -> semantic on low-confidence rule path.	DoD	Unverified	Proposed DoD item 1	Added because source issue has no explicit DoD
Preferred OpenAI provider unit test proves semantic acceptance from chat-completions payload.	DoD	Unverified	Proposed DoD item 2	Added because source issue has no explicit DoD
api/src/services/query-router.test.ts passes locally/CI with added tests.	DoD	Unverified	Proposed DoD item 3	Added because source issue has no explicit DoD
No production file changes outside tests.	DoD	Unverified	Proposed DoD item 4	Added because source issue has no explicit DoD
PR/issue includes short validation evidence (command + pass summary).	DoD	Unverified	Proposed DoD item 5	Added because source issue has no explicit DoD
Production router code changes	Non-goal	Unverified	Out-of-scope section	Must remain absent in PR diff
Routing threshold/circuit-breaker behavior changes	Non-goal	Unverified	Out-of-scope section	Must remain absent in PR diff
API contract changes	Non-goal	Unverified	Out-of-scope section	Must remain absent in PR diff

Open Questions

None blocking.

[mfittko]

Refinement update for #124 is complete and issue body has been upgraded to assignment-ready scope.

What was clarified

• Converted request into two implementation slices:
  1. Required generic/Ollama llm -> semantic regression test
  2. Preferred OpenAI chat-completions semantic acceptance test
• Added explicit out-of-scope constraints to enforce test-only delivery.
• Added objective validation plan and pass/fail assertions.
• Added proposed DoD (issue had no explicit DoD section).

Key decisions

• Keep OpenAI branch as preferred (per original wording) but include it in refined plan for parity.
• Require asserting rule === "entity_pattern" to prove non-explicit low-confidence rule entry path.
• No production router changes allowed.

Blocker status

• Refinement is complete.
• Remaining blocker to close issue: implementation + test execution evidence.