Repository navigation
feat(A0): 64-bit integer overflow wrapping for arithmetic and bitwise ops - #177
Merged
Merged
Conversation
Lua 5.3 §3.4.1 requires integer operations to wrap modulo 2^64 to the signed 64-bit range. Without wrapping, results overflow into Erlang's arbitrary-precision integers, breaking expectations like `maxint + 1 == minint` and `1 << 63 == minint`. This conforms to the Lua reference and is a deliberate divergence from Luerl, which inherits Erlang's bignum semantics. Adds `Lua.VM.Numeric` with `to_signed_int64/1` and applies it to integer-only results in arithmetic ops (`+`, `-`, `*`, `//`, `%`, unary `-`) and all bitwise ops (`&`, `|`, ~^`, `~`, `<<`, `>>`). Floats are untouched. The previously partial wrapping in `lua_shift_left`/`lua_shift_right` (masked to unsigned 64-bit, but left as positive bignums for high-bit results) now produces the correct signed values. Closes #161
This was referenced May 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
64-bit integer overflow wrapping for arithmetic and bitwise ops
Plan:
.agents/plans/A0-int-overflow-wrapping.mdCloses #161
Goal
Make integer operations wrap to signed 64-bit per the Lua 5.3 spec, so
maxint + 1 == minintand1 << 63 == minintinstead of overflowing into arbitrary-precision Erlang integers.This is a deliberate divergence from Luerl, which inherits Erlang's bignum semantics. The new VM conforms to Lua 5.3 §3.4.1 ("In case of overflows in integer arithmetic, all operations wrap around, according to the usual rules of two-complement arithmetic").
Success criteria
mix testpasses — 1273 → 1284 (11 new tests, no regressions)test/lua/vm/arithmetic_test.exs:maxint + 1 == minintminint - 1 == maxintmaxint * 2 == -21 << 63 == minint~0 == -1~0xffffffffffffffff == 00x8000000000000000 // 1 == minint(no overflow into bignum)mix test --only lua53count unchanged (29/0/25 → 29/0/25).bitwise.luais in the deferred list (A5) and depends on stdlib bits beyond this plan's scope; this PR removes one of its blockers but does not flip it green on its own.Changes
Lua.VM.Numericmodule withto_signed_int64/1,max_int/0,min_int/0, andsigned?/1. The module docstring documents the Lua-vs-Luerl divergence so it's discoverable from generated docs.Lua.VM.Executor:safe_add,safe_subtract,safe_multiply,safe_negateroute integer-only results through a new privatenarrow_if_integer/1helper (floats untouched).safe_floor_divideandsafe_modulowrap their integer paths.:bitwise_and,:bitwise_or,:bitwise_xor,:bitwise_notwrap their results.lua_shift_left/2andlua_shift_right/2previously masked to unsigned 64-bit, leaving1 << 63as a positive bignum. Both now flow their result throughto_signed_int64/1, so high-bit results land atminintinstead.Notes on Lua-vs-Luerl behavior
This is the first behavior change on the new VM where users coming from Luerl will see different output from the same Lua source. The divergence is intentional and matches the Lua 5.3 reference. We should call this out in CHANGELOG / release notes for 0.5.0; that documentation update is out of scope here and belongs with A12.
Verification
Out of scope (intentional)
bitwise.luafailures unrelated to overflow — that is the A5 plan.