Ship natives as one jar per backend, declared once in natives.csv

net.ladenthin:llama is now the Java classes only. Every native build ships as
its own jar of the same artifact, classifier <backend>-<os>-<arch>, holding
exactly one directory net/ladenthin/llama/<OS>/<ARCH>/<backend>/. The
directories never overlap, so any combination of natives jars shares one
classpath: LlamaLoader tries the backends it finds in a fixed order (GPU
backends, metal, msvc, cpu) through its ClassLoader and falls through to the
CPU library when a GPU runtime is missing. A GPU jar next to the CPU jar now
has a CPU fallback; before, each GPU classifier was a complete replacement jar
with its own compile pass and none.

- llama-platform: new pom-packaging module (nothing to upload besides the
  pom) naming the classes jar plus the CPU/Metal jars of every desktop.
- .github/natives.csv is the single list of natives jars. The merge and
  fat-jar scripts read it; check-natives.py (code-style job) fails when the
  generated pom executions, llama-platform, the workflow artifact names or
  BACKEND_PRIORITY disagree with it. The 16 classifier profiles (17 compile
  passes) became one generated `natives` profile: pom 2278 -> ~1570 lines.
- CMake writes to src/main/natives/<OS>/<ARCH>/<backend>/; build jobs upload
  natives-<classifier>, and the package/publish jobs fetch them with one glob
  instead of ~20 download steps each. The merge checks every listed artifact
  arrived holding only its own directory.
- The all-backends fat jars are plain merges; the jllama-backends.txt
  manifest is gone. Sibling files a backend needs first are listed in a
  per-directory jllama-extras.txt.
- Module path: each natives jar declares a unique Automatic-Module-Name.
  Without it every natives jar derives the module name `llama` and the JVM
  silently keeps only the first (measured); package-fatjars.sh checks the
  manifest of every built jar. module-info now requires Jackson and SLF4J,
  without which the classes jar never worked on the module path.
- smoke-natives-jars.sh loads the classes jar with all 26 natives jars at
  once, on the classpath and on the module path, in the package job.
- Three test classes checked for the library at a hard-coded path and would
  have skipped silently on the new layout; one shared NativeLibraryPresence
  helper replaces them.
- The Atmosphere agent depends on llama-platform (opt out with
  -Dllama.natives=none, as CI does); the langchain4j and agent integration
  jobs point the loader at the downloaded library via lib.path.

Verified locally with a real Linux x86-64 build plus placeholder libraries
for the other 25 directories: 1823 tests green, all 26 natives jars and 4
all-backends jars built and checked, the fat jar and the natives jars load
on classpath and module path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AytmJF9faEiQEVt6eetQS2

Author: claude

