@asmlift/core 0.2.0 → 0.4.0

package/src/macros.ts

@@ -0,0 +1,335 @@
+// asmlift — address-cast macros: the OTHER way a project names a fixed RAM cell.
+//
+// Some decomp projects declare `extern u16 gCounter;` and let the linker place it; others write
+// `#define gCounter (*(u16 *)0x03001234)`. Both read the same cell, but they are NOT
+// interchangeable in the bytes an old compiler emits: an `extern` produces a RELOCATED literal-pool
+// word (`.word gCounter`), the macro a NUMERIC one (`.word 0x3001234`). A target that shows the
+// numeric word can therefore only be matched by the macro spelling — a symtab name will not do,
+// and no `.symtab` carries these names in the first place (a macro is not a symbol).
+//
+// This module is the PURE recognizer over preprocessor output (`cpp -dD`). Everything it accepts is
+// a fact it can name exactly; everything else is refused, because a wrong width or a dropped
+// `volatile` is the plausible-but-wrong class — see the guards on {@link addressCastMacros}.
+
+/** One recognized address-cast macro. */
+export interface AddressMacro {
+  name: string;
+  /** the cell's address — the map key this macro names */
+  address: number;
+  /** the macro body VERBATIM, as the declaration must reproduce it */
+  body: string;
+  /** the cast's byte width */
+  size: number;
+  /** the cast type's signedness */
+  signed: boolean;
+  /** the cast type was volatile-qualified (`vu16`) — the MMIO idiom. Load-bearing: a
+   *  non-volatile spelling lets the compiler fold or reorder repeated accesses. */
+  volatile?: true;
+}
+
+/** The scalar type spellings a cast may use, and what each one means. Deliberately a CLOSED table:
+ *  an unrecognized spelling (a project typedef, an enum, a struct) is refused rather than guessed,
+ *  and every `volatile` alias is absent so it can never be silently dropped — the qualifier changes
+ *  whether repeated reads may be folded, which is both a byte and a semantic difference. */
+const SCALAR_TYPES: Record<string, { size: number; signed: boolean; volatile?: true }> = {
+  u8: { size: 1, signed: false },
+  s8: { size: 1, signed: true },
+  u16: { size: 2, signed: false },
+  s16: { size: 2, signed: true },
+  u32: { size: 4, signed: false },
+  s32: { size: 4, signed: true },
+  // The `volatile` aliases. They were excluded so the qualifier could never be silently dropped;
+  // it is now CARRIED instead (`volatile: true`, reproduced by every spelling this feeds), which
+  // is the same guarantee without the cost — refusing them lost every MMIO register name a GBA
+  // project has, since those are exactly the cells one declares volatile.
+  vu8: { size: 1, signed: false, volatile: true },
+  vs8: { size: 1, signed: true, volatile: true },
+  vu16: { size: 2, signed: false, volatile: true },
+  vs16: { size: 2, signed: true, volatile: true },
+  vu32: { size: 4, signed: false, volatile: true },
+  vs32: { size: 4, signed: true, volatile: true },
+};
+
+/** A pointer cast inside an address expression (`(void *)0x4000000`). The VALUE is the integer it
+ *  wraps: these headers spell a register base as a `void *` and add a byte offset to it, which is
+ *  GCC's byte-arithmetic extension, so the cast contributes nothing to the address.
+ *
+ *  BYTE-SIZED POINTEES ONLY, and that restriction is load-bearing rather than tidy. C pointer
+ *  arithmetic SCALES by the pointee: `(vu16 *)0x4000000 + 5` is 0x400000A, not 0x4000005. Stripping
+ *  a wider cast would fold the wrong address AND then republish it in a synthesized body that
+ *  agrees with itself — so the candidate still byte-matches the numeric pool word it was looked up
+ *  by, while naming a different register. A wrong name that survives the differ is the one failure
+ *  this module cannot let through.
+ *
+ *  A wider pointee is REFUSED EXPLICITLY below, not left to fall out of the token grammar further
+ *  down — the enforcing line belongs next to the rule it enforces. The cost is named rather than
+ *  hidden: a wider cast with NO arithmetic after it would fold correctly and is refused anyway,
+ *  because the hazard is cast-THEN-add and this cannot tell which it is looking at. */
+const PTR_CAST_ANY = /\(\s*(\w+)\s*\*\s*\)/g;
+const BYTE_POINTEE = new Set(['void', 'u8', 's8', 'vu8', 'vs8']);
+
+/** `src` with byte-sized pointer casts removed, or null if any cast SCALES. */
+function stripPointerCasts(src: string): string | null {
+  let scaling = false;
+  const out = src.replace(PTR_CAST_ANY, (_m, pointee: string) => {
+    if (!BYTE_POINTEE.has(pointee)) {
+      scaling = true;
+    }
+    return ' ';
+  });
+  return scaling ? null : out;
+}
+
+/** An object-like `#define NAME body`, for the expansion table the address evaluator resolves
+ *  identifiers against. Function-like macros (`NAME(x)`) are deliberately excluded: an address
+ *  expression that calls one is refused, not expanded. */
+const OBJECT_DEFINE = /^\s*#define\s+([A-Za-z_]\w*)\s+(\S.*?)\s*$/;
+
+/**
+ * Evaluate a macro's ADDRESS operand to a number, or null when it is not a constant expression
+ * this module can be sure of.
+ *
+ * Real decomp headers rarely write the address as a literal. The Klonoa headers spell every
+ * register as `(*(vu16 *)REG_ADDR_BLDALPHA)` over `REG_ADDR_BLDALPHA = (REG_BASE +
+ * REG_OFFSET_BLDALPHA)`, `REG_BASE = (void *)0x4000000`, `REG_OFFSET_BLDALPHA = 0x52` — so a
+ * literal-only recognizer sees none of the 466 `REG_*` names, and reads every MMIO cell as a
+ * decimal address instead.
+ *
+ * The accepted language is deliberately tiny — integer literals, `+`, `-`, parentheses, pointer
+ * casts (see {@link PTR_CAST}), and identifiers that resolve to another object-like define. Any
+ * other token, an unknown identifier, a function-like macro, a cycle, or a negative result refuses
+ * the whole expression. Folding is done on the EXPANDED integer text, so an operand only ever
+ * evaluates to a number every step of which this module recognized.
+ */
+function evalAddressExpr(
+  src: string,
+  defines: ReadonlyMap<string, string>,
+  seen: ReadonlySet<string>,
+  memo: Map<string, number | null> = new Map(),
+): number | null {
+  if (seen.size > 12) {
+    return null; // pathological nesting — refuse rather than walk further
+  }
+  const stripped = stripPointerCasts(src);
+  if (stripped === null) {
+    return null; // a scaling pointer cast — see PTR_CAST_ANY
+  }
+  const tokens = stripped.match(/[A-Za-z_]\w*|0[xX][0-9A-Fa-f]+|\d+|[()+-]/g);
+  // every character must belong to a token — anything else (`*`, `<<`, a comma) is out of language
+  if (!tokens || tokens.join('') !== stripped.replace(/\s+/g, '')) {
+    return null;
+  }
+  const expanded: string[] = [];
+  for (const tok of tokens) {
+    if (/^[A-Za-z_]/.test(tok)) {
+      const body = defines.get(tok);
+      if (body === undefined || seen.has(tok)) {
+        return null; // undefined name, or a cycle
+      }
+      // Memoized per NAME. The depth cap bounds nesting but not BRANCHING — a define mentioning k
+      // others re-evaluates the whole subtree k times, so a deep, wide table costs exponentially.
+      //
+      // A name's result CAN depend on the path that reached it: both refusals below are
+      // path-sensitive (already in `seen`; depth cap hit), so a cached `null` may be pessimistic
+      // for a shorter path. Safe in ONE direction only — path-dependence can make this refuse
+      // more, never fold a wrong address, which is the direction this module may be wrong in.
+      //
+      // The memo being PER TOP-LEVEL MACRO (the default parameter, fresh at each entry) is
+      // load-bearing rather than incidental: hoisting it across macros to "go faster" would let
+      // one deep macro poison a name for every macro after it, silently dropping recognized cells.
+      let inner: number | null;
+      if (memo.has(tok)) {
+        inner = memo.get(tok)!;
+      } else {
+        inner = evalAddressExpr(body, defines, new Set([...seen, tok]), memo);
+        memo.set(tok, inner);
+      }
+      if (inner === null) {
+        return null;
+      }
+      expanded.push(`(${inner})`);
+    } else if (/^0[xX]/.test(tok)) {
+      expanded.push(String(Number.parseInt(tok, 16)));
+    } else {
+      expanded.push(tok);
+    }
+  }
+  const folded = foldIntegerExpr(expanded.join(' '));
+  return folded !== null && Number.isSafeInteger(folded) && folded >= 0 ? folded : null;
+}
+
+/** Fold a fully-expanded `+`/`-`/parenthesis integer expression. Written out rather than handed to
+ *  an evaluator so nothing outside that grammar can ever be executed. */
+function foldIntegerExpr(text: string): number | null {
+  const toks = text.match(/\d+|[()+-]/g);
+  if (!toks || toks.join('') !== text.replace(/\s+/g, '')) {
+    return null;
+  }
+  let at = 0;
+  const expr = (): number | null => {
+    let acc = term();
+    if (acc === null) {
+      return null;
+    }
+    while (toks[at] === '+' || toks[at] === '-') {
+      const op = toks[at++];
+      const rhs = term();
+      if (rhs === null) {
+        return null;
+      }
+      acc = op === '+' ? acc + rhs : acc - rhs;
+    }
+    return acc;
+  };
+  const term = (): number | null => {
+    if (toks[at] === '(') {
+      at++;
+      const inner = expr();
+      if (inner === null || toks[at] !== ')') {
+        return null;
+      }
+      at++;
+      return inner;
+    }
+    if (toks[at] === '-') {
+      at++;
+      const v = term();
+      return v === null ? null : -v;
+    }
+    const tok = toks[at];
+    if (tok === undefined || !/^\d+$/.test(tok)) {
+      return null;
+    }
+    at++;
+    return Number(tok);
+  };
+  const value = expr();
+  return value !== null && at === toks.length ? value : null;
+}
+
+/** `#define NAME (*(TYPE *)ADDR)` — the ONE shape recognized, where ADDR is any constant
+ *  expression {@link evalAddressExpr} can be sure of (a literal, or names that resolve to one).
+ *  Anything else — a two-level indirection `(*(T **)…)`, a function-like macro, a bare integer
+ *  constant — does not match and is therefore refused by construction. */
+const ADDRESS_CAST = /^\s*#define\s+([A-Za-z_]\w*)\s+(\(\s*\*\s*\(\s*(\w+)\s*\*\s*\)\s*(.+?)\s*\))\s*$/;
+
+/** A bare hex literal — the operand form whose macro body is already self-contained. */
+const HEX_LITERAL = /^0[xX][0-9A-Fa-f]+$/;
+
+/**
+ * Recognize the address-cast macros in `cpp -dD` output, keyed by the address each names.
+ *
+ * REFUSALS, all of them because the alternative is a plausible-but-wrong spelling:
+ *  - a cast type outside {@link SCALAR_TYPES} — a project typedef, an enum, a struct;
+ *  - an address expression {@link evalAddressExpr} cannot fold to a definite number;
+ *  - two macros naming the SAME address (`REG_VCOUNT`/`REG_VCOUNT_L`/`REG_VCOUNT_H` at 0x04000006
+ *    differ in width, and picking wrong turns an `ldrh` into an `ldrb`) — both are dropped;
+ *  - one name defined at two addresses, which no correct spelling can disambiguate.
+ */
+export function addressCastMacros(cppOutput: string): Map<number, AddressMacro> {
+  return addressCastMacrosFrom(cppOutput.split('\n'));
+}
+
+/** The same recognizer over already-split `#define NAME body` lines — what a DWARF
+ *  `.debug_macinfo` reader produces once each definition is re-spelled as a directive. */
+export function addressCastMacrosFrom(defineLines: readonly string[]): Map<number, AddressMacro> {
+  // Pass 1: every object-like define, so an address expression can resolve the names it mentions.
+  // A macro's address is frequently spelled in terms of others (`REG_BASE + REG_OFFSET_X`), and
+  // those helpers are not themselves address casts — they exist only to be expanded.
+  //
+  // LAST DEFINITION WINS, and `#undef` is not modelled: the record is a flat list with no scope, so
+  // a name redefined differently across translation units resolves to whichever came last. Sound
+  // for a project whose headers agree (the Klonoa ELF redefines no name with a differing body);
+  // a project where they disagree would need per-CU scoping, which the record does not carry.
+  const defines = new Map<string, string>();
+  for (const line of defineLines) {
+    const d = OBJECT_DEFINE.exec(line);
+    if (d) {
+      defines.set(d[1], d[2]);
+    }
+  }
+  const byAddress = new Map<number, AddressMacro>();
+  const collided = new Set<number>();
+  const seenNames = new Map<string, number>();
+  for (const line of defineLines) {
+    const m = ADDRESS_CAST.exec(line);
+    if (!m) {
+      continue;
+    }
+    const [, name, rawBody, typeName, addrText] = m;
+    const type = SCALAR_TYPES[typeName];
+    if (!type) {
+      continue; // a spelling outside the closed table — refuse
+    }
+    const address = evalAddressExpr(addrText, defines, new Set([name]));
+    if (address === null) {
+      continue; // an address expression this module cannot be sure of — refuse
+    }
+    // The body must be SELF-CONTAINED and COMPILABLE, because it is republished verbatim as the
+    // definition a reproduction compiles against (macroDefinesUsedBy) — a body naming
+    // `REG_ADDR_VCOUNT` would need that macro, and its two helpers, carried along with it. An
+    // unqualified literal address keeps the project's own spelling; anything else is re-spelled at
+    // the address it evaluated to, which is the same cell and the same type.
+    // A VOLATILE body is re-spelled even when its address is already a literal: the alias it uses
+    // (`vu8`) is a PROJECT typedef, and the prelude a candidate compiles against declares only
+    // u8/u16/u32 + s8/s16/s32. Keeping such a body verbatim republishes a `#define` that does not
+    // compile — latent, because it only bites in the self-declared world.
+    const body =
+      HEX_LITERAL.test(addrText) && !type.volatile
+        ? rawBody
+        : `(*(${type.volatile ? 'volatile ' : ''}${type.signed ? 's' : 'u'}${type.size * 8} *)0x${address.toString(16).toUpperCase()})`;
+    const priorAddr = seenNames.get(name);
+    if (priorAddr !== undefined && priorAddr !== address) {
+      collided.add(priorAddr);
+      collided.add(address);
+      continue;
+    }
+    seenNames.set(name, address);
+    const prior = byAddress.get(address);
+    if (prior && prior.name !== name) {
+      collided.add(address);
+      continue;
+    }
+    byAddress.set(address, {
+      name,
+      address,
+      body,
+      size: type.size,
+      signed: type.signed,
+      ...(type.volatile ? { volatile: true as const } : {}),
+    });
+  }
+  for (const addr of collided) {
+    byAddress.delete(addr);
+  }
+  return byAddress;
+}
+
+/**
+ * The `#define` lines for every address-cast macro in `symbols` that `source` actually names.
+ *
+ * A published source that spells `gCollisionMapPtr` only compiles where that macro is defined —
+ * and a REPRODUCTION of it must therefore carry the definition, or the script the benchmark
+ * publishes cannot build the very source it publishes. Selected by the names the source uses
+ * rather than by the whole map, so a reproduction context stays the size of what it needs.
+ *
+ * Name-sorted and deduplicated: the materialized context must be byte-stable across machines.
+ */
+export function macroDefinesUsedBy(
+  symbols: Map<number, { name: string; macroBody?: string }[]>,
+  source: string,
+): string {
+  const used = new Map<string, string>();
+  for (const infos of symbols.values()) {
+    for (const info of infos) {
+      if (info.macroBody === undefined || used.has(info.name)) {
+        continue;
+      }
+      if (new RegExp(`\\b${info.name}\\b`).test(source)) {
+        used.set(info.name, info.macroBody);
+      }
+    }
+  }
+  const names = [...used.keys()].sort();
+  return names.length ? names.map((n) => `#define ${n} ${used.get(n)}`).join('\n') + '\n' : '';
+}

package/src/pattern/engine.ts

@@ -6,7 +6,7 @@
 // Crucially, rewrites go through replaceAllUsesWith + DCE — never in-place opcode
 // mutation of a live value.
 import { Fn, Op, Value, defOpMap, mkOp, mkValue, replaceAllUsesWith } from '../ir/core';
-import { type Opcode, isDceSafe } from '../ir/opcodes';
+import { NEGATED_ICMP, type Opcode, isDceSafe } from '../ir/opcodes';
 import type { IrType } from '../ir/types';
 import { T } from '../ir/types';
 
@@ -219,18 +219,107 @@ const sextPat = (w: number, k: number): RewritePattern => ({
 
 /** Byte/half zero- and sign-extension casts. Byte = shift by 24, half = shift by 16. The
  *  zero-extend forms fix a miscompile; the sign-extend forms already byte-matched as raw shifts and
- *  fold here for readability + `(s8)`/`(s16)` parity, staying byte-exact (`(s8)x` → `lsl;asr`). */
+ *  fold here for readability + `(s8)`/`(s16)` parity, staying byte-exact (`(s8)x` → `lsl;asr`).
+ *
+ *  SHADOWING NOTE: these run at the idiom stage, BEFORE structuring — so a symbol-map BITFIELD of
+ *  width exactly 8 or 16 whose bits start at bit 0 of its load is folded to `(u8)x`/`(u16)x` here
+ *  and never reaches the bitfield member recognizer (structure.ts, which matches the raw
+ *  `shr(shl(load))` shape only). Honest output, not a miscompile — the field just keeps the cast
+ *  spelling at those widths. Teaching the recognizer a zext/sext arm is the coverage extension if
+ *  a row ever needs it. */
 export const CAST_PATTERNS: RewritePattern[] = [zextPat(8, 24), zextPat(16, 16), sextPat(8, 24), sextPat(16, 16)];
 
+// ── boolean-negation idiom ───────────────────────────────────────────────────────────────────
+// `cmp ^ 1` IS `!cmp`: an `icmp_*` result is 0 or 1 by construction (ir/opcodes.ts), so xoring the
+// low bit flips exactly the boolean. A compiler with no set-on-greater-equal spells a MATERIALISED
+// `a >= b` as its opposite plus that flip — MIPS `slt v0,a0,a1; xori v0,v0,1`, the shape IDO and
+// both GCCs emit and the only one asmlift has measured (m2c `40cbae3` reports ARM `eor #1` too;
+// no agbcc row in the corpus carries it, agbcc materializing the same boolean via branches).
+// The naive lift prints that as the double-negative `a < b ^ 1`, and hides the comparison from
+// every consumer that reasons about booleans: the short-circuit recognizer's `&&`/`||` fold matches
+// an `icmp` feeder, not an `xor` of one. (It does not by itself unblock that fold — measured on
+// this idiom's one benchmark inhabitant, the diamond still declines because raise/shortcircuit.ts
+// additionally wants a 0/1 CONST arm and both arms here are comparisons. It removes one of the two
+// blockers, and the spelling win stands on its own.)
+//
+// UNGATED, unlike the compiler-pinned folds above. Two independent reasons, and the second is the
+// load-bearing one:
+//   • it is a semantic IDENTITY on asmlift's own IR, not a spelling trade — `xor(icmp, 1)` cannot
+//     mean anything but the negated compare on any target;
+//   • THE SHAPE IS ITS OWN GATE. The pattern can only fire where the compiler itself emitted the
+//     flip, and wherever it did, "the negated comparison" is precisely what it was spelling. A
+//     compiler with a set-on-greater-equal never produces the shape and so can never be harmed.
+// Byte evidence is narrower than the reasoning: synthetic:inrange stays MATCH under gcc2.7.2kmc
+// with the folded spelling, which proves the round-trip there; elsewhere it is unmeasured.
+//
+// The negation comes from THE shared table (ir/opcodes.ts NEGATED_ICMP), so this fold, the MIPS
+// `slt …; beqz` branch fold and the short-circuit diamond negation cannot disagree about what the
+// opposite of a compare is. One pattern per comparison — a data-driven fold needs a fixed
+// replacement opcode, so the table is unrolled into ten patterns rather than expressed as a
+// (nonexistent) computed-opcode replacement.
+const notCmpPat = (cmp: string): RewritePattern => ({
+  id: `not-${cmp}`,
+  applies: {},
+  match: {
+    op: 'xor',
+    args: [
+      { op: cmp, args: [{ bind: 'A' }, { bind: 'B' }] },
+      { op: 'const', attrEquals: { value: 1 }, args: [] },
+    ],
+  },
+  // Pinned u32, matching CNTLZW_EQ0 — the other pattern in this file that produces a comparison.
+  // It is what raise/recover.ts stamps on every icmp result unconditionally anyway, so inheriting
+  // the `xor`'s type would reach the same place; saying it here keeps the two icmp-producing
+  // patterns on one discipline instead of leaving a reader to infer which is canonical.
+  replaceWith: { op: NEGATED_ICMP[cmp], args: ['A', 'B'], resultType: T.u(32) },
+});
+
+// The BRANCH-form siblings. Testing a boolean against zero is the same negation by another
+// spelling, and it is what a compare-and-branch ISA actually emits: MIPS `slt v0,…; xori v0,v0,1;
+// beqz v0,L` lifts to `icmp_eq(icmp_sge(…), 0)` once the `xori` has folded, because the branch is a
+// genuine test of the materialised boolean (the frontend's own `slt …; beqz` fusion cannot fire —
+// its pending compare was invalidated by the `xori` that redefined the register). Without these the
+// `^ 1` fold just trades one double negative for another: `a0 >= a1 == 0`.
+//   icmp_eq(cmp, 0) → !cmp     `(a >= b) == 0`  is  `a < b`
+//   icmp_ne(cmp, 0) →  cmp     `(a >= b) != 0`  is  `a >= b`
+// Same soundness argument as the `^ 1` fold (an icmp result is 0/1, so `== 0` is exactly negation)
+// and the same shape-is-its-own-gate reason to leave them ungated.
+const cmpZeroPat = (cmp: string, test: 'icmp_eq' | 'icmp_ne'): RewritePattern => ({
+  id: `${test === 'icmp_eq' ? 'not' : 'is'}-zerotest-${cmp}`,
+  applies: {},
+  match: {
+    op: test,
+    args: [
+      { op: cmp, args: [{ bind: 'A' }, { bind: 'B' }] },
+      { op: 'const', attrEquals: { value: 0 }, args: [] },
+    ],
+  },
+  replaceWith: { op: test === 'icmp_eq' ? NEGATED_ICMP[cmp] : cmp, args: ['A', 'B'], resultType: T.u(32) },
+});
+
+/** `cmp ^ 1` and the zero-test forms `cmp == 0` / `cmp != 0` → the (negated) comparison. Every
+ *  entry is one comparison of `NEGATED_ICMP`; the bundle is what the boolean-reasoning consumers
+ *  downstream (short-circuit recovery, the structurer's condition spelling) actually match on. */
+export const NOT_CMP_PATTERNS: RewritePattern[] = [
+  ...Object.keys(NEGATED_ICMP).map(notCmpPat),
+  ...Object.keys(NEGATED_ICMP).flatMap((cmp) => [cmpZeroPat(cmp, 'icmp_eq'), cmpZeroPat(cmp, 'icmp_ne')]),
+];
+
 // The DEFAULT idiom bundle `decompile()` applies when the caller passes no `patterns`. It is
-// EVERY idiom asmlift owns; each is `{compilers}`-gated (patternApplies), so this one global list
-// self-selects per target — agbcc/gcc get sdiv-pow2, agbcc/ido/gcc get the mul-const folds, and a
-// target whose compiler matches none (mwcc) applies nothing. Ordered like the sub-bundles: the
+// EVERY idiom asmlift owns; the list self-selects per target through patternApplies — agbcc/gcc get
+// sdiv-pow2, agbcc/ido/gcc get the mul-const folds, mwcc gets cntlzw-eq0 + rotl-mirror, and agbcc
+// gets the casts. MOST patterns are `{compilers}`-gated because they trade one spelling for another
+// and are only byte-safe where measured; the boolean-negation folds are deliberately UNGATED (see
+// their comment — the shape is its own gate), so "gated per compiler" is the common case, not the
+// invariant. Ordered like the sub-bundles: the
 // division idiom, then the multiplies (base folds before the composite tail). Passing an explicit
 // `patterns` (including `[]`) overrides this — `[]` runs the naive lift with no idiom folding.
 export const DEFAULT_IDIOM_PATTERNS: RewritePattern[] = [
   SDIV_POW2_2,
   CNTLZW_EQ0,
+  // AFTER cntlzw-eq0, which is what turns mwcc's `clz(x) >> 5` into the `icmp_eq` this fold then
+  // negates — `!(x == 0)` composes only in that order (each pattern runs to fixpoint in turn).
+  ...NOT_CMP_PATTERNS,
   ROTL_MIRROR,
   ...MUL_CONST_PATTERNS,
   ...CAST_PATTERNS,
@@ -238,7 +327,11 @@ export const DEFAULT_IDIOM_PATTERNS: RewritePattern[] = [
 
 // Ops whose operands a compiler may emit in either order — so an idiom's match must try both
 // (agbcc emits `add(X, shr_u(X,31))`; KMC GCC emits `add(shr_u(X,31), X)` for the SAME `x/2`).
-const COMMUTATIVE = new Set(['add', 'mul', 'and', 'or', 'xor']);
+// `icmp_eq`/`icmp_ne` are here for the same reason, not as arithmetic: `x == 0` and `0 == x` are the
+// same test, and which one a frontend builds is an accident of how the branch was decoded — the
+// zero-test folds must match either. The ORDERED comparisons are deliberately absent: swapping the
+// operands of `a < b` is `b > a`, a different opcode, which this mechanism cannot express.
+const COMMUTATIVE = new Set(['add', 'mul', 'and', 'or', 'xor', 'icmp_eq', 'icmp_ne']);
 
 interface Binds {
   values: Map<string, Value>;

package/src/pipeline.ts

@@ -12,13 +12,15 @@ import { VerifyError, verify } from './ir/verify';
 import { Expr, LanguageBackend, SFn, Stmt, exprChildren, stmtChildren, stmtExprs } from './l3/ast';
 import { hoistReusedGlobalBases } from './l3/basecse';
 import { eliminateDeadStores } from './l3/dce';
+import { mergeCommonTails } from './l3/tailmerge';
 import { DEFAULT_IDIOM_PATTERNS, RewritePattern, applyPattern, dce, patternApplies } from './pattern/engine';
-import type { Prototypes } from './proto';
+import { type Prototypes, prototypesFromSymbols } from './proto';
 import { RaiseUnsupportedError } from './raise/errors';
 import { type PreRecoveryPass, runPreRecovery } from './raise/pre-recovery';
 import { recoverTypes } from './raise/recover';
 import { sinkReturns } from './raise/retsink';
 import { StructureError, structure } from './structure/structure';
+import { type SymbolMap, symbolsByName } from './symbols';
 import { type TargetDescription, structureOptionsFor } from './target';
 
 /** How a gap (a construct asmlift cannot faithfully model) degrades:
@@ -53,6 +55,10 @@ export interface DecompileOptions {
    *  MIPS/PPC switch declines/loud-fails; present ⇒ the frontend recovers the `switch_br`.
    *  Produced by `extractAsmData(obj, target)` from the scoring object. */
   asmData?: AsmData;
+  /** OPTIONAL address→symbol map (symbols.ts) — the project's own names (ELF symtab) and
+   *  declaration shapes (DWARF types-sidecar). Drives the Thumb numeric-pool promotion and the
+   *  byte-sensitive global spellings. Absent ⇒ byte-identical to today. */
+  symbols?: SymbolMap;
   /** gap policy — see `OnGap`. Default "strict". */
   onGap?: OnGap;
 }
@@ -97,9 +103,11 @@ function runTower(
   onGap: OnGap,
 ): DecompileResult {
   const backend = opts.backend ?? cBackend;
-  const prototypes = opts.prototypes ?? {};
+  // The project's own DWARF signatures fill in what the caller did not state — in practice the
+  // CALLEES (a function still in assembly has none), which is what makes this transferable.
+  const prototypes = prototypesFromSymbols(opts.symbols, opts.prototypes ?? {});
   // (1) lift: ISA frontend (resolved by target) → L1 with block-argument SSA
-  const fn = frontendFor(target).lift(name, asm, target, prototypes, opts.asmData);
+  const fn = frontendFor(target).lift(name, asm, target, prototypes, opts.asmData, opts.symbols);
   verify(fn);
   const raw = print(fn);
 
@@ -115,7 +123,11 @@ function runTower(
 
   // (4) structure: IR → neutral AST; boundary contract: no unresolved value leaked (strict), or
   // every unresolved value spelled as a loud ASMLIFT_ERROR marker (annotate).
-  const sfn = structureChecked(fn, { ...structureOptionsFor(target, prototypes[name]?.returnsVoid ?? false), onGap });
+  const sfn = structureChecked(fn, {
+    ...structureOptionsFor(target, prototypes[name]?.returnsVoid ?? false),
+    onGap,
+    ...(opts.symbols ? { symbols: symbolsByName(opts.symbols) } : {}),
+  });
 
   // (5) lower + print: neutral AST → target language
   const source = backend.emit(sfn);
@@ -187,10 +199,12 @@ export function structureChecked(fn: Fn, opts: Parameters<typeof structure>[1]):
   // removes statements/flips branches over an already-validated tree.
   assertResolved(raw);
   assertDerefsTyped(raw);
-  // Then the readability/quality rewrites: drop dead stores, then hoist a reused aggregate-global
+  // Then the readability/quality rewrites: merge a statement common to every arm of an if,
+  // drop dead stores (whose empty-then peephole flips the arm the merge empties), then hoist a
+  // reused aggregate-global
   // base into a typed local pointer. The hoist moves the deref cast from each `index` node onto the
   // local's initializer, so re-validate deref typing on the rewritten tree.
-  const sfn = hoistReusedGlobalBases(eliminateDeadStores(raw));
+  const sfn = hoistReusedGlobalBases(eliminateDeadStores(mergeCommonTails(raw)));
   assertDerefsTyped(sfn);
   return sfn;
 }

package/src/proto.ts

@@ -1,3 +1,5 @@
+import type { SymbolMap } from './symbols';
+
 // asmlift — function prototypes: the single carrier for the caller-supplied facts a
 // matching-decomp project reads from its headers (arg counts, void-ness). One `Prototypes`
 // map, keyed by symbol, is threaded through every entry point and resolved at the point of
@@ -40,3 +42,56 @@ export function protoArity(p: FnProto | undefined): number | undefined {
   // fall back to the frontend's arg-register heuristic rather than misread a string's `.length`.
   return undefined;
 }
+
+/** The C type spelling for one declared parameter/return, or null when the facts do not
+ *  determine one. A pointer is `void *` — address-identical to any object pointer, and asmlift
+ *  makes every stride explicit — so nothing is guessed about what it points at. */
+function typeSpelling(t: { size: number | null; signed: boolean | null; pointer?: boolean }): ParamType | null {
+  if (t.pointer) {
+    return 'void *';
+  }
+  if (t.size === 1 || t.size === 2 || t.size === 4) {
+    // A signless 4-byte type is the C89 enum idiom (int); a signless NARROW one has no honest
+    // spelling, and the width alone would not fix its load, so it is refused.
+    if (t.signed === null) {
+      return t.size === 4 ? 's32' : null;
+    }
+    return `${t.signed ? 's' : 'u'}${t.size * 8}`;
+  }
+  return null;
+}
+
+/**
+ * Prototypes the project's own DWARF states, merged UNDER the caller's.
+ *
+ * A caller-supplied proto always wins: it comes from the user's headers or the benchmark
+ * manifest, and it is the thing a real user actually has for the function they are decompiling.
+ * The map fills the rest — in practice the CALLEES, since a function still written in assembly
+ * has no signature in its project's ELF (see SymbolSignature).
+ *
+ * Every parameter must spell faithfully or the whole entry is dropped: a partly-typed list would
+ * be read for its LENGTH and give the right arity with the wrong widths, which is worse than the
+ * arg-register heuristic it would replace.
+ */
+export function prototypesFromSymbols(symbols: SymbolMap | undefined, base: Prototypes = {}): Prototypes {
+  if (!symbols) {
+    return base;
+  }
+  const out: Prototypes = { ...base };
+  for (const infos of symbols.values()) {
+    for (const info of infos) {
+      if (info.kind !== 'code' || !info.signature || out[info.name] !== undefined) {
+        continue;
+      }
+      const params = info.signature.params.map(typeSpelling);
+      if (params.some((p) => p === null)) {
+        continue;
+      }
+      out[info.name] = {
+        params: params as ParamType[],
+        ...(info.signature.returns === null ? { returnsVoid: true } : {}),
+      };
+    }
+  }
+  return out;
+}