@asmlift/core 0.8.1 → 0.10.0

package/src/rank-declare.ts

@@ -9,10 +9,14 @@
 // asks each emitted tree for its references. A SIBLING MODULE, never a `rank/` directory — see the
 // same note on rank-variations.ts.
 import { type Fn, type Value, defOpMap } from './ir/core';
+import { qualified } from './ir/discipline';
+import { MEM_BASE_OPS } from './ir/opcodes';
 import type { SFn } from './l3/ast';
-import { type SymbolRef, collectSymbolRefs } from './l3/symbol-refs';
-import type { SymbolInfo } from './symbols';
-import { C_TYPEDEFS } from './target';
+import { type SymbolRef, collectSymbolRefs, ownReturnDefinition } from './l3/symbol-refs';
+import type { FnProto, Prototypes } from './proto';
+import { storeSigned, storedConstantSign } from './raise/storesign';
+import { type SymbolInfo, accessSignedness } from './symbols';
+import { C_TYPEDEFS, type TargetDescription, globalRegisterSymbol } from './target';
 
 /** Bare-global ACCESS FACTS for name-only map symbols — the width/signedness authority the
  *  declaration synthesis (declare.ts) uses when the map has no shape. The map knows only the
@@ -22,15 +26,35 @@ import { C_TYPEDEFS } from './target';
  *  Mirrors structure()'s scalar-global rule: a fact is recorded only for a symbol accessed
  *  EXCLUSIVELY at offset 0 with ONE width and ONE load signedness — anything else (interior
  *  offsets, address arithmetic, width or sign conflicts) records nothing, because those
- *  spellings go through `&gSym` casts where every object decl is address-identical. */
+ *  spellings go through `&gSym` casts where every object decl is address-identical.
+ *
+ *  A symbol never LOADED takes its sign from its stamped stores (raise/storesign.ts); an unstamped
+ *  store says nothing, so a cell only ever stored unstamped keeps the unsigned default. A load
+ *  still wins, as in raise/structs.ts. Stores whose stamps disagree keep the width with the
+ *  unsigned default: dropping the fact would declare `extern u32` under a bare `gSym = v` that
+ *  then compiles to `sw` where the target has `sh`. The bare spelling has no cast to carry the
+ *  stamp, so this declaration is the only place the stored constant's view can be written.
+ *
+ *  An UNSTAMPED store of a constant zero-extended from its narrow sign bit vetoes a signed
+ *  declaration. storesign.ts leaves such a store unstamped when a wider use shares the constant,
+ *  and the structurer spells it as the literal (`gS = 65535; gW = 65535;`). Under `extern s16 gS`,
+ *  that literal converts to -1, and the shared register splits in two. The veto only ever chooses
+ *  the unsigned default, which is what the declaration was before stamps existed. */
 export function bareGlobalAccessFacts(fn: Fn): Map<string, { width: number; signed: boolean }> {
   const defs = defOpMap(fn);
   const symOf = (v: Value): string | null => {
     const d = defs.get(v);
     return d?.opcode === 'gaddr' && d.attrs.code !== true ? (d.attrs.sym as string) : null;
   };
-  const acc = new Map<string, { widths: Set<number>; signs: Set<boolean>; interior: boolean }>();
-  const get = (s: string) => acc.get(s) ?? acc.set(s, { widths: new Set(), signs: new Set(), interior: false }).get(s)!;
+  const acc = new Map<
+    string,
+    { widths: Set<number>; signs: Set<boolean>; stored: Set<boolean>; unsignedLiteral: boolean; interior: boolean }
+  >();
+  const get = (s: string) =>
+    acc.get(s) ??
+    acc
+      .set(s, { widths: new Set(), signs: new Set(), stored: new Set(), unsignedLiteral: false, interior: false })
+      .get(s)!;
   for (const b of fn.blocks) {
     for (const op of b.ops) {
       if (op.opcode === 'load' || op.opcode === 'store') {
@@ -42,7 +66,17 @@ export function bareGlobalAccessFacts(fn: Fn): Map<string, { width: number; sign
           } else {
             a.widths.add(op.attrs.width as number);
             if (op.opcode === 'load') {
-              a.signs.add(((op.attrs.signed as boolean) ?? false) && (op.attrs.width as number) < 4);
+              a.signs.add(accessSignedness(op.attrs.width as number, op.attrs.signed as boolean | undefined));
+            } else if (op.attrs.signed !== undefined) {
+              a.stored.add(storeSigned(op, op.attrs.width as number));
+            } else {
+              const d = defs.get(op.operands[1]);
+              if (
+                d?.opcode === 'const' &&
+                storedConstantSign(d.attrs.value as number, op.attrs.width as number) === false
+              ) {
+                a.unsignedLiteral = true;
+              }
             }
           }
         }
@@ -64,9 +98,15 @@ export function bareGlobalAccessFacts(fn: Fn): Map<string, { width: number; sign
   }
   const out = new Map<string, { width: number; signed: boolean }>();
   for (const [s, a] of acc) {
-    if (!a.interior && a.widths.size === 1 && a.signs.size <= 1) {
-      out.set(s, { width: [...a.widths][0], signed: a.signs.has(true) });
+    if (a.interior || a.widths.size !== 1 || a.signs.size > 1) {
+      continue;
     }
+    // Loads decide when there are any. Stores whose stamps disagree pick no view, nor does a signed
+    // stamp beside an unstamped zero-extended literal: the declaration keeps the width and takes
+    // the unsigned default it had before stamps existed.
+    const signed =
+      a.signs.size === 1 ? a.signs.has(true) : a.stored.size === 1 && a.stored.has(true) && !a.unsignedLiteral;
+    out.set(s, { width: [...a.widths][0], signed });
   }
   return out;
 }
@@ -172,16 +212,73 @@ export type RefusedDeclarationReason =
  *  module note. */
 export function bareGlobalSymbols(fn: Fn): Map<string, SymbolInfo> {
   const out = new Map<string, SymbolInfo>();
+  const defs = defOpMap(fn);
+  // A name the lift accessed QUALIFIED at its own address (ir/discipline.ts `qualified`, whichever
+  // placement put it there) is declared `volatile`: the structurer spells that access by the bare
+  // name, whose declaration owns its qualifiers (l3/volstore.ts `qualifiedMemoryAccess`), so a plain
+  // declaration would drop the qualifier the access carries — `gR;` under `extern u32 gR;` compiles
+  // to no read at all. A `declared` placement says the project's own header qualifies the name, and
+  // the declaration synthesized beside it says so too.
+  const qualifiedNames = new Set<string>();
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      const d = MEM_BASE_OPS.has(op.opcode) ? defs.get(op.operands[0]) : undefined;
+      if (d?.opcode === 'gaddr' && op.attrs.off === 0 && qualified(op)) {
+        qualifiedNames.add(d.attrs.sym as string);
+      }
+    }
+  }
   for (const b of fn.blocks) {
     for (const op of b.ops) {
       if (op.opcode === 'gaddr' && typeof op.attrs.sym === 'string') {
-        out.set(op.attrs.sym, { name: op.attrs.sym, kind: 'data' });
+        const sym = op.attrs.sym;
+        out.set(sym, {
+          name: sym,
+          kind: 'data',
+          ...(qualifiedNames.has(sym) ? { volatile: true } : {}),
+          ...(typeof op.attrs.globalRegister === 'string' ? { globalRegister: op.attrs.globalRegister } : {}),
+        });
       }
     }
   }
   return out;
 }
 
+/** The globals a function-scope static's initializer holds the address of (ir/core.ts
+ *  `LocalObject.relocs`), as name-only symbols for the same synthesis: the candidate spells each in
+ *  the static's definition (`(u32)&Name`), and only the static's relocations name it. Kept apart
+ *  from {@link bareGlobalSymbols}, whose names the variation gates read as the globals the BODY
+ *  addresses: an address in a table no access ever subscripts says nothing of how one is spelled. */
+export function initAddressSymbols(fn: Fn): Map<string, SymbolInfo> {
+  const out = new Map<string, SymbolInfo>();
+  for (const obj of fn.localObjects?.values() ?? []) {
+    for (const r of obj.relocs ?? []) {
+      out.set(r.symbol, { name: r.symbol, kind: 'data' });
+    }
+  }
+  return out;
+}
+
+/** The global register variables a compiler that declares them only as a contiguous run
+ *  (`globalRegisterVariables.contiguous`, mwcc 2.4: "gaps between assigned global register variables
+ *  are not permitted") needs declared below the highest one `refs` names, and they do not. Each is a
+ *  word nothing reads, declared only so the one the body uses is legal. */
+function globalRegisterFillers(
+  refs: readonly SymbolRef[],
+  target: Pick<TargetDescription, 'globalRegisterVariables'>,
+): SymbolRef[] {
+  const run = target.globalRegisterVariables?.contiguous ?? [];
+  const named = new Set(refs.flatMap((r) => (r.info.globalRegister === undefined ? [] : [r.info.globalRegister])));
+  const top = Math.max(-1, ...[...named].map((r) => run.indexOf(r)));
+  return run
+    .slice(0, top + 1)
+    .filter((r) => !named.has(r))
+    .map((r) => {
+      const name = globalRegisterSymbol(r);
+      return { name, info: { name, kind: 'data', globalRegister: r }, synthesized: true };
+    });
+}
+
 /** The reference collector one enumeration uses, over ONE dictionary. A factory rather than a
  *  free function because all four of its inputs are per-enumeration constants that must not vary
  *  per tree — naming them here is what keeps a caller from passing a different dictionary to two
@@ -202,15 +299,39 @@ export function makeRefCollector(ctx: {
   /** the globals the TARGET names — the pool/reloc names and the shapes the asm evidences, before
    *  the map is unioned in */
   targetNames: ReadonlySet<string>;
+  /** the project's prototype table — what lets a CALL TARGET be declared rather than refused */
+  prototypes: Prototypes;
+  /** the target the lift ran for, whose ABI says which declared types a printed prototype carries */
+  target: Pick<TargetDescription, 'doubleArgWords' | 'globalRegisterVariables'>;
   /** reports a refusal at most once per (name, reason); the caller owns the dedup */
   refuse: (name: string, reason: RefusedDeclarationReason) => void;
+  /** the function's own declaration — stated, or the context's own entry — whose struct return a
+   *  tree that returns it needs defined (`ownReturnDefinition`) */
+  own?: FnProto;
 }): (tree: SFn) => { symbolRefs?: SymbolRef[] } {
-  const { declSymbols, accessFacts, mapSymbols, targetNames, refuse } = ctx;
+  const { declSymbols, accessFacts, mapSymbols, targetNames, prototypes, target, refuse, own } = 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.
     const bound = new Set<string>([...tree.params.map((p) => p.name), ...tree.locals.map((l) => l.name)]);
-    const refs = collectSymbolRefs(tree.body, declSymbols, tree.name, refuse).flatMap((r) => {
+    // A function-scope static is declared in the body beside the locals, so it shares their
+    // namespace: one the emitter's own names can reach dies with the spelling, as below.
+    const statics = new Set((tree.statics ?? []).map((st) => st.name));
+    // …and the compiler's anonymous images, which reach the C only as a local's initializer
+    const images = new Set((tree.images ?? []).map((im) => im.name));
+    for (const st of statics) {
+      if (bound.has(st) || EMITTER_NAME.test(st)) {
+        refuse(st, 'emitter-name');
+        throw new Error(
+          `cannot spell '${tree.name}': the target names a function-scope static '${st}', which is a ` +
+            `name the emitted C uses for its own locals and parameters — no declaration can bind it`,
+        );
+      }
+    }
+    const refs = collectSymbolRefs(tree, declSymbols, prototypes, target, refuse).flatMap((r) => {
+      if (statics.has(r.name) || images.has(r.name)) {
+        return []; // defined in the body — the map's global of the same name is another object
+      }
       // THE ONE REFUSAL THAT IS NOT A REFUSAL — a name the emitted C uses for its OWN storage
       // kills the SPELLING, because no declaration makes that candidate right and no declaration
       // makes it fail either. Two shapes, and the second is why the test is the emitter's whole
@@ -257,8 +378,18 @@ export function makeRefCollector(ctx: {
       // A ref no MAP accounts for is a hypothesis read out of the target asm, and it is marked
       // as one all the way to the consumer (SymbolRef.synthesized).
       const synthesized = mapSymbols?.has(r.name) ? {} : { synthesized: true as const };
+      // A global the asm reads narrower than a word holds no pointer, whatever it meets bare.
+      if (r.holdsPointer && access !== undefined && access.width !== 4) {
+        const { holdsPointer: _, ...integer } = r;
+        return [{ ...integer, access, ...synthesized }];
+      }
       return [{ ...r, ...(access ? { access } : {}), ...synthesized }];
     });
+    refs.push(...globalRegisterFillers(refs, target));
+    const returned = ownReturnDefinition(tree, own);
+    if (returned !== undefined) {
+      refs.push(returned);
+    }
     return refs.length ? { symbolRefs: refs } : {};
   };
 }

package/src/rank-variations.ts

@@ -27,6 +27,7 @@ import {
 import type { Gate } from './l3/gates';
 import type { HoistPlacement } from './l3/hoist';
 import { initFirstGuards } from './l3/initfirst';
+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
@@ -35,6 +36,7 @@ import { unmergeJoins } from './l3/unmerge';
 import type { structureChecked } from './pipeline';
 import {
   hasDerivedReadHome,
+  hasEscapingExtension,
   hasHomeableSharedAddress,
   hasLoopSharedPureValue,
   hasMergeFeedHome,
@@ -53,11 +55,12 @@ 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. Two variations are EXEMPT from structure()'s assertDefaultAccepts invariant:
- *  `/reread-globals` only relaxes inlining barriers and `/uns-cmp` only changes spelling and
- *  declarations — neither adds materialization or merging, so neither can unlock a function the
- *  default declines (reread also skips the strip closure). Both exemptions are stated here
- *  rather than left implicit in a missing `||` arm or trigger term. */
+ *  same setting without it) failed the boundary contracts. 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
+ *  test/variation-offers.test.ts — never restated here, where a second copy drifts from the guard
+ *  without anything going red. */
 export interface StructureVariation {
   flag:
     | 'reread'
@@ -67,7 +70,8 @@ export interface StructureVariation {
     | 'exprHome'
     | 'derivedHome'
     | 'mergeHome'
-    | 'unsCmp'
+    | 'escapeHome'
+    | 'signedCmp'
     | 'freshMerge'
     | 'copyDefPos'
     | 'siteSense';
@@ -203,17 +207,40 @@ export const STRUCTURE_VARIATIONS: readonly StructureVariation[] = [
     perLiftGate: hasMergeFeedHome,
     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.
+  // `/escape-home` — the escaping-extension-home variation (structure/analysis.ts AnalyzeOptions
+  // homeEscapingExtensions): a `zext`/`sext` with 2+ consumers, none of them in its own block,
+  // materializes into a local — the register the asm narrowed into once and every later block read
+  // — where the default re-evaluates the truncation at each consumer (`(u16)v` per use). The
+  // MIRROR of `/expr-home`, which wants a def outside a loop and a consumer inside; neither scope
+  // reaches the other's shape. Gated per symbol-map setting like its four siblings.
+  //
+  // A VARIATION, not a default, and `pokeemerald:AcroBikeHandleInputTurning:agbcc` is the row that
+  // decides it: it is a MATCH inside the scope, so forced on the spelling would be REPLACED across
+  // the fan rather than added to it. As a variation `compareScored` rides the un-homed sibling
+  // beside it and the match cannot be lost — the same argument `/merge-home` records above.
   {
-    flag: 'unsCmp',
-    name: 'uns-cmp',
-    options: (on) => ({ unsignedCompareSpelling: on }),
+    flag: 'escapeHome',
+    name: 'escape-home',
+    options: (on) => ({ homeEscapingExtensions: on }),
+    perLiftGate: hasEscapingExtension,
+    strip: true,
+  },
+  // `/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: '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,
   },
@@ -351,18 +378,31 @@ export const STRUCTURE_VARIATIONS: readonly StructureVariation[] = [
   },
 ];
 
-/** The STACKED variations (sanctioned in the POLICY note at rank.ts's respell site): each entry is
- *  a statement-order/shape respell variation orthogonal to every other respell variation, derived
- *  onto every source. 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 —
- *  all three fire, the match needs exactly two — is what would earn the lattice. */
-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
@@ -430,17 +470,47 @@ export const STACKED_VARIATIONS: { name: VariationName; apply: (sfn: SFn) => SFn
  *  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] : []),
-];
+/** 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,
@@ -448,7 +518,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);
@@ -457,6 +532,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. */