KC cache task

.scratch/alpha-hardening/prd.json

@@ -503,9 +503,30 @@
       "notes": "Source issue: .scratch/alpha-hardening/issues/24-routing-telemetry-resume.md. Resume task for interrupted 2026-07-07 Claude session; first known fix is server.py:1490 annotation crash.",
       "dependsOn": [],
       "completionNotes": ""
+    },
+    {
+      "id": "AH-025",
+      "title": "25 — Sharded per-node KV cache for distributed generation (MoE/hybrid-attention aware)",
+      "description": "Status: ready-for-agent\n\nScoped 2026-07-08 from a live two-machine distributed-inference debugging session. The ADR-0020 mixed-topology start_layer bug is fixed (518c259, e44abc9, 1ecc599); this is the next performance blocker in the same path. The distributed generation loop has NO KV cache at all: model_backend.py passes use_cache: False in every layer-forward call, and each autoregressive step re-encodes the entire prompt-so-far from scratch, re-running every layer on every node in the route for every generated token. Observed on a live 2-node Qwen2.5-0.5B GPU pipeline: tps decayed from 22.3 (at 235 output tokens) to 12.6 (at 449 tokens) within a single generation, the expected quadratic-cost signature. X-Meshnet-Session already exists on the wire but is minted fresh per token and only labels one activation transfer for chunk reassembly/logging, not keyed to any cached state. Build: (1) stable per-request session lifecycle instead of per-token, (2) per-node sharded cache keyed by session scoped to that node's own layer range only, (3) prefill-vs-decode split so post-prefill steps send only the newest token's activation, (4) cache abstraction that holds whatever use_cache=True returns per layer range (not K/V-shaped-only) because Qwen3.6's hybrid linear-attention layers cache recurrent conv/delta state, not standard K/V, (5) TTL+LRU eviction with an explicit cache-miss fallback to full re-prefill so restarts/route-changes degrade gracefully instead of corrupting output. MoE expert routing itself is layer-local and was already ruled out as the cause of the earlier Qwen3.6 garbage-output bug (that was the start_layer double-execution); the MoE angle that matters here is architecture-awareness so the cache design does not hardcode a K/V shape assumption that breaks on Qwen3.6's hybrid attention layers.\n\nSource issue has full subtask table and code refs.",
+      "acceptanceCriteria": [
+        "A session ID is stable across all steps of one chat generation (not re-minted per token)",
+        "Steps after the first prefill send only the new token's activation, not the full sequence, over the wire between nodes",
+        "Each node caches past_key_values/recurrent state only for its own shard's layer range; no node ever holds another node's cache",
+        "Cache works correctly for both standard-attention shards and Qwen3.6-style hybrid linear-attention/recurrent shards",
+        "Bounded memory: TTL + LRU eviction; eviction/restart triggers a documented cache-miss response, not silent corruption",
+        "Golden-output regression test proves cached and uncached distributed generation produce equivalent output for a fixed prompt",
+        "Measured tps improvement recorded on the same 2-node Qwen2.5-0.5B topology used to observe the regression (target: flat tps across generation length)",
+        "tests/test_two_node_pipeline.py and tests/test_dynamic_routing.py still pass",
+        "Design captured in a new ADR (or an amendment to ADR-0020/0021) covering the cache-miss/route-change interaction"
+      ],
+      "priority": 25,
+      "passes": false,
+      "notes": "Source issue: .scratch/alpha-hardening/issues/25-per-node-kv-cache-distributed.md. Perf follow-up to the ADR-0020 routing fix; no prior story covered KV caching or MoE-specific caching needs.",
+      "dependsOn": [],
+      "completionNotes": ""
     }
   ],
   "metadata": {
-    "updatedAt": "2026-07-07T21:30:00.000Z"
+    "updatedAt": "2026-07-08T19:15:00.000Z"
   }
-}
+}