@asmlift/core 0.8.1 → 0.10.0

package/src/proto.ts

@@ -1,15 +1,22 @@
-import type { SymbolMap, SymbolTypeFacts } from './symbols';
+import { parseTypeName } from './cdecl/parse';
+import type { IrType } from './ir/types';
+import { demangle, implicitArgumentWords, spellType } from './mangle';
+import type { SymbolInfo, SymbolMap, SymbolTypeFacts } from './symbols';
+import type { TargetDescription } from './target';
 
 // asmlift — function prototypes: the single carrier for the caller-supplied facts a
 // 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
+// point of use — a callee's `params` gives the registers its call occupies, 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 *"`, `"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.
+/** One declared parameter, as its C type text (`"u8"`, `"s32"`, `"void *"`, `"int"`). The lift reads
+ *  ONE fact off it and derives everything else from that fact: the WIDTH it spells
+ *  (`declaredWidth`). raise/paramwidth.ts checks its inference against that width, and
+ *  `declaredCallArgs` sums the list's widths into the argument registers the call occupies. On a
+ *  function compiled as C++ the printer reads the SPELLING too: a call argument is cast to it where
+ *  C++ converts nothing implicitly (backend/cfamily.ts `argConversion`).
  *
  *  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
@@ -22,11 +29,46 @@ export type ParamType = string;
 /** What the headers know about one function. All fields optional: a partial table (only
  *  callee arities, or only the current function's void-ness) is the common case. */
 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`; only the typed form carries a width. Omit to let the frontend fall back to its
-   *  contiguous-arg-register heuristic. */
+  /** declared parameters — either the typed parameter list a header extraction produces
+   *  (`["u8", "s32"]`), which is a list of C PARAMETERS, or a bare COUNT, which is the user's word
+   *  for how many argument REGISTERS the call occupies — read so at a call. On the function's OWN
+   *  entry a count bounds no argument register (`ownArgumentWords` abstains): a header's count may
+   *  be of C parameters, and one of those may span any number of words. The two are the
+   *  same number only while every parameter fits in a register, and `declaredCallArgs` is what
+   *  converts the first into the second. Omit — or spell a parameter that conversion cannot size — to let the frontend
+   *  fall back to its contiguous-arg-register heuristic. */
   params?: number | ParamType[];
+  /** The parameters, by index into a typed `params`, whose spelling `declaredWidth` cannot size and
+   *  which still travel in one register: an enum, or an array or function type a typedef name
+   *  stands for, which the parameter adjusts to a pointer. A context states it, reading the types
+   *  behind the names (`prototypesFromContext`). Every reader sizes such a parameter at one word
+   *  (`paramClassOf`): the call lowering's widths (`declaredCallArgs`) and a frontend's frame
+   *  partition alike. */
+  wordParams?: readonly number[];
+  /** The parameters, by index into a typed `params`, that are a struct, union or class passed BY
+   *  VALUE: mwcc passes the address of a copy it builds in the caller's own frame, which no source
+   *  declares (`frontend/ppc.ts` `measurePpcFrame`). A context states it, reading the tag behind the
+   *  name (`prototypesFromContext`). A spelling neither this nor `wordParams` lists, and that
+   *  nothing else sizes, is UNSIZED — a name nothing here resolved, not a struct by inference — and
+   *  every reader abstains on it. */
+  byValueParams?: readonly number[];
+  /** The members of each struct or union a typed `params` list passes BY VALUE, keyed by the
+   *  parameter's index: what sizes it, and so how many argument words it takes on a target that
+   *  passes one in words (`compilerBehaviors.byValueAggregateArgWords`, read by `aggregate.ts`
+   *  `byValueCallArgs`). A context states it from the struct's definition, as it states
+   *  `returnLayout`. A by-value parameter with no layout here is unsized, and a call to it refuses
+   *  (`aggregate.ts` `byValueRefusal`) rather than take the argument-register guess. */
+  byValueLayouts?: Readonly<Record<number, AggregateLayout>>;
+  /** The FIXED parameters of a VARIADIC declaration, spelled as a typed `params` list spells them.
+   *  Such a declaration states no `params`, because its arity is the call's and a list would read
+   *  as the whole of it; `wordParams` and `byValueParams` index into this list instead. A context
+   *  states it (`prototypesFromContext`). Read for two things, and never as a layout of its own.
+   *  Where each fixed parameter is one word, they are the call's first argument words, and only
+   *  what the `...` takes is guessed (frontend/call-plan.ts `variadicFloor`). Where one is not, the
+   *  call refuses (`variadicRefusal`): the arity guess reads argument words one by one, so a fixed
+   *  parameter that is not one word is split or dropped: `void takeV(struct W, ...)` would lift
+   *  `takeV(*(s32 *)&gW, 5)`, which compiles against the header. */
+  variadicParams?: ParamType[];
   /** 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
@@ -45,29 +87,624 @@ export interface FnProto {
    *  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;
+  /** The declared return type, as its C type text — the same vocabulary `params` is written in and
+   *  read through the same {@link declaredWidth}, because a return and a parameter spell a width
+   *  the same way and two spellings of one vocabulary is where they start to disagree.
+   *
+   *  WHAT IT BUYS THAT `returnsVoid` CANNOT: how many registers the callee hands BACK. A value
+   *  wider than a register comes home in a register PAIR, so after a `bl` the second register holds
+   *  the returned high half — a legitimate definition — where for every other callee it holds the
+   *  callee's leftovers and reading it is the wrong value `frontend/ssa.ts` refuses. Those two are
+   *  the same instructions, so nothing in the assembly tells them apart and the caller must be
+   *  TOLD, exactly as `returnsVoid` must be.
+   *
+   *  A SPELLING THIS CANNOT SIZE — OR CANNOT PRINT — IS SILENCE, never a word. {@link spellableProto}
+   *  is the one gate and {@link declaredReturnWidth} is defined on top of it, so a `returns` whose
+   *  width the frontend acts on is always one the candidate's own translation unit can declare;
+   *  anything else lifts the call the way an undeclared callee is lifted. Under-declaring stays the
+   *  safe direction here too — a return wrongly declared 64-bit names a register the callee really
+   *  did destroy, which is the defect the refusal exists for.
+   *
+   *  `"void"` HERE IS `returnsVoid`, not a width. The two keys are one fact and
+   *  {@link declaresVoidReturn} reads both, so either spelling suppresses the phantom return value
+   *  on the function's own entry and rules out a hidden struct-return pointer at a callee.
+   *  `validatePrototypes` refuses a table that states them differently, in either direction.
+   *
+   *  A HEADER STATES IT AND NOTHING DERIVES IT. `prototypesFromSymbols` does not fill this in:
+   *  `typeSpelling` sizes 1, 2 and 4 bytes, so a DWARF-derived entry could only ever spell a return
+   *  that already fits a register, where the field changes nothing. */
+  returns?: ParamType;
+  /** The declared return is a struct or union handed back BY VALUE. A caller that calls such a
+   *  function may be handing it a hidden pointer to the storage the return lands in, in argument 0
+   *  (agbcc thumb.h:672 STRUCT_VALUE_REGNUM 0), with every declared argument one register up
+   *  (thumb.h:644-645) — so the declared `params` do not say which registers the call reads, and a
+   *  lift that reads them from r0 names the hidden pointer as the first argument. A `returns` that
+   *  spells `struct Tag` or `union Tag` states the same fact ({@link declaresAggregateReturn});
+   *  this key also says it of a typedef name, which spells no keyword, and carries the members
+   *  whose layout decides whether the target returns it through memory at all (`aggregate.ts`). */
+  returnLayout?: AggregateLayout;
+  /** ON THE FUNCTION'S OWN ENTRY, `true` says the entry is its declaration context's header entry
+   *  (proto-context.ts `ownContextEntry`) and not the caller's word: it bounds the argument
+   *  registers SOFTLY (pipeline.ts `liftWithinContextBound`), and a struct it returns through
+   *  memory is lifted as that struct where the lift proves the hidden pointer is only its storage
+   *  (pipeline.ts `returnOwnStruct`), and kept as the pointer function with a note where it does
+   *  not; it is read as nothing else — not as a scalar return, not by any reader of a stated own
+   *  entry. Each entry path takes it out of the table before anything reads it (proto-context.ts `splitOwnContext`). It is how a table carries the
+   *  entry a `--context` lift was handed: a benchmark row publishes it so its `--proto` replay
+   *  lifts as the harness did. On a callee's entry it is ignored. */
+  fromContext?: boolean;
+}
+
+/** A struct or union a declaration spells: what it is, and its members as the header lists them.
+ *  No offset or size is stored, because both are the TARGET's — agbcc rounds every struct and
+ *  union to a word (thumb.h:367 STRUCTURE_SIZE_BOUNDARY 32) where mwcc does not — and are computed
+ *  where a target is in hand (`aggregate.ts`). */
+export interface AggregateLayout {
+  kind: 'struct' | 'union';
+  /** every member in declaration order; absent when one of them could not be read, which leaves
+   *  the aggregate known to exist and nothing known about its shape */
+  members?: AggregateMember[];
+}
+
+/** One member of an {@link AggregateLayout}. */
+export interface AggregateMember {
+  /** empty only for an unnamed bitfield, which pads */
+  name: string;
+  /** a scalar or pointer type as C spells it (`u32`, `float`, `u8 *`), an enum as `enum` and its
+   *  name, or a nested struct or union */
+  type: ParamType | AggregateLayout;
+  /** an array member's extents, outermost first */
+  dims?: number[];
+  /** a bitfield's width in bits */
+  bits?: number;
 }
 
 /** symbol → prototype. The function under decompilation and its callees share one table. */
 export type Prototypes = Record<string, FnProto>;
 
-/** The call-site arity a proto declares, normalizing the count form (`2`) and the typed-list
- *  form (`["u8", "s32"]`) to one number. `undefined` when `params` is omitted — the caller then
- *  falls back to its arg-register heuristic. Reading a typed list as its length is what lets a
- *  header-derived proto (`params: ["u8"]`) recover its argument instead of silently dropping it. */
-export function protoArity(p: FnProto | undefined): number | undefined {
+/** How many argument WORDS a list of parameter WIDTHS occupies: a parameter wider than a machine
+ *  word travels in a pair of words, every other one in a single word, and where the target aligns
+ *  an 8-byte argument (`TargetDescription.evenWordAlignedArgs`) a pair that would start at an odd
+ *  word skips one.
+ *
+ *  The rule lives here rather than beside either caller because it has two, and they are the two
+ *  vocabularies a declaration is written in. `runtime-helpers.ts` states a compiler's own helper
+ *  signatures as widths (`__ashrdi3` is `[64, 32]` — two C parameters, three registers), and
+ *  `declaredCallArgs` below reads the same widths off a project's C types. One ABI fact, one
+ *  copy of it; a second copy is a rule that can disagree with itself.
+ *
+ *  agbcc DOES NOT ALIGN, a measured fact rather than an omission: its `thumb.h` computes an
+ *  argument's register from a plain byte counter with no rounding, so `void f(s32, long long)`
+ *  passes the pair in r1:r2 where AAPCS would pad to r2:r3. O32 does, for a scalar and a struct
+ *  alike, and that is the one fact both read here: `aggregate.ts` `byValueCallArgs` places a struct
+ *  by this count, and the lowering that builds an o32 pair, which `frontend/mips.ts` does not yet
+ *  (it refuses a declared 64-bit parameter, `CallLowering.pairs`), counts its words the same way. */
+export function wordsOf(params: readonly number[], target: Pick<TargetDescription, 'evenWordAlignedArgs'>): number {
+  return params.reduce((n, w) => (w > 32 ? n + (target.evenWordAlignedArgs === true ? n % 2 : 0) + 2 : n + 1), 0);
+}
+
+/** Whether a proto states a parameter list at all — readably or not. The tier question, asked
+ *  before the layout question: a project that declares a callee has re-declared it, and falling
+ *  through to a compiler's runtime table or to the C standard's signatures behind a declaration
+ *  nobody could SIZE would answer with a different function's shape. */
+export function declaresParams(p: FnProto | undefined): boolean {
+  return typeof p?.params === 'number' || Array.isArray(p?.params);
+}
+
+/** The declaration a call to `callee` is read at — THE TIER ORDER, written once: the project's own
+ *  entry where it states a parameter list (`declaresParams`), then the compiler's runtime table
+ *  (`helpers`: `runtime-helpers.ts` `helperPrototypes` of the target), then the signatures the C
+ *  standard fixes. `frontend/call-plan.ts` lowers every call at it, and the CLI asks it which
+ *  callees a run guessed, so a callee the lowering reads a signature for is never reported as
+ *  guessed, and one it guesses for always is. `Object.hasOwn` on all three tables: a callee named
+ *  `toString` would otherwise read a `Function` off `Object.prototype` as its entry. */
+export function calleeDeclaration(callee: string, prototypes: Prototypes, helpers: Prototypes): FnProto | undefined {
+  const known = (t: Prototypes) => (Object.hasOwn(t, callee) ? t[callee] : undefined);
+  const own = known(prototypes);
+  return declaresParams(own) ? own : (known(helpers) ?? known(STANDARD_SIGNATURES));
+}
+
+/** What a declaration says about the argument registers a call occupies — the width each declared
+ *  parameter travels in, in argument order — or `undefined` when it says nothing this can act on.
+ *
+ *  THREE WAYS TO SAY NOTHING, AND THEY ARE ONE ANSWER. `params` omitted; `params` malformed (a
+ *  bare `"u8"` string, the shape the untyped CLI `--proto` JSON admits); and a list holding a
+ *  spelling neither `declaredWidth` reads nor the declaration sizes — a project typedef
+ *  (`bool8`, `Direction`, `TaskFunc`) that `wordParams` does not list, a by-value struct, a
+ *  floating type (a by-value struct is the exception below). The first two are not a reading of the
+ *  list at all. The third is a list read to the end that cannot be CONVERTED: a parameter of
+ *  unknown width occupies one argument register or two, and the choice moves every later argument's
+ *  home. Where the declaration does settle it
+ *  — a typedef'd enum, an array or a function type the context resolved to one word, which
+ *  `wordParams` lists (`paramClassOf`) — the parameter is 32 bits and the list converts.
+ *
+ *  SO IT ABSTAINS, AND ABSTAINING IS NEITHER A REFUSAL NOR A GUESS. The caller falls back to its
+ *  own contiguous-arg-register scan — exactly what it does for a callee the project never declared
+ *  — and that scan names itself a guess: `SsaBuilder.readGuessedArg` ASKS whether a register was
+ *  set up, and `finish()` retracts the ones an intervening call destroyed. Refusing instead would
+ *  be a function that lifts when told nothing and declines when told more. The list's LENGTH is
+ *  still read: every parameter is at least one word, so a guess that counts fewer registers has
+ *  dropped one, and that refuses (frontend/call-plan.ts `refuseShortOfDeclared`). Returning
+ *  one-register-each instead would be a layout nothing could know to be right, and the frontend
+ *  would then ASSERT those registers rather than ask for them.
+ *
+ *  A PARAMETER THE DECLARATION PASSES AS A STRUCT OR UNION BY VALUE IS THE EXCEPTION, because it is
+ *  known not to be one register: the caller asks `aggregate.ts` `byValueCallArgs` to place it, and
+ *  where no rule does (`byValueRefusal`) the call refuses (frontend/call-plan.ts
+ *  `refuseUnplacedByValue`). That is a function that declines when told more, on purpose: a guess
+ *  over a struct drops it or reads its words as separate arguments, and both compile.
+ *
+ *  THE MACHINE IS NOT A WITNESS FOR A WIDTH NOBODY STATED, which is the reading this replaces. The
+ *  contiguous scan is wrong in both directions and neither is recoverable here. It OVER-counts:
+ *  it is read before `frontend/ssa.ts` `narrowToSetupArgs` trims the registers a call sat between,
+ *  so `bl __muldi3` leaves r2 and r3 counted as arguments of the NEXT call. It UNDER-counts: an
+ *  incoming argument register this function passes straight through has no definition here at all,
+ *  so it counts zero — measured on agbcc, `void g(MyU64); void f(MyU64 x){ g(x|1); }` leaves the
+ *  high half in r1 untouched and the scan answers 1 for a call the ABI hands a pair. An equality
+ *  between that scan and the one-register-each reading is therefore as likely to be a miscounted
+ *  pair as a confirmation of anything, and a witness that cannot fail is not a witness.
+ *
+ *  The COUNT form is the user's word for argument REGISTERS and says so at its declaration, so it
+ *  expands to that many words and can never abstain. It is the way past a header this cannot size.
+ *
+ *  A `double` IS A TARGET FACT. Where it crosses a call in general argument words
+ *  (`TargetDescription.doubleArgWords`) it is 64 bits of words and its index is in `doubles`, so a
+ *  reader can tell it from a `long long`, whose bits are the same words in another order; on a
+ *  target that states no such words the list abstains. A `float` states no layout on either: it
+ *  is one word on a soft-float target, but that word is a float only to a callee whose declaration
+ *  the candidate prints, and `spellableProto` prints no `float` — an undeclared callee is handed a
+ *  `float` promoted to a `double`, which is two words. A known spelling with no layout is not the
+ *  unsized abstention, so on a target with no FPU a call to such a declaration refuses rather than
+ *  guess (frontend/call-plan.ts `refuseUnplacedFloat`). */
+export function declaredCallArgs(
+  p: FnProto | undefined,
+  target: Pick<TargetDescription, 'doubleArgWords'>,
+): { widths: readonly number[]; doubles: ReadonlySet<number> } | undefined {
   if (typeof p?.params === 'number') {
-    return p.params;
+    return { widths: Array.from({ length: p.params }, () => 32), doubles: new Set() };
   }
-  if (Array.isArray(p?.params)) {
-    return p.params.length;
+  if (!Array.isArray(p?.params)) {
+    return undefined;
+  }
+  const widths: number[] = [];
+  const doubles = new Set<number>();
+  for (const [i, t] of p.params.entries()) {
+    const w = declaredWidth(t) ?? (paramClassOf(p, p.params, i) === 'word' ? 32 : undefined);
+    if (w !== undefined) {
+      widths.push(w);
+    } else if (target.doubleArgWords !== undefined && isDoubleSpelling(t)) {
+      doubles.add(i);
+      widths.push(64);
+    } else {
+      return undefined;
+    }
+  }
+  return { widths, doubles };
+}
+
+/** WHAT ONE DECLARED PARAMETER IS, as far as where a caller places it goes — the one reading every
+ *  reader of a declaration takes, so the call lowering (`declaredCallArgs`) and a frontend's frame
+ *  partition (`frontend/call-plan.ts` `declaredParams`) cannot give one declaration two answers: a
+ *  value of one word (`declaredWidth` sizes it at 32 bits or less, or `wordParams` lists it), one
+ *  wider than a word, a floating type (`isFloatingSpelling`), a struct or union passed by value
+ *  (`byValueParams` lists it, or the spelling says so with its keyword: `struct B`), or UNSIZED — a
+ *  spelling nothing here resolved, which states none of those and is not read as any of them. A
+ *  count states words. */
+export type ParamClass = 'word' | 'wide' | 'float' | 'by-value' | 'unsized';
+
+/** A struct, union or class named by its keyword and tag, with no declarator: passed by value. */
+const BY_VALUE_SPELLING = /^\s*(?:struct|union|class)\s+\w+\s*$/;
+
+/** The class of parameter `k` of the typed list `params` that declaration `p` states (`ParamClass`). */
+export function paramClassOf(p: FnProto, params: readonly ParamType[], k: number): ParamClass {
+  const spelling = params[k];
+  const w = declaredWidth(spelling);
+  return w !== undefined
+    ? w > 32
+      ? 'wide'
+      : 'word'
+    : isFloatingSpelling(spelling)
+      ? 'float'
+      : p.wordParams?.includes(k)
+        ? 'word'
+        : p.byValueParams?.includes(k) || BY_VALUE_SPELLING.test(spelling.replace(/\b(?:const|volatile)\b/g, ' '))
+          ? 'by-value'
+          : 'unsized';
+}
+
+/** Why a call to the VARIADIC declaration `p` cannot be placed by the arity guess: its first fixed
+ *  parameter (`FnProto.variadicParams`, an index into it) that is not one argument word, and the
+ *  reason. Undefined where `p` is no variadic declaration, or where every fixed parameter is a word
+ *  or UNSIZED — a spelling nothing here resolved, which may be one word, and on which every reader
+ *  abstains (`declaredCallArgs`) rather than refuse. */
+export function variadicRefusal(p: FnProto | undefined): { refused: string; param: number } | undefined {
+  const fixed = p?.variadicParams;
+  if (fixed === undefined || p?.params !== undefined) {
+    return undefined;
+  }
+  const reasons: Partial<Record<ParamClass, string>> = {
+    'by-value': 'reads a struct or union passed by value as that many separate words',
+    wide: 'reads a value wider than a word as two separate arguments',
+    float: 'reads a floating-point value as integer words, or misses it in the FPU registers',
+  };
+  for (const k of fixed.keys()) {
+    const why = reasons[paramClassOf(p!, fixed, k)];
+    if (why !== undefined) {
+      return {
+        refused: `its declaration is variadic: the call's arguments are placed by the arity guess, which ${why}`,
+        param: k,
+      };
+    }
   }
