# OCaml-on-SX: OCaml + ReasonML + Dream on the CEK/VM

The meta-circular demo: SX's native evaluator is OCaml, so implementing OCaml on top of
SX closes the loop — the source language of the host is running inside the host it
compiles to. Beyond the elegance, it's practically useful: once OCaml expressions run on
the SX CEK/VM you get Dream (a clean OCaml web framework) almost for free, and ReasonML
is a syntax variant that shares the same transpiler output.

End-state goal: **OCaml programs running on the SX CEK/VM**, with enough of the standard
library to support Dream's middleware model. Dream-on-SX is the integration target —
a `handler`/`middleware`/`router` API that feels idiomatic while running purely in SX.
ReasonML (Phase 8) adds an alternative syntax frontend that targets the same transpiler.

## What this covers that nothing else in the set does

- **Strict ML semantics** — unlike Haskell, OCaml is call-by-value with explicit `Lazy.t`
  for laziness. Pattern match is exhaustive. Polymorphic variants. Structural equality.
- **First-class modules and functors** — modules as values (phase 4); functors as SX
  higher-order functions over module records. Unlike Haskell typeclasses, OCaml's module
  system is explicit and compositional.
- **Mutable state without monads** — `ref`, `:=`, `!` are primitives. Arrays. `Hashtbl`.
  The IO model is direct; `Lwt`/Dream map to `perform`/`cek-resume` for async.
- **Dream's composable HTTP model** — `handler = request -> response promise`,
  `middleware = handler -> handler`. Algebraically clean; `@@` composition maps to SX
  function composition trivially.
- **ReasonML** — same semantics, JS-friendly surface syntax. JSX variant pairs with SX
  component rendering.

## Ground rules

- **Scope:** only touch `lib/ocaml/**`, `lib/dream/**`, `lib/reasonml/**`, and
  `plans/ocaml-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, or other
  `lib/<lang>/`.
- **Shared-file issues** go under "Blockers" below with a minimal repro; do not fix here.
- **SX files:** use `sx-tree` MCP tools only.
- **Architecture:** OCaml source → AST → SX AST → CEK. No standalone OCaml evaluator.
  The OCaml AST is walked by an `ocaml-eval` function in SX that produces SX values.
- **Type system:** deferred until Phase 5. Phases 1–4 are intentionally untyped —
  get the evaluator right first, then layer HM inference on top.
- **Dream:** implemented as a library in Phase 7; no separate build step. `Dream.run`
  wraps SX's existing HTTP server machinery via `perform`/`cek-resume`.
- **Commits:** one feature per commit. Keep `## Progress log` updated and tick boxes.

## Architecture sketch

```
OCaml source text
    │
    ▼
lib/ocaml/tokenizer.sx   — keywords, operators, string/char literals, comments
    │
    ▼
lib/ocaml/parser.sx      — OCaml AST: let/let rec, fun, match, if, begin/end,
    │                      module/struct/functor, type decls, expressions
    ▼
lib/ocaml/desugar.sx     — surface → core: tuple patterns, or-patterns,
    │                      sequence (;) → (do), when guards, field punning
    ▼
lib/ocaml/transpile.sx   — OCaml AST → SX AST
    │
    ▼
lib/ocaml/runtime.sx     — ADT constructors, module primitives, ref/array ops,
    │                      Stdlib shims, Dream server (phase 7)
    ▼
SX CEK evaluator (both JS and OCaml hosts)
```

## Semantic mappings

| OCaml construct | SX mapping |
|----------------|-----------|
| `let x = e` (top-level) | `(define x e)` |
| `let f x y = e` | `(define (f x y) e)` |
| `let rec f x = e` | `(define (f x) e)` — SX define is already recursive |
| `fun x -> e` | `(fn (x) e)` |
| `e1 \|> f` | `(f e1)` — pipe desugars to reverse application |
| `e1; e2` | `(do e1 e2)` |
| `begin e1; e2; e3 end` | `(do e1 e2 e3)` |
| `if c then e1 else e2` | `(if c e1 e2)` |
| `match x with \| P -> e` | `(match x (P e) ...)` via Phase 6 ADT primitive |
| `type t = A \| B of int` | `(define-type t (A) (B v))` |
| `module M = struct ... end` | SX dict `{:let-bindings ...}` — module as record |
| `functor (M : S) -> ...` | `(fn (M) ...)` — functor as SX lambda over module record |
| `open M` | inject M's bindings into scope via `env-merge` |
| `M.field` | `(get M :field)` |
| `{ r with f = v }` | `(dict-set r :f v)` |
| `ref x` | `(make-ref x)` — mutable cell |
| `!r` | `(deref-ref r)` |
| `r := v` | `(set-ref! r v)` |
| `(a, b, c)` | tagged list `(:tuple a b c)` |
| `[1; 2; 3]` | `(list 1 2 3)` |
| `[| 1; 2; 3 |]` | `(make-array 1 2 3)` (Phase 6) |
| `try e with \| Ex -> h` | `(guard (fn (ex) h) e)` via SX exception system |
| `raise Ex` | `(perform (:raise Ex))` |
| `Printf.printf "%d" x` | `(perform (:print (format "%d" x)))` |

