feat(stovepipe): Add build analysis contract

Author: prathshenoy

Makefile

@@ -628,6 +628,7 @@ GO_GENERATE_PACKAGES := \
 	./runway/extension/merger/... \
 	./stovepipe/controller/... \
 	./stovepipe/core/requestlog/... \
+	./stovepipe/extension/buildanalysis/... \
 	./stovepipe/extension/buildrunner/... \
 	./stovepipe/extension/projectstatus/... \
 	./stovepipe/extension/queueconfig/... \

stovepipe/entity/BUILD.bazel

@@ -4,6 +4,7 @@ go_library(
     name = "go_default_library",
     srcs = [
         "build.go",
+        "build_report.go",
         "ingest.go",
         "list.go",
         "project_status.go",

stovepipe/entity/build_report.go

@@ -0,0 +1,59 @@
+// Copyright (c) 2026 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
+
+// BuildReportState describes the availability of a validation report.
+type BuildReportState string
+
+const (
+	// BuildReportStateUnknown means report availability has not been established.
+	BuildReportStateUnknown BuildReportState = ""
+	// BuildReportStatePending means a final report is not available yet.
+	BuildReportStatePending BuildReportState = "pending"
+	// BuildReportStateAvailable means a final validation report can be interpreted.
+	BuildReportStateAvailable BuildReportState = "available"
+	// BuildReportStateUnavailable means the attempt ended without a usable final report.
+	BuildReportStateUnavailable BuildReportState = "unavailable"
+)
+
+// BuildRetryDisposition describes the automatic retry decision for an attempt of a
+// validation task, not manual reruns or the retries used to read its evidence.
+type BuildRetryDisposition string
+
+const (
+	// BuildRetryDispositionUnknown means the automatic retry decision is not known.
+	BuildRetryDispositionUnknown BuildRetryDisposition = ""
+	// BuildRetryDispositionPending means an automatic retry is scheduled or running.
+	BuildRetryDispositionPending BuildRetryDisposition = "pending"
+	// BuildRetryDispositionExhausted means no automatic retry remains under the applicable policy.
+	BuildRetryDispositionExhausted BuildRetryDisposition = "exhausted"
+)
+
+// BuildReport contains validation evidence from the current attempt of a validation task.
+// A validation task is work executed and retried together; a unit is the
+// granularity of reported outcomes. All identifiers are opaque.
+type BuildReport struct {
+	// TaskID identifies the logical validation task within the build, stable across attempts.
+	TaskID string `json:"task_id"`
+	// AttemptID identifies this execution of the validation task; empty if none exists yet.
+	AttemptID string `json:"attempt_id"`
+	// State describes whether this attempt's final validation report is available.
+	State BuildReportState `json:"state"`
+	// FailedUnits lists failed validation-unit identifiers when State is available.
+	// An empty list establishes no failure within the report's coverage, not build success.
+	FailedUnits []string `json:"failed_units"`
+	// RetryDisposition describes the automatic retry decision for this attempt.
+	RetryDisposition BuildRetryDisposition `json:"retry_disposition"`
+}

stovepipe/extension/buildanalysis/BUILD.bazel

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

stovepipe/extension/buildanalysis/README.md

@@ -0,0 +1,26 @@
+# Build analysis
+
+`Reader` reads validation reports available from an active or completed build. It does not poll build status, wait for completion, schedule redelivery, or persist results. This package defines only the extension contract; it adds no running pipeline stage.
+
+Report values and their availability and retry-disposition enums are defined in the [domain model](../../entity/build_report.go).
+
+A build is the overall validation run. Within a build, a validation task is work executed and retried together, and an attempt is one execution of that task. A validation unit is the granularity at which an implementation reports outcomes within an attempt, not necessarily the smallest executable operation.
+
+A read returns a slice with one report for each relevant task discovered in the build, using its current attempt. Pending or unavailable reports are included rather than silently omitting those tasks. Task identities remain stable across retries within a build; attempt identities distinguish executions but do not establish their ordering. Task, attempt, and validation-unit identifiers are opaque.
+
+Implementations own artifact formats, provider APIs, task composition, validation-unit granularity, and automatic retry-policy interpretation. Queue routing belongs to host wiring through `Factory`.
+
+Report state describes result availability, not whether validation passed or failed:
+
+| State | Meaning |
+| --- | --- |
+| Unknown | Report availability has not been established; this is the zero value. |
+| Pending | The task has not started or its current attempt is still running, so final results are not available yet. |
+| Available | A final validation report can be interpreted, whether it contains failed units or no failures. |
+| Unavailable | The attempt ended without a usable final report, for example because expected output is missing or malformed. |
+
+Pending or unavailable reports do not invalidate usable reports from other tasks. An empty failure list in an available report means no failures were reported within its coverage; an empty list in a pending or unavailable report establishes nothing about validation success. Dependency failures, such as task-enumeration failures or timeouts while fetching output, return plain errors for the host's classifier rather than an unavailable report; callers discard reports returned with an error.
+
+Build status determines when the caller performs its final inspection. A final snapshot can still contain unavailable reports: analysis can finish without establishing every validation outcome. An empty report slice does not establish build success. Inferring recovery from absence requires an available report from comparable validation covering the unit. A consumer requiring terminal attribution must establish build completion and usable evidence for the relevant scope.
+
+Automatic retry disposition describes whether the current attempt of a task will be retried and is unknown unless the provider can establish it. The latest failed attempt alone does not prove exhaustion. Exhaustion applies to automatic retries under the current policy, not the possibility of a manual rerun. A unit's failure remains evidence of that attempt even when a retry is pending; consumers must not combine successive snapshots into a permanent union of failed units.

stovepipe/extension/buildanalysis/buildanalysis.go

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 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 buildanalysis defines validation reports available from active or
+// completed builds, independently of build status polling.
+package buildanalysis
+
+//go:generate mockgen -source=buildanalysis.go -destination=mock/buildanalysis_mock.go -package=mock
+
+import (
+	"context"
+
+	"github.com/uber/submitqueue/stovepipe/entity"
+)
+
+// Reader inspects every relevant task currently discoverable in a build,
+// returning one report per task for its current attempt without waiting.
+// Pending or unavailable reports are normal results. Implementations must be
+// safe for concurrent use and return plain errors for dependency failures.
+// Reports returned with an error must not be used.
+type Reader interface {
+	Read(ctx context.Context, buildID entity.BuildID) ([]entity.BuildReport, error)
+}
+
+// Config identifies the queue whose validation-report reader is requested.
+type Config struct {
+	// QueueName identifies the queue.
+	QueueName string
+}
+
+// Factory resolves a queue's reader; implementations and routing belong to host wiring.
+type Factory interface {
+	For(cfg Config) (Reader, error)
+}

stovepipe/extension/buildanalysis/mock/BUILD.bazel

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