feat: lift the pure subset of foreign values into IR primops (#178) - #210

Closes #178. Builds on the foreign parser (#173) and case-of-known-constructor (#177); unblocks the dictionary-method inlining of #180.

What

Polymorphic hot code bottoms out in opaque curried foreigns (intAdd, ordIntImpl, refEq, boolConj) that the IR optimizer cannot see through, because to the IR a foreign body is text. This lifts the pure return-tree subset of such a body, taken from the actual fork source the foreign parser (#173) already gives us, into IR primops the existing rewrites can specialize.

• IR primops (IR.Types): PrimBinOp ann PrimOp a b and PrimNot ann a, with a PrimOp enum of the twelve binary operators. Each node is defined as the matching Lua operator, so lowering is the identity and lifting its inverse (Note [IR primops]). Equality stays the existing Eq node; the lifter maps == onto it and ~= onto not (a == b).
• Lowering (Lua.fromIR): each primop lowers to the same-named Lua BinOp / UnOp.
• Constant folding (IR.Optimizer): fold primops over literal operands in Lua 5.1 semantics (Note [Folding primops follows Lua 5.1]). Integer +/-/* fold with a ±2^53 exactness guard, floats only to a finite result, integer modulo copies the divisor-signed a - floor(a/b)*b, concat is string-with-string, comparisons fold on two numbers, and and/or/not fold including the short-circuit identities.
• Boolean-if simplification (IR.Optimizer): if p then True else False becomes p, if p then False else True becomes not p, if not p then a else b becomes if p then b else a (drop the negation, swap the branches), and not (not e) becomes e. Every Ord comparison and /= decays to the if … then False else True shape, so once the comparison bodies lift this is the dominant residual; the not p rewrite is only expressible because the primops above give the IR a PrimNot. The Lua backend then emits not (a == b) as a ~= b, the form luacheck expects.
• The lifter (Lua.ForeignLift): translate the liftable subset of an export's parsed Lua AST. Curried single-parameter lambdas become nested Abs, if/elseif/else return trees become IfThenElse, operators become primops, and a reference resolves either to a parameter or to an inlined header local (which is how ordIntImpl = (unsafeCoerceImpl) and the refEq aliases lift). Loops, mutation, varargs, multi-parameter functions, table constructors, and calls leave the export opaque.
• The allowlist: the arithmetic/comparison/boolean/concat core (intAdd/intMul/intSub, ordIntImpl/ordCharImpl, boolConj/boolDisj/boolNot, the refEq family, concatString). It is a hard contract: an allowlisted export that fails to lift, because a fork changed its shape, is a compile error rather than a silent performance cliff. An export not on the list stays opaque even when it would lift.
• Wiring: Backend.compileModules runs the lifter before the optimizer, and the golden harness's compileCorefn does the same, so the .ir goldens go through the real pipeline.

Design points

Lifted exports become ordinary bindings, not foreigns. The first cut replaced the accessor in place inside uberModuleForeigns, and it miscompiled. DCE's reachability graph only understands the ForeignImport / ObjectProp shapes among the foreigns, so a lifted lambda has no vertex there, gets read as unreachable, and is dropped while every reference to it survives dangling (attempt to call field 'Data_Ring_intSub' (a nil value)). Moving the lifted export into uberModuleBindings fixes it structurally: DCE handles it as a normal binding, and once the accessor is gone it prunes the export's name from the module's ForeignImport, since nothing reads it off the foreign import anymore, so the source row drops out of the emitted FFI. When every export of a module lifts, its ForeignImport disappears: see the Fibonacci diff, where the Data_Semiring_foreign / Data_Ring_foreign tables are gone and intAdd is a native +.

Folding tracks Lua 5.1. The target is all-doubles, so the rules watch it: integer folds bail beyond ±2^53 (a folded literal has to reparse to the value the runtime computes), float folds stop at a finite result (Lua has no inf/nan numeric literal), modulo copies the formula whose sign follows the divisor, and concat is string-with-string only (Lua's number-to-string on concat is build-dependent). Comparisons fold on two numbers; strings and chars are left alone, since Lua orders strings by bytes while the IR literal is semantic Text.

Semantics from the source, not a registry. The original plan was a hand-written qualified-name to IR registry (the purs-backend-es approach). Deriving the semantics from the parsed fork source instead makes registry drift against the package set impossible by construction. That is the payoff of Lua's tiny grammar, and the reason the allowlist can be a hard contract instead of best-effort.

Verification

• Unit tests for every folding rule (the range guard, the modulo sign, finite-float, string concat, numeric comparisons, boolean short-circuit) and its declines, for the boolean-if rules and the ~= peephole, and for the lifter (each liftable shape, each declined shape, allowlist membership).
• The shared IR generator now emits PrimBinOp / PrimNot, so the optimizer's well-scopedness, GUC, free-reference, and idempotence properties fuzz constant folding over primops. Unlike Fold ReflectCtor and DataArgumentByIndex over known constructor applications (case-of-known-constructor) #177, widening the generator is in scope here, since folding correctness is what benefits from the fuzz.
• A runnable Golden.Primops module exercises lifted arithmetic, comparison, equality, concat, and booleans, with a hand-verified eval oracle.
• Full suite green (686 examples), hlint clean, warning-free build. Every eval oracle is unchanged across the golden churn, which is the semantic safety net: the runtime output of every runnable golden is byte-identical, so both the lifting and the boolean-if simplification are behavior-preserving. The boolean-if rules also shrink the output, e.g. the tailRecM loop guard collapses from a nested IIFE plus a boolean round-trip to a single swapped-branch if.

Notes for reviewers

Scope vs the 42x number. #178 gives you the primops and the lifter, and direct arithmetic collapses fully (the Fibonacci golden is native + and subtraction now, no foreign dispatch). The general greaterThanOrEq(ordInt)(a)(b) to not (a < b) collapse also needs dictionary-method inlining (#180), which this unblocks: the ordIntImpl body is already lifted into primops inside ordInt.compare, but the Data_Ord_compare(dict) method dispatch stands until #180 inlines it.

Twice-used primops can surface as a shared worker. A lifted primop used at two or more saturated sites can come out as an uncurried worker instead of an inline operator (Fibonacci's sub$w(v, k) for n - 1 and n - 2). The chain: purs shares sub ringInt as a top-level binding when - is used more than once, reduceObjectProp strips the Just Always off the lifted lambda as it resolves through the dict projection (by design, so foreign accessors don't over-inline), and uncurry then splits the surviving curried binding into worker and wrapper. Correct, and still far cheaper than the old foreign dispatch of a table index plus two curried calls. Inlining trivial primop-bodied bindings regardless of use count would close the gap; it is a reasonable low-priority follow-up, filed as #211 and out of scope here.