Repository navigation
refactor(router): plugins use the prelude; drop the API snapshots; slim the gate and AGENTS files - #193
Closed
ishandhanani wants to merge 4 commits into
Closed
refactor(router): plugins use the prelude; drop the API snapshots; slim the gate and AGENTS files#193ishandhanani wants to merge 4 commits into
ishandhanani wants to merge 4 commits into
Conversation
A plugin crate depends on dynamo-kv-router alone and imports through plugins::prelude. Owner decision 2026-11-02/03. plugins::prelude re-exports MAX_SESSION_AFFINITY_ENTRIES and MAX_SESSION_AFFINITY_ID_BYTES; the builtin sticky_min_load policy takes them from the prelude and builtin drops dynamo-session-affinity. The synchronous DefaultWorkerSelector adapter and its DefaultWorkerSelectorControl handle (the prelude WorkerSelectionPolicy behind the kernel's WorkerSelector trait, for direct selection and deterministic replay) move whole from lib/router-plugins/builtin/src/default/selector.rs to lib/mocker/src/replay/default_selector.rs, the mocker being their only consumer and a host that already depends on the kernel; the mocker's three imports (replay/offline/extensions/kv_router, router_controls, router_shared) re-point. The adapter built the policy through two builtin-private helpers (runtime_policy, PolicyParameters); builtin exposes default_policy_with_rng, one public constructor beside default_policy, and PolicyParameters stays private. builtin's integration tests drive the policy directly as a WorkerSelector, seeded through default_policy_with_rng; the adapter's handle-sharing and clone test moves with it to the mocker's router_controls tests. builtin's dynamo-scheduler edge becomes a dev-dependency (the remaining uses are cfg(test) modules, the two benches, and the integration tests); the mocker gains fastrand for the adapter's seeded stream. Lockfiles: root, Python bindings, KVBM bindings. scripts/router_layering_check.sh gains a plugin table: builtin, the catalog, and each custom-policy example crate name exactly the Dynamo crates allowed (dynamo-kv-router; the example catalog also its sibling example policies; the EPP example also the catalog and dynamo-ext-proc). Planting dynamo-scheduler back into builtin's normal dependencies fails the gate with a line naming builtin. Signed-off-by: Ishan Dhanani <ishandhanani@gmail.com>
The cargo-public-api snapshots of the six tier-1 router crates were migration scaffolding for the split (SPLIT_V2 section 10): they caught a shim or a path going missing while the crates were being carved out. With the shims gone and the stack prepared for review they only add a nightly toolchain and a cargo-public-api install to CI and a snapshot diff to every change of a public item. Owner decision 2026-11-02/03: the snapshot machinery goes; the layering gate stays for the dependency edges. Deleted: scripts/router_public_api_check.sh and public-api.txt in lib/kv-router, lib/router/protocol, lib/kv-events, lib/kv-hints, lib/error, lib/multimodal. .github/workflows/pre-merge.yml loses the "Check router public API snapshots" step together with its nightly toolchain and cargo-public-api install (nothing else used them). .pre-commit-config.yaml and .github/filters.yaml never named the script. The README and AGENTS mentions in lib/kv-router, lib/error, lib/kv-hints, and lib/multimodal are removed; every public item stays documented. tests/plugin_api_prelude.rs stays: it is the compile-time check that a plugin needs the prelude alone. Signed-off-by: Ishan Dhanani <ishandhanani@gmail.com>
Owner decision 2026-11-02/03: the gate stays for the dependency edges
only. Each router-family row of scripts/router_layering_check.sh now
carries exactly two sets: the exact direct Dynamo dependencies (normal
[dependencies], optional included; the set each crate's AGENTS.md
states) and the crates forbidden anywhere in its --all-features
closure (today's lists, unchanged: the runtime, kv-router, the stage
and kernel crates a row must not reach, tokio/zmq/axum/reqwest/
prometheus for the leaves, with HOST_ADAPTER_EXEMPT and the kv-indexer
export note). The direct set replaces the exact router-family closure
column, so each crate's row reads as its manifest does.
Kept: the protocol behavior grep (SPLIT_V2 G9) as one standalone check,
the composition crate's router set and transport check on its
no-features tree, the plugin table, the workspace check that no normal
dependency enables testing/bench/profile on a router crate (the
protocol crate's AttemptId constructors live behind them), the two
source rules (no #[doc(hidden)], no cross-crate glob re-export; the
kv-router test_utils exemption stays), ROUTER_CRATE_DIRS, and the
--host resolution of HOSTS and HOSTS_EXTERNAL. Dropped: the exact
closure column, the exact third-party direct-dependency lists
(COMPOSITION_DIRECT_DEPS and the per-row column), and the
README/AGENTS/CLAUDE trio check. Output format unchanged
("router layering: N checks, M failures", "FAIL ..." lines): 40 checks
plain, 59 with --host, 0 failures.
Planted one at a time and reverted, each fails closed: dynamo-tokens
added to session-affinity (direct set), tokio added to dynamo-error
(forbidden closure), a glob re-export in slot-tracker (source rule),
reqwest added to session-affinity under --host (every host reports the
reach).
lib/router/README.md describes the slimmed gate. The pre-commit
trigger adds lib/router-plugins, lib/error, lib/multimodal, and the
custom-policy examples, the paths the plugin table and the leaf rows
read. The filters.yaml comment no longer mentions per-crate docs.
Signed-off-by: Ishan Dhanani <ishandhanani@gmail.com>
…nd the gate
Owner decision 2026-11-02/03: each router crate's AGENTS.md shrinks to
what the crate owns, its Dynamo dependencies (the exact set the gate
row states), what it must not depend on, how hosts import it, the gate
command, and the design pointer; owners grow them later. Fourteen
crates (lib/error, lib/multimodal, lib/router/protocol, lib/kv-hashing,
lib/kv-events, lib/zmq, lib/kv-hints, lib/router/{kv-indexer,
slot-tracker, session-affinity, worker-selection, admission,
scheduler}, lib/kv-router) are nine lines each (before: 7, 8, 13, 6,
7, 7, 8, 10, 8, 6, 7, 7, 157, 35). lib/router-plugins/builtin and
lib/router-plugins/catalog gain the same nine-line AGENTS.md stating
the plugin rule (dynamo-kv-router alone, imports through
plugins::prelude) and a CLAUDE.md twin (@AGENTS.md).
Durable rules that are not derivable from the code move into READMEs
under "Working rules": the scheduler's invariants, lock order, and
actor rules into lib/router/scheduler/README.md; the public
worker-selection plugin API rules into
lib/router/worker-selection/README.md, the crate that owns that
contract; kv-router's N-2 wire note, dependency footprint notes, hash
collection rule, and engine hash invariant into
lib/kv-router/README.md. The scheduler's queue-hierarchy narrative
(diagram, per-class storage) was derivable from the code and is not
carried over; it remains at ebd31cd. One line per bullet, no
hard-wrapped Markdown. CLAUDE.md twins stay everywhere;
scripts/validate_agent_instructions.py validates 58 scopes.
Signed-off-by: Ishan Dhanani <ishandhanani@gmail.com>
ishandhanani
had a problem deploying
to
external_collaborator
November 3, 2026 02:43 — with
GitHub Actions
Failure
ishandhanani
had a problem deploying
to
external_collaborator
November 3, 2026 02:43 — with
GitHub Actions
Failure
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Router split v2 follow-up (DYNO-194). Stacked on #173.
Summary
Four commits. Owner decisions (2026-11-02/03): plugin crates depend on
dynamo-kv-routeronly and import throughplugins::prelude; the public-API snapshot machinery was migration scaffolding and goes; the layering gate stays for the dependency edges only; each crate's AGENTS.md shrinks to purpose, dependencies, and the gate command (owners grow them later). It is fine that the series introduced these and removes them here.refactor(router): plugin crates import through the prelude(f6f38ac).plugins::preludere-exportsMAX_SESSION_AFFINITY_ENTRIESandMAX_SESSION_AFFINITY_ID_BYTES; builtin'ssticky_min_loadtakes them from the prelude and builtin dropsdynamo-session-affinity. The synchronousDefaultWorkerSelectoradapter and itsDefaultWorkerSelectorControlhandle (the preludeWorkerSelectionPolicybehind the kernel'sWorkerSelector<C>trait, for direct selection and deterministic replay) move whole fromlib/router-plugins/builtin/src/default/selector.rstolib/mocker/src/replay/default_selector.rs: the mocker is their only consumer outside builtin (grep over lib, components, examples, bindings:replay/offline/extensions/kv_router/mod.rs,replay/router_controls.rs,replay/router_shared.rs; the brief named two, the third is theReplaySchedulertype alias inrouter_shared.rs) and a host that already depends on the kernel, so the adapter lives with the one caller that needs a&selfselector with a shared control handle. The adapter built its policy through two builtin-private helpers (runtime_policy,pub(super) PolicyParameters); builtin exposes one public constructor besidedefault_policy,pub fn default_policy_with_rng(config: SelectionConfig, worker_label: &'static str, rng: Option<Arc<Mutex<fastrand::Rng>>>) -> WorkerSelectionPolicy(default_policydelegates to it withNone), andPolicyParametersstays private; adding the function was smaller than wideningdefault_policy, which has seven callers. builtin's integration tests used the adapter at twelve sites: ten only as a seededWorkerSelector, whichWorkerSelectionPolicyalready is (impl<C: WorkerConfigLike> WorkerSelector<C> for WorkerSelectionPolicy), sotests/default_policy.rsgets a seven-lineseeded(config, label, seed)helper overdefault_policy_with_rngandtests/kv_transfer.rsinlines its three sites;selector_runtime_update_keeps_the_seeded_random_streamdrivesWorkerSelectionPolicy::update_runtime_configdirectly;selector_controls_share_runtime_state_and_clones_start_freshtests the adapter's handle sharing and clone semantics and moves with it into the mocker'srouter_controlstests (with its three-linepatchhelper). builtin'sdynamo-scheduleredge becomes a dev-dependency (remaining uses:cfg(test)modules inthunderagent/worker_selection/mod.rsandtwo_tier_cost_fn.rs, the two benches, the integration tests);cargo check -p dynamo-custom-policy-builtin(no tests) compiles withdynamo-kv-routeras its only Dynamo edge (cargo tree -e normal --depth 1). The mocker gainsfastrand = "2"for the adapter's seeded stream.scripts/router_layering_check.shgains a plugin table: builtin, the catalog, and eachexamples/router/custom-policy-example/*crate name exactly the Dynamo crates allowed (dynamo-kv-router; the example catalog also its four sibling example policies, which the brief's rule did not anticipate; the EPP example also the catalog anddynamo-ext-proc).chore(router): drop the public-API snapshots(7ae5030). Deleted:scripts/router_public_api_check.shandpublic-api.txtinlib/kv-router(918 lines),lib/router/protocol(217),lib/kv-events(255),lib/kv-hints(134),lib/error(134),lib/multimodal(19)..github/workflows/pre-merge.ymlloses the "Check router public API snapshots" step with its nightly toolchain andcargo-public-apiinstall (nothing else used either)..pre-commit-config.yamland.github/filters.yamlnever named the script. Mentions removed fromlib/kv-router/README.md,lib/error/{README,AGENTS}.md,lib/kv-hints/{README,AGENTS}.md,lib/multimodal/{README,AGENTS}.md; the repo-wide grep over md, mdx, yml, yaml, sh, toml, py, rs is empty.tests/plugin_api_prelude.rsstays. The chain v2 script drops the snapshot line from stage 5.chore(router): slim the layering gate to the dependency edges(1011544). Each router-family row now carries exactly two sets: the exact direct Dynamo dependencies (normal[dependencies], optional included; the set each crate's AGENTS.md states) and the crates forbidden anywhere in its--all-featuresclosure (today's lists unchanged, withHOST_ADAPTER_EXEMPTand the kv-indexerexportnote). Kept: the protocol behavior grep (G9) as one standalone check, the composition crate's router set and transport check on its no-features tree, the plugin table, the workspace check that no normal dependency enablestesting/bench/profileon a router crate (it guards the protocol crate'sAttemptIdconstructors, not the snapshots), the two source rules with the kv-routertest_utilsexemption,ROUTER_CRATE_DIRS, and--hostoverHOSTSandHOSTS_EXTERNAL. Dropped: the exact router-family closure column,COMPOSITION_DIRECT_DEPSand the per-row third-party direct-dependency column, the README/AGENTS/CLAUDE trio check. Output format unchanged: 40 checks plain (13 rows x 2, protocol grep, 2 composition, 8 plugin, workspace features, 2 source rules), 59 with--host(the same 19 host checks as before), 0 failures; before: 47 and 66.lib/router/README.mddescribes the slimmed gate; the pre-commit trigger regex addslib/router-plugins/,lib/error/,lib/multimodal/, andexamples/router/custom-policy-example/(paths the plugin table and the leaf rows read; the regex is^-anchored, soCargo\.tomlmatched the root manifest only); thefilters.yamlcomment no longer mentions per-crate docs.docs(router): trim each crate's AGENTS.md to purpose, dependencies, and the gate(0ebe1e5). Fourteen crate AGENTS.md files are nine lines each:# <path>, one or two sentences on what the crate owns,Depends on (Dynamo crates)exactly matching the gate row,Must not depend on, how hosts import it (hostmodule for the six stage crates, directly for the leaves, kv-router, and the plugins),Check,Design. Before and after: error 7 -> 9, multimodal 8 -> 9, protocol 13 -> 9, kv-hashing 6 -> 9, kv-events 7 -> 9, zmq 7 -> 9, kv-hints 8 -> 9, kv-indexer 10 -> 9, slot-tracker 8 -> 9, session-affinity 6 -> 9, worker-selection 7 -> 9, admission 7 -> 9, scheduler 157 -> 9, kv-router 35 -> 9;lib/router-plugins/builtinandlib/router-plugins/cataloggain the same nine-line file stating the plugin rule plus aCLAUDE.mdtwin. Durable, non-derivable rules move into READMEs under "Working rules": the scheduler's invariants, lock order, and actor rules (18 bullets) intolib/router/scheduler/README.md; the public worker-selection plugin API rules intolib/router/worker-selection/README.md(the crate that owns the contract; the brief said the scheduler README); kv-router's N-2 wire note, dependency footprint notes, hash collection rule, and engine hash invariant intolib/kv-router/README.md. The scheduler's queue-hierarchy narrative (Mermaid diagram, per-class storage) was derivable from the code and is not carried over; it remains atebd31cdf4d. The nested AGENTS.md files underlib/kv-router/src/*andlib/router/kv-indexer/src/concurrent_radix_tree_compressedare outside the brief and untouched.scripts/validate_agent_instructions.py: 58 scopes OK.Adapter move-diff
python3 -I scripts/router_move_diff.py ebd31cdf4d WORKTREE --from lib/router-plugins/builtin/src/default/selector.rs --to lib/mocker/src/replay/default_selector.rs:Not the brief's
dropped 0: the three lines are the private-helper call (runtime_policy(config, PolicyParameters::from(&config), worker_type, rng)) becoming the one public constructor (default_policy_with_rng(config, worker_type, rng)); every other normalized line of the adapter is common. Theuselines (dropped from the diff by normalization) change fromsuper::runtime_policytodynamo_custom_policy_builtin::default_policy_with_rng.Gate fail-closed outputs
Each planted alone and reverted;
git statusclean after each.Plugin rule (commit 1;
dynamo-scheduler = { workspace = true }added back to builtin's[dependencies]):Commit 3, the four kept kinds:
The brief's fourth kind reads "a host importing a stage not through
host"; no gate check of that kind exists (hosts importdynamo_kv_indexer::cuckoodirectly 33 times, by design), so the--hostkind planted is the one the gate has: a table crate reaching a transport crate in every host's resolved graph, including the externaldynamo-py3manifest. For the manifest plants the lockfile was refreshed so--lockedreached the check instead of dying first; the plant and the lockfile were reverted together.Removal proof (
git diff ebd31cdf4d..0ebe1e5139 -- '*.rs', 11 files, +88 -73; commits 2 to 4 touch no.rsfile)lib/router-plugins/builtin/src/default/selector.rs->lib/mocker/src/replay/default_selector.rs, git rename with +2 -4 (the move-diff above).use,mod, and re-export re-points, 26 lines:prelude.rs+1;mocker/replay/mod.rs+1 (mod default_selector;); the three mocker imports (+1 -1 each);router_controls.rstest import; builtinlib.rs(+1 -2, the two adapter names leave thepub use default::{...}anddefault_policy_with_rngjoins it);default.rs(mod selector;and itspub usegone);sticky_min_load.rs-1; the test files' import lines.default.rs: +12 -3 including its three doc lines (default_policynow delegates).default_policy.rs+19 -51 (theseededhelper and its two imports +10; seven seeded sites -16 +7;let mut updatedand the dropped.runtime_control()-3 +1; the moved test -27);kv_transfer.rs+12 -8 (three sites re-pointed todefault_policy/default_policy_with_rng).router_controls.rs+38 -2: the moved test and thepatchhelper (+37) plus the two import re-points.cargo tree -p dynamo-custom-policy-builtin -e normal --depth 1: Dynamo crates before{dynamo-kv-router dynamo-scheduler dynamo-session-affinity}, after{dynamo-kv-router}.Host Cargo.toml edges
lib/router-plugins/builtin/Cargo.toml:dynamo-session-affinityremoved;dynamo-schedulerremoved from[dependencies](the[dev-dependencies]entry withfeatures = ["bench"]already existed).lib/mocker/Cargo.toml:fastrand = "2"added. Lockfiles: root losesdynamo-session-affinityunder builtin and gainsfastrandunder the mocker; the Python and KVBM bindings lockfiles (which do not carry non-member dev-dependencies) also losedynamo-schedulerunder builtin.MODE=fullmandatory.Validation
Validation chain v2 in
MODE=full(mandatory: builtin's and the mocker'sCargo.tomledges change),TAG=194 LLM_EXTRA_TESTS="discovery pool_relay", run once on the final head0ebe1e5139after commit 4 (log/tmp/rr-split/s194-validation.logon the build host). Every stage exit 0 except the pre-existing kvbm-consolidator manifest failure (unrelated, untouched). NoMOVE_SPECS_FILE: the adapter move-diff is reported above and is not an exact move.target21 GB after the run.cargo clippy --all-targets -- -D warnings(default and--all-features);cargo test --all-features: admission 22, error 29, kv-events 64, kv-hashing 19 + 17 + 3, kv-hints 4, kv-indexer 599 + 2 ignored, multimodal 4, protocol 9, scheduler 289 + 1 ignored, session-affinity 10, slot-tracker 131, worker-selection 43, zmq 2, doc-tests 2 + 2 ignored (1,247 passed, 5 ignored);RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --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 --features bench --benches; tests 220 + 1 + 7;plugin_api_prelude1 passed (the prelude gained two constants; the test is unchanged).cargo clippy --workspace --all-targets -- -D warningsclean.cargo check -p dynamo-llm --libalone;cargo test -p dynamo-llm --libforkv_router(492),discovery(275),pool_relay(261); per-hostcargo clippy -p <host> --tests -- -D warningsexit 0 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, libdynamo_llm; kvbm-consolidator exit 101 (manifest, pre-existing);lib/bindings/pythoncargo clippy --features kv-indexer,slot-tracker,select-service -- -D warningsexit 0.scripts/router_features_check.sh(every kv-router feature alone and together);scripts/router_layering_check.sh40 checks, 0 failures and--host59 checks, 0 failures;python3 .github/codeowners/build_codeowners.py --strict7587/7587 explicitly owned (the two new AGENTS.md and CLAUDE.md files are under the ownedlib/router-plugins/area);cargo fmt --all -- --check;cargo metadata --lockedfor the root,lib/bindings/python, andlib/bindings/kvbmlockfiles.cargo check -p dynamo-custom-policy-builtin(no tests) exit 0;cargo test -p dynamo-mocker --lib replay170 passed, 0 failed (includes the moved adapter test). After commit 1 (logs194-c1-check.log):cargo tree -p dynamo-custom-policy-builtin -e normal --depth 1listsdynamo-kv-routeras the only Dynamo crate; builtincargo clippy --all-targets -- -D warningsclean; builtin tests lib 65 + 2 ignored, batch_scoring 5, cache_inputs 1, default_lifecycle 3, default_policy 19, kv_transfer 3, plugin_registry 4; mockercargo clippy --testsclean; mocker replay 170; prelude 1; gate 55 checks (47 + the 8 plugin rows), 0 failures.target21 GB; 275 GB free.