jz 0.4.0 → 0.5.0

package/src/ir.js

@@ -21,7 +21,19 @@
  */
 
 import { ctx, err, inc, PTR, LAYOUT } from './ctx.js'
-import { T, VAL, valTypeOf, lookupValType, repOf, repOfGlobal } from './analyze.js'
+import { T, VAL, valTypeOf, lookupValType, repOf, repOfGlobal, objLiteralSchemaId } from './analyze.js'
+
+// === Numeric range ===
+
+/** Signed-32-bit range. Used everywhere a number value must round-trip through
+ *  wasm `i32` (literal constants, default-arg folding, exprType inference). */
+export const I32_MIN = -2147483648
+export const I32_MAX = 2147483647
+
+/** True when `v` is a finite integer that fits in i32 *and* isn't -0 (which i32
+ *  cannot represent). Callers that don't care about -0 can compare against
+ *  I32_MIN/I32_MAX directly. */
+export const isI32 = (v) => Number.isInteger(v) && v >= I32_MIN && v <= I32_MAX && !Object.is(v, -0)
 
 // === Type helpers ===
 
@@ -52,8 +64,17 @@ export const asF64 = n => {
   if (n == null) err(`compiler internal: expected emitted IR value in ${ctx.func.current?.name || '<module>'}, got empty value`)
   if (n.ptrKind != null) return boxPtrIR(n, valKindToPtr(n.ptrKind), n.ptrAux || 0)
   if (n.type === 'f64') return n
-  if (n.type === 'i64') return typed(['f64.reinterpret_i64', n], 'f64')
-  if (n[0] === 'i32.const' && typeof n[1] === 'number') return typed(['f64.const', n[1]], 'f64')
+  if (n.type === 'i64') {
+    // Cancel the reinterpret round-trip at construction: reinterpret is bit-preserving
+    // both ways, so f64.reinterpret_i64(i64.reinterpret_f64(X)) === X. Folding here keeps
+    // the pair out of the IR entirely (smaller tree for every downstream pass) instead of
+    // letting fusedRewrite untangle it post-emit.
+    if (Array.isArray(n) && n[0] === 'i64.reinterpret_f64' && Array.isArray(n[1])) return typed(n[1], 'f64')
+    return typed(['f64.reinterpret_i64', n], 'f64')
+  }
+  // A `.unsigned` const carries its uint32 value as a signed i32 bit pattern, so
+  // widen via `>>> 0` (e.g. -1 → 4294967295); a plain const copies through verbatim.
+  if (n[0] === 'i32.const' && typeof n[1] === 'number') return typed(['f64.const', n.unsigned ? n[1] >>> 0 : n[1]], 'f64')
   return typed([n.unsigned ? 'f64.convert_i32_u' : 'f64.convert_i32_s', n], 'f64')
 }
 
@@ -72,8 +93,13 @@ export const asI32 = n => {
 /** Coerce node to i32 offset for a ptr-narrowed return / store. Same-kind unboxed
  *  ptr passes through; otherwise extract low 32 bits from the NaN-boxed f64
  *  (NOT trunc — that would convert numerically). */
-export const asPtrOffset = (n, ptrKind) =>
-  n.ptrKind === ptrKind ? n : typed(['i32.wrap_i64', ['i64.reinterpret_f64', asF64(n)]], 'i32')
+export const asPtrOffset = (n, ptrKind) => {
+  if (n.ptrKind === ptrKind) return n
+  const f = asF64(n)
+  // Peel the inner reinterpret round-trip before wrapping: i64.reinterpret_f64(f64.reinterpret_i64(Y)) === Y.
+  const bits = Array.isArray(f) && f[0] === 'f64.reinterpret_i64' && Array.isArray(f[1]) ? f[1] : ['i64.reinterpret_f64', f]
+  return typed(['i32.wrap_i64', bits], 'i32')
+}
 
 /** Coerce emitted IR to a target WASM param type ('i32' | 'i64' | 'f64'). */
 export const asParamType = (n, t) => t === 'i32' ? asI32(n) : t === 'i64' ? asI64(n) : asF64(n)
@@ -116,30 +142,71 @@ export const toI32 = n => {
 }
 
 /** Extract i64 from BigInt-as-f64. */
-export const asI64 = n => typed(['i64.reinterpret_f64', asF64(n)], 'i64')
+export const asI64 = n => {
+  const f = asF64(n)
+  // Cancel reinterpret round-trip: i64.reinterpret_f64(f64.reinterpret_i64(Y)) === Y.
+  if (Array.isArray(f) && f[0] === 'f64.reinterpret_i64' && Array.isArray(f[1])) return typed(f[1], 'i64')
+  return typed(['i64.reinterpret_f64', f], 'i64')
+}
 
 /** Wrap i64 result back to BigInt-as-f64. */
-export const fromI64 = n => typed(['f64.reinterpret_i64', n], 'f64')
+export const fromI64 = n => {
+  // Cancel reinterpret round-trip: f64.reinterpret_i64(i64.reinterpret_f64(X)) === X.
+  if (Array.isArray(n) && n[0] === 'i64.reinterpret_f64' && Array.isArray(n[1])) return typed(n[1], 'f64')
+  return typed(['f64.reinterpret_i64', n], 'f64')
+}
 
 // === Nullish sentinels ===
 
 /** Reserved atoms (PTR.ATOM tag, offset=0).
  *    aux=1 → null      (NULL_NAN)
  *    aux=2 → undefined (UNDEF_NAN)
+ *    aux=4 → false     (FALSE_NAN)
+ *    aux=5 → true      (TRUE_NAN)
  *  See module/symbol.js for the broader reserved-atom-id scheme.
  *  Distinct from 0, NaN, and all pointers. Triggers default params.
  *  At the JS boundary, null and undefined preserve their identity for interop. */
 export const NULL_NAN = '0x' + (LAYOUT.NAN_PREFIX_BITS | (1n << BigInt(LAYOUT.AUX_SHIFT))).toString(16).toUpperCase().padStart(16, '0')
 export const UNDEF_NAN = '0x' + (LAYOUT.NAN_PREFIX_BITS | (2n << BigInt(LAYOUT.AUX_SHIFT))).toString(16).toUpperCase().padStart(16, '0')
+/** Boxed-boolean carrier. `false`/`true` are reserved atoms — materialized only
+ *  where boolean identity is observed (typeof/String/JSON/host boundary); in
+ *  branch/arithmetic position booleans stay raw i32/f64 0/1. The atomId encodes
+ *  the truth value in its low bit (4=false, 5=true), so `aux & 1` recovers 0/1
+ *  and `4 | bit` boxes it — see boolBoxIR / unboxBoolIR. */
+export const BOOL_ATOM_BASE = 4
+export const FALSE_NAN = '0x' + (LAYOUT.NAN_PREFIX_BITS | (4n << BigInt(LAYOUT.AUX_SHIFT))).toString(16).toUpperCase().padStart(16, '0')
+export const TRUE_NAN = '0x' + (LAYOUT.NAN_PREFIX_BITS | (5n << BigInt(LAYOUT.AUX_SHIFT))).toString(16).toUpperCase().padStart(16, '0')
 /** WAT-template-ready sentinel expressions for use in stdlib template strings.
  *  `f64.const nan:0xHEX` is 3 bytes shorter than `f64.reinterpret_i64 (i64.const ...)`. */
 export const NULL_WAT = `(f64.const nan:${NULL_NAN})`
 export const UNDEF_WAT = `(f64.const nan:${UNDEF_NAN})`
 export const NULL_IR = ['f64.const', `nan:${NULL_NAN}`]
 export const UNDEF_IR = ['f64.const', `nan:${UNDEF_NAN}`]
+export const FALSE_IR = ['f64.const', `nan:${FALSE_NAN}`]
+export const TRUE_IR = ['f64.const', `nan:${TRUE_NAN}`]
 export const nullExpr = () => typed(NULL_IR, 'f64')
 export const undefExpr = () => typed(UNDEF_IR.slice(), 'f64')
 
+/** Materialize the boxed-boolean carrier from a 0/1-valued expression. The atom
+ *  is `BOOL_ATOM_BASE | bit`, so boxing is one `i32.or` then an ATOM mkptr; when
+ *  the input folds to a constant 0/1 we emit the `f64.const nan:` literal directly.
+ *  Used only at observation/escape sites — never in branch or arithmetic position. */
+export function boolBoxIR(e) {
+  const i = truthyIR(e)
+  if (Array.isArray(i) && i[0] === 'i32.const') return typed((i[1] ? TRUE_IR : FALSE_IR).slice(), 'f64')
+  return mkPtrIR(['i32.const', PTR.ATOM], ['i32.or', ['i32.const', BOOL_ATOM_BASE], i], ['i32.const', 0])
+}
+
+/** Recover the 0/1 i32 value of a known boxed-boolean f64 expression: `aux & 1`. */
+export function unboxBoolIR(f64expr) {
+  if (Array.isArray(f64expr) && f64expr[0] === 'f64.const') {
+    const bits = typeof f64expr[1] === 'string' ? f64expr[1].replace(/^nan:/, '') : null
+    if (bits === TRUE_NAN) return typed(['i32.const', 1], 'i32')
+    if (bits === FALSE_NAN) return typed(['i32.const', 0], 'i32')
+  }
+  return typed(['i32.and', ['i32.wrap_i64', ['i64.shr_u', ['i64.reinterpret_f64', f64expr], ['i64.const', String(LAYOUT.AUX_SHIFT)]]], ['i32.const', 1]], 'i32')
+}
+
 // === Constants ===
 
 /** Max arity of inline closure slots. Closures are compiled with signature
@@ -149,6 +216,7 @@ export const undefExpr = () => typed(UNDEF_IR.slice(), 'f64')
 export const MAX_CLOSURE_ARITY = 8
 
 /** Matches WASM instructions that require a memory section. */
+// FIXME: can be simpler regex, just test second part - load vs store vs grow vs size vs memory
 export const MEM_OPS = /\b(i32\.load|i32\.store|f64\.load|f64\.store|f32\.load|f32\.store|i64\.load|i64\.store|memory\.size|memory\.grow|i32\.load8|i32\.load16|i32\.store8|i32\.store16)\b/
 
 export const WASM_OPS = new Set(['block','loop','if','then','else','br','br_if','call','call_indirect','return','return_call','throw','try_table','catch','nop','drop','unreachable','select','result','mut','param','func','module','memory','table','elem','data','type','import','export','local','global','ref'])
@@ -295,14 +363,14 @@ export const isPostfix = (a, op, b) => Array.isArray(a) && a[0] === op && Array.
 
 /** Emit a numeric constant with correct i32/f64 typing.
  *  `-0` is f64-only (i32 has no signed zero) — preserve the sign by emitting f64. */
-export const emitNum = v => Number.isInteger(v) && v >= -2147483648 && v <= 2147483647 && !Object.is(v, -0)
+export const emitNum = v => isI32(v)
   ? typed(['i32.const', v], 'i32') : typed(['f64.const', v], 'f64')
 
 // === Temp locals ===
 
 /** Allocate a temp local, returns name without $. Optional tag aids WAT readability.
- *  Skips names already registered (by analyzeLocals from prepare-generated names)
- *  to avoid collisions that would silently override the pre-analyzed type. */
+ *  Skips names already registered (by analyzeBody().locals from prepare-generated
+ *  names) to avoid collisions that would silently override the pre-analyzed type. */
 export function temp(tag = '') {
   let name
   do { name = `${T}${tag}${ctx.func.uniq++}` } while (ctx.func.locals.has(name))
@@ -339,12 +407,58 @@ export const f64rem = (a, b) => {
     ['f64.sub', ga, ['f64.mul', ['f64.trunc', ['f64.div', ga, gb]], gb]]], 'f64')
 }
 
