@asmlift/core 0.8.0 → 0.9.0

package/src/runtime-helpers.ts

@@ -0,0 +1,287 @@
+// asmlift — the COMPILER RUNTIME HELPERS a target's codegen calls, and what each one computes.
+//
+// A compiler lowers an operation its ISA cannot do to a call into its own runtime: agbcc emits
+// `bl __divsi3` for `a / b` because ARMv4T has no divider, and `bl __muldi3` for a 64-bit multiply
+// because ARMv4T has no 64-bit anything. Two things are needed to recover either, and they are
+// different things:
+//   • the SIGNATURE, so the call's arguments are recovered at all (the frontend's arity lookup
+//     falls back to this behind any caller-supplied prototype);
+//   • the OPERATION, so the call is rewritten to the op it computes and the structurer prints
+//     `a / b` rather than `__divsi3(a, b)`.
+//
+// AN ENTRY HERE IS ALSO A REFUSAL. Where no recogniser folds a call to a name in this table,
+// `raise/widehelpers.ts` turns it into a gap instead of letting the backend spell it. Re-emitting
+// the compiler's own runtime call as source is not a recovery — it is the one shape that MATCHES
+// for free, because a compiler handed `__div2i(a, b)` emits the `bl __div2i` it was lifted from.
+// A helper nothing here can fold therefore declines; a helper nothing here NAMES still passes
+// through, which is what makes adding a name a decision rather than a note.
+//
+// WHICH HELPERS A COMPILER EMITS IS A COMPILER FACT, so the table hangs off `TargetDescription`
+// rather than off a pass. `proto.ts` holds signatures fixed by the C STANDARD, which a runtime
+// helper is precisely not — agbcc calls `__muldi3`, CodeWarrior calls `__div2i`, IDO calls
+// `__ll_mul`, and nothing about the C standard predicts any of them. A scan that assumes one
+// family reports ZERO on the others.
+//
+// `params` is a list of C parameter WIDTHS in bits, not a word count, and the difference is the
+// whole point of the field: `__ashrdi3` takes a 64-bit value and a 32-bit count — two C parameters
+// occupying THREE argument registers. A stated width is read two ways and both conversions live
+// here: `wordsOf` (proto.ts, because a C declaration asks the same question) counts the argument
+// REGISTERS the list occupies, and `irWidthOf` gives the IR width one parameter ARRIVES at once a
+// frontend has paired those registers up.
+import { type Op, type Value, mkOp } from './ir/core';
+import { FLOAT_OPS, type Opcode, WIDE_BITS } from './ir/opcodes';
+import { type IrType, intWidth } from './ir/types';
+import { type Prototypes, wordsOf } from './proto';
+
+export interface RuntimeHelper {
+  /** the op this helper computes, where asmlift has one. Absent for a helper it can only SIGN. */
+  op?: Opcode;
+  /** each C parameter's width in bits, in argument order. */
+  params: readonly number[];
+  /** the returned width: 0 (void), 32, or 64 (a register PAIR). */
+  returns: 0 | 32 | 64;
+}
+
+/** The entry a target's table holds for `callee`, or undefined. THE ONE READER, because the table
+ *  is an object literal and a C function may be named `toString`: a bare index or an `in` answers
+ *  with a member of `Object.prototype` for eight names, and what each caller then does with that
+ *  `Function` differs — one reads `params` off it and throws a TypeError, another refuses while
+ *  naming a runtime helper the target does not have. `Object.hasOwn` is stated here so that no
+ *  caller can be the one that forgot it. (`proto.ts` states the same rule for the prototype
+ *  tables, which are read the same way for the same reason.) */
+export function lookupHelper(
+  table: Readonly<Record<string, RuntimeHelper>> | undefined,
+  callee: string,
+): RuntimeHelper | undefined {
+  return table && Object.hasOwn(table, callee) ? table[callee] : undefined;
+}
+
+/** The IR width a C parameter of `bits` arrives at: one 64-bit value for anything wider than a
+ *  register, because a frontend that reads such a parameter fuses its registers into a single
+ *  value; a machine word for everything else, whatever narrower width the C type carries. The
+ *  counterpart of `wordsOf` — same threshold, different vocabulary. */
+export function irWidthOf(bits: number): number {
+  return bits > 32 ? WIDE_BITS : 32;
+}
+
+/** Whether a call ARRIVED in the shape this helper's signature states: one result at the returned
+ *  width, and each operand at the IR width its C parameter carries.
+ *
+ *  A COUNT IS NOT A WIDTH, and the gap between them is where a 64-bit operation gets invented over
+ *  two 32-bit words. Two ordinary shapes reach a fold with the right operand count and the wrong
+ *  contents: a call whose arity came off a caller-supplied prototype rather than off this table, so
+ *  no frontend ever built the pair; and a call on a target whose frontend does not pair registers
+ *  at all, where an argument register that is not live at the call gets trimmed and the survivors
+ *  happen to number what the table states. Either one folded publishes an operation over one half
+ *  of each value, at exit 0 and with no gap — so the pair construction IS the precondition, and a
+ *  shape that lacks it belongs to `refuseUnmodelledHelpers`.
+ *
+ *  AN OPERAND THAT CARRIES NO INTEGER WIDTH REFUSES, which is `intWidth` returning null for a
+ *  pointer or an aggregate. `ir/verify.ts` reads that same null as "does not take part in the width
+ *  rule"; here it means there is no width to check the claim against, and a fold may not proceed on
+ *  a claim it cannot check.
+ *
+ *  A `returns: 0` entry can never satisfy this, because no result carries width 0. A void helper
+ *  computing on a 64-bit value is a shape there is no operation to fold it into. */
+export function arrivesAsDeclared(
+  helper: RuntimeHelper,
+  operands: readonly IrType[],
+  results: readonly IrType[],
+): boolean {
+  if (results.length !== 1 || intWidth(results[0]) !== helper.returns) {
+    return false;
+  }
+  return (
+    operands.length === helper.params.length && operands.every((t, i) => intWidth(t) === irWidthOf(helper.params[i]))
+  );
+}
+
+/** Whether a helper computes on a value wider than a register — the ones the 64-bit representation
+ *  is for, and the ones no hardware capability can make unnecessary. */
+export function isWideHelper(h: RuntimeHelper): boolean {
+  return h.returns > 32 || h.params.some((w) => w > 32);
+}
+
+/** The op a recognised helper call is rewritten to, STAMPED with the helper it was: `helper` names
+ *  the callee. An integer helper's op takes the call's own operands and the SAME result value, so
+ *  every use already points at it; a float helper's takes them re-typed as floats
+ *  (`raise/floathelpers.ts`). `raise/softdiv.ts`, `raise/widehelpers.ts` and `raise/floathelpers.ts`
+ *  build every one through here.
+ *
+ *  The stamp carries the one fact the op's opcode loses: the asm CALLED something here. A
+ *  `sdiv` is a `divw` on mwcc and a `bl __divsi3` on agbcc, and an `shr_s` is a shift everywhere
+ *  but a `bl __ashrdi3` where it is 64-bit on agbcc — which ops a compiler calls a helper for is a
+ *  compiler fact, not an ISA one, and it was known exactly once, at the rewrite. What reads it is
+ *  every rule that places a call: a call runs once, where the asm ran it (ir/discipline.ts
+ *  `placedAt`), and a pass that moves the op elsewhere drops the stamp (`forgetHelperPlacement`). */
+export function helperOp(opcode: Opcode, helper: string, operands: readonly Value[], result: Value): Op {
+  return mkOp(opcode, { operands: [...operands], results: [result], attrs: { helper } });
+}
+
+/** Whether a helper computes on floats: its op is a float op, so its operands and result are floats
+ *  of the widths its signature states, carried in integer registers by a soft-float runtime. Every
+ *  reader of the table asks this and not the width, because the two families fold into different
+ *  IR: an integer helper into its op over the same values, a float helper into a float op over
+ *  values re-typed as floats (`raise/floathelpers.ts`). */
+export function isFloatHelper(h: RuntimeHelper): boolean {
+  return h.op !== undefined && FLOAT_OPS.has(h.op);
+}
+
+/** Signatures for a target's helpers, in the WORD arity the frontend's prototype lookup speaks.
+ *  Consumed behind any caller-supplied prototype — the project's own headers win. */
+export function helperPrototypes(table: Readonly<Record<string, RuntimeHelper>> | undefined): Prototypes {
+  return Object.fromEntries(Object.entries(table ?? {}).map(([sym, h]) => [sym, { params: wordsOf(h.params) }]));
+}
+
+/** agbcc's runtime, which is GCC 2.9's libgcc for ARM.
+ *
+ *  THE 64-BIT MULTIPLY IS SIGNEDNESS-BLIND, and that is a fact about this libgcc rather than a
+ *  simplification here: `optabs.c` initialises the only integer multiply libfunc from the MODE
+ *  alone, and `expmed.c` routes every `MULT` through it whatever the operands' signedness, so
+ *  `__umuldi3` does not exist and both spellings emit `bl __muldi3`. Signedness comes from the
+ *  operand SET-UP instead — `asr rN,rM,#31` per half for signed, `mov rN,#0` for unsigned. The
+ *  DIVISIONS do split, and their entries say so.
+ *
+ *  THE DOUBLE ARITHMETIC IS HERE, AND NOTHING ELSE OF THE SOFT FLOAT. `optabs.c:4022`
+ *  `init_floating_libfuncs` names DFmode's add, sub, mul, div (4129-4140) and neg (4155), and
+ *  `thumb.md` has no DF pattern but the move, so every one of them is a call; the ABI is a long
+ *  long's (thumb.h:632, 655). `raise/floathelpers.ts` folds them to the float ops over a `double`.
+ *
+ *  NAMING THEM IS A TRADE, and these five make it: a call the fold refuses declines where an
+ *  unnamed helper would publish as a pass-through that matches for free. So a function whose
+ *  double arithmetic feeds a compare (`__gtdf2`…), a conversion (`__fixdfsi`…) or any other call
+ *  declines, where unnamed it would print `__muldf3(); return __fixdfsi();`. The compares and
+ *  conversions of both precisions stay out, because the IR has no int<->float op to fold one into;
+ *  the single-precision arithmetic stays out because its pass-throughs are what the float rows
+ *  score on (`synthetic:fadd:agbcc`), and declining them is the same trade, to be made with a
+ *  measurement of those rows. Making it is a table row: the fold reads each value's width off the
+ *  signature. */
+export const AGBCC_RUNTIME_HELPERS: Readonly<Record<string, RuntimeHelper>> = {
+  // 32-bit software division — the ops `raise/softdiv.ts` rewrites, gated on the target having no
+  // hardware divider, which is what those four are about.
+  __divsi3: { op: 'sdiv', params: [32, 32], returns: 32 },
+  __udivsi3: { op: 'udiv', params: [32, 32], returns: 32 },
+  __modsi3: { op: 'smod', params: [32, 32], returns: 32 },
+  __umodsi3: { op: 'umod', params: [32, 32], returns: 32 },
+  // 64-bit arithmetic. NOT gated on a hardware capability: no ISA this repo targets has 64-bit
+  // integer arithmetic at all, so a call here is software on every one of them.
+  __muldi3: { op: 'mul', params: [64, 64], returns: 64 },
+  __divdi3: { op: 'sdiv', params: [64, 64], returns: 64 },
+  __udivdi3: { op: 'udiv', params: [64, 64], returns: 64 },
+  __moddi3: { op: 'smod', params: [64, 64], returns: 64 },
+  __umoddi3: { op: 'umod', params: [64, 64], returns: 64 },
+  __ashldi3: { op: 'shl', params: [64, 32], returns: 64 },
+  __ashrdi3: { op: 'shr_s', params: [64, 32], returns: 64 },
+  __lshrdi3: { op: 'shr_u', params: [64, 32], returns: 64 },
+  __negdi2: { op: 'neg', params: [64], returns: 64 },
+  // Double arithmetic, which the same pair carries (`raise/floathelpers.ts`).
+  __adddf3: { op: 'fadd', params: [64, 64], returns: 64 },
+  __subdf3: { op: 'fsub', params: [64, 64], returns: 64 },
+  __muldf3: { op: 'fmul', params: [64, 64], returns: 64 },
+  __divdf3: { op: 'fdiv', params: [64, 64], returns: 64 },
+  __negdf2: { op: 'fneg', params: [64], returns: 64 },
+};
+
+/** CodeWarrior's PowerPC runtime (`Runtime.PPCEABI.H`), as the GameCube projects vendor it.
+ *
+ *  A DIFFERENT FAMILY ENTIRELY, which is the reason this table is per target and not per repo: a
+ *  scan for `__*di3` reports zero on every one of these. These seven are the integer set, agreed
+ *  on by all three PPC checkouts' own vendored `runtime.c` (each at a different path), where every
+ *  one is an `ASM` function whose body states its register contract: `__div2i` takes r3:r4 and
+ *  r5:r6 and returns r3:r4, `__shl2i` takes r3:r4 and a count in r5.
+ *
+ *  ONE SHIFT LEFT AND TWO RIGHT, which is the same signedness rule agbcc's `__ashldi3` follows:
+ *  the bits a left shift brings in are zero whatever the operand is, so there is nothing for a
+ *  `__shl2u` to do differently.
+ *
+ *  NO MULTIPLY, and that is a fact about this compiler rather than a hole here: mwcc open-codes a
+ *  64-bit multiply. `synthetic:llmul:mwcc_242_81` is the evidence and it is in the corpus — its
+ *  target is 28 bytes of `mulhwu` and two `mullw` with no relocation at all, against 32 bytes and
+ *  an `R_PPC_REL24` to `__div2i` for `lldivs` beside it. The float and decimal helpers of the same
+ *  runtime (`__cvt_sll_flt`, `__num2dec`) are left out for the reason the agbcc table leaves out
+ *  its own.
+ *
+ *  ⚠ WHAT THIS TABLE DOES ON THIS TARGET TODAY IS REFUSE, and the `op` column is not reachable
+ *  from a lift. `frontend/ppc.ts` reads guessed argument registers and fuses none of them into a
+ *  pair, so no value on this target is ever 64 bits wide, so `arrivesAsDeclared` can never be
+ *  satisfied here and `recognizeWideHelpers` cannot fold. THAT absent pairing is the gate bounding
+ *  the path — not anything in this file, and not `refuseUnmodelledHelpers`, which is what these
+ *  names reach instead. The ops below are measured off the vendored `runtime.c` and asserted
+ *  directly by `runtime-helper-refusal.test.ts`, because a claim no lift can reach is a claim no
+ *  lift can check either; naming which operation each helper computes is the half of the frontend
+ *  work that is done. */
+export const PPC_MWCC_RUNTIME_HELPERS: Readonly<Record<string, RuntimeHelper>> = {
+  __div2i: { op: 'sdiv', params: [64, 64], returns: 64 },
+  __div2u: { op: 'udiv', params: [64, 64], returns: 64 },
+  __mod2i: { op: 'smod', params: [64, 64], returns: 64 },
+  __mod2u: { op: 'umod', params: [64, 64], returns: 64 },
+  __shl2i: { op: 'shl', params: [64, 32], returns: 64 },
+  __shr2i: { op: 'shr_s', params: [64, 32], returns: 64 },
+  __shr2u: { op: 'shr_u', params: [64, 32], returns: 64 },
+};
+
+/** IDO 7.1's runtime for the 64-bit operations MIPS II has no instruction for, a family of its own
+ *  (`__ll_*` for signed, `__ull_*` for unsigned): a scan for `__*di3` reports zero on it.
+ *
+ *  Compiled at `-mips2 -O2 -32 -non_shared -G 0` (compiled evidence only): `a * b` calls `__ll_mul`
+ *  for both signednesses, the divisions and remainders split, and a left shift is one helper while
+ *  the right shift splits. A SHIFT'S COUNT TRAVELS AS A PAIR: `a << n` with `int n` builds
+ *  `a2 = n >> 31, a3 = n` before `jal __ll_lshift`, so both parameters are 64 bits wide.
+ *
+ *  EVERY CONVERSION BETWEEN A 64-BIT INTEGER AND A FLOAT IS A CALL TOO, one per direction, precision
+ *  and signedness. The float side travels in the FPU's registers (`$f12` in, `$f0` out), so these
+ *  carry no op: a guessed call to one passes and returns nothing it can see.
+ *
+ *  SO IS A 64-BIT BITFIELD: a read hands the word's address, start bit and length to
+ *  `__ll_bit_extract` (`__ull_bit_extract` unsigned), and a write of either signedness calls
+ *  `__ll_bit_insert` with the value as a fourth parameter. No op folds either.
+ *
+ *  THE NAMES ARE THE COMPILER'S OWN: these are every `__ll_*`, `__ull_*` and `__*_to_*ll` that a pass
+ *  of IDO 7.1 carries in its string table (`cfe` carries them all). Its libc defines more
+ *  (`__ll_mod`, `__ull_divremi`, `__ull_divrem_*`), which no pass names, so no compiled code calls them.
+ *
+ *  ⚠ WHAT THIS TABLE DOES ON THIS TARGET IS REFUSE, as `PPC_MWCC_RUNTIME_HELPERS` does and for the
+ *  same reason: `frontend/mips.ts` fuses no register pair, so a call to one of these arrives with
+ *  word operands and `refuseUnmodelledHelpers` gaps it by name. */
+export const IDO_RUNTIME_HELPERS: Readonly<Record<string, RuntimeHelper>> = {
+  __ll_mul: { op: 'mul', params: [64, 64], returns: 64 },
+  __ll_div: { op: 'sdiv', params: [64, 64], returns: 64 },
+  __ull_div: { op: 'udiv', params: [64, 64], returns: 64 },
+  __ll_rem: { op: 'smod', params: [64, 64], returns: 64 },
+  __ull_rem: { op: 'umod', params: [64, 64], returns: 64 },
+  __ll_lshift: { op: 'shl', params: [64, 64], returns: 64 },
+  __ll_rshift: { op: 'shr_s', params: [64, 64], returns: 64 },
+  __ull_rshift: { op: 'shr_u', params: [64, 64], returns: 64 },
+  __ll_to_d: { params: [64], returns: 64 },
+  __ll_to_f: { params: [64], returns: 32 },
+  __ull_to_d: { params: [64], returns: 64 },
+  __ull_to_f: { params: [64], returns: 32 },
+  __d_to_ll: { params: [64], returns: 64 },
+  __f_to_ll: { params: [32], returns: 64 },
+  __d_to_ull: { params: [64], returns: 64 },
+  __f_to_ull: { params: [32], returns: 64 },
+  __ll_bit_extract: { params: [32, 32, 32], returns: 64 },
+  __ull_bit_extract: { params: [32, 32, 32], returns: 64 },
+  __ll_bit_insert: { params: [32, 32, 32, 64], returns: 64 },
+};
+
+/** GCC's libgcc for MIPS, as KMC GCC and GCC 2.7.2 call it at the N64 projects' `-mips3 -mgp32`
+ *  (compiled evidence only, both toolchains agreeing): the four divisions are calls, while a
+ *  64-bit multiply is `mult`/`multu` and a shift is open-coded, so neither has an entry. The
+ *  conversions between a 64-bit integer and a float are calls, with no `__floatundi*`: an unsigned
+ *  one converts as signed and corrects the result when `__cmpdi2` finds the value negative. The
+ *  conversions carry no op, for the reason `IDO_RUNTIME_HELPERS` gives. It refuses on this target
+ *  for that table's reason too. */
+export const MIPS_GCC_RUNTIME_HELPERS: Readonly<Record<string, RuntimeHelper>> = {
+  __divdi3: { op: 'sdiv', params: [64, 64], returns: 64 },
+  __udivdi3: { op: 'udiv', params: [64, 64], returns: 64 },
+  __moddi3: { op: 'smod', params: [64, 64], returns: 64 },
+  __umoddi3: { op: 'umod', params: [64, 64], returns: 64 },
+  __floatdidf: { params: [64], returns: 64 },
+  __floatdisf: { params: [64], returns: 32 },
+  __fixdfdi: { params: [64], returns: 64 },
+  __fixsfdi: { params: [32], returns: 64 },
+  __fixunsdfdi: { params: [64], returns: 64 },
+  __fixunssfdi: { params: [32], returns: 64 },
+  __cmpdi2: { params: [64, 64], returns: 32 },
+};

