feat(codegen): renumber compiler-minted locals at emission - #308

Closes #306.

Problem

Every fresh name the compiler mints carries an index drawn from a monotone supply threaded through the whole pipeline: suffix-minted names like x$223 (uniquification, inline-paste freshening) and prefix-minted names like $cse1413 or the $sel/$a dispatch locals of codegen, all mangled $ → _S_ on the way into the Lua AST. That index is pipeline history, not artifact structure — any upstream change that shifts how much supply earlier code consumes renames every later binder, so semantically identity changes churn golden files in nothing but indices (#304 review: of 26 moved modules, several changed only like v_S_1437 → v_S_1440).

The new differential spec demonstrates the leak at the level it manifests, before the fix (test/Language/PureScript/Backend/Lua/Renumber/Spec.hs, compiling the same IR twice with a burned supply offset of 100):

expected: "return {
            value = (function()
              local v_S_0 = 1
              local x_S_2
              x_S_2 = v_S_0
              return x_S_2
            end)()
          }"
 but got: "return {
            value = (function()
              local v_S_100 = 1
              local x_S_102
              x_S_102 = v_S_100
              return x_S_102
            end)()
          }"

Fix

A late Chunk → Chunk pass, Language.PureScript.Backend.Lua.Renumber, wired at the tail of optimizeChunk (the shared seam both Backend.compileModules and the golden harness print through), after every name-minting Lua-level transform and immediately before the printer. The supply must stay global — the pipeline's unique-binders invariant depends on it — so nothing changes in the IR; only the emitted spelling is normalized.

The pass renumbers every supply-drawn digit run occurring in a local binder in first-occurrence order — a fresh index per base name, counted from 0 — and rewrites the binder's references scope-consistently. A digit run is supply-drawn in exactly two shapes, mirroring the two minting grammars (see Note [Supply-drawn digit runs] in the new module): a whole _S_-delimited segment (x_S_223, and the same run embedded mid-name in a derived dispatcher b_S_5_S_loop), or the run terminating the tag of a _S_-prefixed name (_S_cse1413, _S_a1). Digit runs anywhere else are spelling, not supply: add3 keeps its 3, SpecConstr's positional …_S_sc1Tuple keeps its 1.

Two design points worth review attention:

• Derived names renumber in step with the binder they embed. Loopification derives a dispatcher's name from its leader member (b$5 → b$5$loop), so a suffix-only rule would stabilize the member yet leave the dispatcher churning. Assignments are keyed by (piece-prefix, original run), so b_S_5 and b_S_5_S_loop both map through the same entry — the second differential test pins exactly this on a mutually tail-recursive group.
• The rewrite is capture-free alpha-renaming by construction. Binders rename together with exactly their in-scope references (the walk models Lua scoping, including the repeat-until condition seeing body locals); an unbound reference is a global — an FFI file's stdlib or host-API read — and is never rewritten, and allocation skips any index whose spelling occurs free in the chunk, so a renamed binder cannot capture such a global either.

Sample of the resulting normalization, quoted from the accepted Golden.NativeLoopsGuard.Test/golden.lua:

-      local bind_S_1433 = (Effect_monadEffect.Bind1()).bind
-      return function(f_S_1434)
-        return function(a_S_1435)
-          return bind_S_1433(f_S_1434)(function(fPrime_S_1436)
-            return bind_S_1433(a_S_1435)(function(aPrime_S_1437)
+      local bind_S_0 = (Effect_monadEffect.Bind1()).bind
+      return function(f_S_1)
+        return function(a_S_1)
+          return bind_S_0(f_S_1)(function(fPrime_S_0)
+            return bind_S_0(a_S_1)(function(aPrime_S_0)

Verification

• Differential (red before the pass, green after): compiling the same IR with supply indices offset by 100 must emit byte-identical text — one test for plain suffix-minted locals, one for a local recursive group whose lowering derives a dispatcher name and mints $sel/$a locals.
• Unit fixtures (parse → renumber → print): first-occurrence allocation per base, prefix-minted names, dispatcher/member pairing, sibling-scope consistency, repeat-until scoping, the free-spelling skip, and the untouched classes (unsuffixed names, positional digits, field names, table keys, global references).
• Properties (Hedgehog, 300 tests each, seed-stressed 12 runs): the pass is idempotent on chunks generated over supply-minted name pools, and is the identity on chunks without supply-drawn names.
• Corpus: the one-time whole-corpus renumbering touches only golden.lua files (52 of them); every golden.ir and every hand-verified eval/golden.txt oracle is byte-identical and green, which pins the renaming as alpha-equivalence on the corpus. Luacheck stays clean; cabal test all green on the accepted state.

Notes

• The insertion/deletion counts of the golden diff differ slightly (1485/−1512) because shorter names let the pretty-printer re-join previously wrapped lines; the change is still purely name-driven.
• A hand-written FFI local that happens to spell a minted shape (x_S_1 is a legal Lua and PureScript identifier) is renumbered too — consistently with its references, so semantics are unchanged; only the spelling in the output moves.
• The issue names a possible follow-up (dropping the suffix entirely where the base name is unambiguous in scope); that needs real shadowing analysis and stays out of scope here.