jz 0.4.0 → 0.5.0

package/src/narrow.js

@@ -8,17 +8,22 @@
  */
 
 import { ctx } from './ctx.js'
-import { isLiteralStr } from './ir.js'
+import { isLiteralStr, I32_MIN, I32_MAX } from './ir.js'
 import {
   VAL,
-  analyzeBody, analyzeLocals,
-  callerParamFactMap, clearStickyNull, ensureParamRep, mergeParamFact,
-  exprType, findMutations, hasBareReturn, inferArgArrElemSchema,
-  inferArgArrElemValType, inferArgSchema, inferArgType, inferArgTypedCtor,
+  analyzeBody,
+  paramFactsOf,
+  exprType, findMutations, hasBareReturn,
   invalidateLocalsCache, invalidateValTypesCache, isBlockBody, alwaysReturns,
   narrowReturnArrayElems, observeProgramSlots, returnExprs, staticObjectProps,
+  scanBoundedLoops,
   typedElemAux, typedElemCtor, ctorFromElemAux, valTypeOf,
 } from './analyze.js'
+import {
+  clearStickyNull, ensureParamRep, mergeParamFact,
+  inferArrElemSchema, inferArrElemValType,
+  inferSchemaId, inferValType, inferTypedCtor,
+} from './infer.js'
 
 const PTR_ABI_KINDS = new Set([VAL.OBJECT, VAL.SET, VAL.MAP, VAL.BUFFER])
 
@@ -197,21 +202,245 @@ function refreshCallerLocals(callerCtx) {
     // this, post-G `refreshCallerLocals` still walks bodies with arr untyped, the
     // length stays f64, and any callee taking that length never gets an i32 param
     // (heapsort→siftDown's `end`). analyzeFuncForEmit re-seeds + re-invalidates at
-    // emit time, so this transient repByLocal doesn't leak past narrowing.
-    ctx.func.repByLocal = new Map()
-    for (const p of func.sig.params) if (p.ptrKind != null) ctx.func.repByLocal.set(p.name, { val: p.ptrKind })
+    // emit time, so this transient localReps doesn't leak past narrowing.
+    ctx.func.localReps = new Map()
+    for (const p of func.sig.params) if (p.ptrKind != null) ctx.func.localReps.set(p.name, { val: p.ptrKind })
     invalidateLocalsCache(func.body)
-    const fresh = analyzeLocals(func.body)
+    const fresh = analyzeBody(func.body).locals
     for (const p of func.sig.params) if (!fresh.has(p.name)) fresh.set(p.name, p.type)
     callerCtx.get(func).callerLocals = fresh
   }
-  ctx.func.repByLocal = null
+  ctx.func.localReps = null
 }
 
 function resetParamWasmFacts(paramReps) {
   for (const m of paramReps.values()) for (const r of m.values()) r.wasm = undefined
 }
 
