Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 33 additions & 2 deletions .agents/plans/A0-int-overflow-wrapping.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
31 changes: 19 additions & 12 deletions lib/lua/vm/executor.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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,
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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 ──────────────────────────────────────────────────────
Expand Down
85 changes: 85 additions & 0 deletions lib/lua/vm/numeric.ex
Original file line number Diff line number Diff line change
@@ -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
65 changes: 65 additions & 0 deletions test/lua/vm/arithmetic_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading