flow: retry combinator — re-run node on raised exceptions + 6 tests

(retry n node) re-runs up to n attempts on a raised exception; the last attempt's
exception propagates. Explicit (fail ...) values are NOT retried — they pass through.

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

lib/flow/scoreboard.json

@@ -1,10 +1,10 @@
 {
-  "total": 36,
-  "passed": 36,
+  "total": 42,
+  "passed": 42,
   "failed": 0,
   "suites": {
     "basic": { "passed": 18, "total": 18 },
-    "control": { "passed": 18, "total": 18 }
+    "control": { "passed": 24, "total": 24 }
   },
   "phases": { "phase1": "done", "phase2": "in-progress" }
 }

lib/flow/scoreboard.md

@@ -1,6 +1,6 @@
 # flow-on-sx Scoreboard
 
-**All tests pass: 36 / 36 across 2 suites.**
+**All tests pass: 42 / 42 across 2 suites.**
 
 `bash lib/flow/conformance.sh`
 
@@ -9,7 +9,7 @@
 | Suite | Passing | Covers |
 |-------|--------:|--------|
 | basic |     18  | Phase 1: single nodes, linear sequence, data-flow threading, defflow, parallel fan/join, nested composition, publish-shaped flow |
-| control |  18  | Phase 2: `branch` (6); error model `fail`/`failed?`/`fail-reason` (6); `try-catch` reifying raised exceptions (6) |
+| control |  24  | Phase 2: `branch` (6); error model `fail`/`failed?`/`fail-reason` (6); `try-catch` (6); `retry n` re-running on raised exceptions (6) |
 
 ## Architecture
 
@@ -36,6 +36,6 @@ capture the flow continuation directly.
 ## Phases
 
 - [x] Phase 1 — Declarative DAG + sequential execution (combinators + 18 tests, `flow/start`)
-- [~] Phase 2 — Control flow + error handling (`branch`, error model, `try-catch` done)
+- [~] Phase 2 — Control flow + error handling (`branch`, error model, `try-catch`, `retry` done)
 - [ ] Phase 3 — Suspend / resume (the showcase)
 - [ ] Phase 4 — Distributed nodes via fed-sx

lib/flow/spec.sx

@@ -24,6 +24,10 @@
 ;;   (fail-reason x)    — the reason carried by a failure value
 ;;   (try-catch node handler) — run node; if it raises, call (handler error)
 ;;     with the reified error and return the handler's value
+;;   (retry n node)     — run node, re-running up to n attempts total on a raised
+;;     exception; the last attempt's exception propagates. Only RAISED exceptions
+;;     are retried — explicit (fail ...) values pass through unchanged. (Once a
+;;     node has suspended in Phase 3, retry does not re-run it; resume continues.)
 
 (define
   flow-combinators-src
@@ -31,7 +35,7 @@
 
 (define
   flow-control-src
-  "(define (branch pred then else)\n     (lambda (input) (if (pred input) (then input) (else input))))\n   (define (fail reason) (list (quote flow-fail) reason))\n   (define (failed? x) (and (pair? x) (eq? (car x) (quote flow-fail))))\n   (define (fail-reason x) (car (cdr x)))\n   (define (try-catch node handler)\n     (lambda (input) (guard (e (#t (handler e))) (node input))))")
+  "(define (branch pred then else)\n     (lambda (input) (if (pred input) (then input) (else input))))\n   (define (fail reason) (list (quote flow-fail) reason))\n   (define (failed? x) (and (pair? x) (eq? (car x) (quote flow-fail))))\n   (define (fail-reason x) (car (cdr x)))\n   (define (try-catch node handler)\n     (lambda (input) (guard (e (#t (handler e))) (node input))))\n   (define (flow-retry-step n node input)\n     (guard (e (#t (if (<= n 1) (raise e) (flow-retry-step (- n 1) node input))))\n       (node input)))\n   (define (retry n node) (lambda (input) (flow-retry-step n node input)))")
 
 (define
   flow-load-combinators!

lib/flow/tests/control.sx

@@ -108,4 +108,36 @@
     "(flow/start (sequence (try-catch (lambda (x) (raise (quote x))) (flow-const 10)) (lambda (n) (* n 5))) 0)")
   50)
 
+;; ── retry — re-run on raised exceptions ─────────────────────────
+(flow-ctl-test
+  "retry: succeeds after transient failures"
+  (flow-c
+    "(define ctr 0) (defflow flaky (lambda (x) (set! ctr (+ ctr 1)) (if (< ctr 3) (raise (quote nope)) (* x 10)))) (list (flow/start (retry 5 flaky) 7) ctr)")
+  (list 70 3))
+(flow-ctl-test
+  "retry: exhausted re-raises (caught by try-catch)"
+  (flow-c
+    "(flow/start (try-catch (retry 2 (lambda (x) (raise (quote always)))) (flow-const (quote gaveup))) 0)")
+  "gaveup")
+(flow-ctl-test
+  "retry: n=1 means a single attempt"
+  (flow-c
+    "(define ctr 0) (flow/start (try-catch (retry 1 (lambda (x) (set! ctr (+ ctr 1)) (raise (quote bad)))) (lambda (e) ctr)) 0)")
+  1)
+(flow-ctl-test
+  "retry: success on first attempt does not re-run"
+  (flow-c
+    "(define ctr 0) (flow/start (sequence (retry 5 (lambda (x) (set! ctr (+ ctr 1)) (* x 2))) (lambda (n) ctr)) 21)")
+  1)
+(flow-ctl-test
+  "retry: does not retry explicit failure values"
+  (flow-c
+    "(define ctr 0) (failed? (flow/start (retry 5 (lambda (x) (set! ctr (+ ctr 1)) (fail (quote bad)))) 0))")
+  true)
+(flow-ctl-test
+  "retry: failure-value path runs node exactly once"
+  (flow-c
+    "(define ctr 0) (flow/start (sequence (retry 5 (lambda (x) (set! ctr (+ ctr 1)) (fail (quote bad)))) (lambda (f) ctr)) 0)")
+  1)
+
 (define flow-ctl-tests-run! (fn () {:total (+ flow-ctl-pass flow-ctl-fail) :passed flow-ctl-pass :failed flow-ctl-fail :fails flow-ctl-fails}))

plans/flow-on-sx.md

@@ -16,7 +16,7 @@ federation extension via fed-sx for remote-node execution.
 
 ## Status (rolling)
 
-`bash lib/flow/conformance.sh` → **36/36** (Phase 1 done; Phase 2 in progress)
+`bash lib/flow/conformance.sh` → **42/42** (Phase 1 done; Phase 2 in progress)
 
 ## Ground rules
 
@@ -77,7 +77,9 @@ lib/flow/spec.sx           lib/flow/runtime.sx          lib/flow/store.sx
 
 - [x] `cond` combinator — predicate selects branch (named `branch`; `cond` is a
   Scheme special form). `(branch pred then else)` — 6 tests.
-- [ ] `retry n [backoff]` — re-runs node up to n times on exception
+- [x] `retry n` — re-runs node up to n attempts on a raised exception; last
+  exception propagates. Only raised exceptions are retried — `(fail ...)` values
+  pass through. 6 tests. (Backoff deferred: no wall clock in pure SX.)
 - [ ] `timeout ms` — bounds node execution
 - [x] `try-catch` — exception handler with reified error: `(try-catch node handler)`
   runs node; on raise, calls `(handler error)` and returns its value. 6 tests.