refactor(common): centralize cross-feature and architecture gating

server/CMakeLists.txt

@@ -318,6 +318,7 @@ add_library(dflash_common STATIC
     src/common/daemon_loop.cpp
     src/common/gguf_inspect.cpp
     src/common/backend_factory.cpp
+    src/common/feature_gate.cpp
     src/placement/placement_config.cpp
     src/common/layer_split_utils.cpp
     src/common/ddtree.cpp
@@ -1114,23 +1115,57 @@ if(DFLASH27B_TESTS)
         add_test(NAME server_unit COMMAND test_server_unit)
     endif()
 
-    # 'make check' — builds test targets then runs ctest
-    if(TARGET test_server_unit)
-        set(_check_deps test_server_unit)
-        if(TARGET test_deepseek4_unit)
-            list(APPEND _check_deps test_deepseek4_unit)
+    # Feature/architecture gate tests. check_feature_compatibility(),
+    # collect_feature_warnings() and the capability table are pure functions,
+    # so this target deliberately compiles only feature_gate.cpp and
+    # placement_config.cpp — no dflash_common, no ggml, no GPU toolkit. That
+    # keeps a gate rule testable in seconds instead of behind a full backend
+    # build, which is the whole reason these tests do not live in
+    # test_server_unit.
+    if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/test/test_feature_gate.cpp")
+        add_executable(test_feature_gate test/test_feature_gate.cpp)
+        target_sources(test_feature_gate PRIVATE
+            src/common/feature_gate.cpp
+            src/placement/placement_config.cpp)
+        target_include_directories(test_feature_gate PRIVATE
+            ${CMAKE_CURRENT_SOURCE_DIR}/src
+            ${CMAKE_CURRENT_SOURCE_DIR}/src/common)
+        # compiled_placement_backend() is decided by these defines, so the
+        # gate must be tested with the same ones the server is built with.
+        if(DFLASH27B_GPU_BACKEND STREQUAL "hip")
+            target_compile_definitions(test_feature_gate PRIVATE
+                DFLASH27B_BACKEND_HIP=1 GGML_USE_HIP)
+        else()
+            target_compile_definitions(test_feature_gate PRIVATE
+                DFLASH27B_BACKEND_CUDA=1)
         endif()
-        add_custom_target(check
-            COMMAND ${CMAKE_CTEST_COMMAND} --output-on-failure
-            DEPENDS ${_check_deps}
-            COMMENT "Building and running unit tests"
-        )
+        add_test(NAME feature_gate COMMAND test_feature_gate)
+    endif()
+
+    # 'make check' — builds test targets then runs ctest.
+    # Collect deps per target rather than gating the whole list on
+    # test_server_unit: test_feature_gate has no CURL dependency, so it must
+    # still build when the server unit tests are skipped.
+    set(_check_deps "")
+    if(TARGET test_server_unit)
+        list(APPEND _check_deps test_server_unit)
+    endif()
+    if(TARGET test_feature_gate)
+        list(APPEND _check_deps test_feature_gate)
+    endif()
+    if(TARGET test_deepseek4_unit)
+        list(APPEND _check_deps test_deepseek4_unit)
+    endif()
+    if(TARGET test_server_unit)
+        set(_check_comment "Building and running unit tests")
     else()
-        add_custom_target(check
-            COMMAND ${CMAKE_CTEST_COMMAND} --output-on-failure
-            COMMENT "Building and running unit tests (server unit tests skipped — CURL not found)"
-        )
+        set(_check_comment "Building and running unit tests (server unit tests skipped — CURL not found)")
     endif()
+    add_custom_target(check
+        COMMAND ${CMAKE_CTEST_COMMAND} --output-on-failure
+        DEPENDS ${_check_deps}
+        COMMENT "${_check_comment}"
+    )
 
     if(DFLASH27B_GPU_BACKEND STREQUAL "cuda")
     # internal.h includes <cuda_runtime.h> when GGML_USE_CUDA is set; link

server/src/common/backend_args.h

@@ -0,0 +1,74 @@
+// Raw backend construction arguments.
+//
+// This contains only caller-requested configuration. Runtime facts derived
+// from the model or compiled binary belong in ResolvedBackendPlan instead.
+
+#pragma once
+
+#include "placement/placement_config.h"
+#include "placement/remote_draft_config.h"
+#include "placement/remote_target_shard_config.h"
+#include "prefill_attention_mode.h"
+
+namespace dflash::common {
+
+// Server-owned features that participate in backend admission even though
+// they are not consumed by ModelBackend construction itself. Keep these
+// separate from BackendArgs so the factory API remains usable by callers that
+// do not run the HTTP server.
+struct BackendFeatureConfig {
+    bool pflash_enabled = false;
+    bool pflash_drafter_configured = false;
+
+    // MoE-only server features. Recorded here so the gate can report them as
+    // inert on a dense architecture; both are applied via env vars at parse
+    // time rather than through BackendArgs.
+    bool routing_stats_requested = false;    // --freq / --collect-routing
+    bool adaptive_experts_requested = false; // --adaptive-experts
+};
+
+// A superset of all per-architecture config fields. The factory reads only
+// those relevant to the resolved architecture; unused fields are ignored.
+struct BackendArgs {
+    // Required
+    const char *    model_path   = nullptr;   // target .gguf
+
+    // Optional: speculative decode draft model (qwen35 only)
+    const char *    draft_path   = nullptr;
+
+    // Device placement
+    DevicePlacement device;
+    DevicePlacement draft_device;
+    RemoteDraftConfig remote_draft;
+    RemoteTargetShardConfig remote_target_shard;
+
+    // I/O — only used when running under daemon_loop (legacy). The new
+    // server passes -1 and uses on_token callbacks instead.
+    int             stream_fd    = -1;
+
+    // Chunked prefill
+    int                  chunk                = 512;
+    PrefillAttentionMode ds4_prefill_mode     = PrefillAttentionMode::Exact;
+    bool                 ds4_prefill_mode_set = false;
+
+    // deepseek4-specific decode options
+    int             ds4_expert_top_k = 0;  // 0 = model default
+    bool            ds4_fused_decode = false;
+
+    // Attention and speculative-decode options. Individual backends consume
+    // only the fields they support.
+    int             fa_window        = 0;  // 0 = full attention. qwen3.6 full-attn layers must see the whole context; a finite window drops the system prompt/tools -> breaks tool calls.
+    int             kq_stride_pad    = 32;
+    int             draft_swa_window = 0;
+    int             draft_ctx_max    = 4096;
+    bool            fast_rollback    = true;
+    bool            seq_verify       = false;
+    bool            ddtree_mode      = false;
+    int             ddtree_budget    = 22;
+    float           ddtree_temp      = 1.0f;
+    bool            ddtree_chain_seed = true;
+    int             verify_width     = 0;  // chain spec verify width; 0 = adaptive
+    bool            use_feature_mirror = false;
+};
+
+}  // namespace dflash::common