jz 0.5.0 → 0.6.0

package/src/{narrow.js → compile/narrow.js}

@@ -7,26 +7,29 @@
  * function `sig` records change.
  */
 
-import { ctx } from './ctx.js'
-import { isLiteralStr, I32_MIN, I32_MAX } from './ir.js'
+import { ctx, warn } from '../ctx.js'
+import { isBlockBody, alwaysReturns, hasBareReturn, returnExprs } from '../ast.js'
+import { isLiteralStr, I32_MIN, I32_MAX } from '../ir.js'
 import {
-  VAL,
-  analyzeBody,
-  paramFactsOf,
-  exprType, findMutations, hasBareReturn,
-  invalidateLocalsCache, invalidateValTypesCache, isBlockBody, alwaysReturns,
-  narrowReturnArrayElems, observeProgramSlots, returnExprs, staticObjectProps,
-  scanBoundedLoops,
-  typedElemAux, typedElemCtor, ctorFromElemAux, valTypeOf,
+  analyzeBody, findMutations, invalidateLocalsCache,
 } from './analyze.js'
+import { staticObjectProps } from '../static.js'
+import { scanBoundedLoops, exprType, typedElemCtor } from '../type.js'
+import { typedElemAux, ctorFromElemAux } from '../../layout.js'
+import { observeProgramSlots } from './program-facts.js'
+import { valTypeOf } from '../kind.js'
+import { VAL, updateRep } from '../reps.js'
+import {
+  paramFactsOf, ensureParamRep, mergeParamFact,
+} from '../param-reps.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])
 