## Dream semantic mappings (Phase 7)

| Dream construct | SX mapping |
|----------------|-----------|
| `handler = request -> response promise` | `(fn (req) (perform (:http-respond ...)))` |
| `middleware = handler -> handler` | `(fn (next) (fn (req) ...))` |
| `Dream.router [routes]` | `(ocaml-dream-router routes)` — dispatch on method+path |
| `Dream.get "/path" h` | route record `{:method "GET" :path "/path" :handler h}` |
| `Dream.scope "/p" [ms] [rs]` | prefix mount with middleware chain |
| `Dream.param req "name"` | path param extracted during routing |
| `m1 @@ m2 @@ handler` | `(m1 (m2 handler))` — left-fold composition |
| `Dream.session_field req "k"` | `(perform (:session-get req "k"))` |
| `Dream.set_session_field req "k" v` | `(perform (:session-set req "k" v))` |
| `Dream.flash req` | `(perform (:flash-get req))` |
| `Dream.form req` | `(perform (:form-parse req))` — returns Ok/Error ADT |
| `Dream.websocket handler` | `(perform (:websocket handler))` |
| `Dream.run handler` | starts SX HTTP server with handler as root |

## Roadmap

### Phase 1 — Tokenizer + parser

- [x] **Tokenizer:** keywords (`let`, `rec`, `in`, `fun`, `function`, `match`, `with`,
      `type`, `of`, `module`, `struct`, `end`, `functor`, `sig`, `open`, `include`,
      `if`, `then`, `else`, `begin`, `try`, `exception`, `raise`, `mutable`,
      `for`, `while`, `do`, `done`, `and`, `as`, `when`), operators (`->`, `|>`,
      `<|`, `@@`, `@`, `:=`, `!`, `::`, `**`, `:`, `;`, `;;`), identifiers (lower,
      upper/ctor), char literals `'c'`, string literals (escaped),
      int/float literals (incl. hex, exponent, underscores), nested block
      comments `(* ... *)`. _(labels `~label:` / `?label:` and heredoc `{|...|}`
      deferred — surface tokens already work via `~`/`?` punct + `{`/`|` punct.)_
- [~] **Parser:** expressions: literals, identifiers, constructor application,
      lambda, application (left-assoc), binary ops with precedence (29 ops via
      `lib/guest/pratt.sx`), `if`/`then`/`else`, `let`/`in`, `let rec`,
      `fun`/`->`, `match`/`with`, tuples, list literals, sequences `;`,
      `begin`/`end`, unit `()`. Top-level decls: `let [rec] name params* = expr`
      and bare expressions, `;;`-separated via `ocaml-parse-program`. _(Pending:
      `type`/`module`/`exception`/`open`/`include` decls, `try`/`with`,
      `function`, record literals/updates, field access, `and` mutually-recursive
      bindings.)_
- [~] **Patterns:** constructor (nullary + with args, incl. flattened tuple
      args `Pair (a, b)` → `(:pcon "Pair" PA PB)`), literal (int/string/char/
      bool/unit), variable, wildcard `_`, tuple, list cons `::`, list
      literal, `as` binding (`pat as name`). Match clauses support `when`
      guard via `(:case-when PAT GUARD BODY)`. _(Pending: record patterns,
      or-pattern `P1 | P2` — ambiguous with clause separator without
      lookahead.)_
- [ ] OCaml is **not** indentation-sensitive — no layout algorithm needed.
- [ ] Tests in `lib/ocaml/tests/parse.sx` — 50+ round-trip parse tests.

### Phase 2 — Core evaluator (untyped)

- [x] `ocaml-eval` entry: walks OCaml AST, produces SX values.
- [x] `let`/`let rec`/`let ... in`. Mutually recursive `let rec f = … and
      g = …` works at top level via `(:def-rec-mut BINDINGS)`; placeholders
      are bound first, rhs evaluated in the joint env, cells filled in.
      `let x = … and y = …` (non-rec) emits `(:def-mut BINDINGS)` —
      sequential bindings against the parent env.
