@asmlift/core 0.5.0 → 0.7.0

package/src/ir/verify.ts

@@ -3,7 +3,9 @@
 //   1. every block ends in exactly one terminator (and it is the last op)
 //   2. operands well-formed: opcode registered, correct arity/attrs
 //   3. SSA: each value defined once; every use is defined; def dominates use
-import { Block, Fn, Value, predecessors } from './core';
+//   4. side data: a fn that carries a write-order record carries one for EVERY block, with every
+//      ordinal inside that block's own write count (ir/core.ts `WriteOrder`)
+import { Block, Fn, Value, dominators } from './core';
 import { opSig } from './opcodes';
 
 export class VerifyError extends Error {}
@@ -133,42 +135,8 @@ export function verify(fn: Fn): void {
     );
   }
 
-  // --- dominance (iterative dominators over the CFG) ---
-  const entry = fn.blocks[0];
-  const preds = predecessors(fn);
-  const dom = new Map<Block, Set<Block>>();
-  const allBlocks = new Set(fn.blocks);
-  for (const b of fn.blocks) {
-    dom.set(b, b === entry ? new Set([entry]) : new Set(allBlocks));
-  }
-  let changed = true;
-  while (changed) {
-    changed = false;
-    for (const b of fn.blocks) {
-      if (b === entry) {
-        continue;
-      }
-      let inter: Set<Block> | null = null;
-      for (const p of preds.get(b)!) {
-        const dp = dom.get(p)!;
-        if (inter === null) {
-          inter = new Set(dp);
-          continue;
-        }
-        for (const x of inter) {
-          if (!dp.has(x)) {
-            inter.delete(x);
-          }
-        } // intersect in place (spec-safe delete-in-iter)
-      }
-      const next = new Set<Block>(inter ?? []);
-      next.add(b);
-      if (!setEq(next, dom.get(b)!)) {
-        dom.set(b, next);
-        changed = true;
-      }
-    }
-  }
+  // --- dominance: def must dominate every use (ir/core.ts owns the analysis) ---
+  const dom = dominators(fn);
   const dominates = (a: Block, b: Block) => dom.get(b)!.has(a);
 
   for (const b of fn.blocks) {
@@ -193,6 +161,44 @@ export function verify(fn: Fn): void {
       ),
     );
   }
