@asmlift/core 0.2.0 → 0.4.0

package/src/structure/structure.ts

@@ -37,11 +37,23 @@
 // whose exit copies would clobber, switch fall-through, and mixed-entry self-loops (a guarded
 // header also entered by a plain br).
 import { Block, Fn, Op, Value, defOpMap, successorsOf } from '../ir/core';
-import { type IrType, T } from '../ir/types';
-import { BinOp, Expr, SFn, Stmt, SwitchCase, exprChildren, mapExprChildren } from '../l3/ast';
+import { type IrType, T, scalarTypeForAccess, typeEquals } from '../ir/types';
+import { BinOp, Expr, SFn, Stmt, SwitchCase, exprChildren, mapExprChildren, negateCond } from '../l3/ast';
 import { exprCType, ptrElemBytes } from '../l3/typing';
 import { returnType } from '../raise/recover';
 import { collectStructs } from '../raise/structs';
+import {
+  type DeclaredField,
+  type SymbolInfo,
+  type SymbolStructField,
+  arrayInnerExtents,
+  declaredFields,
+  isArrayField,
+  isBitfieldField,
+  isScalarCellSize,
+  pointeeFields,
+  scalarCellType,
+} from '../symbols';
 import { analyze } from './analysis';
 import { makeLoopHazards, updateWriteSet } from './hazards';
 import { analyzeLoops, dominators } from './loops';
@@ -59,44 +71,295 @@ import { makeSwitchRecovery } from './switch-recover';
 // TODAY — carrying the struct name (resolved against SFn.structs) is the same move as width and
 // the named follow-up; until then no backend pays a tax for the tree cast (Pascal loud-fails
 // `field` regardless, C++ falls through its leaf hook to the shared C spelling).
+// `&gSym`, possibly wearing the value-context integer cast the additive lowering adds
+// (`(u32)&gSym` — see lowerDef's addr-intify): both spell the same link-time constant, so the
+// fold rules match through the cast and every access that CAN spell a named element still does.
+// WIDTH 32 ONLY — a NARROWING cast (`(u8)&gSym`, from a zext/sext lowering) is a different
+// VALUE (`addr & 0xFF`), and folding through it would read the named global at a wrong address
+// (the adversarial round's probe: `*(u8*)(u8)&gSym` must keep its truncation, never become
+// `*(u8*)&gSym` — let alone a confidently-named `gSym.field`).
+function addrIn(e: Expr): Extract<Expr, { k: 'addr' }> | null {
+  if (e.k === 'addr') {
+    return e;
+  }
+  if (e.k === 'cast' && e.to.kind === 'int' && e.to.width === 32 && e.e.k === 'addr') {
+    return e.e;
+  }
+  return null;
+}
+
 // If `e` is a global address `&gSym` (optionally `+ index`), return the global name and the
 // element index (byte residual divided by the access width). `&gSym` alone → idx const 0;
 // `&gSym + i` → idx `i / width` (exact division only — a non-multiple residual is a mid-element
 // access this whole-global spelling can't express, so it declines to null and the caller casts).
 function globalOf(e: Expr, width: number): { name: string; idx: Expr } | null {
-  if (e.k === 'addr') {
-    return { name: e.name, idx: { k: 'const', value: 0 } };
+  const top = addrIn(e);
+  if (top) {
+    return { name: top.name, idx: { k: 'const', value: 0 } };
   }
   if (e.k === 'bin' && e.op === '+') {
-    for (const [addrSide, other] of [
+    for (const [side, other] of [
       [e.l, e.r],
       [e.r, e.l],
     ] as const) {
-      if (addrSide.k === 'addr') {
-        // width 1 → the byte residual IS the index; width>1 → a constant residual divides, a
-        // non-constant residual must already be element-scaled (`i * width`) to divide exactly.
-        if (width === 1) {
-          return { name: addrSide.name, idx: other };
-        }
-        if (other.k === 'const') {
-          return other.value % width === 0
-            ? { name: addrSide.name, idx: { k: 'const', value: other.value / width } }
-            : null;
-        }
-        if (other.k === 'bin' && (other.op === '*' || other.op === '<<')) {
-          const factor =
-            other.op === '<<'
-              ? other.r.k === 'const'
-                ? 1 << other.r.value
-                : 0
-              : other.r.k === 'const'
-                ? other.r.value
-                : 0;
-          if (factor === width) {
-            return { name: addrSide.name, idx: other.l };
-          }
-        }
-        return null; // a non-element-aligned residual — decline the global-array spelling
+      const addrSide = addrIn(side);
+      if (addrSide) {
+        const idx = elementIndex(other, width);
+        return idx ? { name: addrSide.name, idx } : null;
+      }
+    }
+  }
+  return null;
+}
+
+// THE one gate on the BARE-NAME array-global spelling (`gSym[i]` rather than `((T *)&gSym)[i]`),
+// shared by the constant-offset and variable-index access paths so the two cannot disagree.
+// Returns the `index` node's `lead` fragment when the bare form is spellable, or null to fall
+// through to the always-valid `&gSym` cast form.
+//
+// Two facts are required, not one. The element WIDTH must match, as it always has. And the RANK
+// must be SPELLABLE, because one subscript reaches an element only on a rank-1 array: on `u16
+// g[4][0x400]`, `g[i]` is a ROW. Against the project's own header that is usually a type error,
+// but where the row address flows into an integer context it is merely a warning and the emitted C
+// then addresses a different object than the asm did — silently.
+//
+// A rank > 1 pins the leading dimensions at 0 and puts the whole flat element index in the last
+// subscript (`g[0][i]`) — the same address arithmetic, and the idiom decomp sources themselves use
+// when the split is not observable in the asm either (`gBgTilemapBufs[0][…]` in kleod,
+// `gNatureStatTable[nature][…]` in pokeemerald). A rank the map states but cannot spell (an unknown
+// inner extent) gets no bare form at all; `((T *)&gSym)[i]` is byte-identical and valid under ANY
+// declaration, which is why it is the safe fallback. See symbols.ts arrayInnerExtents for why an
+// ABSENT rank is read as 1 rather than as unknown.
+function bareArrayLead(si: SymbolInfo, width: number): { lead?: number[] } | null {
+  if (si.shape !== 'array' || si.elemSize !== width) {
+    return null;
+  }
+  const inner = arrayInnerExtents(si);
+  return inner === null ? null : inner.length === 0 ? {} : { lead: new Array<number>(inner.length).fill(0) };
+}
+
+// A BYTE residual read as an ELEMENT index of `elemSize`-wide elements, or null when it is not one
+// — the residual then addresses mid-element and no whole-element spelling can express it, so the
+// caller falls through to the honest cast forms. THE one copy of the rule, indexing the
+// `&gSym`-based array spelling: width 1 → the byte residual IS the index; wider → a constant
+// residual must divide exactly, and a non-constant one must already be element-scaled
+// (`i * elemSize` / `i << log2(elemSize)`), which is exactly what the asm's own index scaling
+// produced.
+function elementIndex(residual: Expr, elemSize: number): Expr | null {
+  if (elemSize === 1) {
+    return residual;
+  }
+  if (residual.k === 'const') {
+    return residual.value % elemSize === 0 ? { k: 'const', value: residual.value / elemSize } : null;
+  }
+  if (residual.k === 'bin' && (residual.op === '*' || residual.op === '<<')) {
+    const factor =
+      residual.op === '<<'
+        ? residual.r.k === 'const'
+          ? 1 << residual.r.value
+          : 0
+        : residual.r.k === 'const'
+          ? residual.r.value
+          : 0;
+    if (factor === elemSize) {
+      return residual.l;
+    }
+  }
+  return null;
+}
+
+/** The symbol-map rendering context threaded into memAccess/arrayAccess: shape facts per
+ *  global name, plus a callback registering a global's env type (so the bare `gSym[i]` spelling,
+ *  which must pass the stride check uncast, does). Absent ⇒ today's spellings. */
+interface SymRenderCtx {
+  info(name: string): SymbolInfo | undefined;
+  noteGlobal(name: string, type: IrType): void;
+}
+
+// ── interior spelling through a POINTER-shaped global ────────────────────────────────────────
+// A pointer global's VALUE is the address of the object the project's header says it points at.
+// With that pointee's layout in the map, an access at a known offset is a NAMED member of it —
+// `gPtr->member` — which is the source spelling; without it the access is byte arithmetic on the
+// loaded cell (`((u8 *)gPtr + i)[16]`), honest but opaque. The address computed is IDENTICAL
+// either way: `->member` adds the member's DWARF offset, which is the same constant the arithmetic
+// added, and an index into an array member scales by the member's own element size, which the
+// rules below require to equal the access width. Everything not provably that — a partial overlap,
+// a width mismatch, an unnamed offset, a member whose declared signedness differs from the
+// access's (an s8 read is ldrb+lsl+asr where u8 is ldrb alone), a missing layout — falls THROUGH
+// to the cast forms. A member is never guessed.
+
+/** The global named by a pointer global's VALUE as the additive lowering spells it: the bare
+ *  `gPtr`, or that value wearing the byte-pointer / u32 cast that lowering adds (cast-then-add,
+ *  see the `needsIntSpelling` / pointer-global arithmetic rules below). Both denote the same
+ *  address and add BYTES to it, so both fold here; a cast to any other pointer type is NOT looked
+ *  through — a `(u16 *)` base would re-scale everything added after it. */
+function ptrGlobalValueName(x: Expr): string | null {
+  if (x.k === 'var') {
+    return x.name;
+  }
+  if (x.k === 'cast' && x.e.k === 'var') {
+    const t = x.to;
+    const bytePtr = t.kind === 'ptr' && t.to.kind === 'int' && t.to.width === 8;
+    return bytePtr || (t.kind === 'int' && t.width === 32) ? x.e.name : null;
+  }
+  return null;
+}
+
+/** A pointer global's value, the constant bytes added to it, and the at-most-one variable term. */
+interface PtrGlobalBase {
+  name: string;
+  byte: number;
+  idx: Expr | null;
+}
+
+/** Decompose an access base into "the VALUE of a map-declared POINTER global + a constant byte
+ *  offset + at most ONE variable term": `gPtr`, `gPtr + K`, `(u8 *)gPtr + i`, `(u8 *)gPtr + (i <<
+ *  2) + K`. Null for anything else — two variable terms, no such global, a non-`+` operator —
+ *  because only a single residual can be read as one member's index. */
+function ptrGlobalBase(e: Expr, isPtrGlobal: (n: string) => boolean): PtrGlobalBase | null {
+  let name: string | null = null;
+  let byte = 0;
+  let idx: Expr | null = null;
+  let ok = true;
+  const visit = (x: Expr): void => {
+    if (!ok) {
+      return;
+    }
+    if (x.k === 'bin' && x.op === '+') {
+      visit(x.l);
+      visit(x.r);
+      return;
+    }
+    const global = ptrGlobalValueName(x);
+    if (global !== null && name === null && isPtrGlobal(global)) {
+      name = global;
+      return;
+    }
+    if (x.k === 'const') {
+      byte += x.value;
+      return;
+    }
+    if (idx !== null) {
+      ok = false;
+      return;
+    }
+    idx = x;
+  };
+  visit(e);
+  return ok && name !== null ? { name, byte, idx } : null;
+}
+
+/** Does a member declared at signedness `declared` read as EXACTLY the type the cast spelling this
+ *  replaces would have produced — `scalarTypeForAccess(width, signed)`? That is the whole
+ *  byte-exactness argument for naming a member instead of casting: same address, same read width,
+ *  same C type, so every operator downstream compiles identically. A 4-byte access renders s32
+ *  whatever the load said (the ISA has one word load), so only a SIGNED member may take its place;
+ *  narrower accesses carry their own signedness and must match it. An undeclared signedness (the
+ *  member is not a base type — a nested struct, an enum, a pointer) is never assumed to match.
+ *  Compared against THE one copy of that rule (ir/types.ts) rather than restating it. */
+function spellsAccessType(declared: boolean | undefined, width: number, signed: boolean): boolean {
+  if (declared === undefined) {
+    return false;
+  }
+  return typeEquals(T.int(width * 8, declared), scalarTypeForAccess(width, signed));
+}
+
+/** May a member be NAMED by an access of this direction, given the qualifiers on its declaration?
+ *  The named spelling REPLACES a cast through `(u8 *)`, which carries no qualifier at all, so a
+ *  qualifier the name reintroduces changes what the compiler emits:
+ *    • `volatile` makes the access observable — the load may no longer be folded or reordered,
+ *      which is a different instruction sequence (measured: 6 insns where the cast form was 5);
+ *    • `const` under a STORE is a hard error, where the cast form merely cast the qualifier away.
+ *  Either way the honest spelling is the cast form, so the member simply is not nameable here. */
+function memberQualsAllow(f: SymbolStructField, containerConst: boolean | undefined, isStore: boolean): boolean {
+  if (f.volatile) {
+    return false;
+  }
+  return !(isStore && (f.const || containerConst));
+}
+
+// WHY THERE IS NO INDEXED `gPtr->arr[i]` SPELLING.
+//
+// Naming a member is only allowed where it is byte-identical to the cast form it replaces, and
+// for the INDEXED form that was measured to be false. Against agbcc, `gPtr->arr[i]` and
+// `((u8 *)gPtr + i)[K]` differ at EVERY nonzero K and for every width and direction — agbcc does
+// not reassociate `(base + K) + i` into `(base + i) + K`, so it materialises the offset instead of
+// folding it into the load (`adds r1, #16`; +2 code bytes at width 1, +4 at widths 2 and 4). At
+// K = 0 the two still differ for widths 2 and 4, where the commutative `adds` picks a different
+// destination register. The single agbcc case that did measure identical — width 1 at K = 0 —
+// survives only a BARE index in a function with ONE such access: `i & 255`, `i + 1`, `i >> 2` and
+// a second access that lets the cast side CSE its base all break it. A spelling rule decides one
+// expression at a time and cannot see the neighbouring access that changes the answer, so there is
+// no local gate that makes this form safe. (Both MIPS targets accept it freely, but core is
+// target-agnostic — it cannot condition on the compiler it is emitting for.)
+//
+// The CONSTANT-offset form below is the opposite case, and is emitted unconditionally: measured
+// identical on all three targets for widths 1/2/4, loads and stores, at every offset tested up to
+// 4096 — including offsets past Thumb's immediate range, and under multi-member, across-a-call
+// and in-a-loop shapes. It is one load whose member offset becomes the same immediate the cast
+// form used, and unlike the indexed form it composes.
+
+/** The pointee a global's value may be spelled through: the members the declaration synthesis
+ *  DECLARES. Null when nothing may be named through it — THE shared gate (symbols.ts
+ *  pointeeFields), so core never names a member that synthesis would not declare, and never sees a
+ *  member synthesis drops (a union alias behind the first view at that offset). A VOLATILE pointee
+ *  declines outright: every named access through it would be a volatile access where the cast form
+ *  it replaces was plain. */
+function spellablePointee(
+  name: string,
+  sym: SymRenderCtx,
+): { fields: DeclaredField[]; const: boolean | undefined } | null {
+  const pointee = sym.info(name)?.pointee;
+  const fields = pointeeFields(pointee);
+  if (fields === null || pointee!.volatile) {
+    return null;
+  }
+  return { fields, const: pointee!.const };
+}
+
+/** `gPtr->member` for an access through a pointer global's value, or null when the offset is not
+ *  provably ONE member's (see the block comment above). A VARIABLE index declines whatever it
+ *  lands on — the indexed form is not byte-neutral and has no spelling here. */
+function pointeeAccess(
+  pg: PtrGlobalBase,
+  off: number,
+  width: number,
+  signed: boolean,
+  isStore: boolean,
+  sym: SymRenderCtx,
+): Expr | null {
+  if (pg.idx !== null) {
+    return null;
+  }
+  const total = pg.byte + off;
+  // Constant offset: the member must match EXACTLY — offset, read width, and the SPELLED type
+  // (spellsAccessType). An ARRAY member is excluded whatever its size: `u8 x[1]` would match a
+  // byte access by (offset, size) and spell `->x`, which is not an lvalue of that width at all.
+  // A BITFIELD member likewise: its `size` is the byte span its bits touch, so a 7-bit field
+  // would match a plain u16 read and spell a 7-bit lvalue for a 16-bit access.
+  const p = spellablePointee(pg.name, sym);
+  const f = p?.fields.find((m) => m.offset === total && m.size === width && !isArrayField(m) && !isBitfieldField(m));
+  return p && f && spellsAccessType(f.signed, width, signed) && memberQualsAllow(f, p.const, isStore)
+    ? { k: 'field', base: { k: 'var', name: pg.name }, name: f.name }
+    : null;
+}
+
+// The (name, byte offset) of a global access with a CONSTANT total offset — `&gSym` → off,
+// `&gSym + K` → K + off. The exact byte is what a struct-layout field lookup needs; a variable
+// residual returns null (no field spelling — falls through to the index/cast forms).
+function globalConstByte(baseExpr: Expr, off: number): { name: string; byte: number } | null {
+  const top = addrIn(baseExpr);
+  if (top) {
+    return { name: top.name, byte: off };
+  }
+  if (baseExpr.k === 'bin' && baseExpr.op === '+') {
+    for (const [a, b] of [
+      [baseExpr.l, baseExpr.r],
+      [baseExpr.r, baseExpr.l],
+    ] as const) {
+      const a2 = addrIn(a);
+      if (a2 && b.k === 'const') {
+        return { name: a2.name, byte: b.value + off };
       }
     }
   }
@@ -111,6 +374,8 @@ function memAccess(
   signed: boolean,
   ctype: (e: Expr) => IrType | undefined,
   scalarGlobals: Set<string>,
+  sym?: SymRenderCtx,
+  isStore = false,
 ): Expr {
   // A deref of a global's address collapses to the bare global: `*(&gSym)` at off 0 is `gSym`;
   // at off N the global is an array — `gSym[N/width]` (a C global name decays to a pointer, so
@@ -118,6 +383,39 @@ function memAccess(
   // `*(&gSym + i)` → `gSym[i + off/width]` (byte offset `i` peeled from the tree; for a u8 global
   // the residual IS the index). This is what makes an agbcc `.word gSym` pool access a named
   // global read/element rather than a phantom-pointer deref.
+  // Declaration-shape spellings (symbol map): a STRUCT global's constant-offset access is the
+  // named field (`gSym.field` — the source spelling a folded literal can never match); an ARRAY
+  // global indexes its BARE name (`gSym[i]`, see below). Exact field match only (offset AND
+  // width) — anything else falls through to the honest cast forms, never a guessed field.
+  if (sym) {
+    const gb = globalConstByte(baseExpr, off);
+    const si = gb ? sym.info(gb.name) : undefined;
+    if (gb && si?.shape === 'struct') {
+      // THE shared spellability predicate (symbols.ts), the same call declare.ts gates its struct
+      // declaration on: a layout it declines whole is a layout with no nameable members, and a
+      // union alias it drops for the first view at that offset is a name no declaration carries.
+      // An ARRAY member is excluded for the same reason as in pointeeAccess: `u8 x[1]` would match
+      // a byte access by (offset, size) and spell `.x`, which is not an lvalue of that width. A
+      // BITFIELD member likewise — a plain read of its bytes is not a read of its bits (the named
+      // bitfield spelling has its own recognizer, on the extract shape: see lowerDef).
+      const fld = declaredFields(si.layout)?.find(
+        (f) => f.offset === gb.byte && f.size === width && !isArrayField(f) && !isBitfieldField(f),
+      );
+      if (fld && memberQualsAllow(fld, si.const, isStore)) {
+        return { k: 'field', base: { k: 'var', name: gb.name }, name: fld.name, dot: true };
+      }
+    }
+    // …and the same idea one indirection down: an access at a CONSTANT offset through a POINTER
+    // global's VALUE is a named member of what it points at (`gPtr->member`) when the map knows
+    // the pointee's layout — see pointeeAccess for the guards.
+    const pg = ptrGlobalBase(baseExpr, (n) => sym.info(n)?.shape === 'pointer');
+    if (pg) {
+      const spelled = pointeeAccess(pg, off, width, signed, isStore, sym);
+      if (spelled) {
+        return spelled;
+      }
+    }
+  }
   const g = globalOf(baseExpr, width);
   if (g) {
     const idxVal = g.idx;
@@ -136,6 +434,15 @@ function memAccess(
         : idxVal.k === 'const'
           ? { k: 'const', value: idxVal.value + off / width }
           : { k: 'bin', op: '+', l: idxVal, r: { k: 'const', value: off / width } };
+    // ARRAY-declared global (symbol map): index the bare name — `gSym[i]`, the spelling the
+    // dogfood proved agbcc needs for ROM tables — with the element type registered in the env
+    // so the stride check passes and no cast is added. Element-width match only.
+    const siArr = sym?.info(g.name);
+    const lead = siArr === undefined ? null : bareArrayLead(siArr, width);
+    if (lead !== null) {
+      sym!.noteGlobal(g.name, T.ptr(T.int(width * 8, siArr!.elemSigned ?? false)));
+      return { k: 'index', base: { k: 'var', name: g.name }, idx, width, signed, ...lead };
+    }
     return { k: 'index', base: { k: 'addr', name: g.name }, idx, width, signed };
   }
   const bt = base.type;
@@ -169,11 +476,19 @@ function arrayAccess(
   elemSize: number,
   signed: boolean,
   ctype: (e: Expr) => IrType | undefined,
+  sym?: SymRenderCtx,
 ): Expr {
   // A variable-index access off a global's address indexes the ADDRESS `&gSym` (the cast form
   // `((T *)&gSym)[i]` — valid for a struct global too, unlike casting the bare value). A
   // struct-array-of-globals (fieldOff) through `&gSym` is out of scope — fall through.
   if (baseExpr.k === 'addr' && fieldOff === undefined) {
+    // ARRAY-declared global (symbol map): the bare-name spelling, same rule as memAccess.
+    const si = sym?.info(baseExpr.name);
+    const lead = si === undefined ? null : bareArrayLead(si, elemSize);
+    if (lead !== null) {
+      sym!.noteGlobal(baseExpr.name, T.ptr(T.int(elemSize * 8, si!.elemSigned ?? false)));
+      return { k: 'index', base: { k: 'var', name: baseExpr.name }, idx: idxExpr, width: elemSize, signed, ...lead };
+    }
     return { k: 'index', base: baseExpr, idx: idxExpr, width: elemSize, signed };
   }
   const bt = base.type;
@@ -243,12 +558,11 @@ const ARITH_TO_BIN: Record<string, BinOp> = {
   and: '&',
   xor: '^',
   shl: '<<',
-  shr_u: '>>',
+  shr_u: '>>>', // the LOGICAL right shift; the C backend spells it `>>` over an unsigned operand
   shr_s: '>>',
   logic_and: '&&',
   logic_or: '||', // short-circuit connectives (raise/shortcircuit.ts)
 };
-const NEGATE: Record<string, BinOp> = { '<': '>=', '>=': '<', '>': '<=', '<=': '>', '==': '!=', '!=': '==' };
 
 // Recovered info for a self-loop header: its exit block and the per-parameter back-edge
 // arg it feeds (the value on the header→header edge). The back-edge arg is the "next"
@@ -300,12 +614,32 @@ export interface StructureOptions {
   // body). GCC freely uses `!=`; IDO prefers `==`/`<`. A per-compiler DATA lever, not an `arch ==`
   // branch — default true (permissive; the decline path keeps it sound either way).
   switchAllowsNeqCase?: boolean;
+  // Anchor a constant merge copy at its const op's ORIGINAL position instead of at the CFG edge:
+  // `movs r9, #0` at entry ahead of a single-armed overwrite emits as a pre-initialization above
+  // the `if`, not as its else-arm. A differ-refereed candidate axis (rank.ts `/defsite`), never a
+  // default — see the refusal conditions where it is computed.
+  anchorConstCopies?: boolean;
+  // HARDWARE fact from TargetDescription.capabilities.endianness, threaded by structureOptionsFor:
+  // the bitfield extract recognizer solves an LSB-first equation, so it only runs on little-endian
+  // data. The provider already refuses to EMIT bitfield facts for a big-endian ELF; this is the
+  // same boundary enforced on core's side, against a hand-built map that never went through it.
+  littleEndian?: boolean;
+  // Spell `(x << a) >> b` extracts of a struct global as the map's named bitfield member. On by
+  // default; rank.ts enumerates the OFF spelling as the `/no-bitfield` axis, because the named
+  // read recompiles at the DECLARATION's access width — where that diverges from the asm's load
+  // width the honest shift spelling is the one that matches, and the differ referees.
+  spellBitfieldMembers?: boolean;
   // How an unresolvable VALUE degrades (a live `opaque`, an unlowered transient op, a dropped def):
   //   "strict"   (default) — the `"?"` sentinel, tripping assertResolved at the boundary (loud in
   //              the PROCESS);
   //   "annotate" — a `marker` node that spells as the undefined ASMLIFT_ERROR(...) symbol (loud in
   //              the ARTIFACT: the function emits complete, but cannot compile un-acknowledged).
   onGap?: 'strict' | 'annotate';
+  /** NAME-keyed project symbol facts (symbols.ts `symbolsByName`) — drives the byte-sensitive
+   *  declaration-shape spellings: `shape:'array'` forces the aggregate classification and the
+   *  bare `gSym[i]` form; `shape:'struct'`+layout spells interiors as `gSym.field`. Absent (or
+   *  a symbol not in the map) ⇒ today's usage-inferred behavior, byte-identical. */
+  symbols?: Map<string, SymbolInfo>;
 }
 
 export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
@@ -315,7 +649,11 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
     preserveDivergentBranchSense = true,
     orderArgCopiesByComputation = true,
     switchAllowsNeqCase = true,
+    anchorConstCopies = false,
+    littleEndian = true,
+    spellBitfieldMembers = true,
     onGap = 'strict',
+    symbols,
   } = opts;
   const defs = defOpMap(fn);
   const preds = predecessorBlocks(fn);
@@ -323,7 +661,10 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
   const dom = dominators(fn);
 
   // ── analysis phase (structure/analysis.ts): use registry, liveness, materialization ──
-  const { useSitesOf, opIndex, opBlock, liveIn, materialize, reachFrom } = analyze(fn, returnsVoid);
+  const { useSitesOf, opIndex, opBlock, liveIn, materialize, reachFrom, emitPos, memWriteBetween } = analyze(
+    fn,
+    returnsVoid,
+  );
 
   // SCALAR-vs-AGGREGATE globals: a `gaddr` symbol accessed EXCLUSIVELY at offset 0 is a scalar
   // global → the bare name `gSym` (byte-exact, matches the source). A symbol accessed at any
@@ -347,14 +688,16 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
           if (s) {
             (offsets.get(s) ?? offsets.set(s, new Set()).get(s)!).add(op.attrs.off as number);
           }
-          // a `+`-tree base holding a gaddr (global array element) is aggregate
-          const d = defs.get(op.operands[0]);
-          if (d?.opcode === 'add') {
-            for (const o of d.operands) {
-              const s2 = gaddrSym(o);
-              if (s2) {
-                bumpAgg(s2);
-              }
+        } else if (op.opcode === 'add' || op.opcode === 'sub') {
+          // ANY arithmetic on the symbol's address is interior addressing ⇒ aggregate — even when
+          // the sum only reaches memory through a copy/phi (a pointer-walk loop `p = &g + 2;
+          // do { *p++ … }` never makes the add a DIRECT load/store base, which is all the old
+          // check saw; the symbol then classified scalar and emitted the bare `g = 0` spelling,
+          // which a project declaring `extern u16 g[]` rejects as an incomplete-type assignment).
+          for (const o of op.operands) {
+            const s2 = gaddrSym(o);
+            if (s2) {
+              bumpAgg(s2);
             }
           }
         } else if (op.opcode === 'aload' || op.opcode === 'astore') {
@@ -370,8 +713,38 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
         scalarGlobals.add(sym);
       }
     }
+    // Declaration-shape OVERRIDE (symbol map): a project-declared array/struct global is an
+    // AGGREGATE whatever the usage inference saw — a lone off-0 access to `extern u16 tbl[]`
+    // must still spell through the aggregate/array forms, never the bare scalar `tbl`.
+    if (symbols) {
+      for (const [n, si] of symbols) {
+        if (si.shape === 'array' || si.shape === 'struct') {
+          scalarGlobals.delete(n);
+        }
+      }
+    }
   }
 
+  // Symbol-map rendering context (memAccess/arrayAccess): shape lookups + the env registry for
+  // array-shaped globals actually referenced (they surface as SFn.globals — typed, undeclared).
+  const shapedGlobalTypes = new Map<string, IrType>();
+  const symCtx: SymRenderCtx | undefined = symbols
+    ? { info: (n) => symbols.get(n), noteGlobal: (n, t) => shapedGlobalTypes.set(n, t) }
+    : undefined;
+
+  /** A bare `gSym` naming a map-declared POINTER global — the VALUE of a pointer cell. Load,
+   *  store and compare of that 4-byte cell are identical for any object-pointer type, so the
+   *  declared pointee never matters to THEM; arithmetic on the loaded value is the opposite case,
+   *  where the pointee's size scales what is added and every stride must therefore be made
+   *  explicit (`(u8 *)gPtr + K`). `ctype` cannot see any of this: it types only params/locals, so
+   *  a pointer global renders `undefined` there. */
+  const isPtrGlobal = (x: Expr): boolean => x.k === 'var' && symCtx?.info(x.name)?.shape === 'pointer';
+
+  /** Operands `-`/`~` cannot take as spelled: a rendered pointer, a bare `&gSym`, a pointer
+   *  global's value. All three are ill-formed C under a unary arithmetic operator — the asm did
+   *  32-bit integer math on the address, so that is what gets spelled. */
+  const needsIntSpelling = (x: Expr): boolean => ctype(x)?.kind === 'ptr' || x.k === 'addr' || isPtrGlobal(x);
+
   // --- loop discovery (loops.ts): natural loops via dominator back-edges + the nesting forest ---
   const forest = analyzeLoops(fn, dom);
 
@@ -580,6 +953,50 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
   // The C static type of a rendered expression, over the declared variable types — what decides
   // whether a memory access's base may be dereferenced as spelled (memAccess/arrayAccess).
   const ctype = (e0: Expr): IrType | undefined => exprCType(e0, (n) => varType.get(n));
+
+  /** `&gSym` assigned to a `T *` local: the address of an AGGREGATE is not a pointer to its
+   *  element. `&gArr` is `T (*)[n]`, `&gStruct` is `struct S *`, and neither is assignable to
+   *  `T *` — yet the IR's `gaddr` value legitimately has type `T *`, because that is what the asm
+   *  loaded. The bare spelling therefore states a type the project's own header contradicts.
+   *
+   *  It survived because agbcc only WARNS ("assignment from incompatible pointer type") and
+   *  computes the right address anyway. That leniency is not something to rely on: the Klonoa
+   *  project's own build template treats these as fatal, so the row's emitted C does not build
+   *  where its author would put it. The cast is the always-valid spelling — the same fallback
+   *  `bareArrayLead` documents for the indexed form — and it is byte-identical (measured on
+   *  kleod:UpdateHUDCounterDisplay: 81 with and without).
+   *
+   *  The test is whether `&gSym`'s rendered type PROVABLY equals the destination's, not whether the
+   *  symbol looks like an aggregate. A shape enumeration got this wrong three ways, each a real
+   *  miss: `shape:'pointer'` declares a pointer cell (`void *gSym`, or `struct Tag *gSym` when the
+   *  pointee has a declarable layout), so `&gSym` is a pointer-to-pointer either way; a `shape:'scalar'`
+   *  whose width differs from the destination's pointee gives `s32 *` for a `u16 *` slot; and a
+   *  NAME-ONLY symbol is synthesized as `extern u32 gSym;` (declare.ts), which is `u32 *` — not the
+   *  `T *` the older comment here claimed. So the default is to CAST, and the cast is omitted only
+   *  where the declared cell type is known and matches exactly. Byte-identical either way, so the
+   *  cost of casting one time too many is a redundant `(T *)`, never a wrong address. */
+  const castAggregateAddr = (name: string, value: Expr): Expr => {
+    const t = varType.get(name);
+    if (t?.kind !== 'ptr' || value.k !== 'addr') {
+      return value;
+    }
+    // The only provably-redundant case: a NON-VOLATILE scalar cell whose DECLARED type is the
+    // destination's pointee, where `&gSym` already denotes exactly `T *`.
+    //
+    // `scalarCellType` and not `scalarTypeForAccess`: the latter answers what an ACCESS of that
+    // width reads and collapses every 4-byte access to `s32`, so it called a `u32` cell equal to an
+    // `s32 *` destination and let the incompatible assignment through. And a `volatile` cell makes
+    // `&gSym` a `volatile T *`, so omitting the cast would DISCARD the qualifier — the same class of
+    // fatal-under-a-strict-build defect this rule exists to remove.
+    const si = symCtx?.info(value.name);
+    if (si?.shape === 'scalar' && !si.volatile && isScalarCellSize(si.size)) {
+      if (typeEquals(scalarCellType(si.size, si.signed), t.to)) {
+        return value;
+      }
+    }
+    return { k: 'cast', to: t, e: value };
+  };
+
   let fresh = 0;
   // Materialized defs are named FIRST: the temp is the register the compiler held the
   // value in, so downstream coalescing (loop inits, merge params) may adopt it — subject to the
@@ -786,11 +1203,270 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
     }
   }
 
-  // An unresolvable value: strict mode keeps the `"?"` sentinel (assertResolved trips at the
-  // boundary — loud in the PROCESS); annotate mode emits a marker (the undefined ASMLIFT_ERROR
-  // symbol — loud in the ARTIFACT, function still complete).
-  const mkGap = (reason: string, args: Expr[]): Expr =>
-    onGap === 'annotate' ? { k: 'marker', reason, args } : { k: 'var', name: '?' };
+  // ── def-site anchoring of constant merge copies (anchorConstCopies) ──────────────────────────
+  // An edge copy `v = K` places the constant where the EDGE is, but the asm often materialized K
+  // earlier: `movs r9, #0` at entry ahead of a single-armed overwrite, `movs r5, #1` at the top
+  // of an arm ahead of a nested if. Anchoring the copy at the const op's own program position
+  // reproduces that placement — the write is emitted as a statement there (sideEffects reads
+  // `anchoredAt`) and the edge copies it replaces are suppressed (argAssignsFor reads
+  // `suppressedArgs`). Where the surviving arm then empties, mkIf's empty-then peephole yields
+  // the single-armed positive `if` the source wrote.
+  //
+  // REFUSAL CONDITIONS — each keeps the edge placement, never producing a different write:
+  //   - the arg is not an UNNAMED `const` op (only a rematerializable constant carries
+  //     unambiguous placement evidence; a named value's position is its materialized def's);
+  //   - the merge is a loop header (loop copies have their own placement discipline);
+  //   - the const's block does not dominate every edge source passing it (the anchored write
+  //     must precede the edge on every path);
+  //   - the const's block or any edge source sits inside ANY loop. Block-level dominance does
+  //     not give per-ITERATION precedence — a path may pass the def in iteration 1 and take the
+  //     suppressed edge in iteration 2 with the variable overwritten in between, the /preinit
+  //     sticky-arm failure class (PR #13) — so in-loop shapes are declined outright;
+  //   - the merge variable names any OTHER SSA value (a shared name has readers and writers
+  //     between the def site and the edge that edge placement respects and anchoring would not);
+  //   - another anchored const of the same variable lies on a path from this one to this one's
+  //     edge (the later write would clobber this arg's value; both stay at their edges instead).
+  const anchoredAt = new Map<Op, { name: string; arg: Value }[]>();
+  const suppressedArgs = new Map<object, Set<number>>();
+  if (anchorConstCopies) {
+    const nameCount = new Map<string, number>();
+    for (const n of varName.values()) {
+      nameCount.set(n, (nameCount.get(n) ?? 0) + 1);
+    }
+    const inLoop = (b: Block): boolean => {
+      for (const nl of forest.byHeader.values()) {
+        if (nl.body.has(b)) {
+          return true;
+        }
+      }
+      return false;
+    };
+    // conservative "a write in `a` may execute between one in `b` and `b`'s terminator": same
+    // block counts (op order refined by the caller where it matters), else CFG reachability
+    const mayFollow = (a: Block, b: Block): boolean => a === b || reachFrom(a).has(b);
+    for (const M of fn.blocks) {
+      if (M === entry || M.params.length === 0 || forest.byHeader.has(M)) {
+        continue;
+      }
+      M.params.forEach((p, i) => {
+        const name = varName.get(p)!;
+        if (nameCount.get(name) !== 1) {
+          return;
+        }
+        // every in-edge record into M, grouped by the SSA value it passes for param i
+        const groups = new Map<Value, { rec: { block: Block; args: Value[] }; src: Block }[]>();
+        for (const pr of new Set(preds.get(M) ?? [])) {
+          for (const s of pr.ops[pr.ops.length - 1].successors) {
+            if (s.block === M) {
+              const g = groups.get(s.args[i]);
+              if (g) {
+                g.push({ rec: s, src: pr });
+              } else {
+                groups.set(s.args[i], [{ rec: s, src: pr }]);
+              }
+            }
+          }
+        }
+        const candidates: { arg: Value; def: Op; defBlock: Block; edges: { rec: object; src: Block }[] }[] = [];
+        for (const [arg, edges] of groups) {
+          const def = defs.get(arg);
+          if (!def || def.opcode !== 'const' || varName.has(arg)) {
+            continue;
+          }
+          const defBlock = opBlock.get(def)!;
+          if (inLoop(defBlock) || edges.some(({ src }) => inLoop(src))) {
+            continue;
+          }
+          if (edges.some(({ src }) => !dom.get(src)!.has(defBlock))) {
+            continue;
+          }
+          candidates.push({ arg, def, defBlock, edges });
+        }
+        // pairwise clobber check: candidate `c` is unsafe when another candidate's write can lie
+        // between c's def and one of c's edges (def_c → def_o → edge_c); both then keep their edges
+        const safe = candidates.filter((c) =>
+          candidates.every((o) => {
+            if (o === c) {
+              return true;
+            }
+            const oAfterC =
+              c.defBlock === o.defBlock ? opIndex.get(o.def)! > opIndex.get(c.def)! : mayFollow(c.defBlock, o.defBlock);
+            return !(oAfterC && c.edges.some(({ src }) => mayFollow(o.defBlock, src)));
+          }),
+        );
+        for (const c of safe) {
+          const at = anchoredAt.get(c.def);
+          if (at) {
+            at.push({ name, arg: c.arg });
+          } else {
+            anchoredAt.set(c.def, [{ name, arg: c.arg }]);
+          }
+          for (const { rec } of c.edges) {
+            const sup = suppressedArgs.get(rec);
+            if (sup) {
+              sup.add(i);
+            } else {
+              suppressedArgs.set(rec, new Set([i]));
+            }
+          }
+        }
+      });
+    }
+  }
+
+  // ── BITFIELD member reads (symbol map) ──────────────────────────────────────────────────────
+  // The `(x << a) >> b` extract of a struct global's loaded bytes IS a bitfield access when the
+  // map declares a bitfield at exactly those bits: spelled `gSym.field`, the source form, whose
+  // declared `u32 field : n` then makes C's own integer promotion reproduce the signedness every
+  // downstream operator compiled with (a 7-bit unsigned field promotes to signed int — sdiv
+  // renders `/` and recompiles to __divsi3, where the raw-shift spelling stays u32).
+  //
+  // Semantically EXACT, never approximate: the window must lie inside the loaded bytes (so the
+  // load's extension bits cannot reach it), the field's position, width and signedness must all
+  // match the extract (a logical shift is an unsigned read, an arithmetic one a signed read —
+  // a signless field never matches), and the member must be nameable at all (memberQualsAllow;
+  // the map only carries bitfield facts for little-endian ELFs — see SymbolStructField). Any
+  // mismatch keeps the honest shift spelling.
+  //
+  // Precomputed over the ops (not folded during rendering) for the load's sake: a load whose
+  // EVERY use is a spelled extract chain must not also emit its materialized `v = *(u16 *)&g;`
+  // temp — the compiler CSEs the repeated member reads back to one load, but the leftover temp
+  // would be a second one. A VOLATILE container refuses the whole fold: N member reads are N
+  // volatile accesses where the asm did one load. (Byte-level residual, differ-refereed: a load
+  // only PARTIALLY absorbed — one extract spelled, another use kept — emits both the temp and
+  // the named reads, one load more than the asm; semantics hold, the score decides.)
+  //
+  // ORDERING GATE (adversarial round, CRITICAL 1 — twice): the named spelling replaces a
+  // REGISTER value — the bits captured at the load's program position — with a fresh memory
+  // read at each render position. Every other memory read in this file goes through the
+  // materialization model (analysis.ts) for exactly that hazard, so the fold clears the SAME
+  // bar with the SAME machinery: `emitPos` resolves where each extract actually renders
+  // (transitively through its inlining consumers — an unresolvable position refuses), and
+  // `memWriteBetween` walks every def-avoiding load→render path for a call, an opaque, or a
+  // store not provably to a DIFFERENT named global. Path-based on purpose: the second audit
+  // pass broke the first fix's linear-position scan with a block laid out AFTER the render in
+  // address order but executing between load and render on the taken path — fn.blocks order is
+  // address order, not topological order.
+  const bitfieldSpelling = new Map<Op, { global: string; field: string }>();
+  const absorbedLoads = new Set<Op>();
+  if (symCtx && littleEndian && spellBitfieldMembers) {
+    // the (name, byte) of a load's address when it resolves through defs alone — `gaddr` or
+    // `add(gaddr, const)`; anything else (a materialized base, a variable index) declines
+    const loadTargets = new Map<Op, { name: string; byte: number }>();
+    const addrOf = (v: Value, off: number): { name: string; byte: number } | null => {
+      const d0 = defs.get(v);
+      if (d0?.opcode === 'gaddr') {
+        return { name: d0.attrs.sym as string, byte: off };
+      }
+      if (d0?.opcode === 'add' && d0.operands.length === 2) {
+        for (const [x, y] of [
+          [d0.operands[0], d0.operands[1]],
+          [d0.operands[1], d0.operands[0]],
+        ] as const) {
+          const g0 = defs.get(x);
+          const c0 = defs.get(y);
+          if (g0?.opcode === 'gaddr' && c0?.opcode === 'const') {
+            return { name: g0.attrs.sym as string, byte: (c0.attrs.value as number) + off };
+          }
+        }
+      }
+      return null;
+    };
+    // A write for the fold's purposes: calls and opaques always; a store/astore unless its base
+    // resolves to a global PROVABLY different from the folded one. (Name comparison suffices:
+    // the pool promotion picks one canonical name per address, so one cell cannot appear under
+    // two names within a function.)
+    const mayWrite =
+      (sym: string) =>
+      (x: Op): boolean => {
+        if (x.opcode === 'call' || x.opcode === 'opaque') {
+          return true;
+        }
+        if (x.opcode !== 'store' && x.opcode !== 'astore') {
+          return false;
+        }
+        const t = addrOf(x.operands[0], 0);
+        return !(t && t.name !== sym);
+      };
+    for (const blk of fn.blocks) {
+      for (const op of blk.ops) {
+        if ((op.opcode !== 'shr_u' && op.opcode !== 'shr_s') || op.operands.length !== 1) {
+          continue;
+        }
+        const b = op.attrs.imm as number | undefined;
+        const inner = defs.get(op.operands[0]);
+        if (typeof b !== 'number' || b <= 0 || b >= 32 || inner?.opcode !== 'shl' || inner.operands.length !== 1) {
+          continue;
+        }
+        const a = inner.attrs.imm as number | undefined;
+        if (typeof a !== 'number' || a < 0 || b < a) {
+          continue;
+        }
+        const w = 32 - b; // extract width
+        const lo = b - a; // low bit within the loaded value
+        const load = defs.get(inner.operands[0]);
+        if (load?.opcode !== 'load' || lo + w > (load.attrs.width as number) * 8) {
+          continue;
+        }
+        // a materialized shl would still emit its `v = x << a` temp reading the load — the fold
+        // would then ADD member reads on top of it; rare, refuse
+        if (materialize.has(inner)) {
+          continue;
+        }
+        const gb = addrOf(load.operands[0], load.attrs.off as number);
+        const si = gb ? symCtx.info(gb.name) : undefined;
+        if (!gb || si?.shape !== 'struct' || si.volatile) {
+          continue;
+        }
+        // where does the member read RENDER? at the extract's own position when materialized,
+        // else wherever each of its consumers ultimately renders (emitPos, transitively —
+        // unresolvable refuses); every load→render path must be write-free
+        const renders = materialize.has(op)
+          ? [{ blk: opBlock.get(op)!, idx: opIndex.get(op)! }]
+          : [...new Set((useSitesOf.get(op.results[0]) ?? []).map((s) => s.op))].map((c) => emitPos(c));
+        const writes = mayWrite(gb.name);
+        if (renders.some((r) => r === null) || renders.some((r) => memWriteBetween(load, r!, writes))) {
+          continue;
+        }
+        const signedRead = op.opcode === 'shr_s';
+        const fld = declaredFields(si.layout)?.find(
+          (f) => f.bitWidth === w && f.offset * 8 + f.bitOffset! === gb.byte * 8 + lo && f.signed === signedRead,
+        );
+        if (fld && memberQualsAllow(fld, si.const, false)) {
+          bitfieldSpelling.set(op, { global: gb.name, field: fld.name });
+          loadTargets.set(load, gb);
+        }
+      }
+    }
+    // a load is ABSORBED when every use is an shl whose every use is a spelled extract
+    for (const load of loadTargets.keys()) {
+      const shls = useSitesOf.get(load.results[0]) ?? [];
+      const absorbed =
+        shls.length > 0 &&
+        shls.every(
+          (u) =>
+            u.op.opcode === 'shl' && (useSitesOf.get(u.op.results[0]) ?? []).every((v) => bitfieldSpelling.has(v.op)),
+        );
+      if (absorbed) {
+        absorbedLoads.add(load);
+      }
+    }
+  }
+
+  // An unresolvable value: strict mode keeps the `"?"` sentinel AND records the reason — the
+  // decline thrown below names the actual gaps ("unmodelled instruction 'adde'"), the same
+  // reasons annotate mode's markers carry, instead of the anonymous `?` that assertResolved
+  // would report at the boundary (assertResolved stays as the backstop for any other producer).
+  // Annotate mode emits a marker (the undefined ASMLIFT_ERROR symbol — loud in the ARTIFACT,
+  // function still complete).
+  const strictGaps: string[] = [];
+  const mkGap = (reason: string, args: Expr[]): Expr => {
+    if (onGap === 'annotate') {
+      return { k: 'marker', reason, args };
+    }
+    strictGaps.push(reason);
+    return { k: 'var', name: '?' };
+  };
 
   // Lower ONE def's operation to an Expr, rendering operands through `e`. Shared between the
   // inline-at-use path (exprWith) and the materialized-temp path (sideEffects), so both spell a
@@ -799,8 +1475,37 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
     if (d.opcode === 'const') {
       return { k: 'const', value: d.attrs.value as number };
     }
+    // a bitfield extract recognized over the ops (see the precompute above): the member read,
+    // not the shift pair
+    const bf = bitfieldSpelling.get(d);
+    if (bf) {
+      return { k: 'field', base: { k: 'var', name: bf.global }, name: bf.field, dot: true };
+    }
     if (CMP_TO_BIN[d.opcode]) {
-      return { k: 'bin', op: CMP_TO_BIN[d.opcode], l: e(d.operands[0]), r: e(d.operands[1]) };
+      // A bare global address `&gSym` as a COMPARISON operand is the same unspelled escape as the
+      // arithmetic case below (see intifyAddr): its C type comes from the PROJECT's own
+      // declaration, unknowable here. Worse, the compare's SIGNEDNESS lives in the operand types
+      // (CMP_TO_BIN maps icmp_ult and icmp_slt to the same '<'), so leaving `&gSym` untyped lets
+      // the project's declaration pick the compare the compiler emits — silently byte-inexact
+      // whenever it disagrees with the asm. The honest spelling is integer math on the address
+      // with the cast AGREEING with the opcode's signedness: unsigned compares (and the
+      // sign-agnostic ==/!=) spell `(u32)&gSym`, signed compares `(s32)&gSym` — exactly the
+      // compare the asm did. The deref folds never see a compare operand, so no named spelling is
+      // lost; a NARROWING cast (`(u8)&gSym`) is not a bare `addr` and keeps its truncation.
+      // SCOPE (adversarial review): this closes the hole for BARE addr operands only. An
+      // addr-carrying arithmetic tree (`(u32)&gSym + 4`, spelled by intifyAddr below) under an
+      // icmp_s* still compares unsigned in C (u32 wins the usual-arithmetic-conversions) — the
+      // same pre-existing wrongness the old ptr-vs-int spelling had, surfacing as a scoring
+      // nonmatch, never a silent regression of a formerly-correct compare. Rare shape; an outer
+      // signed cast on addr-carrying trees is the follow-up if it ever costs a row.
+      const t = /^icmp_s/.test(d.opcode) ? T.s(32) : T.u(32);
+      const intifyAddrCmp = (x: Expr): Expr => (x.k === 'addr' ? { k: 'cast', to: t, e: x } : x);
+      return {
+        k: 'bin',
+        op: CMP_TO_BIN[d.opcode],
+        l: intifyAddrCmp(e(d.operands[0])),
+        r: intifyAddrCmp(e(d.operands[1])),
+      };
     }
     if (ARITH_TO_BIN[d.opcode]) {
       let l = e(d.operands[0]);
@@ -844,6 +1549,53 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
       } else if (op === '-' && ctype(l)?.kind !== 'ptr' && ctype(r)?.kind === 'ptr') {
         r = intify(r); // int - ptr is not C
       }
+      // A bare global address `&gSym` under ANY of these operators is never emitted as-is: its C
+      // type comes from the PROJECT's own declaration (unknowable here — exprCType types `addr`
+      // undefined, so the ptr-keyed intify above never fires on it), which makes `&gSym + K`
+      // byte-INEXACT (C scales K by sizeof(gSym)) and `&gSym & K` ill-formed. The honest spelling
+      // is integer math on the address — `(u32)&gSym + K`, exactly the arithmetic the asm did.
+      // The deref folds (globalOf / globalConstByte, via addrIn) look through this cast, so every
+      // access that CAN spell a named element/field still does; only a genuine value-context
+      // escape (a call argument, a stored address, a compare) keeps it — previously such an
+      // escape tripped assertDerefsTyped's interior-pointer rule and declined the whole function.
+      const intifyAddr = (x: Expr): Expr => (x.k === 'addr' ? { k: 'cast', to: T.u(32), e: x } : x);
+      l = intifyAddr(l);
+      r = intifyAddr(r);
+      // The SAME hazard one level down, for a POINTER-shaped global's VALUE (`gPtr`, isPtrGlobal):
+      // C scales `gPtr + K` by sizeof(*gPtr) — 1 under the map's synthesized `void *`, but
+      // whatever the PROJECT's header declares (a 0x5C-byte struct, say) in the world a user
+      // actually recompiles in. The asm added BYTES, so the honest spelling makes the stride
+      // explicit: CAST-THEN-ADD, `(u8 *)gPtr + K`, the same address in EVERY world. Add-then-cast
+      // (`(u8 *)(gPtr + K)`, what the backend's deref legalization would otherwise produce) is
+      // byte-correct in exactly one of them — a silent wrongness, the class this project refuses.
+      // NOT foldable into the deref index either: `((u8 *)gPtr)[K + off]` re-scales K by the
+      // ACCESS width, a different address whenever that width is not 1.
+      // Under the non-additive operators C rejects a pointer outright, so there the honest
+      // spelling is integer math on the cell — exactly intifyAddr's `(u32)&gSym` rule.
+      const bytePtr = (x: Expr): Expr => ({ k: 'cast', to: T.ptr(T.u(8)), e: x });
+      const intifyPtrGlobal = (x: Expr): Expr => ({ k: 'cast', to: T.u(32), e: x });
+      if (op === '+' || op === '-') {
+        // `ptr ± int` and `ptr - ptr` are byte arithmetic once both sides are byte pointers;
+        // `ptr + ptr` and `int - ptr` are not C at all, so the second pointer goes integer.
+        const bothPtr = isPtrGlobal(l) && isPtrGlobal(r);
+        if (isPtrGlobal(l)) {
+          l = bytePtr(l);
+        }
+        if (isPtrGlobal(r)) {
+          r = bothPtr && op === '-' ? bytePtr(r) : op === '+' && !bothPtr ? bytePtr(r) : intifyPtrGlobal(r);
+        }
+      } else if (op !== '&&' && op !== '||') {
+        // (`&&`/`||` take a pointer operand legally — a truth test, no arithmetic.)
+        l = isPtrGlobal(l) ? intifyPtrGlobal(l) : l;
+        r = isPtrGlobal(r) ? intifyPtrGlobal(r) : r;
+      }
+      // (The two right shifts stay DISTINCT ops here — `>>>` logical, `>>` arithmetic. Which token
+      // a language spells each with, and what cast pins the choice, is a BACKEND decision; see
+      // l3/ast.ts BinOp and backend/cfamily.ts's shift rule.)
+      // SCOPE: this and intifyAddr cover the ARITHMETIC escapes. A pointer global under a
+      // COMPARISON (`gPtr < K` — C compares unsigned whatever the asm's icmp_s* said) is the same
+      // class as intifyAddrCmp's `addr` rule and is deliberately left alone here: it is valid C
+      // today, so closing it would churn spellings for a signedness case no row exercises.
       return { k: 'bin', op, l, r };
     }
     // `-`/`~` on a pointer rendering is equally not C — same honest integer cast as above.
@@ -851,8 +1603,9 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
       // The C rotate idiom — `x >> n | x << (32 - n)` (mirrored for rotl). Byte-exact round-trip
       // on agbcc (thumb ror) and mwcc (rotlw/rotlwi), verified against both toolchains before the
       // ops landed. `x` and `n` render twice — both pure by construction (SSA values; the rotate's
-      // operands are register reads), and recovery seeds the rotated value unsigned so `>>`
-      // spells the logical shift the idiom requires.
+      // operands are register reads). The right half is the LOGICAL shift `>>>` — the idiom is
+      // wrong with an arithmetic one — stated on the node rather than left to the rotated value's
+      // recovered unsignedness, which is a property of recovery rather than of the idiom.
       //
       // (The PPC mirror fold — `rotl(x, 32 - m)` ⇒ rotr(x, m) — lives in the PATTERN layer,
       // engine.ts ROTL_MIRROR: it is a compiler-spelling idiom, mwcc-gated there, not a
@@ -869,7 +1622,7 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
         n.k === 'const'
           ? { k: 'const', value: 32 - n.value }
           : { k: 'bin', op: '-', l: { k: 'const', value: 32 }, r: n };
-      const [near, far] = dir === 'rotr' ? (['>>', '<<'] as const) : (['<<', '>>'] as const);
+      const [near, far] = dir === 'rotr' ? (['>>>', '<<'] as const) : (['<<', '>>>'] as const);
       return {
         k: 'bin',
         op: '|',
@@ -879,11 +1632,11 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
     }
     if (d.opcode === 'neg') {
       const x = e(d.operands[0]);
-      return { k: 'un', op: '-', e: ctype(x)?.kind === 'ptr' ? { k: 'cast', to: T.s(32), e: x } : x };
+      return { k: 'un', op: '-', e: needsIntSpelling(x) ? { k: 'cast', to: T.s(32), e: x } : x };
     }
     if (d.opcode === 'not') {
       const x = e(d.operands[0]);
-      return { k: 'un', op: '~', e: ctype(x)?.kind === 'ptr' ? { k: 'cast', to: T.s(32), e: x } : x };
+      return { k: 'un', op: '~', e: needsIntSpelling(x) ? { k: 'cast', to: T.s(32), e: x } : x };
     }
     // Width-narrowing casts: `zext`/`sext` widen a `width`-bit value back to 32 → C `(u8)e`/`(s8)e`.
     if (d.opcode === 'zext') {
@@ -896,6 +1649,12 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
       return { k: 'call', fn: d.attrs.target as string, args: d.operands.map(e) };
     }
     if (d.opcode === 'gaddr') {
+      // A promoted CODE symbol (frontend `code: true`) is a function pointer stored as an
+      // integer: spelled `(u32)Name` — the source idiom — never `&Name` (defect G of the
+      // dogfood report; the & form compiles but is a different, non-matching spelling).
+      if (d.attrs.code === true) {
+        return { k: 'cast', to: T.int(32, false), e: { k: 'var', name: d.attrs.sym as string } };
+      }
       return { k: 'addr', name: d.attrs.sym as string };
     }
     if (d.opcode === 'load') {
@@ -907,6 +1666,7 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
         (d.attrs.signed as boolean) ?? false,
         ctype,
         scalarGlobals,
+        symCtx,
       );
     }
     // aload carries a runtime index operand (variable-index array access) — `base[index]`, or
@@ -920,6 +1680,7 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
         d.attrs.elemSize as number,
         (d.attrs.signed as boolean) ?? false,
         ctype,
+        symCtx,
       );
     }
     return d.opcode === 'opaque'
@@ -983,13 +1744,17 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
     const target = succ.block;
     const argExpr = sub ? exprWith(sub) : expr;
     const copies: { name: string; value: Expr; arg: Value }[] = [];
+    const suppressed = suppressedArgs.get(succ);
     target.params.forEach((p, i) => {
+      if (suppressed?.has(i)) {
+        return;
+      } // anchored at its const's def site — the write already ran before this edge
       const name = varName.get(p)!;
       const arg = succ.args[i];
       if ((sub?.get(arg) ?? varName.get(arg)) === name) {
         return;
       } // identity copy — coalesced away
-      copies.push({ name, value: argExpr(arg), arg });
+      copies.push({ name, value: castAggregateAddr(name, argExpr(arg)), arg });
     });
     // Emit in the order the args are COMPUTED in `pred` — a compiler that lays the defining ops
     // (and thus the copies that read them) out in that order matches with no spurious arg-swap.
@@ -1035,6 +1800,8 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
           width === 4,
           ctype,
           scalarGlobals,
+          symCtx,
+          true, // an lvalue: a member whose declaration is const cannot be NAMED as the target
         );
         if (lval0.k === 'var') {
           globalNames.add(lval0.name);
@@ -1056,13 +1823,21 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
             elemSize,
             elemSize === 4,
             ctype,
+            symCtx,
           ),
           value: expr(op.operands[2]),
         });
       } else if (op.opcode === 'call' && op.results.length && !useSitesOf.has(op.results[0])) {
         out.push({ k: 'exprstmt', value: expr(op.results[0]) });
-      } else if (materialize.has(op)) {
-        out.push({ k: 'assign', name: varName.get(op.results[0])!, value: lowerDef(op, expr) });
+      } else if (materialize.has(op) && !absorbedLoads.has(op)) {
+        // (an absorbed load's every consumer spells a named bitfield read — emitting its temp
+        // here would recompile to a second load the asm does not have)
+        const nm = varName.get(op.results[0])!;
+        out.push({ k: 'assign', name: nm, value: castAggregateAddr(nm, lowerDef(op, expr)) });
+      }
+      // a merge copy anchored at this const's original position (anchorConstCopies, above)
+      for (const a of anchoredAt.get(op) ?? []) {
+        out.push({ k: 'assign', name: a.name, value: expr(a.arg) });
       }
     }
     return out;
