README
¶
Speculation Path Selector
Vendor-agnostic interface for deciding what the orchestrator should do with each path in a batch's enumerated speculation tree.
See the Speculation RFC for the end-to-end design and how selection fits into the orchestrator pipeline.
Selector
A selector is the policy — the part that decides how aggressively to spend build resources. Given the candidate paths in the batch's tree and their current status, what should we do with each, right now? It returns an action per path — Promote (advance it one stage toward running) or Cancel. Strategies span a spectrum: build only the single optimistic path (cheapest — bet on the happy case), build every candidate (maximum parallelism, maximum build cost), or a top-K / budget-bounded subset in between.
The selector decides only where to spend build resources. It does not decide merging: a path becomes mergeable when its build passed and its base matches what actually landed, which is deterministic, not a policy choice — so the controller finalizes it on its own.
The controller hands the selector the batch's speculation tree directly — the subject it decides over. The controller is the single writer: it reconciles each path's status (candidate, selected, prioritized, building, passed, failed, cancelling, cancelled) from the latest builds and dependency states, and it maps each of the selector's decisions to a status transition — Promote → Selected, Cancel → Cancelling (or Cancelled when nothing is building) — applied under the tree's optimistic lock and persisted. The selector's only output is decisions, each naming a path by its ID, at most one per path; it never writes status. This keeps it a deterministic policy over the tree it is given.
Selection expresses desire, not admission: Selected means this batch wants to spend a build slot on the path, while Prioritized means the queue-wide prioritizer has actually admitted it under the shared build budget and it is cleared to build. A promoted path waits in Selected until the prioritizer clears it — with free budget it would move on promptly, under contention it may wait indefinitely or be dropped. That split exists because a selector sees only its own batch and cannot ration a budget shared across the whole queue.
Because it is re-run on every build signal, a selector can start narrow — build the optimistic path first — and widen later, committing more paths only once earlier bets resolve. Returning no action for a path leaves it as-is. Policy parameters — a top-K cap, a build budget, an experiment toggle — are configured when the selector is constructed rather than passed through this contract.
Factory
A per-queue factory returns the selector for a queue, following the repo's extension contract. It is handed only the queue identity and nothing else; policy knobs — a top-K cap, a build budget, an experiment toggle — are injected at construction by the integrator in the wiring layer, which resolves per-queue settings through queueconfig. Selection itself stays config-free.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// QueueName identifies the queue this Selector serves.
QueueName string
}
Config carries the per-queue identity handed to a Factory. The system knows only the queue name; policy knobs such as a top-K cap or build budget are injected at construction by the integrator.
type Factory ¶
type Factory interface {
// For returns the Selector for the given queue.
For(cfg Config) (Selector, error)
}
Factory builds the Selector for a queue. Implementations are provided by integrators (and tests) and inject whatever they need at construction.
type Selector ¶
type Selector interface {
// Select returns the decisions to take for the given tree, at most one per
// path (the controller treats conflicting duplicates as a policy bug and
// skips them). Returning multiple Promote decisions selects several paths
// for building in parallel — each waits for the prioritizer to clear it
// under the queue's build budget before a build is dispatched. An empty
// result means nothing should be done right now. Paths the selector has no
// opinion on are simply omitted (leave-as-is).
Select(ctx context.Context, tree entity.SpeculationTree) ([]entity.PathDecision, error)
}
Selector decides what the controller should do with each path in a batch's speculation tree.
Selection is the policy: it answers "which futures do we spend build resources on, and how many, right now". It reads the batch's tree — each path's controller-stamped Status (Candidate / Selected / Prioritized / Building / Passed / Failed / Cancelling / Cancelled) and Score — and returns a decision per path it wants to act on.
The controller hands the selector the batch's speculation tree directly — the subject it decides over. Its only output is decisions (Promote / Cancel), each naming a path by its ID (entity.SpeculationPathInfo.ID); it never writes Status. The controller maps each decision to a status transition — Promote → Selected, Cancel → Cancelling (or Cancelled) — applied under the tree's optimistic lock, and persists it, staying the single writer of tree state. This keeps the selector a deterministic policy over the tree it is given. Policy knobs such as a top-K limit or budget belong to the implementation's construction, not this method.
Source Files
Directories