@asmlift/core 0.1.0

package/src/raise/retsink.ts

@@ -0,0 +1,72 @@
+// asmlift — return-sinking (F-CFG-class structural pass; successor-aware, ISA-neutral).
+//
+// A short-circuit `if (a && b) return X; return Y;` (and the `||` / value-returning variants) compiles to
+// a diamond whose arms converge on a single RETURN block: `br ^merge(X)` / `br ^merge(Y)` into
+// `^merge(v): ret v`. The structurer lowers that merge as a shared VARIABLE — `v0 = X … v0 = Y … return v0`
+// — which is byte-exact-CORRECT but recompiles DIFFERENTLY from the source: agbcc/gcc, given the natural
+// `if (a==0) return Y; if (b==0) return Y; return X;` (early returns), re-share the return block and match;
+// given the merge-variable spelling they materialise the merge differently and MISS (verified on `ifand`).
+// The fix is a classic transform: TAIL-DUPLICATE a return-only merge block into each predecessor that
+// reaches it by an unconditional branch — replace `br ^merge(v)` with `ret v` and drop the now-unreachable
+// merge. The structurer then emits early returns in each arm (it already duplicates a shared arm block),
+// which recompiles to the compiler's shared-return form. Purely structural: no new IR/AST vocabulary.
+//
+// GATE — only the SHORT-CIRCUIT shape, never a simple value-select. A single-condition select
+// (`c ? x : y`, and the branchless-compare idioms `clamp0`/`le0`/…) also converges two arms on a return
+// merge, but there the compiler emits the MERGE-VARIABLE form, which is what byte-matches — sinking it
+// would REGRESS those. The distinguishing signal is structural: a short-circuit chain converges on a
+// SHARED arm (the common early-exit reached from ≥2 conditions, so it has ≥2 predecessors), whereas a
+// simple diamond's arms each have exactly one predecessor. So sink only when some branch-predecessor of
+// the merge is itself shared (≥2 preds); every simple select stays a merge var.
+//
+// This does NOT recover the boolean-VALUE form `return a && b` — that is shortcircuit.ts's job
+// (the `logic_and`/`logic_or` connective plus agbcc's `(-b|b)>>31` = `b!=0` normalisation).
+import { Block, Fn, mkOp, predecessors } from '../ir/core';
+
+/** Tail-duplicate a return-only merge block into its unconditional-branch predecessors, but ONLY in the
+ *  short-circuit shape (some branch-pred is shared). Returns whether anything changed. A "return-only"
+ *  block is exactly one `ret` whose operands are all its own block-params, so each predecessor already
+ *  carries the returned value as a successor arg. */
+export function sinkReturns(fn: Fn): boolean {
+  let changed = false;
+  const preds = predecessors(fn);
+  const isBrTo = (p: Block, m: Block) => {
+    const t = p.ops[p.ops.length - 1];
+    return t.opcode === 'br' && t.successors.length === 1 && t.successors[0].block === m;
+  };
+  for (const m of [...fn.blocks]) {
+    if (m.ops.length !== 1) {
+      continue;
+    }
+    const ret = m.ops[0];
+    if (ret.opcode !== 'ret') {
+      continue;
+    }
+    // Every returned value must be a param of this block (so it comes in on the edge). A `ret` of a
+    // value computed elsewhere, or of a non-param, can't be reconstructed from the predecessor's args.
+    if (!ret.operands.every((o) => m.params.includes(o))) {
+      continue;
+    }
+    const ps = preds.get(m) ?? [];
+    const brPreds = ps.filter((p) => isBrTo(p, m));
+    if (brPreds.length === 0) {
+      continue;
+    }
+    // SHORT-CIRCUIT GATE: at least one branch-pred must be a shared block (≥2 preds of its own). A simple
+    // single-condition select has only single-pred arms and is left as a merge variable (which matches).
+    if (!brPreds.some((p) => (preds.get(p)?.length ?? 0) >= 2)) {
+      continue;
+    }
+    for (const p of brPreds) {
+      const args = p.ops[p.ops.length - 1].successors[0].args;
+      const sunk = ret.operands.map((o) => args[m.params.indexOf(o)]);
+      p.ops[p.ops.length - 1] = mkOp('ret', { operands: sunk });
+      changed = true;
+    }
+    // If no predecessor still branches to m (all were unconditional), it is unreachable — drop it.
+    if (brPreds.length === ps.length && fn.blocks[0] !== m) {
+      fn.blocks = fn.blocks.filter((b) => b !== m);
+    }
+  }
+  return changed;
+}

