# Lua-on-SX: Lua 5.1 on the CEK/VM

Compile Lua 5.1 AST to SX AST; the existing CEK evaluator runs it. Same architecture as `plans/js-on-sx.md` — reuse SX semantics wherever they fit, only shim the Lua-specific parts (tables/metatables, `nil`/`false`-only-falsy, multi-return, coroutines via `perform`/resume).

End-state goal: **100% of PUC-Rio Lua 5.1.5 test suite.** Running as a long-lived background agent that drives the scoreboard up one failure-mode at a time, like `lib/js/`.

## Ground rules

- **Scope:** only touch `lib/lua/**` and `plans/lua-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, `lib/js/**`, `lib/hyperscript/**`, `lib/prolog/**`, `lib/stdlib.sx`, or anything in `lib/` root. Lua-specific primitives go in `lib/lua/runtime.sx`.
- **Shared-file issues** go under "Blockers" below with a minimal repro; do not fix from this loop.
- **SX files:** use `sx-tree` MCP tools only (never `Edit`/`Read`/`Write` on `.sx` files). `sx_write_file` for new files, path/pattern edits for changes.
- **Architecture:** Lua source → Lua AST → SX AST → CEK. No standalone Lua evaluator.
- **Commits:** one feature per commit. Keep `## Progress log` updated (dated entries, newest first) and tick boxes in the roadmap.

## Architecture sketch

```
Lua source text
    │
    ▼
lib/lua/tokenizer.sx     — numbers, strings (short + long [[…]]), idents, ops, comments
    │
    ▼
lib/lua/parser.sx        — Lua AST as SX trees, e.g. (lua-for-num i a b c body)
    │
    ▼
lib/lua/transpile.sx     — Lua AST → SX AST (entry: lua-eval-ast)
    │
    ▼
existing CEK / VM
```

Runtime shims in `lib/lua/runtime.sx`: `lua-truthy?`, string coercion for `..`/arithmetic, table ops (array + hash part), metatable dispatch, `pcall`/`error` bridge, `string`/`math`/`table` libs.

## Roadmap

Each item: implement → tests → tick box → update progress log.

### Phase 1 — tokenizer + parser
- [ ] Tokenizer: numbers (int, float, hex), strings (short + long `[[…]]`), idents, keywords, operators, comments (`--`, `--[[…]]`)
- [ ] Parser: blocks, `local`, `if/elseif/else/end`, `while`, numeric `for`, `function`, `return`, expressions, table constructors, indexing (`.`, `[]`), calls (`f(…)`, `f:m(…)`)
- [ ] Skip for phase 1: generic `for … in …`, goto/labels, nested varargs `...`
- [ ] Unit tests in `lib/lua/tests/parse.sx`: source → expected AST

### Phase 2 — transpile: control flow + arithmetic
- [ ] `lua-eval-ast` entry
- [ ] Arithmetic (Lua 5.1 semantics — `/` is float)
- [ ] Comparison + logical (short-circuit, Lua truthy)
- [ ] `..` concat with string/number coercion
- [ ] `if`, `while`, numeric `for`, `local`, assignment, blocks
- [ ] 30+ eval tests in `lib/lua/tests/eval.sx`

### Phase 3 — tables + functions + first PUC-Rio slice
- [ ] `function` (anon, local, top-level), closures
- [ ] Multi-return: return as list, unpack at call sites
- [ ] Table constructors (array + hash + computed keys)
- [ ] Raw table access `t.k` / `t[k]` (no metatables yet)
- [ ] Vendor PUC-Rio 5.1.5 suite to `lib/lua/lua-tests/` (just `.lua` files)
- [ ] `lib/lua/conformance.sh` + Python runner (model on `lib/js/test262-runner.py`)
- [ ] `scoreboard.json` + `scoreboard.md` baseline

### Phase 4 — metatables + error handling (next run)
- [ ] Metatable dispatch: `__index`, `__newindex`, `__add`/`__sub`/…, `__eq`, `__lt`, `__call`, `__tostring`, `__len`
- [ ] `pcall`/`xpcall`/`error` via handler-bind
- [ ] Generic `for … in …`

### Phase 5 — coroutines (the showcase)
- [ ] `coroutine.create`/`.resume`/`.yield`/`.status`/`.wrap` via `perform`/`cek-resume`

### Phase 6 — standard library
- [ ] `string` — `format`, `sub`, `find`, `match`, `gmatch`, `gsub`, `len`, `rep`, `upper`, `lower`, `byte`, `char`
- [ ] `math` — full surface
- [ ] `table` — `insert`, `remove`, `concat`, `sort`, `unpack`
- [ ] `io` — minimal stub (read/write to SX IO surface)
- [ ] `os` — time/date subset

### Phase 7 — modules + full conformance
- [ ] `require` / `package` via SX `define-library`/`import`
- [ ] Drive PUC-Rio scoreboard to 100%

## Progress log

_Newest first. Agent appends on every commit._

- _(awaiting phase 1)_

## Blockers

_Shared-file issues that need someone else to fix. Minimal repro only._

- _(none yet)_