@asmlift/core 0.9.0 → 0.11.0

package/src/rank-variations.ts

@@ -24,10 +24,11 @@ import {
   ORDERBASE_GATES,
   UNFOLDED_GATES,
 } from './l3/basecse';
+import { jumpToCaseEnds } from './l3/caseendgoto';
 import type { Gate } from './l3/gates';
 import type { HoistPlacement } from './l3/hoist';
 import { initFirstGuards } from './l3/initfirst';
-import { narrowDeclarations, narrowReadDeclarations } from './l3/narrowdecl';
+import { narrowDeclarations, narrowLoadDeclarations, narrowReadDeclarations } from './l3/narrowdecl';
 import { pollGuards, pollReads } from './l3/pollguard';
 import { unmergeJoins } from './l3/unmerge';
 // TYPE-ONLY, and deliberately: the structure-variation table types its `options` as
@@ -55,7 +56,11 @@ import type { VariationName } from './variation-tokens';
  *  that setting's own lifted fn (a map-lifted shared lift spells const bases as gaddr, which would
  *  blind the /raw-globals siblings — the /addr-home lesson). `strip` opts the variation into the
  *  dropped-sibling closure: a candidate that applies it is skipped when its default sibling (the
- *  same setting without it) failed the boundary contracts. Which of these entries `structure()`'s
+ *  same setting without it) failed the boundary contracts. `offWitness` is the exact gate where
+ *  only the structuring itself knows whether the variation can change the tree: the OFF sibling
+ *  (the same setting without it, structured earlier in the same pass) runs with that hook, and a
+ *  setting whose OFF sibling never fired it is skipped, since it would build that sibling's tree
+ *  again. Which of these entries `structure()`'s
  *  `assertDefaultAccepts` guard does NOT reset — the ones that cannot unlock a function the default
  *  declines, and so carry a written argument in place of the guard — is stated ONCE, beside that
  *  guard in structure.ts, and derived from the guard's own reset list in
@@ -71,14 +76,18 @@ export interface StructureVariation {
     | 'derivedHome'
     | 'mergeHome'
     | 'escapeHome'
-    | 'unsCmp'
+    | 'signedCmp'
     | 'freshMerge'
     | 'copyDefPos'
-    | 'siteSense';
+    | 'siteSense'
+    | 'tailCopies'
+    | 'forContinue'
+    | 'caseGoto';
   name: VariationName;
   options: (on: boolean) => Parameters<typeof structureChecked>[1];
   sharedGate?: (sharedLift: Fn, defs: Map<Value, Op>) => boolean;
   perLiftGate?: (fn: Fn) => boolean;
+  offWitness?: 'onTailFallerKept' | 'onForOffered' | 'onCaseCopied';
   strip: boolean;
 }
 export const STRUCTURE_VARIATIONS: readonly StructureVariation[] = [
@@ -225,17 +234,22 @@ export const STRUCTURE_VARIATIONS: readonly StructureVariation[] = [
     perLiftGate: hasEscapingExtension,
     strip: true,
   },
-  // `/uns-cmp` — spell unsigned compares unsigned (structure.ts unsignedCompareSpelling): an
-  // icmp_u* operand takes a (u32) cast where the rendered operands do not guarantee the
-  // unsignedness, and a mixed-claimant declaration reconciles to u32 when nothing under the
-  // name needs signed. Which side the source spelled is genuinely ambiguous: a signed spelling
-  // that byte-matched was PROVED non-negative by the compiler (only then does it emit the
-  // unsigned branch from a signed compare), and emission's provable set is smaller than the
-  // compiler's. Gated on the function having an unsigned compare at all.
+  // `/signed-cmp` — spell an unsigned compare SIGNED (structure.ts unsignedCompareSpelling OFF): no
+  // `(u32)` cast at an icmp_u* and no u32 reconciliation of a mixed-claimant declaration. The
+  // default is the one spelling value-faithful without a proof; this one is a real source where the
+  // compiler PROVED both sides non-negative (only then does it emit the unsigned branch from a
+  // signed compare), which emission cannot always repeat. Where the proof does not hold it is a
+  // different program, so rank.ts judges every emitted tree (`signedOverUnsignedCompare`) and makes
+  // a signed rendering `Candidate.matchOnly`, whichever setting or respell spelled it. A tie or a
+  // better nonmatch score is no evidence for it (`synthetic:selloop:gcc2.7.2kmc`).
+  // KNOWN GAP, in the safe direction: the judgment reads the tree's declarations, and globals are
+  // not among them, so a compare that renders unsigned only through a `void *` global the backend
+  // declares (ptrcell.test.ts KR1, `g >= gLimit`) is still withheld on a nonmatch.
+  // Gated on the function having an unsigned compare at all.
   {
-    flag: 'unsCmp',
-    name: 'uns-cmp',
-    options: (on) => ({ unsignedCompareSpelling: on }),
+    flag: 'signedCmp',
+    name: 'signed-cmp',
+    options: (on) => ({ unsignedCompareSpelling: !on }),
     sharedGate: (sharedLift) => sharedLift.blocks.some((b) => b.ops.some((op) => op.opcode.startsWith('icmp_u'))),
     strip: true,
   },
@@ -371,26 +385,107 @@ export const STRUCTURE_VARIATIONS: readonly StructureVariation[] = [
       ),
     strip: false,
   },
