feat(stovepipe): Publish issue-tracking updates

Author: prathshenoy

doc/rfc/stovepipe/steps/buildanalysis.md

@@ -1,6 +1,6 @@
-# Build issue observation
+# Build issue detection
 
-Build analysis runs alongside status polling and recording. Hosts supply a queue-resolved detector factory. The reference service uses a no-op detector so the analysis stage is always wired without inspecting provider output; deployments replace the factory with their integration. No-op results do not establish build success or recovery.
+Build analysis runs alongside status polling and recording. Hosts supply a queue-resolved detector factory. The reference service uses a no-op detector so the analysis stage is always wired without inspecting provider output; deployments replace the factory with their integration. No-op results do not establish build success. The reference host registers an issue-tracking publication route but does not yet consume those notifications.
 
 ## Start and completion notices
 
@@ -10,9 +10,9 @@ Start and completion notices use distinct deterministic message IDs and the same
 
 Publication errors are returned through the producing stage's retry/DLQ policy. Analysis processing does not gate record, but notification publication is still part of the producing stage: a failed start publication can send the build-stage message to its existing fail-closed recovery path.
 
-## Observations and polling
+## Build issues and polling
 
-The [analysis controller](../../../../stovepipe/controller/buildanalysis/README.md) owns detection, per-build observation persistence, polling, and the stop condition for Requests that end without a recorded build result. It only accumulates historical observations; it does not maintain open issues or infer recovery from absence.
+The [analysis controller](../../../../stovepipe/controller/buildanalysis/README.md) owns detection, per-build issue persistence, polling, and the stop condition for Requests that end without a recorded build result. It accumulates per-build issues and publishes queue-partitioned issue-tracking notifications after persistence; it does not maintain open issues itself. Successful terminal analysis requests final reconciliation only after the Request records that Build as its winning outcome. Final reconciliation uses the accumulated build issues, including issues omitted from the last detector response. See the controller documentation for handoff and deduplication rules.
 
 Status-polling DLQ recovery does not publish a build-completion notice. The analysis polling loop observes the ended Request through storage instead.
 

service/stovepipe/server/main.go

@@ -409,7 +409,7 @@ func registerPrimaryControllers(
 	}
 	count++
 
-	analysisController := buildanalysis.NewController(logger, scope, store, detectorFactory, stovepipemq.TopicKeyBuildAnalysis, "stovepipe-buildanalysis")
+	analysisController := buildanalysis.NewController(logger, scope, store, detectorFactory, registry, stovepipemq.TopicKeyBuildAnalysis, "stovepipe-buildanalysis")
 	if err := c.Register(analysisController); err != nil {
 		return count, fmt.Errorf("failed to register buildanalysis controller: %w", err)
 	}
@@ -561,6 +561,11 @@ func newTopicRegistry(q extqueue.Queue, subscriberName string) (consumer.TopicRe
 			Queue:        q,
 			Subscription: extqueue.DLQSubscriptionConfig(subscriberName, "stovepipe-hook-dlq"),
 		},
+		{
+			Key:   stovepipemq.TopicKeyIssueTrack,
+			Name:  "issuetrack",
+			Queue: q,
+		},
 		{
 			Key:          stovepipemq.TopicKeyBuildAnalysis,
 			Name:         "buildanalysis",

service/stovepipe/server/main_test.go

@@ -92,6 +92,15 @@ func TestEveryRegisteredControllerResolvesInTheTopicRegistry(t *testing.T) {
 	}
 }
 
