refactor(stovepipe): scope entities and extensions to gateway only

Replace ChangeInfo with ChangeEvent as the ingestion payload type and
introduce ChangeURI as the lightweight pipeline reference. Update Commit entity and create CommitStatusentity. Update ChangeHandler and the filter to accept ChangeEvent. Remove the
storage extension and Batch entity, which belong to the orchestrator.

Author: gsturges

stovepipe/core/filter/filter.go

@@ -22,10 +22,10 @@ import (
 )
 
 // Config controls which VCS URIs are watched.
-// WatchedURIPrefixes is a list of URI prefixes to match against ChangeInfo.URI.
+// WatchedURIPrefixes is a list of URI prefixes to match against ChangeEvent.URI.
 // Example: "git://github.com/uber/go-code/refs/heads/main"
 // watches all commits on the main branch of uber/go-code.
-func ShouldProcess(event entity.ChangeInfo, watchedPrefixes []string) bool {
+func ShouldProcess(event entity.ChangeEvent, watchedPrefixes []string) bool {
 	for _, prefix := range watchedPrefixes {
 		if strings.HasPrefix(event.URI, prefix) {
 			return true

stovepipe/entity/BUILD.bazel

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

stovepipe/entity/batch.go

@@ -0,0 +1,59 @@
+// 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
+
+import (
+	"encoding/json"
+	"fmt"
+
+	entitygit "github.com/uber/submitqueue/stovepipe/entity/git"
+)
+
+// ChangeEvent represents a single new trunk change entering the pipeline, published to the
+// start topic. A trunk change is one commit, so the event carries one git-backed URI. It is
+// source-agnostic: both the webhook and the reconciliation poller emit it. Additional fields
+// (e.g. source, committer time) can be added later as ingestion needs them.
+type ChangeEvent struct {
+	// URI identifies the commit that entered the pipeline (git://owner/repo/branch/revision).
+	URI string `json:"uri"`
+}
+
+// ToBytes serializes the ChangeEvent to JSON bytes for queue message payload.
+func (e ChangeEvent) ToBytes() ([]byte, error) {
+	return json.Marshal(e)
+}
+
+// Validate checks that the change event carries a valid git-backed commit URI.
+func (e ChangeEvent) Validate() error {
+	if e.URI == "" {
+		return fmt.Errorf("change event requires a commit URI")
+	}
+	if _, err := entitygit.ParseChangeID(e.URI); err != nil {
+		return fmt.Errorf("change event URI: %w", err)
+	}
+	return nil
+}
+
+// ChangeEventFromBytes deserializes a ChangeEvent from JSON bytes.
+func ChangeEventFromBytes(data []byte) (ChangeEvent, error) {
+	var event ChangeEvent
+	if err := json.Unmarshal(data, &event); err != nil {
+		return ChangeEvent{}, err
+	}
+	if err := event.Validate(); err != nil {
+		return ChangeEvent{}, err
+	}
+	return event, nil
+}

stovepipe/entity/change_event.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 entity
+
+import "encoding/json"
+
+// ChangeURI is the lightweight reference passed between pipeline stages. It
+// carries only the change identity; stages re-resolve any state they need.
+type ChangeURI struct {
+	// URI is the change identity (git://owner/repo/branch/revision).
+	URI string `json:"uri"`
+}
+
+// ToBytes serializes the ChangeURI to JSON bytes for a queue message payload.
+func (c ChangeURI) ToBytes() ([]byte, error) {
+	return json.Marshal(c)
+}
+
+// ChangeURIFromBytes deserializes a ChangeURI from JSON bytes.
+func ChangeURIFromBytes(data []byte) (ChangeURI, error) {
+	var ref ChangeURI
+	err := json.Unmarshal(data, &ref)
+	return ref, err
+}

stovepipe/entity/change_uri.go

@@ -14,44 +14,50 @@
 
 package entity
 
-// CommitStatus is the validation state of a trunk commit as determined by Stovepipe.
-type CommitStatus string
+// CommitStatusKind is the validation state of a trunk commit as determined by Stovepipe.
+type CommitStatusKind string
 
 const (
-	// CommitStatusUnknown is the default state when a commit is first ingested.
+	// CommitStatusKindUnknown 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"
+	CommitStatusKindUnknown CommitStatusKind = ""
+	// CommitStatusKindIngested means the commit has been received and recorded by the gateway.
+	CommitStatusKindIngested CommitStatusKind = "ingested"
+	// CommitStatusKindQueued means the commit is waiting to enter the validation pipeline.
+	CommitStatusKindQueued CommitStatusKind = "queued"
+	// CommitStatusKindProcessing means the commit is actively being validated.
+	CommitStatusKindProcessing CommitStatusKind = "processing"
+	// CommitStatusKindSucceeded means the relevant targets build and test successfully at this commit.
+	CommitStatusKindSucceeded CommitStatusKind = "succeeded"
+	// CommitStatusKindFailed means a target is broken at this commit; it is the offending change.
+	CommitStatusKindFailed CommitStatusKind = "failed"
 )
 
 // IsCommitStatusTerminal returns true if the status is a final, irreversible state.
-func IsCommitStatusTerminal(s CommitStatus) bool {
-	return s == CommitStatusSucceeded || s == CommitStatusFailed
+func IsCommitStatusTerminal(s CommitStatusKind) bool {
+	return s == CommitStatusKindSucceeded || s == CommitStatusKindFailed
 }
 
-// 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.
+// Commit is a trunk commit tracked by Stovepipe's gateway.
+// URI is the primary key — it is the canonical change identity from the originating ChangeEvent.
 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
+	// URI is the canonical change identity from the originating ChangeEvent.
+	URI string
+	// SequenceNumber is the number of commits reachable from this commit on the trunk branch,
+	// derived from `git rev-list --count`. Higher values are newer.
+	// Must be populated at ingestion time — a zero value indicates the field was not set.
+	SequenceNumber int64
 	// 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
+}
+
+// CommitStatus is a point-in-time validation status entry for a Commit.
+// Multiple CommitStatus records form the status history of a single Commit.
+type CommitStatus struct {
+	// CommitURI is the URI of the Commit this status belongs to.
+	CommitURI string
+	// Status is the validation state recorded at this point in time.
+	Status CommitStatusKind
+	// CreatedAt is the time this status was recorded, in milliseconds since epoch.
+	CreatedAt int64
 }

stovepipe/entity/commit.go

@@ -25,6 +25,8 @@ import (
 
 // LoggingHandler is a stub ChangeHandler that logs received changes.
 // Replace with real persistence logic once DB schema is ready.
+// Implementations must resolve entity.Commit.SequenceNumber (via `git rev-list --count`)
+// before persisting — a zero value indicates the field was not populated.
 type LoggingHandler struct {
 	logger *zap.Logger
 }
@@ -35,12 +37,9 @@ func New(logger *zap.Logger) extension.ChangeHandler {
 	return LoggingHandler{logger: logger}
 }
 
-func (h LoggingHandler) IngestChange(ctx context.Context, info entity.ChangeInfo) error {
+func (h LoggingHandler) IngestChange(ctx context.Context, event entity.ChangeEvent) error {
 	h.logger.Info("ingested change",
-		zap.String("uri", info.URI),
-		zap.String("previous_uri", info.PreviousURI),
-		zap.String("author_name", info.AuthorName),
-		zap.String("author_email", info.AuthorEmail),
+		zap.String("uri", event.URI),
 	)
 	return nil
 }

stovepipe/entity/entity.go

@@ -30,5 +30,5 @@ type ChangeIngester interface {
 
 // ChangeHandler processes a single change received from the ingester.
 type ChangeHandler interface {
-	IngestChange(ctx context.Context, info entity.ChangeInfo) error
+	IngestChange(ctx context.Context, event entity.ChangeEvent) error
 }