v0.1.10 Epic: KDN Contracts, LMCache Compatibility, and Observability Baseline

[rickisba]

Objective

Deliver the v0.1.10 runtime, contract, and observability foundation required by the revised v0.2.0 roadmap.

The long-term architecture is:

KDN Server = Knowledge Control Plane + LMCache-Compatible Remote Cache Serving Plane.

KDN remains an independently deployable CacheRoute server. It provides knowledge semantics and policy to CacheRoute and remote-cache serving operations to LMCache. It must not be identified with Redis or implement a second general-purpose KVCache storage engine.

Runtime Baseline

Before implementing the remaining contracts, CacheRoute must establish a current serving baseline through #148:

• target: Python 3.12, CUDA 13.0, PyTorch 2.11.0, vLLM 0.25.1, and LMCache 0.5.2;
• known-good rollback/reference: vLLM 0.25.1 with LMCache 0.5.1;
• latest target versions become officially supported only after clean dependency resolution, CacheRoute startup, and end-to-end LMCache MP cache-reuse validation;
• generic CacheRoute requirements must not downgrade or replace the ABI-sensitive serving stack.

All later v0.1.10 contracts should be designed and tested against this baseline rather than the previous vLLM 0.13.x / LMCache 0.3.x environment.

Architectural Alignment

• KDN Knowledge Control Plane owns KnowledgeObject identity/version, CacheArtifact compatibility, desired state, policy, and historical value.
• KDN Remote Cache Serving Plane exposes backend-neutral Lookup, Store, Load/Retrieve, and asynchronous task semantics to LMCache.
• KDN Provider Compatibility Layer isolates LMCache version/mode and concrete Provider differences.
• LMCache/Provider runtime owns physical KV bytes, chunking, layout, serde, low-level transfer, and physical object observations.
• Proxy KVCache Management is a short-lived observed execution view and does not copy an authoritative chunk index.
• Redis and filesystem injection remain Legacy or early validation Providers only.

v0.1.10 defines contracts only after establishing the current serving baseline. The independent KDN Serving Plane MVP is planned for v0.1.12, and multi-Provider/LMCache evolution compatibility is planned for v0.1.13.

Scope and Status

• v0.1.10-0: Upgrade CacheRoute Serving Baseline to vLLM 0.25.1 and LMCache 0.5.2 #148 Upgrade the CacheRoute serving baseline to vLLM 0.25.1 and LMCache 0.5.2, including dependency compatibility and MP validation.
• v0.1.10-1: Add Instance Capability Fingerprints and Compatibility-Aware Registration #138 Add Instance capability fingerprints and compatibility-aware registration.
• v0.1.10-2: Define Storage-Neutral KDN, Cache Observation, Serving Task, and Queue State Models #139 Define storage-neutral KDN, cache-observation, serving-task, and queue state models.
• v0.1.10-3: Define Versioned KDN Server Contracts and LMCache Compatibility Profiles #140 Define versioned KDN Server contracts and LMCache Compatibility Profiles.
• v0.1.10-4: Add Unified KDN, LMCache, Provider, and Queue-Stage Observability #141 Add unified tracing across KDN Serving, Provider, LMCache, Proxy, and vLLM stages.
• v0.1.10-5: Add Cross-Profile Regression and Backward-Compatibility Validation #142 Add v0.1.10 regression, compatibility-profile, and backward-compatibility validation.

No active PR is treated as the implementation baseline for #139–#142. Each Issue should be implemented independently from its current specification after #148 establishes the runtime dependency baseline.

Required v0.1.10 Contracts

• validated serving-stack version and dependency profile;
• Instance Capability;
• CacheArtifact and CacheReplicaObservation;
• KDNServingEndpoint;
• KDNServingTask;
• LMCacheCompatibilityProfile;
• QueueWork;
• protocol-version and capability-negotiation vocabulary;
• stable Trace stages and source/provenance fields;
• Legacy kv_ready and Redis compatibility mapping.

Release Acceptance Criteria

• The target vLLM/LMCache/PyTorch stack resolves in a clean Python 3.12 environment and passes pip check.
• CacheRoute application requirements do not downgrade or conflict with the serving stack.
• LMCache MP and vLLM LMCacheMPConnector complete a deterministic cold-versus-cache-hit validation.
• Incompatible Instance or Artifact reuse is rejected with a structured reason.
• Core objects contain no KV bytes, backend credentials, raw Redis keys, or LMCache private classes.
• CacheRoute-facing Knowledge Management and LMCache-facing Remote Cache Serving contracts are explicitly separated.
• LMCache Compatibility Profiles can represent MP L2 Plugin, Native Plugin, Remote Storage Plugin, Legacy, Mock, and unknown capability sets.
• Unknown capability is never interpreted as supported.
• Predicted, observed, measured, inferred, stale, and unsupported trace values are distinguishable and identify their source.
• Existing text injection, Legacy KV injection, registration, forwarding, and demo startup remain compatible.
• Core tests run in CPU-only CI without a GPU, live vLLM endpoint, Redis service, or LMCache cluster.

Non-Goals

• Implementing the independent production KDN Serving Plane.
• Implementing a CacheRoute-owned block store, allocator, serde, or physical eviction engine.
• Binding KDN to Redis or one LMCache private API.
• Tracking nightly or unreleased vLLM/LMCache branches as the stable baseline.
• Implementing the full Proxy KVCache Manager or ExecutionGraph scheduler.
• Changing routing or cache-placement policy.

Delivery Order

1. v0.1.10-0: Upgrade CacheRoute Serving Baseline to vLLM 0.25.1 and LMCache 0.5.2 #148 current serving-stack and dependency baseline
2. v0.1.10-1: Add Instance Capability Fingerprints and Compatibility-Aware Registration #138 capability fingerprints — complete and revalidated on the new stack
3. v0.1.10-2: Define Storage-Neutral KDN, Cache Observation, Serving Task, and Queue State Models #139 storage-neutral states and logical objects
4. v0.1.10-3: Define Versioned KDN Server Contracts and LMCache Compatibility Profiles #140 dual KDN contracts and LMCache Compatibility Profiles
5. v0.1.10-4: Add Unified KDN, LMCache, Provider, and Queue-Stage Observability #141 trace and provenance
6. v0.1.10-5: Add Cross-Profile Regression and Backward-Compatibility Validation #142 regression and compatibility-profile validation

Each subtask must be independently testable and must keep business logic out of demo_*.py.