jz 0.6.0 → 0.7.0

package/src/compile/loop-divmod.js

@@ -0,0 +1,155 @@
+// Loop induction strength-reduction for `i % w` and `(i / w) | 0`.
+//
+// JS `%` and `/` are float ops; `i % w` with a RUNTIME divisor lowers to f64
+// (i % 0 is NaN, so it can't be soundly typed i32 — see type.js exprType `%`).
+// That makes the column `x = i % w` an f64 local, which cascades: every dependent
+// neighbour index becomes f64 and each typed-array access pays an f64→i32 convert.
+// Measured ~5× slower than V8, which speculates the divisor non-zero and uses i32.
+//
+// This pass replaces the per-iteration division with incremental i32 counters in a
+// unit-stride loop: the column `cx` increments by 1 and wraps to 0 at `w`, bumping
+// the row `cy`. No division survives in the body, so the whole index chain stays
+// i32. Fully sound — counters are pure increment (the divisor-zero question never
+// arises), and if `w == 0` the loop's `i < w*h` guard never admits an iteration, so
+// the one-time seed `(i%w)|0` (NaN→0) is unused.
+//
+// Recognized (post-prepare AST): a `while` whose body increments one IV `i` by +1
+// exactly once, reads `['%', i, w]` and/or `['|', ['/', i, w], LIT0]` with `w`
+// loop-invariant, and has no `continue` / closure-capture of i,w (which could
+// desync the counters). Number literals are sparse-array holes `[, v]` (n[0] is the
+// hole = undefined), so literal tests use `== null`; created literals are bare numbers.
+
+import { findMutations } from './analyze-scans.js'
+
+const litN = (n, k) => Array.isArray(n) && n.length === 2 && n[0] == null && n[1] === k
+const isMod = (n, i, w) => Array.isArray(n) && n[0] === '%' && n[1] === i && n[2] === w
+const isFloorDiv = (n, i, w) =>
+  Array.isArray(n) && n[0] === '|' && litN(n[2], 0) &&
+  Array.isArray(n[1]) && n[1][0] === '/' && n[1][1] === i && n[1][2] === w
+
+// IV a statement increments by exactly +1, or null. Covers `i++` (post-inc desugars
+// to `(++i) - 1`), `++i`, `i += 1`, `i = i + 1`.
+function incVarOf(stmt) {
+  if (!Array.isArray(stmt)) return null
+  let inc = stmt
+  if (stmt[0] === '-' && litN(stmt[2], 1) && Array.isArray(stmt[1]) && stmt[1][0] === '++') inc = stmt[1]
+  if (inc[0] === '++' && typeof inc[1] === 'string') return inc[1]
+  if (stmt[0] === '+=' && typeof stmt[1] === 'string' && litN(stmt[2], 1)) return stmt[1]
+  if (stmt[0] === '=' && typeof stmt[1] === 'string' && Array.isArray(stmt[2]) && stmt[2][0] === '+') {
+    const [, a, b] = stmt[2]
+    if (a === stmt[1] && litN(b, 1)) return stmt[1]
+    if (b === stmt[1] && litN(a, 1)) return stmt[1]
+  }
+  return null
+}
+
+const usesPattern = (n, i, w, pred) => Array.isArray(n) && (pred(n, i, w) || n.some(c => usesPattern(c, i, w, pred)))
+const replace = (n, i, w, cx, cy) =>
+  !Array.isArray(n) ? n : isMod(n, i, w) ? cx : isFloorDiv(n, i, w) ? cy : n.map(c => replace(c, i, w, cx, cy))
+// a `continue` that targets THIS loop (not one nested inside) — would skip the increment
+const hasOuterContinue = (n) => Array.isArray(n) &&
+  (n[0] === 'continue' || (n[0] !== 'while' && n[0] !== 'for' && n[0] !== 'do' && n[0] !== '=>' && n.some(hasOuterContinue)))
+// Vars assigned anywhere inside a closure in the function. Such a var can be
+// mutated by a call in the loop body (the closure may be defined outside the loop,
+// so a body-local findMutations misses it), so it is not safe as the IV or divisor.
+const ASSIGN_OPS = new Set(['=', '+=', '-=', '*=', '/=', '%=', '**=', '&=', '|=', '^=', '<<=', '>>=', '>>>=', '&&=', '||=', '??='])
+const collectAssigns = (n, out) => {
+  if (!Array.isArray(n)) return
+  if (typeof n[1] === 'string' && (ASSIGN_OPS.has(n[0]) || n[0] === '++' || n[0] === '--')) out.add(n[1])
+  n.forEach(c => collectAssigns(c, out))
+}
+const closureMutated = (n, out) => {
+  if (!Array.isArray(n)) return out
+  if (n[0] === '=>') collectAssigns(n, out)
+  n.forEach(c => closureMutated(c, out))
+  return out
+}
+
+let _uniq = 0
+let _cm = new Set()  // closure-mutated vars for the function currently being transformed
+
+// Try to strength-reduce one `while` statement. Returns [seed, loop] or null.
+function tryReduce(stmt) {
+  if (!Array.isArray(stmt) || stmt[0] !== 'while') return null
+  const cond = stmt[1], lbody = stmt[2]
+  if (!Array.isArray(lbody) || lbody[0] !== ';') return null
+
+  // exactly one IV incremented by +1
+  let iv = null, ivIdx = -1
+  for (let k = 1; k < lbody.length; k++) {
+    const v = incVarOf(lbody[k])
+    if (v) { if (iv) return null; iv = v; ivIdx = k }
+  }
+  if (!iv) return null
+
+  // a single invariant divisor `w` (`i % w` / `(i/w)|0` all share it)
+  let w = null
+  const findW = (n) => {
+    if (!Array.isArray(n)) return
+    const d = n[0] === '%' && n[1] === iv ? n[2]
+      : (n[0] === '|' && litN(n[2], 0) && Array.isArray(n[1]) && n[1][0] === '/' && n[1][1] === iv) ? n[1][2] : null
+    if (typeof d === 'string') { if (w == null) w = d; else if (w !== d) w = false }
+    n.forEach(findW)
+  }
+  findW(lbody)
+  if (!w || w === iv) return null
+
+  const usesMod = usesPattern(lbody, iv, w, isMod)
+  const usesDiv = usesPattern(lbody, iv, w, isFloorDiv)
+  if (!usesMod && !usesDiv) return null
+
+  // soundness: w invariant, iv written ONLY by the increment, no continue/closure capture
+  const wMut = new Set(); findMutations(lbody, new Set([w]), wMut)
+  if (wMut.has(w)) return null
+  const ivMut = new Set()
+  findMutations([';', ...lbody.slice(1).filter((_, k) => k !== ivIdx - 1)], new Set([iv]), ivMut)
+  if (ivMut.has(iv)) return null
+  if (hasOuterContinue(lbody)) return null
+  if (_cm.has(iv) || _cm.has(w)) return null  // IV/divisor mutable via a closure call
+
+  const id = _uniq++
+  const cx = `__lsrx${id}`, cy = `__lsry${id}`
+  // seed (inside the w>0 branch): cx = (i%w)|0, cy = (i/w)|0 — one-time, i32 via |0
+  const seedDecls = [['=', cx, ['|', ['%', iv, w], 0]]]
+  if (usesDiv) seedDecls.push(['=', cy, ['|', ['/', iv, w], 0]])
+  const seed = ['let', ...seedDecls]
+
+  // transformed body: replace patterns, inject `cx++; if(cx>=w){cx=0; cy++}` after the increment
+  const newBody = [';']
+  for (let k = 1; k < lbody.length; k++) {
+    newBody.push(replace(lbody[k], iv, w, cx, cy))
+    if (k === ivIdx) {
+      newBody.push(['=', cx, ['+', cx, 1]])
+      if (usesDiv) newBody.push(['=', cy, ['+', cy, ['?:', ['>=', cx, w], 1, 0]]])
+      newBody.push(['=', cx, ['?:', ['>=', cx, w], 0, cx]])
+    }
+  }
+  const fast = ['while', replace(cond, iv, w, cx, cy), newBody]
+  // The counters track i%w only when w>0 AND i>=0: w<=0 gives NaN / a negative-divisor
+  // modulo, and i<0 makes i%w negative (JS modulo takes the dividend's sign) — neither
+  // follows the 0..w-1 +1-wrap the counters model. A one-time `w>0 && i>=0` guard (i is
+  // the IV's entry value; it only increments, so it stays ≥0) keeps the fast i32 path
+  // for the universal positive-dimension, forward-counting case and falls back to the
+  // unmodified loop otherwise — sound for any w, any start.
+  return [['if', ['&&', ['>', w, 0], ['>=', iv, 0]], ['{}', [';', seed, fast]], stmt]]
+}
+
+// Walk the body; transform `while` loops inside every block (post-order so a nested
+// loop is reduced before its enclosing one is examined).
+function walk(node) {
+  if (!Array.isArray(node)) return node
+  const n = node.map(walk)
+  if (n[0] !== ';') return n
+  const out = [';']
+  for (let k = 1; k < n.length; k++) {
+    const r = tryReduce(n[k])
+    if (r) out.push(...r)
+    else out.push(n[k])
+  }
+  return out
+}
+
+export function strengthReduceLoopDivMod(body) {
+  _cm = closureMutated(body, new Set())
+  return walk(body)
+}