- [x] Lambda + application (curried by default — auto-curry multi-param defs).
- [x] `fun`/`function` (single-arg lambda with immediate match on arg).
- [x] `if`/`then`/`else`, `begin`/`end`, sequence `;`.
- [x] Arithmetic, comparison, boolean ops, string `^`, `mod`.
- [x] Unit `()` value; `ignore`.
- [x] References: `ref`, `!`, `:=`.
- [ ] Mutable record fields.
- [x] `for i = lo to hi do ... done` loop; `while cond do ... done` (incl.
      `downto` direction).
- [x] `try`/`with` — maps to SX `guard`; `raise` is a builtin that calls
      host SX `raise`. `failwith` and `invalid_arg` ship as builtins.
- [ ] Tests in `lib/ocaml/tests/eval.sx` — 50+ tests, pure + imperative.

### Phase 3 — ADTs + pattern matching

- [ ] `type` declarations: `type t = A | B of t1 * t2 | C of { x: int }`.
      _(Parser + evaluator currently inferred-arity at runtime; type decls
      pending.)_
- [x] Constructors as tagged lists: `A` → `("A")`, `B(1, "x")` → `("B" 1 "x")`.
- [~] `match`/`with`: constructor, literal, variable, wildcard, tuple, list
      cons/nil, nested patterns. _(Pending: `as` binding, or-patterns,
      `when` guard.)_
- [x] Exhaustiveness: runtime error on incomplete match (no compile-time check yet).
- [ ] Built-in types: `option` (`None`/`Some`), `result` (`Ok`/`Error`),
      `list` (nil/cons), `bool`, `unit`, `exn`.
- [ ] `exception` declarations; built-in: `Not_found`, `Invalid_argument`,
      `Failure`, `Match_failure`.
- [ ] Polymorphic variants (surface syntax `\`Tag value`; runtime same tagged list).
- [ ] Tests in `lib/ocaml/tests/adt.sx` — 40+ tests: ADTs, match, option/result.

### Phase 4 — Modules + functors

- [x] `module M = struct let x = 1 let f y = x + y end` → SX dict
      `{"x" 1 "f" <fn>}`.
- [~] `module type S = sig val x : int val f : int -> int end` — signature
      annotations are parsed-and-skipped (`skip-optional-sig`); typed
      checking deferred to Phase 5.
- [x] `module M : S = struct ... end` — coercive sealing (signature ignored).
- [x] `functor (M : S) -> struct ... end` via shorthand `module F (M) = …`.
- [x] `module F = Functor(Base)` — functor application; multi-param via
      `module P = F(A)(B)`.
- [x] `open M` — merge M's dict into current env (via
      `ocaml-env-merge-dict`). Module path `M.Sub` resolves via
      `ocaml-resolve-module-path`.
- [x] `include M` — at top level same as `open`; inside a module also
      copies M's bindings into the surrounding module's exports.
- [x] `M.name` — dict get via field access.
- [ ] First-class modules (pack/unpack) — deferred to Phase 5.
- [ ] Standard module hierarchy: `List`, `Option`, `Result`, `String`, `Char`,
      `Int`, `Float`, `Bool`, `Unit`, `Printf`, `Format` (stubs, filled in Phase 6).
- [ ] Tests in `lib/ocaml/tests/modules.sx` — 30+ tests.

### Phase 5.1 — Conformance scoreboard

- [x] `lib/ocaml/conformance.sh` runs the full test suite, classifies
      each test by description prefix into a suite (tokenize, parser,
      eval-core, phase2-refs, phase2-loops, phase2-function, phase2-exn,
      phase3-adt, phase4-modules, phase5-hm, phase6-stdlib, let-and,
      phase1-params, misc), and emits `scoreboard.json` + `scoreboard.md`.
- [ ] Vendor a slice of the OCaml testsuite at `lib/ocaml/baseline/`
      and feed it through `ocaml-run-program`, scoring per-file
      conformance. _(Pending — needs more stdlib coverage and ADT type
      decls to make most testsuite files runnable.)_

### Phase 5 — Hindley-Milner type inference

- [~] Algorithm W: `gen`/`inst` from `lib/guest/hm.sx`, `unify` from
      `lib/guest/match.sx`, `infer-expr` written here. Covers atoms, var,
      lambda, app, let, if, op, neg, not. _(Pending: tuples, lists,
      pattern matching, let-rec, modules.)_
