v0.1.10-5: Add v1/Legacy Dual-Profile and LMCache Gateway Regression Validation

[rickisba]

Background

v0.1.10 now establishes a v1-first LMCache Gateway architecture while preserving the existing Legacy path. The release gate must prove both properties:

1. new CacheRoute capabilities use LMCache-native public interfaces in v1;
2. Legacy startup, Redis injection, request formats, and demos remain available without receiving new v1 functionality.

This Issue validates contracts and Gateway behavior. It does not implement a second cache store or require production policy work.

Objective

Validate the complete v0.1.10 change set across:

• the completed v1 serving baseline;
• resolved v1, legacy, and migration-only auto profiles;
• storage-neutral state and observation models;
• KDN Knowledge/Cache Service contracts;
• LMCache Gateway Profiles and capability discovery;
• token/artifact lookup, tier/adapter observations, operation intents, and structured fallback;
• request and cache-operation traces;
• current Legacy behavior;
• CPU-only test isolation and targeted GPU end-to-end validation.

Test Scope

Runtime Profile Rules

• v1 is the default target for all new features.
• legacy preserves historical behavior and is feature-frozen.
• auto resolves once at startup to an explicit profile and remains fixed.
• A v1 request cannot silently execute a Legacy write path.
• Profile aliases and invalid values behave deterministically.

Existing Legacy Behavior

• Legacy kv_ready metadata and read-only file projection.
• Redis scan/dump/restore/inject.
• Text injection and text-only paths.
• Legacy Instance registration and heartbeat payloads.
• Existing routing and forwarding decisions for compatible inputs.
• Legacy startup smoke tests for Scheduler, KDN, Proxy, and Instance.

v1 State Models

• RuntimeProfile;
• CacheArtifact;
• CacheReplicaObservation;
• LMCacheEndpoint;
• CacheOperationTask;
• QueueWork;
• serialization, immutability, valid/invalid transitions, retryable/terminal states, expiry, profile, and endpoint-generation semantics.

Gateway and Contract Profiles

• Mock MP HTTP Gateway;
• Mock Coordinator Gateway;
• Mock SDK Gateway;
• Mock Metrics/Event Gateway;
• composed v1 Capability Snapshot;
• LegacyCacheAdapter;
• unknown-future Profile;
• token lookup range and matched-coverage representation;
• cache-object and tier/adapter summary representation;
• prefetch, pin/unpin, clear/delete, status, cancellation, and explicit unsupported behavior;
• idempotency and structured fallback;
• proof that domain payloads contain no KV bytes, credentials, raw Redis keys, private LMCache classes, or chunk-index copies.

Trace and Provenance

• text-only, Legacy KV, v1 LMCache-backed KV, unsupported capability, stale observation, endpoint restart, failed/skipped stage, and fallback paths;
• separation of KDN decisions, Gateway invocation, LMCache asynchronous operation, adapter/tier observation, Proxy queueing, and vLLM execution;
• separation of predicted, observed, measured, inferred, stale, unsupported, partial, skipped, and Legacy-projected values.

LMCache-Native Integration

Targeted integration validation should cover:

• current LMCache MP startup and health;
• current vLLM LMCacheMPConnector startup;
• one token/artifact lookup path through the selected public interface;
• one object/tier or adapter observation path;
• one warm prefetch or equivalent supported operation;
• operation status/completion where supported;
• a cold request with no cache read;
• a warm request with actual LMCache hit-token or remote-read evidence;
• deterministic cold-versus-hit output comparison;
• endpoint restart and generation invalidation.

Test Isolation Requirements

• Generic pytest collection performs no external request at module import time.
• Historical scripts requiring live endpoints are explicit integration entry points, guarded by main(), moved outside discovery, or skipped when unavailable.
• CPU-only tests use Mock Gateway and Profile data.
• Core tests require no GPU, live vLLM endpoint, LMCache daemon, Redis service, or external storage system.
• Optional dependencies use documented extras, isolated imports, or explicit skips rather than unrelated collection failures.
• v1 and Legacy test fixtures use separate directories, Redis databases, ports, and environment variables.

