@asmlift/core 0.1.0 → 0.3.0

package/src/frontend/mips.ts

@@ -30,6 +30,7 @@ import { FrontendUnsupportedError } from './errors';
 import { assertInputFormat } from './format';
 import type { Frontend } from './frontend';
 import { opaqueDest } from './opaque';
+import { isSplatMips, parseSplatMips } from './splat';
 import { abiSortEntryParams } from './ssa';
 import { makeSsaBuilder } from './ssa';
 
@@ -87,6 +88,99 @@ const isXfer = (ins: Instr) => isReturn(ins) || isUncond(ins) || isCond(ins);
 // `sll`+`addu` before the access, so no `base+index` addressing form appears in parseMem input.
 const parseDisasm = (disasm: string): Instr[] => parseSharedDisasm(disasm);
 
+// A MIPS `%hi`/`%lo` relocation operand — the assembler's HI16/LO16 split that materialises the
+// address of a named global: `%hi(SYM)`, `%lo(SYM)`, `%hi(SYM + N)`, or the memory form
+// `%lo(SYM + N)(base)`. Splat spells global access this way and the Splat parser preserves it
+// verbatim (frontend/splat.ts); the objdump dialect hides the symbol in a relocation, which
+// `applyMipsGlobalRelocs` rewrites into the same `%hi`/`%lo` operands. Either way `lift` folds a
+// `lui %hi` + its consuming `%lo` into a single `gaddr(SYM)` (the op the Thumb frontend also emits
+// for a pool-loaded global), carrying the addend as the access offset. Returns null for a
+// non-`%hi/%lo` operand.
+function parseReloc(kind: 'hi' | 'lo', operand: string): { sym: string; addend: number; base?: string } | null {
+  const m = operand.match(
+    new RegExp(String.raw`^%${kind}\(\s*([A-Za-z_.$][\w.$]*)\s*(?:\+\s*(0x[0-9a-fA-F]+|\d+))?\s*\)(?:\((\w+)\))?$`),
+  );
+  if (!m) {
+    return null;
+  }
+  return { sym: m[1], addend: m[2] ? parseImm(m[2]) : 0, base: m[3] };
+}
+
+// Bridge objdump global-access relocations into the `%hi`/`%lo` operands `parseReloc` reads, so the
+// gaddr recognition recovers named globals from an object file the same way it does from Splat text.
+// In objdump a global load shows `lui rX,0x0` with the symbol ONLY in the `R_MIPS_HI16`/`LO16`
+// reloc records — without this the base decodes as address 0 and the access reads `*(T *)0`. Using
+// asmData, rewrite each `lui`'s immediate to `%hi(SYM)` and its paired consumer's operand to
+// `%lo(SYM[+N])`. Mirrors the harness's disasmToM2c rewrite, so asmlift and m2c recover the same
+// symbols. NAMED object symbols only — a reloc against a `.rodata`/`.data` SECTION is a jump-table
+// base (Regime B) or section-relative data, left untouched.
+function applyMipsGlobalRelocs(instrs: Instr[], ad: AsmData): void {
+  const byAddr = new Map(instrs.map((ins) => [ins.addr, ins]));
+  const his: { addr: number; sym: string }[] = [];
+  const los = new Map<number, string>(); // LO16 instruction addr → symbol
+  for (const r of ad.relocs) {
+    if (r.section !== '.text' || r.sym.startsWith('.')) {
+      continue; // section-symbol relocs are jump tables / anonymous data — not named globals
+    }
+    if (r.type === 'R_MIPS_HI16') {
+      his.push({ addr: r.offset, sym: r.sym });
+    } else if (r.type === 'R_MIPS_LO16') {
+      los.set(r.offset, r.sym);
+    }
+  }
+  if (his.length === 0) {
+    return;
+  }
+  his.sort((a, b) => a.addr - b.addr);
+  const loAddrs = [...los.keys()].sort((a, b) => a - b);
+  const consumed = new Set<number>();
+  for (const hi of his) {
+    const lui = byAddr.get(hi.addr);
+    if (!lui || lui.mnemonic !== 'lui') {
+      continue;
+    }
+    // Pair with the first not-yet-consumed same-symbol LO16 after the lui (GCC emits the pair with
+    // the base register threaded, so a 1:1 by-symbol-and-order match is the observed shape).
+    const loAddr = loAddrs.find((a) => a > hi.addr && !consumed.has(a) && los.get(a) === hi.sym);
+    const lo = loAddr !== undefined ? byAddr.get(loAddr) : undefined;
+    if (!lo) {
+      continue;
+    }
+    // The addend N rides in the instruction fields, not the reloc record: `(HI16 imm << 16) + the
+    // LO16 instruction's signed immediate`. HI16 imm is 0 in a relocatable object.
+    const rw = rewriteLoReloc(lo, hi.sym, parseImm(lui.ops[1] ?? '0') << 16);
+    if (rw === null) {
+      continue; // an unmodelled consumer (FP load, …) — leave the pair raw; it declines downstream
+    }
+    lui.ops[1] = rw.n === 0 ? `%hi(${hi.sym})` : `%hi(${hi.sym} + 0x${rw.n.toString(16)})`;
+    consumed.add(loAddr!);
+  }
+}
+
+// Rewrite a LO16 consumer's operand to `%lo(SYM[+N])`, returning the addend N, or null when the
+// instruction is not a modelled global consumer (leave it raw). `hiBase` is the HI16 imm << 16.
+function rewriteLoReloc(lo: Instr, sym: string, hiBase: number): { n: number } | null {
+  const macro = (n: number) => (n === 0 ? `%lo(${sym})` : `%lo(${sym} + 0x${n.toString(16)})`);
+  if (lo.mnemonic === 'addiu' || lo.mnemonic === 'addi') {
+    const n = hiBase + parseImm(lo.ops[2] ?? '0');
+    if (n < 0) {
+      return null; // a negative interior offset — unusual; leave raw
+    }
+    lo.ops[2] = macro(n);
+    return { n };
+  }
+  if (/^(lw|lh|lhu|lb|lbu|sw|sh|sb)$/.test(lo.mnemonic)) {
+    const mem = parseMem(lo.ops[lo.ops.length - 1] ?? '');
+    const n = hiBase + mem.off;
+    if (n < 0) {
+      return null;
+    }
+    lo.ops[lo.ops.length - 1] = `${macro(n)}(${mem.base})`;
+    return { n };
+  }
+  return null;
+}
+
 interface MipsBlock {
   startAddr: number;
   body: Instr[]; // computation instructions (excludes the branch and its delay slot)
@@ -370,8 +464,15 @@ export function lift(
   _prototypes: Prototypes = {},
   asmData?: AsmData,
 ): Fn {
-  assertInputFormat('mips', 'objdump', asm);
-  const instrs = parseDisasm(sliceSymbol(asm, name)); // ONE function only — an absent symbol declines loud
+  // Two input dialects reach this frontend: `objdump -d` text (IDO/KMC — no compiler-emitted asm),
+  // and Splat-disassembled `.s` (pmret-style N64 projects). Splat is normalised to the SAME
+  // DisasmInstr[] shape (frontend/splat.ts) so everything below is dialect-agnostic.
+  const splat = isSplatMips(asm);
+  if (!splat) {
+    assertInputFormat('mips', 'objdump', asm);
+  }
+  // ONE function only — an absent symbol declines loud (either dialect's slicer enforces this).
+  const instrs = splat ? parseSplatMips(asm, name) : parseDisasm(sliceSymbol(asm, name));
   if (instrs.length === 0) {
     throw new FrontendUnsupportedError(`cannot lift '${name}': no instructions found in the input text`);
   }
@@ -380,6 +481,12 @@ export function lift(
   // exempted from the loud-fail below; an UNrecovered `jr <non-ra>` still fails loud.
   const jts = asmData ? recoverMipsJumpTables(instrs, asmData) : new Map<number, MipsJT>();
   const recoveredJr = new Set([...jts.values()].map((j) => j.jrAddr));
+  // Bridge global-access relocations into `%hi`/`%lo` operands (objdump dialect only — Splat text
+  // already carries them). Runs AFTER jump-table recovery so its raw `.rodata` table-base relocs are
+  // read pristine; global rewrites target NAMED symbols and never touch a jump-table base.
+  if (!splat && asmData) {
+    applyMipsGlobalRelocs(instrs, asmData);
+  }
   // TRUSTWORTHINESS: fail LOUD on a control transfer this frontend cannot model — the `opaque`
   // path cannot catch these (implicit or no register destination). `jal`/`jalr` clobber `v0`
   // implicitly, so dropping a call fabricates `v0` from a stale value; a `jr` to anything but `ra`
@@ -451,10 +558,31 @@ export function lift(
 
   const fillBlock = (b: MipsBlock, bi: number) => {
     const ops = irBlocks[bi].ops;
+    // Pending `lui rX, %hi(SYM)` relocations awaiting their consuming `%lo` (a load/store base or an
+    // `addiu`). Block-local: the pair is emitted adjacently, so a `%lo` with no matching in-scope
+    // `%hi` (a cross-block or gp-relative access) declines LOUD rather than fabricating a base.
+    const hiReloc = new Map<string, { sym: string; addend: number }>();
+    // Materialise the address of a named global — the same `gaddr` op the Thumb frontend emits; the
+    // structurer lowers a load/store through it to `SYM` (scalar) or `((T *)&SYM)[i]` (aggregate).
+    const emitGaddr = (sym: string): Value => {
+      const g = mkValue(T.unk(32));
+      ops.push(mkOp('gaddr', { results: [g], attrs: { sym } }));
+      return g;
+    };
     const read = (r: string): Value => {
       if (isZero(r)) {
         return constVal(0);
       }
+      // A `%hi(SYM)` register read as DATA before its `%lo` completes the address is a split hi/lo
+      // relocation (the high half used alone) this frontend does not model — decline rather than
+      // treat the partial address as a value. The legit consumers (load/store/addiu `%lo`) validate
+      // `hiReloc` directly and never route the base through `read`, so this fires only on misuse.
+      const hr = hiReloc.get(r);
+      if (hr) {
+        throw new FrontendUnsupportedError(
+          `cannot lift '${name}': %hi(${hr.sym}) register used as data before a matching %lo — split hi/lo relocation not modelled`,
+        );
+      }
       // Reading `sp` as a DATA operand means frame-pointer arithmetic or an address-taken local
       // (`addiu a0,sp,8` = `&local`) — not modellable without a stack abstraction. Fabricating a
       // value for `sp` invents a PHANTOM leading parameter that shifts every real argument — a
@@ -477,6 +605,10 @@ export function lift(
       return readVar(r, bi);
     };
     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
+      // `%hi` NOT overwritten persists across multiple `%lo` uses (the read-modify-write idiom).
+      hiReloc.delete(r);
       if (!isZero(r)) {
         writeVar(r, bi, v);
       }
@@ -527,6 +659,22 @@ export function lift(
         // and raise/const.ts folds the const/const pair into one 32-bit const — the form that
         // recompiles to this exact `lui;ori`.
         case 'lui':
+          // `lui rD, %hi(SYM)` is the high half of a global's address — record it, pending the `%lo`
+          // that completes it (below), instead of materialising a bogus numeric const. rD's SSA value
+          // is deliberately NOT written: the high half is meaningless alone, so the `gaddr` is emitted
+          // at the consuming `%lo`. A read of rD as data before that is caught by the `read` guard;
+          // an UNconsumed `%hi` (no `%lo`) is a dead `lui` whose rD is never read — the residual case
+          // (an unconsumed `%hi` reg read via a `readVar` bypass) does not occur in compiler output.
+          if (s.startsWith('%')) {
+            const hi = parseReloc('hi', s);
+            if (!hi) {
+              throw new FrontendUnsupportedError(`cannot lift '${name}': unsupported relocation immediate '${s}'`);
+            }
+            if (!isZero(d)) {
+              hiReloc.set(d, { sym: hi.sym, addend: hi.addend });
+            }
+            break;
+          }
           write(d, constVal((parseImm(s) << 16) >> 0));
           break;
         case 'addiu':
@@ -537,6 +685,24 @@ export function lift(
           if (isStackPtr(d)) {
             break;
           }
+          // `addiu rD, rHi, %lo(SYM)` completes a global's address materialised by a `lui %hi(SYM)`:
+          // rD = &SYM (+ addend for a byte offset into the global). Emits the shared `gaddr` op.
+          if (t.startsWith('%')) {
+            const lo = parseReloc('lo', t);
+            const hr = lo ? hiReloc.get(s) : undefined;
+            if (!lo || !hr || hr.sym !== lo.sym || hr.addend !== lo.addend) {
+              throw new FrontendUnsupportedError(
+                `cannot lift '${name}': %lo relocation '${t}' with no matching in-scope %hi — split/cross-block hi/lo not modelled`,
+              );
+            }
+            // `&SYM` (addend 0), or `&SYM + N` for a byte offset into the global. The `add` tree is
+            // folded byte-correctly by memAccess when this address is a load/store base; if it
+            // instead ESCAPES as a value, `assertDerefsTyped` declines it (the byte offset would
+            // element-scale in C) — see the interior-global-pointer guard there.
+            const g = emitGaddr(lo.sym);
+            lo.addend !== 0 ? emitBin('add', d, g, constVal(lo.addend)) : write(d, g);
+            break;
+          }
           if (isZero(s)) {
             write(d, constVal(parseImm(t)));
             break;
@@ -706,6 +872,16 @@ export function lift(
     // drop its destination register — emit an honest `opaque`: dead ⇒ it vanishes; live ⇒
     // assertResolved fails LOUD (see frontend/opaque.ts for the policy).
     const emitOpaqueDest = (ins: Instr) => {
+      // A `%hi`/`%lo` operand on an instruction NOT modelled as a global consumer — an FP load/store
+      // (`lwc1`/`ldc1`), or any unmodelled op — reaches here (the modelled consumers handle their own
+      // `%hi`/`%lo` and return before the default case). Dropping it to an opaque would silently
+      // delete the global access (its base is not a bare register the opaque srcReg scan can see), so
+      // decline LOUD rather than lose it.
+      if (ins.ops.some((o) => o.startsWith('%'))) {
+        throw new FrontendUnsupportedError(
+          `cannot lift '${name}': unmodelled instruction '${ins.mnemonic}' with a %hi/%lo global operand — not modelled`,
+        );
+      }
       // storeClass: unmodelled MIPS stores — incl. the unaligned pair swl/swr and the FPU stores,
       // whose FIRST token is a register (a SOURCE, not a dest) that would otherwise fabricate an
       // opaque write to it while dropping the real memory write.
@@ -730,7 +906,30 @@ export function lift(
     };
     const emitUn = kit.un;
     const emitShImm = (opc: Opcode, d: string, x: Value, sa: string) => kit.shImm(opc, d, x, parseImm(sa));
+    // Resolve a `%lo(SYM + N)(rHi)` memory operand to a global address: validate it pairs with an
+    // in-scope `%hi`, emit the `gaddr`, and return it as the base with the addend as the access
+    // offset. A non-`%lo` operand returns null (the caller falls through to the normal off(base)).
+    const globalBase = (mem: string): { base: Value; off: number } | null => {
+      if (!mem.startsWith('%')) {
+        return null;
+      }
+      const lo = parseReloc('lo', mem);
+      const hr = lo && lo.base ? hiReloc.get(lo.base) : undefined;
+      if (!lo || !lo.base || !hr || hr.sym !== lo.sym || hr.addend !== lo.addend) {
+        throw new FrontendUnsupportedError(
+          `cannot lift '${name}': %lo access '${mem}' with no matching in-scope %hi — split/cross-block hi/lo not modelled`,
+        );
+      }
+      return { base: emitGaddr(lo.sym), off: lo.addend };
+    };
     const emitLoad = (d: string, mem: string, width: number, signed: boolean) => {
+      const g = globalBase(mem);
+      if (g) {
+        const res = mkValue(T.unk(32));
+        ops.push(mkOp('load', { operands: [g.base], results: [res], attrs: { off: g.off, width, signed } }));
+        write(d, res);
+        return;
+      }
       const { off, base } = parseMem(mem);
       // A word reload from a stack slot is transparent to dataflow — the SAME value spilled — so
       // route it through the slot SSA variable, not a `load` through `sp` (which would make `sp` a
@@ -756,6 +955,11 @@ export function lift(
       write(d, res);
     };
     const emitStore = (srcReg: string, mem: string, width: number) => {
+      const g = globalBase(mem);
+      if (g) {
+        ops.push(mkOp('store', { operands: [g.base, read(srcReg)], attrs: { off: g.off, width } }));
+        return;
+      }
       const { off, base } = parseMem(mem);
       // A word spill to a stack slot (an argument home slot `sw a0,0(sp)`, or a local): record the
       // slot's value in SSA, do NOT emit a `store` through `sp`. A never-reloaded spill (the ABI

package/src/frontend/splat.ts

@@ -0,0 +1,305 @@
+// asmlift — the Splat-dialect MIPS reader. Splat (the N64 disassembler that pmret/decomp.me-style
+// projects run) emits a GNU-as flavour that neither `objdump -d` nor a compiler produce, so the
+// shared objdump scaffolding (frontend/disasm.ts) reads nothing from it. This module normalises
+// that dialect into the SAME `DisasmInstr[]` the objdump parser yields, so the whole MIPS frontend
+// (delay slots, blocks, SSA, recovery) runs downstream unchanged — mirroring how the Thumb frontend
+// grew a second dialect for pret/luvdis splits.
+//
+// What the dialect adds over objdump:
+//   • `glabel NAME` / `endlabel NAME` function markers (objdump uses `ADDR <sym>:` headers);
+//   • a `/* ROM VRAM BYTES */` comment prefix on every instruction (the addr lives INSIDE it, so
+//     disasm.ts's `ADDR:` line anchor never matches) — the VRAM word is the instruction address;
+//   • `$`-prefixed registers (`$v0`, `$sp`) — stripped to the bare names the frontend's guards expect;
+//   • `.L<vram>_<rom>` local labels as branch/jump TARGETS (objdump prints a resolved address) —
+//     resolved here to the target instruction's address;
+//   • constant immediate EXPRESSIONS (`(0x660104 >> 16)`, `(x & 0xFFFF)`) — the assembler's hi/lo
+//     split of a 32-bit literal, evaluated here to the plain number the decode switch parses.
+//
+// `%hi`/`%lo` operands (a global's address) are preserved verbatim so the MIPS frontend can fold
+// them into a `gaddr` (frontend/mips.ts). The other GOT/PIC relocations (`%gp_rel`, `%got`, …) are
+// declined LOUD — small-data / position-independent access is not modelled. Preserving rather than
+// blindly evaluating is what keeps `parseImm('%hi(SYM)')` from silently becoming a NaN immediate.
+import type { DisasmInstr } from './disasm';
+import { FrontendUnsupportedError } from './errors';
+
+// One instruction line: `/* ROM VRAM BYTES */  MNEMONIC  OPS`. Group 1 is the VRAM address word.
+const INSN_LINE = /^\/\*\s*[0-9A-Fa-f]+\s+([0-9A-Fa-f]+)\s+[0-9A-Fa-f]+\s*\*\/\s*(\S+)\s*(.*)$/;
+// A Splat instruction-comment prefix anywhere in the text — the load-bearing format signal.
+const INSN_SIGNAL = /\/\*\s*[0-9A-Fa-f]+\s+[0-9A-Fa-f]+\s+[0-9A-Fa-f]+\s*\*\//;
+// A local-label DEFINITION on its own line (`.L800011C0_1DC0:`); the colon is required.
+const LABEL_DEF = /^(\.[\w.$]+):$/;
+// A GOT/PIC relocation operand this reader does not support (small-data / position-independent
+// access) — declined loud. `%hi`/`%lo` are NOT here: they name a global's address and are preserved
+// verbatim for the MIPS frontend to fold into a `gaddr` (see normalizeOperand / frontend/mips.ts).
+const RELOC_OP = /%(gp_rel|gprel|got|call16|call_hi|call_lo|higher|highest|neg|tprel|dtprel)\b/i;
+// Data directives whose bytes could encode an effect: skipping one inside a function slice would
+// silently delete it, so they decline (mirrors the Thumb frontend's in-code-data guard).
+const DATA_DIRECTIVE =
+  /^\.(byte|half|hword|short|2byte|word|4byte|long|dword|8byte|quad|float|double|ascii|asciz|string|incbin|space|skip|fill|zero)\b/i;
+
+/** Does this text look like Splat-dialect MIPS? Both signals (`glabel` markers and the
+ *  three-word instruction-comment prefix) are unique to Splat — objdump and compiler `.s` carry
+ *  neither — so a positive match is unambiguous. */
+export function isSplatMips(asm: string): boolean {
+  return /^\s*glabel\s+\S+/m.test(asm) || INSN_SIGNAL.test(asm);
+}
+
+/** Parse Splat-dialect text into one function's `DisasmInstr[]`. When `glabel` markers are present
+ *  the text is sliced to exactly `name` (an absent symbol declines LOUD — emitting some other
+ *  function's body under the requested name is the silent miscompile the cardinal rule forbids);
+ *  a marker-less fragment is parsed whole. Branch targets are resolved against the local-label
+ *  map, so an unresolved `.L` target declines here rather than crashing deep in the frontend. */
+export function parseSplatMips(asm: string, name: string): DisasmInstr[] {
+  const lines = asm.split('\n');
+
+  // Slice to the requested function: `glabel NAME` … its `endlabel`/the next `glabel`/EOF.
+  const glabels: { line: number; sym: string }[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^\s*glabel\s+(\S+)/);
+    if (m) {
+      glabels.push({ line: i, sym: m[1] });
+    }
+  }
+  let slice = lines;
+  if (glabels.length > 0) {
+    const at = glabels.findIndex((g) => g.sym === name);
+    if (at === -1) {
+      throw new FrontendUnsupportedError(
+        `symbol '${name}' not found in the Splat disassembly (functions present: ${glabels.map((g) => g.sym).join(', ')})`,
+      );
+    }
+    let end = lines.length;
+    for (let i = glabels[at].line + 1; i < lines.length; i++) {
+      if (/^\s*(endlabel|glabel)\b/.test(lines[i])) {
+        end = i;
+        break;
+      }
+    }
+    slice = lines.slice(glabels[at].line, end);
+  }
+
+  // Flatten to instructions, assigning any pending label(s) to the NEXT instruction's address.
+  const instrs: DisasmInstr[] = [];
+  const labelAddr = new Map<string, number>();
+  let pending: string[] = [];
+  for (const raw of slice) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) {
+      continue;
+    }
+    if (/^(glabel|endlabel|dlabel|jlabel)\b/.test(line) || /^nonmatching\b/.test(line)) {
+      continue; // function/data markers and the objdiff scratch header
+    }
+    const labelDef = line.match(LABEL_DEF);
+    if (labelDef) {
+      pending.push(labelDef[1]);
+      continue;
+    }
+    if (line.startsWith('.')) {
+      // A data directive in the code stream could hide an instruction/effect — decline; other
+      // bookkeeping directives (`.set`, `.align`, `.section`…) are transparent and skipped.
+      if (DATA_DIRECTIVE.test(line)) {
+        throw new FrontendUnsupportedError(
+          `cannot lift '${name}': data directive '${line}' in the code stream — skipping it would silently delete its effect`,
+        );
+      }
+      continue;
+    }
+    const m = line.match(INSN_LINE);
+    if (!m) {
+      throw new FrontendUnsupportedError(
+        `cannot lift '${name}': unrecognised line in the Splat disassembly: '${line}'`,
+      );
+    }
+    const addr = parseInt(m[1], 16);
+    const mnemonic = m[2];
+    // A data directive carrying an instruction-comment prefix (`/* … */ .word …`) would otherwise
+    // be decoded as a mnemonic and silently become an opaque — decline it like the bare form.
+    if (DATA_DIRECTIVE.test(mnemonic)) {
+      throw new FrontendUnsupportedError(
+        `cannot lift '${name}': data directive '${mnemonic}' in the code stream — skipping it would silently delete its effect`,
+      );
+    }
+    const ops = m[3].trim() ? splitOperands(m[3].trim()).map((o) => normalizeOperand(name, o)) : [];
+    // addi/addiu SIGN-EXTEND their 16-bit immediate; Splat may spell the low half of a materialised
+    // constant as an unsigned mask (`(0x8000ABCD & 0xFFFF)` = 0xABCD), so re-sign it here to match
+    // the hardware — and the objdump path, which prints the already-signed value. Zero-extending ops
+    // (ori/andi/xori) and lui keep the unsigned value, so they are deliberately excluded.
+    if ((mnemonic === 'addiu' || mnemonic === 'addi') && ops.length === 3 && /^-?(0x[0-9a-fA-F]+|\d+)$/.test(ops[2])) {
+      ops[2] = String(signExtend16(ops[2]));
+    }
+    for (const l of pending) {
+      labelAddr.set(l, addr);
+    }
+    pending = [];
+    instrs.push({ addr, mnemonic, ops });
+  }
+
+  // Resolve every branch/jump's target label to an address. A target that is not a local label of
+  // this function — an unresolvable `.L`, or a bare symbol (`j func` tail call) — declines LOUD
+  // rather than leaving `target` undefined for the frontend to crash on (`succ(undefined)`).
+  for (const ins of instrs) {
+    if (!isBranchMnemonic(ins.mnemonic)) {
+      continue;
+    }
+    const label = ins.ops[ins.ops.length - 1];
+    const t = label !== undefined ? labelAddr.get(label) : undefined;
+    if (t === undefined) {
+      throw new FrontendUnsupportedError(
+        `cannot lift '${name}': branch/jump target '${label ?? ''}' is not a local label in this function ` +
+          `(tail call / cross-function branch not modelled)`,
+      );
+    }
+    ins.target = t;
+  }
+  return instrs;
+}
+
+// A control transfer whose last operand is a code-label target: `b`, `j`, and the conditional
+// branches (`beq`/`bnez`/`bc1f`…). NOT `jal`/`jalr` (calls) or `jr` (register) — the MIPS frontend
+// owns those declines; `break` is a trap, not a branch.
+const isBranchMnemonic = (mn: string): boolean => mn === 'j' || (mn[0] === 'b' && mn !== 'break');
+
+// Re-sign a raw 16-bit immediate: a value with bit 15 set becomes negative (two's complement),
+// matching how addi/addiu sign-extend the field. A value already ≤ 0x7FFF is unchanged.
+function signExtend16(s: string): number {
+  const v = parseInt(s, /^-?0x/i.test(s) ? 16 : 10) & 0xffff;
+  return v & 0x8000 ? v - 0x10000 : v;
+}
+
+// Split an operand list on top-level commas (commas inside `(...)` — a memory operand or a
+// constant expression — do not separate operands).
+function splitOperands(s: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let cur = '';
+  for (const ch of s) {
+    if (ch === '(') {
+      depth++;
+    } else if (ch === ')') {
+      depth--;
+    }
+    if (ch === ',' && depth === 0) {
+      out.push(cur.trim());
+      cur = '';
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur.trim()) {
+    out.push(cur.trim());
+  }
+  return out;
+}
+
+// Rewrite one Splat operand into the canonical objdump spelling the frontend consumes: strip the
+// `$` register sigil, fold a memory operand's displacement expression, evaluate a bare constant
+// expression, preserve a `%hi`/`%lo` global reference, and decline an unsupported PIC relocation.
+function normalizeOperand(name: string, op: string): string {
+  // `%hi(SYM)` / `%lo(SYM + N)` / `%lo(SYM)(base)` — a global's address. Preserved verbatim (with a
+  // de-sigiled base) for the MIPS frontend to fold into a `gaddr`; NOT declined like the PIC relocs.
+  const hilo = op.match(/^(%(?:hi|lo)\([^)]*\))(?:\((\$?[A-Za-z]\w*)\))?$/);
+  if (hilo) {
+    return hilo[2] ? `${hilo[1]}(${hilo[2].replace(/^\$/, '')})` : hilo[1];
+  }
+  if (RELOC_OP.test(op)) {
+    throw new FrontendUnsupportedError(
+      `cannot lift '${name}': relocation operand '${op}' (small-data / PIC data access) — not modelled`,
+    );
+  }
+  // Memory operand `DISP(base)` — base is a register (letter-first), DISP a constant/expression.
+  const mem = op.match(/^(.*)\((\$?[A-Za-z]\w*)\)$/);
+  if (mem) {
+    const disp = mem[1].trim();
+    const off = disp === '' ? '0' : String(evalConst(name, disp));
+    return `${off}(${mem[2].replace(/^\$/, '')})`;
+  }
+  // A bare constant expression (`(0x660104 >> 16)`) — the assembler's hi/lo literal split.
+  if (op.startsWith('(')) {
+    return String(evalConst(name, op));
+  }
+  return op.replace(/^\$/, '');
+}
+
+// Evaluate a constant integer expression (the assembler's hi/lo split: hex/dec literals with
+// `+ - * << >> & | ^ ~` and parentheses). Precedence-climbing; C-like precedence. A shift `>>` is
+// LOGICAL — Splat's operands are unsigned 32-bit constants. Anything unparsable declines LOUD
+// rather than silently yielding NaN.
+function evalConst(name: string, expr: string): number {
+  const toks = expr.match(/0x[0-9a-fA-F]+|\d+|<<|>>|[-+*&|^()~]/g);
+  if (!toks) {
+    throw new FrontendUnsupportedError(`cannot lift '${name}': unparsable constant expression '${expr}'`);
+  }
+  const prec: Record<string, number> = { '|': 1, '^': 2, '&': 3, '<<': 4, '>>': 4, '+': 5, '-': 5, '*': 6 };
+  let p = 0;
+  const fail = () => {
+    throw new FrontendUnsupportedError(`cannot lift '${name}': unparsable constant expression '${expr}'`);
+  };
+  const primary = (): number => {
+    const t = toks[p++];
+    if (t === undefined) {
+      return fail();
+    }
+    if (t === '(') {
+      const v = expr2(0);
+      if (toks[p++] !== ')') {
+        return fail();
+      }
+      return v;
+    }
+    if (t === '-') {
+      return -unary();
+    }
+    if (t === '~') {
+      return ~unary();
+    }
+    if (/^(0x[0-9a-fA-F]+|\d+)$/.test(t)) {
+      return t.toLowerCase().startsWith('0x') ? parseInt(t, 16) : parseInt(t, 10);
+    }
+    return fail();
+  };
+  const unary = (): number => primary();
+  const expr2 = (minPrec: number): number => {
+    let left = unary();
+    for (;;) {
+      const op = toks[p];
+      if (op === undefined || prec[op] === undefined || prec[op] < minPrec) {
+        break;
+      }
+      p++;
+      const right = expr2(prec[op] + 1);
+      switch (op) {
+        case '+':
+          left = (left + right) | 0;
+          break;
+        case '-':
+          left = (left - right) | 0;
+          break;
+        case '*':
+          left = Math.imul(left, right);
+          break;
+        case '<<':
+          left = (left << right) >>> 0;
+          break;
+        case '>>':
+          left = left >>> right;
+          break;
+        case '&':
+          left = left & right;
+          break;
+        case '|':
+          left = left | right;
+          break;
+        case '^':
+          left = left ^ right;
+          break;
+      }
+    }
+    return left;
+  };
+  const v = expr2(0);
+  if (p !== toks.length) {
+    return fail();
+  }
+  return v;
+}