feat(speculation): speculator extension contract

Makefile

@@ -366,7 +366,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/validator/... ./platform/consumer/... ./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/... ./submitqueue/extension/validator/... ./platform/consumer/... ./stovepipe/extension/storage/... ./stovepipe/extension/sourcecontrol/...
 	@echo "Mocks generated successfully!"
 
 proto: ## Generate protobuf files from .proto definitions

submitqueue/extension/speculation/speculator/BUILD.bazel

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

submitqueue/extension/speculation/speculator/README.md

@@ -0,0 +1,13 @@
+# speculator
+
+The `speculator` package defines the one speculation extension the speculate controller calls. A `Speculator` decides **which speculation paths to build and which running ones to cancel**, within the queue's build budget — and nothing else. It can never express a verdict: whether a batch merges or fails is fixed by the facts and computed by the controller, so swapping in a different `Speculator` changes which paths run, never a batch's outcome.
+
+`Speculate` is handed the queue's in-flight batches plus any finalized batches still referenced as dependencies (each with its dependency list and state) and every path set for them — live and recently finished, so a `Speculator` will not re-propose a path that already passed or failed. It returns a list of build and cancel actions; a path it wants left as-is has no entry in the result. The controller validates the output (dropping builds it shouldn't propose and rejecting cancels of passed paths), so an implementation may read extra injected data without affecting correctness.
+
+`Cancel` is a `Speculator`'s only cancel power — preempting an in-flight path to free budget for a better candidate. Correctness cancels (refuting a path whose bet a resolved dependency broke, and batch cancellation) belong to the controller and are not routed through the extension.
+
+Like the other extensions, a `Speculator` is selected **per queue** by the wiring layer through the `Config` (queue name) and `Factory` interface. Budget, depth bound, clock, and any extra data are injected at construction by the integrator, not carried on the contract.
+
+## Adding a backend
+
+Create a package under `speculator/<backend>/` whose `New(...)` returns a `speculator.Speculator`, injecting whatever it needs at construction. Resolve any content it requires internally; do not add a `Config` or `Factory` implementation here — per-queue routing and the factory adapter live in the wiring layer.

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

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

submitqueue/extension/speculation/speculator/speculator.go

@@ -0,0 +1,54 @@
+// 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 speculator
+
+//go:generate mockgen -source=speculator.go -destination=mock/speculator_mock.go -package=mock
+
+import (
+	"context"
+
+	"github.com/uber/submitqueue/submitqueue/entity"
+)
+
+// Speculator decides which speculation paths to build and which running ones to
+// cancel, within the queue's build budget. It is the only speculation extension the
+// speculate controller calls. It can never express a verdict: whether a batch
+// merges or fails is fixed by the facts and computed by the controller, so a
+// swapped-in Speculator changes which paths run, never a batch's outcome.
+type Speculator interface {
+	// Speculate is handed the queue's in-flight batches plus any finalized
+	// batches still referenced as dependencies (each with its dependency list and
+	// state) and every path set for them — live and recently finished, so it will
+	// not re-propose a path that already passed or failed. It returns the build
+	// and cancel actions it proposes; a path it wants left as-is has no entry in
+	// the result.
+	Speculate(ctx context.Context, batches []entity.Batch, pathSets []entity.SpeculationPathSet) ([]entity.Speculation, error)
+}
+
+// Config carries the per-queue identity handed to a Factory. The system knows
+// only the queue name; everything an implementation needs is injected at
+// construction by the integrator.
+type Config struct {
+	// QueueName identifies the queue this Speculator serves.
+	QueueName string
+}
+
+// Factory builds the Speculator for a queue. Implementations are provided by
+// integrators (and tests) and inject whatever they need — budget, depth bound,
+// clock, and any extra data — at construction.
+type Factory interface {
+	// For returns the Speculator for the given queue.
+	For(cfg Config) (Speculator, error)
+}