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

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

Role: iterates plans/host-on-sx.md forever. The SX web host — off Quart, onto the kernel. Turns the subsystem libraries (feed/search/acl/mod/flow/commerce/ identity/content/events/relations) into running services, and walks rose-ash off Python/Quart by the strangler-fig method. This is the dependency hub — it imports every subsystem's public API. One feature per commit.

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

Orientation — two layers, two timelines (read plans/host-on-sx.md first)

1. Now (unblocked): native OCaml HTTP server (already live in prod on sx.rose-ash.com) + SXTP adapter + SX handlers. Migrate rose-ash endpoints onto the SX host one at a time; Quart proxies the rest until cut over. No ocaml-on-sx dependency for this layer.
2. Next (Phase 4, gated): dream-on-sx as the framework layer over the same handlers — typed routing, middleware, sessions, CSRF. Gated on ocaml-on-sx Phases 1–5 + Phase 6 minimal stdlib (currently 480/480 and advancing — verify its scoreboard before starting Phase 4). Do not block Phases 1–3 on Dream.
3. Always: Python only at the external edges (SumUp, Ghost, ActivityPub crypto, IPFS/Kubo) — thin injected adapters behind subsystem interfaces. "Drop Quart" ≠ "drop every line of Python."

Prompt

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

Restart baseline — check before iterating

1. Read plans/host-on-sx.md — Roadmap + Progress log + Blockers + the migration ledger.
2. ls lib/host/ — pick up from the most advanced file. No dir → Phase 1.
3. If lib/host/tests/*.sx exist, run them via the epoch protocol against sx_server.exe (SX_SERVER=/root/rose-ash/hosts/ocaml/_build/default/bin/sx_server.exe). Green before new work.
4. Confirm the subsystems you're about to wire are present on this branch (ls lib/feed lib/acl lib/mod …) — host imports their public APIs only.

The queue

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

• Phase 1 — router.sx (route table, (method,path) match) + handler.sx (request/response model, subsystem dispatch) + migrate ONE read endpoint end-to-end with a golden-response test + conformance.sh + scoreboard
• Phase 2 — middleware.sx (composable auth(identity) ∘ acl ∘ mute ∘ error)
  • sxtp.sx (host↔subsystem wire format, align with the existing SXTP spec) + migrate a write endpoint (auth + permission + action)
• Phase 3 — strangler migration ledger: enumerate Quart endpoints, track migrated vs proxied, golden-response harness vs live Quart, cut over a whole small domain (likes or relations) as proof
• Phase 4 (gated) — Dream framework layer once ocaml-on-sx 1–5 + stdlib is green: adopt dream-on-sx routing/middleware/session ergonomics over the same handlers; re-home external adapters as native where replacements land

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

Migration discipline (the strangler rule)

• Every migrated endpoint must be behavior-equivalent to its Quart original. Capture a golden response from the live Quart endpoint before the flip; the SX handler's response must match (status, headers that matter, body shape). Keep the golden fixtures in lib/host/tests/.
• Never big-bang. One endpoint at a time; Quart proxies everything not yet migrated. The migration ledger is the source of truth for what's flipped.
• A handler is request -> response calling subsystem public APIs; middleware is composed handlers. Don't reach into subsystem internals — wire to their APIs.

Ground rules (hard)

• Scope: only lib/host/** and plans/host-on-sx.md. May import every subsystem's public API + the kernel's server/SXTP surface. Do not edit spec/, hosts/, shared/, or any subsystem internals. Host-primitive / native server changes belong in hosts/ (out of scope) → Blockers entry.
• 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/host. Never main/architecture. (Note: main push = PRODUCTION deploy — never from this loop.)
• Commits: one feature per commit (host: feed-timeline read endpoint + golden test).
• Plan file: Progress log + tick boxes + migration ledger every commit.
• Blocked 2 iterations on one issue → Blockers entry, move on.

host-specific gotchas

• The native server lives in hosts/ and is out of scope. You wire SX handlers to it via defhandler/defpage/SXTP; you don't modify the listener. If the server surface lacks something, that's a Blockers entry for the kernel loop.
• SXTP is the host↔service wire format — align with the existing spec (applications/sxtp/spec.sx); don't invent a parallel protocol.
• Subsystems are libraries with public APIs. Treat mod/decide, acl-permit?, feed/search queries etc. as the contract; if you need something not exposed, it's a subsystem feature request (their loop), not a host reach-in.
• Auth vs permission are different middlewares. identity answers "who is this" (sessions/OAuth); acl answers "may they". Compose them as distinct layers.
• External edges stay Python until native replacements exist — model them as injected adapter interfaces so a handler depends on the interface, not on Python.
• Dream is Phase 4 and gated — verify ocaml-on-sx scoreboard (Phases 1–5 + minimal stdlib) before touching it; the native server is sufficient for 1–3.

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 lets when one binding references an earlier one.
• env-bind! creates a binding; env-set! mutates an existing one.
• Namespace-prefix host helpers (host/…).
• 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. Read the plan, confirm the subsystems you need are present, find the first unchecked [ ], implement it. Start with Phase 1 on the native server — do not wait for Dream.