@asmlift/core 0.10.0 → 0.11.0

package/src/ir/core.ts

@@ -59,8 +59,57 @@ export interface Fn {
   /** L1 SIDE DATA (see {@link LocalObjects}); set by a frontend that recovered one, `undefined` on
    *  every other `Fn`. REQUIRED-but-possibly-undefined for exactly the reason `writeOrder` is. */
   localObjects: LocalObjects | undefined;
+  /** L1 SIDE DATA (see {@link AsmLayout}); set by a frontend, `undefined` on parsed IR.
+   *  REQUIRED-but-possibly-undefined for exactly the reason `writeOrder` is. */
+  asmLayout: AsmLayout | undefined;
 }
 
+/** One block's place in the assembly a frontend lifted it from ({@link AsmLayout}). */
+export interface AsmBlockLayout {
+  /** the block's position among the function's blocks in the asm text, first block 0 */
+  readonly index: number;
+  /** the block's instructions without its control transfer, one string per instruction as the
+   *  asm spells it (`mnemonic op,op`), followed by `<sym>` (`<sym+0xN>` with an addend) where a
+   *  relocation fills in a symbol the operands do not name (frontend/ssa.ts `recordAsmLayout`). A
+   *  MIPS delay slot is part of the block it runs in. */
+  readonly body: readonly string[];
+  /** the positions in `body` of the instructions that make a call, as the frontend's ISA reads them
+   *  (Thumb `bl`/`blx` but not a far-jump relay, MIPS `jal`/`jalr`/`bal`, PPC `bl`/`bctrl`/`blrl`) */
+  readonly calls: readonly number[];
+  /** the block ends in an unconditional jump to a label: neither a fall-through, nor a return,
+   *  nor a conditional or indirect branch */
+  readonly endsInJump: boolean;
+}
+
+/** WHERE THE COMPILER PUT EACH BLOCK, and what it holds besides its branch: a measurement only the
+ *  frontend can make. The IR keeps the CFG and drops the order, since `fn.blocks` is a list passes
+ *  are free to rewrite (raise/reroll.ts moves a block ahead of another, and inserts one).
+ *
+ *  The reader is the return-tail chooser (structure/cross-jumped-tail.ts). Where the compiler
+ *  cross-jumps return tails (target.ts `crossJumpsReturnTails`), the layout tells a tail the source
+ *  wrote once from one it wrote into every arm, and the CFG cannot. Keyed by Block OBJECT, so a
+ *  clone re-keys it (cli/src/report.ts `structuredCloneFn`). A block a pass created has no entry,
+ *  and every reader takes a missing entry as "no evidence". Recorded by the Thumb and MIPS
+ *  frontends only: no mark is read on mwcc (it declares neither `crossJumpsReturnTails` nor an
+ *  unfolded taken-edge constant), so frontend/ppc.ts records none until one is, and a PPC lift's
+ *  `asmLayout` is undefined.
+ *
+ *  AN ENTRY DESCRIBES THE ASM BLOCK THE IR BLOCK WAS LIFTED FROM, whatever raising later did to the
+ *  IR block. A return sunk into it, or ops a fold absorbed (shortcircuit, tailsink, divpow2), leave
+ *  the entry as the frontend wrote it. So `endsInJump` and `body` say what the compiler emitted,
+ *  not what the block holds now: over the agbcc lifts of the 620 functions the join re-spells
+ *  (2026-11-05), 786 of 10520 blocks have an entry saying they end in a jump and no longer end in a
+ *  `br`. The return-tail chooser reads exactly that, the asm terminator. A reader of the current
+ *  block reads its ops.
+ *
+ *  BUT ON MIPS THE ASM IS THE NORMALISED ASM. frontend/mips.ts records the layout after
+ *  `normaliseBranchLikely`, which gives a likely branch's slot a block of its own and retargets an
+ *  unconditional `b T` whose slot copies the word at T-4 to that word, emptying the slot.
+ *  Such a `b`'s entry has `body` ending in `nop` where the compiler emitted the copied word
+ *  (`func_80A42DB4_jp`'s `b` at 0x80A42DCC, whose slot is `sw zero,0(a3)`), so every MIPS mark
+ *  reads the normalised body, not the emitted one. */
+export type AsmLayout = Map<Block, AsmBlockLayout>;
+
 /** Where a function-scope static lives, which decides how its definition is spelled: `rodata` is
  *  `const` with an initializer, `data` has an initializer, `bss` has none. */
 export type LocalObjectSection = 'rodata' | 'data' | 'bss';
@@ -356,6 +405,19 @@ export function mkOp(opcode: Opcode, o: Partial<Op> = {}): Op {
   };
 }
 
