temporal-spring-ai: reframe replay-test messages around plugin behavior

Reviewer pointed out that "ChatModel must not be re-invoked during replay"
reads as testing Temporal's activity replay guarantee rather than the
plugin's behavior. Reword class-level javadoc and assertion messages so
the property under test is explicit: the plugin places ChatModel calls,
activity-stub tool calls, and @SideEffectTool bodies behind the correct
Temporal boundary. Temporal's replay/memoization semantics are assumed
correct. The counter-stays-at-1 observation is the signal we use to
detect a plugin regression, not the thing being tested.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: donald-pinckney

temporal-spring-ai/src/test/java/io/temporal/springai/replay/ActivityToolSideEffectTest.java

@@ -35,10 +35,15 @@
 import org.springframework.ai.tool.annotation.Tool;
 
 /**
- * Asserts that a workflow replay does not re-invoke activity-backed tools. The {@link AddActivity}
- * impl holds a counter that increments on each tool call. After the initial run the counter is 1;
- * after replaying the captured history, it must still be 1 — activity results for the tool call
- * come from history, not from re-invoking the activity impl.
+ * Asserts that {@link TemporalChatClient#defaultTools} routes activity-stub tools through the
+ * activity boundary the user already set up (via {@code Workflow.newActivityStub}) rather than
+ * invoking the underlying impl directly from workflow code. This is a plugin property: the plugin
+ * must recognize the stub as an activity-backed tool and invoke it as such, not unwrap it into a
+ * plain in-workflow Java method call. Temporal's replay semantics for activities are assumed
+ * correct.
+ *
+ * <p>If the plugin regressed to invoking a stub's backing impl directly, replay would re-run that
+ * call and the counter would exceed 1.
  */
 class ActivityToolSideEffectTest {
 
@@ -82,7 +87,9 @@ void activityTool_notReInvokedOnReplay() throws Exception {
             WorkflowOptions.newBuilder().setTaskQueue(TASK_QUEUE).build());
     assertEquals("The answer is 5", workflow.chat("What is 2+3?"));
     assertEquals(
-        1, addActivity.callCount.get(), "Tool activity should run once during the initial run");
+        1,
+        addActivity.callCount.get(),
+        "sanity check: the tool activity impl ran exactly once for one workflow invocation");
 
     WorkflowExecutionHistory history =
         client.fetchHistory(WorkflowStub.fromTyped(workflow).getExecution().getWorkflowId());
@@ -91,7 +98,9 @@ void activityTool_notReInvokedOnReplay() throws Exception {
     assertEquals(
         1,
         addActivity.callCount.get(),
-        "Tool activity must not be re-invoked during replay — results come from history");
+        "TemporalChatClient must invoke activity-stub tools as activities; a counter above 1"
+            + " means the plugin unwrapped the stub and called the impl directly from workflow"
+            + " code");
   }
 
   @WorkflowInterface

temporal-spring-ai/src/test/java/io/temporal/springai/replay/ChatModelSideEffectTest.java

@@ -28,12 +28,17 @@
 import org.springframework.ai.chat.prompt.Prompt;
 
 /**
- * Asserts that a workflow replay does not re-invoke the underlying {@link ChatModel}. The counter
- * lives on the activity's backing ChatModel, which is only reached when the {@code CallChatModel}
- * activity is scheduled by the workflow. On replay, the activity result is fetched from history;
- * the impl is not re-invoked. If we ever regress by dropping that guarantee — say by adding an
- * in-workflow cache that falls back to invoking the model directly — the counter will advance to 2
- * and this test will fail.
+ * Asserts that {@link ActivityChatModel} routes every {@link ChatModel} invocation through an
+ * activity boundary rather than calling the underlying {@code ChatModel} directly from workflow
+ * code. This is a property of the plugin, not of Temporal: Temporal guarantees activity results are
+ * replayed from history, but that only helps if the plugin actually scheduled an activity in the
+ * first place.
+ *
+ * <p>Concretely, if a regression routed chat calls directly (e.g. an in-workflow cache whose miss
+ * path invokes the {@code ChatModel} inline), replay would re-run that inline call and the counter
+ * would advance past 1. Caching is disabled in {@link #setUp()} so the worker replays on every
+ * workflow task — making this failure mode observable during the initial run, not only via the
+ * explicit {@code WorkflowReplayer} pass.
  */
 class ChatModelSideEffectTest {
 
@@ -76,7 +81,9 @@ void chatModel_notReInvokedOnReplay() throws Exception {
             ChatWorkflow.class, WorkflowOptions.newBuilder().setTaskQueue(TASK_QUEUE).build());
     assertEquals("pong", workflow.chat("ping"));
     assertEquals(
-        1, model.callCount.get(), "ChatModel should be called once during the initial run");
+        1,
+        model.callCount.get(),
+        "sanity check: the ChatModel ran exactly once for one workflow invocation");
 
     WorkflowExecutionHistory history =
         client.fetchHistory(WorkflowStub.fromTyped(workflow).getExecution().getWorkflowId());
