# Reference Implementations

Classification of implementations studied during architecture design.
Each was examined for its approach to compilation, VM design, memory
management, and API surface.

## Tier 1 — Primary References

### PUC-Rio Lua 5.1.1 (C)

- **Local path**: `./lua-5.1.1/` (built from official tarball; see `AGENTS.md` for setup)
- **Role**: The specification. All behavioral questions are answered here.
- **Architecture**: 17,654 lines. Single-pass recursive descent compiler
  emitting 38 register-based opcodes (u32 packed). CallInfo chain for
  call stack. Incremental tri-color mark-sweep GC with write barriers.
  Array+hash tables. Interned strings with cached hash. longjmp/setjmp
  error handling. Stack-based C API.
- **What we take**: Opcode semantics, GC behavioral contract, weak table
  semantics, finalizer protocol, `collectgarbage()` API, standard library
  behavior, error messages.
- **What we change**: Single-pass compilation (we use AST), longjmp (we
  use Result), C API (we use traits), raw pointers (we use arenas).

### Luau (C++)

- **Local path**: `~/Repos/github.com/luau-lang/luau`
- **Role**: Architecture reference. Lua 5.1-compatible scripting language.
- **Architecture**: Lexer -> Parser -> AST -> Compiler -> VM. 83
  register-based opcodes (count evolves with development). Incremental tri-color GC. CallInfo chain.
  Array+hash tables. String interning. No longjmp (C++ exceptions).
- **What we take**: AST-based pipeline design, separation of compiler
  phases, Proto as non-GC value (owned by closures), CallInfo chain
  pattern, incremental GC debt model.
- **What we change**: Opcode count (we use PUC-Rio's 38, not Luau's 83),
  language extensions (we implement standard Lua 5.1.1 only), native
  codegen (out of scope).

## Tier 2 — Selective References

### tsuki (Rust, Lua 5.4)

- **Local path**: `~/Repos/github.com/ultimaweapon/tsuki`
- **Role**: Proves Result-based error handling works for a Lua VM.
- **Architecture**: c2rust translation of Lua 5.4. PUC-Rio file naming
  (llex.rs, lparser.rs, lcode.rs). 83 opcodes. Incremental GC via raw
  pointers. Heavy use of unsafe code. Memory-safe public API over unsafe internals.
- **What we take**: Result-based error propagation pattern, memory-safe
  public API design, packed u32 instruction format for
  serialization.
- **What we avoid**: c2rust code style, heavy unsafe, wrong Lua version
  (5.4 vs 5.1.1).

### full-moon (Rust, parser only)

- **Local path**: `~/Repos/github.com/Kampfkarren/full-moon`
- **Role**: Best Rust patterns for Lua parsing.
- **Architecture**: Hand-written recursive descent parser. Lossless AST
  preserving whitespace and comments. Error recovery with partial AST.
  Multi-dialect support (5.1-5.4, Luau) via feature flags. Sealed
  traits, visitor pattern, builder pattern.
- **What we take**: Recursive descent parsing patterns, AST node design
  idioms, error recovery approach, sealed trait pattern.
- **What we avoid**: Lossless parsing (unnecessary for a VM), multi-dialect
  support (we only target 5.1.1), external dependencies.

### mlua (Rust, FFI wrapper)

- **Local path**: `~/Repos/github.com/mlua-rs/mlua`
- **Role**: API design reference for embedding Lua in Rust.
- **Architecture**: FFI wrapper around C Lua. Memory-safe Rust API over
  unsafe C bindings. Trait-based type conversions (`IntoLua`, `FromLua`).
  Registry-based lifetime management. Scoped values. UserData trait.
- **What we take**: Trait-based API design (`IntoLua`/`FromLua` pattern),
  UserData trait approach, scope-based lifetime management, error type
  design.
- **Not applicable**: FFI wrapping (we implement from scratch), C Lua
  compilation, vendored builds.

## Tier 3 — Limited Relevance

### lua-in-rust (Rust, Lua 5.1.1)

- **Local path**: `~/Repos/github.com/cjneidhart/lua-in-rust`
- **Role**: Previous base for rilua. Studied for lessons learned.
- **Architecture**: Single-pass compiler, stack-based VM (~40 custom
  opcodes), stop-the-world mark-sweep GC with raw pointers, string
  interning, HashMap-only tables. ~5,000 lines. ~40% complete.
- **Lessons**: Stack-based VM diverges too far from PUC-Rio's
  register-based design. Single-pass compilation makes the compiler
  hard to test and extend. Raw pointer GC works but is fragile.
  String interning with pointer equality is the right approach.

### lua-rs (Rust, compiler only)

- **Local path**: `~/Repos/github.com/lonng/lua-rs`
- **Role**: Shows AST-to-bytecode compilation for Lua 5.1.
- **Architecture**: Multi-pass with explicit AST. Scanner -> Parser ->
  AST -> Compiler -> FunctionProto. No VM. Broken build. Zero unsafe.
- **Useful for**: AST node design, constant folding patterns, debug
  info tracking. Not useful for VM or runtime design.

### coppermoon (Rust, mlua wrapper)

- **Local path**: `~/Repos/github.com/coppermoondev/coppermoon`
- **Role**: None for VM/compiler work.
- **Architecture**: Node.js-like runtime wrapping mlua (C Lua 5.4 FFI).
  Not a from-scratch implementation. Provides batteries-included stdlib
  (HTTP, SQLite, WebSocket, etc.) over the C VM.
- **Not applicable**: Everything. This wraps C Lua, not implements it.

### hematita (Rust, Lua 5.3)

- **Local path**: `~/Repos/github.com/danii/hematita`
- **GitHub**: <https://github.com/danii/hematita>
- **Role**: Reference for hardened Lua interpreter patterns in Rust.
- **Architecture**: From-scratch Lua interpreter in Rust targeting 5.3.
  Focuses on safety and correctness. Useful for comparing implementation
  approaches for parsing, value representation, and standard library.
- **What we take**: Comparison point for implementation patterns and
  edge case handling.
- **Differences**: Targets Lua 5.3 (not 5.1.1), different design goals.
