@asmlift/core 0.1.0

package/src/pipeline.ts

@@ -0,0 +1,272 @@
+// asmlift — the library entry point. `decompile(name, asm, target)` runs the raising tower and
+// returns structured results: the source, the per-level IR dumps, and diagnostics.
+import { cBackend } from './backend/c';
+import { ContractError, assertDerefsTyped, assertResolved, assertTypesRecovered } from './contracts';
+import type { AsmData } from './frontend/asmdata';
+import { FrontendUnsupportedError } from './frontend/errors';
+import { frontendFor } from './frontend/registry';
+import type { Fn } from './ir/core';
+import { print } from './ir/print';
+import { T } from './ir/types';
+import { VerifyError, verify } from './ir/verify';
+import { Expr, LanguageBackend, SFn, Stmt, exprChildren, stmtChildren, stmtExprs } from './l3/ast';
+import { hoistReusedGlobalBases } from './l3/basecse';
+import { eliminateDeadStores } from './l3/dce';
+import { DEFAULT_IDIOM_PATTERNS, RewritePattern, applyPattern, dce, patternApplies } from './pattern/engine';
+import type { Prototypes } from './proto';
+import { RaiseUnsupportedError } from './raise/errors';
+import { type PreRecoveryPass, runPreRecovery } from './raise/pre-recovery';
+import { recoverTypes } from './raise/recover';
+import { sinkReturns } from './raise/retsink';
+import { StructureError, structure } from './structure/structure';
+import { type TargetDescription, structureOptionsFor } from './target';
+
+/** How a gap (a construct asmlift cannot faithfully model) degrades:
+ *    "strict"   — throw / `"?"`-sentinel → ContractError. Loud in the PROCESS. The default, and
+ *                 what every contract/loud-fail test pins: asmlift knows when it doesn't know.
+ *    "annotate" — always emit SOMETHING (the m2c usefulness property), but every gap is loud in
+ *                 the ARTIFACT: a localizable gap becomes an undefined ASMLIFT_ERROR("reason", …)
+ *                 marker inline; a non-localizable failure (unliftable control flow, a broken
+ *                 invariant) degrades to a stub carrying the reason + the original asm as a
+ *                 comment. Either way the source cannot compile un-acknowledged, and the gaps are
+ *                 ALSO returned as structured `diagnostics` for the harness / self-improve loop. */
+export type OnGap = 'strict' | 'annotate';
+
+/** One machine-readable gap: which stage declined and why. The comments/markers in the emitted
+ *  source are the human projection of these entries — a tool should read THIS, not parse text. */
+export interface Diagnostic {
+  stage: 'lift' | 'raise' | 'structure' | 'contract' | 'verify' | 'internal';
+  reason: string;
+}
+
+export interface DecompileOptions {
+  backend?: LanguageBackend;
+  /** idiom patterns applied at L1. DEFAULTS to `DEFAULT_IDIOM_PATTERNS` (every idiom asmlift
+   *  owns, each `{compilers}`-gated so it self-selects per target). Pass an explicit list to
+   *  override, or `[]` to run the naive lift with no idiom folding. */
+  patterns?: RewritePattern[];
+  /** function prototypes from the project's headers, keyed by symbol: a callee's `params`
+   *  drives its `bl` argument recovery; the current function's own entry supplies its
+   *  `returnsVoid`. One table, resolved at the point of use (see proto.ts). */
+  prototypes?: Prototypes;
+  /** OPTIONAL Regime-B side-table (data-section jump tables + relocations). Absent ⇒ a dense
+   *  MIPS/PPC switch declines/loud-fails; present ⇒ the frontend recovers the `switch_br`.
+   *  Produced by `extractAsmData(obj, target)` from the scoring object. */
+  asmData?: AsmData;
+  /** gap policy — see `OnGap`. Default "strict". */
+  onGap?: OnGap;
+}
+
+export interface DecompileResult {
+  source: string;
+  sfn: SFn;
+  ir: { raw: string; folded: string; recovered: string }; // IR dumps: post-lift, post-idiom, post-recovery
+  patternHits: number;
+  /** structured gap list — ALWAYS present; empty ⇔ the emission is gap-free (compiles + candidate
+   *  for scoring). Non-empty ⇔ the source contains ASMLIFT_ERROR markers / a stub and will NOT
+   *  compile until the user defines that symbol (the loud-in-artifact contract). */
+  diagnostics: Diagnostic[];
+}
+
+export function decompile(
+  name: string,
+  asm: string,
+  target: TargetDescription,
+  opts: DecompileOptions = {},
+): DecompileResult {
+  const onGap = opts.onGap ?? 'strict';
+  if (onGap === 'strict') {
+    return runTower(name, asm, target, opts, 'strict');
+  }
+  try {
+    return runTower(name, asm, target, opts, 'annotate');
+  } catch (e) {
+    // A NON-localizable failure (unliftable control transfer, frame model, a broken internal
+    // invariant): there is no line to mark, so degrade to a stub — the failure reason + the
+    // original asm as comments, and one ASMLIFT_ERROR marker so the file stays uncompilable
+    // un-acknowledged. The user/LLM gets the raw material to finish by hand instead of a throw.
+    return stubResult(name, asm, opts.backend ?? cBackend, e);
+  }
+}
+
+function runTower(
+  name: string,
+  asm: string,
+  target: TargetDescription,
+  opts: DecompileOptions,
+  onGap: OnGap,
+): DecompileResult {
+  const backend = opts.backend ?? cBackend;
+  const prototypes = opts.prototypes ?? {};
+  // (1) lift: ISA frontend (resolved by target) → L1 with block-argument SSA
+  const fn = frontendFor(target).lift(name, asm, target, prototypes, opts.asmData);
+  verify(fn);
+  const raw = print(fn);
+
+  // (2) idiom fold: apply serializable patterns on the IR (the AI-improvement surface),
+  // gated generically by the Target's capabilities (not an `arch ==` branch).
+  const patternHits = applyIdiomPatterns(fn, target, opts.patterns);
+  const folded = print(fn);
+
+  // (2.35–3.5) pre-recovery recognizers → type recovery → return-sinking, the ONE shared spine
+  // (`raiseRecovered`) that trace.ts and the cli's rank.ts/report.ts also run.
+  raiseRecovered(fn, target);
+  const recovered = print(fn);
+
+  // (4) structure: IR → neutral AST; boundary contract: no unresolved value leaked (strict), or
+  // every unresolved value spelled as a loud ASMLIFT_ERROR marker (annotate).
+  const sfn = structureChecked(fn, { ...structureOptionsFor(target, prototypes[name]?.returnsVoid ?? false), onGap });
+
+  // (5) lower + print: neutral AST → target language
+  const source = backend.emit(sfn);
+
+  return { source, sfn, ir: { raw, folded, recovered }, patternHits, diagnostics: collectMarkers(sfn) };
+}
+
+// ── the shared raising tower ────────────────────────────────────────────────────────────────
+// decompile(), decompileTraced (trace.ts), and the cli's decompileRanked (rank.ts) /
+// decompileWithReport + its score probe (report.ts) all raise a lifted fn through the SAME
+// stage sequence. The optional hooks are the only per-caller
+// differences: rank pins its signedness candidate `beforeRecover`; the report pushes trace
+// entries after each stage. Every hook fires AFTER the stage's verify, so a hook can never
+// observe unverified IR.
+
+/** Stage 2 — idiom fold: filter the pattern set by target capabilities, apply, dce + verify.
+ *  Returns total hits. `patterns` defaults to DEFAULT_IDIOM_PATTERNS exactly like decompile(). */
+export function applyIdiomPatterns(fn: Fn, target: TargetDescription, patterns?: RewritePattern[]): number {
+  const active = (patterns ?? DEFAULT_IDIOM_PATTERNS).filter((p) => patternApplies(p, target));
+  let hits = 0;
+  for (const p of active) {
+    hits += applyPattern(fn, p);
+  }
+  if (active.length) {
+    dce(fn);
+    verify(fn);
+  }
+  return hits;
+}
+
+export interface RaiseHooks {
+  /** after each pre-recovery pass that changed the IR (fires after its verify) */
+  afterPass?: (pass: PreRecoveryPass, result: number | boolean) => void;
+  /** between pre-recovery and recoverTypes — rank.ts pins candidate signedness here */
+  beforeRecover?: () => void;
+  /** after recoverTypes + verify + assertTypesRecovered */
+  afterRecover?: () => void;
+  /** after return-sinking, only when it changed the fn (fires after its verify) */
+  afterRetsink?: () => void;
+}
+
+/** Stages 2.35–3.5 — pre-recovery recognizers (the shared ordered list in raise/pre-recovery.ts)
+ *  → type recovery (boundary contract: no `unknown` survives) → return-sinking (tail-duplicate a
+ *  return-only merge so short-circuits emit early returns). `verify` after every pass that
+ *  changed the IR. */
+export function raiseRecovered(fn: Fn, target: TargetDescription, hooks: RaiseHooks = {}): void {
+  runPreRecovery(fn, target, (pass, result) => {
+    verify(fn);
+    hooks.afterPass?.(pass, result);
+  });
+  hooks.beforeRecover?.();
+  recoverTypes(fn);
+  verify(fn);
+  assertTypesRecovered(fn);
+  hooks.afterRecover?.();
+  if (sinkReturns(fn)) {
+    verify(fn);
+    hooks.afterRetsink?.();
+  }
+}
+
+/** Stage 4 — structure + its boundary contracts, always as a pair. */
+export function structureChecked(fn: Fn, opts: Parameters<typeof structure>[1]): SFn {
+  const raw = structure(fn, opts);
+  // BOTH boundary contracts run on the pre-DCE tree: the readability pass must never be able to
+  // hide a structuring defect by dropping the dead statement that carries it. assertResolved
+  // catches an unresolved `?` value; assertDerefsTyped catches an ill-typed deref (e.g. a pointer
+  // under a rejected operator) — even one sitting in dead code structure emitted. DCE then only
+  // removes statements/flips branches over an already-validated tree.
+  assertResolved(raw);
+  assertDerefsTyped(raw);
+  // Then the readability/quality rewrites: drop dead stores, then hoist a reused aggregate-global
+  // base into a typed local pointer. The hoist moves the deref cast from each `index` node onto the
+  // local's initializer, so re-validate deref typing on the rewritten tree.
+  const sfn = hoistReusedGlobalBases(eliminateDeadStores(raw));
+  assertDerefsTyped(sfn);
+  return sfn;
+}
+
+// ── annotate-mode support ─────────────────────────────────────────────────────────────────
+
+/** Classify a caught failure by which stage's designed signal it is. `instanceof`, not name
+ *  strings: a renamed or newly-subclassed error class (PpcUnsupported subclasses
+ *  FrontendUnsupported) stays correctly classified instead of silently degrading to "internal". */
+function stageOf(e: unknown): Diagnostic['stage'] {
+  if (e instanceof FrontendUnsupportedError) {
+    return 'lift';
+  }
+  if (e instanceof RaiseUnsupportedError) {
+    return 'raise';
+  }
+  if (e instanceof StructureError) {
+    return 'structure';
+  }
+  if (e instanceof ContractError) {
+    return 'contract';
+  }
+  if (e instanceof VerifyError) {
+    return 'verify';
+  }
+  return 'internal';
+}
+
+/** The annotate-mode fallback for a failure with no line to mark: a compilable-shaped stub whose
+ *  body is one ASMLIFT_ERROR marker, headed by the reason + the ORIGINAL ASM as comments.
+ *  Exported for trace.ts (decompileTraced), whose annotate mode must degrade to the SAME stub
+ *  as decompile(). */
+export function stubResult(name: string, asm: string, backend: LanguageBackend, e: unknown): DecompileResult {
+  const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
+  const stage = stageOf(e);
+  const sfn: SFn = {
+    name,
+    params: [],
+    locals: [],
+    retType: T.void(),
+    body: [{ k: 'exprstmt', value: { k: 'marker', reason: `could not decompile (${stage}): ${msg}`, args: [] } }],
+  };
+  const header = [
+    backend.comment(`asmlift could not decompile '${name}' — ${stage}: ${msg}`),
+    backend.comment('original assembly:'),
+    ...asm
+      .split('\n')
+      .filter((l) => l.trim() !== '')
+      .map((l) => backend.comment(`  ${l}`)),
+  ];
+  return {
+    source: header.join('\n') + '\n' + backend.emit(sfn),
+    sfn,
+    ir: { raw: '', folded: '', recovered: '' },
+    patternHits: 0,
+    diagnostics: [{ stage, reason: msg }],
+  };
+}
+
+/** Every ASMLIFT_ERROR marker in the emitted AST, as a structured diagnostic (one per marker,
+ *  document order). The harness/self-improve loop reads THIS; the source text is for humans. */
+function collectMarkers(sfn: SFn): Diagnostic[] {
+  // On the shared exprChildren/stmtExprs/stmtChildren traversal. Order is exprs-then-children
+  // per statement — deterministic and near-document-order (a `for`'s cond is visited before its
+  // init; see the note on stmtChildren).
+  const out: Diagnostic[] = [];
+  const we = (e: Expr): void => {
+    if (e.k === 'marker') {
+      out.push({ stage: 'structure', reason: e.reason });
+    }
+    exprChildren(e).forEach(we);
+  };
+  const ws = (s: Stmt): void => {
+    stmtExprs(s).forEach(we);
+    stmtChildren(s).forEach(ws);
+  };
+  sfn.body.forEach(ws);
+  return out;
+}

