@asmlift/core 0.6.0 → 0.7.0

package/src/l3/scopebase.ts

@@ -1,4 +1,4 @@
-// L3 re-spelling lever: name a reused global base in a pointer local placed by SCOPE rather than at
+// L3 respell variation: name a reused global base in a pointer local placed by SCOPE rather than at
 // the function top. Two region rules ship, one pass and one collected index behind them:
 //
 //   `/scopebase`   ONE local for a key, at the innermost list holding all of its uses (else the
@@ -9,13 +9,15 @@
 //                  and the three-block-scoped one assemble byte-identically. So there is no nested
 //                  declaration block here and none is needed — the locals are declared at function
 //                  top and only their ASSIGNMENTS are placed per region. That compiler fact is
-//                  PINNED rather than asserted: packages/cli/test/matching/decl-scope-axis.test.ts
+//                  PINNED rather than asserted: packages/cli/test/matching/decl-scope-variation.test.ts
 //                  compiles both spellings through the project's own agbcc and compares the object
 //                  bytes, and compiles a count-collapsed third spelling to show the COUNT is not
 //                  free either.
 //
-// The lever earns its place: returning `null` from `hoistScopedBases` costs
-// kleod:UpdateHUDCounterDisplay its match, so the benchmark's zero-lost gate guards this file.
+// The variation earned its place on kleod's kl-eod-decomp rows: returning `null` from `hoistScopedBases`
+// cost kleod:UpdateHUDCounterDisplay its match. That row was retired on 2026-09-13 with its source,
+// so no current benchmark row is known to guard this file; re-measure by ablation on the current
+// rows before naming one.
 //
 // `l3/basecse.ts` already hoists a reused leaf base — at three positions now, of which two are in
 // the TOP-LEVEL statement list (the function top, or an init's first use where a roster row asks
@@ -28,8 +30,8 @@
 //   narrows that range and does not close it: the init still lands ABOVE the `if`. `l3/hoist.ts`'s
 //   third placement, `scope`, now does close it for the run basecse places, so "into a nested list"
 //   is no longer this file's alone; what stays here is the base this file can SEE (below) and the
-//   COUNT question (`REGION_RULES`), which no placement answers. That argument is why the lever is
-//   scope-aware; it is NOT a claim about what the lever achieves, and no committed measurement
+//   COUNT question (`REGION_RULES`), which no placement answers. That argument is why the variation is
+//   scope-aware; it is NOT a claim about what the variation achieves, and no committed measurement
 //   separates basecse's two flat placements (the one that did edited a reference source by hand and
 //   cannot be re-run). On kleod:UpdateHUDCounterDisplay the primary path declines outright (a later
 //   pass retired the phi it keyed on, so the base's uses span the function body), and the cluster
@@ -47,7 +49,7 @@
 // shape. The decomp author's alternative is a no-op read-modify-write (`g[0][K] += 0;`) purely to
 // force that materialization; naming the base is the same codegen without the quirk.
 //
-// A LEVER, not a rewrite: both region rules are emitted as ADDITIONAL candidates (rank.ts
+// A VARIATION, not a committed rewrite: both region rules are emitted as ADDITIONAL candidates (rank.ts
 // `/scopebase`, `/regionbase`) with the differ refereeing, so the un-hoisted spelling is always
 // still in the list and neither can cost a match.
 //
@@ -60,7 +62,7 @@
 // sees it (they check resolution, deref typing, and whether a local is written ANYWHERE).
 //
 // ORDERING: `hoistBaseLocals` (basecse) runs unconditionally in `structureChecked`, BEFORE
-// rank's levers see the tree. So this pass's `addr`/`const` input is what basecse's DEFAULT table
+// rank's variations see the tree. So this pass's `addr`/`const` input is what basecse's DEFAULT table
 // refused — EVERY gate in it, single-use bases as much as loop and repeated-constant-offset ones —
 // which is why `SCOPEBASE_GATES` re-states basecse's rules rather than assuming those bases never
 // arrive.
@@ -72,7 +74,7 @@ import { type Gate, ablateHeuristic, firstRejection } from './gates';
 import { nameAllocator, takenNames } from './hoist';
 import { addressableGlobals } from './storage';
 
