@asmlift/core 0.9.0 → 0.11.0

package/src/trace.ts

@@ -7,13 +7,22 @@
 import { cBackend } from './backend/c';
 import type { CodegenProfile } from './codegen-flags';
 import type { AsmData } from './frontend/asmdata';
+import type { CalleeBodies } from './frontend/callee-body';
 import type { Fn } from './ir/core';
 import { print } from './ir/print';
 import { verify } from './ir/verify';
 import type { LanguageBackend } from './l3/ast';
 import { DEFAULT_IDIOM_PATTERNS, RewritePattern, applyPattern, dce, patternApplies } from './pattern/engine';
-import { type OnGap, liftStamped, raiseRecovered, structureChecked, stubResult } from './pipeline';
-import { type Prototypes, declaresVoidReturn, prototypesFromSymbols } from './proto';
+import {
+  type OnGap,
+  liftStamped,
+  offsetNameBehaviorsFor,
+  raiseRecovered,
+  structureReturnTailReading,
+  stubResult,
+} from './pipeline';
+import { type FnProto, type Prototypes, declaresVoidReturn, prototypesFromSymbols } from './proto';
+import { type ContextGlobals, splitOwnContext } from './proto-context';
 import { assumedShapes, inferGlobalArrays, orderLicensedGlobals } from './raise/globalshape';
 import { OFFSET_NAME_PASS } from './raise/offsetnames';
 import { type SymbolInfo, type SymbolMap, symbolsByName } from './symbols';
