@asmlift/core 0.6.0 → 0.7.0

package/src/structure/switch-recover.ts

@@ -23,6 +23,12 @@ export interface SwitchRecoverDeps {
   switchAllowsBoundCase: boolean;
   /** emit the case arms in the ASSEMBLY's block-layout order rather than by ascending case value */
   switchArmsFollowLayout: boolean;
+  /** DECLINE a recovered tree whose own layout INTERLEAVES a test with a case body. A source
+   *  `switch` front-loads its whole dispatch ahead of every arm body; an if/else-if LADDER emits
+   *  each test directly above its own body. See StructureOptions for the compiled evidence, for
+   *  the frontend premise this shares with `switchArmsFollowLayout`, and for what the decline
+   *  costs when it is wrong. */
+  switchRequiresFrontLoadedTests: boolean;
   /** may the emitted SOURCE say "this arm runs on into the next one"? False for a language whose
    *  `case` cannot fall through (Pascal), and then Regime A declines a falling arm to if-recovery
    *  — the behaviourally identical recovery that backend CAN print. See StructureOptions. */
@@ -247,6 +253,7 @@ export function makeSwitchRecovery(deps: SwitchRecoverDeps): SwitchRecovery {
     switchAllowsNeqCase,
     switchAllowsBoundCase,
     switchArmsFollowLayout,
+    switchRequiresFrontLoadedTests,
     spellSwitchFallthrough,
     emitsOwnStatement,
     blockOf,
@@ -255,17 +262,25 @@ export function makeSwitchRecovery(deps: SwitchRecoverDeps): SwitchRecovery {
     structureRegion,
   } = deps;
 
-  // A block's index in `fn.blocks` as its position in the ASSEMBLY — the sole warrant for reading a
-  // source's arm order off block indices below, and true PER FRONTEND rather than of the IR:
+  // A block's index in `fn.blocks` as its position in the ASSEMBLY — the warrant for every reading
+  // of layout below, and true PER FRONTEND rather than of the IR:
   //   - thumb.ts and mips.ts build the list by scanning the instruction stream in address order;
   //   - ppc.ts does not. It APPENDS a synthetic return block (`synthReturn`) at the end of the list
   //     for every conditional-return branch, wherever in the stream that branch sits, so its list
   //     is not address order at all;
   //   - raising only ever REMOVES blocks from the list (raise/{divpow2,latch,retsink,shortcircuit}
   //     .ts all `filter`), never inserts or reorders, so the frontend's order is what survives.
-  // `switchArmsFollowLayout` is therefore a claim about a target's FRONTEND as much as about its
-  // compiler, and a target opts in on both — which is why PPC_MWCC, whose frontend fails the first
-  // half, does not.
+  // TWO READERS, both target-gated, and they need DIFFERENT strengths of the compiler half:
+  //   - `switchArmsFollowLayout` (arm ORDER, the sort below) needs the full claim — no block moved
+  //     at all — because it PLACES the arms from the layout;
+  //   - `switchRequiresFrontLoadedTests` (PRE5, whether to recover at all) needs only that no case
+  //     BODY was moved above a dispatch test, which a compiler with a scheduler can still satisfy;
+  //     `MIPS_GCC` declares `switchRequiresFrontLoadedTests` and NOT `switchArmsFollowLayout` for
+  //     exactly that reason — it has a scheduler and fills delay slots (target.ts).
+  // Both are therefore claims about a target's FRONTEND as much as about its compiler, and a target
+  // opts in on both halves — which is why PPC_MWCC, whose frontend fails the frontend half outright,
+  // declares neither. Anything added below that reads `layoutIndex` inherits the frontend half and
+  // owes a statement of which strength of the compiler half it needs.
   const blockIndex = new Map(fn.blocks.map((blk, i) => [blk, i] as const));
   const layoutIndex = (blk: Block): number => blockIndex.get(blk) ?? -1;
 
@@ -336,9 +351,10 @@ export function makeSwitchRecovery(deps: SwitchRecoverDeps): SwitchRecovery {
   };
 
   // --- Regime A: comparison-tree switch recovery ----------------------------------------------------
-  // Every ambiguity declines. Four preconditions are enforced below, annotated PRE1..PRE4:
+  // Every ambiguity declines. Five preconditions are enforced below, annotated PRE1..PRE5:
   // scrutinee identity/dominance, ARM EXITS (per site: `break`, `fallthrough` — which `chainArms`
-  // then places — or a decline), concrete interval consistency, test purity.
+  // then places — or a decline), concrete interval consistency, test purity, and — where the target
+  // has declared that its layout answers it — which SPELLING the source wrote.
 
   // 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.
@@ -772,6 +788,83 @@ export function makeSwitchRecovery(deps: SwitchRecoverDeps): SwitchRecovery {
       }
     }
 
+    // PRE5 (WHICH SPELLING THE SOURCE WROTE), per SITE, and only where the caller has declared
+    // that the layout answers it. Everything above establishes that this tree CAN be spelled as a
+    // `switch`; this asks whether it WAS. The two spellings are different objects, not one object
+    // two ways: a source `switch` front-loads its whole dispatch ahead of every arm body (agbcc's
+    // `expand_end_case` closes with a `reorder_insns` that moves the dispatch in front of the
+    // bodies expanded before it — the same sources `switchArmsFollowLayout` is read off), while an
+    // if/else-if ladder emits each test directly above the body it guards. So a test block laid
+    // out AFTER a case body cannot have come from a source `switch`, and recovering one here spells
+    // a ladder as a `switch` with no dual anywhere in the fan for a differ to prefer.
+    //
+    // READ PER SITE, off THIS recovery's own blocks, never off the function. A function holding a
+    // ladder and a real `switch` must keep both readings, and a function-wide OR would collapse
+    // them into one boolean and be wrong on one site by construction.
+    //
+    // WHAT IT REFUSES TO DO. The reading runs BACKWARDS, from emission to spelling, so it inherits
+    // `layoutIndex`'s premise (above) at the weaker of the two strengths stated there. A frontend
+    // or compiler that breaks it can hand this a front-loaded layout for a ladder, and then the
+    // gate simply does not fire. The converse error, a real `switch` whose layout interleaves,
+    // costs only the `switch` SPELLING: the recovery declines to if-recovery, behaviourally
+    // identical (the file header) and scored by the differ. This gate can lose a match; it can
+    // never produce a wrong answer.
+    //
+    // WHAT THE DECLINE PRODUCES, AND IT IS NOT ALWAYS A CLEAN LADDER. Recovery is RECURSIVE:
+    // declining a tree here hands the tree back to if-recovery, which then runs recovery AGAIN on
+    // each sub-tree it structures. On a flat tree that is a ladder over every case value. On a
+    // NESTED tree it is not: `corpus/agbcc-swnested.s` (a source `switch` nested inside an
+    // if/else-if ladder) declines HERE on the outer tree — correctly, the ladder arm's body really
+    // does sit between the tests — and the sub-tree then re-recovers, so the emitted C is an `if`
+    // nest holding a `switch` over a STRICT SUBSET of the source's case labels. Still behaviourally
+    // identical, and no worse than the alternative (with the reading withdrawn that same function
+    // comes back as one `switch` merging two arms the source wrote apart), but it is a THIRD
+    // spelling that neither reading would give, and nothing in the output says a dispatch was
+    // half-declined: "the decline is a clean ladder" holds at the OUTERMOST tree only. Pinned by
+    // the test "PRE5 declines a tree RECURSIVELY" on the committed fixture.
+    //
+    // WHAT THE POSITIONS ARE READ THROUGH, which is the premise that lives inside asmlift rather
+    // than in the compiler. `caseBlocks` holds `forwardingTarget` results (`asCase` is called on the
+    // resolved block), so an arm whose body is a bare jump contributes ITS TARGET's position, not
+    // its own. A forwarding target laid out ABOVE the dispatch would then read as a body above a
+    // test and decline a real `switch`.
+    //
+    // WHY THAT HAS NO INHABITANT IS MEASURED, NOT ARGUED. Two arguments that look like proofs are
+    // not: "the block is reached by a back edge" needs the block to DOMINATE the dispatch, which an
+    // `if` arm ahead of the `switch` does not, and a cross-jumped arm tail reaches it on an
+    // ordinary forward edge; "this flag's targets reorder nothing" is false — `MIPS_GCC` declares
+    // it WITH a scheduler, on the half-premise stated at `layoutIndex` above. Measured: across 28
+    // compiled probes on agbcc, gcc2.7.2 -O1 and gcc2.7.2kmc -O2 — arms cross-jumped onto a shared
+    // tail ahead of the dispatch, `goto`s out of an arm to a label above it, shared early returns,
+    // `continue`/`break` out of a switch inside a loop — no toolchain placed an arm's forwarding
+    // target above its own dispatch: every firing came back with zero bodies above the first test.
+    // Safe because no compiler in the corpus emits that shape, not because none can; whoever makes
+    // one — a new frontend, a relaxed loop recovery, a scheduler that hoists a merged tail —
+    // inherits this reader.
+    //
+    // `bodyPos` covers the CASE bodies only. `defaultBlk` is left out deliberately: it can be the
+    // dispatch's own fall-out block rather than an arm the source wrote (the W2/W4 withholdings
+    // above), so its position is one the source never chose. Both omissions can only make the gate
+    // UNDER-fire, i.e. keep a `switch`, which is the safe direction.
+    //
+    // AND THE READING REFUSES ITSELF where it has nothing to read. `layoutIndex` answers `-1` for a
+    // block absent from `fn.blocks`, which is not a position — taken as one it sorts below every
+    // real body and declines the tree holding it. That state has no inhabitant and cannot get one
+    // without a bug upstream: `ir/verify.ts` rejects a successor that is not a block of the fn and
+    // the tower runs it after the lift and after every raising pass, and `predecessorBlocks` throws
+    // by name on the same state near the top of `structure()`. So this is belt-and-braces over a
+    // VERIFIER BUG, not over an expected shape — kept because standing down costs nothing. Its test
+    // pins the UNREACHABILITY (both throws fire first); the `placed` branch itself stays
+    // unexecuted, and cannot be covered without breaking one of those two invariants.
+    if (switchRequiresFrontLoadedTests) {
+      const testPos = [...seen].map(layoutIndex);
+      const bodyPos = [...caseBlocks].map(layoutIndex);
+      const placed = [...testPos, ...bodyPos].every((i) => i >= 0);
+      if (placed && Math.max(...testPos) > Math.min(...bodyPos)) {
+        return null;
+      }
+    }
+
     // ARM ORDER. The case values are disjoint (PRE3), so where no arm falls through the order
     // carries no meaning and is pure matching evidence: ascending case VALUE is the neutral
     // spelling, and where a compiler has declared `switchArmsFollowLayout` the layout of the bodies

package/src/symbols.ts

@@ -52,9 +52,30 @@ 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;
+  /** ARRAY field only: the RANK — the per-dimension extents, outermost first (`u8 x[6][8]` →
+   *  `[6, 8]`), `null` for an unbounded one. {@link SymbolInfo.dims}'s law, one indirection down,
+   *  and for the same reason: `length` is the PRODUCT of the dimensions, so it cannot say how many
+   *  subscripts reach an ELEMENT. `->x[i]` on a `[6][8]` member is a ROW, and 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.
+   *
+   *  ABSENCE READS DIFFERENTLY HERE THAN IT DOES FOR A GLOBAL, and the difference is the whole
+   *  point of the field. {@link arrayInnerExtents} may read an absent `SymbolInfo.dims` as rank 1
+   *  because the ELF provider's capability gate refuses a @gba-kit/debug-info that cannot report
+   *  a global's rank. No such gate covers a MEMBER's rank — a member simply omits the key both
+   *  when the DWARF carries no subranges and when the package is too old to look — so absence
+   *  here means "the map could not say". A consumer that must type-check against a FOREIGN
+   *  declaration (the indexed member spelling, structure.ts's `pointeeElement`) refuses on
+   *  absence; a consumer synthesizing its OWN declaration may still flatten, because its access
+   *  and its declaration then agree by construction. That is why {@link structFieldInnerExtents}
+   *  answers `[]` for absence and the refusal lives at the access site instead. */
+  dims?: (number | null)[];
   /** 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
+   *  bitfield — `size` above stays the byte SPAN its bits touch, which is why the exact
+   *  (offset,size) scalar-field rules must exclude it. The span is NOT the access the compiler
+   *  uses: measured with the pinned agbcc, `u32 x : 8` at bit 12 spans 2 bytes and is reached by
+   *  a WORD, `u32 a : 20` spans 3, and `u16 a : 2` spans 1 in a 2-byte container. A consumer
+   *  needing the access width computes it from `bitOffset`/`bitWidth` (structure/bitfields.ts). 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). */
@@ -95,7 +116,7 @@ export interface SymbolPointee {
  *  NO POINTEE, and the absence is UPSTREAM's rather than a shape asmlift dropped:
  *  `@gba-kit/debug-info`'s `TypeFacts` — what a `FunctionSignature`'s params are made of — is
  *  exactly these three fields. {@link SymbolInfo.pointee} exists only for a symbol AT AN ADDRESS.
- *  Widening this is priced in docs/level-tower.md and pinned in test/param-pointee-axis.test.ts. */
+ *  Widening this is priced in docs/level-tower.md and pinned in test/param-pointee-variation.test.ts. */
 export interface SymbolTypeFacts {
   size: number | null;
   signed: boolean | null;
@@ -197,6 +218,28 @@ export function arrayInnerExtents(info: SymbolInfo): number[] | null {
   return inner.every((d) => typeof d === 'number' && d > 0) ? (inner as number[]) : null;
 }
 
+/** {@link arrayInnerExtents}, one indirection down: the INNER extents of an array MEMBER, shared
+ *  by the access side (structure.ts's indexed member spelling) and the declaration side
+ *  (symbolFieldType) so the two cannot disagree about a member's shape.
+ *
+ *  `[]` is the rank-1 answer — one subscript, `u8 x[48];`, the spelling every map has had. It is
+ *  ALSO what an absent `dims` answers, because the declaration synthesis that reads this renders
+ *  the member itself and so cannot be wrong about it. A consumer type-checking against a header it
+ *  did NOT write must test `f.dims === undefined` first and decline; see {@link
+ *  SymbolStructField.dims} for why that asymmetry is real rather than a shortcut.
+ *
+ *  Null means NO consistent pair is available (a stated rank with an unknown or non-positive inner
+ *  extent, which neither a declaration nor a subscript can spell), and both sides honour it the
+ *  same way: the declaration falls back to the flat member, the access to the cast form. */
+export function structFieldInnerExtents(f: SymbolStructField): number[] | null {
+  const dims = isArrayField(f) ? f.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[]>;
 
@@ -225,6 +268,13 @@ export function isBitfieldField(f: SymbolStructField): boolean {
   return f.bitWidth !== undefined;
 }
 
+/** Does the map declare a bitfield member anywhere, in a symbol's own layout or its pointee's? */
+export function declaresBitfields(symbols: SymbolMap): boolean {
+  return [...symbols.values()].some((infos) =>
+    infos.some((i) => [...(i.layout ?? []), ...(i.pointee?.layout ?? [])].some(isBitfieldField)),
+  );
+}
+
 /** A layout member that {@link declaredFields} passed: sizable, and seated at an offset no
  *  earlier member already covers. */
 export type DeclaredField = SymbolStructField & { size: number };
@@ -244,6 +294,31 @@ function wellFormedField(f: unknown): f is SymbolStructField {
   ) {
     return false;
   }
+  // `dims`, when stated, must be an array of positive extents or nulls whose product is the
+  // member's own `length` — three facts that contradict each other cannot all be trusted, exactly
+  // as `elemSize * length !== size` declines the layout below. A member with no `elemSize` is not
+  // an array and may not carry a rank at all.
+  if (m.dims !== undefined) {
+    if (
+      !Array.isArray(m.dims) ||
+      m.dims.length === 0 ||
+      m.elemSize === undefined ||
+      !m.dims.every((d) => d === null || (typeof d === 'number' && Number.isInteger(d) && d > 0))
+    ) {
+      return false;
+    }
+    // The product test has to hold over the NUMERIC extents alone, not only when every extent is
+    // numeric. A partly-null rank still constrains `length`: `[null, 5]` says the member's
+    // elements come in rows of five, so a `length` of 48 contradicts it exactly as `[6, 9]` and 48
+    // do — and symbolFieldType, which recovers a missing outer extent as `length / prod(inner)`,
+    // would spell that pair `u8 grid[9.6][5];`. A non-integral quotient is not a spelling defect
+    // to patch downstream: it is the same three-facts-disagree malformation, declined here.
+    const numeric = (m.dims as (number | null)[]).filter((d): d is number => typeof d === 'number');
+    const stated = numeric.reduce((a, b) => a * b, 1);
+    if (m.length !== undefined && (numeric.length === m.dims.length ? stated !== m.length : m.length % stated !== 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.
@@ -341,9 +416,29 @@ export function declaredFields(layout: SymbolStructField[] | undefined): Declare
 export function symbolFieldType(f: DeclaredField): IrType {
   if (isArrayField(f)) {
     const scalarElem = f.elemSigned !== undefined && (f.elemSize === 1 || f.elemSize === 2 || f.elemSize === 4);
-    return scalarElem && f.length !== undefined && f.elemSize! * f.length === f.size
-      ? T.array(T.int(f.elemSize! * 8, f.elemSigned!), f.length)
-      : T.array(T.u(8), f.size);
+    if (!(scalarElem && f.length !== undefined && f.elemSize! * f.length === f.size)) {
+      return T.array(T.u(8), f.size);
+    }
+    // The declared RANK, when the map states one: `u8 x[6][8]` rather than `u8 x[48]`. Same
+    // object and same size either way — but a foreign header declares the member ONE of those two
+    // ways, and an access spelled against the other does not type-check (see
+    // SymbolStructField.dims). An unspellable rank (null) keeps the flat member.
+    //
+    // The outer extent is RECOVERED as `length / prod(inner)` — the map may leave the outermost
+    // subrange null where it knows the total. wellFormedField already declines a `length` the
+    // inner extents do not divide, so the quotient is a whole number for any layout that reached
+    // here; it is re-checked rather than assumed because this function is exported and a
+    // fractional extent prints `u8 grid[9.6][5];`, which is not C. The flat member is the honest
+    // fallback, the same one an unspellable inner extent takes.
+    const inner = structFieldInnerExtents(f);
+    const elem = T.int(f.elemSize! * 8, f.elemSigned!);
+    if (inner === null || inner.length === 0) {
+      return T.array(elem, f.length);
+    }
+    const outer = f.length / inner.reduce((a, b) => a * b, 1);
+    return Number.isInteger(outer) && outer > 0
+      ? [outer, ...inner].reverse().reduce<IrType>((t, n) => T.array(t, n), elem)
+      : T.array(elem, f.length);
   }
   if (f.pointer && f.size === 4) {
     // The pointee width is byte-load-bearing: arithmetic on the loaded pointer scales by it, so
@@ -365,6 +460,32 @@ export function symbolFieldType(f: DeclaredField): IrType {
   }
   return T.array(T.u(8), f.size);
 }
+
+/** The array shape the DECLARATION actually spells for a member — the extents outermost first and
+ *  the element type left at the bottom — read back out of {@link symbolFieldType} rather than
+ *  re-derived from the map's own facts. It answers whatever that declaration is, which for a
+ *  member with no spellable element type is the flat `u8 name[size]`: extents `[size]` over `u8`,
+ *  not the empty shape.
+ *
+ *  Exists because "how many subscripts does this member take, and of what" was being answered
+ *  twice: once here (which needs `length` and a base-type `elemSigned`, and declares the flat byte
+ *  array without either) and once straight off `dims` at the access site. `dims` and `length` are
+ *  INDEPENDENT facts — a flexible array member states a stride and no bound (see
+ *  SymbolStructField.length), and a member whose OUTERMOST subrange is unbounded (`u8 data[][8]`,
+ *  legal C) reaches a map as `dims: [null, 8]` with no `length` at all. The declaration then spells
+ *  `u8 grid[48];` while an access reading the rank off `dims` spells `gPtr->grid[0][a0];`, which is
+ *  not C (`subscripted value is not an array, pointer, or vector`). An access side that asks THIS
+ *  question cannot diverge from the declaration whatever gate symbolFieldType grows next. */
+export function declaredArrayShape(f: DeclaredField): { extents: number[]; elem: IrType } {
+  let t = symbolFieldType(f);
+  const extents: number[] = [];
+  while (t.kind === 'array') {
+    extents.push(t.count);
+    t = t.elem;
+  }
+  return { extents, elem: t };
+}
+
 /** A 4-byte member/scalar with NO base-type signedness is the enum idiom — C89 says int. */
 export const ENUM_IS_SIGNED = true;