@asmlift/core 0.2.0 → 0.4.0

package/README.md

@@ -38,7 +38,7 @@ Input is **text**, following what each target's toolchain produces:
 | Option       | Meaning                                                                                                                                                                                                                                                                                                                                                                                |
 | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `backend`    | `cBackend` (default) or `pascalBackend` — values from `@asmlift/core/backend/*`. C++ is `cppBackend(spec)`, a per-function factory: it takes a `CppFnSpec` (class/method name, explicit param types, class field layouts — what a project's headers supply) and covers free and non-virtual member functions with word-sized fields; virtual dispatch, references, ctors/dtors decline |
-| `patterns`   | Idiom rewrite patterns. Omitted = `DEFAULT_IDIOM_PATTERNS` (each gated per compiler); `[]` = none                                                                                                                                                                                                                                                                                      |
+| `patterns`   | Idiom rewrite patterns. Omitted = `DEFAULT_IDIOM_PATTERNS` (self-selects per target: most are compiler-gated, the boolean-negation folds are universal); `[]` = none                                                                                                                                                                                                                   |
 | `prototypes` | Callee arities + void-ness, as a real project takes them from headers — drives call-argument recovery                                                                                                                                                                                                                                                                                  |
 | `asmData`    | Optional `objdump -s -r -t` side-table; required to recover MIPS/PPC jump-table switches                                                                                                                                                                                                                                                                                               |
 | `onGap`      | `"strict"` (default): throw on any gap. `"annotate"`: emit best-effort source with `ASMLIFT_ERROR` markers; every gap is also returned in the structured `diagnostics` array (empty ⇔ gap-free)                                                                                                                                                                                        |
@@ -86,7 +86,7 @@ injected via hooks, never copied. `verify()` runs after every IR-mutating pass;
 | `pattern/engine.ts`                             | Idiom layer: **rewrite patterns as data** + greedy driver + DCE; `patternApplies` gates on Target capabilities                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `raise/*.ts`                                    | The pre-recovery recognizers, in ONE ordered list (`pre-recovery.ts`): const materialize → magic division (`magicdiv.ts`, Hacker's Delight inverse) → soft division → array legalize → struct-array → struct-pointer → short-circuit; plus `recover.ts` (L1→L2 type recovery), `retsink.ts` (return-sinking), `errors.ts` (`RaiseUnsupportedError`)                                                                                                                                                                                       |
 | `structure/*.ts`                                | L2→L3 in four modules: `loops.ts` (natural-loop discovery), `analysis.ts` (use registry, liveness, C4 materialization), `switch-recover.ts` (Regime-A comparison-tree recovery), `structure.ts` (SSA-destruction coalescing with interference checks + emission: if/while/do-while/for/switch, break/early-return)                                                                                                                                                                                                                        |
-| `l3/*.ts`                                       | `ast.ts`: language-**neutral** structured AST, the one traversal vocabulary (`exprChildren` etc.), and the `LanguageBackend` seam. Post-structure passes `dce.ts` + `basecse.ts`, the differ-ranked re-spelling levers `regspell.ts` + `reindex.ts`, and `typing.ts` (the rendered-expression C type the backends and contracts share)                                                                                                                                                                                                    |
+| `l3/*.ts`                                       | `ast.ts`: language-**neutral** structured AST, the one traversal vocabulary (`exprChildren` etc.), and the `LanguageBackend` seam. Post-structure passes `dce.ts` + `basecse.ts`, the shared hoist mechanism `hoist.ts`, the differ-ranked re-spelling levers `regspell.ts` + `reindex.ts` + `argbase.ts` + `scopebase.ts`, and `typing.ts` (the rendered-expression C type the backends and contracts share)                                                                                                                             |
 | `backend/{c,cpp,cfamily,pascal}.ts`             | Three backends: C and C++ (CodeWarrior mangling via `mangle.ts`) over the shared `cfamily.ts` substrate, and Pascal (`:=`, `div`, tail-position returns; unspellable constructs throw)                                                                                                                                                                                                                                                                                                                                                    |
 | `pipeline.ts`                                   | `decompile()` + the shared tower spine + annotate-mode stubs/diagnostics                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `trace.ts`                                      | `decompileTraced` — the traced tower (per-stage IR dumps + pattern before/after events), browser-pure; @asmlift/cli's `report.ts` enriches it with objdiff scores/candidates, the playground's Pipeline tab renders it directly                                                                                                                                                                                                                                                                                                           |
@@ -104,7 +104,9 @@ Recovered today: straight-line, if/else diamonds, natural loops (`while` / `do-w
 properly nested, in-body `break`/early-`return`), comparison-tree and jump-table switches,
 direct calls, constant-offset and variable-index memory (`*p`, `p[n]`, `a[i]`, struct fields),
 magic-number and soft division, short-circuit booleans, width casts. Still DECLINED (loud, never
-wrong code): **local stack frames** (address-taken locals / sp-as-data / live spills),
+wrong code): **local stack frames** (address-taken locals / sp-as-data; MIPS models word `sp`
+slots and PPC elides callee-saved save slots, so a spill/reload pair is modelled on those two —
+anything the narrow models cannot honour declines),
 **cross-block condition flags** on PPC (a `cmpw` whose branch lands in another block — the
 capability gap behind the mwcc switch stubs), computed tail calls, PIC/`gp`/SDA global access,
 switch fall-through, multi-latch/irreducible loops, floats, and 64-bit memory ops. Prototypes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asmlift/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "license": "MIT",
   "type": "module",
   "description": "Match decompile an assembly function to C or Pascal",

package/src/backend/cfamily.ts

@@ -9,6 +9,78 @@ import { IrType, T, scalarTypeForAccess, typeToString } from '../ir/types';
 import { BinOp, Expr, SFn, Stmt, dotBase } from '../l3/ast';
 import { type VarTypes, declaredTypes, derefStrideOk, exprCType } from '../l3/typing';
 
+/**
+ * The C SIGNEDNESS a rendered integer expression actually has — `true`/`false`, or `undefined`
+ * when it is not determinable here. The deliberate complement to l3/typing's `exprCType`, which is
+ * pointer-ness-accurate and reports every integer as `s32` by contract; this models the two C
+ * rules that contract omits, integer PROMOTION and the usual arithmetic CONVERSIONS.
+ *
+ * It lives HERE, in the C-family backend, because it is a model of C's own rules with no meaning
+ * for another language — the same reason the cast it feeds is synthesized here rather than in the
+ * tower. `exprCType` stays in l3/ because Pascal consults it too.
+ *
+ * It exists for one question, and the question is byte-load-bearing: C spells both `>>>` and `>>`
+ * as `>>` and chooses between them from the left operand's type. A logical shift rendered over a
+ * signed expression recompiles to `asr` where the target has `lsr`, and evaluates to a different
+ * value. The C-family backend casts the operand whenever this returns anything but the signedness
+ * the operator needs, so `undefined` is the safe answer in every case the model does not cover — a
+ * redundant cast is codegen-identical, a missing one is a miscompile.
+ *
+ * Anything narrower than 32 bits promotes to `int` and is therefore SIGNED, whatever it was
+ * declared. Pointers, calls and markers are `undefined`.
+ */
+function renderedIntSignedness(e: Expr, varType: VarTypes): boolean | undefined {
+  const rec = (x: Expr): boolean | undefined => renderedIntSignedness(x, varType);
+  // an lvalue-ish leaf: its C type is a declaration / an explicit cast / a carried access width
+  const promoted = (t: IrType | undefined): boolean | undefined =>
+    t?.kind !== 'int' ? undefined : t.width < 32 ? true : t.width === 32 ? t.signed : undefined;
+  switch (e.k) {
+    case 'var':
+    case 'cast':
+    case 'index':
+    case 'field':
+      return promoted(exprCType(e, varType));
+    // A decimal literal is `int` when it fits in one; C89 gives a larger one an unsigned type,
+    // which is not the same operand — so it is left undetermined rather than assumed. INT_MIN is
+    // in that larger class despite fitting: the backend prints it as `-2147483648`, which C lexes
+    // as unary minus applied to `2147483648` — a constant too big for `int`, hence unsigned long.
+    case 'const':
+      return e.value > -2147483648 && e.value <= 2147483647 ? true : undefined;
+    // `-x` / `~x` carry the PROMOTED type of the operand; `!x` is `int`.
+    case 'un':
+      return e.op === '!' ? true : rec(e.e);
+    case 'bin': {
+      // Shifts take the type of the LEFT operand alone — the right is promoted independently.
+      if (e.op === '<<' || e.op === '>>' || e.op === '>>>') {
+        return rec(e.l);
+      }
+      // Comparisons and the logical connectives yield `int`.
+      if (['<', '<=', '>', '>=', '==', '!=', '&&', '||'].includes(e.op)) {
+        return true;
+      }
+      // Usual arithmetic conversions over the remaining binary operators: at equal rank, unsigned
+      // wins. Either side unknown leaves the result unknown — EXCEPT when the known side is
+      // unsigned, which already decides it.
+      //
+      // That exception is the one place this returns a DEFINITE answer from an unknown operand,
+      // and it is sound only because every integer here is rank `int`: at UNEQUAL rank C converts
+      // to the wider type first, so `unsigned int & long long` is SIGNED. Core has no 64-bit
+      // integer type at all (the decomp typedef vocabulary stops at 32 — see contracts.ts
+      // SCALAR_WIDTHS), so the unequal-rank case cannot arise. Adding one would invalidate this.
+      const l = rec(e.l);
+      const r = rec(e.r);
+      if (l === false || r === false) {
+        return false;
+      }
+      return l === true && r === true ? true : undefined;
+    }
+    case 'call':
+    case 'marker':
+    case 'addr':
+      return undefined;
+  }
+}
+
 // C operator precedence (lower binds tighter). Used to emit MINIMAL parentheses. Shared: C++ has
 // the same precedence for these operators.
 const PREC: Record<BinOp, number> = {
@@ -19,6 +91,7 @@ const PREC: Record<BinOp, number> = {
   '-': 4,
   '<<': 5,
   '>>': 5,
+  '>>>': 5, // spells as C's `>>` (see printExpr's shift rule) — same precedence
   '<': 6,
   '<=': 6,
   '>': 6,
@@ -47,14 +120,42 @@ export function cType(t: IrType): string {
 }
 
 /** Declare a name of a given type, C declarator rules: an array puts its length AFTER the name
- *  (`u8 _pad[4]`), everything else is the prefix `cType name`. */
+ *  (`u8 _pad[4]`), a pointer binds its `*` to the declarator (`void *p`), everything else is
+ *  the prefix `cType name`. */
 function cDeclare(t: IrType, name: string): string {
   if (t.kind === 'array') {
     return `${cType(t.elem)} ${name}[${t.count}]`;
   }
+  if (t.kind === 'ptr') {
+    return `${cType(t.to)} *${name}`;
+  }
   return `${cType(t)} ${name}`;
 }
 
+/** One field of a rendered struct declaration — the minimal input shape shared by the two
+ *  producers of `struct N { ... };` text: the backend's recovered structs (SFn.structs, whose
+ *  StructType fields already carry pads as real `u8[N]` members) and the cli's map-layout
+ *  declaration synthesis (declare.ts, which seats fields at exact offsets by interleaving pad
+ *  fields itself). `volatile` is the MMIO member idiom (`volatile u16 gain;`) — only the
+ *  map-derived synthesis sets it today; recovered structs never do. */
+export interface StructFieldDecl {
+  name: string;
+  type: IrType;
+  volatile?: boolean;
+  /** bitfield width — spells `u32 name : n;` (the map-layout synthesis is the only producer) */
+  bits?: number;
+}
+
+/** THE struct-declaration spelling — every `struct N { ... };` asmlift prints comes from here,
+ *  so the backend's recovered-struct decls and the scoring layer's synthesized decls cannot
+ *  drift apart. One line, fields in caller order (the type is self-describing: padding is the
+ *  caller's discipline, already present as real fields). */
+export function renderStructDecl(name: string, fields: StructFieldDecl[]): string {
+  const one = (f: StructFieldDecl) =>
+    `${f.volatile ? 'volatile ' : ''}${cDeclare(f.type, f.name)}${f.bits !== undefined ? ` : ${f.bits}` : ''};`;
+  return `struct ${name} { ${fields.map(one).join(' ')} };`;
+}
+
 // A LEAF hook lets a C-family backend override how a `var` or `index` node spells WITHOUT
 // re-implementing precedence, parenthesization, or statement structure. It returns the
 // replacement text, or null to fall through to the default C spelling — how the C++ backend
@@ -79,6 +180,28 @@ function printExpr(e: Expr, parentPrec: number, vt: VarTypes, leaf?: LeafHook):
     derefStrideOk(exprCType(ix.base, vt), ix.width)
       ? ix.base
       : { k: 'cast', to: T.ptr(scalarTypeForAccess(ix.width, ix.signed)), e: ix.base };
+  // C-FAMILY SHIFT LEGALIZATION, the same discipline one operator over. The tower keeps the two
+  // right shifts apart (`>>>` logical, `>>` arithmetic); C spells BOTH `>>` and picks between them
+  // from the LEFT OPERAND'S TYPE. So the operand must be made to carry the choice, or an `shr_u`
+  // recompiles to `asr` where the target has `lsr` AND evaluates differently —
+  // `*(u8 *)&g << 30 >> 30` promotes to `int`, so a 2-bit field holding 2 comes out -1.
+  //
+  // (engine.ts's zext fold covers the same hazard for widths C can NAME, by folding the whole
+  // shift pair to a cast op. Every other extract width — every bitfield read — lands here.)
+  //
+  // The cast is added unless the operand PROVABLY renders with the signedness the op needs:
+  // renderedIntSignedness answers `undefined` wherever its model does not reach, and a redundant
+  // cast is codegen-identical while a missing one is a miscompile. An existing 32-bit integer cast
+  // is REPLACED rather than wrapped — `(u32)(s32)&g` and `(u32)&g` are the same bytes, and the
+  // arithmetic rules upstream do emit that inner cast (intifyAddr).
+  const shiftOperand = (e0: Extract<Expr, { k: 'bin' }>): Expr => {
+    const wantSigned = e0.op === '>>';
+    if (renderedIntSignedness(e0.l, vt) === wantSigned) {
+      return e0.l;
+    }
+    const inner = e0.l.k === 'cast' && e0.l.to.kind === 'int' && e0.l.to.width === 32 ? e0.l.e : e0.l;
+    return { k: 'cast', to: T.int(32, wantSigned), e: inner };
+  };
   switch (e.k) {
     case 'var':
       return e.name;
@@ -99,6 +222,21 @@ function printExpr(e: Expr, parentPrec: number, vt: VarTypes, leaf?: LeafHook):
       // binds tighter than any prefix operator, so a cast/unary/deref base is printed at prec 1
       // and parenthesizes itself: `((u8 *)p)[1]`). The postfix form needs no outer parentheses.
       const base = legalized(e);
+      // Leading constant subscripts (a multidimensional array global's bare spelling) keep the
+      // postfix form whatever `idx` is: `g[0][0]` is the element, `*g[0]` would be its ROW.
+      //
+      // `lead` implies the base already strides the access width — its only producer registers a
+      // matching element type for the global (structure.ts bareArrayLead + noteGlobal). Nothing
+      // else enforced that, and the failure would be quiet-ish: legalization would wrap the base,
+      // spelling `((u16 *)g)[0][i]`, which subscripts a `u16` twice. Check it rather than assume.
+      if (e.lead && e.lead.length > 0) {
+        if (base !== e.base) {
+          throw new Error(
+            `c backend: a multidimensional array access needs a base that strides ${e.width} bytes as spelled`,
+          );
+        }
+        return `${rec(base, 1)}${e.lead.map((l) => `[${l}]`).join('')}[${rec(e.idx, 99)}]`;
+      }
       if (e.idx.k === 'const' && e.idx.value === 0) {
         const s = `*${rec(base, 2)}`;
         return parentPrec < 2 ? `(${s})` : s;
@@ -117,10 +255,21 @@ function printExpr(e: Expr, parentPrec: number, vt: VarTypes, leaf?: LeafHook):
       // first (the C++ member-access rewrite).
       const ix = dotBase(e);
       if (ix) {
+        // This path spells the index node from parts, so a `lead` would be DROPPED — an element
+        // access silently becoming a row's. Unreachable today (arrayAccess's lead branch requires
+        // `fieldOff === undefined`, which is exclusive with the dot form), but this is a
+        // text-returning path with no other guard, so it refuses rather than assumes.
+        if (ix.lead && ix.lead.length > 0) {
+          throw new Error(`c backend: a multidimensional array element has no struct-field spelling yet`);
+        }
         const hooked = leaf?.(ix, rec);
         const baseTxt = hooked ?? `${rec(ix.base, 1)}[${rec(ix.idx, 99)}]`;
         return `${baseTxt}.${e.name}`;
       }
+      // explicit dot: a struct-VALUE global's field (`gSym.field`, symbol-map layout spelling)
+      if (e.dot) {
+        return `${rec(e.base, 1)}.${e.name}`;
+      }
       return `${rec(e.base, 1)}->${e.name}`;
     }
     case 'un': {
@@ -145,7 +294,9 @@ function printExpr(e: Expr, parentPrec: number, vt: VarTypes, leaf?: LeafHook):
     }
     case 'bin': {
       const p = PREC[e.op];
-      const s = `${rec(e.l, p)} ${e.op} ${rec(e.r, p - 1)}`;
+      // Both right shifts spell C's `>>`; `shiftOperand` supplies the operand cast that says which.
+      const shift = e.op === '>>' || e.op === '>>>';
+      const s = `${rec(shift ? shiftOperand(e) : e.l, p)} ${shift ? '>>' : e.op} ${rec(e.r, p - 1)}`;
       return p > parentPrec ? `(${s})` : s;
     }
   }
@@ -333,9 +484,7 @@ function cFamilyBody(fn0: SFn, leaf?: LeafHook): string[] {
  *  raise/structs.ts (unaccessed leading/interior gaps) interleave them where natural C alignment
  *  does not already cover the offset. This just declares each field in order. */
 function structDecls(fn: SFn): string[] {
-  return (fn.structs ?? []).map(
-    (s) => `struct ${s.name} { ${s.fields.map((f) => cDeclare(f.type, f.name) + ';').join(' ')} };`,
-  );
+  return (fn.structs ?? []).map((s) => renderStructDecl(s.name, s.fields));
 }
 
 /** Assemble a full C-family function from a caller-supplied signature line and the shared body. */

package/src/backend/cpp.ts

@@ -90,7 +90,9 @@ export function cppBackend(spec: CppFnSpec): LanguageBackend {
       // 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') {
+        // `lead` (a multidimensional array global) is not a receiver access and must not be
+        // rewritten to one — the hook returns text, so a dropped subscript would be silent.
+        if (e.k === 'index' && e.base.k === 'var' && e.idx.k === 'const' && !e.lead?.length) {
           const r = recv.get(e.base.name);
           if (r) {
             if (e.width === 4) {

package/src/backend/pascal.ts

@@ -35,6 +35,10 @@ const BIT_FN: Partial<Record<BinOp, string>> = {
   '|': 'bitor',
   '^': 'bitxor',
   '<<': 'lshift',
+  // `rshift` over this backend's signed `Integer` reproduces IDO's `sra` — verified byte-exact
+  // against upas (pascal-ido.test.ts `asr2`). `>>>`, the LOGICAL shift, has no verified spelling
+  // here and is therefore absent: it reaches the loud decline below rather than borrowing this
+  // one, which would emit an arithmetic shift where the machine did a logical one.
   '>>': 'rshift',
 };
 
@@ -83,6 +87,13 @@ function makePrinter(vt: VarTypes) {
         // 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.
+        // Leading constant subscripts (a multidimensional array global) have no IDO Pascal
+        // spelling yet, and dropping them would read a ROW's address as an element — decline
+        // LOUD, like the address-of case above. Unreachable today (the symbol map is agbcc-only),
+        // but silence here would be the wrong kind of unreachable.
+        if (e.lead && e.lead.length > 0) {
+          throw new Error(`pascal backend: a multidimensional array access has no IDO Pascal spelling yet`);
+        }
         const bt = exprCType(e.base, vt);
         if ((bt !== undefined && !derefStrideOk(bt, e.width)) || (bt === undefined && e.width !== 4)) {
           throw new Error(

package/src/contracts.ts

@@ -5,7 +5,7 @@
 // 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 type { BinOp, Expr, SFn, Stmt } from './l3/ast';
 import { exprChildren, fieldSpellsDot, stmtChildren, stmtExprs } from './l3/ast';
 import { declaredTypes, exprCType } from './l3/typing';
 
@@ -71,8 +71,23 @@ export function assertDerefsTyped(sfn: SFn): void {
   const vt = declaredTypes(sfn);
   const ctype = (e: Expr): IrType | undefined => exprCType(e, vt);
   const bad: string[] = [];
+  // A `void` function must not RETURN A VALUE. Holds by construction today — returnType() answers
+  // void only when every `ret` is operand-less — but `retType` has two producers (the recovered
+  // type and the prototype's `returnsVoid`) and the value-suppression lives in a third place
+  // (structure.ts's return lowering), so a regressing edit to any of them prints `return expr;`
+  // inside a void function. That is ill-formed C the candidate compiler only rejects two stages
+  // later, with a diagnostic pointing at the symptom rather than the pass. Cheap to state here.
+  if (sfn.retType.kind === 'void') {
+    const valued = (stmts: Stmt[]): boolean =>
+      stmts.some((s) => (s.k === 'return' && s.value !== undefined) || valued(stmtChildren(s)));
+    if (valued(sfn.body)) {
+      bad.push(`function '${sfn.name}' is typed void but a return carries a value`);
+    }
+  }
   // Ops C rejects outright on a pointer operand (the additive ops and &&/|| are legal C).
-  const NO_PTR_OPS = new Set(['&', '|', '^', '<<', '>>', '*', '/', '%']);
+  const NO_PTR_OPS = new Set<BinOp>(['&', '|', '^', '<<', '>>', '>>>', '*', '/', '%']);
+  // The comparison operators — where a bare `&SYM` operand is SIGN-ambiguous, not ill-formed.
+  const CMP_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.)
@@ -99,15 +114,32 @@ export function assertDerefsTyped(sfn: SFn): void {
     }
     // A bare global ADDRESS `&SYM` under `+`/`-` is an ESCAPING interior pointer: C scales the byte
     // offset by sizeof(SYM), which is unknown for a header-typed global, so `&SYM + N` is byte-
-    // inexact. A load/store base folds the offset byte-correctly (globalOf turns `&SYM + N` into an
-    // `index`/`field` node whose base is a bare `addr`, never an `addr` under a `bin`), so an `addr`
-    // reaching a `+`/`-` operand here escaped to a value context — flag it rather than emit wrong bytes.
+    // inexact. Nothing emits this shape anymore: a load/store base folds byte-correctly (globalOf
+    // turns `&SYM + N` into an `index`/`field` node whose base is a bare `addr`), and the additive
+    // lowering intifies every other `addr` operand to `(u32)&SYM` (structure.ts intifyAddr — the
+    // cast types int, so it never lands here). A bare `addr` reaching a `+`/`-` operand is therefore
+    // a lowering REGRESSION — flag it rather than emit wrong bytes.
     if (e.k === 'bin' && (e.op === '+' || e.op === '-')) {
       const addrSide = e.l.k === 'addr' ? e.l : e.r.k === 'addr' ? e.r : undefined;
       if (addrSide) {
         bad.push(`interior pointer arithmetic on the global address '&${addrSide.name}'`);
       }
     }
+    // A bare global address `&SYM` as a COMPARISON operand is the same unspelled escape under a
+    // different operator — and worse than ill-formed: the compare's SIGNEDNESS is spelled by the
+    // operand TYPES (the structurer maps icmp_ult and icmp_slt to the same '<'), and `&SYM`'s C
+    // type is the project's own declaration, unknowable here — so the emitted compare can flip
+    // signedness against the asm's, silently. The cmp lowering intifies it signedness-aware
+    // (`(u32)`/`(s32)&SYM` — structure.ts intifyAddrCmp; the cast types int, so it never lands
+    // here). A bare `addr` reaching a comparison operand is therefore a lowering REGRESSION —
+    // flag it rather than emit sign-ambiguous C.
+    if (e.k === 'bin' && CMP_OPS.has(e.op)) {
+      for (const side of [e.l, e.r]) {
+        if (side.k === 'addr') {
+          bad.push(`bare global address '&${side.name}' as a comparison operand`);
+        }
+      }
+    }
     // `!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}'`);

package/src/declare.ts

@@ -0,0 +1,251 @@
+// asmlift — declaration SYNTHESIS for self-declaring candidates
+// (research/self-declaring-candidates-2026-07-26.md).
+//
+// A scored candidate that names map-derived symbols must compile WITHOUT the project's headers:
+// this module renders the declaration block for exactly the symbols the candidate's tree
+// references in a value context (Candidate.symbolRefs — derived from the candidate's final
+// tree at enumeration, l3/symbol-refs.ts). It is a SCORING-LAYER
+// concern only — backends never print declarations (a project user compiles asmlift output
+// against their own headers, where a second declaration would collide).
+//
+// LIVES IN CORE (browser-pure, no Node imports) because BOTH scorers prepend it: the cli's
+// Node/objdiff path (which re-exports this module unchanged) and the webapp's wasm scorer
+// (score-wasm.ts) — one renderer, so the two scoring worlds cannot drift.
+//
+// Fidelity rules (each empirically verified against agbcc — see the research doc):
+//   • struct decls are rebuilt from the map layout with explicit `u8 pad[]` gap fields — the
+//     padded synthesis is byte-identical to the real header declaration;
+//   • member/scalar SIGNEDNESS drives u8/s8/u16/s16/u32/s32 — an s8 field read is
+//     ldrb+lsl+asr where u8 is ldrb alone, so a guessed signedness is a wrong-bytes decl;
+//   • `volatile` is load-bearing (a non-volatile MMIO decl lets the compiler fold/reorder
+//     accesses), `const` is the ROM-table spelling;
+//   • code symbols get `void Name(void);` ONLY when value-referenced — call targets are never
+//     in `symbolRefs` (core excludes them: prototyping a called symbol is C89 poison);
+//   • nothing guesses, with TWO documented exceptions: a SHAPED symbol without the facts to
+//     declare faithfully is SKIPPED — the candidate then fails to compile LOUDLY and is
+//     dropped by rankBy. Exception one is the 4-byte signless-non-pointer cell (see
+//     ENUM_IS_SIGNED): spelled s32 on the C89 enum=int rule. For a true enum that is the header
+//     truth; the residual mis-spell class (a 4-byte nested-struct member word-read via a dot
+//     field) can only LOSE score — the target bytes derive from the truth decls, so a
+//     divergent compile can never false-match. Exception two is the NAME-ONLY data symbol
+//     (`extern u32 name;` — see the default case): required to reproduce symtab-only map
+//     rows outside project headers, justified by the same only-loses-score argument.
+import { type StructFieldDecl, renderStructDecl } from './backend/cfamily';
+import { T } from './ir/types';
+import type { SymbolRef } from './l3/symbol-refs';
+import {
+  ENUM_IS_SIGNED,
+  type SymbolInfo,
+  type SymbolStructField,
+  arrayInnerExtents,
+  declaredFields,
+  pointeeFields,
+  symbolFieldType,
+} from './symbols';
+
+/** The u8/s8/u16/s16/u32/s32 spelling for a 1/2/4-byte cell, or null (no faithful narrow type). */
+function intType(size: number, signed: boolean): string | null {
+  const base = size === 1 ? '8' : size === 2 ? '16' : size === 4 ? '32' : null;
+  return base === null ? null : `${signed ? 's' : 'u'}${base}`;
+}
+
+/** `volatile const ` qualifier prefix (either may be absent). */
+function quals(info: SymbolInfo): string {
+  return `${info.volatile ? 'volatile ' : ''}${info.const ? 'const ' : ''}`;
+}
+
+/** One struct field's type, seated at its exact offset by the caller's pad discipline — THE shared
+ *  map-field typing (symbols.ts `symbolFieldType`, which core's own legalization env also reads,
+ *  so the declaration and the type the emitter reasoned against cannot drift). Member volatility
+ *  is kept on the field decl here (`vu16 field;` — dropping it lets the compiler fold repeated
+ *  reads), being a decl-only fact. */
+const fieldType = symbolFieldType;
+
+/** The padded `struct Tag { ... };` declaration for a layout: fields seated at exact offsets,
+ *  gaps as explicit u8 pad arrays, rendered by THE shared struct renderer (core
+ *  backend/cfamily.ts renderStructDecl — the same spelling the backend's recovered-struct
+ *  decls use, so the two cannot drift). Returns null when the layout cannot be reproduced
+ *  faithfully (an unsized member). */
+function structDecl(tag: string, layout: SymbolStructField[] | undefined, size: number | undefined): string | null {
+  // THE shared spellability predicate (symbols.ts): which members exist, and whether the layout
+  // can be reproduced at all. Core's access rules gate on the SAME call, so a member this
+  // declaration omits — an unsizable layout declined whole, a union alias dropped for its first
+  // view — is a member no emitted expression can name.
+  const members = declaredFields(layout);
+  if (members === null) {
+    return null;
+  }
+  const fields: StructFieldDecl[] = [];
+  // The cursor is in BITS (declaredFields' own discipline) so bitfield members seat exactly.
+  // Gaps pad as the u8 arrays they always were when both ends are byte-aligned, and as named
+  // `u32 asmlift_pad_N : k` bitfields otherwise — split at 32-bit unit boundaries, matching the
+  // no-straddle allocation rule declaredFields verified each kept member against. For a
+  // bitfield-free layout every gap is byte-aligned, so the emitted text is unchanged.
+  let bitCursor = 0;
+  let pad = 0;
+  const padTo = (lo: number): void => {
+    while (bitCursor < lo) {
+      // asmlift_-prefixed so a REAL member named pad_N (a decomp-header idiom) never collides
+      const name = `asmlift_pad_${pad++}`;
+      if (bitCursor % 8 === 0 && lo % 8 === 0) {
+        fields.push({ name, type: T.array(T.u(8), (lo - bitCursor) / 8) });
+        bitCursor = lo;
+      } else {
+        const k = Math.min(lo - bitCursor, 32 - (bitCursor % 32));
+        fields.push({ name, type: T.u(32), bits: k });
+        bitCursor += k;
+      }
+    }
+  };
+  for (const m of members) {
+    const bits = m.bitWidth !== undefined;
+    const lo = m.offset * 8 + (bits ? m.bitOffset! : 0);
+    padTo(lo);
+    fields.push({
+      name: m.name,
+      type: fieldType(m),
+      ...(m.volatile ? { volatile: true } : {}),
+      ...(bits ? { bits: m.bitWidth } : {}),
+    });
+    bitCursor = bits ? lo + m.bitWidth! : (m.offset + m.size) * 8;
+  }
+  if (size !== undefined) {
+    padTo(size * 8); // tail padding to the declared size
+  }
+  return renderStructDecl(tag, fields);
+}
+
+/**
+ * Render the declaration block for a candidate's recorded symbol references. Deterministic
+ * (refs arrive name-sorted from core; struct decls dedupe by tag). The block is prepended by
+ * the candidate compiler AFTER the typedef prelude — it spells types as u8/s16/… — and only in
+ * the self-declared world (the probe in compile-command.ts arbitrates; in the headers world
+ * both prelude and declarations are dropped, headers own everything).
+ */
+export function renderDeclarations(refs: SymbolRef[]): string {
+  const lines: string[] = [];
+  const declaredTags = new Set<string>();
+  for (const { name, info, access } of refs) {
+    // An address-cast macro declares itself: the header's own body, verbatim. It must NOT become
+    // an `extern` — that is the whole point of the fact (an extern emits a relocated pool word
+    // where the macro emits the numeric one the target shows).
+    if (info.macroBody !== undefined) {
+      lines.push(`#define ${name} ${info.macroBody}`);
+      continue;
+    }
+    if (info.kind === 'code') {
+      // value-referenced code symbol ((u32)Func): any prototype makes the name visible, and
+      // the address is arity-independent. Call targets never reach this module (core excludes
+      // them from symbolRefs — see collectSymbolRefs).
+      lines.push(`void ${name}(void);`);
+      continue;
+    }
+    switch (info.shape) {
+      case 'scalar': {
+        // Signedness default: absent + 4 bytes is the enum idiom (int ⇒ s32); absent + narrow
+        // has no honest spelling — skip (loud, see module note).
+        const t =
+          info.size !== undefined
+            ? intType(info.size, info.signed ?? (info.size === 4 ? ENUM_IS_SIGNED : false))
+            : null;
+        if (t !== null && (info.signed !== undefined || info.size === 4)) {
+          lines.push(`extern ${quals(info)}${t} ${name};`);
+        }
+        break;
+      }
+      case 'array': {
+        // Element type mirrors core's bare `gSym[i]` env typing exactly (elemSigned ?? false).
+        // A non-1/2/4 element width is never bare-indexed by core (only &gSym cast forms), so
+        // an unsized u8[] decl is codegen-identical for every spelling core emits.
+        const elem = info.elemSize !== undefined ? intType(info.elemSize, info.elemSigned ?? false) : null;
+        // The RANK must be reproduced, or the declaration disagrees with the access core spells:
+        // a `gSym[0][i]` needs a 2-D declaration to be an element rather than a type error. The
+        // OUTERMOST extent is always left unsized — it is the one C lets a declaration omit, and
+        // omitting it keeps this decl compatible with the project's real one whatever its size
+        // (the same reason the rank-1 form has always been `[]`). Inner extents are load-bearing:
+        // they are what scales each leading subscript, so they are spelled exactly.
+        const rank = (arrayInnerExtents(info) ?? []).map((d) => `[${d}]`).join('');
+        lines.push(`extern ${quals(info)}${elem ?? 'u8'} ${name}[]${rank};`);
+        break;
+      }
+      case 'struct': {
+        // With a layout: the padded struct decl + a typed extern (the `gSym.field` spelling
+        // compiles against it). Without one, every core spelling is &gSym-based (a struct
+        // global never spells bare), so an unsized u8[] extern is codegen-identical.
+        const tag = info.structName ?? `Asmlift_${name}`;
+        const decl = structDecl(tag, info.layout, info.size);
+        if (decl !== null) {
+          if (!declaredTags.has(tag)) {
+            declaredTags.add(tag);
+            lines.push(decl);
+          }
+          lines.push(`extern ${quals(info)}struct ${tag} ${name};`);
+        } else {
+          lines.push(`extern ${quals(info)}u8 ${name}[];`);
+        }
+        break;
+      }
+      case 'pointer': {
+        // With a POINTEE layout the emitter may spell an interior as `gPtr->member`, which only
+        // compiles against a pointer to that struct — so the pointee is declared here (the same
+        // padded synthesis a struct global gets) and the extern is typed. The declared pointee
+        // never changes bytes: the cell is 4 bytes whatever it addresses, and core's own lowering
+        // makes every arithmetic stride EXPLICIT (`(u8 *)gPtr + K` / `(u32)gPtr`), so no emitted
+        // expression is scaled by this type.
+        // Without one, pointee fidelity is unnecessary — load/store/compare of the cell are
+        // identical for any object-pointer type, and the output then never derefs through the
+        // decl's pointee.
+        // THE shared gate (symbols.ts pointeeFields): the typed extern is emitted on exactly
+        // the condition under which core may spell `gPtr->member`, so the two cannot disagree.
+        const tag = info.pointee?.structName;
+        const decl =
+          pointeeFields(info.pointee) !== null ? structDecl(tag!, info.pointee!.layout, info.pointee!.size) : null;
+        if (decl !== null && !declaredTags.has(tag!)) {
+          declaredTags.add(tag!);
+          lines.push(decl);
+        }
+        // The POINTEE's own qualifiers bind to the pointed-at type (`volatile struct S *g`); the
+        // cell's bind to the VARIABLE (`struct S *volatile g`). They are independent declarations
+        // of two different objects, and the synthesis reproduces each on its own side of the `*`.
+        const pointeeQuals = `${info.pointee?.volatile ? 'volatile ' : ''}${info.pointee?.const ? 'const ' : ''}`;
+        const pointeeType = decl !== null ? `${pointeeQuals}struct ${tag} *` : `${pointeeQuals}void *`;
+        lines.push(`extern ${pointeeType}${info.volatile ? 'volatile ' : ''}${info.const ? 'const ' : ''}${name};`);
+        break;
+      }
+      default: {
+        // Name-only (no sidecar shape) — the second documented exception (see the module note;
+        // the first is the 4-byte signless enum cell). Skipping here was the original rule, but
+        // it made every named-spelling row of a symtab-only map project (marioparty3: names
+        // with no DWARF shapes) unreproducible in the self-declared world — the benchmark
+        // compiled those candidates inside the project headers, which declare the symbol.
+        // The width authority is the candidate's OWN IR (ref.access, rank.ts
+        // bareGlobalAccessFacts): a bare `name = v` / `x = name` compiles to the access the
+        // tree performed only under a decl of that exact width (`extern u16 g;` is `sh` where
+        // a guessed u32 is `sw`). Without a bare off-0 access fact, every core spelling goes
+        // through `&name` casts, where any object decl is address-identical — u32 is the
+        // fallback cell. A divergent decl can only LOSE score — the target bytes derive from
+        // the truth decls, so a mis-declared compile can never false-match (same argument as
+        // enumIsSigned).
+        const t = access ? intType(access.width, access.signed) : null;
+        lines.push(`extern ${quals(info)}${t ?? 'u32'} ${name};`);
+        break;
+      }
+    }
+  }
+  return lines.length ? lines.join('\n') + '\n' : '';
+}
+
+/** The object-like `#define`s out of a rendered declaration block.
+ *
+ *  Address-cast macro defines are the one part of a synthesized block that must survive into the
+ *  HEADERS world too. Everything else there is owned by the injected headers (a duplicate typedef
+ *  or struct definition is a C89 hard error), but a duplicate `#define` with an identical body is
+ *  legal — and a PREPROCESSED project context has no macros left at all, so dropping these turns a
+ *  macro-named candidate into an `undeclared identifier` rather than a spelling choice. */
+export function macroDefinesOf(declarations: string | undefined): string {
+  if (!declarations) {
+    return '';
+  }
+  const lines = declarations.split('\n').filter((l) => l.startsWith('#define '));
+  return lines.length ? lines.join('\n') + '\n' : '';
+}