v0.1.10-3: Define Versioned KDN Cache Service Facade and LMCache Gateway Contracts #140

Background

The modern v1 stack uses the direct data path:

vLLM <-> LMCacheMPConnector <-> LMCache MP L1/L2 and loaded adapters

Current LMCache already provides token lookup, cache-object and tier management, adapter cascades, prefetch, pin/unpin, clear/delete, capacity/eviction, operation status, metrics, events, and multi-server coordination. CacheRoute must use those capabilities instead of implementing simplified duplicates in KDN.

The revised KDN positioning is:

KDN Server = Knowledge Control Plane + CacheRoute Cache Service Facade + LMCache Orchestration Gateway.

This Issue defines contracts only; it does not implement a second remote KV data plane.

Objective

Define versioned, storage-neutral contracts for:

1. CacheRoute-facing Knowledge and Cache Service APIs;
2. LMCache Gateway capability discovery and invocation;
3. v1, Legacy, Mock, unsupported, and future-version profiles;
4. token/artifact lookup observations, logical cache-operation tasks, status, cancellation, structured errors, and fallback;
5. explicit Runtime Profile and LMCache Compatibility Profile negotiation.

CacheRoute-Facing Contract Families

Knowledge Service

• register/update/resolve knowledge;
• list compatible Artifacts;
• query knowledge and Artifact compatibility;
• report request outcomes and policy feedback.

Cache Service Facade

• GetCacheObservation;
• LookupArtifact;
• LookupTokens;
• CreatePrefetchIntent;
• CreatePinIntent / CreateUnpinIntent;
• CreateClearIntent;
• CreateRebuildIntent;
• GetOperationStatus / CancelOperation where supported;
• GetLMCacheEndpoints;
• GetTierAndAdapterSummary;
• GetMaintenanceStatus.

These interfaces express CacheRoute domain semantics and logical references. They do not carry physical KV payloads or expose private LMCache/Redis objects.

LMCache Gateway Profiles

Define stable Gateway/Profile vocabulary for at least:

• mp_http_api;
• mp_coordinator;
• mp_sdk;
• mp_metrics_events;
• optional mp_l2_plugin when a genuine backend capability gap exists;
• legacy_redis;
• mock;
• unknown_future.

A deployment may compose multiple Gateway adapters behind one immutable LMCacheCompatibilityProfile and CapabilitySnapshot.

Required Capability Model

Represent, when available:

• LMCache version/build identity;
• endpoint generation and runtime mode;
• loaded L1/L2 adapters and order;
• token lookup and lookup range/coverage;
• cache-object listing and deletion;
• warm prefetch and operation status;
• pin/unpin;
• tier capacity and usage;
• eviction/maintenance observability;
• metrics and events;
• batching;
• locking/unlock/lease semantics;
• asynchronous completion and cancellation;
• config, key/hash, layout, serde, chunk-size, and connector profiles.

Unknown capability is never treated as supported.

Implementation Scope

• Define explicit KDN protocol and Gateway/Profile versions.
• Separate CacheRoute domain contracts from concrete LMCache request/response schemas.
• Define startup capability discovery and immutable Capability Snapshot semantics.
• Define version-gated adapters/factories as the only place allowed to know LMCache route names, module paths, private experimental APIs, or response-shape differences.
• Represent token sequences or opaque token references without reproducing LMCache Token Database or Chunk Key generation.
• Define source, endpoint, adapter/tier, timestamp/freshness, generation, and confidence on observations.
• Define idempotency for logical CacheOperationTask submission.
• Define unsupported, incompatible, stale, partial, failed, cancelled, and explicit text-fallback outcomes.
• Make v1 the only target for new Gateway capabilities.
• Keep Legacy behind an explicit LegacyCacheAdapter; no v1 operation may silently use a Legacy write path.
• Treat auto as startup profile resolution, not an operation-time fallback mechanism.
• Provide Mock Gateway contracts suitable for CPU-only CI.

Acceptance Criteria

• Every new message carries an explicit CacheRoute/KDN contract version and resolved Runtime Profile.
• Every v1 LMCache operation identifies an LMCache Compatibility Profile and endpoint generation.
• The contracts can represent token lookup, cache observation, prefetch, pin/unpin, clear/delete, object/tier summaries, and operation status without implementing those mechanisms in CacheRoute.
• MP HTTP, Coordinator, SDK, Metrics/Event, Mock, Legacy, and unknown-future profiles are representable without changing domain models.
• Unsupported/unknown capability fails explicitly and can select a documented text fallback.
• Repeated operation submission with one idempotency key does not create duplicate logical CacheRoute work.
• Observations identify source, freshness, generation, adapter/tier, Runtime Profile, and LMCache Profile where available.
• Tests prove that payloads contain no KV binary data, credentials, raw Redis keys, private LMCache serialized objects, or physical chunk-index copies.
• A v1 request cannot silently execute through legacy_redis.
• Legacy remains representable and operational without receiving new v1 functionality.
• Automated tests cover versioning, profile resolution, capability discovery, token lookup representation, idempotency, async completion, unsupported capability, stale observation, fallback, and secret rejection.

Non-Goals

• Implementing another KDN remote KV server on the vLLM/LMCache hot path.
• Reimplementing LMCache Token Database, key/hash generation, L1/L2 StorageManager, adapter cascades, Store/Prefetch Controller, pinning, clearing, capacity accounting, serde, locks, or eviction.
• Implementing production Gateway I/O in this contract Issue.
• Adding new functionality to Legacy.
• Implementing placement, admission, cache-value, or queue policy.
• Binding CacheRoute to one LMCache private API or source-tree layout.

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 v1 runtime baseline.
• Completed v0.1.10-1: Add Instance Capability Fingerprints and Compatibility-Aware Registration #138 Instance capability identity.
• v0.1.10-2: Define v1 Runtime, Artifact, LMCache Observation, Operation Task, and Queue State Models #139 state and object vocabulary.
• v0.1.10-4: Add Unified v1 LMCache Gateway, Tier, Adapter, and Queue Observability #141 trace/provenance vocabulary.