@asmlift/core 0.6.0 → 0.8.0

package/src/ir/core.ts

@@ -53,8 +53,55 @@ export interface Fn {
    *  so at its own definition), and a fact the structurer reads but the score probe's clone drops
    *  makes that probe's delta a fact about a program asmlift does not emit. */
   slotHomes: SlotHomes | undefined;
+  /** L1 SIDE DATA (see {@link ParamEvidence}); set by the SSA builder, `undefined` on parsed IR.
+   *  REQUIRED-but-possibly-undefined for exactly the reason `writeOrder` and `slotHomes` are. */
+  paramEvidence: ParamEvidence | undefined;
 }
 
+/** What the machine's own object shows about each ENTRY PARAMETER, beyond the value graph — two
+ *  observations the lift destroys, recorded so raise/paramwidth.ts can read them. Every entry
+ *  parameter of a lifted function has an entry; a `Fn` with no map is one nobody measured.
+ *
+ *  BOTH ARE OBSERVATIONS, NOT VERDICTS. What a compiler's object shows for a narrow DECLARED
+ *  parameter is a fact about a TARGET, and this builder holds none; `target.ts`
+ *  `compilerBehaviors.narrowParamWitness` decides what the pair means, and the disassemblies for
+ *  each value live there.
+ *
+ *  `deadHome` — THE STORE DOES NOT REACH THE IR. Both slot-modelling frontends spell a word
+ *  sp-relative store as a write to the SSA key `sp@k` instead of a `store` op (`stackSlotKey`), so
+ *  a slot nothing reloads has no reader, no op and no value: it simply is not there by L1. A
+ *  parameter stored to two slots, one of them reloaded, still counts — the dead store happened —
+ *  and the reader's own gates decide what a parameter with that much traffic may become.
+ *
+ *  It asks NO FRAME PARTITION, and that is the difference from {@link SlotHomes}. A slot home is a
+ *  DECLARATION RANK, so `sp@40` had to be classified as this function's local before it could be
+ *  stamped, and MIPS declares no partition and so stamps none. "Stored here and never read back"
+ *  needs no such classification: it is a statement about the store, true at any offset.
+ *
+ *  `selfRedefined` — THE REGISTER IDENTITY DOES NOT REACH THE IR EITHER. SSA renames, so nothing
+ *  downstream can tell a value the machine put back in the argument's OWN register from one it put
+ *  in a scratch. This records the first: the first write to the parameter's register, in the entry
+ *  block, is a value that parameter itself feeds. First and not any — a later write is a reuse of a
+ *  register the parameter is done with.
+ *
+ *  ENTRY PARAMETERS ONLY, for both. A dead spill of an ordinary value is a dead spill, and an
+ *  ordinary register's self-update is arithmetic; it is the incoming ARGUMENT that carries a
+ *  declaration.
+ *
+ *  AND SO NEITHER FOLLOWS `replaceAllUsesWith`, where a {@link SlotHomes} entry does. A frame
+ *  coordinate belongs to whichever value the structurer will name, so it travels with the uses;
+ *  these are facts about the ARGUMENT REGISTER the machine was handed, and no other value can come
+ *  to have been that argument. The score probe's clone re-keys the map (`cli/src/report.ts`)
+ *  because a clone mints new `Value` objects for the same parameters; nothing else moves it. */
+export interface ParamObservation {
+  /** the machine stored this parameter to a stack slot no load reads back (the ABI argument home) */
+  deadHome: boolean;
+  /** the first entry-block write to this parameter's own register is a value the parameter feeds */
+  selfRedefined: boolean;
+}
+
+export type ParamEvidence = ReadonlyMap<Value, ParamObservation>;
+
 /** Which `[sp,#k]` the machine homed a value at — the frame coordinate, carried L1 → L3.
  *
  *  The coordinate exists only in the frontends: they record a word sp-relative slot's value in SSA
@@ -69,9 +116,10 @@ export interface Fn {
  *
  *  DECLARES, NOT OWNS, AND THE DIFFERENCE IS AN AGBCC FACT WITH A LIVE DEPENDENCY: `ownedLocals`,
  *  the partition a def-less READ asks, admits agbcc's outgoing stack-argument area, and an offset
- *  there is an ABI position rather than an `expand_decl` rank. Under Thumb the two ranges are
- *  written equal, and a decline rather than a proof is what makes that safe — see `declaredLocals`
- *  (frontend/ssa.ts) for the dependency and what lifting it obliges.
+ *  there is an ABI position rather than an `expand_decl` rank. Under Thumb the declared range
+ *  therefore starts above that area, where the largest outgoing argument block the frontend could
+ *  LICENSE ends — see `declaredLocals` (frontend/ssa.ts) for what the licence proves and for the
+ *  frames it refuses outright.
  *
  *  ONE consumer reads it for its content — the structurer, which turns it into
  *  `SFn.locals[i].slots`; everything else only carries it (`replaceAllUsesWith`, the report's
@@ -117,6 +165,14 @@ export type SlotHomes = Map<Value, Set<number>>;
  *  param have no common scale. LAST write, not first: a predecessor commonly writes one key several
  *  times (1,867 of 5,283 records over three checkouts), and the edge carries what the last left.
  *
+ *  A SECOND CONSUMER READS THE ABSENCE, not the order. `structure.ts`'s `enclosingCarrierName` takes
+ *  a missing `lastWrite` entry on a measured block as the licence to give a nested loop's parameter
+ *  the enclosing header's NAME: the key was not written, so the machine carried the value into the
+ *  inner loop in the register it had — one variable, not a copy. There a stale or over-eager "not
+ *  written" is not a mis-sorted copy but a copy the emitted C no longer makes, so the absence
+ *  semantics below are load-bearing for naming, and a pass that drops a record it should have
+ *  folded changes spellings, not just orders.
+ *
  *  Keyed by OBJECTS (the predecessor block, the destination param), never by arg position, so the
  *  param splices in `ir/simplify.ts` cannot leave it stale. A pass that moves one block's ops into
  *  another owes `foldWriteOrder`.
@@ -186,6 +242,17 @@ export function terminator(b: Block): Op | undefined {
   return b.ops[b.ops.length - 1];
 }
 
+/** The layout fall-through stamp alone (`opcodes.ts` declares it on `br` and on `ret`). A pass that
+ *  moves a `ret` ONTO an edge takes the edge's own stamp with it and nothing else: the rest of a
+ *  terminator's attrs describe the branch, not the arrival.
+ *
+ *  A GUARD rather than a fix — `fallthrough` is the only attr anything sets on a `br`, so copying
+ *  the whole bag would behave identically — spelled so that the next attr a frontend invents cannot
+ *  ride onto an edge it says nothing about. */
+export function fallThroughOf(term: Op): Op['attrs'] {
+  return term.attrs.fallthrough === true ? { fallthrough: true } : {};
+}
+
 /** The successor blocks of `b`, read off its terminator. */
 export function successorsOf(b: Block): Block[] {
   return terminator(b)?.successors.map((s) => s.block) ?? [];

package/src/ir/opcodes.ts

@@ -177,7 +177,16 @@ export const OPCODES = {
   // no more reapable than a dead `call`.
   opaque: { operands: 'variadic', results: 1, effects: true },
   // --- terminators ---
+  // `fallthrough: true` — OPTIONAL, the same fact as on `br`: a `ret` SUNK onto one edge
+  // (`raise/retsink.ts`, `raise/tailsink.ts`) replaces that edge's `br` and takes its stamp, so
+  // `structure/retspell.ts` can still read how the machine arrived. A `ret` a frontend built carries
+  // nothing, and is read by its block's in-edges instead.
   ret: { operands: 'variadic', results: 0, terminator: true, successors: 0 },
+  // `fallthrough: true` — OPTIONAL, set by a frontend when the block carried NO control-transfer
+  // instruction and this `br` stands for the machine simply running into the next block. Its
+  // absence therefore means a real branch instruction. The one reader is `structure/retspell.ts`,
+  // which needs to tell a `b <label>` (a transfer the source asked for) from layout; a pass that
+  // builds a fresh `br` leaves it off and is read as a branch, which is the conservative answer.
   br: { operands: 0, results: 0, terminator: true, successors: 1 },
   cond_br: { operands: 1, results: 0, terminator: true, successors: 2 },
   // Many-way switch dispatch (Regime B, jump table). The single operand is the scrutinee;
@@ -237,11 +246,11 @@ export const NEGATED_ICMP: Readonly<Record<string, Opcode>> = Object.fromEntries
 /** Ops with an observable side effect: the flag on the signature, derived rather than re-listed.
  *  `isDceSafe` asks the same question of the FLAG through `opSig` rather than of this set, so the
  *  two cannot disagree. The SET's own consumers are `HOIST_UNSAFE_OPS` below, structure.ts's
- *  `sideEffects` walk (an effectful op whose result nobody reads is still an execution),
+ *  block-purity tests (may this block be folded into a loop header, is this exit owned),
  *  analysis.ts's memory-write barrier, divpow2's bias block (which is DELETED rather than moved),
- *  and the idiom layer's de-sequencing guard (pattern/engine.ts). Three of them —  the
- *  `sideEffects` walk, the barrier and the bias block — each carried a hand-written copy of this
- *  membership, which is how the models drifted apart before. */
+ *  and the idiom layer's de-sequencing guard (pattern/engine.ts). Derived rather than re-listed
+ *  because three of those consumers each carried a hand-written copy of this membership, which is
+ *  how the models drifted apart. */
 export const EFFECTFUL_OPS: ReadonlySet<string> = new Set(
   (Object.keys(OPCODES) as Opcode[]).filter((k) => (OPCODES[k] as OpSig).effects),
 );
@@ -254,8 +263,9 @@ export const EFFECTFUL_OPS: ReadonlySet<string> = new Set(
  *  is raise/shortcircuit.ts, which hoists an arm's body into the block above, and the structurer
  *  inlines an unnamed value back into the `&&`/`||` right-hand side, where C's own short-circuit
  *  re-guards it. Adding the two reads
- *  here costs three byte-matches (kleod:UpdateHUDCounterDisplay, synthetic:breakloop,
- *  synthetic:strcmp1), so the argument is load-bearing rather than merely plausible.
+ *  here cost three byte-matches (kleod:UpdateHUDCounterDisplay, retired 2026-09-13 with its source,
+ *  plus synthetic:breakloop and synthetic:strcmp1), so the argument was load-bearing rather than
+ *  merely plausible. Not re-measured since the kleod row's retirement.
  *
  *  KNOWN GAP: the trapping divides are absent too, and there the re-guard argument does NOT carry
  *  — a hoisted `sdiv` that the structurer NAMES becomes an unconditional statement. Left as it is
@@ -271,9 +281,20 @@ export const EFFECTFUL_OPS: ReadonlySet<string> = new Set(
  *  re-guard at the new point — actually holds at your call site. */
 export const HOIST_UNSAFE_OPS: ReadonlySet<string> = EFFECTFUL_OPS;
 
+/** The ops whose `operands[0]` is a memory-access BASE: `load base`, `store base, value`,
+ *  `aload base, index`, `astore base, index, value` (the operand roles are in the registry above).
+ *  Authored rather than derived — no registry field records the operand ROLE, and the only other
+ *  memory-touching opcode is `call`, whose variadic operands are arguments and not a base.
+ *
+ *  Two consumers ask two different questions of it and both need the same answer, which is why it
+ *  is here and not next to either: `structure/analysis.ts` uses it for the address-home variation's slot
+ *  model, and `raise/const.ts` to recognise a folded literal that IS an address. */
+export const MEM_BASE_OPS: ReadonlySet<string> = new Set(['load', 'store', 'aload', 'astore']);
+
 /** Ops whose answer depends on WHERE they run: an effect (its order against other effects is
  *  observable) or a memory read (it answers whichever stores ran before it). The question a pass
- *  asks before moving a computation to another point on the SAME path. */
+ *  asks before moving a computation to another point on the SAME path. `SPELLED_WHEN_DEAD_OPS`
+ *  below asks a DIFFERENT question and derives, today, the same set. */
 export const ORDER_SENSITIVE_OPS: ReadonlySet<string> = new Set(
   (Object.keys(OPCODES) as Opcode[]).filter((k) => {
     const sig = OPCODES[k] as OpSig;
@@ -281,6 +302,30 @@ export const ORDER_SENSITIVE_OPS: ReadonlySet<string> = new Set(
   }),
 );
 
+/** Ops the structurer must still SPELL when nothing consumes their result — an effect, or a memory
+ *  READ. Consumer: structure.ts's `sideEffects` walk.
+ *
+ *  The read half is the entry worth arguing, because `reads` documents the OPPOSITE about C — a
+ *  load nobody reads is deletable, nothing observes it. That is the C claim. The COMPILER claim
+ *  points the other way: an optimizing compiler deletes every dead read it is ALLOWED to delete, so
+ *  one still in the target is evidence the source's access was `volatile`. Membership here only
+ *  says the structurer may not drop the op silently; whether a `volatile` can actually reach the
+ *  access is a second, ADDRESS-level question the call site asks separately
+ *  (structure.ts `volatileQualifiable`), and a read it answers no to is dropped as before.
+ *
+ *  DERIVED FROM THE REGISTRY, not aliased to `ORDER_SENSITIVE_OPS`, even though the two are
+ *  extensionally identical today and `HOIST_UNSAFE_OPS` above does alias `EFFECTFUL_OPS`. An alias
+ *  makes two DIFFERENT questions incapable of ever differing, so the day one of them acquires an
+ *  opcode the other should not have, the edit lands on both silently. The identity is pinned by a
+ *  test instead (test/pattern.test.ts), where a future divergence surfaces as a decision to make
+ *  rather than a coupling nobody sees. */
+export const SPELLED_WHEN_DEAD_OPS: ReadonlySet<string> = new Set(
+  (Object.keys(OPCODES) as Opcode[]).filter((k) => {
+    const sig = OPCODES[k] as OpSig;
+    return sig.effects || sig.reads;
+  }),
+);
+
 /** Ops that may not be RE-EVALUATED at another program point — order-sensitive, or trapping. The
  *  trap half is what separates this from `ORDER_SENSITIVE_OPS`: it only matters when the new point
  *  can be reached on a path the old one was not, so a consumer that merely re-orders on one path

package/src/ir/parse.ts

@@ -121,7 +121,13 @@ export function parse(text: string): Fn {
 
   // No write order: the text form is the value graph, and the record is a measurement of the
   // MACHINE. A parsed fn's edges are UNMEASURED, never written-nowhere (ir/core.ts `WriteOrder`).
-  return { name, blocks: rawBlocks.map((r) => r.block), writeOrder: undefined, slotHomes: undefined };
+  return {
+    name,
+    blocks: rawBlocks.map((r) => r.block),
+    writeOrder: undefined,
+    slotHomes: undefined,
+    paramEvidence: undefined,
+  };
 }
 
 /** Drop the two annotations `print(fn, { writeOrder: true })` appends, and NOTHING else.

package/src/ir/simplify.ts

@@ -105,7 +105,7 @@ function trivialPhiValue(incoming: readonly Successor[], i: number, param: Value
 export function firstTrivialPhi(fn: Fn): { block: Block; param: Value } | null {
   // ONE pass over the successor edges, indexed by target — `simplifyTrivialPhis` rescans the
   // whole function per block, which is fine for a mutating fixpoint and not for a check on the
-  // raising tower's hot path (a candidate fan re-raises the same function once per lift variant).
+  // raising tower's hot path (a candidate fan re-raises the same function once per lift).
   const incomingOf = new Map<Block, Successor[]>();
   for (const pb of fn.blocks) {
     for (const op of pb.ops) {

package/src/l3/address.ts

@@ -7,8 +7,8 @@
 // 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 lever that re-spells THROUGH it collapses the
-//     stride (`((struct S *)K)[i].f` is not `((u8 *)K)[…]`). This is the reading a lever that
+//     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.

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, isLoop, 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 = isLoop(s);
+      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 };
+}