@asmlift/core 0.9.0 → 0.10.0

package/src/runtime-helpers.ts

@@ -29,9 +29,10 @@
 // REGISTERS the list occupies, and `irWidthOf` gives the IR width one parameter ARRIVES at once a
 // frontend has paired those registers up.
 import { type Op, type Value, mkOp } from './ir/core';
-import { FLOAT_OPS, type Opcode, WIDE_BITS } from './ir/opcodes';
+import { FLOAT_COMPUTING, FLOAT_TO_INT, INT_TO_FLOAT, NEGATED_FCMP, type Opcode, WIDE_BITS } from './ir/opcodes';
 import { type IrType, intWidth } from './ir/types';
 import { type Prototypes, wordsOf } from './proto';
+import type { TargetDescription } from './target';
 
 export interface RuntimeHelper {
   /** the op this helper computes, where asmlift has one. Absent for a helper it can only SIGN. */
@@ -40,6 +41,19 @@ export interface RuntimeHelper {
   params: readonly number[];
   /** the returned width: 0 (void), 32, or 64 (a register PAIR). */
   returns: 0 | 32 | 64;
+  /** A THREE-WAY FLOAT COMPARE: its result's SIGN orders its two operands (negative, zero, positive
+   *  for less, equal, greater), and this is the value it returns where either is a NaN. A compare
+   *  folds through the integer test its caller applies to the result (raise/floathelpers.ts), so it
+   *  carries this in place of an `op`. */
+  unordered?: 1 | -1;
+  /** THE RELATION THE SOURCE SPELLED, for a compare helper whose relation and its negation are both
+   *  C operators — `__eqsf2` for `==`, `__nesf2` for `!=`. agbcc's gcc folds `!(a == b)` into
+   *  `a != b` before it picks a helper, so the helper names the relation the source wrote, and a
+   *  lift that spells its negation (or the negation's `!`) recompiles to the other helper. The fold
+   *  stamps it on the compare as `attrs.relation` (raise/floathelpers.ts), and the structurer keeps
+   *  that relation's spelling by choosing the arm order instead (l3/ast.ts `Expr.helperRel`). The
+   *  ordered four need none: `!(a > b)` keeps `__gtsf2`, and no other helper computes it. */
+  relation?: 'fcmp_oeq' | 'fcmp_une';
 }
 
 /** The entry a target's table holds for `callee`, or undefined. THE ONE READER, because the table
@@ -118,19 +132,34 @@ export function helperOp(opcode: Opcode, helper: string, operands: readonly Valu
   return mkOp(opcode, { operands: [...operands], results: [result], attrs: { helper } });
 }
 
-/** Whether a helper computes on floats: its op is a float op, so its operands and result are floats
- *  of the widths its signature states, carried in integer registers by a soft-float runtime. Every
- *  reader of the table asks this and not the width, because the two families fold into different
- *  IR: an integer helper into its op over the same values, a float helper into a float op over
- *  values re-typed as floats (`raise/floathelpers.ts`). */
+/** Whether a helper computes on floats: its op is a float op, a conversion or a compare, so the
+ *  operands and the result that op takes as floats are floats of the widths its signature states,
+ *  carried in integer registers by a soft-float runtime. Every reader of the table asks this and
+ *  not the width, because the two families fold into different IR: an integer helper into its op
+ *  over the same values, a float helper into its op over values re-typed as floats where the op
+ *  takes one (`raise/floathelpers.ts`). */
 export function isFloatHelper(h: RuntimeHelper): boolean {
-  return h.op !== undefined && FLOAT_OPS.has(h.op);
+  return h.unordered !== undefined || (h.op !== undefined && FLOAT_COMPUTING.has(h.op));
+}
+
+/** Which sides of a float helper are floats: its operands (one kind for all of them, in every op
+ *  here) and its result. A conversion has an integer on one side; a compare returns one. */
+export function floatSidesOf(h: RuntimeHelper): { operands: boolean; result: boolean } {
+  const op = h.op ?? '';
+  return {
+    operands: !INT_TO_FLOAT.has(op),
+    result: h.unordered === undefined && !FLOAT_TO_INT.has(op) && NEGATED_FCMP[op] === undefined,
+  };
 }
 
 /** Signatures for a target's helpers, in the WORD arity the frontend's prototype lookup speaks.
  *  Consumed behind any caller-supplied prototype — the project's own headers win. */
-export function helperPrototypes(table: Readonly<Record<string, RuntimeHelper>> | undefined): Prototypes {
-  return Object.fromEntries(Object.entries(table ?? {}).map(([sym, h]) => [sym, { params: wordsOf(h.params) }]));
+export function helperPrototypes(
+  target: Pick<TargetDescription, 'runtimeHelpers' | 'evenWordAlignedArgs'>,
+): Prototypes {
+  return Object.fromEntries(
+    Object.entries(target.runtimeHelpers ?? {}).map(([sym, h]) => [sym, { params: wordsOf(h.params, target) }]),
+  );
 }
 
 /** agbcc's runtime, which is GCC 2.9's libgcc for ARM.
@@ -142,20 +171,32 @@ export function helperPrototypes(table: Readonly<Record<string, RuntimeHelper>>
  *  operand SET-UP instead — `asr rN,rM,#31` per half for signed, `mov rN,#0` for unsigned. The
  *  DIVISIONS do split, and their entries say so.
  *
- *  THE DOUBLE ARITHMETIC IS HERE, AND NOTHING ELSE OF THE SOFT FLOAT. `optabs.c:4022`
- *  `init_floating_libfuncs` names DFmode's add, sub, mul, div (4129-4140) and neg (4155), and
- *  `thumb.md` has no DF pattern but the move, so every one of them is a call; the ABI is a long
- *  long's (thumb.h:632, 655). `raise/floathelpers.ts` folds them to the float ops over a `double`.
+ *  THE FLOAT ARITHMETIC OF BOTH PRECISIONS IS HERE, AND FOLDS. `optabs.c:4022`
+ *  `init_floating_libfuncs` names each mode's add, sub, mul, div (4129-4140) and neg (4155), and
+ *  `thumb.md` has no SF or DF pattern but the move, so every one of them is a call; a single
+ *  travels as an int's word and a double as a long long's pair (thumb.h:632, 655).
+ *  `raise/floathelpers.ts` folds them to the float ops over a `float` or a `double`.
  *
- *  NAMING THEM IS A TRADE, and these five make it: a call the fold refuses declines where an
- *  unnamed helper would publish as a pass-through that matches for free. So a function whose
- *  double arithmetic feeds a compare (`__gtdf2`…), a conversion (`__fixdfsi`…) or any other call
- *  declines, where unnamed it would print `__muldf3(); return __fixdfsi();`. The compares and
- *  conversions of both precisions stay out, because the IR has no int<->float op to fold one into;
- *  the single-precision arithmetic stays out because its pass-throughs are what the float rows
- *  score on (`synthetic:fadd:agbcc`), and declining them is the same trade, to be made with a
- *  measurement of those rows. Making it is a table row: the fold reads each value's width off the
- *  signature. */
+ *  NAMING THEM IS A TRADE, and these ten make it: a call the fold refuses declines where an unnamed
+ *  helper would publish as a pass-through. So a function whose float arithmetic feeds a compare, a
+ *  conversion or an ordinary call declines, where unnamed it would print `__muldf3(); g();`. For
+ *  the singles that pass-through is wrong C: unnamed, `__mulsf3`'s arity is GUESSED (frontend/ssa.ts
+ *  `fallbackArgc`), and a guess drops what the function passes on unchanged — `a * b + c` as
+ *  `__addsf3(__mulsf3(), a2)`, `a + b` as `__addsf3()`.
+ *
+ *  THE CONVERSIONS FOLD TOO, to the cast each computes (`fptosi`, `sitofp`, `fpext` …), with an
+ *  integer on one side that `raise/floathelpers.ts` takes as any integer. THE COMPARES fold through
+ *  the test their caller applies to the integer they return, by libgcc's contract for it
+ *  (`unordered`), and one whose result is read any other way refuses (`refuseUnmodelledHelpers`).
+ *  Unnamed, each would be the same guess, dropping the argument passed on unchanged and matching
+ *  byte for byte: `(int)x` as `__fixsfsi()`, `(float)i` as `__floatsisf()`, `a > b` as
+ *  `__gtsf2() > 0`. The names are the ones agbcc
+ *  emits for every compare, every conversion between `int`, `unsigned`, `long long` and either
+ *  precision, and every widening and narrowing between the two precisions (compiled evidence: one
+ *  function per operation at the canonical flags). There is no conversion of an unsigned integer
+ *  INTO a float: agbcc open-codes `(float)u` around `__floatsisf` and `__addsf3`. `__cmpdi2`, which
+ *  it also calls converting an `unsigned long long`, is an integer compare and outside this
+ *  family. */
 export const AGBCC_RUNTIME_HELPERS: Readonly<Record<string, RuntimeHelper>> = {
   // 32-bit software division — the ops `raise/softdiv.ts` rewrites, gated on the target having no
   // hardware divider, which is what those four are about.
@@ -180,6 +221,45 @@ export const AGBCC_RUNTIME_HELPERS: Readonly<Record<string, RuntimeHelper>> = {
   __muldf3: { op: 'fmul', params: [64, 64], returns: 64 },
   __divdf3: { op: 'fdiv', params: [64, 64], returns: 64 },
   __negdf2: { op: 'fneg', params: [64], returns: 64 },
+  // Single arithmetic, one float in one register each way (thumb.h:632's word).
+  __addsf3: { op: 'fadd', params: [32, 32], returns: 32 },
+  __subsf3: { op: 'fsub', params: [32, 32], returns: 32 },
+  __mulsf3: { op: 'fmul', params: [32, 32], returns: 32 },
+  __divsf3: { op: 'fdiv', params: [32, 32], returns: 32 },
+  __negsf2: { op: 'fneg', params: [32], returns: 32 },
+  // The compares, one int out of two floats of either precision, each libgcc's three-way
+  // `__fpcmp_parts` when both are ordered (fp-bit.c:1117-1188). On a NaN each returns the value its
+  // own relation tests FALSE on — `== 0`, `< 0`, `<= 0` are false on 1, `> 0`, `>= 0` on -1 — except
+  // `__nesf2`, whose 1 makes `!=` true (fp-bit.c:1214-1309). agbcc tests the result against 0 with
+  // the relation the helper is named for.
+  __eqsf2: { params: [32, 32], returns: 32, unordered: 1, relation: 'fcmp_oeq' },
+  __nesf2: { params: [32, 32], returns: 32, unordered: 1, relation: 'fcmp_une' },
+  __gtsf2: { params: [32, 32], returns: 32, unordered: -1 },
+  __gesf2: { params: [32, 32], returns: 32, unordered: -1 },
+  __ltsf2: { params: [32, 32], returns: 32, unordered: 1 },
+  __lesf2: { params: [32, 32], returns: 32, unordered: 1 },
+  __eqdf2: { params: [64, 64], returns: 32, unordered: 1, relation: 'fcmp_oeq' },
+  __nedf2: { params: [64, 64], returns: 32, unordered: 1, relation: 'fcmp_une' },
+  __gtdf2: { params: [64, 64], returns: 32, unordered: -1 },
+  __gedf2: { params: [64, 64], returns: 32, unordered: -1 },
+  __ltdf2: { params: [64, 64], returns: 32, unordered: 1 },
+  __ledf2: { params: [64, 64], returns: 32, unordered: 1 },
+  // The conversions: to and from a word, to and from a long long, and between the precisions.
+  // `__fix*` truncates toward zero, as C's conversion out of a float does.
+  __fixsfsi: { op: 'fptosi', params: [32], returns: 32 },
+  __fixunssfsi: { op: 'fptoui', params: [32], returns: 32 },
+  __floatsisf: { op: 'sitofp', params: [32], returns: 32 },
+  __fixdfsi: { op: 'fptosi', params: [64], returns: 32 },
+  __fixunsdfsi: { op: 'fptoui', params: [64], returns: 32 },
+  __floatsidf: { op: 'sitofp', params: [32], returns: 64 },
+  __fixsfdi: { op: 'fptosi', params: [32], returns: 64 },
+  __fixunssfdi: { op: 'fptoui', params: [32], returns: 64 },
+  __floatdisf: { op: 'sitofp', params: [64], returns: 32 },
+  __fixdfdi: { op: 'fptosi', params: [64], returns: 64 },
+  __fixunsdfdi: { op: 'fptoui', params: [64], returns: 64 },
+  __floatdidf: { op: 'sitofp', params: [64], returns: 64 },
+  __extendsfdf2: { op: 'fpext', params: [32], returns: 64 },
+  __truncdfsf2: { op: 'fptrunc', params: [64], returns: 32 },
 };
 
 /** CodeWarrior's PowerPC runtime (`Runtime.PPCEABI.H`), as the GameCube projects vendor it.
@@ -220,6 +300,44 @@ export const PPC_MWCC_RUNTIME_HELPERS: Readonly<Record<string, RuntimeHelper>> =
   __shr2u: { op: 'shr_u', params: [64, 32], returns: 64 },
 };
 
+/** A compiler runtime's OUT-OF-LINE REGISTER SAVE AND RESTORE ROUTINES: a prologue that saves a run
+ *  of callee-saved registers by calling into the runtime instead of storing each one inline. A
+ *  compiler fact, like the table above, and it hangs off `TargetDescription` for the same reason:
+ *  which compiler emits the family, at which level, is measured per build, and a frontend that
+ *  hard-coded the names would recognise them on a target whose runtime has no such routine.
+ *
+ *  A call to one is FRAME BOOKKEEPING, not a call: it writes no register but the link register, and
+ *  the frame address in `frameReg` is the only thing it reads (frontend/ppc.ts `saveRoutine`). */
+export interface RegisterSaveRoutines {
+  /** the register a routine takes its frame address in. The save area is the words just BELOW it. */
+  frameReg: string;
+  /** every routine name, with three groups: `save` or `rest`, the register file (`gpr`/`fpr`), and
+   *  the first register the routine moves — it moves that one up to the file's last, 31. */
+  name: RegExp;
+}
+
+/** The routine a callee symbol names under `routines`, or null when it names none. */
+export function registerSaveRoutineOf(
+  routines: RegisterSaveRoutines | undefined,
+  sym: string,
+): { sym: string; restore: boolean; fpr: boolean; first: number } | null {
+  const m = routines?.name.exec(sym);
+  return m ? { sym: m[0], restore: m[1] === 'rest', fpr: m[2] === 'fpr', first: Number(m[3]) } : null;
+}
+
+/** CodeWarrior's `_savegpr_NN` / `_restgpr_NN` and `_savefpr_NN` / `_restfpr_NN`, called after
+ *  `addi r11,r1,N`. `_savegpr_NN` stores rNN..r31 into the 4*(32-NN) bytes just below r11, and
+ *  `_savefpr_NN` stores fNN..f31 into the 8*(32-NN) bytes below it.
+ *
+ *  COMPILED, per build: 2.4.2 and 2.4.7 emit the family at every level (`-O4,p`, `-O4,s`, `-O0,p`).
+ *  2.3.3 never does at Pikmin's `-O4,p`, where it saves with `stmw` and inline `stfd`, but does at
+ *  `-O0,p` and `-O4,s`; all three builds share `PPC_MWCC`, so the description carries it. The bench's
+ *  feature tagger reads this same pattern (apps/benchmark `features.ts`). */
+export const PPC_MWCC_SAVE_ROUTINES: RegisterSaveRoutines = {
+  frameReg: 'r11',
+  name: /^_(save|rest)(gpr|fpr)_(\d+)$/,
+};
+
 /** IDO 7.1's runtime for the 64-bit operations MIPS II has no instruction for, a family of its own
  *  (`__ll_*` for signed, `__ull_*` for unsigned): a scan for `__*di3` reports zero on it.
  *

package/src/structure/analysis.ts

@@ -892,7 +892,7 @@ export interface AnalyzeOptions {
    *  A compiler behavior (TargetDescription.compilerBehaviors `readsStayWhereWritten`), not
    *  a differ-refereed variation, and that distinction is the argument: a variation exists where the asm
    *  UNDERDETERMINES the source, some pass having collapsed two spellings onto one output
-   *  (`/uns-cmp`'s non-negativity proof is the type case). Where the compiler emits a read in the
+   *  (`/signed-cmp`'s non-negativity proof is the type case). Where the compiler emits a read in the
    *  block the source spelled it in, re-spelling it at the block the asm read in reproduces that
    *  asm while the sunk spelling is one it emits only for a source that read per arm — nothing for
    *  the differ to referee, and the extra candidate is pure cost. Which compilers may declare
@@ -1521,6 +1521,9 @@ interface LoopRules {
   /** The def's value enters some loop's header live and every consumer sits outside that loop, as
    *  does the def: the value is carried ACROSS the loop, not into it. */
   liveAcrossLoop(def: Op, r: Value, consumers: Op[]): boolean;
+  /** `liveAcrossLoop`, and neither the def nor any consumer sits in any loop, enclosing ones
+   *  included: never a value the compiler could have hoisted out of one. */
+  carriedPastLoops(def: Op, r: Value, consumers: Op[]): boolean;
   /** Does `r`, computed by `op` in `L`'s body, read a loop variable the update overwrites? */
   readsPreUpdate(L: BottomTestedLoop, op: Op, r: Value): boolean;
   escapesAheadOfUpdate(op: Op, r: Value, consumers: Op[]): boolean;
@@ -1551,6 +1554,9 @@ function makeLoopRules(a: {
         !L.body.has(opBlock.get(def)!) &&
         consumers.every((c) => !L.body.has(opBlock.get(c)!)),
     );
+  const carriedPastLoops = (def: Op, r: Value, consumers: Op[]): boolean =>
+    liveAcrossLoop(def, r, consumers) &&
+    loopBodies.every((L) => !L.body.has(opBlock.get(def)!) && consumers.every((c) => !L.body.has(opBlock.get(c)!)));
   /** THE PRE-UPDATE ESCAPE. A value a bottom-tested loop computes and the code after it reads,
    *  whose expression reads a loop variable — `do { s = &f->v; f = f->next; } while (--n); *out =
    *  s;`. Inlined at the post-loop read it re-reads that variable's NAME, which by then holds the
@@ -1710,6 +1716,7 @@ function makeLoopRules(a: {
     multiBlockHeaders,
     bottomTested,
     liveAcrossLoop,
+    carriedPastLoops,
     readsPreUpdate,
     escapesAheadOfUpdate,
     rebuiltPast,
@@ -2042,6 +2049,20 @@ function namePureOp(rules: MaterializeRules, state: MaterializeState, op: Op, b:
   } else if (op.opcode !== 'const' && pr && copyInterdependent.has(pr) && !scopes.addressCone(op)) {
     materialize.add(op);
   }
+  // A PURE VALUE CARRIED ACROSS A LOOP, computed and read outside every loop, as `nameAccess` names
+  // a read (`carriedPastLoops`; a value read inside a loop is `/expr-home`'s question, where loop.c's
+  // invariant motion may have put it). `j = n * 3; for (…) { if (t[i] == 7) { gHit = j; break; } }`
+  // computes `j` ahead of the loop and holds it in a register to the break arm, which sits outside
+  // the natural loop. Inlined, `gHit = n * 3` moves the computation into the arm, and every profile
+  // compiles it there (IDO scores the two alike). A `const` is re-materialized where it is used, and
+  // an address loses its inline byte-stride cast standing alone and is what a compiler CSEs and
+  // moves freely, so neither is named.
+  if (op.opcode !== 'const' && pr && useSitesOf.has(pr) && !scopes.addressCone(op) && !rendersAsAddress(op)) {
+    const cons = [...new Set((useSitesOf.get(pr) ?? []).map((s) => s.op))];
+    if (loops.carriedPastLoops(op, pr, cons)) {
+      materialize.add(op);
+    }
+  }
   // A float PRODUCT read by a float add or subtract, directly or through a negation, is named
   // on a compiler that contracts (target.ts `contractsFloatProducts`): it fuses only WITHIN
   // one expression, so the inline `a * b + c` recompiles to one `fmadds` — one rounding, a
@@ -2248,7 +2269,7 @@ function isBarrier(rules: MaterializeRules, materialize: ReadonlySet<Op>, access
   // order is the compiler's to choose (`gY = VCOUNT - TM0CNT_L` reads VCOUNT first); a
   // qualified read spelled as a bare statement because nothing uses it is an access too.
   if (once && !isCall && (x.opcode === 'load' || x.opcode === 'aload') && counted(x)) {
-    return true;
+    return !interchangeableReads(rules, x, op);
   }
   if (!isCall) {
     return false;
@@ -2261,6 +2282,148 @@ function isBarrier(rules: MaterializeRules, materialize: ReadonlySet<Op>, access
   return false;
 }
 
+const COMMUTATIVE_OPS: ReadonlySet<string> = new Set(['add', 'mul', 'and', 'or', 'xor']);
+
+/** One op's identity apart from its operands: opcode, result count and attributes, keys sorted. */
+const opShape = (op: Op): string =>
+  `${op.opcode}/${op.results.length}/${JSON.stringify(Object.entries(op.attrs).sort(([a], [b]) => a.localeCompare(b)))}`;
+
+/** Do two values name the same address: one value, or two `gaddr`s of one symbol? */
+function sameAddress(defOf: Map<Value, Op>, a: Value, b: Value): boolean {
+  if (a === b) {
+    return true;
+  }
+  const da = defOf.get(a);
+  const db = defOf.get(b);
+  return (
+    da !== undefined &&
+    db !== undefined &&
+    da.opcode === 'gaddr' &&
+    db.opcode === 'gaddr' &&
+    opShape(da) === opShape(db)
+  );
+}
+
+/** Are two qualified reads of ONE cell interchangeable in the one expression they feed: the same
+ *  access of the same address, each the sole use of its value up a chain of ops alike but for it,
+ *  the two chains meeting as the two operands of one commutative op? Then the expression's value is
+ *  the same whichever read the compiler makes first, and its order is the compiler's to choose:
+ *  `gR + gR` over `extern volatile u32 gR;` and `*gPV + *gPV` over `u16 *volatile gPV` read the
+ *  object twice, in an order the source never stated, so naming the first read into a temp spells
+ *  an order the source did not have (ido 7.1 loads `gR + gR` in the other order). The meeting op
+ *  may also be a sum both reads enter with one sign, past a reassociation (`sameSignInOneSum`).
+ *  `gR - gR` is not symmetric — the order decides which read is the minuend — and stays sequenced.
+ *  `a` is the later read, `b` the earlier one placed past it. */
+function interchangeableReads(rules: MaterializeRules, a: Op, b: Op): boolean {
+  const { defOf } = rules;
+  if (
+    a === b ||
+    opShape(a) !== opShape(b) ||
+    a.operands.length !== b.operands.length ||
+    !a.operands.every((v, i) => sameAddress(defOf, v, b.operands[i]))
+  ) {
+    return false;
+  }
+  return mirroredChains(rules, a, b) || sameSignInOneSum(rules, b, a);
+}
+
+/** The two reads' sole-use chains are alike but for them and meet as the two operands of one
+ *  commutative op: `(gR << 1) * (gR << 1)`. */
+function mirroredChains(rules: MaterializeRules, a: Op, b: Op): boolean {
+  const { useSitesOf } = rules.uses;
+  let ca = a;
+  let cb = b;
+  for (let depth = 0; depth < 8; depth++) {
+    const va = ca.results[0];
+    const vb = cb.results[0];
+    const ua = va === undefined ? undefined : useSitesOf.get(va);
+    const ub = vb === undefined ? undefined : useSitesOf.get(vb);
+    if (ua?.length !== 1 || ub?.length !== 1) {
+      return false;
+    }
+    const na = ua[0].op;
+    const nb = ub[0].op;
+    if (na === nb) {
+      return (
+        COMMUTATIVE_OPS.has(na.opcode) &&
+        na.successors.length === 0 &&
+        na.operands.length === 2 &&
+        ((na.operands[0] === va && na.operands[1] === vb) || (na.operands[0] === vb && na.operands[1] === va))
+      );
+    }
+    if (
+      opShape(na) !== opShape(nb) ||
+      na.successors.length > 0 ||
+      nb.successors.length > 0 ||
+      (MEM_BASE_OPS.has(na.opcode) && counted(na)) ||
+      na.operands.length !== nb.operands.length ||
+      !na.operands.every((v, i) => (v === va ? nb.operands[i] === vb : v === nb.operands[i] && v !== vb))
+    ) {
+      return false;
+    }
+    ca = na;
+    cb = nb;
+  }
+  return false;
+}
+
+/** Each read's sole-use chain up through `add`/`sub` ops, as the ops it passes and the read's sign in
+ *  each: entering an `add`, or a `sub` as its minuend, keeps the sign; entering a `sub` as its
+ *  subtrahend flips it. The value of every op on the chain is then that sign times the read, plus
+ *  terms the read is not in. */
+function additiveChain(rules: MaterializeRules, read: Op): Map<Op, { sign: number; operand: number }> {
+  const { useSitesOf } = rules.uses;
+  const chain = new Map<Op, { sign: number; operand: number }>();
+  let v = read.results[0];
+  let sign = 1;
+  for (let depth = 0; depth < 8 && v !== undefined; depth++) {
+    const uses = useSitesOf.get(v);
+    if (uses?.length !== 1) {
+      break;
+    }
+    const n = uses[0].op;
+    const operand = n.operands.indexOf(v);
+    if (
+      (n.opcode !== 'add' && n.opcode !== 'sub') ||
+      n.operands.length !== 2 ||
+      n.results.length !== 1 ||
+      n.successors.length > 0 ||
+      n.operands.lastIndexOf(v) !== operand
+    ) {
+      break;
+    }
+    sign = n.opcode === 'sub' && operand === 1 ? -sign : sign;
+    chain.set(n, { sign, operand });
+    v = n.results[0];
+  }
+  return chain;
+}
+
+/** The two reads meet in one sum with the same sign: their sole-use chains run through `add`/`sub`
+ *  ops only, to an op one reaches through each operand, where each counts with the same sign. The
+ *  sum is then the same whichever read is made first, however the compiler reassociated it:
+ *  ido 7.1 compiles `(gR - x) + (gR - x)` as `((gR - x) + gR) - x`, where one read passes a `sub`
+ *  before the `add` they meet in and the other does not, so the chains are not mirrored. `gR - gR`
+ *  meets with opposite signs and stays sequenced. Wrapping arithmetic keeps the sum associative.
+ *  The value is then right in either order, but the match is not: the earlier read must also be
+ *  the one the expression spells first, entering the meeting op as its left operand, or a compiler
+ *  that reads operands left to right reverses the asm's two loads. mwcc 2.4.2 reads
+ *  `gMS.f + ((t + gMS.f) + t)`'s right-hand `gMS.f` first, so spelling both in one expression
+ *  there puts the asm's second load first. */
+function sameSignInOneSum(rules: MaterializeRules, earlier: Op, later: Op): boolean {
+  const ofEarlier = additiveChain(rules, earlier);
+  if (ofEarlier.size === 0) {
+    return false;
+  }
+  for (const [n, inLater] of additiveChain(rules, later)) {
+    const inEarlier = ofEarlier.get(n);
+    if (inEarlier !== undefined) {
+      return inEarlier.operand === 0 && inLater.operand === 1 && inEarlier.sign === inLater.sign;
+    }
+  }
+  return false;
+}
+
 /** The rules for a memory access — a `call`, `load` or `aload` — in order; the first that names
  *  the op ends the walk. */
 function nameAccess(rules: MaterializeRules, state: MaterializeState, op: Op, b: Block): void {

package/src/structure/arith-ops.ts

@@ -0,0 +1,23 @@
+// asmlift structurer — the IR's integer arithmetic opcodes and the L3 operator each one renders
+// as. The float ops are FLOAT_TO_BIN in structure.ts, which says why they are not here.
+import type { BinOp } from '../l3/ast';
+
+export const ARITH_TO_BIN: Record<string, BinOp> = {
+  add: '+',
+  sub: '-',
+  mul: '*',
+  sdiv: '/',
+  // the UNSIGNED quotient/remainder — the C backend spells them `/`/`%` over an operand it casts
+  // unsigned (l3/ast.ts BinOp, backend/cfamily.ts C_SPELLING)
+  udiv: '/u',
+  smod: '%',
+  umod: '%u',
+  or: '|',
+  and: '&',
+  xor: '^',
+  shl: '<<',
+  shr_u: '>>>', // the LOGICAL right shift; the C backend spells it `>>` over an unsigned operand
+  shr_s: '>>',
+  logic_and: '&&',
+  logic_or: '||', // short-circuit connectives (raise/shortcircuit.ts)
+};

package/src/structure/globalaccess.ts

@@ -1,17 +1,29 @@
 // THE GLOBAL-ACCESS ADDRESS DECOMPOSITION — the pure half of the symbol-map access spellings.
 //
-// Everything here is a function of an `Expr`, a `SymbolInfo` and a width: no structurer state, no
-// naming walk, no loop context. It answers three questions the access spellings in structure.ts
-// ask over and over — is this address `&gSym` plus something; does that something divide into
-// whole elements; and do the terms of it name the DECLARED subscripts of a multidimensional array
-// — and it answers them the same way for every caller, which is the point of the split: the
-// rank-pinning fallback and the declared-subscript recovery share `bareArrayElement`, so the two
-// cannot disagree about what a bare element spelling is.
+// Everything here is a function of an `Expr`, the map's declarations and a width: no structurer
+// state, no naming walk, no loop context. It answers three questions the access spellings in
+// structure.ts ask over and over — is this address `&gSym` plus something; does that something
+// divide into whole elements; and do the terms of it name the DECLARED subscripts of a
+// multidimensional array — and it answers them the same way for every caller, which is the point
+// of the split: the rank-pinning fallback and the declared-subscript recovery share
+// `bareArrayElement`, so the two cannot disagree about what a bare element spelling is. The same
+// holds for what the map declares a named member to be (`ptrMemberDecl`), which the access folds
+// and the pointer spelling (pointer-spelling.ts) both read.
 import type { Expr } from '../l3/ast';
-import { type SymbolInfo, arrayInnerExtents } from '../symbols';
+import {
+  type DeclaredField,
+  type SymbolInfo,
+  type SymbolStructField,
+  arrayInnerExtents,
+  declaredFields,
+  isArrayField,
+  isBitfieldField,
+  isPtrField,
+  pointeeFields,
+} from '../symbols';
 
 // `&gSym`, possibly wearing the value-context integer cast the additive lowering adds
-// (`(u32)&gSym` — see `intifyAddr` in structure.ts's lowerDef): both spell the same link-time
+// (`(u32)&gSym` — see `ARITH_ROWS` in pointer-spelling.ts): both spell the same link-time
 // constant, so the fold rules match through the cast and every access that CAN spell a named
 // element still does.
 // WIDTH 32 ONLY — a NARROWING cast (`(u8)&gSym`, from a zext/sext lowering) is a different
@@ -298,3 +310,93 @@ export function addOffset(idx: Expr, n: number): Expr {
     ? { k: 'const', value: idx.value + n }
     : { k: 'bin', op: '+', l: idx, r: { k: 'const', value: n } };
 }
+
+/** May a member be NAMED by an access of this direction, given the qualifiers on its declaration?
+ *  The named spelling REPLACES a cast through `(u8 *)`, which carries no qualifier at all, so a
+ *  qualifier the name reintroduces changes what the compiler emits:
+ *    • `volatile` makes the access observable — the load may no longer be folded or reordered,
+ *      which is a different instruction sequence (measured: 6 insns where the cast form was 5);
+ *    • `const` under a STORE is a hard error, where the cast form merely cast the qualifier away.
+ *  Either way the honest spelling is the cast form, so the member simply is not nameable here. */
+export function memberQualsAllow(f: SymbolStructField, containerConst: boolean | undefined, isStore: boolean): boolean {
+  if (f.volatile) {
+    return false;
+  }
+  return !(isStore && (f.const || containerConst));
+}
+
+/** The member a `width`-byte access at byte `byte` of a struct global names, `gSym.member`: one at
+ *  that offset and of that size, no array or bitfield, whose qualifiers allow the access. An ARRAY
+ *  member would match a byte access by (offset, size) and spell `.x`, which is not an lvalue of
+ *  that width; a plain read of a BITFIELD's bytes is not a read of its bits. */
+export function structMemberAt(
+  si: SymbolInfo,
+  byte: number,
+  width: number,
+  isStore: boolean,
+): DeclaredField | undefined {
+  if (si.shape !== 'struct') {
+    return undefined;
+  }
+  const f = declaredFields(si.layout)?.find(
+    (x) => x.offset === byte && x.size === width && !isArrayField(x) && !isBitfieldField(x),
+  );
+  return f !== undefined && memberQualsAllow(f, si.const, isStore) ? f : undefined;
+}
+
+/** The members a symbol's declaration seats: a struct global's own, or a pointer global's
+ *  pointee's. */
+export interface MemberLookup {
+  fieldsOf(name: string): DeclaredField[] | null;
+}
+
+/** {@link MemberLookup.fieldsOf} over `info`, MEMOIZED per symbol. `declaredFields` validates every
+ *  member and returns a fresh sorted copy on every call, and pointer-spelling.ts's `roleOf`
+ *  asks it for every member operand of every arithmetic op lowered, so an uncached lookup is an
+ *  O(n log n) allocation on a hot path — inside a `structure()` a ranked run repeats once per
+ *  candidate, 17,856 times on the largest fan. */
+export function memoFieldsOf(info: (name: string) => SymbolInfo | undefined): MemberLookup['fieldsOf'] {
+  const cache = new Map<string, DeclaredField[] | null>();
+  return (name) => {
+    const hit = cache.get(name);
+    if (hit !== undefined) {
+      return hit;
+    }
+    const si = info(name);
+    const fields =
+      si?.shape === 'struct' ? declaredFields(si.layout) : si?.shape === 'pointer' ? pointeeFields(si.pointee) : null;
+    cache.set(name, fields);
+    return fields;
+  };
+}
+
+/** The map member a `field` node NAMES, or null when it names none — THE one resolver for "what
+ *  does the declaration say about this member", for rules that must reason about a member's type
+ *  after the access rules have already spelled it. Both named spellings resolve, through the same
+ *  shared gate their spelling passed: `gSym.member` off a struct global's {@link declaredFields},
+ *  `gPtr->member` off the pointee's ({@link pointeeFields}). A synthesized `field_K` — the
+ *  recovered-struct spelling, which no map declares — resolves to null, and so does any base that
+ *  is not a map-shaped global, which is what makes every caller refuse rather than guess.
+ *
+ *  The pointee arm reaches only what the MAP lets it: `pointeeAccess` gates every `gPtr->member`
+ *  spelling on `spellsAccessType(f.signed, …)`, so a pointer field declaring no signedness — which
+ *  is every one in the corpus's vendored maps — is never named, and a pointer read one indirection
+ *  down spells `((s32 *)gQ)[1]`. That is a fact about those maps, not about this code: `SymbolMap`
+ *  is a caller-supplied input, and one field flips it (`signed: true` on a 4-byte pointer member
+ *  of a pointee yields `(u8 *)gQ->pInner`, cast and all, pinned in pointer-members.test.ts). So
+ *  the arm is live and tested, and the byte-arithmetic rule that reads this answer is correct for
+ *  it — where resolving a pointee member to null would reopen the double-scaling hole silently. */
+export function declaredMemberOf(x: Expr, sym: MemberLookup | undefined): DeclaredField | null {
+  if (x.k !== 'field' || x.base.k !== 'var' || sym === undefined) {
+    return null;
+  }
+  return sym.fieldsOf(x.base.name)?.find((f) => f.name === x.name) ?? null;
+}
+
+/** The map member a `field` node names when the declaration makes it a POINTER — {@link
+ *  isPtrField} being the shared two-fact test, so this and the synthesized declaration cannot
+ *  disagree about what a member is. */
+export function ptrMemberDecl(x: Expr, sym: MemberLookup | undefined): DeclaredField | null {
+  const f = declaredMemberOf(x, sym);
+  return f !== null && isPtrField(f) ? f : null;
+}