feat(router): expose an explicit admission barrier

[Harrilee]

Summary

A host driving native scheduling futures needs to know when the admission actor has processed submitted work without waiting for capacity-blocked requests. LocalScheduler::update_queue() intentionally returns immediately when queueing is disabled, so it cannot provide that guarantee for the default router configuration.

Add SchedulerQueue::admission_barrier() and a LocalScheduler delegate. The explicit barrier uses the existing update command and acknowledgement, including cancellation cleanup and ready-work rechecks, and reports actor shutdown as an error. Existing update calls retain their no-queue fast path. Scheduling, selection, capacity, and booking algorithms are unchanged.

This small native interface supports AISimulate directly hosting Dynamo's production scheduler instead of copying admission logic into the simulator. It is a prerequisite for the refactoring in AISimulate #306.

Validation

• cargo test --locked -p dynamo-kv-router --features standalone-selection --lib scheduling::local::tests: 25 passed.
• cargo test --locked -p dynamo-kv-router --features standalone-selection --lib scheduling::queue::tests: 54 passed, 1 existing ignored test.
• New paused-clock tests cover admission with queueing enabled/disabled, preservation of the existing update fast path, blocked requests, cancellation cleanup, capacity release, and unchanged virtual time.
• Scoped rustfmt, diff checks, and commit pre-commit hooks passed.

Where should the reviewer start?

lib/kv-router/src/scheduling/queue.rs defines the acknowledgement contract; local.rs exposes it and contains the two behavioral tests.

Related Issues

Refs AIC-1817.

Summary by CodeRabbit

• New Features
  • Scheduling now checks submitted requests and processes ready work even when queueing is disabled. Requests that cannot proceed because capacity is full remain pending and can continue when capacity becomes available. Blocked requests can also be canceled without advancing paused time.

[devin-ai-integration]

✅ Dynamo PR CI passed — run 38680261251 (attempt 1) on 85ce615a40

Gate checks: ✅ backend-status-check · ✅ deploy-status-check · ✅ dynamo-status-check

_{Posted automatically by Devin for run 38680261251. Updated on every full-CI run of this PR.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: ai-dynamo/dynamo/.coderabbit.yaml
• Review profile: CHILL
• Plan: Enterprise
• Run ID: 14bf9422-06e8-4355-9b04-e9db7dd1c6d4

📥 Commits

Reviewing files that changed from the base of the PR and between f5c3659 and 85ce615.

📒 Files selected for processing: 2

• lib/kv-router/src/scheduling/local.rs
• lib/kv-router/src/scheduling/queue.rs

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

Walkthrough

The scheduler queue adds an acknowledged admission barrier. The local scheduler delegates to it to process submitted admissions regardless of queueing mode. Tests cover runnable admissions, capacity-blocked admissions, cancellation, and capacity release.

Changes

Admission barrier

Layer / File(s)	Summary
Queue barrier and acknowledgement lib/kv-router/src/scheduling/queue.rs	SchedulerQueue::admission_barrier sends an update and awaits its acknowledgement. It returns SubscriberShutdown if sending fails or the acknowledgement channel closes. update delegates to the barrier and ignores its result.
Local scheduler barrier behavior lib/kv-router/src/scheduling/local.rs	LocalScheduler::admission_barrier delegates to the queue. Tests verify that the barrier processes submitted admissions with queueing enabled or disabled, leaves capacity-blocked admissions pending, and processes them after capacity is released. They also cover cancellation and paused time.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 85ce6

The barrier processes submitted admissions without waiting for capacity-blocked requests. No issue identified here prevents merging after normal checks.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 77.78% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the primary change: exposing an explicit admission barrier.
Description check		The description explains the motivation, implementation, validation, reviewer starting points, and related issue. It uses a Summary section instead of the template's Overview and Details headings, but…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description explains the motivation, implementation, validation, reviewer starting points, and related issue. It uses a Summary section instead of the template's Overview and Details headings, but it provides the required information and includes a valid issue reference.

• Fix all pre-merge checks with AI

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[tedzhouhk]

Reviewed at 85ce615. The explicit admission barrier is a suitable native scheduler interface: it reuses the existing Update/ack mechanism, preserves the no-queue fast path of update(), and leaves capacity-blocked requests pending without adding simulation or policy logic.

Validation: independently ran the scheduling:: suite with standalone-selection on this commit: 270 passed, 0 failed, 1 ignored. Current-head Pre Merge and full CI pass.