@asmlift/core 0.9.0 → 0.11.0

package/src/pipeline.ts

@@ -1,22 +1,36 @@
 // asmlift — the library entry point. `decompile(name, asm, target)` runs the raising tower and
 // returns structured results: the source, the per-level IR dumps, and diagnostics.
+import { aggregateSize, ownArgumentWordsOn, returnedAggregate, returnsInMemory } from './aggregate';
 import { cBackend } from './backend/c';
 import {
   ContractError,
   assertDerefsTyped,
   assertEffectsPreserved,
+  assertFrameUnionsViewed,
   assertLocalsWritten,
   assertPostIncrUnshared,
   assertResolved,
   assertTypesRecovered,
 } from './contracts';
-import type { AsmData } from './frontend/asmdata';
+import type { AsmData, Reloc } from './frontend/asmdata';
+import { returnedStruct, structLocalType } from './frontend/call-plan';
+import {
+  type CalleeBodies,
+  type CalleeBodyBound,
+  type CalleeStackWords,
+  calleeBodyReads,
+} from './frontend/callee-body';
 import { FrontendUnsupportedError } from './frontend/errors';
+import type { LiftOptions } from './frontend/frontend';
+import { liftOwnRegisterStruct, liftOwnStructReturn } from './frontend/own-struct-return';
+import { liftRegisterStructCalls } from './frontend/register-struct-call';
 import { frontendFor } from './frontend/registry';
+import { ABSORBED_KEYS, HOMED_UNDEF } from './frontend/ssa';
 import { type Fn, reachableBlocks } from './ir/core';
+import { deadOps } from './ir/discipline';
 import { print } from './ir/print';
-import { firstTrivialPhi } from './ir/simplify';
-import { T } from './ir/types';
+import { firstTrivialPhi, pruneDeadParams } from './ir/simplify';
+import { type IrType, T, intWidth } from './ir/types';
 import { VerifyError, verify } from './ir/verify';
 import { LanguageBackend, SFn, gapReasonFor, walkExprs } from './l3/ast';
 import { BASECSE_GATES, hoistBaseLocals } from './l3/basecse';
@@ -24,16 +38,32 @@ import { eliminateDeadStores } from './l3/dce';
 import { mergeCommonTails } from './l3/tailmerge';
 import { dropUnspelledReturns } from './l3/tailret';
 import { DEFAULT_IDIOM_PATTERNS, RewritePattern, applyPattern, dce, patternApplies } from './pattern/engine';
-import { type FnProto, type Prototypes, declaresVoidReturn, prototypesFromSymbols } from './proto';
-import { stampDeclaredVolatileUnder } from './raise/declared-volatile';
+import {
+  type FnProto,
+  type Prototypes,
+  declaresAggregateReturn,
+  declaresVoidReturn,
+  ownReturnWidth,
+  prototypesFromSymbols,
+} from './proto';
+import { type ContextGlobals, splitOwnContext } from './proto-context';
+import { type StampBehaviors, stampDeclaredVolatileUnder } from './raise/declared-volatile';
 import { RaiseUnsupportedError } from './raise/errors';
 import { assumedShapes, inferGlobalArrays, orderLicensedGlobals } from './raise/globalshape';
-import { foldEmptyLatches } from './raise/latch';
-import { OFFSET_NAME_PASS } from './raise/offsetnames';
+import { OFFSET_NAME_PASS, type OffsetNameBehaviors } from './raise/offsetnames';
 import { type PreRecoveryOptions, type PreRecoveryPass, runPreRecovery } from './raise/pre-recovery';
+import { PRE_STRUCTURE_FOLDS, type PreStructureFold } from './raise/pre-structure';
 import { recoverTypes } from './raise/recover';
 import { sinkReturns } from './raise/retsink';
-import { StructureError, structure } from './structure/structure';
+import { crossJumpedTail } from './structure/cross-jumped-tail';
+import {
+  DefaultAcceptsMemo,
+  DefaultAcceptsMemoMisuse,
+  type JoinPastReturnsSite,
+  StructureError,
+  structure,
+} from './structure/structure';
+import { unfoldedBranchConstant } from './structure/unfolded-branch-constant';
 import { type SymbolInfo, type SymbolMap, symbolsByName } from './symbols';
 import { type TargetDescription, structureOptionsFor } from './target';
 
