flow: operational introspection API — flow/status,result,list,pending + 12 tests

flow/status id -> done|suspended|cancelled|unknown; flow/result id -> value or
error; flow/list -> (id status) per flow; flow/pending -> (id waiting-tag) for
suspended flows (operator view of what each awaits). Pure store introspection.

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

lib/flow/conformance.sh

@@ -26,6 +26,7 @@ SUITES=(
   "suspend     flow-sus-tests-run!       lib/flow/tests/suspend.sx"
   "recovery    flow-rec-tests-run!       lib/flow/tests/recovery.sx"
   "distributed flow-dist-tests-run!      lib/flow/tests/distributed.sx"
+  "api         flow-api-tests-run!       lib/flow/tests/api.sx"
 )
 
 TMPFILE=$(mktemp); trap "rm -f $TMPFILE" EXIT

lib/flow/scoreboard.json

@@ -1,13 +1,14 @@
 {
-  "total": 93,
-  "passed": 93,
+  "total": 105,
+  "passed": 105,
   "failed": 0,
   "suites": {
     "basic": { "passed": 18, "total": 18 },
     "control": { "passed": 31, "total": 31 },
     "suspend": { "passed": 17, "total": 17 },
     "recovery": { "passed": 8, "total": 8 },
-    "distributed": { "passed": 19, "total": 19 }
+    "distributed": { "passed": 19, "total": 19 },
+    "api": { "passed": 12, "total": 12 }
   },
-  "phases": { "phase1": "done", "phase2": "done", "phase3": "done", "phase4": "done" }
+  "phases": { "phase1": "done", "phase2": "done", "phase3": "done", "phase4": "done", "phase5": "in-progress" }
 }

lib/flow/scoreboard.md

@@ -1,6 +1,6 @@
 # flow-on-sx Scoreboard
 
-**All tests pass: 93 / 93 across 5 suites. All four phases complete.**
+**All tests pass: 105 / 105 across 6 suites. Phases 1-4 complete; Phase 5 in progress.**
 
 `bash lib/flow/conformance.sh`
 
@@ -13,6 +13,7 @@
 | suspend |  17  | Phase 3: suspend/resume/cancel via deterministic replay; multi-step, replay determinism, lifecycle guards, suspend-in-branch |
 | recovery |  8  | Phase 3: crash recovery — store export/import, resumable scan, restart-at-every-step, replay-log survival |
 | distributed | 19 | Phase 4: `remote-node` (7); `remote-failover` (6); replication + handoff across instances (6) |
+| api |  12  | Phase 5: introspection — `flow/status`, `flow/result`, `flow/list`, `flow/pending` |
 
 ## Architecture
 
@@ -42,5 +43,6 @@ capture the flow continuation directly.
 - [x] Phase 2 — Control flow + error handling (branch, error model, try-catch, retry, timeout)
 - [x] Phase 3 — Suspend/resume (suspend/resume/cancel + crash recovery via deterministic replay)
 - [x] Phase 4 — Distributed nodes via fed-sx (remote-node, failover, replication + handoff)
+- [~] Phase 5 — Operational API + combinators (introspection done; tap/recover/map-flow next)
 - [ ] Phase 3 — Suspend / resume (the showcase)
 - [ ] Phase 4 — Distributed nodes via fed-sx

lib/flow/tests/api.sx

