@asmlift/core 0.3.0 → 0.4.0

package/src/frontend/ssa.ts

@@ -3,11 +3,20 @@
 // CFG (predecessors per block) and, per block, emits ops through `readVar`/`writeVar`; this
 // module materialises block-argument phis at joins and back-edges.
 //
+// `preds` is an EDGE list, not a block list: it carries one entry per CFG edge, so a `switch_br`
+// with several case values reaching one block appears there several times. Both readings are
+// needed and they are not interchangeable — phi wiring wants the distinct predecessor BLOCKS (one
+// value each), while the args it appends belong to the EDGES (every one of them). `distinctPreds`
+// names the first; `appendSuccessorArg` walks the second. (ir/core.ts `predecessors` and
+// structure.ts `predecessorBlocks` have the same duality, and structure.ts already dedups ad hoc
+// at its two join sites.)
+//
 // Protocol: create the builder, then fill blocks in index order. For each block, emit its
 // computation via read/writeVar, push its terminator op last (successors referencing
 // `irBlocks`, args left empty — phi wiring appends them), then call `markFilled(b)`. When all
 // blocks are filled, call `finish()` to remove trivial phis.
-import { Block, Fn, Successor, Value, mkValue, replaceAllUsesWith } from '../ir/core';
+import { Block, Fn, Value, mkValue } from '../ir/core';
+import { simplifyTrivialPhis } from '../ir/simplify';
 import { T } from '../ir/types';
 
 export interface SsaBuilder {
@@ -27,6 +36,7 @@ export interface SsaBuilder {
   finish(): void;
 }
 
+/** `preds` is per-EDGE (see the module header): one entry per CFG edge into each block. */
 export function makeSsaBuilder(name: string, blockCount: number, preds: number[][]): SsaBuilder {
   const irBlocks: Block[] = Array.from({ length: blockCount }, () => ({ params: [] as Value[], ops: [] }));
   const fn: Fn = { name, blocks: irBlocks };
@@ -38,6 +48,9 @@ export function makeSsaBuilder(name: string, blockCount: number, preds: number[]
   const phiBlock = new Map<Value, number>();
   const paramReg = new Map<Value, string>();
 
+  // `preds` lists an entry per CFG EDGE; these are the distinct predecessor BLOCKS.
+  const distinctPreds = (b: number): number[] => [...new Set(preds[b])];
+
   const writeVar = (reg: string, b: number, v: Value) => defs[b].set(reg, v);
   const readVar = (reg: string, b: number): Value => defs[b].get(reg) ?? readRecursive(reg, b);
 
@@ -55,7 +68,10 @@ export function makeSsaBuilder(name: string, blockCount: number, preds: number[]
       incompletePhis[b].set(reg, phi);
       return phi;
     }
-    const ps = preds[b];
+    // DISTINCT predecessor blocks: a switch_br reaching this block on several case values is one
+    // predecessor with several edges, and it supplies ONE value — counting the edges instead would
+    // manufacture a join (and a phi) where there is none.
+    const ps = distinctPreds(b);
     if (ps.length === 0) {
       // live-in with no predecessor: an incoming argument register → function parameter.
       const p = mkValue(T.unk(32));
@@ -75,16 +91,24 @@ export function makeSsaBuilder(name: string, blockCount: number, preds: number[]
     return phi;
   };
   const addPhiOperands = (reg: string, b: number) => {
-    for (const p of preds[b]) {
+    for (const p of distinctPreds(b)) {
       appendSuccessorArg(p, b, readVar(reg, p));
     }
   };
-  // Append `arg` to predecessor p's terminator successor that targets block b.
+  // Append `arg` to EVERY successor edge of predecessor p that targets block b.
+  //
+  // A predecessor normally has one edge to a given successor, but a `switch_br` has as many as it
+  // has case values, and two cases sharing a body (`case 1: case 2:`) is ordinary C. Block args
+  // belong to the EDGE, so each of those edges needs its own copy: appending to just the first (a
+  // `find`) left the others short, while `preds` listing the block once per edge made the loop run
+  // k times and pile k copies onto that same first edge. Both halves of that — every edge, once per
+  // predecessor BLOCK — have to hold together, which is why they are fixed in one place.
   const appendSuccessorArg = (p: number, b: number, arg: Value) => {
     const term = irBlocks[p].ops[irBlocks[p].ops.length - 1];
-    const s = term.successors.find((su) => su.block === irBlocks[b]);
-    if (s) {
-      s.args.push(arg);
+    for (const s of term.successors) {
+      if (s.block === irBlocks[b]) {
+        s.args.push(arg);
+      }
     }
   };
   const sealBlock = (b: number) => {
@@ -128,7 +152,7 @@ export function makeSsaBuilder(name: string, blockCount: number, preds: number[]
       filled[b] = true;
       sealReadyBlocks();
     },
-    finish: () => simplifyTrivialPhis(fn, phiBlock),
+    finish: () => simplifyTrivialPhis(fn, (p) => phiBlock.delete(p)),
   };
 }
 
@@ -167,48 +191,3 @@ export function abiSortEntryParams(
   }
   entry.params.sort((x, y) => rank(x) - rank(y));
 }
-
-// Remove block-parameters that are really trivial phis: those whose incoming operands (across
-// every predecessor edge, ignoring self-references from a back-edge) are all the same single
-// value. Such a parameter carries no join information — a loop-invariant register or a value
-// defined before the join — so it is replaced by that value and the corresponding argument
-// dropped from each predecessor's terminator. Iterated to fixpoint because removing one phi
-// can make another trivial.
-function simplifyTrivialPhis(fn: Fn, phiBlock: Map<Value, number>): void {
-  const edgesTo = (b: Block): Successor[] => {
-    const out: Successor[] = [];
-    for (const pb of fn.blocks) {
-      for (const op of pb.ops) {
-        for (const s of op.successors) {
-          if (s.block === b) {
-            out.push(s);
-          }
-        }
-      }
-    }
-    return out;
-  };
-  let changed = true;
-  while (changed) {
-    changed = false;
-    for (const b of fn.blocks) {
-      const incoming = edgesTo(b);
-      for (let i = b.params.length - 1; i >= 0; i--) {
-        const param = b.params[i];
-        const operands = incoming.map((s) => s.args[i]);
-        const distinct = [...new Set(operands.filter((v) => v !== param))];
-        if (distinct.length !== 1) {
-          continue;
-        } // a genuine join (or unreachable) — keep it
-        const v = distinct[0];
-        replaceAllUsesWith(fn, param, v);
-        b.params.splice(i, 1);
-        for (const s of incoming) {
-          s.args.splice(i, 1);
-        }
-        phiBlock.delete(param);
-        changed = true;
-      }
-    }
-  }
-}

package/src/frontend/thumb.ts

@@ -30,14 +30,74 @@ import { opaqueDest } from './opaque';
 import { abiSortEntryParams, fallbackArgc, makeSsaBuilder } from './ssa';
 
 interface Instr {
+  /** the CANONICAL spelling — legacy names are normalised (see LEGACY_MNEMONICS) so that every
+   *  consumer matches one name. */
   mnemonic: string;
   ops: string[];
+  /** the spelling the input file actually used, present only when normalisation changed it.
+   *  Messages must use this: a decline naming `ldrsh` for a file containing `ldsh` sends the
+   *  reader looking for an instruction that is not there. */
+  asWritten?: string;
 }
 interface AsmBlock {
   label: string;
   instrs: Instr[];
 }
 
+// Alternative mnemonic spellings, normalised at the single point where an instruction enters the
+// IR. Each maps to a name the decode switch below already handles.
+//
+// These are not "similar" instructions — each pair is ONE instruction with two accepted spellings.
+// The ARM7TDMI Technical Reference Manual (ARM DDI 0029G) gives a single encoding for each:
+// Figure 1-6 "Thumb instruction set formats" lists Format 08 "Load and store sign-extended byte and
+// halfword" (0101 H S 1 Ro Rb Rd) and Format 15 "Multiple load and store" (1100 L Rb Rlist), and
+// Table 1-7 "Thumb instruction set summary" spells them `LDRSH Rd, [Rb, Ro]`, `LDRSB Rd, [Rb, Ro]`,
+// `LDMIA Rb!, <reglist>` and `STMIA Rb!, <reglist>`. Older ARM7TDMI documentation used LDSH/LDSB,
+// which is where the short spellings come from; the stack-suffix forms (FD, EA) are the same
+// instructions named after the stack discipline they implement.
+//
+// Confirmed with this project's own toolchain — same encoding, and gba-kit executes them with the
+// same architectural effect (sign extension, transfers, base writeback):
+//
+//     ldsh  / ldrsh        885e / 885e        ldm   / ldmia / ldmfd   01c9 / 01c9 / 01c9
+//     ldsb  / ldrsb        8856 / 8856        stm   / stmia / stmea   01c1 / 01c1 / 01c1
+//
+// Measured on the Klonoa: Empire of Dreams disassembly (luvdis, 469 .s files): `ldsh` 292 and
+// `ldsb` 180 against `ldrsh` 0 and `ldrsb` 12 — the same tool emits both spellings for the signed
+// byte load — and `ldm` 12 / `stm` 34 against `ldmia` 0 / `stmia` 0. The UAL names this frontend
+// cased for the multiple forms never appear in that corpus at all.
+//
+// These are PURE SYNONYMS — identical operands — which is why they belong in a table here rather
+// than in decode arms like MIPS's `move` or PPC's `slwi`. That distinction, and why there is no
+// shared alias helper across the three frontends, is written up once in ./opaque.ts.
+//
+// The LOAD aliases matter more than the store ones, and the asymmetry is worth knowing: an
+// unrecognised `stm*` matches `opaquePolicy.storeClass` and fails LOUD, but an unrecognised `ldm*`
+// does not — it reaches opaqueDest, which takes ops[0] (the BASE) as the destination, so the opaque
+// is dead, DCE removes it, and the load silently vanishes. Measured: `ldmfd r1, {r0}; bx lr` lifted
+// to `return a0;` where the answer is `return *a0;`. Every load spelling ARMv4T Thumb accepts is
+// therefore listed. (`ldmed`/`ldmea` are NOT: they mean IB/DB, which Thumb-1 does not have, and
+// `as` rejects them — so they cannot appear.)
+//
+// `stmfd` is deliberately absent, and the asymmetry is real rather than an oversight: `stmfd` is
+// `stmdb`, and ARMv4T Thumb has neither — `as` rejects both with "selected processor does not
+// support ... in Thumb mode". There is nothing to normalise it TO.
+//
+// Null-prototype so that an inherited key (`constructor`, `toString`) cannot be mistaken for an
+// entry. Unreachable from real assembly, but the lookup should not depend on that.
+const LEGACY_MNEMONICS: Readonly<Record<string, string>> = Object.assign(Object.create(null), {
+  ldsh: 'ldrsh',
+  ldsb: 'ldrsb',
+  ldm: 'ldmia',
+  ldmfd: 'ldmia',
+  stm: 'stmia',
+  stmea: 'stmia',
+});
+
+function canonicalMnemonic(mn: string): string {
+  return LEGACY_MNEMONICS[mn] ?? mn;
+}
+
 // Map a Thumb conditional-branch mnemonic to the icmp opcode for "branch taken". The signed forms
 // (`blt`/`ble`/`bgt`/`bge`) follow a signed `cmp`; the UNSIGNED forms carry the carry/borrow sense:
 // `bhi` = unsigned > (higher), `bls` = unsigned <= (lower-or-same), `bcc`/`blo` = unsigned <
@@ -119,6 +179,48 @@ const imm = (s: string) => parseInt(s.replace(/^#/, ''), s.includes('0x') ? 16 :
 // detection sees them, and any consumer that needs the exact list rejects the leftover `-` token
 // loudly rather than treating the fused range as one phantom register.
 const REG_NUM: Record<string, number> = { sp: 13, lr: 14, pc: 15 };
+
+// Thumb-1 data-processing mnemonics that write the condition flags when their destination is a LOW
+// register — which is all of them on this ISA, `s`-suffix or not (the assembler picks the encoding).
+// Used to invalidate a pending compare: see the decode loop. `cmp`/`cmn`/`tst` are absent on purpose
+// — they set flags but define no register, and `cmp` is the very instruction that seeds the pending
+// compare. Loads, stores, push/pop, `bl` and the high-register forms leave the flags alone.
+const FLAG_SETTING = new Set([
+  'mov',
+  'movs',
+  'add',
+  'adds',
+  'sub',
+  'subs',
+  'lsl',
+  'lsls',
+  'lsr',
+  'lsrs',
+  'asr',
+  'asrs',
+  'neg',
+  'negs',
+  'rsb',
+  'rsbs',
+  'mvn',
+  'mvns',
+  'bic',
+  'bics',
+  'ror',
+  'rors',
+  'mul',
+  'muls',
+  'and',
+  'ands',
+  'orr',
+  'orrs',
+  'eor',
+  'eors',
+  'adc',
+  'adcs',
+  'sbc',
+  'sbcs',
+]);
 const regNum = (r: string) => (r[0] === 'r' ? Number(r.slice(1)) : REG_NUM[r]);
 function expandRegList(tokens: string[]): string[] {
   const out: string[] = [];
@@ -305,7 +407,14 @@ function decode(name: string, asm: string): { blocks: AsmBlock[]; dataWords: Map
       continue;
     }
     dataLabel = null; // a real instruction ends a data run
-    flat.push({ instr: { mnemonic: m[1], ops: m[2] ? splitOperands(m[2]) : [] } });
+    const canon = canonicalMnemonic(m[1]);
+    flat.push({
+      instr: {
+        mnemonic: canon,
+        ops: m[2] ? splitOperands(m[2]) : [],
+        ...(canon === m[1] ? {} : { asWritten: m[1] }),
+      },
+    });
   }
   if (
     armLabels.has(name) ||
@@ -608,6 +717,41 @@ function decode(name: string, asm: string): { blocks: AsmBlock[]; dataWords: Map
         `cannot lift '${name}': block '${mixed.label}' interleaves raw data (.${subwordData.get(mixed.label)}) with instructions`,
       );
     }
+    // Two labels on the same instruction (`.LCB80:` immediately followed by `.L7:`) make the first
+    // an ALIAS of the second, not a block of its own — agbcc emits exactly that when a long-jump
+    // helper label lands on an existing one. The empty block is dropped just below, so a branch
+    // naming the alias would afterwards resolve to nothing and decline as a dangling target. Point
+    // those branches at the block the label actually names, before anything reads the CFG.
+    // A label naming DATA is emphatically NOT an alias, and this is the guard the whole pass turns
+    // on. Decode pushes an empty block for a literal-pool / jump-table label too, so aliasing them
+    // blindly would silently retarget `beq .Lpool` at whatever code happens to follow the pool —
+    // marker-free, plausible, wrong C where the frontend used to decline. Every agbcc pool is a
+    // label on data, so that is the common case, not an exotic one. A data label therefore neither
+    // aliases nor is aliased THROUGH: scanning past one for a later code block would silently jump
+    // over the data.
+    const isDataLabel = (l: string) => dataWords.has(l) || subwordData.has(l);
+    const aliasOf = new Map<string, string>();
+    for (let i = 0; i < blocks.length; i++) {
+      if (blocks[i].instrs.length > 0 || isDataLabel(blocks[i].label)) {
+        continue;
+      }
+      let j = i + 1;
+      while (j < blocks.length && blocks[j].instrs.length === 0 && !isDataLabel(blocks[j].label)) {
+        j++;
+      }
+      const next = blocks[j];
+      if (next && next.instrs.length > 0) {
+        aliasOf.set(blocks[i].label, next.label);
+      } // otherwise a trailing or data-fronted label: left dangling so a branch to it still declines
+    }
+    for (const b of aliasOf.size ? blocks : []) {
+      for (const ins of b.instrs) {
+        const k = ins.ops.length - 1;
+        if ((ins.mnemonic === 'b' || COND_OPCODE[ins.mnemonic]) && k >= 0) {
+          ins.ops[k] = aliasOf.get(ins.ops[k]) ?? ins.ops[k];
+        }
+      }
+    }
     let live = blocks.filter((b) => b.instrs.length > 0);
     // Alignment-pad NOPs a splitter emits around returns and literal pools: `lsls r0, r0, #0`
     // is the 0x0000 halfword, `mov r8, r8` is 0x46C0, plus a literal `nop`. A block made ONLY
@@ -784,21 +928,47 @@ function recoverJumpTable(
   disp: AsmBlock,
   dataWords: Map<string, string[]>,
   blockLabels: Set<string>,
+  longDefault?: string,
 ): JumpTable | null {
-  // bounds: last two instrs must be `cmp rX,#M` then `bhi DEF` (unsigned upper-bound guard).
+  // bounds: last two instrs are `cmp rX,#M` then the out-of-range guard, in one of two spellings.
+  //
+  //   direct    cmp rX,#M ; bhi DEF                 → fall through to the dispatch
+  //   long jump cmp rX,#M ; bls DISP ; b DEF        → branch TO the dispatch, long-branch the default
+  //
+  // The second is what agbcc emits whenever the default is out of a conditional branch's reach —
+  // Thumb-1 `B<cond>` carries a signed 8-bit HALFWORD offset, so ±256 BYTES, about 128
+  // instructions — which on a real switch it usually is: five of the six benchmark
+  // functions with a table use it, and only the sixth uses the direct form. `longDefault` is the
+  // target of that trailing `b`, read by the caller from the block after `bounds`.
   const bi = bounds.instrs;
-  const bhi = bi[bi.length - 1],
+  const guard = bi[bi.length - 1],
     cmp = bi[bi.length - 2];
-  if (!bhi || !cmp || bhi.mnemonic !== 'bhi' || cmp.mnemonic !== 'cmp') {
+  if (!guard || !cmp || cmp.mnemonic !== 'cmp') {
     return null;
   }
+  let defaultLabel: string;
+  if (longDefault === undefined) {
+    if (guard.mnemonic !== 'bhi') {
+      return null;
+    }
+    defaultLabel = guard.ops[0];
+  } else {
+    // The `bls` must name THIS dispatch block, or the guard belongs to some other branch and the
+    // `b` we picked up is not its default.
+    if (guard.mnemonic !== 'bls' || guard.ops[0] !== disp.label) {
+      return null;
+    }
+    defaultLabel = longDefault;
+  }
   const scrutReg = cmp.ops[0];
   const m = cmp.ops[1];
   if (!m?.startsWith('#')) {
     return null;
   }
   const n = imm(m) + 1; // cases 0..M  → N = M+1
-  const defaultLabel = bhi.ops[0];
+  if (n < 1) {
+    return null; // a bound that admits no case at all is not a dispatch — fail closed
+  }
 
   // disp: exactly the 5-op idiom, threading a single index register from `lsl rY,rX,#2`.
   const d = disp.instrs;
@@ -835,11 +1005,28 @@ function recoverJumpTable(
   }
 
   // Read the table: the ldr loads a POINTER word (PTR: .word TABLE); the table is TABLE: .word C0…
-  const ptrWords = dataWords.get(ptrLabel);
-  if (!ptrWords || ptrWords.length !== 1) {
+  // Note the case labels are matched against `blockLabels` as WRITTEN: the adjacent-label aliasing in
+  // `decode` rewrites branch operands, not `.word` entries, so a table naming an aliased label would
+  // decline here rather than dispatch anywhere. Loud, and no corpus instance — left as a known edge
+  // rather than fixed speculatively.
+  //
+  // The pointer word is addressed the same way every other pool load in this frontend is —
+  // `LABEL[+N]`, selecting word N/4 — because a literal pool is a POOL: agbcc packs the dispatch
+  // pointer in beside whatever else the function needed, and which slot it lands in is an artifact
+  // of emission order. Reading only a bare label whose pool held exactly ONE word declined six real
+  // benchmark functions whose table pointer merely sat later in the pool. Same fix m2c made in
+  // `a7c5c2d`, and the same shared POOL_LABEL grammar the const/gaddr resolvers use, so the three
+  // cannot disagree about what `.L21+0x4` addresses.
+  const pm = ptrLabel.match(POOL_LABEL);
+  const ptrWords = pm ? dataWords.get(pm[1]) : undefined;
+  if (!pm || !ptrWords) {
     return null;
   }
-  const caseLabels = dataWords.get(ptrWords[0]);
+  const ptrOff = pm[2] ? Number(pm[2]) : 0;
+  if (ptrOff % 4 !== 0 || ptrOff / 4 >= ptrWords.length) {
+    return null; // misaligned or past the end of the pool — not a word this pool holds
+  }
+  const caseLabels = dataWords.get(ptrWords[ptrOff / 4].trim());
   if (!caseLabels || caseLabels.length !== n) {
     return null;
   } // table length must equal the bound
@@ -875,26 +1062,49 @@ export function lift(
   const poolNamesSymbols = poolNamesASymbol(dataWords, blockLabels);
   // Any label referenced as a branch target (so we can tell if an elided dispatch block has a SECOND
   // predecessor — a `b disp` from elsewhere — which would dangle after elision; decline if so).
-  const branchTargets = new Set<string>();
+  // How many branches name each label — not just whether any does, because the long-jump bounds
+  // form legitimately branches to its own dispatch block exactly once.
+  const branchRefs = new Map<string, number>();
   for (const b of rawBlocks) {
     for (const ins of b.instrs) {
       if ((ins.mnemonic === 'b' || COND_OPCODE[ins.mnemonic]) && ins.ops.length) {
-        branchTargets.add(ins.ops[ins.ops.length - 1]);
+        const t = ins.ops[ins.ops.length - 1];
+        branchRefs.set(t, (branchRefs.get(t) ?? 0) + 1);
       }
     }
   }
   const tables = new Map<AsmBlock, JumpTable>(); // bounds block → recovered table
-  const elided = new Set<AsmBlock>(); // dispatch blocks removed from the CFG
+  const elided = new Set<AsmBlock>(); // dispatch (and long-jump default) blocks removed from the CFG
   rawBlocks.forEach((d, i) => {
     const last = d.instrs[d.instrs.length - 1];
-    if (last && last.mnemonic === 'mov' && last.ops[0] === 'pc' && last.ops[1] !== 'lr') {
-      const bounds = rawBlocks[i - 1];
-      // The dispatch block must be reached ONLY by falling through from its bounds predecessor — a
-      // `b disp` target elsewhere would leave a dangling edge after elision, so decline (→ loud-fail).
-      const jt = bounds && !branchTargets.has(d.label) ? recoverJumpTable(bounds, d, dataWords, blockLabels) : null;
+    if (!last || last.mnemonic !== 'mov' || last.ops[0] !== 'pc' || last.ops[1] === 'lr') {
+      return;
+    }
+    const refs = branchRefs.get(d.label) ?? 0;
+    const prev = rawBlocks[i - 1];
+    // Direct form: the dispatch is reached ONLY by falling through from its bounds predecessor. A
+    // `b disp` from anywhere else would leave a dangling edge after elision, so decline (→ loud-fail).
+    if (prev && refs === 0) {
+      const jt = recoverJumpTable(prev, d, dataWords, blockLabels);
       if (jt) {
-        tables.set(bounds, jt);
+        tables.set(prev, jt);
         elided.add(d);
+        return;
+      }
+    }
+    // Long-jump form: `bounds` (cmp; bls DISP), then a lone `b DEF` block, then the dispatch. The
+    // dispatch is entered by exactly that one `bls` and nothing else, and the `b DEF` block —
+    // synthetically labelled, so unnameable and unreachable once the bounds block dispatches — is
+    // elided WITH it. Leaving it would make it a parameterless predecessor of the default block,
+    // and wiring a phi through it fabricates an entry parameter (the phantom-param miscompile).
+    const boundsB = rawBlocks[i - 2];
+    const prevNamed = prev ? (branchRefs.get(prev.label) ?? 0) > 0 : false;
+    if (refs === 1 && prev && boundsB && !prevNamed && prev.instrs.length === 1 && prev.instrs[0].mnemonic === 'b') {
+      const jt = recoverJumpTable(boundsB, d, dataWords, blockLabels, prev.instrs[0].ops[0]);
+      if (jt) {
+        tables.set(boundsB, jt);
+        elided.add(d);
+        elided.add(prev);
       }
     }
   });
@@ -1028,7 +1238,7 @@ export function lift(
     // adjustments have no low-register data destination, so they fall through harmlessly;
     // terminators are handled in the terminator section below.
     const isThumbReg = (s: string | undefined): s is string => /^r\d+$/.test(s ?? '');
-    const emitOpaqueDest = (ins: { mnemonic: string; ops: string[] }) => {
+    const emitOpaqueDest = (ins: { mnemonic: string; ops: string[]; asWritten?: string }) => {
       // storeClass: unmodelled Thumb stores are str*/stm* — `stmia rN!, {…}`'s dest token `r0!`
       // fails isReg, so without this it would be skipped as "no reg dest", silently deleting the
       // memory writes AND the base writeback. push/pop stay transparent frame ops (they don't match).
@@ -1040,6 +1250,7 @@ export function lift(
         storeClass: /^(str|stm)/,
         skipSafe: /^(push|pop|nop)$/,
         context: name,
+        display: ins.asWritten,
       });
       if (!od) {
         return;
@@ -1047,7 +1258,7 @@ export function lift(
       const operands = od.srcRegs.map((r) => readVar(r, bi));
       const res = mkValue(T.unk(32));
       // carry the mnemonic so annotate mode can name the gap (`ASMLIFT_ERROR("unmodelled 'rsb'")`)
-      irb.ops.push(mkOp('opaque', { operands, results: [res], attrs: { mnemonic: ins.mnemonic } }));
+      irb.ops.push(mkOp('opaque', { operands, results: [res], attrs: { mnemonic: ins.asWritten ?? ins.mnemonic } }));
       writeVar(od.dst, bi, res);
     };
     // 2-operand ALU form `op rD, op2` (rD = rD ⟨op⟩ op2). `op2` is an immediate (`#N`) or a
@@ -1076,6 +1287,22 @@ export function lift(
       if (classifyXfer(ins)) {
         continue;
       }
+      // A Thumb-1 data-processing instruction on LOW registers writes the condition flags whether or
+      // not the mnemonic carries the `s` (agbcc spells `adds r0,r0,r3` as `add r0,r0,r3`, and the
+      // assembler picks the flag-setting encoding) — so an instruction between a `cmp` and its branch
+      // REPLACES the flags the branch will test. Folding the earlier `cmp` in anyway would emit a
+      // condition on the wrong operands: silently wrong C with no marker. Drop the pending compare
+      // and let the terminator's existing "no reaching compare in its block" decline fire — the loud
+      // answer, since modelling arithmetic flags is a capability asmlift does not have.
+      //
+      // The HIGH-register forms (`mov rD,rH`, `add rD,rH`) do NOT set flags and stay transparent,
+      // which is what keeps agbcc's callee-saved shuffling from tripping this. Measured free: across
+      // every agbcc row in the benchmark, no conditional-branch block has ANY instruction between its
+      // compare and the branch — compilers keep the pair adjacent. The inhabitant this guards is
+      // hand-written asm in the playground, where there is no oracle to catch a lie.
+      if (FLAG_SETTING.has(ins.mnemonic) && /^r[0-7]$/.test(reg(ins.ops[0] ?? ''))) {
+        pendingCmp = null;
+      }
       const [a, b, c] = ins.ops;
       switch (ins.mnemonic) {
         case 'mov':
@@ -1215,9 +1442,18 @@ export function lift(
           // rejoin below also tolerates a split list defensively. Thumb-1 LDMIA skips the
           // writeback when rN is itself in the list (the loaded value wins) — modelled; any
           // malformed shape degrades to the loud opaque.
-          // `!` = writeback (`ldmia rN!, {…}`); its absence is the valid no-writeback form
-          // (`ldmia rN, {…}` — same transfers, base unchanged). A missing register list is
-          // malformed → loud opaque.
+          // There is NO no-writeback form in Thumb-1, so the `!` is decoration and must not drive
+          // the model. Four sources agree:
+          //   * ARM DDI 0029G Table 1-7 gives the canonical syntax as `LDMIA Rb!, <reglist>` and
+          //     `STMIA Rb!, <reglist>` — the `!` is part of the mnemonic, not an option, and
+          //     Figure 1-6 Format 15 has no bit that could encode its absence;
+          //   * GNU as assembles `ldm r1,{r0}` and `ldm r1!,{r0}` to the same halfword, 0xc901,
+          //     and warns "this instruction will write back the base register";
+          //   * gba-kit executes both with the base advanced by 4;
+          //   * GBATEK, THUMB.15: "Both STM and LDM are incrementing the Base Register".
+          // An earlier version of this comment called the `!`-less spelling "the valid
+          // no-writeback form — same transfers, base unchanged", which is false, and the code
+          // below acted on it. A missing register list is malformed → loud opaque.
           const baseTok = a;
           const writeback = !!baseTok?.endsWith('!');
           if (baseTok === undefined || b === undefined || !b.startsWith('{')) {
@@ -1244,6 +1480,30 @@ export function lift(
             emitOpaqueDest(ins);
             break;
           }
+          // An STM whose base is in its own list, but is not the LOWEST entry, stores a value this
+          // frontend must not guess — because the available references DISAGREE about what it is.
+          //
+          //   ARM:      UNPREDICTABLE, "the stored value cannot be relied upon".
+          //   GNU as:   warns "value stored for rN is UNKNOWN".
+          //   GBATEK:   version-specific — "Store OLD base if Rb is FIRST entry in Rlist,
+          //             otherwise store NEW base (STM/ARMv4), always store OLD base (STM/ARMv5)".
+          //   mGBA:     stores the OLD base unconditionally, on an ARMv4T core — its STM_LOOP
+          //             reads gprs[i] during the loop and the writeback runs after it.
+          //
+          // So GBATEK's ARMv4 rule and the reference emulator's behaviour do not agree, and no
+          // hardware test result was found either way. This frontend used to emit the old base,
+          // i.e. it silently picked one side of that disagreement. Declining is the contract:
+          // where the architecture declines to define a value, so do we.
+          //
+          // (One site in the Klonoa corpus, in unreachable code after a `pop`/`bx`, and it already
+          // declines for an unrelated pc-relative-pool reason — so this costs nothing today.)
+          if (ins.mnemonic === 'stmia' && list.some((r) => reg(r) === baseReg) && reg(list[0]) !== baseReg) {
+            throw new FrontendUnsupportedError(
+              `cannot lift '${name}': stm with the base register in its own list, not as the lowest ` +
+                `entry — the value stored for that register is UNPREDICTABLE and differs between ` +
+                `ARMv4 (new base) and ARMv5 (old base)`,
+            );
+          }
           // SNAPSHOT the base ONCE: hardware performs every transfer from the ORIGINAL base, but
           // a base-in-list ldmia overwrites that register mid-list — re-reading it per iteration
           // loaded the siblings from the freshly-loaded value instead (silent wrong addresses,
@@ -1260,10 +1520,12 @@ export function lift(
               irb.ops.push(mkOp('store', { operands: [base0, readData(reg(r), bi)], attrs: { off: 4 * i, width: 4 } }));
             }
           });
-          // Writeback advances the base by 4×count — SUPPRESSED when there is no `!`, or (ldmia)
-          // when the base is itself in the list (the loaded value wins, ARMv4T).
+          // Writeback advances the base by 4×count. It is suppressed ONLY for an ldmia whose base
+          // is in its own list — the loaded value wins. GBATEK, THUMB.15: "no writeback
+          // (LDM/ARMv4/ARMv5; at this point, THUMB opcodes work different than ARM opcodes)".
+          // The `!` is NOT what decides it: see above, there is no encoding without writeback.
           const wroteBase = ins.mnemonic === 'ldmia' && list.some((r) => reg(r) === baseReg);
-          if (writeback && !wroteBase) {
+          if (!wroteBase) {
             const adv = mkValue(T.unk(32));
             irb.ops.push(mkOp('add', { operands: [base0, constVal(4 * list.length, bi)], results: [adv] }));
             writeVar(baseReg, bi, adv);
@@ -1477,7 +1739,20 @@ export function lift(
       irb.ops.push(mkOp('br', { successors: [succ(fallLabel(bi))] }));
     } else if (kind === 'return') {
       // bx lr / pop {…,pc} / mov pc,lr
-      irb.ops.push(mkOp('ret', { operands: [readVar(target.returnReg, bi)] }));
+      //
+      // A `bx rN` BRANCHES THROUGH rN, so at that instruction rN holds the RETURN ADDRESS. When rN
+      // is the return-VALUE register the two uses collide, and the address wins by definition —
+      // whatever value was in r0 is gone, so the function cannot be returning one. agbcc spells an
+      // interworking return that way (`push {lr}` … `pop {r0}; bx r0`), and reading r0 as a value
+      // there invents a return the machine provably cannot make: a phantom `return`, a non-`void`
+      // signature that would contradict the project's own prototype, and a live range that keeps
+      // otherwise-dead computation alive.
+      //
+      // The other return forms are untouched, because none of them writes the return register:
+      // `bx lr` and `bx r1`/`bx r2` branch through a different one, and `pop {…,pc}` / `mov pc,lr`
+      // load PC directly. Only the register actually branched through is disqualified.
+      const viaReturnReg = last.mnemonic === 'bx' && last.ops[0] === target.returnReg;
+      irb.ops.push(mkOp('ret', { operands: viaReturnReg ? [] : [readVar(target.returnReg, bi)] }));
     } else if (kind === 'uncond') {
       irb.ops.push(mkOp('br', { successors: [succ(last.ops[0])] }));
     } else if (kind === 'cond') {

package/src/ir/opcodes.ts

@@ -130,11 +130,55 @@ export function opSig(opcode: string): OpSig | undefined {
   return (OPCODES as Record<string, OpSig | undefined>)[opcode];
 }
 
+/** The comparison whose result is the logical NEGATION of each `icmp_*` — `!(a < b)` is `a >= b`.
+ *
+ *  Unlike EFFECTFUL_OPS/HOIST_UNSAFE_OPS below, this is AUTHORED data seated beside the registry,
+ *  not a view derived from it: nothing in `OPCODES` states which comparison opposes which. What is
+ *  derived is its SYMMETRY — the five involutive pairs are expanded both ways, so `neg(neg(c)) === c`
+ *  holds by construction (a hand-written map is one typo away from breaking it, and the symptom is a
+ *  plainly inverted condition in the emitted C). Completeness against the icmp family is the part
+ *  construction cannot give, so a test asserts it (test/pattern.test.ts) — an eleventh comparison
+ *  added to `OPCODES` would otherwise degrade three consumers three different ways.
+ *
+ *  It lives here for the reason HOIST_UNSAFE_OPS does: every consumer that has to say "the opposite
+ *  of this compare" reads THIS one — the MIPS frontend's `slt …; beqz` branch-when-false fold, the
+ *  short-circuit recognizer's diamond negation, and the idiom layer's `cmp ^ 1` fold — so they
+ *  cannot drift apart the way inline copies did. Two adjacent facts worth knowing: raise/
+ *  shortcircuit.ts derives its `BOOL_OPS` from these keys (asserting negatable-icmp == boolean-op,
+ *  true today), and l3/ast.ts `NEGATE_REL` is the SAME relation over the neutral L3 operator
+ *  vocabulary — deliberately separate, because signedness lives in the operand types there, so the
+ *  two tables are not candidates for further consolidation. */
+const ICMP_NEGATION_PAIRS: readonly (readonly [Opcode, Opcode])[] = [
+  ['icmp_eq', 'icmp_ne'],
+  ['icmp_slt', 'icmp_sge'],
+  ['icmp_sgt', 'icmp_sle'],
+  ['icmp_ult', 'icmp_uge'],
+  ['icmp_ugt', 'icmp_ule'],
+];
+export const NEGATED_ICMP: Readonly<Record<string, Opcode>> = Object.fromEntries(
+  ICMP_NEGATION_PAIRS.flatMap(([a, b]) => [
+    [a, b],
+    [b, a],
+  ]),
+);
+
 /** Ops with an observable side effect — the derived view raise/shortcircuit.ts consumes. */
 export const EFFECTFUL_OPS: ReadonlySet<string> = new Set(
   (Object.keys(OPCODES) as Opcode[]).filter((k) => (OPCODES[k] as OpSig).effects),
 );
 
+/** Ops that may not be REORDERED across other code — `EFFECTFUL_OPS` plus `opaque`.
+ *
+ *  `effects` is overloaded on two axes, and `opaque` is exactly the op that separates them: a dead
+ *  `opaque` MUST stay deletable (`isDceSafe` below says so deliberately — giving it `effects: true`
+ *  would strand dead opaques after every pattern rewrite, and they would surface as ASMLIFT_ERROR
+ *  gaps in functions that emit cleanly today), while a LIVE one is an instruction asmlift could not
+ *  model and must not be moved past anything. So "deletable when dead" and "movable when live" are
+ *  different questions and get different views, both derived here rather than re-spelled per
+ *  consumer — structure/analysis.ts and structure/structure.ts each carry their own inline copy of
+ *  this membership, which is how the two models drifted apart in the first place. */
+export const HOIST_UNSAFE_OPS: ReadonlySet<string> = new Set([...EFFECTFUL_OPS, 'opaque']);
+
 /** May a dead result of this opcode be deleted? Registered, no observable effects, not control
  *  flow. Deliberately includes `opaque` — a dead opaque vanishing is designed behavior. */
 export function isDceSafe(opcode: string): boolean {