@asmlift/core 0.6.0 → 0.7.0

package/src/l3/basecse.ts

@@ -13,14 +13,14 @@
 // question the source answered per BASE — one register file spelled as a pointer local beside
 // scalar cells spelled as bare derefs. The `single-cell` gate is what makes the narrower answer
 // reachable: under `LIVEBASE_BLOCK_GATES` a base every access of which is ONE fixed offset stays
-// inline, and rank's LIVEBASE_ADMISSIONS roster emits each table's hoist — and every product of
+// inline, and rank's LIVEBASE_HOISTS roster emits each table's hoist — and every composition onto
 // it — as its own candidate family, for the differ to referee between them. The unit is
 // the (base, width, signedness) KEY, not the base — a base read at two widths is two keys, and the
 // gate can leave one of them inline while the other binds.
 //
 // COVERAGE: the roster (rank.ts) is SEVEN rows over FIVE gate tables — two PAIRS share a table and
 // differ only in placement, `/basefold` with `/basefold/sinkinit` and `/orderbase` with
-// `/orderbase/scoped` — and it is a set of hand-picked SUBSETS rather than a narrowness ranking;
+// `/orderbase-scoped` — and it is a set of hand-picked SUBSETS rather than a narrowness ranking;
 // only `/livebase` ⊇ `/livebase-block` are ordered by inclusion. A table
 // whose predicate cuts across the others therefore carves out a PARTIAL answer, which is what
 // `UNFOLDED_GATES` does. Measured at ONE stated scope, `decompile()`'s default structuring,
@@ -61,7 +61,7 @@
 // and `ldrb r0, [r4, #0x3]` — agbcc CSEs the symbol reference where it re-materializes the integer
 // — so the inline subscript spelling produces exactly the shape this rule reads as evidence
 // against it. asmlift lifts that asm back to the correct `((u8 *)&gS)[3]` and then offers the
-// named-base respelling anyway. Measured reach: of the 21 keys the symbol half newly admits over
+// spelling through a named base anyway. Measured reach: of the 21 keys the symbol half newly admits over
 // the artifact's agbcc rows in both symbol-map configurations, 4 are on a base whose address the
 // tree also uses as a value (2 distinct keys, on `kleod:ProcessInputAndUpdateEntities` and
 // `pokeemerald:TrySetCantSelectMoveBattleScript`).
@@ -74,14 +74,14 @@
 // `synthetic:foldhead` its match — which is why `index.operandOff` is carried from the lift
 // instead of re-derived, and why a committed pass that can drop it is worth a test
 // (test/basecse.test.ts, the "`operandOff` is provenance" describe). WHAT EACH ROW IS WORTH is
-// measured in rank.ts's note on `BASEFOLD_ADMISSIONS`, not here, and the two rows are not worth
+// measured in rank.ts's note on `BASEFOLD_HOISTS`, not here, and the two rows are not worth
 // the same thing. Promoting the hint to a default would need this paragraph to say something it
 // does not.
 //
-// It is EVIDENCE and not proof, which is why `BASEFOLD_GATES` below is a lever rather than a
+// It is EVIDENCE and not proof, which is why `BASEFOLD_GATES` below backs a variation rather than a
 // relaxation of the default table. agbcc folds a subscript but keeps an aggregate MEMBER offset in
 // the memory operand: `((struct S *)0x3001100)->b` emits `.word 0x3001100` + `ldr [r0, #0x4]`,
-// byte-identical to the named-base spelling, and the same holds for a union member and for a
+// byte-identical to the spelling through a named base, and the same holds for a union member and for a
 // store. So the shape has two sources and asmlift can spell only one of them; rank.ts offers both
 // and the differ referees.
 //
@@ -97,7 +97,7 @@
 // AGGREGATE base (F9 spells a SCALAR global as a bare `var`, which is never an `index`-of-leaf, so
 // scalar recovery is untouched). Non-leaf bases (a local, a struct-element `p[a0]`,
 // arithmetic) are excluded: agbcc may re-derive those, so hoisting them can
-// MISMATCH (empirically confirmed) — the differ-refereed `/addr-home` axis
+// MISMATCH (empirically confirmed) — the differ-refereed `/addr-home` variation
 // (structure/analysis.ts homeSharedAddresses) serves the shared gaddr-free ARITHMETIC bases
 // instead.
 // The hoisted local carries the access's pointer type, so the
@@ -149,8 +149,8 @@ const keyOf = (base: HoistableBase, width: number, signed: boolean): string => `
 /** The key's own grammar, read back — `<leafId>[ <type>] <width> <signed>`.
  *
  *  IT LIVES BESIDE `keyOf` BECAUSE THAT IS THE ONLY THING THAT MAKES IT SAFE. The key is a string
- *  and its readers are elsewhere — `l3/homesplit.ts` builds a candidate LABEL out of it, and a
- *  label is a candidate's identity — so a second file knowing this grammar is a collision waiting
+ *  and its readers are elsewhere — `l3/homesplit.ts` builds a candidate's VARIATION out of it, and a
+ *  candidate's variations are its identity — so a second file knowing this grammar is a collision waiting
  *  for the next base kind (`homeSplitTag` states the one the cast form causes).
  *
  *  The one space inside a cast's base id is this grammar's own separator, not the type's: every
@@ -357,7 +357,7 @@ export interface BaseKey {
    *  what a pointer local's own initializer STATEMENT produces (see raise/globalshape.ts's header
    *  for the compile that separates the two), while the inline cast produces the other order — so
    *  it is evidence a home is what the source wrote. Read only by `ORDERBASE_GATES` (rank.ts);
-   *  false for every base a compiler that has not opted in produced, which is what keeps the axis
+   *  false for every base a compiler that has not opted in produced, which is what keeps the variation
    *  off those targets. */
   orderLicensed: boolean;
 }
@@ -380,13 +380,13 @@ export const BASECSE_GATES: readonly Gate<BaseKey>[] = [
     // Censused at `decompile()`'s default structuring, map-less, one tree per row over the
     // artifact's 404 agbcc rows: `ORDERBASE_GATES` admits 12 keys on 10 rows, 11 of them cast keys.
     id: 'cast-base',
-    why: 'a struct element’s reinterpret cast is the inline spelling unless the assembly says the base had a home',
+    why: 'a struct element’s reinterpret cast is the inline spelling unless the assembly says the base was held in a local',
     sound: false,
     rejects: (c) => c.castBase,
   },
   {
     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: reachedOnce,
   },
@@ -397,8 +397,27 @@ export const BASECSE_GATES: readonly Gate<BaseKey>[] = [
     rejects: (c) => c.inLoop,
   },
   {
+    // A KNOWN COUNTEREXAMPLE, recorded here rather than fixed. `LIVEBASE_GATES` already names it —
+    // an MMIO wait or poll stores and re-reads ONE fixed offset through ONE register the whole
+    // time — so this gate rejects a base the target demonstrably held in a register, and the row
+    // it costs is carried by `/livebase`, which is this table minus the placement gates.
+    //
+    // NOT FIXED BY EXCLUDING A VALUELESS READ FROM THE CENSUS: that hides a real access to make
+    // the gate right for the wrong reason — the premise is falsified by the function's assembly,
+    // not by how the access is spelled. NOT FIXED BY EXEMPTING DEVICE-REGISTER BASES EITHER: that
+    // is the sound rule, and its blast radius is every MMIO row in the corpus against a gate this
+    // comment records was bought with a real match. It wants its own round and its own zero-flip
+    // gate.
+    //
+    // THE STRUCTURER'S DEAD-READ SPELLING (structure.ts `unreadResult`) INTERACTS, but not on the
+    // map-fed default: that spelling requires a qualifier to reach the access, a CAST spelling
+    // (`((s32 *)&REG_DMA3SAD)[2]`) carries none, and a map-fed DMA tree spells it exactly that
+    // way — so no statement is emitted there, offset 8 is touched once, and the base local
+    // survives. The inhabitant is the `/raw-globals` subtree, where the read IS spelled and this
+    // gate DOES demote; that subtree's own winner is a `/livebase` candidate, so nothing on the
+    // ranked path loses by it. Stated because the demotion is invisible from either file alone.
     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,
   },
@@ -427,14 +446,14 @@ export const BASECSE_GATES: readonly Gate<BaseKey>[] = [
 export const BASEFOLD_GATES: readonly Gate<BaseKey>[] = [
   {
     id: 'single-use-unfolded',
-    why: 'one access re-materializes as cheaply as a named local, unless its offset survived the fold',
+    why: 'a base accessed once is as cheap to load again as to hold in a named local, unless its offset survived the fold',
     sound: false,
     rejects: (c) => reachedOnce(c) && !c.unfoldedOffset,
   },
   ...ablateHeuristic(BASECSE_GATES, 'single-use'),
 ];
 
-/** The `/livebase` lever's admission (rank.ts): the default rules with both PLACEMENT heuristics
+/** The `/livebase` variation's admission (rank.ts): the default rules with both PLACEMENT heuristics
  *  ablated, keeping only `single-use`. `loop` and `repeated-const-offset` predict which spelling
  *  the compiler chose, and both predictions have a counterexample — an MMIO poll (`p[2] = go;
  *  while (p[2] & BUSY) {}`) stores and re-reads a fixed offset through ONE register the whole
@@ -447,7 +466,7 @@ export const LIVEBASE_GATES: readonly Gate<BaseKey>[] = ablateHeuristic(
 
 /** `/livebase-block`'s admission (rank.ts): `/livebase` plus `single-cell`. The two tables differ
  *  by exactly one gate, so `without(LIVEBASE_BLOCK_GATES, 'single-cell')` is `/livebase`'s own
- *  admission and this selectivity axis prices by ablation like every other.
+ *  admission and this selectivity rule prices by ablation like every other.
  *
  *  `single-cell` GENERATES a narrower candidate; it does not classify, and taking it for a compiler
  *  fact is the way to misuse it. Its counterexample is in this corpus: `synthetic:sizebound`'s
@@ -470,13 +489,13 @@ export const LIVEBASE_GATES: readonly Gate<BaseKey>[] = ablateHeuristic(
  *  whenever an admission is added to or removed from the roster.
  *  HOW: prefer the edit-free form — import this array and `splice` the gate out of it before the
  *  first `enumerateCandidates` call, since the roster holds a reference to this very object. The
- *  env-read recipe on BASEFOLD_ADMISSIONS edits files instead, and a tap reverted underneath a
+ *  env-read recipe on BASEFOLD_HOISTS edits files instead, and a tap reverted underneath a
  *  running process reports ZEROES rather than crashing, which reads exactly like "the rule never
  *  fires"; if you use it, hash the tree either side of the window and quote both hashes.
  *
- *  A CENSUS OVER WINNING LABELS CANNOT STAND IN FOR THAT — "only a row whose winner carries
+ *  A CENSUS OVER WINNERS' VARIATIONS CANNOT STAND IN FOR THAT — "only a row whose winner carries
  *  `/livebase-block` can move" is unsound for the reason rank.ts's `seen` dedup spells out. This
- *  table's own winning-label census reads 5 rows and read 7 before `/unfolded` shipped, and the
+ *  table's own census over winners' variations reads 5 rows and read 7 before `/unfolded` shipped, and the
  *  two that left differ: `synthetic:foldpark` by RENAME (byte-identical source, MATCH either
  *  side), `synthetic:unfoldpark` because its winning SPELLING changed, 402 bytes at diff:9 to 397
  *  at MATCH.
@@ -597,7 +616,8 @@ export const UNFOLDED_GATES: readonly Gate<BaseKey>[] = [
  *  reading the population: where `raise/globalshape.ts` shapes a name the structurer usually spells
  *  it bare and no key exists here at all — but a shape is ONE element type for the whole name, so an
  *  access that strides something else keeps its cast and its key. `kleod:SetupBG3WindowOverlay`'s
- *  `gBgInfo` derives `elemSize 4` and still reaches this table at stride 28, in both arms.
+ *  `gBgInfo` (a row retired 2026-09-13) derived `elemSize 4` and still reached this table at stride
+ *  28, in both arms.
  *
  *  What this table admits, censused over the artifact's 370 agbcc rows: map-less 8 rows / 10 keys,
  *  map-ful 10 rows / 12 keys. TWO shapes, and the arms differ:
@@ -624,8 +644,8 @@ export const UNFOLDED_GATES: readonly Gate<BaseKey>[] = [
  *  exemption cannot have.
  *
  *  `loop` and `repeated-const-offset` STAY. Neither is about the base's identity and both are fan
- *  control; ablating them is `/livebase`'s axis, already on the roster, and a row that wants the
- *  product is one roster line. THE PRICE OF THAT IS A HOLE, and it is named rather than left for a
+ *  control; ablating them is `/livebase`'s variation, already on the roster, and a row that wants the
+ *  pairing is one hoist. THE PRICE OF THAT IS A HOLE, and it is named rather than left for a
  *  reader to find: a licensed base with a use inside a loop is admitted by NO table on the roster —
  *  this one refuses it on `loop`, and every table that ablates `loop` refuses it on `cast-base` or
  *  `single-use` — which is the "a base set that is no row's stays unreachable" debt
@@ -652,7 +672,7 @@ export const ORDERBASE_GATES: readonly Gate<BaseKey>[] = [
   ...ablateHeuristic(ablateHeuristic(BASECSE_GATES, 'cast-base'), 'single-use'),
   {
     id: 'order-licensed',
-    why: 'nothing in the assembly says this base had a home: the index was scaled first, or the order says nothing',
+    why: 'nothing in the assembly says this base was held in a local: the index was scaled first, or the order says nothing',
     sound: false,
     rejects: (c) => !c.orderLicensed,
   },
@@ -718,13 +738,13 @@ function admit(sfn: SFn, gates: readonly Gate<BaseKey>[]): { c: Collected; keys:
  *  `scope` DECLINES, and the overload is how a caller is told: `null` means the placement had
  *  nothing to say about this function, because no init landed inside a nested list. That tree is
  *  byte-for-byte the `first-use` spelling (l3/hoist.ts's `nested`), and the roster withholds the
- *  `first-use` row for this table deliberately (rank.ts, ORDERBASE_ADMISSIONS) — so returning it
+ *  `first-use` row for this table deliberately (rank.ts, ORDERBASE_HOISTS) — so returning it
  *  ships the withheld candidate under the scoped row's name.
  *
  *  IT WITHDRAWS A SPELLING RATHER THAN COLLAPSING A DUPLICATE, which is what the decline costs.
- *  `ORDERBASE_ADMISSIONS` holds exactly two rows, `head` and `scope`, so nothing is ever enumerated
+ *  `ORDERBASE_HOISTS` holds exactly two rows, `head` and `scope`, so nothing is ever enumerated
  *  at `first-use` for this table and the refused tree has no twin to fold into — its shape and
- *  `/volatile` products go with it. Over each project's whole `asm` tree, map-ful: of the 48
+ *  `/volatile` compositions go with it. Over each project's whole `asm` tree, map-ful: of the 48
  *  functions `ORDERBASE_GATES` admits, 7 place an init inside a nested list and 41 do not, and for
  *  29 of the 41 the refused spelling is one the `head` row does not already produce. Instrumented
  *  on two of those, both map-ful — the `kleod:StreamCmd_SetBGScroll` row (fan 11), and
@@ -785,13 +805,13 @@ export function hoistBaseLocals(
   }
   const out = { ...sfn, body, locals };
   // The two FLAT placements can only put the run in the top-level list, above every use of it by
-  // construction. `scope` puts an init inside a nested list, which is where a placing lever can ship
+  // construction. `scope` puts an init inside a nested list, which is where a placing variation can ship
   // the one failure the byte differ rewards — a read of a local whose assignment does not reach it —
   // so the tree it emits is checked rather than argued (contracts.ts).
   //
   // THE POPULATION IS THE MOTION, and `moved` is what the placer says it moved rather than what this
   // function minted. The leading run this pass inherits is the DEFAULT hoist's, committed by
-  // `structureChecked` before rank's levers see the tree (pipeline.ts), and `scope` moves those
+  // `structureChecked` before rank's variations see the tree (pipeline.ts), and `scope` moves those
   // inits too — so `newLocals` names less than half of what has to be judged. Real inhabitants, in the
   // CHECKOUTS rather than in a benchmark row — `DecompressAndLoadLevel` in klonoa and `sub_8052474`
   // in sa3, both map-ful — each sink one inherited `p0` beside the minted `p1`.

package/src/l3/coalesce.ts

@@ -217,7 +217,7 @@ export interface MergePair {
  *  `const-fed` is what keeps three of them (ablate it and the span path offers 273). A rule
  *  refusing every in-loop local would make that bound redundant; this one does not, so any further
  *  relaxation of `const-fed` is a multiplier, and two call sites pay it (`/coalesce` and
- *  `/scopebase-coalesce`; the `/livebase` pairings enumerate the ARM path and pay
+ *  `/scopebase/coalesce`; the `/livebase` pairings enumerate the ARM path and pay
  *  ARM_DISJOINT_GATES' `arm-init` instead). */
 export const COALESCE_GATES: readonly Gate<MergePair>[] = [
   {
@@ -234,7 +234,7 @@ export const COALESCE_GATES: readonly Gate<MergePair>[] = [
   },
   {
     id: 'volatile',
-    why: 'a volatile qualifier (object or pointee) is observable and typeToString does not spell it — merging strips or adds it',
+    why: 'a `volatile` qualifier, on the variable or on what it points to, is observable, and merging would drop or add it',
     sound: true,
     guardedBy: 'coalesce.test.ts: a volatile pair never merges',
     rejects: (c) => c.eitherIsVolatile,
@@ -252,7 +252,7 @@ export const COALESCE_GATES: readonly Gate<MergePair>[] = [
   },
   {
     id: 'const-fed',
-    why: 'a load-fed local — other than a for induction variable, whose feeds are its own — is one the compiler had a reason to keep where it was',
+    why: 'a local set from a memory load, other than a `for` loop counter, is one the compiler had a reason to keep where it was',
     sound: false,
     rejects: (c) => !c.x.constFed || !c.y.constFed,
   },
@@ -265,20 +265,20 @@ export const COALESCE_GATES: readonly Gate<MergePair>[] = [
   },
   {
     id: 'first-is-write',
-    why: 'a survivor first MENTIONED by a read would see the absorbed value there',
+    why: 'a survivor whose first mention is a read would see the absorbed value there',
     sound: false,
     rejects: (c) => !c.y.firstIsWrite,
   },
 ];
 
-/** Every legal single merge, each as its own tree — NOT one committed choice.
+/** Every legal single merge, each as its own tree — NOT one committed decision.
  *
  *  Which pair a register allocator coalesced is not derivable from the L3 tree, and first-fit gets
  *  it wrong. Run kleod:UpdateHUDCounterDisplay's published repro script (results.json carries it)
  *  and read the candidate table: of its two legal merges, one scores WORSE than not merging at all
  *  and declaration order is the one that picks it. Emitting no merges at all costs that row its
  *  match, which is what guards this file. `rank.ts` already has the idiom for exactly this —
- *  `/regcopy`'s "the tail choice is allocator-ambiguous, so both are ranked" — so every candidate is
+ *  `/regcopy`'s "the tail decision is allocator-ambiguous, so both are ranked" — so every candidate is
  *  emitted and the differ referees.
  *
  *  ACCEPTED, NOT FIXED: a survivor assigned only on SOME paths still absorbs the other's value on
@@ -356,7 +356,7 @@ export const ARM_DISJOINT_GATES: readonly Gate<ArmPair>[] = [
   },
   {
     id: 'volatile',
-    why: 'a volatile qualifier (object or pointee) is observable — merging strips or adds it',
+    why: 'a `volatile` qualifier, on the variable or on what it points to, is observable, and merging would drop or add it',
     sound: true,
     guardedBy: 'coalesce.test.ts: a volatile pair never merges',
     rejects: (c) => c.eitherIsVolatile,
@@ -370,7 +370,7 @@ export const ARM_DISJOINT_GATES: readonly Gate<ArmPair>[] = [
   },
   {
     id: 'arm-init',
-    why: 'a local not const-initialized at its arm’s first mention is one the compiler had a reason to keep — the growth bound const-fed gives the span table',
+    why: 'a local its arm does not first set to a constant is one the compiler had a reason to keep apart',
     sound: false,
     rejects: (c) => !c.bothArmConstInit,
   },
@@ -378,7 +378,7 @@ export const ARM_DISJOINT_GATES: readonly Gate<ArmPair>[] = [
 
 /** The arm-disjoint merges alone — the class the livebase pairings enumerate (rank.ts): the
  *  demanding row's shared counter is arm-disjoint, and the span-model merges already ride the
- *  plain /coalesce label, so pairing them too would multiply candidates with no row behind it. */
+ *  plain /coalesce variation, so pairing them too would multiply candidates with no row behind it. */
 export function armDisjointCandidates(sfn: SFn): { merged: string; sfn: SFn }[] {
   return armDisjointUnder(ARM_DISJOINT_GATES, sfn).candidates;
 }

package/src/l3/gates.ts

@@ -7,10 +7,14 @@
 //
 // `why` is a LABEL, one line. The argument for why the rule is correct belongs in the file header,
 // which has room; duplicating it here is how a table stops paying for itself.
+//
+// A table a variation's definition names (`variation-gates.ts`) shows its `why` to a reader, in the
+// webapp's variation drawer, so there the label is plain prose: no tag, file or function name, or
+// shouted word. `variation-offers.test.ts` holds it to that.
 export interface Gate<Ctx> {
   /** stable, kebab-case; appears in test names and in the contract report */
   readonly id: string;
-  /** one line: the reason the rule exists */
+  /** one line: the reason the rule exists, readable without the code */
   readonly why: string;
   /** Remove it and some candidate is WRONG, not merely worse. Everything else is a codegen
    *  heuristic the differ still referees. This flag is what makes `guardedBy` mandatory. */
@@ -86,3 +90,73 @@ export function gateTableDefects<Ctx>(gates: readonly Gate<Ctx>[]): string[] {
   }
   return out;
 }
+
+/** A gate table that counts its own refusals — {@link tallying}'s return. */
+export interface Tallied<Ctx> {
+  /** Hand this to the pass, in place of the table it wraps. */
+  readonly gates: readonly Gate<Ctx>[];
+  /** The census so far, most-refused first, ties in table order. A snapshot: counts keep
+   *  accumulating across every later call, which is what a corpus-wide census wants.
+   *
+   *  THERE IS NO RESET, deliberately — a per-row census is two snapshots DIFFED, not a fresh
+   *  wrapper per row, because a wrapper is a new table IDENTITY and a reader that keys on one
+   *  (`rank.ts`'s `censuses` memo) sees a fresh key every row. Counting is keyed by `g.id`, so a
+   *  table COMPOSED from several should be run past `gateTableDefects` first: two rules sharing an
+   *  id sum into one number, and the contract test only checks the tables on its own roster. */
+  readonly refusals: () => readonly (readonly [string, number])[];
+}
+
+/** The same table, wrapping each `rejects` in a counter — so a caller OUTSIDE core can obtain the
+ *  per-id census that `l3/coalesce.ts` and `structure/namecoalesce.ts` hand-roll into their return
+ *  type (`l3/scopebase.ts` reports the same attribution per KEY), from any pass that takes its
+ *  table as a parameter:
+ *
+ *      const t = tallying(UNMERGE_SITE_GATES);
+ *      unmergeJoins(sfn, { site: t.gates });
+ *      console.log(t.refusals());   // [['empty-arm', 168], ['no-merge-name', 80]]
+ *
+ *  THAT IS THE API AND NOT YET A CENSUS: nothing exports a corpus of trees to loop over, and a
+ *  tabled pass's only shipped caller is normally inside core. Taking the census off a REAL
+ *  enumeration is `pnpm bench gates --pass <id>`, whose header
+ *  (`apps/benchmark/src/run/gate-census.ts`) holds the measured reasons it is a subcommand rather
+ *  than a script to copy, and what a SECOND censusable pass costs.
+ *
+ *  WHAT IT COUNTS IS AN EVALUATION THAT ANSWERED TRUE, not a site. Under `firstRejection` — which
+ *  short-circuits — that is the FIRST rejecter, so this produces the same census the hand-rolled
+ *  maps do, with the same reading: an id absent from it is starved OR REDUNDANT WITH an earlier
+ *  rule, and telling the two apart takes the same rule run with the rest of the table empty
+ *  (`grep -n "ON ITS OWN" packages/core/src/raise/globalshape.ts`, whose dated table ships three
+ *  rules of the second kind). A consumer that asks the table something else — `.some`, `.filter` —
+ *  gets one count per evaluation instead, which is a different question and rarely the one wanted.
+ *
+ *  AND IT COUNTS REFUSALS, WHICH IS NOT REACH. A rule can refuse hundreds of times and still change
+ *  no output, because a later rule or a narrowing outside the table would have refused the same
+ *  sites: that is the MOVED column, it costs an ablation rather than a census, and `l3/unmerge.ts`'s
+ *  header carries the worked example of the two disagreeing.
+ *
+ *  IT CHANGES NO BEHAVIOUR: each wrapper's predicate IS the original's, `id`/`why`/`sound`/
+ *  `guardedBy` are carried, so `without`, `ablateHeuristic` and `gateTableDefects` all still hold
+ *  over the result. What it does change is the table's IDENTITY, and some readers key on that —
+ *  `rank.ts`'s `censuses` memo is a `Map` over `Gate<BaseKey>[]` instances — so wrap once and reuse
+ *  `gates`, rather than per call. */
+export function tallying<Ctx>(gates: readonly Gate<Ctx>[]): Tallied<Ctx> {
+  const counts = new Map<string, number>();
+  const order = new Map(gates.map((g, i) => [g.id, i]));
+  return {
+    gates: gates.map((g) => ({
+      ...g,
+      rejects: (c: Ctx) => {
+        const r = g.rejects(c);
+        if (r) {
+          counts.set(g.id, (counts.get(g.id) ?? 0) + 1);
+        }
+        return r;
+      },
+    })),
+    refusals: () =>
+      [...counts].sort((a, b) => b[1] - a[1] || (order.get(a[0]) ?? 0) - (order.get(b[0]) ?? 0)) as readonly (readonly [
+        string,
+        number,
+      ])[],
+  };
+}

package/src/l3/hoist.ts

@@ -208,7 +208,7 @@ function scopeSite(list: Stmt[], name: string): { list: Stmt[]; at: number } | n
  *  different bytes. Where no nested list holds every mention this IS `first-use`, which is what
  *  makes it a placement rather than a second policy.
  *
- *  These three are the axis a roster admission may state (rank.ts) and the only values
+ *  These three are the positions a hoist may state (rank.ts) and the only values
  *  `hoistBaseLocals` accepts. */
 export type HoistPlacement = 'head' | 'first-use' | 'scope';
 

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()];
 }