@asmlift/core 0.3.0 → 0.5.0

package/src/ir/alias.ts

@@ -0,0 +1,75 @@
+// 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.
+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;
+}
+
+/**
+ * "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/opcodes.ts

@@ -108,8 +108,21 @@ export const OPCODES = {
   //   - 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`.
   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
+  // reserved local area; the Thumb frontend's post-lift audit stamps `name`/`width`/`signed` after
+  // proving every access agrees, and the structurer declares the local and renders `&name` exactly
+  // as it renders a gaddr's `&sym`. Operand-free and pure, so GVN numbers it like gaddr and a dead
+  // one is reaped.
+  // `width`/`signed` are stamped by the frontend's frame-object AUDIT — requiring them makes
+  // "the audit ran" a verifier-checkable fact instead of a convention: a frontend that emits a
+  // laddr and skips the audit fails verify loudly instead of rendering `&undefined`.
+  laddr: { operands: 0, results: 1, requiredAttrs: ['off', 'width', 'signed'] },
   // --- black-box escape hatch (keeps lifting total) ---
-  opaque: { operands: 'variadic', results: 1 },
+  // `effects: true`: an instruction asmlift could not model may do anything — write memory, trap,
+  // touch a system register — and `results[0]` is only the part we can name. So a dead `opaque` is
+  // no more reapable than a dead `call`.
+  opaque: { operands: 'variadic', results: 1, effects: true },
   // --- terminators ---
   ret: { operands: 'variadic', results: 0, terminator: true, successors: 0 },
   br: { operands: 0, results: 0, terminator: true, successors: 1 },
@@ -130,13 +143,54 @@ export function opSig(opcode: string): OpSig | undefined {
   return (OPCODES as Record<string, OpSig | undefined>)[opcode];
 }
 
-/** Ops with an observable side effect — the derived view raise/shortcircuit.ts consumes. */
+/** The comparison whose result is the logical NEGATION of each `icmp_*` — `!(a < b)` is `a >= b`.
+ *
+ *  Unlike EFFECTFUL_OPS/HOIST_UNSAFE_OPS below, this is AUTHORED data seated beside the registry,
+ *  not a view derived from it: nothing in `OPCODES` states which comparison opposes which. What is
+ *  derived is its SYMMETRY — the five involutive pairs are expanded both ways, so `neg(neg(c)) === c`
+ *  holds by construction (a hand-written map is one typo away from breaking it, and the symptom is a
+ *  plainly inverted condition in the emitted C). Completeness against the icmp family is the part
+ *  construction cannot give, so a test asserts it (test/pattern.test.ts) — an eleventh comparison
+ *  added to `OPCODES` would otherwise degrade three consumers three different ways.
+ *
+ *  It lives here for the reason HOIST_UNSAFE_OPS does: every consumer that has to say "the opposite
+ *  of this compare" reads THIS one — the MIPS frontend's `slt …; beqz` branch-when-false fold, the
+ *  short-circuit recognizer's diamond negation, and the idiom layer's `cmp ^ 1` fold — so 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. */
+const ICMP_NEGATION_PAIRS: readonly (readonly [Opcode, Opcode])[] = [
+  ['icmp_eq', 'icmp_ne'],
+  ['icmp_slt', 'icmp_sge'],
+  ['icmp_sgt', 'icmp_sle'],
+  ['icmp_ult', 'icmp_uge'],
+  ['icmp_ugt', 'icmp_ule'],
+];
+export const NEGATED_ICMP: Readonly<Record<string, Opcode>> = Object.fromEntries(
+  ICMP_NEGATION_PAIRS.flatMap(([a, b]) => [
+    [a, b],
+    [b, a],
+  ]),
+);
+
+/** Ops with an observable side effect: the flag on the signature, derived rather than re-listed.
+ *  Consumed by `isDceSafe`, by `HOIST_UNSAFE_OPS` below, and by structure.ts's `sideEffects` walk
+ *  (an effectful op whose result nobody reads is still an execution). */
 export const EFFECTFUL_OPS: ReadonlySet<string> = new Set(
   (Object.keys(OPCODES) as Opcode[]).filter((k) => (OPCODES[k] as OpSig).effects),
 );
 
+/** Ops that may not be REORDERED across other code. Identical to `EFFECTFUL_OPS` — one flag answers
+ *  both "deletable when dead" and "movable when live" — and kept as its own name because the call
+ *  sites ask the reordering question. Derived here rather than re-spelled per consumer:
+ *  structure/analysis.ts and structure/structure.ts each carry their own inline copy of this
+ *  membership, which is how the two models drifted apart in the first place. */
+export const HOIST_UNSAFE_OPS: ReadonlySet<string> = EFFECTFUL_OPS;
+
 /** May a dead result of this opcode be deleted? Registered, no observable effects, not control
- *  flow. Deliberately includes `opaque` — a dead opaque vanishing is designed behavior. */
+ *  flow. `opaque` is excluded via its `effects` flag — see the note on its signature. */
 export function isDceSafe(opcode: string): boolean {
   const sig = opSig(opcode);
   return !!sig && !sig.effects && !sig.terminator;

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,221 @@
+// 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.
+ *
+ *  NO shadowing filter, unlike scopebase.ts's `isLeaf`, and the asymmetry is deliberate: that pass
+ *  re-spells the base as `&g`, which under a shadowing local names a different object, while this
+ *  one keeps the base expression verbatim and places the assignment immediately before the same
+ *  statement. Adding the filter here only loses hoists (test/addr-placement.test.ts). */
+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 }
@@ -110,7 +153,7 @@ export interface SwitchCase {
 export interface SFn {
   name: string;
   params: { name: string; type: IrType }[];
-  locals: { name: string; type: IrType }[]; // recovered locals, declared at function top
+  locals: { name: string; type: IrType; volatile?: true }[]; // recovered locals, declared at function top
   /** project globals referenced with a known declaration shape (symbol map) — typed for the
    *  legalization env (exprCType) but NEVER declared by a backend: the project's own headers
    *  declare them, exactly like every other global name asmlift emits. */
@@ -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;
@@ -212,6 +271,14 @@ export function exprEquals(a: Expr, b: Expr): boolean {
 // recognizeForLoops) rightly keep their own switches.
 
 /** The direct sub-expressions of `e`, in syntactic order. */
+/** THE spelling of an unmodelled instruction's gap reason, in one place: `structure.ts` writes it
+ *  into the marker, `contracts.ts` matches on it to prove the gap was not dropped, and the benchmark
+ *  classifies declines by it. Two spellings make that contract silently vacuous — enforced-looking
+ *  and never firing. `?` when a frontend stamps no mnemonic. */
+export function gapReasonFor(mnemonic: unknown): string {
+  return `unmodelled instruction '${typeof mnemonic === 'string' ? mnemonic : '?'}'`;
+}
+
 export function exprChildren(e: Expr): Expr[] {
   switch (e.k) {
     case 'var':
@@ -305,3 +372,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 };
+}