@asmlift/core 0.6.0 → 0.7.0

package/src/raise/const.ts

@@ -3,17 +3,33 @@
 // A RISC target builds a 32-bit literal in two halves: a high-half load (MIPS `lui`, PPC `lis`) then a
 // low-half `ori`/`addiu`. The frontends lift that pair faithfully as `or(const(hi<<16), const(lo))` /
 // `add(const(hi<<16), const(lo))` — a live binary op over two `const` ops — because neither frontend can
-// see across the two instructions. This pass folds any such const/const `or`/`add` into a single `const`,
+// see across the two instructions. This pass folds such a const/const `or`/`add` into a single `const`,
 // which is the form that (a) type-recovers as one 32-bit literal and (b) recompiles to the exact
 // `lui;ori` / `lis;ori` pair. Without it a magic-division reciprocal or an address literal is never a
 // single value the later passes can reason about.
 //
+// THE CLIENTELE IS "A VALUE THE TARGET MATERIALISES IN TWO INSTRUCTIONS", and it is wider than the
+// RISC pair above in both directions, and both halves are measured:
+//   - It is NOT ARM-free. On Thumb a literal is a pool word plus an immediate `add`, which is exactly a
+//     two-instruction materialisation and lifts as the same const/const pair. Ablating the whole pass
+//     costs three agbcc BYTE-MATCHES — `synthetic:dmafield` MATCH -> diff:29, `synthetic:fieldbase`
+//     MATCH -> diff:22, `synthetic:bgfixed` MATCH -> diff:2 (measured, whole pass off). Do not gate
+//     this pass on a RISC target.
+//   - The pair is NOT confined to ONE block. `synthetic:mergepool:gcc2.7.2kmc` lifts a genuine
+//     `lui;ori` as `or(const 65536, const 9029)` whose two halves are defined in DIFFERENT blocks
+//     (instrumented: `b0=0 b1=1`), because gcc hoisted the high half above the branch. A guard
+//     tightened to a literal same-block test loses folds the corpus depends on.
+// What the refusal below actually excludes is narrower than either: an operand a terminator hands to a
+// successor's block-parameter — a REGISTER the compiler held live across a branch — where the pair is
+// ALSO not recognisable as a hi/lo pair and the result is not an address. See its site for the cost.
+//
 // This cannot be a data-`RewritePattern`: the fold's result is COMPUTED from the two operands' values,
 // which the pattern engine's numeric-exact `attrEquals` cannot express. So it lives here as an always-on
 // recognizer, run before type recovery. Value-preserving and local; a single left-to-right pass suffices
 // (SSA guarantees each const is defined before the op that consumes it, and a folded result feeds
 // forward for any chained materialisation).
-import { Fn, Op, defOpMap, mkOp } from '../ir/core';
+import { Fn, Op, Value, defOpMap, mkOp } from '../ir/core';
+import { MEM_BASE_OPS } from '../ir/opcodes';
 
 // The binary opcodes whose const/const form is a constant. `>> 0` normalises to a signed 32-bit result
 // (hardware wraparound): `|` already yields int32, `+` may exceed it and is truncated to match `addu`/`add`.
@@ -22,11 +38,123 @@ const FOLD: Record<string, (a: number, b: number) => number> = {
   add: (a, b) => (a + b) >> 0,
 };
 
