@asmlift/core 0.4.0 → 0.6.0

package/src/l3/inlinebase.ts

@@ -0,0 +1,193 @@
+// L3 re-spelling lever: DELETE a pointer local holding a CONSTANT address and spell each access
+// through it as the cast constant (`*(u16 *)0x4000208` rather than `p = (u16 *)0x4000208; *p`).
+//
+// The local is structure/analysis.ts's value-home spelling for a `const` with 2+ consumers that
+// is LIVE ACROSS A CALL: a value the compiler needs after a call survives in a callee-saved
+// register, and a named local reproduces that register. The machine fact is real — agbcc does
+// park the address in `r4` across the calls — but it does NOT imply the source named anything:
+// a constant re-spelled at each use is CSEd into the same one register. So the asm
+// underdetermines the spelling, and this is the differ-refereed other side of it.
+//
+// It is codegen-visible, which is why both sides have to be enumerated rather than one picked:
+// the extra `p = …;` statement is scheduled ahead of the rest of the entry block, so the pool
+// load moves in front of the frame-address materialization the target emits first
+// (pokeemerald:EReader_Reset, agbcc 2.9-arm-000512 — 1 insert + 1 delete, the whole residual).
+//
+// SEMANTICS ARE PRESERVED BY CONSTRUCTION: this is constant propagation of a local that is
+// assigned once, from a compile-time constant, before anything mentions it, and whose address is
+// never taken — so every use reads that constant on every path, and the substituted expression
+// carries the local's own declared type AND its pointee volatility.
+//
+// THE QUALIFIER TRAVELS WITH THE ADDRESS. The deleted local is the only place a `volatile`
+// pointee could be written, and a raw address is precisely the case with no declaration
+// anywhere else to carry it — so dropping it here spells an MMIO access non-volatile in the one
+// place the differ sometimes cannot referee. On pokeemerald:EReader_Reset the two spellings
+// separate at 11 against 12 on their own, and are BYTE-IDENTICAL once the slot qualifier is
+// there too — the shape that matches (agbcc 2.9-arm-000512, `-O2 -mthumb-interwork -Wimplicit
+// -fhex-asm -fprologue-bugfix`; `.s` diff empty, `.o` identical under cmp). So rank.ts emits
+// the qualified spelling as a second OUTPUT of this lever, `/volatile` narrowed to the locals
+// it deletes. Each cast this mints carries the qualifier; a use whose width does not stride the
+// declared pointee renders through the C-family printer's reinterpret cast instead, which
+// carries it too (backend/cfamily.ts) — in C the access takes the OUTER type, so a plain cast
+// there would spell exactly the silent drop this paragraph exists to prevent.
+//
+// GATE (INLINEBASE_GATES) — the local must be all of: pointer-typed; initialized by a bare
+// NONZERO `const` (a `(T *)base` CAST initializer is l3/basecse.ts's reuse hoist, whose own lever
+// family owns that question; `0` is NULL, never an address, which is also the sibling qualifier
+// lever's rule); assigned exactly once, by a statement at the body's TOP LEVEL that no earlier
+// statement's mention precedes; never address-taken; used only as the base of an `index`, at 2+
+// sites (one use is not the reused address this exists for); not object-`volatile` (a
+// `T *volatile p` has no inhabitant, and cfamily.ts prints that flag in the pointee's position);
+// and not `frame` (a slot is an asm fact — see the SFn.locals doc). Anything else, and nothing
+// qualifying at all, DECLINES (null) rather than approximating.
+//
+// A RE-SPELLING RATHER THAN A STRUCTURING AXIS, which is a cost choice and not the
+// underdetermination one (docs/level-tower.md, "a third fork sits inside the ranked population").
+// The question — does a `const` with 2+ consumers live across a call in a named local — is the one
+// `/reread-globals`, `/addr-home`, `/expr-home` and `/derived-home` each answer as a
+// STRUCTURING_AXES entry. An axis here would double the enumeration on every function it admits;
+// substituting on the already-homed tree costs 766 candidates over 47058 (+1.6%) across the 33 of
+// 69 klonoa functions that lift with no symbol map.
+//
+// KNOWN GAP, and it is the price of that choice rather than an oversight: only `index` bases are
+// re-spelled, so the same L2 home passed to a callee or standing as a `field` base is out of
+// reach — `otherUses` refuses it. Reaching those needs the un-homed tree, which is
+// structure/analysis.ts's decision; the day a row demands one, this becomes the axis.
+//
+// The idiom it recovers is every GBA project's register macro: `*(vu16 *)0x4000208` is what
+// `REG_IME` expands to, so the deleted local is not merely an undone home.
+import { type Expr, type SFn, mapExprChildren, mapStmtExprs } from './ast';
+import { type Gate, firstRejection } from './gates';
+import { type Mentions, localMentions } from './mentions';
+
+/** One local as the gates read it. */
+interface BaseCtx {
+  isPointer: boolean;
+  objectVolatile: boolean;
+  hasFrame: boolean;
+  m: Mentions;
+}
+
+export const INLINEBASE_GATES: readonly Gate<BaseCtx>[] = [
+  {
+    id: 'non-pointer',
+    why: 'the lever re-spells an address; a scalar value home is a different question',
+    sound: false,
+    rejects: (c) => !c.isPointer,
+  },
+  {
+    id: 'object-volatile',
+    why: 'the substitution carries the POINTEE flag, so an object-volatile pointer would lose its own',
+    sound: true,
+    guardedBy: 'inlinebase.test.ts: an object-volatile or frame local declines',
+    rejects: (c) => c.objectVolatile,
+  },
+  {
+    id: 'frame',
+    why: 'a slot the asm materialized is an asm fact, not a spelling to undo',
+    sound: false,
+    rejects: (c) => c.hasFrame,
+  },
+  {
+    id: 'multi-assign',
+    why: 'a name assigned more than once is not one constant',
+    sound: true,
+    guardedBy: 'inlinebase.test.ts: a second assignment means the name is not one constant',
+    rejects: (c) => c.m.assigns !== 1,
+  },
+  {
+    id: 'const-init',
+    why: 'only a bare `const` at the body’s top level is an address available on every path',
+    sound: true,
+    guardedBy: 'inlinebase.test.ts: an assignment below the top level may not run on every path',
+    rejects: (c) => c.m.topAssignAt === null || c.m.constValue === null,
+  },
+  {
+    id: 'null-base',
+    why: '`0` is NULL, never an address — the sibling qualifier lever (volatileptr.ts) refuses it too',
+    sound: false,
+    rejects: (c) => c.m.constValue === 0,
+  },
+  {
+    id: 'use-before-assign',
+    why: 'a mention ahead of the assignment reads something the constant does not stand for',
+    sound: true,
+    guardedBy: 'inlinebase.test.ts: a use in a loop ABOVE the assignment reads the local before it is set',
+    rejects: (c) => c.m.firstAt !== c.m.topAssignAt,
+  },
+  {
+    id: 'addr-taken',
+    why: 'a deleted local has no address to take',
+    sound: true,
+    guardedBy: 'inlinebase.test.ts: an address-taken local has an identity the constant cannot stand in for',
+    rejects: (c) => c.m.addrTaken !== 0,
+  },
+  {
+    id: 'other-uses',
+    why: 'a use the substitution cannot reach would name the deleted local',
+    sound: true,
+    guardedBy: 'inlinebase.test.ts: a use that is not an `index` base is outside what the lever re-spells',
+    rejects: (c) => c.m.otherUses !== 0,
+  },
+  {
+    id: 'single-use',
+    why: 'one use is not the reused address this lever exists for',
+    sound: false,
+    rejects: (c) => c.m.baseUses < 2,
+  },
+];
+
+/** The locals INLINEBASE_GATES admits, each with the cast its uses become. */
+function plan(sfn: SFn): Map<string, Extract<Expr, { k: 'cast' }>> {
+  const t = localMentions(sfn);
+  const out = new Map<string, Extract<Expr, { k: 'cast' }>>();
+  for (const l of sfn.locals) {
+    const m = t.get(l.name);
+    if (
+      m === undefined ||
+      firstRejection(INLINEBASE_GATES, {
+        isPointer: l.type.kind === 'ptr',
+        objectVolatile: l.volatile !== undefined,
+        hasFrame: l.frame !== undefined,
+        m,
+      }) !== null
+    ) {
+      continue;
+    }
+    out.set(l.name, {
+      k: 'cast',
+      to: l.type,
+      ...(l.pointeeVolatile ? { volatile: true as const } : {}),
+      e: { k: 'const', value: m.constValue! },
+    });
+  }
+  return out;
+}
+
+/** Which locals this lever would delete — rank.ts narrows `/volatile` to exactly these before
+ *  pairing, so the qualified output never qualifies a pointer the lever leaves standing. */
+export function inlinableConstBases(sfn: SFn): string[] {
+  return [...plan(sfn).keys()];
+}
+
+/** The `/inlinebase` candidate, or null when no local qualifies. Read-only: returns a fresh SFn
+ *  whose body is rebuilt, leaving the input untouched. */
+export function inlineConstBases(sfn: SFn): SFn | null {
+  const inline = plan(sfn);
+  if (inline.size === 0) {
+    return null;
+  }
+  // A FRESH node per use — never one shared tree — because identity-keyed rules downstream
+  // (contracts.ts's dot-base exemption) read node identity.
+  const sub = (e: Expr): Expr => {
+    if (e.k === 'var') {
+      const at = inline.get(e.name);
+      if (at !== undefined) {
+        return { ...at, e: { ...at.e } };
+      }
+    }
+    return mapExprChildren(e, sub);
+  };
+  const body = sfn.body.filter((s) => !(s.k === 'assign' && inline.has(s.name))).map((s) => mapStmtExprs(s, sub));
+  return { ...sfn, locals: sfn.locals.filter((l) => !inline.has(l.name)), body };
+}

package/src/l3/mentions.ts

@@ -0,0 +1,113 @@
+// What one L3 tree does to each of its locals, counted once.
+//
+// Levers ask overlapping versions of the question and would disagree if each walked the tree
+// its own way: l3/inlinebase.ts needs the SHAPE of every use (only an `index` base is re-spellable,
+// and the single assignment must be a top-level `const` nothing mentions earlier), while
+// l3/volatileval.ts needs the COUNTS, to check the tree still performs every access the machine
+// did before it declares them all observable. One walk answers both, and it has to: on the counting
+// consumer a miscount is a wrong `volatile` claim, not a missed candidate.
+//
+// Derived from the ONE traversal vocabulary (exprChildren/stmtExprs/stmtChildren) for every node
+// kind, so a new one is a compile error there rather than a silent undercount here — with `index`
+// as the ONE hand-rolled case, because the callback needs to know which child stands as the base
+// and `exprChildren` flattens that away. That hand-rolling is a standing hazard rather than an
+// oversight: a POSITION added to `index` reaches the generic vocabulary for free and this walk not
+// at all. Every position is enumerated below and pinned by
+// test/array-rank-guards.test.ts, beside the generic helpers it cannot speak for.
+import { type Expr, type SFn, type Stmt, exprChildren, stmtChildren, stmtExprs } from './ast';
+
+export interface Mentions {
+  /** assignments to the name, at any nesting */
+  assigns: number;
+  /** body-top-level index of its single top-level assignment, or null */
+  topAssignAt: number | null;
+  /** the bare-`const` value that assignment stores, or null if it stores anything else */
+  constValue: number | null;
+  addrTaken: number;
+  /** uses as the `base` of an `index` node — the only use shape a base lever can re-spell */
+  baseUses: number;
+  /** every other read */
+  otherUses: number;
+  /** body-top-level index of the first statement mentioning the name at all */
+  firstAt: number | null;
+}
+
+/** reads of the name, however spelled */
+export function readsOf(m: Mentions): number {
+  return m.baseUses + m.otherUses;
+}
+
+const blank = (): Mentions => ({
+  assigns: 0,
+  topAssignAt: null,
+  constValue: null,
+  addrTaken: 0,
+  baseUses: 0,
+  otherUses: 0,
+  firstAt: null,
+});
+
+/** Visit every node, telling the callback whether it stands as an `index`'s base. */
+function walkExpr(e: Expr, visit: (x: Expr, isIndexBase: boolean) => void, isIndexBase = false): void {
+  visit(e, isIndexBase);
+  if (e.k === 'index') {
+    walkExpr(e.base, visit, true);
+    // `lead` — a multidimensional global's LEADING subscripts — is an ordinary value position, so
+    // a name mentioned there is a real read. Missing it does not cost a candidate: it lets a lever
+    // DELETE a local the body still names.
+    for (const l of e.lead ?? []) {
+      walkExpr(l, visit, false);
+    }
+    walkExpr(e.idx, visit, false);
+    return;
+  }
+  for (const c of exprChildren(e)) {
+    walkExpr(c, visit, false);
+  }
+}
+
+/** Every mention of every local, keyed by name. Locals only — a param or a global name is not in
+ *  the map, and a lever asking about one gets `undefined` rather than a zeroed record. */
+export function localMentions(sfn: SFn): Map<string, Mentions> {
+  const t = new Map<string, Mentions>(sfn.locals.map((l) => [l.name, blank()]));
+  const seen = (name: string, at: number): Mentions | undefined => {
+    const m = t.get(name);
+    if (m && m.firstAt === null) {
+      m.firstAt = at;
+    }
+    return m;
+  };
+  const stmt = (s: Stmt, at: number, top: boolean): void => {
+    if (s.k === 'assign') {
+      const m = seen(s.name, at);
+      if (m) {
+        m.assigns++;
+        if (top) {
+          m.topAssignAt = at;
+          m.constValue = s.value.k === 'const' ? s.value.value : null;
+        }
+      }
+    }
+    for (const e of stmtExprs(s)) {
+      walkExpr(e, (x, isIndexBase) => {
+        if (x.k === 'var' || x.k === 'addr') {
+          const m = seen(x.name, at);
+          if (m) {
+            if (x.k === 'addr') {
+              m.addrTaken++;
+            } else if (isIndexBase) {
+              m.baseUses++;
+            } else {
+              m.otherUses++;
+            }
+          }
+        }
+      });
+    }
+    for (const c of stmtChildren(s)) {
+      stmt(c, at, false);
+    }
+  };
+  sfn.body.forEach((s, i) => stmt(s, i, true));
+  return t;
+}

