addressing last review comments

Signed-off-by: Loic Marchal <lmarchal@redhat.com>

Author: loicmarchal

docs/metrics.md

@@ -258,15 +258,18 @@ Exposed when the `flowControl` feature gate is enabled.
 #### `flow_control_pool_saturation`
 
 *   **Type:** Gauge
-*   **Labels:** `inference_pool`
-*   **Description:** Pool saturation signal gating dispatch. 1.0 is the gating set point; values
-    above 1.0 indicate the magnitude of oversubscription past it (deliberately not clamped). An
-    empty pool reads as 1.0, and with the default utilization detector, endpoints with missing or
-    stale metrics score as fully saturated (fail-closed).
-*   **Usage:** When saturation reaches the usage limit threshold, the dispatch cycle skips
-    dispatching and requests remain queued. A reading pinned at exactly 1.0 can be fail-closed
-    stale-metrics or an empty pool rather than genuine overload (which typically reads above 1.0);
-    check `flow_control_stale_endpoints` to disambiguate.
+*   **Labels:** `inference_pool`, `stage`
+*   **Description:** Pool saturation signal gating dispatch. The `stage` label partitions by
+    pipeline role: `prefill` and `decode` are per-stage signals, `effective` is
+    `max(prefill, decode)` and is the value used for gating. In monolithic deployments (no role
+    labels) all endpoints land in the decode stage. 1.0 is the gating set point; values above 1.0
+    indicate the magnitude of oversubscription past it (deliberately not clamped). An empty pool
+    reads as 1.0, and with the default utilization detector, endpoints with missing or stale
+    metrics score as fully saturated (fail-closed).
+*   **Usage:** When the effective saturation reaches the usage limit threshold, the dispatch cycle
+    skips dispatching and requests remain queued. A reading pinned at exactly 1.0 can be
+    fail-closed stale-metrics or an empty pool rather than genuine overload (which typically reads
+    above 1.0); check `flow_control_stale_endpoints` to disambiguate.
 
 #### `flow_control_stale_endpoints`
 

pkg/epp/flowcontrol/controller/internal/processor_test.go

@@ -1214,15 +1214,15 @@ func TestProcessor(t *testing.T) {
 					makeEndpoint(bylabel.RoleDecode),
 				}
 
-				// Prefill is healthy but decode is saturated.
 				h.saturationDetector.SaturationFunc = func(_ context.Context, endpoints []fwkdl.Endpoint) float64 {
 					for _, ep := range endpoints {
-						role := ep.GetMetadata().Labels[bylabel.RoleLabel]
-						if role == bylabel.RoleDecode {
-							return 1.0
+						if ep.GetMetadata().Labels[bylabel.RoleLabel] != bylabel.RolePrefill {
+							// Any mixed or decode set reads healthy: the flat average is
+							// diluted by idle decode workers.
+							return 0.3
 						}
 					}
-					return 0.1
+					return 1.5 // homogeneous prefill subset: stage saturated
 				}
 
 				dispatched := h.processor.dispatchCycle(context.Background())

pkg/epp/metrics/llm_d_router_metrics.go

@@ -388,9 +388,11 @@ var (
 			Subsystem: LLMDRouterEndpointPickerSubsystem,
 			Name:      "flow_control_pool_saturation",
 			Help: metricsutil.HelpMsgWithStability(
-				"Pool saturation signal gating Flow Control dispatch. 1.0 is the gating set point; values above 1.0 "+
-					"indicate the magnitude of oversubscription past it. An empty pool reads as 1.0. With the default "+
-					"utilization detector, endpoints with missing or stale metrics score as fully saturated "+
+				"Pool saturation signal gating Flow Control dispatch. The stage label partitions by pipeline role: "+
+					"'prefill' and 'decode' are per-stage signals, 'effective' is max(prefill, decode) and is the "+
+					"value used for gating. 1.0 is the gating set point; values above 1.0 indicate the magnitude of "+
+					"oversubscription past it. An empty pool reads as 1.0. With the default utilization detector, "+
+					"endpoints with missing or stale metrics score as fully saturated "+
 					"(fail-closed; see flow_control_stale_endpoints).",
 				compbasemetrics.ALPHA),
 		},

pkg/epp/metrics/metrics.go

@@ -370,7 +370,9 @@ var (
 			Name:      "flow_control_pool_saturation",
 			Help: metricsutil.HelpMsgWithStability(
 				"[Deprecated: Use llm_d_epp_flow_control_pool_saturation] Pool saturation signal gating Flow Control "+
-					"dispatch. 1.0 is the gating set point; values above 1.0 indicate the magnitude of oversubscription "+
+					"dispatch. The stage label partitions by pipeline role: 'prefill' and 'decode' are per-stage "+
+					"signals, 'effective' is max(prefill, decode) and is the value used for gating. "+
+					"1.0 is the gating set point; values above 1.0 indicate the magnitude of oversubscription "+
 					"past it. An empty pool reads as 1.0. With the default utilization detector, endpoints with missing "+
 					"or stale metrics score as fully saturated (fail-closed; see "+
 					"llm_d_epp_flow_control_stale_endpoints).",