@asmlift/core 0.9.0 → 0.11.0

package/src/cdecl/parse.ts

@@ -369,6 +369,27 @@ class Parser {
     if (specifiers === null) {
       return null;
     }
+    // C89's implicit `int` ahead of a declarator list: `extern gN, gM;` and `static gA[4];` read the
+    // first name as a type word, and in valid C no type is followed by `,`, `=` or `[`. The word goes
+    // back to being the first declarator. A lone `extern gN;` is a statement this cannot tell from
+    // an unknown type declaring nothing; `proto-context.ts` reads that one against the types the
+    // context declares.
+    const { storage, type, unknownWords } = specifiers;
+    const next = this.t.char(this.i);
+    if (
+      !this.cxx &&
+      (storage.includes('extern') || storage.includes('static')) &&
+      type.kind === 'words' &&
+      type.words.length === 1 &&
+      !BASIC.has(type.words[0]) &&
+      unknownWords.length === 0 &&
+      (next === COMMA || next === EQUALS || next === OPEN_BRACKET) &&
+      this.t.text(this.i - 1) === type.words[0]
+    ) {
+      this.i--;
+      specifiers.type = { kind: 'words', words: ['int'] };
+      specifiers.spelling = 'int';
+    }
     const declarators: Declarator[] = [];
     if (this.t.char(this.i) === SEMICOLON) {
       this.i++;

package/src/contracts.ts

@@ -9,8 +9,9 @@ import { placedAt } from './ir/discipline';
 import { MEM_BASE_OPS } from './ir/opcodes';
 import { type IrType, memberOf, typeToString } from './ir/types';
 import { cellAddress, qualifiedBase } from './l3/address';
-import { type BinOp, type Expr, type SFn, type Stmt, calleeOf } from './l3/ast';
+import { type BinOp, type Expr, type SFn, type Stmt, calleeOf, caseGotoViolation, switchArmSuccessors } from './l3/ast';
 import {
+  assignsIn,
   exprChildren,
   fieldSpellsDot,
   gapReasonFor,
@@ -19,9 +20,11 @@ import {
   stmtChildren,
   stmtExprs,
   stmtLists,
+  taintOverAssigns,
   walkExprs,
 } from './l3/ast';
 import { mentionedLocals } from './l3/mentions';
+import { localAddresses } from './l3/storage';
 import { declaredTypes, exprCType } from './l3/typing';
 import { castOffDeclaration } from './l3/volstore';
 
@@ -188,17 +191,23 @@ function qualifiedAccessChain(e: Expr): boolean {
 }
 
 /** The global an access's address is named by: its base through casts, address arithmetic and the
- *  element or member a dot member selects from, down to `gSym` or `&gSym`. Null when the base is
+ *  element or member a dot member selects from, down to `&gSym`, or to a `gSym` that spells its own
+ *  address — an array's name, which decays to it (`addresses`), or the struct a dot member selects
+ *  from (`dotted`). Any other bare `gSym` is the object's VALUE: `*(u16 *)gPtr` reads what the
+ *  pointer points at, not the pointer, so the access names no object. Null too when the base is
  *  anything else — another access, a local. */
-function accessedObject(base: Expr): string | null {
+function accessedObject(base: Expr, addresses: ReadonlySet<string>, dotted = false): string | null {
   switch (base.k) {
     case 'var':
+      return dotted || addresses.has(base.name) ? base.name : null;
     case 'addr':
       return base.name;
     case 'cast':
-      return accessedObject(base.e);
+      return accessedObject(base.e, addresses);
     case 'bin':
-      return base.op === '+' || base.op === '-' ? (accessedObject(base.l) ?? accessedObject(base.r)) : null;
+      return base.op === '+' || base.op === '-'
+        ? (accessedObject(base.l, addresses) ?? accessedObject(base.r, addresses))
+        : null;
     default:
       return null;
   }
@@ -211,6 +220,9 @@ interface TreeContext {
   declared: ReadonlySet<string>;
   written: ReadonlySet<string>;
   typeOf: (e: Expr) => IrType | undefined;
+  /** The names whose bare spelling is the object's address: the array-declared globals the
+   *  structurer subscripts by name (SFn.globals), and the array or struct statics it defines. */
+  addresses: ReadonlySet<string>;
 }
 
 /** every call under `e`, counted by target name; every qualified memory access, by the address it
@@ -231,7 +243,9 @@ function effectsInExpr(
 ): void {
   const bump = (k: string) => into.set(k, (into.get(k) ?? 0) + 1);
   const access = e.k === 'index' || e.k === 'field';
-  const object = access && !selected ? accessedObject(dotSelected(e)) : null;
+  const inner = access && !selected ? dotSelectedAccess(e) : null;
+  const object =
+    inner === null ? null : accessedObject(inner.base, ctx.addresses, inner.k === 'field' && fieldSpellsDot(inner));
   const ofDeclared = object !== null && !target && ctx.declared.has(object);
   const writesDeclared = object !== null && target && ctx.written.has(object);
   if (e.k === 'call') {
@@ -248,7 +262,9 @@ function effectsInExpr(
     if (object !== null) {
       bump(`${ofDeclared && castOffDeclaration(e, ctx.typeOf) ? STRIPPED : DECLARED}${object}`);
     }
-  } else if (!named && !target && e.k === 'var') {
+  } else if (!target && e.k === 'var' && !(named && (selected || ctx.addresses.has(e.name)))) {
+    // A bare name is a read of the object's value unless it spells the address of an access, which
+    // counts it: the struct a dot member selects from, or an array's decayed name.
     bump(`${DECLARED}${e.name}`);
   }
   const partOfThis = e.k === 'field' && fieldSpellsDot(e);
@@ -257,23 +273,27 @@ function effectsInExpr(
   );
 }
 
-/** A dot member's own base chain, past the element or member it selects from: the address of the
- *  one access the member spells. */
-function dotSelected(e: Extract<Expr, { k: 'index' } | { k: 'field' }>): Expr {
+type Access = Extract<Expr, { k: 'index' } | { k: 'field' }>;
+
+/** A dot member's innermost access, past the element or member it selects from: its base is the
+ *  address of the one access the member spells. */
+function dotSelectedAccess(e: Access): Access {
   if (e.k === 'field' && fieldSpellsDot(e) && (e.base.k === 'index' || e.base.k === 'field')) {
-    return dotSelected(e.base);
+    return dotSelectedAccess(e.base);
   }
-  return e.base;
+  return e;
 }
 
 /** The executions on the paths through a statement list, split by how each path LEAVES it: falling off
- *  the end, or by a `return`, `break` or `continue`. Null when no path leaves that way. Each is the
+ *  the end, or by a `return`, `break`, `continue` or case-end `goto` (`end`, which leaves every loop
+ *  up to its switch arm and then the switch). Null when no path leaves that way. Each is the
  *  per-name maximum over the paths of that kind. */
 interface PathCounts {
   through: EffectCounts | null;
   ret: EffectCounts | null;
   brk: EffectCounts | null;
   cont: EffectCounts | null;
+  end: EffectCounts | null;
 }
 
 const sum = (a: EffectCounts, b: EffectCounts): EffectCounts => combine(a, b, (x, y) => x + y);
@@ -285,6 +305,7 @@ const after = (c: EffectCounts, p: PathCounts): PathCounts => ({
   ret: p.ret && sum(c, p.ret),
   brk: p.brk && sum(c, p.brk),
   cont: p.cont && sum(c, p.cont),
+  end: p.end && sum(c, p.end),
 });
 /** `a` then `b`: only a path that falls off the end of `a` reaches `b` */
 const seq = (a: PathCounts, b: PathCounts): PathCounts =>
@@ -295,6 +316,7 @@ const seq = (a: PathCounts, b: PathCounts): PathCounts =>
         ret: most(a.ret, b.ret && sum(a.through, b.ret)),
         brk: most(a.brk, b.brk && sum(a.through, b.brk)),
         cont: most(a.cont, b.cont && sum(a.through, b.cont)),
+        end: most(a.end, b.end && sum(a.through, b.end)),
       };
 /** whichever of the alternatives runs */
 const either = (...ps: PathCounts[]): PathCounts => ({
@@ -302,14 +324,18 @@ const either = (...ps: PathCounts[]): PathCounts => ({
   ret: most(...ps.map((p) => p.ret)),
   brk: most(...ps.map((p) => p.brk)),
   cont: most(...ps.map((p) => p.cont)),
+  end: most(...ps.map((p) => p.end)),
 });
-const falls = (c: EffectCounts): PathCounts => ({ through: c, ret: null, brk: null, cont: null });
+const falls = (c: EffectCounts): PathCounts => ({ through: c, ret: null, brk: null, cont: null, end: null });
 
 /** `total` = every occurrence in the tree; `paths` = the most any single syntactic path executes,
  *  by how it leaves `stmts`. A path that leaves by `return` runs nothing after it, so two sequenced
  *  `if (…) { f(); return; }` arms are one call on any path, not two. `unreached` collects every
  *  statement that follows one no path falls past: the path count skips it, so the caller refuses it
- *  rather than let a duplicated region hide there. */
+ *  rather than let a duplicated region hide there. A labelled `break;` no path falls into is not
+ *  one of them while a case-end `goto` in an earlier statement of the list is still leaving
+ *  (`paths.end`): the goto lands on it, or on a labelled `break;` further out that this one's
+ *  `break` reaches too, so it is reached, and it holds no code a region could hide in. */
 function countEffects(
   stmts: Stmt[],
   ctx: TreeContext,
@@ -318,7 +344,7 @@ function countEffects(
   let total: EffectCounts = new Map();
   let paths = falls(new Map());
   for (const s of stmts) {
-    if (paths.through === null) {
+    if (paths.through === null && !(s.k === 'break' && s.label !== undefined && paths.end !== null)) {
       unreached.push(s);
     }
     const own: EffectCounts = new Map();
@@ -336,31 +362,64 @@ function countEffects(
       total = arms.reduce((acc, a) => sum(acc, a.total), sum(total, dflt.total));
       // A fall-through arm continues into the NEXT one emitted (the last into `default`), so a
       // path through arm i runs the chain starting at i — the shape the fall-through round's
-      // CRITICAL took. Built from the end; `chain[i]` is that arm's paths.
-      const chain: PathCounts[] = new Array(arms.length);
-      for (let i = arms.length - 1; i >= 0; i--) {
-        const next = i + 1 < arms.length ? chain[i + 1] : dflt.paths;
-        chain[i] = s.cases[i].fallsThrough ? seq(arms[i].paths, next) : arms[i].paths;
-      }
-      // No `default` is one more alternative: no arm runs. A `break` leaves the switch, so it
-      // continues after it as a fall-off-the-end does.
-      const inner = either(...chain, s.default ? dflt.paths : falls(new Map()));
-      here = after(own, { through: most(inner.through, inner.brk), ret: inner.ret, brk: null, cont: inner.cont });
+      // CRITICAL took. `chain[i]` is that arm's paths. An arm that ends `goto L;` continues into
+      // the arm labelled L instead (`switchArmSuccessors`): the goto is its body's last top-level
+      // statement (`assertCaseGotosNarrow`), so the paths that fall off its end are the goto's,
+      // counted below as `through` (a `goto` ends nothing of its own). Memoised, since a goto may
+      // name an arm above it; a chain that comes back to an arm it already runs is no tree the
+      // structurer builds. The `default` is node `cases.length`.
+      const next = switchArmSuccessors(s);
+      const bodies = [...arms, dflt];
+      const chain: (PathCounts | undefined)[] = new Array(bodies.length);
+      const onChain = new Set<number>();
+      const chainAt = (i: number): PathCounts => {
+        const known = chain[i];
+        if (known !== undefined) {
+          return known;
+        }
+        if (onChain.has(i)) {
+          throw new ContractError('a switch whose arms fall or jump round in a cycle');
+        }
+        onChain.add(i);
+        const to = next[i];
+        const then = to === undefined ? undefined : chainAt(to);
+        onChain.delete(i);
+        return (chain[i] = then === undefined ? bodies[i].paths : seq(bodies[i].paths, then));
+      };
+      const dfltChain = chainAt(arms.length);
+      // No `default` is one more alternative: no arm runs. A `break` or a case-end `goto` leaves the
+      // switch, so it continues after it as a fall-off-the-end does.
+      const inner = either(...arms.map((_, i) => chainAt(i)), s.default ? dfltChain : falls(new Map()));
+      here = after(own, {
+        through: most(inner.through, inner.brk, inner.end),
+        ret: inner.ret,
+        brk: null,
+        cont: inner.cont,
+        end: null,
+      });
     } else if (stmtChildren(s).length > 0) {
       // A loop: its sequenced children (a body, a `for`'s init/inc) counted ONCE — a loop's dynamic
       // trip count is not a syntactic occurrence, and the IR side is static too. A `break` or
       // `continue` in the body lands after the loop or at its test, and the test may exit without
-      // running the body.
+      // running the body. A case-end `goto` leaves the loop for its switch's end.
       const body = countEffects(stmtChildren(s), ctx, unreached);
       total = sum(total, body.total);
       const p = body.paths;
-      here = after(own, { through: most(p.through, p.brk, p.cont, new Map()), ret: p.ret, brk: null, cont: null });
+      here = after(own, {
+        through: most(p.through, p.brk, p.cont, new Map()),
+        ret: p.ret,
+        brk: null,
+        cont: null,
+        end: p.end,
+      });
     } else if (s.k === 'return') {
-      here = { through: null, ret: own, brk: null, cont: null };
+      here = { through: null, ret: own, brk: null, cont: null, end: null };
     } else if (s.k === 'break') {
-      here = { through: null, ret: null, brk: own, cont: null };
+      here = { through: null, ret: null, brk: own, cont: null, end: null };
     } else if (s.k === 'continue') {
-      here = { through: null, ret: null, brk: null, cont: own };
+      here = { through: null, ret: null, brk: null, cont: own, end: null };
+    } else if (s.k === 'caseEndGoto') {
+      here = { through: null, ret: null, brk: null, cont: null, end: own };
     } else {
       here = falls(own);
     }
@@ -369,12 +428,24 @@ function countEffects(
   return { total, paths };
 }
 
+/** Every `goto` keeps one of the two forms L3 allows it (l3/ast.ts `caseGotoViolation`): the last
+ *  statement of a switch arm's own body naming a case label of that switch, or a case-end goto
+ *  naming a labelled `break;` that ends the arm it sits in. The effect count below reads a goto
+ *  that way, so a tree outside it is refused before it is counted. */
+export function assertCaseGotosNarrow(sfn: SFn): void {
+  const why = caseGotoViolation(sfn.body);
+  if (why !== null) {
+    throw new ContractError(`'${sfn.name}': ${why}`);
+  }
+}
+
 /**
  * Post structuring: every call and pinned access the asm makes is emitted, and none of those or of
  * its declared volatile reads is emitted more times than the asm makes it on any one path. See the
  * note above for what this deliberately does not cover.
  */
 export function assertEffectsPreserved(fn: Fn, sfn: SFn): void {
+  assertCaseGotosNarrow(sfn);
   // Reachable blocks only: an unreachable block's call is legitimately never emitted.
   const seen = reachableBlocks(fn);
   const irCalls: EffectCounts = new Map();
@@ -499,6 +570,12 @@ export function assertEffectsPreserved(fn: Fn, sfn: SFn): void {
     declared: new Set([...irDeclared.keys()].map((k) => k.slice(DECLARED.length))),
     written: declaredWritten,
     typeOf: (e) => exprCType(e, vt),
+    addresses: new Set([
+      ...(sfn.globals ?? []).map((g) => g.name),
+      ...[...(sfn.statics ?? []), ...(sfn.images ?? [])]
+        .filter((st) => st.type.kind === 'array' || st.type.kind === 'struct')
+        .map((st) => st.name),
+    ]),
   };
   const { total, paths } = countEffects(sfn.body, ctx, unreached);
   if (unreached.length) {
@@ -753,10 +830,17 @@ export function assertLocalsWritten(sfn: SFn): void {
     }
     exprChildren(e).forEach(walkExpr);
   };
+  // A store to a member of a local struct (`ret.a = v`) writes that local.
+  const memberOf = (e: Expr): string | undefined =>
+    e.k === 'field' && e.dot === true ? (e.base.k === 'var' ? e.base.name : memberOf(e.base)) : undefined;
   const walkStmt = (st: Stmt): void => {
     if (st.k === 'assign' && suspect.has(st.name)) {
       written.add(st.name);
     }
+    const member = st.k === 'store' ? memberOf(st.lval) : undefined;
+    if (member !== undefined && suspect.has(member)) {
+      written.add(member);
+    }
     stmtExprs(st).forEach(walkExpr);
     stmtChildren(st).forEach(walkStmt);
   };
@@ -858,6 +942,131 @@ export function assertNoOrphanedLocals(before: SFn, after: SFn): void {
   }
 }
 
+/** The types a tree reads or writes LOCAL STORAGE at, other than an integer — the frame bytes
+ *  reached by address (l3/storage.ts `localAddresses`), each access typed as it is spelled
+ *  (`exprCType`: the cast on the storage, or the element struct's field). An aggregate is the
+ *  element a `.field` selects from, not an access, so only scalars count. */
+function localStorageNonIntegers(sfn: SFn): Set<string> {
+  const { isAddress, accessAddress } = localAddresses(sfn);
+  const vt = declaredTypes(sfn);
+  const out = new Set<string>();
+  for (const e of walkExprs(sfn.body)) {
+    if ((e.k === 'index' || e.k === 'field') && isAddress(accessAddress(e))) {
+      const t = exprCType(e, vt);
+      if (t !== undefined && t.kind !== 'int' && t.kind !== 'struct' && t.kind !== 'array') {
+        out.add(typeToString(t));
+      }
+    }
+  }
+  return out;
+}
+
+/** After a respell variation: no access to LOCAL STORAGE is re-typed to a non-integer.
+ *
+ *  The frame audit's licence for a runtime index wider than a byte (frontend/frame-objects.ts
+ *  `indexedWidth`) rests on what L3 SPELLS: agbcc at -O2 keeps a read ordered after a store to the
+ *  same bytes only while both are integers of one width, and gives a pointer (or `long`, or a
+ *  float) an alias set of its own, so a variation that re-types the bytes' reads hands the
+ *  compiler a stale read the asm never had — C that compiles, scores, and is wrong. `/ptr-field`'s
+ *  `over-local-storage` gate is the refusal that names itself; this is the backstop for the next
+ *  variation that re-types, failing at its own stage rather than three away.
+ *
+ *  A DIFFERENTIAL, like `assertNoOrphanedLocals`: it judges only a non-integer type the tree it
+ *  derives from did not already read the storage at. The default tree is the frame audit's
+ *  answer, and a type it gives a local object (a header-typed out-parameter's pointer member, say)
+ *  is the source's own spelling, not a variation's claim. */
+export function assertLocalStorageStaysInteger(before: SFn, after: SFn): void {
+  const had = localStorageNonIntegers(before);
+  const added = [...localStorageNonIntegers(after)].filter((t) => !had.has(t));
+  if (added.length) {
+    throw new ContractError(
+      `a respell variation re-typed an access to local storage in '${after.name}' as ${added
+        .sort()
+        .map((t) => `'${t}'`)
+        .join(', ')} — not an integer, so agbcc may read it stale past an integer store to the same bytes`,
+    );
+  }
+}
+
+/** A FRAME UNION IS READ AND WRITTEN ONLY THROUGH ITS VIEWS. The frame audit declares storage
+ *  accessed at two widths over one byte as a union of per-width views (frontend/frame-objects.ts
+ *  `unionViews`, structure.ts `laddrType`), because agbcc gives an access through a union member
+ *  alias set 0 and reorders nothing past it — where a cast on the same bytes is read stale past a
+ *  store of the other width. That licence holds only while EVERY access is a member access:
+ *    - the union's name appears only as the base of a view (`u.half`), and an element of an array
+ *      view is subscripted, element 0 included — `*u.half` dereferences the view's decay, an
+ *      INDIRECT_REF agbcc types by its pointee and reads stale exactly as the cast (compiled);
+ *    - nothing is accessed through its ADDRESS: `&u`, under casts and `+`/`-`, or a local ever
+ *      assigned such a value, as the base of a subscript, an arrow or a deref is the cast
+ *      spelling again. The address itself may go anywhere a value goes — a call's argument, a
+ *      device's source register — since handing it on accesses nothing.
+ *  ABSOLUTE, not a differential: the default tree satisfies it by construction, so any tree that
+ *  does not was made by a variation. Checked on the default tree (pipeline.ts) and on every
+ *  respelled one (rank.ts, beside `assertLocalStorageStaysInteger`). */
+export function assertFrameUnionsViewed(sfn: SFn): void {
+  const unions = new Map(sfn.locals.filter((l) => l.type.kind === 'union').map((l) => [l.name, l.type]));
+  if (unions.size === 0) {
+    return;
+  }
+  const bad = (why: string): never => {
+    throw new ContractError(`'${sfn.name}' ${why} — agbcc may read the frame union stale through it`);
+  };
+  const reaches = (e: Expr, held: ReadonlySet<string>): boolean => {
+    switch (e.k) {
+      case 'addr':
+        return unions.has(e.name);
+      case 'var':
+        return held.has(e.name);
+      case 'cast':
+        return reaches(e.e, held);
+      case 'bin':
+        return (e.op === '+' || e.op === '-') && (reaches(e.l, held) || reaches(e.r, held));
+      default:
+        return false;
+    }
+  };
+  const held = taintOverAssigns(assignsIn(sfn.body), [], (a, t) => reaches(a.value, t));
+  const isView = (e: Expr): boolean =>
+    e.k === 'field' && e.dot === true && e.base.k === 'var' && unions.has(e.base.name);
+  const visit = (e: Expr): void => {
+    if (e.k === 'field' && isView(e)) {
+      if (memberOf(unions.get((e.base as { name: string }).name), e.name) === undefined) {
+        bad(`names '${e.name}', which is no view of the frame union`);
+      }
+      return;
+    }
+    if (e.k === 'index' && isView(e.base)) {
+      if (e.idx.k === 'const' && e.idx.value === 0 && e.subscript !== true) {
+        bad('dereferences a view of a frame union (`*u.view`) instead of subscripting it');
+      }
+      visit(e.base);
+      visit(e.idx);
+      return;
+    }
+    if ((e.k === 'index' || (e.k === 'field' && e.dot !== true)) && reaches(e.base, held)) {
+      bad('accesses a frame union through a pointer to its bytes');
+    }
+    if (e.k === 'var' && unions.has(e.name)) {
+      bad(`uses the frame union '${e.name}' other than through a view`);
+    }
+    exprChildren(e).forEach(visit);
+  };
+  const walk = (list: readonly Stmt[]): void => {
+    for (const st of list) {
+      if (st.k === 'assign' && unions.has(st.name)) {
+        bad(`assigns the frame union '${st.name}' whole`);
+      }
+      stmtExprs(st).forEach(visit);
+      // a `for`'s init and inc are statements of their own, outside both lists
+      stmtLists(st).forEach(walk);
+      if (st.k === 'for') {
+        walk([st.init, st.inc]);
+      }
+    }
+  };
+  walk(sfn.body);
+}
+
 /** After a respell variation: every read of a MINTED local — its ADDRESS being taken included — must sit where
  *  that local's assignment has already run.
  *
@@ -1013,8 +1222,9 @@ export function assertDerefsTyped(sfn: SFn): void {
     if (e.k === 'index' && !structElem.has(e) && !SCALAR_WIDTHS.has(e.width)) {
       bad.push(`index width ${e.width} is not a C scalar width`);
     }
-    // The emitter legalizes pointer operands away from these ops (structure.ts intify); a
-    // pointer surviving here is ill-typed C the compiler will reject.
+    // The emitter legalizes pointer operands away from these ops (structure/pointer-spelling.ts
+    // `ARITH_ROWS`, its `bitwise` row); a pointer surviving here is ill-typed C the compiler will
+    // reject.
     if (e.k === 'bin' && NO_PTR_OPS.has(e.op)) {
       for (const side of [e.l, e.r]) {
         if (ctype(side)?.kind === 'ptr') {
@@ -1026,9 +1236,9 @@ export function assertDerefsTyped(sfn: SFn): void {
     // offset by sizeof(SYM), which is unknown for a header-typed global, so `&SYM + N` is byte-
     // inexact. Nothing emits this shape anymore: a load/store base folds byte-correctly (globalOf
     // turns `&SYM + N` into an `index`/`field` node whose base is a bare `addr`), and the additive
-    // lowering intifies every other `addr` operand to `(u32)&SYM` (structure.ts intifyAddr — the
-    // cast types int, so it never lands here). A bare `addr` reaching a `+`/`-` operand is therefore
-    // a lowering REGRESSION — flag it rather than emit wrong bytes.
+    // lowering intifies every other `addr` operand to `(u32)&SYM` (structure/pointer-spelling.ts
+    // ARITH_ROWS — the cast types int, so it never lands here). A bare `addr` reaching a `+`/`-`
+    // operand is therefore a lowering REGRESSION — flag it rather than emit wrong bytes.
     if (e.k === 'bin' && (e.op === '+' || e.op === '-')) {
       const addrSide = e.l.k === 'addr' ? e.l : e.r.k === 'addr' ? e.r : undefined;
       if (addrSide) {

package/src/declare.ts

@@ -185,7 +185,36 @@ export function renderDeclarations(refs: SymbolRef[]): string {
   const lines: string[] = [];
   const declaredTags = new Set<string>();
   const declaredTypedefs = new Set<string>();
-  for (const { name, info, access, proto, returned, holdsPointer } of refs) {
+  const defineStruct = (s: { readonly name: string; readonly declared: string; readonly layout: AggregateLayout }) => {
+    if (!declaredTags.has(s.name)) {
+      declaredTags.add(s.name);
+      lines.push(declaredStructDecl(s.name, s.layout));
+    }
+    if (!/^(?:struct|union)\s/.test(s.declared) && !declaredTypedefs.has(s.declared)) {
+      declaredTypedefs.add(s.declared);
+      lines.push(`typedef struct ${s.name} ${s.declared};`);
+    }
+  };
+  for (const {
+    name,
+    info,
+    access,
+    proto,
+    returned,
+    passed,
+    passedAs,
+    holdsPointer,
+    implicitCall,
+    definesReturn,
+  } of refs) {
+    // THE FUNCTION'S OWN STRUCT RETURN, defined as a callee's is; the function itself is declared
+    // by its definition
+    if (definesReturn) {
+      if (returned !== undefined) {
+        defineStruct(returned);
+      }
+      continue;
+    }
     // An address-cast macro declares itself: the header's own body, verbatim. It must NOT become
     // an `extern` — that is the whole point of the fact (an extern emits a relocated pool word
     // where the macro emits the numeric one the target shows).
@@ -193,6 +222,14 @@ export function renderDeclarations(refs: SymbolRef[]): string {
       lines.push(`#define ${name} ${info.macroBody}`);
       continue;
     }
+    // A GLOBAL REGISTER VARIABLE declares itself in its register (SymbolInfo.globalRegister), typed
+    // as a name-only global is: a pointer where the body stores or meets one, else the word the
+    // body accesses.
+    if (info.globalRegister !== undefined) {
+      const t = holdsPointer ? 'void *' : `${intType(access?.width ?? 4, access?.signed ?? true) ?? 's32'} `;
+      lines.push(`register ${t}${name} __asm__("${info.globalRegister}");`);
+      continue;
+    }
     // A CALL TARGET the project declared completely — its own prototype, re-spelled from the
     // parameter and return type texts the project wrote. This is the one declaration here that
     // is load-bearing for the CALL and not only for the name: an implicit declaration is `int`,
@@ -203,23 +240,24 @@ export function renderDeclarations(refs: SymbolRef[]): string {
       // A STRUCT IT RETURNS THROUGH MEMORY is the headers' type, spelled as they spell it, so it is
       // defined here with the rest of what they own: by its tag, once, whoever else declares that
       // tag — and a typedef name is bound to it on top.
-      if (returned?.declared !== undefined) {
-        if (!declaredTags.has(returned.name)) {
-          declaredTags.add(returned.name);
-          lines.push(declaredStructDecl(returned.name, returned.layout));
-        }
-        if (!/^(?:struct|union)\s/.test(returned.declared) && !declaredTypedefs.has(returned.declared)) {
-          declaredTypedefs.add(returned.declared);
-          lines.push(`typedef struct ${returned.name} ${returned.declared};`);
-        }
+      // …and so is a struct it is passed by value, the same way.
+      for (const s of [...(returned?.declared !== undefined ? [returned] : []), ...(passed ?? [])]) {
+        defineStruct(s);
       }
       lines.push(`${proto.returns} ${name}(${proto.params.length > 0 ? proto.params.join(', ') : 'void'});`);
       continue;
     }
+    // A CALL TARGET no prototype spells, named ahead of its first call by an initializer — C's
+    // implicit declaration, `int F();`, written where the initializer can see it. No parameter
+    // list, so the call binds to it exactly as it bound to the implicit one (see collectSymbolRefs).
+    if (implicitCall) {
+      lines.push(`int ${name}();`);
+      continue;
+    }
     if (info.kind === 'code') {
       // value-referenced code symbol ((u32)Func): any prototype makes the name visible, and
-      // the address is arity-independent. A call target reaches this module only with a complete
-      // prototype, which the branch above already printed — see collectSymbolRefs.
+      // the address is arity-independent. A call target reaches here only with a complete
+      // prototype or as an initializer's implicit call, which the branches above printed.
       lines.push(`void ${name}(void);`);
       continue;
     }
@@ -317,6 +355,12 @@ export function renderDeclarations(refs: SymbolRef[]): string {
           lines.push(`extern void *${info.volatile ? 'volatile ' : ''}${info.const ? 'const ' : ''}${name};`);
           break;
         }
+        // A global passed bare as a struct by value is that struct, which its callee's prototype
+        // defines (`passed`); a declaration of an incomplete tag is completed by that definition.
+        if (passedAs !== undefined) {
+          lines.push(`extern ${quals(info)}${passedAs} ${name};`);
+          break;
+        }
         const t = access ? intType(access.width, access.signed) : null;
         lines.push(`extern ${quals(info)}${t ?? 'u32'} ${name};`);
         break;
@@ -326,18 +370,23 @@ export function renderDeclarations(refs: SymbolRef[]): string {
   return lines.length ? lines.join('\n') + '\n' : '';
 }
 
-/** The object-like `#define`s out of a rendered declaration block.
+/** THE LINES OF A RENDERED DECLARATION BLOCK THAT THE HEADERS WORLD KEEPS: its object-like
+ *  `#define`s and its global register variables. Everything else there is owned by the injected
+ *  headers (a duplicate typedef or struct definition is a C89 hard error), and these two are not:
+ *
+ *  - an address-cast macro, because a duplicate `#define` with an identical body is legal — and a
+ *    PREPROCESSED project context has no macros left at all, so dropping these turns a macro-named
+ *    candidate into an `undeclared identifier` rather than a spelling choice;
+ *  - a global register variable (`register T greg_r8 __asm__("r8");`, SymbolInfo.globalRegister),
+ *    because no header declares the name the lift made up for it.
  *
- *  Address-cast macro defines are the one part of a synthesized block that must survive into the
- *  HEADERS world too. Everything else there is owned by the injected headers (a duplicate typedef
- *  or struct definition is a C89 hard error), but a duplicate `#define` with an identical body is
- *  legal — and a PREPROCESSED project context has no macros left at all, so dropping these turns a
- *  macro-named candidate into an `undeclared identifier` rather than a spelling choice. */
-export function macroDefinesOf(declarations: string | undefined): string {
+ *  Chosen by each line's leading keyword, which `renderDeclarations` prints for these two kinds
+ *  only: a new kind of line it prints with either keyword rides into the headers world too. */
+export function declarationsKeptWithHeaders(declarations: string | undefined): string {
   if (!declarations) {
     return '';
   }
-  const lines = declarations.split('\n').filter((l) => l.startsWith('#define '));
+  const lines = declarations.split('\n').filter((l) => l.startsWith('#define ') || l.startsWith('register '));
   return lines.length ? lines.join('\n') + '\n' : '';
 }