@asmlift/core 0.3.0 → 0.4.0

package/src/ir/simplify.ts

@@ -0,0 +1,72 @@
+// asmlift — SSA cleanups that belong to the substrate, not to any one pass.
+//
+// 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';
+
+/**
+ * Remove block params that are really TRIVIAL PHIS — those whose incoming args, across every
+ * predecessor edge and ignoring a self-reference from a back edge, are all one value. Such a param
+ * carries no join information, so it is replaced by that value and the arg dropped from each
+ * predecessor's terminator. Returns how many were removed.
+ *
+ * Iterated to a fixpoint: removing one phi can make the next trivial.
+ *
+ * DOMINANCE is free. If every predecessor passes `v`, then `v` is defined before each of those
+ * terminators and every path into the block goes through one of them — so `v` dominates the block
+ * and every use the param had. The self-reference waiver preserves that: a class where every edge
+ * passes the param itself has no first dynamic entry, so the first real entry always arrives on a
+ * `v`-passing edge.
+ *
+ * THE ENTRY BLOCK IS NEVER TOUCHED. Its params are the function's own parameters. Braun's
+ * construction in `frontend/ssa.ts` used to rely on entry having no in-edges to get this for free —
+ * which stops being true for an entry block that is ALSO a loop header, a shape this codebase does
+ * have (`raise/shortcircuit.ts` and `raise/retsink.ts` both guard it explicitly, the former after a
+ * reproduced silent miscompile). The guard is stated rather than inherited from an accident.
+ *
+ * `onRemoved` lets a caller drop its own bookkeeping for the retired param (the frontend's phi-block
+ * map); it is called once per removal, before the param is spliced out.
+ */
+export function simplifyTrivialPhis(fn: Fn, onRemoved?: (param: Value) => void): number {
+  const edgesTo = (b: Block): Successor[] => {
+    const out: Successor[] = [];
+    for (const pb of fn.blocks) {
+      for (const op of pb.ops) {
+        for (const s of op.successors) {
+          if (s.block === b) {
+            out.push(s);
+          }
+        }
+      }
+    }
+    return out;
+  };
+  let removed = 0;
+  for (;;) {
+    let changed = false;
+    for (const b of fn.blocks) {
+      if (b === fn.blocks[0]) {
+        continue;
+      }
+      const incoming = edgesTo(b);
+      for (let i = b.params.length - 1; i >= 0; i--) {
+        const param = b.params[i];
+        const distinct = [...new Set(incoming.map((s) => s.args[i]).filter((v) => v !== param))];
+        if (distinct.length !== 1) {
+          continue; // a genuine join, or unreachable (no in-edges at all)
+        }
+        replaceAllUsesWith(fn, param, distinct[0]);
+        onRemoved?.(param);
+        b.params.splice(i, 1);
+        for (const s of incoming) {
+          s.args.splice(i, 1);
+        }
+        removed++;
+        changed = true;
+      }
+    }
+    if (!changed) {
+      return removed;
+    }
+  }
+}

package/src/l3/argbase.ts

