rose-ash/plans/lua-on-sx.md

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.

• 2026-04-24: lua: phase 2 transpile — arithmetic, comparison, short-circuit logical, .. concat, if/while/repeat/for-num/local/assign. 157 total tests green.
• 2026-04-24: lua: parser (exprs with precedence, all phase-1 statements, funcbody, table ctors, method/chained calls) — 112 total tokenizer+parser tests
• 2026-04-24: lua: tokenizer (numbers/strings/long-brackets/keywords/ops/comments) + 56 tests

Blockers

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

• (none yet)