v0.1.10-3: Define Versioned KDN Server Contracts and LMCache Compatibility Profiles

[rickisba]

Background

The revised v0.2.0 architecture positions KDN as an independent server with two stable external interfaces:

1. a CacheRoute-facing Knowledge Management API;
2. an LMCache-facing Remote Cache Serving API.

KDN must support multiple Provider forms and remain compatible with LMCache evolution. LMCache is moving toward MP server mode, asynchronous L1/L2 flows, and plugin-based adapters, while older in-process and remote-connector paths remain relevant for compatibility. CacheRoute therefore needs stable contracts and explicit Compatibility Profiles rather than direct dependence on one LMCache class, module path, HTTP endpoint, or configuration style.

Objective

Define versioned, storage-neutral protocol models for:

• KDN Knowledge Management requests and responses;
• KDN Remote Cache Serving handshake and operation semantics;
• LMCache capability negotiation and Compatibility Profiles;
• Provider capability summaries;
• lookup observations, asynchronous task references, status, cancellation, and structured results;
• protocol/version incompatibility and fallback behavior.

This Issue defines contracts only. The independent KDN Serving Plane MVP belongs to v0.1.12.

Required Contract Families

CacheRoute-Facing Knowledge Management

• register/update/resolve knowledge;
• list compatible Artifacts;
• query observations and KDN serving candidates;
• create placement, prefetch, Pin, clear, refresh, and rebuild intent;
• report request outcome and maintenance status.

LMCache-Facing Remote Cache Serving

• handshake and capabilities;
• Lookup and BatchedLookup;
• Store/Publish;
• Load/Retrieve;
• Prefetch;
• Pin/Unpin;
• Remove/Clear;
• Unlock where required;
• TaskStatus/Completion;
• Health/Metrics.

The contract may describe operations that are unsupported by a specific Profile. Unsupported capability must be explicit.

LMCacheCompatibilityProfile

Define a stable profile containing at least:

• profile_id;
• LMCache version range;
• integration family/mode;
• protocol, key-format, layout, and serde profiles;
• supported operations and batching;
• locking, completion, event, and cancellation models;
• configuration schema version;
• profile status: experimental, validated, default, deprecated, or unsupported.

Initial integration-family vocabulary should support:

• mp_l2_plugin;
• mp_native_plugin;
• remote_storage_plugin;
• controller_api;
• in_process_legacy;
• mock.

Implementation Scope

• Define versioned request/response models and structured error categories.
• Separate KDN Serving Protocol version from LMCache Compatibility Profile.
• Define handshake and capability-negotiation semantics.
• Define unknown-capability behavior; unknown is never treated as supported.
• Define maximum batch, locking/unlock/lease, asynchronous completion, event, and cancellation fields.
• Define observation source, timestamp/freshness, endpoint/provider generation, and confidence.
• Define idempotency rules for logical KDN tasks.
• Keep desired policy intent separate from Provider observations.
• Keep LMCache public-interface details isolated to Compatibility adapters.
• Do not expose raw KV payloads, backend credentials, internal Redis keys, private LMCache objects, or one Provider's serialization.
• Preserve Legacy Redis/file behavior behind an explicit Legacy Profile.
• Provide Mock Profile models suitable for CPU-only CI.

Acceptance Criteria

• Every new contract carries an explicit KDN protocol version.
• Every LMCache-facing connection identifies a Compatibility Profile.
• Unsupported protocol versions and unsupported/unknown capabilities fail with structured outcomes.
• A Profile can express MP L2 Plugin, Native Plugin, Remote Storage Plugin, Controller, Legacy, and Mock modes without changing domain models.
• Repeated task submission with one idempotency key does not create duplicate logical work.
• Lookup/status results identify source, freshness, generation, Provider, and Profile.
• Tests prove that protocol payloads contain no KV binary data, credentials, raw Redis keys, or LMCache private serialized objects.
• Legacy paths remain representable without becoming the default architecture.
• Automated tests cover versioning, negotiation, idempotency, async completion, unsupported capability, stale observation, and secret rejection.

Non-Goals

• Running the production KDN Serving server.
• Implementing Provider I/O, LMCache plugins, or a KDN Connector.
• Implementing a CacheRoute-owned block store, allocator, serde, or physical transfer engine.
• Implementing placement, admission, eviction, or prefetch policy.
• Binding CacheRoute to one LMCache version or private API.

Parent Epic

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

Dependencies

• Completed v0.1.10-1: Add Instance Capability Fingerprints and Compatibility-Aware Registration #138 for Instance capability identity.
• v0.1.10-2: Define Storage-Neutral KDN, Cache Observation, Serving Task, and Queue State Models #139 for storage-neutral object/state vocabulary.
• v0.1.10-4: Add Unified KDN, LMCache, Provider, and Queue-Stage Observability #141 for trace/provenance fields.