@asmlift/core 0.5.0 → 0.7.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,35 +11,532 @@
 // 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, so it has ≥2 predecessors), whereas a
-// simple diamond's arms each have exactly one predecessor. So sink only when some branch-predecessor of
-// the merge is itself shared (≥2 preds); 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
+// case 2's body running on — for a reason that has nothing to do with a chain of conditions.
+// Sinking there tail-duplicates the switch's SHARED RETURN into all five of its paths, which agbcc
+// then constant-folds per arm (`synthetic:sw_fall:agbcc`, 5 of its 11 objdiff points).
+//
+// So one arrival is SUBTRACTED, and only one kind: the previous arm of the same dispatch RUNNING
+// ON into this one (`fellInto`). It is subtracted for what it IS, not for what it computed —
+// "this pred computed something and ran on" is a proxy for the same intuition, and it refuses the
+// shape this pass exists for, where the two arms of `if (a) { … return 0; } if (b) { … return 0; }`
+// both compute and both jump to the shared exit (`retsink.test.ts`'s `TWO_ARMS`; five real-tier
+// sites have it, `kleod:EntityItemDrop:agbcc` among them).
+//
+// "THE PREVIOUS ARM OF THE SAME DISPATCH" IS A CLAIM ABOUT A DISPATCH, so this file models one
+// (`scrutOf`/`armsOf` below): two arms of two DIFFERENT tests on the SAME scrutinee. A proxy that
+// does not name a dispatch is wrong in both directions, and both readings are pinned as fixtures —
+// "each is the target of SOME conditional branch" reads the join of an `if` with no `else` as a
+// fall-in (`IF_NO_ELSE`), and adding "…and not siblings of the same `cond_br`" still says nothing
+// about WHICH dispatch, so `if (a) … if (b) …` on two different values loses its sinking. A
+// function with no comparison-tree dispatch has no fall-in to subtract, which is the truth about it.
+//
+// The two other clauses (`FALL_IN_GATES`): `q` must arrive by an UNCONDITIONAL branch, and it must
+// have a BODY. `isBodyless` (ir/core.ts) is the shared spelling of the second — a bodyless arm is
+// the record gcc leaves of a decision that RAN OUT (`emit_case_nodes` mints a `b .Ldefault` per
+// exhausted subtree), and it arrives rather than falls in; dropping it costs
+// `synthetic:llshr:gcc2.7.2kmc` its sinking. Its parameter half is what keeps an EMPTY case arm
+// (one op, but it binds the accumulator) on the fall-in side.
+//
+// AND THE MERGE MUST BELONG TO THAT DISPATCH (`ownedBy`). A fall-through switch can SHARE its
+// return with control flow outside itself — a guard's `goto` onto the same `return` — and there
+// refusing to sink is exactly wrong: the merge is left standing, Regime-A switch recovery declines
+// on it, and if-recovery duplicates the tails anyway. The pred shape alone cannot tell the two
+// apart (both present one fell-into arm with two preds); the SCRUTINEE can, because the guard tests
+// a different value. `synthetic:sw_fallguard` is the row: MATCH, and diff:6 with the clause dropped.
+//
+// REGIME SCOPE — the model is `cond_br`-seeded, so it is INERT ON A JUMP TABLE. A `switch_br`
+// dispatch's arms are invisible to `armsOf` and `fellInto` never fires there, so on
+// `synthetic:sw_jtfall`/`sw_jtfalldesc` the pass behaves as it does where there is no dispatch at
+// all. Deliberate: seeding `switch_br` too would move matching rows with no row asking for it. It
+// is the second definition of "this arm falls into that one" in the tree — `switch-recover.ts`'s
+// `analyzeArmExit` covers both regimes and is not reachable from `raise/` — so whoever builds the
+// Regime-B hoist should route both through one recognizer rather than widen the seed here.
 //
 // 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, defOpMap, mkOp, predecessors } from '../ir/core';
