refactor(server): seal backend construction behind a plan

.github/workflows/ci.yml

@@ -82,15 +82,15 @@ jobs:
             -DCMAKE_BUILD_TYPE=Release
           cmake --build build --target \
             test_dflash test_generate test_flash_attn_sparse test_server_unit \
-            test_deepseek4_unit test_feature_gate test_seq_slot_manager \
+            test_deepseek4_unit test_backend_plan test_feature_gate test_seq_slot_manager \
             test_seq_engine_contract test_seq_batch_plan test_client_send_buffer \
             test_model_smoke test_batched_gdn test_concat_transpose -j$(nproc)
 
       - name: Run C++ server unit tests
         run: |
           cd server/build
           ctest --output-on-failure \
-            -R "server_unit|deepseek4_unit|feature_gate|seq_slot_manager|seq_engine_contract|seq_batch_plan|client_send_buffer|batched_gdn_cpu" \
+            -R "server_unit|deepseek4_unit|backend_plan|feature_gate|seq_slot_manager|seq_engine_contract|seq_batch_plan|client_send_buffer|batched_gdn_cpu" \
             --no-tests=error
 
       - name: Populate venv with cu128 torch + setuptools

server/CMakeLists.txt

@@ -541,6 +541,7 @@ add_library(dflash_common STATIC
     src/common/backend_precision.cpp
     src/common/daemon_loop.cpp
     src/common/gguf_inspect.cpp
+    src/common/backend_plan.cpp
     src/common/backend_factory.cpp
     src/common/feature_gate.cpp
     src/placement/placement_config.cpp
@@ -1842,6 +1843,24 @@ if(DFLASH27B_TESTS)
         endif()
     endif()
 
+    if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/test/test_backend_plan.cpp")
+        add_executable(test_backend_plan test/test_backend_plan.cpp)
+        target_sources(test_backend_plan PRIVATE
+            src/common/backend_plan.cpp
+            src/common/feature_gate.cpp
+            src/placement/placement_config.cpp)
+        target_include_directories(test_backend_plan PRIVATE
+            ${CMAKE_CURRENT_SOURCE_DIR}/src
+            ${CMAKE_CURRENT_SOURCE_DIR}/src/common)
+        if(DFLASH27B_GPU_BACKEND STREQUAL "hip")
+            target_compile_definitions(test_backend_plan PRIVATE
+                DFLASH27B_BACKEND_HIP=1 GGML_USE_HIP)
+        else()
+            target_compile_definitions(test_backend_plan PRIVATE
+                DFLASH27B_BACKEND_CUDA=1)
+        endif()
+    endif()
+
     function(dflash_discover_cppunit_tests target)
         if(CMAKE_CROSSCOMPILING)
             add_test(NAME "${target}" COMMAND ${target})
@@ -1874,6 +1893,7 @@ if(DFLASH27B_TESTS)
     set(_new_cppunit_test_targets
         test_platform_compat
         test_draft_swa
+        test_backend_plan
         test_feature_gate
         test_qwen35_split_tree_guard
         test_recurrent_snapshot
@@ -1959,6 +1979,9 @@ if(DFLASH27B_TESTS)
     if(TARGET test_feature_gate)
         list(APPEND _check_deps test_feature_gate)
     endif()
+    if(TARGET test_backend_plan)
+        list(APPEND _check_deps test_backend_plan)
+    endif()
     if(_check_deps)
         add_custom_target(check
             COMMAND ${CMAKE_CTEST_COMMAND} --output-on-failure

server/src/common/backend_args.h

@@ -1,11 +1,13 @@
 // Raw backend construction arguments.
 //
 // This contains only caller-requested configuration. Runtime facts derived
-// from the model or compiled binary belong in ResolvedBackendPlan instead.
+// from the model or compiled binary belong in BackendPlan instead.
 
 #pragma once
 
 #include <limits>
+#include <optional>
+#include <string>
 
 #include "placement/draft_residency.h"
 #include "placement/placement_config.h"
@@ -15,35 +17,40 @@
 
 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 {
+enum class KvFlashRequest {
+    Off,
+    Auto,
+    Fixed,
+};
+
+// Server-owned facts that participate in backend admission without becoming
+// backend construction arguments. This is the only projection the HTTP server
+// may pass into backend preparation.
+struct BackendAdmissionContext {
     bool pflash_enabled = false;
     bool pflash_drafter_configured = false;
     DraftResidencyPolicy draft_residency = DraftResidencyPolicy::Auto;
 
-    // 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
+    // Automatic sizing remains backend-owned because only the initialized
+    // backend has the VRAM budget. Fixed pools can participate in admission.
+    KvFlashRequest kvflash = KvFlashRequest::Off;
 
-    // A fixed KVFlash pool requested through DFLASH_KVFLASH. "auto" is
-    // resolved later by the backend because only it has the VRAM budget needed
-    // to know whether a pool will actually be active.
-    bool kvflash_enabled = false;
+    bool kvflash_requested() const {
+        return kvflash != KvFlashRequest::Off;
+    }
+    bool fixed_kvflash_requested() const {
+        return kvflash == KvFlashRequest::Fixed;
+    }
 };
 
 // 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
+    std::string model_path;  // target .gguf
 
     // Optional: speculative decode draft model (qwen35 only)
-    const char *    draft_path   = nullptr;
+    std::optional<std::string> draft_path;
 
     // Device placement
     DevicePlacement device;
@@ -82,13 +89,22 @@ struct BackendArgs {
     bool            fast_rollback    = true;
     bool            seq_verify       = false;
     bool            specla_mode      = false;
+    int             specla_top_k     = 4;
+    bool            specla_top_k_explicit = false;
     bool            ddtree_mode      = false;
     int             ddtree_budget    = 22;
     float           ddtree_temp      = 1.0f;
     bool            ddtree_chain_seed = true;
     float           ddtree_tau       = std::numeric_limits<float>::infinity();
+    bool            ddtree_tau_explicit = false;
     int             verify_width     = 0;  // chain spec verify width; 0 = adaptive
     bool            use_feature_mirror = false;
+
+    // MoE backend requests. The server currently realizes these through
+    // environment variables, but admission still treats them as explicit
+    // operator input rather than server-owned context.
+    bool            routing_stats_requested = false;
+    bool            adaptive_experts_requested = false;
 };
 
 }  // namespace dflash::common