@asmlift/core 0.8.0 → 0.9.0

package/src/l3/ptrcell.ts

@@ -0,0 +1,357 @@
+// L3: a POINTER CELL — a global the body stores a pointer into, and the one place that spelling is
+// recognised.
+//
+// structure() spells a pointer value stored into a word global as `g = (void *)X` (structure.ts
+// `intoPtrCell`), the store every pointer declaration of `g` takes. Three readers act on it, and
+// all three ask `pointerCells` rather than re-reading the cast:
+//
+//   • l3/symbol-refs.ts declares a name-only cell `void *` in the candidate's own world, the type
+//     that store needs, and so each global the cell meets bare that nothing reads as an integer
+//     (`pointerPartners`);
+//   • `legalizePointerCells` below converts the cell's other uses to match that declaration;
+//   • l3/intcell.ts spells the cell as the integer a project may have declared instead.
+//
+// The fact is derived from the final tree at each reader rather than carried on SFn, for the reason
+// l3/symbol-refs.ts's header gives: a rewrite that drops the store must drop the fact with it.
+import { type IrType, T } from '../ir/types';
+import { declaredWidth } from '../proto';
+import { type Expr, type SFn, type Stmt, exprChildren, mapExprChildren, stmtChildren, walkExprs } from './ast';
+import { declaredTypes, exprCType } from './typing';
+
+/** The bare name an `assign` stores a `(void *)` value into: a pointer cell, when no local binds
+ *  it. */
+export function pointerCellStore(s: Stmt): string | undefined {
+  return s.k === 'assign' && s.value.k === 'cast' && s.value.to.kind === 'ptr' && s.value.to.to.kind === 'void'
+    ? s.name
+    : undefined;
+}
+
+const COMPARE = new Set(['<', '<=', '>', '>=', '==', '!=']);
+
+const assigns = (body: Stmt[]): Extract<Stmt, { k: 'assign' }>[] => {
+  const out: Extract<Stmt, { k: 'assign' }>[] = [];
+  const visit = (s: Stmt): void => {
+    if (s.k === 'assign') {
+      out.push(s);
+    }
+    stmtChildren(s).forEach(visit);
+  };
+  body.forEach(visit);
+  return out;
+};
+
+/** Whether `e` reads a variable `pick` takes. */
+const readsVar = (e: Expr, pick: (name: string) => boolean): boolean =>
+  (e.k === 'var' && pick(e.name)) || exprChildren(e).some((c) => readsVar(c, pick));
+
+/** A cell's value moved by integers (`g + 4`, `g + a0 - 8`): pointer arithmetic, a pointer as the
+ *  cell is. Whatever is added is an integer, as no pointer is; what is subtracted is a constant,
+ *  since a pointer's difference is no pointer. */
+export function cellOffset(e: Expr, cells: ReadonlySet<string>): boolean {
+  if (e.k !== 'bin' || (e.op !== '+' && e.op !== '-')) {
+    return false;
+  }
+  const base = (x: Expr): boolean => (x.k === 'var' && cells.has(x.name)) || cellOffset(x, cells);
+  const offset = (x: Expr): boolean => !readsVar(x, (n) => e.op === '-' || cells.has(n));
+  return (base(e.l) && offset(e.r)) || (e.op === '+' && base(e.r) && offset(e.l));
+}
+
+/** The globals `body` stores a pointer into: a `(void *)` store, or the bare value of another one,
+ *  or that value moved by integers (`cellOffset`). */
+export function pointerCells(body: Stmt[], isGlobal: (name: string) => boolean): Set<string> {
+  const stores = assigns(body).filter((s) => isGlobal(s.name));
+  const out = new Set(stores.filter((s) => pointerCellStore(s) !== undefined).map((s) => s.name));
+  for (let grew = true; grew;) {
+    grew = false;
+    for (const s of stores) {
+      if (!out.has(s.name) && ((s.value.k === 'var' && out.has(s.value.name)) || cellOffset(s.value, out))) {
+        out.add(s.name);
+        grew = true;
+      }
+    }
+  }
+  return out;
+}
+
+/** The bare globals a pointer cell meets bare: compared with one or with its `cellOffset`, or
+ *  stored into one. */
+function meetsBare(body: Stmt[], isGlobal: (name: string) => boolean, cells: ReadonlySet<string>): Set<string> {
+  const out = new Set<string>();
+  const meets = (e: Expr): void => {
+    if (e.k === 'var' && isGlobal(e.name) && !cells.has(e.name)) {
+      out.add(e.name);
+    }
+  };
+  const isCell = (e: Expr): boolean => (e.k === 'var' && cells.has(e.name)) || cellOffset(e, cells);
+  for (const s of assigns(body)) {
+    if (cells.has(s.name)) {
+      meets(s.value);
+    }
+  }
+  for (const e of walkExprs(body)) {
+    if (e.k === 'bin' && COMPARE.has(e.op)) {
+      if (isCell(e.l)) {
+        meets(e.r);
+      }
+      if (isCell(e.r)) {
+        meets(e.l);
+      }
+    }
+  }
+  return out;
+}
+
+/** Whether a name `sfn` reads is a global: no param or local binds it. */
+const globalOf = (sfn: SFn): ((name: string) => boolean) => {
+  const bound = new Set([...sfn.params.map((p) => p.name), ...sfn.locals.map((l) => l.name)]);
+  return (name) => !bound.has(name);
+};
+
+/** The globals `sfn` stores a pointer into (`pointerCells`). */
+export function pointerCellsOf(sfn: SFn): Set<string> {
+  return pointerCells(sfn.body, globalOf(sfn));
+}
+
+/** Whether a declared parameter spelling is an integer of at most a word: the conversion a pointer
+ *  argument needs to reach it. A spelling this cannot read is no opinion. */
+const integerParam = (t: string | undefined): boolean => {
+  if (t === undefined) {
+    return false;
+  }
+  const w = declaredWidth(t);
+  return w !== undefined && w <= 32 && !t.includes('*') && !t.includes('(');
+};
+
+/** What `mapIntegerSlots` does at each place a pointer cell meets an integer. */
+interface SlotRules {
+  /** An operand a cell meets bare, which no conversion takes. */
+  pointerTyped: (e: Expr) => boolean;
+  /** An operand the context reads as an integer. */
+  int: (e: Expr) => Expr;
+  /** An argument an integer parameter takes. */
+  intArg: (e: Expr) => Expr;
+  /** A bare global compared with a cell that is no partner. */
+  comparedGlobal: (e: Expr) => Expr;
+  /** A value stored into a cell. */
+  intoCell: (e: Expr) => Expr;
+  /** A `cellOffset` a pointer meets. */
+  pointerOffset: (e: Expr) => Expr;
+  /** A global stored into that is no cell, which is an integer slot. */
+  storedGlobal: (name: string) => void;
+}
+
+/** `sfn` with `rules` applied at every place its context states an integer type: an operand of a
+ *  non-additive operator, of `-`/`~`, an index, a switch, a comparison with no pointer, a call
+ *  argument whose callee's declared parameter (`SFn.declaredArgs`) is an integer, and a store, an
+ *  assignment or a return into an integer slot. A global stored into that is no cell is an integer
+ *  slot: the candidate's own world declares it one. */
+function mapIntegerSlots(sfn: SFn, cells: ReadonlySet<string>, rules: SlotRules): SFn {
+  const isGlobal = globalOf(sfn);
+  const vt = declaredTypes(sfn);
+  const isCell = (e: Expr): boolean => (e.k === 'var' && cells.has(e.name)) || cellOffset(e, cells);
+  const bareGlobal = (e: Expr): boolean => e.k === 'var' && isGlobal(e.name) && !cells.has(e.name);
+  const compare = (x: Expr, other: Expr): Expr =>
+    isCell(other) && bareGlobal(x) && !rules.pointerTyped(x)
+      ? rules.comparedGlobal(x)
+      : rules.pointerTyped(other) || cellOffset(other, cells)
+        ? cellOffset(x, cells)
+          ? rules.pointerOffset(x)
+          : x
+        : rules.int(x);
+  const expr = (e0: Expr): Expr => {
+    const e = mapExprChildren(e0, expr);
+    switch (e.k) {
+      case 'bin':
+        if (e.op === '&&' || e.op === '||' || e.op === '+' || e.op === '-') {
+          return e;
+        }
+        if (COMPARE.has(e.op)) {
+          return { ...e, l: compare(e.l, e.r), r: compare(e.r, e.l) };
+        }
+        return { ...e, l: rules.int(e.l), r: rules.int(e.r) };
+      case 'un':
+        return e.op === '-' || e.op === '~' ? { ...e, e: rules.int(e.e) } : e;
+      case 'call': {
+        const params =
+          typeof e.fn === 'string' && sfn.declaredArgs && Object.hasOwn(sfn.declaredArgs, e.fn)
+            ? sfn.declaredArgs[e.fn]
+            : undefined;
+        if (params === undefined) {
+          return e;
+        }
+        return { ...e, args: e.args.map((a, i) => (integerParam(params[i]) ? rules.intArg(a) : a)) };
+      }
+      case 'index':
+        return { ...e, idx: rules.int(e.idx), ...(e.lead ? { lead: e.lead.map(rules.int) } : {}) };
+      default:
+        return e;
+    }
+  };
+
+  const stmt = (s: Stmt): Stmt => {
+    switch (s.k) {
+      case 'assign': {
+        const value = expr(s.value);
+        if (cells.has(s.name)) {
+          return { ...s, value: rules.pointerTyped(value) ? value : rules.intoCell(value) };
+        }
+        const t = vt(s.name);
+        if (t === undefined && isGlobal(s.name)) {
+          rules.storedGlobal(s.name);
+          return { ...s, value: rules.int(value) };
+        }
+        return { ...s, value: t?.kind === 'int' ? rules.int(value) : value };
+      }
+      case 'store': {
+        const value = expr(s.value);
+        return {
+          ...s,
+          lval: expr(s.lval),
+          value: exprCType(s.lval, vt)?.kind === 'int' ? rules.int(value) : value,
+        };
+      }
+      case 'exprstmt':
+        return { ...s, value: expr(s.value) };
+      case 'return':
+        return s.value ? { ...s, value: sfn.retType.kind === 'int' ? rules.int(expr(s.value)) : expr(s.value) } : s;
+      case 'if':
+        return { ...s, cond: expr(s.cond), then: s.then.map(stmt), else: s.else.map(stmt) };
+      case 'while':
+      case 'dowhile':
+        return { ...s, cond: expr(s.cond), body: s.body.map(stmt) };
+      case 'for':
+        return { ...s, init: stmt(s.init), cond: expr(s.cond), inc: stmt(s.inc), body: s.body.map(stmt) };
+      case 'switch':
+        return {
+          ...s,
+          scrutinee: rules.int(expr(s.scrutinee)),
+          cases: s.cases.map((c) => ({ ...c, body: c.body.map(stmt) })),
+          default: s.default?.map(stmt),
+        };
+      case 'break':
+      case 'continue':
+        return s;
+    }
+  };
+  return { ...sfn, body: sfn.body.map(stmt) };
+}
+
+/** A sum no operand of which renders a pointer: read as an integer, each bare name in it is. */
+const integerSum = (e: Expr, vt: (name: string) => IrType | undefined): e is Extract<Expr, { k: 'bin' }> =>
+  e.k === 'bin' &&
+  (e.op === '+' || e.op === '-') &&
+  exprCType(e.l, vt)?.kind !== 'ptr' &&
+  exprCType(e.r, vt)?.kind !== 'ptr';
+
+/** The globals a pointer cell meets bare (compared with it or its offset, or stored into it) that hold a pointer
+ *  too: the candidate's own world declares each `void *` beside the cells, and they are left as
+ *  spelled, since converting one would convert whatever the project declares it, where bare a
+ *  float, an array or a function meets the cell as a constraint violation.
+ *
+ *  A global the body also reads as an integer is not one: `void *` takes none of those reads, so its
+ *  own world declares it the integer it is read as, and the cell converts to meet it. */
+export function pointerPartners(sfn: SFn): Set<string> {
+  const isGlobal = globalOf(sfn);
+  const cells = pointerCells(sfn.body, isGlobal);
+  const meets = meetsBare(sfn.body, isGlobal, cells);
+  if (meets.size === 0) {
+    return meets;
+  }
+  const vt = declaredTypes(sfn);
+  const read = new Set<string>();
+  const int = (e: Expr): Expr => {
+    if (e.k === 'var' && meets.has(e.name)) {
+      read.add(e.name);
+    } else if (integerSum(e, vt)) {
+      int(e.l);
+      int(e.r);
+    }
+    return e;
+  };
+  mapIntegerSlots(sfn, cells, {
+    pointerTyped: (e) => e.k === 'var' && (cells.has(e.name) || meets.has(e.name)),
+    int,
+    intArg: int,
+    comparedGlobal: int,
+    intoCell: (e) => e,
+    pointerOffset: (e) => e,
+    storedGlobal: (name) => {
+      if (meets.has(name)) {
+        read.add(name);
+      }
+    },
+  });
+  return new Set([...meets].filter((n) => !read.has(n)));
+}
+
+/** `sfn` with every integer use of a pointer cell converted to the integer it reads as, and every
+ *  integer stored into one converted to a pointer.
+ *
+ *  A cell the body stores a pointer into is a pointer under every declaration that store compiles
+ *  against, so the cell's integer readers (`return g;`, `if (g >= a0)`, `v0 = g;`, `g + 4` returned
+ *  as an integer, an integer parameter's argument) and its integer writers (`g = a0;`) need the
+ *  conversion C leaves implicit and CodeWarrior and IDO reject: `(u32)g`, `g = (void *)a0`. The
+ *  conversion of a word is no instruction, so the bytes are the implicit one's. A cell's offset
+ *  (`cellOffset`) stored into a cell or compared with a pointer is the pointer it is, spelled in
+ *  bytes: `gOut = (void *)((u8 *)g + 4)`, `(u8 *)g + 4 == gP`.
+ *
+ *  SCOPE: a use whose context states an integer type (`mapIntegerSlots`); elsewhere the use is left
+ *  as the structurer spelled it. A truth test, a sum that renders a pointer (the structurer's own
+ *  byte sum, which the backend converts at an integer slot: `legalizePointerWrites`), and a
+ *  comparison with a pointer (a call by its declared return, `SFn.declaredReturns`), with 0 or with
+ *  a partner (`pointerPartners`) are left alone. A global compared with the cell that is no partner
+ *  goes `(u32)(u8 *)g` beside the cell's `(u32)g`: under a float declaration that is no C, as the
+ *  bare comparison was not. KNOWN GAP: under an array or a function declaration that is the
+ *  global's address, compared with no diagnostic, and IDO takes the integer read that made it no
+ *  partner (`v1 = g`) with none either; structure.ts `globalWord` says why no spelling reads the
+ *  word there.
+ *
+ *  Run by the C-family backend's `emit` (backend/cfamily.ts), after every respell variation, so a
+ *  respell reads the uses as the structurer spelled them and a store it removes takes the
+ *  conversions with it. */
+export function legalizePointerCells(sfn: SFn): SFn {
+  const cells = pointerCellsOf(sfn);
+  if (cells.size === 0) {
+    return sfn;
+  }
+  const partners = pointerPartners(sfn);
+  const vt = declaredTypes(sfn);
+  const isCell = (e: Expr): boolean => e.k === 'var' && cells.has(e.name);
+  const returnsPointer = (fn: string | Expr): boolean =>
+    typeof fn === 'string' &&
+    sfn.declaredReturns !== undefined &&
+    Object.hasOwn(sfn.declaredReturns, fn) &&
+    sfn.declaredReturns[fn].includes('*');
+  const asInt = (e: Expr): Expr =>
+    isCell(e) ? { k: 'cast', to: T.u(32), e } : integerSum(e, vt) ? { ...e, l: asInt(e.l), r: asInt(e.r) } : e;
+  // A cell's offset as the pointer it is: byte arithmetic on the cell, `(u8 *)g + 4`, which no
+  // pointee scales and which a `void *` takes.
+  const asBytes = (e: Expr): Expr =>
+    isCell(e)
+      ? { k: 'cast', to: T.ptr(T.u(8)), e }
+      : e.k === 'bin' && cellOffset(e, cells)
+        ? { ...e, l: asBytes(e.l), r: e.op === '+' ? asBytes(e.r) : e.r }
+        : e;
+  // The structurer's byte sum on a cell's value (`(u8 *)g + 8`) is a pointer too, which an integer
+  // parameter takes converted as a bare cell does; the backend converts it at every other integer
+  // slot (`legalizePointerWrites`).
+  const cellSum = (e: Expr): boolean =>
+    (e.k === 'cast' && e.to.kind === 'ptr' && isCell(e.e)) ||
+    (e.k === 'bin' && (e.op === '+' || e.op === '-') && (cellSum(e.l) || cellSum(e.r)));
+  return mapIntegerSlots(sfn, cells, {
+    pointerTyped: (e) =>
+      isCell(e) ||
+      (e.k === 'var' && partners.has(e.name)) ||
+      e.k === 'addr' ||
+      (e.k === 'call' && returnsPointer(e.fn)) ||
+      (e.k === 'const' && e.value === 0) ||
+      exprCType(e, vt)?.kind === 'ptr',
+    int: asInt,
+    intArg: (e) =>
+      e.k === 'bin' && cellSum(e) && exprCType(e, vt)?.kind === 'ptr' ? { k: 'cast', to: T.u(32), e } : asInt(e),
+    comparedGlobal: (e) => ({ k: 'cast', to: T.u(32), e: { k: 'cast', to: T.ptr(T.u(8)), e } }),
+    intoCell: (e) => ({ k: 'cast', to: T.ptr(T.void()), e: asBytes(e) }),
+    pointerOffset: asBytes,
+    storedGlobal: () => {},
+  });
+}

package/src/l3/regspell.ts

@@ -40,6 +40,7 @@ function isPure(e: Expr): boolean {
   switch (e.k) {
     case 'var':
     case 'const':
+    case 'fconst':
       return true;
     case 'un':
     case 'cast':
@@ -56,6 +57,9 @@ function renameVar(e: Expr, from: string, to: string): Expr {
   if (e.k === 'var') {
     return e.name === from ? { k: 'var', name: to } : e;
   }
+  if (e.k === 'postincr') {
+    return e.name === from ? { ...e, name: to } : e;
+  }
   return mapExprChildren(e, (c) => renameVar(c, from, to));
 }
 
@@ -251,12 +255,22 @@ export function registerishSpellings(sfn: SFn): RegcopySpelling[] {
           //   • E and the cond pure; the cond's non-E operand must NOT mention v (a clamp's
           //     `if (a < v)` would compare against the POST-assignment v — reproduced);
           //   • the copy w carries E's RENDERED type, not v's declared one (retyping a u32
-          //     comparison signed flipped its sense — reproduced).
-          if (!isPure(E) || !isPure(cond) || condOtherMentions(cond, E, v)) {
+          //     comparison signed flipped its sense — reproduced), PROMOTED: the update assigns
+          //     back into w, and a narrow w would truncate what the update computed;
+          //   • v not narrow, because then v's declaration IS the update's truncation, which a
+          //     word-wide w would drop.
+          const vType = typeOf(v);
+          if (
+            !isPure(E) ||
+            !isPure(cond) ||
+            condOtherMentions(cond, E, v) ||
+            (vType.kind === 'int' && vType.width < 32)
+          ) {
             out.push(s);
             continue;
           }
-          const wType = exprCType(E, declaredTypes({ ...sfn, locals })) ?? typeOf(v);
+          const rendered = exprCType(E, declaredTypes({ ...sfn, locals })) ?? vType;
+          const wType = rendered.kind === 'int' && rendered.width < 32 ? T.s(32) : rendered;
           const w = freshVar(wType);
           const condOnW = rewriteCond(cond, E, w);
           if (condOnW) {

package/src/l3/reindex.ts

@@ -95,6 +95,7 @@ import {
   Stmt,
   mapExprChildren,
   mapStmtExprs,
+  mentionedName,
   rematerializableAddress,
   stmtChildren,
   stmtExprs,
@@ -109,14 +110,15 @@ interface WalkLoop {
   base: string; // the var `p` was initialised from
 }
 
-/** Total mentions of `name` across a statement list (reads, writes, everywhere). `addr` counts:
- *  `&x` is how a frame local's address renders (structure.ts laddrName), and an escaped address
- *  is a read of the object by whatever holds it — the accounting these recognizers rest on is
- *  "nothing else in the function touches this name", which a var-only count cannot say. */
+/** Total mentions of `name` across a statement list (reads, writes, everywhere) — `mentionedName`'s
+ *  whole vocabulary, because the accounting these recognizers rest on is "nothing else in the
+ *  function touches this name", which a var-only count cannot say. `&x` is how a frame local's
+ *  address renders (structure.ts laddrName), and an escaped address is a read of the object by
+ *  whatever holds it. */
 function countMentions(stmts: Stmt[], name: string): number {
   let n = 0;
   const inExpr = (e: Expr): void => {
-    if ((e.k === 'var' || e.k === 'addr') && e.name === name) {
+    if (mentionedName(e) === name) {
       n++;
     }
     mapExprChildren(e, (c) => {
@@ -170,8 +172,9 @@ function derefWidths(stmts: Stmt[], p: string): number[] {
 
 /** Does `e` mention `name` anywhere — as a value or as an escaped address (see countMentions)? */
 function mentionsVar(e: Expr, name: string): boolean {
-  if (e.k === 'var' || e.k === 'addr') {
-    return e.name === name;
+  const own = mentionedName(e);
+  if (own !== undefined) {
+    return own === name;
   }
   let found = false;
   mapExprChildren(e, (c) => {

package/src/l3/symbol-refs.ts

@@ -16,8 +16,12 @@
 // to recompute it (a dead-store DCE that drops a tree's only reference would otherwise leave a
 // stale ref, transitively reintroducing the hazards the collector excludes). Deriving at the
 // consumption point makes staleness impossible by construction.
+import type { IrType } from '../ir/types';
+import { type AggregateLayout, type ParamType, type Prototypes, spellableProto } from '../proto';
 import type { SymbolInfo } from '../symbols';
-import { Expr, Stmt, exprChildren, stmtChildren, stmtExprs } from './ast';
+import type { TargetDescription } from '../target';
+import { Expr, SFn, Stmt, exprChildren, mentionedName, stmtChildren, stmtExprs } from './ast';
+import { pointerCellsOf, pointerPartners } from './ptrcell';
 
 /** One recorded VALUE reference — a name the tree references plus the facts to declare it. */
 export interface SymbolRef {
@@ -27,43 +31,88 @@ export interface SymbolRef {
    *  own IR — attached by the enumeration (rank.ts bareGlobalAccessFacts), consumed by the
    *  declaration synthesis (declare.ts) as the width/signedness authority for `extern T name;`. */
   access?: { width: number; signed: boolean };
-  /** NO SYMBOL MAP KNOWS THIS NAME — the declaration for it is a HYPOTHESIS, not a fact. Both the
-   *  name and (through `access`) its width and signedness were read out of the candidate's own
-   *  asm: the very bytes the candidate is then scored against. A fitted declaration cannot LOSE
-   *  score, so it is not covered by declare.ts's only-loses-score argument — it can manufacture
-   *  agreement instead. Which is legitimate (the artifact is decls + source, and it does compile
-   *  to those bytes) exactly as long as the consumer SHOWS the declarations with the verdict.
-   *  Marked here so a consumer can tell the two provenances apart inside one block. */
+  /** NO SYMBOL MAP ACCOUNTS FOR THIS NAME — that is the whole predicate, and it is one fact with
+   *  two provenances the consumer must be able to tell apart.
+   *
+   *  WITHOUT `proto`, the declaration is a HYPOTHESIS: the name and (through `access`) its width
+   *  and signedness were read out of the candidate's own asm — the very bytes the candidate is
+   *  then scored against. A fitted declaration cannot LOSE score, so it is not covered by
+   *  declare.ts's only-loses-score argument; it can manufacture agreement instead. Which is
+   *  legitimate (the artifact is decls + source, and it does compile to those bytes) exactly as
+   *  long as the consumer SHOWS the declarations with the verdict.
+   *
+   *  WITH `proto`, the declaration's TEXT is the project's own — a call target asmlift has a
+   *  prototype for — and asmlift invented nothing about it. It is still marked, because the
+   *  predicate this flag states is about the symbol MAP and not about who wrote the type, and
+   *  because the score rests on that line being in the translation unit either way. A consumer
+   *  wording the block reads `proto` to say which it is looking at; dropping the mark instead
+   *  would under-report a declaration the verdict depends on, which is the direction
+   *  `synthesizedRefs` exists to avoid. */
   synthesized?: true;
+  /** A CALL TARGET's own declaration, re-spelled from the prototype the project supplied — the
+   *  parameter type texts and the return type text, verbatim as the user wrote them. Present only
+   *  where {@link spellableProto} could read a COMPLETE C prototype out of the `FnProto`, and it
+   *  is what `declare.ts` prints instead of an `extern`: a call target is a function, and
+   *  `extern u32 llsrc;` is not a declaration of it. Absent where the symbol map calls the name
+   *  something other than code — two facts that disagree are not one fact — and that subtraction
+   *  happens at the table (`proto.ts` `prototypesFromSymbols`), so the frontend loses the same
+   *  fact in the same place rather than acting on one this withheld. */
+  proto?: { readonly params: readonly ParamType[]; readonly returns: ParamType };
+  /** The struct a call target returns through memory — a type the project's headers own
+   *  (ir/types.ts `declared`), so `declare.ts` defines it beside `proto`, whose `returns` spells it:
+   *  by its tag (`name`), from the members the declaration lists (`layout`, which the lift laid out
+   *  to type the call). */
+  returned?: { readonly name: string; readonly declared: string; readonly layout: AggregateLayout };
+  /** The bare name holds a pointer (l3/ptrcell.ts): the body stores one into it, or it meets such a
+   *  cell bare and nothing reads it as an integer (`pointerPartners`). A name-only declaration of it
+   *  is a pointer, which the store needs and an integer cell rejects on CodeWarrior. */
+  holdsPointer?: true;
 }
 
 /** The declarable symbols a structured body references in a VALUE context — the input to the
  *  scoring layer's declaration synthesis. A name counts when it appears as a `var`/`addr` leaf
  *  and the caller's dictionary knows it (bare `gSym`, `&gSym`, `(u32)Func`, a `field` base — all reduce to
- *  those leaves). A name that is ANY call's target is excluded entirely, even if also
- *  value-referenced: prototyping a called symbol `void F(void);` hard-errors under gcc-2.9
- *  when the call passes args, while leaving it undeclared keeps today's implicit-declaration
- *  behavior (the one honest option without arity knowledge). The function's OWN name
- *  (`selfName`) is excluded too — the candidate's definition IS its declaration, and a
+ *  those leaves). The function's OWN name
+ *  (`tree.name`) is excluded too — the candidate's definition IS its declaration, and a
  *  synthesized `void F(void);` above `s32 F(...)` is a conflicting-types hard error (a
  *  self-address reference resolves against the definition itself).
  *
+ *  A CALL TARGET IS DECLARED WHEN, AND ONLY WHEN, THE PROJECT DECLARED IT COMPLETELY. `void
+ *  F(void);` hard-errors under gcc-2.9 the moment the call passes an argument, so with no arity
+ *  knowledge the honest option is to leave the name undeclared and keep C's implicit-declaration
+ *  behaviour — which is what this did for every call target and still does for every one the
+ *  prototype table cannot spell. Where it CAN (`spellableProto`), that knowledge is exactly what
+ *  the refusal said it lacked, and the declaration is the project's own text rather than a guess.
+ *  It is needed: an implicit declaration is `int`, so `(s64)llsrc()` sign-extends a word and the
+ *  candidate carries an `asr` the target does not have.
+ *
  *  Both exclusions are REPORTED through `onRefused`, on the caller's own refusal channel: they
  *  leave a name undeclared for asmlift's own reason, and a consumer's list of those reasons is
  *  incomplete without them. */
 export function collectSymbolRefs(
-  body: Stmt[],
+  tree: SFn,
   symbols: Map<string, SymbolInfo>,
-  selfName: string,
+  /** the project's prototype table — the only thing that can turn a call target into a
+   *  declaration. REQUIRED, not optional: a caller that forgot it would silently get the old
+   *  blanket refusal back, which is the shape of an optional refusal a second caller switches off. */
+  prototypes: Prototypes,
+  /** which declared types the frontend lays out, so which a printed prototype may carry */
+  target: Pick<TargetDescription, 'doubleArgWords'>,
   onRefused?: (name: string, reason: 'call-target' | 'self-name') => void,
 ): SymbolRef[] {
   const called = new Set<string>();
+  // the struct a callee returns through memory, as the lift typed it
+  const returned = new Map<string, Extract<IrType, { kind: 'struct' }>>();
   const valueRefs = new Set<string>();
   const visitExpr = (e: Expr): void => {
-    if (e.k === 'call') {
+    const named = mentionedName(e);
+    if (e.k === 'call' && typeof e.fn === 'string') {
       called.add(e.fn);
-    } else if ((e.k === 'var' || e.k === 'addr') && symbols.has(e.name)) {
-      valueRefs.add(e.name);
+      if (e.sret?.kind === 'struct') {
+        returned.set(e.fn, e.sret);
+      }
+    } else if (named !== undefined && symbols.has(named)) {
+      valueRefs.add(named);
     }
     exprChildren(e).forEach(visitExpr);
   };
@@ -76,19 +125,51 @@ export function collectSymbolRefs(
     stmtExprs(s).forEach(visitExpr);
     stmtChildren(s).forEach(visitStmt);
   };
-  body.forEach(visitStmt);
-  return [...valueRefs]
+  tree.body.forEach(visitStmt);
+  const holdsPointer = new Set([...pointerCellsOf(tree), ...pointerPartners(tree)]);
+  // A call target is a ref in its own right, whether or not the body also names it as a value —
+  // `Object.hasOwn`, because `prototypes` is caller-supplied JSON and a callee may be named
+  // `toString`. The union is sorted as one list so the rendered block stays deterministic.
+  const proto = new Map<string, NonNullable<SymbolRef['proto']>>();
+  for (const n of called) {
+    // TWO FACTS ABOUT ONE NAME, AND A DISAGREEMENT IS SILENCE — decided at the TABLE, not here. A
+    // map entry that states a data shape for this name contradicts the prototype that calls it a
+    // function, and `proto.ts` `prototypesFromSymbols` has already taken the `returns` off such an
+    // entry, so what arrives here states no printable prototype and the frontend read the call the
+    // same way. Testing it a second time at this reader is what let the two answer differently.
+    const p = Object.hasOwn(prototypes, n) ? spellableProto(prototypes[n], target, returned.get(n)) : undefined;
+    if (p !== undefined) {
+      proto.set(n, p);
+    }
+  }
+  return [...new Set([...valueRefs, ...proto.keys()])]
     .sort()
     .filter((n) => {
-      if (called.has(n)) {
+      if (called.has(n) && !proto.has(n)) {
         onRefused?.(n, 'call-target');
         return false;
       }
-      if (n === selfName) {
+      if (n === tree.name) {
         onRefused?.(n, 'self-name');
         return false;
       }
       return true;
     })
-    .map((n) => ({ name: n, info: symbols.get(n)! }));
+    .map((n) => {
+      const p = proto.get(n);
+      // A call target the map never mentioned still has to carry an `info` — it is a code symbol
+      // and that is all this knows about it. `declare.ts` prints the prototype and never reaches
+      // the shape, so nothing here is guessed about storage that does not exist.
+      const info = symbols.get(n) ?? { name: n, kind: 'code' as const };
+      const r = p ? returned.get(n) : undefined;
+      const layout = r?.declared !== undefined ? prototypes[n].returnLayout : undefined;
+      const definition = layout?.members !== undefined ? { name: r!.name, declared: r!.declared!, layout } : undefined;
+      return {
+        name: n,
+        info,
+        ...(p ? { proto: p } : {}),
+        ...(definition ? { returned: definition } : {}),
+        ...(holdsPointer.has(n) ? { holdsPointer: true as const } : {}),
+      };
+    });
 }