test(flowcontrol): address review feedback on benchmark suite

- Use the llm-d Authors copyright header on the new files (doc.go,
  detector_test.go) per review.
- Fail fast if the PerformanceMatrix warmup request is not dispatched,
  matching the full-path harness, instead of silently timing a dead
  dispatch loop.
- Fail fast if a matrix coordinate dispatches zero requests, so a
  wedged dispatch path produces a red build instead of plausible
  zero rows.
- Drop the matrix harness TTL from 5m to 30s: nothing in a throughput
  benchmark legitimately waits minutes, and a tight TTL bounds a
  wedged coordinate to seconds of CI time instead of minutes per cell.
- Document the liveness bias of the benchDetector's stuck-read reclaim
  heuristic: true queueing still reports saturated while releases flow;
  a stalled release transiently over-admits rather than latching.

Signed-off-by: Luke Van Drie <lukevandrie@google.com>

Author: LukeAVanDrie

pkg/epp/flowcontrol/benchmark/benchmark_test.go

@@ -72,15 +72,17 @@ func BenchmarkFlowController_PerformanceMatrix(b *testing.B) {
 // runMatrixCoordinate executes a single coordinate of the performance hypercube.
 func runMatrixCoordinate(b *testing.B, m benchMatrix) {
 	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel() // Ensure SUT goroutines are torn down even when the coordinate fails fatally.
 
 	fc, detector := setupBenchmarkHarness(ctx, b, m.priorities, m.limit, nil, nil)
 
 	// Warm up: block on one request until it's dispatched, proving the dispatch loop is live before
-	// timing. Release the slot per the loop's immediate-drain protocol.
+	// timing. Release the slot per the loop's immediate-drain protocol (a no-op under free-flow).
 	warmup := &benchRequest{key: flowcontrol.FlowKey{ID: "warmup", Priority: 0}, byteSize: 1024}
-	if outcome, _ := fc.EnqueueAndWait(ctx, warmup); outcome == types.QueueOutcomeDispatched && m.limit > 0 {
-		detector.Release()
+	if outcome, err := fc.EnqueueAndWait(ctx, warmup); outcome != types.QueueOutcomeDispatched {
+		b.Fatalf("warmup request was not dispatched: outcome=%v, err=%v", outcome, err)
 	}
+	detector.Release()
 
 	reqs := make([]*benchRequest, m.flows)
 	for i := 0; i < int(m.flows); i++ {
@@ -166,6 +168,13 @@ func runMatrixCoordinate(b *testing.B, m benchMatrix) {
 	elapsed := b.Elapsed().Seconds()
 	telemetry.report(b, elapsed)
 
+	// Every coordinate expects flow (W>L or free-flow), so zero dispatches means the dispatch path
+	// wedged mid-run: fail loudly instead of publishing plausible-looking zero rows. Assert on the
+	// benchmark goroutine (never inside RunParallel, where FailNow is invalid).
+	if telemetry.dispatchCount.Load() == 0 {
+		b.Fatalf("coordinate %s dispatched zero requests; the dispatch path is wedged", m.name())
+	}
+
 	cancel()                          // Graceful teardown to prevent async skewing of subsequent coordinates.
 	time.Sleep(50 * time.Millisecond) // Wait for SUT background goroutines to terminate.
 }

pkg/epp/flowcontrol/benchmark/detector_test.go

@@ -1,5 +1,5 @@
 /*
-Copyright 2026 The Kubernetes Authors.
+Copyright 2026 The llm-d Authors.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

pkg/epp/flowcontrol/benchmark/doc.go

@@ -1,5 +1,5 @@
 /*
-Copyright 2026 The Kubernetes Authors.
+Copyright 2026 The llm-d Authors.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

pkg/epp/flowcontrol/benchmark/helpers_test.go

@@ -119,6 +119,12 @@ type benchDetector struct {
 // stuckReadThreshold is the number of consecutive saturated reads with zero intervening releases
 // after which the detector treats the outstanding grants as leaked idle permits and reclaims one.
 // >1 so that a single slow Release under load does not cause a spurious reclaim.
+//
+// The heuristic is deliberately biased toward liveness: if a genuine holder's Release stalls past
+// the threshold (e.g. its worker goroutine is descheduled), the reclaim transiently over-admits
+// beyond L rather than risking a latched-saturated deadlock. For a CPU-cost benchmark that is the
+// right trade: true queueing still reports saturated (1.0) while releases flow, and a slightly
+// loose L only shifts the coordinate's operating point, whereas a latch would hang the run.
 const stuckReadThreshold = 2
 
 // Release frees the permit held by the dispatch that just completed.
@@ -284,7 +290,10 @@ func setupBenchmarkHarness(
 	cfg := customCfg
 	if cfg == nil {
 		cfg = &controller.Config{
-			DefaultRequestTTL:        5 * time.Minute,
+			// Nothing in a throughput benchmark legitimately waits minutes: the worst observed
+			// steady-state queue wait is ~10s (L=1, W=5000). A tight TTL bounds the cost of a wedged
+			// coordinate to seconds of CI time instead of minutes per cell.
+			DefaultRequestTTL:        30 * time.Second,
 			ExpiryCleanupInterval:    1 * time.Hour, // Effectively disabled
 			EnqueueChannelBufferSize: 2000,
 		}