+func TestIssueTrackingHasPublicationRouteWithoutConsumption(t *testing.T) {
+	registry, primary, deadLetter := registeredControllers(t)
+	name, ok := registry.TopicName(stovepipemq.TopicKeyIssueTrack)
+	require.True(t, ok)
+	assert.Equal(t, "issuetrack", name)
+	assert.NotContains(t, topicKeys(primary), stovepipemq.TopicKeyIssueTrack)
+	assert.NotContains(t, topicKeys(deadLetter), dlq.TopicKey(stovepipemq.TopicKeyIssueTrack))
+}
+
 func TestHookStage(t *testing.T) {
 	registry, primary, deadLetter := registeredControllers(t)
 

stovepipe/controller/build/build_analysis_test.go

@@ -110,15 +110,16 @@ func TestBuildAnalysisPipeline(t *testing.T) {
 
 	detectorFactory := buildissuemock.NewMockDetectorFactory(ctrl)
 	detector := buildissuemock.NewMockDetector(ctrl)
-	detectorFactory.EXPECT().For(buildissue.DetectorConfig{QueueName: testQueue}).Return(detector, nil).Times(3)
+	detectorFactory.EXPECT().For(buildissue.DetectorConfig{QueueName: testQueue}).Return(detector, nil).Times(4)
 	gomock.InOrder(
 		detector.EXPECT().Detect(gomock.Any(), entity.BuildID{ID: testBuildID}).Return([]entity.BuildIssue{a}, nil),
-		detector.EXPECT().Detect(gomock.Any(), entity.BuildID{ID: testBuildID}).Return([]entity.BuildIssue{a, b}, nil),
-		detector.EXPECT().Detect(gomock.Any(), entity.BuildID{ID: testBuildID}).Return([]entity.BuildIssue{a, b}, nil),
+		detector.EXPECT().Detect(gomock.Any(), entity.BuildID{ID: testBuildID}).Return([]entity.BuildIssue{b}, nil),
+		detector.EXPECT().Detect(gomock.Any(), entity.BuildID{ID: testBuildID}).Return(nil, nil),
+		detector.EXPECT().Detect(gomock.Any(), entity.BuildID{ID: testBuildID}).Return(nil, nil),
 	)
 
 	analysisController := buildanalysis.NewController(zap.NewNop().Sugar(), tally.NoopScope,
-		staticStorageFactory{store: m.store}, detectorFactory, stovepipemq.TopicKeyBuildAnalysis, "analysis")
+		staticStorageFactory{store: m.store}, detectorFactory, buildController.registry, stovepipemq.TopicKeyBuildAnalysis, "analysis")
 	statusController := buildsignal.NewController(zap.NewNop().Sugar(), tally.NoopScope,
 		staticStorageFactory{store: m.store}, m.materializer, m.runnerFactory, buildController.registry,
 		stovepipemq.TopicKeyBuildSignal, "signal")
@@ -139,17 +140,37 @@ func TestBuildAnalysisPipeline(t *testing.T) {
 	assert.True(t, persisted[a])
 	assert.False(t, persisted[b])
 
+	secondPoll := delivered(published["buildanalysis"][0])
+	secondPoll.EXPECT().Hold(buildanalysis.PollDelayMs)
+	require.NoError(t, analysisController.Process(ctx, secondPoll))
+	assert.True(t, persisted[b])
+
 	require.NoError(t, statusController.Process(ctx, delivered(published["buildsignal"][0])))
 	require.Len(t, published["record"], 1)
 	require.Len(t, published["buildanalysis"], 2)
 	assert.Equal(t, entity.BuildStatusFailed, savedBuild.Status)
 	assert.Equal(t, entity.RequestStateFailed, request.State)
 	assert.Zero(t, queue.InFlightCount)
-	assert.False(t, persisted[b])
+	assert.True(t, persisted[b])
 	assert.NotEqual(t, published["buildanalysis"][0].ID, published["buildanalysis"][1].ID)
 
 	require.NoError(t, analysisController.Process(ctx, delivered(published["buildanalysis"][0])))
 	require.NoError(t, analysisController.Process(ctx, delivered(published["buildanalysis"][1])))
 	assert.Len(t, persisted, 2)
 	assert.True(t, persisted[b])
+	assert.True(t, persisted[a])
+
+	require.Len(t, published["issuetrack"], 4)
+	for i, msg := range published["issuetrack"] {
+		assert.Equal(t, testQueue, msg.PartitionKey)
+		assert.Equal(t, testQueue, msg.Tenant)
+		notification := &stovepipemq.IssueTrack{}
+		require.NoError(t, stovepipemq.Unmarshal(msg.Payload, notification))
+		assert.Equal(t, testBuildID, notification.GetBuildId())
+		assert.Equal(t, testQueue, notification.GetQueueName())
+		assert.Equal(t, i > 1, notification.GetFinalize())
+	}
+	assert.NotEqual(t, published["issuetrack"][0].ID, published["issuetrack"][1].ID)
+	assert.NotEqual(t, published["issuetrack"][1].ID, published["issuetrack"][2].ID)
+	assert.Equal(t, published["issuetrack"][2].ID, published["issuetrack"][3].ID)
 }

stovepipe/controller/build/build_test.go

@@ -99,6 +99,7 @@ func newController(t *testing.T, ctrl *gomock.Controller) (*Controller, buildMoc
 	registry, err := consumer.NewTopicRegistry([]consumer.TopicConfig{
 		{Key: stovepipemq.TopicKeyBuildSignal, Name: "buildsignal", Queue: queue},
 		{Key: stovepipemq.TopicKeyBuildAnalysis, Name: "buildanalysis", Queue: queue},
+		{Key: stovepipemq.TopicKeyIssueTrack, Name: "issuetrack", Queue: queue},
 		{Key: stovepipemq.TopicKeyRecord, Name: "record", Queue: queue},
 	})
 	require.NoError(t, err)

stovepipe/controller/buildanalysis/BUILD.bazel

@@ -12,6 +12,7 @@ go_library(
         "//platform/base/messagequeue:go_default_library",
         "//platform/consumer:go_default_library",
         "//platform/metrics:go_default_library",
+        "//platform/publish:go_default_library",
         "//stovepipe/core/loader:go_default_library",
         "//stovepipe/core/messagequeue:go_default_library",
         "//stovepipe/core/requestlog:go_default_library",
@@ -36,7 +37,9 @@ go_test(
         "//platform/consumer:go_default_library",
         "//platform/consumer/mock:go_default_library",
         "//platform/errs:go_default_library",
+        "//platform/extension/messagequeue/mock:go_default_library",
         "//platform/metrics:go_default_library",
+        "//platform/publish:go_default_library",
         "//stovepipe/core/messagequeue:go_default_library",
         "//stovepipe/core/requestlog:go_default_library",
         "//stovepipe/core/requestlog/mock:go_default_library",

stovepipe/controller/buildanalysis/README.md

@@ -1,31 +1,39 @@
 # Build analysis
 
-## Observations
+## Build issues
 
-The controller reloads the queue-scoped Build, invokes the queue's issue detector, and persists each returned observation individually. Observations already stored for the same build, task, and unit within a queue are not persisted again, so repeated polls and retries after partial writes are safe. Detector results accompanying an error are discarded.
+The controller reloads the queue-scoped Build, invokes the queue's issue detector, and persists each returned build issue individually. Build issues already stored for the same build, task, and unit within a queue are not persisted again, so repeated polls and retries after partial writes are safe. Detector results accompanying an error are discarded.
 
-This controller only accumulates historical observations. An empty detection result neither deletes earlier observations nor establishes recovery. Open-issue projection, lifecycle history, and resolution are outside its scope.
+After persistence, the controller publishes an issue-tracking notification partitioned by queue. Issue tracking maintains open issues and lifecycle history; analysis never writes them directly. An empty detection result does not delete earlier build issues.
+
+## Issue-tracking handoff
+
+Refresh notifications let issue tracking open issues reported by the build without closing other open issues. Final notifications let it also close open issues absent from the build's accumulated issues. A successful terminal detection must discover all remaining reportable issues; it need not repeat earlier build issues. An empty terminal response still triggers finalization, but does not retract earlier build issues from the same build. See the [detector contract](../../extension/buildissue/README.md).
+
+All analysis deliveries for a build must share its build-ID partition and consumer group. The controller validates that partition key. Finalization requires a successful pass that began with a terminal Build and the Request's recorded winning build ID. If status becomes terminal before that outcome is recorded, analysis publishes a refresh and holds until the outcome is available. Known losing builds do not publish. A terminal Request without a recorded winning build permits a refresh but not closing issues based on absence.
+
+Every refresh gets a fresh notification ID because held polling deliveries do not identify individual passes. A fixed ID would suppress later refreshes after earlier notifications were consumed. Retries can therefore publish duplicate refreshes; issue tracking is idempotent. Final notifications use one deterministic ID per build, so duplicate terminal passes deduplicate. Publication errors return through the normal analysis retry/DLQ policy; no hold or successful completion occurs before publication succeeds.
 
 ## Polling and completion
 
-Every delivery reloads the Build and its Request before detection. After a successful pass, a nonterminal Build holds the delivery for two minutes; a terminal Build completes the delivery after persistence. The status read before detection determines whether the pass holds: if the Build finishes during detection, another delivery is needed to analyze it after observing terminal status. More than one delivery may analyze the same terminal Build; observation persistence remains idempotent.
+Every delivery reloads the Build and its Request before detection. After a successful pass, a nonterminal Build holds the delivery for two minutes; a terminal Build completes after persistence and publication once its Request outcome is known, or the Request has ended without one. A pass that begins with a nonterminal Build always holds, even if the Build finishes during detection, so another delivery analyzes it after observing terminal status. More than one delivery may analyze the same terminal Build; build-issue persistence remains idempotent.
 
 If the Request is terminal but the loaded Build is nonterminal, analysis reloads the Build before deciding to stop. The Build may have finished between the initial Build read and the Request read; reloading avoids skipping its final analysis. If it is still nonterminal, analysis stops without detection or a hold. This can occur when the status-polling DLQ handler fails the Request without learning the actual build result, leaving the Build at its last observed status.
 
 Status polling and updates remain the responsibility of buildsignal. Analysis never changes Request state or releases build slots.
 
 ## Errors
 
-Detection, persistence, configuration, state-loading, and message-validation errors are returned to the consumer for its normal retry or DLQ policy, whether the Build is running or terminal. Analysis errors do not use the two-minute polling hold. The consumer classifies errors and applies its configured retry limits and backoff; a final analysis can still fail and dead-letter.
+Detection, persistence, publication, configuration, state-loading, and message-validation errors are returned to the consumer for its normal retry or DLQ policy, whether the Build is running or terminal. Analysis errors do not use the two-minute polling hold. The consumer classifies errors and applies its configured retry limits and backoff; a final analysis can still fail and dead-letter.
 
 ## DLQ recovery
 
-The recovery controller records a `build_analysis_abandoned` event in the Request's history, with the build ID, to indicate that analysis could not complete and issue observations may be incomplete. It does not rerun detection, delete earlier observations, change Request or Build state, or release a build slot. Original failure details are logged rather than included in the immutable history event.
+The recovery controller records a `build_analysis_abandoned` event in the Request's history, with the build ID, to indicate that analysis could not complete and the recorded build issues may be incomplete. It does not rerun detection, delete earlier build issues, change Request or Build state, or release a build slot. Original failure details are logged rather than included in the immutable history event.
 
 History identity is stable per build, so repeated recovery deliveries and separate analysis notices for the same build retain one event. Different builds retain different events, even for the same Request. A later successful analysis does not erase the historical occurrence.
 
 State-read and history-write errors are returned for retry. Hosts must run recovery with the DLQ consumer's always-retryable processor and unlimited-retry subscription; only recovery work is retried, not analysis. Unusable payloads, invalid or unresolvable queues, missing Build or Request records, and queue mismatches are logged and acknowledged rather than retried indefinitely.
 
 ## Host integration
 
-The reference service supplies a no-op detector and publishes analysis notices at build start and completion. It registers the normal analysis controller with bounded retries and the recovery controller with the existing DLQ consumer. See [build issue observation](../../../doc/rfc/stovepipe/steps/buildanalysis.md) for the publication rules and retry configuration.
+The reference service supplies a no-op detector and publishes analysis notices at build start and completion. It also registers a publish-only issue-tracking topic; issue-tracking consumption and recovery are not enabled yet. It registers the normal analysis controller with bounded retries and the recovery controller with the existing DLQ consumer. See [build issue detection](../../../doc/rfc/stovepipe/steps/buildanalysis.md) for the publication rules and retry configuration.