;; 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

(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)))")

(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)))