@asmlift/core 0.5.0 → 0.7.0

package/src/raise/paramwidth.ts

@@ -0,0 +1,201 @@
+// A NARROW DECLARED PARAMETER, extended once in the prologue.
+//
+// agbcc has no byte/half register move, so a callee whose parameter is declared `u8`/`s16` widens
+// it itself, with a shift pair at the very top of the function — the caller passes a full register
+// and the extension is part of the prologue. Both spellings below compiled with this benchmark's
+// own agbcc, and where each one puts the pair is the whole rule:
+//
+//     void pa(s32 *out, u8 a)  { out[0]=1; out[1]=2; out[2]=a; }      lsl/lsr mov str mov str str
+//     void pb(s32 *out, s32 a) { out[0]=1; out[1]=2; out[2]=(u8)a; }  mov str mov str lsl/lsr str
+//
+// The idiom patterns fold that pair to one `zext`/`sext` op, so `pa`'s parameter reaches this pass
+// as a value whose SOLE use is its own extension — nothing can read the raw register, which is
+// exactly what a narrow declaration means. Recovered as a wide parameter instead, the same function
+// has to re-spell `(u8)a` at every use; agbcc then elides an extension no use needs, gives the
+// extended value no register of its own, and the whole allocation moves.
+//
+// WIDTH AND SIGNEDNESS ARE READ OFF, NOT GUESSED: the extension states both (agbcc's shift pair by
+// its amount and its `asr`/`lsr`, PPC's by the opcode), so no width is ever enumerated here.
+//
+// NOT agbcc-GATED, because the shape is not agbcc's alone: mwcc's PPC prologue widens a declared
+// narrow parameter with the `extsb`/`extsh` the frontend lifts to the same op, and the synthetic
+// `sextb`/`tos8` rows keep matching on that toolchain through this pass.
+//
+// WHAT THE PROLOGUE TEST CANNOT SEE, and why the declaration settles it. The scan steps over the
+// pure materializations agbcc interleaves among the extensions, so a constant the scheduler HOISTED
+// above a mid-body cast leaves `pb` looking like `pa`:
+//
+//     void pc(s32 a, s32 *out) { s32 t = 7; out[0] = (u8)a; out[1] = t; out[2] = t; }
+//         movs r2,#7 / lsls r0,#24 / lsrs r0,#24 / str / str / str
+//     void pc(u8 a, s32 *out)  { s32 t = 7; out[0] = a;     out[1] = t; out[2] = t; }
+//         lsls r0,#24 / lsrs r0,#24 / movs r2,#7 / str / str / str
+//
+// Those two ROM sources are DIFFERENT BYTES — the const moves across the shift pair — so the width
+// is a fact here and not a spelling, while no reader of the raw register and no body code is
+// present to make the gates below refuse. Nor does the ORDER decide it: sa3's `sub_802DFC8` really
+// is declared `s16 direction` and agbcc emits its `movs r5, #0` before the `lsl/asr` too, so the
+// hoisted-const shape arrives from both source spellings and reaches this pass as the same IR.
+//
+// The tiebreak is therefore not in the asm, and the SCORE cannot supply it either: asmlift
+// re-materializes a small constant at each use instead of binding it to a local, so its own two
+// spellings of `pc` emit the same instruction order and score alike. `proto-width` takes the
+// tiebreak from the caller's declaration instead, and where none was supplied the extension stands.
+// What that refusal protects is a function this pass never compiles: agbcc truncates at every
+// PROTOTYPED CALL SITE of a narrow-declared callee — `lsl/asr` ahead of the `bl`, two Thumb
+// instructions per site — so a wrong width here costs bytes the per-function differ cannot see.
+//
+// FUSED BEHIND A POOL LOAD. The prologue scan steps over a pool-loaded address, and a body cast
+// with nothing else ahead of it — `gB = gW[(u8)a]` is `ldr r2,=gB / ldr r1,=gW / lsl r0,#24 /
+// lsr r0,#22` — reaches it looking like a declaration once raise/extscale.ts has re-split the fused
+// pair. The fold knows where the machine put that `lsl` and records it (`ScaleRecord.behindPool`),
+// and `fused-behind-pool` reads the record: an unsigned declared parameter's `lsl` precedes every
+// pool load in the benchmark's agbcc references (extscale.ts's header has the census). Only the
+// fold's own extensions are judged this way; a plain cast's extension sits at its right shift,
+// where its position says nothing about its `lsl`'s.
+import { type Fn, type Op, type Value, replaceAllUsesWith, successorsOf } from '../ir/core';
+import { CAST_WIDTHS, MATERIALIZING_OPS } from '../ir/opcodes';
+import { T } from '../ir/types';
+import { type Gate, firstRejection } from '../l3/gates';
+import { type FnProto, declaredWidth } from '../proto';
+
+/** What the gates below judge: one entry parameter and the extension that reads it. */
+export interface NarrowParamCandidate {
+  /** the parameter the extension reads */
+  param: Value;
+  /** the extension's `width` attribute */
+  width: number;
+  /** the entry block has predecessors */
+  entryIsJoin: boolean;
+  /** the extension is in the entry block's PROLOGUE — see the scan in `narrowEntryParams` */
+  inPrologue: boolean;
+  /** reads of the RAW parameter anywhere in the function */
+  uses: number;
+  /** the width the caller's own prototype declares for this parameter, if it declares one */
+  declared: number | undefined;
+  /** the extension is one raise/extscale.ts re-split from a fused pair whose `shl` the machine ran
+   *  behind a pool load — see FUSED BEHIND A POOL LOAD */
+  fusedBehindPool: boolean;
+}
+
+export const PARAM_WIDTH_GATES: readonly Gate<NarrowParamCandidate>[] = [
+  {
+    id: 'entry-is-join',
+    why: "a joined entry's params are merge values, not the function's arguments",
+    sound: true,
+    guardedBy: 'param-width.test.ts: an entry block with a predecessor carries merge values, not arguments',
+    rejects: (c) => c.entryIsJoin,
+  },
+  {
+    id: 'param-typed',
+    why: 'the pointer/aggregate recovery already decided this parameter',
+    sound: true,
+    guardedBy: 'param-width.test.ts: a parameter the pointer recovery already typed is left alone',
+    rejects: (c) => c.param.type.kind !== 'unknown',
+  },
+  {
+    id: 'cast-width',
+    why: 'only 8 and 16 are widths a `zext`/`sext` — and so a C declaration — carries',
+    sound: true,
+    guardedBy: 'param-width.test.ts: a width no C type spells is refused',
+    rejects: (c) => !CAST_WIDTHS.has(c.width),
+  },
+  {
+    id: 'raw-reader',
+    why: 'a reader of the un-extended register proves the declaration was wide',
+    sound: true,
+    guardedBy: 'param-width.test.ts: a second reader of the raw parameter proves the declaration was wide',
+    rejects: (c) => c.uses !== 1,
+  },
+  {
+    id: 'proto-width',
+    why: "the caller's headers declare this parameter, and a declaration outranks an inference",
+    sound: true,
+    guardedBy: 'param-width.test.ts: a declared width the extension contradicts refuses the narrowing',
+    rejects: (c) => c.declared !== undefined && c.declared !== c.width,
+  },
+  {
+    id: 'not-prologue',
+    why: 'an extension behind body code is where the SOURCE wrote the cast',
+    sound: true,
+    guardedBy: 'param-width.test.ts: an extension behind a nullary call is body code',
+    rejects: (c) => !c.inPrologue,
+  },
+  {
+    id: 'fused-behind-pool',
+    why: 'a fused cast behind a pool load is body code if unsigned, and either width is the same object if signed',
+    sound: true,
+    guardedBy: 'extscale.test.ts: a body cast behind nothing but a pool load keeps its parameter wide',
+    rejects: (c) => c.fusedBehindPool,
+  },
+];
+
+/** How many times `v` is read anywhere in `fn` — op operands and branch arguments alike. */
+function useCount(fn: Fn, v: Value): number {
+  let n = 0;
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      n += op.operands.filter((o) => o === v).length;
+      for (const s of op.successors) {
+        n += s.args.filter((a) => a === v).length;
+      }
+    }
+  }
+  return n;
+}
+
+/** Type an entry parameter at the width its prologue extension proves, and drop the extension.
+ *  `self` is the prototype the caller supplied for THIS function, if any; `fusedBehindPool` is
+ *  raise/extscale.ts's record of the extensions it re-split behind a pool load
+ *  (`ScaleRecord.behindPool`). Returns the number of parameters narrowed. */
+export function narrowEntryParams(
+  fn: Fn,
+  self?: FnProto,
+  gates: readonly Gate<NarrowParamCandidate>[] = PARAM_WIDTH_GATES,
+  fusedBehindPool: ReadonlySet<Op> = new Set(),
+): number {
+  const entry = fn.blocks[0];
+  const declared = Array.isArray(self?.params) ? self.params.map(declaredWidth) : [];
+  const entryIsJoin = fn.blocks.some((b) => successorsOf(b).includes(entry));
+  const params = new Set(entry.params);
+  // The prologue: the entry block's leading parameter extensions, plus the `MATERIALIZING_OPS`
+  // agbcc interleaves among them. Scanning stops at the first op that READS a value — body code
+  // has run by then, and an extension behind body code is where the SOURCE wrote it.
+  const prologue = new Set<Op>();
+  for (const op of entry.ops) {
+    if (MATERIALIZING_OPS.has(op.opcode)) {
+      continue;
+    }
+    if ((op.opcode !== 'sext' && op.opcode !== 'zext') || !params.has(op.operands[0])) {
+      break;
+    }
+    prologue.add(op);
+  }
+  let narrowed = 0;
+  for (const op of [...entry.ops]) {
+    if (op.opcode !== 'sext' && op.opcode !== 'zext') {
+      continue;
+    }
+    const p = op.operands[0];
+    if (!params.has(p)) {
+      continue;
+    }
+    const width = op.attrs.width as number;
+    const c: NarrowParamCandidate = {
+      param: p,
+      width,
+      entryIsJoin,
+      inPrologue: prologue.has(op),
+      uses: useCount(fn, p),
+      declared: declared[entry.params.indexOf(p)],
+      fusedBehindPool: fusedBehindPool.has(op),
+    };
+    if (firstRejection(gates, c) !== null) {
+      continue;
+    }
+    p.type = T.int(width, op.opcode === 'sext');
+    replaceAllUsesWith(fn, op.results[0], p);
+    entry.ops.splice(entry.ops.indexOf(op), 1);
+    narrowed++;
+  }
+  return narrowed;
+}

