@asmlift/core 0.8.1 → 0.10.0

package/src/l3/hoist.ts

@@ -10,7 +10,7 @@
 // see `HoistPlacement` and `BaseInitPlacement`. Everything lives in one file because each half was
 // a per-caller copy once and every copy drifted from its original.
 import type { Expr, SFn, Stmt } from './ast';
-import { exprChildren, mapStmtLists, stmtChildren, stmtExprs, stmtLists } from './ast';
+import { exprChildren, mapStmtLists, mentionedName, stmtChildren, stmtExprs, stmtLists } from './ast';
 import { localMentions } from './mentions';
 
 /** Every identifier a MINTED name must not collide with, anywhere in `sfn` — the hoists below,
@@ -18,17 +18,18 @@ import { localMentions } from './mentions';
  *
  *  Wider than "the declared locals" on purpose, and each addition is a real collision:
  *   - params and locals, obviously;
- *   - every `var`/`addr` mentioned — a GLOBAL is referenced by bare name, so a local shadowing one
- *     silently redirects every later mention of it;
+ *   - every name an expression mentions — a GLOBAL is referenced by bare name, so a local shadowing
+ *     one silently redirects every later mention of it;
  *   - every CALL TARGET — a local named like a callee shadows the function;
  *   - every assignment target, which includes names no declaration list carries. */
 export function takenNames(sfn: SFn): Set<string> {
   const taken = new Set<string>([...sfn.params.map((p) => p.name), ...sfn.locals.map((l) => l.name)]);
   const visit = (e: Expr): void => {
-    if (e.k === 'var' || e.k === 'addr') {
-      taken.add(e.name);
+    const n = mentionedName(e);
+    if (n !== undefined) {
+      taken.add(n);
     }
-    if (e.k === 'call') {
+    if (e.k === 'call' && typeof e.fn === 'string') {
       taken.add(e.fn);
     }
     for (const c of exprChildren(e)) {
@@ -115,7 +116,7 @@ function mentionsHere(s: Stmt, name: string): boolean {
   }
   let found = false;
   const visit = (e: Expr): void => {
-    if ((e.k === 'var' || e.k === 'addr') && e.name === name) {
+    if (mentionedName(e) === name) {
       found = true;
     }
     for (const c of exprChildren(e)) {

package/src/l3/initfirst.ts

@@ -38,15 +38,33 @@
 // re-enters everything, a case can fall through), so there the variable must appear nowhere
 // outside the rewritten `if` at all. Declines (null) when nothing changes.
 import type { Expr, SFn, Stmt } from './ast';
-import { NEGATE_REL, exprChildren, exprEquals, exprHasEffect, stmtChildren, stmtExprs, walkExprs } from './ast';
-import { arithConversionSignedness, declaredTypes, provablyNonNegative } from './typing';
+import {
+  NEGATE_REL,
+  exprChildren,
+  exprEquals,
+  exprHasEffect,
+  keepsHelperRel,
+  mentionedName,
+  stmtChildren,
+  stmtExprs,
+  walkExprs,
+} from './ast';
+import {
+  arithConversionSignedness,
+  declaredTypes,
+  exprIntWidth,
+  provablyNonNegative,
+  rendersSignedOverUnsigned,
+} from './typing';
 
 const readsVar = (e: Expr, name: string): boolean =>
-  ((e.k === 'var' || e.k === 'addr') && e.name === name) || exprChildren(e).some((c) => readsVar(c, name));
+  mentionedName(e) === name || exprChildren(e).some((c) => readsVar(c, name));
 
-// READS only — a pure write in a tail is benign (it overwrites the minted value on every path,
-// and any read after it is that write's business); touchesOutside below is TOTAL because strong
-// mode must know the name is absent, presence of any kind included.
+// MENTIONS in an expression — a read, an `&v` a callee may read through, a `v++` that reads before
+// it writes. A whole-statement write is what is benign (an `assign` overwrites the minted value on
+// every path, and any read after it is that write's business), which is why the target of one is
+// not consulted here; touchesOutside below is TOTAL because strong mode must know the name is
+// absent, presence of any kind included.
 const stmtTouches = (s: Stmt, name: string): boolean =>
   stmtExprs(s).some((e) => readsVar(e, name)) || stmtChildren(s).some((x) => stmtTouches(x, name));
 
@@ -67,10 +85,11 @@ const stripWideIntCast = (e: Expr): Expr =>
  *  would silently discard it. */
 const varRooted = (e: Expr): boolean => (e.k === 'var' ? true : e.k === 'cast' ? varRooted(e.e) : false);
 
-/** A guard re-spell's X: call/marker-free, every named leaf a non-volatile param/local of THIS
- *  function (a global or `&gSym` could be project-declared volatile), and every deref `varRooted`. */
+/** A guard re-spell's X: call/marker/post-increment-free, every named leaf a non-volatile param/local
+ *  of THIS function (a global or `&gSym` could be project-declared volatile), and every deref
+ *  `varRooted`. */
 const hoistableRead = (e: Expr, ownNames: ReadonlySet<string>, volatileLocals: ReadonlySet<string>): boolean => {
-  if (e.k === 'call' || e.k === 'marker' || e.k === 'addr') {
+  if (e.k === 'call' || e.k === 'marker' || e.k === 'postincr' || e.k === 'addr') {
     return false;
   }
   if (e.k === 'var' && (!ownNames.has(e.name) || volatileLocals.has(e.name))) {
@@ -83,8 +102,9 @@ const hoistableRead = (e: Expr, ownNames: ReadonlySet<string>, volatileLocals: R
 };
 
 /** A compare operand and the init's value denote the same 32-bit value under different SPELLINGS
- *  when a width-32 cast is all that separates them: `/uns-cmp` wraps one side in `(u32)` to make
- *  the branch unsigned, and on a zero-trip guard that side is the very const the init assigns.
+ *  when a width-32 cast is all that separates them: the unsigned-compare spelling wraps one side in
+ *  `(u32)` to make the branch unsigned, and on a zero-trip guard that side is the very const the
+ *  init assigns.
  *  The swap is still exact — `v = X` stores X's 32 bits and `v` is 32-bit-declared
  *  (meaningPreserved refuses otherwise), so `v` and `(u32)X` carry the same bit pattern and only
  *  the compare's rendered signedness can differ, which meaningPreserved checks separately. A
@@ -110,6 +130,12 @@ const meaningPreserved = (
   if (vt?.kind !== 'int' || vt.width !== 32) {
     return false;
   }
+  // …AND SO MUST X, which the premise above states and the check did not: `v = X` represents X
+  // exactly only while X fits in v, so a 64-bit X assigned to a 32-bit v truncates and every
+  // signedness argument below it is about a value the program does not have.
+  if (exprIntWidth(side === 'l' ? l : r, env) !== 32) {
+    return false;
+  }
   if (provablyNonNegative(l, env) && provablyNonNegative(r, env)) {
     return true;
   }
@@ -119,6 +145,25 @@ const meaningPreserved = (
   return before !== undefined && before === after;
 };
 
+/** `cond` with one side read through `v`, AFTER `meaningPreserved` said yes. That answer is a
+ *  value proof the finished tree cannot repeat: `v` holds X, but `v`'s declaration does not say
+ *  what range X had, so rank.ts's judgment of the tree (typing.ts `signedOverUnsignedCompare`)
+ *  would call an unsigned compare whose ORIGINAL operands were both non-negative signed, and
+ *  withhold a spelling that compares the same values. So a compare that was value-faithful before
+ *  the swap is marked proved: its `unsignedCmp` evidence is dropped. One that was not keeps it. */
+const swapSide = (
+  cond: Extract<Expr, { k: 'bin' }>,
+  side: 'l' | 'r',
+  v: string,
+  env: ReturnType<typeof declaredTypes>,
+): Expr => {
+  const out: Extract<Expr, { k: 'bin' }> = { ...cond, [side]: { k: 'var', name: v } };
+  if (cond.unsignedCmp === true && !rendersSignedOverUnsigned(cond.l, cond.r, env)) {
+    delete out.unsignedCmp;
+  }
+  return out;
+};
+
 /** TOTAL (reads and pure writes) — see the note on stmtTouches. Runs against the pre-rewrite
  *  tree (`skip` is an original-tree statement, found by identity); the rewrites never change a
  *  name's presence in a subtree, so the verdict carries over to the rewritten one. */
@@ -205,7 +250,7 @@ export function initFirstGuards(sfn: SFn): SFn | null {
         then = then.slice(1);
         els = els.slice(1);
       }
-      if (then.length === 0 && els.length > 0) {
+      if (then.length === 0 && els.length > 0 && !keepsHelperRel(cond)) {
         const neg = cond.k === 'bin' ? NEGATE_REL[cond.op] : undefined;
         if (neg !== undefined && cond.k === 'bin') {
           cond = { ...cond, op: neg };
@@ -216,16 +261,20 @@ export function initFirstGuards(sfn: SFn): SFn | null {
       // a COMMON-hoisted variable holds its const on both paths, so the condition's matching
       // const operand reads through it unconditionally — no tail gate needed.
       // A BARE const only, where the guard re-spelling below uses the cast-tolerant `sameValue`:
-      // this site does not run `meaningPreserved`, so it may not swap in a name whose declared
-      // type could re-render the compare's signedness — which is exactly what peeling a `(u32)`
-      // would put on the table. A row that needs `/uns-cmp`'s spelling hoisted here brings the
-      // gate with it.
+      // peeling a `(u32)` here would put a re-rendered signedness on the table with no cast left to
+      // say which. The name's DECLARED type can re-render it too — `if (a1 > 0)` read through a
+      // `u32 v` that holds the 0 is `a1 != 0` — so the swap asks `meaningPreserved` as the guard
+      // re-spelling does.
       for (const hv of hoisted) {
         if (cond.k === 'bin' && NEGATE_REL[cond.op]) {
           if (cond.l.k === 'const' && cond.l.value === hv.value) {
-            cond = { ...cond, l: { k: 'var', name: hv.name } };
+            if (meaningPreserved(cond.l, cond.r, 'l', hv.name, env)) {
+              cond = swapSide(cond, 'l', hv.name, env);
+            }
           } else if (cond.r.k === 'const' && cond.r.value === hv.value) {
-            cond = { ...cond, r: { k: 'var', name: hv.name } };
+            if (meaningPreserved(cond.l, cond.r, 'r', hv.name, env)) {
+              cond = swapSide(cond, 'r', hv.name, env);
+            }
           }
         }
       }
@@ -265,7 +314,7 @@ export function initFirstGuards(sfn: SFn): SFn | null {
         ) {
           out.push(init);
           moved.add(init);
-          cond = { ...cond, [side]: { k: 'var', name: init.name } };
+          cond = swapSide(cond, side, init.name, env);
           then = then.slice(1);
           changed = true;
         }

package/src/l3/intcell.ts

@@ -0,0 +1,98 @@
+// L3 respell variation: a pointer cell spelled as the integer a project may have declared it.
+//
+// A global the body stores a pointer into is spelled as a pointer (l3/ptrcell.ts): the store is
+// `g = (void *)((u8 *)g + K)` or `g = (void *)X`, the integer uses convert it, `(u32)g`, and the
+// candidate's own world declares it `void *`. A project that declares the cell an INTEGER
+// (`u32 g; … g += 4;`) wrote none of those conversions, and two compilers tell: CodeWarrior rejects
+// a pointer stored into the integer, and IDO allocates registers differently around a `(u32)g` it
+// takes as a conversion. Under a pointer declaration `g = g + K` scales K by the pointee instead,
+// so which of the two is right is a fact about the project's declaration, which nothing in the asm
+// states.
+//
+// So the spelling is a PROOF-CARRYING candidate (`needsProof`, Candidate.matchOnly): published
+// only at a byte-exact score, where the bytes are the evidence that the declaration it compiled
+// against gives K the asm's stride. Its own self-declared world declares the cell an integer,
+// because no pointer store is left in it.
+//
+// SCOPE (decline over approximate): a cell no declaration in the tree types and the symbol map
+// does not declare other than an integer, and of its uses only the ones the pointer spelling made:
+// the `(void *)` stores into it and a `(u32)` conversion of its bare value. A map's pointer is the
+// project's own declaration, and its own world declares that, under which a byte-exact score is
+// no evidence of the stride the project's pointee gives K. A global the body only reads converted
+// is not this question.
+import type { IrType } from '../ir/types';
+import { T } from '../ir/types';
+import { type Expr, type SFn, type Stmt, mapExprChildren, mapStmtExprs } from './ast';
+import { pointerCellStore, pointerCellsOf } from './ptrcell';
+import { declaredTypes } from './typing';
+
+const isPtrTo = (t: IrType, to: 'void' | 'u8'): boolean =>
+  t.kind === 'ptr' && (to === 'void' ? t.to.kind === 'void' : t.to.kind === 'int' && t.to.width === 8);
+const isWord = (t: IrType): boolean => t.kind === 'int' && t.width === 32;
+
+/** `g`, `(u8 *)g`, `(u32)g` or `(u32)(u8 *)g` for the bare name `name`. */
+const isCell = (x: Expr, name: string): boolean =>
+  (x.k === 'var' && x.name === name) || (x.k === 'cast' && (isWord(x.to) || isPtrTo(x.to, 'u8')) && isCell(x.e, name));
+
+/** The integer a `(void *)` store into the cell `name` stores: its own arithmetic for a self-store,
+ *  a bare value as it stands, anything else converted. */
+function integerValue(value: Expr, name: string): Expr {
+  const stored = value.k === 'cast' ? value.e : value;
+  // `(u8 *)((u32)g + r)`: the integer sum the arithmetic table restores to a byte pointer
+  // (structure/pointer-spelling.ts ARITH_ROWS, `restore: 'bytes'`)
+  const sum = stored.k === 'cast' && isPtrTo(stored.to, 'u8') ? stored.e : stored;
+  if (sum.k === 'bin' && (sum.op === '+' || sum.op === '-') && isCell(sum.l, name)) {
+    return { ...sum, l: { k: 'var', name } };
+  }
+  return stored.k === 'var' ? stored : { k: 'cast', to: T.u(32), e: stored };
+}
+
+/** The `/int-cell` candidate: every pointer cell no declaration types, spelled as an integer.
+ *  `mapDeclared` says the symbol map declares a name something other than an integer. */
+export function integerCells(
+  sfn: SFn,
+  mapDeclared: (name: string) => boolean,
+): { sfn: SFn; needsProof: boolean } | null {
+  const vt = declaredTypes(sfn);
+  const cells = new Set([...pointerCellsOf(sfn)].filter((n) => vt(n) === undefined && !mapDeclared(n)));
+  if (cells.size === 0) {
+    return null;
+  }
+  const expr = (e0: Expr): Expr => {
+    const e = mapExprChildren(e0, expr);
+    if (e.k === 'cast' && isWord(e.to)) {
+      const inner = e.e.k === 'cast' && isPtrTo(e.e.to, 'u8') ? e.e.e : e.e;
+      if (inner.k === 'var' && cells.has(inner.name)) {
+        return inner;
+      }
+    }
+    return e;
+  };
+  const stmt = (s: Stmt): Stmt => {
+    switch (s.k) {
+      case 'assign': {
+        const value = expr(s.value);
+        return cells.has(s.name) && pointerCellStore(s) !== undefined
+          ? { ...s, value: integerValue(value, s.name) }
+          : { ...s, value };
+      }
+      case 'if':
+        return { ...s, cond: expr(s.cond), then: s.then.map(stmt), else: s.else.map(stmt) };
+      case 'while':
+      case 'dowhile':
+        return { ...s, cond: expr(s.cond), body: s.body.map(stmt) };
+      case 'for':
+        return { ...s, init: stmt(s.init), cond: expr(s.cond), inc: stmt(s.inc), body: s.body.map(stmt) };
+      case 'switch':
+        return {
+          ...s,
+          scrutinee: expr(s.scrutinee),
+          cases: s.cases.map((c) => ({ ...c, body: c.body.map(stmt) })),
+          default: s.default?.map(stmt),
+        };
+      default:
+        return mapStmtExprs(s, expr);
+    }
+  };
+  return { sfn: { ...sfn, body: sfn.body.map(stmt) }, needsProof: true };
+}

package/src/l3/mentions.ts

@@ -90,7 +90,7 @@ export function localMentions(sfn: SFn): Map<string, Mentions> {
     }
     for (const e of stmtExprs(s)) {
       walkExpr(e, (x, isIndexBase) => {
-        if (x.k === 'var' || x.k === 'addr') {
+        if (x.k === 'var' || x.k === 'addr' || x.k === 'postincr') {
           const m = seen(x.name, at);
           if (m) {
             if (x.k === 'addr') {
@@ -100,6 +100,11 @@ export function localMentions(sfn: SFn): Map<string, Mentions> {
             } else {
               m.otherUses++;
             }
+            // `v++` reads AND writes, so it counts on both sides. `topAssignAt`/`constValue` stay
+            // untouched: they describe a top-level `assign` STATEMENT, which this is not.
+            if (x.k === 'postincr') {
+              m.assigns++;
+            }
           }
         }
       });
@@ -126,8 +131,9 @@ export function localMentions(sfn: SFn): Map<string, Mentions> {
  *  rewriting and go stale.
  *
  *  TOTAL over the vocabulary by construction: `assign` is the only `Stmt` carrying a bare name and
- *  `var`/`addr` the only `Expr`s, and both walks are derived from `stmtChildren`/`stmtExprs` — so a
- *  `for`'s init and inc, a `switch`'s scrutinee, its cases and its default are all covered. */
+ *  `var`/`addr`/`postincr` the only `Expr`s, and both walks are derived from
+ *  `stmtChildren`/`stmtExprs` — so a `for`'s init and inc, a `switch`'s scrutinee, its cases and its
+ *  default are all covered. */
 function scanMentions(stmts: readonly Stmt[], names: ReadonlySet<string>, first: boolean): Set<string> {
   // TWO FLAT SWEEPS, not one expression walk per nesting level. `walkExprs` already descends
   // `stmtChildren` (ast.ts), so calling it per statement from inside a recursion that ALSO
@@ -149,7 +155,7 @@ function scanMentions(stmts: readonly Stmt[], names: ReadonlySet<string>, first:
     stack.push(...stmtChildren(s));
   }
   for (const e of walkExprs(body)) {
-    if ((e.k === 'var' || e.k === 'addr') && names.has(e.name)) {
+    if ((e.k === 'var' || e.k === 'addr' || e.k === 'postincr') && names.has(e.name)) {
       found.add(e.name);
       if (first) {
         return found;

package/src/l3/narrowdecl.ts

@@ -0,0 +1,259 @@
+// L3 stacked variations `/narrow-decl`, `/narrow-load` and `/narrow-read`: a named narrow value
+// declared at its width. `/narrow-decl` takes the narrowing cast at the local's one write,
+// `/narrow-load` a write that is a narrow memory read, which has no cast to drop, and `/narrow-read`
+// the narrowing at every one of its reads:
+//
+//   s32 v; v = (u8)(x - 1); … v …        becomes   u8 v; v = x - 1; … v …       (/narrow-decl)
+//   s32 v; v = p[3]; … v …               becomes   u8 v; v = p[3]; … v …        (/narrow-load)
+//   s32 v; v = f(); … (u8)v … (u8)v …    becomes   u8 v; v = f(); … v … v …     (/narrow-read)
+//
+// The two spellings compute the same C value at every read. The declaration truncates where the
+// cast did, or stores a value already of its type, and a `u8`, `s8`, `u16` or `s16` read is
+// promoted to `int`, which is what an `s32` read already is. They are not the same program to gcc
+// 2.9's front end. `get_narrower` (gcc/tree.c:4516) sees through the promotion of a narrow VARIABLE
+// and not through an `int` that a cast was assigned to, so for an unsigned narrow one
+// `shorten_compare` (gcc/c-common.c:1158) makes a compare against a constant unsigned and folds
+// `>= 0`, `/` and `%` are shortened to their unsigned helpers (gcc/c-typeck.c:2036-2041, :2079-2090),
+// and `>>` becomes a logical shift (gcc/c-typeck.c:2119). Without such an operator the object can
+// still differ: `convert_to_integer` pushes a narrow store's truncation into an AND's operands
+// (gcc/convert.c:278-284), and a `u8` local is a pseudo PROMOTE_MODE already zero-extended
+// (gcc/thumb.h:344, gcc/stmt.c:3318-3323), whose low byte is free to read (gcc/expr.c:830-836),
+// where an `s32` one takes a fresh byte pseudo and a register copy. Compiled with agbcc
+// `-O2 -mthumb-interwork -fhex-asm -fprologue-bugfix`,
+//
+//   v = g.c - 1;  h.d = (v & 1) + rnd() % (5 - v) + 1;
+//
+// copies `v` before the AND under `s32 v` (`mov r1, #1; add r4, r5, #0; and r4, r4, r1`) and
+// operates on it in place under `u8 v` (`mov r5, #1; and r5, r5, r4`), which is what
+// `kleod:sub_0803E8CC` holds; over `v | 2`, `v ^ 2`, `v + 3` and `v * 3` the two compile alike.
+// IDO, KMC gcc and gcc 2.7.2 each emit different code for that pair as well, and every mwcc
+// build does for a compare of the narrowed value. Which one the
+// source declared is not in the asm, so the differ referees, and the candidate it is derived onto
+// stays in the fan. A load written to a `u8` local is loaded where it is written, and one written to
+// an `s32` local where it is first read (two byte reads held across two calls, compiled in the
+// matching suite: `pokeemerald:LoadMonInfo`).
+//
+// At the reads, `(u8)(s32)e`, `(u8)(u32)e` and `(u8)e` keep the same low byte of any integer `e`,
+// so dropping each read's cast keeps its value, whichever write stored it. The pair compiles
+// differently by where the extension lands: a `u8` local holding a call's result is zero-extended
+// as it is stored, right after the `bl`, where `(u8)v` extends at the read, after whatever ran in
+// between (`pokeemerald:RtcGetDayCount`, three results passed on as `u8`s).
+//
+// Three STACKED variations (rank-variations.ts), derived onto every other candidate's tree: the
+// width of a declaration is orthogonal to what every respell variation outside that table changes,
+// and the row that needs it needs it on top of `/offmember`. Three, not one, because a function
+// holding a local narrowed at its cast write, a local written by a narrow load and a local narrowed
+// at its reads may need any combination of the kinds narrowed. Each rewrites every local it admits.
+// They do not commute: a cast that is one local's write and another's read is taken by whichever
+// runs first, and so is a load-written local whose reads are all narrowed. So every subset of the
+// three is its own candidate, and in one holding a write-side member and `/narrow-read` the
+// write side runs first and takes the local.
+//
+// KNOWN GAP, and it is the price of deciding at L3 rather than where the value is named: which
+// spelling a call's result had shows only in where its extension lands, right after its `bl` or
+// just before its read, and structure/analysis.ts settles that per local when it names the call and
+// inlines the extension into the read. So two read-side locals declared differently (`s32 y` cast
+// at its read beside `u8 m`) have no candidate, as each entry narrows both or neither; here that
+// would take 2^k candidates over k such locals. Nor has `s32 v = (u8)f()` once another such value
+// is held across its call, which then compiles like neither spelling; held alone it compiles like
+// `u8 v`, which /narrow-read reaches.
+//
+// REFUSED, each because the two spellings would stop computing the same value or would not build:
+//   • a local that is not a 32-bit integer;
+//   • a local whose address is taken, or that is volatile, a frame object, uninitialized, or homed
+//     in a stack slot. Each of those is an object in memory, whose width is its access width;
+//   • a write of a constant that fits neither the signed nor the unsigned type of the narrow width,
+//     which gcc warns of when it converts one implicitly (gcc/c-common.c:849-861, :870-895) and a
+//     `-Werror` build refuses;
+//   • /narrow-decl, /narrow-load: a `u32` local. Its reads stay bare, and a `u32` read is unsigned,
+//     so narrowing it would turn its compares, divisions and shifts into signed ones;
+//   • /narrow-decl, /narrow-load: a local written more than once, or by `v++`, where a later write
+//     could store a value the narrow declaration would truncate and a bare read would not;
+//   • /narrow-decl: a local whose one write is a `for` loop's init, or that is not an integer
+//     narrowed to a narrower integer. A call's operand is not known to be an integer (its callee
+//     may return a pointer), so `(u8)f()` is refused too;
+//   • /narrow-load: a local whose one write is a `for` loop's init, or is no `p[i]` or member read
+//     of a narrower integer type. A narrow variable (`v = a1` of a `u8 a1`) is refused: no row has
+//     needed it;
+//   • /narrow-read: a read that is not a narrowing cast (a bare `v`, an index base, a `v++`), reads
+//     cast to two widths or two signednesses, a write in a `for` loop's init or step, and a write
+//     whose value is a pointer, a float or of no known type. A call is admitted: its value already
+//     converts implicitly to the 32-bit local, and narrowing changes only the width of that
+//     conversion, never whether C performs one. A `u32` local and one written more than once are
+//     admitted, because every read already narrows each value stored to the one width.
+import type { IrType } from '../ir/types';
+import {
+  type Expr,
+  type SFn,
+  type Stmt,
+  mapExprChildren,
+  mapStmtExprs,
+  mapStmtLists,
+  stmtLists,
+  walkExprs,
+} from './ast';
+import { type Mentions, localMentions, readsOf } from './mentions';
+import { declaredTypes, exprCType } from './typing';
+
+type Narrowing = Extract<Expr, { k: 'cast' }> & { to: Extract<IrType, { kind: 'int' }> };
+
+/** An integer narrowed to a narrower integer. A pointer or a float operand keeps its cast: C converts
+ *  neither to an integer by assignment alone. */
+const isNarrowing = (e: Expr, env: ReturnType<typeof declaredTypes>): e is Narrowing =>
+  e.k === 'cast' && !e.volatile && e.to.kind === 'int' && e.to.width < 32 && exprCType(e.e, env)?.kind === 'int';
+
+/** The narrower integer type a memory read (`p[i]`, `*p`, a member) already has, which a local it is
+ *  assigned to may be declared at with nothing to drop. */
+const narrowLoad = (e: Expr, env: ReturnType<typeof declaredTypes>): Narrowing['to'] | undefined => {
+  if (e.k !== 'index' && e.k !== 'field') {
+    return undefined;
+  }
+  const t = exprCType(e, env);
+  return t?.kind === 'int' && t.width < 32 ? (t as Narrowing['to']) : undefined;
+};
+
+/** `(T)v`, the read of `name` narrowed to the narrower integer T. */
+const isReadNarrowing = (e: Expr, name: string): e is Narrowing =>
+  e.k === 'cast' && !e.volatile && e.to.kind === 'int' && e.to.width < 32 && e.e.k === 'var' && e.e.name === name;
+
+/** The one type every read of `name` is narrowed to, or undefined when a read is not narrowed
+ *  or two reads are narrowed differently. `reads` counts every read however spelled, so a read
+ *  that is not a narrowing leaves the count short. */
+function readNarrowing(body: Stmt[], name: string, reads: number): Narrowing['to'] | undefined {
+  let to: Narrowing['to'] | undefined;
+  let narrowed = 0;
+  for (const e of walkExprs(body)) {
+    if (!isReadNarrowing(e, name)) {
+      continue;
+    }
+    if (to !== undefined && (to.width !== e.to.width || to.signed !== e.to.signed)) {
+      return undefined;
+    }
+    to = e.to;
+    narrowed++;
+  }
+  return narrowed === reads ? to : undefined;
+}
+
+/** The value of every assignment statement to `name`, found the way the write-side rewrite finds
+ *  them: through statement lists, so a `for` init or step is not one. */
+function writtenValues(body: Stmt[], name: string): Expr[] {
+  const values: Expr[] = [];
+  const walk = (list: Stmt[]): void => {
+    for (const s of list) {
+      if (s.k === 'assign' && s.name === name) {
+        values.push(s.value);
+      }
+      stmtLists(s).forEach(walk);
+    }
+  };
+  walk(body);
+  return values;
+}
+
+/** `body` with every `(T)name` read spelled `name`. */
+const dropReadCasts = (body: Stmt[], name: string): Stmt[] => {
+  const expr = (e: Expr): Expr => (isReadNarrowing(e, name) ? e.e : mapExprChildren(e, expr));
+  return body.map((s) => mapStmtExprs(s, expr));
+};
+
+/** The local's admission common to both sides: a 32-bit integer in no memory. */
+const admissible = (l: SFn['locals'][number], m: Mentions | undefined): m is Mentions =>
+  m !== undefined &&
+  m.addrTaken === 0 &&
+  l.type.kind === 'int' &&
+  l.type.width === 32 &&
+  !l.volatile &&
+  !l.frame &&
+  !l.uninit &&
+  !l.slots;
+
+/** Whether storing `value` into an `int` of `to`'s width converts without gcc's constant warning: a
+ *  constant must fit the signed or the unsigned type of that width. */
+const storesQuietly = (value: Expr, to: Narrowing['to']): boolean =>
+  value.k !== 'const' || (value.value >= -(2 ** (to.width - 1)) && value.value < 2 ** to.width);
+
+/** `sfn` with each local in `narrowed` declared at its width, or null when it is empty. */
+const declared = (sfn: SFn, body: Stmt[], narrowed: Map<string, IrType>): SFn | null =>
+  narrowed.size === 0
+    ? null
+    : { ...sfn, body, locals: sfn.locals.map((l) => ({ ...l, type: narrowed.get(l.name) ?? l.type })) };
+
+/** What a write-side variation makes of a local's one write: the narrow type to declare the local
+ *  at and the value to store, or undefined when it does not take that write. */
+type WriteNarrowing = (
+  value: Expr,
+  env: ReturnType<typeof declaredTypes>,
+) => { to: Narrowing['to']; value: Expr } | undefined;
+
+/** A narrowing cast, dropped. */
+const castWrite: WriteNarrowing = (value, env) =>
+  isNarrowing(value, env) && storesQuietly(value.e, value.to) ? { to: value.to, value: value.e } : undefined;
+
+/** A narrow memory read, kept as written. */
+const loadWrite: WriteNarrowing = (value, env) => {
+  const to = narrowLoad(value, env);
+  return to === undefined ? undefined : { to, value };
+};
+
+/** The tree with every admitted local whose one write `take` takes narrowed at that write, or null
+ *  when none is. */
+function narrowAtWrite(sfn: SFn, take: WriteNarrowing): SFn | null {
+  const mentions = localMentions(sfn);
+  const env = declaredTypes(sfn);
+  let body = sfn.body;
+  const narrowed = new Map<string, IrType>();
+  for (const l of sfn.locals) {
+    const m = mentions.get(l.name);
+    if (!admissible(l, m) || m.assigns !== 1 || l.type.kind !== 'int' || !l.type.signed) {
+      continue;
+    }
+    let to: IrType | undefined;
+    const rewrite = (list: Stmt[]): Stmt[] =>
+      list.map((s) => {
+        const taken = s.k === 'assign' && s.name === l.name ? take(s.value, env) : undefined;
+        if (taken !== undefined) {
+          to = taken.to;
+          return { ...s, value: taken.value };
+        }
+        return mapStmtLists(s, rewrite);
+      });
+    const next = rewrite(body);
+    if (to !== undefined) {
+      body = next;
+      narrowed.set(l.name, to);
+    }
+  }
+  return declared(sfn, body, narrowed);
+}
+
+/** `/narrow-decl`: the tree with every admitted local narrowed at its cast write, or null when none is. */
+export const narrowDeclarations = (sfn: SFn): SFn | null => narrowAtWrite(sfn, castWrite);
+
+/** `/narrow-load`: the tree with every admitted local written by a narrow memory read declared at that
+ *  read's type, or null when none is. */
+export const narrowLoadDeclarations = (sfn: SFn): SFn | null => narrowAtWrite(sfn, loadWrite);
+
+/** `/narrow-read`: the tree with every admitted local narrowed at its reads, or null when none is. */
+export function narrowReadDeclarations(sfn: SFn): SFn | null {
+  const mentions = localMentions(sfn);
+  const env = declaredTypes(sfn);
+  let body = sfn.body;
+  const narrowed = new Map<string, IrType>();
+  for (const l of sfn.locals) {
+    const m = mentions.get(l.name);
+    if (!admissible(l, m)) {
+      continue;
+    }
+    const written = writtenValues(body, l.name);
+    if (written.length !== m.assigns || written.some((w) => w.k !== 'call' && exprCType(w, env)?.kind !== 'int')) {
+      continue;
+    }
+    const read = readNarrowing(body, l.name, readsOf(m));
+    if (read !== undefined && written.every((w) => storesQuietly(w, read))) {
+      body = dropReadCasts(body, l.name);
+      narrowed.set(l.name, read);
+    }
+  }
+  return declared(sfn, body, narrowed);
+}

package/src/l3/nearbase.ts

@@ -11,11 +11,13 @@
 //
 // SCOPE (decline over approximate): cluster MEMBERSHIP comes from CONST deref bases only (a
 // struct-pointer cast base and everything inside a dot-form field subtree keep their spelling —
-// their stride is the struct's, not a byte's); a cluster needs at least two DISTINCT addresses
+// their stride is the struct's, not a byte's — and a `volatile`-qualified base keeps its spelling
+// and stays out of every cluster, since a `u8 *` base local would read and write the device
+// plainly); a cluster needs at least two DISTINCT addresses
 // within the target's declared derivation reach of its lowest (TargetDescription nearBaseSpan —
 // beyond it the derive costs more than the pool word it saves); every access the walk visits
-// rewrites, so a cluster splits only across the field-subtree and struct-pointer-cast
-// boundaries. A member basecse
+// rewrites, so a cluster splits only across the field-subtree, struct-pointer-cast and
+// `volatile` boundaries. A member basecse
 // already hoisted arrives as a `var` base and is invisible here — the reused-base and
 // neighbor-base spellings stay separate candidates. Once a cluster HAS formed, a bare const
 // VALUE inside its window re-spells too, as `(s32)(b + off)` — the address of a cell handed to
@@ -24,7 +26,7 @@
 // only coincidentally lands in the window, which is the stated cost of the variation (the `s32` cast
 // assumes addresses below 2^31, true of every target that declares nearBaseSpan today). Declines
 // (null) when no cluster forms.
-import { baseConst } from './address';
+import { baseConst, qualifiedBase } from './address';
 import type { Expr, SFn } from './ast';
 import { mapExprChildren, mapStmtExprs } from './ast';
 import { type BaseInit, nameAllocator, placeBaseLocals } from './hoist';
@@ -46,7 +48,7 @@ export function nearBaseClusters(sfn: SFn, span: number): SFn | null {
       return e; // rewrite refuses these subtrees, so collecting under them would seed a cluster
     }
     const m = mapExprChildren(e, collect);
-    if (m.k === 'index') {
+    if (m.k === 'index' && !qualifiedBase(m.base)) {
       const c = baseConst(m.base);
       if (c !== null) {
         addrs.add(c);
@@ -92,6 +94,9 @@ export function nearBaseClusters(sfn: SFn, span: number): SFn | null {
     if (e.k === 'field') {
       return e;
     }
+    if (e.k === 'index' && qualifiedBase(e.base)) {
+      return { ...e, idx: rewrite(e.idx) }; // the whole cast chain stays, so the access stays volatile
+    }
     if (e.k === 'index') {
       const c = baseConst(e.base);
       const lo = c !== null ? baseOf.get(c) : undefined;