@asmlift/core 0.1.0 → 0.2.0

package/README.md

@@ -28,15 +28,10 @@ const { source, diagnostics } = decompile('my_func', asm, MIPS_IDO);
 console.log(source); // s32 my_func(s32 a0) { ... }
 ```
 
-Input is **text**: GBA `.s` assembly for the ARM target — both agbcc compiler output and
-pret-style project splits (`asm/nonmatchings/`: `thumb_func_start` macros, `_08xxxxxx` labels,
-`.4byte` literal pools) — and `objdump -d --no-show-raw-insn`
-output for MIPS/PPC — the format follows what each target's toolchain actually produces. The
-frontends classify the input first (`frontend/format.ts`): text that positively matches the
-_other_ format declines at the boundary naming both, instead of failing confusingly mid-decode.
-Multi-function input is sliced to the named symbol; an absent symbol declines with the list of
-symbols present. (`@asmlift/cli` additionally accepts ELF **object files** and runs the right
-objdump for you.)
+Input is **text**, following what each target's toolchain produces:
+
+- The ARM target reads GBA `.s`, produced by agbcc and pret-style project splits.
+- The MIPS/PPC targets read `objdump -d --no-show-raw-insn` output and Splat-disassembled `.s`.
 
 ### `decompile(name, asm, target, opts?)`
 
@@ -84,20 +79,20 @@ injected via hooks, never copied. `verify()` runs after every IR-mutating pass;
 
 ### Modules
 
-| Module                                          | What it is                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ir/{types,core,opcodes,print,parse,verify}.ts` | MLIR-lite substrate: CFG of blocks + typed **block-arguments**, the typed opcode registry (`Opcode`, the one `effects` table DCE and hoist guards derive from), printer + parser (round-trip for L1/scalar types — see the domain note in parse.ts), verifier (arity/attrs/terminators/SSA dominance, located errors)                                                                                                                 |
-| `frontend/{thumb,mips,ppc}.ts`                  | ISA frontends: decode → CFG → L1 with **Braun-2013 block-arg SSA** (`ssa.ts`), incl. loops, calls (signature-driven arity), memory, jump tables. Shared scaffolding: `disasm.ts` (objdump parsing), `emit.ts` (per-block emitter kit + `switch_br`), `opaque.ts` (the unmodelled-op → loud-`opaque` contract), `errors.ts` (`FrontendUnsupportedError`; PPC's subclass), `registry.ts`, `asmdata.ts` (Regime-B jump-table side-table) |
-| `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)                                                                                                |
-| `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                                                                                                                                                                                                       |
-| `rank.ts`                                       | Pure candidate enumeration + `rankBy` (an injected score function ranks). @asmlift/cli's differ ranks through `rankBy`; the playground's wasm scorer consumes the same enumeration with its own async loop                                                                                                                                                                                                                            |
-| `target.ts`                                     | `TargetDescription` (ABI + capabilities + compilerBehaviors as data — no `arch ==` in shared code); toolchain paths live in `@asmlift/toolchains`                                                                                                                                                                                                                                                                                     |
-| `contracts.ts`, `proto.ts`, `mangle.ts`         | Boundary contracts; prototype tables; the CodeWarrior mangler                                                                                                                                                                                                                                                                                                                                                                         |
+| Module                                          | What it is                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ir/{types,core,opcodes,print,parse,verify}.ts` | MLIR-lite substrate: CFG of blocks + typed **block-arguments**, the typed opcode registry (`Opcode`, the one `effects` table DCE and hoist guards derive from), printer + parser (round-trip for L1/scalar types — see the domain note in parse.ts), verifier (arity/attrs/terminators/SSA dominance, located errors)                                                                                                                                                                                                                     |
+| `frontend/{thumb,mips,ppc}.ts`                  | ISA frontends: decode → CFG → L1 with **Braun-2013 block-arg SSA** (`ssa.ts`), incl. loops, calls (signature-driven arity), memory, jump tables. Shared scaffolding: `disasm.ts` (objdump parsing), `splat.ts` (Splat-dialect MIPS → objdump-shaped instrs), `format.ts` (input-format classification), `emit.ts` (per-block emitter kit + `switch_br`), `opaque.ts` (the unmodelled-op → loud-`opaque` contract), `errors.ts` (`FrontendUnsupportedError`; PPC's subclass), `registry.ts`, `asmdata.ts` (Regime-B jump-table side-table) |
+| `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)                                                                                                                                                                                                    |
+| `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                                                                                                                                                                                                                                                                                                           |
+| `rank.ts`                                       | Pure candidate enumeration + `rankBy` (an injected score function ranks). @asmlift/cli's differ ranks through `rankBy`; the playground's wasm scorer consumes the same enumeration with its own async loop                                                                                                                                                                                                                                                                                                                                |
+| `target.ts`                                     | `TargetDescription` (ABI + capabilities + compilerBehaviors as data — no `arch ==` in shared code); toolchain paths live in `@asmlift/toolchains`                                                                                                                                                                                                                                                                                                                                                                                         |
+| `contracts.ts`, `proto.ts`, `mangle.ts`         | Boundary contracts; prototype tables; the CodeWarrior mangler                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 
 Scoring and ranking live across the package seam in [`@asmlift/cli`](../cli/README.md):
 `score.ts` + `objdiff.ts` (toolchain compiles → in-process pinned `objdiff-wasm`, fail-closed)

package/package.json

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

package/src/contracts.ts

@@ -97,6 +97,17 @@ export function assertDerefsTyped(sfn: SFn): void {
         }
       }
     }
+    // A bare global ADDRESS `&SYM` under `+`/`-` is an ESCAPING interior pointer: C scales the byte
+    // offset by sizeof(SYM), which is unknown for a header-typed global, so `&SYM + N` is byte-
+    // inexact. A load/store base folds the offset byte-correctly (globalOf turns `&SYM + N` into an
+    // `index`/`field` node whose base is a bare `addr`, never an `addr` under a `bin`), so an `addr`
+    // reaching a `+`/`-` operand here escaped to a value context — flag it rather than emit wrong bytes.
+    if (e.k === 'bin' && (e.op === '+' || e.op === '-')) {
+      const addrSide = e.l.k === 'addr' ? e.l : e.r.k === 'addr' ? e.r : undefined;
+      if (addrSide) {
+        bad.push(`interior pointer arithmetic on the global address '&${addrSide.name}'`);
+      }
+    }
     // `!p` is legal C (pointer truthiness); `-p`/`~p` are not.
     if (e.k === 'un' && e.op !== '!' && ctype(e.e)?.kind === 'ptr') {
       bad.push(`pointer operand under unary '${e.op}'`);

package/src/detect.ts

@@ -1,11 +1,14 @@
 // asmlift — small pure helpers over raw asm TEXT (no parsing): shared by the CLI and the
 // web playground, which both need a function name before they can call `decompile`.
 
-/** Best-effort function-name detection: the objdump symbol header, else the `.globl` name,
- *  else the first label. Returns undefined when the asm names nothing (caller asks the user). */
+/** Best-effort function-name detection: the objdump symbol header, else Splat's `glabel` marker,
+ *  else the `.globl` name, else the first label. Returns undefined when the asm names nothing
+ *  (caller asks the user). Returns the FIRST function in multi-function input, matching how the
+ *  objdump header case auto-selects. */
 export function detectName(asm: string): string | undefined {
   return (
     asm.match(/^[0-9a-f]+ <([\w.$]+)>:/m)?.[1] ??
+    asm.match(/^\s*glabel\s+([\w.$]+)/m)?.[1] ??
     asm.match(/^\s*\.globl\s+([\w.$]+)/m)?.[1] ??
     asm.match(/^([A-Za-z_]\w*):/m)?.[1]
   );

package/src/frontend/format.ts

@@ -9,12 +9,14 @@
 // hand-written instructions) stays "unknown" and flows through to the frontend — the
 // decode-level loud-fail nets still own that case.
 import { FrontendUnsupportedError } from './errors';
+import { isSplatMips } from './splat';
 
-export type AsmTextFormat = 'objdump' | 'gnu-as';
+export type AsmTextFormat = 'objdump' | 'gnu-as' | 'splat';
 
 const FORMAT_LABEL: Record<AsmTextFormat, string> = {
   objdump: 'objdump disassembly (`objdump -d --no-show-raw-insn` output)',
   'gnu-as': 'GNU-as assembly text (compiler-emitted `.s`)',
+  splat: 'Splat-disassembled MIPS (`glabel` + `/* rom vram bytes */` `.s`)',
 };
 
 // objdump output: `ADDR <sym>:` section headers, address-prefixed instruction lines, or the
@@ -23,8 +25,13 @@ const OBJDUMP_SIGNAL = /^[0-9a-f]{2,} <[^>]+>:|^\s+[0-9a-f]+:\t|file format /im;
 const GNU_AS_SIGNAL =
   /^\s*\.(text|code|align|globl|global|thumb_func|section|syntax|arch|cpu|set|ent|type|size|file)\b/im;
 
-/** Classify assembly TEXT by positive signals; "unknown" when neither (or both) match. */
+/** Classify assembly TEXT by positive signals; "unknown" when neither (or both) match. Splat is
+ *  checked FIRST: its files also carry GNU-as directives (`.section`/`.align`), so a bare gnu-as
+ *  match would mislabel them — the Splat-specific `glabel`/instruction-comment signal is decisive. */
 export function classifyAsmText(text: string): AsmTextFormat | 'unknown' {
+  if (isSplatMips(text)) {
+    return 'splat';
+  }
   const objdump = OBJDUMP_SIGNAL.test(text);
   const gnuAs = GNU_AS_SIGNAL.test(text);
   if (objdump === gnuAs) {
@@ -42,6 +49,7 @@ export function assertInputFormat(frontendId: string, expected: AsmTextFormat, a
   }
   throw new FrontendUnsupportedError(
     `cannot lift: input looks like ${FORMAT_LABEL[got]}, but the '${frontendId}' frontend reads ` +
-      `${FORMAT_LABEL[expected]} — MIPS/PPC targets take objdump output; the ARM/agbcc target takes agbcc .s text`,
+      `${FORMAT_LABEL[expected]} — the ARM/agbcc target takes agbcc .s text; MIPS/PPC take objdump output ` +
+      `(the MIPS frontend also reads Splat .s)`,
   );
 }

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;
+}

package/src/raise/magicdiv.ts

@@ -1,4 +1,4 @@
-// asmlift — magic-number constant-division recovery (L1 recognition; gcc-mips + mwcc-ppc).
+// asmlift — magic-number constant-division recovery (L1 recognition; gcc2.7.2kmc + mwcc_242_81).
 //
 // A compiler replaces `x / C` for a non-power-of-2 constant `C` with a HIGH-WORD MULTIPLY by a
 // precomputed "magic" reciprocal `M`, a shift `s`, and a sign correction. The frontend lifts the