Merge pull request #253 from bernardladenthin/claude/bold-brahmagupta-y8wc7p

Validate slotId and handle next_token array in SlotMetrics

Author: bernardladenthin

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

@@ -79,15 +79,24 @@ public Session(LlamaModel model, int slotId, @Nullable String systemMessage) {
      * the transformed instance — it cannot mutate the input.
      *
      * @param model the underlying model
-     * @param slotId the slot id
+     * @param slotId the slot id; must be non-negative (a session is pinned to one concrete slot
+     *     for both inference and {@link #save(String)} / {@link #restore(String)} / {@link #close()})
      * @param systemMessage optional system prompt
      * @param paramsCustomizer applied to each request's parameters; may be {@code null}
+     * @throws IllegalArgumentException if {@code slotId} is negative
      */
     public Session(
             LlamaModel model,
             int slotId,
             @Nullable String systemMessage,
             @Nullable UnaryOperator<InferenceParameters> paramsCustomizer) {
+        // Validate here, not per request: every send()/stream() pins this slot id (see
+        // buildParams), and the slot also backs save()/restore()/close(). A negative id is
+        // meaningless for those, so reject it up front with a clear message rather than letting
+        // InferenceParameters.withSlotId throw on the first inference call.
+        if (slotId < 0) {
+            throw new IllegalArgumentException("slotId must be non-negative, was " + slotId);
+        }
         this.model = model;
         this.slotId = slotId;
         this.state = new SessionState(slotId, systemMessage);

src/main/java/net/ladenthin/llama/value/SlotMetrics.java

@@ -75,15 +75,29 @@ public long getCachedPromptTokens() {
      * @return decoded-token count
      */
     public long getDecodedTokens() {
-        return node.path("next_token").path("n_decoded").asLong(0L);
+        return nextToken().path("n_decoded").asLong(0L);
     }
 
     /**
      * Returns tokens remaining under the current generation limit.
      * @return remaining-token count
      */
     public long getRemainingTokens() {
-        return node.path("next_token").path("n_remain").asLong(0L);
+        return nextToken().path("n_remain").asLong(0L);
+    }
+
+    /**
+     * Resolves the {@code next_token} payload node. llama.cpp's {@code server_slot::to_json}
+     * (b9739) serializes {@code next_token} as a JSON <em>array containing a single object</em>,
+     * so the counters live at {@code next_token[0]}. This unwraps that array; if a bare object
+     * is encountered instead it is used directly, and anything else yields a missing node whose
+     * accessors fall back to their defaults.
+     *
+     * @return the object node carrying {@code n_decoded} / {@code n_remain}, or a missing node
+     */
+    private JsonNode nextToken() {
+        JsonNode next = node.path("next_token");
+        return next.isArray() ? next.path(0) : next;
     }
 
     /**

src/test/java/net/ladenthin/llama/SessionTest.java

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: MIT
+package net.ladenthin.llama;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.containsString;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Model-free unit tests for {@link Session} construction invariants. A session is pinned to one
+ * concrete slot for both inference and {@link Session#save(String)} / {@link Session#restore(String)} /
+ * {@link Session#close()}, so a negative slot id is rejected at construction rather than surfacing
+ * deep inside the first {@code send()} call (where {@code InferenceParameters.withSlotId} would throw).
+ */
+public class SessionTest {
+
+    @Test
+    public void negativeSlotIdRejectedAtConstruction() {
+        // The slot-id guard runs before the model is dereferenced, so a null model still exercises it.
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, () -> new Session(null, -1, null));
+        assertThat(ex.getMessage(), containsString("slotId must be non-negative"));
+    }
+
+    @Test
+    public void negativeSlotIdRejectedOnCustomizerConstructor() {
+        assertThrows(IllegalArgumentException.class, () -> new Session(null, -7, null, p -> p));
+    }
+}

src/test/java/net/ladenthin/llama/value/ServerMetricsTest.java

@@ -5,6 +5,7 @@
 package net.ladenthin.llama.value;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -28,9 +29,11 @@ private ServerMetrics parse(String json) throws Exception {
             + "\"n_prompt_tokens_processed\":10,\"t_prompt_processing\":5,"
             + "\"n_tokens_predicted\":20,\"t_tokens_generation\":8,"
             + "\"n_decode_total\":300,\"n_busy_slots_total\":4,\"n_tokens_max\":4096,"
+            // next_token is an ARRAY of one object — this mirrors llama.cpp's server_slot::to_json
+            // at b9739, not a bare object; SlotMetrics must unwrap next_token[0].
             + "\"slots\":[{\"id\":0,\"n_ctx\":4096,\"is_processing\":true,"
             + "\"n_prompt_tokens\":100,\"n_prompt_tokens_processed\":20,"
-            + "\"n_prompt_tokens_cache\":80,\"next_token\":{\"n_decoded\":7,\"n_remain\":9}},"
+            + "\"n_prompt_tokens_cache\":80,\"next_token\":[{\"n_decoded\":7,\"n_remain\":9}]},"
             + "{\"id\":1}]}";
 
     @Test
@@ -110,6 +113,16 @@ public void typedSlotMetricsExposeCacheCounts() throws Exception {
         assertEquals(9L, slot.getRemainingTokens());
         assertEquals(0, slot.asJson().path("id").asInt());
         assertTrue(slot.toString().contains("n_prompt_tokens_cache"));
+
+        // Assert against the SECOND slot (id=1, no is_processing) so the id and is_processing
+        // accessors are pinned to non-default values a constant-return mutant cannot satisfy:
+        // slot 0's id==0 and is_processing==true coincide with the mutated constants.
+        SlotMetrics idle = m.getSlotMetrics().get(1);
+        assertEquals(1, idle.getId());
+        assertFalse(idle.isProcessing());
+        // next_token absent on the idle slot — accessors fall back to zero, not throw.
+        assertEquals(0L, idle.getDecodedTokens());
+        assertEquals(0L, idle.getRemainingTokens());
     }
 
     @Test