v0.1.10-2: Define Storage-Neutral Artifact, Replica, DataPlaneTask, and QueueWork State Models

[rickisba]

Background

CacheRoute currently relies on coarse states such as kv_ready and file existence. Explicit lifecycle and task contracts are required before introducing the KDN semantic catalog, LMCache integration adapter, Proxy observed cache view, or ExecutionGraph.

The contracts must not imply that CacheRoute owns a physical KVCache store. LMCache remains the source of truth for physical cache chunks, storage backends, locations, and runtime cache operations.

Objective

Define stable identifiers, immutable serializable state enums, and validated state transitions for:

• logical cache artifacts associated with knowledge and compatibility identity;
• logical cache-replica observations/references to LMCache-managed data;
• LMCache-backed data-operation tasks;
• Proxy queue work items.

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

Implementation Scope

• Define storage-neutral state enums for Artifact, Replica observation, DataPlaneTask, and QueueWork.
• Define stable identifier types or generation rules.
• Document allowed, retryable, and terminal transitions.
• Reject invalid transitions with structured errors and prevent direct mutation from bypassing transition validation.
• Keep all wire values JSON serializable and extensible.
• Define CacheReplica as a logical reference/observation. Fields such as backend type and location key are opaque LMCache or Legacy adapter references, not CacheRoute-owned storage addresses or credentials.
• Provide a read-only mapping from Legacy kv_ready metadata without changing SQLite, files, manifests, injection behavior, or runtime layout.
• Support dictionary records, sqlite3.Row, and attribute-backed records in the Legacy mapper.
• Map normal unbuilt kv_ready=0 knowledge to PENDING; reserve FAILED for confirmed stale or failed observations such as kv_ready=1 with a missing runtime directory.
• Make compatibility uncertainty explicit for Legacy artifacts.
• Document that physical existence, block residency, storage tier, and backend health must later be obtained through LMCache lookup/status/events where available.

Acceptance Criteria

• Each object has a stable ID, explicit state, and immutable transition path.
• Allowed transitions succeed; invalid and terminal transitions fail deterministically with machine-readable details.
• Same-state transitions are idempotent.
• Terminal and retryable states are distinguishable.
• Artifact and Replica models do not contain KV bytes, Redis keys, credentials, serialization details, or CacheRoute-specific block allocation.
• Replica documentation explicitly describes an LMCache-managed logical reference/observation rather than a CacheRoute-owned physical placement.
• Legacy kv_ready rows, including sqlite3.Row, map safely and read-only.
• kv_ready=0 without confirmed files 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, Legacy mapping, and sqlite3.Row handling.

Design Constraints

• New fields remain optional at existing API boundaries during v0.1.10.
• State models are mechanism-focused and contain no scheduling, placement, admission, eviction, or maintenance policy.
• This issue must not implement an LMCache adapter, persistent catalog, Proxy block index, or physical KV store.

Parent Epic

• v0.1.10 Epic: Contract and Observability Baseline #137

Implementation Status

• PR v0.1.10: add storage-neutral cache lifecycle and task state models #147 is the active implementation PR.
• PR [Superseded by #147] v0.1.10 state models placeholder #146 is a superseded Codex placeholder and must not be merged.
• Coordinate compatibility identity with completed v0.1.10-1: Add Instance Capability Fingerprints and Compatibility-Aware Registration #138 and protocol semantics with v0.1.10-3: Define a Versioned LMCache-Aligned KDN Management Protocol #140.