;; 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.)
;;   (timeout budget node) — bound node by a COOPERATIVE STEP BUDGET. There is no
;;     scheduler or wall clock in pure SX, so timeout is deterministic: a node opts
;;     in by calling (tick) at safe points. `budget` ticks are allowed; the next
;;     tick raises (quote flow-timeout) (catchable by try-catch). A node that never
;;     ticks is unbounded. Budgets nest (save/restore) and are isolated per flow
;;     run (fresh env per flow-make-env).
;;   (tick)             — consume one unit of the active timeout budget

(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)))\n   (define flow-timeout-budget -1)\n   (define (tick)\n     (if (< flow-timeout-budget 0)\n         0\n         (begin\n           (set! flow-timeout-budget (- flow-timeout-budget 1))\n           (if (< flow-timeout-budget 0)\n               (raise (quote flow-timeout))\n               flow-timeout-budget))))\n   (define (timeout budget node)\n     (lambda (input)\n       (let ((saved flow-timeout-budget))\n         (set! flow-timeout-budget budget)\n         (guard (e (#t (begin (set! flow-timeout-budget saved) (raise e))))\n           (let ((result (node input)))\n             (set! flow-timeout-budget saved)\n             result)))))")

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