Compatibility Matrix Gate

Record rows containing:

• CacheRoute version;
• resolved Runtime Profile;
• vLLM version/profile;
• LMCache version/profile;
• Gateway adapters;
• storage adapters/tiers represented;
• validated operations;
• actual hit-observation mechanism;
• known limitations;
• status: validated, experimental, deprecated, or unsupported.

At minimum, validate:

• the current v1 baseline;
• one Mock future/unknown capability Profile;
• the Legacy Profile;
• one unsupported/incompatible Profile;
• two represented LMCache adapter/tier configurations through mock or integration tests.

Final Acceptance Criteria

• v0.1.10-0: Upgrade CacheRoute Serving Baseline to vLLM 0.25.1 and LMCache 0.5.2 #148 remains complete and the current v1 environment passes dependency and startup checks.
• v1 CacheRoute components start with the documented modern configuration.
• Legacy components start with their documented configuration.
• auto resolves and freezes one explicit profile.
• New optional fields do not break old clients.
• Legacy kv_ready, text injection, Redis scan/dump/restore/inject, and forwarding remain operational.
• New Gateway features are reachable only through v1 or Mock profiles.
• No v1 request silently calls a Legacy write adapter.
• State models conform to v0.1.10-2: Define v1 Runtime, Artifact, LMCache Observation, Operation Task, and Queue State Models #139 and remain storage-neutral.
• Service/Gateway contracts conform to v0.1.10-3: Define Versioned KDN Cache Service Facade and LMCache Gateway Contracts #140 and represent LMCache-native capabilities rather than duplicates.
• Trace output conforms to v0.1.10-4: Add Unified v1 LMCache Gateway, Tier, Adapter, and Queue Observability #141 and preserves Runtime Profile, endpoint generation, adapter/tier, source, and freshness.
• Unknown capability is not treated as supported.
• Actual cache reuse is confirmed by LMCache-native hit-token or remote-read observations in the targeted integration test.
• Generic pytest collection performs no external service call.
• Core unit and contract tests run in CPU-only CI.
• All regressions are fixed or listed as explicit blockers in v0.1.10 Epic: KDN Distribution Infrastructure Contracts and Observability Baseline #137.

Deliverables

• Automated unit and contract tests.
• CPU-only integration/smoke tests using Mock Gateway Profiles.
• A minimal Legacy regression suite.
• A targeted GPU LMCache MP/vLLM/CacheRoute reuse test.
• A machine-readable or Markdown Compatibility Matrix.
• Reproducible Python 3 validation commands.
• CI changes only where required to run the new tests.

Non-Goals

• Performance targets or overlap benchmarks.
• Implementing a KDN physical KV store or data hot path.
• Reimplementing LMCache storage, token lookup, adapter cascades, prefetch, pinning, clearing, or eviction.
• Adding new Legacy features.
• Validating every possible LMCache backend or CUDA/PyTorch combination.
• Replacing GPU-dependent performance benchmarks.

Parent Epic

• v0.1.10 Epic: KDN Distribution Infrastructure Contracts and Observability Baseline #137

Dependencies

• Completed v0.1.10-0: Upgrade CacheRoute Serving Baseline to vLLM 0.25.1 and LMCache 0.5.2 #148
• Completed v0.1.10-1: Add Instance Capability Fingerprints and Compatibility-Aware Registration #138
• v0.1.10-2: Define v1 Runtime, Artifact, LMCache Observation, Operation Task, and Queue State Models #139
• v0.1.10-3: Define Versioned KDN Cache Service Facade and LMCache Gateway Contracts #140
• v0.1.10-4: Add Unified v1 LMCache Gateway, Tier, Adapter, and Queue Observability #141