+/** Resolve the slot index of a ToPrimitive method (`valueOf`/`toString`) on an
+ *  OBJECT operand — from a schema-bound variable or an inline object literal.
+ *  Returns -1 when the method is absent. */
+function primMethodIdx(node, name) {
+  if (typeof node === 'string') return ctx.schema.find(node, name)
+  const sid = objLiteralSchemaId(node)
+  const props = sid != null ? ctx.schema.list[sid] : null
+  return props ? props.indexOf(name) : -1
+}
+
+/** Emit the ES `OrdinaryToPrimitive` method-fallback chain for an OBJECT operand,
+ *  returning an i64 IR node holding the resulting primitive — or null when the
+ *  object exposes none of the hinted methods. `order` is the method-try order
+ *  (number hint → [valueOf,toString]; string hint → [toString,valueOf]). Each
+ *  present method is called in turn: a primitive result short-circuits out, a
+ *  non-primitive (object) result falls through to the next method, and if every
+ *  method yields a non-primitive a TypeError is thrown — the spec algorithm. */
+function toPrimitiveChain(node, v, order) {
+  const present = order.map(name => primMethodIdx(node, name)).filter(i => i >= 0)
+  if (!present.length) return null
+  ctx.runtime.throws = true
+  inc('__is_object')
+  const blk = `$tp${ctx.func.uniq++}`
+  const prim = tempI64('prim')
+  const optr = tempI32('op')
+  // Resolve the object's data pointer once — `v` may carry side effects and is
+  // referenced once per method slot below.
+  const body = [['result', 'i64'],
+    ['local.set', `$${optr}`, ptrOffsetIR(v, VAL.OBJECT)]]
+  for (const idx of present) {
+    const method = typed(ctx.abi.object.ops.load(['local.get', `$${optr}`], idx), 'f64')
+    body.push(
+      ['local.set', `$${prim}`, asI64(ctx.closure.call(method, []))],
+      ['br_if', blk, ['local.get', `$${prim}`],
+        ['i32.eqz', ['call', '$__is_object', ['local.get', `$${prim}`]]]])
+  }
+  // Every method returned a non-primitive — `Cannot convert object to primitive`.
+  body.push(['throw', '$__jz_err', ['f64.const', 0]])
+  return typed(['block', blk, ...body], 'i64')
+}
+
 /** Coerce an emitted IR value to a plain f64 Number per JS `ToNumber`.
  *  Skips coercion when static type proves the value is already numeric
- *  (i32 node, compile-time literal, known VAL.NUMBER/VAL.BIGINT) or when
- *  __to_num is not available (no string module loaded → no strings possible). */
+ *  (i32 node, compile-time literal, known VAL.NUMBER/VAL.BIGINT). When the full
+ *  string-parsing `__to_num` isn't loaded (no string module → no strings can
+ *  exist) nullish *literals* still fold statically (null→+0, undefined→NaN);
+ *  non-literal values pass through uncoerced. */
 export function toNumF64(node, v) {
-  if (v.type === 'i32' || isLit(v)) return asF64(v)
+  // An i32 node carrying `.ptrKind` is an *unboxed pointer* (object/array local),
+  // not a number — skipping coercion would reinterpret pointer bits as an f64.
+  // Only a plain i32 (loop counter, `x|0`) is genuinely already-numeric.
+  if ((v.type === 'i32' && v.ptrKind == null) || isLit(v)) return asF64(v)
   const vt = keyValType(node)
   if (vt === VAL.NUMBER || vt === VAL.BIGINT) return asF64(v)
   if (vt === VAL.DATE) {
@@ -353,20 +467,76 @@ export function toNumF64(node, v) {
       : ['i32.wrap_i64', ['i64.reinterpret_f64', asF64(v)]]
     return typed(['f64.load', ptr], 'f64')
   }
+  // ToPrimitive (number hint): an OBJECT operand coerces through the
+  // `OrdinaryToPrimitive` method chain [valueOf, toString] — `valueOf` is tried
+  // first, and when it yields a non-primitive `toString` is tried; if both
+  // yield non-primitives a TypeError is thrown. The chosen primitive still
+  // flows through `__to_num` so a string return ("−7") is parsed. An abrupt
+  // completion (throwing method) propagates through the closure call.
+  if (vt === VAL.OBJECT && ctx.closure.call && ctx.schema.find) {
+    const prim = toPrimitiveChain(node, v, ['valueOf', 'toString'])
+    if (prim) {
+      // No `__to_num` helper → the program provably has no strings, so the
+      // primitive is a non-string value already usable as an f64.
+      if (!ctx.core.stdlib['__to_num']) return asF64(prim)
+      inc('__to_num')
+      return typed(['call', '$__to_num', prim], 'f64')
+    }
+  }
   // intCertain locals: every reachable def is integer-valued, so the binding
   // never carries a NaN-boxed pointer — skip the __to_num wrapper.
   if (typeof node === 'string' && repOf(node)?.intCertain === true) return asF64(v)
+  // intCertain schema slot reads `o.x`: every observed write is integer-shaped,
+  // so the loaded f64 is a plain number — same justification as the local case.
+  if (Array.isArray(node) && node[0] === '.' && typeof node[1] === 'string' && typeof node[2] === 'string') {
+    if (ctx.schema.slotIntCertainAt?.(node[1], node[2]) === true) return asF64(v)
+  }
   // IR-level shapes that produce real f64 numbers (never NaN-boxed pointers):
   // i32→f64 conversions, stdlib clock helper. Skip the __to_num call wrapper.
   if (Array.isArray(v)) {
     if (v[0] === 'f64.convert_i32_s' || v[0] === 'f64.convert_i32_u') return v
     if (v[0] === 'call' && v[1] === '$__time_ms') return v
   }
-  if (!ctx.core.stdlib['__to_num']) return asF64(v)
+  if (!ctx.core.stdlib['__to_num']) {
+    // No full ToNumber helper loaded — the program provably has no strings.
+    // A nullish *literal* still coerces (null→+0, undefined→NaN) — fold it
+    // statically so `Math.log10(null)` & friends are correct at zero cost.
+    // Non-literal values fall through to `asF64`: an untyped runtime value
+    // *could* be a nullish sentinel, but blanket per-use coercion taxes every
+    // numeric kernel (fib, math loops) — nullable-param coercion belongs once
+    // at the function boundary (null-flow inference), not at each use site.
+    const f = asF64(v)
+    if (Array.isArray(f) && f[0] === 'f64.const' && typeof f[1] === 'string') {
+      const lit = f[1]
+      if (lit.startsWith('nan:'))                           // NaN-boxed sentinel/pointer
+        return typed(['f64.const', lit.slice(4) === NULL_NAN ? 0 : 'nan'], 'f64')
+    }
+    return f
+  }
   inc('__to_num')
   return typed(['call', '$__to_num', asI64(v)], 'f64')
 }
 
+/** Coerce an emitted IR value to a jz string per JS `ToString`, returning an
+ *  i64 string value. The mirror of `toNumF64` for the string hint: an OBJECT
+ *  operand coerces through `OrdinaryToPrimitive(string)` — method chain
+ *  [toString, valueOf], `toString` first with fallback to `valueOf`, TypeError
+ *  if both yield non-primitives. The chosen primitive still flows through
+ *  `__to_str` so a numeric return is rendered. A throwing method propagates as
+ *  an abrupt completion through the closure call. */
+export function toStrI64(node, v) {
+  const vt = keyValType(node)
+  if (vt === VAL.OBJECT && ctx.closure.call && ctx.schema.find) {
+    const prim = toPrimitiveChain(node, v, ['toString', 'valueOf'])
+    if (prim) {
+      inc('__to_str')
+      return typed(['call', '$__to_str', prim], 'i64')
+    }
+  }
+  inc('__to_str')
+  return typed(['call', '$__to_str', asI64(v)], 'i64')
+}
+
 /** Convert already-emitted WASM node to i32 boolean. NaN is falsy (like JS).
  *  Peepholes: i32 → as-is; `f64.convert_i32_*(x)` → x (i32 conversion never NaN);
  *  nested `__is_truthy(x)` → x (already 0/1); literal f64 const folds to 0/1. */
@@ -382,11 +552,18 @@ export function truthyIR(e) {
     if (e[0] === 'f64.const' && typeof e[1] === 'number') {
       return typed(['i32.const', (e[1] !== 0 && !Number.isNaN(e[1])) ? 1 : 0], 'i32')
     }
+    // Fold NaN-boxed sentinel literals in `f64.const nan:0x...` form (boolean
+    // atoms, null/undefined): TRUE → 1, everything else nullish/false → 0.
+    if (e[0] === 'f64.const' && typeof e[1] === 'string' && e[1].startsWith('nan:')) {
+      const bits = e[1].slice(4)
+      if (bits === TRUE_NAN) return typed(['i32.const', 1], 'i32')
+      if (bits === FALSE_NAN || bits === UNDEF_NAN || bits === NULL_NAN) return typed(['i32.const', 0], 'i32')
+    }
     // Fold NaN-boxed pointer literals: UNDEF/NULL/canonical-NaN sentinels are falsy;
     // all other NaN-boxed pointers (SSO strings, heap ptrs, etc.) are truthy.
     if (e[0] === 'f64.reinterpret_i64' && Array.isArray(e[1]) && e[1][0] === 'i64.const') {
       const bits = String(e[1][1])
-      const FALSY = new Set([UNDEF_NAN, NULL_NAN, '0x7FF8000000000000', '0x7FFA400000000000'])
+      const FALSY = new Set([UNDEF_NAN, NULL_NAN, FALSE_NAN, '0x7FF8000000000000', '0x7FFA400000000000'])
       return typed(['i32.const', FALSY.has(bits) ? 0 : 1], 'i32')
     }
     // Fresh pointer constructors never produce nullish. Treat as always truthy.
@@ -428,7 +605,7 @@ export function needsDynShadow(target) {
   if (!ctx.module.modules.collection) return false
   // Functions/CLOSURE always need dynamic props so cross-module property
   // access (fn.parse, i32.parse aliases) sees the same value as schema slots.
-  const vt = typeof target === 'string' ? (ctx.func.repByLocal?.get(target)?.val || ctx.scope.globalValTypes?.get(target)) : null
+  const vt = typeof target === 'string' ? (ctx.func.localReps?.get(target)?.val || ctx.scope.globalValTypes?.get(target)) : null
   if (vt === 'closure' || usesDynProps(vt)) return true
   const dyn = ctx.types?.dynKeyVars
   if (target == null) return ctx.types?.anyDynKey ?? false
@@ -481,6 +658,11 @@ export function readVar(name) {
                        : typed(['f64.const', rep.intConst], 'f64')
   }
   const node = typed(['local.get', `$${name}`], t)
+  // Proven uint32 accumulator local (narrowUint32): a later asF64 must widen with
+  // convert_i32_u (the i32 bit pattern is an unsigned value), not _s. `.wrapSafe`
+  // marks it as the always-ToUint32-sunk kind so the arithmetic widening guards
+  // keep it on the i32 path — wrapping is its intended semantics, not a leak.
+  if (t === 'i32' && rep?.unsigned) { node.unsigned = true; node.wrapSafe = true }
   if (rep?.ptrKind != null) {
     node.ptrKind = rep.ptrKind
     const aux = rep.ptrAux ?? ctx.schema.idOf?.(name)
@@ -531,7 +713,7 @@ export function writeVar(name, valIR, void_) {
 
 /** Check if f64 expr is nullish (NULL_NAN or UNDEF_NAN). Returns i32.
  *  Peepholes: fold known NaN-boxed sentinel literals; elide on numeric literals;
- *  unboxed pointer locals are proven non-null by analyzePtrUnboxable.
+ *  unboxed pointer locals are proven non-null by unboxablePtrs.
  *  Inlines directly: (i32.or (i64.eq bits NULL_NAN) (i64.eq bits UNDEF_NAN))
  *  rather than calling $__is_nullish — saves WASM call dispatch in V8 JIT. */
 export const isNullish = (f64expr) => {
@@ -586,22 +768,38 @@ export const isUndef = (f64expr) => {
   return typed(['i64.eq', ['i64.reinterpret_f64', f64expr], ['i64.const', UNDEF_NAN]], 'i32')
 }
 
-// === Array layout helpers ===
+/** Mask that clears the boolean atom's truth bit, mapping TRUE_NAN→FALSE_NAN.
+ *  `(bits & BOOL_ATOM_MASK) === FALSE_NAN` recognizes both in one i64.and+i64.eq. */
+const BOOL_ATOM_MASK = '0x' + BigInt.asUintN(64, ~(1n << BigInt(LAYOUT.AUX_SHIFT))).toString(16).toUpperCase().padStart(16, '0')
+
+/** Check if f64 expr is a boxed-boolean atom (TRUE_NAN or FALSE_NAN). Returns i32.
+ *  Single-eval: masks the truth bit and compares to FALSE_NAN once. */
+export const isBoolAtom = (f64expr) => {
+  if (f64expr.ptrKind != null) return typed(['i32.const', 0], 'i32')
+  if (Array.isArray(f64expr) && f64expr[0] === 'f64.const' && String(f64expr[1]).startsWith('nan:')) {
+    const b = String(f64expr[1]).slice(4)
+    return typed(['i32.const', (b === TRUE_NAN || b === FALSE_NAN) ? 1 : 0], 'i32')
+  }
+  return typed(['i64.eq',
+    ['i64.and', ['i64.reinterpret_f64', f64expr], ['i64.const', BOOL_ATOM_MASK]],
+    ['i64.const', FALSE_NAN]], 'i32')
+}
 
-/** Slot address: `base + idx*8` IR. Uses `local.get` directly when idx=0. */
+// === Array layout helpers — routed through the array carrier (abi/array.js) ===
+
+/** Slot address: element `idx` off `baseLocal`. Constant idx folds the `*8`. */
 export function slotAddr(baseLocal, idx) {
-  const base = ['local.get', `$${baseLocal}`]
-  return idx === 0 ? base : ['i32.add', base, ['i32.const', idx * 8]]
+  return ctx.abi.array.ops.addr(['local.get', `$${baseLocal}`], idx)
 }
 
 /** Load f64 element from array data at ptr + i*8. ptr/i are local name strings. */
 export function elemLoad(ptr, i) {
-  return ['f64.load', ['i32.add', ['local.get', `$${ptr}`], ['i32.shl', ['local.get', `$${i}`], ['i32.const', 3]]]]
+  return ctx.abi.array.ops.load(['local.get', `$${ptr}`], ['local.get', `$${i}`])
 }
 
 /** Store f64 val at array data ptr + i*8. ptr/i are local name strings. */
 export function elemStore(ptr, i, val) {
-  return ['f64.store', ['i32.add', ['local.get', `$${ptr}`], ['i32.shl', ['local.get', `$${i}`], ['i32.const', 3]]], val]
+  return ctx.abi.array.ops.store(['local.get', `$${ptr}`], ['local.get', `$${i}`], val)
 }
 
 /** Emit a loop iterating over array elements. Returns IR instruction list.
@@ -708,6 +906,76 @@ export function findBodyStart(fn) {
   return fn.length
 }
 
+/**
+ * Tail-call rewrite: walks tail positions of an emitted IR tree and replaces
+ * direct `(call $name args...)` ops with `(return_call $name args...)`.
+ *
+ * Tail positions, recursively from the IR root:
+ *   - the root itself (function's terminal value-producing expression, or the
+ *     emitted value of an explicit `return X`)
+ *   - both arms of `(if (result T) cond (then ...) (else ...))`
+ *   - last instruction of `(block (result T) ...)`
+ *
+ * Only fires when caller and callee result types match — if they didn't match,
+ * `asParamType`/`asPtrOffset` would have wrapped the call in a conversion op,
+ * pushing the `call` away from the tail position. We don't recurse into
+ * arithmetic / select / loop ops: their results aren't standalone-tail control
+ * transfers.
+ *
+ * Two callers:
+ *   - `compile.js` runs it on the function's final value-producing IR to TCO
+ *     expression-bodied arrows like `(n, acc) => n <= 0 ? acc : sum(n-1, acc+n)`
+ *     where the AST has no `return` keyword.
+ *   - `emit.js` `'return'` op handler runs it on the emitted return expression
+ *     so explicit `return cond ? f(x) : g(x)` also gets deep tail rewriting.
+ *
+ * Returns the input unchanged when no transform applies.
+ */
+export const tcoTailRewrite = (ir, resultType) => {
+  if (ctx.transform.noTailCall || ctx.func.inTry) return ir
+  if (!Array.isArray(ir)) return ir
+  const op = ir[0]
+  if (op === 'call' && typeof ir[1] === 'string') {
+    // IR call name is `$name`; func.map keys are bare `name`.
+    const calleeName = ir[1].startsWith('$') ? ir[1].slice(1) : ir[1]
+    const callee = ctx.func.map.get(calleeName)
+    // If this is a known user func, verify result-type match. Otherwise
+    // (closures, imports, runtime helpers — not in `ctx.func.map`) trust the
+    // tail-position invariant: emit.js' asParamType/asPtrOffset already wrapped
+    // any mismatched call in a conversion op, so a bare `(call $X …)` at the
+    // tail of the function/if/block has by construction the same result type
+    // as the caller.
+    if (callee) {
+      if (callee.raw) return ir
+      const calleeRT = callee.sig?.results?.[0] ?? 'f64'
+      if (calleeRT !== resultType) return ir
+    }
+    return typed(['return_call', ...ir.slice(1)], resultType)
+  }
+  if (op === 'if' && Array.isArray(ir[1]) && ir[1][0] === 'result') {
+    let changed = false
+    const newIr = ir.slice()
+    for (let i = 3; i < newIr.length; i++) {
+      const arm = newIr[i]
+      if (Array.isArray(arm) && (arm[0] === 'then' || arm[0] === 'else') && arm.length > 1) {
+        const last = arm[arm.length - 1]
+        const rewritten = tcoTailRewrite(last, resultType)
+        if (rewritten !== last) {
+          newIr[i] = [...arm.slice(0, -1), rewritten]
+          changed = true
+        }
+      }
+    }
+    return changed ? typed(newIr, ir.type) : ir
+  }
+  if (op === 'block' && ir.length > 1) {
+    const last = ir[ir.length - 1]
+    const rewritten = tcoTailRewrite(last, resultType)
+    if (rewritten !== last) return typed([...ir.slice(0, -1), rewritten], ir.type)
+  }
+  return ir
+}
+
 export function reconstructArgsWithSpreads(normal, spreads) {
   const combined = []
   let normalIdx = 0