@asmlift/core 0.1.0 → 0.3.0

package/src/frontend/thumb.ts

@@ -19,7 +19,9 @@ import type { Opcode } from '../ir/opcodes';
 import { T } from '../ir/types';
 import { type Prototypes, protoArity } from '../proto';
 import { RUNTIME_HELPERS } from '../raise/softdiv';
+import { type SymbolMap, lookupInterior, lookupSymbol } from '../symbols';
 import type { TargetDescription } from '../target';
+import type { AsmData } from './asmdata';
 import { pushSwitchBr } from './emit';
 import { FrontendUnsupportedError } from './errors';
 import { assertInputFormat } from './format';
@@ -171,10 +173,15 @@ function splitOperands(s: string): string[] {
 // Parse a Thumb memory addressing operand `[base]` or `[base, #off]` into base register +
 // constant byte offset. (Register-scaled indices like `[base, r1, lsl #2]` are not handled
 // yet — agbcc materialises those as explicit add/lsl before the load in the cases we target.)
-function parseAddr(operand: string): { base: string; off: number } {
+function parseAddr(operand: string): { base: string; off: number; regOff?: string } {
   const inner = operand.replace(/[[\]]/g, '').trim();
   const parts = inner.split(',').map((s) => s.trim());
   const base = parts[0];
+  // `[rB, rX]` — REGISTER-offset addressing. Surfaced to the caller so load/store DECLINE
+  // loud: silently reading `[rB]` (the old behavior) dropped the index — a silent miscompile.
+  if (parts[1] !== undefined && !parts[1].startsWith('#')) {
+    return { base, off: 0, regOff: parts[1] };
+  }
   const off = parts[1]?.startsWith('#') ? imm(parts[1]) : 0;
   return { base, off };
 }
@@ -724,6 +731,37 @@ function poolRef(operand: string, dataWords: Map<string, string[]>): PoolRef | n
   return { kind: 'unmodelled', why: `pool word '${w}' is a symbol offset or code label` };
 }
 
+/** Does this function's literal pool name at least one EXTERNAL symbol?
+ *
+ *  agbcc emits a pool word symbolically exactly when the source expression named a linker symbol,
+ *  and numerically when it did not (`*(vu16 *)0x4000130`, an address-cast macro). So within one
+ *  function, a numeric word sitting alongside a symbolic one is numeric *by the source's choice* —
+ *  which is what lets {@link liftThumb} refuse to invent a name for it.
+ *
+ *  The witness is required because that inference only holds for asm that KEPT its symbols. A
+ *  linked-ROM disassembly resolves every relocation to a number, and there "numeric" says nothing
+ *  about the source; vetoing on it would disable the map's naming for the users who need it most.
+ *  A function whose pool names nothing external is therefore left alone (both spellings still
+ *  enumerate, and the differ referees) rather than being read as evidence of anything.
+ *
+ *  Labels DEFINED in this same asm — the jump-table pointer word, a pret-style `_08012358` pool
+ *  label — are not external symbols and never witness: they survive disassembly whether or not
+ *  relocations did. */
+function poolNamesASymbol(dataWords: Map<string, string[]>, blockLabels: Set<string>): boolean {
+  for (const [, words] of dataWords) {
+    for (const raw of words) {
+      const w = raw.trim();
+      if (!/^[A-Za-z_]\w*$/.test(w) || w.startsWith('.L')) {
+        continue;
+      }
+      if (!dataWords.has(w) && !blockLabels.has(w)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
 // Recover an agbcc Thumb jump-table dispatch. Given a dispatch block `disp` ending in `mov pc, rV`
 // and its unique bounds predecessor `bounds` ending in `cmp rX,#(N-1); bhi DEF`, verify the exact
 // idiom and read the inline table — else return null (→ the indirect-jump loud-fail fires). The
@@ -816,7 +854,14 @@ function recoverJumpTable(
 /** Lift decoded asm → an L1 Fn with block-argument SSA. `prototypes` supplies each callee's
  *  declared parameter count (from the project's headers); it is authoritative for recovering
  *  how many argument registers a `bl` passes (falling back to a heuristic when absent). */
-export function lift(name: string, asm: string, target: TargetDescription, prototypes: Prototypes = {}): Fn {
+export function lift(
+  name: string,
+  asm: string,
+  target: TargetDescription,
+  prototypes: Prototypes = {},
+  _asmData?: AsmData,
+  symbols?: SymbolMap,
+): Fn {
   assertInputFormat('thumb', 'gnu-as', asm);
   const { blocks: rawBlocks, dataWords } = decode(name, asm);
 
@@ -825,6 +870,9 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
   // dispatch block is ELIDED from the CFG. A `mov pc` that is NOT a recognised table falls through
   // to the loud-fail below.
   const blockLabels = new Set(rawBlocks.map((b) => b.label));
+  // Whether THIS asm preserves symbol names in its literal pools — the witness the numeric-pool
+  // naming veto needs (see poolNamesASymbol).
+  const poolNamesSymbols = poolNamesASymbol(dataWords, blockLabels);
   // Any label referenced as a branch target (so we can tell if an elided dispatch block has a SECOND
   // predecessor — a `b disp` from elsewhere — which would dangle after elision; decline if so).
   const branchTargets = new Set<string>();
@@ -1278,6 +1326,54 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
           if (ins.mnemonic === 'ldr' && b !== undefined) {
             const pr = poolRef(b, dataWords);
             if (pr?.kind === 'const') {
+              // Numeric-pool PROMOTION (symbols.ts): a pool-loaded word whose value the
+              // project's symbol map knows becomes the NAMED global's address — the same
+              // `gaddr` the symbol-pool path emits, so everything downstream is the existing
+              // named-global machinery. Only pool-loaded words promote (an address built by
+              // arithmetic never reaches here); a promoted `code` symbol carries `code: true`
+              // so the structurer spells it `(u32)Name`, not `&Name`.
+              //
+              // VETOED when this asm's pool names other symbols (poolNamesASymbol): agbcc would
+              // have emitted THIS word symbolically too had the source named it, so promoting it
+              // spells a name the source did not use.
+              //
+              // …but the veto is really about RELOCATION, not about naming. An `extern` name makes
+              // the compiler emit a relocated pool word, which contradicts the numeric word the
+              // target shows. An address-cast MACRO expands to that same numeric literal, so it is
+              // COMPATIBLE with the evidence by construction and is never vetoed — indeed it is
+              // the spelling the numeric word is evidence FOR (klonoa's true source reaches these
+              // cells through exactly such macros). Nothing is guessed in either case: a vetoed
+              // word stays the raw constant the target says it is.
+              const found = symbols ? lookupSymbol(symbols, pr.value) : null;
+              const si = found && (!poolNamesSymbols || found.macroBody !== undefined) ? found : null;
+              if (si) {
+                const res = mkValue(T.unk(32));
+                irb.ops.push(
+                  mkOp('gaddr', {
+                    results: [res],
+                    attrs: { sym: si.name, ...(si.kind === 'code' ? { code: true } : {}) },
+                  }),
+                );
+                writeVar(reg(a), bi, res);
+                break;
+              }
+              // INTERIOR attribution: a value strictly inside a sized data symbol becomes
+              // `gaddr sym + offset` — the `&gSym + K` tree structure.ts already lowers (and,
+              // with a struct layout, spells as the named field). Sized symbols only; an
+              // unattributed address stays a raw const — nothing guesses.
+              // Interior attribution is always an `&gSym + K` spelling — extern-shaped, hence
+              // relocated — so the veto applies to it without the macro exemption above.
+              const interior = symbols && !poolNamesSymbols ? lookupInterior(symbols, pr.value) : null;
+              if (interior) {
+                const g = mkValue(T.unk(32));
+                const k = mkValue(T.unk(32));
+                const res = mkValue(T.unk(32));
+                irb.ops.push(mkOp('gaddr', { results: [g], attrs: { sym: interior.info.name } }));
+                irb.ops.push(mkOp('const', { results: [k], attrs: { value: interior.offset } }));
+                irb.ops.push(mkOp('add', { operands: [g, k], results: [res] }));
+                writeVar(reg(a), bi, res);
+                break;
+              }
               const res = mkValue(T.unk(32));
               irb.ops.push(mkOp('const', { results: [res], attrs: { value: pr.value } }));
               writeVar(reg(a), bi, res);
@@ -1303,9 +1399,19 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
           }
           const width = /b/.test(ins.mnemonic) ? 1 : /h/.test(ins.mnemonic) ? 2 : 4;
           const signed = ins.mnemonic === 'ldr' || /s/.test(ins.mnemonic.slice(3));
-          const { base, off } = parseAddr(b);
+          const { base, off, regOff } = parseAddr(b);
+          // `[rB, rX]` register-offset: lower EXACTLY as `rB + rX` then a load at offset 0 —
+          // the same address arithmetic the encoding performs. (parseAddr used to silently
+          // read `[rB]`, dropping the index — a silent miscompile; ldrsh exists ONLY in this
+          // form in Thumb-1, so every ldrsh went through here.)
+          let baseVal = readData(base, bi);
+          if (regOff !== undefined) {
+            const sum = mkValue(T.unk(32));
+            irb.ops.push(mkOp('add', { operands: [baseVal, readData(regOff, bi)], results: [sum] }));
+            baseVal = sum;
+          }
           const res = mkValue(T.unk(32));
-          irb.ops.push(mkOp('load', { operands: [readData(base, bi)], results: [res], attrs: { off, width, signed } }));
+          irb.ops.push(mkOp('load', { operands: [baseVal], results: [res], attrs: { off, width, signed } }));
           writeVar(reg(a), bi, res);
           break;
         }
@@ -1318,8 +1424,15 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
             break;
           }
           const width = /b/.test(ins.mnemonic) ? 1 : /h/.test(ins.mnemonic) ? 2 : 4;
-          const { base, off } = parseAddr(b);
-          irb.ops.push(mkOp('store', { operands: [readData(base, bi), readData(reg(a), bi)], attrs: { off, width } }));
+          const { base, off, regOff } = parseAddr(b);
+          let storeBase = readData(base, bi);
+          if (regOff !== undefined) {
+            // register-offset store: same exact `rB + rX` lowering as the load path above
+            const sum = mkValue(T.unk(32));
+            irb.ops.push(mkOp('add', { operands: [storeBase, readData(regOff, bi)], results: [sum] }));
+            storeBase = sum;
+          }
+          irb.ops.push(mkOp('store', { operands: [storeBase, readData(reg(a), bi)], attrs: { off, width } }));
           break;
         }
         case 'bl':

package/src/l3/ast.ts

@@ -43,7 +43,7 @@ export type Expr =
   // pointer, so the byte offset resolves to a named field instead of a scaled array index).
   // Unlike `index`, this carries the field NAME (which encodes the byte offset, `field_<off>`),
   // not a width-scaled number — the byte-offset-carrying member access cpp.ts's sub-word guard needs.
-  | { k: 'field'; base: Expr; name: string }
+  | { k: 'field'; base: Expr; name: string; dot?: true }
   // A GAP MARKER — the annotate-mode (`onGap: "annotate"`) spelling of a value asmlift could not
   // faithfully lift (an unmodelled instruction's `opaque` result, an unlowered transient op, a
   // dropped def). Every backend spells it as a call to the UNDEFINED symbol `ASMLIFT_ERROR("reason",
@@ -111,6 +111,10 @@ export interface SFn {
   name: string;
   params: { name: string; type: IrType }[];
   locals: { name: string; type: IrType }[]; // recovered locals, declared at function top
+  /** project globals referenced with a known declaration shape (symbol map) — typed for the
+   *  legalization env (exprCType) but NEVER declared by a backend: the project's own headers
+   *  declare them, exactly like every other global name asmlift emits. */
+  globals?: { name: string; type: IrType }[];
   retType: IrType;
   body: Stmt[];
   /** Struct types this function's fields reference, declared above it by the backend. Empty
@@ -148,7 +152,9 @@ export function dotBase(f: Extract<Expr, { k: 'field' }>): Extract<Expr, { k: 'i
 
 /** Boolean projection of `dotBase` for conditions that need no narrowing. */
 export function fieldSpellsDot(f: Extract<Expr, { k: 'field' }>): boolean {
-  return dotBase(f) !== undefined;
+  // dot also spells a STRUCT-VALUE global's field (`gSym.field`, the symbol-map layout path) —
+  // marked explicitly by the structurer via `dot: true` since the base is a `var`, not an index.
+  return dotBase(f) !== undefined || f.dot === true;
 }
 
 /** Structural equality of two expression trees. THE one copy of Expr deep-equal (like

package/src/l3/symbol-refs.ts

@@ -0,0 +1,61 @@
+// asmlift — SELF-DECLARING CANDIDATES: the pure map-reference query
+// (research/self-declaring-candidates-2026-07-26.md).
+//
+// `collectSymbolRefs` derives, from a FINAL structured tree, every map-derived symbol the body
+// references in a VALUE context — the input to the scoring layer's declaration synthesis
+// (@asmlift/cli declare.ts). It is a pure tree query with no pipeline state: the enumeration
+// layer (rank.ts) calls it exactly once per candidate, on the tree the candidate's source was
+// emitted from, at the moment the candidate is finalized. There is deliberately NO cached
+// `symbolRefs` field on `SFn` — a carried field would oblige every future l3 pass to remember
+// to recompute it (a dead-store DCE that drops a tree's only reference would otherwise leave a
+// stale ref, transitively reintroducing the hazards the collector excludes). Deriving at the
+// consumption point makes staleness impossible by construction.
+import type { SymbolInfo } from '../symbols';
+import { Expr, Stmt, exprChildren, stmtChildren, stmtExprs } from './ast';
+
+/** One recorded map-symbol VALUE reference — a name the tree references plus its map facts. */
+export interface SymbolRef {
+  name: string;
+  info: SymbolInfo;
+  /** NAME-ONLY symbols (no map shape): the bare off-0 access facts observed in the candidate's
+   *  own IR — attached by the enumeration (rank.ts bareGlobalAccessFacts), consumed by the
+   *  declaration synthesis (declare.ts) as the width/signedness authority for `extern T name;`. */
+  access?: { width: number; signed: boolean };
+}
+
+/** The map-derived symbols a structured body references in a VALUE context — the input to the
+ *  scoring layer's declaration synthesis. A name counts when it appears as a `var`/`addr` leaf
+ *  and the map knows it (bare `gSym`, `&gSym`, `(u32)Func`, a `field` base — all reduce to
+ *  those leaves). A name that is ANY call's target is excluded entirely, even if also
+ *  value-referenced: prototyping a called symbol `void F(void);` hard-errors under gcc-2.9
+ *  when the call passes args, while leaving it undeclared keeps today's implicit-declaration
+ *  behavior (the one honest option without arity knowledge). The function's OWN name
+ *  (`selfName`) is excluded too — the candidate's definition IS its declaration, and a
+ *  synthesized `void F(void);` above `s32 F(...)` is a conflicting-types hard error (a
+ *  self-address reference resolves against the definition itself). */
+export function collectSymbolRefs(body: Stmt[], symbols: Map<string, SymbolInfo>, selfName: string): SymbolRef[] {
+  const called = new Set<string>();
+  const valueRefs = new Set<string>();
+  const visitExpr = (e: Expr): void => {
+    if (e.k === 'call') {
+      called.add(e.fn);
+    } else if ((e.k === 'var' || e.k === 'addr') && symbols.has(e.name)) {
+      valueRefs.add(e.name);
+    }
+    exprChildren(e).forEach(visitExpr);
+  };
+  const visitStmt = (s: Stmt): void => {
+    // an `assign` carries its target as a NAME, not an Expr — a scalar global WRITE
+    // (`gSym = x;`) references the symbol every bit as much as a read does
+    if (s.k === 'assign' && symbols.has(s.name)) {
+      valueRefs.add(s.name);
+    }
+    stmtExprs(s).forEach(visitExpr);
+    stmtChildren(s).forEach(visitStmt);
+  };
+  body.forEach(visitStmt);
+  return [...valueRefs]
+    .filter((n) => !called.has(n) && n !== selfName)
+    .sort()
+    .map((n) => ({ name: n, info: symbols.get(n)! }));
+}

package/src/l3/typing.ts

@@ -27,6 +27,10 @@ export type VarTypes = (name: string) => IrType | undefined;
 
 export function declaredTypes(fn: SFn): VarTypes {
   const m = new Map<string, IrType>();
+  // shape-known project globals first, so a (theoretical) local of the same name wins
+  for (const g of fn.globals ?? []) {
+    m.set(g.name, g.type);
+  }
   for (const p of fn.params) {
     m.set(p.name, p.type);
   }

package/src/macros.ts

@@ -0,0 +1,126 @@
+// asmlift — address-cast macros: the OTHER way a project names a fixed RAM cell.
+//
+// Some decomp projects declare `extern u16 gCounter;` and let the linker place it; others write
+// `#define gCounter (*(u16 *)0x03001234)`. Both read the same cell, but they are NOT
+// interchangeable in the bytes an old compiler emits: an `extern` produces a RELOCATED literal-pool
+// word (`.word gCounter`), the macro a NUMERIC one (`.word 0x3001234`). A target that shows the
+// numeric word can therefore only be matched by the macro spelling — a symtab name will not do,
+// and no `.symtab` carries these names in the first place (a macro is not a symbol).
+//
+// This module is the PURE recognizer over preprocessor output (`cpp -dD`). Everything it accepts is
+// a fact it can name exactly; everything else is refused, because a wrong width or a dropped
+// `volatile` is the plausible-but-wrong class — see the guards on {@link addressCastMacros}.
+
+/** One recognized address-cast macro. */
+export interface AddressMacro {
+  name: string;
+  /** the cell's address — the map key this macro names */
+  address: number;
+  /** the macro body VERBATIM, as the declaration must reproduce it */
+  body: string;
+  /** the cast's byte width */
+  size: number;
+  /** the cast type's signedness */
+  signed: boolean;
+}
+
+/** The scalar type spellings a cast may use, and what each one means. Deliberately a CLOSED table:
+ *  an unrecognized spelling (a project typedef, an enum, a struct) is refused rather than guessed,
+ *  and every `volatile` alias is absent so it can never be silently dropped — the qualifier changes
+ *  whether repeated reads may be folded, which is both a byte and a semantic difference. */
+const SCALAR_TYPES: Record<string, { size: number; signed: boolean }> = {
+  u8: { size: 1, signed: false },
+  s8: { size: 1, signed: true },
+  u16: { size: 2, signed: false },
+  s16: { size: 2, signed: true },
+  u32: { size: 4, signed: false },
+  s32: { size: 4, signed: true },
+};
+
+/** `#define NAME (*(TYPE *)0xADDR)` — the ONE shape recognized. Anything else (a two-level
+ *  indirection, an offset expression, a function-like macro, a bare integer constant) does not
+ *  match and is therefore refused by construction. */
+const ADDRESS_CAST = /^\s*#define\s+([A-Za-z_]\w*)\s+(\(\s*\*\s*\(\s*(\w+)\s*\*\s*\)\s*(0[xX][0-9A-Fa-f]+)\s*\))\s*$/;
+
+/**
+ * Recognize the address-cast macros in `cpp -dD` output, keyed by the address each names.
+ *
+ * REFUSALS, all of them because the alternative is a plausible-but-wrong spelling:
+ *  - a cast type outside {@link SCALAR_TYPES} — including every `volatile` alias (`vu16`), whose
+ *    qualifier must not be silently dropped;
+ *  - two macros naming the SAME address (`REG_VCOUNT`/`REG_VCOUNT_L`/`REG_VCOUNT_H` at 0x04000006
+ *    differ in width, and picking wrong turns an `ldrh` into an `ldrb`) — both are dropped;
+ *  - one name defined at two addresses, which no correct spelling can disambiguate.
+ */
+export function addressCastMacros(cppOutput: string): Map<number, AddressMacro> {
+  return addressCastMacrosFrom(cppOutput.split('\n'));
+}
+
+/** The same recognizer over already-split `#define NAME body` lines — what a DWARF
+ *  `.debug_macinfo` reader produces once each definition is re-spelled as a directive. */
+export function addressCastMacrosFrom(defineLines: readonly string[]): Map<number, AddressMacro> {
+  const byAddress = new Map<number, AddressMacro>();
+  const collided = new Set<number>();
+  const seenNames = new Map<string, number>();
+  for (const line of defineLines) {
+    const m = ADDRESS_CAST.exec(line);
+    if (!m) {
+      continue;
+    }
+    const [, name, body, typeName, addrText] = m;
+    const type = SCALAR_TYPES[typeName];
+    if (!type) {
+      continue; // unknown or volatile-qualified spelling — refuse
+    }
+    const address = Number.parseInt(addrText, 16);
+    if (!Number.isFinite(address)) {
+      continue;
+    }
+    const priorAddr = seenNames.get(name);
+    if (priorAddr !== undefined && priorAddr !== address) {
+      collided.add(priorAddr);
+      collided.add(address);
+      continue;
+    }
+    seenNames.set(name, address);
+    const prior = byAddress.get(address);
+    if (prior && prior.name !== name) {
+      collided.add(address);
+      continue;
+    }
+    byAddress.set(address, { name, address, body, size: type.size, signed: type.signed });
+  }
+  for (const addr of collided) {
+    byAddress.delete(addr);
+  }
+  return byAddress;
+}
+
+/**
+ * The `#define` lines for every address-cast macro in `symbols` that `source` actually names.
+ *
+ * A published source that spells `gCollisionMapPtr` only compiles where that macro is defined —
+ * and a REPRODUCTION of it must therefore carry the definition, or the script the benchmark
+ * publishes cannot build the very source it publishes. Selected by the names the source uses
+ * rather than by the whole map, so a reproduction context stays the size of what it needs.
+ *
+ * Name-sorted and deduplicated: the materialized context must be byte-stable across machines.
+ */
+export function macroDefinesUsedBy(
+  symbols: Map<number, { name: string; macroBody?: string }[]>,
+  source: string,
+): string {
+  const used = new Map<string, string>();
+  for (const infos of symbols.values()) {
+    for (const info of infos) {
+      if (info.macroBody === undefined || used.has(info.name)) {
+        continue;
+      }
+      if (new RegExp(`\\b${info.name}\\b`).test(source)) {
+        used.set(info.name, info.macroBody);
+      }
+    }
+  }
+  const names = [...used.keys()].sort();
+  return names.length ? names.map((n) => `#define ${n} ${used.get(n)}`).join('\n') + '\n' : '';
+}

package/src/pipeline.ts

@@ -13,12 +13,13 @@ import { Expr, LanguageBackend, SFn, Stmt, exprChildren, stmtChildren, stmtExprs
 import { hoistReusedGlobalBases } from './l3/basecse';
 import { eliminateDeadStores } from './l3/dce';
 import { DEFAULT_IDIOM_PATTERNS, RewritePattern, applyPattern, dce, patternApplies } from './pattern/engine';
-import type { Prototypes } from './proto';
+import { type Prototypes, prototypesFromSymbols } from './proto';
 import { RaiseUnsupportedError } from './raise/errors';
 import { type PreRecoveryPass, runPreRecovery } from './raise/pre-recovery';
 import { recoverTypes } from './raise/recover';
 import { sinkReturns } from './raise/retsink';
 import { StructureError, structure } from './structure/structure';
+import { type SymbolMap, symbolsByName } from './symbols';
 import { type TargetDescription, structureOptionsFor } from './target';
 
 /** How a gap (a construct asmlift cannot faithfully model) degrades:
@@ -53,6 +54,10 @@ export interface DecompileOptions {
    *  MIPS/PPC switch declines/loud-fails; present ⇒ the frontend recovers the `switch_br`.
    *  Produced by `extractAsmData(obj, target)` from the scoring object. */
   asmData?: AsmData;
+  /** OPTIONAL address→symbol map (symbols.ts) — the project's own names (ELF symtab) and
+   *  declaration shapes (DWARF types-sidecar). Drives the Thumb numeric-pool promotion and the
+   *  byte-sensitive global spellings. Absent ⇒ byte-identical to today. */
+  symbols?: SymbolMap;
   /** gap policy — see `OnGap`. Default "strict". */
   onGap?: OnGap;
 }
@@ -97,9 +102,11 @@ function runTower(
   onGap: OnGap,
 ): DecompileResult {
   const backend = opts.backend ?? cBackend;
-  const prototypes = opts.prototypes ?? {};
+  // The project's own DWARF signatures fill in what the caller did not state — in practice the
+  // CALLEES (a function still in assembly has none), which is what makes this transferable.
+  const prototypes = prototypesFromSymbols(opts.symbols, opts.prototypes ?? {});
   // (1) lift: ISA frontend (resolved by target) → L1 with block-argument SSA
-  const fn = frontendFor(target).lift(name, asm, target, prototypes, opts.asmData);
+  const fn = frontendFor(target).lift(name, asm, target, prototypes, opts.asmData, opts.symbols);
   verify(fn);
   const raw = print(fn);
 
@@ -115,7 +122,11 @@ function runTower(
 
   // (4) structure: IR → neutral AST; boundary contract: no unresolved value leaked (strict), or
   // every unresolved value spelled as a loud ASMLIFT_ERROR marker (annotate).
-  const sfn = structureChecked(fn, { ...structureOptionsFor(target, prototypes[name]?.returnsVoid ?? false), onGap });
+  const sfn = structureChecked(fn, {
+    ...structureOptionsFor(target, prototypes[name]?.returnsVoid ?? false),
+    onGap,
+    ...(opts.symbols ? { symbols: symbolsByName(opts.symbols) } : {}),
+  });
 
   // (5) lower + print: neutral AST → target language
   const source = backend.emit(sfn);

package/src/proto.ts

@@ -1,3 +1,5 @@
+import type { SymbolMap } from './symbols';
+
 // asmlift — function prototypes: the single carrier for the caller-supplied facts a
 // matching-decomp project reads from its headers (arg counts, void-ness). One `Prototypes`
 // map, keyed by symbol, is threaded through every entry point and resolved at the point of
@@ -40,3 +42,56 @@ export function protoArity(p: FnProto | undefined): number | undefined {
   // fall back to the frontend's arg-register heuristic rather than misread a string's `.length`.
   return undefined;
 }
+
+/** The C type spelling for one declared parameter/return, or null when the facts do not
+ *  determine one. A pointer is `void *` — address-identical to any object pointer, and asmlift
+ *  makes every stride explicit — so nothing is guessed about what it points at. */
+function typeSpelling(t: { size: number | null; signed: boolean | null; pointer?: boolean }): ParamType | null {
+  if (t.pointer) {
+    return 'void *';
+  }
+  if (t.size === 1 || t.size === 2 || t.size === 4) {
+    // A signless 4-byte type is the C89 enum idiom (int); a signless NARROW one has no honest
+    // spelling, and the width alone would not fix its load, so it is refused.
+    if (t.signed === null) {
+      return t.size === 4 ? 's32' : null;
+    }
+    return `${t.signed ? 's' : 'u'}${t.size * 8}`;
+  }
+  return null;
+}
+
+/**
+ * Prototypes the project's own DWARF states, merged UNDER the caller's.
+ *
+ * A caller-supplied proto always wins: it comes from the user's headers or the benchmark
+ * manifest, and it is the thing a real user actually has for the function they are decompiling.
+ * The map fills the rest — in practice the CALLEES, since a function still written in assembly
+ * has no signature in its project's ELF (see SymbolSignature).
+ *
+ * Every parameter must spell faithfully or the whole entry is dropped: a partly-typed list would
+ * be read for its LENGTH and give the right arity with the wrong widths, which is worse than the
+ * arg-register heuristic it would replace.
+ */
+export function prototypesFromSymbols(symbols: SymbolMap | undefined, base: Prototypes = {}): Prototypes {
+  if (!symbols) {
+    return base;
+  }
+  const out: Prototypes = { ...base };
+  for (const infos of symbols.values()) {
+    for (const info of infos) {
+      if (info.kind !== 'code' || !info.signature || out[info.name] !== undefined) {
+        continue;
+      }
+      const params = info.signature.params.map(typeSpelling);
+      if (params.some((p) => p === null)) {
+        continue;
+      }
+      out[info.name] = {
+        params: params as ParamType[],
+        ...(info.signature.returns === null ? { returnsVoid: true } : {}),
+      };
+    }
+  }
+  return out;
+}

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