Skip to content

refactor(router): add dynamo-kv-events for KV event types and the engine codec - #113

Closed
ishandhanani wants to merge 1 commit into
idhanani/dyn-171-kv-hashing-contractfrom
idhanani/dyn-172-kv-events
Closed

ishandhanani wants to merge 1 commit into
idhanani/dyn-171-kv-hashing-contractfrom
idhanani/dyn-172-kv-events

Conversation

@ishandhanani

Copy link
Copy Markdown
Owner

Step 2 of the router split v2 (DYNO-172), stacked on #112.

Summary

Adds dynamo-kv-events (lib/kv-events): everything about KV cache events, for both ends of the wire.

  • event: KvCacheEvents, KvCacheEvent, KvCacheEventData, KvCacheStoreData, KvCacheStoredBlockData, KvCacheRemoveData, KvCacheEventError, RouterEvent and its builders, KV_EVENT_SUBJECT.
  • zmq_wire: the engine ZMQ msgpack codec, filters, extra-key and multimodal parsing, moved as a directory with its tests.
  • cursor: the replay cursor a subscriber keeps in step with a publisher.
  • placement: the publisher-side Placement, PlacementOwner, PlacementEvent helpers.

Dependencies: dynamo-router-protocol, dynamo-kv-hashing, serde, serde_json, rmp-serde, rustc-hash, thiserror, tracing. No sockets, tasks, or servers; the ZMQ socket is dynamo-zmq (next) and the listener is a dynamo-kv-router adapter. lib/kv-router keeps pub use shims at every old path, including dynamo_kv_router::zmq_wire and dynamo_kv_router::recovery, so no other crate changes in this step. Sidecars, the C bindings, kvbm-consolidator, and the lib/llm publisher switch imports in the host rewrite step.

One cross-crate effect, handled: KvCacheEventError is #[non_exhaustive], which binds only across crates. kv-router's two exhaustive matches on it (indexer/metrics.rs, behind the metrics feature) gain a wildcard arm and an unknown status counter, pre-registered like the others, so a newer dynamo-kv-events reporting a kind this indexer predates is counted rather than refused. lib/llm already matched it with a wildcard.

Validation

  • cargo test -p dynamo-kv-events: 65 passed (codec tests plus the moved event tests).
  • cargo check -p dynamo-kv-router and cargo check -p dynamo-kv-router --all-features --tests: clean (the all-features check is what caught the non-exhaustive matches; it is now part of every step's validation).
  • cargo test -p dynamo-kv-router: 1,039 lib + 1 integration passed with default features; 1,049 + 1 with --features metrics,testing (the 65-test drop from refactor(router): move the hash contract to dynamo-kv-hashing #112 is the codec and event tests now in kv-events).
  • cargo check -p dynamo-llm -p dynamo-mocker -p dynamo-bench -p dynamo-custom-policy-builtin -p dynamo-sglang-sidecar --tests: clean.
  • cargo clippy on protocol, kv-hashing, kv-events, kv-router with -D warnings: clean, including --all-features on kv-events and kv-router.
  • scripts/router_layering_check.sh: 11 checks, 0 failures (kv-events row: router deps == {protocol, kv-hashing}; direct deps == {dynamo-kv-hashing, dynamo-router-protocol, rmp-serde, rustc-hash, serde, serde_json, thiserror, tracing}).
  • scripts/router_move_diff.py e1e8b11db3 WORKTREE over the moved files: 4,782 normalized lines in common; 4 new (two pad_value_for_mm_hash paths re-spelled to dynamo_kv_hashing::routing, the mod tests wrapper in event.rs); 2 dropped (the old spellings). Every moved file at fraction 1.000 except convert.rs at 0.998. The indexer/metrics.rs wildcard arms and unknown counter are a deliberate change outside the move set.
  • CODEOWNERS: lib/kv-events/ claimed; the zmq_wire and extra_keys.rs globs follow the move; build_codeowners.py --strict clean; validate_agent_instructions.py 46 scopes OK.

@github-actions github-actions Bot added refactor documentation Improvements or additions to documentation labels Oct 30, 2026
@ishandhanani
ishandhanani added this pull request to stack #158 November 1, 2026 06:35
…ine codec

Move everything about KV cache events out of lib/kv-router into
lib/kv-events: the event types (KvCacheEvents, KvCacheEvent,
KvCacheEventData, store, remove, and stored-block data, KvCacheEventError),
the RouterEvent envelope and its builders, KV_EVENT_SUBJECT, the engine ZMQ
msgpack codec (zmq_wire), the replay cursor (recovery/cursor.rs), and the
publisher placement helpers (Placement, PlacementOwner, PlacementEvent).
The RouterEvent legacy-wire tests and the router event constructor test
move with the types; the codec's tests move with the codec.

Both ends of the KV-event wire depend on this crate: workers, sidecars,
and the C bindings publish with it, the router's indexer ingests with it.
It depends on dynamo-router-protocol and dynamo-kv-hashing plus serde,
rmp-serde, rustc-hash, thiserror, and tracing; no sockets, tasks, or
servers. lib/kv-router keeps pub use shims at every old path, including the
zmq_wire and recovery module paths, so no other crate's imports change.

KvCacheEventError is non-exhaustive, which binds only across crates, so
kv-router's two exhaustive matches on it (behind the metrics feature) gain a
wildcard arm and an "unknown" status counter.

The layering gate gains a dynamo-kv-events row; CODEOWNERS claims
lib/kv-events and follows the moved extra_keys override.

Step 2 of the router split v2 plan. DYNO-172.

Signed-off-by: Ishan Dhanani <ishandhanani@gmail.com>
@ishandhanani

Copy link
Copy Markdown
Owner Author

Landed upstream as ai-dynamo#18055 (squash commit 79692cf on main, 2026-11-11). Closing this fork review unit.

This branch had an error being deployed

1 failed deployment
external_collaborator — acd8bf42 Deployed Nov 2, 2026 by ishandhanani via ok-to-test #515
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation refactor

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant