fix(slot-metrics): unwrap next_token array + guard Session slot id

Follow-up to PR #251 (session slot pinning + KV-cache observability).

- SlotMetrics.getDecodedTokens()/getRemainingTokens() read next_token.n_decoded
  / n_remain directly, but llama.cpp's server_slot::to_json (b9739) serializes
  next_token as a JSON array containing a single object, so both accessors
  silently returned 0 against a live server. Unwrap next_token[0] (tolerating a
  bare object defensively). The ServerMetricsTest fixture used the wrong (object)
  shape and masked this; it now uses the real array shape.

- Session rejected a negative slot id only indirectly: every send()/stream()
  pins the slot via InferenceParameters.withSlotId, which throws on a negative
  id, so a Session built with a negative slot failed deep inside the first call.
  Validate slotId >= 0 at construction instead (the slot also backs
  save/restore/close), and cover it with a model-free SessionTest.

- Strengthen the typed-slot test to assert id/is_processing on the second
  (idle) slot so constant-return mutants can no longer survive; PIT mutation
  coverage for SlotMetrics is back to 100% (228/228).

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

Author: claude

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