feat(worker): add KVCacheManager stats tier (Phase 5.1 of decouple, refs #175)

[Andrewxu313]

Description

Phase 2 / Slice 5 — port step (1 of 3+). Issue #175. Worker unchanged in this PR.

Surface (+426 LOC, 2 files)

File	LOC	Purpose
batchgen/worker/kv_manager.py	192	KVStats + HostKVUtilization + KVUtilizationRequest + KVStatsBackend Protocol + KVCacheManager
tests/worker/test_kv_manager.py	234	9 real-fixture unit tests

Scope refinement vs original plan

Plan §D claimed Slice 5 would retire the whole KV Cache Helper section (~1330 LOC, 27 methods). Audit shows the 27 methods span four distinct concerns:

Concern	LOC	Status
Read-only stats (3 methods)	~76	This PR
Page-table capacity helpers (3 methods)	~71	Deferred to 5.2
Allocation / I/O (8 methods)	~370	Deferred to 5.3
Migration planners + executors (5 methods)	~644	Deferred to 5.4–5.5
Other (8 methods)	~169	TBD

Porting all of Slice 5 in one PR would be too risky. This PR establishes the KVStatsBackend Protocol + KVCacheManager shell with just the three read-only stat methods; the harder allocators / planners / migrations land in later sub-slices.

Methods ported

Was on worker	LOC	New method on KVCacheManager
_get_host_kv_free_pages	5	get_host_free_pages()
_get_gpu_kv_free_pages	6	get_gpu_free_pages()
_get_host_kv_utilization	65	get_host_utilization(req)

Design

• Frozen KVStats dataclass for C++-backed page-counter snapshots.
• Frozen HostKVUtilization for per-node aggregated views (host KV is shared across all GPUs on a node).
• Narrow KVStatsBackend Protocol: just get_host_stats() -> KVStats and get_gpu_stats() -> Optional[KVStats]. Production wires the worker's host_paged_kv_worker_view / gpu_paged_kv_cache_manager; tests wire a FakeKVBackend with explicit pre-set stats.

Pure read-only — no NCCL, no state mutation, no compare-mode complexity. The handler reads stats, aggregates by node, returns a frozen dataclass.

Tests

9 cases: free-page reads, GPU-unbound fallback to 0, node aggregation across an 8-GPU node with mixed sequence statuses (IN_DECODE, PREFILLED, ON_HOLD all counted as valid; QUEUEING and COMPLETED excluded), free_percent handles 0-total edge case, node_rank_end clamps to world_size when nodes are partial, and backend swap works structurally.

$ python3 -m pytest tests/worker/ -x
============================== 67 passed in 1.31s ==============================

Motivation

Refs #175. Part of milestone Worker decouple.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

(New module + tests. Worker behavior unchanged.)

Checklist

• I have read the CONTRIBUTION guide.
• I have updated the tests (if applicable). 9 new unit tests.
• I have updated the documentation (if applicable). N/A.

Pre-merge verification

• python -m py_compile batchgen/worker/kv_manager.py tests/worker/test_kv_manager.py succeeds.
• pytest tests/worker/ -x → 67/67 passing.
• pr-gpu-smoke.yml — runs on PR push.