refactor: extract ChatTranscript with two-phase commit semantics from Session

Eliminates the catch-cleanup-rethrow pattern in Session.send and
Session.stream by moving transcript management into a new ChatTranscript
class whose API surface enforces the two-phase commit invariant by
construction.

The catch-rethrow pattern fb-contrib flagged
(THROWS_METHOD_THROWS_RUNTIMEEXCEPTION) was the symptom of
"mutate shared state, then if the call fails, undo the mutation". The
ChatTranscript design eliminates the root cause: there is no API to
commit half a round. The only round-commit method, appendRound(user,
assistant), appends both turns atomically; the wire format sent to the
model is built via messagesWithPendingUserTurn(...) which returns a
fresh list WITHOUT mutating the transcript. On model failure, the
caller never reaches appendRound — no rollback logic is required.

Side benefit — testable as running documentation. Extracting the
transcript management decouples the invariant from LlamaModel (whose
static initializer loads the native library and is unmockable in
test environments without the native library). The new
ChatTranscriptTest exercises the invariant with 12 tests across two
categories:

  @nested "mechanical API behaviour" (8 tests):
    - appendRound commits both turns atomically
    - appendUserTurn + appendAssistantTurn match appendRound
    - messagesWithPendingUserTurn does NOT mutate the transcript
    - messagesWithPendingUserTurn returns a fresh list each call
    - snapshot includes the system message when configured
    - snapshot omits the system message when null or empty
    - snapshot is unmodifiable
    - getSystemMessage returns null when absent

  @nested "two-phase commit pattern - running documentation" (4 tests):
    - fresh transcript untouched when model throws
    - existing transcript byte-for-byte unchanged when model throws
    - success commits user + assistant atomically
    - stream() shape - user turn only, assistant follows via
      commitStreamedReply

Each two-phase test composes the ChatTranscript API the same way
Session.send and Session.stream do, so reading the test doubles as
documentation of the design contract.

Net:
  - New file: src/main/java/net/ladenthin/llama/ChatTranscript.java
  - New file: src/test/java/net/ladenthin/llama/ChatTranscriptTest.java
  - Session.java: 247 lines -> 247 lines (no net change; delegates to
    ChatTranscript). The catch-rethrow blocks are gone; the
    buildParamsWithPendingUserTurn helper now delegates to
    ChatTranscript.messagesWithPendingUserTurn.