package/src/raise/pre-recovery.ts

@@ -10,25 +10,79 @@
 // rank's score-probe both verify; the report's trace entries ride pipeline's hook). The `dce` after a
 // pass that changed the IR is INTRINSIC to the pass (it declares whether it leaves dead ops) and lives
 // in the driver.
-import { Fn } from '../ir/core';
+import { Block, Fn } from '../ir/core';
 import { simplifyTrivialPhis } from '../ir/simplify';
 import { dce } from '../pattern/engine';
+import type { FnProto } from '../proto';
 import type { TargetDescription } from '../target';
 import { recognizeArrays } from './arrays';
 import { recognizeConsts } from './const';
 import { recognizeDivPow2 } from './divpow2';
+import {
+  type PoolOrder,
+  type ScaleRecord,
+  emptyScaleRecord,
+  foldScaledExtensions,
+  foldsShiftPairCasts,
+  poolOrderOf,
+  restoreUnclaimedScales,
+} from './extscale';
 import { numberPureValues } from './gvn';
 import { recognizeMagicDivision } from './magicdiv';
-import { recognizeBranchShortCircuit, recognizeShortCircuit } from './shortcircuit';
+import { recognizeMemberArrays } from './memberarrays';
+import { rerootNarrowReads } from './narrow';
+import { type MergeShape, mergeShapes, narrowBlockLocals } from './narrowlocal';
+import { PARAM_WIDTH_GATES, narrowEntryParams } from './paramwidth';
+import { type BranchShortCircuitOptions, recognizeBranchShortCircuit, recognizeShortCircuit } from './shortcircuit';
 import { recognizeSoftDiv } from './softdiv';
 import { recognizeStructArrays } from './struct-arrays';
 import { recognizeStructs } from './structs';
 
+/** Per-call options for the pass list — ONE field per pass that takes any, named for the pass, so
+ *  a caller reads which recognizer it is steering and a pass that takes none says so by absence.
+ *  A field here selects between spellings its pass can already produce; none of them relaxes a
+ *  soundness refusal, and each recognizer documents its own. */
+export interface PreRecoveryOptions {
+  /** raise/shortcircuit.ts `recognizeBranchShortCircuit` — the connective-vs-comparison-tree question. */
+  shortCircuit?: BranchShortCircuitOptions;
+}
+
+/** CFG facts read off the function ONCE, before the first pass below rewrites it.
+ *
+ *  A pass that judges the SHAPE agbcc emitted cannot read that shape off `fn` when its turn comes:
+ *  by then divpow2 has deleted a block, both short-circuit folds have rewritten edges, and the
+ *  eight `dce: true` passes have changed op counts. So the driver reads it here and hands it down. */
+export interface PreRecoveryFacts {
+  /** the join shape of every block, for raise/narrowlocal.ts's `edge-extends` and, downstream of
+   *  pre-recovery entirely, raise/retsink.ts's `pre-diamond`. Blocks a later pass creates are
+   *  absent, and absent reads as "no diamond" — the refusing direction, in both readers. */
+  mergeShapes: Map<Block, MergeShape>;
+  /** which entry-block ops the machine ran after its first pool-loaded address, for
+   *  raise/extscale.ts's behind-a-pool-load record. Read HERE because `addrnum`, the first pass,
+   *  hoists duplicated addresses to the head of the entry block and that order is gone after it. */
+  poolOrder: PoolOrder;
+  /** THE ONE FACT A PASS WRITES rather than the lift: what raise/extscale.ts's fold made, for the
+   *  two passes after it that read it — paramwidth's `fused-behind-pool` gate and
+   *  `extscale-restore`. Empty until the fold runs. */
+  scales: ScaleRecord;
+}
+
 export interface PreRecoveryPass {
   /** stable id — also the report's trace-stage key. */
   id: string;
-  /** run the recognizer; returns a truthy value (a change count, or `true`) iff it CHANGED the IR. */
-  run: (fn: Fn) => number | boolean;
+  /** run the recognizer; returns a truthy value (a change count, or `true`) iff it CHANGED the IR.
+   *  `self` is the prototype the caller supplied for the function being raised — read only by
+   *  parameter-width, which checks its inference against a declared width. `lifted` is the
+   *  pre-pass snapshot — read by narrow-local (its CFG) and scaled-extension (its entry order) —
+   *  plus the fold's record, which scaled-extension writes and parameter-width and
+   *  scaled-extension-restore read. */
+  run: (
+    fn: Fn,
+    self: FnProto | undefined,
+    opts: PreRecoveryOptions,
+    target: TargetDescription,
+    lifted: PreRecoveryFacts,
+  ) => number | boolean;
   /** run `dce` after this pass changes the IR (the pass declares it leaves dead ops behind). */
   dce: boolean;
   /** optional target gate (soft-div only fires on a no-hardware-divide target — see raise/softdiv.ts). */
@@ -36,9 +90,10 @@ export interface PreRecoveryPass {
 }
 
 /** THE ordered pre-recovery pass list — the single source of truth shared by pipeline / rank / report.
- *  address-numbering → const-materialize → magic-division → pow2-division → soft-division → array-legalize →
- *  struct-array → struct-pointer → short-circuit → branch-short-circuit. See each recognizer's file
- *  for the rationale. */
+ *  address-numbering → const-materialize → magic-division → pow2-division → soft-division →
+ *  scaled-extension → array-legalize → struct-array → member-array → struct-pointer → short-circuit →
+ *  branch-short-circuit → narrow-reads → narrow-local → parameter-width → scaled-extension-restore.
+ *  See each recognizer's file for the rationale. */
 export const PRE_RECOVERY_PASSES: PreRecoveryPass[] = [
   // FIRST: collapsing duplicate address definitions removes block params every later recognizer
   // would otherwise have to reason around, and it can only shrink the value graph.
@@ -47,10 +102,11 @@ export const PRE_RECOVERY_PASSES: PreRecoveryPass[] = [
     // Numbering alone is not enough and not safe to ship alone: collapsing the duplicates leaves a
     // block param whose edges now all carry one value, and the structurer still destroys THAT into
     // a local (it only reuses a name a carrier already has, and an inlined `gaddr` has none).
-    // Numbering alone costs kleod:UpdateHUDCounterDisplay its match, so the pair is the atomic
-    // unit, expressed as a body rather than a sum of two unrelated counts. It is NOT monotone,
-    // which is worth knowing before tuning either half: dropping the cleanup IMPROVES
-    // kleod:ConfigureEntityBehavior and kleod:CountCollectedGems, neither of them near matching.
+    // Numbering alone cost kleod:UpdateHUDCounterDisplay its match (measured on kleod's
+    // kl-eod-decomp rows, retired 2026-09-13), so the pair is the atomic unit, expressed as a body
+    // rather than a sum of two unrelated counts. It was NOT monotone, which is worth knowing before
+    // tuning either half: dropping the cleanup IMPROVED kleod:ConfigureEntityBehavior and
+    // kleod:CountCollectedGems, neither of them near matching then.
     run: (fn) => {
       const n = numberPureValues(fn);
       return n + simplifyTrivialPhis(fn);
@@ -66,37 +122,128 @@ export const PRE_RECOVERY_PASSES: PreRecoveryPass[] = [
   // beside magicdiv so that a reader looking for division recovery finds both together.
   { id: 'divpow2', run: recognizeDivPow2, dce: true },
   { id: 'softdiv', run: (fn) => recognizeSoftDiv(fn), dce: false, gate: (t) => !t.capabilities.hwDivide },
+  // AFTER `const`, which folds a shift pair over a constant to the constant it computes, and BEFORE
+  // the three array recognizers, whose input this pass produces: `shl(ext(x), k)` is an element
+  // scale they legalize and the fused pair is not. `dce: true` — the `shl` a fold leaves readerless.
+  // It reads `lifted.poolOrder`, the entry block's order before `addrnum` hoisted its addresses,
+  // and writes `lifted.scales`.
+  {
+    id: 'extscale',
+    run: (fn, _self, _opts, _target, lifted) => foldScaledExtensions(fn, lifted.poolOrder, lifted.scales),
+    dce: true,
+    gate: foldsShiftPairCasts,
+  },
   { id: 'arrays', run: recognizeArrays, dce: true },
   // struct-arrays AFTER arrays (scalar stride==width shapes are claimed first — see the
   // discriminator note in raise/struct-arrays.ts) and BEFORE structs (an element's field
   // accesses must not be re-derived as constant-offset struct-pointer accesses).
   { id: 'struct-arrays', run: recognizeStructArrays, dce: true },
+  // member-arrays AFTER struct-arrays, and that order IS load-bearing — but the order alone does
+  // not deconflict them, because the two passes claim different VALUES: struct-arrays types the
+  // materialized `add(P, K)` and member-arrays groups on `P`, so `P->tbl[i].f` reaches both. What
+  // deconflicts them is member-arrays' `claimed-access` gate, reading the marks struct-arrays
+  // leaves. Its position before `structs` is NOT load-bearing — a base carrying both of THOSE
+  // shapes is refused on either side (`direct-access` here, the `unknown` check there) — and it
+  // sits there so the three struct synthesizers read in the order of their evidence. `narrowlocal`
+  // reads the carrier's extension chain rather than any address, so nothing here orders against it.
+  { id: 'member-arrays', run: (fn) => recognizeMemberArrays(fn), dce: true },
   { id: 'structs', run: recognizeStructs, dce: false },
   { id: 'shortcircuit', run: recognizeShortCircuit, dce: true },
-  // The control-flow sibling, and this order IS load-bearing — value form FIRST.
+  // The control-flow sibling, value form FIRST.
   //
   // Their input SHAPES are disjoint (the value form's second block ends in `br` carrying a phi
-  // argument, this one's ends in `cond_br`), so neither can eat the other's literal pattern. But
-  // this pass REWRITES its head's condition into a `logic_or`/`logic_and`, and the value form
-  // refuses any head whose condition is not a negatable icmp — so running this one first can
-  // permanently disqualify a value fold that was available. The reverse cannot happen: the value
-  // form replaces its head's `cond_br` with a `br`, which this pass never matches.
-  { id: 'branch-shortcircuit', run: recognizeBranchShortCircuit, dce: true },
+  // argument, this one's ends in `cond_br`), so neither can eat the other's literal pattern. The
+  // order is not otherwise load-bearing: this pass REWRITES its head's condition into a
+  // `logic_or`/`logic_and`, and the value form takes a fused head — both siblings negate a
+  // connective by De Morgan (`negateCondOps`, raise/shortcircuit.ts). Running this one first can
+  // still cost a value fold wherever that helper refuses the fused cone (a non-negatable leaf, or a
+  // cone over its budget), but instrumenting the value form's head gate over the benchmark corpus
+  // counts 0 fused heads across the 782 rows that lift map-lessly, so the hazard has no producer
+  // there. The reverse direction never could: the value form replaces its head's `cond_br` with a
+  // `br`, which this pass never matches.
+  // The `target` argument is read by ONE conjunct of ONE gate, as at `narrowlocal` below:
+  // `read-behind-effect`'s "a local costs a second load", compiled on all five bench toolchains and
+  // true on agbcc alone (raise/shortcircuit.ts, target.ts `reloadsLocalReread`).
+  {
+    id: 'branch-shortcircuit',
+    run: (fn, _self, opts, target) =>
+      recognizeBranchShortCircuit(fn, {
+        ...opts.shortCircuit,
+        reloadsLocalReread: target.compilerBehaviors.reloadsLocalReread,
+      }),
+    dce: true,
+  },
+  // LAST, and the position IS load-bearing: this pass reads the CFG's edge arguments to find a
+  // loop variable's next value, and both short-circuit folds above rewrite the very edges it reads.
+  // `dce: false` — the rewrite orphans nothing, since the operand it drops keeps its other use.
+  { id: 'narrow', run: rerootNarrowReads, dce: false },
+  // The two WIDTH passes, last of the recognizers and in either order relative to each other: each
+  // only DELETES an extension and retypes the parameter that fed it, so every recognizer above sees
+  // the shape it was written against and neither can match a shape the other creates. They are
+  // disjoint by construction — `narrowlocal` refuses an entry parameter, `paramwidth` reads only
+  // entry parameters — and `narrowlocal` cannot take an extension `narrow` above wants either, since
+  // a parameter carrying BOTH a `zext` and a `sext` has two readers and is refused.
+  // `dce: false` on both — the extension each drops is spliced out in place, and its result has no
+  // other reader.
+  // The `target` argument is read by ONE conjunct of ONE gate — see raise/narrowlocal.ts's
+  // `NarrowLocalOptions`. A whole-pass `gate` would be wrong: the pass's SOUND rules are claims
+  // about C and run everywhere; only the join-shape evidence is a claim about gcc 2.x's optimizer.
+  // That same conjunct is why it reads `lifted.mergeShapes`: every pass above it can rewrite the
+  // CFG whose shape it judges.
+  {
+    id: 'narrowlocal',
+    run: (fn, _self, _opts, target, lifted) =>
+      narrowBlockLocals(
+        fn,
+        undefined,
+        { hoistsSingleSetArm: target.compilerBehaviors.hoistsSingleSetArm },
+        lifted.mergeShapes,
+      ),
+    dce: false,
+  },
+  {
+    id: 'paramwidth',
+    run: (fn, self, _opts, _target, lifted) => narrowEntryParams(fn, self, PARAM_WIDTH_GATES, lifted.scales.behindPool),
+    dce: false,
+  },
+  // LAST, after every pass that can CLAIM what `extscale` exposed — the two width passes above take
+  // an extension, the array recognizers a scale. What none of them took goes back to the pair the
+  // frontend lifted (raise/extscale.ts, WHAT NOBODY CLAIMED). `dce: true` — the extension it leaves
+  // readerless.
+  {
+    id: 'extscale-restore',
+    run: (fn, _self, _opts, _target, lifted) => restoreUnclaimedScales(fn, lifted.scales),
+    dce: true,
+    gate: foldsShiftPairCasts,
+  },
 ];
 
 /** Run the pre-recovery passes in order. For each pass whose gate passes and that CHANGES the IR, run
  *  `dce` when the pass declares it, then invoke `afterPass(pass, result)` (the caller's verify/trace
- *  hook), if given. */
+ *  hook), if given.
+ *
+ *  RETURNS the facts it read, because a pass AFTER pre-recovery needs one of them too:
+ *  `raise/retsink.ts`'s `pre-diamond` asks whether a return merge was a diamond in the ROM, and
+ *  by its turn `raise/shortcircuit.ts` has manufactured diamonds that were not. The map is the
+ *  driver's to compute — it is the only place that sees `fn` before the first pass — so handing it
+ *  back is cheaper and truer than recomputing something later that cannot be recomputed. */
 export function runPreRecovery(
   fn: Fn,
   target: TargetDescription,
   afterPass?: (pass: PreRecoveryPass, result: number | boolean) => void,
-): void {
+  self?: FnProto,
+  opts: PreRecoveryOptions = {},
+): PreRecoveryFacts {
+  const lifted: PreRecoveryFacts = {
+    mergeShapes: mergeShapes(fn),
+    poolOrder: poolOrderOf(fn),
+    scales: emptyScaleRecord(),
+  };
   for (const pass of PRE_RECOVERY_PASSES) {
     if (pass.gate && !pass.gate(target)) {
       continue;
     }
-    const result = pass.run(fn);
+    const result = pass.run(fn, self, opts, target, lifted);
     if (result) {
       if (pass.dce) {
         dce(fn);
@@ -104,4 +251,5 @@ export function runPreRecovery(
       afterPass?.(pass, result);
     }
   }
+  return lifted;
 }

package/src/raise/recover.ts

@@ -12,13 +12,30 @@ const UNSIGNED_CMP = new Set(['icmp_ult', 'icmp_ule', 'icmp_ugt', 'icmp_uge']);
 const SIGNED_DIV = new Set(['sdiv', 'smod']);
 const UNSIGNED_DIV = new Set(['udiv', 'umod']);
 
+/** Type an as-yet-untyped value as an integer of its own width. Only `unknown`s: a value some
+ *  earlier rule already typed keeps that answer, so the phases below compose without an order
+ *  between the rules INSIDE one of them. */
+function setInt(v: Value, signed: boolean): void {
+  if (v.type.kind === 'unknown') {
+    v.type = T.int(v.type.width, signed);
+  }
+}
+
+/** The four phases, in the one order they are sound in: seed signedness from the opcodes that carry
+ *  it, type the bases of memory accesses as pointers, propagate that pointer-ness across the SSA,
+ *  then default whatever is left. Each is in place over `fn`, and each depends on the previous one
+ *  having already refused to overwrite a type — the pointer phases must run BEFORE the s32 default
+ *  or a loop-carried pointer is flattened to an integer. */
 export function recoverTypes(fn: Fn): void {
-  const setInt = (v: Value, signed: boolean) => {
-    if (v.type.kind === 'unknown') {
-      v.type = T.int(v.type.width, signed);
-    }
-  };
-  // Seed: operands of a signed comparison are signed integers.
+  seedSignednessFromOpcodes(fn);
+  typeDerefBases(fn);
+  propagatePointers(fn);
+  defaultUnknownsToS32(fn);
+}
+
+/** PHASE 1 — signedness from op semantics: the operands of a signed comparison are signed integers,
+ *  a comparison's result is a bool, and a division carries its signedness in the OPCODE. */
+function seedSignednessFromOpcodes(fn: Fn): void {
   for (const b of fn.blocks) {
     for (const op of b.ops) {
       if (SIGNED_CMP.has(op.opcode)) {
@@ -52,12 +69,14 @@ export function recoverTypes(fn: Fn): void {
       }
     }
   }
-  // A value used as the base of a memory access is a pointer; its pointee type comes from the
-  // access width (and, for loads, signedness). This must run before the s32 default so the
-  // base is typed `T *` rather than being flattened to a plain integer. Both the constant-offset
-  // forms (load/store, width) and the variable-index forms (aload/astore, elemSize) type their
-  // base operand[0]; only the scale attribute differs.
+}
 
+/** PHASE 2 — a value used as the base of a memory access is a pointer; its pointee type comes from
+ *  the access width (and, for loads, signedness). This must run before the s32 default so the base
+ *  is typed `T *` rather than being flattened to a plain integer. Both the constant-offset forms
+ *  (load/store, width) and the variable-index forms (aload/astore, elemSize) type their base
+ *  operand[0]; only the scale attribute differs. */
+function typeDerefBases(fn: Fn): void {
   for (const b of fn.blocks) {
     for (const op of b.ops) {
       let width: number, signed: boolean;
@@ -76,7 +95,9 @@ export function recoverTypes(fn: Fn): void {
           break;
         case 'astore':
           width = op.attrs.elemSize as number;
-          signed = width === 4;
+          // an astore carries no signedness of its own unless a recovery recorded the member's;
+          // structure.ts reads it by the same rule
+          signed = (op.attrs.signed as boolean | undefined) ?? width === 4;
           break;
         default:
           continue;
@@ -87,16 +108,16 @@ export function recoverTypes(fn: Fn): void {
       }
     }
   }
-  // Propagate pointer-ness across the SSA. The seed above types only the DIRECT base of a dereference;
-  // a loop-carried pointer reaches its dereference through a block-arg phi (its incoming `a0`) and a
-  // `p = p + stride` walk, so those values stay `unknown` and the s32 default below would spell them
-  // `int` — an `int→int*` assignment mwcc/agbcc REJECT (gcc warns). Flow the pointer type across the
-  // exact same-value edges (a phi is one value; `ptr ± const` is the same pointer type). Union-find over
-  // Value identity. SOUND: every edge connects values that provably hold the same pointer, and we only
-  // fill `unknown`s — a class with a conflicting int member or two distinct pointees is left untouched.
-  propagatePointers(fn);
-  // Default every still-unknown value to s32. This is a COMPILER default (agbcc/IDO/GCC all take
-  // plain `int` as the integer default), not a hardware fact — applied uniformly.
+}
+
+// PHASE 3 is `propagatePointers` (below, with its own note). Phase 2 types only the DIRECT base of
+// a dereference; a loop-carried pointer reaches its dereference through a block-arg phi (its
+// incoming `a0`) and a `p = p + stride` walk, so those values stay `unknown` and phase 4 would
+// spell them `int` — an `int→int*` assignment mwcc/agbcc REJECT (gcc warns).
+
+/** PHASE 4 — default every still-unknown value to s32. This is a COMPILER default (agbcc/IDO/GCC
+ *  all take plain `int` as the integer default), not a hardware fact — applied uniformly. */
+function defaultUnknownsToS32(fn: Fn): void {
   for (const b of fn.blocks) {
     for (const p of b.params) {
       if (p.type.kind === 'unknown') {
@@ -225,7 +246,19 @@ export function returnType(fn: Fn): IrType {
     const term = b.ops[b.ops.length - 1];
     if (term?.opcode === 'ret' && term.operands.length > 0) {
       const v = term.operands[0];
-      return v.type.kind === 'unknown' ? T.s(32) : v.type;
+      // A NARROW value in the return register does not make the DECLARED return type narrow: the
+      // register is a word, and the value's width says how it was COMPUTED, not what the header
+      // spelled. The two readings compile alike through agbcc and do NOT through mwcc —
+      // `s8 f(s8 x) { return x; }` drops the `extsb` that `s32 f(s8 x) { return x; }` keeps and the
+      // target has (synthetic `sextb`/`tos8`).
+      //
+      // The widening lands on `s32`, the same fallback an untyped return takes, rather than on the
+      // value's own signedness: a `zext` states what the ARGUMENT was declared as, which is no
+      // evidence about the header's return type — and `u32 f(u8 x){return x;}` and its `s32` twin
+      // are one `lsl/lsr/bx lr` through agbcc either way. A narrowed PARAMETER
+      // (raise/paramwidth.ts) is the only value that reaches here narrow: no frontend types a
+      // load's result below a word.
+      return v.type.kind === 'unknown' || (v.type.kind === 'int' && v.type.width < 32) ? T.s(32) : v.type;
     }
   }
   return T.s(32);