+  // `/tail-copies` — WHICH ARM KEEPS A CROSS-JUMPED TAIL (structure.ts `copyEveryTailEntrant`,
+  // switch-recover.ts `copySharedFallTargets`). A compiler that cross-jumps keeps one copy of the
+  // code two or more jump-table arms end in, so those arms all enter one sibling arm's body. The
+  // default writes the body back into every entrant but the one the arm-order policy puts directly
+  // above the sibling, which keeps its fall-through; this writes it into every entrant. Which arm
+  // the source wrote the tail under is not in the asm, and one compiler answers both ways at one
+  // set of flags: on KMC `-O2` and gcc 2.7.2 `-O1`, `synthetic:jt_xjcase` (case 1 written above
+  // case 2 and falling into it) recompiles only from the default, while the same arms written
+  // out of case order (`case 3`, `case 2`, `case 1`) are 24 objdump lines off from the default
+  // and 4 from this. So the differ referees it per row, like `/copy-defpos`.
+  //
+  // Gated EXACTLY, by its OFF sibling's structuring (`offWitness`): the two settings read
+  // different exits only where an entrant is left falling into a cross-jumped sibling
+  // (`copySharedFallTargets`' `onFallerKept`), so where the OFF sibling never left one the ON setting
+  // is not structured at all. No question of the raised fn answers that ahead of the pass: a block
+  // two arms reach is no sibling where it is the switch's merge (nearly every switch's post-switch
+  // code), and two entrants can reach their sibling through one shared cross-jumped block, so one
+  // in-edge. In the strip closure, and reset by `assertDefaultAccepts`: where the target language
+  // has no fall-through (Pascal) the default can still decline on the one fall-through it keeps,
+  // and copying every entrant would structure what the default refused.
+  {
+    flag: 'tailCopies',
+    name: 'tail-copies',
+    options: (on) => ({ copyEveryTailEntrant: on }),
+    offWitness: 'onTailFallerKept',
+    strip: true,
+  },
+  // `/for-continue` — A COUNTED LOOP AS `for` WHERE THE DEFAULT LIFTS IT AS `while (1)` (structure.ts
+  // `spellCountedLoopsFor`, `forPlanAt`). A loop whose latch steps one counter and tests it, entered
+  // through the same test, is one asm under both spellings, and the `for` is the one a jump-table arm
+  // inside it can `continue` and leave by `break;` after the switch. structure() reaches that `for`
+  // on its own only where every `while (1)` structuring declined (`ForRanking`); here it is ranked
+  // where the default lifts. Measured on agbcc, objdump instruction lines off the target, both lifts
+  // 0/20000 against the source in a host differential: a `for` whose five jump-table arms each
+  // `continue` or call and leave lifts as `while (1)` with the code after the loop copied into every
+  // arm at 54, and as the `for` at 27; two nested-loop probes go 81 → 68 and 55 → 44.
+  //
+  // Gated EXACTLY, by its OFF sibling's structuring (`offWitness`): only a `while (1)` loop that passes
+  // every one of `forPlanAt`'s checks can change, and the OFF sibling reports meeting one
+  // (`onForOffered`). In the strip closure, and reset by `assertDefaultAccepts`: a first run that
+  // spells every such loop `for` can structure a function the default (with its own reruns) refuses.
+  {
+    flag: 'forContinue',
+    name: 'for-continue',
+    options: (on) => ({ spellCountedLoopsFor: on }),
+    offWitness: 'onForOffered',
+    strip: true,
+  },
+  // `/case-goto` — TWO ARMS ENTERING ONE CASE'S BODY AS A `goto` TO ITS LABEL WHERE THE DEFAULT
+  // COPIES IT (structure.ts `jumpToSharedCases`, switch-recover.ts `jumpSharedFallTargets`). Where
+  // two or more jump-table arms enter one case arm's body, the default writes that body back into the
+  // entrants but one (`copySharedFallTargets`) and reads the goto only where every goto-free
+  // structuring of the function declines, in a switch none of them spelled goto-free
+  // (`JumpRanking`); this reads the goto first. The asm does not
+  // say which: a compiler that cross-jumps merges a source copy into the goto's bytes when the whole
+  // copy matches, and on agbcc it stops short where CSE has the arm re-use an address the copy
+  // re-forms, so the copy compiles to more code than the goto (`synthetic:sw_gotocase2`, case 1's copy
+  // re-reading `gE[i]`). The differ referees it per row, like `/tail-copies`, and a tie goes to the
+  // candidate without the goto (rank.ts `gotoCount`). It does not take `/tail-copies`' faller choice:
+  // the entrant directly above the case always falls, since a jump from it would land on the label
+  // right below it, a path its fall-through already spells — so `/tail-copies/case-goto` is no
+  // candidate of its own.
+  //
+  // Gated EXACTLY, by its OFF sibling's structuring (`offWitness`): the two settings read different
+  // exits only where the copies write a case arm's body into an entrant (`onCaseCopied`). In the
+  // strip closure, and reset by `assertDefaultAccepts`: read first, the jumps can leave a chain the
+  // copies after them structure where the default (copies, then jumps) declined.
+  {
+    flag: 'caseGoto',
+    name: 'case-goto',
+    options: (on) => ({ jumpToSharedCases: on }),
+    offWitness: 'onCaseCopied',
+    strip: true,
+  },
 ];
 
