From b0ee4b6bb953f16cc74dc846d284cd2d7d5f84df Mon Sep 17 00:00:00 2001
From: lapy <vin.lapenta@gmail.com>
Date: Thu, 6 Aug 2026 18:35:28 +0100
Subject: [PATCH] Harden model-spec dependency option cross-checks

Require dependencies[].option and required_when.option_key to reference
declared options, document OR semantics, and keep the toy demo in sync.
---
 docs/maintainers/model_specs.md               |  11 +-
 .../model_spec_demo/specs/toy_qwen3_asr.json  |  37 +++++-
 src/framework/model_spec/schema.cpp           |  62 ++++++++-
 tests/unittests/test_model_spec_system.cpp    | 120 +++++++++++++++++-
 4 files changed, 216 insertions(+), 14 deletions(-)

diff --git a/docs/maintainers/model_specs.md b/docs/maintainers/model_specs.md
index b83e9739..00967b1a 100644
--- a/docs/maintainers/model_specs.md
+++ b/docs/maintainers/model_specs.md
@@ -191,10 +191,13 @@ runtime option key is derived as `<family>.<option>`.
 Required dependencies are unconditional. Optional dependencies must declare
 typed `required_when` rows. Each row is a condition over a public option key.
 Common request keys such as `return_timestamps` stay unprefixed; model-specific
