README
¶
Speculation Path Scorer
Vendor-agnostic interface for scoring the paths in a batch's speculation tree — the predicted-success probability of each candidate bet, recomputed as the batch's world changes.
See the Speculation RFC for the end-to-end design and how scoring fits into the orchestrator pipeline.
Scorer
A path's score is a prediction: how likely is this bet to pay off, right now? The scorer answers it from the current state — the per-batch success probabilities of a path's base batches (entity.Batch.Score, set by the score stage), which of those dependencies have already landed or had their build pass (resolved assumptions raise confidence), and optionally other signals such as how long the batch has waited or historical pass rates. The score is the common currency the selector and prioritizer both rank on, so keeping it current is what makes both act on the latest reality.
Because it is a prediction over live state, the scorer is re-run on every respeculate, right after the controller reconciles path status — so when a dependency lands, its build passes, or a sibling path fails, the surviving paths' scores are recomputed before anything is selected or prioritized. The controller drives when to rescore (it is part of reconciliation) and persists the result; the scorer owns the formula.
This is the per-path scorer, distinct from the per-batch score stage, which sets entity.Batch.Score. The path scorer consumes those batch scores to score whole paths. The controller hands it the batch's speculation tree directly — the subject it scores — and any richer signal an implementation needs (the dependency batches' scores, historical pass rates) is injected at its factory, not passed in. It never writes: its only output is per-path scores, each naming a path by its ID, and the controller merges them into the tree and persists — the controller stays the single writer of tree state, and everything else about a path (structure, status) never passes through the scorer at all. Paths omitted from the result keep their last persisted score.
Scores are probabilities in [0, 1] — 0 is a bet certain to lose, 1 a bet certain to pay off. That is the contract every implementation must satisfy, and the controller enforces the range when it consumes the result. The selector and prioritizer rank on these values, so implementations sharing a queue must agree on this scale.
Factory
A per-queue factory returns the scorer for a queue, following the repo's extension contract. It is handed only the queue identity; scoring knobs and read access to any extra signals are injected at construction by the integrator in the wiring layer, which resolves per-queue settings through queueconfig. Scoring 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 Scorer serves.
QueueName string
}
Config carries the per-queue identity handed to a Factory. The system knows only the queue name; everything an implementation needs (scoring knobs, and read access to any extra signals such as the dependency batches' scores) is injected at construction by the integrator.
type Factory ¶
type Factory interface {
// For returns the Scorer for the given queue.
For(cfg Config) (Scorer, error)
}
Factory builds the Scorer for a queue. Implementations are provided by integrators (and tests) and inject whatever they need at construction.
type Scorer ¶
type Scorer interface {
// Score returns the freshly computed predicted-success score of each path in
// the tree as entity.PathScore values, keyed by path ID
// (entity.SpeculationPathInfo.ID). Paths omitted from the result keep their
// last persisted score. The combination formula is the implementation's
// concern; the returned values must be probabilities in [0, 1] — the
// controller enforces the range when it consumes them.
Score(ctx context.Context, tree entity.SpeculationTree) ([]entity.PathScore, error)
}
Scorer computes the predicted-success score of every path in a batch's speculation tree.
A path's score is a prediction — "how likely is this bet to pay off?" — and predictions must move as evidence arrives. The scorer answers "how good is each path right now" from the current state: the per-batch success probabilities of a path's base batches (entity.Batch.Score, set by the score stage), which of those dependencies have already landed or had their build pass (resolved assumptions raise confidence), and optionally other signals (how long the batch has waited, historical pass rates).
The controller re-runs the scorer on every respeculate, right after it reconciles path status — so when a dependency lands, its build passes, or a sibling path fails, the surviving paths' scores are recomputed against the new reality before anything is selected or prioritized. The controller drives *when* to rescore and persists the result; the scorer owns the *formula*.
This is the per-*path* scorer, distinct from the per-*batch* score stage (extension/scorer), which sets entity.Batch.Score. The path scorer consumes those batch scores to score whole paths.
The controller hands the scorer the batch's speculation tree directly — the subject it scores. Any richer signal an implementation needs (the dependency batches' scores, historical pass rates) is injected at its Factory, not passed here. It never writes: it returns per-path scores and the controller merges them into the tree and persists, keeping the controller the single writer of tree state.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package fake provides a programmable pathscorer.Scorer for tests and examples.
|
Package fake provides a programmable pathscorer.Scorer for tests and examples. |
|
Package mock is a generated GoMock package.
|
Package mock is a generated GoMock package. |
|
Package probability provides a pathscorer.Scorer that scores each path as the probability that exactly that path's assumption holds: every base dependency lands and every non-base dependency of the head does not.
|
Package probability provides a pathscorer.Scorer that scores each path as the probability that exactly that path's assumption holds: every base dependency lands and every non-base dependency of the head does not. |