@asmlift/core 0.9.0 → 0.11.0

package/src/ir/entry.ts

@@ -0,0 +1,157 @@
+// asmlift — does a test placed ahead of a loop compute the loop's own test on the loop's entry values?
+//
+// Three questions ask exactly that, at two levels, and all read the answer from this one predicate:
+//   • structure's GUARD FUSION (`structure.ts`, through `hazards.ts`): the `if` a rotated loop is
+//     wrapped in is deleted when it is the loop's test at the first iteration, and the loop re-tests;
+//   • raise's RE-ROLL (`raise/reroll.ts`): a loop test the compiler peeled into the loop's entry is
+//     deleted when it is the latch's test at the values the entry hands the loop;
+//   • the re-roll's TOP-TEST RESTORE (`entryGuard`, same file): the guard a restored top test
+//     makes redundant is deleted when it is that test at the entry values, with the same exit args.
+//
+// The reading is STRUCTURAL, never semantic: two values are the same when they are one value, or
+// when their defining ops have one opcode, one set of attributes and operands that are the same in
+// turn. A false negative costs a loud decline, the direction to be wrong in. `entry` models the
+// first iteration: on the loop side (`a`), a value it maps is read as the value it maps to, and
+// below that substitution the walk is in the entry's world, where the map no longer applies — a
+// loop-invariant back-edge argument read inside the entry's own expression is itself there, not the
+// param it feeds.
+//
+// `normalize` adds the equalities the re-roll needs and guard fusion does not take: an `add` or
+// `or` of a constant 0 on EITHER side, commutative operands in either order, and a load off
+// `base + c` as the same load off `base` at its offset plus `c` (`str[0]` against `str[i]` at
+// `i = 0`). Each is an identity of the integer operators, so turning it on for guard fusion is a
+// spelling decision, not a soundness one.
+import { Op, Value, attrsKey } from './core';
+import { spelledWhenDead } from './discipline';
+import { NEGATED_ICMP } from './opcodes';
+
+export interface EntryReading {
+  /** the value each loop-side value holds on the loop's first iteration */
+  readonly entry: ReadonlyMap<Value, Value>;
+  /** values whose defining op may be read through; everything else compares by identity. Default:
+   *  every value. An operand-free op that reads no memory (a constant, a symbol address) is always
+   *  read through: it is its attributes wherever it sits. */
+  readonly through?: (v: Value) => boolean;
+  /** the identities above, beyond `x + 0` / `x - 0` / `x | 0` with the zero on the right */
+  readonly normalize?: boolean;
+}
+
+/** Opcodes whose two operands may be read in either order, under `normalize`. */
+const COMMUTES = new Set(['add', 'mul', 'and', 'or', 'xor', 'icmp_eq', 'icmp_ne']);
+
+/** Is `a` (loop side), read on the loop's entry values, the same value as `b`? With `negated`, is it
+ *  `b`'s logical opposite — the usual case where a guard spells the loop's test the other way round. */
+export function sameAtEntry(
+  defs: ReadonlyMap<Value, Op>,
+  a: Value,
+  b: Value,
+  reading: EntryReading,
+  negated = false,
+): boolean {
+  const { entry, through = () => true, normalize = false } = reading;
+  const readable = (v: Value): boolean => {
+    const d = defs.get(v);
+    return d !== undefined && (through(v) || (d.operands.length === 0 && !spelledWhenDead(d)));
+  };
+  const constOf = (v: Value): number | null => {
+    const d = defs.get(v);
+    return d?.opcode === 'const' && typeof d.attrs?.value === 'number' ? d.attrs.value : null;
+  };
+  /** A constant `v` reads as: under `normalize`, as its entry substitution reads. */
+  const constAt = (v: Value, atEntry: boolean): number | null => constOf(normalize ? view(v, atEntry).x : v);
+  /** `x0` as the comparison reads it: through the entry map while on the loop side (`!atEntry`), and
+   *  with `x + 0` / `x - 0` / `x | 0` read as `x` — substituting a loop variable by its init constant
+   *  turns ordinary index arithmetic into exactly these. */
+  function view(x0: Value, atEntry0: boolean): { x: Value; atEntry: boolean } {
+    let x = x0;
+    let atEntry = atEntry0;
+    for (;;) {
+      const mapped = atEntry ? undefined : entry.get(x);
+      if (mapped !== undefined) {
+        x = mapped;
+        atEntry = true;
+        continue;
+      }
+      const d = readable(x) ? defs.get(x) : undefined;
+      if (!d || d.operands.length !== 2 || !['add', 'sub', 'or'].includes(d.opcode)) {
+        return { x, atEntry };
+      }
+      if (constAt(d.operands[1], atEntry) === 0) {
+        x = d.operands[0];
+      } else if (normalize && d.opcode !== 'sub' && constAt(d.operands[0], atEntry) === 0) {
+        x = d.operands[1];
+      } else {
+        return { x, atEntry };
+      }
+    }
+  }
+  /** A load's address as a base and a constant offset, the `+ c` of an `add` folded in. */
+  const address = (d: Op, atEntry0: boolean): { base: Value; off: number; atEntry: boolean } => {
+    const off = Number(d.attrs.off ?? 0);
+    const { x: base, atEntry } = view(d.operands[0], atEntry0);
+    const ad = readable(base) ? defs.get(base) : undefined;
+    if (ad?.opcode === 'add' && ad.operands.length === 2) {
+      for (const k of [0, 1]) {
+        const c = constAt(ad.operands[k], atEntry);
+        if (c !== null) {
+          return { base: ad.operands[1 - k], off: off + c, atEntry };
+        }
+      }
+    }
+    return { base, off, atEntry };
+  };
+  // memoised per (x, y, side): a value its own consumer reads twice would otherwise double the work
+  // at every level
+  const memo = new Map<string, boolean>();
+  const ids = new Map<Value, number>();
+  const id = (v: Value) => ids.get(v) ?? (ids.set(v, ids.size), ids.size - 1);
+  /** `da` (read with `atEntry`) and `db` (the entry's own) compute the same value. */
+  const sameOp = (da: Op, db: Op, opcodeOk: boolean, atEntry: boolean): boolean => {
+    if (!opcodeOk || da.operands.length !== db.operands.length) {
+      return false;
+    }
+    if (normalize && da.opcode === 'load' && db.opcode === 'load') {
+      const x = address(da, atEntry);
+      const y = address(db, true);
+      return x.off === y.off && attrsKey(da, 'off') === attrsKey(db, 'off') && same(x.base, x.atEntry, y.base);
+    }
+    if (attrsKey(da) !== attrsKey(db)) {
+      return false;
+    }
+    if (da.operands.every((o, i) => same(o, atEntry, db.operands[i]))) {
+      return true;
+    }
+    return (
+      normalize &&
+      COMMUTES.has(da.opcode) &&
+      da.operands.length === 2 &&
+      same(da.operands[0], atEntry, db.operands[1]) &&
+      same(da.operands[1], atEntry, db.operands[0])
+    );
+  };
+  function same(x0: Value, atEntry0: boolean, y0: Value): boolean {
+    const { x, atEntry } = view(x0, atEntry0);
+    const { x: y } = view(y0, true);
+    if (x === y) {
+      return true;
+    }
+    const key = `${id(x)},${id(y)},${atEntry ? 1 : 0}`;
+    const hit = memo.get(key);
+    if (hit !== undefined) {
+      return hit;
+    }
+    const da = readable(x) ? defs.get(x) : undefined;
+    const db = readable(y) ? defs.get(y) : undefined;
+    const r = !!da && !!db && sameOp(da, db, da.opcode === db.opcode, atEntry);
+    memo.set(key, r);
+    return r;
+  }
+  if (!negated) {
+    return same(a, false, b);
+  }
+  const { x, atEntry } = view(a, false);
+  const { x: y } = view(b, true);
+  const da = readable(x) ? defs.get(x) : undefined;
+  const db = readable(y) ? defs.get(y) : undefined;
+  return !!da && !!db && sameOp(da, db, NEGATED_ICMP[da.opcode] === db.opcode, atEntry);
+}

