@asmlift/core 0.5.0 → 0.6.0

package/src/l3/initfirst.ts

@@ -0,0 +1,301 @@
+// L3 re-spelling lever: a loop INIT moves above the guard that encloses it, and the guard reads
+// the initialized variable.
+//
+// `for (i = 0; i < n; i++)` compiles with the init BEFORE the zero-trip test (`mov r3,#0` then
+// `cmp r3, r5`), while `if (0 < n) { i = 0; do … }` compiles with the init behind the branch.
+// Both source forms lift to the SAME IR — a const has no position — so which the original spelled
+// is not recoverable; this lever emits the init-first sibling and the differ referees:
+//
+//     if (0 < n) { v = 0; … }   →   v = 0; if (v < n) { … }
+//
+// Two rewrites (the guard re-spelling gated on the moved write being dead — see SCOPE):
+//   • common-arm hoist — both arms of an `if` begin with the SAME pure-const assign
+//     (`if (c) { v = 0; } else { v = 0; … }`, gcc's inverted-guard shape): the assign moves above
+//     the `if`, and an emptied then-arm flips into its negated else form.
+//   • guard re-spelling — an else-less `if` whose then-arm begins with `v = X` and whose
+//     condition carries X ITSELF as a comparison side: the assign moves above and that side
+//     becomes `v`. X is a const (`for (j = 0; j < n;…)`'s shape) or a pure NON-VOLATILE read
+//     (`for (j = *p; j < size;…)` — guard and init read the same cell back to back, which the
+//     local-spelling source reads ONCE; collapsing the adjacent pair is what the compiler saw).
+//
+// SCOPE (decline over approximate): both rewrites touch PRIVATE locals only — a bare-global
+// assign stores memory other code observes, a VOLATILE local's store is itself observable (the
+// escaped DMA scratch), and a local whose ADDRESS is taken anywhere can be read through the
+// pointer where no name betrays it — all three stay put. The common-arm hoist carries pure
+// CONST values only. A guard re-spell's X must be call-free and marker-free, may mention only
+// the function's own non-volatile params/locals (a global or `&gSym` could be project-declared
+// volatile, and a volatile read may not be deduplicated), and the substitution must PRESERVE
+// THE COMPARE'S MEANING: the variable's declared type can differ from X's rendered type, so the
+// swap is admitted only when both sides were provably non-negative (every signedness reading
+// agrees there) or the compare's rendered signedness is unchanged — anything indeterminate
+// refuses. The condition must not read the variable (its pre-assign value dies in the move)
+// and, for a READ X, must be effect-free as a whole (the hoist moves X's read above it). The
+// guard re-spelling
+// mints a write on a previously write-free path, so it needs that write to be DEAD there: the
+// variable must be untouched after the `if` in its own list and in the tail of every ancestor
+// list (a sibling arm of an ancestor `if` is not "after" — it never runs in the same entry).
+// Under a loop or switch ancestor the tails stop describing what runs next (a back edge
+// re-enters everything, a case can fall through), so there the variable must appear nowhere
+// outside the rewritten `if` at all. Declines (null) when nothing changes.
+import type { Expr, SFn, Stmt } from './ast';
+import { NEGATE_REL, exprChildren, exprEquals, exprHasEffect, stmtChildren, stmtExprs, walkExprs } from './ast';
+import { arithConversionSignedness, declaredTypes, provablyNonNegative } from './typing';
+
+const readsVar = (e: Expr, name: string): boolean =>
+  ((e.k === 'var' || e.k === 'addr') && e.name === name) || exprChildren(e).some((c) => readsVar(c, name));
+
+// READS only — a pure write in a tail is benign (it overwrites the minted value on every path,
+// and any read after it is that write's business); touchesOutside below is TOTAL because strong
+// mode must know the name is absent, presence of any kind included.
+const stmtTouches = (s: Stmt, name: string): boolean =>
+  stmtExprs(s).some((e) => readsVar(e, name)) || stmtChildren(s).some((x) => stmtTouches(x, name));
+
+const isConstAssign = (s: Stmt): s is Extract<Stmt, { k: 'assign' }> & { value: { k: 'const'; value: number } } =>
+  s.k === 'assign' && s.value.k === 'const';
+
+/** Peel value-preserving `(s32)`/`(u32)` casts. Width 32 only: a narrower target truncates. A
+ *  `volatile` cast is never peeled — the qualifier is the access's meaning, and the differ cannot
+ *  referee its loss. */
+const stripWideIntCast = (e: Expr): Expr =>
+  e.k === 'cast' && e.to.kind === 'int' && e.to.width === 32 && e.volatile !== true ? stripWideIntCast(e.e) : e;
+
+/** Every deref rooted at a var through casts only. The var-root rule is a TWO-WORLD argument, not a
+ *  volatility proof: a deref through a plain-declared pointer local may still be MMIO, but the
+ *  /volatile axis enumerates the qualified sibling — where this lever refuses — so both worlds reach
+ *  the differ and collapsing reads here is the plain world's own premise. A raw `*(u16 *)CONST` deref
+ *  has NO local for /volatile to qualify, so no sibling carries the volatile world and the collapse
+ *  would silently discard it. */
+const varRooted = (e: Expr): boolean => (e.k === 'var' ? true : e.k === 'cast' ? varRooted(e.e) : false);
+
+/** A guard re-spell's X: call/marker-free, every named leaf a non-volatile param/local of THIS
+ *  function (a global or `&gSym` could be project-declared volatile), and every deref `varRooted`. */
+const hoistableRead = (e: Expr, ownNames: ReadonlySet<string>, volatileLocals: ReadonlySet<string>): boolean => {
+  if (e.k === 'call' || e.k === 'marker' || e.k === 'addr') {
+    return false;
+  }
+  if (e.k === 'var' && (!ownNames.has(e.name) || volatileLocals.has(e.name))) {
+    return false;
+  }
+  if ((e.k === 'index' || e.k === 'field') && !varRooted(e.base)) {
+    return false;
+  }
+  return exprChildren(e).every((c) => hoistableRead(c, ownNames, volatileLocals));
+};
+
+/** A compare operand and the init's value denote the same 32-bit value under different SPELLINGS
+ *  when a width-32 cast is all that separates them: `/uns-cmp` wraps one side in `(u32)` to make
+ *  the branch unsigned, and on a zero-trip guard that side is the very const the init assigns.
+ *  The swap is still exact — `v = X` stores X's 32 bits and `v` is 32-bit-declared
+ *  (meaningPreserved refuses otherwise), so `v` and `(u32)X` carry the same bit pattern and only
+ *  the compare's rendered signedness can differ, which meaningPreserved checks separately. A
+ *  NARROWING cast changes the value and never matches, and a `volatile` one is not peeled at all. */
+const sameValue = (a: Expr, b: Expr): boolean => exprEquals(stripWideIntCast(a), stripWideIntCast(b));
+
+/** The compare-meaning gate (see SCOPE): substituting `v` for X may change the compare's
+ *  rendered signedness through v's declared type. Sufficiency: v's declared width must be 32
+ *  (the assignment `v = X` then represents any 32-bit-or-narrower X exactly, so v's runtime
+ *  value EQUALS X's — a narrow-declared v would truncate and no signedness reasoning survives
+ *  that), and then (a) both original sides provably in [0, 2^31) ⇒ signed and unsigned
+ *  compares agree on the actual values whatever the swap does to rendered signedness; (b)
+ *  otherwise a defined, UNCHANGED rendered signedness over equal values gives the identical
+ *  result. Anything indeterminate refuses. */
+const meaningPreserved = (
+  l: Expr,
+  r: Expr,
+  side: 'l' | 'r',
+  v: string,
+  env: ReturnType<typeof declaredTypes>,
+): boolean => {
+  const vt = env(v);
+  if (vt?.kind !== 'int' || vt.width !== 32) {
+    return false;
+  }
+  if (provablyNonNegative(l, env) && provablyNonNegative(r, env)) {
+    return true;
+  }
+  const before = arithConversionSignedness(l, r, env);
+  const vv: Expr = { k: 'var', name: v };
+  const after = side === 'l' ? arithConversionSignedness(vv, r, env) : arithConversionSignedness(l, vv, env);
+  return before !== undefined && before === after;
+};
+
+/** TOTAL (reads and pure writes) — see the note on stmtTouches. Runs against the pre-rewrite
+ *  tree (`skip` is an original-tree statement, found by identity); the rewrites never change a
+ *  name's presence in a subtree, so the verdict carries over to the rewritten one. */
+const touchesOutside = (list: Stmt[], skip: Stmt, name: string): boolean =>
+  list.some(
+    (st) =>
+      st !== skip &&
+      (stmtExprs(st).some((e) => readsVar(e, name)) ||
+        (st.k === 'assign' && st.name === name) ||
+        touchesOutside(stmtChildren(st), skip, name)),
+  );
+
+/** Every name whose ADDRESS this function takes anywhere — a local read through the captured
+ *  pointer with no name in sight. */
+function addressTakenNames(sfn: SFn): Set<string> {
+  const taken = new Set<string>();
+  for (const e of walkExprs(sfn.body)) {
+    if (e.k === 'addr') {
+      taken.add(e.name);
+    }
+  }
+  return taken;
+}
+
+export function initFirstGuards(sfn: SFn): SFn | null {
+  let changed = false;
+  // the names both rewrites may move a write of: this function's params and its non-volatile
+  // locals, minus everything whose address escapes
+  const addressTaken = addressTakenNames(sfn);
+  const fnLocal = new Set(
+    [...sfn.params.map((d) => d.name), ...sfn.locals.filter((l) => l.volatile !== true).map((l) => l.name)].filter(
+      (n) => !addressTaken.has(n),
+    ),
+  );
+  const volatileLocals = new Set(
+    sfn.locals.filter((l) => l.volatile === true || l.pointeeVolatile === true).map((l) => l.name),
+  );
+  const ownNames = new Set([...sfn.params.map((p) => p.name), ...sfn.locals.map((l) => l.name)]);
+  const env = declaredTypes(sfn);
+
+  // `tails`: for each ancestor list, the statements after the ancestor on the path here.
+  // `strong`: a loop or switch ancestor exists, so tails stop bounding what runs after.
+  interface Ctx {
+    tails: Stmt[][];
+    strong: boolean;
+  }
+  // Assigns this pass itself hoisted to an arm head's parent list. An ancestor `if` whose arm now
+  // BEGINS with one would otherwise re-spell it again — rewriting its own condition's accidental
+  // matching const into the variable and stealing the arrangement the inner guard needed.
+  const moved = new Set<Stmt>();
+  const rewriteList = (list: Stmt[], ctx: Ctx): Stmt[] => {
+    const out: Stmt[] = [];
+    for (let i = 0; i < list.length; i++) {
+      const s0 = list[i];
+      const s = recurse(s0, { tails: [...ctx.tails, list.slice(i + 1)], strong: ctx.strong });
+      if (s.k !== 'if') {
+        out.push(s);
+        continue;
+      }
+      let { cond, then, else: els } = s;
+      // common-arm hoist
+      const hoisted: { name: string; value: number }[] = [];
+      for (;;) {
+        const t0 = then[0];
+        const e0 = els[0];
+        if (
+          t0 === undefined ||
+          e0 === undefined ||
+          moved.has(t0) ||
+          moved.has(e0) ||
+          !isConstAssign(t0) ||
+          !isConstAssign(e0) ||
+          !fnLocal.has(t0.name) ||
+          t0.name !== e0.name ||
+          t0.value.value !== e0.value.value ||
+          readsVar(cond, t0.name)
+        ) {
+          break;
+        }
+        out.push(t0);
+        moved.add(t0);
+        hoisted.push({ name: t0.name, value: t0.value.value });
+        changed = true;
+        then = then.slice(1);
+        els = els.slice(1);
+      }
+      if (then.length === 0 && els.length > 0) {
+        const neg = cond.k === 'bin' ? NEGATE_REL[cond.op] : undefined;
+        if (neg !== undefined && cond.k === 'bin') {
+          cond = { ...cond, op: neg };
+          [then, els] = [els, then];
+          changed = true;
+        }
+      }
+      // a COMMON-hoisted variable holds its const on both paths, so the condition's matching
+      // const operand reads through it unconditionally — no tail gate needed.
+      // A BARE const only, where the guard re-spelling below uses the cast-tolerant `sameValue`:
+      // this site does not run `meaningPreserved`, so it may not swap in a name whose declared
+      // type could re-render the compare's signedness — which is exactly what peeling a `(u32)`
+      // would put on the table. A row that needs `/uns-cmp`'s spelling hoisted here brings the
+      // gate with it.
+      for (const hv of hoisted) {
+        if (cond.k === 'bin' && NEGATE_REL[cond.op]) {
+          if (cond.l.k === 'const' && cond.l.value === hv.value) {
+            cond = { ...cond, l: { k: 'var', name: hv.name } };
+          } else if (cond.r.k === 'const' && cond.r.value === hv.value) {
+            cond = { ...cond, r: { k: 'var', name: hv.name } };
+          }
+        }
+      }
+      // guard re-spelling — X a const or a hoistable read, matched as a whole comparison side
+      if (
+        els.length === 0 &&
+        then.length > 0 &&
+        then[0].k === 'assign' &&
+        !moved.has(then[0]) &&
+        fnLocal.has(then[0].name) &&
+        cond.k === 'bin' &&
+        NEGATE_REL[cond.op]
+      ) {
+        const init = then[0];
+        const rest = list.slice(i + 1);
+        const side =
+          isConstAssign(init) || hoistableRead(init.value, ownNames, volatileLocals)
+            ? sameValue(cond.l, init.value)
+              ? ('l' as const)
+              : sameValue(cond.r, init.value)
+                ? ('r' as const)
+                : null
+            : null;
+        const deadAfter = ctx.strong
+          ? !touchesOutside(sfn.body, s0, init.name)
+          : !rest.some((t) => stmtTouches(t, init.name)) &&
+            ctx.tails.every((tail) => !tail.some((t) => stmtTouches(t, init.name)));
+        if (
+          side !== null &&
+          !readsVar(cond, init.name) &&
+          deadAfter &&
+          // A READ X's hoist moves its evaluation ABOVE the whole condition, so the condition must
+          // carry no effect it could cross (a call there could write the cell X reads); a CONST
+          // init crosses nothing and keeps the wider admission.
+          (isConstAssign(init) || !exprHasEffect(cond)) &&
+          meaningPreserved(cond.l, cond.r, side, init.name, env)
+        ) {
+          out.push(init);
+          moved.add(init);
+          cond = { ...cond, [side]: { k: 'var', name: init.name } };
+          then = then.slice(1);
+          changed = true;
+        }
+      }
+      out.push({ ...s, cond, then, else: els });
+    }
+    return out;
+  };
+
+  const recurse = (s: Stmt, ctx: Ctx): Stmt => {
+    const strong = { ...ctx, strong: true };
+    switch (s.k) {
+      case 'if':
+        return { ...s, then: rewriteList(s.then, ctx), else: rewriteList(s.else, ctx) };
+      case 'while':
+      case 'dowhile':
+        return { ...s, body: rewriteList(s.body, strong) };
+      case 'for':
+        return { ...s, body: rewriteList(s.body, strong) };
+      case 'switch':
+        return {
+          ...s,
+          cases: s.cases.map((c) => ({ ...c, body: rewriteList(c.body, strong) })),
+          ...(s.default ? { default: rewriteList(s.default, strong) } : {}),
+        };
+      default:
+        return s;
+    }
+  };
+
+  const body = rewriteList(sfn.body, { tails: [], strong: false });
+  return changed ? { ...sfn, body } : null;
+}