@@ -0,0 +1,216 @@
+// L3 re-spelling lever: materialize the deref BASES of a call's arguments into locals, before the
+// call.
+//
+// When a call's arguments are each a deref through a different fixed address, the compiler loads
+// BOTH addresses before dereferencing either — it needs two registers live across the argument
+// setup, so it emits the two pool loads first:
+//
+//     ldr  r0, .L4        <- both addresses
+//     ldr  r1, .L4+0x4
+//     ldrb r0, [r0]       <- then both loads
+//     ldrb r1, [r1, #0x8]
+//
+// Spelling the derefs INLINE in the argument list (`f(*(u8 *)0x4000006, gEntityArray[8])`) makes
+// agbcc finish argument 0 before starting argument 1 — `ldr; ldrb; ldr; ldrb` — which is the same
+// four instructions in a different order, and a nonmatch. The source that produces the target's
+// order names the bases first (`vu8 *p = &REG_VCOUNT_L; u8 *e = gEntityArray; f(*p, e[8])`), which
+// is what a decomp author writes and what this pass reproduces.
+//
+// A LEVER, not a rewrite: it is emitted as an ADDITIONAL candidate (rank.ts `/argbase`) and the
+// differ referees, so the inline spelling is always still there to win. That is what bounds the
+// risk — a lever that replaced the primary could lose a match, this one cannot.
+//
+// SEMANTICS ARE PRESERVED BY CONSTRUCTION, which matters because on a NONMATCH row the
+// best-scoring candidate is what the user is shown. Only a PURE leaf base is eligible — a global's
+// address (`addr`), a numeric pointer (`const`), or the bare name of a declared global — so
+// evaluating it earlier can be neither observable nor faulting. A local variable is excluded: it
+// may be assigned between the hoist point and the call, which would change what is dereferenced.
+//
+// KNOWN LIMITATION: the hoisted local is a plain `T *` — `IrType` models no cv-qualifier at all,
+// so naming a VOLATILE cell through it drops the qualifier that macros.ts goes out of its way to
+// carry. Pre-existing and not introduced here (every pointer local in the tower has it), but the
+// two features meet on exactly the MMIO shape this lever targets, so it is written down rather
+// than left to be rediscovered.
+//
+// GATE: at least TWO arguments of the same call must qualify, with DISTINCT bases. The reordering
+// this reproduces only exists when two addresses compete for registers during argument setup — with
+// ONE base there is nothing to interleave, so the compiler emits the same sequence either way and
+// naming it is pure churn. (Evidence: on kleod:UpdateFadeEffect, hoisting only the first base
+// leaves the diff at 2; both together take it to 0.)
+import { type IrType, T, scalarTypeForAccess } from '../ir/types';
+import type { Expr, SFn, Stmt } from './ast';
+import { mapExprChildren, stmtExprs } from './ast';
+import { nameAllocator } from './hoist';
+
+/** A base this pass may evaluate early: pure, and not something a store can change under us. */
+function eligibleBase(base: Expr, globals: ReadonlySet<string>): boolean {
+  return base.k === 'addr' || base.k === 'const' || (base.k === 'var' && globals.has(base.name));
+}
+
+/** THE identity of an eligible base — what makes two accesses "the same address".
+ *
+ *  A global reaches this pass under TWO spellings: `addr g` (its address) and, when the symbol map
+ *  types it as an array of the access width, the bare `var g`. They denote the same cell, so a
+ *  structural comparison would count them as two addresses and defeat the gate on
+ *  `f(*(u8 *)&g, g[4])` — the exact churn the gate exists to reject, reached by a different route.
+ *  Named bases therefore key on the NAME alone, whichever node kind carries it. */
+function baseIdentity(base: Expr): string {
+  return base.k === 'const' ? `c:${base.value}` : `n:${(base as Extract<Expr, { k: 'var' | 'addr' }>).name}`;
+}
+
+/** The `index` nodes directly under a call's arguments whose base is eligible — the candidates for
+ *  materialization. Only the argument's OWN top-level deref counts: a base buried inside arbitrary
+ *  argument arithmetic is not what the compiler is loading up front. */
+function argBases(call: Extract<Expr, { k: 'call' }>, globals: ReadonlySet<string>): Extract<Expr, { k: 'index' }>[] {
+  const out: Extract<Expr, { k: 'index' }>[] = [];
+  for (const a of call.args) {
+    if (a.k === 'index' && !a.lead?.length && eligibleBase(a.base, globals)) {
+      out.push(a);
+    }
+  }
+  return out;
+}
+
+/** Distinct bases, in first-appearance order — the compiler loads each ADDRESS once.
+ *
+ *  Keyed on the base alone, deliberately, even though the naming below keys on width too: the gate
+ *  counts how many addresses compete for registers during argument setup, and two accesses of the
+ *  same address at different widths are still ONE address. Counting them separately would pass the
+ *  gate on `callee(*(u8 *)&g, *(u16 *)&g)`, where nothing reorders and there is nothing to fix. */
+function distinctBases(nodes: Extract<Expr, { k: 'index' }>[]): Extract<Expr, { k: 'index' }>[] {
+  const out: Extract<Expr, { k: 'index' }>[] = [];
+  for (const n of nodes) {
+    if (!out.some((o) => baseIdentity(o.base) === baseIdentity(n.base))) {
+      out.push(n);
+    }
+  }
+  return out;
+}
+
+/** The (base, width, signedness) key an `index` shares with every other access through the same
+ *  base — so ALL of a base's uses in one call rewrite to the same local, not just the first. */
+function baseKey(n: Extract<Expr, { k: 'index' }>): string {
+  return `${baseIdentity(n.base)} ${n.width} ${n.signed}`;
+}
+
+/**
+ * The `/argbase` re-spelling, or null when no statement qualifies (the caller then adds no
+ * candidate at all rather than a duplicate of the primary).
+ */
+export function materializeArgBases(sfn: SFn): SFn | null {
+  const globals = new Set((sfn.globals ?? []).map((g) => g.name));
+  const fresh = nameAllocator(sfn);
+  const newLocals: { name: string; type: IrType }[] = [];
+  let fired = false;
+
+  // Rewrite ONE statement into the list that replaces it: the naming assignments, then the
+  // statement with its qualifying bases pointed at them. The naming goes immediately BEFORE the
+  // statement holding the call, not at the function top — the compiler loads these addresses where
+  // it needs them, and hoisting further extends live ranges the original never had (the
+  // register-pressure failure basecse.ts's loop gate exists for).
+  //
+  // NOTE the shape: recursion happens per FIELD, through an exhaustive switch, and the `pre`
+  // insertion happens INSIDE it. Rebuilding a statement from a flattened `stmtChildren` list cannot
+  // work — inserting statements shifts the boundary the rebuild would have to split at, and
+  // `stmtChildren('for')` is `[init, inc, ...body]`, which is not a body. Both mistakes produce
+  // COMPILING but wrong C (a call migrating across an if/else boundary; a `for` init duplicated
+  // into its body), which no boundary contract checks: they check resolution and spellability, not
+  // statement placement.
+  const rewrite = (s: Stmt): Stmt[] => {
+    const pre: Stmt[] = [];
+    const localFor = new Map<string, string>();
+    // Only the statement's OWN expressions can carry a call this pass names bases for; nested
+    // statement lists get their own `pre`, in their own scope, via the recursion below.
+    //
+    // A LOOP's own expression is its CONDITION, which runs every iteration — but `pre` lands
+    // BEFORE the loop, which would make this a loop-invariant hoist to a point the original never
+    // had. That is the register-pressure failure basecse.ts's `inLoop` gate exists to refuse, and
+    // it would contradict this pass's own placement rule two comments down. So a loop's condition
+    // is left alone; only its body (via the recursion) is eligible.
+    const ownExprs = s.k === 'while' || s.k === 'dowhile' || s.k === 'for' ? [] : stmtExprs(s);
+    for (const e of ownExprs) {
+      const scan = (x: Expr): void => {
+        if (x.k === 'call') {
+          const bases = distinctBases(argBases(x, globals));
+          if (bases.length >= 2) {
+            for (const b of bases) {
+              const key = baseKey(b);
+              if (localFor.has(key)) {
+                continue;
+              }
+              const ptrType = T.ptr(scalarTypeForAccess(b.width, b.signed));
+              const nm = fresh();
+              localFor.set(key, nm);
+              newLocals.push({ name: nm, type: ptrType });
+              pre.push({ k: 'assign', name: nm, value: { k: 'cast', to: ptrType, e: b.base } });
+            }
+            fired = true;
+          }
+        }
+        mapExprChildren(x, (c) => {
+          scan(c);
+          return c;
+        });
+      };
+      scan(e);
+    }
+    const point = (e: Expr): Expr => {
+      if (e.k === 'index' && !e.lead?.length && eligibleBase(e.base, globals)) {
+        const nm = localFor.get(baseKey(e));
+        if (nm) {
+          return { ...e, base: { k: 'var', name: nm }, idx: point(e.idx) };
+        }
+      }
+      return mapExprChildren(e, point);
+    };
+    const kids = (list: Stmt[]): Stmt[] => list.flatMap(rewrite);
+    let out: Stmt;
+    switch (s.k) {
+      case 'assign':
+        out = { ...s, value: point(s.value) };
+        break;
+      case 'store':
+        out = { ...s, lval: point(s.lval), value: point(s.value) };
+        break;
+      case 'exprstmt':
+        out = { ...s, value: point(s.value) };
+        break;
+      case 'return':
+        out = s.value === undefined ? s : { ...s, value: point(s.value) };
+        break;
+      case 'if':
+        out = { ...s, cond: point(s.cond), then: kids(s.then), else: kids(s.else) };
+        break;
+      case 'while':
+      case 'dowhile':
+        out = { ...s, cond: point(s.cond), body: kids(s.body) };
+        break;
+      case 'for': {
+        // `init`/`inc` are single statements. A `pre` produced inside either has nowhere legal to
+        // go (before the loop changes when it runs; inside the body repeats it), so this pass
+        // declines to fire there and leaves them alone.
+        out = { ...s, cond: point(s.cond), body: kids(s.body) };
+        break;
+      }
+      case 'switch':
+        out = {
+          ...s,
+          scrutinee: point(s.scrutinee),
+          cases: s.cases.map((c) => ({ ...c, body: kids(c.body) })),
+          ...(s.default ? { default: kids(s.default) } : {}),
+        };
+        break;
+      case 'break':
+      case 'continue':
+        out = s;
+        break;
+    }
+    if (pre.length === 0) {
+      return [out];
+    }
+    return [...pre, out];
+  };
+
+  const body = sfn.body.flatMap(rewrite);
+  return fired ? { ...sfn, body, locals: [...sfn.locals, ...newLocals] } : null;
+}

