feat(kdn): define versioned cache service and LMCache gateway contracts

kdn_server/README.md

@@ -426,3 +426,22 @@ The batch script is useful for preparing knowledge-intensive workloads used in C
 - The standalone `kv_injector.py` path is mainly for debugging. In the full CacheRoute workflow, KVCache injection should be triggered by the scheduling and KDN matching process.
 - Some paths and model names in the examples should be adjusted according to your local deployment.
 - For full deployment with vLLM, LMCache, Redis, Scheduler, Proxy, and Instance, see the main `README.md`.
+
+## Versioned control-plane contracts
+
+The v0.1.10 versioned control-plane layer supplements the operational KDN
+workflows documented above. It defines storage-neutral domain objects,
+versioned Knowledge and Cache Service messages, explicit
+Runtime/Profile/Endpoint negotiation, immutable capability discovery, a
+CPU-only Mock Gateway, and a read-only Legacy adapter. It does not replace the
+existing KDN HTTP service, CLI, text database, KV construction, injection
+workflow, Redis integration, or LMCache data path. Production LMCache HTTP,
+Coordinator, SDK, Redis, and KV data movement are not implemented by this
+contract layer.
+
+Detailed references:
+
+- [Domain vocabulary](domain/README.md)
+- [Service contracts](contracts/README.md)
+- [Gateway architecture](gateway/README.md)
+- [CPU-only tests and workflows](../test/kdn/README.md)

kdn_server/contracts/README.md

@@ -0,0 +1,73 @@
+# Versioned KDN service contracts
+
+[Back to the KDN architecture](../README.md) · [Shared domain vocabulary](../domain/README.md) · [Gateway architecture](../gateway/README.md) · [Executable workflows](../../test/kdn/README.md)
+
+The contracts package is the storage-neutral public wire layer. Definitions live in [`common.py`](common.py), [`knowledge.py`](knowledge.py), [`cache_service.py`](cache_service.py), and [`errors.py`](errors.py); the stable import surface is [`__init__.py`](__init__.py).
+
+## Contract versions and evolution
+
+- `KDN_CONTRACT_VERSION = "kdn.v1"`
+- `GATEWAY_CONTRACT_VERSION = "lmcache-gateway.v1"`
+
+Enum wire values and existing field meanings are stable. Unsupported versions are rejected explicitly. Additive evolution should use compatible optional fields when semantics remain unchanged; otherwise introduce a new contract version. Never silently reinterpret a persisted field.
+
+## Common envelope
+
+Every versioned message carries a resolved `runtime_profile`, `request_id`, optional `correlation_id`, and timezone-aware UTC timestamp. Models are frozen Pydantic models with `extra="forbid"`, and validation rejects startup-only `auto`. Unknown fields therefore cannot smuggle backend-specific or sensitive state across the boundary.
+
+Gateway-targeted requests and responses additionally require a non-empty `compatibility_profile_id`, canonical `endpoint_id`, and endpoint generation. The target makes negotiation reproducible:
+
+- Runtime/Profile/Endpoint mismatch → `incompatible`;
+- generation mismatch → `stale`;
+- unknown or unsupported capability → `unsupported`.
+
+Legacy may use generation `0` for unknown; v1 and test/mock require a positive generation.
+
+## Knowledge Service families
+
+[`knowledge.py`](knowledge.py) defines storage-neutral contracts to register, update, and resolve knowledge; list compatible artifacts; query artifact compatibility; and report request outcomes. These are contracts only—this package does not register HTTP routes or prescribe a database.
+
+## Cache Service families
+
+[`cache_service.py`](cache_service.py) defines dedicated request and response families for artifact lookup, cache observation, token lookup, prefetch, pin/unpin, clear, rebuild, operation status and cancellation, endpoint discovery, tier/adapter summaries, and maintenance status.
+
+Dedicated responses validate their expected success payload, target provenance, observation freshness, operation provenance, intent-specific operation type, and terminal cancellation no-op semantics. The outcome vocabulary is `success`, `unsupported`, `incompatible`, `stale`, `partial`, `failed`, `cancelled`, `text_fallback`, and `idempotency_conflict`. Every non-success response carries a matching safe `ContractErrorDetail`.
+
+## Token contracts
+
+`TokenInput` accepts exactly one of an immutable tuple of token IDs or an opaque `TokenReference`. `TokenCoverage.whole_request_hit` represents whole-request hit/miss independently from `covered_ranges`; exact ranges are exposed only when `range_coverage` is explicitly supported. This layer does not implement LMCache hashing, chunk keys, token databases, serialization, or block allocation.
+
+## Security and storage neutrality
+
+Contracts prohibit credentials, API keys, authorization headers, raw Redis keys, KV bytes, tensors, device pointers, physical chunk/block indexes, and private serialized LMCache objects. Structured errors contain stable codes and safe messages—not backend exceptions.
+
+## Minimal examples
+
+```python
+from kdn_server.contracts import LookupArtifactRequest, LookupTokensRequest, TokenInput
+
+TARGET = {
+    "runtime_profile": "test/mock",
+    "compatibility_profile_id": "example-compatible-v1",
+    "endpoint_id": "endpoint_" + "1" * 32,
+    "endpoint_generation": 1,
+}
+artifact_request = LookupArtifactRequest(
+    **TARGET,
+    artifact_id="artifact_" + "2" * 32,
+)
+token_request = LookupTokensRequest(
+    **TARGET,
+    tokens=TokenInput(token_ids=(11, 12, 13)),
+)
+```
+
+Inspect outcomes without parsing backend-specific payloads:
+
+```python
+response = gateway.lookup_tokens(token_request)
+if response.outcome.value == "text_fallback":
+    assert response.error.fallback_eligible
+```
+
+For complete, executable Mock and Legacy sequences, continue to the [CPU-only workflow guide](../../test/kdn/README.md).

