jz 0.8.0 → 0.9.0

package/src/compile/narrow.js

@@ -8,16 +8,17 @@
  */
 
 import { ctx, warn, err } from '../ctx.js'
-import { isBlockBody, alwaysReturns, hasBareReturn, returnExprs } from '../ast.js'
+import { isBlockBody, alwaysReturns, hasBareReturn, returnExprs, callArgs, ASSIGN_OPS, extractParams, classifyParam } from '../ast.js'
 import { isLiteralStr, I32_MIN, I32_MAX } from '../ir.js'
 import {
-  analyzeBody, findMutations, invalidateLocalsCache,
+  analyzeBody, findMutations, invalidateLocalsCache, mayBeNullish,
 } 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 { typedCtorElemValType } from '../kind-traits.js'
 import { VAL, updateRep } from '../reps.js'
 import {
   paramFactsOf, ensureParamRep, mergeParamFact,
@@ -62,12 +63,17 @@ function filterLiveCallSites(callSites, valueUsed) {
 
 function buildCallerCtx() {
   const callerCtx = new Map()
-  callerCtx.set(null, { callerLocals: ctx.scope.globalTypes, callerValTypes: ctx.scope.globalValTypes })
+  const globalTE = ctx.scope.globalTypedElem || new Map()
+  callerCtx.set(null, { callerLocals: ctx.scope.globalTypes, callerValTypes: ctx.scope.globalValTypes, callerTypedElems: globalTE })
   for (const func of ctx.func.list) {
     if (!func.body || func.raw) continue
     const facts = analyzeBody(func.body)
     for (const p of func.sig.params) if (!facts.locals.has(p.name)) facts.locals.set(p.name, p.type)
-    callerCtx.set(func, { callerLocals: facts.locals, callerValTypes: facts.valTypes })
+    // Shadow-aware local+global typed-array map: a `const buf = new Int32Array(…)`
+    // local makes `buf[i]` arg reads type i32 at this caller's sites, so a callee
+    // param fed only such elements narrows (else it stays f64 and `1 << p` drags in
+    // __to_num → the whole string↔number stdlib). Mirrors callerTypedElemsFor.
+    callerCtx.set(func, { callerLocals: facts.locals, callerValTypes: facts.valTypes, callerTypedElems: callerTypedElemsFor(func, globalTE) })
   }
   return callerCtx
 }
@@ -88,13 +94,23 @@ function applyI32ParamSpecialization(paramReps, valueUsed, { skipTyped = false }
     const reps = paramReps.get(func.name)
     if (!reps) continue
     const restIdx = func.rest ? func.sig.params.length - 1 : -1
+    // A narrowed param type is a CALLER-side contract; the body keeps it only if it
+    // never writes the param (a body write emits through the generic f64 assign path
+    // — `a += 1` after an i32 narrow is a validation-failing local.set type clash).
+    // Same exclusion validateIntConstParams applies, for the same reason.
+    let mutated = null
     for (const [k, r] of reps) {
       if (k === restIdx || k >= func.sig.params.length) continue
       const p = func.sig.params[k]
       if (func.defaults?.[p.name] != null) continue
+      if (r.wasm !== 'v128' && (r.wasm !== 'i32' || p.type === 'i32')) continue
+      if (mutated === null) {
+        mutated = new Set()
+        if (func.body) findMutations(func.body, new Set(func.sig.params.map(p => p.name)), mutated)
+      }
+      if (mutated.has(p.name)) 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'
     }
@@ -129,7 +145,14 @@ function applyPointerParamAbi(paramReps, valueUsed, hardParamVal) {
     const reps = paramReps.get(func.name)
     if (!reps) continue
     const restIdx = func.rest ? func.sig.params.length - 1 : -1
-    for (const [k] of reps) {
+    // A pointer-narrowed param is a CALLER-side contract (unboxed i32 offset,
+    // reads rebox via ptrKind/ptrAux). The body keeps it only if it never
+    // WRITES the param: a reassignment (`v = v['@@iterator']()`) stores a
+    // boxed f64 into the i32 local — mixed views, wasm validation failure
+    // (the recorded reassigned-param kind bug). Same rule the wasm-type
+    // narrowing applies, for the same reason.
+    let mutated = null
+    for (const [k, r] 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.
@@ -140,6 +163,31 @@ function applyPointerParamAbi(paramReps, valueUsed, hardParamVal) {
       const p = func.sig.params[k]
       if (p.type === 'i32') continue
       if (func.defaults?.[p.name] != null) continue
+      if (mutated === null) {
+        mutated = new Set()
+        if (func.body) findMutations(func.body, new Set(func.sig.params.map(q => q.name)), mutated)
+      }
+      if (mutated.has(p.name)) continue
+      // OBJECT is the one PTR_ABI_KINDS member whose unboxed i32 offset is
+      // ambiguous without a schema id: SET/MAP/BUFFER have a fixed runtime layout
+      // (aux always 0, per narrowPointerResults), but an OBJECT's payload slots are
+      // laid out per-schema, and the offset alone can't tell a reader which schema
+      // to rebox against. r.schemaId is the SAME hard (never-reset) call-site fact
+      // narrowPointerResults' return-value arm trusts (param-reps.js: "schemaId ...
+      // stay HARD"); demanding it here too, and skipping the narrow when it's absent
+      // or conflicting, closes the gap this function used to leave: it set
+      // p.ptrKind = VAL.OBJECT with no p.ptrAux, so every later reboxer of this
+      // param — asF64's boxPtrIR defaults an omitted aux to 0 — stamped the offset
+      // with WHATEVER schema happens to be id 0 program-wide (a live, unrelated
+      // object's field layout, not this parameter's own). A fresh instance built
+      // from that mistagged parameter (watr's own `normalize(opts)`, opts narrowed
+      // this way with no callers.length>1 disagreement to save it) then reads as
+      // if it belonged to schema 0 — the wild "phantom keys" class of miscompile.
+      if (hv === VAL.OBJECT) {
+        const aux = r.schemaId
+        if (aux == null) continue
+        p.ptrAux = aux
+      }
       p.type = 'i32'
       p.ptrKind = hv
     }
@@ -197,6 +245,7 @@ function applyTypedPointerParamAbi(paramReps, valueUsed) {
     const reps = paramReps.get(func.name)
     if (!reps) continue
     const restIdx = func.rest ? func.sig.params.length - 1 : -1
+    let mutated = null   // body-write guard — same contract as applyPointerParamAbi
     for (const [k, r] of reps) {
       const ctor = r.typedCtor
       if (ctor == null) continue
@@ -205,6 +254,11 @@ function applyTypedPointerParamAbi(paramReps, valueUsed) {
       const p = func.sig.params[k]
       if (p.type === 'i32') continue
       if (func.defaults?.[p.name] != null) continue
+      if (mutated === null) {
+        mutated = new Set()
+        if (func.body) findMutations(func.body, new Set(func.sig.params.map(q => q.name)), mutated)
+      }
+      if (mutated.has(p.name)) continue
       const aux = typedElemAux(ctor)
       if (aux == null) continue
       p.type = 'i32'
@@ -497,14 +551,51 @@ 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.
  */
+/** True iff return-expr `e` is provably just `paramName` unchanged: either the bare
+ *  name itself, or a recursive call to `func.name` that forwards `paramName` at its
+ *  OWN parameter index (`return f(x, out, y)` inside `f`) — by induction on recursion
+ *  depth, that call's result is whatever `f` would return given that same value, which
+ *  bottoms out at the direct-return arms below. Strict AST-identity match only (no
+ *  attempt to prove two *different* expressions are equal at runtime). */
+function passesParamThrough(e, paramName, paramIdx, funcName) {
+  if (e === paramName) return true
+  if (!Array.isArray(e) || e[0] !== '()' || e[1] !== funcName) return false
+  return callArgs(e)[paramIdx] === paramName
+}
+
 /** 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. */
+ *  narrowed to an unboxed i32 (p.ptrKind set) — directly, or via a same-function
+ *  recursive call that forwards it unchanged (see passesParamThrough). Without the
+ *  recursive case, a function like flow-types.js's extractRefinements — whose `!`
+ *  branch delegates via `return extractRefinements(cond[1], out, !sense)` instead of
+ *  a bare `return out` — fails the naive all-return-exprs-are-the-bare-name check on
+ *  that ONE path, so the whole function loses ptrKind tracking (see
+ *  narrowPointerResults below): the caller then numeric-converts the returned offset
+ *  bits into a bogus float instead of reboxing them into a NaN-boxed pointer — a
+ *  silent value corruption, not a compile error, that only a receiver expecting the
+ *  real pointer (e.g. Map.prototype.size's raw __len dispatch) turns into a wild
+ *  offset read.
+ *
+ *  Every path must also yield a real value, not fall through / bare-`return` into
+ *  `undefined` (an f64 atom) — a match here forces this function's signature to
+ *  unconditional i32, so a value-less path would be a genuine wasm type error
+ *  (validated on encode, not just a mistracked type). Same guarantee
+ *  narrowPointerResults' func.valResult-driven arm takes via alwaysReturns, and
+ *  narrowValResults skips via hasBareReturn, for the identical reason: a recursive
+ *  walker whose tail happens to read `return helper(...)` (a value only its OWN
+ *  recursive call consumes) commonly has OTHER arms that are bare `return;`
+ *  early-exits — real shape, not hypothetical (plan/literals.js's
+ *  _disqualifyPromotion: single value-bearing return via self-recursion, but
+ *  multiple bare `return`s alongside it that returnExprs below never sees).
+ *
+ *  Returns that param, else null. */
 function passthroughPtrParam(func) {
-  const exprs = returnExprs(func.body)
+  const body = func.body
+  if (isBlockBody(body) && (!alwaysReturns(body) || hasBareReturn(body))) return null
+  const exprs = returnExprs(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
+  return func.sig.params.find((p, idx) =>
+    p.ptrKind && exprs.every(e => passesParamThrough(e, p.name, idx, func.name))) || null
 }
 
 function narrowPointerResults(funcs, paramReps) {
@@ -523,9 +614,12 @@ function narrowPointerResults(funcs, paramReps) {
       if (func.sig.ptrKind == null) {
         const pp = passthroughPtrParam(func)
         if (pp) {
+          // OBJECT reboxes by schema-id; TYPED by the param's ELEM-TYPE bits
+          // (pp.ptrAux) — without them the caller reboxes with aux 0 (Int8
+          // dispatch) and every read of the returned array mis-strides to 0.
           const aux = pp.ptrKind === VAL.OBJECT
             ? paramFactsOf(paramReps, func, 'schemaId')?.get(pp.name) ?? null
-            : null
+            : pp.ptrAux ?? 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) {
@@ -725,6 +819,7 @@ export default function narrowSignatures(programFacts, ast) {
       callee, callerFunc, argList, func, restIdx,
       callerLocals: ctxEntry.callerLocals,
       callerValTypes: ctxEntry.callerValTypes,
+      callerTypedElems: ctxEntry.callerTypedElems,
       callerParamFacts(key) {
         if (!paramFacts.has(key)) paramFacts.set(key, paramFactsOf(paramReps, callerFunc, key))
         return paramFacts.get(key)
@@ -763,7 +858,17 @@ export default function narrowSignatures(programFacts, ast) {
   const inferValAtSite = (arg, state) => {
     const v = inferValType(arg, state.callerValTypes)
     if (v != null) return v
-    if (typeof arg !== 'string') return null
+    if (typeof arg !== 'string') {
+      // Typed-array element read `recv[i]` where the receiver is a TYPED param/local of the CALLER:
+      // valTypeOf can't see this (it queries ctx.func, not the caller), so `f(src[i])` with a
+      // Float64Array PARAM `src` never propagated Number to f's param. Mirror VT['[]'] exactly,
+      // but resolve the receiver through the caller's own context — sound: only fires when the
+      // receiver is provably VAL.TYPED, and the ctor decides Number vs BigInt (BigInt64Array).
+      if (Array.isArray(arg) && arg[0] === '[]' && arg.length === 3 && typeof arg[1] === 'string' &&
+          (state.callerValTypes?.get(arg[1]) || ctx.scope.globalValTypes?.get(arg[1])) === VAL.TYPED)
+        return typedCtorElemValType(state.callerTypedElems?.get(arg[1])) || VAL.NUMBER
+      return null
+    }
     const fromParam = state.callerParamFacts('val')?.get(arg)
     if (fromParam != null) return fromParam
     const def = state.callerFunc?.defaults?.[arg]
@@ -847,15 +952,32 @@ export default function narrowSignatures(programFacts, ast) {
     if (state.callee === state.callerFunc?.name &&
         isRecurIntExpr(arg, new Set(state.func.sig.params.map(p => p.name)), state.callerLocals)) return 'i32'
     if (!state._teOverlay) {
-      const m = new Map(ctx.scope.globalTypedElem || [])
+      // Caller's typed arrays (locals + non-shadowed globals, precomputed shadow-aware
+      // in buildCallerCtx) so a LOCAL `const buf = new Int32Array(…)` makes `buf[i]`
+      // type i32 here — not just module globals / typedCtor-narrowed params.
+      const m = new Map(state.callerTypedElems || ctx.scope.globalTypedElem || [])
       const pf = state.callerParamFacts('typedCtor')
       if (pf) for (const [name, ctor] of pf) if (ctor != null) m.set(name, ctor)
       state._teOverlay = m
     }
     const prev = ctx.func.localTypedElemsOverlay
     ctx.func.localTypedElemsOverlay = state._teOverlay
-    try { return exprType(arg, state.callerLocals) }
+    let wt
+    try { wt = exprType(arg, state.callerLocals) }
     finally { ctx.func.localTypedElemsOverlay = prev }
+    // An i32-typed BARE NAME that carries a POINTER kind in the caller (a local
+    // or param already narrowed to an unboxed i32 offset) is NOT integer
+    // evidence: narrowing the callee's param to plain i32 on it makes every
+    // callee read widen the raw offset NUMERICALLY (f64.convert_i32_s) — the
+    // pointer arrives as a small number and every prop probe silently misses
+    // (this ate `Promise.any(obj)`'s GetIterator through __p_any → __p_list).
+    // Report the boxed f64 lane instead; only applyPointerParamAbi — which
+    // stamps ptrKind/ptrAux so reads REBOX — may unbox pointer params.
+    if (wt === 'i32' && typeof arg === 'string') {
+      const vk = state.callerValTypes?.get?.(arg)
+      if (vk != null && vk !== VAL.NUMBER && vk !== VAL.BOOL) return 'f64'
+    }
+    return wt
   }
   const runFixpoint = () => runCallsiteLattice([
     // val runs SOFT (monotone): a TYPED param's val only becomes inferable after the
@@ -890,8 +1012,8 @@ export default function narrowSignatures(programFacts, ast) {
   // Fix: iterate a *soft* merge — propagate known ctors, treat "can't tell yet"
   // as skip (no poison) — to a fixpoint, then one *hard* validating sweep that
   // poisons params whose call sites still can't be proven (genuinely-untyped args).
-  const runArrElemFixpoint = (field, inferFn, elemsCtxMap) => {
-    const infer = (arg, _k, state) => inferFn(arg, elemsCtxMap.get(state.callerFunc), state.callerParamFacts(field))
+  const runArrElemFixpoint = (field, inferFn, elemsCtxMap, sidsCtxMap) => {
+    const infer = (arg, _k, state) => inferFn(arg, elemsCtxMap.get(state.callerFunc), state.callerParamFacts(field), sidsCtxMap?.get(state.callerFunc))
     let changed
     const bump = (r, v) => { if (v == null || r[field] === null) return; const b = r[field]; mergeParamFact(r, field, v); if (r[field] !== b) changed = true }
     const soft = {
@@ -913,6 +1035,23 @@ export default function narrowSignatures(programFacts, ast) {
   // narrowing stays below — it benefits from i32 params being narrowed first.
   const funcsWithNarrowableResult = narrowableFuncs(valueUsed)
   narrowValResults(funcsWithNarrowableResult)
+  // Own-default typed annotation: `(arr = new Int32Array(0)) => …` self-declares
+  // the param's element ctor — the ONLY evidence a host-called export can carry
+  // (no call sites to lattice over; Workers v1 SPMD kernels are exactly this
+  // shape). A WEAK seed: set only at BOTTOM, so call-site facts merge/poison
+  // over it as usual. Runtime safety for Atomics receivers is the tag+elem
+  // guard in __atomics_addr (module/atomics.js) — a wrong host arg throws.
+  for (const func of ctx.func.list) {
+    if (!func.sig?.params || !func.defaults) continue
+    for (let k = 0; k < func.sig.params.length; k++) {
+      const d = func.defaults[func.sig.params[k].name]
+      if (Array.isArray(d) && d[0] === '()' && typeof d[1] === 'string' &&
+          d[1].startsWith('new.') && d[1].endsWith('Array')) {
+        const r = ensureParamRep(paramReps, func.name, k)
+        if (r.typedCtor === undefined) r.typedCtor = d[1]
+      }
+    }
+  }
   runFixpoint()
   runFixpoint()
 
@@ -996,11 +1135,65 @@ export default function narrowSignatures(programFacts, ast) {
   // (before E3 ran) are stale (mkInput's ptrKind was unset then).
   phase.invalidateBodyFacts()
   const callerTypedCtx = phase.callerTyped()
+  // Per-caller receiver schemas for field-provenance args (`transform(plan.tw…)`):
+  // a small decl scan per body — collision-free and live-rep-independent (the
+  // rep/schema.vars chains aren't trustworthy mid-lattice). inferSchemaId covers
+  // literals and calls (valResult/ptrAux — E-complete by this phase); chained
+  // decls resolve through the accumulating map. Module-const sids (`const P =
+  // mk(n)` at top level) seed every caller's map; a local decl SHADOWS the seed
+  // (unresolvable → masks it), and any reassignment drops the name (the second
+  // write could carry a different schema).
+  const moduleSids = new Map()
+  {
+    const visitDecl = (node) => {
+      if (!Array.isArray(node)) return
+      if (node[0] === 'let' || node[0] === 'const') {
+        for (const d of node.slice(1)) {
+          if (!Array.isArray(d) || d[0] !== '=' || typeof d[1] !== 'string') continue
+          if (!ctx.scope.consts?.has(d[1])) continue
+          const sid = inferSchemaId(d[2], moduleSids)
+          if (sid != null && !moduleSids.has(d[1])) moduleSids.set(d[1], sid)
+        }
+        return
+      }
+      if (node[0] === ';' || node[0] === 'export') for (let i = 1; i < node.length; i++) visitDecl(node[i])
+    }
+    if (Array.isArray(ast)) {
+      if (ast[0] === ';') for (let i = 1; i < ast.length; i++) visitDecl(ast[i])
+      else visitDecl(ast)
+    }
+  }
+  const callerSidsCtx = new Map()
+  for (const func of ctx.func.list) {
+    if (!func.body || func.raw) continue
+    const sids = new Map(moduleSids), poisoned = new Set()
+    const scan = (n) => {
+      if (!Array.isArray(n)) return
+      if (n[0] === '=>') return
+      if (n[0] === 'let' || n[0] === 'const') {
+        for (const d of n.slice(1)) {
+          if (Array.isArray(d) && d[0] === '=' && typeof d[1] === 'string') {
+            const sid = inferSchemaId(d[2], sids)
+            sids.delete(d[1])          // a local decl shadows any module seed
+            if (sid != null && !poisoned.has(d[1])) sids.set(d[1], sid)
+            scan(d[2])
+          } else scan(d)
+        }
+        return
+      }
+      if ((ASSIGN_OPS.has(n[0]) || n[0] === '++' || n[0] === '--') && typeof n[1] === 'string') { poisoned.add(n[1]); sids.delete(n[1]) }
+      for (let i = 1; i < n.length; i++) scan(n[i])
+    }
+    // params shadow module seeds too — an arg-bound `P` is not the module const
+    for (const p of func.sig?.params || []) sids.delete(p.name)
+    scan(func.body)
+    callerSidsCtx.set(func, sids)
+  }
   // Two-pass fixpoint: lets a caller's params, once typed, propagate further to
   // 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', inferTypedCtor, callerTypedCtx)
+  const runTypedFixpoint = () => runArrElemFixpoint('typedCtor', inferTypedCtor, callerTypedCtx, callerSidsCtx)
   runTypedFixpoint()
   runTypedFixpoint()
 
@@ -1033,6 +1226,15 @@ export default function narrowSignatures(programFacts, ast) {
   // (callback bench: mix is FNV — params and result all i32-shaped, but inferred
   // only after E phase narrowed mix's result).
   phase.refreshLocals()
+  // I1: Re-run POINTER results now that Phase G has tagged typed params — a
+  // pass-through like `norm = (w) => { …w[i]…; return w }` gains w.ptrKind only
+  // in G, AFTER the first narrowPointerResults sweep, so its sig.ptrKind stayed
+  // null and the I2 numeric-results pass below then STOLE the return as plain
+  // i32 — the caller f64.convert_i32_s'd the returned offset into a bogus float
+  // (the cross-module memo miscompile: `g._w = norm(w)` stored a number, the
+  // slot read dispatched on it as a pointer → undefined). The rerun stamps
+  // sig.ptrKind first; I2's f64-results guard then skips these functions.
+  narrowPointerResults(funcsWithNarrowableResult, paramReps)
   // I2: Re-narrow i32 RESULTS now that Phase G (applyTypedPointerParamAbi) has tagged
   // typed-array params ptrKind=TYPED. Phase E ran before G, so a function returning a
   // typed-array element — dict's `lookup = (keys, vals, k) => { … return vals[h] }` with
@@ -1055,6 +1257,63 @@ export default function narrowSignatures(programFacts, ast) {
   // 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))])
+  // BIGINT params: re-derive nullability the val claim just erased. VT['?:']
+  // carries BIGINT through a nullish-literal arm (the kind is untaggable at
+  // runtime — kind.js), so a site arg like `c ? BigInt(x) : null` PROVES
+  // BIGINT while still passing null on the other path; the settle above
+  // stamps bare val=BIGINT and strictSentinel would then FOLD the callee's
+  // `x == null` guard (watr's `_i64Arith(r)`: fold-miss null crosses for
+  // real — the guard must return null, not format atom bits as hex). Any
+  // site arg not structurally non-nullish marks the param nullable, which
+  // only suppresses that fold (emitFunc's caller-side nullability block).
+  // Scoped to BIGINT vals: tagged kinds keep their runtime forks and their
+  // folds. Name args resolve through the CALLER body's own writes — at plan
+  // time no caller ctx.func is installed, so rep lookups would misread;
+  // an unwritten name (param/global/closure) fails closed.
+  const bodyNameNullable = (callerFunc) => {
+    const seen = new Set()
+    const nameNullable = (name) => {
+      if (seen.has(name)) return false            // cyclic alias: no new evidence
+      seen.add(name)
+      let found = false, nullish = false
+      const walk = (node) => {
+        if (nullish || !Array.isArray(node)) return
+        const op = node[0]
+        if ((op === 'let' || op === 'const') && node.length >= 2) {
+          for (let i = 1; i < node.length; i++) {
+            const d = node[i]
+            if (Array.isArray(d) && d[0] === '=' && d[1] === name) {
+              found = true
+              if (mayBeNullish(d[2], nameNullable)) nullish = true
+            }
+          }
+        } else if (op === '=' && node[1] === name) {
+          found = true
+          if (mayBeNullish(node[2], nameNullable)) nullish = true
+        } else if (typeof op === 'string' && op.length > 1 && op.endsWith('=') &&
+                   ASSIGN_OPS.has(op) && node[1] === name) {
+          found = true
+          nullish = true                          // ??=/||= etc. — fail closed
+        }
+        for (let i = 1; i < node.length; i++) walk(node[i])
+      }
+      walk(callerFunc?.body)
+      return found ? nullish : true               // unwritten name — fail closed
+    }
+    return nameNullable
+  }
+  for (const [fname, reps] of paramReps) {
+    for (const [k, r] of reps) {
+      if (r.val !== VAL.BIGINT || r.nullable) continue
+      for (const cs of callSites) {
+        if (cs.callee !== fname || k >= cs.argList.length) continue
+        if (mayBeNullish(cs.argList[k], bodyNameNullable(cs.callerFunc))) {
+          r.nullable = true
+          break
+        }
+      }
+    }
+  }
   // 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),
@@ -1067,6 +1326,22 @@ export default function narrowSignatures(programFacts, ast) {
   // 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)
+
+  // Stamp the settled per-param val kind onto sig.params (mirror of emitFunc's
+  // updateRep(pname, { val: r.val }) merge — same source, same condition). The
+  // call-site emitter needs it to pick the arg carrier: a BOOL arg into an
+  // UNTYPED f64 param boxes to its TRUE/FALSE atom (boolean identity crosses
+  // the boundary), while a val-known param keeps the raw 0/1 ABI its body
+  // assumes. Read by coerceArg (emit.js).
+  for (const func of ctx.func.list) {
+    if (!func.sig || func.raw) continue
+    const reps = paramReps.get(func.name)
+    if (!reps) continue
+    for (const [k, r] of reps) {
+      const p = func.sig.params[k]
+      if (p && r.val != null && p.val == null) p.val = r.val
+    }
+  }
 }
 
 /** Gate the jsstring carrier on the host. ON by default for the JS host: a
@@ -1520,6 +1795,268 @@ export function specializeBimorphicTyped(programFacts) {
   }
 }
 
+/**
+ * Speculative typed-param specialization — the GUARDED sibling of
+ * specializeBimorphicTyped, for params whose args can never be statically
+ * PROVEN typed: plan objects through Map caches, nullable module-let memos,
+ * returned-object fields — the fftplan/provenance shape-class, where the
+ * receiver's schema is unknowable but every value that ever reaches the call
+ * is, in practice, the same typed array.
+ *
+ * When every static call site's arg at a position carries the SAME ctor as
+ * evidence — a proven inferTypedCtor, or the program-wide write-gated slot
+ * census for a bare field read (ctx.schema.slotTypedCtorByProp, the
+ * guardedSlotOf contract) — clone the callee with those params typed
+ * (identical machinery to the bimorphic clones) and record it in
+ * ctx.types.specFns. Emit rewrites every static direct call into
+ *
+ *   tags-all-match? call $f$spec(raw offsets…) : call $f(boxes…)
+ *
+ * (emitSpeculativeCall) — one masked NaN-box compare per speculated arg per
+ * CALL, amortized over the callee's loops. A nullish / other-kind / view
+ * value simply falls to the original call unchanged, so speculation can only
+ * ever be as fast, never wrong; the original function stays for indirect and
+ * boundary callers. Gate on a loop in the body: the win is per-ELEMENT
+ * access, so guarding loop-free leaf calls only spends the compare.
+ *
+ * Evidence is a recursive WEAK lattice (soundness never depends on it — the
+ * runtime guard does; evidence only decides where speculating is worth it):
+ *   - proven inferTypedCtor at the site (strong)
+ *   - `x.prop` → program-wide write-gated slot census (slotTypedCtorByProp)
+ *   - a name → its single `=` binding's init, chased recursively
+ *   - a name that is an ENCLOSING ARROW's param → meet over the arrow's own
+ *     call sites at that position (the `edge(wre, wim)` harness shape: the
+ *     kernel call sits inside a local arrow whose args carry the evidence)
+ *   - `f(...)` → f's return census: every return a `new K`, a local bound to
+ *     one, a censused field read, or another censused call; nullish returns
+ *     are SKIPPED (they fail the guard at runtime, by design — this is what
+ *     lets Map-cache/memo getters like getPlan(n) census through)
+ */
+export function speculateTypedParams(programFacts, ast) {
+  const { callSites, paramReps } = programFacts
+  if (!ctx.schema.slotTypedCtorByProp) return
+
+  const sitesByCallee = new Map()
+  for (const cs of callSites) {
+    const list = sitesByCallee.get(cs.callee)
+    if (list) list.push(cs); else sitesByCallee.set(cs.callee, [cs])
+  }
+  const callerTypedCtx = buildCallerTypedCtx()
+  const callerTypedParamsCtx = new Map()
+  for (const func of ctx.func.list) {
+    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) {
+        acc ||= new Map()
+        if (!acc.has(p.name)) acc.set(p.name, ctorFromElemAux(p.ptrAux))
+      }
+    }
+    if (acc) callerTypedParamsCtx.set(func, acc)
+  }
+
+  const hasLoop = (n) => Array.isArray(n)
+    && (n[0] === 'for' || n[0] === 'while' || n[0] === 'do' || n.some((c, i) => i > 0 && hasLoop(c)))
+
+  // ---- weak evidence engine (see doc above) ----
+  const DBG2 = typeof process !== 'undefined' && !!process.env?.JZ_DBG_SPEC
+  const isNullish = (r) => r == null || r === 'null' || r === 'undefined'
+    || (Array.isArray(r) && (r[0] === 'null' || r[0] === 'undefined'))
+  const retMemo = new Map()
+  const MAX_DEPTH = 6
+  const bodyOf = (callerFunc) => callerFunc ? callerFunc.body : ast
+
+  // Return census of a named function: the single ctor every non-nullish
+  // return resolves to, or null.
+  function retCensus(fname, depth) {
+    if (retMemo.has(fname)) return retMemo.get(fname)
+    retMemo.set(fname, null)                       // cycle guard
+    const func = ctx.func.map.get(fname)
+    if (!func?.body || func.raw || depth > MAX_DEPTH) return null
+    const te = analyzeBody(func.body).typedElems
+    let ctor = null
+    for (const r of returnExprs(func.body)) {
+      if (isNullish(r)) continue
+      const c = typedElemCtor(r)
+        || (typeof r === 'string' ? te?.get(r) : null)
+        || (Array.isArray(r) && r[0] === '.' && typeof r[2] === 'string' ? ctx.schema.slotTypedCtorByProp(r[2]) : null)
+        || (Array.isArray(r) && r[0] === '()' && typeof r[1] === 'string' ? retCensus(r[1], depth + 1) : null)
+      if (!c || (ctor && c !== ctor)) return null
+      ctor = c
+    }
+    retMemo.set(fname, ctor)
+    return ctor
+  }
+
+  // Chain of arrow nodes enclosing `target` inside `root` (outermost first).
+  function arrowPathTo(root, target) {
+    const path = []
+    const walk = (n) => {
+      if (!Array.isArray(n)) return false
+      if (n === target) return true
+      const isArrow = n[0] === '=>'
+      if (isArrow) path.push(n)
+      for (let i = 1; i < n.length; i++) if (walk(n[i])) return true
+      if (isArrow) path.pop()
+      return false
+    }
+    return walk(root) ? path : null
+  }
+
+  function evidenceOfArg(arg, callerFunc, siteNode, depth, seen) {
+    const r = evidenceOfArgInner(arg, callerFunc, siteNode, depth, seen)
+    if (DBG2) console.error('[evid=]', JSON.stringify(arg)?.slice(0, 50), '→', r)
+    return r
+  }
+  function evidenceOfArgInner(arg, callerFunc, siteNode, depth, seen) {
+    if (arg == null || depth > MAX_DEPTH) return null
+    const proven = inferTypedCtor(arg, callerTypedCtx.get(callerFunc), callerTypedParamsCtx.get(callerFunc))
+    if (proven) return proven
+    if (Array.isArray(arg)) {
+      if (arg[0] === '.' && typeof arg[2] === 'string') return ctx.schema.slotTypedCtorByProp(arg[2])
+      if (arg[0] === '()' && typeof arg[1] === 'string' && ctx.func.map.has(arg[1])) return retCensus(arg[1], depth)
+      return typedElemCtor(arg)
+    }
+    if (typeof arg !== 'string') return null
+    // Cycle guard is PATH-local: the key backtracks on exit (a name legitimately
+    // recurs across sibling meet branches — e.g. duplicated call sites after
+    // lambda inlining — and must resolve fresh in each).
+    const key = (callerFunc?.name || '') + '|' + arg
+    if (seen.has(key)) return null
+    seen.add(key)
+    try {
+      return resolveName()
+    } finally { seen.delete(key) }
+
+    function resolveName() {
+    const body = bodyOf(callerFunc)
+    if (!body) return null
+    // Enclosing-arrow param? Meet the arrow's own call sites at that position.
+    const arrows = siteNode ? arrowPathTo(body, siteNode) : null
+    if (arrows) for (let a = arrows.length - 1; a >= 0; a--) {
+      const names = extractParams(arrows[a][1]).map(p => classifyParam(p)).filter(c => c.kind === 'plain').map(c => c.name)
+      const j = names.indexOf(arg)
+      if (j < 0) continue
+      // The binding name of this arrow (`const edge = (…) => …`), then its calls.
+      let bindName = null
+      const findBind = (n) => {
+        if (!Array.isArray(n)) return
+        if (n[0] === '=' && typeof n[1] === 'string' && n[2] === arrows[a]) bindName = n[1]
+        for (let i = 1; i < n.length && !bindName; i++) findBind(n[i])
+      }
+      findBind(body)
+      if (!bindName) return null
+      const calls = []
+      const findCalls = (n) => {
+        if (!Array.isArray(n)) return
+        if (n[0] === '()' && n[1] === bindName) calls.push(n)
+        for (let i = 1; i < n.length; i++) findCalls(n[i])
+      }
+      findCalls(body)
+      if (!calls.length) return null
+      let ctor = null
+      for (const cn of calls) {
+        const list = cn[2] == null ? [] : (Array.isArray(cn[2]) && cn[2][0] === ',') ? cn[2].slice(1) : [cn[2]]
+        const c = evidenceOfArg(list[j], callerFunc, cn, depth + 1, seen)
+        if (!c || (ctor && c !== ctor)) return null
+        ctor = c
+      }
+      return ctor
+    }
+    // Single-`=` local binding: chase its init. More than one write → too
+    // murky to be worth the guard.
+    let decl = null, writes = 0
+    const findDecl = (n) => {
+      if (!Array.isArray(n)) return
+      if (typeof n[1] === 'string' && n[1] === arg) {
+        if (n[0] === '=') { decl = n; writes++ }
+        else if (ASSIGN_OPS.has(n[0]) || n[0] === '++' || n[0] === '--') writes++
+      }
+      for (let i = 1; i < n.length; i++) findDecl(n[i])
+    }
+    findDecl(body)
+    if (!decl || writes !== 1) return null
+    return evidenceOfArg(decl[2], callerFunc, decl, depth + 1, seen)
+    }
+  }
+
+  const DBG = typeof process !== 'undefined' && !!process.env?.JZ_DBG_SPEC
+  const originals = ctx.func.list.slice()
+  for (const func of originals) {
+    if (func.raw || func.rest || !func.body) continue
+    if (func.sig?.results?.length !== 1) continue
+    const sites = sitesByCallee.get(func.name)
+    if (!sites?.length) { if (DBG) console.error('[spec]', func.name, 'no sites'); continue }
+    if (!hasLoop(func.body)) continue
+
+    // Candidate positions: still a dyn f64 box after F-phase/bimorphic (no
+    // pointer ABI, not numeric-narrowed), no default (undefined must reach it).
+    const reps = paramReps.get(func.name)
+    const candidates = []
+    for (let k = 0; k < func.sig.params.length; k++) {
+      const p = func.sig.params[k]
+      if (p.type !== 'f64' || p.ptrKind != null) continue
+      if (func.defaults?.[p.name] != null) continue
+      const r = reps?.get(k)
+      if (r && (r.val != null && r.val !== VAL.TYPED)) continue
+      candidates.push(k)
+    }
+    if (!candidates.length) continue
+
+    // Evidence meet across sites per position. A site WITHOUT evidence is
+    // NEUTRAL — its calls just miss the guard at runtime and take the
+    // original (a plain-array or debug caller must not veto the hot sites'
+    // win). Only CONFLICTING evidence (two different ctors) kills the
+    // position — a guard can only test one kind.
+    const specs = []
+    for (const k of candidates) {
+      let ctor = null, dead = false
+      for (const site of sites) {
+        const arg = site.argList[k]
+        if (arg == null) continue
+        const proven = inferTypedCtor(arg, callerTypedCtx.get(site.callerFunc), callerTypedParamsCtx.get(site.callerFunc))
+        const c = proven ?? evidenceOfArg(arg, site.callerFunc, site.node, 0, new Set())
+        if (DBG) console.error('[spec]', func.name, 'k=' + k, JSON.stringify(arg)?.slice(0, 60), 'proven=' + proven, 'c=' + c)
+        if (c == null) continue
+        if (ctor && c !== ctor) { dead = true; break }
+        ctor = c
+      }
+      if (dead || !ctor) continue
+      const aux = typedElemAux(ctor)
+      if (aux == null) continue
+      specs.push({ k, ctor, aux })
+    }
+    if (!specs.length) continue
+
+    let cloneName = `${func.name}$spec`
+    while (ctx.func.names.has(cloneName)) cloneName += '$'
+    const specAt = new Map(specs.map(s => [s.k, s]))
+    const cloneSig = {
+      params: func.sig.params.map((p, idx) => {
+        const s = specAt.get(idx)
+        return s ? { name: p.name, type: 'i32', ptrKind: VAL.TYPED, ptrAux: s.aux } : { ...p }
+      }),
+      results: [...func.sig.results],
+    }
+    const clone = { ...func, name: cloneName, sig: cloneSig, exported: false }
+    ctx.func.list.push(clone)
+    ctx.func.map.set(cloneName, clone)
+    ctx.func.names.add(cloneName)
+
+    const cloneReps = new Map()
+    if (reps) for (const [k, r] of reps) cloneReps.set(k, { ...r })
+    for (const s of specs) {
+      const r = cloneReps.get(s.k) || {}
+      r.typedCtor = s.ctor
+      r.val = VAL.TYPED
+      cloneReps.set(s.k, r)
+    }
+    paramReps.set(cloneName, cloneReps)
+
+    ;(ctx.types.specFns ||= new Map()).set(func.name, { clone: cloneName, guards: specs.map(s => ({ k: s.k, aux: s.aux })) })
+  }
+}
+
 /**
  * Phase: refine ctx.types.anyDynKey using post-narrowSignatures type info.
  */