-/** A base this lever may name: a leaf whose value is a fixed address. */
+/** A base this variation may name: a leaf whose value is a fixed address. */
 type LeafBase = Extract<Expr, { k: 'addr' } | { k: 'const' } | { k: 'var' }>;
 
 /** THE identity of a base — what makes two accesses "the same address".
@@ -89,7 +91,7 @@ export interface AccessCtx {
   readonly addressable: ReadonlySet<string>;
 }
 
-/** Which accesses this lever may re-point. BOTH rules are SOUND: each one, removed, makes the
+/** Which accesses this variation may re-point. BOTH rules are SOUND: each one, removed, makes the
  *  rewrite name DIFFERENT BYTES — C that compiles, type-checks and scores, which is the failure
  *  mode nothing downstream catches.
  *
@@ -117,14 +119,14 @@ export const SCOPEBASE_ELIGIBILITY: readonly Gate<AccessCtx>[] = [
   },
   {
     id: 'shadowed-or-nonarray-base',
-    why: '`&name` on a local or a pointer-shaped global names a different object',
+    why: 'taking `&name` of a local or a pointer-shaped global names a different object',
     sound: true,
     guardedBy: 'addr-placement.test.ts: scopebase declines the shadowed name rather than take its address',
     rejects: (c) => c.base.k === 'var' && !c.addressable.has(c.base.name),
   },
 ];
 
-/** An access this lever may re-point, or null. */
+/** An access this variation may re-point, or null. */
 function eligible(
   e: Expr,
   globals: ReadonlySet<string>,
@@ -320,7 +322,7 @@ function deepestCluster(all: Site[]): { scope: Stmt[]; depth: number; uses: Site
   return best;
 }
 
-/** How a key's uses are cut into REGIONS — the one axis this pass varies. Names a `REGION_RULES`
+/** How a key's uses are cut into REGIONS — the one dimension this pass varies. Names a `REGION_RULES`
  *  entry; it is the only field a production caller passes. */
 export type RegionSelector = 'whole' | 'per-region';
 
@@ -414,13 +416,13 @@ export interface RegionCtx {
 const COUNTING_RULES: readonly Gate<RegionCtx>[] = [
   {
     id: 'single-use',
-    why: 'one access re-materializes as cheaply as a named local',
+    why: 'a base accessed once is as cheap to load again as to hold in a named local',
     sound: false,
     rejects: (c) => c.uses < 2,
   },
   {
     id: 'repeated-const-offset',
-    why: 'a fixed offset touched twice is a scalar RMW, which the compiler re-materializes',
+    why: 'a fixed offset read and then written is one scalar update, and the compiler loads its address again for it',
     sound: false,
     rejects: (c) => c.repeatedConstOffset,
   },
@@ -431,7 +433,7 @@ const COUNTING_RULES: readonly Gate<RegionCtx>[] = [
 const LOOP_RULES: readonly Gate<RegionCtx>[] = [
   {
     id: 'per-iteration-use',
-    why: 'no scope reachable from the use runs at a loop condition or `for` inc cadence',
+    why: 'no scope reachable from the use runs as often as a loop condition or a `for` increment',
     sound: false,
     rejects: (c) => c.perIteration,
   },
@@ -443,7 +445,7 @@ const LOOP_RULES: readonly Gate<RegionCtx>[] = [
   },
 ];
 
-/** The admission rules. NONE is sound: a wrong choice here names the same address in a different
+/** The admission rules. NONE is sound: a wrong decision here names the same address in a different
  *  place, so it costs bytes and a match, never meaning — the eligibility table above is where
  *  meaning is at stake, and `rank.ts` keeps the un-hoisted spelling beside every candidate.
  *
@@ -504,7 +506,7 @@ export const SCOPEBASE_GATES: readonly Gate<RegionCtx>[] = [...COUNTING_RULES, .
 const perRegionReading = (g: Gate<RegionCtx>): Gate<RegionCtx> => ({
   ...g,
   id: `region-${g.id}`,
-  why: `${g.why} — judged over ONE region's direct uses`,
+  why: `counted over one region’s own uses: ${g.why}`,
 });
 
 /** `/regionbase`'s admission (rank.ts): the per-region readings of `SCOPEBASE_GATES`, MINUS the one
@@ -531,7 +533,7 @@ const perRegionReading = (g: Gate<RegionCtx>): Gate<RegionCtx> => ({
  *  admits.
  *
  *  ONE RULE HERE IS PRICED BY A ROW; three are not. Ablating `region-single-use` moves
- *  `synthetic:dmascope` — the lever's own row — while `region-repeated-const-offset`,
+ *  `synthetic:dmascope` — the variation's own row — while `region-repeated-const-offset`,
  *  `per-iteration-use` and `regions-degenerate` each leave all five gating rows exactly where they
  *  stand. NO SCORE PAIR IS QUOTED for that move: `dmascope` is MATCH in the committed artifact, so
  *  a pair whose unablated endpoint is a nonmatch score describes a corpus state that no longer
@@ -546,7 +548,7 @@ export const REGIONBASE_GATES: readonly Gate<RegionCtx>[] = [
   ...ablateHeuristic(LOOP_RULES, 'nested-loop-use'),
   {
     id: 'regions-degenerate',
-    why: 'one region is the function-top hoist basecse and /livebase already offer',
+    why: 'a single region is the function-top local that the default hoist and `livebase` already offer',
     sound: false,
     rejects: (c) => c.siblingRegions < 2,
   },
@@ -554,7 +556,7 @@ export const REGIONBASE_GATES: readonly Gate<RegionCtx>[] = [
 
 /** THE REGION RULE, as a value. A third rule is one entry here — a partition, a gate table, and
  *  the population its counting rules are judged over — rather than three hand-edited branches in
- *  three functions, which is the same doctrine `rank.ts` states for its own admissions ("one entry
+ *  three functions, which is the same doctrine `rank-variations.ts` states for its hoist roster ("one entry
  *  here, one gate table, and that table's line in the gate-contract roster — not nine hand-edited
  *  sites that can drift"). */
 export interface RegionRule {
@@ -675,9 +677,10 @@ export function planScopedBases(sfn: SFn, opts: ScopeBaseOpts = {}): ScopedBaseP
    *  PER KEY, not per function, and the difference is not hypothetical. Nothing in the L3 contract
    *  forbids the sharing — `l3/pollguard.ts` already emits it (`{ k: 'if', cond: s.cond, then: [s] }`
    *  puts one `cond` object at two tree positions), and it is harmless today only because the shapes
-   *  are derived AFTER this lever in `rank.ts`, an ordering nothing pins. A whole-function decline
+   *  are derived AFTER this variation in `rank.ts`, an ordering nothing pins. A whole-function decline
    *  would make a future producer that shares one node silently delete every base this pass names —
-   *  including `kleod:UpdateHUDCounterDisplay`'s match, which returning `null` costs. Refusing the
+   *  including, until that row was retired (2026-09-13), `kleod:UpdateHUDCounterDisplay`'s match,
+   *  which returning `null` cost. Refusing the
    *  key that actually shares costs that key's spelling and nothing else, and the differ still has
    *  every other spelling in the list.
    *
@@ -757,14 +760,14 @@ export function planScopedBases(sfn: SFn, opts: ScopeBaseOpts = {}): ScopedBaseP
 
 /**
  * The re-spelling `regions` asks for — `/scopebase` or `/regionbase` — or null when nothing
- * qualifies (the caller then adds no candidate rather than a duplicate of the primary).
+ * qualifies (the caller then adds no candidate rather than a duplicate of the default).
  */
 export const hoistScopedBases = (sfn: SFn, opts: ScopeBaseOpts = {}): SFn | null =>
   applyScopedBasePlan(sfn, planScopedBases(sfn, opts));
 
 /**
  * `plan` applied to the tree it was planned over — null when it decided nothing (the caller then
- * adds no candidate rather than a duplicate of the primary).
+ * adds no candidate rather than a duplicate of the default).
  *
  * IDENTITY-BOUND to that tree, and not by the type: `scope` is matched against statement LISTS and
  * `repoint` against access NODES, both by reference. A plan from a DIFFERENT tree therefore splices

package/src/l3/sinkinit.ts

@@ -1,18 +1,18 @@
-// L3 re-spelling lever: sink each leading pointer-base INIT to the statement that first uses it.
+// L3 respell variation: sink each leading pointer-base INIT to the statement that first uses it.
 //
 // `l3/basecse.ts`'s COMMITTED call emits every base hoist at the head of `sfn.body`, so a base
 // first touched halfway down the function is live across everything above it — a live range the
-// original never had, and agbcc pays for it with a callee-saved register. (Its roster admissions
-// ask for this placement directly, through the same `l3/hoist.ts` mechanism this lever uses; what
-// the lever adds is reaching the run on a tree the roster did not build — one NOTHING re-hoisted,
+// original never had, and agbcc pays for it with a callee-saved register. (Its roster's hoists
+// ask for this placement directly, through the same `l3/hoist.ts` mechanism this variation uses; what
+// the variation adds is reaching the run on a tree the roster did not build — one NOTHING re-hoisted,
 // or one `l3/nearbase.ts` prepended into, which is the `/nearbase/sinkinit` pairing.)
 // Compiled pair on `synthetic:basehome`:
 // assigning at the top adds `push {r4, lr}` / `pop {r4}` / `pop {r0}` / `bx r0` where assigning at
-// the first use keeps a plain `bx lr`. The ladder that row records is the argument for the lever
+// the first use keeps a plain `bx lr`. The ladder that row records is the argument for the variation
 // being a PLACEMENT rather than a wider hoist — top-placed 11, not hoisted at all 9, placed at
 // first use 0. A hoist at the wrong place is worse than no hoist.
 //
-// A LEVER, NOT THE DEFAULT. Which placement the source used is per-function knowledge the asm does
+// A VARIATION, NOT THE DEFAULT. Which placement the source used is per-function knowledge the asm does
 // not carry: moving basecse's own head placement to first use moves 8 benchmark rows, 4 better and
 // 4 worse, two of the losses being matches. The UNSUNK spelling always rides beside this one —
 // head-placed wherever basecse built the run, prepend-placed under `/nearbase` — and the differ
@@ -25,7 +25,7 @@
 // immediately before the first TOP-LEVEL statement mentioning its name and never INTO a nested
 // scope, so it still dominates every use — planning a hoist inside a scope is `l3/scopebase.ts`'s
 // job and it does the domination work. `placeBaseLocals` carries the refusals; a run where none of
-// them moves is this lever declining.
+// them moves is this variation declining.
 //
 // SEMANTICS BY CONSTRUCTION: the moved value is a pure address leaf — it reads nothing, writes its
 // own plain cell and cannot fault — and every statement it crosses mentions the name nowhere, an

package/src/l3/slotorder.ts

@@ -7,13 +7,13 @@
 // LOWER `[sp,#k]`, and a source whose two spilled locals are declared the other way round compiles
 // to the same object with those two operands swapped and nothing else moved.
 //
-// A PER-COMPILER DEFAULT, NOT A RANKED AXIS. The asm does not underdetermine the answer: a
+// A COMPILER BEHAVIOR, NOT A RANKED VARIATION. The asm does not underdetermine the answer: a
 // `[sp,#k]` operand NAMES the slot, and slot → declaration rank is a FUNCTION once the compiler is
-// fixed. An axis exists where two source spellings collapse to the same object and only the differ
+// fixed. A variation exists where two source spellings collapse to the same object and only the differ
 // can choose between them; here the object chooses. The fan cost is zero — this rewrites the one
 // tree every candidate already carries, adding no candidate, no `structure()` call and no compile.
 //
-// WHY `emit` OWNS IT. Two reasons, and they point the same way. It must run AFTER every L3 lever,
+// WHY `emit` OWNS IT. Two reasons, and they point the same way. It must run AFTER every L3 respell variation,
 // because each of those rebuilds the declaration list (appends: basecse, scopebase, argbase,
 // nearbase, regspell, reindex; filters: unmerge, coalesce, dce, inlinebase, pollguard, unreduce),
 // and `emit` is last by construction. And it must NOT run at a `.emit(` call site: there are seven

package/src/l3/storage.ts

@@ -9,7 +9,7 @@
 // SHADOWING is what the copies disagreed on, and the disagreement is REAL rather than drift: a
 // name can be declared both a global and a local, because `SFn.globals` records what the code
 // REFERENCES (structure.ts `noteGlobal`) independently of what it declares. Which answer is right
-// depends on how the asking lever will SPELL the name, so the two questions are two functions
+// depends on how the asking pass will SPELL the name, so the two questions are two functions
 // here instead of one set each caller filters its own way:
 //   • it keeps the reference verbatim (`(u8 *)g`) — the shadow is harmless, the spelling denotes
 //     whatever the original access denoted: `declaredGlobals`;

package/src/l3/tailmerge.ts

@@ -25,7 +25,7 @@
 // above covers only below-vs-in-arms.
 //
 // KNOWN INTERACTIONS, both byte-level rather than soundness. This pass is unconditional like
-// `dce.ts` and `basecse.ts` rather than a differ-refereed lever, and the argument those files each
+// `dce.ts` and `basecse.ts` rather than a differ-refereed variation, and the argument those files each
 // state for themselves applies here too and was missing: a wrong merge changes recompiled bytes and
 // surfaces as a LOST match under the zero-lost gate, never as wrong C.
 //
@@ -49,7 +49,7 @@
 //     ways in `test/tailmerge.test.ts`.
 //     A ranked row is not stuck with either order: `/copy-defpos` (rank.ts) enumerates the
 //     def-position spelling beside the record's, so the merged form is a candidate the differ can
-//     pick on bytes — on `CountCollectedGems` its gate admits the axis on the map-ful and map-less
+//     pick on bytes — on `CountCollectedGems` its gate admits the variation on the map-ful and map-less
 //     lifts alike. What no arm of the fan spells is the third form, the hidden statement merged
 //     while KEEPING the record's order.
 //

package/src/l3/typing.ts

@@ -21,7 +21,7 @@ import { IrType, T, scalarTypeForAccess } from '../ir/types';
 import { type Expr, type SFn, exprChildren } from './ast';
 
 /** The declared type of a printed variable — the env `exprCType` judges rendered C against.
- *  THE one copy of the SFn→env derivation — printers, contracts and L3 levers alike: each
+ *  THE one copy of the SFn→env derivation — printers, contracts and L3 respell variations alike: each
  *  consumer judging against anything but the declarations it emits would let them disagree. */
 export type VarTypes = (name: string) => IrType | undefined;
 
@@ -133,7 +133,7 @@ export function arithConversionSignedness(l: Expr, r: Expr, varType: VarTypes):
  *
  * THE one rendered-signedness judgment, and it lives beside the declarations it judges against
  * because every consumer shares it: the C-family backend's operand pin, structure.ts's
- * unsigned-compare gate (the /uns-cmp axis) and its signed-compare pin, and — through
+ * unsigned-compare gate (the /uns-cmp variation) and its signed-compare pin, and — through
  * `arithConversionSignedness` above — initfirst's compare-meaning gate. Two of those models
  * disagreeing about one expression is the drift this placement prevents.
  *
@@ -149,7 +149,7 @@ export function arithConversionSignedness(l: Expr, r: Expr, varType: VarTypes):
  * instruction-for-instruction the same where `f` really returns `int`); a missing one is a
  * miscompile — with `u32 f(void);` in scope `f() / a` calls `__udivsi3` where the machine called
  * `__divsi3`, and `if (f() >= 0)` compiles to `bl f; mov r0, #0`, comparison and both arms gone.
- * The one consumer that reads `undefined` the other way is the /uns-cmp axis's own gate, which is
+ * The one consumer that reads `undefined` the other way is the /uns-cmp variation's own gate, which is
  * asking whether an operand is ALREADY unsigned.
  *
  * Anything narrower than 32 bits promotes to `int` and is therefore SIGNED, whatever it was