@asmlift/core 0.8.1 → 0.10.0

package/src/l3/ast.ts

@@ -6,15 +6,49 @@ import { type IrType, typeEquals } from '../ir/types';
 export type Expr =
   | { k: 'var'; name: string }
   | { k: 'const'; value: number }
-  | { k: 'bin'; op: BinOp; l: Expr; r: Expr }
-  | { k: 'un'; op: '-' | '~' | '!'; e: Expr }
+  // A `double` literal, carried as its IEEE bit pattern (ir/float-bits.ts) — a kind apart from the
+  // integer `const`, so no integer fold, range test or signedness reading ever takes it for one.
+  | { k: 'fconst'; bits: string }
+  // `unsignedCmp` is EVIDENCE, not spelling: an ordering compare (`<` `<=` `>` `>=`) lowered from an
+  // `icmp_u*`, which C spells with the same token as the signed one and decides from the operand
+  // types. The printer never reads it; `signedOverUnsignedCompare` (l3/typing.ts) does, over the
+  // FINISHED tree, so a pass that substitutes into a compare cannot re-spell it signed unseen.
+  // `exprEquals` ignores it, as it ignores `index.operandOff`: two nodes that print alike are
+  // alike to a CSE. A merge that keeps one of two equal nodes keeps it through `unionEvidence`, so
+  // the evidence of the one it drops is not lost with it.
+  //
+  // `helperRel` is evidence too: on a float `==`/`!=`, the relation the SOURCE spelled, where the
+  // compiler picked a runtime helper by it (runtime-helpers.ts `RuntimeHelper.relation` — agbcc's
+  // `__eqsf2` and `__nesf2`). It rides through `negateCond` unchanged, so a node whose `op` is not
+  // its `helperRel` is one a negation moved off the helper, and `keepsHelperRel` /
+  // `regainsHelperRel` below are what a pass choosing between `if (c) A else B` and
+  // `if (!c) B else A` asks. Ignored by `exprEquals` and by the printer, like `unsignedCmp`.
+  | { k: 'bin'; op: BinOp; l: Expr; r: Expr; unsignedCmp?: true; helperRel?: BinOp }
+  | { k: 'un'; op: '-' | '~' | '!' | 'f-'; e: Expr }
+  // A post-increment `name++` (`by` 1) or post-decrement `name--` (`by` -1): the value the local
+  // held BEFORE the update, with the update as a side effect. The only expression form here that
+  // WRITES anything, so `exprHasEffect` answers for it alongside `call` and `marker` — that is what
+  // every pass asking "may I move or duplicate this" already consults. It also NAMES a local, so
+  // `mentionedName` answers for it beside `var` and `addr`, and the two walks that classify their
+  // own leaves — `l3/mentions.ts` and `contracts.ts`'s `assertLocalsWritten` — count it on both
+  // sides, because `v++` reads the name and writes it.
+  //
+  // The target is a NAME rather than an Expr because its one producer has one: structure.ts's
+  // `emitDoWhile`, folding a loop update into a bottom test that reads the variable at its
+  // pre-update value (`while (v0 != 0 && v1++ <= 9)`). A general lvalue has no inhabitant.
+  //
+  // WHERE IT MAY STAND IS THE PRODUCER'S OBLIGATION, not a property of the node: C89 leaves the
+  // program undefined when the same object is also read elsewhere between two sequence points, and
+  // short-circuit operators decide whether the update happens at all. `PREUPDATE_COND_GATES`
+  // (structure/hazards.ts) holds both rules for the one producer.
+  | { k: 'postincr'; name: string; by: 1 | -1 }
   // A C-style value cast `(T)e`. Tree-level producers: a width-narrowing cast `(u8)e` (the
   // recovered form of a byte/half extend idiom — zext/sext IR ops), the STRUCT-pointer cast
   // (structure.ts memAccess/arrayAccess struct paths — see the note on `field` below), and the
-  // integer legalization of a pointer operand under an operator C rejects (structure.ts intify,
-  // `3 & (s32)p`). Scalar deref casts are backend-owned — the C-family printer synthesizes
-  // them from the `index` node's width. Each backend spells the cast in its own syntax
-  // (C: `(u8)e`; Pascal: no spelling yet → fails loud).
+  // integer legalization of a pointer operand under an operator C rejects (the arithmetic table,
+  // structure/pointer-spelling.ts: `3 & (s32)p`). Scalar deref casts are backend-owned — the
+  // C-family printer synthesizes them from the `index` node's width. Each backend spells the cast
+  // in its own syntax (C: `(u8)e`; Pascal: no spelling yet → fails loud).
   //
   // `volatile` qualifies the POINTEE of a pointer cast (`(volatile u16 *)0x4000208`) — the one
   // place asmlift can say "this access is to a volatile object" when there is no declaration to
