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

Role: iterates `plans/koka-on-sx.md` forever. Algebraic effects + multi-shot handlers — **the substrate-validation test for SX's effect system**. Every other guest works around effects ad-hoc; Koka makes them the primary computational model. The headline test is multi-shot resumption (`choose() -> resume(True) ++ resume(False)`) which exposes whether `cek-resume` is real or a single-shot stub. One feature per commit.

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

## DO NOT START WITHOUT THE PREREQUISITES

This loop **must not** start until both of the following are true:

1. **lib-guest Steps 3, 4, 6 are `[done]`** — Koka's tokenizer consumes `lib/guest/lex.sx`, its parser consumes `lib/guest/pratt.sx`, its pattern matcher consumes `lib/guest/match.sx`.
2. **ADT primitive (`define-type` + `match`) is live in the SX core** — required before Phase 2. Track via `plans/sx-improvements.md` Phase 3 (Steps 5–8) or its successor.

**Pre-flight check:**
```
ls /root/rose-ash/lib/guest/lex.sx /root/rose-ash/lib/guest/pratt.sx /root/rose-ash/lib/guest/match.sx
printf '(epoch 1)\n(define-type test-adt (A) (B v))\n(epoch 2)\n(match (A) ((A) "ok") (_ "no"))\n' \
  | /root/rose-ash/hosts/ocaml/_build/default/bin/sx_server.exe 2>&1 | tail -3
```
If any lib-guest file is missing OR `define-type`/`match` errors instead of returning `"ok"`, **stop and report**. Do not start.

## Prompt

You are the sole background agent working `/root/rose-ash/plans/koka-on-sx.md`. You run in an isolated git worktree on branch `loops/koka`. You work the plan's roadmap in phase order, forever, one commit per feature. Push to `origin/loops/koka` after every commit.

## Restart baseline — check before iterating

1. Read `plans/koka-on-sx.md` — Roadmap + Progress log + Blockers tell you where you are.
2. Run the pre-flight check above. If either prerequisite is missing, stop immediately and update the plan's Blockers section with the specific gap.
3. `ls lib/koka/` — pick up from the most advanced file that exists. If the directory does not exist, you are at Phase 1.
4. If `lib/koka/tests/*.sx` exist, run them via the epoch protocol against `sx_server.exe`. They must be green before new work.

## The queue

Phase order per `plans/koka-on-sx.md`:

- **Phase 1** — tokenizer + parser (consuming `lib/guest/lex.sx` + `lib/guest/pratt.sx`)
- **Phase 2** — ADT definitions + match (consuming `lib/guest/match.sx`)
- **Phase 3** — core evaluator (pure expressions, no effects yet)
- **Phase 4** — **effect system** (the headline phase — see discipline section below)
- **Phase 5** — standard effect library (`console`, `exn`, `state<s>`, `async`)
- **Phase 6** — classic Koka programs as integration tests (counter, choice, iterator, exception, coroutine)

Within a phase, pick the checkbox with the best tests-per-effort ratio.

Every iteration: implement → test → commit → tick `[ ]` in plan → append Progress log → push → next.

## Substrate-validation discipline (the multi-shot test)

The reason Koka exists in this set is to verify that SX's `cek-resume` supports **multi-shot continuations**. The Phase 4 commit that lands `choose() -> resume(True) ++ resume(False)` returning `[True, True, False, True]` is the single most important commit in this whole plan. Everything before it is scaffolding; everything after it is filling out the language.

After every Phase 4 commit, append to the Progress log a line stating which resumption pattern was exercised:

- **No resume** (handler `return(x) -> e` only) — value pass-through.
- **Tail resumption** (`op() -> resume(v)`) — handler resumes exactly once, in tail position. Should be optimisable; verify no extra allocation.
- **Single resume not in tail** (`op() -> let x = resume(v) in compute(x)`) — handler resumes once, then does work after.
- **Multi-shot** (`choose() -> resume(True) ++ resume(False)`) — handler resumes the same continuation twice.
- **Zero resume** (handler returns without calling resume) — abort/escape semantics.

