From cf251a2b325fe8fa6c70d05ed7fe24e216304468 Mon Sep 17 00:00:00 2001
From: mnoah1 <mnoah1@uber.com>
Date: Tue, 7 Jul 2026 21:27:09 +0000
Subject: [PATCH] feat(stovepipe): add Queue coordination entity

Add the per-queue Queue control row that backs the process stage's
concurrency gate and backlog coalescing: last_green_uri (incremental
baseline), in_flight_count and max_concurrent (the concurrency gate),
latest_request_seq (the coalescing pointer), and version for
optimistic-locking CAS. Matches the entity model in the process RFC.

No timestamps, consistent with the existing Request entity. Pure data
struct with no message-payload serialization (Queue is a persisted
control record, not a queue message).
---
 stovepipe/entity/BUILD.bazel |  5 ++++-
 stovepipe/entity/queue.go    | 40 ++++++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 stovepipe/entity/queue.go

diff --git a/stovepipe/entity/BUILD.bazel b/stovepipe/entity/BUILD.bazel
index 778cf6d1..be03f14b 100644
--- a/stovepipe/entity/BUILD.bazel
+++ b/stovepipe/entity/BUILD.bazel
@@ -2,7 +2,10 @@ load("@rules_go//go:def.bzl", "go_library", "go_test")
 
 go_library(
     name = "entity",
-    srcs = ["request.go"],
+    srcs = [
+        "queue.go",
+        "request.go",
+    ],
     importpath = "github.com/uber/submitqueue/stovepipe/entity",
     visibility = ["//visibility:public"],
 )
diff --git a/stovepipe/entity/queue.go b/stovepipe/entity/queue.go
new file mode 100644
index 00000000..410e0654
--- /dev/null
+++ b/stovepipe/entity/queue.go
@@ -0,0 +1,40 @@
+// 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
+
+// DefaultMaxConcurrent is the default concurrency cap when wiring supplies no override.
+const DefaultMaxConcurrent int32 = 1
+
+// Queue is the per-queue coordination row. One row per named repo+ref; ingest, process,
+// and record advance different fields under optimistic-locking CAS.
+type Queue struct {
+	// Name is the stable logical id (e.g. "monorepo/main").
+	Name string `json:"name"`
+
+	// LastGreenURI is the most recent whole-repo-green commit; empty until first green.
+	LastGreenURI string `json:"last_green_uri"`
+
+	// InFlightCount is active Phase 1 validations not yet terminal.
+	InFlightCount int32 `json:"in_flight_count"`
+
+	// MaxConcurrent caps concurrent in-flight validations.
+	MaxConcurrent int32 `json:"max_concurrent"`
+
+	// LatestRequestSeq is the highest ingested request sequence for backlog coalescing.
+	LatestRequestSeq int64 `json:"latest_request_seq"`
+
+	// Version is used for optimistic locking.
+	Version int32 `json:"version"`
+}