tv-labs/lua

This system is a pure Elixir implementation of a Lua 5.3 virtual machine, designed to provide a sandboxed, NIF-free runtime for executing Lua scripts within the BEAM environment. It features a custom register-based compiler and bytecode dispatcher with configurable security constraints, such as instruction budgets and call depth limits, to prevent denial-of-service scenarios. The library includes a comprehensive standard library, structured error handling, and developer tooling like Mix tasks for evaluation, benchmarking, and conformance testing against the official Lua 5.3 suite.

8 changes.

The project replaced the Luerl backend with a fully native Elixir-based Lua 5.3 virtual machine, introducing a custom compiler, register-based VM, and configurable sandboxing with resource limits. This major release established a new API surface, comprehensive test coverage for conformance and error handling, and updated documentation to reflect the breaking changes and security features.

23 changes.

This period focused on building a complete register-based Lua 5.3 virtual machine and compiler in Elixir, replacing the previous interpreter with a bytecode pipeline featuring a peephole optimizer and efficient dispatcher. The work included implementing the full standard library, structured error handling, and comprehensive test coverage using the official Lua 5.3 suite to ensure language compliance. Additionally, developer tooling such as Mix tasks, benchmarks, and AI agent workflows were introduced to support the new infrastructure.

The VM now includes the full Lua 5.3 standard library, providing \debug\, \math\, \os\, \string\, \table\, and \utf8\ modules. These modules are installed as global tables in the VM state, enabling standard operations such as string manipulation, pattern matching, mathematical functions, table sorting, and UTF-8 processing. The \os\ module includes time functions and environment access, while the \debug\ module provides stack introspection and upvalue management.

lib/lua/vm/stdlib · high confidence

New Livebook guides have been added to the documentation, providing runnable examples for core Lua integration features. These include a quickstart for basic script evaluation and table decoding, instructions for compiling and reusing Lua chunks, methods for extending the standard library and passing Elixir structs via userdata, and detailed coverage of sandboxing controls (including call depth and instruction budgets) and error handling strategies.

guides/examples · high confidence

The Lua VM now supports binary data packing and unpacking via the new \string.pack\, \string.unpack\, and \string.packsize\ functions. These functions allow users to serialize and deserialize data according to a format-string mini-language, handling various integer and float sizes, endianness, and alignment. This implementation follows the Lua 5.3 specification for string packing operations.

lib/lua/vm/stdlib/string · high confidence

This change establishes the foundational structure for the project's 1.0 release. It introduces the \CHANGELOG.md\ to document the migration from the Luerl backend to the new Elixir-native Lua 5.3 VM, including specific breaking changes in value encoding and error handling. The \README.md\ is rewritten to position the library as a sandboxed, NIF-free Lua runtime for Elixir, featuring a quickstart guide and security documentation. Additionally, the repository is initialized with essential configuration files (\.dockerignore\, \.formatter.exs\, \Dockerfile\, \fly.toml\) and AI-agent usage rules (\AGENTS.md\) to support development and deployment workflows.

(repo-wide) · high confidence

The website now features an interactive Lua showcase that allows users to write and execute Lua code directly in the browser. This is powered by a CodeMirror-based editor component that supports syntax highlighting, line numbers, and theme switching (light/dark) that respects the site's current theme. The editor integrates with the Phoenix LiveView backend, syncing user input to a hidden textarea for form submission and persisting code snippets to local storage. The UI includes custom animations for the Lua logo and uses Tailwind CSS with daisyUI for styling, providing a polished, responsive experience for exploring Lua features.

website · high confidence

The library now provides a Lua virtual machine implementation that allows users to initialize a sandboxed environment via \Lua.new/1\. This environment supports configurable security constraints through the \:sandboxed\ and \:exclude\ options, which control access to standard library functions like \io\ and \os\. Additionally, users can enforce resource limits to prevent denial-of-service scenarios, including caps on call depth (\:max\_call\_depth\), string size (\:max\_string\_bytes\), and instruction count (\:max\_instructions\).

lib · high confidence

This change replaces the previous Lua implementation with a new, conformant compiler and register-based virtual machine written in Elixir. Users can now define Elixir functions exposed to Lua via the \Lua.API\ module using the \deflua\ macro, supporting scoped namespaces, state access, and guard clauses. The new engine includes a full AST with position tracking, a lexer that handles shebangs and multi-line comments, and a parser that produces structured errors. Execution is handled by a new VM that supports dense bytecode encoding, a peephole optimizer, and configurable instruction budgets. Error reporting has been unified under \Lua.CompilerException\, providing both plain text for logging and rich, ANSI-colored source context for interactive use.