package/src/l3/mulfirst.ts

@@ -0,0 +1,42 @@
+// L3 re-spelling lever: put the PRODUCT operand first in a commutative `+`.
+//
+// structure.ts's def-order rule spells commutative operands in EVALUATION order, which recovers
+// gcc's left-to-right source order. IDO and mwcc break the correspondence for exactly one shape:
+// in `a*b + c` they SCHEDULE the independent load of `c` above the product's `mflo`/`mullw`, so
+// the machine add reads (c, product) and def order re-spells the source's product-first sum as
+// c-first. Which order the source used is not recoverable from positions there — so this lever
+// emits the product-first sibling and the differ referees (verified byte-identical against IDO
+// on the bg_area row; the def-order spelling stays in the list for sources that really were
+// c-first).
+//
+// SCOPE (decline over approximate): a `+` is flipped only when exactly ONE side is a product
+// (`bin('*')` at the root, casts looked through) — two products or none leave nothing to anchor
+// the flip on. A side carrying an effect (a call, a marker) never moves — evaluation order of
+// the operands is what the lever edits. Declines (null) when no `+` changes, so no duplicate
+// candidate.
+import type { Expr, SFn } from './ast';
+import { exprHasEffect, mapExprChildren, mapStmtExprs } from './ast';
+
+const isProduct = (e: Expr): boolean =>
+  e.k === 'bin' && e.op === '*' ? true : e.k === 'cast' ? isProduct(e.e) : false;
+
+export function mulFirstSums(sfn: SFn): SFn | null {
+  let changed = false;
+  const rewrite = (e: Expr): Expr => {
+    const m = mapExprChildren(e, rewrite);
+    if (
+      m.k === 'bin' &&
+      m.op === '+' &&
+      isProduct(m.r) &&
+      !isProduct(m.l) &&
+      !exprHasEffect(m.l) &&
+      !exprHasEffect(m.r)
+    ) {
+      changed = true;
+      return { ...m, l: m.r, r: m.l };
+    }
+    return m;
+  };
+  const body = sfn.body.map((s) => mapStmtExprs(s, rewrite));
+  return changed ? { ...sfn, body } : null;
+}

