@asmlift/core 0.4.0 → 0.6.0

package/src/l3/offmember.ts

@@ -0,0 +1,371 @@
+// L3 re-spelling: spell a leaf base's constant subscript as a struct MEMBER, so the offset stays
+// in the instruction's displacement instead of folding into the address the compiler materializes.
+//
+// THE COMPILER FACT this exists for is the one `l3/basecse.ts`'s header states in the imperative
+// and cannot act on: on a target that declares `compilerBehaviors.foldsConstAddrOffset`, a
+// constant SUBSCRIPT folds into the literal the address materializes, while an aggregate MEMBER
+// offset stays in the memory operand.
+//
+//   ((u16 *)0x3003468)[7]          →  .word 0x3003476  +  ldrh r0, [r0]
+//   ((struct S *)0x3003468)->m14   →  .word 0x3003468  +  ldrh r0, [r0, #0xe]
+//
+// Both denote the same cell. Which one the source wrote is not derivable from the C, but the ASM
+// says which one the compiler was given: an offset that reached the load's own displacement got
+// there because nothing folded it, and only a member (or a named base — that is `/basefold`'s
+// spelling) leaves it there. `l3/ast.ts`'s `index.operandOff` carries that displacement down from
+// the lift, because the fold at L3 (`idx = idxVal + off / width`, structure/structure.ts) makes
+// the two indistinguishable afterwards.
+//
+// THE ROSTER ALREADY OFFERS THE OTHER SOURCE OF THE SAME SHAPE. `/basefold` reads the identical
+// evidence and answers it with a NAMED BASE (`u16 *p = (u16 *)C; p[7]`), which also keeps the
+// displacement. The member is the second source and was in no fan; the two are different C and
+// different register pressure, so both ride and the differ referees.
+//
+// SCOPE — a LEAF base only (a bare `addr` or a bare `const`), which is `l3/basecse.ts`'s
+// `isHoistableBase` population. A computed base (`((u16 *)v0)[8]`) is out: the address is already
+// held somewhere, so nothing folded into a literal and the evidence says nothing — that shape is
+// `/addr-home`'s (structure/analysis.ts). It is a GATE rather than a collection filter so the
+// refusal is attributable: `firstRejection` names it.
+//
+// NO DEVICE-REGISTER REFUSAL, which is a priced decision and not an omission. A base inside the
+// target's declared `deviceRegisters` window is admitted like any other, so this pass will offer
+// `((struct Off0 *)&REG_DMA3SAD)->m8` — a struct declared over the register file, carrying no
+// qualifier. Three measurements say a refusal there buys nothing for that price.
+//
+//   REACH. Every device-window base reaching this table is already refused by `no-operand-off`
+//   (49 of them map-less, 2 map-ful, over all four checkouts — 1417 structured functions map-less,
+//   398 map-ful): the DMA idiom writes offset 0 as well as offset 8, and offset 0 leaves no
+//   displacement. A window refusal removes ZERO further bases in either configuration.
+//
+//   PREMISE. It would be refusing a dropped qualifier, and there is none to drop: `/volatile`
+//   wraps the base in a CAST that `non-leaf-base` refuses, so the two levers cannot compose and
+//   the tree this pass is handed is unqualified in both configurations. Nor is a tie-break lost —
+//   `deviceVolatileClaims` counts only qualifiers a tree already asserts, so an unqualified tree
+//   scores zero whichever way it is spelled.
+//
+//   CONFIGURATION. A numeric window is read through `addrConst`, and a symbol map turns a device
+//   address into a named `addr` no range can see. So such a refusal fires map-less and not
+//   map-ful on the SAME function — and the real tier runs map-ful. A refusal a symbol map
+//   switches off is not a refusal.
+//
+// What referees it instead is the differ, and `offmember.test.ts` pins the price on real compiled
+// asm: on a DMACNT spin that never touches DMASAD — the one shape `no-operand-off` does not cover
+// — the member spelling is offered and LOSES, 52 candidates, best
+// `unsigned/derived-home/livebase/volatile: 4` against `/offmember`'s 5. A row where it WINS over
+// MMIO is what would earn a gate here, together with a window reading that survives a symbol map.
+//
+// NOT AN EXTENSION OF raise/struct-arrays.ts. That pass mints an element struct off the `mul`/`shl`
+// STRIDE idiom in the machine code, and this shape has no scale at all — the subscript is a
+// constant and the base is a leaf, so there is no stride to read. It is a SPELLING of a tree
+// structuring already produced, which is what puts it in `l3/` beside the other re-spellings.
+//
+// SOUNDNESS. The member offset is `idx * width`, the access's own byte offset from the base — never
+// `operandOff`, which is EVIDENCE about where the offset travelled and is only part of it when the
+// address carried the rest. So the respelled node addresses the same cell by construction, and the
+// one way it could not is a layout C cannot reproduce — a member C would seat somewhere other than
+// where the asm read it. `unspellable-layout` refuses that, and it is the table's only sound gate.
+//
+// REFUSAL. `spellOperandMembers` returns `null` when no base was admitted, so a function with no
+// eligible site contributes no candidate and costs nothing.
+//
+// WHAT THE DECLARATION GOVERNS, and it is narrower than it looks: the CONSTANT SUBSCRIPTS this
+// pass grouped under one base expression, and nothing else. A sibling
+// access through the same address that this pass has no member spelling for — a variable
+// subscript, a `lead`-prefixed one — is left exactly as it was, keeping its own cast, and a
+// struct-array element off the same numeric constant reaches the address through a different base
+// expression and so a different key entirely. So one address really can leave here spelled two
+// ways, and `offmember.test.ts` emits exactly this pair rather than describing it:
+// `((struct Off0 *)50345232)->m16` beside `((s32 *)50345232)[a0]`.
+//
+// THAT IS UGLY AND IT IS NOT UNSOUND, and only the second half is a gate's business. Every
+// access carries its own cast, so no access reads a byte it did not read before; the seating check
+// below judges the accesses the declaration is built FROM, which are exactly the accesses
+// respelled through it, so its argument is over a total population of what it governs. The
+// contradiction is between two FICTIONAL TYPES over one address, which is a readability claim —
+// `quality`'s clientele, not a gate's.
+//
+// AND THE TIGHTER RULE IS PRICED, so it is not re-derived from scratch. Refusing a base whose
+// siblings this pass cannot spell removes `a:gCallbackQueue` from
+// `kleod:ProcessInputAndUpdateEntities` (asserted by dumping that row's winning source both ways:
+// 9 `struct Off*` declarations become 2, and the survivor is `gUnk_03004C20`) and COSTS that row
+// score, while protecting no row anywhere in the artifact. NO BRACKET IS QUOTED, and that is a
+// discipline rather than a gap: a bracket is a claim about the whole tree, so BOTH endpoints move
+// whenever anything else does. Read the unablated endpoint off the committed artifact — where
+// `kleod:ProcessInputAndUpdateEntities` scores 211 — and re-measure the ablated one before writing
+// a pair anywhere.
+// "PROTECTS NO ROW" IS A CENSUS AND NOT A SAMPLE, and the population is small because this is an
+// extra GATE: it only ever removes candidates, so only a row whose winner carries `/offmember` can
+// move at all. THAT POPULATION IS A QUERY, not a count to keep in step by hand — the rows of
+// `apps/benchmark/results/results.json` whose `asmlift.candidateLabel` contains `offmember` — and
+// it grows with the corpus, so re-run it before repeating the result. It held eight rows besides
+// `ProcessInputAndUpdateEntities` when the census ran, all unmoved with the rule on:
+// `synthetic:basecell`, `synthetic:bgfixed`, `synthetic:foldsink`, `sa3:sub_802DFC8` and
+// `sa3:sub_803213C` all still MATCH, `kleod:RollRandomLevelVariant` 18,
+// `kleod:CountCollectedGems` 290, `kleod:UpdateWorldMapNodeAnim` 157, each the artifact's own
+// number. A gate needs a row it protects. (One side effect worth recording: with the rule on, PI's
+// winner becomes `unsigned/setup-args/no-ptr-elem/offmember` — an arm that wins no REAL row wins
+// there. It is an ablation's artifact, not a reason to ship either.)
+//
+// ALL-OR-NOTHING PER FUNCTION, and that is a PRICE rather than a property. Every admitted base is
+// respelled together in one candidate, so a function with two admitted bases where the target
+// folded one and kept the other in the operand has no reachable spelling — the coverage hole
+// `l3/ptrfield.ts` measures for its fields. `l3/basecse.ts` is NOT a second witness to it but the
+// counterexample: its `UNFOLDED_GATES` cuts across `LIVEBASE_BLOCK_GATES` rather than refining it,
+// so a partial answer IS reachable there — a proper nonempty subset on 13 of the agbcc rows the
+// artifact carried when that census ran,
+// one of three bases on `synthetic:dmascope` — and that is the way out of this hole too: not a
+// per-base fork, but a SECOND PREDICATE separating the bases the differ has to choose between.
+// The per-base fork is 2^n and the family's standing price for forking ten refusal sites per site
+// was 1024x, so the arbitrary subsets stay unreachable until a row demands one.
+// Measured over klonoa's 69
+// lifting functions (lift → idioms → raise → structure, one pass per configuration): 36 admitted
+// bases over 25 functions map-less and 38 over 24 map-ful, so the multi-base functions really are
+// the majority of the surplus and a missing subset has somewhere to live. The other three
+// checkouts admit 32 bases over 32 functions (af), 10 over 10 (marioparty3) and 2 over 2
+// (snowboardkids2), all map-less.
+import { nextStructIndex } from '../ir/struct-names';
+import { type IrType, T, scalarTypeForAccess } from '../ir/types';
+import type { Expr, SFn, StructType } from './ast';
+import { mapExprChildren, mapStmtExprs, walkExprs } from './ast';
+import { type Gate, firstRejection } from './gates';
+
+/** One observed constant-subscript access through a base. */
+interface Site {
+  /** the member's byte offset from the base — `idx * width`, the address the node denotes */
+  off: number;
+  width: number;
+  signed: boolean;
+  /** the displacement the instruction carried, when it carried one (l3/ast.ts `operandOff`) */
+  operandOff?: number;
+}
+
+/** The identity of an access's base, for grouping. Leaf bases key by value; everything else keys
+ *  by its printed shape, so a non-leaf base still reaches the table and is refused by NAME. */
+const baseKey = (e: Expr): string =>
+  e.k === 'addr' ? `a:${e.name}` : e.k === 'const' ? `c:${e.value}` : `x:${JSON.stringify(e)}`;
+
+/** What the gates judge: one base and every constant-subscript access through it. */
+export interface OffmemberBase {
+  key: string;
+  /** the base is a bare `addr`/`const` — the population whose address the compiler materializes */
+  leafBase: boolean;
+  /** some access through this base carries no memory-operand displacement, so nothing says its
+   *  offset was ever anywhere but the address */
+  missingOperandOff: boolean;
+  /** some access's subscript is WIDER than the displacement the instruction carried — the address
+   *  expression held the rest, and how that split maps back onto one member is not measured */
+  indexCarriesMore: boolean;
+  /** the accesses cannot be declared as a plain C struct seating each at its own offset */
+  unspellableLayout: boolean;
+}
+
+export const OFFMEMBER_GATES: readonly Gate<OffmemberBase>[] = [
+  {
+    id: 'non-leaf-base',
+    why: 'a computed base is already held somewhere, so nothing folded into a literal',
+    // A REACH argument, which is why it claims no soundness and owes no guard — and it is the
+    // only thing standing between this pass and a dropped qualifier, which the header's
+    // no-device-refusal paragraph is the other half of. A `/volatile` base reaches L3 as a CAST
+    // over the constant, so this gate excludes it as a side effect of excluding every computed
+    // base, and the natural widening ("a cast of a leaf const is still a leaf") would respell a
+    // qualified access as an unqualified member with no test failing. Nothing downstream would
+    // object. So the widening is forbidden HERE, at this gate, and a round that wants it owes a
+    // qualifier-preserving spelling first.
+    sound: false,
+    rejects: (c) => !c.leafBase,
+  },
+  {
+    id: 'no-operand-off',
+    why: 'an offset that never reached the instruction is not evidence of a member',
+    sound: false,
+    rejects: (c) => c.missingOperandOff,
+  },
+  {
+    id: 'index-carries-more',
+    why: 'the address carried part of the offset, and that decomposition is unmeasured',
+    sound: false,
+    rejects: (c) => c.indexCarriesMore,
+  },
+  {
+    id: 'unspellable-layout',
+    why: 'a struct C cannot seat at the observed offsets would address different bytes',
+    sound: true,
+    guardedBy: 'offmember.test.ts: a base whose accesses no plain struct can seat is refused',
+    rejects: (c) => c.unspellableLayout,
+  },
+];
+
+/** The members this base is spelled through: one field per distinct offset. Shared by the seating
+ *  PREDICATE and the layout BUILDER so the two cannot judge one field set and declare another —
+ *  and, since `seatable` now refuses an offset whose views disagree on width OR signedness, every
+ *  surviving offset has exactly one view and the pick below is an identity on an admitted base.
+ *  It is kept because this runs on ABLATED tables too, where the gate is gone and something still
+ *  has to choose; preferring the signed view keeps that choice the widest one. */
+function membersOf(sites: readonly Site[]): Site[] {
+  const byOff = new Map<number, Site>();
+  for (const s of sites) {
+    const prev = byOff.get(s.off);
+    if (!prev || (s.signed && !prev.signed)) {
+      byOff.set(s.off, s);
+    }
+  }
+  return [...byOff.values()].sort((a, b) => a.off - b.off);
+}
+
+/** Can plain C seat every member at the offset the asm read it at, AND does the member read the
+ *  same value the access did?
+ *
+ *  FOUR ways it cannot, and the first three are the same defect — a field the declaration would
+ *  place somewhere other than where the access reads: a NEGATIVE offset, which no member has; two
+ *  views of ONE offset at different widths (a union); and two offsets whose byte ranges collide.
+ *
+ *  THE FOURTH IS NOT ABOUT PLACEMENT, and it is the easy one to leave out: two views of one
+ *  offset at one width but
+ *  DIFFERENT SIGNEDNESS (`ldrb` and `ldrsb` at the same address). One member has one type, so
+ *  respelling both through it changes what one of the two READS — `scalarTypeForAccess` honours
+ *  signedness at widths 1 and 2, so an unsigned read becomes sign-extending. That is a value
+ *  change rather than a spelling change, and the differ can referee it only by luck: a masked or
+ *  compared result compiles to the same bytes while the published C says something the asm does
+ *  not. C spells it as a union, which is not a member, so it is refused exactly as the width union
+ *  is. `l3/basecse.ts` keys `(base, width, signedness)` for the same reason, and `l3/typing.ts`
+ *  states the rule in the imperative: signedness counts wherever the access extends.
+ *
+ *  Natural ALIGNMENT is not among them, and that is an invariant rather than an omission: a
+ *  member's offset here is the node's own `idx * width`, so it is a multiple of its width by
+ *  construction and C's own alignment can always place it. A clause for it would have no
+ *  inhabitant.
+ *
+ *  This is what `unspellable-layout` asks, and the gate is the ONLY refusal — `layoutFor` below
+ *  builds whatever it is handed, so ablating the gate really does emit the mislaid struct rather
+ *  than quietly declining beside it. */
+function seatable(sites: readonly Site[]): boolean {
+  let cursor = 0;
+  const views = new Map<number, Site>();
+  for (const s of sites) {
+    const v = views.get(s.off);
+    if (v !== undefined && (v.width !== s.width || v.signed !== s.signed)) {
+      return false;
+    }
+    views.set(s.off, s);
+  }
+  for (const m of membersOf(sites)) {
+    if (m.off < cursor) {
+      return false;
+    }
+    cursor = m.off + m.width;
+  }
+  return true;
+}
+
+/** The struct declaration for a base: each member at its own offset, gaps filled with an explicit
+ *  `u8[N]` pad so the declaration reproduces the observed offsets on its own — the discipline
+ *  raise/structs.ts and raise/struct-arrays.ts share. No trailing pad and no `size`: the spelling
+ *  is `->m`, so `sizeof` is never taken. */
+function layoutFor(name: string, sites: readonly Site[]): StructType {
+  const fields: StructType['fields'] = [];
+  let cursor = 0;
+  let pad = 0;
+  for (const m of membersOf(sites)) {
+    if (cursor < m.off) {
+      fields.push({ off: cursor, type: T.array(T.u(8), m.off - cursor), name: `_pad${pad++}` });
+    }
+    fields.push({ off: m.off, type: scalarTypeForAccess(m.width, m.signed), name: `m${m.off}` });
+    cursor = m.off + m.width;
+  }
+  return { name, fields };
+}
+
+/** Every CONSTANT-SUBSCRIPT `index` access, grouped by base, in first-appearance order — the
+ *  accesses this pass has a member spelling for, which are exactly the ones the declaration it
+ *  builds will govern. A sibling with a variable subscript or a `lead` is not one of them and is
+ *  not counted: it keeps its own cast and this pass never rewrites it (see the header's
+ *  "WHAT THE DECLARATION GOVERNS"). */
+function collect(sfn: SFn): { order: string[]; sites: Map<string, Site[]> } {
+  const order: string[] = [];
+  const sites = new Map<string, Site[]>();
+  for (const e of walkExprs(sfn.body)) {
+    if (e.k !== 'index' || e.idx.k !== 'const' || e.lead !== undefined) {
+      continue;
+    }
+    const k = baseKey(e.base);
+    let list = sites.get(k);
+    if (!list) {
+      order.push(k);
+      list = [];
+      sites.set(k, list);
+    }
+    list.push({ off: e.idx.value * e.width, width: e.width, signed: e.signed, operandOff: e.operandOff });
+  }
+  return { order, sites };
+}
+
+/** The keys `gates` admits, with the struct each one is spelled through. */
+function admit(
+  sfn: SFn,
+  gates: readonly Gate<OffmemberBase>[],
+  firstName: number,
+): Map<string, { struct: StructType; type: IrType }> {
+  const { order, sites } = collect(sfn);
+  const out = new Map<string, { struct: StructType; type: IrType }>();
+  let n = firstName;
+  for (const key of order) {
+    const list = sites.get(key)!;
+    const rejected = firstRejection(gates, {
+      key,
+      leafBase: key.startsWith('a:') || key.startsWith('c:'),
+      missingOperandOff: list.some((s) => s.operandOff === undefined),
+      indexCarriesMore: list.some((s) => s.operandOff !== undefined && s.operandOff !== s.off),
+      unspellableLayout: !seatable(list),
+    });
+    if (rejected === null) {
+      const struct = layoutFor(`Off${n}`, list);
+      out.set(key, { struct, type: T.ptr(T.struct(struct.name, struct.fields)) });
+      n++;
+    }
+  }
+  return out;
+}
+
+/** The gate table an ablation swaps out. Optional, so a caller gets the shipped table by default.
+ *  The pass needs nothing else from the target: the fold this exists for is `foldsConstAddrOffset`
+ *  and rank.ts asks that before offering the axis at all. */
+export interface OffmemberOpts {
+  readonly gates?: readonly Gate<OffmemberBase>[];
+}
+
+/** The census without the rewrite, for a caller comparing what two tables would admit. */
+export function offmemberBases(sfn: SFn, opts: OffmemberOpts = {}): readonly string[] {
+  return [...admit(sfn, opts.gates ?? OFFMEMBER_GATES, 0).keys()];
+}
+
+/** Re-spell every admitted base's constant subscripts as members of a synthesized struct.
+ *  `null` when nothing is admitted — the axis then contributes no candidate. */
+export function spellOperandMembers(sfn: SFn, opts: OffmemberOpts = {}): SFn | null {
+  // Past EVERY `Off<N>` the tree already carries, never the first free one (`ir/struct-names.ts`,
+  // shared with the other two minters, which also records that this scan returns 0 on every
+  // corpus function). The prefix is what keeps this pass clear of raise/structs.ts's `Struct<N>`
+  // and raise/struct-arrays.ts's `Elem<N>`; the monotone scan is what keeps it clear of itself.
+  const seed = nextStructIndex(
+    (sfn.structs ?? []).map((s) => s.name),
+    'Off',
+  );
+  const admitted = admit(sfn, opts.gates ?? OFFMEMBER_GATES, seed);
+  if (admitted.size === 0) {
+    return null;
+  }
+  const rewrite = (e: Expr): Expr => {
+    if (e.k === 'index' && e.idx.k === 'const' && e.lead === undefined) {
+      const hit = admitted.get(baseKey(e.base));
+      if (hit) {
+        return { k: 'field', base: { k: 'cast', to: hit.type, e: e.base }, name: `m${e.idx.value * e.width}` };
+      }
+    }
+    return mapExprChildren(e, rewrite);
+  };
+  const structs = [...(sfn.structs ?? []), ...[...admitted.values()].map((a) => a.struct)].sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+  // `mapStmtExprs` recurses into nested statement lists, so one call per top-level statement
+  // covers the whole body.
+  return { ...sfn, structs, body: sfn.body.map((st) => mapStmtExprs(st, rewrite)) };
+}

