@asmlift/core 0.5.0 → 0.6.0

package/src/trace.ts

@@ -13,10 +13,18 @@ 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 } from './proto';
-import { type SymbolMap, symbolsByName } from './symbols';
+import { type Prototypes, prototypesFromSymbols } from './proto';
+import { assumedShapes, inferGlobalArrays, orderLicensedGlobals } from './raise/globalshape';
+import { type SymbolInfo, type SymbolMap, symbolsByName } from './symbols';
 import { type TargetDescription, structureOptionsFor } from './target';
 
+/** EVERY stage dump carries the write-order record (ir/print.ts `PrintOptions`) — not just
+ *  `stage:lift`, even though only the frontend measures it. Two reasons: the raising folds MUTATE
+ *  it (`foldWriteOrder`), so a stage that changes it and nothing else has something to show; and
+ *  the Pipeline tab dims a stage whose dump equals the previous one, which is a claim about the
+ *  whole program state and would be false if one dump carried the record and the next did not. */
+const irDump = (fn: Fn): string => print(fn, { writeOrder: true });
+
 export interface StageTrace {
   id: string; // stable localization anchor: "stage:lift", "stage:recover", …
   title: string; // human label = the transform this stage performs
@@ -52,6 +60,22 @@ export interface TraceReport {
   /** Set ONLY on the annotate-mode stub path (empty trace): the failure reason, machine-readable —
    *  so a consumer of the reasoning trail is not reduced to parsing the stub's source comments. */
   declineReason?: string;
+  /** The shapes the emitted source's spelling ASSUMES, derived from the assembly rather than read
+   *  from a map — pipeline.ts `DecompileResult.assumedSymbols`, and the same obligation: a
+   *  consumer showing the source must show these, because a bare `gSym[i]` means what the
+   *  declaration of `gSym` says it means.
+   *
+   *  NARROWER THAN THE `stage:globalshape` ENTRY ABOVE, on purpose. That entry reports what the
+   *  stage DERIVED, so a spelling decision downstream is attributable to a stage; this reports
+   *  what the SOURCE rests on, and a shape the structurer refused or a name the caller's own map
+   *  described is not an obligation the reader has (raise/globalshape.ts `assumedShapes`). */
+  assumedSymbols: SymbolInfo[];
+}
+
+/** `; dims [_][2]` for a derived rank, or '' for rank 1 — the trace note's tail. */
+function dimsNote(i: SymbolInfo): string {
+  const inner = i.shape === 'array' ? (i.dims ?? []).slice(1) : [];
+  return inner.length === 0 ? '' : `, dims [_]${inner.map((d) => `[${d ?? '?'}]`).join('')}`;
 }
 
 // Every knob decompile() takes must exist here with the SAME default — a surface that disagrees
@@ -64,8 +88,13 @@ export interface TraceOptions {
   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. */
-  probeScore?: (fn: Fn) => number | undefined;
+   *  pattern N's after-score is pattern N+1's before-score. Absent ⇒ score 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;
 }
 
 // The report's per-pass trace stage id + title, keyed by the shared PreRecoveryPass.id. Kept HERE
@@ -121,6 +150,7 @@ export function decompileTraced(
         asm,
         trace: [],
         patternEvents: [],
+        assumedSymbols: [],
         source: stub.source,
         declineReason: e instanceof Error ? e.message : String(e),
       },
@@ -135,7 +165,10 @@ function traceTower(
   opts: TraceOptions,
 ): { source: string; report: TraceReport } {
   const backend = opts.backend ?? cBackend;
-  const prototypes = opts.prototypes ?? {};
+  // 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 trace: StageTrace[] = [];
   const patternEvents: PatternEvent[] = [];
@@ -143,7 +176,27 @@ function traceTower(
   // (1) lift → typed-SSA IR
   const fn = frontendFor(target).lift(name, asm, target, prototypes, opts.asmData, opts.symbols);
   verify(fn);
-  trace.push({ id: 'stage:lift', title: 'Lift (ISA frontend → typed-SSA IR)', irDump: print(fn), verified: true });
+  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.
+  //
+  // IT GETS ITS OWN TRACE ENTRY because it is the one stage whose product is not the IR: it
+  // changes the DEFAULT spelling of every indexed global and leaves no mark in any `irDump`, so
+  // without a line here a reader following the trail from `stage:lift` to `stage:structure` sees
+  // `gTbl[i]` appear with nothing that produced it, and a wrong shape is attributable to no stage.
+  const inferredSymbols = inferGlobalArrays(fn, target);
+  const orderLicensed = orderLicensedGlobals(fn, target);
+  trace.push({
+    id: 'stage:globalshape',
+    title: 'Array shape from stride evidence (globals no symbol map describes)',
+    verified: true,
+    note:
+      inferredSymbols.size === 0
+        ? 'nothing evidenced — every indexed global keeps `((T *)&gSym)[i]`, valid under any declaration'
+        : [...inferredSymbols.values()]
+            .map((i) => `${i.name}: elem ${i.elemSize} ${i.elemSigned ? 'signed' : 'unsigned'}${dimsNote(i)}`)
+            .join('; '),
+  });
 
   // (2) idiom fold (capability-gated), with an optional probed score per pattern boundary —
   // the SAME default set as decompile()/decompileRanked
@@ -151,17 +204,17 @@ function traceTower(
   // 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);
+  let scoreBefore = opts.probeScore?.(fn, inferredSymbols);
   for (const p of active) {
-    const beforeIr = print(fn);
+    const beforeIr = irDump(fn);
     const hits = applyPattern(fn, p);
     dce(fn);
     verify(fn);
     if (hits === 0) {
       continue;
     }
-    const afterIr = print(fn);
-    const scoreAfter = opts.probeScore?.(fn);
+    const afterIr = irDump(fn);
+    const scoreAfter = opts.probeScore?.(fn, inferredSymbols);
     patternEvents.push({
       id: `pattern:${p.id}`,
       patternId: p.id,
@@ -178,7 +231,7 @@ function traceTower(
     trace.push({
       id: 'stage:idiom',
       title: `Idiom fold (${active.length} pattern(s), capability-gated)`,
-      irDump: print(fn),
+      irDump: irDump(fn),
       verified: true,
     });
   }
@@ -187,34 +240,55 @@ function traceTower(
   // type recovery → return-sinking, byte-identical to decompile()/decompileRanked by
   // construction. The trace's only additions are the entries, injected via the hooks
   // (each fires post-verify).
-  raiseRecovered(fn, target, {
-    afterPass: (pass, result) => {
-      // A pass with no registered strings still traces under a generic title: the traced tower
-      // must never crash (and so diverge from decompile()) just because a NEW pre-recovery pass
-      // landed before its trace entry did.
-      const t = PRE_RECOVERY_TRACE[pass.id] ?? {
-        stage: `stage:${pass.id}`,
-        title: () => `${pass.id} (pre-recovery pass)`,
-      };
-      trace.push({ id: t.stage, title: t.title(result), irDump: print(fn), verified: true });
+  raiseRecovered(
+    fn,
+    target,
+    {
+      afterPass: (pass, result) => {
+        // A pass with no registered strings still traces under a generic title: the traced tower
+        // must never crash (and so diverge from decompile()) just because a NEW pre-recovery pass
+        // landed before its trace entry did.
+        const t = PRE_RECOVERY_TRACE[pass.id] ?? {
+          stage: `stage:${pass.id}`,
+          title: () => `${pass.id} (pre-recovery pass)`,
+        };
+        trace.push({ id: t.stage, title: t.title(result), irDump: irDump(fn), verified: true });
+      },
+      afterRecover: () =>
+        trace.push({
+          id: 'stage:recover',
+          title: 'Type recovery (in-place on IR)',
+          irDump: irDump(fn),
+          verified: true,
+        }),
+      afterRetsink: () =>
+        trace.push({
+          id: 'stage:retsink',
+          title: 'Return-sinking (tail-duplicate return-only merge)',
+          irDump: irDump(fn),
+          verified: true,
+        }),
+      afterLatchFold: () =>
+        trace.push({
+          id: 'stage:latchfold',
+          title: 'Empty-latch folding (splice out an SSA-emptied back-edge block)',
+          irDump: irDump(fn),
+          verified: true,
+        }),
     },
-    afterRecover: () =>
-      trace.push({ id: 'stage:recover', title: 'Type recovery (in-place on IR)', irDump: print(fn), verified: true }),
-    afterRetsink: () =>
-      trace.push({
-        id: 'stage:retsink',
-        title: 'Return-sinking (tail-duplicate return-only merge)',
-        irDump: print(fn),
-        verified: true,
-      }),
-  });
+    prototypes[name],
+  );
 
   // (4) structure → neutral AST; boundary contract: no unresolved value leaked (strict) or
   // spelled as a loud ASMLIFT_ERROR marker (annotate) — same onGap lever as decompile()
+  const mapSymbols = opts.symbols ? symbolsByName(opts.symbols) : undefined;
   const sfn = structureChecked(fn, {
     ...structureOptionsFor(target, returnsVoid),
+    spellSwitchFallthrough: (opts.backend ?? cBackend).spellsSwitchFallthrough,
     onGap: opts.onGap ?? 'strict',
-    ...(opts.symbols ? { symbols: symbolsByName(opts.symbols) } : {}),
+    ...(mapSymbols ? { symbols: mapSymbols } : {}),
+    ...(inferredSymbols.size ? { inferredSymbols } : {}),
+    ...(orderLicensed.size ? { orderLicensedGlobals: orderLicensed } : {}),
   });
   trace.push({
     id: 'stage:structure',
@@ -243,6 +317,11 @@ function traceTower(
       trace,
       patternEvents,
       source,
+      // The same narrowing pipeline.ts's `DecompileResult` makes, and for the same reason: the
+      // `stage:globalshape` entry above reports what the STAGE derived, this reports what the
+      // SOURCE rests on, and they differ wherever a consumer refused the shape or the caller's
+      // own map already declared the name (raise/globalshape.ts `assumedShapes`).
+      assumedSymbols: assumedShapes(inferredSymbols, sfn, mapSymbols),
     },
   };
 }