package/src/l3/inlinebase.ts

@@ -0,0 +1,193 @@
+// L3 re-spelling lever: DELETE a pointer local holding a CONSTANT address and spell each access
+// through it as the cast constant (`*(u16 *)0x4000208` rather than `p = (u16 *)0x4000208; *p`).
+//
+// The local is structure/analysis.ts's value-home spelling for a `const` with 2+ consumers that
+// is LIVE ACROSS A CALL: a value the compiler needs after a call survives in a callee-saved
+// register, and a named local reproduces that register. The machine fact is real — agbcc does
+// park the address in `r4` across the calls — but it does NOT imply the source named anything:
+// a constant re-spelled at each use is CSEd into the same one register. So the asm
+// underdetermines the spelling, and this is the differ-refereed other side of it.
+//
+// It is codegen-visible, which is why both sides have to be enumerated rather than one picked:
+// the extra `p = …;` statement is scheduled ahead of the rest of the entry block, so the pool
+// load moves in front of the frame-address materialization the target emits first
+// (pokeemerald:EReader_Reset, agbcc 2.9-arm-000512 — 1 insert + 1 delete, the whole residual).
+//
+// SEMANTICS ARE PRESERVED BY CONSTRUCTION: this is constant propagation of a local that is
+// assigned once, from a compile-time constant, before anything mentions it, and whose address is
+// never taken — so every use reads that constant on every path, and the substituted expression
+// carries the local's own declared type AND its pointee volatility.
+//
+// THE QUALIFIER TRAVELS WITH THE ADDRESS. The deleted local is the only place a `volatile`
+// pointee could be written, and a raw address is precisely the case with no declaration
+// anywhere else to carry it — so dropping it here spells an MMIO access non-volatile in the one
+// place the differ sometimes cannot referee. On pokeemerald:EReader_Reset the two spellings
+// separate at 11 against 12 on their own, and are BYTE-IDENTICAL once the slot qualifier is
+// there too — the shape that matches (agbcc 2.9-arm-000512, `-O2 -mthumb-interwork -Wimplicit
+// -fhex-asm -fprologue-bugfix`; `.s` diff empty, `.o` identical under cmp). So rank.ts emits
+// the qualified spelling as a second OUTPUT of this lever, `/volatile` narrowed to the locals
+// it deletes. Each cast this mints carries the qualifier; a use whose width does not stride the
+// declared pointee renders through the C-family printer's reinterpret cast instead, which
+// carries it too (backend/cfamily.ts) — in C the access takes the OUTER type, so a plain cast
+// there would spell exactly the silent drop this paragraph exists to prevent.
+//
+// GATE (INLINEBASE_GATES) — the local must be all of: pointer-typed; initialized by a bare
+// NONZERO `const` (a `(T *)base` CAST initializer is l3/basecse.ts's reuse hoist, whose own lever
+// family owns that question; `0` is NULL, never an address, which is also the sibling qualifier
+// lever's rule); assigned exactly once, by a statement at the body's TOP LEVEL that no earlier
+// statement's mention precedes; never address-taken; used only as the base of an `index`, at 2+
+// sites (one use is not the reused address this exists for); not object-`volatile` (a
+// `T *volatile p` has no inhabitant, and cfamily.ts prints that flag in the pointee's position);
+// and not `frame` (a slot is an asm fact — see the SFn.locals doc). Anything else, and nothing
+// qualifying at all, DECLINES (null) rather than approximating.
+//
+// A RE-SPELLING RATHER THAN A STRUCTURING AXIS, which is a cost choice and not the
+// underdetermination one (docs/level-tower.md, "a third fork sits inside the ranked population").
+// The question — does a `const` with 2+ consumers live across a call in a named local — is the one
+// `/reread-globals`, `/addr-home`, `/expr-home` and `/derived-home` each answer as a
+// STRUCTURING_AXES entry. An axis here would double the enumeration on every function it admits;
+// substituting on the already-homed tree costs 766 candidates over 47058 (+1.6%) across the 33 of
+// 69 klonoa functions that lift with no symbol map.
+//
+// KNOWN GAP, and it is the price of that choice rather than an oversight: only `index` bases are
+// re-spelled, so the same L2 home passed to a callee or standing as a `field` base is out of
+// reach — `otherUses` refuses it. Reaching those needs the un-homed tree, which is
+// structure/analysis.ts's decision; the day a row demands one, this becomes the axis.
+//
+// The idiom it recovers is every GBA project's register macro: `*(vu16 *)0x4000208` is what
+// `REG_IME` expands to, so the deleted local is not merely an undone home.
+import { type Expr, type SFn, mapExprChildren, mapStmtExprs } from './ast';
+import { type Gate, firstRejection } from './gates';
+import { type Mentions, localMentions } from './mentions';
+
+/** One local as the gates read it. */
+interface BaseCtx {
+  isPointer: boolean;
+  objectVolatile: boolean;
+  hasFrame: boolean;
+  m: Mentions;
+}
+
+export const INLINEBASE_GATES: readonly Gate<BaseCtx>[] = [
+  {
+    id: 'non-pointer',
+    why: 'the lever re-spells an address; a scalar value home is a different question',
+    sound: false,
+    rejects: (c) => !c.isPointer,
+  },
+  {
+    id: 'object-volatile',
+    why: 'the substitution carries the POINTEE flag, so an object-volatile pointer would lose its own',
+    sound: true,
+    guardedBy: 'inlinebase.test.ts: an object-volatile or frame local declines',
+    rejects: (c) => c.objectVolatile,
+  },
+  {
+    id: 'frame',
+    why: 'a slot the asm materialized is an asm fact, not a spelling to undo',
+    sound: false,
+    rejects: (c) => c.hasFrame,
+  },
+  {
+    id: 'multi-assign',
+    why: 'a name assigned more than once is not one constant',
+    sound: true,
+    guardedBy: 'inlinebase.test.ts: a second assignment means the name is not one constant',
+    rejects: (c) => c.m.assigns !== 1,
+  },
+  {
+    id: 'const-init',
+    why: 'only a bare `const` at the body’s top level is an address available on every path',
+    sound: true,
+    guardedBy: 'inlinebase.test.ts: an assignment below the top level may not run on every path',
+    rejects: (c) => c.m.topAssignAt === null || c.m.constValue === null,
+  },
+  {
+    id: 'null-base',
+    why: '`0` is NULL, never an address — the sibling qualifier lever (volatileptr.ts) refuses it too',
+    sound: false,
+    rejects: (c) => c.m.constValue === 0,
+  },
+  {
+    id: 'use-before-assign',
+    why: 'a mention ahead of the assignment reads something the constant does not stand for',
+    sound: true,
+    guardedBy: 'inlinebase.test.ts: a use in a loop ABOVE the assignment reads the local before it is set',
+    rejects: (c) => c.m.firstAt !== c.m.topAssignAt,
+  },
+  {
+    id: 'addr-taken',
+    why: 'a deleted local has no address to take',
+    sound: true,
+    guardedBy: 'inlinebase.test.ts: an address-taken local has an identity the constant cannot stand in for',
+    rejects: (c) => c.m.addrTaken !== 0,
+  },
+  {
+    id: 'other-uses',
+    why: 'a use the substitution cannot reach would name the deleted local',
+    sound: true,
+    guardedBy: 'inlinebase.test.ts: a use that is not an `index` base is outside what the lever re-spells',
+    rejects: (c) => c.m.otherUses !== 0,
+  },
+  {
+    id: 'single-use',
+    why: 'one use is not the reused address this lever exists for',
+    sound: false,
+    rejects: (c) => c.m.baseUses < 2,
+  },
+];
+
+/** The locals INLINEBASE_GATES admits, each with the cast its uses become. */
+function plan(sfn: SFn): Map<string, Extract<Expr, { k: 'cast' }>> {
+  const t = localMentions(sfn);
+  const out = new Map<string, Extract<Expr, { k: 'cast' }>>();
+  for (const l of sfn.locals) {
+    const m = t.get(l.name);
+    if (
+      m === undefined ||
+      firstRejection(INLINEBASE_GATES, {
+        isPointer: l.type.kind === 'ptr',
+        objectVolatile: l.volatile !== undefined,
+        hasFrame: l.frame !== undefined,
+        m,
+      }) !== null
+    ) {
+      continue;
+    }
+    out.set(l.name, {
+      k: 'cast',
+      to: l.type,
+      ...(l.pointeeVolatile ? { volatile: true as const } : {}),
+      e: { k: 'const', value: m.constValue! },
+    });
+  }
+  return out;
+}
+
+/** Which locals this lever would delete — rank.ts narrows `/volatile` to exactly these before
+ *  pairing, so the qualified output never qualifies a pointer the lever leaves standing. */
+export function inlinableConstBases(sfn: SFn): string[] {
+  return [...plan(sfn).keys()];
+}
+
+/** The `/inlinebase` candidate, or null when no local qualifies. Read-only: returns a fresh SFn
+ *  whose body is rebuilt, leaving the input untouched. */
+export function inlineConstBases(sfn: SFn): SFn | null {
+  const inline = plan(sfn);
+  if (inline.size === 0) {
+    return null;
+  }
+  // A FRESH node per use — never one shared tree — because identity-keyed rules downstream
+  // (contracts.ts's dot-base exemption) read node identity.
+  const sub = (e: Expr): Expr => {
+    if (e.k === 'var') {
+      const at = inline.get(e.name);
+      if (at !== undefined) {
+        return { ...at, e: { ...at.e } };
+      }
+    }
+    return mapExprChildren(e, sub);
+  };
+  const body = sfn.body.filter((s) => !(s.k === 'assign' && inline.has(s.name))).map((s) => mapStmtExprs(s, sub));
+  return { ...sfn, locals: sfn.locals.filter((l) => !inline.has(l.name)), body };
+}