+/** An op's attributes as one comparable key, keys sorted (so insertion order never tells two
+ *  equal attribute sets apart), leaving out the attribute `drop` names. */
+export function attrsKey(op: Op, drop: string | null = null): string {
+  return JSON.stringify(
+    Object.entries(op.attrs ?? {})
+      .filter(([k]) => k !== drop)
+      .sort(([a], [b]) => a.localeCompare(b)),
+  );
+}
+
+/** One op's identity apart from its operands: opcode, result count and attributes. */
+export const opShape = (op: Op): string => `${op.opcode}/${op.results.length}/${attrsKey(op)}`;
+
 // ── a call's callee: a NAME (`attrs.target`) or, for a call through a register, a VALUE ─────────
 //
 // An INDIRECT call carries `indirect: true` and no `target`, and calls the function whose address
@@ -438,7 +500,7 @@ export function successorsOf(b: Block): Block[] {
  *  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> {
+export function reachableBlocks(fn: { readonly blocks: readonly Block[] }): Set<Block> {
   const seen = new Set<Block>();
   const entry = fn.blocks[0];
   if (entry === undefined) {
@@ -484,7 +546,7 @@ export function reachForward(
 }
 
 /** Predecessor map for the whole function's CFG. */
-export function predecessors(fn: Fn): Map<Block, Block[]> {
+export function predecessors(fn: { readonly blocks: readonly Block[] }): Map<Block, Block[]> {
   const preds = new Map<Block, Block[]>();
   for (const b of fn.blocks) {
     preds.set(b, []);
@@ -503,7 +565,7 @@ export function predecessors(fn: Fn): Map<Block, Block[]> {
  *  `verify` needs it to check def-dominates-use, `ir/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>> {
+export function dominators(fn: { readonly blocks: readonly Block[] }): Map<Block, Set<Block>> {
   const preds = predecessors(fn);
   const all = new Set(fn.blocks);
   const dom = new Map<Block, Set<Block>>();
@@ -536,6 +598,94 @@ export function dominators(fn: Fn): Map<Block, Set<Block>> {
   return dom;
 }
 
+/** Whether `h` dominates `t`, exactly as `dominators(fn).get(t).has(h)` answers it: the
+ *  same data-flow (dom(b) = {b} ∪ ⋂ dom(preds), the entry alone, every other block starting from all
+ *  of them), iterated to the same greatest fixed point, over one bit per block instead of a `Set`
+ *  per block. raise/shortcircuit.ts's `naturalLoopBodies` asks it once per scan of a function its fold
+ *  keeps changing, where the sets cost a large function's lift most of its raising time. */
+export function dominance(fn: { readonly blocks: readonly Block[] }): (h: Block, t: Block) => boolean {
+  const n = fn.blocks.length;
+  const words = Math.ceil(n / 32);
+  const index = new Map<Block, number>();
+  fn.blocks.forEach((b, i) => index.set(b, i));
+  const preds = predecessors(fn);
+  const dom = fn.blocks.map((_, i) => {
+    const bits = new Uint32Array(words);
+    if (i === 0) {
+      bits[0] = 1;
+    } else {
+      bits.fill(0xffffffff);
+      if (n % 32 !== 0) {
+        bits[words - 1] = 2 ** (n % 32) - 1;
+      }
+    }
+    return bits;
+  });
+  const next = new Uint32Array(words);
+  for (let changed = true; changed;) {
+    changed = false;
+    for (let i = 1; i < n; i++) {
+      const ps = preds.get(fn.blocks[i])!;
+      if (ps.length === 0) {
+        next.fill(0);
+      } else {
+        next.set(dom[index.get(ps[0])!]);
+        for (let k = 1; k < ps.length; k++) {
+          const dp = dom[index.get(ps[k])!];
+          for (let w = 0; w < words; w++) {
+            next[w] &= dp[w];
+          }
+        }
+      }
+      next[i >>> 5] |= 1 << (i & 31);
+      const prev = dom[i];
+      let same = true;
+      for (let w = 0; w < words; w++) {
+        if (next[w] !== prev[w]) {
+          same = false;
+          break;
+        }
+      }
+      if (!same) {
+        prev.set(next);
+        changed = true;
+      }
+    }
+  }
+  return (h, t) => {
+    const hi = index.get(h);
+    const ti = index.get(t);
+    return hi !== undefined && ti !== undefined && (dom[ti][hi >>> 5] & (1 << (hi & 31))) !== 0;
+  };
+}
+
+/** Each block's IMMEDIATE dominator: of its strict `dominators`, which form a chain, the nearest —
+ *  the one every other dominates, so the one with the most dominators of its own. Read off those
+ *  sets rather than computed again, so the tree and the sets cannot disagree; but off the sets of
+ *  the blocks the entry reaches (`reachableBlocks`) alone, because `dominators` counts an edge
+ *  out of an unreachable block as a way in, and one such edge into a loop's join leaves the join
+ *  dominated by nothing but itself. The entry, and every unreachable block, have none.
+ *  `ir/bits.ts`'s `edgeFacts` walks this tree up from a point to read what the branches above it
+ *  prove there. */
+export function immediateDominators(fn: { readonly blocks: readonly Block[] }): Map<Block, Block> {
+  const live = reachableBlocks(fn);
+  const blocks = fn.blocks.filter((b) => live.has(b));
+  const dom = dominators({ blocks });
+  const out = new Map<Block, Block>();
+  for (const b of blocks.slice(1)) {
+    let near: Block | undefined;
+    for (const d of dom.get(b)!) {
+      if (d !== b && (near === undefined || dom.get(d)!.size > dom.get(near)!.size)) {
+        near = d;
+      }
+    }
+    if (near !== undefined) {
+      out.set(b, near);
+    }
+  }
+  return out;
+}
+
 /** 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;
@@ -605,7 +755,7 @@ export function forwardingTarget(b: Block): Block {
  *  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: Pick<Fn, 'blocks'>): Map<Value, readonly Value[]> {
+export function mergeClasses(fn: { readonly blocks: readonly Block[] }): Map<Value, readonly Value[]> {
   const parent = new Map<Value, Value>();
   const find = (v: Value): Value => {
     let r = v;

package/src/ir/entry.ts

@@ -21,7 +21,7 @@
 // `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 } from './core';
+import { Op, Value, attrsKey } from './core';
 import { spelledWhenDead } from './discipline';
 import { NEGATED_ICMP } from './opcodes';
 
@@ -100,8 +100,6 @@ export function sameAtEntry(
     }
     return { base, off, atEntry };
   };
-  const attrsOf = (d: Op, drop: string | null) =>
-    JSON.stringify(Object.fromEntries(Object.entries(d.attrs ?? {}).filter(([k]) => k !== drop)));
   // 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>();
@@ -115,9 +113,9 @@ export function sameAtEntry(
     if (normalize && da.opcode === 'load' && db.opcode === 'load') {
       const x = address(da, atEntry);
       const y = address(db, true);
-      return x.off === y.off && attrsOf(da, 'off') === attrsOf(db, 'off') && same(x.base, x.atEntry, y.base);
+      return x.off === y.off && attrsKey(da, 'off') === attrsKey(db, 'off') && same(x.base, x.atEntry, y.base);
     }
-    if (attrsOf(da, null) !== attrsOf(db, null)) {
+    if (attrsKey(da) !== attrsKey(db)) {
       return false;
     }
     if (da.operands.every((o, i) => same(o, atEntry, db.operands[i]))) {

package/src/ir/opcodes.ts

@@ -204,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
@@ -408,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/verify.ts

@@ -211,6 +211,7 @@ export function verify(fn: Fn): void {
           // second as `u8 name[count]`, so a typed element there would be a type nothing pinned —
           // the exact answer the audit refuses to invent. (One BYTE encodes like a real `u8`
           // scalar either way; the declaration is the same one, so nothing has to tell them apart.)
+          // A part's element, where its own accesses pin one, rides beside them as `elem` below.
           if (op.opcode === 'laddr') {
             const count = op.attrs.count;
             if (typeof count !== 'number' || !Number.isInteger(count) || count < 1) {
@@ -229,6 +230,21 @@ export function verify(fn: Fn): void {
             if (op.attrs.part === true && count < 2) {
               throw new VerifyError(`'laddr' part must be storage of two or more bytes, got ${count}`);
             }
+            // …whose ELEMENT its accesses may agree on (frame-objects.ts `stampPartElements`): a
+            // width that tiles the part, negative for a signed narrow one, never the default `u8`
+            const elem = op.attrs.elem;
+            if (
+              elem !== undefined &&
+              (op.attrs.part !== true ||
+                op.attrs.views !== undefined ||
+                ![2, 4, -1, -2].includes(elem as number) ||
+                count % Math.abs(elem as number) !== 0)
+            ) {
+              throw new VerifyError(
+                `'laddr' elem is a part's element width (2, 4; -1, -2 signed) tiling its ${count} bytes, ` +
+                  `got ${String(elem)}${op.attrs.part === true ? '' : ' on storage that is no part'}`,
+              );
+            }
             // …and storage accessed at two widths over one byte names the VIEWS a union of it
             // declares (frame-objects.ts `unionViews`): one per element width in bytes, negative
             // for a signed narrow one, each tiling the storage — so at least two, distinct, of a

package/src/l3/argbase.ts

@@ -208,6 +208,8 @@ export function materializeArgBases(sfn: SFn): SFn | null {
         break;
       case 'break':
       case 'continue':
+      case 'goto':
+      case 'caseEndGoto':
         out = s;
         break;
     }