package/src/stillborn.ts

@@ -0,0 +1,289 @@
+// asmlift — THE STILLBORN FAN: when to stop compiling a fan that cannot compile.
+//
+// A fan is a product of variations over ONE function body, and every variation only re-spells
+// statements. When the body holds a statement the compiler refuses for a reason no variation
+// reaches — a call with more arguments than the project's header declares, a struct-typed global
+// read as a scalar — every candidate is refused for it, and the fan's size is the number of times
+// the same sentence gets printed: 30,240 on `kleod:PauseMenuScreenHandler`.
+//
+// THE RULE. The DEFAULT candidate (first in enumeration order) is compiled first. Only if the
+// compiler REJECTS it is anything else asked: a PROBE per variation name — the candidate with the
+// fewest variations that carries it, per signedness half (HALF BY HALF) — is compiled, and the fan
+// is stillborn only when the default holds an error that SURVIVES every probe: a message the probe
+// was rejected with too, exactly as many times as the default was (compiler-diagnostics.ts
+// `errorMessages`, positions normalised away). Then the remaining candidates are NOT COMPILED, and
+// are reported as exactly that.
+//
+// WHAT IT BETS ON: that a statement no probe re-spells is re-spelled by no product of the probes'
+// variations either, so its error is in every candidate. That is a bet, not a theorem — a product
+// is not the sum of its variations (THE RESIDUALS, below) — and the rule never compiles a product
+// to check it.
+//
+// One survivor is enough; the probes may reach the default's other errors. In
+// `ac-decomp:aINS_destruct:mwcc_242_81`'s vendored-context attempt `/setup-args` cures the call to
+// `mPlib_Get_item_net_catch_label`, both `illegal implicit conversion` errors stay, and the fan of
+// 12 stops after 8 compiles.
+//
+// EXACTLY as many times: a probe that prints the survivor more often has re-spelled a statement
+// that raises it (`/reread-globals` re-reading a global whose type is refused), and a probe that
+// prints it fewer times has cured one. Either one reached it, so neither vouches that a product
+// leaves it alone.
+//
+// PER ATTEMPT. A rejection may hold several compiles (compiler-diagnostics.ts `attemptsOf`: the
+// benchmark's real tier tries every candidate in a ladder of contexts and two dialects), and a
+// candidate compiles when ANY attempt does. So a survivor is asked of EACH attempt, and one attempt
+// without a survivor keeps the fan alive: an attempt no candidate can compile in — a context that
+// cannot open its own headers — prints the same sentences for every candidate, and those survive
+// every probe while another attempt's product compiles. Every probe must have been tried in the
+// same attempts, under the same labels, as the default.
+//
+// HALF BY HALF. Every fan is enumerated at BOTH signednesses (variation-tokens.ts, kind
+// `signedness`), and a signedness re-types the whole body, so the survivor is worded once per half:
+// aINS_destruct's `illegal implicit conversion` to `struct game_s *` names `unsigned long` in one
+// half and `long` in the other, and asked over the whole fan nothing in its vendored-context
+// attempt survives the `signed` probe. So each half is asked as a fan of its own — its first
+// candidate is its default, its probes are the smallest carrier of each variation name INSIDE it —
+// and the fan is stillborn only when every half is. A half is found by the registry's kind, never
+// by a name, and a fan with no signedness in its names is one half. A stopped fan pays both halves'
+// probes.
+//
+// KNOWN GAP: a variation that re-words the survivor in PART of the fan is not split on, so its
+// probe leaves that attempt without a survivor and the fan is ranked whole —
+// `kleod:WorldMapScreenUnlockNewWorld:agbcc`'s only vendored-context error, `incompatible types in
+// assignment`, reads `invalid operands to binary &` under `/derived-home` and `/setup-args`.
+//
+// Anything else ranks the whole fan. A probe that compiles or is withheld: the fan is alive. An
+// attempt with no survivor: a product of variations may cure what no single one does. An attempt
+// whose errors are not read — none recognised, or the compiler stopped reporting — or an attempt
+// list that differs from the default's: an unread sentence equals nothing. A throw that is not a
+// `CompilerRejection`: a timeout or a killed compiler says nothing about the candidate.
+//
+// THE RESIDUALS, which this rule does NOT close: a product that cures the survivor while every
+// probe keeps it. One survivor being enough, a stop may rest its whole bet on a single message in
+// the one attempt a candidate could compile in. Two shapes are known.
+//
+// JOINT CURE: ONE error MESSAGE that needs TWO variations together. `a & b` is `invalid operands
+// to binary &` while either operand is a struct; if one variation re-types `a` and another re-types
+// `b`, each probe leaves the message where it was, and only their product compiles. The same shape
+// arises without any re-typing wherever the compiler prints ONE message for a statement holding TWO
+// defects: mwcc and IDO report `y = g(1, 2) + h(3, 4)` as a single message, and agbcc, kmc and IDO
+// report an undeclared name once however many times it is used. Two DIFFERENT messages each cured
+// by its own variation are not this case: each probe removes its message, and neither survives.
+// Signedness re-types operands and can cure half a statement — against a declared
+// `CARDGetSectorSize(long, unsigned long *)`, `signed` turns a call's `(unsigned long, long *)` into
+// `(long, long *)`, one message either way — and HALF BY HALF is what closes it there: a half holds
+// its signedness fixed. Any OTHER variation that re-types an operand or cures half a statement
+// must revisit this rule.
+//
+// INTERACTION: a variation whose reach depends on another. A respell runs over whatever tree the
+// structure variations built, so a structure variation × respell product re-spells statements
+// neither of its probes touched: `/unmerge` copies a join's call into both arms only on the
+// `/flip-join` tree, so their product can print a message more often than the default and either
+// probe do. A product that moves a survivor UP keeps it an error; one that moved it to zero, leaving
+// no other error, would be a candidate that compiles and that the stop never compiles.
+//
+// ONE COPY. Probe selection and the verdict are pure functions over indices, so the sync driver
+// (rank.ts `rankBy`), the pooled CLI driver and the webapp's async loop all sequence their own
+// compiles and ask the same question. Every driver finishes the probe phase before compiling
+// anything else, which is what keeps the verdict independent of a scheduler.
+import { CompilerRejection, attemptsOf, verdictMessages } from './compiler-diagnostics';
+import { VARIATION_TOKENS } from './variation-tokens';
+
+/** What compiling one candidate came to, as far as this rule reads it. `compiled` covers scored
+ *  AND withheld: either way the compiler accepted the text. */
+export type ProbeOutcome = 'compiled' | { thrown: unknown };
+
+/** The signedness names, read off the registry by kind. */
+const SIGNEDNESS = new Set<string>(VARIATION_TOKENS.filter((t) => t.variationKind === 'signedness').map((t) => t.name));
+
+/** The fan's signedness HALVES: candidates grouped by the signedness their names carry, each in
+ *  enumeration order, the halves in the order of their first candidate. Index 0 opens the first. */
+function halvesOf(candidates: readonly { variations: readonly string[] }[]): number[][] {
+  const halves = new Map<string, number[]>();
+  candidates.forEach((c, i) => {
+    const key = c.variations.filter((v) => SIGNEDNESS.has(v)).join('/');
+    const half = halves.get(key);
+    if (half === undefined) {
+      halves.set(key, [i]);
+    } else {
+      half.push(i);
+    }
+  });
+  return [...halves.values()];
+}
+
+/** A half's probes: for every variation name in the half, the index of the candidate IN THE HALF
+ *  with the FEWEST variations that carries it, enumeration order breaking a tie. Ascending, and
+ *  without the half's own first candidate, which is its default.
+ *
+ *  A NAME is the whole part as the candidate carries it, subject included: `argcopy-a0@1.0` and
+ *  `argcopy-a0@2.0` are two probes, because each re-spells a different statement and the rule asks
+ *  whether ANY re-spelling reaches the failing one. Collapsing them to the registered name would
+ *  probe one region and answer for both. */
+function probesOf(candidates: readonly { variations: readonly string[] }[], half: readonly number[]): number[] {
+  const smallest = new Map<string, number>();
+  for (const i of half) {
+    for (const v of candidates[i].variations) {
+      const held = smallest.get(v);
+      if (held === undefined || candidates[i].variations.length < candidates[held].variations.length) {
+        smallest.set(v, i);
+      }
+    }
+  }
+  return [...new Set(smallest.values())].filter((i) => i !== half[0]).sort((a, b) => a - b);
+}
+
+/** The candidates to compile once the default was rejected: every half's default and probes
+ *  (`halvesOf`, `probesOf`). Ascending, and without the default itself. */
+export function probeIndices(candidates: readonly { variations: readonly string[] }[]): number[] {
+  const probes = new Set<number>();
+  for (const half of halvesOf(candidates)) {
+    for (const i of [half[0], ...probesOf(candidates, half)]) {
+      probes.add(i);
+    }
+  }
+  probes.delete(0);
+  return [...probes].sort((a, b) => a - b);
+}
+
+/** A fan declared stillborn. */
+export interface Stillborn {
+  /** each half's default's errors that survived every probe of that half, as the compiler worded
+   *  them in that half: a message named at the most times one attempt printed it */
+  messages: string[];
+  /** indices that WERE compiled — the default and the probes, ascending */
+  compiled: number[];
+  /** indices that were not, ascending: the rest of the fan */
+  notCompiled: number[];
+}
+
+/** A rejection read attempt by attempt: each attempt's label and the multiset of its error
+ *  messages. Null for anything the rule cannot read as a verdict — a compile, a throw that is no
+ *  `CompilerRejection`, or any attempt whose errors are unread. */
+interface Reading {
+  labels: string[];
+  errors: Map<string, number>[];
+}
+
+/** Whether a throw is the compiler REFUSING the text, read as the rule reads a probe: a
+ *  `CompilerRejection` whose every attempt prints an error the rule reads. Any other throw — a
+ *  killed compiler, a timeout — says nothing about the candidate, and neither does a rejection
+ *  that prints no such error: a Docker CLI that cannot reach its daemon exits 1, as a refusing
+ *  compiler does. Whatever checks the rule's bet by compiling a stopped fan's rest (the
+ *  benchmark's `bench fan --whole`) counts a refusal through this test, never a second one. */
+export const readableRefusal = (thrown: unknown): boolean => readingOf({ thrown }) !== null;
+
+function readingOf(outcome: ProbeOutcome): Reading | null {
+  if (outcome === 'compiled' || !(outcome.thrown instanceof CompilerRejection)) {
+    return null;
+  }
+  const attempts = attemptsOf(outcome.thrown.diagnostic);
+  const errors: Map<string, number>[] = [];
+  for (const attempt of attempts) {
+    const messages = verdictMessages(attempt.diagnostic);
+    if (messages === null) {
+      return null;
+    }
+    const tally = new Map<string, number>();
+    for (const m of messages) {
+      tally.set(m, (tally.get(m) ?? 0) + 1);
+    }
+    errors.push(tally);
+  }
+  return { labels: attempts.map((a) => a.label), errors };
+}
+
+/** The default's errors that survive `probes`, per attempt — null as soon as one attempt has none
+ *  left, or a probe cannot be read against the default. Asks `outcomeOf` for the probes in order
+ *  and for none past the first that ends it. */
+function survivors(
+  anchor: number,
+  probes: readonly number[],
+  outcomeOf: (index: number) => ProbeOutcome,
+): Map<string, number>[] | null {
+  const anchored = readingOf(outcomeOf(anchor));
+  if (anchored === null) {
+    return null;
+  }
+  const left = anchored.errors.map((tally) => new Map(tally));
+  for (const i of probes) {
+    const probe = readingOf(outcomeOf(i));
+    if (
+      probe === null ||
+      probe.labels.length !== anchored.labels.length ||
+      probe.labels.some((label, k) => label !== anchored.labels[k])
+    ) {
+      return null;
+    }
+    for (const [k, tally] of left.entries()) {
+      for (const [message, times] of tally) {
+        if (probe.errors[k].get(message) !== times) {
+          tally.delete(message);
+        }
+      }
+      if (tally.size === 0) {
+        return null;
+      }
+    }
+  }
+  return left;
+}
+
+/** The verdict over a fan whose default and probes have all been compiled — null for "rank the
+ *  whole fan", which is every case but one (the module header states the rule).
+ *
+ *  `outcomeOf` is asked for index 0 and then, only while the answer can still be "stillborn", for
+ *  the probes of its half in order, then for each further half's default and probes — so a
+ *  synchronous driver may compile on demand inside it and pays for no probe past the first that
+ *  ends it. It must answer whenever asked: a driver that skipped a
+ *  probe has not run the rule, and "stillborn" over the probes it happened to compile would be a
+ *  different, weaker rule. */
+export function stillbornVerdict(
+  candidates: readonly { variations: readonly string[] }[],
+  outcomeOf: (index: number) => ProbeOutcome | undefined,
+): Stillborn | null {
+  if (candidates.length === 0) {
+    return null;
+  }
+  const asked = (i: number): ProbeOutcome => {
+    const outcome = outcomeOf(i);
+    if (outcome === undefined) {
+      throw new Error(`internal: the stillborn verdict was asked before candidate ${i} was compiled`);
+    }
+    return outcome;
+  };
+  const perHalf: Map<string, number>[][] = [];
+  for (const half of halvesOf(candidates)) {
+    const left = survivors(half[0], probesOf(candidates, half), asked);
+    if (left === null) {
+      return null;
+    }
+    perHalf.push(left);
+  }
+  const compiled = [0, ...probeIndices(candidates)];
+  const tried = new Set(compiled);
+  return {
+    messages: namedOnce(perHalf.flat()),
+    compiled,
+    notCompiled: candidates.map((_, i) => i).filter((i) => !tried.has(i)),
+  };
+}
+
+/** Every half's and attempt's survivors as one list: a message in the order it first appears, as
+ *  many times as the attempt that printed it most. */
+function namedOnce(perAttempt: readonly Map<string, number>[]): string[] {
+  const most = new Map<string, number>();
+  for (const tally of perAttempt) {
+    for (const [message, times] of tally) {
+      most.set(message, Math.max(most.get(message) ?? 0, times));
+    }
+  }
+  return [...most].flatMap(([message, times]) => Array.from({ length: times }, () => message));
+}
+
+/** Whether a driver that has compiled ONLY the default should now compile the probes — i.e.
+ *  whether the default was rejected in a way the rule can read. A driver may skip this and compile
+ *  the probes regardless; asking first is what keeps an ordinary fan's compile order untouched. */
+export function defaultIsReadableRejection(outcome: ProbeOutcome): boolean {
+  return readingOf(outcome) !== null;
+}