From ed5b730f1f9a706bc7cad5bcc33c46ab5995512f Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Wed, 6 May 2026 18:10:15 -0700 Subject: [PATCH 1/3] chore(A7): start plan --- .agents/plans/A7-nextvar-suite.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/plans/A7-nextvar-suite.md b/.agents/plans/A7-nextvar-suite.md index 0d3a4035..15f589cf 100644 --- a/.agents/plans/A7-nextvar-suite.md +++ b/.agents/plans/A7-nextvar-suite.md @@ -5,7 +5,7 @@ issue: 168 pr: null branch: fix/nextvar-suite base: main -status: ready +status: in-progress direction: A unlocks: - nextvar.lua From 64c03827faea91190adfeaa416da55cc25ff765a Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Wed, 6 May 2026 18:26:26 -0700 Subject: [PATCH 2/3] =?UTF-8?q?fix(vm):=20align=20table=20key=20semantics?= =?UTF-8?q?=20with=20Lua=205.3=20=C2=A73.4.11?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three closely-related table-semantics bugs in the VM and stdlib: * Assigning `nil` to a key did not delete the key, so `#{nil}` returned 1, `t[k] = nil` left the entry visible to `pairs`, and `next(t)` returned a key whose value was nil. * Float keys with an exact integer value lived in a different slot from their integer counterpart, so `t[2^0] = v` followed by `t[1]` read nothing. * `pairs()` and `ipairs()` with no argument or a non-table argument crashed the BEAM with a `FunctionClauseError` instead of raising a Lua-level "bad argument" error. A new `Lua.VM.Table.put_data/3` helper centralizes the write-as-delete and integer-coercion rules, with matching `get_data/2` and `has_data?/2` read helpers. Every table-data mutation in `executor.ex`, `state.ex`, and `stdlib.ex` (rawset, rawget, next, set_global) now flows through those helpers, so the contract holds uniformly across the four write paths (set_table, set_field, set_list, table_newindex) and rawset. Eighteen new unit tests in `test/lua/vm/nextvar_semantics_test.exs` pin the §3.4.11 rules on small focused inputs so any future regression points at the specific semantic that broke. This is the first half of plan A7. The second half — dead-key tracking so `next(t, k)` survives `t[k] = nil` mid-iteration, plus the strict "invalid key" raise that depends on it — is split out to plan A7a. With dead keys in place, `nextvar.lua` will pass end-to-end and can be promoted to the ready set in `lua53_suite_test.exs`. Plan: A7 Refs #168 --- lib/lua/vm/executor.ex | 17 +-- lib/lua/vm/state.ex | 2 +- lib/lua/vm/stdlib.ex | 24 +++- lib/lua/vm/table.ex | 73 ++++++++++++ test/lua/vm/nextvar_semantics_test.exs | 152 +++++++++++++++++++++++++ 5 files changed, 255 insertions(+), 13 deletions(-) create mode 100644 test/lua/vm/nextvar_semantics_test.exs diff --git a/lib/lua/vm/executor.ex b/lib/lua/vm/executor.ex index d8bc44f0..492a33a6 100644 --- a/lib/lua/vm/executor.ex +++ b/lib/lua/vm/executor.ex @@ -16,6 +16,7 @@ defmodule Lua.VM.Executor do alias Lua.VM.Numeric alias Lua.VM.RuntimeError alias Lua.VM.State + alias Lua.VM.Table alias Lua.VM.TypeError alias Lua.VM.Value @@ -1075,7 +1076,7 @@ defmodule Lua.VM.Executor do if total > 0 do Enum.reduce(0..(total - 1), table.data, fn i, data -> value = elem(regs, start + i) - Map.put(data, offset + i + 1, value) + Table.put_data(data, offset + i + 1, value) end) else table.data @@ -1101,7 +1102,7 @@ defmodule Lua.VM.Executor do if values_to_collect > 0 do Enum.reduce(0..(values_to_collect - 1), table.data, fn i, data -> value = elem(regs, start + i) - Map.put(data, offset + i + 1, value) + Table.put_data(data, offset + i + 1, value) end) else table.data @@ -1109,7 +1110,7 @@ defmodule Lua.VM.Executor do else Enum.reduce(1..count, table.data, fn i, data -> value = elem(regs, start + i - 1) - Map.put(data, offset + i, value) + Table.put_data(data, offset + i, value) end) end @@ -1434,7 +1435,7 @@ defmodule Lua.VM.Executor do table = Map.fetch!(state.tables, id) - case Map.get(table.data, key) do + case Table.get_data(table.data, key) do nil -> case table.metatable do nil -> @@ -1468,15 +1469,15 @@ defmodule Lua.VM.Executor do table = Map.fetch!(state.tables, id) - if Map.has_key?(table.data, key) do + if Table.has_data?(table.data, key) do State.update_table(state, {:tref, id}, fn t -> - %{t | data: Map.put(t.data, key, value)} + %{t | data: Table.put_data(t.data, key, value)} end) else case table.metatable do nil -> State.update_table(state, {:tref, id}, fn t -> - %{t | data: Map.put(t.data, key, value)} + %{t | data: Table.put_data(t.data, key, value)} end) {:tref, mt_id} -> @@ -1485,7 +1486,7 @@ defmodule Lua.VM.Executor do case Map.get(mt.data, "__newindex") do nil -> State.update_table(state, {:tref, id}, fn t -> - %{t | data: Map.put(t.data, key, value)} + %{t | data: Table.put_data(t.data, key, value)} end) {:tref, _} = newindex_table -> diff --git a/lib/lua/vm/state.ex b/lib/lua/vm/state.ex index 72174177..0018b474 100644 --- a/lib/lua/vm/state.ex +++ b/lib/lua/vm/state.ex @@ -61,7 +61,7 @@ defmodule Lua.VM.State do @spec set_global(t(), binary(), term()) :: t() def set_global(%__MODULE__{g_ref: g_ref} = state, name, value) when is_binary(name) and not is_nil(g_ref) do update_table(state, g_ref, fn table -> - %{table | data: Map.put(table.data, name, value)} + %{table | data: Table.put_data(table.data, name, value)} end) end diff --git a/lib/lua/vm/stdlib.ex b/lib/lua/vm/stdlib.ex index 31ae4b72..beb5aac9 100644 --- a/lib/lua/vm/stdlib.ex +++ b/lib/lua/vm/stdlib.ex @@ -11,6 +11,7 @@ defmodule Lua.VM.Stdlib do alias Lua.VM.Executor alias Lua.VM.RuntimeError alias Lua.VM.State + alias Lua.VM.Table alias Lua.VM.TypeError alias Lua.VM.Value @@ -246,14 +247,14 @@ defmodule Lua.VM.Stdlib do # rawget(table, key) — get without metamethods defp lua_rawget([{:tref, id}, key | _], state) do table = Map.fetch!(state.tables, id) - {[Map.get(table.data, key)], state} + {[Table.get_data(table.data, key)], state} end # rawset(table, key, value) — set without metamethods defp lua_rawset([{:tref, _} = tref, key, value | _], state) do state = State.update_table(state, tref, fn table -> - %{table | data: Map.put(table.data, key, value)} + %{table | data: Table.put_data(table.data, key, value)} end) {[tref], state} @@ -280,7 +281,7 @@ defmodule Lua.VM.Stdlib do # next(table [, key]) — returns next key-value pair after key defp lua_next([{:tref, id} | rest], state) do - key = List.first(rest) + key = rest |> List.first() |> Table.normalize_key() table = Map.fetch!(state.tables, id) case find_next_entry(table.data, key) do @@ -302,7 +303,14 @@ defmodule Lua.VM.Stdlib do end defp find_next_entry(data, key) do - # Walk the iterator until we find key, then return the next entry + # Walk the iterator until we find key, then return the next entry. + # NOTE: Lua 5.3 §6.1 says `next(t, k)` should error when `k` is not + # present in `t`. We can't yet emit that error reliably because we + # don't track "dead keys" — when a for-in loop sets `t[k] = nil` + # mid-iteration, real Lua keeps the key reachable in the hash chain + # so iteration continues. Until that lands (plan A7a), be lenient + # and treat a missing key as end-of-iteration. Direct `next(t, bad)` + # calls therefore return nil, nil instead of raising "invalid key". iter = :maps.iterator(data) find_after_key(iter, key) end @@ -329,6 +337,10 @@ defmodule Lua.VM.Stdlib do {[next_func, tref, nil], state} end + defp lua_pairs([], _state), do: raise(ArgumentError.value_expected("pairs", 1)) + + defp lua_pairs([v | _], _state), do: raise(ArgumentError.type_error("pairs", 1, "table", Value.type_name(v))) + # ipairs(table) — returns iterator function, table, 0 defp lua_ipairs([{:tref, _} = tref | _], state) do iterator = @@ -347,6 +359,10 @@ defmodule Lua.VM.Stdlib do {[iterator, tref, 0], state} end + defp lua_ipairs([], _state), do: raise(ArgumentError.value_expected("ipairs", 1)) + + defp lua_ipairs([v | _], _state), do: raise(ArgumentError.type_error("ipairs", 1, "table", Value.type_name(v))) + # select(index, ...) — returns arguments starting from index # select('#', ...) — returns count of arguments defp lua_select(["#" | args], state) do diff --git a/lib/lua/vm/table.ex b/lib/lua/vm/table.ex index 8893c2a5..4ce92fc7 100644 --- a/lib/lua/vm/table.ex +++ b/lib/lua/vm/table.ex @@ -14,4 +14,77 @@ defmodule Lua.VM.Table do data: %{optional(term()) => term()}, metatable: {:tref, non_neg_integer()} | nil } + + @doc """ + Writes `value` into a table data map under `key`, honoring Lua semantics: + + * Assigning `nil` removes the key (Lua spec §3.4.11 — fields with `nil` + values are absent from the table). + * Any other value is stored normally. + + Used by every code path that mutates table contents (`set_table`, + `set_field`, `set_list`, `rawset`) so the "store-as-delete" rule is + applied uniformly. + """ + @spec put_data(map(), term(), term()) :: map() + def put_data(data, key, value) do + key = normalize_key(key) + + case value do + nil -> Map.delete(data, key) + _ -> Map.put(data, key, value) + end + end + + @doc """ + Normalizes a table key per Lua 5.3 §3.4.11. + + Float keys that hold an exact integer value are coerced to integers so + that `t[1.0]` and `t[1]` refer to the same slot. NaN keys are left as + floats; callers that disallow NaN keys (`set_table`, `rawset`) detect + the NaN and raise before reaching the data map. + """ + @spec normalize_key(term()) :: term() + def normalize_key(key) when is_float(key) do + cond do + # NaN is not equal to itself; leave as-is so the caller can detect it. + key != key -> + key + + # Integer-valued floats convert to integers. + key == trunc(key) and key >= -9_223_372_036_854_775_808.0 and key <= 9_223_372_036_854_775_807.0 -> + trunc(key) + + true -> + key + end + end + + def normalize_key(key), do: key + + @doc """ + Returns true if a key is invalid for use in a table assignment. + + Per Lua 5.3 §3.4.11 / §6.1, table keys cannot be `nil` or `NaN`. + Callers should `raise` with the appropriate "table index is nil" / + "table index is NaN" error message before mutating table data. + """ + @spec invalid_key?(term()) :: boolean() + def invalid_key?(nil), do: true + def invalid_key?(key) when is_float(key) and key != key, do: true + def invalid_key?(_), do: false + + @doc """ + Reads a value from a table data map, applying Lua key normalization + (integer-valued floats collapse to integers per §3.4.11). + """ + @spec get_data(map(), term()) :: term() + def get_data(data, key), do: Map.get(data, normalize_key(key)) + + @doc """ + Returns true when the table data map has an entry for the given key + after normalization. + """ + @spec has_data?(map(), term()) :: boolean() + def has_data?(data, key), do: Map.has_key?(data, normalize_key(key)) end diff --git a/test/lua/vm/nextvar_semantics_test.exs b/test/lua/vm/nextvar_semantics_test.exs new file mode 100644 index 00000000..a0016da0 --- /dev/null +++ b/test/lua/vm/nextvar_semantics_test.exs @@ -0,0 +1,152 @@ +defmodule Lua.VM.NextvarSemanticsTest do + @moduledoc """ + Regressions for the table semantics gaps surfaced by `nextvar.lua` (plan A7). + + Each test pins a single Lua 5.3 contract that the suite exercises. The cases + here are deliberately small so a future regression points at the specific + semantic that broke, not at the 600-line suite file. + + See `.agents/plans/A7-nextvar-suite.md` for context. The plan covers three + fixes in this PR: + + 1. Assigning `nil` to a key removes the key (Lua 5.3 §3.4.11). + 2. Float keys with an exact integer value collapse to integers + (Lua 5.3 §3.4.11). + 3. `pairs`/`ipairs` raise "bad argument" for non-table inputs. + + A fourth gap (dead-key tracking so iteration tolerates `t[k] = nil` + during `pairs`) is deferred to plan A7a. + """ + + use ExUnit.Case, async: true + + defp run!(code) do + {results, _state} = Lua.eval!(Lua.new(), code) + results + end + + describe "nil-value writes delete the key (§3.4.11)" do + test "table constructor with explicit nil leaves index unset" do + assert run!("return \#{}") == [0] + assert run!("return \#{nil}") == [0] + assert run!("return \#{nil, nil}") == [0] + assert run!("return \#{nil, nil, nil}") == [0] + end + + test "leading non-nil followed by nils still reports a small border" do + assert run!("return \#{1, nil, nil}") == [1] + assert run!("return \#{1, 2, nil}") == [2] + end + + test "rawlen ignores trailing nil entries from the constructor" do + assert run!("return rawlen({nil})") == [0] + assert run!("return rawlen({1, nil, nil})") == [1] + end + + test "assignment of nil clears the key from rawget" do + assert run!("local t = {a = 1}; t.a = nil; return rawget(t, 'a')") == [nil] + assert run!("local t = {1, 2, 3}; t[2] = nil; return rawget(t, 2)") == [nil] + end + + test "assignment of nil removes the key from pairs iteration" do + code = """ + local t = {a = 1, b = 2} + t.a = nil + local n = 0 + for _ in pairs(t) do n = n + 1 end + return n + """ + + assert run!(code) == [1] + end + + test "rawset(t, k, nil) removes the key" do + assert run!("local t = {1, 2}; rawset(t, 2, nil); return rawget(t, 2)") == [nil] + end + + test "next on a table whose only key was cleared returns nil" do + # `next` returns two values when there is no next entry: a nil key + # and a nil value. After clearing the sole key, iteration is over. + assert run!("local t = {x = 1}; t.x = nil; return next(t)") == [nil, nil] + end + end + + describe "float keys with exact integer value collapse to integers (§3.4.11)" do + test "writing t[1.0] = v makes t[1] read v" do + assert run!("local t = {}; t[1.0] = 'hello'; return t[1]") == ["hello"] + end + + test "writing t[1] = v makes t[1.0] read v" do + assert run!("local t = {}; t[1] = 'hello'; return t[1.0]") == ["hello"] + end + + test "rawset and rawget agree across integer/float forms" do + code = """ + local t = {} + rawset(t, 5.0, 42) + return rawget(t, 5) + """ + + assert run!(code) == [42] + end + + test "next reports the key in canonical integer form" do + assert run!("local t = {}; t[2.0] = 'v'; local k = next(t); return k") == [2] + end + + test "float-keyed integer indices act as integer keys" do + # Float-power keys must round-trip through normalization so that + # `t[2.0^i]` is reachable via `t[1]`, `t[2]`, etc. Before A7 these + # writes landed at *float* keys and the reads found nothing. + code = """ + local t = {} + for i = 0, 4 do t[2.0 ^ i] = true end + return t[1], t[2], t[4], t[8], t[16] + """ + + assert run!(code) == [true, true, true, true, true] + end + + test "length operator after float-key writes returns a valid border" do + # `#t` is allowed to return any border `n` (n where t[n]~=nil and + # t[n+1]==nil). For the dense block {1, 2} starting from key 1, the + # smallest border is 2 (since t[2] is set and t[3] is nil). Real + # Lua 5.3 returns 2 here. + assert run!("local t = {} t[1.0] = 'a'; t[2.0] = 'b'; return \#t") == [2] + + # Pin the symptom that originally broke nextvar.lua line 310: + # `a[#a]` after dense float-keyed writes must reach a real value. + assert run!("local t = {} t[1.0] = 'a'; t[2.0] = 'b'; return t[\#t]") == ["b"] + end + + test "non-integer float keys are preserved as floats" do + assert run!("local t = {}; t[1.5] = 'half'; return t[1.5], t[1]") == ["half", nil] + end + end + + describe "pairs and ipairs validate their argument" do + test "pairs() with no argument raises 'bad argument'" do + assert_raise Lua.RuntimeException, ~r/bad argument #1 to 'pairs'/, fn -> + Lua.eval!(Lua.new(), "pairs()") + end + end + + test "ipairs() with no argument raises 'bad argument'" do + assert_raise Lua.RuntimeException, ~r/bad argument #1 to 'ipairs'/, fn -> + Lua.eval!(Lua.new(), "ipairs()") + end + end + + test "pairs(non_table) raises 'bad argument'" do + assert_raise Lua.RuntimeException, ~r/bad argument #1 to 'pairs'/, fn -> + Lua.eval!(Lua.new(), "pairs(42)") + end + end + + test "ipairs(non_table) raises 'bad argument'" do + assert_raise Lua.RuntimeException, ~r/bad argument #1 to 'ipairs'/, fn -> + Lua.eval!(Lua.new(), "ipairs('hello')") + end + end + end +end From d78728060ff34e0bdee32b13814532e658dedbaa Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Wed, 6 May 2026 18:27:42 -0700 Subject: [PATCH 3/3] chore(A7): mark plan as review and queue A7a A7 ships PR #200 with three of four nextvar.lua root causes fixed. The remaining gap (dead-key tracking so `next(t, k)` survives `t[k] = nil` mid-iteration) is captured as plan A7a so `nextvar.lua` can be promoted to the ready set there. --- .agents/plans/A7-nextvar-suite.md | 84 ++++++++++++++++-- .agents/plans/A7a-nextvar-dead-keys.md | 114 +++++++++++++++++++++++++ 2 files changed, 191 insertions(+), 7 deletions(-) create mode 100644 .agents/plans/A7a-nextvar-dead-keys.md diff --git a/.agents/plans/A7-nextvar-suite.md b/.agents/plans/A7-nextvar-suite.md index 15f589cf..912f3950 100644 --- a/.agents/plans/A7-nextvar-suite.md +++ b/.agents/plans/A7-nextvar-suite.md @@ -2,13 +2,13 @@ id: A7 title: Fix nextvar.lua "concatenate nil" failure issue: 168 -pr: null +pr: 200 branch: fix/nextvar-suite base: main -status: in-progress +status: review direction: A unlocks: - - nextvar.lua + - nextvar.lua # partial — full pass requires A7a (dead-key tracking) --- ## Goal @@ -23,9 +23,12 @@ nil correctly will let downstream code distinguish absent from present). ## Success criteria -- [ ] `mix test` passes (≥ 1273, no regressions) -- [ ] Each fixed issue has a unit test in `test/lua/vm/nextvar_*_test.exs` -- [ ] `nextvar.lua` passes end-to-end. +- [x] `mix test` passes (≥ 1273, no regressions) — 1420 tests, 0 failures +- [x] Each fixed issue has a unit test in `test/lua/vm/nextvar_*_test.exs` + (`test/lua/vm/nextvar_semantics_test.exs`, 18 cases) +- [ ] `nextvar.lua` passes end-to-end — **partial**. Three of four root + causes fixed; the fourth (dead-key tracking for iterate-then-clear) + is split out to plan A7a. ## Implementation notes @@ -52,4 +55,71 @@ mix test --only lua53 ## Discoveries -(populated during implementation) +The `nextvar.lua` failure had shifted by the time A7 ran — A1 had landed +and the original "concatenate nil" symptom was gone, replaced by an +assertion failure deeper in the file. Bisecting line by line surfaced +four distinct Lua 5.3 semantics gaps in the VM and stdlib: + +1. **Assigning `nil` to a table key did not delete the key.** + `set_table`, `set_field`, `set_list`, `table_newindex`, and `rawset` + all called `Map.put(data, key, nil)` instead of `Map.delete(data, key)`. + Consequences: `#{nil}` returned 1, `for k,v in pairs(t) do t[k] = nil end` + left every key visible, and `next(t)` returned a key whose value was + `nil`. + +2. **Float keys with an exact integer value were stored as floats.** + `t[2.0] = v` and `t[2] = v` lived in different slots; `t[1]` after + `for i=0,4 do t[2^i] = true end` returned nil because `2^0` is `1.0` + (float). Lua 5.3 §3.4.11 mandates integer-valued floats collapse to + integers as table keys. + +3. **`pairs` and `ipairs` did not validate their argument.** Calling + them with no argument or with a non-table value crashed the BEAM + process with a `FunctionClauseError` instead of raising the Lua-level + "bad argument" error. + +4. **`next(t, k)` does not handle keys that were valid mid-iteration + and are now nil.** Real Lua keeps removed keys reachable in the hash + chain (the "dead key" trick) so `for k,v in pairs(t) do t[k] = nil end` + works. We don't have dead-key tracking, so iteration breaks as soon + as a key is cleared. Per Lua 5.3 §6.1, a strict `next` should also + raise "invalid key" when the key never existed in the table — but + that strict check conflicts with mid-iteration deletion until dead + keys are implemented. + +This PR fixes (1), (2), and (3), each with a focused unit test in +`test/lua/vm/nextvar_semantics_test.exs`. The `next` error path is +left lenient (returns `nil, nil` for missing keys) so the dead-key gap +in (4) can be closed in plan **A7a — dead keys for `next`** without +this PR causing iteration regressions in the meantime. With (4) fixed, +`nextvar.lua` should pass end-to-end and be promoted to `@ready_tests` +in `test/lua53_suite_test.exs`. + +### Files touched + +- `lib/lua/vm/table.ex` — added `put_data/3`, `get_data/2`, `has_data?/2`, + `normalize_key/1`, `invalid_key?/1` so every table-data access can + share the same write-as-delete and integer-coercion rules. +- `lib/lua/vm/executor.ex` — routed `set_table`, `set_field`, `set_list` + (both variants), `table_index`, and `table_newindex` through the new + helpers. +- `lib/lua/vm/state.ex` — `set_global` now deletes when the value is + `nil` so `x = nil` at top level removes the global. +- `lib/lua/vm/stdlib.ex` — `rawset`/`rawget` use the new helpers; + `pairs`/`ipairs` raise `ArgumentError` for missing or wrong-typed + arguments; `next` normalizes float-int keys. +- `test/lua/vm/nextvar_semantics_test.exs` — new file pinning each fix. + +## What changed + +- PR: #200 (`fix(vm): align table key semantics with Lua 5.3 §3.4.11`) +- `mix test`: 1402 → 1420 (+18 unit tests; 0 failures, 31 skipped). +- `mix test --only lua53`: 5 ready / 24 skipped (unchanged — `nextvar.lua` + stays skipped until A7a lands). +- Files touched (5): `lib/lua/vm/table.ex`, `lib/lua/vm/executor.ex`, + `lib/lua/vm/state.ex`, `lib/lua/vm/stdlib.ex`, plus new + `test/lua/vm/nextvar_semantics_test.exs`. +- Follow-up: `.agents/plans/A7a-nextvar-dead-keys.md` — dead-key + tracking so `next(t, k)` survives `t[k] = nil` mid-iteration, plus + the strict "invalid key" raise it unblocks. Promoting `nextvar.lua` + to `@ready_tests` happens there. diff --git a/.agents/plans/A7a-nextvar-dead-keys.md b/.agents/plans/A7a-nextvar-dead-keys.md new file mode 100644 index 00000000..9412e828 --- /dev/null +++ b/.agents/plans/A7a-nextvar-dead-keys.md @@ -0,0 +1,114 @@ +--- +id: A7a +title: Dead-key tracking for `next` so nextvar.lua passes end-to-end +issue: null +pr: null +branch: fix/nextvar-dead-keys +base: main +status: ready +direction: A +unlocks: + - nextvar.lua +--- + +## Goal + +Finish the work of plan A7 by making `nextvar.lua` pass end-to-end. +The remaining gap is the "dead-key" semantics that real Lua uses to +keep `next(t, k)` working when `t[k]` was just set to `nil` during +`pairs` iteration. + +Lua 5.3 §6.1 says: + +> The behavior of next is undefined if, during the traversal, you assign +> any value to a non-existent field in the table. You may, however, modify +> existing fields. In particular, you may clear existing fields. + +The reference implementation supports the second sentence by leaving +removed keys reachable in the hash chain (marked `TDEADKEY`) so iteration +that already passed through that slot can still find the next live entry. + +## Out of scope + +- Anything outside dead-key tracking and the strict-`next` error path it + unblocks. In particular: the table representation rewrite, faster + `next`/`pairs`/`ipairs` implementations, stricter NaN-key handling. +- Promoting other suite files to `@ready_tests`. + +## Success criteria + +- [ ] `mix test` passes (≥ 1420, no regressions). +- [ ] `next(t, k)` raises "invalid key to 'next'" when `k` was *never* a + key in `t` (Lua 5.3 §6.1; nextvar.lua line 230). +- [ ] `for k, v in pairs(t) do t[k] = nil end` iterates every key once + without raising (nextvar.lua line 320–326). +- [ ] `nextvar.lua` passes end-to-end and is promoted to + `@ready_tests` in `test/lua53_suite_test.exs`. +- [ ] Unit tests in `test/lua/vm/nextvar_dead_keys_test.exs`: + one for the "never-existed key" error, one for the + "iterate-then-clear" loop, one for "clear, re-assign, iterate" + to make sure dead-key state doesn't leak across same-key reuse. + +## Implementation notes + +A few candidate shapes: + +1. **Per-table iteration order list.** Add `Lua.VM.Table` an `order` list + that mirrors keys in insertion order, plus a `dead` MapSet for keys + whose slot is still in `order` but whose value has been cleared. + `next(t, k)` walks `order` until it sees `k`, then returns the next + `order` entry whose key is in `data`. `t[k] = nil` removes the key + from `data` and adds to `dead`. `t[k] = v` (re-assignment) removes + from `dead` and from `order`, and re-appends to `order`. This gives + the same observable behavior as Lua's dead-key trick without changing + the data map shape. + +2. **Track a "tombstones" map.** Same idea but separate from `order` — + `data` holds live values, `tombstones` holds previously-seen keys. + `next` falls through `tombstones` to the next live entry. Slightly + simpler than maintaining `order`. + +3. **Use `:maps.iterator/1` snapshot once per pairs call.** Less + faithful to Lua semantics; doesn't survive `t[k] = v` for new `v`. + +Recommend (1). Consequences: + +- Insertion order is deterministic (we already get this from Erlang maps, + but it's not guaranteed for large maps). Storing it explicitly removes + the dependency. +- `for k in pairs(t)` will iterate in insertion order, matching the + closest thing Lua specifies. +- `Table.put_data/3` becomes the single place that has to maintain + `order` and `dead`. Read paths don't change. + +After landing: + +1. Add the strict-`next` raise back in `lib/lua/vm/stdlib.ex` (the comment + in `find_next_entry` calls this out — drop the comment when removing + the leniency). +2. Move `nextvar.lua` from `@skipped_tests` to `@ready_tests` in + `test/lua53_suite_test.exs`. +3. Verify the rest of the suite still passes. + +## Verification + +```bash +mix format +mix compile --warnings-as-errors +mix test +mix test --only lua53 +``` + +## Risks + +- Changing the table representation (adding `order`/`dead`) touches + every write path. Plenty of risk for subtle regressions in + `pairs`/`ipairs`/`#`. Land behind the existing `Table.put_data` + helpers from A7 to keep the surface narrow. +- Performance: `order` is an O(n) list. For tables with frequent + re-assignments to the same key, list churn could matter. Defer the + perf fix until benchmarks demand it. + +## Discoveries + +(populated during implementation)