-/** The STACKED variations (sanctioned in the POLICY note at rank.ts's respell site): each entry is
- *  a statement-order/shape or declaration-width respell variation orthogonal to every respell
- *  variation outside this table, derived onto every source. Two members need not commute
- *  (`/narrow-decl` and `/narrow-read` compete for one cast), and table order then decides which one
- *  takes it in the all-together candidate. Each fires alone, plus
- *  all of them together in table order — not the full subset lattice; the pairs question is
- *  settled by applyStacked' skip-on-decline below, and a row demanding a true EXCLUSION pair —
- *  every member fires, the match needs a strict subset of them — is what would earn the lattice.
- *  So a member appended here also changes the all-together candidate wherever it fires beside two
- *  or more of the others. */
-export const STACKED_VARIATIONS: { name: VariationName; apply: (sfn: SFn) => SFn | null }[] = [
+/** The statement-order/shape members. */
+const STACKED_SHAPES: { name: VariationName; apply: (sfn: SFn) => SFn | null }[] = [
   { name: 'initfirst', apply: initFirstGuards },
   { name: 'pollguard', apply: pollGuards },
   { name: 'pollread', apply: pollReads },
+];
+
+/** The declaration-width members: one dimension, the width each kind of local is declared at
+ *  (l3/narrowdecl.ts). A function holding a cast-written local,
+ *  load-written locals and call-result locals may need any combination of the three kinds narrow
+ *  while all three fire (the matching suite compiles all eight), so every subset is offered. */
+const STACKED_WIDTHS: { name: VariationName; apply: (sfn: SFn) => SFn | null }[] = [
   { name: 'narrow-decl', apply: narrowDeclarations },
+  { name: 'narrow-load', apply: narrowLoadDeclarations },
   { name: 'narrow-read', apply: narrowReadDeclarations },
 ];
 
+/** The STACKED variations (sanctioned in the POLICY note at rank.ts's respell site): each entry is
+ *  a statement-order/shape or declaration-width respell variation orthogonal to every respell
+ *  variation outside this table, derived onto every source. Two members need not commute
+ *  (`/narrow-decl` and `/narrow-read` compete for one cast, `/narrow-load` and `/narrow-read` for
+ *  one local), and table order then decides which one takes it in a candidate holding both. Which
+ *  of them a candidate applies is STACKED_SUBSETS. */
+export const STACKED_VARIATIONS = [...STACKED_SHAPES, ...STACKED_WIDTHS];
+
 /** The PRE-RESPELL variations (sanctioned in the POLICY note at rank.ts's respell site): a tree
  *  rewrite applied BEFORE the respell set, so the whole set derives from its output instead of
  *  composing onto it. Same record type as STACKED_VARIATIONS above, and deliberately so — the only difference is
@@ -455,20 +550,60 @@ export const STACKED_VARIATIONS: { name: VariationName; apply: (sfn: SFn) => SFn
  *  `synthetic:ladidx1`, `synthetic:ladidx2`, `synthetic:revlad5s`. `bench regression` is an
  *  OUTCOME gate over all tiers, so every one of them turns it red — but `benchmark.yml` is
  *  `workflow_dispatch`, manual, with no cron, so nothing runs that gate on a PR. The scores and the
- *  method are in `apps/benchmark/dataset/synthetic.ts`'s `/unmerge` block. */
-export const PRE_RESPELL_VARIATIONS: typeof STACKED_VARIATIONS = [{ name: 'unmerge', apply: unmergeJoins }];
-
-export const STACKED_SUBSETS: (typeof STACKED_VARIATIONS)[number][][] = [
-  ...STACKED_VARIATIONS.map((x) => [x]),
-  ...(STACKED_VARIATIONS.length > 1 ? [STACKED_VARIATIONS] : []),
+ *  method are in `apps/benchmark/dataset/synthetic.ts`'s `/unmerge` block.
+ *
+ *  `/case-end-goto` (l3/caseendgoto.ts) is the second entry: a search loop's hit flag read where the
+ *  code after its loop ends the switch arm, rewritten as the case-end goto the source wrote. Here
+ *  rather than among the stacked members because the rest of the respell set must derive from the
+ *  goto tree (an `initfirst` or `sinkinit` over a tree that no longer declares the flag), and here
+ *  rather than as a structure variation for the cost l3/caseendgoto.ts's header gives. Each entry applies to
+ *  the structured tree on its own, so `/unmerge` and `/case-end-goto` never compose. */
+export const PRE_RESPELL_VARIATIONS: typeof STACKED_VARIATIONS = [
+  { name: 'unmerge', apply: unmergeJoins },
+  { name: 'case-end-goto', apply: jumpToCaseEnds },
 ];
 
+/** Every subset of `xs`, the empty one first, each in `xs`' order. */
+const subsets = <X>(xs: readonly X[]): X[][] =>
+  xs.reduce<X[][]>((acc, x) => [...acc, ...acc.map((s) => [...s, x])], [[]]);
+
+/** The stacked members a candidate applies: the table's two dimensions crossed, a shape choice
+ *  (none, each shape alone, or every shape) by a width choice (any subset of the widths, none
+ *  included), the shapes first. A product, because a function may need a shape AND a strict subset
+ *  of the widths that fire: `initfirst` beside a narrow cast-written local and wide load-written
+ *  ones (the matching suite compiles that pair both ways). The shapes are not a lattice of their own:
+ *  applyStacked's skip-on-decline makes "every shape" each pair of them wherever the third declines,
+ *  and a row demanding a strict subset of the shapes while all fire is what would earn one. Fewest
+ *  members first, so where everything else ties the smaller set is enumerated first and wins. */
+export const STACKED_SUBSETS: (typeof STACKED_VARIATIONS)[number][][] = subsets(STACKED_WIDTHS)
+  .flatMap((widths) =>
+    [[], ...STACKED_SHAPES.map((x) => [x]), ...(STACKED_SHAPES.length > 1 ? [STACKED_SHAPES] : [])].map((shapes) => [
+      ...shapes,
+      ...widths,
+    ]),
+  )
+  .filter((subset) => subset.length > 0)
+  .sort((a, b) => a.length - b.length);
+
+/** A stacked member that threw, named by the members that fired before it and then itself: the
+ *  step that threw, which every subset reaching it shares. Reported under that name rather than
+ *  the whole subset's, so a consumer deduping on the step prints one broken member once and not
+ *  once per subset holding it. */
+export class StackedMemberThrew extends Error {
+  constructor(
+    readonly variations: readonly VariationName[],
+    cause: unknown,
+  ) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause });
+  }
+}
+
 /** The subset applied in table order, SKIP-ON-DECLINE: a member that declines contributes
  *  nothing rather than killing the combination — the all-shapes candidate is "everything that
  *  fires", so a pair is reachable whenever the third declines. The variations are the members that
- *  actually FIRED, so they never name a variation that declined; a fired-set that
- *  duplicates a smaller subset emits identical source and the dedup collapses it. Null when
- *  nothing fired. */
+ *  actually FIRED, so they never name a variation that declined; a fired set that
+ *  duplicates a smaller subset's derives the same tree, which the caller emits once
+ *  (`firstFired`). Null when nothing fired. A member that throws throws StackedMemberThrew. */
 export const applyStacked = (
   subset: readonly (typeof STACKED_VARIATIONS)[number][],
   from: SFn,
@@ -476,7 +611,12 @@ export const applyStacked = (
   let cur = from;
   const fired: VariationName[] = [];
   for (const sp of subset) {
-    const r = sp.apply(cur);
+    let r: SFn | null;
+    try {
+      r = sp.apply(cur);
+    } catch (e) {
+      throw new StackedMemberThrew([...fired, sp.name], e);
+    }
     if (r) {
       cur = r;
       fired.push(sp.name);
@@ -485,6 +625,17 @@ export const applyStacked = (
   return fired.length > 0 ? { out: cur, variations: fired } : null;
 };
 
+/** Whether `fired` is a fired set not yet in `seen`, recording it. Two subsets that fire the same
+ *  members derive the same tree, so a caller emits only the first. */
+export const firstFired = (seen: Set<string>, fired: readonly VariationName[]): boolean => {
+  const key = fired.join('/');
+  if (seen.has(key)) {
+    return false;
+  }
+  seen.add(key);
+  return true;
+};
+
 /** The locals a variation added — a NAME diff rather than a positional slice, so a pass that ever
  *  reorders locals cannot silently empty the set. It is what scopes `/volatile` to the pointers
  *  the variation itself created (volatilePtrLocals' `only`), leaving the tree's own locals alone. */