@asmlift/core 0.1.0

package/src/ir/core.ts

@@ -0,0 +1,104 @@
+// asmlift IR — the MLIR-lite substrate shared by all levels.
+//
+//   - a CFG of basic blocks with TYPED BLOCK-ARGUMENTS (functional-form SSA); no phi
+//   - exactly one terminator per block; terminators carry successors + block-arg lists
+//   - Value identity is OBJECT IDENTITY, owned by the graph — no module-global counter;
+//     textual names are assigned at print time by deterministic traversal
+//   - passes transform via replaceAllUsesWith, never in-place opcode/type mutation
+//
+// The two real representations are this `Fn` (typed-SSA) and the structured `SFn` AST; type
+// recovery is an in-place pass on `Fn`.
+import type { Opcode } from './opcodes';
+import type { IrType } from './types';
+
+export type AttrVal = number | boolean | string | number[];
+
+/** An SSA value. Identity is the object itself; the type may be `unknown` at L1. */
+export interface Value {
+  type: IrType;
+}
+
+/** A branch target: which block, and the arguments bound to its block-parameters. */
+export interface Successor {
+  block: Block;
+  args: Value[];
+}
+
+export interface Op {
+  opcode: string;
+  operands: Value[];
+  results: Value[];
+  attrs: Record<string, AttrVal>;
+  successors: Successor[]; // non-empty only for terminators
+}
+
+/** A basic block. `params` are its block-arguments. Must end in exactly one terminator. */
+export interface Block {
+  params: Value[];
+  ops: Op[];
+}
+
+/** A function. `blocks[0]` is the entry; its params are the function parameters. */
+export interface Fn {
+  name: string;
+  blocks: Block[];
+}
+
+export function mkValue(type: IrType): Value {
+  return { type };
+}
+
+export function mkOp(opcode: Opcode, o: Partial<Op> = {}): Op {
+  return {
+    opcode,
+    operands: o.operands ?? [],
+    results: o.results ?? [],
+    attrs: o.attrs ?? {},
+    successors: o.successors ?? [],
+  };
+}
+
+/** The successor blocks of `b`, read off its terminator. */
+export function successorsOf(b: Block): Block[] {
+  const term = b.ops[b.ops.length - 1];
+  return term ? term.successors.map((s) => s.block) : [];
+}
+
+/** Predecessor map for the whole function's CFG. */
+export function predecessors(fn: Fn): Map<Block, Block[]> {
+  const preds = new Map<Block, Block[]>();
+  for (const b of fn.blocks) {
+    preds.set(b, []);
+  }
+  for (const b of fn.blocks) {
+    for (const s of successorsOf(b)) {
+      preds.get(s)!.push(b);
+    }
+  }
+  return preds;
+}
+
+/** Every value defined by an op result → its defining op (block params excluded). */
+export function defOpMap(fn: Fn): Map<Value, Op> {
+  const m = new Map<Value, Op>();
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      for (const r of op.results) {
+        m.set(r, op);
+      }
+    }
+  }
+  return m;
+}
+
+/** Replace every use of `oldV` with `newV` (operands + successor args). No in-place op mutation. */
+export function replaceAllUsesWith(fn: Fn, oldV: Value, newV: Value): void {
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      op.operands = op.operands.map((v) => (v === oldV ? newV : v));
+      for (const s of op.successors) {
+        s.args = s.args.map((v) => (v === oldV ? newV : v));
+      }
+    }
+  }
+}

package/src/ir/opcodes.ts

