@asmlift/core 0.5.0 → 0.7.0

package/src/l3/ast.ts

@@ -1,7 +1,7 @@
 // asmlift L3 — the language-NEUTRAL structured AST. A LanguageBackend lowers this to a
 // concrete language (C / Pascal / C++) and prints it. "Return a value" and binary ops
 // are neutral nodes here; each backend owns its own spelling.
-import type { IrType } from '../ir/types';
+import { type IrType, typeEquals } from '../ir/types';
 
 export type Expr =
   | { k: 'var'; name: string }
@@ -15,7 +15,13 @@ export type Expr =
   // `3 & (s32)p`). Scalar deref casts are backend-owned — the C-family printer synthesizes
   // them from the `index` node's width. Each backend spells the cast in its own syntax
   // (C: `(u8)e`; Pascal: no spelling yet → fails loud).
-  | { k: 'cast'; to: IrType; e: Expr }
+  //
+  // `volatile` qualifies the POINTEE of a pointer cast (`(volatile u16 *)0x4000208`) — the one
+  // place asmlift can say "this access is to a volatile object" when there is no declaration to
+  // hang it on, which is exactly the raw-address case (l3/inlinebase.ts). IrType models no
+  // cv-qualifier, deliberately: volatility is a SPELLING, carried at the declaration or the
+  // cast, the same split SFn.locals makes for `volatile`/`pointeeVolatile`.
+  | { k: 'cast'; to: IrType; e: Expr; volatile?: true }
   | { k: 'call'; fn: string; args: Expr[] }
   // The ADDRESS of a named global, `&gSym` (agbcc pool `.word gSym`, frontend `gaddr` op). A
   // DEREF of it collapses to the bare global: memAccess/arrayAccess spell `*(&gSym)` as `gSym`
@@ -38,13 +44,105 @@ export type Expr =
   // Variable-index `a[i]` is recovered at the IR level (`aload`/`astore` carry elemSize;
   // raise/arrays.ts) but still LOWERS to this one C-shaped `index` node, so it stays C-only
   // (a Pascal array-access spelling is future work). Treat `index` with idx ≠ 0 as C-shaped.