- [x] Type variables: `'a`, `'b`; unification with occur-check (kit).
- [x] Let-polymorphism: generalise at let-bindings (kit `hm-generalize`).
- [ ] ADT types: `type 'a option = None | Some of 'a`.
- [~] Function types `T1 -> T2` work; tuples/records pending.
- [ ] Type signatures: `val f : int -> int` — verify against inferred type.
- [ ] Module type checking: seal against `sig` (Phase 4 stubs become real checks).
- [ ] Error reporting: position-tagged errors with expected vs actual types.
- [ ] First-class modules: `(module M : S)` pack; `(val m : (module S))` unpack.
- [ ] No rank-2 polymorphism, no GADTs (out of scope).
- [ ] Tests in `lib/ocaml/tests/types.sx` — 60+ inference tests.

### Phase 6 — Standard library

- [~] `List`: `map`, `filter`, `fold_left`, `fold_right`, `length`, `rev`,
      `append`, `iter`, `for_all`, `exists`, `mem`, `nth`, `hd`, `tl`,
      `rev_append`. _(Pending: concat/flatten, iteri/mapi, find/find_opt,
      assoc/assq, sort, init, combine, split, partition.)_
- [~] `Option`: `map`, `bind`, `value`, `get`, `is_none`, `is_some`.
      _(Pending: fold/join/iter/to_list/to_result.)_
- [~] `Result`: `map`, `bind`, `is_ok`, `is_error`. _(Pending:
      fold/get_ok/get_error/map_error/to_option.)_
- [~] `String`: `length`, `get`, `sub`, `concat`, `uppercase_ascii`,
      `lowercase_ascii`, `starts_with`. _(Pending: split_on_char, trim,
      contains, ends_with, index_opt, replace_all.)_
- [~] `Char`: `code`, `chr`, `lowercase_ascii`, `uppercase_ascii`.
      _(Pending: escaped.)_
- [~] `Int`: `to_string`, `of_string`, `abs`, `max`, `min`.
      _(Pending: arithmetic helpers, min_int/max_int.)_
- [~] `Float`: `to_string`. _(Pending: of_string, arithmetic helpers.)_
- [~] `Printf`: stub `sprintf`/`printf`. _(Real format-string
      interpretation pending.)_
- [ ] `String`: `length`, `get`, `sub`, `concat`, `split_on_char`, `trim`,
      `uppercase_ascii`, `lowercase_ascii`, `contains`, `starts_with`, `ends_with`,
      `index_opt`, `replace_all` (non-stdlib but needed).
- [ ] `Char`: `code`, `chr`, `escaped`, `lowercase_ascii`, `uppercase_ascii`.
- [ ] `Int`/`Float`: arithmetic, `to_string`, `of_string_opt`, `min_int`, `max_int`.
- [ ] `Hashtbl`: `create`, `add`, `replace`, `find`, `find_opt`, `remove`, `mem`,
      `iter`, `fold`, `length` — backed by SX mutable dict.
- [ ] `Map.Make` functor — balanced BST backed by SX sorted dict.
- [ ] `Set.Make` functor.
- [ ] `Printf`: `sprintf`, `printf`, `eprintf` — format strings via `(format ...)`.
- [ ] `Sys`: `argv`, `getenv_opt`, `getcwd` — via `perform` IO.
- [ ] Scoreboard runner: `lib/ocaml/conformance.sh` + `scoreboard.json`.
- [ ] Target: 150+ tests across all stdlib modules.

### Phase 7 — Dream web framework (`lib/dream/`)

The five types: `request`, `response`, `handler = request -> response`,
`middleware = handler -> handler`, `route`. Everything else is a function over these.

- [ ] **Core types** in `lib/dream/types.sx`: request/response records, route record.
- [ ] **Router** in `lib/dream/router.sx`:
      - `dream-get path handler`, `dream-post path handler`, etc. for all HTTP methods.
      - `dream-scope prefix middlewares routes` — prefix mount with middleware chain.
      - `dream-router routes` — dispatch tree, returns handler; no match → 404.
      - Path param extraction: `:name` segments, `**` wildcard.
      - `dream-param req name` — retrieve matched path param.
- [ ] **Middleware** in `lib/dream/middleware.sx`:
      - `dream-pipeline middlewares handler` — compose middleware left-to-right.
      - `dream-no-middleware` — identity.
      - Logger: `(dream-logger next req)` — logs method, path, status, timing.
      - Content-type sniffer.
- [ ] **Sessions** in `lib/dream/session.sx`:
      - Cookie-backed session middleware.
      - `dream-session-field req key`, `dream-set-session-field req key val`.
      - `dream-invalidate-session req`.
