issue 974: the builders say the checks they run in a bucket that ages, and a builder drops a waiting request for a head and trunk commit another is running

internal/broker/controller_buckets.go

@@ -49,6 +49,13 @@ var (
 	// controller's watcher hearing the expiry ends the wait and names the machine silent. Written by the lease
 	// holder alone.
 	RolloutSilentBucket = BucketName(ControllerSeat, "rollout-silent")
+	// CheckRunningBucket holds the pull request checks the builders are running now (novox/hq ADR 0406 §3, issue 974): per
+	// pull request a key `<owner>.<repo>.<number>` (or `group.<name>`) holding the head and trunk commit being checked, the
+	// builder and its build. A builder puts it when it starts a check and again on each heartbeat, and deletes it when the
+	// check ends; a key not renewed within the bucket's age is a builder that died, and is gone. A builder that takes a
+	// waiting request for a head and trunk commit a key names drops it. **Written by the build seat's holders, several by
+	// design** — each the key of the check it runs.
+	CheckRunningBucket = BucketName(ControllerSeat, "checks-running")
 )
 
 // The controller's record mirrors (novox/hq ADR 0289, design 54, design 57 package F3): a bucket per kind of
@@ -102,6 +109,10 @@ const RolloutSilentMarkerTTL = time.Minute
 // takes nothing live.
 const RolloutSilentKeptFor = time.Hour
 
+// CheckRunningKeptFor is the age of a running check's key: a few heartbeats (ten seconds each) of a builder, so a builder that
+// died is forgotten within two minutes and the check it ran is taken again then.
+const CheckRunningKeptFor = 2 * time.Minute
+
 // AskedKeptFor is how long an ask is kept after it was made: a month, as the router keeps its own.
 const AskedKeptFor = 30 * 24 * time.Hour
 
@@ -130,13 +141,13 @@ func IsControllerBucket(bucket string) bool {
 	return bucket == CallsBucket || bucket == HandActsBucket || bucket == ConditionsBucket ||
 		bucket == ConditionHistoryBucket || bucket == LeaseBucket || bucket == AskedBucket ||
 		bucket == AssignmentsBucket || bucket == DeclaredConfigBucket || bucket == PredefinedBucket ||
-		bucket == MergeWindowBucket || bucket == RolloutSilentBucket
+		bucket == MergeWindowBucket || bucket == RolloutSilentBucket || bucket == CheckRunningBucket
 }
 
 // ControllerBuckets are the controller's own buckets, in the order they are asserted.
 func ControllerBuckets() []string {
 	return []string{LeaseBucket, CallsBucket, HandActsBucket, ConditionsBucket, ConditionHistoryBucket, AskedBucket,
-		AssignmentsBucket, DeclaredConfigBucket, PredefinedBucket, MergeWindowBucket, RolloutSilentBucket}
+		AssignmentsBucket, DeclaredConfigBucket, PredefinedBucket, MergeWindowBucket, RolloutSilentBucket, CheckRunningBucket}
 }
 
 // ControllerBucketsAsserter is what raising the controller's buckets needs of a connection.
@@ -264,6 +275,21 @@ func (j *JetStream) EnsureControllerBuckets() error {
 	}); err != nil {
 		return fmt.Errorf("asserting bucket %s: %w", RolloutSilentBucket, err)
 	}
+	// **The checks running: a key that ages** (ADR 0406 §3, issue 974). One message a key, each renewal a new one, so the
+	// age of the bucket is how long a key outlives the builder that stopped renewing it.
+	if _, err := js.CreateOrUpdateKeyValue(ctx, jetstream.KeyValueConfig{
+		Bucket: CheckRunningBucket,
+		Description: "the pull request checks the builders are running now (novox/hq ADR 0406): `<pull request>` holds the " +
+			"head and trunk commit, the builder and its build; put by the builder when it starts and at each heartbeat, " +
+			"deleted when the check ends, gone within two minutes of a builder that died; written by the build seat's holders",
+		History:      1,
+		TTL:          CheckRunningKeptFor,
+		MaxValueSize: 4 << 10,
+		MaxBytes:     8 << 20,
+		Storage:      jetstream.FileStorage,
+	}); err != nil {
+		return fmt.Errorf("asserting bucket %s: %w", CheckRunningBucket, err)
+	}
 	// **The record mirrors: no age** (design 54 §5). A key is removed when its record is, by a purge whose
 	// marker lives a day; a key that expired would be a record the bus forgot while the store still holds it.
 	for _, m := range []struct{ bucket, why string }{