;; lib/flow/spec.sx — flow combinators as a Scheme prelude.
;;
;; A flow is a Scheme procedure of one argument: the upstream value.
;;   node : input -> output
;; A leaf node ignoring its argument is effectively a thunk. Combinators
;; build composite nodes out of child nodes. The whole flow runs INSIDE the
;; Scheme interpreter so that Phase 3's `suspend` (call/cc) can capture the
;; flow continuation directly.
;;
;; Phase 1 combinators (flow-combinators-src):
;;   (flow-node f)      — wrap a 1-arg procedure as a node (identity)
;;   (flow-id input)    — pass the upstream value through unchanged
;;   (flow-const v)     — node that ignores input and yields v
;;   (sequence n ...)   — thread input left-to-right through children
;;   (parallel n ...)   — fan input to every child, join results into a list
;;                        (SEQUENTIAL evaluation; true concurrency is Phase 3)
;;   (defflow name body)— bind a named flow
;;
;; Phase 2 combinators (flow-control-src):
;;   (branch pred then else) — pred on input selects then/else node
;;     (`cond` is a Scheme special form, so the combinator is named `branch`)
;;   (fail reason)      — make an explicit failure value (data, not an exception)
;;   (failed? x)        — is x a failure value?
;;   (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
  "(define (flow-node f) f)\n   (define (flow-id input) input)\n   (define (flow-const v) (lambda (input) v))\n   (define (flow-seq-step ns v)\n     (if (null? ns) v (flow-seq-step (cdr ns) ((car ns) v))))\n   (define sequence (lambda ns (lambda (input) (flow-seq-step ns input))))\n   (define parallel (lambda ns (lambda (input) (map (lambda (n) (n input)) ns))))\n   (define-syntax defflow\n     (syntax-rules ()\n       ((defflow nm body) (define nm body))))")

(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))))\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!
  (fn
    (env)
    (begin
      (scheme-eval-program (scheme-parse-all flow-combinators-src) env)
      (scheme-eval-program (scheme-parse-all flow-control-src) env)
      env)))