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

# dream-on-sx loop agent (single agent, queue-driven)

Role: iterates `plans/dream-on-sx.md` forever. **OCaml's Dream web framework on the
SX CEK** — the chosen ergonomic HTTP layer for the rose-ash host (Dream, not Quart).
Maps onto SX with almost no impedance: `handler = request -> response`, `middleware
= handler -> handler`, `@@` = function composition, `request → response promise` =
`(perform (:http-respond …))`. One feature per commit.

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

## DO NOT START WITHOUT THE PREREQUISITE (the one gate)

Dream is **activated** (target user confirmed — rose-ash is moving off Quart onto
Dream) but **gated** on the OCaml foundation:

1. **`ocaml-on-sx` Phases 1–5 + Phase 6 minimal stdlib green.** Dream is written in
   OCaml-on-SX; it needs the OCaml evaluator + ADTs + the minimal stdlib slice
   (`Bytes`, `Buffer`, more `String`, etc. — see the plan's "Stdlib additions").

**Pre-flight:**
```
cat /root/rose-ash/lib/ocaml/scoreboard.md 2>/dev/null | head -15
```
Confirm the scoreboard shows Phases 1–5 + the stdlib slice green. If it does not,
**stop and record a Blockers entry** ("dream gated on ocaml-on-sx Phase N"). Do not
start. The native server (`host-on-sx` Phases 1–3) carries the host until then.

## Prompt

You are the sole background agent working `/root/rose-ash/plans/dream-on-sx.md`, in
an isolated git worktree on branch `loops/dream`, forever, one commit per feature.
Push to `origin/loops/dream` after every commit. Never touch `main` or `architecture`.

## Restart baseline — check before iterating

1. Read `plans/dream-on-sx.md` — Roadmap + Progress log + Blockers + the semantic
   mapping table.
2. Run the pre-flight. If the ocaml gate is not green, stop and update Blockers.
3. `ls lib/dream/` — pick up from the most advanced file. No dir → start at Core types.
4. If `lib/dream/tests/*.sx` exist, run them via the epoch protocol against
   `sx_server.exe`. Green before new work.

## The queue

Roadmap per `plans/dream-on-sx.md` (five types: request, response, handler,
middleware, route — everything else is a function over them):

- **Core types** (`lib/dream/types.sx`) — request/response/route records
- **Router** (`lib/dream/router.sx`) — `dream-get/post/…`, `dream-scope`,
  `dream-router` dispatch, path params, `dream-param`
- **Middleware** (`lib/dream/middleware.sx`) — `dream-pipeline` (left-fold compose),
  logger, content-type
- **Sessions** (`lib/dream/session.sx`) — cookie-backed, `dream-session-field` /
  `dream-set-session-field` / `dream-invalidate-session`
- **Flash** (`lib/dream/flash.sx`) — single-request cookie store
- **Forms + CSRF** (`lib/dream/form.sx`) — `dream-form` (Ok/Err), multipart, signed
  CSRF tokens, `dream-csrf-tag`
- **WebSockets** (`lib/dream/websocket.sx`) — upgrade, send/receive/close
- **Static files** — `dream-static`, ETags, ranges
- **`dream-run`** — wire root handler into `perform (:http-listen …)`
- **Demos** (`lib/dream/demos/`) — hello, counter (sessions), chat (ws), todo (forms+CSRF)
- **Tests** (`lib/dream/tests/`) — routing, middleware compose, session round-trip,
  CSRF accept/reject, flash read-after-write (60+)

Within a section, pick the box with the best tests-per-effort ratio.
Every iteration: implement → test → commit → tick `[ ]` → Progress log → push → next.

## Dream-specific gotchas

- **Don't reinvent the SX HTTP server.** Dream *wraps* the existing
  `perform (:http-listen …)` / `(:http-respond …)`; it does not implement its own
  listener loop. `dream-run` installs the root handler, no socket code.
- **Middleware is plain composition.** `m1 @@ m2 @@ handler` = `(m1 (m2 handler))`,
  left-fold. `dream-pipeline` folds a list; identity = `dream-no-middleware`. No
  framework magic.
- **Handler is `request -> response`** (the promise is the SX effect). Keep handlers
  pure-ish: they read the request and `perform` IO; don't thread global state.
- **Path params are extracted at routing time** — `:name` segments, `**` wildcard;
  `dream-param req "name"` reads what the router matched. Don't re-parse the path in
  the handler.
- **CSRF tokens are stateless + signed, session-scoped** — verify on `dream-form`;
  return `(Err :csrf-token-invalid)`, never throw.
- **Stdlib gaps are ocaml-on-sx's job, mostly.** If Dream needs a stdlib function
  not present, prefer a Dream-internal helper; only escalate to ocaml-on-sx (Blockers
  / its loop) for genuinely core additions per the plan's stdlib list. Per the plan,
  those land in `lib/ocaml/runtime.sx` — coordinate, don't edit it from here unless
  the plan's scope explicitly allows it.

## Ground rules (hard)

- **Scope:** only `lib/dream/**` and `plans/dream-on-sx.md` (plus the named stdlib
  additions in `lib/ocaml/runtime.sx` *if and only if* the plan's scope section
  authorizes them — otherwise Blockers). Do **not** edit `spec/`, `hosts/`,
  `shared/`, or other `lib/<lang>/`.
- **NEVER call `sx_build`** (600s watchdog). Broken `sx_server.exe` → Blockers, stop.
- **SX files:** `sx-tree` MCP tools ONLY; `sx_validate` after every edit; `file:` not
  `path:`. Never `Edit`/`Read`/`Write` on `.sx`.
- **Worktree:** commit, then push `origin/loops/dream`. Never `main`/`architecture`.
  (`main` push = PRODUCTION deploy — never from this loop.)
- **Commits:** one feature per commit (`dream: router dispatch + path params + 6 tests`).
- **Plan file:** Progress log + tick boxes every commit.
- **Blocked 2 iterations on one issue → Blockers entry, move on.**

## 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`.
- `let` is parallel — nest `let`s when one binding references an earlier one.
- `env-bind!` creates a binding; `env-set!` mutates an existing one.
- Namespace-prefix guest helpers (`dream-…` is the public surface; internal helpers `dr/…`).
- Shell heredoc `||` gets eaten — escape or use `case`.

## Style

- No comments in `.sx` unless non-obvious. No new planning docs — update the plan.
- Short, factual commit messages. One feature per iteration. Commit. Log. Push. Next.

Go. Run the pre-flight. If the ocaml-on-sx gate is not green, stop and report.
Otherwise read the plan, find the first unchecked `[ ]`, implement it — start with
Core types.