@asmlift/core 0.1.0

package/src/raise/magicdiv.ts

@@ -0,0 +1,386 @@
+// asmlift — magic-number constant-division recovery (L1 recognition; gcc-mips + mwcc-ppc).
+//
+// A compiler replaces `x / C` for a non-power-of-2 constant `C` with a HIGH-WORD MULTIPLY by a
+// precomputed "magic" reciprocal `M`, a shift `s`, and a sign correction. The frontend lifts the
+// high-word multiply to a transient `mulh`/`mulhu` op (mips `mfhi` after `mult`/`multu`; ppc
+// `mulhw`/`mulhwu`); this pass matches the DAG hanging off it, RECONSTRUCTS `C`, PROVES it with the
+// forward Hacker's-Delight generator, and rewrites the tree to `sdiv`/`udiv(x, const C)` — the same
+// op the hardware-divide and softdiv paths emit, which the structurer prints as `x / C` and the
+// compiler re-lowers to the identical magic sequence.
+//
+// Soundness: the round-trip is SELF-VERIFYING — asmlift emits a plain `x / C` and the target
+// compiler regenerates ITS magic; a wrong `C` recompiles to different bytes → nonmatch, never a
+// false match. The forward-verify below is therefore a MATCH-RATE filter (don't emit a nonsense
+// divide from a `mulh` chain that isn't a division) rather than the trust barrier. An unrecognised /
+// unverifiable shape leaves the `mulh` in place → it loud-fails at the structurer boundary (the
+// transient op has no C spelling). The guard is a COMPUTATION, which the patterns-as-data layer
+// cannot state, so this lives as a bespoke always-on pass run before type recovery.
+import { Fn, Op, Value, defOpMap, mkOp, mkValue } from '../ir/core';
+import { T } from '../ir/types';
+
+/** Forward signed magic generator (Hacker's Delight §10-3). Given divisor `d` (2 ≤ d), returns the
+ *  32-bit magic multiplier `M` and shift `s` a compiler would pick. All intermediates stay < 2^33, so
+ *  plain Number arithmetic is exact (no 32-bit-overflow products are taken). */
+function magicS(d: number): { M: number; s: number } {
+  const two31 = 0x80000000;
+  const ad = Math.abs(d);
+  const t = two31 + (d < 0 ? 1 : 0);
+  const anc = t - 1 - (t % ad);
+  let p = 31;
+  let q1 = Math.floor(two31 / anc),
+    r1 = two31 - q1 * anc;
+  let q2 = Math.floor(two31 / ad),
+    r2 = two31 - q2 * ad;
+  let delta: number;
+  do {
+    p++;
+    q1 = 2 * q1;
+    r1 = 2 * r1;
+    if (r1 >= anc) {
+      q1++;
+      r1 -= anc;
+    }
+    q2 = 2 * q2;
+    r2 = 2 * r2;
+    if (r2 >= ad) {
+      q2++;
+      r2 -= ad;
+    }
+    delta = ad - r2;
+  } while (q1 < delta || (q1 === delta && r1 === 0));
+  let M = q2 + 1;
+  if (d < 0) {
+    M = -M;
+  }
+  return { M: M >>> 0, s: p - 32 };
+}
+
+/** Forward UNSIGNED magic generator (Hacker's Delight §10-8). Returns the multiplier `M`, shift `s`,
+ *  and the `add` indicator (true ⇒ the "add-correction" variant that needs an extra `+x` term —
+ *  matched by matchUnsignedAddCorrection, not the simple `mulhu>>s` shape). */
+function magicU(d: number): { M: number; s: number; add: boolean } {
+  const u = (x: number) => x >>> 0;
+  let p = 31;
+  const nc = u(u(-1) - u(u(-d) % d));
+  let q1 = Math.floor(0x80000000 / nc),
+    r1 = u(0x80000000 - q1 * nc);
+  let q2 = Math.floor(0x7fffffff / d),
+    r2 = u(0x7fffffff - q2 * d);
+  let add = false,
+    delta: number;
+  do {
+    p++;
+    if (r1 >= nc - r1) {
+      q1 = u(2 * q1 + 1);
+      r1 = u(2 * r1 - nc);
+    } else {
+      q1 = u(2 * q1);
+      r1 = u(2 * r1);
+    }
+    if (r2 + 1 >= d - r2) {
+      if (q2 >= 0x7fffffff) {
+        add = true;
+      }
+      q2 = u(2 * q2 + 1);
+      r2 = u(2 * r2 + 1 - d);
+    } else {
+      if (q2 >= 0x80000000) {
+        add = true;
+      }
+      q2 = u(2 * q2);
+      r2 = u(2 * r2 + 1);
+    }
+    delta = d - 1 - r2;
+  } while (p < 64 && (q1 < delta || (q1 === delta && r1 === 0)));
+  return { M: u(q2 + 1), s: p - 32, add };
+}
+
+// Realistic constant divisors are small; bound the inverse search generously (covers fixed-point
+// scales) but finitely. The search is only reached once a `mulh`/`mulhu` anchor with a const magic is
+// found (rare — non-division functions have no high-word multiply), so cost is negligible.
+const DIVISOR_MAX = 0x40000;
+
+/** Invert a magic: find the divisor `C` whose FORWARD magic is exactly the observed `(M, s)` —
+ *  a proof by exact reproduction. `kind` picks the catalog: signed (magicS), simple unsigned
+ *  (magicU, no add-correction), or add-correction unsigned (magicU with `add`). Returns null if
+ *  no divisor in range reproduces the pair. */
+function recoverDivisor(M: number, s: number, kind: 'signed' | 'unsigned' | 'unsigned-add'): number | null {
+  const mu = M >>> 0;
+  for (let d = 2; d <= DIVISOR_MAX; d++) {
+    if (kind === 'signed') {
+      const m = magicS(d);
+      if (m.M === mu && m.s === s) {
+        return d;
+      }
+    } else {
+      const m = magicU(d);
+      if (m.M === mu && m.s === s && m.add === (kind === 'unsigned-add')) {
+        return d;
+      }
+    }
+  }
+  return null;
+}
+
+// ── DAG helpers ───────────────────────────────────────────────────────────────────────────────────
+
+interface Ctx {
+  defOf: Map<Value, Op>;
+  usesOf: Map<Value, Op[]>;
+}
+
+function buildCtx(fn: Fn): Ctx {
+  const usesOf = new Map<Value, Op[]>();
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      for (const o of op.operands) {
+        const arr = usesOf.get(o);
+        if (arr) {
+          arr.push(op);
+        } else {
+          usesOf.set(o, [op]);
+        }
+      }
+    }
+  }
+  return { defOf: defOpMap(fn), usesOf };
+}
+
+const constVal = (ctx: Ctx, v: Value): number | null => {
+  const d = ctx.defOf.get(v);
+  return d && d.opcode === 'const' ? (d.attrs.value as number) : null;
+};
+
+/** Bind a high-word multiply's operands: M = the const operand, x = the other. Exactly one of
+ *  the two must be a constant. */
+function bindMulOperands(ctx: Ctx, mul: Op): { x: Value; M: number } | null {
+  const [a, b] = mul.operands;
+  const ca = constVal(ctx, a),
+    cb = constVal(ctx, b);
+  if (ca !== null && cb === null) {
+    return { M: ca, x: b };
+  }
+  if (cb !== null && ca === null) {
+    return { M: cb, x: a };
+  }
+  return null;
+}
+
+/** A single unique use of `v` matching `pred`, or null (ambiguous / absent both yield null). */
+function uniqueUse(ctx: Ctx, v: Value, pred: (op: Op) => boolean): Op | null {
+  const hits = (ctx.usesOf.get(v) ?? []).filter(pred);
+  return hits.length === 1 ? hits[0] : null;
+}
+
+/** An immediate-form shift `op(base){imm}` result → the shift amount, else null. */
+function immShiftAmt(op: Op, opcode: string): number | null {
+  return op.opcode === opcode && op.operands.length === 1 && typeof op.attrs.imm === 'number'
+    ? (op.attrs.imm as number)
+    : null;
+}
+
+/** The block+index of `op`, or null. */
+function locate(fn: Fn, op: Op): { block: number; idx: number } | null {
+  for (let b = 0; b < fn.blocks.length; b++) {
+    const i = fn.blocks[b].ops.indexOf(op);
+    if (i >= 0) {
+      return { block: b, idx: i };
+    }
+  }
+  return null;
+}
+
+// ── The recogniser ──────────────────────────────────────────────────────────────────────────────
+
+/** Rewrite each recognised magic-division tree to `sdiv`/`udiv(x, const C)`, in place. Returns whether
+ *  anything changed. Runs BEFORE type recovery so the new op's operands get signedness typing. */
+export function recognizeMagicDivision(fn: Fn): boolean {
+  const ctx = buildCtx(fn);
+  let changed = false;
+
+  for (const b of fn.blocks) {
+    for (const op of [...b.ops]) {
+      let rec: Match | null = null;
+      if (op.opcode === 'mulh') {
+        rec = matchSignedMagic(ctx, op);
+      } // signed magic division
+      else if (op.opcode === 'mulhu')
+      // unsigned: simple, else add-correction
+      {
+        rec = matchUnsignedSimpleMagic(ctx, op) ?? matchUnsignedAddCorrection(ctx, op);
+      } else {
+        continue;
+      }
+      if (!rec) {
+        continue;
+      } // uncatalogued / unverifiable → leave the high-mul → loud-fail
+      const loc = locate(fn, rec.root);
+      if (!loc) {
+        continue;
+      }
+      const block = fn.blocks[loc.block];
+      const cRes = mkValue(T.unk(32));
+      const cOp = mkOp('const', { results: [cRes], attrs: { value: rec.C } });
+      // Reuse the root's result Value so every downstream use auto-points at the divide; DCE reaps the
+      // now-dead mulh/add/shift/correction ops.
+      const divOp = mkOp(rec.signed ? 'sdiv' : 'udiv', { operands: [rec.x, cRes], results: [rec.root.results[0]] });
+      block.ops.splice(loc.idx, 1, cOp, divOp);
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+interface Match {
+  x: Value;
+  C: number;
+  root: Op;
+  signed: boolean;
+}
+
+/** Match the signed magic-division DAG rooted at a `mulh`, in either the MIPS (`- (x>>31)`) or PPC
+ *  (`+ (t>>u31)`) sign-correction form, and reconstruct+verify the divisor. */
+function matchSignedMagic(ctx: Ctx, mul: Op): Match | null {
+  // Bind M (the const operand) and x (the other).
+  const bound = bindMulOperands(ctx, mul);
+  if (!bound) {
+    return null;
+  }
+  const { x, M } = bound;
+  const r = mul.results[0];
+
+  // base = mulh result, or `add(mulh, x)` when the magic needed the +x "33rd bit" correction (M high).
+  let base = r;
+  const addX = uniqueUse(
+    ctx,
+    r,
+    (o) =>
+      o.opcode === 'add' &&
+      ((o.operands[0] === r && o.operands[1] === x) || (o.operands[1] === r && o.operands[0] === x)),
+  );
+  if (addX) {
+    base = addX.results[0];
+  }
+  // The +x correction is REQUIRED exactly when M's top bit is set (M reads as negative in the
+  // signed mulh, so the product under-counts by x) and FORBIDDEN otherwise. recoverDivisor
+  // verifies only (M, s), which is identical for both shapes — an untied match would rewrite a
+  // spurious-+x or missing-+x tree to a divide computing a DIFFERENT value than the matched asm.
+  if (M >>> 0 >= 0x80000000 !== (addX !== null)) {
+    return null;
+  }
+
+  // shifted = shr_s(base, s)  (arithmetic right shift by the magic shift)
+  const shOp = uniqueUse(ctx, base, (o) => immShiftAmt(o, 'shr_s') !== null);
+  if (!shOp) {
+    return null;
+  }
+  const s = immShiftAmt(shOp, 'shr_s')!;
+  const shifted = shOp.results[0];
+
+  // Sign correction → root. MIPS: sub(shifted, shr_s(x,31)); PPC: add(shifted, shr_u(shifted,31)).
+  let root: Op | null = null;
+  const subUse = uniqueUse(ctx, shifted, (o) => o.opcode === 'sub' && o.operands[0] === shifted);
+  if (subUse) {
+    const w = ctx.defOf.get(subUse.operands[1]);
+    if (w && immShiftAmt(w, 'shr_s') === 31 && w.operands[0] === x) {
+      root = subUse;
+    } // - (x>>31)
+  }
+  if (!root) {
+    const addUse = uniqueUse(
+      ctx,
+      shifted,
+      (o) => o.opcode === 'add' && (o.operands[0] === shifted || o.operands[1] === shifted),
+    );
+    if (addUse) {
+      const other = addUse.operands[0] === shifted ? addUse.operands[1] : addUse.operands[0];
+      const w = ctx.defOf.get(other);
+      if (w && immShiftAmt(w, 'shr_u') === 31 && w.operands[0] === shifted) {
+        root = addUse;
+      } // + (t>>u31)
+    }
+  }
+  if (!root) {
+    return null;
+  }
+
+  const C = recoverDivisor(M, s, 'signed');
+  if (C === null) {
+    return null;
+  } // no divisor reproduces (M,s) exactly → not a division we trust
+  return { x, C, root, signed: true };
+}
+
+/** Match the SIMPLE unsigned magic-division DAG `shr_u(mulhu(x, M), s)` (no correction) and
+ *  reconstruct+verify the divisor. The add-correction variant (`t + ((x−t)>>1)`) is not matched
+ *  here — its `mulhu` result feeds a `sub`, not a direct `shr_u`, so this matcher naturally declines it. */
+function matchUnsignedSimpleMagic(ctx: Ctx, mul: Op): Match | null {
+  const bound = bindMulOperands(ctx, mul);
+  if (!bound) {
+    return null;
+  }
+  const { x, M } = bound;
+  const r = mul.results[0];
+
+  // shifted = shr_u(mulhu, s) — the quotient. The simple form has NO sign/round correction: the shift
+  // result IS the returned value, so it is the root.
+  const shOp = uniqueUse(ctx, r, (o) => immShiftAmt(o, 'shr_u') !== null);
+  if (!shOp) {
+    return null;
+  }
+  const s = immShiftAmt(shOp, 'shr_u')!;
+
+  const C = recoverDivisor(M, s, 'unsigned');
+  if (C === null) {
+    return null;
+  }
+  return { x, C, root: shOp, signed: false };
+}
+
+/** Match the ADD-CORRECTION unsigned magic DAG (used when the magic reciprocal didn't fit in 32 bits):
+ *    t = mulhu(x, M);  d1 = x − t;  d2 = d1 >>u 1;  d3 = t + d2;  root = d3 >>u (s−1)
+ *  and reconstruct+verify the divisor (`magicU(C).add === true`, `magicU(C).s === s`). */
+function matchUnsignedAddCorrection(ctx: Ctx, mul: Op): Match | null {
+  const bound = bindMulOperands(ctx, mul);
+  if (!bound) {
+    return null;
+  }
+  const { x, M } = bound;
+  const t = mul.results[0];
+
+  // d1 = sub(x, t)  [x − t]
+  const d1 = uniqueUse(ctx, t, (o) => o.opcode === 'sub' && o.operands[0] === x && o.operands[1] === t);
+  if (!d1) {
+    return null;
+  }
+  // d2 = shr_u(d1, 1)
+  const d2 = uniqueUse(ctx, d1.results[0], (o) => immShiftAmt(o, 'shr_u') === 1);
+  if (!d2) {
+    return null;
+  }
+  // d3 = add(t, d2)  (either operand order)
+  const d3 = uniqueUse(
+    ctx,
+    d2.results[0],
+    (o) => o.opcode === 'add' && (o.operands[0] === d2.results[0] || o.operands[1] === d2.results[0]),
+  );
+  if (!d3) {
+    return null;
+  }
+  const otherAdd = d3.operands[0] === d2.results[0] ? d3.operands[1] : d3.operands[0];
+  if (otherAdd !== t) {
+    return null;
+  } // the add must combine `t` and `d2`
+  // root = shr_u(d3, s−1)
+  const rootOp = uniqueUse(ctx, d3.results[0], (o) => immShiftAmt(o, 'shr_u') !== null);
+  if (!rootOp) {
+    return null;
+  }
+  const s2 = immShiftAmt(rootOp, 'shr_u')!;
+
+  const C = recoverDivisor(M, s2 + 1, 'unsigned-add'); // the final shift is s−1, so the magic shift is s2+1
+  if (C === null) {
+    return null;
+  }
+  return { x, C, root: rootOp, signed: false };
+}

package/src/raise/pre-recovery.ts

@@ -0,0 +1,71 @@
+// asmlift — the pre-recovery raise-pass sequence, as ONE shared ordered list.
+//
+// These recognizers run AFTER idiom-pattern folding and BEFORE type recovery, each rewriting the IR
+// into a form recovery/structuring can reason about. Their ORDER and per-pass `dce`/gating semantics
+// are load-bearing; this module is the single source of truth — add a pass HERE and every caller
+// (pipeline, rank, report) picks it up. A pass added to one call site alone leaves the others
+// hitting the unlowered op → a spurious noncompile.
+//
+// Callers supply an `afterPass` hook for their own per-pass concern (pipeline's raiseRecovered and
+// rank's score-probe both verify; the report's trace entries ride pipeline's hook). The `dce` after a
+// pass that changed the IR is INTRINSIC to the pass (it declares whether it leaves dead ops) and lives
+// in the driver.
+import { Fn } from '../ir/core';
+import { dce } from '../pattern/engine';
+import type { TargetDescription } from '../target';
+import { recognizeArrays } from './arrays';
+import { recognizeConsts } from './const';
+import { recognizeMagicDivision } from './magicdiv';
+import { recognizeShortCircuit } from './shortcircuit';
+import { recognizeSoftDiv } from './softdiv';
+import { recognizeStructArrays } from './struct-arrays';
+import { recognizeStructs } from './structs';
+
+export interface PreRecoveryPass {
+  /** stable id — also the report's trace-stage key. */
+  id: string;
+  /** run the recognizer; returns a truthy value (a change count, or `true`) iff it CHANGED the IR. */
+  run: (fn: Fn) => number | boolean;
+  /** run `dce` after this pass changes the IR (the pass declares it leaves dead ops behind). */
+  dce: boolean;
+  /** optional target gate (soft-div only fires on a no-hardware-divide target — see raise/softdiv.ts). */
+  gate?: (target: TargetDescription) => boolean;
+}
+
+/** THE ordered pre-recovery pass list — the single source of truth shared by pipeline / rank / report.
+ *  const-materialize → magic-division → soft-division → array-legalize → struct-array →
+ *  struct-pointer → short-circuit. See each recognizer's file for the rationale. */
+export const PRE_RECOVERY_PASSES: PreRecoveryPass[] = [
+  { id: 'const', run: recognizeConsts, dce: true },
+  { id: 'magicdiv', run: recognizeMagicDivision, dce: true },
+  { id: 'softdiv', run: (fn) => recognizeSoftDiv(fn), dce: false, gate: (t) => !t.capabilities.hwDivide },
+  { id: 'arrays', run: recognizeArrays, dce: true },
+  // struct-arrays AFTER arrays (scalar stride==width shapes are claimed first — see the
+  // discriminator note in raise/struct-arrays.ts) and BEFORE structs (an element's field
+  // accesses must not be re-derived as constant-offset struct-pointer accesses).
+  { id: 'struct-arrays', run: recognizeStructArrays, dce: true },
+  { id: 'structs', run: recognizeStructs, dce: false },
+  { id: 'shortcircuit', run: recognizeShortCircuit, dce: true },
+];
+
+/** Run the pre-recovery passes in order. For each pass whose gate passes and that CHANGES the IR, run
+ *  `dce` when the pass declares it, then invoke `afterPass(pass, result)` (the caller's verify/trace
+ *  hook), if given. */
+export function runPreRecovery(
+  fn: Fn,
+  target: TargetDescription,
+  afterPass?: (pass: PreRecoveryPass, result: number | boolean) => void,
+): void {
+  for (const pass of PRE_RECOVERY_PASSES) {
+    if (pass.gate && !pass.gate(target)) {
+      continue;
+    }
+    const result = pass.run(fn);
+    if (result) {
+      if (pass.dce) {
+        dce(fn);
+      }
+      afterPass?.(pass, result);
+    }
+  }
+}

package/src/raise/recover.ts

@@ -0,0 +1,215 @@
+// asmlift — L1→L2 type recovery (a constraint pass). Seeds signedness from op semantics
+// (signed comparisons/divisions ⇒ signed operands), types memory-access bases as pointers,
+// propagates pointer-ness across the SSA, then defaults the rest to s32. Emits recovered
+// types onto the SSA values in place.
+import { Fn, Value, defOpMap } from '../ir/core';
+import { IrType, T, scalarTypeForAccess, typeEquals } from '../ir/types';
+
+const SIGNED_CMP = new Set(['icmp_slt', 'icmp_sle', 'icmp_sgt', 'icmp_sge']);
+const UNSIGNED_CMP = new Set(['icmp_ult', 'icmp_ule', 'icmp_ugt', 'icmp_uge']);
+// Division/remainder carry signedness in the OPCODE (a hardware `div` vs `divu`), so they seed it
+// onto their operands AND result — the reason the backend can pick signed `/` over unsigned operands.
+const SIGNED_DIV = new Set(['sdiv', 'smod']);
+const UNSIGNED_DIV = new Set(['udiv', 'umod']);
+
+export function recoverTypes(fn: Fn): void {
+  const setInt = (v: Value, signed: boolean) => {
+    if (v.type.kind === 'unknown') {
+      v.type = T.int(v.type.width, signed);
+    }
+  };
+  // Seed: operands of a signed comparison are signed integers.
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      if (SIGNED_CMP.has(op.opcode)) {
+        op.operands.forEach((o) => setInt(o, true));
+      }
+      if (UNSIGNED_CMP.has(op.opcode)) {
+        op.operands.forEach((o) => setInt(o, false));
+      } // sltu ⇒ u32 operands
+      if (op.opcode.startsWith('icmp')) {
+        op.results.forEach((r) => (r.type = T.u(32)));
+      } // bool
+      // The register (2-operand) division form seeds operand+result signedness; the immediate form
+      // (`sdiv X {imm=…}`, 1 operand) is always the signed strength-reduced divisor.
+      if (SIGNED_DIV.has(op.opcode)) {
+        op.operands.forEach((o) => setInt(o, true));
+        op.results.forEach((r) => setInt(r, true));
+      }
+      if (UNSIGNED_DIV.has(op.opcode)) {
+        op.operands.forEach((o) => setInt(o, false));
+        op.results.forEach((r) => setInt(r, false));
+      }
+      // A rotate is a bitwise permutation: its value operand and result are unsigned (the C
+      // idiom's `>>` must be the LOGICAL shift or the spelling stops round-tripping). The
+      // rotate AMOUNT (operand 1, register form) keeps its own signedness.
+      if (op.opcode === 'rotr' || op.opcode === 'rotl') {
+        setInt(op.operands[0], false);
+        op.results.forEach((r) => setInt(r, false));
+      }
+    }
+  }
+  // A value used as the base of a memory access is a pointer; its pointee type comes from the
+  // access width (and, for loads, signedness). This must run before the s32 default so the
+  // base is typed `T *` rather than being flattened to a plain integer. Both the constant-offset
+  // forms (load/store, width) and the variable-index forms (aload/astore, elemSize) type their
+  // base operand[0]; only the scale attribute differs.
+
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      let width: number, signed: boolean;
+      switch (op.opcode) {
+        case 'load':
+          width = op.attrs.width as number;
+          signed = op.attrs.signed as boolean;
+          break;
+        case 'store':
+          width = op.attrs.width as number;
+          signed = width === 4;
+          break;
+        case 'aload':
+          width = op.attrs.elemSize as number;
+          signed = op.attrs.signed as boolean;
+          break;
+        case 'astore':
+          width = op.attrs.elemSize as number;
+          signed = width === 4;
+          break;
+        default:
+          continue;
+      }
+      const base = op.operands[0];
+      if (base.type.kind === 'unknown') {
+        base.type = T.ptr(scalarTypeForAccess(width, signed));
+      }
+    }
+  }
+  // Propagate pointer-ness across the SSA. The seed above types only the DIRECT base of a dereference;
+  // a loop-carried pointer reaches its dereference through a block-arg phi (its incoming `a0`) and a
+  // `p = p + stride` walk, so those values stay `unknown` and the s32 default below would spell them
+  // `int` — an `int→int*` assignment mwcc/agbcc REJECT (gcc warns). Flow the pointer type across the
+  // exact same-value edges (a phi is one value; `ptr ± const` is the same pointer type). Union-find over
+  // Value identity. SOUND: every edge connects values that provably hold the same pointer, and we only
+  // fill `unknown`s — a class with a conflicting int member or two distinct pointees is left untouched.
+  propagatePointers(fn);
+  // Default every still-unknown value to s32. This is a COMPILER default (agbcc/IDO/GCC all take
+  // plain `int` as the integer default), not a hardware fact — applied uniformly.
+  for (const b of fn.blocks) {
+    for (const p of b.params) {
+      if (p.type.kind === 'unknown') {
+        p.type = T.s(32);
+      }
+    }
+    for (const op of b.ops) {
+      for (const r of op.results) {
+        if (r.type.kind === 'unknown') {
+          r.type = T.s(32);
+        }
+      }
+    }
+  }
+}
+
+// Union-find pointer propagation (see the call site). Unions (1) each successor arg with the block param
+// it binds (the phi/copy identity) and (2) an `add`/`sub` result with its non-constant operand when the
+// other operand is a constant (a pointer ± an integer offset stays the same pointer type). Then, for each
+// class with EXACTLY ONE distinct pointee and NO conflicting int-typed member, every `unknown` member of
+// the class is typed with that pointee. Conservative on conflict: a genuinely ambiguous value (used as
+// both pointer and integer, or with two pointee widths) is left for the s32 default — sound, never a
+// mistype. Types only; changes no op, so it cannot alter compiled bytes except to fix the `int→ptr` form.
+//
+// Domain assumption (edge type 1): in WELL-TYPED compiler output a block-arg phi merges values of ONE
+// type, so a pointer's phi has only pointer incoming args — propagating the pointee across it is exact.
+// Genuinely type-punned asm (one register aliasing a pointer and an integer across a merge) has no
+// byte-exact C anyway; the `hasInt` conflict guard blocks the common form, and the residual is ill-typed
+// input, not a miscompile of well-typed code.
+function propagatePointers(fn: Fn): void {
+  const parent = new Map<Value, Value>();
+  const find = (v: Value): Value => {
+    if (!parent.has(v)) {
+      parent.set(v, v);
+      return v;
+    }
+    let r = v;
+    while (parent.get(r)! !== r) {
+      r = parent.get(r)!;
+    }
+    for (let c = v; parent.get(c)! !== r;) {
+      const n = parent.get(c)!;
+      parent.set(c, r);
+      c = n;
+    }
+    return r;
+  };
+  const union = (a: Value, b: Value) => {
+    parent.set(find(a), find(b));
+  };
+
+  const defs = defOpMap(fn);
+  const isConst = (v: Value) => defs.get(v)?.opcode === 'const';
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      for (const s of op.successors) {
+        const n = Math.min(s.args.length, s.block.params.length);
+        for (let i = 0; i < n; i++) {
+          union(s.args[i], s.block.params[i]);
+        }
+      }
+      if ((op.opcode === 'add' || op.opcode === 'sub') && op.results.length === 1 && op.operands.length === 2) {
+        const [x, y] = op.operands;
+        const xc = isConst(x),
+          yc = isConst(y);
+        if (xc !== yc) {
+          union(op.results[0], xc ? y : x);
+        } // exactly one const ⇒ pointer ± offset
+        // A `base + index` add (two non-constant operands) is NOT unioned: base and index are not
+        // reliably distinguishable here. Attempting it mis-typed the INDEX as the pointer whenever
+        // the true base was itself int-seeded by a pointer comparison (`if (p < lim)` → `sltu`/`cmplw`
+        // seeds the base `int`, the index stays `unknown`) — silent-wrong pointer-scaled C. Recovering
+        // `add(base,index)` bases needs a stronger base/index discriminator; deferred rather than
+        // risk a miscompile.
+      }
+    }
+  }
+
+  // Per class: the distinct pointees seen, and whether any member is a definite integer (a conflict).
+  const info = new Map<Value, { pointees: IrType[]; hasInt: boolean }>();
+  for (const v of parent.keys()) {
+    const root = find(v);
+    let e = info.get(root);
+    if (!e) {
+      e = { pointees: [], hasInt: false };
+      info.set(root, e);
+    }
+    if (v.type.kind === 'ptr' && !e.pointees.some((t) => typeEquals(t, v.type))) {
+      e.pointees.push(v.type);
+    }
+    if (v.type.kind === 'int') {
+      e.hasInt = true;
+    }
+  }
+  for (const v of parent.keys()) {
+    if (v.type.kind !== 'unknown') {
+      continue;
+    }
+    const e = info.get(find(v))!;
+    if (e.pointees.length === 1 && !e.hasInt) {
+      v.type = e.pointees[0];
+    }
+  }
+}
+
+/** The recovered return type = the type of the value returned by the first `ret`. */
+export function returnType(fn: Fn): IrType {
+  for (const b of fn.blocks) {
+    const term = b.ops[b.ops.length - 1];
+    if (term?.opcode === 'ret') {
+      if (term.operands.length === 0) {
+        return T.s(32);
+      }
+      const v = term.operands[0];
+      return v.type.kind === 'unknown' ? T.s(32) : v.type;
+    }
+  }
+  return T.s(32);
+}