.github/check-natives.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+"""Fail when anything that names the natives jars disagrees with .github/natives.csv.
+
+The list is the one place a natives jar is declared. Everything else either reads it (the merge,
+the fat-jar assembly) or must repeat it, and is checked here:
+  * llama/pom.xml       one jar execution per row: classifier, directory, Automatic-Module-Name
+  * llama-platform      depends on exactly the rows marked platform=yes
+  * publish.yml         a build job uploads natives-<classifier> for every row, and no other
+  * LlamaLoader         BACKEND_PRIORITY tries every backend (else a jar ships and never loads)
+
+Usage:
+  check-natives.py          check, exit 1 on any disagreement
+  check-natives.py pom      print the natives jar executions for llama/pom.xml
+"""
+
+import csv
+import os
+import re
+import sys
+import xml.etree.ElementTree as ET
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+NS = {"m": "http://maven.apache.org/POM/4.0.0"}
+
+
+def rows():
+    with open(os.path.join(ROOT, ".github", "natives.csv"), encoding="utf-8") as f:
+        lines = [line for line in f if line.strip() and not line.startswith("#")]
+    return list(csv.DictReader(lines))
+
+
+def module_name(classifier):
+    """Each natives jar needs its own: without one, every jar derives the module name `llama`
+    from its file name, and the module path silently keeps only the first."""
+    return "net.ladenthin.llama.natives." + classifier.replace("-", "_")
+
+
+def pom_execution(row):
+    return f"""\t\t\t\t\t\t\t<execution>
+\t\t\t\t\t\t\t\t<id>natives-{row['classifier']}</id>
+\t\t\t\t\t\t\t\t<phase>package</phase>
+\t\t\t\t\t\t\t\t<goals>
+\t\t\t\t\t\t\t\t\t<goal>jar</goal>
+\t\t\t\t\t\t\t\t</goals>
+\t\t\t\t\t\t\t\t<configuration>
+\t\t\t\t\t\t\t\t\t<classifier>{row['classifier']}</classifier>
+\t\t\t\t\t\t\t\t\t<classesDirectory>${{project.basedir}}/src/main/natives</classesDirectory>
+\t\t\t\t\t\t\t\t\t<includes>
+\t\t\t\t\t\t\t\t\t\t<include>net/ladenthin/llama/{row['directory']}/**</include>
+\t\t\t\t\t\t\t\t\t</includes>
+\t\t\t\t\t\t\t\t\t<archive>
+\t\t\t\t\t\t\t\t\t\t<addMavenDescriptor>false</addMavenDescriptor>
+\t\t\t\t\t\t\t\t\t\t<manifestEntries>
+\t\t\t\t\t\t\t\t\t\t\t<Automatic-Module-Name>{module_name(row['classifier'])}</Automatic-Module-Name>
+\t\t\t\t\t\t\t\t\t\t</manifestEntries>
+\t\t\t\t\t\t\t\t\t</archive>
+\t\t\t\t\t\t\t\t</configuration>
+\t\t\t\t\t\t\t</execution>"""
+
+
+def pom_natives(path):
+    """classifier -> (include, module name) for every jar execution of the natives profile."""
+    tree = ET.parse(path)
+    found = {}
+    for profile in tree.getroot().iterfind("m:profiles/m:profile", NS):
+        if profile.findtext("m:id", namespaces=NS) != "natives":
+            continue
+        for ex in profile.iterfind(".//m:plugin/m:executions/m:execution", NS):
+            conf = ex.find("m:configuration", NS)
+            classifier = conf.findtext("m:classifier", namespaces=NS) if conf is not None else None
+            if classifier:
+                found[classifier] = (conf.findtext("m:includes/m:include", namespaces=NS),
+                                     conf.findtext("m:archive/m:manifestEntries/m:Automatic-Module-Name",
+                                                   namespaces=NS))
+    return found
+
+
+def compare(what, expected, actual, failures):
+    for name in sorted(expected - actual):
+        failures.append(f"{what}: missing {name}")
+    for name in sorted(actual - expected):
+        failures.append(f"{what}: {name} is not in .github/natives.csv")
+
+
+def main(argv):
+    natives = rows()
+    if len(argv) > 1 and argv[1] == "pom":
+        print("\n".join(pom_execution(r) for r in natives))
+        return 0
+    failures = []
+    by_classifier = {r["classifier"]: r for r in natives}
+    if len(by_classifier) != len(natives):
+        failures.append("natives.csv lists a classifier twice")
+    for r in natives:
+        backend, rest = r["directory"].rsplit("/", 1)[1], r["classifier"]
+        if not rest.startswith(backend + "-") or r["platform"] not in ("yes", "no"):
+            failures.append(f"natives.csv: row {r['classifier']} -- classifier must start with its "
+                            f"directory's backend '{backend}', platform must be yes or no")
+
+    pom = pom_natives(os.path.join(ROOT, "llama", "pom.xml"))
+    compare("llama/pom.xml natives profile", set(by_classifier), set(pom), failures)
+    for classifier in sorted(set(pom) & set(by_classifier)):
+        want = (f"net/ladenthin/llama/{by_classifier[classifier]['directory']}/**", module_name(classifier))
+        if pom[classifier] != want:
+            failures.append(f"llama/pom.xml: {classifier} has {pom[classifier]}, expected {want} "
+                            f"(check-natives.py pom prints the executions)")
+
+    platform = ET.parse(os.path.join(ROOT, "llama-platform", "pom.xml"))
+    deps = {d.findtext("m:classifier", namespaces=NS)
+            for d in platform.getroot().iterfind("m:dependencies/m:dependency", NS)} - {None}
+    compare("llama-platform/pom.xml", {r["classifier"] for r in natives if r["platform"] == "yes"}, deps, failures)
+
+    with open(os.path.join(ROOT, ".github", "workflows", "publish.yml"), encoding="utf-8") as f:
+        uploads = set(re.findall(r"upload-artifact@\S+\s+with:\s+name:\s*natives-(\S+)", f.read()))
+    compare("publish.yml natives-* uploads", set(by_classifier), uploads, failures)
+
+    loader = os.path.join(ROOT, "llama", "src", "main", "java", "net", "ladenthin", "llama", "loader",
+                          "LlamaLoader.java")
+    with open(loader, encoding="utf-8") as f:
+        block = re.search(r"BACKEND_PRIORITY\s*=(.*?);", f.read(), re.S)
+    priority = set(re.findall(r'"([^"]+)"', block.group(1))) if block else set()
+    for backend in sorted({r["directory"].rsplit("/", 1)[1] for r in natives} - priority):
+        failures.append(f"LlamaLoader.BACKEND_PRIORITY does not try '{backend}' -- its jars would never load")
+
+    for f in failures:
+        print(f"::error::{f}", file=sys.stderr)
+    print(f"{len(natives)} natives jars, {len(failures)} disagreements")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