@@ -73,8 +103,33 @@ export interface DecompileOptions {
    *  declaration shapes (DWARF types-sidecar). Drives the Thumb numeric-pool promotion and the
    *  byte-sensitive global spellings. Absent ⇒ byte-identical to today. */
   symbols?: SymbolMap;
+  /** what the project's declaration context states about its globals (proto-context.ts
+   *  `globalsFromContext`): no aggregate is spelled as a bare scalar name, and every access to a
+   *  volatile object the map does not lay out, or through a pointer to one, is stamped
+   *  (raise/declared-volatile.ts), so the cast it is read through carries the qualifier. */
+  contextGlobals?: ContextGlobals;
+  /** the declaration context's own entry for `name` (proto-context.ts `ownContextEntry`), which
+   *  bounds the argument registers SOFTLY where `prototypes` states no entry for it, and whose
+   *  struct return, where it declares one, is lifted where the machine proves it (`liftStamped`);
+   *  absent ⇒ nothing bounds them softly. A `prototypes` entry for `name` marked
+   *  `fromContext` is read as this, and taken out of the table (proto-context.ts
+   *  `splitOwnContext`). */
+  ownContextProto?: FnProto;
+  /** OPTIONAL bodies of callees the input does not define, found elsewhere by the driver (the CLI
+   *  reads them off `tools.asmlift.elf`): each answers what its callee can read of its arguments
+   *  where the input holds no label of that name (frontend/callee-body.ts). Absent ⇒ only the
+   *  input's own bodies answer. */
+  calleeBodies?: CalleeBodies;
   /** gap policy — see `OnGap`. Default "strict". */
   onGap?: OnGap;
+  /** force the return-tail copies (`StructureOptions.copyReturnTails`, rank.ts's `/ret-copy`).
+   *  Absent ⇒ the shorter of the copies and the join past early returns, ties to the join
+   *  (`structureReturnTailReading`). */
+  copyReturnTails?: boolean;
+  /** force the join past early returns wherever the structuring takes it, however long it spells
+   *  the function (rank.ts's `/ret-join` where the copies are the shorter). Absent ⇒ the shorter,
+   *  as above. Ignored under `copyReturnTails`. */
+  joinPastReturns?: boolean;
 }
 
 export interface DecompileResult {
@@ -120,6 +175,23 @@ export interface DecompileResult {
    *  `stage:offsetnames`), and it is also the only thing in a result that says a walk spelling
    *  stopped being enumerable here. Empty on every run with no symbol map. */
   walkedNames: string[];
+  /** WHERE THE LIFT WENT PAST ITS CONTEXT DECLARATION (`liftStamped`'s `[own-arity]` notes): each
+   *  names the declaration and either the argument registers the body reads past it, kept as
+   *  parameters, or the refusal that made the lift drop the bound. A note is no gap, but the
+   *  parameter list printed contradicts the header, which every compiler here rejects as
+   *  conflicting types. Empty where no context entry was handed over, or where the lift stayed
+   *  within it. */
+  ownArityNotes: string[];
+  /** WHICH BODIES HANDED IN (`DecompileOptions.calleeBodies`) THE LIFT ASKED, and what each answered
+   *  (frontend/callee-body.ts): the argument words that callee's body reads at most. A call asks only
+   *  where a gate questions a register the caller did not set up for it, and only of a callee whose
+   *  entry states no parameter list (frontend/call-plan.ts `bodyWords`), so a body handed in that no
+   *  call asked, or that answered nothing, is not here. Empty where no bodies were handed in. */
+  calleeBodiesAsked: Record<string, number>;
+  /** WHICH CALLEES NOTHING DECLARES THE LIFT SIZED OFF THEIR OWN BODIES, with the stack words each was
+   *  laid out at past the argument registers (frontend/callee-body.ts `CalleeStackWords`): a call to
+   *  one takes every argument register and those words, no guess. Empty where none was. */
+  calleeStackSized: Record<string, number>;
 }
 
 export function decompile(
@@ -153,9 +225,24 @@ function runTower(
   const backend = opts.backend ?? cBackend;
   // The project's own DWARF signatures fill in what the caller did not state — in practice the
   // CALLEES (a function still in assembly has none), which is what makes this transferable.
-  const prototypes = prototypesFromSymbols(opts.symbols, opts.prototypes ?? {});
+  const own = splitOwnContext(opts.prototypes, name, opts.ownContextProto);
+  const prototypes = prototypesFromSymbols(opts.symbols, own.prototypes ?? {});
   // (1) lift: ISA frontend (resolved by target) → L1 with block-argument SSA
-  const fn = liftStamped(name, asm, target, prototypes, opts.asmData, opts.symbols);
+  const ownArityNotes: string[] = [];
+  const bodiesAsked = new Map<string, number | undefined>();
+  const stacksSized = new Map<string, number>();
+  const fn = liftStamped(
+    name,
+    asm,
+    target,
+    prototypes,
+    opts.asmData,
+    opts.symbols,
+    opts.contextGlobals,
+    { calleeBodies: opts.calleeBodies, bodiesAsked, stacksSized },
+    own.ownContextProto,
+    ownArityNotes,
+  );
   // 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 });
@@ -178,7 +265,15 @@ function runTower(
   // `inferredSymbols`, and the ORDER licence only enables a cast spelling that is byte-correct
   // under any declaration. Measured: with this call moved ABOVE both readings, the three corpus
   // rows the pass fires on keep their fan size, their winner and their score exactly.
-  const walkedNames = opts.symbols ? OFFSET_NAME_PASS.run(fn, opts.symbols, target.compilerBehaviors) : [];
+  //
+  // The pass is also where the lift's names become final, so it DECLINES the function — whether or
+  // not it named anything — when two accesses reach one cell under two spellings, or one spelling
+  // reaches two of the cells the map places a name at (raise/offsetnames.ts `cellSpelledTwice`,
+  // RaiseUnsupportedError). That check is no gate: `bench gates --pass offsetnames` tables the walk
+  // refusals only, and a decline from it reads as this stage's.
+  const walkedNames = opts.symbols
+    ? OFFSET_NAME_PASS.run(fn, opts.symbols, offsetNameBehaviorsFor(target, opts.contextGlobals))
+    : [];
 
   // (2) idiom fold: apply serializable patterns on the IR (the AI-improvement surface),
   // gated generically by the Target's capabilities (not an `arch ==` branch).
@@ -193,17 +288,34 @@ function runTower(
   // (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, declaresVoidReturn(prototypes[name]), prototypes),
-    // 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,
-    ...(mapSymbols ? { symbols: mapSymbols } : {}),
-    ...(inferredSymbols.size ? { inferredSymbols } : {}),
-    ...(orderLicensed.size ? { orderLicensedGlobals: orderLicensed } : {}),
-  });
+  const { sfn } = structureReturnTailReading(
+    fn,
+    {
+      ...structureOptionsFor(target, declaresVoidReturn(prototypes[name]), prototypes),
+      // 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,
+      spellSwitchBreak: backend.spellsSwitchBreak,
+      spellEarlyReturns: backend.spellsEarlyReturn,
+      ...(opts.copyReturnTails ? { copyReturnTails: true } : {}),
+      ...(opts.joinPastReturns ? { joinPastReturns: true } : {}),
+      onGap,
+      ...(mapSymbols ? { symbols: mapSymbols } : {}),
+      ...(opts.contextGlobals ? { contextGlobals: opts.contextGlobals } : {}),
+      ...(inferredSymbols.size ? { inferredSymbols } : {}),
+      ...(orderLicensed.size ? { orderLicensedGlobals: orderLicensed } : {}),
+    },
+    (t) => backend.emit(t),
+    {},
+    // ONE default-accepts memo for this lift, as rank.ts keeps one per lift: the copies the measured
+    // default structures first carry `copyReturnTails`, so every run of their ladder asks
+    // `assertDefaultAccepts` to structure the default first, and without a memo each rerun pays that
+    // whole structuring again. `structure()` does not mutate `fn` (structure-purity.test.ts), so the
+    // memo's answer is the one each rerun would compute. Measured on Klonoa's sub_0800D188 (1,783
+    // blocks): every one of its copies' reruns structured the whole join ladder again.
+    new DefaultAcceptsMemo(fn),
+  );
 
   // (5) lower + print: neutral AST → target language
   const source = backend.emit(sfn);
@@ -219,13 +331,139 @@ function runTower(
     // does not have (raise/globalshape.ts `assumedShapes`).
     assumedSymbols: assumedShapes(inferredSymbols, sfn, mapSymbols),
     walkedNames,
+    ownArityNotes,
+    calleeBodiesAsked: answeredBodies(bodiesAsked, opts.calleeBodies),
+    calleeStackSized: Object.fromEntries(stacksSized),
   };
 }
 
+/** The bodies handed in that a lift asked and that answered (`DecompileResult.calleeBodiesAsked`). */
+function answeredBodies(
+  asked: ReadonlyMap<string, number | undefined>,
+  bodies: CalleeBodies | undefined,
+): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const [callee, words] of asked) {
+    if (words !== undefined && bodies !== undefined && Object.hasOwn(bodies, callee)) {
+      out[callee] = words;
+    }
+  }
+  return out;
+}
+
+/** The `calleeBodiesAsked` and `calleeStackSized` (`DecompileResult`) of one lift under `opts`, for a
+ *  caller whose result carries none — the ranked path, whose every candidate lifts as this one does.
+ *  Empty where the lift fails: the run reports that failure itself. */
+export function calleeBodyNotesOf(
+  name: string,
+  asm: string,
+  target: TargetDescription,
+  opts: Pick<
+    DecompileOptions,
+    'prototypes' | 'asmData' | 'symbols' | 'contextGlobals' | 'ownContextProto' | 'calleeBodies'
+  >,
+): Pick<DecompileResult, 'calleeBodiesAsked' | 'calleeStackSized'> {
+  const own = splitOwnContext(opts.prototypes, name, opts.ownContextProto);
+  const asked = new Map<string, number | undefined>();
+  const stacksSized = new Map<string, number>();
+  try {
+    liftStamped(
+      name,
+      asm,
+      target,
+      prototypesFromSymbols(opts.symbols, own.prototypes ?? {}),
+      opts.asmData,
+      opts.symbols,
+      opts.contextGlobals,
+      { calleeBodies: opts.calleeBodies, bodiesAsked: asked, stacksSized },
+      own.ownContextProto,
+    );
+  } catch {
+    return { calleeBodiesAsked: {}, calleeStackSized: {} };
+  }
+  return {
+    calleeBodiesAsked: answeredBodies(asked, opts.calleeBodies),
+    calleeStackSized: Object.fromEntries(stacksSized),
+  };
+}
+
+/** The `[own-arity]` notes (`DecompileResult.ownArityNotes`) of one lift under `opts`, for a caller
+ *  whose result carries none — the ranked path, whose every candidate lifts as this one does. Empty
+ *  where the lift fails: the run reports that failure itself. */
+export function ownArityNotesOf(
+  name: string,
+  asm: string,
+  target: TargetDescription,
+  opts: Pick<
+    DecompileOptions,
+    'prototypes' | 'asmData' | 'symbols' | 'contextGlobals' | 'ownContextProto' | 'calleeBodies'
+  >,
+): string[] {
+  const own = splitOwnContext(opts.prototypes, name, opts.ownContextProto);
+  if (own.ownContextProto === undefined) {
+    return [];
+  }
+  const notes: string[] = [];
+  try {
+    liftStamped(
+      name,
+      asm,
+      target,
+      prototypesFromSymbols(opts.symbols, own.prototypes ?? {}),
+      opts.asmData,
+      opts.symbols,
+      opts.contextGlobals,
+      { calleeBodies: opts.calleeBodies },
+      own.ownContextProto,
+      notes,
+    );
+  } catch {
+    return [];
+  }
+  return notes;
+}
+
+/** What the declared-volatile stamp reads besides the IR and the map: the compiler's fact and the
+ *  declaration context's globals. Every stamp a driver puts reads the same two. */
+export function stampBehaviorsFor(
+  target: TargetDescription,
+  contextGlobals: ContextGlobals | undefined,
+): StampBehaviors {
+  return {
+    volatileReadsExtendInRegister: target.compilerBehaviors.volatileReadsExtendInRegister,
+    contextGlobals,
+  };
+}
+
+/** What the offset-name pass reads besides the IR and the map: the stamp's behaviours (it re-stamps
+ *  after naming) and whether the compiler reloads across two spellings of one cell (its one-spelling
+ *  check, raise/offsetnames.ts `cellSpelledTwice`). */
+export function offsetNameBehaviorsFor(
+  target: TargetDescription,
+  contextGlobals: ContextGlobals | undefined,
+): OffsetNameBehaviors {
+  return {
+    ...stampBehaviorsFor(target, contextGlobals),
+    reloadsAcrossSpellings: target.compilerBehaviors.reloadsAcrossSpellings,
+  };
+}
+
+/** What `liftStamped` is handed besides the frontend's own options: the bodies of callees found
+ *  outside the input, which only the callee-body readers read (`bodyReadsIn`), and a record of each
+ *  callee whose bound a call asked, with its answer (`DecompileResult.calleeBodiesAsked`). */
+export type StampedLiftOptions = LiftOptions & {
+  calleeBodies?: CalleeBodies;
+  bodiesAsked?: Map<string, number | undefined>;
+  /** each callee a call was sized at off its body, with its stack words (`DecompileResult.calleeStackSized`) */
+  stacksSized?: Map<string, number>;
+};
+
 /** Stage 1 — lift: the target's ISA frontend → L1, verified, with every read of an object
- *  `symbols` declares volatile stamped `declared` (raise/declared-volatile.ts) before any pass asks
- *  whether it may be deleted. Every entry path lifts through here, each lift under the map its
- *  structuring will be handed. */
+ *  `symbols` or `contextGlobals` declares volatile stamped `declared` (raise/declared-volatile.ts)
+ *  before any pass asks whether it may be deleted. Every entry path lifts through here, each lift
+ *  under the map its structuring will be handed, and each bounded by the context's own entry
+ *  (`ownContext`) the same way (`liftWithinContextBound`); `notes` collects that bound's
+ *  `[own-arity]` notes. */
 export function liftStamped(
   name: string,
   asm: string,
@@ -233,13 +471,496 @@ export function liftStamped(
   prototypes: Prototypes,
   asmData: AsmData | undefined,
   symbols: SymbolMap | undefined,
+  contextGlobals: ContextGlobals | undefined,
+  stampedOptions?: StampedLiftOptions,
+  ownContext?: FnProto,
+  notes?: string[],
 ): Fn {
-  const fn = frontendFor(target).lift(name, asm, target, prototypes, asmData, symbols);
+  const { calleeBodies, bodiesAsked, stacksSized, ...liftOptions } = stampedOptions ?? {};
+  // Its callers split the table already; split again here, where every lift passes, so that no
+  // frontend is handed a marked context entry to read as a stated, hard bound.
+  const split = splitOwnContext(prototypes, name, ownContext);
+  const table = split.prototypes ?? {};
+  const own = Object.hasOwn(table, name) ? table[name] : undefined;
+  const ownReturn = ownStructReturnThroughMemory(name, target, own, split.ownContextProto, notes);
+  // a refusal about the return's width that the declared struct explains waits for the proof
+  let deferred: ((unproved: string) => never) | undefined;
+  const bytes = ownReturn?.register === true ? undefined : ownReturn?.type.size;
+  // what each callee whose body is in this input, or handed in, reads of its arguments, lifted from
+  // that body as a call to it is first lowered (frontend/callee-body.ts); the callee's own lift reads
+  // no bodies, and, off the same lift, what each one loads of its incoming stack words
+  const read =
+    liftOptions.calleeBodyBound === undefined || liftOptions.calleeStackWords === undefined
+      ? bodyReadsIn(name, asm, target, prototypes, ownContext, table, asmData, symbols, contextGlobals, calleeBodies)
+      : undefined;
+  const bound = liftOptions.calleeBodyBound ?? read!.bound;
+  const calleeBodyBound: CalleeBodyBound =
+    bodiesAsked === undefined
+      ? bound
+      : (callee) => {
+          const words = bound(callee);
+          bodiesAsked.set(callee, words);
+          return words;
+        };
+  const options = {
+    ...liftOptions,
+    calleeBodyBound,
+    calleeStackWords: liftOptions.calleeStackWords ?? read!.stackWords,
+    ...(stacksSized === undefined
+      ? {}
+      : { stackSized: (callee: string, words: number) => stacksSized.set(callee, words) }),
+  };
+  const fn = liftWithinContextBound(
+    name,
+    asm,
+    target,
+    table,
+    asmData,
+    symbols,
+    contextGlobals,
+    bytes === undefined
+      ? options
+      : { ...options, ownMemoryReturn: { bytes, defer: (refuse) => void (deferred ??= refuse) } },
+    split.ownContextProto,
+    notes,
+  );
+  // a struct a callee returns in a register is the local the call assigns, or the function's own
+  // return where every return hands that struct back whole
+  const calls = liftRegisterStructCalls(
+    fn,
+    table,
+    target,
+    own ?? split.ownContextProto,
+    ownReturn?.register === true ? ownReturn.type : undefined,
+  );
   verify(fn);
-  stampDeclaredVolatileUnder(fn, symbols, target.compilerBehaviors);
+  if (ownReturn !== undefined && !calls.handedBack) {
+    returnOwnStruct(fn, name, target, ownReturn, notes, deferred, calls.readsCallStruct);
+    verify(fn);
+  }
+  refuseNarrowReturnsOfWideDeclaration(fn, name, own);
+  stampDeclaredVolatileUnder(fn, symbols, stampBehaviorsFor(target, contextGlobals));
   return fn;
 }
 
+/** Both readers of a callee's body (frontend/callee-body.ts `calleeBodyReads`). */
+type BodyReaders = { bound: CalleeBodyBound; stackWords: CalleeStackWords };
+
+/** The readers already built, per caller table as handed to `liftStamped`, each with what else it was
+ *  read under. A ranked run lifts one function a dozen times under one table, and each callee body
+ *  is a lift of the whole input, so reading it once per lift would double the lift time of a large
+ *  unit. Keyed by identity: a table rebuilt reads its bounds again, which costs and never lies. */
+const readsRead = new WeakMap<
+  Prototypes,
+  Array<{
+    key: readonly unknown[];
+    reads: BodyReaders;
+  }>
+>();
+
+/** Each callee's body readers (frontend/callee-body.ts) as a lift of `name` under `table` reads them: every
+ *  callee lifted from the same input, or from its body in `calleeBodies`, under the same table, map
+ *  and context, reading no bodies. A body from outside the input is lifted with none of the input's
+ *  side table, which describes the input's own object, and with only the relocations it carries
+ *  (`CalleeBody.relocs`). Kept across lifts of the same function under the same caller table,
+ *  map, data, context and bodies (`readsRead`). */
+function bodyReadsIn(
+  name: string,
+  asm: string,
+  target: TargetDescription,
+  prototypes: Prototypes,
+  ownContext: FnProto | undefined,
+  table: Prototypes,
+  asmData: AsmData | undefined,
+  symbols: SymbolMap | undefined,
+  contextGlobals: ContextGlobals | undefined,
+  calleeBodies: CalleeBodies | undefined,
+): BodyReaders {
+  const key = [name, asm, target, ownContext, asmData, symbols, contextGlobals, calleeBodies];
+  const read = readsRead.get(prototypes) ?? [];
+  readsRead.set(prototypes, read);
+  const hit = read.find((r) => r.key.every((k, i) => k === key[i]));
+  if (hit !== undefined) {
+    return hit.reads;
+  }
+  const reads = calleeBodyReads(
+    name,
+    asm,
+    target,
+    table,
+    (callee, calleeTable, entryReadCalls, text, relocs) =>
+      liftStamped(
+        callee,
+        text,
+        target,
+        calleeTable,
+        text === asm ? asmData : relocs === undefined ? undefined : relocsOnly(relocs, target),
+        symbols,
+        contextGlobals,
+        { calleeBodyBound: () => undefined, calleeStackWords: () => undefined, entryReadCalls },
+      ),
+    calleeBodies,
+    frontendFor(target).entryStackWords,
+  );
+  // a handful per table: the symbol settings a ranked run tries, never a growing list
+  read.unshift({ key, reads });
+  read.length = Math.min(read.length, 8);
+  return reads;
+}
+
+/** A side table holding a body's own relocations and nothing of the input's object: no section
+ *  bytes, so no jump table reads, and no symbols. */
+const relocsOnly = (relocs: readonly Reloc[], target: TargetDescription): AsmData => ({
+  sections: new Map(),
+  relocs: [...relocs],
+  symbols: new Map(),
+  symbolCount: 0,
+  bigEndian: target.capabilities.endianness === 'big',
+});
+
+/** THE CONTEXT'S OWN ENTRY BOUNDS THE ARGUMENT REGISTERS, SOFTLY: an argument register past the
+ *  words it fills (`ownArgumentWordsOn`, the layout a stated entry gets) is lifted as an uninitialised
+ *  local's home, and where the finished lift still READS one, the function is lifted again with
+ *  the bound raised past it, so that register stays the parameter a context-less lift makes it,
+ *  with an `[own-arity]` note naming the declaration and the register.
+ *
+ *  WHY SOFT, where a stated entry is hard. A header entry for a function still in assembly was
+ *  written with no compiler checking it against a definition, and the two directions of its error
+ *  cost differently. Too long, it only keeps a parameter. Too short, a hard bound turns a real
+ *  argument into `uninit_<reg>`, which compiles silently: sbk2's task callbacks are declared
+ *  `void f(void);` ahead of a definition that reads `a0`, 407 of 525 such headers were short when
+ *  their functions were decompiled, and a hard bound lifted 16 of 33 sampled ones as `s32
+ *  uninit_a0; … memcpy(uninit_a0 + 28, …)`. Kept as a parameter instead, the lift is the right
+ *  function and contradicts the header, which every compiler here rejects as conflicting types —
+ *  loud — and the note says which register. What the bound buys is the other direction: a
+ *  register nothing in the lift reads is no parameter (sa3's `void Task_802F698(void)` lifted
+ *  `(s32 a0, s32 a1, s32 a2, s32 a3)`).
+ *
+ *  "READS" MEANS THE FINISHED LIFT, not the SSA builder. A register is read as the argument of a
+ *  call whose arity was guessed, and the guess then trims it (`k4(a, b, 2, 0); zq(a); sl();` reads
+ *  a2/a3 as `zq`'s and `sl`'s possible arguments); so the test is that an undefined value of a
+ *  dropped register survives into the lift — an `undef` keyed by it, or by a join that took it,
+ *  that `dce` would not delete, or one the machine homes to a slot nothing reads
+ *  (`readDroppedArgRegs`). A read the raising tower would delete later still counts: that only
+ *  keeps the parameter.
+ *
+ *  A LIFT THAT REFUSES WITHIN THE BOUND IS LIFTED WITHOUT IT, with a note, so the bound turns no
+ *  lift into a decline. The one refusal it adds is a stated entry's (frontend/ssa.ts
+ *  `LiveInModel.ownArgWords`): an incoming stack argument past it, which no local can be, and which,
+ *  named by position past the registers the bound dropped, would be one slot low. A stated entry for
+ *  `name` — `prototypes`, which includes what the symbol map derives — wins, and the context's is
+ *  not read. */
+function liftWithinContextBound(
+  name: string,
+  asm: string,
+  target: TargetDescription,
+  prototypes: Prototypes,
+  asmData: AsmData | undefined,
+  symbols: SymbolMap | undefined,
+  contextGlobals: ContextGlobals | undefined,
+  liftOptions: LiftOptions | undefined,
+  ownContext: FnProto | undefined,
+  notes: string[] | undefined,
+): Fn {
+  const frontend = frontendFor(target);
+  // THE CONTEXT'S OWN ENTRY RIDES ON EVERY LIFT IT MAY BIND, the stated entry's absence permitting.
+  // A lift bounded by exactly its words, or one it fills every register of, may take it as proof
+  // (`LiftOptions.contextOwnProto.proves`). Any other lift may only refuse on it: the unbounded
+  // relift below, and a bound raised past a register the body reads. Otherwise a decided arity gap
+  // (frontend/call-plan.ts `decideGap`) that the entry refuses would come back from the relift as a
+  // lift without it. With `int pr(void)` in the context, `logv(s, 1)` would lift `logv(a0, 1)`, the
+  // same as with no declaration.
+  const context = (proves: boolean): LiftOptions =>
+    ownContext === undefined || Object.hasOwn(prototypes, name)
+      ? {}
+      : { contextOwnProto: { proto: ownContext, proves } };
+  const unbounded = () =>
+    forgetAbsorbedKeys(
+      frontend.lift(name, asm, target, prototypes, asmData, symbols, contextGlobals, {
+        ...liftOptions,
+        ...context(false),
+      }),
+    );
+  let words =
+    ownContext === undefined || Object.hasOwn(prototypes, name)
+      ? undefined
+      : ownArgumentWordsOn(name, ownContext, target);
+  if (words === undefined || words >= target.argRegs.length) {
+    return words === undefined
+      ? unbounded()
+      : forgetAbsorbedKeys(
+          frontend.lift(name, asm, target, prototypes, asmData, symbols, contextGlobals, {
+            ...liftOptions,
+            ...context(true),
+          }),
+        );
+  }
+  const declared = spelledDeclaration(name, ownContext!);
+  const declaredWords = words;
+  for (;;) {
+    let fn: Fn;
+    try {
+      fn = frontend.lift(name, asm, target, prototypes, asmData, symbols, contextGlobals, {
+        ...liftOptions,
+        contextOwnWords: words,
+        ...context(words === declaredWords),
+      });
+    } catch (e) {
+      if (!(e instanceof FrontendUnsupportedError)) {
+        throw e;
+      }
+      const lifted = unbounded();
+      notes?.push(
+        `${name}: lifted without its context declaration \`${declared}\`, which it could not be lifted within ` +
+          `(${e.message.split('\n')[0]})`,
+      );
+      return lifted;
+    }
+    const read = readDroppedArgRegs(fn, target.argRegs.slice(words));
+    if (read.length === 0) {
+      return forgetAbsorbedKeys(fn);
+    }
+    notes?.push(
+      `${name}: its context declaration \`${declared}\` fills ${words} argument word${words === 1 ? '' : 's'}, ` +
+        `and the body reads ${read.join(', ')} past ${words === 1 ? 'it' : 'them'} — kept as ` +
+        `${read.length === 1 ? 'a parameter' : 'parameters'}, which the header contradicts`,
+    );
+    words = Math.max(...read.map((r) => target.argRegs.indexOf(r))) + 1;
+    if (words >= target.argRegs.length) {
+      return unbounded();
+    }
+  }
+}
+
+/** The dropped argument registers whose undefined value the lift still reads: an `undef` keyed by
+ *  one, or that absorbed one when its join collapsed (frontend/ssa.ts `ABSORBED_KEYS`), which is
+ *  not dead (`deadOps`, the definition `dce` deletes by) or which the machine stored to a slot
+ *  nothing reads back (`HOMED_UNDEF`). That store reaches no op, and it is still a read: IDO -g3 and
+ *  -O0 home every argument register the definition declares, so a header naming fewer contradicts
+ *  the asm, and the main lift's `(a0, a1)` is the one that recompiles to the same words. */
+function readDroppedArgRegs(fn: Fn, dropped: readonly string[]): string[] {
+  const dead = deadOps(fn.blocks);
+  const read = new Set<string>();
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      if (op.opcode === 'undef' && (!dead.has(op) || op.attrs[HOMED_UNDEF] === true)) {
+        for (const k of [String(op.attrs.key), ...String(op.attrs[ABSORBED_KEYS] ?? '').split(',')]) {
+          read.add(k);
+        }
+      }
+    }
+  }
+  return dropped.filter((r) => read.has(r));
+}
+
+/** `fn` with no `undef` carrying `ABSORBED_KEYS` or `HOMED_UNDEF`, which nothing past the own-entry
+ *  bound reads. */
+function forgetAbsorbedKeys(fn: Fn): Fn {
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      if (op.opcode === 'undef') {
+        delete op.attrs[ABSORBED_KEYS];
+        delete op.attrs[HOMED_UNDEF];
+      }
+    }
+  }
+  return fn;
+}
+
+/** A declaration as a note spells it: `int f(short, int)`, `void f(void)`, `int f(int, ...)`, and
+ *  `int f()` for one that states no parameters. */
+function spelledDeclaration(name: string, p: FnProto): string {
+  const ret = p.returns ?? (p.returnsVoid === true ? 'void' : 'int');
+  const params =
+    p.variadicParams !== undefined
+      ? [...p.variadicParams, '...'].join(', ')
+      : Array.isArray(p.params)
+        ? p.params.length > 0
+          ? p.params.join(', ')
+          : 'void'
+        : '';
+  return `${ret} ${name}(${params})`;
+}
+
+/** A FUNCTION THAT ITSELF RETURNS A STRUCT BY VALUE, as its declaration says: a stated entry for
+ *  `name` (`own`), or else the context's own entry (`ownContext`, proto-context.ts
+ *  `ownContextEntry`). Where its target's rule (`returnsInMemory`) returns the struct through
+ *  memory, its caller hands it the storage in the first argument register, so its declared
+ *  parameters sit one register up, and the lift is the pointer function `s32 *f(s32 *a0, s32 a1)`
+ *  until `returnOwnStruct` proves that pointer is the storage and lifts the struct return the
+ *  declaration names. This answers what that proof is handed — the struct laid out, and which
+ *  declaration said so — and refuses, before any frontend runs, where no lift can be the declared
+ *  function:
+ *   - a struct the rule hands back in two registers (mwcc's svr4 eight-byte struct in r3:r4): the
+ *     lift returns one word, and would drop the second register — on both declarations, since a
+ *     context's header that says so is the only thing that says the second register is live;
+ *   - a stated declaration whose struct the rule cannot place, because the target states no rule
+ *     or nothing lays the struct out, or that names no type a local can be declared with. A context
+ *     entry that cannot be placed keeps the pointer lift, with a note in `notes`: what it costs is
+ *     a signature the header contradicts, which the compiler rejects.
+ *  A struct the rule hands back in one register (agbcc's and mwcc's one-word struct in r0/r3) is
+ *  that register's word: the plan says so (`register`), and a struct that is all one word-wide
+ *  integer member is spelled as that member (frontend/own-struct-return.ts
+ *  `liftOwnRegisterStruct`), where any other one stays the word the lift returns, with a note in
+ *  `notes` saying why (`returnOwnStruct`). */
+function ownStructReturnThroughMemory(
+  name: string,
+  target: TargetDescription,
+  own: FnProto | undefined,
+  ownContext: FnProto | undefined,
+  notes: string[] | undefined,
+): OwnStructReturn | undefined {
+  const stated = own !== undefined;
+  const declared = stated ? own : ownContext;
+  if (!declaresAggregateReturn(declared)) {
+    return undefined;
+  }
+  const spelled = declared!.returns ?? 'a struct or union';
+  const read = returnedStruct(declared!, target);
+  if (read === 'register') {
+    // A struct wider than a word that comes back in registers is a pair the lift returns one word
+    // of, dropping the second register; one of a word or less is that word
+    const size = aggregateSize(returnedAggregate(declared!), target)?.size;
+    if (size !== undefined && size <= 4) {
+      const type = structLocalType(declared!, target);
+      return 'refused' in type
+        ? undefined
+        : { type, stated, declaration: spelledDeclaration(name, declared!), register: true };
+    }
+    if (size !== undefined) {
+      const pair =
+        `this target hands its ${size} bytes back in two registers — a function that itself returns a struct ` +
+        'in a register pair is not modelled';
+      if (stated) {
+        throw new FrontendUnsupportedError(
+          `cannot lift '${name}': it is declared to return ${spelled} by value, and ${pair}`,
+        );
+      }
+      throw new FrontendUnsupportedError(
+        `cannot lift '${name}': its context declaration says it returns ${spelled} by value, and ${pair} ` +
+          `(\`${spelledDeclaration(name, declared!)}\`)`,
+      );
+    }
+    return undefined;
+  }
+  if ('refused' in read) {
+    const how =
+      returnsInMemory(returnedAggregate(declared!), target) === true
+        ? `this target returns that through a hidden pointer in ${target.argRegs[0]}, and ${read.refused}`
+        : target.compilerBehaviors.aggregateReturn === undefined
+          ? `nothing here says whether this target returns it through a hidden pointer in ${target.argRegs[0]}`
+          : `nothing here lays it out, and this target's rule needs its layout to say whether it comes back through a ` +
+            `hidden pointer in ${target.argRegs[0]}`;
+    if (stated) {
+      throw new FrontendUnsupportedError(
+        `cannot lift '${name}': it is declared to return ${spelled} by value, and ${how}`,
+      );
+    }
+    notes?.push(
+      `[own-return] ${name}: its context declaration \`${spelledDeclaration(name, declared!)}\` returns a struct by value, ` +
+        `and ${how} — lifted as the machine code's function, which the header contradicts`,
+    );
+    return undefined;
+  }
+  return { type: read.type, stated, declaration: spelledDeclaration(name, declared!) };
+}
+
+/** The struct a function's own declaration returns by value, and which declaration said so. */
+interface OwnStructReturn {
+  type: Extract<IrType, { kind: 'struct' }>;
+  stated: boolean;
+  declaration: string;
+  /** the target hands it back in the return register, not through a hidden pointer */
+  register?: true;
+}
+
+/** Lifts `fn`'s struct return (frontend/own-struct-return.ts `liftOwnStructReturn`), where the
+ *  lift proves the hidden pointer is the struct's storage. Where it does not, a STATED declaration
+ *  refuses — the pointer function contradicts it — and a context's keeps the pointer lift, as the
+ *  machine code's function, with a note in `notes`: the context's own entry is a header nothing
+ *  checked against a definition (`liftWithinContextBound` says why that makes it soft). Either way, a
+ *  refusal the frontend `deferred` because this struct would explain it (agbcc's 8-byte epilogue,
+ *  `LiftOptions.ownMemoryReturn`) is thrown where the proof fails, since nothing else explains it, and
+ *  says why the proof failed. */
+function returnOwnStruct(
+  fn: Fn,
+  name: string,
+  target: TargetDescription,
+  own: OwnStructReturn,
+  notes: string[] | undefined,
+  deferred: ((unproved: string) => never) | undefined,
+  readsCallStruct: boolean,
+): void {
+  if (own.register) {
+    // a word the struct may not be all of stays the lift's own return, as the machine has it, and
+    // the note says why the declared struct is not what it returns
+    const kept = liftOwnRegisterStruct(fn, own.type);
+    // … save in a function that reads a struct a call returned (frontend/register-struct-call.ts):
+    // the word it returns may be computed from that struct — through a frame slot as well as an
+    // op — and the word return would print it as the scalar the declaration contradicts
+    if (kept !== undefined && readsCallStruct) {
+      throw new FrontendUnsupportedError(
+        `cannot lift '${name}': it is declared to return ${own.type.declared ?? 'a struct'} by value, which comes back in ` +
+          `${target.returnReg} — ${kept}, and it reads a struct a call returned there, which what it returns may be computed from`,
+      );
+    }
+    if (kept !== undefined) {
+      notes?.push(
+        `[own-return] ${name}: its ${own.stated ? '' : 'context '}declaration \`${own.declaration}\` returns ` +
+          `${own.type.declared ?? 'a struct'} by value in ${target.returnReg}, and ${kept} — lifted as the word ` +
+          'the machine code returns, which the header contradicts',
+      );
+    }
+    return;
+  }
+  const why = liftOwnStructReturn(fn, own.type, target);
+  if (why === undefined) {
+    return;
+  }
+  // a refusal the frontend deferred because this struct would explain it stands where it does not
+  deferred?.(why);
+  const declared = `${own.type.declared ?? 'a struct'} by value, which this target returns through a hidden pointer in ${target.argRegs[0]}`;
+  if (own.stated) {
+    throw new FrontendUnsupportedError(
+      `cannot lift '${name}': it is declared to return ${own.type.declared ?? 'a struct'} by value, which this target returns ` +
+        `through a hidden pointer in ${target.argRegs[0]}, and the lift cannot show that pointer is only its storage: ${why}`,
+    );
+  }
+  notes?.push(
+    `[own-return] ${name}: its context declaration \`${own.declaration}\` returns ${declared}, and the lift cannot show ` +
+      `that pointer is only its storage (${why}) — lifted as the machine code's pointer function, which the header contradicts`,
+  );
+}
+
+/** A FUNCTION DECLARED TO RETURN AN INTEGER WIDER THAN A REGISTER, whose lift returns one word or
+ *  none, refuses — on every frontend, since this reads only the lifted `ret`s.
+ *
+ *  Only the declaration can decide this. A `long long` comes back in a register pair (Thumb r0:r1,
+ *  O32 v0:v1, PowerPC r3:r4), and where the body never reads the pair's second register back, the
+ *  asm of `long long f(long long *p, long long *q) { long long x = *p; *q = x; return x; }` is
+ *  byte-identical to that of the `s32` function storing the same two words (kmc-gcc and gcc 2.7.2
+ *  compile both to one object). A frontend that builds the pair returns one 64-bit value and
+ *  passes; one that lowered a word would print `s32 f(...)` against the project's own `long long
+ *  f(...)` — a candidate the compiler rejects as conflicting types. The frontends' asm rules
+ *  (Thumb's `refuseWordReturns`, O32's `v1MayHoldLowWord`) stay as the backstop for a function
+ *  nothing declares, and that byte-identical shape is their blind spot. */
+function refuseNarrowReturnsOfWideDeclaration(fn: Fn, name: string, own: FnProto | undefined): void {
+  const width = ownReturnWidth(own);
+  if (width === undefined || width <= 32) {
+    return;
+  }
+  for (const blk of fn.blocks) {
+    for (const op of blk.ops) {
+      if (op.opcode === 'ret' && !op.operands.some((v) => (intWidth(v.type) ?? 0) > 32)) {
+        throw new FrontendUnsupportedError(
+          `cannot lift '${name}': its declaration returns a ${width}-bit integer, which comes back as the halves of a ` +
+            '64-bit pair, and this lowering returns one word',
+        );
+      }
+    }
+  }
+}
+
 // ── the shared raising tower ────────────────────────────────────────────────────────────────
 // 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
@@ -272,19 +993,20 @@ 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;
+  /** after each pre-structure fold (raise/pre-structure.ts) that changed the fn (fires after its verify) */
+  afterFold?: (fold: PreStructureFold) => 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) → empty-latch folding (splice out a
- *  back-edge block SSA construction emptied). `verify` after every pass that changed the IR.
+ *  return-only merge so short-circuits emit early returns) → the pre-structure folds
+ *  (raise/pre-structure.ts: empty latches, exit trampolines, peeled loop tests). `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
+ *  Return-sinking and latch folding 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
+ *  that unreachable, since the blocks retsink wants are never back-edge sources. The folds go 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
@@ -314,6 +1036,9 @@ export function raiseRecovered(
     pre,
   );
   hooks.beforeRecover?.();
+  if (declaresVoidReturn(self)) {
+    dropVoidReturnOperands(fn);
+  }
   recoverTypes(fn);
   verify(fn);
   assertTypesRecovered(fn);
@@ -330,9 +1055,11 @@ export function raiseRecovered(
     verify(fn);
     hooks.afterRetsink?.();
   }
-  if (foldEmptyLatches(fn)) {
-    verify(fn);
-    hooks.afterLatchFold?.();
+  for (const fold of PRE_STRUCTURE_FOLDS) {
+    if (fold.run(fn) > 0) {
+      verify(fn);
+      hooks.afterFold?.(fold);
+    }
   }
   // 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
@@ -352,6 +1079,31 @@ export function raiseRecovered(
   }
 }
 
+/** A FUNCTION ITS DECLARATION SAYS RETURNS NOTHING RETURNS NOTHING: each `ret` drops the return
+ *  register the frontend hands it (frontend/ssa.ts returns that register at every `ret`, whatever
+ *  the declared type), and the joins only that operand read go with it. Before type recovery, since
+ *  a join read by nothing else is no value of the program, and recovery would otherwise unify what
+ *  two paths leave in that register: mwcc's `if (*p == 7) { gHit += 1; break; }` leaves r3 holding
+ *  gHit's value on one exit and the walked pointer on the other, and the one join typed both as
+ *  `u8 *` (`gHit = (void *)(v0 + 1)`, which mwcc rejects). The structurer already reads no `ret`
+ *  operand under `returnsVoid`, so this changes no `return` it writes. */
+function dropVoidReturnOperands(fn: Fn): void {
+  let dropped = false;
+  for (const blk of fn.blocks) {
+    for (const op of blk.ops) {
+      if (op.opcode === 'ret' && op.operands.length > 0) {
+        op.operands = [];
+        dropped = true;
+      }
+    }
+  }
+  if (dropped) {
+    pruneDeadParams(fn);
+    dce(fn);
+    verify(fn);
+  }
+}
+
 /** Run `body`; if it declines, name the unmodelled instructions the function carries.
  *
  *  An `opaque` degrades its own value AND makes its block impure, so a shape recognizer refuses:
@@ -413,8 +1165,9 @@ export function structureChecked(
   fn: Fn,
   opts: Parameters<typeof structure>[1],
   hooks?: Parameters<typeof structure>[2],
+  memo?: Parameters<typeof structure>[3],
 ): SFn {
-  const raw = attributeOpaques(fn, () => structure(fn, opts, hooks));
+  const raw = attributeOpaques(fn, () => structure(fn, opts, hooks, memo));
   // 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
@@ -430,6 +1183,7 @@ export function structureChecked(
   // re-validate deref typing on the rewritten tree.
   const sfn = readabilityRewrites(raw);
   assertDerefsTyped(sfn);
+  assertFrameUnionsViewed(sfn);
   assertPostIncrUnshared(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.
@@ -437,6 +1191,250 @@ export function structureChecked(
   return sfn;
 }
 
+/** Non-blank lines in an emitted source: what the return-tail reading below is bounded by, and
+ *  rank.ts's compactness tie-break, counted exactly as the report counts `lines`
+ *  (apps/benchmark/src/eval/quality.ts). Deterministic, and total on any string. */
+export function sourceLineCount(source: string): number {
+  return source.split('\n').filter((l) => l.trim().length > 0).length;
+}
+
+/** The reading a {@link structureReturnTailReading} did not publish, for rank.ts's alternative
+ *  candidate: its tree and which reading it is, or why the copies have none. */
+export type UnpublishedReading =
+  { readonly reading: 'copies' | 'join'; readonly sfn: SFn } | { readonly reading: 'copies'; readonly error: unknown };
+
+export interface ReturnTailReading {
+  /** the tree this structuring publishes */
+  readonly sfn: SFn;
+  /** the other reading of the same structuring, where the published one was a choice between two:
+   *  absent where no divergent branch took the join past early returns, or where a reading was
+   *  forced */
+  readonly unpublished?: UnpublishedReading;
+}
+
+/** Stage 4, THE RETURN-TAIL READING BOUNDED BY SIZE AND READ OFF THE LAYOUT. On a target that
+ *  declares the join past early returns its default (target.ts `joinPastReturnsByDefault`:
+ *  mwcc_242_81 and mwcc_233_163n), `structureChecked`, and where that structuring took the join
+ *  somewhere, the same structuring again reading the return-tail copies (`copyReturnTails`). The copies are
+ *  published where they spell the function SHORTER, or where the target's asm layout shows that the
+ *  compiler cross-jumped a tail the source wrote into every arm, or its cse left a return unfolded
+ *  (below). Every other target publishes the copies (THE MEASURED DEFAULT).
+ *
+ *  WHY A BOUND. The join writes the code below a divergent branch once where the copies write it
+ *  into every arm; but the join copies a return tail into each early return in its turn, so neither
+ *  reading is the shorter in general (structure.ts `structureWithinBudget`). Where the join is the
+ *  longer, it is the reading that duplicates code. Measured with the real compilers over the 620
+ *  real functions the unbounded join re-spells (2026-11-05): the 180 it makes longer score further
+ *  from their bytes than the copies on 89 and closer on 10 (MATCH 23 → 16).
+ *
+ *  THE UNIT IS THE WHOLE FUNCTION'S EMITTED SOURCE, in non-blank lines (`sourceLineCount`), and a
+ *  tie goes to the join.
+ *    - Whole function, not per branch: these are the two whole-function readings the ranked fan
+ *      holds (rank.ts's default and its `/ret-copy` or `/ret-join` sibling), so the published tree
+ *      is always one of them. A per-branch unit differs only where the join fires at two or more
+ *      branches (196 of those 620), and its gain there is not measured. Of the 13 that MATCH only
+ *      with the copies (all sa3 agbcc) this bound publishes the copies on 9; on the other 4 the
+ *      join is the shorter, and 3 of them take it at a single branch, so a per-branch unit could
+ *      recover at most 1. The layout recovers all 4 (THE LAYOUT, below).
+ *    - Emitted, not the structured tree: `readabilityRewrites` runs after `structure()` and can fold
+ *      copied tails back together (`mergeCommonTails`), so a size read inside `structure()` is not
+ *      the size published.
+ *    - Lines, not statements: on those 620 the final tree's statement count disagrees with the line
+ *      class on 49, and it ties the mwcc jump-table window (cli
+ *      test/matching/jump-table-window.test.ts) at 17 statements where the copies are 30 lines and
+ *      byte-exact, the join 32.
+ *    - Lines alone, not rank.ts `compareScored`'s goto and cast counts ahead of them: on those 620
+ *      neither reading spells a `goto`, and casts-first parts from lines on 17, where lines scores
+ *      the closer on 5 and casts on 3, with no MATCH between them. The ranked fan holds both
+ *      readings, so where the default is ranked `compareScored` still orders them.
+ *
+ *  THE LAYOUT. A compiler that cross-jumps return tails (target.ts `crossJumpsReturnTails`) compiles
+ *  the copies into the CFG the join reads, with one copy of the tail. So the join is the shorter
+ *  reading of those copies, and the bound alone publishes it. What the copies leave instead is a
+ *  mark in the layout at a site the join took: the surviving tail ends in a jump over an arm laid
+ *  out after it, identical arms stayed separate blocks, or a call at the join was cut from the
+ *  argument setup each arm kept (structure/cross-jumped-tail.ts). Where
+ *  any site the published join run took shows a mark, the copies are published whatever their size.
+ *    - Read only where the target declares the merge. ido7.1 lays a tail out mid-construct with no
+ *      cross-jump, and there the same layout fact is not evidence of the copies.
+ *    - Whole function, as the bound is: the two readings are still rank.ts's default and its
+ *      `/ret-copy` or `/ret-join` sibling, so the ranked fan holds the same two trees. A mark at one
+ *      site re-spells every join the function took, marked or not (14 of the 116 agbcc functions
+ *      with a mark over those 620 have unmarked sites too); a per-site reading would add trees to
+ *      the fan, and is not built.
+ *    - MEASURED over those 620 functions, each reading really compiled: the bound with the layout
+ *      gives MATCH 44 (copies everywhere 35, the bound alone 40), and loses none of the copies'
+ *      matches. The bound alone loses 4, all sa3 agbcc: three where the tail is left mid-construct,
+ *      and one where identical case bodies stayed apart. The first two marks were chosen on those
+ *      620; the third, and the split tail of the first, on held-out generated sources written with
+ *      the copies, where the bound with the first two still lost matches the copies make (agbcc 7,
+ *      gcc2.7.2kmc 9, gcc2.7.2 2 of 160; with all three, 2, 3, 1). Their numbers are in
+ *      structure/cross-jumped-tail.ts. So, held out, this reading still loses some of the copies'
+ *      matches; the 620 and the full bench lose none. Those 620 MATCH figures are of the bound with
+ *      the marks on every compiler; agbcc, ido7.1 and the two GCC 2.7.2 lanes publish the copies
+ *      (THE MEASURED DEFAULT), so the marks are read by the tests and by no default (no compiler
+ *      that declares `crossJumpsReturnTails` declares the join its default), and the join's gains
+ *      there are given up (agbcc 2 of the 620, ido7.1 7: the field's note).
+ *    - A mark is evidence, not proof: jump2 cross-jumps shared arm code that is not a return tail
+ *      too, and leaves the same marks under a join-written source (structure/cross-jumped-tail.ts).
+ *      So a mark moves which verified reading is the default, never what is lifted.
+ *
+ *  THE UNFOLDED RETURN. Where the target's cse folds a branch-proven constant only into the branch's
+ *  fall-through arm (target.ts `foldsBranchConstantOnTakenEdge` false: gcc 2.x at -O1), an early
+ *  return of the very value its branch tested equal to a constant, left unfolded in the object, was
+ *  the jump-target (`else`) arm in the source, and the join cannot spell it: `if (x == 0) return x;`
+ *  compiles to `return 0` (structure/unfolded-branch-constant.ts). Where any site shows one, the
+ *  copies are published whatever their size, as for a layout mark. MEASURED on Mario Party 3's
+ *  `func_8010BD28_472F98_mgmode` (gcc2.7.2 -O1), the one held-out real function the join lost a
+ *  match on there (2026-11-06): the copies match, the join is 1 line off. Like the layout marks it
+ *  is read by no default now: gcc2.7.2 publishes the copies (THE MEASURED DEFAULT).
+ *
+ *  THE MEASURED DEFAULT. A target that does not declare `joinPastReturnsByDefault` (agbcc, ido7.1,
+ *  gcc2.7.2kmc, gcc2.7.2, mwcc_247_107, and any description that leaves it out) publishes the copies
+ *  whatever the bound and the marks would say, and keeps the join as the unpublished reading, so
+ *  the ranked fan holds both as before (`copiesByDefault`). The join is declared only where the
+ *  held-out real functions and the generated ones written with the copies show the bound with every
+ *  mark losing none of the copies' matches; on agbcc and ido7.1 (held out) and on gcc2.7.2kmc and
+ *  gcc2.7.2 (generated) it loses some no mark read from the target separates, and mwcc_247_107 is
+ *  unmeasured (the field's note has the counts and the gains given up).
+ *
+ *  REFUSALS. Never a lift turned into a decline:
+ *    - a join that declines or crosses the copy budget already falls to the copies inside
+ *      `structure()` (`structureWithinBudget`), and that tree is published as it was;
+ *    - outside the measured default, the copies are structured only once the join has lifted, and
+ *      where they decline, fail a boundary contract, or the backend cannot emit one of the two, the
+ *      join stands;
+ *    - under the measured default the copies come first, and where they refuse the join stands, so
+ *      a function the old default declined can lift there (`copiesByDefault`);
+ *    - a forced reading (`copyReturnTails`, `joinPastReturns`), or a language with no early `return`
+ *      (`spellEarlyReturns: false`), is structured once, as asked. rank.ts forces the join this way
+ *      for a setting whose stripped sibling dropped its copies.
+ *
+ *  HOOKS. The caller's hooks fire for both structurings, so an observer reads the union of what the
+ *  two runs saw. That is what keeps rank.ts's off-sibling witness sound: a setting is a tree dedup
+ *  of its sibling only where neither reading of the sibling fired the witness. A
+ *  `DefaultAcceptsMemoMisuse` is a defect and is rethrown, never an unpublished reading. */
+export function structureReturnTailReading(
+  fn: Fn,
+  opts: Parameters<typeof structure>[1] & {
+    joinPastReturns?: boolean;
+    crossJumpsReturnTails?: boolean;
+    foldsBranchConstantOnTakenEdge?: boolean;
+    joinPastReturnsByDefault?: boolean;
+  },
+  emit: (sfn: SFn) => string,
+  hooks: Parameters<typeof structure>[2] = {},
+  memo?: Parameters<typeof structure>[3],
+): ReturnTailReading {
+  // `crossJumpsReturnTails` rides along into `structure()`, which never reads it, as every compiler
+  // behaviour `structureOptionsFor` spreads does: stripped here, it would key this structuring's
+  // default-accepts memo apart from rank.ts's other passes over the same setting.
+  const { joinPastReturns, ...structOpts } = opts;
+  if (structOpts.copyReturnTails === true || structOpts.spellEarlyReturns === false) {
+    return { sfn: structureChecked(fn, structOpts, hooks, memo) };
+  }
+  const sites: JoinPastReturnsSite[] = [];
+  const structureJoin = () =>
+    structureChecked(
+      fn,
+      structOpts,
+      {
+        ...hooks,
+        onJoinPastReturns: (site) => {
+          sites.push(site);
+          hooks.onJoinPastReturns?.(site);
+        },
+      },
+      memo,
+    );
+  if (opts.joinPastReturnsByDefault !== true && joinPastReturns !== true) {
+    return copiesByDefault(fn, structOpts, structureJoin, sites, hooks, memo);
+  }
+  const join = structureJoin();
+  if (sites.length === 0 || joinPastReturns === true) {
+    return { sfn: join };
+  }
+  let copies: SFn;
+  try {
+    copies = structureChecked(fn, { ...structOpts, copyReturnTails: true }, hooks, memo);
+  } catch (error) {
+    if (error instanceof DefaultAcceptsMemoMisuse) {
+      throw error;
+    }
+    return { sfn: join, unpublished: { reading: 'copies', error } };
+  }
+  // Read only where the compiler is one that merges return tails: elsewhere the same layout is no
+  // evidence of the copies (ido7.1 lays a tail out mid-construct with no cross-jump at all).
+  const crossJumped = opts.crossJumpsReturnTails === true && sites.some((site) => crossJumpedTail(fn, site));
+  // Read only where the target's cse leaves the taken edge unfolded (gcc 2.x at -O1): elsewhere a
+  // return of the tested value says nothing about which arm the source wrote it in.
+  const unfolded =
+    opts.foldsBranchConstantOnTakenEdge === false && sites.some((site) => unfoldedBranchConstant(fn, site));
+  let publishCopies = false;
+  try {
+    const [copyLines, joinLines] = [sourceLineCount(emit(copies)), sourceLineCount(emit(join))];
+    publishCopies = crossJumped || unfolded || copyLines < joinLines;
+  } catch {
+    // a backend that cannot spell one of the two leaves the join standing; the caller's own emit of
+    // the join reports its refusal where it has one
+  }
+  return publishCopies
+    ? { sfn: copies, unpublished: { reading: 'join', sfn: join } }
+    : { sfn: join, unpublished: { reading: 'copies', sfn: copies } };
+}
+
+/** THE MEASURED DEFAULT (no `joinPastReturnsByDefault`): the copies, structured FIRST and
+ *  published wherever they lift, as the default before the join past early returns was one. The join
+ *  is structured after them for the ranked fan, and its refusal costs only that reading.
+ *
+ *  Where the copies REFUSE, the join is published: never a lift turned into a decline. The copies
+ *  here (`copyReturnTails`) are not that old default's structuring: its ladder's other rungs live in
+ *  the join's reading (structure.ts THE COPIES, where the join refuses), and a function only they
+ *  lift is one the copies alone decline (`synthetic:sw_gotocase2` on
+ *  ido7.1, a case that leaves its switch for a loop exit past the switch's end). So this default
+ *  also LIFTS some functions the old one declined, where only the join structures them (pokeemerald
+ *  `Task_ShowContestEntryMonPic`, agbcc, a jump table whose case arms the copies cannot linearize):
+ *  a decline turned into a lift, which the held-out sweep counts as moved, not as level. A refusal a
+ *  function's first structuring alone can see (a volatile read stamped late under a `&&`/`||`) is
+ *  remembered on the function (structure.ts `STAMPED_LATE`), so the join run after the copies
+ *  declines it as they did. Where both refuse, the copies' refusal is the one reported. */
+function copiesByDefault(
+  fn: Fn,
+  structOpts: Parameters<typeof structure>[1],
+  structureJoin: () => SFn,
+  sites: readonly JoinPastReturnsSite[],
+  hooks: Parameters<typeof structure>[2],
+  memo: Parameters<typeof structure>[3],
+): ReturnTailReading {
+  const refusal = (error: unknown) => {
+    if (error instanceof DefaultAcceptsMemoMisuse) {
+      throw error;
+    }
+    return error;
+  };
+  let copies: SFn | undefined;
+  let copiesError: unknown;
+  try {
+    copies = structureChecked(fn, { ...structOpts, copyReturnTails: true }, hooks, memo);
+  } catch (error) {
+    copiesError = refusal(error);
+  }
+  let join: SFn;
+  try {
+    join = structureJoin();
+  } catch (error) {
+    refusal(error);
+    if (copies === undefined) {
+      throw copiesError;
+    }
+    return { sfn: copies };
+  }
+  if (copies === undefined) {
+    return sites.length === 0 ? { sfn: join } : { sfn: join, unpublished: { reading: 'copies', error: copiesError } };
+  }
+  return sites.length === 0 ? { sfn: copies } : { sfn: copies, unpublished: { reading: 'join', sfn: join } };
+}
+
 // ── annotate-mode support ─────────────────────────────────────────────────────────────────
 
 /** Classify a caught failure by which stage's designed signal it is. `instanceof`, not name
@@ -492,6 +1490,9 @@ export function stubResult(name: string, asm: string, backend: LanguageBackend,
     // A stub spells no global, so it assumes nothing about one and walked to none.
     assumedSymbols: [],
     walkedNames: [],
+    ownArityNotes: [],
+    calleeBodiesAsked: {},
+    calleeStackSized: {},
   };
 }