@asmlift/core 0.5.0 → 0.6.0

package/src/pattern/engine.ts

@@ -5,13 +5,22 @@
 //
 // Crucially, rewrites go through replaceAllUsesWith + DCE — never in-place opcode
 // mutation of a live value.
-import { Fn, Op, Value, defOpMap, mkOp, mkValue, replaceAllUsesWith } from '../ir/core';
-import { NEGATED_ICMP, type Opcode, isDceSafe } from '../ir/opcodes';
+import { Block, Fn, Op, Value, defOpMap, mkOp, mkValue, replaceAllUsesWith } from '../ir/core';
+import { EFFECTFUL_OPS, NEGATED_ICMP, ORDER_SENSITIVE_OPS, type Opcode, isDceSafe } from '../ir/opcodes';
 import type { IrType } from '../ir/types';
 import { T } from '../ir/types';
 
 export type MatchNode =
-  | { op: string; attrEquals?: Record<string, number>; bindImm?: Record<string, string>; args: MatchNode[] }
+  | {
+      op: string;
+      attrEquals?: Record<string, number>;
+      bindImm?: Record<string, string>;
+      /** Match this node's two operands in the WRITTEN order only, even when the opcode is in
+       *  `COMMUTATIVE` — for an idiom where the machine's operand order is evidence about the
+       *  source rather than an accident of the encoding (see HWMOD_PATTERNS for the one case). */
+      ordered?: true;
+      args: MatchNode[];
+    }
   | { bind: string } // bind this operand's VALUE to a name
   | { same: string } // this operand must equal a previously-bound value
   | { constImm: string }; // this operand must be a `const`; bind its numeric VALUE to an imm name
@@ -67,6 +76,21 @@ export interface RewritePattern {
   // COMPUTED-attr half of the envelope (ImmExpr, above) IS built — earned by the
   // multiply-by-constant idioms.
   replaceWith: { op: string; args: ReplaceArg[]; attrs?: Record<string, number | ImmExpr>; resultType?: IrType };
+  /** Two REPLACEMENT operand names, in the order the replacement RENDERS them, whose defs C leaves
+   *  UNSEQUENCED against each other. A fold that collapses a multi-op idiom into one op drops its
+   *  operands from several uses to one, which lets the structurer inline both at that one use — and
+   *  then the RECOMPILING COMPILER, not asmlift, picks which of the two runs first. Naming this pair
+   *  makes the driver refuse a fold that would CHANGE the machine's order. What counts as "the
+   *  operand" and as "the order" is subtler than it reads, and `reordersUnsequenced` below owns both.
+   *
+   *  The `RightFirst` half is a compiler fact about the operator the replacement spells, verified by
+   *  compiling in both directions rather than assumed: mwcc lowers `f() % g()` as `bl g; bl f` and
+   *  `g() % f()` as `bl f; bl g`. It holds per OPERATOR, not per target — the same compiler runs
+   *  `-`'s LEFT operand first (`f() - g()` is `bl f; bl g`) — which is why it lives on the pattern
+   *  rather than on TargetDescription, and stays a field name rather than an order enum while there
+   *  is one inhabitant. The direction was measured on ONE compiler, so `validatePattern` pins the
+   *  declaring pattern's compiler gate to that set; widening it fails loud. */
+  unsequencedRightFirst?: [string, string];
 }
 
 /** Does this pattern apply to `target`? Every DECLARED axis must match: the ISA (so an idiom can be
@@ -142,6 +166,52 @@ export const SDIV_POW2_2: RewritePattern = {
   replaceWith: { op: 'sdiv', args: ['X'], attrs: { imm: 2 }, resultType: T.s() },
 };
 
+// ── the synthesized remainder (PPC) ─────────────────────────────────────────────────────
+// PowerPC divides in hardware but has no remainder instruction, so `a % b` is lowered as
+// `divw rQ,a,b; mullw rP,rQ,b; subf rD,rP,a` — the operator is GONE from the machine code, spelled
+// out as its own definition. Folding the triple back to one `smod`/`umod` gives recovery and the
+// structurer the operator the source wrote, and re-emitting `%` reproduces the triple byte-exact.
+//
+// This is NOT the `capabilities.hwDivide` axis: MIPS also divides in hardware and needs no fold at
+// all, because `div` leaves the remainder in `hi` and the frontend reads it straight out. The
+// narrower fact is a hardware divide that yields the QUOTIENT ONLY; `isa: 'ppc'` STANDS IN for it
+// until a second ISA earns the capability, and `compilers` carries the measured half, that mwcc's
+// lowering is exactly this triple in exactly this order. Neither clause is independently
+// falsifiable today — PPC_MWCC is the only target either one selects.
+//
+// `ordered: true` on the multiply says quotient-first is the PRECONDITION for re-emitting `%` — NOT
+// that the order identifies what the source wrote, which is false: `int q = a / b; return a - q *
+// b;` is a decomposition that compiles quotient-first too. So over-firing is byte-neutral (verified
+// by compiling both), and the flag buys the refusal direction: matching the swapped `mullw rP,b,rQ`
+// of `a - a / b * b` would respell an already byte-exact decomposition into a miss.
+//
+// A CONSTANT divisor is out of reach and deliberately left so — see the recognizer table on
+// `smod` in ir/opcodes.ts, which owns why. It costs nothing: `mulli` has no register operand
+// order to lose, and both spellings assemble to the same bytes.
+function hwModPattern(div: 'sdiv' | 'udiv', mod: 'smod' | 'umod'): RewritePattern {
+  return {
+    id: `hwmod-${mod}`,
+    applies: { isa: 'ppc', compilers: ['mwcc'] },
+    match: {
+      op: 'sub',
+      args: [
+        { bind: 'A' },
+        {
+          op: 'mul',
+          ordered: true,
+          args: [{ op: div, args: [{ same: 'A' }, { bind: 'B' }] }, { same: 'B' }],
+        },
+      ],
+    },
+    replaceWith: { op: mod, args: ['A', 'B'] },
+    unsequencedRightFirst: ['A', 'B'],
+  };
+}
+
+/** `a - a / b * b` → `a % b`, signed and unsigned. The `same` bindings are load-bearing: a
+ *  different dividend or divisor is a subtraction, not a remainder. */
+export const HWMOD_PATTERNS: RewritePattern[] = [hwModPattern('sdiv', 'smod'), hwModPattern('udiv', 'umod')];
+
 // ── multiply-by-constant idioms (DIVMUL) ────────────────────────────────────────────────
 // A compiler strength-reduces `x * C` for a small constant C into shifts + one add/sub, because a
 // shift-add chain is cheaper than a general multiply. The reduction is COMPILER-driven and shared
@@ -307,15 +377,16 @@ export const NOT_CMP_PATTERNS: RewritePattern[] = [
 
 // The DEFAULT idiom bundle `decompile()` applies when the caller passes no `patterns`. It is
 // EVERY idiom asmlift owns; the list self-selects per target through patternApplies — agbcc/gcc get
-// sdiv-pow2, agbcc/ido/gcc get the mul-const folds, mwcc gets cntlzw-eq0 + rotl-mirror, and agbcc
-// gets the casts. MOST patterns are `{compilers}`-gated because they trade one spelling for another
-// and are only byte-safe where measured; the boolean-negation folds are deliberately UNGATED (see
-// their comment — the shape is its own gate), so "gated per compiler" is the common case, not the
-// invariant. Ordered like the sub-bundles: the
-// division idiom, then the multiplies (base folds before the composite tail). Passing an explicit
-// `patterns` (including `[]`) overrides this — `[]` runs the naive lift with no idiom folding.
+// sdiv-pow2, agbcc/ido/gcc get the mul-const folds, mwcc gets cntlzw-eq0 + rotl-mirror + the PPC
+// remainder fold, and agbcc gets the casts. MOST patterns are `{compilers}`-gated because they
+// trade one spelling for another and are only byte-safe where measured; the boolean-negation folds
+// are deliberately UNGATED (see their comment — the shape is its own gate), so "gated per compiler"
+// is the common case, not the invariant. Ordered like the sub-bundles: the division idioms, then
+// the multiplies (base folds before the composite tail). Passing an explicit `patterns` (including
+// `[]`) overrides this — `[]` runs the naive lift with no idiom folding.
 export const DEFAULT_IDIOM_PATTERNS: RewritePattern[] = [
   SDIV_POW2_2,
+  ...HWMOD_PATTERNS,
   CNTLZW_EQ0,
   // AFTER cntlzw-eq0, which is what turns mwcc's `clz(x) >> 5` into the `icmp_eq` this fold then
   // negates — `!(x == 0)` composes only in that order (each pattern runs to fixpoint in turn).
@@ -331,6 +402,7 @@ export const DEFAULT_IDIOM_PATTERNS: RewritePattern[] = [
 // same test, and which one a frontend builds is an accident of how the branch was decoded — the
 // zero-test folds must match either. The ORDERED comparisons are deliberately absent: swapping the
 // operands of `a < b` is `b > a`, a different opcode, which this mechanism cannot express.
+// Membership here is about the OPCODE; a single pattern node opts back out with `ordered: true`.
 const COMMUTATIVE = new Set(['add', 'mul', 'and', 'or', 'xor', 'icmp_eq', 'icmp_ne']);
 
 interface Binds {
@@ -379,9 +451,10 @@ function tryMatch(node: MatchNode, v: Value, defs: Map<Value, Op>, b: Binds): bo
   if (d.operands.length !== node.args.length) {
     return false;
   }
-  // A commutative binary op matches its two args in EITHER order. Each order is tried on a cloned
-  // bind map so a partial (then-failed) match can't leak bindings; the first full match commits.
-  if (COMMUTATIVE.has(d.opcode) && node.args.length === 2) {
+  // A commutative binary op matches its two args in EITHER order, unless the pattern declared this
+  // node `ordered`. Each order is tried on a cloned bind map so a partial (then-failed) match can't
+  // leak bindings; the first full match commits.
+  if (COMMUTATIVE.has(d.opcode) && node.args.length === 2 && !node.ordered) {
     for (const [i, j] of [
       [0, 1],
       [1, 0],
@@ -402,8 +475,155 @@ function tryMatch(node: MatchNode, v: Value, defs: Map<Value, Op>, b: Binds): bo
   return node.args.every((a, i) => tryMatch(a, d.operands[i], defs, b));
 }
 
+/** Walk a pattern's match DAG once and reject a declaration that could not have an effect, or one
+ *  whose compiler gate outruns the evidence behind it. Same diagnosability-first rule as the
+ *  unbound-`replaceWith` throw below: `ordered` is consulted ONLY inside `tryMatch`'s
+ *  commutative-swap branch, so on a non-commutative or non-binary node it would be silently inert,
+ *  and a pattern author (or a generator emitting patterns as data) would get no error and no effect.
+ *
+ *  Everything checked here is a property of the pattern OBJECT, so the answer is memoized against it
+ *  rather than recomputed per lift — patterns may still be built at runtime, which is why this is a
+ *  WeakSet and not module-scope validation of the DEFAULT list. Only a PASSING run is recorded: a
+ *  pattern that threw must throw again on the next lift, or the first caller (annotate mode, which
+ *  swallows the throw into a stub) would silently license the malformed pattern for the whole run. */
+const UNSEQUENCED_RIGHT_FIRST_MEASURED_ON = ['mwcc'];
+const validated = new WeakSet<RewritePattern>();
+
+function validatePattern(pat: RewritePattern): void {
+  if (validated.has(pat)) {
+    return;
+  }
+  const walk = (n: MatchNode): void => {
+    if (!('op' in n)) {
+      return;
+    }
+    if (n.ordered && !(COMMUTATIVE.has(n.op) && n.args.length === 2)) {
+      throw new Error(
+        `pattern '${pat.id}' declares 'ordered' on a '${n.op}' node with ${n.args.length} operand(s), ` +
+          `where the written order is already the only reading — the flag would be inert`,
+      );
+    }
+    n.args.forEach(walk);
+  };
+  walk(pat.match);
+  if (pat.unsequencedRightFirst) {
+    for (const name of pat.unsequencedRightFirst) {
+      if (!pat.replaceWith.args.includes(name)) {
+        throw new Error(
+          `pattern '${pat.id}' names '${name}' in 'unsequencedRightFirst', which is not a replaceWith operand`,
+        );
+      }
+    }
+    const on = pat.applies.compilers ?? [];
+    const measured = UNSEQUENCED_RIGHT_FIRST_MEASURED_ON;
+    if (on.length !== measured.length || !measured.every((c) => on.includes(c))) {
+      throw new Error(
+        `pattern '${pat.id}' declares 'unsequencedRightFirst' but applies to compilers [${on.join(', ')}]; ` +
+          `the operand direction is only measured for [${measured.join(', ')}] — measure the new one and widen the set`,
+      );
+    }
+  }
+  validated.add(pat);
+}
+
+/** Would this fold DE-SEQUENCE the two named operands — leave the recompiling compiler, rather than
+ *  the machine code, deciding which of two observable effects runs first?
+ *
+ *  The fold collapses a several-op idiom into one, which drops each named operand from two uses to
+ *  one; the structurer then inlines a single-use def at its one use, TRANSITIVELY THROUGH PURE
+ *  SINGLE-USE OPS. So what lands at an operand position is that operand's whole inlinable CONE, not
+ *  just its def, and the question has to be asked over the cones: one pure `+ 1` between an effect
+ *  and the fold's operand is the difference between `f() % g()` and `(f() + 1) % g()`, and the
+ *  second one reorders exactly as the first does. Both cones become operands of ONE expression,
+ *  where C leaves their order unspecified. asmlift's inline-at-use model (structure/analysis.ts)
+ *  exempts exactly this case — "a sibling effect inlined into the SAME statement is not a reorder,
+ *  the recompiling compiler orders unsequenced operands of one expression exactly as it originally
+ *  chose to". That premise holds only when the expression asmlift re-spells is the one the source
+ *  wrote. A fold INVENTS an expression, so it must check.
+ *
+ *  A cone's members are weighed by ORDER_SENSITIVE_OPS, not EFFECTFUL_OPS: a memory read answers
+ *  whichever stores ran before it, so hoisting a `load` over a `call` — one asmlift may itself be
+ *  passing the loaded pointer to — changes the answer as surely as swapping two calls. Two READS
+ *  are the exception and commute, the same fact the structurer states as "a load never bars a
+ *  load", so a hazard needs an EFFECT on at least one side; `*p % *q` is admitted.
+ *
+ *  Refuses only what it must — the alternative spelling (the idiom written out) names the operands
+ *  and states the order, so a refusal is a loud, correct, slightly-worse-scoring answer. */
+function reordersUnsequenced(
+  fn: Fn,
+  root: Op,
+  names: [string, string],
+  binds: Binds,
+  defs: Map<Value, Op>,
+  pid: string,
+): boolean {
+  // Both cones are read within the ROOT's block, on two different grounds. A cross-block EFFECT the
+  // structurer materializes unconditionally — its execution would otherwise become path-dependent —
+  // so the C names it and pins the order there. A cross-block READ it does not; what pins that one
+  // is the structurer's own def→render write scan, where a call counts as a write, so a read cannot
+  // reach this expression across the very call it would be racing.
+  const blk: Block | undefined = fn.blocks.find((b) => b.ops.includes(root));
+  if (!blk) {
+    return false;
+  }
+  const at = new Map<Op, number>(blk.ops.map((o, i) => [o, i]));
+  const uses = new Map<Value, number>();
+  for (const b of fn.blocks) {
+    for (const o of b.ops) {
+      for (const v of [...o.operands, ...o.successors.flatMap((x) => x.args)]) {
+        uses.set(v, (uses.get(v) ?? 0) + 1);
+      }
+    }
+  }
+  /** What the structurer may pull in at one operand position: the operand's own def — which this
+   *  fold is about to drop to a single use — then each operand def that is ALREADY single-use, a
+   *  multi-use value being named and so staying a statement of its own. */
+  const coneOf = (name: string): Set<Op> => {
+    const v = binds.values.get(name);
+    if (!v) {
+      throw new Error(`pattern '${pid}' names unbound value '${name}' in 'unsequencedRightFirst'`);
+    }
+    const cone = new Set<Op>();
+    const stack: (Op | undefined)[] = [defs.get(v)];
+    while (stack.length) {
+      const op = stack.pop();
+      if (!op || cone.has(op) || !at.has(op)) {
+        continue;
+      }
+      cone.add(op);
+      for (const o of op.operands) {
+        if (uses.get(o) === 1) {
+          stack.push(defs.get(o));
+        }
+      }
+    }
+    return cone;
+  };
+  const [lc, rc] = names.map(coneOf);
+  const sensitive = (c: Set<Op>) => [...c].filter((o) => ORDER_SENSITIVE_OPS.has(o.opcode));
+  for (const l of sensitive(lc)) {
+    for (const r of sensitive(rc)) {
+      // One op standing in BOTH cones is one evaluation and cannot be sequenced against itself; two
+      // READS commute; and a right-cone op the machine ALREADY runs first loses nothing.
+      if (l === r || at.get(l)! >= at.get(r)! || !(EFFECTFUL_OPS.has(l.opcode) || EFFECTFUL_OPS.has(r.opcode))) {
+        continue;
+      }
+      // The left one runs first, so an inlined `A op B` would swap them — UNLESS a sibling effect
+      // stands between, which the inline-at-use model refuses to cross, forcing a named temp at the
+      // def's own position. A cone member is no sibling: it is inlined into this very expression.
+      if (
+        !blk.ops.slice(at.get(l)! + 1, at.get(r)!).some((o) => EFFECTFUL_OPS.has(o.opcode) && !lc.has(o) && !rc.has(o))
+      ) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
 /** Apply one pattern greedily to a fixed point. Returns the number of rewrites. */
 export function applyPattern(fn: Fn, pat: RewritePattern): number {
+  validatePattern(pat);
   let count = 0,
     changed = true;
   while (changed) {
@@ -419,6 +639,9 @@ export function applyPattern(fn: Fn, pat: RewritePattern): number {
         if (!tryMatch(pat.match, op.results[0], defs, binds)) {
           continue;
         }
+        if (pat.unsequencedRightFirst && reordersUnsequenced(fn, op, pat.unsequencedRightFirst, binds, defs, pat.id)) {
+          continue;
+        }
         // Materialize any synthesized-constant replacement operands as their own `const` ops,
         // spliced in before the rewrite; bound-value operands resolve from the value binds.
         const rw = pat.replaceWith;

package/src/pipeline.ts

@@ -5,28 +5,32 @@ import {
   ContractError,
   assertDerefsTyped,
   assertEffectsPreserved,
+  assertLocalsWritten,
   assertResolved,
   assertTypesRecovered,
 } from './contracts';
 import type { AsmData } from './frontend/asmdata';
 import { FrontendUnsupportedError } from './frontend/errors';
 import { frontendFor } from './frontend/registry';
-import { type Block, type Fn, successorsOf } from './ir/core';
+import { type Fn, reachableBlocks } from './ir/core';
 import { print } from './ir/print';
+import { firstTrivialPhi } from './ir/simplify';
 import { T } from './ir/types';
 import { VerifyError, verify } from './ir/verify';
-import { Expr, LanguageBackend, SFn, Stmt, exprChildren, gapReasonFor, stmtChildren, stmtExprs } from './l3/ast';
-import { hoistReusedGlobalBases } from './l3/basecse';
+import { LanguageBackend, SFn, gapReasonFor, walkExprs } from './l3/ast';
+import { BASECSE_GATES, hoistBaseLocals } from './l3/basecse';
 import { eliminateDeadStores } from './l3/dce';
 import { mergeCommonTails } from './l3/tailmerge';
 import { DEFAULT_IDIOM_PATTERNS, RewritePattern, applyPattern, dce, patternApplies } from './pattern/engine';
-import { type Prototypes, prototypesFromSymbols } from './proto';
+import { type FnProto, type Prototypes, prototypesFromSymbols } from './proto';
 import { RaiseUnsupportedError } from './raise/errors';
-import { type PreRecoveryPass, runPreRecovery } from './raise/pre-recovery';
+import { assumedShapes, inferGlobalArrays, orderLicensedGlobals } from './raise/globalshape';
+import { foldEmptyLatches } from './raise/latch';
+import { type PreRecoveryOptions, type PreRecoveryPass, runPreRecovery } from './raise/pre-recovery';
 import { recoverTypes } from './raise/recover';
 import { sinkReturns } from './raise/retsink';
 import { StructureError, structure } from './structure/structure';
-import { type SymbolMap, symbolsByName } from './symbols';
+import { type SymbolInfo, type SymbolMap, symbolsByName } from './symbols';
 import { type TargetDescription, structureOptionsFor } from './target';
 
 /** How a gap (a construct asmlift cannot faithfully model) degrades:
@@ -74,10 +78,36 @@ export interface DecompileResult {
   sfn: SFn;
   ir: { raw: string; folded: string; recovered: string }; // IR dumps: post-lift, post-idiom, post-recovery
   patternHits: number;
-  /** structured gap list — ALWAYS present; empty ⇔ the emission is gap-free (compiles + candidate
-   *  for scoring). Non-empty ⇔ the source contains ASMLIFT_ERROR markers / a stub and will NOT
-   *  compile until the user defines that symbol (the loud-in-artifact contract). */
+  /** structured gap list — ALWAYS present. Non-empty ⇔ the source contains ASMLIFT_ERROR markers /
+   *  a stub and will NOT compile until the user acts (the loud-in-artifact contract).
+   *
+   *  EMPTY IS THE ABSENCE OF A GAP, NOT A PROMISE THAT THE C COMPILES. A candidate can also fail
+   *  on a symbol the caller never declared, which is a CONTEXT question the benchmark answers by
+   *  escalating to the vendored preprocessed context. Most such names survive K&R implicit
+   *  declaration; a function ADDRESS does not, and klonoa's `UpdateStageSelectScreen` reports 0
+   *  gaps while emitting `((s32 *)50345232)[1] = &HandlePauseMenuInput;`, which agbcc rejects
+   *  where the plain call above it passes with a warning. Declaring an address-taken unknown
+   *  callee would close it — an emitter change, moving source bytes on every row that has one. */
   diagnostics: Diagnostic[];
+  /** THE SHAPES THIS SOURCE'S SPELLING ASSUMES, which no symbol map supplied (raise/globalshape.ts).
+   *
+   *  Everything else a backend emits is byte-correct under ANY declaration of the names it spells
+   *  — that is exactly why `((T *)&gSym)[i]` is the fallback (structure/globalaccess.ts). A bare
+   *  `gSym[i]` is not: it means what the DECLARATION of `gSym` says it means, and where that
+   *  declaration was derived from the assembly rather than read from the project's map, the
+   *  emitted source is right about the target's bytes only beside the declaration derived with it.
+   *  The element SIGNEDNESS is the sharp case, and it is an assumption rather than a reading:
+   *  compiled through the benchmark's own agbcc command, `(u16)gS[i]` over `extern const s16 gS[]`
+   *  and `gS[i]` over `extern const u16 gS[]` are the SAME OBJECT, so the assembly cannot say which
+   *  the source wrote — asmlift picks the one its own declaration block states.
+   *
+   *  So this travels with the source on every path that can emit it: the scoring layer renders it
+   *  (declare.ts, and main.ts's `[declared]` block), and a caller that shows the source alone must
+   *  show these too, or it is publishing a spelling whose meaning it has not stated. Empty on every
+   *  run that assumed nothing — which includes every derived shape the structurer did not spell
+   *  bare, and every name the caller's own map described (raise/globalshape.ts `assumedShapes`
+   *  computes that narrowing and names the corpus row behind each half). */
+  assumedSymbols: SymbolInfo[];
 }
 
 export function decompile(
@@ -115,39 +145,66 @@ function runTower(
   // (1) lift: ISA frontend (resolved by target) → L1 with block-argument SSA
   const fn = frontendFor(target).lift(name, asm, target, prototypes, opts.asmData, opts.symbols);
   verify(fn);
-  const raw = print(fn);
+  // Every dump carries the write-order record (ir/print.ts `PrintOptions`): it decides the
+  // edge-copy order and the raising folds mutate it, so two dumps compare whole program states.
+  const raw = print(fn, { writeOrder: true });
+  // (1.5) the ARRAY SHAPES this function's own assembly evidences, for globals the project map
+  // does not describe. Read HERE, off the lifted fn, because the fact it needs — whether the base
+  // was materialized before the index was scaled — is destroyed by the raising tower below
+  // (raise/globalshape.ts's module note). Empty unless the target opts in.
+  const inferredSymbols = inferGlobalArrays(fn, target);
+  // …and the ORDER half of the same reading, which reaches names the shape derivation refuses (a
+  // struct element among them). Read off the same lifted fn, for the same reason.
+  const orderLicensed = orderLicensedGlobals(fn, target);
 
   // (2) idiom fold: apply serializable patterns on the IR (the AI-improvement surface),
   // gated generically by the Target's capabilities (not an `arch ==` branch).
   const patternHits = applyIdiomPatterns(fn, target, opts.patterns);
-  const folded = print(fn);
+  const folded = print(fn, { writeOrder: true });
 
   // (2.35–3.5) pre-recovery recognizers → type recovery → return-sinking, the ONE shared spine
   // (`raiseRecovered`) that trace.ts and the cli's rank.ts/report.ts also run.
-  raiseRecovered(fn, target);
-  const recovered = print(fn);
+  raiseRecovered(fn, target, {}, prototypes[name]);
+  const recovered = print(fn, { writeOrder: true });
 
   // (4) structure: IR → neutral AST; boundary contract: no unresolved value leaked (strict), or
   // every unresolved value spelled as a loud ASMLIFT_ERROR marker (annotate).
+  const mapSymbols = opts.symbols ? symbolsByName(opts.symbols) : undefined;
   const sfn = structureChecked(fn, {
     ...structureOptionsFor(target, prototypes[name]?.returnsVoid ?? false),
+    // What the EMITTED LANGUAGE can say is a structuring input wherever two recoveries of one
+    // shape are behaviourally identical and only one of them is printable (switch fall-through
+    // vs plain if-nesting): recovery must not mint a tree this backend would refuse.
+    spellSwitchFallthrough: backend.spellsSwitchFallthrough,
     onGap,
-    ...(opts.symbols ? { symbols: symbolsByName(opts.symbols) } : {}),
+    ...(mapSymbols ? { symbols: mapSymbols } : {}),
+    ...(inferredSymbols.size ? { inferredSymbols } : {}),
+    ...(orderLicensed.size ? { orderLicensedGlobals: orderLicensed } : {}),
   });
 
   // (5) lower + print: neutral AST → target language
   const source = backend.emit(sfn);
 
-  return { source, sfn, ir: { raw, folded, recovered }, patternHits, diagnostics: collectMarkers(sfn) };
+  return {
+    source,
+    sfn,
+    ir: { raw, folded, recovered },
+    patternHits,
+    diagnostics: collectMarkers(sfn),
+    // WHAT THE SOURCE RESTS ON, not what the derivation found: a shape the structurer did not
+    // spell bare, and a name the caller's own map described, are both obligations this reader
+    // does not have (raise/globalshape.ts `assumedShapes`).
+    assumedSymbols: assumedShapes(inferredSymbols, sfn, mapSymbols),
+  };
 }
 
 // ── the shared raising tower ────────────────────────────────────────────────────────────────
-// decompile(), decompileTraced (trace.ts), and the cli's decompileRanked (rank.ts) /
-// decompileWithReport + its score probe (report.ts) all raise a lifted fn through the SAME
-// stage sequence. The optional hooks are the only per-caller
-// differences: rank pins its signedness candidate `beforeRecover`; the report pushes trace
-// entries after each stage. Every hook fires AFTER the stage's verify, so a hook can never
-// observe unverified IR.
+// decompile(), decompileTraced (trace.ts), rank.ts's decompileRanked and the cli's
+// decompileWithReport + its score probe (report.ts) all raise a lifted fn through the SAME stage
+// sequence. Two things vary per caller and nothing else does: the optional HOOKS — rank pins its
+// signedness candidate at `beforeRecover`, decompileTraced pushes a trace entry after each stage —
+// and the `pre` options bag, which reaches the pre-recovery passes themselves. Every hook fires
+// AFTER the stage's verify, so a hook can never observe unverified IR.
 
 /** Stage 2 — idiom fold: filter the pattern set by target capabilities, apply, dce + verify.
  *  Returns total hits. `patterns` defaults to DEFAULT_IDIOM_PATTERNS exactly like decompile(). */
@@ -173,17 +230,47 @@ export interface RaiseHooks {
   afterRecover?: () => void;
   /** after return-sinking, only when it changed the fn (fires after its verify) */
   afterRetsink?: () => void;
+  /** after empty-latch folding, only when it removed a block (fires after its verify) */
+  afterLatchFold?: () => void;
 }
 
 /** Stages 2.35–3.5 — pre-recovery recognizers (the shared ordered list in raise/pre-recovery.ts)
  *  → type recovery (boundary contract: no `unknown` survives) → return-sinking (tail-duplicate a
- *  return-only merge so short-circuits emit early returns). `verify` after every pass that
- *  changed the IR. */
-export function raiseRecovered(fn: Fn, target: TargetDescription, hooks: RaiseHooks = {}): void {
-  runPreRecovery(fn, target, (pass, result) => {
-    verify(fn);
-    hooks.afterPass?.(pass, result);
-  });
+ *  return-only merge so short-circuits emit early returns) → empty-latch folding (splice out a
+ *  back-edge block SSA construction emptied). `verify` after every pass that changed the IR.
+ *
+ *  The two CFG passes look ordered and are not: running latch folding FIRST instead changes
+ *  nothing across a 3337-function agbcc corpus. Worth saying, because folding an empty block ahead
+ *  of return-sinking does take away `br` predecessors it needs — the dominance gate is what makes
+ *  that unreachable, since the blocks retsink wants are never back-edge sources. It goes last
+ *  because that is where the CFG stops moving.
+ *
+ *  The tail is three separate parameters rather than an options bag on purpose: this is the
+ *  published package root export, so every caller outside this repo is pinned to the positions.
+ *
+ *  @param hooks per-stage observers; see {@link RaiseHooks}. Each fires after that stage's verify.
+ *  @param self  this function's own prototype, where the caller has one — what the pre-recovery
+ *               passes read to type the parameters they are narrowing.
+ *  @param pre   per-caller PRE-RECOVERY options. One shipped user: rank.ts's `/connective`
+ *               candidate, which passes `{ shortCircuit: { foldTreeOwned: true } }` to take the
+ *               fold the comparison-tree refusal owns (raise/shortcircuit.ts). */
+export function raiseRecovered(
+  fn: Fn,
+  target: TargetDescription,
+  hooks: RaiseHooks = {},
+  self?: FnProto,
+  pre: PreRecoveryOptions = {},
+): void {
+  runPreRecovery(
+    fn,
+    target,
+    (pass, result) => {
+      verify(fn);
+      hooks.afterPass?.(pass, result);
+    },
+    self,
+    pre,
+  );
   hooks.beforeRecover?.();
   recoverTypes(fn);
   verify(fn);
@@ -193,6 +280,26 @@ export function raiseRecovered(fn: Fn, target: TargetDescription, hooks: RaiseHo
     verify(fn);
     hooks.afterRetsink?.();
   }
+  if (foldEmptyLatches(fn)) {
+    verify(fn);
+    hooks.afterLatchFold?.();
+  }
+  // THE BOUNDARY POSTCONDITION. Above this line passes move the CFG; below it nothing does, and the
+  // structurer reads a block parameter as a JOIN — a name it must give a local of its own. A param
+  // whose every in-edge carries one value is not a join, and leaving one standing is how a
+  // CFG-motion pass does its damage three stages away rather than where it happened: retsink's own
+  // stranded merge was destroyed into `v0 = 0; return v0;` and read by Regime-A switch recovery as a
+  // SECOND `default` candidate, declining every fall-through tree. This names it at retsink.
+  // Not an `ir/verify.ts` rule: a trivial phi is well-formed IR, and both SSA construction and the
+  // `addrnum` pass mint one and clear it inside their own scope (see `firstTrivialPhi`).
+  const stranded = firstTrivialPhi(fn);
+  if (stranded) {
+    throw new Error(
+      `internal: raising left a trivial phi — block #${fn.blocks.indexOf(stranded.block)} takes ` +
+        `'${stranded.param}', whose every in-edge carries one value. A pass that retires an in-edge ` +
+        `must run simplifyTrivialPhis after it.`,
+    );
+  }
 }
 
 /** Run `body`; if it declines, name the unmodelled instructions the function carries.
@@ -214,15 +321,7 @@ function attributeOpaques<T>(fn: Fn, body: () => T): T {
     if (!(e instanceof StructureError) || !fn.blocks[0]) {
       throw e;
     }
-    const seen = new Set<Block>([fn.blocks[0]]);
-    for (const stack = [fn.blocks[0]]; stack.length;) {
-      for (const s of successorsOf(stack.pop()!)) {
-        if (!seen.has(s)) {
-          seen.add(s);
-          stack.push(s);
-        }
-      }
-    }
+    const seen = reachableBlocks(fn);
     const names = new Set<string>();
     for (const b of seen) {
       for (const op of b.ops) {
@@ -244,20 +343,26 @@ function attributeOpaques<T>(fn: Fn, body: () => T): T {
 /** Stage 4 — structure + its boundary contracts, always as a pair. */
 export function structureChecked(fn: Fn, opts: Parameters<typeof structure>[1]): SFn {
   const raw = attributeOpaques(fn, () => structure(fn, opts));
-  // BOTH boundary contracts run on the pre-DCE tree: the readability pass must never be able to
+  // The boundary contracts run on the pre-DCE tree: the readability pass must never be able to
   // hide a structuring defect by dropping the dead statement that carries it. assertResolved
   // catches an unresolved `?` value; assertDerefsTyped catches an ill-typed deref (e.g. a pointer
-  // under a rejected operator) — even one sitting in dead code structure emitted. DCE then only
-  // removes statements/flips branches over an already-validated tree.
+  // under a rejected operator) — even one sitting in dead code structure emitted;
+  // assertLocalsWritten catches a materialized def whose assignment no position emitted. DCE then
+  // only removes statements/flips branches over an already-validated tree.
   assertResolved(raw);
   assertDerefsTyped(raw);
+  assertLocalsWritten(raw);
   assertEffectsPreserved(fn, raw);
   // Then the readability/quality rewrites: merge a statement common to every arm of an if,
-  // drop dead stores (whose empty-then peephole flips the arm the merge empties), then hoist a
-  // reused aggregate-global
-  // base into a typed local pointer. The hoist moves the deref cast from each `index` node onto the
-  // local's initializer, so re-validate deref typing on the rewritten tree.
-  const sfn = hoistReusedGlobalBases(eliminateDeadStores(mergeCommonTails(raw)));
+  // drop dead stores (whose empty-then peephole flips the arm the merge empties), then hoist each
+  // leaf base the DEFAULT gate table admits into a typed local pointer. The hoist moves the deref
+  // cast from each `index` node onto the local's initializer, so re-validate deref typing on the
+  // rewritten tree.
+  // Both arguments SPELLED, defaults or not: this is the one call to this pass that is committed
+  // rather than offered, so it is the one whose gate table and whose placement can cost a MATCH
+  // instead of a candidate (docs/level-tower.md). A committed policy that reads as "whatever the
+  // default is" is the policy nobody reviews.
+  const sfn = hoistBaseLocals(eliminateDeadStores(mergeCommonTails(raw)), BASECSE_GATES, 'head');
   assertDerefsTyped(sfn);
   // Re-checked after the readability rewrites for the same reason deref typing is: a pass that
   // merges arms or drops statements must not be able to lose or duplicate a call.
@@ -317,26 +422,22 @@ export function stubResult(name: string, asm: string, backend: LanguageBackend,
     ir: { raw: '', folded: '', recovered: '' },
     patternHits: 0,
     diagnostics: [{ stage, reason: msg }],
+    // A stub spells no global, so it assumes nothing about one.
+    assumedSymbols: [],
   };
 }
 
 /** Every ASMLIFT_ERROR marker in the emitted AST, as a structured diagnostic (one per marker,
  *  document order). The harness/self-improve loop reads THIS; the source text is for humans. */
 function collectMarkers(sfn: SFn): Diagnostic[] {
-  // On the shared exprChildren/stmtExprs/stmtChildren traversal. Order is exprs-then-children
-  // per statement — deterministic and near-document-order (a `for`'s cond is visited before its
-  // init; see the note on stmtChildren).
+  // On the shared `walkExprs` traversal (l3/ast.ts). Order is exprs-then-nested-statements per
+  // statement — deterministic and near-document-order (a `for`'s cond is visited before its init;
+  // see the note on stmtChildren).
   const out: Diagnostic[] = [];
-  const we = (e: Expr): void => {
+  for (const e of walkExprs(sfn.body)) {
     if (e.k === 'marker') {
       out.push({ stage: 'structure', reason: e.reason });
     }
-    exprChildren(e).forEach(we);
-  };
-  const ws = (s: Stmt): void => {
-    stmtExprs(s).forEach(we);
-    stmtChildren(s).forEach(ws);
-  };
-  sfn.body.forEach(ws);
+  }
   return out;
 }