package/src/compile/narrow.js

@@ -7,7 +7,7 @@
  * function `sig` records change.
  */
 
-import { ctx, warn } from '../ctx.js'
+import { ctx, warn, err } from '../ctx.js'
 import { isBlockBody, alwaysReturns, hasBareReturn, returnExprs } from '../ast.js'
 import { isLiteralStr, I32_MIN, I32_MAX } from '../ir.js'
 import {
@@ -24,7 +24,7 @@ import {
 } from '../param-reps.js'
 import {
   inferArrElemSchema, inferArrElemValType,
-  inferSchemaId, inferValType, inferTypedCtor,
+  inferSchemaId, inferValType, inferTypedCtor, inferParams,
 } from './infer.js'
 
 const PTR_ABI_KINDS = new Set([VAL.OBJECT, VAL.SET, VAL.MAP, VAL.BUFFER])
@@ -156,12 +156,32 @@ function refreshCallerValTypes(callerCtx) {
   }
 }
 
+// Per-caller typed-elem context: the caller's body-local typed arrays, layered
+// over the module's typed-array globals so a call like `f(globalArr)` resolves
+// `globalArr`'s ctor (inferTypedCtor reads only this map for a bare-name arg).
+// A global is visible UNLESS the caller shadows the name with a param or local
+// of its own — only then could the name denote a non-typed value. Globals are
+// sound to consult: globalTypedElem holds a name only when EVERY assignment to
+// it is the same single typed-array ctor (scope.js invalidates on any conflict),
+// so it can't denote a different kind at the call site.
+function callerTypedElemsFor(func, globalTE) {
+  const local = analyzeBody(func.body).typedElems
+  if (!globalTE.size) return local
+  const shadowed = new Set(analyzeBody(func.body).locals.keys())
+  for (const p of func.sig?.params || []) shadowed.add(p.name)
+  const merged = new Map()
+  for (const [k, v] of globalTE) if (!shadowed.has(k)) merged.set(k, v)
+  for (const [k, v] of local) merged.set(k, v)  // local typed binding shadows the global
+  return merged
+}
+
 function buildCallerTypedCtx() {
   const callerTypedCtx = new Map()
-  callerTypedCtx.set(null, ctx.scope.globalTypedElem || new Map())
+  const globalTE = ctx.scope.globalTypedElem || new Map()
+  callerTypedCtx.set(null, globalTE)
   for (const func of ctx.func.list) {
     if (!func.body || func.raw) continue
-    callerTypedCtx.set(func, analyzeBody(func.body).typedElems)
+    callerTypedCtx.set(func, callerTypedElemsFor(func, globalTE))
   }
   return callerTypedCtx
 }
