# lib/kv-router/src/scheduling
Scheduling owns request admission, queueing, worker selection, and the handoff
from projected load into sequence-state booking.
## Guardrails
- `SchedulerQueue::admit_one` is the canonical admission path: compute projected
load, select worker, respond, then book state. Do not bypass this for normal
scheduling.
- Do not remove or weaken `admission_gate` without proving selection plus
booking remains serialized enough to avoid oversubscription regressions.
- Potential-load projection must go through
`ActiveSequencesMultiWorker::potential_blocks_and_tokens_at(...)` with
`SchedulingRequest::prefill_token_deltas()`. Do not scan per-worker
`ActiveSequences` directly from scheduling.
- `SchedulingRequest` helper methods are the canonical source for effective
cached tokens, effective overlap, worker allowance, prefill-token defaults,
and request block count. Do not duplicate this logic in policies or selectors.
- WSPT must remain prefill-hint aware: pinned requests use the pinned worker's
effective cached tokens; unpinned requests use the best allowed worker. Do not
silently fall back to raw ISL unless tracking is disabled or cache data is
absent.
- Pinned-worker and allowed-worker constraints must be validated before
selection and respected by queue capacity checks, selector candidate
iteration, and WSPT priority.
- Prefill load hints are computed at scheduler/request boundaries from
selected-worker `cached_tokens`. Do not move ISL/cache-token math back into
`ActiveSequences`.
- Selectors should be side-effect free: no booking, no queue mutation, and no
`PromptRegistry` mutation.
- Do not hold the pending-heap lock while selecting, calling slot state,
responding, or awaiting. The queue heap is only for parked requests.
- Do not hold `workers_with_configs.borrow()` across `.await`; take a short
synchronous snapshot or borrow for selection only.
- Any change to queue ordering, WSPT keys, capacity checks, admission
serialization, or selector scoring should include focused tests and
before/after routing or queue benchmarks.
- Keep text and external IDs such as request IDs on standard hash collections.
Use `FxHashMap` / `FxHashSet` for internal numeric hot-path keys only.