v0.1.10-2: Define v1 Runtime, Artifact, LMCache Observation, Operation Task, and Queue State Models

[rickisba]

Background

CacheRoute now has explicit v1, legacy, and migration-only auto runtime profiles. The remaining v0.1.10 models must reflect the modern LMCache MP architecture without breaking the Legacy path.

The v1 boundary is:

KDN owns knowledge and logical operation semantics; LMCache owns token/chunk/key generation, physical KV objects, L1/L2 residency, adapters, serde, locks, transfer, capacity, and eviction.

The models must not turn CacheRoute into a second physical cache implementation.

Objective

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

• RuntimeProfile — resolved execution profile; persisted values are v1, legacy, or test/mock, while auto is startup input rather than a long-lived domain state;
• CacheArtifact — logical knowledge materialization identity;
• CacheReplicaObservation — TTL-bound observation/reference to LMCache-managed data;
• LMCacheEndpoint — logical identity and generation of an LMCache MP/Coordinator/Gateway target;
• CacheOperationTask — logical Lookup/Prefetch/Pin/Clear/Rebuild or observation task;
• QueueWork — Proxy-local execution work state.

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

Implementation Scope

• Define stable wire-format enums and identifiers.
• Document allowed, idempotent, retryable, and terminal transitions.
• Reject invalid transitions with structured errors and prevent direct mutation from bypassing transition validation.
• Keep desired state separate from observed state.
• Require physical observations to carry source, endpoint, Runtime Profile, LMCache Profile, adapter/tier where known, timestamp, expiry/freshness, endpoint generation, and confidence.
• Define CacheReplicaObservation as an opaque short-lived logical observation; it is not a CacheRoute-owned physical replica record.
• Define LMCacheEndpoint without binding domain identity to one HTTP route, Python class, Redis backend, or LMCache source-tree layout.
• Define CacheOperationTask without embedding Provider credentials, physical KV payloads, raw Redis keys, or LMCache-private request objects.
• Make v1 the default target for all new state and operation semantics.
• Keep Legacy mappings read-only and explicit, including compatibility uncertainty.
• Treat auto as startup resolution input; once resolved, the process profile is immutable.
• Provide read-only Legacy kv_ready mapping without changing SQLite, files, manifests, injection behavior, or runtime layout.

Acceptance Criteria

• Every object has a stable ID and explicit state.
• Allowed transitions succeed; 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, credentials, private serialization, block allocators, or LMCache-private classes.
• Observed state cannot be confused with desired state.
• CacheReplicaObservation can expire stale physical facts and records LMCache endpoint/profile provenance.
• LMCacheEndpoint can represent MP HTTP, Coordinator, SDK, Metrics/Event, Mock, and Legacy Gateway profiles without changing its identity model.
• auto cannot appear as a persisted active operation profile after startup resolution.
• A v1 task cannot transition into a Legacy write operation implicitly.
• Legacy kv_ready records map safely and read-only; normal unbuilt knowledge maps to pending rather than failed.
• Existing Legacy Redis/file paths remain operational.
• Unit tests cover transitions, immutability, serialization, ID stability, secret rejection, expiry, endpoint generation, profile resolution, and Legacy mapping.

Design Constraints

• New fields remain optional at existing Legacy API boundaries during v0.1.10.
• State models contain no routing, admission, cache-value, eviction, prefetch, or maintenance policy.
• This Issue does not implement the LMCache Gateway, KDN cache-service endpoints, a persistent Artifact catalog, a Proxy block index, or a physical KV store.
• New implementation targets v1; Legacy receives projection and regression support only.

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 for the v1 serving baseline.
• Completed v0.1.10-1: Add Instance Capability Fingerprints and Compatibility-Aware Registration #138 for Instance capability identity.
• Coordinate Gateway/Profile vocabulary with v0.1.10-3: Define Versioned KDN Cache Service Facade and LMCache Gateway Contracts #140.
• No closed PR is treated as the implementation baseline.