Router/2383 policy parser hot reload (#2519)

* feat(router): add policy parser and hot-reload store

* feat(router): preserve collection routing metadata

* test(router): cover policy loading in CI

* fix(router): align pull validation with policy compilation

* fix(router): reject duplicate policy model names

* fix(router): harden policy store file handling

Author: eddierichter-amd

.github/workflows/cpp_server_build_test_release.yml

@@ -282,8 +282,11 @@ jobs:
           cmake --build --preset default --target test_routing_policy_semantic
           cmake --build --preset default --target test_routing_policy_deterministic
           cmake --build --preset default --target test_routing_policy_engine
+          cmake --build --preset default --target test_routing_policy_parser
+          cmake --build --preset default --target test_routing_policy_store
+          cmake --build --preset default --target test_model_manager_collection_validation
           cd build
-          ctest --output-on-failure -R "DirectoryWatcher|LatestVersionFallback|RoutingPolicy(Contract|Evaluator|Registry|Semantic|Deterministic|Engine)Test"
+          ctest --output-on-failure -R "DirectoryWatcher|LatestVersionFallback|RoutingPolicy(Contract|Evaluator|Registry|Semantic|Deterministic|Engine|Parser|Store)Test|ModelManagerCollectionValidationTest"
 
       - name: Upload .deb package
         uses: actions/upload-artifact@v7
@@ -588,8 +591,11 @@ jobs:
           cmake --build --preset default --target test_routing_policy_semantic
           cmake --build --preset default --target test_routing_policy_deterministic
           cmake --build --preset default --target test_routing_policy_engine
+          cmake --build --preset default --target test_routing_policy_parser
+          cmake --build --preset default --target test_routing_policy_store
+          cmake --build --preset default --target test_model_manager_collection_validation
           cd build
-          ctest --output-on-failure -R "DirectoryWatcher|LatestVersionFallback|RoutingPolicy(Contract|Evaluator|Registry|Semantic|Deterministic|Engine)Test"
+          ctest --output-on-failure -R "DirectoryWatcher|LatestVersionFallback|RoutingPolicy(Contract|Evaluator|Registry|Semantic|Deterministic|Engine|Parser|Store)Test|ModelManagerCollectionValidationTest"
 
       - name: Upload .pkg package
         if: steps.check_signing.outputs.has_signing == 'true'

CMakeLists.txt

@@ -630,6 +630,8 @@ set(SOURCES_CORE
     src/cpp/server/system_info.cpp
     src/cpp/server/recipe_options.cpp
     src/cpp/server/routing_policy.cpp
+    src/cpp/server/routing_policy_parser.cpp
+    src/cpp/server/routing_policy_store.cpp
     src/cpp/server/runtime_config.cpp
     src/cpp/server/telemetry.cpp
     src/cpp/server/logging_config.cpp
@@ -2025,6 +2027,78 @@ if(EXISTS "${_ROUTING_ENGINE_TEST_SRC}")
     add_test(NAME RoutingPolicyEngineTest COMMAND test_routing_policy_engine)
 endif()
 
+# Routing policy parser (issue #2383): collection.router JSON -> RoutePolicy,
+# schema/parser key parity, component resolution, and validation errors.
+set(_ROUTING_PARSER_TEST_SRC
+    "${CMAKE_CURRENT_SOURCE_DIR}/test/cpp/test_routing_policy_parser.cpp"
+)
+if(EXISTS "${_ROUTING_PARSER_TEST_SRC}")
+    add_executable(test_routing_policy_parser
+        test/cpp/test_routing_policy_parser.cpp
+        src/cpp/server/routing_policy.cpp
+        src/cpp/server/routing_policy_parser.cpp
+    )
+    target_include_directories(test_routing_policy_parser PRIVATE
+        ${CMAKE_CURRENT_SOURCE_DIR}/src/cpp/include
+        ${CMAKE_CURRENT_SOURCE_DIR}/test/cpp
+        ${CMAKE_CURRENT_BINARY_DIR}/include
+    )
+    target_link_libraries(test_routing_policy_parser PRIVATE nlohmann_json::nlohmann_json)
+    target_compile_definitions(test_routing_policy_parser PRIVATE
+        ROUTING_FIXTURE_DIR="${CMAKE_CURRENT_SOURCE_DIR}/test/cpp/fixtures/routing"
+        ROUTING_SCHEMA_FILE="${CMAKE_CURRENT_SOURCE_DIR}/src/cpp/resources/schemas/route_policy.schema.json"
+    )
+
+    include(CTest)
+    add_test(NAME RoutingPolicyParserTest COMMAND test_routing_policy_parser)
+endif()
+
+# Routing policy store (issue #2383): directory-backed policy loading and
+# DirectoryWatcher-triggered shared_ptr snapshot swaps.
+set(_ROUTING_STORE_TEST_SRC
+    "${CMAKE_CURRENT_SOURCE_DIR}/test/cpp/test_routing_policy_store.cpp"
+)
+if(EXISTS "${_ROUTING_STORE_TEST_SRC}")
+    add_executable(test_routing_policy_store
+        test/cpp/test_routing_policy_store.cpp
+        src/cpp/server/routing_policy.cpp
+        src/cpp/server/routing_policy_parser.cpp
+        src/cpp/server/routing_policy_store.cpp
+        src/cpp/server/directory_watcher.cpp
+    )
+    target_include_directories(test_routing_policy_store PRIVATE
+        ${CMAKE_CURRENT_SOURCE_DIR}/src/cpp/include
+        ${CMAKE_CURRENT_SOURCE_DIR}/test/cpp
+        ${CMAKE_CURRENT_BINARY_DIR}/include
+    )
+    target_link_libraries(test_routing_policy_store PRIVATE nlohmann_json::nlohmann_json)
+    find_package(Threads REQUIRED)
+    target_link_libraries(test_routing_policy_store PRIVATE Threads::Threads)
+    target_compile_definitions(test_routing_policy_store PRIVATE
+        ROUTING_FIXTURE_DIR="${CMAKE_CURRENT_SOURCE_DIR}/test/cpp/fixtures/routing"
+    )
+
+    include(CTest)
+    add_test(NAME RoutingPolicyStoreTest COMMAND test_routing_policy_store)
+endif()
+
+# ModelManager collection validation for collection.router registration:
+# /pull-style validation rejects malformed routing and preserves the routing
+# block in ModelInfo::extras after user-model registration.
+set(_MODEL_MANAGER_COLLECTION_VALIDATION_TEST_SRC
+    "${CMAKE_CURRENT_SOURCE_DIR}/test/cpp/test_model_manager_collection_validation.cpp"
+)
+if(EXISTS "${_MODEL_MANAGER_COLLECTION_VALIDATION_TEST_SRC}")
+    add_executable(test_model_manager_collection_validation
+        test/cpp/test_model_manager_collection_validation.cpp
+    )
+    target_link_libraries(test_model_manager_collection_validation PRIVATE lemonade-server-core)
+    add_dependencies(test_model_manager_collection_validation copy_resources)
+
+    include(CTest)
+    add_test(NAME ModelManagerCollectionValidationTest COMMAND test_model_manager_collection_validation)
+endif()
+
 # Auto-tune: GGUF array storage, scalar derivation, weighted KV cache computation.
 # Covers head_count_kv_per_layer, sliding_window_pattern, SWA precise weighted sum,
 # full_attention_interval exact count, and scalar fallback paths.

src/app/src/renderer/utils/modelData.ts

@@ -1,4 +1,4 @@
-import { isCollectionRecipe } from './recipeNames';
+import { isModelCollectionRecipe } from './recipeNames';
 
 export const USER_MODEL_PREFIX = 'user.';
 
@@ -36,6 +36,9 @@ export interface ModelInfo {
   // global default in toolDefinitions.json when set. Keeps {tool_list} and
   // {tool_guidance} placeholders so runtime substitution still works.
   system_prompt?: string;
+  // collection.router policies. Kept opaque in the general model catalog; router
+  // authoring tools validate against the routing schema.
+  routing?: unknown;
   [key: string]: unknown;
 }
 
@@ -76,7 +79,7 @@ const normalizeModelInfo = (info: unknown): ModelInfo | null => {
   const checkpoint = typeof info['checkpoint'] === 'string' ? info['checkpoint'] : '';
   const recipe = typeof info['recipe'] === 'string' ? info['recipe'] : '';
 
-  if (!recipe || (!checkpoint && !isCollectionRecipe(recipe))) {
+  if (!recipe || (!checkpoint && !isModelCollectionRecipe(recipe))) {
     return null;
   }
 
@@ -142,6 +145,10 @@ const normalizeModelInfo = (info: unknown): ModelInfo | null => {
     normalized.system_prompt = systemPrompt;
   }
 
+  if (isRecord(info['routing'])) {
+    normalized.routing = info['routing'];
+  }
+
   const vision = info['vision'];
   if (typeof vision === 'boolean') {
     normalized.vision = vision;
@@ -234,6 +241,10 @@ const fetchBuiltInModelsFromAPI = async (): Promise<ModelsData> => {
         modelInfo.system_prompt = model.system_prompt;
       }
 
+      if (model.routing && typeof model.routing === 'object' && !Array.isArray(model.routing)) {
+        modelInfo.routing = model.routing;
+      }
+
       // cloud_provider distinguishes per-provider buckets in the Model
       // Manager grouping (recipe="cloud" alone collapses all providers
       // into a single sub-heading).
@@ -289,6 +300,7 @@ const EXPORT_KNOWN_KEYS = new Set([
   'labels',
   'recipe',
   'recipe_options',
+  'routing',
   'size',
   'system_prompt',
 ]);
@@ -323,7 +335,7 @@ export const normalizeModelExportPayload = (
   const name = typeof payload.model_name === 'string' && payload.model_name ? payload.model_name : fallbackId;
   payload.model_name = name.startsWith(USER_MODEL_PREFIX) ? name : `${USER_MODEL_PREFIX}${name}`;
 
-  if (isCollectionRecipe(typeof payload.recipe === 'string' ? payload.recipe : undefined)) {
+  if (isModelCollectionRecipe(typeof payload.recipe === 'string' ? payload.recipe : undefined)) {
     // Normalize each embedded component with the same transform. Components
     // are leaf models: drop their (empty) collection fields and keep bare
     // names — the server decides `user.` prefixing when registering them.

src/app/src/renderer/utils/recipeNames.ts

@@ -1,9 +1,14 @@
 export const COLLECTION_OMNI_MODEL_RECIPE = 'collection.omni';
+export const COLLECTION_ROUTER_MODEL_RECIPE = 'collection.router';
 
 export const isCollectionRecipe = (recipe?: string): boolean => {
   return recipe === COLLECTION_OMNI_MODEL_RECIPE;
 };
 
+export const isModelCollectionRecipe = (recipe?: string): boolean => {
+  return recipe === COLLECTION_OMNI_MODEL_RECIPE || recipe === COLLECTION_ROUTER_MODEL_RECIPE;
+};
+
 // Recipe display names. Hardware-backend names (llamacpp, whispercpp, sd-cpp, …)
 // are populated at runtime from /system-info's `recipes[].display_name`, which is
 // generated from the C++ backend descriptors — the single source of truth. Only
@@ -12,6 +17,7 @@ export const isCollectionRecipe = (recipe?: string): boolean => {
 // no local support rows).
 export const RECIPE_DISPLAY_NAMES: Record<string, string> = {
   [COLLECTION_OMNI_MODEL_RECIPE]: 'Lemonade',
+  [COLLECTION_ROUTER_MODEL_RECIPE]: 'Router',
   'cloud': 'Cloud',
 };
 

src/cpp/cli/main.cpp

@@ -361,7 +361,7 @@ static bool has_manual_pull_options(const CliConfig& config) {
 
 static int handle_pull_command(lemonade::LemonadeClient& client, const CliConfig& config) {
     if (has_manual_pull_options(config)) {
-        if (lemon::is_collection_recipe(config.recipe)) {
+        if (lemon::is_omni_collection_recipe(config.recipe)) {
             if (config.components.empty()) {
                 std::cerr << "Error: omni pull requires --components MODEL [MODEL ...]."
                           << std::endl;
@@ -1271,7 +1271,7 @@ int main(int argc, char* argv[]) {
         ->type_name("TYPE CHECKPOINT")
         ->multi_option_policy(CLI::MultiOptionPolicy::TakeAll);
     pull_cmd->add_option("--recipe", config.recipe,
-        "Recipe for the custom user.* model (e.g., llamacpp, flm, sd-cpp, whispercpp, collection.omni)")
+        "Recipe for the custom user.* model (e.g., llamacpp, flm, sd-cpp, whispercpp, collection.omni, collection.router)")
         ->group("Manual Configuration Options")
         ->type_name("RECIPE")
         ->default_val(config.recipe);

src/cpp/cli/recipe_import.cpp

@@ -30,6 +30,7 @@ const std::vector<std::string> kKnownKeys = {
     "labels",
     "recipe",
     "recipe_options",
+    "routing",
     "size",
     "system_prompt"
 };
@@ -244,7 +245,7 @@ bool validate_and_transform_model_json(nlohmann::json& model_data) {
         return false;
     }
 
-    bool is_collection = lemon::is_collection_recipe(model_data["recipe"].get<std::string>());
+    bool is_collection = lemon::is_model_collection_recipe(model_data["recipe"].get<std::string>());
 
     bool has_checkpoints = model_data.contains("checkpoints") && model_data["checkpoints"].is_object();
     bool has_checkpoint = model_data.contains("checkpoint") && model_data["checkpoint"].is_string();

src/cpp/include/lemon/model_types.h

@@ -7,11 +7,20 @@
 namespace lemon {
 
 constexpr const char* COLLECTION_OMNI_MODEL_RECIPE = "collection.omni";
+constexpr const char* COLLECTION_ROUTER_MODEL_RECIPE = "collection.router";
 
-inline bool is_collection_recipe(const std::string& recipe) {
+inline bool is_omni_collection_recipe(const std::string& recipe) {
     return recipe == COLLECTION_OMNI_MODEL_RECIPE;
 }
 
+inline bool is_router_collection_recipe(const std::string& recipe) {
+    return recipe == COLLECTION_ROUTER_MODEL_RECIPE;
+}
+
+inline bool is_model_collection_recipe(const std::string& recipe) {
+    return is_omni_collection_recipe(recipe) || is_router_collection_recipe(recipe);
+}
+
 enum class ModelState {
     LOADING,
     READY,

src/cpp/include/lemon/routing_policy_parser.h

@@ -0,0 +1,41 @@
+#pragma once
+
+#include "lemon/routing_policy.h"
+
+#include <functional>
+#include <optional>
+#include <set>
+#include <string>
+#include <vector>
+
+namespace lemon {
+
+// Resolves a component name from collection JSON into the name the engine should
+// route to. Server integration can bind this to ModelManager::resolve_model_name;
+// pure parser tests use the identity resolver.
+using RoutingComponentResolver =
+    std::function<std::optional<std::string>(const std::string& component)>;
+
+struct RoutingPolicyParseOptions {
+    RoutingComponentResolver resolve_component;
+    bool require_declared_components = true;
+};
+
+// Parser key registries. The parser rejects any key outside these sets; the
+// schema-parity test compares them to route_policy.schema.json so parser and
+// schema vocabulary cannot drift silently.
+const std::set<std::string>& routing_policy_root_keys();
+const std::set<std::string>& routing_block_keys();
+const std::set<std::string>& routing_router_keys();
+const std::set<std::string>& routing_classifier_keys();
+const std::set<std::string>& routing_rule_keys();
+const std::set<std::string>& routing_match_expr_keys();
+const std::set<std::string>& routing_metadata_match_keys();
+
+// Parse a full collection.router document into engine-ready policy state.
+// Throws std::invalid_argument with a user-facing message on validation errors.
+RoutePolicy parse_route_policy_collection(
+    const json& collection_json,
+    const RoutingPolicyParseOptions& options = RoutingPolicyParseOptions{});
+
+} // namespace lemon

src/cpp/include/lemon/routing_policy_store.h

@@ -0,0 +1,51 @@
+#pragma once
+
+#include "lemon/directory_watcher.h"
+#include "lemon/routing_policy.h"
+#include "lemon/routing_policy_parser.h"
+
+#include <map>
+#include <memory>
+#include <string>
+
+namespace lemon {
+
+// Directory-backed cache of compiled collection.router engines. A reload builds
+// a complete immutable snapshot and atomically swaps the shared_ptr, so readers
+// either see the old valid set or the new valid set.
+//
+// This is the module-level hot-reload implementation for #2383. It is not wired
+// into Server request dispatch yet: #2385 owns attaching a store/registry to the
+// live server lifecycle and using its engines to route OpenAI requests.
+class RoutingPolicyStore {
+public:
+    struct Snapshot {
+        std::map<std::string, std::shared_ptr<const RoutingPolicyEngine>> engines;
+        std::map<std::string, std::string> errors;
+    };
+
+    RoutingPolicyStore(std::string directory,
+                       ClassifierServices services,
+                       RoutingPolicyParseOptions parse_options = {});
+    ~RoutingPolicyStore();
+
+    std::shared_ptr<const Snapshot> reload();
+    void start_watching();
+    void stop_watching();
+
+    std::shared_ptr<const RoutingPolicyEngine> get_engine(const std::string& model_name) const;
+    std::shared_ptr<const Snapshot> snapshot() const;
+
+private:
+    std::shared_ptr<const Snapshot> load_directory() const;
+
+    std::string directory_;
+    ClassifierServices services_;
+    RoutingPolicyParseOptions parse_options_;
+    std::unique_ptr<DirectoryWatcher> watcher_;
+    // TODO(C++20): replace std::atomic_load/store free functions with a
+    // std::atomic<std::shared_ptr<const Snapshot>> member (deprecated in C++20).
+    std::shared_ptr<const Snapshot> snapshot_;
+};
+
+} // namespace lemon

src/cpp/server/hf_variants.cpp

@@ -323,7 +323,7 @@ nlohmann::json fetch_pull_variants(const std::string& checkpoint, bool& not_foun
             manifest = nlohmann::json();
         }
         bool valid_manifest = manifest.is_object() &&
-            is_collection_recipe(manifest.value("recipe", std::string())) &&
+            is_omni_collection_recipe(manifest.value("recipe", std::string())) &&
             manifest.contains("components") && manifest["components"].is_array() &&
             !manifest["components"].empty() &&
             manifest.contains("models") && manifest["models"].is_array();