package/src/l3/ast.ts

@@ -38,7 +38,13 @@ export type Expr =
   // Variable-index `a[i]` is recovered at the IR level (`aload`/`astore` carry elemSize;
   // raise/arrays.ts) but still LOWERS to this one C-shaped `index` node, so it stays C-only
   // (a Pascal array-access spelling is future work). Treat `index` with idx ≠ 0 as C-shaped.
-  | { k: 'index'; base: Expr; idx: Expr; width: number; signed: boolean }
+  // `lead` prefixes CONSTANT subscripts before `idx` — `g[0][i]` rather than `g[i]`. It exists for
+  // exactly one inhabitant: the bare-name spelling of a MULTIDIMENSIONAL array global, where one
+  // subscript reaches a row and the element needs the leading dimensions pinned first. The node
+  // still denotes ONE `width`-byte element, so its type, its legalization and its stride contract
+  // are unchanged — this is a spelling of the same address, not a new kind of access. Absent for
+  // every rank-1 access, which is why it is optional rather than an empty array.
+  | { k: 'index'; base: Expr; idx: Expr; width: number; signed: boolean; lead?: number[] }
   // A named struct-field access `base->name` (raise/structs.ts recovered `base` as a struct
   // pointer, so the byte offset resolves to a named field instead of a scaled array index).
   // Unlike `index`, this carries the field NAME (which encodes the byte offset, `field_<off>`),