package/src/proto.ts

@@ -0,0 +1,42 @@
+// asmlift — function prototypes: the single carrier for the caller-supplied facts a
+// matching-decomp project reads from its headers (arg counts, void-ness). One `Prototypes`
+// map, keyed by symbol, is threaded through every entry point and resolved at the point of
+// use — a callee's `params` gives its call-site arity, a function's own entry gives its
+// `returnsVoid`. It also keeps the frontend seam honest: a frontend receives prototypes,
+// not a grab-bag of ISA-specific options.
+
+/** One declared parameter, as its C type text (`"u8"`, `"s32"`, `"void *"`). asmlift consumes
+ *  only the COUNT today (call-site arity), but a project's header extraction naturally produces
+ *  the typed list, and keeping it lets a later pass pin an argument's width/signedness. */
+export type ParamType = string;
+
+/** What the headers know about one function. All fields optional: a partial table (only
+ *  callee arities, or only the current function's void-ness) is the common case. */
+export interface FnProto {
+  /** declared parameters — either a bare arity COUNT or the typed parameter list a header
+   *  extraction produces (`["u8", "s32"]`). BOTH forms yield the call-site arity via
+   *  `protoArity`; omit to let the frontend fall back to its contiguous-arg-register heuristic. */
+  params?: number | ParamType[];
+  /** the declared return type is `void`, so a trailing `bx lr` leaves a meaningless
+   *  return register that must not surface as a `return` value. */
+  returnsVoid?: boolean;
+}
+
+/** symbol → prototype. The function under decompilation and its callees share one table. */
+export type Prototypes = Record<string, FnProto>;
+
+/** The call-site arity a proto declares, normalizing the count form (`2`) and the typed-list
+ *  form (`["u8", "s32"]`) to one number. `undefined` when `params` is omitted — the caller then
+ *  falls back to its arg-register heuristic. Reading a typed list as its length is what lets a
+ *  header-derived proto (`params: ["u8"]`) recover its argument instead of silently dropping it. */
+export function protoArity(p: FnProto | undefined): number | undefined {
+  if (typeof p?.params === 'number') {
+    return p.params;
+  }
+  if (Array.isArray(p?.params)) {
+    return p.params.length;
+  }
+  // Omitted OR malformed (e.g. a bare `"u8"` string reaching the untyped CLI `--proto` JSON):
+  // fall back to the frontend's arg-register heuristic rather than misread a string's `.length`.
+  return undefined;
+}

