mino_pcall: expose raw thrown value; STM propagates validator throws

Two coupled changes follow on from the previous pcall catch-arm fix:

1. mino_pcall's signature gains an out_ex parameter. When the call
   throws, *out_ex receives the raw thrown value (the cell passed to
   (throw ...) -- typically an ex-info map or similar payload).
   Callers like agent dispatch and STM validator handling that want
   to surface the user's exception unchanged read from out_ex
   directly. Breaking ABI change for existing pcall callers; mino
   is alpha so no compat shim.

2. The agent code's agent_try_call workaround is removed.
   agent.c now calls mino_pcall(..., &new_state, &thrown_ex) for
   actions, validators, and watches, getting the same exception
   capture in 1 line where agent_try_call took 30. The custom try
   frame is gone.

3. run_ref_validator in stm.c uses out_ex, threading the captured
   exception through tx_state_t's new validator_thrown_ex slot.
   tx_commit sets validator_rejected for both throws and falsy-
   rejects (both are hard failures, distinct from read-set-
   conflict retries) and parks the captured exception on tx.
   dosync_run consumes it: if validator_thrown_ex is set, it
   propagates the user's original payload via mino_throw;
   otherwise it raises the canonical MCT001 "Invalid reference
   state".

   Net behavior change: a validator that throws now aborts the
   transaction with the validator's own exception (matching JVM
   Clojure's "propagate the validator's exception" semantic). The
   previous code retried until the retry cap and then threw
   MST004 "transaction retry limit exceeded".

GC: tx->validator_thrown_ex is traced in gc_mark_ctx_tx so the
captured exception stays reachable across collections that may
fire between commit and dosync_run's re-throw.

tests/stm_test.clj covers both cases:
- validator-throw-propagates-original-exception checks that
  (ex-data e) returns the original ex-info data.
- validator-falsy-reject-throws-MCT001 pins the falsy-reject path.

Internal suite 1514 / 7171 / 0. External baseline unchanged. The
upstream add_watch.cljc / remove_watch.cljc agent arms still pass
cleanly.

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

Author: leifericf

CHANGELOG.md

@@ -394,6 +394,56 @@ The agent code's `agent_try_call` workaround (added in E.4) is
 left in place by this commit; the follow-up replaces it with a
 direct `mino_pcall` call now that the catch arm is well-behaved.
 
+### `mino_pcall` exposes the raw thrown value; STM validator throws propagate
+
+Two coupled changes follow on from the catch-arm fix:
+
+`mino_pcall`'s signature gains an `out_ex` parameter:
+
+```c
+int mino_pcall(mino_state_t *S, mino_val_t *fn, mino_val_t *args,
+               mino_env_t *env,
+               mino_val_t **out, mino_val_t **out_ex);
+```
+
+When the call throws, `*out_ex` receives the raw thrown value (the
+cell passed to `(throw ...)` -- typically an `ex-info` map or
+similar payload). Callers like agent dispatch and STM validator
+handling that want to surface the user's exception unchanged read
+from `out_ex` directly. **Breaking ABI change: existing pcall
+callers need to add the extra parameter (NULL is fine if the value
+isn't needed).** mino is alpha; no compat shim.
+
+The agent code's `agent_try_call` workaround is removed:
+`src/prim/agent.c` now calls `mino_pcall(...&new_state, &thrown_ex)`
+for actions, validators, and watches, getting the same exception
+capture in 1 line where `agent_try_call` took 30. The custom try
+frame is gone.
+
+`run_ref_validator` in `src/prim/stm.c` likewise uses `out_ex`,
+threading the captured exception through `tx_state_t`'s new
+`validator_thrown_ex` slot. `tx_commit` sets the
+`validator_rejected` flag for both throws and falsy-rejects (both
+are hard failures, distinct from read-set-conflict retries) and
+parks the captured exception on `tx`. `dosync_run` consumes it: if
+`validator_thrown_ex` is set, it propagates the user's original
+payload via `mino_throw`; otherwise it raises the canonical
+`MCT001 "Invalid reference state"`.
+
+Net behavior: a validator that throws now aborts the transaction
+with the validator's own exception (matching JVM Clojure's
+"propagate the validator's exception" semantic), where the
+previous code retried until the cap and then threw `MST004
+"transaction retry limit exceeded"`. A validator that returns
+falsy without throwing still produces `MCT001`.
+
+`tests/stm_test.clj` covers both cases:
+`validator-throw-propagates-original-exception` checks that
+`(ex-data e)` returns the original ex-info data; the new
+`validator-falsy-reject-throws-MCT001` pins the falsy-reject path.
+
+Internal suite 1514 / 7171 / 0.
+
 ### Agents (MVP)
 
 mino now ships agents: `agent`, `agent?`, `send`, `send-off`,

