@asmlift/core 0.5.0 → 0.6.0

package/src/frontend/ssa.ts

@@ -15,8 +15,8 @@
 // computation via read/writeVar, push its terminator op last (successors referencing
 // `irBlocks`, args left empty — phi wiring appends them), then call `markFilled(b)`. When all
 // blocks are filled, call `finish()` to remove trivial phis.
-import { Block, Fn, Op, Value, mkValue } from '../ir/core';
-import { simplifyTrivialPhis } from '../ir/simplify';
+import { Block, Fn, Op, type SlotHomes, Value, type WriteOrder, mkOp, mkValue } from '../ir/core';
+import { pruneDeadParams, simplifyTrivialPhis } from '../ir/simplify';
 import { T } from '../ir/types';
 import { FrontendUnsupportedError } from './errors';
 
@@ -48,13 +48,14 @@ export interface SsaBuilder {
   /** Whether `reg` has a definition reaching block `b` (best-effort call-arity heuristic). */
   hasReachingDef(reg: string, b: number, seen?: Set<number>): boolean;
   /** Record that block `b` makes a call HERE: the ABI's caller-saved registers stop being ones the
-   *  caller set up. Call it AFTER `recordGuessedCall` for the same instruction, and before writing
-   *  the call's own result. */
+   *  caller set up. Call it AFTER `recordGuessedCall` for the same instruction, and after writing
+   *  the call's own result — the result is the CALLEE's, so it must not count as caller-side
+   *  argument setup for whatever call comes next. */
   noteCall(b: number): void;
   /** Register a `call` op whose arity was GUESSED (no prototype), so `finish` can cut it back to the
    *  argument registers that were actually set up on every path (see {@link trimClobberedCallArgs}).
-   *  `argRegs` is the target's argument-register order. */
-  recordGuessedCall(op: Op, b: number, argRegs: string[]): void;
+   *  `abi` is the target's argument-register order and its return register. */
+  recordGuessedCall(op: Op, b: number, abi: { argRegs: string[]; returnReg: string }): void;
   /** Remove trivial phis and enforce the frontend's postconditions; call once every block is
    *  filled. Throws FrontendUnsupportedError if a stack slot escaped as an entry parameter. */
   finish(): void;
@@ -67,9 +68,135 @@ export interface SsaBuilder {
 // A virtual key must be outside its ISA's register grammar so it cannot collide with a real one, and
 // a key read with no reaching def becomes a function PARAMETER by the live-in path below — which is
 // how both of those capabilities get their parameters without a new opcode or pass.
-export function makeSsaBuilder(name: string, blockCount: number, preds: number[][]): SsaBuilder {
+/** What a def-less live-in MEANS here, in two coordinate systems — the frame in slot-key offsets,
+ *  the register file by key. RANGES and LISTS rather than a verdict, so the classification below is
+ *  checkable here: a frontend that is wrong about its own frame gets refused instead of believed,
+ *  and a range that collapses to empty (an unmeasurable frame) stops claiming anything on its own.
+ *  Ghidra carries the same partition as compiler-spec data (`<localrange>`, stack `<pentry>`) read
+ *  by architecture-neutral code. */
+export interface LiveInModel {
+  /** Storage this function owns as LOCALS ⇒ a def-less read is an uninitialised local. `[from, to)`.
+   *
+   *  Asserts more than ownership: that this function's own stores are the ONLY writer. An address
+   *  into the frame that escapes to anything which could write it stops that holding, and the
+   *  retraction is the frontend's obligation (frontend/thumb.ts, after the frame-object audit). */
+  ownedLocals?: { from: number; to: number };
+  /** Storage this function DECLARES as locals ⇒ a `[sp,#k]` spill here is a DECLARATION RANK
+   *  (`ir/core.ts` `SlotHomes`, ordered by `l3/slotorder.ts`). `[from, to)`.
+   *
+   *  WHY THIS IS NOT `ownedLocals`, and the distinction is the whole point of the field. Owning
+   *  storage and declaring it are different claims, and agbcc's frame contains storage it owns
+   *  and does not declare: `ACCUMULATE_OUTGOING_ARGS` puts the OUTGOING STACK-ARGUMENT area at
+   *  the BOTTOM of `localArea` (frontend/thumb.ts says so at its own decline), so `[0, localArea)`
+   *  admits argument slots. A def-less read of one is still an uninitialised local — `ownedLocals`
+   *  is right for that question — but its offset is an ABI position, not an `expand_decl` rank,
+   *  and ranking a declaration list by it would be wrong with no diagnostic.
+   *
+   *  TODAY THE TWO RANGES COINCIDE UNDER THUMB, AND THAT IS DELEGATED, NOT PROVED. What keeps
+   *  argument slots out of `SlotHomes` is `prefixStored` (frontend/thumb.ts): a function whose
+   *  frame has an outgoing area DECLINES before it reaches here, so every function that does
+   *  reach here has none. That guard's own comment says "Neither is sound alone and the pair is
+   *  not either", and lifting it is a named next step — so this field exists to make the
+   *  dependency TYPED and LOCAL rather than implicit and cross-module. Whoever lifts that decline
+   *  must narrow this range above the argument block; leaving it equal to `ownedLocals` would
+   *  start minting declaration ranks out of argument slots silently.
+   *
+   *  The class is populated, not hypothetical. Over a sweep of every sa3 and klonoa listing, of
+   *  2,001 lifted real agbcc functions 27 carry any L1 slot home, 12 of those also CALL, and 11 of
+   *  those carry a home at offset 0 — the exact offset `prefixStored` encodes as where an argument
+   *  block starts (`PackSaveSector` homes [0,4,…,72], `modf` [0,4,…,36], `RenderDialogSprites`
+   *  [0,4,…,36], and eight more). None reaches the ordering today, for an unrelated reason
+   *  (`l3/slotorder.ts`'s REACH note), so nothing downstream is guarding this.
+   *
+   *  ABSENT ⇒ NO STAMP. MIPS and PPC declare no frame partition at all, so they stamp nothing,
+   *  which is the refusing direction. */
+  declaredLocals?: { from: number; to: number };
+  /** Storage the CALLER wrote — incoming stack arguments ⇒ a def-less read is a parameter.
+   *  `[from, to)`. O32's register-parameter home area belongs to NEITHER range: caller-owned, but
+   *  not an argument. */
+  callerParams?: { from: number; to: number };
+  /** Registers a def-less read of which is an uninitialised local the compiler put in a register.
+   *  TWO facts, and the frontend owes both: the ABI passes no argument there (`target.nonArgRegs`,
+   *  so no caller could have handed a value over, however early the read happens) AND this function
+   *  saved the register (so it is one the compiler was free to home a local in). The ABI half alone
+   *  describes the CALLER, and asm that follows no ABI — hand-written, or a mid-function fragment,
+   *  which klonoa's `bl`-as-a-long-branch splits produce for real — is genuinely handed live values
+   *  in registers it never saved. Passing the ABI list unfiltered cost the MP2K engine's
+   *  `ChnVolSetAsm` its two-pointer signature and left it storing through `uninit_r4`, silently.
+   *
+   *  The save is a MEASUREMENT, like the frame's, and belongs to whoever can make it — Thumb reads
+   *  the leading push run (`savedRegs`); a frontend that cannot measure it passes nothing here and
+   *  keeps the parameter it would have got anyway.
+   *
+   *  The frame's sole-writer obligation has no counterpart here and needs none: a register has no
+   *  address, so nothing outside this function can name it and there is no escape to retract.
+   *
+   *  LISTED, not derived as "everything outside argRegs", because the complement contains the
+   *  VIRTUAL keys too (`@sarg<k>` — an incoming stack argument, which really is a parameter), and a
+   *  rule that had to exclude them would be reading a grammar this module does not own. A register
+   *  spelling nobody listed keeps its existing treatment, so the list is safe to grow.
+   *
+   *  Declaring this obliges `argRegs` below, and the two must be DISJOINT. */
+  uninitRegs?: readonly string[];
+  /** Registers the ABI DOES pass arguments in — the other side of the register partition, and the
+   *  only reason the side above is checkable rather than believed. The frame coordinate declares
+   *  both of its sides and refuses an offset in neither; this one declares both and refuses a key
+   *  in BOTH, which is the same move.
+   *
+   *  Without it the whole contract rests on one hand-written list in target.ts being right, in a
+   *  file whose idiom is "a compiler fact is one field": spelling `r1` where `r11` was meant
+   *  deletes a parameter and emits `s32 uninit_r1;` in its place, with no diagnostic anywhere.
+   *  `readRecursive` cannot catch that on its own — it never sees the argument registers, because
+   *  a read of one takes the parameter path by falling through every other case. */
+  argRegs?: readonly string[];
+}
+
+/** The register partition's postcondition, checked at the point of USE. `uninitRegs` asserts "no
+ *  caller could have handed a value over in these"; `argRegs` is the set of registers a caller
+ *  hands values over in. A key in both is a target that contradicts itself, and a `uninitRegs` with
+ *  no `argRegs` beside it is one whose assertion nothing can check — both refuse rather than
+ *  silently reclassify an argument as an uninitialised local. */
+function checkedLiveInModel(fnName: string, m: LiveInModel): LiveInModel {
+  if (m.uninitRegs === undefined) {
+    return m;
+  }
+  const args = m.argRegs;
+  if (args === undefined) {
+    throw new Error(
+      `lifting '${fnName}': the live-in model lists registers the ABI does not pass arguments in ` +
+        `but not the ones it does, so nothing can check the two agree`,
+    );
+  }
+  const both = m.uninitRegs.filter((r) => args.includes(r));
+  if (both.length > 0) {
+    throw new Error(
+      `lifting '${fnName}': the live-in model lists ${both.join(', ')} as BOTH an argument register ` +
+        `and one the ABI does not pass arguments in`,
+    );
+  }
+  return m;
+}
+
+export function makeSsaBuilder(
+  name: string,
+  blockCount: number,
+  preds: number[][],
+  /** A supplier because half the partition is MEASURED rather than declared: Thumb's local area
+   *  comes from a prologue walk that runs after this call. Evaluated once, on first use. Omitted ⇒
+   *  no partition is claimed, so every slot refuses and every register is a parameter. */
+  liveInOf: () => LiveInModel = () => ({}),
+): SsaBuilder {
+  let modelMemo: LiveInModel | null = null;
+  // Checked ONCE, where the model is materialised — every function with a parameter reads a
+  // register def-lessly, so this runs on effectively every lift rather than only on the rare
+  // function that reads the mis-listed register. A contradictory or half-declared partition is a
+  // bug in the TARGET, not an unliftable function, so it throws a plain Error: a decline would
+  // report the target's typo as a property of the input, once per function, forever.
+  const model = (): LiveInModel => (modelMemo ??= checkedLiveInModel(name, liveInOf()));
+  const inRange = (off: number, r?: { from: number; to: number }) => r !== undefined && off >= r.from && off < r.to;
   const irBlocks: Block[] = Array.from({ length: blockCount }, () => ({ params: [] as Value[], ops: [] }));
-  const fn: Fn = { name, blocks: irBlocks };
+  // `writeOrder` and `slotHomes` are filled in below, where the builder's counters live.
+  const fn: Fn = { name, blocks: irBlocks, writeOrder: undefined, slotHomes: undefined };
 
   const defs: Array<Map<string, Value>> = irBlocks.map(() => new Map());
   const sealed: boolean[] = irBlocks.map(() => false);
@@ -100,11 +227,91 @@ export function makeSsaBuilder(name: string, blockCount: number, preds: number[]
   const writtenSinceCall: Array<Set<string>> = irBlocks.map(() => new Set());
   const callsIn = new Set<number>();
   const guessedCalls: GuessedCallSite[] = [];
-  let argRegsSeen: string[] = [];
+  let abiSeen: { argRegs: string[]; returnReg: string } = { argRegs: [], returnReg: '' };
+
+  // WRITE ORDER (ir/core.ts `WriteOrder`). Measured here for the same reason the clobber set is:
+  // every register write in every frontend already goes through `writeVar`, and a delay-slot write
+  // is decoded before its branch is emitted, so the ordinal is the machine's own program order on
+  // every ISA with no frontend code. Per block, because the consumer asks a per-EDGE question.
+  const writeCount: number[] = irBlocks.map(() => 0);
+  const lastWriteAt: Array<Map<string, number>> = irBlocks.map(() => new Map());
+  const writeOrder: WriteOrder = { lastWrite: new Map(), writes: new Map() };
+  fn.writeOrder = writeOrder;
+
+  // SLOT HOMES (ir/core.ts `SlotHomes`). Measured HERE, in the shared builder, for the same
+  // reason the clobber set and the write order are: BOTH frontends already spell a word spill as
+  // a write to the key `sp@k` (`stackSlotKey`, below), so the frontend supplies the coordinate
+  // and one rule applies it — a per-frontend stamp would be right only while each remembered to
+  // route every slot write past a wrapper, and a missed write is a local with no frame order.
+  // Empty rather than absent on a function that spills nothing: this builder measured it.
+  const slotHomes: SlotHomes = new Map();
+  fn.slotHomes = slotHomes;
+  const noteSlotHome = (key: string, v: Value) => {
+    const off = slotKeyOffset(key);
+    if (off === null) {
+      return; // an ordinary register: no frame coordinate exists
+    }
+    // THE KEY SPELLING CANNOT DECIDE THIS, exactly as `readRecursive` says below of a def-less
+    // read: `sp@40` is a local on one ABI and the caller's fifth argument on another. So the stamp
+    // asks the frontend for a partition and refuses where no answer exists. The two frontends
+    // differ here and the refusal is what makes that safe: Thumb declares a range; MIPS declares NO
+    // partition (frontend/mips.ts: `addiu sp,sp,±N` is transparent, so its slot keys span O32's
+    // caller-owned register-parameter home area `[0,16)` and the incoming stack arguments above
+    // it), and PPC declares none either — so both stamp nothing rather than reporting the caller's
+    // frame as this function's declaration ranks.
+    //
+    // AND IT ASKS `declaredLocals`, NOT `ownedLocals`, which is a different question with a
+    // different answer under agbcc — the outgoing stack-argument area is storage the function owns
+    // and does not declare. The two ranges are equal under Thumb today only because `prefixStored`
+    // declines every function with an outgoing area; see `declaredLocals`' own doc for the
+    // measurement and for what lifting that decline obliges.
+    if (!inRange(off, model().declaredLocals)) {
+      return;
+    }
+    // ONE CLASS INSIDE THE PARTITION IS STILL NOT A DECLARATION RANK, and NOTHING HERE REFUSES IT.
+    // A stack AGGREGATE the frontend decomposed into per-word keys yields several `sp@k`s that are
+    // fields of ONE declared object, not several declared scalars — and it reaches the stamp
+    // because a non-address-taken array never mints an `laddr`, which is the only aggregate the
+    // structurer's `frame` refusal catches. It is the only class the ordering meets in the wild:
+    // over 2,463 real agbcc functions (158 sa3 + klonoa listings) exactly one carries two
+    // slot-carrying locals, sa3 `sub_80617E0`, whose [sp,#0]..[sp,#0xc] are the four words of
+    // `Vec2_32 sp00[2]` (its own preprocessed source declares it), with the only genuine reload
+    // spill at [sp,#0x10].
+    //
+    // That one is declined downstream — its words land under two names at offset 12, and
+    // `l3/slotorder.ts`'s injectivity refusal reads a duplicate as evidence reload did not produce
+    // — but the class is NOT covered by that refusal: an aggregate whose words reach L3 under
+    // distinct names at distinct offsets is injective and would be ordered. FLIP CONDITION: once
+    // stack-array recovery declares `sp00[2]`, ordering an aggregate against a reload spill by the
+    // minimum of its element offsets is WRONG — `assign_stack_local` runs before reload and puts
+    // every array below every spill slot regardless of declaration rank. The licence this
+    // capability rests on (reload hands a spilled pseudo its slot by `expand_decl` rank) is about
+    // separately declared SCALARS; intra-aggregate offsets are fixed by the aggregate's layout at
+    // expand time.
+    //
+    // UNION, not a choice (ir/core.ts `SlotHomes`): whether the earlier declaration rank is the
+    // lower or the higher offset is a per-COMPILER fact, and this builder is handed a name, a
+    // block count, a predecessor list and a live-in model — no target. `l3/slotorder.ts` reduces.
+    // A GUARD WITH NO CORPUS INHABITANT: over both benchmark tiers no value is ever written to two
+    // DIFFERENT slots, so the `else` below has never produced a set of size two on a real input.
+    const prev = slotHomes.get(v);
+    if (prev === undefined) {
+      slotHomes.set(v, new Set([off]));
+    } else {
+      prev.add(off);
+    }
+  };
+  const forgetOrder = (p: Value) => {
+    for (const m of writeOrder.lastWrite.values()) {
+      m.delete(p);
+    }
+  };
 
   const writeVar = (reg: string, b: number, v: Value) => {
+    noteSlotHome(reg, v);
     writtenSinceCall[b].add(reg);
     defs[b].set(reg, v);
+    lastWriteAt[b].set(reg, writeCount[b]++);
   };
   const readVar = (reg: string, b: number): Value => defs[b].get(reg) ?? readRecursive(reg, b);
 
@@ -113,6 +320,10 @@ export function makeSsaBuilder(name: string, blockCount: number, preds: number[]
     irBlocks[b].params.push(phi);
     phiBlock.set(phi, b);
     phiKey.set(phi, reg);
+    // A slot that arrives as a PHI — a loop header reading back what an earlier iteration spilled
+    // — is the same frame coordinate under a block param, and the structurer names it like any
+    // other value, so it carries the home too.
+    noteSlotHome(reg, phi);
     defs[b].set(reg, phi); // set before wiring operands to break cycles
     return phi;
   };
@@ -128,7 +339,29 @@ export function makeSsaBuilder(name: string, blockCount: number, preds: number[]
     // manufacture a join (and a phi) where there is none.
     const ps = distinctPreds(b);
     if (ps.length === 0) {
-      // live-in with no predecessor: an incoming argument register → function parameter.
+      // A live-in with no predecessor is a value this function never produced: an incoming argument,
+      // or storage it allocated and never wrote. WHICH ONE is the partition's answer, in whichever
+      // coordinate the key names. The key spelling cannot decide a slot on its own — `sp@40` is a
+      // local on one ABI and the caller's fifth argument on another — so a slot in neither range is
+      // refused rather than guessed. A register is decided by the calling convention instead of by
+      // a measurement: a caller cannot pass a value in a register the ABI does not pass arguments
+      // in, so a read of one before any write is an uninitialised local.
+      const off = slotKeyOffset(reg);
+      if (off !== null && !inRange(off, model().ownedLocals) && !inRange(off, model().callerParams)) {
+        throw new FrontendUnsupportedError(
+          `cannot lift '${name}': ${reg} is read on a path that never stores it, and lies outside ` +
+            `this function's frame partition (uninitialised local, or storage it does not own) — not modelled`,
+        );
+      }
+      const uninitialised =
+        off !== null ? inRange(off, model().ownedLocals) : (model().uninitRegs?.includes(reg) ?? false);
+      if (uninitialised) {
+        const op = mkOp('undef', { results: [mkValue(T.unk(32))], attrs: { key: reg } });
+        irBlocks[b].ops.unshift(op); // ahead of everything in a block that nothing precedes
+        defs[b].set(reg, op.results[0]);
+        return op.results[0];
+      }
+      // an incoming argument register → function parameter.
       // If one was already asserted for this key (ensureParam), adopt it — minting a second
       // parameter for the same key would put the key in the signature twice.
       const obliged = obligedParams[b].get(reg);
@@ -150,12 +383,21 @@ export function makeSsaBuilder(name: string, blockCount: number, preds: number[]
     }
     // sealed join: create the phi and wire every predecessor's terminator arg now.
     const phi = newPhi(reg, b);
-    addPhiOperands(reg, b);
+    addPhiOperands(reg, b, phi);
     return phi;
   };
-  const addPhiOperands = (reg: string, b: number) => {
+  // The ONE point that knows the phi, its key and each predecessor together, which is what the
+  // write-order record is keyed by. `phi` is passed rather than looked up: by the time a deferred
+  // phi is wired the block may have written its key again, so `defs[b]` no longer names it.
+  const addPhiOperands = (reg: string, b: number, phi: Value) => {
     for (const p of distinctPreds(b)) {
       appendSuccessorArg(p, b, readVar(reg, p));
+      const at = lastWriteAt[p].get(reg);
+      if (at !== undefined) {
+        const rec = writeOrder.lastWrite.get(irBlocks[p]) ?? new Map<Value, number>();
+        rec.set(phi, at);
+        writeOrder.lastWrite.set(irBlocks[p], rec);
+      }
     }
   };
   // Append `arg` to EVERY successor edge of predecessor p that targets block b.
@@ -179,8 +421,8 @@ export function makeSsaBuilder(name: string, blockCount: number, preds: number[]
       return;
     }
     sealed[b] = true; // set first: addPhiOperands may recurse back here
-    for (const reg of incompletePhis[b].keys()) {
-      addPhiOperands(reg, b);
+    for (const [reg, phi] of incompletePhis[b]) {
+      addPhiOperands(reg, b, phi);
     }
     incompletePhis[b].clear();
   };
@@ -233,10 +475,12 @@ export function makeSsaBuilder(name: string, blockCount: number, preds: number[]
     hasReachingDef,
     noteCall: (b: number) => {
       callsIn.add(b);
-      writtenSinceCall[b] = new Set(); // the callee clobbers the caller-saved registers
+      // the callee clobbers the caller-saved registers, its own result register included — see
+      // the ordering contract on the interface
+      writtenSinceCall[b] = new Set();
     },
-    recordGuessedCall: (op: Op, b: number, argRegs: string[]) => {
-      argRegsSeen = argRegs;
+    recordGuessedCall: (op: Op, b: number, abi: { argRegs: string[]; returnReg: string }) => {
+      abiSeen = abi;
       guessedCalls.push({
         block: b,
         op,
@@ -252,17 +496,41 @@ export function makeSsaBuilder(name: string, blockCount: number, preds: number[]
       // Guessed arities counted argument registers by reaching definition alone; now that every
       // block's calls are known, drop the ones an intervening call had already clobbered.
       if (guessedCalls.length) {
+        const calleeResults = new Set<Value>();
+        for (const b of irBlocks) {
+          for (const op of b.ops) {
+            if (op.opcode === 'call') {
+              for (const r of op.results) {
+                calleeResults.add(r);
+              }
+            }
+          }
+        }
         trimClobberedCallArgs({
-          argRegs: argRegsSeen,
+          argRegs: abiSeen.argRegs,
+          returnReg: abiSeen.returnReg,
+          calleeResults,
           preds,
           freshAtEnd: writtenSinceCall,
           callsIn,
           sites: guessedCalls,
         });
       }
+      irBlocks.forEach((blk, i) => writeOrder.writes.set(blk, writeCount[i]));
       simplifyTrivialPhis(fn, (p) => {
         phiBlock.delete(p);
         phiKey.delete(p);
+        forgetOrder(p);
+      });
+      // Then the phis nothing reads at all — a register two paths leave holding different junk
+      // (a loop counter after its last use, a scratch the epilogue overwrites) still joins as a
+      // phi, and a dead phi is not junk downstream: its edge args become post-loop copies in the
+      // emitted C and block gates keyed on "this exit carries nothing". Order matters only for
+      // economy: trivial-phi removal can orphan a phi's last reader, never the reverse.
+      pruneDeadParams(fn, (p) => {
+        phiBlock.delete(p);
+        phiKey.delete(p);
+        forgetOrder(p);
       });
       // A STACK SLOT MAY NEVER LEAVE AS AN ENTRY PARAMETER. A slot is memory the function itself
       // allocated, so its value can only come from a store the function made; arriving as a live-in
@@ -286,10 +554,15 @@ export function makeSsaBuilder(name: string, blockCount: number, preds: number[]
       // semantic postcondition, and a postcondition enforced by convention is not enforced.
       for (const p of irBlocks[0].params) {
         const key = paramReg.get(p) ?? phiKey.get(p);
-        if (key?.startsWith(SLOT_PREFIX)) {
+        // The SAME rule the mint site used, over the same ranges, so the two cannot disagree. A
+        // slot that reached the signature is either owned storage (which should have become an
+        // `undef`) or unclassified — both are bugs, and this is where a per-read test cannot be
+        // total, so it is asserted over the finished function.
+        const koff = key === undefined ? null : slotKeyOffset(key);
+        if (koff !== null && !inRange(koff, model().callerParams)) {
           throw new FrontendUnsupportedError(
-            `cannot lift '${name}': stack slot ${key} is read on a path that never stores it ` +
-              `(partially-initialised local) — not modelled`,
+            `cannot lift '${name}': ${key} is read on a path that never stores it ` +
+              `(partially-initialised local, or storage this function does not own) — not modelled`,
           );
         }
       }
@@ -329,6 +602,12 @@ export interface GuessedCallSite {
 
 export interface CallArgTrim {
   argRegs: string[];
+  /** the ABI return register. Load-bearing only where it IS `argRegs[0]` (ARM r0, PPC r3) — that
+   *  aliasing is what makes a callee's result indistinguishable from caller-side argument setup. */
+  returnReg: string;
+  /** every value a `call` op produced. Tells a callee's own return apart from a join that merely
+   *  PASSES THROUGH one, which the register file cannot: both leave argument 0 unfresh. */
+  calleeResults: ReadonlySet<Value>;
   /** one entry per CFG edge, as passed to {@link makeSsaBuilder} */
   preds: number[][];
   /** per block: the keys written since its LAST call (since its start if it makes none). Indexed by
@@ -351,17 +630,21 @@ export interface CallArgTrim {
  *  SCOPE: this closes the arguments an intervening CALL disproves, which is the common case in real
  *  code. It does not close the rest — a dead value the compiler happened to leave in the next
  *  argument register with no call in between still reads as an argument, and nothing about the
- *  register file can say otherwise. Only a declared prototype closes those.
+ *  register file can say otherwise. A declared prototype closes those outright; short of one, the
+ *  narrower reading is recorded here and offered as a ranked candidate ({@link narrowToSetupArgs}).
  *
  *  A must-analysis: a register is FRESH at a point iff on EVERY path reaching it, it was written
  *  after the last call. The entry block starts all-fresh (those are the caller's own arguments).
- *  The result only ever SHRINKS an arity — a register the analysis cannot prove clobbered stays an
- *  argument — so no real argument can be dropped by it.
+ *  The result only ever SHRINKS an arity, but two of the shrinks are REFUSALS and not proofs, so a
+ *  real argument CAN go with them: a fresh register above a hole stops the run (a 64-bit return
+ *  occupies two registers and the frontend cannot express one, so the caller's r2 goes with the
+ *  unfillable r1), and a callee's return read as the callee's own drops an argument a `g(f())`
+ *  source did pass. A declared prototype is what closes either.
  *
  *  Frontend-agnostic: the caller supplies what its own lifting scan observed, so nothing here
  *  re-derives which instruction writes which register. */
 export function trimClobberedCallArgs(inp: CallArgTrim): void {
-  const { argRegs, preds, freshAtEnd, callsIn, sites } = inp;
+  const { argRegs, returnReg, calleeResults, preds, freshAtEnd, callsIn, sites } = inp;
   const blockCount = freshAtEnd.length;
   const all = () => new Set(argRegs);
   const localEnd = (b: number) => freshAtEnd[b] ?? new Set<string>();
@@ -400,23 +683,115 @@ export function trimClobberedCallArgs(inp: CallArgTrim): void {
       freshOut[b] = fout;
     }
   }
-  for (const s of sites) {
-    const fresh = s.afterCallInBlock ? s.freshBefore : new Set([...freshIn[s.block], ...s.freshBefore]);
-    let n = 0;
+  const runOfFresh = (fresh: Set<string>, from: number): number => {
+    let n = from;
     while (n < argRegs.length && fresh.has(argRegs[n])) {
       n++;
     }
+    return n;
+  };
+  // A LATER argument register this caller set up proves the call takes arguments at all, and
+  // argument 0 sits below one that is proven — so it is being passed too, whatever put it there
+  // (`bl __mulsf3; add r1,r4,#0; bl __addsf3` is `__addsf3(__mulsf3(a, b), c)`).
+  const setsUpLater = (fresh: Set<string>): boolean => argRegs.some((r, i) => i > 0 && fresh.has(r));
+  // THE RETURN REGISTER IS NOT ARGUMENT SETUP. Where the ABI aliases it onto argument 0, the
+  // frontends record a call's clobber AFTER its own result, so the result leaves the register
+  // UNfresh here. That disproves caller setup only where the callee's return is BOTH what the
+  // register still holds and all the site has to go on: with a later register set up (above), or
+  // with a value no call produced — a join of one path's return with another path's caller-computed
+  // value — argument 0 is a real argument, and dropping the second kind would delete the
+  // instructions that computed it.
+  //
+  // With neither, the site carries no argument evidence at all: `bl f; bl g` is `f(); g();` as
+  // readily as `g(f())`, the two spell the same bytes on this ABI, and only the nested one needs
+  // `f` to return a value and `g` to accept one — a spelling the project's own header rejects
+  // outright when it does not. A declared prototype never reaches here, and stays the way `g(f())`
+  // is recovered.
+  const argcAt = (fresh: Set<string>, op: Op): number => {
+    if (argRegs[0] !== returnReg || fresh.has(argRegs[0])) {
+      return runOfFresh(fresh, 0);
+    }
+    if (setsUpLater(fresh) || !calleeResults.has(op.operands[0])) {
+      return runOfFresh(new Set([argRegs[0], ...fresh]), 0);
+    }
+    return 0;
+  };
+  for (const s of sites) {
+    const fresh = s.afterCallInBlock ? s.freshBefore : new Set([...freshIn[s.block], ...s.freshBefore]);
+    const n = argcAt(fresh, s.op);
     if (n < s.op.operands.length) {
       s.op.operands.length = n;
     }
+    // The SHORTER arity the same evidence also allows, recorded for {@link narrowToSetupArgs}: the
+    // run over what THIS BLOCK wrote, dropping the registers that are fresh only because no call
+    // stands between here and wherever they were last written. Both readings stay live, so this one
+    // is recorded rather than applied. A survivor is what it drops, so the join clause above has no
+    // place here — but `setsUpLater` still does: a register this block set up two instructions
+    // before the call is not something the narrower reading may call dead.
+    const localFresh = setsUpLater(s.freshBefore) ? new Set([argRegs[0], ...s.freshBefore]) : s.freshBefore;
+    const local = Math.min(runOfFresh(localFresh, 0), s.op.operands.length);
+    if (local < s.op.operands.length) {
+      setupArgc.set(s.op, local);
+    }
+  }
+}
+
+/** The narrower arity {@link narrowToSetupArgs} would cut each guessed call to. A SIDE table and
+ *  not an attr: this is a fact about one LIFT, not part of the IR the rest of the pipeline compares
+ *  and prints — `structure/hazards.ts` decides two ops equal by comparing their attrs verbatim, so
+ *  an attr only one of an otherwise-matching pair carries would cost a recovery. */
+const setupArgc = new WeakMap<Op, number>();
+
+/** Whether anything in `fn` HAS the narrower reading — the lever's gate, so the ~99% of functions
+ *  with no narrowable call cost no re-lift. Read it off the lift itself: a later pipeline stage may
+ *  replace a `call` op (softdiv rewrites one to a division), and the table is keyed by op. */
+export function hasSetupArgsNarrowing(fn: Fn): boolean {
+  return fn.blocks.some((b) => b.ops.some((op) => setupArgc.has(op)));
+}
+
+/** Cut every guessed call to the arity its OWN BLOCK set up, and report whether anything moved.
+ *
+ *  `trimClobberedCallArgs` keeps an argument register whose value merely survives from an earlier
+ *  block, because compiled code really does pass one that way: agbcc leaves a value already in r0
+ *  where it is and branches to the call (`if (x) f(x);` is `cmp r0,#0; beq; bl f`, no setup at
+ *  all). Those are also the bytes `if (x) f();` compiles to, so usually neither reading is
+ *  refutable — but where the guard is an EQUALITY the compiler proves the argument constant and
+ *  has to materialize it (`if (x == 0) f(x);` opens the arm with `mov r0,#0`), and the absence of
+ *  that instruction rules the wider reading out. Which case a function is in is not knowable from
+ *  the register file, and is exactly what a differ decides. Hence a ranked candidate rather than a
+ *  default: the arm that passes only what the calling block itself put there.
+ *
+ *  Applies only to arities that were GUESSED — a declared prototype never recorded the fact. */
+export function narrowToSetupArgs(fn: Fn): boolean {
+  let changed = false;
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      const setup = setupArgc.get(op);
+      if (setup !== undefined && setup < op.operands.length) {
+        op.operands.length = setup;
+        changed = true;
+      }
+    }
+  }
+  if (changed) {
+    // A dropped argument can be a join's last reader, and `finish()` pruned the dead phis before
+    // this reading existed. Left in, the phi's edge args render as assignments to a local nothing
+    // reads (`v0 = UpdateWorldMapCursor();`) — see the note on the prune in `finish`.
+    pruneDeadParams(fn);
   }
+  return changed;
 }
 
 /** The stack-slot key both the MIPS and Thumb frontends use for a word-sized local in the
- *  function's own frame. Shared so the two spell it identically and `assertNoSlotEscaped` can
+ *  function's own frame. Shared so the two spell it identically and the frame-partition rule can
  *  recognise either frontend's slots. See the virtual-key note in the module header. */
 const SLOT_PREFIX = 'sp@';
 export const stackSlotKey = (off: number): string => `${SLOT_PREFIX}${off}`;
+/** The byte offset a slot key names, or null if `key` is not a slot key at all (an ordinary
+ *  register). The grammar stays owned by this module — {@link LiveInModel} is expressed in the same
+ *  coordinate, so the classification rule can be generic. */
+export const slotKeyOffset = (key: string): number | null =>
+  key.startsWith(SLOT_PREFIX) ? Number(key.slice(SLOT_PREFIX.length)) : null;
 
 /** Order the TRUE entry block's parameters by ABI argument register, so downstream naming
  *  (`a0`, `a1`, …) matches the calling convention, not first-read order (a callee-saved copy can