From b8f090e1b95ac49af329d7368217fcd261deec0b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 22 Nov 2025 16:42:51 +0000
Subject: [PATCH] Add Phase 122+ modernization recommendations

Comprehensive analysis of next modernization opportunities:

Tier 1 (High-Value, Low-Risk):
- Phase 122: constexpr expansion (50+ getters, 2-3 hours)
- Phase 123: [[nodiscard]] annotations (30-40 functions, 4-6 hours)
- Phase 124: Constant macros to constexpr (15-20 macros, 2-3 hours)

Tier 2 (Medium-Value, Medium-Risk):
- Phase 125: GC macro modernization (5-7 macros, requires benchmarking)
- Phase 126: std::span expansion (20-30 sites, requires careful benchmarking)

Tier 3 (Defer):
- Range-based for loops (limited benefit)
- Loop counter/size conversions (high risk, low value)
- cast() macro elimination (massive scope)

Status update:
- Boolean conversions: Already complete! (5/8 already done, 3/8 not boolean functions)
- Constructor patterns: Already using member initializer lists (Phase 122)
- Current performance: 4.26s avg (better than 4.33s target)

Includes specific file locations, line numbers, code examples, and detailed
risk assessments for each opportunity.
---
 docs/PHASE_122_PLUS_RECOMMENDATIONS.md | 1194 ++++++++++++++++++++++++
 1 file changed, 1194 insertions(+)
 create mode 100644 docs/PHASE_122_PLUS_RECOMMENDATIONS.md

