feat: add dynamo single-node example (frontend + workers, Maru KV sharing)

[seohui-XCENA]

Summary

Adds examples/dynamo/single_node/: one node, one OpenAI-compatible dynamo.frontend (--router-mode direct) in front of two dynamo.vllm workers with MaruKVConnector, sharing KV through one Maru CXL pool. single_node_example.sh brings the whole stack up in the safe order, runs a cross-instance sharing test (a long prompt direct-routed to worker A, then to worker B, which retrieves A's chunks from the pool instead of recomputing them), and tears everything down.

Operational lessons (encoded in the scripts and README)

• Frontend first. The frontend must watch discovery before any worker registers — file-discovery generate leases expire in ~10s without a watching frontend, after which every request is 503 Model not ready, forever.
• Workers start sequentially when sharing a GPU: concurrent vLLM memory profiling races to a negative KV budget.
• Readiness is probed with a direct-routed 1-token completion — /health flaps 503 after registration, and untargeted requests are 400 in direct router mode.
• The file discovery backend can intermittently miss or drop a worker's registration, so each worker gets one automatic retry, and DISCOVERY_BACKEND=etcd is documented as the reliable alternative (real leases, lossless watches).

Note

The example requires the vLLM-0.23 paged-KV axis-order fix in the connector (#72) — on current main the store path crashes with a gather-index assert. It runs cleanly once #72 lands.

Test plan

• E2E (0.5B model, both workers on one GPU, etcd discovery, fix(maru_vllm): adapt LMCache kernel integration to relocated KV-type enums #72 connector applied locally): both workers registered and served through the frontend, identical answers from both, and the cross-instance retrieve confirmed by worker B's External prefix cache hit rate: 69.6% (worker A: 0.0%; prefix caching disabled, so Maru is the only cache source); clean teardown.

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
__init__.py	6	0	100%
__main__.py	3	3	0%	5, 7–8
allocation_manager.py	129	11	91%	30–31, 44–45, 52, 237–238, 268–271
client.py	187	8	96%	88, 130, 147–148, 311–313, 319
config.py	46	1	98%	72
constants.py	9	0	100%
device_scanner.py	115	5	96%	13–15, 63, 96
handler.py	557	86	85%	153, 168, 179–186, 194–196, 211, 217–219, 227, 238–243, 248, 273, 300–301, 305, 345, 349–350, 355, 377, 384–385, 389–395, 398, 402–404, 420, 422–423, 432, 486, 507, 517–518, 624–626, 633, 755–758, 761, 772–775, 781, 867, 971, 1134–1138, 1144, 1155–1159, 1165, 1244, 1249, 1291
ipc.py	275	2	99%	365, 441
kv_manager.py	108	0	100%
logging_setup.py	19	0	100%
plugin.py	59	3	95%	65–67
protocol.py	233	0	100%
resource_manager_installer.py	103	13	87%	80–86, 167, 169–172, 187
rpc_async_client.py	190	0	100%
rpc_async_server.py	111	0	100%
rpc_client.py	71	0	100%
rpc_client_base.py	106	10	91%	185, 221–222, 233–234, 306–307, 311–312, 375
rpc_handler_mixin.py	106	19	82%	154–156, 159–161, 219–222, 227, 231–235, 256–257, 263
rpc_server.py	64	0	100%
serializer.py	81	0	100%
server.py	170	13	92%	64–65, 73, 168, 172, 243, 247, 265–266, 357–359, 444
stats_manager.py	95	0	100%
types.py	60	1	98%	145
uds_helpers.py	13	0	100%
memory
__init__.py	5	0	100%
allocator.py	55	0	100%
mapper.py	164	17	90%	65–74, 77–80, 293, 342, 376
owned_region_manager.py	101	1	99%	212
types.py	63	0	100%
TOTAL	3325	193	94%

Tests	Skipped	Failures	Errors	Time
724	4 💤	0 ❌	0 🔥	7.464s ⏱️