package/src/l3/parkfirst.ts

@@ -0,0 +1,96 @@
+// L3 re-spelling lever: park incoming ARGUMENTS first in the entry straight-line prefix.
+//
+// A copy of an incoming parameter into a local (`v = a1`) reproduces the register park the
+// compiler performed to free a caller-save register (`mov ip, r1`). The park instruction lifts
+// to pure SSA aliasing — no op, no position — so the emitted order falls out of block emission
+// (materialized statements first, edge copies last), while the compiler may have parked BEFORE
+// any of those statements ran (hipress homes its counter in ip before loading a byte into the
+// vacated r1). Both orders are legitimate C for the same asm; this lever emits the park-first
+// sibling and the differ referees.
+//
+// SCOPE (decline over approximate): only plain assigns in the ENTRY straight-line prefix (the
+// leading run of assigns) move; a park's RHS must be pure over PARAMETERS AND CONSTANTS through
+// scalar nodes only (var/const/un/bin/cast — a memory read or a call would be re-scheduled, not
+// re-spelled), so a constant initializer qualifies as a park and a param leaf is NOT required —
+// what this lever moves is the leading run's ORDER, and a constant is as free of position as a
+// parked register is; and a park never crosses a statement that writes a name it reads, reads or
+// writes its destination (`&v` counts as touching v), or carries an effect. Relative order — of the
+// parks and of everything else — is preserved. Declines (null) when nothing moves.
+//
+// WHAT THE DESTINATION TEST IS, stated because it is narrower than "a local": the target is checked
+// against the PARAMS alone, so every other name an `assign` can carry qualifies — and structure.ts
+// spells a store to a bare scalar GLOBAL as an `assign` like any other, so such a store parks too.
+// The crossing checks are NAME-KEYED, so a crossed statement that reaches the destination (or a
+// name the park reads) through an ALIAS rather than by name is invisible to them — the same
+// name-keyed model every lever at this level defers aliasing to.
+//
+// The kmc hipress residual is this axis's OTHER projection — its keep-load renders first while
+// gcc2.7.2 schedules it last — so a second inhabitant consolidates both into one entry-prefix
+// ordering lever rather than growing a sibling.
+import type { Expr, SFn, Stmt } from './ast';
+import { exprChildren, exprHasEffect } from './ast';
+
+type Assign = Extract<Stmt, { k: 'assign' }>;
+
+// `addr` counts as touching its name: `foo(&v)` may read or write v through the pointer, so a
+// park must treat it exactly like a direct read-and-write of v.
+const readVars = (e: Expr, acc: Set<string> = new Set()): Set<string> => {
+  if (e.k === 'var' || e.k === 'addr') {
+    acc.add(e.name);
+  }
+  for (const c of exprChildren(e)) {
+    readVars(c, acc);
+  }
+  return acc;
+};
+
+const pureOverParams = (e: Expr, params: ReadonlySet<string>): boolean => {
+  switch (e.k) {
+    case 'var':
+      return params.has(e.name);
+    case 'const':
+      return true;
+    case 'un':
+    case 'cast':
+      return pureOverParams(e.e, params);
+    case 'bin':
+      return pureOverParams(e.l, params) && pureOverParams(e.r, params);
+    default:
+      return false;
+  }
+};
+
+export function parkParamsFirst(sfn: SFn): SFn | null {
+  const params = new Set(sfn.params.map((p) => p.name));
+  let n = 0;
+  while (n < sfn.body.length && sfn.body[n].k === 'assign') {
+    n++;
+  }
+  const prefix = sfn.body.slice(0, n) as Assign[];
+  const parks: Assign[] = [];
+  const rest: Assign[] = [];
+  for (const st of prefix) {
+    // `rest` is exactly what this park would cross — a REFUSED earlier park is in it, so a later
+    // park is re-checked against it like any other crossed statement.
+    if (!params.has(st.name) && pureOverParams(st.value, params)) {
+      const reads = readVars(st.value);
+      if (
+        rest.every(
+          (c) =>
+            !exprHasEffect(c.value) && // a call can write anything an escaped address reaches
+            !reads.has(c.name) &&
+            c.name !== st.name &&
+            !readVars(c.value).has(st.name),
+        )
+      ) {
+        parks.push(st);
+        continue;
+      }
+    }
+    rest.push(st);
+  }
+  if (parks.length === 0 || parks.every((p, i) => prefix[i] === p)) {
+    return null; // nothing to move, or the parks already lead the prefix
+  }
+  return { ...sfn, body: [...parks, ...rest, ...sfn.body.slice(n)] };
+}

