@asmlift/core 0.3.0 → 0.4.0

package/README.md

@@ -38,7 +38,7 @@ Input is **text**, following what each target's toolchain produces:
 | Option       | Meaning                                                                                                                                                                                                                                                                                                                                                                                |
 | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `backend`    | `cBackend` (default) or `pascalBackend` — values from `@asmlift/core/backend/*`. C++ is `cppBackend(spec)`, a per-function factory: it takes a `CppFnSpec` (class/method name, explicit param types, class field layouts — what a project's headers supply) and covers free and non-virtual member functions with word-sized fields; virtual dispatch, references, ctors/dtors decline |
-| `patterns`   | Idiom rewrite patterns. Omitted = `DEFAULT_IDIOM_PATTERNS` (each gated per compiler); `[]` = none                                                                                                                                                                                                                                                                                      |
+| `patterns`   | Idiom rewrite patterns. Omitted = `DEFAULT_IDIOM_PATTERNS` (self-selects per target: most are compiler-gated, the boolean-negation folds are universal); `[]` = none                                                                                                                                                                                                                   |
 | `prototypes` | Callee arities + void-ness, as a real project takes them from headers — drives call-argument recovery                                                                                                                                                                                                                                                                                  |
 | `asmData`    | Optional `objdump -s -r -t` side-table; required to recover MIPS/PPC jump-table switches                                                                                                                                                                                                                                                                                               |
 | `onGap`      | `"strict"` (default): throw on any gap. `"annotate"`: emit best-effort source with `ASMLIFT_ERROR` markers; every gap is also returned in the structured `diagnostics` array (empty ⇔ gap-free)                                                                                                                                                                                        |
@@ -86,7 +86,7 @@ injected via hooks, never copied. `verify()` runs after every IR-mutating pass;
 | `pattern/engine.ts`                             | Idiom layer: **rewrite patterns as data** + greedy driver + DCE; `patternApplies` gates on Target capabilities                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `raise/*.ts`                                    | The pre-recovery recognizers, in ONE ordered list (`pre-recovery.ts`): const materialize → magic division (`magicdiv.ts`, Hacker's Delight inverse) → soft division → array legalize → struct-array → struct-pointer → short-circuit; plus `recover.ts` (L1→L2 type recovery), `retsink.ts` (return-sinking), `errors.ts` (`RaiseUnsupportedError`)                                                                                                                                                                                       |
 | `structure/*.ts`                                | L2→L3 in four modules: `loops.ts` (natural-loop discovery), `analysis.ts` (use registry, liveness, C4 materialization), `switch-recover.ts` (Regime-A comparison-tree recovery), `structure.ts` (SSA-destruction coalescing with interference checks + emission: if/while/do-while/for/switch, break/early-return)                                                                                                                                                                                                                        |
-| `l3/*.ts`                                       | `ast.ts`: language-**neutral** structured AST, the one traversal vocabulary (`exprChildren` etc.), and the `LanguageBackend` seam. Post-structure passes `dce.ts` + `basecse.ts`, the differ-ranked re-spelling levers `regspell.ts` + `reindex.ts`, and `typing.ts` (the rendered-expression C type the backends and contracts share)                                                                                                                                                                                                    |
+| `l3/*.ts`                                       | `ast.ts`: language-**neutral** structured AST, the one traversal vocabulary (`exprChildren` etc.), and the `LanguageBackend` seam. Post-structure passes `dce.ts` + `basecse.ts`, the shared hoist mechanism `hoist.ts`, the differ-ranked re-spelling levers `regspell.ts` + `reindex.ts` + `argbase.ts` + `scopebase.ts`, and `typing.ts` (the rendered-expression C type the backends and contracts share)                                                                                                                             |
 | `backend/{c,cpp,cfamily,pascal}.ts`             | Three backends: C and C++ (CodeWarrior mangling via `mangle.ts`) over the shared `cfamily.ts` substrate, and Pascal (`:=`, `div`, tail-position returns; unspellable constructs throw)                                                                                                                                                                                                                                                                                                                                                    |
 | `pipeline.ts`                                   | `decompile()` + the shared tower spine + annotate-mode stubs/diagnostics                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `trace.ts`                                      | `decompileTraced` — the traced tower (per-stage IR dumps + pattern before/after events), browser-pure; @asmlift/cli's `report.ts` enriches it with objdiff scores/candidates, the playground's Pipeline tab renders it directly                                                                                                                                                                                                                                                                                                           |
@@ -104,7 +104,9 @@ Recovered today: straight-line, if/else diamonds, natural loops (`while` / `do-w
 properly nested, in-body `break`/early-`return`), comparison-tree and jump-table switches,
 direct calls, constant-offset and variable-index memory (`*p`, `p[n]`, `a[i]`, struct fields),
 magic-number and soft division, short-circuit booleans, width casts. Still DECLINED (loud, never
-wrong code): **local stack frames** (address-taken locals / sp-as-data / live spills),
+wrong code): **local stack frames** (address-taken locals / sp-as-data; MIPS models word `sp`
+slots and PPC elides callee-saved save slots, so a spill/reload pair is modelled on those two —
+anything the narrow models cannot honour declines),
 **cross-block condition flags** on PPC (a `cmpw` whose branch lands in another block — the
 capability gap behind the mwcc switch stubs), computed tail calls, PIC/`gp`/SDA global access,
 switch fall-through, multi-latch/irreducible loops, floats, and 64-bit memory ops. Prototypes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asmlift/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "type": "module",
   "description": "Match decompile an assembly function to C or Pascal",

package/src/backend/cfamily.ts

@@ -9,6 +9,78 @@ import { IrType, T, scalarTypeForAccess, typeToString } from '../ir/types';
 import { BinOp, Expr, SFn, Stmt, dotBase } from '../l3/ast';
 import { type VarTypes, declaredTypes, derefStrideOk, exprCType } from '../l3/typing';
 
+/**
+ * The C SIGNEDNESS a rendered integer expression actually has — `true`/`false`, or `undefined`
+ * when it is not determinable here. The deliberate complement to l3/typing's `exprCType`, which is
+ * pointer-ness-accurate and reports every integer as `s32` by contract; this models the two C
+ * rules that contract omits, integer PROMOTION and the usual arithmetic CONVERSIONS.
+ *
+ * It lives HERE, in the C-family backend, because it is a model of C's own rules with no meaning
+ * for another language — the same reason the cast it feeds is synthesized here rather than in the
+ * tower. `exprCType` stays in l3/ because Pascal consults it too.
+ *
+ * It exists for one question, and the question is byte-load-bearing: C spells both `>>>` and `>>`
+ * as `>>` and chooses between them from the left operand's type. A logical shift rendered over a
+ * signed expression recompiles to `asr` where the target has `lsr`, and evaluates to a different
+ * value. The C-family backend casts the operand whenever this returns anything but the signedness
+ * the operator needs, so `undefined` is the safe answer in every case the model does not cover — a
+ * redundant cast is codegen-identical, a missing one is a miscompile.
+ *
+ * Anything narrower than 32 bits promotes to `int` and is therefore SIGNED, whatever it was
+ * declared. Pointers, calls and markers are `undefined`.
+ */
+function renderedIntSignedness(e: Expr, varType: VarTypes): boolean | undefined {
+  const rec = (x: Expr): boolean | undefined => renderedIntSignedness(x, varType);
+  // an lvalue-ish leaf: its C type is a declaration / an explicit cast / a carried access width
+  const promoted = (t: IrType | undefined): boolean | undefined =>
+    t?.kind !== 'int' ? undefined : t.width < 32 ? true : t.width === 32 ? t.signed : undefined;
+  switch (e.k) {
+    case 'var':
+    case 'cast':
+    case 'index':
+    case 'field':
+      return promoted(exprCType(e, varType));
+    // A decimal literal is `int` when it fits in one; C89 gives a larger one an unsigned type,
+    // which is not the same operand — so it is left undetermined rather than assumed. INT_MIN is
+    // in that larger class despite fitting: the backend prints it as `-2147483648`, which C lexes
+    // as unary minus applied to `2147483648` — a constant too big for `int`, hence unsigned long.
+    case 'const':
+      return e.value > -2147483648 && e.value <= 2147483647 ? true : undefined;
+    // `-x` / `~x` carry the PROMOTED type of the operand; `!x` is `int`.
+    case 'un':
+      return e.op === '!' ? true : rec(e.e);
+    case 'bin': {
+      // Shifts take the type of the LEFT operand alone — the right is promoted independently.
+      if (e.op === '<<' || e.op === '>>' || e.op === '>>>') {
+        return rec(e.l);
+      }
+      // Comparisons and the logical connectives yield `int`.
+      if (['<', '<=', '>', '>=', '==', '!=', '&&', '||'].includes(e.op)) {
+        return true;
+      }
+      // Usual arithmetic conversions over the remaining binary operators: at equal rank, unsigned
+      // wins. Either side unknown leaves the result unknown — EXCEPT when the known side is
+      // unsigned, which already decides it.
+      //
+      // That exception is the one place this returns a DEFINITE answer from an unknown operand,
+      // and it is sound only because every integer here is rank `int`: at UNEQUAL rank C converts
+      // to the wider type first, so `unsigned int & long long` is SIGNED. Core has no 64-bit
+      // integer type at all (the decomp typedef vocabulary stops at 32 — see contracts.ts
+      // SCALAR_WIDTHS), so the unequal-rank case cannot arise. Adding one would invalidate this.
+      const l = rec(e.l);
+      const r = rec(e.r);
+      if (l === false || r === false) {
+        return false;
+      }
+      return l === true && r === true ? true : undefined;
+    }
+    case 'call':
+    case 'marker':
+    case 'addr':
+      return undefined;
+  }
+}
+
 // C operator precedence (lower binds tighter). Used to emit MINIMAL parentheses. Shared: C++ has
 // the same precedence for these operators.
 const PREC: Record<BinOp, number> = {
@@ -19,6 +91,7 @@ const PREC: Record<BinOp, number> = {
   '-': 4,
   '<<': 5,
   '>>': 5,
+  '>>>': 5, // spells as C's `>>` (see printExpr's shift rule) — same precedence
   '<': 6,
   '<=': 6,
   '>': 6,
@@ -69,6 +142,8 @@ export interface StructFieldDecl {
   name: string;
   type: IrType;
   volatile?: boolean;
+  /** bitfield width — spells `u32 name : n;` (the map-layout synthesis is the only producer) */
+  bits?: number;
 }
 
 /** THE struct-declaration spelling — every `struct N { ... };` asmlift prints comes from here,
@@ -76,7 +151,9 @@ export interface StructFieldDecl {
  *  drift apart. One line, fields in caller order (the type is self-describing: padding is the
  *  caller's discipline, already present as real fields). */
 export function renderStructDecl(name: string, fields: StructFieldDecl[]): string {
-  return `struct ${name} { ${fields.map((f) => `${f.volatile ? 'volatile ' : ''}${cDeclare(f.type, f.name)};`).join(' ')} };`;
+  const one = (f: StructFieldDecl) =>
+    `${f.volatile ? 'volatile ' : ''}${cDeclare(f.type, f.name)}${f.bits !== undefined ? ` : ${f.bits}` : ''};`;
+  return `struct ${name} { ${fields.map(one).join(' ')} };`;
 }
 
 // A LEAF hook lets a C-family backend override how a `var` or `index` node spells WITHOUT
@@ -103,6 +180,28 @@ function printExpr(e: Expr, parentPrec: number, vt: VarTypes, leaf?: LeafHook):
     derefStrideOk(exprCType(ix.base, vt), ix.width)
       ? ix.base
       : { k: 'cast', to: T.ptr(scalarTypeForAccess(ix.width, ix.signed)), e: ix.base };
+  // C-FAMILY SHIFT LEGALIZATION, the same discipline one operator over. The tower keeps the two
+  // right shifts apart (`>>>` logical, `>>` arithmetic); C spells BOTH `>>` and picks between them
+  // from the LEFT OPERAND'S TYPE. So the operand must be made to carry the choice, or an `shr_u`
+  // recompiles to `asr` where the target has `lsr` AND evaluates differently —
+  // `*(u8 *)&g << 30 >> 30` promotes to `int`, so a 2-bit field holding 2 comes out -1.
+  //
+  // (engine.ts's zext fold covers the same hazard for widths C can NAME, by folding the whole
+  // shift pair to a cast op. Every other extract width — every bitfield read — lands here.)
+  //
+  // The cast is added unless the operand PROVABLY renders with the signedness the op needs:
+  // renderedIntSignedness answers `undefined` wherever its model does not reach, and a redundant
+  // cast is codegen-identical while a missing one is a miscompile. An existing 32-bit integer cast
+  // is REPLACED rather than wrapped — `(u32)(s32)&g` and `(u32)&g` are the same bytes, and the
+  // arithmetic rules upstream do emit that inner cast (intifyAddr).
+  const shiftOperand = (e0: Extract<Expr, { k: 'bin' }>): Expr => {
+    const wantSigned = e0.op === '>>';
+    if (renderedIntSignedness(e0.l, vt) === wantSigned) {
+      return e0.l;
+    }
+    const inner = e0.l.k === 'cast' && e0.l.to.kind === 'int' && e0.l.to.width === 32 ? e0.l.e : e0.l;
+    return { k: 'cast', to: T.int(32, wantSigned), e: inner };
+  };
   switch (e.k) {
     case 'var':
       return e.name;
@@ -123,6 +222,21 @@ function printExpr(e: Expr, parentPrec: number, vt: VarTypes, leaf?: LeafHook):
       // binds tighter than any prefix operator, so a cast/unary/deref base is printed at prec 1
       // and parenthesizes itself: `((u8 *)p)[1]`). The postfix form needs no outer parentheses.
       const base = legalized(e);
+      // Leading constant subscripts (a multidimensional array global's bare spelling) keep the
+      // postfix form whatever `idx` is: `g[0][0]` is the element, `*g[0]` would be its ROW.
+      //
+      // `lead` implies the base already strides the access width — its only producer registers a
+      // matching element type for the global (structure.ts bareArrayLead + noteGlobal). Nothing
+      // else enforced that, and the failure would be quiet-ish: legalization would wrap the base,
+      // spelling `((u16 *)g)[0][i]`, which subscripts a `u16` twice. Check it rather than assume.
+      if (e.lead && e.lead.length > 0) {
+        if (base !== e.base) {
+          throw new Error(
+            `c backend: a multidimensional array access needs a base that strides ${e.width} bytes as spelled`,
+          );
+        }
+        return `${rec(base, 1)}${e.lead.map((l) => `[${l}]`).join('')}[${rec(e.idx, 99)}]`;
+      }
       if (e.idx.k === 'const' && e.idx.value === 0) {
         const s = `*${rec(base, 2)}`;
         return parentPrec < 2 ? `(${s})` : s;
@@ -141,6 +255,13 @@ function printExpr(e: Expr, parentPrec: number, vt: VarTypes, leaf?: LeafHook):
       // first (the C++ member-access rewrite).
       const ix = dotBase(e);
       if (ix) {
+        // This path spells the index node from parts, so a `lead` would be DROPPED — an element
+        // access silently becoming a row's. Unreachable today (arrayAccess's lead branch requires
+        // `fieldOff === undefined`, which is exclusive with the dot form), but this is a
+        // text-returning path with no other guard, so it refuses rather than assumes.
+        if (ix.lead && ix.lead.length > 0) {
+          throw new Error(`c backend: a multidimensional array element has no struct-field spelling yet`);
+        }
         const hooked = leaf?.(ix, rec);
         const baseTxt = hooked ?? `${rec(ix.base, 1)}[${rec(ix.idx, 99)}]`;
         return `${baseTxt}.${e.name}`;
@@ -173,7 +294,9 @@ function printExpr(e: Expr, parentPrec: number, vt: VarTypes, leaf?: LeafHook):
     }
     case 'bin': {
       const p = PREC[e.op];
-      const s = `${rec(e.l, p)} ${e.op} ${rec(e.r, p - 1)}`;
+      // Both right shifts spell C's `>>`; `shiftOperand` supplies the operand cast that says which.
+      const shift = e.op === '>>' || e.op === '>>>';
+      const s = `${rec(shift ? shiftOperand(e) : e.l, p)} ${shift ? '>>' : e.op} ${rec(e.r, p - 1)}`;
       return p > parentPrec ? `(${s})` : s;
     }
   }

package/src/backend/cpp.ts

@@ -90,7 +90,9 @@ export function cppBackend(spec: CppFnSpec): LanguageBackend {
       // class pointer, and print an unscaled `this[2]` that C++ strides by sizeof(class).
       // Correct bytes over idiomatic spelling, never the reverse.
       const leaf: LeafHook = (e: Expr) => {
-        if (e.k === 'index' && e.base.k === 'var' && e.idx.k === 'const') {
+        // `lead` (a multidimensional array global) is not a receiver access and must not be
+        // rewritten to one — the hook returns text, so a dropped subscript would be silent.
+        if (e.k === 'index' && e.base.k === 'var' && e.idx.k === 'const' && !e.lead?.length) {
           const r = recv.get(e.base.name);
           if (r) {
             if (e.width === 4) {

package/src/backend/pascal.ts

@@ -35,6 +35,10 @@ const BIT_FN: Partial<Record<BinOp, string>> = {
   '|': 'bitor',
   '^': 'bitxor',
   '<<': 'lshift',
+  // `rshift` over this backend's signed `Integer` reproduces IDO's `sra` — verified byte-exact
+  // against upas (pascal-ido.test.ts `asr2`). `>>>`, the LOGICAL shift, has no verified spelling
+  // here and is therefore absent: it reaches the loud decline below rather than borrowing this
+  // one, which would emit an arithmetic shift where the machine did a logical one.
   '>>': 'rshift',
 };
 
@@ -83,6 +87,13 @@ function makePrinter(vt: VarTypes) {
         // any plausible `^Integer`-shaped callee agrees with the machine width; a sub-word access
         // through an unknowable base would DISCARD the node's width (upas checks types, not
         // machine widths), so it declines like a definite mismatch.
+        // Leading constant subscripts (a multidimensional array global) have no IDO Pascal
+        // spelling yet, and dropping them would read a ROW's address as an element — decline
+        // LOUD, like the address-of case above. Unreachable today (the symbol map is agbcc-only),
+        // but silence here would be the wrong kind of unreachable.
+        if (e.lead && e.lead.length > 0) {
+          throw new Error(`pascal backend: a multidimensional array access has no IDO Pascal spelling yet`);
+        }
         const bt = exprCType(e.base, vt);
         if ((bt !== undefined && !derefStrideOk(bt, e.width)) || (bt === undefined && e.width !== 4)) {
           throw new Error(

package/src/contracts.ts

@@ -5,7 +5,7 @@
 // wrong C.
 import type { Fn, Value } from './ir/core';
 import { type IrType, typeToString } from './ir/types';
-import type { Expr, SFn, Stmt } from './l3/ast';
+import type { BinOp, Expr, SFn, Stmt } from './l3/ast';
 import { exprChildren, fieldSpellsDot, stmtChildren, stmtExprs } from './l3/ast';
 import { declaredTypes, exprCType } from './l3/typing';
 
@@ -71,8 +71,21 @@ export function assertDerefsTyped(sfn: SFn): void {
   const vt = declaredTypes(sfn);
   const ctype = (e: Expr): IrType | undefined => exprCType(e, vt);
   const bad: string[] = [];
+  // A `void` function must not RETURN A VALUE. Holds by construction today — returnType() answers
+  // void only when every `ret` is operand-less — but `retType` has two producers (the recovered
+  // type and the prototype's `returnsVoid`) and the value-suppression lives in a third place
+  // (structure.ts's return lowering), so a regressing edit to any of them prints `return expr;`
+  // inside a void function. That is ill-formed C the candidate compiler only rejects two stages
+  // later, with a diagnostic pointing at the symptom rather than the pass. Cheap to state here.
+  if (sfn.retType.kind === 'void') {
+    const valued = (stmts: Stmt[]): boolean =>
+      stmts.some((s) => (s.k === 'return' && s.value !== undefined) || valued(stmtChildren(s)));
+    if (valued(sfn.body)) {
+      bad.push(`function '${sfn.name}' is typed void but a return carries a value`);
+    }
+  }
   // Ops C rejects outright on a pointer operand (the additive ops and &&/|| are legal C).
-  const NO_PTR_OPS = new Set(['&', '|', '^', '<<', '>>', '*', '/', '%']);
+  const NO_PTR_OPS = new Set<BinOp>(['&', '|', '^', '<<', '>>', '>>>', '*', '/', '%']);
   // The comparison operators — where a bare `&SYM` operand is SIGN-ambiguous, not ill-formed.
   const CMP_OPS = new Set(['<', '<=', '>', '>=', '==', '!=']);
   // 1/2/4 only: the decomp typedef vocabulary (C_TYPEDEFS) has no 64-bit scalar, so a width-8

package/src/declare.ts

@@ -37,6 +37,7 @@ import {
   ENUM_IS_SIGNED,
   type SymbolInfo,
   type SymbolStructField,
+  arrayInnerExtents,
   declaredFields,
   pointeeFields,
   symbolFieldType,
@@ -75,23 +76,41 @@ function structDecl(tag: string, layout: SymbolStructField[] | undefined, size:
     return null;
   }
   const fields: StructFieldDecl[] = [];
-  let cursor = 0;
+  // The cursor is in BITS (declaredFields' own discipline) so bitfield members seat exactly.
+  // Gaps pad as the u8 arrays they always were when both ends are byte-aligned, and as named
+  // `u32 asmlift_pad_N : k` bitfields otherwise — split at 32-bit unit boundaries, matching the
+  // no-straddle allocation rule declaredFields verified each kept member against. For a
+  // bitfield-free layout every gap is byte-aligned, so the emitted text is unchanged.
+  let bitCursor = 0;
   let pad = 0;
-  for (const m of members) {
-    if (m.offset > cursor) {
+  const padTo = (lo: number): void => {
+    while (bitCursor < lo) {
       // asmlift_-prefixed so a REAL member named pad_N (a decomp-header idiom) never collides
-      fields.push({ name: `asmlift_pad_${pad++}`, type: T.array(T.u(8), m.offset - cursor) });
+      const name = `asmlift_pad_${pad++}`;
+      if (bitCursor % 8 === 0 && lo % 8 === 0) {
+        fields.push({ name, type: T.array(T.u(8), (lo - bitCursor) / 8) });
+        bitCursor = lo;
+      } else {
+        const k = Math.min(lo - bitCursor, 32 - (bitCursor % 32));
+        fields.push({ name, type: T.u(32), bits: k });
+        bitCursor += k;
+      }
     }
+  };
+  for (const m of members) {
+    const bits = m.bitWidth !== undefined;
+    const lo = m.offset * 8 + (bits ? m.bitOffset! : 0);
+    padTo(lo);
     fields.push({
       name: m.name,
       type: fieldType(m),
       ...(m.volatile ? { volatile: true } : {}),
+      ...(bits ? { bits: m.bitWidth } : {}),
     });
-    cursor = m.offset + m.size;
+    bitCursor = bits ? lo + m.bitWidth! : (m.offset + m.size) * 8;
   }
-  if (size !== undefined && size > cursor) {
-    // tail padding to the declared size
-    fields.push({ name: `asmlift_pad_${pad}`, type: T.array(T.u(8), size - cursor) });
+  if (size !== undefined) {
+    padTo(size * 8); // tail padding to the declared size
   }
   return renderStructDecl(tag, fields);
 }
@@ -139,7 +158,14 @@ export function renderDeclarations(refs: SymbolRef[]): string {
         // A non-1/2/4 element width is never bare-indexed by core (only &gSym cast forms), so
         // an unsized u8[] decl is codegen-identical for every spelling core emits.
         const elem = info.elemSize !== undefined ? intType(info.elemSize, info.elemSigned ?? false) : null;
-        lines.push(`extern ${quals(info)}${elem ?? 'u8'} ${name}[];`);
+        // The RANK must be reproduced, or the declaration disagrees with the access core spells:
+        // a `gSym[0][i]` needs a 2-D declaration to be an element rather than a type error. The
+        // OUTERMOST extent is always left unsized — it is the one C lets a declaration omit, and
+        // omitting it keeps this decl compatible with the project's real one whatever its size
+        // (the same reason the rank-1 form has always been `[]`). Inner extents are load-bearing:
+        // they are what scales each leading subscript, so they are spelled exactly.
+        const rank = (arrayInnerExtents(info) ?? []).map((d) => `[${d}]`).join('');
+        lines.push(`extern ${quals(info)}${elem ?? 'u8'} ${name}[]${rank};`);
         break;
       }
       case 'struct': {

package/src/frontend/mips.ts

@@ -19,7 +19,7 @@
 // compares (`sltu`/`sltiu`) lower to `icmp_ult`; recover types their operands u32 so the backend
 // re-emits `sltu` (the operator is the same `<` — the signedness lives in the operand types).
 import { Fn, Op, Successor, Value, mkOp, mkValue } from '../ir/core';
-import type { Opcode } from '../ir/opcodes';
+import { NEGATED_ICMP, type Opcode } from '../ir/opcodes';
 import { T } from '../ir/types';
 import type { Prototypes } from '../proto';
 import type { TargetDescription } from '../target';
@@ -47,19 +47,6 @@ const COND_Z: Record<string, Opcode> = {
   bgez: 'icmp_sge',
 };
 const COND_RR: Record<string, Opcode> = { beq: 'icmp_eq', bne: 'icmp_ne' };
-// Negated icmp opcode (for the `slt …; beqz` "branch when false" fold).
-const NEG_ICMP: Record<string, Opcode> = {
-  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',
-  icmp_eq: 'icmp_ne',
-  icmp_ne: 'icmp_eq',
-};
 
 const isZero = (r: string) => r === 'zero' || r === '$0';
 // The stack pointer (`$29`). A `sw/lw` through it is not a store/load through a data pointer — it
@@ -604,6 +591,18 @@ export function lift(
       }
       return readVar(r, bi);
     };
+    // `slt`-family results, so a following `beqz`/`bnez` can fold into one compare.
+    //
+    // Keyed by the SSA VALUE the compare produced, never by its register. Keying by register is the
+    // bug: `slt v0,a0,a1; xori v0,v0,1; beqz v0,L` (a materialised `a0 >= a1` that a branch then
+    // tests — IDO's spelling, and a live benchmark row) redefines v0, and a register-keyed record
+    // folds the branch against the DEAD `slt`, silently emitting the INVERTED condition. A value
+    // cannot go stale that way: `condValue` resolves the branch's register to whatever value reaches
+    // it and looks THAT up, so a redefinition simply misses and the honest `icmp_eq(rX, 0)` is
+    // emitted. It also needs no invalidation discipline to be maintained by every future writer —
+    // which matters, because `write` is NOT the only path that redefines a register (`lui
+    // rD,%hi(SYM)` deliberately reassigns rD's meaning without it).
+    const cmpDef = new Map<Value, { opcode: string; lhs: Value; rhs: Value }>();
     const write = (r: string, v: Value) => {
       // Writing a register clears any pending `%hi` it held — the high-half address is gone once the
       // register is reassigned (e.g. `lw rHi, %lo(SYM)(rHi)` reuses the base as the load dest). A
@@ -626,13 +625,11 @@ export function lift(
     // DELIBERATELY (unlike divState): a cross-block `mult`/`mflo` pair has no observed inhabitant,
     // and the miss degrades to a LOUD opaque, never silence.
     let mulState: { rs: Value; rt: Value; signed: boolean } | null = null;
-    // `slt`-family results, so a following `beqz`/`bnez` can fold into one compare.
-    const cmpDef = new Map<string, { value: Value; opcode: string; lhs: Value; rhs: Value }>();
     const emitCmp = (opc: Opcode, d: string, lhs: Value, rhs: Value) => {
       const v = mkValue(T.unk(32));
       ops.push(mkOp(opc, { operands: [lhs, rhs], results: [v] }));
       write(d, v);
-      cmpDef.set(d, { value: v, opcode: opc, lhs, rhs });
+      cmpDef.set(v, { opcode: opc, lhs, rhs });
     };
 
     const decode = (ins: Instr) => {
@@ -1053,7 +1050,7 @@ function condValue(
   ops: Op[],
   read: (r: string) => Value,
   constVal: (n: number) => Value,
-  cmpDef: Map<string, { value: Value; opcode: string; lhs: Value; rhs: Value }>,
+  cmpDef: Map<Value, { opcode: string; lhs: Value; rhs: Value }>,
 ): Value {
   const mk = (opc: Opcode, l: Value, r: Value): Value => {
     const v = mkValue(T.unk(32));
@@ -1064,15 +1061,19 @@ function condValue(
     return mk(COND_RR[br.mnemonic], read(br.ops[0]), read(br.ops[1]));
   }
   // *z forms compare a register against zero — except beqz/bnez may fold a preceding `slt`.
-  const rs = br.ops[0];
-  const folded = cmpDef.get(rs);
+  // Resolve the register to its reaching VALUE first: that is the fold's key (so a redefinition
+  // between the compare and the branch misses instead of folding stale), and it is also what
+  // routes the operand through `read`'s loud guards (sp / `%hi` / `gp` used as data) on every
+  // path — the fold used to bypass them by never reading the register at all.
+  const rsv = read(br.ops[0]);
+  const folded = cmpDef.get(rsv);
   if (folded && br.mnemonic === 'bnez') {
-    return folded.value;
+    return rsv;
   } // branch when slt is true
   if (folded && br.mnemonic === 'beqz') {
-    return mk(NEG_ICMP[folded.opcode], folded.lhs, folded.rhs);
+    return mk(NEGATED_ICMP[folded.opcode], folded.lhs, folded.rhs);
   } // …when false
-  return mk(COND_Z[br.mnemonic], read(rs), constVal(0));
+  return mk(COND_Z[br.mnemonic], rsv, constVal(0));
 }
 
 /** The MIPS-II / IDO frontend, registered for the `mips` target. */

package/src/frontend/opaque.ts

@@ -7,6 +7,37 @@
 // This module owns only the POLICY (which token is the destination, which are register sources).
 // The frontend still owns the SSA plumbing (how to `read` a source and `write`/emit the result),
 // because that is block-local state the policy must not touch.
+//
+// ─── A NOTE ON ALTERNATIVE MNEMONIC SPELLINGS ──────────────────────────────────────────────────
+//
+// Every ISA here accepts more than one spelling for some instructions, and the frontends handle
+// that in two DIFFERENT ways on purpose. Which one is right is decided by the operands, not by
+// taste:
+//
+//   * PURE SYNONYM — same operands, same semantics, different name. Normalise it in a name→name
+//     table at the parse site, so every consumer of the mnemonic sees one name. Thumb does this
+//     for `ldsh`/`ldrsh`, `ldsb`/`ldrsb`, `ldm`/`ldmfd`/`ldmia`, `stm`/`stmea`/`stmia`, which
+//     ARM DDI 0029G Figure 1-6 gives a single encoding apiece.
+//
+//     The table is the right shape THERE because the mnemonic is read by more than the decode
+//     switch — Thumb's `classifyXfer` matches it to tell a return from an indirect jump, the
+//     `storeClass` below matches it to decide whether an unmodelled op may be skipped, and the
+//     instruction-size walk tests it for `bl`. An alias arm on one `case` fixes one of those.
+//
+//   * EXTENDED MNEMONIC / PSEUDO-INSTRUCTION — different operand GRAMMAR, so no rename can
+//     express it. Give it its own decode arm. MIPS `move rD,rS` (2 operands) is `addu rD,rS,zero`
+//     (3); PPC `mr rD,rS` is `or rD,rS,rS`; PPC `slwi rD,rS,n` (3) is `rlwinm rD,rS,n,mb,me` (5,
+//     with mask fields computed from n). Routing these through a table would be a category error.
+//
+// There is deliberately NO shared alias helper. As of writing, MIPS and PPC have no pure-synonym
+// gap at all — every `unmodelled instruction` decline they produce across the whole benchmark is
+// a genuinely unmodelled opcode (`lwc1`, `fmuls`, `fctiwz`, `subfe`, …), not a spelling — so such
+// a helper would have exactly one caller. The bar for extracting one is the bar this module itself
+// met: several frontends hand-copying the same policy AND observed drift between the copies.
+//
+// One thing that IS shared, and should stay shared: `display` below. A frontend that normalises
+// spellings must still REPORT the one its input actually used, or a decline sends the reader
+// looking for an instruction their disassembly does not contain.
 import { FrontendUnsupportedError } from './errors';
 
 export interface OpaquePolicy {
@@ -27,6 +58,11 @@ export interface OpaquePolicy {
   storeClass?: RegExp;
   /** attribution for thrown declines: the function being lifted (optionally "+ site"). */
   context?: string;
+  /** How to SPELL the mnemonic in messages, when that differs from the name used to classify it.
+   *  A frontend that normalises legacy spellings (Thumb `ldsh` -> `ldrsh`) classifies on the
+   *  canonical name but must report the one the input file actually contains — otherwise a decline
+   *  names an instruction the reader cannot find in their own .s. Defaults to `mnemonic`. */
+  display?: string;
   /** Mnemonics PROVABLY effect-free — or deliberately transparent (Thumb push/pop frame ops) —
    *  in this ISA: the ONLY unmodelled no-destination instructions that may be skipped. Any other
    *  no-destination unmodelled instruction THROWS: a side-effect-only instruction (swi, syscall,
@@ -54,13 +90,14 @@ export interface OpaqueDest {
  *  reaches structuring as the sentinel `?` and trips `assertResolved` — the loud failure the
  *  contract requires, instead of a stale/absent value surfacing as confidently-wrong source. */
 export function opaqueDest(mnemonic: string, ops: string[], policy: OpaquePolicy): OpaqueDest | null {
+  const shown = policy.display ?? mnemonic;
   if (policy.storeClass?.test(mnemonic)) {
     // `context` names the function (and, where the ISA has addresses, the site) — this message
     // lands verbatim in annotate-mode stub headers, where an un-attributed decline is
     // unactionable in a multi-function run.
     const where = policy.context ? `cannot lift '${policy.context}': ` : '';
     throw new FrontendUnsupportedError(
-      `${where}unmodelled store-class instruction '${mnemonic}' — a memory write cannot be skipped or degraded to a register opaque`,
+      `${where}unmodelled store-class instruction '${shown}' — a memory write cannot be skipped or degraded to a register opaque`,
     );
   }
   const norm = policy.normalize ?? ((s) => s);
@@ -71,7 +108,7 @@ export function opaqueDest(mnemonic: string, ops: string[], policy: OpaquePolicy
     } // explicitly transparent for this ISA
     const where = policy.context ? `cannot lift '${policy.context}': ` : '';
     throw new FrontendUnsupportedError(
-      `${where}unmodelled effect instruction '${mnemonic}' — no register destination to degrade, and skipping it would silently delete its effect`,
+      `${where}unmodelled effect instruction '${shown}' — no register destination to degrade, and skipping it would silently delete its effect`,
     );
   }
   if (policy.isZero?.(dst)) {