Merge pull request #28 from CajunSystems/claude/review-effect-monad-docs-01MUVnR8rmRYVYJBXbtMfn9X

Author: contrasam

CHANGELOG.md

@@ -30,7 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Documentation**: Complete guide with examples, best practices, and use cases
 
 - **Effect Monad for Functional Actors**: Complete functional programming API for actor behaviors
-  - **Stack-Safe**: Uses Trampoline for unbounded effect composition without stack overflow
+  - **Stack-Safe**: Unbounded effect composition without stack overflow (chain thousands of operations)
   - **Type-Safe Error Handling**: `Effect<State, Error, Result>` with explicit error channel
   - **Composable Operations**: `map`, `flatMap`, `andThen`, `filter`, `recover`, `zip`, `parZip`
   - **Request-Response Pattern**: `Effect.ask(pid, message, timeout)` for actor communication

README.md

@@ -986,7 +986,7 @@ counter.tell(new Increment(5));
 #### Why Use Effects?
 
 - **Composable**: Build complex behaviors from simple building blocks
-- **Stack-Safe**: Uses Trampoline pattern to prevent stack overflow on deep compositions
+- **Stack-Safe**: Prevents stack overflow on deep compositions (chain thousands of operations safely)
 - **🚀 Blocking is Safe**: Cajun runs on Java 21+ Virtual Threads - write normal blocking code without fear!
   - No `CompletableFuture` chains or async/await complexity
   - Database calls, HTTP requests, file I/O - just write them naturally

docs/effect_monad_api.md

@@ -6,7 +6,7 @@ The Effect monad provides a composable, type-safe, **stack-safe** way to build a
 
 ## Key Features
 
-- **Stack-Safe** - Uses Trampoline pattern to prevent stack overflow on deep compositions
+- **Stack-Safe** - Prevents stack overflow on deep compositions (chain thousands of operations safely)
 - **Simplified Type Signature** - `Effect<State, Error, Result>` with Message type at match level
 - **Idiomatic Java naming** - Uses `.of()` instead of `.pure()`, familiar to Java developers
 - **Composable** - Build complex behaviors from simple building blocks
@@ -56,11 +56,10 @@ An `Effect` represents a **stack-safe** computation that:
 - May produce a **result** value
 - May perform **side effects** (logging, sending messages, etc.)
 - May **fail** with an **error** of type `Error` (typically `Throwable`)
-- Returns a `Trampoline<EffectResult<State, Result>>` for stack safety
 
 **Key Changes from Previous Version:**
 - Message type moved from interface to `match()` method
-- All operations return `Trampoline` for stack-safe execution
+- Stack-safe execution for deep compositions
 - Explicit `Error` type parameter for better type safety
 
 ### EffectResult<State, Result>

docs/effect_monad_guide.md

@@ -105,10 +105,9 @@ counter.tell(new Increment(5));
 
 1. **Message Queued**: The message enters the actor's mailbox (a queue)
 2. **Actor Wakes Up**: The actor's virtual thread picks up the message
-3. **Effect Executes**: The effect's runT() method is called with current state, message, and context
-4. **Trampoline Runs**: The effect returns a Trampoline which is immediately evaluated
-5. **State Updated**: If successful, the actor's state is updated
-6. **Next Message**: The actor processes the next message in the mailbox
+3. **Effect Executes**: The effect runs with current state, message, and context
+4. **State Updated**: If successful, the actor's state is updated
+5. **Next Message**: The actor processes the next message in the mailbox
 
 ### Key Insights
 
@@ -1062,7 +1061,7 @@ Effect<Int, Throwable, String> effect =
 // When the actor runs the effect, it executes immediately
 EffectResult<Int, String> result = effect.run(state, message, context);
 
-// The trampoline ensures stack safety, but execution is eager:
+// Execution is eager and stack-safe:
 // 1. modify runs
 // 2. log runs
 // 3. map runs
@@ -1074,7 +1073,7 @@ EffectResult<Int, String> result = effect.run(state, message, context);
 1. **Effects are values** - You can store them, pass them around, compose them
 2. **Composition is lazy** - Chaining effects doesn't execute them
 3. **Execution is eager** - Once `run()` is called, the effect runs to completion
-4. **Trampolining is transparent** - Stack safety doesn't change eager semantics
+4. **Stack safety is transparent** - You can chain thousands of operations without worry
 
 ### Suspended Computations
 

docs/throwable_effect_api.md

@@ -2,12 +2,12 @@
 
 ## Overview
 
-`ThrowableEffect<State, Result>` is a simplified, stack-safe alternative to `Effect<State, Message, Result>`. It removes the Message type parameter, making the API less verbose while maintaining full functionality through the use of a `Trampoline` for stack safety.
+`ThrowableEffect<State, Result>` is a simplified, stack-safe alternative to `Effect<State, Message, Result>`. It removes the Message type parameter, making the API less verbose while maintaining full stack-safe functionality.
 
 ## Key Features
 
 - **Less Verbose** - Only 2 type parameters instead of 3