-  // `lead` prefixes CONSTANT subscripts before `idx` — `g[0][i]` rather than `g[i]`. It exists for
-  // exactly one inhabitant: the bare-name spelling of a MULTIDIMENSIONAL array global, where one
-  // subscript reaches a row and the element needs the leading dimensions pinned first. The node
-  // still denotes ONE `width`-byte element, so its type, its legalization and its stride contract
-  // are unchanged — this is a spelling of the same address, not a new kind of access. Absent for
-  // every rank-1 access, which is why it is optional rather than an empty array.
-  | { k: 'index'; base: Expr; idx: Expr; width: number; signed: boolean; lead?: number[] }
+  // `lead` prefixes the LEADING subscripts before `idx` — `g[0][i]` or `g[r][i]` rather than
+  // `g[i]`. It exists for exactly one inhabitant: the bare-name spelling of a MULTIDIMENSIONAL
+  // array global, where one subscript reaches a row and the element needs the leading dimensions
+  // pinned first. The node still denotes ONE `width`-byte element, so its type, its legalization
+  // and its stride contract are unchanged — this is a spelling of the same address, not a new kind
+  // of access. Absent for every rank-1 access, which is why it is optional rather than an empty
+  // array. A leading subscript is an EXPRESSION because a row index the asm computed is a value,
+  // not a literal (`g[gRow][i]`), so every generic walk descends into it: a name mentioned there
+  // is a real use, and a rewrite that skipped it would rename half an address. `exprChildren` and
+  // `mapExprChildren` below carry it, which is what makes that true for every walk DERIVED from
+  // them; the one walk that is not — l3/mentions.ts, which hand-rolls a traversal to tell an
+  // `index` BASE from every other position — enumerates the positions itself and has to be
+  // extended by hand when one is added here.
+  // `operandOff` is the one field here that is EVIDENCE rather than spelling: it is the BYTE
+  // DISPLACEMENT this access's constant offset arrived in through the instruction's MEMORY
+  // OPERAND (`ldrb [r0, #0x3]` records 3), as opposed to through the address the pool word
+  // materialized (`.word gSym+0x3`, which records nothing). Both denote the same cell and print
+  // the same subscript, which is why `exprEquals` ignores it — but on a compiler that folds a
+  // constant subscript into the literal, only one C spelling could have put it there, so
+  // `l3/basecse.ts` reads its PRESENCE as the evidence its `unfoldedOffset` rule is about and
+  // `l3/offmember.ts` reads its VALUE as the member offset to re-spell. Absent whenever the
+  // offset was 0 or came from the address expression, so absence is never proof of anything — and
+  // a displacement can be NEGATIVE, so every reader tests `!== undefined`, never truthiness.
+  //
+  // THE FIELD IS HALF OF A TWO-PART FACT, and the other half has no field because it needs none.
+  // A displacement that reached the instruction says the compiler did not fold it; WHAT TO DO
+  // about that depends on the BASE'S KIND, which is read off the base expression at each reader:
+  //   • a local (`var`)   — nothing to reassociate into; already right, and no reader fires.
+  //   • a plus tree       — the fold pulls the displacement into the tree, costing an `add` and a
+  //                         register. The repair is to home the base in a local so it becomes a
+  //                         `var`, which is the ADDRESS-HOME variation and lives one level down at L2
+  //                         (`structure/analysis.ts`'s `sharedBaseClasses`) because materializing
+  //                         a value is a structuring decision, not a spelling.
+  //   • a leaf const/addr — the fold bakes the displacement into the literal, changing the `.word`.
+  //                         The repair is a spelling: `/basefold`'s named base or
+  //                         `/offmember`'s aggregate member, both at L3.
+  // The two repairs are deliberately NOT dispatched from one place. They sit at different levels
+  // and partition the space by their own pre-existing predicates (a non-const pure def with no
+  // gaddr in its cone, versus `l3/offmember.ts`'s leaf base), so a shared dispatch would be
+  // scaffolding over two rules that already disagree about what a base is. What the reader needs
+  // is the map, which is this paragraph.
+  //
+  // `baseOrdered` is the SECOND evidence field, and it answers about the base rather than the
+  // offset: the input assembly materialized this access's base BEFORE it scaled the index
+  // (raise/globalshape.ts `orderLicensedGlobals`, stamped at the structure seam; that module's
+  // header carries the compiles saying which source spellings produce which order). It is what
+  // says a base may be given a HOME — `l3/basecse.ts`'s `order-licensed`. Absent means "no such
+  // evidence", never "the index came first": a scaling in another block is not comparable, and a
+  // compiler that has not opted in stamps nothing. `exprEquals` ignores it for `operandOff`'s
+  // reason — both spellings denote the same cell — and it is per SYMBOL, so every access of one
+  // name carries the same answer, which is right for agbcc because one CSEd pool load serves
+  // them all.
+  //
+  // `baseAdvanced` is the THIRD, and it answers about the ADDRESS COMPUTATION: this access's
+  // address was reached by ADDING this many bytes to a register that already held — and had just
+  // been used as — another address (`adds r3, #2` between two stores), rather than by a second
+  // pool word or a memory-operand displacement. `raise/const.ts` records it on the literal its
+  // fold produces, because the fold is what makes the three shapes indistinguishable; the
+  // structure seam copies it here. `l3/advance.ts` is what reads it, to offer a pointer local
+  // advanced in place. `exprEquals` ignores it for `operandOff`'s reason. Absence is never proof:
+  // a target whose frontend does not lift the advance stamps nothing, and the value is a byte
+  // count that can be NEGATIVE, so readers test `!== undefined`.
+  | {
+      k: 'index';
+      base: Expr;
+      idx: Expr;
+      width: number;
+      signed: boolean;
+      lead?: Expr[];
+      /** The ELEMENT type the base's own DECLARATION gives it, for the one base whose stride the
+       *  C type walk cannot reconstruct: a map-declared array MEMBER (`gPtr->arr`), which
+       *  `exprCType` types `undefined` because the `field` node hangs off an untyped `var`. Without
+       *  it the C backend legalizes the base through a reinterpret cast (`((u8 *)gPtr->arr)[i]`),
+       *  which is the CAST form's object again and defeats the whole point of naming the member.
+       *
+       *  IT IS A PRODUCER INVARIANT: the backend cannot vet a stated type. `derefStrideOk` tests
+       *  the STATED type against the access width, never against the base, so it is true by
+       *  construction for anything a producer could state AND for a statement gone stale. What
+       *  the consumer does guard is PRECEDENCE — this field is consulted only where `exprCType`
+       *  answers nothing (cfamily.ts `legalizedIndexBase`), so wherever the walk can read the base
+       *  it corrects a stale statement instead of being overridden by it. The one producer,
+       *  structure/structure.ts `pointeeElement`, sets it from the same `elemSize`/`elemSigned` it
+       *  has just passed `spellsAccessType` on — and that predicate IS
+       *  `typeEquals(T.int(width*8, elemSigned), scalarTypeForAccess(width, signed))`, so
+       *  `derefStrideOk` over the stated pointer is true by construction at every width (4 by
+       *  `width === 4`, 1 and 2 by `to.signed === signed`). The obligation is on the PRODUCER:
+       *  state the type the access's own width and signedness agree with.
+       *
+       *  THE ALTERNATIVE REJECTED: teach `exprCType` the pointee layout, the way
+       *  `sym.noteGlobal` types the bare-array spelling —
+       *  the printer already renders `u8 grid[6][8]` for this member from this same layout. It was
+       *  rejected because `SFn.globals` is also the ADDRESSABLE-BASE list, so typing the symbol
+       *  there admits it as a `/livebase` base (measured on the probe: 8 extra base locals). Typing
+       *  the one node costs no candidates. */
+      baseElem?: IrType;
+      operandOff?: number;
+      baseOrdered?: true;
+      baseAdvanced?: number;
+    }
   // A named struct-field access `base->name` (raise/structs.ts recovered `base` as a struct
   // pointer, so the byte offset resolves to a named field instead of a scaled array index).
   // Unlike `index`, this carries the field NAME (which encodes the byte offset, `field_<off>`),
@@ -59,31 +157,41 @@ export type Expr =
   // default) never produces this node; it keeps the `"?"` sentinel → ContractError behavior.
   | { k: 'marker'; reason: string; args: Expr[] };
 
-// `>>` is the ARITHMETIC right shift and `>>>` the LOGICAL one. C spells both `>>` and picks from
-// the left operand's type, so the C backend synthesizes the cast that pins the choice — exactly as
-// it already synthesizes scalar deref casts from an `index` node's width. A backend with no
-// spelling for one of them (IDO Pascal) declines LOUDLY on the operation itself, rather than on
-// whatever artifact another language's spelling happened to leave in the tree.
+// THE SIGNEDNESS-CARRYING PAIRS. `>>` is the ARITHMETIC right shift and `>>>` the LOGICAL one;
+// `/`/`%` are the SIGNED quotient and remainder and `/u`/`%u` the unsigned ones. C spells each pair
+// with one token and picks between them from the operand types, so the C backend synthesizes the
+// cast that pins the choice — exactly as it already synthesizes scalar deref casts from an `index`
+// node's width. A backend with no spelling for one of them (IDO Pascal) declines LOUDLY on the
+// operation itself, rather than on whatever artifact another language's spelling happened to leave
+// in the tree.
+//
+// WHY THESE SPLITS AND NOT THE OTHERS. "The machine distinguishes them" is NOT the rule — the
+// machine distinguishes `sltu`/`slt` too, and CMP_TO_BIN deliberately collapses `icmp_u*`→`<` etc.,
+// noting that "unsignedness is in the operand types". Taking the machine as the rule would license
+// more splits with no inhabitant, which is what "earn the level" forbids. The rule is the repo's
+// own: a split is earned by a real, byte-load-bearing divergence WITH inhabitants that no other
+// channel can carry. The shifts earned it first (~20 rows, 5 projects, 4 compilers) because the
+// operand type could not carry them — a promoted narrow value is signed whatever it was loaded as.
 //