+
+  checkWriteOrder(fn);
+}
+
+/** THE WRITE-ORDER RECORD'S CROSS-PASS OBLIGATION, checked rather than trusted (ir/core.ts
+ *  `WriteOrder`, `foldWriteOrder`), because the consequence of missing it is silent: an unmeasured
+ *  block's edge copies sort with no records at all, changing the order the structurer emits them in
+ *  and, on a cycle, which register it spills. No decline, no marker.
+ *
+ *  WHAT IT CATCHES: a pass that MINTS a block into a measured fn, or drops a block's entry, leaving
+ *  a hole indistinguishable from a fn nobody measured. Also an ordinal outside its block's own
+ *  write count — a `foldWriteOrder` that moved records without growing the count. WHAT IT CANNOT:
+ *  ops moved from one MEASURED block into another with the fold forgotten, since both blocks still
+ *  have entries and no snapshot of the IR shows the move. That half stays a review obligation until
+ *  the record hangs on `Successor` itself.
+ *
+ *  A fn is "measured" iff it has any entry at all; one with none is parsed or hand-built IR, whose
+ *  edges take the def-position proxy by design. */
+function checkWriteOrder(fn: Fn): void {
+  const order = fn.writeOrder;
+  if (order === undefined || order.writes.size === 0) {
+    return;
+  }
+  for (const b of fn.blocks) {
+    const writes = order.writes.get(b);
+    if (writes === undefined) {
+      throw new VerifyError(
+        `fn '${fn.name}': block ^bb${fn.blocks.indexOf(b)} carries no write-order entry, but the fn is measured`,
+      );
+    }
+    for (const at of order.lastWrite.get(b)?.values() ?? []) {
+      if (at < 0 || at >= writes) {
+        throw new VerifyError(
+          `fn '${fn.name}': write-order ordinal ${at} on block ^bb${fn.blocks.indexOf(b)} is outside its ${writes} writes`,
+        );
+      }
+    }
+  }
 }
 
 /** Run a check body; a VerifyError it throws is re-thrown with the op's location appended —
@@ -207,15 +213,3 @@ function locate(body: () => void, where: () => string): void {
     throw e;
   }
 }
-
-function setEq(a: Set<Block>, b: Set<Block>): boolean {
-  if (a.size !== b.size) {
-    return false;
-  }
-  for (const x of a) {
-    if (!b.has(x)) {
-      return false;
-    }
-  }
-  return true;
-}

package/src/l3/address.ts

@@ -0,0 +1,62 @@
+// asmlift — THE THREE READINGS OF A CONSTANT ADDRESS, in one place because they are three and not
+// one, and because the same four lines had been re-typed into five files at three strengths.
+//
+// A raw address reaches L3 as a cast chain over a `const`, and "which numeric cell is this" has
+// three different right answers depending on what the caller intends to DO with the answer. The
+// readings are deliberately not merged; what this module supplies is names for them, so a pass
+// declares which one it means instead of restating four lines and drifting.
+//
+//   • baseConst   — a deref BASE, through SCALAR pointer casts only. A cast to a STRUCT pointer is
+//     the dot-form's base and is refused, because a respell variation that re-spells THROUGH it collapses the
+//     stride (`((struct S *)K)[i].f` is not `((u8 *)K)[…]`). This is the reading a respell variation that
+//     REWRITES the base needs: l3/nearbase.ts's clusters, l3/volstore.ts's qualifier.
+//   • addrConst   — the address an expression IS, through ANY pointer cast. Wider, and safe
+//     because nothing re-spells through it: l3/volatileptr.ts counts volatility claims with it.
+//   • rootConst   — the constant an ACCESS CHAIN is rooted at, through any cast and any number of
+//     subscripts and field selections. Wide enough to place an object whose element is not known,
+//     which is what a read with a runtime subscript needs (l3/unreduce.ts's aliasing gate).
+//
+// And `cellAddress`, which is not a fourth reading of a base but the WHOLE address an `index`
+// denotes — base plus subscript × width — or null when any part of it is not constant.
+//
+// A CAUTION THE HISTORY EARNED: `rootConst` and `cellAddress` disagree, and a predicate that uses
+// one on its write side and the other on its read side is not the same predicate on both. A read
+// rooted at 0x03FFFFF0 whose element is `[8]` denotes 0x04000010 — a device register the root
+// reports as EWRAM. Ask for both where both can be had.
+import type { Expr } from './ast';
+
+/** the numeric address behind a deref base, through SCALAR pointer casts only */
+export const baseConst = (e: Expr): number | null =>
+  e.k === 'const'
+    ? e.value
+    : e.k === 'cast' && !(e.to.kind === 'ptr' && e.to.to.kind === 'struct')
+      ? baseConst(e.e)
+      : null;
+
+/** the numeric address an expression IS, through any number of pointer casts */
+export const addrConst = (e: Expr): number | null =>
+  e.k === 'const' ? e.value : e.k === 'cast' && e.to.kind === 'ptr' ? addrConst(e.e) : null;
+
+/** the constant an ACCESS CHAIN is rooted at, through any cast, subscript and field selection */
+export const rootConst = (e: Expr): number | null =>
+  e.k === 'const'
+    ? e.value
+    : e.k === 'cast'
+      ? rootConst(e.e)
+      : e.k === 'index' || e.k === 'field'
+        ? rootConst(e.base)
+        : null;
+
+/** The WHOLE address an `index` access denotes, or null when any part of it is not constant. A
+ *  `field` never resolves here: its offset is the struct's, which this module has no layout for. */
+export function cellAddress(e: Expr): number | null {
+  if (e.k !== 'index' || e.lead !== undefined || e.idx.k !== 'const') {
+    return null; // a `lead` is a multidimensional global's leading dimension, not a numeric address
+  }
+  const base = baseConst(e.base);
+  return base === null ? null : base + e.idx.value * e.width;
+}
+
+/** is `a` inside the half-open range `w`? A null address, or no declared range, is never inside. */
+export const inRange = (a: number | null, w?: readonly [number, number]): boolean =>
+  w !== undefined && a !== null && a >= w[0] && a < w[1];

package/src/l3/advance.ts

