[LightRAG][Step 6] Enable controlled LightRAG retrieval with fallback, caching, and rollback

[rickisba]

Parent Epic: #162
Depends on: #167
Related regression contract: #142

Goal

Allow LightRAG to become the active retrieval backend for explicitly selected traffic after shadow-mode evidence is available, while preserving deterministic fallback, overload protection, and immediate rollback to the embedding backend.

Scope

• Add controlled activation by environment/configuration and, where appropriate, explicit request cohort or deterministic sampling.
• Keep embedding as the safe default until configuration explicitly selects LightRAG.
• Implement bounded retrieval-result caching with a key that includes normalized query identity, retrieval mode, top-k/budget, knowledge index version, and embedding/index fingerprint.
• Define cache invalidation on KDN knowledge/index version changes.
• Add a circuit breaker or equivalent failure-state controller for repeated LightRAG timeouts/errors.
• Preserve fallback order: active LightRAG -> embedding backend -> no knowledge injection.
• Add concurrency limits, queue limits, request timeouts, and overload rejection/skip behavior.
• Expose health and readiness information that distinguishes CacheRoute availability from optional LightRAG backend availability.
• Add explicit rollback configuration that requires no data migration and no Proxy/Instance restart where feasible.
• Validate naive mode first; enable mix mode only through explicit configuration and separate measurements.
• Add bounded retrieval provenance to request trace so downstream results can be attributed to backend, mode, cache hit/miss, fallback, and circuit state.
• Add a detailed deployment/runbook document outside the root README.

Activation Gates

Before LightRAG is recommended as active for broader traffic, evidence must cover:

• retrieval timeout/error rate;
• fallback rate;
• stale/unresolved KID rate;
• p50/p95/p99 retrieval latency;
• answer-quality evaluation on a labeled or reproducible dataset;
• TTFT and E2E impact;
• cross-KDN traffic and injected-token impact;
• rollback behavior under forced LightRAG failure.

The PR must not claim a universal threshold without measured data. Configuration defaults should remain conservative.

Invariants

• Scheduler still selects KDN and Proxy only.
• Proxy still selects a concrete Instance.
• LightRAG failure cannot make the basic inference endpoint unavailable.
• Cache entries cannot outlive the knowledge/index version encoded in their key.
• Circuit-breaker state is observable and bounded.
• Root README content is not replaced or expanded into a full deployment guide.

Non-Goals

• Do not make graph-derived relationships directly control Scheduler routing yet.
• Do not implement Knowledge Demand Profile or joint optimization.
• Do not remove the embedding backend.
• Do not require GPU/CUDA for CPU-only tests.

Acceptance Criteria

• LightRAG can be enabled for controlled traffic and disabled immediately through configuration.
• Result caching is version-aware and covered by invalidation tests.
• Repeated failures open the breaker; recovery/half-open behavior is deterministic and tested.
• Fallback preserves request availability and canonical KID semantics.
• Overload limits prevent unbounded LightRAG work.
• Health endpoints distinguish optional-backend degradation from CacheRoute service failure.
• CPU-only tests cover activation, cache hit/miss/invalidation, timeout, breaker transitions, fallback, overload, recovery, and rollback.
• An end-to-end smoke test demonstrates active LightRAG retrieval through Scheduler, KDN/Proxy routing, Proxy Instance selection, and text or KV injection without changing responsibility boundaries.

Validation

Run focused activation/cache/breaker tests, the complete retrieval suite from Steps 1-5, relevant v1 regression tests, and documented smoke tests. Include actual results in the PR and use Closes #168.