+/** Is `v` a RISC HIGH HALF — what one `lui`/`lis`/`addis` puts in a register? `hi << 16`, for a
+ *  NON-ZERO `hi`. Zero is excluded deliberately, and that exclusion is what makes this test
+ *  trustworthy as a positive: `lui rD, 0` is a no-op no compiler emits, so a `const 0` is never a
+ *  half being materialised — it is an initialised register, exactly the shape the refusal below
+ *  exists to protect.
+ *
+ *  IT COVERS THE RISC HALF OF THE CLIENTELE ONLY, because the 16/16 split is an ISA fact: censused
+ *  over the corpus's const/const fold sites, all 19 RISC ones (gcc2.7.2kmc / mwcc_242_81 / ido7.1)
+ *  are recognisable to it and 0 of the 20 agbcc ones are — an ARM pool word is an arbitrary 32-bit
+ *  value (`0x03001C00`, low half `0x1C00`) and can never pass. The ARM half of the clientele is
+ *  protected by `memBases` and by simply not being edge-carried; four agbcc sites on three rows
+ *  (`dmascope` ×2, `dmascope2`, `dmafield`'s `add(…,112)`) sit behind neither carve-out. If a row
+ *  ever needs the buy-back on ARM, the half-width belongs on the target description —
+ *  `PreRecoveryPass` already threads `target`, and `softdiv` gates on `capabilities.hwDivide` —
+ *  rather than as a second constant here. */
+const isHighHalf = (v: number): boolean => (v & 0xffff) === 0 && v !== 0;
+
+/** Is `v` a LOW HALF — what one `ori`/`addi`/`addiu` can supply? `ori` takes an UNSIGNED 16-bit
+ *  immediate and `addi`/`addiu` a SIGNED one, so the admissible range is the union: mwcc completes an
+ *  `addis` with a NEGATIVE `addi` whenever bit 15 of the low half is set (`0x12350000 + -25924` is
+ *  `0x12345ABC`). Deliberately NOT split per-opcode (`or` unsigned, `add` signed): that narrowing is
+ *  true of the ISA, reaches 0 rows of the corpus, and no fixture reddens when it is removed, so it
+ *  would be an unpinned clause. The half-width belongs on the target description if a row needs it. */
+const isLowHalf = (v: number): boolean => v >= -0x8000 && v <= 0xffff;
+
+/** The constant a foldable const/const pair denotes, or `null` when `opcode` is not one this pass
+ *  folds. Exported because `structure.ts` repairs the refusal's residue at RENDER time and must
+ *  print exactly what an unrefused fold here would have produced — the opcode set and the int32
+ *  normalisation are one decision, so they live in one place. */
+export function foldConstPair(opcode: string, a: number, b: number): number | null {
+  const f = FOLD[opcode];
+  return f ? f(a, b) : null;
+}
+
+/** Does this opcode's const/const form denote a constant? The membership half of `foldConstPair`,
+ *  for callers that must classify an op before they have its operands' values. */
+export const isConstFoldOpcode = (opcode: string): boolean => opcode in FOLD;
+
+/** THE EVIDENCE THE FOLD WOULD OTHERWISE DESTROY, stamped on the literal it produces.
+ *
+ *  Three Thumb shapes put two accesses a constant distance apart, and the assembly tells them
+ *  apart: two pool words (two independent `const` ops), one pool word plus memory-operand
+ *  displacements (`l3/ast.ts`'s `operandOff`), and one pool word plus an `add` to the register
+ *  that already held the first address (`ldr r3,=X; strh [r3]; adds r3,#2; strh [r3]`). The third
+ *  lifts as `add(const X, const 2)` — indistinguishable, once folded, from a literal `X + 2` the
+ *  compiler materialised in two instructions, which is this pass's whole clientele. So the fold
+ *  still happens and the distinction is recorded, exactly as `structure.ts` records `operandOff`
+ *  before its own fold (see the `operandOff` note in l3/ast.ts).
+ *
+ *  WHAT IT ASSERTS is narrow and is a fact about REGISTERS, not about C: at this instruction the
+ *  machine held the base address in a register, used it as an address, and advanced it by `step`
+ *  bytes to reach another address it also used. THE READER decides what to spell — `l3/advance.ts`
+ *  offers a pointer local advanced in place, which is the only C spelling that reproduces the
+ *  `add` on a compiler that folds a constant subscript into the memory operand, and which is
+ *  INERT (same bytes as the subscript) wherever the pointee is not `volatile`.
+ *
+ *  THE THREE REFUSALS, each of which makes the stamp mean something else:
+ *   • `or`, not `add` — a hi/lo `or` is a literal being assembled, never a pointer being moved.
+ *   • the ADDEND is itself a memory base. Then both halves are addresses and neither is the step;
+ *     the shape is not an advance and the stamp would name an arbitrary one of them.
+ *   • either the base or the result is never used AS AN ADDRESS. A register that only feeds
+ *     arithmetic is a value, and `X + 2` over two values is a literal by every reading.
+ *  A zero step is dropped too: it names no advance, and `l3/ast.ts`'s readers all test
+ *  `!== undefined` rather than truthiness, so a stamped 0 would read as a real one. */
+function advanceEvidence(op: Op, a: number, c: number, memBases: ReadonlySet<Value>): { advancedBy?: number } {
+  if (op.opcode !== 'add' || !memBases.has(op.results[0])) {
+    return {};
+  }
+  const baseIdx = memBases.has(op.operands[0]) ? 0 : memBases.has(op.operands[1]) ? 1 : -1;
+  if (baseIdx < 0 || memBases.has(op.operands[1 - baseIdx])) {
+    return {};
+  }
+  const step = baseIdx === 0 ? c : a;
+  return step === 0 ? {} : { advancedBy: step };
+}
+
 /** Fold each const/const `or`/`add` into one `const`, in place. Returns whether anything changed. The
  *  now-dead source consts are left for DCE (they may still have other uses; liveness is not our concern). */
 export function recognizeConsts(fn: Fn): boolean {
   let changed = false;
   const defs = defOpMap(fn);
+  // The two facts the CLIENTELE REFUSAL below reads, both collected in one walk.
+  //   `edgeSlots` — for every value a terminator hands to a successor, WHICH block-parameters it
+  //     feeds. Being in the map at all is "a register the compiler held live across a branch": in
+  //     functional-form SSA the machine had this value in a register at the branch and the join
+  //     reads it back. WHICH parameter is the second question, and the buy-back below needs it.
+  //   `memBases`  — every value used as a memory base, i.e. the values that ARE addresses.
+  const edgeSlots = new Map<Value, Set<Value>>();
+  const memBases = new Set<Value>();
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      for (const sc of op.successors) {
+        sc.args.forEach((v, i) => {
+          const param = sc.block.params[i];
+          if (param === undefined) {
+            return;
+          }
+          const slots = edgeSlots.get(v);
+          if (slots) {
+            slots.add(param);
+          } else {
+            edgeSlots.set(v, new Set([param]));
+          }
+        });
+      }
+      if (MEM_BASE_OPS.has(op.opcode) && op.operands.length > 0) {
+        memBases.add(op.operands[0]);
+      }
+    }
+  }
+  /** Do these two values reach the SAME block-parameter — i.e. are they two arms' feeds of one
+   *  merge? See the refusal for why that is what tells an accumulator from a shared high half. */
+  const meetAtSameParam = (x: Value, y: Value): boolean => {
+    const sx = edgeSlots.get(x);
+    const sy = edgeSlots.get(y);
+    return !!sx && !!sy && [...sx].some((k) => sy.has(k));
+  };
   const constOf = (op: Op | undefined): number | null =>
     op && op.opcode === 'const' ? (op.attrs.value as number) : null;
   for (const b of fn.blocks) {
@@ -41,8 +169,80 @@ export function recognizeConsts(fn: Fn): boolean {
       if (a === null || c === null) {
         continue;
       }
+      // ── THE REFUSAL: this shape is not a literal being materialised ───────────────────────────
+      // An operand a terminator ALSO hands to a successor's block-parameter is a register the compiler
+      // held live across the branch, whose value on this path happens to be a constant. agbcc's
+      // `s = 0; ... if (c) s += 1;` lifts as `add(%s = const 0, const 1)` in the taken arm, where
+      // `%s` is also the value bb0 hands the join. Folding it to `const 1` deletes the accumulator's
+      // last reference, so every later level sees an arm that materialises a literal and spells it
+      // as one (`v = 1;` with an `else v = 0;`) instead of the `s += 1` the target records — and the
+      // enumeration gate for the shipped `/merge-home` variation, which is what would have spelled the
+      // hoisted init, reads FALSE because the merge feed it looks for is gone.
+      //
+      // The mapping is a FUNCTION, not an open question, so this is a default and not a variation: a register
+      // carried across a branch is not a literal being materialised, whichever compiler produced it.
+      //
+      // IT IS A PROXY, and the two carve-outs are where it is bought back. Edge-carrying is evidence
+      // of a register, not proof, and the same `add(const 0, const K)` still folds wherever nothing
+      // carries the zero (6 sites on 5 marioparty3/snowboardkids2 rows) — defensible, since with no
+      // merge there is no home to hoist and the incident cannot occur, but the rule is narrower than
+      // "never fold a const/const pair over a branch".
+      //   - `hiLoPair` — the pass's OWN clientele beats the proxy. mwcc materialises `0x12345678` as
+      //     `lis; addi` and shares the `lis` across a branch whenever the high half is live at the
+      //     join, so the genuine pair IS edge-carried and the proxy refuses it: measured, a
+      //     `base = 0x12340000; if (c) q[0] = base|0x5678; else q[1] = base|0x9ABC; *p = base;` row
+      //     emitted `*a2 = 305397760 + 22136;` on mwcc_242_81 where every other toolchain emitted the
+      //     folded literal. The literal is then no longer ONE value for `recognizeMagicDivision`, type
+      //     recovery or the symbol map — the same never-enumerated failure this refusal exists to fix,
+      //     one level down.
+      //
+      //     `feedsSameMerge` IS A CONDITION ON THAT BUY-BACK: read as a bare "is this a hi/lo pair"
+      //     it re-opens the very incident this refusal exists for. An accumulator's `const 0` init
+      //     passes `isLowHalf`, so `s = 0; if (c) s += 0x10000;` — one 16.16 fixed-point step — is a
+      //     hi/lo pair by the letter of the test, and its MIRROR `s = 0x10000; if (c) s += 1;` is
+      //     one whichever operand is read as the half. Folded, a two-arm `s += 0x10000` row scores
+      //     **diff:1** on mwcc_242_81 with `hasMergeFeedHome` FALSE; refused, **MATCH** with the
+      //     gate TRUE. What separates the two shapes is WHERE THE VALUES GO rather than their bit
+      //     patterns: an accumulator's init and its updated copy are two arms' feeds of ONE block
+      //     parameter — exactly the merge `/merge-home` exists to home — whereas a shared high half
+      //     reaches the join while the COMPLETED literal is stored or returned, never merged with
+      //     the half it was built from. Measured FREE: with it in, 770 synthetic + 252 real rows are
+      //     byte-identical in post-recovery IR, in emitted source and in gap list to the branch
+      //     without it.
+      //   - `memBases` — an address literal, `0x03001C00 + 1206` reached through one arm's base
+      //     register. It decides 0 folds over the corpus's 806 lifted rows and is here as a
+      //     statement of scope; `hiLoPair` is the clause that carries real traffic. Deliberately NOT
+      //     transitive and NOT extended to call arguments: an address literal escaping as a call
+      //     argument is a shape the refusal HELPS (a probe row scored diff:7 -> MATCH with it
+      //     firing), so widening this test would give that back.
+      //
+      // NOT CONVERTIBLE TO A `Gate` TABLE, and the reason is the type rather than the minutes.
+      // `firstRejection` reads a table as a DISJUNCTION of independent refusals; the test below is
+      // a CONJUNCTION with two buy-backs, and "refuse unless exempted" decomposes only by making
+      // every term re-carry the whole conjunction. The census would then report one opaque id and
+      // stay silent about WHICH exemption fired — the only question the paragraphs above ask. Said
+      // here because a selector that ranks passes by refusal count or by instrument minutes points
+      // at this file (`grep -n "raise/const.ts" docs/level-tower.md`), and both readings are wrong
+      // about it for different reasons.
+      //
+      // A REFUSAL IS ALSO A SCHEDULING DECISION, and that coupling is invisible at this site:
+      // `pre-recovery.ts` registers this pass `dce: true` and runs `dce(fn)` only when the pass
+      // returns TRUTHY, so a function whose ONLY const/const pair is refused gets no DCE here at
+      // all — and `addrnum` above is `dce: false`, so this is the first pass that can schedule one.
+      // Measured inert: forcing the cancelled `dce(fn)` removes 0 ops on every invocation of every
+      // reachable row (`sinkacc`, 3 invocations). Worth knowing before this refusal is widened.
+      const edgeCarried = edgeSlots.has(op.operands[0]) || edgeSlots.has(op.operands[1]);
+      const feedsSameMerge =
+        meetAtSameParam(op.results[0], op.operands[0]) || meetAtSameParam(op.results[0], op.operands[1]);
+      const hiLoPair = ((isHighHalf(a) && isLowHalf(c)) || (isHighHalf(c) && isLowHalf(a))) && !feedsSameMerge;
+      if (edgeCarried && !hiLoPair && !memBases.has(op.results[0])) {
+        continue;
+      }
       // Reuse the SAME result Value → every existing use already points at it (no RAUW needed).
-      const folded = mkOp('const', { results: [op.results[0]], attrs: { value: fold(a, c) } });
+      const folded = mkOp('const', {
+        results: [op.results[0]],
+        attrs: { value: fold(a, c), ...advanceEvidence(op, a, c, memBases) },
+      });
       b.ops.splice(i, 1, folded);
       defs.set(op.results[0], folded); // keep the def map current so a chained fold sees this const
       changed = true;

package/src/raise/divpow2.ts

@@ -31,9 +31,9 @@
 // SELF-VERIFYING. asmlift emits a plain `x / 2^k` and the target compiler regenerates ITS own
 // lowering; a wrong divisor recompiles to different bytes and shows up as a nonmatch, never as a
 // false match. The residual exposure is a lost match, not a miscompile — on a compiler that lowers
-// `/2^k` branchlessly, a diamond of this shape came from hand-written biasing, and respelling it
+// `/2^k` branchlessly, a diamond of this shape came from hand-written biasing, and rewriting it
 // costs a match that used to land. Measured positive on ido7.1 (two flips), agbcc and gcc2.7.2kmc
-// (modpow2 stays byte-exact through the respelling); mwcc_242_81 and gcc2.7.2 have no inhabitant, so
+// (modpow2 stays byte-exact through the rewrite); mwcc_242_81 and gcc2.7.2 have no inhabitant, so
 // they are unmeasured rather than clean.
 //
 // It is deliberately IDENTITY-OR-DECLINE about the shape (the bias constant must be exactly

package/src/raise/extscale.ts

@@ -0,0 +1,342 @@
+// A NARROWING EXTENSION FUSED WITH THE LEFT SHIFT THAT SCALES IT.
+//
+// agbcc lowers `(u8)x` to a shift pair, `lsl #24; lsr #24` (the CAST_PATTERNS idiom,
+// pattern/engine.ts). Scale the narrowed value and gcc's combiner merges the right half of the pair
+// with the scale, so `(u8)x << 3` is TWO instructions, not three:
+//
+//     lsl  r0, r0, #0x18        %1 = shl %x {imm=24}
+//     lsr  r0, r0, #0x15        %2 = shr_u %1 {imm=21}      == zext8(x) << 3
+//
+// Exactly: `(x << L) >>u R` for `0 < R < L` keeps x's low `32 - L` bits and lands them at bit
+// `L - R`, which is `zext(x, 32 - L) << (L - R)`; `>>s` is the same with `sext`. What the fold buys
+// is the two facts the raw pair hides from every pass below — and ONLY those: the spelling it
+// prints when neither is claimed is not byte-neutral, so that spelling never ships (WHAT NOBODY
+// CLAIMED, below):
+//
+//   • THE WIDTH. A declared `u8 idx` is extended in the prologue, and that extension is what
+//     raise/paramwidth.ts reads to type the parameter. When the extension is fused, the prologue
+//     holds a bare `shl` instead: paramwidth sees no extension of this parameter, AND its prologue
+//     scan stops at that `shl`, so every LATER parameter's extension reads as body code too. Typed
+//     `u32`, the function recompiles with both shifts at the use and the whole schedule moves.
+//   • THE SCALE. `shl(ext(x), k)` is the element-scaled index raise/arrays.ts and
+//     raise/struct-arrays.ts legalize; `shr_u(shl(x, 24), 21)` is an opaque byte offset to both.
+//
+// WHERE THE EXTENSION GOES is the one real decision here, and it is read off the machine, not
+// chosen. The two halves of the pair are not scheduled together. Compiled with this benchmark's
+// agbcc, the same body over a narrow and a wide parameter:
+//
+//     void pa(u8 a, u8 b)  { gA |= 4; gB = (u32)&gT + a * 4;      gC = b; }
+//         lsl r0,#24 / lsl r1,#24 / lsr r1,#24 / …body… / lsr r0,#22 / add …
+//     void pb(u32 a, u8 b) { gA |= 4; gB = (u32)&gT + (u8)a * 4;  gC = b; }
+//         lsl r1,#24 / lsr r1,#24 / …body… / lsl r0,#24 / lsr r0,#22 / add …
+//
+// The declaration's extension starts in the prologue and only its SECOND half is merged into the
+// use; a cast in the body is lowered at the use, both halves together. So the extension is placed
+// where its `shl` stood and the scale where the right shift stood: a prologue `lsl` yields a
+// prologue extension, which paramwidth's own gates then judge. Those gates keep a body cast wide
+// only when body code that READS a value comes first — `not-prologue` steps over materializations,
+// a pool-loaded address among them — which is why the fold records a pair it finds behind one
+// (THE BODY CAST BEHIND A POOL LOAD, below). Placing both at the right shift instead throws `pa`'s
+// prologue evidence away, so `pa` reads as `pb` and stays wide — measured on the benchmark's sa3
+// rows whose first parameter is a declared `u8` scaled this way:
+// `sa2__sub_8007858` 39/60 anchored against 44/61 at the right shift, and `sa2__sub_8007958` 64/87
+// against 66/88.
+//
+// The SIGNED form does not carry that evidence on agbcc: `void pd(s16 a, …) { … a * 2 … }` and its
+// wide twin `(s16)a * 2` compile to the SAME object, both halves at the use — the ambiguity of
+// paramwidth's `pc` pair — so the placement rule is the same either way, and where the pair sits the
+// judgement is paramwidth's.
+//
+// REFUSES — the pair is left as it is — when:
+//   • `R >= L`. `R == L` is the plain cast, which CAST_PATTERNS already folded; `R > L` keeps
+//     `32 - R` bits of `x << L` and scales nothing — a bitfield EXTRACT, structure/bitfields.ts's
+//     shape — so the two readings are disjoint by the shift amounts alone;
+//   • `32 - L` is not a C cast width (8 or 16) — `lsl #28; lsr #26` is `(x & 15) << 2`, which no
+//     cast spells;
+//   • either shift is the two-register form (no `imm`) or `R` is 0;
+//   • the target is not one CAST_PATTERNS applies to. Same predicate, because the fused pair is
+//     that cast's lowering with a scale merged in: where `(u8)x` is not a shift pair (IDO and GCC
+//     `andi`), `(u8)x << k` is not one either, and a `sll; srl` there is some other arithmetic.
+//
+//   • another narrowing of the same value, at the same width and with the same SIGN, sits in the
+//     pair's block — a second right shift of a `shl(x, L)`, fused or plain, or the extension
+//     CAST_PATTERNS made of a plain one. agbcc extends a value once per block per signedness:
+//     `p[(u8)a * 4] = 1; return (u8)a;` is one `lsl #24; lsr #24` and a `lsl #4` at the use, and no
+//     fused pair. So a same-sign sibling means the source wrote the shift itself —
+//
+//         u32 r6(u32 a, u32 *p) { u32 t = a << 24; p[t >> 22] = 1; return t >> 24; }
+//             lsl r0,#24 / lsr r2,r0,#20 / … / lsr r0,r0,#24
+//
+//     which folded, struct-arrays spelled `a1[(u8)a0].field_0`: objdiff 3 where the raw pair is
+//     byte-exact. Opposite signs share only the `lsl` — `p[(u8)a] = (s8)a` is `lsl #24; lsr #22 …
+//     asr #24` — and both of those ARE casts, so they fold. The test is per BLOCK because the
+//     sharing is: the same two casts in two blocks lower twice, each with its own `lsl`
+//     (`if (c) p[1] = (u8)a; return p[(u8)a];`), and the fused one folds; and a `shl` shared
+//     ACROSS blocks is a declaration too — sa3's `sub_8010184` indexes `s->hitboxes[hbIndex]`
+//     twice over an `s16 hbIndex`: one `lsl #16`, read by an `asr #13` in each of two blocks. The
+//     idiom patterns turn a plain pair into its extension in place, so the test reads the same
+//     before them as after, and raise/globalshape.ts, which reads the lift, agrees with the fold
+//     about every pair.
+//
+// THE BODY CAST BEHIND A POOL LOAD folds, and the fold records it: the pair's `shl` reads an entry
+// parameter and the machine ran it after a pool-loaded address. Compiled with this benchmark's
+// agbcc, a body cast whose only predecessors are pool loads puts nothing between them and the
+// extension that paramwidth's scan stops at, so the extension reads as a declaration:
+//
+//     void pc1(u32 a) { gB = (u32)&gT + (u8)a * 4; }     ldr r2,=gB / lsl r0,#24 / lsr r0,#22
+//
+// narrowed to `u8 a0` (objdiff 2) where the raw pair is MATCH. An UNSIGNED declared parameter's
+// `lsl` comes before any pool load, symbol or numeric: all 44 over the benchmark's agbcc
+// references. A signed one need not (27 before, 2 after): the signed form carries no placement
+// evidence (above), and its narrow and wide spellings compile to the same object. So only the
+// WIDTH is refused, by raise/paramwidth.ts's `fused-behind-pool` reading the record; the SCALE stays
+// for the array passes: `gB = gW[(u8)a]` is objdiff 2 as the raw pair and byte-exact as
+// `gW[(u8)a0]`, and sa3's `DemoPlayAlloc` (`gDemoRecordings[demoIndex]` over an `s16`) is spelled
+// as the subscript it is.
+// The order is read off the LIFTED function (`poolOrderOf`, which says why). NOT caught: a NUMERIC
+// pool word lifts to `const`, the same op a `movs` does, and paramwidth's own header says why a
+// `movs` ahead of the pair decides nothing — so a body cast behind only a numeric pool load
+// (`& 0xfff` over a wide parameter in a loop) still narrows.
+//
+// One extension per (`shl`, signedness): two folded scales of one sign off one `shl` — in two
+// blocks, `sub_8010184`'s shape — share it, and opposite signs get one each. The `shl` dies when
+// every reader was folded; one that keeps a raw reader (`p[t >> 22] = 1; return t;`) stays beside
+// the extension.
+//
+// WHAT NOBODY CLAIMED goes back (`restoreUnclaimedScales`, the last pre-recovery pass). An
+// extension no width pass took and a scale no array pass took print as `(u8)a1 << 12`, and that is
+// NOT the same object as the lifted `a1 << 24 >> 12`: straight-line they compile alike (the `pb`
+// pair above), but kleod's `SetWorldMapTilePalette` — two `u8` parameters, the first used in agbcc's
+// shifted domain so paramwidth's scan stops at its `shl` and refuses the second's extension — scores
+// 54/93 with the raw pair and 59/91 with the cast, the loop's r4/r6 allocation swapped. So every
+// scale the fold made that still reads its extension is rewritten in place to the pair it replaced;
+// what survives the pass is exactly what a consumer claimed, and everywhere else the output is the
+// one the lift alone produces.
+//
+// That is a decision about the DEFAULT, not a finding that the raw spelling is better: the unclaimed cast
+// has both signs. Over the 55 corpus functions the fold fires on, scored on the benchmark's own
+// path, restoring moves four scores — `SetWorldMapTilePalette` 59/91 → 54/93 and sa3
+// `UnpackSaveSector` 347 → 346 better, sa3 `ClearSave` 189 → 191 and `CompleteSave` 185 → 187
+// worse, all four to what the lift alone scores (and sa3 `ValidateSave`'s denominator, 213/378 →
+// 213/379). A spelling with both signs is the differ's to referee (a ranked variation), and none is
+// built; the default is the one that asserts nothing the lift did not.
+import { type Block, type Fn, type Op, type Value, defOpMap, mkOp, mkValue, replaceAllUsesWith } from '../ir/core';
+import { CAST_WIDTHS } from '../ir/opcodes';
+import { CAST_PATTERNS, patternApplies } from '../pattern/engine';
+import type { TargetDescription } from '../target';
+
+/** `shr_{u,s}(shl(src, L), R)` read as `ext(src, 32 - L) << (L - R)`. */
+export interface ScaledExtension {
+  /** the value being narrowed — the `shl`'s operand */
+  src: Value;
+  /** the cast width, `32 - L` */
+  width: number;
+  /** `shr_s` (sign-extend) rather than `shr_u` */
+  signed: boolean;
+  /** the scale's shift amount, `L - R` */
+  shift: number;
+  /** the `shl` — where the extension begins */
+  inner: Op;
+}
+
+/** The fused pair's SHAPE rooted at `op`, or null — the header's refusals on the amounts and the
+ *  two-register form. The sibling refusal is {@link foldablePairs}', the target's the caller's. */
+export function scaledExtensionOf(op: Op | undefined, defs: Map<Value, Op>): ScaledExtension | null {
+  if (!op || (op.opcode !== 'shr_u' && op.opcode !== 'shr_s') || op.operands.length !== 1) {
+    return null;
+  }
+  const inner = defs.get(op.operands[0]);
+  const r = op.attrs.imm;
+  const l = inner?.attrs.imm;
+  if (inner?.opcode !== 'shl' || inner.operands.length !== 1 || typeof r !== 'number' || typeof l !== 'number') {
+    return null;
+  }
+  if (!CAST_WIDTHS.has(32 - l) || r <= 0 || r >= l) {
+    return null;
+  }
+  return { src: inner.operands[0], width: 32 - l, signed: op.opcode === 'shr_s', shift: l - r, inner };
+}
+
+/** Does `target` lower a narrowing cast to a shift pair — the gate the fold shares with the cast
+ *  idiom itself. */
+export const foldsShiftPairCasts = (target: TargetDescription): boolean =>
+  CAST_PATTERNS.every((p) => patternApplies(p, target));
+
+/** Where the MACHINE put each entry-block op relative to its first pool-loaded address, read off a
+ *  function whose entry block is still in lifted order. See THE BODY CAST BEHIND A POOL LOAD. */
+export interface PoolOrder {
+  /** the function's parameters */
+  entryParams: ReadonlySet<Value>;
+  /** the entry block's ops that come after a `gaddr` */
+  afterPoolLoad: ReadonlySet<Op>;
+}
+
+/** Read {@link PoolOrder} off `fn`. Valid only BEFORE raise/gvn.ts's `addrnum` runs: that pass
+ *  hoists a duplicated address to the head of the entry block, after which a `gaddr`'s position no
+ *  longer says where the machine loaded it. The idiom patterns before it leave both a `gaddr` and a
+ *  fused pair's `shl` where they were — a plain cast's pair is folded at its right half, which is
+ *  why this fact is read for the FUSED form only. */
+export function poolOrderOf(fn: Fn): PoolOrder {
+  const entry = fn.blocks[0];
+  const afterPoolLoad = new Set<Op>();
+  let seen = false;
+  for (const op of entry?.ops ?? []) {
+    if (seen) {
+      afterPoolLoad.add(op);
+    }
+    seen ||= op.opcode === 'gaddr';
+  }
+  return { entryParams: new Set(entry?.params ?? []), afterPoolLoad };
+}
+
+/** Is `o` a narrowing of `m.src` at `m.width` with `m`'s signedness — a right shift of a
+ *  `shl(src, 32 - width)`, fused or plain, or the extension CAST_PATTERNS made of a plain one? The
+ *  answer is the same before the idiom patterns and after them: they turn a plain pair into its
+ *  extension at the pair's own position. */
+function narrowsLike(o: Op, m: ScaledExtension, defs: Map<Value, Op>): boolean {
+  if (o.opcode === (m.signed ? 'sext' : 'zext')) {
+    return o.operands[0] === m.src && o.attrs.width === m.width;
+  }
+  if (o.opcode !== (m.signed ? 'shr_s' : 'shr_u') || o.operands.length !== 1) {
+    return false;
+  }
+  const l = 32 - m.width;
+  const r = o.attrs.imm;
+  const d = defs.get(o.operands[0]);
+  return (
+    d?.opcode === 'shl' &&
+    d.operands.length === 1 &&
+    d.operands[0] === m.src &&
+    d.attrs.imm === l &&
+    typeof r === 'number' &&
+    r > 0 &&
+    r <= l
+  );
+}
+
+/** Every fused pair in `fn` AS THE FOLD TAKES IT, keyed by its right shift: the shape, minus a pair
+ *  with a same-sign sibling in its block. THE ONE READING — the fold and raise/globalshape.ts's
+ *  stride reader both ask here, and both before any pair is rewritten; a reader that took a pair the
+ *  fold leaves raw would license an element scale that no pass below legalizes. The TARGET half of
+ *  the gate is the caller's: the pass list gates the fold, and globalshape asks
+ *  {@link foldsShiftPairCasts} before it reads. */
+export function foldablePairs(fn: Fn, defs: Map<Value, Op> = defOpMap(fn)): Map<Op, ScaledExtension> {
+  const out = new Map<Op, ScaledExtension>();
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      const m = scaledExtensionOf(op, defs);
+      if (m !== null && !b.ops.some((o) => o !== op && narrowsLike(o, m, defs))) {
+        out.set(op, m);
+      }
+    }
+  }
+  return out;
+}
+
+/** What the fold made, for the two passes that read it later: raise/paramwidth.ts's
+ *  `fused-behind-pool` gate and {@link restoreUnclaimedScales}. One per pre-recovery run
+ *  (`PreRecoveryFacts.scales`), keyed by op identity. */
+export interface ScaleRecord {
+  /** each scale the fold made → the extension it reads and the pair it replaced */
+  folded: Map<Op, { ext: Op; l: number; r: number }>;
+  /** the extensions over an entry parameter whose `shl` the machine ran behind a pool load */
+  behindPool: Set<Op>;
+}
+
+export const emptyScaleRecord = (): ScaleRecord => ({ folded: new Map(), behindPool: new Set() });
+
+/** Rewrite every fused pair to `shl(ext(src), shift)`, the extension spliced in at the `shl`'s
+ *  position and the scale at the right shift's, and write what it made into `record`. Returns the
+ *  number of pairs folded; the `shl`s left without a reader are the pass driver's DCE. `order` is
+ *  the lifted-order fact the driver read before `addrnum` (`PreRecoveryFacts.poolOrder`); the
+ *  default reads it off `fn` itself, which is right only while `fn`'s entry block is still in lifted
+ *  order — a test's parsed IR. */
+export function foldScaledExtensions(
+  fn: Fn,
+  order: PoolOrder = poolOrderOf(fn),
+  record: ScaleRecord = emptyScaleRecord(),
+): number {
+  const defs = defOpMap(fn);
+  const blockOf = new Map<Op, Block>();
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      blockOf.set(op, b);
+    }
+  }
+  const exts = new Map<Op, Map<boolean, Op>>();
+  let folded = 0;
+  for (const [op, m] of foldablePairs(fn, defs)) {
+    const bySign = exts.get(m.inner) ?? exts.set(m.inner, new Map()).get(m.inner)!;
+    let ext = bySign.get(m.signed);
+    if (ext === undefined) {
+      ext = mkOp(m.signed ? 'sext' : 'zext', {
+        operands: [m.src],
+        results: [mkValue(m.inner.results[0].type)],
+        attrs: { width: m.width },
+      });
+      const home = blockOf.get(m.inner)!;
+      home.ops.splice(home.ops.indexOf(m.inner), 0, ext);
+      if (order.entryParams.has(m.src) && order.afterPoolLoad.has(m.inner)) {
+        record.behindPool.add(ext);
+      }
+      bySign.set(m.signed, ext);
+    }
+    const scaled = mkOp('shl', {
+      operands: [ext.results[0]],
+      results: [mkValue(op.results[0].type)],
+      attrs: { imm: m.shift },
+    });
+    const b = blockOf.get(op)!;
+    b.ops.splice(b.ops.indexOf(op), 1, scaled);
+    replaceAllUsesWith(fn, op.results[0], scaled.results[0]);
+    record.folded.set(scaled, { ext, l: 32 - m.width, r: 32 - m.width - m.shift });
+    folded++;
+  }
+  return folded;
+}
+
+/** Put back the machine's own pair wherever no pass below claimed what the fold exposed. Returns
+ *  the number of scales restored; an extension left without a reader is the driver's DCE.
+ *
+ *  A scale is CLAIMED when it no longer reads the fold's extension — raise/paramwidth.ts or
+ *  raise/narrowlocal.ts retyped the value and dropped the extension, so the scale now reads that
+ *  value — or when it is gone, legalized into an element index by raise/arrays.ts or
+ *  raise/struct-arrays.ts. Anything else still reads the extension, and is rewritten in place (same
+ *  result value, same position) to `shr(shl(src, L), R)`, with the `shl` where the extension stood:
+ *  the ops the frontend lifted, in the order it lifted them. */
+export function restoreUnclaimedScales(fn: Fn, record: ScaleRecord): number {
+  const shls = new Map<Op, Op>();
+  let restored = 0;
+  for (const b of fn.blocks) {
+    for (const op of [...b.ops]) {
+      const f = record.folded.get(op);
+      if (f === undefined || op.opcode !== 'shl' || op.operands[0] !== f.ext.results[0]) {
+        continue;
+      }
+      // The pair is rebuilt from the amounts RECORDED at the fold, so they must still be the ones
+      // the two ops carry: a pass that re-scaled the `shl` or re-widened the extension in place
+      // would make the recorded pair compute a different value. None does today; refuse, not guess.
+      const extended = f.ext.opcode === 'zext' || f.ext.opcode === 'sext';
+      if (!extended || f.ext.attrs.width !== 32 - f.l || op.attrs.imm !== f.l - f.r) {
+        continue;
+      }
+      let shl = shls.get(f.ext);
+      if (shl === undefined) {
+        const home = fn.blocks.find((x) => x.ops.includes(f.ext))!;
+        shl = mkOp('shl', {
+          operands: [f.ext.operands[0]],
+          results: [mkValue(f.ext.results[0].type)],
+          attrs: { imm: f.l },
+        });
+        home.ops.splice(home.ops.indexOf(f.ext), 0, shl);
+        shls.set(f.ext, shl);
+      }
+      op.opcode = f.ext.opcode === 'sext' ? 'shr_s' : 'shr_u';
+      op.operands = [shl.results[0]];
+      op.attrs = { imm: f.r };
+      record.folded.delete(op);
+      restored++;
+    }
+  }
+  return restored;
+}