Skip to content

docs(rfc): queue-scoped speculation design#413

Open
behinddwalls wants to merge 1 commit into
mainfrom
speculation-rfc
Open

docs(rfc): queue-scoped speculation design#413
behinddwalls wants to merge 1 commit into
mainfrom
speculation-rfc

Conversation

@behinddwalls

@behinddwalls behinddwalls commented Jul 21, 2026

Copy link
Copy Markdown
Collaborator

Summary

Why?

A merge queue that verifies one change at a time is bounded by its slowest build. Speculation pipelines it — building a batch early against a guess at how its unresolved dependencies will resolve, so a matching build is already done when reality settles. Doing that correctly on an eventually consistent, transactionless substrate needs a real design: how futures are represented, which ones build under a bounded CI budget, what is persisted, and where each decision lives.

What?

This RFC designs speculation for SubmitQueue end to end. Every queue change runs a pass: read the current facts, apply fixed rules, ask one pluggable extension which paths to build, and write the result. Only chosen paths are persisted (a path set per head, each chosen path keyed by a content hash so crash recovery is idempotent); the rest are recomputed each pass, never stored. The one extension — the Speculator — decides which paths to build and which running ones to preempt; verdicts (merge/fail/cancel) and refutation cancels stay controller rules, so a swapped-in extension can never merge or fail a batch. The default Speculator composes three per-queue tuning interfaces: PathScorer (prices a path as the product of its dependencies' landing chances), Generator (a lazy best-first candidate stream per head that caps its own planning depth), and Allocator (spends the build budget across heads under a score floor and settles in-flight paths by ID).

This fills the previously empty doc/rfc/submitqueue/speculation.md.

@behinddwalls
behinddwalls marked this pull request as ready for review July 21, 2026 03:28
@behinddwalls
behinddwalls requested review from a team and sbalabanov as code owners July 21, 2026 03:28
## Summary

### Why?

A merge queue that verifies one change at a time is bounded by its slowest build. Speculation pipelines it — building a batch early against a guess at how its unresolved dependencies will resolve, so a matching build is already done when reality settles. Doing that correctly on an eventually consistent, transactionless substrate needs a real design: how futures are represented, which ones build under a bounded CI budget, what is persisted, and where each decision lives.

### What?

This RFC designs speculation for SubmitQueue end to end. Every queue change runs a pass: read the current facts, apply fixed rules, ask one pluggable extension which paths to build, and write the result. Only chosen paths are persisted (a path set per head, each chosen path keyed by a content hash so crash recovery is idempotent); the rest are recomputed each pass, never stored. The one extension — the Speculator — decides which paths to build and which running ones to preempt; verdicts (merge/fail/cancel) and refutation cancels stay controller rules, so a swapped-in extension can never merge or fail a batch. The default Speculator composes three per-queue tuning interfaces: PathScorer (prices a path as the product of its dependencies' landing chances), Generator (a lazy best-first candidate stream per head that caps its own planning depth), and Allocator (spends the build budget across heads under a score floor and settles in-flight paths by ID).

This fills the previously empty doc/rfc/submitqueue/speculation.md.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant