@asmlift/core 0.8.0 → 0.9.0

package/src/trace.ts

@@ -2,20 +2,20 @@
 // 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, structureChecked, stubResult } from './pipeline';
+import { type Prototypes, declaresVoidReturn, prototypesFromSymbols } from './proto';
 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 +39,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 {
@@ -93,14 +93,15 @@ export interface TraceOptions {
   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
   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 +115,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 && / ||)' },
@@ -183,13 +190,12 @@ function traceTower(
   // 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 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);
   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 +218,28 @@ 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, target.compilerBehaviors) : [];
+  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 +249,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({
@@ -297,7 +317,7 @@ 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,
     onGap: opts.onGap ?? 'strict',
     ...(mapSymbols ? { symbols: mapSymbols } : {}),

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 {
@@ -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: {
@@ -729,6 +746,32 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     implementedIn: ANALYSIS,
     seeAlso: ['expr-home', 'fresh-merge'],
   },
+  '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:
+      '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'],
+  },
   'uns-cmp': {
     title: 'Unsigned compare spelled unsigned',
     summary: 'an unsigned compare carries a `(u32)` cast where its operands do not already say so',
@@ -794,7 +837,7 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
       compiler: 'agbcc',
       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 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 +1607,81 @@ 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-read', 'derived-home', 'escape-home'],
+  },
+  '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'],
+  },
+  '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-tokens.ts

@@ -85,6 +85,7 @@ const TOKENS = [
   { name: 'expr-home', variationKind: 'structure' },
   { name: 'derived-home', variationKind: 'structure' },
   { name: 'merge-home', variationKind: 'structure' },
+  { name: 'escape-home', variationKind: 'structure' },
   { name: 'uns-cmp', variationKind: 'structure' },
   { name: 'fresh-merge', variationKind: 'structure' },
   { name: 'copy-defpos', variationKind: 'structure' },
@@ -129,6 +130,13 @@ const TOKENS = [
   { name: 'initfirst', variationKind: 'respell' },
   { name: 'pollguard', variationKind: 'respell' },
   { name: 'pollread', variationKind: 'respell' },
+  { name: 'narrow-decl', 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 +290,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 +310,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 +320,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 +331,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 +350,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 +362,7 @@ export function tallyFanVariations(fan: {
           candidates: n.candidates,
           ...(n.dropped ? { dropped: n.dropped } : {}),
           ...(n.withheld ? { withheld: n.withheld } : {}),
+          ...(n.notCompiled ? { notCompiled: n.notCompiled } : {}),
         },
       ];
     }),