@@ -92,6 +101,9 @@ export interface TraceOptions {
   prototypes?: Prototypes; // header facts (callee arities + void-ness), keyed by symbol
   asmData?: AsmData; // data-section side table (Regime-B jump tables), as in decompile()
   symbols?: SymbolMap; // address→symbol map (symbols.ts), as in decompile(); absent ⇒ inert
+  contextGlobals?: ContextGlobals; // the declaration context's globals, as in decompile()
+  ownContextProto?: FnProto; // the context's own entry, as in decompile()
+  calleeBodies?: CalleeBodies; // bodies of callees outside the input, as in decompile()
   onGap?: OnGap; // "strict" (default) | "annotate", as in decompile()
   /** Source probe at pattern boundaries: the source asmlift would emit there, which the cli report
    *  scores. One call per boundary: pattern N's after-source is pattern N+1's before-source. Absent ⇒
@@ -189,13 +201,24 @@ function traceTower(
   // Merged exactly as pipeline.ts does: the project's own DWARF signatures fill in what the caller
   // did not state. A trace that lifted from a different table would explain a run that never
   // happened.
-  const prototypes = prototypesFromSymbols(opts.symbols, opts.prototypes ?? {});
+  const ownContext = splitOwnContext(opts.prototypes, name, opts.ownContextProto);
+  const prototypes = prototypesFromSymbols(opts.symbols, ownContext.prototypes ?? {});
   const returnsVoid = declaresVoidReturn(prototypes[name]);
   const trace: StageTrace[] = [];
   const patternEvents: PatternEvent[] = [];
 
   // (1) lift → typed-SSA IR
-  const fn = liftStamped(name, asm, target, prototypes, opts.asmData, opts.symbols);
+  const fn = liftStamped(
+    name,
+    asm,
+    target,
+    prototypes,
+    opts.asmData,
+    opts.symbols,
+    opts.contextGlobals,
+    { calleeBodies: opts.calleeBodies },
+    ownContext.ownContextProto,
+  );
   trace.push({ id: 'stage:lift', title: 'Lift (ISA frontend → typed-SSA IR)', irDump: irDump(fn), verified: true });
   // The array shapes the assembly evidences, off the LIFTED fn — same reading, same reason, as
   // pipeline.ts's runTower: the fold and the tower below destroy the order the licence reads.
@@ -220,8 +243,10 @@ function traceTower(
 
   // The names the map holds for addresses this machine code built by arithmetic off a named one
   // (raise/offsetnames.ts), off the same lifted fn and for the same reason as pipeline.ts's
-  // runTower.
-  const named = opts.symbols ? OFFSET_NAME_PASS.run(fn, opts.symbols, target.compilerBehaviors) : [];
+  // runTower — and its one-spelling-per-cell decline, which throws from here (pipeline.ts's 1.6).
+  const named = opts.symbols
+    ? OFFSET_NAME_PASS.run(fn, opts.symbols, offsetNameBehaviorsFor(target, opts.contextGlobals))
+    : [];
   trace.push({
     id: 'stage:offsetnames',
     title: 'Name a walked-to address the symbol map knows',
@@ -302,10 +327,10 @@ function traceTower(
           irDump: irDump(fn),
           verified: true,
         }),
-      afterLatchFold: () =>
+      afterFold: (fold) =>
         trace.push({
-          id: 'stage:latchfold',
-          title: 'Empty-latch folding (splice out an SSA-emptied back-edge block)',
+          id: `stage:${fold.id}`,
+          title: fold.title,
           irDump: irDump(fn),
           verified: true,
         }),
@@ -316,14 +341,21 @@ function traceTower(
   // (4) structure → neutral AST; boundary contract: no unresolved value leaked (strict) or
   // spelled as a loud ASMLIFT_ERROR marker (annotate) — same onGap option as decompile()
   const mapSymbols = opts.symbols ? symbolsByName(opts.symbols) : undefined;
-  const sfn = structureChecked(fn, {
-    ...structureOptionsFor(target, returnsVoid, prototypes),
-    spellSwitchFallthrough: (opts.backend ?? cBackend).spellsSwitchFallthrough,
-    onGap: opts.onGap ?? 'strict',
-    ...(mapSymbols ? { symbols: mapSymbols } : {}),
-    ...(inferredSymbols.size ? { inferredSymbols } : {}),
-    ...(orderLicensed.size ? { orderLicensedGlobals: orderLicensed } : {}),
-  });
+  const { sfn } = structureReturnTailReading(
+    fn,
+    {
+      ...structureOptionsFor(target, returnsVoid, prototypes),
+      spellSwitchFallthrough: (opts.backend ?? cBackend).spellsSwitchFallthrough,
+      spellSwitchBreak: (opts.backend ?? cBackend).spellsSwitchBreak,
+      spellEarlyReturns: (opts.backend ?? cBackend).spellsEarlyReturn,
+      onGap: opts.onGap ?? 'strict',
+      ...(mapSymbols ? { symbols: mapSymbols } : {}),
+      ...(opts.contextGlobals ? { contextGlobals: opts.contextGlobals } : {}),
+      ...(inferredSymbols.size ? { inferredSymbols } : {}),
+      ...(orderLicensed.size ? { orderLicensedGlobals: orderLicensed } : {}),
+    },
+    (t) => backend.emit(t),
+  );
   trace.push({
     id: 'stage:structure',
     title: 'Structuring (IR → neutral AST)',

package/src/variation-definitions.ts

@@ -96,7 +96,7 @@ export const VARIATION_KIND_DEFINITIONS: { readonly [K in VariationKind]: Variat
     title: 'Structure',
     meaning:
       'How the checked control flow becomes C: which way a test reads, where a loop starts, what reaches a merge (the point where two paths meet), where a value is kept, and how a read or a compare is spelled.',
-    examples: ['flip-branch', 'defsite', 'loop-entry', 'reread-globals', 'uns-cmp'],
+    examples: ['flip-branch', 'defsite', 'loop-entry', 'reread-globals', 'signed-cmp'],
   },
   respell: {
     title: 'Respell',
@@ -264,6 +264,7 @@ export interface VariationDefinition {
 const CALLS =
   'void A(); void B(); void C(); void D(); void X(); void Y(); void P(); void Q(); s32 f(); s32 g(); s32 h(); void use();\n';
 
+const PIPELINE = 'packages/core/src/pipeline.ts';
 const RANK = 'packages/core/src/rank.ts';
 const RANK_VARIATIONS = 'packages/core/src/rank-variations.ts';
 const SYMBOLS = 'packages/core/src/symbols.ts';
@@ -296,7 +297,7 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
       after: 's32 example(u32 a0, u32 a1)',
     },
     implementedIn: RANK,
-    seeAlso: ['signed', 'uns-cmp'],
+    seeAlso: ['signed', 'signed-cmp'],
   },
   signed: {
     title: 'Signed parameters',
@@ -371,14 +372,43 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     implementedIn: 'packages/core/src/raise/shortcircuit.ts',
     seeAlso: ['site-sense'],
   },
+  'narrow-param': {
+    title: 'Parameter declared at the width every use extends it to',
+    summary: 'a parameter read only through narrowing casts is declared narrow, though the prologue does not widen it',
+    detail:
+      'A parameter the function only ever reads through narrowing casts can be declared at 32 bits and cast ' +
+      'at each use, or declared at the widest cast and read bare. Every use is the same value either way, ' +
+      'and where the compiler widens it at each use rather than on entry, the assembly does not say which ' +
+      'one the source declared. This lift declares it narrow, and loses a tie when no prototype declares the width.',
+    compilerBehavior:
+      'agbcc widens an `s16` parameter at each use when every use extends it, and then the two declarations ' +
+      'differ only in how the registers around them are allocated: a sibling `u8` parameter is copied ' +
+      'before it is widened under the narrow one.',
+    offeredWhen: {
+      when: 'Some parameter is read only through 8- or 16-bit casts or masks, and the default lift left it 32 bits wide.',
+      decidedBy: { symbol: 'runPreRecovery', file: 'packages/core/src/raise/pre-recovery.ts' },
+      gates: ['PARAM_READER_WIDTH_GATES'],
+    },
+    example: {
+      compiler: 'agbcc',
+      unit: 'extern u8 *gM; void f3(u8 *, u16, u8); void f2(u8 *, u8);\n@',
+      before: 'void example(s32 a, u8 b) { u8 *p = gM; f3(p + (s16)a * 4, (u16)a, b); f2(p + b * 8, b); }',
+      after: 'void example(s16 a, u8 b) { u8 *p = gM; f3(p + a * 4, (u16)a, b); f2(p + b * 8, b); }',
+    },
+    implementedIn: 'packages/core/src/raise/paramwidth.ts',
+  },
   'shared-ret': {
     title: 'Shared code after an early return',
     summary: 'code both arms of an `if` reach before returning is written once, after the `if`',
     detail:
-      'An `if` whose arms never meet again before the function returns has no follow, so by default a ' +
-      'region both arms reach is written in each of them. This structures the same raised function again ' +
-      "with that shared region as the `if`'s follow: it is written once after the `if`, and every other " +
-      'path leaves through an early `return`.',
+      'An `if` whose arms never meet again before the function returns has no follow, so under the ' +
+      'return-tail copies (`ret-copy`) a region both arms reach is written in each of them. This structures ' +
+      "the same raised function again with the copies and that shared region as the `if`'s follow: it is " +
+      'written once after the `if`, and every other path leaves through an early `return`. On agbcc, ' +
+      "this example's compiler, the copies are the default, so this is the step from them to the region " +
+      'written once. Where the join past early returns is the default instead (CodeWarrior ' +
+      "2.4.2 and 2.3.3), it already writes this example's region once, since the paths that do not " +
+      'return meet at it: the variation is a reading of the copies, ranked beside them.',
     offeredWhen: {
       when: 'Some `if` has arms that reach a common `return` block and no common block before it.',
       decidedBy: { symbol: 'hasDivergentSharedRet', file: STRUCTURE },
@@ -390,7 +420,68 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
       after: 'if (c) { A(); } else { if (x) { C(); return; } } B();',
     },
     implementedIn: STRUCTURE,
-    seeAlso: ['shared-tail'],
+    seeAlso: ['shared-tail', 'ret-copy'],
+  },
+  'ret-copy': {
+    title: 'Return tails copied',
+    summary: 'code below an `if` whose arms only meet at the `return` is written into each arm',
+    detail:
+      'An `if` with an early `return` in one arm has no block both arms reach before the function ' +
+      'returns. Where the join past early returns is the default (CodeWarrior 2.3.3, and 2.4.2, ' +
+      "this example's compiler), asmlift gives it the block where the paths that do not return meet as its " +
+      'join, so the code from there is written once and every other path leaves through its early ' +
+      '`return`; that also reads early returns the compiler merged into the epilogue or cross-jumped ' +
+      'into one return tail, and a `switch` with a `case` that returns early. This structures the same ' +
+      'raised function again with no such join: everything below the `if` is written into each arm, ' +
+      'once more per such `if` of a chain, which is the source some functions were written as. Where ' +
+      'the copies spell the whole function in fewer lines than the join, where the compiler is one that ' +
+      'cross-jumps return tails and the layout shows it did, or where an early return keeps a constant ' +
+      'its branch proved unfolded (gcc 2.x below -O2), they are the default instead, and the join is ' +
+      'offered as `ret-join`. On agbcc and IDO 7.1, measured against held-out functions where the join ' +
+      'loses matches, on GCC 2.7.2 and KMC, measured against generated functions where it does, and on CodeWarrior 2.4.7, where no held-out function was measured, the copies are ' +
+      'the default outright, and this variation is never offered there. Past the copy budget the copies ' +
+      'are not offered.',
+    offeredWhen: {
+      when: 'Some `if` or `switch` outside every loop took a join past early returns that the default kept.',
+      decidedBy: { symbol: 'structureReturnTailReading', file: PIPELINE },
+    },
+    example: {
+      compiler: 'mwcc',
+      unit: CALLS + 'extern s32 gT; void example(s32 a, s32 b) { @ }',
+      before: 'if (a > 3) { if (b == 1) { A(); gT = 0; return; } B(); } else { C(); } X(); Y();',
+      after: 'if (a > 3) { if (b == 1) { A(); gT = 0; return; } B(); X(); Y(); } else { C(); X(); Y(); }',
+      note: 'the shape of `synthetic:retchain_one`',
+    },
+    implementedIn: STRUCTURE,
+    seeAlso: ['shared-ret', 'ret-join'],
+  },
+  'ret-join': {
+    title: 'Join past early returns, where the copies are the default',
+    summary: 'the join past early returns, where it writes a return tail into early returns',
+    detail:
+      'The join past early returns writes the code below a divergent `if` once, but where the paths that ' +
+      'do not return meet at a block only some of them reach, every other path becomes an early `return` ' +
+      'that takes its own copy of the tail below. Where that spells the whole function in more lines than ' +
+      'the return-tail copies, or where the layout shows the compiler cross-jumped a return tail the ' +
+      'source wrote into every arm, or where an early return keeps a constant its branch proved unfolded ' +
+      '(gcc 2.x below -O2), the copies are the default and this is the join, offered beside them, which is ' +
+      "the source some functions were written as. On agbcc, this example's compiler, and on IDO 7.1, GCC 2.7.2, KMC and " +
+      'CodeWarrior 2.4.7, the copies are the default outright: the join is this variation ' +
+      'wherever it is taken.',
+    offeredWhen: {
+      when: 'Some `if` or `switch` outside every loop took a join past early returns that the default gave up for the copies.',
+      decidedBy: { symbol: 'structureReturnTailReading', file: PIPELINE },
+    },
+    example: {
+      compiler: 'agbcc',
+      unit: CALLS + 'void example(s32 a) { @ }',
+      before: 'if (a == 1) { A(); B(); } else if (a == 2 || a == 3) { A(); } else { A(); B(); } X(); Y(); C();',
+      after:
+        'if (a == 1) { A(); } else { if (a == 2 || a == 3) { A(); X(); Y(); C(); return; } A(); } B(); X(); Y(); C();',
+      note: 'the shape of sa3 `sub_809A808`',
+    },
+    implementedIn: PIPELINE,
+    seeAlso: ['ret-copy'],
   },
   'shared-tail': {
     title: 'Store tail copied back',
@@ -398,7 +489,7 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     detail:
       "agbcc's global common-subexpression pass can move a trailing store into every predecessor of a join, " +
       'and the paths then jump into one `store; return` tail. This lift copies that tail back into each ' +
-      'path that branches to it, and then structures with the shared follow `shared-ret` uses, so the ' +
+      'path that branches to it, and then structures with the copies and the shared follow `shared-ret` uses, so the ' +
       'store the source wrote once is written after the `if` and the others before an early `return`. It is ' +
       'enumerated apart from `shared-ret` because the sink can delete the shared `return` that variation needs.',
     compilerBehavior:
@@ -420,6 +511,63 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     implementedIn: 'packages/core/src/raise/tailsink.ts',
     seeAlso: ['shared-ret'],
   },
+  'kept-slot': {
+    title: 'Each arm keeps its copy of a shared tail',
+    summary: "a MIPS jump's delay slot that ends a tail both arms spell stays in its own arm",
+    detail:
+      'IDO, KMC and GCC 2.7.2 fill the delay slot of a `b` or `j` with a copy of the first word at its ' +
+      'target, so by default the jump is read as landing one word earlier and the two arms meet there. ' +
+      'Where the word before the jump also matches the word before that copy, the two arms may instead ' +
+      'have been written out twice, each ending in the same instructions. This lift keeps the slot in its ' +
+      'own arm, so each arm keeps the whole tail it spells.',
+    compilerBehavior:
+      'The two readings are one object: the slot runs before the target on its one edge either way. ' +
+      'Which arms the source wrote out is something only the differ can tell. The question arises on IDO ' +
+      'alone: GCC 2.7.2 and KMC cross-jump a tail both arms spell into one copy at the join before they ' +
+      'fill any slot, so their output has no tail written twice (`mergenarrow` builds with no `b` on either).',
+    offeredWhen: {
+      when: 'The MIPS lift reported a `b`/`j` whose slot ends a common tail of two or more words, and retargeted it.',
+      decidedBy: { symbol: 'enumerateCandidates', file: RANK },
+    },
+    example: {
+      compiler: 'ido',
+      unit: 'void example(s32 *out, s32 a, s32 b, s32 c) { @ }',
+      before: 's32 v; if (c) { v = (a + b) << 16; } else { v = (a - b) << 16; } out[0] = v >> 16;',
+      after: 's16 v; if (c) { v = a + b; } else { v = a - b; } out[0] = v;',
+      note: 'the shape of `synthetic:mergenarrow`',
+    },
+    implementedIn: 'packages/core/src/frontend/mips.ts',
+  },
+  'far-cast': {
+    title: 'Store past the displacement range through a cast',
+    summary: 'a store to a member past the instruction offset range is spelled through a cast of the base',
+    detail:
+      'A member past the offset an instruction can carry is reached through an address the machine adds up ' +
+      'first, and by default that access joins its struct and is spelled as the member. A store there could ' +
+      'equally have been written through a cast of the base, `*((u8 *)p + 38) = v`, or through a pointer the ' +
+      'source held, and on some compilers that is a different object. This lift keeps every such store on ' +
+      'the address it was reached through; loads still join the struct.',
+    compilerBehavior:
+      'agbcc evaluates the right-hand side of a member store before it adds up the address, and the address ' +
+      'of a cast store before the right-hand side, so the two spellings allocate and order registers ' +
+      "differently; a hoisted `u8 *d = &p->f38; *d = v;` builds the cast spelling's object. Elsewhere the " +
+      'member and the cast compile alike one access at a time, but a folded store no longer aliases the ' +
+      'loads beside it, so the lift moves those loads past it, and a pointer the source held is spelled as ' +
+      'members: KMC and GCC 2.7.2 build two loads written before a store and the same loads written after ' +
+      'it into different objects, and two of the three mwcc builds allocate a held pointer and the member ' +
+      'spelling different registers.',
+    offeredWhen: {
+      when: 'The default lift folded a store through a materialised `base + K` address into its struct.',
+      decidedBy: { symbol: 'enumerateCandidates', file: RANK },
+    },
+    example: {
+      compiler: 'agbcc',
+      unit: 'struct S { s32 a; u8 pad[34]; u8 f38; };\nvoid example(struct S *p, u8 *q) { @ }',
+      before: 'p->f38 = *q; p->a = 0;',
+      after: '*((u8 *)p + 38) = *q; p->a = 0;',
+    },
+    implementedIn: 'packages/core/src/raise/structs.ts',
+  },
 
   // ── structure ───────────────────────────────────────────────────────────────────────────────
   'flip-branch': {
@@ -772,14 +920,16 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     implementedIn: ANALYSIS,
     seeAlso: ['expr-home', 'derived-home'],
   },
-  'uns-cmp': {
-    title: 'Unsigned compare spelled unsigned',
-    summary: 'an unsigned compare carries a `(u32)` cast where its operands do not already say so',
+  'signed-cmp': {
+    title: 'Unsigned compare spelled signed',
+    summary: 'an unsigned compare drops the `(u32)` cast the default gives an operand that does not already say so',
     detail:
-      'An unsigned comparison takes a `(u32)` cast on an operand the rendering does not already make ' +
-      'unsigned, and a declaration claimed by both kinds of use becomes `u32` when nothing under it needs ' +
-      'signed. Which the source wrote is open in one direction: a signed spelling that matched was proved ' +
-      'non-negative by the compiler, and asmlift can prove less than the compiler can.',
+      'By default an unsigned comparison takes a `(u32)` cast on an operand the rendering does not already ' +
+      'make unsigned, and a declaration claimed by both kinds of use becomes `u32` when nothing under it ' +
+      'needs signed. This writes the comparison without them, as a signed one. The source may have done so: ' +
+      'a compiler emits an unsigned compare for a signed one where it proved both sides non-negative, and ' +
+      'asmlift can prove less than the compiler can. Where the sides can be negative it computes something ' +
+      'else, so it is published only when the candidate matches byte for byte; otherwise it is withheld.',
     compilerBehavior:
       'A compiler emits an unsigned branch from a signed compare only where it proved both sides non-negative.',
     offeredWhen: {
@@ -789,8 +939,8 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     example: {
       compiler: 'agbcc',
       unit: CALLS + 'void example(s32 a, s32 b) { @ A(); }',
-      before: 'if (a < b)',
-      after: 'if ((u32)a < b)',
+      before: 'if ((u32)a < b)',
+      after: 'if (a < b)',
     },
     implementedIn: STRUCTURE,
     seeAlso: ['unsigned', 'signed'],
@@ -835,8 +985,12 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     },
     example: {
       compiler: 'agbcc',
+      // The callees are PROTOTYPED here, unlike `CALLS`: `bl f` sees `c` read in r2 and a0 untouched
+      // in r0, which a pass-through `f(a0, a1, c)` would leave the same way, so an undeclared `f`
+      // declines (frontend/ssa.ts `fallbackArgc` refuses the gap). The lift reads these declarations
+      // off the unit as shown.
       unit:
-        CALLS +
+        's32 f(void); s32 g(void); s32 h(s32, s32);\n' +
         's32 example(s32 a0, s32 a1, s32 c) { s32 v1; s32 v2; if (c) { v1 = f() + 1; v2 = g(); } else { @ } return h(v1, v2); }',
       before: 'v2 = a1; v1 = a0;',
       after: 'v1 = a0; v2 = a1;',
@@ -869,6 +1023,107 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     implementedIn: STRUCTURE,
     seeAlso: ['flip-join', 'flip-branch', 'sense', 'connective'],
   },
+  'tail-copies': {
+    title: 'Shared switch tail copied into every arm',
+    summary: 'every `case` that runs into the tail a cross-jump kept gets its own copy of it',
+    detail:
+      'When several `case` arms end in the same code, the compiler keeps one copy and the other arms jump ' +
+      "into it, so they all enter one arm's body. By default the arm placed directly above that body keeps " +
+      'falling into it and the others get a copy. This gives every one of them its own copy.',
+    compilerBehavior:
+      'Which arm the source wrote the shared code under is not in the assembly. On KMC and gcc 2.7.2, an ' +
+      'arm written above its target in case order wants the fall-through, and arms written out of case ' +
+      'order want the copies.',
+    offeredWhen: {
+      when: "Structuring this lift without it left a jump-table arm falling into a sibling arm's body that another arm also enters.",
+      decidedBy: { symbol: 'STRUCTURE_VARIATIONS', file: RANK_VARIATIONS },
+    },
+    example: {
+      compiler: 'gcc',
+      unit:
+        'extern s32 gOut; void f(s32); void g(s32); void h(s32); void m(s32); void r(s32);\n' +
+        'void example(s32 id, s32 v) { switch (id) { @ } r(0); }',
+      before:
+        'case 0: f(1); break; case 1: g(v); case 2: gOut = v; break; case 3: h(v); gOut = v; break; case 4: m(5); break;',
+      after:
+        'case 0: f(1); break; case 1: g(v); gOut = v; break; case 2: gOut = v; break; case 3: h(v); gOut = v; break; case 4: m(5); break;',
+      note: 'cases 1 and 3 both enter case 2',
+    },
+    implementedIn: STRUCTURE,
+    seeAlso: ['unmerge', 'shared-tail'],
+  },
+  'for-continue': {
+    title: 'Counted loop spelled as a `for`',
+    summary: 'a `while (1)` whose last block steps and tests a counter is written `for (init; test; step)`',
+    detail:
+      'A loop whose last block adds to a counter and tests it is written by default as `while (1)` with ' +
+      '`i++; if (!(test)) break;` at the foot of its body, and a jump-table arm inside it that leaves the ' +
+      'loop copies the code after the loop and returns. This writes it as `for (i = init; test; i++)` instead, ' +
+      'so an arm that reaches the step is `continue;`, an arm that leaves the loop ends the switch, and a ' +
+      '`break;` after the switch leaves the loop. Only a loop whose entry test is the same test (or folds to ' +
+      'true) and whose last block does nothing but step one counter and test it is written this way.',
+    compilerBehavior:
+      'agbcc and gcc 2.7.2 lay a `for` out as a guard, the body and a latch that steps and tests, which is ' +
+      'also how they lay out the `while (1)` spelling of the same loop. Which one the source wrote decides ' +
+      'how the arms that leave the loop are laid out, and that is not in the assembly before it is compiled.',
+    offeredWhen: {
+      when: 'Structuring this lift without it met a `while (1)` loop whose last block steps one counter and tests it.',
+      decidedBy: { symbol: 'STRUCTURE_VARIATIONS', file: RANK_VARIATIONS },
+    },
+    example: {
+      compiler: 'agbcc',
+      unit:
+        'struct E { s32 x; u8 id; u8 u; }; extern struct E gE[]; void k(s32);\n' +
+        'void example(s32 lo, s32 hi) { s32 i; @ k(99); }',
+      before:
+        'if (lo <= hi) { i = lo; while (1) { switch (gE[i].id) { case 1: if (gE[i].u != 1) { k(4); k(99); return; } break; ' +
+        'case 2: if (gE[i].x <= 20) { k(5); k(99); return; } break; case 3: if (gE[i].x >= 0) { k(6); k(99); return; } break; ' +
+        'case 4: if (gE[i].x > 2) { k(7); k(99); return; } break; case 5: if (gE[i].x != 9) { k(8); k(99); return; } break; } ' +
+        'i++; if (i > hi) break; } }',
+      after:
+        'for (i = lo; i <= hi; i++) { switch (gE[i].id) { case 1: if (gE[i].u == 1) continue; k(4); break; ' +
+        'case 2: if (gE[i].x > 20) continue; k(5); break; case 3: if (gE[i].x < 0) continue; k(6); break; ' +
+        'case 4: if (gE[i].x <= 2) continue; k(7); break; case 5: if (gE[i].x == 9) continue; k(8); break; ' +
+        'default: continue; } break; }',
+      note: 'every arm either goes round the loop or calls `k` and leaves it; five arms, so agbcc dispatches through a jump table',
+    },
+    implementedIn: STRUCTURE,
+    seeAlso: ['tail-copies'],
+  },
+  'case-goto': {
+    title: 'Shared case body entered by `goto`',
+    summary:
+      "every `case` that runs into another case's body the default copies it into ends `goto` to that case instead",
+    detail:
+      "When several `case` arms run on into one other arm's body, by default the arm placed directly above " +
+      'that body keeps falling into it and the others get a copy of it. This leaves the copies out: those ' +
+      'arms end in `goto` to a label on that arm, after its `case` labels. It is one of the two kinds of `goto` asmlift writes.',
+    compilerBehavior:
+      'A compiler that cross-jumps keeps one copy of code that several arms end in, so a copy and a `goto` can ' +
+      'build the same object. agbcc stops that merge short where an arm already formed an address the copy ' +
+      'forms again, and the copy then compiles to more code than the `goto`.',
+    offeredWhen: {
+      when: "Structuring this lift without it copied a case arm's body into another jump-table arm that runs on into it.",
+      decidedBy: { symbol: 'STRUCTURE_VARIATIONS', file: RANK_VARIATIONS },
+    },
+    example: {
+      compiler: 'agbcc',
+      unit:
+        'struct E { s32 x; u8 id; u8 f; u8 u; u8 v; }; extern struct E gE[]; extern s32 gOut; void k(s32);\n' +
+        'void example(s32 lo, s32 hi) { s32 i; for (i = lo; i <= hi; i++) { switch (gE[i].id) { @ default: continue; } break; } }',
+      before:
+        'case 1: if (gE[i].u == 1) continue; if (gE[i].x > 20) continue; gOut = 1; k(i); break; ' +
+        'case 2: if (gE[i + 1].v != 0) continue; case 3: case 4: if (gE[i].x > 20) continue; gOut = 1; k(i); break; ' +
+        'case 7: k(7); break;',
+      after:
+        'case 1: if (gE[i].u == 1) continue; goto case_3; ' +
+        'case 2: if (gE[i + 1].v != 0) continue; case 3: case 4: case_3: if (gE[i].x > 20) continue; gOut = 1; k(i); ' +
+        'break; case 7: k(7); break;',
+      note: 'cases 1 and 2 both run on into the body of cases 3 and 4',
+    },
+    implementedIn: STRUCTURE,
+    seeAlso: ['tail-copies'],
+  },
 
   // ── respell ─────────────────────────────────────────────────────────────────────────────────
   unmerge: {
@@ -902,6 +1157,40 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     implementedIn: l3('unmerge'),
     seeAlso: ['initfirst', 'regionbase'],
   },
+  'case-end-goto': {
+    title: 'Search loop leaving its case by `goto`',
+    summary: "a search loop's hit that skips the rest of its `case` jumps to a label on the case's closing `break;`",
+    detail:
+      'When a loop inside a `case` has a second way out that skips the code after the loop and ends the ' +
+      '`case`, the default sets a flag before it leaves the loop and runs that code under `if (flag == 0)` ' +
+      'after it. This leaves the flag out: the second way out is `goto` to a label on the `break;` that ' +
+      'ends the case, and the code after the loop runs unguarded before that label. It is one of the two ' +
+      'kinds of `goto` asmlift writes.',
+    compilerBehavior:
+      'agbcc sends a `goto` to a `break;` straight to the end of the `switch`, and past a loop the switch ' +
+      'ends, so only the `goto` builds the bytes the source did; the flag adds a variable and its tests.',
+    offeredWhen: {
+      judges: "each flag set at a loop's own `break` and tested right after that loop",
+      gates: ['CASE_END_GOTO_GATES'],
+    },
+    example: {
+      compiler: 'agbcc',
+      unit:
+        'struct E { s32 x; u8 id; u8 f; u8 u; u8 v; }; extern struct E gE[]; extern s32 gLo, gHi; void k(s32);\n' +
+        'void example(s32 lo, s32 hi) { s32 i, j, h, a = 0; for (i = lo; i <= hi; i++) { if (gE[i].f <= 26) { ' +
+        'switch (gE[i].id) { @ default: continue; } break; } } k(a); }',
+      before:
+        'case 1: case 2: if (gE[i].x > 5) continue; h = 0; for (j = gLo; j <= gHi; j++) { if (i != j && gE[j].f == 28) ' +
+        '{ a = 1; k(j); h = 1; break; } } if (h == 0) { gE[i].f = 19; k(i); } break; case 4: k(i + 4); break;',
+      after:
+        'case 1: case 2: if (gE[i].x > 5) continue; for (j = gLo; j <= gHi; j++) { if (i != j && gE[j].f == 28) ' +
+        '{ a = 1; k(j); goto hit; } } gE[i].f = 19; k(i); hit: break; case 4: k(i + 4); break;',
+      note: 'the search loop in cases 1 and 2 either finds a hit, which skips the rest of the case, or runs out into it',
+    },
+    implementedIn: l3('caseendgoto'),
+    seeAlso: ['case-goto'],
+  },
+
   argbase: {
     title: 'Argument bases named before the call',
     summary: "the fixed addresses a call's arguments read are loaded into pointer locals first",
@@ -1630,7 +1919,31 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
       after: 'u8 v; v = gA[12] - 1; gB[14] = (v & 1) + f() % (5 - v) + 1;',
     },
     implementedIn: l3('narrowdecl'),
-    seeAlso: ['narrow-read', 'derived-home', 'escape-home'],
+    seeAlso: ['narrow-load', 'narrow-read', 'derived-home', 'escape-home'],
+  },
+  'narrow-load': {
+    title: 'Narrow load declared at its width',
+    summary: 'a local holding one narrow memory read is declared at that width instead of as an `s32`',
+    detail:
+      'A byte or halfword read from memory into a local can be spelled two ways: an `s32` local assigned the ' +
+      "read, or a local declared at the read's width. Every read of the local is the same value either way; " +
+      "which one the source declared is not in the assembly. Applied on top of every other candidate's source.",
+    compilerBehavior:
+      'agbcc loads a narrow local where it is written and an `s32` one where it is first read, so two byte ' +
+      'reads held across two calls are loaded at different points.',
+    offeredWhen: {
+      when: 'An `s32` local written once, outside a `for` init, by an element or member read of a narrower integer, in no memory.',
+      decidedBy: { symbol: 'narrowLoadDeclarations', file: l3('narrowdecl') },
+    },
+    example: {
+      compiler: 'agbcc',
+      unit: 'void f7(u8 *, u8 *, u8, u8, s32, u8, u8);\nvoid example(u8 *p, s32 x) { @ }',
+      before:
+        's32 a; s32 b; a = p[100]; b = p[101]; f7(p + 4, p + 8, a, b, x, 1, 2); f7(p + 8, p + 12, a, b, x, 3, 4);',
+      after: 'u8 a; u8 b; a = p[100]; b = p[101]; f7(p + 4, p + 8, a, b, x, 1, 2); f7(p + 8, p + 12, a, b, x, 3, 4);',
+    },
+    implementedIn: l3('narrowdecl'),
+    seeAlso: ['narrow-decl', 'narrow-read'],
   },
   'narrow-read': {
     title: 'Narrow value declared at its width, read bare',
@@ -1653,7 +1966,7 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
       after: 'u8 y; u8 m; y = cv(p[0]); m = cv(p[1]); return dc(y, m, (u8)cv(p[2]));',
     },
     implementedIn: l3('narrowdecl'),
-    seeAlso: ['narrow-decl'],
+    seeAlso: ['narrow-decl', 'narrow-load'],
   },
   'int-cell': {
     title: 'Global stored a pointer, spelled as an integer',

package/src/variation-gates.ts

@@ -11,6 +11,7 @@
 import { ADVANCE_HEAD_GATES, ADVANCE_MEMBER_GATES } from './l3/advance';
 import { ARGCOPY_GATES, ARGCOPY_REGION_GATES } from './l3/argcopy';
 import { BASEFOLD_GATES, LIVEBASE_BLOCK_GATES, LIVEBASE_GATES, ORDERBASE_GATES, UNFOLDED_GATES } from './l3/basecse';
+import { CASE_END_GOTO_GATES } from './l3/caseendgoto';
 import { ARM_DISJOINT_GATES, COALESCE_GATES } from './l3/coalesce';
 import type { Gate } from './l3/gates';
 import { HOMESPLIT_FAN_GATES, HOMESPLIT_GATES } from './l3/homesplit';
@@ -29,6 +30,7 @@ import {
 import { UNREDUCE_GATES } from './l3/unreduce';
 import { VOL_SLOT_GATES } from './l3/volatileval';
 import { VOL_STORE_GATES } from './l3/volstore';
+import { PARAM_READER_WIDTH_GATES } from './raise/paramwidth';
 import { ARM_REREAD_GATES } from './raise/shortcircuit';
 import { NAME_COALESCE_GATES } from './structure/namecoalesce';
 import { FRESH_MERGE_GATES } from './structure/structure';
@@ -48,6 +50,7 @@ export const VARIATION_GATE_TABLES = {
   ARM_DISJOINT_GATES,
   ARM_REREAD_GATES,
   BASEFOLD_GATES,
+  CASE_END_GOTO_GATES,
   COALESCE_GATES,
   COUNTDOWN_GATES,
   FRESH_MERGE_GATES,
@@ -59,6 +62,7 @@ export const VARIATION_GATE_TABLES = {
   NAME_COALESCE_GATES,
   OFFMEMBER_GATES,
   ORDERBASE_GATES,
+  PARAM_READER_WIDTH_GATES,
   PTR_FIELD_GATES,
   REGIONBASE_GATES,
   SCOPEBASE_ELIGIBILITY,