benilla-octo/third_party/lua-src/BENILLA.md

benilla's lua-src fork — what differs from upstream, and how to check

Upstream: mlua-rs/lua-src-rs, MIT, version 550.0.0 — the version mlua 0.11 resolves to. Wired in through [patch.crates-io] in the workspace root.

Why a fork exists at all

The 1.12 addon corpus is Lua 5.0 code. It uses the iterator-less generic-for:

for k, v in someTable do ... end        -- no pairs(), no iterator function

183 of 218 corpus addons are reached by it (118 carry it, 65 inherit it through a declared dependency), across 1,163 sites. On stock Lua 5.1 it raises attempt to call a table value, and it is the first session-start error for 60 of 218 addons — three quarters of everything that breaks once the client is actually running, eleven times the next cause.

Lua 5.1 removed it at the opcode level, which is why no layer above the VM can reach it. Every other dialect gap this project has closed was reachable from inside Lua — table.setn is a library function, bit is a library, print is a global (decisions 1194, 1196). This one is not:

• a __call metamethod would work, but the tables are the addon's own and Lua 5.1 has no per-type default metatable for tables;
• rewriting the chunk source means parsing Lua with a regex to tell in t do from in pairs(t) do, and getting that wrong changes behaviour silently;
• there is no lua50 backend — lua-src ships 5.1 through 5.5 and every one of them removed it.

What is NOT being done

benilla is not adopting Lua 5.0. We stay on 5.1.5 and restore the behaviour of a single opcode that Lua itself shipped and labelled /* for compatibility only */. Every other 5.1 fix, and the whole of mlua's surface, stay exactly as upstream. That is a far smaller commitment than a version downgrade, and it is the entire reason this is a one-hunk fork rather than a vendored 5.0.

The delta, and the command that proves it

Current state: no source hunk yet. The lua-5.1.5/ tree here is byte-identical to upstream's, and src/lib.rs differs only by having Lua 5.2/5.3/5.4/5.5 stripped from the Version enum (with their source trees deleted) — benilla builds 5.1 and only 5.1, and a fork that still offered the other four would answer a request for one with a missing directory at build time instead of a compile error.

This ordering is deliberate: the build pipeline is proven transparent before any behavioural payload goes into it, so that when the suite moves, the patch is the only thing that could have moved it. Landed inert, with all tests passing, exactly so that claim is checkable.

To verify the Lua sources against upstream at any time:

# 550.0.0 is the pinned version; adjust the path if cargo's registry hash differs.
diff -r third_party/lua-src/lua-5.1.5 \
  ~/.cargo/registry/src/*/lua-src-550.0.0/lua-5.1.5

Today that prints nothing. When the payload lands it must print exactly the hunk described in decision 1215 and nothing else — if it ever prints more, something crept in.

Status of the payload

Blocked, deliberately, on a reverse-engineering answer from the sibling repo wow-5875-re: what the real 1.12.1 client's own Lua does when a generic-for's generator is a table. Stock Lua 5.0 is corroboration, not the authority — the client links 5.0 but may be modified.

Checking stock 5.0 already corrected two assumptions the project had written down (it substitutes in OP_TFORPREP, an opcode 5.1 deleted, not in OP_TFORLOOP; and the test is a bare ttistable with no __call check, using the global next — so an addon that overwrites next changes loop behaviour). Two corrections from checking one step out is the reason for checking the next one before writing C.