feat(storage): path-build link store for per-path builds

## Summary

### Why?

Speculation needs one build per *path*, and something must record which build belongs to which path attempt. The runner chooses the build ID, so a caller holding a path cannot derive it; a keyed record is the key-value contract's mechanism for a reverse lookup.

### What?

`entity.PathBuild` is new: the `(pathID, attempt) -> buildID` link, with `storage.PathBuildStore`, a MySQL implementation, schema, and mocks.

The record is write-once: created only once the runner has named the build, never updated. Absent means no build is recorded for the attempt; present names its build permanently, and a retried path is a new attempt under a different key. Because creation is the only write, the first insert also decides concurrent dispatches for the same attempt — `ErrAlreadyExists` tells the loser the attempt's build is someone else's. There is deliberately no reservation state and no version column: the stage that watches builds (later in this stack) stops any build whose path no longer wants it, so no reader needs to distinguish "idle" from "mid-dispatch".

`entity.Build` gains `PathID` and `Attempt`, and `entity.SpeculationPath` gains `Base()` — the dependencies the path assumes will succeed — so every consumer derives the base one way.

## Test Plan

✅ `bazel test //submitqueue/entity/... //submitqueue/extension/storage/...`

✅ `bazel test //test/integration/submitqueue/extension/storage/mysql:go_default_test` — an attempt resolving to its build, `ErrNotFound` when undispatched, and a duplicate `Create` refused so the first link stands.

✅ `make fmt`, `make gazelle`, `make mocks`

Author: behinddwalls

submitqueue/entity/BUILD.bazel

@@ -14,6 +14,7 @@ go_library(
         "land.go",
         "list.go",
         "merge_result.go",
+        "path_build.go",
         "push_result.go",
         "queue_config.go",
         "request.go",

submitqueue/entity/build.go

@@ -55,12 +55,25 @@ func (s BuildStatus) IsTerminal() bool {
 
 // Build represents a build scheduled for a batch along a specific speculation path.
 // All fields except the Status are immutable after creation.
+//
+// It is keyed by the runner's build ID, which is the identifier every stage
+// downstream of the trigger already holds: a poll, a webhook, and a runner-side
+// log line all name a build, none of them names a speculation path. The path
+// coordinates ride along on the record so those stages never have to
+// understand speculation to do their job.
 type Build struct {
 	// ID is the identifier minted by the queue's build runner when the build
 	// is triggered; this is the primary storage key.
 	ID string
 	// BatchID is the batch for which this build is scheduled.
 	BatchID string
+	// PathID is the speculation path this build verifies, as carried by
+	// SpeculationPathEntry.ID.
+	PathID string
+	// Attempt is which build attempt for that path this is, starting at 1.
+	// A path may be built more than once, so ID names the run while
+	// (PathID, Attempt) names the slot it occupies.
+	Attempt int
 	// Status represents the state of the build lifecycle this build is in.
 	Status BuildStatus
 }

submitqueue/entity/path_build.go

@@ -0,0 +1,35 @@
+// 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 entity
+
+// PathBuild names the build started for one attempt of one speculation path.
+//
+// It is the reverse of Build's key. A Build is keyed by the identifier the
+// runner minted, which is what every stage watching a build already holds; a
+// caller starting from a path has no way to derive that identifier, so the link
+// is recorded under the coordinates it does hold.
+//
+// A record is write-once: it is created already naming its build and never
+// changes, so an attempt maps to one build for good — a retried path is a new
+// attempt under a different key. An absent record means no build is recorded
+// for the attempt; it does not promise that none is starting.
+type PathBuild struct {
+	// PathID is the speculation path, as carried by SpeculationPathEntry.ID.
+	PathID string
+	// Attempt is which build attempt for that path this is, starting at 1.
+	Attempt int
+	// BuildID is the build started for that attempt. Never empty.
+	BuildID string
+}

submitqueue/entity/speculation.go

@@ -79,6 +79,24 @@ func (p SpeculationPath) ID() string {
 	return hex.EncodeToString(sum[:])
 }
 
+// Base returns the path's base — the batches its head is stacked on top of:
+// the IDs of the dependencies the path assumes will succeed, in the path's
+// dependency order.
+//
+// It is a projection of the path rather than a decision about it — a
+// dependency the path assumes will fail is by definition built without, and
+// an ignored one is not built on either — so every caller that needs the base
+// derives it here rather than re-reading the assumptions itself.
+func (p SpeculationPath) Base() []string {
+	var deps []string
+	for _, dep := range p.Dependencies {
+		if dep.Assumption == DependencyAssumptionSucceeds {
+			deps = append(deps, dep.Batch)
+		}
+	}
+	return deps
+}
+
 // SpeculationPathStatus is the lifecycle status of one speculation path's
 // current build attempt.
 type SpeculationPathStatus string
@@ -122,9 +140,10 @@ func (s SpeculationPathStatus) IsTerminal() bool {
 }
 
 // SpeculationPathEntry is the stored record of one chosen speculation path,
-// keyed by the hash of its content. It holds no build reference (that lives on
-// the separate execution record, keyed by (ID, Attempt)) and no score (a score
-// is meaningful only within a single speculation run).
+// keyed by the hash of its content. It holds no build reference — a build is
+// linked to an attempt by PathBuild, so the path stays what the speculation run
+// decided rather than a mirror of what the build system is doing — and no score
+// (a score is meaningful only within a single speculation run).
 type SpeculationPathEntry struct {
 	// ID is the primary key: the hash of the path's content (head plus its
 	// assumptions). It always equals Path.ID() — it is materialized here, rather

submitqueue/extension/storage/BUILD.bazel

@@ -7,6 +7,7 @@ go_library(
         "batch_store.go",
         "build_store.go",
         "change_store.go",
+        "path_build_store.go",
         "request_batch_store.go",
         "request_log_store.go",
         "request_queue_summary_store.go",

submitqueue/extension/storage/mock/BUILD.bazel

@@ -7,6 +7,7 @@ go_library(
         "batch_store_mock.go",
         "build_store_mock.go",
         "change_store_mock.go",
+        "path_build_store_mock.go",
         "request_batch_store_mock.go",
         "request_log_store_mock.go",
         "request_queue_summary_store_mock.go",

submitqueue/extension/storage/mock/path_build_store_mock.go

@@ -7,6 +7,7 @@ go_library(
         "batch_store.go",
         "build_store.go",
         "change_store.go",
+        "path_build_store.go",
         "request_batch_store.go",
         "request_log_store.go",
         "request_queue_summary_store.go",