@asmlift/core 0.8.1 → 0.10.0

package/src/frontend/stackargs.ts

@@ -15,7 +15,7 @@
  *  that matter — a sub-word or register-offset access is not a slot, and one anywhere turns the
  *  whole word-slot model off at the same gate this analysis's `blocker` feeds, so no access that
  *  could alias a licensed word is ever silently missing from the events. */
-export type StackArgsEvent<C> = StackArgsSlot | StackArgsCall<C>;
+export type StackArgsEvent<C> = StackArgsSlot | StackArgsCall<C> | StackArgsEscape;
 
 /** A whole-word access to a reserved frame slot at `off`, which must lie inside `[0, localArea)`. */
 export interface StackArgsSlot {
@@ -23,10 +23,24 @@ export interface StackArgsSlot {
   readonly off: number;
 }
 
+/** A frame address `sp + off` LEAVING this function — in an argument register at a call, or stored
+ *  to memory a device or another function reads. Its receiver may read the frame from `off` up, so
+ *  a word there that this function stored and never reloads has been read, by the receiver.
+ *
+ *  Emitted only under `compilerBehaviors.escapedFrameAddressNamesALocal`: that premise is what
+ *  makes the words from `off` up a local's rather than an argument area's. It ends only what is
+ *  pending WHERE it fires, never a word staged after it, and the field says why that is the safe
+ *  reading of a whole-function layout fact (a block copy's base escapes too). */
+export interface StackArgsEscape {
+  readonly kind: 'escape';
+  readonly off: number;
+}
+
 /** A call, and what its callee's DECLARATION says it takes on the stack. `declared` is the block
  *  `[0, 4*(n - argRegs))` as an ascending offset list, or null when nothing declares this call —
- *  an indirect call, a callee with no prototype, or one whose arity fits in registers. A null
- *  declaration can only ever lead to a refusal: the code alone cannot say where a block ENDS. */
+ *  an indirect call, a callee with no prototype, or one whose arity fits in registers. The code
+ *  alone cannot say where a null declaration's block ENDS, so such a call is never handed a stack
+ *  word; it lifts only when `loadedWordBound` clears every word that could open one. */
 export interface StackArgsCall<C> {
   readonly kind: 'call';
   /** The frontend's own handle for this call — the key of `OutgoingArgs.blocks`. */
@@ -34,6 +48,9 @@ export interface StackArgsCall<C> {
   /** The callee's name, for the refusal messages. `?` where the frontend has none. */
   readonly callee: string;
   readonly declared: readonly number[] | null;
+  /** The parameters the declaration lists, for the refusal messages — fewer than its words when a
+   *  64-bit parameter takes two or a hidden struct-return pointer takes one. Absent, one per word. */
+  readonly params?: number;
 }
 
 /** One basic block's events. Where control goes afterwards is read out of `preds`, so a block is
@@ -56,6 +73,12 @@ export interface StackArgsInput<C> {
   readonly argRegs: number;
   /** The frontend's verdict that the whole frame is one addressable object handed to a callee. */
   readonly capturedWholeFrame: boolean;
+  /** The lowest frame word this function loads where its compiler loads no word of the outgoing
+   *  area, before a call or after (`target.ts` `outgoingAreaNeverLoadedFrom`, the strong form of
+   *  `localsAboveOutgoingArea`, 0 on agbcc): `loadedWordBound` over these blocks, which the frontend
+   *  computes once and hands the frame-object audit too. Every word at or above it is a local's.
+   *  `Infinity` where the compiler claims no such offset. */
+  readonly loadedWordBound: number;
 }
 
 /** What this function's calls do with the BOTTOM of its frame — the outgoing stack-argument area
@@ -74,6 +97,40 @@ export interface OutgoingArgs<C> {
 }
 
 const isCallEvent = <C>(ev: StackArgsEvent<C>): ev is StackArgsCall<C> => ev.kind === 'call';
+const isSlotEvent = <C>(ev: StackArgsEvent<C>): ev is StackArgsSlot => ev.kind === 'store' || ev.kind === 'load';
+
+/** THE LOWEST FRAME WORD THIS FUNCTION LOADS AT OR ABOVE `from`, or `Infinity` when it loads none
+ *  or nothing states `from`. The Thumb frontend calls it once per lift and hands the number to both
+ *  readers: `analyzeOutgoingArgs` and the frame-object audit (`FrameObjectAudit.loadedWords`).
+ *  Under `outgoingAreaNeverLoadedFrom` the caller never reads a word of its outgoing area from that
+ *  offset up — not after a call, where the callee may have assigned to it, and not before one
+ *  either: the area holds only what the caller staged for a callee, every argument that contains a
+ *  call is computed before any word is staged, and nothing is saved there around a nested call
+ *  (agbcc-restage.s pins all three). So a word it loads is a local; and since the area is one
+ *  region at the frame bottom that every call shares, every word at or above the bound is proven
+ *  not to be an argument.
+ *
+ *  Only a load in a live block counts: a load that cannot run proves nothing. An ESCAPE does not
+ *  count: its receiver MAY read the words, and a bound is a proof, which a read that may not happen
+ *  cannot supply. */
+export function loadedWordBound<C>(
+  blocks: readonly StackArgsBlock<C>[],
+  live: ReadonlySet<number>,
+  from: number | undefined,
+): number {
+  if (from === undefined) {
+    return Infinity;
+  }
+  let bound = Infinity;
+  for (const b of live) {
+    for (const ev of blocks[b].events) {
+      if (ev.kind === 'load' && ev.off >= from) {
+        bound = Math.min(bound, ev.off);
+      }
+    }
+  }
+  return bound;
+}
 
 // THE OUTGOING STACK-ARGUMENT AREA, AND WHO MAY CONSUME IT.
 //
@@ -86,7 +143,7 @@ const isCallEvent = <C>(ev: StackArgsEvent<C>): ev is StackArgsCall<C> => ev.kin
 // CreateEntity_Platform_0_0 (platform.c:734) forwards SIX arguments and came out as
 // `CreateEntity_Platform(0, 0, a0, (u16)a1)`.
 //
-// TWO INDEPENDENT WITNESSES MUST AGREE, and that agreement is the whole licence:
+// TWO INDEPENDENT WITNESSES MUST AGREE for a call to CONSUME words — the licence:
 //   * the DECLARATION says how many words a call takes. AAPCS lays arguments 5..n at [sp,#0]
 //     upward, one word each, so the block is `[0, 4*(n - |argRegs|))`, contiguous from zero.
 //   * the CODE says which words are staged for it — the offsets stored and not yet reloaded when
@@ -100,15 +157,27 @@ const isCallEvent = <C>(ev: StackArgsEvent<C>): ev is StackArgsCall<C> => ev.kin
 //   * a variadic callee's list is a prefix — `sprintf` truthfully declares two and is handed six,
 //   * a large struct return adds a hidden pointer argument that appears in no parameter list.
 //
-// None of those is recorded by `FnProto` or `SymbolSignature`, so an ARITY-ONLY acceptance had
-// all three holes: supplying a TRUE fact (`{ sprintf: { params: 2 } }`) turned a correct decline
-// into `return sprintf(a0, a1)` with both stack arguments deleted. Under the rule here the four
-// words `sprintf` is really handed are four offsets reaching the call that its declaration does
-// not account for, the witnesses disagree, and the answer is the decline again. And the CODE
+// A `SymbolSignature` records none of those, and neither does a COUNT. A typed `FnProto` list
+// records only a `long long`, which the Thumb frontend refuses past the argument registers; a
+// `double` or a by-value struct has no width there, so the list states no layout at all. An
+// ARITY-ONLY acceptance therefore has all three holes: supplying a TRUE fact
+// (`{ sprintf: { params: 2 } }`) turns a correct decline into `return sprintf(a0, a1)` with both
+// stack arguments deleted. Under the rule here the four words `sprintf` is really handed are four
+// offsets reaching the call that its declaration does not account for, the witnesses disagree, and the answer is the decline again. And the CODE
 // alone cannot say where a block ENDS — a store never reloaded is an argument's signature, but
-// so is a dead local, which is why reading the code alone could only ever refuse (conditions (a)
+// so is a dead local, which is why reading the code alone never licenses a word (conditions (a)
 // and (b) below, kept for every call no declaration covers).
 //
+// A THIRD WITNESS SAYS WHERE THE AREA ENDS, and it only ever clears words. Under a compiler that
+// keeps one outgoing area below every local and never loads a word of it
+// (`outgoingAreaNeverLoadedFrom`), a word this function LOADS is a local, and so is every word above it
+// (`loadedWordBound`). Every refusal that reads the code — NOTHING EXTRA, (a) and (b) — then
+// weighs only the words beneath the bound, so an undeclared call lifts once no word there could
+// open an argument block, and takes no stack word. Hand-written asm that reads its own outgoing
+// argument defeats it, and lifts with that argument dropped — a producer assumption of the same
+// kind as CONTIGUITY below, which is why the premise is declared per compiler (`target.ts`
+// `outgoingAreaNeverLoadedFrom`) and never inferred.
+//
 // THE TWO SIDES ARE CHECKED AGAINST DIFFERENT SETS, and the asymmetry is the point.
 //   * NOTHING EXTRA is checked against the MAY set (stored and unreloaded on SOME path): the
 //     weakest thing that could still be a word this call takes must be inside the block.
@@ -118,14 +187,15 @@ const isCallEvent = <C>(ev: StackArgsEvent<C>): ev is StackArgsCall<C> => ev.kin
 //     0x0 in block")`; here it is a decline, and for the same reason — it is a GAP, and a gap
 //     must never render as a plausible value.
 //
-// WHAT "NOTHING EXTRA" COSTS, because the reach is narrower than the disappearance of the old
-// decline suggests. A genuine SPILL that is live across a licensed call sits in the may set and is
-// not in the declared block, so the call refuses — and that is agbcc's commonest frame with an
-// outgoing area. Tolerating it means arguing that a pending word which is RELOADED later is a
-// local rather than argument n+1, which needs a gate and a row that gate protects; none exists.
-// The cost is in attribution, not correctness: the decline such a function gets names a STORE
-// ("[sp,#k] also reaches the call unread") rather than the capability, so a gap histogram groups
-// this class under that message and not under anything about stack arguments.
+// A SPILL LIVE ACROSS A LICENSED CALL sits in the may set and is not in the declared block — agbcc's
+// commonest frame with an outgoing area. The declaration cannot excuse it; `loadedWordBound` can: a
+// word this function loads is a local, so NOTHING EXTRA counts only the pending words beneath the
+// bound. A declared block that reaches the bound contradicts it, and needs no check of its own:
+// the block is contiguous words from zero, so it holds the bound's word, which this function loads
+// — "this function also LOADS it" below refuses it if nothing earlier does.
+// A spill with no load at or beneath it still refuses, and its decline names a STORE ("[sp,#k]
+// also reaches the call unread") rather than the capability, so a gap histogram groups it under
+// that message.
 // The must set is an intersection over predecessors, which is exactly what a TAIL-MERGED call
 // site needs: agbcc does tail-merge (`Task_BonusFlower_Spawn`, sa3 bonus_game_enemies, stores
 // argument 5 in both predecessors with the `bl` in the join), and a one-armed store — the same
@@ -148,6 +218,7 @@ export function analyzeOutgoingArgs<C>({
   localArea,
   argRegs,
   capturedWholeFrame,
+  loadedWordBound: bound,
 }: StackArgsInput<C>): OutgoingArgs<C> {
   const refuse = (blocker: string): OutgoingArgs<C> => ({ blocker, blocks: new Map(), area: 0 });
   // EVERY block, not the entry-reachable ones: a call in dead code stages nothing, so the
@@ -164,19 +235,28 @@ export function analyzeOutgoingArgs<C>({
     return { blocker: null, blocks: new Map(), area: 0 };
   }
   const say = (offs: readonly number[]) => offs.map((o) => `[sp,#${o}]`).join(', ');
-  const arityOf = (offs: readonly number[]) => argRegs + offs.length;
+  const declaredAs = (ev: StackArgsCall<C>, offs: readonly number[]) => {
+    const words = argRegs + offs.length;
+    return ev.params === undefined || ev.params === words
+      ? `${words} arguments`
+      : `${ev.params} arguments in ${words} argument words`;
+  };
 
-  // THE ONE-WORD CAPTURED FRAME. `capturedWholeFrame` says the whole frame is an
-  // object whose address a callee holds; a declared fifth argument says [sp,#0] is a DIFFERENT
-  // callee's argument slot. Two contradictory claims about the same word, and nothing here can
-  // decide which to believe, so the honest answer is the decline it has always been.
+  // THE ONE-WORD CAPTURED FRAME. `capturedWholeFrame` says the whole frame is an object whose
+  // address has ESCAPED this function — handed to a callee, or published to memory; the frontend
+  // that computes it owns which escapes qualify. A declared fifth argument says [sp,#0] is a
+  // DIFFERENT callee's argument slot. Two contradictory claims about the same word, and nothing
+  // here can decide which to believe, so the honest answer is the decline it has always been.
+  // This is the flow-INSENSITIVE reading of an escape, sound only at one word; the `escape` event
+  // is the per-program-point reading of the same escapes at any frame size, and its contradiction
+  // with a declared block is the "ESCAPED ADDRESS AT OR BELOW A LICENSED WORD" refusal below.
   if (capturedWholeFrame) {
     for (const ev of calls) {
       const offs = ev.declared;
       if (offs !== null) {
         return refuse(
-          `callee \`${ev.callee}\` is declared with ${arityOf(offs)} arguments, so [sp,#0] is its outgoing stack argument — ` +
-            'but this one-word frame is an object whose address is passed to a callee, and the two name the same word',
+          `callee \`${ev.callee}\` is declared with ${declaredAs(ev, offs)}, so [sp,#0] is its outgoing stack argument — ` +
+            'but this one-word frame is an object whose address escapes the function, and the two name the same word',
         );
       }
     }
@@ -188,6 +268,20 @@ export function analyzeOutgoingArgs<C>({
     return { blocker: null, blocks: new Map(), area: 0 };
   }
 
+  const succs = asmBlocks.map((): number[] => []);
+  for (const b of live) {
+    for (const q of preds[b]) {
+      if (live.has(q)) {
+        succs[q].push(b);
+      }
+    }
+  }
+  // Every word at or above this is a proven local, so it is no call's argument. The three
+  // code-reading refusals below — the licence's NOTHING EXTRA, (a) and (b) — each hunt for a word
+  // that could be one, so the words they weigh are cut to those beneath the bound once, where
+  // they are collected (`mayAt`, `storedAnywhere`), and none of them repeats the test.
+  const belowBound = (s: Iterable<number>): Set<number> => new Set([...s].filter((o) => o < bound));
+
   const everySlot: number[] = [];
   for (let o = 0; o + 4 <= localArea; o += 4) {
     everySlot.push(o);
@@ -234,7 +328,7 @@ export function analyzeOutgoingArgs<C>({
       );
       for (const ev of asmBlocks[b].events) {
         if (isCallEvent(ev)) {
-          mayAt.set(ev, new Set(may));
+          mayAt.set(ev, belowBound(may));
           mustAt.set(ev, new Set(must));
           storedAt.set(ev, new Set(stored));
           for (const o of ev.declared ?? []) {
@@ -245,9 +339,18 @@ export function analyzeOutgoingArgs<C>({
           may.add(ev.off);
           must.add(ev.off);
           stored.add(ev.off);
-        } else {
+        } else if (ev.kind === 'load') {
           may.delete(ev.off);
           must.delete(ev.off);
+        } else {
+          // the receiver of the escaped address reads what it was handed, so those words stop
+          // being pending exactly as a reload would end them
+          for (const o of everySlot) {
+            if (o >= ev.off) {
+              may.delete(o);
+              must.delete(o);
+            }
+          }
         }
       }
       const grow = (out: Array<Set<number>>, cur: Set<number>): void => {
@@ -297,7 +400,7 @@ export function analyzeOutgoingArgs<C>({
     const extra = asc(may).filter((o) => !offs.includes(o));
     if (missing.length > 0 || extra.length > 0) {
       return refuse(
-        `callee \`${ev.callee}\` is declared with ${arityOf(offs)} arguments, so its outgoing stack-argument block is ${say(offs)} — but ` +
+        `callee \`${ev.callee}\` is declared with ${declaredAs(ev, offs)}, so its outgoing stack-argument block is ${say(offs)} — but ` +
           (missing.length > 0
             ? `${say(missing)} is not stored on every path to the call`
             : `${say(extra)} also reaches the call unread, so the declaration does not account for every word staged here`),
@@ -313,18 +416,52 @@ export function analyzeOutgoingArgs<C>({
       licensed.add(o);
     }
   }
+  // An ESCAPED ADDRESS AT OR BELOW A LICENSED WORD — the one-word captured frame's contradiction,
+  // at any frame size. The escape names the words from its offset up as an object's, a licensed
+  // block names one of them as a callee's argument, and nothing here can decide which to believe.
+  // Under agbcc the two never meet (an address-taken local sits ABOVE the outgoing area, and at
+  // [sp,#0] only when no call takes a stack word), so a function that has both is not agbcc's
+  // layout and declines.
+  const escapes = [...live].flatMap((b) => asmBlocks[b].events.flatMap((ev) => (ev.kind === 'escape' ? [ev.off] : [])));
+  const lowestEscape = Math.min(Infinity, ...escapes);
+  for (const ev of calls) {
+    const offs = blocks.get(ev.call) ?? [];
+    const clash = offs.find((o) => o >= lowestEscape);
+    if (clash !== undefined) {
+      return refuse(
+        `callee \`${ev.callee}\` is declared with ${declaredAs(ev, offs)}, so [sp,#${clash}] is its outgoing stack argument — ` +
+          `but the frame address [sp,#${lowestEscape}] escapes this function, so the words from there up are an object's, and the two name the same word`,
+      );
+    }
+  }
   // The two whole-function facts the next two refusals read: every offset live code stores, and
   // every offset live code loads back. A reload in dead code is not evidence that anything reads
   // the slot back, so it does not count.
   const reloaded = new Set<number>();
-  const storedAnywhere = new Set<number>();
+  const stores = new Set<number>();
   for (const b of live) {
     for (const ev of asmBlocks[b].events) {
-      if (ev.kind !== 'call') {
-        (ev.kind === 'store' ? storedAnywhere : reloaded).add(ev.off);
+      if (isSlotEvent(ev)) {
+        (ev.kind === 'store' ? stores : reloaded).add(ev.off);
       }
     }
   }
+  // …and a word an escaped address hands over is read by its receiver, which is a reload for (a):
+  // its never being read back HERE is explained by who reads it THERE.
+  //
+  // WHOLE-FUNCTION, unlike the pending sets above: a store after the last escape, or on a path
+  // that never escapes, is excused here too. That is sound because (a) is not what clears a word
+  // for a call. A word that is some call's argument reaches that call pending, and the licence's
+  // equality (a declared callee) or (b) (an undeclared one) refuses it there, per program point:
+  // `qh5`'s fifth `h5` word, staged after its memcpy base escapes, is refused by (b). What this
+  // widening lets through is a store that reaches no call pending with its lower slots supplied,
+  // which by CONTIGUITY (above) no call takes as an argument.
+  for (const o of everySlot) {
+    if (o >= lowestEscape) {
+      reloaded.add(o);
+    }
+  }
+  const storedAnywhere = belowBound(stores);
   // A LICENSED WORD THIS FUNCTION ALSO LOADS. The area belongs to the CALLEE — which may assign
   // to a stack parameter — so after the `bl` the word holds whatever the callee left, and an
   // `ldr` off that offset reads a GAP. The dataflow above cannot catch it: the call consumes the
@@ -347,7 +484,8 @@ export function analyzeOutgoingArgs<C>({
   // (a) — a store never reloaded ANYWHERE, with its lower slots supplied, is an argument's
   // signature: an outgoing argument is read by the CALLEE, never by the caller. Its real theorem
   // is the layout one (the area sits at the BOTTOM of localArea, disjoint from the locals, so no
-  // local load can land on an argument offset), which is why it is a whole-function question.
+  // local load can land on an argument offset), which is why it is a whole-function question, and
+  // why a word at or above `bound` never reaches it: the bound proves that theorem for it.
   // A LICENSED offset is excluded: its never being reloaded is explained by the call that takes it.
   for (const off of asc(storedAnywhere)) {
     if (!licensed.has(off) && !reloaded.has(off) && prefixStored(off, storedAnywhere)) {
@@ -384,7 +522,7 @@ export function analyzeOutgoingArgs<C>({
   // where the function ENDS. That is not an argument and not a local anyone reloads, so nothing
   // here can say what it is: decline rather than let it drop as a dead def.
   //
-  // "WHERE THE FUNCTION ENDS" IS A LIVE BLOCK WITH NO LIVE SUCCESSOR, read off `preds`, not a
+  // "WHERE THE FUNCTION ENDS" IS A LIVE BLOCK WITH NO LIVE SUCCESSOR, read off `succs`, not a
   // terminator the caller classified. Under Thumb the two coincide — a computed PC write has no
   // static successor and the frontend throws on one long before here — but asking the CFG costs
   // nothing and removes a fact the caller could get wrong.
@@ -396,16 +534,8 @@ export function analyzeOutgoingArgs<C>({
   // declines at L2: "unrecovered back-edge into block #1 (loop-recovery declined this shape)". So
   // the loud answer is preserved by a DIFFERENT family's refusal, not by this one. Closing it needs
   // a backward "can this word still be consumed?" pass, which no row in the corpus asks for.
-  const hasLiveSucc = asmBlocks.map(() => false);
-  for (let b = 0; b < asmBlocks.length; b++) {
-    if (live.has(b)) {
-      for (const q of preds[b]) {
-        hasLiveSucc[q] = true;
-      }
-    }
-  }
   for (let b = 0; b < asmBlocks.length; b++) {
-    if (!live.has(b) || hasLiveSucc[b]) {
+    if (!live.has(b) || succs[b].length > 0) {
       continue;
     }
     for (const off of asc(mayOut[b])) {