test(loader): add model-free native-load smoke + document the procedure

Adds NativeLibraryLoadSmokeTest: forces LlamaModel.<clinit> (System.load ->
JNI_OnLoad), which FindClass-es every JNI-referenced Java class, with no GGUF
model required. It guards the two load-time failure modes that shipped on this
branch and were invisible to a local `mvn test` (model-gated tests self-skip
before the lib loads) and to the pure-Java unit tests:
  - wrong native-resource path in LlamaLoader (lib not found), and
  - a stale FindClass FQN in jllama.cpp after a Java package move (lib loads
    but JNI_OnLoad throws NoClassDefFoundError).

The test self-skips when libjllama is not on the classpath (pure-Java checkout,
no CMake build), so a build-less `mvn test` stays green; CI's test-java-* jobs
and any local build run it for real. Presence is checked against the canonical
/net/ladenthin/llama/<os>/<arch>/ layout directly (not via
LlamaLoader.getNativeResourcePath()) so a regression there cannot silently skip
the guard — instead the load itself fails the assertion.

Verified locally both ways: lib present -> Tests run: 1 (loads, JNI_OnLoad OK);
lib moved aside -> Skipped: 1, BUILD SUCCESS.

CLAUDE.md: documents the model-free load-verification recipe under
"Restricted-network environments" (build the lib via FetchContent — GitHub is
reachable even when huggingface.co is not — then run the smoke test), and the
rule to update jllama.cpp FindClass/signature FQNs + keep
LlamaLoader.NATIVE_RESOURCE_BASE anchored when moving a JNI-referenced class.

Author: claude

CLAUDE.md

@@ -303,6 +303,49 @@ be exercised either in CI (via `.github/workflows/publish.yml`) or on a
 developer machine with HF access; pre-staged models can also be uploaded
 into `models/` out-of-band.
 
