Skip to content

refactor(router): move ResidencyOwnerKey to protocol identity - #167

Closed
ishandhanani wants to merge 1 commit into
idhanani/dyn-186-residency-to-kv-eventsfrom
idhanani/dyn-187-owner-key-to-identity
Closed

ishandhanani wants to merge 1 commit into
idhanani/dyn-186-residency-to-kv-eventsfrom
idhanani/dyn-187-owner-key-to-identity

Conversation

@ishandhanani

Copy link
Copy Markdown
Owner

Router split v2 follow-up (DYNO-187). Stacked on #166.

Summary

  • Why: ResidencyOwnerKey is an identity, not residency vocabulary. The indexer computes it (ResidencyOwnerKeyExt::compact_key, BLAKE3 over a ResidencyOwner) and every other crate only carries and compares it: kv-hints names it in KvTransferCandidateSource::CacheOwner, the kernel and lib/llm pass it through, kv-events itself never used it (no type in dynamo-kv-events mentions the key; ResidencyOwner and its impls do not reference it). That is the AttemptId precedent: an identity one crate mints and everyone names lives in dynamo_router_protocol::identity. Moving it there drops the kv-hints -> kv-events edge that DYNO-186 (refactor(router): move the residency vocabulary to dynamo-kv-events #166) had to add, so kv-hints is back to protocol-only among router crates.
  • Move (verbatim: doc comment, derives, impl ResidencyOwnerKey { from_digest, digest }): lib/kv-events/src/residency.rs lines 43-60 -> lib/router/protocol/src/identity.rs, directly after CacheOwnerId and its Display/FromStr impls. The doc link [CacheOwnerId] now resolves in the same module, so the text is unchanged. The identity module doc names the key.
  • Re-pointed (compiler-driven): lib/kv-hints/src/wire.rs imports dynamo_router_protocol::identity::ResidencyOwnerKey; lib/kv-hints/Cargo.toml drops dynamo-kv-events (nothing else in kv-hints used it; verified by grep). kv-indexer residency.rs (the key from protocol, ResidencyOwner still from kv-events) and prelude.rs (same split). lib/llm needed no change: its recovery tests reach ResidencyOwnerKeyExt through dynamo_kv_indexer::host and never name the key type.
  • Shims: dynamo_scheduler::protocols and dynamo_kv_router::protocols each re-export ResidencyOwnerKey from dynamo_router_protocol::identity instead of dynamo_kv_events::residency; every public name kept.
  • Gate (scripts/router_layering_check.sh) kv-hints row back to its DYNO-185 shape: column 2 router deps dynamo-router-protocol dynamo-kv-events dynamo-kv-hashing -> dynamo-router-protocol; column 3 forbidden regains dynamo-kv-events dynamo-kv-hashing; column 4 direct deps drop dynamo-kv-events. No other row changes. Three lockfiles (root, lib/bindings/python, lib/bindings/kvbm) each lose the one dynamo-kv-events line under dynamo-kv-hints.
  • Docs: kv-hints crate doc, README, AGENTS back to "depends on dynamo-router-protocol only" (AGENTS "never add" list regains dynamo-kv-events and now also names dynamo-kv-hashing); protocol crate doc and README table note the key stays in identity; kv-events README drops the key from the residency list and AGENTS drops kv-hints from the consumer list; lib/router/README.md kv-hints row deps back to protocol, serde, rustc-hash.
  • Snapshots (scripts/router_public_api_check.sh --update): lib/kv-events/public-api.txt 261 -> 257 (-4: pub struct ResidencyOwnerKey(_), its impl, digest, from_digest); lib/router/protocol/public-api.txt 251 -> 255 (+4: the same four lines under identity::, between PoolId and RoutingPartitionId); lib/kv-hints/public-api.txt 142 unchanged in count, two defining-path lines change: KvTransferCandidateSource::CacheOwner(dynamo_kv_events::residency::ResidencyOwnerKey) -> (dynamo_router_protocol::identity::ResidencyOwnerKey) at the wire:: path and the root re-export; lib/kv-router/public-api.txt (1398) and lib/error/public-api.txt (134) byte-identical.
  • Codeowners: no directory added or removed; CODEOWNERS unchanged (strict check passes). No behavior change. Plan step 9 not started.

Validation

All stages exit 0 except the pre-existing kvbm-consolidator manifest failure (its manifest inherits kvbm-logical from a root workspace that does not define it; unrelated, untouched here); log /tmp/rr-split/s187-validation.log on the build host (/tmp/rr-split/chain-187.sh).

  • dynamo-kv-events: cargo clippy -p dynamo-kv-events --all-targets -- -D warnings (default and --all-features); cargo test -p dynamo-kv-events (65 passed); RUSTDOCFLAGS="-D warnings" cargo doc -p dynamo-kv-events --no-deps (default and --all-features).
  • Stage crates dynamo-router-protocol, dynamo-kv-hints, dynamo-kv-indexer, dynamo-scheduler: cargo clippy -p <c> --all-targets -- -D warnings (default and --all-features); cargo test -p <c> --all-features (11; 4; 597 + 2 ignored; 289 + 1 ignored); RUSTDOCFLAGS="-D warnings" cargo doc -p <c> --no-deps (default and --all-features).
  • cargo clippy -p dynamo-kv-router --features http,ingest-zmq,replica-sync-zmq,peer-recovery,metrics,testing --all-targets -- -D warnings; cargo check -p dynamo-kv-router --features bench --benches; cargo test -p dynamo-kv-router --features ... (220 + 1 + 1 + 7); cargo test -p dynamo-kv-router --test plugin_api_prelude --test plugin_api_compat (1 + 1).
  • cargo clippy --workspace --all-targets -- -D warnings clean.
  • Hosts: cargo check -p dynamo-llm --lib; cargo clippy -p dynamo-llm --all-targets -- -D warnings; cargo test -p dynamo-llm --lib kv_router (485 passed); cargo test -p dynamo-llm --lib block_manager::kv_consolidator (21 passed); cargo clippy -p <p> --tests -- -D warnings for dynamo-mocker, dynamo-bench, dynamo-ext-proc, dynamo-custom-policy-builtin, dynamo-worker-selection-policy-catalog, dynamo-sglang-sidecar, dynamo-vllm-sidecar, dynamo-backend-common, dynamo-sglang-mocker, dynamo-vllm-mocker, dynamo-custom-policy-example-epp, dynamo-custom-policy-example-soft-pin-repin (all twelve exist); lib/bindings/python: cargo clippy --features kv-indexer,slot-tracker,select-service -- -D warnings.
  • bash scripts/router_features_check.sh; bash scripts/router_public_api_check.sh after --update (all five snapshots match); bash scripts/router_layering_check.sh 44 checks, 0 failures and --host 63 checks, 0 failures; python3 .github/codeowners/build_codeowners.py ... --strict 7549/7549 explicitly owned; cargo fmt --all -- --check; cargo metadata --locked for the root, lib/bindings/python, and lib/bindings/kvbm lockfiles.
  • Move proof over the pair of files (the key leaves one and enters the other): python3 -I scripts/router_move_diff.py e844c1580e WORKTREE --from lib/kv-events/src/residency.rs lib/router/protocol/src/identity.rs --to lib/kv-events/src/residency.rs lib/router/protocol/src/identity.rs: from residency.rs raw=260 normalized=190 found=190, from identity.rs raw=359 normalized=281 found=281, to residency.rs raw=241 normalized=180, to identity.rs raw=379 normalized=291, summary from_normalized=471 to_normalized=471 common=471 new=0 dropped=0, result MOVE.

ResidencyOwnerKey is an identity the indexer computes and every other
crate names, the AttemptId precedent: kv-hints carries it in
KvTransferCandidateSource::CacheOwner, the kernel and lib/llm pass it
through, and dynamo-kv-events itself never used it. Move the struct and
its two const fns verbatim from dynamo_kv_events::residency to
dynamo_router_protocol::identity, directly after CacheOwnerId.

Consequences: dynamo-kv-hints drops its dynamo-kv-events dependency
(the edge DYNO-186 added) and is back to protocol-only among router
crates; the layering gate row, crate docs, README, and AGENTS say so
again. kv-indexer and both deprecated protocols shims re-point with
every name kept. Snapshots: kv-events -4, protocol +4, kv-hints two
defining-path lines, kv-router and dynamo-error unchanged.

No behavior change. DYNO-187.

Signed-off-by: Ishan Dhanani <ishandhanani@gmail.com>
@github-actions github-actions Bot added refactor documentation Improvements or additions to documentation labels Nov 2, 2026
@ishandhanani
ishandhanani added this pull request to stack #158 November 2, 2026 04:42
@ishandhanani

Copy link
Copy Markdown
Owner Author

Closed: superseded. With kv-hints allowed to depend on kv-indexer, ResidencyOwnerKey belongs in kv-indexer (its producer) rather than protocol; DYNO-191 moves it there together with KvTransferCandidateSource and the label-hash helpers. The branch stays for reference.

This branch had an error being deployed

1 failed deployment
external_collaborator — aee82dae Deployed Nov 2, 2026 by ishandhanani via ok-to-test #445
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