feat: add setFlashAttn(FlashAttn), deprecate the valueless enableFlashAttn

llama.cpp turned --flash-attn from a bare flag into a value-taking option in
b10273: on|off|auto is mandatory. enableFlashAttn() emits the key with no
value, so the parser consumes whatever argv token follows and the load dies
naming a flag the caller never set -- error: unknown value for --flash-attn:
'--reasoning-format' is a real observed message.

Until now the option was simply not expressible through this binding.
putScalar is protected, so a downstream caller could not work around it
either; srcmorph ships a plan-time refusal for exactly this reason.

args.FlashAttn follows the CacheType / TensorReadLazyMode pattern, and
setFlashAttn routes through putEnum, so the value lands as its own argv token
after the key.

enableFlashAttn() is deprecated rather than fixed in place. Rewriting it to
emit "on" would turn Flash Attention on for every caller whose argv happened
to survive -- a behaviour change wearing a bugfix's clothes. Error Prone's
@InlineMe suggestion is declined for the same reason and the suppression says
so: inlining would copy the broken emission into callers, which is the
opposite of the migration, and the replacement is not equivalent because it
takes a value the old method cannot supply.

One existing test had encoded the defect as the contract:
testToArrayComplexCombination asserted a 9-token argv built with
enableFlashAttn(). It now uses the new setter and asserts 10, and the
deprecated method's valueless emission gets its own test that says in its name
and javadoc that it is pinning a defect. Two further tests cover every enum
value and assert the value is the token immediately after the key -- the
property whose absence caused all of this.

llama module: 1478 tests, 0 failures.

Author: claude

CHANGELOG.md

@@ -9,6 +9,30 @@ from version 5.0.0 onward. Pre-fork releases (`1.x`–`4.2.0`) were authored by
 
 ## [Unreleased]
 