lib/lua · high confidence

Added four new workflow scripts in .agents/workflows to automate the lifecycle of pull requests and issues. The pr-feedback-stabilize workflow loops through up to three rounds of addressing review feedback and independent reviews to stabilize open PRs without merging. The ship-issue-batch workflow orchestrates the end-to-end process for seven specific issues, including planning, implementation in isolated git worktrees, and review. The triage-implement-review workflow handles eight Lua 5.3 suite issues by triaging failures, implementing fixes, and managing PR reviews. The recover-triage-implement-review workflow serves as a recovery run to finish interrupted issues and address feedback across multiple PRs. All workflows enforce strict git worktree isolation to prevent corruption of the primary repository and adhere to conventional commit and subsystem scoping rules.

.agents/workflows · high confidence

This change introduces a new Lua VM implementation in \lib/lua/vm\, replacing the previous interpreter with a register-based virtual machine featuring a hand-written bytecode dispatcher for improved performance. The VM now includes a comprehensive error handling system with specific exception types (\ArgumentError\, \AssertionError\, \InternalError\) that are wrapped into public \Lua.RuntimeException\ instances, providing structured error data including source location, line numbers, and call stacks. Additionally, display wrappers (\Display.Table\, \Display.Closure\, \Display.NativeFunc\, \Display.Userdata\) are introduced to provide human-readable representations of Lua values at the API boundary, while bootstrap mechanisms memoize VM templates for efficient instantiation.

lib/lua/vm · high confidence

A new Mix task, \mix lua.eval\, has been added to allow users to evaluate Lua source files or stdin input directly from the command line. The task initializes a fresh Lua VM, executes the provided script, and prints the return values to stdout. It supports reading from a file path or standard input (using \-\), allows specifying a custom source name for error reporting via the \--source\ option, and exits with code 1 if a Lua compiler or runtime exception occurs, printing the formatted error to stderr.

lib/mix · high confidence

The benchmarks directory now includes a comprehensive suite of scripts (fibonacci, closures, oop, metamethods, patterns, pcall\_varargs, string\_ops, string\_format, table\_ops, encode\_decode, and array\_vs\_map\_probe) that compare the Lua implementation against Luerl and optional C Lua via luaport. A new BASELINE.md documents the 1.0.0 performance gate results, highlighting significant improvements in string.format and table.sort. The suite supports quick and full run modes via the LUA\_BENCH\_MODE environment variable and includes a setup script for building the luaport dependency.

benchmarks · high confidence

Developers can now use \mix lua.bench\ to run performance benchmarks against the VM, \mix lua.get\_tests\ to download the official Lua 5.3 test suite, and \mix lua.suite\ to execute those tests with options for filtering, timeouts, and conformance auditing. These tasks are intended for library development and are not included in the Hex package.

tasks · high confidence

The \lib/lua/compiler\ area now includes a complete register-based compiler pipeline (\codegen\, \scope\, \peephole\, \bytecode\) and a dense bytecode dispatcher (\Lua.VM.Dispatcher\). This replaces the previous interpretation-only path with a compiled bytecode representation that enables significantly faster execution for arithmetic, table, closure, and control-flow operations. The compiler includes a peephole optimizer that performs move elision, constant folding, and upvalue-field fusion to reduce instruction count, and a goto resolution pass that statically resolves \goto\/\label\ targets to avoid runtime overhead. The dispatcher uses a dense integer-tagged bytecode format to allow the BEAM VM to use a jump table for efficient opcode dispatch, while maintaining a fallback to the interpreter for any unsupported opcodes.

lib/lua/compiler · high confidence

The project now includes symbolic links in the .claude and .opencode directories that point to ../.agents/skills and ../.agents/commands respectively. This change establishes the necessary file structure for agent orchestration, allowing these tools to locate and utilize shared skills and command definitions stored in the .agents directory.

.claude, .opencode · low confidence

The Lua parser has been rewritten in Elixir, introducing a new module structure that includes \Lua.Parser.Comments\ for collecting and attaching leading/trailing comments to AST nodes, \Lua.Parser.Pratt\ for operator precedence parsing (including Lua 5.3 bitwise operators), and \Lua.Parser.Error\ for structured, wire-safe error reporting with source context and suggestions. The parser now supports error recovery strategies via \Lua.Parser.Recovery\, allowing it to continue parsing after errors and collect multiple issues in a single pass. This change replaces the previous implementation, altering how parse errors are reported and how comments are handled in the AST.

