@asmlift/core 0.5.0 → 0.7.0

package/src/pipeline.ts

@@ -5,28 +5,32 @@ import {
   ContractError,
   assertDerefsTyped,
   assertEffectsPreserved,
+  assertLocalsWritten,
   assertResolved,
   assertTypesRecovered,
 } from './contracts';
 import type { AsmData } from './frontend/asmdata';
 import { FrontendUnsupportedError } from './frontend/errors';
 import { frontendFor } from './frontend/registry';
-import { type Block, type Fn, successorsOf } from './ir/core';
+import { type Fn, reachableBlocks } from './ir/core';
 import { print } from './ir/print';
+import { firstTrivialPhi } from './ir/simplify';
 import { T } from './ir/types';
 import { VerifyError, verify } from './ir/verify';
-import { Expr, LanguageBackend, SFn, Stmt, exprChildren, gapReasonFor, stmtChildren, stmtExprs } from './l3/ast';
-import { hoistReusedGlobalBases } from './l3/basecse';
+import { LanguageBackend, SFn, gapReasonFor, walkExprs } from './l3/ast';
+import { BASECSE_GATES, hoistBaseLocals } from './l3/basecse';
 import { eliminateDeadStores } from './l3/dce';
 import { mergeCommonTails } from './l3/tailmerge';
 import { DEFAULT_IDIOM_PATTERNS, RewritePattern, applyPattern, dce, patternApplies } from './pattern/engine';
-import { type Prototypes, prototypesFromSymbols } from './proto';
+import { type FnProto, type Prototypes, prototypesFromSymbols } from './proto';
 import { RaiseUnsupportedError } from './raise/errors';
-import { type PreRecoveryPass, runPreRecovery } from './raise/pre-recovery';
+import { assumedShapes, inferGlobalArrays, orderLicensedGlobals } from './raise/globalshape';
+import { foldEmptyLatches } from './raise/latch';
+import { type PreRecoveryOptions, type PreRecoveryPass, runPreRecovery } from './raise/pre-recovery';
 import { recoverTypes } from './raise/recover';
 import { sinkReturns } from './raise/retsink';
 import { StructureError, structure } from './structure/structure';
-import { type SymbolMap, symbolsByName } from './symbols';
+import { type SymbolInfo, type SymbolMap, symbolsByName } from './symbols';
 import { type TargetDescription, structureOptionsFor } from './target';
 
 /** How a gap (a construct asmlift cannot faithfully model) degrades:
@@ -74,10 +78,36 @@ export interface DecompileResult {
   sfn: SFn;
   ir: { raw: string; folded: string; recovered: string }; // IR dumps: post-lift, post-idiom, post-recovery
   patternHits: number;
-  /** structured gap list — ALWAYS present; empty ⇔ the emission is gap-free (compiles + candidate
-   *  for scoring). Non-empty ⇔ the source contains ASMLIFT_ERROR markers / a stub and will NOT
-   *  compile until the user defines that symbol (the loud-in-artifact contract). */
+  /** structured gap list — ALWAYS present. Non-empty ⇔ the source contains ASMLIFT_ERROR markers /
+   *  a stub and will NOT compile until the user acts (the loud-in-artifact contract).
+   *
+   *  EMPTY IS THE ABSENCE OF A GAP, NOT A PROMISE THAT THE C COMPILES. A candidate can also fail
+   *  on a symbol the caller never declared, which is a CONTEXT question the benchmark answers by
+   *  escalating to the vendored preprocessed context. Most such names survive K&R implicit
+   *  declaration; a function ADDRESS does not, and klonoa's `UpdateStageSelectScreen` reports 0
+   *  gaps while emitting `((s32 *)50345232)[1] = &HandlePauseMenuInput;`, which agbcc rejects
+   *  where the plain call above it passes with a warning. Declaring an address-taken unknown
+   *  callee would close it — an emitter change, moving source bytes on every row that has one. */
   diagnostics: Diagnostic[];
+  /** THE SHAPES THIS SOURCE'S SPELLING ASSUMES, which no symbol map supplied (raise/globalshape.ts).
+   *
+   *  Everything else a backend emits is byte-correct under ANY declaration of the names it spells
+   *  — that is exactly why `((T *)&gSym)[i]` is the fallback (structure/globalaccess.ts). A bare
+   *  `gSym[i]` is not: it means what the DECLARATION of `gSym` says it means, and where that
+   *  declaration was derived from the assembly rather than read from the project's map, the
+   *  emitted source is right about the target's bytes only beside the declaration derived with it.
+   *  The element SIGNEDNESS is the sharp case, and it is an assumption rather than a reading:
+   *  compiled through the benchmark's own agbcc command, `(u16)gS[i]` over `extern const s16 gS[]`
+   *  and `gS[i]` over `extern const u16 gS[]` are the SAME OBJECT, so the assembly cannot say which
+   *  the source wrote — asmlift picks the one its own declaration block states.
+   *
+   *  So this travels with the source on every path that can emit it: the scoring layer renders it
+   *  (declare.ts, and main.ts's `[declared]` block), and a caller that shows the source alone must
+   *  show these too, or it is publishing a spelling whose meaning it has not stated. Empty on every
+   *  run that assumed nothing — which includes every derived shape the structurer did not spell
+   *  bare, and every name the caller's own map described (raise/globalshape.ts `assumedShapes`
+   *  computes that narrowing and names the corpus row behind each half). */
+  assumedSymbols: SymbolInfo[];
 }
 
 export function decompile(
@@ -115,39 +145,66 @@ function runTower(
   // (1) lift: ISA frontend (resolved by target) → L1 with block-argument SSA
   const fn = frontendFor(target).lift(name, asm, target, prototypes, opts.asmData, opts.symbols);
   verify(fn);
-  const raw = print(fn);
+  // Every dump carries the write-order record (ir/print.ts `PrintOptions`): it decides the
+  // edge-copy order and the raising folds mutate it, so two dumps compare whole program states.
+  const raw = print(fn, { writeOrder: true });
+  // (1.5) the ARRAY SHAPES this function's own assembly evidences, for globals the project map
+  // does not describe. Read HERE, off the lifted fn, because the fact it needs — whether the base
+  // was materialized before the index was scaled — is destroyed by the raising tower below
+  // (raise/globalshape.ts's module note). Empty unless the target opts in.
+  const inferredSymbols = inferGlobalArrays(fn, target);
+  // …and the ORDER half of the same reading, which reaches names the shape derivation refuses (a
+  // struct element among them). Read off the same lifted fn, for the same reason.
+  const orderLicensed = orderLicensedGlobals(fn, target);
 
   // (2) idiom fold: apply serializable patterns on the IR (the AI-improvement surface),
   // gated generically by the Target's capabilities (not an `arch ==` branch).
   const patternHits = applyIdiomPatterns(fn, target, opts.patterns);
-  const folded = print(fn);
+  const folded = print(fn, { writeOrder: true });
 
   // (2.35–3.5) pre-recovery recognizers → type recovery → return-sinking, the ONE shared spine
   // (`raiseRecovered`) that trace.ts and the cli's rank.ts/report.ts also run.
-  raiseRecovered(fn, target);
-  const recovered = print(fn);
+  raiseRecovered(fn, target, {}, prototypes[name]);
+  const recovered = print(fn, { writeOrder: true });
 
   // (4) structure: IR → neutral AST; boundary contract: no unresolved value leaked (strict), or
   // every unresolved value spelled as a loud ASMLIFT_ERROR marker (annotate).
+  const mapSymbols = opts.symbols ? symbolsByName(opts.symbols) : undefined;
   const sfn = structureChecked(fn, {
     ...structureOptionsFor(target, prototypes[name]?.returnsVoid ?? false),
+    // What the EMITTED LANGUAGE can say is a structuring input wherever two recoveries of one
+    // shape are behaviourally identical and only one of them is printable (switch fall-through
+    // vs plain if-nesting): recovery must not mint a tree this backend would refuse.
+    spellSwitchFallthrough: backend.spellsSwitchFallthrough,
     onGap,
-    ...(opts.symbols ? { symbols: symbolsByName(opts.symbols) } : {}),
+    ...(mapSymbols ? { symbols: mapSymbols } : {}),
+    ...(inferredSymbols.size ? { inferredSymbols } : {}),
+    ...(orderLicensed.size ? { orderLicensedGlobals: orderLicensed } : {}),
   });
 
   // (5) lower + print: neutral AST → target language
   const source = backend.emit(sfn);
 
-  return { source, sfn, ir: { raw, folded, recovered }, patternHits, diagnostics: collectMarkers(sfn) };
+  return {
+    source,
+    sfn,
+    ir: { raw, folded, recovered },
+    patternHits,
+    diagnostics: collectMarkers(sfn),
+    // WHAT THE SOURCE RESTS ON, not what the derivation found: a shape the structurer did not
+    // spell bare, and a name the caller's own map described, are both obligations this reader
+    // does not have (raise/globalshape.ts `assumedShapes`).
+    assumedSymbols: assumedShapes(inferredSymbols, sfn, mapSymbols),
+  };
 }
 
 // ── the shared raising tower ────────────────────────────────────────────────────────────────
-// decompile(), decompileTraced (trace.ts), and the cli's decompileRanked (rank.ts) /
-// decompileWithReport + its score probe (report.ts) all raise a lifted fn through the SAME
-// stage sequence. The optional hooks are the only per-caller
-// differences: rank pins its signedness candidate `beforeRecover`; the report pushes trace
-// entries after each stage. Every hook fires AFTER the stage's verify, so a hook can never
-// observe unverified IR.
+// decompile(), decompileTraced (trace.ts), rank.ts's decompileRanked and the cli's
+// decompileWithReport + its score probe (report.ts) all raise a lifted fn through the SAME stage
+// sequence. Two things vary per caller and nothing else does: the optional HOOKS — rank pins its
+// signedness candidate at `beforeRecover`, decompileTraced pushes a trace entry after each stage —
+// and the `pre` options bag, which reaches the pre-recovery passes themselves. Every hook fires
+// AFTER the stage's verify, so a hook can never observe unverified IR.
 
 /** Stage 2 — idiom fold: filter the pattern set by target capabilities, apply, dce + verify.
  *  Returns total hits. `patterns` defaults to DEFAULT_IDIOM_PATTERNS exactly like decompile(). */
@@ -173,26 +230,84 @@ export interface RaiseHooks {
   afterRecover?: () => void;
   /** after return-sinking, only when it changed the fn (fires after its verify) */
   afterRetsink?: () => void;
+  /** after empty-latch folding, only when it removed a block (fires after its verify) */
+  afterLatchFold?: () => void;
 }
 
 /** Stages 2.35–3.5 — pre-recovery recognizers (the shared ordered list in raise/pre-recovery.ts)
  *  → type recovery (boundary contract: no `unknown` survives) → return-sinking (tail-duplicate a
- *  return-only merge so short-circuits emit early returns). `verify` after every pass that
- *  changed the IR. */
-export function raiseRecovered(fn: Fn, target: TargetDescription, hooks: RaiseHooks = {}): void {
-  runPreRecovery(fn, target, (pass, result) => {
-    verify(fn);
-    hooks.afterPass?.(pass, result);
-  });
+ *  return-only merge so short-circuits emit early returns) → empty-latch folding (splice out a
+ *  back-edge block SSA construction emptied). `verify` after every pass that changed the IR.
+ *
+ *  The two CFG passes look ordered and are not: running latch folding FIRST instead changes
+ *  nothing across a 3337-function agbcc corpus. Worth saying, because folding an empty block ahead
+ *  of return-sinking does take away `br` predecessors it needs — the dominance gate is what makes
+ *  that unreachable, since the blocks retsink wants are never back-edge sources. It goes last
+ *  because that is where the CFG stops moving.
+ *
+ *  The tail is three separate parameters rather than an options bag on purpose: this is the
+ *  published package root export, so every caller outside this repo is pinned to the positions.
+ *
+ *  @param hooks per-stage observers; see {@link RaiseHooks}. Each fires after that stage's verify.
+ *  @param self  this function's own prototype, where the caller has one — what the pre-recovery
+ *               passes read to type the parameters they are narrowing.
+ *  @param pre   per-caller PRE-RECOVERY options. One shipped user: rank.ts's `/connective`
+ *               candidate, which passes `{ shortCircuit: { foldTreeOwned: true } }` to take the
+ *               fold the comparison-tree refusal owns (raise/shortcircuit.ts). */
+export function raiseRecovered(
+  fn: Fn,
+  target: TargetDescription,
+  hooks: RaiseHooks = {},
+  self?: FnProto,
+  pre: PreRecoveryOptions = {},
+): void {
+  const lifted = runPreRecovery(
+    fn,
+    target,
+    (pass, result) => {
+      verify(fn);
+      hooks.afterPass?.(pass, result);
+    },
+    self,
+    pre,
+  );
   hooks.beforeRecover?.();
   recoverTypes(fn);
   verify(fn);
   assertTypesRecovered(fn);
   hooks.afterRecover?.();
-  if (sinkReturns(fn)) {
+  // `lifted.mergeShapes` is the CFG as it ENTERED pre-recovery, and retsink's `pre-diamond` needs
+  // exactly that: `raise/shortcircuit.ts` manufactures two-armed diamonds out of condition trees the
+  // ROM never merged, and a diamond this pass reads at its own turn may be one of those.
+  if (
+    sinkReturns(fn, {
+      hoistsSingleSetArm: target.compilerBehaviors.hoistsSingleSetArm,
+      mergeShapes: lifted.mergeShapes,
+    })
+  ) {
     verify(fn);
     hooks.afterRetsink?.();
   }
+  if (foldEmptyLatches(fn)) {
+    verify(fn);
+    hooks.afterLatchFold?.();
+  }
+  // THE BOUNDARY POSTCONDITION. Above this line passes move the CFG; below it nothing does, and the
+  // structurer reads a block parameter as a JOIN — a name it must give a local of its own. A param
+  // whose every in-edge carries one value is not a join, and leaving one standing is how a
+  // CFG-motion pass does its damage three stages away rather than where it happened: retsink's own
+  // stranded merge was destroyed into `v0 = 0; return v0;` and read by Regime-A switch recovery as a
+  // SECOND `default` candidate, declining every fall-through tree. This names it at retsink.
+  // Not an `ir/verify.ts` rule: a trivial phi is well-formed IR, and both SSA construction and the
+  // `addrnum` pass mint one and clear it inside their own scope (see `firstTrivialPhi`).
+  const stranded = firstTrivialPhi(fn);
+  if (stranded) {
+    throw new Error(
+      `internal: raising left a trivial phi — block #${fn.blocks.indexOf(stranded.block)} takes ` +
+        `'${stranded.param}', whose every in-edge carries one value. A pass that retires an in-edge ` +
+        `must run simplifyTrivialPhis after it.`,
+    );
+  }
 }
 
 /** Run `body`; if it declines, name the unmodelled instructions the function carries.
@@ -214,15 +329,7 @@ function attributeOpaques<T>(fn: Fn, body: () => T): T {
     if (!(e instanceof StructureError) || !fn.blocks[0]) {
       throw e;
     }
-    const seen = new Set<Block>([fn.blocks[0]]);
-    for (const stack = [fn.blocks[0]]; stack.length;) {
-      for (const s of successorsOf(stack.pop()!)) {
-        if (!seen.has(s)) {
-          seen.add(s);
-          stack.push(s);
-        }
-      }
-    }
+    const seen = reachableBlocks(fn);
     const names = new Set<string>();
     for (const b of seen) {
       for (const op of b.ops) {
@@ -234,7 +341,7 @@ function attributeOpaques<T>(fn: Fn, body: () => T): T {
     if (!names.size || /unmodelled instruction/.test(e.message)) {
       throw e;
     }
-    // Through `gapReasonFor`, so the classifier sees its canonical text — a hand-written variant
+    // Through `gapReasonFor`, so the classifier sees its canonical text — a hand-written spelling
     // misses the mnemonic-anchored classes and every attributed decline lands in the generic bucket.
     const list = [...names].sort().map(gapReasonFor).join(', ');
     throw new StructureError(`${e.message} — and the function carries ${list}, which is the more likely cause`);
@@ -242,22 +349,32 @@ function attributeOpaques<T>(fn: Fn, body: () => T): T {
 }
 
 /** Stage 4 — structure + its boundary contracts, always as a pair. */
-export function structureChecked(fn: Fn, opts: Parameters<typeof structure>[1]): SFn {
-  const raw = attributeOpaques(fn, () => structure(fn, opts));
-  // BOTH boundary contracts run on the pre-DCE tree: the readability pass must never be able to
+export function structureChecked(
+  fn: Fn,
+  opts: Parameters<typeof structure>[1],
+  hooks?: Parameters<typeof structure>[2],
+): SFn {
+  const raw = attributeOpaques(fn, () => structure(fn, opts, hooks));
+  // The boundary contracts run on the pre-DCE tree: the readability pass must never be able to
   // hide a structuring defect by dropping the dead statement that carries it. assertResolved
   // catches an unresolved `?` value; assertDerefsTyped catches an ill-typed deref (e.g. a pointer
-  // under a rejected operator) — even one sitting in dead code structure emitted. DCE then only
-  // removes statements/flips branches over an already-validated tree.
+  // under a rejected operator) — even one sitting in dead code structure emitted;
+  // assertLocalsWritten catches a materialized def whose assignment no position emitted. DCE then
+  // only removes statements/flips branches over an already-validated tree.
   assertResolved(raw);
   assertDerefsTyped(raw);
+  assertLocalsWritten(raw);
   assertEffectsPreserved(fn, raw);
   // Then the readability/quality rewrites: merge a statement common to every arm of an if,
-  // drop dead stores (whose empty-then peephole flips the arm the merge empties), then hoist a
-  // reused aggregate-global
-  // base into a typed local pointer. The hoist moves the deref cast from each `index` node onto the
-  // local's initializer, so re-validate deref typing on the rewritten tree.
-  const sfn = hoistReusedGlobalBases(eliminateDeadStores(mergeCommonTails(raw)));
+  // drop dead stores (whose empty-then peephole flips the arm the merge empties), then hoist each
+  // leaf base the DEFAULT gate table admits into a typed local pointer. The hoist moves the deref
+  // cast from each `index` node onto the local's initializer, so re-validate deref typing on the
+  // rewritten tree.
+  // Both arguments SPELLED, defaults or not: this is the one call to this pass that is committed
+  // rather than offered, so it is the one whose gate table and whose placement can cost a MATCH
+  // instead of a candidate (docs/level-tower.md). A committed policy that reads as "whatever the
+  // default is" is the policy nobody reviews.
+  const sfn = hoistBaseLocals(eliminateDeadStores(mergeCommonTails(raw)), BASECSE_GATES, 'head');
   assertDerefsTyped(sfn);
   // Re-checked after the readability rewrites for the same reason deref typing is: a pass that
   // merges arms or drops statements must not be able to lose or duplicate a call.
@@ -317,26 +434,22 @@ export function stubResult(name: string, asm: string, backend: LanguageBackend,
     ir: { raw: '', folded: '', recovered: '' },
     patternHits: 0,
     diagnostics: [{ stage, reason: msg }],
+    // A stub spells no global, so it assumes nothing about one.
+    assumedSymbols: [],
   };
 }
 
 /** Every ASMLIFT_ERROR marker in the emitted AST, as a structured diagnostic (one per marker,
  *  document order). The harness/self-improve loop reads THIS; the source text is for humans. */
 function collectMarkers(sfn: SFn): Diagnostic[] {
-  // On the shared exprChildren/stmtExprs/stmtChildren traversal. Order is exprs-then-children
-  // per statement — deterministic and near-document-order (a `for`'s cond is visited before its
-  // init; see the note on stmtChildren).
+  // On the shared `walkExprs` traversal (l3/ast.ts). Order is exprs-then-nested-statements per
+  // statement — deterministic and near-document-order (a `for`'s cond is visited before its init;
+  // see the note on stmtChildren).
   const out: Diagnostic[] = [];
-  const we = (e: Expr): void => {
+  for (const e of walkExprs(sfn.body)) {
     if (e.k === 'marker') {
       out.push({ stage: 'structure', reason: e.reason });
     }
-    exprChildren(e).forEach(we);
-  };
-  const ws = (s: Stmt): void => {
-    stmtExprs(s).forEach(we);
-    stmtChildren(s).forEach(ws);
-  };
-  sfn.body.forEach(ws);
+  }
   return out;
 }

package/src/proto.ts

@@ -1,15 +1,22 @@
-import type { SymbolMap } from './symbols';
+import type { SymbolMap, SymbolTypeFacts } from './symbols';
 
 // asmlift — function prototypes: the single carrier for the caller-supplied facts a
-// matching-decomp project reads from its headers (arg counts, void-ness). One `Prototypes`
-// map, keyed by symbol, is threaded through every entry point and resolved at the point of
-// use — a callee's `params` gives its call-site arity, a function's own entry gives its
-// `returnsVoid`. It also keeps the frontend seam honest: a frontend receives prototypes,
-// not a grab-bag of ISA-specific options.
+// matching-decomp project reads from its headers (arg counts, parameter widths, void-ness). One
+// `Prototypes` map, keyed by symbol, is threaded through every entry point and resolved at the
+// point of use — a callee's `params` gives its call-site arity, a function's own entry gives its
+// `returnsVoid` and the widths raise/paramwidth.ts checks against. It also keeps the frontend seam
+// honest: a frontend receives prototypes, not a grab-bag of ISA-specific options.
 
-/** One declared parameter, as its C type text (`"u8"`, `"s32"`, `"void *"`). asmlift consumes
- *  only the COUNT today (call-site arity), but a project's header extraction naturally produces
- *  the typed list, and keeping it lets a later pass pin an argument's width/signedness. */
+/** One declared parameter, as its C type text (`"u8"`, `"s32"`, `"void *"`, `"int"`). Two facts
+ *  are read off it: the list's LENGTH is the call-site arity (`protoArity`), and one entry's WIDTH
+ *  (`declaredWidth`) is what raise/paramwidth.ts checks its inference against.
+ *
+ *  A DECLARED WIDTH ONLY VETOES, never pins. Where the asm carries a prologue extension the
+ *  declaration contradicts, the declaration wins — it is a fact from the project's headers, where
+ *  the extension is an inference off an encoding two different C sources produce. Where the asm
+ *  carries no extension, this list is NOT consulted: pinning there would type every parameter of
+ *  every row from the declaration, and a declared `u32` kills rank.ts's signed arm before the
+ *  differ ever sees it. That half is a variation question and is not answered here. */
 export type ParamType = string;
 
 /** What the headers know about one function. All fields optional: a partial table (only
@@ -17,10 +24,26 @@ export type ParamType = string;
 export interface FnProto {
   /** declared parameters — either a bare arity COUNT or the typed parameter list a header
    *  extraction produces (`["u8", "s32"]`). BOTH forms yield the call-site arity via
-   *  `protoArity`; omit to let the frontend fall back to its contiguous-arg-register heuristic. */
+   *  `protoArity`; only the typed form carries a width. Omit to let the frontend fall back to its
+   *  contiguous-arg-register heuristic. */
   params?: number | ParamType[];
-  /** the declared return type is `void`, so a trailing `bx lr` leaves a meaningless
-   *  return register that must not surface as a `return` value. */
+  /** The declared return type is `void`. Read for the function under decompilation, where a
+   *  trailing `bx lr` leaves a meaningless return register that must not surface as a `return`
+   *  value — and, since the out-parameter path landed, for a CALLEE, where it is the only thing
+   *  that tells an out-parameter frame from a hidden struct-return pointer.
+   *
+   *  THAT SECOND READER IS LOAD-BEARING AND THE FIELD IS UNCHECKED DATA, which is worth knowing
+   *  before authoring one. `validatePrototypes` type-checks the boolean and can check no more:
+   *  nothing in the assembly distinguishes the two frames, which is why the refusal exists. So a
+   *  callee wrongly declared `void` turns a loud decline into a compiling, plausible, wrong
+   *  program — measured on the shape the guard is for, `struct S4 mk(int); struct S4 s = mk(x);`
+   *  lifts as `mk(&sp0); return (u8)sp0;` when `mk` is declared `returnsVoid` — where a callee
+   *  wrongly declared NON-void, or left undeclared, only costs the lift. Under-declaring is the
+   *  safe direction and this project has already shipped one wrong entry (a dataset row declaring
+   *  `returnsVoid: true` for a function whose own reference returns `void *`).
+   *
+   *  Both readers see one field through two trust levels: caller-supplied on `--proto`, and
+   *  machine-derived from DWARF through `prototypesFromSymbols`. Neither is distinguished here. */
   returnsVoid?: boolean;
 }
 
@@ -43,10 +66,85 @@ export function protoArity(p: FnProto | undefined): number | undefined {
   return undefined;
 }
 
+/** Bit width per C89 base type on every target asmlift lifts (all ILP32). `long` is 32 here and
+ *  would not be on an LP64 host, so it is a target fact rather than a language one. */
+const BASE_WIDTHS: ReadonlyMap<string, number> = new Map([
+  ['char', 8],
+  ['short', 16],
+  ['short int', 16],
+  ['int', 32],
+  ['long', 32],
+  ['long int', 32],
+]);
+
+/** The bit width one declared parameter type spells, or `undefined` for a spelling this does not
+ *  read — a project typedef, a struct, a `float`. UNDEFINED IS "NO OPINION", never "wide": the one
+ *  consumer treats a width it can read as authority and a width it cannot as absence, so an
+ *  unrecognized spelling leaves the asm's own inference standing.
+ *
+ *  A pointer is register-wide whatever it points at, which is the fact the `*` test carries. */
+export function declaredWidth(t: ParamType): number | undefined {
+  const s = t
+    .replace(/\b(?:const|volatile)\b/g, ' ')
+    .trim()
+    .replace(/\s+/g, ' ');
+  if (s.endsWith('*')) {
+    return 32;
+  }
+  const own = /^([su])(8|16|32)$/.exec(s);
+  if (own) {
+    return Number(own[2]);
+  }
+  // `unsigned`/`signed` alone is `unsigned int`/`signed int`; the signedness itself is not a width.
+  const base = s
+    .replace(/\b(?:signed|unsigned)\b/g, ' ')
+    .trim()
+    .replace(/\s+/g, ' ');
+  return BASE_WIDTHS.get(base === '' && s !== '' ? 'int' : base);
+}
+
+/** Problems with a HAND-WRITTEN prototype table — empty when it is well formed.
+ *
+ *  `protoArity` above falls back to the arg-register heuristic on a `params` it cannot read, which
+ *  is right when `params` is omitted and silent when it is mistyped: `params: "2"` then decompiles
+ *  at a guessed arity, and a misspelled `returnsVoid` does nothing at all. Neither is visible in
+ *  the output, so a table that came from outside is checked before it reaches either. */
+export function validatePrototypes(value: unknown): string[] {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return ['must be an object mapping a symbol name to its prototype'];
+  }
+  const problems: string[] = [];
+  for (const [sym, proto] of Object.entries(value)) {
+    if (typeof proto !== 'object' || proto === null || Array.isArray(proto)) {
+      problems.push(`${sym}: must be an object, e.g. {"params": 2}`);
+      continue;
+    }
+    for (const key of Object.keys(proto)) {
+      if (key !== 'params' && key !== 'returnsVoid') {
+        problems.push(`${sym}: unknown key "${key}" (expected "params" or "returnsVoid")`);
+      }
+    }
+    const { params, returnsVoid } = proto as { params?: unknown; returnsVoid?: unknown };
+    if (params !== undefined) {
+      const countOk = typeof params === 'number' && Number.isInteger(params) && params >= 0;
+      const listOk = Array.isArray(params) && params.every((t) => typeof t === 'string');
+      if (!countOk && !listOk) {
+        problems.push(`${sym}: "params" must be a non-negative integer or a list of type strings`);
+      }
+    }
+    if (returnsVoid !== undefined && typeof returnsVoid !== 'boolean') {
+      problems.push(`${sym}: "returnsVoid" must be a boolean`);
+    }
+  }
+  return problems;
+}
+
 /** The C type spelling for one declared parameter/return, or null when the facts do not
  *  determine one. A pointer is `void *` — address-identical to any object pointer, and asmlift
- *  makes every stride explicit — so nothing is guessed about what it points at. */
-function typeSpelling(t: { size: number | null; signed: boolean | null; pointer?: boolean }): ParamType | null {
+ *  makes every stride explicit — so nothing is guessed about what it points at. A richer spelling
+ *  would also be INERT: `declaredWidth` answers 32 for every `*`, and a CALLEE's parameter types
+ *  are read for the list's length alone (test/param-pointee-variation.test.ts). */
+function typeSpelling(t: SymbolTypeFacts): ParamType | null {
   if (t.pointer) {
     return 'void *';
   }

package/src/raise/arrays.ts

@@ -61,7 +61,12 @@ export function recognizeArrays(fn: Fn): number {
         b.ops[i] = mkOp('aload', {
           operands: [m.base, m.index],
           results: [res],
-          attrs: { elemSize: op.attrs.width as number, signed: op.attrs.signed as boolean },
+          // listOrder rides along: an ldmia-expanded load keeps its stream-order caveat as an aload
+          attrs: {
+            elemSize: op.attrs.width as number,
+            signed: op.attrs.signed as boolean,
+            ...(op.attrs.listOrder === true && { listOrder: true }),
+          },
         });
         replaceAllUsesWith(fn, op.results[0], res);
         count++;