@@ -1127,6 +1147,87 @@ export function adviseJsstringCarrier(paramReps, valueUsed) {
   }
 }
 
+// Two value-kinds CONFLICT when passing one where the other is expected would
+// rely on a JS boundary coercion jz does not implement (so the result diverges).
+// NUMBER↔STRING is the canonical pair: `"5" * 2` is 10 in JS but NaN in jz, and a
+// STRING passed to a numeric param reads its NaN-boxed bits as an f64. ARRAY/OBJECT
+// vs NUMBER/STRING likewise. We treat the four primitive-ish kinds as mutually
+// exclusive; BOOL is omitted (it nanboxes to 0/1 and numeric code tolerates it).
+const STRICT_CONFLICT = {
+  [VAL.NUMBER]: new Set([VAL.STRING, VAL.ARRAY, VAL.OBJECT]),
+  [VAL.STRING]: new Set([VAL.NUMBER, VAL.ARRAY, VAL.OBJECT]),
+  [VAL.ARRAY]: new Set([VAL.NUMBER, VAL.STRING]),
+  [VAL.OBJECT]: new Set([VAL.NUMBER, VAL.STRING]),
+}
+const kindName = (v) => ({ [VAL.NUMBER]: 'number', [VAL.STRING]: 'string', [VAL.ARRAY]: 'array', [VAL.OBJECT]: 'object' }[v] || 'value')
+
+/**
+ * Strict-mode boundary type check (standalone; runs in both the full-narrow and
+ * skip-narrow plan paths).
+ *
+ * jz infers a param's type from how it's used (`x * 2` → number, `s.charCodeAt`
+ * → string) or from an explicit default (`x = 0` → number). In permissive mode a
+ * caller may pass any type and jz silently computes a divergent result (`"5"*2`
+ * is 10 in JS, NaN here). Strict mode is the canonical subset where that misuse
+ * is a compile error instead — consistent with strict already rejecting `==`,
+ * dynamic dispatch, and `void`.
+ *
+ * Fires ONLY when BOTH sides are statically certain and conflict:
+ *   - the callee param has a known kind (its default-value type, or a settled
+ *     `val` rep from body-usage / call-site inference), AND
+ *   - the argument expression has a known, conflicting kind (a literal or a
+ *     locally-typed binding).
+ * An untyped param or untyped arg is never flagged — no false positives on
+ * genuinely polymorphic code.
+ */
+export function strictBoundaryTypeCheck(programFacts) {
+  if (!ctx.transform.strict) return
+  const { callSites, paramReps } = programFacts
+
+  // Per-callee body-evidence cache: methodEvidence (.charCodeAt→STRING, .push→
+  // ARRAY) keyed by param name. Computed lazily, once per callee.
+  const bodyEvidence = new Map()
+  const evidenceOf = (func) => {
+    if (!bodyEvidence.has(func.name)) {
+      const names = func.sig.params.map(p => p.name).filter(Boolean)
+      bodyEvidence.set(func.name, func.body ? inferParams(func.body, names) : new Map())
+    }
+    return bodyEvidence.get(func.name)
+  }
+
+  // Expected kind of callee param k, from any statically-certain source:
+  //   1. explicit default value type — the source's own declaration (x = 0 → number)
+  //   2. settled call-site/usage rep `val` (paramReps; present after full narrow)
+  //   3. type-exclusive body evidence (methodEvidence; works in skip-narrow path too)
+  // First certain source wins; null when the param is genuinely polymorphic.
+  const paramKind = (func, k) => {
+    const p = func.sig.params[k]
+    if (!p) return null
+    const def = func.defaults?.[p.name]
+    if (def != null) { const dv = valTypeOf(def); if (dv) return dv }
+    const repVal = paramReps?.get(func.name)?.get(k)?.val
+    if (repVal != null) return repVal
+    return evidenceOf(func).get(p.name)?.val ?? null
+  }
+
+  for (const cs of callSites) {
+    const func = ctx.func.map.get(cs.callee)
+    if (!func || func.raw || !func.sig) continue
+    if (func.rest) continue                       // rest packs args into an array
+    for (let k = 0; k < cs.argList.length && k < func.sig.params.length; k++) {
+      const want = paramKind(func, k)
+      if (want == null) continue
+      const conflicts = STRICT_CONFLICT[want]
+      if (!conflicts) continue
+      const got = valTypeOf(cs.argList[k])
+      if (got != null && conflicts.has(got)) {
+        const pname = func.sig.params[k].name
+        err(`strict mode: ${kindName(want)} parameter '${pname}' of '${cs.callee}' received a ${kindName(got)} argument — jz does not coerce ${kindName(got)}→${kindName(want)} at the call boundary (the result would diverge from JS). Pass a ${kindName(want)}, or { strict: false }.`)
+      }
+    }
+  }
+}
+
 /**
  * Phase: bimorphic typed-array param specialization.
  *
@@ -1161,13 +1262,9 @@ export function specializeBimorphicTyped(programFacts) {
     if (list) list.push(cs); else sitesByCallee.set(cs.callee, [cs])
   }
 
-  // Per-caller typedElem map (literal `new TypedArray(N)` bindings inside body).
-  const callerTypedCtx = new Map()
-  callerTypedCtx.set(null, ctx.scope.globalTypedElem || new Map())
-  for (const func of ctx.func.list) {
-    if (!func.body || func.raw) continue
-    callerTypedCtx.set(func, analyzeBody(func.body).typedElems)
-  }
+  // Per-caller typedElem map: body-local `new TypedArray(N)` bindings layered
+  // over the module's typed globals (shared with buildCallerTypedCtx).
+  const callerTypedCtx = buildCallerTypedCtx()
   // Per-caller typed-param map: caller's own params that F/G already narrowed
   // (so transitive `sum(arr)` inside a func that took `arr` from above resolves).
   const callerTypedParamsCtx = new Map()

package/src/compile/peel-stencil.js

@@ -0,0 +1,261 @@
+// Edge-clamp peeling for box-filter / stencil loops.
+//
+// A stencil loop reads `arr[clamp(iv + k, 0, BOUND-1)]` for a window of taps k ∈
+// [-r, r]. The clamp guards the array edges, but for the interior iv ∈ [r, BOUND-r)
+// every `iv + k` is already in range, so the clamp is a proven no-op there. Per-tap
+// the branch is cheap-but-not-free, and it blocks the marching-pointer / SIMD lift
+// of the inner accumulation. Measured ~18% of the box-blur pass.
+//
+// Split the loop over `iv` (whose bound is the clamp's BOUND) into three runs —
+// left edge [0, xs), clamp-free interior [xs, xe), right edge [xe, BOUND) — where
+// xs = min(r, BOUND), xe = max(xs, BOUND - r). The interior copy has the clamp `if`
+// dropped (the bare `iv + k` index remains). Bit-exact: for iv ∈ [r, BOUND-r),
+// iv+k ∈ [iv-r, iv+r] ⊆ [0, BOUND-1].
+//
+// Recognized (post-prepare AST): a `while (iv < BOUND)` loop whose body contains a
+// clamp `ci = iv + k; if (ci < 0) ci = 0; else if (ci >= BOUND) ci = BOUND-1` whose
+// BOUND is the SAME var as the loop bound and whose `k` is a tap-loop IV ranging
+// [-r, r] (`k = -r … k <= r`). Both hblur (peel the x-loop) and vblur (peel the
+// y-loop) match. Number literals are sparse-array holes (`n[0]` is undefined), so
+// literal tests use `== null`; created literals are bare numbers.
+
+import { findMutations } from './analyze-scans.js'
+
+const litN = (n, k) => Array.isArray(n) && n.length === 2 && n[0] == null && n[1] === k
+const isVar = (n) => typeof n === 'string'
+
+// `k = -r`: prepared as ['u-', r] (unary minus) or ['-', 0, r].
+const negOf = (n) => Array.isArray(n) && n[0] === 'u-' ? n[1]
+  : (Array.isArray(n) && n[0] === '-' && litN(n[1], 0) ? n[2] : null)
+
+// Every write to `iv` in `node` is a strictly-positive step (++iv / iv+=1 / iv=iv+1),
+// so iv advances monotonically — required so the three split loops partition [0,bound)
+// and the clamp-free interior never re-runs at an edge index. Any other write → false.
+const ASSIGN = new Set(['=', '+=', '-=', '*=', '/=', '%=', '&=', '|=', '^=', '<<=', '>>=', '>>>=', '**=', '&&=', '||=', '??='])
+function ivMonotonic(node, iv) {
+  if (!Array.isArray(node)) return true
+  if ((node[0] === '++' || node[0] === '--') && node[1] === iv) return node[0] === '++'
+  if (ASSIGN.has(node[0]) && node[1] === iv) {
+    if (node[0] === '+=' && litN(node[2], 1)) return true
+    if (node[0] === '=' && Array.isArray(node[2]) && node[2][0] === '+'
+      && ((node[2][1] === iv && litN(node[2][2], 1)) || (node[2][2] === iv && litN(node[2][1], 1)))) return true
+    return false   // any other assignment to iv (=, -=, *=, …) breaks monotonicity
+  }
+  return node.every(c => ivMonotonic(c, iv))
+}
+
+// Vars assigned inside any closure in the function — a call in the loop can mutate
+// them even though findMutations (direct writes only) misses it. iv/bound/r in this
+// set must bail (same class as the loop-SR closure-mutation guard).
+const collectAssigns = (n, out) => {
+  if (!Array.isArray(n)) return
+  if (typeof n[1] === 'string' && (ASSIGN.has(n[0]) || n[0] === '++' || n[0] === '--')) out.add(n[1])
+  n.forEach(c => collectAssigns(c, out))
+}
+const closureMutated = (n, out) => {
+  if (!Array.isArray(n)) return out
+  if (n[0] === '=>') collectAssigns(n, out)
+  n.forEach(c => closureMutated(c, out))
+  return out
+}
+let _cm = new Set()
+
+// Find, anywhere in `node`, a clamp `if (ci < 0) ci = 0; else if (ci >= B) ci = B-1`
+// over a var `ci` and bound var `B`. Returns { ci, bound } or null (first match).
+function findClamp(node) {
+  if (!Array.isArray(node)) return null
+  if (node[0] === 'if') {
+    const [, cond, then, els] = node
+    // outer: if (ci < 0) ci = 0; else <inner>
+    if (Array.isArray(cond) && cond[0] === '<' && isVar(cond[1]) && litN(cond[2], 0)
+      && Array.isArray(then) && then[0] === '=' && then[1] === cond[1] && litN(then[2], 0)
+      && Array.isArray(els) && els[0] === 'if') {
+      const ci = cond[1], [, c2, t2] = els
+      // inner: if (ci >= B) ci = B-1
+      if (Array.isArray(c2) && c2[0] === '>=' && c2[1] === ci && isVar(c2[2])
+        && Array.isArray(t2) && t2[0] === '=' && t2[1] === ci
+        && Array.isArray(t2[2]) && t2[2][0] === '-' && t2[2][1] === c2[2] && litN(t2[2][2], 1))
+        return { ci, bound: c2[2], node }
+    }
+  }
+  for (const c of node) { const r = findClamp(c); if (r) return r }
+  return null
+}
+
+// `ci = iv + k` (or `k + iv`) assignment/decl: returns { iv, tap } given the clamp var.
+function clampSource(node, ci) {
+  let found = null
+  const visit = (n) => {
+    if (found || !Array.isArray(n)) return
+    if (n[0] === '=' && n[1] === ci && Array.isArray(n[2]) && n[2][0] === '+') {
+      const [, a, b] = n[2]
+      if (isVar(a) && isVar(b)) found = { a, b }
+    }
+    n.forEach(visit)
+  }
+  visit(node)
+  return found
+}
+
+// The tap IV must range EXACTLY [-r, r]: a loop `while (t <= r)` AND `t` seeded to
+// `-r` (same `r`). Returns the radius var `r` only when both match; null otherwise.
+// Asymmetric / wider ranges would make xs=r, xe=bound-r unsound, so they bail.
+function tapRadius(loopBody, tap) {
+  let boundR = null, initR = null
+  const visit = (n) => {
+    if (!Array.isArray(n)) return
+    // tap loop bound `k <= r`: while (cond at [1]) or for (cond at [2]).
+    const cond = n[0] === 'while' ? n[1] : n[0] === 'for' ? n[2] : null
+    if (Array.isArray(cond) && cond[0] === '<=' && cond[1] === tap && isVar(cond[2])) boundR = cond[2]
+    // tap init `k = -r` (a bare assignment, or inside the for's `let` init clause).
+    if (n[0] === '=' && n[1] === tap) { const neg = negOf(n[2]); if (isVar(neg)) initR = neg }
+    n.forEach(visit)
+  }
+  visit(loopBody)
+  return boundR != null && boundR === initR ? boundR : null
+}
+
+// Count every write (=, compound-assign, ++/--) to variable `v` in `node`.
+function countWrites(node, v) {
+  let n = 0
+  const visit = (x) => {
+    if (!Array.isArray(x)) return
+    if ((x[0] === '++' || x[0] === '--') && x[1] === v) n++
+    else if (ASSIGN.has(x[0]) && x[1] === v) n++
+    x.forEach(visit)
+  }
+  visit(node)
+  return n
+}
+
+// Count tap-shaped seeds (`tap = -r`) and bounds (`tap <= r`) in `body`. The peel is
+// sound only for a SINGLE tap loop; two loops sharing the tap var make tapRadius pick
+// the wrong (last-seen) radius, so xs=r/xe=bound-r no longer match the clamped loop.
+function tapStructures(body, tap) {
+  let seeds = 0, bounds = 0
+  const visit = (n) => {
+    if (!Array.isArray(n)) return
+    const cond = n[0] === 'while' ? n[1] : n[0] === 'for' ? n[2] : null
+    if (Array.isArray(cond) && cond[0] === '<=' && cond[1] === tap && isVar(cond[2])) bounds++
+    if (n[0] === '=' && n[1] === tap && isVar(negOf(n[2]))) seeds++
+    n.forEach(visit)
+  }
+  visit(body)
+  return { seeds, bounds }
+}
+
+// True if `iv` is written anywhere INSIDE a nested loop within `body`. Then iv is not
+// constant across the tap accumulation (e.g. an `iv++` living inside the tap loop, so
+// the real outer step is 2r+1), and the per-outer-iteration peel is unsound.
+function ivWrittenInNestedLoop(body, iv) {
+  let found = false
+  const visit = (n, inLoop) => {
+    if (!Array.isArray(n)) return
+    if (inLoop && (((n[0] === '++' || n[0] === '--') && n[1] === iv) || (ASSIGN.has(n[0]) && n[1] === iv))) found = true
+    const deeper = inLoop || n[0] === 'while' || n[0] === 'for'
+    n.forEach(c => visit(c, deeper))
+  }
+  visit(body, false)
+  return found
+}
+
+let _uniq = 0
+
+// Drop the clamp `if` node from a (cloned) body, leaving the bare `ci = iv + k`.
+const dropClamp = (node, clampNode) =>
+  !Array.isArray(node) ? node
+    : node === clampNode ? ['{}', [';']]   // empty block (the if is a statement)
+    : node.map(c => dropClamp(c, clampNode))
+
+// A strictly-positive +1 step on `iv` (the for-loop increment): i++, ++i, i+=1, i=i+1.
+const stepIsPosInc = (s, iv) => {
+  if (!Array.isArray(s)) return false
+  let inc = s
+  if (s[0] === '-' && litN(s[2], 1) && Array.isArray(s[1]) && s[1][0] === '++') inc = s[1]
+  if (inc[0] === '++' && inc[1] === iv) return true
+  if (s[0] === '+=' && s[1] === iv && litN(s[2], 1)) return true
+  return s[0] === '=' && s[1] === iv && Array.isArray(s[2]) && s[2][0] === '+'
+    && ((s[2][1] === iv && litN(s[2][2], 1)) || (s[2][2] === iv && litN(s[2][1], 1)))
+}
+
+function tryPeel(stmt) {
+  if (!Array.isArray(stmt)) return null
+  // Normalize while / for into (iv, bound, body, init, step). For a `while`, the
+  // increment is inside the body; for a `for` it is the separate step clause, which
+  // we re-append to each split loop's body (converting the for into init + whiles).
+  let iv, bound, body, init = null, step = null
+  if (stmt[0] === 'while') {
+    const cond = stmt[1]
+    if (!Array.isArray(cond) || cond[0] !== '<' || !isVar(cond[1])) return null
+    iv = cond[1]; bound = cond[2]; body = stmt[2]
+  } else if (stmt[0] === 'for') {
+    init = stmt[1]; const cond = stmt[2]; step = stmt[3]; body = stmt[4]
+    if (!Array.isArray(cond) || cond[0] !== '<' || !isVar(cond[1])) return null
+    iv = cond[1]; bound = cond[2]
+    if (!stepIsPosInc(step, iv)) return null
+  } else return null
+  if (!isVar(bound) || !Array.isArray(body)) return null
+  // A loop whose body is a single statement (e.g. an outer row loop wrapping one
+  // inner loop — the vertical blur pass) isn't a `;` sequence; normalize it.
+  if (body[0] !== ';') body = [';', body]
+
+  const clamp = findClamp(body)
+  if (!clamp || clamp.bound !== bound) return null   // clamp bound must be this loop's bound
+  const src = clampSource(body, clamp.ci)
+  if (!src) return null
+  // ci = a + b: one operand is the loop IV, the other the tap IV
+  const tap = src.a === iv ? src.b : src.b === iv ? src.a : null
+  if (!tap) return null
+  const r = tapRadius(body, tap)
+  if (r == null) return null
+
+  // The clamp var must be written EXACTLY three times: its `ci = iv+k` source and the
+  // two clamp branches (`ci=0`, `ci=bound-1`). Any extra write — `ci = ci-1`, `ci = -ci`
+  // between the source and the clamp — changes what value the clamp actually guards, so
+  // dropping the clamp in the interior (which assumes the guarded value is iv+k) is
+  // unsound. Three is the exact count for a well-formed clamp; more ⇒ a mutation.
+  if (countWrites(body, clamp.ci) !== 3) return null
+  // Exactly one tap loop (one seed, one bound): two loops sharing the tap var would let
+  // tapRadius pick the wrong radius.
+  const ts = tapStructures(body, tap)
+  if (ts.seeds !== 1 || ts.bounds !== 1) return null
+  // iv must be constant across the tap accumulation — not bumped inside the tap loop.
+  if (ivWrittenInNestedLoop(body, iv)) return null
+
+  // Soundness: iv advances monotonically (else the interior re-runs at an edge index),
+  // and bound/r are loop-invariant (else the once-computed xs/xe go stale mid-loop).
+  if (!ivMonotonic(body, iv)) return null
+  const mut = new Set(); findMutations(body, new Set([bound, r]), mut)
+  if (mut.has(bound) || mut.has(r)) return null
+  if (_cm.has(iv) || _cm.has(bound) || _cm.has(r)) return null  // closure-mutable → unsafe
+
+  const id = _uniq++
+  const xs = `__pks${id}`, xe = `__pke${id}`
+  // xs = r < bound ? r : bound ;  xe = (bound - r) > xs ? bound - r : xs
+  const seed = ['let',
+    ['=', xs, ['?:', ['<', r, bound], r, bound]],
+    ['=', xe, ['?:', ['>', ['-', bound, r], xs], ['-', bound, r], xs]]]
+  const interiorBody = dropClamp(body, clamp.node)
+  // for: append the step to each split loop's body; while: body already increments.
+  const mk = (B, bod) => ['while', ['<', iv, B], step ? [';', ...bod.slice(1), step] : bod]
+  const loops = [mk(xs, body), mk(xe, interiorBody), mk(bound, body)]
+  return init ? [init, seed, ...loops] : [seed, ...loops]
+}
+
+function walk(node) {
+  if (!Array.isArray(node)) return node
+  const n = node.map(walk)
+  if (n[0] !== ';') return n
+  const out = [';']
+  for (let k = 1; k < n.length; k++) {
+    const r = tryPeel(n[k])
+    if (r) out.push(...r)
+    else out.push(n[k])
+  }
+  return out
+}
+
+export function peelClampedStencil(body) {
+  _cm = closureMutated(body, new Set())
+  return walk(body)
+}

package/src/compile/plan/advise.js

@@ -1,4 +1,4 @@
-import { ctx, warn } from '../../ctx.js'
+import { ctx, warn, err } from '../../ctx.js'
 import { refsName, REFS_IN_EXPR } from '../../ast.js'
 import { intLiteralValue } from '../../static.js'
 import { VAL } from '../../reps.js'
@@ -307,10 +307,64 @@ function adviseSimdLoops() {
 }
 
 /** Compile-time advisories at end of plan — extensible home for soft warnings. */