-keys stay namespaced. The dependency is needed when any row matches.
-`dependencies[].option` must name a declared option in the dependency `scope`,
-and every `required_when[].option_key` must refer to a declared public option in
-the referenced scope. Multiple `required_when` rows use OR semantics.
+session/load keys stay namespaced as `<family>.<name>`. Multiple rows are OR'd:
+the dependency is needed when **any** row matches.
+
+`dependencies[].option` must be a local name that already exists under
+`options.<scope>` for the same dependency `scope`. Each
+`required_when[].option_key` must refer to an option declared under
+`options.<required_when.scope>` (using the public key form above).
 
 ```json
 {
diff --git a/examples/model_spec_demo/specs/toy_qwen3_asr.json b/examples/model_spec_demo/specs/toy_qwen3_asr.json
index 9e9684ac..00e556d5 100644
--- a/examples/model_spec_demo/specs/toy_qwen3_asr.json
+++ b/examples/model_spec_demo/specs/toy_qwen3_asr.json
@@ -38,27 +38,55 @@
           "en",
           "zh"
         ],
+        "required": false,
         "default": "auto",
         "description": "Recognition language."
       },
       {
         "name": "return_timestamps",
         "type": "bool",
+        "required": false,
         "default": false,
         "description": "Return token timestamps when supported."
+      },
+      {
+        "name": "audio_chunk_mode",
+        "type": "enum",
+        "values": [
+          "auto",
+          "fixed",
+          "vad",
+          "none"
+        ],
+        "required": false,
+        "default": "auto",
+        "description": "Audio chunking mode."
       }
     ],
     "session": [
       {
-        "name": "toy_qwen3_asr.lookahead",
+        "name": "lookahead",
         "type": "int",
+        "required": false,
         "default": 3,
-        "description": "Toy decoder lookahead."
+        "description": "Toy decoder lookahead. Public key: toy_qwen3_asr.lookahead."
+      },
+      {
+        "name": "forced_aligner",
+        "type": "path",
+        "required": false,
+        "description": "Optional forced aligner model path. Public key: toy_qwen3_asr.forced_aligner."
+      },
+      {
+        "name": "vad",
+        "type": "path",
+        "required": false,
+        "description": "Optional Silero VAD path. Public key: toy_qwen3_asr.vad."
       }
     ],
     "load": [
       {
-        "name": "toy_qwen3_asr.weight_type",
+        "name": "weight_type",
         "type": "enum",
         "values": [
           "native",
@@ -67,8 +95,9 @@
           "bf16",
           "q8_0"
         ],
+        "required": false,
         "default": "native",
-        "description": "Toy weight storage type."
+        "description": "Toy weight storage type. Public key: toy_qwen3_asr.weight_type."
       }
     ]
   },
diff --git a/src/framework/model_spec/schema.cpp b/src/framework/model_spec/schema.cpp
index 291da22b..719f82dc 100644
--- a/src/framework/model_spec/schema.cpp
+++ b/src/framework/model_spec/schema.cpp
@@ -341,6 +341,39 @@ void validate_option(
     (void) require_spec_string(require_spec_field(value, "description", path), std::string(path) + ".description");
 }
 
+struct DeclaredOptions {
+    // Local option names keyed by scope (dependencies[].option looks here).
+    std::unordered_map<std::string, std::unordered_set<std::string>> local_by_scope;
+    // Public option keys keyed by scope (required_when.option_key looks here).
+    std::unordered_map<std::string, std::unordered_set<std::string>> public_by_scope;
+};
+
+DeclaredOptions collect_declared_options(const json::Value & value, const std::string & family, std::string_view path) {
+    DeclaredOptions declared;
+    require_spec_object(value, path);
+    for (const std::string scope : {"request", "session", "load"}) {
+        const auto child_path = std::string(path) + "." + scope;
+        const auto & rows = require_spec_array(require_spec_field(value, scope, path), child_path);
+        auto & locals = declared.local_by_scope[scope];
+        auto & publics = declared.public_by_scope[scope];
+        for (size_t index = 0; index < rows.size(); ++index) {
+            const auto & row = rows[index];
+            require_spec_object(row, child_path + "[" + std::to_string(index) + "]");
+            const auto name = require_spec_string(
+                require_spec_field(row, "name", child_path + "[" + std::to_string(index) + "]"),
+                child_path + "[" + std::to_string(index) + "].name");
+            if (scope == "request") {
+                locals.insert(name);
+                publics.insert(name);
+            } else {
+                locals.insert(name);
+                publics.insert(family + "." + name);
+            }
+        }
+    }
+    return declared;
+}
+
 void validate_options(const json::Value & value, const std::string & family, std::string_view path) {
     require_spec_object(value, path);
     for (const std::string scope : {"request", "session", "load"}) {
@@ -538,7 +571,11 @@ std::unordered_set<std::string> validate_packages(
     return package_ids;
 }
 
-void validate_dependencies(const json::Value & value, const std::string & family, std::string_view path) {
+void validate_dependencies(
+    const json::Value & value,
+    const std::string & family,
+    const DeclaredOptions & declared,
+    std::string_view path) {
     const auto & dependencies = require_spec_array(value, path);
     for (size_t index = 0; index < dependencies.size(); ++index) {
         const auto item_path = std::string(path) + "[" + std::to_string(index) + "]";
@@ -554,6 +591,11 @@ void validate_dependencies(const json::Value & value, const std::string & family
             fail(item_path + ".option", "dependency option must be local; the public key is derived as " + family + ".<option>");
         }
         validate_request_option_name(family + "." + option, family, item_path + ".option");
+        const auto local_it = declared.local_by_scope.find(scope);
+        if (local_it == declared.local_by_scope.end() || local_it->second.find(option) == local_it->second.end()) {
+            fail(item_path + ".option",
+                 "dependency option '" + option + "' is not declared in options." + scope);
+        }
         const auto required = require_spec_bool(require_spec_field(dependency, "required", item_path), item_path + ".required");
         if (dependency.find("required_for") != nullptr) {
             fail(item_path + ".required_for", "use typed required_when conditions");
@@ -582,6 +624,13 @@ void validate_dependencies(const json::Value & value, const std::string & family
                     require_spec_field(condition, "option_key", condition_path),
                     condition_path + ".option_key");
                 validate_request_option_name(option_key, family, condition_path + ".option_key");
+                const auto public_it = declared.public_by_scope.find(condition_scope);
+                if (public_it == declared.public_by_scope.end() ||
+                    public_it->second.find(option_key) == public_it->second.end()) {
+                    fail(condition_path + ".option_key",
+                         "required_when option_key '" + option_key +
+                             "' is not declared in options." + condition_scope);
+                }
                 const auto & equals = require_spec_field(condition, "equals", condition_path);
                 if (!equals.is_bool() && !equals.is_number() && !equals.is_string()) {
                     fail(condition_path + ".equals", "expected bool, number, or string");
@@ -635,7 +684,10 @@ void validate_v1(const json::Value & spec, std::string_view source_name) {
         require_spec_field(spec, "languages", source_name), nullptr, std::string(source_name) + ".languages", "language");
     validate_runtime(require_spec_field(spec, "runtime", source_name), std::string(source_name) + ".runtime");
     validate_capabilities(require_spec_field(spec, "capabilities", source_name), task_ids, std::string(source_name) + ".capabilities");
-    validate_options(require_spec_field(spec, "options", source_name), family, std::string(source_name) + ".options");
+    const auto & options_field = require_spec_field(spec, "options", source_name);
+    validate_options(options_field, family, std::string(source_name) + ".options");
+    const auto declared_options =
+        collect_declared_options(options_field, family, std::string(source_name) + ".options");
 
     const bool has_default_download =
         has_spec_field(spec, "package_defaults") && has_spec_field(*spec.find("package_defaults"), "download");
@@ -646,7 +698,11 @@ void validate_v1(const json::Value & spec, std::string_view source_name) {
     const auto packages_path = std::string(source_name) + ".packages";
     const auto & packages_field = require_spec_field(spec, "packages", source_name);
     const auto package_ids = validate_packages(packages_field, packages_path, has_default_download);
-    validate_dependencies(require_spec_field(spec, "dependencies", source_name), family, std::string(source_name) + ".dependencies");
+    validate_dependencies(
+        require_spec_field(spec, "dependencies", source_name),
+        family,
+        declared_options,
+        std::string(source_name) + ".dependencies");
     validate_ui(require_spec_field(spec, "ui", source_name), package_ids, std::string(source_name) + ".ui");
 
     const auto sources_path = std::string(source_name) + ".sources";
diff --git a/tests/unittests/test_model_spec_system.cpp b/tests/unittests/test_model_spec_system.cpp
index d4620f8a..cc761993 100644
--- a/tests/unittests/test_model_spec_system.cpp
+++ b/tests/unittests/test_model_spec_system.cpp
@@ -91,7 +91,46 @@ std::string schema_v1_spec_text(const std::string & dependencies) {
   "languages": ["en"],
   "runtime": {"tags": ["gguf"]},
   "capabilities": {"tts": ["long_form"]},
-  "options": {"request": [], "session": [], "load": []},
+  "options": {
+    "request": [
+      {
+        "name": "return_timestamps",
+        "type": "bool",
+        "required": false,
+        "default": false,
+        "description": "Return timestamps when supported."
+      },
+      {
+        "name": "audio_chunk_mode",
+        "type": "enum",
+        "values": ["auto", "fixed", "vad", "none"],
+        "required": false,
+        "default": "auto",
+        "description": "Audio chunking mode."
+      },
+      {
+        "name": "vad_path",
+        "type": "path",
+        "required": false,
+        "description": "Optional request-scoped VAD path."
+      }
+    ],
+    "session": [
+      {
+        "name": "peer_model_path",
+        "type": "path",
+        "required": false,
+        "description": "Peer model path."
+      },
+      {
+        "name": "vad_path",
+        "type": "path",
+        "required": false,
+        "description": "Session-scoped VAD path."
+      }
+    ],
+    "load": []
+  },
   "packages": [
     {
       "id": "toy_model_q8",
@@ -343,6 +382,59 @@ void test_legacy_dependencies_schema() {
           }
         ])JSON"),
         "missing required field 'path'");
+    // Dependency options must be declared under options.<scope>.
+    expect_rejects(
+        "undeclared_dependency_option",
+        schema_v1_spec_text(R"JSON([
+          {
+            "kind": "model",
+            "family": "peer_model",
+            "scope": "session",
+            "option": "missing_peer_path",
+            "required": true
+          }
+        ])JSON"),
+        "is not declared in options.session");
+    // required_when option keys must refer to declared options in that scope.
+    expect_rejects(
+        "undeclared_required_when_option",
+        schema_v1_spec_text(R"JSON([
+          {
+            "kind": "model",
+            "family": "peer_model",
+            "scope": "session",
+            "option": "peer_model_path",
+            "required": false,
+            "required_when": [
+              {
+                "scope": "request",
+                "option_key": "unknown_trigger",
+                "equals": true
+              }
+            ]
+          }
+        ])JSON"),
+        "is not declared in options.request");
+    // Session-scoped required_when keys use the public <family>.<name> form.
+    expect_rejects(
+        "required_when_session_local_name",
+        schema_v1_spec_text(R"JSON([
+          {
+            "kind": "model",
+            "family": "peer_model",
+            "scope": "session",
+            "option": "peer_model_path",
+            "required": false,
+            "required_when": [
+              {
+                "scope": "session",
+                "option_key": "peer_model_path",
+                "equals": "/tmp/peer"
+              }
+            ]
+          }
+        ])JSON"),
+        "is not declared in options.session");
 }
 
 void test_typed_schema_renamed_dependencies() {
@@ -363,8 +455,30 @@ void test_typed_schema_renamed_dependencies() {
     "asr": ["word_timestamps"]
   },
   "options": {
-    "request": [],
-    "session": [],
+    "request": [
+      {
+        "name": "return_timestamps",
+        "type": "bool",
+        "required": false,
+        "default": false,
+        "description": "Return word timestamps."
+      },
+      {
+        "name": "audio_chunk_seconds",
+        "type": "float",
+        "required": false,
+        "default": 15,
+        "description": "Audio chunk duration in seconds."
+      }
+    ],
+    "session": [
+      {
+        "name": "aligner_path",
+        "type": "path",
+        "required": false,
+        "description": "Forced aligner model path."
+      }
+    ],
     "load": []
   },
   "packages": [