@asmlift/core 0.1.0

package/src/structure/switch-recover.ts

@@ -0,0 +1,410 @@
+// asmlift structurer — Regime-A SWITCH RECOVERY: recognise a comparison tree over a single
+// scrutinee rooted at a cond_br and rebuild the `switch` — or DECLINE (null) to plain
+// if-recovery, which is behaviourally identical (a clean nonmatch, never a miscompile). The
+// factory takes its dependencies EXPLICITLY (`SwitchRecoverDeps`); `expr`/`structureRegion` are
+// late-bound callbacks into the emission phase, so case bodies reuse the ordinary structuring
+// machinery (loops/ifs inside cases, the onStack guard).
+import { Block, Fn, Op, Value, successorsOf } from '../ir/core';
+import { Expr, Stmt, SwitchCase } from '../l3/ast';
+
+export interface SwitchRecoverDeps {
+  fn: Fn;
+  defs: Map<Value, Op>;
+  dom: Map<Block, Set<Block>>;
+  ipdom: Map<Block, Block | null>;
+  opBlock: Map<Op, Block>;
+  /** does this value carry a variable name? (named values are not constants) */
+  isNamed: (v: Value) => boolean;
+  /** is this opcode an integer comparison? */
+  isCmpOpcode: (opcode: string) => boolean;
+  switchAllowsNeqCase: boolean;
+  expr: (v: Value) => Expr;
+  structureRegion: (b: Block, stop: Block | null) => Stmt[];
+}
+
+export interface SwitchRecovery {
+  recognizeSwitch: (b: Block, stop: Block | null) => Stmt[] | null;
+  /** shared with the Regime-B (`switch_br`) path in structure.ts, which throws where A declines */
+  caseRegionReachesSibling: (targets: Set<Block>, b: Block, merge: Block | null) => boolean;
+}
+
+export function makeSwitchRecovery(deps: SwitchRecoverDeps): SwitchRecovery {
+  const { fn, defs, dom, ipdom, opBlock, isNamed, isCmpOpcode, switchAllowsNeqCase, expr, structureRegion } = deps;
+
+  // --- Regime A: comparison-tree switch recovery ----------------------------------------------------
+  // Every ambiguity declines. Four preconditions are enforced below, annotated PRE1..PRE4:
+  // scrutinee identity/dominance, no fall-through, concrete interval consistency, test purity.
+
+  // Fold a value that is a compile-time constant (a `const`, or a synthesized immediate like agbcc's
+  // `250 << 2` for a large sparse case) to a number — else null.
+  const evalConst = (v: Value): number | null => {
+    if (isNamed(v)) {
+      return null;
+    } // a named variable is not a constant
+    const d = defs.get(v);
+    if (!d) {
+      return null;
+    }
+    if (d.opcode === 'const') {
+      return (d.attrs.value as number) | 0;
+    }
+    // Resolve the two operands of a binary op to constants (2-operand → both; 1-operand → operand +
+    // `imm` attr, which MUST be present, else decline — a missing imm would wrongly fold `and x` to 0).
+    const operands2 = (): [number, number] | null => {
+      const a = evalConst(d.operands[0]);
+      if (a === null) {
+        return null;
+      }
+      let c: number | null;
+      if (d.operands.length === 2) {
+        c = evalConst(d.operands[1]);
+      } else if (typeof d.attrs.imm === 'number') {
+        c = d.attrs.imm | 0;
+      } else {
+        return null;
+      }
+      return c === null ? null : [a, c];
+    };
+    const bin = (f: (a: number, c: number) => number): number | null => {
+      const p = operands2();
+      return p === null ? null : f(p[0], p[1]) | 0;
+    };
+    const shift = (f: (a: number, c: number) => number): number | null => {
+      const p = operands2();
+      if (p === null || p[1] < 0 || p[1] >= 32) {
+        return null;
+      } // out-of-range shift amount → decline
+      return f(p[0], p[1]) | 0;
+    };
+    switch (d.opcode) {
+      case 'shl':
+        return shift((a, c) => a << c);
+      case 'shr_u':
+        return shift((a, c) => a >>> c);
+      case 'shr_s':
+        return shift((a, c) => a >> c);
+      case 'or':
+        return bin((a, c) => a | c);
+      case 'and':
+        return bin((a, c) => a & c);
+      case 'xor':
+        return bin((a, c) => a ^ c);
+      case 'add':
+        return bin((a, c) => a + c);
+      case 'sub':
+        return bin((a, c) => a - c);
+      case 'neg': {
+        const a = evalConst(d.operands[0]);
+        return a === null ? null : -a | 0;
+      }
+      case 'not': {
+        const a = evalConst(d.operands[0]);
+        return a === null ? null : ~a | 0;
+      }
+      default:
+        return null;
+    }
+  };
+
+  // A "pure test block": its only computation is constants + one integer comparison feeding its
+  // cond_br terminator (no store/call/load/opaque — its body is DISCARDED when the tree collapses to a
+  // switch, so a side effect there would be lost). PRE4 (purity). The root block is exempt from the
+  // "only const/icmp" rule because its non-terminator ops are already emitted as sideEffects(b) before
+  // the switch; a non-root test block must be strictly pure.
+  const SIDE_EFFECTFUL = new Set(['store', 'astore', 'call', 'load', 'aload', 'opaque']);
+  interface TestInfo {
+    x: Value;
+    k: number;
+    cls: 'eq' | 'ne' | 'rel';
+    opcode: string;
+    xOnLeft: boolean;
+  }
+  const testInfo = (blk: Block, isRoot: boolean): TestInfo | null => {
+    const term = blk.ops[blk.ops.length - 1];
+    if (term.opcode !== 'cond_br') {
+      return null;
+    }
+    const cmp = defs.get(term.operands[0]);
+    if (!cmp || !isCmpOpcode(cmp.opcode)) {
+      return null;
+    }
+    if (!isRoot && blk.ops.some((op) => SIDE_EFFECTFUL.has(op.opcode))) {
+      return null;
+    } // PRE4
+    // Which operand is the scrutinee, which is the constant?
+    const [lo, ro] = cmp.operands;
+    const lc = evalConst(lo),
+      rc = evalConst(ro);
+    let x: Value, k: number, xOnLeft: boolean;
+    if (lc === null && rc !== null) {
+      x = lo;
+      k = rc;
+      xOnLeft = true;
+    } else if (rc === null && lc !== null) {
+      x = ro;
+      k = lc;
+      xOnLeft = false;
+    } else {
+      return null;
+    } // both/neither const
+    const cls = cmp.opcode === 'icmp_eq' ? 'eq' : cmp.opcode === 'icmp_ne' ? 'ne' : 'rel';
+    return { x, k, cls, opcode: cmp.opcode, xOnLeft };
+  };
+
+  // Evaluate a test predicate for a CONCRETE scrutinee value — used to SIMULATE the decision tree and
+  // verify recovered case values (below). Returns true iff the `taken` (successors[0]) edge is followed.
+  // Signed/unsigned per the icmp opcode (PRE3, done concretely rather than via interval lattices).
+  const evalCmp = (opcode: string, xOnLeft: boolean, xv: number, k: number): boolean => {
+    const uns = opcode.startsWith('icmp_u');
+    const [xn, kn] = uns ? [xv >>> 0, k >>> 0] : [xv | 0, k | 0];
+    const [l, r] = xOnLeft ? [xn, kn] : [kn, xn]; // put the scrutinee where it textually appears
+    switch (opcode) {
+      case 'icmp_eq':
+        return l === r;
+      case 'icmp_ne':
+        return l !== r;
+      case 'icmp_slt':
+      case 'icmp_ult':
+        return l < r;
+      case 'icmp_sle':
+      case 'icmp_ule':
+        return l <= r;
+      case 'icmp_sgt':
+      case 'icmp_ugt':
+        return l > r;
+      case 'icmp_sge':
+      case 'icmp_uge':
+        return l >= r;
+      default:
+        return false;
+    }
+  };
+
+  // Can any case/default entry's region reach a SIBLING entry (switch fall-through)? Region =
+  // blocks strictly dominated by `b`, short of `merge`. Shared by Regime A (declines to
+  // if-recovery) and Regime B (throws — a jump-table has no fallback).
+  const caseRegionReachesSibling = (targets: Set<Block>, b: Block, merge: Block | null): boolean => {
+    const inRegion = (blk: Block) => blk !== merge && dom.get(blk)!.has(b);
+    for (const entry of targets) {
+      const rseen = new Set<Block>([entry]);
+      const q = [entry];
+      while (q.length) {
+        const cur = q.pop()!;
+        for (const s of successorsOf(cur)) {
+          if (s === entry) {
+            continue;
+          }
+          if (targets.has(s)) {
+            return true;
+          }
+          if (inRegion(s) && !rseen.has(s)) {
+            rseen.add(s);
+            q.push(s);
+          }
+        }
+      }
+    }
+    return false;
+  };
+
+  const recognizeSwitch = (b: Block, stop: Block | null): Stmt[] | null => {
+    const root = testInfo(b, true);
+    if (!root) {
+      return null;
+    }
+    const scrut = root.x;
+    // PRE1 (scrutinee identity + dominance): the scrutinee is a single raw SSA Value that must DOMINATE
+    // the whole region. A block param (phi) is rejected — it is not one definition across the region.
+    // Params are seeded into names (isNamed); a value defined by an op has a defining block that must dominate
+    // b. Function params (entry params) dominate everything.
+    const scrutDef = defs.get(scrut);
+    const entryBlk = fn.blocks[0];
+    if (scrutDef) {
+      const defBlk = opBlock.get(scrutDef)!;
+      if (!dom.get(b)!.has(defBlk)) {
+        return null;
+      }
+    } else if (!entryBlk.params.includes(scrut)) {
+      return null; // a non-entry block param → decline
+    }
+
+    // Walk the test tree. `cases`: value → case-entry block. `defaultCands`: leaves reached without an
+    // equality pin. A test-block DAG cycle, or a `!=` case when the compiler disallows it, declines.
+    const cases = new Map<number, Block>();
+    const defaultCands = new Set<Block>();
+    // Skip pure forwarding blocks — a block whose only op is an unconditional `br` (no side effects, no
+    // params). agbcc's binary-search layout branches to the shared default through such empty `b .Ldef`
+    // blocks; without skipping them each becomes a DISTINCT default candidate and the whole tree declines.
+    const skipForward = (blk: Block): Block => {
+      let cur = blk;
+      const guard = new Set<Block>();
+      // Only skip a truly empty forwarding block: a lone `br` with no params AND no successor ARGS —
+      // an edge that carries a phi arg is NOT transparent (skipping it would drop that assignment).
+      while (
+        cur.ops.length === 1 &&
+        cur.ops[0].opcode === 'br' &&
+        cur.params.length === 0 &&
+        cur.ops[0].successors[0].args.length === 0 &&
+        !guard.has(cur)
+      ) {
+        guard.add(cur);
+        cur = cur.ops[0].successors[0].block;
+      }
+      return cur;
+    };
+    // Concretely SIMULATE the decision tree for a scrutinee value `xv`, returning the leaf block it
+    // reaches (or null on an unexpected cycle). This is PRE3 done concretely: it lets us verify each
+    // recovered case value actually routes to its recorded body in the ORIGINAL tree.
+    const simulateTree = (xv: number): Block | null => {
+      let cur = b;
+      const guard = new Set<Block>();
+      for (;;) {
+        const ti = testInfo(cur, cur === b);
+        if (!ti || ti.x !== scrut) {
+          return cur;
+        } // reached a leaf (case body / default)
+        if (guard.has(cur)) {
+          return null;
+        }
+        guard.add(cur);
+        const term = cur.ops[cur.ops.length - 1];
+        const taken = evalCmp(ti.opcode, ti.xOnLeft, xv, ti.k);
+        cur = skipForward(term.successors[taken ? 0 : 1].block);
+      }
+    };
+    const seen = new Set<Block>();
+    const work: Block[] = [b];
+    while (work.length) {
+      const blk = work.pop()!;
+      if (seen.has(blk)) {
+        return null;
+      } // a test-block DAG cycle → decline
+      seen.add(blk);
+      const ti = testInfo(blk, blk === b);
+      if (!ti || ti.x !== scrut) {
+        return null;
+      } // PRE1: every test is on the SAME Value
+      const term = blk.ops[blk.ops.length - 1];
+      const taken = skipForward(term.successors[0].block),
+        fall = skipForward(term.successors[1].block);
+      const asLeafOrTest = (child: Block, role: 'case' | 'nav', k?: number) => {
+        const isTest = !!testInfo(child, false) && testInfo(child, false)!.x === scrut;
+        if (role === 'case') {
+          if (isTest) {
+            return false;
+          } // a case target that's a test → decline
+          if (child.params.length) {
+            return false;
+          } // case entry with a phi → decline
+          if (cases.has(k!)) {
+            return false;
+          } // duplicate case value → decline
+          cases.set(k!, child);
+          return true;
+        }
+        // navigation edge
+        if (isTest) {
+          work.push(child);
+          return true;
+        }
+        defaultCands.add(child); // a non-test leaf reached by nav = default
+        return true;
+      };
+      if (ti.cls === 'eq') {
+        if (!asLeafOrTest(taken, 'case', ti.k)) {
+          return null;
+        } // x==k → taken is case k
+        if (!asLeafOrTest(fall, 'nav')) {
+          return null;
+        }
+      } else if (ti.cls === 'ne') {
+        if (!switchAllowsNeqCase) {
+          return null;
+        } // per-compiler gate
+        if (!asLeafOrTest(fall, 'case', ti.k)) {
+          return null;
+        } // x!=k → the EQUAL side (fall) is case k
+        if (!asLeafOrTest(taken, 'nav')) {
+          return null;
+        }
+      } else {
+        // relational → pure navigation
+        if (!asLeafOrTest(taken, 'nav')) {
+          return null;
+        }
+        if (!asLeafOrTest(fall, 'nav')) {
+          return null;
+        }
+      }
+    }
+
+    if (cases.size < 2) {
+      return null;
+    } // not worth a switch (m2c: ≥2 cases)
+    // The default is the single non-test leaf that is NOT a case body. 0 → no default; ≥2 distinct → decline.
+    const caseBlocks = new Set(cases.values());
+    const defaults = [...defaultCands].filter((d) => !caseBlocks.has(d));
+    if (defaults.length > 1) {
+      return null;
+    }
+    const defaultBlk = defaults[0] ?? null;
+    if (defaultBlk && defaultBlk.params.length) {
+      return null;
+    } // default entry with a phi → decline
+    // A default candidate that is ALSO a case body means a relational edge hit a case leaf → ambiguous.
+    if ([...defaultCands].some((d) => caseBlocks.has(d))) {
+      return null;
+    }
+
+    // PRE1 dominance of the whole region: b must dominate every case body + the default (single-entry).
+    for (const cb of caseBlocks) {
+      if (!dom.get(cb)!.has(b)) {
+        return null;
+      }
+    }
+    if (defaultBlk && !dom.get(defaultBlk)!.has(b)) {
+      return null;
+    }
+
+    // PRE2 (fall-through): only NON-fall-through switches are handled — decline if any case body
+    // can reach ANOTHER case body (or the default) while staying inside the region. (The SAME
+    // predicate serves the Regime-B path, which throws instead.)
+    const merge = ipdom.get(b) ?? stop;
+    const targets = new Set<Block>([...caseBlocks, ...(defaultBlk ? [defaultBlk] : [])]);
+    if (caseRegionReachesSibling(targets, b, merge)) {
+      return null;
+    }
+
+    // PRE3 (concrete interval consistency): a `case k` is only sound if the ORIGINAL tree
+    // actually routes x==k to its recorded body. A relational guard can make an `x==k` test DEAD (e.g.
+    // `if(x<5){ if(x==20) … }` — x==20 is unreachable under x<5); a naive switch would resurrect `case 20`
+    // and misroute x==20. Simulating the tree per case value catches exactly this — decline on any mismatch.
+    for (const [k, blk] of cases) {
+      if (simulateTree(k) !== blk) {
+        return null;
+      }
+    }
+
+    // Build the switch. Cases sorted ascending (safe: no fall-through — PRE2). Bodies delegate to the
+    // existing structureRegion (loops/ifs inside cases, the onStack guard — all reused).
+    const scrutExpr = expr(scrut);
+    const sortedCases = [...cases.entries()].sort((a, c) => a[0] - c[0]);
+    const outCases: SwitchCase[] = sortedCases.map(([k, blk]) => ({
+      values: [k],
+      body: structureRegion(blk, merge),
+      fallsThrough: false,
+    }));
+    const sw: Stmt = {
+      k: 'switch',
+      scrutinee: scrutExpr,
+      cases: outCases,
+      ...(defaultBlk ? { default: structureRegion(defaultBlk, merge) } : {}),
+    };
+    const out: Stmt[] = [sw];
+    if (merge && merge !== stop) {
+      out.push(...structureRegion(merge, stop));
+    }
+    return out;
+  };
+  return { recognizeSwitch, caseRegionReachesSibling };
+}

package/src/target.ts

@@ -0,0 +1,140 @@
+// asmlift — the Target: (isa, compiler) as first-class axes. ABI + capabilities are DATA
+// consumed generically by shared passes — never a target-name branch inside a shared pass
+// (m2c's `arch.arch ==` leakage).
+//
+// What each datum drives:
+//   • id               → frontend dispatch (registry.ts)
+//   • compiler         → idiom gating (patternApplies) + the report
+//   • argRegs / returnReg → entry-param ordering and return-value read in the frontends
+//   • capabilities.hwDivide → gates the MIPS hardware-divide decode (mips.ts), the soft-division
+//     pre-recovery pass, and idiom gating; a `div` on a target declaring no divider degrades to
+//     a loud opaque (exercised by packages/cli/test/matching/divmul.test.ts). `hwFloat` → idiom
+//     gating only (no float pass yet).
+//   • capabilities.endianness / flags → RESERVED hardware facts, not yet read by any pass
+//     (byte-addressing will consume endianness; PPC condition regs → flags).
+//   • compilerBehaviors.* → all consumed by the structurer (threaded via StructureOptions).
+//
+// `capabilities` (HARDWARE facts) vs `compilerBehaviors` (COMPILER canonicalization choices) are
+// deliberately separate bags: a new compiler must set its behaviors EXPLICITLY instead of
+// silently inheriting a universal that is really per-compiler. `coalesceLoopInit` already
+// differs across targets (IDO true, agbcc/GCC false).
+// This module is browser-pure by contract (no Node APIs, enforced by
+// test/browser-safe.test.ts): the toolchain paths that COMPILE for these targets
+// live in @asmlift/toolchains.
+import type { StructureOptions } from './structure/structure';
+
+export interface TargetDescription {
+  id: string; // the ISA — 'armv4t' / 'mips' / 'ppc'. Selects the frontend (registry.ts).
+  // The COMPILER is a first-class axis distinct from the ISA (matching = deoptimize to a specific
+  // compiler): two targets can share an ISA (⇒ one frontend) yet differ here — e.g. MIPS_IDO vs
+  // MIPS_GCC. Consumed by pattern gating (patternApplies) and the report. (version/flags/language
+  // are future axes, added when earned.)
+  compiler: string; // 'agbcc' / 'ido' / 'gcc' / 'mwcc'
+  argRegs: string[];
+  returnReg: string;
+  // HARDWARE / ISA facts — independent of the compiler.
+  capabilities: {
+    endianness: 'little' | 'big'; // RESERVED — no pass reads it yet (byte-addressing will)
+    hwDivide: boolean; // consumed by patternApplies (idiom gating)
+    hwFloat: boolean; // consumed by patternApplies (idiom gating)
+    flags: boolean; // RESERVED — no pass reads it yet (PPC condition regs will)
+  };
+  // COMPILER BEHAVIORS — the specific compiler's canonicalization choices, distinct from
+  // hardware `capabilities`. All consumed by the structurer (threaded through StructureOptions).
+  compilerBehaviors: {
+    // When a loop induction variable's initial value comes from an argument register, some
+    // compilers keep mutating that register across the loop (coalesce → no init copy); others
+    // copy to a fresh local. IDO -O2 reuses the arg register (true); agbcc/KMC-GCC allocate
+    // fresh (false).
+    coalesceLoopInit?: boolean;
+    // Divergent-if (both arms terminate, no join): reproduce the source branch DIRECTION by
+    // emitting the forward-branch-on-negated-condition (taken arm as `else`). IDO/MIPS preserves
+    // source direction so this must be on to be byte-exact; agbcc/GCC canonicalize either way so
+    // true is a safe default there. A compiler that inverts branch canonicalization sets it
+    // false. Absent ⇒ true; a compiler opts OUT.
+    preserveDivergentBranchSense?: boolean;
+    // Order the parallel-copy assignments at a CFG edge by the order their values are COMPUTED
+    // in the predecessor (vs. source/param order), matching a compiler that lays defining ops
+    // (and the copies reading them) out in computation order. Uniform (true) across all current
+    // compilers. Absent ⇒ true; a compiler opts OUT.
+    orderArgCopiesByComputation?: boolean;
+    // Regime-A switch recovery: accept an `x != K` test as a case (the EQUAL side is the case
+    // body). GCC freely emits `!=`; IDO prefers `==`/`<`. Absent ⇒ true (permissive); the
+    // decline path keeps recovery sound either way.
+    switchAllowsNeqCase?: boolean;
+  };
+}
+
+export const ARMV4T_AGBCC: TargetDescription = {
+  id: 'armv4t',
+  compiler: 'agbcc',
+  argRegs: ['r0', 'r1', 'r2', 'r3'],
+  returnReg: 'r0',
+  capabilities: { endianness: 'little', hwDivide: false, hwFloat: false, flags: true },
+  compilerBehaviors: { coalesceLoopInit: false, preserveDivergentBranchSense: true, orderArgCopiesByComputation: true },
+};
+
+/** MIPS-II / IDO 7.1 target. IDO is the IRIX C compiler,
+ *  statically recompiled to run natively (ido-static-recomp). Unlike agbcc
+ *  it emits no textual asm, so asmlift's input is the DISASSEMBLED object (`mips-linux-gnu-
+ *  objdump -d`); the arch-agnostic objdiff scorer scores the MIPS object directly. Big-endian,
+ *  hardware divide + FPU (N64). */
+export const MIPS_IDO: TargetDescription = {
+  id: 'mips',
+  compiler: 'ido',
+  argRegs: ['a0', 'a1', 'a2', 'a3'],
+  returnReg: 'v0',
+  capabilities: { endianness: 'big', hwDivide: true, hwFloat: true, flags: false },
+  // `switchAllowsNeqCase: false` — IDO's switch dispatch uses `==`/`<`, never `!=` cases;
+  // leaving it permissive mis-recognises `!=`-rooted if-else chains as switches.
+  compilerBehaviors: {
+    coalesceLoopInit: true,
+    preserveDivergentBranchSense: true,
+    orderArgCopiesByComputation: true,
+    switchAllowsNeqCase: false,
+  },
+};
+
+/** MIPS + KMC GCC — the SAME ISA as MIPS_IDO, a DIFFERENT compiler: `id:"mips"` reuses the
+ *  `mips` frontend verbatim, only `compiler` varies. Same N64 hardware ⇒ identical hardware
+ *  capabilities to IDO. */
+export const MIPS_GCC: TargetDescription = {
+  id: 'mips',
+  compiler: 'gcc',
+  argRegs: ['a0', 'a1', 'a2', 'a3'],
+  returnReg: 'v0',
+  // KMC GCC allocates a fresh local for the loop init (coalesceLoopInit false — where it differs
+  // from IDO); the structuring levers take the universal default until a KMC fixture says otherwise.
+  capabilities: { endianness: 'big', hwDivide: true, hwFloat: true, flags: false },
+  compilerBehaviors: { coalesceLoopInit: false, preserveDivergentBranchSense: true, orderArgCopiesByComputation: true },
+};
+
+/** PowerPC (GameCube/Wii) + Metrowerks CodeWarrior. The real GC/Wii matching target is
+ *  CodeWarrior `mwcceppc` (not GCC): active decomp projects and decomp.me standardize on it.
+ *  `-proc gekko` = the GC Gekko CPU. Big-endian, hardware divide + FPU. `flags: true`: PPC has
+ *  condition registers (cr0–cr7), but compare→branch still fuses into a single `cond_br`
+ *  (test/ppc-seam.test.ts), so `flags` stays a documented hardware fact, not yet an IR concern —
+ *  real flags-as-data is deferred until a fixture reuses/combines a cr field. */
+export const PPC_MWCC: TargetDescription = {
+  id: 'ppc',
+  compiler: 'mwcc',
+  // PPC EABI: r3–r10 pass integer/pointer arguments; r3 also returns.
+  argRegs: ['r3', 'r4', 'r5', 'r6', 'r7', 'r8', 'r9', 'r10'],
+  returnReg: 'r3',
+  capabilities: { endianness: 'big', hwDivide: true, hwFloat: true, flags: true },
+  // CodeWarrior's structuring levers are UNKNOWN until fixtures reveal them — safe universal
+  // defaults; coalesceLoopInit false until a CW loop fixture says otherwise.
+  compilerBehaviors: { coalesceLoopInit: false, preserveDivergentBranchSense: true, orderArgCopiesByComputation: true },
+};
+
+/** Build the structurer's options for a target: the function's own `returnsVoid` plus every
+ *  `compilerBehaviors` lever (they map 1:1 onto StructureOptions field names). The ONE place a
+ *  target's compiler behaviors flow into the target-agnostic structurer — a new behavior lever
+ *  is a field in `compilerBehaviors`, consumed automatically. */
+export function structureOptionsFor(t: TargetDescription, returnsVoid: boolean): StructureOptions {
+  return { returnsVoid, ...t.compilerBehaviors };
+}
+
+export const C_TYPEDEFS =
+  'typedef unsigned char u8;typedef unsigned short u16;typedef unsigned int u32;' +
+  'typedef signed char s8;typedef short s16;typedef int s32;\n';