@@ -53,8 +59,45 @@ export type Expr =
   // default) never produces this node; it keeps the `"?"` sentinel → ContractError behavior.
   | { k: 'marker'; reason: string; args: Expr[] };
 
+// `>>` is the ARITHMETIC right shift and `>>>` the LOGICAL one. C spells both `>>` and picks from
+// the left operand's type, so the C backend synthesizes the cast that pins the choice — exactly as
+// it already synthesizes scalar deref casts from an `index` node's width. A backend with no
+// spelling for one of them (IDO Pascal) declines LOUDLY on the operation itself, rather than on
+// whatever artifact another language's spelling happened to leave in the tree.
+//
+// WHY THIS ONE SPLIT AND NOT THE OTHERS. "The machine distinguishes them" is NOT the rule — the
+// machine distinguishes `divu`/`div` and `sltu`/`slt` too, and ARITH_TO_BIN deliberately collapses
+// `udiv`→`/`, `umod`→`%`, `icmp_u*`→`<` etc., noting that "unsignedness is in the operand types".
+// Taking the machine as the rule would license four more splits with no inhabitant, which is what
+// "earn the level" forbids. The rule is the repo's own: the shift split because a real,
+// byte-load-bearing divergence HAD inhabitants (~20 rows, 5 projects, 4 compilers) and no other
+// channel could carry it — the operand type could not, since a promoted narrow value is signed
+// whatever it was loaded as.
+//
+// The collapsed operators lean on exactly that channel, so they carry the same latent hazard:
+// `*(u16 *)p / 3` renders as a signed division of a promoted `int` where the asm did `divu`. It is
+// tolerated because no row has produced such a divergence. When one does, the fix is this same
+// split — not a per-site patch.
 export type BinOp =
