@asmlift/core 0.4.0 → 0.6.0

package/src/l3/homesplit.ts

@@ -0,0 +1,285 @@
+// The `/livebase-block × /regionbase` PAIRING (rank.ts `/livebase-block/homesplit`): one base kept
+// at the function head and a SECOND base split into one local per region, in the same function.
+//
+// WHY IT IS NOT REACHABLE FROM EITHER LEVER. Both are whole-FUNCTION policies over the bases they
+// bind: `hoistBaseLocals` homes every key its table admits at one placement, and
+// `hoistScopedBases` splits every key its region rule admits. A function whose two bases want
+// OPPOSITE answers is spelled by neither. `synthetic:dmapoll` is that function and its endpoint is
+// compiled rather than argued: with both bases at function scope agbcc scores 11, with both split
+// per region 18, with neither hoisted 69 — and 0 only where the two policies apply to DIFFERENT
+// bases (the lattice in apps/benchmark/dataset/synthetic.ts).
+//
+// A PIPE, NEVER A MERGE, and that is the whole safety argument for the names. `hoistBaseLocals`
+// runs FIRST with one key withheld; every key it homes now reads through a pointer LOCAL, which
+// `SCOPEBASE_ELIGIBILITY`'s `shadowed-or-nonarray-base` refuses outright, so no key the head hoist
+// claimed reaches the second pass at all. What that pass DOES see is the withheld key together with
+// every base the caller's table never bound, and it splits those too — `splitHomeBases` counts the
+// withheld key's own entries and nothing else. `nameAllocator` (l3/hoist.ts) re-derives its taken
+// names from the tree it is handed, so the second pass cannot re-mint the first's. Merging two runs
+// over ONE input is the shape that would collide, and nothing here does it.
+//
+// WHICH KEY IS WITHHELD IS NOT DERIVABLE, so every admitted key is offered as its own candidate,
+// LABELLED WITH THAT KEY, and the differ referees — the same posture `/scopebase` and `/regionbase`
+// take toward each other. The label carries `homeSplitTag(key)` because a candidate label is an
+// IDENTITY: `bench diff` and docs/ranked-repro.md compare candidates by it, so one label over two
+// withholds would hide a program swap from both. The withhold itself is DATA: one rejection
+// prepended to the caller's own admission table, in the `Gate<BaseKey>` type that table already
+// has, so `firstRejection` attributes a refusal to it, `without` ablates it, and the composed table
+// is on `gate-contract.test.ts`'s roster like any other.
+//
+// EXACTLY ONE KEY IS WITHHELD, and the arity is a claim rather than an oversight. A two-key withhold
+// exists only where the caller's table binds three — `homesplit-fan-cap` admits no more — and there
+// it is the three further pairs, each carrying the three respells rank.ts derives from one pipe:
+// NINE more candidates per axis point on those functions alone, before any shape product, and no
+// row asks for one. `l3/volatileptr.ts`'s `volatileSubsetCandidates` enumerates every proper subset
+// under the same cap; it does that because a row demanded each of them. Widen this the same way,
+// on a row.
+//
+// SEMANTICS ARE PRESERVED BY CONSTRUCTION — both halves only re-spell where the address of a global
+// is materialized, and each half's own contracts (`placeBaseLocals`' ordering, `assertHoistsDominate`
+// on the region plan) still run. What the pairing can get WRONG is bytes, and one qualifier.
+import { addrConst, inRange } from './address';
+import type { Expr, SFn, Stmt } from './ast';
+import { exprChildren, stmtExprs, stmtLists } from './ast';
+import { type BaseKey, baseSites, hoistBaseLocals, leafId, parseBaseKey } from './basecse';
+import { type Gate, firstRejection } from './gates';
+import type { HoistPlacement } from './hoist';
+import { applyScopedBasePlan, planScopedBases, scopedBaseKey } from './scopebase';
+import { volatileEligibleValue } from './volatileptr';
+
+/** `gates` with `key` refused. The withhold goes FIRST so `firstRejection` attributes a refusal to
+ *  it rather than to whichever inherited rule would also have fired. */
+export const withholdingKey = (gates: readonly Gate<BaseKey>[], key: string): readonly Gate<BaseKey>[] => [
+  {
+    id: 'withheld-key',
+    why: 'this key is the one the region rule is to split, so the head hoist must not claim it',
+    sound: false,
+    rejects: (c) => c.key === key,
+  },
+  ...gates,
+];
+
+/** The withheld key as a LABEL token: `c:67109076 4 true` → `0x40000d4.4s`. Width and signedness
+ *  ride because they are part of the key — two keys over one address are two different spellings.
+ *
+ *  PARSED BY THE KEY'S PRODUCER (`l3/basecse.ts`'s `parseBaseKey`, beside `keyOf`), because a base
+ *  id is not one space-free word and a local split here gets it wrong in both directions. `baseId`
+ *  spells a CAST base as `a:gEnigmaBerries <Elem5*>` — one space, and it is the grammar's own
+ *  separator rather than the type's. Split from the FRONT, the type reads as the width and the
+ *  width as the signedness; split from the END, the `a:` form comes out right and the `c:` form
+ *  runs `Number` over `67109076 <u16*>`, tagging every cast over a numeric base `0xNaN` and
+ *  collapsing distinct keys onto one label. No shipped table admits a cast base outside
+ *  `/orderbase`, and `/orderbase` carries `pairings: false`, so no such key reaches this function
+ *  today — but a candidate LABEL is an identity (`bench diff` and docs/ranked-repro.md compare
+ *  candidates by it), and one roster line is all that stands between the two. The sibling half of
+ *  the same hazard is already guarded in `splitHomeBases`, which translates a cast base to no
+ *  region key and declines. */
+export function homeSplitTag(key: string): string {
+  const { leaf, castType, width, signed } = parseBaseKey(key);
+  const base = leaf.startsWith('c:') ? `0x${Number(leaf.slice(2)).toString(16)}` : leaf.slice(leaf.indexOf(':') + 1);
+  // The cast's element type stays in the token — it is part of the key's identity, since two casts
+  // over one symbol are two locals that stride differently. Whitespace is squeezed defensively
+  // rather than because any type spells one: a label is one whitespace-free word everywhere it is
+  // read, and that has to hold whatever `typeToString` grows.
+  const type = castType === null ? '' : `<${castType}>`;
+  return `${`${base}${type}`.replace(/\s+/g, '')}.${width}${signed ? 's' : 'u'}`;
+}
+
+/** The FUNCTION-level half of the admission: how many keys the caller's table binds on this tree.
+ *  Nothing about one withheld key, which is why it is decided once (see `homeSplitWithholds`). */
+export interface HomeSplitFanCtx {
+  /** how many keys the caller's admission table binds — the pairing needs at least two */
+  readonly hoistableKeys: number;
+}
+
+/** The two rules that read the tree's KEY COUNT and nothing else, which is why they are asked once
+ *  per (tree, table) rather than per candidate: inside the pipe they would cost a head hoist, a
+ *  region plan, a rewrite and a census to report a fact the caller holds before any of it. */
+export const HOMESPLIT_FAN_GATES: readonly Gate<HomeSplitFanCtx>[] = [
+  {
+    id: 'homesplit-degenerate',
+    why: 'withholding the only hoistable key is `/regionbase`, and withholding none is `/livebase-block`',
+    sound: false,
+    rejects: (c) => c.hoistableKeys < 2,
+  },
+  {
+    id: 'homesplit-fan-cap',
+    why: 'one candidate per hoistable key, times the volatile products — the whole cost of the axis',
+    sound: false,
+    rejects: (c) => c.hoistableKeys > 3,
+  },
+];
+
+/** One candidate PAIRING, as the per-key admission rules see it. */
+export interface HomeSplitCtx {
+  /** the region rule gives the withheld key two or more locals */
+  readonly withheldSplits: boolean;
+  /** the withheld key's head home would have been a `/volatile`-qualified local at a DEVICE
+   *  address, and the piped tree leaves a READ of that base inline */
+  readonly inlineDeviceRead: boolean;
+}
+
+/** The pairing's PER-KEY admission. NONE is sound, and none is owed a `sound: true`: withholding a
+ *  key from the head hoist and splitting it per region names the SAME ADDRESS in a different place
+ *  (`keyOf` folds width and signedness into the key), the two rules that decide MEANING already
+ *  live in `SCOPEBASE_ELIGIBILITY`, and a plan over a SUBSET of the keys admits nothing the
+ *  all-keys plan did not. What these rules decide is bytes, fan, and one qualifier.
+ *
+ *  `homesplit-drops-device-volatile` is the one that protects a row rather than the fan.
+ *  `/volatile` (l3/volatileptr.ts) qualifies MINTED POINTER LOCALS and `/vol-store` (l3/volstore.ts)
+ *  a STORE at a fixed device address; a device READ left inline is reached by neither. Withholding
+ *  a key is exactly what can leave one there — the head hoist would have homed it into a local
+ *  `/volatile` covers — so the pairing declines rather than publish a spelling that silently drops
+ *  a qualifier the spelling it replaces CARRIED.
+ *
+ *  WHETHER IT CARRIED ONE IS `/volatile`'s OWN QUESTION, so it is asked of that model
+ *  (`volatileEligibleValue`) rather than re-derived here from the base's node kind or its address.
+ *  The difference is the arm the benchmark runs on: under a symbol map an absolute pool constant
+ *  lifts to a `gaddr`, and `/volatile` VETOES a local fed `&gSym` because the symbol map owns a
+ *  declared global's volatility. On a named base the head home this rule protects is therefore
+ *  unqualified too — nothing is dropped, and refusing there would delete a spelling to protect a
+ *  qualifier NEITHER side carries. The address is a second question, asked only of a base the
+ *  qualifier could have reached. */
+export const HOMESPLIT_GATES: readonly Gate<HomeSplitCtx>[] = [
+  {
+    id: 'homesplit-no-region',
+    why: 'a withheld key the region rule declines to split leaves the spelling the primary carries',
+    sound: false,
+    rejects: (c) => !c.withheldSplits,
+  },
+  {
+    id: 'homesplit-drops-device-volatile',
+    why: 'a device read left inline is qualified by neither /volatile nor /vol-store',
+    sound: false,
+    rejects: (c) => c.inlineDeviceRead,
+  },
+];
+
+/** The keys this tree offers as withholds — one candidate each, or none at all. The caller asks
+ *  ONCE per (tree, admission table) and loops over the answer.
+ *
+ *  IT IS A KEY-COUNT FACT AND NEVER A SYMBOL-MAP ONE. The keys are not spelled here: they arrive
+ *  from `l3/basecse.ts`, whose `leafId`/`keyOf` render a leaf base as `c:<const>` wherever it is
+ *  not a named `a:<sym>`, and `homeSplitTag` above prints that half as `0x…`. (This module's own
+ *  `leafBaseId`, BELOW, is a different reader — it identifies bases inside
+ *  `baseReads`/`splitHomeBases` and never produces the argument.) So a tree lifted with NO map
+ *  reaches this door on plain addresses: enumerated map-less, `EntityHitReaction` in the klonoa
+ *  `code_1` checkout yields 512 `/homesplit` candidates over 512 distinct sources, keyed
+ *  `0x3004c20.1u` and `0x40000d4.4s` — TWO numeric keys. "No map, so this product cannot fire" is
+ *  therefore a fact about whichever function was censused, not about the arm, and a skip built on
+ *  it deletes live candidates. */
+export function homeSplitWithholds(
+  keys: readonly string[],
+  admission: readonly Gate<HomeSplitFanCtx>[] = HOMESPLIT_FAN_GATES,
+): readonly string[] {
+  return firstRejection(admission, { hoistableKeys: keys.length }) === null ? keys : [];
+}
+
+export interface HomeSplitOpts {
+  /** the caller's own admission table — `/livebase-block`'s on the roster row that pairs */
+  readonly gates: readonly Gate<BaseKey>[];
+  readonly placement: HoistPlacement;
+  /** the key withheld from the head hoist, in `l3/basecse.ts` vocabulary */
+  readonly key: string;
+  readonly deviceRegisters?: readonly [number, number];
+  readonly admission?: readonly Gate<HomeSplitCtx>[];
+}
+
+/** A leaf deref base's identity, ignoring the access width — `l3/basecse.ts`'s spelling of it,
+ *  taken from that module rather than re-spelled here, and `null` for every other base kind. */
+const leafBaseId = (b: Expr): string | null => (b.k === 'const' || b.k === 'addr' ? leafId(b) : null);
+
+/** Every leaf-based READ in the tree, by base identity — an access reached anywhere but as a
+ *  store's own lvalue. A store's lvalue is what `/vol-store` can still qualify; nothing else is. */
+function baseReads(body: Stmt[], out: Set<string>): void {
+  const visit = (e: Expr): void => {
+    if (e.k === 'index') {
+      const id = leafBaseId(e.base);
+      if (id !== null) {
+        out.add(id);
+      }
+    }
+    exprChildren(e).forEach(visit);
+  };
+  const walk = (s: Stmt): void => {
+    for (const e of stmtExprs(s)) {
+      // a store's LVALUE is the one position `/vol-store` reaches, so it is not a read
+      if (s.k === 'store' && e === s.lval) {
+        exprChildren(e).forEach(visit);
+        continue;
+      }
+      visit(e);
+    }
+    if (s.k === 'for') {
+      // `init` and `inc` are STATEMENTS, reached by neither `stmtExprs` nor `stmtLists` — the same
+      // walker asymmetry `l3/scopebase.ts`'s `collect` calls out. A read missed here is a device
+      // read the rule below cannot see.
+      walk(s.init);
+      walk(s.inc);
+    }
+    for (const child of stmtLists(s)) {
+      child.forEach(walk);
+    }
+  };
+  body.forEach(walk);
+}
+
+/**
+ * The pairing for ONE withheld key: the tree with every OTHER admitted base homed at `placement`,
+ * and the withheld one split per region. `homed` is the intermediate — the caller re-checks the
+ * placement differential across the pipe with it. Null when a rule refuses, or when either half
+ * declines.
+ */
+export function splitHomeBases(sfn: SFn, opts: HomeSplitOpts): { homed: SFn; split: SFn } | null {
+  const gates = opts.admission ?? HOMESPLIT_GATES;
+  // `null` only at `placement: 'scope'` (l3/basecse.ts), and no PAIRING roster row sits at that
+  // placement today — so this is a guard rather than a path.
+  const homed = hoistBaseLocals(sfn, withholdingKey(opts.gates, opts.key), opts.placement);
+  if (homed === null) {
+    return null;
+  }
+  // The withheld key in the REGION pass's vocabulary. The two passes key on the same address but
+  // spell an `addr` base's identity differently, so the translation is explicit — a string compare
+  // across them would silently never match for an `addr` base. A CAST base (an array-of-struct
+  // element's `(struct S *)&gSym`) has no spelling in the region pass at all — its `LeafBase` is
+  // the leaf kinds only — so it translates to nothing and the pairing declines, which is the same
+  // answer the region planner would have given.
+  const meta = baseSites(sfn).get(opts.key);
+  const scoped = meta && meta.base.k !== 'cast' ? scopedBaseKey(meta.base, meta.width, meta.signed) : null;
+  // ONE plan, then its applier — the count below and the rewrite read the same decision rather than
+  // two runs of the planner that a future rule could make disagree.
+  const plan = planScopedBases(homed, { regions: 'per-region' });
+  const split = plan.entries.filter((e) => e.key === scoped).length;
+  const out = applyScopedBasePlan(homed, plan);
+  // Judged on the SPLIT tree, which is the only one that answers the question: an access the region
+  // rule repoints into a minted local is one `/volatile` covers, and on `homed` it is still inline.
+  const reads = new Set<string>();
+  baseReads((out ?? homed).body, reads);
+  const base = meta?.base ?? null;
+  const id = base ? leafBaseId(base) : null;
+  if (
+    firstRejection(gates, {
+      withheldSplits: split >= 2,
+      inlineDeviceRead:
+        id !== null &&
+        base !== null &&
+        volatileEligibleValue(base) &&
+        inRange(addrConst(base), opts.deviceRegisters) &&
+        reads.has(id),
+    }) !== null
+  ) {
+    return null;
+  }
+  if (out === null) {
+    if (split >= 2) {
+      // `homesplit-no-region` admitted two or more entries for the withheld key, so the plan is
+      // neither empty nor compound and the applier cannot decline. Loud rather than silent.
+      throw new Error(`homesplit: the region plan splits ${opts.key} ${split} ways and the applier declined`);
+    }
+    // With that rule ABLATED (`without(HOMESPLIT_GATES, …)`) its premise is gone, and an ablation
+    // that converts a decline into a throw prices the rule at every dropped candidate instead of
+    // at the spelling it keeps out. A decline is the honest answer on that path.
+    return null;
+  }
+  return { homed, split: out };
+}