A handler that compiles but does the wrong thing under multi-shot is a substrate bug, not a Koka bug. Open a Blockers entry, do not fix the substrate from this loop.

## Ground rules (hard)

- **Scope:** only `lib/koka/**` and `plans/koka-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, `lib/guest/**` (read-only consumer), or other `lib/<lang>/`.
- **Consume `lib/guest/`** wherever it covers a need (lex, pratt, match). Hand-rolling defeats the validation goal.
- **Do not patch the substrate from this loop.** If `cek-resume` is misbehaving, write the failing test, open a Blockers entry, stop. The fix lives in `spec/evaluator.sx` and is not your scope.
- **Effect types are deferred entirely.** Track effects at runtime only — an unhandled effect at the top level raises a runtime error, not a type error. No row polymorphism.
- **NEVER call `sx_build`.** 600s watchdog will kill you. If `sx_server.exe` is broken, add a Blockers entry and stop.
- **SX files:** `sx-tree` MCP tools ONLY. `sx_validate` after every edit. Never `Edit`/`Read`/`Write` on `.sx`.
- **Worktree:** commit, then push to `origin/loops/koka`. Never touch `main`. Never push to `architecture`.
- **Commit granularity:** one feature per commit. Short factual messages: `koka: state effect handler + 4 tests`.
- **Plan file:** update Progress log + tick boxes every commit.
- **If blocked** for two iterations on the same issue, add to Blockers and move on.

## Koka-specific gotchas

- **Effects are dynamically scoped, not lexically.** When an effect operation `op()` fires inside a function called from inside a handler, the *call-time* handler stack matters, not the *definition-time* environment. This is the opposite of normal lexical scope. SX's `perform`/`cek-resume` is dynamically scoped by construction — that's why the mapping works.
- **Handler installation is `with handler { body }`, not a function call.** The handler is installed for the dynamic extent of `body`. Implement as a `with-handler` evaluator form, not as a lambda taking a body argument — the body must run *inside* the handler frame, not be passed *into* a handler-creating call.
- **`resume` is bound by the handler clause, not globally.** Each operation clause `op(args) -> body` exposes `resume` as a callable inside `body`. `resume(v)` continues the suspended computation with `v` as the value of the original `op()` call. Implement by capturing the continuation at the `perform` point and binding it to `resume` in the clause's env.
- **`return(x) -> e` is the value clause.** When the handled body finishes without firing the effect, its value is bound to `x` in this clause and the result is `e`. If absent, default is `return(x) -> x`. This is *not* the same as a normal function return.
- **Tail-resumptive handlers should be optimisable.** Most practical handlers (`state.get() -> resume(s)`, `console.println(s) -> { print(s); resume(()) }`) resume exactly once in tail position. The CEK should be able to detect this and skip the continuation capture entirely. If you discover the optimisation is missing, that's substrate work — open a Blockers entry, do not implement here.
- **`type maybe<a> { Nothing; Just(value: a) }`.** Map directly to SX `(define-type maybe (Nothing) (Just value))`. Polymorphism erased at runtime — the type parameter is for documentation/future inference, not for evaluation.
- **Pipe `|>` is reverse application.** `x |> f |> g` = `g(f(x))`. Parse as left-associative infix at low precedence.
- **No type inference, no exhaustiveness checking.** Phase 2 match falls back to runtime `match-failure` exception on no clause hit. Don't try to verify exhaustiveness statically.

## 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.
- Shell heredoc `||` gets eaten — escape or use `case`.

## Style

- No comments in `.sx` unless non-obvious.
- No new planning docs — update `plans/koka-on-sx.md` inline.
- Short, factual commit messages (`koka: multi-shot choose + 3 tests`).
- One feature per iteration. Commit. Log. Push. Next.

Go. Run the pre-flight check. If lib-guest or the ADT primitive is not in place, stop and report. Otherwise read the plan, find the first unchecked `[ ]`, implement it.