jz 0.7.0 → 0.8.1

package/src/compile/plan/literals.js

@@ -28,7 +28,7 @@ import {
   some, T, stmtList, refsName, REFS_IN_EXPR, ASSIGN_OPS, isReassigned, hasControlTransfer,
 } from '../../ast.js'
 import {
-  intLiteralValue, constIntExpr, staticObjectProps, staticPropertyKey,
+  intLiteralValue, nonNegIntLiteral, constIntExpr, staticObjectProps, staticPropertyKey,
 } from '../../static.js'
 import {
   smallConstForTripCount, containsDeclOf, cloneWithSubst,
@@ -37,7 +37,7 @@ import { VAL } from '../../reps.js'
 import { includeModule } from '../../autoload.js'
 import { analyzeBody, invalidateLocalsCache } from '../analyze.js'
 import {
-  isSimpleArg, fixedScalarTypedArray, fixedTypedArraysInBody, maxScalarTypedArrayLen,
+  isSimpleArg, fixedScalarTypedArray, fixedTypedArraysInBody, maxScalarTypedArrayLen, freshTypedArrayLocals,
 } from './common.js'
 
 // === Loop unrolling & scalarization ===
@@ -526,6 +526,44 @@ export const scalarizeFunctionTypedArrays = (programFacts) => {
   return changed
 }
 
+// Param-distinctness (alias analysis). Marks a function's typed-array params MUTUALLY DISTINCT
+// (provably different buffers) when EVERY call site passes a distinct fresh `new TypedArray` local
+// for each of them. This is what lets the optimizer's LICM hoist a load from one such param across
+// a store to another (the load can't be clobbered) — the alias-analysis-enabled LICM that
+// rust/clang get for free (raytrace's sphere loads vs the framebuffer store). Sound because:
+//   • a fresh `new TypedArray(N)` is a unique buffer (the allocator returns fresh memory);
+//   • requiring ALL typed-array-param args to be fresh-new excludes views/subarrays (not fresh)
+//     and forwarded params (not fresh), the only ways two args could alias;
+//   • pairwise-distinct arg names rule out the same buffer passed twice;
+//   • scalar (non-TYPED) params are ignored — they can't alias a buffer.
+// Conservatively all-or-nothing per function: any non-fresh/duplicate typed arg ⇒ no fact.
+export const analyzeParamDistinctness = (programFacts) => {
+  const freshByFunc = new Map(ctx.func.list.map(func => [func, freshTypedArrayLocals(func.body)]))
+  const sitesByCallee = new Map()
+  for (const site of programFacts.callSites) {
+    if (!site.callerFunc) continue
+    const l = sitesByCallee.get(site.callee); l ? l.push(site) : sitesByCallee.set(site.callee, [site])
+  }
+  for (const func of ctx.func.list) {
+    const params = func.sig?.params, sites = sitesByCallee.get(func.name)
+    if (!params || !sites?.length) continue
+    const typedIdx = []
+    for (let i = 0; i < params.length; i++) if (params[i].ptrKind === VAL.TYPED) typedIdx.push(i)
+    if (typedIdx.length < 2) continue   // distinctness only matters with ≥2 typed-array params
+    let ok = true
+    for (const site of sites) {
+      const seen = new Set()
+      for (const i of typedIdx) {
+        const arg = site.argList?.[i]
+        if (typeof arg !== 'string' || !freshByFunc.get(site.callerFunc)?.has(arg) || seen.has(arg)) { ok = false; break }
+        seen.add(arg)
+      }
+      if (!ok) break
+    }
+    if (ok) func.distinctParams = new Set(typedIdx.map(i => params[i].name))
+  }
+}
+
 const scalarizeArrayLiteralSeq = (seq) => {
   if (!Array.isArray(seq) || seq[0] !== ';') return { node: seq, changed: false }
   let changed = false
@@ -940,13 +978,41 @@ const _intArrayLitElems = (expr) => {
   return out
 }
 
+// Arithmetic and bitwise operators that always produce a numeric result —
+// regardless of operand types — so `name[expr]` is index-safe after promotion.
+// Bitwise ops (`&`, `|`, etc.) ToInt32 their operands; pure-arithmetic ops with
+// numeric leaves stay numeric. `+` is excluded: `"a" + "b"` is a string.
+const _NUMERIC_INDEX_OPS = new Set(['-', '*', '/', '%', '&', '|', '^', '<<', '>>', '>>>', 'u-', 'u+'])
+
+// Returns true when `key` is provably a numeric index at plan time: an integer
+// literal, a local name whose val-type is VAL.NUMBER in `valTypes`, or a
+// compound expression that always produces a number (arithmetic/bitwise ops).
+// Mirrors the `idxNumericName` / `intIndexIR` guard in emit so that the same
+// index shapes that skip `__is_str_key` at emit-time also pass here. Used by
+// `_disqualifyPromotion` to gate index reads: a non-numeric key on a promoted
+// Int32Array NaN-coerces to 0 (trunc_sat_f64_s(NaN) = 0) instead of returning
+// undefined — the correct JS behaviour for an out-of-range or string index.
+const _isNumericKey = (key, valTypes) => {
+  if (key == null) return false
+  if (nonNegIntLiteral(key) != null) return true           // literal integer
+  if (typeof key === 'string') return valTypes?.get(key) === VAL.NUMBER
+  if (!Array.isArray(key)) return false
+  const op = key[0]
+  if (op == null) return typeof key[1] === 'number'        // [null, n] literal
+  if (_NUMERIC_INDEX_OPS.has(op)) return true              // always produces Number
+  // `+` is numeric only when both operands are proven numeric.
+  if (op === '+' && key.length === 3)
+    return _isNumericKey(key[1], valTypes) && _isNumericKey(key[2], valTypes)
+  return false
+}
+
 // Walks `node` and disqualifies every candidate name that appears in an
 // unsafe context. `initSet` holds the candidate's own init-decl AST nodes
 // (their LHS reference is the binding being defined, not an escape).
-const _disqualifyPromotion = (node, candidates, disqualified, initSet) => {
+const _disqualifyPromotion = (node, candidates, disqualified, initSet, valTypes) => {
   if (initSet.has(node)) {
     // The init decl itself: only walk the RHS (skip the LHS `name`).
-    return _disqualifyPromotion(node[2], candidates, disqualified, initSet)
+    return _disqualifyPromotion(node[2], candidates, disqualified, initSet, valTypes)
   }
   if (typeof node === 'string') {
     // Bare identifier outside any handled parent context — escape.
@@ -972,7 +1038,7 @@ const _disqualifyPromotion = (node, candidates, disqualified, initSet) => {
       Array.isArray(node[1]) && (node[1][0] === '.' || node[1][0] === '?.') &&
       typeof node[1][1] === 'string' && candidates.has(node[1][1])) {
     disqualified.add(node[1][1])
-    for (let i = 2; i < node.length; i++) _disqualifyPromotion(node[i], candidates, disqualified, initSet)
+    for (let i = 2; i < node.length; i++) _disqualifyPromotion(node[i], candidates, disqualified, initSet, valTypes)
     return
   }
 
@@ -994,7 +1060,7 @@ const _disqualifyPromotion = (node, candidates, disqualified, initSet) => {
         typeof callee[1] === 'string' && candidates.has(callee[1])) {
       if (!_TYPED_SAFE_METHODS.has(callee[2])) disqualified.add(callee[1])
       // Walk method args (skip the receiver — already validated above).
-      for (let i = 2; i < node.length; i++) _disqualifyPromotion(node[i], candidates, disqualified, initSet)
+      for (let i = 2; i < node.length; i++) _disqualifyPromotion(node[i], candidates, disqualified, initSet, valTypes)
       return
     }
     // Array.isArray flips true→false under promotion.
@@ -1003,7 +1069,7 @@ const _disqualifyPromotion = (node, candidates, disqualified, initSet) => {
       const list = raw == null ? [] : (Array.isArray(raw) && raw[0] === ',') ? raw.slice(1) : [raw]
       for (const a of list) {
         if (typeof a === 'string' && candidates.has(a)) disqualified.add(a)
-        else _disqualifyPromotion(a, candidates, disqualified, initSet)
+        else _disqualifyPromotion(a, candidates, disqualified, initSet, valTypes)
       }
       return
     }
@@ -1011,10 +1077,15 @@ const _disqualifyPromotion = (node, candidates, disqualified, initSet) => {
     // bare-name leaf above and disqualify.
   }
 
-  // Index read `name[k]` — read access is TYPED-safe. Walk the key in case
-  // it contains references to other candidate names.
+  // Index read `name[k]` — TYPED-safe only when the key is provably numeric.
+  // A string or unknown key on a promoted Int32Array would NaN-coerce to 0
+  // (i32.trunc_sat_f64_s(NaN) = 0) instead of returning undefined — silently
+  // wrong. Mirror the `idxNumericName` / `intIndexIR` guard in emit: disqualify
+  // the candidate unless `k` is an integer literal, a VAL.NUMBER local, or an
+  // expression that always produces a Number (bitwise/arithmetic ops).
   if (op === '[]' && typeof node[1] === 'string' && candidates.has(node[1])) {
-    _disqualifyPromotion(node[2], candidates, disqualified, initSet)
+    _disqualifyPromotion(node[2], candidates, disqualified, initSet, valTypes)
+    if (!_isNumericKey(node[2], valTypes)) disqualified.add(node[1])
     return
   }
 
@@ -1023,15 +1094,15 @@ const _disqualifyPromotion = (node, candidates, disqualified, initSet) => {
   if (ASSIGN_OPS.has(op) && Array.isArray(node[1]) && node[1][0] === '[]' &&
       typeof node[1][1] === 'string' && candidates.has(node[1][1])) {
     disqualified.add(node[1][1])
-    _disqualifyPromotion(node[1][2], candidates, disqualified, initSet)
-    _disqualifyPromotion(node[2], candidates, disqualified, initSet)
+    _disqualifyPromotion(node[1][2], candidates, disqualified, initSet, valTypes)
+    _disqualifyPromotion(node[2], candidates, disqualified, initSet, valTypes)
     return
   }
 
   // Whole-binding reassign: `name = …` / `name += …` / etc.
   if (ASSIGN_OPS.has(op) && typeof node[1] === 'string' && candidates.has(node[1])) {
     disqualified.add(node[1])
-    _disqualifyPromotion(node[2], candidates, disqualified, initSet)
+    _disqualifyPromotion(node[2], candidates, disqualified, initSet, valTypes)
     return
   }
 
@@ -1041,7 +1112,7 @@ const _disqualifyPromotion = (node, candidates, disqualified, initSet) => {
     if (typeof t === 'string' && candidates.has(t)) { disqualified.add(t); return }
     if (Array.isArray(t) && t[0] === '[]' && typeof t[1] === 'string' && candidates.has(t[1])) {
       disqualified.add(t[1])
-      _disqualifyPromotion(t[2], candidates, disqualified, initSet)
+      _disqualifyPromotion(t[2], candidates, disqualified, initSet, valTypes)
       return
     }
   }
@@ -1056,9 +1127,9 @@ const _disqualifyPromotion = (node, candidates, disqualified, initSet) => {
       else if (Array.isArray(d) && d[0] === '=' && typeof d[1] === 'string' &&
                candidates.has(d[1]) && !initSet.has(d)) {
         disqualified.add(d[1])
-        _disqualifyPromotion(d[2], candidates, disqualified, initSet)
+        _disqualifyPromotion(d[2], candidates, disqualified, initSet, valTypes)
       } else {
-        _disqualifyPromotion(d, candidates, disqualified, initSet)
+        _disqualifyPromotion(d, candidates, disqualified, initSet, valTypes)
       }
     }
     return
@@ -1080,14 +1151,14 @@ const _disqualifyPromotion = (node, candidates, disqualified, initSet) => {
     for (let i = 1; i < node.length; i++) {
       const child = node[i]
       if (i === 2 && typeof child === 'string' && candidates.has(child)) continue
-      _disqualifyPromotion(child, candidates, disqualified, initSet)
+      _disqualifyPromotion(child, candidates, disqualified, initSet, valTypes)
     }
     return
   }
 
   // Generic — recurse into children. Bare-name refs at unhandled positions
   // hit the string-leaf branch above and disqualify on contact.
-  for (let i = 1; i < node.length; i++) _disqualifyPromotion(node[i], candidates, disqualified, initSet)
+  for (let i = 1; i < node.length; i++) _disqualifyPromotion(node[i], candidates, disqualified, initSet, valTypes)
 }
 
 // Walk `body` to collect every `let X = [intLit, …]` candidate. Each entry
@@ -1155,8 +1226,11 @@ const promoteIntArrayLiteralsInBody = (body) => {
   if (!candidates.size) return { node: body, changed: false }
   const initSet = new Set()
   for (const { initDecl } of candidates.values()) initSet.add(initDecl)
+  // valTypes from analyzeBody gives per-local VAL.* kinds, used by
+  // _disqualifyPromotion to prove index keys are numeric (see _isNumericKey).
+  const { valTypes } = analyzeBody(body)
   const disqualified = new Set()
-  _disqualifyPromotion(body, candidates, disqualified, initSet)
+  _disqualifyPromotion(body, candidates, disqualified, initSet, valTypes)
   const validated = new Set()
   for (const name of candidates.keys()) if (!disqualified.has(name)) validated.add(name)
   if (!validated.size) return { node: body, changed: false }

package/src/ctx.js

@@ -38,11 +38,11 @@ export { HEAP, LAYOUT, PTR, ATOM, FORWARDING_MASK, nanPrefixHex, atomNanHex, sso
 // |-----------|----------|---------------------------------|---------------------------|
 // | core      | compile  | reset, modules, inc(), emit*    | emit, compile, modules    |
 // | module    | compile  | prepare, index.js               | prepare, compile, emit    |
-// | scope     | compile  | analyze, compile, plan, modules | compile, emit             |
-// | func      | function | compile, narrow                 | emit, modules             |
+// | scope     | compile  | analyze, compile, plan, modules, assemble | compile, emit   |
+// | func      | function | compile, narrow, assemble       | emit, modules             |
 // | types     | function | analyze, plan                   | emit, modules             |
 // | schema    | compile  | prepare, analyze, compile       | prepare, analyze, emit    |
-// | closure   | init     | modules (fn plugin)             | emit, compile             |
+// | closure   | init     | modules (fn plugin), plan, emit | emit, compile             |
 // | runtime   | compile  | emit, modules                   | emit, compile             |
 // | memory    | compile  | index.js                        | compile                   |
 // | error     | compile  | prepare, compile, emit          | err()                     |
@@ -63,6 +63,11 @@ export { HEAP, LAYOUT, PTR, ATOM, FORWARDING_MASK, nanPrefixHex, atomNanHex, sso
 // narrow-phase writers: narrowSignatures (under plan) temporarily swaps
 //   ctx.func.{localReps, locals, current} per-function with save/restore
 //   so per-call-site signature inference sees the right scope.
+// assemble-phase writers: buildStartFn (wat/assemble.js) re-owns the ctx.func frame
+//   (locals/stack/refinements/…) to emit the module-init `start` fn, save/restoring
+//   around it; the data pass also const-folds ctx.scope.globals (mut→false) and
+//   declares the __heap* globals. emit seeds ctx.closure.{paramTypes,paramTypedCtors}
+//   at direct-call sites (read by emitClosureBody); plan sets ctx.closure.{floor,width}.
 export const ctx = {
   core: {},       // emitter table + stdlib registry (seeded by reset + modules)
   module: {},     // module graph: imports, resolved sources, module-init blocks
@@ -92,9 +97,14 @@ export const ctx = {
                   // the defaults; see reset() for the field list and who flips each.
 }
 
-/** Create a child scope via shallow flat copy (metacircular-safe: no prototype chain).
+/** Create a child scope via shallow flat copy with NO prototype chain. Critical:
+ *  `{ ...parent }` would inherit Object.prototype in V8 (jz.js), so a name-keyed lookup
+ *  like `chain['valueOf']`/`emit['toString']` returns the inherited method instead of
+ *  undefined — corrupting resolution of any identifier named like an Object method. The
+ *  kernel's jz objects are already prototype-less, so this was a jz.js-ONLY footgun. A
+ *  prototype-less dict (Object.create(null) + assign) is correct in both engines.
  *  Mutations to the child do not affect the parent; lookups work via direct property access. */
-export const derive = (parent) => ({ ...parent })
+export const derive = (parent) => Object.assign(Object.create(null), parent)
 
 /** Include stdlib names for emission. */
 export const inc = (...names) => names.forEach(n => ctx.core.includes.add(n))
@@ -133,12 +143,19 @@ export const emitter = (deps, fn) => {
  *  carry it as `.argc`; bare ones expose it as the function's own `.length`. */
 export const emitArity = (h) => h?.argc ?? h?.length
 
-/** Tag an emit handler as a property getter — it yields a value when the
- *  property is *read* (`re.source`, `m.size`), so the `.`-read path may fire it.
- *  Untagged handlers are methods: a bare read of `m.values` must not invoke them
- *  (that would materialize a view instead of reading the `"values"` property);
- *  they fire only from the method-call path. Apply outermost: `getter(emitter(…))`. */
-export const getter = (fn) => (fn.getter = true, fn)
+/** Register `fn` as a property-GETTER emitter for `key` — it yields a value when
+ *  the property is *read* (`re.source`, `m.size`, `a.byteOffset`), so the `.`-read
+ *  path fires it. (Untagged `ctx.core.emit` handlers are methods: a bare read of
+ *  `m.values` must NOT invoke them — that would materialize a view — they fire only
+ *  from the method-call path.) Getter-ness lives in `ctx.core.getters` (a plain Set),
+ *  NOT as a flag on the emitter closure: the self-host kernel can't reliably read a
+ *  dynamic property off a closure returned via a dynamic-key lookup, so a closure tag
+ *  silently read `undefined` and every getter fell through to `__dyn_get`. A Set
+ *  key-lookup is kernel-safe. Dispatch (module/core.js) checks `ctx.core.getters.has(key)`. */
+export const registerGetter = (key, fn) => {
+  ctx.core.emit[key] = fn
+  ctx.core.getters.add(key)
+}
 
 /** Expand ctx.core.includes transitively via ctx.core.stdlibDeps. Call before WASM assembly.
  *  Each module co-locates its own deps with its stdlib registrations at init time. */
@@ -207,6 +224,13 @@ export function reset(proto, globals, bridge) {
                             // `(import "env" "name" (global $name i64))` at assembly. Same
                             // usage-gated pattern as jsstring — emit records, assembly owns
                             // the ctx.module.imports write.
+    getters: new Set(), // keys of emit entries that are property getters — the
+                        // kernel-safe authority for getter dispatch (a closure-attached
+                        // flag was unreadable in the self-host kernel after a dynamic-key
+                        // lookup, so every getter silently fell through to __dyn_get).
+                        // MUST remain last: adding fields before stdlib/stdlibDeps/… shifts
+                        // their slot indices and breaks the self-host compiled kernel's reads.
+                        // Populated by registerGetter(); checked by module/core.js dispatch.
   }
 
 
@@ -234,6 +258,10 @@ export function reset(proto, globals, bridge) {
     globalTypedElem: null,
     globalReps: null, // Map<name, ValueRep> — module-level pointer reps (TYPED const globals stored as raw i32 offset, etc.)
     consts: null,
+    constInts: null,      // Map<name, int> — module const folded to an integer literal (prepare/plan seed; static/ir read)
+    constStrs: null,      // Map<name, string> — module const folded to a string literal
+    shapeStrs: null,      // Map<expr, string> / shapeStrArrays: Map<name, string[]> — schema-shape string folds
+    shapeStrArrays: null,
   }
 
   ctx.func = {
@@ -241,7 +269,7 @@ export function reset(proto, globals, bridge) {
     names: new Set(),  // Set<string> — known func names (list + imported funcs); populated at compile() start
     map: new Map(),    // Map<string, func> — name → func entry; populated at compile() start
     multiProp: new Set(),  // Set<"obj.prop"> — function-properties assigned >1× (wrapper composition); suppresses the static fn.prop() direct call
-    exports: {},
+    exports: Object.create(null),  // name-keyed: prototype-less (see derive) — `export let valueOf` must not hit Object.prototype
     current: null,
     locals: new Map(),
     localReps: null,
@@ -324,6 +352,8 @@ export function reset(proto, globals, bridge) {
     minArgc: null,        // Map<closureBodyName, number> — fewest args any direct call passed.
                           // A slot at index ≥ minArgc is omitted by some call (→ may be undefined),
                           // so it must NOT be typed NUMBER, else `x === undefined` mis-folds to false.
+    floor: null,          // min closure-table arity (modules: fn/timer/typedarray/array; read in plan). null ⇒ 0.
+    width: null,          // closure call/make signature width (plan/scope sets; emit/assemble read). null ⇒ MAX_CLOSURE_ARITY.
   }
 
   ctx.runtime = {
@@ -370,6 +400,15 @@ export function reset(proto, globals, bridge) {
     inspect: false,     // when true, compile() additionally populates ctx.inspect with the inferred
                         // per-function signatures, locals, and JSON shapes — readable by editor
                         // hosts for inlay hints / hover types without re-running the analyzer.
+    helperCounters: false, // internal profiling mode: export mutable i64 counters for selected
+                           // runtime helpers and instrument their entry blocks. Build-time opt-in
+                           // only; normal output is byte-identical and pays no counter cost.
+    helperCallsites: false, // profiling-only: export mutable i64 counters for selected runtime
+                            // helper callsites after optimization, so hot helpers can be traced
+                            // back to the compiled function that calls them.
+    loopXformId: 0,     // monotonic id for the per-function loop transforms' generated locals
+                        // (loop-model freshLoopId). Per-compile (reset here), not a module-global —
+                        // so compile(P) is deterministic regardless of prior compiles in the process.
   }
 
   // Inspection sink. Populated by compile() only when transform.inspect is true.

package/src/helper-counters.js

@@ -0,0 +1,137 @@
+import { ctx, declGlobal, inc } from './ctx.js'
+import { findBodyStart } from './ir.js'
+
+export const HELPER_COUNTERS = [
+  ['__eq', 'eq'],
+  ['__same_value_zero', 'same_value_zero'],
+  ['__is_truthy', 'is_truthy'],
+  ['__ptr_type', 'ptr_type'],
+  ['__ptr_offset', 'ptr_offset'],
+  ['__len', 'len'],
+  ['__length', 'length'],
+  ['__typed_idx', 'typed_idx'],
+  ['__str_len', 'str_len'],
+  ['__str_eq', 'str_eq'],
+  ['__str_eq_cold', 'str_eq_cold'],
+  ['__str_hash', 'str_hash'],
+  ['__map_hash', 'map_hash'],
+  ['__hash_get_local', 'hash_get_local'],
+  ['__hash_set_local', 'hash_set_local'],
+  ['__ihash_get_local', 'ihash_get_local'],
+  ['__ihash_set_local', 'ihash_set_local'],
+  ['__dyn_get', 'dyn_get'],
+  ['__dyn_get_t', 'dyn_get_t'],
+  ['__dyn_get_t_h', 'dyn_get_t_h'],
+  ['__dyn_set', 'dyn_set'],
+  ['__arr_grow', 'arr_grow'],
+  ['__arr_grow_known', 'arr_grow_known'],
+  ['__arr_push1', 'arr_push1'],
+  ['__arr_shift', 'arr_shift'],
+  ['__alloc', 'alloc'],
+  ['__alloc_hdr', 'alloc_hdr'],
+  ['__alloc_hdr_n', 'alloc_hdr_n'],
+  ['__memgrow', 'memgrow'],
+]
+
+const COUNTER_BY_HELPER = new Map(HELPER_COUNTERS.map(([helper, label]) => [helper, `__hc_${label}`]))
+const LABEL_BY_WAT_HELPER = new Map(HELPER_COUNTERS.map(([helper, label]) => [`$${helper}`, label]))
+
+export const HELPER_SITE_PREFIX = '__hcs_'
+
+export const helperCounterName = helper => COUNTER_BY_HELPER.get(helper)
+
+export function installHelperCounters() {
+  if (!ctx.transform.helperCounters) return
+  for (const counter of COUNTER_BY_HELPER.values()) {
+    if (!ctx.scope.globals.has(counter)) declGlobal(counter, 'i64', 0, { export: counter })
+  }
+  ctx.core.stdlib.__helper_counts_reset = `(func $__helper_counts_reset (export "__helper_counts_reset")
+${[...COUNTER_BY_HELPER.values()].map(counter => `    (global.set $${counter} (i64.const 0))`).join('\n')})`
+  inc('__helper_counts_reset')
+}
+
+// Bump the helper's counter once on entry. NOTE the semantics: this counts FUNCTION
+// ENTRIES at runtime — a call site that jz inlined or specialized away (fusedRewrite,
+// specializeMkptr/specializePtrBase, …) never enters the function and is NOT counted. So
+// the numbers are a relative ranking / lower bound for picking hot helpers, not exact
+// operation counts. Good enough to choose targets; don't read them as call totals.
+export function instrumentHelperCounter(helper, fn) {
+  const counter = ctx.transform.helperCounters && helperCounterName(helper)
+  if (!counter || !Array.isArray(fn) || fn[0] !== 'func') return fn
+  fn.splice(findBodyStart(fn), 0,
+    ['global.set', `$${counter}`, ['i64.add', ['global.get', `$${counter}`], ['i64.const', 1]]])
+  return fn
+}
+
+const safeExportPart = name => String(name || 'anon')
+  .replace(/^\$/, '')
+  .replace(/[^A-Za-z0-9_.-]+/g, '_')
+  .slice(0, 80) || 'anon'
+
+const helperSiteFilter = () => {
+  const opt = ctx.transform.helperCallsites
+  if (opt === true) return null
+  const raw = Array.isArray(opt) ? opt : String(opt || '').split(',')
+  const labels = raw.map(s => String(s).trim()).filter(Boolean).map(s => s.replace(/^\$?__/, ''))
+  return labels.length ? new Set(labels) : null
+}
+
+const funcResults = fn => {
+  const out = []
+  if (!Array.isArray(fn) || fn[0] !== 'func') return out
+  for (let i = 2; i < fn.length; i++) {
+    const n = fn[i]
+    if (Array.isArray(n) && n[0] === 'result') out.push(...n.slice(1))
+  }
+  return out
+}
+
+const bumpCounter = counter =>
+  ['global.set', `$${counter}`, ['i64.add', ['global.get', `$${counter}`], ['i64.const', 1]]]
+
+// Profiling-only helper-callsite counters. Unlike instrumentHelperCounter(), this
+// answers "which compiled function executed the helper call?" by wrapping each
+// final `(call $__helper ...)` with a tiny counter block:
+//   (block (result T) (global.set $__hcs_N ...) (call $__helper ...))
+//
+// This intentionally runs after whole-module optimization. The profile should
+// observe final codegen, while production output remains byte-identical because
+// ctx.transform.helperCallsites is build-time opt-in.
+export function instrumentHelperCallsites(funcs) {
+  if (!ctx.transform.helperCallsites) return 0
+  const only = helperSiteFilter()
+
+  const resultsByName = new Map()
+  for (const fn of funcs) {
+    if (Array.isArray(fn) && fn[0] === 'func' && typeof fn[1] === 'string')
+      resultsByName.set(fn[1], funcResults(fn))
+  }
+
+  let id = 0
+  const wrap = (node, owner) => {
+    if (!Array.isArray(node)) return node
+    for (let i = 1; i < node.length; i++) node[i] = wrap(node[i], owner)
+
+    if (node[0] !== 'call' || typeof node[1] !== 'string') return node
+    const label = LABEL_BY_WAT_HELPER.get(node[1])
+    if (!label) return node
+    if (only && !only.has(label) && !only.has(node[1].replace(/^\$?__/, ''))) return node
+    const results = resultsByName.get(node[1])
+    if (!results) return node
+
+    const counter = `${HELPER_SITE_PREFIX}${id++}`
+    const ownerPart = safeExportPart(owner)
+    declGlobal(counter, 'i64', 0, { export: `${counter}:${label}:${ownerPart}` })
+    const block = ['block']
+    for (const type of results) block.push(['result', type])
+    block.push(bumpCounter(counter), node)
+    return block
+  }
+
+  for (const fn of funcs) {
+    if (!Array.isArray(fn) || fn[0] !== 'func' || typeof fn[1] !== 'string') continue
+    const bodyStart = findBodyStart(fn)
+    for (let i = bodyStart; i < fn.length; i++) fn[i] = wrap(fn[i], fn[1])
+  }
+  return id
+}

package/src/ir.js

@@ -21,8 +21,8 @@
  */
 
 import { ctx, err, inc, PTR, LAYOUT } from './ctx.js'
-import { ptrBoxPrefixBigInt, atomNanHex, nanPrefixHex } from '../layout.js'
-import { I32_MIN, I32_MAX, isI32, isLiteralStr, isFuncRef } from './ast.js'
+import { ptrBoxPrefixBigInt, ptrBits, i64Hex, atomNanHex, nanPrefixHex } from '../layout.js'
+import { I32_MIN, I32_MAX, isI32, isLiteralStr, isFuncRef, isLeaf } from './ast.js'
 import { VAL, lookupValType, repOf, repOfGlobal } from './reps.js'
 import { valTypeOf } from './kind.js'
 import { T } from './ast.js'
@@ -182,6 +182,82 @@ const narrowI32 = (x, isRoot) => {
   return null
 }
 
+// Conservative VALUE-RANGE for a pure f64 expression tree: returns { lo, hi } bounding
+// every value the node can take, or null when unknown. SOUND by construction — each rule
+// over-approximates using the SAME f64 ops the runtime uses (f64 +/−/× are monotone in
+// each argument, so combining endpoint-bounds with plain JS doubles yields bounds that
+// contain the true value). A null/non-finite endpoint anywhere collapses to null, so a
+// non-null result also PROVES the value is finite (never NaN, never ±∞). Used by toI32 to
+// drop the +∞-guard `select` (and the i64 round-trip when the value fits i32) — the guard
+// exists only to remap +∞→0, so a proof of finiteness retires it.
+const fin = (lo, hi) => (Number.isFinite(lo) && Number.isFinite(hi) && lo <= hi) ? { lo, hi } : null
+// Range of the i32 that feeds an `f64.convert_i32_*`, refined by a narrowing load width.
+const convRange = (child, signed) => {
+  if (Array.isArray(child)) {
+    const o = child[0]
+    if (o === 'i32.load8_u') return { lo: 0, hi: 255 }
+    if (o === 'i32.load8_s') return { lo: -128, hi: 127 }
+    if (o === 'i32.load16_u') return { lo: 0, hi: 65535 }
+    if (o === 'i32.load16_s') return { lo: -32768, hi: 32767 }
+    if (o === 'i32.const' && typeof child[1] === 'number') return signed ? { lo: child[1] | 0, hi: child[1] | 0 } : { lo: child[1] >>> 0, hi: child[1] >>> 0 }
+  }
+  return signed ? { lo: I32_MIN, hi: I32_MAX } : { lo: 0, hi: 4294967295 }
+}
+// `get`, when supplied, resolves a `(local.get $V)` to $V's single defining value node
+// (a `name → defExpr | null` map/function built from a one-def-per-local scan). This lets the
+// range see through the temps that inlining introduces — e.g. `floor(mul(convert($px),0.03125))`
+// stashed in `$xi` before truncation — so the i32-fit proof survives the indirection. SOUND
+// without code motion: a single-textual-def local holds exactly the value its def computes, so
+// the def's range bounds every value the local can take, even if the def's inputs vary across
+// iterations. A self-referential (loop-carried) single def is caught by the `seen` cycle guard
+// and yields null (unknown), which is conservative.
+export const f64Range = (n, get) => {
+  const seen = get ? new Set() : null
+  const r = (n) => {
+    if (!Array.isArray(n)) return null
+    const op = n[0]
+    if (op === 'local.get' && get && typeof n[1] === 'string') {
+      if (seen.has(n[1])) return null               // loop-carried / cyclic def → unknown
+      const def = typeof get === 'function' ? get(n[1]) : get.get(n[1])
+      if (!def) return null
+      seen.add(n[1]); const rng = r(def); seen.delete(n[1])
+      return rng
+    }
+    if (op === 'f64.const') return typeof n[1] === 'number' ? fin(n[1], n[1]) : null   // `nan:…`/Inf literal strings → null
+    if (op === 'f64.convert_i32_s') return convRange(n[1], true)
+    if (op === 'f64.convert_i32_u') return convRange(n[1], false)
+    if (op === 'f64.neg') { const a = r(n[1]); return a && fin(-a.hi, -a.lo) }
+    if (op === 'f64.abs') { const a = r(n[1]); return a && fin(a.lo > 0 ? a.lo : a.hi < 0 ? -a.hi : 0, Math.max(-a.lo, a.hi)) }
+    if (op === 'f64.sqrt') { const a = r(n[1]); return a && a.lo >= 0 && fin(Math.sqrt(a.lo), Math.sqrt(a.hi)) }
+    // Rounding ops preserve finiteness and are monotonic, so the range maps elementwise. This lets
+    // `Math.floor(x)|0` over a bounded x (every grid/image/audio index: `px*scale`, perm[] lookups)
+    // drop the +∞-guard + i64 round-trip in toI32 down to a single i32.trunc_sat_f64_s. `nearest`
+    // (round-half-to-even) lands in {floor,ceil} so its bounds are floor(lo)..ceil(hi).
+    if (op === 'f64.floor') { const a = r(n[1]); return a && fin(Math.floor(a.lo), Math.floor(a.hi)) }
+    if (op === 'f64.ceil')  { const a = r(n[1]); return a && fin(Math.ceil(a.lo), Math.ceil(a.hi)) }
+    if (op === 'f64.trunc') { const a = r(n[1]); return a && fin(Math.trunc(a.lo), Math.trunc(a.hi)) }
+    if (op === 'f64.nearest') { const a = r(n[1]); return a && fin(Math.floor(a.lo), Math.ceil(a.hi)) }
+    if (op === 'f64.add') { const a = r(n[1]), b = r(n[2]); return a && b && fin(a.lo + b.lo, a.hi + b.hi) }
+    if (op === 'f64.sub') { const a = r(n[1]), b = r(n[2]); return a && b && fin(a.lo - b.hi, a.hi - b.lo) }
+    if (op === 'f64.mul') {
+      const a = r(n[1]), b = r(n[2]); if (!a || !b) return null
+      const p = [a.lo * b.lo, a.lo * b.hi, a.hi * b.lo, a.hi * b.hi]
+      return fin(Math.min(...p), Math.max(...p))
+    }
+    if (op === 'f64.div') {
+      const c = Array.isArray(n[2]) && n[2][0] === 'f64.const' && typeof n[2][1] === 'number' ? n[2][1] : null
+      if (c == null || c === 0) return null               // variable / zero divisor → may be ±∞
+      const a = r(n[1]); if (!a) return null
+      const p = [a.lo / c, a.hi / c]
+      return fin(Math.min(...p), Math.max(...p))
+    }
+    if (op === 'f64.min') { const a = r(n[1]), b = r(n[2]); return a && b && fin(Math.min(a.lo, b.lo), Math.min(a.hi, b.hi)) }
+    if (op === 'f64.max') { const a = r(n[1]), b = r(n[2]); return a && b && fin(Math.max(a.lo, b.lo), Math.max(a.hi, b.hi)) }
+    return null
+  }
+  return r(n)
+}
+
 /** Coerce node to i32 with wrapping (JS `|0` semantics: values > 2^31 wrap to negative).
  *  Per ECMAScript ToInt32, NaN and ±∞ map to 0. `i64.trunc_sat_f64_s` handles NaN
  *  and -∞ correctly, but +∞ saturates to i64_max which wraps to -1 — guard +∞ via
@@ -204,15 +280,27 @@ export const toI32 = n => {
   // computes in i32 (mod-2^32 ring) — no trunc/guard at all.
   const nw = narrowI32(n, true)
   if (nw) return nw.node
+  // Value-range narrowing: a NON-integer f64 tree (e.g. `10 + 200·(u8[i]/255)`) the ring
+  // path rejects, but whose value is PROVABLY FINITE — so the +∞-guard `select` is dead.
+  // When the value also provably fits i32, a single `i32.trunc_sat_f64_s` IS exact ToInt32
+  // (no saturation can fire in-range, no NaN, no ±∞) — dropping the i64 round-trip AND the
+  // guard. Pervasive in pixel/colour packing: `(base + scale·v)|0`.
+  const rng = f64Range(n)
+  if (rng) {
+    if (rng.lo >= I32_MIN && rng.hi <= I32_MAX) return typed(['i32.trunc_sat_f64_s', n], 'i32')
+    // Finite and within (−2^63, 2^63): keep the mod-2^32 wrap, drop the (now-dead) +∞ guard.
+    // i64.trunc_sat does not saturate in this window, so wrap_i64 == ToInt32. Beyond ±2^63 we
+    // fall through to the guarded path (which already saturates there — the documented boundary).
+    if (rng.lo >= -9223372036854775808 && rng.hi < 9223372036854775808)
+      return typed(['i32.wrap_i64', ['i64.trunc_sat_f64_s', n]], 'i32')
+  }
   // Leaf nodes are cheap to duplicate; for everything else, evaluate once via local.tee.
-  const isLeaf = Array.isArray(n) && n.length <= 2 &&
-    (n[0] === 'f64.const' || n[0] === 'local.get' || n[0] === 'global.get')
   // `i32.wrap_i64(i64.trunc_sat_f64_s x)` is exact ToInt32 for |x| < 2^63 (the
   // overwhelming common range), maps NaN/−∞→0, and +∞ is guarded to 0 by the
   // select. For |x| ≥ 2^63 it saturates rather than wrapping mod 2^32 — a
   // deliberately-allowed asm.js-style boundary (no per-`|0` helper/guard cost).
   const wrap = x => typed(['i32.wrap_i64', ['i64.trunc_sat_f64_s', x]], 'i32')
-  if (isLeaf) {
+  if (isLeaf(n)) {
     return typed(['select', wrap(n), ['i32.const', 0], ['f64.ne', n, ['f64.const', Infinity]]], 'i32')
   }
   const t = temp('inf')
@@ -317,13 +405,7 @@ export const BOXED_MUTATORS = new Set(['push', 'pop', 'shift', 'unshift', 'splic
 const litI32 = n => Array.isArray(n) && n[0] === 'i32.const' && typeof n[1] === 'number' ? n[1] : null
 
 /** Pack (type, aux, offset) into the f64 NaN-box bit pattern as a hex string. */
-function packPtrBits(type, aux, offset) {
-  const bits = LAYOUT.NAN_PREFIX_BITS
-    | ((BigInt(type) & BigInt(LAYOUT.TAG_MASK)) << BigInt(LAYOUT.TAG_SHIFT))
-    | ((BigInt(aux) & BigInt(LAYOUT.AUX_MASK)) << BigInt(LAYOUT.AUX_SHIFT))
-    | (BigInt(offset >>> 0) & BigInt(LAYOUT.OFFSET_MASK))
-  return '0x' + bits.toString(16).toUpperCase().padStart(16, '0')
-}
+const packPtrBits = (type, aux, offset) => i64Hex(ptrBits(type, aux, offset))
 
 /** Build `__mkptr(type, aux, offset)` IR. Folds to `(f64.const nan:0x...)` — 9 bytes
  *  vs 12 for `f64.reinterpret_i64 (i64.const ...)` — when all args are i32 literals.
@@ -384,7 +466,7 @@ export function ptrTypeIR(valIR, valType) {
 // op on it misdispatches; BigInt64Array/BigUint64Array views and
 // DataView.{get,set}BigUint64 are a legacy f64-value shim there. Strings are
 // tagged and survive every boundary; BigInt math happens only inside single
-// expressions. (Same contract as wat/optimize.js's i64 VALUE CONTRACT.)
+// expressions. (Same contract as watr/optimize's i64 VALUE CONTRACT.)
 const _F64_BITS_BUF = new ArrayBuffer(8)
 const _F64_BITS_F = new Float64Array(_F64_BITS_BUF)
 const _F64_BITS_U32 = new Uint32Array(_F64_BITS_BUF)  // LE halves: [0]=lo, [1]=hi
@@ -1009,6 +1091,13 @@ export function readVar(name) {
     return typed(['f64.load', boxedAddr(name)], 'f64')
   }
   if (isGlobal(name)) {
+    // A module-level integer const (`const N = 16384`) is an immutable compile-time
+    // value: emit i32.const directly (when it fits i32) so `x % N` / `x & N` / `x / N`
+    // and counters bounded by N take the native integer path, instead of the global
+    // folding to an f64 constant and routing through the f64 round-trip. Value-preserving
+    // — an f64 consumer widens the i32.const via convert, which folds back to f64.const.
+    const ci = ctx.scope.constInts?.get?.(name)
+    if (ci != null && isI32(ci)) return typed(['i32.const', ci], 'i32')
     const gt = ctx.scope.globalTypes.get(name) || 'f64'
     const node = typed(['global.get', dollar(name)], gt)
     const grep = repOfGlobal(name)