feat(kv-router): stamp request identity on selector scoring rows

[nv-yna]

Overview:

selector.rs emits one tracing::debug! per candidate carrying the whole cost breakdown — overlap_blocks, raw_prefill_blocks, overlap_credit_blocks, overlap_credit_decay, prefill_load_scale, adjusted_prefill_blocks, decode_blocks, and the resulting logit. It is the only place the router explains why it picked a worker. But the row carries no identity, so anything reading these logs can only group candidates into decisions by line adjacency.

This PR stamps request_id and worker_type on those rows, and request_id on the winner rows, making them self-joining. The selector change is +15/−0 and logging-only. The branch also repairs two pre-existing README links to the disaggregated-serving architecture page; their old redirect resolves to HTTP 404 and was failing the repository-wide docs-link check.

Details:

Adjacency is not sound here, for two structural reasons:

1. The rows are outside the request span. They are emitted from the SchedulerQueueActor task, which scheduling/queue.rs:409 spawns via tokio::spawn(actor.run(admission_rx)) with no .instrument(...). The caller's request span is therefore not in scope, and the logging layer cannot attach x_request_id/trace_id. This is exactly why [ROUTING] Best — emitted on the caller's task at llm/src/kv_router/push_router/selection.rs:183 — does carry x_request_id while these rows do not.
2. There is one actor per scheduler. A disaggregated deployment runs two (prefill and decode), so two concurrent tasks interleave into one log.

Measured on a 1.24 GB frontend-log sample from a 6-prefill + 1-decode deployment:

metric	value
candidate→winner agreement, overall	72.46%
…on 24-candidate prefill decisions	99.82%
…on 8-candidate decode decisions	42.98%
winners with no preceding candidate rows	14.40%

Decode-pool analysis is not currently possible from these logs, and the smaller a pool's candidate set, the more adjacency corrupts it.

The two fields:

• request_id — request.mode.request_id() is already reachable at the emission site and returns the same value [ROUTING] Best logs. That makes the candidate row self-joining to the client record in one hop, rather than requiring a bridge through the winner row (which is absent for 14.40% of decisions).
• worker_type — separates the two pools with no join at all. This matters beyond bookkeeping: the pools score differently. prefill_router/mod.rs's build_decode_router_override forces overlap_score_credit = 0.0 and track_prefill_tokens = false on the decode path, so decode candidates are load-only and have raw_prefill_blocks == 0 by construction. Aggregating the two pools mixes two different scoring regimes.

Alternatives considered:

• A monotonic decision counter. Rejected — it is a surrogate for a natural key already in hand, it does not survive a process restart, and it collides across router replicas (router_replica_sync), so aggregated logs from two frontends would share ids. It also puts mutable global state in a component scheduling/CLAUDE.md declares side-effect free.
• Propagating the caller's span across AdmissionCommand::Enqueue. This is the framework-correct fix — it would give x_request_id, trace_id, span_id and parent_id on every event inside selection, permanently. It is a larger, cross-crate change to the actor message type, so it belongs in its own PR. This one is the minimal change that makes the existing rows usable.

Cost: both fields are evaluated inside the macro, so they cost nothing when DEBUG is disabled. When enabled, request_id is a borrowed &str and worker_type a &'static str — nothing is allocated in selector.rs.

No scoring behaviour changes, and no function signatures change.

Where should the reviewer start?

lib/kv-router/src/scheduling/selector.rs contains the code change; README.md contains only the two URL corrections described above. Start with two places in selector.rs:

1. worker_logit (the two tracing::debug! candidate rows) — confirm the added fields are inside the macro invocation, so they are not evaluated when DEBUG is off, and that request.mode.request_id() introduces no allocation.
2. select_worker (the three tracing::info! winner rows: pinned, decode, general) — request_id is bound once and reused; confirm it matches what [ROUTING] Best logs so the two rows join.

Worth a skeptical eye: the unwrap_or("-") fallback. ScheduleMode::QueryOnly permits a None request id (prefill_router/query.rs passes None), so those rows are deliberately labelled rather than dropped — an explicit sentinel beats today's silent misattribution by adjacency, but say so if you'd prefer a different sentinel or an omitted field.

Related Issues

🚫 This PR is NOT linked to an issue:

• Confirmed — no related issue

Validation

• cargo test -p dynamo-kv-router --lib — 849 passed, 0 failed, 2 ignored
• cargo clippy -p dynamo-kv-router --no-deps --all-targets -- -D warnings — clean
• cargo fmt -p dynamo-kv-router — applied
• Lychee v0.24.2 with the workflow flags against README.md — 102 links checked, 0 errors
• pre-commit run --all-files — all hooks passed
• No selector test changes were needed, which is itself the behaviour-preservation check: the selector change is additive logging fields only.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[github-actions]

🌿 Fern Docs Preview: https://nvidia-preview-019faf9f-7439-711b-8f73-a17fd7cfa23c.docs.buildwithfern.com/dynamo/dev

[coderabbitai]

Walkthrough

Changes

Selector logging correlation

Layer / File(s)	Summary
Decision identifier and scoring logs lib/kv-router/src/scheduling/selector.rs	Adds a monotonic per-decision counter and propagates decision_id into worker_logit debug tracing.
Selection log wiring and test updates lib/kv-router/src/scheduling/selector.rs	Adds decision_id and request_id to pinned and final selection logs, updates scoring calls, and adjusts unit tests for the expanded helper signature.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and matches the main logging change in selector scoring rows.
Description check	✅ Passed	The description includes the required sections and clearly states that no related issue is linked.

---

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

[datadog-official]

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 44.41% (+6.48%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: f19f5d3 | Docs | Datadog PR Page | Give us feedback!}

[dynamo-ops]

/ok to test f92280d

[dynamo-ops]

/ok to test f19f5d3