@asmlift/core 0.6.0 → 0.8.0

package/src/l3/homesplit.ts

@@ -1,7 +1,7 @@
 // The `/livebase-block × /regionbase` PAIRING (rank.ts `/livebase-block/homesplit`): one base kept
 // at the function head and a SECOND base split into one local per region, in the same function.
 //
-// WHY IT IS NOT REACHABLE FROM EITHER LEVER. Both are whole-FUNCTION policies over the bases they
+// WHY IT IS NOT REACHABLE FROM EITHER VARIATION. Both are whole-FUNCTION policies over the bases they
 // bind: `hoistBaseLocals` homes every key its table admits at one placement, and
 // `hoistScopedBases` splits every key its region rule admits. A function whose two bases want
 // OPPOSITE answers is spelled by neither. `synthetic:dmapoll` is that function and its endpoint is
@@ -19,9 +19,9 @@
 // over ONE input is the shape that would collide, and nothing here does it.
 //
 // WHICH KEY IS WITHHELD IS NOT DERIVABLE, so every admitted key is offered as its own candidate,
-// LABELLED WITH THAT KEY, and the differ referees — the same posture `/scopebase` and `/regionbase`
-// take toward each other. The label carries `homeSplitTag(key)` because a candidate label is an
-// IDENTITY: `bench diff` and docs/ranked-repro.md compare candidates by it, so one label over two
+// NAMED BY THAT KEY, and the differ referees — the same posture `/scopebase` and `/regionbase`
+// take toward each other. The variation carries `homeSplitTag(key)` because a candidate's variations are its
+// IDENTITY: `bench diff` and docs/ranked-repro.md compare candidates by them, so one name over two
 // withholds would hide a program swap from both. The withhold itself is DATA: one rejection
 // prepended to the caller's own admission table, in the `Gate<BaseKey>` type that table already
 // has, so `firstRejection` attributes a refusal to it, `without` ablates it, and the composed table
@@ -30,7 +30,7 @@
 // EXACTLY ONE KEY IS WITHHELD, and the arity is a claim rather than an oversight. A two-key withhold
 // exists only where the caller's table binds three — `homesplit-fan-cap` admits no more — and there
 // it is the three further pairs, each carrying the three respells rank.ts derives from one pipe:
-// NINE more candidates per axis point on those functions alone, before any shape product, and no
+// NINE more candidates per structure setting on those functions alone, before any stacked variation, and no
 // row asks for one. `l3/volatileptr.ts`'s `volatileSubsetCandidates` enumerates every proper subset
 // under the same cap; it does that because a row demanded each of them. Widen this the same way,
 // on a row.
@@ -59,7 +59,7 @@ export const withholdingKey = (gates: readonly Gate<BaseKey>[], key: string): re
   ...gates,
 ];
 
-/** The withheld key as a LABEL token: `c:67109076 4 true` → `0x40000d4.4s`. Width and signedness
+/** The withheld key as a variation's SUBJECT: `c:67109076 4 true` → `0x40000d4.4s`. Width and signedness
  *  ride because they are part of the key — two keys over one address are two different spellings.
  *
  *  PARSED BY THE KEY'S PRODUCER (`l3/basecse.ts`'s `parseBaseKey`, beside `keyOf`), because a base
@@ -68,9 +68,9 @@ export const withholdingKey = (gates: readonly Gate<BaseKey>[], key: string): re
  *  separator rather than the type's. Split from the FRONT, the type reads as the width and the
  *  width as the signedness; split from the END, the `a:` form comes out right and the `c:` form
  *  runs `Number` over `67109076 <u16*>`, tagging every cast over a numeric base `0xNaN` and
- *  collapsing distinct keys onto one label. No shipped table admits a cast base outside
+ *  collapsing distinct keys onto one name. No shipped table admits a cast base outside
  *  `/orderbase`, and `/orderbase` carries `pairings: false`, so no such key reaches this function
- *  today — but a candidate LABEL is an identity (`bench diff` and docs/ranked-repro.md compare
+ *  today — but a candidate's variations are its identity (`bench diff` and docs/ranked-repro.md compare
  *  candidates by it), and one roster line is all that stands between the two. The sibling half of
  *  the same hazard is already guarded in `splitHomeBases`, which translates a cast base to no
  *  region key and declines. */
@@ -79,7 +79,7 @@ export function homeSplitTag(key: string): string {
   const base = leaf.startsWith('c:') ? `0x${Number(leaf.slice(2)).toString(16)}` : leaf.slice(leaf.indexOf(':') + 1);
   // The cast's element type stays in the token — it is part of the key's identity, since two casts
   // over one symbol are two locals that stride differently. Whitespace is squeezed defensively
-  // rather than because any type spells one: a label is one whitespace-free word everywhere it is
+  // rather than because any type spells one: a variation is one whitespace-free word everywhere it is
   // read, and that has to hold whatever `typeToString` grows.
   const type = castType === null ? '' : `<${castType}>`;
   return `${`${base}${type}`.replace(/\s+/g, '')}.${width}${signed ? 's' : 'u'}`;
@@ -98,13 +98,13 @@ export interface HomeSplitFanCtx {
 export const HOMESPLIT_FAN_GATES: readonly Gate<HomeSplitFanCtx>[] = [
   {
     id: 'homesplit-degenerate',
-    why: 'withholding the only hoistable key is `/regionbase`, and withholding none is `/livebase-block`',
+    why: 'with one hoistable base there is nothing new: withholding it is `regionbase`, and withholding none is `livebase-block`',
     sound: false,
     rejects: (c) => c.hoistableKeys < 2,
   },
   {
     id: 'homesplit-fan-cap',
-    why: 'one candidate per hoistable key, times the volatile products — the whole cost of the axis',
+    why: 'more than three hoistable bases would add a candidate for each, times the volatile pairings',
     sound: false,
     rejects: (c) => c.hoistableKeys > 3,
   },
@@ -143,13 +143,13 @@ export interface HomeSplitCtx {
 export const HOMESPLIT_GATES: readonly Gate<HomeSplitCtx>[] = [
   {
     id: 'homesplit-no-region',
-    why: 'a withheld key the region rule declines to split leaves the spelling the primary carries',
+    why: 'a base held back from the function-top local that no per-region local takes instead leaves the spelling the default carries',
     sound: false,
     rejects: (c) => !c.withheldSplits,
   },
   {
     id: 'homesplit-drops-device-volatile',
-    why: 'a device read left inline is qualified by neither /volatile nor /vol-store',
+    why: 'a device read left inline would carry neither `volatile` nor `vol-store`',
     sound: false,
     rejects: (c) => c.inlineDeviceRead,
   },

package/src/l3/initfirst.ts

@@ -1,10 +1,10 @@
-// L3 re-spelling lever: a loop INIT moves above the guard that encloses it, and the guard reads
+// L3 respell variation: a loop INIT moves above the guard that encloses it, and the guard reads
 // the initialized variable.
 //
 // `for (i = 0; i < n; i++)` compiles with the init BEFORE the zero-trip test (`mov r3,#0` then
 // `cmp r3, r5`), while `if (0 < n) { i = 0; do … }` compiles with the init behind the branch.
 // Both source forms lift to the SAME IR — a const has no position — so which the original spelled
-// is not recoverable; this lever emits the init-first sibling and the differ referees:
+// is not recoverable; this variation emits the init-first sibling and the differ referees:
 //
 //     if (0 < n) { v = 0; … }   →   v = 0; if (v < n) { … }
 //
@@ -61,7 +61,7 @@ const stripWideIntCast = (e: Expr): Expr =>
 
 /** Every deref rooted at a var through casts only. The var-root rule is a TWO-WORLD argument, not a
  *  volatility proof: a deref through a plain-declared pointer local may still be MMIO, but the
- *  /volatile axis enumerates the qualified sibling — where this lever refuses — so both worlds reach
+ *  /volatile variation enumerates the qualified sibling — where this variation refuses — so both worlds reach
  *  the differ and collapsing reads here is the plain world's own premise. A raw `*(u16 *)CONST` deref
  *  has NO local for /volatile to qualify, so no sibling carries the volatile world and the collapse
  *  would silently discard it. */

package/src/l3/inlinebase.ts

@@ -1,4 +1,4 @@
-// L3 re-spelling lever: DELETE a pointer local holding a CONSTANT address and spell each access
+// L3 respell variation: DELETE a pointer local holding a CONSTANT address and spell each access
 // through it as the cast constant (`*(u16 *)0x4000208` rather than `p = (u16 *)0x4000208; *p`).
 //
 // The local is structure/analysis.ts's value-home spelling for a `const` with 2+ consumers that
@@ -25,34 +25,34 @@
 // separate at 11 against 12 on their own, and are BYTE-IDENTICAL once the slot qualifier is
 // there too — the shape that matches (agbcc 2.9-arm-000512, `-O2 -mthumb-interwork -Wimplicit
 // -fhex-asm -fprologue-bugfix`; `.s` diff empty, `.o` identical under cmp). So rank.ts emits
-// the qualified spelling as a second OUTPUT of this lever, `/volatile` narrowed to the locals
+// the qualified spelling as a second OUTPUT of this variation, `/volatile` narrowed to the locals
 // it deletes. Each cast this mints carries the qualifier; a use whose width does not stride the
 // declared pointee renders through the C-family printer's reinterpret cast instead, which
 // carries it too (backend/cfamily.ts) — in C the access takes the OUTER type, so a plain cast
 // there would spell exactly the silent drop this paragraph exists to prevent.
 //
 // GATE (INLINEBASE_GATES) — the local must be all of: pointer-typed; initialized by a bare
-// NONZERO `const` (a `(T *)base` CAST initializer is l3/basecse.ts's reuse hoist, whose own lever
+// NONZERO `const` (a `(T *)base` CAST initializer is l3/basecse.ts's reuse hoist, whose own variation
 // family owns that question; `0` is NULL, never an address, which is also the sibling qualifier
-// lever's rule); assigned exactly once, by a statement at the body's TOP LEVEL that no earlier
+// variation's rule); assigned exactly once, by a statement at the body's TOP LEVEL that no earlier
 // statement's mention precedes; never address-taken; used only as the base of an `index`, at 2+
 // sites (one use is not the reused address this exists for); not object-`volatile` (a
 // `T *volatile p` has no inhabitant, and cfamily.ts prints that flag in the pointee's position);
 // and not `frame` (a slot is an asm fact — see the SFn.locals doc). Anything else, and nothing
 // qualifying at all, DECLINES (null) rather than approximating.
 //
-// A RE-SPELLING RATHER THAN A STRUCTURING AXIS, which is a cost choice and not the
-// underdetermination one (docs/level-tower.md, "a third fork sits inside the ranked population").
+// A RESPELL VARIATION RATHER THAN A STRUCTURE VARIATION, which is a cost decision and not the
+// underdetermination one (docs/level-tower.md, "a third fork sits inside the ranked variations").
 // The question — does a `const` with 2+ consumers live across a call in a named local — is the one
 // `/reread-globals`, `/addr-home`, `/expr-home` and `/derived-home` each answer as a
-// STRUCTURING_AXES entry. An axis here would double the enumeration on every function it admits;
+// STRUCTURE_VARIATIONS entry. A structure variation here would double the enumeration on every function it admits;
 // substituting on the already-homed tree costs 766 candidates over 47058 (+1.6%) across the 33 of
 // 69 klonoa functions that lift with no symbol map.
 //
 // KNOWN GAP, and it is the price of that choice rather than an oversight: only `index` bases are
 // re-spelled, so the same L2 home passed to a callee or standing as a `field` base is out of
 // reach — `otherUses` refuses it. Reaching those needs the un-homed tree, which is
-// structure/analysis.ts's decision; the day a row demands one, this becomes the axis.
+// structure/analysis.ts's decision; the day a row demands one, this becomes a structure variation.
 //
 // The idiom it recovers is every GBA project's register macro: `*(vu16 *)0x4000208` is what
 // `REG_IME` expands to, so the deleted local is not merely an undone home.
@@ -71,20 +71,20 @@ interface BaseCtx {
 export const INLINEBASE_GATES: readonly Gate<BaseCtx>[] = [
   {
     id: 'non-pointer',
-    why: 'the lever re-spells an address; a scalar value home is a different question',
+    why: 'only a local holding an address is substituted; a local holding a scalar value is a different question',
     sound: false,
     rejects: (c) => !c.isPointer,
   },
   {
     id: 'object-volatile',
-    why: 'the substitution carries the POINTEE flag, so an object-volatile pointer would lose its own',
+    why: 'the substitution keeps only the `volatile` of what the pointer points to, so a pointer that is itself volatile would lose its own',
     sound: true,
     guardedBy: 'inlinebase.test.ts: an object-volatile or frame local declines',
     rejects: (c) => c.objectVolatile,
   },
   {
     id: 'frame',
-    why: 'a slot the asm materialized is an asm fact, not a spelling to undo',
+    why: 'a stack slot the assembly used is a fact about the function, not a spelling to undo',
     sound: false,
     rejects: (c) => c.hasFrame,
   },
@@ -104,7 +104,7 @@ export const INLINEBASE_GATES: readonly Gate<BaseCtx>[] = [
   },
   {
     id: 'null-base',
-    why: '`0` is NULL, never an address — the sibling qualifier lever (volatileptr.ts) refuses it too',
+    why: 'a base of `0` is a null pointer, never an address, and `volatile` refuses it too',
     sound: false,
     rejects: (c) => c.m.constValue === 0,
   },
@@ -126,12 +126,12 @@ export const INLINEBASE_GATES: readonly Gate<BaseCtx>[] = [
     id: 'other-uses',
     why: 'a use the substitution cannot reach would name the deleted local',
     sound: true,
-    guardedBy: 'inlinebase.test.ts: a use that is not an `index` base is outside what the lever re-spells',
+    guardedBy: 'inlinebase.test.ts: a use that is not an `index` base is outside what the variation re-spells',
     rejects: (c) => c.m.otherUses !== 0,
   },
   {
     id: 'single-use',
-    why: 'one use is not the reused address this lever exists for',
+    why: 'one use is not the reused address this variation exists for',
     sound: false,
     rejects: (c) => c.m.baseUses < 2,
   },
@@ -164,8 +164,8 @@ function plan(sfn: SFn): Map<string, Extract<Expr, { k: 'cast' }>> {
   return out;
 }
 
-/** Which locals this lever would delete — rank.ts narrows `/volatile` to exactly these before
- *  pairing, so the qualified output never qualifies a pointer the lever leaves standing. */
+/** Which locals this variation would delete — rank.ts narrows `/volatile` to exactly these before
+ *  pairing, so the qualified output never qualifies a pointer the variation leaves standing. */
 export function inlinableConstBases(sfn: SFn): string[] {
   return [...plan(sfn).keys()];
 }

package/src/l3/mentions.ts

@@ -1,6 +1,6 @@
 // What one L3 tree does to each of its locals, counted once.
 //
-// Levers ask overlapping versions of the question and would disagree if each walked the tree
+// Respell variations ask overlapping versions of the question and would disagree if each walked the tree
 // its own way: l3/inlinebase.ts needs the SHAPE of every use (only an `index` base is re-spellable,
 // and the single assignment must be a top-level `const` nothing mentions earlier), while
 // l3/volatileval.ts needs the COUNTS, to check the tree still performs every access the machine
@@ -14,7 +14,7 @@
 // oversight: a POSITION added to `index` reaches the generic vocabulary for free and this walk not
 // at all. Every position is enumerated below and pinned by
 // test/array-rank-guards.test.ts, beside the generic helpers it cannot speak for.
-import { type Expr, type SFn, type Stmt, exprChildren, stmtChildren, stmtExprs } from './ast';
+import { type Expr, type SFn, type Stmt, exprChildren, stmtChildren, stmtExprs, walkExprs } from './ast';
 
 export interface Mentions {
   /** assignments to the name, at any nesting */
@@ -24,7 +24,7 @@ export interface Mentions {
   /** the bare-`const` value that assignment stores, or null if it stores anything else */
   constValue: number | null;
   addrTaken: number;
-  /** uses as the `base` of an `index` node — the only use shape a base lever can re-spell */
+  /** uses as the `base` of an `index` node — the only use shape a base-hoisting variation can re-spell */
   baseUses: number;
   /** every other read */
   otherUses: number;
@@ -53,7 +53,7 @@ function walkExpr(e: Expr, visit: (x: Expr, isIndexBase: boolean) => void, isInd
   if (e.k === 'index') {
     walkExpr(e.base, visit, true);
     // `lead` — a multidimensional global's LEADING subscripts — is an ordinary value position, so
-    // a name mentioned there is a real read. Missing it does not cost a candidate: it lets a lever
+    // a name mentioned there is a real read. Missing it does not cost a candidate: it lets a variation
     // DELETE a local the body still names.
     for (const l of e.lead ?? []) {
       walkExpr(l, visit, false);
@@ -67,7 +67,7 @@ function walkExpr(e: Expr, visit: (x: Expr, isIndexBase: boolean) => void, isInd
 }
 
 /** Every mention of every local, keyed by name. Locals only — a param or a global name is not in
- *  the map, and a lever asking about one gets `undefined` rather than a zeroed record. */
+ *  the map, and a pass asking about one gets `undefined` rather than a zeroed record. */
 export function localMentions(sfn: SFn): Map<string, Mentions> {
   const t = new Map<string, Mentions>(sfn.locals.map((l) => [l.name, blank()]));
   const seen = (name: string, at: number): Mentions | undefined => {
@@ -111,3 +111,66 @@ export function localMentions(sfn: SFn): Map<string, Mentions> {
   sfn.body.forEach((s, i) => stmt(s, i, true));
   return t;
 }
+
+/** THE ONE WALK behind `mentionsAnyLocal` and `mentionedLocals` below: which of `names` anything
+ *  under `stmts` still NAMES — as an assignment TARGET (which carries no expression, so no walk
+ *  over values can see it), as a read, or as an address. `first` returns at the first hit it
+ *  reaches, which is all the boolean caller needs.
+ *
+ *  The question a pass that DELETES a declaration has to answer, and it lives here rather than in
+ *  the deleting pass for the reason this file's header states about its own walk: a second walk
+ *  over the node vocabulary is how a new node kind becomes a silent undercount, and beside
+ *  `localMentions` a divergence is at least visible. This one is answered over a SUBTREE, so it
+ *  cannot be derived from the counts above — `localMentions` is keyed to `sfn.locals` across the
+ *  whole body, and l3/unmerge.ts's whole point is that those counts are sampled before any
+ *  rewriting and go stale.
+ *
+ *  TOTAL over the vocabulary by construction: `assign` is the only `Stmt` carrying a bare name and
+ *  `var`/`addr` the only `Expr`s, and both walks are derived from `stmtChildren`/`stmtExprs` — so a
+ *  `for`'s init and inc, a `switch`'s scrutinee, its cases and its default are all covered. */
+function scanMentions(stmts: readonly Stmt[], names: ReadonlySet<string>, first: boolean): Set<string> {
+  // TWO FLAT SWEEPS, not one expression walk per nesting level. `walkExprs` already descends
+  // `stmtChildren` (ast.ts), so calling it per statement from inside a recursion that ALSO
+  // descends re-walks every nested expression once per enclosing level — quadratic in the nesting
+  // depth, 301 `has` calls at depth 24 where one pass needs 25. Small at today's call sites (one
+  // rewritten subtree per un-merge site, one dropped-locals set per respelled tree), but this is a
+  // SHARED helper and its cost belongs in its contract.
+  const found = new Set<string>();
+  const body = [...stmts] as Stmt[];
+  const stack: Stmt[] = [...body];
+  while (stack.length > 0) {
+    const s = stack.pop()!;
+    if (s.k === 'assign' && names.has(s.name)) {
+      found.add(s.name);
+      if (first) {
+        return found;
+      }
+    }
+    stack.push(...stmtChildren(s));
+  }
+  for (const e of walkExprs(body)) {
+    if ((e.k === 'var' || e.k === 'addr') && names.has(e.name)) {
+      found.add(e.name);
+      if (first) {
+        return found;
+      }
+    }
+  }
+  return found;
+}
+
+/** true when anything under `stmts` still names one of `names`. See `scanMentions` above. */
+export function mentionsAnyLocal(stmts: readonly Stmt[], names: ReadonlySet<string>): boolean {
+  return scanMentions(stmts, names, true).size > 0;
+}
+
+/** WHICH of `names` the tree still mentions — the same walk `mentionsAnyLocal` answers "any" over,
+ *  told to keep going, for the caller that has to NAME the survivors.
+ *
+ *  It exists so that contracts.ts's `assertNoOrphanedLocals` — the loud backstop for exactly the
+ *  mistake this predicate guards — does not carry a THIRD hand-rolled copy of the node vocabulary.
+ *  The boolean cannot serve it (the diagnostic needs the set) and one call per dropped name would
+ *  be a walk per name. */
+export function mentionedLocals(stmts: readonly Stmt[], names: ReadonlySet<string>): Set<string> {
+  return scanMentions(stmts, names, false);
+}

package/src/l3/mulfirst.ts

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

package/src/l3/nearbase.ts

@@ -1,9 +1,9 @@
-// L3 re-spelling lever: NEIGHBOR absolute addresses derive from one shared base local.
+// L3 respell variation: NEIGHBOR absolute addresses derive from one shared base local.
 //
 // A cluster of raw-address accesses a few bytes apart is one object's cells: the compiler holds
 // the object's base in a register and derives each cell (`add #72` / `add #74` off one pool
 // word, a halfword offset beyond the load range forcing the add, the in-range word staying
-// `[rN, #112]`), where a per-cell spelling anchors one pool constant per address. This lever
+// `[rN, #112]`), where a per-cell spelling anchors one pool constant per address. This variation
 // re-spells every deref base in a cluster as an offset from a `u8 *` base local holding the
 // cluster's lowest address, and the differ referees:
 //
@@ -21,7 +21,7 @@
 // VALUE inside its window re-spells too, as `(s32)(b + off)` — the address of a cell handed to
 // something (a DMA source register) is the same derived add in the original, and the two
 // spellings are value-equal by construction, so the differ referees — including an integer that
-// only coincidentally lands in the window, which is the stated cost of the lever (the `s32` cast
+// only coincidentally lands in the window, which is the stated cost of the variation (the `s32` cast
 // assumes addresses below 2^31, true of every target that declares nearBaseSpan today). Declines
 // (null) when no cluster forms.
 import { baseConst } from './address';
@@ -31,7 +31,7 @@ import { type BaseInit, nameAllocator, placeBaseLocals } from './hoist';
 
 /** `span` is the target's single-add-immediate derivation reach
  *  (TargetDescription.compilerBehaviors.nearBaseSpan) — a target that declares none never runs
- *  this lever. */
+ *  this variation. */
 export function nearBaseClusters(sfn: SFn, span: number): SFn | null {
   if (!Number.isFinite(span) || span < 0) {
     return null; // a hostile span stalls the cluster window instead of shrinking it

package/src/l3/offmember.ts

@@ -38,7 +38,7 @@
 //   displacement. A window refusal removes ZERO further bases in either configuration.
 //
 //   PREMISE. It would be refusing a dropped qualifier, and there is none to drop: `/volatile`
-//   wraps the base in a CAST that `non-leaf-base` refuses, so the two levers cannot compose and
+//   wraps the base in a CAST that `non-leaf-base` refuses, so the two variations cannot compose and
 //   the tree this pass is handed is unqualified in both configurations. Nor is a tie-break lost —
 //   `deviceVolatileClaims` counts only qualifiers a tree already asserts, so an unqualified tree
 //   scores zero whichever way it is spelled.
@@ -96,7 +96,7 @@
 // "PROTECTS NO ROW" IS A CENSUS AND NOT A SAMPLE, and the population is small because this is an
 // extra GATE: it only ever removes candidates, so only a row whose winner carries `/offmember` can
 // move at all. THAT POPULATION IS A QUERY, not a count to keep in step by hand — the rows of
-// `apps/benchmark/results/results.json` whose `asmlift.candidateLabel` contains `offmember` — and
+// `apps/benchmark/results/results.json` whose `asmlift.winnerVariations` contains `offmember` — and
 // it grows with the corpus, so re-run it before repeating the result. It held eight rows besides
 // `ProcessInputAndUpdateEntities` when the census ran, all unmoved with the rule on:
 // `synthetic:basecell`, `synthetic:bgfixed`, `synthetic:foldsink`, `sa3:sub_802DFC8` and
@@ -222,7 +222,7 @@ function membersOf(sites: readonly Site[]): Site[] {
  *  THE FOURTH IS NOT ABOUT PLACEMENT, and it is the easy one to leave out: two views of one
  *  offset at one width but
  *  DIFFERENT SIGNEDNESS (`ldrb` and `ldrsb` at the same address). One member has one type, so
- *  respelling both through it changes what one of the two READS — `scalarTypeForAccess` honours
+ *  spelling both through it changes what one of the two READS — `scalarTypeForAccess` honours
  *  signedness at widths 1 and 2, so an unsigned read becomes sign-extending. That is a value
  *  change rather than a spelling change, and the differ can referee it only by luck: a masked or
  *  compared result compiles to the same bytes while the published C says something the asm does
@@ -328,7 +328,7 @@ function admit(
 
 /** The gate table an ablation swaps out. Optional, so a caller gets the shipped table by default.
  *  The pass needs nothing else from the target: the fold this exists for is `foldsConstAddrOffset`
- *  and rank.ts asks that before offering the axis at all. */
+ *  and rank.ts asks that before offering the variation at all. */
 export interface OffmemberOpts {
   readonly gates?: readonly Gate<OffmemberBase>[];
 }
@@ -339,7 +339,7 @@ export function offmemberBases(sfn: SFn, opts: OffmemberOpts = {}): readonly str
 }
 
 /** Re-spell every admitted base's constant subscripts as members of a synthesized struct.
- *  `null` when nothing is admitted — the axis then contributes no candidate. */
+ *  `null` when nothing is admitted — the variation then contributes no candidate. */
 export function spellOperandMembers(sfn: SFn, opts: OffmemberOpts = {}): SFn | null {
   // Past EVERY `Off<N>` the tree already carries, never the first free one (`ir/struct-names.ts`,
   // shared with the other two minters, which also records that this scan returns 0 on every

package/src/l3/parkfirst.ts

@@ -1,18 +1,18 @@
-// L3 re-spelling lever: park incoming ARGUMENTS first in the entry straight-line prefix.
+// L3 respell variation: park incoming ARGUMENTS first in the entry straight-line prefix.
 //
 // A copy of an incoming parameter into a local (`v = a1`) reproduces the register park the
 // compiler performed to free a caller-save register (`mov ip, r1`). The park instruction lifts
 // to pure SSA aliasing — no op, no position — so the emitted order falls out of block emission
 // (materialized statements first, edge copies last), while the compiler may have parked BEFORE
 // any of those statements ran (hipress homes its counter in ip before loading a byte into the
-// vacated r1). Both orders are legitimate C for the same asm; this lever emits the park-first
+// vacated r1). Both orders are legitimate C for the same asm; this variation emits the park-first
 // sibling and the differ referees.
 //
 // SCOPE (decline over approximate): only plain assigns in the ENTRY straight-line prefix (the
 // leading run of assigns) move; a park's RHS must be pure over PARAMETERS AND CONSTANTS through
 // scalar nodes only (var/const/un/bin/cast — a memory read or a call would be re-scheduled, not
 // re-spelled), so a constant initializer qualifies as a park and a param leaf is NOT required —
-// what this lever moves is the leading run's ORDER, and a constant is as free of position as a
+// what this variation moves is the leading run's ORDER, and a constant is as free of position as a
 // parked register is; and a park never crosses a statement that writes a name it reads, reads or
 // writes its destination (`&v` counts as touching v), or carries an effect. Relative order — of the
 // parks and of everything else — is preserved. Declines (null) when nothing moves.
@@ -22,11 +22,11 @@
 // spells a store to a bare scalar GLOBAL as an `assign` like any other, so such a store parks too.
 // The crossing checks are NAME-KEYED, so a crossed statement that reaches the destination (or a
 // name the park reads) through an ALIAS rather than by name is invisible to them — the same
-// name-keyed model every lever at this level defers aliasing to.
+// name-keyed model every respell variation at this level defers aliasing to.
 //
-// The kmc hipress residual is this axis's OTHER projection — its keep-load renders first while
+// The kmc hipress residual is this variation's OTHER projection — its keep-load renders first while
 // gcc2.7.2 schedules it last — so a second inhabitant consolidates both into one entry-prefix
-// ordering lever rather than growing a sibling.
+// ordering variation rather than growing a sibling.
 import type { Expr, SFn, Stmt } from './ast';
 import { exprChildren, exprHasEffect } from './ast';
 

package/src/l3/pollguard.ts

@@ -1,4 +1,4 @@
-// L3 poll-shape re-spelling levers: `pollGuards` regrows an empty bottom-tested loop's guard;
+// L3 poll-shape respell variations: `pollGuards` regrows an empty bottom-tested loop's guard;
 // `pollReads` folds a materialized poll's re-read back into its while condition. Each carries
 // its own trace argument below.
 //
@@ -6,7 +6,7 @@
 //
 // For an empty body the two forms compile to the SAME instructions — gcc collapses the guard
 // into the bottom test late (jump optimization), AFTER flow has counted the guard's reads — so
-// the choice leaves no instruction trace, only a register-allocation ripple: the extra
+// the decision leaves no instruction trace, only a register-allocation ripple: the extra
 // source-level read raises the condition operands' ref counts, which re-orders the allocator's
 // priorities for the WHOLE function (the busy-wait's base landing in a low reg vs `ip`). Which
 // form the source spelled is unrecoverable from the bytes; both are emitted and the differ
@@ -34,7 +34,7 @@ export function pollGuards(sfn: SFn): SFn | null {
   return changed ? { ...sfn, body } : null;
 }
 
-// L3 re-spelling lever: a materialized POLL re-reads in its own condition.
+// L3 respell variation: a materialized POLL re-reads in its own condition.
 //
 //     v = dma[2]; while ((v & BUSY) != 0) { v = dma[2]; }   →   while ((dma[2] & BUSY) != 0) {}
 //

package/src/l3/ptrfield.ts

@@ -1,4 +1,4 @@
-// L3 re-spelling lever: declare a recovered WORD field a POINTER (`void *field_4;` rather than
+// L3 respell variation: declare a recovered WORD field a POINTER (`void *field_4;` rather than
 // `s32 field_4;`), and cast at each read.
 //
 // raise/structs.ts recovers a field's type from the ACCESS WIDTH alone — a 4-byte load is `s32`,
@@ -34,13 +34,13 @@
 // each use computes the same value it did. Nothing else moves. THE 32-BIT ASSUMPTION IS ASSERTED,
 // NOT CHECKED — there is no pointer-width field on TargetDescription to check it against, and the
 // assumption is already tower-wide (`l3/typing.ts`'s `ptrElemBytes` returns 4 for any pointee). On
-// a 64-bit target this lever would change a struct's LAYOUT rather than only its spelling, so the
+// a 64-bit target this variation would change a struct's LAYOUT rather than only its spelling, so the
 // width field is what that target's first row must add, and this note is where to start.
 //
 // IT FLIPS EVERY ADMITTED FIELD AT ONCE, and its own paragraph above says the knowledge is
 // PER-FIELD — so the subset enumeration `l3/volatileptr.ts` does for exactly this reason
-// (`volatileSubsetCandidates`, capped at three locals) is the shape this lever will eventually
-// want. It is not built yet because nothing demands it: swept over 834 corpus trees, the lever
+// (`volatileSubsetCandidates`, capped at three locals) is the shape this variation will eventually
+// want. It is not built yet because nothing demands it: swept over 834 corpus trees, the variation
 // fires on 42, and 34 of those have a single admitted field. The six 2-field trees and the two
 // 4-field ones (`sa3:sa2__sub_8083504` flips Struct0.field_8/12 and Struct2.field_8/12 together)
 // are where 1 of 3 and 1 of 15 non-empty subsets is reachable. A row that needs one of the missing

package/src/l3/regspell.ts

@@ -1,4 +1,4 @@
-// asmlift L3 — the REGISTER-COPY re-spelling, a differ-ranked representation lever (the fourth,
+// asmlift L3 — the REGISTER-COPY respell variation, differ-ranked like the three before it (the fourth,
 // after signedness / branch sense / walk-vs-index).
 //
 // A compiler's register allocation leaves SOURCE-visible footprints the coalescing structurer
@@ -26,7 +26,7 @@
 //        a bin operand materializes into its own fresh local first (`v = 128 << 9; … v / x …`) —
 //        the register the compiler staged the constant in.
 //   R3 — return assign-back: a non-var return expression lands in a fresh local first
-//        (`r = E; return r`). Emitted as a SEPARATE variant (with/without R3) when R1/R2 fired:
+//        (`r = E; return r`). Emitted as a SEPARATE result (with/without R3) when R1/R2 fired:
 //        which tail the source spelled is itself ambiguous.
 import { IrType, T } from '../ir/types';
 import { Expr, SFn, Stmt, exprEquals, mapExprChildren } from './ast';
@@ -124,8 +124,8 @@ function isConstExpr(e: Expr): boolean {
  *  var and only the fresh spelling exists — so the tails are a 1- OR 2-element list and the SECOND
  *  spelling is not at a fixed index.
  *
- *  This field exists because the caller labels these, and a label is the instrument every census
- *  in this repo reads (it is a `bench diff` FIELD). Index a `['/regcopy', '/regcopy-ret',
+ *  This field exists because the caller names these, and a candidate's variations are the instrument
+ *  every census in this repo reads (a `bench diff` FIELD). Index a `['/regcopy', '/regcopy-ret',
  *  '/regcopy-ret-fresh']` table by POSITION instead and an R1-less function publishes its fresh
  *  tail as `/regcopy-ret` — the dead-var-reuse name on the spelling that has no dead var to reuse
  *  — and a census over the token `/regcopy-ret-fresh` then censuses nothing wherever R1 declines,
@@ -133,7 +133,7 @@ function isConstExpr(e: Expr): boolean {
 export type RegcopyTail = 'none' | 'reuse' | 'fresh';
 
 export interface RegcopySpelling {
-  /** which R3 tail this variant carries — `none` is the un-tailed base */
+  /** which R3 tail this result carries — `none` is the un-tailed base */
   tail: RegcopyTail;
   sfn: SFn;
 }
@@ -213,7 +213,7 @@ function renameSubexpr(e: Expr, E: Expr, name: string): Expr {
   return mapExprChildren(e, (c) => renameSubexpr(c, E, name));
 }
 
-/** Apply the register-copy re-spelling. Returns 0–3 variants — the base, plus the R3 tail in each
+/** Apply the register-copy re-spelling. Returns 0–3 results — the base, plus the R3 tail in each
  *  spelling that exists (reuse needs R1 to have fired, fresh always does) — and an EMPTY list when
  *  nothing fired. Pure — never mutates the input. */
 export function registerishSpellings(sfn: SFn): RegcopySpelling[] {
@@ -247,7 +247,7 @@ export function registerishSpellings(sfn: SFn): RegcopySpelling[] {
         if (m) {
           const { v, E, updArm, upd, cond } = m;
           // GUARDS BEFORE ALLOCATION (a declined shape must leave no residue — the leaked
-          // dead `w` even perturbed the live-name count this lever exists to reproduce):
+          // dead `w` even perturbed the live-name count this variation exists to reproduce):
           //   • E and the cond pure; the cond's non-E operand must NOT mention v (a clamp's
           //     `if (a < v)` would compare against the POST-assignment v — reproduced);
           //   • the copy w carries E's RENDERED type, not v's declared one (retyping a u32
@@ -327,7 +327,7 @@ export function registerishSpellings(sfn: SFn): RegcopySpelling[] {
   }
   const base: SFn = { ...sfn, locals: [...locals], body: afterR2 };
 
-  // R3 variants: the tail assign-back — a non-var return lands in a local first. WHICH local is
+  // R3 results: the tail assign-back — a non-var return lands in a local first. WHICH local is
   // itself allocator-ambiguous (gcc 2.9 wanted R1's dead value var — live-name-count sensitive;
   // another allocator may want the fresh one), so BOTH tails are emitted as candidates rather
   // than asserting one compiler's preference; the source dedupe collapses them when identical.