feat(speculation): generator contract and bestfirst impl

submitqueue/entity/speculation.go

@@ -196,8 +196,8 @@ type CandidatePath struct {
 	// Path is the candidate: a head plus one assumption per dependency.
 	Path SpeculationPath
 	// RankingScore is the score the Generator ranked this candidate by. Higher
-	// sorts first. The scale is the Generator's own — consumers order by it but
-	// do not interpret it — and it is meaningful only within the run that
-	// produced it, which is why it is never stored.
+	// sorts first within the Generator's own ranking. Consumers take candidates
+	// in iterator order and do not interpret the value. It is meaningful only
+	// within the run that produced it, which is why it is never stored.
 	RankingScore float64
 }

submitqueue/extension/scorer/README.md

@@ -1,64 +1,17 @@
-# Scorer
+# scorer
 
-Vendor-agnostic interface for computing success probability scores for code changes.
+A `Scorer` returns the probability that a batch's build succeeds — a number between 0.0 and 1.0. It is handed the batch identity and resolves the batch's changes itself through an injected `changeset.Resolver`, so callers pass an `entity.Batch` and nothing more.
 
-## Interface
+Callers may score every batch a queue is waiting on, so implementations should be cheap. A speculation run scores each batch at most once, but it does not carry results across runs; anything expensive belongs behind the implementation's own cache.
 
-### Scorer
-
-Computes a success probability for a given change.
-
-```go
-type Scorer interface {
-    Score(ctx context.Context, change entity.Change) (float64, error)
-}
-```
-
-- **change**: A `entity.Change` identifying the code change to score.
-- **Score**: Returns a probability between 0.0 and 1.0 indicating the likelihood of a successful land. Returns an error if scoring fails.
+Like the other extensions, a `Scorer` is selected **per queue** by the wiring layer through the `Config` (queue name) and `Factory` interface.
 
 ## Implementations
 
-### Heuristic
-
-Scores a change by extracting a numeric value via a `ValueFunc` and matching it against ordered buckets. Each bucket maps a `[Min, Max]` range to a probability.
-
-```go
-s := heuristic.New(
-    []heuristic.Bucket{
-        {Min: 0, Max: 5, Score: 0.95},
-        {Min: 6, Max: 20, Score: 0.75},
-        {Min: 21, Max: 100, Score: 0.5},
-    },
-    func(ctx context.Context, change entity.Change) (int, error) {
-        // resolve the change into a numeric metric
-        return filesChanged, nil
-    },
-)
-
-score, err := s.Score(ctx, change)
-```
-
-### Composite
-
-Combines multiple named scorers into a single score using a reduce function. The reduce function receives a `map[string]float64` mapping scorer names to their scores, enabling domain-aware aggregation.
-
-Built-in reduce functions: `Min`, `Max`, `Avg`.
-
-```go
-s := composite.New(
-    map[string]scorer.Scorer{
-        "files": fileScorer,
-        "deps":  depScorer,
-    },
-    composite.Min,
-)
+**`heuristic`** scores a batch by extracting one number from its changes and matching that against ordered buckets, each mapping a `[Min, Max]` range to a probability. The extraction is a caller-supplied `ValueFunc` over the resolved `entity.BatchChanges`, so the same bucketing works for files touched, lines changed, or any other metric.
 
-score, err := s.Score(ctx, change)
-```
+**`composite`** runs several named scorers and reduces their scores to one. The reduce function receives the scores keyed by scorer name, so it can weigh sources differently rather than treating them as interchangeable; `Min`, `Max`, and `Avg` are provided.
 
-## Implementing a Backend
+## Adding a backend
 
-1. Create `extension/scorer/{backend}/` directory
-2. Implement the `Scorer` interface
-3. Accept `entity.Change` and resolve it into whatever data the implementation needs
+Create a package under `scorer/<backend>/` whose `New(...)` returns a `scorer.Scorer`, injecting whatever it needs at construction — a `changeset.Resolver` to reach the batch's changes, a metrics scope, any client. Do not add a `Config` or `Factory` implementation here; per-queue routing and the factory adapter live in the wiring layer.

submitqueue/extension/scorer/scorer.go

@@ -22,11 +22,17 @@ import (
 	"github.com/uber/submitqueue/submitqueue/entity"
 )
 
