@asmlift/core 0.5.0 → 0.7.0

package/src/raise/struct-arrays.ts

@@ -18,7 +18,9 @@
 // UNAMBIGUOUS here (the scaled operand is the index, read from the machine code) — the unscaled
 // `add(x, y)` byte form stays out of scope (genuinely ambiguous without types).
 import { Fn, Op, Value, defOpMap, mkOp } from '../ir/core';
+import { nextStructIndex } from '../ir/struct-names';
 import { IrType, StructField, T, scalarTypeForAccess } from '../ir/types';
+import { collectStructs } from './structs';
 
 interface Scaled {
   base: Value;
@@ -94,6 +96,15 @@ function withPadding(dataFields: StructField[], stride: number): StructField[] {
 export function recognizeStructArrays(fn: Fn): number {
   const defs = defOpMap(fn);
   let count = 0;
+  // The NAME index is not the recognition count: `count` is this function's return value — how
+  // many groups it recognized — and seeding it would report the wrong number. The index starts
+  // past every `Elem<N>` the graph already mentions; over the corpus that scan returns 0 every
+  // time, because this pass runs once per function and nothing else mints the prefix, and
+  // ir/struct-names.ts states why the computed 0 is kept over the assumed one.
+  let name = nextStructIndex(
+    [...collectStructs(fn)].map((s) => s.name),
+    'Elem',
+  );
 
   // group candidate element pointers by base, tracking each add's own index and stride
   const byBase = new Map<Value, { add: Op; index: Value; stride: number }[]>();
@@ -222,7 +233,7 @@ export function recognizeStructArrays(fn: Fn): number {
       type: scalarTypeForAccess(width, loadSigned ?? width === 4),
       name: `field_${off}`,
     }));
-    const elemStruct = T.struct(`Elem${count}`, withPadding(dataFields, stride), stride);
+    const elemStruct = T.struct(`Elem${name++}`, withPadding(dataFields, stride), stride);
     base.type = T.ptr(elemStruct);
 
     // Rewrite each field load/store into an aload/astore carrying base, ITS elem's index,
@@ -242,7 +253,13 @@ export function recognizeStructArrays(fn: Fn): number {
           bb.ops[i] = mkOp('aload', {
             operands: [base, index],
             results: [op.results[0]],
-            attrs: { elemSize: stride, signed: op.attrs.signed as boolean, fieldOff: op.attrs.off as number },
+            // listOrder rides along: an ldmia-expanded load keeps its stream-order caveat as an aload
+            attrs: {
+              elemSize: stride,
+              signed: op.attrs.signed as boolean,
+              fieldOff: op.attrs.off as number,
+              ...(op.attrs.listOrder === true && { listOrder: true }),
+            },
           });
         } else if (op.opcode === 'store') {
           bb.ops[i] = mkOp('astore', {

package/src/raise/structs.ts

@@ -22,8 +22,22 @@
 //   base @ {off8 w4}           -> array  (single aligned access — no struct evidence)
 //   base @ aload(index)        -> array  (variable index — untouched)
 //
-// This recovery is BYTE-NEUTRAL — `->field_N` and `[idx]` compile identically, so it is a
-// representation upgrade driven by access evidence, not a scored lever. GAPS between accessed
+// This recovery is USUALLY BYTE-NEUTRAL — `->field_N` and `[idx]` mostly compile identically, so it
+// is a representation upgrade driven by access evidence rather than a scored variation. TWO
+// MEASUREMENTS SAY "USUALLY" IS THE RIGHT WORD, and both were made on agbcc against a real target
+// object, each pair differing in ONE token:
+//   • THE SPELLING. `synthetic:dmanest`'s reference compiles from `((struct Elem0 *)K)[a1].field_4`
+//     to a byte-exact match and from `((s32 *)((a1 << 3) + K))[1]` to a 2-point diff — a
+//     COMPONENT_REF keeps the offset in the load displacement, an index folds it into the pool
+//     literal. The row's own dataset entry carries the reproduction.
+//   • THE FIELD TYPE, which this file assigns from the ACCESS WIDTH alone. A word field declared
+//     `void *` rather than `s32` changes agbcc's alias set and lets a loop-invariant load leave the
+//     loop: `synthetic:dmaptrsrc` matches with the pointer declaration and diffs by 35 without it
+//     (its own fan: `/vol-store/unreduce/ptr-field` 0, `/vol-store/unreduce` 35).
+//     That is what `l3/ptrfield.ts` offers as a differ-ranked variation.
+// So the neutrality claim is CONDITIONAL, and nothing here says on what. Until it does, read it as
+// "no candidate is enumerated for this question", not as "the differ could not referee one" — the
+// second reading is the one both measurements above falsify. GAPS between accessed
 // offsets (unaccessed leading/interior fields) are filled with `u8[N]` PAD fields so the declared
 // struct reproduces the observed offsets byte-for-byte and is self-describing (the same
 // discipline raise/struct-arrays.ts withPadding uses). Each accessed field must still be
@@ -31,6 +45,7 @@
 // at an offset natural C alignment could not place it at) is rejected LOUD, as is an
 // overlap/union.
 import { Fn, Op, Value } from '../ir/core';
+import { nextStructIndex } from '../ir/struct-names';
 import { IrType, StructField, T, scalarTypeForAccess } from '../ir/types';
 import type { StructType } from '../l3/ast';
 import { RaiseUnsupportedError } from './errors';
@@ -49,7 +64,7 @@ interface Access {
 // is a DIFFERENT operation: this pass is ALIGNMENT-AWARE (no explicit pad when C's own inter-field
 // padding already lands the field) and carries NO trailing pad / struct `size` (a recovered struct
 // here is only ever a `struct S *` pointee accessed by named field — never an array element or a
-// by-value param, so sizeof is never taken). If the two are ever unified, PARAMETERIZE those axes
+// by-value param, so sizeof is never taken). If the two are ever unified, PARAMETERIZE those dimensions
 // — a naive merge would break the natural-alignment golden or silently mislay a struct that later
 // becomes an element / ABI value.
 const sizeAlign = (width: number): number => width;
@@ -189,6 +204,10 @@ export function recognizeStructs(fn: Fn): number {
     }
   }
 
+  // The NAME counter is seeded from the names already in the graph, not from this pass's own
+  // success count: raise/memberarrays.ts runs first and mints `Struct<N>` types of its own, and two
+  // different layouts under one name would leave `collectStructs` declaring only one of them.
+  let name = firstFreeStructIndex(fn);
   let count = 0;
   for (const base of order) {
     if (arrayBases.has(base)) {
@@ -203,7 +222,7 @@ export function recognizeStructs(fn: Fn): number {
       continue;
     } // uniform stride / single aligned access → array
     try {
-      base.type = T.ptr(buildStruct(`Struct${count}`, accesses));
+      base.type = T.ptr(buildStruct(`Struct${name}`, accesses));
     } catch (e) {
       // A NAMED global whose accesses synthesis cannot reconcile is not a reason to decline the
       // function: its declaration belongs to the project's own headers, and its constant-offset
@@ -219,11 +238,22 @@ export function recognizeStructs(fn: Fn): number {
       }
       throw e;
     }
+    name++;
     count++;
   }
   return count;
 }
 
+/** The next `Struct<N>` index past every one this function's graph already uses — the shared name
+ *  allocator for the two passes that synthesize a struct pointee. The scan itself is
+ *  `ir/struct-names.ts`, which the three struct minters share; this names the prefix. */
+export function firstFreeStructIndex(fn: Fn): number {
+  return nextStructIndex(
+    [...collectStructs(fn)].map((s) => s.name),
+    'Struct',
+  );
+}
+
 /** The distinct struct types this function's L2 GRAPH mentions (unwrapping struct pointers on every
  *  value), deduped by name and sorted, for the backend to declare above the function.
  *

package/src/raise/tailsink.ts

@@ -0,0 +1,126 @@
+// asmlift — sink a shared STORE tail back into the paths that branch to it.
+//
+// agbcc's gcse.c PRE finds a trailing store's base partially redundant, INSERTS it at the end of
+// every predecessor of the join, and the arms then cross-jump into one `store; ret`:
+//
+//     if (c) { for (…) …; } else { if (x) { gQ.cur = fnA; return; } }
+//     gQ.cur = fnB;
+//
+// lifts as ONE tail block `^t(v): store gQ.cur, v; ret` that the `fnA` arm and the join the two
+// sides reach both branch to. The structurer can spell that tail once, after the `if`, only if the
+// `fnA` path returns before it — so this duplicates the tail into every path that branches to it.
+// WHICH copy is the tail the source wrote once is not decided here: it is the `ret` reachable from
+// both successors of the `if`, which `structure()`'s `followEarlyReturns` finds and spells after
+// the `if`, with every other copy an early `return;` (`synthetic:gcsetail`). Under `-fno-gcse` the
+// tail/duplicated pairs compile byte-identical, and there is no loop gate: a loop before the join
+// is a sample, not a law.
+//
+// A block that supplies the tail's arguments is a SOURCE: a PURE FORWARDER (`^f(v): br ^t(v)`,
+// reached only by `br`) is seen through to its own predecessors, so the arms that branch into the
+// tail through a shared base reload are sources like any other (`synthetic:gcsefwd`).
+//
+// A LIFT VARIATION, NEVER A DEFAULT: `synthetic:gcsepre` and `synthetic:gcsepredup` compile to
+// different objects (an r4/r5 swap) and lift to byte-identical IR, the first written with the
+// shared tail and the second with the default duplicated into each arm — no IR rule tells them
+// apart, so rank.ts enumerates this beside the unsunk lift and the differ referees.
+//
+// SOUND BY CONSTRUCTION: tail duplication. Each copy runs on exactly the paths that ran the tail,
+// immediately before the same `ret`. A value the tail reads is one of two things. It is a block
+// parameter of the tail OR OF A FORWARDER on the way, and the copy takes the argument that path's
+// edge into that block carried. Or it is defined elsewhere, dominates the tail, and so dominates
+// every source of it. The forwarder's own parameter is not a corner: a tail whose only predecessor
+// is a forwarder loses its parameter to raise's `simplifyTrivialPhis` and reads the forwarder's
+// directly — a jump pad `.L4: b .L6` in front of the store does exactly that — and the forwarder is
+// swept once every source holds its copy. A copy replaces a `br`, the source's only edge. A
+// CONDITIONAL edge cannot carry one — splicing over it would drop the branch's other successor — so
+// the tail stays for the sources that reach it that way; that restriction is the rewrite's own
+// precondition, not a gate.
+//
+// NO GATE: which copy stays shared is the follow's question, and whether a sunk function is worth
+// a candidate is rank.ts's, asked with the follow's own predicate (`hasDivergentSharedRet`) rather
+// than a copy of it here.
+import { type Block, type Fn, type Value, mkOp, predecessors, reachableBlocks, terminator } from '../ir/core';
+import { simplifyTrivialPhis } from '../ir/simplify';
+
+/** One edge that supplies the tail its arguments. `resolve` sends a value the tail reads to the
+ *  value it has at the end of `from`: a parameter of the tail or of any forwarder between becomes
+ *  the argument this path's edge into that block carried, and anything else is left alone. */
+interface Source {
+  readonly from: Block;
+  readonly resolve: (v: Value) => Value;
+}
+
+/** A block whose ops are one or more `store`s and then a void `ret`. */
+function isStoreTail(b: Block): boolean {
+  const t = b.ops[b.ops.length - 1];
+  return (
+    b.ops.length >= 2 &&
+    t.opcode === 'ret' &&
+    t.operands.length === 0 &&
+    b.ops.slice(0, -1).every((o) => o.opcode === 'store')
+  );
+}
+
+/** Copy every store tail that two or more sources reach into each source that reaches it by a
+ *  `br`; returns whether anything changed. */
+export function sinkStoreTails(fn: Fn): boolean {
+  let changed = false;
+  for (const tail of [...fn.blocks]) {
+    if (tail === fn.blocks[0] || !fn.blocks.includes(tail) || !isStoreTail(tail)) {
+      continue;
+    }
+    const preds = predecessors(fn);
+    // The sources, seen through pure forwarders. `resolve` sends a value the tail reads to the value
+    // it has on entry to the block being walked; each edge out of a predecessor composes one more
+    // step onto it — `to`'s own parameters, not only the tail's, because the tail may read a
+    // forwarder's parameter directly.
+    const forwarders = new Set<Block>();
+    const sources: Source[] = [];
+    const conditional: Block[] = [];
+    const walk = (to: Block, resolve: (v: Value) => Value) => {
+      for (const p of preds.get(to) ?? []) {
+        const t = terminator(p)!;
+        if (t.opcode !== 'br') {
+          conditional.push(p);
+          continue;
+        }
+        const edge = t.successors[0].args;
+        const through = (v: Value): Value => {
+          const w = resolve(v);
+          const i = to.params.indexOf(w);
+          return i >= 0 ? edge[i] : w;
+        };
+        const isForwarder =
+          p !== fn.blocks[0] &&
+          p.ops.length === 1 &&
+          !forwarders.has(p) &&
+          (preds.get(p) ?? []).every((q) => terminator(q)?.opcode === 'br');
+        if (isForwarder) {
+          forwarders.add(p);
+          walk(p, through);
+        } else {
+          sources.push({ from: p, resolve: through });
+        }
+      }
+    };
+    walk(tail, (v) => v);
+    if (sources.length === 0 || sources.length + conditional.length < 2) {
+      continue;
+    }
+    const body = tail.ops.slice(0, -1);
+    for (const src of sources) {
+      const copies = body.map((o) => mkOp('store', { operands: o.operands.map(src.resolve), attrs: { ...o.attrs } }));
+      src.from.ops.splice(src.from.ops.length - 1, 1, ...copies, mkOp('ret'));
+    }
+    // By REACHABILITY, not predecessor count: the tail (unless a conditional edge keeps it) and
+    // every forwarder on the way are left unreachable, however long the chain, and a forwarder's
+    // in-edge from another orphan still counts as a predecessor.
+    const live = reachableBlocks(fn);
+    fn.blocks = fn.blocks.filter((b) => live.has(b));
+    changed = true;
+  }
+  if (changed) {
+    simplifyTrivialPhis(fn);
+  }
+  return changed;
+}

package/src/rank-declare.ts

@@ -0,0 +1,256 @@
+// asmlift — the DECLARATION half of candidate enumeration, split out of rank.ts. A candidate's
+// source names globals its own asm named, and outside the project's headers those names need
+// declarations or every candidate fails to compile. This module answers three questions about
+// them and nothing else: what the tree's own IR says about a bare global's ACCESS
+// (`bareGlobalAccessFacts`), which names exist at all (`bareGlobalSymbols`), and which of them a
+// declaration must REFUSE to claim (`makeRefCollector`, via `RefusedDeclarationReason`).
+//
+// It knows nothing about variations or ranking: the enumeration driver hands it a dictionary and
+// asks each emitted tree for its references. A SIBLING MODULE, never a `rank/` directory — see the
+// same note on rank-variations.ts.
+import { type Fn, type Value, defOpMap } from './ir/core';
+import type { SFn } from './l3/ast';
+import { type SymbolRef, collectSymbolRefs } from './l3/symbol-refs';
+import type { SymbolInfo } from './symbols';
+import { C_TYPEDEFS } from './target';
+
+/** 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. */
+export 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;
+}
+
+/** Names a declaration must never claim, because `extern u32 <name>;` is not a declaration of
+ *  `<name>` at all for them. Four groups, and only the first two are guessed:
+ *
+ *    1. the prelude's own typedef names, derived FROM `C_TYPEDEFS` rather than re-listed (a
+ *       prelude that grows a name grows this set) — `extern u32 u16;` redefines the type the
+ *       declaration is written in;
+ *    2. the C89 keywords;
+ *    3. the gnu89 keywords gcc-2.9 REJECTS in this position, and the two library objects it
+ *       refuses to have redeclared. MEASURED against the pinned agbcc — 72 plausible pool names
+ *       compiled as `extern u32 <name>;` at file scope, 18 exited non-zero: `syntax error before
+ *       'asm'` for the keyword class, ``'exit' redeclared as different kind of symbol`` for the
+ *       two built-ins;
+ *    4. the gnu89 declaration SPECIFIERS that PARSE and thereby declare nothing — `inline`,
+ *       `__const`, `__volatile__`, … are `warning: useless keyword or type name in empty
+ *       declaration`, exit 0, and the name is still undeclared. Emitting the line would be a
+ *       declaration that is not one.
+ *
+ *  WHAT REFUSING BUYS is less than a plain `'<name>' undeclared`, and the difference is the
+ *  reason the refusal is REPORTED rather than trusted to the compiler. A hard error in the block
+ *  kills that candidate's whole TU (its own — every candidate compiles alone) for a name it
+ *  merely mentioned, so refusing is right. But for a KEYWORD the body spells the same token
+ *  anyway and the candidate still fails: the refusal only moves the diagnostic. And for the two
+ *  BUILT-INS nothing fails — agbcc reads `&exit` as the address of its own builtin, exit 0 with
+ *  `warning: built-in function 'exit' used without declaration`, where the declaration would have
+ *  been exit 1. There the refusal trades a candidate that cannot build for one that builds
+ *  against the wrong object, which is the better half of a bad choice only because a target
+ *  naming a global `exit` has no honest spelling either way. */
+const DECL_RESERVED = new Set<string>([
+  ...[...C_TYPEDEFS.matchAll(/(\w+)\s*;/g)].map((m) => m[1]),
+  ...(
+    'auto break case char const continue default do double else enum extern float for goto if int long ' +
+    'register return short signed sizeof static struct switch typedef union unsigned void volatile while'
+  ).split(' '),
+  // group 3 — measured hard errors (agbcc, `extern u32 <name>;` at file scope)
+  ...(
+    'asm __asm __asm__ typeof __typeof __typeof__ __attribute __attribute__ __extension__ __label__ ' +
+    '__alignof __alignof__ __real__ __imag__ __func__ __FUNCTION__ exit abort'
+  ).split(' '),
+  // group 4 — measured "useless keyword ... in empty declaration": parses, declares nothing
+  ...(
+    'inline __inline __inline__ __const __const__ __signed __signed__ __volatile __volatile__ ' +
+    '__restrict __restrict__ __complex__'
+  ).split(' '),
+]);
+
+/** The emitter's own NAME GRAMMAR for storage it invents: parameters `a0, a1, …` (structure.ts
+ *  names them positionally, so no rename can move one) and coalesced/temp locals `v0…`/`t0…`
+ *  (structure.ts's `localNames` accepts exactly `/^[vt]\d+$/`). A pool or map symbol with one of
+ *  these names cannot be declared beside the C that spells it — see the refusal in `refsOf`, which
+ *  is the one that kills the spelling rather than the line.
+ *
+ *  Checked as a grammar IN ADDITION to the tree's own bound names, because the collision that
+ *  matters is the one the tree cannot show: `localNames` DROPS a local whose name a written
+ *  global already claims, so where the global is stored `tree.locals` is silent about it. The
+ *  price is refusing a real global that happens to be named `v3` in a function that never mints
+ *  one — measured at zero: over the benchmark corpus, in each row's own symbol world, no candidate
+ *  references such a name, and no vendored symbol map on that sweep's checkouts contained one. The
+ *  map's own name total is deliberately not quoted — it is a property of the checkouts the sweep
+ *  ran over rather than of this repo, so nothing here can re-derive it. */
+const EMITTER_NAME = /^[avt]\d+$/;
+
+/** Why a name the candidate's tree references got NO declaration. Reported rather than silently
+ *  applied, because an undeclared name and a REFUSED one produce the same `'x' undeclared` from
+ *  the compiler and only the second one is asmlift's own decision. Same argument as `onEnumerationError`
+ *  one screen down: a refusal nobody can see is indistinguishable from a capability that was
+ *  never there.
+ *
+ *  ALL FIVE ARE DECIDED AT ONE POINT (`refsOf`), over the names the collector actually returns
+ *  and AFTER the map/pool union — so the report and the rendered block are one list read two
+ *  ways. A test applied where a name ENTERS can be undone by the other half of the union, and
+ *  then the report contradicts the block beside it. */
+export type RefusedDeclarationReason =
+  | 'not-an-identifier' // a relocation name like `$L1` / `.rodata.str1`
+  | 'reserved' // a name `extern u32 <name>;` cannot declare (DECL_RESERVED)
+  | 'call-target' // the name is some call's target: `void F(void);` hard-errors over args
+  | 'self-name' // the function's own name — its definition already declares it
+  | 'emitter-name'; // a name the emitted C uses for its OWN locals and parameters
+
+/** The globals a candidate names because its own asm named them, as name-only `SymbolInfo`s —
+ *  half of the declaration-synthesis dictionary (the symbol map, where there is one, is the other).
+ *
+ *  asmlift does not need a map to EMIT a symbol name: the Thumb frontend reads it out of the
+ *  `.s` file's own literal pool (`.word gBgTilemapBufs` → `gaddr`, thumb.ts's pool grammar) and
+ *  the MIPS frontend out of an object relocation, and structure() spells such a `gaddr` as
+ *  `&gSym`. So the invariant "a candidate's source only names symbols the map knows" is FALSE,
+ *  and a consumer that compiles candidates OUTSIDE the project's own headers (the playground)
+ *  needs these declarations or every candidate fails with "`gSym' undeclared".
+ *
+ *  `kind: 'data'` unconditionally: `code: true` is set only where a symbol MAP said so
+ *  (frontend/thumb.ts), so map-less the IR cannot tell a function pointer from a data address —
+ *  and it does not need to. structure() spells a `code`-less `gaddr` as `&Name`, and `&Name`
+ *  under `extern u32 Name;` is the relocated address whatever Name really is.
+ *
+ *  NOTHING IS REFUSED HERE, deliberately: a name this walk drops is a name the union above it
+ *  could put straight back. Every refusal is decided once, over the collector's output, in
+ *  `refsOf` (see `RefusedDeclarationReason`).
+ *
+ *  A declaration built from this half is a HYPOTHESIS, and where `bareGlobalAccessFacts` gives it
+ *  a width that width came out of the asm the candidate is scored against. The marker is
+ *  `SymbolRef.synthesized`; the argument, and its price against the vendored maps, is declare.ts's
+ *  module note. */
+export function bareGlobalSymbols(fn: Fn): Map<string, SymbolInfo> {
+  const out = new Map<string, SymbolInfo>();
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      if (op.opcode === 'gaddr' && typeof op.attrs.sym === 'string') {
+        out.set(op.attrs.sym, { name: op.attrs.sym, kind: 'data' });
+      }
+    }
+  }
+  return out;
+}
+
+/** The reference collector one enumeration uses, over ONE dictionary. A factory rather than a
+ *  free function because all four of its inputs are per-enumeration constants that must not vary
+ *  per tree — naming them here is what keeps a caller from passing a different dictionary to two
+ *  spellings of the same row.
+ *
+ *  ALL FIVE REFUSALS ARE DECIDED AT THIS ONE POINT, over the names the collector actually returns
+ *  and AFTER the map/pool union — so the report and the rendered declaration block are one list
+ *  read two ways. A test applied where a name ENTERS can be undone by the other half of the union,
+ *  and then the report contradicts the block beside it. */
+export function makeRefCollector(ctx: {
+  /** the union the declarations are synthesized from: pool/reloc names, the shapes the asm
+   *  evidences for them, and the project map — in increasing authority */
+  declSymbols: Map<string, SymbolInfo>;
+  /** the IR-derived width/signedness authority for a name-only symbol's declaration */
+  accessFacts: ReadonlyMap<string, { width: number; signed: boolean }>;
+  /** the project map alone — a name it does NOT know makes the ref a `synthesized` hypothesis */
+  mapSymbols: ReadonlyMap<string, SymbolInfo> | undefined;
+  /** reports a refusal at most once per (name, reason); the caller owns the dedup */
+  refuse: (name: string, reason: RefusedDeclarationReason) => void;
+}): (tree: SFn) => { symbolRefs?: SymbolRef[] } {
+  const { declSymbols, accessFacts, mapSymbols, refuse } = ctx;
+  return (tree: SFn): { symbolRefs?: SymbolRef[] } => {
+    // The names THIS tree binds. Computed per tree because the emitter mints local names per
+    // spelling — but the test below is NOT `bound` alone, and the difference is a wrong answer.
+    const bound = new Set<string>([...tree.params.map((p) => p.name), ...tree.locals.map((l) => l.name)]);
+    const refs = collectSymbolRefs(tree.body, declSymbols, tree.name, refuse).flatMap((r) => {
+      // THE ONE REFUSAL THAT IS NOT A REFUSAL — a name the emitted C uses for its OWN storage
+      // kills the SPELLING, because no declaration makes that candidate right and no declaration
+      // makes it fail either. Two shapes, and the second is why the test is the emitter's whole
+      // NAME GRAMMAR rather than this tree's bound set:
+      //   READ — the tree binds `v0` and also spells `&v0` for the pool global. The local
+      //     shadows the extern, so the candidate takes a stack address where the asm takes a
+      //     relocated one. Withholding the declaration does not stop it compiling: its SIBLING
+      //     names still get theirs, and the TU builds.
+      //   WRITE — structure.ts drops a local whose name a WRITTEN global already claims
+      //     (`localNames`, filtered by `globalNames`), so the collision is INVISIBLE in
+      //     `tree.locals`: every use of the emitter's local binds the extern instead, and the
+      //     loop pointer it was holding becomes a store to that global once per iteration.
+      // Both compile, both are wrong, and a compiling wrong answer is the one outcome this
+      // project trades nothing for — so the spelling dies here and `respellTree`'s catch reports it.
+      // If every spelling of every tree dies, the row declines LOUDLY naming the collision.
+      if (bound.has(r.name) || EMITTER_NAME.test(r.name)) {
+        refuse(r.name, 'emitter-name');
+        throw new Error(
+          `cannot spell '${tree.name}': the target names a global '${r.name}', which is a name the ` +
+            `emitted C uses for its own locals and parameters — no declaration can bind it`,
+        );
+      }
+      // Applied to the UNION, not to the pool half on its way in: a map can supply `$LC0` or
+      // `abort` as readily as a relocation can, and `extern u32 abort;` is the same hard error
+      // whichever half it came from.
+      if (!/^[A-Za-z_]\w*$/.test(r.name)) {
+        refuse(r.name, 'not-an-identifier');
+        return [];
+      }
+      if (DECL_RESERVED.has(r.name)) {
+        refuse(r.name, 'reserved');
+        return [];
+      }
+      // 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;
+      // A ref no MAP accounts for is a hypothesis read out of the target asm, and it is marked
+      // as one all the way to the consumer (SymbolRef.synthesized).
+      const synthesized = mapSymbols?.has(r.name) ? {} : { synthesized: true as const };
+      return [{ ...r, ...(access ? { access } : {}), ...synthesized }];
+    });
+    return refs.length ? { symbolRefs: refs } : {};
+  };
+}