@asmlift/core 0.3.0 → 0.5.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.3.0",
+  "version": "0.5.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,
@@ -69,6 +142,8 @@ 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,
@@ -76,7 +151,9 @@ export interface StructFieldDecl {
  *  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 {
-  return `struct ${name} { ${fields.map((f) => `${f.volatile ? 'volatile ' : ''}${cDeclare(f.type, f.name)};`).join(' ')} };`;
+  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
@@ -103,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;
@@ -123,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;
@@ -141,6 +255,13 @@ 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}`;
@@ -173,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;
     }
   }
@@ -265,7 +388,10 @@ function printStmt(s: Stmt, indent: string, vt: VarTypes, leaf?: LeafHook): stri
           out.push(`${bi}break;`);
         }
       }
-      if (s.default) {
+      // `?.length`, not just presence: a label with no statement under it is not valid C89, and an
+      // L3 pass (dce, reindex) may empty a default that arrived with statements — the structurer's
+      // own "don't attach an empty default" rule cannot see that.
+      if (s.default?.length) {
         out.push(`${ci}default:`);
         for (const t of s.default) {
           out.push(...printStmt(t, bi, vt, leaf));
@@ -347,7 +473,7 @@ function cFamilyBody(fn0: SFn, leaf?: LeafHook): string[] {
   const vt: VarTypes = declaredTypes(fn);
   const lines: string[] = [];
   for (const l of fn.locals) {
-    lines.push(`    ${cType(l.type)} ${l.name};`);
+    lines.push(`    ${l.volatile ? 'volatile ' : ''}${cType(l.type)} ${l.name};`);
   }
   for (const s of fn.body) {
     lines.push(...printStmt(s, '    ', vt, leaf));

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

@@ -3,10 +3,10 @@
 // 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 Block, type Fn, type Value, successorsOf } 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 type { BinOp, Expr, SFn, Stmt } from './l3/ast';
+import { exprChildren, fieldSpellsDot, gapReasonFor, stmtChildren, stmtExprs } from './l3/ast';
 import { declaredTypes, exprCType } from './l3/typing';
 
 export class ContractError extends Error {
@@ -58,6 +58,170 @@ export function assertResolved(sfn: SFn): void {
   }
 }
 
+// ── effects: executed once, never dropped ──────────────────────────────────────────────────
+//
+// The three contracts around this one are about TYPING and SPELLABILITY. Nothing checked the
+// property the structurer's materialization model exists to preserve: a call in the asm must run
+// exactly as often in the emitted source. Its two failure modes are the two that hurt most —
+// asmlift's first rule is that a loud failure beats a silently wrong answer, and both of these are
+// silent:
+//
+//   • DROPPED — a call the asm makes has no counterpart in the tree at all;
+//   • RE-RUN  — inlining a call's value at more than one render position (or a structuring copy
+//     that duplicates a region onto a single path) makes one call execute twice. The round that
+//     recovered switch fall-through hit exactly this shape, and only an adversarial reviewer
+//     caught it.
+//
+// Deliberately narrow, so it never declines a function that is fine:
+//
+//   • CALLS only. Loads legitimately re-render (that is the whole point of the inline-at-use
+//     model, and the alias gate governs it); stores are checked by neither direction here because
+//     the readability DCE pass is allowed to drop a provably dead one.
+//   • PER PATH, not per tree. Structuring may legitimately emit one block twice — two exclusive
+//     switch arms sharing a body, a duplicated return merge — and each path still executes it
+//     once. So the duplication rule compares the maximum over syntactic root-to-leaf paths (a
+//     branch takes the max of its arms, a loop body counts once, a fall-through arm chains into
+//     the next) against the IR's static count.
+//   • Names the IR does not have are ignored, and only calls carrying a target symbol are counted
+//     (every frontend that emits `call` today stamps one).
+type CallCounts = Map<string, number>;
+
+/** per-key combine of two count maps (`sum` for sequence, `max` for exclusive alternatives) */
+function combine(a: CallCounts, b: CallCounts, f: (x: number, y: number) => number): CallCounts {
+  const out = new Map(a);
+  for (const [k, v] of b) {
+    out.set(k, f(out.get(k) ?? 0, v));
+  }
+  return out;
+}
+
+/** every `call` expression under `e`, counted by target name */
+function callsInExpr(e: Expr, into: CallCounts): void {
+  if (e.k === 'call') {
+    into.set(e.fn, (into.get(e.fn) ?? 0) + 1);
+  }
+  exprChildren(e).forEach((c) => callsInExpr(c, into));
+}
+
+/** `total` = every occurrence in the tree; `path` = the most any single syntactic path executes */
+function countCalls(stmts: Stmt[]): { total: CallCounts; path: CallCounts } {
+  let total: CallCounts = new Map();
+  let path: CallCounts = new Map();
+  const add = (r: { total: CallCounts; path: CallCounts }, pathF: (x: number, y: number) => number) => {
+    total = combine(total, r.total, (x, y) => x + y);
+    path = combine(path, r.path, pathF);
+  };
+  for (const s of stmts) {
+    const own: CallCounts = new Map();
+    stmtExprs(s).forEach((e) => callsInExpr(e, own));
+    add({ total: own, path: own }, (x, y) => x + y);
+    if (s.k === 'if') {
+      const t = countCalls(s.then);
+      const e = countCalls(s.else);
+      // exclusive arms: the path count is whichever arm runs, the total counts both
+      add(
+        { total: combine(t.total, e.total, (x, y) => x + y), path: combine(t.path, e.path, Math.max) },
+        (x, y) => x + y,
+      );
+    } else if (s.k === 'switch') {
+      const arms = s.cases.map((c) => countCalls(c.body));
+      const dflt = countCalls(s.default ?? []);
+      // A fall-through arm continues into the NEXT one emitted (the last into `default`), so a
+      // path through arm i runs the chain starting at i — the shape the fall-through round's
+      // CRITICAL took. Built from the end; `chain[i]` is that arm's per-path count.
+      const chain: CallCounts[] = new Array(arms.length);
+      for (let i = arms.length - 1; i >= 0; i--) {
+        const next = i + 1 < arms.length ? chain[i + 1] : dflt.path;
+        chain[i] = s.cases[i].fallsThrough ? combine(arms[i].path, next, (x, y) => x + y) : arms[i].path;
+      }
+      const armTotal = arms.reduce((acc, a) => combine(acc, a.total, (x, y) => x + y), dflt.total);
+      const armPath = chain.reduce((acc, c) => combine(acc, c, Math.max), dflt.path);
+      add({ total: armTotal, path: armPath }, (x, y) => x + y);
+    } else {
+      // Sequenced children (a loop body, a `for`'s init/inc): counted ONCE — a loop's dynamic trip
+      // count is not a syntactic occurrence, and the IR side is static too.
+      for (const c of stmtChildren(s)) {
+        add(countCalls([c]), (x, y) => x + y);
+      }
+    }
+  }
+  return { total, path };
+}
+
+/**
+ * Post structuring: every call the asm makes is emitted, and none is emitted more times than the
+ * asm makes it on any one path. See the note above for what this deliberately does not cover.
+ */
+export function assertEffectsPreserved(fn: Fn, sfn: SFn): void {
+  // Reachable blocks only: an unreachable block's call is legitimately never emitted.
+  const seen = new Set<Block>([fn.blocks[0]]);
+  for (const stack = [fn.blocks[0]]; stack.length;) {
+    for (const s of successorsOf(stack.pop()!)) {
+      if (!seen.has(s)) {
+        seen.add(s);
+        stack.push(s);
+      }
+    }
+  }
+  const irCalls: CallCounts = new Map();
+  // Unmodelled instructions, by the mnemonic the frontend stamped. Same "never dropped" property as
+  // a call, and it needs its own tally because an `opaque` carries no `target`.
+  const irOpaques = new Set<string>();
+  for (const b of seen) {
+    for (const op of b.ops) {
+      if (op.opcode === 'call' && typeof op.attrs.target === 'string') {
+        const t = op.attrs.target;
+        irCalls.set(t, (irCalls.get(t) ?? 0) + 1);
+      } else if (op.opcode === 'opaque') {
+        irOpaques.add(gapReasonFor(op.attrs.mnemonic));
+      }
+    }
+  }
+  // DROPPED only, not the RE-RUN half: a gap rendered twice is a diagnostic printed twice, which
+  // costs nothing because nothing recompiles it, and structuring legitimately duplicates a shared
+  // arm — so a per-path count here would fire on correct output.
+  //
+  // Bites only in ANNOTATE mode (under `strict` the gap is the `?` sentinel and structure() has
+  // already thrown), which is where it is needed: that is the CLI and benchmark default, and the
+  // only mode with no other backstop against a silently dropped opaque.
+  if (irOpaques.size) {
+    const emitted = new Set<string>();
+    const we = (e: Expr): void => {
+      if (e.k === 'marker') {
+        emitted.add(e.reason);
+      }
+      exprChildren(e).forEach(we);
+    };
+    const ws = (s: Stmt): void => {
+      stmtExprs(s).forEach(we);
+      stmtChildren(s).forEach(ws);
+    };
+    sfn.body.forEach(ws);
+    for (const reason of irOpaques) {
+      if (!emitted.has(reason)) {
+        throw new ContractError(
+          `structuring dropped the ${reason} in '${sfn.name}' — an instruction asmlift could not model left no trace`,
+        );
+      }
+    }
+  }
+  if (!irCalls.size) {
+    return;
+  }
+  const { total, path } = countCalls(sfn.body);
+  for (const [name, n] of irCalls) {
+    if (!(total.get(name) ?? 0)) {
+      throw new ContractError(`structuring dropped the call to '${name}' in '${sfn.name}' — its effect is lost`);
+    }
+    const p = path.get(name) ?? 0;
+    if (p > n) {
+      throw new ContractError(
+        `structuring emitted ${p} calls to '${name}' on one path in '${sfn.name}', where the asm makes ${n}`,
+      );
+    }
+  }
+}
+
 /** 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
@@ -71,8 +235,21 @@ 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

package/src/declare.ts

@@ -37,6 +37,7 @@ import {
   ENUM_IS_SIGNED,
   type SymbolInfo,
   type SymbolStructField,
+  arrayInnerExtents,
   declaredFields,
   pointeeFields,
   symbolFieldType,
@@ -75,23 +76,41 @@ function structDecl(tag: string, layout: SymbolStructField[] | undefined, size:
     return null;
   }
   const fields: StructFieldDecl[] = [];
-  let cursor = 0;
+  // 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;
-  for (const m of members) {
-    if (m.offset > cursor) {
+  const padTo = (lo: number): void => {
+    while (bitCursor < lo) {
       // asmlift_-prefixed so a REAL member named pad_N (a decomp-header idiom) never collides
-      fields.push({ name: `asmlift_pad_${pad++}`, type: T.array(T.u(8), m.offset - cursor) });
+      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 } : {}),
     });
-    cursor = m.offset + m.size;
+    bitCursor = bits ? lo + m.bitWidth! : (m.offset + m.size) * 8;
   }
-  if (size !== undefined && size > cursor) {
-    // tail padding to the declared size
-    fields.push({ name: `asmlift_pad_${pad}`, type: T.array(T.u(8), size - cursor) });
+  if (size !== undefined) {
+    padTo(size * 8); // tail padding to the declared size
   }
   return renderStructDecl(tag, fields);
 }
@@ -139,7 +158,14 @@ export function renderDeclarations(refs: SymbolRef[]): string {
         // 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;
-        lines.push(`extern ${quals(info)}${elem ?? 'u8'} ${name}[];`);
+        // 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': {