@asmlift/core 0.5.0 → 0.6.0

package/src/l3/volatileptr.ts

@@ -0,0 +1,207 @@
+// L3 re-spelling lever: declare a pointer local that holds a NUMERIC address as pointing to
+// volatile data (`volatile u16 *p = (u16 *)0x3000010;`).
+//
+// A numeric address has no declaration anywhere — the project maps a symbol's volatility, but a
+// raw constant is exactly the case with no symbol — so whether the original source read it
+// through a `volatile` pointer is not derivable from the asm. It is codegen-visible all the
+// same: a volatile MEM is barred from motion and combination, which reorders the loop
+// optimizer's pseudos and lands the register allocator on different homes (on the row this was
+// built for, the counter is copied out of r0 so the loaded value can have it — the target's
+// allocation). So the qualified spellings are emitted alongside the plain one — the all-locals
+// form as rank.ts `/volatile`, per-local subsets as its `-name` variants — and the differ
+// referees.
+//
+// SEMANTICS ARE PRESERVED BY CONSTRUCTION: `volatile` only RESTRICTS what a compiler may do
+// with the accesses; every execution of the qualified spelling is an execution of the plain
+// one. C89 also admits the assignment without a cast change — the qualifier is added on the
+// pointee, and assignment may add pointee qualifiers.
+//
+// GATE: only a local of pointer type assigned a REMATERIALIZABLE address somewhere in the body
+// (l3/ast.ts — any constant expression reading no variable and no memory, so a shift-encoded
+// hardware base qualifies exactly like a pool word); a bare `0` is NULL, never an address. A value
+// CONTAINING a global's address — `&gSym` at ANY depth: under a cast, inside interior-address
+// arithmetic (`(u16 *)((u32)&gSym + 8)`) — VETOES the local, qualifying assignments on other paths
+// notwithstanding, and the veto propagates through assignments to a FIXPOINT (`q` tainted,
+// `p = q` taints `p`; conservatively, `p` assigned ANY expression mentioning a tainted name).
+// The symbol map owns a declared global's volatility, and a mixed-feed local would read the
+// mapped global through a volatile view the map never granted. No qualifying local ⇒ decline
+// (null), so the lever never emits a duplicate of the primary.
+import { addrConst, cellAddress, inRange } from './address';
+import { type Expr, type SFn, type Stmt, mapExprChildren, rematerializableAddress, walkExprs } from './ast';
+
+const exprHas = (e: Expr, pred: (x: Expr) => boolean): boolean => {
+  if (pred(e)) {
+    return true;
+  }
+  let hit = false;
+  mapExprChildren(e, (c) => {
+    hit ||= exprHas(c, pred);
+    return c;
+  });
+  return hit;
+};
+
+function collectAssigns(stmts: Stmt[], out: { name: string; value: Expr }[]): void {
+  for (const s of stmts) {
+    switch (s.k) {
+      case 'assign':
+        out.push({ name: s.name, value: s.value });
+        break;
+      case 'if':
+        collectAssigns(s.then, out);
+        collectAssigns(s.else, out);
+        break;
+      case 'while':
+      case 'dowhile':
+        collectAssigns(s.body, out);
+        break;
+      case 'for':
+        collectAssigns([s.init, s.inc], out);
+        collectAssigns(s.body, out);
+        break;
+      case 'switch':
+        for (const c of s.cases) {
+          collectAssigns(c.body, out);
+        }
+        collectAssigns(s.default ?? [], out);
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+/** How many of this tree's `volatile` claims land on a DEVICE REGISTER — the gate on rank.ts's
+ *  volatility tie-break, so it is counted here beside the lever that mints the claims.
+ *
+ *  Two spellings assert one: a `volatile` pointer cast over a numeric address (what
+ *  l3/inlinebase.ts leaves at each use and what l3/volstore.ts mints at a device store), and a
+ *  pointee-volatile pointer local, which asserts it at whichever numeric address feeds the local.
+ *  A `volatile` SCALAR local (l3/volatileval.ts) asserts nothing about an address — it is a stack
+ *  slot — so it is not counted.
+ *
+ *  A claim under a SUBSCRIPT is placed by the whole cell and not by the cast's own operand, which
+ *  is the disagreement l3/address.ts warns about: `((volatile s32 *)0x03FFFFF0)[8]` denotes
+ *  BG0HOFS, and asking the base alone reports EWRAM and counts nothing. Either reading landing in
+ *  the window counts it, so a runtime subscript over an in-window base still does.
+ *
+ *  Nothing outside the window counts. A qualifier on ordinary memory is a claim about the source
+ *  the differ cannot referee and the range cannot support, and preferring it corpus-wide buys one
+ *  honest MMIO spelling at the price of many false ones. */
+export function deviceVolatileClaims(sfn: SFn, window?: readonly [number, number]): number {
+  if (window === undefined) {
+    return 0;
+  }
+  const inWindow = (e: Expr) => inRange(addrConst(e), window);
+  let n = 0;
+  const underSubscript = new Set<Expr>();
+  for (const e of walkExprs(sfn.body)) {
+    if (e.k === 'index' && e.base.k === 'cast') {
+      underSubscript.add(e.base);
+    }
+  }
+  const assigns: { name: string; value: Expr }[] = [];
+  collectAssigns(sfn.body, assigns);
+  for (const l of sfn.locals) {
+    if (l.type.kind === 'ptr' && (l.pointeeVolatile !== undefined || l.volatile !== undefined)) {
+      n += assigns.filter((a) => a.name === l.name && inWindow(a.value)).length;
+    }
+  }
+  for (const e of walkExprs(sfn.body)) {
+    if (e.k === 'index' && e.base.k === 'cast' && e.base.volatile === true) {
+      if (inRange(cellAddress(e), window) || inWindow(e.base.e)) {
+        n++;
+      }
+    } else if (e.k === 'cast' && e.volatile === true && !underSubscript.has(e) && inWindow(e.e)) {
+      n++;
+    }
+  }
+  return n;
+}
+
+/** The locals the lever would qualify — the per-local SUBSET enumeration's input (below):
+ *  which pointers the original declared volatile is per-pointer knowledge the asm does not
+ *  carry (an MMIO block and a plain RAM table can sit side by side, and qualifying the table
+ *  blocks the read collapse its region wants), so each non-empty subset is its own candidate
+ *  when few enough locals qualify, and the differ referees. */
+function volatileEligibleLocals(sfn: SFn): string[] {
+  return sfn.locals.filter(eligibility(sfn)).map((l) => l.name);
+}
+
+/** the value-side VETO of the header's GATE: `&gSym` at any depth, under a cast or inside interior
+ *  address arithmetic. Named because the taint seed and `volatileEligibleValue` are the same test. */
+const feedsSymbolAddress = (e: Expr): boolean => exprHas(e, (x) => x.k === 'addr');
+
+/** Whether a pointer local fed exactly this value, and nothing else, would qualify — the header's
+ *  GATE at its one-assignment case, where the taint fixpoint is its own seed.
+ *
+ *  Exported because a caller asking "would the spelling I am REPLACING have carried the qualifier?"
+ *  has to ask this model rather than re-derive it. The const-vs-symbol answer is this file's: a
+ *  numeric address has no declaration anywhere, a symbol's volatility is the map's, and a rule that
+ *  hard-codes that split drifts the moment the veto moves (l3/homesplit.ts). */
+export const volatileEligibleValue = (e: Expr): boolean => rematerializableAddress(e) && !feedsSymbolAddress(e);
+
+/** the shared eligibility predicate (the GATE in the header) for one function's locals */
+function eligibility(sfn: SFn): (l: SFn['locals'][number]) => boolean {
+  const assigns: { name: string; value: Expr }[] = [];
+  collectAssigns(sfn.body, assigns);
+  const numericFed = new Set<string>();
+  const tainted = new Set<string>();
+  for (const a of assigns) {
+    if (rematerializableAddress(a.value)) {
+      numericFed.add(a.name);
+    }
+    if (feedsSymbolAddress(a.value)) {
+      tainted.add(a.name);
+    }
+  }
+  for (let grew = true; grew;) {
+    grew = false;
+    for (const a of assigns) {
+      if (!tainted.has(a.name) && exprHas(a.value, (x) => x.k === 'var' && tainted.has(x.name))) {
+        tainted.add(a.name);
+        grew = true;
+      }
+    }
+  }
+  return (l) =>
+    l.type.kind === 'ptr' &&
+    l.volatile === undefined &&
+    l.pointeeVolatile === undefined &&
+    numericFed.has(l.name) &&
+    !tainted.has(l.name);
+}
+
+/** The proper non-empty SUBSETS of the qualifying locals (within `within`, when given) as
+ *  alternative outputs — one candidate per subset, labeled by its member names. Empty above
+ *  three qualifiers: the arm is capped at 6 extra spellings, and the all-qualifiers form is the
+ *  plain lever's own candidate. */
+export function volatileSubsetCandidates(sfn: SFn, within?: ReadonlySet<string>): { merged: string; sfn: SFn }[] {
+  const elig = volatileEligibleLocals(sfn).filter((n) => within === undefined || within.has(n));
+  if (elig.length < 2 || elig.length > 3) {
+    return [];
+  }
+  const out: { merged: string; sfn: SFn }[] = [];
+  for (let mask = 1; mask < (1 << elig.length) - 1; mask++) {
+    const subset = elig.filter((_, i) => (mask & (1 << i)) !== 0);
+    const r = volatilePtrLocals(sfn, new Set(subset));
+    if (r) {
+      out.push({ merged: subset.join('-'), sfn: r });
+    }
+  }
+  return out;
+}
+
+/** The `/volatile` candidate, or null when no local qualifies. Read-only: returns a fresh SFn
+ *  sharing the (unmodified) body. `only` narrows the lever to the named locals — a /volatile
+ *  PRODUCT (rank.ts) qualifies just the locals its first lever centres on (kept walk bases,
+ *  created hoists), so the product never degenerates into a general /volatile composition over
+ *  the function's other locals — and the subset enumeration re-uses the same door. */
+export function volatilePtrLocals(sfn: SFn, only?: ReadonlySet<string>): SFn | null {
+  const eligible = eligibility(sfn);
+  const qualifies = (l: SFn['locals'][number]): boolean => eligible(l) && (only === undefined || only.has(l.name));
+  if (!sfn.locals.some(qualifies)) {
+    return null;
+  }
+  return { ...sfn, locals: sfn.locals.map((l) => (qualifies(l) ? { ...l, pointeeVolatile: true } : l)) };
+}

package/src/l3/volatileval.ts

@@ -0,0 +1,130 @@
+// L3 re-spelling lever: declare a stack-homed scalar local `volatile` (`volatile u16 sp0;`).
+//
+// `volatile` on a scalar VALUE local FORCES the value into memory: agbcc's allocator is
+// otherwise free to keep it in a callee-saved register across a call, and no other qualifier
+// or type spelling takes that freedom away. Whether the source spelled it is not derivable from
+// the asm — a slot-homed value can equally come from an address-taken local or from plain
+// register pressure — so both spellings are emitted and the differ referees, exactly as the
+// sibling pointee lever (volatileptr.ts) does for a numeric-address pointer.
+//
+// SEMANTICS ARE PRESERVED BY CONSTRUCTION, as they are there: `volatile` only RESTRICTS what a
+// compiler may do with the accesses, so every execution of the qualified spelling is an
+// execution of the plain one. The object is a function local whose address does not escape,
+// so nothing outside the function can observe the difference at all.
+//
+// ENVELOPE — narrower than "a source-level volatile scalar": an `laddr`-recovered frame object,
+// which under Thumb is a SUB-WORD one (see the `frame` note on SFn.locals). A `volatile s32`
+// local spills straight to `[sp,#imm]` and is recovered as an ordinary value with no local of
+// its own, so this lever cannot reach it. The flag is the set of slots asmlift PROVED, not the
+// set of values a source could have qualified.
+//
+// GATE — VOL_SLOT_GATES holds the rules; the argument behind each is here, where there is room:
+//
+//   • The frame record is what gives the qualifier a home to force. Qualifying a register-homed
+//     value would enumerate a spelling no source that produced this asm could have had.
+//   • SCALAR, because a pointer local declares as `volatile u16 * p` — one prefix, two meanings —
+//     and cfamily.ts spells that for `pointeeVolatile`. On a pointer the qualifier would say
+//     something about the pointee the tree never claimed.
+//   • `volatile` already set is the frontend's stamp for an object whose address was PUBLISHED
+//     to memory (frontend/thumb.ts stamps it there, on `published`, not on any escape) — the
+//     candidate would duplicate the primary.
+//   • An address-TAKEN local already has a memory home in every spelling, so there is no home
+//     left for the qualifier to move: EReader_Reset's slot read and written through a pointer
+//     local compiles to IDENTICAL assembly with the qualifier and without (agbcc 2.9-arm-000512,
+//     `-O2 -mthumb-interwork -Wimplicit -fhex-asm -fprologue-bugfix`). What it can still do
+//     there is stop reads collapsing, which frontend/thumb.ts measured turning a byte-exact
+//     candidate into a four-instruction nonmatch.
+//   • ACCESS-SET EQUALITY is what makes the qualified spelling honest, and it is the one
+//     condition the tree alone cannot answer. `volatile` asserts that every access written is an
+//     access performed; the passes between the asm and here break that in both directions and
+//     leave no trace. eliminateDeadStores drops a store to a local it can see is dead — licensed
+//     by the ABSENCE of the flag this lever adds — so a source that stores the slot twice
+//     arrives with one store. And the structurer emits one C read per USE rather than per
+//     machine load, so one `ldrh` feeding two uses arrives as two reads. Either way the
+//     qualified spelling would declare an access set asmlift did not preserve, so both DECLINE.
+//
+// No qualifying local ⇒ decline (null), so the lever never emits a duplicate of the primary.
+//
+// ALL ELIGIBLE SLOTS OR NONE, where the sibling pointee lever enumerates per-local SUBSETS on the
+// argument that volatility is per-pointer knowledge. It is per-slot knowledge here too; the
+// subsets are simply uninhabited — across the 311 agbcc benchmark rows no function reaches this
+// gate with two eligible slots. How many reach it at all depends on the sweep's configuration, so
+// the subset question is the one to quote: two rows with the callee arities declared, one without.
+import type { SFn } from './ast';
+import { type Gate, firstRejection } from './gates';
+import { localMentions, readsOf } from './mentions';
+
+/** One local as the gates read it. */
+interface SlotCtx {
+  hasFrame: boolean;
+  isScalar: boolean;
+  alreadyVolatile: boolean;
+  addrTaken: number;
+  /** the tree's reads and writes are the machine's loads and stores */
+  accessSetKept: boolean;
+}
+
+export const VOL_SLOT_GATES: readonly Gate<SlotCtx>[] = [
+  {
+    id: 'no-frame',
+    why: 'the frame record is the memory home the qualifier has to force',
+    sound: false,
+    rejects: (c) => !c.hasFrame,
+  },
+  {
+    id: 'non-scalar',
+    why: 'on a pointer declarator the one `volatile` prefix binds to the pointee, not the object',
+    sound: true,
+    guardedBy: 'volatileval.test.ts: a non-scalar frame local never qualifies',
+    rejects: (c) => !c.isScalar,
+  },
+  {
+    id: 'already-volatile',
+    why: 'the primary already declares it, so the candidate would duplicate it',
+    sound: false,
+    rejects: (c) => c.alreadyVolatile,
+  },
+  {
+    id: 'addr-taken',
+    why: 'an address-taken local already has a memory home, so there is none left to force',
+    sound: false,
+    rejects: (c) => c.addrTaken > 0,
+  },
+  {
+    id: 'access-set',
+    why: 'the qualifier asserts every access written is performed, so the tree’s must be the machine’s',
+    sound: true,
+    guardedBy: 'volatileval.test.ts: a store the tree no longer carries declines',
+    rejects: (c) => !c.accessSetKept,
+  },
+];
+
+/** the shared eligibility predicate (VOL_SLOT_GATES) for one function's locals */
+function eligibility(sfn: SFn): (l: SFn['locals'][number]) => boolean {
+  const uses = localMentions(sfn);
+  return (l) => {
+    const u = uses.get(l.name);
+    if (u === undefined) {
+      return false;
+    }
+    return (
+      firstRejection(VOL_SLOT_GATES, {
+        hasFrame: l.frame !== undefined,
+        isScalar: l.type.kind === 'int',
+        alreadyVolatile: l.volatile !== undefined || l.pointeeVolatile !== undefined,
+        addrTaken: u.addrTaken,
+        accessSetKept: readsOf(u) === l.frame?.loads && u.assigns === l.frame?.stores,
+      }) === null
+    );
+  };
+}
+
+/** The `/vol-slot` candidate, or null when no local qualifies. Read-only: returns a fresh SFn
+ *  sharing the (unmodified) body. */
+export function volatileValueLocals(sfn: SFn): SFn | null {
+  const qualifies = eligibility(sfn);
+  if (!sfn.locals.some(qualifies)) {
+    return null;
+  }
+  return { ...sfn, locals: sfn.locals.map((l) => (qualifies(l) ? { ...l, volatile: true as const } : l)) };
+}

package/src/l3/volstore.ts

@@ -0,0 +1,229 @@
+// L3 re-spelling lever: pin a STORE at a fixed DEVICE-REGISTER address `volatile`
+// (`*(volatile s32 *)0x40000d4 = x` rather than `*(s32 *)0x40000d4 = x`).
+//
+// A numeric address has no declaration anywhere, so whether the original source wrote through a
+// `volatile` lvalue is not derivable from the asm — the same gap l3/volatileptr.ts's header
+// argues. That lever answers it for a pointer LOCAL holding the address; this one answers it
+// where there is no local at all, which is the spelling a `#define REG(x) *(vu32 *)(x)` macro
+// produces and the shape structure.ts leaves when the address re-materializes at each use.
+//
+// IT IS CODEGEN-VISIBLE, and the mechanism is one line of the compiler. agbcc's loop optimizer
+// runs `load_mems` (gcc/loop.c:8877) between the invariant hoist and strength reduction; it
+// PROMOTES a loop-invariant MEM into a register for the loop's duration and writes it back once
+// after the exit, and it stands down on exactly two conditions (gcc/loop.c:8934):
+//
+//     if (MEM_VOLATILE_P (mem) || invariant_p (XEXP (mem, 0)) != 1)
+//       loop_mems[i].optimize = 0;
+//
+// So an unpinned store to a fixed address inside a loop LEAVES THE LOOP — verified in both
+// directions on synthetic:dmafill (unpinned: one store in the body, three after the `ble`, two
+// pool words; pinned: four stores per iteration, four pool words). A decompiler that never spells
+// the qualifier can therefore never reproduce the loop body of any function that drives a device
+// register in a loop, whatever else it gets right.
+//
+// SEMANTICS ARE PRESERVED BY CONSTRUCTION: `volatile` only RESTRICTS what a compiler may do with
+// an access; every execution of the qualified spelling is an execution of the plain one. The
+// qualifier goes on the POINTEE of the deref cast, which is where C puts it and what
+// backend/cfamily.ts already prints for the casts l3/inlinebase.ts mints.
+//
+// GATE (VOL_STORE_GATES, read once per access). THE ADMISSION RULE IS ONE: the access's WHOLE
+// address must be a compile-time constant — a base that rematerializes to a numeric address plus a
+// constant subscript, no `lead` — lying inside a device-register window the target declares
+// (TargetDescription.capabilities.deviceRegisters); and the access must not already be qualified.
+// The first three entries PARTITION the first half rather than adding to it: `inRange` is false
+// when there is no window OR no constant OR the wrong constant, so ablating `no-window` or
+// `non-const-address` changes no admission anywhere in the ctx space. What they buy is a refusal
+// that says WHICH half is missing — "this target declares no device page" and "this address is
+// IWRAM" are different facts about a row, and over the corpus they are 283 and 711 of the 1011
+// refusals against `outside-window`'s 17. Nothing qualifying ⇒ decline (null), never a duplicate
+// of the primary.
+//
+// THE WINDOW IS A REACH GATE, PRICED — not a soundness one, which is why it is `sound: false`.
+// A `volatile` qualifier only restricts the compiler, so widening the range can never make a
+// candidate WRONG; what it would make is a claim about ordinary memory that the target denies
+// (IWRAM, EWRAM, palette, VRAM and OAM are memory a source does not qualify — target.ts) and that
+// the differ can only referee by luck. Measured by running the lever twice, once with the declared
+// range and once with one admitting every constant address: 8 trees over 7 rows carry a
+// const-address store the window excludes, and the fan moves on two of them —
+// `synthetic:readarm` 6 candidates → 8 (the extra one TIES its match at 0) and
+// `synthetic:fieldbase` 14 → 20 (best extra 22, losing to 0). No row's score or outcome moves
+// either way. So the range buys candidate discipline and the honesty of the claim, and no match
+// rests on it.
+//
+// WHAT THE WINDOW IS NOT: A CLAIM THAT NOTHING ELSE MAY QUALIFY ORDINARY MEMORY. `/volatile`
+// (l3/volatileptr.ts) does exactly that, and a sweep over 834 corpus trees finds it qualifying an
+// address outside this window on 21 (tree, local, address) pairs, 16 of them on agbcc — including
+// `kleod:WritePaletteColor:agbcc`, a published byte-exact MATCH whose winning source contains
+// `*(volatile s32 *)50351492 = v2 + 5;` at 0x03004D84, which is IWRAM — the same minted-cast form
+// this lever produces, at an address this lever's window refuses.
+//
+// THE TWO ARE SEPARATED BY THEIR DERIVATION AND NOT BY WHAT THEY EMIT, which is the trap in
+// reading that spelling as a contradiction. `/inlinebase` alone mints no qualifier at all —
+// enumerated on that row, `unsigned/inlinebase` carries zero `volatile` casts and
+// `unsigned/inlinebase/volatile` carries three. The qualifier comes from `/volatile`, which put it
+// on a pointer LOCAL the asm shows the compiler re-materializing rather than keeping; inlining
+// then carries that codegen fact onto each cast it leaves behind. This lever runs where no such
+// local ever existed, so its only input is the number — and outside a range the target has
+// declared, a number supports nothing. The window is where THIS lever's evidence runs out, not
+// where the target's permission does.
+//
+// (So the two are not foldable on the window, and the fold is not free: adopting it for `/volatile`
+// would delete the WritePaletteColor spelling. `deviceVolatileClaims` in volatileptr.ts already
+// unifies the COUNT side, which is the half where one answer really is enough. Nor do they
+// COMPOSE over the tree's OWN locals: that pairing would qualify a function's existing pointer-local
+// homes and its raw-constant stores together, and over 834 corpus trees both levers fire on ONE —
+// `kleod:SetupBG3WindowOverlay:agbcc`, which neither decompiler scores — and under two DIFFERENT
+// published classifications: asmlift `noncompile` (agbcc rejects its call to `m4aSoundVSyncOff`),
+// m2c `declined`. A pairing whose whole reach is a row asmlift cannot compile is one a row has yet
+// to demand.
+//
+// A lever that MINTS the locals is a different question with a different answer, and `rank.ts`
+// pairs this pass with one: `/regionbase` homes the regions holding two or more direct uses of a
+// device base and leaves every other spelling of the same address inline, so both qualifiers have
+// something to claim in one function. `synthetic:dmascope` is that row.)
+//
+// SCOPE: STORES only. A device READ is a different question with a different answer — the idiom
+// fold's DCE drops a use-less device load outright (synthetic:dmaback), so a read that survives to
+// L3 is one whose value the function consumes, and whether THAT may be CSEd is the question
+// `/reread-globals` referees as a structuring axis. The price of pinning one is real and is
+// measured on `synthetic:ucmp:agbcc`, a byte-exact match whose loop test READS 0x3001048: qualify
+// that read and the row scores 15. This lever does not reach it — ucmp's stores go through a
+// runtime address (`*(u8 *)(v1 + 0x3002000)`), so it declines there on `non-const-address`, in
+// both configurations and with any window. No row demands the read spelling, and a lever with no
+// inhabitant is what "earn the level" forbids.
+import { type IrType, T, scalarTypeForAccess } from '../ir/types';
+import { cellAddress, inRange } from './address';
+import { type Expr, type SFn, type Stmt, stmtChildren } from './ast';
+import { type Gate, firstRejection } from './gates';
+
+/** One STORE lvalue as the gates read it. */
+interface AccessCtx {
+  /** the target declares a device-register range at all */
+  hasWindow: boolean;
+  /** the access's whole address as a compile-time constant, or null */
+  address: number | null;
+  /** that address lies inside the declared window */
+  inWindow: boolean;
+  /** the lvalue already carries a `volatile` qualifier */
+  qualified: boolean;
+}
+
+// One rule at three resolutions, most general first: `inRange` fails for all three reasons, so
+// only `outside-window` and `already-qualified` change an admission. See the header's GATE
+// paragraph — what the first two decide is the REASON a row is refused, not whether it is.
+export const VOL_STORE_GATES: readonly Gate<AccessCtx>[] = [
+  {
+    id: 'no-window',
+    why: 'a target that declares no device range has no address this lever may call volatile',
+    sound: false,
+    rejects: (c) => !c.hasWindow,
+  },
+  {
+    id: 'non-const-address',
+    why: 'a runtime address names no cell, so nothing here can say which object it reaches',
+    sound: false,
+    rejects: (c) => c.address === null,
+  },
+  {
+    // NOT "the target denies this address may be volatile" — `/volatile` qualifies IWRAM on eleven
+    // agbcc rows, one of them a published match, and it is right to: see the header's last
+    // paragraph. This gate is about what THIS lever has evidence for, which is the address alone.
+    id: 'outside-window',
+    why: 'the address is the only evidence this lever has, and outside the window it supports nothing',
+    sound: false,
+    rejects: (c) => !c.inWindow,
+  },
+  {
+    id: 'already-qualified',
+    why: 'a second qualifier would nest a cast over a spelling that already asserts volatility',
+    sound: false,
+    rejects: (c) => c.qualified,
+  },
+];
+
+/** Does this base already assert volatility — a `volatile` cast at any depth of the cast chain? */
+const qualifiedBase = (e: Expr): boolean => e.k === 'cast' && (e.volatile === true || qualifiedBase(e.e));
+
+/** The pointee the deref cast carries: the access's own scalar type. */
+const pointee = (ix: Extract<Expr, { k: 'index' }>): IrType => scalarTypeForAccess(ix.width, ix.signed);
+
+/** What the gates read about one indexed access: its cell address, and whether that address is
+ *  evidence — a window to place it in, the placement itself, and whether the base already carries
+ *  the qualifier. */
+function accessCtx(lval: Extract<Expr, { k: 'index' }>, window: readonly [number, number] | undefined): AccessCtx {
+  const address = cellAddress(lval);
+  return {
+    hasWindow: window !== undefined,
+    address,
+    inWindow: inRange(address, window),
+    qualified: qualifiedBase(lval.base),
+  };
+}
+
+/** The store lvalue the gates admit, rewritten — or the input unchanged. */
+function qualify(lval: Expr, window: readonly [number, number] | undefined): Expr {
+  if (lval.k !== 'index') {
+    return lval; // a `field` lvalue is a recovered struct view, whose declaration owns volatility
+  }
+  const ctx = accessCtx(lval, window);
+  if (firstRejection(VOL_STORE_GATES, ctx) !== null) {
+    return lval;
+  }
+  // An existing scalar pointer cast takes the qualifier in place; a bare const gets one minted,
+  // exactly the node backend/cfamily.ts's own deref legalization would have synthesized.
+  const base: Expr =
+    lval.base.k === 'cast' && lval.base.to.kind === 'ptr'
+      ? { ...lval.base, volatile: true }
+      : { k: 'cast', to: T.ptr(pointee(lval)), volatile: true, e: lval.base };
+  return { ...lval, base };
+}
+
+/** How many stores this tree would qualify — the enumeration gate, so a function with no device
+ *  store costs one walk and no candidate.
+ *
+ *  A COUNT, so the shared `stmtChildren` walk order (a switch's default at `defaultAt`, not last)
+ *  cannot reach the answer. */
+export function deviceStoreCount(sfn: SFn, window?: readonly [number, number]): number {
+  let n = 0;
+  const visit = (stmts: readonly Stmt[]): void => {
+    for (const s of stmts) {
+      if (s.k === 'store' && qualify(s.lval, window) !== s.lval) {
+        n++;
+      }
+      visit(stmtChildren(s));
+    }
+  };
+  visit(sfn.body);
+  return n;
+}
+
+/** The `/vol-store` candidate, or null when no store qualifies. Read-only: returns a fresh SFn
+ *  whose body is rebuilt, leaving the input untouched. */
+export function volatileDeviceStores(sfn: SFn, window?: readonly [number, number]): SFn | null {
+  if (deviceStoreCount(sfn, window) === 0) {
+    return null;
+  }
+  const rewrite = (stmts: readonly Stmt[]): Stmt[] =>
+    stmts.map((s): Stmt => {
+      switch (s.k) {
+        case 'store':
+          return { ...s, lval: qualify(s.lval, window) };
+        case 'if':
+          return { ...s, then: rewrite(s.then), else: rewrite(s.else) };
+        case 'while':
+        case 'dowhile':
+          return { ...s, body: rewrite(s.body) };
+        case 'for':
+          return { ...s, init: rewrite([s.init])[0], inc: rewrite([s.inc])[0], body: rewrite(s.body) };
+        case 'switch':
+          return {
+            ...s,
+            cases: s.cases.map((c) => ({ ...c, body: rewrite(c.body) })),
+            ...(s.default ? { default: rewrite(s.default) } : {}),
+          };
+        default:
+          return s;
+      }
+    });
+  return { ...sfn, body: rewrite(sfn.body) };
+}

package/src/l3/zerosub.ts

@@ -0,0 +1,62 @@
+// L3 re-spelling lever: spell a negate of a SHARED subtraction as `0 - x`.
+//
+// The two C spellings of a negation are not interchangeable in front of gcc 2.9's folder. `-x` is
+// built through build_unary_op and FOLDED, so fold-const.c's "Convert - (a - b) to (b - a)"
+// (gcc/fold-const.c:4821) rewrites a negated subtraction into the reversed one before CSE ever
+// runs. `0 - x` reaches fold as a MINUS_EXPR with a zero left operand and comes back as a bare
+// `build1 (NEGATE_EXPR, …)` (gcc/fold-const.c:5085) which is never re-folded, so the subtraction
+// survives as itself.
+//
+// With ONE use that difference is invisible: RTL combine folds the negate back in and both
+// spellings emit the same `sub r0, r1, r0`. With the subtraction SHARED — its value also feeding
+// the compare that chose the branch — they diverge by more than the negate, because the reversed
+// subtraction is a second computation whose operands must stay live: `-(a - b)` costs six
+// instructions (one a register copy) where `0 - (a - b)` costs five. Both compiled with agbcc
+// `-O2 -mthumb-interwork -Wimplicit -fhex-asm -fprologue-bugfix`.
+//
+// NOT an agbcc rule, so no target gate: compiled on the shared shape, IDO, KMC GCC and gcc
+// 2.7.2/MIPS each emit a different function for the two spellings as well — IDO the other way
+// round, where `-(a - b)` is the `negu` and `0 - (a - b)` the reversed `subu` — and only mwcc
+// collapses them, where the duplicate scores identically and can neither win nor lose.
+//
+// So which one the source wrote is not recoverable — a `neg` is reachable from `-t` over a named
+// local as well — and the differ referees. Semantics are preserved by construction: `-x` and
+// `0 - x` are the same C expression for every integer type.
+//
+// A RE-SPELLING rather than a fourth value-home axis (docs/level-tower.md's third fork). The fold
+// rule fires at all only because asmlift INLINED a value the source bound to a local, and naming
+// that local reaches the same match by the other route: on `pokeemerald:GetAnchorCoord:agbcc`,
+// `s32 t = a1 - a0;` scores 0 against the row's own target.o where the inlined body with a plain
+// `-` scores 1. asmlift cannot spell it — all three home axes decline on pedigree (`/addr-home`
+// wants an address, `/expr-home` a loop, `/derived-home` a memory read) and this is a bare pure
+// value with three consumers. An axis admitting any such value would reach the use shapes a
+// substitution cannot, and would double the fan wherever it admits; this costs one candidate per
+// distinct tree carrying the shape. Take the axis when a row demands a shape this cannot reach.
+//
+// SCOPE (decline over approximate). Only a `bin('-')` operand, and only a SHARED one. Neither
+// restriction is caution: over any other operand shape the fold rule does not apply and the two
+// spellings compile identically (verified for `-(a + b)`, `-(a >> 3)`, `-(a * 3)`, `-a`), so
+// firing there could only duplicate the primary. An EFFECTFUL subtraction is out of scope too —
+// two textually equal calls are two calls, not one shared value, so the premise fails.
+import { type Expr, type SFn, exprEquals, exprHasEffect, mapExprChildren, mapStmtExprs, walkExprs } from './ast';
+
+export function zeroSubNegates(sfn: SFn): SFn | null {
+  const subs: Expr[] = [];
+  for (const e of walkExprs(sfn.body)) {
+    if (e.k === 'bin' && e.op === '-') {
+      subs.push(e);
+    }
+  }
+  const shared = (x: Expr): boolean => subs.filter((s) => exprEquals(s, x)).length > 1;
+  let changed = false;
+  const rewrite = (e: Expr): Expr => {
+    const m = mapExprChildren(e, rewrite);
+    if (m.k === 'un' && m.op === '-' && m.e.k === 'bin' && m.e.op === '-' && !exprHasEffect(m.e) && shared(m.e)) {
+      changed = true;
+      return { k: 'bin', op: '-', l: { k: 'const', value: 0 }, r: m.e };
+    }
+    return m;
+  };
+  const body = sfn.body.map((s) => mapStmtExprs(s, rewrite));
+  return changed ? { ...sfn, body } : null;
+}