@@ -0,0 +1,143 @@
+// asmlift IR — the opcode signature registry.
+//
+// A closed table of signatures. The verifier and the parser are driven by it, so a mnemonic
+// typo or an operand-count mismatch fails at its source instead of surfacing as wrong output
+// several stages later.
+
+export interface OpSig {
+  /** exact operand count, or "variadic" (e.g. ret takes 0 or 1). */
+  operands: number | 'variadic';
+  results: number;
+  terminator?: boolean;
+  /** required successor count (terminators only), or "variadic" (switch_br: N cases + 1 default). */
+  successors?: number | 'variadic';
+  requiredAttrs?: readonly string[];
+  /** observable side effect (memory write / call): never deleted when dead, never hoisted into
+   *  an unconditional position. THE one effect vocabulary — DCE (pattern/engine.ts) and the
+   *  short-circuit hoist guard (raise/shortcircuit.ts) both derive from this flag. */
+  effects?: boolean;
+}
+
+export const OPCODES = {
+  // --- pure integer ops ---
+  const: { operands: 0, results: 1, requiredAttrs: ['value'] },
+  add: { operands: 2, results: 1 },
+  sub: { operands: 2, results: 1 },
+  mul: { operands: 2, results: 1 },
+  // High word of the 32x32->64 product: `mulh` signed, `mulhu` unsigned. TRANSIENT — emitted by the
+  // frontend (MIPS `mfhi` after `mult`/`multu`; PPC `mulhw`/`mulhwu`) and rewritten away by the
+  // magic-division recognizer (raise/magicdiv.ts) before recovery. They carry no C spelling: a `mulh`
+  // that survives to the structurer hits the `"?"` loud-fail (like a bare `clz`) — never printed.
+  // Effect-free (no `effects` flag) so DCE reaps a dead one.
+  mulh: { operands: 2, results: 1 },
+  mulhu: { operands: 2, results: 1 },
+  neg: { operands: 1, results: 1 },
+  not: { operands: 1, results: 1 }, // bitwise complement (`mvn`) → ~x
+  or: { operands: 2, results: 1 },
+  and: { operands: 2, results: 1 },
+  xor: { operands: 2, results: 1 },
+  // shifts take EITHER 1 operand + `imm` attr (immediate: `lsl rD,rS,#n`) OR 2 operands
+  // (register: `lsl rD,rS,rN`). Variadic so both forms verify; the structurer branches on
+  // operand count (structure.ts) to print `x << n` vs `x << y`.
+  shl: { operands: 'variadic', results: 1 },
+  shr_u: { operands: 'variadic', results: 1 },
+  shr_s: { operands: 'variadic', results: 1 },
+  // Rotates, variadic like the shifts (immediate: PPC `rotlwi`; register: Thumb `ror`, PPC
+  // `rotlw`). Lowered by the structurer to the C rotate idiom (`x >> n | x << (32 - n)` /
+  // mirrored for rotl), which agbcc AND mwcc compile back to the single rotate instruction —
+  // byte-exact round-trip verified both ways before these ops landed.
+  rotr: { operands: 'variadic', results: 1 },
+  rotl: { operands: 'variadic', results: 1 },
+  // Count leading zeros (PPC `cntlzw`). TRANSIENT like mulh: the cntlzw-equality pattern
+  // (pattern/engine.ts CNTLZW_EQ0, mwcc-gated) folds `clz(x) >> 5` → `x == 0` (mwcc's spelling
+  // of ==0 and `!`); a bare clz that survives has no C spelling → the structurer's loud gap.
+  clz: { operands: 1, results: 1 },
+  // width-narrowing casts (S4): `zext`/`sext` take one operand and a `width` attr (8/16), and
+  // widen back to 32 with zero/sign extension — the recovered form of a compiler's byte/half
+  // extend idiom (`(x<<24)>>24` etc.). The backend prints them as a C cast `(u8)x` / `(s8)x`;
+  // recompiling the cast reproduces the extend sequence on the compilers that emit it. Produced
+  // by the cast idiom patterns (pattern/engine.ts), gated to those compilers.
+  zext: { operands: 1, results: 1, requiredAttrs: ['width'] },
+  sext: { operands: 1, results: 1, requiredAttrs: ['width'] },
+  // Division/remainder. `sdiv` is variadic like the shifts: the immediate form (1 operand +
+  // `imm` attr) is the strength-reduced constant divisor an idiom folds to (`sdiv X {imm=2}`);
+  // the register form (2 operands) is a real hardware divide (`div`/`divu` + `mflo`/`mfhi` on an
+  // ISA with `capabilities.hwDivide`); the structurer branches on count. `udiv`/`smod`/`umod`
+  // are 2-operand only. `sdiv`/`udiv` = quotient, `smod`/`umod` = remainder; signedness lives in
+  // the op (recovery types the operands to match), so the backend picks `/`/`%` over
+  // correctly-typed operands.
+  sdiv: { operands: 'variadic', results: 1 },
+  udiv: { operands: 2, results: 1 },
+  smod: { operands: 2, results: 1 },
+  umod: { operands: 2, results: 1 },
+  // signed/equality comparisons (result is a boolean-valued u32)
+  icmp_slt: { operands: 2, results: 1 },
+  icmp_sle: { operands: 2, results: 1 },
+  icmp_sgt: { operands: 2, results: 1 },
+  icmp_sge: { operands: 2, results: 1 },
+  // unsigned comparisons (MIPS `sltu`/`sltiu`; the operator is the same `<`, unsignedness lives
+  // in the operand TYPES — recover types their operands u32, so the backend emits `sltu`).
+  icmp_ult: { operands: 2, results: 1 },
+  icmp_ule: { operands: 2, results: 1 },
+  icmp_ugt: { operands: 2, results: 1 },
+  icmp_uge: { operands: 2, results: 1 },
+  icmp_eq: { operands: 2, results: 1 },
+  icmp_ne: { operands: 2, results: 1 },
+  // Short-circuit logical connectives (`&&`/`||`), produced by the boolean short-circuit recognizer
+  // (raise/shortcircuit.ts) from a value-merge diamond. Both operands are boolean-valued (0/1); the
+  // result is the 0/1 connective. Distinct from bitwise `and`/`or` — the backend prints `&&`/`||`,
+  // which recompiles to the branch diamond the source emitted.
+  logic_and: { operands: 2, results: 1 },
+  logic_or: { operands: 2, results: 1 },
+  // --- memory ---
+  load: { operands: 1, results: 1, requiredAttrs: ['off', 'width', 'signed'] },
+  store: { operands: 2, results: 0, requiredAttrs: ['off', 'width'], effects: true },
+  // Typed element-scaled array access. Unlike load/store's constant `off`, these carry an
+  // explicit runtime `index` operand plus the `elemSize` the index scales by, so the base is a
+  // genuine `elem *` and no byte-offset arithmetic leaks into the emitted source. Produced by
+  // the array-recognition legalization pass (raise/arrays.ts).
+  aload: { operands: 2, results: 1, requiredAttrs: ['elemSize', 'signed'] }, // aload base, index
+  astore: { operands: 3, results: 0, requiredAttrs: ['elemSize'], effects: true }, // astore base, index, value
+  // --- call: operands are the argument values (r0..), result is the return value (r0),
+  //     `target` attr is the callee symbol. Caller-saved clobbering is implicit. ---
+  call: { operands: 'variadic', results: 1, requiredAttrs: ['target'], effects: true },
+  // The ADDRESS of a named global (agbcc `ldr rD, .Lpool` where the pool word is `.word gSym`).
+  // Pure, 0 operands. Globals come from the project headers, so they are referenced by name, never
+  // declared as locals. The structurer lowers it three ways (see scalarGlobals in structure.ts):
+  //   - a load/store through an off-0 SCALAR gaddr → a bare global `gSym` / `gSym = v`;
+  //   - an indexed or non-zero-offset AGGREGATE access → the address-cast `((T *)&gSym)[i]`;
+  //   - any other use (e.g. `&gSym` passed to a call) → the `{k:'addr'}` L3 node, printed `&gSym`.
+  gaddr: { operands: 0, results: 1, requiredAttrs: ['sym'] },
+  // --- black-box escape hatch (keeps lifting total) ---
+  opaque: { operands: 'variadic', results: 1 },
+  // --- terminators ---
+  ret: { operands: 'variadic', results: 0, terminator: true, successors: 0 },
+  br: { operands: 0, results: 0, terminator: true, successors: 1 },
+  cond_br: { operands: 1, results: 0, terminator: true, successors: 2 },
+  // Many-way switch dispatch (Regime B, jump table). The single operand is the scrutinee;
+  // successors are the N case blocks followed by the default block (the LAST successor);
+  // `cases` is the index-aligned list of the first N successors' case values.
+  switch_br: { operands: 1, results: 0, terminator: true, successors: 'variadic', requiredAttrs: ['cases'] },
+} as const satisfies Record<string, OpSig>;
+
+/** The registered opcode vocabulary as a TYPE — `mkOp("add", …)` compiles, `mkOp("addd", …)`
+ *  does not. */
+export type Opcode = keyof typeof OPCODES;
+
+/** Signature lookup by RUNTIME opcode string (Op.opcode is a plain string — IR consumers switch
+ *  on it); undefined for an unregistered opcode. */
+export function opSig(opcode: string): OpSig | undefined {
+  return (OPCODES as Record<string, OpSig | undefined>)[opcode];
+}
+
+/** Ops with an observable side effect — the derived view raise/shortcircuit.ts consumes. */
+export const EFFECTFUL_OPS: ReadonlySet<string> = new Set(
+  (Object.keys(OPCODES) as Opcode[]).filter((k) => (OPCODES[k] as OpSig).effects),
+);
+
+/** May a dead result of this opcode be deleted? Registered, no observable effects, not control
+ *  flow. Deliberately includes `opaque` — a dead opaque vanishing is designed behavior. */
+export function isDceSafe(opcode: string): boolean {
+  const sig = opSig(opcode);
+  return !!sig && !sig.effects && !sig.terminator;
+}

