Finalizing v2 saturation engine (#836)

* feat: add priority, roles, multi-analyzer scoring, and GreedyByScore optimizer

Implement five interconnected enhancements to the V2 saturation engine:

1. Per-model priority config with "{modelID}#{namespace}" lookup and
   default fallback via resolveSaturationConfig()

2. P/D role types (prefill/decode/both) on VariantReplicaState,
   VariantDecision, and VariantCapacity, injected from deployment
   labels (llm-d.ai/role)

3. Per-role capacity aggregation in the V2 analyzer via
   aggregateByRole(), with scheduler queue demand split by role:
   prefill gets inputTokens, decode gets inputTokens+outputTokens

4. Multi-analyzer scoring infrastructure with AnalyzerScoreConfig
   and composite score = priority * sum(requiredCapacity_i * score_i)

5. Rename GreedyBySaturationOptimizer to GreedyByScoreOptimizer with
   score-based priority ordering, per-role work units for P/D
   disaggregated models, and proportional P/D balancing

* refactor: demand-proportional P/D distribution in GreedyByScoreOptimizer

Replace post-hoc proportionalPDBalance() with demand-proportional
allocation integrated into the fair-share algorithm itself.

Previously, disaggregated models created separate per-role work units
that competed independently in fair-share, then a post-processing step
patched up the P:D ratio based on initial replica counts.

Now each model enters fair-share as a single entity. When allocating
replicas, allocateByRole() distributes them between prefill/decode
roles proportional to their per-role RequiredCapacity. If one role
can't use GPUs (e.g. accelerator exhausted), subsequent iterations
let the other role absorb its share naturally.

Removed: proportionalPDBalance, initTargetsForRole, mergeWorkTargets
Added: allocateByRole, allocateToVariants, roleDemands on modelWork

* fix: prevent role absorption in demand-proportional P/D allocation

When one role cannot fully allocate (e.g., accelerator exhausted), consume
its unallocated share from remaining so it does not overflow to other roles
in subsequent fair-share iterations.

* refactor: use Analyzers list for V2 selection with per-analyzer threshold overrides

Replace analyzerName-based V2 detection with IsV2() that checks for
Analyzers list (new-style) or analyzerName (backward compat). Add
per-analyzer ScaleUpThreshold/ScaleDownBoundary overrides on
AnalyzerScoreConfig with global fallback via EffectiveScaleUpThreshold/
EffectiveScaleDownBoundary methods.

* refactor: convert interfaces tests to Ginkgo

Convert saturation_scaling_test.go from standard testing to Ginkgo
Describe/It/Expect style with DescribeTable for validation cases.
Add suite_test.go for Ginkgo test runner bootstrap.

* refactor: unify enforcer to single EnforcePolicyOnDecisions entry point

Remove V1-specific EnforcePolicy (map-based) and its helpers (applyScaleToZero,
ensureMinimumReplicas). The V1 path now converts targets to decisions first,
then uses EnforcePolicyOnDecisions — the same path as V2. This eliminates the
dependency on VariantSaturationAnalysis for cost data in the enforcer.

* refactor: move SaturationScalingConfig types from interfaces to config package

Move SaturationScalingConfig, AnalyzerScoreConfig, and related constants
(DefaultPriority, DefaultScaleUpThreshold, DefaultScaleDownBoundary) from
internal/interfaces/ to internal/config/ where they belong alongside the
rest of the configuration types. Update all imports across 15 files.

Author: ev-shindin

internal/config/config.go

@@ -7,7 +7,7 @@ import (
 
 	ctrl "sigs.k8s.io/controller-runtime"
 
-	interfaces "github.com/llm-d/llm-d-workload-variant-autoscaler/internal/interfaces"
+	"github.com/llm-d/llm-d-workload-variant-autoscaler/internal/interfaces"
 )
 
 // Config is the unified configuration structure for the WVA controller.
@@ -75,7 +75,7 @@ type featureFlagsConfig struct {
 
 // SaturationScalingConfigPerModel represents saturation scaling configuration
 // for all models. Maps model ID (or "default" key) to its configuration.
-type SaturationScalingConfigPerModel map[string]interfaces.SaturationScalingConfig
+type SaturationScalingConfigPerModel map[string]SaturationScalingConfig
 
 // QMAnalyzerConfigPerModel represents queueing model scaling configuration
 // for all models. Maps model ID (or "default" key) to its configuration.
@@ -310,13 +310,13 @@ func (c *Config) ScaleFromZeroMaxConcurrency() int {
 // SaturationConfig returns the current global saturation scaling configuration.
 // Thread-safe. Returns a copy to prevent external modifications.
 // For namespace-aware lookups, use SaturationConfigForNamespace instead.
-func (c *Config) SaturationConfig() map[string]interfaces.SaturationScalingConfig {
+func (c *Config) SaturationConfig() map[string]SaturationScalingConfig {
 	return c.SaturationConfigForNamespace("")
 }
 
 // resolveSaturationConfig resolves saturation config for a namespace (namespace-local > global).
 // Must be called while holding at least a read lock.
-func (c *Config) resolveSaturationConfig(namespace string) map[string]interfaces.SaturationScalingConfig {
+func (c *Config) resolveSaturationConfig(namespace string) map[string]SaturationScalingConfig {
 	// Check namespace-local first (if namespace is provided)
 	if namespace != "" {
 		if nsConfig, exists := c.saturation.namespaceConfigs[namespace]; exists {
@@ -358,19 +358,19 @@ func (c *Config) resolveScaleToZeroConfig(namespace string) ScaleToZeroConfigDat
 // Resolution order: namespace-local > global
 // Thread-safe. Returns a copy to prevent external modifications.
 // If namespace is empty, returns global config.
-func (c *Config) SaturationConfigForNamespace(namespace string) map[string]interfaces.SaturationScalingConfig {
+func (c *Config) SaturationConfigForNamespace(namespace string) map[string]SaturationScalingConfig {
 	c.mu.RLock()
 	defer c.mu.RUnlock()
 	sourceConfig := c.resolveSaturationConfig(namespace)
 	return copySaturationConfig(sourceConfig)
 }
 
 // copySaturationConfig creates a deep copy of the saturation config map.
-func copySaturationConfig(src map[string]interfaces.SaturationScalingConfig) map[string]interfaces.SaturationScalingConfig {
+func copySaturationConfig(src map[string]SaturationScalingConfig) map[string]SaturationScalingConfig {
 	if src == nil {
-		return make(map[string]interfaces.SaturationScalingConfig)
+		return make(map[string]SaturationScalingConfig)
 	}
-	result := make(map[string]interfaces.SaturationScalingConfig, len(src))
+	result := make(map[string]SaturationScalingConfig, len(src))
 	for k, v := range src {
 		result[k] = v
 	}
@@ -410,19 +410,19 @@ func copyScaleToZeroConfig(src ScaleToZeroConfigData) ScaleToZeroConfigData {
 // UpdateSaturationConfig updates the global saturation scaling configuration.
 // Thread-safe. Takes a copy of the provided map to prevent external modifications.
 // For namespace-local updates, use UpdateSaturationConfigForNamespace instead.
-func (c *Config) UpdateSaturationConfig(config map[string]interfaces.SaturationScalingConfig) {
+func (c *Config) UpdateSaturationConfig(config map[string]SaturationScalingConfig) {
 	c.UpdateSaturationConfigForNamespace("", config)
 }
 
 // UpdateSaturationConfigForNamespace updates the saturation scaling configuration for the given namespace.
 // If namespace is empty, updates global config.
 // Thread-safe. Takes a copy of the provided map to prevent external modifications.
-func (c *Config) UpdateSaturationConfigForNamespace(namespace string, config map[string]interfaces.SaturationScalingConfig) {
+func (c *Config) UpdateSaturationConfigForNamespace(namespace string, config map[string]SaturationScalingConfig) {
 	c.mu.Lock()
 	defer c.mu.Unlock()
 
 	// Make a copy to prevent external modifications
-	newConfig := make(map[string]interfaces.SaturationScalingConfig, len(config))
+	newConfig := make(map[string]SaturationScalingConfig, len(config))
 	maps.Copy(newConfig, config)
 
 	var oldCount int

internal/config/config_test.go

@@ -9,7 +9,7 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	interfaces "github.com/llm-d/llm-d-workload-variant-autoscaler/internal/interfaces"
+	"github.com/llm-d/llm-d-workload-variant-autoscaler/internal/interfaces"
 )
 
 // TestConfig_ThreadSafeUpdates tests that concurrent reads and writes to DynamicConfig
@@ -71,8 +71,8 @@ func TestConfig_ThreadSafeUpdates(t *testing.T) {
 			for j := 0; j < iterations; j++ {
 
 				// Update saturation config
-				newSatConfig := make(map[string]interfaces.SaturationScalingConfig)
-				newSatConfig["test-accelerator"] = interfaces.SaturationScalingConfig{
+				newSatConfig := make(map[string]SaturationScalingConfig)
+				newSatConfig["test-accelerator"] = SaturationScalingConfig{
 					KvCacheThreshold:     0.8,
 					QueueLengthThreshold: 5,
 					KvSpareTrigger:       0.1,
@@ -303,7 +303,7 @@ func TestConfig_NamespaceAwareResolutionPrecedence(t *testing.T) {
 	cfg := NewTestConfig()
 
 	// Set up global saturation config
-	globalSatConfig := map[string]interfaces.SaturationScalingConfig{
+	globalSatConfig := map[string]SaturationScalingConfig{
 		"default": {
 			KvCacheThreshold:     0.80,
 			QueueLengthThreshold: 5,
@@ -339,7 +339,7 @@ func TestConfig_NamespaceAwareResolutionPrecedence(t *testing.T) {
 	// Test 2: Namespace-local config takes precedence
 	t.Run("Namespace-local config takes precedence", func(t *testing.T) {
 		// Set namespace-local saturation config
-		nsSatConfig := map[string]interfaces.SaturationScalingConfig{
+		nsSatConfig := map[string]SaturationScalingConfig{
 			"default": {
 				KvCacheThreshold:     0.70, // Different from global (0.80)
 				QueueLengthThreshold: 3,    // Different from global (5)
@@ -388,7 +388,7 @@ func TestConfig_NamespaceConfigDeletion(t *testing.T) {
 	cfg := NewTestConfig()
 
 	// Set up global saturation config
-	globalSatConfig := map[string]interfaces.SaturationScalingConfig{
+	globalSatConfig := map[string]SaturationScalingConfig{
 		"default": {
 			KvCacheThreshold:     0.80,
 			QueueLengthThreshold: 5,
@@ -411,7 +411,7 @@ func TestConfig_NamespaceConfigDeletion(t *testing.T) {
 	namespace := "test-namespace"
 
 	// Set namespace-local config
-	nsSatConfig := map[string]interfaces.SaturationScalingConfig{
+	nsSatConfig := map[string]SaturationScalingConfig{
 		"default": {
 			KvCacheThreshold:     0.70,
 			QueueLengthThreshold: 3,
@@ -451,7 +451,7 @@ func TestConfig_MultipleNamespaces(t *testing.T) {
 	cfg := NewTestConfig()
 
 	// Set up global config
-	globalSatConfig := map[string]interfaces.SaturationScalingConfig{
+	globalSatConfig := map[string]SaturationScalingConfig{
 		"default": {
 			KvCacheThreshold:     0.80,
 			QueueLengthThreshold: 5,
@@ -463,7 +463,7 @@ func TestConfig_MultipleNamespaces(t *testing.T) {
 	namespace2 := "namespace2"
 
 	// Set namespace1 config
-	ns1SatConfig := map[string]interfaces.SaturationScalingConfig{
+	ns1SatConfig := map[string]SaturationScalingConfig{
 		"default": {
 			KvCacheThreshold:     0.70,
 			QueueLengthThreshold: 3,
@@ -472,7 +472,7 @@ func TestConfig_MultipleNamespaces(t *testing.T) {
 	cfg.UpdateSaturationConfigForNamespace(namespace1, ns1SatConfig)
 
 	// Set namespace2 config
-	ns2SatConfig := map[string]interfaces.SaturationScalingConfig{
+	ns2SatConfig := map[string]SaturationScalingConfig{
 		"default": {
 			KvCacheThreshold:     0.90,
 			QueueLengthThreshold: 7,

internal/config/loader_test.go

@@ -8,7 +8,7 @@ import (
 
 	flag "github.com/spf13/pflag"
 
-	interfaces "github.com/llm-d/llm-d-workload-variant-autoscaler/internal/interfaces"
+
 )
 
 // writeTestConfigFile writes a YAML config file to a temp directory and returns its path.
@@ -256,7 +256,7 @@ func TestConfig_UpdateDynamicConfig(t *testing.T) {
 	}
 
 	// Update saturation config
-	satConfig := map[string]interfaces.SaturationScalingConfig{
+	satConfig := map[string]SaturationScalingConfig{
 		"test": {
 			KvCacheThreshold:     0.9,
 			QueueLengthThreshold: 10,

internal/interfaces/saturation_scaling.go internal/config/saturation_scaling.gointernal/interfaces/saturation_scaling.go renamed to internal/config/saturation_scaling.go

@@ -1,7 +1,11 @@
-package interfaces
+package config
 
 import "fmt"
 
+// DefaultPriority is the default model priority multiplier.
+// Higher priority → preferential GPU allocation in fair-share.
+const DefaultPriority = 1.0
+
 // SaturationScalingConfig holds saturation-based scaling thresholds for a model variant.
 // Saturation scaling is enabled by default and uses these thresholds to determine when
 // replicas are saturated and when to scale up.
@@ -44,13 +48,64 @@ type SaturationScalingConfig struct {
 	// Used by V2 analyzer: spareCapacity = currentSupply - totalDemand / ScaleDownBoundary
 	// Default: 0.70 (70% utilization allows scale-down)
 	ScaleDownBoundary float64 `yaml:"scaleDownBoundary,omitempty"`
+
+	// Priority is a multiplier for this model's scaling urgency.
+	// Higher priority → preferential GPU allocation in fair-share.
+	// Default: 1.0 (neutral).
+	Priority float64 `yaml:"priority,omitempty"`
+
+	// Analyzers configures the set of analyzers and their weights.
+	// When empty and AnalyzerName is "saturation", defaults to
+	// [{Name: "saturation", Score: 1.0, Enabled: true}].
+	Analyzers []AnalyzerScoreConfig `yaml:"analyzers,omitempty"`
+}
+
+// AnalyzerScoreConfig configures an individual analyzer's weight in the
+// composite scoring function. Per-analyzer threshold overrides are optional;
+// when nil, the global top-level thresholds are used.
+type AnalyzerScoreConfig struct {
+	Name              string   `yaml:"name"`
+	Enabled           *bool    `yaml:"enabled,omitempty"`           // default true
+	Score             float64  `yaml:"score,omitempty"`             // default 1.0
+	ScaleUpThreshold  *float64 `yaml:"scaleUpThreshold,omitempty"` // overrides global
+	ScaleDownBoundary *float64 `yaml:"scaleDownBoundary,omitempty"` // overrides global
+}
+
+// EffectiveScaleUpThreshold returns the per-analyzer threshold if set,
+// otherwise falls back to the global value.
+func (a *AnalyzerScoreConfig) EffectiveScaleUpThreshold(global float64) float64 {
+	if a.ScaleUpThreshold != nil {
+		return *a.ScaleUpThreshold
+	}
+	return global
+}
+
+// EffectiveScaleDownBoundary returns the per-analyzer boundary if set,
+// otherwise falls back to the global value.
+func (a *AnalyzerScoreConfig) EffectiveScaleDownBoundary(global float64) float64 {
+	if a.ScaleDownBoundary != nil {
+		return *a.ScaleDownBoundary
+	}
+	return global
 }
 
 // GetAnalyzerName implements the AnalyzerConfig interface.
+// Returns "saturation" if Analyzers list is populated (new-style config),
+// otherwise returns the raw AnalyzerName field (backward compat).
 func (c *SaturationScalingConfig) GetAnalyzerName() string {
+	if len(c.Analyzers) > 0 {
+		return "saturation"
+	}
 	return c.AnalyzerName
 }
 
+// IsV2 returns true if this config selects the V2 token-based analyzer path.
+// V2 is active when either the Analyzers list is populated (new-style) or
+// AnalyzerName is "saturation" (old-style, backward compat).
+func (c *SaturationScalingConfig) IsV2() bool {
+	return len(c.Analyzers) > 0 || c.AnalyzerName == "saturation"
+}
+
 // V2 analyzer default thresholds, applied when fields are omitted from YAML config.
 const (
 	DefaultScaleUpThreshold  = 0.85
@@ -60,13 +115,33 @@ const (
 // ApplyDefaults fills in zero-valued V2 fields with their defaults.
 // Must be called before Validate() to handle omitempty zero-values correctly.
 func (c *SaturationScalingConfig) ApplyDefaults() {
-	if c.AnalyzerName == "saturation" {
+	if c.Priority == 0 {
+		c.Priority = DefaultPriority
+	}
+	if c.IsV2() {
 		if c.ScaleUpThreshold == 0 {
 			c.ScaleUpThreshold = DefaultScaleUpThreshold
 		}
 		if c.ScaleDownBoundary == 0 {
 			c.ScaleDownBoundary = DefaultScaleDownBoundary
 		}
+		// Default analyzers list when empty (backward compat for analyzerName: "saturation")
+		if len(c.Analyzers) == 0 {
+			enabled := true
+			c.Analyzers = []AnalyzerScoreConfig{
+				{Name: "saturation", Score: 1.0, Enabled: &enabled},
+			}
+		}
+		// Apply per-entry defaults
+		for i := range c.Analyzers {
+			if c.Analyzers[i].Score == 0 {
+				c.Analyzers[i].Score = 1.0
+			}
+			if c.Analyzers[i].Enabled == nil {
+				enabled := true
+				c.Analyzers[i].Enabled = &enabled
+			}
+		}
 	}
 }
 
@@ -86,14 +161,18 @@ func (c *SaturationScalingConfig) Validate() error {
 	if c.QueueSpareTrigger < 0 {
 		return fmt.Errorf("queueSpareTrigger must be >= 0, got %.1f", c.QueueSpareTrigger)
 	}
+	if c.Priority < 0 {
+		return fmt.Errorf("priority must be >= 0, got %.2f", c.Priority)
+	}
+
 	// KV cache threshold should be greater than spare trigger (otherwise contradictory)
 	if c.KvCacheThreshold < c.KvSpareTrigger {
 		return fmt.Errorf("kvCacheThreshold (%.2f) should be >= kvSpareTrigger (%.2f)",
 			c.KvCacheThreshold, c.KvSpareTrigger)
 	}
 
-	// V2 analyzer threshold validation
-	if c.AnalyzerName == "saturation" {
+	// V2 analyzer threshold validation (global defaults)
+	if c.IsV2() {
 		if c.ScaleUpThreshold <= 0 || c.ScaleUpThreshold > 1 {
 			return fmt.Errorf("scaleUpThreshold must be in (0, 1], got %.2f", c.ScaleUpThreshold)
 		}
@@ -103,6 +182,24 @@ func (c *SaturationScalingConfig) Validate() error {
 		if c.ScaleUpThreshold <= c.ScaleDownBoundary {
 			return fmt.Errorf("scaleUpThreshold (%.2f) must be > scaleDownBoundary (%.2f)", c.ScaleUpThreshold, c.ScaleDownBoundary)
 		}
+		// Per-analyzer threshold overrides
+		for _, a := range c.Analyzers {
+			if a.ScaleUpThreshold != nil {
+				if *a.ScaleUpThreshold <= 0 || *a.ScaleUpThreshold > 1 {
+					return fmt.Errorf("analyzer %q: scaleUpThreshold must be in (0, 1], got %.2f", a.Name, *a.ScaleUpThreshold)
+				}
+			}
+			if a.ScaleDownBoundary != nil {
+				if *a.ScaleDownBoundary <= 0 || *a.ScaleDownBoundary > 1 {
+					return fmt.Errorf("analyzer %q: scaleDownBoundary must be in (0, 1], got %.2f", a.Name, *a.ScaleDownBoundary)
+				}
+			}
+			up := a.EffectiveScaleUpThreshold(c.ScaleUpThreshold)
+			down := a.EffectiveScaleDownBoundary(c.ScaleDownBoundary)
+			if up <= down {
+				return fmt.Errorf("analyzer %q: scaleUpThreshold (%.2f) must be > scaleDownBoundary (%.2f)", a.Name, up, down)
+			}
+		}
 	}
 
 	return nil