Skip to content

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

Merged
behinddwalls merged 1 commit into
mainfrom
preetam/ext/speculation-prioritizer
Jul 12, 2026
Merged

feat(speculation): add prioritizer + prioritization-limit extensions#320
behinddwalls merged 1 commit into
mainfrom
preetam/ext/speculation-prioritizer

Conversation

@behinddwalls

@behinddwalls behinddwalls commented Jul 8, 2026

Copy link
Copy Markdown
Collaborator

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

prioritizer: selection is per batch and blind to other batches, so it cannot ration a shared build budget. The prioritizer sees every path across the queue's in-flight batches that runs or wants to run (Selected / Prioritized / Building, each carrying its ID and score), ranks them — scores are probabilities in [0, 1] per the path scorer's contract — and returns sparse decisions naming paths by ID: Promote to admit under the budget, Cancel to preempt, at most one decision per path. Whether it preempts at all is implementation policy (sticky-slots vs preemptive). It never writes: the controller maps each decision back to its tree and applies the status transition under that tree's optimistic lock. Prioritized thus means exactly "admitted under the queue's build budget, cleared to build, not yet building".

prioritizationlimit: the "how much" policy bounding the queue's concurrent speculation builds — the budget the prioritizer admits against. Injected into the prioritizer at construction and applied by it, keeping the interface limit-free; the value is signal-driven, 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.

Stack

  1. feat(entity): give speculation paths an assigned identity #337
  2. feat(speculation): add enumerator + dependency-limit extensions #315
  3. feat(speculation): add path scorer extension #316
  4. feat(speculation): add selector + selection-limit extensions #317
  5. @ feat(speculation): add prioritizer + prioritization-limit extensions #320
  6. feat(storage,entity): path identity + speculation path→build mapping store #331
  7. feat(speculation): add parity default impls for the speculation seams #332
  8. feat(speculation): add probability path scorer #333

@behinddwalls behinddwalls marked this pull request as ready for review July 8, 2026 23:20
@behinddwalls behinddwalls requested review from a team and sbalabanov as code owners July 8, 2026 23:20
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-selector branch from 0ab1871 to d9084c2 Compare July 9, 2026 17:02
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from 844dbfc to ade23bb Compare July 9, 2026 17:03
@behinddwalls behinddwalls marked this pull request as draft July 9, 2026 17:03
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-selector branch from d9084c2 to 0ae2849 Compare July 9, 2026 17:42
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from ade23bb to 2516cc1 Compare July 9, 2026 17:42
behinddwalls added a commit that referenced this pull request Jul 9, 2026
## 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
@behinddwalls behinddwalls marked this pull request as ready for review July 9, 2026 20:37
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from 2516cc1 to c7caaa6 Compare July 10, 2026 01:31
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-selector branch from 0ae2849 to 59ce810 Compare July 10, 2026 01:31
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from c7caaa6 to b9fb69b Compare July 10, 2026 01:33
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-selector branch from 59ce810 to 607704c Compare July 10, 2026 01:33
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from b9fb69b to f3c68e1 Compare July 10, 2026 03:31
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-selector branch from 607704c to c9633a9 Compare July 10, 2026 03:31
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-selector branch from c9633a9 to 84ad089 Compare July 10, 2026 19:24
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from f3c68e1 to 0426ccb Compare July 10, 2026 19:24
Comment thread submitqueue/extension/speculation/prioritizer/README.md
Comment thread submitqueue/extension/speculation/prioritizer/README.md Outdated
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-selector branch from 84ad089 to ef8c027 Compare July 11, 2026 05:02
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-selector branch from ef8c027 to 77ee7b5 Compare July 11, 2026 05:24
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from 55d0b08 to 87f2056 Compare July 11, 2026 05:24
behinddwalls added a commit that referenced this pull request Jul 12, 2026
## Summary
### Why?

The speculation seams being introduced up-stack (path scorer, selector,
prioritizer) and durable links from other entities (a path→build
mapping) all need to refer to one specific path inside a batch's
speculation tree. Restating the full Base/Head split in every seam
output couples those contracts to path structure and forces consumers to
compare ordered slices; a single opaque identity lets each seam return
only what matters — a path ID plus its verdict — and gives durable links
a stable key to hang on.

### What?

`entity.SpeculationPathInfo` gains `ID`: assigned by the controller when
the path entry is first persisted, immutable thereafter, and unique
within its tree. Its format is the controller's choice and carries no
meaning — it is never parsed. Everything outside the tree names a path
by this ID. The tree store persists it transparently through the JSON
`paths` column, so the change is additive with no schema migration.

## Test Plan
✅ `bazel test //submitqueue/entity/...` — entity suite passes; the field
rides the existing JSON round-trip in the tree store.

## Issues


## Stack
1. @ #337
1. #315
1. #316
1. #317
1. #320
1. #331
1. #332
1. #333
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-selector branch from 77ee7b5 to 59bdcde Compare July 12, 2026 21:07
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from 87f2056 to 03c3b63 Compare July 12, 2026 21:07
behinddwalls added a commit that referenced this pull request Jul 12, 2026
## Summary
Add the first speculation seam and its limit counterpart from the
speculation RFC, as vendor-agnostic extension interfaces under
submitqueue/extension/speculation/.

enumerator: given a batch and its active dependencies ordered
oldest-first (queue arrival order — the ordering that fixes which
assumed-good Base prefixes exist), mechanically lists the candidate
Base/Head speculation paths — pure, deterministic, and purely
structural. It returns only []entity.SpeculationPath: identity, status,
and score are controller-owned, and the controller wraps each path into
the persisted tree entry (SpeculationPathInfo), keeping a clean
ownership boundary between the seam and tree state.