+**Verifying the native library *loads* without models (model-free smoke).**
+Even with HuggingFace blocked you can still do the one piece of *real native*
+verification that does not need a GGUF: confirm the library loads and its
+`JNI_OnLoad` resolves every Java class it looks up by name. The model-gated
+tests cannot do this in a restricted sandbox — they self-skip via
+`Assume.assumeTrue(model present)` **before** the lib is ever loaded, so a plain
+`mvn test` is silent on load-time breakage. The full local recipe:
+
+```bash
+# 1. Build the native lib locally (FetchContent pulls llama.cpp from GitHub,
+#    which is reachable even when huggingface.co is not):
+mvn -q compile
+cmake -B build -DBUILD_TESTING=ON
+cmake --build build --config Release -j$(nproc)   # -> src/main/resources/.../<os>/<arch>/libjllama.so
+# 2. Force LlamaModel.<clinit> (System.load -> JNI_OnLoad) with no model:
+mvn test -Dtest=NativeLibraryLoadSmokeTest
+```
+
+`NativeLibraryLoadSmokeTest` (in the `loader` package) calls
+`Class.forName("net.ladenthin.llama.LlamaModel")`, which runs
+`LlamaLoader.initialize() -> System.load() -> JNI_OnLoad`, which in turn calls
+`FindClass(...)` for every JNI-referenced Java class. It **passes** when the lib
+loads cleanly, **fails** if the native-resource path in `LlamaLoader` is wrong
+(lib not found) or a `FindClass`/field-signature FQN in
+`src/main/cpp/jllama.cpp` is stale after a Java package move (lib loads but
+`JNI_OnLoad` throws `NoClassDefFoundError: net/ladenthin/llama/...`), and
+**self-skips** when `libjllama` is not on the classpath (pure-Java checkout, no
+CMake build) so it never breaks a build-less `mvn test`.
+
+Both of those failure modes shipped on a branch once — the layered-package
+restructure left (a) `LlamaLoader.getNativeResourcePath()` deriving the resource
+root from the loader's own package (which moved to `…loader`) and (b)
+`jllama.cpp` still `FindClass`-ing the old flat paths — and neither was visible
+to a local `mvn test` (model tests skipped) or to the pure-Java unit tests.
+**When you move a Java class the JNI layer references by name** (`LlamaModel`
+[root], `exception.LlamaException`, `value.LogLevel`, `args.LogFormat`,
+`callback.LoadProgressCallback`), update the matching `FindClass` / `"L…;"`
+signature string in `src/main/cpp/jllama.cpp` and keep the native-resource root
+anchored at `net/ladenthin/llama/` in `LlamaLoader.NATIVE_RESOURCE_BASE` (it must
+not track the loader's own Java package). This is the same
+"FQN/path not updated after a package move" class as the stale
+`spotbugs-exclude.xml`, PIT `targetClasses`, and `CMakeLists.txt` OSInfo repairs.
+
 ### Code Formatting
 ```bash
 clang-format -i src/main/cpp/*.cpp src/main/cpp/*.hpp   # Format C++ code

src/test/java/net/ladenthin/llama/loader/NativeLibraryLoadSmokeTest.java

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: MIT
+
+package net.ladenthin.llama.loader;
+
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assumptions.assumeTrue;
+
+import net.ladenthin.llama.ClaudeGenerated;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Model-free smoke test that the bundled native library actually loads and its
+ * {@code JNI_OnLoad} resolves every Java class it looks up by name.
+ *
+ * <p>Forcing {@code LlamaModel.<clinit>} runs
+ * {@code LlamaLoader.initialize() -> System.load() -> JNI_OnLoad}, which calls
+ * {@code FindClass(...)} for the JNI-referenced classes ({@code LlamaException},
+ * {@code LogLevel}, {@code LogFormat}, ...). No GGUF model is required, so this
+ * catches the two failure modes that the model-gated tests cannot exercise when
+ * models are absent (e.g. in a restricted-network sandbox):
+ *
+ * <ul>
+ *   <li>a wrong native-resource path in {@link LlamaLoader} (lib not found), and</li>
+ *   <li>a stale {@code FindClass} FQN in {@code jllama.cpp} after a Java package
+ *       move (lib loads but {@code JNI_OnLoad} throws
+ *       {@code NoClassDefFoundError}).</li>
+ * </ul>
+ *
+ * <p>Both bugs shipped once on this branch precisely because they only surface
+ * when the library is loaded — see the regression history in {@code CLAUDE.md}.
+ *
+ * <p>The test self-skips when {@code libjllama} is not on the classpath (a
+ * pure-Java checkout with no native build), so a plain {@code mvn test} stays
+ * green without a CMake build; CI's {@code test-java-*} jobs and any local build
+ * have the library and run it for real. The presence check uses the canonical
+ * resource layout directly (not {@link LlamaLoader#getNativeResourcePath()}) so
+ * a regression in that method cannot silently skip this guard.
+ */
+@ClaudeGenerated(
+        purpose = "Model-free native-load smoke: force LlamaModel.<clinit> so System.load + JNI_OnLoad "
+                + "run and resolve every FindClass'd Java class. Guards against native-resource-path and "
+                + "stale-JNI-FQN regressions that only appear when the library is actually loaded; skips "
+                + "cleanly when libjllama is not on the classpath.")
+class NativeLibraryLoadSmokeTest {
+
+    private static boolean nativeLibraryOnClasspath() {
+        String resource = "/net/ladenthin/llama/" + OSInfo.getNativeLibFolderPathForCurrentOS() + "/"
+                + System.mapLibraryName("jllama");
+        return NativeLibraryLoadSmokeTest.class.getResource(resource) != null;
+    }
+
+    @Test
+    void loadingNativeLibraryRunsJniOnLoadWithoutError() {
+        assumeTrue(nativeLibraryOnClasspath(), "libjllama not on classpath — skipping native-load smoke");
+        assertDoesNotThrow(
+                () -> Class.forName("net.ladenthin.llama.LlamaModel"),
+                "LlamaModel.<clinit> must load the native library and JNI_OnLoad must resolve "
+                        + "every FindClass'd Java class");
+    }
+}