@@ -22,12 +56,58 @@ export type Expr =
   // cv-qualifier, deliberately: volatility is a SPELLING, carried at the declaration or the
   // cast, the same split SFn.locals makes for `volatile`/`pointeeVolatile`.
   | { k: 'cast'; to: IrType; e: Expr; volatile?: true }
-  | { k: 'call'; fn: string; args: Expr[] }
+  // A call. `wide64` is the INTEGER RANK the callee's return renders with, and it is carried on the
+  // node because nothing downstream can derive it: a callee's return type comes from a prototype
+  // outside the emitted function, so `exprCType` answers `undefined` for a call and every reader of
+  // the rendered rank would otherwise read C's implicit `int`.
+  //
+  // IT IS TRUE OF THE C THAT IS COMPILED BECAUSE THE SOURCES AGREE, and that agreement is a
+  // property of one lookup rather than of two modules happening to match. The width is set where
+  // the frontend was TOLD it — a compiler's own runtime-helper signature, whose callee the
+  // candidate never declares because the helper table IS the declaration, or a project's
+  // `FnProto.returns`, which `proto.ts` `spellableProto` admits only when the same entry can be
+  // PRINTED as the callee's own prototype. `prototypesFromSymbols` resolves that table once, so
+  // the frontend that stamps this and the collector that prints the declaration read one answer.
+  // The filters in `rank-declare.ts` can still withhold a printed declaration (a name the emitted
+  // C uses for its own storage, a non-identifier, a reserved name) — every one of them kills the
+  // SPELLING or the whole row rather than leaving this stamp standing over an implicitly-`int`
+  // callee.
+  //
+  // `sret` is the type of a struct the callee returns BY VALUE through memory. `args[0]` is then the
+  // hidden pointer the frontend read from the first argument register — the address of the struct
+  // the call fills — and the rest are the declared arguments. The only C spelling is a statement,
+  // `dest = fn(rest)`, so such a call stands alone. `returns` is the type of a struct the callee
+  // returns BY VALUE in registers, where the call is that value itself, `return mk(x);`
+  // (frontend/register-struct-call.ts); the declarations block prints its prototype by it.
+  //
+  // `byValue` names the arguments that are a struct passed BY VALUE — a local or a global spelled
+  // bare, `take(s)` — by their place in `args` and the declared parameter each is, with the struct
+  // the declaration passes
+  // (frontend/call-plan.ts `foldByValueArgs`); the declarations block defines each beside the
+  // callee's prototype.
+  //
+  // `fn` is the callee's NAME, or for an indirect call the EXPRESSION whose value is the address
+  // called (ir/core.ts `calleeValue`) — a child of the node like its arguments, listed first in
+  // `exprChildren`. That is no evaluation order: C leaves it unspecified, and agbcc loads the callee
+  // after the arguments.
+  | {
+      k: 'call';
+      fn: string | Expr;
+      args: Expr[];
+      wide64?: true;
+      sret?: IrType;
+      returns?: IrType;
+      byValue?: readonly { readonly at: number; readonly param: number; readonly type: IrType }[];
+    }
   // The ADDRESS of a named global, `&gSym` (agbcc pool `.word gSym`, frontend `gaddr` op). A
   // DEREF of it collapses to the bare global: memAccess/arrayAccess spell `*(&gSym)` as `gSym`
   // and `(&gSym)[i]` as `gSym[i]` (a global name decays to a pointer). Only a genuinely
   // address-TAKEN global (passed by address, `&gSym` as a call arg) prints the `&` form. The
   // global's type comes from the project headers, so it is never declared as a local.
+  //
+  // An ARRAY's address is spelled by the bare name, and that is a fact of C's declarator grammar
+  // rather than of the address — so the C printer decides it from the name's declared type, and
+  // this node carries nothing about it (backend/cfamily.ts, `case 'addr'`).
   | { k: 'addr'; name: string }
   // A memory access `base[idx]` (printed `*base` when idx is the constant 0), CARRYING the
   // access's element width (bytes) and signedness. `idx` counts elements of `width` bytes.
@@ -142,6 +222,15 @@ export type Expr =
       operandOff?: number;
       baseOrdered?: true;
       baseAdvanced?: number;