package/src/raise/arrays.ts

@@ -0,0 +1,84 @@
+// asmlift — array-access LEGALIZATION (L1 → typed `aload`/`astore`).
+//
+// A compiler materialises a VARIABLE-index array access `a[i]` as an explicit scaled-address
+// computation before the memory op —
+//
+//   sll  t6, a1, 0x2        %s = shl %i {imm=2}         (index << log2 elemSize)
+//   addu t7, a0, t6         %p = add %base, %s          (base + scaled index)
+//   lw   v0, 0(t7)          %v = load %p {off=0,width=4,signed}
+//
+// which lifts to `load(add(base, shl(index, k)))` — an untyped byte-address the backend can
+// only spell as the uncompilable `*(base + (index << k))` (base was never typed a pointer, and
+// the shift would double-scale). This pass recognises that address shape and rewrites the
+// access to a typed `aload`/`astore` carrying `elemSize = 1 << k`, so type recovery types
+// `base` as `elem *` and structuring lowers it to the neutral `base[index]` index node.
+//
+// It is LEGALIZATION, not an idiom rewrite: the match needs the relation
+// `1 << shiftImm == accessWidth`, which the patterns-as-data idiom layer's `attrEquals`
+// (pattern/engine.ts) cannot state. Only the shift-scaled form is handled — elemSize = 1 << k
+// (2 or 4 in practice), where the shifted operand is unambiguously the index. The unscaled
+// byte form (`add(base, index)`, elemSize 1) is deferred: without types, base and index are
+// indistinguishable there.
+import { Fn, Op, Value, defOpMap, mkOp, mkValue, replaceAllUsesWith } from '../ir/core';
+
+// If `addr` is `add(base, shl(index, k))` with `1 << k === width`, return {base, index}.
+// The `add` is commutative, so the scaled side may be either operand.
+function scaledAddress(addr: Value, width: number, defs: Map<Value, Op>): { base: Value; index: Value } | null {
+  const add = defs.get(addr);
+  if (!add || add.opcode !== 'add' || add.operands.length !== 2) {
+    return null;
+  }
+  for (const [scaledSide, baseSide] of [
+    [0, 1],
+    [1, 0],
+  ] as const) {
+    const shl = defs.get(add.operands[scaledSide]);
+    if (!shl || shl.opcode !== 'shl' || shl.operands.length !== 1) {
+      continue;
+    } // must be `shl x {imm}`
+    if (1 << (shl.attrs.imm as number) !== width) {
+      continue;
+    }
+    return { base: add.operands[baseSide], index: shl.operands[0] };
+  }
+  return null;
+}
+
+/** Rewrite variable-index `load`/`store` (scaled-address form) into typed `aload`/`astore`.
+ *  Returns the number of accesses legalised. Dead address ops are then DCE'd. */
+export function recognizeArrays(fn: Fn): number {
+  let count = 0;
+  const defs = defOpMap(fn);
+  for (const b of fn.blocks) {
+    for (let i = 0; i < b.ops.length; i++) {
+      const op = b.ops[i];
+      if (op.opcode === 'load' && (op.attrs.off as number) === 0) {
+        const m = scaledAddress(op.operands[0], op.attrs.width as number, defs);
+        if (!m) {
+          continue;
+        }
+        const res = mkValue(op.results[0].type);
+        b.ops[i] = mkOp('aload', {
+          operands: [m.base, m.index],
+          results: [res],
+          attrs: { elemSize: op.attrs.width as number, signed: op.attrs.signed as boolean },
+        });
+        replaceAllUsesWith(fn, op.results[0], res);
+        count++;
+      } else if (op.opcode === 'store' && (op.attrs.off as number) === 0) {
+        const m = scaledAddress(op.operands[0], op.attrs.width as number, defs);
+        if (!m) {
+          continue;
+        }
+        b.ops[i] = mkOp('astore', {
+          operands: [m.base, m.index, op.operands[1]],
+          attrs: { elemSize: op.attrs.width as number },
+        });
+        count++;
+      }
+    }
+  }
+  // the now-dead `add`/`shl` address computation is reaped by the DRIVER's dce
+  // (pre-recovery.ts declares `dce: true` for this pass)
+  return count;
+}

