@asmlift/core 0.7.0 → 0.8.0

package/src/raise/retsink.ts

@@ -239,7 +239,7 @@
 //
 // This does NOT recover the boolean-VALUE form `return a && b` — that is shortcircuit.ts's job
 // (the `logic_and`/`logic_or` connective plus agbcc's `(-b|b)>>31` = `b!=0` normalisation).
-import { Block, Fn, Op, Value, defOpMap, isBodyless, mkOp, predecessors, terminator } from '../ir/core';
+import { Block, Fn, Op, Value, defOpMap, fallThroughOf, isBodyless, mkOp, predecessors, terminator } from '../ir/core';
 import { NEGATED_ICMP } from '../ir/opcodes';
 import { simplifyTrivialPhis } from '../ir/simplify';
 import { type Gate, firstRejection } from '../l3/gates';
@@ -645,9 +645,13 @@ export function sinkReturns(
       continue;
     }
     for (const p of brPreds) {
-      const args = p.ops[p.ops.length - 1].successors[0].args;
-      const sunk = ret.operands.map((o) => args[m.params.indexOf(o)]);
-      p.ops[p.ops.length - 1] = mkOp('ret', { operands: sunk });
+      const t = p.ops[p.ops.length - 1];
+      const sunk = ret.operands.map((o) => t.successors[0].args[m.params.indexOf(o)]);
+      // The `br` being replaced carries whether the machine BRANCHED to this epilogue or fell into
+      // it, which is what `structure/retspell.ts` reads. Sinking puts the return ON that edge, so
+      // the edge's fact travels with it; ask the new return block's in-edges instead and they answer
+      // how control reached the statements above the return, not how it reached the epilogue.
+      p.ops[p.ops.length - 1] = mkOp('ret', { operands: sunk, attrs: fallThroughOf(t) });
       changed = true;
     }
     // If no predecessor still branches to m (all were unconditional), it is unreachable — drop it.

package/src/raise/tailsink.ts

@@ -39,7 +39,16 @@
 // NO GATE: which copy stays shared is the follow's question, and whether a sunk function is worth
 // a candidate is rank.ts's, asked with the follow's own predicate (`hasDivergentSharedRet`) rather
 // than a copy of it here.
