@asmlift/core 0.3.0 → 0.4.0

package/src/structure/switch-recover.ts

@@ -18,6 +18,12 @@ export interface SwitchRecoverDeps {
   /** is this opcode an integer comparison? */
   isCmpOpcode: (opcode: string) => boolean;
   switchAllowsNeqCase: boolean;
+  /** does emitting this block's ops carry a statement beyond the ops themselves? A def-site
+   *  ANCHORED merge copy (structure.ts anchorConstCopies) is attached to a const op and emitted
+   *  with the block's side effects — a test block carrying one is not pure however pure its
+   *  opcodes look, because collapsing it into a `switch` discards the write while the edge copy
+   *  it replaced stays suppressed. */
+  emitsAnchoredWrite: (blk: Block) => boolean;
   expr: (v: Value) => Expr;
   structureRegion: (b: Block, stop: Block | null) => Stmt[];
 }
@@ -29,7 +35,19 @@ export interface SwitchRecovery {
 }
 
 export function makeSwitchRecovery(deps: SwitchRecoverDeps): SwitchRecovery {
-  const { fn, defs, dom, ipdom, opBlock, isNamed, isCmpOpcode, switchAllowsNeqCase, expr, structureRegion } = deps;
+  const {
+    fn,
+    defs,
+    dom,
+    ipdom,
+    opBlock,
+    isNamed,
+    isCmpOpcode,
+    switchAllowsNeqCase,
+    emitsAnchoredWrite,
+    expr,
+    structureRegion,
+  } = deps;
 
   // --- Regime A: comparison-tree switch recovery ----------------------------------------------------
   // Every ambiguity declines. Four preconditions are enforced below, annotated PRE1..PRE4:
@@ -128,9 +146,9 @@ export function makeSwitchRecovery(deps: SwitchRecoverDeps): SwitchRecovery {
     if (!cmp || !isCmpOpcode(cmp.opcode)) {
       return null;
     }
-    if (!isRoot && blk.ops.some((op) => SIDE_EFFECTFUL.has(op.opcode))) {
+    if (!isRoot && (blk.ops.some((op) => SIDE_EFFECTFUL.has(op.opcode)) || emitsAnchoredWrite(blk))) {
       return null;
-    } // PRE4
+    } // PRE4 — anchored writes included: discarded with the block, while their edge copies stay suppressed
     // Which operand is the scrutinee, which is the constant?
     const [lo, ro] = cmp.operands;
     const lc = evalConst(lo),

package/src/symbols.ts

@@ -52,6 +52,17 @@ export interface SymbolStructField {
   /** ARRAY field only: the element count (absent for a flexible array member, which declares a
    *  stride but no bound) — types the synthesized `T name[n];` field decl */
   length?: number;
+  /** BITFIELD field only: the field's width in BITS. Its PRESENCE is what marks a field a
+   *  bitfield — `size` above stays the byte span its bits touch (the read width the compiler
+   *  uses), which is why the exact (offset,size) scalar-field rules must exclude it. The
+   *  provider only emits these for LITTLE-ENDIAN ELFs: both the extract equation the access
+   *  recognizer solves and the `u32 name : n` layout model the synthesis verifies are LE-GCC
+   *  semantics, so a big-endian map carries no bitfield members at all (today's behavior). */
+  bitWidth?: number;
+  /** BITFIELD field only: the bit position of the field's LOW bit within the byte at `offset`
+   *  (LSB-first) — the field's absolute low bit is `offset*8 + bitOffset`. Required alongside
+   *  `bitWidth`; a bitfield missing it is malformed and declines the whole layout. */
+  bitOffset?: number;
 }
 
 /** What a `shape:'pointer'` global POINTS AT, when the sidecar says its target is a struct/union.
@@ -118,6 +129,15 @@ export interface SymbolInfo {
   elemSize?: number;
   /** element signedness for `shape:'array'` (default unsigned) — types the env entry */
   elemSigned?: boolean;
+  /** ARRAY RANK for `shape:'array'` — the per-dimension extents, outermost first (`u16
+   *  g[4][0x400]` → `[4, 1024]`), `null` for an unbounded one. It is NOT `size`/`elemSize`
+   *  restated: those size the object, this says how many subscripts reach an ELEMENT. `gSym[i]`
+   *  on a rank-2 array is a ROW — against the project's own header that is a type error, or,
+   *  where the row address flows into an integer context, silently the wrong address. So the
+   *  bare spelling needs the leading subscripts (`gSym[0][i]`), and its ABSENCE is what forbids
+   *  the bare spelling from being attempted at all (see the provider's dims capability gate:
+   *  a package that cannot report rank must not be read as "rank 1"). */
+  dims?: (number | null)[];
   /** the real struct tag for `shape:'struct'` — names the synthesized struct declaration
    *  (absent ⇒ synthesis mints a placeholder tag; the tag is codegen-arbitrary) */
   structName?: string;
@@ -145,6 +165,33 @@ export interface SymbolInfo {
   macroBody?: string;
 }
 
+/** THE one reading of {@link SymbolInfo.dims} for spelling C, shared by the access side
+ *  (structure.ts's bare-name gate) and the declaration side (declare.ts) so the two cannot
+ *  disagree about an array's shape.
+ *
+ *  Returns the INNER extents — every dimension but the outermost. The outermost is excluded
+ *  because C lets a declaration omit it, and the inner ones are exactly what scales a leading
+ *  subscript. `[]` is the rank-1 answer: one subscript, `extern T gSym[];`, the spelling this has
+ *  always had.
+ *
+ *  An ABSENT `dims` also reads as rank 1, because that is what the author of such a map said: the
+ *  ELF provider's capability gate refuses a @gba-kit/debug-info that cannot report rank, so
+ *  absence here can only come from a hand-written map whose `shape:'array'` states a plain array.
+ *  Absence never means "the package could not say" — that case fails loudly at load.
+ *
+ *  Null means NO consistent pair is available (a stated rank with an unknown inner extent, which
+ *  neither a declaration nor a subscript can spell). Both sides honour it the same way: the access
+ *  falls back to `((T *)&gSym)[i]`, the declaration to the flat `extern T gSym[];` — valid
+ *  together under whatever the project's own header says. */
+export function arrayInnerExtents(info: SymbolInfo): number[] | null {
+  const dims = info.shape === 'array' ? info.dims : undefined;
+  if (dims === undefined || dims.length <= 1) {
+    return [];
+  }
+  const inner = dims.slice(1);
+  return inner.every((d) => typeof d === 'number' && d > 0) ? (inner as number[]) : null;
+}
+
 /** address → symbols at that address; `[0]` is the provider's canonical pick. */
 export type SymbolMap = Map<number, SymbolInfo[]>;
 
@@ -155,6 +202,13 @@ export function isArrayField(f: SymbolStructField): boolean {
   return f.elemSize !== undefined;
 }
 
+/** THE one test for "is this field a bitfield" — the PRESENCE of `bitWidth` (see the field doc).
+ *  The exact (offset,size) scalar-field rules must exclude these: a 7-bit field whose bits span
+ *  2 bytes carries `size: 2` and would otherwise match a plain u16 read at its offset. */
+export function isBitfieldField(f: SymbolStructField): boolean {
+  return f.bitWidth !== undefined;
+}
+
 /** A layout member that {@link declaredFields} passed: sizable, and seated at an offset no
  *  earlier member already covers. */
 export type DeclaredField = SymbolStructField & { size: number };
@@ -166,12 +220,30 @@ function wellFormedField(f: unknown): f is SymbolStructField {
     return false;
   }
   const m = f as Partial<SymbolStructField>;
-  return (
-    typeof m.name === 'string' &&
-    typeof m.offset === 'number' &&
-    Number.isFinite(m.offset) &&
-    (m.size === null || (typeof m.size === 'number' && Number.isFinite(m.size) && m.size >= 0))
-  );
+  if (
+    typeof m.name !== 'string' ||
+    typeof m.offset !== 'number' ||
+    !Number.isFinite(m.offset) ||
+    !(m.size === null || (typeof m.size === 'number' && Number.isFinite(m.size) && m.size >= 0))
+  ) {
+    return false;
+  }
+  // A bitfield's two facts must be present TOGETHER and internally consistent — a bitWidth with
+  // no bitOffset (or bits outside the byte span `size` claims) leaves the field unseatable, so
+  // the member is malformed and the layout declines whole like any other malformed member.
+  if (m.bitWidth !== undefined) {
+    return (
+      typeof m.bitWidth === 'number' &&
+      Number.isInteger(m.bitWidth) &&
+      m.bitWidth > 0 &&
+      typeof m.bitOffset === 'number' &&
+      Number.isInteger(m.bitOffset) &&
+      m.bitOffset >= 0 &&
+      typeof m.size === 'number' &&
+      m.bitOffset + m.bitWidth <= m.size * 8
+    );
+  }
+  return true;
 }
 
 /**
@@ -202,15 +274,33 @@ export function declaredFields(layout: SymbolStructField[] | undefined): Declare
       return null;
     }
   }
-  const members = (layout as DeclaredField[]).slice().sort((a, b) => a.offset - b.offset);
+  // The cursor is in BITS so co-located bitfields seat correctly: `u32 a:2; u32 b:3;` are two
+  // members at byte offset 0, not a union alias. For plain members the arithmetic is the old
+  // byte cursor times 8 — behavior-identical for every bitfield-free layout.
+  const lowBitOf = (m: DeclaredField): number => m.offset * 8 + (m.bitWidth !== undefined ? m.bitOffset! : 0);
+  const members = (layout as DeclaredField[])
+    .slice()
+    .sort((a, b) => lowBitOf(a) - lowBitOf(b) || (a.bitWidth ?? -1) - (b.bitWidth ?? -1));
   const out: DeclaredField[] = [];
-  let cursor = 0;
+  let bitCursor = 0;
   for (const m of members) {
-    if (m.offset < cursor) {
+    const lo = lowBitOf(m);
+    if (lo < bitCursor) {
       continue; // an overlapping (union) member: the first view is declared, the alias is not
     }
-    out.push(m);
-    cursor = m.offset + m.size;
+    if (m.bitWidth !== undefined) {
+      // The synthesis lays bitfields as LE-GCC `u32 name : n`, whose allocation never straddles
+      // a 32-bit unit — a field that would cannot be reproduced, so it is not declared (its bits
+      // pad instead) and no access may name it. The cursor does NOT advance: the bits stay a hole.
+      if (Math.floor(lo / 32) !== Math.floor((lo + m.bitWidth - 1) / 32)) {
+        continue;
+      }
+      out.push(m);
+      bitCursor = lo + m.bitWidth;
+    } else {
+      out.push(m);
+      bitCursor = (m.offset + m.size) * 8;
+    }
   }
   return out;
 }
@@ -247,14 +337,39 @@ export function symbolFieldType(f: DeclaredField): IrType {
     const scalarPointee = f.pointeeSize === 1 || f.pointeeSize === 2 || f.pointeeSize === 4;
     return T.ptr(scalarPointee ? T.int(f.pointeeSize! * 8, f.pointeeSigned ?? false) : T.void());
   }
-  if (f.size === 1 || f.size === 2 || f.size === 4) {
-    return T.int(f.size * 8, f.signed ?? (f.size === 4 ? ENUM_IS_SIGNED : false));
+  if (isBitfieldField(f)) {
+    // The BASE type of the synthesized `u32 name : n` — the `: n` itself is the declaration
+    // renderer's job (StructFieldDecl.bits). 32-bit base always: that is the LE-GCC unit model
+    // declaredFields verified the layout against. A signless bitfield declares unsigned — the
+    // extract recognizer refuses to NAME one anyway, so the choice only types padding.
+    return T.int(32, f.signed ?? false);
+  }
+  if (isScalarCellSize(f.size)) {
+    return scalarCellType(f.size, f.signed);
   }
   return T.array(T.u(8), f.size);
 }
 /** A 4-byte member/scalar with NO base-type signedness is the enum idiom — C89 says int. */
 export const ENUM_IS_SIGNED = true;
 
+/** Is this byte size one a base type can spell? */
+export function isScalarCellSize(size: number | undefined): size is 1 | 2 | 4 {
+  return size === 1 || size === 2 || size === 4;
+}
+
+/** THE DECLARED type of a 1/2/4-byte scalar cell — what `extern T gSym;` synthesis writes, and
+ *  therefore what `&gSym` actually points to.
+ *
+ *  Extracted because this rule had drifted into a fourth copy. It is NOT `scalarTypeForAccess`,
+ *  which answers a different question — the type an ACCESS of that width reads — and collapses
+ *  every 4-byte access to `s32` whatever the signedness. Using that one to decide "does `&gSym`
+ *  already have the destination's type" silently answered YES for a `u32` cell reaching an
+ *  `s32 *`, and the incompatible-pointer assignment survived. Declaration side and access side are
+ *  separate facts; this is the declaration one. */
+export function scalarCellType(size: 1 | 2 | 4, signed: boolean | undefined): IrType {
+  return T.int(size * 8, signed ?? (size === 4 ? ENUM_IS_SIGNED : false));
+}
+
 /**
  * THE gate on every spelling through a POINTER global's value: the members a `gPtr->member`
  * spelling may name, or null when nothing may be named through this pointee at all. Null unless

package/src/target.ts

@@ -34,7 +34,7 @@ export interface TargetDescription {
   returnReg: string;
   // HARDWARE / ISA facts — independent of the compiler.
   capabilities: {
-    endianness: 'little' | 'big'; // RESERVED — no pass reads it yet (byte-addressing will)
+    endianness: 'little' | 'big'; // consumed by structureOptionsFor (bitfield extract recognition is LSB-first)
     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)
@@ -132,7 +132,9 @@ export const PPC_MWCC: TargetDescription = {
  *  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 };
+  // `littleEndian` is the one HARDWARE capability the structurer consumes (bitfield extract
+  // recognition is LSB-first); everything else is a compiler behavior.
+  return { returnsVoid, littleEndian: t.capabilities.endianness === 'little', ...t.compilerBehaviors };
 }
 
 export const C_TYPEDEFS =

package/src/trace.ts

@@ -72,12 +72,21 @@ export interface TraceOptions {
 // (not in pre-recovery.ts) because these strings are a trace concern — the driver itself is
 // trace-agnostic. `title` is a function so `arrays` can fold its scaled-access count in.
 const PRE_RECOVERY_TRACE: Record<string, { stage: string; title: (result: number | boolean) => string }> = {
+  addrnum: {
+    stage: 'stage:addrnum',
+    title: (r) => `Address numbering (${r} duplicate address def(s) / trivial phi(s) collapsed)`,
+  },
   const: { stage: 'stage:const', title: () => 'Const materialize (lui;ori → one 32-bit const)' },
   magicdiv: { stage: 'stage:magicdiv', title: () => 'Magic-number division recovery (mulh/mulhu → sdiv/udiv)' },
   softdiv: { stage: 'stage:softdiv', title: () => 'Soft-division lower (bl __divsi3 → division op)' },
   arrays: { stage: 'stage:legalize', title: (r) => `Array legalize (${r} scaled access(es) → aload/astore)` },
   structs: { stage: 'stage:structs', title: () => 'Struct-pointer recovery (access-pattern evidence)' },
   shortcircuit: { stage: 'stage:shortcircuit', title: () => 'Short-circuit recovery (boolean && / ||)' },
+  'branch-shortcircuit': {
+    stage: 'stage:branch-shortcircuit',
+    title: () => 'Short-circuit recovery (control-flow && / ||)',
+  },
+  'struct-arrays': { stage: 'stage:struct-arrays', title: () => 'Struct-array recovery (element stride evidence)' },
 };
 
 /** Run the tower while recording a TraceReport. Strict mode throws on any gap (like decompile);