Fix: size HBG ready queues from reachable tasks

[TaoZQY]

Summary

• derive every HBG ready-queue capacity from the tasks that can reach it at bind time
• cache a routing histogram once per distinct Graph Definition and apply it for each Graph submission
• count predicated tasks toward both the dummy queue and their normal/sync queue, because the predicate is resolved on device
• round logical capacities up to a power of two, reserve a reusable 32768-entry ceiling, and reject larger graphs during bind with READY_QUEUE_OVERFLOW
• keep the a2a3 and a5 implementations mirrored and add shared Qwen-scale/boundary tests

Design

The ready queue has no recoverable full path, so its capacity is a correctness bound rather than a tuning hint. The host task window is scanned once after orchestration. Graph nodes are not materialized in that window, so each distinct Graph Definition is walked once to build a routing histogram, then that histogram is added once per Graph submission/replay.

Each queue receives the smallest power-of-two capacity that can hold its reachable population (minimum 2). The shared-memory arena remains fixed and reusable, with a bounded capacity of 32768 entries per queue. Inputs above that supported bound fail during bind instead of reaching a fatal queue-full condition on device.

This is intentionally scoped to HBG queue sizing: no retry/backpressure protocol or scheduler redesign is introduced.

Testing

• runtime editable build on latest main
• C++ unit tests: 117/117 passed
• a2a3sim HBG scope: 14 passed, 7 skipped
• a5sim HBG scope: 11 passed
• pre-commit: all hooks passed
• a2a3 onboard Qwen3-14B decode, GraphExecutionBatch16Seq3500, 3/3 rounds with golden validation passed (task_20260824_003633_278330810026); device time was 37.77-38.36 ms

Performance check

A 100-round baseline/current comparison on the issue branch showed typical device latency unchanged within noise:

• steady mean: 39.03 ms -> 39.18 ms (+0.38%)
• median: 39.86 ms -> 39.99 ms (+0.32%)

Fixes #1920

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d1600641-2c15-403f-80fc-b8878f62b32c

📥 Commits

Reviewing files that changed from the base of the PR and between 66ba5c4 and 33d6f14.

📒 Files selected for processing (9)

• src/a2a3/runtime/host_build_graph/host/runtime_maker.cpp
• src/a2a3/runtime/host_build_graph/runtime/runtime_types.h
• src/a2a3/runtime/host_build_graph/runtime/scheduler/scheduler.h
• src/a2a3/runtime/host_build_graph/runtime/shared/runtime_init.cpp
• src/a5/runtime/host_build_graph/host/runtime_maker.cpp
• src/a5/runtime/host_build_graph/runtime/runtime_types.h
• src/a5/runtime/host_build_graph/runtime/scheduler/scheduler.h
• src/a5/runtime/host_build_graph/runtime/shared/runtime_init.cpp
• tests/ut/cpp/common/test_hbg_ready_queue_seed.cpp

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The host build graph now computes ready-queue populations from submitted tasks and graph definitions. It derives per-queue capacities, rejects populations above the configured limit, and uses the capacities when reserving and initializing scheduler queues.

Changes

Ready-queue capacity derivation

Layer / File(s)	Summary
Population model and capacity derivation src/a2a3/runtime/host_build_graph/runtime/..., src/a5/runtime/host_build_graph/runtime/...	The fixed queue-size macro is replaced by READY_QUEUE_CAPACITY_LIMIT. New population and capacity structures track task categories and resource shapes, enforce the limit, and derive power-of-two capacities.
Host population collection src/a2a3/runtime/host_build_graph/host/runtime_maker.cpp, src/a5/runtime/host_build_graph/host/runtime_maker.cpp	Host orchestration validates total_tasks, counts submitted task populations, aggregates graph-definition populations, and publishes derived capacities or the latched overflow status.
Scheduler reservation and validation src/a2a3/runtime/host_build_graph/runtime/..., src/a5/runtime/host_build_graph/runtime/..., tests/ut/cpp/common/test_hbg_ready_queue_seed.cpp	Scheduler reservations and queue headers use individual derived capacities. Tests cover Qwen sizing, multi-queue derivation, and the capacity-limit boundary.

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

Merge Risk: ⚪ Minimal · up to 33d6f

The change sizes HBG ready queues from reachable tasks and rejects graphs above the supported bound; reported tests and performance checks pass, so no actionable merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant HostOrchestration
  participant GraphDefinitions
  participant ReadyQueuePopulations
  participant SchedulerLayout
  participant Scheduler
  HostOrchestration->>ReadyQueuePopulations: Count submitted task-slot populations
  HostOrchestration->>GraphDefinitions: Bind uploaded definitions
  GraphDefinitions->>ReadyQueuePopulations: Add definition node populations
  ReadyQueuePopulations->>SchedulerLayout: Derive per-queue capacities
  SchedulerLayout->>Scheduler: Reserve and initialize queue storage

Loading

Poem

I’m a rabbit with queues in a row,
Counting each task as I go.
Capacities bloom,
Overflow finds room—
And schedulers ready to flow.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: sizing HBG ready queues from reachable tasks.
Description check	✅ Passed	The description directly explains bind-time queue sizing, overflow handling, mirrored implementations, and testing.
Linked Issues check	✅ Passed	The changes satisfy issue #1920 by deriving per-queue capacities, counting reachable tasks, enforcing the reservation ceiling, and failing during bind on overflow.
Out of Scope Changes check	✅ Passed	The changes remain within issue #1920 scope and support the stated implementation with mirrored code and focused tests.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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