@asmlift/core 0.8.0 → 0.9.0

package/src/raise/truncload.ts

@@ -0,0 +1,366 @@
+// asmlift — A NARROW READ OF A WIDER FIELD, which the struct recognizers see as a second field at
+// the same offset.
+//
+// WHAT IS MISSING WITHOUT THIS. A compiler asked for the low byte of a halfword member emits a byte
+// load at the halfword's own address:
+//
+//     BlendPalette(..., task->data[6], ...)      // data[] is s16, the parameter is u8
+//     ldrh r0, [r4, #0xc]        @ the member, read whole
+//     ldrb r2, [r4, #0xc]        @ the same member, narrowed for the call
+//
+// The pass that groups a base's constant-offset accesses reads that as ONE OFFSET AT TWO WIDTHS:
+// `raise/structs.ts` declares the pair a union member (on a parameter or a loaded pointer). That
+// reading is right about the SHAPE and wrong about the CAUSE — there is no second object here, only
+// a cast — so the function would carry a union its source never declared. (`raise/memberarrays.ts`'s
+// same-sounding `member-conflict` judges VARIABLE-INDEX accesses, `aload`/`astore`, and a base with
+// any constant-offset load is already outside that pass by `direct-access`. It is a different shape
+// and this fold does not reach it.)
+//
+// THE ASM DOES NOT SAY WHICH IT IS, and that is the point: a union, a cast, a bitfield and two
+// adjacent bytes the compiler fused all produce the same two instructions. What this pass claims is
+// narrower than any of those readings. `(u8)x` and a byte load of `x`'s low-order byte denote THE
+// SAME BYTES AND THE SAME VALUE, so rewriting one into the other invents no type and loses no
+// fidelity; what the struct recognizers then do with a base carrying one width instead of two is
+// their existing job, refereed by the differ as before.
+//
+// MEASURED, not argued, on the row that motivated it
+// (`pokeemerald:AnimTask_FlashHealthboxOnLevelUp_Step:agbcc`): the reference source declares ONE
+// `s16` member at offset 12 and passes it to a `u8` parameter, and agbcc compiles that to the
+// `ldrh`/`ldrb` pair above — `.text` sha256 `e0524eb341119a21`, 204 bytes, byte-identical to the
+// target object. So the single-field layout this pass makes reachable is the layout the ROM was
+// built from.
+//
+// WHAT IT DOES. Over the L1 fn, for every base with constant-offset accesses: a LOAD whose byte
+// range is the LOW-ORDER END of a strictly wider access's range at the same base becomes a
+// `zext`/`sext` — matching the narrow load's own signedness — of a fresh load at the wider range.
+// No opcode, no representation, no level: `zext`/`sext` with a `width` attr already exist
+// (`ir/opcodes.ts`), they already print as a C cast, and the backend already recompiles that cast
+// to the narrow instruction on the compilers that emit it.
+//
+// THE FOLD WIDENS A READ, which is the one thing worth arguing about, and the two rules that bound
+// it are `fixed-cell` and `covering-dominates` below. Neither is a restatement of what
+// raise/structs.ts already claims, and the difference is what makes them rules rather than
+// decoration: that pass declares a SINGLE LAYOUT covering every offset the function touches, which
+// is a claim the compiler reads and no instruction executes, while this one emits a DEREFERENCE.
+// Widening a read where the covering access is on the other arm of a branch would have the emitted
+// program load bytes that no execution reaching that point ever loaded — a compile-time claim
+// escalated into a runtime one. Widening a read of a cell at a constant address would change the
+// event a device sees. So the range this fold widens to must be a range some access at the same
+// base read ON THIS PATH, at a cell whose declaration cannot make its access width observable.
+//
+// LOW-ORDER END IS AN ENDIANNESS QUESTION, read off `capabilities.endianness` rather than assumed:
+// the low bytes of a big-endian field sit at its TOP address (`lw 20(a0)` covering `lhu 22(a0)`),
+// the low bytes of a little-endian one at its base. Both directions have a corpus inhabitant and
+// the benchmark's `unitrunc` row carries both.
+//
+// WHICH GATE BOUNDS THE CORPUS PATH — `pnpm bench gates --pass truncload [--toolchain <id>]`, and
+// the answer is the SOUND ones, per population. Over the synthetic tier on agbcc (337 rows) the
+// census reads `covering-store 12, covering-dominates 4, fixed-cell 2`; on ido7.1 (179 rows) and
+// gcc2.7.2kmc (183) `covering-store 12, high-order-read 4, fixed-cell 2`, the big-endian rows
+// reaching the skew rule because `utag`'s union members are read at the field's TOP; on
+// mwcc_242_81 (189) `covering-store 12, fixed-cell 2`. The union rows (`uhalf`, `ureread`, `utag`)
+// are most of it, and they are counted whole only because raise/structs.ts
+// recovers them rather than declining part-way through the enumeration — the next paragraph.
+//
+// READ THE `did not lift` LINE WITH THE COUNTS, because the census runs the whole RANKED
+// enumeration per row and a row that THROWS part-way through it contributes a TRUNCATED count
+// rather than none. `synthetic:unidev` is the worked example: while `raise/structs.ts` declined it
+// the agbcc census read `fixed-cell 1` with 13 rows unlifted, and once that pass stopped declining
+// a literal-address base it read `fixed-cell 2` with 12 — the same refusals, all of them now
+// reached. `--only synthetic:unidev:agbcc` shows the whole delta on that one row.
+//
+// `high-order-read` is STARVED on agbcc — not because nothing
+// skews there, but because `synthetic:uhalf`'s skewed read sits on a base whose widest access is
+// the `u->w = v` STORE, so the earlier rule answers first. Real rows show two of them alone:
+// `--only sa3:sub_804DC38:agbcc` reads `high-order-read 4`, an `ldrb` at byte 5 of a word at 4,
+// and `--only kleod:WorldMapScreenUnlockNewWorld:agbcc` reads `fixed-cell 90` — a named global's
+// cells, which is the same shape a named hardware register has. Two rules are UNINHABITED and say
+// so rather than being left to look load-bearing: `unresolved-base` and `cast-width` are refusals
+// no corpus row reaches, and both are pinned by a hand-written shape in the unit tests instead.
+//
+// A THIRD SHAPE IS ADMITTED AND SAYS SO RATHER THAN BEING CLAIMED SOUND: a cell reached at a
+// RUNTIME index from a literal or a named base — `((vu16 *)0x4000000)[i]`, the GBA palette and DMA
+// loops. `fixed-cell` does not fire there, because no constant address exists to read, and nothing
+// else can: the IR for that loop and the IR for an element of an ordinary global array are the
+// SAME IR, so refusing it would refuse every indexed access into a named object — including the
+// map-less spelling of the row this pass was written for. Where the access is qualified — the lift
+// pinned it as a device register's, or the map declares its object volatile — `qualified-access`
+// refuses it; any other one is a residue, it is unpriced, and the place it would be settled is the
+// symbol map, not this pass.
+//
+// A NARROW STORE IS NOT A CANDIDATE AT ALL — the refusal is in the candidate builder below rather
+// than in the gate table, and this is the table's named residue. Widening a write clobbers the
+// bytes past it, and no cast spelling expresses a partial write: `(u8)p->f = v` is not C. A base
+// whose conflict is a narrow STORE therefore keeps both widths — two views of a union member where
+// raise/structs.ts synthesizes the layout, two casts at a declared address.
+//
+// THE SECOND RESIDUE. A union read through members of three widths on three arms of a `switch`
+// (`synthetic:utag`) is refused by `covering-dominates`, and the overlap it leaves is declared as a
+// union member by raise/structs.ts — which is what that source wrote. Widening its reads DOES
+// compile byte-exactly on agbcc, which is exactly why the rule has to be a rule: the differ scores
+// the sound and the unsound spelling the same, so nothing downstream would ever refuse it.
+import { constAddressOf, globalCellOf } from '../ir/alias';
+import { type Block, type Fn, type Op, type Value, defOpMap, dominators, mkOp, mkValue } from '../ir/core';
+import { qualified } from '../ir/discipline';
+import { CAST_WIDTHS } from '../ir/opcodes';
+import { T } from '../ir/types';
+import { type Gate, firstRejection } from '../l3/gates';
+import { type Access, constOffsetAccesses } from './structs';
+
+/** Ops through which a base address is still the SAME address question — the arithmetic a lift
+ *  produces between a root and a load's operand. Anything else (a `load`, a `call`, a `laddr`) is
+ *  a value the function obtained, which ENDS the walk: a pointer it was handed is an object the
+ *  source declared, and there is nothing further to resolve. */
+const ADDRESS_ARITHMETIC: ReadonlySet<string> = new Set(['add', 'sub', 'or', 'and', 'xor', 'shl', 'shr_u', 'shr_s']);
+
+/** Does this base's origin RESOLVE — does the walk above reach a root it can name on every branch?
+ *  An entry parameter, a literal, a named global and a loaded pointer all resolve; a block param
+ *  joining two edges and an `undef` do not.
+ *
+ *  It answers ONE question and `fixed-cell` answers the other: whether the cell is at a constant
+ *  address is asked of the resolved base, and a base that never resolved cannot be asked at all.
+ *  WHY THE WALK IS HERE rather than composed out of ir/alias.ts's `constAddressOf` /
+ *  `globalBaseOf`: both of those return null for "not one of these" AND for "cannot tell", so a
+ *  caller composing them cannot separate a parameter from a join — and the join is the case that
+ *  has to refuse. */
+function baseResolves(defs: Map<Value, Op>, entryParams: ReadonlySet<Value>, v: Value): boolean {
+  const d = defs.get(v);
+  if (!d) {
+    return entryParams.has(v);
+  }
+  if (d.opcode === 'undef') {
+    return false;
+  }
+  return !ADDRESS_ARITHMETIC.has(d.opcode) || d.operands.every((o) => baseResolves(defs, entryParams, o));
+}
+
+/** What the gates below judge: one narrow LOAD and the access at its base that covers it. */
+export interface TruncatedLoad {
+  /** the narrow load reads a cell at a COMPILE-TIME CONSTANT address */
+  fixedCell: boolean;
+  /** the narrow load or its cover is a qualified access: pinned by the lift, or of an object the
+   *  map declares volatile */
+  qualified: boolean;
+  /** the base's origin resolves — it is not a join the walk could not finish */
+  resolvedBase: boolean;
+  /** the covering access is a LOAD, so its signedness is read rather than invented */
+  coveringLoad: boolean;
+  /** the narrow bytes are the low-order end of the covering range on THIS target's endianness */
+  lowOrderEnd: boolean;
+  /** the covering access runs, on EVERY path that reaches the narrow load, before it */
+  coveringDominates: boolean;
+  /** the width in BITS the cast would carry */
+  castWidth: number;
+}
+
+export const TRUNC_LOAD_GATES: readonly Gate<TruncatedLoad>[] = [
+  {
+    // SOUND, and it is the ACCESS WIDTH that is at stake rather than the value: a hardware register
+    // answers a byte read and a halfword read differently, so reading two bytes where the machine
+    // read one is an event the device sees. A memory-mapped register is a FIXED cell, and both
+    // spellings a source has for one land here: the bare cast of a number (`*(vu16 *)0x4000004`)
+    // through `constAddressOf`, and the named register (`REG_DISPSTAT`) through `globalCellOf`,
+    // whose `volatile` is a declaration in the project's headers that no raise pass can read.
+    // The two helpers are ir/alias.ts's, and `constAddressOf` is the address structure.ts's
+    // `volatileQualifiable` asks about — so a load this rule and `qualified-access` admit is one that
+    // predicate answers no to, by construction rather than by measurement.
+    //
+    // NOT `capabilities.deviceRegisters`. That window is documented as a question about SPELLING
+    // and may be approximate (target.ts), so a soundness rule may not rest on it; asking whether
+    // the address is constant at all is wider and needs nothing approximate.
+    id: 'fixed-cell',
+    why: 'a cell at a constant address can be a hardware register, where the access WIDTH is itself observable',
+    sound: true,
+    guardedBy: 'truncload.test.ts: a cell at a constant address is not narrowed',
+    rejects: (c) => c.fixedCell,
+  },
+  {
+    // SOUND, and the residue of the rule above rather than a rule of its own: a base that joins two
+    // edges has no definition to walk, so `fixed-cell` cannot ask its question and the honest
+    // answer is that this pass does not know what the base is. An `undef` base is the same shape —
+    // storage nothing was entitled to write.
+    id: 'unresolved-base',
+    why: 'a base whose origin does not resolve cannot be shown not to be a device cell',
+    sound: true,
+    guardedBy: 'truncload.test.ts: a base joined on two edges is not narrowed',
+    rejects: (c) => !c.resolvedBase,
+  },
+  {
+    // SOUND, and `fixed-cell`'s question answered by the passes that knew it: the device pin
+    // (frontend/device-pins.ts) marks a register's access whatever its address is, including the
+    // runtime-indexed channel `(vu32 *)(0x40000B0 + ch * 12)` no constant address reaches, and the
+    // `declared` stamp (raise/declared-volatile.ts) marks a read of a volatile object through a
+    // runtime index into it. Widened, the narrow access becomes a cast of a fresh load that carries
+    // no placement, at a width the machine never used on the object.
+    id: 'qualified-access',
+    why: 'a qualified access is made at its own width, and the fold would also drop its placement',
+    sound: true,
+    guardedBy: 'truncload.test.ts: a pinned narrow read through a runtime-indexed base keeps its width and its pin',
+    rejects: (c) => c.qualified,
+  },
+  {
+    // The sibling narrowing passes' rule, under the sibling name (raise/paramwidth.ts,
+    // raise/narrowlocal.ts): a width `CAST_WIDTHS` does not carry has no C cast to spell it, so the
+    // fold would mint a `zext` the backend can only gap on. No corpus row reaches it today — every
+    // frontend load is 1, 2 or 4 bytes — and it costs a line rather than an argument about which
+    // widths a frontend may acquire.
+    id: 'cast-width',
+    why: 'only 8 and 16 are widths a `zext`/`sext` — and so a C declaration — carries',
+    sound: true,
+    guardedBy: 'truncload.test.ts: a width no C type spells is refused',
+    rejects: (c) => !CAST_WIDTHS.has(c.castWidth),
+  },
+  {
+    // A covering STORE fixes the bytes but not the field's signedness, and the fold has to put one
+    // on the load it synthesizes. Not sound — the bytes are the same either way, so the worst case
+    // is a field declared `u16` where the source wrote `s16` — but inventing a fact the asm did not
+    // carry is not how a default spelling is chosen, and the differ never sees this one because the
+    // synthesized load is not enumerated.
+    id: 'covering-store',
+    why: 'a covering store carries no signedness, so the field type would be invented rather than read',
+    sound: false,
+    rejects: (c) => !c.coveringLoad,
+  },
+  {
+    // SOUND: a read of bytes ABOVE the field's low-order end is `(u16)(x >> 16)`, not `(u16)x`.
+    // The cast spelling would read the field's other half — a different value from the one the
+    // machine loaded, silently. The shifted form is expressible, but it is not what the narrow
+    // instruction spells and nothing would recompile to it, so the honest answer is to leave the
+    // base declining.
+    id: 'high-order-read',
+    why: 'bytes above the low-order end of a field are a shift, and a plain cast would read the wrong ones',
+    sound: true,
+    guardedBy: 'truncload.test.ts: a read above the low-order end is not narrowed',
+    rejects: (c) => !c.lowOrderEnd,
+  },
+  {
+    // SOUND, and the rule that separates this fold from the layout claim it feeds. Widening the
+    // read puts a WIDER ACCESS at the point where the machine executed a narrower one, so the bytes
+    // past the narrow range have to be bytes this execution already read — not merely bytes the
+    // FUNCTION reads somewhere. raise/structs.ts declares one layout per base across the whole
+    // function, which is a claim about the object's TYPE and costs no instruction; this fold emits
+    // a dereference, so the same function-wide reasoning would have the program read three bytes it
+    // never read on the path it is on. Dominance is what makes the two claims different sizes.
+    id: 'covering-dominates',
+    why: 'the bytes past the narrow read must be bytes this execution already read, not bytes some other path reads',
+    sound: true,
+    guardedBy: 'truncload.test.ts: a cover on the other arm of a branch is not narrowed',
+    rejects: (c) => !c.coveringDominates,
+  },
+];
+
+/** One admitted-or-refused fold: the narrow load, the access it truncates, and what the gates see. */
+export interface TruncLoadCandidate {
+  narrow: Access;
+  covering: Access;
+  c: TruncatedLoad;
+}
+
+/** Every narrow load an access at the same base covers, in program order.
+ *
+ *  WHICH COVER, when several cover the same narrow read: the pick is a TOTAL ORDER over facts, not
+ *  a reduction over the order the accesses happen to be emitted in. A cover the sound rules can
+ *  admit outranks one they cannot — `{w4@8, w4@6, w1@8}` folds whichever of the two wide reads was
+ *  emitted first otherwise, so an identical access set would admit or refuse on instruction
+ *  scheduling alone. After that the WIDEST wins, because a base read at 4, 2 and 1 bytes from one
+ *  offset collapses to ONE field in a single pass that way where the closest cover would need a
+ *  fixpoint; then a load over a store; then the earlier access. A cover is never itself a
+ *  candidate, since a candidate is strictly narrower than its own cover. */
+export function truncatedLoadCandidates(fn: Fn, littleEndian: boolean): TruncLoadCandidate[] {
+  const { accessesOf } = constOffsetAccesses(fn);
+  const defs = defOpMap(fn);
+  const entryParams = new Set(fn.blocks[0].params);
+  const dom = dominators(fn);
+  const blockDominates = (a: number, b: number): boolean => dom.get(fn.blocks[b] as Block)!.has(fn.blocks[a] as Block);
+  const runsBefore = (a: Access, b: Access): boolean =>
+    a.block === b.block ? a.at < b.at : blockDominates(a.block, b.block);
+  const isLowOrderEnd = (narrow: Access, cover: Access): boolean =>
+    littleEndian ? narrow.off === cover.off : narrow.off + narrow.width === cover.off + cover.width;
+
+  const out: TruncLoadCandidate[] = [];
+  for (const b of fn.blocks) {
+    for (const op of b.ops as Op[]) {
+      if (op.opcode !== 'load') {
+        continue;
+      }
+      const base = op.operands[0];
+      const all = accessesOf.get(base)!;
+      const narrow = all.find((a) => a.op === op)!;
+      const covers = all.filter(
+        (a) => a.width > narrow.width && a.off <= narrow.off && a.off + a.width >= narrow.off + narrow.width,
+      );
+      if (covers.length === 0) {
+        continue;
+      }
+      const preference = (a: Access): number[] => [
+        isLowOrderEnd(narrow, a) ? 1 : 0,
+        runsBefore(a, narrow) ? 1 : 0,
+        a.width,
+        a.isLoad ? 1 : 0,
+      ];
+      const covering = covers.reduce((best, a) => {
+        const [x, y] = [preference(a), preference(best)];
+        const i = x.findIndex((v, k) => v !== y[k]);
+        return i >= 0 && x[i] > y[i] ? a : best;
+      });
+      out.push({
+        narrow,
+        covering,
+        c: {
+          fixedCell: constAddressOf(defs, base, narrow.off) !== null || globalCellOf(defs, base, narrow.off) !== null,
+          qualified: [op, covering.op].some(qualified),
+          resolvedBase: baseResolves(defs, entryParams, base),
+          coveringLoad: covering.isLoad,
+          lowOrderEnd: isLowOrderEnd(narrow, covering),
+          coveringDominates: runsBefore(covering, narrow),
+          castWidth: narrow.width * 8,
+        },
+      });
+    }
+  }
+  return out;
+}
+
+/** Rewrite every admitted narrow load into a cast of a wider one. Returns the number of rewrites.
+ *
+ *  `gates` is a REQUIRED argument, not an option with a default: the table is how the refusals are
+ *  ablated, and a second caller that could omit it would switch the channel off silently. */
+export function foldTruncatedLoads(fn: Fn, littleEndian: boolean, gates: readonly Gate<TruncatedLoad>[]): number {
+  const admitted = truncatedLoadCandidates(fn, littleEndian).filter((k) => firstRejection(gates, k.c) === null);
+  if (admitted.length === 0) {
+    return 0;
+  }
+  const byBlock = new Map<number, TruncLoadCandidate[]>();
+  for (const k of admitted) {
+    const list = byBlock.get(k.narrow.block);
+    if (list) {
+      list.push(k);
+    } else {
+      byBlock.set(k.narrow.block, [k]);
+    }
+  }
+  for (const [block, ks] of byBlock) {
+    const b = fn.blocks[block];
+    const inserted = new Map<number, Op>();
+    for (const k of ks) {
+      const wide = mkOp('load', {
+        operands: [k.narrow.op.operands[0]],
+        results: [mkValue(T.unk(32))],
+        attrs: { off: k.covering.off, width: k.covering.width, signed: k.covering.signed },
+      });
+      inserted.set(k.narrow.at, wide);
+      // REWRITTEN IN PLACE, so the result `Value` identity survives and every existing use — and
+      // any slot home stamped on it (`ir/core.ts` SlotHomes) — keeps reading the same value. The
+      // operand it drops is the base, which the fresh load above still reads, so nothing is
+      // orphaned and the pass declares `dce: false`.
+      k.narrow.op.opcode = k.narrow.signed ? 'sext' : 'zext';
+      k.narrow.op.operands = [wide.results[0]];
+      k.narrow.op.attrs = { width: k.narrow.width * 8 };
+    }
+    b.ops = b.ops.flatMap((op, at) => {
+      const wide = inserted.get(at);
+      return wide ? [wide, op] : [op];
+    });
+  }
+  return admitted.length;
+}