-// WHY THIS ONE SPLIT AND NOT THE OTHERS. "The machine distinguishes them" is NOT the rule — the
-// machine distinguishes `divu`/`div` and `sltu`/`slt` too, and ARITH_TO_BIN deliberately collapses
-// `udiv`→`/`, `umod`→`%`, `icmp_u*`→`<` etc., noting that "unsignedness is in the operand types".
-// Taking the machine as the rule would license four more splits with no inhabitant, which is what
-// "earn the level" forbids. The rule is the repo's own: the shift split because a real,
-// byte-load-bearing divergence HAD inhabitants (~20 rows, 5 projects, 4 compilers) and no other
-// channel could carry it — the operand type could not, since a promoted narrow value is signed
-// whatever it was loaded as.
+// The divides earned it second, on pokeemerald:GetAnchorCoord — `(u32)(coord * a1) / (u32)a0`
+// standing beside two arithmetic shifts of the same values. Their only other channel is the operand
+// TYPES, reached by flipping a declaration, and there that flip is unreachable and unsound at
+// once: the divisor also feeds a signed compare, so the /uns-cmp reconciliation correctly refuses
+// it, and forcing it anyway makes agbcc delete the comparison as always-false. A per-operand pin is
+// the only spelling that says "this division alone is unsigned".
 //
-// The collapsed operators lean on exactly that channel, so they carry the same latent hazard:
-// `*(u16 *)p / 3` renders as a signed division of a promoted `int` where the asm did `divu`. It is
-// tolerated because no row has produced such a divergence. When one does, the fix is this same
-// split — not a per-site patch.
+// The COMPARISONS stay collapsed, and that asymmetry is the rule applying rather than an omission:
+// which side a compare was spelled from genuinely underdetermines — a signed spelling that
+// byte-matched was proved non-negative by the compiler — so it is refereed as a variation, while a
+// division helper is a pure function of the expression's C type with no such proof available.
 export type BinOp =
   | '+'
   | '-'
   | '*'
   | '/'
+  | '/u'
   | '%'
+  | '%u'
   | '<'
   | '<='
   | '>'
@@ -130,7 +238,20 @@ export type Stmt =
   | { k: 'continue' }
   // A multi-way `switch` over an integer scrutinee (recovered from a comparison tree — Regime A — or
   // a jump-table `switch_br` — Regime B). `cases` are emitted IN ARRAY ORDER; `default` (if present)
-  // is emitted last.
+  // is emitted after `defaultAt` of them, or after all of them when that is absent.
+  //
+  // `defaultAt` exists because C lets `default:` sit BETWEEN case labels and a compiler that lays
+  // case bodies out in source order shows where the source put it. It is a COUNT of preceding arms,
+  // not an index into an array a later pass may rebuild, and a count past the arms is a producer bug
+  // a backend refuses. Setting it is legal only when the arm before the label does not fall through:
+  // moving the label in front of a falling arm would divert that arm into the default. The C-family
+  // printer terminates a non-final default with `break;` for the mirror-image reason.
+  //
+  // Unlike `fallsThrough` below, `defaultAt` is a SPELLING: the arm BEFORE the label is closed (the
+  // rule above) and so is the default body itself (the C-family printer terminates a non-final one),
+  // so a backend with no positional default (Pascal's `otherwise`) may ignore the count and still
+  // emit the same program. The arm AFTER the label is under no such rule and MAY fall through — it
+  // falls into the arm below it, which the label does not stand between.
   //
   // NON-NEUTRALITY NOTE (like the `index` node above): `fallsThrough` encodes a C/C++ control-flow
   // concept POSITIONALLY — `cases[i].fallsThrough === true` means control continues into
@@ -139,7 +260,12 @@ export type Stmt =
   // Pascal backend MUST loud-fail a `fallsThrough` case (it has no faithful spelling), exactly as it
   // loud-fails `field`/`cast`. Recovery must therefore only set `fallsThrough` when the fall-through
   // target is the emission-adjacent case.
