@asmlift/core 0.3.0 → 0.5.0

package/src/l3/basecse.ts

@@ -21,11 +21,16 @@
 import { type IrType, T, scalarTypeForAccess } from '../ir/types';
 import type { Expr, SFn, Stmt } from './ast';
 import { mapExprChildren, stmtChildren, stmtExprs } from './ast';
+import { type Gate, firstRejection } from './gates';
+import { nameAllocator } from './hoist';
 
 // A HOISTABLE base is a bare `addr` (a global address) or a bare `const` (a numeric pointer
 // address). Both are relocation-invariant leaves whose value the compiler keeps in one register
 // when it indexes them at 2+ sites. Anything else (a local var, a struct-element `p[a0]`, arbitrary
-// arithmetic) is NOT — agbcc may re-derive it.
+// arithmetic) is NOT — agbcc may re-derive it. Admitting the bare `var` that scopebase.ts and
+// argbase.ts take is the obvious consolidation and it is wrong twice over: this pass has no `lead`
+// handling, so a rank-aware `g[0][i]` comes out as `p[0][i]` through a scalar pointer, and it
+// undoes raise/gvn.ts's hoist on exactly the rows a symbol map serves (test/addr-placement.test.ts).
 type HoistableBase = Extract<Expr, { k: 'addr' } | { k: 'const' }>;
 const isHoistableBase = (e: Expr): e is HoistableBase => e.k === 'addr' || e.k === 'const';
 const baseId = (b: HoistableBase): string => (b.k === 'addr' ? `a:${b.name}` : `c:${b.value}`);
@@ -39,12 +44,11 @@ interface Collected {
   meta: Map<string, { base: HoistableBase; width: number; signed: boolean }>;
   /** keys with ANY use inside a loop — disqualified (see the loop note in `hoistReusedGlobalBases`). */
   inLoop: Set<string>;
-  /** per key, how many times each CONSTANT offset was accessed. A constant offset touched 2+ times
-   *  is a SCALAR access at one fixed location (a `*(T*)C |= x` MMIO read-modify-write, or repeated
-   *  `*p`), which the compiler re-materializes rather than register-holds — hoisting it MISMATCHES
-   *  (it broke the ProcessHBlankWait match). A key with ANY repeated constant offset is therefore
-   *  disqualified, even if it ALSO has distinct-offset uses (a mixed scalar+array base). A genuine
-   *  reused array base touches each constant offset once, or uses a variable index (not tallied). */
+  /** per key, how many times each CONSTANT offset was accessed — the input to the
+   *  `repeated-const-offset` gate, which losing the ProcessHBlankWait match is what bought. A
+   *  genuine reused array base touches each constant offset once, or indexes by a variable (not
+   *  tallied); a repeat means a scalar re-access, and ONE is enough to disqualify the base even
+   *  when it also has distinct-offset uses. */
   constOffCount: Map<string, Map<number, number>>;
 }
 
@@ -135,45 +139,62 @@ function rewriteStmt(s: Stmt, localFor: Map<string, string>): Stmt {
   }
 }
 