- [ ] **Flash messages** in `lib/dream/flash.sx`:
      - `dream-flash-middleware` — single-request cookie store.
      - `dream-add-flash-message req category msg`.
      - `dream-flash-messages req` — returns list of `(category, msg)`.
- [ ] **Forms + CSRF** in `lib/dream/form.sx`:
      - `dream-form req` — returns `(Ok fields)` or `(Err :csrf-token-invalid)`.
      - `dream-multipart req` — streaming multipart form data.
      - CSRF middleware: stateless signed tokens, session-scoped.
      - `dream-csrf-tag req` — returns hidden input fragment for SX templates.
- [ ] **WebSockets** in `lib/dream/websocket.sx`:
      - `dream-websocket handler` — upgrades request; handler `(fn (ws) ...)`.
      - `dream-send ws msg`, `dream-receive ws`, `dream-close ws`.
- [ ] **Static files:** `dream-static root-path` — serves files, ETags, range requests.
- [ ] **`dream-run`**: wires root handler into SX's `perform (:http-listen ...)`.
- [ ] **Demos** in `lib/dream/demos/`:
      - `hello.ml` → `lib/dream/demos/hello.sx`: "Hello, World!" route.
      - `counter.ml` → `lib/dream/demos/counter.sx`: in-memory counter with sessions.
      - `chat.ml` → `lib/dream/demos/chat.sx`: multi-room WebSocket chat.
      - `todo.ml` → `lib/dream/demos/todo.sx`: CRUD list with forms + CSRF.
- [ ] Tests in `lib/dream/tests/`: routing dispatch, middleware composition,
      session round-trip, CSRF accept/reject, flash read-after-write — 60+ tests.

### Phase 8 — ReasonML syntax variant (`lib/reasonml/`)

ReasonML is OCaml with a JS-friendly surface: semicolons, `let` with `=` everywhere,
`=>` for lambdas, `switch` for match, `{j|...|j}` string interpolation. Same semantics —
different tokenizer + parser, same `lib/ocaml/transpile.sx` output.

- [ ] **Tokenizer** in `lib/reasonml/tokenizer.sx`:
      - `let x = e;` binding syntax (semicolons required).
      - `(x, y) => e` arrow function syntax.
      - `switch (x) { | Pat => e | ... }` for match.
      - JSX: `<Comp prop=val />`, `<div>children</div>`.
      - String interpolation: `{j|hello $(name)|j}`.
      - Type annotations: `x : int`, `let f : int => int = x => x + 1`.
- [ ] **Parser** in `lib/reasonml/parser.sx`:
      - Produce same OCaml AST nodes as `lib/ocaml/parser.sx`.
      - JSX → SX component calls: `<Comp x=1 />` → `(~comp :x 1)`.
      - Multi-arg functions: `(x, y) => e` → auto-curried pair.
- [ ] Shared transpiler: `lib/reasonml/transpile.sx` delegates to
      `lib/ocaml/transpile.sx` (parse → ReasonML AST → OCaml AST → SX AST).
- [ ] Tests in `lib/reasonml/tests/`: tokenizer, parser, eval, JSX — 40+ tests.
- [ ] ReasonML Dream demos: translate Phase 7 demos to ReasonML syntax.

## The meta-circular angle

SX is bootstrapped to OCaml (`hosts/ocaml/`). Running OCaml inside SX running on OCaml is
the "mother tongue" closure: OCaml → SX → OCaml. This means:

- The OCaml host's native pattern matching and ADTs are exact reference semantics for
  the SX-level implementation — any mismatch is a bug.
- The SX `match` / `define-type` primitives (Phase 6 of the primitives roadmap) were
  built knowing OCaml was the intended target.
- When debugging the transpiler, the OCaml REPL is always available as oracle.
- Dream running in SX can serve the sx.rose-ash.com docs site — the framework that
  describes the runtime it runs on.

## Key dependencies

- **Phase 6 ADT primitive** (`define-type`/`match`) — required before Phase 3.
- **`perform`/`cek-resume`** IO suspension — required before Phase 7 (Dream async).
- **HO forms** and first-class lambdas — already in spec, no blocker.
- **Module system** (Phase 4) is independent of type inference (Phase 5) — can overlap.
- **ReasonML** (Phase 8) can start once OCaml parser is stable (after Phase 2).

## Progress log

_Newest first._

- 2026-05-08 Phase 3 — `as` aliases + `when` guards in match (+6 tests,
  295 total). Parser: pattern parser wraps with `as ident` → `(:pas
  PAT NAME)`. Match's `one` consumes optional `when GUARD-EXPR` → emits
  `(:case-when PAT GUARD BODY)` instead of `:case`. Eval `:pas` matches
  inner pattern then also binds the alias name; `case-when` checks the
  guard after a successful match and falls through if false. Or-pat
  `(P1 | P2)` deferred — ambiguous with clause separator without
  parens-only support.
- 2026-05-08 Phase 1+2 — record literals `{ x = 1; y = 2 }` and
  functional update `{ r with x = 99 }`. Parser produces `(:record (F E)
  ...)` and `(:record-update BASE-EXPR (F E) ...)`. Eval builds a dict
  from field bindings; record-update merges over the base dict (the same
  dict-based representation we already use for modules). Field access
  via existing `:field` postfix. Record patterns deferred. 289/289 (+6).
- 2026-05-08 Phase 5.1 — `lib/ocaml/conformance.sh` + `scoreboard.json`
  + `scoreboard.md`. Classifies tests into 14 suites by description
  prefix and emits structured pass/fail counts. Current: 284 pass / 0
  fail (one test counted twice in classifier, hence 284 vs 283
  underlying). Vendoring real OCaml testsuite is the next step but
  needs more stdlib coverage to make .ml files runnable end-to-end.
- 2026-05-08 Phase 1 — unit `()` and wildcard `_` parameters in `let f ()
  = …` / `fun _ -> …` / `let f _ = …`. Parser helper `try-consume-param!`
  now handles ident, wildcard `_` (renamed to `__wild_N`), unit `()`
  (renamed to `__unit_N`), and typed `(x : T)` (signature skipped).
  Same for top-level `parse-decl-let`. test.sh timeout extended from
  60s to 180s for the growing suite. 283/283 (+5).
- 2026-05-08 Phase 6 — extended stdlib slice (+13 tests, 278 total).
  Host primitives exposed via `_string_*`, `_char_*`, `_int_*`,
  `_string_of_*` underscore-prefixed builtins so the OCaml-side
  `lib/ocaml/runtime.sx` modules can wrap them: String (length, get,
  sub, concat, uppercase_ascii, lowercase_ascii, starts_with), Char
  (code, chr, lowercase_ascii, uppercase_ascii), Int (to_string,
  of_string, abs, max, min), Float.to_string, Printf stubs. Also added
  `print_string`/`print_endline`/`print_int` builtins.
- 2026-05-08 Phase 5 — Hindley-Milner type inference, paired-sequencing
  consumer of `lib/guest/hm.sx` (algebra) and `lib/guest/match.sx`
  (unify). `lib/ocaml/infer.sx` ships Algorithm W rules for OCaml AST:
  atoms, var (instantiate), fun (auto-curry through fresh-tv), app
  (unify against arrow), let (generalize over rhs), if (unify branches),
  neg/not, op (treat as app of builtin). Builtin env types `+`/`-`/etc.
  as monomorphic int->int->int and `=`/`<>` as polymorphic 'a->'a->bool.
  Tested: literals, +1, identity polymorphism `'a -> 'a`, let-poly so
  `let id = fun x -> x in id true : Bool`, `twice` infers
  `('a -> 'a) -> 'a -> 'a`. Mandate satisfied: OCaml-on-SX is the
  deferred second consumer for lib-guest Step 8. 265/265 (+14).
- 2026-05-08 Phase 2 — `let ... and ...` mutual recursion at top level.
  Parser collects all bindings into a list, emitting `(:def-rec-mut)` or
  `(:def-mut)` when there are 2+. Eval allocates a placeholder cell per
  recursive binding, builds an env with all of them visible, then fills
  the cells. Even/odd mutual-recursion test passes. 251/251 (+3).
- 2026-05-08 Phase 6 — `lib/ocaml/runtime.sx` minimal stdlib slice
  written entirely in OCaml syntax: List (length, rev, rev_append, map,
  filter, fold_left/right, append, iter, mem, for_all, exists, hd, tl,
  nth), Option (map, bind, value, get, is_none, is_some), Result (map,
  bind, is_ok, is_error). Loaded once via `ocaml-load-stdlib!`, cached
  in `ocaml-stdlib-env`; `ocaml-run` and `ocaml-run-program` layer user
  code on top via `ocaml-base-env`. The fact that these are written in
  OCaml (not SX) and parse + evaluate cleanly is a substrate-validation
  win: every parser, eval, match, ref, and module path proven by a
  single nontrivial Ocaml program. 248/248 (+23).
- 2026-05-08 Phase 4 — functors + module aliases (+5 tests, 225 total).
  Parser: `module F (M) = struct DECLS end` → `(:functor-def NAME PARAMS
  DECLS)`. `module N = expr` (where expr isn't `struct`) → `(:module-alias
  NAME BODY-SRC)`. Functor params accept `(P)` or `(P : Sig)` (signatures
  parsed-and-skipped). Eval: `ocaml-make-functor` builds a curried
  host-SX closure that takes module dicts and returns a module dict;
  `ocaml-resolve-module-path` extended for `:app` so `F(A)`, `F(A)(B)`,
  `Outer.Inner` all resolve to dicts. Tested: 1-arg functor, 2-arg
  curried `Pair(One)(Two)`, module alias, submodule alias, identity
  functor with include. Phase 4 LOC ~290 (still well under 2000).
- 2026-05-08 Phase 4 — `open M` / `include M` (+5 tests, 220 total).
  Parser: top-level `open Path` / `include Path` decls; path is `Ctor (.
  Ctor)*`. Eval resolves the path via `ocaml-resolve-module-path` (the
  same `:con`-as-module-lookup escape hatch used for `:field`); merges
  the dict bindings into the current env via `ocaml-env-merge-dict`.
  `include` inside a module also adds the bindings to the module's
  resulting dict, so `module Sphere = struct include Math let area r =
  ... end` exposes both Math's `pi` and Sphere's `area`. Phase 4 LOC
  cumulative: ~165.
- 2026-05-08 Phase 4 — modules + field access (+11 tests, 215 total). Parser:
  `module M = struct DECLS end` decl in `ocaml-parse-program`. Body parsed
  by sub-tokenising the source between `struct` and the matching `end`,
  tracking nesting via `struct`/`begin`/`sig`/`end`. Field access added
  as a postfix layer above `parse-atom`, binding tighter than application:
  `f r.x` → `(:app f (:field r "x"))`. Eval: `(:module-def NAME DECLS)`
  builds a dict via new `ocaml-eval-module` that runs decls in a sub-env;
  `(:field EXPR NAME)` looks up the field, with the special case that
  `(:con NAME)` heads are interpreted as module-name lookups instead of
  nullary ctors. Tested: simple module, multi-decl module, nested modules
  (`Outer.Inner.v`), `let rec` inside a module, module containing tuple
  pattern match. Phase 4 LOC: ~110 (well under 2000 budget).
- 2026-05-08 Phase 2 — `try`/`with` + `raise` builtin. Parser produces
  `(:try EXPR CLAUSES)`; eval delegates to SX `guard` with `else`
  matching the raised value against clause patterns and re-raising on
  no-match. `raise`/`failwith`/`invalid_arg` exposed as builtins;
  failwith builds `("Failure" msg)` so `Failure msg -> ...` patterns
  match. 204/204 (+6).
- 2026-05-08 Phase 2 — `function | pat -> body | …` parser + eval.
  Sugar for `fun x -> match x with | …`. AST: `(:function CLAUSES)`
  evaluated to a unary closure that runs `ocaml-match-clauses` on the
  argument. `let rec` knot also triggers when rhs is `:function`, so
  `let rec map f = function | [] -> [] | h::t -> f h :: map f t` works.
  ocaml-match-eval refactored to share `ocaml-match-clauses` with the
  function form. 198/198 (+4).
- 2026-05-08 Phase 2 — `for`/`while` loops. `(:for NAME LO HI DIR BODY)`
  with `:ascend`/`:descend` direction (`to`/`downto`); `(:while COND BODY)`.
  Both eval to unit and re-bind the loop var per iteration. 194/194 (+5).
- 2026-05-08 Phase 2 — references (`ref`/`!`/`:=`). `ref` is a builtin
  that boxes its argument in a one-element list (the mutable cell);
  prefix `!` parses to `(:deref EXPR)` and reads `(nth cell 0)`; `:=`
  joins the precedence table at the lowest binop level (right-assoc) and
  short-circuits in eval to mutate via `set-nth!`. Closures capture refs
  by sharing the underlying list. 189/189 (+6).
- 2026-05-08 Phase 3 — pattern matching evaluator + constructors (+18
  tests, 183 total). Constructor application: `(:app (:con NAME) arg)`
  builds a tagged list `(NAME …args)` with tuple args flattened (so
  `Pair (a, b)` → `("Pair" a b)` matches the parser's pattern flatten).
  Standalone ctor `(:con NAME)` → `(NAME)` (nullary). Pattern matcher:
  :pwild / :pvar / :plit (unboxed compare) / :pcon (head + arity match) /
  :pcons (cons-decompose) / :plist (length+items) / :ptuple (after `tuple`
  tag). Match drives clauses until first success; runtime error on
  exhaustion. Tested with option match, literal match, tuple match,
  recursive list functions (`len`, `sum`), nested ctor (`Pair(a,b)`).
  Note: arity flattening happens for any tuple-arg ctor — without ADT
  declarations there's no way to distinguish `Some (1,2)` (single tuple
  payload) from `Pair (1,2)` (two-arg ctor). All-flatten convention is
  consistent across parser + evaluator.
- 2026-05-08 Phase 2 — `lib/ocaml/eval.sx`: ocaml-eval + ocaml-run +
  ocaml-run-program. Coverage: atoms, var lookup, :app (curried),
  :op (arithmetic/comparison/boolean/^/mod/::/|>), :neg, :not, :if,
  :seq, :tuple, :list, :fun (auto-curried host-SX closures), :let,
  :let-rec (recursive knot via one-element-list mutable cell). Initial
  env exposes `not`/`succ`/`pred`/`abs`/`max`/`min`/`fst`/`snd`/`ignore`
  as host-SX functions. Tests: literals, arithmetic, comparison, boolean,
  string concat, conditionals, lambda + closures + recursion (fact 5,
  fib 10, sum 100), sequences, top-level program decls, |> pipe. 165/165
  passing (+42).
- 2026-05-07 Phase 1 — sequence operator `;`. Lowest-precedence binary;
  `e1; e2; e3` → `(:seq e1 e2 e3)`. Two-phase grammar: `parse-expr-no-seq`
  is the prior expression entry point; new `parse-expr` wraps it with
  `;` chaining. List-literal items still use `parse-expr-no-seq` so `;`
  retains its separator role inside `[…]`. Match-clause bodies use the
  seq variant and stop at `|`, matching real OCaml semantics. Trailing `;`
  before `end`/`)`/`|`/`in`/`then`/`else`/eof is permitted. 123/123 tests
  passing (+10).
- 2026-05-07 Phase 1 — `match`/`with` + pattern parser. Patterns: wildcard,
  literal, var, ctor (nullary + with arg, with tuple-arg flattening so
  `Pair (a, b)` → `(:pcon "Pair" PA PB)`), tuple, list literal, cons `::`
  (right-assoc), parens, unit. Match clauses: leading `|` optional, body
  parsed via `parse-expr`. AST: `(:match SCRUT CLAUSES)` where each clause
  is `(:case PAT BODY)`. 113/113 tests passing (+9). Note: parse-expr is
  used for case bodies, so a trailing `| pat -> body` after a complex body
  will be reached because `|` is not in the binop table for level 1.
- 2026-05-07 Phase 1 — top-level program parser `ocaml-parse-program`. Parses
  a sequence of `let [rec] name params* = expr` decls and bare expressions
  separated by `;;`. Output `(:program DECLS)` with each decl one of `(:def …)`,
  `(:def-rec …)`, `(:expr E)`. Decl bodies parsed by re-feeding the source
  slice through `ocaml-parse` (cheap stand-in until shared-state refactor).
  104/104 tests now passing (+9).
- 2026-05-07 Phase 1 — `lib/ocaml/parser.sx` expression parser consuming
  `lib/guest/pratt.sx` for binop precedence (29 operators across 8 levels,
  incl. keyword-spelled binops `mod`/`land`/`lor`/`lxor`/`lsl`/`lsr`/`asr`).
  Atoms (literals + var/con/unit/list), application (left-assoc), prefix
  `-`/`not`, tuples, parens, `if`/`then`/`else`, `fun x y -> body`,
  `let`/`let rec` with function shorthand. AST shapes match Haskell-on-SX
  conventions (`(:int N)` `(:op OP L R)` `(:fun PARAMS BODY)` etc.). Total
  95/95 tests now passing via `lib/ocaml/test.sh`.
- 2026-05-07 Phase 1 — `lib/ocaml/tokenizer.sx` consuming `lib/guest/lex.sx`
  via `prefix-rename`. Covers idents, ctors, 51 keywords, numbers (int / float
  / hex / exponent / underscored), strings (with escapes), chars (with escapes),
  type variables (`'a`), nested block comments, and 26 operator/punct tokens
  (incl. `->` `|>` `<-` `:=` `::` `;;` `@@` `<>` `&&` `||` `**` etc.). 58/58
  tokenizer tests pass via `lib/ocaml/test.sh` driving `sx_server.exe`.

## Blockers

_(none yet)_
