feat(speculation): fold predictor into Scorer

Score takes the path-set snapshot. Evidence is a scorer wrapping a base; heuristic and composite ignore paths. Delete the sibling Predictor factory.

Author: behinddwalls

submitqueue/extension/speculation/generator/bestfirst/bestfirst.go

@@ -121,7 +121,7 @@ func (g *bestFirst) score(ctx context.Context, ids []string, batchByID map[strin
 			probabilityByID[id] = defaultProbability
 			continue
 		}
-		probability, err := g.scorer.Score(ctx, batch)
+		probability, err := g.scorer.Score(ctx, batch, entity.SpeculationPathSet{})
 		if err != nil {
 			// A scorer that failed because the caller went away has not found
 			// an unpriceable dependency — it has found a dead ctx, which ends

submitqueue/extension/speculation/generator/bestfirst/bestfirst_test.go

@@ -38,7 +38,7 @@ type stubScorer struct {
 	scores map[string]float64
 }
 
-func (s stubScorer) Score(_ context.Context, b entity.Batch) (float64, error) {
+func (s stubScorer) Score(_ context.Context, b entity.Batch, _ entity.SpeculationPathSet) (float64, error) {
 	if v, ok := s.scores[b.ID]; ok {
 		return v, nil
 	}
@@ -136,7 +136,7 @@ func newCountingScorer(scores map[string]float64) *countingScorer {
 	return &countingScorer{scores: scores, calls: map[string]int{}}
 }
 
-func (c *countingScorer) Score(_ context.Context, b entity.Batch) (float64, error) {
+func (c *countingScorer) Score(_ context.Context, b entity.Batch, _ entity.SpeculationPathSet) (float64, error) {
 	c.calls[b.ID]++
 	c.total++
 	if v, ok := c.scores[b.ID]; ok {
@@ -148,14 +148,14 @@ func (c *countingScorer) Score(_ context.Context, b entity.Batch) (float64, erro
 // errScorer always fails, to exercise error propagation from scoring.
 type errScorer struct{}
 
-func (errScorer) Score(context.Context, entity.Batch) (float64, error) {
+func (errScorer) Score(context.Context, entity.Batch, entity.SpeculationPathSet) (float64, error) {
 	return 0, assert.AnError
 }
 
 // constScorer scores every batch identically, regardless of ID.
 type constScorer struct{ v float64 }
 
-func (c constScorer) Score(context.Context, entity.Batch) (float64, error) { return c.v, nil }
+func (c constScorer) Score(context.Context, entity.Batch, entity.SpeculationPathSet) (float64, error) { return c.v, nil }
 
 // wideHead builds one Speculating head over n unresolved dependencies, each at a
 // distinct score so no two combinations tie.
@@ -839,7 +839,7 @@ func TestBestFirst_HonorsCancelledContext(t *testing.T) {
 // own call was cancelled would.
 type cancellingScorer struct{ cancel context.CancelFunc }
 
-func (s cancellingScorer) Score(context.Context, entity.Batch) (float64, error) {
+func (s cancellingScorer) Score(context.Context, entity.Batch, entity.SpeculationPathSet) (float64, error) {
 	s.cancel()
 	return 0, context.Canceled
 }

submitqueue/extension/speculation/predictor/BUILD.bazel

@@ -1,19 +1,23 @@
 # scorer
 
-A `Scorer` returns the probability that a batch ultimately succeeds — reaches its terminal `Succeeded` state with its changes landed, not merely a passing build — as 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.
+A `Scorer` returns how likely a batch is to reach `Succeeded` with its changes landed, as a number between 0.0 and 1.0. `Score(ctx, batch, paths)` is handed the batch identity and that batch's own `SpeculationPathSet` — zero-valued when nothing has speculated on it yet. Callers pass a snapshot they already hold; a scorer must not load the path-set store.
 
 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.
 
-The default speculation pipeline does not rank on the scorer directly. The queue's `Predictor` is built over its `Scorer` and revises the scorer's price with path-set evidence before `bestfirst` ranks paths. The scorer still prices only the change; it does not see path sets.
+The default `bestfirst` generator ranks on this number. The default scorer is **evidence** wrapping a **base**: heuristic or composite prices the change and ignores `paths`; evidence revises that price from the path set and batch state.
 
 Like the other extensions, a `Scorer` is selected **per queue** by the wiring layer through the `Config` (queue name) and `Factory` interface.
 
+See [doc/rfc/submitqueue/outcome-predictor.md](../../../../doc/rfc/submitqueue/outcome-predictor.md) for the GLM, factor contract, evidence rules, and configuration shape.
+
 ## Implementations
 
-**`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.
+**`evidence`** revises a nested base scorer with YAML-configured factors for `pathPassed`, `pathFailed`, `merging`, and `cancelling`. A factor of `1` leaves the base price alone; every factor defaults to `1` until someone sets one. Only paths that assume every dependency succeeds count as path evidence.
+
+**`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. It ignores `paths`.
 
-**`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.
+**`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. It ignores `paths` except to forward them to children.
 
 ## Adding a backend
 
-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.
+Create a package under `scorer/<backend>/` whose `New(...)` returns a `scorer.Scorer`, injecting whatever it needs at construction — a nested `Scorer` for evidence, 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/speculation/predictor/README.md

@@ -94,13 +94,13 @@ func New(cfg scorer.Config, scorers map[string]scorer.Scorer, reduce ReduceFunc,
 
 // Score evaluates all child scorers on the batch and combines their results using the
 // reduce function. If any child scorer returns an error, that error is returned immediately.
-func (c *compositeScorer) Score(ctx context.Context, batch entity.Batch) (ret float64, retErr error) {
+func (c *compositeScorer) Score(ctx context.Context, batch entity.Batch, paths entity.SpeculationPathSet) (ret float64, retErr error) {
 	op := metrics.Begin(c.scope, "score", metrics.FastLatencyBuckets)
 	defer func() { op.Complete(retErr) }()
 
 	scores := make(map[string]float64, len(c.scorers))
 	for name, s := range c.scorers {
-		score, err := s.Score(ctx, batch)
+		score, err := s.Score(ctx, batch, paths)
 		if err != nil {
 			return 0, err
 		}

submitqueue/extension/speculation/predictor/mock/BUILD.bazel

@@ -34,14 +34,14 @@ type fixedScorer struct {
 	score float64
 }
 
-func (f *fixedScorer) Score(_ context.Context, _ entity.Batch) (float64, error) {
+func (f *fixedScorer) Score(_ context.Context, _ entity.Batch, _ entity.SpeculationPathSet) (float64, error) {
 	return f.score, nil
 }
 
 // errorScorer always returns an error.
 type errorScorer struct{}
 
-func (e *errorScorer) Score(_ context.Context, _ entity.Batch) (float64, error) {
+func (e *errorScorer) Score(_ context.Context, _ entity.Batch, _ entity.SpeculationPathSet) (float64, error) {
 	return 0, fmt.Errorf("scorer failed")
 }
 
@@ -102,7 +102,7 @@ func TestScorer_Score(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			s := New(testCfg, tt.scorers, tt.reduce, tally.NoopScope)
-			got, err := s.Score(context.Background(), entity.Batch{})
+			got, err := s.Score(context.Background(), entity.Batch{}, entity.SpeculationPathSet{})
 			require.NoError(t, err)
 			assert.InDelta(t, tt.want, got, 1e-9)
 		})
@@ -114,7 +114,7 @@ func TestScorer_Score_ChildError(t *testing.T) {
 		"error": &errorScorer{},
 		"files": &fixedScorer{0.9},
 	}, Min, tally.NoopScope)
-	_, err := s.Score(context.Background(), entity.Batch{})
+	_, err := s.Score(context.Background(), entity.Batch{}, entity.SpeculationPathSet{})
 	require.Error(t, err)
 }
 
@@ -143,7 +143,7 @@ func TestReduceFunc_ReceivesNames(t *testing.T) {
 		"files": &fixedScorer{0.9},
 		"deps":  &fixedScorer{0.95},
 	}, custom, tally.NoopScope)
-	got, err := s.Score(context.Background(), entity.Batch{})
+	got, err := s.Score(context.Background(), entity.Batch{}, entity.SpeculationPathSet{})
 	require.NoError(t, err)
 	assert.Equal(t, 0.9, got)
 	assert.ElementsMatch(t, []string{"files", "deps"}, receivedNames)