@asmlift/core 0.1.0 → 0.3.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.3.0",
   "license": "MIT",
   "type": "module",
   "description": "Match decompile an assembly function to C or Pascal",

package/src/backend/cfamily.ts

@@ -47,14 +47,38 @@ export function cType(t: IrType): string {
 }
 
 /** Declare a name of a given type, C declarator rules: an array puts its length AFTER the name
- *  (`u8 _pad[4]`), everything else is the prefix `cType name`. */
+ *  (`u8 _pad[4]`), a pointer binds its `*` to the declarator (`void *p`), everything else is
+ *  the prefix `cType name`. */
 function cDeclare(t: IrType, name: string): string {
   if (t.kind === 'array') {
     return `${cType(t.elem)} ${name}[${t.count}]`;
   }
+  if (t.kind === 'ptr') {
+    return `${cType(t.to)} *${name}`;
+  }
   return `${cType(t)} ${name}`;
 }
 
+/** One field of a rendered struct declaration — the minimal input shape shared by the two
+ *  producers of `struct N { ... };` text: the backend's recovered structs (SFn.structs, whose
+ *  StructType fields already carry pads as real `u8[N]` members) and the cli's map-layout
+ *  declaration synthesis (declare.ts, which seats fields at exact offsets by interleaving pad
+ *  fields itself). `volatile` is the MMIO member idiom (`volatile u16 gain;`) — only the
+ *  map-derived synthesis sets it today; recovered structs never do. */
+export interface StructFieldDecl {
+  name: string;
+  type: IrType;
+  volatile?: boolean;
+}
+
+/** THE struct-declaration spelling — every `struct N { ... };` asmlift prints comes from here,
+ *  so the backend's recovered-struct decls and the scoring layer's synthesized decls cannot
+ *  drift apart. One line, fields in caller order (the type is self-describing: padding is the
+ *  caller's discipline, already present as real fields). */
+export function renderStructDecl(name: string, fields: StructFieldDecl[]): string {
+  return `struct ${name} { ${fields.map((f) => `${f.volatile ? 'volatile ' : ''}${cDeclare(f.type, f.name)};`).join(' ')} };`;
+}
+
 // A LEAF hook lets a C-family backend override how a `var` or `index` node spells WITHOUT
 // re-implementing precedence, parenthesization, or statement structure. It returns the
 // replacement text, or null to fall through to the default C spelling — how the C++ backend
@@ -121,6 +145,10 @@ function printExpr(e: Expr, parentPrec: number, vt: VarTypes, leaf?: LeafHook):
         const baseTxt = hooked ?? `${rec(ix.base, 1)}[${rec(ix.idx, 99)}]`;
         return `${baseTxt}.${e.name}`;
       }