diff --git a/docs/PHASE_122_PLUS_RECOMMENDATIONS.md b/docs/PHASE_122_PLUS_RECOMMENDATIONS.md
new file mode 100644
index 00000000..bef9ed81
--- /dev/null
+++ b/docs/PHASE_122_PLUS_RECOMMENDATIONS.md
@@ -0,0 +1,1194 @@
+# Phase 122+ Modernization Recommendations
+
+**Date**: November 22, 2025
+**Current Status**: Phase 121 Complete (Header Modularization)
+**Current Performance**: ~4.26s avg ✅ (better than 4.33s target!)
+**Modernization Progress**: ~99% complete
+
+---
+
+## Executive Summary
+
+After 121 phases of aggressive modernization, the Lua C++ conversion project has achieved excellent results:
+- ✅ **19/19 classes** with full encapsulation
+- ✅ **~500 macros converted** (~99% complete)
+- ✅ **100% modern C++ casts**
+- ✅ **All enums are enum classes**
+- ✅ **Performance**: 4.26s avg (better than 4.33s target)
+- ✅ **96.1% code coverage**
+- ✅ **Zero warnings**, all tests passing
+
+This document identifies **specific, actionable opportunities** for continued modernization, prioritized by value and risk.
+
+---
+
+## Table of Contents
+
+1. [Tier 1: High-Value, Low-Risk (Recommended Next)](#tier-1-high-value-low-risk)
+2. [Tier 2: Medium-Value, Medium-Risk (Benchmark Required)](#tier-2-medium-value-medium-risk)
+3. [Tier 3: Defer (High Risk or Low Value)](#tier-3-defer)
+4. [Status Update: Boolean Conversions](#status-update-boolean-conversions)
+5. [Recommended Execution Plan](#recommended-execution-plan)
+6. [Performance Requirements](#performance-requirements)
+
+---
+
+## Tier 1: High-Value, Low-Risk
+
+These phases are **recommended for immediate implementation** with high confidence of success.
+
+---
+
+### Phase 122: constexpr Expansion ⭐ **TOP PRIORITY**
+
+**Value**: HIGH | **Risk**: VERY LOW | **Effort**: 2-3 hours
+
+#### Problem
+
+Many simple getter methods are marked `inline const noexcept` but could be `inline constexpr` for better optimization and compile-time evaluation.
+
+#### Opportunity
+
+**Estimated count**: 50+ simple getters across multiple files
+
+#### Specific Examples
+
+**File: `src/core/lstate.h:793-813`**
+
+```cpp
+// CURRENT:
+inline lu_byte getParam(int idx) const noexcept { return params[idx]; }
+inline lu_byte getCurrentWhite() const noexcept { return currentwhite; }
+inline GCState getState() const noexcept { return static_cast<GCState>(state); }
+inline GCKind getKind() const noexcept { return static_cast<GCKind>(kind); }
+inline lu_byte getStopEm() const noexcept { return stopem; }
+inline lu_byte getStp() const noexcept { return stp; }
+inline bool isRunning() const noexcept { return stp == 0; }
+inline lu_byte getEmergency() const noexcept { return emergency; }
+
+// PROPOSED:
+inline constexpr lu_byte getParam(int idx) const noexcept { return params[idx]; }
+inline constexpr lu_byte getCurrentWhite() const noexcept { return currentwhite; }
+inline constexpr GCState getState() const noexcept { return static_cast<GCState>(state); }
+inline constexpr GCKind getKind() const noexcept { return static_cast<GCKind>(kind); }
+inline constexpr lu_byte getStopEm() const noexcept { return stopem; }
+inline constexpr lu_byte getStp() const noexcept { return stp; }
+inline constexpr bool isRunning() const noexcept { return stp == 0; }
+inline constexpr lu_byte getEmergency() const noexcept { return emergency; }
+```
+
+**File: `src/compiler/lparser.h:471-553`** - FuncState getters
+
+```cpp
+// Example getters to convert:
+inline lu_byte getFreeReg() const noexcept { return freereg; }
+inline lu_byte getNActVar() const noexcept { return nactvar; }
+inline int getPc() const noexcept { return pc; }
+inline int getLastTarget() const noexcept { return lasttarget; }
+inline int getFirstLocal() const noexcept { return firstlocal; }
+inline int getFirstLabel() const noexcept { return firstlabel; }
+
+// Should become:
+inline constexpr lu_byte getFreeReg() const noexcept { return freereg; }
+inline constexpr lu_byte getNActVar() const noexcept { return nactvar; }
+inline constexpr int getPc() const noexcept { return pc; }
+// ... etc
+```
+
+**File: `src/objects/lproto.h:44-106`** - Proto getters
+
+```cpp
+// Many getters like:
+inline int getMaxStackSize() const noexcept { return maxstacksize; }
+inline int getSizeUpvalues() const noexcept { return sizeupvalues; }
+inline int getSizeK() const noexcept { return sizek; }
+inline int getSizeCode() const noexcept { return sizecode; }
+inline int getSizeLineInfo() const noexcept { return sizelineinfo; }
+inline int getSizeP() const noexcept { return sizep; }
+
+// All can add constexpr
+```
+
+**File: `src/objects/ltable.h:74-109`** - Table getters
+
+```cpp
+// Examples:
+inline unsigned int arraySize() const noexcept { return asize; }
+inline lu_byte getFlags() const noexcept { return flags; }
+inline lu_byte getLogSizeNode() const noexcept { return lsizenode; }
+
+// Should become constexpr
+```
+
+**File: `src/objects/lobject_core.h`** - GCBase getters
+
+```cpp
+// Core GC getters:
+inline lu_byte getType() const noexcept { return tt; }
+inline lu_byte getMarked() const noexcept { return marked; }
+
+// Add constexpr
+```
+
+#### Implementation Strategy
+
+1. **Pattern recognition**: Search for `inline.*const noexcept { return`
+2. **Verification**: Ensure function body is a simple return statement (no side effects)
+3. **Conversion**: Add `constexpr` keyword
+4. **Testing**: Compile and run tests (should be immediate pass)
+
+```bash
+# Search pattern to find candidates:
+grep -rn "inline.*const noexcept { return" src/core/lstate.h src/compiler/lparser.h src/objects/
+```
+
+#### Benefits
+
+- ✅ **Compile-time evaluation**: Values can be computed at compile time
+- ✅ **Better optimization**: Compiler has more freedom to inline and optimize
+- ✅ **Zero runtime cost**: No performance impact
+- ✅ **Self-documenting**: `constexpr` signals pure computation with no side effects
+- ✅ **Future-proofing**: Enables use in constexpr contexts
+
+#### Risk Assessment
+
+**Risk**: VERY LOW
+- Purely additive change (doesn't remove functionality)
+- Compile-time error if function can't be constexpr (safe)
+- No runtime behavior change
+- All getters are simple field accesses or casts
+
+#### Estimated Time
+
+**2-3 hours** total:
+- 1 hour: Identify and convert lstate.h, lparser.h
+- 1 hour: Convert lproto.h, ltable.h, lobject_core.h
+- 30 min: Build, test, commit
+
+---
+
+### Phase 123: [[nodiscard]] Safety Annotations ⭐
+
+**Value**: HIGH | **Risk**: MEDIUM | **Effort**: 4-6 hours
+
+#### Context
+
+Phase 118 added 15 `[[nodiscard]]` annotations and **caught 1 real bug** (ignored return value). Expanding this will prevent more bugs.
+
+#### Opportunity
+
+**Estimated count**: 30-40 functions across critical subsystems
+
+#### Priority 1: Memory Allocations (CRITICAL)
+
+**File: `src/memory/lmem.h:83-93`**
+
+Ignoring return values from allocation functions causes **memory leaks**. These are the most critical candidates.
+
+```cpp
+// CURRENT:
+LUAI_FUNC void *luaM_realloc_ (lua_State *L, void *block, size_t oldsize, size_t size);
+LUAI_FUNC void *luaM_saferealloc_ (lua_State *L, void *block, size_t oldsize, size_t size);
+LUAI_FUNC void *luaM_growaux_ (lua_State *L, void *block, int nelems, int *size,
+                               unsigned size_elem, int limit, const char *what);
+LUAI_FUNC void *luaM_shrinkvector_ (lua_State *L, void *block, int *nelem,
+                                     int final_n, unsigned size_elem);
+LUAI_FUNC void *luaM_malloc_ (lua_State *L, size_t size, int tag);
+
+// PROPOSED:
+[[nodiscard]] LUAI_FUNC void *luaM_realloc_ (lua_State *L, void *block, size_t oldsize, size_t size);
+[[nodiscard]] LUAI_FUNC void *luaM_saferealloc_ (lua_State *L, void *block, size_t oldsize, size_t size);
+[[nodiscard]] LUAI_FUNC void *luaM_growaux_ (lua_State *L, void *block, int nelems, int *size,
+                                              unsigned size_elem, int limit, const char *what);
+[[nodiscard]] LUAI_FUNC void *luaM_shrinkvector_ (lua_State *L, void *block, int *nelem,
+                                                    int final_n, unsigned size_elem);
+[[nodiscard]] LUAI_FUNC void *luaM_malloc_ (lua_State *L, size_t size, int tag);
+```
+
+**File: `src/memory/lgc.h:390-391`** - GC allocations
+
+```cpp
+// CURRENT:
+LUAI_FUNC GCObject *luaC_newobj (lua_State *L, LuaT tt, size_t sz);
+LUAI_FUNC GCObject *luaC_newobjdt (lua_State *L, LuaT tt, size_t sz, size_t offset);
+
+// PROPOSED:
+[[nodiscard]] LUAI_FUNC GCObject *luaC_newobj (lua_State *L, LuaT tt, size_t sz);
+[[nodiscard]] LUAI_FUNC GCObject *luaC_newobjdt (lua_State *L, LuaT tt, size_t sz, size_t offset);
+```
+
+**Count**: ~7 allocation functions
+
+#### Priority 2: Type Conversion Functions (IMPORTANT)
+
+**File: `src/vm/lvm.h:100-146`**
+
+These functions return `bool` indicating success/failure. Ignoring the return value means using potentially invalid data.
+
+```cpp
+// CURRENT:
+inline bool tonumber(const TValue* o, lua_Number* n) noexcept {
+    if (ttisfloat(o)) {
+        *n = fltvalue(o);
+        return true;
+    }
+    else if (cvt2num(o))
+        return false;  /* not convertible to number */
+    else {
+        *n = cast_num(ivalue(o));
+        return true;
+    }
+}
+
+inline bool tonumberns(const TValue* o, lua_Number& n) noexcept { ... }
+inline bool tointeger(const TValue* o, lua_Integer* i) noexcept { ... }
+inline bool tointegerns(const TValue* o, lua_Integer* i) noexcept { ... }
+
+// PROPOSED:
+[[nodiscard]] inline bool tonumber(const TValue* o, lua_Number* n) noexcept { ... }
+[[nodiscard]] inline bool tonumberns(const TValue* o, lua_Number& n) noexcept { ... }
+[[nodiscard]] inline bool tointeger(const TValue* o, lua_Integer* i) noexcept { ... }
+[[nodiscard]] inline bool tointegerns(const TValue* o, lua_Integer* i) noexcept { ... }
+```
+
+**File: `src/vm/lvm.h:239`**
+
+```cpp
+// CURRENT:
+LUAI_FUNC int luaV_flttointeger (lua_Number n, lua_Integer *p, F2Imod mode);
+
+// PROPOSED:
+[[nodiscard]] LUAI_FUNC int luaV_flttointeger (lua_Number n, lua_Integer *p, F2Imod mode);
+```
+
+**Count**: ~8 conversion functions
+
+#### Priority 3: Table and Stack Operations (MEDIUM)
+
+**File: `src/objects/ltable.h:273-276`**
+
+Protected set operations return status codes. Ignoring these means not knowing if operation succeeded.
+
+```cpp
+// CURRENT:
+int pset(const TValue* key, TValue* val);
+int psetInt(lua_Integer key, TValue* val);
+int psetShortStr(TString* key, TValue* val);
+int psetStr(TString* key, TValue* val);
+
+// PROPOSED:
+[[nodiscard]] int pset(const TValue* key, TValue* val);
+[[nodiscard]] int psetInt(lua_Integer key, TValue* val);
+[[nodiscard]] int psetShortStr(TString* key, TValue* val);
+[[nodiscard]] int psetStr(TString* key, TValue* val);
+```
+
+**File: `src/objects/ltable.h:452-455`** - Global functions
+
+```cpp
+[[nodiscard]] LUAI_FUNC int luaH_psetint (Table *t, lua_Integer key, TValue *val);
+[[nodiscard]] LUAI_FUNC int luaH_psetshortstr (Table *t, TString *key, TValue *val);
+[[nodiscard]] LUAI_FUNC int luaH_psetstr (Table *t, TString *key, TValue *val);
+[[nodiscard]] LUAI_FUNC int luaH_pset (Table *t, const TValue *key, TValue *val);
+```
+
+**File: `src/core/lstack.h:208, 321, 324`**
+
+Stack operations that can fail should not have their return values ignored.
+
+```cpp
+// CURRENT:
+int ensureSpace(lua_State* L, int n) { ... }
+int grow(lua_State* L, int n, int raiseerror);
+int realloc(lua_State* L, int newsize, int raiseerror);
+
+// PROPOSED:
+[[nodiscard]] int ensureSpace(lua_State* L, int n) { ... }
+[[nodiscard]] int grow(lua_State* L, int n, int raiseerror);
+[[nodiscard]] int realloc(lua_State* L, int newsize, int raiseerror);
+```
+
+**Count**: ~20 table/stack functions
+
+#### Implementation Strategy
+
+1. **Phase 123.1**: Memory allocations (highest priority, ~7 functions)
+2. **Phase 123.2**: Type conversions (~8 functions)
+3. **Phase 123.3**: Table/stack operations (~20 functions)
+
+#### Expected Issues
+
+Adding `[[nodiscard]]` may reveal existing code that ignores return values. This is **GOOD** - it exposes potential bugs.
+
+**Possible scenarios**:
+```cpp
+// Compiler will warn about this:
+tonumber(o, &n);  // ❌ Ignoring bool return - is conversion successful?
+
+// Must change to:
+if (!tonumber(o, &n)) {
+    // Handle conversion failure
+}
+
+// Or explicitly discard (if truly intentional):
+(void)tonumber(o, &n);  // Explicit "I know what I'm doing"
+```
+
+#### Benefits
+
+- ✅ **Bug prevention**: Compiler enforces checking critical return values
+- ✅ **Self-documenting**: Signatures show which functions require checking
+- ✅ **Historical evidence**: Phase 118 caught 1 bug with just 15 annotations
+- ✅ **Zero runtime cost**: Compile-time only
+
+#### Risk Assessment
+
+**Risk**: MEDIUM
+- May reveal existing code with ignored returns (GOOD - exposes bugs)
+- Requires fixing any warnings that appear
+- Some warnings may be false positives (use `(void)` cast if intentional)
+
+**Mitigation**:
+- Add annotations incrementally (Priority 1 → 2 → 3)
+- Fix warnings as they appear
+- Document any intentional discards with comments
+
+#### Estimated Time
+
+**4-6 hours** total:
+- 1-2 hours: Priority 1 (memory allocations + fix any warnings)
+- 1-2 hours: Priority 2 (conversions + fix warnings)
+- 2 hours: Priority 3 (table/stack + fix warnings)
+
+---
+
+### Phase 124: Constant Macros to constexpr
+
+**Value**: MEDIUM | **Risk**: VERY LOW | **Effort**: 2-3 hours
+
+#### Problem
+
+Numeric constant macros lack type safety and don't show in debuggers.
+
+#### Opportunity
+
+**Estimated count**: 15-20 constant macros
+
+#### Specific Examples
+
+**File: `src/compiler/parseutils.cpp:34, 116-119, 164`**
+
+```cpp
+// CURRENT:
+#define MAXVARS         200
+#define MAX_CNST        (INT_MAX/2)
+#define UNARY_PRIORITY  12
+
+// PROPOSED:
+inline constexpr int MAXVARS = 200;
+inline constexpr int MAX_CNST = INT_MAX / 2;
+inline constexpr int UNARY_PRIORITY = 12;
+```
+
+**File: `src/libraries/lstrlib.cpp:38, 350-351, 374, 378-379`**
+
+```cpp
+// CURRENT:
+#define LUA_MAXCAPTURES 32
+#define CAP_UNFINISHED  (-1)
+#define CAP_POSITION    (-2)
+#define MAXCCALLS       200
+#define L_ESC           '%'
+#define SPECIALS        "^$*+?.([%-"
+
+// PROPOSED:
+inline constexpr int LUA_MAXCAPTURES = 32;
+inline constexpr int CAP_UNFINISHED = -1;
+inline constexpr int CAP_POSITION = -2;
+inline constexpr int MAXCCALLS = 200;
+inline constexpr char L_ESC = '%';
+inline constexpr const char* SPECIALS = "^$*+?.([%-";
+```
+
+**Other Files**: Look for similar patterns in:
+- `src/libraries/lmathlib.cpp`
+- `src/libraries/lutf8lib.cpp`
+- `src/vm/lvm.cpp`
+
+#### Search Pattern
+
+```bash
+# Find constant macro candidates:
+grep -rn "^#define [A-Z_][A-Z_]* [0-9]" src/compiler src/libraries src/vm
+grep -rn "^#define [A-Z_][A-Z_]* ('[^']*')" src/
+```
+
+#### Benefits
+
+- ✅ **Type safety**: Macros are untyped, constexpr variables have types
+- ✅ **Debugger visibility**: Shows in debugger, macros don't
+- ✅ **Scoped properly**: Namespace/class scope, not global preprocessor
+- ✅ **Better error messages**: Type errors are clearer
+- ✅ **No performance impact**: Identical to macros
+
+#### Exceptions (Keep as Macros)
+
+**Do NOT convert**:
+- Platform detection macros (preprocessor-only)
+- Conditional compilation macros
+- Token-pasting macros (use `##`)
+- String-ification macros (use `#`)
+
+#### Implementation Strategy
+
+1. Search for constant macros
+2. For each candidate:
+   - Verify it's a simple constant (not token-pasting/stringification)
+   - Convert to `inline constexpr` with appropriate type
+   - Build and test
+3. Commit in logical groups (by file or subsystem)
+
+#### Risk Assessment
+
+**Risk**: VERY LOW
+- Simple mechanical transformation
+- Compile error if conversion is invalid (safe)
+- No runtime behavior change
+
+#### Estimated Time
+
+**2-3 hours**:
+- 1 hour: Identify candidates, convert parseutils.cpp
+- 1 hour: Convert library files (lstrlib, lmathlib, etc.)
+- 30 min: Build, test, commit
+
+---
+
+## Tier 2: Medium-Value, Medium-Risk
+
+These phases **require performance benchmarking** before acceptance.
+
+---
+
+### Phase 125: GC Macro Modernization
+
+**Value**: MEDIUM | **Risk**: MEDIUM | **Effort**: 3-4 hours + benchmarking
+
+#### Problem
+
+GC marking macros are hard to debug (can't step through) and lack type safety.
+
+#### Opportunity
+
+**File: `src/memory/lgc.cpp:83-98`**
+
+5-7 GC marking macros that could be inline functions.
+
+```cpp
+// CURRENT MACROS:
+#define gcvalarr(t,i)  \
+    ((*(t)->getArrayTag(i) & BIT_ISCOLLECTABLE) ? (t)->getArrayVal(i)->gc : nullptr)
+
+#define markvalue(g,o) { checkliveness(mainthread(g),o); \
+  if (valiswhite(o)) reallymarkobject(g,gcvalue(o)); }
+
+#define markkey(g, n) { if (keyiswhite(n)) reallymarkobject(g,n->getKeyGC()); }
+
+#define markobject(g,t) { if (iswhite(t)) reallymarkobject(g, obj2gco(t)); }
+
+#define markobjectN(g,t) { if (t) markobject(g,t); }
+```
+
+**Proposed inline functions:**
+
+```cpp
+inline GCObject* gcvalarr(Table* t, int i) noexcept {
+  return (*(t)->getArrayTag(i) & BIT_ISCOLLECTABLE) ? (t)->getArrayVal(i)->gc : nullptr;
+}
+
+inline void markvalue(global_State* g, const TValue* o) noexcept {
+  checkliveness(mainthread(g), o);
+  if (valiswhite(o)) reallymarkobject(g, gcvalue(o));
+}
+
+inline void markkey(global_State* g, Node* n) noexcept {
+  if (keyiswhite(n)) reallymarkobject(g, n->getKeyGC());
+}
+
+template<typename T>
+inline void markobject(global_State* g, T* t) noexcept {
+  if (iswhite(t)) reallymarkobject(g, obj2gco(t));
+}
+
+template<typename T>
+inline void markobjectN(global_State* g, T* t) noexcept {
+  if (t) markobject(g, t);
+}
+```
+
+**File: `src/memory/lgc.cpp:144, 160`** - List linking macros
+
+```cpp
+// CURRENT:
+#define linkgclist(o,p)    linkgclist_(obj2gco(o), &(o)->gclist, &(p))
+#define linkobjgclist(o,p) linkgclist_(obj2gco(o), getgclist(o), &(p))
+
+// PROPOSED: Templates
+template<typename T>
+inline void linkgclist(T* o, GCObject*& p) noexcept {
+  linkgclist_(obj2gco(o), &(o)->gclist, &p);
+}
+
+template<typename T>
+inline void linkobjgclist(T* o, GCObject*& p) noexcept {
+  linkgclist_(obj2gco(o), getgclist(o), &p);
+}
+```
+
+#### Benefits
+
+- ✅ **Better type safety**: Template type checking
+- ✅ **Debuggable**: Can step through function in debugger
+- ✅ **Better error messages**: Template errors are clearer than macro errors
+- ✅ **Maintainability**: Easier to understand and modify
+
+#### Risks
+
+**Risk**: MEDIUM
+- **GC is a hot path**: Macro vs function difference may matter
+- **Inlining**: Must verify compiler inlines these
+- **Performance**: Must benchmark to ensure no regression
+
+#### ⚠️ CRITICAL Benchmarking Requirement
+
+**MUST benchmark before and after**:
+
+```bash
+cd /home/user/lua_cpp/testes
+for i in 1 2 3 4 5; do \
+    ../build/lua all.lua 2>&1 | grep "total time:"; \
+done
+```
+
+**Acceptance criteria**:
+- Average time ≤4.33s (≤3% regression from 4.20s baseline)
+- If >4.33s: **REVERT IMMEDIATELY**
+
+**Verify inlining**:
+```bash
+# Check assembly to confirm inlining:
+objdump -d build/liblua.a | grep -A10 markvalue
+# Should show no call instruction - directly inlined code
+```
+
+#### Implementation Strategy
+
+1. **Convert one macro** (start with `gcvalarr` - simplest)
+2. **Benchmark**: Ensure no regression
+3. **If OK**: Convert 2-3 more macros
+4. **Benchmark again**
+5. **If regression detected**: Analyze which macro caused it, revert that one
+6. **Continue incrementally**
+
+#### Estimated Time
+
+**3-4 hours** + benchmarking:
+- 1 hour: Convert macros
+- 1 hour: Build, initial testing
+- 1-2 hours: Benchmarking and optimization if needed
+
+---
+
+### Phase 126: std::span Expansion
+
+**Value**: MEDIUM-HIGH | **Risk**: MEDIUM | **Effort**: 6-8 hours + benchmarking
+
+#### ⚠️ WARNING
+
+Phase 115 Part 3 (Table::getArraySpan()) showed **11.9% performance regression** (4.70s avg vs 4.20s baseline).
+
+**This phase requires extreme caution and continuous benchmarking**.
+
+#### Problem
+
+Some code still uses raw pointer + size pairs where std::span accessors already exist.
+
+#### Opportunity 1: Use Existing Span Accessors
+
+**File: `src/compiler/lparser.h:282-287`**
+
+Dyndata already has span accessors but many sites still use raw pointer getters:
+
+```cpp
+// Already exists:
+std::span<Vardesc> actvarGetSpan() noexcept {
+  return std::span(actvar_vec.data(), actvar_vec.size());
+}
+
+std::span<Labeldesc> getLabelSpan() noexcept {
+  return std::span(label.vec.data(), label.vec.size());
+}
+```
+
+**Search for conversion opportunities**:
+```bash
+grep -rn "actvarGetArr()" src/compiler/  # Find sites using raw pointer
+grep -rn "getArr()" src/compiler/        # Check Labellist usage
+```
+
+**Strategy**: Convert call sites from `getArr()` to `getSpan()` where:
+- No pointer arithmetic is performed
+- Bounds are known/checked
+- Not in hot paths (VM, GC critical sections)
+
+#### Opportunity 2: String Span Overloads
+
+**File: `src/objects/lstring.h:178-186`**
+
+String operations already have span overloads. Find call sites using `(const char*, size_t)` and convert:
+
+```cpp
+// Already exists:
+static unsigned computeHash(std::span<const char> str, unsigned seed);
+static TString* create(lua_State* L, std::span<const char> str);
+
+// Find call sites using old signature:
+grep -rn "computeHash.*const char\*" src/
+grep -rn "TString::create.*const char\*" src/
+```
+
+#### Opportunity 3: Buffer Operations
+
+**File: `src/auxiliary/lauxlib.h:216, 283`**
+
+Add span overloads for buffer operations:
+
+```cpp
+// CURRENT:
+LUALIB_API void (luaL_addlstring) (luaL_Buffer *B, const char *s, size_t l);
+
+// PROPOSED: Add overload (keep existing for C API)
+inline void luaL_addlstring(luaL_Buffer *B, std::span<const char> s) {
+  luaL_addlstring(B, s.data(), s.size());
+}
+```
+
+#### Critical Rules
+
+**DO NOT convert**:
+1. ❌ VM hot paths (`src/vm/lvm.cpp`)
+2. ❌ GC critical sections (`src/memory/lgc.cpp`, `src/memory/gc/*.cpp`)
+3. ❌ Code with pointer arithmetic
+4. ❌ Code that stores pointers long-term (span may outlive data)
+
+**DO convert**:
+1. ✅ Compiler/parser code (cold paths)
+2. ✅ Library functions (cold paths)
+3. ✅ Test infrastructure
+4. ✅ Debug/auxiliary code
+
+#### Implementation Strategy
+
+**Incremental with continuous benchmarking**:
+
+1. **Phase 126.1**: Non-VM compiler code (~10 sites)
+   - Convert Dyndata usage in parseutils.cpp
+   - **Benchmark** - if >4.33s, revert and stop
+
+2. **Phase 126.2**: Library functions (~10 sites)
+   - String operations in lstrlib.cpp
+   - **Benchmark** - if regression, revert and stop
+
+3. **Phase 126.3**: Auxiliary code (~5 sites)
+   - Buffer operations in lauxlib.cpp
+   - **Benchmark**
+
+**STOP IMMEDIATELY** if any sub-phase shows regression >3%
+
+#### Analysis from Phase 115
+
+Phase 115 Part 3 regression analysis showed:
+- **Problem**: `Table::getArraySpan()` in hot path (table access)
+- **Cause**: Possible bounds checking overhead or optimizer confusion
+- **Lesson**: Avoid span in performance-critical table/VM operations
+
+#### Benefits
+
+- ✅ **Bounds safety**: Debug builds catch out-of-bounds access
+- ✅ **Clearer intent**: Span signals "view over array"
+- ✅ **Type safety**: Size and pointer kept together
+
+#### Risks
+
+**Risk**: MEDIUM-HIGH
+- Performance regression possible (historical evidence from Phase 115)
+- Span may confuse optimizer in some contexts
+- Requires extensive benchmarking
+
+#### Estimated Time
+
+**6-8 hours** + extensive benchmarking:
+- 2 hours: Identify safe conversion sites
+- 2 hours: Convert Phase 126.1 (compiler code)
+- 1 hour: Benchmark and analyze
+- 2 hours: Convert Phase 126.2-3 (if Phase 126.1 passes)
+- 1-2 hours: Final benchmarking and analysis
+
+---
+
+## Tier 3: Defer
+
+These opportunities are **not recommended** due to high risk or low value.
+
+---
+
+### ⛔ Range-Based For Loops
+
+**Status**: Defer indefinitely
+**Reason**: Most loops need indices for other operations
+
+#### Analysis
+
+Most for loops in the codebase use the index variable for operations beyond iteration:
+
+```cpp
+// COMMON PATTERN - Cannot use range-based for
+for (int i = 0; i < n; i++) {
+    processItem(arr[i], i);      // Uses index i
+    if (condition)
+        adjustSize(i);            // Uses index i
+}
+
+// RARE PATTERN - Could use range-based for
+for (int i = 0; i < n; i++) {
+    processItem(arr[i]);          // Only uses arr[i], not i
+}
+```
+
+**Estimated candidates**: Only 5-10 loops (out of ~400 total)
+
+**Verdict**: Not worth the effort for so few conversions.
+
+---
+
+### ⛔ Loop Counter Conversion (int → size_t)
+
+**Status**: Defer indefinitely
+**Reason**: High risk, minimal benefit, conflicts with API design
+
+From TYPE_MODERNIZATION_ANALYSIS.md:
+
+**Scope**: ~400 for loops across codebase
+
+#### Problems
+
+1. **Signed/unsigned comparison warnings**:
+```cpp
+for (size_t i = 0; i < someInt; i++)  // ⚠️ Warning: signed/unsigned comparison
+```
+
+2. **Reverse iteration bugs**:
+```cpp
+for (size_t i = n - 1; i >= 0; i--)  // ❌ INFINITE LOOP! i is unsigned, never < 0
+```
+
+3. **Lua API uses int throughout**:
+```cpp
+// C API signature - cannot change
+LUA_API int lua_checkstack(lua_State *L, int n);
+
+// Internal code would need constant casting:
+size_t needed = calculateSize();
+lua_checkstack(L, static_cast<int>(needed));  // Cast at every API boundary
+```
+
+#### Analysis
+
+- Lua's `int`-based API is **intentional design** for backward compatibility
+- Most loops iterate <1000 times (overflow not a practical concern)
+- Would introduce 100+ signed/unsigned comparison warnings
+- Massive mechanical changes with limited benefit
+
+**Effort**: 20-30 hours
+**Risk**: MEDIUM (easy to introduce bugs)
+**Benefit**: NEGLIGIBLE (no practical overflow risk)
+
+**Verdict**: ⛔ **NOT RECOMMENDED**
+
+---
+
+### ⛔ Size Variable Conversion (int → size_t)
+
+**Status**: Defer indefinitely
+**Reason**: High underflow risk, API constraints
+
+From TYPE_MODERNIZATION_ANALYSIS.md:
+
+**Scope**: ~30 size variables across memory management code
+
+#### Critical Risk: Underflow
+
+```cpp
+// DANGER with size_t
+size_t a = 5;
+size_t b = 10;
+size_t diff = a - b;  // ❌ Wraps to SIZE_MAX (18446744073709551611)!
+
+if (diff > threshold) {
+    // Will execute even though diff should be -5
+}
+
+// vs. int (expected behavior)
+int a = 5;
+int b = 10;
+int diff = a - b;  // ✅ -5 (as expected)
+```
+
+#### Examples
+
+**File: `src/compiler/funcstate.cpp:415`**
+```cpp
+int numfreeregs = MAX_FSTACK - getFreeReg();
+// If getFreeReg() > MAX_FSTACK, this would wrap to huge positive with size_t!
+```
+
+**File: `src/objects/ltable.cpp`** (8 instances)
+```cpp
+int oldsize = oldasize + oldhsize;  // Delta calculations
+int delta = newsize - oldsize;       // Needs to handle negative
+```
+
+#### Analysis
+
+- Must audit **every subtraction expression** for underflow
+- Lua API uses `int` throughout (design constraint)
+- Overflow unlikely in practice (Lua limits table/array sizes)
+- **Subtraction is common** in size calculations (high risk)
+
+**Effort**: 6-10 hours
+**Risk**: **HIGH** (underflow bugs are subtle and dangerous)
+**Benefit**: LOW (overflow not practical concern)
+
+**Verdict**: ⛔ **DEFER - HIGH RISK, LOW VALUE**
+
+---
+
+### ⛔ Pointer-to-Reference Conversion
+
+**Status**: Defer unless null-dereference bugs found
+**Reason**: Very large refactoring for hypothetical benefits
+
+#### Opportunity
+
+Some functions take `Table* t` or `Proto* p` that are never null. Could use `Table& t` instead.
+
+```cpp
+// CURRENT:
+LUAI_FUNC void luaH_resize (lua_State *L, Table *t, unsigned nasize, unsigned nhsize);
+
+// PROPOSED:
+LUAI_FUNC void luaH_resize (lua_State *L, Table& t, unsigned nasize, unsigned nhsize);
+```
+
+#### Problems
+
+**Estimated count**: 20-30 functions
+**Call sites**: 100+ locations to update
+
+**Effort**: 8-12 hours
+**Risk**: MEDIUM (large refactoring, must verify all call sites)
+**Benefit**: Clearer contract (null not allowed)
+
+#### Analysis
+
+- Requires changing function signatures AND all call sites
+- Must verify that null is truly never passed
+- Current code already has good null checks
+- Benefit is documentation only (no functional improvement)
+
+**Verdict**: ⛔ **DEFER unless specific null-dereference bugs are found**
+
+---
+
+### ⛔ cast() Macro Elimination
+
+**Status**: Document as technical debt, defer indefinitely
+**Reason**: Hundreds of sites, very high risk
+
+#### The Problem
+
+**File: `src/memory/llimits.h:178`**
+```cpp
+#define cast(t, exp)    ((t)(exp))
+```
+
+Used extensively throughout codebase (hundreds of sites). Comment says:
+```cpp
+// (Lua code uses cast() for many purposes including const-casting)
+```
+
+#### Why It Exists
+
+Lua C code uses `cast()` for multiple purposes:
+- `static_cast` equivalent
+- `reinterpret_cast` equivalent
+- `const_cast` equivalent
+- Arithmetic type conversions
+
+#### Required Work
+
+Converting would require:
+1. **Audit all cast() uses** (hundreds of sites)
+2. **Classify each use**: static/reinterpret/const/arithmetic
+3. **Convert to appropriate C++ cast**
+4. **Test extensively** (very error-prone)
+
+**Effort**: 40-60 hours
+**Risk**: VERY HIGH
+**Benefit**: Type safety at cast sites
+
+#### Analysis
+
+This is a **massive refactoring** that should only be undertaken if:
+- Significant cast-related bugs are found
+- Dedicated multi-week effort is available
+- Extensive testing infrastructure is ready
+
+**Verdict**: ⛔ **Document as technical debt, defer indefinitely**
+
+---
+
+## Status Update: Boolean Conversions
+
+TYPE_MODERNIZATION_ANALYSIS.md listed 8 functions as candidates for `int → bool` conversion. Investigation shows:
+
+### ✅ Already Converted to bool (5 functions)
+
+1. `iscleared()` - src/memory/gc/gc_weak.cpp:52 ✅
+2. `hashkeyisempty()` - src/objects/ltable.cpp:1125 ✅
+3. `rawfinishnodeset()` - src/objects/ltable.cpp:1177 ✅
+4. `isneg()` - src/objects/lobject.cpp:207 ✅
+5. `checkbuffer()` - src/serialization/lzio.cpp:46 ✅
+
+### ❌ Return Meaningful int Values (3 functions)
+
+These are **NOT boolean functions** - they return status codes or indices:
+
+6. **`finishnodeset()`** - src/objects/ltable.cpp:1167
+   ```cpp
+   static int finishnodeset (Table *t, TValue *slot, TValue *val) {
+     if (!ttisnil(slot)) {
+       *slot = *val;
+       return HOK;  // Success code
+     }
+     else
+       return retpsetcode(t, slot);  // Returns encoded node position or HNOTFOUND
+   }
+   ```
+   **Returns**: `HOK` (success) or node encoding from `retpsetcode()`
+
+7. **`check_capture()`** - src/libraries/lstrlib.cpp:382
+   ```cpp
+   static int check_capture (MatchState *ms, int l) {
+     l -= '1';
+     if (l_unlikely(l < 0 || l >= ms->level ||
+                    ms->capture[l].len == CAP_UNFINISHED))
+       return luaL_error(ms->L, "invalid capture index %%%d", l + 1);
+     return l;  // Returns capture index
+   }
+   ```
+   **Returns**: Capture index (0-N) or error code
+
+8. **`test2()`** - src/libraries/liolib.cpp:456
+   ```cpp
+   static int test2 (RN *rn, const char *set) {
+     if (rn->c == set[0] || rn->c == set[1])
+       return nextc(rn);  // Returns result of nextc()
+     else return 0;
+   }
+   ```
+   **Returns**: `nextc()` result (character code) or 0
+
+### Conclusion
+
+**Boolean conversion work is already complete!** ✅
+
+The remaining 3 functions are correctly returning `int` because they return meaningful numeric values, not just true/false.
+
+**No action needed for this category.**
+
+---
+
+## Recommended Execution Plan
+
+### Immediate Next Steps (High Confidence)
+
+#### **Phase 122: constexpr Expansion**
+- **Priority**: TOP
+- **Effort**: 2-3 hours
+- **Risk**: VERY LOW
+- **Files**:
+  - `src/core/lstate.h` (20+ getters)
+  - `src/compiler/lparser.h` (15+ getters)
+  - `src/objects/lproto.h` (10+ getters)
+  - `src/objects/ltable.h` (5+ getters)
+  - `src/objects/lobject_core.h` (5+ getters)
+- **Target**: 50+ simple getters
+- **Acceptance**: Clean compile, all tests pass
+
+#### **Phase 123: [[nodiscard]] Safety**
+- **Priority**: HIGH
+- **Effort**: 4-6 hours
+- **Risk**: MEDIUM (may reveal ignored returns)
+- **Sub-phases**:
+  1. **Phase 123.1**: Memory allocations (7 functions) - CRITICAL
+  2. **Phase 123.2**: Type conversions (8 functions) - IMPORTANT
+  3. **Phase 123.3**: Table/stack operations (20+ functions) - MEDIUM
+- **Acceptance**: Clean compile (after fixing any warnings), all tests pass
+- **Note**: Warnings about ignored returns are GOOD - they expose potential bugs
+
+#### **Phase 124: Constant Macros to constexpr**
+- **Priority**: MEDIUM
+- **Effort**: 2-3 hours
+- **Risk**: VERY LOW
+- **Files**:
+  - `src/compiler/parseutils.cpp` (3 macros)
+  - `src/libraries/lstrlib.cpp` (6 macros)
+  - Other library files (6+ macros)
+- **Target**: 15-20 constant macros
+- **Acceptance**: Clean compile, all tests pass
+
+### Total Tier 1 Effort
+
+**8-12 hours** of high-confidence work with excellent expected outcomes.
+
+### Optional (Requires Benchmarking)
+
+#### **Phase 125: GC Macro Modernization** (if time permits)
+- **Effort**: 3-4 hours + benchmarking
+- **Risk**: MEDIUM
+- **Acceptance**:
+  - Clean compile, all tests pass
+  - **Performance ≤4.33s** (≤3% regression)
+  - If >4.33s: **REVERT IMMEDIATELY**
+
+#### **Phase 126: std::span Expansion** (CAUTION)
+- **Effort**: 6-8 hours + extensive benchmarking
+- **Risk**: MEDIUM-HIGH (Phase 115 showed 11.9% regression)
+- **Approach**: Incremental sub-phases with continuous benchmarking
+- **Acceptance**: Performance ≤4.33s after EACH sub-phase
+- **If ANY regression >3%: STOP IMMEDIATELY**
+
+---
+
+## Performance Requirements
+
+### Current Performance Status
+
+**Current**: ~4.26s avg ✅
+**Target**: ≤4.33s (≤3% regression from 4.20s baseline)
+**Baseline**: 4.20s (November 2025, current hardware)
+
+**Status**: EXCELLENT - 1.4% above baseline, better than target!
+
+### Benchmark Procedure
+
+**After EVERY phase**, run the standard benchmark:
+
+```bash
+cd /home/user/lua_cpp/testes
+for i in 1 2 3 4 5; do \
+    ../build/lua all.lua 2>&1 | grep "total time:"; \
+done
+```
+
+**Calculate average** and compare to target.
+
+### Acceptance Criteria
+
+**Tier 1 phases (122-124)**:
+- Expected: No performance change (non-hot path changes)
+- Acceptance: Any result (these are zero-cost abstractions)
+- Action: Document performance, proceed
+
+**Tier 2 phases (125-126)**:
+- **MUST** maintain ≤4.33s average
+- If >4.33s: **REVERT IMMEDIATELY**
+- If 4.20s-4.33s: Document and proceed
+- If <4.20s: Celebrate improvement! 🎉
+
+### Build Configuration
+
+Always use **Release build** for benchmarking:
+
+```bash
+cmake -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+**Debug builds are NOT representative** of performance.
+
+---
+
+## Summary
+
+### What We've Achieved (Phases 1-121)
+
+The Lua C++ conversion project has achieved **exceptional modernization**:
+
+1. ✅ **19/19 classes** with full encapsulation (100%)
+2. ✅ **~500 macros converted** (~99% complete)
+3. ✅ **100% modern C++ casts** (Phases 102-111)
+4. ✅ **All enums are enum classes** (Phases 96-100)
+5. ✅ **nullptr throughout** (Phase 114)
+6. ✅ **std::array** for fixed arrays (Phase 119)
+7. ✅ **CRTP inheritance** for all GC types
+8. ✅ **C++ exceptions** replacing setjmp/longjmp
+9. ✅ **Modern CMake** with sanitizers, LTO, CTest
+10. ✅ **96.1% code coverage**
+11. ✅ **Zero warnings**, all tests passing
+12. ✅ **Performance**: 4.26s avg (better than 4.33s target!)
+
+### Remaining Opportunities (Phases 122+)
+
+**High-Value, Low-Risk** (8-12 hours):
+- ✅ Phase 122: constexpr expansion (50+ getters)
+- ✅ Phase 123: [[nodiscard]] annotations (30-40 functions)
+- ✅ Phase 124: Constant macros to constexpr (15-20 macros)
+
+**Medium-Value, Medium-Risk** (benchmark required):
+- ⚠️ Phase 125: GC macro modernization (5-7 macros)
+- ⚠️ Phase 126: std::span expansion (20-30 sites)
+
+**Low-Value or High-Risk** (defer):
+- ⛔ Range-based for loops
+- ⛔ Loop counter conversion
+- ⛔ Size variable conversion
+- ⛔ Pointer-to-reference conversion
+- ⛔ cast() macro elimination
+
+### Key Insight
+
+**Not all C legacy is bad.** Lua's `int`-based API design is:
+- Intentional for backward compatibility
+- Practical for the problem domain
+- Well-tested over decades
+
+Modern C++ doesn't mean blindly converting every `int` to `size_t` or every macro to a function. It means making **pragmatic improvements** where they add clear value.
+
+### Final Recommendation
+
+**Execute Phases 122-124** (Tier 1) with high confidence. These are low-risk, high-value improvements that align perfectly with the project's performance requirements.
+
+**Phases 125-126** (Tier 2) are optional and should only be attempted if:
+- Performance benchmarking shows no regression
+- Time is available for careful analysis
+- Risk tolerance is appropriate
+
+The codebase is already in **excellent shape**. Further modernization should be **highly selective** and **performance-validated**.
+
+---
+
+**Document Version**: 1.0
+**Last Updated**: November 22, 2025
+**Status**: Phase 121 Complete, Phases 122+ Planned