From ba36bcf7053f25df818e3ddb17f6fdfb887419ef Mon Sep 17 00:00:00 2001
From: raystorm <2557058999@qq.com>
Date: Tue, 5 May 2026 18:34:52 +0800
Subject: [PATCH] Add compatibility matrix tests for router config aliases

---
 router/config.py     |  2 ++
 tests/test_config.py | 72 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+)

diff --git a/router/config.py b/router/config.py
index ce88e18..0b37629 100644
--- a/router/config.py
+++ b/router/config.py
@@ -21,6 +21,8 @@ class HardRuleSpec(BaseModel):
 class RouterSettings(BaseModel):
     # entry_model is the product-facing alias; route_model remains supported for
     # backward compatibility with existing routes.yaml deployments.
+    # When both keys are present, route_model takes precedence via AliasChoices
+    # ordering for deterministic compatibility.
     route_model: str = Field(
         default="semantic-router",
         validation_alias=AliasChoices("route_model", "entry_model"),
diff --git a/tests/test_config.py b/tests/test_config.py
index 6b8242a..f9b7f4b 100644
--- a/tests/test_config.py
+++ b/tests/test_config.py
@@ -343,3 +343,75 @@ def test_router_settings_rejects_recursive_target_model():
                 ),
             },
         )
+
+
+def test_router_settings_accepts_entry_model_alias_key():
+    settings = RouterSettings.model_validate(
+        {
+            "entry_model": "smart-router",
+            "routes": {"fast": {"description": "low risk", "utterances": ["x"]}},
+        }
+    )
+    assert settings.route_model == "smart-router"
+    assert settings.entry_model == "smart-router"
+
+
+def test_router_settings_prefers_route_model_when_both_alias_keys_present():
+    settings = RouterSettings.model_validate(
+        {
+            "route_model": "route-model-wins",
+            "entry_model": "entry-model-loses",
+            "routes": {"fast": {"description": "low risk", "utterances": ["x"]}},
+        }
+    )
+
+    assert settings.route_model == "route-model-wins"
+
+
+def test_router_settings_accepts_fallback_route_id_key():
+    settings = RouterSettings.model_validate(
+        {
+            "fallback_route_id": "fast",
+            "routes": {"fast": {"description": "low risk", "utterances": ["x"]}},
+        }
+    )
+
+    assert settings.fallback_route_id == "fast"
+    assert settings.default_route == "fast"
+
+
+def test_router_settings_accepts_default_route_legacy_alias_key():
+    settings = RouterSettings.model_validate(
+        {
+            "default_route": "fast",
+            "routes": {"fast": {"description": "low risk", "utterances": ["x"]}},
+        }
+    )
+
+    assert settings.fallback_route_id == "fast"
+
+
+def test_router_settings_defaults_target_model_to_route_id_when_omitted():
+    settings = RouterSettings.model_validate(
+        {
+            "routes": {
+                "fast": {"description": "low risk", "utterances": ["x"]},
+                "strong": {"description": "high risk", "utterances": ["y"]},
+            }
+        }
+    )
+
+    assert settings.routes["fast"].target_model == "fast"
+    assert settings.routes["strong"].target_model == "strong"
+
+
+def test_router_settings_rejects_missing_fallback_route_id_in_routes():
+    with pytest.raises(ValidationError, match="fallback_route_id must be present"):
+        RouterSettings.model_validate(
+            {
+                "fallback_route_id": "missing",
+                "routes": {
+                    "fast": {"description": "low risk", "utterances": ["x"]},
+                },
+            }
+        )