-  '+' | '-' | '*' | '/' | '%' | '<' | '<=' | '>' | '>=' | '==' | '!=' | '&' | '|' | '^' | '<<' | '>>' | '&&' | '||';
+  | '+'
+  | '-'
+  | '*'
+  | '/'
+  | '%'
+  | '<'
+  | '<='
+  | '>'
+  | '>='
+  | '=='
+  | '!='
+  | '&'
+  | '|'
+  | '^'
+  | '<<'
+  | '>>'
+  | '>>>'
+  | '&&'
+  | '||';
 
 export type Stmt =
   | { k: 'assign'; name: string; value: Expr }
@@ -189,11 +232,27 @@ export function exprEquals(a: Expr, b: Expr): boolean {
     }
     case 'index': {
       const bb = b as typeof a;
-      return a.width === bb.width && a.signed === bb.signed && exprEquals(a.base, bb.base) && exprEquals(a.idx, bb.idx);
+      // `lead` is part of the ADDRESS (`g[0][i]` and `g[1][i]` are different elements), so it
+      // must be compared — an omission here would let CSE/dedup collapse two distinct accesses.
+      const lead = a.lead ?? [];
+      const bLead = bb.lead ?? [];
+      return (
+        a.width === bb.width &&
+        a.signed === bb.signed &&
+        lead.length === bLead.length &&
+        lead.every((v, i) => v === bLead[i]) &&
+        exprEquals(a.base, bb.base) &&
+        exprEquals(a.idx, bb.idx)
+      );
     }
     case 'field': {
       const bb = b as typeof a;
-      return a.name === bb.name && exprEquals(a.base, bb.base);
+      // `dot` is part of the SPELLING, and for the same reason `lead` is compared above: a CSE or
+      // dedup that treats these as equal keeps one node and discards the other, silently respelling
+      // `p->field_4` as `p.field_4` (or the reverse). Both compile only for the base type each
+      // belongs to, so collapsing them is how a valid access becomes an invalid one — or worse, a
+      // valid one against a different object.
+      return a.name === bb.name && (a.dot ?? false) === (bb.dot ?? false) && exprEquals(a.base, bb.base);
     }
     case 'marker': {
       const bb = b as typeof a;
@@ -305,3 +364,58 @@ export function stmtChildren(s: Stmt): Stmt[] {
       return [...s.cases.flatMap((c) => c.body), ...(s.default ?? [])];
   }
 }
+
+// THE negation of a CONDITION — the one implementation, shared by every L3 pass that flips one.
+//
+// There were two, and they drifted: structure.ts's empty-then peephole learned to distribute over
+// the short-circuit connectives while l3/dce.ts's copy kept wrapping in `!`, and because
+// `eliminateDeadStores` runs AFTER structuring it re-introduced the very spelling the other one had
+// just removed. That is the l3/hoist.ts failure mode verbatim — a copied helper silently losing the
+// newer rule — so this lives with the AST vocabulary and the passes call it.
+//
+// Three rules, in order:
+//   1. a relational operator flips directly (`!=` → `==`, `<` → `>=`, …), exact over C's total
+//      integer order;
+//   2. DE MORGAN — `!(a && b)` becomes `!a || !b`. Sound including EVALUATION ORDER: `a && b` runs
+//      `b` only when `a` holds, and `!a || !b` runs `!b` only when `!a` is false, i.e. when `a`
+//      holds. Same operands, same inputs — which is what makes it safe over a `b` that loads. It
+//      matters because a source `&&` and its dual `||` compile to the SAME branch graph, so the
+//      recognizers in raise/shortcircuit.ts can only pick whichever the asm's branch senses spell;
+//      distributing is what lets the `/flip-branch` candidate reach the other one;
+//   3. `!!x` collapses to `x`, reachable only from a double flip that rule 2 now produces.
+//
+// CONTEXT REQUIREMENT, and it is the reason this is `negateCond` and not `negate`: rule 3 is valid
+// only in a TRUTH-VALUE context, where `x` and `!!x` are interchangeable. `!!5` is 1 and `5` is 5,
+// so this must never be used to negate a general integer expression — only an `if`/loop test or an
+// operand of one of the connectives above.
+//
+// SCOPE of rule 2: it only gives the differ a second spelling where a candidate lever already flips
+// the condition, and `preserveDivergentBranchSense` covers divergent `if`s ONLY. A connective that
+// ended up as a LOOP test therefore has no dual candidate at all — the differ never sees the other
+// form, so on such a row this rule changes how the code READS and nothing else. Widening the
+// branch-sense lever to loop tests is what would make it a matching lever there, and that is a
+// separate change.
+const NEGATE_REL: Partial<Record<BinOp, BinOp>> = {
+  '<': '>=',
+  '>=': '<',
+  '>': '<=',
+  '<=': '>',
+  '==': '!=',
+  '!=': '==',
+};
+
+export function negateCond(e: Expr): Expr {
+  if (e.k === 'bin') {
+    const flipped = NEGATE_REL[e.op];
+    if (flipped) {
+      return { ...e, op: flipped };
+    }
+    if (e.op === '&&' || e.op === '||') {
+      return { ...e, op: e.op === '&&' ? '||' : '&&', l: negateCond(e.l), r: negateCond(e.r) };
+    }
+  }
+  if (e.k === 'un' && e.op === '!') {
+    return e.e;
+  }
+  return { k: 'un', op: '!', e };
+}