+/**
+ * Phase E: numeric result narrowing.
+ *
+ * For every narrowable func whose body returns only i32-typed expressions,
+ * narrow sig.results[0] to 'i32'. An *unsigned* tail flips sig.unsignedResult so
+ * the call-site rebox uses f64.convert_i32_u and preserves [0, 2^32) range.
+ * A tail is unsigned when it is a top-level `(x >>> 0)` OR a call to a function
+ * already narrowed `unsignedResult` — the latter propagates the flag through
+ * helper chains (`const u = x => (x|0)>>>0; const main = x => u(x)`), which a
+ * literal-`>>>`-only check would miss, reboxing main's result signed and
+ * silently turning `4294967295` into `-1`.
+ *
+ * Sign must be consistent across *all* tails: the same i32 bit pattern maps to
+ * two different JS numbers under signed vs unsigned conversion, so a function
+ * mixing signed (`x|0`) and unsigned (`x>>>0`) tails cannot be reboxed with a
+ * single boundary flag. Such functions are left at f64 — the body then converts
+ * each tail with its own sign. (Pre-fix, a top-level `>>>` next to a signed tail
+ * narrowed unsigned and corrupted the signed branch.)
+ *
+ * Fixpoint: a call to another narrowed func contributes i32; iterate until
+ * stable so chains of i32-only helpers all narrow together. exprType already
+ * consults ctx.func.map for narrowed user-function results plus the
+ * Math.imul/Math.clz32/charCodeAt stdlib subset.
+ *
+ * Safe for exports — boundary wrapper restores the f64 JS ABI. `return;`
+ * (bare) is preserved as f64; multi-value / raw / value-used are skipped by
+ * the narrowable filter.
+ */
+function narrowI32Results(funcs) {
+  // A return tail is unsigned-valued when it is a top-level `>>>` or a call to
+  // a function already proven unsignedResult. Other i32 tails are signed.
+  const isUnsignedTail = (e) => Array.isArray(e) && (
+    e[0] === '>>>' ||
+    (e[0] === '()' && typeof e[1] === 'string' && ctx.func.map?.get(e[1])?.sig?.unsignedResult === true)
+  )
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const func of funcs) {
+      if (func.sig.results[0] === 'i32') continue
+      const body = func.body
+      if (isBlockBody(body) && hasBareReturn(body)) continue
+      const exprs = returnExprs(body)
+      if (!exprs.length) continue
+      const savedCurrent = ctx.func.current
+      ctx.func.current = func.sig
+      const locals = isBlockBody(body) ? analyzeBody(body).locals : new Map()
+      for (const p of func.sig.params) if (!locals.has(p.name)) locals.set(p.name, p.type)
+      const allI32 = exprs.every(e => exprType(e, locals) === 'i32')
+      const anyUnsigned = exprs.some(isUnsignedTail)
+      const allUnsigned = exprs.every(isUnsignedTail)
+      ctx.func.current = savedCurrent
+      // Narrow only when sign is consistent (all-signed or all-unsigned tails).
+      if (allI32 && (!anyUnsigned || allUnsigned)) {
+        func.sig.results = ['i32']
+        if (allUnsigned) func.sig.unsignedResult = true
+        changed = true
+      }
+    }
+  }
+}
+
+/**
+ * Phase E2: VAL-kind result inference.
+ *
+ * When every return-tail resolves to the same VAL.* kind, record it on
+ * func.valResult so call-site valTypeOf inherits it (enables static dispatch
+ * on .length / [i] / .prop through the call chain). Fixpoint propagates
+ * through helper chains. Exports are safe — same boundary-wrapper guarantee
+ * as numeric narrowing.
+ */
+function narrowValResults(funcs) {
+  const valTypeOfWithCalls = (expr, localValTypes) => {
+    if (expr == null) return null
+    if (typeof expr === 'string') return localValTypes?.get(expr) || ctx.scope.globalValTypes?.get(expr) || null
+    if (!Array.isArray(expr)) return valTypeOf(expr)
+    const [op, ...args] = expr
+    if (op === '()' && typeof args[0] === 'string') {
+      const f = ctx.func.map.get(args[0])
+      if (f?.valResult) return f.valResult
+    }
+    if (op === '?:') {
+      const a = valTypeOfWithCalls(args[1], localValTypes), b = valTypeOfWithCalls(args[2], localValTypes)
+      return a && a === b ? a : null
+    }
+    if (op === '&&' || op === '||') {
+      const a = valTypeOfWithCalls(args[0], localValTypes), b = valTypeOfWithCalls(args[1], localValTypes)
+      return a && a === b ? a : null
+    }
+    return valTypeOf(expr)
+  }
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const func of funcs) {
+      if (func.valResult) continue
+      const body = func.body
+      const isBlock = isBlockBody(body)
+      if (isBlock && hasBareReturn(body)) continue
+      const exprs = returnExprs(body)
+      if (!exprs.length) continue
+      const localValTypes = isBlock ? analyzeBody(body).valTypes : new Map()
+      const vt0 = valTypeOfWithCalls(exprs[0], localValTypes)
+      if (!vt0) continue
+      const allSame = exprs.every(e => valTypeOfWithCalls(e, localValTypes) === vt0)
+      if (allSame) { func.valResult = vt0; changed = true }
+    }
+  }
+}
+
+const PTR_RESULT_KINDS_NOAUX = new Set([VAL.SET, VAL.MAP, VAL.BUFFER])
+
+// Per-body local elemAux map: scans `let/const x = new TypedArray(...)` decls so a return
+// like `let a = new Float64Array(...); return a` resolves to a constant aux.
+function localElemAuxMap(body) {
+  const m = new Map()
+  const walk = (n) => {
+    if (!Array.isArray(n)) return
+    const op = n[0]
+    if (op === '=>') return
+    if ((op === 'let' || op === 'const') && n.length > 1) {
+      for (let i = 1; i < n.length; i++) {
+        const a = n[i]
+        if (Array.isArray(a) && a[0] === '=' && typeof a[1] === 'string') {
+          const aux = typedElemAux(typedElemCtor(a[2]))
+          if (aux != null) m.set(a[1], aux)
+        }
+      }
+    }
+    for (let i = 1; i < n.length; i++) walk(n[i])
+  }
+  walk(body)
+  return m
+}
+
+function typedAuxOfReturn(expr, localElemMap) {
+  if (typeof expr === 'string') return localElemMap?.get(expr) ?? null
+  if (!Array.isArray(expr)) return null
+  const [op, ...args] = expr
+  if (op === '()' && typeof args[0] === 'string') {
+    if (args[0].startsWith('new.')) {
+      const ctor = typedElemCtor(expr)
+      return ctor != null ? typedElemAux(ctor) : null
+    }
+    const f = ctx.func.map.get(args[0])
+    if (f?.valResult === VAL.TYPED && f.sig.ptrAux != null) return f.sig.ptrAux
+    return null
+  }
+  if (op === '?:') {
+    const a = typedAuxOfReturn(args[1], localElemMap)
+    const b = typedAuxOfReturn(args[2], localElemMap)
+    return a != null && a === b ? a : null
+  }
+  if (op === '&&' || op === '||') {
+    const a = typedAuxOfReturn(args[0], localElemMap)
+    const b = typedAuxOfReturn(args[1], localElemMap)
+    return a != null && a === b ? a : null
+  }
+  return null
+}
+
+/**
+ * Phase E3: pointer result narrowing.
+ *
+ * For narrowable funcs whose valResult is a non-ambiguous pointer kind with a
+ * constant aux, narrow sig.results[0] from f64 to i32 and tag sig.ptrKind/.ptrAux.
+ * Eliminates the f64.reinterpret_i64+i64.or rebox at every return and the
+ * matching unbox dance at every call site that uses the value as a pointer.
+ *
+ * Aux strategy:
+ *   - SET/MAP/BUFFER: aux always 0 — no per-callsite preservation needed.
+ *   - OBJECT: aux is schema-id; narrow only when all return exprs share a constant
+ *     schema (literal, schemaId-bound param, module-bound var, or call to another
+ *     OBJECT-narrowed func). Caller picks aux up via callIR.ptrAux → readVar →
+ *     localReps.schemaId, restoring property-slot dispatch through the call boundary.
+ *   - TYPED: aux is elem-type; require all return tails to agree on a single aux.
+ *
+ * Skipped: ARRAY forwards on realloc, STRING dual-encoded SSO/heap, CLOSURE
+ * (aux carries funcIdx for call_indirect). Body must guarantee-return so the
+ * fallthrough fallback can't produce a wrong-typed undef.
+ *
+ * Fixpoint: a chain `outer → inner → {a,b}` needs inner to narrow first so
+ * outer's call to inner contributes a known schema-id.
+ */
+function narrowPointerResults(funcs, paramReps) {
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const func of funcs) {
+      if (!func.valResult) continue
+      if (func.sig.results[0] !== 'f64') continue
+      const isBlock = isBlockBody(func.body)
+      if (isBlock && !alwaysReturns(func.body)) continue
+      if (PTR_RESULT_KINDS_NOAUX.has(func.valResult)) {
+        func.sig.results = ['i32']
+        func.sig.ptrKind = func.valResult
+        changed = true
+        continue
+      }
+      const exprs = returnExprs(func.body)
+      if (!exprs.length) continue
+      if (func.valResult === VAL.OBJECT) {
+        const paramSchemasMap = paramFactsOf(paramReps, func, 'schemaId')
+        const sid0 = inferSchemaId(exprs[0], paramSchemasMap)
+        if (sid0 == null) continue
+        if (!exprs.every(e => inferSchemaId(e, paramSchemasMap) === sid0)) continue
+        func.sig.results = ['i32']
+        func.sig.ptrKind = VAL.OBJECT
+        func.sig.ptrAux = sid0
+        changed = true
+      } else if (func.valResult === VAL.TYPED) {
+        const localMap = isBlock ? localElemAuxMap(func.body) : null
+        const aux0 = typedAuxOfReturn(exprs[0], localMap)
+        if (aux0 == null) continue
+        if (!exprs.every(e => typedAuxOfReturn(e, localMap) === aux0)) continue
+        func.sig.results = ['i32']
+        func.sig.ptrKind = VAL.TYPED
+        func.sig.ptrAux = aux0
+        changed = true
+      }
+    }
+  }
+}
+
 function createPhaseState() {
   const callerCtx = buildCallerCtx()
   const elemCtx = new Map()
@@ -269,13 +498,13 @@ export default function narrowSignatures(programFacts, ast) {
   // D: Call-site type propagation — infer param types from how functions are called.
   // Drives off `callSites` collected during the ProgramFacts walk; no AST re-walking.
   // For non-exported internal functions, if all call sites agree on a param's type,
-  // seed the param's val rep (ctx.func.repByLocal) during per-function compilation.
+  // seed the param's val rep (ctx.func.localReps) during per-function compilation.
   // Also infer i32/f64 WASM type — when all call sites pass i32 for a param, specialize
   // sig.params[k].type to i32 (no default, no rest, not exported, not value-used).
   // Also propagate schema ID — when all call sites pass objects with the same schema,
   // bind the callee's param to that schema so `p.x` becomes a direct slot load.
-  // Inference helpers (inferArgType/inferArgSchema/inferArgArr*/inferArgTypedCtor)
-  // live in analyze.js — pure AST→fact resolvers shared across fixpoint phases.
+  // Inference helpers (inferValType/inferSchemaId/inferArr*/inferTypedCtor)
+  // live in infer.js — pure AST→fact resolvers shared across fixpoint phases.
   // Per-caller analysis is stable across fixpoint iterations — precompute once.
   // callerCtx[null] (top-level) uses module globals for both locals and valTypes.
   const phase = createPhaseState()
@@ -286,7 +515,7 @@ export default function narrowSignatures(programFacts, ast) {
     else if (Array.isArray(arg) && arg[0] == null && typeof arg[1] === 'number') raw = arg[1]
     else if (Array.isArray(arg) && arg[0] === 'u-' && typeof arg[1] === 'number') raw = -arg[1]
     else if (typeof arg === 'string' && ctx.scope.constInts?.has(arg)) raw = ctx.scope.constInts.get(arg)
-    return (raw != null && Number.isInteger(raw) && raw >= -2147483648 && raw <= 2147483647) ? raw : null
+    return (raw != null && Number.isInteger(raw) && raw >= I32_MIN && raw <= I32_MAX) ? raw : null
   }
 
   const runCallsiteLattice = (rules) => {
@@ -303,7 +532,7 @@ export default function narrowSignatures(programFacts, ast) {
         callerLocals: ctxEntry.callerLocals,
         callerValTypes: ctxEntry.callerValTypes,
         callerParamFacts(key) {
-          if (!paramFacts.has(key)) paramFacts.set(key, callerParamFactMap(paramReps, callerFunc, key))
+          if (!paramFacts.has(key)) paramFacts.set(key, paramFactsOf(paramReps, callerFunc, key))
           return paramFacts.get(key)
         },
       }
@@ -317,13 +546,13 @@ export default function narrowSignatures(programFacts, ast) {
   }
 
   const poison = field => r => { r[field] = null }
-  // Default-aware val inference. Adds two fallbacks beyond inferArgType's
+  // Default-aware val inference. Adds two fallbacks beyond inferValType's
   // body-local `callerValTypes` lookup so a hot recursive helper like
   // `uleb(n, buffer = []) { ... return uleb(n, buffer) }` resolves the
   // recursive `buffer` arg to VAL.ARRAY (via callerParamFacts on iter 2,
   // or via the caller's own default expression on iter 1).
   const inferValAtSite = (arg, state) => {
-    const v = inferArgType(arg, state.callerValTypes)
+    const v = inferValType(arg, state.callerValTypes)
     if (v != null) return v
     if (typeof arg !== 'string') return null
     const fromParam = state.callerParamFacts('val')?.get(arg)
@@ -361,7 +590,7 @@ export default function narrowSignatures(programFacts, ast) {
         else if (r.wasm !== wt) r.wasm = null
       },
     },
-    mergeRule('schemaId', (arg, _k, state) => inferArgSchema(arg, state.callerParamFacts('schemaId'))),
+    mergeRule('schemaId', (arg, _k, state) => inferSchemaId(arg, state.callerParamFacts('schemaId'))),
     {
       missing: poison('intConst'),
       apply(r, arg, k, state) {
@@ -389,8 +618,8 @@ export default function narrowSignatures(programFacts, ast) {
     do { changed = false; runCallsiteLattice([soft]) } while (changed)
     runCallsiteLattice([mergeRule(field, infer)])
   }
-  const runArrFixpoint = () => runArrElemFixpoint('arrayElemSchema', inferArgArrElemSchema, phase.callerElems('arrElemSchemas'))
-  const runArrValTypeFixpoint = () => runArrElemFixpoint('arrayElemValType', inferArgArrElemValType, phase.callerElems('arrElemValTypes'))
+  const runArrFixpoint = () => runArrElemFixpoint('arrayElemSchema', inferArrElemSchema, phase.callerElems('arrElemSchemas'))
+  const runArrValTypeFixpoint = () => runArrElemFixpoint('arrayElemValType', inferArrElemValType, phase.callerElems('arrElemValTypes'))
   runFixpoint()
   runFixpoint()
 
@@ -418,97 +647,12 @@ export default function narrowSignatures(programFacts, ast) {
   //   - exclude rest position (array pack/unpack stays f64).
   applyPointerParamAbi(paramReps, valueUsed)
 
-  // E: Result-type monomorphization — narrow sig.results[0] to 'i32' when body only
-  // produces i32 values. Fixpoint: a call to another narrowed func now contributes i32;
-  // iterate until stable so chains of i32-only helpers all narrow together.
-  // Safety: skip exported (JS boundary preserves number semantics), value-used (closure
-  // trampolines assume f64 result), raw WAT, multi-value. `undefined` return = skip.
-  // exprType already consults ctx.func.map for narrowed user-function results
-  // (analyze.js exprType `()` branch), plus the Math.imul/Math.clz32/charCodeAt
-  // stdlib subset and primitive-op rules. Earlier we had a local shim here that
-  // shadowed exprType's stdlib rules with `return 'f64'` for any non-user call;
-  // unifying through exprType lets a single rule (math.imul → i32) flow through
-  // to mix-style helpers (`(h, x) => Math.imul(h ^ (x|0), C)`) and unblocks the
-  // E-phase result narrowing on every call site that consumes them.
-  const exprTypeWithCalls = exprType
-  // Body-driven: safe for exports — the result type is determined by what the body
-  // computes, not by what JS callers might pass. JS-visible f64 ABI is restored at
-  // the boundary via a synthesized wrapper (see synthesizeBoundaryWrappers below).
-  // Shared pool for E (numeric), E2 (valType) and E3 (ptr) narrowing — same predicate.
+  // E + E2: body-driven result-type inference. Pool of narrowable funcs is shared
+  // across the i32/VAL/pointer passes — same predicate (non-raw, non-value-used,
+  // single-result).
   const funcsWithNarrowableResult = narrowableFuncs(valueUsed)
-  let changed = true
-  while (changed) {
-    changed = false
-    for (const func of funcsWithNarrowableResult) {
-      if (func.sig.results[0] === 'i32') continue
-      const body = func.body
-      // Bare `return;` produces undef (f64) — narrowing to i32 would lose that.
-      if (isBlockBody(body) && hasBareReturn(body)) continue
-      const exprs = returnExprs(body)
-      if (!exprs.length) continue
-      // Narrow result to i32 when every return-tail types as i32 (incl. bitwise ops, `|0`,
-      // and `>>>`). When ANY tail is `>>>` (unsigned uint32 idiom) we still narrow, but tag
-      // `sig.unsignedResult` so the call-site rebox uses `f64.convert_i32_u` — preserving
-      // the [0, 2^32) range that `(x >>> 0)` carries through hash/CRC finalizers.
-      const anyUnsigned = exprs.some(e => Array.isArray(e) && e[0] === '>>>')
-      const savedCurrent = ctx.func.current
-      ctx.func.current = func.sig
-      const locals = isBlockBody(body) ? analyzeLocals(body) : new Map()
-      for (const p of func.sig.params) if (!locals.has(p.name)) locals.set(p.name, p.type)
-      const allI32 = exprs.every(e => exprTypeWithCalls(e, locals) === 'i32')
-      ctx.func.current = savedCurrent
-      if (allI32) {
-        func.sig.results = ['i32']
-        if (anyUnsigned) func.sig.unsignedResult = true
-        changed = true
-      }
-    }
-  }
-
-  // E2: VAL-type result inference — if a function always returns the same VAL kind,
-  // record it so callers inherit that type (enables static dispatch on .length, .[],
-  // .prop through a call chain). Fixpoint propagates through helper chains.
-  // Safety: skip exported (host sees raw f64), value-used (indirect call signature).
-  // Shim so calls to already-typed funcs contribute their result type.
-  const valTypeOfWithCalls = (expr, localValTypes) => {
-    if (expr == null) return null
-    if (typeof expr === 'string') return localValTypes?.get(expr) || ctx.scope.globalValTypes?.get(expr) || null
-    if (!Array.isArray(expr)) return valTypeOf(expr)
-    const [op, ...args] = expr
-    if (op === '()' && typeof args[0] === 'string') {
-      const f = ctx.func.map.get(args[0])
-      if (f?.valResult) return f.valResult
-    }
-    if (op === '?:') {
-      const a = valTypeOfWithCalls(args[1], localValTypes), b = valTypeOfWithCalls(args[2], localValTypes)
-      return a && a === b ? a : null
-    }
-    if (op === '&&' || op === '||') {
-      const a = valTypeOfWithCalls(args[0], localValTypes), b = valTypeOfWithCalls(args[1], localValTypes)
-      return a && a === b ? a : null
-    }
-    return valTypeOf(expr)
-  }
-  // Body-driven valResult inference: same safety analysis as numeric narrowing
-  // above — exports OK because boundary wrapper restores f64 ABI for JS callers.
-  changed = true
-  while (changed) {
-    changed = false
-    for (const func of funcsWithNarrowableResult) {
-      if (func.valResult) continue
-      const body = func.body
-      const isBlock = isBlockBody(body)
-      if (isBlock && hasBareReturn(body)) continue
-      const exprs = returnExprs(body)
-      if (!exprs.length) continue
-      const localValTypes = isBlock ? analyzeBody(body).valTypes : new Map()
-      // Params of this function contribute no known VAL type yet (paramReps may help later).
-      const vt0 = valTypeOfWithCalls(exprs[0], localValTypes)
-      if (!vt0) continue
-      const allSame = exprs.every(e => valTypeOfWithCalls(e, localValTypes) === vt0)
-      if (allSame) { func.valResult = vt0; changed = true }
-    }
-  }
+  narrowI32Results(funcsWithNarrowableResult)
+  narrowValResults(funcsWithNarrowableResult)
 
   // Now that E2 set `valResult` on funcs, narrow per-func `arrayElemSchema` for
   // VAL.ARRAY-returning funcs (via push observations + call chains). Then re-run the
@@ -542,141 +686,9 @@ export default function narrowSignatures(programFacts, ast) {
   // through helper chains: `init()→main→runKernel`.
   runArrValTypeFixpoint()
   runArrValTypeFixpoint()
-  // E3: Result-type pointer narrowing — when valResult is a non-ambiguous pointer kind
-  // with constant aux, narrow sig.results[0] from f64 to i32 and tag sig.ptrKind/.ptrAux.
-  // Eliminates the f64.reinterpret_i64+i64.or rebox at every return and the
-  // i32.wrap_i64+i64.reinterpret_f64 unbox at every callsite that uses the value as a
-  // pointer (load .[], .length, .prop slot dispatch).
-  //   - SET/MAP/BUFFER: aux always 0 — no per-callsite aux preservation needed.
-  //   - OBJECT: aux is schema-id; narrow only when all return exprs share a constant
-  //     schema (literal `{a,b,c}`, schemaId-bound param, module-bound var, or call to
-  //     another OBJECT-narrowed func). Caller picks aux up via callIR.ptrAux → readVar →
-  //     repByLocal.schemaId, restoring property-slot dispatch through the call boundary.
-  // Safety: ARRAY forwards on realloc (no narrowing). STRING dual-encoded SSO/heap.
-  // CLOSURE/TYPED also carry meaningful aux — TYPED narrowing is a follow-up. Body must
-  // be a guaranteed-return form — fallthrough fallback i32.const 0 would be a valid
-  // offset 0 of the narrowed kind, not undefined.
-  const PTR_RESULT_KINDS_NOAUX = new Set([VAL.SET, VAL.MAP, VAL.BUFFER])
-  // Schema-id inference for a return expression. Returns id (number), or null if unknown
-  // / not constant. Mirrors inferArgSchema but extends with calls to already-narrowed
-  // OBJECT-result funcs (fixpoint propagation through helper chains).
-  const schemaIdOfReturn = (expr, paramSchemasMap) => {
-    if (typeof expr === 'string') {
-      if (paramSchemasMap?.has(expr)) return paramSchemasMap.get(expr)
-      if (ctx.schema.vars.has(expr)) return ctx.schema.vars.get(expr)
-      return null
-    }
-    if (!Array.isArray(expr)) return null
-    const [op, ...args] = expr
-    if (op === '{}') {
-      // Object literal: bail to null on block body, dynamic key, or spread.
-      const parsed = staticObjectProps(args)
-      return parsed ? ctx.schema.register(parsed.names) : null
-    }
-    if (op === '()' && typeof args[0] === 'string') {
-      const f = ctx.func.map.get(args[0])
-      if (f?.valResult === VAL.OBJECT && f.sig.ptrAux != null) return f.sig.ptrAux
-      return null
-    }
-    if (op === '?:') {
-      const a = schemaIdOfReturn(args[1], paramSchemasMap)
-      const b = schemaIdOfReturn(args[2], paramSchemasMap)
-      return a != null && a === b ? a : null
-    }
-    if (op === '&&' || op === '||') {
-      const a = schemaIdOfReturn(args[0], paramSchemasMap)
-      const b = schemaIdOfReturn(args[1], paramSchemasMap)
-      return a != null && a === b ? a : null
-    }
-    return null
-  }
-  // Per-body local elemAux map: scans `let/const x = new TypedArray(...)` decls so
-  // a return like `let a = new Float64Array(...); return a` resolves to a constant
-  // aux. Result calls + ?: are handled inline in typedAuxOfReturn.
-  const localElemAuxMap = (body) => {
-    const m = new Map()
-    const walk = (n) => {
-      if (!Array.isArray(n)) return
-      const op = n[0]
-      if (op === '=>') return
-      if ((op === 'let' || op === 'const') && n.length > 1) {
-        for (let i = 1; i < n.length; i++) {
-          const a = n[i]
-          if (Array.isArray(a) && a[0] === '=' && typeof a[1] === 'string') {
-            const aux = typedElemAux(typedElemCtor(a[2]))
-            if (aux != null) m.set(a[1], aux)
-          }
-        }
-      }
-      for (let i = 1; i < n.length; i++) walk(n[i])
-    }
-    walk(body)
-    return m
-  }
-  const typedAuxOfReturn = (expr, localElemMap) => {
-    if (typeof expr === 'string') return localElemMap?.get(expr) ?? null
-    if (!Array.isArray(expr)) return null
-    const [op, ...args] = expr
-    if (op === '()' && typeof args[0] === 'string') {
-      if (args[0].startsWith('new.')) {
-        const ctor = typedElemCtor(expr)
-        return ctor != null ? typedElemAux(ctor) : null
-      }
-      const f = ctx.func.map.get(args[0])
-      if (f?.valResult === VAL.TYPED && f.sig.ptrAux != null) return f.sig.ptrAux
-      return null
-    }
-    if (op === '?:') {
-      const a = typedAuxOfReturn(args[1], localElemMap)
-      const b = typedAuxOfReturn(args[2], localElemMap)
-      return a != null && a === b ? a : null
-    }
-    if (op === '&&' || op === '||') {
-      const a = typedAuxOfReturn(args[0], localElemMap)
-      const b = typedAuxOfReturn(args[1], localElemMap)
-      return a != null && a === b ? a : null
-    }
-    return null
-  }
-  // Fixpoint: a chain `outer → inner → {a,b}` needs inner to narrow first so outer's
-  // call to inner contributes a known schema-id.
-  let narrowChanged = true
-  while (narrowChanged) {
-    narrowChanged = false
-    for (const func of funcsWithNarrowableResult) {
-      if (!func.valResult) continue
-      if (func.sig.results[0] !== 'f64') continue
-      const isBlock = isBlockBody(func.body)
-      if (isBlock && !alwaysReturns(func.body)) continue
-      if (PTR_RESULT_KINDS_NOAUX.has(func.valResult)) {
-        func.sig.results = ['i32']
-        func.sig.ptrKind = func.valResult
-        narrowChanged = true
-        continue
-      }
-      const exprs = returnExprs(func.body)
-      if (!exprs.length) continue
-      if (func.valResult === VAL.OBJECT) {
-        const paramSchemasMap = callerParamFactMap(paramReps, func, 'schemaId')
-        const sid0 = schemaIdOfReturn(exprs[0], paramSchemasMap)
-        if (sid0 == null) continue
-        if (!exprs.every(e => schemaIdOfReturn(e, paramSchemasMap) === sid0)) continue
-        func.sig.results = ['i32']
-        func.sig.ptrKind = VAL.OBJECT
-        func.sig.ptrAux = sid0
-        narrowChanged = true
-      } else if (func.valResult === VAL.TYPED) {
-        const localMap = isBlock ? localElemAuxMap(func.body) : null
-        const aux0 = typedAuxOfReturn(exprs[0], localMap)
-        if (aux0 == null) continue
-        if (!exprs.every(e => typedAuxOfReturn(e, localMap) === aux0)) continue
-        func.sig.results = ['i32']
-        func.sig.ptrKind = VAL.TYPED
-        func.sig.ptrAux = aux0
-        narrowChanged = true
-      }
-    }
-  }
+  // E3: pointer-kind result narrowing — once valResult is set, lift the wasm
+  // return type to i32 + ptrKind/ptrAux when aux is statically resolvable.
+  narrowPointerResults(funcsWithNarrowableResult, paramReps)
 
   // F: Cross-call typed-array element ctor propagation. Runs AFTER E3 so that
   // calls to user functions returning a TYPED-narrowed pointer (with constant
@@ -685,8 +697,10 @@ export default function narrowSignatures(programFacts, ast) {
   // for their own params and `arr[i]` reads emit a direct `f64.load` instead of
   // the runtime `__is_str_key + __typed_idx` dispatch — closes the largest
   // chunk of the JS→wasm gap on f64-heavy hot loops.
-  // (Helpers `inferArgTypedCtor`/`ctorFromElemAux` live in analyze.js so the
-  //  bimorphic-typed specialization pass below can reuse them.)
+  // (Helper `inferTypedCtor` lives in src/infer.js — the call-site mirror
+  //  of body-walk evidence — and is reused by the bimorphic-typed
+  //  specialization pass below; `ctorFromElemAux` stays in analyze.js next
+  //  to its encode/decode partner.)
   // Per-caller typed-elem map, recomputed now that E3 has tagged helper sigs.
   // Cache invalidation: analyzeBody.typedElems reads `ctx.func.map.get(...).sig.ptrKind`
   // for `let x = mkInput(...)` decls; entries cached during the initial walk
@@ -697,7 +711,7 @@ export default function narrowSignatures(programFacts, ast) {
   // its own callees (e.g. if `outer(buf)` calls `inner(buf)` and we learn `buf`
   // for outer, the second pass picks it up for inner). Reuses runArrElemFixpoint
   // (same shape — field/inferFn/elemsCtxMap parameterization).
-  const runTypedFixpoint = () => runArrElemFixpoint('typedCtor', inferArgTypedCtor, callerTypedCtx)
+  const runTypedFixpoint = () => runArrElemFixpoint('typedCtor', inferTypedCtor, callerTypedCtx)
   runTypedFixpoint()
   runTypedFixpoint()
 
@@ -714,7 +728,7 @@ export default function narrowSignatures(programFacts, ast) {
   // H: Post-F/G re-fixpoint — propagates VAL kinds through bimorphic call sites
   // where ptrKind narrowed but ptrAux disagreed (e.g. `sum(f64arr)` and `sum(i32arr)`
   // → both VAL.TYPED, different ctors). Without this, callerValTypes carries no entry
-  // for caller's params, so inferArgType returns null and paramReps[callee][k].val is
+  // for caller's params, so inferValType returns null and paramReps[callee][k].val is
   // sticky null. With ptrKind enriching callerValTypes, sum's arr gets val=TYPED in
   // its rep, letting array.js skip __is_str_key + __str_idx dispatch on `arr[i]`.
   enrichCallerValTypesFromPointerParams(callerCtx)
@@ -742,6 +756,174 @@ export default function narrowSignatures(programFacts, ast) {
   // so r.wasm flips to 'i32' here — but narrowing now breaks the clone path
   // that still needs to mint per-ctor sigs with ptrKind=TYPED, ptrAux=ctor-aux.
   applyI32ParamSpecialization(paramReps, valueUsed, { skipTyped: true })
+
+  // J: jsstring boundary opt-in — for exported funcs with a string param whose
+  // every use is mappable to a wasm:js-string builtin, flip the param's wasm
+  // slot from f64 (nanbox SSO carrier) to externref so the JS host passes the
+  // native string directly. Zero copy, zero transcoding. See applyJsstringBoundaryCarrier.
+  if (jsstringEnabled()) applyJsstringBoundaryCarrier(paramReps, valueUsed)
+}
+
+/** Gate the jsstring opt-in: enabled by default for JS hosts; disabled under
+ *  WASI (env imports unavailable) or when explicitly opted out via the
+ *  `optimize: { jsstring: false }` knob (used by side-by-side benchmarks). */
+function jsstringEnabled() {
+  if (ctx.transform.host === 'wasi') return false
+  if (ctx.transform.optimize?.jsstring === false) return false
+  return true
+}
+
+/** Phase J standalone: runs even when `canSkipWholeProgramNarrowing` short-circuits
+ *  the main narrow pass. The check is body-local and export-boundary-only, so call-
+ *  site lattice isn't needed; just guard on host and run the use-scan. */
+export function applyJsstringBoundaryCarrierStandalone(programFacts) {
+  if (!jsstringEnabled()) return
+  applyJsstringBoundaryCarrier(new Map(), programFacts.valueUsed)
+}
+
+/**
+ * Body-local boolean-result inference. `narrowValResults` is the general (any
+ * VAL.*) pass, but it lives inside whole-program narrowing, which is skipped for
+ * trivial leaf modules (no call sites). A boolean result is the one kind whose
+ * internal carrier (the 0/1 number) differs from its host-boundary carrier (the
+ * TRUE_NAN/FALSE_NAN atom), so an exported `(a) => a > 2` still needs its boundary
+ * box even on the skip path. This pass only ever *sets* valResult = VAL.BOOL, so
+ * it is safe to run unconditionally — pointer/array/number results are untouched.
+ */
+export function narrowBoolResults() {
+  for (const func of ctx.func.list) {
+    if (func.raw || func.valResult || !func.body || func.sig.results.length !== 1) continue
+    const body = func.body
+    const isBlock = isBlockBody(body)
+    if (isBlock && hasBareReturn(body)) continue
+    const exprs = returnExprs(body)
+    if (!exprs.length) continue
+    const localValTypes = isBlock ? analyzeBody(body).valTypes : null
+    const vt = e => typeof e === 'string'
+      ? (localValTypes?.get(e) || ctx.scope.globalValTypes?.get(e) || null)
+      : valTypeOf(e)
+    if (exprs.every(e => vt(e) === VAL.BOOL)) func.valResult = VAL.BOOL
+  }
+}
+
+// ── jsstring boundary carrier ───────────────────────────────────────────────
+//
+// Mappable use of an exported string param:
+//   - `s.length`               → wasm:js-string.length
+//   - `s.charCodeAt(idx)`      → wasm:js-string.charCodeAt — but ONLY when the
+//                                index is provably in-bounds (scanBoundedLoops).
+//                                The builtin traps on OOB; JS semantics return
+//                                NaN. The only way to preserve JS semantics with
+//                                zero overhead is to refuse non-bounded use.
+// Anything else (concat, indexing `s[i]`, regex, hash key, passing to a non-
+// externref param, reassignment, closure capture, `==` with anything, …) is a
+// fallback trigger and disqualifies the param.
+
+const JSS_OK_PROPS = new Set(['length', 'charCodeAt'])
+
+/**
+ * Decide whether `name` (an exported func's STRING-shaped param) can flow
+ * through the boundary as `externref`. Walk the body once: every leaf
+ * occurrence of `name` must be the receiver of `.length` (always safe) or
+ * `.charCodeAt` whose callee node lives in `safeCC` (provably bounded).
+ * Reassignment / `++` / `--` / closure capture all reject conservatively.
+ *
+ * Returns `{ ok, stringDiscriminating }` — `stringDiscriminating` is true iff
+ * we saw at least one string-only use (`.charCodeAt`); the caller uses this
+ * to gate on whether the body actually proves the param is a string, since
+ * `.length` alone is polymorphic across string/array/typed-array.
+ */
+function paramAllUsesJsstringMappable(body, name, safeCC) {
+  if (body == null) return { ok: false, stringDiscriminating: false }
+  let ok = true
+  let stringDiscriminating = false
+  const walk = (node) => {
+    if (!ok) return
+    if (typeof node === 'string') {
+      // A bare reference to the param outside an eligible `[., name, prop]`
+      // callee slot is a fallback trigger — the param escaped to a non-
+      // mappable use.
+      if (node === name) ok = false
+      return
+    }
+    if (!Array.isArray(node)) return
+    const op = node[0]
+    if (op === '=>') {
+      // Nested arrow may shadow `name` with its own param; if it doesn't, any
+      // capture of the outer `name` is an escape we can't track — reject.
+      const params = node[1]
+      const shadowed = Array.isArray(params)
+        ? params.some(p => (typeof p === 'string' && p === name) ||
+                           (Array.isArray(p) && p[1] === name))
+        : params === name
+      if (!shadowed) ok = false
+      return
+    }
+    if ((op === '=' || op === '+=' || op === '-=' || op === '*=' || op === '/=' ||
+         op === '%=' || op === '&=' || op === '|=' || op === '^=' ||
+         op === '>>=' || op === '<<=' || op === '>>>=' ||
+         op === '||=' || op === '&&=' || op === '??=' ||
+         op === '++' || op === '--') && node[1] === name) {
+      ok = false
+      return
+    }
+    if (op === '.' && node[1] === name && JSS_OK_PROPS.has(node[2])) {
+      // .length is always safe but polymorphic across string/array/typed.
+      // .charCodeAt is only safe when the loop-bounds analysis proves the
+      // index in-bounds (this dotted callee node is exactly the one collected
+      // by scanBoundedLoops) — but it IS string-discriminating.
+      if (node[2] === 'length') return
+      if (safeCC.has(node)) { stringDiscriminating = true; return }
+      ok = false
+      return
+    }
+    // For `['()', callee, ...args]` with callee = ['.', name, 'charCodeAt'],
+    // `name` is in the callee receiver slot (validated by the branch above).
+    // The `.length` case is just a member read — no `()` wrapping.
+    for (let i = 1; i < node.length; i++) walk(node[i])
+  }
+  walk(body)
+  return { ok, stringDiscriminating }
+}
+
+function applyJsstringBoundaryCarrier(paramReps, valueUsed) {
+  for (const func of ctx.func.list) {
+    if (func.raw || !func.exported) continue
+    if (!func.body) continue
+    if (func.rest) continue                          // rest position stays packed-array
+    if (valueUsed.has(func.name)) continue           // value-used → callers may pass non-string
+    // Pre-compute the in-bounds .charCodeAt callee nodes once per body.
+    const safeCC = new Set()
+    scanBoundedLoops(func.body, safeCC)
+    const reps = paramReps.get(func.name)
+    for (let k = 0; k < func.sig.params.length; k++) {
+      const p = func.sig.params[k]
+      if (p.type !== 'f64' || p.ptrKind != null) continue
+      // String-literal defaults (`s = ''`, `s = 'default'`) are both string-
+      // discrimination proof AND substituted JS-side by the interop wrapper —
+      // see `jz:extparam` def field. Non-string defaults still disqualify:
+      // the wasm side has no way to materialise an arbitrary externref default
+      // at boundary-check time without a host import.
+      const defVal = func.defaults?.[p.name]
+      if (defVal != null && !isLiteralStr(defVal)) continue
+      const { ok: usesOk, stringDiscriminating } = paramAllUsesJsstringMappable(func.body, p.name, safeCC)
+      if (!usesOk) continue
+      const r = reps?.get(k)
+      // Skip if any rep says non-STRING (`r.val` set to ARRAY/TYPED at any
+      // call site rules out jsstring).
+      if (r && r.val != null && r.val !== VAL.STRING) continue
+      // Discrimination signal: either a string-discriminating body use
+      // (`.charCodeAt`), a call-site proof (`r.val === STRING`), or an
+      // explicit string-literal default (the source intent declaration).
+      const hasStringDefault = defVal != null && isLiteralStr(defVal)
+      if (!stringDiscriminating && r?.val !== VAL.STRING && !hasStringDefault) continue
+      p.type = 'externref'
+      p.jsstring = true
+      // Record the literal default so compile.js can omit wasm-side substitution
+      // (the JS-side interop wrapper applies the default on `undefined`).
+      if (hasStringDefault) p.jsstringDefault = defVal[1]
+    }
+  }
 }
 
 /**
@@ -789,7 +971,7 @@ export function specializeBimorphicTyped(programFacts) {
   // (so transitive `sum(arr)` inside a func that took `arr` from above resolves).
   const callerTypedParamsCtx = new Map()
   for (const func of ctx.func.list) {
-    const m = callerParamFactMap(paramReps, func, 'typedCtor') || null
+    const m = paramFactsOf(paramReps, func, 'typedCtor') || null
     let acc = m
     if (func.sig?.params) for (const p of func.sig.params) {
       if (p.ptrKind === VAL.TYPED && p.ptrAux != null) {
@@ -834,7 +1016,7 @@ export function specializeBimorphicTyped(programFacts) {
       const combo = []
       for (const k of bimorphic) {
         if (k >= site.argList.length) { abort = true; break }
-        const c = inferArgTypedCtor(site.argList[k], callerTypedElems, callerTypedParams)
+        const c = inferTypedCtor(site.argList[k], callerTypedElems, callerTypedParams)
         if (c == null || typedElemAux(c) == null) { abort = true; break }
         combo.push(c)
       }