@asmlift/core 0.4.0 → 0.6.0

package/src/l3/dce.ts

@@ -15,8 +15,11 @@
 // read as live throughout), so a removal only happens when the local is provably dead. Only
 // names in `locals` are eligible — globals (side effects, referenced by name from headers) and
 // params are never touched — and a value carrying a side effect / gap signal / memory load is
-// never dropped (see `mustKeep`). Locals are never address-taken in L3 (`addr` names a global),
-// so `var` reads are a COMPLETE account of a local's uses.
+// never dropped (see `mustKeep`). An `addr` node can now name a LOCAL as well as a global (the
+// frame-local object a Thumb `laddr` declares — structure.ts), and an address-taken local's stores
+// are observable through the escaped pointer whether or not any `var` read follows — so an `addr`
+// name counts as a READ below, which pins the local and every store to it. For globals that is a
+// no-op (they were never eligible), so the single rule covers both.
 //
 // Ordering: structureChecked runs `assertResolved` BEFORE this pass, so in strict mode an
 // unresolved `?` value trips the contract first and never reaches DCE; `mustKeep` treating `?` as
@@ -25,9 +28,10 @@ import type { Expr, SFn, Stmt } from './ast';
 import { exprChildren, negateCond, stmtChildren, stmtExprs } from './ast';
 
 /** Accumulate every LOCAL-eligible `var` name read anywhere in `e` (recurses all sub-exprs). An
- *  `addr` node names a global, not a local, so it is not a local read. */
+ *  `addr` name counts too: taking a local's address makes every store to it observable through the
+ *  escaped pointer, so an address-taken local is never dead here. */
 function readsInto(e: Expr, out: Set<string>): void {
-  if (e.k === 'var') {
+  if (e.k === 'var' || e.k === 'addr') {
     out.add(e.name);
   }
   for (const c of exprChildren(e)) {
@@ -46,17 +50,19 @@ function reads(e: Expr): Set<string> {
  *   - `marker` — the annotate-mode ASMLIFT_ERROR gap signal, which must survive so the gap stays loud;
  *   - the strict-mode `?` unresolved sentinel (`{k:'var', name:'?'}`) — dropping it would let a
  *     value asmlift could NOT lift slip past `assertResolved`, silently downgrading a loud gap;
- *   - a memory load (`index`/`field`) — asmlift models no `volatile`, so a possibly-effectful read
+ *   - a memory load (`index`/`field`) — a deref's volatility is unknowable here, so a possibly-effectful read
  *     is never deleted (this pass never removes a memory access).
+ *   - a read of a VOLATILE local (the frame object whose address escaped) — a volatile read is an
+ *     observable access the machine performed; deleting the dead assignment would delete the read.
  *  A dead assignment whose value contains any of these is kept. */
-function mustKeep(e: Expr): boolean {
+function mustKeep(e: Expr, volatiles: ReadonlySet<string>): boolean {
   if (e.k === 'call' || e.k === 'marker' || e.k === 'index' || e.k === 'field') {
     return true;
   }
-  if (e.k === 'var' && e.name === '?') {
+  if (e.k === 'var' && (e.name === '?' || volatiles.has(e.name))) {
     return true;
   }
-  return exprChildren(e).some(mustKeep);
+  return exprChildren(e).some((c) => mustKeep(c, volatiles));
 }
 
 /** Every local read anywhere within these statements (exprs + nested statements). Used to give
@@ -70,12 +76,32 @@ function allReadsInto(stmts: Stmt[], out: Set<string>): void {
   }
 }
 
+/** Every name whose ADDRESS is taken anywhere within these statements. Globals land here too and
+ *  are harmless — they were never store-eligible. */
+function allAddrNamesInto(stmts: Stmt[], out: Set<string>): void {
+  const walk = (e: Expr) => {
+    if (e.k === 'addr') {
+      out.add(e.name);
+    }
+    for (const c of exprChildren(e)) {
+      walk(c);
+    }
+  };
+  for (const s of stmts) {
+    for (const e of stmtExprs(s)) {
+      walk(e);
+    }
+    allAddrNamesInto(stmtChildren(s), out);
+  }
+}
+
 /** Backward live-variable walk over one block. `liveOut` is the set of locals live on exit;
  *  returns the rewritten block and the set live on entry. */
 function dceBlock(
   stmts: Stmt[],
   liveOut: ReadonlySet<string>,
   locals: ReadonlySet<string>,
+  volatiles: ReadonlySet<string>,
 ): { out: Stmt[]; liveIn: Set<string> } {
   const live = new Set(liveOut);
   const rev: Stmt[] = [];
@@ -89,7 +115,7 @@ function dceBlock(
     const s = stmts[i];
     switch (s.k) {
       case 'assign': {
-        if (locals.has(s.name) && !live.has(s.name) && !mustKeep(s.value)) {
+        if (locals.has(s.name) && !live.has(s.name) && !mustKeep(s.value, volatiles)) {
           continue; // dead local store — drop it; liveness is unchanged (it was a no-op)
         }
         live.delete(s.name); // the write kills the name for statements before it …
@@ -131,8 +157,8 @@ function dceBlock(
         break;
       }
       case 'if': {
-        const t = dceBlock(s.then, live, locals);
-        const e = dceBlock(s.else, live, locals);
+        const t = dceBlock(s.then, live, locals, volatiles);
+        const e = dceBlock(s.else, live, locals, volatiles);
         const nlive = new Set<string>();
         for (const r of reads(s.cond)) {
           nlive.add(r);
@@ -146,7 +172,7 @@ function dceBlock(
         setLive(nlive);
         if (t.out.length === 0 && e.out.length === 0) {
           // both arms empty: keep only if the condition itself has a side effect
-          if (mustKeep(s.cond)) {
+          if (mustKeep(s.cond, volatiles)) {
             rev.push({ k: 'exprstmt', value: s.cond });
           }
         } else if (t.out.length === 0) {
@@ -162,7 +188,7 @@ function dceBlock(
         // loop-carried store is never cut. Body DCE removes only what is dead on EVERY path.
         const loopLive = new Set(live);
         allReadsInto([s], loopLive);
-        const b = dceBlock(s.body, loopLive, locals);
+        const b = dceBlock(s.body, loopLive, locals, volatiles);
         const nlive = new Set(loopLive);
         for (const r of b.liveIn) {
           nlive.add(r);
@@ -174,7 +200,7 @@ function dceBlock(
       case 'for': {
         const loopLive = new Set(live);
         allReadsInto([s], loopLive);
-        const b = dceBlock(s.body, loopLive, locals);
+        const b = dceBlock(s.body, loopLive, locals, volatiles);
         const nlive = new Set(loopLive);
         for (const r of b.liveIn) {
           nlive.add(r);
@@ -188,8 +214,8 @@ function dceBlock(
         // read anywhere in the switch as live throughout — no case-body store is ever cut.
         const swLive = new Set(live);
         allReadsInto([s], swLive);
-        const cases = s.cases.map((c) => ({ ...c, body: dceBlock(c.body, swLive, locals).out }));
-        const def = s.default ? dceBlock(s.default, swLive, locals).out : s.default;
+        const cases = s.cases.map((c) => ({ ...c, body: dceBlock(c.body, swLive, locals, volatiles).out }));
+        const def = s.default ? dceBlock(s.default, swLive, locals, volatiles).out : s.default;
         const nlive = new Set(swLive);
         for (const r of reads(s.scrutinee)) {
           nlive.add(r);
@@ -227,9 +253,18 @@ function referencedNames(stmts: Stmt[], out: Set<string>): void {
 /** Remove dead local stores and simplify the branches they empty out, then drop any local
  *  declaration left unreferenced. Returns a new SFn; the input is not mutated. */
 export function eliminateDeadStores(sfn: SFn): SFn {
-  const locals = new Set(sfn.locals.map((l) => l.name));
-  const body = dceBlock(sfn.body, new Set<string>(), locals).out;
+  // AN ADDRESS-TAKEN local is never eligible, whatever its qualifiers: every store to it is
+  // observable through the escaped pointer wherever it sits, and this walk is BACKWARD, so the
+  // `addr`-as-read pin above only ever protected the stores UPSTREAM of an `&sp0` occurrence.
+  // Publish-the-address-then-fill (`g(&sp0); sp0 = v;`) puts one downstream, and this very pass
+  // deleted it. `volatile` stays in the test beside it because the qualifier is a separate reason
+  // (an MMIO cell the frontend never rendered an `&` for), not a spelling of this one.
+  const addressTaken = new Set<string>();
+  allAddrNamesInto(sfn.body, addressTaken);
+  const volatiles = new Set(sfn.locals.filter((l) => l.volatile).map((l) => l.name));
+  const locals = new Set(sfn.locals.filter((l) => !l.volatile && !addressTaken.has(l.name)).map((l) => l.name));
+  const body = dceBlock(sfn.body, new Set<string>(), locals, volatiles).out;
   const used = new Set<string>();
   referencedNames(body, used);
-  return { ...sfn, body, locals: sfn.locals.filter((l) => used.has(l.name)) };
+  return { ...sfn, body, locals: sfn.locals.filter((l) => used.has(l.name) || l.volatile) };
 }

package/src/l3/gates.ts

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

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