@asmlift/core 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asmlift/core",
-  "version": "0.2.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.)
@@ -99,15 +101,32 @@ 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.
+    // 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/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;
 }

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