@asmlift/core 0.2.0 → 0.3.0

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

@@ -12,17 +12,19 @@ import { cBackend } from './backend/c';
 import { assertDerefsTyped, assertResolved } from './contracts';
 import type { AsmData } from './frontend/asmdata';
 import { frontendFor } from './frontend/registry';
-import { Fn } from './ir/core';
+import { Fn, type Value, defOpMap } from './ir/core';
 import { T } from './ir/types';
 import { verify } from './ir/verify';
 import type { LanguageBackend, SFn } from './l3/ast';
 import { registerishSpellings } from './l3/regspell';
 import { reindexWalks } from './l3/reindex';
+import { type SymbolRef, collectSymbolRefs } from './l3/symbol-refs';
 import { RewritePattern } from './pattern/engine';
 import { applyIdiomPatterns, raiseRecovered, structureChecked } from './pipeline';
-import type { Prototypes } from './proto';
+import { type Prototypes, prototypesFromSymbols } from './proto';
 import { runPreRecovery } from './raise/pre-recovery';
 import { recoverTypes } from './raise/recover';
+import { type SymbolMap, symbolsByName } from './symbols';
 import { type TargetDescription, structureOptionsFor } from './target';
 
 /** The signedness of the entry parameters — the classic ambiguity asm cannot resolve.
@@ -51,25 +53,104 @@ function pinScalarParams(fn: Fn, signed: boolean, ptrIdx: Set<number>): void {
   });
 }
 
+/** Bare-global ACCESS FACTS for name-only map symbols — the width/signedness authority the
+ *  declaration synthesis (declare.ts) uses when the map has no shape. The map knows only the
+ *  NAME (symtab-only projects: marioparty3); the candidate's own IR knows exactly how the cell
+ *  is accessed, and the bare `gSym = v` / `x = gSym` spelling compiles to those bytes only
+ *  under a decl of that exact width (`extern u16 g;` is `sh` where a guessed u32 is `sw`).
+ *  Mirrors structure()'s scalar-global rule: a fact is recorded only for a symbol accessed
+ *  EXCLUSIVELY at offset 0 with ONE width and ONE load signedness — anything else (interior
+ *  offsets, address arithmetic, width or sign conflicts) records nothing, because those
+ *  spellings go through `&gSym` casts where every object decl is address-identical. */
+function bareGlobalAccessFacts(fn: Fn): Map<string, { width: number; signed: boolean }> {
+  const defs = defOpMap(fn);
+  const symOf = (v: Value): string | null => {
+    const d = defs.get(v);
+    return d?.opcode === 'gaddr' && d.attrs.code !== true ? (d.attrs.sym as string) : null;
+  };
+  const acc = new Map<string, { widths: Set<number>; signs: Set<boolean>; interior: boolean }>();
+  const get = (s: string) => acc.get(s) ?? acc.set(s, { widths: new Set(), signs: new Set(), interior: false }).get(s)!;
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      if (op.opcode === 'load' || op.opcode === 'store') {
+        const s = symOf(op.operands[0]);
+        if (s) {
+          const a = get(s);
+          if ((op.attrs.off as number) !== 0) {
+            a.interior = true;
+          } else {
+            a.widths.add(op.attrs.width as number);
+            if (op.opcode === 'load') {
+              a.signs.add(((op.attrs.signed as boolean) ?? false) && (op.attrs.width as number) < 4);
+            }
+          }
+        }
+      } else if (op.opcode === 'aload' || op.opcode === 'astore') {
+        const s = symOf(op.operands[0]);
+        if (s) {
+          get(s).interior = true;
+        }
+      } else {
+        // any other use of the address (arithmetic, a call arg, a comparison) is interior/escape
+        for (const o of op.operands) {
+          const s = symOf(o);
+          if (s) {
+            get(s).interior = true;
+          }
+        }
+      }
+    }
+  }
+  const out = new Map<string, { width: number; signed: boolean }>();
+  for (const [s, a] of acc) {
+    if (!a.interior && a.widths.size === 1 && a.signs.size <= 1) {
+      out.set(s, { width: [...a.widths][0], signed: a.signs.has(true) });
+    }
+  }
+  return out;
+}
+
 export interface EnumerateOptions {
   patterns?: RewritePattern[];
   backend?: LanguageBackend;
   prototypes?: Prototypes;
   asmData?: AsmData;
+  /** address→symbol map (symbols.ts) — same contract as DecompileOptions.symbols */
+  symbols?: SymbolMap;
 }
 
 /** One distinct candidate spelling (a signedness × branch-sense lever combination), emitted to source. */
 export interface Candidate {
   label: string;
   source: string;
+  /** the map-derived VALUE references this candidate's tree contains — what the scoring
+   *  layer's declaration synthesis renders. DERIVED, never carried: computed once from the
+   *  exact tree this candidate's source was emitted from, at the moment the candidate is
+   *  finalized (l3/symbol-refs.ts — no pipeline stage caches refs, so they cannot go stale).
+   *  Present on EVERY spelling variant that names mapped symbols — including '/raw-globals',
+   *  whose tree still names pool/reloc-derived globals (it only drops the map's shaped
+   *  SPELLINGS). Absent without a map — synthesis then has nothing to do. */
+  symbolRefs?: SymbolRef[];
 }
 /** A candidate paired with its score `S` (the injected scorer's result shape — must carry `.score`). */
 export interface Scored<S> extends Candidate {
   score: S;
 }
