refactor: remove LlamaPublisher in favour of consumer-side reactive adapters

Removes the hand-rolled reactive-streams Publisher and the associated
mandatory runtime dependency on org.reactivestreams. Adds consumer-facing
documentation showing how to wrap LlamaIterable with each mainstream
reactive library's resource-management primitive — verified end-to-end
by a new ReactorIntegrationTest using test-scope reactor-core.

Why now
=======

LlamaPublisher (introduced in PR #188 as section 2.3 of the Kotlin SDK
feature comparison) had zero non-test callers. The feature-investigation
document itself describes its source spec as "no longer a roadmap". The
real-world Android consumer LLaMAndroid uses the existing LlamaIterable
API directly inside a Kotlin flow { } block — bypassing the publisher
entirely. Upstream kherud/java-llama.cpp never carried this class.

LlamaIterable already implements Iterable<LlamaOutput> + AutoCloseable —
the contract every reactive library needs to bridge a blocking source:

  - Project Reactor : Flux.using(supplier, Flux::fromIterable, ::close)
  - RxJava 3 / RxAndroid : Flowable.using(supplier, Flowable::fromIterable, ::close)
  - Kotlin Flow : flow { iterable.use { for (x in it) emit(x) } }
  - Akka Streams : Source.fromIterator(() -> iterable.iterator())

These are the canonical patterns the libraries themselves recommend for
blocking sources. Keeping a Publisher in the binding forced every
consumer onto the org.reactivestreams runtime dep just to access a class
nobody called.

Critical correctness note: Flux.fromIterable / Flowable.fromIterable do
NOT auto-close AutoCloseable iterables on cancel — the consumer must use
.using(...) or equivalent. The README documents this caveat explicitly;
the ReactorIntegrationTest pins the correct pattern.

Changes
=======

Deletes:
  - src/main/java/net/ladenthin/llama/LlamaPublisher.java (175 LOC)
  - src/test/java/net/ladenthin/llama/LlamaPublisherTest.java (204 LOC)
  - LlamaModel.streamPublisher / streamChatPublisher (23 LOC)
  - pom.xml org.reactivestreams runtime dep + version property
  - module-info.java javadoc reference

Adds:
  - src/test/java/net/ladenthin/llama/ReactorIntegrationTest.java
    Mock-iterable contract test (always runs) + real-model gate test
    proving end-to-end cancel propagation via Flux.using + LlamaIterable.close
  - pom.xml reactor-core + reactor-test at test scope, 3.6.11
  - README.md new "Reactive integration" section covering Reactor,
    RxJava 3, Kotlin Flow (with LLaMAndroid reference), Akka Streams,
    and the why-no-built-in-Publisher rationale

Updates:
  - docs/feature-investigation-llama-stack-client-kotlin.md: section 2.3
    status now reads "SHIPPED + REVERTED REACTIVE PUBLISHER" with full
    rationale and pointer to the README
  - TODO.md: new Done entry capturing the decision trail

Net: -331 LOC (-503 source, +172 test/docs); -1 runtime dep
(org.reactivestreams); +2 test-scope deps (reactor-core, reactor-test).
SpotBugs Max+Low: total drops 25 -> 19 (all 6 LlamaPublisher$LlamaSubscription
findings cleared as a side effect: MDM_WAIT_WITHOUT_TIMEOUT x4 +
CWO_CLOSED_WITHOUT_OPENED + PRMC_POSSIBLY_REDUNDANT_METHOD_CALLS).

Tests
=====

ReactorIntegrationTest: 2 tests, mock variant always runs, real-model
variant gated on TestConstants.MODEL_PATH. Mock test proves Reactor
backpressure (request(2) delivers exactly 2 items, never more) and
cleanup-on-cancel (Flux.using cleanup function fires on cancel).
887 of 888 tests pass (the 1 error is the known sandbox-without-native-lib
UnsatisfiedLinkError in RerankingModelTest, unrelated to this change).

Author: claude

README.md

