feat(speculation): add prioritizer + prioritization-limit extensions by behinddwalls · Pull Request #320 · uber/submitqueue

behinddwalls · 2026-07-08T23:15:00Z

Summary

Add the prioritizer seam and its limit counterpart from the speculation RFC, as vendor-agnostic extension interfaces under submitqueue/extension/speculation/.

prioritizer: the queue-wide policy that rations a shared build budget across every in-flight batch. The controller hands it the queue's candidate paths — every path that is Selected (wants a slot) or Prioritized/Building (holds a slot), each with its score — and it returns sparse decisions: Promote to admit a pending path, Cancel to preempt a running one; omitted paths are left as-is. Whether it preempts is its own per-queue policy (sticky-slots vs preemptive), so the interface is unchanged either way. It never writes; the controller maps each decision to a guarded status transition (Promote → Prioritized, Cancel → Cancelling) and enacts it, staying the single writer. It shares the selector's SpeculationPathDecision output and ranks on the scorer's path Score, so it lives in the same speculation/ family.

prioritizationlimit: the "how much" policy bounding how many builds the queue runs at once — the queue's concurrent-build budget and the ultimate cap on speculation's demand on CI. Injected into the prioritizer at construction and called by it; the value is dynamic, not a fixed constant.

Each follows the repo extension contract: Factory.For(Config) (T, error) with Config carrying only QueueName. Includes READMEs, gomock packages, and programmable fakes. Interfaces only; concrete impls and controller wiring are deferred.

Test Plan

Issues

Stack

## Summary Reshape the speculation tree data model around the Base/Head path that the build stage actually consumes, and align its store with the speculation design. entity: SpeculationPath{Base, Head} becomes the unit; SpeculationPathInfo carries the path plus its Score, controller-owned Status (candidate/selected/prioritized/building/passed/failed/cancelling/cancelled), and BuildID — Path is immutable once persisted, Score/Status/BuildID are updateable by the controller. Score is scorer-computed and controller-persisted dynamic state — recomputed on every respeculate, not set at enumeration. Selected/Prioritized and Cancelling/Cancelled split desire vs budget-cleared and cancel-intent vs terminal, so the persisted status carries the cross-stage contract. Adds SpeculationPathAction (Promote/Cancel) and SpeculationPathDecision for the selector and prioritizer seams. SpeculationTree.Speculations becomes Paths, and the tree gains a Version for optimistic locking (starts at 1, incremented per change). The Build entity uses the shared SpeculationPath (Head = the batch under verification) and drops its own Score, which was never populated or read. storage: SpeculationTreeStore.UpdateSpeculations(batchID, []SpeculationInfo) becomes a pure conditional write — Update(ctx, batchID, oldVersion, newVersion, paths) — returning ErrVersionMismatch when the persisted version does not match, per the repo's optimistic-locking pattern (version arithmetic owned by the controller). The MySQL impl treats rowsAffected == 1 as success, 0 as version mismatch, and anything else as a generic error. The MySQL column speculations is renamed paths and the schema gains a version column. MySQL impl, mock, and storage integration coverage (create/get round-trip, duplicate, versioned whole-tree overwrite, stale-write rejection, not-found) added/updated. ## Test Plan ## Issues ## Stack 1. @ #231 1. #315 1. #316 1. #317 1. #320

Add the prioritizer seam and its limit counterpart from the speculation RFC, as vendor-agnostic extension interfaces under submitqueue/extension/speculation/. prioritizer: the queue-wide policy that rations a shared build budget across every in-flight batch. The controller hands it the queue's candidate paths — every path that is Selected (wants a slot) or Prioritized/Building (holds a slot), each with its score — and it returns sparse decisions: Promote to admit a pending path, Cancel to preempt a running one; omitted paths are left as-is. Whether it preempts is its own per-queue policy (sticky-slots vs preemptive), so the interface is unchanged either way. It never writes; the controller maps each decision to a guarded status transition (Promote → Prioritized, Cancel → Cancelling) and enacts it, staying the single writer. It shares the selector's SpeculationPathDecision output and ranks on the scorer's path Score, so it lives in the same speculation/ family. prioritizationlimit: the "how much" policy bounding how many builds the queue runs at once — the queue's concurrent-build budget and the ultimate cap on speculation's demand on CI. Injected into the prioritizer at construction and called by it; the value is dynamic, not a fixed constant. Each follows the repo extension contract: Factory.For(Config) (T, error) with Config carrying only QueueName. Includes READMEs, gomock packages, and programmable fakes. Interfaces only; concrete impls and controller wiring are deferred.

albertywu · 2026-07-10T22:37:35Z

+
+## Prioritizer
+
+Selection is per batch and blind to other batches, so it cannot ration a shared budget: if every batch promoted generously, their combined demand could swamp CI. The prioritizer closes that gap. It sees every path across all of the queue's in-flight batches that is running or wants to run, ranks them by each path's score (plus any fairness or tie-break policy), and admits only the subset that fits the queue's concurrent-build budget. Selection expresses *desire* per batch; prioritization reconciles that desire against *supply* — it is the queue-wide enforcer.


Is there any contract on what score values can be, for example are scores always in [0, 1] range or something else? Or Prioritizer doesn't care as long as there is some ordering it will use relative ordering to decide on a stack-rank of paths using path score?