-- **Stack-Safe** - Uses `Trampoline` to prevent StackOverflowError on deep compositions
+- **Stack-Safe** - Prevents StackOverflowError on deep compositions (chain thousands of operations safely)
 - **Built-in Error Channel** - Throwable handling is part of the type
 - **Message Type at Match** - Type constraint only where needed
 - **Fully Compatible** - All operators from Effect are available
@@ -64,10 +64,10 @@ ThrowableEffect<Integer, String> effect = ThrowableEffect.fail(new RuntimeExcept
 
 ## Stack Safety
 
-The key innovation of `ThrowableEffect` is its use of `Trampoline` for stack-safe evaluation:
+`ThrowableEffect` is designed to handle deep effect compositions without stack overflow:
 
 ```java
-// This would cause StackOverflowError with regular Effect
+// Chain thousands of operations safely
 ThrowableEffect<Integer, Integer> effect = ThrowableEffect.of(0);
 
 for (int i = 0; i < 10000; i++) {
@@ -78,22 +78,7 @@ for (int i = 0; i < 10000; i++) {
 EffectResult<Integer, Integer> result = effect.run(0, msg, context);
 ```
 
-### How It Works
-
-Instead of eagerly evaluating compositions, `ThrowableEffect` returns a `Trampoline` that describes the computation:
-
-```java
-@FunctionalInterface
-public interface ThrowableEffect<S, R> {
-    // Returns a Trampoline for lazy, stack-safe evaluation
-    Trampoline<EffectResult<S, R>> runT(S state, Object message, ActorContext context);
-    
-    // Convenience method that runs the trampoline
-    default EffectResult<S, R> run(S state, Object message, ActorContext context) {
-        return runT(state, message, context).run();
-    }
-}
-```
+This means you can build complex effect pipelines by composing many operations together without worrying about stack depth limitations.
 
 ## Monadic Operations
 
@@ -201,41 +186,12 @@ ThrowableEffect<Integer, Void> counter = ThrowableEffect.<Integer>match()
     .when(Decrement.class, (state, msg, ctx) -> 
         ThrowableEffect.modify(s -> s - msg.amount())
     )
-    .when(GetCount.class, (state, msg, ctx) -> 
-        ThrowableEffect.<Integer, Void>state()
-            .andThen((state2, msg2, ctx2) -> {
-                msg.replyTo().tell(state2);
-                return Trampoline.done(EffectResult.noResult(state2));
-            })
+    .when(GetCount.class, (state, msg, ctx) ->
+        ThrowableEffect.tell(msg.replyTo(), state)
     )
     .build();
 ```
 
-## Trampoline API
-
-The `Trampoline` data structure enables stack-safe recursion:
-
-```java
-// Create a completed trampoline
-Trampoline<Integer> done = Trampoline.done(42);
-
-// Suspend a computation
-Trampoline<Integer> suspended = Trampoline.more(() -> 
-    Trampoline.done(42)
-);
-
-// Delay a computation
-Trampoline<Integer> delayed = Trampoline.delay(() -> expensiveComputation());
-
-// Map and flatMap are stack-safe
-Trampoline<Integer> result = trampoline
-    .map(x -> x * 2)
-    .flatMap(x -> Trampoline.done(x + 10));
-
-// Run the trampoline
-Integer value = result.run();  // Iterative evaluation - no stack growth
-```
-
 ## When to Use ThrowableEffect vs Effect
 
 ### Use ThrowableEffect When:
@@ -266,7 +222,7 @@ ThrowableEffect<State, Result> newEffect = ...;
 ## Performance
 
 - **Stack Safety**: Prevents StackOverflowError for deep compositions
-- **Overhead**: Minimal - trampoline adds one level of indirection
+- **Overhead**: Minimal - negligible performance cost for stack safety
 - **Parallel Operations**: Same performance as Effect (uses CompletableFuture)
 - **Memory**: Slightly lower than Effect (one less type parameter)
 
@@ -281,21 +237,12 @@ ThrowableEffect<State, Result> newEffect = ...;
    ThrowableEffect.modify(s -> s)
    ```
 
-2. **Prefer `filterOrElse()` over manual validation**
+2. **Use `filterOrElse()` for conditional validation**
    ```java
-   // Good
    effect.filterOrElse(
        s -> s.isValid(),
        fallbackEffect
    )
-   
-   // Manual
-   effect.andThen((s, m, c) -> {
-       if (!s.isValid()) {
-           return fallbackEffect.runT(s, m, c);
-       }
-       return Trampoline.done(EffectResult.noResult(s));
-   })
    ```
 
 3. **Use `attempt()` for exception-prone operations**
@@ -316,4 +263,4 @@ ThrowableEffect<State, Result> newEffect = ...;
 
 ## Summary
 
-`ThrowableEffect` provides a cleaner, stack-safe API for building functional actors in Cajun. Its simplified type signature and built-in trampoline make it ideal for complex effect compositions while maintaining full compatibility with the existing Effect ecosystem.
+`ThrowableEffect` provides a cleaner, stack-safe API for building functional actors in Cajun. Its simplified type signature makes it ideal for complex effect compositions while maintaining full compatibility with the existing Effect ecosystem.