Skip to content

refactor(router): move the candidate columns to worker-selection - #168

Closed
ishandhanani wants to merge 1 commit into
idhanani/dyn-186-residency-to-kv-eventsfrom
idhanani/dyn-188-columns-to-worker-selection
Closed

ishandhanani wants to merge 1 commit into
idhanani/dyn-186-residency-to-kv-eventsfrom
idhanani/dyn-188-columns-to-worker-selection

Conversation

@ishandhanani

Copy link
Copy Markdown
Owner

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

Summary

  • Why: the producer owns the type. WorkerInputs (the optional column groups a filter, scorer, picker, or classifier declares) and WorkerInfo (the static facts every candidate row carries) are the column vocabulary of worker selection's candidate table: worker selection builds its rows from them and its plugin traits return them. Nothing in protocol or any engine, worker, or sidecar wire names them, so they do not meet protocol's entry rule. Admission's classifier declares and reads columns too, so admission now depends on worker-selection for its output types (the stage-edges-over-protocol-hoisting decision of 2026-11-01; same shape as the admission -> slot-tracker edge for the fullness rule). No cycle: worker-selection does not depend on admission.
  • Move (git mv, body byte-identical apart from one import line): lib/router/protocol/src/columns.rs -> lib/router/worker-selection/src/columns.rs; use crate::worker::{WorkerCapacity, WorkerWithDpRank} becomes use dynamo_router_protocol::worker::{...}. The bit layout, ALL, and every doc comment are unchanged (the ALL/KV_TRANSFER follow-up is tracked in Linear, not here). worker-selection gains pub mod columns; inputs.rs re-exports crate::columns::{WorkerInfo, WorkerInputs} so every existing worker-selection path (dynamo_worker_selection::{WorkerInfo, WorkerInputs}, the kv-router plugins::worker_selection and plugins::prelude re-exports) keeps resolving. Protocol drops pub mod columns; its crate doc and README table list the columns under worker-selection.
  • Re-pointed: admission classifier/{inputs,mod,runtime,view}.rs import dynamo_worker_selection::columns::{WorkerInfo | WorkerInputs} (explicit module path); lib/router/admission/Cargo.toml gains dynamo-worker-selection. lib/kv-router/benches/worker_selection.rs imports dynamo_worker_selection::columns::WorkerInputs. The kv-router prelude already re-exported both names from crate::plugins::worker_selection (verified; nothing to change). No lib/llm, mocker, bench, ext-proc, or bindings file named dynamo_router_protocol::columns.
  • Gate (scripts/router_layering_check.sh) admission row: column 2 router deps dynamo-router-protocol dynamo-slot-tracker -> dynamo-router-protocol dynamo-slot-tracker dynamo-worker-selection; column 3 forbidden drops dynamo-worker-selection; column 4 direct deps gain dynamo-worker-selection. The worker-selection row needs no change (it gains no dependency). Three lockfiles (root, lib/bindings/python, lib/bindings/kvbm) each gain the one dynamo-worker-selection line under dynamo-admission.
  • Docs: admission AGENTS/README name the new edge and why; worker-selection crate doc, AGENTS, README name the columns; protocol crate doc and README table; lib/router/README.md worker-selection and admission rows and the status paragraph.
  • Snapshots (scripts/router_public_api_check.sh --update): lib/router/protocol/public-api.txt 251 -> 229 (-22: pub mod columns, WorkerInfo + its impl + new/worker/max_num_batched_tokens/total_kv_blocks/capacity, WorkerInputs + its impl + NONE/CACHE/LOAD/PREFERRED_TAINT/OCCUPANCY/KV_TRANSFER/ALL + contains/without, and the BitOr impl with its Output type and bitor); nothing added. lib/kv-router/public-api.txt (1398) byte-identical: the prelude and plugins::worker_selection re-export WorkerInfo/WorkerInputs from dynamo_worker_selection, which still exports both names at its root, and cargo-public-api renders those re-exports without a defining path, so no kv-router line changes. lib/kv-events (261), lib/kv-hints (142), lib/error (134) byte-identical to refactor(router): move the residency vocabulary to dynamo-kv-events #166's head; worker-selection has no snapshot (tier 2).
  • Codeowners: no directory added or removed; CODEOWNERS unchanged (strict check passes). No behavior change. Plan step 9 not started.
  • Base: this commit was first validated on top of fork PR refactor(router): move ResidencyOwnerKey to protocol identity #167 (ResidencyOwnerKey to protocol identity), which was then closed as superseded (the key will move to kv-indexer instead), and rebased onto refactor(router): move the residency vocabulary to dynamo-kv-events #166's head e844c1580e with git rebase --onto. The one conflict was the protocol crate-doc paragraph ("Deliberately elsewhere", adjacent to refactor(router): move ResidencyOwnerKey to protocol identity #167's rewrap of the same paragraph); it was resolved to refactor(router): move the residency vocabulary to dynamo-kv-events #166's text with "candidate rows" becoming "the candidate columns and rows". No code conflicted. Snapshots were regenerated on the rebased tree and matched the commit; the full chain below ran before the rebase and the quick re-verification after it.

