feat(pushqueue): add domain entities and extension interfaces

pushqueue/entity/BUILD.bazel

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

pushqueue/entity/land.go

@@ -0,0 +1,49 @@
+// 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
+
+// QueueTarget identifies a landing destination in a version control system.
+// Defined locally in pushqueue; consolidated into shared entity/ by Chunk 2.
+type QueueTarget struct {
+	// Name is an optional logical identifier for correlation and config lookup.
+	Name string
+	// Address is the VCS repository address (remote URL, depot path).
+	Address string
+	// Target is the landing ref (branch name, stream path).
+	Target string
+}
+
+// LandStrategy defines the possible landing methods for a code change.
+type LandStrategy string
+
+const (
+	// LandStrategyUnknown is the unknown strategy. It is set by default
+	// when the structure is initialized. It should never be seen in the system.
+	LandStrategyUnknown LandStrategy = ""
+	// LandStrategyRebase rebases commits onto the target branch before landing.
+	LandStrategyRebase LandStrategy = "rebase"
+	// LandStrategySquashRebase squashes commits into a single commit before rebasing.
+	LandStrategySquashRebase LandStrategy = "squash_rebase"
+	// LandStrategyMerge creates a merge commit preserving commit history.
+	LandStrategyMerge LandStrategy = "merge"
+)
+
+// LandItem represents a single code change to land with its strategy.
+type LandItem struct {
+	// URIs identifies the change (RFC 3986). Scheme identifies the provider.
+	URIs []string
+	// Strategy is the landing strategy for this change.
+	Strategy LandStrategy
+}

pushqueue/extension/landqueue/BUILD.bazel

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

pushqueue/extension/landqueue/landqueue.go

@@ -0,0 +1,50 @@
+// 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 landqueue
+
+//go:generate mockgen -source=landqueue.go -destination=mock/landqueue_mock.go -package=mock
+
+import (
+	"context"
+
+	"github.com/uber/submitqueue/pushqueue/entity"
+)
+
+// Preparer performs pre-push preparation for a set of land items.
+// Implementations are typically backed by a VCS extension. The Queue
+// receives a Preparer at construction time and may invoke it between
+// Enqueue and Wait to pipeline preparation with queue wait time.
+type Preparer interface {
+	Prepare(ctx context.Context, target entity.QueueTarget, items []entity.LandItem) error
+}
+
+// Queue serializes access to a landing target, ensuring only one request
+// pushes at a time per (address, target) pair.
+//
+// Contract:
+//   - Enqueue is idempotent: re-enqueueing the same request is a no-op.
+//   - Wait blocks until this request is head-of-queue AND preparation
+//     (via the Preparer provided at construction) has completed.
+//     Must respect ctx cancellation.
+//   - Dequeue removes this request from the queue. Must be called exactly
+//     once per successful Enqueue (use defer).
+//   - Implementations must detect stale queue heads and evict them after a timeout.
+//   - Implementations decide when to call Preparer.Prepare — during the
+//     wait (pipelined) or synchronously before Wait returns (simple).
+type Queue interface {
+	Enqueue(ctx context.Context, target entity.QueueTarget, items []entity.LandItem) error
+	Wait(ctx context.Context, target entity.QueueTarget) error
+	Dequeue(ctx context.Context, target entity.QueueTarget) error
+}

pushqueue/extension/landqueue/mock/BUILD.bazel

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

pushqueue/extension/vcs/BUILD.bazel

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

pushqueue/extension/vcs/mock/BUILD.bazel

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