.github/merge-native-artifacts.sh

@@ -4,43 +4,41 @@
 #
 # SPDX-License-Identifier: MIT OR Apache-2.0
 
-# Merges the per-artifact native-library trees downloaded by the `*-libraries` glob into the
-# single default-JAR resource tree — and FAILS LOUD if two artifacts claim the same file path.
+# Merges the per-build native-library artifacts downloaded by the `natives-*` glob into the one
+# natives tree (llama/src/main/natives/net/ladenthin/llama/) that the `natives` Maven profile
+# packages — and FAILS LOUD when an artifact does not hold exactly what its name promises.
 #
-# Why this exists: the `package` / `publish-snapshot` / `publish-release` jobs pull every build
-# job whose artifact name ends in `-libraries` with one globbed `actions/download-artifact`.
-# That is convenient (a new CPU platform ships in the default JAR by naming its artifact
-# `<Something>-libraries`, no packaging change) but it is silently unsafe: an artifact name says
-# nothing about which `{OS}/{ARCH}` subdirectory the job's CMake run actually wrote. When two
-# artifacts carry the same relative path, `merge-multiple: true` extracts both onto that one
-# path and the survivor can be a byte-level hybrid of the two, not either input.
+# Every shipped build uploads its tree as `natives-<classifier>`, one per row of
+# .github/natives.csv, which names the one directory it may write. Checked before anything is
+# merged:
+#   * every listed artifact arrived, with its library, and no unlisted one did;
+#   * every file lies below the artifact's own directory. A build whose CMake picked another
+#     backend name or platform (the routing lives in llama/CMakeLists.txt) would otherwise land in
+#     some other natives jar, or in none;
+#   * no relative path is claimed by two artifacts. This follows from the second check, and is
+#     kept anyway because it is the failure that actually shipped: all three macOS build jobs
+#     wrote Mac/aarch64 and used to share one glob, the merge produced a byte-level hybrid of two
+#     dylibs, and macOS SIGKILLed every process that loaded it (5.0.6 and several 5.0.7
+#     snapshots). A check on the merged tree cannot see it — the collision leaves exactly one
+#     file on the path, a corrupt one — so it has to run before the merge.
 #
-# That is exactly what happened to macOS arm64: all three macOS build jobs write
-# `Mac/aarch64/libjllama.dylib` (none of them passes -DOS_NAME/-DOS_ARCH, so CMakeLists
-# auto-detects the same subdir) and all three used to upload under a `*-libraries` name. The
-# published dylib became a hybrid whose ad-hoc linker signature no longer matched its own
-# __TEXT pages, so macOS SIGKILLed every process that loaded it — shipped broken in 5.0.6 and
-# several 5.0.7 snapshots. The immediate fix renamed those artifacts out of the glob; this
-# script is the backstop that stops the same hole from being reopened by a future job.
-#
-# NOTE ON WHAT *CANNOT* WORK AS A GUARD: asserting "exactly one library per {OS}/{ARCH}" on the
-# merged tree does not detect this. The collision overwrites one path, so the merged tree still
-# holds exactly one file there — a corrupt one. The collision is only observable BEFORE the
-# merge, which is why this script does the merge itself instead of checking afterwards.
+# After the merge, a backend directory holding files beside its library gets a
+# jllama-extras.txt listing them; LlamaLoader loads those first (e.g. the OpenCL ICD loader that
+# OpenVINO ships on Windows).
 #
 # Usage: merge-native-artifacts.sh <staging-dir> <dest-dir>