+### Added
+- **`ModelParameters.setFlashAttn(FlashAttn)` — the only way to express `--flash-attn` correctly.**
+  llama.cpp turned that option from a bare flag into a value-taking one in **b10273**: the
+  `on|off|auto` value is mandatory, so emitting the key alone makes the parser consume whatever argv
+  token happens to follow it. The failure is as misleading as it sounds — the load dies naming a flag
+  the caller never set, e.g. `error: unknown value for --flash-attn: '--reasoning-format'`.
+
+  The new `args.FlashAttn` enum follows the existing `CacheType` / `TensorReadLazyMode` pattern, so
+  the option is now expressible: `AUTO` is upstream's own default, `ON` forces it and fails the load
+  where the backend cannot provide it, `OFF` disables it.
+
+### Deprecated
+- **`ModelParameters.enableFlashAttn()`** — it emits the valueless `--flash-attn` described above.
+  Its behaviour is deliberately left unchanged rather than quietly rewritten to emit `on`: that would
+  turn Flash Attention *on* for callers whose argv happened to survive, which is a behaviour change
+  disguised as a fix. Migrate to `setFlashAttn(FlashAttn)`.
+
+### Fixed
+- **A test pinned the broken argv shape as correct.** `ModelParametersExtendedTest`'s
+  complex-combination case asserted a 9-token argv built with `enableFlashAttn()` — i.e. it encoded
+  the valueless emission as the expected contract, which is why no gate ever flagged it. It now uses
+  `setFlashAttn(FlashAttn.ON)` and asserts 10 tokens, and a separate test pins the deprecated
+  method's emission explicitly as the defect it is, so the two cannot be confused again.
+
 ## [5.1.0] - 2026-08-29
 
 > The entries below also cover the **b9917 → b10456** window (PRs #341–#394), which went unrecorded

llama/src/main/java/net/ladenthin/llama/args/FlashAttn.java

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+// SPDX-FileCopyrightText: 2023-2025 Konstantin Herud
+//
+// SPDX-License-Identifier: MIT
+
+package net.ladenthin.llama.args;
+
+/**
+ * Flash Attention mode for {@code --flash-attn}.
+ *
+ * <p>llama.cpp turned {@code --flash-attn} from a bare flag into a value-taking option in b10273:
+ * the value is mandatory, and emitting the key alone makes the parser consume whatever argv token
+ * follows it. That is why this is an enum rather than a boolean — see
+ * {@link net.ladenthin.llama.parameters.ModelParameters#setFlashAttn(FlashAttn)}.</p>
+ */
+public enum FlashAttn implements CliArg {
+
+    /** Force Flash Attention on; the model load fails if the backend cannot provide it. */
+    ON("on"),
+    /** Force Flash Attention off. */
+    OFF("off"),
+    /** Let llama.cpp decide per backend and model — upstream's own default. */
+    AUTO("auto");
+
+    private final String argValue;
+
+    FlashAttn(String argValue) {
+        this.argValue = argValue;
+    }
+
+    @Override
+    public String getArgValue() {
+        return argValue;
+    }
+}

llama/src/main/java/net/ladenthin/llama/parameters/ModelParameters.java

@@ -250,14 +250,46 @@ public ModelParameters disableContextShift() {
     }
 
     /**
-     * Enable Flash Attention (default: disabled).
+     * Enable Flash Attention by emitting {@code --flash-attn} with no value.
+     *
+     * <p><b>Deprecated because it produces an argv llama.cpp misreads.</b> Since b10273
+     * {@code --flash-attn} takes a mandatory {@code on|off|auto} value, so a valueless emission makes
+     * the parser consume the <em>next</em> argv token as the mode. The model load then fails naming a
+     * flag the caller never set &mdash; for example {@code error: unknown value for --flash-attn:
+     * '--reasoning-format'} &mdash; which is as misleading a diagnostic as it looks.</p>
+     *
+     * <p>Use {@link #setFlashAttn(FlashAttn)} instead. This method is kept so existing callers still
+     * compile, and its behaviour is deliberately unchanged: silently rewriting it to emit
+     * {@code on} would flip Flash Attention on for callers whose argv happened to survive, which is a
+     * behaviour change disguised as a fix.</p>
      *
      * @return this builder
+     * @deprecated emits a valueless {@code --flash-attn}; use {@link #setFlashAttn(FlashAttn)}
      */
+    @Deprecated
+    // Error Prone offers @InlineMe for a deprecated one-liner. Declined on purpose: inlining would
+    // copy setFlag(ModelFlag.FLASH_ATTN) -- the broken emission itself -- into every caller, which is
+    // the opposite of the migration. The replacement is setFlashAttn(FlashAttn), and it is not
+    // equivalent: it takes a value this method cannot supply.
+    @SuppressWarnings("InlineMeSuggester")
     public ModelParameters enableFlashAttn() {
         return setFlag(ModelFlag.FLASH_ATTN);
     }
 
+    /**
+     * Set the Flash Attention mode ({@code --flash-attn}).
+     *
+     * <p>The value is mandatory upstream, so this is the only way to express the option correctly.
+     * {@link FlashAttn#AUTO} is llama.cpp's own default and lets it decide per backend and model;
+     * {@link FlashAttn#ON} forces it and fails the load where the backend cannot provide it.</p>
+     *
+     * @param mode the Flash Attention mode
+     * @return this builder
+     */
+    public ModelParameters setFlashAttn(FlashAttn mode) {
+        return putEnum("--flash-attn", mode);
+    }
+
     /**
      * Use the full-size SWA KV cache so the sliding-window layers' KV is reusable across requests
      * (restores prompt-prefix cache reuse with {@link #setCacheReuse(int)}); costs ~2x SWA-layer

llama/src/test/java/net/ladenthin/llama/parameters/ModelParametersExtendedTest.java

@@ -22,6 +22,7 @@
 import net.ladenthin.llama.ClaudeGenerated;
 import net.ladenthin.llama.args.*;
 import net.ladenthin.llama.args.CacheType;
+import net.ladenthin.llama.args.FlashAttn;
 import net.ladenthin.llama.args.GpuSplitMode;
 import net.ladenthin.llama.args.MiroStat;
 import net.ladenthin.llama.args.NumaStrategy;
@@ -634,13 +635,50 @@ public void testDisableContextShift() {
         assertThat(p.parameters.get("--no-context-shift"), is(nullValue()));
     }
 
+    /**
+     * Pins the DEPRECATED method's emission -- a key with a null value, i.e. a valueless
+     * {@code --flash-attn} -- as the defect it is, not as the contract.
+     *
+     * <p>llama.cpp has required a mandatory {@code on|off|auto} since b10273, so this argv makes the
+     * parser eat the next token. The behaviour is kept deliberately (changing it would flip Flash
+     * Attention on for callers whose argv happened to survive); the migration is
+     * {@link ModelParameters#setFlashAttn}, whose tests are below.</p>
+     */
     @Test
-    public void testEnableFlashAttn() {
+    public void testEnableFlashAttn_deprecated_emitsNoValue() {
         ModelParameters p = new ModelParameters().enableFlashAttn();
         assertThat(p.parameters, hasKey("--flash-attn"));
         assertThat(p.parameters.get("--flash-attn"), is(nullValue()));
     }
 
+    @Test
+    public void testSetFlashAttnRendersEveryMode() {
+        // Every mode the enum declares must reach argv as its own CLI string; a mode added later is
+        // then covered without touching this test.
+        for (FlashAttn mode : FlashAttn.values()) {
+            ModelParameters p = new ModelParameters().setFlashAttn(mode);
+            assertThat(p.parameters, hasKey("--flash-attn"));
+            assertThat(p.parameters.get("--flash-attn"), is(mode.getArgValue()));
+        }
+    }
+
+    @Test
+    public void testSetFlashAttnPutsTheValueAfterTheKeyInArgv() {
+        // The point of the whole change: the value must be its own argv token immediately after the
+        // key. Anything else and llama.cpp consumes whatever follows as the mode.
+        String[] arr = new ModelParameters().setFlashAttn(FlashAttn.ON).toArray();
+        int key = -1;
+        for (int i = 0; i < arr.length; i++) {
+            if ("--flash-attn".equals(arr[i])) {
+                key = i;
+                break;
+            }
+        }
+        assertThat("--flash-attn missing from argv", key, is(not(-1)));
+        assertThat("--flash-attn is the last token, so its mandatory value is missing", key < arr.length - 1, is(true));
+        assertThat(arr[key + 1], is("on"));
+    }
+
     @Test
     public void testEnableSwaFull() {
         ModelParameters p = new ModelParameters().enableSwaFull();
@@ -1092,10 +1130,13 @@ public void testToArrayComplexCombination() {
                 .setModel("model.gguf")
                 .setCtxSize(2048)
                 .enableEmbedding()
-                .enableFlashAttn();
+                .setFlashAttn(FlashAttn.ON);
         String[] arr = p.toArray();
-        // argv[0]="" + --fit + on + --model + model.gguf + --ctx-size + 2048 + --embedding + --flash-attn = 9
-        assertThat(arr, arrayWithSize(9));
+        // argv[0]="" + --fit + on + --model + model.gguf + --ctx-size + 2048 + --embedding
+        //   + --flash-attn + on = 10.
+        // This used to call enableFlashAttn() and assert 9, which pinned the valueless emission as
+        // the expected argv shape -- the very defect setFlashAttn exists to fix.
+        assertThat(arr, arrayWithSize(10));
         assertThat(arr[0], is(""));
     }