jz 0.5.1 → 0.7.0

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

@@ -0,0 +1,370 @@
+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'
+import { adviseJsstringCarrier } from '../narrow.js'
+
+/** Compile-time advisories — heap growth, Map iteration order, SIMD hints. */
+const HEAP_LOOP_OPS = new Set(['for', 'for-in', 'for-of', 'while', 'do', 'do-while'])
+const HEAP_VALS = new Set([
+  VAL.ARRAY, VAL.STRING, VAL.OBJECT, VAL.HASH, VAL.SET, VAL.MAP,
+  VAL.CLOSURE, VAL.TYPED, VAL.REGEX, VAL.BUFFER,
+])
+
+function returnsHeap(func) {
+  if (func.sig.ptrKind != null) return true
+  return func.valResult != null && HEAP_VALS.has(func.valResult)
+}
+
+function isHeapAlloc(node) {
+  if (!Array.isArray(node)) return false
+  const op = node[0]
+  if (op === '{}') {
+    // `['{}', [';', …]]` is a block body, not an object literal.
+    if (node.length === 2 && Array.isArray(node[1]) && node[1][0] === ';') return false
+    return node.length > 1
+  }
+  if (op === '[]') return node.length === 2
+  if (op === '()' && Array.isArray(node[1]) && node[1][0] === '.') {
+    const method = node[1][2]
+    if (method === 'push' || method === 'concat') return true
+  }
+  return false
+}
+
+function containsHeapAlloc(node) {
+  if (!Array.isArray(node)) return false
+  if (isHeapAlloc(node)) return true
+  for (let i = 1; i < node.length; i++)
+    if (containsHeapAlloc(node[i])) return true
+  return false
+}
+
+function heapLoopBody(node) {
+  if (!Array.isArray(node) || !HEAP_LOOP_OPS.has(node[0])) return null
+  return node[node.length - 1]
+}
+
+function heapLoopAllocSites(body) {
+  const sites = []
+  const walk = (node) => {
+    if (!Array.isArray(node)) return
+    if (HEAP_LOOP_OPS.has(node[0])) {
+      const lb = heapLoopBody(node)
+      if (lb && containsHeapAlloc(lb))
+        sites.push({ loc: node.loc ?? lb.loc })
+    }
+    for (let i = 1; i < node.length; i++) walk(node[i])
+  }
+  walk(body)
+  return sites
+}
+
+function bodyHeapAllocates(body) {
+  return body != null && containsHeapAlloc(body)
+}
+
+/** Mirrors `applyArenaRewind` eligibility in src/assemble.js (AST-level). */
+function isArenaRewindable(func) {
+  if (func.raw) return false
+  if (func.sig.params.length !== 0) return false
+  if (func.sig.results.length !== 1) return false
+  if (func.sig.ptrKind != null) return false
+  if (returnsHeap(func)) return false
+  if (func.sig.results[0] === 'f64' && func.valResult !== VAL.NUMBER && func.valResult != null)
+    return false
+  if (func.sig.results[0] !== 'f64' && func.sig.results[0] !== 'i32') return false
+  return bodyHeapAllocates(func.body)
+}
+
+function exportedFuncNames() {
+  const names = new Set()
+  for (const [key, val] of Object.entries(ctx.func.exports)) {
+    const name = val === true ? key : (typeof val === 'string' ? val : null)
+    if (name) names.add(name)
+  }
+  return names
+}
+
+/** Bump-allocator growth advisories — no-op without an `opts.warnings` sink. */
+function adviseHeapGrowth() {
+  if (!ctx.warnings) return
+  if (ctx.transform.alloc === false) return
+
+  const exported = exportedFuncNames()
+
+  for (const func of ctx.func.list) {
+    if (func.raw || !func.body) continue
+
+    const fn = func.name
+    const isExport = exported.has(fn)
+
+    if (isExport && returnsHeap(func)) {
+      warn('heap-return',
+        `export '${fn}' returns a heap value — repeated calls grow linear memory; call memory.reset() between batches from the host`,
+        { fn }, func.body.loc)
+      continue
+    }
+
+    const loopSites = heapLoopAllocSites(func.body)
+    for (const site of loopSites) {
+      warn('heap-loop',
+        `${isExport ? `export '${fn}'` : `'${fn}'`} allocates heap values inside a loop — peak memory grows with trip count; call memory.reset() between batches from the host`,
+        { fn }, site.loc)
+    }
+
+    if (isExport && !returnsHeap(func) && bodyHeapAllocates(func.body)
+        && !isArenaRewindable(func) && loopSites.length === 0) {
+      const code = func.sig.params.length > 0 ? 'arena-rewind-skipped' : 'heap-per-call'
+      const detail = func.sig.params.length > 0
+        ? `export '${fn}' allocates heap values but cannot rewind per call (parameters or returned pointers prevent arena rewind)`
+        : `export '${fn}' allocates heap values — jz does not reclaim between calls`
+      warn(code,
+        `${detail}; call memory.reset() between batches from the host`,
+        { fn }, func.body.loc)
+    }
+  }
+}
+
+const SET_MAP_ITER_OPS = new Set(['for-in', 'for-of'])
+const SET_MAP_METHODS = new Set(['keys', 'values', 'entries', 'forEach'])
+const SET_MAP_SLOT_ORDER = 'uses slot order, not insertion order — results may differ from JavaScript'
+
+function newSetMapKind(node) {
+  if (!Array.isArray(node)) return null
+  if (node[0] === 'new') {
+    const ctor = node[1]
+    const name = typeof ctor === 'string' ? ctor
+      : Array.isArray(ctor) && ctor[0] === '()' && typeof ctor[1] === 'string' ? ctor[1]
+      : null
+    if (name === 'Set') return 'set'
+    if (name === 'Map') return 'map'
+  }
+  if (node[0] === '()' && typeof node[1] === 'string') {
+    if (node[1] === 'new.Set') return 'set'
+    if (node[1] === 'new.Map') return 'map'
+  }
+  return null
+}
+
+function collectSetMapBindings(body) {
+  const bindings = new Map()
+  const walk = (node) => {
+    if (!Array.isArray(node)) return
+    const op = node[0]
+    if (op === 'let' || op === 'const') {
+      for (let i = 1; i < node.length; i++) {
+        const d = node[i]
+        if (!Array.isArray(d) || d[0] !== '=' || typeof d[1] !== 'string') continue
+        const kind = newSetMapKind(d[2])
+        if (kind) bindings.set(d[1], kind)
+      }
+    }
+    for (let i = 1; i < node.length; i++) walk(node[i])
+  }
+  walk(body)
+  return bindings
+}
+
+function exprSetMapKind(expr, bindings) {
+  const direct = newSetMapKind(expr)
+  if (direct) return direct
+  return typeof expr === 'string' ? bindings.get(expr) || null : null
+}
+
+function isJsonStringifyCall(node) {
+  if (!Array.isArray(node) || node[0] !== '()') return false
+  const callee = node[1]
+  if (callee === 'JSON.stringify') return true
+  return Array.isArray(callee) && callee[0] === '.' && callee[1] === 'JSON' && callee[2] === 'stringify'
+}
+
+function adviseSetMapIterationOrder() {
+  if (!ctx.warnings) return
+
+  for (const func of ctx.func.list) {
+    if (func.raw || !func.body) continue
+    const fn = func.name
+    const bindings = collectSetMapBindings(func.body)
+
+    const warnOrder = (msg, loc) => warn('set-map-order', msg, { fn }, loc)
+    const label = (kind) => kind === 'set' ? 'Set' : 'Map'
+
+    const walk = (node) => {
+      if (!Array.isArray(node)) return
+      const op = node[0]
+
+      if (SET_MAP_ITER_OPS.has(op)) {
+        const kind = exprSetMapKind(node[2], bindings)
+        if (kind) warnOrder(`${label(kind)} iteration ${SET_MAP_SLOT_ORDER}`, node.loc ?? node[2]?.loc)
+      }
+
+      if (op === '()' && Array.isArray(node[1]) && node[1][0] === '.') {
+        const [, recv, method] = node[1]
+        const kind = SET_MAP_METHODS.has(method) ? exprSetMapKind(recv, bindings) : null
+        if (kind) warnOrder(`${label(kind)}.${method}() ${SET_MAP_SLOT_ORDER}`, node.loc ?? recv?.loc)
+      }
+
+      if (isJsonStringifyCall(node)) {
+        const kind = exprSetMapKind(node[2], bindings)
+        if (kind) warnOrder(`JSON.stringify on a ${kind} serializes entries in slot order, not insertion order — output may differ from JavaScript`, node.loc)
+      }
+
+      if (op === '...') {
+        const kind = exprSetMapKind(node[1], bindings)
+        if (kind) warnOrder(`spread over a ${kind} follows slot order, not insertion order — element order may differ from JavaScript`, node.loc)
+      }
+
+      for (let i = 1; i < node.length; i++) walk(node[i])
+    }
+    walk(func.body)
+  }
+}
+
+function forInductionVar(step) {
+  if (!Array.isArray(step)) return null
+  if (step[0] === '++' || step[0] === '--') return typeof step[1] === 'string' ? step[1] : null
+  if (step[0] === '-' && Array.isArray(step[1]) && step[1][0] === '++')
+    return typeof step[1][1] === 'string' ? step[1][1] : null
+  if ((step[0] === '+=' || step[0] === '-=') && step[2]?.[0] == null && step[2]?.[1] === 1)
+    return typeof step[1] === 'string' ? step[1] : null
+  return null
+}
+
+function indexStrideOnVar(indexExpr, iv) {
+  if (!Array.isArray(indexExpr)) return 1
+  const op = indexExpr[0]
+  if (indexExpr === iv) return 1
+  if (op === '[]' && indexExpr[2] === iv) return 1
+  if (op === '*' && ((indexExpr[1] === iv && intLiteralValue(indexExpr[2]) > 1)
+    || (indexExpr[2] === iv && intLiteralValue(indexExpr[1]) > 1)))
+    return intLiteralValue(indexExpr[1] === iv ? indexExpr[2] : indexExpr[1])
+  if (op === '+') {
+    for (let i = 1; i < indexExpr.length; i++) {
+      const s = indexStrideOnVar(indexExpr[i], iv)
+      if (s > 1) return s
+    }
+  }
+  return 1
+}
+
+const SIMD_REDUCE_OPS = new Set(['+=', '|=', '&=', '^=', '-=', '*=', '/=', '%='])
+
+function simdLoopIssues(body, iv) {
+  let indexed = false, carried = false, maxStride = 1
+  const walk = (node) => {
+    if (!Array.isArray(node)) return
+    const op = node[0]
+    if (op === '=>') return
+    if (op === '[]' && node.length === 3) {
+      const idx = node[2]
+      if (idx === iv || (Array.isArray(idx) && refsName(idx, iv, REFS_IN_EXPR))) indexed = true
+      const stride = indexStrideOnVar(idx, iv)
+      if (stride > maxStride) maxStride = stride
+    }
+    if (SIMD_REDUCE_OPS.has(op) && typeof node[1] === 'string' && node[1] !== iv) carried = true
+    if (op === '=' && typeof node[1] === 'string' && node[1] !== iv) {
+      const rhs = node[2]
+      if (rhs === node[1] || (Array.isArray(rhs) && refsName(rhs, node[1], REFS_IN_EXPR))) carried = true
+    }
+    for (let i = 1; i < node.length; i++) walk(node[i])
+  }
+  walk(body)
+  return { indexed, carried, maxStride }
+}
+
+function adviseSimdLoops() {
+  if (!ctx.warnings) return
+  if (ctx.transform.optimize?.vectorizeLaneLocal === false) return
+
+  for (const func of ctx.func.list) {
+    if (func.raw || !func.body) continue
+    const fn = func.name
+
+    const walk = (node) => {
+      if (!Array.isArray(node)) return
+      if (node[0] === 'for' && node.length >= 5) {
+        const [, , , step, body] = node
+        const iv = forInductionVar(step)
+        if (iv) {
+          const { indexed, carried, maxStride } = simdLoopIssues(body, iv)
+          if (indexed && carried) {
+            warn('simd-loop-carried',
+              `'${fn}' loop carries a scalar updated each iteration — SIMD vectorization skipped; split the reduction or use a separate accumulator`,
+              { fn }, node.loc)
+          }
+          if (indexed && maxStride > 1) {
+            warn('simd-aos-stride',
+              `'${fn}' indexed access stride ${maxStride} on loop counter — split into one typed array per field for SIMD (array-of-structures blocks vectorization)`,
+              { fn }, node.loc)
+          }
+        }
+      }
+      for (let i = 1; i < node.length; i++) walk(node[i])
+    }
+    walk(func.body)
+  }
+}
+
+/** 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()
+}
+