Validation

Full chain on the pre-rebase tree (same diff, on top of #167): all stages exit 0 except the pre-existing kvbm-consolidator manifest failure (unrelated, untouched); log /tmp/rr-split/s188-validation.log on the build host (/tmp/rr-split/chain-188.sh). Then, on the rebased tree e0487538ed (parent e844c1580e): cargo clippy --workspace --all-targets -- -D warnings clean; cargo test -p dynamo-worker-selection --all-features (43), -p dynamo-admission --all-features (22), -p dynamo-router-protocol --all-features (11); RUSTDOCFLAGS="-D warnings" cargo doc --no-deps for protocol, worker-selection, admission; bash scripts/router_layering_check.sh --host 63 checks, 0 failures; bash scripts/router_public_api_check.sh all five match (kv-router 1398, protocol 229, kv-events 261, kv-hints 142, error 134); cargo fmt --all -- --check; cargo metadata --locked for the three lockfiles; move-diff from e844c15 53/53 MOVE; tracked tree clean (log /tmp/rr-split/s188-rebased-validation.log, script /tmp/rr-split/verify-188-rebased.sh).

  • dynamo-worker-selection: cargo clippy -p dynamo-worker-selection --all-targets -- -D warnings (default and --all-features); cargo test -p dynamo-worker-selection (43 passed); RUSTDOCFLAGS="-D warnings" cargo doc -p dynamo-worker-selection --no-deps (default and --all-features).
  • Stage crates dynamo-router-protocol, dynamo-admission, dynamo-scheduler: cargo clippy -p <c> --all-targets -- -D warnings (default and --all-features); cargo test -p <c> --all-features (11; 22; 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 (pre-rebase base aee82da, and identically from e844c15 on the rebased tree): python3 -I scripts/router_move_diff.py <base> WORKTREE --from lib/router/protocol/src/columns.rs --to lib/router/worker-selection/src/columns.rs: from lib/router/protocol/src/columns.rs raw=94 normalized=53 found=53 fraction=1.000, to lib/router/worker-selection/src/columns.rs raw=94 normalized=53, summary from_normalized=53 to_normalized=53 common=53 new=0 dropped=0, result MOVE.

WorkerInputs (the optional column groups a filter, scorer, picker, or
classifier declares) and WorkerInfo (the static facts every candidate
row carries) are the column vocabulary of worker selection's candidate
table: worker selection builds its rows from them and its plugin traits
return them. Nothing on an engine, worker, or sidecar wire names them,
so they do not meet protocol's entry rule; the producer owns them.

git mv lib/router/protocol/src/columns.rs to
lib/router/worker-selection/src/columns.rs, byte-identical apart from
the one import line. worker-selection re-exports both names from
inputs.rs so every existing path keeps resolving; protocol drops the
module. Admission's classifier declares and reads columns, so admission
now depends on worker-selection for that stage's output types (the
stage-edges-over-protocol-hoisting decision, the same shape as its
slot-tracker edge for the fullness rule; acyclic). Gate row for
admission updated; kv-router's worker_selection bench re-pointed.

Snapshots: protocol loses its 22 columns:: lines; kv-router, kv-events,
kv-hints, and dynamo-error are unchanged. No behavior change. DYNO-188.

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

Copy link
Copy Markdown
Owner Author

Closed: superseded by decision. WorkerInfo and WorkerInputs stay in dynamo-router-protocol: they are shared neutral vocabulary across admission, worker-selection, the kernel, and plugins, and the admission -> worker-selection edge bought for two types was heavier than it is worth. DYNO-191 rebases onto #166. Branch kept for reference.

ishandhanani added a commit that referenced this pull request Nov 2, 2026
KvTransferCandidateSource (who holds a prefix a target could fetch),
label_key and topology_keys (the label hashing both sides of a source
match use), and ResidencyOwnerKey (the compact owner identity the
indexer computes in compact_key) are what the indexer emits with a
match. #165 placed the first three in dynamo-kv-hints and #166 the key
in dynamo-kv-events, which left the indexer depending on the feature
crate for its own output types. Rule: a feature crate depends on the
stage that produces its types, never the reverse; the producer owns
its outputs.

Moves, text verbatim (move-diff over the five files from e844c15:
573/573 common, new 0, dropped 0): KvTransferCandidateSource and its
From<WorkerWithDpRank> from lib/kv-hints/src/wire.rs and label_key and
topology_keys from lib/kv-hints/src/keys.rs into
lib/router/kv-indexer/src/kv_hints.rs beside KvTransferCandidates;
ResidencyOwnerKey from lib/kv-events/src/residency.rs into
lib/router/kv-indexer/src/residency.rs just before
ResidencyOwnerKeyExt. kv-hints gains dynamo-kv-indexer, drops
dynamo-kv-events (nothing else in it used that crate), and re-exports
the three names at every path it exposed (root, keys::, wire::), so
every existing consumer path resolves. kv-indexer drops
dynamo-kv-hints. kv-events drops the key it never used; ResidencyOwner
is untouched. Protocol gains nothing.

Edges: kv-indexer -> protocol, kv-events, kv-hashing (was also
kv-hints); kv-hints -> protocol, kv-indexer (was protocol, kv-events).
Gate rows for both crates updated, including kv-hints' forbidden list,
which can no longer name tokio, anyhow, or async-trait now that they
arrive through the indexer; scheduler and kv-events rows and
COMPOSITION_ROUTER_DEPS unchanged. Re-pointed: the kernel and
kv-router protocols shims take ResidencyOwnerKey from
dynamo_kv_indexer::residency (same public name); the plugin prelude
takes KvTransferCandidateSource from the indexer beside
KvTransferCandidates. Three lockfiles follow the manifests. Crate
docs, AGENTS, and READMEs for kv-indexer, kv-hints, and kv-events, the
lib/router and protocol README tables, name the new owner.

Snapshots: kv-events 261 -> 257 (the key, its impl, digest,
from_digest); kv-hints 142 -> 134 (the three re-exported names render
as pub use lines at root, keys::, and wire:: in place of their inlined
definitions, and the two source fields at both paths name the
indexer's defining path); kv-router, protocol, and dynamo-error
byte-identical. No behavior change. DYNO-191.

Validation: clippy (default and --all-features, --all-targets, -D
warnings), cargo test --all-features, and rustdoc -D warnings for
kv-events, kv-hints, kv-indexer, scheduler, and protocol; kv-router
clippy with all features, bench check, tests, and prelude tests;
workspace clippy; hosts alone (lib/llm check, clippy, kv_router tests;
twelve host crates clippy --tests; Python bindings clippy);
router_features_check, router_public_api_check, router_layering_check
plain and --host, codeowners --strict, cargo fmt --check, and the
three lockfiles --locked. The chain ran on top of fork PR #168
(e048753); after #168 was closed the commit was rebased onto #166's
head e844c15 and re-verified there: workspace clippy, the five
crates' tests --all-features, the gate --host, the five snapshots,
fmt --check, and the three lockfiles --locked.

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

This branch had an error being deployed

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