-#   <staging-dir>  output of `actions/download-artifact` with `pattern: "*-libraries"` and
+#   <staging-dir>  output of `actions/download-artifact` with `pattern: "natives-*"` and
 #                  `merge-multiple: false`, i.e. one subdirectory per artifact name.
-#   <dest-dir>     the tree the artifacts are merged into, e.g.
-#                  llama/src/main/resources/net/ladenthin/llama/
+#   <dest-dir>     the tree the artifacts are merged into,
+#                  llama/src/main/natives/net/ladenthin/llama/
 #
-# Fail-loud: aborts when the staging directory holds no artifacts (a silently empty default JAR
-# is worse than a red job) and when any relative path is claimed by more than one artifact.
+# Fail-loud: also aborts when the staging directory holds no artifacts.
 
 set -euo pipefail
 
 STAGING="${1:?usage: merge-native-artifacts.sh <staging-dir> <dest-dir>}"
 DEST="${2:?usage: merge-native-artifacts.sh <staging-dir> <dest-dir>}"
+LIST="$(dirname "$0")/natives.csv"
 
 if [ ! -d "$STAGING" ]; then
   echo "::error::staging directory '$STAGING' does not exist — the globbed download did not run." >&2
@@ -52,12 +50,31 @@ artifacts=()
 while IFS= read -r d; do artifacts+=("$(basename "$d")"); done < <(find "$STAGING" -mindepth 1 -maxdepth 1 -type d | sort)
 
 if [ "${#artifacts[@]}" -eq 0 ]; then
-  echo "::error::no '*-libraries' artifacts found in '$STAGING' — the default JAR would ship without native libraries." >&2
+  echo "::error::no 'natives-*' artifacts found in '$STAGING' — there would be no natives jars." >&2
   exit 1
 fi
 
 echo "Merging ${#artifacts[@]} native-library artifact(s) into $DEST"
-for a in "${artifacts[@]}"; do echo "  - $a"; done
+listed=0
+while IFS=, read -r classifier dir lib _; do
+  listed=$((listed + 1))
+  a="natives-$classifier"
+  if [ ! -d "$STAGING/$a" ]; then
+    echo "::error::no artifact '$a' -- the build job for this row of $LIST did not upload it" >&2
+    exit 1
+  fi
+  stray="$(cd "$STAGING/$a" && find . -type f | sed 's|^\./||' | grep -v "^$dir/" || true)"
+  if [ -n "$stray" ] || [ ! -f "$STAGING/$a/$dir/$lib" ]; then
+    echo "::error::artifact '$a' must hold $dir/$lib and nothing outside $dir/; outside it:" >&2
+    printf '%s\n' "$stray" | sed 's|^|::error::  |' >&2
+    exit 1
+  fi
+  echo "  - $a -> $dir/"
+done < <(grep -v -e '^#' -e '^classifier,' -e '^$' "$LIST")
+if [ "$listed" -ne "${#artifacts[@]}" ]; then
+  echo "::error::$STAGING holds ${#artifacts[@]} natives-* artifacts but $LIST lists $listed: $(printf '%s ' "${artifacts[@]}")" >&2
+  exit 1
+fi
 
 # relpath -> space-separated list of artifacts that carry it. Bash 3.2 (macOS) has no
 # associative arrays, so this stays a sorted "<relpath>\t<artifact>" stream processed by awk.
@@ -71,16 +88,11 @@ collisions="$(
 )"
 
 if [ -n "$collisions" ]; then
-  echo "::error::two or more '*-libraries' artifacts write the same path — merging them would produce a hybrid, corrupt native library." >&2
+  echo "::error::two or more 'natives-*' artifacts write the same path — merging them would produce a hybrid, corrupt native library." >&2
   while IFS=$'\t' read -r path owners; do
     echo "::error::  $path  <- claimed by:$owners" >&2
   done <<< "$collisions"
-  cat >&2 <<'EOF'
-::error::Fix: only ONE artifact per {OS}/{ARCH} may be named `*-libraries`. Rename the extra
-::error::build jobs' artifacts outside the glob (as the macOS jobs do: macos-15-metal /
-::error::macos-14-metal / macos-15-no-metal) and download the variant that ships explicitly by
-::error::name. See CLAUDE.md, "macOS arm64: three build jobs, one shipped dylib".
-EOF
+  echo "::error::Fix: only one shipped build per <backend>-<os>-<arch>; name a test-only variant outside the glob (see CLAUDE.md, \"macOS arm64\")." >&2
   exit 1
 fi
 