@@ -0,0 +1,373 @@
+// L3 respell variation: a pointer local the source ADVANCED between two accesses, rather than two
+// addresses the compiler derived from one.
+//
+// `ldr r3,=X; strh [r3]; adds r3,#2; strh [r3]` — the machine held an address in a register, used
+// it, moved it, used it again. `raise/const.ts` folds the lift's `add(const X, const 2)` into the
+// literal `X + 2`, because on Thumb that pair is also how a compiler materialises a 32-bit literal
+// it cannot encode in one instruction, and it records the distinction it is erasing as
+// `index.baseAdvanced` (l3/ast.ts's third evidence field). This pass reads it:
+//
+//     *(u16 *)0x04000048 = a;  *(u16 *)0x0400004A = b;
+//   → u16 *p = (u16 *)0x04000048;  *p = a;  p = p + 1;  *p = b;
+//
+// WHY IT IS A CANDIDATE. Against the INDEXED spelling of the same minted local the advance buys
+// nothing: agbcc folds `p = p + 1; *p` straight back into `strh [r3, #2]`, byte for byte the
+// subscript's own object. What makes it visible is the CONJUNCTION with a `volatile` pointee,
+// which bars that fold and leaves the `add` the target records. Both halves are compiled against
+// `kleod:StreamCmd_SetWindowRegs`'s target object; the four corners are in test/advance.test.ts's
+// header. So this pass emits a spelling and `compareScored` referees; nothing here claims the
+// source wrote it.
+//
+// SOUNDNESS IS ADDRESS EQUALITY. `p` is freshly minted and assigned by nothing else, so at each
+// member's access it holds `A0 + Σ steps so far` — that member's own absolute address — PROVIDED
+// every advance sits between the accesses it separates on every path, and PROVIDED every node this
+// pass re-spells as `*p` is one of those accesses. A top-level statement list has no back edge and
+// runs its statements in order at most once each, so placing each advance at the top level
+// immediately above its member's statement, with the members at STRICTLY INCREASING top-level
+// indices, carries the first half.
+//
+// THE SECOND HALF IS `rewrite`, AND IT MATCHES BY ADDRESS, NOT BY IDENTITY (`:rewrite` below): it
+// replaces EVERY `index` node whose `cellAddress` is a chain member's, wherever it sits. So a
+// second access at a member's address — a twin at the top level, or one inside an arm or a loop
+// body — is re-spelled `*p` at a point where `p` does not hold that address. The two rules that
+// refuse those shapes (`member-second-site`, `member-nested-site`, and their head twins) are
+// therefore SOUND, not narrowing, and the shape is pinned by test/advance.test.ts's `an access at
+// a chain address inside a loop is not re-spelled`.
+//
+// SCOPE (decline over approximate) is `ADVANCE_HEAD_GATES` and `ADVANCE_MEMBER_GATES` below — as
+// tables rather than an `||` chain, so `sound` costs a `guardedBy` and every rule is ablated
+// against the real pass by test/advance.test.ts's battery, which records WHAT THE ABLATED PASS
+// EMITS and checks `sound` against it. NOT by `bench gates`: `pnpm bench gates --pass advance`
+// answers `no censusable pass "advance"`, and structurally must, because this pass is reached
+// through a static import binding in rank.ts rather than through a mutable caller-side record
+// (run/gate-census.ts's header, which measures the `TypeError` a module-namespace write raises).
+// The firing census below was therefore taken by hand, with the recipe it states.
+//
+// FIVE OF THE TWELVE ARE NARROWING rather than soundness and each says which it is. Three are
+// judgements about what the asm shows (`head-already-advanced`, `member-negative-step`,
+// `member-no-evidence` — the last is what makes this a reading rather than a guess); one,
+// `member-signedness`, buys the minted local ONE pointee type where the backend would otherwise
+// spell a correct reinterpret cast; one, `member-element-grid`, is a LOUD refusal — ablated it
+// emits `p0 = p0 + 0.5;`, which is not C. Dropping `member-no-evidence` alone leaves the emitted
+// step `undefined / width` = `NaN`, refused downstream only by the two arithmetic rules'
+// comparisons against it (`NaN % w !== 0`, `NaN !== addr`); the battery's `noncompile` verdicts
+// for both are what hold that.
+//
+// HOW OFTEN EACH FIRES, over the whole corpus — `bench sweep --fan`, both arms, 2,126 records,
+// instrumented on `firstRejection` (2026-09-12), which is HAND INSTRUMENTATION and reproduced by
+// wrapping both tables in `tallying()` (l3/gates.ts) at this pass's one call site in rank.ts,
+// passing `.gates` to `advancedBases`, and printing `.refusals()` when the sweep ends. The numbers
+// count CALLS, and enumeration calls this pass about eleven times per record, once per structure setting's
+// tree:
+//     23,322 calls · 112 found a chain · 23,210 declined
+//     head-second-site 872 · member-no-evidence 664 · head-nested-site 256 · head-already-advanced 144
+//     every other member rule: 0
+// So the eight remaining member rules are pinned by the battery and by NOTHING IN THE CORPUS —
+// where the corpus refuses a chain, it refuses it at the head. Chain lengths found: 96 of two
+// members and 16 of four, no others.
+//
+// WHAT THIS PASS DOES NOT DO, both measured rather than assumed:
+//   • A function with TWO disjoint chains gets one candidate, spelling the FIRST BY POSITION — not
+//     the longest, and the second chain is unreachable by any variation. ZERO of the 112 chain-bearing
+//     calls above held a second chain sharing no address with the first (the instrument kept
+//     scanning), so the second local this would need has no inhabitant to price it.
+//   • The init is `prepend`ed and there is no sunk twin; see the note at `placeBaseLocals` below.
+//   • IT IS MAP-LESS ONLY. Every member is reached through `cellAddress`, which answers null once
+//     a symbol map promotes the pool word to `&REG_WININ` — so with a map this pass enumerates
+//     nothing, and every `/advance` candidate the corpus carries is a `/raw-globals` one. That is
+//     what caps the variation at the six rows `bench sweep --fan --base origin/main` names
+//     (apps/benchmark/dataset/synthetic.ts, at `volwalk`), and it is the question to ask of it the
+//     day the symbol-map direction lands: this capability survives only if `cellAddress` learns
+//     the promoted form.
+import { type IrType, scalarTypeForAccess } from '../ir/types';
+import { cellAddress } from './address';
+import { type Expr, type SFn, type Stmt, mapExprChildren, mapStmtExprs, stmtChildren, stmtExprs } from './ast';
+import { type Gate, firstRejection } from './gates';
+import type { BaseInit } from './hoist';
+import { nameAllocator, placeBaseLocals } from './hoist';
+
+/** One const-addressed access, with the top-level statement it was reached at. */
+export interface Site {
+  stmt: number;
+  addr: number;
+  width: number;
+  signed: boolean;
+  advanced?: number;
+}
+
+/** One candidate member, judged against the chain so far. `twin`/`nested` are the two ways some
+ *  OTHER node in the tree names this site's address — the facts `rewrite`'s by-address match makes
+ *  load-bearing. */
+export interface MemberCtx {
+  prev: Site;
+  site: Site;
+  twin: boolean;
+  nested: boolean;
+}
+export type HeadCtx = Omit<MemberCtx, 'prev'>;
+
+/** The head's own admission. The two address rules are the same PREDICATE as the member table's
+ *  and deliberately not the same rule objects (see gates.ts on why a second consumer owns its
+ *  own): a head that is re-spelled at a second site is wrong for the same reason a member is. */
+export const ADVANCE_HEAD_GATES: readonly Gate<HeadCtx>[] = [
+  {
+    id: 'head-second-site',
+    why: 'the rewrite finds accesses by address, so another access to the same address would read `p` before it is set',
+    sound: true,
+    guardedBy: 'advance.test.ts: a chain address reached at a second site declines',
+    rejects: (c) => c.twin,
+  },
+  {
+    id: 'head-nested-site',
+    why: 'the same address inside an arm or a loop body is re-spelled at a point `p` may not hold',
+    sound: true,
+    guardedBy: 'advance.test.ts: an access at a chain address inside a loop is not re-spelled',
+    rejects: (c) => c.nested,
+  },
+  {
+    id: 'head-already-advanced',
+    why: 'an access the machine reached by stepping from an earlier one continues that chain, and starting a chain there would load an address the machine never loaded',
+    sound: false,
+    guardedBy: 'advance.test.ts: a chain may not START at an advanced site',
+    rejects: (c) => c.site.advanced !== undefined,
+  },
+];
+
+/** Each successor, against the member before it. FIRST rejection wins, so a refusal is
+ *  attributable to one rule. */
+export const ADVANCE_MEMBER_GATES: readonly Gate<MemberCtx>[] = [
+  {
+    id: 'member-no-evidence',
+    why: 'where the lift recorded no step, the pair is the compiler deriving two addresses from one literal',
+    sound: false,
+    guardedBy: 'advance.test.ts: the same pair with no evidence declines',
+    rejects: (c) => c.site.advanced === undefined,
+  },
+  {
+    id: 'member-second-site',
+    why: 'the rewrite finds accesses by address, so another access to the same address would read `p` at the wrong value',
+    sound: true,
+    guardedBy: 'advance.test.ts: a chain address reached at a second site declines',
+    rejects: (c) => c.twin,
+  },
+  {
+    id: 'member-nested-site',
+    why: 'the same address inside an arm or a loop body is re-spelled at a point `p` may not hold',
+    sound: true,
+    guardedBy: 'advance.test.ts: an access at a chain address inside a loop is not re-spelled',
+    rejects: (c) => c.nested,
+  },
+  {
+    id: 'member-statement-order',
+    why: 'the advance must sit between the two accesses it separates, so the indices must increase',
+    sound: true,
+    guardedBy: 'advance.test.ts: two accesses in ONE statement are not a chain',
+    rejects: (c) => c.site.stmt <= c.prev.stmt,
+  },
+  {
+    id: 'member-width',
+    why: 'the new pointer has one pointee width, and `*p` at another width names other bytes',
+    sound: true,
+    guardedBy: 'advance.test.ts: members of different widths decline',
+    rejects: (c) => c.site.width !== c.prev.width,
+  },
+  {
+    id: 'member-signedness',
+    why: 'the new pointer has one pointee type, and a second access of another type would need a cast the source did not write',
+    sound: false,
+    guardedBy: 'advance.test.ts: members of different signedness decline',
+    rejects: (c) => c.site.signed !== c.prev.signed,
+  },
+  {
+    id: 'member-element-grid',
+    why: 'a step that is not a whole number of elements would be written `p = p + step / width` with a fraction, which is not C',
+    sound: false,
+    guardedBy: 'advance.test.ts: a step off the element grid declines',
+    rejects: (c) => c.site.advanced! % c.prev.width !== 0,
+  },
+  {
+    id: 'member-step-lands',
+    why: 'a step that does not land on this access is evidence about some other pair of addresses',
+    sound: true,
+    guardedBy: 'advance.test.ts: a step that does not land on the next access declines',
+    rejects: (c) => c.prev.addr + c.site.advanced! !== c.site.addr,
+  },
+  {
+    id: 'member-negative-step',
+    why: 'a backward step (`p = p + -1`) is correct C, but this variation writes only forward steps',
+    sound: false,
+    guardedBy: 'advance.test.ts: a NEGATIVE step declines',
+    rejects: (c) => c.site.advanced! <= 0,
+  },
+];
+
+/** Every const-addressed `index` node in the body, split into the ones reached EXACTLY ONCE per
+ *  execution of a top-level statement — the only places an advance statement can be put — and the
+ *  ADDRESSES of every other one, which the chain rule refuses outright.
+ *
+ *  A loop's OWN expression joins its body on the second side: a `while` condition runs once per
+ *  iteration, so an advance above the loop and an access in its test are not the same count. A
+ *  top-level `if`'s condition stays on the first side, because the `if` statement itself runs once
+ *  whatever its arms do. */
+function collectSites(body: readonly Stmt[]): { sites: Site[]; nestedAddrs: Set<number> } {
+  const sites: Site[] = [];
+  const nestedAddrs = new Set<number>();
+  const visit = (e: Expr, stmt: number, nested: boolean): void => {
+    if (e.k === 'index') {
+      const addr = cellAddress(e);
+      if (addr !== null) {
+        if (nested) {
+          nestedAddrs.add(addr);
+        } else {
+          sites.push({ stmt, addr, width: e.width, signed: e.signed, advanced: e.baseAdvanced });
+        }
+      }
+    }
+    mapExprChildren(e, (c) => {
+      visit(c, stmt, nested);
+      return c;
+    });
+  };
+  const walk = (stmts: readonly Stmt[], stmt: number, nested: boolean): void => {
+    for (const s of stmts) {
+      const repeats = s.k === 'while' || s.k === 'dowhile' || s.k === 'for';
+      for (const e of stmtExprs(s)) {
+        visit(e, stmt, nested || repeats);
+      }
+      walk(stmtChildren(s), stmt, true);
+    }
+  };
+  body.forEach((s, i) => walk([s], i, false));
+  return { sites, nestedAddrs };
+}
+
+/** The one chain this pass spells, or null.
+ *
+ *  A NON-MEMBER SITE BETWEEN TWO MEMBERS DOES NOT END THE CHAIN. `p` is freshly minted, so an
+ *  access that does not touch it cannot move it — and the clientele is MMIO setup code, where one
+ *  `REG_BLDCNT = y;` between two window writes is the ordinary case. So the head is chosen by the
+ *  head table rather than by position, and the walk scans every later site rather than stopping at
+ *  the first one a gate refuses. Ambiguity is resolved greedily in statement order: where two later
+ *  sites would both extend the chain, the earlier one does.
+ *
+ *  THE TOLERANCE HAS NO CORPUS INHABITANT. MMIO writes with an unrelated const-addressed access
+ *  between two members appear nowhere in the corpus, so this is a rule the file can state
+ *  truthfully rather than reach a sweep can show. */
+function chainOf(sites: readonly Site[], nestedAddrs: ReadonlySet<number>, gates: AdvanceGates): Site[] | null {
+  const head = gates.head ?? ADVANCE_HEAD_GATES;
+  const member = gates.member ?? ADVANCE_MEMBER_GATES;
+  const occurrences = new Map<number, number>();
+  for (const s of sites) {
+    occurrences.set(s.addr, (occurrences.get(s.addr) ?? 0) + 1);
+  }
+  const ctx = (site: Site): HeadCtx => ({
+    site,
+    twin: (occurrences.get(site.addr) ?? 0) > 1,
+    nested: nestedAddrs.has(site.addr),
+  });
+  for (let i = 0; i < sites.length; i++) {
+    if (firstRejection(head, ctx(sites[i])) !== null) {
+      continue;
+    }
+    const chain = [sites[i]];
+    for (let j = i + 1; j < sites.length; j++) {
+      if (firstRejection(member, { prev: chain[chain.length - 1], ...ctx(sites[j]) }) === null) {
+        chain.push(sites[j]);
+      }
+    }
+    if (chain.length >= 2) {
+      return chain;
+    }
+  }
+  return null;
+}
+
+/** The two tables, ablatable — `gates.ts`'s reason: a test drops one entry and re-runs the REAL
+ *  predicate on real input, with no test-only branch in the shipped path. Nothing in `src/` passes
+ *  this; a shipped ablation of a `sound: true` rule emits wrong addresses, which is what
+ *  `ablateHeuristic` refuses. */
+export interface AdvanceGates {
+  head?: readonly Gate<HeadCtx>[];
+  member?: readonly Gate<MemberCtx>[];
+}
+
+/** Re-spell one advanced chain as a pointer local moved in place, or decline (null). */
+export function advancedBases(sfn: SFn, gates: AdvanceGates = {}): SFn | null {
+  const { sites, nestedAddrs } = collectSites(sfn.body);
+  const chain = chainOf(sites, nestedAddrs, gates);
+  if (chain === null) {
+    return null;
+  }
+  const name = nameAllocator(sfn)();
+  const elem: IrType = scalarTypeForAccess(chain[0].width, chain[0].signed);
+  const ptr: IrType = { kind: 'ptr', to: elem };
+  const members = new Set(chain.map((m) => m.addr));
+  // The access itself: every chain member reads `*p`, because `p` has been advanced to exactly its
+  // address. The evidence fields go with the old base — they described how the ADDRESS was
+  // computed, and this spelling is the answer to that question rather than another instance of it.
+  //
+  // BY ADDRESS, NOT BY IDENTITY, and the header's soundness argument turns on it: a node this
+  // finds at a member's address that is NOT the member — a twin, or one inside an arm or a loop —
+  // is re-spelled too, which is why the gates that refuse those shapes are `sound: true`.
+  const rewrite = (e: Expr): Expr => {
+    const m = mapExprChildren(e, rewrite);
+    const addr = m.k === 'index' ? cellAddress(m) : null;
+    if (m.k === 'index' && addr !== null && members.has(addr)) {
+      return { k: 'index', base: { k: 'var', name }, idx: { k: 'const', value: 0 }, width: m.width, signed: m.signed };
+    }
+    return m;
+  };
+  // The emitted distance is the GATED quantity — the step `member-step-lands` tied to this pair of
+  // addresses and `member-element-grid` divided — rather than the address difference, which is the
+  // same number only because those two rules hold. Deriving it separately is how a later ablation
+  // of one of them emits a fractional advance nothing checked.
+  //
+  // WHICH MAKES THE ARITHMETIC HERE TOTAL ONLY BECAUSE OF THE TABLE, and both ways out are LOUD
+  // rather than silent — measured, and pinned by the battery's `noncompile` verdicts rather than
+  // guarded here: with `member-element-grid` dropped this emits `p0 = p0 + 0.5;`, and with
+  // `member-no-evidence` dropped `advanced` is `undefined` and this emits `p0 = p0 + NaN;`.
+  // Neither is C, so a candidate carrying one is dropped at compile with its message rather than
+  // scored — which is why the two rules are `sound: false` and why no `Number.isInteger` refusal
+  // stands here: adding one would turn those two ablations into a DECLINE and delete the evidence
+  // the battery reads. `member-no-evidence` is ablatable by `ablateHeuristic`, so a round that
+  // ships that ablation as a ranked candidate ships noncompiling sources; that is its price.
+  const advanceAt = new Map<number, number>();
+  for (let i = 1; i < chain.length; i++) {
+    advanceAt.set(chain[i].stmt, chain[i].advanced! / chain[i].width);
+  }
+  const body: Stmt[] = [];
+  sfn.body.forEach((s, i) => {
+    const step = advanceAt.get(i);
+    if (step !== undefined) {
+      body.push({
+        k: 'assign',
+        name,
+        value: { k: 'bin', op: '+', l: { k: 'var', name }, r: { k: 'const', value: step } },
+      });
+    }
+    body.push(mapStmtExprs(s, rewrite));
+  });
+  const init: BaseInit = {
+    k: 'assign',
+    name,
+    value: { k: 'cast', to: ptr, e: { k: 'const', value: chain[0].addr } },
+  };
+  const locals = [...sfn.locals, { name, type: ptr as SFn['locals'][number]['type'] }];
+  // `prepend` for `l3/nearbase.ts`'s reason and a second one this pass owns: the init MATERIALISES
+  // the register the chain advances, and the target's own instruction order is what says where the
+  // pool word was loaded. Putting it in first-use order instead moves it below whatever else the
+  // function loads first, which on `kleod:StreamCmd_SetWindowRegs` swaps the two pool words and
+  // costs the match; test/advance.test.ts's `the base init leads` pins the emitted order.
+  //
+  // AND NO `/advance/sinkinit` ALTERNATIVE, unlike `/nearbase`, which ships one for exactly this decision —
+  // not because the decision is better determined here (the generator cannot see the target either
+  // way) but because the twin CANNOT EXIST. `sinkInitsToFirstUse` sinks an init only when
+  // `localMentions` counts ONE assignment to its local ("or the move would cross the other write",
+  // l3/hoist.ts), and an advance IS a second assignment to this one — so the sink declines on every
+  // tree this pass produces, by construction rather than by row: the sink returns null on the
+  // advanced tree, and registering `/advance/sinkinit` adds no candidate to
+  // `kleod:StreamCmd_SetWindowRegs:agbcc`'s fan. The `prepend` decision above is therefore the only
+  // placement this variation HAS, which is a stronger reason to record the compile behind it.
+  const { body: placed } = placeBaseLocals({ ...sfn, locals, body }, [init], 'prepend');
+  return { ...sfn, locals, body: placed };
+}

package/src/l3/argbase.ts

@@ -1,4 +1,4 @@
-// L3 re-spelling lever: materialize the deref BASES of a call's arguments into locals, before the
+// L3 respell variation: 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
@@ -16,9 +16,9 @@
 // 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
+// A VARIATION, not a committed 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.
+// risk — a rewrite that replaced the default 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
@@ -29,7 +29,7 @@
 // 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
+// two features meet on exactly the MMIO shape this variation 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
@@ -41,6 +41,7 @@ import { type IrType, T, scalarTypeForAccess } from '../ir/types';
 import type { Expr, SFn, Stmt } from './ast';
 import { mapExprChildren, stmtExprs } from './ast';
 import { nameAllocator } from './hoist';
+import { declaredGlobals } from './storage';
 
 /** A base this pass may evaluate early: pure, and not something a store can change under us.
  *
@@ -103,7 +104,7 @@ function baseKey(n: Extract<Expr, { k: 'index' }>): string {
  * 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 globals = declaredGlobals(sfn);
   const fresh = nameAllocator(sfn);
   const newLocals: { name: string; type: IrType }[] = [];
   let fired = false;