+
 function filterLiveCallSites(callSites, valueUsed) {
   if (!callSites.length) return
 
@@ -82,11 +85,12 @@ function applyI32ParamSpecialization(paramReps, valueUsed, { skipTyped = false }
     if (!reps) continue
     const restIdx = func.rest ? func.sig.params.length - 1 : -1
     for (const [k, r] of reps) {
-      if (r.wasm !== 'i32' || k === restIdx) continue
-      if (k >= func.sig.params.length) continue
+      if (k === restIdx || k >= func.sig.params.length) continue
       const p = func.sig.params[k]
-      if (p.type === 'i32') continue
       if (func.defaults?.[p.name] != null) continue
+      // SIMD: a param passed a v128 (lane vector) at every call site is a v128 param.
+      if (r.wasm === 'v128') { p.type = 'v128'; continue }
+      if (r.wasm !== 'i32' || p.type === 'i32') continue
       if (skipTyped && r.val === VAL.TYPED) continue
       p.type = 'i32'
     }
@@ -115,21 +119,25 @@ function validateIntConstParams(paramReps, valueUsed) {
   }
 }
 
-function applyPointerParamAbi(paramReps, valueUsed) {
+function applyPointerParamAbi(paramReps, valueUsed, hardParamVal) {
   for (const func of ctx.func.list) {
     if (func.exported || func.raw || valueUsed.has(func.name)) continue
     const reps = paramReps.get(func.name)
     if (!reps) continue
     const restIdx = func.rest ? func.sig.params.length - 1 : -1
-    for (const [k, r] of reps) {
-      if (!PTR_ABI_KINDS.has(r.val)) continue
+    for (const [k] of reps) {
+      // Re-fold call sites HARD (the shared val lattice is soft, so r.val may be a
+      // partial consensus from typed sites alone) — only specialize when every site
+      // proves the same pointer kind.
+      const hv = hardParamVal(func.name, k)
+      if (!PTR_ABI_KINDS.has(hv)) continue
       if (k === restIdx) continue
       if (k >= func.sig.params.length) continue
       const p = func.sig.params[k]
       if (p.type === 'i32') continue
       if (func.defaults?.[p.name] != null) continue
       p.type = 'i32'
-      p.ptrKind = r.val
+      p.ptrKind = hv
     }
   }
 }
@@ -256,7 +264,7 @@ function narrowI32Results(funcs) {
   while (changed) {
     changed = false
     for (const func of funcs) {
-      if (func.sig.results[0] === 'i32') continue
+      if (func.sig.results[0] === 'i32' || func.sig.results[0] === 'v128') continue
       const body = func.body
       if (isBlockBody(body) && hasBareReturn(body)) continue
       const exprs = returnExprs(body)
@@ -265,12 +273,16 @@ function narrowI32Results(funcs) {
       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 allV128 = exprs.every(e => exprType(e, locals) === 'v128')
+      const allI32 = !allV128 && 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)) {
+      // SIMD: every tail returns a lane vector → v128 result.
+      if (allV128) {
+        func.sig.results = ['v128']
+        changed = true
+      } else if (allI32 && (!anyUnsigned || allUnsigned)) {   // sign-consistent i32 tails
         func.sig.results = ['i32']
         if (allUnsigned) func.sig.unsignedResult = true
         changed = true
@@ -401,11 +413,47 @@ function typedAuxOfReturn(expr, localElemMap) {
  * Fixpoint: a chain `outer → inner → {a,b}` needs inner to narrow first so
  * outer's call to inner contributes a known schema-id.
  */
+/** A function whose every return is the same parameter that was pointer-ABI
+ *  narrowed to an unboxed i32 (p.ptrKind set). Returns that param, else null. */
+function passthroughPtrParam(func) {
+  const exprs = returnExprs(func.body)
+  if (!exprs.length) return null
+  const name = exprs[0]
+  if (typeof name !== 'string' || !exprs.every(e => e === name)) return null
+  return func.sig.params.find(p => p.name === name && p.ptrKind) || null
+}
+
 function narrowPointerResults(funcs, paramReps) {
   let changed = true
   while (changed) {
     changed = false
     for (const func of funcs) {
+      // Pointer pass-through: every return is the same parameter that
+      // applyPointerParamAbi narrowed to an unboxed i32 pointer. The result IS that
+      // pointer, so its sig must carry the param's ptrKind (+ schemaId for OBJECT).
+      // Without this the result is a bare i32 the caller numeric-converts
+      // (`f64.convert_i32_s`) instead of reboxing — dropping the schema-id so a
+      // later `.prop` read mis-resolves to `undefined`. narrowValResults can't see
+      // this (it reads body-locals, not param facts) and narrowI32Results steals it
+      // as a numeric i32, so resolve it here from the settled param lattice.
+      if (func.sig.ptrKind == null) {
+        const pp = passthroughPtrParam(func)
+        if (pp) {
+          const aux = pp.ptrKind === VAL.OBJECT
+            ? paramFactsOf(paramReps, func, 'schemaId')?.get(pp.name) ?? null
+            : null
+          // OBJECT needs a known schema-id to rebox; a polymorphic pass-through
+          // (conflicting schemas → null) keeps its current handling.
+          if (pp.ptrKind !== VAL.OBJECT || aux != null) {
+            func.sig.results = ['i32']
+            func.sig.ptrKind = pp.ptrKind
+            func.valResult = pp.ptrKind
+            if (aux != null) func.sig.ptrAux = aux
+            changed = true
+            continue
+          }
+        }
+      }
       if (!func.valResult) continue
       if (func.sig.results[0] !== 'f64') continue
       const isBlock = isBlockBody(func.body)
@@ -467,7 +515,7 @@ function createPhaseState() {
 
     invalidateBodyFacts() {
       for (const func of ctx.func.list) {
-        if (func.body && !func.raw) invalidateValTypesCache(func.body)
+        if (func.body && !func.raw) invalidateLocalsCache(func.body)
       }
       clearDerived()
     },
@@ -484,6 +532,67 @@ function createPhaseState() {
   }
 }
 
+const _FIELD_TO_SLICE = {
+  arrayElemSchema: 'arrElemSchemas',
+  arrayElemValType: 'arrElemValTypes',
+}
+
+/** Propagate Array<T> element facts from return paths into caller paramReps (phase G). */
+function narrowReturnArrayElems(field, paramReps, valueUsed) {
+  const sliceKey = _FIELD_TO_SLICE[field]
+  const targets = ctx.func.list.filter(f =>
+    !f.raw && !f.exported && !valueUsed.has(f.name) &&
+    f.valResult === VAL.ARRAY && f[field] == null
+  )
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const f of targets) invalidateLocalsCache(f.body)
+    for (const func of targets) {
+      if (func[field] != null) continue
+      const isBlock = isBlockBody(func.body)
+      if (isBlock && !alwaysReturns(func.body)) continue
+      const exprs = returnExprs(func.body)
+      if (!exprs.length) continue
+      const savedLocals = ctx.func.locals
+      const facts = analyzeBody(func.body)
+      ctx.func.locals = new Map(facts.locals)
+      for (const p of func.sig.params) if (!ctx.func.locals.has(p.name)) ctx.func.locals.set(p.name, p.type)
+      const localElems = facts[sliceKey]
+      ctx.func.locals = savedLocals
+      const paramElemMap = paramFactsOf(paramReps, func, field) || new Map()
+      const resolveExpr = (expr) => {
+        if (typeof expr === 'string') {
+          if (localElems.has(expr)) {
+            const v = localElems.get(expr)
+            if (v != null) return v
+          }
+          if (paramElemMap.has(expr)) return paramElemMap.get(expr)
+          return null
+        }
+        if (Array.isArray(expr) && expr[0] === '()' && typeof expr[1] === 'string') {
+          const f = ctx.func.map?.get(expr[1])
+          if (f?.[field] != null) return f[field]
+        }
+        if (Array.isArray(expr) && expr[0] === '?:') {
+          const a = resolveExpr(expr[2]), b = resolveExpr(expr[3])
+          return a != null && a === b ? a : null
+        }
+        if (Array.isArray(expr) && (expr[0] === '&&' || expr[0] === '||')) {
+          const a = resolveExpr(expr[1]), b = resolveExpr(expr[2])
+          return a != null && a === b ? a : null
+        }
+        return null
+      }
+      const v0 = resolveExpr(exprs[0])
+      if (v0 == null) continue
+      if (!exprs.every(e => resolveExpr(e) === v0)) continue
+      func[field] = v0
+      changed = true
+    }
+  }
+}
+
 export default function narrowSignatures(programFacts, ast) {
   const { callSites, valueUsed, paramReps, hasSchemaLiterals } = programFacts
 
@@ -518,29 +627,35 @@ export default function narrowSignatures(programFacts, ast) {
     return (raw != null && Number.isInteger(raw) && raw >= I32_MIN && raw <= I32_MAX) ? raw : null
   }
 
+  // Per-call-site inference context for a narrowable callee. null for call sites
+  // whose callee is exported / value-used / unknown, or whose caller has no ctx.
+  const siteState = (cs) => {
+    const { callee, argList, callerFunc } = cs
+    const func = ctx.func.map.get(callee)
+    if (!func || func.exported || valueUsed.has(callee)) return null
+    const ctxEntry = callerCtx.get(callerFunc)
+    if (!ctxEntry) return null
+    const restIdx = func.rest ? func.sig.params.length - 1 : -1
+    const paramFacts = new Map()
+    return {
+      callee, callerFunc, argList, func, restIdx,
+      callerLocals: ctxEntry.callerLocals,
+      callerValTypes: ctxEntry.callerValTypes,
+      callerParamFacts(key) {
+        if (!paramFacts.has(key)) paramFacts.set(key, paramFactsOf(paramReps, callerFunc, key))
+        return paramFacts.get(key)
+      },
+    }
+  }
   const runCallsiteLattice = (rules) => {
     for (let s = 0; s < callSites.length; s++) {
-      const { callee, argList, callerFunc } = callSites[s]
-      const func = ctx.func.map.get(callee)
-      if (!func || func.exported || valueUsed.has(callee)) continue
-      const ctxEntry = callerCtx.get(callerFunc)
-      if (!ctxEntry) continue
-      const restIdx = func.rest ? func.sig.params.length - 1 : -1
-      const paramFacts = new Map()
-      const state = {
-        callee, callerFunc, argList, func, restIdx,
-        callerLocals: ctxEntry.callerLocals,
-        callerValTypes: ctxEntry.callerValTypes,
-        callerParamFacts(key) {
-          if (!paramFacts.has(key)) paramFacts.set(key, paramFactsOf(paramReps, callerFunc, key))
-          return paramFacts.get(key)
-        },
-      }
+      const state = siteState(callSites[s])
+      if (!state) continue
+      const { func, argList } = state
       for (let k = 0; k < func.sig.params.length; k++) {
-        const r = ensureParamRep(paramReps, callee, k)
+        const r = ensureParamRep(paramReps, state.callee, k)
         if (k >= argList.length) { for (const rule of rules) rule.missing(r, k, state); continue }
-        const arg = argList[k]
-        for (const rule of rules) rule.apply(r, arg, k, state)
+        for (const rule of rules) rule.apply(r, argList[k], k, state)
       }
     }
   }
@@ -568,7 +683,33 @@ export default function narrowSignatures(programFacts, ast) {
     const pname = state.func.sig.params[k]?.name
     return pname != null ? state.func.defaults?.[pname] : null
   }
-  const mergeRule = (field, infer) => ({
+  // Hard consensus val for (funcName, param k): the kind every live call site
+  // agrees on, or null if any site is untyped / missing / disagrees. The shared
+  // `val` lattice runs SOFT (a value can come from typed sites alone, untyped
+  // sites skipped); a consumer that *mutates the signature* off val must instead
+  // ask this — it re-folds the sites HARD so it never specializes a param that
+  // some call site can't prove. (applyPointerParamAbi is that consumer.)
+  const hardParamVal = (funcName, k) => {
+    let consensus
+    for (let s = 0; s < callSites.length; s++) {
+      if (callSites[s].callee !== funcName) continue
+      const state = siteState(callSites[s])
+      if (!state) continue
+      if (k >= state.argList.length) return null         // missing → undefined at runtime
+      const v = inferValAtSite(state.argList[k], state)
+      if (v == null) return null                         // an untyped site ⇒ not specializable
+      if (consensus === undefined) consensus = v
+      else if (consensus !== v) return null              // disagreement ⇒ TOP
+    }
+    return consensus ?? null
+  }
+  // `soft` makes apply treat a null inference as BOTTOM (skip — "this site can't
+  // tell yet") instead of TOP (poison): the monotone meet. A soft field never
+  // needs clearStickyNull; its consumers either re-validate hard (hardParamVal)
+  // or read it after a final hard settling sweep. `missing` poisons regardless —
+  // an omitted arg with no default is undefined at runtime, a real reason not to
+  // specialize, and must stay sticky.
+  const mergeRule = (field, infer, soft = false) => ({
     missing(r, k, state) {
       if (r[field] === null) return
       const def = defaultArg(state, k)
@@ -576,11 +717,19 @@ export default function narrowSignatures(programFacts, ast) {
       else r[field] = null
     },
     apply(r, arg, k, state) {
-      if (r[field] !== null) mergeParamFact(r, field, infer(arg, k, state))
+      if (r[field] === null) return
+      const v = infer(arg, k, state)
+      if (v == null) { if (!soft) r[field] = null; return }
+      mergeParamFact(r, field, v)
     },
   })
   const runFixpoint = () => runCallsiteLattice([
-    mergeRule('val', (arg, _k, state) => inferValAtSite(arg, state)),
+    // val runs SOFT (monotone): a TYPED param's val only becomes inferable after the
+    // typedCtor fixpoint + pointer-ABI enrichment, so an early hard merge would
+    // sticky-poison it (the old clearStickyNull undid that). Soft leaves it BOTTOM;
+    // the post-enrichment rerun fills it in. applyPointerParamAbi re-validates via
+    // hardParamVal; a final hard sweep settles val for emit + late consumers.
+    mergeRule('val', (arg, _k, state) => inferValAtSite(arg, state), true),
     {
       missing: poison('wasm'),
       apply(r, arg, _k, state) {
@@ -620,6 +769,16 @@ export default function narrowSignatures(programFacts, ast) {
   }
   const runArrFixpoint = () => runArrElemFixpoint('arrayElemSchema', inferArrElemSchema, phase.callerElems('arrElemSchemas'))
   const runArrValTypeFixpoint = () => runArrElemFixpoint('arrayElemValType', inferArrElemValType, phase.callerElems('arrElemValTypes'))
+
+  // E2 (VAL-kind result inference) FIRST: it's body-driven and call-chain self-
+  // fixpointing — independent of the param lattice and the narrowing acts (it reads
+  // analyzeBody valTypes + callees' valResult, never paramReps or sig.params). Running
+  // it up front means a call arg like `initRows()` resolves to its VAL.ARRAY result on
+  // the param fixpoint's FIRST pass, so val/schemaId never get the can't-tell-yet
+  // poison that clearStickyNull used to un-stick (root B). Numeric (i32) result
+  // narrowing stays below — it benefits from i32 params being narrowed first.
+  const funcsWithNarrowableResult = narrowableFuncs(valueUsed)
+  narrowValResults(funcsWithNarrowableResult)
   runFixpoint()
   runFixpoint()
 
@@ -645,14 +804,12 @@ export default function narrowSignatures(programFacts, ast) {
   //     (aux carries element-type, handled separately by applyTypedPointerParamAbi).
   //   - exclude params with defaults (nullish sentinel needs the f64 NaN space).
   //   - exclude rest position (array pack/unpack stays f64).
-  applyPointerParamAbi(paramReps, valueUsed)
+  applyPointerParamAbi(paramReps, valueUsed, hardParamVal)
 
-  // 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)
+  // E: numeric (i32) result narrowing — kept here, after applyI32ParamSpecialization,
+  // so a body returning `param + 1` sees param already narrowed to i32. (E2 / VAL
+  // result inference ran up front — see above.) funcsWithNarrowableResult hoisted there.
   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
@@ -673,11 +830,9 @@ export default function narrowSignatures(programFacts, ast) {
   // observation upgrade `undefined` → NUMBER without poisoning earlier
   // monomorphic observations.
   if (hasSchemaLiterals) observeProgramSlots(ast)
-  // Clear sticky-null on val/schemaId — first 2 passes ran with valResult unset, so
-  // call args resolving via `f.valResult` returned null and got stuck. Re-running
-  // with refreshed callerValTypes lets these flow.
-  clearStickyNull(paramReps, 'val')
-  clearStickyNull(paramReps, 'schemaId')
+  // Re-run with refreshed callerValTypes + the new program-slot observations. (No
+  // clearStickyNull needed: valResult was known before the first pass — see E2 hoist
+  // above — so val/schemaId never got the can't-tell-yet poison this used to undo.)
   runFixpoint()
   // Now that .val is refreshed, dedicated arr-elem-schema fixpoint.
   runArrFixpoint()
@@ -720,7 +875,7 @@ export default function narrowSignatures(programFacts, ast) {
   // i32 offset (with ptrAux carrying the elem-type bits). Eliminates the
   // per-read `i32.wrap_i64 (i64.reinterpret_f64 (local.get $arr))` unbox dance
   // that today dominates hot loops dominated by typed-array indexing.
-  // Call sites coerce via emitArgForParam → ptrOffsetIR(arg, VAL.TYPED).
+  // Call sites coerce via coerceArg → ptrOffsetIR(arg, VAL.TYPED).
   // Safety: same exclusions as the OBJECT/SET/MAP/BUFFER narrowing above —
   // exported, value-used, raw, defaults, rest position.
   applyTypedPointerParamAbi(paramReps, valueUsed)
@@ -728,11 +883,11 @@ 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 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]`.
+  // for caller's params, so inferValType returned null and (under the old hard merge)
+  // sticky-poisoned the param's val. The soft val merge leaves it BOTTOM instead, so
+  // this rerun — now that enrichment has put VAL.TYPED into callerValTypes — simply
+  // fills it in (array.js then skips __is_str_key + __str_idx dispatch on `arr[i]`).
   enrichCallerValTypesFromPointerParams(callerCtx)
-  clearStickyNull(paramReps, 'val')
   runFixpoint()
 
   // I: Post-E re-narrow of numeric (i32) params. The first numeric narrowing pass
@@ -750,6 +905,12 @@ export default function narrowSignatures(programFacts, ast) {
   // so the refreshed exprType view propagates.
   resetParamWasmFacts(paramReps)
   runFixpoint()
+  // Settle val HARD now that every producer (results, typedCtor, enrichment) has run
+  // and the soft lattice has converged: re-fold each param's sites and poison any
+  // whose val isn't unanimous (a site left BOTTOM = genuinely untyped). After this,
+  // r.val is sound for emit + the late/post-return consumers (applyI32ParamSpecial-
+  // ization's skipTyped guard, specializeBimorphicTyped) — which read it directly.
+  runCallsiteLattice([mergeRule('val', (arg, _k, state) => inferValAtSite(arg, state))])
   // Don't steal typed-array params from specializeBimorphicTyped: F phase parks
   // bimorphic typed params at type='f64' with sticky-null typedCtor (two distinct
   // ctors at call sites). Their callers post-F pass them as i32 (pointer ABI),
@@ -764,9 +925,12 @@ export default function narrowSignatures(programFacts, ast) {
   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). */
+/** Gate the jsstring carrier on the host. ON by default for the JS host: a
+ *  js-host build is already JS-locked (it imports `env.*`), so the externref +
+ *  `wasm:js-string` carrier's JS dependency is free there, and the zero-copy
+ *  string-read path is a clear win. OFF under WASI: the carrier needs a JS host,
+ *  and wasi builds must stay portable (wasmtime/Go/Rust). Opt out on JS with
+ *  `optimize: { jsstring: false }` (e.g. side-by-side benchmarks). */
 function jsstringEnabled() {
   if (ctx.transform.host === 'wasi') return false
   if (ctx.transform.optimize?.jsstring === false) return false
@@ -782,13 +946,15 @@ export function applyJsstringBoundaryCarrierStandalone(programFacts) {
 }
 
 /**
- * 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.
+ * Body-local boolean/bigint-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). Boolean and bigint are the two kinds
+ * whose internal carrier differs from the host-boundary carrier — bool rides a 0/1
+ * number internally but crosses as the TRUE_NAN/FALSE_NAN atom; bigint rides an
+ * i64-reinterpreted f64 internally but must cross as a real Number — so an exported
+ * `(a) => a > 2` or `() => 100n` still needs its boundary thunk even on the skip path.
+ * This pass only ever *sets* valResult to VAL.BOOL / VAL.BIGINT, so it is safe to run
+ * unconditionally — pointer/array/number results are untouched.
  */
 export function narrowBoolResults() {
   for (const func of ctx.func.list) {
@@ -803,6 +969,7 @@ export function narrowBoolResults() {
       ? (localValTypes?.get(e) || ctx.scope.globalValTypes?.get(e) || null)
       : valTypeOf(e)
     if (exprs.every(e => vt(e) === VAL.BOOL)) func.valResult = VAL.BOOL
+    else if (exprs.every(e => vt(e) === VAL.BIGINT)) func.valResult = VAL.BIGINT
   }
 }
 
@@ -828,35 +995,37 @@ const JSS_OK_PROPS = new Set(['length', 'charCodeAt'])
  * `.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.
+ * Returns `{ ok, stringDiscriminating, reason? }` — `stringDiscriminating` is
+ * true iff we saw at least one string-only use (`.charCodeAt`); `reason` names
+ * the first blocking use when `ok` is false.
  */
 function paramAllUsesJsstringMappable(body, name, safeCC) {
-  if (body == null) return { ok: false, stringDiscriminating: false }
+  if (body == null) return { ok: false, stringDiscriminating: false, reason: null }
   let ok = true
   let stringDiscriminating = false
+  let reason = null
+  const fail = (msg) => { ok = false; reason ||= msg }
+  const refsParam = (node) => {
+    if (node === name) return true
+    if (!Array.isArray(node)) return false
+    for (let i = 1; i < node.length; i++) if (refsParam(node[i])) return true
+    return 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
+      if (node === name) fail('bare use of the string param disables the zero-copy externref boundary carrier')
       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
+      if (!shadowed) fail('closure capture of the string param disables the zero-copy externref boundary carrier')
       return
     }
     if ((op === '=' || op === '+=' || op === '-=' || op === '*=' || op === '/=' ||
@@ -864,26 +1033,23 @@ function paramAllUsesJsstringMappable(body, name, safeCC) {
          op === '>>=' || op === '<<=' || op === '>>>=' ||
          op === '||=' || op === '&&=' || op === '??=' ||
          op === '++' || op === '--') && node[1] === name) {
-      ok = false
+      fail('reassigning the string param disables the zero-copy externref boundary carrier')
+      return
+    }
+    if (op === '+' && node.slice(1).some(arg => refsParam(arg))) {
+      fail('string concatenation on the param disables the zero-copy externref boundary carrier')
       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
+      fail(`\`.${node[2]}\` on the string param disables the zero-copy externref boundary carrier`)
       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 }
+  return { ok, stringDiscriminating, reason }
 }
 
 function applyJsstringBoundaryCarrier(paramReps, valueUsed) {
@@ -919,13 +1085,48 @@ function applyJsstringBoundaryCarrier(paramReps, valueUsed) {
       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`).
+      updateRep(p.name, { carrier: 'jsstring', val: VAL.STRING })
       if (hasStringDefault) p.jsstringDefault = defVal[1]
     }
   }
 }
 
+/** Soft warnings when a string param could use the externref carrier but doesn't. */
+export function adviseJsstringCarrier(paramReps, valueUsed) {
+  if (!ctx.warnings || !jsstringEnabled()) return
+
+  for (const func of ctx.func.list) {
+    if (func.raw || !func.exported || !func.body || func.rest) continue
+    if (valueUsed?.has(func.name)) continue
+
+    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.jsstring) continue
+      if (p.type !== 'f64' || p.ptrKind != null) continue
+
+      const defVal = func.defaults?.[p.name]
+      if (defVal != null && !isLiteralStr(defVal)) continue
+
+      const r = reps?.get(k)
+      if (r && r.val != null && r.val !== VAL.STRING) continue
+
+      const hasStringDefault = defVal != null && isLiteralStr(defVal)
+      const { ok: usesOk, stringDiscriminating, reason } =
+        paramAllUsesJsstringMappable(func.body, p.name, safeCC)
+      const isCandidate = stringDiscriminating || r?.val === VAL.STRING || hasStringDefault
+      if (!isCandidate || usesOk) continue
+
+      warn('jsstring-declined',
+        `export '${func.name}' param '${p.name}': ${reason || 'string param uses disable the zero-copy externref boundary carrier'}`,
+        { fn: func.name }, func.body.loc)
+    }
+  }
+}
+
 /**
  * Phase: bimorphic typed-array param specialization.
  *
@@ -1142,7 +1343,12 @@ export function refineDynKeys(programFacts) {
         if (!NON_DYN_VTS.has(vt)) real = true
       }
     } else if (op === 'for-in') real = true
-    if (op === '=>') return
+    // Recurse into nested arrows too. Closures stay inline (defFunc skips
+    // depth>0), so a dynamic-key access captured in one — e.g. `handlers[op]`
+    // in a dispatch closure — is reachable only through its parent's body.
+    // Matches collectProgramFacts, which also crosses arrows when setting
+    // anyDyn; not crossing here let refineDynKeys reset a flag the initial scan
+    // correctly raised. Monotone-safe: extra visits only ever raise `real`.
     for (let i = 1; i < node.length; i++) visit(typeMap, node[i])
   }