-// Scorer computes a success probability score for a batch based on its changes.
+// Scorer computes the probability that a batch's build succeeds, based on its
+// changes.
 type Scorer interface {
-	// Score returns a probability between 0.0 and 1.0 indicating the likelihood
-	// of a successful land for the given batch. It is handed the batch identity
-	// and resolves the batch's changes itself through an injected changeset.Resolver.
+	// Score returns a probability between 0.0 and 1.0 that the given batch's
+	// build succeeds. It is handed the batch identity and resolves the batch's
+	// changes itself through an injected changeset.Resolver.
+	//
+	// Callers may score every batch a queue is waiting on, so implementations
+	// should be cheap: a speculation run scores each batch at most once, but it
+	// does not carry results over to the next run, so anything expensive to
+	// compute belongs behind the implementation's own cache.
 	Score(ctx context.Context, batch entity.Batch) (float64, error)
 }
 

submitqueue/extension/speculation/generator/BUILD.bazel

@@ -0,0 +1,9 @@
+load("@rules_go//go:def.bzl", "go_library")
+
+go_library(
+    name = "go_default_library",
+    srcs = ["generator.go"],
+    importpath = "github.com/uber/submitqueue/submitqueue/extension/speculation/generator",
+    visibility = ["//visibility:public"],
+    deps = ["//submitqueue/entity:go_default_library"],
+)

submitqueue/extension/speculation/generator/README.md

@@ -0,0 +1,9 @@
+# generator
+
+The `generator` package is a piece the `standard` `Speculator` is built from: a `Generator` produces the queue's candidate paths as one ordered stream across all heads. It is **not** controller-facing — the speculate controller only knows the `Speculator` contract, and a different `Speculator` need not split its work this way. So there is no `Config` or `Factory` here; a `Generator` is chosen when the `standard` `Speculator` is constructed.
+
+`Open` starts the stream over the queue's live batches and returns a `PathIterator`. Beyond any ranking work required up front, the generator computes only the candidates the caller pulls. A cancelled or expired context ends the stream with its error.
+
+Candidates never repeat and never contradict a known fact. Beyond that, the order is the `Generator`'s own: it yields candidates in whatever ranking it implements, and each carries the score it ranked by — higher first, on a scale the generator defines. Consumers take the iterator in the order given and do not interpret the score. Scores mean something only within the run and are never stored.
+
+The generator offers every path in the space, including paths whose builds already ran. Suppressing finished paths is the `Allocator`'s job, since that is the piece reconciling candidates against the stored path sets.

submitqueue/extension/speculation/generator/bestfirst/BUILD.bazel

@@ -0,0 +1,30 @@
+load("@rules_go//go:def.bzl", "go_library", "go_test")
+
+go_library(
+    name = "go_default_library",
+    srcs = [
+        "bestfirst.go",
+        "head.go",
+        "iterator.go",
+    ],
+    importpath = "github.com/uber/submitqueue/submitqueue/extension/speculation/generator/bestfirst",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//submitqueue/entity:go_default_library",
+        "//submitqueue/extension/scorer:go_default_library",
+        "//submitqueue/extension/speculation/generator:go_default_library",
+    ],
+)
+
+go_test(
+    name = "go_default_test",
+    srcs = ["bestfirst_test.go"],
+    embed = [":go_default_library"],
+    deps = [
+        "//submitqueue/entity:go_default_library",
+        "//submitqueue/extension/scorer:go_default_library",
+        "//submitqueue/extension/speculation/generator:go_default_library",
+        "@com_github_stretchr_testify//assert:go_default_library",
+        "@com_github_stretchr_testify//require:go_default_library",
+    ],
+)

submitqueue/extension/speculation/generator/bestfirst/README.md

@@ -0,0 +1,15 @@
+# bestfirst
+
+`bestfirst` implements `generator.Generator` by ranking candidate paths by the probability that all their dependency assumptions hold. It returns one path per pull across all speculating heads without enumerating every combination up front.
+
+The [best-first speculation path generation RFC](../../../../../doc/rfc/submitqueue/speculation-generator-best-first.md) defines the terminology, algorithm, correctness argument, worked example, and alternatives considered. This README records only the package's operational behavior.
+
+## Behavior
+
+- `Open` scores each unique unresolved dependency once, fixes assumptions for resolved dependencies, calculates each head's best score, and seeds one shared heap with every eligible head's best-path candidate.
+- `Next` removes the highest-ranked candidate, adds at most two child candidates, constructs that candidate's complete path, and returns it. Pulling long enough returns every path exactly once in non-increasing score order.
+- Ranking scores are sums of log probabilities, avoiding underflow while preserving probability order. They are meaningful only within the run that produced them.
+- Exact ties prefer fewer flips, then compare taken flip indexes, then head ID.
+- A missing dependency uses a success probability of 0.95 because it cannot be scored from the input snapshot.
+
+The behavior is covered by `bestfirst_test.go`.