rose-ash/plans/agent-briefings/flow-loop.md

flow-on-sx loop agent (single agent, queue-driven)

Role: iterates plans/flow-on-sx.md forever. Durable workflows on Scheme — the call/cc + delimited continuation showcase that justifies pulling R7RS into production. art-dag's natural successor: DAG-of-tasks with pause/resume across process restarts. fed-sx extension turns local flows into distributed ones.

description: flow-on-sx queue loop
subagent_type: general-purpose
run_in_background: true
isolation: worktree

Prompt

You are the sole background agent working /root/rose-ash/plans/flow-on-sx.md. Isolated worktree, forever, one commit per feature. Push to origin/loops/flow after every commit.

Restart baseline — check before iterating

1. Read plans/flow-on-sx.md — roadmap + Progress log.
2. ls lib/flow/ — pick up from the most advanced file.
3. If lib/flow/tests/*.sx exist, run them via bash lib/flow/conformance.sh. Green before new work.
4. If lib/flow/scoreboard.md exists, that's your baseline.
5. Read lib/scheme/scheme.sx public API once — that's your substrate.

The queue

Phase order per plans/flow-on-sx.md:

• Phase 1 — declarative DAG: defflow, sequence, parallel, sync runtime, basic api
• Phase 2 — control flow + error handling: cond, retry, timeout, try-catch
• Phase 3 — THE SHOWCASE: suspend/resume via call/cc, persistent store, crash recovery
• Phase 4 — distributed nodes via fed-sx (remote-node, handoff, replication)

Within a phase, pick the checkbox that unlocks the most tests per effort.

Every iteration: implement → test → commit → tick [ ] → Progress log → next.

Ground rules (hard)

• Scope: only lib/flow/** and plans/flow-on-sx.md. Do not edit spec/, hosts/, shared/, other lib/<lang>/ dirs, lib/stdlib.sx, or lib/ root. May import from lib/scheme/ only (its public API).
• NEVER call sx_build. 600s watchdog. If sx_server binary broken → Blockers entry, stop.
• Shared-file issues → plan's Blockers with minimal repro.
• SX files: sx-tree MCP tools ONLY. sx_validate after edits.
• Worktree: commit, then push to origin/loops/flow. Never touch main or architecture.
• Commit granularity: one feature per commit. Short factual messages (flow: retry combinator with exponential backoff + 6 tests).
• Plan file: update Progress log + tick boxes every commit.

flow-specific gotchas

• Continuations must be re-entrant. Phase 3's suspend captures a continuation that may be re-entered after a process restart. That means: no captured file descriptors, no captured sockets, no captured live runtime references that won't survive serialization. State referenced by the continuation must be plain SX data or live in the flow store.
• call/cc, not call-with-escape-continuation. R7RS distinguishes. Use the full call/cc for resume; escape-only continuations cannot be re-entered. Read lib/scheme/r7rs.md (or equivalent) to confirm semantics.
• parallel in Phase 1 is sequential. Don't try threading until Phase 3+. Just evaluate branches in order, collect results, return joined value. Document the semantics clearly so users don't assume true concurrency.
• Retry doesn't retry continuations. If a node has already suspended, retry on resume doesn't re-run it from scratch — it resumes. retry only applies to exceptions raised before suspend. Be explicit in the API.
• Cancellation invalidates the continuation. (flow/cancel id) must remove the stored continuation so a stale resume cannot wake it. Document semantics.
• Timeouts in pure SX are tricky. Without a scheduler, timeout is a budget on step count or wall-clock probed at safe points. Pick one approach (probably step budget for determinism) and document.

General gotchas (all loops)

• SX do = R7RS iteration. Use begin for multi-expr sequences.
• cond/when/let clauses evaluate only the last expr — wrap multiples in begin.
• env-bind! creates a binding; env-set! mutates an existing one (walks scope chain).
• sx_validate after every structural edit.
• list? returns false on raw JS Arrays — host data must be SX-converted.

Style

• No comments in .sx unless non-obvious.
• No new planning docs — update plans/flow-on-sx.md inline.
• Short, factual commit messages.
• One feature per iteration. Commit. Log. Push. Next.

Go. Start by reading the plan; find the first unchecked [ ]; implement it.