[enhancement] Add adaptive routing, degradation, and the production retrieval service #866

Phase 3 of Parent epic: #863

Summary

Complete the decision and serving layer on top of the Phase 2 retrieval core. Implement a
deterministic rule-based Adaptive Hybrid policy, explicit budget and failure semantics, and a versioned Solon REST adapter that upper-layer applications can call directly.

The REST contract established in Phase 1 is the compatibility boundary. This issue adds production behavior and operational safeguards without renaming or removing its core fields.

Motivation

Different queries need different retrieval work. A fixed strategy can waste latency and token budget on simple queries or fail to explore difficult multi-hop questions. In addition, the current service prototype does not expose a stable, typed retrieval endpoint with readiness, observability, and degradation semantics.

Scope

• Implement immutable RoutingContext, RetrievalPlan, and RetrievalProgress models.
• Implement DeterministicRulePolicy using query length, average IDF, first-stage score gap, anchor count/confidence, candidate degree, and graph growth rate.
• Validate every plan against hard limits, available indexes, supported hop count, and configured fallback rules before execution.
• Add optional bounded replanning at stage boundaries with a configured maxReplanCount.
• Implement typed failures for invalid requests, missing graphs, unavailable indexes, timeouts, unsupported options, and internal errors. Hybrid fallback must preserve completed evidence and record the degraded channels and reason codes.
• Add POST /api/v1/retrievals to the existing Solon service. Support request IDs via
  X-Request-Id, server defaults, graph/index version selection, mode, optional query vectors, topK, timeout, and candidate/token budgets.
• Add /health, /ready, and a machine-readable metrics endpoint or metrics integration consistent with existing GeaFlow service conventions.
• Add structured logs containing request ID, graph/version, selected mode, effective budgets, channel work, result count, latency, status, and degradation reason.
• Provide a runnable upper-layer HTTP example using curl or a small client.

Suggested implementation locations

• geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/policy/ - routing context, rule policy, plan validation, and bounded replanning.
• geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/service/ - orchestration, error mapping, readiness, trace, and metrics.
• geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/api/ - Solon controllers and HTTP DTOs.
• geaflow-ai/src/main/resources/application.yml - versioned defaults and hard limits.
• geaflow-ai/src/test/java/org/apache/geaflow/ai/retrieval/ - policy, service, contract, and HTTP integration tests.

Testing requirements

• Unit tests for feature extraction, rule boundaries, plan validation, fallback, and replan limits.
• Service tests for each typed error, timeout behavior, request ID propagation, effective budgets, graph versions, and non-null response collections.
• Solon HTTP contract tests for success, empty result, failure, readiness, and metrics responses.
• Regression tests proving all existing /query/* behavior remains available.

Dependencies and follow-up

• Later policy implementations may be added behind AdaptivePolicy without changing the REST API.