docs(rfc): queue-scoped speculation design#413
Merged
Conversation
behinddwalls
marked this pull request as ready for review
July 21, 2026 03:28
behinddwalls
force-pushed
the
speculation-rfc
branch
2 times, most recently
from
July 21, 2026 21:21
e0ac903 to
55dd290
Compare
sbalabanov
requested changes
Jul 22, 2026
sbalabanov
left a comment
Contributor
There was a problem hiding this comment.
back to you based on brainstorming session
behinddwalls
force-pushed
the
speculation-rfc
branch
from
July 22, 2026 19:21
55dd290 to
b98e465
Compare
JamyDev
reviewed
Jul 22, 2026
JamyDev
reviewed
Jul 22, 2026
behinddwalls
force-pushed
the
speculation-rfc
branch
from
July 22, 2026 22:01
b98e465 to
a3f6bf6
Compare
JamyDev
approved these changes
Jul 23, 2026
sbalabanov
approved these changes
Jul 23, 2026
| // dependency appears exactly once, in queue order, so the path is self-describing. | ||
| type SpeculationPath struct { | ||
| Head string // the batch being built | ||
| Bets []DependencyBet // one bet per dependency of Head, in queue order |
Contributor
There was a problem hiding this comment.
doesn't it duplicate SpeculationPath ?
Collaborator
Author
There was a problem hiding this comment.
It just captures all deps, regardless of dropped or being excluded in a path so finalization and bypassing logic can make those decisions based on the bet itself.. as when we relax, Batch.Deps would be different from what Bet gets
behinddwalls
force-pushed
the
speculation-rfc
branch
from
July 23, 2026 22:34
a3f6bf6 to
54b98ab
Compare
## Summary ### Why? A merge queue that verifies one change at a time is bounded by its slowest build. Speculation builds a batch early against a guess at how its unresolved dependencies will resolve, so a matching build is ready when reality settles while merging stays strict. Getting that right on an eventually consistent, transactionless store needs an explicit design for how a path is represented, which paths build under a bounded CI budget, what is persisted, and where each decision lives. ### What? This RFC designs speculation for SubmitQueue end to end. Each queue change fires one run per queue: the speculate controller reads the current facts once, reconciles path state, refutes broken bets, finalizes verdicts, asks one pluggable extension which paths to build or preempt, and writes the result. Only chosen paths are persisted; every other possibility is recomputed each run. The Speculator is the only controller-facing extension. It chooses which paths to build and which running ones to cancel, while verdicts and correctness cancels remain controller rules. The default Speculator internally composes a Generator, which produces a lazy best-first candidate stream, and an Allocator, which spends the CI budget and settles in-flight paths by ID; alternate Speculators need not preserve that split. A path is self-describing: it carries an included, excluded, or dropped bet on every dependency. Its identity hashes the head plus its bets, build dispatches are replayed idempotently by path and attempt, and pending, building, and cancelling paths continue to charge the hard CI budget until terminal. The design also covers conflict relaxation and bypassing a large dependency once passed builds cover every possible resolution. The RFC fills the previously empty `doc/rfc/submitqueue/speculation.md`.
behinddwalls
force-pushed
the
speculation-rfc
branch
from
July 23, 2026 22:40
54b98ab to
3091616
Compare
behinddwalls
temporarily deployed
to
stack-rebase
July 23, 2026 22:55 — with 
GitHub Actions
Inactive
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Why?
A merge queue that verifies one change at a time is bounded by its slowest build. Speculation builds a batch early against a guess at how its unresolved dependencies will resolve, so a matching build is ready when reality settles while merging stays strict. Getting that right on an eventually consistent, transactionless store needs an explicit design for how a path is represented, which paths build under a bounded CI budget, what is persisted, and where each decision lives.
What?
This RFC designs speculation for SubmitQueue end to end. Each queue change fires one run per queue: the speculate controller reads the current facts once, reconciles path state, refutes broken bets, finalizes verdicts, asks one pluggable extension which paths to build or preempt, and writes the result. Only chosen paths are persisted; every other possibility is recomputed each run.
The Speculator is the only controller-facing extension. It chooses which paths to build and which running ones to cancel, while verdicts and correctness cancels remain controller rules. The default Speculator internally composes a Generator, which produces a lazy best-first candidate stream, and an Allocator, which spends the CI budget and settles in-flight paths by ID; alternate Speculators need not preserve that split.
A path is self-describing: it carries an included, excluded, or dropped bet on every dependency. Its identity hashes the head plus its bets, build dispatches are replayed idempotently by path and attempt, and pending, building, and cancelling paths continue to charge the hard CI budget until terminal. The design also covers conflict relaxation and bypassing a large dependency once passed builds cover every possible resolution.
The RFC fills the previously empty
doc/rfc/submitqueue/speculation.md.