@asmlift/core 0.5.0 → 0.7.0

package/src/l3/sinkinit.ts

@@ -0,0 +1,40 @@
+// L3 respell variation: sink each leading pointer-base INIT to the statement that first uses it.
+//
+// `l3/basecse.ts`'s COMMITTED call emits every base hoist at the head of `sfn.body`, so a base
+// first touched halfway down the function is live across everything above it — a live range the
+// original never had, and agbcc pays for it with a callee-saved register. (Its roster's hoists
+// ask for this placement directly, through the same `l3/hoist.ts` mechanism this variation uses; what
+// the variation adds is reaching the run on a tree the roster did not build — one NOTHING re-hoisted,
+// or one `l3/nearbase.ts` prepended into, which is the `/nearbase/sinkinit` pairing.)
+// Compiled pair on `synthetic:basehome`:
+// assigning at the top adds `push {r4, lr}` / `pop {r4}` / `pop {r0}` / `bx r0` where assigning at
+// the first use keeps a plain `bx lr`. The ladder that row records is the argument for the variation
+// being a PLACEMENT rather than a wider hoist — top-placed 11, not hoisted at all 9, placed at
+// first use 0. A hoist at the wrong place is worse than no hoist.
+//
+// A VARIATION, NOT THE DEFAULT. Which placement the source used is per-function knowledge the asm does
+// not carry: moving basecse's own head placement to first use moves 8 benchmark rows, 4 better and
+// 4 worse, two of the losses being matches. The UNSUNK spelling always rides beside this one —
+// head-placed wherever basecse built the run, prepend-placed under `/nearbase` — and the differ
+// referees, so ADDING this candidate can never cost a match. Withholding one is a different
+// question and not a free one (l3/basecse.ts's fold-evidence note).
+//
+// SCOPE (decline over approximate). Only the LEADING run of base inits moves — the run basecse.ts
+// and nearbase.ts mint into, placed by the same `l3/hoist.ts` mechanism, so no two of the three can
+// disagree about where the run ends or how a body carrying it is rebuilt. Each init sinks to
+// immediately before the first TOP-LEVEL statement mentioning its name and never INTO a nested
+// scope, so it still dominates every use — planning a hoist inside a scope is `l3/scopebase.ts`'s
+// job and it does the domination work. `placeBaseLocals` carries the refusals; a run where none of
+// them moves is this variation declining.
+//
+// SEMANTICS BY CONSTRUCTION: the moved value is a pure address leaf — it reads nothing, writes its
+// own plain cell and cannot fault — and every statement it crosses mentions the name nowhere, an
+// `&p` escape included (mentions.ts counts `addr` as a mention). All later evaluation can change
+// is where the allocator puts it.
+import type { SFn } from './ast';
+import { placeBaseLocals } from './hoist';
+
+export function sinkInitsToFirstUse(sfn: SFn): SFn | null {
+  const { body, moved } = placeBaseLocals(sfn, [], 'first-use');
+  return moved.length === 0 ? null : { ...sfn, body };
+}

package/src/l3/slotorder.ts