@@ -89,5 +101,14 @@ for a in "${artifacts[@]}"; do
   cp -R "$STAGING/$a/." "$DEST/"
 done
 
+# Sibling files of a backend's library are loaded before it, in name order.
+find "$DEST" -mindepth 3 -maxdepth 3 -type d | sort | while IFS= read -r dir; do
+  extras="$(cd "$dir" && find . -maxdepth 1 -type f ! -name 'libjllama.*' ! -name 'jllama.dll' ! -name '*.metal' ! -name jllama-extras.txt | sed 's|^\./||' | sort)"
+  if [ -n "$extras" ]; then
+    printf '%s\n' "$extras" > "$dir/jllama-extras.txt"
+    echo "extras for ${dir#"$DEST"}: $(echo "$extras" | tr '\n' ' ')"
+  fi
+done
+
 echo "Merged native tree:"
 find "$DEST" -type f | sort | sed 's|^|  |'

.github/natives.csv

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+#
+# The natives jars: the single list every packaging step reads (see CLAUDE.md, "Natives jars").
+# One row per jar, net.ladenthin:llama:<classifier>, holding exactly one directory,
+# net/ladenthin/llama/<directory>/, whose name ends in the backend LlamaLoader tries.
+#   classifier  <backend>-<os>-<arch>; the build job uploads its tree as artifact natives-<classifier>
+#   directory   <OS>/<ARCH>/<backend>, as llama/CMakeLists.txt writes it and OSInfo resolves it
+#   library     the file that must be in it
+#   platform    yes = a dependency of net.ladenthin:llama-platform (the CPU natives of a desktop)
+# Adding a row: add the natives jar execution to llama/pom.xml (`check-natives.py pom` prints it),
+# a build job uploading natives-<classifier>, and, for a new backend, its name in CMakeLists.txt
+# and LlamaLoader.BACKEND_PRIORITY. .github/check-natives.py fails until all of them agree.
+classifier,directory,library,platform
+cpu-linux-x86-64,Linux/x86_64/cpu,libjllama.so,yes
+cpu-linux-aarch64,Linux/aarch64/cpu,libjllama.so,yes
+cpu-linux-s390x,Linux/s390x/cpu,libjllama.so,yes
+cpu-android-aarch64,Linux-Android/aarch64/cpu,libjllama.so,no
+cpu-android-x86-64,Linux-Android/x86_64/cpu,libjllama.so,no
+cpu-windows-x86-64,Windows/x86_64/cpu,jllama.dll,yes
+cpu-windows-x86,Windows/x86/cpu,jllama.dll,yes
+cpu-windows-aarch64,Windows/aarch64/cpu,jllama.dll,yes
+metal-macos-aarch64,Mac/aarch64/metal,libjllama.dylib,yes
+msvc-windows-x86-64,Windows/x86_64/msvc,jllama.dll,no
+msvc-windows-x86,Windows/x86/msvc,jllama.dll,no
+cuda13-linux-x86-64,Linux/x86_64/cuda13,libjllama.so,no
+cuda13-windows-x86-64,Windows/x86_64/cuda13,jllama.dll,no
+vulkan-linux-x86-64,Linux/x86_64/vulkan,libjllama.so,no
+vulkan-linux-aarch64,Linux/aarch64/vulkan,libjllama.so,no
+vulkan-windows-x86-64,Windows/x86_64/vulkan,jllama.dll,no
+opencl-android-aarch64,Linux-Android/aarch64/opencl,libjllama.so,no
+opencl-windows-x86-64,Windows/x86_64/opencl,jllama.dll,no
+opencl-windows-aarch64,Windows/aarch64/opencl,jllama.dll,no
+rocm-linux-x86-64,Linux/x86_64/rocm,libjllama.so,no
+rocm-windows-x86-64,Windows/x86_64/rocm,jllama.dll,no
+sycl-fp16-linux-x86-64,Linux/x86_64/sycl-fp16,libjllama.so,no
+sycl-fp32-linux-x86-64,Linux/x86_64/sycl-fp32,libjllama.so,no
+sycl-windows-x86-64,Windows/x86_64/sycl,jllama.dll,no
+openvino-linux-x86-64,Linux/x86_64/openvino,libjllama.so,no
+openvino-windows-x86-64,Windows/x86_64/openvino,jllama.dll,no