package/src/l3/mentions.ts

@@ -0,0 +1,113 @@
+// What one L3 tree does to each of its locals, counted once.
+//
+// Levers ask overlapping versions of the question and would disagree if each walked the tree
+// its own way: l3/inlinebase.ts needs the SHAPE of every use (only an `index` base is re-spellable,
+// and the single assignment must be a top-level `const` nothing mentions earlier), while
+// l3/volatileval.ts needs the COUNTS, to check the tree still performs every access the machine
+// did before it declares them all observable. One walk answers both, and it has to: on the counting
+// consumer a miscount is a wrong `volatile` claim, not a missed candidate.
+//
+// Derived from the ONE traversal vocabulary (exprChildren/stmtExprs/stmtChildren) for every node
+// kind, so a new one is a compile error there rather than a silent undercount here — with `index`
+// as the ONE hand-rolled case, because the callback needs to know which child stands as the base
+// and `exprChildren` flattens that away. That hand-rolling is a standing hazard rather than an
+// oversight: a POSITION added to `index` reaches the generic vocabulary for free and this walk not
+// at all. Every position is enumerated below and pinned by
+// test/array-rank-guards.test.ts, beside the generic helpers it cannot speak for.
+import { type Expr, type SFn, type Stmt, exprChildren, stmtChildren, stmtExprs } from './ast';
+
+export interface Mentions {
+  /** assignments to the name, at any nesting */
+  assigns: number;
+  /** body-top-level index of its single top-level assignment, or null */
+  topAssignAt: number | null;
+  /** the bare-`const` value that assignment stores, or null if it stores anything else */
+  constValue: number | null;
+  addrTaken: number;
+  /** uses as the `base` of an `index` node — the only use shape a base lever can re-spell */
+  baseUses: number;
+  /** every other read */
+  otherUses: number;
+  /** body-top-level index of the first statement mentioning the name at all */
+  firstAt: number | null;
+}
+
+/** reads of the name, however spelled */
+export function readsOf(m: Mentions): number {
+  return m.baseUses + m.otherUses;
+}
+
+const blank = (): Mentions => ({
+  assigns: 0,
+  topAssignAt: null,
+  constValue: null,
+  addrTaken: 0,
+  baseUses: 0,
+  otherUses: 0,
+  firstAt: null,
+});
+
+/** Visit every node, telling the callback whether it stands as an `index`'s base. */
+function walkExpr(e: Expr, visit: (x: Expr, isIndexBase: boolean) => void, isIndexBase = false): void {
+  visit(e, isIndexBase);
+  if (e.k === 'index') {
+    walkExpr(e.base, visit, true);
+    // `lead` — a multidimensional global's LEADING subscripts — is an ordinary value position, so
+    // a name mentioned there is a real read. Missing it does not cost a candidate: it lets a lever
+    // DELETE a local the body still names.
+    for (const l of e.lead ?? []) {
+      walkExpr(l, visit, false);
+    }
+    walkExpr(e.idx, visit, false);
+    return;
+  }
+  for (const c of exprChildren(e)) {
+    walkExpr(c, visit, false);
+  }
+}
+
+/** Every mention of every local, keyed by name. Locals only — a param or a global name is not in
+ *  the map, and a lever asking about one gets `undefined` rather than a zeroed record. */
+export function localMentions(sfn: SFn): Map<string, Mentions> {
+  const t = new Map<string, Mentions>(sfn.locals.map((l) => [l.name, blank()]));
+  const seen = (name: string, at: number): Mentions | undefined => {
+    const m = t.get(name);
+    if (m && m.firstAt === null) {
+      m.firstAt = at;
+    }
+    return m;
+  };
+  const stmt = (s: Stmt, at: number, top: boolean): void => {
+    if (s.k === 'assign') {
+      const m = seen(s.name, at);
+      if (m) {
+        m.assigns++;
+        if (top) {
+          m.topAssignAt = at;
+          m.constValue = s.value.k === 'const' ? s.value.value : null;
+        }
+      }
+    }
+    for (const e of stmtExprs(s)) {
+      walkExpr(e, (x, isIndexBase) => {
+        if (x.k === 'var' || x.k === 'addr') {
+          const m = seen(x.name, at);
+          if (m) {
+            if (x.k === 'addr') {
+              m.addrTaken++;
+            } else if (isIndexBase) {
+              m.baseUses++;
+            } else {
+              m.otherUses++;
+            }
+          }
+        }
+      });
+    }
+    for (const c of stmtChildren(s)) {
+      stmt(c, at, false);
+    }
+  };
+  sfn.body.forEach((s, i) => stmt(s, i, true));
+  return t;
+}

