@asmlift/core 0.1.0

package/src/backend/cpp.ts

@@ -0,0 +1,145 @@
+// asmlift — the C++ language backend. Emits IDIOMATIC, de-mangled C++ — a member function with
+// scope resolution (`Vec::dot`), an implicit `this`, and named member access — reusing the
+// shared C-family printer (backend/cfamily.ts) for the body VERBATIM, because a CodeWarrior
+// member function's body is byte-identical to the same C with `this` explicit. Only the
+// DIVERGENT C++ surface lives here: the scoped/`this` signature, the class declaration, member
+// access, and the mangled SYMBOL (src/mangle.ts) that objdiff aligns the candidate by.
+//
+// What it consumes beyond the neutral SFn — supplied like `prototypes` (a decomp project has its
+// class layouts in headers, exactly as it has function prototypes): the owning class + method
+// name, the explicit parameter names/types, and the field layout of each class touched (so an
+// indexed load `this[1]` becomes the named `y`).
+//
+// Scope: free functions and non-virtual member functions with scalar/pointer params and named
+// field access. Virtual dispatch, references, and constructors/destructors are deliberately not
+// built ahead of an inhabitant.
+import { Expr, LanguageBackend, SFn } from '../l3/ast';
+import { type CppType, mangle, spellType } from '../mangle';
+import { LeafHook, cComment, emitCFamily } from './cfamily';
+
+export interface CppClass {
+  fields: { name: string; type: CppType }[];
+} // field i at word offset i
+export interface CppFnSpec {
+  method: string; // idiomatic function / method name
+  cls?: string; // owning class (member fn); omit for a free fn
+  retType: CppType;
+  params: { name: string; type: CppType }[]; // EXPLICIT params (the implicit `this` excluded)
+  classes?: Record<string, CppClass>; // layouts for named member access
+}
+
+/** The mangled CodeWarrior symbol this spec compiles to — the objdiff alignment key. */
+export function cppSymbol(spec: CppFnSpec): string {
+  return mangle({ name: spec.method, cls: spec.cls, params: spec.params.map((p) => p.type) });
+}
+
+/** Build a C++ backend for one function, parameterized by its recovered C++ signature. The lifted
+ *  SFn params are positional: for a member function SFn.params[0] is `this`, the rest are `params`. */
+export function cppBackend(spec: CppFnSpec): LanguageBackend {
+  return {
+    id: 'cpp',
+    emit(fn: SFn): string {
+      // Map each lifted param var → its C++ meaning: `this` (bare member access) or a named param
+      // (a pointer-to-class param uses `->`). A pointer-to-known-class param is a member receiver.
+      const thisVar = spec.cls ? fn.params[0]?.name : undefined;
+      const explicitStart = spec.cls ? 1 : 0;
+      const rename = new Map<string, string>(); // lifted var → C++ name
+      const recv = new Map<string, { cls: string; via: 'this' | string }>(); // var → member receiver
+      if (thisVar) {
+        rename.set(thisVar, 'this');
+        recv.set(thisVar, { cls: spec.cls!, via: 'this' });
+      }
+      spec.params.forEach((p, i) => {
+        const v = fn.params[explicitStart + i]?.name;
+        if (!v) {
+          return;
+        }
+        rename.set(v, p.name);
+        if (p.type.ptr === 1 && spec.classes?.[p.type.base]) {
+          recv.set(v, { cls: p.type.base, via: p.name });
+        }
+      });
+
+      const field = (cls: string, k: number): string => {
+        const fields = spec.classes?.[cls]?.fields ?? [];
+        // The lifted index `k` counts WORD offsets. It coincides with the sequential field
+        // position ONLY when every field is word-sized (4 bytes), so a `short`/`char`/mixed-width
+        // struct would map `k` to the WRONG field. Rather than emit silently-wrong idiomatic C++,
+        // fail LOUD: a mixed layout needs byte-offset field resolution, which is follow-on work.
+        if (!fields.every((f) => typeWidth(f.type) === 4)) {
+          throw new Error(
+            `cpp backend: class ${cls} has a sub-word/mixed field layout — member access needs byte-offset recovery (not yet supported)`,
+          );
+        }
+        const f = fields[k];
+        if (!f) {
+          throw new Error(`cpp backend: no field at word offset ${k} of class ${cls}`);
+        }
+        return f.name;
+      };
+      // Leaf hook: rewrite an indexed access on a receiver into named member access, and a bare
+      // receiver/param var into its C++ name. Everything else falls through to shared C spelling.
+      //
+      // The member rewrite fires ONLY for a WORD access (`width === 4`): the word-index `field()`
+      // mapping assumes idx counts words, and the all-word-layout guard above checks the CLASS,
+      // not the ACCESS — a sub-word access on a word field (`lhz` from offset 4) would map its
+      // byte-scaled idx to the wrong member and read the wrong width, silently. The sub-word
+      // receiver access is spelled HERE too (the honest reinterpret cast, `((s16 *)this)[2]`):
+      // it cannot fall through to the shared legalization, because the hook RENAMES the receiver
+      // — the shared printer would judge the SFn var's recovered type while the reader sees the
+      // class pointer, and print an unscaled `this[2]` that C++ strides by sizeof(class).
+      // Correct bytes over idiomatic spelling, never the reverse.
+      const leaf: LeafHook = (e: Expr) => {
+        if (e.k === 'index' && e.base.k === 'var' && e.idx.k === 'const') {
+          const r = recv.get(e.base.name);
+          if (r) {
+            if (e.width === 4) {
+              return r.via === 'this' ? field(r.cls, e.idx.value) : `${r.via}->${field(r.cls, e.idx.value)}`;
+            }
+            if (e.width === 1 || e.width === 2) {
+              return `((${e.signed ? 's' : 'u'}${e.width * 8} *)${r.via === 'this' ? 'this' : r.via})[${e.idx.value}]`;
+            }
+            // any other width is a struct-array STRIDE (a dot-form base) — not this rewrite's
+            // shape; fall through to the shared spelling so `.field` stays intact.
+          }
+        }
+        if (e.k === 'var') {
+          const nm = rename.get(e.name);
+          if (nm) {
+            return nm;
+          }
+        }
+        return null;
+      };
+
+      const paramList = spec.params.map((p) => `${spellType(p.type)} ${p.name}`).join(', ');
+      const decls = classDecls(spec, paramList);
+      const signature = `${spellType(spec.retType)} ${spec.cls ? spec.cls + '::' : ''}${spec.method}(${paramList})`;
+      return (decls ? decls + '\n' : '') + emitCFamily(signature, fn, leaf);
+    },
+    comment: cComment, // C++ shares C's block-comment spelling
+  };
+}
+
+// Byte width of a C++ type (a pointer is always word-sized). Used to reject a sub-word field layout
+// the word-index member-access mapping cannot represent.
+function typeWidth(t: CppType): number {
+  if (t.ptr > 0) {
+    return 4;
+  }
+  return (
+    { char: 1, bool: 1, 'unsigned char': 1, short: 2, 'unsigned short': 2, 'long long': 8, double: 8 }[t.base] ?? 4
+  );
+}
+
+// The class declaration(s) a member/field-accessing function needs to compile: fields in word-offset
+// order, plus the method prototype inside its owning class.
+function classDecls(spec: CppFnSpec, paramList: string): string {
+  const out: string[] = [];
+  for (const [cname, cdef] of Object.entries(spec.classes ?? {})) {
+    const fields = cdef.fields.map((f) => `${spellType(f.type)} ${f.name};`).join(' ');
+    const method = cname === spec.cls ? ` ${spellType(spec.retType)} ${spec.method}(${paramList});` : '';
+    out.push(`struct ${cname} { ${fields}${method} };`);
+  }
+  return out.join('\n');
+}

