@asmlift/core 0.6.0 → 0.8.0

package/src/raise/retsink.ts

@@ -1,6 +1,6 @@
 // asmlift — return-sinking (F-CFG-class structural pass; successor-aware, ISA-neutral).
 //
-// A short-circuit `if (a && b) return X; return Y;` (and the `||` / value-returning variants) compiles to
+// A short-circuit `if (a && b) return X; return Y;` (and the `||` / value-returning forms) compiles to
 // a diamond whose arms converge on a single RETURN block: `br ^merge(X)` / `br ^merge(Y)` into
 // `^merge(v): ret v`. The structurer lowers that merge as a shared VARIABLE — `v0 = X … v0 = Y … return v0`
 // — which is byte-exact-CORRECT but recompiles DIFFERENTLY from the source: agbcc/gcc, given the natural
@@ -11,13 +11,188 @@
 // merge. The structurer then emits early returns in each arm (it already duplicates a shared arm block),
 // which recompiles to the compiler's shared-return form. Purely structural: no new IR/AST vocabulary.
 //
-// GATE — only the SHORT-CIRCUIT shape, never a simple value-select. A single-condition select
-// (`c ? x : y`, and the branchless-compare idioms `clamp0`/`le0`/…) also converges two arms on a return
-// merge, but there the compiler emits the MERGE-VARIABLE form, which is what byte-matches — sinking it
-// would REGRESS those. The distinguishing signal is structural: a short-circuit chain converges on a
-// SHARED arm — the common early-exit reached from ≥2 CONDITIONS — whereas a simple diamond's arms are
-// each reached from one. So sink only when some branch-predecessor of the merge is ARRIVED at from
-// two places; every simple select stays a merge var.
+// GATE — the SHORT-CIRCUIT shape, plus the one single-condition shape a merge variable cannot spell.
+// A single-condition select (`c ? x : y`, and the branchless-compare idioms `clamp0`/`le0`/…) also
+// converges two arms on a return merge, and for most of them the compiler emits the MERGE-VARIABLE
+// form, which is what byte-matches — sinking those would REGRESS them. The distinguishing signal is
+// structural: a short-circuit chain converges on a SHARED arm — the common early-exit reached from
+// ≥2 CONDITIONS — whereas a simple diamond's arms are each reached from one. So sink when some
+// branch-predecessor of the merge is ARRIVED at from two places.
+//
+// A ONE-SET-ARM DIAMOND IS THE EXCEPTION (`SELECT_GATES`), and it is a compiler fact rather than a
+// preference — THE SAME compiler fact `raise/narrowlocal.ts` already owns, read in the same
+// backwards direction. gcc 2.x's `jump_optimize` (`gcc/jump.c:443-445`, guard at `:471-502`)
+// collapses `if (c) v = a; else v = b;` into `v = b; if (c) v = a;` when both arms are ONE
+// speculatable SET, so agbcc never emits that diamond back: one arm is HOISTED above the compare
+// and the other becomes a conditional skip — `movs r0,#5; cmp r1,#0; bne .L; movs r0,#3; .L: bx lr`,
+// four blocks collapsed to two, with no unconditional branch to the merge at all. For the {0,1} pair
+// it goes further and folds branchlessly (`negs r0,r0; lsrs r0,r0,#31`), erasing the comparison too.
+// So where the TARGET holds that diamond, a merge variable is the spelling of some other function,
+// and sinking is the only candidate that can match (measured on `kleod:IsSelectButtonPressed:agbcc`,
+// retired 2026-09-13).
+//
+// ONE MODEL, NOT TWO. The predicate is `narrowlocal.ts`'s exported `armIsOneSet` — no op that
+// `REEVAL_UNSAFE_OPS` calls unsafe, and EXACTLY one result-producing op — read here by
+// `arms-are-one-set`. It is cited there line by line to `jump.c:474/:480/:482/:483` and
+// `rtlanal.c:1770-1784`, with the three things an op count alone gets wrong, and a reach census over
+// 13733 blocks. It is SHARED rather than re-derived here because it is one optimizer guard and a
+// second model of it would drift; where the shared predicate costs this pass something narrowlocal
+// does not pay is named below.
+//
+// THE EVIDENCE IS COMPILED AND COMMITTED, not described — seven functions written each way, agbcc
+// -O2 -mthumb (`test/corpus/agbcc-select-{merge,early}.s`, regenerated by
+// `scripts/regen-select-spelling-probes.ts`, asserted by `select-spelling.test.ts`). Read as a
+// truth-table for `armIsOneSet` in THIS direction:
+//
+//   selbtn   v = 1 / v = 0            one SET   merge LOSES the diamond, early keeps it   ADMIT
+//   selk53   v = 5 / v = 3            one SET   merge LOSES the diamond, early keeps it   ADMIT
+//   selpool  two 32-bit pool consts   one SET   merge LOSES the diamond, early keeps it   ADMIT
+//   selcomp  v = a + b / v = a - b    one SET   merge LOSES the diamond, early keeps it   ADMIT
+//   selbody  *p = 1; v = 5 / …        bodied    BOTH keep it, opposite ARM ORDER          refuse
+//   selcomp3 v = a + b + 7 / …        3 ops     BOTH keep it, opposite ARM ORDER          refuse
+//   selload  v = *p / v = *q          a READ    BOTH keep it, opposite ARM ORDER          refuse
+//
+// The refusals are the load-bearing half. Where the arms are not one SET the hoist does not
+// happen, so BOTH spellings emit a diamond and they differ only
+// in ARM ORDER — sinking there is not wrong, it is the wrong SENSE, and the unranked primary
+// (`packages/cli/test/matching`, the CLI one-shot, apps/web's preset) has no `/flip-branch` to
+// recover it. Five shapes were measured losing a byte-exact match to the missing clause — a bodied
+// arm, one bodied arm, a bodied `x == 3` head, bodied pool constants, and a two-way `switch` with a
+// `default` — and they are pinned in `packages/cli/test/matching/fixtures.ts` (`selbody`, `sw2`).
+//
+// WHERE THE SHARED PREDICATE IS CONSERVATIVE, and why that is accepted. `armIsOneSet` COUNTS
+// constants, because the lifted IR does not say which immediate a target can fold. `selk3`
+// (`v = a + 3` / `v = a - 3`) is two ops in the IR and one `adds` on this target, so `jump.c`'s own
+// guard counts one SET where this predicate counts two and the arm is hoisted while the clause
+// refuses it — an over-refusal that costs a CANDIDATE here, where narrowlocal's same over-refusal
+// costs nothing (its fallback is the spelling it emits anyway). That divergence is ARGUED from the
+// optimizer, not compiled: `selk3` is deliberately absent from the committed pair below, which is
+// the truth-table for the predicate rather than for the compiler. Accepted rather than forked: no
+// corpus row inhabits the difference, and a cost model neither pass has is a worse thing to own than
+// a shared conservative predicate. Two more shapes it refuses on the same counting grounds, both
+// unreached on the corpus: an arm left EMPTY by an earlier asmlift pass hoisting its constant into
+// the head (`:480` runs `single_set` on the arm's own insn, and an arm whose only insn is its jump
+// has none), and an arm carrying TWO constants into a multi-operand `ret`.
+//
+// THAT IS A FACT ABOUT ONE COMPILER, so it has a per-compiler home rather than an `arch ==` branch,
+// and it is the field narrowlocal already threads: `compilerBehaviors.hoistsSingleSetArm`
+// (target.ts), threaded in as `RetSinkOptions` from `decompile`'s own target, read by the
+// `compiler-hoists-single-set-arm` clause. ONE field, because it is one guard: a second boolean for
+// it would let a round that measures mwcc's `jump_optimize` set one reader's and leave the other's
+// false. Set on agbcc
+// and nowhere else — this pass is ISA-neutral and runs for IDO, gcc2.7.2kmc and mwcc too, and
+// nothing has compiled the pair on any of them. The short-circuit admissions above take no such
+// clause: their argument is about a SHARED ARM in the CFG, not about a compiler's hoist.
+//
+// THE COMPILER CLAUSE IS LAST IN THE TABLE, not first. A census of a gate table counts the clause
+// that FIRST refuses each site, and `target.ts` states that this admission reaches no non-agbcc row.
+// Placed first, this COMPILER fact collects 28 of the 74 sites — 26 of them shapes that are not
+// diamonds at all — and a census then reads the opposite of that sentence. Last, it decides 0 sites
+// on the entire corpus, which is what the sentence claims. Costs nothing either way (measured: 0 of
+// 1039 rows move on the reorder).
+//
+// WHAT EACH CLAUSE ACTUALLY DECIDES, measured by ablating it and re-lifting all 1039 corpus rows
+// offline (`targetAsm` out of the artifact, source-hash diff), ON THE TABLE AS IT STANDS — a number
+// here is only true of the clause ORDER it was measured under, so `retsink.test.ts` pins that order
+// and the next reorder fails a test:
+//
+//     two-arms-one-head   61 sites / 0 rows      arms-are-one-set     8 sites / 6 rows
+//     pre-diamond          2 sites / 0 rows      a-value-is-returned  2 sites / 0 rows
+//     compiler-hoists-single-set-arm  0 sites / 0 rows       ADMIT  1 site
+//     no-arrival-but-the-arms          0 sites / 0 rows
+//
+// The table is reached at 74 sites over the 1039 rows and admits ONE, and the SIX rows
+// `arms-are-one-set` decides alone are `pokeemerald:GiveBerryPowder:agbcc`,
+// `pokeemerald:MathUtil_Div16:agbcc`, `pokeemerald:MathUtil_Div16Shift:agbcc`,
+// `sa3:sub_8001FD4:agbcc`, `synthetic:armkeep:agbcc`, `synthetic:bgfixed:agbcc` — five of them MATCH
+// today. Three clauses decide 0 rows, and they are not the same kind of zero:
+//
+//   • `compiler-hoists-single-set-arm` decides 0 SITES as well, which is the point of putting it
+//     last, and is what `target.ts` claims for it. Moved back to first it collects 28 sites and
+//     still moves 0 rows.
+//   • `no-arrival-but-the-arms` and `pre-diamond` decide the SAME two sites
+//     (`pokeemerald:GetGenderFromSpeciesAndPersonality:agbcc`,
+//     `pokeemerald:TrySetCantSelectMoveBattleScript:agbcc`) and the order between them decides which
+//     one the census bills. Both are merges with a third in-edge: `mergeArms` counts ALL
+//     predecessors where `two-arms-one-head` counts only the `br` ones, so the pre-recovery map
+//     already called them no diamond. NO MANUFACTURED DIAMOND REACHES THIS TABLE TODAY — the reason
+//     is still `fusedDiamond` being tested first in the same disjunction, and `pre-diamond` is the
+//     clause that stops that being an accident. Argued, not corpus-paid, and marked as such.
+//   • `a-value-is-returned` first-refuses two agbcc sites (below) and is subsumed by
+//     `arms-are-one-set` a step later.
+//
+// THE THREADING IS NOT FRAGILE, which was the open question when `pre-diamond` was proposed: of the
+// 74 sites, ZERO find their merge block ABSENT from the pre-recovery map. Block identity survives
+// all twelve pre-recovery passes, their eight `dce` runs and `recoverTypes`, so every refusal here
+// is a real `diamond: false` and never a lost key.
+//
+// The named single-condition controls — `maxi`/`mini`/`absdiff`/`clamp0`/`bittest` — are NOT
+// protected by any of these clauses: agbcc
+// emits those as a branch-over-one-instruction (or branchlessly), so their targets hold no two-armed
+// diamond and `two-arms-one-head` has already refused them. A control that stays MATCH because it
+// never reaches the table is not evidence the table is right — the shapes that DO reach it are the
+// bodied ones above, and they are what `packages/cli/test/matching` pins.
+//
+// REACH: ONE corpus row. Re-lifting all 1039 rows against `origin/main` changes the emitted source
+// of `kleod:IsSelectButtonPressed:agbcc` and of nothing else. That is one inhabitant because the
+// corpus has one, not because the rule is shaped to it: the three synthetic rows minted for this
+// admission (`selconst`, `selhead` — a body in the HEAD, arms still one SET each — and `selloop`, a
+// loop ahead of the diamond; see `apps/benchmark/dataset/synthetic.ts`) are MATCH on agbcc as well,
+// the last of them composing with another variation. FAILURE DIRECTION: a wrong admission costs
+// a SPELLING and never an answer — the transform is a tail duplication, every arm keeps the value it
+// carried — which is why every clause here is `sound: false`.
+//
+// SINKING IS NECESSARY, NOT SUFFICIENT: `/flip-branch` was necessary on every inhabitant measured —
+// the 4 shapes the admission was built on (`if (x & 0x40) return 1; return 0;` and its inverse,
+// `if (x > 3) return 5; return 3;`, `if (x == 0) return 1; return 0;`), and the three synthetic rows
+// above (the loop one's winner's variations are `signed/flip-branch/indexed`). Unranked, all four of the first
+// score 3 and none matches; the target row's own winner's variations moved `unsigned` → `unsigned/flip-branch`. The mechanism is structural rather than a
+// property of the sample: a sunk diamond has NO JOIN left, so the shipped joined-if default (the
+// layout reading) does not cover it, and on every diamond measured here agbcc puts the source's
+// taken arm in the FAR block, which makes the layout reading systematically inverted. "Both arms are
+// one SET" is a per-SITE fact this pass holds at the moment it fires, so emitting the target's
+// sense HERE would move the unranked path too — the CLI one-shot, apps/web's preset, and
+// `packages/cli/test/matching`, none of which the ranked fan rescues. That is a separate round with
+// its own regression surface (`regression.test.ts`'s fixtures, the byte-pinned playground preset)
+// and is booked rather than bundled.
+//
+// WHY A GATE AND NOT A VARIATION, since `l3/unmerge.ts` is this tree's other "duplicate a join back
+// into the arms" pass and IS one. `unmerge.ts` is a variation on the stated grounds that the mapping
+// from its tree back to a source is not a function and not uniformly many-to-one — which way it
+// goes is a property of the SHAPE, and no gate there can read that off the tree. This admission
+// asserts the opposite for its own shape, and the assertion is what `arms-are-one-set` IS: on the
+// question that clause reads, the mapping is a function, the differ never has to referee it, and the fan
+// does not grow (4 candidates before, 4 after). A variation where a default belongs doubles every
+// enumeration to referee a question with one answer.
+//
+// WHAT MOVES THE THING THIS DEFAULT PLACES. `docs/level-tower.md`: a compiler behavior read
+// backwards "owes an explicit refusal for every pass that moves the thing it is placing".
+// The thing placed is a TWO-ARMED DIAMOND, and asmlift manufactures one. `raise/shortcircuit.ts`'s
+// `branch-shortcircuit` builds diamonds out of condition trees the ROM never merged — measured in
+// `narrowlocal.ts`'s `mergeShapes` header, where 20 sa3 blocks gain `diamond` between lift and
+// pre-recovery's end and that pass accounts for all 10 that gain `hoistable`. `sinkReturns` runs
+// LATER STILL (`pipeline.ts`: after all twelve pre-recovery passes, eight of them followed by `dce`,
+// and after `recoverTypes`), so it sees every one of them.
+//
+// THE REFUSAL IS `pre-diamond`, and it is the same answer narrowlocal reached: the shape is read
+// from `PreRecoveryFacts.mergeShapes`, computed ONCE on the CFG as it ENTERS pre-recovery and
+// threaded down. A merge block absent from that map — created by a later pass — reads as no diamond
+// and is refused. A manufactured diamond therefore cannot be mistaken for one the ROM held, which is
+// the whole content of the backwards read.
+//
+// IT IS AN ARGUED GUARD AND NOT A CORPUS-PAID ONE, and the honest version of the claim is this: no
+// manufactured diamond reaches this table today, because `fusedDiamond` is tested before
+// `constantSelect()` in the same disjunction, so a `logic_and`-fused manufacture takes the
+// short-circuit path instead. That is a coincidence of evaluation order on a corpus with exactly ONE
+// admit site — nothing here could have caught it changing — and `pre-diamond` is what makes the
+// refusal stated rather than accidental. A pre-recovery fusion CAN destroy the CFG signal these
+// clauses read without any hosted gate noticing, so the divergence is worth pinning even unreached:
+// the fixture (`retsink.test.ts`) builds it by hand — a live diamond the pre-recovery map does not
+// have — because the corpus supplies none.
+// What the clause does NOT claim to cover is the second half of the tower's sentence — an IR
+// boundary the FRONTEND invents. `mergeShapes`' own header names that residue (the frontend cuts
+// blocks at labels, `applyIdiomPatterns` folds shift pairs, both before pre-recovery runs, and both
+// only ever make an arm SHORTER), and it is inherited here unchanged rather than re-argued.
 //
 // THE QUANTITY IS ARRIVALS, NOT PREDECESSORS. A FALL-THROUGH switch arm is the difference:
 // `case 2: r++; case 1: r++;` gives case 1's body two predecessors — the dispatch's `beq`, and
@@ -64,10 +239,11 @@
 //
 // This does NOT recover the boolean-VALUE form `return a && b` — that is shortcircuit.ts's job
 // (the `logic_and`/`logic_or` connective plus agbcc's `(-b|b)>>31` = `b!=0` normalisation).
-import { Block, Fn, Op, Value, defOpMap, isBodyless, mkOp, predecessors, terminator } from '../ir/core';
+import { Block, Fn, Op, Value, defOpMap, fallThroughOf, isBodyless, mkOp, predecessors, terminator } from '../ir/core';
 import { NEGATED_ICMP } from '../ir/opcodes';
 import { simplifyTrivialPhis } from '../ir/simplify';
 import { type Gate, firstRejection } from '../l3/gates';
+import { type MergeShape, armIsOneSet } from './narrowlocal';
 
 /** The fused short-circuit connectives (raise/shortcircuit.ts). A `cond_br` on one of these is the
  *  post-fusion record of the ≥2 conditions that used to reach a shared arm. */
@@ -114,11 +290,130 @@ export const FALL_IN_GATES: readonly Gate<FallInCandidate>[] = [
     id: 'one-dispatch-owning-the-merge',
     why: 'both arms of ONE dispatch on one scrutinee, and that dispatch owns the return merge',
     sound: false,
-    guardedBy: 'ablating the dispatch gate reads an `if` join, and a guarded switch, as fall-ins',
+    guardedBy: 'retsink.test.ts: ablating the dispatch gate reads an `if` join, and a guarded switch, as fall-ins',
     rejects: (c) => c.dispatches.length === 0,
   },
 ];
 
+/** A return merge offered to the ONE-SET-ARM admission of the header. Like `FallInCandidate` the
+ *  table is a value, so each clause can be dropped and the pass re-run on real input. */
+export interface SelectCandidate {
+  /** the unconditional-branch predecessors of the merge */
+  readonly brPreds: readonly Block[];
+  /** every predecessor of the merge, `brPreds` included */
+  readonly preds: readonly Block[];
+  /** the block both arms are reached from, when exactly one block reaches both by a `cond_br`
+   *  whose two successors ARE the arms — null when the shape is anything else */
+  readonly head: Block | null;
+  /** whether the merge was ALREADY a two-armed diamond on the CFG as it entered pre-recovery
+   *  (`PreRecoveryFacts.mergeShapes`) — false for a block a later pass created or reshaped, and
+   *  false whenever the caller threaded no map */
+  readonly preDiamond: boolean;
+  /** the ops defining the values the arms carry in, one per arm per returned operand; `undefined`
+   *  where the value has no defining op (a block parameter, or a live-in) */
+  readonly carried: readonly (Op | undefined)[];
+  /** whether EVERY arm is one speculatable SET — `raise/narrowlocal.ts`'s exported `armIsOneSet`,
+   *  this tree's one model of `gcc/jump.c:471-502`'s guard */
+  readonly armsOneSet: boolean;
+  /** whether THIS target's compiler is one the hoist was measured on
+   *  (`compilerBehaviors.hoistsSingleSetArm`) */
+  readonly targetHoists: boolean;
+}
+
+export const SELECT_GATES: readonly Gate<SelectCandidate>[] = [
+  {
+    // The diamond itself: two distinct arms, each reached only from one head, and that head's
+    // `cond_br` choosing between exactly the two of them. A FALL-THROUGH switch has neither — its
+    // arms run on into one another and its tests reach the shared return directly — so this
+    // admission never overlaps the fall-in machinery above. What it DOES overlap is a two-way
+    // `switch` with a `default`: that is a diamond, it
+    // reaches this table, and it is judged on the shape it has rather than the keyword that spelled
+    // it (`sw2`, packages/cli/test/matching — a bodied one, so `arms-are-one-set` refuses it).
+    id: 'two-arms-one-head',
+    why: 'both arms chosen by ONE `cond_br` and reached from nowhere else — the diamond itself',
+    sound: false,
+    rejects: (c) => c.head === null,
+  },
+  {
+    // THE TOWER'S OBLIGATION FOR A BACKWARDS DEFAULT, discharged (header). The clause above reads
+    // the CFG as it stands at this pass's turn; this one asks whether the ROM had the same shape,
+    // by reading `mergeShapes` off the CFG as it ENTERED pre-recovery. `raise/shortcircuit.ts`
+    // MANUFACTURES two-armed diamonds out of condition trees the ROM never merged, and it runs
+    // before this pass; a manufactured one is not evidence about how agbcc spelled anything.
+    id: 'pre-diamond',
+    why: "the diamond must be the ROM's, not one a pre-recovery pass manufactured out of a condition tree",
+    sound: false,
+    guardedBy: 'retsink.test.ts: a diamond absent from the pre-recovery map is refused',
+    rejects: (c) => !c.preDiamond,
+  },
+  {
+    // `carried` is read off the two arms, so an arrival that is not an arm carries a value nothing
+    // here has judged. A guard branching onto the same `return` hands the merge whatever it was
+    // holding — and the hoist argument is about ALL of a merge variable's assignments, not two of
+    // the three.
+    id: 'no-arrival-but-the-arms',
+    why: 'a third in-edge carries a value the arm test never saw',
+    sound: false,
+    // Dropping it also changes the lift of `pokeemerald:GetGenderFromSpeciesAndPersonality:agbcc`.
+    guardedBy: 'retsink.test.ts: every one-set-arm clause refuses a shape the two-armed evidence does not cover',
+    rejects: (c) => c.preds.length !== c.brPreds.length,
+  },
+  {
+    // The claim is about a merge VARIABLE, and a `ret` with no operands has none: there is no value
+    // for agbcc to hoist above the compare, so nothing says it would not re-emit this shape.
+    //
+    // SUBSUMED ON THIS CORPUS, and the row ids are the point. Instrumenting `firstRejection` over
+    // all 1039 rows shows the clause first-refusing two agbcc sites — `kleod:Decompress` (kl-eod-decomp's source, before 2026-09-13) and
+    // `kleod:ReadKeyInput` — so the ARM Thumb frontend really does hand this table operand-less
+    // `ret` merges. Ablating it still moves 0 rows,
+    // because `arms-are-one-set` refuses both a step later. It is kept for the same reason
+    // `no-arrival-but-the-arms` is: the two make independent claims, and this one is the only thing
+    // between an operand-less `ret` and admission on a shape whose arms ARE one SET each.
+    id: 'a-value-is-returned',
+    why: 'a `ret` with no operands carries no merge variable, so the hoist the admission rests on cannot apply',
+    sound: false,
+    rejects: (c) => c.carried.length === 0,
+  },
+  {
+    // THE HOIST'S OWN GUARD, borrowed rather than re-derived: `raise/narrowlocal.ts`'s
+    // `armIsOneSet`, cited there line by line to `gcc/jump.c:474/:480/:482/:483`. An arm that is not
+    // one speculatable SET is not hoisted, so the merge-variable spelling keeps its diamond too and
+    // sinking trades a byte-exact match for the same shape in the other ARM ORDER — which only the
+    // ranked `/flip-branch` can pay back, and the unranked primary cannot. Paid for by five measured
+    // byte-exact matches (header).
+    //
+    // The three places this shared predicate is narrower than the optimizer it models — a
+    // foldable-immediate arm, an emptied arm, a two-constant arm — are named in the header; no
+    // corpus row inhabits any of them, and all three are in the refusing direction.
+    id: 'arms-are-one-set',
+    why: 'an arm that is not ONE speculatable SET is never hoisted, so the merge variable keeps the diamond too',
+    sound: false,
+    // The clause the compiled evidence is committed FOR: `selbody`/`selcomp3`/`selload` keep their
+    // diamond in both spellings while `selbtn`/`selk53`/`selpool`/`selcomp` lose it in the merge one
+    // (select-spelling.test.ts), and five shapes lose a byte-exact match without it
+    // (packages/cli/test/matching). On the corpus, dropping it changes `pokeemerald:GiveBerryPowder`.
+    guardedBy: 'select-spelling.test.ts: an arm that is NOT one SET CAN be spelled with a merge variable',
+    rejects: (c) => !c.armsOneSet,
+  },
+  {
+    // THE COMPILER THE ARGUMENT IS ABOUT. Every measurement behind this table is agbcc -O2
+    // -mthumb; nothing has compiled the pair on IDO, KMC GCC or mwcc. The rest of this file is
+    // ISA-neutral and runs for all four, so without this clause an agbcc cost model would decide a
+    // PowerPC function with nothing in the code saying so. It claims nothing instead
+    // (`target.ts hoistsSingleSetArm`, absent ⇒ false), which is free: re-lifting all 1039 corpus
+    // rows shows the admission reaches no non-agbcc row either way.
+    //
+    // LAST in the table on purpose. A census attributes a site to the clause that FIRST refuses it,
+    // so first position would charge this COMPILER fact with 28 refusals, 26 of them shapes that are
+    // not diamonds at all. Last, it decides 0 sites on the whole corpus, which is exactly what
+    // `target.ts` claims for it.
+    id: 'compiler-hoists-single-set-arm',
+    why: 'the hoist this admission reads backwards was measured on agbcc and declared nowhere else',
+    sound: false,
+    rejects: (c) => !c.targetHoists,
+  },
+];
+
 /** The two questions the fall-in clauses ask of the function's comparison-tree dispatches. */
 interface DispatchModel {
   /** Is this block part of the dispatch on `s` — either one of its tests, or an arm of one? */
@@ -194,11 +489,35 @@ function dispatchModel(fn: Fn, defs: Map<Value, Op>): DispatchModel {
   };
 }
 