albertywu · 2026-07-10T22:49:19Z

+
+Selection is per batch and blind to other batches, so it cannot ration a shared budget: if every batch promoted generously, their combined demand could swamp CI. The prioritizer closes that gap. It sees every path across all of the queue's in-flight batches that is running or wants to run, ranks them by each path's score (plus any fairness or tie-break policy), and admits only the subset that fits the queue's concurrent-build budget. Selection expresses *desire* per batch; prioritization reconciles that desire against *supply* — it is the queue-wide enforcer.
+
+The controller hands the prioritizer the queue's candidate paths directly — every path that is `Selected` (wants a slot) or `Prioritized`/`Building` (holds a slot), each carrying its score. It returns **sparse decisions**: `Promote` to admit a pending path, `Cancel` to preempt a running one. Paths it omits are left as-is. It never writes: the controller groups the decisions by `Path.Head` (the batch ID) to locate each affected tree, maps each decision to a status transition (`Promote` → `Prioritized`, `Cancel` → `Cancelling`) applied under that tree's optimistic lock, and enacts it, staying the single writer.


Does Prioritized mean "Waiting to Build" or something? Unclear to me what Prioritized means here

Maybe Admitted if it means the path is admitted through the build gates but has not actually started building yet?

behinddwalls added the ChangesPlanned label Jul 8, 2026

behinddwalls marked this pull request as ready for review July 8, 2026 23:20

behinddwalls requested review from a team and sbalabanov as code owners July 8, 2026 23:20

behinddwalls force-pushed the preetam/ext/speculation-selector branch from 0ab1871 to d9084c2 Compare July 9, 2026 17:02

behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from 844dbfc to ade23bb Compare July 9, 2026 17:03

behinddwalls marked this pull request as draft July 9, 2026 17:03

behinddwalls force-pushed the preetam/ext/speculation-selector branch from d9084c2 to 0ae2849 Compare July 9, 2026 17:42

behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from ade23bb to 2516cc1 Compare July 9, 2026 17:42

behinddwalls marked this pull request as ready for review July 9, 2026 20:37

behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from 2516cc1 to c7caaa6 Compare July 10, 2026 01:31

behinddwalls force-pushed the preetam/ext/speculation-selector branch from 0ae2849 to 59ce810 Compare July 10, 2026 01:31

behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from c7caaa6 to b9fb69b Compare July 10, 2026 01:33

behinddwalls force-pushed the preetam/ext/speculation-selector branch from 59ce810 to 607704c Compare July 10, 2026 01:33

behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from b9fb69b to f3c68e1 Compare July 10, 2026 03:31

behinddwalls force-pushed the preetam/ext/speculation-selector branch from 607704c to c9633a9 Compare July 10, 2026 03:31

This was referenced Jul 10, 2026

feat(storage,entity): path identity + speculation path→build mapping store #331

Open

feat(speculation): add parity default impls for the speculation seams #332

Open

feat(speculation): add probability path scorer #333

Open

behinddwalls force-pushed the preetam/ext/speculation-selector branch from c9633a9 to 84ad089 Compare July 10, 2026 19:24

behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from f3c68e1 to 0426ccb Compare July 10, 2026 19:24

albertywu reviewed Jul 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(speculation): add prioritizer + prioritization-limit extensions#320

feat(speculation): add prioritizer + prioritization-limit extensions#320
behinddwalls wants to merge 1 commit into
preetam/ext/speculation-selectorfrom
preetam/ext/speculation-prioritizer

behinddwalls commented Jul 8, 2026 •

edited

Loading

Uh oh!

albertywu Jul 10, 2026

Uh oh!

albertywu Jul 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## Prioritizer

		Selection is per batch and blind to other batches, so it cannot ration a shared budget: if every batch promoted generously, their combined demand could swamp CI. The prioritizer closes that gap. It sees every path across all of the queue's in-flight batches that is running or wants to run, ranks them by each path's score (plus any fairness or tie-break policy), and admits only the subset that fits the queue's concurrent-build budget. Selection expresses desire per batch; prioritization reconciles that desire against supply — it is the queue-wide enforcer.


		Selection is per batch and blind to other batches, so it cannot ration a shared budget: if every batch promoted generously, their combined demand could swamp CI. The prioritizer closes that gap. It sees every path across all of the queue's in-flight batches that is running or wants to run, ranks them by each path's score (plus any fairness or tie-break policy), and admits only the subset that fits the queue's concurrent-build budget. Selection expresses desire per batch; prioritization reconciles that desire against supply — it is the queue-wide enforcer.

		The controller hands the prioritizer the queue's candidate paths directly — every path that is `Selected` (wants a slot) or `Prioritized`/`Building` (holds a slot), each carrying its score. It returns sparse decisions: `Promote` to admit a pending path, `Cancel` to preempt a running one. Paths it omits are left as-is. It never writes: the controller groups the decisions by `Path.Head` (the batch ID) to locate each affected tree, maps each decision to a status transition (`Promote` → `Prioritized`, `Cancel` → `Cancelling`) applied under that tree's optimistic lock, and enacts it, staying the single writer.

Uh oh!

Conversation

behinddwalls commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test Plan

Issues

Stack

Uh oh!

albertywu Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

albertywu Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

behinddwalls commented Jul 8, 2026 •

edited

Loading