feat(speculation): add selector + selection-limit extensions

Add the selector seam and its limit counterpart from the speculation RFC, as vendor-agnostic extension interfaces under submitqueue/extension/speculation/.

selector: given a speculation tree with each path's controller-stamped status and freshly recomputed score, returns a per-path action (Build/Cancel) for the paths it chooses to act on. It is the policy seam — it reads status and score and emits actions only, never writes status, and does not decide merging. (This is the selector previously bundled with the enumerator, now split into its own change.)

selectionlimit: the "how much" policy bounding how many paths a batch may build in parallel. It is the selector's companion — the selector decides which paths, the limit decides how many. Injected into the selector at construction and called by it, keeping the selector interface limit-free; the value is signal-driven, not a fixed constant.

Each follows the repo extension contract (conflict.Analyzer reference shape): Factory.For(Config) (T, error) with Config carrying only QueueName. Includes READMEs, gomock packages, and Makefile mock-gen wiring. Interfaces only; concrete impls and controller wiring are deferred.

Author: behinddwalls

Makefile

@@ -364,7 +364,7 @@ local-stovepipe-stop: ## Stop the Stovepipe service
 
 mocks: ## Generate mock files using mockgen
 	@echo "Generating mocks..."
-	@$(BAZEL) run @rules_go//go -- generate ./submitqueue/extension/storage/... ./submitqueue/extension/buildrunner/... ./submitqueue/extension/changeprovider/... ./platform/extension/counter/... ./platform/extension/messagequeue/... ./submitqueue/extension/queueconfig/... ./submitqueue/extension/mergechecker/... ./submitqueue/extension/pusher/... ./submitqueue/extension/scorer/... ./submitqueue/extension/conflict/... ./submitqueue/extension/speculation/enumerator/... ./submitqueue/extension/speculation/dependencylimit/... ./submitqueue/extension/speculation/scorer/... ./platform/consumer/... ./submitqueue/core/changeset/... ./stovepipe/extension/storage/... ./stovepipe/extension/sourcecontrol/...
+	@$(BAZEL) run @rules_go//go -- generate ./submitqueue/extension/storage/... ./submitqueue/extension/buildrunner/... ./submitqueue/extension/changeprovider/... ./platform/extension/counter/... ./platform/extension/messagequeue/... ./submitqueue/extension/queueconfig/... ./submitqueue/extension/mergechecker/... ./submitqueue/extension/pusher/... ./submitqueue/extension/scorer/... ./submitqueue/extension/conflict/... ./submitqueue/extension/speculation/enumerator/... ./submitqueue/extension/speculation/dependencylimit/... ./submitqueue/extension/speculation/scorer/... ./submitqueue/extension/speculation/selector/... ./submitqueue/extension/speculation/selectionlimit/... ./platform/consumer/... ./submitqueue/core/changeset/... ./stovepipe/extension/storage/... ./stovepipe/extension/sourcecontrol/...
 	@echo "Mocks generated successfully!"
 
 proto: ## Generate protobuf files from .proto definitions

submitqueue/extension/speculation/selectionlimit/BUILD.bazel

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

submitqueue/extension/speculation/selectionlimit/README.md

@@ -0,0 +1,17 @@
+# Speculation Selection Limit
+
+Vendor-agnostic "how much" policy that bounds how many paths a batch may build in parallel.
+
+See the [Speculation RFC](../../../../doc/rfc/submitqueue/speculation.md) for the end-to-end design and how limits fit into the two-layer speculation model.
+
+## Selection Limit
+
+The selection limit is the [selector](../selector)'s companion. The selector decides **which** of a batch's paths are worth building — its ranking over the tree; the selection limit decides **how many** of them may run at once. Keeping "which" and "how much" separate keeps selector logic free of resource accounting and lets the bound scale with build resources without touching that logic.
+
+The value is **signal-driven**, not a fixed constant. Its primary input is the build system's available capacity, but a policy may also weigh historical pass rates, cost budgets, time of day, or an experiment toggle.
+
+Unlike the dependency limit — which the controller holds and applies as an eligibility gate — the selection limit is **injected into the seam that uses it**: the selector is constructed with it and calls it itself, never receiving it as a method parameter. This follows the repo's extension-contract pattern (dependencies injected at the `Factory`), keeps the selector interface limit-free and stable, and lets the limit be swapped independently of selector logic.
+
+## Factory
+
+A per-queue factory returns the limit policy for a queue, following the repo's extension contract. It is handed only the queue identity; the signals a policy weighs — a capacity feed, historical metrics, config — are injected at construction by the integrator in the wiring layer, which is also where the limit is handed to the selector. Computing the limit itself takes no further inputs.

submitqueue/extension/speculation/selectionlimit/fake/BUILD.bazel