package/src/ir/parse.ts

@@ -0,0 +1,221 @@
+// asmlift IR — the textual parser (the inverse of print.ts).
+//
+// The parser exists so that `parse(print(fn))` round-trips: the same textual artifact is
+// both the debug dump and the test oracle. The parser builds the graph but enforces NO
+// semantics — that is the verifier's job — so malformed-but-well-formed-syntax IR can be
+// constructed and then rejected by verify().
+// ROUND-TRIP DOMAIN: parse(print(fn)) holds for L1/scalar types only — `unkN`/`sN`/`uN` and
+// `*`-pointers to them. STRUCT/ARRAY/VOID types print (typeToString) but do NOT parse back; a
+// post-type-recovery dump is a one-way debugging artifact, not a test oracle.
+import { Block, Fn, Op, Successor, Value, mkOp, mkValue } from './core';
+import type { Opcode } from './opcodes';
+import { IrType, parseType } from './types';
+
+export function parse(text: string): Fn {
+  const raw = text.split('\n').map((l) => l.replace(/\r$/, ''));
+  let i = 0;
+  while (i < raw.length && raw[i].trim() === '') {
+    i++;
+  }
+  const fnM = raw[i]?.match(/^fn (\w+) \{$/);
+  if (!fnM) {
+    throw new Error(`expected 'fn NAME {', got '${raw[i] ?? '<eof>'}'`);
+  }
+  const name = fnM[1];
+  i++;
+
+  const body: string[] = [];
+  for (; i < raw.length; i++) {
+    if (raw[i] === '}') {
+      break;
+    }
+    if (raw[i].trim() === '') {
+      continue;
+    }
+    body.push(raw[i].trim());
+  }
+
+  // PASS A — create all blocks and pre-declare every value by its textual name, so
+  // operands can resolve regardless of definition order (incl. loop back-edges).
+  const valueByName = new Map<string, Value>();
+  const declValue = (nm: string, ty: IrType): Value => {
+    let v = valueByName.get(nm);
+    if (!v) {
+      v = mkValue(ty);
+      valueByName.set(nm, v);
+    } else {
+      v.type = ty;
+    }
+    return v;
+  };
+
+  interface RawBlock {
+    block: Block;
+    opLines: string[];
+  }
+  const rawBlocks: RawBlock[] = [];
+  const blockByLabel = new Map<string, Block>();
+  let cur: RawBlock | null = null;
+
+  for (const line of body) {
+    const bh = line.match(/^\^(\w+)\((.*)\):$/);
+    if (bh) {
+      const block: Block = { params: [], ops: [] };
+      cur = { block, opLines: [] };
+      rawBlocks.push(cur);
+      if (blockByLabel.has(bh[1])) {
+        throw new Error(`duplicate block label '${bh[1]}'`);
+      }
+      blockByLabel.set(bh[1], block);
+      for (const p of splitTop(bh[2])) {
+        const pm = p.match(/^(%\w+):\s*(.+)$/);
+        if (!pm) {
+          throw new Error(`bad block param '${p}'`);
+        }
+        block.params.push(declValue(pm[1], parseType(pm[2])));
+      }
+      continue;
+    }
+    if (!cur) {
+      throw new Error(`op outside any block: '${line}'`);
+    }
+    cur.opLines.push(line);
+    const eq = splitEquals(line);
+    if (eq) {
+      for (const r of splitTop(eq.results)) {
+        const rm = r.match(/^(%\w+):\s*(.+)$/);
+        if (!rm) {
+          throw new Error(`bad result decl '${r}'`);
+        }
+        declValue(rm[1], parseType(rm[2]));
+      }
+    }
+  }
+
+  // PASS B — wire operands / successor args / results.
+  const refValue = (nm: string): Value => {
+    const v = valueByName.get(nm);
+    if (!v) {
+      throw new Error(`reference to undefined value '${nm}'`);
+    }
+    return v;
+  };
+  const refBlock = (label: string): Block => {
+    const b = blockByLabel.get(label);
+    if (!b) {
+      throw new Error(`reference to undefined block '^${label}'`);
+    }
+    return b;
+  };
+  for (const rb of rawBlocks) {
+    for (const line of rb.opLines) {
+      rb.block.ops.push(parseOp(line, refValue, refBlock));
+    }
+  }
+
+  return { name, blocks: rawBlocks.map((r) => r.block) };
+}
+
+function parseOp(line: string, refValue: (nm: string) => Value, refBlock: (label: string) => Block): Op {
+  const eq = splitEquals(line);
+  const results: Value[] = eq ? splitTop(eq.results).map((r) => refValue(r.match(/^(%\w+):/)![1])) : [];
+  let rest = eq ? eq.rest : line;
+
+  let attrs: Record<string, number | boolean | string | number[]> = {};
+  const am = rest.match(/\s*\{([^}]*)\}\s*$/);
+  if (am) {
+    attrs = parseAttrs(am[1]);
+    rest = rest.slice(0, am.index).trim();
+  }
+
+  const sp = rest.indexOf(' ');
+  const opcode = sp < 0 ? rest : rest.slice(0, sp);
+  const argStr = sp < 0 ? '' : rest.slice(sp + 1);
+
+  const operands: Value[] = [];
+  const successors: Successor[] = [];
+  for (const arg of splitTop(argStr)) {
+    if (arg.startsWith('^')) {
+      const sm = arg.match(/^\^(\w+)\((.*)\)$/);
+      if (!sm) {
+        throw new Error(`bad successor '${arg}'`);
+      }
+      successors.push({ block: refBlock(sm[1]), args: splitTop(sm[2]).map(refValue) });
+    } else if (arg.startsWith('%')) {
+      operands.push(refValue(arg));
+    } else {
+      throw new Error(`unexpected operand '${arg}'`);
+    }
+  }
+  return mkOp(opcode as Opcode, { operands, results, attrs, successors }); // data boundary: verify() rejects unknowns
+}
+
+// --- small text helpers ---
+
+/** Split on top-level commas only (ignore commas inside (...), {...} or [...] — print.ts's
+ *  list attrs are bracketed and rely on this tracking). */
+function splitTop(s: string): string[] {
+  const out: string[] = [];
+  let depth = 0,
+    cur = '';
+  for (const c of s) {
+    if (c === '(' || c === '{' || c === '[') {
+      depth++;
+    } else if (c === ')' || c === '}' || c === ']') {
+      depth--;
+    }
+    if (c === ',' && depth === 0) {
+      if (cur.trim()) {
+        out.push(cur.trim());
+      }
+      cur = '';
+    } else {
+      cur += c;
+    }
+  }
+  if (cur.trim()) {
+    out.push(cur.trim());
+  }
+  return out;
+}
+
+/** Split at the first top-level " = " (not inside attrs braces). */
+function splitEquals(t: string): { results: string; rest: string } | null {
+  let depth = 0;
+  for (let k = 0; k + 3 <= t.length; k++) {
+    const c = t[k];
+    if (c === '(' || c === '{') {
+      depth++;
+    } else if (c === ')' || c === '}') {
+      depth--;
+    } else if (depth === 0 && t.startsWith(' = ', k)) {
+      return { results: t.slice(0, k).trim(), rest: t.slice(k + 3).trim() };
+    }
+  }
+  return null;
+}
+
+function parseAttrs(s: string): Record<string, number | boolean | string | number[]> {
+  const a: Record<string, number | boolean | string | number[]> = {};
+  for (const pair of splitTop(s)) {
+    const eqi = pair.indexOf('=');
+    if (eqi < 0) {
+      throw new Error(`bad attr '${pair}'`);
+    }
+    const k = pair.slice(0, eqi).trim();
+    const raw = pair.slice(eqi + 1).trim();
+    if (raw.startsWith('"')) {
+      a[k] = JSON.parse(raw);
+    } else if (raw === 'true') {
+      a[k] = true;
+    } else if (raw === 'false') {
+      a[k] = false;
+    } else if (raw.startsWith('[')) {
+      a[k] = raw.slice(1, -1).split(';').filter(Boolean).map(Number);
+    } // switch_br cases
+    else {
+      a[k] = Number(raw);
+    }
+  }
+  return a;
+}

package/src/ir/print.ts

@@ -0,0 +1,77 @@
+// asmlift IR — the canonical textual printer.
+//
+// Determinism: value names are assigned HERE, at print time, by a fixed traversal
+// (blocks in order; within a block, params then op-results). Two
+// structurally-identical functions therefore print byte-identically regardless of the
+// order their Value objects were created — there is no global counter to leak order.
+import type { AttrVal, Block, Fn, Value } from './core';
+import { typeToString } from './types';
+
+export function print(fn: Fn): string {
+  const blockLabel = new Map<Block, string>();
+  fn.blocks.forEach((b, i) => blockLabel.set(b, `bb${i}`));
+
+  const name = new Map<Value, string>();
+  let counter = 0;
+  const assign = (v: Value) => {
+    if (!name.has(v)) {
+      name.set(v, `%${counter++}`);
+    }
+    return name.get(v)!;
+  };
+  for (const b of fn.blocks) {
+    for (const p of b.params) {
+      assign(p);
+    }
+    for (const op of b.ops) {
+      for (const r of op.results) {
+        assign(r);
+      }
+    }
+  }
+  const ref = (v: Value) => name.get(v) ?? '%<undef>';
+
+  const lines: string[] = [`fn ${fn.name} {`];
+  for (const b of fn.blocks) {
+    const params = b.params.map((p) => `${ref(p)}: ${typeToString(p.type)}`).join(', ');
+    lines.push(`^${blockLabel.get(b)}(${params}):`);
+    for (const op of b.ops) {
+      let s = '  ';
+      if (op.results.length) {
+        s += op.results.map((r) => `${ref(r)}: ${typeToString(r.type)}`).join(', ') + ' = ';
+      }
+      s += op.opcode;
+      const args: string[] = [];
+      for (const o of op.operands) {
+        args.push(ref(o));
+      }
+      for (const su of op.successors) {
+        args.push(`^${blockLabel.get(su.block)}(${su.args.map(ref).join(', ')})`);
+      }
+      if (args.length) {
+        s += ' ' + args.join(', ');
+      }
+      s += fmtAttrs(op.attrs);
+      lines.push(s);
+    }
+  }
+  lines.push('}');
+  return lines.join('\n') + '\n';
+}
+
+function fmtAttrs(a: Record<string, AttrVal>): string {
+  const keys = Object.keys(a).sort();
+  if (keys.length === 0) {
+    return '';
+  }
+  return ' {' + keys.map((k) => `${k}=${fmtAttr(a[k])}`).join(', ') + '}';
+}
+
+function fmtAttr(v: AttrVal): string {
+  // A list attr (switch_br `cases`) prints bracketed so `parseAttrs`' top-level comma split (which
+  // tracks `[`/`(`/`{` depth) keeps it as one token and round-trips it back to a number[].
+  if (Array.isArray(v)) {
+    return `[${v.join(';')}]`;
+  }
+  return typeof v === 'string' ? JSON.stringify(v) : String(v);
+}