package/src/backend/pascal.ts

@@ -0,0 +1,279 @@
+// asmlift — the IDO / SGI Pascal backend. Consumes the SAME
+// language-neutral L3 AST as the C backend; every divergence lives here: `:=` assignment,
+// `if..then..else`, and the neutral "return a value" node lowered to Pascal's name-assignment
+// idiom (`FnName := expr`).
+//
+// DIALECT NOTE (verified against IDO 7.1 `upas`): in SGI Pascal `and`/`or`/`not` are BOOLEAN
+// operators — using them on integers is a type error ("operand(s) must be boolean"). Bitwise
+// and shift operations are INTRINSIC FUNCTIONS: bitand/bitor/bitxor/bitnot and lshift/rshift.
+// (`rshift` is arithmetic on a signed Integer → `sra`.) This is the concrete difference from
+// Turbo/Delphi/FreePascal.
+import { IrType, typeToString } from '../ir/types';
+import { BinOp, Expr, LanguageBackend, SFn, Stmt } from '../l3/ast';
+import { type VarTypes, declaredTypes, derefStrideOk, exprCType } from '../l3/typing';
+
+// Infix operators IDO Pascal spells directly.
+const OP: Partial<Record<BinOp, string>> = {
+  // NOTE: no `%`. IDO Pascal `mod` is ISO (result in [0, n), sign of the DIVISOR), which does NOT
+  // match C's truncated `%` (sign of the DIVIDEND) — verified: `a mod 3` mis-scores against the
+  // IDO C `a % 3` codegen. There is no faithful IDO-Pascal spelling of a signed C remainder, so the
+  // backend fails LOUD on `%` (below) rather than emit a silently-wrong `mod`. `/`→`div` DOES match.
+  '+': '+',
+  '-': '-',
+  '*': '*',
+  '/': 'div',
+  '<': '<',
+  '<=': '<=',
+  '>': '>',
+  '>=': '>=',
+  '==': '=',
+  '!=': '<>',
+};
+// Bitwise/shift operations that IDO Pascal spells as intrinsic FUNCTION calls `fn(l, r)`.
+const BIT_FN: Partial<Record<BinOp, string>> = {
+  '&': 'bitand',
+  '|': 'bitor',
+  '^': 'bitxor',
+  '<<': 'lshift',
+  '>>': 'rshift',
+};
+
+function pasType(t: IrType): string {
+  if (t.kind === 'ptr') {
+    return '^' + pasType(t.to);
+  }
+  if (t.kind === 'int') {
+    return t.signed ? 'Integer' : 'Cardinal';
+  }
+  // `unknown` reaching a backend means recovery's totality contract already failed upstream —
+  // spell it Integer (assertTypesRecovered is the real gate). struct/array have NO faithful
+  // spelling here yet — fail loud, like every other unspellable construct in this backend. A
+  // void RETURN type is deliberately spelled as `procedure` (see emit) and never reaches here.
+  if (t.kind === 'unknown') {
+    return 'Integer';
+  }
+  throw new Error(`pascal backend: no faithful spelling for a ${t.kind}-typed value yet`);
+}
+
+// Pascal precedence is paren-hungry and differs from C; emit parens around every nested
+// binary/unary subexpression (always safe). Minimal-paren Pascal is a later refinement.
+//
+// pe/ps live in a factory closing over `vt` (the declared type of each printed variable) so the
+// deref check below can judge the Pascal the reader will see without threading an argument
+// through every recursion site.
+function makePrinter(vt: VarTypes) {
+  function pe(e: Expr): string {
+    switch (e.k) {
+      case 'var':
+        return e.name;
+      case 'addr':
+        // IDO Pascal address-of has no faithful spelling here yet — loud-decline (agbcc-only
+        // globals today; a deref of an addr is simplified away before it reaches this backend).
+        throw new Error(`pascal backend: address-of global '${e.name}' has no IDO Pascal spelling yet`);
+      case 'const':
+        return String(e.value);
+      case 'call':
+        return `${e.fn}(${e.args.map(pe).join(', ')})`;
+      case 'index': {
+        // The width-carrying access node (l3/ast.ts): each backend legalizes its own derefs. The
+        // C family inserts a reinterpret cast when the base's rendered type does not stride the
+        // access width; Pascal HAS no reinterpret cast, so a definite mismatch declines LOUD — a
+        // `p^` through the wrong-width pointer would silently read the wrong size. An UNKNOWABLE
+        // base (a call — its type lives outside this unit) prints ONLY for a word access, where
+        // any plausible `^Integer`-shaped callee agrees with the machine width; a sub-word access
+        // through an unknowable base would DISCARD the node's width (upas checks types, not
+        // machine widths), so it declines like a definite mismatch.
+        const bt = exprCType(e.base, vt);
+        if ((bt !== undefined && !derefStrideOk(bt, e.width)) || (bt === undefined && e.width !== 4)) {
+          throw new Error(
+            `pascal backend: a ${e.width}-byte access through a base of type '${bt ? typeToString(bt) : '<unknowable>'}' has no faithful spelling (no reinterpret cast)`,
+          );
+        }
+        return e.idx.k === 'const' && e.idx.value === 0 ? `${pe(e.base)}^` : `${pe(e.base)}[${pe(e.idx)}]`;
+      }
+      // Recovered struct field access has no faithful IDO-Pascal spelling yet (records + `.field`
+      // are future work) — fail LOUD rather than emit a silently-wrong access, as `%` does above.
+      case 'field':
+        throw new Error(`pascal backend: struct field access '${e.name}' has no IDO Pascal spelling yet`);
+      case 'un':
+        return e.op === '~' ? `bitnot(${pe(e.e)})` : `(${e.op === '!' ? 'not ' : e.op}${pe(e.e)})`;
+      // Casts have no faithful IDO-Pascal spelling yet — fail LOUD rather than emit silently-wrong
+      // source. Tree-level producers reaching here: the width-narrowing idiom casts (agbcc-gated,
+      // so never on this path today), structure.ts's STRUCT-pointer casts (unreachable too — the
+      // `field` case above throws first), and intify's `(s32)ptr` legalization (any target).
+      // Scalar deref casts never appear in the tree — the index case above owns that judgment.
+      case 'cast':
+        throw new Error(`pascal backend: cast has no IDO Pascal spelling yet`);
+      // A gap marker: a call to the UNDECLARED function ASMLIFT_ERROR — Pascal has no preprocessor,
+      // but an undeclared identifier fails `upas` all the same, so the loud-in-artifact property
+      // (the file cannot compile until the user consciously supplies the symbol) is preserved.
+      // Single quotes double to escape inside a Pascal string literal.
+      case 'marker':
+        return `ASMLIFT_ERROR(${[`'${e.reason.replace(/'/g, "''")}'`, ...e.args.map(pe)].join(', ')})`;
+      case 'bin': {
+        const fn = BIT_FN[e.op];
+        if (fn) {
+          return `${fn}(${pe(e.l)}, ${pe(e.r)})`;
+        }
+        const op = OP[e.op];
+        // Fail LOUD on an operator this backend cannot faithfully spell (e.g. `%`) rather than emit
+        // `(l undefined r)` — a silently-wrong Pascal expression.
+        if (!op) {
+          throw new Error(`pascal backend: operator '${e.op}' has no faithful IDO Pascal spelling`);
+        }
+        return `(${pe(e.l)} ${op} ${pe(e.r)})`;
+      }
+    }
+  }
+
+  // `tail` = control falls off the END of the function once this statement (the LAST of its list)
+  // completes. Pascal has no early return — `fnName := v` only sets the result — so a `return` is
+  // faithful ONLY in tail position (the assignment-then-fall-off-end idiom; a bare tail `return;`
+  // simply falls off). A NON-tail return would render as a silent fall-through miscompile, so it
+  // fails LOUD, mirroring this file's `%`/`field`/`break` throws.
+  function ps(fnName: string, s: Stmt, indent: string, tail = false): string[] {
+    // render a statement list: only its LAST statement can inherit tail position
+    const list = (stmts: Stmt[], ind: string, tl: boolean): string[] =>
+      stmts.flatMap((x, i) => ps(fnName, x, ind, tl && i === stmts.length - 1));
+    switch (s.k) {
+      case 'assign': {
+        // The write-side sibling of the index case's deref discipline: Pascal has no reinterpret
+        // cast, so a definitely-non-pointer value assigned into a pointer-declared var (the shape
+        // the C family legalizes with `(u8 *)…`, cfamily.ts legalizePointerWrites) declines LOUD
+        // here instead of failing three stages later in upas.
+        const dt = vt(s.name);
+        const ct = exprCType(s.value, vt);
+        if (dt?.kind === 'ptr' && ct && ct.kind !== 'ptr' && ct.kind !== 'array') {
+          throw new Error(
+            `pascal backend: assigning a ${typeToString(ct)} value into pointer var '${s.name}' has no faithful spelling (no reinterpret cast)`,
+          );
+        }
+        return [`${indent}${s.name} := ${pe(s.value)};`];
+      }
+      case 'store':
+        return [`${indent}${pe(s.lval)} := ${pe(s.value)};`];
+      case 'exprstmt':
+        return [`${indent}${pe(s.value)};`];
+      case 'return':
+        if (!tail) {
+          throw new Error('pascal backend: early `return` (not in tail position) has no faithful IDO Pascal spelling');
+        }
+        return s.value ? [`${indent}${fnName} := ${pe(s.value)};`] : [];
+      case 'if': {
+        const cond = pe(s.cond);
+        const block = (stmts: Stmt[], ind: string) =>
+          stmts.length === 1
+            ? ps(fnName, stmts[0], ind, tail)
+            : [`${ind}begin`, ...list(stmts, ind + '  ', tail), `${ind}end`];
+        // Pascal: no `;` before `else`; the branch statements already carry their own.
+        const out = [`${indent}if ${cond} then`];
+        out.push(...block(s.then, indent + '  '));
+        if (s.else.length) {
+          out.push(`${indent}else`);
+          out.push(...block(s.else, indent + '  '));
+        }
+        return out;
+      }
+      case 'while': {
+        // loop bodies are NEVER tail position — control returns to the test
+        const body =
+          s.body.length === 1
+            ? ps(fnName, s.body[0], indent + '  ')
+            : [`${indent}begin`, ...s.body.flatMap((x) => ps(fnName, x, indent + '  ')), `${indent}end`];
+        return [`${indent}while ${pe(s.cond)} do`, ...body];
+      }
+      case 'dowhile':
+        // IDO/SGI Pascal `repeat S until C` runs the body once then tests — the exit test is the NEGATION
+        // of the C loop-continue condition (`do{}while(c)` re-enters while c is TRUE; `repeat until` exits
+        // when its test is TRUE). `repeat`/`until` need no begin/end (the keywords bracket the body).
+        return [
+          `${indent}repeat`,
+          ...s.body.flatMap((x) => ps(fnName, x, indent + '  ')),
+          `${indent}until ${pe({ k: 'un', op: '!', e: s.cond })};`,
+        ];
+      case 'for':
+        // IDO/SGI Pascal's native `for i := a to b do` is restricted to a unit-stride countable
+        // range, so rather than pattern-match that subset, render the ALWAYS-faithful desugaring
+        // `init; while cond do begin body; inc end` (reusing the `while` arm). The `for` node
+        // exists purely as a C/C++ readability spelling — no silently-wrong `to`-bound. (A native
+        // `for` spelling is future work.)
+        return [
+          ...ps(fnName, s.init, indent),
+          ...ps(fnName, { k: 'while', cond: s.cond, body: [...s.body, s.inc] }, indent),
+        ];
+      // SGI/IDO Pascal has no loop `break`/`continue` — loud-fail rather than emit silently-wrong control
+      // flow (mirrors the `field`/`cast`/`%` throws). A `goto`-lowered form is future work.
+      case 'break':
+        throw new Error('pascal backend: `break` has no IDO Pascal spelling');
+      case 'continue':
+        throw new Error('pascal backend: `continue` has no IDO Pascal spelling');
+      case 'switch': {
+        // IDO/SGI Pascal `case E of L: S; … otherwise S end`. There is NO fall-through in Pascal case-of,
+        // so a `fallsThrough` arm has no faithful spelling → loud-fail (mirrors the `field`/`cast`/`%`
+        // throws above). Each arm's body is a single statement or a begin/end block.
+        const arm = (body: Stmt[], ind: string) =>
+          body.length === 1
+            ? ps(fnName, body[0], ind + '  ')
+            : [`${ind}  begin`, ...body.flatMap((x) => ps(fnName, x, ind + '  ')), `${ind}  end`];
+        // Pascal has no early `return`: a `return v` inside a case renders `fnName := v` and then FALLS
+        // THROUGH the case-of into any post-switch code — a silent miscompile for a mixed return/break
+        // switch. Loud-fail if a case (or default) body contains a return, rather than emit wrong code.
+        const hasReturn = (body: Stmt[]): boolean =>
+          body.some(
+            (st) =>
+              st.k === 'return' ||
+              (st.k === 'if' && (hasReturn(st.then) || hasReturn(st.else))) ||
+              ((st.k === 'while' || st.k === 'dowhile' || st.k === 'for') && hasReturn(st.body)) ||
+              (st.k === 'switch' && (st.cases.some((c) => hasReturn(c.body)) || hasReturn(st.default ?? []))),
+          );
+        if (s.cases.some((c) => hasReturn(c.body)) || hasReturn(s.default ?? [])) {
+          throw new Error(
+            'pascal backend: `return` inside a switch case has no faithful IDO Pascal spelling (no early return)',
+          );
+        }
+        const out = [`${indent}case ${pe(s.scrutinee)} of`];
+        for (const c of s.cases) {
+          if (c.fallsThrough) {
+            throw new Error('pascal backend: switch fall-through has no faithful IDO Pascal case-of spelling');
+          }
+          out.push(`${indent}  ${c.values.join(', ')}:`, ...arm(c.body, indent + '  '));
+        }
+        if (s.default) {
+          out.push(`${indent}  otherwise`);
+          out.push(...arm(s.default, indent + '  '));
+        }
+        out.push(`${indent}end;`);
+        return out;
+      }
+    }
+  }
+  return ps;
+}
+
+export const pascalBackend: LanguageBackend = {
+  id: 'pascal',
+  emit(fn: SFn): string {
+    // Same env discipline as the C family (cfamily.ts cFamilyBody): the printer judges derefs
+    // against the exact declarations it emits.
+    const ps = makePrinter(declaredTypes(fn));
+    const params = fn.params.map((p) => `${p.name}: ${pasType(p.type)}`).join('; ');
+    // A void return is a PROCEDURE — the honest Pascal spelling (the annotate-mode stub's SFn is
+    // void-typed by design); a valued function keeps the `function … : T` form.
+    const lines = [
+      fn.retType.kind === 'void'
+        ? `procedure ${fn.name}(${params});`
+        : `function ${fn.name}(${params}): ${pasType(fn.retType)};`,
+    ];
+    if (fn.locals.length) {
+      lines.push('var', ...fn.locals.map((l) => `  ${l.name}: ${pasType(l.type)};`));
+    }
+    lines.push('begin');
+    fn.body.forEach((s, i) => lines.push(...ps(fn.name, s, '  ', i === fn.body.length - 1)));
+    lines.push('end;');
+    return lines.join('\n') + '\n';
+  },
+  // ISO/IDO Pascal comment; `*)` inside the text would terminate it early — split it.
+  comment(text: string): string {
+    return `(* ${text.replace(/\*\)/g, '* )')} *)`;
+  },
+};

package/src/contracts.ts

@@ -0,0 +1,131 @@
+// asmlift — stage boundary contracts: semantic POSTCONDITIONS enforced in production at the
+// stage boundaries, in every entry path (decompile / decompileTraced / the cli's
+// decompileRanked / decompileWithReport).
+// A pass that regresses fails AT its boundary with a diagnostic, not three stages later as
+// wrong C.
+import type { Fn, Value } from './ir/core';
+import { type IrType, typeToString } from './ir/types';
+import type { Expr, SFn, Stmt } from './l3/ast';
+import { exprChildren, fieldSpellsDot, stmtChildren, stmtExprs } from './l3/ast';
+import { declaredTypes, exprCType } from './l3/typing';
+
+export class ContractError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ContractError';
+  }
+}
+
+// An `unknown` may hide NESTED inside a pointer (`ptr(unknown)` prints as `unk32 *` — uncompilable,
+// since `unk32` isn't a real typedef). Check the whole type, not just its top-level kind.
+function hasUnknown(t: IrType): boolean {
+  return t.kind === 'unknown' || (t.kind === 'ptr' && hasUnknown(t.to));
+}
+
+/** Post type-recovery: no SSA value may still be `unknown` (at any depth). Recovery is total by
+ *  construction (it defaults every residual to s32), so a surviving `unknown` means a recovery pass
+ *  stopped short — caught here, before it poisons a downstream type decision or the emitted
+ *  signature. */
+export function assertTypesRecovered(fn: Fn): void {
+  const check = (v: Value, what: string) => {
+    if (hasUnknown(v.type)) {
+      throw new ContractError(`type recovery left ${what} unknown in '${fn.name}'`);
+    }
+  };
+  for (const b of fn.blocks) {
+    b.params.forEach((p, i) => check(p, `param #${i}`));
+    for (const op of b.ops) {
+      op.results.forEach((r, i) => check(r, `${op.opcode} result #${i}`));
+    }
+  }
+}
+
+/** Post structuring: the AST must reference no unresolved value. The structurer emits the
+ *  sentinel var `"?"` when it cannot resolve a value (a dropped def, or an opcode it has no
+ *  lowering for) — which would print as uncompilable source. Fail at the structuring boundary
+ *  instead of emitting garbage. */
+export function assertResolved(sfn: SFn): void {
+  // Derived from the shared exprChildren/stmtExprs/stmtChildren traversal so no statement kind
+  // can be missed. A gap `marker` is annotate-mode's DESIGNED spelling of an unresolved value
+  // ("resolved" by construction); only its args could still hide a stray `"?"` — and args are
+  // exactly its children.
+  const badExpr = (e: Expr): boolean => (e.k === 'var' && e.name === '?') || exprChildren(e).some(badExpr);
+  const badStmt = (s: Stmt): boolean => stmtExprs(s).some(badExpr) || stmtChildren(s).some(badStmt);
+  if (sfn.body.some(badStmt)) {
+    throw new ContractError(
+      `structuring left an unresolved value ('?') in '${sfn.name}' — a dropped def or unlowered opcode`,
+    );
+  }
+}
+
+/** Post structuring: the AST's memory accesses and operators must be SPELLABLE — a `field`
+ *  node's base a pointer-to-struct (`->`) or a struct value (`.`, an array element) carrying
+ *  that field; no pointer operand under an operator C rejects; and every SCALAR `index` node's
+ *  width a real C scalar width (a regressing pass emitting width 3 would print as the
+ *  nonexistent `(u24 *)` typedef and fail at candidate compile three stages later). Index BASES
+ *  are deliberately not checked: the width-carrying node makes every base legalizable — the C
+ *  family casts at the node's width, Pascal declines loud — so a non-pointer base is a backend
+ *  spelling decision, not an ill-formed tree. Only DEFINITE violations throw: an expression
+ *  whose C type is not statically knowable here (a call's return, a gap marker) passes. */
+export function assertDerefsTyped(sfn: SFn): void {
+  const vt = declaredTypes(sfn);
+  const ctype = (e: Expr): IrType | undefined => exprCType(e, vt);
+  const bad: string[] = [];
+  // Ops C rejects outright on a pointer operand (the additive ops and &&/|| are legal C).
+  const NO_PTR_OPS = new Set(['&', '|', '^', '<<', '>>', '*', '/', '%']);
+  // 1/2/4 only: the decomp typedef vocabulary (C_TYPEDEFS) has no 64-bit scalar, so a width-8
+  // access would print as the nonexistent `(s64 *)` — exactly the three-stages-later failure
+  // this rule pre-empts. (If f64 loads ever land they are floats, not a scalar width here.)
+  const SCALAR_WIDTHS = new Set([1, 2, 4]);
+  // Dot-form field bases (struct-array elements) carry the struct STRIDE as their width — any
+  // stride matching the element size is legal there (the tree-level struct cast governs the
+  // spelling; a stride/size MISMATCH types scalar in exprCType and the field rule flags it).
+  // Collected as fields are visited, BEFORE recursing into their children. Identity-keyed: a
+  // future subtree-SHARING pass (CSE-style) would leak the exemption to aliased bare uses —
+  // trees are freshly built per node today (structure.ts), which this relies on.
+  const structElem = new Set<Expr>();
+  const checkExpr = (e: Expr): void => {
+    if (e.k === 'index' && !structElem.has(e) && !SCALAR_WIDTHS.has(e.width)) {
+      bad.push(`index width ${e.width} is not a C scalar width`);
+    }
+    // The emitter legalizes pointer operands away from these ops (structure.ts intify); a
+    // pointer surviving here is ill-typed C the compiler will reject.
+    if (e.k === 'bin' && NO_PTR_OPS.has(e.op)) {
+      for (const side of [e.l, e.r]) {
+        if (ctype(side)?.kind === 'ptr') {
+          bad.push(`pointer operand under '${e.op}'`);
+        }
+      }
+    }
+    // `!p` is legal C (pointer truthiness); `-p`/`~p` are not.
+    if (e.k === 'un' && e.op !== '!' && ctype(e.e)?.kind === 'ptr') {
+      bad.push(`pointer operand under unary '${e.op}'`);
+    }
+    if (e.k === 'field') {
+      if (fieldSpellsDot(e)) {
+        structElem.add(e.base);
+      }
+      const bt = ctype(e.base);
+      if (bt) {
+        // type-check against the same dot-vs-arrow spelling the printer will use (shared rule)
+        const st = fieldSpellsDot(e) ? bt : bt.kind === 'ptr' ? bt.to : undefined;
+        if (!st || st.kind !== 'struct') {
+          bad.push(`member access '${e.name}' on a non-struct base (C type '${typeToString(bt)}')`);
+        } else if (!st.fields.some((f) => f.name === e.name)) {
+          bad.push(`member access '${e.name}' not declared on '${st.name}'`);
+        }
+      }
+    }
+    exprChildren(e).forEach(checkExpr);
+  };
+  const checkStmt = (s: Stmt): void => {
+    stmtExprs(s).forEach(checkExpr);
+    stmtChildren(s).forEach(checkStmt);
+  };
+  sfn.body.forEach(checkStmt);
+  if (bad.length) {
+    throw new ContractError(
+      `structuring emitted ill-typed C in '${sfn.name}': ${bad[0]}${bad.length > 1 ? ` (+${bad.length - 1} more)` : ''}`,
+    );
+  }
+}

package/src/detect.ts

@@ -0,0 +1,12 @@
+// asmlift — small pure helpers over raw asm TEXT (no parsing): shared by the CLI and the
+// web playground, which both need a function name before they can call `decompile`.
+
+/** Best-effort function-name detection: the objdump symbol header, else the `.globl` name,
+ *  else the first label. Returns undefined when the asm names nothing (caller asks the user). */
+export function detectName(asm: string): string | undefined {
+  return (
+    asm.match(/^[0-9a-f]+ <([\w.$]+)>:/m)?.[1] ??
+    asm.match(/^\s*\.globl\s+([\w.$]+)/m)?.[1] ??
+    asm.match(/^([A-Za-z_]\w*):/m)?.[1]
+  );
+}