@asmlift/core 0.3.0 → 0.5.0

package/src/macros.ts

@@ -22,32 +22,206 @@ export interface AddressMacro {
   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 }> = {
+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 },
 };
 
-/** `#define NAME (*(TYPE *)0xADDR)` — the ONE shape recognized. Anything else (a two-level
- *  indirection, an offset expression, 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*(0[xX][0-9A-Fa-f]+)\s*\))\s*$/;
+/** 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} — including every `volatile` alias (`vu16`), whose
- *    qualifier must not be silently dropped;
+ *  - 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.
@@ -59,6 +233,21 @@ export function addressCastMacros(cppOutput: string): Map<number, AddressMacro>
 /** 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>();
@@ -67,15 +256,28 @@ export function addressCastMacrosFrom(defineLines: readonly string[]): Map<numbe
     if (!m) {
       continue;
     }
-    const [, name, body, typeName, addrText] = m;
+    const [, name, rawBody, typeName, addrText] = m;
     const type = SCALAR_TYPES[typeName];
     if (!type) {
-      continue; // unknown or volatile-qualified spelling — refuse
+      continue; // a spelling outside the closed table — refuse
     }
-    const address = Number.parseInt(addrText, 16);
-    if (!Number.isFinite(address)) {
-      continue;
+    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);
@@ -88,7 +290,14 @@ export function addressCastMacrosFrom(defineLines: readonly string[]): Map<numbe
       collided.add(address);
       continue;
     }
-    byAddress.set(address, { name, address, body, size: type.size, signed: type.signed });
+    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);

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

@@ -1,17 +1,24 @@
 // asmlift — the library entry point. `decompile(name, asm, target)` runs the raising tower and
 // returns structured results: the source, the per-level IR dumps, and diagnostics.
 import { cBackend } from './backend/c';
-import { ContractError, assertDerefsTyped, assertResolved, assertTypesRecovered } from './contracts';
+import {
+  ContractError,
+  assertDerefsTyped,
+  assertEffectsPreserved,
+  assertResolved,
+  assertTypesRecovered,
+} from './contracts';
 import type { AsmData } from './frontend/asmdata';
 import { FrontendUnsupportedError } from './frontend/errors';
 import { frontendFor } from './frontend/registry';
-import type { Fn } from './ir/core';
+import { type Block, type Fn, successorsOf } from './ir/core';
 import { print } from './ir/print';
 import { T } from './ir/types';
 import { VerifyError, verify } from './ir/verify';
-import { Expr, LanguageBackend, SFn, Stmt, exprChildren, stmtChildren, stmtExprs } from './l3/ast';
+import { Expr, LanguageBackend, SFn, Stmt, exprChildren, gapReasonFor, 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, prototypesFromSymbols } from './proto';
 import { RaiseUnsupportedError } from './raise/errors';
@@ -188,9 +195,55 @@ export function raiseRecovered(fn: Fn, target: TargetDescription, hooks: RaiseHo
   }
 }
 
+/** Run `body`; if it declines, name the unmodelled instructions the function carries.
+ *
+ *  An `opaque` degrades its own value AND makes its block impure, so a shape recognizer refuses:
+ *  `headerPure` rejects a header holding one, and the loop declines with "unrecovered back-edge …".
+ *  True and useless — the shape is fine, an instruction is missing — and the benchmark classifies
+ *  declines by that text, so the round is filed as a loop-capability gap and the improvement loop
+ *  builds the wrong thing.
+ *
+ *  Only ADDS attribution: never converts a decline into a success, never fires without an
+ *  unmodelled instruction, reachable blocks only (one in dead code did not cause the refusal). */
+function attributeOpaques<T>(fn: Fn, body: () => T): T {
+  try {
+    return body();
+  } catch (e) {
+    // Attribution is a nicety, so it must not be able to throw: a crash here would replace a
+    // DESIGNED loud failure with an incidental one, which contract-invariant.test.ts rejects by name.
+    if (!(e instanceof StructureError) || !fn.blocks[0]) {
+      throw e;
+    }
+    const seen = new Set<Block>([fn.blocks[0]]);
+    for (const stack = [fn.blocks[0]]; stack.length;) {
+      for (const s of successorsOf(stack.pop()!)) {
+        if (!seen.has(s)) {
+          seen.add(s);
+          stack.push(s);
+        }
+      }
+    }
+    const names = new Set<string>();
+    for (const b of seen) {
+      for (const op of b.ops) {
+        if (op.opcode === 'opaque') {
+          names.add(typeof op.attrs.mnemonic === 'string' ? op.attrs.mnemonic : '?');
+        }
+      }
+    }
+    if (!names.size || /unmodelled instruction/.test(e.message)) {
+      throw e;
+    }
+    // Through `gapReasonFor`, so the classifier sees its canonical text — a hand-written variant
+    // misses the mnemonic-anchored classes and every attributed decline lands in the generic bucket.
+    const list = [...names].sort().map(gapReasonFor).join(', ');
+    throw new StructureError(`${e.message} — and the function carries ${list}, which is the more likely cause`);
+  }
+}
+
 /** Stage 4 — structure + its boundary contracts, always as a pair. */
 export function structureChecked(fn: Fn, opts: Parameters<typeof structure>[1]): SFn {
-  const raw = structure(fn, opts);
+  const raw = attributeOpaques(fn, () => structure(fn, opts));
   // BOTH boundary contracts run on the pre-DCE tree: the readability pass must never be able to
   // hide a structuring defect by dropping the dead statement that carries it. assertResolved
   // catches an unresolved `?` value; assertDerefsTyped catches an ill-typed deref (e.g. a pointer
@@ -198,11 +251,17 @@ 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
+  assertEffectsPreserved(fn, raw);
+  // 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);
+  // Re-checked after the readability rewrites for the same reason deref typing is: a pass that
+  // merges arms or drops statements must not be able to lose or duplicate a call.
+  assertEffectsPreserved(fn, sfn);
   return sfn;
 }