test: bound tackle freshness score

apps/api/app/schemas.py

@@ -118,7 +118,7 @@ class TackleCombinationOut(BaseModel):
     catches: int
     unique_players: int
     last_seen_at: datetime
-    freshness_score: int
+    freshness_score: int = Field(ge=0, le=100)
     status: str
     explanation: str
 

apps/api/openapi.json

@@ -2290,6 +2290,8 @@
             "type": "string"
           },
           "freshness_score": {
+            "maximum": 100.0,
+            "minimum": 0.0,
             "title": "Freshness Score",
             "type": "integer"
           },

apps/api/tests/test_analytics.py

@@ -6,6 +6,7 @@ from sqlalchemy.orm import Session
 from app.database import Base
 from app.models import CatchReport, CatchTackleComponent, Fish, ModerationStatus, SourceType, Spot, Waterbody
 from app.routers.analytics import tackle_combinations
+from app.schemas import TackleCombinationOut
 
 
 def test_tackle_recommendation_requires_samples_and_independent_players() -> None:
@@ -99,3 +100,18 @@ def test_tackle_analytics_exposes_decay_and_prefers_fresher_equal_samples() -> N
         assert rows[0].freshness_score <= 100
 
     engine.dispose()
+
+
+def test_tackle_freshness_score_contract_rejects_out_of_range_values() -> None:
+    base = {
+        "role": "lure", "value": "Spinner", "catches": 3, "unique_players": 2,
+        "last_seen_at": datetime.now(timezone.utc), "status": "recommendation", "explanation": "ok",
+    }
+    assert TackleCombinationOut(**base, freshness_score=0).freshness_score == 0
+    assert TackleCombinationOut(**base, freshness_score=100).freshness_score == 100
+    for value in (-1, 101):
+        try:
+            TackleCombinationOut(**base, freshness_score=value)
+        except ValueError:
+            continue
+        raise AssertionError(f"freshness score {value} was accepted")