diff --git a/.agents/plans/A0-int-overflow-wrapping.md b/.agents/plans/A0-int-overflow-wrapping.md index bbd2e137..ec05cb9c 100644 --- a/.agents/plans/A0-int-overflow-wrapping.md +++ b/.agents/plans/A0-int-overflow-wrapping.md @@ -2,10 +2,10 @@ id: A0 title: 64-bit integer overflow wrapping for arithmetic and bitwise ops issue: 161 -pr: null +pr: 177 branch: feat/int-overflow-wrapping base: main -status: ready +status: review direction: A unlocks: - bitwise.lua @@ -85,3 +85,34 @@ mix test test/lua/vm/arithmetic_test.exs cases (e.g. `0xffffffffffffffff + 1` should be `0` after wrapping). - Some property tests in the existing test suite may rely on the current (incorrect) bignum behavior — they'll need updating to match Lua 5.3. + +## What changed + +PR #177. + +Files touched: + +- `lib/lua/vm/numeric.ex` (new) — `to_signed_int64/1`, `max_int/0`, + `min_int/0`, `signed?/1`, with module docs spelling out the + Lua-vs-Luerl divergence. +- `lib/lua/vm/executor.ex` — wrapped integer-only results in `+`, `-`, + `*`, `//`, `%`, unary `-`, `&`, `|`, `~^`, `~`, `<<`, `>>`. Floats + untouched. Pre-existing partial wrapping in `lua_shift_left`/ + `lua_shift_right` (masked unsigned, leaving high-bit results as + positive bignums) now produces signed values. +- `test/lua/vm/arithmetic_test.exs` — 11 new tests covering the + required cases plus `negation of minint`, `float arithmetic + unaffected`, and `modulo wraps`. + +Suite delta: `mix test` 1273 → 1284 (11 new tests, no regressions). +`mix test --only lua53` unchanged at 29/0/25. `bitwise.lua` not flipped +green — additional stdlib work is required and is the scope of A5. + +Discovery: `lua_shift_left/2` was already half-Lua-flavored (masked to +unsigned 64-bit) but had not been updated to return signed values. The +plan called this out only obliquely via the `1 << 63 == minint` success +criterion; the fix is included here since it is in scope and required +for that test. + +Follow-up: documenting the Luerl divergence in CHANGELOG / release +notes belongs with A12 (readme/changelog) before 0.5.0 ships. diff --git a/lib/lua/vm/executor.ex b/lib/lua/vm/executor.ex index 69905d4c..7eae09f7 100644 --- a/lib/lua/vm/executor.ex +++ b/lib/lua/vm/executor.ex @@ -13,6 +13,7 @@ defmodule Lua.VM.Executor do """ alias Lua.VM.InternalError + alias Lua.VM.Numeric alias Lua.VM.RuntimeError alias Lua.VM.State alias Lua.VM.TypeError @@ -807,7 +808,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__band", val_a, val_b, state, fn -> - Bitwise.band(to_integer!(val_a), to_integer!(val_b)) + Numeric.to_signed_int64(Bitwise.band(to_integer!(val_a), to_integer!(val_b))) end) regs = put_elem(regs, dest, result) @@ -820,7 +821,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__bor", val_a, val_b, state, fn -> - Bitwise.bor(to_integer!(val_a), to_integer!(val_b)) + Numeric.to_signed_int64(Bitwise.bor(to_integer!(val_a), to_integer!(val_b))) end) regs = put_elem(regs, dest, result) @@ -833,7 +834,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__bxor", val_a, val_b, state, fn -> - Bitwise.bxor(to_integer!(val_a), to_integer!(val_b)) + Numeric.to_signed_int64(Bitwise.bxor(to_integer!(val_a), to_integer!(val_b))) end) regs = put_elem(regs, dest, result) @@ -871,7 +872,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_unary_metamethod("__bnot", val, state, fn -> - Bitwise.bnot(to_integer!(val)) + Numeric.to_signed_int64(Bitwise.bnot(to_integer!(val))) end) regs = put_elem(regs, dest, result) @@ -1588,7 +1589,7 @@ defmodule Lua.VM.Executor do defp safe_add(a, b) do with {:ok, na} <- to_number(a), {:ok, nb} <- to_number(b) do - na + nb + narrow_if_integer(na + nb) else {:error, val} -> raise TypeError, @@ -1601,7 +1602,7 @@ defmodule Lua.VM.Executor do defp safe_subtract(a, b) do with {:ok, na} <- to_number(a), {:ok, nb} <- to_number(b) do - na - nb + narrow_if_integer(na - nb) else {:error, val} -> raise TypeError, @@ -1614,7 +1615,7 @@ defmodule Lua.VM.Executor do defp safe_multiply(a, b) do with {:ok, na} <- to_number(a), {:ok, nb} <- to_number(b) do - na * nb + narrow_if_integer(na * nb) else {:error, val} -> raise TypeError, @@ -1649,7 +1650,7 @@ defmodule Lua.VM.Executor do raise RuntimeError, value: "attempt to divide by zero" is_integer(na) and is_integer(nb) -> - lua_idiv(na, nb) + Numeric.to_signed_int64(lua_idiv(na, nb)) true -> Float.floor(na / nb) * 1.0 @@ -1671,7 +1672,7 @@ defmodule Lua.VM.Executor do raise RuntimeError, value: "attempt to perform modulo by zero" is_integer(na) and is_integer(nb) -> - na - lua_idiv(na, nb) * nb + Numeric.to_signed_int64(na - lua_idiv(na, nb) * nb) true -> na - Float.floor(na / nb) * nb @@ -1707,7 +1708,7 @@ defmodule Lua.VM.Executor do defp safe_negate(a) do case to_number(a) do {:ok, na} -> - -na + narrow_if_integer(-na) {:error, val} -> raise TypeError, @@ -1717,6 +1718,12 @@ defmodule Lua.VM.Executor do end end + # Narrow integer results to signed 64-bit per Lua 5.3 §3.4.1. Floats are + # left untouched: IEEE 754 has its own overflow semantics that the spec + # leaves alone. + defp narrow_if_integer(n) when is_integer(n), do: Numeric.to_signed_int64(n) + defp narrow_if_integer(n), do: n + # ── Type-safe comparison ─────────────────────────────────────────────────── defp safe_compare_lt(a, b) do @@ -1826,7 +1833,7 @@ defmodule Lua.VM.Executor do defp lua_shift_left(val, shift) when shift < 0, do: lua_shift_right(val, -shift) defp lua_shift_left(val, shift) do - Bitwise.band(Bitwise.bsl(val, shift), 0xFFFFFFFFFFFFFFFF) + Numeric.to_signed_int64(Bitwise.bsl(val, shift)) end defp lua_shift_right(_val, shift) when shift >= 64, do: 0 @@ -1835,7 +1842,7 @@ defmodule Lua.VM.Executor do defp lua_shift_right(val, shift) do unsigned_val = Bitwise.band(val, 0xFFFFFFFFFFFFFFFF) - Bitwise.bsr(unsigned_val, shift) + Numeric.to_signed_int64(Bitwise.bsr(unsigned_val, shift)) end # ── Value type helper ────────────────────────────────────────────────────── diff --git a/lib/lua/vm/numeric.ex b/lib/lua/vm/numeric.ex new file mode 100644 index 00000000..d465668a --- /dev/null +++ b/lib/lua/vm/numeric.ex @@ -0,0 +1,85 @@ +defmodule Lua.VM.Numeric do + @moduledoc """ + Numeric helpers implementing Lua 5.3 integer semantics. + + Lua 5.3 specifies that integer arithmetic and bitwise operations operate + on signed 64-bit values that wrap modulo 2^64 on overflow. This is a + divergence from Erlang's arbitrary-precision integers, which is why this + module exists. + + The reference: Lua 5.3 §3.4.1 "Arithmetic Operators": + + > In case of overflows in integer arithmetic, all operations wrap around, + > according to the usual rules of two-complement arithmetic. + + ## Lua vs. Luerl + + This module also marks a deliberate divergence from Luerl, which inherits + Erlang's bignum behavior. Code written against Lua 5.3 (textbooks, the + official test suite, copy-paste from elsewhere) expects wrapping; Luerl + does not provide it. This library does, on the new VM. + + ## Bounds + + * `max_int/0` — `9_223_372_036_854_775_807` (`2^63 - 1`) + * `min_int/0` — `-9_223_372_036_854_775_808` (`-2^63`) + + ## Functions + + * `to_signed_int64/1` — wrap any integer into the signed 64-bit range. + * `signed?/1` — predicate, true when an integer is already in range. + """ + + import Bitwise + + @uint64_modulus 0x10000000000000000 + @uint64_mask 0xFFFFFFFFFFFFFFFF + @sign_bit 0x8000000000000000 + + @max_int 0x7FFFFFFFFFFFFFFF + @min_int -0x8000000000000000 + + @doc "Maximum signed 64-bit integer (`2^63 - 1`)." + @spec max_int() :: integer() + def max_int, do: @max_int + + @doc "Minimum signed 64-bit integer (`-2^63`)." + @spec min_int() :: integer() + def min_int, do: @min_int + + @doc """ + Wrap an integer to the signed 64-bit range. + + Floats are returned unchanged so this is safe to apply to results of mixed + integer/float pipelines that have already been narrowed by the caller. + + ## Examples + + iex> Lua.VM.Numeric.to_signed_int64(0) + 0 + + iex> Lua.VM.Numeric.to_signed_int64(Lua.VM.Numeric.max_int() + 1) + -9_223_372_036_854_775_808 + + iex> Lua.VM.Numeric.to_signed_int64(Lua.VM.Numeric.min_int() - 1) + 9_223_372_036_854_775_807 + + iex> Lua.VM.Numeric.to_signed_int64(0xFFFFFFFFFFFFFFFF) + -1 + """ + @spec to_signed_int64(integer()) :: integer() + def to_signed_int64(n) when is_integer(n) do + masked = band(n, @uint64_mask) + if masked >= @sign_bit, do: masked - @uint64_modulus, else: masked + end + + @doc """ + Returns `true` when `n` is already in the signed 64-bit range. + + Cheap predicate for the fast path: integers produced by Lua-level + operations on already-narrow integers are usually still narrow, so we can + avoid the masking step in those cases when we want. + """ + @spec signed?(integer()) :: boolean() + def signed?(n) when is_integer(n), do: n >= @min_int and n <= @max_int +end diff --git a/test/lua/vm/arithmetic_test.exs b/test/lua/vm/arithmetic_test.exs index a88009b6..ab20ad3a 100644 --- a/test/lua/vm/arithmetic_test.exs +++ b/test/lua/vm/arithmetic_test.exs @@ -276,4 +276,69 @@ defmodule Lua.VM.ArithmeticTest do assert err =~ "compare" end end + + # See `Lua.VM.Numeric` and Lua 5.3 §3.4.1. Integer operations wrap to + # signed 64-bit. This is a deliberate divergence from Luerl, which uses + # Erlang's bignum semantics. + describe "64-bit integer overflow wrapping (Lua 5.3 §3.4.1)" do + @maxint 9_223_372_036_854_775_807 + @minint -9_223_372_036_854_775_808 + + defp eval_int(code) do + assert {:ok, ast} = Parser.parse(code) + assert {:ok, proto} = Compiler.compile(ast, source: "test.lua") + state = State.new() + assert {:ok, [result], _state} = VM.execute(proto, state) + result + end + + test "maxint + 1 wraps to minint" do + assert eval_int("return 0x7fffffffffffffff + 1") == @minint + end + + test "minint - 1 wraps to maxint" do + assert eval_int("return -0x8000000000000000 - 1") == @maxint + end + + test "maxint * 2 wraps to -2" do + assert eval_int("return 0x7fffffffffffffff * 2") == -2 + end + + test "1 << 63 is minint, not a positive bignum" do + assert eval_int("return 1 << 63") == @minint + end + + test "~0 is -1" do + assert eval_int("return ~0") == -1 + end + + test "~0xffffffffffffffff is 0" do + assert eval_int("return ~0xffffffffffffffff") == 0 + end + + test "0x8000000000000000 // 1 stays at minint (no overflow into bignum)" do + assert eval_int("return 0x8000000000000000 // 1") == @minint + end + + test "negation of minint wraps back to minint" do + # -minint as a true integer would be 2^63 which is one past maxint. + # In Lua 5.3 that overflows back to minint. + assert eval_int("local x = -0x8000000000000000; return -x") == @minint + end + + test "float arithmetic is unaffected by wrapping" do + # 2^53 is the largest exact integer in IEEE 754 doubles. As a float + # result it must not get masked through the int64 wrapping path — + # the result should still be a float, and it should be the IEEE + # answer, not an integer. + result = eval_int("return 9007199254740992.0 * 2") + assert is_float(result) + assert result == 1.8014398509481984e16 + end + + test "modulo wraps results into signed range" do + # When both operands are integers, lua_mod result must be signed-64. + assert eval_int("return -1 % 0x7fffffffffffffff") == @maxint - 1 + end + end end