@@ -0,0 +1,123 @@
+// asmlift — declare slot-homed locals in the TARGET'S OWN FRAME ORDER.
+//
+// THE LAW. gcc 2.9 hands a spilled user local its frame slot by DECLARATION RANK: reload walks
+// pseudos in ascending number handing each global-allocation loser a fresh stack slot, a user
+// local's pseudo number is fixed at its `expand_decl` — i.e. its position in the declaration list
+// — and the Thumb frame grows upward. So under agbcc the earlier-declared spilled local takes the
+// LOWER `[sp,#k]`, and a source whose two spilled locals are declared the other way round compiles
+// to the same object with those two operands swapped and nothing else moved.
+//
+// A COMPILER BEHAVIOR, NOT A RANKED VARIATION. The asm does not underdetermine the answer: a
+// `[sp,#k]` operand NAMES the slot, and slot → declaration rank is a FUNCTION once the compiler is
+// fixed. A variation exists where two source spellings collapse to the same object and only the differ
+// can choose between them; here the object chooses. The fan cost is zero — this rewrites the one
+// tree every candidate already carries, adding no candidate, no `structure()` call and no compile.
+//
+// WHY `emit` OWNS IT. Two reasons, and they point the same way. It must run AFTER every L3 respell variation,
+// because each of those rebuilds the declaration list (appends: basecse, scopebase, argbase,
+// nearbase, regspell, reindex; filters: unmerge, coalesce, dce, inlinebase, pollguard, unreduce),
+// and `emit` is last by construction. And it must NOT run at a `.emit(` call site: there are seven
+// of those, the web Playground reaches two of them for one function (the headline source and the
+// Pipeline tab), and the score probe reaches a third — a call-site ordering would print an ordered
+// headline beside an unordered pipeline dump and measure the probe's scoreDelta on a source the
+// ranked path never compiles.
+//
+// WHAT DEPENDS ON THE ORDER THIS DOES NOT CHANGE. `l3/coalesce.ts` picks the arm-disjoint survivor
+// by `declIdx` — the earlier declaration, matching how a shared source local reads. It runs before
+// this and therefore reads the UNSORTED list, which is exactly right and is what the emit-time
+// placement preserves. Sorting any earlier would silently change which local survives every
+// arm-disjoint merge.
+import type { SFn } from './ast';
+
+/** Refill the positions held by slot-carrying locals with those same locals in frame order.
+ *
+ *  PURE: the structurer's own list is never mutated, so `emit` cannot leak an ordered list back to
+ *  a caller that expects the structurer's order.
+ *
+ *  REFUSAL CONDITIONS, all of them — 1, 2 and 6 are checked below; 3, 4 and 5 hold by construction
+ *  (see each):
+ *   1. `fn.slotOrder` absent — the target's direction is unknown, or it ships `'unknown'`: the
+ *      ordering is the IDENTITY. There is no default direction.
+ *   2. Fewer than two sortable locals: nothing to order.
+ *   3. A local with no `slots`, or an empty list, keeps its position exactly. Only the positions
+ *      the sortable locals already occupy are refilled, so an unslotted local never moves and no
+ *      local is ever inserted or removed.
+ *   4. `frame` and `uninit` locals are never sortable, because the structurer never stamps
+ *      `slots` on them — the refusal, and the measurement behind it, live at that stamp site.
+ *   5. Parameters are never touched: their storage is the caller's question.
+ *   6. TWO DECLARED LOCALS SHARING ONE OFFSET REFUSE THE WHOLE FUNCTION. Reload hands each
+ *      spilled pseudo a FRESH slot (`reload1.c:769-770`, the premise this file's law rests on),
+ *      so a frame in which the slot -> local map is not injective is not a frame this law
+ *      describes at all: something upstream — a decomposed stack aggregate, a coalesce, a naming
+ *      walk that put two spilled values under two names at one address — produced the evidence,
+ *      and none of those is a declaration rank. It is NOT enough to leave that PAIR alone: the
+ *      shared offset is still used to rank both of them against every other sortable local, so
+ *      the whole ordering is unlicensed and the identity is the only sound answer.
+ *
+ *      MEASURED, both sides. It costs nothing: `spillorder` (v6@4 v12@0), `uninit_spill` (v4@0
+ *      v5@4 v6@8), `dma_fill_uninit` (v2@16 v4@4 v6@8 v8@12) and the `agbcc-u8spill.s` fixture
+ *      (v0@4 v10@8 v11@12) are all injective, so every shipped inhabitant keeps its ordering. And
+ *      it is what the wild corpus asks for: of 2,463 real agbcc functions (158 sa3 + klonoa
+ *      listings) exactly ONE carries two slot-carrying locals at all, and it is non-injective —
+ *      `sa3 enemies/hariisen_proj.s` `sub_80617E0`, `v8@12 v12@8 v13@12`, which without this
+ *      refusal emitted `… v7 v12 v9 v10 v11 v8 v13 …` against the declaration order `… v7 v8 v9
+ *      v10 v11 v12 v13 …`. Its slots are four words of one declared stack array (see the stamp
+ *      site's aggregate note), which is exactly the class that mints a duplicate. So the one real
+ *      function this default reached was one whose evidence contradicts its own premise, and the
+ *      wild reach is zero functions changed rather than one changed wrongly.
+ *
+ *      A consequence, so nothing downstream relies on the sort's stability: two sortable locals
+ *      can no longer TIE. Equal ranks means an equal minimum offset under `ascending` and an
+ *      equal maximum under `descending`, and either is a shared offset, which this refuses first.
+ *
+ *  AND THIS IS THE ONE PLACE A SET OF HOMES IS REDUCED TO A RANK. A local can carry several
+ *  offsets, and every site that merged them took the union and chose nothing, because the choice
+ *  is direction-dependent and none of them holds a target (ir/core.ts `SlotHomes`). The earliest
+ *  declaration rank is the LOWEST offset under an ascending frame and the HIGHEST under a
+ *  descending one: one comparator, applied where `slotOrder` is in hand.
+ *
+ *  The `descending` half of that comparator has NO SHIPPED INHABITANT: agbcc is the only target
+ *  that ships a direction and it is `ascending`. It is reached only through the public
+ *  `StructureOptions.spillSlotOrder` and by the tests, and it exists because ido7.1's
+ *  `TargetDescription` carries a MEASURED `descending` with a written flip condition (target.ts).
+ *
+ *  REACH. The two inhabitants are `spillorder` (6 → MATCH) and `dma_fill_uninit` (12 → MATCH, a
+ *  row this capability did not author). On the REAL agbcc tier it is ZERO, and the cause is named
+ *  rather than assumed: of 126 cases, four carry any L1 slot home, two carry a slot-carrying local
+ *  at L3, and NONE carries two. So the blocker is neither the frame order nor the census — the
+ *  structurer's naming walk INLINES spilled values instead of declaring them (`PackSaveSector`
+ *  spills to 18 distinct slots, 108 stamped values, and reaches L3 with zero slot-carrying
+ *  locals), which is also why counting stores is a bad proxy for reach.  */
+export function orderSlotLocals(fn: SFn): SFn {
+  const dir = fn.slotOrder;
+  if (dir === undefined) {
+    return fn;
+  }
+  // the earliest declaration rank among a local's homes
+  const rank = (l: SFn['locals'][number]): number =>
+    dir === 'ascending' ? Math.min(...l.slots!) : Math.max(...l.slots!);
+  const at: number[] = [];
+  fn.locals.forEach((l, i) => {
+    if (l.slots !== undefined && l.slots.length > 0) {
+      at.push(i);
+    }
+  });
+  if (at.length < 2) {
+    return fn;
+  }
+  // refusal 6: the slot -> local map must be INJECTIVE, or this frame is not one the law
+  // describes and no local in it can be ranked. Over every offset of every sortable local, not
+  // just their ranks: a duplicate anywhere means some slot was not a fresh reload assignment.
+  const offsets = at.flatMap((i) => fn.locals[i].slots!);
+  if (new Set(offsets).size !== offsets.length) {
+    return fn;
+  }
+  const inFrameOrder = at
+    .map((i) => fn.locals[i])
+    .sort((a, b) => (dir === 'ascending' ? rank(a) - rank(b) : rank(b) - rank(a)));
+  const locals = [...fn.locals];
+  at.forEach((i, k) => {
+    locals[i] = inFrameOrder[k];
+  });
+  return { ...fn, locals };
+}

package/src/l3/storage.ts

@@ -0,0 +1,48 @@
+// Which STORAGE CLASS an L3 name denotes.
+//
+// `assign` names its target with a bare string, and structure.ts spells a store to a local, to a
+// param and to a bare scalar global identically — so every pass that must tell them apart has to
+// re-derive the distinction from `SFn`'s three declaration lists. Four did, privately, and the one
+// that got it wrong (l3/reindex.ts) read a plausible type off a global and re-spelled away a write
+// another translation unit observes.
+//
+// SHADOWING is what the copies disagreed on, and the disagreement is REAL rather than drift: a
+// name can be declared both a global and a local, because `SFn.globals` records what the code
+// REFERENCES (structure.ts `noteGlobal`) independently of what it declares. Which answer is right
+// depends on how the asking pass will SPELL the name, so the two questions are two functions
+// here instead of one set each caller filters its own way:
+//   • it keeps the reference verbatim (`(u8 *)g`) — the shadow is harmless, the spelling denotes
+//     whatever the original access denoted: `declaredGlobals`;
+//   • it re-spells the reference as an ADDRESS (`&g`) — a shadow then names the LOCAL's storage,
+//     silently a different object: `addressableGlobals`;
+//   • it asks which of the three classes a bare `assign` name denotes at all: `nameStorage`, the
+//     primitive the other two are the shadow-sensitive projections over.
+import type { SFn } from './ast';
+
+export type Storage = 'local' | 'param' | 'global';
+
+/** Every declared name, classified. A local or a param SHADOWS a same-named global — that is what
+ *  the name binds to. A name absent from the map is declared nowhere. */
+export function nameStorage(sfn: SFn): Map<string, Storage> {
+  const t = new Map<string, Storage>();
+  for (const g of sfn.globals ?? []) {
+    t.set(g.name, 'global');
+  }
+  for (const p of sfn.params) {
+    t.set(p.name, 'param');
+  }
+  for (const l of sfn.locals) {
+    t.set(l.name, 'local');
+  }
+  return t;
+}
+
+/** Names declared as globals, INCLUDING one a local or param shadows (see the header). */
+export function declaredGlobals(sfn: SFn): Set<string> {
+  return new Set((sfn.globals ?? []).map((g) => g.name));
+}
+
+/** Names whose ADDRESS is the global's — a shadowed one excluded (see the header). */
+export function addressableGlobals(sfn: SFn): Set<string> {
+  return new Set([...nameStorage(sfn)].filter(([, s]) => s === 'global').map(([n]) => n));
+}

package/src/l3/symbol-refs.ts

@@ -1,9 +1,15 @@
 // asmlift — SELF-DECLARING CANDIDATES: the pure map-reference query
 // (research/self-declaring-candidates-2026-07-26.md).
 //
-// `collectSymbolRefs` derives, from a FINAL structured tree, every map-derived symbol the body
+// `collectSymbolRefs` derives, from a FINAL structured tree, every DECLARABLE symbol the body
 // references in a VALUE context — the input to the scoring layer's declaration synthesis
-// (@asmlift/cli declare.ts). It is a pure tree query with no pipeline state: the enumeration
+// (core declare.ts). "Declarable" and not "map-derived": the dictionary this is called with is
+// the caller's, and rank.ts hands it a symbol map UNIONED with the names read straight out of
+// the asm's own literal pool / relocations (`bareGlobalSymbols`), so a candidate compiled
+// outside project headers declares what it spells even with no map at all. The map's facts win
+// per NAME where it has them; the rest come back marked `synthesized`.
+//
+// It is a pure tree query with no pipeline state: the enumeration
 // layer (rank.ts) calls it exactly once per candidate, on the tree the candidate's source was
 // emitted from, at the moment the candidate is finalized. There is deliberately NO cached
 // `symbolRefs` field on `SFn` — a carried field would oblige every future l3 pass to remember
@@ -13,7 +19,7 @@
 import type { SymbolInfo } from '../symbols';
 import { Expr, Stmt, exprChildren, stmtChildren, stmtExprs } from './ast';
 
-/** One recorded map-symbol VALUE reference — a name the tree references plus its map facts. */
+/** One recorded VALUE reference — a name the tree references plus the facts to declare it. */
 export interface SymbolRef {
   name: string;
   info: SymbolInfo;
@@ -21,19 +27,36 @@ 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. */
+  synthesized?: true;
 }
 
-/** The map-derived symbols a structured body references in a VALUE context — the input to the
+/** 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 map knows it (bare `gSym`, `&gSym`, `(u32)Func`, a `field` base — all reduce to
+ *  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
  *  synthesized `void F(void);` above `s32 F(...)` is a conflicting-types hard error (a
- *  self-address reference resolves against the definition itself). */
-export function collectSymbolRefs(body: Stmt[], symbols: Map<string, SymbolInfo>, selfName: string): SymbolRef[] {
+ *  self-address reference resolves against the definition itself).
+ *
+ *  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[],
+  symbols: Map<string, SymbolInfo>,
+  selfName: string,
+  onRefused?: (name: string, reason: 'call-target' | 'self-name') => void,
+): SymbolRef[] {
   const called = new Set<string>();
   const valueRefs = new Set<string>();
   const visitExpr = (e: Expr): void => {
@@ -55,7 +78,17 @@ export function collectSymbolRefs(body: Stmt[], symbols: Map<string, SymbolInfo>
   };
   body.forEach(visitStmt);
   return [...valueRefs]
-    .filter((n) => !called.has(n) && n !== selfName)
     .sort()
+    .filter((n) => {
+      if (called.has(n)) {
+        onRefused?.(n, 'call-target');
+        return false;
+      }
+      if (n === selfName) {
+        onRefused?.(n, 'self-name');
+        return false;
+      }
+      return true;
+    })
     .map((n) => ({ name: n, info: symbols.get(n)! }));
 }

package/src/l3/tailmerge.ts

@@ -25,7 +25,7 @@
 // above covers only below-vs-in-arms.
 //
 // KNOWN INTERACTIONS, both byte-level rather than soundness. This pass is unconditional like
-// `dce.ts` and `basecse.ts` rather than a differ-refereed lever, and the argument those files each
+// `dce.ts` and `basecse.ts` rather than a differ-refereed variation, and the argument those files each
 // state for themselves applies here too and was missing: a wrong merge changes recompiled bytes and
 // surfaces as a LOST match under the zero-lost gate, never as wrong C.
 //
@@ -37,6 +37,21 @@
 //     of the arms hides the common tail, and DCE only removes it afterwards, so the shape this pass
 //     exists for is missed. The fix is a fixpoint of the pair, not one extra call — a lone second
 //     pass leaves an empty `if` behind.
+//   - THE SAME HIDING HAPPENS WITHOUT DCE, and the edge-copy sort decides when. An arm ends in the
+//     copies of one CFG edge, ordered by the predecessor's write record or by the def-position
+//     proxy (`structure.ts`); an arm-varying copy ordered LAST hides an agreeing one behind it.
+//     Measured on klonoa `CountCollectedGems` (map-less, agbcc): the record's order leaves six
+//     copies of `v22 = (s32 *)50345232;` where the proxy's order merges them into one, and with
+//     THIS PASS disabled both orders emit all six — so the duplication is this peel not firing,
+//     not something the sort creates. Reaching the hidden statement is not a matter of peeling
+//     further: it would have to move ACROSS the differing one, which needs the independence
+//     argument this pass deliberately does not have (see the soundness note above). Pinned both
+//     ways in `test/tailmerge.test.ts`.
+//     A ranked row is not stuck with either order: `/copy-defpos` (rank.ts) enumerates the
+//     def-position spelling beside the record's, so the merged form is a candidate the differ can
+//     pick on bytes — on `CountCollectedGems` its gate admits the variation on the map-ful and map-less
+//     lifts alike. What no arm of the fan spells is the third form, the hidden statement merged
+//     while KEEPING the record's order.
 //
 // SCOPE. Only `assign`/`store`/`exprstmt` merge, compared structurally through `exprEquals`.
 // Control flow (`break`/`continue`/`return`) is excluded: moving one out of an arm changes which

package/src/l3/typing.ts

@@ -18,10 +18,10 @@
 // provably a pointer" (adds a cast — valid C either way); the deref contract treats `undefined`
 // as "not provably wrong" (no error).
 import { IrType, T, scalarTypeForAccess } from '../ir/types';
-import type { Expr, SFn } from './ast';
+import { type Expr, type SFn, exprChildren } from './ast';
 
 /** The declared type of a printed variable — the env `exprCType` judges rendered C against.
- *  THE one copy of the SFn→env derivation (C printer, Pascal printer, deref contract): each
+ *  THE one copy of the SFn→env derivation — printers, contracts and L3 respell variations alike: each
  *  consumer judging against anything but the declarations it emits would let them disagree. */
 export type VarTypes = (name: string) => IrType | undefined;
 
@@ -48,22 +48,211 @@ export function ptrElemBytes(to: IrType): number {
   return to.kind === 'int' ? to.width / 8 : to.kind === 'ptr' ? 4 : 0;
 }
 
-/** May a `width`-byte access dereference a base of rendered C type `rt` AS SPELLED — i.e. is `rt`
- *  a pointer/array whose element size equals the access width? THE one copy of the stride rule:
+/** The env a C-family printer judges rendered C against: the declared types, plus which printed
+ *  vars render as a pointer to VOLATILE. IrType models no cv-qualifier (see the `cast` node doc in
+ *  l3/ast.ts), so a printer that RE-TYPES an access — the deref legalization — has to read the
+ *  qualifier from here or the re-typing silently drops it. */
+export interface PrintEnv {
+  readonly type: VarTypes;
+  readonly volatilePointee: (name: string) => boolean;
+}
+
+export function printEnv(fn: SFn): PrintEnv {
+  // both flags, because the C declarator prints ONE `volatile ` prefix for a pointer local and it
+  // binds to the pointee either way (the declaration loop in backend/cfamily.ts)
+  const vol = new Set(
+    fn.locals.filter((l) => l.type.kind === 'ptr' && (l.pointeeVolatile || l.volatile)).map((l) => l.name),
+  );
+  return { type: declaredTypes(fn), volatilePointee: (n) => vol.has(n) };
+}
+
+/** Does anything under `e` assert a VOLATILE POINTEE? The two spellings that carry the qualifier
+ *  into printed C are a `volatile` cast node and a volatile-pointee declaration. The whole subtree
+ *  is searched, not the pointer spine: a cast to an integer type between the assertion and the
+ *  access — `(u32)p + 4` — renders the qualifier no less dropped, and over-qualifying an access
+ *  only restricts the compiler further, where under-qualifying is a lie about MMIO. */
+export function assertsVolatile(e: Expr, env: PrintEnv): boolean {
+  return (
+    (e.k === 'cast' && e.volatile === true) ||
+    (e.k === 'var' && env.volatilePointee(e.name)) ||
+    exprChildren(e).some((c) => assertsVolatile(c, env))
+  );
+}
+
+/** May a `width`-byte access of the given signedness dereference a base of rendered C type `rt` AS
+ *  SPELLED — i.e. is `rt` a pointer/array whose element size equals the access width, and whose
+ *  element extends the way the access does? THE one copy of the stride rule:
  *  the C-family printer decides cast insertion from it, the Pascal backend decides declining from
  *  it, and exprCType types the access result from it. `false` for a non-pointer, an unknowable
  *  base (undefined), or a pointer of the WRONG stride — a wrong-stride deref would make C read
  *  the wrong width and scale the index by the wrong element size. */
-export function derefStrideOk(rt: IrType | undefined, width: number): boolean {
+export function derefStrideOk(rt: IrType | undefined, width: number, signed: boolean): boolean {
+  // SIGNEDNESS COUNTS WHEREVER THE ACCESS EXTENDS. A sub-word load fills the top bits from either
+  // the sign bit or zero, and in the emitted C the pointee type is the ONLY thing that says which —
+  // so a base of the wrong signedness has to take the reinterpret cast exactly as a base of the
+  // wrong stride does. Read `*(u8 *)p` where the machine did `ldrsb` and `p[9] < 0` is not merely a
+  // different value: an `unsigned char` promotes to a non-negative `int`, so the arm goes dead.
+  // A word access extends nothing, and a POINTER pointee is a word.
+  const extendsOk = (to: IrType) => width === 4 || (to.kind === 'int' && to.signed === signed);
   if (rt?.kind === 'ptr') {
-    return rt.to.kind !== 'struct' && ptrElemBytes(rt.to) === width;
+    return rt.to.kind !== 'struct' && ptrElemBytes(rt.to) === width && extendsOk(rt.to);
   }
   if (rt?.kind === 'array') {
-    return rt.elem.kind === 'int' && rt.elem.width === width * 8;
+    return rt.elem.kind === 'int' && rt.elem.width === width * 8 && extendsOk(rt.elem);
   }
   return false;
 }
 
+/** The USUAL ARITHMETIC CONVERSIONS over two rendered operands: at equal rank, unsigned wins.
+ *  Either side unknown leaves the result unknown — EXCEPT when the known side is unsigned, which
+ *  already decides it.
+ *
+ *  That exception is the one place this returns a DEFINITE answer from an unknown operand, and it
+ *  is sound only because every integer here is rank `int`: at UNEQUAL rank C converts to the wider
+ *  type first, so `unsigned int & long long` is SIGNED. Core has no 64-bit integer type at all
+ *  (the decomp typedef vocabulary stops at 32 — see contracts.ts SCALAR_WIDTHS), so the
+ *  unequal-rank case cannot arise. Adding one would invalidate this.
+ *
+ *  Exported because two consumers ask it about an operator whose own rendering they are deciding,
+ *  so they cannot ask `renderedIntSignedness` about the node: the C-family backend's operand pin,
+ *  and initfirst's compare-meaning gate over a substitution not yet made. */
+export function arithConversionSignedness(l: Expr, r: Expr, varType: VarTypes): boolean | undefined {
+  const ls = renderedIntSignedness(l, varType);
+  const rs = renderedIntSignedness(r, varType);
+  if (ls === false || rs === false) {
+    return false;
+  }
+  return ls === true && rs === true ? true : undefined;
+}
+
+/**
+ * The C SIGNEDNESS a rendered integer expression actually has — `true`/`false`, or `undefined`
+ * when it is not determinable here. The deliberate complement to `exprCType`, which is
+ * pointer-ness-accurate and reports every integer as `s32` by contract; this models the two C
+ * rules that contract omits, integer PROMOTION and the usual arithmetic CONVERSIONS.
+ *
+ * THE one rendered-signedness judgment, and it lives beside the declarations it judges against
+ * because every consumer shares it: the C-family backend's operand pin, structure.ts's
+ * unsigned-compare gate (the /uns-cmp variation) and its signed-compare pin, and — through
+ * `arithConversionSignedness` above — initfirst's compare-meaning gate. Two of those models
+ * disagreeing about one expression is the drift this placement prevents.
+ *
+ * The question is byte-load-bearing: C spells both `>>>` and `>>` as `>>` and chooses between them
+ * from the left operand's type, so a logical shift rendered over a signed expression recompiles to
+ * `asr` where the target has `lsr` and evaluates to a different value.
+ *
+ * `undefined` means the model did not reach, never "possibly signed": what a `call` renders as is
+ * decided by the prototype in scope, and the prototypes in scope are the PROJECT's — the scoring
+ * context prepends its headers, and those do declare unsigned-returning callees. So every consumer
+ * whose operator needs a definite signedness takes a cast on `undefined` exactly as on the wrong
+ * definite answer. A redundant cast is codegen-identical (`(s32)f() / a` and `f() / a` assemble
+ * instruction-for-instruction the same where `f` really returns `int`); a missing one is a
+ * miscompile — with `u32 f(void);` in scope `f() / a` calls `__udivsi3` where the machine called
+ * `__divsi3`, and `if (f() >= 0)` compiles to `bl f; mov r0, #0`, comparison and both arms gone.
+ * The one consumer that reads `undefined` the other way is the /uns-cmp variation's own gate, which is
+ * asking whether an operand is ALREADY unsigned.
+ *
+ * Anything narrower than 32 bits promotes to `int` and is therefore SIGNED, whatever it was
+ * declared. Pointers, calls and markers are `undefined`.
+ */
+export function renderedIntSignedness(e: Expr, varType: VarTypes): boolean | undefined {
+  const rec = (x: Expr): boolean | undefined => renderedIntSignedness(x, varType);
+  // an lvalue-ish leaf: its C type is a declaration / an explicit cast / a carried access width
+  const promoted = (t: IrType | undefined): boolean | undefined =>
+    t?.kind !== 'int' ? undefined : t.width < 32 ? true : t.width === 32 ? t.signed : undefined;
+  switch (e.k) {
+    case 'var':
+    case 'cast':
+    case 'index':
+    case 'field':
+      return promoted(exprCType(e, varType));
+    // A decimal literal is `int` when it fits in one, and C89 gives a larger one an UNSIGNED type
+    // — agbcc says so itself ("decimal constant is so large that it is unsigned"). INT_MIN is in
+    // that class despite fitting: the backend prints it as `-2147483648`, which C lexes as unary
+    // minus applied to `2147483648`. Definite, not undetermined, and it drags the whole
+    // expression with it: `a / -2147483648` compiles to `lsr r0, r0, #0x1f` — an unsigned divide
+    // folded to a shift — where `a / (s32)-2147483648` calls `__divsi3`.
+    case 'const':
+      return e.value > -2147483648 && e.value <= 2147483647;
+    // `-x` / `~x` carry the PROMOTED type of the operand; `!x` is `int`.
+    case 'un':
+      return e.op === '!' ? true : rec(e.e);
+    case 'bin': {
+      // The SIGNEDNESS-CARRYING pairs — the ops the tower keeps apart because C spells each pair
+      // with one token and picks between them from the operand types (l3/ast.ts BinOp). The
+      // C-family backend PINS their operands, so what gets printed renders as the op says
+      // whatever the operands would have rendered as on their own. Reporting the operands here
+      // instead would answer about an expression nobody prints: a `>>` over a u32 var prints
+      // `(s32)v >> 3` and is signed, and a consumer told otherwise omits its own cast.
+      if (e.op === '>>' || e.op === '/' || e.op === '%') {
+        return true;
+      }
+      if (e.op === '>>>' || e.op === '/u' || e.op === '%u') {
+        return false;
+      }
+      // `<<` is sign-blind, so it keeps its left operand's type — nothing pins it.
+      if (e.op === '<<') {
+        return rec(e.l);
+      }
+      // Comparisons and the logical connectives yield `int`.
+      if (['<', '<=', '>', '>=', '==', '!=', '&&', '||'].includes(e.op)) {
+        return true;
+      }
+      return arithConversionSignedness(e.l, e.r, varType);
+    }
+    case 'call':
+    case 'marker':
+    case 'addr':
+      return undefined;
+  }
+}
+
+/** Is the rendered expression provably in [0, 2^31) — the range where a signed and an unsigned
+ *  compare agree on every input (and where gcc itself emits the unsigned branch for the signed
+ *  spelling)? Narrow unsigned values are the everyday case: a `(u8)x` cast or a `u8`/`u16`
+ *  deref promotes to a non-negative `int`. Conservative false elsewhere. */
+export function provablyNonNegative(e: Expr, varType: VarTypes): boolean {
+  switch (e.k) {
+    case 'const':
+      return e.value >= 0 && e.value < 0x80000000;
+    case 'un':
+      return e.op === '!';
+    case 'bin':
+      return ['<', '<=', '>', '>=', '==', '!=', '&&', '||'].includes(e.op);
+    case 'cast':
+      return e.to.kind === 'int' && e.to.width < 32 && !e.to.signed;
+    default: {
+      const t = exprCType(e, varType);
+      return t?.kind === 'int' && t.width < 32 && !t.signed;
+    }
+  }
+}
+
+/** Does this write put a value that renders as a DEFINITELY-NON-POINTER C expression into a
+ *  pointer-declared slot? — `v2 = a1 + v0` with `v2: u8 *`, a `return a0 + v0` from a
+ *  pointer-returning function, a store through a pointer-element lvalue. The machine's register
+ *  move says nothing about types; C does, and mwcc makes it an ERROR (gcc merely warns).
+ *
+ *  ONE question, TWO answers: the C family legalizes it with the reinterpret cast to the declared
+ *  type (backend/cfamily.ts), Pascal has no reinterpret cast and declines LOUD (backend/pascal.ts).
+ *  The question is shared so the two backends cannot come to disagree about WHICH writes are the
+ *  hazard while still disagreeing about what to do with one.
+ *
+ *  A rendering the model cannot reach (a call, whose C type comes from a prototype outside the
+ *  emitted function) is NOT the hazard: the answer has to be definite in the non-pointer
+ *  direction. A type predicate so the cast site keeps its narrowing on the declared type. */
+export function writesNonPointerIntoPointer(
+  declared: IrType | undefined,
+  value: Expr,
+  varType: VarTypes,
+): declared is Extract<IrType, { kind: 'ptr' }> {
+  if (declared?.kind !== 'ptr') {
+    return false;
+  }
+  const ct = exprCType(value, varType);
+  return ct !== undefined && ct.kind !== 'ptr' && ct.kind !== 'array';
+}
+
 export function exprCType(e: Expr, varType: (name: string) => IrType | undefined): IrType | undefined {
   const rec = (x: Expr): IrType | undefined => exprCType(x, varType);
   switch (e.k) {
@@ -121,10 +310,10 @@ export function exprCType(e: Expr, varType: (name: string) => IrType | undefined
       if (bt?.kind === 'ptr' && bt.to.kind === 'struct' && (bt.to.size === undefined || bt.to.size === e.width)) {
         return bt.to;
       }
-      if (bt?.kind === 'ptr' && derefStrideOk(bt, e.width)) {
+      if (bt?.kind === 'ptr' && derefStrideOk(bt, e.width, e.signed)) {
         return bt.to;
       }
-      if (bt?.kind === 'array' && derefStrideOk(bt, e.width)) {
+      if (bt?.kind === 'array' && derefStrideOk(bt, e.width, e.signed)) {
         return bt.elem;
       }
       return scalarTypeForAccess(e.width, e.signed);