@asmlift/core 0.6.0 → 0.8.0

package/src/structure/bitfields.ts

@@ -73,11 +73,15 @@ export interface BitfieldDeps {
   memberQualsAllow: (f: SymbolStructField, containerConst: boolean | undefined, isStore: boolean) => boolean;
 }
 
+/** What a recognized bitfield store assigns: an inserted value, or the literal 0 the asm does not
+ *  carry (the ALL-ZERO form — see the note in `makeBitfieldSpelling`). */
+export type BitfieldAssigned = { k: 'zero' } | { k: 'value'; v: Value };
+
 export interface BitfieldSpellings {
   /** extract op → the `gSym.field` read it spells */
   spelling: Map<Op, { global: string; field: string }>;
-  /** store op → the `gSym.field = value` write it spells */
-  stores: Map<Op, { global: string; field: string; value: Value }>;
+  /** store op → the `gSym.field = …` write it spells */
+  stores: Map<Op, { global: string; field: string; value: BitfieldAssigned }>;
   /** loads whose EVERY use is a spelled extract: the fold emits no temp for these */
   absorbed: Set<Op>;
 }
@@ -103,7 +107,7 @@ export function makeBitfieldSpelling(deps: BitfieldDeps): BitfieldSpellings {
   // …and the WRITE side: a store the mask-and-insert idiom recognized (see the block below), with
   // the value the source assigned. THE SECOND inhabitant of "a precomputed member spelling", which
   // is what makes the shape shared rather than anticipated.
-  const bitfieldStore = new Map<Op, { global: string; field: string; value: Value }>();
+  const bitfieldStore = new Map<Op, { global: string; field: string; value: BitfieldAssigned }>();
   const absorbedLoads = new Set<Op>();
   if (symCtx && littleEndian && spellBitfieldMembers) {
     // the (name, byte) of a load's address when it resolves through defs alone — `gaddr` or
@@ -190,6 +194,34 @@ export function makeBitfieldSpelling(deps: BitfieldDeps): BitfieldSpellings {
     // single-use and unmaterialized, because the fold DELETES all of them — a second reader would
     // keep the temp and the emitted C would do the work twice.
     //
+    // THE ALL-ZERO FORM HAS NO `or`: agbcc's `expmed.c` skips the insert when the assigned value
+    // is all-zero (`:557-558`, `:606-608`), so `gSym.field = 0;` lowers to
+    // `store(A, and(load(A), ~W))` and the store's value operand IS the keep.
+    //
+    // ITS EVIDENCE IS THE MASK, NOT THE VALUE. `= 0` is also spellable raw, as
+    // `*(u8 *)&gSym = KEEP & *(u8 *)&gSym`, so keying on "the inserted value is 0" would name a
+    // member wherever the two spellings are the SAME OBJECT. Measured, pinned agbcc, `u8 a:4;
+    // u8 b:4`: the DECLARED store of the LOW nibble complements in the 32-bit domain — `~0xF` =
+    // -16, which no Thumb `mov #imm8` encodes, so `mov #0x10; neg` — where the byte-domain raw
+    // spelling narrows the same keep to one encodable `mov #0xF0`. The HIGH nibble's two
+    // spellings are byte-identical (`mov #0xf` on both sides). So the fold admits the zero form
+    // only where the keep mask is that 32-bit complement; the gate below says what each clause
+    // kills.
+    //
+    // THE MASK'S ENCODING IS NOT ITS DEFINING OP. `mov;neg` is only how the complement is built
+    // where it misses `mov #imm8`; agbcc spells the same complement for `u16 a : 12` as a pool
+    // `ldr` of `-0x1000` (compiled). A rule keyed on "defined by a `neg`" would refuse that real
+    // inhabitant, so the gate reads the mask's VALUE. The price: the Thumb frontend lowers
+    // `bic Rd,Rm` to `and(Rd, ~Rm)`, so a hand-written `mov #0xf; bic` arrives as the same IR as
+    // the accepted `mov #0x10; neg` and is admitted. agbcc emits no `bic` for this idiom
+    // (compiled: the or-form clear is `mov #0x4; neg`), and `/no-bitfield` co-enumerates the raw
+    // spelling, so that is one extra candidate for the differ, not a lost one.
+    //
+    // TARGET COUPLING, stated because the code cannot: every argument here is a THUMB encoding
+    // argument, and the fold's only target guard is `littleEndian`. That is sound only because
+    // armv4t+agbcc is the one little-endian target in `target.ts`; a second one inherits none of
+    // this reasoning.
+    //
     // TRUNCATION is what makes an UNMASKED insert legal, and only sometimes: C truncates the
     // assigned value to the field width, while the asm's `or` writes every bit of `v << lo` that
     // the STORE keeps. The two agree when the field ends the stored cell — bits above it are
@@ -239,24 +271,33 @@ export function makeBitfieldSpelling(deps: BitfieldDeps): BitfieldSpellings {
         const width = op.attrs.width as number;
         const cell = globalCellOf(defs, op.operands[0], op.attrs.off as number);
         const si = cell ? symCtx.info(cell.name) : undefined;
-        const orOp = defs.get(op.operands[1]);
+        const valOp = defs.get(op.operands[1]);
+        // the ALL-ZERO form: no `or`, the keep `and` IS the store's value. Single-use and
+        // unmaterialized go untested here because the shared `andOp` gate tests the same op.
+        const zeroForm = valOp?.opcode === 'and';
         if (
           !cell ||
           si?.shape !== 'struct' ||
           si.volatile ||
-          orOp?.opcode !== 'or' ||
-          orOp.operands.length !== 2 ||
-          materialize.has(orOp) ||
-          (useSitesOf.get(orOp.results[0]) ?? []).length !== 1
+          (!zeroForm &&
+            (valOp?.opcode !== 'or' ||
+              valOp.operands.length !== 2 ||
+              materialize.has(valOp) ||
+              (useSitesOf.get(valOp.results[0]) ?? []).length !== 1))
         ) {
           continue;
         }
         const cellBits = width * 8;
         const cellMask = width >= 4 ? -1 : (1 << cellBits) - 1;
-        for (const [keepV, insV] of [
-          [orOp.operands[0], orOp.operands[1]],
-          [orOp.operands[1], orOp.operands[0]],
-        ] as const) {
+        // The `or` form's two pairs are the commutativity of `|`; the zero form contributes one,
+        // with `null` for the insert the asm does not contain.
+        const pairs: readonly (readonly [Value, Value | null])[] = zeroForm
+          ? [[op.operands[1], null]]
+          : [
+              [valOp!.operands[0], valOp!.operands[1]],
+              [valOp!.operands[1], valOp!.operands[0]],
+            ];
+        for (const [keepV, insV] of pairs) {
           const andOp = defs.get(keepV);
           if (
             andOp?.opcode !== 'and' ||
@@ -298,30 +339,89 @@ export function makeBitfieldSpelling(deps: BitfieldDeps): BitfieldSpellings {
           if ((((w >= 32 ? -1 : (1 << w) - 1) << lo) & cellMask) !== clear) {
             continue;
           }
-          // …and the insert must be exactly that value seated at `lo`.
-          const shifted = defs.get(insV);
-          const value =
-            lo === 0
-              ? insV
-              : shifted?.opcode === 'shl' && shifted.operands.length === 1 && shifted.attrs.imm === lo
-                ? shifted.operands[0]
-                : null;
-          if (
-            value === null ||
-            (lo !== 0 && (materialize.has(shifted!) || (useSitesOf.get(insV) ?? []).length !== 1))
-          ) {
+          // …AND THE STORE'S WIDTH MUST BE THE ACCESS AN ASSIGNMENT TO THOSE BITS COMPILES TO:
+          // the NARROWEST aligned 1/2/4-byte cell that contains the whole window. agbcc picks the
+          // access from the field's own BITS, not from its container's declared type — measured,
+          // pinned agbcc, one compile per row:
+          //
+          //    u16 a : 2   at bit 0     → `ldrb`/`strb`   (narrower than the `u16` container)
+          //    u32 a : 12  at bit 0     → `ldrh`/`strh`   (narrower than the `u32` container)
+          //    u32 x : 8   at bit 12    → `ldr`/`str`     (WIDER: bits 12-19 straddle bytes 1-2)
+          //    u32 a : 17  / a : 20     → `ldr`/`str`     (WIDER: no 3-byte access exists)
+          //
+          // Both directions matter and only one of them is intuitive. Without the narrowing half a
+          // `strh` over `gState.hearts` (two bits inside byte 0) spells a member from bytes that
+          // spelling cannot reproduce. Without the WIDENING half every field whose bits straddle
+          // an aligned pair — the common packed-header shape — is refused, because the compiler
+          // had no choice but a word.
+          //
+          // So the test reads the WINDOW and never the map's `size`. `size` is the field's byte
+          // SPAN (@gba-kit/debug-info emits `ceil((bitsIntoByte + bitWidth) / 8)`), which for the
+          // two widening rows is 2 and 3 — neither an access this machine has, and 3 an access no
+          // machine has. Any bound expressed in `size` is therefore wrong for a whole band of real
+          // fields however it rounds. `bitOffset`/`bitWidth` state the same fact exactly.
+          const loBit = cell.byte * 8 + lo;
+          const cellWidth = [1, 2, 4].find(
+            (n) => Math.floor(loBit / (n * 8)) === Math.floor((loBit + w - 1) / (n * 8)),
+          );
+          if (width !== cellWidth) {
+            continue;
+          }
+          // THE ZERO FORM'S EVIDENCE RULE: accept only a keep mask no RAW spelling of the same
+          // clear can produce. Three clauses, each measured with the pinned agbcc:
+          //
+          //  · `mask === ~clear` — the 32-bit complement of the window. `~0xF` = -16 for a low
+          //    nibble, `-0x1000` for `u16 a : 12`: neither is encodable in the byte domain, so a
+          //    raw spelling narrows to a different object. A pool word like `0xFFFF00F0` clears
+          //    the same nibble but zeroes bits ABOVE the cell, so it is some other function whose
+          //    clear is a coincidence.
+          //  · `(mask & cellMask) !== mask` — a WORD cell is refused outright. `cellMask` has bit
+          //    31 clear at widths 1-2, so `mask === ~clear` already forces an outside bit there
+          //    and this can only bite at width 4. It costs nothing: compiled, `gS.a = 0;` for
+          //    `u32 a : 20` and `*(s32 *)&gS &= -1048576;` are byte-identical.
+          //  · `(mask & cellMask) !== 0` — a mask keeping NO bit of the cell is not a
+          //    read-modify-write. agbcc compiles `g.f8 = 0;`, a field filling its own byte, to
+          //    `mov #0x0; strb`, so the candidate could not reproduce its own input.
+          //
+          // The rule refuses a real population as collateral: agbcc narrows the HIGH nibble's
+          // clear to the in-cell `mov #0xf`, byte-identical to the raw spelling, so a declared
+          // store does NOT always complement in 32 bits. Only the converse is needed.
+          //
+          // NONE of this may extend to the `or` form, where the insert seated at `lo` is the
+          // evidence and agbcc does spell an end-of-cell clear with the narrow in-cell constant.
+          // `zeroForm`, the discriminant that built `pairs`, is what keeps the two apart.
+          if (zeroForm && (mask !== ~clear || (mask & cellMask) === mask || (mask & cellMask) === 0)) {
             continue;
           }
-          if (lo + w !== cellBits && provableBits(bits, value) > w) {
-            continue; // C would truncate bits the asm's `or` writes
+          // …and the insert must be exactly that value seated at `lo`. The zero form skips it:
+          // no insert to seat, and no bit the (absent) `or` writes for C's truncation to disagree
+          // with.
+          let assigned: BitfieldAssigned = { k: 'zero' };
+          if (insV !== null) {
+            const shifted = defs.get(insV);
+            const inserted =
+              lo === 0
+                ? insV
+                : shifted?.opcode === 'shl' && shifted.operands.length === 1 && shifted.attrs.imm === lo
+                  ? shifted.operands[0]
+                  : null;
+            if (
+              inserted === null ||
+              (lo !== 0 && (materialize.has(shifted!) || (useSitesOf.get(insV) ?? []).length !== 1))
+            ) {
+              continue;
+            }
+            if (lo + w !== cellBits && provableBits(bits, inserted) > w) {
+              continue; // C would truncate bits the asm's `or` writes
+            }
+            assigned = { k: 'value', v: inserted };
           }
+          // …and a DECLARED field must occupy exactly the window.
           const fld = symCtx
             .fieldsOf(cell.name)
-            ?.find(
-              (f) => f.bitWidth === w && f.offset * 8 + f.bitOffset! === cell.byte * 8 + lo && f.signed !== undefined,
-            );
+            ?.find((f) => f.bitWidth === w && f.offset * 8 + f.bitOffset! === loBit && f.signed !== undefined);
           if (fld && memberQualsAllow(fld, si.const, true)) {
-            bitfieldStore.set(op, { global: cell.name, field: fld.name, value });
+            bitfieldStore.set(op, { global: cell.name, field: fld.name, value: assigned });
           }
           break;
         }

package/src/structure/globalaccess.ts

@@ -123,12 +123,12 @@ export function bareArrayElement(si: SymbolInfo, width: number, signed: boolean)
 // reduce to: `(r<<11) + (i<<1)` and `((r<<10) + i) << 1` differ only in where the element scale
 // sits, which is exactly what the division removes. So this runs on the byte residual and
 // arrayAccess does not call it — see the note at that site for what the two spellings measure.
-// `packages/cli/test/matching/array-rank-axis.test.ts` compiles both halves of that.
+// `packages/cli/test/matching/array-rank-variation.test.ts` compiles both halves of that.
 //
 // The recovered address is the SAME address either way (C scales `[r]` by the declared row size,
 // which is the constant the arithmetic multiplied by), so this is a spelling, not a re-addressing.
 //
-// AND IT IS AN AXIS, NOT A DEFAULT — the evidence above says the residual carries a ROW, and it
+// AND IT IS A VARIATION, NOT A DEFAULT — the evidence above says the residual carries a ROW, and it
 // does not say which of the two spellings that reach it wrote one. The cast form this replaces
 // (`*(T *)((r<<11) + (i<<1) + (u32)&g)`) compiles to the SAME shift structure and differs only in
 // scheduling on agbcc, kmc and mwcc, and is byte-identical on IDO — where the flat sum is
@@ -149,7 +149,7 @@ function addTerms(e: Expr, sign: 1 | -1, into: { e: Expr; sign: 1 | -1 }[]): voi
 
 /** `x` when `t` is the NON-CONSTANT value `x` scaled by exactly `stride` (`x * stride` or
  *  `x << log2(stride)`), else null. A constant term is never a recovered subscript: both
- *  spellings of a constant row index compile identically, so nothing referees the choice. */
+ *  spellings of a constant row index compile identically, so nothing referees the question. */
 function scaledBy(t: Expr, stride: number): Expr | null {
   if (t.k !== 'bin') {
     return null;
@@ -195,6 +195,32 @@ export function declaredSubscripts(
   if (inner === null || inner.length === 0) {
     return null;
   }
+  return subscriptsFromExtents(inner, residual, width, true);
+}
+
+/** THE split of a BYTE residual into a multidimensional array's subscripts, shared by the two
+ *  declarations that can state a rank: a GLOBAL's ({@link declaredSubscripts}) and an array
+ *  MEMBER's (structure.ts `pointeeElement`). One copy, because the two must not come to disagree
+ *  about which term is a row.
+ *
+ *  `needRecovered` is the one place they legitimately differ, and it is a fact about the
+ *  FALLBACK rather than about the arithmetic. For a global, a residual holding no term at a
+ *  leading stride means there is nothing to recover, and today's flat `gSym[i]` already spells
+ *  the very same address — so the split is refused and nothing is lost. An array MEMBER of a rank
+ *  the project's own header declares has NO such fallback: `->x[i]` on a `u8 x[6][8]` is a ROW,
+ *  which does not type-check, so the leading subscripts have to be spelled even when every one of
+ *  them comes out the literal 0 (`->x[0][i]`, the same address the byte arithmetic reached).
+ *
+ *  REFUSES (null) when: any leading stride is not strictly larger than the one below it (an
+ *  extent of 1 makes two positions indistinguishable, so the split would be a guess); a stride is
+ *  not a safe integer; `needRecovered` and no term is a non-constant multiple of a leading stride;
+ *  or what remains does not divide into whole elements. */
+export function subscriptsFromExtents(
+  inner: number[],
+  residual: Expr,
+  width: number,
+  needRecovered: boolean,
+): { lead: Expr[]; idx: Expr } | null {
   const strides: number[] = [];
   for (let p = 0; p < inner.length; p++) {
     strides.push(inner.slice(p).reduce((a, b) => a * b, width));
@@ -217,7 +243,7 @@ export function declaredSubscripts(
     }
     return { k: 'const', value: 0 };
   });
-  if (taken.size === 0) {
+  if (needRecovered && taken.size === 0) {
     return null;
   }
   let sum: Expr = { k: 'const', value: 0 };

package/src/structure/namecoalesce.ts

@@ -52,18 +52,34 @@
 // still holds the value the iteration started with — `structure.ts` refuses to let a merge outside
 // the loop adopt it for exactly that reason (`carriesPreUpdate`), and refuses to let an inner
 // loop's variable adopt an enclosing one's, which the inner loop would then mutate every iteration.
-// `loop-escape` restates both over classes: a class holding a loop header's parameter may absorb
-// only values the loop's body contains. Two loops' variables always fail it — a nested pair because
-// the outer variable's home is outside the inner body, a disjoint pair in both directions — so the
-// enclosing-loop rule needs no gate of its own.
+// That second refusal has ONE exception there, `enclosingCarrierName`: a value the frontend's
+// write-order record shows crossing into the inner loop in the register it already had, and — its
+// `carriedByBothLoops` clause, this gate's premise stated per site — one that every outer back
+// edge hands back as a value the inner loop carries. So the walk can already hand this pass a class
+// holding BOTH headers' parameters; what it cannot hand it is a class the outer loop overwrites
+// behind the inner one's back. `loop-escape` restates both refusals over classes: a class holding
+// a loop header's parameter may absorb only values the loop's body contains. Two loops' variables
+// always fail it — a nested pair because the outer variable's home is outside the inner body, a
+// disjoint pair in both directions — so the enclosing-loop rule needs no gate of its own here.
 //
-// It is NOT marked sound, because it has not been shown to be, and it is BLUNTER than the rule it
-// restates: `carriesPreUpdate` branches on which emitter owns the latch and names four shapes that
-// are not the hazard, none of which this has. Dropping it over 773 benchmark rows improves 12 and
-// regresses none, measured at #55 — `nestedloop` is `int s = 0; … s += i*j`, one accumulator the
-// pass currently emits as two. Lifting `carriesPreUpdate` itself to name classes is the work that would take those
-// 12 rows; it needs the class-level closure, since a merge can reach a loop variable's name through
-// an edge that carried no loop variable at all.
+// It is BLUNTER than the rule it restates: `carriesPreUpdate` branches on which emitter owns the
+// latch and names four shapes that are not the hazard, none of which this has. It IS load-bearing,
+// and the measurement that says so is not a benchmark one: dropping it over 773 rows improves 12
+// and regresses none (#55), and `nestedloop` is `int s = 0; … s += i*j`, one accumulator the pass
+// emits as two — but with it dropped, two generated functions COMPUTE SOMETHING ELSE: an inner
+// loop's variable adopts the enclosing loop's carrier and then overwrites it every iteration. Both
+// are frozen as literal IR in `test/loop-escape-witnesses.ts`, and `namecoalesce.test.ts` asserts
+// the escape copy the gate forces on one side and its absence on the other. A byte score cannot
+// see that failure, which is the whole reason that fuzz exists. So the 12 rows are real and so is the hazard, and taking them
+// still needs `carriesPreUpdate` lifted to name classes: the class-level closure, since a merge can
+// reach a loop variable's name through an edge that carried no loop variable at all.
+//
+// WHY THE FLAG IS `false` ANYWAY, recorded here because this is where it is set. By `gates.ts`'s
+// definition — remove it and some candidate is WRONG — this gate qualifies, and the two frozen
+// witnesses are the proof. It stays `false` on the bluntness above: what is shown wrong is the
+// SHAPE this rejects, not the rule as written, which also refuses merges `carriesPreUpdate` would
+// allow. Flipping it costs a line in `namecoalesce-fuzz`'s `OUT_OF_REACH` — the ablating arm has no
+// witness inside `SEEDS` — and buys no coverage that `namecoalesce.test.ts` does not already hold.
 //
 // TWO KNOWN GAPS, both on the READ side of a relocated write:
 //
@@ -160,7 +176,7 @@ export const NAME_COALESCE_GATES: readonly Gate<NameMerge>[] = [
   },
   {
     id: 'type',
-    why: 'the survivor keeps its own declared type, so the two must agree',
+    why: 'a merged variable has one declared type, so the types of the two names must agree',
     sound: true,
     guardedBy: 'namecoalesce.test.ts: ablating type merges two names the declarations disagree about',
     rejects: (c) => !c.sameType,
@@ -177,8 +193,11 @@ export const NAME_COALESCE_GATES: readonly Gate<NameMerge>[] = [
   },
   {
     id: 'loop-escape',
-    why: 'outside the loop a loop variable’s name holds the value from BEFORE the update',
+    why: 'outside the loop a loop variable’s name holds the value from before the update',
     sound: false,
+    // Not required of an unsound gate, and named anyway: the differential fuzz never ablates this
+    // one, so the frozen witnesses are its only evidence and `gate-contract` pins their test.
+    guardedBy: 'namecoalesce.test.ts: ablating loop-escape lets an inner loop clobber the enclosing loop variable',
     rejects: (c) => c.loopEscapes,
   },
 ];

package/src/structure/retspell.ts

@@ -0,0 +1,95 @@
+// Which `return;` statements the SOURCE wrote, read off the assembly.
+//
+// A void `return;` is a control transfer to the epilogue, and a compiler spells one as an
+// unconditional `b <epilogue>`. So where the epilogue is a block of its OWN — nothing in it but the
+// `ret` — its in-edges are the ways the body ends, and only one kind of arrival is a statement:
+//
+//   - an unconditional branch instruction into it → a `return;` the source wrote.
+//   - FALLING into it                            → the body simply running out, which spells
+//                                                  nothing.
+//   - a conditional branch's own edge            → nothing either. Unoptimised code tests into a
+//                                                  BODY label and never into the epilogue, so a
+//                                                  `bxx` landing there is jump-optimisation having
+//                                                  rerouted a branch the source did not write — and
+//                                                  by then both spellings are one object anyway.
+//
+// The statement being decided is the one at the END of the body, so a fall-through in-edge normally
+// settles it: that edge is the body running out, and it wrote no `return;`. A branch in-edge
+// alongside it is a `return;`, just not this one — it ends an arm, and `l3/tailret.ts` may delete a
+// return only in TAIL position, so an arm the function continues past keeps its own. An arm that IS
+// in tail position is one the compiler must branch over regardless (the block laid out before the
+// epilogue is the one that falls in, and only one block can be), so its `return;` and its `}`
+// compile to the same instruction. That is what makes the answer safe per BLOCK.
+//
+// ONE KIND OF BRANCH IN-EDGE OVERRULES THE FALLING ONE: a branch out of an EMPTY block. That arm
+// holds nothing but the `return;`, so dropping it does not shorten a statement list, it flips the
+// branch sense — and the two senses are two different objects. Measured on `if (*p & 1) return; …`
+// at agbcc -O0: the sense that writes the `return;` is 40 bytes, `beq` over a `b <epilogue>`; the
+// flipped one is 36, `bne` over the body with no `b` at all. So that `b` is in the object because
+// the source wrote a `return;`, and the falling edge beside it licenses nothing.
+//
+// With no fall-through in-edge, a branch in-edge is the only evidence there is, and it says the
+// source wrote a `return;` — keep it. With neither, nothing reached the epilogue by a written
+// transfer at all and there is nothing to spell. NO in-edge at all says the same thing without
+// needing the epilogue to be a block of its own: a body that never branched anywhere ended by
+// running out. That is the single-block function, which on an OBJECT has no epilogue label to
+// split it — the shape the `.s` path never shows.
+//
+// A `ret` SUNK onto one edge (`raise/retsink.ts`, `raise/tailsink.ts`) carries that edge's own
+// fall-through fact and answers for itself, which beats anything its block's in-edges could say:
+// those are about reaching the statements above the return, not about reaching the epilogue. An
+// epilogue block that ALSO holds statements and did not come from sinking is not asked at all, for
+// the same reason.
+//
+// NOT DECIDED HERE: a `while` whose only exit branches straight to the epilogue. That `b` is the
+// loop's `}`, and the same instruction to the same address is what a trailing `return;` compiles to
+// — the two objects differ only by an empty forwarder block between them, which is a fact about
+// branch chains rather than about return spelling. It is kept, which is the side that can never
+// delete a return the object needs.
+//
+// The in-edges the reading is about are the ways the body ENDS, so only LIVE ones count. The thumb
+// frontend hands over unreachable blocks on purpose, and one laid out just before the epilogue would
+// otherwise contribute a fall-through no execution takes — deleting the `return;` every real edge
+// branched in with.
+//
+// This decides SPELLING only; `l3/tailret.ts` owns whether a marked return is safe to delete.
+import type { Block, Fn } from '../ir/core';
+import { predecessors, reachableBlocks } from '../ir/core';
+
+/** The arrival an in-edge stands for: a `return;` the source wrote, or the body running out. */
+const isWrittenBranch = (p: Block): boolean => {
+  const term = p.ops[p.ops.length - 1];
+  return term.opcode === 'br' && term.attrs.fallthrough !== true;
+};
+const isFallThrough = (p: Block): boolean => {
+  const term = p.ops[p.ops.length - 1];
+  return term.opcode === 'br' && term.attrs.fallthrough === true;
+};
+/** A branch out of an EMPTY block is an arm with nothing else in it: the `return;` it stands for is
+ *  the only statement that arm would hold, so it has nowhere else to live and is never dropped. */
+const isBareBranch = (p: Block): boolean => p.ops.length === 1 && isWrittenBranch(p);
+
+/** The blocks whose `ret` the assembly shows no `return;` for. */
+export function unspelledEpilogues(fn: Fn): Set<Block> {
+  const preds = predecessors(fn);
+  const live = reachableBlocks(fn);
+  const out = new Set<Block>();
+  for (const b of fn.blocks) {
+    const term = b.ops[b.ops.length - 1];
+    if (term?.opcode !== 'ret') {
+      continue;
+    }
+    const inEdges = (preds.get(b) ?? []).filter((p) => live.has(p));
+    // Nothing arrived here from anywhere: the body never left its one block, so it transferred
+    // control to no epilogue and spelled no `return;`.
+    if (inEdges.length === 0) {
+      out.add(b);
+      continue;
+    }
+    const fellIn = inEdges.some(isFallThrough) && !inEdges.some(isBareBranch);
+    if (term.attrs.fallthrough === true || (b.ops.length === 1 && (fellIn || !inEdges.some(isWrittenBranch)))) {
+      out.add(b);
+    }
+  }
+  return out;
+}