From 229903cbf93722864cb9458731983b29cebafe60 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 1 Sep 2026 08:18:12 +0000
Subject: [PATCH 1/3] feat: wire flashAttn up for real, now that the binding
 can express it

The knob has been documented and settable since it was introduced, and could
never be forwarded. --flash-attn takes a mandatory on|off|auto, the binding
offered only a bare-flag setter, and emitting the key alone made llama.cpp's
parser consume the next argv token -- so the load died naming a flag the user
never set. 1.2.0 shipped a refusal at plan time rather than that diagnostic.

net.ladenthin:llama 5.2.0 adds ModelParameters.setFlashAttn(FlashAttn), so the
provider now emits --flash-attn on when the knob is set. false keeps emitting
nothing, which leaves llama.cpp's own auto default in force: that is what an
unconfigured run should get, and it is what every other optional knob here
does with its sentinel.

Both refusals go, along with the three tests that pinned them, and the
DEFAULT_FLASH_ATTN javadoc stops describing a knob that cannot be used. The
history is kept in that javadoc rather than deleted -- the reason the value
matters is exactly why the knob spent a release unusable.

The part that is more than bookkeeping: flashAttn moves out of the knob
sweep's NOT_SWEPT list into a real sweep case, so it is now set against a real
model on every run. Until now only the refusal had ever been executed, which
is what the removed TODO asked for. 36 sweep cases green, plus EngineSupport,
AiGenerationConfig and the factory mapping -- 105 tests.

llama.version moves to 5.2.0-SNAPSHOT deliberately: the binding change is not
published yet, so CI stays red until it is. The CHANGELOG says so, so a red
build is not mistaken for a regression.
---
 CHANGELOG.md                                  | 28 ++++++++++
 TODO.md                                       | 27 ----------
 srcmorph/pom.xml                              |  2 +-
 .../srcmorph/config/AiGenerationConfig.java   | 23 +++++----
 .../srcmorph/engine/EngineSupport.java        | 25 ---------
 .../LlamaCppJniAiGenerationProvider.java      | 43 +++-------------
 .../srcmorph/engine/EngineSupportTest.java    | 51 -------------------
 .../provider/LlamaCppJniKnobSweepTest.java    | 42 +++------------
 8 files changed, 56 insertions(+), 185 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cb6fda20..f17dee98 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,34 @@ The release procedure (prompt template and step-by-step instructions) lives in [
 
 ---
 
+## [Unreleased]
+
+### Added
+- **`flashAttn` works.** The knob was documented and settable since it was introduced, but could not
+  be forwarded: `--flash-attn` takes a mandatory `on|off|auto` and `net.ladenthin:llama` offered only
+  a bare-flag setter, which emitted the key alone and made llama.cpp's parser consume the following
+  argv token — the load then died naming a flag the user never set. 1.2.0 shipped a refusal at plan
+  time rather than that diagnostic.
+
+  `net.ladenthin:llama` **5.2.0** adds `ModelParameters.setFlashAttn(FlashAttn)`, so the provider now
+  emits `--flash-attn on` when the knob is set. `false` still emits nothing, which leaves llama.cpp's
+  own `auto` default in force — that is the correct behaviour for an unconfigured run, and it is what
+  the knob's javadoc now says.
+
+  **The knob is exercised against a real model for the first time.** `flashAttn` moves out of
+  `LlamaCppJniKnobSweepTest`'s `NOT_SWEPT` list into a real sweep case; until now only the refusal had
+  ever been executed.
+
+### Removed
+- The plan-time and provider-side refusals (`EngineSupport.validateFlashAttnIsNotRequested`,
+  `LlamaCppJniAiGenerationProvider.FLASH_ATTN_UNSUPPORTED_MESSAGE`) and the three tests that pinned
+  them.
+
+### Changed
+- **`net.ladenthin:llama` 5.1.0 → 5.2.0-SNAPSHOT.** Deliberately a snapshot: the binding change this
+  release depends on is not yet published. Building srcmorph therefore requires that snapshot to be
+  resolvable, and CI stays red until it is — recorded here so nobody mistakes it for a regression.
+
 ## [1.2.0] - 2026-09-01
 
 ### Added
diff --git a/TODO.md b/TODO.md
index 7c813f52..a89c3d11 100644
--- a/TODO.md
+++ b/TODO.md
@@ -55,33 +55,6 @@ recorded in git history and `crossrepostatus.md`, not here.
   not dropping the idea. Deliberately out of scope for 1.2.0: it is a build-time question, not a
   correctness one.
 
-- **Wire `flashAttn` up for real after `net.ladenthin:llama` 5.2.0 ships.** 1.2.0 *refuses* the knob
-  rather than forwarding it, in two places (`LlamaCppJniAiGenerationProvider.model()` for the direct
-  API path, `EngineSupport.validateFlashAttnIsNotRequested` for the plan phase), because the binding
-  cannot currently spell it: `-fa` takes a mandatory `[on|off|auto]`, `enableFlashAttn()` routes
-  through `setFlag` which stores `null`, and the argv renderer then emits the key with no token after
-  it — so llama.cpp swallows the *next* argv token and the load dies naming a flag the user never set
-  (`error: unknown value for --flash-attn: '--reasoning-format'`, reproduced against the shipped fat
-  jar). No workaround exists downstream: `putScalar` is `protected`.
-
-  When 5.2.0 lands with a value-taking setter: bump `llama.version`, replace both guards with the real
-  call, delete `FLASH_ATTN_UNSUPPORTED_MESSAGE` and the four tests that pin the refusal (two in
-  `EngineSupportTest`, one in `LlamaCppJniAiGenerationProviderTest`, and
-  `LlamaCppJniKnobSweepTest#flashAttn_isRefusedRatherThanSilentlyDropped`), and restore the
-  `flashAttn`/`cacheTypeV` guidance in `srcmorph-maven-plugin/README.md`. Then move `flashAttn` out of
-  `LlamaCppJniKnobSweepTest.NOT_SWEPT` into a real sweep case — that is the step that finally sets the
-  knob against a real model, which the refusal has never done. The sweep's completeness check keeps
-  the bookkeeping honest: it fails if the knob is neither swept nor excluded, so it cannot be left
-  half-migrated.
-
-  **The trap to avoid: bumping `llama.version` alone changes nothing visible.** The guards keep
-  throwing, the knob keeps looking broken, and every gate stays green — so this has to be an explicit
-  line on the bump checklist rather than something a version bump surfaces on its own. The upstream
-  fix is tracked in java-llama.cpp (`ModelParameters` needs `setFlashAttn(on|off|auto)` mirroring the
-  `CacheType` enum pattern, `enableFlashAttn()` deprecated, and
-  `ModelParametersExtendedTest.testToArrayComplexCombination` corrected — it currently pins the broken
-  9-token argv shape as correct).
-
 - **`enable_thinking` is sent unconditionally, including at its own default.**
   `LlamaCppJniAiGenerationProvider.model()` always puts `enable_thinking` into
   `chatTemplateKwargs`, at whatever `chatTemplateEnableThinking` says — and its default is `true`.
diff --git a/srcmorph/pom.xml b/srcmorph/pom.xml
index c0d176cd..4a9ae65d 100644
--- a/srcmorph/pom.xml
+++ b/srcmorph/pom.xml
@@ -50,7 +50,7 @@ SPDX-License-Identifier: Apache-2.0
              templating is unchanged. The rest of the provider's API surface (LlamaModel,
              InferenceParameters, ModelParameters, ChatResponse/Timings/Pair, ChatResponseParser,
              ReasoningFormat) is untouched by 5.1.0. -->
-        <llama.version>5.1.0</llama.version>
+        <llama.version>5.2.0-SNAPSHOT</llama.version>
         <!-- Native build selector for net.ladenthin:llama. Empty = the main jar (CPU, Ninja default).
              The gpu-cuda / gpu-vulkan profiles set a GPU classifier; or override with
              -Dllama.classifier=cuda13-windows-x86-64. GPU builds need their runtime on PATH
diff --git a/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiGenerationConfig.java b/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiGenerationConfig.java
index 62b8dcd9..90c78efb 100644
--- a/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiGenerationConfig.java
+++ b/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiGenerationConfig.java
@@ -280,17 +280,18 @@ public AiGenerationConfig() {
     /**
      * Default Flash Attention setting ({@code --flash-attn}).
      *
-     * <p><b>Enabling this is currently refused</b> &mdash; see
-     * {@code LlamaCppJniAiGenerationProvider.FLASH_ATTN_UNSUPPORTED_MESSAGE}. The binding emits
-     * {@code --flash-attn} without the {@code [on|off|auto]} value llama.cpp requires, so the parser
-     * swallows the following argv token and the model load dies naming an unrelated flag. srcmorph fails
-     * at plan time instead, until a binding release exposes a value-taking setter.</p>
-     *
-     * <p>{@code false} therefore emits nothing at all, which leaves llama.cpp's own default in force —
-     * and that default is {@code auto}, not off ({@code common.h}: {@code flash_attn_type =
-     * LLAMA_FLASH_ATTN_TYPE_AUTO}). An earlier version of this javadoc said {@code false} "leaves it off,
-     * as llama.cpp does"; both halves were wrong. Once the knob works, enabling it lowers KV-cache memory
-     * and is the precondition for quantizing the V cache ({@link #DEFAULT_CACHE_TYPE_V}).</p>
+     * <p>{@code true} emits {@code --flash-attn on}; {@code false} emits nothing at all, which leaves
+     * llama.cpp's own default in force — and that default is {@code auto}, not off ({@code common.h}:
+     * {@code flash_attn_type = LLAMA_FLASH_ATTN_TYPE_AUTO}). An earlier version of this javadoc said
+     * {@code false} "leaves it off, as llama.cpp does"; both halves were wrong. Enabling it lowers
+     * KV-cache memory and is the precondition for quantizing the V cache
+     * ({@link #DEFAULT_CACHE_TYPE_V}).</p>
+     *
+     * <p>The value matters, and that is why the knob went through a release refusing to be set at all:
+     * {@code --flash-attn} takes a mandatory {@code [on|off|auto]}, and the binding used to offer only a
+     * bare-flag setter, which emitted the key alone and made llama.cpp's parser consume the next argv
+     * token — killing the load while naming a flag the user never set. {@code net.ladenthin:llama}
+     * 5.2.0 added {@code ModelParameters.setFlashAttn(FlashAttn)}, which is what the provider uses.</p>
      */
     public static final boolean DEFAULT_FLASH_ATTN = false;
 
diff --git a/srcmorph/src/main/java/net/ladenthin/srcmorph/engine/EngineSupport.java b/srcmorph/src/main/java/net/ladenthin/srcmorph/engine/EngineSupport.java
index 0b19cd3a..ad1bfae4 100644
--- a/srcmorph/src/main/java/net/ladenthin/srcmorph/engine/EngineSupport.java
+++ b/srcmorph/src/main/java/net/ladenthin/srcmorph/engine/EngineSupport.java
@@ -18,7 +18,6 @@
 import net.ladenthin.srcmorph.provider.AiGenerationProviderFactory;
 import net.ladenthin.srcmorph.provider.GgufModelInfo;
 import net.ladenthin.srcmorph.provider.GgufModelInspector;
-import net.ladenthin.srcmorph.provider.LlamaCppJniAiGenerationProvider;
 import net.ladenthin.srcmorph.provider.LlamaCppJniConfig;
 import net.ladenthin.srcmorph.provider.LlamaCppJniConfigFactory;
 import org.jspecify.annotations.Nullable;
@@ -198,34 +197,10 @@ static void validateRoutedModelPaths(
                         + " (checked before any model is loaded; fix the modelPath, or set"
                         + " generationProvider to mock for a model-free run)");
             }
-            validateFlashAttnIsNotRequested(aiDefinitionKey, modelConfig);
             validateAgainstTheModelItself(aiDefinitionKey, modelConfig, Paths.get(modelPath));
         }
     }
 
-    /**
-     * Refuses {@code flashAttn} at plan time, before any model is loaded or any file written.
-     *
-     * <p>The knob is documented and settable but cannot work with the pinned binding: {@code -fa} takes a
-     * mandatory {@code [on|off|auto]} value and {@code ModelParameters.enableFlashAttn()} emits the flag
-     * without one, so llama.cpp swallows the following argv token and the load dies naming a flag the
-     * user never set. Refusing here rather than in the provider means a multi-model run fails before its
-     * first group generates, instead of after.</p>
-     *
-     * @param aiDefinitionKey the model definition being validated, for the message
-     * @param modelConfig     its resolved configuration
-     * @throws SrcMorphException when {@code flashAttn} is enabled
-     */
-    private static void validateFlashAttnIsNotRequested(
-            final String aiDefinitionKey, final AiGenerationConfig modelConfig) throws SrcMorphException {
-        // TODO: remove together with the provider-side guard once net.ladenthin:llama 5.2.0 exposes a
-        // value-taking Flash Attention setter -- see the TODO in LlamaCppJniAiGenerationProvider.model().
-        if (modelConfig.isFlashAttn()) {
-            throw new SrcMorphException("aiDefinition '" + aiDefinitionKey + "': "
-                    + LlamaCppJniAiGenerationProvider.FLASH_ATTN_UNSUPPORTED_MESSAGE);
-        }
-    }
-
     /**
      * Checks the configuration against what the GGUF file itself declares, still without loading it.
      *
diff --git a/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniAiGenerationProvider.java b/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniAiGenerationProvider.java
index 4b8479e4..fc951b7a 100644
--- a/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniAiGenerationProvider.java
+++ b/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniAiGenerationProvider.java
@@ -12,6 +12,7 @@
 import lombok.ToString;
 import net.ladenthin.llama.LlamaModel;
 import net.ladenthin.llama.args.CacheType;
+import net.ladenthin.llama.args.FlashAttn;
 import net.ladenthin.llama.args.ReasoningFormat;
 import net.ladenthin.llama.args.TensorReadLazyMode;
 import net.ladenthin.llama.json.ChatResponseParser;
@@ -46,28 +47,6 @@ public final class LlamaCppJniAiGenerationProvider implements AiGenerationProvid
     /** OpenAI finish reason meaning "the token budget ran out", as opposed to {@code "stop"}. */
     private static final String FINISH_REASON_LENGTH = "length";
 
-    /**
-     * Why {@code flashAttn} is refused outright rather than forwarded.
-     *
-     * <p>Upstream's {@code -fa} takes a mandatory {@code [on|off|auto]} value, but the binding models it
-     * as a bare flag: {@code ModelParameters.enableFlashAttn()} calls {@code setFlag}, which stores a
-     * {@code null} value, and the argv renderer emits the key with no token after it. llama.cpp's parser
-     * then consumes the <em>next</em> argv token as the value, so the model load dies naming an entirely
-     * unrelated flag — verified against the shipped fat jar: {@code error: unknown value for
-     * --flash-attn: '--reasoning-format'}. There is no partial or degraded mode; nothing loads.</p>
-     *
-     * <p>srcmorph cannot spell it correctly through the binding's public API — {@code setFlag}
-     * unconditionally stores {@code null} and {@code putScalar} is {@code protected} — so until the
-     * binding ships a value-taking setter, refusing the knob with a message that names the cause is
-     * strictly better than letting the user hit a parse error about a flag they never set.</p>
-     */
-    public static final String FLASH_ATTN_UNSUPPORTED_MESSAGE =
-            "flashAttn cannot be enabled with net.ladenthin:llama 5.1.0:"
-                    + " the binding emits '--flash-attn' without the [on|off|auto] value llama.cpp requires, so the"
-                    + " model load fails with a parse error naming an unrelated flag. Remove flashAttn from the"
-                    + " model definition (and any cacheTypeV that depends on it) until a binding release exposes a"
-                    + " value-taking setter.";
-
     private final LlamaCppJniConfig config;
 
     // Native llama.cpp model handle — its toString prints native pointer / internal
@@ -168,21 +147,13 @@ private LlamaModel model() {
             if (!compatibilityHelper.isBlank(config.tensorReadLazy())) {
                 modelParameters.setTensorReadLazy(tensorReadLazyMode(config.tensorReadLazy()));
             }
-            // TODO: after net.ladenthin:llama 5.2.0 ships the value-taking Flash Attention setter,
-            // replace this refusal with the real wiring -- modelParameters.setFlashAttn(<on>) -- and
-            // delete FLASH_ATTN_UNSUPPORTED_MESSAGE, EngineSupport.validateFlashAttnIsNotRequested,
-            // and the three tests that pin the refusal (two in EngineSupportTest, one here). Bumping
-            // llama.version alone will NOT surface this: the guard keeps throwing and the knob keeps
-            // looking broken, so the bump checklist has to name it. See TODO.md.
+            // Flash Attention. Emitted only when asked for: llama.cpp's own default is `auto`, so
+            // NOT emitting the option leaves it to decide per backend and model, which is what an
+            // unconfigured run should get. `--flash-attn` takes a mandatory on|off|auto value, which
+            // is why this goes through the enum setter -- the bare-flag setter emits the key alone
+            // and llama.cpp then swallows the following argv token.
             if (config.flashAttn()) {
-                // The model path is not decoration: this guard fires on the direct-API path, where
-                // there is no aiDefinition key to name (the plan-time guard in EngineSupport prefixes
-                // that one), so without it a caller running several models is told what is wrong but
-                // not which configuration to change. It also keeps the message out of
-                // WEM_WEAK_EXCEPTION_MESSAGING, which SpotBugs raises on a throw whose whole message
-                // is a compile-time constant.
-                throw new IllegalArgumentException(
-                        "model '" + config.modelPath() + "': " + FLASH_ATTN_UNSUPPORTED_MESSAGE);
+                modelParameters.setFlashAttn(FlashAttn.ON);
             }
             // KV-cache quantization. Set independently of each other, but note that a quantized V cache
             // generally needs Flash Attention above -- llama.cpp refuses the combination otherwise.
diff --git a/srcmorph/src/test/java/net/ladenthin/srcmorph/engine/EngineSupportTest.java b/srcmorph/src/test/java/net/ladenthin/srcmorph/engine/EngineSupportTest.java
index a88a488a..d9278a41 100644
--- a/srcmorph/src/test/java/net/ladenthin/srcmorph/engine/EngineSupportTest.java
+++ b/srcmorph/src/test/java/net/ladenthin/srcmorph/engine/EngineSupportTest.java
@@ -268,57 +268,6 @@ private static void writeMinimalGguf(final Path file) throws IOException {
         Files.write(file, header.array());
     }
 
-    /**
-     * Builds a lookup whose one definition has both a model path and {@code flashAttn} enabled.
-     *
-     * @param modelPath the definition's model path
-     * @return the lookup
-     */
-    private static AiModelDefinitionSupport supportWithFlashAttn(final String modelPath) {
-        final AiModelDefinition definition = new AiModelDefinition();
-        definition.setKey("routed");
-        definition.setModelPath(modelPath);
-        definition.setFlashAttn(true);
-        return new AiModelDefinitionSupport(Arrays.asList(definition));
-    }
-
-    /**
-     * {@code flashAttn} is documented and settable but cannot work with the pinned binding: it emits
-     * {@code --flash-attn} with no value, llama.cpp swallows the following argv token, and the load dies
-     * naming a flag the user never set. Refusing at plan time means a multi-model run fails before its
-     * first group generates rather than after &mdash; and the message names the real cause instead of
-     * leaving the user with {@code unknown value for --flash-attn: '--reasoning-format'}.
-     */
-    @Test
-    public void validateRoutedModelPaths_flashAttnEnabled_throwsNamingTheCauseBeforeAnyModelLoads() throws IOException {
-        // arrange -- a perfectly valid model, so only flashAttn can be what fails
-        final Path model = modelDir.resolve("real.gguf");
-        writeMinimalGguf(model);
-
-        // act
-        final SrcMorphException thrown = assertThrows(
-                SrcMorphException.class,
-                () -> EngineSupport.validateRoutedModelPaths(
-                        AiGenerationProviderFactory.PROVIDER_LLAMACPP_JNI,
-                        supportWithFlashAttn(model.toString()),
-                        Arrays.asList(routedRule(false, "routed"))));
-
-        // assert
-        assertThat(thrown.getMessage(), containsString("routed"));
-        assertThat(thrown.getMessage(), containsString("flashAttn"));
-        assertThat(thrown.getMessage(), containsString("--flash-attn"));
-    }
-
-    /** The mock provider never touches the binding, so its runs must not be refused. */
-    @Test
-    public void validateRoutedModelPaths_flashAttnEnabledButMockProvider_passes() throws SrcMorphException {
-        // act / assert -- no exception; the guard is scoped to the llamacpp-jni provider
-        EngineSupport.validateRoutedModelPaths(
-                AiGenerationProviderFactory.PROVIDER_MOCK,
-                supportWithFlashAttn("/does/not/exist.gguf"),
-                Arrays.asList(routedRule(false, "routed")));
-    }
-
     @Test
     public void validateRoutedModelPaths_realGgufFile_passes() throws IOException, SrcMorphException {
         // arrange
diff --git a/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniKnobSweepTest.java b/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniKnobSweepTest.java
index 96f34c8e..a769732c 100644
--- a/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniKnobSweepTest.java
+++ b/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniKnobSweepTest.java
@@ -3,7 +3,6 @@
 // SPDX-License-Identifier: Apache-2.0
 package net.ladenthin.srcmorph.provider;
 
-import static org.hamcrest.CoreMatchers.containsString;
 import static org.hamcrest.CoreMatchers.is;
 import static org.hamcrest.CoreMatchers.notNullValue;
 import static org.hamcrest.MatcherAssert.assertThat;
@@ -28,7 +27,6 @@
 import net.ladenthin.srcmorph.document.AiMdHeader;
 import net.ladenthin.srcmorph.document.AiMdHeaderCodec;
 import net.ladenthin.srcmorph.prompt.AiPromptSupport;
-import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.Arguments;
@@ -42,7 +40,9 @@
  * exercised by the native binding <em>accepting</em> the value the provider derives from it. Those
  * two came apart twice: {@code dryPenaltyLastN} was forwarded at its own {@code -1} default and the
  * binding rejects any negative window, so every generation threw before producing a token; and
- * {@code flashAttn} maps onto a setter that cannot express the value llama.cpp now demands. Neither
+ * {@code flashAttn} was mapped onto a bare-flag setter that could not express the mandatory
+ * {@code on|off|auto} value llama.cpp requires, so it emitted an argv that made the parser eat the
+ * following token (fixed by {@code ModelParameters.setFlashAttn}). Neither
  * is visible to a mapping unit test — the mapping was doing exactly what it was written to do — and
  * neither is visible to the rest of the suite, which runs on the {@code mock} provider and never
  * loads the native library. Only a real call finds them.</p>
@@ -97,10 +97,6 @@ private static Map<String, String> notSwept() {
                 "devices",
                 "backend device names (e.g. \"Vulkan1\") exist only on the machine that enumerates them, "
                         + "so no value is valid on an arbitrary runner");
-        reasons.put(
-                "flashAttn",
-                "cannot currently reach the binding at all -- the provider refuses it, which "
-                        + "flashAttn_isRefusedRatherThanSilentlyDropped() pins instead");
         return Collections.unmodifiableMap(reasons);
     }
 
@@ -123,6 +119,11 @@ static Stream<Arguments> knobs() {
                 knob("chatTemplateEnableThinking", b -> b.chatTemplateEnableThinking(false)),
                 knob("cachePrompt", b -> b.cachePrompt(false)),
                 knob("swaFull", b -> b.swaFull(false)),
+                // The knob this whole class was written for: it was unreachable until
+                // net.ladenthin:llama grew a value-taking setter, and until then the provider
+                // refused it outright. This case is the first time it is actually set against a
+                // real model rather than merely pinned as refused.
+                knob("flashAttn", b -> b.flashAttn(true)),
                 knob("cacheReuse", b -> b.cacheReuse(128)),
                 knob("gpuLayers", b -> b.gpuLayers(0)),
                 knob("seed", b -> b.seed(42)),
@@ -200,33 +201,6 @@ public void knob_atNonDefaultValue_stillProducesOutput(
                 "knob " + knobName + " produced an empty response", body.trim().isEmpty(), is(false));
     }
 
-    /**
-     * The one knob the provider refuses outright, pinned here so the sweep's coverage stays honest.
-     *
-     * <p>{@code ModelParameters.enableFlashAttn()} is a bare flag, while llama.cpp's
-     * {@code --flash-attn} has taken a mandatory {@code on|off|auto} value since b10273 — a valueless
-     * emission swallows the following argument. Refusing is the only correct behaviour until the
-     * binding grows a value-taking setter; see the TODO on {@code LlamaCppJniAiGenerationProvider} and
-     * {@code TODO.md}. When that lands, this test flips into a sweep case above.</p>
-     */
-    @Test
-    public void flashAttn_isRefusedRatherThanSilentlyDropped() {
-        NativeLlamaAvailability.assumeAvailable();
-        final LlamaCppJniConfig config = baseline().flashAttn(true).build();
-        final AiPromptSupport promptSupport = new AiPromptSupport(CommonTestFixtures.createFilePromptDefinitions());
-
-        try (LlamaCppJniAiGenerationProvider provider = new LlamaCppJniAiGenerationProvider(config, promptSupport)) {
-            final IllegalArgumentException thrown =
-                    Assertions.assertThrows(IllegalArgumentException.class, () -> provider.generate(request()));
-            // containsString, not equality: the provider prefixes the model it is refusing for, so a
-            // caller running several models can tell which configuration to change.
-            assertThat(
-                    thrown.getMessage(),
-                    containsString(LlamaCppJniAiGenerationProvider.FLASH_ATTN_UNSUPPORTED_MESSAGE));
-            assertThat(thrown.getMessage(), containsString(NativeLlamaAvailability.modelPath()));
-        }
-    }
-
     /**
      * Fails when a knob exists that is neither swept nor listed in {@link #NOT_SWEPT}.
      *

From fcb5a3988a0ef982d2d763e1863ae6f3b0fed0db Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 1 Sep 2026 08:41:34 +0000
Subject: [PATCH 2/3] feat!: follow the binding's lazyMode rename

BREAKING CHANGE: the tensorReadLazy model-definition field and its accessors
are renamed to lazyMode.

llama.cpp b10731 renamed --tensor-read-lazy to -lzm / --lazy-mode with no
alias, and net.ladenthin:llama followed the rename instead of papering over
it. Keeping tensorReadLazy here would leave the configuration surface naming a
flag that no longer exists, so the field, its getters, the LlamaCppJniConfig
accessor and builder, the factory mapping, module-info, the plugin README row
and the sweep case all move.

The mismatch this guards against is not cosmetic, and it showed up while doing
the work: a new Java name paired with an old native fails at load time with
"Failed to parse model parameters" and nothing earlier sees it. The knob sweep
caught exactly that -- case [20] went red against a jar carrying the previous
native, and green once the jar carried one built from the pinned tag. That is
the second defect the sweep has found since it was written.

Core module: 637 tests, 0 failures, 0 skipped, run against a libjllama.so
built from b10731 with all eight patches applied.
---
 CHANGELOG.md                                  | 10 ++++++++++
 TODO.md                                       |  2 +-
 srcmorph-maven-plugin/README.md               |  2 +-
 srcmorph/src/main/java/module-info.java       |  2 +-
 .../srcmorph/config/AiGenerationConfig.java   | 14 ++++++-------
 .../srcmorph/config/AiModelDefinition.java    | 12 +++++------
 .../config/AiModelDefinitionSupport.java      |  2 +-
 .../LlamaCppJniAiGenerationProvider.java      | 20 +++++++++----------
 .../srcmorph/provider/LlamaCppJniConfig.java  | 16 +++++++--------
 .../provider/LlamaCppJniConfigFactory.java    |  2 +-
 .../config/AiGenerationConfigTest.java        | 16 +++++++--------
 .../config/AiModelDefinitionSupportTest.java  |  6 +++---
 .../config/AiModelDefinitionTest.java         | 16 +++++++--------
 .../LlamaCppJniAiGenerationProviderTest.java  | 18 ++++++++---------
 .../LlamaCppJniConfigFactoryTest.java         |  6 +++---
 .../provider/LlamaCppJniConfigTest.java       | 12 +++++------
 .../provider/LlamaCppJniKnobSweepTest.java    |  2 +-
 17 files changed, 84 insertions(+), 74 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f17dee98..40d5dbe8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,6 +33,16 @@ The release procedure (prompt template and step-by-step instructions) lives in [
   them.
 
 ### Changed
+- **`lazyMode` replaces `tensorReadLazy` — breaking.** llama.cpp b10731 renamed `--tensor-read-lazy`
+  to `-lzm` / `--lazy-mode` with no alias, and `net.ladenthin:llama` followed the rename rather than
+  papering over it, so the model-definition field, its `srcmorph.llama.*` surface, the
+  `LlamaCppJniConfig` accessor and the sweep case move with it. Carrying the old name would leave the
+  configuration describing a flag that no longer exists.
+
+  Worth knowing why this is a real hazard and not cosmetics: a **new Java name paired with an old
+  native** produces `Failed to parse model parameters` at load time and nothing earlier catches it.
+  The knob sweep did — it is what surfaced the mismatch here.
+
 - **`net.ladenthin:llama` 5.1.0 → 5.2.0-SNAPSHOT.** Deliberately a snapshot: the binding change this
   release depends on is not yet published. Building srcmorph therefore requires that snapshot to be
   resolvable, and CI stays red until it is — recorded here so nobody mistakes it for a regression.
diff --git a/TODO.md b/TODO.md
index a89c3d11..347d20f3 100644
--- a/TODO.md
+++ b/TODO.md
@@ -47,7 +47,7 @@ recorded in git history and `crossrepostatus.md`, not here.
   its fix: the class generates no mutants, so neither the bug nor the tests that now cover it move
   the number. Do not read that stability as reassurance; PIT structurally could not have caught this.
   It is now worth adding, because the class finally has model-free coverage of the parts that matter
-  (`buildInferenceParameters`, `warnOnTruncatedAnswer`, `logPromptCacheReuse`, `tensorReadLazyMode`,
+  (`buildInferenceParameters`, `warnOnTruncatedAnswer`, `logPromptCacheReuse`, `lazyMode`,
   `cacheType`). **Measure before committing to it**: the real-model tests take ~4-16 s each, and PIT
   re-runs every test covering a mutated line, so mutants in `model()` — the long `ModelParameters`
   chain — could make the run far slower than the current few minutes. If it does, the answer is
diff --git a/srcmorph-maven-plugin/README.md b/srcmorph-maven-plugin/README.md
index 8b2e6daf..6a17cee2 100644
--- a/srcmorph-maven-plugin/README.md
+++ b/srcmorph-maven-plugin/README.md
@@ -439,7 +439,7 @@ below are the shipped values (`AiGenerationConfig.DEFAULT_*`).
 | `batchSize` | `-1` | Logical maximum batch size (`--batch-size`); `-1` = leave default. A prefill-throughput knob, and prefill is what dominates an indexing run: every file is one large prompt with a short answer. Must be positive when set |
 | `ubatchSize` | `-1` | Physical maximum batch size (`--ubatch-size`); `-1` = leave default. Bounds how much of a logical batch reaches the backend at once, so it trades prefill speed against peak memory. Must be positive when set |
 | `threadsBatch` | `-1` | Threads for batch/prompt processing (`--threads-batch`); `-1` = reuse `threads`. Prefill parallelises differently from decode, so the optimum often is not the decode thread count — on a machine with efficiency cores, more threads help prompt processing while hurting generation. Must be positive when set |
-| `tensorReadLazy` | *(empty)* | On-demand reading of lazy-loadable tensors (`--tensor-read-lazy`): `off`, `auto` or `on`; empty leaves the default. Trades resident memory for disk reads and shortens model load time; **requires mmap** |
+| `lazyMode` | *(empty)* | On-demand reading of lazy-loadable tensors (`--tensor-read-lazy`): `off`, `auto` or `on`; empty leaves the default. Trades resident memory for disk reads and shortens model load time; **requires mmap** |
 | `mainGpu` | `-1` | Primary GPU index (`--main-gpu`); `-1` = leave default. Matters on multi-GPU hosts (e.g. a Vulkan build enumerates every GPU) |
 | `devices` | *(empty)* | Explicit device selection (`--device`), comma-separated backend device names (e.g. `Vulkan1`); takes precedence over `mainGpu` |
 | `chatTemplateEnableThinking` | `true` | Enable the chat template's thinking mode |
diff --git a/srcmorph/src/main/java/module-info.java b/srcmorph/src/main/java/module-info.java
index 23a9bf20..93ebbb64 100644
--- a/srcmorph/src/main/java/module-info.java
+++ b/srcmorph/src/main/java/module-info.java
@@ -37,7 +37,7 @@
  * file</em>, and irrelevant to <em>running the result</em>. On the module path every llama.cpp-backed
  * path, including the plan-time {@code GgufModelInspector}, failed for want of a readable module.
  * It is deliberately <b>not</b> {@code transitive}: the binding's types appear only in
- * package-private members ({@code tensorReadLazyMode}, {@code cacheType},
+ * package-private members ({@code lazyMode}, {@code cacheType},
  * {@code buildInferenceParameters}), never in an exported signature — {@code LlamaCppJniConfigFactory}
  * returns srcmorph's own {@code LlamaCppJniConfig} — so no consumer needs the module transitively.
  * Should a llama type ever surface in an exported signature, this must become
diff --git a/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiGenerationConfig.java b/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiGenerationConfig.java
index 90c78efb..81cd0cc0 100644
--- a/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiGenerationConfig.java
+++ b/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiGenerationConfig.java
@@ -243,7 +243,7 @@ public AiGenerationConfig() {
      * <p>Deferring tensor reads can shorten model load time, which matters here because a run loads
      * and unloads one model per model group and {@code calibrate} preflights every model in turn.</p>
      */
-    public static final String DEFAULT_TENSOR_READ_LAZY = "";
+    public static final String DEFAULT_LAZY_MODE = "";
 
     /**
      * Default repeat-penalty window ({@code --repeat-last-n}). {@code -1} (default) means "do not set
@@ -396,7 +396,7 @@ public AiGenerationConfig() {
     private int cpuMoeLayers = DEFAULT_CPU_MOE_LAYERS;
     private int cpuFfnLayers = DEFAULT_CPU_FFN_LAYERS;
     private int kvUnifiedPerSlot = DEFAULT_KV_UNIFIED_PER_SLOT;
-    private String tensorReadLazy = DEFAULT_TENSOR_READ_LAZY;
+    private String lazyMode = DEFAULT_LAZY_MODE;
     private int repeatLastN = DEFAULT_REPEAT_LAST_N;
     private String cacheTypeK = DEFAULT_CACHE_TYPE_K;
     private String cacheTypeV = DEFAULT_CACHE_TYPE_V;
@@ -812,17 +812,17 @@ public void setKvUnifiedPerSlot(final int kvUnifiedPerSlot) {
      *
      * @return {@code off}, {@code auto}, {@code on}, or empty to leave the default
      */
-    public String getTensorReadLazy() {
-        return tensorReadLazy;
+    public String getLazyMode() {
+        return lazyMode;
     }
 
     /**
      * Sets the tensor-read laziness ({@code --tensor-read-lazy}).
      *
-     * @param tensorReadLazy {@code off}, {@code auto}, {@code on}, or empty/{@code null} to leave the default
+     * @param lazyMode {@code off}, {@code auto}, {@code on}, or empty/{@code null} to leave the default
      */
-    public void setTensorReadLazy(final @Nullable String tensorReadLazy) {
-        this.tensorReadLazy = tensorReadLazy != null ? tensorReadLazy : DEFAULT_TENSOR_READ_LAZY;
+    public void setLazyMode(final @Nullable String lazyMode) {
+        this.lazyMode = lazyMode != null ? lazyMode : DEFAULT_LAZY_MODE;
     }
 
     /**
diff --git a/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiModelDefinition.java b/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiModelDefinition.java
index 17cd7bb9..3209963a 100644
--- a/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiModelDefinition.java
+++ b/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiModelDefinition.java
@@ -60,7 +60,7 @@ public AiModelDefinition() {
     private int cpuMoeLayers = AiGenerationConfig.DEFAULT_CPU_MOE_LAYERS;
     private int cpuFfnLayers = AiGenerationConfig.DEFAULT_CPU_FFN_LAYERS;
     private int kvUnifiedPerSlot = AiGenerationConfig.DEFAULT_KV_UNIFIED_PER_SLOT;
-    private String tensorReadLazy = AiGenerationConfig.DEFAULT_TENSOR_READ_LAZY;
+    private String lazyMode = AiGenerationConfig.DEFAULT_LAZY_MODE;
     private int repeatLastN = AiGenerationConfig.DEFAULT_REPEAT_LAST_N;
     private String cacheTypeK = AiGenerationConfig.DEFAULT_CACHE_TYPE_K;
     private String cacheTypeV = AiGenerationConfig.DEFAULT_CACHE_TYPE_V;
@@ -496,17 +496,17 @@ public void setKvUnifiedPerSlot(final int kvUnifiedPerSlot) {
      *
      * @return {@code off}, {@code auto}, {@code on}, or empty to leave the default
      */
-    public String getTensorReadLazy() {
-        return tensorReadLazy;
+    public String getLazyMode() {
+        return lazyMode;
     }
 
     /**
      * Sets the tensor-read laziness ({@code --tensor-read-lazy}) for this model.
      *
-     * @param tensorReadLazy {@code off}, {@code auto}, {@code on}, or empty/{@code null} to leave the default
+     * @param lazyMode {@code off}, {@code auto}, {@code on}, or empty/{@code null} to leave the default
      */
-    public void setTensorReadLazy(final @Nullable String tensorReadLazy) {
-        this.tensorReadLazy = tensorReadLazy != null ? tensorReadLazy : AiGenerationConfig.DEFAULT_TENSOR_READ_LAZY;
+    public void setLazyMode(final @Nullable String lazyMode) {
+        this.lazyMode = lazyMode != null ? lazyMode : AiGenerationConfig.DEFAULT_LAZY_MODE;
     }
 
     /**
diff --git a/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiModelDefinitionSupport.java b/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiModelDefinitionSupport.java
index 3f63cb03..629aeaf0 100644
--- a/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiModelDefinitionSupport.java
+++ b/srcmorph/src/main/java/net/ladenthin/srcmorph/config/AiModelDefinitionSupport.java
@@ -127,7 +127,7 @@ private static AiGenerationConfig toConfig(final AiModelDefinition definition) {
         config.setCpuMoeLayers(definition.getCpuMoeLayers());
         config.setCpuFfnLayers(definition.getCpuFfnLayers());
         config.setKvUnifiedPerSlot(definition.getKvUnifiedPerSlot());
-        config.setTensorReadLazy(definition.getTensorReadLazy());
+        config.setLazyMode(definition.getLazyMode());
         config.setRepeatLastN(definition.getRepeatLastN());
         config.setCacheTypeK(definition.getCacheTypeK());
         config.setCacheTypeV(definition.getCacheTypeV());
diff --git a/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniAiGenerationProvider.java b/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniAiGenerationProvider.java
index fc951b7a..a85fec04 100644
--- a/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniAiGenerationProvider.java
+++ b/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniAiGenerationProvider.java
@@ -13,8 +13,8 @@
 import net.ladenthin.llama.LlamaModel;
 import net.ladenthin.llama.args.CacheType;
 import net.ladenthin.llama.args.FlashAttn;
+import net.ladenthin.llama.args.LazyMode;
 import net.ladenthin.llama.args.ReasoningFormat;
-import net.ladenthin.llama.args.TensorReadLazyMode;
 import net.ladenthin.llama.json.ChatResponseParser;
 import net.ladenthin.llama.parameters.InferenceParameters;
 import net.ladenthin.llama.parameters.ModelParameters;
@@ -144,8 +144,8 @@ private LlamaModel model() {
             // Read lazy-loadable tensors on demand instead of keeping them resident. Shortens model
             // load time, which matters here because a run loads one model per model group and
             // calibrate preflights every model in turn. Empty leaves the binding/native-build default.
-            if (!compatibilityHelper.isBlank(config.tensorReadLazy())) {
-                modelParameters.setTensorReadLazy(tensorReadLazyMode(config.tensorReadLazy()));
+            if (!compatibilityHelper.isBlank(config.lazyMode())) {
+                modelParameters.setLazyMode(lazyMode(config.lazyMode()));
             }
             // Flash Attention. Emitted only when asked for: llama.cpp's own default is `auto`, so
             // NOT emitting the option leaves it to decide per backend and model, which is what an
@@ -206,20 +206,20 @@ private LlamaModel model() {
      * @return the matching mode
      * @throws IllegalArgumentException if no mode declares that CLI string
      */
-    static TensorReadLazyMode tensorReadLazyMode(final String value) {
-        for (final TensorReadLazyMode mode : TensorReadLazyMode.values()) {
+    static LazyMode lazyMode(final String value) {
+        for (final LazyMode mode : LazyMode.values()) {
             if (mode.getArgValue().equalsIgnoreCase(value)) {
                 return mode;
             }
         }
-        throw new IllegalArgumentException("Invalid tensorReadLazy value: \"" + value + "\" (expected one of: "
-                + knownTensorReadLazyValues() + ")");
+        throw new IllegalArgumentException(
+                "Invalid lazyMode value: \"" + value + "\" (expected one of: " + knownLazyModeValues() + ")");
     }
 
     /**
      * Resolves a configured {@code --cache-type-k} / {@code --cache-type-v} value to the binding's enum.
      *
-     * <p>Same contract as {@link #tensorReadLazyMode(String)}: matched case-insensitively against the CLI
+     * <p>Same contract as {@link #lazyMode(String)}: matched case-insensitively against the CLI
      * strings the enum itself declares, so a cache type upstream adds is accepted for free, and an
      * unrecognised value is rejected rather than dropped. The knob name is passed in so the message names
      * the element the user actually wrote.</p>
@@ -260,9 +260,9 @@ private static String knownCacheTypeValues() {
      *
      * @return the CLI strings the binding's enum declares, comma-separated in declaration order
      */
-    private static String knownTensorReadLazyValues() {
+    private static String knownLazyModeValues() {
         final StringBuilder known = new StringBuilder();
-        for (final TensorReadLazyMode mode : TensorReadLazyMode.values()) {
+        for (final LazyMode mode : LazyMode.values()) {
             if (known.length() > 0) {
                 known.append(", ");
             }
diff --git a/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfig.java b/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfig.java
index 154c3758..d7732a78 100644
--- a/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfig.java
+++ b/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfig.java
@@ -46,7 +46,7 @@ public final class LlamaCppJniConfig {
     private final int cpuMoeLayers;
     private final int cpuFfnLayers;
     private final int kvUnifiedPerSlot;
-    private final String tensorReadLazy;
+    private final String lazyMode;
     private final int repeatLastN;
     private final String cacheTypeK;
     private final String cacheTypeV;
@@ -98,7 +98,7 @@ private LlamaCppJniConfig(final Builder builder) {
         this.cpuMoeLayers = builder.cpuMoeLayers;
         this.cpuFfnLayers = builder.cpuFfnLayers;
         this.kvUnifiedPerSlot = builder.kvUnifiedPerSlot;
-        this.tensorReadLazy = builder.tensorReadLazy;
+        this.lazyMode = builder.lazyMode;
         this.repeatLastN = builder.repeatLastN;
         this.cacheTypeK = builder.cacheTypeK;
         this.cacheTypeV = builder.cacheTypeV;
@@ -309,8 +309,8 @@ public int kvUnifiedPerSlot() {
      *
      * @return {@code off}, {@code auto}, {@code on}, or empty to leave the binding/build default
      */
-    public String tensorReadLazy() {
-        return tensorReadLazy;
+    public String lazyMode() {
+        return lazyMode;
     }
 
     /**
@@ -498,7 +498,7 @@ public static final class Builder {
         private int cpuMoeLayers = AiGenerationConfig.DEFAULT_CPU_MOE_LAYERS;
         private int cpuFfnLayers = AiGenerationConfig.DEFAULT_CPU_FFN_LAYERS;
         private int kvUnifiedPerSlot = AiGenerationConfig.DEFAULT_KV_UNIFIED_PER_SLOT;
-        private String tensorReadLazy = AiGenerationConfig.DEFAULT_TENSOR_READ_LAZY;
+        private String lazyMode = AiGenerationConfig.DEFAULT_LAZY_MODE;
         private int repeatLastN = AiGenerationConfig.DEFAULT_REPEAT_LAST_N;
         private String cacheTypeK = AiGenerationConfig.DEFAULT_CACHE_TYPE_K;
         private String cacheTypeV = AiGenerationConfig.DEFAULT_CACHE_TYPE_V;
@@ -722,11 +722,11 @@ public Builder kvUnifiedPerSlot(final int kvUnifiedPerSlot) {
         /**
          * Sets tensor-read laziness ({@code --tensor-read-lazy}); empty = leave default. {@code null} restores the default.
          *
-         * @param tensorReadLazy tensor-read laziness ({@code --tensor-read-lazy}); empty = leave default
+         * @param lazyMode tensor-read laziness ({@code --tensor-read-lazy}); empty = leave default
          * @return this builder
          */
-        public Builder tensorReadLazy(final String tensorReadLazy) {
-            this.tensorReadLazy = tensorReadLazy != null ? tensorReadLazy : AiGenerationConfig.DEFAULT_TENSOR_READ_LAZY;
+        public Builder lazyMode(final String lazyMode) {
+            this.lazyMode = lazyMode != null ? lazyMode : AiGenerationConfig.DEFAULT_LAZY_MODE;
             return this;
         }
 
diff --git a/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfigFactory.java b/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfigFactory.java
index 53e166f0..8ea9d496 100644
--- a/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfigFactory.java
+++ b/srcmorph/src/main/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfigFactory.java
@@ -52,7 +52,7 @@ public static LlamaCppJniConfig fromGenerationConfig(final AiGenerationConfig co
                 .cpuMoeLayers(config.getCpuMoeLayers())
                 .cpuFfnLayers(config.getCpuFfnLayers())
                 .kvUnifiedPerSlot(config.getKvUnifiedPerSlot())
-                .tensorReadLazy(config.getTensorReadLazy())
+                .lazyMode(config.getLazyMode())
                 .repeatLastN(config.getRepeatLastN())
                 .cacheTypeK(config.getCacheTypeK())
                 .cacheTypeV(config.getCacheTypeV())
diff --git a/srcmorph/src/test/java/net/ladenthin/srcmorph/config/AiGenerationConfigTest.java b/srcmorph/src/test/java/net/ladenthin/srcmorph/config/AiGenerationConfigTest.java
index 9ff2bcbf..4d6fc3d3 100644
--- a/srcmorph/src/test/java/net/ladenthin/srcmorph/config/AiGenerationConfigTest.java
+++ b/srcmorph/src/test/java/net/ladenthin/srcmorph/config/AiGenerationConfigTest.java
@@ -171,22 +171,22 @@ public void kvUnifiedPerSlotDefaultsMinusOneAndRoundTrips() {
     }
 
     @Test
-    public void tensorReadLazyDefaultsEmptyAndRoundTrips() {
+    public void lazyModeDefaultsEmptyAndRoundTrips() {
         AiGenerationConfig c = new AiGenerationConfig();
         // Default "" (leave binding/build default) kills the null/non-empty return mutants on the getter.
-        assertThat(c.getTensorReadLazy(), is(""));
-        c.setTensorReadLazy("on");
+        assertThat(c.getLazyMode(), is(""));
+        c.setLazyMode("on");
         // Round-tripped value kills the empty-return getter and removed-assignment setter mutants.
-        assertThat(c.getTensorReadLazy(), is("on"));
+        assertThat(c.getLazyMode(), is("on"));
     }
 
     @Test
-    public void setTensorReadLazyNullResetsToEmpty() {
+    public void setLazyModeNullResetsToEmpty() {
         AiGenerationConfig c = new AiGenerationConfig();
-        c.setTensorReadLazy("auto");
-        c.setTensorReadLazy(null);
+        c.setLazyMode("auto");
+        c.setLazyMode(null);
         // null arg resets to "" — kills the negate mutant on the setter ternary (which would store null).
-        assertThat(c.getTensorReadLazy(), is(""));
+        assertThat(c.getLazyMode(), is(""));
     }
 
     @Test
diff --git a/srcmorph/src/test/java/net/ladenthin/srcmorph/config/AiModelDefinitionSupportTest.java b/srcmorph/src/test/java/net/ladenthin/srcmorph/config/AiModelDefinitionSupportTest.java
index 3d8fa24e..22099a7c 100644
--- a/srcmorph/src/test/java/net/ladenthin/srcmorph/config/AiModelDefinitionSupportTest.java
+++ b/srcmorph/src/test/java/net/ladenthin/srcmorph/config/AiModelDefinitionSupportTest.java
@@ -57,7 +57,7 @@ public void getConfig_knownKey_propagatesAllFields() {
         definition.setCpuMoeLayers(24);
         definition.setCpuFfnLayers(16);
         definition.setKvUnifiedPerSlot(4096);
-        definition.setTensorReadLazy("on");
+        definition.setLazyMode("on");
         definition.setRepeatLastN(128);
         definition.setCacheTypeK("q8_0");
         definition.setCacheTypeV("q4_0");
@@ -123,7 +123,7 @@ public void getConfig_knownKey_propagatesAllFields() {
         assertThat(config.getCpuMoeLayers(), is(equalTo(24)));
         assertThat(config.getCpuFfnLayers(), is(equalTo(16)));
         assertThat(config.getKvUnifiedPerSlot(), is(equalTo(4096)));
-        assertThat(config.getTensorReadLazy(), is(equalTo("on")));
+        assertThat(config.getLazyMode(), is(equalTo("on")));
         assertThat(config.getRepeatLastN(), is(equalTo(128)));
         assertThat(config.getCacheTypeK(), is(equalTo("q8_0")));
         assertThat(config.getCacheTypeV(), is(equalTo("q4_0")));
@@ -173,7 +173,7 @@ public void getConfig_defaultValues_matchAiGenerationConfigDefaults() {
         assertThat(config.getCpuMoeLayers(), is(equalTo(AiGenerationConfig.DEFAULT_CPU_MOE_LAYERS)));
         assertThat(config.getCpuFfnLayers(), is(equalTo(AiGenerationConfig.DEFAULT_CPU_FFN_LAYERS)));
         assertThat(config.getKvUnifiedPerSlot(), is(equalTo(AiGenerationConfig.DEFAULT_KV_UNIFIED_PER_SLOT)));
-        assertThat(config.getTensorReadLazy(), is(equalTo(AiGenerationConfig.DEFAULT_TENSOR_READ_LAZY)));
+        assertThat(config.getLazyMode(), is(equalTo(AiGenerationConfig.DEFAULT_LAZY_MODE)));
         assertThat(config.getRepeatLastN(), is(equalTo(AiGenerationConfig.DEFAULT_REPEAT_LAST_N)));
         assertThat(config.getCacheTypeK(), is(equalTo(AiGenerationConfig.DEFAULT_CACHE_TYPE_K)));
         assertThat(config.getCacheTypeV(), is(equalTo(AiGenerationConfig.DEFAULT_CACHE_TYPE_V)));
diff --git a/srcmorph/src/test/java/net/ladenthin/srcmorph/config/AiModelDefinitionTest.java b/srcmorph/src/test/java/net/ladenthin/srcmorph/config/AiModelDefinitionTest.java
index 93893532..da515c09 100644
--- a/srcmorph/src/test/java/net/ladenthin/srcmorph/config/AiModelDefinitionTest.java
+++ b/srcmorph/src/test/java/net/ladenthin/srcmorph/config/AiModelDefinitionTest.java
@@ -174,22 +174,22 @@ public void kvUnifiedPerSlotDefaultsMinusOneAndRoundTrips() {
     }
 
     @Test
-    public void tensorReadLazyDefaultsEmptyAndRoundTrips() {
+    public void lazyModeDefaultsEmptyAndRoundTrips() {
         AiModelDefinition c = new AiModelDefinition();
         // Default "" (leave binding/build default) kills the null/non-empty return mutants on the getter.
-        assertThat(c.getTensorReadLazy(), is(""));
-        c.setTensorReadLazy("on");
+        assertThat(c.getLazyMode(), is(""));
+        c.setLazyMode("on");
         // Round-tripped value kills the empty-return getter and removed-assignment setter mutants.
-        assertThat(c.getTensorReadLazy(), is("on"));
+        assertThat(c.getLazyMode(), is("on"));
     }
 
     @Test
-    public void setTensorReadLazyNullResetsToEmpty() {
+    public void setLazyModeNullResetsToEmpty() {
         AiModelDefinition c = new AiModelDefinition();
-        c.setTensorReadLazy("auto");
-        c.setTensorReadLazy(null);
+        c.setLazyMode("auto");
+        c.setLazyMode(null);
         // null arg resets to "" — kills the negate mutant on the setter ternary (which would store null).
-        assertThat(c.getTensorReadLazy(), is(""));
+        assertThat(c.getLazyMode(), is(""));
     }
 
     @Test
diff --git a/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniAiGenerationProviderTest.java b/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniAiGenerationProviderTest.java
index 1151a9eb..bbf4fa2e 100644
--- a/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniAiGenerationProviderTest.java
+++ b/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniAiGenerationProviderTest.java
@@ -16,7 +16,7 @@
 import java.nio.file.Paths;
 import java.util.Collections;
 import net.ladenthin.llama.args.CacheType;
-import net.ladenthin.llama.args.TensorReadLazyMode;
+import net.ladenthin.llama.args.LazyMode;
 import net.ladenthin.llama.value.ChatChoice;
 import net.ladenthin.llama.value.ChatMessage;
 import net.ladenthin.llama.value.ChatResponse;
@@ -127,24 +127,24 @@ public void generateWithTimings_realProvider_reportsEngineTimingsThatScaleWithPr
     // </editor-fold>
 
     @Test
-    public void tensorReadLazyMode_mapsEveryDeclaredCliString() {
+    public void lazyMode_mapsEveryDeclaredCliString() {
         // Every mode the binding declares must resolve; a new upstream mode is then covered for free.
-        for (final TensorReadLazyMode mode : TensorReadLazyMode.values()) {
-            assertThat(LlamaCppJniAiGenerationProvider.tensorReadLazyMode(mode.getArgValue()), is(mode));
+        for (final LazyMode mode : LazyMode.values()) {
+            assertThat(LlamaCppJniAiGenerationProvider.lazyMode(mode.getArgValue()), is(mode));
         }
     }
 
     @Test
-    public void tensorReadLazyMode_isCaseInsensitive() {
-        assertThat(LlamaCppJniAiGenerationProvider.tensorReadLazyMode("ON"), is(TensorReadLazyMode.ON));
-        assertThat(LlamaCppJniAiGenerationProvider.tensorReadLazyMode("Auto"), is(TensorReadLazyMode.AUTO));
+    public void lazyMode_isCaseInsensitive() {
+        assertThat(LlamaCppJniAiGenerationProvider.lazyMode("ON"), is(LazyMode.ON));
+        assertThat(LlamaCppJniAiGenerationProvider.lazyMode("Auto"), is(LazyMode.AUTO));
     }
 
     @Test
-    public void tensorReadLazyMode_rejectsUnknownValueAndNamesTheAcceptedOnes() {
+    public void lazyMode_rejectsUnknownValueAndNamesTheAcceptedOnes() {
         // A typo must fail loud rather than be dropped, and the message must name what is accepted.
         final IllegalArgumentException thrown = Assertions.assertThrows(
-                IllegalArgumentException.class, () -> LlamaCppJniAiGenerationProvider.tensorReadLazyMode("lazy"));
+                IllegalArgumentException.class, () -> LlamaCppJniAiGenerationProvider.lazyMode("lazy"));
         assertThat(thrown.getMessage(), containsString("lazy"));
         assertThat(thrown.getMessage(), containsString("off, auto, on"));
     }
diff --git a/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfigFactoryTest.java b/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfigFactoryTest.java
index dbc06e04..ba59cd8e 100644
--- a/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfigFactoryTest.java
+++ b/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfigFactoryTest.java
@@ -39,7 +39,7 @@ private static AiGenerationConfig fullConfig() {
         config.setCpuMoeLayers(24);
         config.setCpuFfnLayers(16);
         config.setKvUnifiedPerSlot(4096);
-        config.setTensorReadLazy("on");
+        config.setLazyMode("on");
         config.setRepeatLastN(128);
         config.setCacheTypeK("q8_0");
         config.setCacheTypeV("q4_0");
@@ -83,7 +83,7 @@ public void fromGenerationConfig_threadsEveryFieldThrough() {
         assertThat(result.cpuMoeLayers(), is(24));
         assertThat(result.cpuFfnLayers(), is(16));
         assertThat(result.kvUnifiedPerSlot(), is(4096));
-        assertThat(result.tensorReadLazy(), is("on"));
+        assertThat(result.lazyMode(), is("on"));
         assertThat(result.repeatLastN(), is(128));
         assertThat(result.cacheTypeK(), is("q8_0"));
         assertThat(result.cacheTypeV(), is("q4_0"));
@@ -152,7 +152,7 @@ public void fromFallbackParameters_appliesEveryAiGenerationConfigDefault() {
         assertThat(result.cpuMoeLayers(), is(AiGenerationConfig.DEFAULT_CPU_MOE_LAYERS));
         assertThat(result.cpuFfnLayers(), is(AiGenerationConfig.DEFAULT_CPU_FFN_LAYERS));
         assertThat(result.kvUnifiedPerSlot(), is(AiGenerationConfig.DEFAULT_KV_UNIFIED_PER_SLOT));
-        assertThat(result.tensorReadLazy(), is(AiGenerationConfig.DEFAULT_TENSOR_READ_LAZY));
+        assertThat(result.lazyMode(), is(AiGenerationConfig.DEFAULT_LAZY_MODE));
         assertThat(result.repeatLastN(), is(AiGenerationConfig.DEFAULT_REPEAT_LAST_N));
         assertThat(result.cacheTypeK(), is(AiGenerationConfig.DEFAULT_CACHE_TYPE_K));
         assertThat(result.cacheTypeV(), is(AiGenerationConfig.DEFAULT_CACHE_TYPE_V));
diff --git a/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfigTest.java b/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfigTest.java
index e947ab74..29db24a0 100644
--- a/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfigTest.java
+++ b/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniConfigTest.java
@@ -130,7 +130,7 @@ public void builder_leavesEveryUnsetValueAtItsAiGenerationConfigDefault() {
         assertThat(config.cpuMoeLayers(), is(AiGenerationConfig.DEFAULT_CPU_MOE_LAYERS));
         assertThat(config.cpuFfnLayers(), is(AiGenerationConfig.DEFAULT_CPU_FFN_LAYERS));
         assertThat(config.kvUnifiedPerSlot(), is(AiGenerationConfig.DEFAULT_KV_UNIFIED_PER_SLOT));
-        assertThat(config.tensorReadLazy(), is(AiGenerationConfig.DEFAULT_TENSOR_READ_LAZY));
+        assertThat(config.lazyMode(), is(AiGenerationConfig.DEFAULT_LAZY_MODE));
         assertThat(config.repeatLastN(), is(AiGenerationConfig.DEFAULT_REPEAT_LAST_N));
         assertThat(config.cacheTypeK(), is(AiGenerationConfig.DEFAULT_CACHE_TYPE_K));
         assertThat(config.cacheTypeV(), is(AiGenerationConfig.DEFAULT_CACHE_TYPE_V));
@@ -178,7 +178,7 @@ public void builder_everySetterWritesItsOwnField() {
                 .cpuMoeLayers(24)
                 .cpuFfnLayers(16)
                 .kvUnifiedPerSlot(4096)
-                .tensorReadLazy("on")
+                .lazyMode("on")
                 .repeatLastN(128)
                 .cacheTypeK("q8_0")
                 .cacheTypeV("q4_0")
@@ -218,7 +218,7 @@ public void builder_everySetterWritesItsOwnField() {
         assertThat(config.cpuMoeLayers(), is(24));
         assertThat(config.cpuFfnLayers(), is(16));
         assertThat(config.kvUnifiedPerSlot(), is(4096));
-        assertThat(config.tensorReadLazy(), is("on"));
+        assertThat(config.lazyMode(), is("on"));
         assertThat(config.repeatLastN(), is(128));
         assertThat(config.cacheTypeK(), is("q8_0"));
         assertThat(config.cacheTypeV(), is("q4_0"));
@@ -248,12 +248,12 @@ public void builder_everySetterWritesItsOwnField() {
     public void builder_nullOnAStringSetter_restoresThatKnobsDefault() {
         // arrange -- set them all first, so the null is genuinely undoing something
         final LlamaCppJniConfig config = LlamaCppJniConfig.builder("model.gguf")
-                .tensorReadLazy("on")
+                .lazyMode("on")
                 .cacheTypeK("q8_0")
                 .cacheTypeV("q4_0")
                 .devices("Vulkan1")
                 .reasoningEffort("high")
-                .tensorReadLazy(null)
+                .lazyMode(null)
                 .cacheTypeK(null)
                 .cacheTypeV(null)
                 .devices(null)
@@ -261,7 +261,7 @@ public void builder_nullOnAStringSetter_restoresThatKnobsDefault() {
                 .build();
 
         // assert
-        assertThat(config.tensorReadLazy(), is(""));
+        assertThat(config.lazyMode(), is(""));
         assertThat(config.cacheTypeK(), is(""));
         assertThat(config.cacheTypeV(), is(""));
         assertThat(config.devices(), is(""));
diff --git a/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniKnobSweepTest.java b/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniKnobSweepTest.java
index a769732c..f1ec6642 100644
--- a/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniKnobSweepTest.java
+++ b/srcmorph/src/test/java/net/ladenthin/srcmorph/provider/LlamaCppJniKnobSweepTest.java
@@ -130,7 +130,7 @@ static Stream<Arguments> knobs() {
                 knob("cpuMoeLayers", b -> b.cpuMoeLayers(0)),
                 knob("cpuFfnLayers", b -> b.cpuFfnLayers(0)),
                 knob("kvUnifiedPerSlot", b -> b.kvUnifiedPerSlot(SWEEP_CONTEXT_SIZE)),
-                knob("tensorReadLazy", b -> b.tensorReadLazy("on")),
+                knob("lazyMode", b -> b.lazyMode("on")),
                 knob("repeatLastN", b -> b.repeatLastN(64)),
                 // A quantized K cache works on its own; a quantized V cache generally needs Flash
                 // Attention, which the provider currently refuses -- so V is swept at an explicit f16.

From 5b4abeb9f3aa251db8a9e6418450a6c8323f682e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 1 Sep 2026 08:54:31 +0000
Subject: [PATCH 3/3] build: pin net.ladenthin:llama to the 5.2.0 release, not
 the snapshot

The provider now calls setFlashAttn(FlashAttn) and setLazyMode(LazyMode), neither
of which exists in 5.1.0, so this module cannot compile against the released
binding any more.

Naming 5.2.0-SNAPSHOT would not help: this repo declares no <repositories>
element (distributionManagement/snapshotRepository is deploy-only), so the
Central snapshot channel is not even resolvable here -- and a -SNAPSHOT
dependency on main would block every srcmorph release, since Central rejects a
release that depends on one.

The build therefore stays red until net.ladenthin:llama:5.2.0 is published, and
goes green with no further edit the moment it is.
---
 srcmorph/pom.xml | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/srcmorph/pom.xml b/srcmorph/pom.xml
index 4a9ae65d..686a400c 100644
--- a/srcmorph/pom.xml
+++ b/srcmorph/pom.xml
@@ -49,8 +49,20 @@ SPDX-License-Identifier: Apache-2.0
              never had an effect, and upstream llama.cpp defaults use_jinja to true, so chat
              templating is unchanged. The rest of the provider's API surface (LlamaModel,
              InferenceParameters, ModelParameters, ChatResponse/Timings/Pair, ChatResponseParser,
-             ReasoningFormat) is untouched by 5.1.0. -->
-        <llama.version>5.2.0-SNAPSHOT</llama.version>
+             ReasoningFormat) is untouched by 5.1.0.
+             5.2.0 is a BREAKING bump this module needs, not an optional one: the binding removed
+             ModelParameters.enableFlashAttn()/ModelFlag.FLASH_ATTN (--flash-attn takes a mandatory
+             on|off|auto value since llama.cpp b10273, so the valueless flag emitted a broken argv)
+             and renamed setTensorReadLazy/TensorReadLazyMode to setLazyMode/LazyMode (llama.cpp
+             b10731 renamed --tensor-read-lazy to --lazy-mode with no alias). The provider calls
+             both, so it cannot compile against 5.1.0 any more.
+             This deliberately names the RELEASE, not 5.2.0-SNAPSHOT: a snapshot would need a
+             <repositories> entry for the Central snapshot channel (this repo declares none -- the
+             distributionManagement/snapshotRepository below is deploy-only) AND would block every
+             srcmorph release, since Central rejects a release with a -SNAPSHOT dependency. The
+             build therefore stays red until net.ladenthin:llama:5.2.0 is published, and goes green
+             with no further edit the moment it is. -->
+        <llama.version>5.2.0</llama.version>
         <!-- Native build selector for net.ladenthin:llama. Empty = the main jar (CPU, Ninja default).
              The gpu-cuda / gpu-vulkan profiles set a GPU classifier; or override with
              -Dllama.classifier=cuda13-windows-x86-64. GPU builds need their runtime on PATH