-  | { k: 'switch'; scrutinee: Expr; cases: SwitchCase[]; default?: Stmt[] }
+  //
+  // Recovery COMPUTES this flag rather than spelling it, so a source grep for `fallsThrough: true`
+  // finds hand-written fixtures and nothing else, whatever the corpus does — count its inhabitants
+  // by instrumenting the printer. Both regimes produce them: the jump table spells `case 4:` of
+  // `kleod:UpdateWorldMapNodeAnim`, the comparison tree `synthetic:sw_fallmem:agbcc`.
+  | { k: 'switch'; scrutinee: Expr; cases: SwitchCase[]; default?: Stmt[]; defaultAt?: number }
   | { k: 'return'; value?: Expr };
 
 /** One arm of a `switch`. `values` stacks multiple `case K:` labels onto one body (`case 1: case 2:`).
@@ -153,7 +279,59 @@ export interface SwitchCase {
 export interface SFn {
   name: string;
   params: { name: string; type: IrType }[];
-  locals: { name: string; type: IrType; volatile?: true }[]; // recovered locals, declared at function top
+  /** Recovered locals, declared at function top. Two INDEPENDENT volatility facts, mirroring
+   *  symbols.ts's cell-vs-pointee split: `volatile` = the local OBJECT is volatile (the
+   *  address-escaped frame scratch; dce.ts treats reads of it as observable), `pointeeVolatile`
+   *  = the local is a pointer TO volatile data (the l3/volatileptr.ts variation; a declaration
+   *  spelling only — nothing about the local itself is observable).
+   *
+   *  `frame` is present on a local the structurer recovered from an `laddr` — the asm
+   *  MATERIALIZED the slot's address into a register, so the object provably lives in memory —
+   *  and carries the machine's static access counts for it. Under Thumb that envelope is a
+   *  SUB-WORD frame object: `strh/ldrh/strb/ldrb` have no `[sp,#imm]` form, so a compiler must
+   *  copy `sp` first, while a word spill goes straight to `[sp,#imm]` and is recovered as an
+   *  SSA value with no local of its own. So `frame` is NOT the set of every value the machine
+   *  slotted. `loads`/`stores` are the yardstick a qualifier variation must match before it may
+   *  declare every access to the object observable: the readability passes between here and L3
+   *  may drop a store or render one machine load as two reads, and `volatile` over an access
+   *  set asmlift did not preserve is a source that contradicts itself. ABSENT where the counts
+   *  would be a floor rather than the set: an address reaching anything but a direct load/store
+   *  leaves accesses the count cannot see.
+   *
+   *  ORDER MATTERS, and it means two different things at two different times. As the structurer
+   *  builds it and as every L3 pass sees it, this is the RECOVERED DECLARATION ORDER — the naming
+   *  walk's order — and passes reason about it as such: `l3/coalesce.ts` picks the arm-disjoint
+   *  survivor by position in THIS list, so the earlier declaration wins the way a shared source
+   *  local reads. The EMITTED order is this list re-sorted by `l3/slotorder.ts` inside `emit`,
+   *  which happens after every pass and returns a copy. A pass that sorted the list any earlier
+   *  would silently change which local survives every arm-disjoint merge.
+   *
+   *  ONE COMMENT, DELIBERATELY. Five sites tell a reader to consult "the SFn.locals doc"
+   *  (structure/structure.ts, l3/inlinebase.ts, l3/volatileval.ts, l3/reindex.ts, l3/unreduce.ts),
+   *  and TypeScript attaches only the LAST doc block before a declaration — so a second block
+   *  added in front of this one would silently orphan everything above and those five references
+   *  would point at half a paragraph. Append here; do not add a neighbour. */
+  locals: {
+    name: string;
+    type: IrType;
+    volatile?: true;
+    pointeeVolatile?: true;
+    frame?: { loads: number; stores: number };
+    /** the local stands on an `undef` — storage the asm reads without ever writing it, where the
+     *  MISSING assignment is the recovery. Marked because a local read and never assigned is
+     *  otherwise a dropped statement (contracts.ts assertLocalsWritten). */
+    uninit?: true;
+    /** every `[sp,#k]` the machine homed this local at, when the asm spilled it — ascending, and
+     *  usually one. Several when the naming walk put several spilled values under this one name,
+     *  or a coalesce absorbed a second homed local into it; the list is the UNION and picks
+     *  nothing, because which offset is the earlier DECLARATION RANK depends on the frame's
+     *  direction and only `l3/slotorder.ts` holds it (ir/core.ts `SlotHomes`).
+     *
+     *  Present ONLY on a local recovered from word-spill VALUES. A `frame` local and a `uninit`
+     *  one are deliberately left unstamped even where the offset is in hand — see the refusal at
+     *  the structurer's build site for the measurement that decided it. */
+    slots?: number[];
+  }[];
   /** project globals referenced with a known declaration shape (symbol map) — typed for the
    *  legalization env (exprCType) but NEVER declared by a backend: the project's own headers
    *  declare them, exactly like every other global name asmlift emits. */