package/src/l3/mulfirst.ts

@@ -0,0 +1,42 @@
+// L3 re-spelling lever: put the PRODUCT operand first in a commutative `+`.
+//
+// structure.ts's def-order rule spells commutative operands in EVALUATION order, which recovers
+// gcc's left-to-right source order. IDO and mwcc break the correspondence for exactly one shape:
+// in `a*b + c` they SCHEDULE the independent load of `c` above the product's `mflo`/`mullw`, so
+// the machine add reads (c, product) and def order re-spells the source's product-first sum as
+// c-first. Which order the source used is not recoverable from positions there — so this lever
+// emits the product-first sibling and the differ referees (verified byte-identical against IDO
+// on the bg_area row; the def-order spelling stays in the list for sources that really were
+// c-first).
+//
+// SCOPE (decline over approximate): a `+` is flipped only when exactly ONE side is a product
+// (`bin('*')` at the root, casts looked through) — two products or none leave nothing to anchor
+// the flip on. A side carrying an effect (a call, a marker) never moves — evaluation order of
+// the operands is what the lever edits. Declines (null) when no `+` changes, so no duplicate
+// candidate.
+import type { Expr, SFn } from './ast';
+import { exprHasEffect, mapExprChildren, mapStmtExprs } from './ast';
+
+const isProduct = (e: Expr): boolean =>
+  e.k === 'bin' && e.op === '*' ? true : e.k === 'cast' ? isProduct(e.e) : false;
+
+export function mulFirstSums(sfn: SFn): SFn | null {
+  let changed = false;
+  const rewrite = (e: Expr): Expr => {
+    const m = mapExprChildren(e, rewrite);
+    if (
+      m.k === 'bin' &&
+      m.op === '+' &&
+      isProduct(m.r) &&
+      !isProduct(m.l) &&
+      !exprHasEffect(m.l) &&
+      !exprHasEffect(m.r)
+    ) {
+      changed = true;
+      return { ...m, l: m.r, r: m.l };
+    }
+    return m;
+  };
+  const body = sfn.body.map((s) => mapStmtExprs(s, rewrite));
+  return changed ? { ...sfn, body } : null;
+}