-/** Tail-duplicate a return-only merge block into its unconditional-branch predecessors, but ONLY in the
- *  short-circuit shape (some branch-pred is shared, or the arms are selected by a fused connective).
- *  Returns whether anything changed. A "return-only" block is exactly one `ret` whose operands are all
- *  its own block-params, so each predecessor already carries the returned value as a successor arg. */
-export function sinkReturns(fn: Fn, gates: readonly Gate<FallInCandidate>[] = FALL_IN_GATES): boolean {
+/** What the one-set-arm admission needs from OUTSIDE the IR it is handed.
+ *
+ *  `hoistsSingleSetArm` is the COMPILER fact, threaded from `decompile`'s own target — the SAME
+ *  `compilerBehaviors` field `raise/narrowlocal.ts` reads, because it is the same `gcc/jump.c` guard.
+ *  Absent ⇒ the one-set-arm admission never fires; the short-circuit admissions are
+ *  compiler-independent and unaffected.
+ *
+ *  `mergeShapes` is the CFG AS IT ENTERED PRE-RECOVERY (`PreRecoveryFacts`), and it is threaded for
+ *  the reason narrowlocal threads it: `raise/shortcircuit.ts` manufactures two-armed diamonds before
+ *  this pass runs, and a manufactured one says nothing about how agbcc spelled the function. Absent
+ *  ⇒ `pre-diamond` refuses every site, so a caller that does not thread it gets no one-set-arm
+ *  admission at all — the refusing direction, and what `sinkReturns`' hand-built unit callers get
+ *  unless they opt in. */
+export interface RetSinkOptions {
+  readonly hoistsSingleSetArm?: boolean;
+  readonly mergeShapes?: ReadonlyMap<Block, MergeShape>;
+}
+
+/** Tail-duplicate a return-only merge block into its unconditional-branch predecessors, in the three
+ *  shapes the header argues for: a short-circuit chain visible in the CFG, one fused into a
+ *  connective, and a two-armed diamond whose arms are ONE speculatable SET each. Returns whether
+ *  anything changed. A "return-only" block is exactly one `ret` whose operands are all its own
+ *  block-params, so each predecessor already carries the returned value as a successor arg. */
+export function sinkReturns(
+  fn: Fn,
+  opts: RetSinkOptions = {},
+  gates: readonly Gate<FallInCandidate>[] = FALL_IN_GATES,
+  selectGates: readonly Gate<SelectCandidate>[] = SELECT_GATES,
+): boolean {
   let changed = false;
   const preds = predecessors(fn);
   const defs = defOpMap(fn);
@@ -216,6 +535,8 @@ export function sinkReturns(fn: Fn, gates: readonly Gate<FallInCandidate>[] = FA
     return t?.opcode === 'br' && t.successors.length === 1 && t.successors[0].block === m;
   };
   for (const m of [...fn.blocks]) {
+    // RETURN-ONLY merges. A merged `store…; ret` is `raise/tailsink.ts`'s, and only as rank.ts's
+    // `/shared-tail` twin: its IR comes from both spellings.
     if (m.ops.length !== 1) {
       continue;
     }
@@ -275,13 +596,62 @@ export function sinkReturns(fn: Fn, gates: readonly Gate<FallInCandidate>[] = FA
     const fellInto = (q: Block, target: Block) =>
       firstRejection(gates, { q, target, dispatches: siblingArms(q, target).filter(ownedBy) }) === null;
     const arrivals = (p: Block) => (preds.get(p) ?? []).filter((q) => !fellInto(q, p)).length;
-    if (!brPreds.some((p) => arrivals(p) >= 2) && !fusedDiamond) {
+    // (c) ONE-SET-ARM DIAMOND — the header's compiler fact. `head` is the diamond read backwards:
+    // each arm's only predecessor is the same block, and that block's `cond_br` chooses between the
+    // two of them. `carried` is what each arm hands the merge, one entry per arm per returned
+    // operand, so a pair whose values come in by different edges is judged together.
+    //
+    // It is deliberately NOT `narrowlocal.ts`'s `mergeArms`, even though the two agree conjunct for
+    // conjunct once `no-arrival-but-the-arms` has run. That one answers "was this a diamond in the
+    // ROM" and is read off the PRE-RECOVERY CFG; `pre-diamond` carries that answer here. This one
+    // answers "is it a diamond NOW", at the moment a tail duplication is about to rewrite these
+    // terminators, and only the live CFG can say so.
+    const armsMeetAt = (): Block | null => {
+      const [x, y] = brPreds;
+      if (brPreds.length !== 2 || x === y) {
+        return null;
+      }
+      const [px, py] = [preds.get(x) ?? [], preds.get(y) ?? []];
+      if (px.length !== 1 || py.length !== 1 || px[0] !== py[0]) {
+        return null;
+      }
+      const t = terminator(px[0]);
+      const succs = t?.opcode === 'cond_br' ? t.successors.map((e) => e.block) : [];
+      return succs.length === 2 && succs.includes(x) && succs.includes(y) ? px[0] : null;
+    };
+    /** What an arm carries in: one entry per returned operand, resolved through the function-wide
+     *  `defs` because the value may be defined in the head rather than in the arm. */
+    const carriedBy = (p: Block) => {
+      const args = p.ops[p.ops.length - 1].successors[0].args;
+      return ret.operands.map((o) => defs.get(args[m.params.indexOf(o)]));
+    };
+    // LAZY, and not for speed: `gate-census.ts` counts a table's refusals as sites it DECIDED, and
+    // the short-circuit admissions above settle most sites before this table would have a say.
+    // Evaluating it there would report refusals at sites whose answer was never in question.
+    const constantSelect = () => {
+      return (
+        firstRejection(selectGates, {
+          brPreds,
+          preds: ps,
+          head: armsMeetAt(),
+          preDiamond: opts.mergeShapes?.get(m)?.diamond === true,
+          carried: brPreds.flatMap(carriedBy),
+          armsOneSet: brPreds.every(armIsOneSet),
+          targetHoists: opts.hoistsSingleSetArm === true,
+        }) === null
+      );
+    };
+    if (!brPreds.some((p) => arrivals(p) >= 2) && !fusedDiamond && !constantSelect()) {
       continue;
     }
     for (const p of brPreds) {
-      const args = p.ops[p.ops.length - 1].successors[0].args;
-      const sunk = ret.operands.map((o) => args[m.params.indexOf(o)]);
-      p.ops[p.ops.length - 1] = mkOp('ret', { operands: sunk });
+      const t = p.ops[p.ops.length - 1];
+      const sunk = ret.operands.map((o) => t.successors[0].args[m.params.indexOf(o)]);
+      // The `br` being replaced carries whether the machine BRANCHED to this epilogue or fell into
+      // it, which is what `structure/retspell.ts` reads. Sinking puts the return ON that edge, so
+      // the edge's fact travels with it; ask the new return block's in-edges instead and they answer
+      // how control reached the statements above the return, not how it reached the epilogue.
+      p.ops[p.ops.length - 1] = mkOp('ret', { operands: sunk, attrs: fallThroughOf(t) });
       changed = true;
     }
     // If no predecessor still branches to m (all were unconditional), it is unreachable — drop it.