-import { type Block, type Fn, type Value, mkOp, predecessors, reachableBlocks, terminator } from '../ir/core';
+import {
+  type Block,
+  type Fn,
+  type Value,
+  fallThroughOf,
+  mkOp,
+  predecessors,
+  reachableBlocks,
+  terminator,
+} from '../ir/core';
 import { simplifyTrivialPhis } from '../ir/simplify';
 
 /** One edge that supplies the tail its arguments. `resolve` sends a value the tail reads to the
@@ -110,7 +119,13 @@ export function sinkStoreTails(fn: Fn): boolean {
     const body = tail.ops.slice(0, -1);
     for (const src of sources) {
       const copies = body.map((o) => mkOp('store', { operands: o.operands.map(src.resolve), attrs: { ...o.attrs } }));
-      src.from.ops.splice(src.from.ops.length - 1, 1, ...copies, mkOp('ret'));
+      // Carry the replaced edge's fall-through fact onto the duplicated `ret`, as `raise/retsink.ts`
+      // does. Only for a source that branches straight to the tail: seen THROUGH a forwarder the path
+      // is several edges and no one of them answers on its own, so the copy is left unmarked and
+      // read as a branch — the side that can never delete a return the object needs.
+      const t = src.from.ops[src.from.ops.length - 1];
+      const attrs = t.successors[0]?.block === tail ? fallThroughOf(t) : {};
+      src.from.ops.splice(src.from.ops.length - 1, 1, ...copies, mkOp('ret', { attrs }));
     }
     // By REACHABILITY, not predecessor count: the tail (unless a conditional edge keeps it) and
     // every forwarder on the way are left unreachable, however long the chain, and a forwarder's

package/src/rank-declare.ts

@@ -118,18 +118,16 @@ const DECL_RESERVED = new Set<string>([
 
 /** The emitter's own NAME GRAMMAR for storage it invents: parameters `a0, a1, …` (structure.ts
  *  names them positionally, so no rename can move one) and coalesced/temp locals `v0…`/`t0…`
- *  (structure.ts's `localNames` accepts exactly `/^[vt]\d+$/`). A pool or map symbol with one of
- *  these names cannot be declared beside the C that spells it — see the refusal in `refsOf`, which
- *  is the one that kills the spelling rather than the line.
+ *  (structure.ts's `localNames` accepts exactly `/^[vt]\d+$/`). A global the target names with one
+ *  of these names cannot be declared beside the C that spells it — see the refusal in `refsOf`,
+ *  which is the one that kills the spelling rather than the line.
  *
  *  Checked as a grammar IN ADDITION to the tree's own bound names, because the collision that
  *  matters is the one the tree cannot show: `localNames` DROPS a local whose name a written
  *  global already claims, so where the global is stored `tree.locals` is silent about it. The
- *  price is refusing a real global that happens to be named `v3` in a function that never mints
- *  one — measured at zero: over the benchmark corpus, in each row's own symbol world, no candidate
- *  references such a name, and no vendored symbol map on that sweep's checkouts contained one. The
- *  map's own name total is deliberately not quoted — it is a property of the checkouts the sweep
- *  ran over rather than of this repo, so nothing here can re-derive it. */
+ *  price is refusing a global the target names `v3` in a function that never mints one. A map
+ *  global the target does NOT name pays nothing: Pikmin's map holds `v0` and `v1`, the only
+ *  grammar names in any vendored map, and no Pikmin row references either. */
 const EMITTER_NAME = /^[avt]\d+$/;
 
 /** Why a name the candidate's tree references got NO declaration. Reported rather than silently
@@ -201,10 +199,13 @@ export function makeRefCollector(ctx: {
   accessFacts: ReadonlyMap<string, { width: number; signed: boolean }>;
   /** the project map alone — a name it does NOT know makes the ref a `synthesized` hypothesis */
   mapSymbols: ReadonlyMap<string, SymbolInfo> | undefined;
