Make DFlash multi-slot shared drafting opt-in

Author: Anbeeld

docs/beellama-args.md

@@ -530,6 +530,7 @@ DFlash diagnostic environment variables:
 | `GGML_DFLASH_VERBOSE_CONTRACT=1` | Logs extra drafter/target contract details during DFlash setup. |
 | `GGML_DFLASH_FORCE_CPU_CROSS=1` | Force the CPU hidden-state cross path even when the GPU ring is available. |
 | `GGML_DFLASH_VERIFY_PAD=1` | Re-enable diagnostic verifier padding to the active draft depth. Default is off because padded rows consume target verify time but are not sampled or accepted. |
+| `GGML_DFLASH_SHARED_DRAFT_BATCH=1` | Opt into the experimental shared multi-slot DFlash drafter graph. The default keeps per-slot cached drafting because the shared graph pays the full multi-slot cross-attention window and disables the drafter K/V projection cache. |
 | `GGML_DFLASH_GPU_RING=0` | Disable the GPU cross-attention ring and force the CPU ring path. |
 | `GGML_DFLASH_MULTI_GPU_TAPE=0` | Disable default-on multi-GPU DFlash GPU ring, hidden capture, tape, and replay. Use to force the CPU/eval-callback fallback for split target placement. |
 | `GGML_DFLASH_ALLOW_MULTI_GPU_TAPE=0` | Compatibility spelling for the same multi-GPU DFlash kill switch. |

docs/beellama-features.md

@@ -42,7 +42,7 @@ BeeLlama's practical advantage is combination. Public llama.cpp has the main run
 | Draft top-k for DFlash tree | No | No | `--draft-topk` | `--spec-draft-top-k` |
 | Adaptive DFlash depth | No | No | Speculative-code adaptive tracking | Server-side `profit` and `fringe` controllers with `--spec-dm-*` CLI |
 | Sampled DFlash CLI | No | No | No checked CLI surface for draft temperature | `--spec-draft-temp 0`, positive value, or `auto` |
-| Multi-slot DFlash | No | No | Shared DFlash slot machinery | Shared drafter context, slot cap, and flat batched drafting |
+| Multi-slot DFlash | No | No | Shared DFlash slot machinery | Shared drafter context, slot cap, and per-slot cached drafting by default; experimental flat batched drafting behind `GGML_DFLASH_SHARED_DRAFT_BATCH=1` |
 | Multimodal with speculation | Upstream rules | Upstream rules | Speculative decoding disabled under multimodal | Flat DFlash allowed; tree and non-DFlash spec disabled |
 | CopySpec | No checked match | No checked match | Yes | Yes as explicit `--spec-type copyspec` |
 | Suffix/recycle speculation | No checked match | No checked match | Yes | Yes |

tests/test-dflash-plumbing.cpp

@@ -207,6 +207,21 @@ int main(int argc, char ** argv) {
     ok &= expect(server_context.find("mark_mtp_draft_context_seq_rm_supported") == std::string::npos,
         "server must not keep the stale MTP seq_rm helper now that upstream probes ctx_dft directly");
 
+    {
+        const size_t shared_gate = server_context.find("bool dflash_shared_drafter_batch_allowed");
+        const size_t opt_in_env = server_context.find("GGML_DFLASH_SHARED_DRAFT_BATCH");
+        const size_t opt_in_check = server_context.find("dflash_shared_drafter_batch_enabled()", shared_gate);
+        const size_t draft_batch_call = server_context.find("common_speculative_draft_batch", shared_gate);
+
+        ok &= expect(shared_gate != std::string::npos &&
+                     opt_in_env != std::string::npos &&
+                     opt_in_check != std::string::npos &&
+                     draft_batch_call != std::string::npos &&
+                     shared_gate < opt_in_check &&
+                     opt_in_check < draft_batch_call,
+            "flat DFlash shared drafter batching must be explicit opt-in because the multi-slot graph disables the single-slot K/V cache");
+    }
+
     const size_t pretranspose = qwen35moe.find("\"qkv_mixed_pretranspose\"");
     const size_t transpose    = qwen35moe.find("qkv_mixed = ggml_transpose(ctx0, qkv_mixed)");
     const size_t transposed   = qwen35moe.find("cb(qkv_mixed, \"qkv_mixed_transposed\", il)");

tools/server/server-context.cpp

@@ -68,6 +68,14 @@ static bool dflash_verify_padding_enabled() {
     return enabled;
 }
 
+static bool dflash_shared_drafter_batch_enabled() {
+    static const bool enabled = [] {
+        const char * env = getenv("GGML_DFLASH_SHARED_DRAFT_BATCH");
+        return env && env[0] != '\0' && strcmp(env, "0") != 0;
+    }();
+    return enabled;
+}
+
 static bool server_model_is_dflash_drafter(const llama_model * model) {
     return model &&
         llama_model_dflash_block_size(model) > 1 &&
@@ -1981,6 +1989,9 @@ struct server_context_impl {
     }
 
     bool dflash_shared_drafter_batch_allowed(int n_drafting) {
+        if (!dflash_shared_drafter_batch_enabled()) {
+            return false;
+        }
         if (n_drafting < 2) {
             return false;
         }