src/gc/roots.c

@@ -315,6 +315,7 @@ static void gc_mark_ctx_tx(mino_state_t *S, mino_thread_ctx_t *ctx)
         gc_mark_interior(S, rs->committed_old);
         gc_mark_interior(S, rs->committed_new);
     }
+    gc_mark_interior(S, tx->validator_thrown_ex);
 }
 
 /* Pin lexical environments published as GC roots and the symbol/keyword

src/mino.h

@@ -1025,12 +1025,19 @@ mino_val_t *mino_call(mino_state_t *S, mino_val_t *fn, mino_val_t *args,
                       mino_env_t *env);
 
 /*
- * Protected call: same as mino_call but returns 0 on success (writing the
- * result to *out) or -1 on error. The error message is available via
- * mino_last_error(). *out is set to NULL on error.
+ * Protected call: same as mino_call but returns 0 on success (writing
+ * the result to *out) or -1 on error. The error message is available
+ * via mino_last_error(). *out is set to NULL on error.
+ *
+ * If out_ex is non-NULL, on error *out_ex is set to the raw thrown
+ * exception value (the cell passed to (throw ...) by the inner code).
+ * This is the original payload, not a diagnostic map -- useful for
+ * captures-and-stores callers like agent dispatch and STM validator
+ * handling that want to surface the user's ex-info / map / etc.
+ * unchanged. *out_ex is set to NULL on success or if out_ex is NULL.
  */
 int mino_pcall(mino_state_t *S, mino_val_t *fn, mino_val_t *args,
-               mino_env_t *env, mino_val_t **out);
+               mino_env_t *env, mino_val_t **out, mino_val_t **out_ex);
 
 /* ------------------------------------------------------------------------- */
 /* Exceptions                                                                */

src/prim/agent.c

@@ -5,7 +5,8 @@
  * thread. JVM Clojure dispatches the action on a worker thread pool
  * and returns the agent immediately; mino runs the action eagerly,
  * validates against the agent's validator, captures any throw into
- * the agent's error slot, dispatches watches, and returns the agent.
+ * the agent's error slot via mino_pcall's out_ex parameter, dispatches
+ * watches, and returns the agent.
  *
  * Why sync: mino's eval loop is serialized under a per-state mutex
  * (mino_state_lock_acquire). A future-driven worker would acquire
@@ -35,56 +36,8 @@
 #include "prim/internal.h"
 #include "eval/internal.h"
 
-#include <setjmp.h>
 #include <string.h>
 
-/* Run fn synchronously and capture any thrown exception into *out_ex.
- * Returns 0 on success (with result in *out_result), -1 on throw.
- *
- * mino_pcall does not work for our needs because its catch arm calls
- * set_eval_diag, which itself longjmps to the next-outer try frame
- * when one is present (mino's diagnostic mechanism converts errors
- * to catchable exceptions outside try blocks). The pcall behavior is
- * "intercept then re-throw if any outer try exists"; we want
- * "intercept and swallow without re-throwing" so a thrown action /
- * watch is captured into the agent's err slot. We push our own try
- * frame and skip the diagnostic conversion. */
-static int agent_try_call(mino_state_t *S, mino_val_t *fn, mino_val_t *args,
-                           mino_env_t *env, mino_val_t **out_result,
-                           mino_val_t **out_ex)
-{
-    int saved_try = mino_current_ctx(S)->try_depth;
-    mino_val_t *result;
-
-    if (saved_try >= MAX_TRY_DEPTH) {
-        if (out_result != NULL) *out_result = NULL;
-        if (out_ex != NULL) *out_ex = NULL;
-        return -1;
-    }
-    mino_current_ctx(S)->try_stack[saved_try].exception      = NULL;
-    mino_current_ctx(S)->try_stack[saved_try].saved_ns       = S->current_ns;
-    mino_current_ctx(S)->try_stack[saved_try].saved_ambient  = S->fn_ambient_ns;
-    mino_current_ctx(S)->try_stack[saved_try].saved_load_len = S->load_stack_len;
-    if (setjmp(mino_current_ctx(S)->try_stack[saved_try].buf) != 0) {
-        /* Caught a throw. Capture the exception, restore state, and
-         * return -1 WITHOUT calling set_eval_diag (which would
-         * re-throw to any enclosing try). */
-        mino_val_t *ex = mino_current_ctx(S)->try_stack[saved_try].exception;
-        S->current_ns    = mino_current_ctx(S)->try_stack[saved_try].saved_ns;
-        S->fn_ambient_ns = mino_current_ctx(S)->try_stack[saved_try].saved_ambient;
-        mino_current_ctx(S)->try_depth = saved_try;
-        if (out_result != NULL) *out_result = NULL;
-        if (out_ex != NULL) *out_ex = ex;
-        return -1;
-    }
-    mino_current_ctx(S)->try_depth++;
-    result = mino_call(S, fn, args, env);
-    mino_current_ctx(S)->try_depth = saved_try;
-    if (out_result != NULL) *out_result = result;
-    if (out_ex != NULL) *out_ex = NULL;
-    return result == NULL ? -1 : 0;
-}
-
 /* --- public-API constructor + predicate ----------------------------------- */
 
 mino_val_t *mino_agent(mino_state_t *S, mino_val_t *initial)
@@ -136,7 +89,7 @@ static void agent_apply_action(mino_state_t *S, mino_val_t *agent,
     mino_val_t *thrown_ex = NULL;
     int         pc;
 
-    pc = agent_try_call(S, fn, call_args, env, &new_state, &thrown_ex);
+    pc = mino_pcall(S, fn, call_args, env, &new_state, &thrown_ex);
     if (pc != 0 || new_state == NULL) {
         gc_write_barrier(S, agent, agent->as.agent.err, thrown_ex);
         agent->as.agent.err = thrown_ex;
@@ -147,8 +100,8 @@ static void agent_apply_action(mino_state_t *S, mino_val_t *agent,
     if (agent->as.agent.validator != NULL) {
         mino_val_t *vargs = mino_cons(S, new_state, mino_nil(S));
         mino_val_t *vresult = NULL;
-        pc = agent_try_call(S, agent->as.agent.validator, vargs, env,
-                              &vresult, &thrown_ex);
+        pc = mino_pcall(S, agent->as.agent.validator, vargs, env,
+                          &vresult, &thrown_ex);
         if (pc != 0 || vresult == NULL || !mino_is_truthy(vresult)) {
             mino_val_t *ex = thrown_ex;
             if (ex == NULL) {
@@ -187,7 +140,7 @@ static void agent_apply_action(mino_state_t *S, mino_val_t *agent,
                       mino_cons(S, agent,
                         mino_cons(S, old_state,
                           mino_cons(S, new_state, mino_nil(S)))));
-            pc = agent_try_call(S, wfn, wargs, env, &wresult, &wthrown);
+            pc = mino_pcall(S, wfn, wargs, env, &wresult, &wthrown);
             if (pc != 0 && wthrown != NULL) {
                 /* Capture the watch's thrown payload into agent.err.
                  * Continue dispatching remaining watches: a thrown

src/prim/stm.c

@@ -745,22 +745,29 @@ mino_val_t *mino_tx_ensure(mino_state_t *S, mino_val_t *ref,
  * the same ref do not conflict.
  */
 /* Run a ref's validator (if any) against the proposed new value via
- * mino_pcall so a thrown validator does not longjmp out while we still
- * hold the commit lock. Returns 1 on success, 0 on validator throw,
- * -1 on validator returning falsy (which is also a rejection but
- * surfaces a different error). */
+ * mino_pcall so a thrown validator does not longjmp out while we
+ * still hold the commit lock. Returns:
+ *   1  -- validator returned truthy
+ *   0  -- validator threw; *out_ex set to the thrown value
+ *  -1  -- validator returned falsy (no throw); *out_ex unchanged.
+ * vfn==NULL is treated as "no validator" and returns 1. */
 static int run_ref_validator(mino_state_t *S, mino_val_t *ref,
-                              mino_val_t *new_val, mino_env_t *env)
+                              mino_val_t *new_val, mino_env_t *env,
+                              mino_val_t **out_ex)
 {
     mino_val_t *vfn = ref->as.tx_ref.validator;
     mino_val_t *vargs;
     mino_val_t *result = NULL;
+    mino_val_t *thrown = NULL;
     int         pc;
     if (vfn == NULL) return 1;
     vargs = mino_cons(S, new_val, mino_nil(S));
-    pc = mino_pcall(S, vfn, vargs, env, &result);
-    if (pc != 0) return 0;
-    if (result == NULL) return 0;
+    pc = mino_pcall(S, vfn, vargs, env, &result, &thrown);
+    if (pc != 0) {
+        if (out_ex != NULL) *out_ex = thrown;
+        return 0;
+    }
+    if (result == NULL) return 0;  /* defensive; shouldn't happen */
     if (!mino_is_truthy(result)) return -1;
     return 1;
 }
@@ -770,6 +777,7 @@ static int tx_commit(mino_state_t *S, tx_state_t *tx, mino_env_t *env,
 {
     tx_ref_state_t *rs;
     if (out_validator_rejected != NULL) *out_validator_rejected = 0;
+    tx->validator_thrown_ex = NULL;
     stm_lock(S);
     /* Validate read set: every ref that the tx read must still be at
      * its snapshot version. */
@@ -797,12 +805,20 @@ static int tx_commit(mino_state_t *S, tx_state_t *tx, mino_env_t *env,
             }
         }
         if (new_val != NULL) {
-            int vc = run_ref_validator(S, rs->ref, new_val, env);
+            mino_val_t *vex = NULL;
+            int vc = run_ref_validator(S, rs->ref, new_val, env, &vex);
             if (vc != 1) {
                 stm_unlock(S);
-                if (out_validator_rejected != NULL && vc == -1) {
+                /* Both throws and falsy-rejects are validator
+                 * rejections (hard failures), distinct from read-set
+                 * conflicts that should retry. dosync_run inspects
+                 * tx->validator_thrown_ex to decide whether to
+                 * propagate the user's exception or throw the generic
+                 * "Invalid reference state" message. */
+                if (out_validator_rejected != NULL) {
                     *out_validator_rejected = 1;
                 }
+                tx->validator_thrown_ex = vex;
                 return 0;
             }
             rs->committed_old = rs->ref->as.tx_ref.val;
@@ -912,9 +928,19 @@ static mino_val_t *tx_run_loop(mino_state_t *S,
             return r;
         }
         if (validator_rejected) {
+            mino_val_t *vex = tx->validator_thrown_ex;
             tx_clear_ref_states(tx);
-            prim_throw_classified(S, "eval/contract", "MCT001",
-                "Invalid reference state");
+            tx->validator_thrown_ex = NULL;
+            if (vex != NULL) {
+                /* Validator threw -- propagate the user's original
+                 * exception value. JVM Clojure surfaces a validator
+                 * throw to the dosync caller as that exception, not
+                 * as a generic IllegalStateException. */
+                mino_throw(S, vex);
+            } else {
+                prim_throw_classified(S, "eval/contract", "MCT001",
+                    "Invalid reference state");
+            }
             return NULL; /* unreachable */
         }
         /* Conflict: free per-ref state and retry. */
@@ -948,11 +974,12 @@ static mino_val_t *tx_outer_run(mino_state_t *S,
 
     ctx_v                 = mino_current_ctx(S);
     saved_try             = ctx_v->try_depth;
-    tx.depth              = 1;
-    tx.refs_head          = NULL;
-    tx.retry_count        = 0;
-    tx.try_depth_at_start = saved_try;
-    tx.retry_signal       = 0;
+    tx.depth                = 1;
+    tx.refs_head            = NULL;
+    tx.retry_count          = 0;
+    tx.try_depth_at_start   = saved_try;
+    tx.retry_signal         = 0;
+    tx.validator_thrown_ex  = NULL;
 
     if (ctx_v->try_depth >= MAX_TRY_DEPTH) {
         return prim_throw_classified(S, "eval/state", "MST006",

src/runtime/internal.h

@@ -217,6 +217,11 @@ typedef struct tx_state {
     int                  retry_count;
     int                  try_depth_at_start; /* try-stack snapshot for retry */
     int                  retry_signal;     /* set by retry-trigger; consumed by loop */
+    /* Set by tx_commit to the validator's thrown exception (if any)
+     * so dosync_run can re-throw the original payload instead of a
+     * generic MCT001 message. NULL when the validator returned falsy
+     * without throwing or when no validator ran. */
+    mino_val_t          *validator_thrown_ex;
 } tx_state_t;
 
 /* ------------------------------------------------------------------------- */

src/runtime/state.c

@@ -743,48 +743,51 @@ mino_val_t *mino_call(mino_state_t *S, mino_val_t *fn, mino_val_t *args, mino_en
 }
 
 int mino_pcall(mino_state_t *S, mino_val_t *fn, mino_val_t *args, mino_env_t *env,
-               mino_val_t **out)
+               mino_val_t **out, mino_val_t **out_ex)
 {
     int saved_try = mino_current_ctx(S)->try_depth;
     mino_val_t *result;
 
-    if (mino_current_ctx(S)->try_depth >= MAX_TRY_DEPTH) {
-        if (out != NULL) {
-            *out = NULL;
-        }
+    if (out_ex != NULL) *out_ex = NULL;
+
+    if (saved_try >= MAX_TRY_DEPTH) {
+        if (out != NULL) *out = NULL;
         return -1;
     }
 
-    mino_current_ctx(S)->try_stack[mino_current_ctx(S)->try_depth].exception      = NULL;
-    mino_current_ctx(S)->try_stack[mino_current_ctx(S)->try_depth].saved_ns       = S->current_ns;
-    mino_current_ctx(S)->try_stack[mino_current_ctx(S)->try_depth].saved_ambient  = S->fn_ambient_ns;
-    mino_current_ctx(S)->try_stack[mino_current_ctx(S)->try_depth].saved_load_len = S->load_stack_len;
-    if (setjmp(mino_current_ctx(S)->try_stack[mino_current_ctx(S)->try_depth].buf) != 0) {
-        /* Landed here from longjmp -- error was thrown. */
+    mino_current_ctx(S)->try_stack[saved_try].exception      = NULL;
+    mino_current_ctx(S)->try_stack[saved_try].saved_ns       = S->current_ns;
+    mino_current_ctx(S)->try_stack[saved_try].saved_ambient  = S->fn_ambient_ns;
+    mino_current_ctx(S)->try_stack[saved_try].saved_load_len = S->load_stack_len;
+    if (setjmp(mino_current_ctx(S)->try_stack[saved_try].buf) != 0) {
+        /* Landed here from longjmp -- error was thrown. Restore the
+         * eval bookkeeping that was active at pcall entry, then
+         * surface the raw thrown value via out_ex without touching
+         * last_error / last_diag.
+         *
+         * pcall does NOT publish to last_error on purpose: the eval
+         * loop has read sites that treat mino_last_error as "an error
+         * happened during my call" (see eval_impl's "evaled == NULL
+         * && mino_last_error != NULL" gate), so leaving a stale diag
+         * from a successfully-caught pcall would mislead the next
+         * failing call into thinking its own error had already been
+         * reported. Callers that want a diag published after pcall
+         * returns -1 call set_eval_diag explicitly. */
+        mino_val_t *ex = mino_current_ctx(S)->try_stack[saved_try].exception;
         S->current_ns    = mino_current_ctx(S)->try_stack[saved_try].saved_ns;
         S->fn_ambient_ns = mino_current_ctx(S)->try_stack[saved_try].saved_ambient;
         load_stack_truncate(S, mino_current_ctx(S)->try_stack[saved_try].saved_load_len);
         mino_current_ctx(S)->try_depth = saved_try;
-        /* pcall does NOT publish to last_error / last_diag on a caught
-         * throw. The eval loop has read sites that treat
-         * mino_last_error as "an error happened during my call" (see
-         * eval_impl's "evaled == NULL && mino_last_error != NULL"
-         * gate), so leaving a stale diag from a successfully-caught
-         * pcall would mislead the next failing call into thinking
-         * its own error had already been reported. Callers that
-         * want a diag published after pcall returns -1 call
-         * set_eval_diag explicitly. */
         if (out != NULL) *out = NULL;
+        if (out_ex != NULL) *out_ex = ex;
         return -1;
     }
     mino_current_ctx(S)->try_depth++;
 
     result = mino_call(S, fn, args, env);
     mino_current_ctx(S)->try_depth = saved_try;
 
-    if (out != NULL) {
-        *out = result;
-    }
+    if (out != NULL) *out = result;
     return result == NULL ? -1 : 0;
 }