SpotBugs Max+Low:
  - THROWS_METHOD_THROWS_RUNTIMEEXCEPTION goes 2 -> 0 by design, not
    by suppression. Cross-repo lifecycle TODO for BAF (PR #4087) can
    take inspiration from this refactor on AbstractProducer.produceKeys
    if/when that two-phase commit fits.
  - IMC_IMMATURE_CLASS_NO_EQUALS goes 2 -> 3 (one new finding on the
    new ChatTranscript class — identity-by-design like the existing
    CancellationToken and ChatRequest sites; will fold into the
    existing class-level suppression block).
Total jllama: 13 -> 12.

Test slice green: 117 tests across ChatTranscriptTest (12),
ChatMessageTest (2), ChatResponseTest (7), InferenceParametersTest
(86), LlamaArchitectureTest (10).

Author: claude

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

@@ -0,0 +1,162 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: MIT
+
+package net.ladenthin.llama;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import lombok.ToString;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Append-only transcript of a multi-turn chat conversation, with an optional
+ * leading {@code system} message. Extracted from {@link Session} so the
+ * transcript invariants — especially the <b>two-phase commit</b> shape — are
+ * testable independently of {@link LlamaModel} and its native library.
+ *
+ * <h2>Two-phase commit invariant</h2>
+ *
+ * <p>The append API only offers <b>atomic</b> turn commits:
+ *
+ * <ul>
+ *   <li>{@link #appendRound(String, String)} appends a user turn AND an
+ *       assistant turn in one synchronised operation — used by
+ *       {@link Session#send(String)} on the model-success path. There is no
+ *       way to commit only one half: if the model call throws, this method
+ *       is simply never called and the transcript is untouched.</li>
+ *   <li>{@link #appendUserTurn(String)} appends only the user turn — used
+ *       by {@link Session#stream(String)} when the streaming iterable has
+ *       been successfully created but the assistant reply is still being
+ *       accumulated. The matching assistant turn is appended later via
+ *       {@link #appendAssistantTurn(String)}.</li>
+ * </ul>
+ *
+ * <p>The wire-format the model sees is built by
+ * {@link #messagesWithPendingUserTurn(String)}, which returns a fresh list
+ * containing the committed turns plus a pending user turn — <b>without
+ * mutating</b> the underlying transcript. This is the mechanism by which the
+ * model receives the prompt before the user turn is committed.
+ *
+ * <h2>Thread safety</h2>
+ *
+ * <p>This class is <b>not</b> internally synchronised. {@link Session} owns
+ * the single instance and serialises access via its intrinsic lock, so the
+ * transcript itself does not need additional synchronisation. Callers that
+ * use {@code ChatTranscript} directly must provide their own synchronisation
+ * if shared across threads.
+ *
+ * <h2>{@code toString} contract</h2>
+ *
+ * <p>Lombok-generated over the system message and turns list. The turns list
+ * IS included because it is the operationally interesting state for log
+ * traces. {@code equals}/{@code hashCode} are intentionally NOT generated:
+ * a transcript instance is identified by its lifecycle owner ({@link Session}),
+ * not by its accumulated content.
+ */
+@ToString
+final class ChatTranscript {
+
+    private final @Nullable String systemMessage;
+    private final List<Pair<String, String>> turns = new ArrayList<Pair<String, String>>();
+
+    /**
+     * Create a new empty transcript with an optional system message.
+     *
+     * @param systemMessage the system prompt to prepend to every wire-format
+     *     prompt; {@code null} or empty means "no system message"
+     */
+    ChatTranscript(@Nullable String systemMessage) {
+        this.systemMessage = systemMessage;
+    }
+
+    /**
+     * Append a user turn AND an assistant turn atomically. This is the only
+     * API that records both halves of a round, so the two-phase commit
+     * invariant is enforced by construction: callers that observe a model
+     * call failure simply never invoke this method.
+     *
+     * @param userMessage the user turn
+     * @param assistantMessage the assistant reply that completes the round
+     */
+    void appendRound(String userMessage, String assistantMessage) {
+        turns.add(new Pair<String, String>("user", userMessage));
+        turns.add(new Pair<String, String>("assistant", assistantMessage));
+    }
+
+    /**
+     * Append a user turn. Used by streaming flows where the assistant reply
+     * is accumulated incrementally and committed later via
+     * {@link #appendAssistantTurn(String)}.
+     *
+     * @param userMessage the user turn
+     */
+    void appendUserTurn(String userMessage) {
+        turns.add(new Pair<String, String>("user", userMessage));
+    }
+
+    /**
+     * Append an assistant turn. Used to complete a round that was begun
+     * with {@link #appendUserTurn(String)}.
+     *
+     * @param assistantMessage the assistant reply
+     */
+    void appendAssistantTurn(String assistantMessage) {
+        turns.add(new Pair<String, String>("assistant", assistantMessage));
+    }
+
+    /**
+     * Build the wire-format messages list with a pending user turn appended,
+     * <b>without mutating</b> this transcript. This is the snapshot a model
+     * call receives before the user turn is committed; if the model call
+     * fails, the pending turn evaporates and the transcript stays untouched.
+     *
+     * @param pendingUserMessage the user turn to include in the wire format
+     * @return a fresh list containing the committed turns followed by the
+     *     pending user turn
+     */
+    List<Pair<String, String>> messagesWithPendingUserTurn(String pendingUserMessage) {
+        List<Pair<String, String>> wire = new ArrayList<Pair<String, String>>(turns.size() + 1);
+        wire.addAll(turns);
+        wire.add(new Pair<String, String>("user", pendingUserMessage));
+        return wire;
+    }
+
+    /**
+     * Return the system message, or {@code null} when none was configured.
+     *
+     * @return the system prompt, or {@code null}
+     */
+    @Nullable
+    String getSystemMessage() {
+        return systemMessage;
+    }
+
+    /**
+     * Return an unmodifiable {@link ChatMessage} snapshot of the transcript,
+     * including the system message if one was configured.
+     *
+     * @return the unmodifiable snapshot
+     */
+    List<ChatMessage> snapshot() {
+        List<ChatMessage> out = new ArrayList<ChatMessage>(turns.size() + 1);
+        if (systemMessage != null && !systemMessage.isEmpty()) {
+            out.add(new ChatMessage("system", systemMessage));
+        }
+        for (Pair<String, String> p : turns) {
+            out.add(new ChatMessage(p.getKey(), p.getValue()));
+        }
+        return Collections.unmodifiableList(out);
+    }
+
+    /**
+     * Return the number of committed turns (user + assistant). Does NOT
+     * include the system message.
+     *
+     * @return the turn count
+     */
+    int size() {
+        return turns.size();
+    }
+}

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

@@ -4,8 +4,6 @@
 
 package net.ladenthin.llama;
 
-import java.util.ArrayList;
-import java.util.Collections;
 import java.util.List;
 import java.util.function.Consumer;
 import lombok.ToString;
@@ -45,8 +43,14 @@ public final class Session implements AutoCloseable {
     private final LlamaModel model;
 
     private final int slotId;
-    private final @Nullable String systemMessage;
-    private final List<Pair<String, String>> turns = new ArrayList<Pair<String, String>>();
+
+    /**
+     * Append-only transcript with two-phase commit semantics. See the
+     * {@link ChatTranscript} class Javadoc for the full invariant statement
+     * and the {@code ChatTranscriptTest} class for the running-documentation
+     * tests that pin the contract.
+     */
+    private final ChatTranscript transcript;
 
     // Lambda Consumer — toString is the implementation hash, not useful in logs.
     @ToString.Exclude
@@ -86,7 +90,7 @@ public Session(
             @Nullable Consumer<InferenceParameters> paramsCustomizer) {
         this.model = model;
         this.slotId = slotId;
-        this.systemMessage = systemMessage;
+        this.transcript = new ChatTranscript(systemMessage);
         this.paramsCustomizer = paramsCustomizer;
     }
 
@@ -101,19 +105,18 @@ public String send(String userMessage) {
             if (streamingActive) {
                 throw new IllegalStateException(
                         "stream in progress on slot " + slotId
-                                + " (transcript=" + turns.size() + " turns)"
+                                + " (transcript=" + transcript.size() + " turns)"
                                 + "; call commitStreamedReply(...) before send(...)");
             }
-            turns.add(new Pair<String, String>("user", userMessage));
-            InferenceParameters params = buildParams();
-            try {
-                String reply = model.chatCompleteText(params);
-                turns.add(new Pair<String, String>("assistant", reply));
-                return reply;
-            } catch (RuntimeException e) {
-                turns.remove(turns.size() - 1);
-                throw e;
-            }
+            // Two-phase commit: build the wire-format with the pending user turn
+            // outside the transcript via messagesWithPendingUserTurn(...). On
+            // model success, commit BOTH turns atomically through appendRound(...).
+            // On model failure, nothing was committed — no rollback logic needed.
+            // Invariant pinned by ChatTranscriptTest.
+            InferenceParameters params = buildParamsWithPendingUserTurn(userMessage);
+            String reply = model.chatCompleteText(params);
+            transcript.appendRound(userMessage, reply);
+            return reply;
         }
     }
 
@@ -131,18 +134,16 @@ public LlamaIterable stream(String userMessage) {
             if (streamingActive) {
                 throw new IllegalStateException(
                         "stream in progress on slot " + slotId
-                                + " (transcript=" + turns.size() + " turns)"
+                                + " (transcript=" + transcript.size() + " turns)"
                                 + "; call commitStreamedReply(...) before stream(...)");
             }
-            turns.add(new Pair<String, String>("user", userMessage));
-            try {
-                LlamaIterable iterable = model.generateChat(buildParams());
-                streamingActive = true;
-                return iterable;
-            } catch (RuntimeException e) {
-                turns.remove(turns.size() - 1);
-                throw e;
-            }
+            // Two-phase commit: see send(). The user turn is committed only after
+            // generateChat successfully returns the iterable; the assistant turn is
+            // committed separately by commitStreamedReply(...).
+            LlamaIterable iterable = model.generateChat(buildParamsWithPendingUserTurn(userMessage));
+            transcript.appendUserTurn(userMessage);
+            streamingActive = true;
+            return iterable;
         }
     }
 
@@ -157,10 +158,10 @@ public void commitStreamedReply(String assistantText) {
             if (!streamingActive) {
                 throw new IllegalStateException(
                         "no stream in progress on slot " + slotId
-                                + " (transcript=" + turns.size() + " turns)"
+                                + " (transcript=" + transcript.size() + " turns)"
                                 + "; call stream(...) first");
             }
-            turns.add(new Pair<String, String>("assistant", assistantText));
+            transcript.appendAssistantTurn(assistantText);
             streamingActive = false;
         }
     }
@@ -176,7 +177,7 @@ public String save(String filepath) {
             if (streamingActive) {
                 throw new IllegalStateException(
                         "stream in progress on slot " + slotId
-                                + " (transcript=" + turns.size() + " turns)"
+                                + " (transcript=" + transcript.size() + " turns)"
                                 + "; call commitStreamedReply(...) before save(...)");
             }
             return model.saveSlot(slotId, filepath);
@@ -194,7 +195,7 @@ public String restore(String filepath) {
             if (streamingActive) {
                 throw new IllegalStateException(
                         "stream in progress on slot " + slotId
-                                + " (transcript=" + turns.size() + " turns)"
+                                + " (transcript=" + transcript.size() + " turns)"
                                 + "; call commitStreamedReply(...) before restore(...)");
             }
             return model.restoreSlot(slotId, filepath);
@@ -207,14 +208,7 @@ public String restore(String filepath) {
      */
     public List<ChatMessage> getMessages() {
         synchronized (lock) {
-            List<ChatMessage> out = new ArrayList<ChatMessage>(turns.size() + 1);
-            if (systemMessage != null && !systemMessage.isEmpty()) {
-                out.add(new ChatMessage("system", systemMessage));
-            }
-            for (Pair<String, String> p : turns) {
-                out.add(new ChatMessage(p.getKey(), p.getValue()));
-            }
-            return Collections.unmodifiableList(out);
+            return transcript.snapshot();
         }
     }
 
@@ -226,9 +220,21 @@ public void close() {
         }
     }
 
-    private InferenceParameters buildParams() {
-        InferenceParameters params =
-                new InferenceParameters("").setMessages(systemMessage, new ArrayList<Pair<String, String>>(turns));
+    /**
+     * Build inference parameters with a pending user turn appended to the existing
+     * transcript — without mutating the underlying {@link ChatTranscript}. The
+     * actual transcript mutation happens AFTER the model call returns successfully,
+     * either via {@link ChatTranscript#appendRound(String, String)} (send path)
+     * or {@link ChatTranscript#appendUserTurn(String)} (stream path).
+     *
+     * @param pendingUserMessage the user turn to include in the wire format
+     * @return inference parameters carrying transcript + pending user turn
+     */
+    private InferenceParameters buildParamsWithPendingUserTurn(String pendingUserMessage) {
+        InferenceParameters params = new InferenceParameters("")
+                .setMessages(
+                        transcript.getSystemMessage(),
+                        transcript.messagesWithPendingUserTurn(pendingUserMessage));
         if (paramsCustomizer != null) {
             paramsCustomizer.accept(params);
         }