package/src/l3/nearbase.ts

@@ -0,0 +1,152 @@
+// L3 re-spelling lever: NEIGHBOR absolute addresses derive from one shared base local.
+//
+// A cluster of raw-address accesses a few bytes apart is one object's cells: the compiler holds
+// the object's base in a register and derives each cell (`add #72` / `add #74` off one pool
+// word, a halfword offset beyond the load range forcing the add, the in-range word staying
+// `[rN, #112]`), where a per-cell spelling anchors one pool constant per address. This lever
+// re-spells every deref base in a cluster as an offset from a `u8 *` base local holding the
+// cluster's lowest address, and the differ referees:
+//
+//     *(u16 *)0x0300104A   →   u8 *b = (u8 *)0x03001048;  *(u16 *)(b + 2)
+//
+// SCOPE (decline over approximate): cluster MEMBERSHIP comes from CONST deref bases only (a
+// struct-pointer cast base and everything inside a dot-form field subtree keep their spelling —
+// their stride is the struct's, not a byte's); a cluster needs at least two DISTINCT addresses
+// within the target's declared derivation reach of its lowest (TargetDescription nearBaseSpan —
+// beyond it the derive costs more than the pool word it saves); every access the walk visits
+// rewrites, so a cluster splits only across the field-subtree and struct-pointer-cast
+// boundaries. A member basecse
+// already hoisted arrives as a `var` base and is invisible here — the reused-base and
+// neighbor-base spellings stay separate candidates. Once a cluster HAS formed, a bare const
+// VALUE inside its window re-spells too, as `(s32)(b + off)` — the address of a cell handed to
+// something (a DMA source register) is the same derived add in the original, and the two
+// spellings are value-equal by construction, so the differ referees — including an integer that
+// only coincidentally lands in the window, which is the stated cost of the lever (the `s32` cast
+// assumes addresses below 2^31, true of every target that declares nearBaseSpan today). Declines
+// (null) when no cluster forms.
+import { baseConst } from './address';
+import type { Expr, SFn } from './ast';
+import { mapExprChildren, mapStmtExprs } from './ast';
+import { type BaseInit, nameAllocator, placeBaseLocals } from './hoist';
+
+/** `span` is the target's single-add-immediate derivation reach
+ *  (TargetDescription.compilerBehaviors.nearBaseSpan) — a target that declares none never runs
+ *  this lever. */
+export function nearBaseClusters(sfn: SFn, span: number): SFn | null {
+  if (!Number.isFinite(span) || span < 0) {
+    return null; // a hostile span stalls the cluster window instead of shrinking it
+  }
+  // collect every DISTINCT const deref-base address
+  const addrs = new Set<number>();
+  const collect = (e: Expr): Expr => {
+    if (e.k === 'field') {
+      return e; // a dot-form subtree keeps its struct base — never collected, never rewritten
+    }
+    if (e.k === 'cast' && e.to.kind === 'ptr' && e.to.to.kind === 'struct') {
+      return e; // rewrite refuses these subtrees, so collecting under them would seed a cluster
+    }
+    const m = mapExprChildren(e, collect);
+    if (m.k === 'index') {
+      const c = baseConst(m.base);
+      if (c !== null) {
+        addrs.add(c);
+      }
+    }
+    return m;
+  };
+  for (const s of sfn.body) {
+    mapStmtExprs(s, collect);
+  }
+  // greedy clusters over the sorted addresses; only multi-member clusters rewrite
+  const sorted = [...addrs].sort((a, b) => a - b);
+  const baseOf = new Map<number, number>();
+  for (let i = 0; i < sorted.length;) {
+    const lo = sorted[i];
+    let j = i;
+    while (j < sorted.length && sorted[j] - lo <= span) {
+      j++;
+    }
+    if (j - i >= 2) {
+      for (let k = i; k < j; k++) {
+        baseOf.set(sorted[k], lo);
+      }
+    }
+    i = j;
+  }
+  if (baseOf.size === 0) {
+    return null;
+  }
+  const baseName = new Map<number, string>();
+  const fresh = nameAllocator(sfn); // the shared minting mechanism — collides with nothing in sfn
+  for (const lo of new Set(baseOf.values())) {
+    baseName.set(lo, fresh());
+  }
+  const derived = (lo: number, off: number): Expr =>
+    off === 0
+      ? { k: 'var', name: baseName.get(lo)! }
+      : { k: 'bin', op: '+', l: { k: 'var', name: baseName.get(lo)! }, r: { k: 'const', value: off } };
+  // the cluster (if any) whose window covers a bare const value
+  const windows = [...new Set(baseOf.values())];
+  const coveringLo = (v: number): number | undefined => windows.find((lo) => v >= lo && v - lo <= span);
+  const rewrite = (e: Expr): Expr => {
+    if (e.k === 'field') {
+      return e;
+    }
+    if (e.k === 'index') {
+      const c = baseConst(e.base);
+      const lo = c !== null ? baseOf.get(c) : undefined;
+      if (c !== null && lo !== undefined) {
+        // the base is replaced wholesale — its inner const must not reach the value path below
+        return { ...e, base: derived(lo, c - lo), idx: rewrite(e.idx) };
+      }
+      return { ...e, base: rewrite(e.base), idx: rewrite(e.idx) };
+    }
+    if (e.k === 'cast' && e.to.kind === 'ptr' && e.to.to.kind === 'struct') {
+      return e; // the struct-arrays base keeps its spelling — same refusal as baseConst's
+    }
+    if (e.k === 'const') {
+      const lo = coveringLo(e.value);
+      if (lo !== undefined) {
+        return {
+          k: 'cast',
+          to: { kind: 'int', width: 32, signed: true },
+          e: derived(lo, e.value - lo),
+        };
+      }
+      return e;
+    }
+    return mapExprChildren(e, rewrite);
+  };
+  const inits: BaseInit[] = [...baseName.entries()].map(([lo, name]) => ({
+    k: 'assign',
+    name,
+    value: {
+      k: 'cast',
+      to: { kind: 'ptr', to: { kind: 'int', width: 8, signed: false } },
+      e: { k: 'const', value: lo },
+    },
+  }));
+  const locals = [
+    ...sfn.locals,
+    ...[...baseName.values()].map((name) => ({
+      name,
+      type: { kind: 'ptr', to: { kind: 'int', width: 8, signed: false } } as SFn['locals'][number]['type'],
+    })),
+  ];
+  // The body rebuild is `l3/hoist.ts`'s, shared with the two other passes that place into the
+  // leading base-init run. The ORDERING is not: `prepend` returns before the first-use query, so
+  // this pass takes the rebuild and abstains from the policy (see `BaseInitPlacement`).
+  //
+  // The DEFAULT is `prepend` — the cluster bases go ABOVE a run already there rather than being
+  // merged into it in first-use order — and it rests on a row, not on a compiler fact. Placing
+  // them in first-use order instead turns `synthetic:dmafield` (won by
+  // `signed/livebase/volatile/nearbase/initfirst`) from a MATCH into diff:5, measured 2026-08-26.
+  // The reading that goes with it — a cluster base is reached at 2+ addresses by construction, so
+  // its pool word is not "first touched late" — explains why first-use order is not obviously
+  // right, not why prepending is; which order the source wrote is per-function knowledge the asm
+  // does not carry. So it is a DEFAULT and not a decision: `rank.ts` offers the sunk ordering
+  // beside it as `/nearbase/sinkinit`, and the differ settles which one a function wanted.
+  const rewritten = sfn.body.map((s) => mapStmtExprs(s, rewrite));
+  const { body } = placeBaseLocals({ ...sfn, locals, body: rewritten }, inits, 'prepend');
+  return { ...sfn, locals, body };
+}