+      /** Spell element 0 as `base[0]`, never `*base`. The two are one lvalue to C and NOT to
+       *  agbcc's alias analysis: `u.half[0]` is an ARRAY_REF of a union member, alias set 0
+       *  (c-common.c `c_get_alias_set`), while `*u.half` dereferences the member's decay — an
+       *  INDIRECT_REF typed by its pointee, which a compiled `*u.half = 1; *u.word = x; return
+       *  *u.half;` returns stale (`mov r0, #0x1`) where the subscript reloads. Set on a view of a
+       *  frame union (structure.ts `frameUnionAccess`), the one access that rests on that set,
+       *  and on an element of a frame array, where it only keeps the element spelling at index 0
+       *  (structure.ts `frameArrayElement`, l3/constinit.ts `asElement`). */
+      subscript?: true;
     }
   // 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).
@@ -176,15 +265,36 @@ export type Expr =
 // The divides earned it second, on pokeemerald:GetAnchorCoord — `(u32)(coord * a1) / (u32)a0`
 // standing beside two arithmetic shifts of the same values. Their only other channel is the operand
 // TYPES, reached by flipping a declaration, and there that flip is unreachable and unsound at
-// once: the divisor also feeds a signed compare, so the /uns-cmp reconciliation correctly refuses
-// it, and forcing it anyway makes agbcc delete the comparison as always-false. A per-operand pin is
-// the only spelling that says "this division alone is unsigned".
+// once: the divisor also feeds a signed compare, so the unsigned-compare reconciliation
+// (structure.ts unsignedCompareSpelling) correctly refuses it, and forcing it anyway makes agbcc
+// delete the comparison as always-false. A per-operand pin is the only spelling that says "this
+// division alone is unsigned".
 //
 // The COMPARISONS stay collapsed, and that asymmetry is the rule applying rather than an omission:
 // which side a compare was spelled from genuinely underdetermines — a signed spelling that
 // byte-matched was proved non-negative by the compiler — so it is refereed as a variation, while a
 // division helper is a pure function of the expression's C type with no such proof available.
+//
+// THE FLOAT OPERATORS (`f+` `f-` `f*` `f/`) are the third split, and they are earned by what an
+// integer operator MEANS to the passes that read one rather than by a spelling: C writes both with
+// the same token, but `/` here is the SIGNED divide the C-family backend pins with `(s32)` casts,
+// and `+`/`-` are the pointer walks, reassociations and constant folds of a dozen L3 passes. A float
+// under any of those is a wrong program, so it gets operators none of them match — the same reason
+// the IR has `fadd` rather than a float-typed `add`. The unary minus splits the same way (`f-` on
+// `un`). The float COMPARES split for the same reason and one more: NaN makes them a partial order,
+// so `negateCond` may flip `f==` and `f!=` into each other and no other — `!(a f> b)` is not
+// `a f<= b`, and it prints as the `!` it is.
 export type BinOp =
+  | 'f+'
+  | 'f-'
+  | 'f*'
+  | 'f/'
+  | 'f<'
+  | 'f<='
+  | 'f>'
+  | 'f>='
+  | 'f=='
+  | 'f!='
   | '+'
   | '-'
   | '*'
@@ -234,7 +344,15 @@ export type Stmt =
   // `break;` / `continue;` — a loop early-exit / next-iteration jump. Emitted ONLY when the target is
   // the innermost enclosing loop (bare C break/continue cannot express a multi-level exit; a deeper
   // target declines). SGI/IDO Pascal has neither, so its backend loud-fails them (like `field`/`cast`).
-  | { k: 'break' }
+  //
+  // `ofSwitch` makes the `break` the innermost enclosing SWITCH's instead: it leaves the arm it sits
+  // in for the code after the switch (`case 1: if (c) break; case 2: …`). Legal only inside a switch
+  // arm with no loop or switch between it and that arm — the producer's contract (structure.ts
+  // `switchBreakAt`). The C family prints both as `break;`, so its printer refuses each where C
+  // would bind it to the other kind — a plain one between `case` labels, this one in a loop body
+  // (backend/cfamily.ts `refuseMisboundBreak`). A pass that reads `break` as a loop exit must skip
+  // this one (l3/reindex.ts `hasLoopExit`).
+  | { k: 'break'; ofSwitch?: true }
   | { k: 'continue' }
   // A multi-way `switch` over an integer scrutinee (recovered from a comparison tree — Regime A — or
   // a jump-table `switch_br` — Regime B). `cases` are emitted IN ARRAY ORDER; `default` (if present)
@@ -337,11 +455,27 @@ export interface SFn {
      *  one are deliberately left unstamped even where the offset is in hand — see the refusal at
      *  the structurer's build site for the measurement that decided it. */
     slots?: number[];
+    /** The declaration's initializer, element by element, null where the source left one out
+     *  (`SImage.init`) — present only on the copy the C-family emitter prints, where
+     *  l3/constinit.ts folded the block copy of the compiler's anonymous constant image into it
+     *  (`u8 sp0[16] = { … };`). Never on a tree a pass sees. */
+    init?: (number | InitAddress | null)[];
+    /** that initializer is spelled as a string literal — the image was written as one */
+    initString?: true;
   }[];
   /** 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. */
   globals?: { name: string; type: IrType }[];
+  /** The function-scope statics this function DEFINES (structure/local-statics.ts), declared at
+   *  the top of its body ahead of the locals. Unlike `globals`, the backend declares these: no
+   *  header does, because the source defined them here. */
+  statics?: SStatic[];
+  /** The compiler's own constant images this function copies a local's initializer from
+   *  (structure/local-statics.ts), under labels the source never wrote. Not statics: no declaration
+   *  may spell one, so the C-family emitter folds each into the initializer of the local its copy
+   *  fills (l3/constinit.ts), and a backend that cannot refuses. */
+  images?: SImage[];
   retType: IrType;
   body: Stmt[];
   /** Struct types this function's fields reference, declared above it by the backend. Empty
@@ -359,6 +493,63 @@ export interface SFn {
    *  `TargetDescription.compilerBehaviors`. ABSENT means the direction is unknown for this target
    *  and `l3/slotorder.ts` is the identity — never "ascending by default". */
   slotOrder?: 'ascending' | 'descending';
+  /** Each declared callee's parameter types (an entry the printer cannot spell is `undefined`):
+   *  what an argument converts to. Read by the C-family printer where `dialect` says C++ or
+   *  `strictConversions` is set, either of which refuses three conversions C makes implicitly
+   *  (backend/cfamily.ts `argConversion`), and by the pointer-cell conversions in every dialect
+   *  (l3/ptrcell.ts). */
+  declaredArgs?: Readonly<Record<string, readonly (string | undefined)[]>>;
+  /** Each declared callee's return type as the project spells it, never printed: whether a call a
+   *  pointer cell is compared with returns a pointer (l3/ptrcell.ts). */
+  declaredReturns?: Readonly<Record<string, string>>;
+  /** The emitted C is compiled AS C++. An emission policy like `slotOrder`. */
+  dialect?: 'c++';
+  /** The compiler parses a designated element in an initializer (`[8] = 2`) — a fact of its
+   *  dialect, carried from `compilerBehaviors.designatedInitializers`. An emission policy: the
+   *  C-family printer spells an initializer's left-out run by index where present, as zeros where
+   *  not. */
+  designators?: true;
+  /** The compiler refuses C's implicit pointer conversions in C as well, as C++ does — carried from
+   *  `compilerBehaviors.strictPointerConversions`. An emission policy: the C-family printer casts an
+   *  argument to its declared parameter (`declaredArgs`), and a pointer of another pointee written
+   *  into a pointer slot, wherever it would for C++. */
+  strictConversions?: true;
+}
+
+/** An initial element that is an ADDRESS CONSTANT (ir/core.ts `LocalObject.relocs`): `symbol`'s
+ *  address plus `addend` bytes, held in the element's integer type — a global's, which a
+ *  declaration outside the function names. */
+export interface InitAddress {
+  symbol: string;
+  addend: number;
+}
+
+/** One function-scope static's definition: `static [const] T name[count] = { init };`. `init` is
+ *  the initial elements in order, absent for a static with no initializer (the target's bss); an
+ *  element the target relocates is the {@link InitAddress} it holds. `align` is an alignment in
+ *  bytes wider than the type's own, which the definition must state. */
+export interface SStatic {
+  name: string;
+  type: IrType;
+  const?: true;
+  align?: number;
+  init?: (number | InitAddress)[];
+  /** the initializer is spelled as a string literal — a byte array the compiler aligns as a
+   *  string (structure/local-statics.ts) */
+  string?: true;
+}
+
+/** One constant image of the compiler's own (ir/core.ts `LocalObject.anonymous`), named by its
+ *  label: an integer array typed by the directives that wrote it, and its initializer element by
+ *  element — null where the source left one out (padding in the image, which C supplies as zero),
+ *  the {@link InitAddress} an element the target relocates holds, and ending at the last one it
+ *  spelled, so it may be shorter than `type`. */
+export interface SImage {
+  name: string;
+  type: IrType;
+  init: (number | InitAddress | null)[];
+  /** the image was written as a string literal (`.ascii`) */
+  string?: true;
 }
 
 /** A struct declaration surfaced to the backend (name + field list). Mirrors the IR struct
@@ -381,6 +572,13 @@ export interface LanguageBackend {
    *  cannot print it turns a whole function that used to decompile into a loud stub. The
    *  structurer reads it through `StructureOptions.spellSwitchFallthrough`. */
   readonly spellsSwitchFallthrough: boolean;
