@asmlift/core 0.5.0 → 0.6.0

package/src/l3/gates.ts

@@ -42,6 +42,27 @@ export function without<Ctx>(gates: readonly Gate<Ctx>[], id: string): readonly
   return gates.filter((g) => g.id !== id);
 }
 
+// NO `just(table, ids)` SELECTOR, deliberately. Selecting rule OBJECTS by id shares the predicate
+// AND the `sound` claim AND the `guardedBy` guard, and a second consumer of a rule wants only the
+// first of the three: a rule that is sound for a declaration is a heuristic for a generated
+// candidate, and the guard the contract test then checks ablates the rule against the OTHER
+// consumer. What a second consumer shares is a PREDICATE — an ordinary function — and what it owns
+// is its own rule objects. `ORDER_SHAPE_GATES` (raise/globalshape.ts) is the worked example, with
+// the over-admission id-selection would carry.
+
+/** `without` for SHIPPED code. A test may ablate any gate — that is how `guardedBy` differential
+ *  tests work — but a pass that re-runs itself with an ablated table as a ranked candidate may
+ *  only drop a HEURISTIC: ablating a `sound: true` gate would ship semantically wrong candidates,
+ *  and on a nonmatch row the best-scoring source is shown to the user. A derived table is a
+ *  top-level const, so the throw fires at import — the mistake cannot ship. */
+export function ablateHeuristic<Ctx>(gates: readonly Gate<Ctx>[], id: string): readonly Gate<Ctx>[] {
+  const g = gates.find((x) => x.id === id);
+  if (g?.sound) {
+    throw new Error(`gate '${id}' is sound — a shipped ablation of it emits wrong candidates`);
+  }
+  return without(gates, 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[] {

package/src/l3/hoist.ts

@@ -1,16 +1,20 @@
-// L3 — the naming MECHANISM shared by every pass that hoists a value into a fresh local.
+// L3 — the MECHANISMS a pass needs to place a hoisted local: how a fresh name is chosen, where the
+// leading run of base inits starts and ends, and where in the body that run goes.
 //
-// Two passes name bases today (`basecse.ts` hoists a REUSED base; `argbase.ts` names a call's
-// argument bases), and they differ in POLICY — which bases are eligible, and when it is worth
-// doing — but not in how a name is chosen. That half was copied, and the copy silently lost a
-// safety guard: basecse added the callee-name exclusion in its own audit precisely so a hoist
-// local could not shadow a called function, and the second implementation did not have it. A third
-// hoisting pass would lose it again, so the mechanism lives here and the policy stays with each
-// caller.
+// Their users differ. Every pass that mints a local takes `nameAllocator` (or `takenNames`, to
+// number its own); the three that touch basecse's leading init run read the rest — basecse and
+// nearbase mint into it, sinkinit moves statements out of it, and all three have to agree on where
+// it stops and how a body carrying it is rebuilt. What stays with each caller is ELIGIBILITY:
+// which values become a local at all, and when it is worth doing. WHERE the run goes is
+// `placeBaseLocals`'s `placement` argument, and that argument is two questions rather than one —
+// 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 { mapExprChildren, stmtChildren, stmtExprs } from './ast';
+import { exprChildren, mapStmtLists, stmtChildren, stmtExprs, stmtLists } from './ast';
+import { localMentions } from './mentions';
 
-/** Every identifier a hoist name must not collide with, anywhere in `sfn`.
+/** Every identifier a MINTED name must not collide with, anywhere in `sfn` — the hoists below,
+ *  and reindex's induction names.
  *
  *  Wider than "the declared locals" on purpose, and each addition is a real collision:
  *   - params and locals, obviously;
@@ -18,7 +22,7 @@ import { mapExprChildren, stmtChildren, stmtExprs } from './ast';
  *     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. */
-function takenNames(sfn: SFn): Set<string> {
+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') {
@@ -27,10 +31,9 @@ function takenNames(sfn: SFn): Set<string> {
     if (e.k === 'call') {
       taken.add(e.fn);
     }
-    mapExprChildren(e, (c) => {
+    for (const c of exprChildren(e)) {
       visit(c);
-      return c;
-    });
+    }
   };
   const walk = (stmts: Stmt[]): void => {
     for (const s of stmts) {
@@ -63,3 +66,279 @@ export function nameAllocator(sfn: SFn): () => string {
     return nm;
   };
 }
+
+export type BaseInit = Extract<Stmt, { k: 'assign' }>;
+
+/** Whether `s` is a BASE INIT: a ptr-cast of an `addr`/`const` leaf assigned into a declared
+ *  NON-VOLATILE local. It reads nothing and writes its own plain cell, which is what makes the run
+ *  of them re-orderable and each of them movable. The volatile exclusion is load-bearing — two
+ *  writes to `volatile` locals are observably ordered, so one at the head simply ends the run. */
+function isBaseInit(s: Stmt, plainLocals: ReadonlySet<string>): s is BaseInit {
+  return (
+    s.k === 'assign' &&
+    plainLocals.has(s.name) &&
+    s.value.k === 'cast' &&
+    s.value.to.kind === 'ptr' &&
+    (s.value.e.k === 'addr' || s.value.e.k === 'const')
+  );
+}
+
+/** `body` split at the end of its LEADING run of base inits — the run `placeBaseLocals` places. */
+function splitLeadingBaseInits(sfn: SFn, body: readonly Stmt[]): { inits: BaseInit[]; rest: Stmt[] } {
+  const plain = new Set(sfn.locals.filter((l) => !l.volatile).map((l) => l.name));
+  let n = 0;
+  while (n < body.length && isBaseInit(body[n], plain)) {
+    n++;
+  }
+  return { inits: body.slice(0, n) as BaseInit[], rest: body.slice(n) };
+}
+
+/** For each local, the index of the first TOP-LEVEL statement of `rest` that mentions it, absent
+ *  when none does. `mentions.ts`'s notion of a mention, so `&p` counts: an init must precede the
+ *  address being taken as surely as it must precede a read. */
+function firstUseIn(sfn: SFn, rest: readonly Stmt[]): Map<string, number> {
+  const out = new Map<string, number>();
+  for (const [name, m] of localMentions({ ...sfn, body: [...rest] })) {
+    if (m.firstAt !== null) {
+      out.set(name, m.firstAt);
+    }
+  }
+  return out;
+}
+
+/** Does `s` mention `name` in its OWN expressions or as its assignment target — nothing nested?
+ *  `mentions.ts`'s notion of a mention (`&p` counts), asked of one statement rather than of a
+ *  top-level index. */
+function mentionsHere(s: Stmt, name: string): boolean {
+  if (s.k === 'assign' && s.name === name) {
+    return true;
+  }
+  let found = false;
+  const visit = (e: Expr): void => {
+    if ((e.k === 'var' || e.k === 'addr') && e.name === name) {
+      found = true;
+    }
+    for (const c of exprChildren(e)) {
+      visit(c);
+    }
+  };
+  stmtExprs(s).forEach(visit);
+  return found;
+}
+
+/** …and the same question of the whole subtree. */
+function mentionsStmt(s: Stmt, name: string): boolean {
+  return mentionsHere(s, name) || stmtChildren(s).some((c) => mentionsStmt(c, name));
+}
+
+/** `{ list, at }` for a top-level first-use index, or null when there is none — the `first-use`
+ *  answer in the shape the `scope` one comes back in. */
+function mapTo(list: Stmt[], at: number | undefined): { list: Stmt[]; at: number } | null {
+  return at === undefined ? null : { list, at };
+}
+
+/** How many times each statement appears in `list`. */
+function tally(list: readonly Stmt[]): Map<Stmt, number> {
+  const out = new Map<Stmt, number>();
+  for (const s of list) {
+    out.set(s, (out.get(s) ?? 0) + 1);
+  }
+  return out;
+}
+
+/** The innermost statement list holding EVERY mention of `name`, and the index in it of the first
+ *  statement that mentions it. This is `firstUseIn` continued downward, and it descends only on
+ *  three facts: exactly one statement of this list mentions the name, that statement mentions it
+ *  nowhere OUTSIDE the lists it opens (its own condition, or a `for`'s `init`/`inc` — which are
+ *  statements no list holds), and exactly one of those lists holds it. Any of the three failing
+ *  means a nested list does not hold every mention, so this list is as deep as the init may go.
+ *  Stopping at the top level reproduces `first-use` exactly, which is what lets `scope` be a
+ *  placement rather than a second policy.
+ *
+ *  DOMINATION IS THE DESCENT'S OWN INVARIANT: every mention is at or after the returned index
+ *  within the returned list, so the init reaches all of them — including from inside a loop body,
+ *  where it simply re-assigns the same link-time constant. `hoistBaseLocals` still CHECKS it
+ *  (`assertHoistsDominate`), because an argument is not a check.
+ *
+ *  A LOOP BODY IS ALSO A LIST NO SHIPPED CANDIDATE CAN REACH, which is a stronger statement than
+ *  the safety argument above and the one that keeps re-assigning a base per iteration out of
+ *  published C. Every gate table any caller pairs with `scope` keeps `BASECSE_GATES`' `loop` rule —
+ *  `ORDERBASE_GATES`, the only roster table at this placement, ablates `cast-base` and `single-use`
+ *  and nothing else — so a base with ANY use inside a loop is refused before a placement is
+ *  consulted. Both halves are pinned in test/sinkinit.test.ts: neither table admits one, and where
+ *  the mechanism is handed such a base directly the tree it emits still dominates. Loop-body bases
+ *  are `l3/scopebase.ts`'s, which plans its own local rather than moving this run. */
+function scopeSite(list: Stmt[], name: string): { list: Stmt[]; at: number } | null {
+  const idxs = list.flatMap((s, i) => (mentionsStmt(s, name) ? [i] : []));
+  if (idxs.length === 0) {
+    return null;
+  }
+  const here = { list, at: idxs[0] };
+  if (idxs.length > 1) {
+    return here;
+  }
+  const s = list[idxs[0]];
+  const lists = stmtLists(s);
+  const inner = lists.filter((l) => l.some((x) => mentionsStmt(x, name)));
+  if (inner.length !== 1) {
+    return here;
+  }
+  // A MULTISET difference, not a set one: `stmtChildren` yields a `for`'s `init` and `inc` beside
+  // its body, and one `Stmt` object may sit at two tree positions. Subtracting by identity would
+  // read a shared `init` as opened and miss the mention it makes before the body ever runs.
+  const opened = tally(lists.flat());
+  const outside =
+    mentionsHere(s, name) ||
+    [...tally(stmtChildren(s))].some(([c, n]) => n > (opened.get(c) ?? 0) && mentionsStmt(c, name));
+  return outside ? here : (scopeSite(inner[0], name) ?? here);
+}
+
+/** WHERE a run of base inits sits, once this file has put it in FIRST-USE order — the order the
+ *  compiler loads the pool words in (`l3/basecse.ts`'s `collect`), so it is the order a reference
+ *  spelling that named these bases would have.
+ *
+ *  `head` keeps the whole ordered run at the top of the body.
+ *  `first-use` then moves each init down to immediately before the statement that first mentions
+ *  it, which is where a base reached ONCE was loaded and which keeps a base first touched halfway
+ *  down the body out of the live range above it.
+ *  `scope` reads that same query one nesting level at a time: an init whose every mention lives
+ *  inside ONE nested list goes inside that list, at the first mention there. `first-use` stops at
+ *  the top-level statement — a base used only inside an `if` arm still has its pool word loaded
+ *  above the branch — and on agbcc, whose statement order survives into the object, the two are
+ *  different bytes. Where no nested list holds every mention this IS `first-use`, which is what
+ *  makes it a placement rather than a second policy.
+ *
+ *  These three are the axis a roster admission may state (rank.ts) and the only values
+ *  `hoistBaseLocals` accepts. */
+export type HoistPlacement = 'head' | 'first-use' | 'scope';
+
+/** `HoistPlacement` plus the ABSTENTION: `prepend` puts the minted inits above a run that keeps
+ *  the order it arrived in, consulting neither the first-use query nor the sort. A third VALUE and
+ *  not a third position, passed only by `l3/nearbase.ts`, whose header carries the argument for it.
+ *
+ *  `hoistBaseLocals` may NOT be handed this: prepending there spells a newly minted base's pool
+ *  load above locals the compiler loads first (`l3/basecse.ts`'s own header), so the two passes
+ *  take different types rather than the same type and a comment. */
+export type BaseInitPlacement = HoistPlacement | 'prepend';
+
+/** `sfn.body` rebuilt with `minted` added to its leading base-init run and the whole run placed
+ *  per `placement`, plus which inits ended up away from the head.
+ *
+ *  `sfn` is both the statements and the DECLARATION ENVIRONMENT the first-use and mention queries
+ *  resolve against, so a caller that mints must pass a shell that already declares the new names
+ *  AND carries the rewritten body. One argument rather than two is the point: a shell whose
+ *  declarations and statements disagree is not expressible here.
+ *
+ *  ONE ORDER, THEN THE POLICY. Under both `HoistPlacement` values the run is put in FIRST-USE
+ *  order before `placement` is consulted — pool-load order, and what makes the two COMPOSABLE
+ *  rather than merely adjacent: `first-use` applied to a `head` result is `first-use` applied to
+ *  the input, so `/livebase/sinkinit` (a hoist at the head that a second pass then sinks) and
+ *  `/basefold/sinkinit` (one hoist placed at first use) are the same transform and the `/sinkinit`
+ *  suffix names one thing wherever it appears. Order the run only on the `head` branch and they
+ *  part company on the inits that CANNOT move, which is the half of the run whose order the
+ *  compiler still reads. Pinned in test/sinkinit.test.ts. `prepend` opts out of all of it.
+ *
+ *  Ties keep list order — existing inits before minted ones, and two inits assigning the SAME
+ *  local in their original sequence, which a stable sort is what guarantees: they write one cell,
+ *  so their order is the only thing that says which value it ends up holding. Two that SINK to the
+ *  same statement keep it too, which is what the splice loop's second sort key is for.
+ *
+ *  Under `first-use`, an init then moves down if the function assigns its local exactly ONCE (the
+ *  move would otherwise cross that other write), something in the remaining body mentions it, and
+ *  it is not already sitting at the first such statement.
+ *
+ *  IT REPORTS THE MOTION rather than its size, and its callers judge those lists instead of arguing
+ *  about them. `moved` names every init that left the leading run; `nested` is the subset that
+ *  landed in a list OTHER than the top-level one, which only `scope` can produce.
+ *
+ *  `nested` empty under `scope` means the placement DEGENERATED — every init went exactly where
+ *  `first-use` would have put it, so the emitted tree is that placement's spelling under a second
+ *  name. A caller offering placements as candidates has to know, or it enumerates one spelling
+ *  twice (l3/basecse.ts's `hoistBaseLocals`). */
+export function placeBaseLocals(
+  sfn: SFn,
+  minted: readonly BaseInit[],
+  placement: BaseInitPlacement,
+): { body: Stmt[]; moved: readonly string[]; nested: readonly string[] } {
+  const still = { moved: [], nested: [] };
+  const body = sfn.body;
+  const { inits: head, rest } = splitLeadingBaseInits(sfn, body);
+  if (head.length + minted.length === 0) {
+    return { body: [...body], ...still };
+  }
+  if (placement === 'prepend') {
+    return { body: [...minted, ...head, ...rest], ...still };
+  }
+  const firstUse = firstUseIn(sfn, rest);
+  const at = (s: BaseInit): number => firstUse.get(s.name) ?? rest.length;
+  const all = [...head, ...minted].sort((a, b) => at(a) - at(b));
+  if (placement === 'head') {
+    return { body: [...all, ...rest], ...still };
+  }
+  const whole = localMentions({ ...sfn, body: [...all, ...rest] });
+  const stay: BaseInit[] = [];
+  const sunk: { site: Stmt[]; at: number; init: BaseInit; i: number }[] = [];
+  for (const [i, init] of all.entries()) {
+    // Assigned exactly once, or the move would cross the other write.
+    const site =
+      whole.get(init.name)?.assigns === 1
+        ? placement === 'scope'
+          ? scopeSite(rest, init.name)
+          : mapTo(rest, firstUse.get(init.name))
+        : null;
+    // Nothing mentions it, or it is already sitting at the first statement of the top-level list:
+    // there is no move to make and the init stays in the leading run.
+    if (site === null || (site.list === rest && site.at === 0)) {
+      stay.push(init);
+    } else {
+      sunk.push({ site: site.list, at: site.at, init, i });
+    }
+  }
+  // Rebuild `rest` around the sink sites, matching each list by IDENTITY against the tree the sites
+  // were computed on — so the walk emits a fresh list only along the path to a site and hands every
+  // other statement back unchanged.
+  const bySite = new Map<Stmt[], typeof sunk>();
+  for (const s of sunk) {
+    bySite.set(s.site, [...(bySite.get(s.site) ?? []), s]);
+  }
+  const rebuild = (list: Stmt[]): Stmt[] => {
+    const here = bySite.get(list);
+    // CONSUMED: one `Stmt[]` object sitting at two tree positions takes the init at the FIRST of
+    // them, never at both, where a second splice would write the same local twice. `scopeSite`
+    // cannot return such a list — sharing means two statements mention the local, which stops the
+    // descent at their common list — so this restates that invariant where breaking it would be
+    // silent. Nothing in the L3 contract forbids the sharing itself (l3/scopebase.ts records a
+    // producer that shares an expression node).
+    bySite.delete(list);
+    let changed = here !== undefined;
+    const mapped = list.map((s) => {
+      let inner = false;
+      const out = mapStmtLists(s, (l) => {
+        const r = rebuild(l);
+        inner ||= r !== l;
+        return r;
+      });
+      changed ||= inner;
+      return inner ? out : s;
+    });
+    if (!changed) {
+      return list;
+    }
+    // Descending by target index, so an earlier insertion does not shift the position a later one
+    // was computed against — and descending among the inits SHARING a target too, because splicing
+    // each at the same index puts the last one spliced on top. Without that second key a run that
+    // sinks together comes out REVERSED, which is the one order this function exists to avoid: it
+    // is pool-load order the sort above is spelling, and `head` would have kept it.
+    for (const { at: to, init } of [...(here ?? [])].sort((a, b) => b.at - a.at || b.i - a.i)) {
+      mapped.splice(to, 0, init);
+    }
+    return mapped;
+  };
+  // `site !== rest` is the whole nesting question: every site is a list of the tree the sites were
+  // computed on, and the top-level one is `rest` by identity.
+  return {
+    body: [...stay, ...rebuild(rest)],
+    moved: sunk.map((s) => s.init.name),
+    nested: sunk.filter((s) => s.site !== rest).map((s) => s.init.name),
+  };
+}

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 };
+}