+  /** the globals the TARGET names — the pool/reloc names and the shapes the asm evidences, before
+   *  the map is unioned in */
+  targetNames: ReadonlySet<string>;
   /** reports a refusal at most once per (name, reason); the caller owns the dedup */
   refuse: (name: string, reason: RefusedDeclarationReason) => void;
 }): (tree: SFn) => { symbolRefs?: SymbolRef[] } {
-  const { declSymbols, accessFacts, mapSymbols, refuse } = ctx;
+  const { declSymbols, accessFacts, mapSymbols, targetNames, refuse } = ctx;
   return (tree: SFn): { symbolRefs?: SymbolRef[] } => {
     // The names THIS tree binds. Computed per tree because the emitter mints local names per
     // spelling — but the test below is NOT `bound` alone, and the difference is a wrong answer.
@@ -226,6 +227,13 @@ export function makeRefCollector(ctx: {
       // project trades nothing for — so the spelling dies here and `respellTree`'s catch reports it.
       // If every spelling of every tree dies, the row declines LOUDLY naming the collision.
       if (bound.has(r.name) || EMITTER_NAME.test(r.name)) {
+        // …but only a global the TARGET names can collide. A name that only the MAP supplies is a
+        // project global the function never touches, and the tree's `v0` is its own local: Pikmin
+        // holds `.sdata` statics named `v0` and `v1`, and refusing them killed every spelling of
+        // every function whose emitted C mints those locals.
+        if (!targetNames.has(r.name)) {
+          return [];
+        }
         refuse(r.name, 'emitter-name');
         throw new Error(
           `cannot spell '${tree.name}': the target names a global '${r.name}', which is a name the ` +

package/src/rank.ts

@@ -34,6 +34,7 @@ import { T } from './ir/types';
 import { verify } from './ir/verify';
 import { advancedBases } from './l3/advance';
 import { materializeArgBases } from './l3/argbase';
+import { argCopyCandidates } from './l3/argcopy';
 import type { LanguageBackend, SFn } from './l3/ast';
 import { type BaseKey, admittedBases, hoistBaseLocals } from './l3/basecse';
 import { armDisjointCandidates, coalesceCandidates } from './l3/coalesce';
@@ -846,14 +847,17 @@ export function enumerateCandidates(
   // spelling needs one, and the declaration a candidate spelling `gTbl[i]` cannot compile
   // without), and the project map, which knows more than either.
   const mapSymbols = baseOpts.symbols;
-  const declSymbols = new Map<string, SymbolInfo>([
-    ...bareGlobalSymbols(sharedLift),
-    ...sharedLiftShapes,
-    ...(mapSymbols ?? []),
-  ]);
+  const targetSymbols = new Map<string, SymbolInfo>([...bareGlobalSymbols(sharedLift), ...sharedLiftShapes]);
+  const declSymbols = new Map<string, SymbolInfo>([...targetSymbols, ...(mapSymbols ?? [])]);
   // The four per-enumeration constants named at the seam rather than captured across 60 lines of
   // closure (rank-declare.ts states why they belong on one object).
-  const refsOf = makeRefCollector({ declSymbols, accessFacts, mapSymbols, refuse });
+  const refsOf = makeRefCollector({
+    declSymbols,
+    accessFacts,
+    mapSymbols,
+    targetNames: new Set(targetSymbols.keys()),
+    refuse,
+  });
   // THE RESPELL SET, as a function whose PARAMETER LIST is the invariant the tree skip below
   // rests on: every source here is a pure function of the structured tree and this call's own
   // constants, so a tree an earlier structure setting already produced can only re-emit sources
@@ -1254,6 +1258,25 @@ export function enumerateCandidates(
       const v = regionVolatile();
       return v ? volStore(v) : null;
     });
+    /** The results of a multi-result variation, under the same guard `respell` gives a
+     *  single-result one: a throw costs this variation and nothing else. Run at statement level
+     *  instead, a throwing source takes the WHOLE row with it — `reportThrow` never runs, so the
+     *  DEFAULT candidate is lost too and the row goes `noncompile`. A multi-result source is a
+     *  `for`-loop subject rather than a thunk, which is why the guard is a helper and not a try
+     *  inside `respell`. */
+    const candidatesOf = (
+      variations: readonly Variation[],
+      from: () => SFn | null | undefined,
+      resultsOf: (s: SFn) => { merged: string; sfn: SFn }[],
+    ): { merged: string; sfn: SFn }[] => {
+      try {
+        const base = from();
+        return base ? resultsOf(base) : [];
+      } catch (e) {
+        reportThrow([...preRespellVariations, ...variations], e);
+        return [];
+      }
+    };
     /** One candidate per result of a multi-result variation, `name` applied to the result's own
      *  subject after `prefix`. */
     const respellEach = (
@@ -1265,19 +1288,8 @@ export function enumerateCandidates(
       if (!offeredOn(target, [...prefix, name])) {
         return;
       }
-      let results: { variations: readonly Variation[]; sfn: SFn }[] = [];
-      try {
-        const base = from();
-        results = (base ? resultsOf(base) : []).map((c) => ({
-          variations: [...prefix, withSubject(name, c.merged)],
-          sfn: c.sfn,
-        }));
-      } catch (e) {
-        reportThrow([...preRespellVariations, ...prefix, name], e);
-        return;
-      }
-      for (const c of results) {
-        respell(c.variations, () => c.sfn);
+      for (const c of candidatesOf([...prefix, name], from, resultsOf)) {
+        respell([...prefix, withSubject(name, c.merged)], () => c.sfn);
       }
     };
     respellEach(['scopebase'], 'coalesce', () => hoistScopedBases(sfn));
@@ -1630,6 +1642,20 @@ export function enumerateCandidates(
       respellEach(variations, 'coalesce', hoist, armDisjointCandidates);
       respellEach([...variations, 'volatile'], 'coalesce', volatiles, armDisjointCandidates);
     }
+    // `/argcopy` — a pointer parameter copied into a local for ONE region (l3/argcopy.ts): the
+    // copy frees the parameter's incoming register for that region, and every legal region is its
+    // own candidate.
+    //
+    // PAIRED WITH `/coalesce`, because a freed register is worth nothing until something takes it:
+    // on pokeemerald:SetMauvilleOldManLanguage the copy frees r5 and the counter shared between two
+    // switch arms is what moves into it, and neither spelling alone reaches the bytes.
+    if (offeredOn(target, ['argcopy'])) {
+      for (const c of candidatesOf(['argcopy'], () => sfn, argCopyCandidates)) {
+        const copied = withSubject('argcopy', c.merged);
+        respell([copied], () => c.sfn);
+        respellEach([copied], 'coalesce', () => c.sfn);
+      }
+    }
     // `/parkfirst` — incoming-argument parks lead the entry prefix (l3/parkfirst.ts): the
     // park's `mov` lifts to pure SSA aliasing, so its position is unrecoverable and the
     // default order is emission's. Both orders are emitted; the differ referees.

package/src/structure/retspell.ts

@@ -0,0 +1,95 @@
+// Which `return;` statements the SOURCE wrote, read off the assembly.
+//
+// A void `return;` is a control transfer to the epilogue, and a compiler spells one as an
+// unconditional `b <epilogue>`. So where the epilogue is a block of its OWN — nothing in it but the
+// `ret` — its in-edges are the ways the body ends, and only one kind of arrival is a statement:
+//
+//   - an unconditional branch instruction into it → a `return;` the source wrote.
+//   - FALLING into it                            → the body simply running out, which spells
+//                                                  nothing.
+//   - a conditional branch's own edge            → nothing either. Unoptimised code tests into a
+//                                                  BODY label and never into the epilogue, so a
+//                                                  `bxx` landing there is jump-optimisation having
+//                                                  rerouted a branch the source did not write — and
+//                                                  by then both spellings are one object anyway.
+//
+// The statement being decided is the one at the END of the body, so a fall-through in-edge normally
+// settles it: that edge is the body running out, and it wrote no `return;`. A branch in-edge
+// alongside it is a `return;`, just not this one — it ends an arm, and `l3/tailret.ts` may delete a
+// return only in TAIL position, so an arm the function continues past keeps its own. An arm that IS
+// in tail position is one the compiler must branch over regardless (the block laid out before the
+// epilogue is the one that falls in, and only one block can be), so its `return;` and its `}`
+// compile to the same instruction. That is what makes the answer safe per BLOCK.
+//
+// ONE KIND OF BRANCH IN-EDGE OVERRULES THE FALLING ONE: a branch out of an EMPTY block. That arm
+// holds nothing but the `return;`, so dropping it does not shorten a statement list, it flips the
+// branch sense — and the two senses are two different objects. Measured on `if (*p & 1) return; …`
+// at agbcc -O0: the sense that writes the `return;` is 40 bytes, `beq` over a `b <epilogue>`; the
+// flipped one is 36, `bne` over the body with no `b` at all. So that `b` is in the object because
+// the source wrote a `return;`, and the falling edge beside it licenses nothing.
+//
+// With no fall-through in-edge, a branch in-edge is the only evidence there is, and it says the
+// source wrote a `return;` — keep it. With neither, nothing reached the epilogue by a written
+// transfer at all and there is nothing to spell. NO in-edge at all says the same thing without
+// needing the epilogue to be a block of its own: a body that never branched anywhere ended by
+// running out. That is the single-block function, which on an OBJECT has no epilogue label to
+// split it — the shape the `.s` path never shows.
+//
+// A `ret` SUNK onto one edge (`raise/retsink.ts`, `raise/tailsink.ts`) carries that edge's own
+// fall-through fact and answers for itself, which beats anything its block's in-edges could say:
+// those are about reaching the statements above the return, not about reaching the epilogue. An
+// epilogue block that ALSO holds statements and did not come from sinking is not asked at all, for
+// the same reason.
+//
+// NOT DECIDED HERE: a `while` whose only exit branches straight to the epilogue. That `b` is the
+// loop's `}`, and the same instruction to the same address is what a trailing `return;` compiles to
+// — the two objects differ only by an empty forwarder block between them, which is a fact about
+// branch chains rather than about return spelling. It is kept, which is the side that can never
+// delete a return the object needs.
+//
+// The in-edges the reading is about are the ways the body ENDS, so only LIVE ones count. The thumb
+// frontend hands over unreachable blocks on purpose, and one laid out just before the epilogue would
+// otherwise contribute a fall-through no execution takes — deleting the `return;` every real edge
+// branched in with.
+//
+// This decides SPELLING only; `l3/tailret.ts` owns whether a marked return is safe to delete.
+import type { Block, Fn } from '../ir/core';
+import { predecessors, reachableBlocks } from '../ir/core';
+
+/** The arrival an in-edge stands for: a `return;` the source wrote, or the body running out. */
+const isWrittenBranch = (p: Block): boolean => {
+  const term = p.ops[p.ops.length - 1];
+  return term.opcode === 'br' && term.attrs.fallthrough !== true;
+};
+const isFallThrough = (p: Block): boolean => {
+  const term = p.ops[p.ops.length - 1];
+  return term.opcode === 'br' && term.attrs.fallthrough === true;
+};
+/** A branch out of an EMPTY block is an arm with nothing else in it: the `return;` it stands for is
+ *  the only statement that arm would hold, so it has nowhere else to live and is never dropped. */
+const isBareBranch = (p: Block): boolean => p.ops.length === 1 && isWrittenBranch(p);
+
+/** The blocks whose `ret` the assembly shows no `return;` for. */
+export function unspelledEpilogues(fn: Fn): Set<Block> {
+  const preds = predecessors(fn);
+  const live = reachableBlocks(fn);
+  const out = new Set<Block>();
+  for (const b of fn.blocks) {
+    const term = b.ops[b.ops.length - 1];
+    if (term?.opcode !== 'ret') {
+      continue;
+    }
+    const inEdges = (preds.get(b) ?? []).filter((p) => live.has(p));
+    // Nothing arrived here from anywhere: the body never left its one block, so it transferred
+    // control to no epilogue and spelled no `return;`.
+    if (inEdges.length === 0) {
+      out.add(b);
+      continue;
+    }
+    const fellIn = inEdges.some(isFallThrough) && !inEdges.some(isBareBranch);
+    if (term.attrs.fallthrough === true || (b.ops.length === 1 && (fellIn || !inEdges.some(isWrittenBranch)))) {
+      out.add(b);
+    }
+  }
+  return out;
+}

package/src/structure/structure.ts

@@ -93,6 +93,7 @@ import {
 import { makeLoopHazards, sunkCopyOverDroppedUndef, updateWriteSet } from './hazards';
 import { type NaturalLoop, analyzeLoops } from './loops';
 import { type NameMerge, coalesceNames } from './namecoalesce';
+import { unspelledEpilogues } from './retspell';
 import { type ArmExit, makeSwitchRecovery } from './switch-recover';
 
 // Lower a constant-offset memory access to its lvalue/rvalue Expr. If the base was recovered as a
@@ -446,7 +447,7 @@ function spellablePointee(
  *  materialised — and where the displacement carries it the cast spelling stands.
  *
  *  THAT CHANNEL DOES NOT SAY THE SOURCE NAMED THE MEMBER: a HOISTED BASE LOCAL materialises the
- *  same constant. Compiled at `TOOLCHAIN.agbccFlags` against `u8 unk8[6][8]`, all three of
+ *  same constant. Compiled at agbcc's canonical flags against `u8 unk8[6][8]`, all three of
  *  `gBlob->unk8[0][i]`, `u8 *p = (u8 *)gBlob->unk8; p[i]` and `u8 *p = (u8 *)gBlob + 8; p[i]` emit
  *  the identical `add r1, #0x8` · `add r1, r1, r0` · `ldrb r0, [r1]`, while `*((u8 *)gBlob + 8 + i)`
  *  and `((u8 *)gBlob + i)[8]` take the displacement — and the base-local form is a spelling three
@@ -1406,7 +1407,7 @@ export interface StructureOptions {
   // and a `switch` over the same values produce the SAME candidate and the differ never sees the
   // ladder — there is nothing in the fan for it to prefer.
   //
-  // The two spellings are different objects. Compiled at TOOLCHAIN.agbccFlags the same two-case
+  // The two spellings are different objects. Compiled at agbcc's canonical flags the same two-case
   // body is 20 bytes either way (0x14, ten Thumb instructions — the pair is committed as
   // `corpus/agbcc-sw{frontload,ladder}.s`) and disagrees instruction for instruction: the `switch` emits
   // `cmp #0x1e; beq` then `cmp #0x64; bne` — both tests ahead of both bodies, and sorted ASCENDING,
@@ -4394,6 +4395,10 @@ export function structure(fn: Fn, opts: StructureOptions = {}, hooks: StructureH
   // Branch-sense sites, numbered as the walk below first reaches them (`branchSenseFlipSites`).
   const senseOrdinal = new Map<number, number>();
 
+  // Which `return;` statements the SOURCE wrote — the reading, and why it is decidable, live in
+  // `structure/retspell.ts`. `l3/tailret.ts` owns whether a marked return is safe to delete.
+  const unspelledRets = unspelledEpilogues(fn);
+
   const structureRegion = (b: Block, stop: Block | null): Stmt[] => {
     if (b === stop) {
       return [];
@@ -4456,7 +4461,11 @@ export function structure(fn: Fn, opts: StructureOptions = {}, hooks: StructureH
     const term = b.ops[b.ops.length - 1];
     if (term.opcode === 'ret') {
       // A void function's `bx lr` leaves whatever in r0; suppress that phantom return value.
-      out.push({ k: 'return', value: returnsVoid || !term.operands.length ? undefined : expr(term.operands[0]) });
+      const value = returnsVoid || !term.operands.length ? undefined : expr(term.operands[0]);
+      // The `value === undefined` half is a GUARD: `l3/tailret.ts` re-checks it before deleting
+      // anything, so marking a value-carrying return would change no output. The mark claims the asm
+      // shows no `return;` STATEMENT here, which is a claim about a VOID return only.
+      out.push({ k: 'return', value, ...(value === undefined && unspelledRets.has(b) ? { unspelled: true } : {}) });
       return out;
     }
     if (term.opcode === 'br') {

package/src/structure/switch-recover.ts

@@ -900,7 +900,7 @@ export function makeSwitchRecovery(deps: SwitchRecoverDeps): SwitchRecovery {
     // WHY BLOCK IDENTITY IS THE KEY, and not a body-equality one like `sameBareExit` above. agbcc
     // MERGES two written-out copies into one block — target.ts's `switchArmsFollowLayout` note
     // says so from agbcc's own sources, SRCS compiling jump.c — and compiling both directions at
-    // TOOLCHAIN.agbccFlags says WHERE the merged block lands: at the last copy's position. So
+    // agbcc's canonical flags says WHERE the merged block lands: at the last copy's position. So
     // `case 0: A break; case 1: … case 2: A break;` and the grouped arm placed THERE are one
     // object (.text md5 555abb1a), while the grouped arm placed at the first value is not
     // (fe4d7d35). That is why the grouped spelling round-trips rather than merely reading shorter: