@asmlift/core 0.10.0 → 0.11.0

package/src/symbols.ts

@@ -560,19 +560,48 @@ export function pointeeFields(pointee: SymbolPointee | undefined): DeclaredField
   return declaredFields(pointee.layout);
 }
 
-/** Kind-aware two-probe lookup for a pool-loaded 32-bit value. Exact match first (any kind);
- *  on miss, `value & ~1` — accepted ONLY when the hit is code, because ELF function addresses
- *  are stored with the Thumb bit cleared while a Thumb code pointer in a pool is odd. An exact
- *  odd-DATA hit therefore wins over a masked code hit (odd data addresses are real). */
+/** A name C can spell. Splat's `func_X.NON_MATCHING` labels are sized data aliases that are not. */
+const C_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** THE one object an address names, decided once per address so every lookup that lands there
+ *  spells the same name. Two names for one object inside one function are not a style problem:
+ *  the compiler treats distinct symbols as non-aliasing and forwards a store made through one past
+ *  a store made through the other.
+ *
+ *  Usually the canonical `[0]`. The exception is an unsized data label ranked first over the sized
+ *  object that starts at the same address (sa3's `gUnknown_08358528` over the 540-byte
+ *  `Map_zone_1_act_hub_fg0`, pokeemerald's `gMultiBootProgram_BerryGlitchFix_End` over
+ *  `gMultiBootProgram_PokemonColosseum_Start`): the object is the sized one, because only it has
+ *  an extent, so both an exact hit and an interior hit name it. Never where any alias is code: a
+ *  sized data alias there is a label over the function's bytes (MIPS `func_X.NON_MATCHING`, which
+ *  splat maps rank behind an unsized `gcc2_compiled.` marker), not an object. */
+function objectAt(infos: readonly SymbolInfo[]): SymbolInfo {
+  const head = infos[0];
+  if (head.kind !== 'data' || head.size !== undefined || infos.some((i) => i.kind === 'code')) {
+    return head;
+  }
+  return infos.find((i) => i.kind === 'data' && i.size !== undefined && C_IDENTIFIER.test(i.name)) ?? head;
+}
+
+/** Kind-aware two-probe lookup for a pool-loaded 32-bit value. Exact match first (any kind), which
+ *  names {@link objectAt}'s object; on miss, `value & ~1` — accepted ONLY when the hit is code,
+ *  because ELF function addresses are stored with the Thumb bit cleared while a Thumb code pointer
+ *  in a pool is odd. An exact odd-DATA hit therefore wins over a masked code hit (odd data
+ *  addresses are real).
+ *
+ *  The masked probe asks for the CODE alias at that address, not for the canonical `[0]`: a
+ *  table-end or segment marker can share its address with the function that follows it, and the
+ *  provider may rank the marker first (pokeemerald's `gMysteryEventScriptCmdTableEnd` over
+ *  `GameCubeMultiBoot_Hash`). An odd pool word there is still the function's Thumb pointer. */
 export function lookupSymbol(map: SymbolMap, value: number): SymbolInfo | null {
-  const exact = map.get(value)?.[0];
-  if (exact) {
-    return exact;
+  const exact = map.get(value);
+  if (exact !== undefined && exact.length > 0) {
+    return objectAt(exact);
   }
   if ((value & 1) === 1) {
-    const masked = map.get(value & ~1)?.[0];
-    if (masked?.kind === 'code') {
-      return masked;
+    const code = map.get(value & ~1)?.find((info) => info.kind === 'code');
+    if (code) {
+      return code;
     }
   }
   return null;
@@ -580,10 +609,11 @@ export function lookupSymbol(map: SymbolMap, value: number): SymbolInfo | null {
 
 /** Interior attribution: the data symbol whose `[address, address+size)` range contains
  *  `value` strictly inside (offset > 0 — exact bases go through `lookupSymbol`). Only
- *  complete-typed globals carry a size, so unsized arrays never attribute. */
+ *  complete-typed globals carry a size, so unsized arrays never attribute. The symbol at each
+ *  base is {@link objectAt}'s, the same one an exact hit on that base names. */
 export function lookupInterior(map: SymbolMap, value: number): { info: SymbolInfo; offset: number } | null {
   for (const [addr, infos] of map) {
-    const info = infos[0];
+    const info = objectAt(infos);
     if (info.kind !== 'data' || info.size === undefined) {
       continue;
     }
@@ -596,9 +626,16 @@ export function lookupInterior(map: SymbolMap, value: number): { info: SymbolInf
 
 /** The `SymbolInfo` keys a project's DWARF can only carry because the symbol's DEFINITION was
  *  compiled from C. Everything else in the map survives a function that is still `INCLUDE_ASM`:
- *  its `.symtab` entry exists (the asm defines the label), and its globals are typed by the OTHER
- *  translation units that declare them. Listed here, once, so {@link asIfUndecompiled} and any
- *  later definition-derived fact (a signature, a local's type, a register location) stay in sync. */
+ *  its `.symtab` entry exists (the asm defines the label), and most globals it reads are typed by
+ *  other code that references them. Listed here, once, so {@link asIfUndecompiled} and any later
+ *  definition-derived fact (a signature, a local's type, a register location) stay in sync.
+ *
+ *  KNOWN GAP: "other code" is not guaranteed. agbcc writes a DWARF entry for an extern global only
+ *  in a compilation unit that references it, so a global defined in asm (a NOTYPE symbol) that only
+ *  the row's own body references takes its type from the row's decompiled C. Nothing here strips
+ *  that type, because the map does not record which compilation unit typed a symbol. kleod has 10
+ *  such globals across 6 rows, among them PauseMenuScreenHandler's `gUnk_081166F8[4][4]`. The
+ *  CLI's repro reads the same ELF and sees the same types. */
 const DEFINITION_DERIVED_KEYS = ['declared', 'signature'] as const satisfies readonly (keyof SymbolInfo)[];
 
 /** The map a user actually has while decompiling `fn` — i.e. with `fn` still an `INCLUDE_ASM`

package/src/target.ts

@@ -5,7 +5,9 @@
 // What each datum drives:
 //   • id               → frontend dispatch (registry.ts)
 //   • compiler         → idiom gating (patternApplies) + the report
-//   • argRegs / returnReg → entry-param ordering and return-value read in the frontends
+//   • argRegs / returnReg → entry-param ordering and return-value read in the frontends; argRegs
+//     also says whether an ARM body's argument scan counts this target's words
+//     (frontend/arm-body.ts `scansArgumentsOf`, read by frontend/callee-body.ts)
 //   • capabilities.hwDivide → gates the MIPS hardware-divide decode (mips.ts), the soft-division
 //     pre-recovery pass, and idiom gating; a `div` on a target declaring no divider degrades to
 //     a loud opaque (exercised by packages/cli/test/matching/divmul.test.ts). `hwFloat` → idiom
@@ -45,7 +47,7 @@
 //     `aggregateReturn`, `largestAlignment`, `enumBytes`, `bitfieldPacking` and
 //     `byValueAggregateArgWords` (aggregate.ts, for frontend/call-plan.ts — which the Thumb, MIPS
 //     and PowerPC lowerings share — frontend/thumb.ts, frontend/mips.ts, frontend/ppc.ts and
-//     frontend/frame-objects.ts),
+//     frontend/frame-objects.ts; `enumBytes` is the structurer's too, through StructureOptions),
 //     `hoistsSingleSetArm` (raise/narrowlocal.ts and raise/retsink.ts), `arrayShapeFromStride`
 //     (raise/globalshape.ts, run on the LIFTED fn), `eightByteReturnScratch`
 //     (frontend/thumb.ts, which reads the epilogue), `callThunks` (frontend/thumb.ts, which
@@ -701,7 +703,7 @@ export interface TargetDescription {
     oneWordFrameIsTheCapturedObject?: boolean;
     // A frame address this function hands out — in an argument register at a call, or stored to
     // memory — is the address of a LOCAL, so its receiver may read the frame from there up and no
-    // word from there up is a call's outgoing argument. Its one reader is the outgoing-argument
+    // word from there up is a call's outgoing argument. Its first reader is the outgoing-argument
     // analysis (`frontend/stackargs.ts`, the `escape` event): a store never reloaded HERE is read
     // THERE. Absent ⇒ a handed-out frame address explains nothing.
     //
@@ -719,8 +721,30 @@ export interface TargetDescription {
     // flow-insensitively, it would set aside `qh5`'s fifth `h5` word and lift `h5(1, 2, 3, 4)`. The
     // cost is false alarms that decline loud (`if (x) gt(&s); else h(y);`); where the analysis also
     // reads the event whole-function, it only refuses or excuses a word no call takes
-    // (stackargs.ts). `oneWordFrameIsTheCapturedObject` is the flow-insensitive licence, sound only
-    // where no block copy fits.
+    // (stackargs.ts). `oneWordFrameIsTheCapturedObject` is the flow-insensitive licence for any
+    // receiver, sound only where no block copy fits.
+    //
+    // Its SECOND reader is the Thumb frame model's [sp,#0] capture (`frontend/thumb.ts`, beside
+    // `noCallTakesAStackWord`), which reads the universal whole-function at offset 0: where the
+    // frame base is handed as the hidden pointer of a callee DECLARED to return a struct through
+    // memory, it is a local's address, so no word of the frame is any call's outgoing argument and
+    // the area is empty — whatever the other calls are (sret2knr: `u8 rnd();` beside two temps).
+    // This premise is read only where some call may take a stack word: where none does there is
+    // no outgoing area to confuse, and an escaping frame base is a local's address on any target,
+    // whoever receives it (a DMA source published to the device's registers, `dmafill_wh`).
+    // The residue cannot reach it: a block copy's base goes to `memcpy`, no struct-returning
+    // callee. That reading is agbcc's layout, and is measured beyond `f0`: thumb.h:573
+    // STARTING_FRAME_OFFSET 0 and :620-621 add `current_function_outgoing_args_size` to every
+    // elimination to sp (:628 ACCUMULATE_OUTGOING_ARGS); function.c:2629 puts STACK_DYNAMIC_OFFSET
+    // past the same size; calls.c:1598-1609 precomputes into a temp every argument containing a
+    // call whenever the call has stack arguments, so a struct result is never built straight into
+    // an outgoing word. Compiled at the rows' flags: `mk(..)` by value as the 5th argument, as the
+    // 1st followed by four ints, `mk(..).a` as the 5th, a 20-byte struct by value, and a 5-argument
+    // K&R `rnd(1, 2, 3, 4, 5)` beside a temp each put the temp at sp+4 or higher, with [sp,#0] the
+    // outgoing word. A frame whose sp moves between two accesses is refused before this is read
+    // (thumb.ts `frameDepthBlocker`). Hand-written asm that builds a struct return at [sp,#0] and
+    // also stores a stack argument there declines; one that hands that word, unstored, to an
+    // undeclared callee as its fifth argument loses it from the callee's guessed arity.
     escapedFrameAddressNamesALocal?: boolean;
     // WHERE AN O32 FUNCTION KEEPS ITS LOCALS in the one frame `addiu sp,sp,-N` reserves — the area
     // the MIPS frontend hands the frame-object audit as `ownedLocals`/`declaredLocals`. Below it
@@ -1099,6 +1123,16 @@ export interface TargetDescription {
     // (proto-context.ts). ABSENT ⇒ unmeasured,
     // and an aggregate with an enum member is not sized.
     enumBytes?: number;
+    // Whether a plain `char` is signed, read where a context declares a global `char` and the lift
+    // asks whether a narrow read of it agrees with that declaration (structure.ts
+    // `storageDisagrees`). The compiler's default, with no flag; `targetFor` applies the flags that
+    // change it (`-funsigned-char`/`-fsigned-char`, IDO's `-signed`, mwcc's `-char`). MEASURED,
+    // `s32 g(void){ return gC; }` over `extern char gC;` at each toolchain's canonical flags: agbcc
+    // `ldrb` and ido7.1 `lbu` (unsigned), gcc2.7.2 `lb` (signed; gcc2.7.2kmc's canonical
+    // `-funsigned-char` makes it `lbu`), mwcc_242_81 `lbz` + `extsb` (signed). ABSENT ⇒ unmeasured,
+    // and a narrow read of a declared plain `char` agrees with neither sign, so it is spelled
+    // through its address.
+    plainCharSigned?: boolean;
     // How a struct's bitfields are placed (`aggregate.ts`). 'contiguous' — each at the bit after the
     // one before, straddling a byte or a word of its declared type, with the next member that is not
     // a bitfield at the first byte past it that its alignment allows. agbcc: thumb.h defines no
@@ -1149,6 +1183,23 @@ export interface TargetDescription {
     // ABSENT ⇒ false: a sign-extending load says nothing about the qualifier, and a device read is
     // pinned, and a read of a declared object placed, whatever its extension.
     volatileReadsExtendInRegister?: boolean;
+    // Does this compiler RELOAD a cell stored through one spelling and read back through another —
+    // two names, or a name and a numeric address, for the same byte? MEASURED at -O2, each probe
+    // storing 5 to a word, 7 to one of its bytes, and reading the word back: IDO 7.1 reloads
+    // (`D_80100000 = 5; ((u8 *)0x80100000)[1] = 7; return D_80100000;` is `sb; jr ra; lw v0`);
+    // agbcc (`sRandCount = 5; ((u8 *)&sUnknown)[4] = 7; return sRandCount;` is `strb; mov r0,
+    // #5`) and gcc 2.7.2 (`sb; jr ra; li v0, 5`) forward the stored value. IDO also reloads across
+    // two externs, two statics, an array element beside a scalar, and a word-wide literal beside
+    // a name. It reloads only a read that FOLLOWS the store: a read placed before a byte store
+    // through another name is sunk past it (`v0 = D_80100004; ((u8 *)&D_80100000)[5] = 7;
+    // return v0;` is `sb; jr ra; lw v0`). So where it holds, a pair of spellings in one block
+    // outside any loop, the store first, is faithful lifted as-is, whether the asm carries both or
+    // the map chose one; any other order, and every pair where it does not hold (an asm that went
+    // back to memory proves the source did not spell the byte two ways), raise/offsetnames.ts
+    // `cellSpelledTwice` declines.
+    //
+    // ABSENT ⇒ false: the compiler forwards (or is unmeasured, which declines the same pairs).
+    reloadsAcrossSpellings?: boolean;
     // Does this compiler, AT THESE FLAGS, keep a plain read whose value nothing uses? A FLAG fact,
     // never written in a description: `targetFor` sets it from the optimisation level
     // (`keepsUnusedReadsAt`), so a target at other flags has it absent. Where it holds, a read
@@ -1200,6 +1251,120 @@ export interface TargetDescription {
     // load decides only where this is `false`. ABSENT ⇒ unmeasured, and read as `true`, which only
     // refuses more.
     discardedReadMayFillArgRegister?: boolean;
+    // DOES THE COMPILER CROSS-JUMP RETURN TAILS? Where two arms end in the same code before the
+    // same return, does it keep ONE copy and jump the other arm into it? Where it does, the source
+    // may have written the tail into every arm (`h(10, 0); return;` in each) and the object still
+    // holds it once. So a join in the CFG is no evidence the source wrote one. What tells the two
+    // spellings apart is where the surviving copy sits, and which arms became one block. Read by
+    // the return-tail chooser (pipeline.ts `structureReturnTailReading`): it publishes the copies
+    // where the target's layout shows that merge (structure/cross-jumped-tail.ts), and never reads
+    // the layout where this is absent.
+    //
+    // gcc 2.x's jump2 pass does it: jump.c, in the `JUMP_CROSS_JUMP` run of `jump_optimize` that
+    // toplev.c makes at `optimize > 0`.
+    //   - An unconditional jump is first cross-jumped into the code before its own target label
+    //     (`find_cross_jump (insn, JUMP_LABEL (insn), 1)`).
+    //   - Only then is it tried against the other jumps to that label, and that search runs only
+    //     `if (INSN_UID (JUMP_LABEL (insn)) < max_uid)`.
+    //   - `do_cross_jump` keeps the LATER copy and jumps to a label before it. `get_label_before`
+    //     creates that label, so a jump already redirected is never searched for siblings again.
+    // So the copies spelling leaves three shapes in the object (structure/cross-jumped-tail.ts):
+    //   - an arm that does not use the tail stays laid out after the surviving copy, and that copy
+    //     ends in a jump over it;
+    //   - identical arm bodies stay separate blocks, where the join's one original label would have
+    //     merged them;
+    //   - `find_cross_jump` compares backward and stops at the first pair that differs, so a call
+    //     the tail opens with can be cut from the argument setup each arm keeps.
+    // MEASURED on two probe pairs, `corpus/probe-rettail-{pa,pb}-{copies,join}.c`: a three-arm `if`
+    // and a seven-case `switch`. Each is compiled at each toolchain's canonical flags by
+    // `scripts/regen-rettail-probes.ts`, and cross-jumped-tail.test.ts reads the objects:
+    //   - agbcc: the `pa` copies keep the tail mid-construct, ending in `b`, with the else arm laid
+    //     out after it. The `pb` copies hold the tail's store ONCE, in six case bodies; the join
+    //     has three bodies.
+    //   - gcc2.7.2 (-O1) and gcc2.7.2kmc (-O2): `pb` is the same, one store, six bodies against
+    //     three. The `pa` copies and join compile byte-identical, because the fall-through arm's
+    //     call merged too.
+    //   - ido7.1 and mwcc_242_81: NO. The `pb` copies keep all seven stores, each before its own
+    //     return, and the `pa` copies keep three calls.
+    // So `true` on ARMV4T_AGBCC and on MIPS_GCC. Each toolchain MIPS_GCC serves owes its own pair
+    // (the KEYED BY DESCRIPTION note at `spillSlotOrder`), and both are committed. ABSENT means no
+    // such merge: the chooser's size bound alone decides. mwcc_233_163n and mwcc_247_107 are
+    // unprobed, and PPC_MWCC claims nothing for them. Read only where the join is the default
+    // (`joinPastReturnsByDefault`), which both descriptions declaring this field leave out, so the
+    // marks decide no shipped default; the probe pairs still pin each one.
+    crossJumpsReturnTails?: boolean;
+    // DOES THE COMPILER FOLD THE CONSTANT A BRANCH PROVED INTO A RETURN ON THE BRANCH'S TAKEN EDGE?
+    // After `if (x == 0)`, a `return x` the jump reaches is `return 0` where it does. gcc 2.x's cse
+    // records the branch's equivalence on the NOT-taken edge of every jump (`record_jump_equiv
+    // (insn, 0)`, cse.c:7597), and on the taken edge only along a path it follows (`record_jump_equiv
+    // (insn, 1)`, cse.c:8545). It follows one only under -fcse-follow-jumps, which toplev.c:3606-3607
+    // sets at `optimize >= 2` (-fcse-skip-blocks skips a block without recording the edge:
+    // `cseFollowsJumpsUnder`). (Line numbers are agbcc's gcc 2.9 tree; for
+    // 2.7.2 the probe below is the evidence.) So where this is `false`, a return of the tested value
+    // left UNFOLDED in the object was the jump-target arm of its branch in the source: an `else`.
+    // The join past early returns spells it `if (x == 0) return x;`, the then arm, which folds.
+    // Read by the return-tail chooser (pipeline.ts `structureReturnTailReading`), which publishes the
+    // copies at such a return (structure/unfolded-branch-constant.ts), and only where the join is
+    // the default (`joinPastReturnsByDefault`), which MIPS_GCC, the one description declaring this
+    // field, leaves out: so it decides no shipped default, and the probes below still pin it.
+    // `false` only by the flags (`targetFor`), never declared.
+    //
+    // MEASURED on the probe pair `corpus/probe-rettail-pg-{copies,join}.c`, the `return gB` after a
+    // `gB` tested against 0, compiled by scripts/regen-rettail-probes.ts. The `beqz`'s delay slot:
+    //   - gcc2.7.2 at -O1 (canonical): copies `nop`, join `move v0,zero`. With the arms of the
+    //     copies flipped (the return the then arm), and with `-O1 -fcse-follow-jumps`, `move v0,zero`.
+    //   - gcc2.7.2 at -O2, and gcc2.7.2kmc at -O2 (canonical): `move v0,zero` under every spelling.
+    // So `true` on MIPS_GCC, and `false` from the flags where cse follows no jump (level 1 without
+    // -fcse-follow-jumps, or -fno-cse-follow-jumps: `cseFollowsJumpsUnder`). Absent elsewhere: agbcc
+    // at -O2 re-loads `gB` for the copies' `else` and does not fold it, which no value of this field
+    // says; ido7.1 and mwcc are unprobed.
+    foldsBranchConstantOnTakenEdge?: boolean;
+    // IS THE JOIN PAST EARLY RETURNS THE DEFAULT READING HERE? Not a compiler behaviour but a MEASURED
+    // DEFAULT, kept beside the behaviours because it is per compiler and read by the chooser they
+    // feed (pipeline.ts `structureReturnTailReading`), which the size bound and the marks above
+    // steer only where this is `true`. ABSENT ⇒ the return-tail copies are published, as before the
+    // join was a default, and the join is still structured and kept in the ranked fan as
+    // `/ret-join`. A compiler the held-out measurement has not reached publishes the copies first,
+    // and the join only where the copies refuse, so it lifts every function it lifted before and
+    // may lift one the old default declined (pipeline.ts `copiesByDefault`).
+    // docs/level-tower.md (A MEASURED DEFAULT IS THE ONE EXCEPTION) says why a field whose readings
+    // split site by site may still be declared here, and what re-measures it.
+    //
+    // MEASURED over held-out real functions, every function of a project outside the 620 the marks
+    // were chosen on, both readings really compiled against the project's own objects (2026-11-06),
+    // and over 160 generated functions written with the copies (2026-11-09). `true` only where the
+    // size bound with every mark loses no match the copies have on every measured set:
+    //   - mwcc_233_163n (Pikmin at its own flags, 2733 functions lifted, 66 re-spelled): 0 lost,
+    //     3 gained (two `actByEvent` methods 4/22 -> 0/20, `stickSlot__6PelletFi` 3/28 -> 0/26);
+    //     the generated functions: every source identical to the copies';
+    //   - mwcc_242_81 (ac-decomp and Mario Party 4, every unit compiled at this build although 9 of
+    //     Mario Party 4's rows are mwcc_247_107; 141 re-spelled): 0 lost, 0 gained; the generated
+    //     functions: every source identical to the copies'.
+    // So `true` on PPC_MWCC (mwcc_242_81) and PPC_MWCC_233; PPC_MWCC_247 (mwcc_247_107) leaves it
+    // out, no held-out unit measured at that build. Left out where it loses, the copies' default
+    // given back with the join's gains:
+    //   - gcc2.7.2kmc: held out (Snowboard Kids 2, 78 re-spelled) 0 lost, 2 gained
+    //     (`func_8003513C_35D3C`, `func_80045564_46164`); generated, 3 lost (the copies match, the
+    //     join is 2 to 8 lines off) and 5 gained. Given up: those 2 held out and the 5 generated.
+    //   - gcc2.7.2: held out (Mario Party 3, all 10019 functions, 150 re-spelled) 0 lost once the
+    //     unfolded return is read (`foldsBranchConstantOnTakenEdge`), none gained; generated, 1 lost
+    //     (4 lines off) and 2 gained. No mark read from the layout or the unfolded return separates
+    //     the 4 generated losses on the two lanes. Given up: the 2 generated, and the held-out and
+    //     620 functions the join brought closer.
+    //   - agbcc (pokeemerald, 15062 functions, 963 re-spelled): 9 lost, 18 gained. None of the 9 is
+    //     marked: switch and comparison-tree sites, a call cross-jumped across arms that pass it
+    //     different arguments, and a third source spelling the copies happen to share. Given up:
+    //     18 held out and 2 of the 620.
+    //   - ido7.1 (Animal Forest, 11363 functions, 252 re-spelled): 4 lost, one shape, 18 gained. ido
+    //     never cross-jumps, so no cross-jump mark applies. Counting copies of the arm's store does
+    //     not separate the readings either: compiled, the join of `func_80A42DB4_jp` ALSO keeps two
+    //     `sw zero,0(a3)`, because ido fills a `beql`'s likely slot with a copy of its target's first
+    //     word. What differs is the branch the slot copy rides: the copies' arm schedules its own
+    //     store into the slot of a plain `b`, the join's copy sits in a `beql`'s. That is the
+    //     candidate signal, unmeasured: frontend/mips.ts `normaliseBranchLikely` rewrites both to one
+    //     shape (its `likely` and `freed` sets still tell them apart) before the layout is recorded,
+    //     so no layout entry carries it. Given up: 18 held out and 7 of the 620.
+    joinPastReturnsByDefault?: boolean;
   };
 }
 
@@ -1335,6 +1500,10 @@ export const ARMV4T_AGBCC: TargetDescription = {
     switchBoundCase: 'taken',
     switchArmsFollowLayout: true,
     switchRequiresFrontLoadedTests: true,
+    // MEASURED on the probe pairs at the field (gcc 2.x jump.c's cross-jump). Read only where the join
+    // is the default (`joinPastReturnsByDefault`), which agbcc leaves out: the join loses 9 of
+    // pokeemerald's matches no mark separates.
+    crossJumpsReturnTails: true,
     hoistsSingleSetArm: true,
     eightByteReturnScratch: 'r2',
     arrayShapeFromStride: true,
@@ -1355,6 +1524,7 @@ export const ARMV4T_AGBCC: TargetDescription = {
     discardedReadMayFillArgRegister: true,
     byValueAggregateArgWords: true,
     enumBytes: 4,
+    plainCharSigned: false,
     bitfieldPacking: 'contiguous',
     roundTripsDoubleLiterals: true,
     // agbcc 2.9 (gcc/varasm.c `assemble_variable`, gcc/thumb.h): an array takes its element's
@@ -1512,6 +1682,7 @@ export const MIPS_IDO: TargetDescription = {
   // `switchAllowsNeqCase: false` — IDO's switch dispatch uses `==`/`<`, never `!=` cases;
   // leaving it permissive mis-recognises `!=`-rooted if-else chains as switches.
   compilerBehaviors: {
+    plainCharSigned: false,
     contractsFloatProducts: false,
     coalesceLoopInit: true,
     preserveDivergentBranchSense: true,
@@ -1519,6 +1690,8 @@ export const MIPS_IDO: TargetDescription = {
     switchAllowsNeqCase: false,
     // MEASURED — the pair at the field compiles to one load of `p[1]` for every local spelling.
     reloadsLocalReread: false,
+    // MEASURED: the probe at the field (`lw v0` after the byte store).
+    reloadsAcrossSpellings: true,
     // MEASURED: the probe at the field.
     narrowStoreConstantTakesLvalueType: true,
     aggregateBoundary: 1,
@@ -1643,6 +1816,7 @@ export const MIPS_GCC: TargetDescription = {
   fpu: O32_FPU,
   capabilities: { endianness: 'big', hwDivide: true, hwFloat: true, flags: false },
   compilerBehaviors: {
+    plainCharSigned: true,
     contractsFloatProducts: false,
     coalesceLoopInit: true,
     preserveDivergentBranchSense: true,
@@ -1682,6 +1856,15 @@ export const MIPS_GCC: TargetDescription = {
     // sub-trees a decline leaves, so a NESTED dispatch comes back as an `if` nest around a `switch`
     // over some of its arms.
     switchRequiresFrontLoadedTests: true,
+    // MEASURED on BOTH toolchains this description serves, the probe pairs at the field.
+    crossJumpsReturnTails: true,
+    // MEASURED at -O2 on both toolchains this description serves, the probe pair at the field;
+    // gcc2.7.2's canonical -O1 clears it (`targetFor`).
+    foldsBranchConstantOnTakenEdge: true,
+    // `joinPastReturnsByDefault` LEFT OUT, so the copies are published and the join is ranked as
+    // `/ret-join`. On held-out real functions it lost none of the copies' matches on either toolchain
+    // this description serves, but on 160 generated functions written with the copies it lost 3 on
+    // gcc2.7.2kmc and 1 on gcc2.7.2, which no mark separates (the field's note).
     // MEASURED on BOTH toolchains this description serves (the note above): one load of `p[1]` for
     // every local spelling of the pair at the field, gcc2.7.2kmc at -O2 and gcc2.7.2 at -O1 alike.
     reloadsLocalReread: false,
@@ -1778,6 +1961,7 @@ export const PPC_MWCC: TargetDescription = {
   // defaults; coalesceLoopInit false until a CW loop fixture says otherwise — the second of the
   // two compiler-wide guesses standing in for the per-function observation named at MIPS_GCC.
   compilerBehaviors: {
+    plainCharSigned: true,
     contractsFloatProducts: true,
     // MEASURED on all three builds in C: an integer, a pointer and a `u16 *` passed to an `s32 *`,
     // `u32` and `s32 *` parameter each fail to compile, and each compiles once cast (see the field).
@@ -1849,12 +2033,31 @@ export const PPC_MWCC: TargetDescription = {
     // MEASURED on all three builds: the probes at the fields.
     forwardsStructReturnDestination: false,
     discardedReadMayFillArgRegister: true,
+    // MEASURED over held-out real functions at mwcc_242_81 and mwcc_233_163n, at the field;
+    // PPC_MWCC_247 leaves it out.
+    joinPastReturnsByDefault: true,
   },
 };
 
+/** A description's behaviours less `joinPastReturnsByDefault`, for a build that shares the
+ *  description but was not measured for that default. */
+function withoutJoinDefault(d: TargetDescription): TargetDescription['compilerBehaviors'] {
+  const { joinPastReturnsByDefault: _measuredElsewhere, ...behaviors } = d.compilerBehaviors;
+  return behaviors;
+}
+
 /** CodeWarrior 2.3.3b163n (Pikmin): `PPC_MWCC` but for the one declaration a probe refuted there —
- *  it rejects a global register variable ("illegal storage class"), so it has no spelling for one. */
-export const PPC_MWCC_233: TargetDescription = { ...PPC_MWCC, globalRegisterVariables: undefined };
+ *  it rejects a global register variable ("illegal storage class"), so it has no spelling for one.
+ *  The return-tail default is PPC_MWCC's, measured at this build over Pikmin
+ *  (`joinPastReturnsByDefault`). */
+export const PPC_MWCC_233: TargetDescription = {
+  ...PPC_MWCC,
+  globalRegisterVariables: undefined,
+};
+
+/** CodeWarrior 2.4.7b107 (Mario Party 4's other build): `PPC_MWCC` less the return-tail default no
+ *  held-out function measured at this build (`joinPastReturnsByDefault`). */
+export const PPC_MWCC_247: TargetDescription = { ...PPC_MWCC, compilerBehaviors: withoutJoinDefault(PPC_MWCC) };
 
 /** A toolchain: one compiler binary, named as decomp.me names it. Several toolchains may share a
  *  description (`MIPS_GCC` serves two), and each keeps its own evidence. */
@@ -1946,7 +2149,7 @@ export const TOOLCHAIN_TARGETS = {
   },
   mwcc_247_107: {
     family: 'mwcc',
-    description: PPC_MWCC,
+    description: PPC_MWCC_247,
   },
 } as const satisfies Readonly<Record<string, ToolchainTarget>>;
 
@@ -2038,9 +2241,67 @@ export function targetFor(toolchain: ToolchainId, cflags: readonly string[]): Re
     const { enumBytes: _flagged, ...behaviors } = target.compilerBehaviors;
     target = { ...target, compilerBehaviors: behaviors };
   }
+  if (target.compilerBehaviors.foldsBranchConstantOnTakenEdge === true && !cseFollowsJumpsUnder(profile)) {
+    target = { ...target, compilerBehaviors: { ...target.compilerBehaviors, foldsBranchConstantOnTakenEdge: false } };
+  }
+  const charSigned = plainCharSignedUnder(t.family, profile.slots);
+  if (charSigned !== 'default' && charSigned !== target.compilerBehaviors.plainCharSigned) {
+    const { plainCharSigned: _default, ...behaviors } = target.compilerBehaviors;
+    target = {
+      ...target,
+      compilerBehaviors: charSigned === undefined ? behaviors : { ...behaviors, plainCharSigned: charSigned },
+    };
+  }
   return { toolchain, cflags, target, profile };
 }
 
+/** Does gcc's cse follow jumps at these flags (`compilerBehaviors.foldsBranchConstantOnTakenEdge`)?
+ *  Only a jump cse FOLLOWS gets its taken edge's equivalence: `cse_end_of_basic_block` marks a path
+ *  branch TAKEN only under `follow_jumps` (cse.c:8192-8211), and the branch around a block that
+ *  `skip_blocks` adds is AROUND, whose block is invalidated, not recorded (cse.c:8223, :8545-8548).
+ *  toplev.c:3606-3607 sets `flag_cse_follow_jumps` at `optimize >= 2`, and the switch sets or clears
+ *  it by name either way, the level's value standing where it is not given. -O0 is answered `true`:
+ *  cse does not run there, which is a different compiler again, and a level no table reads keeps
+ *  the declaration. (cse.c line numbers are agbcc's gcc 2.9 tree.)
+ *
+ *  MEASURED on `corpus/probe-rettail-pg` at gcc2.7.2, the copies' `beqz` delay slot: `nop` (unfolded)
+ *  at -O1, at `-O1 -fcse-skip-blocks`, at `-O2 -fno-cse-follow-jumps` and at `-O2
+ *  -fno-cse-follow-jumps -fno-cse-skip-blocks`; `move v0,zero` at -O2, at `-O2 -fno-cse-skip-blocks`
+ *  and at `-O1 -fcse-follow-jumps`. The join is `move v0,zero` under all seven. */
+function cseFollowsJumpsUnder(profile: CodegenProfile): boolean {
+  if (profile.family !== 'gcc' && profile.family !== 'agbcc') {
+    return true;
+  }
+  if (profile.slots.O === '0') {
+    return true;
+  }
+  const flag = profile.slots['-fcse-follow-jumps'];
+  return flag === 'on' ? true : flag === 'off' ? false : profile.slots.O !== '1';
+}
+
+/** What the flags say a plain `char` is (`compilerBehaviors.plainCharSigned`): `default` where they
+ *  leave it to the compiler. gcc keeps one flag, `flag_signed_char`, that `-fsigned-char` and
+ *  `-fno-unsigned-char` set and `-funsigned-char` and `-fno-signed-char` clear, the last one given
+ *  winning; the profile keeps the two switches apart, so where both are given and they disagree the
+ *  order is lost and the answer is undefined. IDO's `-signed` makes it signed, and mwcc's `-char`
+ *  takes `signed` or `unsigned`. */
+function plainCharSignedUnder(
+  family: FlagFamily,
+  slots: Readonly<Record<string, string>>,
+): boolean | undefined | 'default' {
+  if (family === 'ido') {
+    return slots.char === 'signed' ? true : 'default';
+  }
+  if (family === 'mwcc') {
+    return slots.char === 'signed' ? true : slots.char === 'unsigned' ? false : 'default';
+  }
+  const said = [
+    slots['-fsigned-char'] === undefined ? undefined : slots['-fsigned-char'] === 'on',
+    slots['-funsigned-char'] === undefined ? undefined : slots['-funsigned-char'] === 'off',
+  ].filter((x) => x !== undefined);
+  return said.length === 0 ? 'default' : said.every((x) => x === said[0]) ? said[0] : undefined;
+}
+
 /** Build the structurer's options for a target: the function's own `returnsVoid` plus every
  *  `compilerBehaviors` field. The ONE place a target's compiler behaviors flow into the
  *  target-agnostic structurer — a new compiler behavior is a field in `compilerBehaviors`, consumed

package/src/trace.ts

@@ -7,12 +7,20 @@
 import { cBackend } from './backend/c';
 import type { CodegenProfile } from './codegen-flags';
 import type { AsmData } from './frontend/asmdata';
+import type { CalleeBodies } from './frontend/callee-body';
 import type { Fn } from './ir/core';
 import { print } from './ir/print';
 import { verify } from './ir/verify';
 import type { LanguageBackend } from './l3/ast';
 import { DEFAULT_IDIOM_PATTERNS, RewritePattern, applyPattern, dce, patternApplies } from './pattern/engine';
-import { type OnGap, liftStamped, raiseRecovered, stampBehaviorsFor, structureChecked, stubResult } from './pipeline';
+import {
+  type OnGap,
+  liftStamped,
+  offsetNameBehaviorsFor,
+  raiseRecovered,
+  structureReturnTailReading,
+  stubResult,
+} from './pipeline';
 import { type FnProto, type Prototypes, declaresVoidReturn, prototypesFromSymbols } from './proto';
 import { type ContextGlobals, splitOwnContext } from './proto-context';
 import { assumedShapes, inferGlobalArrays, orderLicensedGlobals } from './raise/globalshape';
@@ -95,6 +103,7 @@ export interface TraceOptions {
   symbols?: SymbolMap; // address→symbol map (symbols.ts), as in decompile(); absent ⇒ inert
   contextGlobals?: ContextGlobals; // the declaration context's globals, as in decompile()
   ownContextProto?: FnProto; // the context's own entry, as in decompile()
+  calleeBodies?: CalleeBodies; // bodies of callees outside the input, as in decompile()
   onGap?: OnGap; // "strict" (default) | "annotate", as in decompile()
   /** Source probe at pattern boundaries: the source asmlift would emit there, which the cli report
    *  scores. One call per boundary: pattern N's after-source is pattern N+1's before-source. Absent ⇒
@@ -207,7 +216,7 @@ function traceTower(
     opts.asmData,
     opts.symbols,
     opts.contextGlobals,
-    undefined,
+    { calleeBodies: opts.calleeBodies },
     ownContext.ownContextProto,
   );
   trace.push({ id: 'stage:lift', title: 'Lift (ISA frontend → typed-SSA IR)', irDump: irDump(fn), verified: true });
@@ -234,9 +243,9 @@ function traceTower(
 
   // The names the map holds for addresses this machine code built by arithmetic off a named one
   // (raise/offsetnames.ts), off the same lifted fn and for the same reason as pipeline.ts's
-  // runTower.
+  // runTower — and its one-spelling-per-cell decline, which throws from here (pipeline.ts's 1.6).
   const named = opts.symbols
-    ? OFFSET_NAME_PASS.run(fn, opts.symbols, stampBehaviorsFor(target, opts.contextGlobals))
+    ? OFFSET_NAME_PASS.run(fn, opts.symbols, offsetNameBehaviorsFor(target, opts.contextGlobals))
     : [];
   trace.push({
     id: 'stage:offsetnames',
@@ -332,16 +341,21 @@ function traceTower(
   // (4) structure → neutral AST; boundary contract: no unresolved value leaked (strict) or
   // spelled as a loud ASMLIFT_ERROR marker (annotate) — same onGap option as decompile()
   const mapSymbols = opts.symbols ? symbolsByName(opts.symbols) : undefined;
-  const sfn = structureChecked(fn, {
-    ...structureOptionsFor(target, returnsVoid, prototypes),
-    spellSwitchFallthrough: (opts.backend ?? cBackend).spellsSwitchFallthrough,
-    spellSwitchBreak: (opts.backend ?? cBackend).spellsSwitchBreak,
-    onGap: opts.onGap ?? 'strict',
-    ...(mapSymbols ? { symbols: mapSymbols } : {}),
-    ...(opts.contextGlobals ? { contextGlobals: opts.contextGlobals } : {}),
-    ...(inferredSymbols.size ? { inferredSymbols } : {}),
-    ...(orderLicensed.size ? { orderLicensedGlobals: orderLicensed } : {}),
-  });
+  const { sfn } = structureReturnTailReading(
+    fn,
+    {
+      ...structureOptionsFor(target, returnsVoid, prototypes),
+      spellSwitchFallthrough: (opts.backend ?? cBackend).spellsSwitchFallthrough,
+      spellSwitchBreak: (opts.backend ?? cBackend).spellsSwitchBreak,
+      spellEarlyReturns: (opts.backend ?? cBackend).spellsEarlyReturn,
+      onGap: opts.onGap ?? 'strict',
+      ...(mapSymbols ? { symbols: mapSymbols } : {}),
+      ...(opts.contextGlobals ? { contextGlobals: opts.contextGlobals } : {}),
+      ...(inferredSymbols.size ? { inferredSymbols } : {}),
+      ...(orderLicensed.size ? { orderLicensedGlobals: orderLicensed } : {}),
+    },
+    (t) => backend.emit(t),
+  );
   trace.push({
     id: 'stage:structure',
     title: 'Structuring (IR → neutral AST)',