package/src/raise/shortcircuit.ts

@@ -0,0 +1,207 @@
+// asmlift — boolean-value short-circuit recovery (F-CFG; successor-aware, agbcc-class).
+//
+// `return a && b` compiles (agbcc) to a value-producing diamond: `if (a==0) result=0; else result=(b!=0)`,
+// where the merge block returns the phi. The structurer lowers that as `if (a==0){v0=0}else{v0=(-b|b)>>31}
+// return v0` — which misses, because (1) the merge is a variable, not the `&&` expression, and (2) the
+// second operand is agbcc's branchless `(-b|b)>>31` bool-normalisation, not a clean `b != 0`. This module
+// recovers the `logic_and`/`logic_or` value so the backend prints `a != 0 && b != 0`, which recompiles to
+// the exact diamond. Two passes:
+//
+//   1. recognizeBoolNormalize — fold `(-x | x) >> 31` (logical) into `x != 0` (icmp_ne). This is agbcc's
+//      branchless "is-nonzero", and it is what the short-circuit second operand looks like.
+//   2. recognizeShortCircuit — collapse a SIMPLE boolean diamond into one connective. The head H ends
+//      `cond_br(cond)[…]`; one edge goes straight to the merge M carrying a boolean CONSTANT 0/1; the other
+//      goes to a single-predecessor block B that computes a boolean Vb and `br M(Vb)`. Then the phi is
+//      `cond ? const : Vb` (or the mirror), which is a `&&`/`||` of `cond` (or its negation) and `Vb`:
+//        head-edge = taken, const 0 → !cond && Vb       head-edge = fall, const 0 →  cond && Vb
+//        head-edge = taken, const 1 →  cond || Vb       head-edge = fall, const 1 → !cond || Vb
+//      B's (pure) ops are hoisted into H, the phi is replaced by the connective, and H `br M`.
+//
+// The feeder Vb may be a boolean OP (→ `logic_and`/`logic_or`) or itself a CONSTANT 0/1 (then the diamond
+// is just `cond ? 0 : 1` = the condition or its negation, no connective). Because the fold is applied
+// ITERATIVELY (a merge with >2 predecessors collapses one diamond at a time, each reducing the pred
+// count), a `&&`-CHAIN like `a > 0 && b > 0 && …` — a shared const-0 exit reached from every condition —
+// folds bottom-up: the innermost diamond becomes a bare condition, which the next diamond consumes as its
+// Vb, and so on. SCOPE: the shared-arm must be reachable as a single-predecessor `br` feeder; the `||`
+// form where the const-1 "true" block has TWO predecessors (`return a || b`) is not folded.
+// Guards stay conservative: the CONST is exactly 0/1, Vb is a bool op or 0/1 const, the head condition is a
+// negatable icmp, and any deviation falls through untouched (a miss, never a miscompile).
+import { Block, Fn, Op, Value, defOpMap, mkOp, mkValue, predecessors, replaceAllUsesWith } from '../ir/core';
+import type { Opcode } from '../ir/opcodes';
+import { EFFECTFUL_OPS } from '../ir/opcodes';
+import { T } from '../ir/types';
+
+const NEGATE_ICMP: Record<string, Opcode> = {
+  icmp_eq: 'icmp_ne',
+  icmp_ne: 'icmp_eq',
+  icmp_slt: 'icmp_sge',
+  icmp_sge: 'icmp_slt',
+  icmp_sgt: 'icmp_sle',
+  icmp_sle: 'icmp_sgt',
+  icmp_ult: 'icmp_uge',
+  icmp_uge: 'icmp_ult',
+  icmp_ugt: 'icmp_ule',
+  icmp_ule: 'icmp_ugt',
+};
+const BOOL_OPS = new Set([...Object.keys(NEGATE_ICMP), 'logic_and', 'logic_or']);
+// Ops with an observable side effect — unsafe to HOIST out of a short-circuit's conditional arm
+// (they would run unconditionally). Derived from the ONE effect table in ir/opcodes.ts.
+const SIDE_EFFECT = EFFECTFUL_OPS;
+
+/** Fold `(-x | x) >> 31` (logical shift) → `x != 0`, in place. agbcc's branchless is-nonzero idiom. */
+// NOT exported: it must run before the diamond fold, an ordering only recognizeShortCircuit's
+// internal call preserves.
+function recognizeBoolNormalize(fn: Fn): boolean {
+  let changed = false;
+  const defs = defOpMap(fn);
+  for (const b of fn.blocks) {
+    for (let i = 0; i < b.ops.length; i++) {
+      const op = b.ops[i];
+      if (op.opcode !== 'shr_u' || op.attrs.imm !== 31 || op.operands.length !== 1) {
+        continue;
+      }
+      const orOp = defs.get(op.operands[0]);
+      if (!orOp || orOp.opcode !== 'or') {
+        continue;
+      }
+      const [p, q] = orOp.operands; // one operand of the `or` must be `neg` of the other
+      const negP = defs.get(p),
+        negQ = defs.get(q);
+      const x =
+        negP?.opcode === 'neg' && negP.operands[0] === q
+          ? q
+          : negQ?.opcode === 'neg' && negQ.operands[0] === p
+            ? p
+            : null;
+      if (!x) {
+        continue;
+      }
+      const zero = mkValue(T.unk(32));
+      const c0 = mkOp('const', { results: [zero], attrs: { value: 0 } });
+      const ne = mkOp('icmp_ne', { operands: [x, zero], results: [op.results[0]] }); // reuse the result Value
+      b.ops.splice(i, 1, c0, ne);
+      defs.set(op.results[0], ne);
+      i++; // skip past the inserted icmp_ne
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+/** Collapse a simple boolean short-circuit diamond into one `logic_and`/`logic_or`, in place. */
+export function recognizeShortCircuit(fn: Fn): boolean {
+  let changed = recognizeBoolNormalize(fn);
+  const term = (b: Block) => b.ops[b.ops.length - 1];
+  const constOf = (defs: Map<Value, Op>, v: Value): number | null => {
+    const d = defs.get(v);
+    return d && d.opcode === 'const' ? (d.attrs.value as number) : null;
+  };
+  const isBool = (defs: Map<Value, Op>, v: Value): boolean => {
+    const d = defs.get(v);
+    return !!d && BOOL_OPS.has(d.opcode);
+  };
+
+  let progress = true;
+  while (progress) {
+    progress = false;
+    const defs = defOpMap(fn);
+    const preds = predecessors(fn);
+    outer: for (const m of fn.blocks) {
+      if (m.params.length !== 1) {
+        continue;
+      }
+      if ((preds.get(m) ?? []).length < 2) {
+        continue;
+      }
+      // Find a diamond among M's predecessors: a `br` feeder B whose SOLE predecessor H is a cond_br
+      // whose two successors are exactly {M, B}. (Per-feeder search — M may have >2 preds in a chain.)
+      for (const bfeed of preds.get(m)!) {
+        const bt = term(bfeed);
+        if (bt.opcode !== 'br' || bt.successors[0]?.block !== m) {
+          continue;
+        }
+        const bp = preds.get(bfeed) ?? [];
+        if (bp.length !== 1) {
+          continue;
+        }
+        const h = bp[0];
+        const ht = term(h);
+        if (ht.opcode !== 'cond_br') {
+          continue;
+        }
+        const [s0, s1] = ht.successors; // [taken, fall]
+        const mIsTaken = s0.block === m && s1.block === bfeed;
+        const mIsFall = s1.block === m && s0.block === bfeed;
+        if (!mIsTaken && !mIsFall) {
+          continue;
+        } // H's successors must be exactly {M, B}
+        const c = constOf(defs, (mIsTaken ? s0 : s1).args[0]); // the H→M edge carries the short-circuit const
+        if (c !== 0 && c !== 1) {
+          continue;
+        }
+        const vb = bt.successors[0].args[0]; // the value B carries to M — a bool op or a 0/1 const
+        const vbConst = constOf(defs, vb);
+        if (vbConst === null && !isBool(defs, vb)) {
+          continue;
+        } // else `cond ? const : Vb` isn't a connective
+        // A const/const diamond is only a (negated) condition, not a constant: `cond?0:1`/`cond?1:0`.
+        if (vbConst !== null && !((c === 0 && vbConst === 1) || (c === 1 && vbConst === 0))) {
+          continue;
+        }
+        // Reduce a const/const diamond ONLY in CHAIN context (M has >2 preds — it feeds an outer connective).
+        // A STANDALONE boolean-producing diamond (`return a > b`, M has 2 preds) is left as a merge variable:
+        // folding it to a bare comparison can LOSE the spelling the compiler emitted (verified: `ult5`
+        // regresses), and the branch-sense candidate already spells the merge both ways.
+        if (vbConst !== null && preds.get(m)!.length <= 2) {
+          continue;
+        }
+        const cond = ht.operands[0];
+        const condDef = defs.get(cond);
+        if (!condDef || !NEGATE_ICMP[condDef.opcode]) {
+          continue;
+        } // head condition must be a negatable icmp
+
+        // The `cond`-side operand is negated iff `cond` guards the short-circuit (taken+0 / fall+1).
+        const wantNeg = (c === 0 && mIsTaken) || (c === 1 && mIsFall);
+        const before = (op: Op) => h.ops.splice(h.ops.length - 1, 0, op); // insert just before H's terminator
+        // B's body is hoisted UNCONDITIONALLY into H (H always executes), so it MUST be side-effect free:
+        // a `store`/`astore`/`call` in B's arm would then run even when the short-circuit does NOT take B
+        // (e.g. `a && ((*p = x) != 0)` would store even when `a` is false) — a silent miscompile. Pure
+        // value ops (arith, loads, icmp) are safe: the structurer inlines them back into the `&&`/`||` RHS
+        // expression, where C's own short-circuit re-guards them. Any side effect ⇒ DECLINE the fold — the
+        // merge-variable spelling the fall-through leaves is correct (the side effect stays in B's block),
+        // just possibly non-matching.
+        if (bfeed.ops.slice(0, -1).some((op) => SIDE_EFFECT.has(op.opcode))) {
+          continue;
+        }
+        bfeed.ops.slice(0, -1).forEach(before); // hoist B's pure body (defines Vb; harmless if a dead const)
+        let condSide = cond;
+        if (wantNeg) {
+          condSide = mkValue(T.unk(32));
+          before(mkOp(NEGATE_ICMP[condDef.opcode], { operands: [...condDef.operands], results: [condSide] }));
+        }
+        // Vb const → the phi reduces to the (possibly negated) condition; Vb bool → a && / || connective.
+        let res = condSide;
+        if (vbConst === null) {
+          res = mkValue(T.unk(32));
+          before(mkOp(c === 0 ? 'logic_and' : 'logic_or', { operands: [condSide, vb], results: [res] }));
+        }
+        // If M still has OTHER predecessors after this collapse (a longer chain), keep the phi and feed the
+        // recovered value as its incoming arg from H — a later iteration folds the rest. Only when this was
+        // the last pair (M drops to a single predecessor) do we retire the phi and rewrite its uses.
+        if (preds.get(m)!.length > 2) {
+          h.ops[h.ops.length - 1] = mkOp('br', { successors: [{ block: m, args: [res] }] });
+        } else {
+          h.ops[h.ops.length - 1] = mkOp('br', { successors: [{ block: m, args: [] }] });
+          replaceAllUsesWith(fn, m.params[0], res); // the phi becomes the recovered boolean value
+          m.params = [];
+        }
+        fn.blocks = fn.blocks.filter((x) => x !== bfeed);
+        changed = true;
+        progress = true;
+        break outer; // defs/preds are stale after mutation — recompute on the next iteration
+      }
+    }
+  }
+  return changed;
+}

package/src/raise/softdiv.ts

@@ -0,0 +1,62 @@
+// asmlift — soft-division helper-call lowering (L1 recognition; agbcc/ARM-class targets).
+//
+// A target with no hardware divide lowers `a / b` (and unsigned / `%`) to a call to a compiler
+// RUNTIME HELPER: agbcc (ARM EABI) emits `bl __divsi3` with the dividend in r0, divisor in r1.
+// asmlift lifts that as an opaque `call{target:"__divsi3"}(a, b)`, which the backend can only spell
+// as the uncompilable `__divsi3(a, b)`. This pass:
+//   (a) supplies the helper SIGNATURES (RUNTIME_HELPERS) so the two arguments ARE recovered — merged
+//       into the frontend's prototype lookup, reusing the existing signature-driven arg recovery; and
+//   (b) rewrites the recognised call to the EXISTING division op (`sdiv`/`udiv`/`smod`/`umod` — the
+//       same 2-operand form the hardware-divide path emits), so type recovery types the operands'
+//       signedness and the structurer lowers it to `a / b` / `a % b`.
+// Re-emitting `a / b` recompiles to the same `bl __divsi3` byte-for-byte.
+//
+// Like array legalization (raise/arrays.ts), this is RECOGNITION the patterns-as-data idiom layer
+// cannot state: its match keys on a `call`'s STRING `target` attr, which the numeric `attrEquals`
+// cannot express. It is naturally inert on hardware-divide targets (which emit `div`/`divu`,
+// never `bl __divsi3`).
+import { Fn, mkOp } from '../ir/core';
+import type { Opcode } from '../ir/opcodes';
+import type { Prototypes } from '../proto';
+
+// runtime helper symbol → { the division op it computes, its argument count }.
+const SOFT_DIV: Record<string, { op: Opcode; params: number }> = {
+  __divsi3: { op: 'sdiv', params: 2 },
+  __udivsi3: { op: 'udiv', params: 2 },
+  __modsi3: { op: 'smod', params: 2 },
+  __umodsi3: { op: 'umod', params: 2 },
+};
+
+/** Signatures for the soft-division runtime helpers, so a `bl __divsi3` recovers both arguments.
+ *  Consumed by the frontend's arity lookup BEHIND any caller-supplied prototype (headers win). */
+export const RUNTIME_HELPERS: Prototypes = Object.fromEntries(
+  Object.entries(SOFT_DIV).map(([sym, h]) => [sym, { params: h.params }]),
+);
+
+/** Rewrite each recognised soft-division helper call to its division op, in place. Returns whether
+ *  anything changed. Runs BEFORE type recovery so the new op's operands get signed/unsigned typing. */
+export function recognizeSoftDiv(fn: Fn): boolean {
+  let changed = false;
+  for (const b of fn.blocks) {
+    for (let i = 0; i < b.ops.length; i++) {
+      const op = b.ops[i];
+      if (op.opcode !== 'call') {
+        continue;
+      }
+      const helper = SOFT_DIV[op.attrs.target as string];
+      if (!helper) {
+        continue;
+      }
+      // Fold only when BOTH arguments were recovered (the signature makes this the norm). A
+      // mis-recovered arity leaves the call untouched rather than fabricating a wrong divide.
+      if (op.operands.length !== helper.params || op.results.length !== 1) {
+        continue;
+      }
+      // Reuse the SAME result Value → every existing use already points at it (no RAUW needed).
+      const div = mkOp(helper.op, { operands: [...op.operands], results: [op.results[0]] });
+      b.ops.splice(i, 1, div);
+      changed = true;
+    }
+  }
+  return changed;
+}

package/src/raise/struct-arrays.ts

@@ -0,0 +1,257 @@
+// Array-of-struct recovery: the scaledAddress extension for NON-scalar strides. Recognizes the
+// element-pointer idiom `%elem = add(base, index * stride)` where the stride is read
+// AUTHORITATIVELY from the `mul #C` / `shl #k` constant in the machine code (the inversion of
+// m2c/Ghidra, which read stride from a supplied type). The element becomes a STRUCT whose fields
+// are the residual offsets of the loads/stores off %elem, so `load %elem {off=K}` becomes
+// `base[index].field_K`. Rewrites those into `aload`/`astore` carrying `fieldOff`. Byte-exact:
+// the element struct is given `size == stride` so its `sizeof` reproduces the observed
+// `mul #stride`.
+//
+// SCALAR-VS-STRUCT DISCRIMINATION (the question that kept this a prototype): a stride==width
+// single-field-at-0 access is a plain scalar array and must stay recognizeArrays' shape, not a
+// 1-field struct. Resolved by ORDER + the clean gate: this pass runs AFTER `arrays` in
+// PRE_RECOVERY_PASSES, so every shl-scaled stride==width off-0 access is already an aload (its
+// add is dead) before this pass looks; overlapping residues (off + width > stride) fail the
+// clean gate. The one shape that still lands here — a mul-by-power-of-2 the compiler chose over
+// shl, which real compilers do not emit — would recover as a 1-field struct: byte-identical
+// address math, merely less idiomatic. The mul/shl stride constant is what makes base/index
+// UNAMBIGUOUS here (the scaled operand is the index, read from the machine code) — the unscaled
+// `add(x, y)` byte form stays out of scope (genuinely ambiguous without types).
+import { Fn, Op, Value, defOpMap, mkOp } from '../ir/core';
+import { IrType, StructField, T, scalarTypeForAccess } from '../ir/types';
+
+interface Scaled {
+  base: Value;
+  index: Value;
+  stride: number;
+}
+
+// `%elem = add(base, index*stride)` — the scaled side is `mul(index, const)` or `shl(index, k)`.
+// The `add` is commutative. Returns the base/index/stride, stride read from the constant.
+function elementPointer(add: Op, defs: Map<Value, Op>): Scaled | null {
+  if (add.opcode !== 'add' || add.operands.length !== 2) {
+    return null;
+  }
+  for (const [s, o] of [
+    [0, 1],
+    [1, 0],
+  ] as const) {
+    const d = defs.get(add.operands[s]);
+    if (!d) {
+      continue;
+    }
+    if (d.opcode === 'mul' && d.operands.length === 2) {
+      const c0 = defs.get(d.operands[0]);
+      const c1 = defs.get(d.operands[1]);
+      if (c1?.opcode === 'const') {
+        return { base: add.operands[o], index: d.operands[0], stride: c1.attrs.value as number };
+      }
+      if (c0?.opcode === 'const') {
+        return { base: add.operands[o], index: d.operands[1], stride: c0.attrs.value as number };
+      }
+    }
+    if (d.opcode === 'shl' && d.operands.length === 1) {
+      return { base: add.operands[o], index: d.operands[0], stride: 1 << (d.attrs.imm as number) };
+    }
+  }
+  return null;
+}
+
+// Byte width of a recovered field type (pointer word-sized; array = elem × count).
+const byteSize = (t: IrType): number =>
+  t.kind === 'array' ? byteSize(t.elem) * t.count : t.kind === 'int' ? t.width / 8 : 4;
+
+// Interleave `u8[N]` PAD fields into a sorted data-field list so every data field lands at its exact
+// offset and the element's total size == stride. Makes the struct type SELF-DESCRIBING (no size-time
+// synthesis in the backend). `char`-style raw bytes are `u8` in the decomp type vocabulary.
+function withPadding(dataFields: StructField[], stride: number): StructField[] {
+  const out: StructField[] = [];
+  let cursor = 0,
+    pad = 0;
+  for (const f of dataFields) {
+    if (f.off > cursor) {
+      out.push({ off: cursor, type: T.array(T.u(8), f.off - cursor), name: `_pad${pad++}` });
+    }
+    out.push(f);
+    cursor = f.off + byteSize(f.type);
+  }
+  if (stride > cursor) {
+    out.push({ off: cursor, type: T.array(T.u(8), stride - cursor), name: `_pad${pad}` });
+  }
+  return out;
+}
+
+/** Recover array-of-struct element access. Returns the number of element-pointers recovered.
+ *
+ *  Element pointers are recovered PER (base, stride) GROUP, not per add: a compiler freely
+ *  rematerializes the same element address (several `add(base, i*stride)` ops for one logical
+ *  array), and recovering them one-by-one would let the first claim the base and force its
+ *  twins to decline — a mixed spelling that is worse than either pure form (found live on
+ *  pokeemerald:GetGender, whose address is materialized twice). A base whose element pointers
+ *  disagree on stride declines entirely: two strides over one base is a reinterpreted view or
+ *  a 2D layout, genuinely ambiguous — decline over guess. */
+export function recognizeStructArrays(fn: Fn): number {
+  const defs = defOpMap(fn);
+  let count = 0;
+
+  // group candidate element pointers by base, tracking each add's own index and stride
+  const byBase = new Map<Value, { add: Op; index: Value; stride: number }[]>();
+  for (const b of fn.blocks) {
+    for (const add of b.ops) {
+      const sc = elementPointer(add, defs);
+      if (sc && sc.stride > 0) {
+        const list = byBase.get(sc.base) ?? [];
+        list.push({ add, index: sc.index, stride: sc.stride });
+        byBase.set(sc.base, list);
+      }
+    }
+  }
+
+  for (const [base, elems] of byBase) {
+    // The base must be RETYPABLE: still `unknown` (this pass runs before recovery seeds it, and
+    // an already-recovered type must not be clobbered), agreed on ONE stride, and never itself a
+    // DIRECT memory base (`arr->x` alongside `arr[i].y`: the retype would make memAccess resolve
+    // the direct access against element fields it may not have).
+    if (base.type.kind !== 'unknown') {
+      continue;
+    }
+    const stride = elems[0].stride;
+    if (elems.some((e) => e.stride !== stride)) {
+      continue;
+    }
+    let clean = true;
+    for (const bb of fn.blocks) {
+      for (const op of bb.ops) {
+        if ((op.opcode === 'load' || op.opcode === 'store') && op.operands[0] === base) {
+          clean = false;
+        }
+      }
+    }
+
+    // Every use of every %elem — across ALL operand positions AND successor block-args (the
+    // IR's full use-set, adversarially learned: `store elem, elem {off}` hides elem at
+    // operand[1] of its own clean access; a branch can carry elem as a block arg the
+    // op-operand scan never sees, leaving a live sizeof-scaling add behind) — must be a
+    // load/store BASE with a field offset inside one element.
+    const elemSet = new Set(elems.map((e) => e.add.results[0]));
+    const indexOf = new Map(elems.map((e) => [e.add.results[0], e.index]));
+    const accesses: { op: Op; elem: Value; off: number; width: number; signed: boolean }[] = [];
+    for (const bb of fn.blocks) {
+      for (const op of bb.ops) {
+        const isMem = (op.opcode === 'load' || op.opcode === 'store') && elemSet.has(op.operands[0]);
+        if (op.operands.some((o, k) => elemSet.has(o) && (k > 0 || !isMem))) {
+          clean = false; // a non-base use — even inside an otherwise-clean access
+        }
+        if (op.successors.some((sx) => sx.args.some((a) => elemSet.has(a)))) {
+          clean = false; // carried into a block arg — a use the rewrite cannot see
+        }
+        if (isMem) {
+          const off = op.attrs.off as number,
+            width = op.attrs.width as number;
+          if (off < 0 || off + width > stride) {
+            clean = false;
+          }
+          accesses.push({
+            op,
+            elem: op.operands[0],
+            off,
+            width,
+            signed: op.opcode === 'load' ? (op.attrs.signed as boolean) : width === 4,
+          });
+        }
+      }
+    }
+    if (!clean || accesses.length === 0) {
+      continue;
+    }
+
+    // Build the element struct over the UNION of the group's accesses: one field per distinct
+    // offset, SIZE = stride (so sizeof matches). The offset set must describe a real C struct —
+    // the guards mirror structs.ts:
+    //   • same-offset accesses must agree on width (a conflict is a union view, not a field —
+    //     collapsing widths deleted a store's byte-range in the adversarial round);
+    //   • fields must not OVERLAP (withPadding assumes disjoint; an overlap silently shifts
+    //     every later field's physical offset);
+    //   • each field must be naturally aligned (off % width) and the stride divisible by the
+    //     widest field's alignment — otherwise the DECLARED layout (which C aligns) diverges
+    //     from the intended offsets and sizeof ≠ stride.
+    // Same-offset rules: widths must agree (any two accesses); LOAD signedness must agree —
+    // two loads reading one field with different extensions is a union view, and merging them
+    // silently drops one side's zero/sign-extension (adversarially learned: `arr[i].f +
+    // (u16)arr[i].f` lost its zext and a byte-exact match with it). A STORE's `signed` is the
+    // width===4 CONVENTION, not a machine fact, so it never conflicts — the field takes its
+    // signedness from the loads when any exist.
+    const byOff = new Map<number, { width: number; loadSigned: boolean | null }>();
+    for (const a of accesses) {
+      const isLoad = a.op.opcode === 'load';
+      const prev = byOff.get(a.off);
+      if (!prev) {
+        byOff.set(a.off, { width: a.width, loadSigned: isLoad ? a.signed : null });
+      } else if (prev.width !== a.width) {
+        clean = false;
+      } else if (isLoad) {
+        if (prev.loadSigned === null) {
+          prev.loadSigned = a.signed;
+        } else if (prev.loadSigned !== a.signed) {
+          clean = false;
+        }
+      }
+    }
+    const offs = [...byOff.entries()].sort(([x], [y]) => x - y);
+    let maxAlign = 1;
+    for (let i = 0; i < offs.length; i++) {
+      const [off, { width }] = offs[i];
+      if (off % width !== 0) {
+        clean = false;
+      }
+      if (i + 1 < offs.length && off + width > offs[i + 1][0]) {
+        clean = false;
+      }
+      maxAlign = Math.max(maxAlign, width);
+    }
+    if (stride % maxAlign !== 0) {
+      clean = false;
+    }
+    if (!clean) {
+      continue;
+    }
+    const dataFields: StructField[] = offs.map(([off, { width, loadSigned }]) => ({
+      off,
+      // store-only field: the width===4 convention, exactly what the old access carried
+      type: scalarTypeForAccess(width, loadSigned ?? width === 4),
+      name: `field_${off}`,
+    }));
+    const elemStruct = T.struct(`Elem${count}`, withPadding(dataFields, stride), stride);
+    base.type = T.ptr(elemStruct);
+
+    // Rewrite each field load/store into an aload/astore carrying base, ITS elem's index,
+    // elemSize, fieldOff. The aload REUSES the load's result value — minting a replacement and
+    // RAUW-ing killed a value that a LATER group's captured base/index still referenced (the
+    // groups were collected before any rewrite), crashing chained table indexing
+    // (`q = o[i].p; q[j].a`) with a use-of-undefined-value; reuse leaves every captured Value
+    // alive, so no group can go stale (adversarially learned).
+    for (const bb of fn.blocks) {
+      for (let i = 0; i < bb.ops.length; i++) {
+        const op = bb.ops[i];
+        if (!elemSet.has(op.operands[0])) {
+          continue;
+        }
+        const index = indexOf.get(op.operands[0])!;
+        if (op.opcode === 'load') {
+          bb.ops[i] = mkOp('aload', {
+            operands: [base, index],
+            results: [op.results[0]],
+            attrs: { elemSize: stride, signed: op.attrs.signed as boolean, fieldOff: op.attrs.off as number },
+          });
+        } else if (op.opcode === 'store') {
+          bb.ops[i] = mkOp('astore', {
+            operands: [base, index, op.operands[1]],
+            attrs: { elemSize: stride, fieldOff: op.attrs.off as number },
+          });
+        }
+      }
+    }
+    count++;
+  }
+  return count;
+}