+      // explicit dot: a struct-VALUE global's field (`gSym.field`, symbol-map layout spelling)
+      if (e.dot) {
+        return `${rec(e.base, 1)}.${e.name}`;
+      }
       return `${rec(e.base, 1)}->${e.name}`;
     }
     case 'un': {
@@ -333,9 +361,7 @@ function cFamilyBody(fn0: SFn, leaf?: LeafHook): string[] {
  *  raise/structs.ts (unaccessed leading/interior gaps) interleave them where natural C alignment
  *  does not already cover the offset. This just declares each field in order. */
 function structDecls(fn: SFn): string[] {
-  return (fn.structs ?? []).map(
-    (s) => `struct ${s.name} { ${s.fields.map((f) => cDeclare(f.type, f.name) + ';').join(' ')} };`,
-  );
+  return (fn.structs ?? []).map((s) => renderStructDecl(s.name, s.fields));
 }
 
 /** Assemble a full C-family function from a caller-supplied signature line and the shared body. */

package/src/contracts.ts

@@ -73,6 +73,8 @@ export function assertDerefsTyped(sfn: SFn): void {
   const bad: string[] = [];
   // Ops C rejects outright on a pointer operand (the additive ops and &&/|| are legal C).
   const NO_PTR_OPS = new Set(['&', '|', '^', '<<', '>>', '*', '/', '%']);
+  // The comparison operators — where a bare `&SYM` operand is SIGN-ambiguous, not ill-formed.
+  const CMP_OPS = new Set(['<', '<=', '>', '>=', '==', '!=']);
   // 1/2/4 only: the decomp typedef vocabulary (C_TYPEDEFS) has no 64-bit scalar, so a width-8
   // access would print as the nonexistent `(s64 *)` — exactly the three-stages-later failure
   // this rule pre-empts. (If f64 loads ever land they are floats, not a scalar width here.)
@@ -97,6 +99,34 @@ 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. Nothing emits this shape anymore: a load/store base folds byte-correctly (globalOf
+    // turns `&SYM + N` into an `index`/`field` node whose base is a bare `addr`), and the additive
+    // lowering intifies every other `addr` operand to `(u32)&SYM` (structure.ts intifyAddr — the
+    // cast types int, so it never lands here). A bare `addr` reaching a `+`/`-` operand is therefore
+    // a lowering REGRESSION — 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}'`);
+      }
+    }
+    // A bare global address `&SYM` as a COMPARISON operand is the same unspelled escape under a
+    // different operator — and worse than ill-formed: the compare's SIGNEDNESS is spelled by the
+    // operand TYPES (the structurer maps icmp_ult and icmp_slt to the same '<'), and `&SYM`'s C
+    // type is the project's own declaration, unknowable here — so the emitted compare can flip
+    // signedness against the asm's, silently. The cmp lowering intifies it signedness-aware
+    // (`(u32)`/`(s32)&SYM` — structure.ts intifyAddrCmp; the cast types int, so it never lands
+    // here). A bare `addr` reaching a comparison operand is therefore a lowering REGRESSION —
+    // flag it rather than emit sign-ambiguous C.
+    if (e.k === 'bin' && CMP_OPS.has(e.op)) {
+      for (const side of [e.l, e.r]) {
+        if (side.k === 'addr') {
+          bad.push(`bare global address '&${side.name}' as a comparison operand`);
+        }
+      }
+    }
     // `!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/declare.ts

@@ -0,0 +1,225 @@
+// asmlift — declaration SYNTHESIS for self-declaring candidates
+// (research/self-declaring-candidates-2026-07-26.md).
+//
+// A scored candidate that names map-derived symbols must compile WITHOUT the project's headers:
+// this module renders the declaration block for exactly the symbols the candidate's tree
+// references in a value context (Candidate.symbolRefs — derived from the candidate's final
+// tree at enumeration, l3/symbol-refs.ts). It is a SCORING-LAYER
+// concern only — backends never print declarations (a project user compiles asmlift output
+// against their own headers, where a second declaration would collide).
+//
+// LIVES IN CORE (browser-pure, no Node imports) because BOTH scorers prepend it: the cli's
+// Node/objdiff path (which re-exports this module unchanged) and the webapp's wasm scorer
+// (score-wasm.ts) — one renderer, so the two scoring worlds cannot drift.
+//
+// Fidelity rules (each empirically verified against agbcc — see the research doc):
+//   • struct decls are rebuilt from the map layout with explicit `u8 pad[]` gap fields — the
+//     padded synthesis is byte-identical to the real header declaration;
+//   • member/scalar SIGNEDNESS drives u8/s8/u16/s16/u32/s32 — an s8 field read is
+//     ldrb+lsl+asr where u8 is ldrb alone, so a guessed signedness is a wrong-bytes decl;
+//   • `volatile` is load-bearing (a non-volatile MMIO decl lets the compiler fold/reorder
+//     accesses), `const` is the ROM-table spelling;
+//   • code symbols get `void Name(void);` ONLY when value-referenced — call targets are never
+//     in `symbolRefs` (core excludes them: prototyping a called symbol is C89 poison);
+//   • nothing guesses, with TWO documented exceptions: a SHAPED symbol without the facts to
+//     declare faithfully is SKIPPED — the candidate then fails to compile LOUDLY and is
+//     dropped by rankBy. Exception one is the 4-byte signless-non-pointer cell (see
+//     ENUM_IS_SIGNED): spelled s32 on the C89 enum=int rule. For a true enum that is the header
+//     truth; the residual mis-spell class (a 4-byte nested-struct member word-read via a dot
+//     field) can only LOSE score — the target bytes derive from the truth decls, so a
+//     divergent compile can never false-match. Exception two is the NAME-ONLY data symbol
+//     (`extern u32 name;` — see the default case): required to reproduce symtab-only map
+//     rows outside project headers, justified by the same only-loses-score argument.
+import { type StructFieldDecl, renderStructDecl } from './backend/cfamily';
+import { T } from './ir/types';
+import type { SymbolRef } from './l3/symbol-refs';
+import {
+  ENUM_IS_SIGNED,
+  type SymbolInfo,
+  type SymbolStructField,
+  declaredFields,
+  pointeeFields,
+  symbolFieldType,
+} from './symbols';
+
+/** The u8/s8/u16/s16/u32/s32 spelling for a 1/2/4-byte cell, or null (no faithful narrow type). */
+function intType(size: number, signed: boolean): string | null {
+  const base = size === 1 ? '8' : size === 2 ? '16' : size === 4 ? '32' : null;
+  return base === null ? null : `${signed ? 's' : 'u'}${base}`;
+}
+
+/** `volatile const ` qualifier prefix (either may be absent). */
+function quals(info: SymbolInfo): string {
+  return `${info.volatile ? 'volatile ' : ''}${info.const ? 'const ' : ''}`;
+}
+
+/** One struct field's type, seated at its exact offset by the caller's pad discipline — THE shared
+ *  map-field typing (symbols.ts `symbolFieldType`, which core's own legalization env also reads,
+ *  so the declaration and the type the emitter reasoned against cannot drift). Member volatility
+ *  is kept on the field decl here (`vu16 field;` — dropping it lets the compiler fold repeated
+ *  reads), being a decl-only fact. */
+const fieldType = symbolFieldType;
+
+/** The padded `struct Tag { ... };` declaration for a layout: fields seated at exact offsets,
+ *  gaps as explicit u8 pad arrays, rendered by THE shared struct renderer (core
+ *  backend/cfamily.ts renderStructDecl — the same spelling the backend's recovered-struct
+ *  decls use, so the two cannot drift). Returns null when the layout cannot be reproduced
+ *  faithfully (an unsized member). */
+function structDecl(tag: string, layout: SymbolStructField[] | undefined, size: number | undefined): string | null {
+  // THE shared spellability predicate (symbols.ts): which members exist, and whether the layout
+  // can be reproduced at all. Core's access rules gate on the SAME call, so a member this
+  // declaration omits — an unsizable layout declined whole, a union alias dropped for its first
+  // view — is a member no emitted expression can name.
+  const members = declaredFields(layout);
+  if (members === null) {
+    return null;
+  }
+  const fields: StructFieldDecl[] = [];
+  let cursor = 0;
+  let pad = 0;
+  for (const m of members) {
+    if (m.offset > cursor) {
+      // asmlift_-prefixed so a REAL member named pad_N (a decomp-header idiom) never collides
+      fields.push({ name: `asmlift_pad_${pad++}`, type: T.array(T.u(8), m.offset - cursor) });
+    }
+    fields.push({
+      name: m.name,
+      type: fieldType(m),
+      ...(m.volatile ? { volatile: true } : {}),
+    });
+    cursor = m.offset + m.size;
+  }
+  if (size !== undefined && size > cursor) {
+    // tail padding to the declared size
+    fields.push({ name: `asmlift_pad_${pad}`, type: T.array(T.u(8), size - cursor) });
+  }
+  return renderStructDecl(tag, fields);
+}
+
+/**
+ * Render the declaration block for a candidate's recorded symbol references. Deterministic
+ * (refs arrive name-sorted from core; struct decls dedupe by tag). The block is prepended by
+ * the candidate compiler AFTER the typedef prelude — it spells types as u8/s16/… — and only in
+ * the self-declared world (the probe in compile-command.ts arbitrates; in the headers world
+ * both prelude and declarations are dropped, headers own everything).
+ */
+export function renderDeclarations(refs: SymbolRef[]): string {
+  const lines: string[] = [];
+  const declaredTags = new Set<string>();
+  for (const { name, info, access } of refs) {
+    // An address-cast macro declares itself: the header's own body, verbatim. It must NOT become
+    // an `extern` — that is the whole point of the fact (an extern emits a relocated pool word
+    // where the macro emits the numeric one the target shows).
+    if (info.macroBody !== undefined) {
+      lines.push(`#define ${name} ${info.macroBody}`);
+      continue;
+    }
+    if (info.kind === 'code') {
+      // value-referenced code symbol ((u32)Func): any prototype makes the name visible, and
+      // the address is arity-independent. Call targets never reach this module (core excludes
+      // them from symbolRefs — see collectSymbolRefs).
+      lines.push(`void ${name}(void);`);
+      continue;
+    }
+    switch (info.shape) {
+      case 'scalar': {
+        // Signedness default: absent + 4 bytes is the enum idiom (int ⇒ s32); absent + narrow
+        // has no honest spelling — skip (loud, see module note).
+        const t =
+          info.size !== undefined
+            ? intType(info.size, info.signed ?? (info.size === 4 ? ENUM_IS_SIGNED : false))
+            : null;
+        if (t !== null && (info.signed !== undefined || info.size === 4)) {
+          lines.push(`extern ${quals(info)}${t} ${name};`);
+        }
+        break;
+      }
+      case 'array': {
+        // Element type mirrors core's bare `gSym[i]` env typing exactly (elemSigned ?? false).
+        // A non-1/2/4 element width is never bare-indexed by core (only &gSym cast forms), so
+        // an unsized u8[] decl is codegen-identical for every spelling core emits.
+        const elem = info.elemSize !== undefined ? intType(info.elemSize, info.elemSigned ?? false) : null;
+        lines.push(`extern ${quals(info)}${elem ?? 'u8'} ${name}[];`);
+        break;
+      }
+      case 'struct': {
+        // With a layout: the padded struct decl + a typed extern (the `gSym.field` spelling
+        // compiles against it). Without one, every core spelling is &gSym-based (a struct
+        // global never spells bare), so an unsized u8[] extern is codegen-identical.
+        const tag = info.structName ?? `Asmlift_${name}`;
+        const decl = structDecl(tag, info.layout, info.size);
+        if (decl !== null) {
+          if (!declaredTags.has(tag)) {
+            declaredTags.add(tag);
+            lines.push(decl);
+          }
+          lines.push(`extern ${quals(info)}struct ${tag} ${name};`);
+        } else {
+          lines.push(`extern ${quals(info)}u8 ${name}[];`);
+        }
+        break;
+      }
+      case 'pointer': {
+        // With a POINTEE layout the emitter may spell an interior as `gPtr->member`, which only
+        // compiles against a pointer to that struct — so the pointee is declared here (the same
+        // padded synthesis a struct global gets) and the extern is typed. The declared pointee
+        // never changes bytes: the cell is 4 bytes whatever it addresses, and core's own lowering
+        // makes every arithmetic stride EXPLICIT (`(u8 *)gPtr + K` / `(u32)gPtr`), so no emitted
+        // expression is scaled by this type.
+        // Without one, pointee fidelity is unnecessary — load/store/compare of the cell are
+        // identical for any object-pointer type, and the output then never derefs through the
+        // decl's pointee.
+        // THE shared gate (symbols.ts pointeeFields): the typed extern is emitted on exactly
+        // the condition under which core may spell `gPtr->member`, so the two cannot disagree.
+        const tag = info.pointee?.structName;
+        const decl =
+          pointeeFields(info.pointee) !== null ? structDecl(tag!, info.pointee!.layout, info.pointee!.size) : null;
+        if (decl !== null && !declaredTags.has(tag!)) {
+          declaredTags.add(tag!);
+          lines.push(decl);
+        }
+        // The POINTEE's own qualifiers bind to the pointed-at type (`volatile struct S *g`); the
+        // cell's bind to the VARIABLE (`struct S *volatile g`). They are independent declarations
+        // of two different objects, and the synthesis reproduces each on its own side of the `*`.
+        const pointeeQuals = `${info.pointee?.volatile ? 'volatile ' : ''}${info.pointee?.const ? 'const ' : ''}`;
+        const pointeeType = decl !== null ? `${pointeeQuals}struct ${tag} *` : `${pointeeQuals}void *`;
+        lines.push(`extern ${pointeeType}${info.volatile ? 'volatile ' : ''}${info.const ? 'const ' : ''}${name};`);
+        break;
+      }
+      default: {
+        // Name-only (no sidecar shape) — the second documented exception (see the module note;
+        // the first is the 4-byte signless enum cell). Skipping here was the original rule, but
+        // it made every named-spelling row of a symtab-only map project (marioparty3: names
+        // with no DWARF shapes) unreproducible in the self-declared world — the benchmark
+        // compiled those candidates inside the project headers, which declare the symbol.
+        // The width authority is the candidate's OWN IR (ref.access, rank.ts
+        // bareGlobalAccessFacts): a bare `name = v` / `x = name` compiles to the access the
+        // tree performed only under a decl of that exact width (`extern u16 g;` is `sh` where
+        // a guessed u32 is `sw`). Without a bare off-0 access fact, every core spelling goes
+        // through `&name` casts, where any object decl is address-identical — u32 is the
+        // fallback cell. A divergent decl can only LOSE score — the target bytes derive from
+        // the truth decls, so a mis-declared compile can never false-match (same argument as
+        // enumIsSigned).
+        const t = access ? intType(access.width, access.signed) : null;
+        lines.push(`extern ${quals(info)}${t ?? 'u32'} ${name};`);
+        break;
+      }
+    }
+  }
+  return lines.length ? lines.join('\n') + '\n' : '';
+}
+
+/** The object-like `#define`s out of a rendered declaration block.
+ *
+ *  Address-cast macro defines are the one part of a synthesized block that must survive into the
+ *  HEADERS world too. Everything else there is owned by the injected headers (a duplicate typedef
+ *  or struct definition is a C89 hard error), but a duplicate `#define` with an identical body is
+ *  legal — and a PREPROCESSED project context has no macros left at all, so dropping these turns a
+ *  macro-named candidate into an `undeclared identifier` rather than a spelling choice. */
+export function macroDefinesOf(declarations: string | undefined): string {
+  if (!declarations) {
+    return '';
+  }
+  const lines = declarations.split('\n').filter((l) => l.startsWith('#define '));
+  return lines.length ? lines.join('\n') + '\n' : '';
+}

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/frontend.ts

@@ -4,6 +4,7 @@
 // for target→frontend dispatch.
 import type { Fn } from '../ir/core';
 import type { Prototypes } from '../proto';
+import type { SymbolMap } from '../symbols';
 import type { TargetDescription } from '../target';
 import type { AsmData } from './asmdata';
 import type { AsmTextFormat } from './format';
@@ -17,6 +18,15 @@ export interface Frontend {
   /** decode one function's assembly into an L1 Fn. `prototypes` supplies callee arities
    *  (and any other header facts the frontend needs); an empty map is valid. `asmData` is the
    *  OPTIONAL Regime-B side-table (data-section jump tables + relocations); absent ⇒ a
-   *  dense-switch dispatch declines/loud-fails. */
-  lift(name: string, asm: string, target: TargetDescription, prototypes: Prototypes, asmData?: AsmData): Fn;
+   *  dense-switch dispatch declines/loud-fails. `symbols` is the OPTIONAL address→symbol map
+   *  (symbols.ts); today only the Thumb frontend consumes it (numeric-pool promotion) — the
+   *  MIPS/PPC objdump dialect already carries symbol names in the asm text. */
+  lift(
+    name: string,
+    asm: string,
+    target: TargetDescription,
+    prototypes: Prototypes,
+    asmData?: AsmData,
+    symbols?: SymbolMap,
+  ): Fn;
 }