@asmlift/core 0.6.0 → 0.8.0

package/src/l3/argbase.ts

@@ -1,4 +1,4 @@
-// L3 re-spelling lever: materialize the deref BASES of a call's arguments into locals, before the
+// L3 respell variation: materialize the deref BASES of a call's arguments into locals, before the
 // call.
 //
 // When a call's arguments are each a deref through a different fixed address, the compiler loads
@@ -16,9 +16,9 @@
 // order names the bases first (`vu8 *p = &REG_VCOUNT_L; u8 *e = gEntityArray; f(*p, e[8])`), which
 // is what a decomp author writes and what this pass reproduces.
 //
-// A LEVER, not a rewrite: it is emitted as an ADDITIONAL candidate (rank.ts `/argbase`) and the
+// A VARIATION, not a committed rewrite: it is emitted as an ADDITIONAL candidate (rank.ts `/argbase`) and the
 // differ referees, so the inline spelling is always still there to win. That is what bounds the
-// risk — a lever that replaced the primary could lose a match, this one cannot.
+// risk — a rewrite that replaced the default could lose a match, this one cannot.
 //
 // SEMANTICS ARE PRESERVED BY CONSTRUCTION, which matters because on a NONMATCH row the
 // best-scoring candidate is what the user is shown. Only a PURE leaf base is eligible — a global's
@@ -29,7 +29,7 @@
 // KNOWN LIMITATION: the hoisted local is a plain `T *` — `IrType` models no cv-qualifier at all,
 // so naming a VOLATILE cell through it drops the qualifier that macros.ts goes out of its way to
 // carry. Pre-existing and not introduced here (every pointer local in the tower has it), but the
-// two features meet on exactly the MMIO shape this lever targets, so it is written down rather
+// two features meet on exactly the MMIO shape this variation targets, so it is written down rather
 // than left to be rediscovered.
 //
 // GATE: at least TWO arguments of the same call must qualify, with DISTINCT bases. The reordering
@@ -39,7 +39,7 @@
 // leaves the diff at 2; both together take it to 0.)
 import { type IrType, T, scalarTypeForAccess } from '../ir/types';
 import type { Expr, SFn, Stmt } from './ast';
-import { mapExprChildren, stmtExprs } from './ast';
+import { isLoop, mapExprChildren, stmtExprs } from './ast';
 import { nameAllocator } from './hoist';
 import { declaredGlobals } from './storage';
 
