jz 0.8.0 → 0.9.0

package/src/compile/inplace-store.js

@@ -0,0 +1,329 @@
+/**
+ * In-place replace-store eligibility sweep — the immutable-update idiom
+ * (`arr[i] = { x, y, … }` in a loop) allocates a fresh object per element per
+ * step. When no alias can observe the difference, overwriting the OLD
+ * element's payload slots is bit-identical and allocation-free.
+ *
+ * Identity change is the only observable: after `arr[i] = fresh`, reading
+ * `arr[i].f` yields the new value either way; only a SAVED alias to the old
+ * element — field-read after the store, identity-compared, or stored
+ * elsewhere — distinguishes fresh-object from in-place. So a store site is
+ * eligible iff the whole program provably creates no such alias for that
+ * schema:
+ *
+ *  1. Schema-S values may appear in a VALUE position (call arg, return,
+ *     container/slot store, comparison, bare use) ONLY as fresh `{}` literals
+ *     — an OBJECT-typed NAME in value position aliases its object → poison S
+ *     (unknown sid → poison all). `.field` receivers are safe (atomic read).
+ *  2. Element reads of maybe-object arrays may only be (a) an immediate
+ *     `.field` receiver, or (b) the whole init RHS of a single-decl binding
+ *     (a tracked ALIAS). Anything else → poison the array's elem sid.
+ *  3. `for…of` over a maybe-object array binds untracked element aliases →
+ *     poison its elem sid.
+ *  4. A candidate store `arr[i] = {lit}` (elem sid of arr == sid of lit, all
+ *     lit slot values NUMBER — no ephemeral pointers stored into a possibly
+ *     durable receiver) is valid iff its sid survives 1-3, every tracked
+ *     alias of that sid lives in the SAME function, same statement block,
+ *     declared before the store, and never mentioned in a later statement of
+ *     that block (block-scoped per iteration, so next-iteration uses re-read).
+ *     Mentions inside the store statement itself are fine — the emit spills
+ *     the literal's values before overwriting.
+ *
+ * Result: `ctx.schema.inplaceStores = WeakSet<literalNode>` — consulted by
+ * emitElementAssign, which emits the guarded in-place fast path (old box has
+ * OBJECT tag + sid S → slot stores; anything else → the generic fresh-alloc
+ * path, so runtime aliens stay bit-exact).
+ */
+import { ctx } from '../ctx.js'
+import { analyzeBody } from './analyze.js'
+import { staticObjectProps } from '../static.js'
+import { VAL } from '../reps.js'
+
+/** Canonical content key for a store site — the ','-wrapper around literal
+ *  props is normalized away between plan and emit, so flatten before
+ *  serializing. Shared by the sweep and emitElementAssign. */
+export const inplaceKey = (arrName, lit) => {
+  const props = lit.slice(1)
+  const flat = props.length === 1 && Array.isArray(props[0]) && props[0][0] === ',' ? props[0].slice(1) : props
+  return `${arrName}|${JSON.stringify(flat)}`
+}
+
+// env-gated debug — dist/jz.js runs in browsers where `process` doesn't exist
+const DBG = typeof process !== 'undefined' && process.env.JZ_DBG_INPLACE
+
+const CONTAINER_METHODS = new Set(['push', 'unshift', 'splice', 'fill', 'set', 'add'])
+
+export function scanInplaceStores(programFacts) {
+  const poisoned = new Set()   // sids with a possible surviving alias
+  let poisonAll = false
+  const aliases = []           // { fn, sid, name, block, declIdx }
+  const candidates = []        // { fn, sid, lit, block, stmtIdx, arrName }
+
+  const paramReps = programFacts.paramReps
+
+  // Element facts for params narrow.js leaves untracked (exported functions):
+  // meet over INTERNAL call sites. Zero internal call sites → only the host
+  // can call, and host-marshaled containers are fresh deep copies (interop
+  // wrapVal) that cannot alias any compile-internal object → non-aliasing.
+  // Any unprovable internal arg → maybe-object with unknown sid.
+  const _csCache = new Map()
+  const callSiteElemInfo = (fnName, k) => {
+    const key = fnName + ' ' + k
+    if (_csCache.has(key)) return _csCache.get(key)
+    let mayBeObject = false, sid = null, seen = 0
+    for (const cs of programFacts.callSites || []) {
+      if (cs.callee !== fnName) continue
+      seen++
+      const arg = cs.argList?.[k]
+      const cf = cs.callerFunc
+      const cfacts = cf?.body && !cf.raw ? analyzeBody(cf.body) : null
+      let proven = false
+      if (typeof arg === 'string' && cfacts) {
+        if (cfacts.typedElems?.has(arg) || cfacts.locals?.get(arg) === 'typed') proven = true
+        else {
+          const ev = cfacts.arrElemValTypes?.get(arg)
+          if (ev != null && ev !== VAL.OBJECT) proven = true
+          const s = cfacts.arrElemSchemas?.get(arg)
+          if (s != null) { mayBeObject = true; sid = sid == null || sid === s ? s : -1; proven = true }
+        }
+      }
+      if (!proven) { mayBeObject = true; sid = -1 }
+    }
+    const r = { sid: sid === -1 ? null : sid, mayBeObject: seen === 0 ? false : mayBeObject }
+    _csCache.set(key, r)
+    return r
+  }
+
+  for (const fn of ctx.func.list) {
+    if (!fn.body || fn.raw) continue
+    const facts = analyzeBody(fn.body)
+    const reps = paramReps?.get(fn.name)
+    const paramIdx = new Map(fn.sig.params.map((p, k) => [p.name, k]))
+
+    // Element info for an array-valued name: elem sid (if known) and whether
+    // elements could be schema objects at all (typed/NUMBER/STRING elems can't).
+    const elemInfo = (name) => {
+      if (typeof name !== 'string') return { sid: null, mayBeObject: true }
+      if (facts.typedElems?.has(name) || facts.locals?.get(name) === 'typed') return { sid: null, mayBeObject: false }
+      let sid = facts.arrElemSchemas?.get(name)
+      let ev = facts.arrElemValTypes?.get(name)
+      const k = paramIdx.get(name)
+      if (k != null) {
+        const r = reps?.get(k)
+        if (r) {
+          if (r.typedElem != null || r.val === VAL.TYPED) return { sid: null, mayBeObject: false }
+          if (sid == null) sid = r.arrayElemSchema
+          if (ev == null) ev = r.arrayElemValType
+        }
+        if (sid == null && (ev == null || ev === VAL.OBJECT)) {
+          // untracked param (exported fn) — derive from internal call sites
+          const cs = callSiteElemInfo(fn.name, k)
+          if (!cs.mayBeObject) return { sid: null, mayBeObject: false }
+          if (sid == null) sid = cs.sid
+        }
+      }
+      if (sid == null && ev != null && ev !== VAL.OBJECT) return { sid: null, mayBeObject: false }
+      return { sid: sid ?? null, mayBeObject: true }
+    }
+    const poisonElem = (name) => {
+      const { sid, mayBeObject } = elemInfo(name)
+      if (!mayBeObject) return
+      if (sid != null) poisoned.add(sid)
+      else { poisonAll = true; if (DBG) console.error('[inplace-poisonAll] elem read of', name, 'in', fn.name) }
+    }
+    // A NAME in value position: aliases its object if OBJECT-typed. An S value
+    // can only reach an unknown-typed name through a path poisoned elsewhere,
+    // so unknown types are ignored (conservatism lives at the leak sites).
+    const poisonName = (name) => {
+      const vt = facts.valTypes?.get(name) ?? (paramIdx.has(name) ? reps?.get(paramIdx.get(name))?.val : null)
+      if (vt !== VAL.OBJECT) return
+      const sid = ctx.schema.vars?.get(name) ?? (paramIdx.has(name) ? reps?.get(paramIdx.get(name))?.schemaId : null)
+      if (sid != null) poisoned.add(sid)
+      else { poisonAll = true; if (DBG) console.error('[inplace-poisonAll] OBJECT name', name, 'in', fn.name) }
+    }
+
+    const litSid = (lit) => {
+      const parsed = staticObjectProps(lit.slice(1))
+      return parsed ? ctx.schema.register(parsed.names) : null
+    }
+
+    // value-position walk; `stmts`/`stmtIdx` track the innermost statement
+    // block so alias decls and stores get comparable positions
+    const walkVal = (n, stmts, stmtIdx) => {
+      if (!Array.isArray(n)) { if (typeof n === 'string') poisonName(n); return }
+      const op = n[0]
+      if (typeof op !== 'string') return
+      if (op === 'str') return
+      if (op === '{}') { for (let i = 1; i < n.length; i++) walkSlotValues(n[i], stmts, stmtIdx); return }
+      if (op === '.' || op === '?.') {
+        // receiver is a safe atomic read — an element-read receiver is fine,
+        // a NAME receiver doesn't alias
+        const r = n[1]
+        if (Array.isArray(r) && r[0] === '[]') { if (typeof r[1] === 'string') { /* arr[i].f — safe */ } else walkVal(r[1], stmts, stmtIdx); if (r[2] != null) walkVal(r[2], stmts, stmtIdx) }
+        else if (Array.isArray(r)) walkVal(r, stmts, stmtIdx)
+        return
+      }
+      if (op === '[]' && n.length === 3) {
+        // element read in value position — a leak unless provably non-object
+        if (typeof n[1] === 'string') poisonElem(n[1])
+        else walkVal(n[1], stmts, stmtIdx)
+        if (n[2] != null) walkVal(n[2], stmts, stmtIdx)
+        return
+      }
+      for (let i = 1; i < n.length; i++) walkVal(n[i], stmts, stmtIdx)
+    }
+    // `{}` literal slot values: `[':' key value]` pairs (or `,`-joined) —
+    // nested fresh literals are fine, everything else is a value position
+    const walkSlotValues = (n, stmts, stmtIdx) => {
+      if (!Array.isArray(n)) { if (typeof n === 'string') poisonName(n); return }
+      if (n[0] === ',') { for (let i = 1; i < n.length; i++) walkSlotValues(n[i], stmts, stmtIdx); return }
+      if (n[0] === ':') { walkVal(n[2], stmts, stmtIdx); return }
+      walkVal(n, stmts, stmtIdx)
+    }
+
+    const walkStmt = (n, stmts, stmtIdx) => {
+      if (!Array.isArray(n)) { if (typeof n === 'string') poisonName(n); return }
+      const op = n[0]
+      // statement-position '{}' is a BLOCK (post-prepare bodies are
+      // ['{}', [';', ...stmts]]), not an object literal
+      if (op === ';' || op === '{' || op === '{}') {
+        const list = n.slice(1)
+        for (let i = 0; i < list.length; i++) walkStmt(list[i], list, i)
+        return
+      }
+      if (op === 'let' || op === 'const') {
+        for (let i = 1; i < n.length; i++) {
+          const d = n[i]
+          if (!Array.isArray(d) || d[0] !== '=') { walkVal(d, stmts, stmtIdx); continue }
+          const [, lhs, rhs] = d
+          if (typeof lhs === 'string' && Array.isArray(rhs) && rhs[0] === '[]' && rhs.length === 3 && typeof rhs[1] === 'string') {
+            // tracked alias: whole-RHS element read into a single binding
+            const { sid, mayBeObject } = elemInfo(rhs[1])
+            if (mayBeObject) {
+              if (sid != null) aliases.push({ fn, sid, name: lhs, block: stmts, declIdx: stmtIdx, arr: rhs[1], idx: typeof rhs[2] === 'string' ? rhs[2] : null })
+              else { poisonAll = true; if (DBG) console.error('[inplace-poisonAll] alias unknown-sid', lhs, 'of', rhs[1], 'in', fn.name) }
+            }
+            if (rhs[2] != null) walkVal(rhs[2], stmts, stmtIdx)
+            continue
+          }
+          walkVal(rhs, stmts, stmtIdx)
+        }
+        return
+      }
+      if (op === '=' && Array.isArray(n[1]) && n[1][0] === '[]' && n[1].length === 3 && typeof n[1][1] === 'string') {
+        const [, lhs, rhs] = n
+        if (lhs[2] != null) walkVal(lhs[2], stmts, stmtIdx)
+        if (Array.isArray(rhs) && rhs[0] === '{}') {
+          const { sid, mayBeObject } = elemInfo(lhs[1])
+          const s = mayBeObject ? litSid(rhs) : null
+          if (s != null && s === sid) candidates.push({ fn, sid: s, lit: rhs, block: stmts, stmtIdx, arrName: lhs[1], idxName: typeof lhs[2] === 'string' ? lhs[2] : null })
+          // literal is a fresh value — walk only its slot values
+          for (let i = 1; i < rhs.length; i++) walkSlotValues(rhs[i], stmts, stmtIdx)
+        } else walkVal(rhs, stmts, stmtIdx)
+        return
+      }
+      if (op === 'for-of') {
+        // `for (const p of arr)` binds untracked element aliases
+        const src = n[2]
+        if (typeof src === 'string') poisonElem(src)
+        else walkVal(src, stmts, stmtIdx)
+        for (let i = 3; i < n.length; i++) walkStmt(n[i], stmts, stmtIdx)
+        return
+      }
+      if (op === '=>') {
+        // closure body: value-walk everything (captured aliases poison via names)
+        for (let i = 1; i < n.length; i++) walkVal(n[i], stmts, stmtIdx)
+        return
+      }
+      if (op === 'for' || op === 'while' || op === 'do' || op === 'if' || op === 'for-in') {
+        // for is flat post-prepare: ['for', init, cond, step, body]
+        for (let i = 1; i < n.length; i++) walkStmt(n[i], stmts, stmtIdx)
+        return
+      }
+      // container-method calls: literal args are fresh single-home values
+      if (op === '()' && Array.isArray(n[1]) && (n[1][0] === '.') && CONTAINER_METHODS.has(n[1][2])) {
+        if (typeof n[1][1] !== 'string') walkVal(n[1][1], stmts, stmtIdx)
+        const argNode = n[2]
+        const args = argNode == null ? [] : (Array.isArray(argNode) && argNode[0] === ',') ? argNode.slice(1) : [argNode]
+        for (const a of args) {
+          if (Array.isArray(a) && a[0] === '{}') { for (let i = 1; i < a.length; i++) walkSlotValues(a[i], stmts, stmtIdx) }
+          else walkVal(a, stmts, stmtIdx)
+        }
+        return
+      }
+      walkVal(n, stmts, stmtIdx)
+    }
+
+    walkStmt(fn.body, null, 0)
+  }
+
+  const containsName = (n, name) => {
+    if (n === name) return true
+    if (!Array.isArray(n)) return false
+    for (let i = (n[0] === 'str' ? n.length : 1); i < n.length; i++) if (containsName(n[i], name)) return true
+    return false
+  }
+
+  // Content-keyed result: per-function body transforms and emit-time inlining
+  // between plan and emit rebuild the tree (and splice bodies across function
+  // frames), so neither node identity nor the enclosing function name survives
+  // to emitElementAssign. A `receiver|literal` content key is sound only if
+  // EVERY same-content candidate program-wide validates — group and meet.
+  // (An inliner that RENAMES the receiver makes the key miss → no transform —
+  // safe in the conservative direction.)
+  // Target-binding reuse: when THE tracked alias of a store site reads the
+  // SAME array at the SAME plain-name index, and every statement between its
+  // decl and the store is a pure local decl (no calls, no writes to the array
+  // or the index — nothing that could rebind arr[i]), the emit can overwrite
+  // through the alias binding directly instead of re-reading the element
+  // (`__arr_idx` + forwarding + bounds, per iteration). Field writes to the
+  // alias itself between are fine — the store overwrites every slot anyway.
+  const impureBetween = (n, idxName, arrName) => {
+    if (!Array.isArray(n)) return false
+    const op = n[0]
+    if (op === '()' || op === 'new' || op === 'await' || op === 'yield') return true
+    if (op === '=' || op === '++' || op === '--' || (typeof op === 'string' && op.length > 1 && op.endsWith('=') && !op.endsWith('==') && op !== '>=' && op !== '<=')) {
+      const t = n[1]
+      if (t === idxName || t === arrName) return true
+      if (Array.isArray(t) && t[0] === '[]' && t[1] === arrName) return true
+    }
+    for (let i = op === 'str' ? n.length : 1; i < n.length; i++) if (impureBetween(n[i], idxName, arrName)) return true
+    return false
+  }
+
+  const verdict = new Map()  // key → false | { alias, idx } | { alias: null }
+  for (const c of candidates) {
+    const key = inplaceKey(c.arrName, c.lit)
+    let ok = !poisonAll && !poisoned.has(c.sid)
+    for (const a of aliases) {
+      if (!ok) break
+      if (a.sid !== c.sid) continue
+      // an alias in another function (or another block) could live across the
+      // call/iteration into this store — reject
+      if (a.fn !== c.fn || a.block !== c.block || a.declIdx >= c.stmtIdx) { ok = false; break }
+      // any mention after the store in the same block observes the overwrite
+      for (let i = c.stmtIdx + 1; i < c.block.length && ok; i++)
+        if (containsName(c.block[i], a.name)) ok = false
+    }
+    let reuse = null
+    if (ok && c.idxName) for (const a of aliases) {
+      if (a.fn !== c.fn || a.block !== c.block || a.sid !== c.sid) continue
+      if (a.declIdx >= c.stmtIdx || a.arr !== c.arrName || a.idx !== c.idxName) continue
+      let pure = true
+      for (let i = a.declIdx + 1; i < c.stmtIdx && pure; i++)
+        pure = !impureBetween(c.block[i], c.idxName, c.arrName)
+      if (pure) { reuse = { alias: a.name, idx: a.idx }; break }
+    }
+    // meet across same-content sites: validity ANDs; reuse must agree exactly
+    const prev = verdict.get(key)
+    if (!ok || prev === false) verdict.set(key, false)
+    else if (prev === undefined) verdict.set(key, reuse ?? { alias: null })
+    else if (prev.alias !== (reuse?.alias ?? null) || (prev.alias && prev.idx !== reuse.idx)) verdict.set(key, { alias: null })
+    if (ok && DBG) console.error('[inplace-ok]', c.fn.name, c.arrName, 'sid', c.sid, reuse ? 'reuse ' + reuse.alias : '')
+  }
+  const out = new Map()
+  for (const [key, v] of verdict) if (v) out.set(key, v)
+  ctx.schema.inplaceStores = out
+  if (DBG) console.error('[inplace]', 'candidates:', candidates.length, 'aliases:', aliases.length, 'poisoned:', [...poisoned], 'poisonAll:', poisonAll, 'eligible:', candidates.filter(c => out.has(c.lit)).length)
+  return out
+}

