@asmlift/core 0.6.0 → 0.8.0

package/src/l3/reindex.ts

@@ -1,11 +1,11 @@
-// asmlift L3 — the walk→index RE-SPELLING, a differ-ranked representation lever.
+// asmlift L3 — the walk→index RESPELL VARIATION, differ-ranked.
 //
 // A compiler strength-reduces a source-level `arr[i]` loop into a pointer WALK (`*p; p += 1`),
 // so asmlift's faithful lift of the machine form emits the walk — but recompiling the walk
 // rarely reproduces the bytes the INDEXED source produced (different induction variable,
 // different regalloc). Which representation the source used is genuinely ambiguous from asm —
 // exactly the class of ambiguity asmlift resolves by CANDIDATES, not guesses (rank.ts: "types
-// are differ-ranked levers"). This module produces the indexed re-spelling of a structured
+// are differ-ranked variations"). This module produces the indexed re-spelling of a structured
 // function; enumerateCandidates emits BOTH and the objdiff score referees.
 //
 // v1 SCOPE (decline over approximate): a loop is re-spelled only when ALL hold —
@@ -29,7 +29,7 @@
 // it (its statements are the loop-preceding subset of the else arm, now unconditionally hoisted).
 // The walk pointers KEEP their init and lose their step — gcc folds a loop-invariant pointer
 // local into addressing, so `p = B; … p[i]` and `B[i]` compile identically, and keeping the
-// local is what lets the `/volatile` lever qualify a numeric B. Several walk pointers share the
+// local is what lets the `/volatile` variation qualify a numeric B. Several walk pointers share the
 // one counter (`dotprod`'s a/b pair). Its OWN rules, on top of the shared table below —
 //   • the guard tests THE SAME var the counter is initialised from, against 0, in the sense that
 //     skips the loop; the do-while exit is exactly `k != 0`;
@@ -227,7 +227,7 @@ export const COUNTDOWN_GATES: readonly Gate<CountdownCtx>[] = [
   },
   {
     id: 'global-counter',
-    why: 'a global counter’s final value is observable to every other caller, ISR and translation unit',
+    why: 'a global counter’s final value is observable to every other caller, interrupt handler and translation unit',
     sound: true,
     guardedBy: 'reindex.test.ts: the counter may not be a GLOBAL',
     rejects: (c) => !c.kIsDeclared,
@@ -255,14 +255,14 @@ export const COUNTDOWN_GATES: readonly Gate<CountdownCtx>[] = [
   },
   {
     id: 'body-exit',
-    why: 'the steps sat in the body tail, which a `continue` skips and a `for`’s inc does not',
+    why: 'the steps sat at the end of the body, which a `continue` skips and a `for`’s increment does not',
     sound: true,
     guardedBy: 'reindex.test.ts: a `break` in the body declines',
     rejects: (c) => c.coreHasExit,
   },
   {
     id: 'walk-base',
-    why: 'the kept init must be a value the rewrite can leave standing — a var, or a rematerializable address',
+    why: 'the kept init must be a value the rewrite can leave standing: a variable, or an address that can be loaded again',
     sound: true,
     guardedBy: 'reindex.test.ts: a walk pointer with no init ahead of the loop declines',
     rejects: (c) => c.badBases.length > 0,
@@ -290,7 +290,7 @@ export const COUNTDOWN_GATES: readonly Gate<CountdownCtx>[] = [
   },
   {
     id: 'leftover-walk',
-    why: 'a leftover outlives the deleted step, and its skip-arm twin reads a pointer that path never set',
+    why: 'a statement left outside the deleted step still reads the walk pointer, which a path that skipped the step never set',
     sound: true,
     guardedBy: 'reindex.test.ts: a leftover mentioning a walk pointer declines',
     rejects: (c) => c.leakyLeftovers > 0,
@@ -367,13 +367,18 @@ function reindexExpr(e: Expr, walk: WalkLoop, iv: string): Expr | null {
         ? { k: 'var', name: iv }
         : { k: 'bin', op: '+', l: { k: 'var', name: iv }, r: e.idx };
     // NOTE: this rebuilds the node from parts, so any field not named here is DROPPED — and the
-    // `index` node has exactly three optional ones (ast.ts): `lead`, `operandOff`, `baseOrdered`.
-    // `lead` is declined above (the deref side); it cannot arrive on the base side either, since
-    // `walk.base` is a local pointer and structuring only ever puts `lead` on an array GLOBAL's
-    // own name. Dropping the other two is right rather than merely harmless: `baseOrdered` is
-    // stamped per SYMBOL on an order-licensed GLOBAL, which a local var base never is, and
-    // `operandOff`'s readers (l3/basecse.ts, l3/offmember.ts) ask about a CONSTANT subscript,
-    // which the rewritten `i`/`i + k` index never is.
+    // `index` node has exactly five optional ones (ast.ts): `lead`, `baseElem`, `operandOff`,
+    // `baseOrdered`, `baseAdvanced`. `lead` is declined above (the deref side); it cannot arrive on
+    // the base side either, since `walk.base` is a local pointer and structuring only ever puts
+    // `lead` on an array GLOBAL's own name. Dropping the other four is right rather than merely
+    // harmless: `baseElem` states the element type of a base the C type walk cannot type, and the
+    // rebuilt base is `{k:'var', name: walk.base}` — a LOCAL pointer, whose declared type the walk
+    // reads straight out of the print env, so a statement about the base it replaced would describe
+    // a different base and the walk answers without one; `baseOrdered` is stamped per SYMBOL on an
+    // order-licensed GLOBAL, which a local var base never is; `operandOff`'s readers
+    // (l3/basecse.ts, l3/offmember.ts) ask about a CONSTANT subscript, which the rewritten
+    // `i`/`i + k` index never is; and `baseAdvanced` describes an address the machine reached from
+    // a CONSTANT one, which a walk pointer's is not.
     return { k: 'index', base: { k: 'var', name: walk.base }, idx, width: e.width, signed: e.signed };
   }
   let failed = false;
@@ -653,8 +658,8 @@ function tryExprWalk(
  *  one loop re-spelled, or null (no candidate) when nothing fired — callers emit the extra
  *  candidate only on non-null. Pure: never mutates the input SFn. `keptWalks` collects the names
  *  of the pointers each fired loop kept as its base — v1 the walk's base (a param lands in the
- *  set too, inertly: the volatile lever marks only declared locals), v2 the walk pointers
- *  themselves — the locals the /indexed/volatile product (rank.ts) narrows the volatile lever
+ *  set too, inertly: the volatile variation marks only declared locals), v2 the walk pointers
+ *  themselves — the locals the /indexed/volatile composition (rank.ts) narrows the volatile variation
  *  to. A v3 loop contributes nothing: it DELETES its pointer, and its base is qualified through
  *  the /livebase pairings instead. `gates` is the shared countdown admission table — a parameter
  *  so a test can ablate one entry and re-run the real pass. */
@@ -666,7 +671,7 @@ export function reindexWalks(
   const ptrVars = new Map<string, IrType>();
   const declTypes = declaredTypes(sfn);
   // BOTH volatility facts (ast.ts SFn.locals): the object-volatile counter, and the pointer whose
-  // POINTEE is volatile — which is the one the `/volatile` lever mints, and the one a walk carries.
+  // POINTEE is volatile — which is the one the `/volatile` variation mints, and the one a walk carries.
   const volatileLocals = new Set(
     sfn.locals.filter((l) => l.volatile === true || l.pointeeVolatile === true).map((l) => l.name),
   );

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,19 +62,19 @@
 // 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.
 import { assertHoistsDominate } from '../contracts';
 import { type IrType, T, scalarTypeForAccess } from '../ir/types';
 import type { Expr, SFn, Stmt } from './ast';
-import { mapExprChildren, stmtExprs, stmtLists } from './ast';
+import { isLoop, mapExprChildren, stmtExprs, stmtLists } from './ast';
 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>,
@@ -225,7 +227,7 @@ function collect(body: Stmt[], path: Stmt[][], loop: boolean[], idxPath: number[
   };
   for (const [i, s] of body.entries()) {
     at = i;
-    const isLoop = s.k === 'while' || s.k === 'dowhile' || s.k === 'for';
+    const repeats = isLoop(s);
     // A loop's OWN condition runs every iteration — a base there is loop-invariant exactly as a
     // body use is, and it lives at THIS list, which does not. basecse.ts and argbase.ts treat the
     // CONDITION the same way. They do NOT agree about a `for`'s `init`: basecse counts it in-loop
@@ -233,7 +235,7 @@ function collect(body: Stmt[], path: Stmt[][], loop: boolean[], idxPath: number[
     // it at the enclosing cadence, which is the truthful reading — it runs once. Recorded because
     // the divergence is real and an extraction has to pick one; both readings are pinned in
     // test/addr-placement.test.ts so the pick is deliberate rather than whichever survives.
-    stmtExprs(s).forEach((e) => visit(e, isLoop));
+    stmtExprs(s).forEach((e) => visit(e, repeats));
     if (s.k === 'for') {
       // `init`/`inc` are typed as the full Stmt union, so a COMPOUND one is type-legal. `stmtExprs`
       // reaches only its own expressions while `rewriteStmt` descends into any nested list — the
@@ -255,7 +257,7 @@ function collect(body: Stmt[], path: Stmt[][], loop: boolean[], idxPath: number[
       stmtExprs(s.inc).forEach((e) => visit(e, true));
     }
     for (const child of stmtLists(s)) {
-      collect(child, [...path, child], [...loop, isLoop], [...idxPath, i], st);
+      collect(child, [...path, child], [...loop, repeats], [...idxPath, i], st);
     }
   }
 }
@@ -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/tailret.ts

@@ -0,0 +1,70 @@
+// L3 spelling pass: drop a void `return;` the assembly says the source never wrote.
+//
+// `structure/retspell.ts` marks a return `unspelled` when the machine reached that epilogue without
+// the `b <epilogue>` a source `return;` compiles to — the reading, and what makes it decidable, is
+// stated there. This pass is the other half: a mark alone is not a licence to delete, because a
+// `return` is still a control transfer in the STATEMENT tree. Deleting one that something follows
+// lets control run on into it, and that is a semantic change, not a spelling one.
+//
+// So the licence is TAIL POSITION and nothing weaker: nothing executes after the statement on any
+// path, all the way up to the end of the function. A return ending a loop body, a `switch` arm, or
+// an `if` arm the function continues past is left exactly where it is, whatever the mark says.
+//
+// TWO SHAPES REFUSE EVEN IN TAIL POSITION, both because removing the statement would leave a
+// statement list that has to be re-spelled rather than shortened:
+//
+//   - the sole statement of a `then` arm. `if (c) { }` is not the answer — `if (!c) { … }` is, and
+//     which sense a compiler emits is a per-SITE question this pass holds nothing to decide.
+//   - the whole function body. A body is not a place a statement can vanish from.
+//
+// An `else` arm IS allowed to empty: an `if` with no else is the same statement, and both the
+// printer (`backend/cfamily.ts`) and `l3/dce.ts` already spell `else: []` that way.
+//
+// THE REFUSALS ARE PROSE, NOT A `Gate` TABLE, and that is the second of the three answers
+// `docs/level-tower.md` sanctions rather than an omission. A table buys the ablation — drop this
+// rule and something breaks — as a test instead of a claim, and it is worth building for a refusal a
+// round has HAD to instrument. None of these was: each is a property of one candidate's own
+// position, and `test/tailret.test.ts` holds a test per refusal, which is the ablation the table
+// would have bought. Convert them when a round has to argue about one.
+//
+// Ordering: after `l3/tailmerge.ts`, whose peel moves `assign`/`store`/`exprstmt` only, so a
+// `return` ending an arm blocks it — run first and this pass hands tailmerge arms it could not
+// otherwise peel, changing rows that have nothing to do with returns. Before `l3/dce.ts`, so its
+// branch peephole sees the `else` this pass empties. `pipeline.ts` commits that order.
+import type { SFn, Stmt } from './ast';
+
+/** Can this statement be deleted outright — a void return the asm did not spell? */
+const isDroppable = (s: Stmt): boolean => s.k === 'return' && s.value === undefined && s.unspelled === true;
+
+/** `stmts` rewritten. `isTail` — control falls off the END of the function after this list, so its
+ *  last statement is in tail position. `mayEmpty` — the list is allowed to come back empty. */
+function walk(stmts: Stmt[], isTail: boolean, mayEmpty: boolean): Stmt[] {
+  const out = stmts.map((s, i) => {
+    const tail = isTail && i === stmts.length - 1;
+    switch (s.k) {
+      case 'if':
+        return { ...s, then: walk(s.then, tail, false), else: walk(s.else, tail, true) };
+      case 'while':
+      case 'dowhile':
+      case 'for':
+        // A return inside a loop is never in tail position: the statement after it is the next
+        // iteration.
+        return { ...s, body: walk(s.body, false, false) };
+      case 'switch':
+        // Nor inside a `switch`: dropping an arm's return diverts it into the arm below.
+        return {
+          ...s,
+          cases: s.cases.map((c) => ({ ...c, body: walk(c.body, false, false) })),
+          ...(s.default ? { default: walk(s.default, false, false) } : {}),
+        };
+      default:
+        return s;
+    }
+  });
+  const last = out[out.length - 1];
+  return isTail && last !== undefined && isDroppable(last) && (out.length > 1 || mayEmpty) ? out.slice(0, -1) : out;
+}
+
+export function dropUnspelledReturns(sfn: SFn): SFn {
+  return { ...sfn, body: walk(sfn.body, true, false) };
+}

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