package/src/l3/basecse.ts

@@ -21,6 +21,7 @@
 import { type IrType, T, scalarTypeForAccess } from '../ir/types';
 import type { Expr, SFn, Stmt } from './ast';
 import { mapExprChildren, stmtChildren, stmtExprs } from './ast';
+import { nameAllocator } from './hoist';
 
 // A HOISTABLE base is a bare `addr` (a global address) or a bare `const` (a numeric pointer
 // address). Both are relocation-invariant leaves whose value the compiler keeps in one register
@@ -135,17 +136,6 @@ function rewriteStmt(s: Stmt, localFor: Map<string, string>): Stmt {
   }
 }
 
-/** A name not already used by a param/local/global in `sfn`, of the form `p<n>`. */
-function freshName(taken: Set<string>): string {
-  let n = 0;
-  while (taken.has(`p${n}`)) {
-    n++;
-  }
-  const nm = `p${n}`;
-  taken.add(nm);
-  return nm;
-}
-
 export function hoistReusedGlobalBases(sfn: SFn): SFn {
   const c: Collected = { count: new Map(), order: [], meta: new Map(), inLoop: new Set(), constOffCount: new Map() };
   collect(sfn.body, c, false);
@@ -171,9 +161,7 @@ export function hoistReusedGlobalBases(sfn: SFn): SFn {
     return sfn;
   }
 
-  const taken = new Set<string>([...sfn.params.map((p) => p.name), ...sfn.locals.map((l) => l.name)]);
-  // globals are referenced by name; a hoist name must not shadow one that appears in the body.
-  collectNames(sfn.body, taken);
+  const fresh = nameAllocator(sfn);
 
   const localFor = new Map<string, string>();
   const newLocals: { name: string; type: IrType }[] = [];
@@ -181,7 +169,7 @@ export function hoistReusedGlobalBases(sfn: SFn): SFn {
   for (const k of hoisted) {
     const m = meta.get(k)!;
     const ptrType = T.ptr(scalarTypeForAccess(m.width, m.signed));
-    const nm = freshName(taken);
+    const nm = fresh();
     localFor.set(k, nm);
     newLocals.push({ name: nm, type: ptrType });
     // `p = (T *)base` — the cast makes the local the access's pointer type so each `p[i]` strides it.
@@ -191,28 +179,3 @@ export function hoistReusedGlobalBases(sfn: SFn): SFn {
   const body = [...hoistStmts, ...sfn.body.map((s) => rewriteStmt(s, localFor))];
   return { ...sfn, body, locals: [...sfn.locals, ...newLocals] };
 }
-
-/** Every `var`/`addr`/called-function name mentioned anywhere in `stmts` (so a hoist name collides
- *  with none — a global via `addr`, a local via `var`, OR a callee via `call.fn`). */
-function collectNames(stmts: Stmt[], out: Set<string>): void {
-  const walk = (e: Expr): void => {
-    if (e.k === 'var' || e.k === 'addr') {
-      out.add(e.name);
-    }
-    if (e.k === 'call') {
-      out.add(e.fn); // a hoist local must not shadow a called function symbol
-    }
-    for (const c of exprChildrenOf(e)) {
-      walk(c);
-    }
-  };
-  for (const s of stmts) {
-    if (s.k === 'assign') {
-      out.add(s.name);
-    }
-    for (const e of stmtExprs(s)) {
-      walk(e);
-    }
-    collectNames(stmtChildren(s), out);
-  }
-}

package/src/l3/coalesce.ts

@@ -0,0 +1,146 @@
+import { typeToString } from '../ir/types';
+import type { Expr, SFn, Stmt } from './ast';
+import { exprChildren, mapExprChildren, stmtChildren, stmtExprs } from './ast';
+
+function namesIn(e: Expr, out: Set<string>): void {
+  // `addr` names a GLOBAL, never a local — collected anyway. A name reaching BOTH forms would
+  // otherwise get a span that ignores its `addr` mentions, and a SHORT span is a clobber while a
+  // long one is only a missed merge. `structure.ts` keeps locals to /^[vt]\d+$/ and excludes global
+  // names, so this cannot fire today; collecting is the direction that stays safe if that changes.
+  if (e.k === 'var' || e.k === 'addr') out.add(e.name);
+  for (const c of exprChildren(e)) namesIn(c, out);
+}
+
+/** Does `e` mention `n` anywhere? */
+function mentions(e: Expr, n: string): boolean {
+  const seen = new Set<string>();
+  namesIn(e, seen);
+  return seen.has(n);
+}
+interface Span {
+  first: number;
+  last: number;
+  inLoop: boolean;
+  constFed: boolean;
+  /** the local's FIRST mention is a write, not a read */
+  firstIsWrite: boolean;
+}
+function spans(body: Stmt[]): Map<string, Span> {
+  const out = new Map<string, Span>();
+  let at = 0;
+  const walk = (list: Stmt[], inLoop: boolean): void => {
+    for (const s of list) {
+      at++;
+      const here = new Set<string>();
+      if (s.k === 'assign') here.add(s.name);
+      for (const e of stmtExprs(s)) namesIn(e, here);
+      for (const n of here) {
+        const sp = out.get(n) ?? {
+          first: at,
+          last: at,
+          inLoop,
+          constFed: true,
+          // an assign that ALSO READS the name (`b = g(b)`) is not a pure write; treating it as one
+          // let `g` receive the absorbed value
+          firstIsWrite: s.k === 'assign' && s.name === n && !stmtExprs(s).some((e) => mentions(e, n)),
+        };
+        sp.last = at;
+        sp.inLoop ||= inLoop;
+        if (s.k === 'assign' && s.name === n && s.value.k !== 'const') sp.constFed = false;
+        out.set(n, sp);
+      }
+      walk(stmtChildren(s), inLoop || s.k === 'while' || s.k === 'dowhile' || s.k === 'for');
+    }
+  };
+  walk(body, false);
+  return out;
+}
+function rename(body: Stmt[], from: string, to: string): Stmt[] {
+  const inExpr = (e: Expr): Expr =>
+    e.k === 'var' && e.name === from ? { ...e, name: to } : mapExprChildren(e, inExpr);
+  const inStmt = (s: Stmt): Stmt => {
+    const r = { ...s } as Record<string, unknown>;
+    if (s.k === 'assign' && s.name === from) r.name = to;
+    for (const key of ['value', 'lval', 'cond', 'scrutinee'] as const) {
+      const v = (s as Record<string, unknown>)[key];
+      if (v !== undefined) r[key] = inExpr(v as Expr);
+    }
+    for (const key of ['then', 'else', 'body', 'default'] as const) {
+      const v = (s as Record<string, unknown>)[key];
+      if (Array.isArray(v)) r[key] = (v as Stmt[]).map(inStmt);
+    }
+    if (s.k === 'for') {
+      r.init = inStmt(s.init);
+      r.inc = inStmt(s.inc);
+    }
+    if (s.k === 'switch') r.cases = s.cases.map((c) => ({ ...c, body: c.body.map(inStmt) }));
+    return r as Stmt;
+  };
+  return body.map(inStmt);
+}
+/** Every legal single merge, each as its own tree — NOT one committed choice.
+ *
+ *  Which pair a register allocator coalesced is not derivable from the L3 tree, and first-fit gets
+ *  it wrong: on kleod:UpdateHUDCounterDisplay the two legal merges score 18 and 40 against a
+ *  no-merge baseline of 21, and declaration order picks the 40. `rank.ts` already has the idiom for
+ *  exactly this — `/regcopy`'s "the tail choice is allocator-ambiguous, so both are ranked" — so
+ *  every candidate is emitted and the differ referees.
+ *
+ *  GATES:
+ *   - a local mentioned inside a loop BODY is excluded. SOUND-critical: it is what makes preorder
+ *     statement order a sufficient approximation of liveness. Preorder is a topological order of the
+ *     CFG except where a later-indexed statement can run before an earlier one, and the positions
+ *     that do that — a `for`'s `init`/`inc`, and everything in any loop body — are inside a loop, so
+ *     the gate covers them. A loop's own CONDITION is NOT covered: it is visited at the loop
+ *     statement's own index with the ENCLOSING loop flag. That is safe only because a condition
+ *     cannot WRITE, so it can extend a read range but never reorder a definition — an earlier
+ *     version of this comment claimed the gate covered conditions too, which it does not.
+ *     Differential fuzzing supports this: removing the gate produces clobbers immediately, leaving
+ *     it on produces none. No such harness is committed, so nothing here re-checks it.
+ *   - both must be CONSTANT-fed. A codegen heuristic, not soundness — removing it stayed
+ *     clobber-free under the same (uncommitted) fuzz and simply scored worse, because a load-fed
+ *     local is one the compiler had a reason to keep where it was. It is also what currently BOUNDS
+ *     candidate growth: merges are `L(L-1)/2` in the local count, each a distinct source and so a
+ *     distinct compile, and nothing else caps that. Corpus-wide today: 2 rows, 13 kept sources.
+ *   - the survivor's first mention must be an ASSIGN THAT DOES NOT ALSO READ IT. `b = g(b)` is a
+ *     write and a read in one statement; counting it as a pure write let `g` receive the absorbed
+ *     value. These two gates are NOT independent: `constFed` also rejects a self-reading assign
+ *     (its value is not a literal), so it masks this one. No committed test isolates it — this is
+ *     defence-in-depth for the day `constFed` is relaxed, which the note above makes plausible.
+ *
+ *  ACCEPTED, NOT FIXED: a survivor assigned only on SOME paths still absorbs the other's value on
+ *  the paths that skip it. The original read an uninitialized local there, so both spellings are
+ *  ill-defined rather than one being wrong — but this is a real difference and the differ, not this
+ *  gate, is what keeps it from faking a match. */
+export function coalesceCandidates(sfn: SFn): { merged: string; sfn: SFn }[] {
+  if (sfn.locals.length < 2) {
+    return [];
+  }
+  const params = new Set(sfn.params.map((p) => p.name));
+  const typeOf = new Map(sfn.locals.map((l) => [l.name, typeToString(l.type)]));
+  const sp = spans(sfn.body);
+  const out: { merged: string; sfn: SFn }[] = [];
+  for (const a of sfn.locals.map((l) => l.name)) {
+    for (const b of sfn.locals.map((l) => l.name)) {
+      const x = sp.get(a);
+      const y = sp.get(b);
+      if (a === b || !x || !y || params.has(a) || params.has(b)) {
+        continue;
+      }
+      if (typeOf.get(a) !== typeOf.get(b) || x.inLoop || y.inLoop || !x.constFed || !y.constFed) {
+        continue;
+      }
+      if (x.last >= y.first || !y.firstIsWrite) {
+        continue;
+      }
+      // Labelled by the PAIR, not by an index into enumeration order: an index silently re-points
+      // at a different merge if `sfn.locals` ordering ever changes, leaving a recorded provenance
+      // that is wrong but plausible.
+      out.push({
+        merged: `${a}-${b}`,
+        sfn: { ...sfn, body: rename(sfn.body, a, b), locals: sfn.locals.filter((l) => l.name !== a) },
+      });
+    }
+  }
+  return out;
+}