@asmlift/core 0.7.0 → 0.8.0

package/src/target.ts

@@ -42,8 +42,13 @@
 // 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 field distinct from the ISA (matching = deoptimize to a specific
@@ -177,6 +182,32 @@ export interface TargetDescription {
     // 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
@@ -219,6 +250,25 @@ 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.
@@ -262,8 +312,8 @@ export interface TargetDescription {
     // 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
-    // TOOLCHAIN.agbccFlags the same two-case body is 20 bytes (0x14, ten Thumb instructions)
+    // 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`
@@ -313,15 +363,18 @@ export interface TargetDescription {
     // 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.
@@ -405,6 +458,7 @@ export const ARMV4T_AGBCC: TargetDescription = {
     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
@@ -413,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,
   },
 };
 
@@ -436,6 +493,11 @@ export const MIPS_IDO: TargetDescription = {
     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
@@ -502,9 +564,12 @@ export const MIPS_GCC: TargetDescription = {
     // 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. Same split — not committed as a fixture only because `beql` is an unmodelled
-    // control transfer, so the row declines before PRE5 and the cross-jumped arms leave no store to
-    // read the split off. Re-measure it the day branch-likely lands. (A THREE-case body says the
+    // 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.)
@@ -520,6 +585,10 @@ export const MIPS_GCC: TargetDescription = {
     // 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
@@ -558,6 +627,10 @@ export const PPC_MWCC: TargetDescription = {
     // `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
@@ -569,6 +642,143 @@ 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` 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

package/src/trace.ts

@@ -5,6 +5,7 @@
 // (objdiff score, per-pattern score deltas via the `probeScore` hook, ranked candidates) when a
 // target object is available; the web playground renders the TraceReport as-is.
 import { cBackend } from './backend/c';
+import type { CodegenProfile } from './codegen-flags';
 import type { AsmData } from './frontend/asmdata';
 import { frontendFor } from './frontend/registry';
 import type { Fn } from './ir/core';
@@ -16,7 +17,7 @@ import { type OnGap, raiseRecovered, structureChecked, stubResult } from './pipe
 import { type Prototypes, prototypesFromSymbols } from './proto';
 import { assumedShapes, inferGlobalArrays, orderLicensedGlobals } from './raise/globalshape';
 import { type SymbolInfo, type SymbolMap, symbolsByName } from './symbols';
-import { type TargetDescription, structureOptionsFor } from './target';
+import { type ResolvedTarget, type TargetDescription, type ToolchainId, structureOptionsFor } from './target';
 
 /** EVERY stage dump carries the write-order record (ir/print.ts `PrintOptions`) — not just
  *  `stage:lift`, even though only the frontend measures it. Two reasons: the raising folds MUTATE
@@ -50,6 +51,11 @@ export interface TraceReport {
   target: {
     isa: string;
     compiler: string;
+    toolchain: ToolchainId;
+    /** the flags the function was compiled with, in the build's order */
+    cflags: readonly string[];
+    /** what those flags make the compiler do */
+    profile: Pick<CodegenProfile, 'slots'>;
     capabilities: TargetDescription['capabilities'];
     compilerBehaviors: TargetDescription['compilerBehaviors'];
   };
@@ -118,19 +124,31 @@ const PRE_RECOVERY_TRACE: Record<string, { stage: string; title: (result: number
   'struct-arrays': { stage: 'stage:struct-arrays', title: () => 'Struct-array recovery (element stride evidence)' },
 };
 
+function reportTarget({ toolchain, cflags, target, profile }: ResolvedTarget): TraceReport['target'] {
+  return {
+    isa: target.id,
+    compiler: target.compiler,
+    toolchain,
+    cflags,
+    profile: { slots: profile.slots },
+    capabilities: target.capabilities,
+    compilerBehaviors: target.compilerBehaviors,
+  };
+}
+
 /** Run the tower while recording a TraceReport. Strict mode throws on any gap (like decompile);
  *  annotate mode never throws — a non-localizable failure degrades to the same stub. */
 export function decompileTraced(
   name: string,
   asm: string,
-  target: TargetDescription,
+  resolved: ResolvedTarget,
   opts: TraceOptions = {},
 ): { source: string; report: TraceReport } {
   if ((opts.onGap ?? 'strict') === 'strict') {
-    return traceTower(name, asm, target, opts);
+    return traceTower(name, asm, resolved, opts);
   }
   try {
-    return traceTower(name, asm, target, opts);
+    return traceTower(name, asm, resolved, opts);
   } catch (e) {
     // Annotate-mode parity with decompile(): a NON-localizable failure degrades to the SAME
     // stub (reason + original asm as comments) instead of a throw.
@@ -141,12 +159,7 @@ export function decompileTraced(
         version: 1,
         type: 'decompile',
         symbol: name,
-        target: {
-          isa: target.id,
-          compiler: target.compiler,
-          capabilities: target.capabilities,
-          compilerBehaviors: target.compilerBehaviors,
-        },
+        target: reportTarget(resolved),
         asm,
         trace: [],
         patternEvents: [],
@@ -161,9 +174,10 @@ export function decompileTraced(
 function traceTower(
   name: string,
   asm: string,
-  target: TargetDescription,
+  resolved: ResolvedTarget,
   opts: TraceOptions,
 ): { source: string; report: TraceReport } {
+  const { target } = resolved;
   const backend = opts.backend ?? cBackend;
   // Merged exactly as pipeline.ts does: the project's own DWARF signatures fill in what the caller
   // did not state. A trace that lifted from a different table would explain a run that never
@@ -207,7 +221,7 @@ function traceTower(
   let scoreBefore = opts.probeScore?.(fn, inferredSymbols);
   for (const p of active) {
     const beforeIr = irDump(fn);
-    const hits = applyPattern(fn, p);
+    const hits = applyPattern(fn, p, target);
     dce(fn);
     verify(fn);
     if (hits === 0) {
@@ -307,12 +321,7 @@ function traceTower(
       version: 1,
       type: 'decompile',
       symbol: name,
-      target: {
-        isa: target.id,
-        compiler: target.compiler,
-        capabilities: target.capabilities,
-        compilerBehaviors: target.compilerBehaviors,
-      },
+      target: reportTarget(resolved),
       asm,
       trace,
       patternEvents,

package/src/variation-definitions.ts

@@ -24,6 +24,8 @@
 //
 // Pure data: this module stays browser-safe. `offeredWhen` names admission tables by key; their rules
 // are `variation-gates.ts`, which a reader of a title or a summary never loads.
+import type { FlagFamily } from './codegen-flags';
+import type { CanonicalToolchainId } from './target';
 import type { GateTableName } from './variation-gates';
 import type { GatingBehavior, VariationKind, VariationName } from './variation-tokens';
 
@@ -105,8 +107,18 @@ export const VARIATION_KIND_DEFINITIONS: { readonly [K in VariationKind]: Variat
   },
 };
 
-/** A compiler an example is built with, as the benchmark's rows name it. */
-export type ExampleCompiler = 'agbcc' | 'ido' | 'gcc' | 'mwcc';
+/** A compiler an example is built with: a compiler family, as the benchmark's rows name it. */
+export type ExampleCompiler = FlagFamily;
+
+/** The toolchain each example compiler builds with. An example and a witness are claims at that
+ *  toolchain's canonical flags (`TOOLCHAIN_TARGETS`), which is what the matching suite compiles them
+ *  at — so the toolchain named here must be one that HAS them, which the type says. */
+export const EXAMPLE_COMPILER_TOOLCHAINS: { readonly [C in ExampleCompiler]: CanonicalToolchainId } = {
+  agbcc: 'agbcc',
+  ido: 'ido7.1',
+  gcc: 'gcc2.7.2kmc',
+  mwcc: 'mwcc_242_81',
+};
 
 /** Each example compiler as a reader knows it. */
 export const EXAMPLE_COMPILER_NAMES: { readonly [C in ExampleCompiler]: string } = {
@@ -1098,6 +1110,44 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     implementedIn: l3('scopebase'),
     seeAlso: ['scopebase', 'homesplit', 'vol-store'],
   },
+  argcopy: {
+    title: 'A pointer parameter copied for one region',
+    summary: 'a region copies an incoming pointer parameter into a local and uses the copy',
+    detail:
+      'A pointer parameter the whole function reads pins its incoming register for the whole body. A source ' +
+      'that copies it into a local at the head of the block that uses it gives the allocator a second name ' +
+      'for the same address, which it may home elsewhere — freeing the parameter register for something ' +
+      "else, such as that block's loop counter. Uses outside the chosen region keep naming the parameter, " +
+      'which is what makes the two ranges separable.',
+    compilerBehavior:
+      'A braced declaration inside the region and a plain local assigned at its head were both taken through ' +
+      'agbcc on the row this variation was built for and produced the same bytes, so the copy is emitted as ' +
+      'a plain local and nothing here carries block scope. The variation has no target gate, so it is offered ' +
+      'on every compiler — as /scopebase, /regionbase and /coalesce, which rest on the same allocator fact, ' +
+      'also are. A target gate would have to claim the copy is INERT on some compiler, the way /advance claims ' +
+      'it of a target that folds a pointer advance; nobody has compiled the pair that would say so, and a gate ' +
+      'withholding a candidate on an untested guess costs matches rather than fan.',
+    offeredWhen: {
+      judges: 'each pointer parameter, in each nested statement list that reads it',
+      gates: ['ARGCOPY_GATES', 'ARGCOPY_REGION_GATES'],
+    },
+    subject: {
+      meaning:
+        'The parameter, then the region that copies it, as a path of statement-index/list-index ' +
+        'PAIRS — one pair per nesting level. `argcopy-a0@0.1` copies `a0` at the head of the second ' +
+        'nested list of the first statement; `argcopy-a0@0.1.2.0` copies it in the first nested list ' +
+        'of the third statement of that one.',
+      examples: ['argcopy-a0@0.0', 'argcopy-a0@0.1', 'argcopy-a0@0.1.2.0'],
+    },
+    example: {
+      compiler: 'agbcc',
+      unit: CALLS + 'void example(u8 *a0, u8 a1, s32 c) { u8 *p0; s32 i; @ }',
+      before: 'if (c) { i = 0; do { if (g(a0 + i) != 0) a0[i + 50] = a1; i = i + 1; } while (i <= 3); }',
+      after: 'if (c) { p0 = a0; i = 0; do { if (g(p0 + i) != 0) p0[i + 50] = a1; i = i + 1; } while (i <= 3); }',
+    },
+    implementedIn: l3('argcopy'),
+    seeAlso: ['scopebase', 'regionbase', 'parkfirst', 'coalesce'],
+  },
   coalesce: {
     title: 'Two locals share one variable',
     summary: 'two locals whose lifetimes never overlap are merged into one',

package/src/variation-gates.ts

@@ -9,6 +9,7 @@
 // Kept apart from `variation-definitions.ts`, which stays pure data: that module takes only the
 // TYPE of a key, so a consumer reading a title or a summary does not load the passes.
 import { ADVANCE_HEAD_GATES, ADVANCE_MEMBER_GATES } from './l3/advance';
+import { ARGCOPY_GATES, ARGCOPY_REGION_GATES } from './l3/argcopy';
 import { BASEFOLD_GATES, LIVEBASE_BLOCK_GATES, LIVEBASE_GATES, ORDERBASE_GATES, UNFOLDED_GATES } from './l3/basecse';
 import { ARM_DISJOINT_GATES, COALESCE_GATES } from './l3/coalesce';
 import type { Gate } from './l3/gates';
@@ -42,6 +43,8 @@ export interface ReaderRule {
 export const VARIATION_GATE_TABLES = {
   ADVANCE_HEAD_GATES,
   ADVANCE_MEMBER_GATES,
+  ARGCOPY_GATES,
+  ARGCOPY_REGION_GATES,
   ARM_DISJOINT_GATES,
   ARM_REREAD_GATES,
   BASEFOLD_GATES,

package/src/variation-tokens.ts

@@ -123,6 +123,7 @@ const TOKENS = [
     target: { behavior: 'foldsPointerAdvance', declared: false, unlessWith: 'volatile' },
   },
   { name: 'parkfirst', variationKind: 'respell' },
+  { name: 'argcopy', variationKind: 'respell', subject: /[A-Za-z_]\w*@[\d.]+/ },
   { name: 'sinkinit', variationKind: 'respell' },
   { name: 'regcopy', variationKind: 'respell', subject: /ret|ret-fresh/ },
   { name: 'initfirst', variationKind: 'respell' },