@asmlift/core 0.3.0 → 0.4.0

package/src/raise/shortcircuit.ts

@@ -1,4 +1,16 @@
-// asmlift — boolean-value short-circuit recovery (F-CFG; successor-aware, agbcc-class).
+// asmlift — short-circuit connective recovery (F-CFG; successor-aware, agbcc-class).
+//
+// A `&&`/`||` reaches the IR in two shapes, and this module recovers BOTH into the SAME pair of
+// opcodes (`logic_and`/`logic_or`) the backend already prints as `&&`/`||`:
+//
+//   - the VALUE form (`return a && b`) — a diamond whose merge phi is the boolean. That is
+//     `recognizeShortCircuit`, described below.
+//   - the CONTROL-FLOW form (`if (a || b) X else Y`) — no value at all, just two `cond_br` blocks
+//     that share a target. That is `recognizeBranchShortCircuit`, at the bottom of this file.
+//
+// They are one concept and stay in one file, but they are separate passes because their inputs do
+// not overlap: the value form needs the second block to end in `br` carrying a phi argument, the
+// branch form needs it to end in `cond_br`.
 //
 // `return a && b` compiles (agbcc) to a value-producing diamond: `if (a==0) result=0; else result=(b!=0)`,
 // where the merge block returns the phi. The structurer lowers that as `if (a==0){v0=0}else{v0=(-b|b)>>31}
@@ -27,26 +39,10 @@
 // Guards stay conservative: the CONST is exactly 0/1, Vb is a bool op or 0/1 const, the head condition is a
 // negatable icmp, and any deviation falls through untouched (a miss, never a miscompile).
 import { Block, Fn, Op, Value, defOpMap, mkOp, mkValue, predecessors, replaceAllUsesWith } from '../ir/core';
-import type { Opcode } from '../ir/opcodes';
-import { EFFECTFUL_OPS } from '../ir/opcodes';
+import { HOIST_UNSAFE_OPS, NEGATED_ICMP } from '../ir/opcodes';
 import { T } from '../ir/types';
 
-const NEGATE_ICMP: Record<string, Opcode> = {
-  icmp_eq: 'icmp_ne',
-  icmp_ne: 'icmp_eq',
-  icmp_slt: 'icmp_sge',
-  icmp_sge: 'icmp_slt',
-  icmp_sgt: 'icmp_sle',
-  icmp_sle: 'icmp_sgt',
-  icmp_ult: 'icmp_uge',
-  icmp_uge: 'icmp_ult',
-  icmp_ugt: 'icmp_ule',
-  icmp_ule: 'icmp_ugt',
-};
-const BOOL_OPS = new Set([...Object.keys(NEGATE_ICMP), 'logic_and', 'logic_or']);
-// Ops with an observable side effect — unsafe to HOIST out of a short-circuit's conditional arm
-// (they would run unconditionally). Derived from the ONE effect table in ir/opcodes.ts.
-const SIDE_EFFECT = EFFECTFUL_OPS;
+const BOOL_OPS = new Set([...Object.keys(NEGATED_ICMP), 'logic_and', 'logic_or']);
 
 /** Fold `(-x | x) >> 31` (logical shift) → `x != 0`, in place. agbcc's branchless is-nonzero idiom. */
 // NOT exported: it must run before the diamond fold, an ordering only recognizeShortCircuit's
@@ -124,6 +120,16 @@ export function recognizeShortCircuit(fn: Fn): boolean {
         if (bp.length !== 1) {
           continue;
         }
+        // The ENTRY block is never a feeder, for the same reason it is never ^g in the branch form
+        // below: `predecessors()` walks successor edges only, so an entry block that is also a loop
+        // header shows one predecessor while actually running BEFORE it on the first iteration.
+        // Hoisting its body then reorders it and deleting it moves `fn.blocks[0]`. Silent — verify,
+        // assertResolved and assertDerefsTyped all pass. PRE-EXISTING (this fold predates the branch
+        // form and `main` miscompiles the same MIPS input); fixed here because the branch form's
+        // note used to assert this one was safe.
+        if (bfeed === fn.blocks[0]) {
+          continue;
+        }
         const h = bp[0];
         const ht = term(h);
         if (ht.opcode !== 'cond_br') {
@@ -157,7 +163,7 @@ export function recognizeShortCircuit(fn: Fn): boolean {
         }
         const cond = ht.operands[0];
         const condDef = defs.get(cond);
-        if (!condDef || !NEGATE_ICMP[condDef.opcode]) {
+        if (!condDef || !NEGATED_ICMP[condDef.opcode]) {
           continue;
         } // head condition must be a negatable icmp
 
@@ -171,14 +177,14 @@ export function recognizeShortCircuit(fn: Fn): boolean {
         // expression, where C's own short-circuit re-guards them. Any side effect ⇒ DECLINE the fold — the
         // merge-variable spelling the fall-through leaves is correct (the side effect stays in B's block),
         // just possibly non-matching.
-        if (bfeed.ops.slice(0, -1).some((op) => SIDE_EFFECT.has(op.opcode))) {
+        if (bfeed.ops.slice(0, -1).some((op) => HOIST_UNSAFE_OPS.has(op.opcode))) {
           continue;
         }
         bfeed.ops.slice(0, -1).forEach(before); // hoist B's pure body (defines Vb; harmless if a dead const)
         let condSide = cond;
         if (wantNeg) {
           condSide = mkValue(T.unk(32));
-          before(mkOp(NEGATE_ICMP[condDef.opcode], { operands: [...condDef.operands], results: [condSide] }));
+          before(mkOp(NEGATED_ICMP[condDef.opcode], { operands: [...condDef.operands], results: [condSide] }));
         }
         // Vb const → the phi reduces to the (possibly negated) condition; Vb bool → a && / || connective.
         let res = condSide;
@@ -205,3 +211,239 @@ export function recognizeShortCircuit(fn: Fn): boolean {
   }
   return changed;
 }
+
+// ── the CONTROL-FLOW form ───────────────────────────────────────────────────────────────────────
+//
+// `if (a || b) X else Y` produces no value: it is two `cond_br` blocks that SHARE a target.
+//
+//     ^h:  cond_br c1, ^X, ^g          <- `a`
+//     ^g:  … ; cond_br c2, ^Y, ^X      <- `b`   (sole predecessor ^h)
+//
+// Nothing in the tower recognizes that today, so the structurer reaches ^X from two arms and
+// TAIL-DUPLICATES it — `if (a) X else { if (b') Y else X }`. The duplicate is correct C but it is
+// not the C the compiler compiled, and the duplicated tail costs every byte it contains.
+//
+// The fold rewrites ^h's terminator to one `cond_br` over a connective and drops ^g. Which
+// connective, and which successor slot, follows from WHICH of ^h's edges leads to ^g:
+//
+//   ^g is ^h's FALL   → ^g runs iff !c1, so the SHARED block is taken iff `c1 || cShared`
+//                       ⇒ cond_br(logic_or(c1, cShared))[shared, other]
+//   ^g is ^h's TAKEN  → ^g runs iff  c1, so the OTHER  block is taken iff `c1 && cOther`
+//                       ⇒ cond_br(logic_and(c1, cOther))[other, shared]
+//
+// where `cShared`/`cOther` is ^g's own condition ORIENTED at that block — ^g's `cond_br` operand
+// when it already branches there, otherwise its negation (so ^g's condition must be a negatable
+// icmp, exactly as in the value form). Both spellings keep ^h's original successor ORDER for the
+// edge that did not change, so the branch sense the frontend read out of the asm is preserved.
+//
+// REFUSALS (each one a real way this could be wrong, not a hypothetical):
+//
+//   - ^g is the ENTRY block. `predecessors()` walks successor edges only — it does not model the
+//     implicit edge into `fn.blocks[0]` — so an entry block that is ALSO a loop header (its one
+//     real predecessor being its own latch) passes the sole-predecessor test below while the whole
+//     soundness argument fails for it: on the first iteration ^g runs BEFORE ^h, so hoisting ^g's
+//     body into ^h reorders it, and deleting ^g moves the entry to another block entirely. That
+//     turns an entry-guarded `while` into a `do…while` whose body runs once unconditionally —
+//     silent wrong code, caught by no contract (verify, assertResolved and assertDerefsTyped all
+//     pass). MIPS and PPC reach this: only thumb.ts inserts a synthetic preheader that would give
+//     the header a second predecessor. `retsink.ts` guards the same way (`fn.blocks[0] !== m`).
+//   - ^g has a predecessor other than ^h — folding would delete a block still reachable elsewhere.
+//   - ^g has block params — ^h's edge binds them, and dropping the edge drops the binding.
+//   - ^h and ^g both test the SAME value against CONSTANTS — that is a comparison-tree `switch`,
+//     not a hand-written `||`. switch-recover.ts requires every test's `cond_br` operand to be an
+//     `icmp` (its `isCmpOpcode` gate), and a `logic_or` is not one, so folding first PERMANENTLY
+//     disqualifies the recovery and a clean `switch (x) { case 1: case 2: … }` degrades to a chain
+//     of nested `if`s. The switch is the better recovery and it is the more specific one, so it
+//     wins the shape. Cost: a genuine source-level `x == 1 || x == 2` that is NOT part of a wider
+//     tree also declines — the same conservative trade loops.ts makes when it refuses to infer a
+//     header from `cond_br` shape.
+//   - ^g holds a side effect — its ops move into ^h, which runs UNCONDITIONALLY. A store in `b`
+//     would then execute even when `a` already decided the branch. (`a || (*p = 1)`.)
+//   - a value defined in ^g is used outside ^g, or used more than once. Then the structurer
+//     MATERIALIZES it into a local, which renders as a statement BEFORE the `if` — turning `b`'s
+//     conditional computation into an unconditional one. Single-use-and-local is precisely the
+//     shape analysis.ts inlines into the connective's right operand, where C's own short-circuit
+//     re-guards it. This is what keeps a load in `b` from being hoisted across the guard in `a`.
+//   - the two edges into the shared block carry DIFFERENT args. Only one edge survives the fold,
+//     so it can only carry one argument list; picking either would silently drop the other path's
+//     phi input.
+//   - ^g's two successors are the same block, or ^g's condition is not a negatable icmp when the
+//     orientation needs negating.
+//
+// Every refusal falls through untouched, leaving the tail-duplicated spelling — a miss, never a
+// miscompile. Applied ITERATIVELY, so `a || b || c` folds left-to-right, each round consuming one
+// more condition block.
+export function recognizeBranchShortCircuit(fn: Fn): boolean {
+  let changed = false;
+  const term = (b: Block) => b.ops[b.ops.length - 1];
+  let progress = true;
+  while (progress) {
+    progress = false;
+    const defs = defOpMap(fn);
+    const preds = predecessors(fn);
+    outer: for (const h of fn.blocks) {
+      const ht = term(h);
+      if (ht.opcode !== 'cond_br') {
+        continue;
+      }
+      const [taken, fall] = ht.successors;
+      // Try ^g = the fall edge, then ^g = the taken edge. `gIsFall` picks the connective.
+      for (const gIsFall of [true, false]) {
+        const gEdge = gIsFall ? fall : taken;
+        const sharedFromH = gIsFall ? taken : fall;
+        const g = gEdge.block;
+        if (g === h || g === sharedFromH.block || g.params.length > 0) {
+          continue;
+        }
+        // The ENTRY block is never ^g — see the REFUSALS note. `predecessors()` cannot see the
+        // implicit entry edge, so this is the only thing standing between an entry-block loop
+        // header and a silently reordered function body.
+        if (g === fn.blocks[0]) {
+          continue;
+        }
+        if ((preds.get(g) ?? []).length !== 1) {
+          continue;
+        }
+        const gt = term(g);
+        if (gt.opcode !== 'cond_br') {
+          continue;
+        }
+        const [gTaken, gFall] = gt.successors;
+        if (gTaken.block === gFall.block) {
+          continue;
+        }
+        // A comparison TREE over one scrutinee belongs to switch recovery, not to this fold.
+        if (sameScrutineeConstTests(defs, ht.operands[0], gt.operands[0])) {
+          continue;
+        }
+        // ^g's body must be pure, and every value it defines must be consumed only by ^g itself —
+        // see the REFUSALS note: an escaping or reused value becomes a statement hoisted out of the
+        // short circuit.
+        // HOIST_UNSAFE_OPS, not EFFECTFUL_OPS: a live `opaque` is an instruction asmlift could not
+        // model, and moving it out of the arm that guards it is the reordering this refuses. Loud
+        // either way today (a decline under `onGap: 'strict'`, an ASMLIFT_ERROR marker under
+        // `annotate`, the CLI and benchmark default), so this closes a model gap rather than fixing
+        // an observed bug.
+        const body = g.ops.slice(0, -1);
+        if (body.some((op) => HOIST_UNSAFE_OPS.has(op.opcode))) {
+          continue;
+        }
+        if (!definedValuesStayLocal(fn, g)) {
+          continue;
+        }
+        // Which of ^g's edges rejoins ^h's other successor? That is the shared block.
+        const sharedEdge =
+          gTaken.block === sharedFromH.block ? gTaken : gFall.block === sharedFromH.block ? gFall : null;
+        if (!sharedEdge) {
+          continue;
+        }
+        const otherEdge = sharedEdge === gTaken ? gFall : gTaken;
+        if (!sameArgs(sharedFromH.args, sharedEdge.args)) {
+          continue;
+        }
+        // The second operand, oriented at the block whose slot it decides: `logic_or` asks "does ^g
+        // reach the SHARED block", `logic_and` asks "does ^g reach the OTHER block".
+        const wantEdge = gIsFall ? sharedEdge : otherEdge;
+        const c2 = gt.operands[0];
+        const c2Def = defs.get(c2);
+        let second = c2;
+        const negated: Op[] = [];
+        if (wantEdge !== gTaken) {
+          if (!c2Def || !NEGATED_ICMP[c2Def.opcode]) {
+            continue;
+          }
+          second = mkValue(T.unk(32));
+          negated.push(mkOp(NEGATED_ICMP[c2Def.opcode], { operands: [...c2Def.operands], results: [second] }));
+        }
+        const res = mkValue(T.unk(32));
+        const connective = mkOp(gIsFall ? 'logic_or' : 'logic_and', {
+          operands: [ht.operands[0], second],
+          results: [res],
+        });
+        // ^g's body moves ahead of ^h's terminator; ^h keeps the successor SLOT that did not change
+        // (taken=shared for `||`, taken=other for `&&`), so the frontend's branch sense survives.
+        h.ops.splice(h.ops.length - 1, 1, ...body, ...negated, connective, {
+          ...mkOp('cond_br', { operands: [res] }),
+          successors: gIsFall
+            ? [
+                { block: sharedEdge.block, args: [...sharedEdge.args] },
+                { block: otherEdge.block, args: [...otherEdge.args] },
+              ]
+            : [
+                { block: otherEdge.block, args: [...otherEdge.args] },
+                { block: sharedEdge.block, args: [...sharedEdge.args] },
+              ],
+        });
+        fn.blocks = fn.blocks.filter((x) => x !== g);
+        changed = true;
+        progress = true;
+        break outer; // defs/preds are stale after the mutation — recompute on the next round
+      }
+    }
+  }
+  return changed;
+}
+
+/** Do `c1` and `c2` compare the SAME value against CONSTANTS? That is the signature of a
+ *  comparison-tree `switch`, which switch-recover.ts owns — see the REFUSALS note. Equality tests
+ *  only: a switch tree dispatches on `==`/`!=`, while a RELATIONAL pair (`x >= lo && x <= hi`, the
+ *  range check) is a genuine connective this fold should still take. */
+function sameScrutineeConstTests(defs: Map<Value, Op>, c1: Value, c2: Value): boolean {
+  const eqTest = (v: Value): { scrutinee: Value } | null => {
+    const d = defs.get(v);
+    if (!d || (d.opcode !== 'icmp_eq' && d.opcode !== 'icmp_ne')) {
+      return null;
+    }
+    const [x, y] = d.operands;
+    const xc = defs.get(x)?.opcode === 'const';
+    const yc = defs.get(y)?.opcode === 'const';
+    // exactly one side constant — `x == y` between two variables is no switch test
+    return xc === yc ? null : { scrutinee: xc ? y : x };
+  };
+  const a = eqTest(c1);
+  const b = eqTest(c2);
+  return a !== null && b !== null && a.scrutinee === b.scrutinee;
+}
+
+/** True when every value `g` defines is read at most once, and any read is inside `g`.
+ *
+ *  The VALUE form above needs no such check, and the asymmetry is real rather than drift: its feeder
+ *  ends in `br M`, so the feeder has no successor of its own to dominate and every value it defines
+ *  is either read in the feeder or carried to `M` as the phi argument the fold consumes. Here ^g
+ *  ends in `cond_br` and its `other` successor IS ^g-dominated, so a ^g-defined value genuinely can
+ *  escape, and only this check stops it.
+ *
+ *  An earlier version of this note justified the asymmetry by "the feeder dominates nothing but
+ *  itself because M has 2+ predecessors", and told the reader not to unify the guards. That was
+ *  WRONG — the entry block dominates every block whatever M's predecessor count — and it was wrong
+ *  about the one guard the two folds genuinely DO share, the `fn.blocks[0]` refusal, which the value
+ *  form was missing entirely. Both now have it. When changing either fold, check the other. */
+function definedValuesStayLocal(fn: Fn, g: Block): boolean {
+  const defined = new Set<Value>(g.ops.flatMap((op) => op.results));
+  if (defined.size === 0) {
+    return true;
+  }
+  const uses = new Map<Value, number>();
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      for (const v of [...op.operands, ...op.successors.flatMap((s) => s.args)]) {
+        if (!defined.has(v)) {
+          continue;
+        }
+        if (b !== g) {
+          return false; // escapes ^g — the structurer would render it before the `if`
+        }
+        uses.set(v, (uses.get(v) ?? 0) + 1);
+      }
+    }
+  }
+  // ZERO uses is fine — a dead op renders nothing at all, so it cannot escape the short circuit.
+  // TWO or more is not: analysis.ts materializes a multi-consumer value into a local, which is a
+  // statement, and a statement lands before the `if`.
+  return [...defined].every((v) => (uses.get(v) ?? 0) <= 1);
+}
+
+/** Two successor argument lists that a fold may collapse into one: same values, same order. */
+function sameArgs(a: Value[], b: Value[]): boolean {
+  return a.length === b.length && a.every((v, i) => v === b[i]);
+}

package/src/raise/structs.ts

@@ -196,8 +196,18 @@ export function recognizeStructs(fn: Fn): number {
   return count;
 }
 
-/** The distinct struct types this function references (unwrapping struct pointers on every value),
- *  deduped by name and sorted, for the backend to declare above the function. */
+/** The distinct struct types this function's L2 GRAPH mentions (unwrapping struct pointers on every
+ *  value), deduped by name and sorted, for the backend to declare above the function.
+ *
+ *  "Mentions", not "references": this walks `fn.blocks` at the moment structuring runs, and the
+ *  result is CACHED on the SFn (`structure.ts`) and carried by every later `{...sfn}` pass, so a
+ *  struct whose last use a subsequent L3 pass removed would still be declared. Sibling `locals` is
+ *  reference-pruned after dead-store elimination (`l3/dce.ts`) for exactly that reason; this list is
+ *  not. No pass drops such a use today — the IR-level DCE runs long before recognition, and l3/dce's
+ *  `mustKeep` never drops a `field`/`index` — so the staleness is LATENT, not live, which is why it
+ *  is recorded here rather than fixed speculatively. The fix, if a pass ever makes it reachable, is
+ *  the one l3/symbol-refs.ts already applies to symbol references: derive at the consumption point
+ *  (`backend/cfamily.ts` structDecls) instead of caching. */
 export function collectStructs(fn: Fn): StructType[] {
   const seen = new Map<string, StructType>();
   const consider = (t: IrType) => {

package/src/rank.ts

@@ -15,9 +15,12 @@ import { frontendFor } from './frontend/registry';
 import { Fn, type Value, defOpMap } from './ir/core';
 import { T } from './ir/types';
 import { verify } from './ir/verify';
+import { materializeArgBases } from './l3/argbase';
 import type { LanguageBackend, SFn } from './l3/ast';
+import { coalesceCandidates } from './l3/coalesce';
 import { registerishSpellings } from './l3/regspell';
 import { reindexWalks } from './l3/reindex';
+import { hoistScopedBases } from './l3/scopebase';
 import { type SymbolRef, collectSymbolRefs } from './l3/symbol-refs';
 import { RewritePattern } from './pattern/engine';
 import { applyIdiomPatterns, raiseRecovered, structureChecked } from './pipeline';
@@ -117,12 +120,30 @@ export interface EnumerateOptions {
   asmData?: AsmData;
   /** address→symbol map (symbols.ts) — same contract as DecompileOptions.symbols */
   symbols?: SymbolMap;
+  /** Called when a re-spelling lever THROWS or fails a boundary contract, so the failure is visible
+   *  instead of the candidate silently not existing. Enumeration continues either way — the primary
+   *  spelling is unaffected — but a lever that never fires because it always throws is a defect, and
+   *  without this it looks identical to a lever that correctly declined. */
+  onLeverError?: (label: string, error: string) => void;
 }
 
-/** One distinct candidate spelling (a signedness × branch-sense lever combination), emitted to source. */
+/** One distinct candidate spelling — a point in the axis cross (signedness × branch sense ×
+ *  def-site anchoring × bitfield spelling × symbol-map variant, plus the L3 re-spellings) —
+ *  emitted to source. */
 export interface Candidate {
   label: string;
   source: string;
+  /** Which PREFERENCE GROUP this spelling belongs to — the symbol-variant index (0 = the map's own
+   *  named spellings, 1 = their `/raw-globals` siblings). Enumeration emits the groups in
+   *  preference order, and a lower group WINS a score tie: when both compile to the same bytes the
+   *  reader should get `gCounter.field`, not a byte offset off a hoisted `(u8 *)` base.
+   *
+   *  Carried structurally rather than left to enumeration order because the readability tie-break
+   *  (compareScored) must compare only spellings that are genuinely alternatives of the same
+   *  thing. Ranking a named spelling against a raw-address one on cast count is not a readability
+   *  comparison at all — the raw form's `(u8 *)` base is not counted, so it would win by
+   *  construction, trading named struct fields for anonymous byte offsets. */
+  group: number;
   /** the map-derived VALUE references this candidate's tree contains — what the scoring
    *  layer's declaration synthesis renders. DERIVED, never carried: computed once from the
    *  exact tree this candidate's source was emitted from, at the moment the candidate is
@@ -179,10 +200,32 @@ export function enumerateCandidates(
   // and let the differ referee. The default sense is always among them, so this never scores
   // worse; it only wins where the flip matches.
   const defSense = baseOpts.preserveDivergentBranchSense ?? true;
-  const senseCands = [
-    { suffix: '', sense: defSense },
-    { suffix: '/flip-branch', sense: !defSense },
+  // `/defsite` — def-site-anchored constant merge copies (structure.ts anchorConstCopies) — is a
+  // structuring axis on the same footing as branch sense: where the asm materialized a merge
+  // constant is placement evidence, but whether the SOURCE spelled it there is genuinely
+  // ambiguous, so both placements are emitted and the differ referees. Crossed with branch sense
+  // (an anchored copy empties an arm, which is exactly what changes which sense wins); the dedup
+  // below collapses every variant the anchoring left unchanged.
+  const baseSense = [
+    { suffix: '', sense: defSense, anchor: false, bitfields: true },
+    { suffix: '/flip-branch', sense: !defSense, anchor: false, bitfields: true },
+    { suffix: '/defsite', sense: defSense, anchor: true, bitfields: true },
+    { suffix: '/flip-branch/defsite', sense: !defSense, anchor: true, bitfields: true },
   ];
+  // `/no-bitfield` — keep the honest shift spelling where the map would name a bitfield member.
+  // The named read recompiles at the DECLARATION's access width; where that diverges from the
+  // asm's load width, the shifts are the spelling that matches — so both are emitted and the
+  // differ referees. Enumerated only when the map carries any bitfield member at all (checked
+  // below), so the 2× cross is paid exactly by the functions it can help; the dedup collapses
+  // every variant where no fold fired.
+  const mapHasBitfields =
+    opts.symbols !== undefined &&
+    [...opts.symbols.values()].some((infos) =>
+      infos.some((i) => [...(i.layout ?? []), ...(i.pointee?.layout ?? [])].some((f) => f.bitWidth !== undefined)),
+    );
+  const senseCands = mapHasBitfields
+    ? [...baseSense, ...baseSense.map((s) => ({ ...s, suffix: `${s.suffix}/no-bitfield`, bitfields: false }))]
+    : baseSense;
   // Probe: recover ONCE with no signedness pin, to learn which entry params are pointers/aggregates
   // so they are excluded from the signedness axis (see NO_PIN_KINDS). One extra lift+recover, no
   // compile. (The probe deliberately stops after recoverTypes — it only reads the param KINDS, so
@@ -211,7 +254,7 @@ export function enumerateCandidates(
         { suffix: '/raw-globals', symbols: undefined },
       ]
     : [{ suffix: '' }];
-  for (const sv of symbolVariants) {
+  for (const [svIndex, sv] of symbolVariants.entries()) {
     const svOpts = sv.symbols ? baseOpts : { ...baseOpts, symbols: undefined };
     for (const cand of SIGN_CANDS) {
       const fn = frontend.lift(name, asm, target, prototypes, opts.asmData, sv.symbols);
@@ -223,7 +266,23 @@ export function enumerateCandidates(
       for (const s of senseCands) {
         // structure() reads `fn` and produces a fresh SFn (it does not mutate `fn`), so both branch
         // senses structure the same recovered function without re-lifting.
-        const sfn = structureChecked(fn, { ...svOpts, preserveDivergentBranchSense: s.sense });
+        let sfn: SFn;
+        try {
+          sfn = structureChecked(fn, {
+            ...svOpts,
+            preserveDivergentBranchSense: s.sense,
+            anchorConstCopies: s.anchor,
+            spellBitfieldMembers: s.bitfields,
+          });
+        } catch (e) {
+          if (!s.anchor && s.bitfields) {
+            throw e; // the base axes keep their behavior: a structuring failure aborts the row
+          }
+          // an anchored variant that fails structuring or its contracts is a dropped lever, never
+          // an aborted enumeration — same rule as respell below
+          opts.onLeverError?.(name + s.suffix, e instanceof Error ? e.message.split('\n')[0] : String(e));
+          continue;
+        }
         // The walk→index re-spelling (l3/reindex.ts) is a THIRD lever on the same footing as
         // signedness and branch sense: whether the source spelled `*p; p++` or `arr[i]` is
         // genuinely ambiguous from asm (compilers strength-reduce the latter into the former), so
@@ -266,24 +325,72 @@ export function enumerateCandidates(
         // to the user — a semantically-wrong re-spelling there is plausible-but-wrong output, the
         // defect class this project exists to avoid. Hence each lever's decline-over-approximate
         // gates, adversarially audited.
-        const respell = (suffix: string, alt: SFn): void => {
+        // Takes a THUNK, so the lever's own computation is inside the try too. A lever that threw
+        // from the pass itself — rather than from the contracts or the backend — would escape and
+        // abort the whole enumeration for this row, primary included: the one way a lever can cost
+        // a match. Making that structural rather than per-call-site means no lever can opt out.
+        const respell = (suffix: string, make: () => SFn | null | undefined): void => {
           try {
+            const alt = make();
+            if (!alt) {
+              return; // the lever declined to fire — no candidate, not a duplicate of the primary
+            }
             assertResolved(alt);
             assertDerefsTyped(alt);
             spellings.push({ suffix, source: backend.emit(alt), ...refsOf(alt) });
-          } catch {
-            // contract-failing or unspellable re-spelling: drop it, keep the primary
+          } catch (e) {
+            // A throwing lever, a contract failure, or an unspellable re-spelling: keep the primary.
+            // REPORTED, not swallowed. `dropped` (below) records only spellings the SCORER refused,
+            // so without this a lever that fails here vanishes with no trace — indistinguishable
+            // from one that correctly declined, which is exactly the hidden failure
+            // DroppedCandidate exists to surface.
+            opts.onLeverError?.(name + suffix, e instanceof Error ? e.message.split('\n')[0] : String(e));
           }
         };
-        const indexed = reindexWalks(sfn);
-        if (indexed) {
-          respell('/indexed', indexed);
-        }
+        // `/argbase` — name a call's argument bases before the call (l3/argbase.ts). A lever on the
+        // same footing as the others: the primary inline spelling stays in the list, so the differ
+        // referees and this can never cost a match.
+        respell('/argbase', () => materializeArgBases(sfn));
+        // `/scopebase` — name a reused global base at the INNERMOST scope holding its uses
+        // (l3/scopebase.ts). Distinct from basecse's function-top hoist, which the primary already
+        // carries: this one fires exactly where that placement would extend a live range the
+        // original never had.
+        // `/scopebase`, and its COALESCED variants. Which locals a register allocator shared is not
+        // derivable from the tree — on the row this was built for the two legal merges score 18 and
+        // 40 against a no-merge 21, so committing to one by declaration order costs 19 points and
+        // discards the winner. Every variant is emitted and the differ referees, exactly as
+        // `/regcopy` does for its allocator-ambiguous tail choice.
+        //
+        // POLICY NOTE: rank.ts's rule is that re-spellings derive from the BASE spelling only —
+        // levers do not compose. These are not a second lever composed onto the first: coalescing is
+        // enumerated as alternative OUTPUTS of the base hoist, in the one place that knows the hoist
+        // just happened. The un-coalesced `/scopebase` stays in the list, so nothing is lost.
+        //
+        // EVERY pass invocation stays INSIDE a thunk — see the paragraph above on why a pass that
+        // runs outside `respell`'s try is the one way a lever can cost a match. `enumerate` re-runs
+        // the hoist per candidate, which is pure and cheap, rather than caching it outside the guard.
+        respell('/scopebase', () => hoistScopedBases(sfn));
+        const enumerate = (label: string, from: () => SFn | null | undefined): void => {
+          let variants: { merged: string; sfn: SFn }[] = [];
+          try {
+            const base = from();
+            variants = base ? coalesceCandidates(base) : [];
+          } catch (e) {
+            opts.onLeverError?.(name + label, e instanceof Error ? e.message.split('\n')[0] : String(e));
+            return;
+          }
+          for (const c of variants) {
+            respell(`${label}-${c.merged}`, () => c.sfn);
+          }
+        };
+        enumerate('/scopebase-coalesce', () => hoistScopedBases(sfn));
+        enumerate('/coalesce', () => sfn);
+        respell('/indexed', () => reindexWalks(sfn));
         // the register-copy spelling (l3/regspell.ts): 0–3 variants (base; tail assign-back reusing
         // the dead value var; tail assign-back into a fresh var — the tail choice is allocator-
         // ambiguous, so both are ranked)
         const REGCOPY_LABELS = ['/regcopy', '/regcopy-ret', '/regcopy-ret-fresh'];
-        registerishSpellings(sfn).forEach((alt, i) => respell(REGCOPY_LABELS[i] ?? `/regcopy-${i}`, alt));
+        registerishSpellings(sfn).forEach((alt, i) => respell(REGCOPY_LABELS[i] ?? `/regcopy-${i}`, () => alt));
         for (const sp of spellings) {
           const source = sp.source;
           // Collapse a spelling that produced identical source (a function with no divergent `if`
@@ -298,6 +405,7 @@ export function enumerateCandidates(
           out.push({
             label: `${cand.label}${s.suffix}${sp.suffix}${sv.suffix}`,
             source,
+            group: svIndex,
             ...(sp.symbolRefs ? { symbolRefs: sp.symbolRefs } : {}),
           });
         }
@@ -332,15 +440,59 @@ export function rankBy<S extends { score: number }>(
   if (results.length === 0) {
     throw new Error(`no scorable candidate for '${symbol}': ${firstLine(lastScoreErr)}`, { cause: lastScoreErr });
   }
-  // Score first; ENUMERATION ORDER breaks a tie. That order is meaningful, not incidental:
-  // enumerateCandidates emits the symbol-map spellings before their `/raw-globals` siblings, so
-  // when both compile to the same bytes the named one wins and the reader gets `gCounter` rather
-  // than a bare address. Spelled as an explicit comparator because relying on Array#sort's
-  // stability would make the preference an accident of two unrelated decisions.
-  results.sort((a, b) => a.score.score - b.score.score || a.order - b.order);
+  results.sort(compareScored);
   return { best: results[0], candidates: results.map(({ order: _order, ...c }) => c), dropped };
 }
 
+/** THE candidate ordering — score, then preference group, then readability, then enumeration
+ *  order. Exported because there are TWO drivers over the same enumeration (this module's sync
+ *  `rankBy` for the Node/objdiff scorer, and the webapp's async await-loop for the wasm one), and
+ *  a per-driver copy would let the same input produce two different winners.
+ *
+ *  SCORE dominates absolutely: the differ is the fitness function, and a tie means the axis that
+ *  separates these two spellings did not change the bytes — so everything below only chooses what
+ *  the READER sees, and can never cost a match.
+ *
+ *  GROUP next: a named symbol-map spelling beats its `/raw-globals` sibling at equal bytes.
+ *
+ *  CAST COUNT next, and only WITHIN a group. A wrong signedness pin is what manufactures casts —
+ *  the C backend has to cast a shift operand back to the signedness the machine op needs, so
+ *  pinning `u32` on a genuinely-signed parameter buys `s32 f(u32 a0) { return (s32)a0 >> a1; }`
+ *  for the same bytes as `s32 f(s32 a0) { return a0 >> a1; }`. Before the backend synthesized that
+ *  cast the wrong pin simply lost on score; now it ties, and enumeration order alone would
+ *  silently install the noisier spelling.
+ *
+ *  ENUMERATION ORDER last, which makes this a strict total order (indices are unique) and the
+ *  result deterministic. Spelled explicitly rather than leaning on Array#sort's stability, which
+ *  would make each preference an accident of two unrelated decisions. */
+export function compareScored<S extends { score: number }>(
+  a: Candidate & { score: S; order: number },
+  b: Candidate & { score: S; order: number },
+): number {
+  return (
+    a.score.score - b.score.score || a.group - b.group || castCount(a.source) - castCount(b.source) || a.order - b.order
+  );
+}
+
+/** Scalar casts in a candidate's rendered source — the readability tie-break above.
+ *
+ *  A TEXT count over the emitted string, matching how the benchmark's own readability metric
+ *  measures the same thing (apps/benchmark/src/eval/quality.ts) — the two must agree about what
+ *  "cast noise" means, or ranking optimizes for something the report then scores differently.
+ *
+ *  It counts the decomp typedef vocabulary only, so a pointer or struct cast is not read as noise
+ *  — those are structural spellings a candidate does not choose. And it carries `quality.ts`'s
+ *  ADDRESS-CAST exemption: `(u32)&gSym` / `(s32)&gSym` is the CORRECT source spelling of integer
+ *  arithmetic on a link-time address, which decomp projects write themselves. Counting it would
+ *  penalize precisely the named spelling this ranking is supposed to prefer.
+ *
+ *  Deterministic, and total on any string. */
+function castCount(source: string): number {
+  const all = source.match(/\((?:u|s)(?:8|16|32)\)/g)?.length ?? 0;
+  const addr = source.match(/\((?:u|s)32\)\s*&/g)?.length ?? 0;
+  return all - addr;
+}
+
 /** First line of whatever the scorer threw — the compiler's own diagnostic, not a stack. */
 function firstLine(e: unknown): string {
   return e instanceof Error ? e.message.split('\n')[0] : String(e ?? 'no candidate produced');