@@ -0,0 +1,19 @@
+load("@rules_go//go:def.bzl", "go_library", "go_test")
+
+go_library(
+    name = "go_default_library",
+    srcs = ["fake.go"],
+    importpath = "github.com/uber/submitqueue/submitqueue/extension/speculation/selectionlimit/fake",
+    visibility = ["//visibility:public"],
+    deps = ["//submitqueue/extension/speculation/selectionlimit:go_default_library"],
+)
+
+go_test(
+    name = "go_default_test",
+    srcs = ["fake_test.go"],
+    embed = [":go_default_library"],
+    deps = [
+        "@com_github_stretchr_testify//assert:go_default_library",
+        "@com_github_stretchr_testify//require:go_default_library",
+    ],
+)

submitqueue/extension/speculation/selectionlimit/fake/fake.go

@@ -0,0 +1,52 @@
+// Copyright (c) 2025 Uber Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package fake provides a programmable selectionlimit.SelectionLimit for tests
+// and examples. New sets the value returned by Limit; FailWith injects an error
+// on every call. It is intended for examples and tests only, never production.
+package fake
+
+import (
+	"context"
+
+	"github.com/uber/submitqueue/submitqueue/extension/speculation/selectionlimit"
+)
+
+// SelectionLimit is a programmable selectionlimit.SelectionLimit.
+type SelectionLimit struct {
+	limit int
+	err   error
+}
+
+// New returns a fake SelectionLimit whose Limit returns the given value.
+func New(limit int) *SelectionLimit {
+	return &SelectionLimit{limit: limit}
+}
+
+// FailWith makes every Limit call return err.
+func (l *SelectionLimit) FailWith(err error) *SelectionLimit {
+	l.err = err
+	return l
+}
+
+// Limit returns the configured value, or the injected error if FailWith was set.
+func (l *SelectionLimit) Limit(_ context.Context) (int, error) {
+	if l.err != nil {
+		return 0, l.err
+	}
+	return l.limit, nil
+}
+
+// ensure the fake satisfies the interface.
+var _ selectionlimit.SelectionLimit = (*SelectionLimit)(nil)

submitqueue/extension/speculation/selectionlimit/fake/fake_test.go

@@ -0,0 +1,36 @@
+// Copyright (c) 2025 Uber Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package fake
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLimit_ReturnsConfiguredValue(t *testing.T) {
+	got, err := New(2).Limit(context.Background())
+	require.NoError(t, err)
+	assert.Equal(t, 2, got)
+}
+
+func TestLimit_FailWith(t *testing.T) {
+	sentinel := errors.New("boom")
+	_, err := New(2).FailWith(sentinel).Limit(context.Background())
+	require.ErrorIs(t, err, sentinel)
+}

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

@@ -0,0 +1,12 @@
+load("@rules_go//go:def.bzl", "go_library")
+
+go_library(
+    name = "go_default_library",
+    srcs = ["selectionlimit_mock.go"],
+    importpath = "github.com/uber/submitqueue/submitqueue/extension/speculation/selectionlimit/mock",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//submitqueue/extension/speculation/selectionlimit:go_default_library",
+        "@org_uber_go_mock//gomock:go_default_library",
+    ],
+)

submitqueue/extension/speculation/selectionlimit/mock/selectionlimit_mock.go

@@ -0,0 +1,57 @@
+// Copyright (c) 2025 Uber Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package selectionlimit
+
+//go:generate mockgen -source=selectionlimit.go -destination=mock/selectionlimit_mock.go -package=mock
+
+import "context"
+
+// SelectionLimit is the "how much" policy that bounds how many paths a batch may
+// build in parallel.
+//
+// It is the selector's companion: the selector decides *which* of a batch's
+// paths are worth building (its ranking); the selection limit decides *how many*
+// of them may run at once. Separating the two keeps selector logic free of
+// resource accounting and lets the bound scale with build resources without
+// touching that logic.
+//
+// The value is dynamic: it may change between calls, so the selector reads it
+// each pass rather than caching it.
+//
+// Unlike the dependency limit, this limit is injected into the seam that uses it
+// — the selector is constructed with it and calls it itself — never passed as a
+// method parameter, keeping the selector interface limit-free and stable.
+type SelectionLimit interface {
+	// Limit returns the current maximum number of paths a batch may build in
+	// parallel. The selector caps its Build actions at this. It takes no
+	// parameters; anything an implementation needs is injected at construction.
+	Limit(ctx context.Context) (int, error)
+}
+
+// Config carries the per-queue identity handed to a Factory. The system knows
+// only the queue name; everything a policy needs to compute the limit (a
+// capacity feed, historical metrics, config) is injected at construction by the
+// integrator.
+type Config struct {
+	// QueueName identifies the queue this SelectionLimit serves.
+	QueueName string
+}
+
+// Factory builds the SelectionLimit for a queue. Implementations are provided by
+// integrators (and tests) and inject whatever signals they need at construction.
+type Factory interface {
+	// For returns the SelectionLimit for the given queue.
+	For(cfg Config) (SelectionLimit, error)
+}

submitqueue/extension/speculation/selectionlimit/selectionlimit.go

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