package/src/l3/initfirst.ts

@@ -0,0 +1,301 @@
+// L3 re-spelling lever: a loop INIT moves above the guard that encloses it, and the guard reads
+// the initialized variable.
+//
+// `for (i = 0; i < n; i++)` compiles with the init BEFORE the zero-trip test (`mov r3,#0` then
+// `cmp r3, r5`), while `if (0 < n) { i = 0; do … }` compiles with the init behind the branch.
+// Both source forms lift to the SAME IR — a const has no position — so which the original spelled
+// is not recoverable; this lever emits the init-first sibling and the differ referees:
+//
+//     if (0 < n) { v = 0; … }   →   v = 0; if (v < n) { … }
+//
+// Two rewrites (the guard re-spelling gated on the moved write being dead — see SCOPE):
+//   • common-arm hoist — both arms of an `if` begin with the SAME pure-const assign
+//     (`if (c) { v = 0; } else { v = 0; … }`, gcc's inverted-guard shape): the assign moves above
+//     the `if`, and an emptied then-arm flips into its negated else form.
+//   • guard re-spelling — an else-less `if` whose then-arm begins with `v = X` and whose
+//     condition carries X ITSELF as a comparison side: the assign moves above and that side
+//     becomes `v`. X is a const (`for (j = 0; j < n;…)`'s shape) or a pure NON-VOLATILE read
+//     (`for (j = *p; j < size;…)` — guard and init read the same cell back to back, which the
+//     local-spelling source reads ONCE; collapsing the adjacent pair is what the compiler saw).
+//
+// SCOPE (decline over approximate): both rewrites touch PRIVATE locals only — a bare-global
+// assign stores memory other code observes, a VOLATILE local's store is itself observable (the
+// escaped DMA scratch), and a local whose ADDRESS is taken anywhere can be read through the
+// pointer where no name betrays it — all three stay put. The common-arm hoist carries pure
+// CONST values only. A guard re-spell's X must be call-free and marker-free, may mention only
+// the function's own non-volatile params/locals (a global or `&gSym` could be project-declared
+// volatile, and a volatile read may not be deduplicated), and the substitution must PRESERVE
+// THE COMPARE'S MEANING: the variable's declared type can differ from X's rendered type, so the
+// swap is admitted only when both sides were provably non-negative (every signedness reading
+// agrees there) or the compare's rendered signedness is unchanged — anything indeterminate
+// refuses. The condition must not read the variable (its pre-assign value dies in the move)
+// and, for a READ X, must be effect-free as a whole (the hoist moves X's read above it). The
+// guard re-spelling
+// mints a write on a previously write-free path, so it needs that write to be DEAD there: the
+// variable must be untouched after the `if` in its own list and in the tail of every ancestor
+// list (a sibling arm of an ancestor `if` is not "after" — it never runs in the same entry).
+// Under a loop or switch ancestor the tails stop describing what runs next (a back edge
+// 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';
+
+const readsVar = (e: Expr, name: string): boolean =>
+  ((e.k === 'var' || e.k === 'addr') && e.name === 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.
+const stmtTouches = (s: Stmt, name: string): boolean =>
+  stmtExprs(s).some((e) => readsVar(e, name)) || stmtChildren(s).some((x) => stmtTouches(x, name));
+
+const isConstAssign = (s: Stmt): s is Extract<Stmt, { k: 'assign' }> & { value: { k: 'const'; value: number } } =>
+  s.k === 'assign' && s.value.k === 'const';
+
+/** Peel value-preserving `(s32)`/`(u32)` casts. Width 32 only: a narrower target truncates. A
+ *  `volatile` cast is never peeled — the qualifier is the access's meaning, and the differ cannot
+ *  referee its loss. */
+const stripWideIntCast = (e: Expr): Expr =>
+  e.k === 'cast' && e.to.kind === 'int' && e.to.width === 32 && e.volatile !== true ? stripWideIntCast(e.e) : e;
+
+/** Every deref rooted at a var through casts only. The var-root rule is a TWO-WORLD argument, not a
+ *  volatility proof: a deref through a plain-declared pointer local may still be MMIO, but the
+ *  /volatile axis enumerates the qualified sibling — where this lever refuses — so both worlds reach
+ *  the differ and collapsing reads here is the plain world's own premise. A raw `*(u16 *)CONST` deref
+ *  has NO local for /volatile to qualify, so no sibling carries the volatile world and the collapse
+ *  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`. */
+const hoistableRead = (e: Expr, ownNames: ReadonlySet<string>, volatileLocals: ReadonlySet<string>): boolean => {
+  if (e.k === 'call' || e.k === 'marker' || e.k === 'addr') {
+    return false;
+  }
+  if (e.k === 'var' && (!ownNames.has(e.name) || volatileLocals.has(e.name))) {
+    return false;
+  }
+  if ((e.k === 'index' || e.k === 'field') && !varRooted(e.base)) {
+    return false;
+  }
+  return exprChildren(e).every((c) => hoistableRead(c, ownNames, volatileLocals));
+};
+
+/** 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.
+ *  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
+ *  NARROWING cast changes the value and never matches, and a `volatile` one is not peeled at all. */
+const sameValue = (a: Expr, b: Expr): boolean => exprEquals(stripWideIntCast(a), stripWideIntCast(b));
+
+/** The compare-meaning gate (see SCOPE): substituting `v` for X may change the compare's
+ *  rendered signedness through v's declared type. Sufficiency: v's declared width must be 32
+ *  (the assignment `v = X` then represents any 32-bit-or-narrower X exactly, so v's runtime
+ *  value EQUALS X's — a narrow-declared v would truncate and no signedness reasoning survives
+ *  that), and then (a) both original sides provably in [0, 2^31) ⇒ signed and unsigned
+ *  compares agree on the actual values whatever the swap does to rendered signedness; (b)
+ *  otherwise a defined, UNCHANGED rendered signedness over equal values gives the identical
+ *  result. Anything indeterminate refuses. */
+const meaningPreserved = (
+  l: Expr,
+  r: Expr,
+  side: 'l' | 'r',
+  v: string,
+  env: ReturnType<typeof declaredTypes>,
+): boolean => {
+  const vt = env(v);
+  if (vt?.kind !== 'int' || vt.width !== 32) {
+    return false;
+  }
+  if (provablyNonNegative(l, env) && provablyNonNegative(r, env)) {
+    return true;
+  }
+  const before = arithConversionSignedness(l, r, env);
+  const vv: Expr = { k: 'var', name: v };
+  const after = side === 'l' ? arithConversionSignedness(vv, r, env) : arithConversionSignedness(l, vv, env);
+  return before !== undefined && before === after;
+};
+
+/** 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. */
+const touchesOutside = (list: Stmt[], skip: Stmt, name: string): boolean =>
+  list.some(
+    (st) =>
+      st !== skip &&
+      (stmtExprs(st).some((e) => readsVar(e, name)) ||
+        (st.k === 'assign' && st.name === name) ||
+        touchesOutside(stmtChildren(st), skip, name)),
+  );
+
+/** Every name whose ADDRESS this function takes anywhere — a local read through the captured
+ *  pointer with no name in sight. */
+function addressTakenNames(sfn: SFn): Set<string> {
+  const taken = new Set<string>();
+  for (const e of walkExprs(sfn.body)) {
+    if (e.k === 'addr') {
+      taken.add(e.name);
+    }
+  }
+  return taken;
+}
+
+export function initFirstGuards(sfn: SFn): SFn | null {
+  let changed = false;
+  // the names both rewrites may move a write of: this function's params and its non-volatile
+  // locals, minus everything whose address escapes
+  const addressTaken = addressTakenNames(sfn);
+  const fnLocal = new Set(
+    [...sfn.params.map((d) => d.name), ...sfn.locals.filter((l) => l.volatile !== true).map((l) => l.name)].filter(
+      (n) => !addressTaken.has(n),
+    ),
+  );
+  const volatileLocals = new Set(
+    sfn.locals.filter((l) => l.volatile === true || l.pointeeVolatile === true).map((l) => l.name),
+  );
+  const ownNames = new Set([...sfn.params.map((p) => p.name), ...sfn.locals.map((l) => l.name)]);
+  const env = declaredTypes(sfn);
+
+  // `tails`: for each ancestor list, the statements after the ancestor on the path here.
+  // `strong`: a loop or switch ancestor exists, so tails stop bounding what runs after.
+  interface Ctx {
+    tails: Stmt[][];
+    strong: boolean;
+  }
+  // Assigns this pass itself hoisted to an arm head's parent list. An ancestor `if` whose arm now
+  // BEGINS with one would otherwise re-spell it again — rewriting its own condition's accidental
+  // matching const into the variable and stealing the arrangement the inner guard needed.
+  const moved = new Set<Stmt>();
+  const rewriteList = (list: Stmt[], ctx: Ctx): Stmt[] => {
+    const out: Stmt[] = [];
+    for (let i = 0; i < list.length; i++) {
+      const s0 = list[i];
+      const s = recurse(s0, { tails: [...ctx.tails, list.slice(i + 1)], strong: ctx.strong });
+      if (s.k !== 'if') {
+        out.push(s);
+        continue;
+      }
+      let { cond, then, else: els } = s;
+      // common-arm hoist
+      const hoisted: { name: string; value: number }[] = [];
+      for (;;) {
+        const t0 = then[0];
+        const e0 = els[0];
+        if (
+          t0 === undefined ||
+          e0 === undefined ||
+          moved.has(t0) ||
+          moved.has(e0) ||
+          !isConstAssign(t0) ||
+          !isConstAssign(e0) ||
+          !fnLocal.has(t0.name) ||
+          t0.name !== e0.name ||
+          t0.value.value !== e0.value.value ||
+          readsVar(cond, t0.name)
+        ) {
+          break;
+        }
+        out.push(t0);
+        moved.add(t0);
+        hoisted.push({ name: t0.name, value: t0.value.value });
+        changed = true;
+        then = then.slice(1);
+        els = els.slice(1);
+      }
+      if (then.length === 0 && els.length > 0) {
+        const neg = cond.k === 'bin' ? NEGATE_REL[cond.op] : undefined;
+        if (neg !== undefined && cond.k === 'bin') {
+          cond = { ...cond, op: neg };
+          [then, els] = [els, then];
+          changed = true;
+        }
+      }
+      // 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.
+      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 } };
+          } else if (cond.r.k === 'const' && cond.r.value === hv.value) {
+            cond = { ...cond, r: { k: 'var', name: hv.name } };
+          }
+        }
+      }
+      // guard re-spelling — X a const or a hoistable read, matched as a whole comparison side
+      if (
+        els.length === 0 &&
+        then.length > 0 &&
+        then[0].k === 'assign' &&
+        !moved.has(then[0]) &&
+        fnLocal.has(then[0].name) &&
+        cond.k === 'bin' &&
+        NEGATE_REL[cond.op]
+      ) {
+        const init = then[0];
+        const rest = list.slice(i + 1);
+        const side =
+          isConstAssign(init) || hoistableRead(init.value, ownNames, volatileLocals)
+            ? sameValue(cond.l, init.value)
+              ? ('l' as const)
+              : sameValue(cond.r, init.value)
+                ? ('r' as const)
+                : null
+            : null;
+        const deadAfter = ctx.strong
+          ? !touchesOutside(sfn.body, s0, init.name)
+          : !rest.some((t) => stmtTouches(t, init.name)) &&
+            ctx.tails.every((tail) => !tail.some((t) => stmtTouches(t, init.name)));
+        if (
+          side !== null &&
+          !readsVar(cond, init.name) &&
+          deadAfter &&
+          // A READ X's hoist moves its evaluation ABOVE the whole condition, so the condition must
+          // carry no effect it could cross (a call there could write the cell X reads); a CONST
+          // init crosses nothing and keeps the wider admission.
+          (isConstAssign(init) || !exprHasEffect(cond)) &&
+          meaningPreserved(cond.l, cond.r, side, init.name, env)
+        ) {
+          out.push(init);
+          moved.add(init);
+          cond = { ...cond, [side]: { k: 'var', name: init.name } };
+          then = then.slice(1);
+          changed = true;
+        }
+      }
+      out.push({ ...s, cond, then, else: els });
+    }
+    return out;
+  };
+
+  const recurse = (s: Stmt, ctx: Ctx): Stmt => {
+    const strong = { ...ctx, strong: true };
+    switch (s.k) {
+      case 'if':
+        return { ...s, then: rewriteList(s.then, ctx), else: rewriteList(s.else, ctx) };
+      case 'while':
+      case 'dowhile':
+        return { ...s, body: rewriteList(s.body, strong) };
+      case 'for':
+        return { ...s, body: rewriteList(s.body, strong) };
+      case 'switch':
+        return {
+          ...s,
+          cases: s.cases.map((c) => ({ ...c, body: rewriteList(c.body, strong) })),
+          ...(s.default ? { default: rewriteList(s.default, strong) } : {}),
+        };
+      default:
+        return s;
+    }
+  };
+
+  const body = rewriteList(sfn.body, { tails: [], strong: false });
+  return changed ? { ...sfn, body } : null;
+}