@@ -1122,6 +1897,7 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
     isNamed: (v) => varName.has(v),
     isCmpOpcode: (opcode) => !!CMP_TO_BIN[opcode],
     switchAllowsNeqCase,
+    emitsAnchoredWrite: (blk) => blk.ops.some((o) => anchoredAt.has(o)),
     expr: (v) => expr(v),
     structureRegion: (b, stop) => structureRegion(b, stop),
   });
@@ -1323,7 +2099,7 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
         out.push(...updateCopies); // the loop update, RAW (i++, p>>=1, …)
         let leaveCond = exprWith(sub)(term.operands[0]);
         if (contIsTaken) {
-          leaveCond = negate(leaveCond);
+          leaveCond = negateCond(leaveCond);
         } // continue is `taken` → leave when NOT it
         const exitArm = isBreak
           ? [...argAssigns(b, loopCtx.exit, sub), { k: 'break' } as Stmt] // break to the loop exit
@@ -1357,7 +2133,7 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
       // IDO/MIPS; agbcc/GCC canonicalise either way, so it is safe there too. A compiler that
       // inverts branch canonicalization sets preserveDivergentBranchSense false and falls through
       // to the positive form below.
-      out.push({ k: 'if', cond: negate(cond), then: elseS, else: thenS });
+      out.push({ k: 'if', cond: negateCond(cond), then: elseS, else: thenS });
       return out;
     }
     out.push(mkIf(cond, thenS, elseS));
@@ -1386,7 +2162,7 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
     const term = li.header.ops[li.header.ops.length - 1];
     let cond = exprWith(loopSub(li))(term.operands[0]);
     if (term.successors[0].block !== li.header) {
-      cond = negate(cond);
+      cond = negateCond(cond);
     } // loop-continue must be `taken`
     const body = [...sideEffects(li.header), ...(updates ?? argAssigns(li.header, li.header))];
     return { k: 'while', cond, body };
@@ -1400,7 +2176,7 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
     const term = wl.header.ops[wl.header.ops.length - 1];
     let cond = expr(term.operands[0]);
     if (term.successors[1].block === wl.bodyEntry) {
-      cond = negate(cond);
+      cond = negateCond(cond);
     }
     // The header→bodyEntry edge may carry non-identity phi args (a value the header COMPUTED and passes
     // into the body). Those copies must open the body — dropping them reads an uninitialised local.
@@ -1462,7 +2238,7 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
     const body = [...inner, ...sideEffects(dw.latch), ...updates];
     let cond = exprWith(sub)(lterm.operands[0]);
     if (lterm.successors[1].block === dw.header) {
-      cond = negate(cond);
+      cond = negateCond(cond);
     } // continue edge must be `taken`
     const out: Stmt[] = [{ k: 'dowhile', cond, body }];
     // The exit region reads latch back-edge values under `sub` (post-loop they live in the loop vars).
@@ -1471,6 +2247,14 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
   };
 
   const body = recognizeForLoops(structureRegion(entry, null));
+  // Strict-mode gaps decline HERE, naming the reasons — the same text annotate's markers
+  // carry, so the two mode surfaces report the same decline (the reproduction scripts run
+  // strict; the benchmark rows store annotate markers — fidelity holds them against each
+  // other). Without this, the `?` sentinels reach assertResolved and decline anonymously.
+  if (strictGaps.length > 0) {
+    const reasons = [...new Set(strictGaps)].join('; ');
+    throw new StructureError(`${strictGaps.length} unresolvable value(s) in '${fn.name}' — ${reasons}`);
+  }
   // v* = coalesced/materialized locals; t* = sequentialize's swap-cycle temps (varType-only —
   // they have no Value, so they are collected from varType, not varName).
   const localNames = [...new Set([...varName.values(), ...[...varType.keys()].filter((n) => /^t\d+$/.test(n))])].filter(
@@ -1481,6 +2265,13 @@ export function structure(fn: Fn, opts: StructureOptions = {}): SFn {
     name: fn.name,
     params: entry.params.map((p, i) => ({ name: `a${i}`, type: p.type })),
     locals: localNames.map((n) => ({ name: n, type: varType.get(n)! })),
+    ...(shapedGlobalTypes.size
+      ? {
+          globals: [...shapedGlobalTypes]
+            .map(([name, type]) => ({ name, type }))
+            .sort((a, b) => a.name.localeCompare(b.name)),
+        }
+      : {}),
     retType: returnsVoid ? T.void() : returnType(fn),
     body,
     ...(structs.length ? { structs } : {}),
@@ -1630,16 +2421,10 @@ function substVar(e: Expr, from: string, to: string): Expr {
 // empty-then peephole: `if (c) {} else { S }` → `if (!c) { S }`
 function mkIf(cond: Expr, thenS: Stmt[], elseS: Stmt[]): Stmt {
   if (thenS.length === 0 && elseS.length > 0) {
-    return { k: 'if', cond: negate(cond), then: elseS, else: [] };
+    return { k: 'if', cond: negateCond(cond), then: elseS, else: [] };
   }
   return { k: 'if', cond, then: thenS, else: elseS };
 }
-function negate(e: Expr): Expr {
-  if (e.k === 'bin' && NEGATE[e.op]) {
-    return { ...e, op: NEGATE[e.op] };
-  }
-  return { k: 'un', op: '!', e };
-}
 
 // --- CFG utilities ---
 function predecessorBlocks(fn: Fn): Map<Block, Block[]> {