@asmlift/core 0.6.0 → 0.8.0

package/src/target.ts

@@ -1,4 +1,4 @@
-// asmlift — the Target: (isa, compiler) as first-class axes. ABI + capabilities are DATA
+// asmlift — the Target: (isa, compiler) as first-class fields. ABI + capabilities are DATA
 // consumed generically by shared passes — never a target-name branch inside a shared pass
 // (m2c's `arch.arch ==` leakage).
 //
@@ -15,38 +15,46 @@
 //   • capabilities.flags → RESERVED, not yet read by any pass (PPC condition regs will).
 //   • capabilities.readOnlyAddressSinks → the Thumb frame-object audit: a frame address stored to
 //     one of these reached a device that only reads through it, so it does not retract `undef`.
-//   • capabilities.deviceRegisters → four readers, and they ask ONE question — "would a source
+//   • capabilities.deviceRegisters → five readers, and they ask ONE question — "would a source
 //     have spelled this address `volatile`" — which is a question about SPELLING and may be
-//     approximate: the `/vol-store` lever's eligibility (l3/volstore.ts), rank.ts's volatility
+//     approximate: the `/vol-store` variation's eligibility (l3/volstore.ts), rank.ts's volatility
 //     tie-break between two byte-identical spellings, the first half of `/unreduce`'s
-//     disjointness gate (l3/unreduce.ts), and the `/homesplit` pairing's refusal to leave a device
-//     READ inline where the spelling it replaces would have qualified it (l3/homesplit.ts).
+//     disjointness gate (l3/unreduce.ts), the `/homesplit` pairing's refusal to leave a device
+//     READ inline where the spelling it replaces would have qualified it (l3/homesplit.ts), and
+//     the structurer's refusal to SPELL a dead memory read whose address no qualifier could ever
+//     reach (structure.ts `volatileQualifiable`, threaded through StructureOptions).
 //   • capabilities.deviceMemoryWriters → the MEMORY-MODEL question, which is a different one and
 //     may NOT be approximate: "can a write to this register make the DEVICE write ordinary
 //     memory". One reader — `/unreduce`'s second half. Split from `deviceRegisters` because
 //     conflating them recorded a false premise (see the field's own comment).
 //   • compilerBehaviors.* → mostly consumed by the structurer (threaded via StructureOptions).
-//     Four exceptions are read off the target directly, their consumers not being the
-//     structurer: `nearBaseSpan` and `foldsConstAddrOffset` (rank.ts, L3 levers),
-//     `hoistsSingleSetArm` (raise/pre-recovery.ts, a raising pass) and `arrayShapeFromStride`
-//     (raise/globalshape.ts, run on the LIFTED fn). The field names are a
+//     Five exceptions are read off the target directly, their consumers not being the
+//     structurer: `nearBaseSpan` and `foldsConstAddrOffset` (rank.ts, L3 respell variations),
+//     `reloadsLocalReread` (raise/pre-recovery.ts), `hoistsSingleSetArm` (two raising passes —
+//     raise/narrowlocal.ts and raise/retsink.ts) and
+//     `arrayShapeFromStride` (raise/globalshape.ts, run on the LIFTED fn). The field names are a
 //     SUPERSET of StructureOptions' — see `structureOptionsFor`.
 //
-// `capabilities` (HARDWARE facts) vs `compilerBehaviors` (COMPILER canonicalization choices) are
+// `capabilities` (HARDWARE facts) vs `compilerBehaviors` (COMPILER canonicalization decisions) are
 // deliberately separate bags: a new compiler must set its behaviors EXPLICITLY instead of
 // silently inheriting a universal that is really per-compiler. `coalesceLoopInit` already
 // differs across targets (IDO true, agbcc/GCC false).
 // This module is browser-pure by contract (no Node APIs, enforced by
 // test/browser-safe.test.ts): the toolchain paths that COMPILE for these targets
 // live in @asmlift/toolchains.
+import { type CodegenProfile, type FlagFamily, parseFlags } from './codegen-flags';
 import type { StructureOptions } from './structure/structure';
 
+/** What a compiler's OBJECT shows for a narrow declared parameter — see
+ *  `compilerBehaviors.narrowParamWitness` for the compiled pair behind each value. */
+export type NarrowParamWitness = 'prologue-extension' | 'home-store-and-in-place' | 'none';
+
 export interface TargetDescription {
   id: string; // the ISA — 'armv4t' / 'mips' / 'ppc'. Selects the frontend (registry.ts).
-  // The COMPILER is a first-class axis distinct from the ISA (matching = deoptimize to a specific
+  // The COMPILER is a first-class field distinct from the ISA (matching = deoptimize to a specific
   // compiler): two targets can share an ISA (⇒ one frontend) yet differ here — e.g. MIPS_IDO vs
   // MIPS_GCC. Consumed by pattern gating (patternApplies) and the report. (version/flags/language
-  // are future axes, added when earned.)
+  // are future fields, added when earned.)
   compiler: string; // 'agbcc' / 'ido' / 'gcc' / 'mwcc'
   argRegs: string[];
   returnReg: string;
@@ -91,7 +99,7 @@ export interface TargetDescription {
     // the same SPELLING question — "would a source have written `volatile` here" — and the file
     // header's ledger names them and what each does with the answer. None of them decides for the
     // reader: which cells a source qualified is not derivable from the asm, so both spellings are
-    // enumerated and the differ referees. ABSENT ⇒ the lever declines everywhere and the tie-break
+    // enumerated and the differ referees. ABSENT ⇒ the variation declines everywhere and the tie-break
     // has no preference, which is the neutral direction — outside a declared window the qualifier
     // is a claim about ordinary memory that the target does not support.
     //
@@ -116,7 +124,7 @@ export interface TargetDescription {
     // possible memory write — the conservative direction, and what every non-GBA target takes.
     deviceMemoryWriters?: readonly (readonly [number, number])[];
   };
-  // COMPILER BEHAVIORS — the specific compiler's canonicalization choices, distinct from
+  // COMPILER BEHAVIORS — the specific compiler's canonicalization decisions, distinct from
   // hardware `capabilities`. Mostly consumed by the structurer (threaded through StructureOptions);
   // the exceptions are listed at the top of this file and each says so at its own field.
   compilerBehaviors: {
@@ -141,7 +149,7 @@ export interface TargetDescription {
     // where that copy sits, not by where its value was computed. Uniform (true) across all current
     // compilers; absent ⇒ true, and a compiler that opts OUT turns the sort off entirely and emits
     // in source/param order. WHICH order a measured edge takes is not this flag's question and
-    // cannot be: the benchmark has rows on both sides inside one compiler (mwcc), so that choice is
+    // cannot be: the benchmark has rows on both sides inside one compiler (mwcc), so that decision is
     // refereed per row by `/copy-defpos` (rank.ts), never declared per compiler here.
     orderArgCopiesByWriteOrder?: boolean;
     // Regime-A switch recovery: accept an `x != K` test as a case (the EQUAL side is the case
@@ -150,18 +158,56 @@ export interface TargetDescription {
     switchAllowsNeqCase?: boolean;
     // The compiler collapses `if (…) x = a; else x = b;` into `x = b; if (…) x = a;` when both
     // arms are ONE speculatable SET — gcc 2.x's `jump_optimize` (`gcc/jump.c:443-445`, guard at
-    // `:471-502`). The ONE reader is raise/narrowlocal.ts's `edge-extends`, which uses it
-    // BACKWARDS: a diamond this compiler would have collapsed and did not is evidence the source
-    // DECLARED the local narrow, because `gcc/thumb.h:344` PROMOTE_MODE expands a narrow-declared
-    // assignment past one SET. Absent ⇒ false, and the clause never admits. `structureOptionsFor`
+    // `:471-502`). Absent ⇒ false, and every clause below never admits. `structureOptionsFor`
     // spreads it onto StructureOptions like every other field here, but NO structurer code reads
-    // it: its reader is a pre-recovery pass, threaded from `runPreRecovery`'s own `target`.
+    // it: both readers are raising passes, threaded from their driver's own `target`.
+    //
+    // TWO READERS, ONE FACT, BOTH READING IT BACKWARDS. One field rather than one per reader,
+    // because a second boolean for the same guard lets a round that measures another compiler's
+    // `jump_optimize` set one and leave the other false, with both comments reading as
+    // authoritative.
+    //
+    //   • raise/narrowlocal.ts's `edge-extends`: a diamond this compiler would have collapsed and
+    //     did NOT is evidence the source DECLARED the local narrow, because `gcc/thumb.h:344`
+    //     PROMOTE_MODE expands a narrow-declared assignment past one SET.
+    //   • raise/retsink.ts's `compiler-hoists-single-set-arm`: a merge-variable select whose arms
+    //     this guard would have collapsed never comes back as a diamond, so a TARGET holding one
+    //     was written with early returns and its returns should be sunk.
     //
-    // Set on agbcc, where the 2x2 in raise/narrowlocal.ts's header was compiled and scored. NOT
-    // set on MIPS_GCC despite it being the same compiler family: nothing has measured the pair
-    // there, the clause reaches 0 of its benchmark rows, and `docs/level-tower.md`'s rule for an
-    // unmeasured per-compiler default is to claim nothing.
+    // Set on agbcc, where the 2x2 in raise/narrowlocal.ts's header was compiled and scored and
+    // where retsink's seven-function spelling pair was compiled and committed
+    // (`packages/core/test/corpus/agbcc-select-{merge,early}.s`). NOT set on MIPS_GCC despite it
+    // being the same compiler family: nothing has measured the pair there, the clause reaches 0 of
+    // its benchmark rows on either reader, and `docs/level-tower.md`'s rule for an unmeasured
+    // compiler behavior is to claim nothing. The evidence a future round needs is one run of
+    // `scripts/regen-select-spelling-probes.ts` retargeted at the compiler in question.
     hoistsSingleSetArm?: boolean;
+    // WHAT, IN THIS COMPILER'S OBJECT, WITNESSES A NARROW DECLARED PARAMETER — the fact
+    // raise/paramwidth.ts needs before it may retype `s32 a0` to `s8 a0`. Three answers, because
+    // the compilers measured give three, and the pass refuses wherever the object is silent. Each
+    // target below carries its own measurement, and raise/paramwidth.ts's header carries the
+    // compiled pairs all three readings rest on.
+    //
+    //   • `'prologue-extension'` — the extension's POSITION decides it: a narrow-declared
+    //     parameter widens at the very top of the function, a body cast widens at its use.
+    //   • `'home-store-and-in-place'` — the position decides NOTHING, both spellings leading the
+    //     function, and TWO other facts decide it together: the parameter is stored to an argument
+    //     home nothing reads back AND widened in its own argument register. Each half alone has a
+    //     compiled counterexample, so only the PAIR separates a declaration from a body cast.
+    //
+    //     THE HOME STORE IS AN `-O2` OBSERVABLE, AND `-g` IS NOT WHAT REMOVES IT. Measured on
+    //     `int f(s8 x){ return x; }`: present at `-O2` and at `-O2 -g3`, absent at `-O1`, at `-O0`
+    //     and at `-g` (which implies `-O0`). So the 42 real af rows that build at
+    //     `-G 0 -non_shared -Wab,-r4300_mul -mips2 -EB -O2 -g3` DO carry it — checked at exactly
+    //     those flags — and a target built at `-O1`/`-O0` would have to claim `'none'`. The
+    //     in-place widening survives every one of those levels, but on its own it decides nothing,
+    //     so the pass refuses there rather than reading half a pair.
+    //   • `'none'` — the object does not distinguish the two at all, so no reading of it licenses
+    //     the narrowing. It is a MEASUREMENT rather than a withholding wherever a target claims it.
+    //
+    // A compiler that sets nothing here also refuses, which is the right default for one nobody has
+    // compiled the pair with (docs/level-tower.md: claim nothing about an unmeasured behavior).
+    narrowParamWitness?: NarrowParamWitness;
     // A subscript over a DECLARED ARRAY OBJECT expands its base ahead of the index, where every
     // pointer or cast base expands it last — so the instruction order in the target's own assembly
     // says which of the two the source wrote, and `raise/globalshape.ts` may derive an array shape
@@ -174,7 +220,7 @@ export interface TargetDescription {
     // so `u16 *p = (u16 *)&gTbl; p[i]` is base-first in the object while `(p = (u16 *)&gTbl)[i]` is
     // index-first, both through this same fork (compiled; raise/globalshape.ts's header carries the
     // four-way table). This flag is therefore NARROWER than that consumer's mechanism — statement
-    // ordering needs no fork, only a compiler that does not schedule — so the home axis is denied
+    // ordering needs no fork, only a compiler that does not schedule — so the home variation is denied
     // to ido/kmc/mwcc for a reason that is not its own. Under-reach, unmeasured, and the fix when a
     // row asks for it is a datum of its own rather than a widening of this one.
     //
@@ -182,7 +228,7 @@ export interface TargetDescription {
     // `TREE_CODE (TREE_TYPE (array)) == ARRAY_TYPE && TREE_CODE (array) != INDIRECT_REF` and both
     // spellings were compiled against the same target. NOT set anywhere else: whether ido, kmc or
     // mwcc distinguish them at all is unmeasured, and `docs/level-tower.md`'s rule for an
-    // unmeasured per-compiler default is to claim nothing. Read off the target by a raising pass
+    // unmeasured compiler behavior is to claim nothing. Read off the target by a raising pass
     // (`inferGlobalArrays`), not by the structurer.
     arrayShapeFromStride?: boolean;
     // Which way this compiler hands out FRAME SLOTS against a spilled local's DECLARATION RANK:
@@ -204,11 +250,30 @@ export interface TargetDescription {
     // says so, but nothing in this bag could express it if they did not. Any behavior that can
     // differ between two toolchains sharing one description is mis-keyed by construction.
     spillSlotOrder?: 'ascending' | 'descending' | 'unknown';
+    // Arguments past the argument registers are staged into an area this function RESERVES at the
+    // BOTTOM of its own frame — `[sp,#0]` upward, one word each — rather than pushed at the call
+    // site. It is GCC's ACCUMULATE_OUTGOING_ARGS target macro, and it is what makes an outgoing
+    // argument INDISTINGUISHABLE by code alone from a dead local: the words sit inside this
+    // frame's reservation and nothing this function does ever reloads one.
+    //
+    // Absent ⇒ no outgoing area is claimed and the Thumb frontend's stack-argument licence never
+    // fires, so a `[sp,#k]` store reaching a call unread declines exactly as it did before that
+    // licence existed. Read off the target by the frontend (`frontend/thumb.ts` `declaredCall`),
+    // not by the structurer.
+    //
+    // Set on agbcc, where the layout was read off `gcc/config/arm/thumb.h` and then measured —
+    // the corpus's `stkarg` (accepting) and `stkwide` (refusing) rows and kleod's
+    // `sub_0804C300` all stage their words at [sp,#0] upward inside the prologue's own
+    // reservation. NOT set anywhere else: a push-based caller would stage nothing inside the
+    // frame, and `docs/level-tower.md`'s rule for an unmeasured compiler behavior is to claim
+    // nothing. No other frontend calls the analysis today, so the field claims a premise rather
+    // than changing a verdict — which is the point: a second armv4t compiler must state it.
+    stagesOutgoingArgsInFrame?: boolean;
     // Regime-A switch recovery: accept a RELATIONAL test whose BRANCH admits exactly one scrutinee
     // value as that case (`cmp r0, #1 / bcc` is `case 0:` of an unsigned switch) rather than as
     // navigation.
     //
-    // A DEFAULT rather than a candidate axis because for agbcc the asm determines the source: at
+    // A DEFAULT rather than a candidate variation because for agbcc the asm determines the source: at
     // -O2 fold-const rewrites a bounded unsigned comparison into an equality before codegen, so
     // `x < 1u` compiles to `cmp r0, #0 / bne` and `x > 0u` to `cmp r0, #0 / beq` — no source-level
     // comparison chain emits a bound test at all. `emit_case_nodes` runs after folding and does:
@@ -232,13 +297,43 @@ export interface TargetDescription {
     // Absent ⇒ ascending case value, where ido/kmc-gcc/mwcc sit: each has a scheduler and none has
     // been put through that evidence. A compiler opts in on its own, never by inheriting.
     switchArmsFollowLayout?: boolean;
+    // Switch recovery: DECLINE a comparison tree whose own layout INTERLEAVES a test block with a
+    // case body, on the reading that the source wrote an if/else-if LADDER there. True claims the
+    // compiler emits a source `switch`'s whole dispatch AHEAD of every arm body — the same
+    // `expand_end_case` closing `reorder_insns` `switchArmsFollowLayout` is read off, used for the
+    // other half of what it does — while a ladder's tests stay above their own bodies.
+    //
+    // IT NEEDS HALF OF `switchArmsFollowLayout`'s PREMISE, AND THE IMPLICATION RUNS ONE WAY ONLY.
+    // That flag PLACES the arms and so needs the whole no-reordering claim (nothing moved a block
+    // at all); this one only asks whether any BODY sits above a test, so a compiler that moves
+    // instructions, fills delay slots, or reorders within a block can still declare it. A compiler
+    // that declares the PLACING one has therefore already said what this one needs — never the
+    // converse. `MIPS_GCC` is the standing counterexample to the converse: it declares this flag on
+    // its own pairs (below) and deliberately does NOT declare `switchArmsFollowLayout`, because it
+    // has a scheduler. Declaring this one is not evidence for that one.
+    //
+    // agbcc declares it, and its own pair of objects says the reading is not vacuous: at agbcc's
+    // canonical flags the same two-case body is 20 bytes (0x14, ten Thumb instructions)
+    // written either way and is a DIFFERENT object — the `switch` emits `cmp #0x1e; beq` then
+    // `cmp #0x64; bne` before either body, sorted ascending and so in the reverse of the written
+    // order; the ladder emits `cmp #0x64; bne` directly above its own body and reaches `cmp #0x1e`
+    // only after it. The pair is committed: `corpus/agbcc-sw{frontload,ladder}.s` from
+    // `corpus/probe-agbcc-sw{frontload,ladder}.c`, regenerated by
+    // `scripts/regen-switch-spelling-probes.ts`, asserted in switch-arms.test.ts.
+    //
+    // Absent ⇒ every recoverable tree is still spelled `switch`, which is where ido/mwcc sit: each
+    // has a scheduler that may move a body above a test, and neither has been put through the pair.
+    // A compiler opts in on its own compiled evidence, never by inheriting — and where one
+    // description serves two toolchains (`MIPS_GCC`), each toolchain owes its own pair, because the
+    // field cannot distinguish them (the KEYED BY DESCRIPTION note at `spillSlotOrder`).
+    switchRequiresFrontLoadedTests?: boolean;
     // Commutative load pairs re-spell in def (evaluation) order (structure.ts lowerDef). Absent
     // ⇒ true — verified byte-exact on agbcc and IDO; a compiler whose scheduler is shown
     // re-ordering independent loads opts OUT here.
     defOrderLoadPairs?: boolean;
-    // The single-add-immediate derivation reach for the /nearbase lever (l3/nearbase.ts):
+    // The single-add-immediate derivation reach for the /nearbase variation (l3/nearbase.ts):
     // neighbor absolute addresses within this many bytes may share one base local. Thumb's
-    // `add rd, #imm8` reaches 255. Absent ⇒ the lever stands down for this target.
+    // `add rd, #imm8` reaches 255. Absent ⇒ the variation stands down for this target.
     nearBaseSpan?: number;
     // Does this compiler CONSTANT-FOLD a constant SUBSCRIPT into the literal address it
     // materializes for an inline constant-address access? agbcc does: `((u8 *)0x3001100)[3]`
@@ -250,25 +345,56 @@ export interface TargetDescription {
     // and PPC lanes put the addend in the instruction by construction (`lui`/`%lo`, `lis`/`ori`),
     // so a surviving offset carries no information there. Absent ⇒ the row is never offered.
     foldsConstAddrOffset?: boolean;
+    // Does this compiler fold a pointer local's OWN ADVANCE back into the memory operand —
+    // `*p = a; p = p + 1; *p = b;` → `strh [r3, #0]` + `strh [r3, #2]`, no `add` — so the advanced
+    // spelling emits the indexed one's stores wherever the pointee is not volatile? agbcc does, on
+    // its own compiled evidence: the four corners in test/advance.test.ts's header, each built
+    // through the benchmark's agbcc against `kleod:StreamCmd_SetWindowRegs`'s object, and the pair
+    // `TARGET_BEHAVIOR_READINGS` compiles to one object in the matching suite. True ⇒
+    // the `advance` registry entry's target gate withholds the UN-QUALIFIED variation, whose spelling this compiler cannot
+    // distinguish from the indexed one it already offers; `/advance/volatile` still rides, because
+    // `volatile` is what bars the fold and that product is the match on this row. Absent ⇒ falsy ⇒
+    // the plain variation ships, which is the conservative reading for a compiler whose pair nobody has
+    // compiled — a compiler opts in on its own evidence and never by inheriting.
+    foldsPointerAdvance?: boolean;
     // Does this compiler EMIT a memory read in the block the source SPELLED it in? One direction
     // only: the def-block placement rule (StructureOptions.readsStayWhereWritten) re-spells a read
     // at the block the asm performed it in, which reproduces the asm iff nothing sinks a spelled
     // read past a branch and nothing lifts one to a dominator. The CONVERSE — the asm's read block
     // is where the source read — is FALSE even here, and no default may be declared as if it held.
     //
-    // agbcc (gcc 2.9-arm, -O2) declares TRUE from its own sources plus a compiled pair: gcc's
-    // Makefile SRCS compiles neither sched.c nor reorg.c and toplev.c never mentions
-    // flag_schedule_insns, so there is no scheduler; gcse.c calls one_code_hoisting_pass only
-    // `if (optimize_size)`, which toplev.c sets only for -Os, so at -O2 the hoister is compiled in
-    // and never runs (a -Os project would NOT get this declaration); and `s = *g; if (c) A(s);
-    // else B(s);` against `if (c) A(*g); else B(*g);` emits one ldrb + one pool word versus one of
-    // each PER ARM, moving neither. The two passes that DO move a read between blocks at -O2 —
-    // loop invariant motion, and the PRE that makes the converse false — are refusals the rule
-    // owes; structure/analysis.ts carries them.
+    // agbcc (gcc 2.9-arm) declares TRUE from its own sources plus compiled pairs: gcc's Makefile
+    // SRCS compiles neither sched.c nor reorg.c and toplev.c never mentions flag_schedule_insns, so
+    // there is no scheduler; and `s = *g; if (c) A(s); else B(s);` against `if (c) A(*g); else
+    // B(*g);` emits one ldrb + one pool word versus one of each PER ARM, moving neither. gcse.c calls
+    // one_code_hoisting_pass only `if (optimize_size)`, which toplev.c sets only for -Os, so at -O2
+    // the hoister never runs. At -Os it runs, and on `if (c) A(*gp); else B(*gp);` it moves only the
+    // pool ADDRESS load above the branch: each arm keeps its own dereference, so the read still
+    // stays in the block that spelled it. That pair is committed: `corpus/agbcc-hoist-{O2,Os}.s` from
+    // `corpus/probe-agbcc-hoist.c`, regenerated by `scripts/regen-flag-pair-probes.ts`, asserted in
+    // hoist-level-probes.test.ts. The two passes that DO move a read between blocks at -O2 — loop
+    // invariant motion, and the PRE that makes the converse false — are refusals the rule owes;
+    // structure/analysis.ts carries them.
     //
     // ABSENT ⇒ the rule stands down, where ido/kmc-gcc/mwcc sit: each has a scheduler and none has
     // been put through that pair. A compiler opts in on its own evidence, never by inheriting.
     readsStayWhereWritten?: boolean;
+    // Does a LOCAL initialised with a memory read its dominating TEST already performed cost this
+    // compiler a SECOND load? The pair is the arm of `if (a && (p[1] & 0x7f) == 0x7f) { … }` spelled
+    // `u8 v = p[1]; p[2] = v;` against `p[2] = p[1];`, and again with a store and with a call
+    // between the local and its use. agbcc loads `p[1]` TWICE for every local spelling and once
+    // for the inline one; ido7.1, gcc2.7.2kmc, gcc2.7.2 and mwcc_242_81 load it ONCE for every
+    // local spelling, holding the register across the store and across the call. agbcc is the
+    // odd one out of five, so the one agbcc-shaped claim that rested on it — raise/shortcircuit.ts's
+    // `read-behind-effect`, "a copy analysis.ts spells as a local costs a load" — reads it here
+    // rather than running on every target — on mwcc it costs the probe named at PPC_MWCC's value
+    // its byte-match.
+    // Read off the target by a raising pass (raise/pre-recovery.ts), not by the structurer.
+    //
+    // ABSENT ⇒ false: the refusal stands down, and a compiler opts IN on its own compiled pair. The
+    // three descriptions that measured false (four compilers) set it anyway, so absent means
+    // UNMEASURED rather than "no".
+    reloadsLocalReread?: boolean;
   };
 }
 
@@ -324,11 +450,15 @@ export const ARMV4T_AGBCC: TargetDescription = {
     orderArgCopiesByWriteOrder: true,
     nearBaseSpan: 255,
     foldsConstAddrOffset: true,
+    foldsPointerAdvance: true,
     readsStayWhereWritten: true,
     switchAllowsBoundCase: true,
     switchArmsFollowLayout: true,
+    switchRequiresFrontLoadedTests: true,
     hoistsSingleSetArm: true,
     arrayShapeFromStride: true,
+    reloadsLocalReread: true,
+    narrowParamWitness: 'prologue-extension',
     // agbcc: reload walks pseudos ascending handing each global-alloc loser a fresh slot, a user
     // local's pseudo number is its `expand_decl` position, and the Thumb frame grows UPWARD
     // (FRAME_GROWS_DOWNWARD is commented out in thumb.h). So the earlier-declared spilled local
@@ -337,6 +467,9 @@ export const ARMV4T_AGBCC: TargetDescription = {
     // control `synthetic:spillorder_rev` (the same body in the order asmlift already emits, which
     // must stay a MATCH), plus `synthetic:dma_fill_uninit`, a row this did not author.
     spillSlotOrder: 'ascending',
+    // agbcc reserves the outgoing area with the rest of the frame (`add sp, sp, #-N` covers both)
+    // and stages arguments 5+ into it at [sp,#0] upward — thumb.h's ACCUMULATE_OUTGOING_ARGS.
+    stagesOutgoingArgsInFrame: true,
   },
 };
 
@@ -358,6 +491,13 @@ export const MIPS_IDO: TargetDescription = {
     preserveDivergentBranchSense: true,
     orderArgCopiesByWriteOrder: true,
     switchAllowsNeqCase: false,
+    // MEASURED — the pair at the field compiles to one load of `p[1]` for every local spelling.
+    reloadsLocalReread: false,
+    // MEASURED at `-mips2 -O2 -32 -non_shared -G 0`: the `sll` leads the function for BOTH
+    // spellings, so the prologue position cannot decide; a narrow DECLARED parameter is the one that
+    // is both homed dead AND widened in its own argument register. raise/paramwidth.ts's header has
+    // the disassemblies, including the counterexample for each half alone.
+    narrowParamWitness: 'home-store-and-in-place',
     // MEASURED `descending` (the earlier-declared spilled local takes the HIGHER offset) and NOT
     // SHIPPED. The probe is COMMITTED — `packages/core/test/corpus/probe-declrank.c` and its
     // reversed-declaration twin, with this compiler's objects beside them — and a test reads the
@@ -388,7 +528,7 @@ export const MIPS_GCC: TargetDescription = {
   // KMC GCC keeps a loop seeded from an argument register IN that register (coalesceLoopInit
   // true, like IDO): test/corpus/gcc-gcd.asm runs its whole loop on a0/a1 with no init copies,
   // and the row it comes from matches only with the parameters as the loop's homes. The other
-  // structuring levers take the universal default until a KMC fixture says otherwise.
+  // structuring compiler behaviors take the universal default until a KMC fixture says otherwise.
   //
   // THIS IS A COMPILER-WIDE GUESS STANDING IN FOR A PER-FUNCTION OBSERVATION the assembly states
   // outright: whether the compiler kept a loop's induction variable in its argument register. What
@@ -407,6 +547,48 @@ export const MIPS_GCC: TargetDescription = {
     coalesceLoopInit: true,
     preserveDivergentBranchSense: true,
     orderArgCopiesByWriteOrder: true,
+    // DECLARED ON A PAIR FROM EACH TOOLCHAIN THIS DESCRIPTION SERVES, never inherited from agbcc's
+    // and never from one sibling to the other. This description is keyed per DESCRIPTION while the
+    // fact is per TOOLCHAIN (the note at `spillSlotOrder`), and `MIPS_GCC` serves two, so both owe
+    // a pair: `corpus/gcc272kmc-sw{frontload,ladder}.asm` from GCC_KMC_TOOLCHAIN at -O2 and
+    // `corpus/gcc272-sw{frontload,ladder}.asm` from the Mario Party 3 toolchain at -O1 — one
+    // two-case body written each way, regenerated from their committed C bodies by
+    // `scripts/regen-switch-spelling-probes.ts`, each carrying a provenance header, and each pair
+    // two different objects: the `switch` emits both `beq`s before the first `sw`, while the ladder
+    // puts an arm's `sw` above the second test. A test asserts that split off every fixture. The
+    // two toolchains come out byte-identical on this body — measured, not assumed, and their
+    // declaration-rank probe objects differ, so a sibling pair is not a formality.
+    //
+    // BOTH TOOLCHAINS EMIT BRANCH-LIKELY on some bodies, and the reading survives it — a property
+    // of the pair, not a way the two diverge. `s32 m1(s32 x, s32 *p){ switch (x) { case 6: *p = 1;
+    // break; case 7: *p = 2; break; } return 0; }` cross-jumps the two stores into one and compiles
+    // instruction for instruction identically at -O1 and at -O2, to `beq` / `beql` with the shared
+    // `sw` after both; the same body as an if/else-if ladder puts the first arm's `li v0,1` BETWEEN
+    // the two tests. Both spellings get all the way through on both toolchains — the `switch` one
+    // recovers a `switch`, the ladder an `if` nest — so what keeps that body out of the fixture set
+    // is not a decline. It is that the cross-jumped arms leave no STORE to read the split off: both
+    // put their one `sw` after both tests, and the interleaved instruction is the ladder's
+    // `li v0,1`. The committed pair keeps its distinct-store arms for that reason. (A THREE-case
+    // body says the
+    // same more loudly, the balanced tree's `slti` bound test landing ahead of the bodies with the
+    // rest, but at three cases neither spelling reaches Regime A on this compiler, so that pair
+    // could not also serve as the recovery test.)
+    //
+    // WHAT IS WEAKER HERE THAN AT agbcc: this compiler HAS a scheduler and fills delay slots, and
+    // both fixtures show it — the ladder's `bne` carries the NEXT test's `li` in its slot. What the
+    // pair shows is that it moves no BODY above a test, which is the only claim the gate rests on,
+    // and the gate's failure direction (switch-recover.ts PRE5) is a lost `switch` spelling, never
+    // a wrong answer. A lost spelling is not always a clean ladder: recovery re-runs on the
+    // sub-trees a decline leaves, so a NESTED dispatch comes back as an `if` nest around a `switch`
+    // over some of its arms.
+    switchRequiresFrontLoadedTests: true,
+    // MEASURED on BOTH toolchains this description serves (the note above): one load of `p[1]` for
+    // every local spelling of the pair at the field, gcc2.7.2kmc at -O2 and gcc2.7.2 at -O1 alike.
+    reloadsLocalReread: false,
+    // MEASURED on BOTH toolchains this description serves: `int f(s8 x){return x;}` and
+    // `int f(s32 x){return (s8)x;}` compile to BYTE-IDENTICAL objects, gcc2.7.2kmc at -O2 and
+    // gcc2.7.2 at -O1 alike — so the object carries no witness at all and the pass refuses.
+    narrowParamWitness: 'none',
     // MEASURED `ascending` on both toolchains this description serves — 7 of 7 spills each, and
     // rank → offset unchanged under a reversed declaration list — and NOT SHIPPED, for the same
     // reason as ido7.1: no row on either tier lifts with two or more spilled user locals. Both
@@ -433,13 +615,22 @@ export const PPC_MWCC: TargetDescription = {
   argRegs: ['r3', 'r4', 'r5', 'r6', 'r7', 'r8', 'r9', 'r10'],
   returnReg: 'r3',
   capabilities: { endianness: 'big', hwDivide: true, hwFloat: true, flags: true },
-  // CodeWarrior's structuring levers are UNKNOWN until fixtures reveal them — safe universal
+  // CodeWarrior's structuring compiler behaviors are UNKNOWN until fixtures reveal them — safe universal
   // defaults; coalesceLoopInit false until a CW loop fixture says otherwise — the second of the
   // two compiler-wide guesses standing in for the per-function observation named at MIPS_GCC.
   compilerBehaviors: {
     coalesceLoopInit: false,
     preserveDivergentBranchSense: true,
     orderArgCopiesByWriteOrder: true,
+    // MEASURED — one load of `p[1]` for every local spelling of the pair at the field, the value
+    // held in a callee-saved register across the call. And the rule it turns off pays here:
+    // `u8 v = p[3]; if ((v & 0x7f) == 0x7f) { fnA(); p[4] = v; return; }` under an `if (a)`
+    // matches only once `read-behind-effect` stops refusing it (3/24 → MATCH 0/22).
+    reloadsLocalReread: false,
+    // The PowerPC prologue widens a declared narrow parameter with `extsb`/`extsh`, which the
+    // frontend lifts to the same `sext` op agbcc's shift pair folds to — the position shape, on
+    // another ISA. `synthetic:{sextb,tos8}:mwcc_242_81` are its rows, MATCH through that pass.
+    narrowParamWitness: 'prologue-extension',
     // NOT MEASURED, and `'unknown'` is therefore the only honest value here rather than a withheld
     // one, as it is at MIPS_IDO and MIPS_GCC. No mwcc row lifts with two or more spilled user
     // locals, and the compiler does not spill the committed declaration-rank probe either: at
@@ -451,9 +642,146 @@ export const PPC_MWCC: TargetDescription = {
   },
 };
 
+/** A toolchain: one compiler binary, named as decomp.me names it. Several toolchains may share a
+ *  description (`MIPS_GCC` serves two), and each keeps its own evidence. */
+export interface ToolchainTarget {
+  family: FlagFamily;
+  /** The codegen flags every committed probe of this toolchain was compiled with: the flags a
+   *  synthetic row compiles at, and the flags a decompile with none given assumes. They are in
+   *  normal form (`storedFlags` keeps every word), so the words only the harness needs (`-c`, the
+   *  diagnostics) live beside the binary's paths in @asmlift/toolchains.
+   *
+   *  A toolchain with no SYNTHETIC tier has NONE, and inventing one would be the fiction the field
+   *  exists to avoid: nothing about the compiler picks a set, every row names the flags its own
+   *  build compiles that unit with, and the probes behind its description are run at those. A
+   *  decompile that reaches such a toolchain with no flags from anywhere is refused rather than
+   *  resolved against a set nobody chose (`resolveFlags`). */
+  canonicalFlags?: readonly string[];
+  /** What this compiler does. Every flag set of the toolchain decompiles against it: a profile of a
+   *  compiler inherits its declarations until a probe refutes one there. */
+  description: TargetDescription;
+}
+
+export const TOOLCHAIN_TARGETS = {
+  agbcc: {
+    family: 'agbcc',
+    canonicalFlags: ['-mthumb-interwork', '-O2', '-fhex-asm', '-fprologue-bugfix'],
+    description: ARMV4T_AGBCC,
+  },
+  'ido7.1': {
+    family: 'ido',
+    canonicalFlags: ['-mips2', '-O2', '-32', '-non_shared', '-G', '0'],
+    description: MIPS_IDO,
+  },
+  'gcc2.7.2kmc': {
+    family: 'gcc',
+    canonicalFlags: [
+      '-mabi=32',
+      '-mgp32',
+      '-mfp32',
+      '-mno-abicalls',
+      '-fno-PIC',
+      '-G',
+      '0',
+      '-funsigned-char',
+      '-mips3',
+      '-EB',
+      '-O2',
+      '-fno-builtin',
+      '-fno-asm',
+    ],
+    description: MIPS_GCC,
+  },
+  'gcc2.7.2': {
+    family: 'gcc',
+    canonicalFlags: ['-G0', '-mips3', '-mgp32', '-mfp32', '-O1', '-Wa,--vr4300mul-off'],
+    description: MIPS_GCC,
+  },
+  mwcc_242_81: {
+    family: 'mwcc',
+    canonicalFlags: [
+      '-proc',
+      'gekko',
+      '-O4,p',
+      '-enum',
+      'int',
+      '-inline',
+      'auto',
+      '-fp',
+      'hard',
+      '-Cpp_exceptions',
+      'off',
+    ],
+    description: PPC_MWCC,
+  },
+  // The other two CodeWarrior builds the GameCube projects compile with: 2.3.3b163n (Pikmin's whole
+  // game tree) and 2.4.7b107 (Mario Party 4's DOL). Both SHARE `PPC_MWCC`, and on their own evidence
+  // rather than because they are the same compiler family: `test/matching/ppc-compiler-behaviors.test.ts`
+  // re-runs both of its probes on each binary at the flags that build's rows compile at, and each
+  // reads as the description says. What moves those readings is the optimisation level — at `-O0,p`
+  // the shipped `mwcc_242_81` re-reads the local too — so the difference is one no per-compiler
+  // field could carry anyway.
+  //
+  // NEITHER HAS CANONICAL FLAGS. They have no synthetic tier: every row of theirs is a real one that
+  // names its unit's own flags, and Pikmin's `-O4,p -lang=c++` and Mario Party 4's `-O0,p -lang=c`
+  // are two different sets, neither of which is "the" one. See `canonicalFlags` above.
+  mwcc_233_163n: {
+    family: 'mwcc',
+    description: PPC_MWCC,
+  },
+  mwcc_247_107: {
+    family: 'mwcc',
+    description: PPC_MWCC,
+  },
+} as const satisfies Readonly<Record<string, ToolchainTarget>>;
+
+export type ToolchainId = keyof typeof TOOLCHAIN_TARGETS;
+
+/** A toolchain that HAS canonical flags — every toolchain with a synthetic tier. Computed from the
+ *  registry, so the set cannot drift from it: a caller that needs a fallback flag set (the
+ *  playground's target picker, the benchmark's synthetic rows) takes this instead of `ToolchainId`
+ *  and a real-only toolchain is refused where it is named, not where it is used. */
+export type CanonicalToolchainId = {
+  [K in ToolchainId]: (typeof TOOLCHAIN_TARGETS)[K] extends { canonicalFlags: readonly string[] } ? K : never;
+}[ToolchainId];
+
+/** A toolchain's canonical flags, or `undefined` where it has none. The ONE place the optional
+ *  field is read: the registry's literal type says which entries carry it, and every caller that
+ *  holds a plain `ToolchainId` has to answer for the ones that do not. */
+export function canonicalFlagsOf(id: ToolchainId): readonly string[] | undefined {
+  const t: ToolchainTarget = TOOLCHAIN_TARGETS[id];
+  return t.canonicalFlags;
+}
+
+export function isCanonicalToolchainId(id: ToolchainId): id is CanonicalToolchainId {
+  return canonicalFlagsOf(id) !== undefined;
+}
+
+export function isToolchainId(id: string): id is ToolchainId {
+  return Object.hasOwn(TOOLCHAIN_TARGETS, id);
+}
+
+/** A toolchain at one flag set. */
+export interface ResolvedTarget {
+  toolchain: ToolchainId;
+  /** the flags the function's target and every candidate compile with */
+  cflags: readonly string[];
+  /** the description asmlift decompiles against: the toolchain's, at every flag set */
+  target: TargetDescription;
+  /** what the flags make the compiler do */
+  profile: CodegenProfile;
+}
+
+/** The target a function compiled by `toolchain` at `cflags` decompiles against, and the profile
+ *  those flags describe. Throws on a level word the toolchain's family cannot read. */
+export function targetFor(toolchain: ToolchainId, cflags: readonly string[]): ResolvedTarget {
+  const t: ToolchainTarget = TOOLCHAIN_TARGETS[toolchain];
+  return { toolchain, cflags, target: t.description, profile: parseFlags(t.family, cflags) };
+}
+
 /** Build the structurer's options for a target: the function's own `returnsVoid` plus every
- *  `compilerBehaviors` lever. The ONE place a target's compiler behaviors flow into the
- *  target-agnostic structurer — a new behavior lever is a field in `compilerBehaviors`, consumed
+ *  `compilerBehaviors` field. The ONE place a target's compiler behaviors flow into the
+ *  target-agnostic structurer — a new compiler behavior is a field in `compilerBehaviors`, consumed
  *  automatically.
  *
  *  The spread is over the WHOLE bag, so a behavior whose reader is not the structurer rides along
@@ -462,8 +790,9 @@ export const PPC_MWCC: TargetDescription = {
  *  are a SUPERSET of StructureOptions', not a bijection, and nothing may derive one from the other
  *  by enumerating keys. */
 export function structureOptionsFor(t: TargetDescription, returnsVoid: boolean): StructureOptions {
-  // `littleEndian` is the one HARDWARE capability the structurer consumes (bitfield extract
-  // recognition is LSB-first); everything else is a compiler behavior.
+  // `littleEndian` and `deviceRegisters` are the HARDWARE capabilities the structurer consumes
+  // (bitfield extract recognition is LSB-first; the dead-read spelling refuses outside the device
+  // window); everything else is a compiler behavior.
   //
   // ONE FIELD IS NOT A STRAIGHT SPREAD, and this is where the difference belongs. A frame
   // direction has THREE states here — `ascending`, `descending`, and `'unknown'` meaning measured
@@ -475,6 +804,7 @@ export function structureOptionsFor(t: TargetDescription, returnsVoid: boolean):
   return {
     returnsVoid,
     littleEndian: t.capabilities.endianness === 'little',
+    ...(t.capabilities.deviceRegisters ? { deviceRegisters: t.capabilities.deviceRegisters } : {}),
     ...behaviors,
     ...(spillSlotOrder === 'ascending' || spillSlotOrder === 'descending' ? { spillSlotOrder } : {}),
   };