lib/lua/parser · high confidence

The library has reached version 1.0.0, replacing the Luerl backend with an Elixir-native Lua 5.3 virtual machine. This is a major behavioral change: the Luerl runtime dependency is removed, encoded value tags have changed (e.g., table references are now \{:tref, integer()}\ instead of \:luerl.tref()\), and error handling now returns structured \Lua.RuntimeException\ structs instead of strings. Additionally, new Mix tasks (\mix lua.eval\, \mix lua.suite\, \mix lua.bench\) are available for running scripts and benchmarks, and comprehensive guides have been added to assist with migration, sandboxing, and usage.

guides · high confidence

Added Lua test case support module; Added compiler test suite for bytecode, instruction sizing, and peephole optimizations; Added comprehensive test suite for Lua parser; Added pcall state preservation benchmark; Added test coverage for Lua AST builder, IDs, meta, pretty printer, and walker; Added test fixtures for script loading and instruction budgeting; Added test suite for embedded examples and Lua 5.3 conformance; Added tests for Lua Mix tasks; Added vendored luassert integration tests; Expanded test coverage for Lua API, error handling, and lexer; Expanded test coverage for Lua VM arithmetic, bitwise, and metamethod behavior; Expanded test coverage for Lua language semantics; Expanded test coverage for Lua standard library modules; Integration of Lua 5.3 official test suite.

This change introduces the v1.0.2 release of the Lua library, a Lua VM implementation in Elixir, along with the initial setup of the interactive demo website. The library depends on Luerl 1.5.1 for benchmarking and uses dev tools like ExDoc 0.38, Dialyxir 1.4, and Styler 1.10. The website is built on Phoenix 1.8.7 and Phoenix Live View 1.1.30, featuring a CodeMirror-based editor for the interactive showcase.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 71.

• Code Health 84
• Architecture 96
• Maturity 68
• Readiness 72
• Security 76
• Accessibility 73

• 300 commits — 226 feature/other, 74 fixes

• lib/lua — 143 commits
• (root) — 66 commits
• .agents/plans — 37 commits
• test/lua — 14 commits
• lib/lua.ex — 8 commits
• .github/workflows — 4 commits
• .agents/skills — 3 commits
• .agents/workflows — 3 commits
• website/lib — 3 commits
• benchmarks/closures.exs — 2 commits
• guides/examples — 2 commits
• test/lua53_skips.exs — 2 commits
• (repo) — 1 commit
• .agents/commands — 1 commit
• bench_results/v1.0.2 — 1 commit
• benchmarks/encode_decode.exs — 1 commit
• test/fixtures — 1 commit
• test/integration — 1 commit
• test/language — 1 commit
• test/lua53_tests — 1 commit

• fix: Fix Elixir 1.19 type warning (#91)
• fix: Fix Lua.Table.as_string with nested tables (#57)
• fix: Fix guard example in Lua.API docs (#90)
• fix: Fix issue with variadic functions that have state (#30)
• fix: Fix typespec for Lua.API.install/3 (#60)
• fix: Fix unbounded recursion on cyclic tables at the eval boundary (#407)
• fix: chore(B7): defer plan; tuple cost crossover makes large tables a regression (#231)
• fix: chore: link plans to GitHub issues, add A14 for regression (#175)
• fix: chore: roadmap hygiene, settle 1.0.0 suite gate (20/29), tostring(fn) fix (#353)
• fix: fix example
• fix: fix(api): deflua/2 preserves function name for guarded heads (#344)
• fix: fix(api): name the callee in call_function/3 errors (#383)
• fix: fix(api): tighten public surface before the 1.0 freeze (#380)
• fix: fix(compiler): assign function declaration to in-scope local (#185)
• fix: fix(compiler): bind for-loop variable per statement to fix register reuse (#195)
• fix: fix(compiler): expand multi-values in obj:method(...) calls (#248)
• fix: fix(compiler): resolve FuncDecl head names at scope analysis (#274)
• fix: fix(error): prune internal frames from Lua.RuntimeException stack (#221)
• fix: fix(error): stdlib bad-arg raises auto-populate line and source (#215)
• fix: fix(errors): render exception messages lazily so ANSI gating holds (#386)
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

tv-labs/lua was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.