jz 0.6.0 → 0.8.0

package/src/wat/assemble.js

@@ -37,8 +37,9 @@ import { T } from '../ast.js'
 import { analyzeValTypes, analyzeBody } from '../compile/analyze.js'
 import { VAL } from '../reps.js'
 import { optimizeFunc, collectVolatileGlobals, collectReachableGlobalWrites, hoistGlobalPtrOffset, stablePtrGlobalNames, hoistConstantPool, specializeMkptr, specializePtrBase, sortStrPoolByFreq, arenaRewindModule } from '../optimize/index.js'
-import { emit } from '../compile/emit.js'
+import { emit, emitVoid } from '../compile/emit.js'
 import { mkPtrIR, MAX_CLOSURE_ARITY, MEM_OPS, findBodyStart } from '../ir.js'
+import { installHelperCounters, instrumentHelperCounter } from '../helper-counters.js'
 
 // NaN-prefix top-13-bits as BigInt — used by the static-prefix-strip pass
 const NAN_PREFIX = BigInt(LAYOUT.NAN_PREFIX)
@@ -153,6 +154,11 @@ export function buildStartFn(ast, sec, closureFuncs, compilePendingClosures) {
   analyzeValTypes(ast)
   const normalizeIR = ir => !ir?.length ? [] : Array.isArray(ir[0]) ? ir : [ir]
 
+  // Mark module-scope emission: top-level statements run exactly once, so a constant
+  // array/object literal here is a single instance that can safely live in a static
+  // data segment (no per-call freshness to violate). Function bodies — compiled
+  // separately, and the late closures below — leave this unset and alloc fresh.
+  ctx.func.atModuleScope = true
   const moduleInits = []
   if (ctx.module.moduleInits) {
     for (const mi of ctx.module.moduleInits) {
@@ -162,7 +168,13 @@ export function buildStartFn(ast, sec, closureFuncs, compilePendingClosures) {
     }
   }
   seedGeneratedLocals(ast)
-  const init = emit(ast)
+  // __start has no result: emit the top-level program in void context so a stray
+  // value is dropped. `ast` is normally a `;` statement-sequence (each statement
+  // already void-dropped), but jzify unwraps a single-statement program to its
+  // bare expression — emitting that in value context leaves a value on the stack
+  // and the start function fails validation. emitVoid handles both shapes.
+  const init = emitVoid(ast)
+  ctx.func.atModuleScope = false
 
   // Module-scope object literals can create closure bodies while `emit(ast)`
   // runs. Those late closures may pull in stdlib helpers (notably JSON.parse)
@@ -210,6 +222,7 @@ export function buildStartFn(ast, sec, closureFuncs, compilePendingClosures) {
   // table holding only empty schemas is pure dead weight there. __json_obj has
   // no such guard — it must read the table whenever stringify is in play.
   const tblConsumed = hasStringify ||
+    ctx.core.includes.has('__obj_clone') ||
     ctx.core.includes.has('__dyn_get') ||
     ctx.core.includes.has('__dyn_get_t') ||
     ctx.core.includes.has('__dyn_get_t_h') ||
@@ -219,7 +232,13 @@ export function buildStartFn(ast, sec, closureFuncs, compilePendingClosures) {
     ctx.core.includes.has('__dyn_get_any_t_h') ||
     ctx.core.includes.has('__dyn_get_expr') ||
     ctx.core.includes.has('__dyn_get_expr_t') ||
-    ctx.core.includes.has('__dyn_get_or')
+    ctx.core.includes.has('__dyn_get_or') ||
+    // A string runtime-key WRITE `o[k]=v` whose `k` matches a schema field must
+    // mirror the value into the fixed schema slot (buildObjectSchemaSetArm), or a
+    // later static `o.x` read returns the stale slot. That mirror is gated on
+    // `$__schema_tbl != 0`, so a write-only module (no `__dyn_get*`) must still
+    // build the table. (needsSchemaTbl below skips it when every schema is empty.)
+    ctx.core.includes.has('__dyn_set')
   const needsSchemaTbl = (ctx.schema.list.length && tblConsumed &&
     (hasStringify || ctx.schema.list.some(s => s.length > 0))) ||
     hasJpObj
@@ -285,6 +304,47 @@ export function buildStartFn(ast, sec, closureFuncs, compilePendingClosures) {
     sec.funcs.unshift(...closureFuncs.slice(beforeLateClosures))
 }
 
+/**
+ * Hoist constant global initializers out of `__start` into immutable inline decls.
+ *
+ * A top-level `const x = <constant>` for a non-numeric value (atom `true`/`null`/
+ * `undefined`/`NaN`, an SSO or static-string NaN-box, a folded pointer) emits a
+ * `(global.set $x (f64.const …))` into `__start`, because only *numeric* consts are
+ * folded ahead of emit. But the value is a compile-time constant, so it belongs in
+ * the decl itself — `(global $x f64 (f64.const …))` — exactly like the numeric path.
+ * That drops the store, and when it empties `__start` the start function and its
+ * directive go too. Gated to single-assignment user `const`s so we never freeze a
+ * binding something else writes.
+ */
+export function hoistConstGlobalInits(sec) {
+  const startFn = sec.start.find(n => Array.isArray(n) && n[0] === 'func' && n[1] === '$__start')
+  if (!startFn) return
+  const writes = new Map()
+  const scan = (node) => {
+    if (!Array.isArray(node)) return
+    if (node[0] === 'global.set' && typeof node[1] === 'string') writes.set(node[1], (writes.get(node[1]) || 0) + 1)
+    for (const c of node) scan(c)
+  }
+  for (const arr of [sec.funcs, sec.stdlib, sec.start]) for (const fn of arr) scan(fn)
+  for (let i = startFn.length - 1; i >= findBodyStart(startFn); i--) {
+    const stmt = startFn[i]
+    if (!Array.isArray(stmt) || stmt[0] !== 'global.set' || writes.get(stmt[1]) !== 1) continue
+    const name = typeof stmt[1] === 'string' && stmt[1][0] === '$' ? stmt[1].slice(1) : null
+    const g = name && ctx.scope.globals.get(name)
+    const c = stmt[2]
+    if (!g || !g.mut || !ctx.scope.consts?.has(name) || !ctx.scope.userGlobals?.has(name)) continue
+    if (!Array.isArray(c) || c[0] !== `${g.type}.const`) continue
+    ctx.scope.globals.set(name, { ...g, mut: false, init: c[1] })
+    startFn.splice(i, 1)
+  }
+  // Hoisting can empty `__start`. The O2 watr pass prunes a bodyless start, but at
+  // O0/O1 nothing else does — drop it (func + directive) here so a const-only module
+  // carries no start at all.
+  if (findBodyStart(startFn) >= startFn.length)
+    for (let j = sec.start.length - 1; j >= 0; j--)
+      if (Array.isArray(sec.start[j]) && sec.start[j][1] === '$__start') sec.start.splice(j, 1)
+}
+
 /**
  * Phase: closure-body dedup.
  *
@@ -420,24 +480,188 @@ export function finalizeClosureTable(sec) {
   for (const fn of sec.start) rewriteCalls(fn)
 }
 
+/**
+ * Stdlib funcs actually reachable from the emitted program. Seeds from real
+ * `call`/`return_call`/`ref.func` sites in the user funcs, `__start`, and the elem
+ * table, then closes transitively over the stdlib call graph (each reached helper's
+ * template references). Conservative by construction — a template `$__foo` in a
+ * feature-dead branch is kept, never dropped — so it's safe to gate inclusion and the
+ * memory/allocator decision on it. An eagerly-`inc`'d helper that nothing calls is
+ * absent, which is the whole point.
+ */
+function reachableStdlib(sec) {
+  const stdlib = ctx.core.stdlib
+  const reach = new Set(), stack = []
+  // Track every reached name (module-namespace `math.sin` included), but only follow
+  // those with a stdlib template. Names match `$foo`, `$__foo`, `$math.sin_core` — the
+  // dotted module funcs are the ones the `$__`-only regex used to miss, pruning live code.
+  const add = (name) => { if (!reach.has(name)) { reach.add(name); if (stdlib[name] != null) stack.push(name) } }
+  const scanIR = (node) => {
+    if (!Array.isArray(node)) return
+    if ((node[0] === 'call' || node[0] === 'return_call' || node[0] === 'ref.func') &&
+        typeof node[1] === 'string' && node[1][0] === '$') add(node[1].slice(1))
+    for (const c of node) scanIR(c)
+  }
+  for (const fn of sec.funcs) scanIR(fn)
+  for (const fn of sec.start) scanIR(fn)
+  for (const e of sec.elem)               // closure table: bare `$fn` func refs
+    if (Array.isArray(e)) for (const c of e) if (typeof c === 'string' && c[0] === '$') add(c.slice(1))
+  // A stdlib func that self-exports (`(export "__invoke_closure")`) is a host-facing
+  // entry point — the JS host calls it directly, so it's a root even when nothing in
+  // the wasm calls it. Mirrors treeshake's inline-export rooting.
+  for (const n of ctx.core.includes) {
+    const v = stdlib[n]
+    let t = ''
+    try { t = typeof v === 'function' ? v() : v } catch { t = '' }
+    if (typeof t === 'string' && t.includes('(export "')) add(n)
+  }
+  while (stack.length) {
+    const v = stdlib[stack.pop()]
+    let text = ''
+    try { text = typeof v === 'function' ? v() : v } catch { text = '' }
+    if (typeof text === 'string') for (const m of text.matchAll(/\$([A-Za-z_][A-Za-z0-9_.]*)/g)) add(m[1])
+  }
+  return reach
+}
+
+// The f64x2 stdlib mirrors the lane vectorizer (optimize/vectorize.js) injects in the LATE 'post'
+// pass — after the stdlib was pulled + treeshaken. Keep in sync with that pass's call-rewrite map
+// (PPC_CALL2). These are the ONLY helpers appendLateStdlib may add; restricting to them avoids
+// touching helpers that live in other module sections (ext-stdlib, imports) where a blind
+// referenced-but-absent scan would wrongly re-append and duplicate them.
+const LATE_VEC_HELPERS = new Set(['math.sin2', 'math.cos2', 'math.pow2', 'math.atan2_2', 'math.hypot_2', 'math.log_v', 'math.exp_v', 'math.exp2_v'])
+
+// A late pass can reference one of the f64x2 mirrors that wasn't present when the stdlib was first
+// assembled. Append any referenced-but-missing mirror body (fixpoint over their own calls, though
+// the trig mirrors call nothing). moduleArr is mutated in place; non-mirror references are left for
+// watr to resolve (a genuine missing helper is the kernel's own pull, already satisfied).
+export function appendLateStdlib(moduleArr) {
+  const stdlib = ctx.core.stdlib
+  const have = new Set()
+  for (const n of moduleArr) if (Array.isArray(n) && n[0] === 'func' && typeof n[1] === 'string') have.add(n[1])
+  let added = true
+  while (added) {
+    added = false
+    const refs = new Set()
+    const scan = (n) => { if (!Array.isArray(n)) return; if ((n[0] === 'call' || n[0] === 'return_call' || n[0] === 'ref.func') && typeof n[1] === 'string' && n[1][0] === '$') refs.add(n[1]); for (const c of n) scan(c) }
+    for (const n of moduleArr) scan(n)
+    for (const ref of refs) {
+      const name = ref.slice(1)
+      if (have.has(ref) || !LATE_VEC_HELPERS.has(name) || stdlib[name] == null) continue
+      const node = parseTemplate(typeof stdlib[name] === 'function' ? stdlib[name]() : stdlib[name])
+      moduleArr.push(node[0] === 'module' ? node[1] : node)
+      have.add(ref)
+      added = true
+    }
+  }
+}
+
 /**
  * Phase: pull stdlib + memory.
  */
 export function pullStdlib(sec) {
+  installHelperCounters()
   resolveIncludes()
 
-  const needsMemory = [...ctx.core.includes].some(n => ctx.core.stdlib[n] && MEM_OPS.test(ctx.core.stdlib[n]))
-  if (!needsMemory) ctx.scope.globals.delete('__heap')
+  // Reachability, not inclusion, decides what the output needs. `ctx.core.includes`
+  // accumulates everything a module *might* use (eager module-load `inc`s + transitive
+  // deps), but a const array / static string literal calls none of it. So we seed from
+  // the actual call sites in the emitted funcs + __start (+ elem table) and close
+  // transitively over the stdlib call graph. An eagerly-included helper that nothing
+  // calls never enters this set — so allocator, memory, and exports reflect real use.
+  const reachable = reachableStdlib(sec)
+  const realize = (n) => { const v = ctx.core.stdlib[n]; try { return typeof v === 'function' ? v() : v } catch { return '' } }
+
+  // Two distinct needs, kept separate:
+  //  · needsAlloc — the program allocates at runtime: an allocator func is reachable,
+  //    or shared-mem string literals seed a pool __start allocs. Drives the bump
+  //    allocator (`__alloc`/`__alloc_hdr`/`__clear`), the `__heap` pointer, and the
+  //    `_alloc`/`_clear` marshalling exports.
+  //  · needsMemory — linear memory must merely *exist*: we allocate, OR a literal lives
+  //    in a static data segment (a const pointer, no allocator behind it), OR a reached
+  //    helper / inline body does a load/store, OR `__ptr_type` is reached (the module
+  //    discriminates heap tags — an `instanceof`/`typeof x==='object'` whose argument the
+  //    host marshals across the boundary). A data segment with no memory is invalid wasm,
+  //    so memory can't be gated on allocation alone.
+  const ALLOC_FUNCS = ['__alloc', '__alloc_hdr', '__alloc_hdr_n']
+  const needsAlloc = !!ctx.runtime.strPool || ALLOC_FUNCS.some(a => reachable.has(a))
+  // Memory ops can be emitted *inline* into user/start funcs (a heap-path char read
+  // loads without calling a stdlib helper), so scan the emitted bodies too.
+  const hasMemOp = (node) => Array.isArray(node) &&
+    ((typeof node[0] === 'string' && MEM_OPS.test(node[0])) || node.some(hasMemOp))
+  // `ctx.runtime.data` is never empty here — the number module seeds a static stringify
+  // prefix (`NaNInfinity…`) at offset 0; stripStaticDataPrefix removes it when unused, so
+  // the real question is whether any data lives *beyond* that strippable prefix.
+  // An explicit `{ memory: pages }` / shared-memory option is a caller request to own
+  // linear memory (e.g. to marshal host values in), independent of what the wasm itself
+  // reaches — honour it even for an otherwise-memoryless program.
+  const explicitMemory = ctx.memory.pages > 0 || !!ctx.memory.shared
+  const needsMemory = needsAlloc || explicitMemory ||
+    (ctx.runtime.data?.length || 0) > (ctx.runtime.staticDataLen || 0) ||
+    reachable.has('__ptr_type') ||
+    [...reachable].some(n => MEM_OPS.test(realize(n))) ||
+    sec.funcs.some(hasMemOp) || sec.start.some(hasMemOp)
+  // Emit only what's reachable: drop every eagerly-`inc`'d *internal* helper the program
+  // never calls. This is what lets a const-array / static-string / atom module shed the
+  // allocator, pointer dispatchers, and length helpers that an array/object module load
+  // pulled in wholesale — and it keeps the dead allocator from dangling on the `$__heap`
+  // we delete below. Scoped to `__`-prefixed names: module-namespace funcs (`math.sin`)
+  // are pulled in on demand, never eagerly, so they're already minimal and never pruned
+  // here (guarding against any reachability blind spot in a dotted-name template).
+  for (const n of [...ctx.core.includes]) if (n.startsWith('__') && !reachable.has(n)) ctx.core.includes.delete(n)
+  // Lazy Eisel-Lemire table injection: only when __dec_to_f64 (correctly-rounded
+  // decimal→f64, module/number.js) survived pruning — append its trimmed 131-entry
+  // (~2KB) power-of-10 table and declare $__el_tbl = that offset. Must run HERE so
+  // dataPages (below) accounts for the addition; keeps it out of programs that never
+  // parse decimals at runtime.
+  if (ctx.core.includes.has('__dec_to_f64') && ctx.runtime.elTable) {
+    const elBefore = ctx.runtime.data.length
+    while (ctx.runtime.data.length % 8 !== 0) ctx.runtime.data += '\0'
+    const elTblOff = ctx.runtime.data.length
+    ctx.runtime.data += ctx.runtime.elTable
+    declGlobal('__el_tbl', 'i32', elTblOff, { mut: false })
+    ctx.runtime.elTable = null  // prevent double-injection on re-entry (null-sentinel; jz forbids delete)
+    // Reachability here OVER-counts __dec_to_f64: a dead inlined helper's `arr[i] | 0`
+    // on an untyped param pulls __to_num → __dec_to_f64, landing the table even when no
+    // LIVE code parses decimals. Record the appended span (padding + table, always the
+    // data tail — it's the last append) so stripDeadElTable can drop it post-lowering,
+    // once reachability is exact. See stripDeadElTable.
+    ctx.runtime.elTableLen = ctx.runtime.data.length - elBefore
+  }
+  if (!needsAlloc) { ctx.scope.globals.delete('__heap'); ctx.scope.globals.delete('__heap_reset') }
   if (needsMemory && ctx.module.modules.core) {
-    for (const fn of ['__alloc', '__alloc_hdr', '__clear']) ctx.core.includes.add(fn)
-    // Late-add of allocators may pull in transitive deps (__alloc → __memgrow,
-    // etc.) that the initial resolveIncludes did not yet see; re-resolve.
-    // No-op when the alloc trio was already present.
-    resolveIncludes()
-    const pages = ctx.memory.pages || 1
-    if (ctx.memory.shared) sec.imports.push(['import', '"env"', '"memory"', ['memory', pages]])
-    else sec.memory.push(['memory', ['export', '"memory"'], pages])
-    if (ctx.transform.alloc !== false && ctx.core._allocRawFuncs)
+    if (needsAlloc) {
+      for (const fn of ['__alloc', '__alloc_hdr', '__clear']) ctx.core.includes.add(fn)
+      // Late-add of allocators may pull in transitive deps (__alloc → __memgrow,
+      // etc.) that the initial resolveIncludes did not yet see; re-resolve.
+      // No-op when the alloc trio was already present.
+      resolveIncludes()
+      // Record the post-init heap top into `__heap_reset` so `__clear` rewinds to
+      // just above this module's init-time heap state (e.g. the self-host compiler's
+      // GLOBALS/atom tables), not into it. Done here — where `__heap` is known to
+      // survive — as the last `__start` action before any non-returning timer loop.
+      // No `__start` ⇒ no init allocations ⇒ `__heap_reset`'s data-end seed is right.
+      if (!ctx.memory.shared && ctx.scope.globals.has('__heap_reset')) {
+        const startFn = sec.start.find(n => Array.isArray(n) && n[0] === 'func' && n[1] === '$__start')
+        if (startFn) {
+          const capture = ['global.set', '$__heap_reset', ['global.get', '$__heap']]
+          const tail = startFn[startFn.length - 1]
+          if (Array.isArray(tail) && tail[0] === 'call' && tail[1] === '$__timer_loop') startFn.splice(startFn.length - 1, 0, capture)
+          else startFn.push(capture)
+        }
+      }
+    }
+    // Initial pages must cover the static data segment (it loads at instantiation), not
+    // just the default 1 — otherwise a module whose constants exceed 64 KiB emits a data
+    // segment that overflows its own memory. The heap grows past this on demand via
+    // __memgrow. (Shared memory loads literals via memory.init into allocated space, so
+    // its initial size isn't pinned by the data length.)
+    const dataPages = ctx.memory.shared ? 0 : Math.ceil((ctx.runtime.data?.length || 0) / 65536)
+    const pages = Math.max(ctx.memory.pages || 1, dataPages)
+    const max = ctx.memory.max || 0   // 0 = no maximum (unbounded growth)
+    if (ctx.memory.shared) sec.imports.push(['import', '"env"', '"memory"', max ? ['memory', pages, max] : ['memory', pages]])
+    else sec.memory.push(max ? ['memory', ['export', '"memory"'], pages, max] : ['memory', ['export', '"memory"'], pages])
+    if (needsAlloc && ctx.transform.alloc !== false && ctx.core._allocRawFuncs)
       sec.funcs.push(...ctx.core._allocRawFuncs.map(parseTemplate))
   }
 
@@ -455,7 +679,7 @@ export function pullStdlib(sec) {
     }
   }
   for (const n of ctx.core.includes) if (!ctx.core.stdlib[n]) err(`internal: stdlib '${n}' was requested but never registered (this is a jz bug — feature pulled in something it can't deliver)`)
-  sec.stdlib.push(...[...ctx.core.includes].map(n => parseTemplate(stdlibStr(n))))
+  sec.stdlib.push(...[...ctx.core.includes].map(n => instrumentHelperCounter(n, parseTemplate(stdlibStr(n)))))
 }
 
 export function syncImports(sec) {
@@ -524,17 +748,58 @@ export function optimizeModule(sec, profiler) {
   if (dataLen > 1024 && !ctx.memory.shared) {
     const heapBase = (dataLen + 7) & ~7
     // Non-shared memory always carries a $__heap global — start it past the
-    // static data so the bump allocator never overwrites a literal.
+    // static data so the bump allocator never overwrites a literal. `__heap_reset`
+    // seeds to the same data end (its runtime value is overwritten by `__start`'s
+    // tail capture for modules that init-allocate; this seed serves modules with no
+    // `__start`, where the data end IS the correct rewind point). `__clear` reads
+    // `$__heap_reset` directly, so no per-function constant patch is needed.
     declGlobal('__heap', 'i32', heapBase, { export: '__heap' })
+    if (ctx.scope.globals.has('__heap_reset')) declGlobal('__heap_reset', 'i32', heapBase)
     if (ctx.scope.globals.has('__heap_start')) declGlobal('__heap_start', 'i32', heapBase)
-    for (const s of sec.stdlib)
-      if (s[0] === 'func' && s[1] === '$__clear')
-        for (let i = 2; i < s.length; i++)
-          if (Array.isArray(s[i]) && s[i][0] === 'global.set' && Array.isArray(s[i][2]) && s[i][2][0] === 'i32.const')
-            s[i][2][1] = `${heapBase}`
   }
 }
 
+/**
+ * Phase: strip the Eisel-Lemire table when it is dead.
+ *
+ * pullStdlib injects the ~2 KB power-of-10 table whenever `__dec_to_f64` is *reachable*,
+ * but that over-counts: a dead inlined helper's `arr[i] | 0` on an untyped param pulls
+ * `__to_num` → `__dec_to_f64`, so the table lands even in a module no live code parses
+ * decimals in. watr later treeshakes the dead function + its `$__el_tbl` global, but it
+ * does NOT treeshake the data segment — so the orphaned table bloated every module ~2 KB.
+ *
+ * This runs LAST (after every lowering has emitted its call/ref.func — doing it earlier is
+ * unsound: refs like `util.clone` are emitted *after* pullStdlib), so a mark-sweep from the
+ * real roots (inline-exported funcs, __start, the closure table, globals/tags/table) gives
+ * EXACT liveness. If `__dec_to_f64` is dead, truncate the table from the data tail (it is
+ * the last append — see pullStdlib). DATA only: the dead function + global are left for
+ * watr, which already removes them. Keeps correctly-rounded decimal parsing wherever it is
+ * genuinely live (parseFloat, the self-host compiler's `Number()` on source literals).
+ */
+export function stripDeadElTable(sec) {
+  if (!ctx.runtime.elTableLen) return
+  const byName = new Map()
+  for (const arr of [sec.funcs, sec.stdlib, sec.start])
+    for (const f of arr || []) if (Array.isArray(f) && f[0] === 'func' && typeof f[1] === 'string') byName.set(f[1], f)
+  const live = new Set(), work = []
+  const mark = (ref) => { if (typeof ref === 'string' && byName.has(ref) && !live.has(ref)) { live.add(ref); work.push(ref) } }
+  const scan = (n) => {
+    if (!Array.isArray(n)) return
+    if ((n[0] === 'call' || n[0] === 'return_call' || n[0] === 'ref.func') && typeof n[1] === 'string') mark(n[1])
+    for (const c of n) scan(c)
+  }
+  for (const f of sec.funcs) if (f.some(el => Array.isArray(el) && el[0] === 'export')) mark(f[1])
+  for (const f of sec.start) scan(f)
+  for (const part of [sec.elem, sec.globals, sec.tags, sec.table]) for (const n of part || []) {
+    if (!Array.isArray(n)) continue
+    for (const c of n) { if (typeof c === 'string' && c[0] === '$') mark(c); else scan(c) }
+  }
+  while (work.length) scan(byName.get(work.pop()))
+  if (live.has('$__dec_to_f64')) return   // genuinely parses decimals at runtime — keep it
+  ctx.runtime.data = ctx.runtime.data.slice(0, ctx.runtime.data.length - ctx.runtime.elTableLen)
+  ctx.runtime.elTableLen = 0
+}
+
 /**
  * Phase: strip static-data prefix.
  */

package/src/widen.js

@@ -0,0 +1,21 @@
+/**
+ * Numeric widening thresholds — the SINGLE SOURCE for "when does an i32 arithmetic
+ * op stay i32 vs widen to f64", shared by the two phases that must agree:
+ *   • emit.js  DECIDES  — emits `i32.mul`/`i32.add` or widens to `f64.mul`/`f64.add`
+ *   • type.js  MIRRORS  — exprType predicts the same i32/f64 so locals are typed right
+ *
+ * SOUNDNESS INVARIANT (one-way, unforgiving): exprType's i32 verdict must be a SUBSET
+ * of emit's — exprType may answer i32 only where emit DEFINITELY produces i32. If type
+ * says i32 but emit yields f64, the result is `trunc_sat`-narrowed back to i32 → silent
+ * miscompile. The two predicates can't share a function (emit reads IR values via
+ * isLit/maskBound, type reads AST via staticValue), but they MUST share this threshold,
+ * or a future edit to one silently drifts the other out of the safe subset.
+ *
+ * @module widen
+ */
+
+// JS `*` is an f64 multiply; `i32.mul` agrees only while the exact product stays
+// f64-exact (|product| ≤ 2^53). Against the full i32 range (2^31) of one operand, the
+// other must be bounded |v| ≤ 2^22 for the product to hold within 2^53 — so a literal
+// or provably-masked operand of that magnitude keeps the multiply on `i32.mul`.
+export const FITS_I32_MAX = 0x400000  // 2^22