+  /** Can this language spell a `break` that leaves a `switch` arm before its end
+   *  (`{ k: 'break', ofSwitch: true }`)? C and C++ can; Pascal has no `break` at all, and its
+   *  backend loud-fails the node. Asked for the same reason as `spellsSwitchFallthrough`: a
+   *  closed arm with a mid-arm exit (`case 10: if (a) { if (b) break; g(1); } h(2); break;`) also
+   *  spells without one, by copying the code the arm meets at into each path, which Pascal prints.
+   *  The structurer reads it through `StructureOptions.spellSwitchBreak`. */
+  readonly spellsSwitchBreak: boolean;
   emit(fn: SFn): string;
   // Spell ONE LINE of text as a comment in this language (C block comments, Pascal `(* … *)`).
   // Used by the annotate-mode stub path to carry the failure reason + the original asm
@@ -427,6 +625,8 @@ export function exprEquals(a: Expr, b: Expr): boolean {
       return a.name === (b as typeof a).name;
     case 'const':
       return a.value === (b as typeof a).value;
+    case 'fconst':
+      return a.bits === (b as typeof a).bits;
     case 'bin': {
       const bb = b as typeof a;
       return a.op === bb.op && exprEquals(a.l, bb.l) && exprEquals(a.r, bb.r);
@@ -435,6 +635,10 @@ export function exprEquals(a: Expr, b: Expr): boolean {
       const bb = b as typeof a;
       return a.op === bb.op && exprEquals(a.e, bb.e);
     }
+    case 'postincr': {
+      const bb = b as typeof a;
+      return a.name === bb.name && a.by === bb.by;
+    }
     case 'cast': {
       const bb = b as typeof a;
       // `volatile` is part of the SPELLING, compared for the same reason `lead` and `dot` are: a
@@ -448,7 +652,29 @@ export function exprEquals(a: Expr, b: Expr): boolean {
     }
     case 'call': {
       const bb = b as typeof a;
-      return a.fn === bb.fn && a.args.length === bb.args.length && a.args.every((x, i) => exprEquals(x, bb.args[i]));
+      // `wide64` is part of the node's IDENTITY, compared for the same reason `volatile` is one
+      // cast up: it decides the rank every operand pin is taken at, so two calls that differ in it
+      // are two different expressions and a dedup that kept one would respell the other's
+      // arithmetic.
+      //
+      // NO PIPELINE INPUT REACHES THIS TERM TODAY, and saying so is cheaper than a witness that
+      // cannot exist: the stamp is a pure function of the callee name (`structure.ts` reads the
+      // call result's IR width, which the frontend set from the callee's declared return), so two
+      // `call` nodes sharing `fn` and `args` always share `wide64` and deleting the term leaves
+      // the whole core suite green. What pins it is a direct test of THIS function's contract in
+      // test/int64-repr.test.ts, over two nodes built by hand — which is the honest bar, because
+      // the claim being made is about `exprEquals` and not about a path through the pipeline.
+      return (
+        (typeof a.fn === 'string' || typeof bb.fn === 'string' ? a.fn === bb.fn : exprEquals(a.fn, bb.fn)) &&
+        (a.wide64 ?? false) === (bb.wide64 ?? false) &&
+        (a.sret === undefined ? bb.sret === undefined : bb.sret !== undefined && typeEquals(a.sret, bb.sret)) &&
+        (a.returns === undefined
+          ? bb.returns === undefined
+          : bb.returns !== undefined && typeEquals(a.returns, bb.returns)) &&
+        (a.byValue ?? []).map((x) => x.at).join() === (bb.byValue ?? []).map((x) => x.at).join() &&
+        a.args.length === bb.args.length &&
+        a.args.every((x, i) => exprEquals(x, bb.args[i]))
+      );
     }
     case 'index': {
       const bb = b as typeof a;
@@ -493,12 +719,103 @@ export function exprEquals(a: Expr, b: Expr): boolean {
   }
 }
 
-/** 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
+/** Do two statements print the same C? The leaf statements compare through {@link exprEquals},
+ *  and an `if` arm by arm; every other kind answers no, which can only keep apart two statements a
+ *  caller might have merged. */
+export function stmtEquals(a: Stmt, b: Stmt): boolean {
+  switch (a.k) {
+    case 'assign':
+      return b.k === 'assign' && a.name === b.name && exprEquals(a.value, b.value);
+    case 'store':
+      return b.k === 'store' && exprEquals(a.lval, b.lval) && exprEquals(a.value, b.value);
+    case 'exprstmt':
+      return b.k === 'exprstmt' && exprEquals(a.value, b.value);
+    case 'return':
+      return (
+        b.k === 'return' &&
+        (a.unspelled ?? false) === (b.unspelled ?? false) &&
+        (a.value === undefined ? b.value === undefined : b.value !== undefined && exprEquals(a.value, b.value))
+      );
+    case 'if':
+      return b.k === 'if' && exprEquals(a.cond, b.cond) && stmtsEqual(a.then, b.then) && stmtsEqual(a.else, b.else);
+    default:
+      return false;
+  }
+}
+
+/** {@link stmtEquals} over two lists, in order. */
+export function stmtsEqual(a: readonly Stmt[], b: readonly Stmt[]): boolean {
+  return a.length === b.length && a.every((s, i) => stmtEquals(s, b[i]));
+}
+
+/** The node a merge KEEPS when it found `a` and `b` equal ({@link exprEquals}) and drops one: `a`,
+ *  with every compare carrying `unsignedCmp` if it did in EITHER. Equality ignores the evidence
+ *  because two compares that print alike are one expression to C; but when one of them was lowered
+ *  from an `icmp_u` and the other from a signed compare, the kept node now stands for both paths,
+ *  and the finished-tree judgment (l3/typing.ts `signedOverUnsignedCompare`) can only see the
+ *  unsigned one's obligation if the node still says so. Keeping `a` bare would publish a signed
+ *  `x < y` on the path that compared unsigned (an slt arm and an sltu arm merged by l3/tailmerge.ts
+ *  under `/signed-cmp`). Precondition: `exprEquals(a, b)`, so the two trees walk in step. */
+export function unionEvidence(a: Expr, b: Expr): Expr {
+  // `mapExprChildren` calls `f` in `exprChildren` order (an object literal evaluates its
+  // properties in source order), so the i-th call pairs with b's i-th child. Not by identity: one
+  // child object may sit in two positions, each with its own counterpart in `b`.
+  const bs = exprChildren(b);
+  let i = 0;
+  const out = mapExprChildren(a, (c) => unionEvidence(c, bs[i++]));
+  return out.k === 'bin' && b.k === 'bin' && b.unsignedCmp === true && out.unsignedCmp !== true
+    ? { ...out, unsignedCmp: true }
+    : out;
+}
+
+/** {@link unionEvidence} over two statements {@link stmtEquals} found equal. */
+export function unionStmtEvidence(a: Stmt, b: Stmt): Stmt {
+  switch (a.k) {
+    case 'assign':
+      return b.k === 'assign' ? { ...a, value: unionEvidence(a.value, b.value) } : a;
+    case 'store':
+      return b.k === 'store'
+        ? { ...a, lval: unionEvidence(a.lval, b.lval), value: unionEvidence(a.value, b.value) }
+        : a;
+    case 'exprstmt':
+      return b.k === 'exprstmt' ? { ...a, value: unionEvidence(a.value, b.value) } : a;
+    case 'return':
+      return b.k === 'return' && a.value !== undefined && b.value !== undefined
+        ? { ...a, value: unionEvidence(a.value, b.value) }
+        : a;
+    case 'if':
+      return b.k === 'if'
+        ? {
+            ...a,
+            cond: unionEvidence(a.cond, b.cond),
+            then: unionStmtsEvidence(a.then, b.then),
+            else: unionStmtsEvidence(a.else, b.else),
+          }
+        : a;
+    default:
+      return a;
+  }
+}
+
+/** {@link unionStmtEvidence} over two lists {@link stmtsEqual} found equal. */
+export function unionStmtsEvidence(a: readonly Stmt[], b: readonly Stmt[]): Stmt[] {
+  return a.map((s, i) => unionStmtEvidence(s, b[i]));
+}
+
+/** THE spelling of an `opaque`'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 : '?'}'`;
+ *  and never firing, since it is an EQUALITY between what the IR carries and what the output shows.
+ *
+ *  TWO PRODUCERS, TWO SENTENCES, and they name different capabilities: an INSTRUCTION no frontend
+ *  decodes (`adc`), and a call into the compiler's own RUNTIME that no recogniser folded
+ *  (`__div2i`). The attrs decide which, so a producer chooses by what it stamps rather than by
+ *  spelling a string. `?` when a frontend stamps neither. */
+export function gapReasonFor(attrs: { mnemonic?: unknown; helper?: unknown }): string {
+  if (typeof attrs.helper === 'string') {
+    return `no model for the runtime helper '${attrs.helper}'`;
+  }
+  return `unmodelled instruction '${typeof attrs.mnemonic === 'string' ? attrs.mnemonic : '?'}'`;
 }
 
 // ── the ONE traversal vocabulary ───────────────────────────────────────────────────────────────
@@ -513,7 +830,9 @@ export function exprChildren(e: Expr): Expr[] {
   switch (e.k) {
     case 'var':
     case 'const':
+    case 'fconst':
     case 'addr':
+    case 'postincr':
       return [];
     case 'bin':
       return [e.l, e.r];
@@ -521,7 +840,7 @@ export function exprChildren(e: Expr): Expr[] {
     case 'cast':
       return [e.e];
     case 'call':
-      return e.args;
+      return typeof e.fn === 'string' ? e.args : [e.fn, ...e.args];
     case 'index':
       return [e.base, ...(e.lead ?? []), e.idx];
     case 'field':
@@ -536,7 +855,9 @@ export function mapExprChildren(e: Expr, f: (c: Expr) => Expr): Expr {
   switch (e.k) {
     case 'var':
     case 'const':
+    case 'fconst':
     case 'addr':
+    case 'postincr':
       return e;
     case 'bin':
       return { ...e, l: f(e.l), r: f(e.r) };
@@ -544,7 +865,7 @@ export function mapExprChildren(e: Expr, f: (c: Expr) => Expr): Expr {
     case 'cast':
       return { ...e, e: f(e.e) };
     case 'call':
-      return { ...e, args: e.args.map(f) };
+      return { ...e, ...(typeof e.fn === 'string' ? {} : { fn: f(e.fn) }), args: e.args.map(f) };
     case 'index':
       return { ...e, base: f(e.base), ...(e.lead ? { lead: e.lead.map(f) } : {}), idx: f(e.idx) };
     case 'field':
@@ -654,7 +975,7 @@ export function rematerializableAddress(e: Expr): boolean {
       case 'un':
         break;
       default:
-        ok = false; // var, addr, index, field, call, marker
+        ok = false; // var, addr, postincr, index, field, call, marker
         return;
     }
     for (const c of exprChildren(x)) {
@@ -665,10 +986,27 @@ export function rematerializableAddress(e: Expr): boolean {
   return ok && nonZero;
 }
 
-/** Whether the tree contains a node with an EFFECT no re-ordering may move: a call, or a marker
- *  standing in for an unmodelled instruction (annotate mode). */
+/** The local or global a node NAMES, or undefined for one that names none — the whole Expr
+ *  vocabulary a "which names does this tree mention" walk has to know about, in one place, because
+ *  a collector that misses a kind reports a SHORT live range and a short range is a clobber where a
+ *  long one is only a missed merge.
+ *
+ *  `call`'s `fn` is not one of them: it names a function, and the walks that care about that ask
+ *  for it beside this (l3/hoist.ts). A walk that must tell the kinds APART — `&v` is a write where
+ *  a bare `v` is a read — keeps its own arms; this answers the name, not what is done to it. */
+export function mentionedName(e: Expr): string | undefined {
+  return e.k === 'var' || e.k === 'addr' || e.k === 'postincr' ? e.name : undefined;
+}
+
+/** The callee a call names, or undefined for an indirect one. */
+export function calleeOf(e: Extract<Expr, { k: 'call' }>): string | undefined {
+  return typeof e.fn === 'string' ? e.fn : undefined;
+}
+
+/** Whether the tree contains a node with an EFFECT no re-ordering may move: a call, a marker
+ *  standing in for an unmodelled instruction (annotate mode), or a post-increment's write. */
 export function exprHasEffect(e: Expr): boolean {
-  return e.k === 'call' || e.k === 'marker' || exprChildren(e).some(exprHasEffect);
+  return e.k === 'call' || e.k === 'marker' || e.k === 'postincr' || exprChildren(e).some(exprHasEffect);
 }
 
 /** Whether the tree performs an access to a `volatile` object — the OTHER thing no re-ordering may
@@ -703,6 +1041,44 @@ function* subterms(e: Expr): Generator<Expr> {
   }
 }
 
+export type Assign = Extract<Stmt, { k: 'assign' }>;
+
+/** Every `assign` in the tree, at any nesting. ORDER-FREE: its callers ask what a name is ever
+ *  assigned, never which assignment comes first, so a switch default's position does not matter. */
+export function assignsIn(body: readonly Stmt[]): Assign[] {
+  const out: Assign[] = [];
+  const visit = (s: Stmt): void => {
+    if (s.k === 'assign') {
+      out.push(s);
+    }
+    stmtChildren(s).forEach(visit);
+  };
+  body.forEach(visit);
+  return out;
+}
+
+/** Grow `seed` over assignments to a fixpoint: an assignment adds its target when `propagates`
+ *  says its value carries what the set holds so far. A FLOW-INSENSITIVE taint, which is what each
+ *  caller wants — the question is what a name may EVER hold, so one assignment anywhere is
+ *  enough. Callers own the seed and the rule; this owns only the iteration. */
+export function taintOverAssigns(
+  assigns: readonly Assign[],
+  seed: Iterable<string>,
+  propagates: (a: Assign, tainted: ReadonlySet<string>) => boolean,
+): Set<string> {
+  const tainted = new Set(seed);
+  for (let grew = true; grew;) {
+    grew = false;
+    for (const a of assigns) {
+      if (!tainted.has(a.name) && propagates(a, tainted)) {
+        tainted.add(a.name);
+        grew = true;
+      }
+    }
+  }
+  return tainted;
+}
+
 /** The statements a statement DIRECTLY contains, in the order a backend prints them — a `switch`
  *  splices its default in at `defaultAt` for that reason. NOTE for document-order walks: a `for`'s
  *  init/inc are listed here while its cond is in stmtExprs — a walker visiting exprs-then-stmts
@@ -905,8 +1281,76 @@ export const NEGATE_REL: Partial<Record<BinOp, BinOp>> = {
   '<=': '>',
   '==': '!=',
   '!=': '==',
+  // C's float `==` is false on a NaN and `!=` true, so these two are each other's negation; the
+  // ordered four have none in the operator vocabulary (the BinOp note).
+  'f==': 'f!=',
+  'f!=': 'f==',
 };
 
+/** The compares under `e`'s connectives whose runtime helper names the relation the source spelled
+ *  (`helperRel`), each answering whether it spells that relation now. `negateCond` flips every one
+ *  of them at once, through De Morgan. */
+function helperRelLeaves(e: Expr, out: boolean[] = []): boolean[] {
+  if (e.k === 'bin' && (e.op === '&&' || e.op === '||')) {
+    helperRelLeaves(e.l, out);
+    helperRelLeaves(e.r, out);
+  } else if (e.k === 'bin' && e.helperRel !== undefined) {
+    out.push(e.op === e.helperRel);
+  }
+  return out;
+}
+
+/** Whether `e` spells, at every compare of it whose runtime helper names the relation the source
+ *  spelled, that relation — so that negating `e` recompiles to the other helper at each of them:
+ *  the relation's twin and its `!` alike, since gcc folds `!(a == b)` into `a != b`. An arm swap
+ *  that would negate it keeps `e` and its arm order instead. */
+export function keepsHelperRel(e: Expr): boolean {
+  const leaves = helperRelLeaves(e);
+  return leaves.length > 0 && leaves.every((own) => own);
+}
+
+/** Whether negating `e` puts every such compare back on its helper's relation: the swap a pass
+ *  would otherwise leave alone is the one that spells the helpers. A condition mixing the two has
+ *  neither answer, and no arm order spells it. */
+export function regainsHelperRel(e: Expr): boolean {
+  const leaves = helperRelLeaves(e);
+  return leaves.length > 0 && leaves.every((own) => !own);
+}
+
+/** A loop's stay condition `P && S` whose compares under `S` are all negated off their helper's
+ *  relation, and whose `P` negates none: `{ head: P, guard: !S }`, which the loop spells
+ *  `while (P) { if (!S) break; … }` — the same tests in the same order, calling the helpers the
+ *  source called. `while (P && S)` has no spelling of that `S` that calls the helper (gcc folds
+ *  `!(a == b)` into `a != b`); the break guard is how the source wrote it before the branch fold
+ *  joined the two tests. Null when the condition already spells every helper's relation, or when no
+ *  split of its `&&` chain separates the two kinds of compare. */
+export function splitHelperBreak(cond: Expr): { head: Expr; guard: Expr } | null {
+  if (keepsHelperRel(cond) || helperRelLeaves(cond).length === 0) {
+    return null;
+  }
+  const conj: Expr[] = [];
+  const flatten = (e: Expr): void => {
+    if (e.k === 'bin' && e.op === '&&') {
+      flatten(e.l);
+      flatten(e.r);
+    } else {
+      conj.push(e);
+    }
+  };
+  flatten(cond);
+  const and = (xs: Expr[]): Expr => xs.reduce((l, r) => ({ k: 'bin', op: '&&', l, r }));
+  // The longest prefix that negates no helper leaf; the rest must negate every one it holds.
+  let k = 0;
+  while (k < conj.length && helperRelLeaves(conj[k]).every((own) => own)) {
+    k++;
+  }
+  if (k === 0 || k === conj.length) {
+    return null;
+  }
+  const rest = and(conj.slice(k));
+  return regainsHelperRel(rest) ? { head: and(conj.slice(0, k)), guard: negateCond(rest) } : null;
+}
+
 export function negateCond(e: Expr): Expr {
   if (e.k === 'bin') {
     const flipped = NEGATE_REL[e.op];