package/src/ir/types.ts

@@ -0,0 +1,106 @@
+// asmlift IR — semantic types. NOT language type strings (a hard requirement from
+// the language-backend study: each backend picks its own spelling from these).
+
+/** One recovered field of a struct: its byte offset within the struct, its recovered
+ *  scalar/pointer type, and its (currently synthetic, offset-derived) name. */
+export interface StructField {
+  off: number;
+  type: IrType;
+  name: string;
+}
+
+export type IrType =
+  | { kind: 'unknown'; width: number } // width in bits; type not yet recovered
+  | { kind: 'int'; width: number; signed: boolean }
+  | { kind: 'ptr'; to: IrType }
+  // A recovered aggregate: heterogeneous fields at byte offsets (raise/structs.ts). Distinct
+  // from `ptr(int)`+array-index because its access pattern is inconsistent with a homogeneous
+  // array (mixed widths / non-uniform offsets). `name` is synthetic today (`Struct0`); a later
+  // DWARF pass supplies real names. Fields are sorted by `off`.
+  | { kind: 'struct'; name: string; fields: StructField[]; size?: number }
+  // A fixed-length array `elem[count]`. Today its sole inhabitant is struct padding (a `u8[N]`
+  // pad member seats fields at their exact offsets, raise/struct-arrays.ts) — a REAL type,
+  // not a printed string. Array-typed fields declare with the length AFTER the name in C
+  // (`u8 _pad[4]`), so the backend routes them through a declarator-aware `cDeclare`, not the
+  // prefix `cType`.
+  | { kind: 'array'; elem: IrType; count: number }
+  | { kind: 'void' }; // a function that returns nothing
+
+/** The scalar type of a memory access of `width` bytes: word ⇒ the s32 integer default;
+ *  narrower widths carry the access's signedness. THE one copy of a match-critical rule (it
+ *  decides emitted decl types), consumed by recover.ts, structs.ts, and struct-arrays — a
+ *  per-consumer copy would silently diverge struct fields from pointer pointees. */
+export function scalarTypeForAccess(width: number, signed: boolean): IrType {
+  return width === 4 ? T.s(32) : T.int(width * 8, signed);
+}
+
+export const T = {
+  unk: (width = 32): IrType => ({ kind: 'unknown', width }),
+  int: (width: number, signed: boolean): IrType => ({ kind: 'int', width, signed }),
+  s: (width = 32): IrType => ({ kind: 'int', width, signed: true }),
+  u: (width = 32): IrType => ({ kind: 'int', width, signed: false }),
+  ptr: (to: IrType): IrType => ({ kind: 'ptr', to }),
+  struct: (name: string, fields: StructField[], size?: number): IrType => ({ kind: 'struct', name, fields, size }),
+  array: (elem: IrType, count: number): IrType => ({ kind: 'array', elem, count }),
+  void: (): IrType => ({ kind: 'void' }),
+};
+
+export function typeToString(t: IrType): string {
+  switch (t.kind) {
+    case 'unknown':
+      return `unk${t.width}`;
+    case 'int':
+      return `${t.signed ? 's' : 'u'}${t.width}`;
+    case 'ptr':
+      return `${typeToString(t.to)}*`;
+    case 'struct':
+      return t.name;
+    case 'array':
+      return `${typeToString(t.elem)}[${t.count}]`;
+    case 'void':
+      return 'void';
+  }
+}
+
+export function parseType(s: string): IrType {
+  s = s.trim();
+  if (s.endsWith('*')) {
+    return T.ptr(parseType(s.slice(0, -1)));
+  }
+  const m = s.match(/^(unk|s|u)(\d+)$/);
+  if (!m) {
+    throw new Error(`bad type '${s}'`);
+  }
+  const width = parseInt(m[2], 10);
+  if (m[1] === 'unk') {
+    return T.unk(width);
+  }
+  return T.int(width, m[1] === 's');
+}
+
+export function typeEquals(a: IrType, b: IrType): boolean {
+  if (a.kind === 'ptr' && b.kind === 'ptr') {
+    return typeEquals(a.to, b.to);
+  }
+  if (a.kind === 'int' && b.kind === 'int') {
+    return a.width === b.width && a.signed === b.signed;
+  }
+  if (a.kind === 'unknown' && b.kind === 'unknown') {
+    return a.width === b.width;
+  }
+  if (a.kind === 'array' && b.kind === 'array') {
+    return a.count === b.count && typeEquals(a.elem, b.elem);
+  }
+  // Two structs are equal when their name + field layout match (recovered structs are named
+  // by layout-discovery order, so equal name ⇒ equal layout in practice).
+  if (a.kind === 'struct' && b.kind === 'struct') {
+    return (
+      a.name === b.name &&
+      a.fields.length === b.fields.length &&
+      a.fields.every(
+        (f, i) => f.off === b.fields[i].off && f.name === b.fields[i].name && typeEquals(f.type, b.fields[i].type),
+      )
+    );
+  }
+  return false;
+}