package/src/{structure → ir}/loops.ts

@@ -1,4 +1,8 @@
-// asmlift — natural-loop discovery: the pure CFG analysis the structurer consumes.
+// asmlift — natural-loop discovery: the pure CFG analysis the structurer consumes, and the raise
+// passes that rewrite a loop's edges before it (`raise/latch.ts`, `raise/reroll.ts`).
+//
+// A substrate fact like dominance, so it lives here and not under `structure/`: that keeps the
+// dependency between the levels one way — structure imports raise, never the reverse.
 //
 // Produces a DEFINITE header set computed structurally from back-edges — a block is a loop header
 // iff it is a real back-edge target (`h ∈ dom(t)` for an edge `t→h`), never inferred from `cond_br`
@@ -8,7 +12,7 @@
 //
 // Dominance itself is a substrate fact and lives in `ir/core.ts`; `analyzeLoops` takes the map as
 // a parameter, so a caller passes `dominators(fn)` from there.
-import { Block, Fn, predecessors, successorsOf } from '../ir/core';
+import { Block, Fn, predecessors, successorsOf } from './core';
 
 /** One natural loop, keyed by its header. */
 export interface NaturalLoop {

package/src/ir/opcodes.ts

@@ -38,7 +38,14 @@ export const OPCODES = {
   // Effect-free (no `effects` flag) so DCE reaps a dead one.
   mulh: { operands: 2, results: 1 },
   mulhu: { operands: 2, results: 1 },
-  neg: { operands: 1, results: 1 },
+  neg: { operands: 1, results: 1 }, // the wrapping negation, 0 - x as a 32-bit word
+  // The MATHEMATICAL negation: what Thumb's `cmn rA, rB` compares rA against when a signed branch
+  // reads it (frontend/thumb.ts `lowerTerminator`). It differs from `neg` at exactly one operand,
+  // 0x80000000, where its value (+2^31) is no 32-bit word at all. A separate opcode rather than an
+  // attr on `neg` because every word evaluator in core folds `neg` as the wrapping one, and an
+  // attr each of them must remember to read fails OPEN: one that does not know `neg_s` falls to
+  // its default arm and declines. Only the structurer spells it, as `-(s32)x`.
+  neg_s: { operands: 1, results: 1 },
   not: { operands: 1, results: 1 }, // bitwise complement (`mvn`) → ~x
   or: { operands: 2, results: 1 },
   and: { operands: 2, results: 1 },
@@ -151,6 +158,32 @@ export const OPCODES = {
   // opcode rather than a `const` over a float type for the reason the arithmetic above has its own:
   // every pass that matches `const` is an integer fold.
   fconst: { operands: 0, results: 1, requiredAttrs: ['bits'] },
+  // The CROSSINGS between a float and an integer, C's conversions: `fptosi`/`fptoui` truncate toward
+  // zero into a signed or unsigned integer of the result's width (32 or 64), `sitofp` converts a
+  // signed one, `fpext`/`fptrunc` move between the precisions. The only ops a float and an integer
+  // meet in (ir/verify.ts). No `uitofp`: no compiler here converts an unsigned integer in one step
+  // (agbcc open-codes it around `__floatsisf`), so it would be an opcode with no producer.
+  fptosi: { operands: 1, results: 1 },
+  fptoui: { operands: 1, results: 1 },
+  sitofp: { operands: 1, results: 1 },
+  fpext: { operands: 1, results: 1 },
+  fptrunc: { operands: 1, results: 1 },
+  // The float COMPARES, a 0/1 integer out of two floats of one type. Ten and not six, because
+  // NaN makes C's relations a partial order: `!(a > b)` is true on a NaN and `a <= b` is not, and
+  // every compiler here compiles the two differently. So each ordered relation (`o`, false on a
+  // NaN) has its logical negation as an unordered opcode (`u`, true on a NaN): `fcmp_ule` IS
+  // `!(a > b)`. C's `!=` is `fcmp_une`. They stay out of `NEGATED_ICMP`, whose integer negation
+  // (`<` ↔ `>=`) would be the wrong program here; `NEGATED_FCMP` below is theirs.
+  fcmp_oeq: { operands: 2, results: 1 },
+  fcmp_une: { operands: 2, results: 1 },
+  fcmp_olt: { operands: 2, results: 1 },
+  fcmp_uge: { operands: 2, results: 1 },
+  fcmp_ole: { operands: 2, results: 1 },
+  fcmp_ugt: { operands: 2, results: 1 },
+  fcmp_ogt: { operands: 2, results: 1 },
+  fcmp_ule: { operands: 2, results: 1 },
+  fcmp_oge: { operands: 2, results: 1 },
+  fcmp_ult: { operands: 2, results: 1 },
   // --- memory ---
   load: { operands: 1, results: 1, requiredAttrs: ['off', 'width', 'signed'], reads: true },
   store: { operands: 2, results: 0, requiredAttrs: ['off', 'width'], effects: true },
@@ -171,6 +204,12 @@ export const OPCODES = {
   //   - a load/store through an off-0 SCALAR gaddr → a bare global `gSym` / `gSym = v`;
   //   - an indexed or non-zero-offset AGGREGATE access → the address-cast `((T *)&gSym)[i]`;
   //   - any other use (e.g. `&gSym` passed to a call) → the `{k:'addr'}` L3 node, printed `&gSym`.
+  // Optional `fromMap: true` marks a name asmlift READ OFF THE SYMBOL MAP (a promoted numeric pool
+  // word, an interior attribution, a named walk) rather than one the asm spells by relocation.
+  // With it, `mapAddr` is the map address the name was read at: a name the map places at several
+  // addresses (a file static per unit) then denotes that one, and two such reads at different
+  // addresses, one of them read off the map, are two objects under one spelling, which
+  // raise/offsetnames.ts `cellSpelledTwice` declines. Two relocations of one name are the asm's own.
   gaddr: { operands: 0, results: 1, requiredAttrs: ['sym'] },
   // The address of a FRAME-LOCAL object — gaddr's local twin, for the address-taken stack local
   // (`mov rD, sp` feeding a DMA register or a callee). `off` is the byte offset inside the frame's
@@ -214,13 +253,16 @@ export const OPCODES = {
   // live-in, and a live-in of the entry block is a PARAMETER — right for an argument register, a
   // fabricated argument for anything else.
   //
-  // Operand-free and pure like `laddr`, and out of raise/gvn.ts's NUMBERABLE set — where numbering
-  // it would be VACUOUS rather than harmful, since two undefs in one function always carry
-  // different keys. "Same key, therefore same value" is empty for a value that has none.
+  // Operand-free and pure like `laddr`, and out of raise/gvn.ts's NUMBERABLE set, which must keep
+  // it out: two undefs of one key are a storage's content and a `copied` move of it, and numbering
+  // them one value would erase the move.
   //
   // `key` names the storage (`sp@0`, `r4`); the structurer reads it to name the local
   // (`uninit_sp0`) and emits NO assignment — that absence is the recovery, and an edge argument
-  // that is one emits no copy either (structure.ts undefCarriesNothing).
+  // that is one emits no copy either (structure.ts undefCarriesNothing). OPTIONAL `copied: true`:
+  // the value another storage's content arrives at a join keyed elsewhere as (`if (c) x = y;` of
+  // two uninitialised locals, frontend/ssa.ts `markCopiedUndefs`) — the machine moved it, so that
+  // edge copy IS emitted, under the name of the undef its key names.
   undef: { operands: 0, results: 1, requiredAttrs: ['key'] },
   // --- black-box escape hatch (keeps lifting total) ---
   // `effects: true`: an instruction asmlift could not model may do anything — write memory, trap,
@@ -243,6 +285,11 @@ export const OPCODES = {
   // Many-way switch dispatch (Regime B, jump table). The single operand is the scrutinee;
   // successors are the N case blocks followed by the default block (the LAST successor);
   // `cases` is the index-aligned list of the first N successors' case values.
+  // `exhaustive: true` — OPTIONAL, set by a frontend whose dispatch block is entered only past a
+  // bounds test that already sent every value outside `cases` elsewhere, so the default edge is
+  // never taken. It still names a block, because the op needs a last successor; the structurer
+  // reads the attr to emit no `default:` arm for it. A pass that rebuilds the op leaves it off and
+  // gets the default arm back, which is the conservative answer.
   switch_br: { operands: 1, results: 0, terminator: true, successors: 'variadic', requiredAttrs: ['cases'] },
 } as const satisfies Record<string, OpSig>;
 
@@ -272,6 +319,65 @@ export const CAST_WIDTHS: ReadonlySet<number> = new Set([8, 16]);
  *  an op computes ON. */
 export const FLOAT_OPS: ReadonlySet<string> = new Set(['fadd', 'fsub', 'fmul', 'fdiv', 'fneg', 'fconst']);
 
+/** The conversions out of a float into an integer, and into a float out of an integer. */
+export const FLOAT_TO_INT: ReadonlySet<string> = new Set(['fptosi', 'fptoui']);
+export const INT_TO_FLOAT: ReadonlySet<string> = new Set(['sitofp']);
+/** The conversions between the two precisions, each named by the width it converts from and to. */
+export const FLOAT_RESIZE: Readonly<Record<string, { from: 32 | 64; to: 32 | 64 }>> = {
+  fpext: { from: 32, to: 64 },
+  fptrunc: { from: 64, to: 32 },
+};
+
+/** The logical negation of each float compare, NaN included (the registry's note on `fcmp_*`):
+ *  expanded both ways from the pairs, as `NEGATED_ICMP` is. */
+const FCMP_NEGATION_PAIRS: readonly (readonly [Opcode, Opcode])[] = [
+  ['fcmp_oeq', 'fcmp_une'],
+  ['fcmp_olt', 'fcmp_uge'],
+  ['fcmp_ole', 'fcmp_ugt'],
+  ['fcmp_ogt', 'fcmp_ule'],
+  ['fcmp_oge', 'fcmp_ult'],
+];
+export const NEGATED_FCMP: Readonly<Record<string, Opcode>> = Object.fromEntries(
+  FCMP_NEGATION_PAIRS.flatMap(([a, b]) => [
+    [a, b],
+    [b, a],
+  ]),
+);
+
+/** What each float compare answers when its first operand is LESS than, EQUAL to or GREATER than
+ *  its second, and when the two are UNORDERED (either is a NaN): the definition of the ten, from
+ *  which a compare a runtime computes some other way is read (raise/floathelpers.ts). */
+export const FCMP_TRUTH: Readonly<Record<string, readonly [lt: boolean, eq: boolean, gt: boolean, un: boolean]>> = {
+  fcmp_olt: [true, false, false, false],
+  fcmp_ole: [true, true, false, false],
+  fcmp_ogt: [false, false, true, false],
+  fcmp_oge: [false, true, true, false],
+  fcmp_oeq: [false, true, false, false],
+  fcmp_une: [true, false, true, true],
+  fcmp_uge: [false, true, true, true],
+  fcmp_ugt: [false, false, true, true],
+  fcmp_ule: [true, true, false, true],
+  fcmp_ult: [true, false, false, true],
+};
+
+/** The float compare whose truth table (`FCMP_TRUTH`'s order: less, equal, greater, unordered) is
+ *  `truth`, or undefined where none is — always true, say. The one reader of the table backwards,
+ *  for every place that computes a compare's answers some other way (agbcc's helper tests,
+ *  raise/floathelpers.ts; PowerPC's `cror` of two bits, frontend/ppc.ts). */
+export function fcmpOfTruth(truth: readonly boolean[]): Opcode | undefined {
+  return Object.keys(FCMP_TRUTH).find((k) => FCMP_TRUTH[k].every((t, i) => t === truth[i])) as Opcode | undefined;
+}
+
+/** Every op that computes on a float: the arithmetic, the conversions and the compares. A runtime
+ *  helper whose op is one of these is a float helper (runtime-helpers.ts `isFloatHelper`). */
+export const FLOAT_COMPUTING: ReadonlySet<string> = new Set([
+  ...FLOAT_OPS,
+  ...FLOAT_TO_INT,
+  ...INT_TO_FLOAT,
+  ...Object.keys(FLOAT_RESIZE),
+  ...Object.keys(NEGATED_FCMP),
+]);
+
 /** Signature lookup by RUNTIME opcode string (Op.opcode is a plain string — IR consumers switch
  *  on it); undefined for an unregistered opcode. */
 export function opSig(opcode: string): OpSig | undefined {
@@ -290,10 +396,10 @@ export function opSig(opcode: string): OpSig | undefined {
  *
  *  It lives here so that every consumer that has to say "the opposite of this compare" reads THIS
  *  one, and they cannot drift apart the way inline copies did. Two adjacent facts worth knowing: raise/
- *  shortcircuit.ts derives its `BOOL_OPS` from these keys (asserting negatable-icmp == boolean-op,
- *  true today), and l3/ast.ts `NEGATE_REL` is the SAME relation over the neutral L3 operator
- *  vocabulary — deliberately separate, because signedness lives in the operand types there, so the
- *  two tables are not candidates for further consolidation. */
+ *  shortcircuit.ts derives its `BOOL_OPS` from these keys and `NEGATED_FCMP`'s (asserting
+ *  negatable compare == boolean-op, true today), and l3/ast.ts `NEGATE_REL` is the SAME relation
+ *  over the neutral L3 operator vocabulary — deliberately separate, because signedness lives in the
+ *  operand types there, so the two tables are not candidates for further consolidation. */
 const ICMP_NEGATION_PAIRS: readonly (readonly [Opcode, Opcode])[] = [
   ['icmp_eq', 'icmp_ne'],
   ['icmp_slt', 'icmp_sge'],
@@ -308,6 +414,28 @@ export const NEGATED_ICMP: Readonly<Record<string, Opcode>> = Object.fromEntries
   ]),
 );
 
+/** The comparison each `icmp_*` is with its operands SWAPPED — `a < b` is `b > a`; `==` and `!=`
+ *  are their own. Not a negation: `NEGATED_ICMP` keeps the operands and flips the answer, this
+ *  keeps the answer and flips the operands. Seated here for the reason `NEGATED_ICMP` is, and
+ *  expanded both ways from its pairs the same way, so `swap(swap(c)) === c` by construction; a test
+ *  asserts it covers the icmp family (test/pattern.test.ts). */
+const ICMP_SWAP_PAIRS: readonly (readonly [Opcode, Opcode])[] = [
+  ['icmp_slt', 'icmp_sgt'],
+  ['icmp_sle', 'icmp_sge'],
+  ['icmp_ult', 'icmp_ugt'],
+  ['icmp_ule', 'icmp_uge'],
+];
+export const SWAPPED_ICMP: Readonly<Record<string, Opcode>> = {
+  icmp_eq: 'icmp_eq',
+  icmp_ne: 'icmp_ne',
+  ...Object.fromEntries(
+    ICMP_SWAP_PAIRS.flatMap(([a, b]) => [
+      [a, b],
+      [b, a],
+    ]),
+  ),
+};
+
 /** The ops whose `operands[0]` is a memory-access BASE: `load base`, `store base, value`,
  *  `aload base, index`, `astore base, index, value` (the operand roles are in the registry above).
  *  Authored rather than derived — no registry field records the operand ROLE, and the only other

package/src/ir/parse.ts

@@ -128,6 +128,7 @@ export function parse(text: string): Fn {
     slotHomes: undefined,
     paramEvidence: undefined,
     localObjects: undefined,
+    asmLayout: undefined,
   };
 }
 

package/src/ir/simplify.ts

@@ -2,7 +2,7 @@
 //
 // Peer of `pattern/engine.ts`'s `dce`: general, opcode-agnostic, and callable by anything that has
 // just changed the CFG.
-import { Block, Fn, Successor, Value, replaceAllUsesWith } from './core';
+import { Block, Fn, Op, Successor, Value, replaceAllUsesWith } from './core';
 
 /**
  * Remove block params that are really TRIVIAL PHIS — those whose incoming args, across every
@@ -55,12 +55,7 @@ export function simplifyTrivialPhis(fn: Fn, onRemoved?: (param: Value) => void):
         if (collapsed === null) {
           continue; // a genuine join, or unreachable (no in-edges at all)
         }
-        replaceAllUsesWith(fn, param, collapsed);
-        onRemoved?.(param);
-        b.params.splice(i, 1);
-        for (const s of incoming) {
-          s.args.splice(i, 1);
-        }
+        retireParam(fn, b, i, collapsed, incoming, onRemoved);
         removed++;
         changed = true;
       }
@@ -77,14 +72,70 @@ export function simplifyTrivialPhis(fn: Fn, onRemoved?: (param: Value) => void):
  *  fixpoint and the non-mutating check below so the two cannot come to disagree about which params
  *  are trivial.
  *
+ *  `same` is the equality the args are held to. Identity by default, which is the trivial phi
+ *  proper; `raise/unpre.ts` passes structural congruence (`ir/entry.ts` `sameAtEntry`) and gets
+ *  back the FIRST arg as the class's representative, which it recomputes rather than reads. The
+ *  self-reference waiver is the same for both, and so is its argument above: the first dynamic
+ *  entry arrives on an edge that hands the representative's class.
+ *
  *  `=== null` IS THE ONLY SAFE TEST. A genuine collapse value is never null, but it CAN be
  *  `undefined` where an edge carries fewer args than the block has params — a malformed graph the
  *  verifier catches elsewhere, and one today's callers pass straight through rather than treat as
  *  "not trivial". A truthiness test would silently change that.
  */
-function trivialPhiValue(incoming: readonly Successor[], i: number, param: Value): Value | null {
-  const distinct = [...new Set(incoming.map((s) => s.args[i]).filter((v) => v !== param))];
-  return distinct.length === 1 ? distinct[0] : null;
+export function trivialPhiValue(
+  incoming: readonly Successor[],
+  i: number,
+  param: Value,
+  same: (a: Value, b: Value) => boolean = (a, b) => a === b,
+): Value | null {
+  const args = incoming.map((s) => s.args[i]).filter((v) => v !== param);
+  if (args.length === 0) {
+    return null;
+  }
+  const first = args[0];
+  return args.every((v) => v === first || same(v, first)) ? first : null;
+}
+
+/** Retire block param `i` of `b` for `value`: every use reads `value`, and the param and each
+ *  in-edge's arg for it are spliced out. `incoming` is every successor that targets `b` — the
+ *  SUCCESSOR objects, not their `args`, which `replaceAllUsesWith` replaces. `onRemoved` runs after
+ *  the uses move and before the splice. */
+export function retireParam(
+  fn: Fn,
+  b: Block,
+  i: number,
+  value: Value,
+  incoming: readonly Successor[],
+  onRemoved?: (param: Value) => void,
+): void {
+  const param = b.params[i];
+  replaceAllUsesWith(fn, param, value);
+  onRemoved?.(param);
+  b.params.splice(i, 1);
+  for (const s of incoming) {
+    s.args.splice(i, 1);
+  }
+}
+
+/** Every in-edge, indexed by target: the successor, the block it leaves and the terminator that
+ *  carries it. ONE pass over the function, for a caller whose CFG does not change while it reads the
+ *  index (params and args may: the successor objects stay). */
+export function inEdgesOf(fn: Fn): Map<Block, { succ: Successor; from: Block; op: Op }[]> {
+  const out = new Map<Block, { succ: Successor; from: Block; op: Op }[]>();
+  for (const from of fn.blocks) {
+    for (const op of from.ops) {
+      for (const succ of op.successors) {
+        const list = out.get(succ.block);
+        if (list === undefined) {
+          out.set(succ.block, [{ succ, from, op }]);
+        } else {
+          list.push({ succ, from, op });
+        }
+      }
+    }
+  }
+  return out;
 }
 
 /**

package/src/ir/types.ts

@@ -7,6 +7,11 @@ export interface StructField {
   off: number;
   type: IrType;
   name: string;
+  /** A cell the function also reads or writes at another width or extension, declared at its
+   *  widest view because the union of its views would not fit the compiler's layout
+   *  (raise/structs.ts `buildUnionStruct`). An access of any other type is a cast of the base
+   *  (structure.ts `memAccess`). */
+  castViews?: true;
 }
 
 export type IrType =
@@ -93,6 +98,31 @@ export const T = {
   void: (): IrType => ({ kind: 'void' }),
 };
 
+/** The member name of each view a union holds, by access width. A width with no entry has no view
+ *  (the deref contract admits no other scalar width either), and its overlap still declines. A
+ *  narrow width loaded with both extensions has a view per extension, `u`/`s` prefixed. */
+export const UNION_VIEW_NAMES: Readonly<Record<number, string>> = { 1: 'byte', 2: 'half', 4: 'word' };
+
+/** The extensions a union declares a view of `width` bytes in, from the accesses of that width:
+ *  THE one rule raise/structs.ts `buildUnionStruct` and the frame audit (frontend/frame-objects.ts
+ *  `unionViews`) both declare by, so a struct member's union and a frame object's cannot disagree
+ *  on their views. A word has one view whatever its loads say (`scalarTypeForAccess`); a narrower
+ *  width a view per extension it is LOADED with, unsigned first; a width only stored the signed
+ *  view where a stamped store says signed (raise/storesign.ts) and the unsigned one otherwise. */
+export function unionViewSigns(
+  width: number,
+  accesses: readonly { readonly isLoad: boolean; readonly signed: boolean; readonly stamped: boolean }[],
+): boolean[] {
+  if (width === 4) {
+    return [true];
+  }
+  const loaded = new Set(accesses.filter((a) => a.isLoad).map((a) => a.signed));
+  if (loaded.size === 0) {
+    return [accesses.some((a) => a.stamped && a.signed)];
+  }
+  return [false, true].filter((sg) => loaded.has(sg));
+}
+
 /** The byte width of a union view's element (an array view's element, or the scalar itself). */
 function viewBytes(t: IrType): number {
   const e = t.kind === 'array' ? t.elem : t;
@@ -102,6 +132,11 @@ function viewBytes(t: IrType): number {
   return e.width / 8;
 }
 
+/** A struct as its declaration spells it (`declared`), else by its tag; any other type as printed. */
+export function structSpelling(t: IrType): string {
+  return t.kind === 'struct' ? (t.declared ?? `struct ${t.name}`) : typeToString(t);
+}
+
 /** The member `name` of an aggregate — a struct's field or a union's view — or undefined when `t`
  *  is not an aggregate or declares no such member. THE one lookup the typing walk and the deref
  *  contract share, so the two cannot disagree on which member access is well-typed. */
@@ -131,8 +166,57 @@ export function unionViewAt(
   if (member === undefined || member.type.kind !== 'union') {
     return undefined;
   }
+  return { member, ...unionView(member.type, off - member.off, width, signed, isStore) };
+}
+
+/** Does a member declared at signedness `declared` read as EXACTLY the type the cast spelling this
+ *  replaces would have produced — `scalarTypeForAccess(width, signed)`? That is the whole
+ *  byte-exactness argument for naming a member instead of casting: same address, same read width,
+ *  same C type, so every operator downstream compiles identically. A 4-byte access renders s32
+ *  whatever the load said (the ISA has one word load), so only a SIGNED member may take its place;
+ *  narrower accesses carry their own signedness and must match it. An undeclared signedness (the
+ *  member is not a base type — a nested struct, an enum, a pointer) is never assumed to match.
+ *  THE one copy of "an access names the member": structure.ts's member spellings and `isCastView`
+ *  below all ask it, so they cannot drift apart. */
+export function spellsAccessType(declared: boolean | undefined, width: number, signed: boolean): boolean {
+  if (declared === undefined) {
+    return false;
+  }
+  return typeEquals(T.int(width * 8, declared), scalarTypeForAccess(width, signed));
+}
+
+/** Does an access of `width` bytes at byte `off`, inside a `castViews` field of the struct, read it
+ *  at a view other than the field's own type — another width or offset, or a load whose type the
+ *  field does not spell (`spellsAccessType`)? A store carries no extension (it truncates to the
+ *  field's bytes whatever their type), so one of the field's width at its offset is the field. */
+export function isCastView(
+  st: Extract<IrType, { kind: 'struct' }>,
+  off: number,
+  width: number,
+  signed: boolean,
+  isStore: boolean,
+): boolean {
+  const f = st.fields.find(
+    (m) => m.castViews === true && m.off <= off && off + width <= m.off + (intWidth(m.type) ?? 0) / 8,
+  );
+  if (f === undefined || f.type.kind !== 'int') {
+    return false;
+  }
+  return off !== f.off || f.type.width !== width * 8 || (!isStore && !spellsAccessType(f.type.signed, width, signed));
+}
+
+/** The view of a union an access of `width` bytes at byte `at` of it reads — the rule
+ *  `unionViewAt` states, asked of a union that is not a struct's member (a frame object declared
+ *  as one, structure.ts `laddrType`). */
+export function unionView(
+  u: Extract<IrType, { kind: 'union' }>,
+  at: number,
+  width: number,
+  signed: boolean,
+  isStore: boolean,
+): { view: StructField | undefined; index: number | null } {
   const elemOf = (t: IrType): IrType => (t.kind === 'array' ? t.elem : t);
-  const wide = member.type.members.filter((m) => intWidth(elemOf(m.type)) === width * 8);
+  const wide = u.members.filter((m) => intWidth(elemOf(m.type)) === width * 8);
   const signOf = (m: StructField): boolean | undefined => {
     const e = elemOf(m.type);
     return e.kind === 'int' ? e.signed : undefined;
@@ -141,7 +225,7 @@ export function unionViewAt(
     width === 4 || (isStore && wide.length === 1)
       ? wide[0]
       : wide.find((m) => signOf(m) === (isStore ? false : signed));
-  return { member, view, index: view?.type.kind === 'array' ? (off - member.off) / width : null };
+  return { view, index: view?.type.kind === 'array' ? at / width : null };
 }
 
 export function typeToString(t: IrType): string {