package/src/raise/const.ts

@@ -0,0 +1,52 @@
+// asmlift — 32-bit constant materialisation (F-CONST; L1 recognition, ISA-neutral).
+//
+// A RISC target builds a 32-bit literal in two halves: a high-half load (MIPS `lui`, PPC `lis`) then a
+// low-half `ori`/`addiu`. The frontends lift that pair faithfully as `or(const(hi<<16), const(lo))` /
+// `add(const(hi<<16), const(lo))` — a live binary op over two `const` ops — because neither frontend can
+// see across the two instructions. This pass folds any such const/const `or`/`add` into a single `const`,
+// which is the form that (a) type-recovers as one 32-bit literal and (b) recompiles to the exact
+// `lui;ori` / `lis;ori` pair. Without it a magic-division reciprocal or an address literal is never a
+// single value the later passes can reason about.
+//
+// This cannot be a data-`RewritePattern`: the fold's result is COMPUTED from the two operands' values,
+// which the pattern engine's numeric-exact `attrEquals` cannot express. So it lives here as an always-on
+// recognizer, run before type recovery. Value-preserving and local; a single left-to-right pass suffices
+// (SSA guarantees each const is defined before the op that consumes it, and a folded result feeds
+// forward for any chained materialisation).
+import { Fn, Op, defOpMap, mkOp } from '../ir/core';
+
+// The binary opcodes whose const/const form is a constant. `>> 0` normalises to a signed 32-bit result
+// (hardware wraparound): `|` already yields int32, `+` may exceed it and is truncated to match `addu`/`add`.
+const FOLD: Record<string, (a: number, b: number) => number> = {
+  or: (a, b) => (a | b) >> 0,
+  add: (a, b) => (a + b) >> 0,
+};
+
+/** Fold each const/const `or`/`add` into one `const`, in place. Returns whether anything changed. The
+ *  now-dead source consts are left for DCE (they may still have other uses; liveness is not our concern). */
+export function recognizeConsts(fn: Fn): boolean {
+  let changed = false;
+  const defs = defOpMap(fn);
+  const constOf = (op: Op | undefined): number | null =>
+    op && op.opcode === 'const' ? (op.attrs.value as number) : null;
+  for (const b of fn.blocks) {
+    for (let i = 0; i < b.ops.length; i++) {
+      const op = b.ops[i];
+      const fold = FOLD[op.opcode];
+      if (!fold || op.operands.length !== 2 || op.results.length !== 1) {
+        continue;
+      }
+      const a = constOf(defs.get(op.operands[0]));
+      const c = constOf(defs.get(op.operands[1]));
+      if (a === null || c === null) {
+        continue;
+      }
+      // Reuse the SAME result Value → every existing use already points at it (no RAUW needed).
+      const folded = mkOp('const', { results: [op.results[0]], attrs: { value: fold(a, c) } });
+      b.ops.splice(i, 1, folded);
+      defs.set(op.results[0], folded); // keep the def map current so a chained fold sees this const
+      changed = true;
+    }
+  }
+  return changed;
+}

package/src/raise/errors.ts

@@ -0,0 +1,10 @@
+// asmlift — the shared DESIGNED loud-failure signal for RAISE passes (the frontend twin is
+// `FrontendUnsupportedError`). A raise pass throws this when it meets a shape it cannot faithfully
+// recover (an overlapping/packed struct layout, …). The class stays distinct from the frontend's
+// so `stageOf` (pipeline.ts) routes a raise decline to the "raise" Diagnostic stage, not "lift".
+export class RaiseUnsupportedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RaiseUnsupportedError';
+  }
+}