Complete Gateway RAG request orchestration and executable acceptance #34

Goal

Complete the Gateway-owned, bounded RAG request workflow and prove it through executable acceptance before expanding source ingestion or adding client adapters.

Current implementation audit (revalidated against main, 2026-10-29)

The earlier audit below was stale and has been replaced with these findings:

Implemented on main

• POST /api/v1/requests is dispatched by runtime/server.py to GatewayService.search.
• Gateway resolves and pins the active Index generation/profile bundle.
• Intent classification and entity extraction run concurrently.
• Lexical and vector retrieval run concurrently through REST.
• Candidate source revisions are verified through Memory/Knowledge REST endpoints before Ranking.
• Ranking is invoked through REST; the Gateway returns provenance, freshness state, degradation metadata, and bounded context.
• Read-your-writes operation polling exists.
• Tests include mocked Gateway orchestration, an HTTP request-route test, and a durable SQLite-backed integration test that exercises real Knowledge, Index, retrieval, freshness, and Ranking handlers. The test suite is therefore not wholly mocked, but it does not yet prove the complete Graph/Reranking workflow.

Confirmed contract gaps

1. Graph orchestration is absent from GatewayService.search. The contract requires Graph traversal for relationship_exploration and explicit relationship requests, concurrent with retrieval. Graph resolution evidence and edge supports must share the canonical verification budget with text candidates. No Graph request or Graph evidence is currently produced by this path.
2. Reranking is absent from GatewayService.search. The contract requires preserving exact-match candidates in Ranking order, reranking only non-exact candidates (maximum 20), validating identity/provenance preservation, and falling back to Ranking order with explicit partial/degraded status on failure.
3. Stage budgets are not enforced. The inbound absolute deadline is propagated, but calls default to 30 seconds and the implementation does not enforce the contract's separate planning (100 ms), retrieval (350 ms), Graph (250 ms), freshness (250 ms), Ranking (150 ms), Reranking (250 ms), and assembly (100 ms) budgets. The hook's 1,500 ms total deadline is not enough by itself to prove those reserved ceilings.
4. Context budgeting is not provider-token correct. Assembly estimates each candidate as ceil(len(text)/4), ignores the requested model, and does not report a conservative estimate in the response metadata. The contract requires provider-model token counting when available and an explicitly identified conservative estimate otherwise. The current estimate also does not account for the source/provenance wrapper added to context.
5. Degradation semantics need tightening. In particular, a successful empty result must remain distinguishable from required retrieval/freshness failure; Ranking failure must not be represented as a successful empty Ranking result; and truncation/freshness filtering must be reflected consistently in status and response metadata.
6. Executable acceptance is incomplete. The existing durable HTTP integration test proves a useful subset (Knowledge → Index → lexical/vector retrieval → canonical freshness → Ranking). It does not exercise Graph traversal/support verification, Reranking, per-stage deadlines/cancellation, required relationship intent, or the complete degradation matrix.
7. Traceability currently maps Gateway acceptance IDs to specifications but does not identify the concrete executable test functions for the complete workflow. Update it as tests are added; do not label a specification as executed coverage.

Required sequence

1. Implement the missing Graph and Reranking stages in Gateway using only logical service REST calls.
2. Enforce one absolute request deadline plus non-borrowable per-stage ceilings and bounded cancellation behavior.
3. Correct context budgeting: use a configured tokenizer for the named model when available; otherwise use a documented conservative estimator and expose that fact. Never claim a provider-token count when only an estimate exists.
4. Correct degradation/status handling for retrieval, freshness, Ranking, Graph, Reranking, and assembly.
5. Extend the durable REST-dispatcher integration test with Graph and Reranking services and durable source/index data. Include required relationship intent, Graph support freshness, reranker identity preservation, and service failures.
6. Add executable cases for empty evidence, partial dependency failure, deadline exhaustion, scope isolation, provenance, deterministic ordering, and bounded context.
7. Update docs/TRACEABILITY.md with concrete test names and distinguish executed coverage from remaining release gates.

Constraints

• REST contracts remain canonical. No direct cross-service implementation calls or cross-owned storage access.
• Do not make RAG a separate deployable service yet; keep it a named, independently testable Gateway-owned capability.
• Do not couple RAG to MCP, Claude Code hooks, a particular model provider, or a particular editor.
• Do not use this issue to expand source format support.
• Keep existing fail-closed Index generation/cutover guarantees intact.
• Do not relax normative contract requirements merely to match current implementation.
• SonarCloud is deliberately excluded from this work.

Acceptance criteria

• Client requests traverse Gateway planning, lexical/vector retrieval, Graph when required, canonical evidence verification, Ranking, optional Reranking, and context assembly through REST contracts only.
• Graph entity-resolution evidence and edge supports are verified against canonical owners before any Graph path is returned.
• Exact-match candidates retain their required primary tier and are never silently dropped by Reranking or context assembly when they fit the budget.
• Every stage obeys its reserved deadline; no service extends the caller's absolute deadline.
• Context never exceeds the requested budget; token-count method/estimate is explicit.
• Integration tests exercise the actual REST dispatcher and durable data, proving success, empty evidence, partial dependency failure, timeout, scope isolation, and provenance.
• Missing/failed required dependencies cannot silently produce a false successful result.
• Traceability links acceptance cases to executable tests by name.
• CI passes, excluding the deliberately deferred SonarCloud check.

Deferred

• PR Add format-aware source ingestion adapters #31 (source-ingestion adapters) remains blocked until this issue's Gateway/RAG acceptance passes.
• PR Defer Index profile registry pending real integration #11 (Index profile registry) remains deferred; it is not required for the current single-instance workflow.
• MCP/client adapters and hook lifecycle integration remain later gates, after the Gateway request path is stable.