+/** A candidate the scorer REFUSED — its C did not build. Recorded rather than discarded: a
+ *  spelling that fails to compile is a defect in the emitter or in the facts it was given, and a
+ *  scoring harness that shows only the surviving sibling reports a clean win over a hidden
+ *  failure. */
+export interface DroppedCandidate {
+  label: string;
+  /** the scorer's first error line (a compiler diagnostic, usually) */
+  error: string;
+}
+
 export interface RankedResult<S> {
   best: Scored<S>; // lowest score
   candidates: Scored<S>[]; // sorted best (lowest) first
+  /** candidates whose scoreFn threw — empty when every spelling built */
+  dropped: DroppedCandidate[];
 }
 
 /** Emit the DISTINCT type/branch-sense candidate spellings for `name` — PURE, no scoring.
@@ -83,9 +164,14 @@ export function enumerateCandidates(
   opts: EnumerateOptions = {},
 ): Candidate[] {
   const backend = opts.backend ?? cBackend;
-  const prototypes = opts.prototypes ?? {};
+  // Same merge as `decompile`: the project's DWARF signatures fill in what the caller did not
+  // state, so both the annotate pass and the ranked candidates reason about one prototype table.
+  const prototypes = prototypesFromSymbols(opts.symbols, opts.prototypes ?? {});
   const frontend = frontendFor(target);
-  const baseOpts = structureOptionsFor(target, prototypes[name]?.returnsVoid ?? false);
+  const baseOpts = {
+    ...structureOptionsFor(target, prototypes[name]?.returnsVoid ?? false),
+    ...(opts.symbols ? { symbols: symbolsByName(opts.symbols) } : {}),
+  };
   // Branch-sense is a differ-ranked LEVER, the same class as param signedness: a divergent `if`
   // can be spelled with either sense (`if (c) A else B` vs `if (!c) B else A`), and which one the
   // source compiler emitted is genuinely ambiguous from asm. There is no safe global heuristic
@@ -101,75 +187,120 @@ export function enumerateCandidates(
   // so they are excluded from the signedness axis (see NO_PIN_KINDS). One extra lift+recover, no
   // compile. (The probe deliberately stops after recoverTypes — it only reads the param KINDS, so
   // the totality contract / return-sinking of the full spine are not run on it.)
-  const probe = frontend.lift(name, asm, target, prototypes, opts.asmData);
+  const probe = frontend.lift(name, asm, target, prototypes, opts.asmData, opts.symbols);
   verify(probe);
   applyIdiomPatterns(probe, target, opts.patterns);
   runPreRecovery(probe, target, () => verify(probe));
   recoverTypes(probe);
   const ptrIdx = new Set<number>(probe.blocks[0].params.flatMap((p, i) => (NO_PIN_KINDS.has(p.type.kind) ? [i] : [])));
+  // Access facts for name-only symbol declarations (see bareGlobalAccessFacts) — derived once
+  // from the probe: widths/offsets are lift-time facts, identical across every candidate.
+  const accessFacts = opts.symbols ? bareGlobalAccessFacts(probe) : new Map<string, never>();
 
   const seen = new Set<string>();
   const out: Candidate[] = [];
-  for (const cand of SIGN_CANDS) {
-    const fn = frontend.lift(name, asm, target, prototypes, opts.asmData);
-    verify(fn);
-    applyIdiomPatterns(fn, target, opts.patterns);
-    // The shared tower spine (pipeline.ts) — the candidate's ONE difference from decompile() is the
-    // signedness pin, injected between pre-recovery and recoverTypes via the beforeRecover hook.
-    raiseRecovered(fn, target, { beforeRecover: () => pinScalarParams(fn, cand.signed, ptrIdx) });
-    for (const s of senseCands) {
-      // structure() reads `fn` and produces a fresh SFn (it does not mutate `fn`), so both branch
-      // senses structure the same recovered function without re-lifting.
-      const sfn = structureChecked(fn, { ...baseOpts, preserveDivergentBranchSense: s.sense });
-      // The walk→index re-spelling (l3/reindex.ts) is a THIRD lever on the same footing as
-      // signedness and branch sense: whether the source spelled `*p; p++` or `arr[i]` is
-      // genuinely ambiguous from asm (compilers strength-reduce the latter into the former), so
-      // when a loop re-spells, BOTH representations are emitted and the differ referees. The
-      // re-spelling passes the same boundary contracts as the primary; one that fails them is
-      // dropped here — never scored, never able to win.
-      const spellings: { suffix: string; source: string }[] = [{ suffix: '', source: backend.emit(sfn) }];
-      // Representation re-spellings — each a lever on the same footing as signedness/branch sense,
-      // each guarded: it must pass the same boundary contracts as the primary AND emit (a backend
-      // that declines by throwing — Pascal loud-fails unspellable shapes — drops the candidate,
-      // never aborts the enumeration). A dropped re-spelling loses nothing: the primary remains.
-      //
-      // POLICY: re-spellings derive from the BASE spelling only — levers do not compose
-      // (an /indexed + /regcopy product is deferred until a row demands it). And a lever must
-      // PRESERVE SEMANTICS by construction: the differ referees byte-exactness (a wrong candidate
-      // can never fake a score-0 match), but on a NONMATCH row the best-scoring source is shown
-      // to the user — a semantically-wrong re-spelling there is plausible-but-wrong output, the
-      // defect class this project exists to avoid. Hence each lever's decline-over-approximate
-      // gates, adversarially audited.
-      const respell = (suffix: string, alt: SFn): void => {
-        try {
-          assertResolved(alt);
-          assertDerefsTyped(alt);
-          spellings.push({ suffix, source: backend.emit(alt) });
-        } catch {
-          // contract-failing or unspellable re-spelling: drop it, keep the primary
+  // The SYMBOL-MAP spelling is itself a ranked LEVER on the same footing as signedness/branch
+  // sense: naming a global changes agbcc's codegen (the eager-load effect), and which side
+  // byte-wins is genuinely per-function — the dogfood's landed matches split between extern
+  // spellings and raw-address macros. So when a map is present the raw-global spelling is ALSO
+  // enumerated ('/raw-globals') and the differ referees; the dedup below collapses the pair
+  // wherever the map changed nothing, so this never scores worse than either side alone.
+  const symbolVariants: { suffix: string; symbols?: typeof opts.symbols }[] = opts.symbols
+    ? [
+        { suffix: '', symbols: opts.symbols },
+        { suffix: '/raw-globals', symbols: undefined },
+      ]
+    : [{ suffix: '' }];
+  for (const sv of symbolVariants) {
+    const svOpts = sv.symbols ? baseOpts : { ...baseOpts, symbols: undefined };
+    for (const cand of SIGN_CANDS) {
+      const fn = frontend.lift(name, asm, target, prototypes, opts.asmData, sv.symbols);
+      verify(fn);
+      applyIdiomPatterns(fn, target, opts.patterns);
+      // The shared tower spine (pipeline.ts) — the candidate's ONE difference from decompile() is the
+      // signedness pin, injected between pre-recovery and recoverTypes via the beforeRecover hook.
+      raiseRecovered(fn, target, { beforeRecover: () => pinScalarParams(fn, cand.signed, ptrIdx) });
+      for (const s of senseCands) {
+        // structure() reads `fn` and produces a fresh SFn (it does not mutate `fn`), so both branch
+        // senses structure the same recovered function without re-lifting.
+        const sfn = structureChecked(fn, { ...svOpts, preserveDivergentBranchSense: s.sense });
+        // The walk→index re-spelling (l3/reindex.ts) is a THIRD lever on the same footing as
+        // signedness and branch sense: whether the source spelled `*p; p++` or `arr[i]` is
+        // genuinely ambiguous from asm (compilers strength-reduce the latter into the former), so
+        // when a loop re-spells, BOTH representations are emitted and the differ referees. The
+        // re-spelling passes the same boundary contracts as the primary; one that fails them is
+        // dropped here — never scored, never able to win.
+        // Each spelling's symbol refs are DERIVED from its own final tree right where the
+        // spelling is emitted — the single point a candidate comes into existence. No pipeline
+        // stage carries refs (SFn has no such field), so a future l3 pass that rewrites the tree
+        // can never leave a stale ref behind: whatever tree reaches emit is the tree the refs
+        // describe, by construction. Collected against the FULL name-keyed map for EVERY
+        // spelling variant — the '/raw-globals' sibling drops the map's shaped SPELLINGS, but
+        // its tree still NAMES pool/reloc-derived globals (ARM `.word gSym`, MIPS `%lo(gSym)`),
+        // and those references need declarations in the self-declared scoring world exactly
+        // like the named variant's (without them every raw sibling fails to compile there,
+        // and the eval-winning raw candidate becomes unreproducible outside project headers).
+        const refsOf = (tree: SFn): { symbolRefs?: SymbolRef[] } => {
+          const refs = baseOpts.symbols
+            ? collectSymbolRefs(tree.body, baseOpts.symbols, tree.name).map((r) => {
+                // name-only symbols carry the IR-derived access facts — the width authority
+                // for their synthesized declaration (shaped symbols keep the map's truth)
+                const access = r.info.shape === undefined ? accessFacts.get(r.name) : undefined;
+                return access ? { ...r, access } : r;
+              })
+            : [];
+          return refs.length ? { symbolRefs: refs } : {};
+        };
+        const spellings: { suffix: string; source: string; symbolRefs?: SymbolRef[] }[] = [
+          { suffix: '', source: backend.emit(sfn), ...refsOf(sfn) },
+        ];
+        // Representation re-spellings — each a lever on the same footing as signedness/branch sense,
+        // each guarded: it must pass the same boundary contracts as the primary AND emit (a backend
+        // that declines by throwing — Pascal loud-fails unspellable shapes — drops the candidate,
+        // never aborts the enumeration). A dropped re-spelling loses nothing: the primary remains.
+        //
+        // POLICY: re-spellings derive from the BASE spelling only — levers do not compose
+        // (an /indexed + /regcopy product is deferred until a row demands it). And a lever must
+        // PRESERVE SEMANTICS by construction: the differ referees byte-exactness (a wrong candidate
+        // can never fake a score-0 match), but on a NONMATCH row the best-scoring source is shown
+        // to the user — a semantically-wrong re-spelling there is plausible-but-wrong output, the
+        // defect class this project exists to avoid. Hence each lever's decline-over-approximate
+        // gates, adversarially audited.
+        const respell = (suffix: string, alt: SFn): void => {
+          try {
+            assertResolved(alt);
+            assertDerefsTyped(alt);
+            spellings.push({ suffix, source: backend.emit(alt), ...refsOf(alt) });
+          } catch {
+            // contract-failing or unspellable re-spelling: drop it, keep the primary
+          }
+        };
+        const indexed = reindexWalks(sfn);
+        if (indexed) {
+          respell('/indexed', indexed);
         }
-      };
-      const indexed = reindexWalks(sfn);
-      if (indexed) {
-        respell('/indexed', indexed);
-      }
-      // the register-copy spelling (l3/regspell.ts): 0–3 variants (base; tail assign-back reusing
-      // the dead value var; tail assign-back into a fresh var — the tail choice is allocator-
-      // ambiguous, so both are ranked)
-      const REGCOPY_LABELS = ['/regcopy', '/regcopy-ret', '/regcopy-ret-fresh'];
-      registerishSpellings(sfn).forEach((alt, i) => respell(REGCOPY_LABELS[i] ?? `/regcopy-${i}`, alt));
-      for (const sp of spellings) {
-        const source = sp.source;
-        // Collapse a spelling that produced identical source (a function with no divergent `if`
-        // structures the same either way): no point scoring a duplicate spelling. Deduping the
-        // WHOLE emitted set (not just scored survivors) is equivalent — an identical source
-        // scores identically, so it can never change `best` — and it keeps the candidate set to
-        // the genuinely distinct spellings.
-        if (seen.has(source)) {
-          continue;
+        // the register-copy spelling (l3/regspell.ts): 0–3 variants (base; tail assign-back reusing
+        // the dead value var; tail assign-back into a fresh var — the tail choice is allocator-
+        // ambiguous, so both are ranked)
+        const REGCOPY_LABELS = ['/regcopy', '/regcopy-ret', '/regcopy-ret-fresh'];
+        registerishSpellings(sfn).forEach((alt, i) => respell(REGCOPY_LABELS[i] ?? `/regcopy-${i}`, alt));
+        for (const sp of spellings) {
+          const source = sp.source;
+          // Collapse a spelling that produced identical source (a function with no divergent `if`
+          // structures the same either way): no point scoring a duplicate spelling. Deduping the
+          // WHOLE emitted set (not just scored survivors) is equivalent — an identical source
+          // scores identically, so it can never change `best` — and it keeps the candidate set to
+          // the genuinely distinct spellings.
+          if (seen.has(source)) {
+            continue;
+          }
+          seen.add(source);
+          out.push({
+            label: `${cand.label}${s.suffix}${sp.suffix}${sv.suffix}`,
+            source,
+            ...(sp.symbolRefs ? { symbolRefs: sp.symbolRefs } : {}),
+          });
         }
-        seen.add(source);
-        out.push({ label: `${cand.label}${s.suffix}${sp.suffix}`, source });
       }
     }
   }
@@ -185,24 +316,32 @@ export function enumerateCandidates(
 export function rankBy<S extends { score: number }>(
   candidates: Candidate[],
   symbol: string,
-  scoreFn: (source: string, symbol: string) => S,
+  scoreFn: (source: string, symbol: string, candidate: Candidate) => S,
 ): RankedResult<S> {
-  const results: Scored<S>[] = [];
-  let lastScoreErr: unknown = null; // a candidate's C that failed to compile; only fatal if ALL do
-  for (const c of candidates) {
+  const results: (Scored<S> & { order: number })[] = [];
+  const dropped: DroppedCandidate[] = []; // spellings that failed to build; only fatal if ALL do
+  let lastScoreErr: unknown = null;
+  candidates.forEach((c, order) => {
     try {
-      results.push({ ...c, score: scoreFn(c.source, symbol) });
+      results.push({ ...c, order, score: scoreFn(c.source, symbol, c) });
     } catch (e) {
       lastScoreErr = e;
+      dropped.push({ label: c.label, error: firstLine(e) });
     }
-  }
+  });
   if (results.length === 0) {
-    const why =
-      lastScoreErr instanceof Error
-        ? lastScoreErr.message.split('\n')[0]
-        : String(lastScoreErr ?? 'no candidate produced');
-    throw new Error(`no scorable candidate for '${symbol}': ${why}`, { cause: lastScoreErr });
+    throw new Error(`no scorable candidate for '${symbol}': ${firstLine(lastScoreErr)}`, { cause: lastScoreErr });
   }
-  results.sort((a, b) => a.score.score - b.score.score);
-  return { best: results[0], candidates: results };
+  // Score first; ENUMERATION ORDER breaks a tie. That order is meaningful, not incidental:
+  // enumerateCandidates emits the symbol-map spellings before their `/raw-globals` siblings, so
+  // when both compile to the same bytes the named one wins and the reader gets `gCounter` rather
+  // than a bare address. Spelled as an explicit comparator because relying on Array#sort's
+  // stability would make the preference an accident of two unrelated decisions.
+  results.sort((a, b) => a.score.score - b.score.score || a.order - b.order);
+  return { best: results[0], candidates: results.map(({ order: _order, ...c }) => c), dropped };
+}
+
+/** First line of whatever the scorer threw — the compiler's own diagnostic, not a stack. */
+function firstLine(e: unknown): string {
+  return e instanceof Error ? e.message.split('\n')[0] : String(e ?? 'no candidate produced');
 }