Scale semantic-score keepScore terms onto a shared [0,1] range.

Normalize deadline urgency, fairness, and preempt cost so default weights stay meaningful under extreme inputs.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: FAUST-BENCHOU

docs/architecture/semantic-score.md

@@ -134,37 +134,40 @@ keepScore(s) =
   + w_C * normalize(preemptCost(s))
 ```
 
-| Term | Definition | If missing |
-|------|------------|------------|
+| Term | Definition (all ≈ `[0,1]`) | If missing |
+|------|----------------------------|------------|
 | `phaseProtect` | `tool_loop`/`lock` → 1.0; `llm_wait` → 0.2; `idle` → 0.0 | 0.5 |
-| `urgency` | See §5.4 | 0 |
-| `fairness` | `waitSec / (1 + attainedServiceSec)` | 0 |
-| `preemptCost` | Snapshot cost/size or `KeepAliveH` | 1 |
+| `urgency` | See §5.4 (online + prior, both scaled to `[0,1]`) | 0 |
+| `fairness` | Soft map of `r=wait/(1+attained)`: `1 − 1/(1+r)` ∈ `[0,1)` | 0 |
+| `preemptCost` | `clamp(log1p(H) / log1p(H_ref), 0, 1)` with `H_ref=1e6` | H=1 → small |
 
-Default weights: `w_L=3`, `w_U=2`, `w_F=2`, `w_C=1` (env-tunable).
+Default weights: `w_L=3`, `w_U=2`, `w_F=2`, `w_C=1` (env-tunable).  
+Terms share a common scale so weights stay meaningful (no raw `1/sec` or unbounded wait).
 
 Low score ⇒ yieldable phase, low urgency, already well-served, cheap to restore → kick first.
 
 ### 5.4 `urgency` (online + optional L3 prior)
 
 ```text
-urgency_online:
+urgency_online:                         # ∈ [0,1]
   if deadline:
-      1 / max(ε, seconds_until(deadline))     # deadline pressure (no step count)
+      1 / (1 + max(0, seconds_until(deadline)))
   else if API priority:
-      map(priority)
+      map(priority) into [0,1]
   else:
       0
 
-urgency_prior:   # from taskProfile — §6 (vLLM-SR traits, not expectedSteps)
-  clamp(0.5 + complexitySignal, 0, 1)        # continuous SR hard−easy signal
-  + α * embeddingSim                         # optional affinity boost
+urgency_prior:   # ∈ [0,1] — §6 (vLLM-SR traits, not expectedSteps)
+  clamp(
+    clamp(0.5 + complexitySignal, 0, 1)  # continuous SR hard−easy signal
+    + α * clamp(embeddingSim, 0, 1),
+    0, 1)
   # domain: affinity / pool filter when Worker pools exist; else unused in score
   # difficultyTier (if present) is debug-only; not used in keepScore
 
 urgency =
   if taskProfile.confidence high:
-      mix(urgency_online, urgency_prior)     # online dominates when present
+      mix(urgency_online, urgency_prior)     # both already on [0,1]
   else:
       urgency_online
 ```
@@ -306,7 +309,7 @@ demos/.../driver  ──classify(taskText)──► taskProfile
 | Path | Change |
 |------|--------|
 | `internal/signals/types.go` | `TaskProfile`: `ComplexitySignal`, `Domain`, `EmbeddingSim`, `Confidence`, `ModelID`, `ScoredAt`; `DifficultyTier` debug-only; stop using `ExpectedSteps*` in policy |
-| `internal/policy/semantic_score.go` | `urgencyPrior` = `clamp(0.5+complexitySignal) + α·embeddingSim`; ignore prior if `confidence < 0.3`; `urgency_online` from `deadline` only |
+| `internal/policy/semantic_score.go` | `urgencyPrior` / online / fairness / preempt all scaled to ≈`[0,1]`; ignore prior if `confidence < 0.3` |
 | `internal/policy/semantic_score_test.go` | Cases: higher `complexitySignal` outranks lower among unlocked peers; low confidence ignores prior |
 | CP / Kind env | `SEMANTIC_PRIOR_MIX`, `SEMANTIC_EMBED_ALPHA` (see §8); **no** HF model load in `controlplane` |
 

internal/policy/semantic_score.go

@@ -196,10 +196,11 @@ func urgency(sem signals.SemanticResource, priorMix, embedAlpha float64, now tim
 func urgencyOnline(sem signals.SemanticResource, now time.Time) float64 {
 	if sem.Deadline != nil && !sem.Deadline.IsZero() {
 		sec := sem.Deadline.Sub(now).Seconds()
-		if sec < 1e-3 {
-			sec = 1e-3
+		if sec < 0 {
+			sec = 0
 		}
-		return 1.0 / sec
+		// Maps remaining time → [0,1]: due now ⇒ 1, far ⇒ ~0.
+		return 1.0 / (1.0 + sec)
 	}
 	return 0
 }
@@ -209,32 +210,17 @@ func urgencyPrior(sem signals.SemanticResource, embedAlpha float64) float64 {
 		return 0
 	}
 	tp := sem.TaskProfile
-	// SR continuous signal → [0,1] contribution: clamp(0.5 + signal).
+	// SR continuous signal → [0,1]: clamp(0.5 + signal).
 	complexity := 0.0
 	if tp.ComplexitySignal != nil {
-		complexity = 0.5 + *tp.ComplexitySignal
-		if complexity < 0 {
-			complexity = 0
-		}
-		if complexity > 1 {
-			complexity = 1
-		}
-	}
-	sim := tp.EmbeddingSim
-	if sim < 0 {
-		sim = 0
-	}
-	if sim > 1 {
-		sim = 1
+		complexity = clamp01(0.5 + *tp.ComplexitySignal)
 	}
+	sim := clamp01(tp.EmbeddingSim)
 	if embedAlpha < 0 {
 		embedAlpha = 0
 	}
-	prior := complexity + embedAlpha*sim
-	if prior <= 0 {
-		return 0
-	}
-	return prior
+	// Keep prior on the same [0,1] scale as other keepScore terms.
+	return clamp01(complexity + embedAlpha*sim)
 }
 
 func fairness(sem signals.SemanticResource) float64 {
@@ -246,15 +232,33 @@ func fairness(sem signals.SemanticResource) float64 {
 	if wait < 0 {
 		wait = 0
 	}
-	return wait / (1 + att)
+	r := wait / (1 + att) // raw ratio, unbounded
+	// Soft map [0,∞) → [0,1): 0→0, 1→0.5, ∞→1.
+	return 1.0 - 1.0/(1.0+r)
 }
 
+// preemptHRef is the KeepAliveH / snapshot-cost scale that maps to ~1.0 after normalize.
+const preemptHRef = 1e6
+
 func normalizePreempt(h float64) float64 {
-	if h <= 0 || math.IsInf(h, 1) {
+	if h <= 0 {
+		return 0
+	}
+	if math.IsInf(h, 1) {
+		return 1
+	}
+	// log1p(H) / log1p(H_ref) ∈ (0,1] for H ≤ H_ref; clamp above.
+	return clamp01(math.Log1p(h) / math.Log1p(preemptHRef))
+}
+
+func clamp01(x float64) float64 {
+	if x < 0 {
+		return 0
+	}
+	if x > 1 {
 		return 1
 	}
-	// Soft compress so large H does not dominate phase/urgency weights.
-	return math.Log1p(h)
+	return x
 }
 
 func envFloat(k string, def float64) float64 {

internal/policy/semantic_score_test.go

@@ -177,3 +177,65 @@ func TestSemanticScorePrefersKickLowWaitHighAttained(t *testing.T) {
 		t.Fatalf("victim=%q want hog (low fairness)", res.VictimID)
 	}
 }
+
+func TestSemanticScoreKeepsNearDeadlineOverFar(t *testing.T) {
+	p := policy.NewSemanticScore()
+	now := time.Now()
+	p.Now = func() time.Time { return now }
+	near := now.Add(2 * time.Second)
+	far := now.Add(2 * time.Hour)
+	workers := []types.Worker{
+		{ID: "w1", MaxSlots: 1, UsedSlots: 1, Healthy: true, RegisteredAt: now},
+	}
+	running := []types.Sandbox{
+		{ID: "far", WorkerID: "w1", State: types.SandboxRunning, CreatedAt: now.Add(-time.Hour)},
+		{ID: "near", WorkerID: "w1", State: types.SandboxRunning, CreatedAt: now},
+	}
+	sandboxSig := map[string]signals.SandboxSignals{
+		"far": {SandboxID: "far", Semantic: signals.SemanticResource{
+			Phase: signals.PhaseLLMWait, Deadline: &far,
+		}},
+		"near": {SandboxID: "near", Semantic: signals.SemanticResource{
+			Phase: signals.PhaseLLMWait, Deadline: &near,
+		}},
+	}
+	res, err := p.Place(context.Background(), policy.PlaceRequest{
+		SandboxID: "new", Workers: workers, Running: running, SandboxSignals: sandboxSig,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.VictimID != "far" {
+		t.Fatalf("victim=%q want far (lower urgency_online)", res.VictimID)
+	}
+}
+
+func TestSemanticScoreHugePreemptCostDoesNotBeatToolLoopFilter(t *testing.T) {
+	// Unlocked idle with tiny H vs locked tool_loop with huge H: still kick idle.
+	p := policy.NewSemanticScore()
+	now := time.Now()
+	workers := []types.Worker{
+		{ID: "w1", MaxSlots: 1, UsedSlots: 1, Healthy: true, RegisteredAt: now},
+	}
+	running := []types.Sandbox{
+		{ID: "tool", WorkerID: "w1", State: types.SandboxRunning, CreatedAt: now.Add(-time.Hour)},
+		{ID: "idle", WorkerID: "w1", State: types.SandboxRunning, CreatedAt: now},
+	}
+	sandboxSig := map[string]signals.SandboxSignals{
+		"tool": {SandboxID: "tool", KeepAliveH: 1e18, Semantic: signals.SemanticResource{
+			Phase: signals.PhaseToolLoop, Lock: true,
+		}},
+		"idle": {SandboxID: "idle", KeepAliveH: 1, Semantic: signals.SemanticResource{
+			Phase: signals.PhaseIdle,
+		}},
+	}
+	res, err := p.Place(context.Background(), policy.PlaceRequest{
+		SandboxID: "new", Workers: workers, Running: running, SandboxSignals: sandboxSig,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.VictimID != "idle" {
+		t.Fatalf("victim=%q want idle (lock filter before cost)", res.VictimID)
+	}
+}