@@ -417,6 +417,67 @@ try (LlamaModel model = new LlamaModel(modelParams)) {
 }
 ```
 
+### Reactive integration (Reactor, RxJava, Kotlin Flow, Akka)
+
+`LlamaIterable` (returned by `model.generate(...)` and `model.generateChat(...)`)
+implements `Iterable<LlamaOutput> & AutoCloseable`, so every mainstream reactive
+library wraps it in a few lines without `java-llama.cpp` pulling in a runtime
+reactive dependency.
+
+**Always wrap with the library's resource-management primitive** — `Flux.using`,
+`Flowable.using`, Kotlin `use {}`, etc. — so that subscription cancellation
+flows into `LlamaIterable.close()` and from there into llama.cpp's native
+`cancelCompletion`. A plain `Flux.fromIterable(iterable)` or `for (x in iter)`
+loop will NOT close the iterable on cancel; the native task slot stays
+occupied until the model is closed.
+
+#### Project Reactor (Spring WebFlux)
+```java
+Flux<LlamaOutput> tokens = Flux.using(
+        () -> model.generate(params),
+        Flux::fromIterable,
+        LlamaIterable::close)
+    .subscribeOn(Schedulers.boundedElastic());
+```
+
+#### RxJava 3 (also for RxAndroid)
+```java
+Flowable<LlamaOutput> tokens = Flowable.using(
+        () -> model.generate(params),
+        Flowable::fromIterable,
+        LlamaIterable::close)
+    .subscribeOn(Schedulers.io());
+```
+
+#### Kotlin Flow (Android / coroutines)
+```kotlin
+fun llama(model: LlamaModel, params: InferenceParameters) = flow {
+    model.generate(params).use { iterable ->
+        for (output in iterable) emit(output)
+    }
+}.flowOn(Dispatchers.IO)
+```
+The companion Android sample [LLaMAndroid](https://github.com/Rattlyy/LLaMAndroid)
+demonstrates the `flow { for (output in model.generate(params)) emit(output) }`
+shape against the upstream binding. Wrap the `for` loop in
+`.use { }` if your collector may cancel mid-stream — otherwise the native task
+slot will not be released until the model is closed.
+
+#### Akka Streams
+```scala
+val tokens: Source[LlamaOutput, NotUsed] = Source
+    .fromIterator(() => model.generate(params).iterator())
+    .async("blocking-io-dispatcher")
+```
+
+**Why no built-in `Publisher`?** Earlier snapshots of this fork shipped a
+hand-rolled `LlamaModel.streamPublisher(...)` returning a Reactive Streams
+`Publisher<LlamaOutput>`. Since every reactive library bridges blocking
+iterables in a few lines via its own resource-management primitive, the binding
+now stays free of any reactive runtime dependency — pick whichever library your
+app already uses. The pattern is verified end-to-end by
+`ReactorIntegrationTest` in the test sources.
+
 ### Logging
 
 Per default, logs are written to stdout.

TODO.md

@@ -69,6 +69,22 @@ These are JNI plumbing items for upstream API additions. Policy: add only after
 
 ## Done (kept for history)
 
+- **Reactive `LlamaPublisher` removed in favour of consumer-side adapters.**
+  The hand-rolled `LlamaPublisher` + `LlamaModel.streamPublisher` /
+  `streamChatPublisher` (shipped in PR #188 as §2.3 of the Kotlin SDK
+  feature comparison) had zero non-test callers. `LlamaIterable` is
+  already `Iterable<LlamaOutput> & AutoCloseable`, and every mainstream
+  reactive library wraps it in a few lines via its own resource-management
+  primitive (`Flux.using`, `Flowable.using`, Kotlin `use {}`). The real-world
+  Android consumer [LLaMAndroid](https://github.com/Rattlyy/LLaMAndroid)
+  already uses `LlamaIterable` inside a Kotlin `flow {}` block — bypassing
+  the publisher entirely. README "Reactive integration" section documents
+  the Reactor / RxJava 3 / Kotlin Flow / Akka patterns; correctness is
+  pinned end-to-end by a new `ReactorIntegrationTest` using
+  test-scope `reactor-core` (zero runtime deps added; `org.reactivestreams`
+  runtime dep dropped). Cleared 6 fb-contrib Max+Low findings on
+  `LlamaPublisher$LlamaSubscription` as a side effect.
+
 - **Error Prone bug-pattern promotions to `ERROR`** — `855f447` (12 patterns promoted; `-Xlint:all` enabled).
 - **`javac -Werror` + `-Xlint:all,-serial,-options,-classfile,-processing`** — `3e2efbb`. ~20 EP warnings addressed first (EqualsGetClass on `Pair` via instanceof; MissingOverride on `PoolingType` / `RopeScalingType`; JdkObsolete `LinkedList` → `ArrayList` in `LlamaLoader`; StringSplitter inline-suppressed; 3× StringCaseLocaleUsage `Locale.ROOT` in `OSInfo`; EmptyCatch in `OSInfo.isAlpineLinux`; FutureReturnValueIgnored in `LlamaModel.completeAsync`; Finalize on `LlamaModel.finalize`; MixedMutabilityReturnType in 4 parser methods; EnumOrdinal in `InferenceParameters.setMiroStat`; EscapedEntity in `InferenceParameters` javadoc; 4× TypeParameterUnusedInFormals; AnnotateFormatMethod on `Java8CompatibilityHelper.formatted`; SafeVarargs + varargs on `Java8CompatibilityHelper.listOf`).
 - **`-parameters` javac arg** — `4350cf2`.

docs/feature-investigation-llama-stack-client-kotlin.md

@@ -158,14 +158,27 @@ papercut.
 
 ### 2.3 Async / non-blocking API — **S–M**
 
-**Status: SHIPPED.** `CompletableFuture` wrappers (`completeAsync`,
-`chatCompleteAsync`, `chatCompleteTextAsync`, plus a
+**Status: SHIPPED + REVERTED REACTIVE PUBLISHER.** `CompletableFuture` wrappers
+(`completeAsync`, `chatCompleteAsync`, `chatCompleteTextAsync`, plus a
 `completeAsync(params, CancellationToken)` bridge that propagates
-`future.cancel(true)` into the cooperative token) in commit `1e673a9`.
-The reactive `Publisher<LlamaOutput>` follow-up (backpressure via
-Reactive Streams, single-subscriber) shipped in commit `afa4f65` as
-`LlamaModel.streamPublisher(...)` and `streamChatPublisher(...)` backed
-by `LlamaPublisher`. New runtime dep: `org.reactivestreams:reactive-streams:1.0.4`.
+`future.cancel(true)` into the cooperative token) in commit `1e673a9` —
+**still shipped**.
+
+The reactive `Publisher<LlamaOutput>` follow-up was shipped in commit `afa4f65`
+as `LlamaModel.streamPublisher(...)` / `streamChatPublisher(...)` backed by
+`LlamaPublisher`. **It has since been removed** — see the README section
+"Reactive integration" for the rationale and the canonical replacement
+patterns. In short: `LlamaIterable` is already
+`Iterable<LlamaOutput> & AutoCloseable`, and every mainstream reactive
+library (Project Reactor, RxJava 3, Kotlin coroutines `Flow`, Akka Streams)
+wraps it in a few lines via its own resource-management primitive
+(`Flux.using`, `Flowable.using`, Kotlin `use {}`, etc.). Keeping a hand-rolled
+`Publisher` in the binding imposed a mandatory `org.reactivestreams` runtime
+dep on every consumer for a class that had **zero non-test callers** —
+including the canonical Android sample [LLaMAndroid](https://github.com/Rattlyy/LLaMAndroid),
+which uses `LlamaIterable` directly inside a Kotlin `flow { }` block. Pattern
+correctness is now pinned end-to-end by `ReactorIntegrationTest`
+(test-scope `reactor-core`); zero runtime deps added.
 
 **Gap.** All `LlamaModel` methods are blocking. Kotlin offers
 `suspend fun` + Flow variants. JVM users currently dedicate platform

pom.xml

@@ -56,7 +56,7 @@ SPDX-License-Identifier: MIT
 		<nullaway.version>0.13.4</nullaway.version>
 		<checker.version>4.2.0</checker.version>
 		<jackson.version>2.22.0</jackson.version>
-		<reactive-streams.version>1.0.4</reactive-streams.version>
+		<reactor.version>3.6.11</reactor.version>
 		<slf4j.version>2.0.18</slf4j.version>
 		<logback.version>1.5.34</logback.version>
 		<animal-sniffer.version>1.27</animal-sniffer.version>
@@ -140,14 +140,6 @@ SPDX-License-Identifier: MIT
 			<artifactId>jackson-databind</artifactId>
 			<version>${jackson.version}</version>
 		</dependency>
-		<!-- Reactive Streams API used by LlamaPublisher to expose token streams as a
-		     Publisher<LlamaOutput>. Java 8 compatible, ~5 KB, supplies the standard
-		     interfaces that Reactor / RxJava / Kotlin coroutines bridge to. -->
-		<dependency>
-			<groupId>org.reactivestreams</groupId>
-			<artifactId>reactive-streams</artifactId>
-			<version>${reactive-streams.version}</version>
-		</dependency>
 		<!-- Required by OSInfo (vendored from xerial/sqlite-jdbc) for log emission. -->
 		<dependency>
 			<groupId>org.slf4j</groupId>
@@ -202,6 +194,23 @@ SPDX-License-Identifier: MIT
 			<version>${logcaptor.version}</version>
 			<scope>test</scope>
 		</dependency>
+		<!-- Test-only Project Reactor used by ReactorIntegrationTest to prove the
+		     "wrap LlamaIterable with Flux.fromIterable + subscribeOn" pattern works
+		     end-to-end (backpressure, AutoCloseable cancel propagation). NOT a runtime
+		     dependency — consumers bring whichever reactive lib they already use
+		     (Reactor / RxJava / Kotlin Flow / Akka — see README "Reactive integration"). -->
+		<dependency>
+			<groupId>io.projectreactor</groupId>
+			<artifactId>reactor-core</artifactId>
+			<version>${reactor.version}</version>
+			<scope>test</scope>
+		</dependency>
+		<dependency>
+			<groupId>io.projectreactor</groupId>
+			<artifactId>reactor-test</artifactId>
+			<version>${reactor.version}</version>
+			<scope>test</scope>
+		</dependency>
 	</dependencies>
 
 	<build>

src/main/java/module-info.java

@@ -26,10 +26,10 @@
  * <p>{@code requires static org.jspecify} is needed only at compile time of this
  * descriptor; JSpecify annotations carry {@code RetentionPolicy.CLASS} so module-path
  * consumers never need jspecify on their runtime path. Checker Framework qualifiers and
- * the Codehaus animal-sniffer annotation are likewise compile-time only. Jackson, SLF4J,
- * and Reactive Streams API are referenced from ordinary sources only; javac in the
- * separate {@code module-info-compile} execution compiles {@code module-info.java} in
- * isolation and therefore does not need their module names. Consumers that put this jar
+ * the Codehaus animal-sniffer annotation are likewise compile-time only. Jackson and
+ * SLF4J are referenced from ordinary sources only; javac in the separate
+ * {@code module-info-compile} execution compiles {@code module-info.java} in isolation
+ * and therefore does not need their module names. Consumers that put this jar
  * on the module path will load these dependencies through their own {@code requires}
  * graph; consumers on the classpath are unaffected.</p>
  *

src/main/java/net/ladenthin/llama/LlamaModel.java

@@ -213,29 +213,6 @@ public java.util.List<ChatResponse> chatBatch(java.util.Collection<ChatRequest>
         return out;
     }
 
-    /**
-     * Reactive-streams variant of {@link #generate(InferenceParameters)}. Returns a
-     * {@link org.reactivestreams.Publisher} of {@link LlamaOutput} tokens. Each subscriber
-     * triggers a fresh streaming inference on a dedicated background thread; backpressure
-     * is honoured via the Reactive Streams {@code request(n)} protocol. Use
-     * {@link org.reactivestreams.Subscription#cancel()} to stop the inference early.
-     *
-     * @param parameters the inference configuration
-     * @return a single-subscriber {@link org.reactivestreams.Publisher} of tokens
-     */
-    public LlamaPublisher streamPublisher(InferenceParameters parameters) {
-        return new LlamaPublisher(this, parameters, false);
-    }
-
-    /**
-     * Reactive-streams variant of {@link #generateChat(InferenceParameters)}.
-     *
-     * @param parameters the inference parameters including messages
-     * @return a single-subscriber {@link org.reactivestreams.Publisher} of tokens
-     */
-    public LlamaPublisher streamChatPublisher(InferenceParameters parameters) {
-        return new LlamaPublisher(this, parameters, true);
-    }
 
     /**
      * Asynchronous variant of {@link #complete(InferenceParameters)}. Runs the inference on