v0.1.10-2: Define Storage-Neutral KDN, Cache Observation, Serving Task, and Queue State Models

[rickisba]

Background

CacheRoute currently relies on coarse states such as kv_ready, file existence, and request-local flags. The revised v0.2.0 roadmap requires stable state contracts before implementing the KDN Knowledge Control Plane, the independent KDN Remote Cache Serving Plane, LMCache Compatibility Profiles, Proxy observations, or ExecutionGraph.

These models must preserve the architectural boundary:

KDN is an independent knowledge-aware remote cache server, but CacheRoute does not define a second physical KVCache storage engine.

Objective

Define stable identifiers, immutable serializable states, and validated transitions for:

• CacheArtifact — logical knowledge materialization identity;
• CacheReplicaObservation — time-bounded observation/reference to Provider-managed data;
• KDNServingEndpoint — logical identity and health state for a KDN serving endpoint;
• KDNServingTask — asynchronous KDN serving or maintenance operation record;
• QueueWork — Proxy-local execution work state.

Preserve the current Legacy KV path as a read-only compatibility projection.

Implementation Scope

• Define stable wire-format state enums and IDs.
• Document allowed, idempotent, retryable, and terminal transitions.
• Reject invalid transitions with structured errors.
• Prevent direct mutation from bypassing transition validation.
• Keep all models JSON serializable and policy-neutral.
• Keep desired state separate from observed state.
• Require observations to support source, timestamp, expiry/freshness, generation, and confidence fields where applicable.
• Define CacheReplicaObservation as an opaque logical reference; it is not a CacheRoute-owned physical placement record.
• Define KDNServingEndpoint without binding it to Redis, one Provider, one LMCache mode, or one endpoint implementation.
• Define KDNServingTask without embedding Provider credentials, physical KV payloads, or LMCache private request objects.
• Provide read-only Legacy kv_ready mapping without changing SQLite, files, manifests, injection behavior, or runtime layout.
• Make Legacy compatibility uncertainty explicit.

Acceptance Criteria

• Every object has a stable ID and explicit state.
• Allowed transitions succeed and invalid transitions fail deterministically with machine-readable details.
• Same-state transitions are idempotent.
• Retryable and terminal states are distinguishable.
• Models contain no KV bytes, raw Redis keys, connection credentials, serialization blobs, block allocators, or LMCache private classes.
• Observed state cannot be confused with desired state.
• CacheReplicaObservation includes enough provenance to expire stale physical observations.
• KDNServingEndpoint can later represent MP L2 Plugin, Native Plugin, Remote Storage Plugin, Legacy, or Mock integration Profiles without changing its identity model.
• Legacy kv_ready rows map safely and read-only; normal unbuilt knowledge maps to pending rather than failed.
• Existing Legacy Redis and file-based paths remain operational.
• Unit tests cover transitions, immutability, serialization, ID stability, secret rejection, observation expiry fields, and Legacy mapping.

Design Constraints

• New fields remain optional at existing API boundaries during v0.1.10.
• State models contain no routing, placement, admission, eviction, prefetch, or maintenance policy.
• This Issue does not implement the KDN Serving server, an LMCache adapter, a persistent Artifact catalog, Proxy block index, or physical KV store.

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.
• Coordinate protocol/profile vocabulary with v0.1.10-3: Define Versioned KDN Server Contracts and LMCache Compatibility Profiles #140.
• No active PR is treated as the implementation baseline for this Issue.