@@ -0,0 +1,79 @@
+;; lib/flow/tests/api.sx — Phase 5: operational introspection API.
+
+(define flow-api-pass 0)
+(define flow-api-fail 0)
+(define flow-api-fails (list))
+
+(define
+  flow-api-test
+  (fn
+    (name actual expected)
+    (if
+      (= actual expected)
+      (set! flow-api-pass (+ flow-api-pass 1))
+      (begin
+        (set! flow-api-fail (+ flow-api-fail 1))
+        (append! flow-api-fails {:name name :expected expected :actual actual})))))
+
+(define flow-a (fn (src) (flow-run src)))
+
+;; ── flow/status ─────────────────────────────────────────────────
+(flow-api-test "status: unknown id" (flow-a "(flow/status 999)") "unknown")
+(flow-api-test
+  "status: suspended flow"
+  (flow-a
+    "(defflow w (lambda (x) (suspend (quote q)))) (define id (car (cdr (flow/start w 0)))) (flow/status id)")
+  "suspended")
+(flow-api-test
+  "status: completed flow"
+  (flow-a
+    "(defflow w (sequence (lambda (x) (suspend (quote q))) (lambda (v) v))) (define id (car (cdr (flow/start w 0)))) (flow/resume id 5) (flow/status id)")
+  "done")
+(flow-api-test
+  "status: cancelled flow"
+  (flow-a
+    "(defflow w (lambda (x) (suspend (quote q)))) (define id (car (cdr (flow/start w 0)))) (flow/cancel id) (flow/status id)")
+  "cancelled")
+
+;; ── flow/result ─────────────────────────────────────────────────
+(flow-api-test
+  "result: returns the value of a completed flow"
+  (flow-a
+    "(defflow w (sequence (lambda (x) (suspend (quote q))) (lambda (v) (list (quote got) v)))) (define id (car (cdr (flow/start w 0)))) (flow/resume id 9) (flow/result id)")
+  (list "got" 9))
+(flow-api-test
+  "result: a still-suspended flow has no result"
+  (flow-a
+    "(defflow w (lambda (x) (suspend (quote q)))) (define id (car (cdr (flow/start w 0)))) (flow/result id)")
+  (list "flow-error" "not-done"))
+(flow-api-test
+  "result: unknown id errors"
+  (flow-a "(flow/result 999)")
+  (list "flow-error" "no-such-flow"))
+
+;; ── flow/list ───────────────────────────────────────────────────
+(flow-api-test "list: empty store" (flow-a "(flow/list)") (list))
+(flow-api-test
+  "list: reports id + status for each flow (newest first)"
+  (flow-a
+    "(defflow w (lambda (x) (suspend (quote q)))) (flow/start w 0) (flow/start (lambda (x) (* x 2)) 5) (flow/list)")
+  (list (list 2 "done") (list 1 "suspended")))
+
+;; ── flow/pending ────────────────────────────────────────────────
+(flow-api-test
+  "pending: lists suspended flows with their waiting tag"
+  (flow-a
+    "(defflow w (lambda (x) (suspend (quote review)))) (flow/start w 0) (flow/pending)")
+  (list (list 1 "review")))
+(flow-api-test
+  "pending: excludes completed and cancelled flows"
+  (flow-a
+    "(defflow w (lambda (x) (suspend (quote q)))) (defflow v (sequence (lambda (x) (suspend (quote r))) (lambda (y) y))) (define i1 (car (cdr (flow/start w 0)))) (define i2 (car (cdr (flow/start v 0)))) (define i3 (car (cdr (flow/start w 0)))) (flow/resume i2 1) (flow/cancel i3) (flow/pending)")
+  (list (list 1 "q")))
+(flow-api-test
+  "pending: operator can drain all pending flows"
+  (flow-a
+    "(defflow w (sequence (lambda (x) (suspend (quote q))) (lambda (v) (* v 10)))) (flow/start w 0) (flow/start w 0) (define ps (flow/pending)) (flow/resume (car (car ps)) 1) (flow/resume (car (car (cdr ps))) 2) (flow/list)")
+  (list (list 1 "done") (list 2 "done")))
+
+(define flow-api-tests-run! (fn () {:total (+ flow-api-pass flow-api-fail) :passed flow-api-pass :failed flow-api-fail :fails flow-api-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` → **93/93** (all four phases complete)
+`bash lib/flow/conformance.sh` → **105/105** (Phases 1-4 complete; Phase 5 in progress)
 
 ## Ground rules
 
@@ -133,6 +133,20 @@ lib/flow/spec.sx           lib/flow/runtime.sx          lib/flow/store.sx
 - [x] `lib/flow/tests/distributed.sx` — 19 cases: remote-node, failover,
   replication, handoff (including replay-log survival across the move)
 
+## Phase 5 — Operational API + combinator library
+
+The four roadmap phases are complete; this phase rounds out the engine into
+something operators and authors actually use. Accumulation, not a rewrite.
+
+- [x] introspection API — `flow/status id`, `flow/result id`, `flow/list`,
+  `flow/pending` (operator view of what each suspended flow awaits). 12 tests in
+  `tests/api.sx`.
+- [ ] `tap` — side-effecting pass-through node (logging/metrics) that returns input
+- [ ] `recover` — complement to try-catch for the fail-VALUE channel: run node; if it
+  yields `(fail ...)`, run a recovery node on the reason
+- [ ] `map-flow` — run a flow per item of a list, join results (sequential)
+- [ ] `lib/flow/tests/api.sx` — introspection + new combinators
+
 ## Progress log
 
 - **Phase 1 (combinators + sequential runtime).** Flow built as a Scheme prelude