package/src/raise/widehelpers.ts

@@ -0,0 +1,106 @@
+// asmlift — 64-bit runtime-helper lowering (L1 recognition).
+//
+// The peer of `raise/softdiv.ts`, one width up, and NOT gated on a hardware capability. A soft
+// division is a division the ISA has no instruction for, so a target with a divider never emits
+// one; no ISA this repo targets has 64-bit integer arithmetic at all, so `bl __muldi3` is software
+// on every one of them whatever `hwDivide` says.
+//
+// By the time this runs the frontend has already read the call's arguments as 64-bit values and
+// split its result back into the register pair (`frontend/thumb.ts`, at the `bl`), so the rewrite
+// itself is the same one-line splice `softdiv` does: the helper's op over the same operands,
+// reusing the SAME result value so every existing use already points at it.
+//
+// The signedness of the OPERATION comes from the helper name where the name splits it
+// (`__divdi3`/`__udivdi3`) and from the operands where it does not — agbcc's `__muldi3` serves
+// both spellings, so nothing here may read a signedness off it. See the table's own note.
+import { Fn, mkOp } from '../ir/core';
+import { arrivesAsDeclared, helperOp, isFloatHelper, isWideHelper, lookupHelper } from '../runtime-helpers';
+import type { TargetDescription } from '../target';
+
+/** Rewrite each recognised 64-bit helper call to the op it computes, in place. Returns whether
+ *  anything changed. Runs BEFORE type recovery, so the operands get their signedness there. */
+export function recognizeWideHelpers(fn: Fn, target: TargetDescription): boolean {
+  const table = target.runtimeHelpers ?? {};
+  let changed = false;
+  for (const b of fn.blocks) {
+    for (let i = 0; i < b.ops.length; i++) {
+      const op = b.ops[i];
+      if (op.opcode !== 'call') {
+        continue;
+      }
+      const helper = lookupHelper(table, String(op.attrs.target));
+      if (!helper?.op || !isWideHelper(helper) || isFloatHelper(helper)) {
+        continue;
+      }
+      // ITS C PARAMETERS AT THEIR STATED WIDTHS, not its argument registers and not their count:
+      // the frontend has paired the registers up, so a `__ashrdi3` that occupied three of them
+      // arrives here as a 64-bit value and a word. That pair construction is the evidence the fold
+      // rests on, and `arrivesAsDeclared` is the precondition for reading it — an operand count
+      // says nothing about what the operands hold, and a call carrying the right count of the
+      // wrong things folds into an operation over one half of each value.
+      //
+      // WHAT DECLINES HERE DOES NOT PASS THROUGH: `refuseUnmodelledHelpers` below gaps every
+      // surviving call to a name this table carries, so a shape this cannot fold gets the loud
+      // answer rather than a plausible one.
+      if (
+        !arrivesAsDeclared(
+          helper,
+          op.operands.map((o) => o.type),
+          op.results.map((r) => r.type),
+        )
+      ) {
+        continue;
+      }
+      b.ops.splice(i, 1, helperOp(helper.op, String(op.attrs.target), op.operands, op.results[0]));
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+/** Turn every surviving call to one of the target's runtime helpers into a gap. Returns whether
+ *  anything changed. Runs after the helper recognisers, so what it sees is what they declined.
+ *
+ *  RE-EMITTING A COMPILER'S OWN RUNTIME CALL IS NOT A RECOVERY, and it is worse than a plain
+ *  miss: it MATCHES. Hand `mwcceppc` the source `return __div2i(a, b);` and it emits the `bl
+ *  __div2i` the row was lifted from, byte for byte — so the differ scores asmlift's failure to
+ *  model 64-bit division exactly as it would score modelling it. A row that cannot tell the two
+ *  apart is measuring nothing, and four cells of the synthetic 64-bit family were banking that.
+ *
+ *  ONLY THE NAMES THE TARGET CARRIES, and a name outside the table stays an ordinary callee —
+ *  which is right, because a project's own `__`-prefixed function is not this compiler's runtime
+ *  and asmlift cannot tell them apart by spelling. A target with NO table therefore refuses
+ *  nothing and spells every helper call it makes, which is the configuration this refusal exists
+ *  to remove (`TargetDescription.runtimeHelpers`).
+ *
+ *  An `opaque` rather than a throw, so the gap behaves like every other one: strict mode declines
+ *  naming it, annotate mode marks it and leaves the rest of the function standing. */
+export function refuseUnmodelledHelpers(fn: Fn, target: TargetDescription): boolean {
+  const table = target.runtimeHelpers;
+  if (!table) {
+    return false;
+  }
+  let changed = false;
+  for (const b of fn.blocks) {
+    for (let i = 0; i < b.ops.length; i++) {
+      const op = b.ops[i];
+      // Membership, through the table's one reader: `in` would also answer for `toString` and every
+      // other name on `Object.prototype`, and this is the refusal, so the fabricated reason would be
+      // the whole of what a caller saw.
+      if (op.opcode !== 'call' || lookupHelper(table, String(op.attrs.target)) === undefined) {
+        continue;
+      }
+      b.ops.splice(
+        i,
+        1,
+        mkOp('opaque', {
+          operands: [...op.operands],
+          results: [...op.results],
+          attrs: { helper: op.attrs.target },
+        }),
+      );
+      changed = true;
+    }
+  }
+  return changed;
+}

package/src/rank-declare.ts

@@ -11,8 +11,9 @@
 import { type Fn, type Value, defOpMap } from './ir/core';
 import type { SFn } from './l3/ast';
 import { type SymbolRef, collectSymbolRefs } from './l3/symbol-refs';
-import type { SymbolInfo } from './symbols';
-import { C_TYPEDEFS } from './target';
+import type { Prototypes } from './proto';
+import { type SymbolInfo, accessSignedness } from './symbols';
+import { C_TYPEDEFS, type TargetDescription } from './target';
 
 /** Bare-global ACCESS FACTS for name-only map symbols — the width/signedness authority the
  *  declaration synthesis (declare.ts) uses when the map has no shape. The map knows only the
@@ -42,7 +43,7 @@ export function bareGlobalAccessFacts(fn: Fn): Map<string, { width: number; sign
           } else {
             a.widths.add(op.attrs.width as number);
             if (op.opcode === 'load') {
-              a.signs.add(((op.attrs.signed as boolean) ?? false) && (op.attrs.width as number) < 4);
+              a.signs.add(accessSignedness(op.attrs.width as number, op.attrs.signed as boolean | undefined));
             }
           }
         }
@@ -202,15 +203,34 @@ export function makeRefCollector(ctx: {
   /** the globals the TARGET names — the pool/reloc names and the shapes the asm evidences, before
    *  the map is unioned in */
   targetNames: ReadonlySet<string>;
+  /** the project's prototype table — what lets a CALL TARGET be declared rather than refused */
+  prototypes: Prototypes;
+  /** the target the lift ran for, whose ABI says which declared types a printed prototype carries */
+  target: Pick<TargetDescription, 'doubleArgWords'>;
   /** reports a refusal at most once per (name, reason); the caller owns the dedup */
   refuse: (name: string, reason: RefusedDeclarationReason) => void;
 }): (tree: SFn) => { symbolRefs?: SymbolRef[] } {
-  const { declSymbols, accessFacts, mapSymbols, targetNames, refuse } = ctx;
+  const { declSymbols, accessFacts, mapSymbols, targetNames, prototypes, target, refuse } = ctx;
   return (tree: SFn): { symbolRefs?: SymbolRef[] } => {
     // The names THIS tree binds. Computed per tree because the emitter mints local names per
     // spelling — but the test below is NOT `bound` alone, and the difference is a wrong answer.
     const bound = new Set<string>([...tree.params.map((p) => p.name), ...tree.locals.map((l) => l.name)]);
-    const refs = collectSymbolRefs(tree.body, declSymbols, tree.name, refuse).flatMap((r) => {
+    // A function-scope static is declared in the body beside the locals, so it shares their
+    // namespace: one the emitter's own names can reach dies with the spelling, as below.
+    const statics = new Set((tree.statics ?? []).map((st) => st.name));
+    for (const st of statics) {
+      if (bound.has(st) || EMITTER_NAME.test(st)) {
+        refuse(st, 'emitter-name');
+        throw new Error(
+          `cannot spell '${tree.name}': the target names a function-scope static '${st}', which is a ` +
+            `name the emitted C uses for its own locals and parameters — no declaration can bind it`,
+        );
+      }
+    }
+    const refs = collectSymbolRefs(tree, declSymbols, prototypes, target, refuse).flatMap((r) => {
+      if (statics.has(r.name)) {
+        return []; // defined in the body — the map's global of the same name is another object
+      }
       // THE ONE REFUSAL THAT IS NOT A REFUSAL — a name the emitted C uses for its OWN storage
       // kills the SPELLING, because no declaration makes that candidate right and no declaration
       // makes it fail either. Two shapes, and the second is why the test is the emitter's whole
@@ -257,6 +277,11 @@ export function makeRefCollector(ctx: {
       // A ref no MAP accounts for is a hypothesis read out of the target asm, and it is marked
       // as one all the way to the consumer (SymbolRef.synthesized).
       const synthesized = mapSymbols?.has(r.name) ? {} : { synthesized: true as const };
+      // A global the asm reads narrower than a word holds no pointer, whatever it meets bare.
+      if (r.holdsPointer && access !== undefined && access.width !== 4) {
+        const { holdsPointer: _, ...integer } = r;
+        return [{ ...integer, access, ...synthesized }];
+      }
       return [{ ...r, ...(access ? { access } : {}), ...synthesized }];
     });
     return refs.length ? { symbolRefs: refs } : {};

package/src/rank-variations.ts

@@ -27,6 +27,7 @@ import {
 import type { Gate } from './l3/gates';
 import type { HoistPlacement } from './l3/hoist';
 import { initFirstGuards } from './l3/initfirst';
+import { narrowDeclarations, narrowReadDeclarations } from './l3/narrowdecl';
 import { pollGuards, pollReads } from './l3/pollguard';
 import { unmergeJoins } from './l3/unmerge';
 // TYPE-ONLY, and deliberately: the structure-variation table types its `options` as
@@ -35,6 +36,7 @@ import { unmergeJoins } from './l3/unmerge';
 import type { structureChecked } from './pipeline';
 import {
   hasDerivedReadHome,
+  hasEscapingExtension,
   hasHomeableSharedAddress,
   hasLoopSharedPureValue,
   hasMergeFeedHome,
@@ -53,11 +55,12 @@ import type { VariationName } from './variation-tokens';
  *  that setting's own lifted fn (a map-lifted shared lift spells const bases as gaddr, which would
  *  blind the /raw-globals siblings — the /addr-home lesson). `strip` opts the variation into the
  *  dropped-sibling closure: a candidate that applies it is skipped when its default sibling (the
- *  same setting without it) failed the boundary contracts. Two variations are EXEMPT from structure()'s assertDefaultAccepts invariant:
- *  `/reread-globals` only relaxes inlining barriers and `/uns-cmp` only changes spelling and
- *  declarations — neither adds materialization or merging, so neither can unlock a function the
- *  default declines (reread also skips the strip closure). Both exemptions are stated here
- *  rather than left implicit in a missing `||` arm or trigger term. */
+ *  same setting without it) failed the boundary contracts. Which of these entries `structure()`'s
+ *  `assertDefaultAccepts` guard does NOT reset — the ones that cannot unlock a function the default
+ *  declines, and so carry a written argument in place of the guard — is stated ONCE, beside that
+ *  guard in structure.ts, and derived from the guard's own reset list in
+ *  test/variation-offers.test.ts — never restated here, where a second copy drifts from the guard
+ *  without anything going red. */
 export interface StructureVariation {
   flag:
     | 'reread'
@@ -67,6 +70,7 @@ export interface StructureVariation {
     | 'exprHome'
     | 'derivedHome'
     | 'mergeHome'
+    | 'escapeHome'
     | 'unsCmp'
     | 'freshMerge'
     | 'copyDefPos'
@@ -203,6 +207,24 @@ export const STRUCTURE_VARIATIONS: readonly StructureVariation[] = [
     perLiftGate: hasMergeFeedHome,
     strip: true,
   },
+  // `/escape-home` — the escaping-extension-home variation (structure/analysis.ts AnalyzeOptions
+  // homeEscapingExtensions): a `zext`/`sext` with 2+ consumers, none of them in its own block,
+  // materializes into a local — the register the asm narrowed into once and every later block read
+  // — where the default re-evaluates the truncation at each consumer (`(u16)v` per use). The
+  // MIRROR of `/expr-home`, which wants a def outside a loop and a consumer inside; neither scope
+  // reaches the other's shape. Gated per symbol-map setting like its four siblings.
+  //
+  // A VARIATION, not a default, and `pokeemerald:AcroBikeHandleInputTurning:agbcc` is the row that
+  // decides it: it is a MATCH inside the scope, so forced on the spelling would be REPLACED across
+  // the fan rather than added to it. As a variation `compareScored` rides the un-homed sibling
+  // beside it and the match cannot be lost — the same argument `/merge-home` records above.
+  {
+    flag: 'escapeHome',
+    name: 'escape-home',
+    options: (on) => ({ homeEscapingExtensions: on }),
+    perLiftGate: hasEscapingExtension,
+    strip: true,
+  },
   // `/uns-cmp` — spell unsigned compares unsigned (structure.ts unsignedCompareSpelling): an
   // icmp_u* operand takes a (u32) cast where the rendered operands do not guarantee the
   // unsignedness, and a mixed-claimant declaration reconciles to u32 when nothing under the
@@ -352,15 +374,21 @@ export const STRUCTURE_VARIATIONS: readonly StructureVariation[] = [
 ];
 
 /** The STACKED variations (sanctioned in the POLICY note at rank.ts's respell site): each entry is
- *  a statement-order/shape respell variation orthogonal to every other respell variation, derived
- *  onto every source. Each fires alone, plus
+ *  a statement-order/shape or declaration-width respell variation orthogonal to every respell
+ *  variation outside this table, derived onto every source. Two members need not commute
+ *  (`/narrow-decl` and `/narrow-read` compete for one cast), and table order then decides which one
+ *  takes it in the all-together candidate. Each fires alone, plus
  *  all of them together in table order — not the full subset lattice; the pairs question is
  *  settled by applyStacked' skip-on-decline below, and a row demanding a true EXCLUSION pair —
- *  all three fire, the match needs exactly two — is what would earn the lattice. */
+ *  every member fires, the match needs a strict subset of them — is what would earn the lattice.
+ *  So a member appended here also changes the all-together candidate wherever it fires beside two
+ *  or more of the others. */
 export const STACKED_VARIATIONS: { name: VariationName; apply: (sfn: SFn) => SFn | null }[] = [
   { name: 'initfirst', apply: initFirstGuards },
   { name: 'pollguard', apply: pollGuards },
   { name: 'pollread', apply: pollReads },
+  { name: 'narrow-decl', apply: narrowDeclarations },
+  { name: 'narrow-read', apply: narrowReadDeclarations },
 ];
 
 /** The PRE-RESPELL variations (sanctioned in the POLICY note at rank.ts's respell site): a tree