@@ -133,7 +133,7 @@ export function materializeArgBases(sfn: SFn): SFn | null {
     // had. That is the register-pressure failure basecse.ts's `inLoop` gate exists to refuse, and
     // it would contradict this pass's own placement rule two comments down. So a loop's condition
     // is left alone; only its body (via the recursion) is eligible.
-    const ownExprs = s.k === 'while' || s.k === 'dowhile' || s.k === 'for' ? [] : stmtExprs(s);
+    const ownExprs = isLoop(s) ? [] : stmtExprs(s);
     for (const e of ownExprs) {
       const scan = (x: Expr): void => {
         if (x.k === 'call') {

package/src/l3/argcopy.ts

@@ -0,0 +1,269 @@
+// L3 respell variation: copy a pointer PARAMETER into a local for ONE REGION.
+//
+// A pointer parameter that a whole function reads pins its incoming register for the whole body.
+// A source that instead copies it into a local — `u8 *b = a0;` at the head of the block that uses
+// it — hands the allocator a SECOND name for the same address, which it may home in a different
+// register, freeing the parameter's for something else. On
+// pokeemerald:SetMauvilleOldManLanguage:agbcc that something else is the arm's loop counter: the
+// target copies the base with `adds r6, r5, #0` and then counts in r5.
+//
+// WHY THIS IS NOT ANY OF ITS NEIGHBOURS. `l3/scopebase.ts` hoists one base per region too, but the
+// value it hoists is the ADDRESS OF A GLOBAL (`(T *)&gSym`) and its `shadowed-or-nonarray-base`
+// rule refuses a `var` base precisely because `&local` names a different object; a parameter
+// already HOLDS the pointer, so nothing is addressed and that rule's argument does not reach here.
+// `l3/argbase.ts` names a call argument's fixed addresses, `l3/inlinebase.ts` DELETES a
+// constant-address local, and `l3/parkfirst.ts` only reorders a copy the tree already has. None of
+// them mints `b = a0`.
+//
+// THE COPY IS A PLAIN LOCAL, NOT A SCOPED DECLARATION. Both spellings — a braced region
+// declaration, and a function-top local assigned at the head of the region — were taken through
+// this row's own agbcc and produce the same bytes, so this pass emits the one L3 already spells
+// and adds no block-scope representation to carry a distinction no object shows.
+//
+// WHAT IT GIVES UP, NAMED. A pointer parameter read only inside a loop that sits at FUNCTION TOP
+// LEVEL gets no candidate at all: `regions()` does not offer the function's own list, so the only
+// region over those reads is the loop body, and `loop-region` refuses it. That population — a base
+// live across a top-level loop — is `/livebase` and `/hipress`'s, and the decline is deliberate.
+// The spelling that shape wants is a copy placed BEFORE the loop with only the loop's reads
+// repointed: a copy SITE separate from its region, which nothing here represents. Relaxing
+// `loop-region` does not reach it — it mints the per-iteration copy that rule exists to refuse.
+//
+// WHAT IS ENUMERATED, AND WHY. Which region the source copied in is not derivable from the tree,
+// so every legal region is offered as its own candidate and the differ referees — the `/regcopy`
+// idiom this file shares with `l3/coalesce.ts`. Uses OUTSIDE the chosen region keep naming the
+// parameter, which is the point: the copy is what makes the two live ranges separable.
+//
+// IT KEEPS ITS OWN REGION WALK, AND THAT IS A SECOND REGION MODEL. `l3/scopebase.ts` ships one
+// already, and this is a narrower duplicate; merging them is the right end state. What blocks that
+// is the SAFETY OBLIGATION, not the region question. scopebase hoists a pure ADDRESS and
+// discharges its obligation by PLACEMENT — `assertHoistsDominate` re-walks the emitted tree to
+// check the hoist dominates every use it repointed. This pass hoists a VALUE the caller passed:
+// its obligation is a whole-function invariance fact (`assigned`, `addressed`) that no placement
+// check can see, and it needs no dominance check at all, because uses outside the region are not
+// repointed. One table over both would need scopebase's `collect()` to admit a plain `var` read
+// as a site and `AccessCtx`/`keyOf` to key a parameter — a widening of a file four shipped
+// variations rest on. Until then every walk HERE goes through `ast.ts`'s shared ones, so the two
+// models at least cannot disagree about what a statement contains.
+import type { Expr, SFn, Stmt } from './ast';
+import { isLoop, mapExprChildren, mapStmtExprs, mapStmtLists, stmtChildren, stmtLists, walkExprs } from './ast';
+import { type Gate, firstRejection } from './gates';
+import { nameAllocator } from './hoist';
+
+/** One candidate copy, as the gates see it. */
+export interface ArgCopyCtx {
+  /** the parameter being copied */
+  readonly param: string;
+  /** the parameter's declared type is a pointer — the register this variation is about is a base */
+  readonly isPointer: boolean;
+  /** the function assigns the parameter somewhere, so a copy taken earlier can go stale */
+  readonly assigned: boolean;
+  /** `&param` occurs, so the copy is a DIFFERENT object and any write through the address misses it */
+  readonly addressed: boolean;
+}
+
+/** The admission rules. The two SOUND ones are the whole soundness argument: with the parameter
+ *  never assigned and never addressed, the copy holds the parameter's value at every point the
+ *  region can reach, so repointing the region's reads at it renames a value rather than changing
+ *  one. Drop either and the rewrite names different memory — C that compiles and scores.
+ *
+ *  Both are decided over the WHOLE tree — see `countReads` on why every walk in this file goes
+ *  through `stmtChildren`/`walkExprs`. A gate that called itself sound while judging a subset of the
+ *  statements `repoint` rewrites would be sound about a function nobody compiles. */
+export const ARGCOPY_GATES: readonly Gate<ArgCopyCtx>[] = [
+  {
+    id: 'non-pointer',
+    why: 'the freed register is a base register, and a scalar parameter does not hold one',
+    sound: false,
+    rejects: (c) => !c.isPointer,
+  },
+  {
+    id: 'assigned',
+    why: 'the function assigns the parameter, so the copy would hold a value the parameter no longer has',
+    sound: true,
+    guardedBy: 'argcopy.test.ts: a parameter a `for` header ADVANCES is never copied',
+    rejects: (c) => c.assigned,
+  },
+  {
+    id: 'addressed',
+    why: 'taking the parameter’s address names its own cell, and the copy is a different cell',
+    sound: true,
+    guardedBy: 'argcopy.test.ts: a parameter whose ADDRESS is taken in a `for` header is never copied',
+    rejects: (c) => c.addressed,
+  },
+];
+
+/** One candidate REGION, as the region rules see it. Separate from {@link ARGCOPY_GATES} for the
+ *  reason `scopebase` keeps two tables: those rules judge the PARAMETER once, these judge each
+ *  place it could be copied, and a refusal tally that mixed the two would count a parameter's
+ *  single verdict once per region. */
+export interface ArgCopyRegionCtx {
+  /** reads of the parameter inside this region */
+  readonly reads: number;
+  /** a loop encloses the region — its own body, or any list nested below one */
+  readonly underLoop: boolean;
+}
+
+/** Which regions are worth offering. NEITHER is sound — each refuses a spelling that is correct
+ *  but models nothing, and what they buy is the candidate count: every one of these is a COMPILE,
+ *  and this variation multiplies with `/coalesce`. */
+export const ARGCOPY_REGION_GATES: readonly Gate<ArgCopyRegionCtx>[] = [
+  {
+    id: 'single-read',
+    why: 'a region reading the parameter once gives the allocator no live range to shorten, so the copy buys nothing',
+    sound: false,
+    rejects: (c) => c.reads < 2,
+  },
+  {
+    id: 'loop-region',
+    why: 'a copy anywhere inside a loop re-runs every iteration, so it belongs to a region that holds the loop instead — and no region does when the loop is at function top level, where this variation offers nothing at all',
+    sound: false,
+    // the second clause has its own test, which `guardedBy` cannot also name (one title per gate):
+    // `argcopy.test.ts: a TOP-LEVEL loop is offered NOTHING`
+    guardedBy: 'argcopy.test.ts: an arm NESTED inside a loop body is refused too',
+    rejects: (c) => c.underLoop,
+  },
+];
+
+/** How many `var n` leaves the region holds, nested statements included — the region rules'
+ *  yardstick for whether a copy has a range to shorten.
+ *
+ *  `walkExprs` (ast.ts) is the whole-tree walk, which descends through `stmtChildren` and so sees a
+ *  `for`'s `init` and `inc`. That is the walk this file must use everywhere: `repoint` rewrites
+ *  those two statements (`mapStmtExprs` recurses into them), so a count taken with `stmtLists` —
+ *  which deliberately omits them, being a walk over the SCOPES a statement opens — would report
+ *  fewer reads than the rewrite touches. */
+function countReads(list: Stmt[], n: string): number {
+  let reads = 0;
+  for (const e of walkExprs(list)) {
+    if (e.k === 'var' && e.name === n) {
+      reads++;
+    }
+  }
+  return reads;
+}
+
+/** Every nested statement list in `body`, each with the path that reaches it — a REGION is any
+ *  list a statement contains, which is what a `case` body, an `if` arm and a loop body all are.
+ *  The function's own top-level list is NOT among them: repointing it renames the parameter over
+ *  the whole function, which is a PARK — the shape `l3/parkfirst.ts` reorders — and not the two
+ *  separable live ranges this variation is about. */
+function regions(body: Stmt[]): { at: number[]; list: Stmt[]; underLoop: boolean }[] {
+  const out: { at: number[]; list: Stmt[]; underLoop: boolean }[] = [];
+  // carried DOWN rather than read off the immediate parent: an `if` arm two levels inside a loop
+  // body re-runs every iteration exactly as the body does, which is what `loop-region` refuses
+  const walk = (list: Stmt[], path: number[], underLoop: boolean): void => {
+    list.forEach((st, i) => {
+      const inside = underLoop || isLoop(st);
+      stmtLists(st).forEach((inner, j) => {
+        const here = [...path, i, j];
+        out.push({ at: here, list: inner, underLoop: inside });
+        walk(inner, here, inside);
+      });
+    });
+  };
+  walk(body, [], false);
+  return out;
+}
+
+/** `list` with every `var n` leaf rewritten to `var to`, nested statements included. Both kind
+ *  switches are ast.ts's, so a new statement or expression kind is that file's problem, not this
+ *  one's.
+ *
+ *  ONE walk: `mapStmtExprs` already recurses into every nested statement — a `for`'s `init`/`inc`
+ *  included, which is what makes this symmetric with `countReads` — so a single `map` over the list
+ *  reaches the whole subtree. Driving it through `mapStmtLists` as well would visit a statement at
+ *  depth d once per level above it: 40 expression visits against 13 on a five-level tree (switch >
+ *  for > do-while > if > store). This runs once per region per parameter per candidate, and each
+ *  candidate is a compile. */
+function repoint(list: Stmt[], n: string, to: string): Stmt[] {
+  const inExpr = (e: Expr): Expr => (e.k === 'var' && e.name === n ? { ...e, name: to } : mapExprChildren(e, inExpr));
+  return list.map((s) => mapStmtExprs(s, inExpr));
+}
+
+/** Replace the region at `at` with `next`. */
+function replaceRegion(body: Stmt[], at: number[], next: Stmt[]): Stmt[] {
+  const [i, j, ...rest] = at;
+  return body.map((st, k) => {
+    if (k !== i) {
+      return st;
+    }
+    let seen = -1;
+    return mapStmtLists(st, (inner) => {
+      seen++;
+      if (seen !== j) {
+        return inner;
+      }
+      return rest.length ? replaceRegion(inner, rest, next) : next;
+    });
+  });
+}
+
+/** `argCopyCandidates` with the gate table supplied plus which gate refused each parameter — the
+ *  same ablation-as-a-value seam the coalescer provides. */
+export function argCopyUnder(
+  gates: readonly Gate<ArgCopyCtx>[],
+  sfn: SFn,
+  regionGates: readonly Gate<ArgCopyRegionCtx>[] = ARGCOPY_REGION_GATES,
+): { candidates: { merged: string; sfn: SFn }[]; refusals: Map<string, number> } {
+  const refusals = new Map<string, number>();
+  const out: { merged: string; sfn: SFn }[] = [];
+  /** `&n` anywhere in the function — every expression node, `for` header included. */
+  const addressed = (n: string): boolean => {
+    for (const e of walkExprs(sfn.body)) {
+      if (e.k === 'addr' && e.name === n) {
+        return true;
+      }
+    }
+    return false;
+  };
+  /** The function assigns `n` anywhere. `stmtChildren`, never `stmtLists`: a `for`'s `init` and
+   *  `inc` are STATEMENTS rather than lists, and an induction step that advances the parameter is
+   *  exactly one of them — the shape `structure/structure.ts`'s `recognizeForLoops` mints. */
+  const assignsTo = (n: string, list: Stmt[] = sfn.body): boolean =>
+    list.some((st) => (st.k === 'assign' && st.name === n) || assignsTo(n, stmtChildren(st)));
+  for (const p of sfn.params) {
+    const refused = firstRejection(gates, {
+      param: p.name,
+      isPointer: p.type.kind === 'ptr',
+      assigned: assignsTo(p.name),
+      addressed: addressed(p.name),
+    });
+    if (refused !== null) {
+      refusals.set(refused, (refusals.get(refused) ?? 0) + 1);
+      continue;
+    }
+    for (const r of regions(sfn.body)) {
+      // not a gate: a region with no read of the parameter has nothing to repoint
+      const reads = countReads(r.list, p.name);
+      if (reads === 0) {
+        continue;
+      }
+      const regionRefused = firstRejection(regionGates, { reads, underLoop: r.underLoop });
+      if (regionRefused !== null) {
+        refusals.set(regionRefused, (refusals.get(regionRefused) ?? 0) + 1);
+        continue;
+      }
+      // allocated against the ORIGINAL function, so every candidate names its copy identically —
+      // each is a separate tree and none of them ever meets another
+      const name = nameAllocator(sfn)();
+      const copied = [
+        { k: 'assign', name, value: { k: 'var', name: p.name } } as Stmt,
+        ...repoint(r.list, p.name, name),
+      ];
+      out.push({
+        merged: `${p.name}@${r.at.join('.')}`,
+        sfn: {
+          ...sfn,
+          body: replaceRegion(sfn.body, r.at, copied),
+          locals: [...sfn.locals, { name, type: p.type }],
+        },
+      });
+    }
+  }
+  return { candidates: out, refusals };
+}
+
+/** Every legal region copy, each as its own tree. */
+export function argCopyCandidates(sfn: SFn): { merged: string; sfn: SFn }[] {
+  return argCopyUnder(ARGCOPY_GATES, sfn).candidates;
+}

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 }
@@ -74,7 +74,7 @@ export type Expr =
   //   • 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 axis and lives one level down at L2
+  //                         `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`.
@@ -96,6 +96,16 @@ export type Expr =
   // 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;
@@ -103,8 +113,35 @@ export type 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).
@@ -145,7 +182,7 @@ export type Expr =
 //
 // 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 an axis, while a
+// 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 =
   | '+'
@@ -229,7 +266,13 @@ export type Stmt =
   // 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 };
+  // `unspelled` — the assembly shows no `return` STATEMENT behind this node: the machine reached
+  // the epilogue here by falling into it, or on a conditional branch's own edge, never by the
+  // `b <epilogue>` a source `return;` compiles to (structure.ts sets it; the reading is stated
+  // there). A void return is then a no-op wherever nothing follows it, and `l3/tailret.ts` drops
+  // it — which is not cosmetic: unoptimised code gives every source `return;` a branch of its own,
+  // so the redundant spelling costs bytes. Advice about SPELLING; nothing may read it as semantics.
+  | { k: 'return'; value?: Expr; unspelled?: true };
 
 /** One arm of a `switch`. `values` stacks multiple `case K:` labels onto one body (`case 1: case 2:`).
  *  `fallsThrough` true ⇒ the body flows into the NEXT arm (no `break;`); see the non-neutrality note. */
@@ -245,7 +288,7 @@ export interface SFn {
   /** 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 lever; a declaration
+   *  = 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
@@ -254,7 +297,7 @@ export interface SFn {
    *  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 lever must match before it may
+   *  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
@@ -312,7 +355,7 @@ export interface SFn {
    *  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 per-compiler default declared in
+   *  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';
@@ -396,7 +439,7 @@ export function exprEquals(a: Expr, b: Expr): boolean {
       const bb = b as typeof a;
       // `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
-      // respelling a volatile access as a plain one.
+      // rewriting a volatile access as a plain one.
       return (
         JSON.stringify(a.to) === JSON.stringify(bb.to) &&
         (a.volatile ?? false) === (bb.volatile ?? false) &&
@@ -411,9 +454,9 @@ 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.
-      // `operandOff` deliberately is 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.
+      // 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 (
@@ -421,6 +464,13 @@ export function exprEquals(a: Expr, b: Expr): boolean {
         a.signed === bb.signed &&
         lead.length === bLead.length &&
         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)
       );
@@ -428,7 +478,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.
@@ -533,7 +583,7 @@ export function stmtExprs(s: Stmt): Expr[] {
  *  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 LEVER THAT HAND-ROLLS ITS OWN MAPPER IS NOT A MISSED MIGRATION. Several do, because their
+ *  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. */
@@ -583,13 +633,13 @@ export function mapStmtExprs(s: Stmt, f: (e: Expr) => Expr): Stmt {
  *  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 levers reading the same initializers are deliberately NOT here: l3/inlinebase.ts
+ *  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
- *  lever that does not fire, and the population is small: over klonoa's 531 lifting functions,
+ *  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 levers landed — a MEASUREMENT over a corpus that grows, so
+ *  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;
@@ -626,8 +676,8 @@ export function exprHasEffect(e: Expr): boolean {
  *  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 lever that knew only the cast
- *  would miss the two a later lever writes: a `volatile` cast (where a raw address carries it), a
+ *  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
@@ -681,6 +731,44 @@ export function stmtChildren(s: Stmt): Stmt[] {
   }
 }
 
+/** A statement that REPEATS what it contains — what {@link isLoop} narrows to.
+ *
+ *  Derived STRUCTURALLY, not from a second list of kinds: a repeating statement is exactly one that
+ *  carries both a `cond` and a `body`, and no other `Stmt` carries both (`if` has `cond` without
+ *  `body`, `switch` has neither). A new repeating kind therefore joins this type by construction,
+ *  where a hand-written kind list falls out of step SILENTLY — TypeScript does not check a
+ *  predicate's body against the type it asserts. */
+export type Loop = Extract<Stmt, { cond: Expr; body: Stmt[] }>;
+
+/** Does this statement REPEAT what it contains? Its body and its own condition run once per
+ *  iteration, which is the fact half of `l3/` asks about: a hoist out of one is loop-invariant
+ *  code motion, a copy inside one re-runs, and a live range that crosses one is under pressure.
+ *
+ *  It lives here, exhaustive and with no `default`, for the reason {@link stmtLists} does: a new
+ *  `Stmt` kind that repeats is then a compile error at ONE site rather than a silent `false` in
+ *  each caller's own hand-spelled kind test. It NARROWS to {@link Loop} rather than returning
+ *  `boolean`, because a caller that reaches `body` afterwards cannot use a `boolean` one and spells
+ *  the kind test out again instead. `backend/pascal.ts` is where that costs correctness: its
+ *  `hasReturn` walk decides a LOUD failure — Pascal's `case-of` cannot spell an early `return` — so
+ *  a repeating kind read as a non-loop turns the refusal into an emitted miscompile. */
+export function isLoop(s: Stmt): s is Loop {
+  switch (s.k) {
+    case 'while':
+    case 'dowhile':
+    case 'for':
+      return true;
+    case 'if':
+    case 'switch':
+    case 'assign':
+    case 'store':
+    case 'exprstmt':
+    case 'return':
+    case 'break':
+    case 'continue':
+      return false;
+  }
+}
+
 /** 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
@@ -801,14 +889,14 @@ export function* walkExprs(body: Stmt[]): Generator<Expr> {
 // 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 fires wherever a branch-sense lever negates the condition, which is both `if`
+// 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 lever asked for
+// 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
-// lever reaches a LOOP test, so a connective that ended up as one has no dual candidate at all —
+// 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 lever to loop tests is what would make it a matching lever
+// 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>> = {
   '<': '>=',