+// Generic-dispatch deopt advisory. A module global indexed inside a loop whose type
+// never resolved to a container (its VAL stays null — "any") lowers EVERY `g[i]` to
+// the runtime tag-dispatch path (__typed_idx / string fork): ~13× slower than a proven
+// typed load, and almost always a MISSED type rather than intentional polymorphism — a
+// loop-hot indexed container has one kind in practice (jz's value model already handles
+// genuinely-polymorphic parser data efficiently; that's a different regime). Like TS
+// flagging `any`, surface the bailout so it's fixed at the source — a `new T()`-typed
+// global, or an `instanceof`/`+` guard — instead of silently paying the cliff. Scoped to
+// module globals: their type is final here (params/locals resolve only at emit). Strict
+// mode, which already rejects dynamic features, escalates this to a hard error.
+function adviseGenericDispatch() {
+  if (!ctx.warnings && !ctx.transform.strict) return
+  const globals = ctx.scope.userGlobals
+  if (!globals?.size) return
+  const isGeneric = (name) => globals.has(name) && !ctx.scope.globalValTypes?.get(name)
+  // A global narrowed by `g instanceof Ctor` / `typeof g` in this function reads
+  // through the refined fast path — the user already applied the recommended fix,
+  // so flagging it would be noise. (Refinements are emit-time; this AST probe is
+  // the sound, conservative suppressor — a guard anywhere in the fn silences it.)
+  const guarded = (body) => {
+    const set = new Set()
+    const scan = (n) => {
+      if (!Array.isArray(n)) return
+      // Raw forms (strict mode skips jzify, so `instanceof`/`typeof` survive)…
+      if ((n[0] === 'instanceof' || n[0] === 'typeof') && typeof n[1] === 'string') set.add(n[1])
+      // …and the lowered predicate jzify emits — `g instanceof Float64Array` becomes
+      // `__is_typed(g)`, `typeof g === 'string'` becomes `__is_str(g)`, etc.
+      else if (n[0] === '()' && typeof n[1] === 'string' && n[1].startsWith('__is') && typeof n[2] === 'string') set.add(n[2])
+      for (let i = 1; i < n.length; i++) scan(n[i])
+    }
+    scan(body)
+    return set
+  }
+  for (const func of ctx.func.list) {
+    if (func.raw || !func.body) continue
+    const fn = func.name
+    const narrowed = guarded(func.body)
+    const walk = (node, inLoop) => {
+      if (!Array.isArray(node)) return
+      const op = node[0]
+      if (op === '[]' && inLoop && typeof node[1] === 'string' && isGeneric(node[1]) && !narrowed.has(node[1])) {
+        const g = node[1]
+        const msg = `'${g}' is indexed (\`${g}[…]\`) in a loop but its type never resolved — every access falls back to runtime dynamic dispatch (~10× slower than a typed load). Give it one provable kind: assign \`${g} = new Float64Array(…)\`, or narrow with \`instanceof\`/\`+\`.`
+        if (ctx.transform.strict) err(`strict mode: ${msg} Pass { strict: false } to allow dynamic dispatch.`)
+        warn('deopt-generic', msg, { fn }, node.loc)
+      }
+      const nowLoop = inLoop || HEAP_LOOP_OPS.has(op)
+      for (let i = 1; i < node.length; i++) walk(node[i], nowLoop)
+    }
+    walk(func.body, false)
+  }
+}
+
 export function adviseProgram(programFacts) {
   adviseHeapGrowth()
   adviseSetMapIterationOrder()
   if (programFacts) adviseJsstringCarrier(programFacts.paramReps, programFacts.valueUsed)
   adviseSimdLoops()
+  adviseGenericDispatch()
 }