@@ -85,7 +92,9 @@ void chatModel_notReInvokedOnReplay() throws Exception {
     assertEquals(
         1,
         model.callCount.get(),
-        "ChatModel must not be re-invoked during replay — activity results come from history");
+        "ActivityChatModel must place ChatModel calls behind an activity boundary; a counter"
+            + " above 1 means the plugin invoked the ChatModel directly from workflow code"
+            + " and replay re-ran it");
   }
 
   @WorkflowInterface

temporal-spring-ai/src/test/java/io/temporal/springai/replay/SideEffectToolReplayTest.java

@@ -31,14 +31,15 @@
 import org.springframework.ai.tool.annotation.Tool;
 
 /**
- * Asserts that {@code Workflow.sideEffect(...)} memoization works for {@link SideEffectTool}
- * bodies. Unlike activity-backed tools, the {@code SideEffectToolCallback} wrapper runs on the
- * workflow side, so <em>every</em> workflow statement re-runs during replay — including the call
- * into {@code SideEffectToolCallback.call()}. What must NOT re-run is the inner tool body (the
- * lambda passed to {@code Workflow.sideEffect}); that result is fetched from the recorded marker.
+ * Asserts that the plugin's {@link SideEffectTool} callback actually wraps the user's {@code @Tool}
+ * method body in {@code Workflow.sideEffect(...)}. This is a plugin property: the {@code
+ * SideEffectToolCallback} itself runs on the workflow side and gets re-entered on every replay, so
+ * if the callback were to invoke the tool body directly instead of via {@code Workflow.sideEffect},
+ * the body would run again on each replay. Temporal's memoization of {@code sideEffect} markers is
+ * assumed correct.
  *
- * <p>A regression that dropped the sideEffect wrapper (e.g., directly invoking the delegate) would
- * bump this counter to 2 on replay.
+ * <p>A regression that drops the {@code Workflow.sideEffect} wrap (calling the delegate directly)
+ * would bump this counter past 1.
  */
 class SideEffectToolReplayTest {
 
@@ -83,7 +84,9 @@ void sideEffectTool_notReInvokedOnReplay() throws Exception {
             TimestampWorkflow.class, WorkflowOptions.newBuilder().setTaskQueue(TASK_QUEUE).build());
     assertEquals("got: 2026-04-21T00:00:00Z", workflow.chat("what time is it?"));
     assertEquals(
-        1, CALL_COUNT.get(), "@SideEffectTool body should run once during the initial run");
+        1,
+        CALL_COUNT.get(),
+        "sanity check: the @SideEffectTool body ran exactly once for one workflow invocation");
 
     WorkflowExecutionHistory history =
         client.fetchHistory(WorkflowStub.fromTyped(workflow).getExecution().getWorkflowId());
@@ -92,8 +95,8 @@ void sideEffectTool_notReInvokedOnReplay() throws Exception {
     assertEquals(
         1,
         CALL_COUNT.get(),
-        "@SideEffectTool body must not re-run on replay — result comes from the recorded"
-            + " sideEffect marker");
+        "SideEffectToolCallback must wrap the @Tool body in Workflow.sideEffect; a counter above"
+            + " 1 means the plugin invoked the tool body directly and replay re-ran it");
   }
 
   @WorkflowInterface