kdn_server/contracts/__init__.py

@@ -0,0 +1,44 @@
+"""Stable public KDN versioned service contract API."""
+from .common import (ContractModel, GATEWAY_CONTRACT_VERSION, GatewayTargetedRequest,
+    KDN_CONTRACT_VERSION, SupportState, TokenInput, TokenReference, VersionedMessage)
+from .errors import ContractError, ContractErrorDetail, OutcomeCode
+from .knowledge import (KnowledgeDescriptor, KnowledgeResponse, ListCompatibleArtifactsRequest,
+    ListCompatibleArtifactsResponse, QueryArtifactCompatibilityRequest,
+    QueryArtifactCompatibilityResponse, RegisterKnowledgeRequest, RegisterKnowledgeResponse,
+    ReportRequestOutcomeRequest, ReportRequestOutcomeResponse, ResolveKnowledgeRequest,
+    ResolveKnowledgeResponse, UpdateKnowledgeRequest, UpdateKnowledgeResponse)
+from .cache_service import (AdapterSummary, ArtifactRequest,
+    CancelOperationRequest, CancelOperationResponse, CapacityUsageObservation,
+    CreateClearIntentRequest, CreateClearIntentResponse, CreatePinIntentRequest,
+    CreatePinIntentResponse, CreatePrefetchIntentRequest, CreatePrefetchIntentResponse,
+    CreateRebuildIntentRequest, CreateRebuildIntentResponse, CreateUnpinIntentRequest,
+    CreateUnpinIntentResponse, GetCacheObservationRequest, GetCacheObservationResponse,
+    GetLMCacheEndpointsRequest, GetLMCacheEndpointsResponse, GetMaintenanceStatusRequest,
+    GetMaintenanceStatusResponse, GetOperationStatusRequest, GetOperationStatusResponse,
+    GetTierAndAdapterSummaryRequest, GetTierAndAdapterSummaryResponse,
+    LookupArtifactRequest, LookupArtifactResponse, LookupTokensRequest, LookupTokensResponse,
+    MaintenanceSummary, OperationIntentRequest, SummaryBase, TierLevel,
+    TierSummary, TokenCoverage)
+
+__all__ = [
+    "KDN_CONTRACT_VERSION", "GATEWAY_CONTRACT_VERSION", "ContractModel", "VersionedMessage",
+    "GatewayTargetedRequest", "SupportState", "TokenReference", "TokenInput", "OutcomeCode",
+    "ContractErrorDetail", "ContractError", "KnowledgeDescriptor",
+    "KnowledgeResponse", "RegisterKnowledgeRequest", "RegisterKnowledgeResponse",
+    "UpdateKnowledgeRequest", "UpdateKnowledgeResponse", "ResolveKnowledgeRequest",
+    "ResolveKnowledgeResponse", "ListCompatibleArtifactsRequest", "ListCompatibleArtifactsResponse",
+    "QueryArtifactCompatibilityRequest", "QueryArtifactCompatibilityResponse",
+    "ReportRequestOutcomeRequest", "ReportRequestOutcomeResponse", "ArtifactRequest",
+    "GetCacheObservationRequest", "LookupArtifactRequest", "LookupTokensRequest",
+    "OperationIntentRequest", "CreatePrefetchIntentRequest", "CreatePinIntentRequest",
+    "CreateUnpinIntentRequest", "CreateClearIntentRequest", "CreateRebuildIntentRequest",
+    "GetOperationStatusRequest", "CancelOperationRequest", "GetLMCacheEndpointsRequest",
+    "GetTierAndAdapterSummaryRequest", "GetMaintenanceStatusRequest", "TokenCoverage",
+    "SummaryBase", "AdapterSummary", "TierLevel", "CapacityUsageObservation", "TierSummary",
+    "MaintenanceSummary", "GetCacheObservationResponse",
+    "LookupArtifactResponse", "LookupTokensResponse",
+    "CreatePrefetchIntentResponse", "CreatePinIntentResponse", "CreateUnpinIntentResponse",
+    "CreateClearIntentResponse", "CreateRebuildIntentResponse", "GetOperationStatusResponse",
+    "CancelOperationResponse", "GetLMCacheEndpointsResponse", "GetTierAndAdapterSummaryResponse",
+    "GetMaintenanceStatusResponse",
+]