@asmlift/core 0.8.1 → 0.10.0

package/src/trace.ts

@@ -2,20 +2,21 @@
 // trail), browser-pure. Runs the SAME stage sequence as pipeline.ts and captures a TraceReport:
 // per-stage IR dumps (each post-verify) and per-pattern before/after events. Scoring lives on
 // the other side of the seam: @asmlift/cli/report enriches this into the full DecompileReport
-// (objdiff score, per-pattern score deltas via the `probeScore` hook, ranked candidates) when a
+// (objdiff score, per-pattern score deltas over the `probeSource` hook's sources, ranked candidates) when a
 // target object is available; the web playground renders the TraceReport as-is.
 import { cBackend } from './backend/c';
 import type { CodegenProfile } from './codegen-flags';
 import type { AsmData } from './frontend/asmdata';
-import { frontendFor } from './frontend/registry';
 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, raiseRecovered, structureChecked, stubResult } from './pipeline';
-import { type Prototypes, prototypesFromSymbols } from './proto';
+import { type OnGap, liftStamped, raiseRecovered, stampBehaviorsFor, structureChecked, 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';
 import { type ResolvedTarget, type TargetDescription, type ToolchainId, structureOptionsFor } from './target';
 
@@ -39,9 +40,9 @@ export interface PatternEvent {
   hits: number;
   beforeIr: string;
   afterIr: string;
-  scoreBefore?: number; // filled only when a probeScore hook is supplied (cli report)
-  scoreAfter?: number;
-  scoreDelta?: number; // negative = improved toward match
+  /** The source a `probeSource` hook emitted at this pattern's boundaries (the cli report scores them). */
+  sourceBefore?: string;
+  sourceAfter?: string;
 }
 
 export interface TraceReport {
@@ -92,15 +93,18 @@ 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()
   onGap?: OnGap; // "strict" (default) | "annotate", as in decompile()
-  /** Score probe at pattern boundaries (cli report's objdiff hook). One call per boundary:
-   *  pattern N's after-score is pattern N+1's before-score. Absent ⇒ score fields stay unset.
+  /** 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 ⇒
+   *  the source fields stay unset.
    *
    *  THE DERIVED ARRAY SHAPES TRAVEL WITH THE CLONE: they are read once off the lift
    *  (`stage:globalshape`) and change the default spelling of every indexed global, so a probe
    *  that structures without them attributes its per-pattern delta to a source the main path does
    *  not emit. */
-  probeScore?: (fn: Fn, inferredSymbols: Map<string, SymbolInfo>) => number | undefined;
+  probeSource?: (fn: Fn, inferredSymbols: Map<string, SymbolInfo>) => string | undefined;
 }
 
 // The report's per-pass trace stage id + title, keyed by the shared PreRecoveryPass.id. Kept HERE
@@ -114,6 +118,12 @@ const PRE_RECOVERY_TRACE: Record<string, { stage: string; title: (result: number
   const: { stage: 'stage:const', title: () => 'Const materialize (lui;ori → one 32-bit const)' },
   magicdiv: { stage: 'stage:magicdiv', title: () => 'Magic-number division recovery (mulh/mulhu → sdiv/udiv)' },
   softdiv: { stage: 'stage:softdiv', title: () => 'Soft-division lower (bl __divsi3 → division op)' },
+  floathelpers: {
+    stage: 'stage:floathelpers',
+    title: () => 'Soft-float lower (bl __adddf3 → float op, a declared double, a literal)',
+  },
+  widehelpers: { stage: 'stage:widehelpers', title: () => '64-bit helper lower (bl __muldi3 → 64-bit op)' },
+  pairparams: { stage: 'stage:pairparams', title: () => 'Parameter pairs (two argument registers → one s64)' },
   arrays: { stage: 'stage:legalize', title: (r) => `Array legalize (${r} scaled access(es) → aload/astore)` },
   structs: { stage: 'stage:structs', title: () => 'Struct-pointer recovery (access-pattern evidence)' },
   shortcircuit: { stage: 'stage:shortcircuit', title: () => 'Short-circuit recovery (boolean && / ||)' },
@@ -182,14 +192,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 returnsVoid = prototypes[name]?.returnsVoid ?? false;
+  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 = frontendFor(target).lift(name, asm, target, prototypes, opts.asmData, opts.symbols);
-  verify(fn);
+  const fn = liftStamped(
+    name,
+    asm,
+    target,
+    prototypes,
+    opts.asmData,
+    opts.symbols,
+    opts.contextGlobals,
+    undefined,
+    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.
@@ -212,13 +232,30 @@ function traceTower(
             .join('; '),
   });
 
-  // (2) idiom fold (capability-gated), with an optional probed score per pattern boundary —
+  // 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, stampBehaviorsFor(target, opts.contextGlobals))
+    : [];
+  trace.push({
+    id: 'stage:offsetnames',
+    title: 'Name a walked-to address the symbol map knows',
+    irDump: irDump(fn),
+    verified: true,
+    note:
+      named.length === 0
+        ? 'no address built off a named one lands on a symbol the map names'
+        : `${named.length} address${named.length === 1 ? '' : 'es'} named: ${named.join(', ')}`,
+  });
+
+  // (2) idiom fold (capability-gated), with an optional probed source per pattern boundary —
   // the SAME default set as decompile()/decompileRanked
   const active = (opts.patterns ?? DEFAULT_IDIOM_PATTERNS).filter((p) => patternApplies(p, target));
-  // Probe economy: ONE probe per pattern boundary — pattern N's after-score IS pattern N+1's
-  // before-score (the state is identical), and each probe costs a full clone + tower + external
-  // compile + objdiff. Zero-hit patterns emit NO event (the IR is unchanged).
-  let scoreBefore = opts.probeScore?.(fn, inferredSymbols);
+  // Probe economy: ONE probe per pattern boundary — pattern N's after-source IS pattern N+1's
+  // before-source (the state is identical), and each probe costs a full clone + tower. Zero-hit
+  // patterns emit NO event (the IR is unchanged).
+  let sourceBefore = opts.probeSource?.(fn, inferredSymbols);
   for (const p of active) {
     const beforeIr = irDump(fn);
     const hits = applyPattern(fn, p, target);
@@ -228,18 +265,17 @@ function traceTower(
       continue;
     }
     const afterIr = irDump(fn);
-    const scoreAfter = opts.probeScore?.(fn, inferredSymbols);
+    const sourceAfter = opts.probeSource?.(fn, inferredSymbols);
     patternEvents.push({
       id: `pattern:${p.id}`,
       patternId: p.id,
       hits,
       beforeIr,
       afterIr,
-      scoreBefore,
-      scoreAfter,
-      scoreDelta: scoreBefore !== undefined && scoreAfter !== undefined ? scoreAfter - scoreBefore : undefined,
+      sourceBefore,
+      sourceAfter,
     });
-    scoreBefore = scoreAfter;
+    sourceBefore = sourceAfter;
   }
   if (active.length) {
     trace.push({
@@ -282,10 +318,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,
         }),
@@ -297,10 +333,12 @@ function traceTower(
   // 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),
+    ...structureOptionsFor(target, returnsVoid, prototypes),
     spellSwitchFallthrough: (opts.backend ?? cBackend).spellsSwitchFallthrough,
+    spellSwitchBreak: (opts.backend ?? cBackend).spellsSwitchBreak,
     onGap: opts.onGap ?? 'strict',
     ...(mapSymbols ? { symbols: mapSymbols } : {}),
+    ...(opts.contextGlobals ? { contextGlobals: opts.contextGlobals } : {}),
     ...(inferredSymbols.size ? { inferredSymbols } : {}),
     ...(orderLicensed.size ? { orderLicensedGlobals: orderLicensed } : {}),
   });

package/src/variation-definitions.ts

@@ -64,6 +64,11 @@ export const READER_WORDS: readonly ReaderWord[] = [
     word: 'withheld',
     meaning: 'A candidate that compiled and scored, but was refused publication for want of a byte-exact proof.',
   },
+  {
+    word: 'not compiled',
+    meaning:
+      "A candidate never handed to the scorer: its fan was stillborn — in each signedness half, the default candidate and one probe per variation were all rejected, every probe keeping one of its default's errors, so the rest was not compiled.",
+  },
 ];
 
 export interface VariationKindDefinition {
@@ -91,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',
@@ -195,6 +200,18 @@ export const TARGET_BEHAVIOR_READINGS: { readonly [B in GatingBehavior]: TargetB
         'the span is how far one instruction can add to a base register, a fact of the instruction set that no pair of spellings decides',
     },
   },
+  pointerIntConversionIsFree: {
+    reads: 'builds a word global read or stored through a pointer conversion into the integer spelling',
+    witness: {
+      compiler: 'agbcc',
+      unit: 'extern u32 g; extern u32 gLimit; void sink(void); u32 example(u32 a) { @ }',
+      spellings: [
+        '*(s32 *)g = a; g = (void *)((u8 *)g + 4); sink(); return (gLimit ^ (u32)g) < 1;',
+        '*(s32 *)g = a; g = g + 4; sink(); return (gLimit ^ g) < 1;',
+      ],
+      compiles: 'same',
+    },
+  },
   foldsPointerAdvance: {
     reads: 'folds a stepped pointer back into an offset load',
     witness: {
@@ -279,7 +296,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',
@@ -354,6 +371,31 @@ 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`',
@@ -403,6 +445,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': {
@@ -729,14 +828,42 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     implementedIn: ANALYSIS,
     seeAlso: ['expr-home', 'fresh-merge'],
   },
-  'uns-cmp': {
-    title: 'Unsigned compare spelled unsigned',
-    summary: 'an unsigned compare carries a `(u32)` cast where its operands do not already say so',
+  'escape-home': {
+    title: 'Narrowed value named where it was narrowed',
+    summary: 'a widening or narrowing whose readers are all elsewhere is computed once, at its own place',
     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.',
+      'A value narrowed or widened from another, read two or more times and never in the place it was ' +
+      'computed, gets a local there — the register the machine narrowed into once and every later block ' +
+      'read. By default the cast is written out again at each reader.',
+    offeredWhen: {
+      when: "A symbol-map setting's own lift narrows or widens a value whose two or more readers are all elsewhere.",
+      decidedBy: { symbol: 'hasEscapingExtension', file: ANALYSIS },
+    },
+    example: {
+      compiler: 'agbcc',
+      unit: CALLS + 's32 example(void) { @ }',
+      before:
+        's32 v; u32 n; u32 i; n = 0; ' +
+        'do { i = 0; do { v = f(); i = i + 1; } while (i <= 63); } while ((u16)v != 0 && n++ <= 9); ' +
+        'return (u16)v;',
+      after:
+        's32 v; s32 t; u32 n; u32 i; n = 0; ' +
+        'do { i = 0; do { v = f(); t = (u16)v; i = i + 1; } while (i <= 63); } while (t != 0 && n++ <= 9); ' +
+        'return t;',
+    },
+    implementedIn: ANALYSIS,
+    seeAlso: ['expr-home', 'derived-home'],
+  },
+  '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:
+      '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: {
@@ -746,8 +873,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'],
@@ -792,9 +919,13 @@ 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 example(s32 a0, s32 a1, s32 c) { s32 v1; s32 v2; if (c) { v1 = f(); v2 = g(); } else { @ } return h(v1, v2); }',
+        '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;',
       note: 'the copies at the end of one path into a merge',
@@ -1564,6 +1695,105 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     implementedIn: l3('pollguard'),
     seeAlso: ['pollguard'],
   },
+  'narrow-decl': {
+    title: 'Narrow value declared at its width',
+    summary: 'a local holding one narrowed value is declared at that width instead of as an `s32` with a cast',
+    detail:
+      'A value narrowed once and read as a local can be spelled two ways: an `s32` assigned the narrowing ' +
+      'cast, or a local declared at the narrow width. Every read is an `int` either way, so the value is the ' +
+      "same; which one the source declared is not in the assembly. Applied on top of every other candidate's source.",
+    compilerBehavior:
+      "gcc 2.9's front end sees through the promotion of a narrow variable and not through a cast assigned " +
+      'to an `int`, so compares, divisions and right shifts of an unsigned narrow one become unsigned; ' +
+      'where none reads it, agbcc can still allocate registers differently. IDO, KMC gcc and gcc 2.7.2 ' +
+      'each emit different code for the example too, and every mwcc build does for a compare of it.',
+    offeredWhen: {
+      when: 'An `s32` local written once, outside a `for` init, by an integer narrowed to a narrower integer, that lives in no memory.',
+      decidedBy: { symbol: 'narrowDeclarations', file: l3('narrowdecl') },
+    },
+    example: {
+      compiler: 'agbcc',
+      unit: CALLS + 'extern u8 gA[]; extern u8 gB[]; void example(void) { @ }',
+      before: 's32 v; v = (u8)(gA[12] - 1); gB[14] = (v & 1) + f() % (5 - v) + 1;',
+      after: 'u8 v; v = gA[12] - 1; gB[14] = (v & 1) + f() % (5 - v) + 1;',
+    },
+    implementedIn: l3('narrowdecl'),
+    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',
+    summary: 'a local read only through one narrowing cast is declared at that width instead of at 32 bits',
+    detail:
+      'A value stored whole and narrowed wherever it is read can be spelled two ways: a 32-bit local cast at every ' +
+      'read, or a local declared at the narrow width and read bare. Every read 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:
+      'A narrow local is extended as it is stored, where the cast extends at each read, after whatever ran in ' +
+      'between: agbcc moves the extension of a call result held across a second call.',
+    offeredWhen: {
+      when: 'A 32-bit local in no memory, written by integers or calls but not in a `for` header, and narrowed by one cast at every read.',
+      decidedBy: { symbol: 'narrowReadDeclarations', file: l3('narrowdecl') },
+    },
+    example: {
+      compiler: 'agbcc',
+      unit: 'u32 cv(u8); u16 dc(u8, u8, u8);\nu16 example(u8 *p) { @ }',
+      before: 's32 y; s32 m; y = cv(p[0]); m = cv(p[1]); return dc((u8)y, (u8)m, (u8)cv(p[2]));',
+      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', 'narrow-load'],
+  },
+  'int-cell': {
+    title: 'Global stored a pointer, spelled as an integer',
+    summary: 'a global the function stores a pointer into is written as an integer: `g = g + K`, no conversions',
+    detail:
+      'A global the function stores a pointer into is written as a pointer by default: `g = (void *)((u8 *)g + K)` ' +
+      'for the byte the assembly addressed, `(u32)g` where the value is used as an integer, and a `void *` ' +
+      'declaration. A project that declares the global an integer wrote `g = g + K` and no conversion, and a ' +
+      'pointer declaration scales that offset instead, so which one is right depends on a declaration the ' +
+      'assembly does not show. Published only when the candidate matches byte for byte; otherwise it is withheld.',
+    compilerBehavior:
+      'CodeWarrior rejects a pointer stored into an integer global; IDO allocates registers differently around ' +
+      'a `(u32)` conversion of one.',
+    offeredWhen: {
+      when:
+        'A store of a `void *` value into a global no declaration in the function types and the symbol map ' +
+        'declares, if at all, an integer.',
+      decidedBy: { symbol: 'integerCells', file: l3('intcell') },
+    },
+    example: {
+      compiler: 'ido',
+      unit: 'extern u32 g; extern u32 gLimit; void sink(void);\nu32 example(u32 a) { @ }',
+      before: '*(s32 *)g = a; g = (void *)((u8 *)g + 4); sink(); return (gLimit ^ (u32)g) < 1;',
+      after: '*(s32 *)g = a; g = g + 4; sink(); return (gLimit ^ g) < 1;',
+      note: 'under the integer declaration the `after` spelling was written against',
+    },
+    implementedIn: l3('intcell'),
+  },
 
   // ── symbol map ──────────────────────────────────────────────────────────────────────────────
   'raw-globals': {

package/src/variation-gates.ts

@@ -29,6 +29,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';
@@ -59,6 +60,7 @@ export const VARIATION_GATE_TABLES = {
   NAME_COALESCE_GATES,
   OFFMEMBER_GATES,
   ORDERBASE_GATES,
+  PARAM_READER_WIDTH_GATES,
   PTR_FIELD_GATES,
   REGIONBASE_GATES,
   SCOPEBASE_ELIGIBILITY,

package/src/variation-tokens.ts

@@ -67,8 +67,11 @@ const TOKENS = [
   // lift: the assembly lifted or raised again
   { name: 'setup-args', variationKind: 'lift' },
   { name: 'connective', variationKind: 'lift' },
+  { name: 'narrow-param', variationKind: 'lift' },
   { name: 'shared-ret', variationKind: 'lift' },
   { name: 'shared-tail', variationKind: 'lift' },
+  { name: 'kept-slot', variationKind: 'lift' },
+  { name: 'far-cast', variationKind: 'lift' },
   // structure: `structure()` re-run with other options
   { name: 'flip-branch', variationKind: 'structure' },
   { name: 'defsite', variationKind: 'structure' },
@@ -85,7 +88,8 @@ const TOKENS = [
   { name: 'expr-home', variationKind: 'structure' },
   { name: 'derived-home', variationKind: 'structure' },
   { name: 'merge-home', variationKind: 'structure' },
-  { name: 'uns-cmp', variationKind: 'structure' },
+  { name: 'escape-home', variationKind: 'structure' },
+  { name: 'signed-cmp', variationKind: 'structure' },
   { name: 'fresh-merge', variationKind: 'structure' },
   { name: 'copy-defpos', variationKind: 'structure' },
   { name: 'site-sense', variationKind: 'structure' },
@@ -129,6 +133,14 @@ const TOKENS = [
   { name: 'initfirst', variationKind: 'respell' },
   { name: 'pollguard', variationKind: 'respell' },
   { name: 'pollread', variationKind: 'respell' },
+  { name: 'narrow-decl', variationKind: 'respell' },
+  { name: 'narrow-load', variationKind: 'respell' },
+  { name: 'narrow-read', variationKind: 'respell' },
+  {
+    name: 'int-cell',
+    variationKind: 'respell',
+    target: { behavior: 'pointerIntConversionIsFree', declared: false },
+  },
   // symbol map: the map's shaped spellings withheld; always the last part
   { name: 'raw-globals', variationKind: 'symbol-map' },
 ] as const satisfies readonly VariationToken[];
@@ -282,12 +294,15 @@ export function splitVariations(name: string): string[] {
 }
 
 /** How many of one fan's candidates carry one variation. `candidates` counts the whole fan —
- *  scored, dropped and withheld alike — and `dropped` and `withheld` are the refused part of that
- *  count, each absent when 0. */
+ *  scored, dropped, withheld and never compiled alike — and `dropped`, `withheld` and
+ *  `notCompiled` are the parts of that count the ranking did not score, each absent when 0.
+ *  `notCompiled` is not a refusal: nothing was compiled (core stillborn.ts), and a tally that
+ *  folded it into `dropped` would report compile failures that never ran. */
 export interface VariationTally {
   candidates: number;
   dropped?: number;
   withheld?: number;
+  notCompiled?: number;
 }
 
 interface NamedCandidate {
@@ -299,7 +314,7 @@ interface NamedCandidate {
  *  (`coalesce-v0-v1` and `coalesce-v2-v3` are both `coalesce`), and a candidate counts once under
  *  each name it carries however many subjects it applies it to.
  *
- *  `fan` is ranking's three-way partition, which puts every enumerated candidate in exactly one
+ *  `fan` is ranking's four-way partition, which puts every enumerated candidate in exactly one
  *  list, so each signedness entry's `candidates` sums with the other's to the fan size.
  *
  *  A tally, not a factorisation: enumeration gates prune the fan, so the counts do not multiply to
@@ -309,6 +324,7 @@ export function tallyFanVariations(fan: {
   candidates: readonly NamedCandidate[];
   dropped: readonly NamedCandidate[];
   withheld: readonly NamedCandidate[];
+  notCompiled: readonly NamedCandidate[];
 }): Record<string, VariationTally> {
   const registeredName = new Map<string, string>();
   const nameOf = (part: string): string => {
@@ -319,13 +335,13 @@ export function tallyFanVariations(fan: {
     }
     return name;
   };
-  const counts = new Map<string, { candidates: number; dropped: number; withheld: number }>();
-  const add = (list: readonly NamedCandidate[], refusal: 'dropped' | 'withheld' | undefined): void => {
+  const counts = new Map<string, { candidates: number; dropped: number; withheld: number; notCompiled: number }>();
+  const add = (list: readonly NamedCandidate[], refusal: 'dropped' | 'withheld' | 'notCompiled' | undefined): void => {
     for (const c of list) {
       for (const name of new Set(c.variations.map(nameOf))) {
         let n = counts.get(name);
         if (n === undefined) {
-          n = { candidates: 0, dropped: 0, withheld: 0 };
+          n = { candidates: 0, dropped: 0, withheld: 0, notCompiled: 0 };
           counts.set(name, n);
         }
         n.candidates++;
@@ -338,6 +354,7 @@ export function tallyFanVariations(fan: {
   add(fan.candidates, undefined);
   add(fan.dropped, 'dropped');
   add(fan.withheld, 'withheld');
+  add(fan.notCompiled, 'notCompiled');
   const kindIndex = (name: string): number => VARIATION_KINDS.indexOf(variationToken(name).variationKind);
   const names = [...counts.keys()].sort((a, b) => kindIndex(a) - kindIndex(b) || (a < b ? -1 : a > b ? 1 : 0));
   return Object.fromEntries(
@@ -349,6 +366,7 @@ export function tallyFanVariations(fan: {
           candidates: n.candidates,
           ...(n.dropped ? { dropped: n.dropped } : {}),
           ...(n.withheld ? { withheld: n.withheld } : {}),
+          ...(n.notCompiled ? { notCompiled: n.notCompiled } : {}),
         },
       ];
     }),