-/** A name not already used by a param/local/global in `sfn`, of the form `p<n>`. */
-function freshName(taken: Set<string>): string {
-  let n = 0;
-  while (taken.has(`p${n}`)) {
-    n++;
-  }
-  const nm = `p${n}`;
-  taken.add(nm);
-  return nm;
+/** One base under consideration, keyed as `(base, width, signedness)`. */
+export interface BaseKey {
+  key: string;
+  uses: number;
+  inLoop: boolean;
+  /** some CONSTANT offset through this base is touched 2+ times */
+  repeatedConstOffset: boolean;
 }
 
+/** The admission rules. NONE is sound, and that is a property of the pass rather than an oversight:
+ *  a wrong hoist emits the same address held in a different place, so it costs bytes and a match,
+ *  never meaning. The zero-lost benchmark gate is what referees them.
+ *
+ *  The `loop` rule is the subtle one. A loop-body base is loop-invariant, so the compiler keeps it
+ *  in a register across the loop too — but hoisting to the FUNCTION TOP forces a callee-saved
+ *  register, which can add the prologue push/pop the original avoided. `l3/scopebase.ts` is the
+ *  scope-aware hoist that serves those instead. */
+export const BASECSE_GATES: readonly Gate<BaseKey>[] = [
+  {
+    id: 'single-use',
+    why: 'one access re-materializes as cheaply as a named local',
+    sound: false,
+    rejects: (c) => c.uses < 2,
+  },
+  {
+    id: 'loop',
+    why: 'a function-top hoist of a loop base forces a callee-saved register the original avoided',
+    sound: false,
+    rejects: (c) => c.inLoop,
+  },
+  {
+    id: 'repeated-const-offset',
+    why: 'a fixed offset touched twice is a scalar RMW, which the compiler re-materializes',
+    sound: false,
+    rejects: (c) => c.repeatedConstOffset,
+  },
+];
+
 export function hoistReusedGlobalBases(sfn: SFn): SFn {
   const c: Collected = { count: new Map(), order: [], meta: new Map(), inLoop: new Set(), constOffCount: new Map() };
   collect(sfn.body, c, false);
-  // A repeated CONSTANT offset means a scalar re-access at a fixed location (MMIO RMW / repeated
-  // `*p`) the compiler re-materializes — disqualify the whole base, even mixed with array uses.
-  const hasRepeatedConstOffset = (k: string): boolean => {
-    for (const n of c.constOffCount.get(k)?.values() ?? []) {
-      if (n >= 2) {
-        return true;
-      }
-    }
-    return false;
-  };
-
-  // Reuse 2+ and NOT used inside a loop. A loop-body base is loop-invariant, so the compiler ALSO
-  // keeps it in a register across the loop — but hoisting it to the function top forces a
-  // callee-saved register that can add prologue push/pop the original avoided, worsening the match
-  // (register-pressure matching, not a correctness issue). Straight-line / branch reuse is the safe
-  // win; a loop-body base is left inline for a future scope-aware hoist.
   const { count, order, meta } = c;
-  const hoisted = order.filter((k) => (count.get(k) ?? 0) >= 2 && !c.inLoop.has(k) && !hasRepeatedConstOffset(k));
+  const hoisted = order.filter(
+    (k) =>
+      firstRejection(BASECSE_GATES, {
+        key: k,
+        uses: count.get(k) ?? 0,
+        inLoop: c.inLoop.has(k),
+        repeatedConstOffset: [...(c.constOffCount.get(k)?.values() ?? [])].some((n) => n >= 2),
+      }) === null,
+  );
   if (hoisted.length === 0) {
     return sfn;
   }
 
-  const taken = new Set<string>([...sfn.params.map((p) => p.name), ...sfn.locals.map((l) => l.name)]);
-  // globals are referenced by name; a hoist name must not shadow one that appears in the body.
-  collectNames(sfn.body, taken);
+  const fresh = nameAllocator(sfn);
 
   const localFor = new Map<string, string>();
   const newLocals: { name: string; type: IrType }[] = [];
@@ -181,7 +202,7 @@ export function hoistReusedGlobalBases(sfn: SFn): SFn {
   for (const k of hoisted) {
     const m = meta.get(k)!;
     const ptrType = T.ptr(scalarTypeForAccess(m.width, m.signed));
-    const nm = freshName(taken);
+    const nm = fresh();
     localFor.set(k, nm);
     newLocals.push({ name: nm, type: ptrType });
     // `p = (T *)base` — the cast makes the local the access's pointer type so each `p[i]` strides it.
@@ -191,28 +212,3 @@ export function hoistReusedGlobalBases(sfn: SFn): SFn {
   const body = [...hoistStmts, ...sfn.body.map((s) => rewriteStmt(s, localFor))];
   return { ...sfn, body, locals: [...sfn.locals, ...newLocals] };
 }
-
-/** Every `var`/`addr`/called-function name mentioned anywhere in `stmts` (so a hoist name collides
- *  with none — a global via `addr`, a local via `var`, OR a callee via `call.fn`). */
-function collectNames(stmts: Stmt[], out: Set<string>): void {
-  const walk = (e: Expr): void => {
-    if (e.k === 'var' || e.k === 'addr') {
-      out.add(e.name);
-    }
-    if (e.k === 'call') {
-      out.add(e.fn); // a hoist local must not shadow a called function symbol
-    }
-    for (const c of exprChildrenOf(e)) {
-      walk(c);
-    }
-  };
-  for (const s of stmts) {
-    if (s.k === 'assign') {
-      out.add(s.name);
-    }
-    for (const e of stmtExprs(s)) {
-      walk(e);
-    }
-    collectNames(stmtChildren(s), out);
-  }
-}

package/src/l3/coalesce.ts

@@ -0,0 +1,215 @@
+import { typeToString } from '../ir/types';
+import type { Expr, SFn, Stmt } from './ast';
+import { exprChildren, mapExprChildren, stmtChildren, stmtExprs } from './ast';
+import { type Gate, firstRejection } from './gates';
+
+function namesIn(e: Expr, out: Set<string>): void {
+  // `addr` names a GLOBAL, never a local — collected anyway. A name reaching BOTH forms would
+  // otherwise get a span that ignores its `addr` mentions, and a SHORT span is a clobber while a
+  // long one is only a missed merge. `structure.ts` keeps locals to /^[vt]\d+$/ and excludes global
+  // names, so this cannot fire today; collecting is the direction that stays safe if that changes.
+  if (e.k === 'var' || e.k === 'addr') out.add(e.name);
+  for (const c of exprChildren(e)) namesIn(c, out);
+}
+
+/** Does `e` mention `n` anywhere? */
+function mentions(e: Expr, n: string): boolean {
+  const seen = new Set<string>();
+  namesIn(e, seen);
+  return seen.has(n);
+}
+export interface Span {
+  first: number;
+  last: number;
+  inLoop: boolean;
+  constFed: boolean;
+  /** the local's FIRST mention is a write, not a read */
+  firstIsWrite: boolean;
+}
+function spans(body: Stmt[]): Map<string, Span> {
+  const out = new Map<string, Span>();
+  let at = 0;
+  const walk = (list: Stmt[], inLoop: boolean): void => {
+    for (const s of list) {
+      at++;
+      const here = new Set<string>();
+      if (s.k === 'assign') here.add(s.name);
+      for (const e of stmtExprs(s)) namesIn(e, here);
+      for (const n of here) {
+        const sp = out.get(n) ?? {
+          first: at,
+          last: at,
+          inLoop,
+          constFed: true,
+          // an assign that ALSO READS the name (`b = g(b)`) is not a pure write; treating it as one
+          // let `g` receive the absorbed value
+          firstIsWrite: s.k === 'assign' && s.name === n && !stmtExprs(s).some((e) => mentions(e, n)),
+        };
+        sp.last = at;
+        sp.inLoop ||= inLoop;
+        if (s.k === 'assign' && s.name === n && s.value.k !== 'const') sp.constFed = false;
+        out.set(n, sp);
+      }
+      walk(stmtChildren(s), inLoop || s.k === 'while' || s.k === 'dowhile' || s.k === 'for');
+    }
+  };
+  walk(body, false);
+  return out;
+}
+function rename(body: Stmt[], from: string, to: string): Stmt[] {
+  const inExpr = (e: Expr): Expr =>
+    e.k === 'var' && e.name === from ? { ...e, name: to } : mapExprChildren(e, inExpr);
+  const inStmt = (s: Stmt): Stmt => {
+    const r = { ...s } as Record<string, unknown>;
+    if (s.k === 'assign' && s.name === from) r.name = to;
+    for (const key of ['value', 'lval', 'cond', 'scrutinee'] as const) {
+      const v = (s as Record<string, unknown>)[key];
+      if (v !== undefined) r[key] = inExpr(v as Expr);
+    }
+    for (const key of ['then', 'else', 'body', 'default'] as const) {
+      const v = (s as Record<string, unknown>)[key];
+      if (Array.isArray(v)) r[key] = (v as Stmt[]).map(inStmt);
+    }
+    if (s.k === 'for') {
+      r.init = inStmt(s.init);
+      r.inc = inStmt(s.inc);
+    }
+    if (s.k === 'switch') r.cases = s.cases.map((c) => ({ ...c, body: c.body.map(inStmt) }));
+    return r as Stmt;
+  };
+  return body.map(inStmt);
+}
+/** One candidate merge under consideration: absorb `a` into `b`. */
+export interface MergePair {
+  a: string;
+  b: string;
+  /** `a`'s span */
+  x: Span;
+  /** `b`'s span — the SURVIVOR's, which is why the asymmetric gates read `y` */
+  y: Span;
+  sameType: boolean;
+  eitherIsParam: boolean;
+}
+
+/** The admission rules, in evaluation order. Two arguments the `why` fields have no room for:
+ *
+ *  WHAT `loop` BUYS is the right to read preorder statement order as liveness. Preorder is a
+ *  topological order of the CFG except where a later-indexed statement can run before an earlier
+ *  one, and every position that does that — a `for`'s `init`/`inc`, any loop body — is inside a
+ *  loop. A loop's own CONDITION is not covered: it is visited at the loop statement's own index with
+ *  the ENCLOSING flag, which is safe only because a condition cannot WRITE.
+ *
+ *  ABLATE `first-is-write` ALONE AND NOTHING HAPPENS — `const-fed` masks it, so a survivor first
+ *  mentioned by a read was uninitialized there in the original too. Drop both to see what it does,
+ *  which is to bound the accepted class below by an order of magnitude. `const-fed` likewise bounds
+ *  candidate growth: merges go as `L(L-1)/2` in the local count, each a distinct compile. */
+export const COALESCE_GATES: readonly Gate<MergePair>[] = [
+  {
+    id: 'param',
+    why: 'a param is the function’s own signature, not a recovered local',
+    sound: false,
+    rejects: (c) => c.eitherIsParam,
+  },
+  {
+    id: 'type',
+    why: 'the survivor keeps its own declared type, so the two must agree',
+    sound: false,
+    rejects: (c) => !c.sameType,
+  },
+  {
+    id: 'loop',
+    why: 'a back edge can run a later statement first, so preorder stops implying disjoint liveness',
+    sound: true,
+    guardedBy: 'coalesce-fuzz.test.ts: dropping it clobbers a defined read',
+    rejects: (c) => c.x.inLoop || c.y.inLoop,
+  },
+  {
+    id: 'const-fed',
+    why: 'a load-fed local is one the compiler had a reason to keep where it was',
+    sound: false,
+    rejects: (c) => !c.x.constFed || !c.y.constFed,
+  },
+  {
+    id: 'overlap',
+    why: 'the ranges must not overlap — the survivor would absorb a value still live',
+    sound: true,
+    guardedBy: 'coalesce.test.ts: OVERLAPPING ranges never merge',
+    rejects: (c) => c.x.last >= c.y.first,
+  },
+  {
+    id: 'first-is-write',
+    why: 'a survivor first MENTIONED by a read would see the absorbed value there',
+    sound: false,
+    rejects: (c) => !c.y.firstIsWrite,
+  },
+];
+
+/** Every legal single merge, each as its own tree — NOT one committed choice.
+ *
+ *  Which pair a register allocator coalesced is not derivable from the L3 tree, and first-fit gets
+ *  it wrong. Run kleod:UpdateHUDCounterDisplay's published repro script (results.json carries it)
+ *  and read the candidate table: of its two legal merges, one scores WORSE than not merging at all
+ *  and declaration order is the one that picks it. Emitting no merges at all costs that row its
+ *  match, which is what guards this file. `rank.ts` already has the idiom for exactly this —
+ *  `/regcopy`'s "the tail choice is allocator-ambiguous, so both are ranked" — so every candidate is
+ *  emitted and the differ referees.
+ *
+ *  ACCEPTED, NOT FIXED: a survivor assigned only on SOME paths still absorbs the other's value on
+ *  the paths that skip it. The original read an uninitialized local there, so both spellings are
+ *  ill-defined rather than one being wrong — but this is a real difference and the differ, not any
+ *  gate, is what keeps it from faking a match. The fuzz asserts it stays reachable, so the carve-out
+ *  that excuses it cannot quietly become dead. */
+export function coalesceCandidates(sfn: SFn): { merged: string; sfn: SFn }[] {
+  return coalesceUnder(COALESCE_GATES, sfn).candidates;
+}
+
+/** `coalesceCandidates` with the gate table supplied, plus which gate refused each pair.
+ *
+ *  The parameter exists so a test can run the pass with one gate DROPPED — the ablation as a value,
+ *  rather than as a flag compiled into the shipped path or an input rewritten to dodge a predicate.
+ *  `refusals` is what makes a gate's reachability checkable: a rule nothing ever reaches is a rule
+ *  no test can be failing on purpose. */
+export function coalesceUnder(
+  gates: readonly Gate<MergePair>[],
+  sfn: SFn,
+): { candidates: { merged: string; sfn: SFn }[]; refusals: Map<string, number> } {
+  const refusals = new Map<string, number>();
+  if (sfn.locals.length < 2) {
+    return { candidates: [], refusals };
+  }
+  const params = new Set(sfn.params.map((p) => p.name));
+  const typeOf = new Map(sfn.locals.map((l) => [l.name, typeToString(l.type)]));
+  const sp = spans(sfn.body);
+  const candidates: { merged: string; sfn: SFn }[] = [];
+  for (const a of sfn.locals.map((l) => l.name)) {
+    for (const b of sfn.locals.map((l) => l.name)) {
+      const x = sp.get(a);
+      const y = sp.get(b);
+      // Not a gate: this is what makes the pair a pair at all. A name with no span is one the body
+      // never mentions, so there is no range to reason about.
+      if (a === b || !x || !y) {
+        continue;
+      }
+      const refused = firstRejection(gates, {
+        a,
+        b,
+        x,
+        y,
+        sameType: typeOf.get(a) === typeOf.get(b),
+        eitherIsParam: params.has(a) || params.has(b),
+      });
+      if (refused !== null) {
+        refusals.set(refused, (refusals.get(refused) ?? 0) + 1);
+        continue;
+      }
+      // Labelled by the PAIR, not by an index into enumeration order: an index silently re-points
+      // at a different merge if `sfn.locals` ordering ever changes, leaving a recorded provenance
+      // that is wrong but plausible.
+      candidates.push({
+        merged: `${a}-${b}`,
+        sfn: { ...sfn, body: rename(sfn.body, a, b), locals: sfn.locals.filter((l) => l.name !== a) },
+      });
+    }
+  }
+  return { candidates, refusals };
+}

package/src/l3/dce.ts

@@ -15,19 +15,23 @@
 // read as live throughout), so a removal only happens when the local is provably dead. Only
 // names in `locals` are eligible — globals (side effects, referenced by name from headers) and
 // params are never touched — and a value carrying a side effect / gap signal / memory load is
-// never dropped (see `mustKeep`). Locals are never address-taken in L3 (`addr` names a global),
-// so `var` reads are a COMPLETE account of a local's uses.
+// never dropped (see `mustKeep`). An `addr` node can now name a LOCAL as well as a global (the
+// frame-local object a Thumb `laddr` declares — structure.ts), and an address-taken local's stores
+// are observable through the escaped pointer whether or not any `var` read follows — so an `addr`
+// name counts as a READ below, which pins the local and every store to it. For globals that is a
+// no-op (they were never eligible), so the single rule covers both.
 //
 // Ordering: structureChecked runs `assertResolved` BEFORE this pass, so in strict mode an
 // unresolved `?` value trips the contract first and never reaches DCE; `mustKeep` treating `?` as
 // keep is defense-in-depth for any future caller that skips that check.
 import type { Expr, SFn, Stmt } from './ast';
-import { exprChildren, stmtChildren, stmtExprs } from './ast';
+import { exprChildren, negateCond, stmtChildren, stmtExprs } from './ast';
 
 /** Accumulate every LOCAL-eligible `var` name read anywhere in `e` (recurses all sub-exprs). An
- *  `addr` node names a global, not a local, so it is not a local read. */
+ *  `addr` name counts too: taking a local's address makes every store to it observable through the
+ *  escaped pointer, so an address-taken local is never dead here. */
 function readsInto(e: Expr, out: Set<string>): void {
-  if (e.k === 'var') {
+  if (e.k === 'var' || e.k === 'addr') {
     out.add(e.name);
   }
   for (const c of exprChildren(e)) {
@@ -48,15 +52,17 @@ function reads(e: Expr): Set<string> {
  *     value asmlift could NOT lift slip past `assertResolved`, silently downgrading a loud gap;
  *   - a memory load (`index`/`field`) — asmlift models no `volatile`, so a possibly-effectful read
  *     is never deleted (this pass never removes a memory access).
+ *   - a read of a VOLATILE local (the frame object whose address escaped) — a volatile read is an
+ *     observable access the machine performed; deleting the dead assignment would delete the read.
  *  A dead assignment whose value contains any of these is kept. */
-function mustKeep(e: Expr): boolean {
+function mustKeep(e: Expr, volatiles: ReadonlySet<string> = new Set()): boolean {
   if (e.k === 'call' || e.k === 'marker' || e.k === 'index' || e.k === 'field') {
     return true;
   }
-  if (e.k === 'var' && e.name === '?') {
+  if (e.k === 'var' && (e.name === '?' || volatiles.has(e.name))) {
     return true;
   }
-  return exprChildren(e).some(mustKeep);
+  return exprChildren(e).some((c) => mustKeep(c, volatiles));
 }
 
 /** Every local read anywhere within these statements (exprs + nested statements). Used to give
@@ -70,33 +76,13 @@ function allReadsInto(stmts: Stmt[], out: Set<string>): void {
   }
 }
 
-/** Negate a condition, flipping a relational operator directly (`!= → ==`, `< → >=`, …) so an
- *  empty-then flip reads cleanly; anything else wraps in `!( … )`. Both forms are semantically
- *  exact over C's total integer order. */
-function negate(cond: Expr): Expr {
-  if (cond.k === 'bin') {
-    const table: Record<string, '==' | '!=' | '<' | '<=' | '>' | '>='> = {
-      '==': '!=',
-      '!=': '==',
-      '<': '>=',
-      '>=': '<',
-      '>': '<=',
-      '<=': '>',
-    };
-    const f = table[cond.op];
-    if (f) {
-      return { k: 'bin', op: f, l: cond.l, r: cond.r };
-    }
-  }
-  return { k: 'un', op: '!', e: cond };
-}
-
 /** Backward live-variable walk over one block. `liveOut` is the set of locals live on exit;
  *  returns the rewritten block and the set live on entry. */
 function dceBlock(
   stmts: Stmt[],
   liveOut: ReadonlySet<string>,
   locals: ReadonlySet<string>,
+  volatiles: ReadonlySet<string> = new Set(),
 ): { out: Stmt[]; liveIn: Set<string> } {
   const live = new Set(liveOut);
   const rev: Stmt[] = [];
@@ -110,7 +96,7 @@ function dceBlock(
     const s = stmts[i];
     switch (s.k) {
       case 'assign': {
-        if (locals.has(s.name) && !live.has(s.name) && !mustKeep(s.value)) {
+        if (locals.has(s.name) && !live.has(s.name) && !mustKeep(s.value, volatiles)) {
           continue; // dead local store — drop it; liveness is unchanged (it was a no-op)
         }
         live.delete(s.name); // the write kills the name for statements before it …
@@ -152,8 +138,8 @@ function dceBlock(
         break;
       }
       case 'if': {
-        const t = dceBlock(s.then, live, locals);
-        const e = dceBlock(s.else, live, locals);
+        const t = dceBlock(s.then, live, locals, volatiles);
+        const e = dceBlock(s.else, live, locals, volatiles);
         const nlive = new Set<string>();
         for (const r of reads(s.cond)) {
           nlive.add(r);
@@ -167,11 +153,11 @@ function dceBlock(
         setLive(nlive);
         if (t.out.length === 0 && e.out.length === 0) {
           // both arms empty: keep only if the condition itself has a side effect
-          if (mustKeep(s.cond)) {
+          if (mustKeep(s.cond, volatiles)) {
             rev.push({ k: 'exprstmt', value: s.cond });
           }
         } else if (t.out.length === 0) {
-          rev.push({ k: 'if', cond: negate(s.cond), then: e.out, else: [] });
+          rev.push({ k: 'if', cond: negateCond(s.cond), then: e.out, else: [] });
         } else {
           rev.push({ k: 'if', cond: s.cond, then: t.out, else: e.out });
         }
@@ -183,7 +169,7 @@ function dceBlock(
         // loop-carried store is never cut. Body DCE removes only what is dead on EVERY path.
         const loopLive = new Set(live);
         allReadsInto([s], loopLive);
-        const b = dceBlock(s.body, loopLive, locals);
+        const b = dceBlock(s.body, loopLive, locals, volatiles);
         const nlive = new Set(loopLive);
         for (const r of b.liveIn) {
           nlive.add(r);
@@ -195,7 +181,7 @@ function dceBlock(
       case 'for': {
         const loopLive = new Set(live);
         allReadsInto([s], loopLive);
-        const b = dceBlock(s.body, loopLive, locals);
+        const b = dceBlock(s.body, loopLive, locals, volatiles);
         const nlive = new Set(loopLive);
         for (const r of b.liveIn) {
           nlive.add(r);
@@ -209,8 +195,8 @@ function dceBlock(
         // read anywhere in the switch as live throughout — no case-body store is ever cut.
         const swLive = new Set(live);
         allReadsInto([s], swLive);
-        const cases = s.cases.map((c) => ({ ...c, body: dceBlock(c.body, swLive, locals).out }));
-        const def = s.default ? dceBlock(s.default, swLive, locals).out : s.default;
+        const cases = s.cases.map((c) => ({ ...c, body: dceBlock(c.body, swLive, locals, volatiles).out }));
+        const def = s.default ? dceBlock(s.default, swLive, locals, volatiles).out : s.default;
         const nlive = new Set(swLive);
         for (const r of reads(s.scrutinee)) {
           nlive.add(r);
@@ -248,9 +234,15 @@ function referencedNames(stmts: Stmt[], out: Set<string>): void {
 /** Remove dead local stores and simplify the branches they empty out, then drop any local
  *  declaration left unreferenced. Returns a new SFn; the input is not mutated. */
 export function eliminateDeadStores(sfn: SFn): SFn {
-  const locals = new Set(sfn.locals.map((l) => l.name));
-  const body = dceBlock(sfn.body, new Set<string>(), locals).out;
+  // A VOLATILE local is never eligible: its stores are observable through the escaped address (the
+  // DMA hardware reads them) wherever they sit. The `addr`-as-read pin alone only protected stores
+  // UPSTREAM of an `&sp0` occurrence in this backward walk — the legal publish-address-then-fill
+  // ordering (`*dmaReg = &sp0;` THEN `sp0 = v;`) had its store deleted by this very pass, defeating
+  // the volatile the frontend added precisely so the RECOMPILER would not delete it.
+  const volatiles = new Set(sfn.locals.filter((l) => l.volatile).map((l) => l.name));
+  const locals = new Set(sfn.locals.filter((l) => !l.volatile).map((l) => l.name));
+  const body = dceBlock(sfn.body, new Set<string>(), locals, volatiles).out;
   const used = new Set<string>();
   referencedNames(body, used);
-  return { ...sfn, body, locals: sfn.locals.filter((l) => used.has(l.name)) };
+  return { ...sfn, body, locals: sfn.locals.filter((l) => used.has(l.name) || l.volatile) };
 }

package/src/l3/gates.ts

@@ -0,0 +1,67 @@
+// A pass's admission rules as DATA, so "does every sound gate have a test that fails without it?"
+// is a query instead of an audit.
+//
+// Because the table is a value, a test can drop one entry and re-run the pass: the real predicate,
+// on real input, with no test-only branch in the shipped path. That makes `sound` cost something to
+// declare — see `gateTableDefects` and the contract test that pairs with it.
+//
+// `why` is a LABEL, one line. The argument for why the rule is correct belongs in the file header,
+// which has room; duplicating it here is how a table stops paying for itself.
+export interface Gate<Ctx> {
+  /** stable, kebab-case; appears in test names and in the contract report */
+  readonly id: string;
+  /** one line: the reason the rule exists */
+  readonly why: string;
+  /** Remove it and some candidate is WRONG, not merely worse. Everything else is a codegen
+   *  heuristic the differ still referees. This flag is what makes `guardedBy` mandatory. */
+  readonly sound: boolean;
+  /** the test that fails when this gate is removed — required for a sound gate */
+  readonly guardedBy?: string;
+  /** true ⇒ REJECT this candidate */
+  readonly rejects: (c: Ctx) => boolean;
+}
+
+/** The id of the first gate that rejects `c`, or null when every gate admits it. FIRST, not all:
+ *  one decisive rule is what makes a refusal attributable, and it keeps the cost the same as the
+ *  `||` chain this replaces — evaluation still short-circuits. */
+export function firstRejection<Ctx>(gates: readonly Gate<Ctx>[], c: Ctx): string | null {
+  for (const g of gates) {
+    if (g.rejects(c)) {
+      return g.id;
+    }
+  }
+  return null;
+}
+
+/** A gate table with one entry removed — the ablation, as a value. Throws on an unknown id: a
+ *  typo'd ablation that silently tests nothing is the failure this file exists to prevent. */
+export function without<Ctx>(gates: readonly Gate<Ctx>[], id: string): readonly Gate<Ctx>[] {
+  if (!gates.some((g) => g.id === id)) {
+    throw new Error(`no gate '${id}' to ablate (have: ${gates.map((g) => g.id).join(', ')})`);
+  }
+  return gates.filter((g) => g.id !== id);
+}
+
+/** Structural defects in a gate table — the part checkable without running the pass. Returns
+ *  findings rather than throwing, so core stays free of a test-framework import. */
+export function gateTableDefects<Ctx>(gates: readonly Gate<Ctx>[]): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const g of gates) {
+    if (seen.has(g.id)) {
+      out.push(`duplicate gate id '${g.id}'`);
+    }
+    seen.add(g.id);
+    if (!/^[a-z][a-z0-9-]*$/.test(g.id)) {
+      out.push(`gate id '${g.id}' is not kebab-case`);
+    }
+    if (g.why.trim().length < 12) {
+      out.push(`gate '${g.id}' has no usable \`why\``);
+    }
+    // the one rule that costs something to declare
+    if (g.sound && !g.guardedBy?.trim()) {
+      out.push(`gate '${g.id}' is marked sound but names no guard`);
+    }
+  }
+  return out;
+}