package/src/compile/loop-recurrence.js

@@ -0,0 +1,167 @@
+// Partial unroll (×2) + scalar replacement of a unit-stride ARRAY RECURRENCE.
+//
+// A DP/scan loop that reads `arr[j-1]` and writes `arr[j]` (unit stride) carries the
+// just-written value to the next iteration THROUGH MEMORY: it stores `arr[j]`, then the next
+// iteration loads `arr[j-1]` — the very cell it just wrote. V8/TurboFan forwards that store→load
+// and unrolls the loop internally; Cranelift/wasmtime and the baseline tiers do neither, so the
+// loop pays a store→load round trip plus full per-iteration overhead on every cell. clang/gcc
+// fix exactly this with this transform — measured 2.15× on wasmtime for the Levenshtein DP
+// (V8-neutral, bit-exact).
+//
+// Recognized (post-prepare AST): a unit-stride `for (let j = LO; j </<= HI; j++)` whose body, for
+// ONE array `arr`, has a single store `arr[j] = <var>` and ≥1 read `arr[j-1]`, accesses `arr` at
+// no other index, never aliases `arr` elsewhere, and contains no call / nested loop / break /
+// continue / return / closure. The `arr[j-1]` read becomes a scalar `left` seeded from `arr[LO-1]`
+// and refreshed after each store; the body is then unrolled ×2 (with a 1-cell tail) so the carry
+// between the paired cells lives in a register and the loop overhead is halved. A `LO <= HI` guard
+// keeps the seed load in step with the original (which reads `arr[LO-1]` only when it iterates),
+// and falls back to the untouched loop on the empty range — sound for any trip count.
+
+import { findMutations } from './analyze-scans.js'
+import { litVal, litN, unitIncVar, normalizeLoop, freshLoopId } from './loop-model.js'
+import { rewriteBlocks, closureMutatedVars } from './loop-model.js'
+
+const isArr = (n) => Array.isArray(n)   // wrap (not alias): the self-host kernel rejects a builtin used as a first-class value
+const clone = (n) => isArr(n) ? n.map(clone) : n
+const isIvMinus1 = (n, iv) => isArr(n) && n[0] === '-' && n[1] === iv && litN(n[2], 1)   // (iv - 1)
+
+// Ops whose presence makes duplicating the body in place unsound (control that escapes the cell,
+// or a call that could alias/mutate `arr` or reorder side effects).
+const REJECT = new Set(['for', 'while', 'do', 'for-in', 'for-of', 'break', 'continue', 'return',
+  'throw', 'switch', 'try', 'catch', 'finally', '=>', 'label'])
+const hasUnsafe = (n) => {
+  if (!isArr(n)) return false
+  if (REJECT.has(n[0])) return true
+  if (n[0] === '()' && typeof n[1] === 'string') return true   // function call `f(args)`
+  return n.some(hasUnsafe)
+}
+
+// Substitute every value-reference of `iv` with (iv + 1); leave the op slot and property keys.
+const subPlus1 = (n, iv) => {
+  if (n === iv) return ['+', iv, 1]
+  if (!isArr(n)) return n
+  if (n[0] === '.' && n.length === 3) return ['.', subPlus1(n[1], iv), n[2]]
+  return [n[0], ...n.slice(1).map(c => subPlus1(c, iv))]
+}
+
+// Rename every let/const-DECLARED var in `stmts` with a suffix, throughout — so the 2nd unrolled
+// cell's locals don't collide with the 1st. Loop-carried outer vars (assigned, not declared here)
+// are untouched, so the recurrence still threads through them.
+function renameDecls(stmts, suf) {
+  const declared = new Set()
+  const collect = (n) => {
+    if (!isArr(n)) return
+    if (n[0] === 'let' || n[0] === 'const')
+      for (let k = 1; k < n.length; k++) if (isArr(n[k]) && n[k][0] === '=' && typeof n[k][1] === 'string') declared.add(n[k][1])
+    n.forEach(collect)
+  }
+  stmts.forEach(collect)
+  if (!declared.size) return stmts
+  const ren = (n) => {
+    if (typeof n === 'string') return declared.has(n) ? n + suf : n
+    if (!isArr(n)) return n
+    if (n[0] === '.' && n.length === 3) return ['.', ren(n[1]), n[2]]
+    return [n[0], ...n.slice(1).map(ren)]
+  }
+  return stmts.map(ren)
+}
+
+// Replace `arr[iv-1]` reads with `left`; keep the store; emit `left = storeVal` after each store.
+function scalarReplace(stmts, arr, iv, left, storeVal) {
+  const repl = (n) => {
+    if (!isArr(n)) return n
+    if (n[0] === '[]' && n[1] === arr && isIvMinus1(n[2], iv)) return left
+    if (n[0] === '.' && n.length === 3) return ['.', repl(n[1]), n[2]]
+    return [n[0], ...n.slice(1).map(repl)]
+  }
+  const out = []
+  for (const s of stmts) {
+    out.push(repl(s))
+    if (isArr(s) && s[0] === '=' && isArr(s[1]) && s[1][0] === '[]' && s[1][1] === arr && s[1][2] === iv)
+      out.push(['=', left, storeVal])
+  }
+  return out
+}
+
+function tryUnroll(stmt, cm) {
+  const L = normalizeLoop(stmt)
+  if (!L || L.kind !== 'for') return null
+  const body = L.body
+  if (!isArr(body) || body[0] !== ';') return null
+  const iv = unitIncVar(L.step)
+  if (!iv) return null
+
+  // init `let iv = LO`, LO a literal ≥ 1 (so arr[LO-1] is a valid in-bounds index)
+  if (!(isArr(L.init) && L.init[0] === 'let' && isArr(L.init[1]) && L.init[1][0] === '=' && L.init[1][1] === iv)) return null
+  const LO = L.init[1][2], loVal = litVal(LO)
+  if (loVal == null || loVal < 1) return null
+
+  // cond `iv <= HI` / `iv < HI`, HI loop-invariant
+  if (!(isArr(L.cond) && (L.cond[0] === '<=' || L.cond[0] === '<') && L.cond[1] === iv)) return null
+  const cmpOp = L.cond[0], HI = L.cond[2]
+  if (!(typeof HI === 'string' || litVal(HI) != null)) return null
+
+  if (hasUnsafe(body)) return null
+  const stmts = body.slice(1)
+
+  // exactly one store `arr[iv] = <var>` — the recurrence array + carried value
+  let arr = null, storeVal = null, nStore = 0
+  for (const s of stmts)
+    if (isArr(s) && s[0] === '=' && isArr(s[1]) && s[1][0] === '[]' && s[1][2] === iv) {
+      if (typeof s[2] !== 'string') return null
+      arr = s[1][1]; storeVal = s[2]; nStore++
+    }
+  if (nStore !== 1 || typeof arr !== 'string') return null
+  if (storeVal === iv || storeVal === arr) return null
+
+  // every `arr[...]` is `arr[iv]` or `arr[iv-1]`, the only write is the store, ≥1 recurrence read,
+  // and `arr` never appears bare (passed/aliased)
+  let hasRec = false, bad = false
+  const scan = (n) => {
+    if (!isArr(n)) return
+    if (n[0] === '[]' && n[1] === arr) {
+      if (n[2] === iv) {} else if (isIvMinus1(n[2], iv)) hasRec = true; else bad = true
+    }
+    if (n[0] === '=' && isArr(n[1]) && n[1][0] === '[]' && n[1][1] === arr && n[1][2] !== iv) bad = true
+    if (!(n[0] === '[]' || n[0] === '.')) for (let k = 1; k < n.length; k++) if (n[k] === arr) bad = true
+    n.forEach(scan)
+  }
+  scan(body)
+  if (bad || !hasRec) return null
+
+  // The carry `left = storeVal` is emitted right after the store, so a recurrence read AFTER the
+  // store would see this cell's value, not arr[iv-1]. Require every arr[iv-1] read to precede it.
+  const storeIdx = stmts.findIndex(s => isArr(s) && s[0] === '=' && isArr(s[1]) && s[1][0] === '[]' && s[1][1] === arr && s[1][2] === iv)
+  const readsRec = (n) => isArr(n) && ((n[0] === '[]' && n[1] === arr && isIvMinus1(n[2], iv)) || n.some(readsRec))
+  for (let k = storeIdx + 1; k < stmts.length; k++) if (readsRec(stmts[k])) return null
+
+  // iv assigned only by the step; iv/arr/HI loop-invariant (not mutated, incl. via a closure call)
+  const ivMut = new Set(); findMutations(body, new Set([iv]), ivMut)
+  if (ivMut.has(iv)) return null
+  if (cm.has(iv) || cm.has(arr)) return null
+  if (typeof HI === 'string') { const hiMut = new Set(); findMutations(body, new Set([HI]), hiMut); if (hiMut.has(HI) || cm.has(HI)) return null }
+
+  // --- transform ---
+  const id = freshLoopId()
+  const left = `__rec${id}`
+  const bodyS = scalarReplace(stmts, arr, iv, left, storeVal)
+  const cellJ = () => bodyS.map(clone)
+  const cellJ1 = renameDecls(bodyS.map(s => subPlus1(clone(s), iv)), `$r${id}`)
+
+  const seed = ['let', ['=', left, ['[]', arr, loVal - 1]]]          // left = arr[LO-1]
+  const letIv = ['let', ['=', iv, clone(LO)]]                        // let iv = LO
+  const twoFit = cmpOp === '<=' ? ['<', iv, clone(HI)] : ['<', iv, ['-', clone(HI), 1]]
+  const main = ['while', twoFit,
+    [';', ['{}', [';', ...cellJ()]], ['{}', [';', ...cellJ1]], ['=', iv, ['+', iv, 2]]]]
+  const tail = ['if', [cmpOp, iv, clone(HI)],
+    ['{}', [';', ...cellJ(), ['=', iv, ['+', iv, 1]]]]]
+  const block = ['{}', [';', letIv, seed, main, tail]]
+  // Run the unrolled form only on a non-empty range (so the seed's arr[LO-1] load matches the
+  // original, which reads it only when it iterates); otherwise the untouched loop.
+  return [['if', [cmpOp, clone(LO), clone(HI)], block, stmt]]
+}
+
+export function unrollRecurrence(body) {
+  const cm = closureMutatedVars(body)
+  return rewriteBlocks(body, stmt => tryUnroll(stmt, cm))
+}