feat(stovepipe): scaffold pipeline entities and storage extension

Add Commit and Batch as the core domain entities the validation pipeline
operates on, each with status types and optimistic-locking Version fields.
Add CommitStore and BatchStore extension interfaces scoped to their
respective service owners (gateway and orchestrator). Fix missing
BUILD.bazel files for the filter and changeingester packages. Flatten
ChangeInfo.Author into AuthorName/AuthorEmail fields directly.

Author: gsturges

stovepipe/core/filter/BUILD.bazel

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

stovepipe/entity/BUILD.bazel

@@ -2,7 +2,11 @@ load("@rules_go//go:def.bzl", "go_library")
 
 go_library(
     name = "entity",
-    srcs = ["entity.go"],
+    srcs = [
+        "batch.go",
+        "commit.go",
+        "entity.go",
+    ],
     importpath = "github.com/uber/submitqueue/stovepipe/entity",
     visibility = ["//visibility:public"],
 )

stovepipe/entity/batch.go

@@ -0,0 +1,63 @@
+// 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
+
+// BatchStatus is the state of a validation batch as it moves through the pipeline.
+type BatchStatus string
+
+const (
+	// BatchStatusUnknown is the unreachable default. It should never be seen in the system.
+	BatchStatusUnknown BatchStatus = ""
+	// BatchStatusPending means the batch has been created but speculate has not yet run.
+	BatchStatusPending BatchStatus = "pending"
+	// BatchStatusBuilding means the batch is moving through the speculate→build→buildsignal→bisect cycle.
+	BatchStatusBuilding BatchStatus = "building"
+	// BatchStatusSucceeded means all commits in the batch's range have been validated green.
+	BatchStatusSucceeded BatchStatus = "succeeded"
+	// BatchStatusFailed means an offending commit in the range has been isolated and marked failed.
+	BatchStatusFailed BatchStatus = "failed"
+)
+
+// IsBatchStatusTerminal returns true if the batch has reached a final state.
+func IsBatchStatusTerminal(s BatchStatus) bool {
+	return s == BatchStatusSucceeded || s == BatchStatusFailed
+}
+
+// Batch is a contiguous range of trunk commits submitted for validation together.
+// The range spans from FromSHA (oldest, inclusive) to ToSHA (newest, inclusive)
+// and represents all commits since the last known green on the branch.
+// Bisection creates sub-range batches from the same type — there is no separate
+// bisection entity; the state of the search lives in the ordinary batch results.
+type Batch struct {
+	// ID is the unique identifier for this batch.
+	ID string
+	// FromSHA is the oldest commit SHA in the validation range (inclusive).
+	FromSHA string
+	// ToSHA is the newest commit SHA in the validation range (inclusive).
+	ToSHA string
+	// Repository is the repository this batch validates.
+	Repository string
+	// Branch is the branch this batch validates.
+	Branch string
+	// Status is the current state of this batch.
+	Status BatchStatus
+	// Version is incremented on each update and used for optimistic locking.
+	// Version arithmetic lives in the controller; the store performs a pure conditional write.
+	Version int32
+	// CreatedAt is the time this batch was created, in milliseconds since epoch.
+	CreatedAt int64
+	// UpdatedAt is the time this batch was last updated, in milliseconds since epoch.
+	UpdatedAt int64
+}

stovepipe/entity/commit.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 entity
+
+// CommitStatus is the validation state of a trunk commit as determined by Stovepipe.
+type CommitStatus string
+
+const (
+	// CommitStatusUnknown is the default state when a commit is first ingested.
+	// The commit has landed on main but has not yet been validated.
+	CommitStatusUnknown CommitStatus = ""
+	// CommitStatusSucceeded means the relevant targets build and test successfully at this commit.
+	CommitStatusSucceeded CommitStatus = "succeeded"
+	// CommitStatusFailed means a target is broken at this commit; it is the offending change.
+	CommitStatusFailed CommitStatus = "failed"
+)
+
+// IsCommitStatusTerminal returns true if the status is a final, irreversible state.
+func IsCommitStatusTerminal(s CommitStatus) bool {
+	return s == CommitStatusSucceeded || s == CommitStatusFailed
+}
+
+// Commit is a trunk commit tracked by Stovepipe. The SHA scoped by Repository and
+// Branch is the natural identity and dedup key: a commit announced by both a webhook
+// and a poll backfill resolves to the same record and is processed once.
+type Commit struct {
+	// SHA is the full commit hash. Identity key; immutable after creation.
+	SHA string
+	// Repository is the repository URI (e.g. "github.com/uber/go-code").
+	Repository string
+	// Branch is the target branch (e.g. "main").
+	Branch string
+	// CommitterTimeMs is the committer timestamp in milliseconds since epoch.
+	// Used to order commits within a range and to establish the trunk sequence.
+	CommitterTimeMs int64
+	// Status is the current validation state of this commit.
+	Status CommitStatus
+	// Version is incremented on each update and used for optimistic locking.
+	// Version arithmetic lives in the controller; the store performs a pure conditional write.
+	Version int32
+	// CreatedAt is the time this commit was first recorded, in milliseconds since epoch.
+	CreatedAt int64
+	// UpdatedAt is the time this commit was last updated, in milliseconds since epoch.
+	UpdatedAt int64
+}

stovepipe/entity/entity.go

@@ -27,23 +27,15 @@ package entity
 type ChangeInfo struct {
 	// URI is the canonical VCS identifier for this change.
 	// Scheme is "git://"; path encodes host, repo, ref, and new revision.
-	// This mirrors the ChangeInfo.URI pattern used in SubmitQueue.
 	URI string `json:"uri"`
 
 	// PreviousURI is the URI of the prior revision on the same ref, if known.
 	// Empty string if unavailable.
 	// Example: "git://github.com/uber/go-code/refs/heads/main/aabbccdd..."
 	PreviousURI string `json:"previous_uri,omitempty"`
 
-	// Author is the identity of the person who authored the change.
-	Author Author `json:"author"`
-}
-
-// Author identifies the person who authored a change.
-// Mirrors SubmitQueue's Author to keep the two domains consistent.
-type Author struct {
-	// Name is the display name of the author.
-	Name string `json:"name"`
-	// Email is the email address of the author.
-	Email string `json:"email,omitempty"`
+	// AuthorName is the display name of the person who authored the change.
+	AuthorName string `json:"author_name,omitempty"`
+	// AuthorEmail is the email address of the author.
+	AuthorEmail string `json:"author_email,omitempty"`
 }

stovepipe/extension/BUILD.bazel

@@ -5,4 +5,5 @@ go_library(
     srcs = ["extension.go"],
     importpath = "github.com/uber/submitqueue/stovepipe/extension",
     visibility = ["//visibility:public"],
+    deps = ["//stovepipe/entity"],
 )

stovepipe/extension/changeingester/BUILD.bazel

@@ -0,0 +1,13 @@
+load("@rules_go//go:def.bzl", "go_library")
+
+go_library(
+    name = "changeingester",
+    srcs = ["logging.go"],
+    importpath = "github.com/uber/submitqueue/stovepipe/extension/changeingester",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//stovepipe/entity",
+        "//stovepipe/extension",
+        "@org_uber_go_zap//:zap",
+    ],
+)

stovepipe/extension/changeingester/logging.go

@@ -39,8 +39,8 @@ func (h LoggingHandler) IngestChange(ctx context.Context, info entity.ChangeInfo
 	h.logger.Info("ingested change",
 		zap.String("uri", info.URI),
 		zap.String("previous_uri", info.PreviousURI),
-		zap.String("author", info.Author.Name),
-		zap.String("author_email", info.Author.Email),
+		zap.String("author_name", info.AuthorName),
+		zap.String("author_email", info.AuthorEmail),
 	)
 	return nil
 }

stovepipe/extension/storage/BUILD.bazel

@@ -0,0 +1,13 @@
+load("@rules_go//go:def.bzl", "go_library")
+
+go_library(
+    name = "storage",
+    srcs = [
+        "batch_store.go",
+        "commit_store.go",
+        "storage.go",
+    ],
+    importpath = "github.com/uber/submitqueue/stovepipe/extension/storage",
+    visibility = ["//visibility:public"],
+    deps = ["//stovepipe/entity"],
+)

stovepipe/extension/storage/batch_store.go

@@ -0,0 +1,43 @@
+// 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 storage
+
+//go:generate mockgen -source=batch_store.go -destination=mock/batch_store_mock.go -package=mock
+
+import (
+	"context"
+
+	"github.com/uber/submitqueue/stovepipe/entity"
+)
+
+// BatchStore is the orchestrator-owned store for in-flight validation batches.
+// A batch represents a contiguous range of trunk commits under validation.
+// Bisection reuses the same type — sub-range probes are ordinary batches
+// driven through the same speculate→build→buildsignal→bisect loop.
+type BatchStore interface {
+	// Get retrieves a batch by ID. Returns ErrNotFound if no record exists.
+	Get(ctx context.Context, id string) (entity.Batch, error)
+
+	// Create records a new batch with status BatchStatusPending.
+	// Returns ErrAlreadyExists if a batch with the same ID already exists.
+	Create(ctx context.Context, batch entity.Batch) error
+
+	// UpdateStatus updates the batch's status and advances the version from
+	// oldVersion to newVersion. Returns ErrVersionMismatch if the current
+	// persisted version does not match oldVersion; the caller must re-read and retry.
+	// Version arithmetic is owned by the caller (controller); the store performs
+	// a pure conditional write.
+	UpdateStatus(ctx context.Context, id string, oldVersion, newVersion int32, status entity.BatchStatus) error
+}