@asmlift/core 0.6.0 → 0.8.0

package/src/l3/unreduce.ts

@@ -1,4 +1,4 @@
-// L3 re-spelling lever: UN-REDUCE a loop-carried accumulator — delete `v = INIT; … v = v + K;`
+// L3 respell variation: UN-REDUCE a loop-carried accumulator — delete `v = INIT; … v = v + K;`
 // and spell each read as the closed form `INIT[start := counter]`.
 //
 //     v0 = (a0 << 6) + a1;                    while (v1 <= 31) {
@@ -91,8 +91,8 @@
 //     left. Refused function-wide, because a stashed pointer outlives the statement that made it.
 //   • MOVED-EFFECT — a call or a marker would run once per read instead of once. Refused.
 //   • MOVED-VOLATILE — a `volatile` access is one the source pinned precisely so it would not be
-//     duplicated or moved. Refused. No corpus row reaches it today (nothing on the base spelling
-//     this lever rides carries a qualifier on a READ), so it is guarded by its unit test alone.
+//     duplicated or moved. Refused. No corpus row reaches it today (nothing on the default spelling
+//     this variation rides carries a qualifier on a READ), so it is guarded by its unit test alone.
 //   • MOVED-READ-ALIASABLE — an ordinary memory read moved down the region sees whatever the
 //     region wrote. asmlift can only rule that out for writes it can NAME, so a moved read is
 //     admitted on one configuration: every write the region evaluates goes to a compile-time
@@ -111,7 +111,7 @@
 // is FALSE. "A write to a hardware register is not a write to any object a C program declares" is
 // true, and it does not finish the argument: a DMA controller READS a control word and then WRITES
 // ordinary memory on the program's behalf. On the GBA, storing `0x84000020` to `DMA3CNT`
-// (0x040000DC) starts a 32-word transfer into `[DMA3DAD]` — and every row this lever reaches
+// (0x040000DC) starts a 32-word transfer into `[DMA3DAD]` — and every row this variation reaches
 // drives exactly that register. Modelled and executed, the admitted candidate turns a clean walk
 // over a destination table into wild writes: the first transfer clobbers the table the init reads,
 // and every later iteration recomputes its destination from the garbage.
@@ -147,12 +147,12 @@
 // `firstRejection` call site over both — 750 synthetic trees and all 252 real-tier rows, the real
 // tier being the SYMBOL-MAPPED configuration since every row carries its authored map —
 // `unitsDisagree` is true on NO row in either, and `/unreduce` fires on no real-tier row at all,
-// so no zero-flip gate reaches this lever. Its one known inhabitant is outside the benchmark:
+// so no zero-flip gate reaches this variation. Its one known inhabitant is outside the benchmark:
 // klonoa's `UpdateHUDTimePanel`, where WITH a symbol map the accumulator lifts `u16 *` against an
 // integer init and the gate refuses it, and with RAW ADDRESSES the same asm lifts all-integer and
 // the candidate is correct and survives (`50335396 + (v15 << 6)`, 64 bytes an iteration, which is
 // the ROM's own `adds r1, #0x40`). Same assembly, same loop, same stride — a raw-address sweep is
-// BLIND to the defect and reports the lever as correct. The checkout sweep behind that datum
+// BLIND to the defect and reports the variation as correct. The checkout sweep behind that datum
 // covered klonoa's 467 functions in BOTH configurations; a second checkout was swept raw-only and
 // found nothing, and since raw-only is the blind arm that null result carries no weight. Only the
 // klonoa half of the sweep is evidence, and it is quoted here without the other.
@@ -186,7 +186,7 @@
 // was actually MISSING from that table (`volatile-counter`) is in it now, which is the part that
 // could not wait.
 //
-// Nothing qualifying ⇒ decline (null), never a duplicate of the primary.
+// Nothing qualifying ⇒ decline (null), never a duplicate of the default.
 import { type IrType } from '../ir/types';
 import { cellAddress, inRange, rootConst } from './address';
 import {
@@ -196,6 +196,7 @@ import {
   exprEquals,
   exprHasEffect,
   exprReadsVolatile,
+  isLoop,
   mapExprChildren,
   stmtChildren,
   stmtExprs,
@@ -264,7 +265,7 @@ export const UNREDUCE_GATES: readonly Gate<AccCtx>[] = [
   },
   {
     id: 'acc-pinned',
-    why: 'a declaration that carries an asm fact cannot be deleted without dropping the fact',
+    why: 'a declaration that carries a fact from the assembly cannot be deleted without dropping the fact',
     sound: true,
     guardedBy: 'unreduce.test.ts: a pinned accumulator declines, on every pin a local can carry',
     rejects: (c) => c.pinned,
@@ -344,14 +345,14 @@ export const UNREDUCE_GATES: readonly Gate<AccCtx>[] = [
   },
   {
     id: 'nonzero-start',
-    why: 'a counter starting at a nonzero constant leaves a bias term this file does not spell',
+    why: 'a counter starting at a nonzero constant leaves a bias term this rewrite does not write',
     sound: true,
     guardedBy: 'unreduce.test.ts: a counter-free init declines unless its start is the constant 0',
     rejects: (c) => c.declined === 'nonzero-start',
   },
   {
     id: 'step-ratio',
-    why: 'a counter stepping by more than one leaves the ratio K/d, which is not a shift',
+    why: 'a counter stepping by more than one leaves a ratio between the two steps, which is not a shift',
     sound: true,
     guardedBy: 'unreduce.test.ts: a counter-free init declines when the counter does not step by one',
     rejects: (c) => c.declined === 'step-ratio',
@@ -426,7 +427,7 @@ function arithScale(t: IrType | undefined): number | null {
 /** Does this local's DECLARATION pin it against deletion? Every flag `SFn.locals` can carry, because
  *  each is a fact about the ASM that only the declaration states: two qualifiers (deleting a
  *  `volatile u16 *` local re-spells `*p = 0` as a raw cast with no qualifier on it — l3/inlinebase.ts
- *  carries it onto the minted cast instead, and this lever has no local left to carry anything), a
+ *  carries it onto the minted cast instead, and this variation has no local left to carry anything), a
  *  frame home, an `undef` whose whole content is the assignment that is MISSING, and the SPILL HOMES.
  *
  *  WHY `slots` PINS, which is not the obvious reading. Deleting a slot-carrying local does not
@@ -537,7 +538,7 @@ function relate(init: Expr, start: Expr, ctr: string, k: Expr, d: number): Relat
     return null; // anything else between the root and the counter, and the stride is not `k`
   };
   // THE SUBSTITUTIONAL FORM FIRST, unchanged: it is the shipped spelling every corpus inhabitant
-  // of this lever rides, and trying it first makes the branch below strictly additive — it is
+  // of this variation rides, and trying it first makes the branch below strictly additive — it is
   // reached only where the old rule already declined, so it can admit candidates but never
   // re-spell one.
   //
@@ -796,7 +797,7 @@ export interface UnreduceResult {
 
 /** The `/unreduce` candidate, or null when no accumulator qualifies. `window` is the target's
  *  declared device-register range (TargetDescription.capabilities.deviceRegisters) — absent, the
- *  lever still fires on a closed form that reads no memory. `triggers` is
+ *  variation still fires on a closed form that reads no memory. `triggers` is
  *  `capabilities.deviceMemoryWriters`; absent, EVERY device store is treated as one. */
 export function unreduceAccumulators(
   sfn: SFn,
@@ -813,7 +814,7 @@ export function unreduceAccumulators(
 
   for (let li = 0; li < body.length; li++) {
     const loop = body[li];
-    if (loop.k !== 'while' && loop.k !== 'dowhile' && loop.k !== 'for') {
+    if (!isLoop(loop)) {
       continue;
     }
     // the counter: one name stepped by a constant, whose start stands above the loop

package/src/l3/volatileptr.ts

@@ -1,4 +1,4 @@
-// L3 re-spelling lever: declare a pointer local that holds a NUMERIC address as pointing to
+// L3 respell variation: 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
@@ -8,7 +8,7 @@
 // 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
+// form as rank.ts `/volatile`, per-local subsets as its results named by subject — and the differ
 // referees.
 //
 // SEMANTICS ARE PRESERVED BY CONSTRUCTION: `volatile` only RESTRICTS what a compiler may do
@@ -25,7 +25,7 @@
 // `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.
+// (null), so the variation never emits a duplicate of the default.
 import { addrConst, cellAddress, inRange } from './address';
 import { type Expr, type SFn, type Stmt, mapExprChildren, rematerializableAddress, walkExprs } from './ast';
 
@@ -72,7 +72,7 @@ function collectAssigns(stmts: Stmt[], out: { name: string; value: Expr }[]): vo
 }
 
 /** 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.
+ *  volatility tie-break, so it is counted here beside the variation 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
@@ -119,7 +119,7 @@ export function deviceVolatileClaims(sfn: SFn, window?: readonly [number, number
   return n;
 }
 
-/** The locals the lever would qualify — the per-local SUBSET enumeration's input (below):
+/** The locals the variation 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
@@ -172,10 +172,10 @@ function eligibility(sfn: SFn): (l: SFn['locals'][number]) => boolean {
     !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
+/** The proper non-empty SUBSETS of the qualifying locals (within `within`, when given) as the
+ *  results of a multi-result variation — one candidate per subset, its members named as the subject. Empty above
  *  three qualifiers: the arm is capped at 6 extra spellings, and the all-qualifiers form is the
- *  plain lever's own candidate. */
+ *  plain variation'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) {
@@ -193,9 +193,9 @@ export function volatileSubsetCandidates(sfn: SFn, within?: ReadonlySet<string>)
 }
 
 /** 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
+ *  sharing the (unmodified) body. `only` narrows the variation to the named locals — a /volatile
+ *  composition (rank.ts) qualifies just the locals its first variation centres on (kept walk bases,
+ *  created hoists), so the composition 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);

package/src/l3/volatileval.ts

@@ -1,11 +1,11 @@
-// L3 re-spelling lever: declare a stack-homed scalar local `volatile` (`volatile u16 sp0;`).
+// L3 respell variation: 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.
+// sibling pointee variation (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
@@ -15,7 +15,7 @@
 // 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
+// its own, so this variation 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:
@@ -27,7 +27,7 @@
 //     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.
+//     candidate would duplicate the default.
 //   • 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,
@@ -38,14 +38,14 @@
 //     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
+//     by the ABSENCE of the flag this variation 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.
+// No qualifying local ⇒ decline (null), so the variation never emits a duplicate of the default.
 //
-// ALL ELIGIBLE SLOTS OR NONE, where the sibling pointee lever enumerates per-local SUBSETS on the
+// ALL ELIGIBLE SLOTS OR NONE, where the sibling pointee variation 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
@@ -67,7 +67,7 @@ interface SlotCtx {
 export const VOL_SLOT_GATES: readonly Gate<SlotCtx>[] = [
   {
     id: 'no-frame',
-    why: 'the frame record is the memory home the qualifier has to force',
+    why: 'without a stack slot in the assembly there is no memory for the qualifier to force the local into',
     sound: false,
     rejects: (c) => !c.hasFrame,
   },
@@ -80,19 +80,19 @@ export const VOL_SLOT_GATES: readonly Gate<SlotCtx>[] = [
   },
   {
     id: 'already-volatile',
-    why: 'the primary already declares it, so the candidate would duplicate it',
+    why: 'the default 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',
+    why: 'an address-taken local already lives in memory, so the qualifier has nothing 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',
+    why: 'the qualifier asserts every access written is performed, so the lifted code must write exactly the accesses the machine performed',
     sound: true,
     guardedBy: 'volatileval.test.ts: a store the tree no longer carries declines',
     rejects: (c) => !c.accessSetKept,

package/src/l3/volstore.ts

@@ -1,9 +1,9 @@
-// L3 re-spelling lever: pin a STORE at a fixed DEVICE-REGISTER address `volatile`
+// L3 respell variation: 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
+// argues. That variation 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.
 //
@@ -36,13 +36,13 @@
 // 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.
+// of the default.
 //
 // 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
+// the differ can only referee by luck. Measured by running the variation 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
@@ -53,31 +53,31 @@
 // 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
+// `kleod:WritePaletteColor:agbcc` (retired 2026-09-13), then a published byte-exact MATCH whose winning source contained
 // `*(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.
+// this variation produces, at an address this variation'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
+// then carries that codegen fact onto each cast it leaves behind. This variation 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
+// declared, a number supports nothing. The window is where THIS variation'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 —
+// homes and its raw-constant stores together, and over 834 corpus trees both variations 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`
+// A variation 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.)
@@ -85,11 +85,11 @@
 // 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
+// `/reread-globals` referees as a structure variation. 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
+// that read and the row scores 15. This variation 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
+// both configurations and with any window. No row demands the read spelling, and a variation with no
 // inhabitant is what "earn the level" forbids.
 import { type IrType, T, scalarTypeForAccess } from '../ir/types';
 import { cellAddress, inRange } from './address';
@@ -114,7 +114,7 @@ interface AccessCtx {
 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',
+    why: 'a target that declares no device range has no address this variation may call volatile',
     sound: false,
     rejects: (c) => !c.hasWindow,
   },
@@ -127,9 +127,9 @@ export const VOL_STORE_GATES: readonly Gate<AccessCtx>[] = [
   {
     // 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.
+    // paragraph. This gate is about what THIS variation 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',
+    why: 'the address is the only evidence this variation has, and outside the window it supports nothing',
     sound: false,
     rejects: (c) => !c.inWindow,
   },

package/src/l3/zerosub.ts

@@ -1,4 +1,4 @@
-// L3 re-spelling lever: spell a negate of a SHARED subtraction as `0 - x`.
+// L3 respell variation: 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)"
@@ -23,20 +23,20 @@
 // 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
+// A RESPELL VARIATION rather than a fourth value-home structure variation (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`
+// `-` scores 1. asmlift cannot spell it — all three home variations 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
+// value with three consumers. A structure variation 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.
+// distinct tree carrying the shape. Take the structure variation 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 —
+// firing there could only duplicate the default. 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';
 

package/src/mangle.ts

@@ -129,6 +129,55 @@ export function demangle(sym: string): CppSig | null {
   return { name, cls, params };
 }
 
+/** A class qualifier off the front of `s` — `12RefCountable`, or `Q23zen17particleGenerator` for a
+ *  nested one — as its scope names and the remaining string; null when `s` does not open with one. */
+function parseQualifier(s: string): { scopes: string[]; rest: string } | null {
+  const nested = /^Q(\d)/.exec(s);
+  let count = nested === null ? 1 : Number(nested[1]);
+  let rest = nested === null ? s : s.slice(2);
+  const scopes: string[] = [];
+  for (; count > 0; count--) {
+    const digits = /^(\d+)/.exec(rest);
+    if (digits === null) {
+      return null;
+    }
+    const len = Number(digits[1]);
+    const id = rest.slice(digits[1].length, digits[1].length + len);
+    if (len === 0 || id.length !== len) {
+      return null;
+    }
+    scopes.push(id);
+    rest = rest.slice(digits[1].length + len);
+  }
+  return { scopes, rest };
+}
+
+/** The name a CodeWarrior function symbol has in its SOURCE — `PlayerState::getStartHour` for
+ *  `getStartHour__11PlayerStateFv`, `zen::particleGenerator::RotAxisX` for a nested class, and the
+ *  constructor and destructor spelled as they are declared (`RefCountable::RefCountable`,
+ *  `System::~System`). Only the name: unlike `demangle` it reads no parameter code, so it answers
+ *  for the references, arrays and const qualifiers that one refuses. Null where `sym` is not a
+ *  mangled function, and for an operator, whose source name is not an identifier. */
+export function demangledName(sym: string): string | null {
+  for (let at = sym.indexOf('__', 1); at > 0; at = sym.indexOf('__', at + 1)) {
+    const name = sym.slice(0, at);
+    const rest = sym.slice(at + 2);
+    const qualified = /^[\dQ]/.test(rest) ? parseQualifier(rest) : { scopes: [], rest };
+    if (qualified === null || !/^C?F/.test(qualified.rest)) {
+      continue;
+    }
+    const { scopes } = qualified;
+    const cls = scopes.at(-1);
+    // every other special name — `__as`, `__nw`, `__pl` — is an operator
+    const member = name === '__ct' ? cls : name === '__dt' && cls !== undefined ? `~${cls}` : name;
+    if (member === undefined || member.startsWith('__')) {
+      return null;
+    }
+    return [...scopes, member].join('::');
+  }
+  return null;
+}
+
 /** Spell a CppType as C++ source (`Vec *`, `unsigned int`). */
 export function spellType(t: CppType): string {
   return t.base + (t.ptr ? ' ' + '*'.repeat(t.ptr) : '');