dependencylimit: the "how much" policy bounding how many active
(in-flight) dependencies a batch may speculate over. It is the
eligibility gate before enumeration; unlike the other speculation limits
it is controller-held rather than injected into a seam, keeping the
enumerator pure. The value is signal-driven, not a fixed constant.

Each follows the repo extension contract (conflict.Analyzer reference
shape): Factory.For(Config) (T, error) with Config carrying only
QueueName; behavioral knobs and limit signals are integrator-injected at
construction. Includes READMEs, gomock packages, and Makefile mock-gen
wiring. Interfaces only; concrete impls and controller wiring are
deferred.

## Test Plan


## Issues


## Stack
1. #337
1. @ #315
1. #316
1. #317
1. #320
1. #331
1. #332
1. #333
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-selector branch from 59bdcde to e435984 Compare July 12, 2026 21:07
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from 03c3b63 to 6f3e86b Compare July 12, 2026 21:07
behinddwalls added a commit that referenced this pull request Jul 12, 2026
Add the scorer seam from the speculation RFC, as a vendor-agnostic
extension interface under submitqueue/extension/speculation/pathscorer/.

The scorer computes each speculation path's predicted-success score from
the current state: the per-batch scores of the path's base batches
(entity.Batch.Score) and which of those dependencies have resolved
(landed or build-passed), plus optionally other signals. It is a
prediction over live state, so the controller re-runs it on every
respeculate right after reconciling status, and persists the result; the
scorer owns only the formula.

The controller hands it the batch's speculation tree directly — the
subject it scores. Any richer signal an implementation needs (dependency
batch scores, historical pass rates) is injected at its Factory, not put
in the signature. It never writes: its only output is per-path scores
([]entity.PathScore — path ID plus fresh score, an entity-level
seam-output type alongside the path-decision type), which the controller
merges into the tree and persists, staying the single writer of tree
state; structure and status never pass through the scorer. Scores are
probabilities in [0, 1] — the contract every implementation must
satisfy, enforced by the controller on consume.

This is the per-path scorer, distinct from the existing per-batch score
stage (`extension/scorer`) that sets entity.Batch.Score — the path
scorer consumes those to score whole paths.

Follows the repo extension contract: Factory.For(Config) (Scorer, error)
with Config carrying only QueueName. Includes README, gomock package,
and a programmable fake. The speculation RFC's seam descriptions are
updated to match the identity-keyed minimal-output contracts (and gain a
design-decision entry for assigned path identity). Interface only;
concrete impls and controller wiring are deferred.


## Stack
1. #337
1. #315
1. @ #316
1. #317
1. #320
1. #331
1. #332
1. #333
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-selector branch from e435984 to fa78ebb Compare July 12, 2026 21:08
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from 6f3e86b to a2bd5b4 Compare July 12, 2026 21:08
behinddwalls added a commit that referenced this pull request Jul 12, 2026
Add the selector seam and its limit counterpart from the speculation
RFC, as vendor-agnostic extension interfaces under
submitqueue/extension/speculation/.

selector: the controller hands it the batch's speculation tree; it
returns per-path decisions (Promote/Cancel), each naming a path by its
ID (entity.SpeculationPathInfo.ID), for the paths it chooses to act on —
at most one decision per path, with conflicting duplicates treated by
the controller as a policy bug (applied first, logged and skipped
after). It is the policy seam — it reads the tree it is given and emits
decisions only, never writing status, and does not decide merging. The
controller maps each decision to a guarded status transition (Promote →
Selected, Cancel → Cancelling/Cancelled) and persists it, staying the
single writer of tree state. entity.PathDecision correspondingly names
paths by PathID rather than restating the Base/Head split.

selectionlimit: the "how much" policy bounding how many paths a batch
may build in parallel. It is the selector's companion — the selector
decides which paths, the limit decides how many. Injected into the
selector at construction and called by it, keeping the selector
interface limit-free; 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.


## Stack
1. #337
1. #315
1. #316
1. @ #317
1. #320
1. #331
1. #332
1. #333
Add the queue-wide prioritizer seam and its limit counterpart from the speculation RFC, as vendor-agnostic extension interfaces under submitqueue/extension/speculation/.

prioritizer: selection is per batch and blind to other batches, so it cannot ration a shared build budget. The prioritizer sees every path across the queue's in-flight batches that runs or wants to run (Selected / Prioritized / Building, each carrying its ID and score), ranks them — scores are probabilities in [0, 1] per the path scorer's contract — and returns sparse decisions naming paths by ID: Promote to admit under the budget, Cancel to preempt, at most one decision per path. Whether it preempts at all is implementation policy (sticky-slots vs preemptive). It never writes: the controller maps each decision back to its tree and applies the status transition under that tree's optimistic lock. Prioritized thus means exactly "admitted under the queue's build budget, cleared to build, not yet building".

prioritizationlimit: the "how much" policy bounding the queue's concurrent speculation builds — the budget the prioritizer admits against. Injected into the prioritizer at construction and applied by it, keeping the interface limit-free; the value is signal-driven, 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.
@behinddwalls behinddwalls force-pushed the preetam/ext/speculation-prioritizer branch from a2bd5b4 to 5c5dafc Compare July 12, 2026 21:08
@behinddwalls behinddwalls changed the base branch from preetam/ext/speculation-selector to main July 12, 2026 21:08
@behinddwalls behinddwalls merged commit bce0f4e into main Jul 12, 2026
2 checks passed
@behinddwalls behinddwalls deployed to stack-rebase July 12, 2026 21:08 — with GitHub Actions Active
@behinddwalls behinddwalls deleted the preetam/ext/speculation-prioritizer branch July 12, 2026 21:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants