@asmlift/core 0.4.0 → 0.6.0

package/src/ir/alias.ts

@@ -0,0 +1,129 @@
+// asmlift — memory DISJOINTNESS: the one place that answers "could this write change what that
+// read sees". A pure query over L2 (typed SSA); no structuring or emission state.
+//
+// It exists because the answer was being given at three different strengths in three places, the
+// weakest one governing the most common case (the materialization model's multi-render load rule,
+// which barred on ANY write). A read that is barred by a store to an unrelated global is spelled
+// as a named local the source never had — the "value home" defect the round-5 dogfood measured as
+// its single highest cost. One predicate, one strength, one place to sharpen.
+//
+// The rule is deliberately NAME-based and deliberately narrow:
+//
+//   • two DIFFERENT named globals are different objects, so a store through one can never change
+//     what a read of the other sees. That is a C guarantee about distinct declared objects, not a
+//     heuristic about what the compiler happened to do.
+//   • name comparison suffices because the pool promotion picks ONE canonical name per address,
+//     so a single cell cannot appear under two names within one function (frontend/thumb.ts).
+//   • anything that does not resolve to a name — a materialized base, a variable index, a pointer
+//     parameter — is unknown, and unknown BARS. A call or an `opaque` bars unconditionally: it may
+//     write anything.
+//
+// Being conservative here costs at most a match (an extra local the compiler would have folded);
+// being wrong here is a silently wrong read. Every relaxation must keep that asymmetry.
+//
+// A SECOND PREMISE LIVES HERE, on different evidence and for a different clientele:
+// `disjointConstSlots` — the same base VALUE, both accesses at a constant offset and width, and
+// byte ranges that do not overlap. Where the name rule above is about two declared OBJECTS, this
+// one is about two byte ranges of whatever single object one base denotes, so it needs no name and
+// asserts nothing about which object that is: `p->field_0` and `p->field_4` are different cells
+// whether `p` points at a global, a local or a parameter. Narrow in the same direction — a
+// different base value or a runtime index BARS — and it COMPOSES with the name rule rather than
+// widening it: a caller asks whichever question its evidence can answer, and a bar from either
+// stands.
+//
+// ONE OTHER PLACE ANSWERS THE SAME QUESTION, on a different premise, and it is not reachable from
+// here: `l3/unreduce.ts`'s `moved-read-aliasable` gate, which asks whether moving a read down to
+// the point that re-reads it lets the writes it crosses change what it sees. It runs on L3, where there are no `Value`s
+// and no `defs` map to resolve, and the addresses it is about are RAW CONSTANTS — precisely the
+// case in which `globalCellOf` returns null and everything here bars. What it uses instead is the
+// TARGET's declared device-register range (`capabilities.deviceRegisters`): a write to a hardware
+// register is not a write to any object a C program declares, so no STORE THE C PERFORMS over that
+// span can change an ordinary read. That is a fact about the board rather than about C, which is
+// why it is a target capability and not a rule in this file. The asymmetry above is kept in both:
+// everything the range does not place BARS.
+//
+// AND IT IS NOT THE WHOLE ANSWER, which this comment used to claim it was. The sentence above
+// covers the CPU's stores and stops there — a DMA controller reads a control word and then WRITES
+// ORDINARY MEMORY on the program's behalf, so a span whose every write is a "device register"
+// write can still rewrite the cell a moved read reads. Executed with the transfer modelled, the
+// admitted candidate turned a clean destination walk into wild writes. The second half of the
+// claim is therefore a second datum, `capabilities.deviceMemoryWriters`, and what it does not
+// settle is settled by the DIFFER instead (`Candidate.matchOnly`) rather than by a wider licence.
+// The lesson generalises past this file: a premise about the board is still a premise, and one
+// stated as an aside in a comment gets copied rather than checked — this one reached four files
+// before anything executed it.
+import { type Op, type Value } from './core';
+
+/** A byte cell of a named global: the symbol plus the byte offset within it. */
+export interface GlobalCell {
+  name: string;
+  byte: number;
+}
+
+/**
+ * The named global cell an address value denotes, resolved through defs alone — `gaddr`, or
+ * `gaddr + const` in either operand order — plus the access's own `off`. Null when the address
+ * does not reduce to a name (a materialized base, a runtime index, a pointer): the caller must
+ * then treat it as unknown memory.
+ */
+export function globalCellOf(defs: Map<Value, Op>, addr: Value, off: number): GlobalCell | null {
+  const d = defs.get(addr);
+  if (d?.opcode === 'gaddr') {
+    return { name: d.attrs.sym as string, byte: off };
+  }
+  if (d?.opcode === 'add' && d.operands.length === 2) {
+    for (const [x, y] of [
+      [d.operands[0], d.operands[1]],
+      [d.operands[1], d.operands[0]],
+    ] as const) {
+      const g = defs.get(x);
+      const c = defs.get(y);
+      if (g?.opcode === 'gaddr' && c?.opcode === 'const') {
+        return { name: g.attrs.sym as string, byte: (c.attrs.value as number) + off };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Are these two accesses through ONE base provably different byte cells — same base value, both at
+ * a constant offset and width, ranges non-overlapping? The everyday struct interleave
+ * `… = p->field_0; p->field_4 = …`, where the store cannot change what the load sees even though
+ * neither side resolves to a named global.
+ *
+ * False on anything less certain, which is what the callers need: a different base value, or an
+ * access with no constant slot to compare. `off`/`width` are contract-required on `load`/`store`
+ * (ir/opcodes.ts), so the casts are defensive; the comparisons are the ones the fused call site in
+ * structure/analysis.ts made, NaN behaviour included.
+ */
+export function disjointConstSlots(load: Op, store: Op): boolean {
+  if (store.operands[0] !== load.operands[0]) {
+    return false;
+  }
+  const lo = load.attrs.off as number,
+    lw = load.attrs.width as number;
+  const so = store.attrs.off as number,
+    sw = store.attrs.width as number;
+  return so + sw <= lo || lo + lw <= so;
+}
+
+/**
+ * "May op `x` write the global named `sym`?" — the predicate a read of `sym` must clear on every
+ * path between its def and each of its render positions (analysis.ts `memWriteBetween`).
+ *
+ * Calls and opaques always may. A store/astore may unless its base resolves to a DIFFERENT named
+ * global. Everything else (pure arithmetic, loads) never writes.
+ */
+export function mayWriteGlobal(defs: Map<Value, Op>, sym: string): (x: Op) => boolean {
+  return (x: Op): boolean => {
+    if (x.opcode === 'call' || x.opcode === 'opaque') {
+      return true;
+    }
+    if (x.opcode !== 'store' && x.opcode !== 'astore') {
+      return false;
+    }
+    const t = globalCellOf(defs, x.operands[0], 0);
+    return !(t && t.name !== sym);
+  };
+}

package/src/ir/bits.ts

@@ -0,0 +1,75 @@
+// KNOWN BITS over SSA values — an L2 fact about `Fn`, answered from declarations and instructions
+// alone.
+//
+// This is not a spelling rule and it says nothing about C. It answers "how many significant bits
+// can this value have", which is what every rule that needs to know whether a narrower container
+// LOSES something must ask: the mask-and-insert fold's truncation bound (structure.ts), and the
+// same question raise/narrowlocal.ts states for itself as "every value arriving on an in-edge is
+// itself an extension of at most this width, or a constant".
+//
+// It is a function over `Fn` rather than a closure inside a rendering pass so that a test can ask
+// it directly: reachable only through emitted C, a wrong answer for one opcode reads as a silent
+// wrong address in a row nobody is looking at.
+import type { Op, Value } from './core';
+
+/** A materialized def emits its own named temp, so its value is a VARIABLE at every use — never a
+ *  literal this analysis may fold through. Callers that have no materialization model pass none. */
+export interface BitsCtx {
+  defs: Map<Value, Op>;
+  materialize?: ReadonlySet<Op>;
+  /** A bound a CALLER already knows for a def — the escape hatch for facts this layer cannot see,
+   *  such as a bitfield read a rendering pass has recognized and can price from the declaration.
+   *  Returning null defers to the rules below. A caller's answer must be a bound on the VALUE, not
+   *  on the container it came out of: a SIGNED narrow read carries all 32 bits however few the
+   *  declaration allots it. */
+  bound?: (d: Op) => number | null;
+}
+
+/** A def's value as a compile-time CONSTANT, or null. A thumb `bic` lifts as `and` with `neg`/
+ *  `not` of a constant, so those two spellings fold; anything else is not a literal. */
+export function constMask(ctx: BitsCtx, v: Value): number | null {
+  const d = ctx.defs.get(v);
+  if (!d || ctx.materialize?.has(d)) {
+    return null;
+  }
+  if (d.opcode === 'const') {
+    return (d.attrs.value as number) | 0;
+  }
+  if ((d.opcode === 'neg' || d.opcode === 'not') && d.operands.length === 1) {
+    const a = constMask(ctx, d.operands[0]);
+    return a === null ? null : (d.opcode === 'neg' ? -a : ~a) | 0;
+  }
+  return null;
+}
+
+/** An UPPER BOUND on the significant bits of a value, or 32 when nothing bounds it. Every answer
+ *  below 32 comes from an instruction or from a caller's declaration-backed `bound`:
+ *    · a zero-fill shift right by n leaves 32 - n;
+ *    · a load leaves its width in bits — UNLESS it sign-extends, which leaves all 32;
+ *    · an `and` with a non-negative constant leaves that constant's top set bit.
+ *  A SIGNED anything is 32: sign extension sets the high bits, and a bound that ignores it turns a
+ *  correct refusal into a plausible wrong answer. */
+export function provableBits(ctx: BitsCtx, v: Value): number {
+  const d = ctx.defs.get(v);
+  if (!d) {
+    return 32;
+  }
+  const given = ctx.bound?.(d);
+  if (given !== null && given !== undefined) {
+    return given;
+  }
+  if (d.opcode === 'shr_u' && d.operands.length === 1 && typeof d.attrs.imm === 'number') {
+    return 32 - (d.attrs.imm as number);
+  }
+  if (d.opcode === 'load') {
+    return d.attrs.signed === true ? 32 : (d.attrs.width as number) * 8;
+  }
+  const m =
+    d.opcode === 'const'
+      ? constMask(ctx, v)
+      : d.opcode === 'and'
+        ? (d.operands.map((o) => constMask(ctx, o)).find((x) => x !== null) ??
+          (typeof d.attrs.imm === 'number' ? (d.attrs.imm as number) | 0 : null))
+        : null;
+  return m !== null && m >= 0 ? 32 - Math.clz32(m) : 32;
+}

package/src/ir/core.ts

@@ -42,6 +42,122 @@ export interface Block {
 export interface Fn {
   name: string;
   blocks: Block[];
+  /** L1 SIDE DATA (see {@link WriteOrder}); set by the SSA builder, `undefined` on parsed IR.
+   *  REQUIRED, not optional, and the `| undefined` is the point: every place that builds an `Fn`
+   *  — the copy in `cli/src/report.ts` most of all — has to say what it does with the record, so
+   *  a side table added to `Fn` cannot be dropped by a copy that simply never mentions it. */
+  writeOrder: WriteOrder | undefined;
+  /** L1 SIDE DATA (see {@link SlotHomes}); set by the SSA builder, `undefined` on parsed IR.
+   *  REQUIRED-but-possibly-undefined for exactly the reason `writeOrder` is: an optional field is
+   *  silently dropped by a copy that never mentions it (`cli/src/report.ts` structuredCloneFn says
+   *  so at its own definition), and a fact the structurer reads but the score probe's clone drops
+   *  makes that probe's delta a fact about a program asmlift does not emit. */
+  slotHomes: SlotHomes | undefined;
+}
+
+/** Which `[sp,#k]` the machine homed a value at — the frame coordinate, carried L1 → L3.
+ *
+ *  The coordinate exists only in the frontends: they record a word sp-relative slot's value in SSA
+ *  under the key `sp@k` (`frontend/ssa.ts` stackSlotKey) instead of emitting a store through `sp`,
+ *  so by L2 the value is an ordinary SSA value and `k` is gone. This map is where `k` survives.
+ *
+ *  A KEY IS NOT A FRAME COORDINATE, and the frontends differ on exactly that. `sp@40` is a local
+ *  on one ABI and the caller's fifth argument on another, so the shared stamp asks the frontend's
+ *  own `LiveInModel.declaredLocals` and refuses an offset outside it — Thumb declares a range,
+ *  MIPS and PPC declare no partition and so stamp nothing. An entry here therefore means "storage
+ *  this function DECLARES, homed at k", not "some sp-relative key".
+ *
+ *  DECLARES, NOT OWNS, AND THE DIFFERENCE IS AN AGBCC FACT WITH A LIVE DEPENDENCY: `ownedLocals`,
+ *  the partition a def-less READ asks, admits agbcc's outgoing stack-argument area, and an offset
+ *  there is an ABI position rather than an `expand_decl` rank. Under Thumb the two ranges are
+ *  written equal, and a decline rather than a proof is what makes that safe — see `declaredLocals`
+ *  (frontend/ssa.ts) for the dependency and what lifting it obliges.
+ *
+ *  ONE consumer reads it for its content — the structurer, which turns it into
+ *  `SFn.locals[i].slots`; everything else only carries it (`replaceAllUsesWith`, the report's
+ *  clone). It exists because a compiler that hands out frame slots by declaration rank makes the
+ *  source's DECLARATION ORDER observable in the object. Absent entries are the norm: most values
+ *  are never spilled, and a value with no entry simply has no frame coordinate to order by.
+ *
+ *  A SET, AND NOTHING MERGES IT. Every place two homes meet — this map's own writes, a value that
+ *  inherits another's uses in `replaceAllUsesWith`, several values under one name in the
+ *  structurer's naming walk, two named locals absorbed into one by `l3/coalesce.ts` — takes the
+ *  UNION. None of those four sites picks an offset, because picking one is a question about the
+ *  TARGET and not one of them holds a target: the SSA builder takes `(name, blockCount, preds,
+ *  liveInOf)`, `replaceAllUsesWith` takes an `Fn`, and `localsAfterMerge` takes a locals list.
+ *
+ *  The reduction happens ONCE, in `l3/slotorder.ts`, which is the one place that holds
+ *  `SFn.slotOrder`. Earliest declaration rank is the LOWEST offset under an ascending frame and
+ *  the HIGHEST under a descending one, so a merge site that took an END of the set would be
+ *  spelling one direction's answer under a neutral name: right for agbcc, inverted for a target
+ *  whose measured direction is `descending` (ido7.1). Reducing where the direction is in hand
+ *  makes it one comparator rather than four copies of a sentence.
+ *
+ *  It is still a POLICY and not a proof: the machine homed one value at two offsets and the source
+ *  declared one local, so no reading of the asm recovers which rank the source had. What the union
+ *  buys is that the choice is made where it can be made correctly.
+ *
+ *  NO `ir/verify.ts` RULE, unlike `writeOrder`: that record is a per-FUNCTION measurement with a
+ *  mixed state to reject (some blocks measured, others not). A slot home is per VALUE and
+ *  legitimately absent on almost every value, so there is no mixed state for a verifier to catch
+ *  and a rule would never fire. */
+export type SlotHomes = Map<Value, Set<number>>;
+
+/** The order in which each block WROTE the keys its successors' block-params stand for — a
+ *  measurement the SSA builder makes and nothing downstream can recover, because the value graph
+ *  keeps no trace of it: a register copy is the same SSA value under a new key, and once a key's
+ *  value is a successor's edge argument the write that put it there has no op of its own.
+ *
+ *  The structurer needs it to spell a parallel copy in the compiler's own order. The compiler
+ *  established the block's final register values in SOME order, and in a cyclic copy the register
+ *  that reached its final value FIRST is the one whose old value had to be saved elsewhere — the
+ *  temp — because the copies that still read that old value run after it. Sorting an edge's copies
+ *  by this record puts that copy first, so the sequentializer's first-copy spill reproduces the
+ *  compiler's temp instead of guessing from def positions, where an in-block def and an incoming
+ *  param have no common scale. LAST write, not first: a predecessor commonly writes one key several
+ *  times (1,867 of 5,283 records over three checkouts), and the edge carries what the last left.
+ *
+ *  Keyed by OBJECTS (the predecessor block, the destination param), never by arg position, so the
+ *  param splices in `ir/simplify.ts` cannot leave it stale. A pass that moves one block's ops into
+ *  another owes `foldWriteOrder`.
+ *
+ *  MEASUREMENT IS PER FUNCTION, NOT PER BLOCK. The SSA builder measures every block it builds, so
+ *  `writes` covers every block or the record is absent/empty (parsed or hand-built IR — nobody
+ *  measured this function); `ir/verify.ts` rejects the mixed state, and says there what that check
+ *  does and does not reach. A reader still asks per BLOCK (`structure.ts` `predIsMeasured`), which
+ *  is how a wholly unmeasured fn takes the def-position proxy without a second query — but a
+ *  missing entry means "no frontend measured this function", never "this block wrote nothing". The
+ *  latter is an entry whose `lastWrite` holds no destination of the edge, its own case with its own
+ *  golden. */
+export interface WriteOrder {
+  /** pred → (param of a successor → ordinal, among the pred's writes, of its LAST write to the key
+   *  that param stands for). No entry ⇒ the pred did not write the key; the arg passes through. */
+  lastWrite: Map<Block, Map<Value, number>>;
+  /** Every measured block → how many writes it made. Membership is the "measured" test. */
+  writes: Map<Block, number>;
+}
+
+/** `from`'s writes now happen at the END of `into` — the bookkeeping a pass owes when it moves one
+ *  block's ops (or the edge copies an empty block stood for) into another. Each of `from`'s records
+ *  lands under `into` at its ordinal plus `into`'s own write count, so a key `into` wrote itself
+ *  still sorts first and a later fold onto `into` composes the same way. REFUSES when `into` was
+ *  never measured: a block no builder counted has no place to put `from`'s writes after, and
+ *  reading it as "wrote nothing of its own" would be a guess. `from`'s own entries stay; a block a
+ *  pass removes from the CFG is never read again. */
+export function foldWriteOrder(order: WriteOrder | undefined, from: Block, into: Block): void {
+  const base = order?.writes.get(into);
+  if (order === undefined || base === undefined) {
+    return;
+  }
+  const moved = order.lastWrite.get(from);
+  if (moved !== undefined) {
+    const rec = order.lastWrite.get(into) ?? new Map<Value, number>();
+    for (const [param, at] of moved) {
+      rec.set(param, base + at);
+    }
+    order.lastWrite.set(into, rec);
+  }
+  order.writes.set(into, base + (order.writes.get(from) ?? 0));
 }
 
 export function mkValue(type: IrType): Value {
@@ -58,10 +174,53 @@ export function mkOp(opcode: Opcode, o: Partial<Op> = {}): Op {
   };
 }
 
+/** A block's last op — its terminator on well-formed IR, `undefined` on a block with no ops.
+ *
+ *  `ir/verify.ts` rejects an empty block and every entry path verifies before raising, so the
+ *  `undefined` case is reachable only from hand-built IR: a test, or a pass reading a block it is
+ *  itself midway through rewriting. A reader that DECIDES something off the terminator therefore
+ *  spells that case (`terminator(b)?.opcode === 'br'`); one that has already established the shape
+ *  indexes `b.ops` directly, so a broken invariant surfaces as a TypeError rather than as a silent
+ *  skip. */
+export function terminator(b: Block): Op | undefined {
+  return b.ops[b.ops.length - 1];
+}
+
 /** The successor blocks of `b`, read off its terminator. */
 export function successorsOf(b: Block): Block[] {
-  const term = b.ops[b.ops.length - 1];
-  return term ? term.successors.map((s) => s.block) : [];
+  return terminator(b)?.successors.map((s) => s.block) ?? [];
+}
+
+/** The blocks reachable from the entry along successor edges — the entry's own reflexive closure,
+ *  so a function with no blocks yields the empty set rather than a set holding `undefined`.
+ *
+ *  A SET, so the walk order is not observable and no caller can come to depend on it. Three passes
+ *  ask this question — `contracts.ts` (an unreachable block's call is legitimately never emitted),
+ *  `pipeline.ts`'s opaque attribution, and `raise/shortcircuit.ts`'s relay drop — and each had its
+ *  own copy. They agree on every input any of them sees, because `successorsOf` reads the
+ *  terminator and `verify` rejects successors on a non-terminator.
+ *
+ *  REACHABILITY, not predecessor count: in-edges from blocks that are themselves unreachable leave
+ *  a block just as orphaned, and the thumb frontend does hand over unreachable blocks. `raise/gvn.ts`
+ *  keeps a walk of its own rather than calling this one — it descends through EVERY op's successors,
+ *  which is the same relation on verified IR and a wider one on the hand-built IR its own note is
+ *  about. */
+export function reachableBlocks(fn: Fn): Set<Block> {
+  const seen = new Set<Block>();
+  const entry = fn.blocks[0];
+  if (entry === undefined) {
+    return seen;
+  }
+  seen.add(entry);
+  for (const stack = [entry]; stack.length;) {
+    for (const s of successorsOf(stack.pop()!)) {
+      if (!seen.has(s)) {
+        seen.add(s);
+        stack.push(s);
+      }
+    }
+  }
+  return seen;
 }
 
 /** Predecessor map for the whole function's CFG. */
@@ -78,6 +237,159 @@ export function predecessors(fn: Fn): Map<Block, Block[]> {
   return preds;
 }
 
+/** Forward dominators (iterative data-flow). dom(b) = {b} ∪ ⋂ dom(preds).
+ *
+ *  A CFG fact, so it lives beside `predecessors` it is built on rather than with either consumer:
+ *  `verify` needs it to check def-dominates-use, `structure/loops.ts` to tell a back-edge from a
+ *  forward one, and `raise/latch.ts` to tell a latch from a preheader. */
+
+export function dominators(fn: Fn): Map<Block, Set<Block>> {
+  const preds = predecessors(fn);
+  const all = new Set(fn.blocks);
+  const dom = new Map<Block, Set<Block>>();
+  fn.blocks.forEach((b, i) => dom.set(b, i === 0 ? new Set([b]) : new Set(all)));
+  for (let changed = true; changed;) {
+    changed = false;
+    for (const b of fn.blocks.slice(1)) {
+      let inter: Set<Block> | null = null;
+      for (const p of preds.get(b)!) {
+        const dp = dom.get(p)!;
+        if (inter === null) {
+          inter = new Set(dp);
+          continue;
+        }
+        for (const x of inter) {
+          if (!dp.has(x)) {
+            inter.delete(x);
+          }
+        } // intersect in place (spec-safe delete-in-iter)
+      }
+      const next = new Set<Block>(inter ?? []);
+      next.add(b);
+      const prev = dom.get(b)!;
+      if (next.size !== prev.size || [...next].some((x) => !prev.has(x))) {
+        dom.set(b, next);
+        changed = true;
+      }
+    }
+  }
+  return dom;
+}
+
+/** A block with NO BODY OF ITS OWN: it declares no parameters and holds a single op, which is
+ *  therefore its terminator. It computes nothing and it binds nothing. Three sites ask this and
+ *  each adds its own clause (`forwardingTarget` below wants a `br` carrying no args;
+ *  switch-recover.ts's `isBareExit` admits a `ret` as well; raise/retsink.ts asks it of a
+ *  predecessor, to tell a decision that RAN OUT from an arm that ran ON), so the shared half is
+ *  stated once, here.
+ *
+ *  THE PARAMETER CLAUSE IS THE LOAD-BEARING HALF, and the reason this is not spelled
+ *  `ops.length === 1`: a case ENTRY whose arm is EMPTY is also one op — the jump onwards — but it
+ *  takes the accumulator as a block parameter, so it is a real arm of a dispatch and not a
+ *  forwarder. */
+export function isBodyless(blk: Block): boolean {
+  return blk.params.length === 0 && blk.ops.length === 1;
+}
+
+/** Where a chain of TRANSPARENT forwarding blocks lands — no params, a lone `br`, no block args.
+ *
+ *  A compiler that cannot reach a target from a conditional branch emits the real branch separately
+ *  (agbcc past Thumb's ±256-byte range; the binary-search layout of a `switch`), so two sites
+ *  reaching one block arrive as two DISTINCT forwarding blocks. A recogniser keyed on successor
+ *  identity needs the destination, not the edge.
+ *
+ *  An edge carrying block ARGUMENTS is not transparent — skipping it would drop the value it
+ *  supplies — so the walk stops there. Read-only: nothing about the graph changes.
+ *
+ *  Two sites test a similar shape and are deliberately NOT callers, both because they KEEP the
+ *  args this refuses to walk past: raise/latch.ts's `foldEmptyLatches` rewrites the edge and
+ *  carries the forwarder's args onto it; structure/switch-recover.ts's `resolveDefault` walks onto
+ *  a default candidate through a `b .Ldefault(v)` and turns that step into one more dispatch edge,
+ *  whose copies the hoist re-emits above the `switch`. */
+export function forwardingTarget(b: Block): Block {
+  const seen = new Set<Block>();
+  let cur = b;
+  while (isBodyless(cur) && !seen.has(cur)) {
+    seen.add(cur);
+    const t = cur.ops[0];
+    if (t.opcode !== 'br' || t.successors[0].args.length > 0) {
+      break;
+    }
+    cur = t.successors[0].block;
+  }
+  return cur;
+}
+
+/** THE MERGE CLASSES: every value that rides a branch edge, grouped with the block parameter it
+ *  binds — transitively, so a value forwarded across several merges lands in one class.
+ *
+ *  Functional-form SSA has no phi node: a register merge is spelled as an edge ARGUMENT plus a
+ *  block PARAMETER, two names for the one value a register carried. So a rule that counts what a
+ *  value is USED for reads one merged value as N values with N use counts, and any threshold it
+ *  applies (`structure/analysis.ts`'s "base of 2+ accesses") is measured against the wrong
+ *  denominator. This is the closure that restores it.
+ *
+ *  A value on no edge is its own class and is absent from the map — read it as `get(v) ?? [v]`.
+ *  Member order is definition order (block order, params before results), so a caller that reports
+ *  a class reports it deterministically.
+ *
+ *  A CFG/SSA fact rather than a rule of any one pass, so it lives here beside `dominators`. Two
+ *  callers took it: `structure/analysis.ts`'s shared-base scope, and `structure/structure.ts`'s
+ *  signed-use cone, which had hand-rolled the same arg↔param map.
+ *
+ *  THE THIRD SITE IS NOT THIS RELATION, and saying so is the point of naming it here.
+ *  `raise/recover.ts`'s `propagatePointers` runs its own union-find over the edge relation PLUS
+ *  the const-offset `add`/`sub` (a pointer ± an integer stays the same pointer), which is a
+ *  strictly larger relation and a typing rule of that pass rather than a fact about the CFG.
+ *  Rewriting it to start from this map would make it seed a pass-specific union on top, i.e. give
+ *  a CFG fact a parameter for one caller's extra edges — so it stays where it is, and what this
+ *  paragraph buys is that the next reader looking for a fourth copy knows which of the two the
+ *  third one is. */
+export function mergeClasses(fn: Fn): Map<Value, readonly Value[]> {
+  const parent = new Map<Value, Value>();
+  const find = (v: Value): Value => {
+    let r = v;
+    while ((parent.get(r) ?? r) !== r) {
+      r = parent.get(r)!;
+    }
+    for (let c = v; (parent.get(c) ?? r) !== r;) {
+      const n = parent.get(c)!;
+      parent.set(c, r);
+      c = n;
+    }
+    parent.set(r, r);
+    return r;
+  };
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      for (const s of op.successors) {
+        // `verify` pins arg/param arity, but this also runs on hand-built IR in tests — take the
+        // overlap rather than index past the end.
+        const n = Math.min(s.args.length, s.block.params.length);
+        for (let i = 0; i < n; i++) {
+          parent.set(find(s.args[i]), find(s.block.params[i]));
+        }
+      }
+    }
+  }
+  const byRoot = new Map<Value, Value[]>();
+  for (const b of fn.blocks) {
+    for (const v of [...b.params, ...b.ops.flatMap((op) => op.results)]) {
+      if (parent.has(v)) {
+        const root = find(v);
+        (byRoot.get(root) ?? byRoot.set(root, []).get(root)!).push(v);
+      }
+    }
+  }
+  const out = new Map<Value, readonly Value[]>();
+  for (const members of byRoot.values()) {
+    for (const v of members) {
+      out.set(v, members);
+    }
+  }
+  return out;
+}
+
 /** Every value defined by an op result → its defining op (block params excluded). */
 export function defOpMap(fn: Fn): Map<Value, Op> {
   const m = new Map<Value, Op>();
@@ -93,6 +405,29 @@ export function defOpMap(fn: Fn): Map<Value, Op> {
 
 /** Replace every use of `oldV` with `newV` (operands + successor args). No in-place op mutation. */
 export function replaceAllUsesWith(fn: Fn, oldV: Value, newV: Value): void {
+  // The frame coordinate follows the value that inherits the uses. Without this the home stays on
+  // a value nothing reads any more while the local the structurer names — `newV` — carries none,
+  // and the declaration list loses its order for that local. UNION, never a choice: this helper is
+  // handed an `Fn` and an `Fn` carries no target, so it cannot know whether the earlier rank is the
+  // lower or the higher offset (`SlotHomes`). `l3/slotorder.ts` decides that, once.
+  //
+  // A GUARD, MEASURED: instrumented over every agbcc case of both benchmark tiers, this fires 14
+  // times on 252 lifted synthetic functions and 112 times on 116 lifted real ones — and in every
+  // single firing the inheriting value already carried the same offset. So it has never yet SAVED
+  // a home, and the union has never yet held two. It ships because the alternative is a home
+  // stranded on a retired value, which is silent.
+  const homes = fn.slotHomes;
+  if (homes !== undefined) {
+    const from = homes.get(oldV);
+    if (from !== undefined) {
+      const to = homes.get(newV);
+      if (to === undefined) {
+        homes.set(newV, new Set(from));
+      } else {
+        from.forEach((off) => to.add(off));
+      }
+    }
+  }
   for (const b of fn.blocks) {
     for (const op of b.ops) {
       op.operands = op.operands.map((v) => (v === oldV ? newV : v));