package/src/l3/pollguard.ts

@@ -0,0 +1,154 @@
+// L3 poll-shape re-spelling levers: `pollGuards` regrows an empty bottom-tested loop's guard;
+// `pollReads` folds a materialized poll's re-read back into its while condition. Each carries
+// its own trace argument below.
+//
+//     do { } while (dma[2] & 0x80000000);   →   if (dma[2] & 0x80000000) { do { } while (…); }
+//
+// For an empty body the two forms compile to the SAME instructions — gcc collapses the guard
+// into the bottom test late (jump optimization), AFTER flow has counted the guard's reads — so
+// the choice leaves no instruction trace, only a register-allocation ripple: the extra
+// source-level read raises the condition operands' ref counts, which re-orders the allocator's
+// priorities for the WHOLE function (the busy-wait's base landing in a low reg vs `ip`). Which
+// form the source spelled is unrecoverable from the bytes; both are emitted and the differ
+// referees.
+//
+// SCOPE (decline over approximate): only a `dowhile` with an EMPTY body regrows a guard —
+// there the two forms have IDENTICAL evaluation traces (each evaluates the condition until its
+// first falsy result; the regrown guard IS the first bottom-test, not an extra one), so
+// volatile reads, calls, any effect in the condition all count the same. A NON-empty body is
+// where the forms genuinely differ (the body runs at least once vs at least zero times), which
+// is why it never wraps. Declines (null) when no empty do-while exists.
+import type { Expr, SFn, Stmt } from './ast';
+import { exprChildren, exprEquals, mapExprChildren, mapStmtLists, stmtChildren, stmtExprs } from './ast';
+
+export function pollGuards(sfn: SFn): SFn | null {
+  let changed = false;
+  const rewrite = (s: Stmt): Stmt => {
+    if (s.k === 'dowhile' && s.body.length === 0) {
+      changed = true;
+      return { k: 'if', cond: s.cond, then: [s], else: [] };
+    }
+    return mapStmtLists(s, (list) => list.map(rewrite));
+  };
+  const body = sfn.body.map(rewrite);
+  return changed ? { ...sfn, body } : null;
+}
+
+// L3 re-spelling lever: a materialized POLL re-reads in its own condition.
+//
+//     v = dma[2]; while ((v & BUSY) != 0) { v = dma[2]; }   →   while ((dma[2] & BUSY) != 0) {}
+//
+// The structurer materializes a loop-carried load into a named temp with a pre-loop read and a
+// per-iteration re-read; the source may have spelled the read INSIDE the condition of an
+// empty-bodied `while`. The two forms have IDENTICAL evaluation traces — the old form reads once
+// before plus once per iteration, the new form reads once per condition evaluation, and both
+// count 1 + iterations — so volatile reads COUNT the same; the condition gates below (call-free,
+// no volatile-rooted or raw derefs) are what make the ORDER identical too: with no other
+// observable effect in the condition, there is nothing for the embedded read to reorder against.
+// What differs is bytes: the pre-read + temp spelling materializes an extra register and
+// instruction the in-condition spelling does not.
+//
+// SCOPE (decline over approximate): each admission is one named predicate below and carries its own
+// refusal's reason; the temp must additionally be the function's OWN non-volatile LOCAL, because a
+// bare global's assigns are stores other code observes and its declaration cannot be dropped.
+// Declines (null) when no poll matches.
+const countVar = (e: Expr, n: string): number =>
+  (e.k === 'var' && e.name === n ? 1 : 0) + exprChildren(e).reduce((a, c) => a + countVar(c, n), 0);
+
+const countAddr = (e: Expr, n: string): number =>
+  (e.k === 'addr' && e.name === n ? 1 : 0) + exprChildren(e).reduce((a, c) => a + countAddr(c, n), 0);
+
+/** call- and marker-free: no effect the fold could move or duplicate. */
+const pure = (e: Expr): boolean => e.k !== 'call' && e.k !== 'marker' && exprChildren(e).every(pure);
+
+/** The var a deref's base stands on, through casts only — null for anything else (a raw address, an
+ *  arithmetic base), which is exactly the set `condDerefsPlain` refuses. */
+const rootVar = (e: Expr): string | null => (e.k === 'var' ? e.name : e.k === 'cast' ? rootVar(e.e) : null);
+
+/** ORDER-safety for the condition's other reads: a deref there must be rooted at a var declared
+ *  non-volatile — a volatile-rooted or raw-address deref is (or may be) an OBSERVABLE read the
+ *  fold would unsequence against X inside one expression, where the original sequenced them. */
+const condDerefsPlain = (e: Expr, volatileLocals: ReadonlySet<string>): boolean => {
+  if (e.k === 'index' || e.k === 'field') {
+    const rv = rootVar(e.base);
+    if (rv === null || volatileLocals.has(rv)) {
+      return false;
+    }
+  }
+  return exprChildren(e).every((c) => condDerefsPlain(c, volatileLocals));
+};
+
+/** Every mention of `n` in a statement list — reads, `&n`, and assign targets, at any depth. */
+const occurs = (list: Stmt[], n: string): number =>
+  list.reduce(
+    (a, st) =>
+      a +
+      stmtExprs(st).reduce((x, e) => x + countVar(e, n) + countAddr(e, n), 0) +
+      (st.k === 'assign' && st.name === n ? 1 : 0) +
+      occurs(stmtChildren(st), n),
+    0,
+  );
+
+/** The loop body must be EXACTLY the one re-read: a single assign of the same variable to the same
+ *  expression. Any other statement there is one the fold would delete along with the loop's body. */
+const bodyIsTheSoleReread = (w: Extract<Stmt, { k: 'while' }>, a: Extract<Stmt, { k: 'assign' }>): boolean =>
+  w.body.length === 1 && w.body[0].k === 'assign' && w.body[0].name === a.name && exprEquals(w.body[0].value, a.value);
+
+/** The condition must read the variable EXACTLY once, as a bare var: a second read would double X's
+ *  per-iteration evaluation, and an `&v` is not a read at all and cannot be substituted. */
+const condReadsVarOnce = (cond: Expr, n: string): boolean => countVar(cond, n) === 1 && countAddr(cond, n) === 0;
+
+/** X must not mention the variable it is assigned to — the folded form evaluates X in a condition
+ *  where that variable no longer exists. */
+const valueIsSelfFree = (value: Expr, n: string): boolean => countVar(value, n) === 0 && countAddr(value, n) === 0;
+
+/** The condition carries no effect and no observable read of its own, which is what makes the
+ *  embedded X unsequenceable against anything: call/marker-free, every deref `condDerefsPlain`. */
+const condFoldable = (cond: Expr, volatileLocals: ReadonlySet<string>): boolean =>
+  pure(cond) && condDerefsPlain(cond, volatileLocals);
+
+/** The pattern owns EVERY occurrence of the variable: both assign targets and the one condition
+ *  read, three in all, counted over the whole function and counting `&v`. Its declaration is dropped
+ *  with the temp, so anything else mentioning it would be left naming a variable that is gone. */
+const ownsEveryOccurrence = (body: Stmt[], n: string): boolean => occurs(body, n) === 3;
+
+export function pollReads(sfn: SFn): SFn | null {
+  const ownPlain = new Set(
+    sfn.locals.filter((l) => l.volatile !== true && l.pointeeVolatile !== true).map((l) => l.name),
+  );
+  const volatileLocals = new Set(
+    sfn.locals.filter((l) => l.volatile === true || l.pointeeVolatile === true).map((l) => l.name),
+  );
+  const subst = (e: Expr, n: string, x: Expr): Expr =>
+    e.k === 'var' && e.name === n ? x : mapExprChildren(e, (c) => subst(c, n, x));
+  const dropped = new Set<string>();
+  const rewriteList = (list: Stmt[]): Stmt[] => {
+    const out: Stmt[] = [];
+    for (let i = 0; i < list.length; i++) {
+      const a = list[i];
+      const w = list[i + 1];
+      if (
+        a.k === 'assign' &&
+        ownPlain.has(a.name) &&
+        w !== undefined &&
+        w.k === 'while' &&
+        bodyIsTheSoleReread(w, a) &&
+        condReadsVarOnce(w.cond, a.name) &&
+        valueIsSelfFree(a.value, a.name) &&
+        pure(a.value) &&
+        condFoldable(w.cond, volatileLocals) &&
+        ownsEveryOccurrence(sfn.body, a.name)
+      ) {
+        out.push({ k: 'while', cond: subst(w.cond, a.name, a.value), body: [] });
+        dropped.add(a.name);
+        i++;
+        continue;
+      }
+      out.push(recurse(a));
+    }
+    return out;
+  };
+  const recurse = (s0: Stmt): Stmt => mapStmtLists(s0, rewriteList);
+  const body = rewriteList(sfn.body);
+  return dropped.size > 0 ? { ...sfn, body, locals: sfn.locals.filter((l) => !dropped.has(l.name)) } : null;
+}