-  // Omitted OR malformed (e.g. a bare `"u8"` string reaching the untyped CLI `--proto` JSON):
-  // fall back to the frontend's arg-register heuristic rather than misread a string's `.length`.
   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. */
+/** HOW MANY GENERAL ARGUMENT WORDS THE FUNCTION UNDER DECOMPILATION'S OWN DECLARATION FILLS — an
+ *  UPPER BOUND, never an exact layout — or `undefined` where the declaration bounds nothing.
+ *
+ *  Its one reader is the live-in model (`frontend/ssa.ts` `registerLiveIns`): an argument register
+ *  at or past this many words is one no caller fills, so a read of it before any write is an
+ *  uninitialised local the compiler homed there, never a parameter. KMC and gcc 2.7.2 home a local
+ *  in `a2`/`a3` past a two-parameter declaration, agbcc in `r3` and mwcc 2.3.3 in `r5`..`r10`, and
+ *  unbounded, each such read is a made-up parameter (`uninitfirst(a0, *a1, a2, a3)`).
+ *
+ *  AN UPPER BOUND, because the direction of every error decides what it costs. A bound too HIGH
+ *  leaves a register a parameter, as no bound at all does. A bound
+ *  too LOW turns a real argument into `uninit_<reg>`, which is wrong C. So:
+ *   - the declared words are laid out by {@link wordsOf}, the call's own rule: a floating parameter
+ *     takes no general word where floats count on their own (`fpu.slots: 'separate'`, the PowerPC
+ *     EABI), and everywhere else a floating parameter takes two, as a `long long` does (O32's
+ *     leading floats still take their integer slots, and agbcc passes both in general words).
+ *     A `float` takes two as well: a list cannot say whether the definition is prototyped, and an
+ *     old-style one (`int k(a, b) float a; int b;`) is handed `a` promoted to `double`, so `b`
+ *     sits in r2 / a2. Two words are an upper bound for a prototyped `float` too.
+ *   - UP TO TWO HIDDEN WORDS ARE ADDED to a typed list where they may come first, because no
+ *     parameter list states them and each pushes every declared parameter one register up. A return the
+ *     declaration does not show is a scalar or `void` may be a struct handed back through a
+ *     pointer in argument 0, and a symbol that may name a C++ member function is handed `this`
+ *     there (`mangle.ts` `implicitArgumentWords`). Both are "may": a static member or a struct
+ *     returned in registers leaves one register a parameter.
+ *
+ *  THE PARAMETERS ARE THE STATED ONES, or where the declaration states none, the ones a mangled
+ *  symbol records (`demangle`: `uninitfirst__FiPi` is `(int, int *)`), which is the compiler's own
+ *  copy of the declaration. A BARE COUNT BOUNDS NOTHING: it may count argument registers
+ *  (`FnProto.params`) or C parameters, any of which may be a pair or a struct passed by value of
+ *  any size. IT ABSTAINS where neither states a list, or on one it cannot lay out: an
+ *  unsized spelling (which may be two words), a struct passed by value (sized by a layout this
+ *  does not read), a `long double`; and on a constructor or destructor, which
+ *  may be handed a flag beside `this`. A variadic declaration states no `params` and so
+ *  abstains: its arity is each caller's.
+ *
+ *  `registerReturn` says the declared struct return is one the target hands back in registers, so
+ *  no hidden pointer comes ahead of the parameters: the target's rule, which this module cannot
+ *  read, so every reader asks through `aggregate.ts` `ownArgumentWordsOn`, which reads it as the call
+ *  lowering does. */
+export function ownArgumentWords(
+  name: string,
+  p: FnProto | undefined,
+  target: Pick<TargetDescription, 'fpu' | 'evenWordAlignedArgs'>,
+  registerReturn = false,
+): number | undefined {
+  const own = ownArguments(name, p, target, registerReturn);
+  if (own === undefined || own.hidden === undefined) {
+    return undefined;
+  }
+  // The hidden words are laid out WITH the declared ones, not added after them: they come first,
+  // so they move where the even-word rule puts a 64-bit parameter. O32's `struct P f(double x)`
+  // passes the struct pointer in a0, skips a1 and passes `x` in a2:a3 — 4 words, where `1 +
+  // wordsOf([64])` says 3 and turns a3 into `uninit_a3`. The call side counts the same way
+  // (`frontend/call-plan.ts`, `[32, ...params]`).
+  return wordsOf([...Array.from({ length: own.hidden }, () => 32), ...own.widths], target);
+}
+
+/** WHETHER THE OWN DECLARATION SAYS THE CALLER FILLS ARGUMENT 0, asked of a function that RETURNS A
+ *  WORD — so no hidden struct pointer is in question: `true` where a declared parameter word or
+ *  `this` comes first, `false` where it states no argument word at all (`g__Fv`, a free
+ *  function of none), and `undefined` where it does not say (no declaration, one {@link
+ *  ownArgumentWords} cannot lay out, or no parameters on a symbol that only MAY be a method, which a
+ *  static member is not). The PowerPC frontend asks it before a bare return hands back r3's entry
+ *  value (`frontend/ppc.ts` `r3IsAnArgument`), and it reads the declaration the bound reads, so the
+ *  two cannot give one declaration two answers. */
+export function ownFirstArgumentPassed(
+  name: string,
+  p: FnProto | undefined,
+  target: Pick<TargetDescription, 'fpu' | 'evenWordAlignedArgs'>,
+): boolean | undefined {
+  const own = ownArguments(name, p, target);
+  if (own === undefined) {
+    return undefined;
+  }
+  if (own.widths.length > 0 || own.passesThis === true) {
+    return true;
+  }
+  return own.passesThis === false ? false : undefined;
+}
+
+/** The own declaration as both readers above read it: the declared parameter words' widths, the
+ *  hidden words that may come ahead of them (`undefined` where they cannot be bounded: a
+ *  constructor's or destructor's flag), and whether `this` is surely passed (`true` for a
+ *  constructor or destructor, `false` for a free function, `undefined` for a symbol that only may
+ *  be a method).
+ *
+ *  A bare count is no declaration this can lay out, so it reads as none. */
+function ownArguments(
+  name: string,
+  p: FnProto | undefined,
+  target: Pick<TargetDescription, 'fpu' | 'evenWordAlignedArgs'>,
+  registerReturn = false,
+): { widths: number[]; hidden: number | undefined; passesThis: boolean | undefined } | undefined {
+  // A COUNT BOUNDS NOTHING: it may mean argument registers or C parameters, and a C parameter
+  // may be a pair or a struct passed by value of any size (`f(struct S12 s)` {params: 1} fills 3
+  // words), so no layout of it is an upper bound.
+  if (typeof p?.params === 'number') {
+    return undefined;
+  }
+  const implicit = implicitArgumentWords(name);
+  const widths = ownParamWidths(name, p ?? undefined, target);
+  if (widths === undefined) {
+    return undefined;
+  }
+  return {
+    widths,
+    hidden: implicit === undefined ? undefined : (registerReturn || showsScalarReturn(p) ? 0 : 1) + implicit,
+    passesThis: implicit === undefined ? true : implicit === 0 ? false : undefined,
+  };
+}
+
+/** Whether a declaration shows its return is a scalar or `void`, so no struct pointer is handed
+ *  in ahead of its parameters: a `void`, or a stated return that is no aggregate and whose width
+ *  or floating type this can read. A project typedef (`Pt`) shows nothing. */
+function showsScalarReturn(p: FnProto | undefined): boolean {
+  return (
+    declaresVoidReturn(p) ||
+    (p?.returns !== undefined &&
+      !declaresAggregateReturn(p) &&
+      (declaredWidth(p.returns) !== undefined || isFloatingSpelling(p.returns)))
+  );
+}
+
+/** The parameter list the own declaration states, or where it states none the one a mangled symbol
+ *  records (`demangle`), as {@link ownArgumentWords} reads it. */
+function ownParamList(name: string, p: FnProto | undefined): (FnProto & { params: ParamType[] }) | undefined {
+  const mangled = Array.isArray(p?.params) ? null : demangle(name);
+  const decl: FnProto | undefined = Array.isArray(p?.params)
+    ? p
+    : mangled === null
+      ? undefined
+      : { params: mangled.params.map(spellType) };
+  return Array.isArray(decl?.params) ? (decl as FnProto & { params: ParamType[] }) : undefined;
+}
+
+/** HOW MANY OF THE FIRST ARGUMENT REGISTERS SURELY HOLD ONE OF THE FUNCTION'S OWN PARAMETERS, each a
+ *  single integer-class word — a LOWER bound, where {@link ownArgumentWords} is an upper one, and 0
+ *  where the declaration says nothing surely.
+ *
+ *  Its reader is the guessed-arity gap (`frontend/call-plan.ts` `decideGap`), which may read an
+ *  argument register left at its incoming value as an argument passed on only where that register
+ *  surely holds a parameter. So every "may" counts against it: a hidden word that may come first (a
+ *  return the declaration does not show is a scalar, a symbol that may be a method) makes it 0,
+ *  and the count stops at the first parameter that is not one integer word — a floating one may
+ *  travel in the FPU's registers and leave its general words holding nothing (O32's leading
+ *  float), a wide or unsized one takes words this does not place.
+ *
+ *  {@link ownLeadingWordRegisters} asks the other question the same run of parameters answers. */
+export function ownLeadingWordParams(
+  name: string,
+  p: FnProto | undefined,
+  target: Pick<TargetDescription, 'fpu' | 'evenWordAlignedArgs'>,
+  registerReturn = false,
+): number {
+  const decl = ownParamList(name, p);
+  const own = ownArguments(name, p, target, registerReturn);
+  return decl === undefined || own === undefined || own.hidden !== 0 ? 0 : leadingWordRun(decl);
+}
+
+/** HOW MANY OF THE FIRST ARGUMENT REGISTERS SURELY HOLD ONE INTEGER WORD, WHOEVER'S, by the own
+ *  declaration (or the parameter list a mangled symbol records), and 0 where it states no list. A
+ *  hidden word (a struct return's pointer, `this`, a constructor's flag) is a word too, and only
+ *  moves the parameters to later registers, so each of the first that-many registers holds a word
+ *  whichever way it falls, and a later parameter this cannot place does not move the ones before
+ *  it. Its reader is the Thumb frame's by-value home test (`frontend/thumb.ts` `argumentHomes`): a
+ *  register that surely holds a word is no by-value struct's home. */
+export function ownLeadingWordRegisters(name: string, p: FnProto | undefined): number {
+  const decl = ownParamList(name, p);
+  return decl === undefined ? 0 : leadingWordRun(decl);
+}
+
+/** The run of leading parameters that are each one integer-class word: it stops at the first
+ *  floating one or the first {@link paramClassOf} does not call `'word'`. */
+function leadingWordRun(decl: FnProto & { params: ParamType[] }): number {
+  let n = 0;
+  while (
+    n < decl.params.length &&
+    !isFloatingSpelling(decl.params[n]) &&
+    paramClassOf(decl, decl.params, n) === 'word'
+  ) {
+    n++;
+  }
+  return n;
+}
+
+/** Whether the own declaration (or the parameter list a mangled symbol records) states a floating
+ *  parameter, or `undefined` where it states no list. Its reader is the guessed-arity gap
+ *  (`frontend/call-plan.ts` `decidedCallRefusal`): a float may travel in an FPU register that no
+ *  guess counts. */
+export function ownDeclaresFloatingParam(name: string, p: FnProto | undefined): boolean | undefined {
+  return ownParamList(name, p)?.params.some((t) => isFloatingSpelling(t));
+}
+
+/** The widths `ownArgumentWords` lays out: one per declared parameter that takes general words. */
+function ownParamWidths(
+  name: string,
+  p: FnProto | undefined,
+  target: Pick<TargetDescription, 'fpu'>,
+): number[] | undefined {
+  const decl = ownParamList(name, p);
+  if (decl === undefined) {
+    return undefined;
+  }
+  const params = decl.params;
+  const widths: number[] = [];
+  for (const k of params.keys()) {
+    const cls = paramClassOf(decl, params, k);
+    if (cls === 'word' || cls === 'wide') {
+      widths.push(cls === 'word' ? 32 : (declaredWidth(params[k]) ?? 64));
+    } else if (cls === 'float') {
+      const bare = params[k]
+        .replace(/\b(?:const|volatile)\b/g, ' ')
+        .trim()
+        .replace(/\s+/g, ' ');
+      const spelled = FLOAT_TYPEDEFS.get(bare) ?? bare;
+      if (spelled === 'long double') {
+        return undefined;
+      }
+      // a `float` may be an old-style definition's, promoted to `double`
+      if (target.fpu?.slots !== 'separate') {
+        widths.push(64);
+      }
+    } else {
+      return undefined;
+    }
+  }
+  return widths;
+}
+
+/** Whether a declared type is `double`, qualifiers aside. */
+const isDoubleSpelling = (t: ParamType): boolean => t.replace(/\b(?:const|volatile)\b/g, ' ').trim() === 'double';
+
+/** The floating type a declared type is, qualifiers aside — a C keyword, or a typedef of one every
+ *  project declares (`FLOAT_TYPEDEFS`) — or undefined for any other type. */
+export const floatingSpelling = (t: ParamType): 'float' | 'double' | 'long double' | undefined => {
+  const bare = t
+    .replace(/\b(?:const|volatile)\b/g, ' ')
+    .trim()
+    .replace(/\s+/g, ' ');
+  const spelled = FLOAT_TYPEDEFS.get(bare) ?? bare;
+  return spelled === 'float' || spelled === 'double' || spelled === 'long double' ? spelled : undefined;
+};
+
+/** Whether a declared type is a floating type (`floatingSpelling`). */
+export const isFloatingSpelling = (t: ParamType): boolean => floatingSpelling(t) !== undefined;
+
+/** A signature the C standard fixes is a COMPLETE one, which an `FnProto` is not: a project
+ *  prototype is a lower bound assembled from whatever a header extraction could read, and omits
+ *  what it could not. The standard omits nothing, so the RETURN is spelled here and is required —
+ *  it is the fact `returnsWithoutHiddenPointer` needs and the fact no header ever supplied. */
+interface StandardSignature extends FnProto {
+  /** the return type, as its C spelling (`"void *"`, `"u32"`, `"void"`) */
+  returns: ParamType;
+  /** for a BLOCK COPY, the operand each role is: it reads `[0, n)` through `src`, writes `[0, n)`
+   *  through `dst`, and keeps neither address (`blockCopyRoles`) */
+  copies?: BlockCopyRoles;
+}
+
+/** The operands of a standard block copy, by role (`StandardSignature.copies`). */
+export interface BlockCopyRoles {
+  readonly dst: number;
+  readonly src: number;
+  readonly n: number;
+}
+
+/** Signatures FIXED BY THE C STANDARD, so they are not a project fact and need no header to be
+ *  known. Consumed by a frontend's arity lookup behind both the caller-supplied prototype and the
+ *  compiler's own runtime helpers (raise/softdiv.ts) — a project that declares one of these wins,
+ *  because a decomp may legitimately be building against its own re-declaration.
+ *
+ *  WHAT AN ENTRY BUYS, which is not the same as what it changes: the arity a call recovers is
+ *  usually the same number the arg-register heuristic already guessed, so an entry moves no code.
+ *  What it moves is what is KNOWN — a guess cannot witness anything, and an entry can. The
+ *  frame-object audit reads the `returns` of one to rule out a hidden struct-return pointer
+ *  (`aggregate.ts` `returnsWithoutHiddenPointer`, asked by frontend/frame-objects.ts).
+ *
+ *  THE LIST IS SHORT ON PURPOSE. `memcpy` is here because a corpus row exercises it and its price
+ *  was measured. `memset`, `strcpy` and the rest of the standard library are equally fixed by the
+ *  standard and equally addable, and they are absent because nothing measures them — a table
+ *  grown by appetite would be a table nobody priced. */
+export const STANDARD_SIGNATURES: Record<string, StandardSignature> = {
+  memcpy: { params: ['void *', 'const void *', 'u32'], returns: 'void *', copies: { dst: 0, src: 1, n: 2 } },
+};
+
+/** The roles of `callee`'s operands where the C standard fixes it as a BLOCK COPY, or `undefined`.
+ *  ONE TABLE for every reader: the frame audit bounds the bytes a copy with a literal count reaches
+ *  (frontend/frame-objects.ts `boundedCopy`), and the constant-initializer fold reads the copy an
+ *  aggregate initializer compiles to (l3/constinit.ts). `memmove` is equally fixed, and absent for
+ *  the reason the list above is short. */
+export function blockCopyRoles(callee: unknown): BlockCopyRoles | undefined {
+  return typeof callee === 'string' && Object.hasOwn(STANDARD_SIGNATURES, callee)
+    ? STANDARD_SIGNATURES[callee].copies
+    : undefined;
+}
+
+/** Whether a declaration says the function returns NO VALUE — the one question `returnsVoid` was
+ *  added for, asked through both keys that can answer it.
+ *
+ *  THE VALIDATOR'S MESSAGE CALLS THE TWO KEYS "one fact spelled two ways", and this is what makes
+ *  that true rather than a description of an intention. Before it, `returns: "void"` validated,
+ *  read as interchangeable, and did nothing at all on the function under decompilation: a void
+ *  function whose asm leaves garbage in r0 got `return <garbage>;` — a candidate that compiles and
+ *  scores, which is the exact defect `returnsVoid` exists to prevent. Every reader of the fact
+ *  calls this, so a key that validates is a key that acts.
+ *
+ *  ONE DIRECTION ONLY, and that asymmetry is the field's: `returnsVoid: false` states nothing that
+ *  any reader acts on (silence and "not void" take the same path), so this answers the positive
+ *  claim and leaves the rest to the machine. */
+export function declaresVoidReturn(p: FnProto | undefined): boolean {
+  return p?.returnsVoid === true || p?.returns?.trim() === 'void';
+}
+
+/** The bit width of the scalar the function UNDER DECOMPILATION declares it returns, or `undefined`
+ *  where its declaration states none this can read: no `returns`, a struct or union by value, a
+ *  floating type or a project typedef (`declaredWidth`'s "no opinion"). A pointer answers 32,
+ *  `long long` 64.
+ *
+ *  Not {@link declaredReturnWidth}, which answers for a CALLEE and only where the candidate can
+ *  print its declaration: the lifted function's own signature is the one the candidate defines,
+ *  so whether its parameters are spellable says nothing about what it returns. */
+export function ownReturnWidth(p: FnProto | undefined): number | undefined {
+  return p?.returns === undefined || declaresAggregateReturn(p) ? undefined : declaredWidth(p.returns);
+}
+
+/** Whether a declaration says nothing any reader acts on about the return — no spelling, no
+ *  layout, and no `returnsVoid: true`. `returnsVoid: false` is silence (`declaresVoidReturn`), and
+ *  it is how a manifest spells a callee it knows only the parameters of. Such an entry can take a
+ *  struct return another source states without contradicting itself. */
+export function statesNoReturn(p: FnProto): boolean {
+  return p.returns === undefined && p.returnsVoid !== true && p.returnLayout === undefined;
+}
+
+/** Whether a declaration says the function returns a struct or union by value — through either
+ *  key that can say it (`FnProto.returnLayout`). Read through `?.` for the reason
+ *  `returnsWithoutHiddenPointer` gives: a `null` entry out of parsed JSON reaches every reader. */
+export function declaresAggregateReturn(p: FnProto | undefined): boolean {
+  // the whole spelling, qualifiers aside — `struct S *` is a pointer, returned in a register
+  const bare = (p?.returns ?? '')
+    .replace(/\b(?:const|volatile)\b/g, ' ')
+    .trim()
+    .replace(/\s+/g, ' ');
+  return p?.returnLayout !== undefined || /^(?:struct|union) [A-Za-z_]\w*$/.test(bare);
+}
+
+/** Bit width per C89 base type on every target asmlift lifts (all ILP32 with a 64-bit `long long`).
+ *  `long` is 32 here and would not be on an LP64 host, so it is a target fact rather than a
+ *  language one.
+ *
+ *  THE FLOATING TYPES ARE ABSENT, and that is a measured ABI fact rather than a hole in the table.
+ *  How many argument registers a `float` or a `double` occupies is a property of the TARGET and
+ *  not of the spelling: `target.ts` declares `hwFloat` on three of its four descriptions, and on a
+ *  PowerPC EABI with an FPU a floating argument travels in f1..f8 and occupies NO general argument
+ *  register at all — compiled with the benchmark's own mwcc, `void g(int, double); void fa(int a,
+ *  double b){ g(a,b); }` sets up r3 and nothing else. The one consumer that lays out argument
+ *  registers would read a width here as "one register" or "a pair", and on those targets both are
+ *  wrong — so `declaredCallArgs` sizes a `double` from the target, and only where it states one;
+ *  `long double` is absent for the neighbouring reason, 8 bytes on these ABIs and 10 or 16
+ *  on others with nothing having measured which one a target's compiler means. A spelling this
+ *  table does not hold costs a caller nothing it was owed: `declaredCallArgs` abstains and the
+ *  machine's own guess stands, which is what the declaration replaced.
+ *
+ *  THE FIXED-WIDTH NAMES ARE FIXED BY THE STANDARD, not by a project, which is the same reason
+ *  `STANDARD_SIGNATURES` exists: `int32_t` is 32 bits wherever it compiles at all, and reading it
+ *  as "a project typedef" put `size_t` and `int64_t` — the spellings a header extraction produces
+ *  most — into the population that cannot be sized. */
 const BASE_WIDTHS: ReadonlyMap<string, number> = new Map([
   ['char', 8],
   ['short', 16],
@@ -75,23 +712,46 @@ const BASE_WIDTHS: ReadonlyMap<string, number> = new Map([
   ['int', 32],
   ['long', 32],
   ['long int', 32],
+  ['long long', 64],
+  ['long long int', 64],
+  ['int8_t', 8],
+  ['uint8_t', 8],
+  ['int16_t', 16],
+  ['uint16_t', 16],
+  ['int32_t', 32],
+  ['uint32_t', 32],
+  ['int64_t', 64],
+  ['uint64_t', 64],
+  ['size_t', 32],
+  ['ssize_t', 32],
+  ['ptrdiff_t', 32],
+  ['intptr_t', 32],
+  ['uintptr_t', 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.
+ *  read — a project typedef, a by-value struct, a floating type. UNDEFINED IS "NO OPINION", never
+ *  "wide": a 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. Its two readers differ in how
+ *  far the absence spreads, and that is a property of what they are asking rather than of this
+ *  answer: raise/paramwidth.ts abstains for that one parameter, and `declaredCallArgs` abstains
+ *  for the whole list, because one unknown width moves every later argument's home.
+ *
+ *  A pointer is register-wide whatever it points at (`isAddress`).
  *
- *  A pointer is register-wide whatever it points at, which is the fact the `*` test carries. */
+ *  A WIDTH WIDER THAN A REGISTER IS A READABLE ANSWER, not an absence. `long long` and `s64`/`u64`
+ *  answer 64, and that is a different fact from silence even though both refuse a narrowing: an
+ *  unreadable spelling MIGHT be wide, where a `long long` IS — which is what a reader asking how
+ *  many argument registers a parameter occupies has to be able to tell apart. */
 export function declaredWidth(t: ParamType): number | undefined {
   const s = t
     .replace(/\b(?:const|volatile)\b/g, ' ')
     .trim()
     .replace(/\s+/g, ' ');
-  if (s.endsWith('*')) {
+  if (isAddress(s)) {
     return 32;
   }
-  const own = /^([su])(8|16|32)$/.exec(s);
+  const own = /^([su])(8|16|32|64)$/.exec(s);
   if (own) {
     return Number(own[2]);
   }
@@ -103,12 +763,253 @@ export function declaredWidth(t: ParamType): number | undefined {
   return BASE_WIDTHS.get(base === '' && s !== '' ? 'int' : base);
 }
 
+/** Whether one declared parameter type spells a signed integer, or `undefined` where it does not say:
+ *  a project typedef, a pointer, a plain `char` (whose signedness is the compiler's). */
+export function declaredSigned(t: ParamType): boolean | undefined {
+  const s = t
+    .replace(/\b(?:const|volatile)\b/g, ' ')
+    .trim()
+    .replace(/\s+/g, ' ');
+  if (isAddress(s)) {
+    return undefined;
+  }
+  const own = /^([su])(8|16|32|64)$/.exec(s);
+  if (own) {
+    return own[1] === 's';
+  }
+  if (/\bunsigned\b/.test(s) || /^uint\d+_t$/.test(s)) {
+    return false;
+  }
+  return /\bsigned\b/.test(s) || /^int\d+_t$/.test(s) || /^(?:short|int|long)\b/.test(s) ? true : undefined;
+}
+
+/** Whether the type name `s` is a pointer by its abstract declarator, the derivation nearest the
+ *  absent name: `u8 *`, `void (*)(s32)`, `f32 (*)[3]`, `void (**)(void)`. A C++ pointer to a data
+ *  member is one too, and a pointer to a member function is not: compiled with mwcc GC/1.2.5n,
+ *  GC/1.3.2 and GC/2.6, `int T::*` is 4 bytes passed in one register, where `void (T::*)(int)` is
+ *  12, passed as the address of a copy the way a struct of that size is. A spelling with neither a
+ *  `(` nor a `::` is a pointer exactly when it ends in its `*`. */
+function isAddress(s: string): boolean {
+  if (!s.includes('(') && !s.includes('::')) {
+    return s.endsWith('*');
+  }
+  const [first, next] = parseTypeName(s)?.declarator.derivations ?? [];
+  return first?.kind === 'pointer' && !(first.member !== undefined && next?.kind === 'function');
+}
+
+/** The scalar vocabulary every candidate's prelude declares: the typedef NAME, and the C89 text it
+ *  stands for. `s64`/`u64` are spelt `long long` because every compiler this repo targets is a C89
+ *  one with the GNU/CW extension, which is what the projects themselves use.
+ *
+ *  THE DATA LIVES HERE AND `target.ts` PRINTS IT (`C_TYPEDEFS`), rather than the other way round,
+ *  because this file sits BELOW that one — `target.ts` imports `runtime-helpers.ts` which imports
+ *  this — and the two readers need the same answer. A COPY is what the import direction made
+ *  tempting and it is a defect either way round: a name listed here and not declared there prints
+ *  a type no translation unit defines, and a typedef declared there and not listed here is a
+ *  spelling asmlift refuses to print for no reason. One of those two directions is a compile
+ *  error in every candidate of the row, with nothing naming the cause, and a test over two lists
+ *  can only ever cover the direction someone thought of — measured: deleting `s64` from the old
+ *  `C_TYPEDEFS` left `proto.test.ts` green while `spellableType('s64')` still answered true. */
+export const PRELUDE_TYPEDEFS: ReadonlyMap<string, string> = new Map([
+  ['u8', 'unsigned char'],
+  ['u16', 'unsigned short'],
+  ['u32', 'unsigned int'],
+  ['s8', 'signed char'],
+  ['s16', 'short'],
+  ['s32', 'int'],
+  ['s64', 'long long'],
+  ['u64', 'unsigned long long'],
+]);
+
+/** The floating typedefs a decomp project declares (`f32`, `f64`), and the C keyword each stands for.
+ *  A candidate's prelude does not declare them: a candidate spells a float with the keyword
+ *  (backend/cfamily.ts), so a project context that typedefs them cannot collide with it. They are
+ *  read to tell that a declared spelling is floating. */
+const FLOAT_TYPEDEFS: ReadonlyMap<string, string> = new Map([
+  ['f32', 'float'],
+  ['f64', 'double'],
+]);
+
+/** The C89 integer bases, which need no declaration anywhere. `signed`/`unsigned` is stripped
+ *  before the lookup, exactly as {@link declaredWidth} strips it. */
+const C89_INTEGER_BASES: ReadonlySet<string> = new Set([
+  'char',
+  'short',
+  'short int',
+  'int',
+  'long',
+  'long int',
+  'long long',
+  'long long int',
+]);
+
+/** Whether asmlift may PRINT this type text into a candidate's translation unit.
+ *
+ *  SIZING AND SPELLING ARE DIFFERENT QUESTIONS AND THE SPELLABLE SET IS THE SMALLER ONE, which is
+ *  the whole reason this exists beside {@link declaredWidth}. `int32_t` and `size_t` have widths the
+ *  C standard fixes, so they size — and a candidate includes no header, so printing either is a
+ *  parse error. `Fixed64` sizes to nothing and prints to nothing. Measured with the project agbcc:
+ *  `Fixed64 DoThing(void);` and `int (*)(void) DoThing(void);` both exit 1 on a syntax error, and
+ *  a candidate whose TU does not compile loses every variation with nothing naming the cause.
+ *
+ *  SO THE VOCABULARY IS CLOSED AND SMALL: `void`, the C89 integer bases with any signedness, the
+ *  prelude's own typedefs, and a pointer to any of those. Everything else is silence, and silence
+ *  here means the callee is left undeclared exactly as it was before a prototype could declare one.
+ *
+ *  A POINTER'S POINTEE STILL HAS TO BE SPELLABLE, and that is the one place this is deliberately
+ *  STRICTER than the compiler: `struct Sprite * DoThing(struct Sprite *);` does compile (the tag is
+ *  declared by the prototype itself), while `Fixed64 *` does not, and both size to 32 through the
+ *  `*` rule — so sizing cannot tell them apart. One unspellable pointee loses every candidate for
+ *  the row, so the pointer form asks the same question of what it points at and a tagged pointer
+ *  goes undeclared rather than half-checked. A round that wants struct pointers declared owns
+ *  proving the tag is safe to mint; `void *` is the spelling that always works. */
+export function spellableType(t: ParamType): boolean {
+  const s = t
+    .replace(/\b(?:const|volatile)\b/g, ' ')
+    .trim()
+    .replace(/\s+/g, ' ');
+  const bare = s.replace(/[\s*]*\*$/, '').trim();
+  if (bare === '') {
+    return false;
+  }
+  if (bare === 'void' || PRELUDE_TYPEDEFS.has(bare)) {
+    return true;
+  }
+  const base = bare
+    .replace(/\b(?:signed|unsigned)\b/g, ' ')
+    .trim()
+    .replace(/\s+/g, ' ');
+  // `unsigned` alone is `unsigned int`. `unsigned Fixed64` is not a type, so a signedness keyword
+  // only ever qualifies a C89 base — a typedef that survived the set test above is rejected here.
+  return C89_INTEGER_BASES.has(base === '' && base !== bare ? 'int' : base);
+}
+
+/** The C prototype an `FnProto` states, or `undefined` where it does not state one this can print.
+ *
+ *  ONE ADMISSION RULE FOR BOTH READERS OF `returns`, and that is what this function is for. The
+ *  frontend reads the return WIDTH off a declaration to decide whether a callee hands back a
+ *  register pair; `declare.ts` prints the declaration into the candidate's own translation unit.
+ *  Those two have to admit the same table or the pipeline lifts a pair and then compiles it against
+ *  an implicitly-`int` callee — measured with the project agbcc, `bl llsrc ; add r0, r1, #0` with
+ *  the declaration and `bl llsrc ; mov r1,#0x20 ; asr r0,r0,r1` without it. A different program,
+ *  and the row simply nonmatches with nothing saying why. So {@link declaredReturnWidth} is defined
+ *  on top of this rather than beside it.
+ *
+ *  COMPLETE MEANS BOTH HALVES, IN TYPES THIS CAN SPELL. A `returns` is required — a proto without
+ *  one states no return type. A parameter LIST is required and every entry must be spellable; the
+ *  zero-argument COUNT form is admitted too, because `params: 0` and `params: []` are the same
+ *  `(void)`, but a count above zero names no C type and cannot be printed. None of those is a
+ *  defect in the proto — all are the common shape — and the answer for them is what it has always
+ *  been, which is to leave the callee undeclared.
+ *
+ *  WHAT THIS PRINTS, THE FRONTEND MUST ALSO BE ABLE TO SIZE, and the two exclusions below are what
+ *  make that true rather than nearly true. Both were reachable and both killed the whole row:
+ *
+ *    `void` AS A PARAMETER. `spellableType` admits it for the RETURN, and `(void)` is C's
+ *    parameterless list — but `declaredWidth('void')` is no width, so `declaredCallArgs` abstains
+ *    and the call is emitted at the arg-register GUESS while the declaration beside it says the
+ *    callee takes nothing. Measured with the project agbcc: `long long DoThing(void);` over
+ *    `DoThing(&DoThing)` is "too many arguments to function `DoThing'", exit 1. The empty list is
+ *    how a parameterless callee is stated and it already prints `(void)`.
+ *
+ *    `void` AS THE RETURN, which is `returnsVoid` under the other spelling ({@link
+ *    declaresVoidReturn} is where the two are one fact). The Thumb and PowerPC lowerings read the
+ *    return register whatever the callee is (`CallLowering.voidReturn`), so `void DoThing(void);`
+ *    printed beside a candidate that USES the result is "void value not ignored as it ought to be",
+ *    exit 1 on the same compiler. It is also what the paragraph below already decided: `returnsVoid` is not a
+ *    source for the printed prototype, and one fact cannot be barred under one spelling and
+ *    admitted under the other. So what this prints is always a VALUE-returning prototype, which is
+ *    what makes {@link declaredReturnWidth} total on its output.
+ *
+ *  `returnsVoid` IS NOT A SECOND SOURCE FOR THE RETURN, and that is a measured decision rather
+ *  than an oversight. `grep -rh '"returnsVoid": true' apps/benchmark/dataset/real/*.json | wc -l`
+ *  prints 175, across all 8 vendored manifests. It is documented UNCHECKED data whose wrong value
+ *  already turns a loud decline into a compiling wrong program, and reading it here would put that
+ *  field into 175 real candidates' own translation units at a price nothing has measured — a
+ *  different change, with a bench behind it, from the one this makes. `returns` states a return
+ *  TYPE, nothing carries it yet, and a project that wants the prototype emitted spells it. */
+export function spellableProto(
+  p: FnProto | undefined,
+  target: Pick<TargetDescription, 'doubleArgWords'>,
+  returned?: IrType,
+  byValue?: ReadonlySet<number>,
+): { readonly params: readonly ParamType[]; readonly returns: ParamType } | undefined {
+  // A struct returned through memory prints as the headers spell the struct the lift typed its call
+  // as (`returned`), which the declarations block defines beside this prototype (declare.ts). With
+  // no such call it is a return this cannot print.
+  // A callee passed a struct by value prints whenever its declaration is complete, `returnsVoid`
+  // standing for `void`: the struct is defined only beside it, and the local the lift passes is of
+  // that type, so without it the candidate cannot declare its own local.
+  const passesStruct = byValue !== undefined && byValue.size > 0;
+  const returns =
+    returned?.kind === 'struct'
+      ? (returned.declared ?? `struct ${returned.name}`)
+      : (p?.returns ?? (passesStruct && p?.returnsVoid === true ? 'void' : undefined));
+  if (
+    p === undefined ||
+    returns === undefined ||
+    (returned === undefined &&
+      !(passesStruct && returns.trim() === 'void') &&
+      (!spellableType(returns) || declaredWidth(returns) === undefined))
+  ) {
+    return undefined;
+  }
+  if (p.params === 0) {
+    return { params: [], returns };
+  }
+  // A parameter prints where the frontend lays it out (`declaredCallArgs`): a type this spells, or a
+  // `double` the target gives general words, which as a C keyword needs no typedef — or a struct
+  // the lift passed by value (`byValue`, by parameter index), which the declarations block defines
+  // beside this prototype from its `byValueLayouts`, as it defines a returned one.
+  if (Array.isArray(p.params) && byValue !== undefined && passesStruct) {
+    const params = p.params;
+    const rest = params.map((t, i) => (byValue.has(i) ? 'u32' : t));
+    const laid = declaredCallArgs({ ...p, params: rest }, target);
+    return laid !== undefined &&
+      [...byValue].every((i) => p.byValueLayouts !== undefined && Object.hasOwn(p.byValueLayouts, i)) &&
+      rest.every((t, i) => laid.doubles.has(i) || spellableType(t))
+      ? { params, returns }
+      : undefined;
+  }
+  const laid = declaredCallArgs(p, target);
+  return Array.isArray(p.params) &&
+    laid !== undefined &&
+    p.params.every((t, i) => laid.doubles.has(i) || spellableType(t))
+    ? { params: p.params, returns }
+    : undefined;
+}
+
+/** The bit width a declaration states its callee RETURNS, or `undefined` when it states nothing a
+ *  reader can act on — which is exactly a proto {@link spellableProto} cannot print.
+ *
+ *  IT IS GATED ON BEING SPELLABLE, not merely on being sizable, and that gate is the soundness of
+ *  the whole reading: a width read here makes the frontend name a second register, and that is only
+ *  the right lift if the candidate's own translation unit declares the callee the same way. The two
+ *  questions are asked through one function so they cannot answer differently — and the answer is
+ *  the RESOLVED table (`prototypesFromSymbols`), which is where a proto the symbol map contradicts
+ *  has already lost its `returns`, so the frontend and the printer see one decision.
+ *
+ *  `returnsVoid` is not consulted and must not be: a void return is not a width of zero, it is the
+ *  absence of a returned value, and the one consumer here asks how many registers come back with a
+ *  value in them. `validatePrototypes` is what keeps the two from contradicting each other.
+ *
+ *  A DESIGNATED SAFE READER, the way `declaredCallArgs` is one: a frontend indexes `prototypes` by a
+ *  callee's name, and a callee named `toString` reads a `Function` off `Object.prototype` — which
+ *  has no `returns`, so it answers here what an undeclared callee answers. */
+export function declaredReturnWidth(
+  p: FnProto | undefined,
+  target: Pick<TargetDescription, 'doubleArgWords'>,
+): number | undefined {
+  const spelled = spellableProto(p, target);
+  return spelled === undefined ? undefined : declaredWidth(spelled.returns);
+}
+
 /** 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. */
+ *  `declaredCallArgs` 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'];
@@ -120,30 +1021,228 @@ export function validatePrototypes(value: unknown): string[] {
       continue;
     }
     for (const key of Object.keys(proto)) {
-      if (key !== 'params' && key !== 'returnsVoid') {
-        problems.push(`${sym}: unknown key "${key}" (expected "params" or "returnsVoid")`);
+      if (
+        key !== 'params' &&
+        key !== 'returnsVoid' &&
+        key !== 'returns' &&
+        key !== 'returnLayout' &&
+        key !== 'wordParams' &&
+        key !== 'byValueParams' &&
+        key !== 'byValueLayouts' &&
+        key !== 'variadicParams' &&
+        key !== 'fromContext'
+      ) {
+        problems.push(
+          `${sym}: unknown key "${key}" (expected "params", "returnsVoid", "returns", "returnLayout", "wordParams", ` +
+            '"byValueParams", "byValueLayouts", "variadicParams" or "fromContext")',
+        );
       }
     }
-    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 ('fromContext' in proto && typeof (proto as { fromContext?: unknown }).fromContext !== 'boolean') {
+      problems.push(`${sym}: "fromContext" must be a boolean`);
+    }
+    const { params, returnsVoid, returns, returnLayout, wordParams, byValueParams, byValueLayouts, variadicParams } =
+      proto as {
+        params?: unknown;
+        returnsVoid?: unknown;
+        returns?: unknown;
+        returnLayout?: unknown;
+        wordParams?: unknown;
+        byValueParams?: unknown;
+        byValueLayouts?: unknown;
+        variadicParams?: unknown;
+      };
+    // a variadic declaration's fixed parameters, which it states beside no typed list
+    if (
+      variadicParams !== undefined &&
+      !(Array.isArray(variadicParams) && variadicParams.every((t) => typeof t === 'string') && params === undefined)
+    ) {
+      problems.push(`${sym}: "variadicParams" must be a list of parameter types, beside no "params"`);
+    }
+    const listed = Array.isArray(params) ? params : Array.isArray(variadicParams) ? variadicParams : undefined;
+    for (const [key, list] of [
+      ['wordParams', wordParams],
+      ['byValueParams', byValueParams],
+    ] as const) {
+      if (
+        list !== undefined &&
+        !(
+          listed !== undefined &&
+          Array.isArray(list) &&
+          list.every((k) => Number.isInteger(k) && k >= 0 && k < listed.length)
+        )
+      ) {
+        problems.push(`${sym}: "${key}" must list indices into a typed "params" or "variadicParams" list`);
       }
     }
+    // Two answers to one question — whether the parameter travels in a register or as a copy.
+    if (
+      Array.isArray(wordParams) &&
+      Array.isArray(byValueParams) &&
+      wordParams.some((k) => byValueParams.includes(k))
+    ) {
+      problems.push(`${sym}: "wordParams" and "byValueParams" both list one parameter`);
+    }
+    // A layout keyed by a parameter the list does not pass by value would size a word as a struct.
+    if (byValueLayouts !== undefined) {
+      if (typeof byValueLayouts !== 'object' || byValueLayouts === null || Array.isArray(byValueLayouts)) {
+        problems.push(`${sym}: "byValueLayouts" must map a parameter index to its layout`);
+      } else {
+        for (const [key, layout] of Object.entries(byValueLayouts)) {
+          const k = Number(key);
+          if (
+            !Array.isArray(params) ||
+            !params.every((t) => typeof t === 'string') ||
+            !/^\d+$/.test(key) ||
+            k >= params.length ||
+            paramClassOf(
+              {
+                wordParams: Array.isArray(wordParams) ? wordParams : [],
+                byValueParams: Array.isArray(byValueParams) ? byValueParams : [],
+              },
+              params,
+              k,
+            ) !== 'by-value'
+          ) {
+            problems.push(`${sym}: "byValueLayouts" key "${key}" is not a parameter the typed "params" pass by value`);
+            continue;
+          }
+          problems.push(...layoutProblems(`${sym}: "byValueLayouts" ${key}`, layout));
+        }
+      }
+    }
+    if (returnLayout !== undefined) {
+      problems.push(...layoutProblems(`${sym}: "returnLayout"`, returnLayout));
+      // A layout beside a return that says `void` or spells a scalar is two answers to one question
+      // — whether the call hands the callee a hidden pointer — and neither can be picked.
+      if (
+        returnsVoid === true ||
+        (typeof returns === 'string' && (returns.trim() === 'void' || declaredWidth(returns) !== undefined))
+      ) {
+        problems.push(
+          `${sym}: "returnLayout" says the return is a struct or union, and the return is also declared scalar or void`,
+        );
+      }
+    }
+    const countOk = typeof params === 'number' && Number.isInteger(params) && params >= 0;
+    const listOk = Array.isArray(params) && params.every((t) => typeof t === 'string');
+    if (params !== undefined && !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`);
     }
+    if (returns !== undefined && typeof returns !== 'string') {
+      problems.push(`${sym}: "returns" must be a type string, e.g. "long long"`);
+    }
+    // The two return keys are one fact spelled two ways (`declaresVoidReturn` is where both are
+    // read), and a table that says both DIFFERENTLY is a table whose author meant one of them.
+    // Neither reading is safe to pick: honouring `returnsVoid` would silently drop a pair the other
+    // key says comes back, and honouring `returns` would license an out-parameter frame the `void`
+    // was there to rule out. BOTH directions are a contradiction, because both are now read — an
+    // explicit `returnsVoid: false` beside `returns: "void"` is the same disagreement written the
+    // other way round, and checking one direction while claiming to check the fact is a completeness
+    // the code would not have.
+    if (
+      typeof returnsVoid === 'boolean' &&
+      typeof returns === 'string' &&
+      returnsVoid !== (returns.trim() === 'void')
+    ) {
+      problems.push(`${sym}: "returnsVoid" is ${returnsVoid} but "returns" says "${returns}"`);
+    }
+    // A `returns` WIDER THAN A REGISTER IS THE ONE THAT NEEDS THE WHOLE PROTOTYPE, and a table
+    // that states one the rest of the entry cannot carry is a table whose author will see nothing
+    // happen. A register-width return is not checked here because it is not inert — it rules out a
+    // hidden struct-return pointer (`returnsWithoutHiddenPointer`) whatever else the entry says —
+    // but the register PAIR is read only where the callee's own declaration can be printed into
+    // the candidate, so a wide `returns` behind an unprintable `params`, or spelled in a type no
+    // candidate's prelude declares, buys exactly nothing and says so nowhere. Naming the gate is
+    // the point: the refusal the user then meets is `frontend/ssa.ts` reporting a destroyed
+    // register, which is true about the bytes and silent about their prototype.
+    const shaped: FnProto | undefined =
+      typeof returns === 'string' && (params === undefined || countOk || listOk)
+        ? { ...(params === undefined ? {} : { params: params as number | ParamType[] }), returns }
+        : undefined;
+    // A table is checked for no target, so a `double` parameter counts as one no target lays out.
+    if (
+      shaped !== undefined &&
+      (declaredWidth(shaped.returns!) ?? 0) > 32 &&
+      spellableProto(shaped, {}) === undefined
+    ) {
+      problems.push(
+        `${sym}: "returns": ${JSON.stringify(shaped.returns)} is wider than a register, and the pair it ` +
+          'comes home in is read only where the whole prototype can be printed into the candidate — so ' +
+          '"params" must be a list of spellable C types (or 0), and the return must be spelled ' +
+          `"long long" or ${[...PRELUDE_TYPEDEFS.keys()]
+            .filter((n) => (declaredWidth(n) ?? 0) > 32)
+            .map((n) => JSON.stringify(n))
+            .join('/')}`,
+      );
+    }
   }
   return problems;
 }
 
+/** Problems with one hand-written {@link AggregateLayout}, each prefixed with `where`. */
+function layoutProblems(where: string, value: unknown): string[] {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return [`${where} must be an object, e.g. {"kind": "struct"}`];
+  }
+  const problems: string[] = [];
+  for (const key of Object.keys(value)) {
+    if (key !== 'kind' && key !== 'members') {
+      problems.push(`${where}: unknown key "${key}" (expected "kind" or "members")`);
+    }
+  }
+  const { kind, members } = value as { kind?: unknown; members?: unknown };
+  if (kind !== 'struct' && kind !== 'union') {
+    problems.push(`${where}: "kind" must be "struct" or "union"`);
+  }
+  if (members === undefined) {
+    return problems;
+  }
+  if (!Array.isArray(members)) {
+    return [...problems, `${where}: "members" must be a list`];
+  }
+  members.forEach((m: unknown, i) => {
+    const at = `${where}: member ${i + 1}`;
+    if (typeof m !== 'object' || m === null || Array.isArray(m)) {
+      problems.push(`${at} must be an object, e.g. {"name": "w", "type": "u32", "dims": [16]}`);
+      return;
+    }
+    for (const key of Object.keys(m)) {
+      if (key !== 'name' && key !== 'type' && key !== 'dims' && key !== 'bits') {
+        problems.push(`${at}: unknown key "${key}" (expected "name", "type", "dims" or "bits")`);
+      }
+    }
+    const { name, type, dims, bits } = m as { name?: unknown; type?: unknown; dims?: unknown; bits?: unknown };
+    const positive = (n: unknown): boolean => typeof n === 'number' && Number.isInteger(n) && n > 0;
+    if (typeof name !== 'string' || !(/^[A-Za-z_]\w*$/.test(name) || (name === '' && bits !== undefined))) {
+      problems.push(`${at}: "name" must be a C identifier (empty only for an unnamed bitfield)`);
+    }
+    if (typeof type !== 'string') {
+      problems.push(...layoutProblems(`${at}: "type"`, type));
+    }
+    if (dims !== undefined && !(Array.isArray(dims) && dims.length > 0 && dims.every(positive))) {
+      problems.push(`${at}: "dims" must be a list of positive integers`);
+    }
+    if (bits !== undefined && !(typeof bits === 'number' && Number.isInteger(bits) && bits >= 0 && bits <= 64)) {
+      problems.push(`${at}: "bits" must be an integer from 0 to 64`);
+    }
+    if (bits !== undefined && dims !== undefined) {
+      problems.push(`${at}: a bitfield has no extents`);
+    }
+  });
+  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. 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). */
+ *  would move no byte: `declaredWidth` answers 32 for every `*`, and a CALLEE's parameter types
+ *  are read for the register widths they sum to (test/param-pointee-variation.test.ts). The one
+ *  reader of a pointee's spelling is a C++ call argument's cast, which a header's declaration
+ *  supplies (proto-context.ts, whose sized entries win over this one). */
 function typeSpelling(t: SymbolTypeFacts): ParamType | null {
   if (t.pointer) {
     return 'void *';
@@ -159,17 +1258,61 @@ function typeSpelling(t: SymbolTypeFacts): ParamType | null {
   return null;
 }
 
+/** The prototype a code symbol's DWARF signature states, or `undefined` when it states none this
+ *  can spell — every parameter must spell faithfully (see `prototypesFromSymbols`).
+ *
+ *  A STRUCT OR UNION RETURN IS KEPT WHEN THE PARAMETERS ARE NOT, because it is what says argument 0
+ *  may be a hidden pointer, and a call read without it names that pointer as the first argument.
+ *  DWARF sizes the return and states no kind: a base type carries a sign and a pointer says so, so
+ *  a signless non-pointer return is an enum, a struct or a union — and one wider than a word is not
+ *  an enum on any target here. The layout it states has no members, which is how a call to it
+ *  declines. KNOWN GAP: a signless return of a word or less is an enum or a small aggregate, and
+ *  nothing here tells them apart, so it states nothing — agbcc returns `struct { u16 a, b; }` through
+ *  memory, and a call storing one straight into a global lifts with the pointer as argument 0. */
+export function symbolPrototype(info: SymbolInfo): FnProto | undefined {
+  if (info.kind !== 'code' || !info.signature) {
+    return undefined;
+  }
+  const r = info.signature.returns;
+  const aggregate = r !== null && r.signed === null && r.pointer !== true && r.size !== null && r.size > 4;
+  const layout = aggregate ? { returnLayout: { kind: 'struct' as const } } : {};
+  const params = info.signature.params.map(typeSpelling);
+  if (params.some((p) => p === null)) {
+    return aggregate ? layout : undefined;
+  }
+  return { params: params as ParamType[], ...(r === null ? { returnsVoid: true } : {}), ...layout };
+}
+
 /**
  * Prototypes the project's own DWARF states, merged UNDER the caller's.
  *
  * A caller-supplied proto always wins: it comes from the user's headers or the benchmark
  * manifest, and it is the thing a real user actually has for the function they are decompiling.
+ * The one fact it takes from the map is a struct return, and only when it says nothing of its own
+ * return (`statesNoReturn`).
  * The map fills the rest — in practice the CALLEES, since a function still written in assembly
  * has no signature in its project's ELF (see SymbolSignature).
  *
  * Every parameter must spell faithfully or the whole entry is dropped: a partly-typed list would
  * be read for its LENGTH and give the right arity with the wrong widths, which is worse than the
  * arg-register heuristic it would replace.
+ *
+ * AND IT IS WHERE THE TWO SOURCES ARE RECONCILED, not merely merged, because this is the one
+ * lookup every reader of the table goes through: `pipeline.ts` and `rank.ts` each call this once
+ * and hand the RESULT to the frontend and to the declaration collector alike. A guard put at one
+ * of those readers instead leaves the other acting on a fact it has withheld — measured, with the
+ * map calling `llsrc` a shaped data object and the proto calling it a `long long` function, the
+ * declaration was withheld and the register pair was lifted anyway, so the candidate compiled
+ * against an implicitly-`int` callee: `bl llsrc ; mov r1,#0x20 ; asr r0,r0,r1` where the target
+ * has `bl llsrc ; add r0,r1,#0`. Adding map knowledge made the tool strictly worse.
+ *
+ * A DISAGREEMENT COSTS THE `returns` AND NOTHING ELSE. The map stating a data SHAPE for a name
+ * contradicts a return type — `long long g(void);` is not a declaration of a byte the project
+ * calls `u8` — and that is the fact both readers need to lose together. The rest of the entry is
+ * untouched: `params` says how many argument registers the call occupies, which nothing about the
+ * name being data makes wrong, and dropping it would change the arity of calls nothing has
+ * measured. A `kind: 'data'` entry with no shape is not the disagreement (see l3/symbol-refs.ts:
+ * that is what a map-less lift mints for every name the IR mentions).
  */
 export function prototypesFromSymbols(symbols: SymbolMap | undefined, base: Prototypes = {}): Prototypes {
   if (!symbols) {
@@ -178,17 +1321,28 @@ export function prototypesFromSymbols(symbols: SymbolMap | undefined, base: Prot
   const out: Prototypes = { ...base };
   for (const infos of symbols.values()) {
     for (const info of infos) {
-      if (info.kind !== 'code' || !info.signature || out[info.name] !== undefined) {
-        continue;
+      if (info.kind !== 'code' && (info.shape !== undefined || info.declared === true)) {
+        const stated = Object.hasOwn(out, info.name) ? out[info.name] : undefined;
+        if (stated?.returns !== undefined) {
+          const { returns: _dropped, ...rest } = stated;
+          out[info.name] = rest;
+        }
       }
-      const params = info.signature.params.map(typeSpelling);
-      if (params.some((p) => p === null)) {
+      const signed = symbolPrototype(info);
+      const held = out[info.name];
+      if (held !== undefined) {
+        // AN ENTRY THAT SAYS NOTHING OF THE RETURN STILL TAKES THE MAP'S STRUCT RETURN, which is
+        // what says argument 0 may be a hidden pointer; without it that pointer is read as the
+        // first declared argument. A header whose return spelling this could not read (`Blob64T`,
+        // defined behind an `#include`) is such an entry too.
+        if (signed?.returnLayout !== undefined && statesNoReturn(held)) {
+          out[info.name] = { ...held, returnLayout: signed.returnLayout };
+        }
         continue;
       }
-      out[info.name] = {
-        params: params as ParamType[],
-        ...(info.signature.returns === null ? { returnsVoid: true } : {}),
-      };
+      if (signed !== undefined) {
+        out[info.name] = signed;
+      }
     }
   }
   return out;