@@ -163,6 +341,18 @@ export interface SFn {
   /** Struct types this function's fields reference, declared above it by the backend. Empty
    *  unless raise/structs.ts recovered a struct. Sorted by name for deterministic output. */
   structs?: StructType[];
+  /** Which way this compiler hands out frame slots against DECLARATION RANK, when it is known:
+   *
+   *  THE ONE COMPILER DATUM ON THE NEUTRAL TREE, and it is here rather than in a backend on
+   *  purpose: `LanguageBackend.emit(fn: SFn): string` is the only seam a backend has, and widening
+   *  it to `emit(fn, opts)` would hand the datum back to the seven `.emit(` CALL SITES this design
+   *  exists to keep it out of. So the tree is neutral in its NODES — every node still spells the
+   *  same thing in C, C++ and Pascal — and not in its emission policy, which this field is.
+   *  `ascending` = the earlier-declared spilled local takes the LOWER `[sp,#k]`. Set by the
+   *  structurer from `StructureOptions.spillSlotOrder`, itself a compiler behavior declared in
+   *  `TargetDescription.compilerBehaviors`. ABSENT means the direction is unknown for this target
+   *  and `l3/slotorder.ts` is the identity — never "ascending by default". */
+  slotOrder?: 'ascending' | 'descending';
 }
 
 /** A struct declaration surfaced to the backend (name + field list). Mirrors the IR struct
@@ -177,6 +367,14 @@ export interface StructType {
  *  comment spelling. */
 export interface LanguageBackend {
   readonly id: 'c' | 'cpp' | 'pascal';
+  /** Can this language spell a `switch` arm that RUNS ON into the next one (`fallsThrough`)?
+   *  C and C++ can; Pascal's `case-of` cannot, and its backend loud-fails the node (see the
+   *  non-neutrality note on `Stmt`'s `switch`). Declared here rather than inferred from `id`
+   *  because it is what RECOVERY must ask: a comparison-tree switch has a second, behaviourally
+   *  identical recovery (plain if-nesting), so minting a `fallsThrough` arm for a backend that
+   *  cannot print it turns a whole function that used to decompile into a loud stub. The
+   *  structurer reads it through `StructureOptions.spellSwitchFallthrough`. */
+  readonly spellsSwitchFallthrough: boolean;
   emit(fn: SFn): string;
   // Spell ONE LINE of text as a comment in this language (C block comments, Pascal `(* … *)`).
   // Used by the annotate-mode stub path to carry the failure reason + the original asm
@@ -201,8 +399,17 @@ export function fieldSpellsDot(f: Extract<Expr, { k: 'field' }>): boolean {
 }
 
 /** Structural equality of two expression trees. THE one copy of Expr deep-equal (like
- *  fieldSpellsDot/derefStrideOk): key-order-independent by construction (a switch, not a
- *  stringify), exhaustive under noImplicitReturns like the walkers below. */
+ *  fieldSpellsDot/derefStrideOk), exhaustive under noImplicitReturns like the walkers below.
+ *
+ *  Key-order-independent for every EXPR field — a switch, not a stringify. NOT for the `cast`
+ *  arm's TARGET TYPE, which is compared by serialization and so is order-sensitive: two `IrType`
+ *  objects with the same fields written in a different order compare UNEQUAL. That is why the
+ *  inline `IrType` literals elsewhere in the codebase are written in `T.int`/`T.ptr` key order —
+ *  matching the constructors keeps them comparable against constructed types.
+ *
+ *  `typeEquals` (ir/types.ts) is NOT the fix: it ignores `struct.size`, so it is strictly more
+ *  permissive, and swapping it in here would let a CSE collapse two accesses whose struct stride
+ *  differs. */
 export function exprEquals(a: Expr, b: Expr): boolean {
   if (a.k !== b.k) {
     return false;
@@ -224,7 +431,14 @@ export function exprEquals(a: Expr, b: Expr): boolean {
     }
     case 'cast': {
       const bb = b as typeof a;
-      return JSON.stringify(a.to) === JSON.stringify(bb.to) && exprEquals(a.e, bb.e);
+      // `volatile` is part of the SPELLING, compared for the same reason `lead` and `dot` are: a
+      // CSE or dedup that treats these as equal keeps one node and drops the other, silently
+      // rewriting a volatile access as a plain one.
+      return (
+        JSON.stringify(a.to) === JSON.stringify(bb.to) &&
+        (a.volatile ?? false) === (bb.volatile ?? false) &&
+        exprEquals(a.e, bb.e)
+      );
     }
     case 'call': {
       const bb = b as typeof a;
@@ -234,13 +448,23 @@ export function exprEquals(a: Expr, b: Expr): boolean {
       const bb = b as typeof a;
       // `lead` is part of the ADDRESS (`g[0][i]` and `g[1][i]` are different elements), so it
       // must be compared — an omission here would let CSE/dedup collapse two distinct accesses.
+      // The EVIDENCE fields (`operandOff`, `baseOrdered`, `baseAdvanced`) deliberately are NOT:
+      // two accesses agreeing on everything else denote the same cell and print the same subscript
+      // however the machine spelled the offset, so a CSE that collapses them respells nothing.
       const lead = a.lead ?? [];
       const bLead = bb.lead ?? [];
       return (
         a.width === bb.width &&
         a.signed === bb.signed &&
         lead.length === bLead.length &&
-        lead.every((v, i) => v === bLead[i]) &&
+        lead.every((v, i) => exprEquals(v, bLead[i])) &&
+        // `baseElem` is part of the SPELLING for the same reason `lead` is: it decides whether the
+        // base takes the reinterpret cast, so two otherwise-equal nodes disagreeing about it print
+        // two different expressions. (Its one producer derives it from the base and the width, so
+        // nodes that agree on those agree here too — this cannot reject a real CSE.)
+        (a.baseElem === undefined
+          ? bb.baseElem === undefined
+          : bb.baseElem !== undefined && typeEquals(a.baseElem, bb.baseElem)) &&
         exprEquals(a.base, bb.base) &&
         exprEquals(a.idx, bb.idx)
       );
@@ -248,7 +472,7 @@ export function exprEquals(a: Expr, b: Expr): boolean {
     case 'field': {
       const bb = b as typeof a;
       // `dot` is part of the SPELLING, and for the same reason `lead` is compared above: a CSE or
-      // dedup that treats these as equal keeps one node and discards the other, silently respelling
+      // dedup that treats these as equal keeps one node and discards the other, silently rewriting
       // `p->field_4` as `p.field_4` (or the reverse). Both compile only for the base type each
       // belongs to, so collapsing them is how a valid access becomes an invalid one — or worse, a
       // valid one against a different object.
@@ -263,14 +487,6 @@ export function exprEquals(a: Expr, b: Expr): boolean {
   }
 }
 
-// ── the ONE traversal vocabulary ───────────────────────────────────────────────────────────────
-// Every generic walker derives from these helpers, so a NEW node kind is a compile error in
-// exactly one place per union (the switches are exhaustive under noImplicitReturns) — a
-// hand-rolled walker that misses a node kind is a silent bug. Specialized walkers with per-kind
-// SEMANTICS (loop-boundary scans like hasEnclosingContinue, rebuilding transforms like
-// recognizeForLoops) rightly keep their own switches.
-
-/** The direct sub-expressions of `e`, in syntactic order. */
 /** THE spelling of an unmodelled instruction's gap reason, in one place: `structure.ts` writes it
  *  into the marker, `contracts.ts` matches on it to prove the gap was not dropped, and the benchmark
  *  classifies declines by it. Two spellings make that contract silently vacuous — enforced-looking
@@ -279,6 +495,14 @@ export function gapReasonFor(mnemonic: unknown): string {
   return `unmodelled instruction '${typeof mnemonic === 'string' ? mnemonic : '?'}'`;
 }
 
+// ── the ONE traversal vocabulary ───────────────────────────────────────────────────────────────
+// Every generic walker derives from these helpers, so a NEW node kind is a compile error in
+// exactly one place per union (the switches are exhaustive under noImplicitReturns) — a
+// hand-rolled walker that misses a node kind is a silent bug. Specialized walkers with per-kind
+// SEMANTICS (loop-boundary scans like hasEnclosingContinue, rebuilding transforms like
+// recognizeForLoops) rightly keep their own switches.
+
+/** The direct sub-expressions of `e`, in syntactic order. */
 export function exprChildren(e: Expr): Expr[] {
   switch (e.k) {
     case 'var':
@@ -293,7 +517,7 @@ export function exprChildren(e: Expr): Expr[] {
     case 'call':
       return e.args;
     case 'index':
-      return [e.base, e.idx];
+      return [e.base, ...(e.lead ?? []), e.idx];
     case 'field':
       return [e.base];
     case 'marker':
@@ -316,7 +540,7 @@ export function mapExprChildren(e: Expr, f: (c: Expr) => Expr): Expr {
     case 'call':
       return { ...e, args: e.args.map(f) };
     case 'index':
-      return { ...e, base: f(e.base), idx: f(e.idx) };
+      return { ...e, base: f(e.base), ...(e.lead ? { lead: e.lead.map(f) } : {}), idx: f(e.idx) };
     case 'field':
       return { ...e, base: f(e.base) };
     case 'marker':
@@ -349,7 +573,132 @@ export function stmtExprs(s: Stmt): Expr[] {
   }
 }
 
-/** The statements a statement DIRECTLY contains. NOTE for document-order walks: a `for`'s
+/** Rebuild `s` with EVERY expression position mapped through `f` — store lvalues and loop/switch
+ *  heads included, nested statements recursively. The rewrite dual of stmtExprs/stmtChildren, for
+ *  the PURE 1:1 case: one expression in, one expression out, every statement kept.
+ *
+ *  A PASS THAT HAND-ROLLS ITS OWN MAPPER IS NOT A MISSED MIGRATION. Several do, because their
+ *  contract is not this one — a rewrite that may DECLINE, one that INSERTS statements, one that
+ *  rewrites assign TARGETS as well as expressions, one that turns a statement into a list. Check
+ *  the contract before pointing one of them here. */
+export function mapStmtExprs(s: Stmt, f: (e: Expr) => Expr): Stmt {
+  const mapS = (x: Stmt): Stmt => mapStmtExprs(x, f);
+  switch (s.k) {
+    case 'assign':
+      return { ...s, value: f(s.value) };
+    case 'store':
+      return { ...s, lval: f(s.lval), value: f(s.value) };
+    case 'exprstmt':
+      return { ...s, value: f(s.value) };
+    case 'return':
+      return s.value ? { ...s, value: f(s.value) } : s;
+    case 'if':
+      return { ...s, cond: f(s.cond), then: s.then.map(mapS), else: s.else.map(mapS) };
+    case 'while':
+    case 'dowhile':
+      return { ...s, cond: f(s.cond), body: s.body.map(mapS) };
+    case 'for':
+      return { ...s, init: mapS(s.init), cond: f(s.cond), inc: mapS(s.inc), body: s.body.map(mapS) };
+    case 'switch':
+      return {
+        ...s,
+        scrutinee: f(s.scrutinee),
+        cases: s.cases.map((c) => ({ ...c, body: c.body.map(mapS) })),
+        default: s.default?.map(mapS),
+      };
+    case 'break':
+    case 'continue':
+      return s;
+  }
+}
+
+/** An address the target can REMATERIALIZE: a constant expression, reading no variable and no
+ *  memory. Which ENCODING the compiler picked for it is not a property of the source — agbcc
+ *  spells a pool word `(s32 *)33569456` but a shift-encodable one `(s32 *)(128 << 18)`, and every
+ *  GBA hardware region (EWRAM 0x2000000, I/O 0x4000000, VRAM 0x6000000 …) takes the second form —
+ *  so both must reach the same admission or the whole MMIO/VRAM fill family declines on its
+ *  address. A bare `(T *)0` is excluded — a null base is not a walk — but the test is on the
+ *  LITERALS the expression mentions, not on the value they fold to, so `(T *)(5 - 5)` passes.
+ *  Folding would need a constant evaluator no consumer has another use for, and both consumers
+ *  keep the expression verbatim, so no decision downstream reads the value.
+ *
+ *  Two ask it: the walk re-index (l3/reindex.ts) about a walk base, and the `volatile` qualifier
+ *  (l3/volatileptr.ts) about what feeds a pointer local. They must agree — a MMIO fill whose base
+ *  one admits and the other refuses can be re-indexed but never qualified, so the paired
+ *  `/indexed/volatile` spelling is unreachable at exactly the hardware addresses it is for.
+ *
+ *  Two respell variations reading the same initializers are deliberately NOT here: l3/inlinebase.ts
+ *  substitutes the address at each use, l3/nearbase.ts clusters neighbours by distance, and both
+ *  need the VALUE, which is the evaluator above. Declining a shift-encoded base there costs a
+ *  variation that does not fire, and the population is small: over klonoa's 531 lifting functions,
+ *  one inlinebase-shaped local with no symbol map and none with it; a folded nearbase would form
+ *  a new cluster in 4 functions mapless and 1 with the map. Both counts were zero over the agbcc
+ *  benchmark rows that lifted when the variations landed — a MEASUREMENT over a corpus that grows, so
+ *  re-take it rather than quoting it: a new row falsifies the number, not the argument. */
+export function rematerializableAddress(e: Expr): boolean {
+  let nonZero = false;
+  let ok = true;
+  const visit = (x: Expr): void => {
+    switch (x.k) {
+      case 'const':
+        nonZero ||= x.value !== 0;
+        break;
+      case 'cast':
+      case 'bin':
+      case 'un':
+        break;
+      default:
+        ok = false; // var, addr, index, field, call, marker
+        return;
+    }
+    for (const c of exprChildren(x)) {
+      visit(c);
+    }
+  };
+  visit(e);
+  return ok && nonZero;
+}
+
+/** Whether the tree contains a node with an EFFECT no re-ordering may move: a call, or a marker
+ *  standing in for an unmodelled instruction (annotate mode). */
+export function exprHasEffect(e: Expr): boolean {
+  return e.k === 'call' || e.k === 'marker' || exprChildren(e).some(exprHasEffect);
+}
+
+/** Whether the tree performs an access to a `volatile` object — the OTHER thing no re-ordering may
+ *  move, and the one `exprHasEffect` deliberately does not answer: that one is about a call, this
+ *  about a QUALIFIER, and a pass that asks the first where it means the second reorders device
+ *  accesses while its gate reports clean.
+ *
+ *  Three spellings assert one thing, and all three are here because a pass that knew only the cast
+ *  would miss the two a later variation writes: a `volatile` cast (where a raw address carries it), a
+ *  read through a pointer local declared to point at volatile data (l3/volatileptr.ts), and a read
+ *  of a `volatile` local object (l3/volatileval.ts). A bare cast counts even with no deref under it
+ *  — the qualifier is on the ACCESS the cast exists to spell, and every caller so far is asking
+ *  whether it may move the expression rather than how many accesses it holds. */
+export function exprReadsVolatile(e: Expr, sfn: SFn): boolean {
+  const pointee = new Set(sfn.locals.filter((l) => l.pointeeVolatile).map((l) => l.name));
+  const object = new Set(sfn.locals.filter((l) => l.volatile).map((l) => l.name));
+  const namesUnder = (x: Expr): string[] =>
+    [...subterms(x)].filter((y): y is Extract<Expr, { k: 'var' }> => y.k === 'var').map((y) => y.name);
+  return [...subterms(e)].some(
+    (x) =>
+      (x.k === 'cast' && x.volatile === true) ||
+      (x.k === 'var' && object.has(x.name)) ||
+      ((x.k === 'index' || x.k === 'field') && namesUnder(x).some((n) => pointee.has(n))),
+  );
+}
+
+/** every node of an expression tree, itself included */
+function* subterms(e: Expr): Generator<Expr> {
+  yield e;
+  for (const c of exprChildren(e)) {
+    yield* subterms(c);
+  }
+}
+
+/** The statements a statement DIRECTLY contains, in the order a backend prints them — a `switch`
+ *  splices its default in at `defaultAt` for that reason. NOTE for document-order walks: a `for`'s
  *  init/inc are listed here while its cond is in stmtExprs — a walker visiting exprs-then-stmts
  *  sees the cond before the init. */
 export function stmtChildren(s: Stmt): Stmt[] {
@@ -368,18 +717,117 @@ export function stmtChildren(s: Stmt): Stmt[] {
       return s.body;
     case 'for':
       return [s.init, s.inc, ...s.body];
+    case 'switch': {
+      const arms = s.cases.map((c) => c.body);
+      arms.splice(s.defaultAt ?? s.cases.length, 0, s.default ?? []);
+      return arms.flat();
+    }
+  }
+}
+
+/** The nested statement LISTS of a statement — the SCOPES it opens.
+ *
+ *  Deliberately not `stmtChildren`, which flattens a `for`'s `init`/`inc` in with its body: those
+ *  are single statements, not lists. A `for`'s body is the only list here, which is what a caller
+ *  that PLACES into a list wants (`l3/scopebase.ts` — before the loop changes when a statement
+ *  runs, inside the body repeats it) and not what a caller that reads the init as a DEF wants
+ *  (`contracts.ts`'s dominance walk, which descends into the loop's parts itself).
+ *
+ *  It lives here so a new `Stmt` kind carrying a list is one compile error rather than a silent
+ *  miss in each caller's own recursion. Exhaustive on purpose: no `default`.
+ */
+export function stmtLists(s: Stmt): Stmt[][] {
+  switch (s.k) {
+    case 'if':
+      return [s.then, s.else];
+    case 'while':
+    case 'dowhile':
+    case 'for':
+      return [s.body];
+    case 'switch':
+      return [...s.cases.map((c) => c.body), ...(s.default ? [s.default] : [])];
+    case 'assign':
+    case 'store':
+    case 'exprstmt':
+    case 'return':
+    case 'break':
+    case 'continue':
+      return [];
+  }
+}
+
+/** The SETTER half of {@link stmtLists}: `s` with each of its nested lists replaced by `f` applied
+ *  to it, in the same order `stmtLists` yields them. A caller that rebuilds a tree around one
+ *  nested list therefore writes no `Stmt`-kind switch of its own — the pair lives here so a new
+ *  kind carrying a list is a compile error in both halves rather than a silent miss in a caller's
+ *  hand-rolled recursion. Exhaustive on purpose: no `default`. */
+export function mapStmtLists(s: Stmt, f: (list: Stmt[]) => Stmt[]): Stmt {
+  switch (s.k) {
+    case 'if':
+      return { ...s, then: f(s.then), else: f(s.else) };
+    case 'while':
+    case 'dowhile':
+    case 'for':
+      return { ...s, body: f(s.body) };
     case 'switch':
-      return [...s.cases.flatMap((c) => c.body), ...(s.default ?? [])];
+      return {
+        ...s,
+        cases: s.cases.map((c) => ({ ...c, body: f(c.body) })),
+        ...(s.default ? { default: f(s.default) } : {}),
+      };
+    case 'assign':
+    case 'store':
+    case 'exprstmt':
+    case 'return':
+    case 'break':
+    case 'continue':
+      return s;
+  }
+}
+
+/** Every expression node in a body, statements nested and children included — the whole-tree walk
+ *  `stmtChildren`, `stmtExprs` and `exprChildren` compose into, kept here so a new node kind is a
+ *  compile error in one of them rather than a silent miss in each caller's own recursion.
+ *
+ *  An EXPLICIT stack, not `yield*` recursion. A delegated generator costs a frame per nesting
+ *  level on every value it forwards, so an expression ten levels down was handed off ten times; this
+ *  walk runs over a whole function body once per emitted candidate. The stack
+ *  holds either a statement list still to expand or an expression still to visit — `Expr` is
+ *  never an array, so the two are told apart without a tag — and both are pushed in reverse so
+ *  they pop in document order, which is the order the recursion produced. */
+export function* walkExprs(body: Stmt[]): Generator<Expr> {
+  const stack: (Expr | Stmt[])[] = [body];
+  while (stack.length > 0) {
+    const top = stack.pop()!;
+    if (Array.isArray(top)) {
+      for (let i = top.length - 1; i >= 0; i--) {
+        const s = top[i];
+        const children = stmtChildren(s);
+        if (children.length > 0) {
+          stack.push(children);
+        }
+        const exprs = stmtExprs(s);
+        for (let j = exprs.length - 1; j >= 0; j--) {
+          stack.push(exprs[j]);
+        }
+      }
+      continue;
+    }
+    yield top;
+    const children = exprChildren(top);
+    for (let i = children.length - 1; i >= 0; i--) {
+      stack.push(children[i]);
+    }
   }
 }
 
 // THE negation of a CONDITION — the one implementation, shared by every L3 pass that flips one.
 //
-// There were two, and they drifted: structure.ts's empty-then peephole learned to distribute over
-// the short-circuit connectives while l3/dce.ts's copy kept wrapping in `!`, and because
-// `eliminateDeadStores` runs AFTER structuring it re-introduced the very spelling the other one had
-// just removed. That is the l3/hoist.ts failure mode verbatim — a copied helper silently losing the
-// newer rule — so this lives with the AST vocabulary and the passes call it.
+// WHY IT IS SHARED RATHER THAN COPIED PER PASS: the passes that flip a condition do not run at one
+// time. The structurer's empty-then peephole flips one, and `eliminateDeadStores` flips another
+// AFTER structuring — so a copy that lacked a rule the other had would re-introduce the exact
+// spelling the earlier pass just removed, and nothing downstream could tell that apart from a
+// spelling the input really had. The negation therefore lives with the AST vocabulary.
 //
 // Three rules, in order:
 //   1. a relational operator flips directly (`!=` → `==`, `<` → `>=`, …), exact over C's total
@@ -389,7 +837,7 @@ export function stmtChildren(s: Stmt): Stmt[] {
 //      holds. Same operands, same inputs — which is what makes it safe over a `b` that loads. It
 //      matters because a source `&&` and its dual `||` compile to the SAME branch graph, so the
 //      recognizers in raise/shortcircuit.ts can only pick whichever the asm's branch senses spell;
-//      distributing is what lets the `/flip-branch` candidate reach the other one;
+//      distributing is what lets the other one be spelled at all;
 //   3. `!!x` collapses to `x`, reachable only from a double flip that rule 2 now produces.
 //
 // CONTEXT REQUIREMENT, and it is the reason this is `negateCond` and not `negate`: rule 3 is valid
@@ -397,13 +845,16 @@ export function stmtChildren(s: Stmt): Stmt[] {
 // so this must never be used to negate a general integer expression — only an `if`/loop test or an
 // operand of one of the connectives above.
 //
-// SCOPE of rule 2: it only gives the differ a second spelling where a candidate lever already flips
-// the condition, and `preserveDivergentBranchSense` covers divergent `if`s ONLY. A connective that
-// ended up as a LOOP test therefore has no dual candidate at all — the differ never sees the other
-// form, so on such a row this rule changes how the code READS and nothing else. Widening the
-// branch-sense lever to loop tests is what would make it a matching lever there, and that is a
-// separate change.
-const NEGATE_REL: Partial<Record<BinOp, BinOp>> = {
+// SCOPE of rule 2: it fires wherever a branch-sense variation negates the condition, which is both `if`
+// classes — `preserveDivergentBranchSense` on divergent ifs, `negateJoinedBranchSense` on
+// reconverging ones — and on the joined class it is a DEFAULT emission, not a differ-only
+// alternative, so a source `&&` can come out as its `||` dual with no variation asked for
+// (`synthetic:ifand_far`, where the branch range put the fold on the other arm). Neither
+// variation reaches a LOOP test, so a connective that ended up as one has no dual candidate at all —
+// the differ never sees the other form, and on such a row this rule changes how the code READS and
+// nothing else. Widening a branch-sense variation to loop tests is what would make it a matching variation
+// there, and that is a separate change.
+export const NEGATE_REL: Partial<Record<BinOp, BinOp>> = {
   '<': '>=',
   '>=': '<',
   '>': '<=',