+import { Block, Fn, Op, Value, defOpMap, 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. */
 const CONNECTIVES = new Set(['logic_and', 'logic_or']);
 
-/** 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): boolean {
+/** "`q` is the previous arm of the same dispatch, RUNNING ON into `target`" — the one arrival
+ *  `arrivals` subtracts. `dispatches` is already the answer to the hard half (`siblingArms` and
+ *  `ownedBy` in `sinkReturns`); the table is a value so each clause can be dropped and the pass
+ *  re-run on real input. Every clause is `sound: false` — they trade BYTES, never correctness:
+ *  admitting one wrongly spells a correct function the compiler does not re-emit, and refusing one
+ *  wrongly does the same in the other direction. */
+export interface FallInCandidate {
+  /** the predecessor under test */
+  readonly q: Block;
+  /** the block it would have fallen into */
+  readonly target: Block;
+  /** the scrutinees whose dispatch has `q` and `target` as arms of two DIFFERENT tests AND owns
+   *  the return merge — empty when there is no such dispatch */
+  readonly dispatches: readonly Value[];
+}
+
+export const FALL_IN_GATES: readonly Gate<FallInCandidate>[] = [
+  {
+    // A DEFINITION rather than a tuning knob, and the one entry here nothing has been shown to
+    // move: a `cond_br` pred did not run on into this block, it chose it, so calling that a
+    // fall-in would be wrong about the CFG whatever it did to the bytes.
+    id: 'arrives-by-decision',
+    why: 'a `cond_br` pred CHOSE this block; that is a decision arriving, never a fall-in',
+    sound: false,
+    rejects: (c) => {
+      const t = terminator(c.q);
+      return t?.opcode !== 'br' || t.successors.length !== 1 || t.successors[0].block !== c.target;
+    },
+  },
+  {
+    // Paid for by a CORPUS row, not by a unit test: dropping it costs `synthetic:llshr:gcc2.7.2kmc`
+    // its sinking, and moves none of this file's fixtures.
+    id: 'bodyless-arm',
+    why: "gcc's `b .Ldefault` for an exhausted subtree is a decision that RAN OUT, not an arm",
+    sound: false,
+    rejects: (c) => isBodyless(c.q),
+  },
+  {
+    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: '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? */
+  inDispatch(b: Block, s: Value): boolean;
+  /** The scrutinees for which `q` and `target` are arms of two DIFFERENT tests: the dispatches in
+   *  which one could be the previous arm of the other. Two successors of ONE `cond_br` — the body
+   *  and the join of an `if` with no `else` — share no such scrutinee, which is the whole point. */
+  siblingArms(q: Block, target: Block): Value[];
+}
+
+/** THE DISPATCH MODEL. A TEST BLOCK ends in a `cond_br` on an integer comparison of exactly one
+ *  non-constant value against constants — the SCRUTINEE. Two test blocks belong to the same
+ *  dispatch when they test the same scrutinee: `recognizeSwitch`'s own PRE1 ("every test is on the
+ *  SAME Value") read at the raise level, without its dominance, purity or interval preconditions —
+ *  those decide whether a `switch` can be SPELLED, and this pass only needs to know a decision tree
+ *  is there. `NEGATED_ICMP` (ir/opcodes.ts) is the shared spelling of the icmp family, so an
+ *  eleventh comparison joins this model for free.
+ *
+ *  Constant folding is deliberately NOT reproduced (`switch-recover.ts evalConst` folds agbcc's
+ *  synthesized immediates): a test whose constant side this cannot see contributes two
+ *  non-constant operands and is skipped, which loses a subtraction rather than inventing one.
+ *
+ *  Built ONCE, before `sinkReturns`' merge loop, and read-only thereafter — nothing in the loop
+ *  writes either table, so the merge that is rewritten first sees the same dispatches as the last. */
+function dispatchModel(fn: Fn, defs: Map<Value, Op>): DispatchModel {
+  const scrutOf = new Map<Block, Value>();
+  /** Arms, indexed by the block reached and the scrutinee whose test sent it there — the test
+   *  blocks are the value, because a fall-in requires the two arms to come from DIFFERENT tests. */
+  const armsOf = new Map<Block, Map<Value, Set<Block>>>();
+  for (const b of fn.blocks) {
+    const t = terminator(b);
+    if (t?.opcode !== 'cond_br') {
+      continue;
+    }
+    const cmp = defs.get(t.operands[0]);
+    if (!cmp || !(cmp.opcode in NEGATED_ICMP)) {
+      continue;
+    }
+    const vars = cmp.operands.filter((o) => defs.get(o)?.opcode !== 'const');
+    if (vars.length !== 1) {
+      continue;
+    }
+    const scrut = vars[0];
+    scrutOf.set(b, scrut);
+    for (const e of t.successors) {
+      let byScrut = armsOf.get(e.block);
+      if (!byScrut) {
+        byScrut = new Map();
+        armsOf.set(e.block, byScrut);
+      }
+      const tests = byScrut.get(scrut) ?? new Set<Block>();
+      tests.add(b);
+      byScrut.set(scrut, tests);
+    }
+  }
+  return {
+    inDispatch: (b, s) => scrutOf.get(b) === s || !!armsOf.get(b)?.has(s),
+    siblingArms: (q, target) => {
+      const aq = armsOf.get(q);
+      const at = armsOf.get(target);
+      if (!aq || !at) {
+        return [];
+      }
+      const out: Value[] = [];
+      for (const [s, testsQ] of aq) {
+        const testsT = at.get(s);
+        if (testsT && [...testsQ].some((c) => [...testsT].some((d) => c !== d))) {
+          out.push(s);
+        }
+      }
+      return out;
+    },
+  };
+}
+
+/** 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);
+  const { inDispatch, siblingArms } = dispatchModel(fn, defs);
+  // WHICH READS NEED `terminator`'s UNDEFINED CASE, which is not "every read of a terminator". The
+  // scan over `fn.blocks` can meet a block with no ops at all, and that is the one read the guard
+  // is for: `ir/verify.ts` rejects an empty block and `pipeline.ts` verifies before calling this,
+  // but `sinkReturns` is exported and its tests build blocks by hand, where a refusal is a better
+  // answer than a TypeError. A read over a PREDECESSOR needs none and does not have one —
+  // `predecessors` is built from `successorsOf`, which is empty for a block with no terminator, so
+  // a bodyless block never appears in anyone's predecessor list. Once a block is known to end in a
+  // `br`, the rewrite below indexes its terminator directly.
   const isBrTo = (p: Block, m: Block) => {
-    const t = p.ops[p.ops.length - 1];
-    return t.opcode === 'br' && t.successors.length === 1 && t.successors[0].block === m;
+    const t = terminator(p);
+    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;
     }
@@ -59,8 +556,9 @@ export function sinkReturns(fn: Fn): boolean {
     }
     // SHORT-CIRCUIT GATE, in two shapes — the chain must be visible in the CFG or in the value domain.
     //
-    //   (a) UNFUSED: at least one branch-pred is a shared block (≥2 preds of its own) — the common
-    //       early-exit reached from every condition of the chain.
+    //   (a) UNFUSED: at least one branch-pred is ARRIVED AT from ≥2 places — the common early-exit
+    //       reached from every condition of the chain. Everything that reaches it counts EXCEPT the
+    //       previous arm running on (`fellInto` below).
     //   (b) FUSED: `branch-shortcircuit` (raise/shortcircuit.ts) rewrites the head's condition into a
     //       `logic_and`/`logic_or` and collapses the second condition block into it. That leaves both
     //       arms single-pred, so (a) cannot see the chain any more — but the CONNECTIVE is now the
@@ -84,7 +582,66 @@ export function sinkReturns(fn: Fn): boolean {
         return t.opcode === 'cond_br' && CONNECTIVES.has(defs.get(t.operands[0])?.opcode ?? '');
       });
     const fusedDiamond = brPreds.length >= 2 && brPreds.some(selectedByConnective);
-    if (!brPreds.some((p) => (preds.get(p)?.length ?? 0) >= 2) && !fusedDiamond) {
+    // Does the dispatch on `s` OWN this merge? Every predecessor of `m` must be part of it — one of
+    // its tests, or an arm of one. A `goto` from outside the switch onto the same `return` fails
+    // this on the scrutinee it tests, so nothing is subtracted and the merge is sunk. `ps`, not
+    // `brPreds`: that outside arrival is a `cond_br` (the guard's `bgt`), which never appears in
+    // `brPreds`.
+    const ownedBy = (s: Value) => ps.every((p) => inDispatch(p, s));
+    // `q` FELL INTO `p`: it is the previous arm of the same dispatch, running on. The clauses are
+    // `FALL_IN_GATES` above, argued in this file's header; `arrivals` counts every OTHER
+    // predecessor. Layout adjacency — `q` sitting immediately above `p`, which is what "fell
+    // through" means in the assembly — is NOT a clause: it moves no corpus row, and it would be an
+    // unpaid premise about `fn.blocks` still being address order.
+    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;
+    // (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) {
@@ -98,5 +655,14 @@ export function sinkReturns(fn: Fn): boolean {
       fn.blocks = fn.blocks.filter((b) => b !== m);
     }
   }
+  // Sinking RETIRES in-edges. A merge also reached by a `cond_br` keeps that one — a conditional
+  // branch cannot carry a `ret` — and so survives with a SINGLE predecessor, where its parameter is
+  // no longer a join but an alias of that edge's argument. Left standing, the structurer destroys
+  // the alias into a local of its own (`v0 = 0; return v0;`) and Regime-A switch recovery reads the
+  // block as a second, distinct default candidate. The cleanup is `ir/simplify.ts`'s own; it simply
+  // has no other caller downstream of here.
+  if (changed) {
+    simplifyTrivialPhis(fn);
+  }
   return changed;
 }