BFM-decomp/docs/hand-matching-process.md

# Guided Hand-Matching — Process Guide & Phase-17 Findings

> **Created 2026-06-19 (Phase 17), mid-session, so the lessons survive a fresh session.**
> This is the replicable process for matching the struct-heavy shared-core residual by
> **Ghidra-driven hand-matching** — the approach that the Phase-17 demo proved works where the
> Phase-16 m2c+permuter brute-force topped out. Companion to `docs/matching-cookbook.md` (idiom
> catalog) and `docs/struct-core-pivot.md` (Phase-16 wall analysis). **Goal: make this so complete
> it can later be partly automated from the process itself.**

---

## 0. THE HEADLINE FINDING (go/no-go = GO)

**Phase 16 declared the loose-typing wall "fundamental / unfixable." This session disproves that for
the majority of functions.** The wall is really a **signature-CONSISTENCY problem**, and it dissolves
under **byte-neutral canonical-widening + the codebase's established cast idioms**.

**Demo close-rate: 4 of 5 sampled residuals reached a full whole-binary byte-match.**

| Function | m2c verdict | Result | Decisive fixes |
|---|---|---|---|
| `func_8012D3B4` | PERMUTER_CLASS (1-off) | ✅ CLOSED, **propagated ×134** | m2c ptr-vs-byte arithmetic; loose-typing: `RotTransPers` void→s32 widen + `(u16)D_800B9A02` cast |
| `func_8012832C` | STRUCTURAL_MISS (switch) | ✅ CLOSED (ov_SC01_077) | gcc reload s0-spill (restructure→rematerialize); branch polarity §T4; loose-typing: 3× void→s32 widen |
| `func_8015F89C` | MCOMPILE_fnptr-call | ✅ CLOSED (ov_SC01_077) | type the fn-ptr table (`void (*D_X[])(void*)`); arity conflict `func_80161208` via the **cast idiom** `((s32(*)(void*))f)(arg)`; canonical-sig-match the callees |
| `func_80147B5C` | STRUCTURAL_MISS (pure struct) | ✅ CLOSED (ov_SC01_077) | **canonical-sig-match the fn's own param** (`s32 a0` per canonical, cast to ptr in body); raw offset casts. *match_one MATCH first try.* |
| `func_8012A328` | STRUCTURAL_MISS (globals+call) | ⚠️ 60/60 structure + correct regs, **1 instr off** | gcc GCSE/reload placement quirk (per-block rematerialize vs hoist) — the §10 hard tail; permuter floor-polluted, can't help |

**Every function reached *isolated* correctness (match_one MATCH or 60/60).** What separated the
closes from the miss was the **whole-binary** step: the closes' blockers were *loose-typing /
signature-consistency conflicts* (deterministically fixable — see §3a), the miss's blocker a *gcc
placement quirk* (the genuine, minority hard tail). **The fnptr-call class (§15-S2, 85 fns) and the
pure-struct class are matchable; even the §14e "arity wall" is partly breakable via the cast idiom.**

---

## 1. THE LOOP (the replicable process)

For one residual function `func_<ADDR>` in the harvest source `ov_SC01_077`:

1. **Richest decompile — use BOTH:**
   - **Ghidra whole-binary** `get_code(0x<ADDR>, decompiler)` — resolves locals vs **globals** vs
     **callee identities** (whole-program view m2c lacks). The MCP server must serve the overlay
     (`tools/ghidra_mcp_start.sh ov_SC01_077`, then `/mcp`, R29). get_code is async → poll
     `get_task_status`.
   - **m2c** `tools/m2c/m2c.py -t mipsel-gcc-c -f func_<ADDR> --context .run/actor_ctx2.c <s>` — a
     per-function scaffold (decompile.py hardcodes the main-EXE path; call m2c directly for overlays).
   - **The ASM is the final arbiter** for addressing + exact codegen (m2c and Ghidra often *disagree*
     on local/global modeling — e.g. `func_8012A328`: m2c made `D_80126B58` a struct, Ghidra made the
     same bytes separate globals; the asm's `lui $s1` reuse settled it).

2. **Hand-write correct C** — fix m2c's structural/arithmetic errors with Ghidra's structure + the
   actor struct (`docs/actor-struct.md`) + the cookbook idioms (§below).

3. **Iterate isolated** with `tools/match_one.py func_<ADDR> --c <draft> --asm-subdir
   asm/ov_SC01_077/nonmatchings/ov_SC01_077` (fast, relocation-masked; prints per-instruction diff).
   Drive to `MATCH (N ins)`.

4. **Resolve loose-typing for the whole binary** (THE step Phase 16 missed):
   - **Canonical-widening:** a callee declared `void` by a prior harvest (because *that* caller
     ignored its `$v0` return) but *this* function uses the return → widen the canonical to `s32`.
     **Byte-neutral** (a function with no explicit `return` compiles identically as `void` or `s32`).
     Edit the single `extern void func_X` in `src/shared/engine_core.h` (or the inline def in the
     overlay `.c`) to `extern s32 func_X`.
   - **Cast idiom:** keep the canonical `s16`, write `(u16)D_X` at unsigned use-sites (the asm `lhu`).
     This is the codebase's own established pattern (e.g. engine_core.h `(u16)D_800B9A02 * 20`).
   - **Match existing canonical sigs** for every callee/global from `engine_core.h` (grep it) so the
     one-big-TU `ov_SC01_077.c` has no conflicting declarations.

5. **Whole-binary gate (THE arbiter, G3/P9):** `tools/harvest_verify.py --binary ov_SC01_077 --src
   src/ov_SC01_077/ov_SC01_077.c --asm-subdir asm/ov_SC01_077/nonmatchings/ov_SC01_077 --out
   build/ov_SC01_077/ov_SC01_077 --good-sha d19c9580a02dc63ba1f0e7e0c770f3b10de35635 --drafts <dir>`.
   It substitutes the draft, builds the whole overlay, keeps it iff SHA == d19c9580 (else reverts).
   **CRUX: match_one MATCH ≠ whole-binary match** — match_one masks `jal`/`%hi`/`%lo`, so it can't see
   callee-signature conflicts. The build is the only truth.

6. **Propagate ×134:** `tools/dedup_propagate.py --addr 0x<ADDR> --source-overlay ov_SC01_077` (byte-
   gates every overlay, fail-closed; authors a `DEFINE_func_<ADDR>` macro in engine_core.h, registers
   the group in `config/dedup.us.yaml`). Then `make check-all` → 136/136 (R22).

To diagnose a whole-binary FAIL: substitute the draft into a `.c` copy, `make build BINARY=ov_SC01_077
2>&1 | grep -iE 'conflicting|redefin|error'`, read the conflict lines, fix the sig, revert.

---

## 2. IDIOMS & FIXES discovered this session (fold into cookbook §1/§2/§16)

- **m2c pointer-vs-byte arithmetic (HIGH-frequency m2c bug).** m2c writes `&D_X + (i * K)` using
  `s32*` pointer arithmetic (scales ×4), where the target indexes by **bytes**. Tell: a shift off by
  ×4 (e.g. `sll v0,0x4` vs `sll v0,2`). Fix: `*(s32 *)((s8 *)&D_X + (i * K))`. (`func_8012D3B4`.)
- **Branch polarity (§T4 restated).** A lone `beqz↔bnez` flip with swapped successors = put the
  target's **fall-through** block in the `if`, the branched-to block in the `else`. m2c's `== 0` form
  was right; "improving" it to `!= 0` + swapped arms broke it. (`func_8012832C`.)
- **gcc reload rematerialization vs callee-saved spill.** A cheap constant (`v0 = 1`) held **live
  across a call** makes gcc spill it to a callee-saved reg (`s0`, +frame). The original instead
  **rematerializes** the constant at each exit. Fix: restructure so the constant is set in the
  *else* / at the exits, not before the call (`if (cond && call()==0) v0=f(); else v0=1;`).
  (`func_8012832C`.)
- **Cross-jump call structure.** To get a single shared `jal` with **per-branch arg setup**
  (a0/a2 duplicated, only a1 differing), write the call **inside each branch**, converging via gotos
  to a shared tail; gcc cross-jumps the identical `jal`+tail. One call site → gcc hoists (too few
  ins); 4+ → gcc under-merges (too many); exactly the shared-block count matches. (`func_8012A328`.)
- **Dual base pointers.** A global loaded once into a callee-saved reg and reused at several offsets
  (`lui $s1,D_X` then `lh 0xNN($s1)`) = model it as a pointer variable `u8 *p = D_X;` referenced
  across the call. Two such bases → two callee-saved regs (s0/s1); their allocation order follows
  first-use order. (`func_8012A328`.)
- **s32 vs s16 for sign-extended values passed to calls.** A value loaded `lh` (sign-extended to 32)
  and passed to a function wants the local + the param typed `s32`, not `s16` — `s16` adds a
  redundant `sll/sra` re-extension. (`func_8012A328`.)
- **THE HARD RESIDUAL (the §10 minority tail):** **per-block address rematerialization vs hoist.** The
  original re-materializes a global's address (`lui+addiu` into a callee-saved reg) **per block**
  while sharing the post-call store; gcc from clean C either hoists it once (1 ins short, store
  merged) or makes the store per-block (over by N). The exact midpoint is a gcc GCSE/reload balance
  not cleanly source-steerable, and the **permuter can't score it** (object score floor-polluted by
  the masked global/call symbols, cookbook §10). 1 instruction, genuinely hard. (`func_8012A328` —
  best draft `.run/demo/func_8012A328.c`, the `p+q` form 61 vs 60.)
- **`lh`-vs-`lhu` fold defeat — the mask-local idiom (NEW, func_8014C308).** When the asm loads a signed
  field (`lh`) and ANDs it with a runtime mask `(x & 0xFFFF)`, writing `*(s16 *)f & (x & 0xFFFF)` **inline**
  lets gcc prove the result fits 16 bits → it folds the load to `lhu` and drops the separate `andi`. FIX:
  hoist the mask to a local — `s32 m = x & 0xFFFF; ... *(s16 *)f & m ...`. gcc can no longer prove `m ≤
  0xFFFF` at the AND, so it keeps `lh` + emits `andi m` then `and`. (Turned `lhu`+`and a3` into the target's
  `lh`+`andi v1`+`and`.)
- **Shared-return cross-jump clustering + branch-polarity control (NEW, func_8014C308).** When the original
  routes two (non-adjacent) predicate tests to ONE shared `return 0` block — so each test's branch-delay slot
  is free to hold the *next* test's constant and the tests branch with a particular polarity (`beq`/`bnez`
  *to* the shared block) — write BOTH as `goto ret0;` to a single trailing `ret0: return 0;`. gcc then makes
  `ret0` a labeled block reached by branches (correct polarity) and schedules the following test's constant
  into the delay slot — reproducing the original's clustering AND its register assignment (constants in the
  non-result reg). A lone `if (x) return 0;` instead **inlines** the return (`beqz`-skip, inverted polarity,
  constant lands in the result reg) → cascade. This fixed func_8014C308's idx 0–21 in one move; what remained
  was a pure v0↔v1 coalescing choice (permuter territory).
- **v0↔v1 result/constant coalescing (the residual after the above).** When a `result` default (`var = 1`)
  competes with a sequential `beq`-chain's constants for the return reg, gcc may put the constants in `v0` and
  the result in `v1` (extra `move v0,v1`), vs the target's result-in-`v0`/constants-in-`v1`. Not reliably
  source-steerable (tried: var-at-top → worse/`t0`; early-return → polarity issues). For a **relocs=0**
  function this is a CLEAN permuter target (no masked-symbol floor) — unlike the §10 call-heavy tail.
  (func_8014C308, ×134.)

---

## 3. LOOSE-TYPING CONFLICTS catalog (this session — all byte-neutral, fleet re-verified 136/136)

| Symbol | Was | Now | Where | Why |
|---|---|---|---|---|
| `RotTransPers` | `void` | `s32` | engine_core.h `DEFINE_func_8017C908` | func_8012D3B4 uses its return |
| `func_80029504` | `void` | `s32` | engine_core.h `DEFINE_func_80159120` | func_8012832C uses its return |
| `func_801288B0` | `void` | `s32` | ov_SC01_077.c inline def | func_8012832C uses its return |
| `func_801289F0` | `void` | `s32` | ov_SC01_077.c inline def | func_8012832C uses its return |
| `D_800B9A02` | `s16` (kept) | `(u16)` cast at use | func_8012D3B4 body | asm loads `lhu` |
| `func_80161208` | `s32 (void)` (kept) | cast at 1-arg call | func_8015F89C call | called 0-arg elsewhere, 1-arg (ptr) here |
| `func_801466F0` / `func_80147078` | — | match canonical sig in the draft | func_8015F89C decls | callee param types (s32/s32*/s16) |
| `func_80147B5C` (the fn itself) | `void(s32,void*)` canonical | declare param `s32`, cast in body | func_80147B5C def | callers pass the address as `s32` |

### §3a — THE SIGNATURE-CONSISTENCY RESOLUTION PLAYBOOK (the wall-breaker)

The Phase-16 "loose-typing wall" is really: *the same symbol is declared/used with different types
across the single overlay TU.* `match_one` (standalone) never sees it; the whole-binary build does.
**Five deterministic moves resolve almost all of it** (apply whichever the conflict needs):

1. **Return-widening (`void`→`s32`).** A callee declared `void` (a prior harvest ignored its `$v0`)
   but THIS fn uses the return → widen its canonical to `s32`. **Byte-neutral** (no explicit `return`
   ⇒ identical epilogue). Edit the single `extern void func_X` in engine_core.h / the overlay def.
2. **Sign cast (`(u16)`/`(s16)`).** Keep the canonical (`s16`); write `(u16)D_X` where the asm loads
   `lhu`. The codebase's own idiom.
3. **Arity cast** — *refines the §14e "arity wall = dead-end".* A callee called 0-arg by one fn and
   N-arg by another: keep the canonical `(void)`, and at the N-arg site **cast** —
   `((ret (*)(argtypes))func_X)(args)`. The codebase already does this (`((s32(*)(s32*))func_80161208)`).
   Works when the extra args are **pointers** (no default promotion); narrow-scalar arity is still hard.
4. **Param-type canonical-matching.** Declare every callee (and the fn's OWN params) with the EXACT
   canonical signature from engine_core.h (grep it), then cast inside the body. E.g. the canonical
   `func_80147B5C(s32 a0, void *a1)` passes an address as `s32` → write `void func_80147B5C(s32 arg0,
   void *arg1)` and access `*(s32 *)(arg0 + 0xNN)` (cast int→ptr, byte-neutral).
5. **Fn-ptr-table typing.** A `(*((idx*4)+D_x))(args)` call needs `D_x` typed as a function-pointer
   array — `extern void (*D_x[])(argtypes);` (engine_core.h often already has it) → m2c/hand C compiles
   and matches (`func_8015F89C`: `D_801891B8[arg0->f_0](arg0)`).

**Diagnosis loop:** `harvest_verify` FAIL → substitute into a `.c` copy → `make build BINARY=ov_SC01_077
2>&1 | grep -iE 'conflicting|redefin'` → each line names a symbol; `grep` its canonical in
engine_core.h → apply move 1–5 → revert the copy, re-gate. (Moves 1–4 are the bulk; func_8012D3B4 +
func_8012832C + func_8015F89C + func_80147B5C all closed this way.)

---

## 4. CURRENT STATE (what's banked / modified this session — do not redo)

- **BANKED matches (all in ov_SC01_077, byte-gated):** `func_8012D3B4` (propagated **×134** →
  `DEFINE_func_8012D3B4` in engine_core.h + `config/dedup.us.yaml`, 134 members); `func_8012832C`,
  `func_8015F89C`, `func_80147B5C` (inline in `ov_SC01_077.c`, not yet propagated — propagating
  func_8012832C/8015F89C would cascade their callee widenings across overlays; func_8015F89C reach is
  only ~3 anyway; func_80147B5C reaches 134). **5 sampled, 4 closed (80%).**
- **WIDENINGS in place (byte-neutral):** see §3 table.
- **NOT closed:** `func_8012A328` (60/60 structure + correct regs, 1-instr gcc quirk). Drafts +
  variants in `.run/demo/` (`func_8012A328.c` = best `p+q`; `v_*.c` = the experiments). `func_801298F4`
  also set aside (a walking-pointer codegen quirk — gcc strength-reduces `*q++` to indexed; the
  original keeps the walk; structure-confirmed by m2c+Ghidra).
- **Fleet:** `make check-all` → **136/136 byte-identical**; `make report` → **55.04%** (was 55.00% at
  this session's start, 54.48% at phase start); `dedup-check` 1409 validated / 0 failed.
- **Scratch:** all drafts under `.run/demo/`. Permuter setup at `.run/permuter/func_8012A328/` (base
  score 1680, floor-polluted — abandoned).

### Session 3 (2026-06-19, normal Max session) — "sample 2 more to firm the rate"
Sampled 1 fnptr + several struct residuals via the §1 loop. **Headline: the loop reconstructs CORRECT
bodies every time (4/4 this session), but the byte-CLOSE on the struct tail is gcc-codegen-quirk-bound, and
candidate sub-class matters more than expected.**
- **BANKED (clean whole-binary close):** `func_8015F9A4` (fnptr-call, reach ×1, inline in `ov_SC01_077.c`)
  — a near-clone of the demo's `func_8015F89C` (same `D_801891B8[arg0->f0](arg0)` table + `func_80161208`
  arity-cast). **fnptr-call class confirmed reliably closeable (2/2 with the demo).**
- **STRUCTURALLY PERFECT, blocked by regalloc — `func_8014C308`** (struct predicate, **relocs=0, reach ×134**):
  body matches; down to a pure v0↔v1 constant/result coalescing swap. Hand-fixes got it from 15→~3 mismatches
  (mask-local idiom + shared-ret0 goto, §2); the residual is a clean **permuter** target (no masked-symbol
  floor). Permuter converging (455→210→140). Drafts: `.run/demo/func_8014C308.c` (+ `_v2`/`_v3` experiments);
  permuter `.run/permuter/func_8014C308/`.
- **NEAR-MISS, ×134, §10 tail — `func_80130AF0`** (struct dispatch, reach ×134): body 100% correct, blocked
  by the §10 per-block `a0` rematerialization / `jal`-delay-slot quirk (call-heavy → permuter floor-polluted).
  Draft `.run/demo/func_80130AF0.c`.
- **NEAR-MISS, ×1 — `func_8016B4F8`** (struct init, reach ×1): body 100% correct, phantom +0x8 -O2 frame
  (cookbook §5 phantom-frame; -O2 variant, not the -O0 reserved-local fix). Draft `.run/demo/func_8016B4F8.c`.
- **SELECTION LESSON:** sorting `STRUCTURAL_MISS` by *ascending* m2c-mismatch biases toward the gcc-quirk
  tail (m2c already nailed the structure → only a codegen quirk remains). Clean closes come from **fnptr-call**,
  **relocs=0 / few-call**, and **m2c-mis-structured-but-fixable** functions. Low-mismatch call-heavy = hard tail.

---

## 5. TOWARD PROGRAMMATIC AUTOMATION (the end goal)

Steps ranked by how mechanizable they are:
1. **Canonical-widening — FULLY automatable.** Scan: for each function declared `void` whose body has
   no explicit `return`, find any call site that *uses* its result (assigns/tests `$v0`) → widen its
   canonical to `s32` everywhere (engine_core.h + overlay defs), gate the fleet byte-neutral. This is
   the **first tool to build** (task 6). It dissolves the dominant blocker pre-harvest.
2. **The cast idiom — mechanical.** `(u16)`/`(s16)` at use-sites per the asm load (`lhu`/`lh`); a
   draft-rewriter can apply it.
3. **m2c arithmetic/polarity fixes — partly mechanical.** The ptr-vs-byte ×4 tell and the branch-
   polarity flip are detectable from the match_one diff; a "fix-suggester" could propose them.
4. **The gcc-quirk tail — NOT automatable cheaply.** Stays manual / permuter (when scorable) / honest
   stub. It's a minority; don't let it block the bulk.

The dream: `gen_harvest_targets` (already callee-sig-aware) + an auto-widening pre-pass + m2c +
diff-driven fix-suggestions → a mostly-automatic loop, with the gcc-quirk tail flagged for humans.

---

## 6. PLAN FORWARD — REVISED 2026-06-19 (session 3) after sizing + the permuter refutation

**Original sequence** (sample → giant → harvest) is superseded. After firming the rate (§4 session 3),
Drew chose **"harvest tractable classes first; giant DEFERRED"** (option A). Then the sizing below changed
the calculus again.

### Harvest opportunity sizing (2026-06-19, reach-weighted; fleet denom = 344,010 instances, 55.04% done)
Per residual bucket (still-stub fns in ov_SC01_077), count / sum-of-reach / %fleet-if-all-matched:

| Class | count | reach | %fleet | tractability |
|---|---|---|---|---|
| `MCOMPILE_fnptr-call` | 83 | 355 | 0.1% | reliably HAND-closeable, but **low reach** (overlay-specific tables) |
| `VOID_VALUE_MISUSE` (widening) | 17 | 1081 | 0.3% | deterministic (canonical-widening) |
| `SIG_FIXABLE_KR` | 4 | 536 | 0.2% | deterministic (sig_unify, mostly done T3) |
| `STRUCTURAL_MISS` | 366 | 26,304 | **7.6%** | HIGH yield, but quirk-heavy; only the m2c-mis-structured-fixable + relocs≤2 subset is tractable |
| `PERMUTER_CLASS` | 145 | 12,263 | **3.6%** | 1-4 mismatch near-misses |
| (call-heavy `relocs 6+` across the above) | 275 | 18,113 | 5.3% | the §10 tail — DEFER as stubs |

**The reach (×134 leverage) is concentrated in the core shared engine functions, which are exactly the
quirk-prone STRUCTURAL_MISS/PERMUTER_CLASS** — NOT the easy fnptr/void classes (those are low-reach).

### The permuter route is largely REFUTED (T6 + session-3 `func_8014C308`)
- **relocs≥1:** T6 proved isolated-permuter wins do NOT transfer to the whole binary (callee inlining in the
  one-big-file TU differs) → ~0 whole-binary yield. The relocs 1-2 band (2.15%) is subject to this.
- **relocs==0** (only 11 fns / 0.39%): permuter-faithful BUT slow — `func_8014C308` (relocs=0, structurally
  perfect, 1 v0↔v1 swap) did NOT close in ~12 min across two runs (best score 140). Needs PERM_ hints.
- ⇒ The permuter is NOT the bulk lever. The yield lever is **guided HAND-matching** (the §1 loop + the §2/§3a
  idioms), which is **breadth** (many independent high-reach fns) → an **Ultracode wave** (R26).

### Revised plan
1. **Ultracode guided-hand-matching wave** over the high-reach **tractable** subset: m2c-mis-structured-fixable
   STRUCTURAL_MISS + fnptr-call + sig/widening-fixable. Agents apply the §1 loop + §2/§3a idioms (mask-local,
   shared-ret0 goto, cast/widening, fnptr-table typing), iterate with `match_one`, gate **whole-binary**
   (`harvest_verify.py`, the sole arbiter), propagate ×reach (`dedup_propagate.py`). The gcc-quirk tail FAILS
   the gate (correctly, G3) → stays an `INCLUDE_ASM` stub (NO NON_MATCHING correct-C track — Drew, A-only,
   until public). Measure the real fleet-% delta. Expected ~2-4% (bounded by the quirk tail).
2. **canonical-widening** folded into the agent playbook (§3a move 1) — a standalone tool is low direct yield
   (0.3%); build it only if sig-conflicts prove a major agent bottleneck.
3. **Document** idioms as they emerge (R16); **giant `func_80144B9C` deferred** (reassess after the wave yield).
4. **T7 go/no-go close + PhaseEnd** once the wave yield is measured.

---

## 7. THE ULTRACODE HARVEST WAVE + THE CANONICAL-SIG WALL (session 3, 2026-06-19 — PROVEN)

The guided-hand-matching loop (§1) **scales via an Ultracode Workflow** (R26). First calibration wave run &
measured; this section is the operational record + the singular bottleneck it exposed.

### 7a. The wave pipeline (reusable)
1. **Ghidra pre-pass (headless batch, NO /mcp):** stop MCP (`tools/ghidra_mcp_stop.sh`), then
   `analyzeHeadless ghidra bfm -process ov_SC01_077 -noanalysis -postScript DecompileFunctions.java
   <addr-list> <out-dir>` → whole-program Ghidra-C to `.run/ghidra_c/func_<ADDR>.c` (rename `FUN_<lower>.c`
   → `func_<UPPER>.c`). Ghidra-C resolves locals-vs-globals-vs-callee better than m2c — agents read the cache
   (no live-MCP contention). `ov_SC01_077` is Ghidra program `00000004` (Phase-13 import).
2. **Draft (Ultracode `parallel`):** `.run/harvest_wave_s3.js` — one agent per target; each reads
   asm+Ghidra-C+m2c+actor-struct+§1/§2/§3a, hand-writes C, iterates `match_one`, writes
   `.run/drafts-s3/<fn>.c` ONLY on MATCH (stop-rule on gcc-quirks → report DIFF, no draft). **GOTCHA: the
   Workflow `args` channel does NOT transit arrays — EMBED the targets as a literal in the script + a `LIMIT`
   const.** Agents also drop scratch (`_try`/`_v2`) in the dir → filter to canonical `func_<ADDR>.c` before gating.
3. **Whole-binary gate:** `harvest_verify.py --drafts <dir> --chunk 1`. **Use `--chunk 1`** — the default
   batched chunk+bisect can drop a GOOD draft because it cross-conflicts with ANOTHER draft in the same chunk
   (shared-callee sig clash), not because it's wrong.
4. **Recover:** `sig_unify.py --in <failed-drafts> --out <fixed>` then re-gate (recovered 2/9 in calibration).
5. **Propagate:** `dedup_propagate.py --auto-from ov_SC01_077` (×reach; also catches up any inline-but-
   unpropagated prior matches). `make check-all` (R22) + `make report`.

### 7b. Calibration result (top-30 by reach, ~1.89M tokens)
- **18/30 match_one MATCH (60%)** — agents reconstruct correct bodies well.
- **10/30 whole-binary verified (33%)** → banked ×134 (incl. the ×268 `func_8015773C`) → **fleet
  55.04%→55.51% (+0.47%)**, 136/136. (8 direct + 2 via sig_unify; 1 verified-but-local-type stays inline ×1.)
- **12/30 match_one DIFF** = the genuine gcc-quirk tail (§2/§10: hoist-vs-remat, phantom frame, v0/v1
  coalescing, walking-pointer). Agents diagnosed each precisely; correctly wrote no draft.

### 7c. THE CANONICAL-SIG WALL (the singular scaling bottleneck — the ~2× lever)
**The whole 60%→33% gap was SIG CONFLICTS — 100% compile-errors, ZERO codegen byte-mismatches.** Parallel
agents each declare a shared callee (`func_80131CA8`, `func_80131E00`, `func_801472C8`, `func_8001D074`, …)
with a different signature; in the one-big-TU `ov_SC01_077.c` those clash (`conflicting types for func_X`).
`func_80131CA8` alone broke 3 drafts (it is BOTH a residual being matched AND a callee in others — circular).

**This is the loose-typing wall in its true form, and it is BEATABLE deterministically** (unlike Phase-16's
verdict). The fix = a **canonical-sig layer**, applied SURGICALLY per-callee (a blanket global decls header
breaks loose matches — Phase 16; but per-callee byte-gated canonicalization works — sig_unify proof):
1. Identify the high-frequency shared callees among the targets.
2. Establish ONE canonical sig each: match the shared-callee residuals **first** (callees-before-callers, so
   the def fixes the sig fleet-wide), or derive from asm/usage and seed `engine_core.h`.
3. Enforce in the wave: agents grep `engine_core.h` for the canonical (already in the prompt) + a strengthened
   `sig_unify` post-pass that unifies the def-sig AND every caller's extern to the SAME canonical.
Expected to lift whole-binary 33% → ~60% (toward the match_one ceiling) — **the dominant scaling lever**.

### 7d. Scaling economics (measured)
Calibration: 30 fns / 1.89M tokens / 33% whole-binary / +0.47%. Naive scale to 300 ≈ ~4% fleet, token-heavy.
With the canonical-sig layer (33%→~60%) ≈ ~6-7% fleet at ~2× token efficiency. **Build the layer before the
big wave.** Targets: `.run/harvest_targets_s3.json` (300, relocs≤5, reach-sorted; the top-30 are done).
*(Superseded by §8 — the layer was built and the "~2×" did not hold; the wall is the compiler, not sigs.)*

---

## 8. THE CANONICAL-SIG LAYER — BUILT, and the decisive finding (Phase-17 session 4, 2026-06-19/20)

**The layer is BUILT and validated; the "~2× scaling lever" framing was WRONG; the real wall is the
gcc-quirk tail, so the next lever is understanding gcc-2.7.2 (R17 research, Phase 18), NOT more brute waves.**

### 8a. What was built (committed, byte-neutral, reusable)
> **DELETED in Phase 26-A (R33):** both tools below were removed — `reconcile_tu`/`cdecl` answer their
> question (a TU's *visible* declarations) **from the build**, not by re-parsing C text. This section is
> retained as the historical Phase-17 record of the (now-retired) fleet-canonical-sig approach.
- `tools/census_conflict_callees.py` — the accurate conflict predicate: an undeclared-`stub` callee with
  `decl_sources = n_callers + is_target >= 2` is a sig-conflict risk (a `declared`/`defined`/`extern` callee
  is conflict-free; gen_harvest_targets feeds the one sig). Writes `.run/conflict_callees.json`.
- `tools/derive_canonical_sigs.py` — one byte-neutral canonical sig per conflict callee: **`s32` return**
  (void→s32 byte-neutral §3a-1; required where `$v0` is used) + **`s32` params** (matched bodies cast int→ptr,
  the demo idiom), **arity** from the Ghidra-C cache AND asm read-before-write `$a0–$a3` (agreed on all 14
  cached; the 6 non-cached stubs call-site-validated). Writes `.run/canonical_sigs.json`.
- The **20-extern block at the TOP of `src/ov_SC01_077/ov_SC01_077.c`** ("Phase-17 canonical-sig layer").
  **LOCAL on purpose** — engine_core.h is shared by all 134 overlays and a reach-1 name (e.g. func_801809BC,
  matched differently in ov_SC03_096) would collide. `gen_harvest_targets` + `sig_unify` both already read
  the overlay `.c`, so the layer auto-wires with **no tool change**.
- **Pipeline change (mandatory):** harvest_verify accumulates the baseline from the (now block-carrying)
  `.c`, so a raw draft's guessed extern clashes with the block even at `--chunk 1`. The wave gate is now
  **draft → `sig_unify` (MANDATORY, normalizes drafts to the file-top canonical) → `harvest_verify --chunk 1`
  → propagate.** Census after the layer: **conflict callees 20→0, blocked targets 24→0**, fleet 136/136 (R22).

### 8b. THE FINDING (R14/P9 — this redirects the whole strategy)
- **The conflict wall is small:** for the remaining 270, only **20 callees / 24 targets / 7% of wave reach**.
  The "~2×" was the *top-30's in-flight* conflicts, since dissolved by banking those callees.
- **The high-reach core IS the gcc-quirk tail.** Hand-tried the 4 reach-134 *circular* conflict callees
  (the §7c "match callees first" move) — **ALL quirk-bound, 0 banked:** func_8012B4B8 = §10 stack-addr
  rematerialize-vs-hoist (gcc caches `&mtx`); func_8012B8E4 = `$s0/$s1` regalloc swap, **structurally perfect
  75=75** but the permuter probe stalled at base score (external callee `ratan2`, so T6 doesn't even apply —
  it's just not in the permuter's search space); func_8016A8FC / func_80169A4C = local-struct-builders
  (stack-layout-bound). Drafts in `.run/drafts-s4/`; permuter scratch `.run/permuter/func_8012B8E4/`.
- **Types are byte-neutral for matching (re-confirmed):** matching reads the access *width* off the asm
  instruction (`lh`=s16, `lbu`=u8, `lw`=s32), not off any struct def — so emulator-recovered struct types
  help *comprehension*, not the byte-close. The wall is the compiler's regalloc/scheduling, which types and
  shared-context do not touch.

### 8c. The leverage analysis (answering "do the fewest largest that unlock the most?")
- The fleet % is **function-count-weighted** (`190,949 / 344,010` functions): **every reach-134 match is
  +0.039% regardless of size.** Giants bank more *bytes* but the same %. So "fewest largest" gives no % edge.
- "Unblock many" = the canonical-sig layer (declaration removes sig-friction; it does NOT make callers
  *matchable* — matching is independent per function). The highest-fan-in callees (func_8012A828 49 callers,
  func_80146CA0 46, …) are already `defined`/`declared`/`extern`. Declaring the top-5 *undeclared* keystones
  touches only 28 of 900 stubs. So there is no "magic 5 unlocks hundreds."
- **The real lever is reach (size-independent), which we already reach-sort, + the idiom flywheel.** Of the
  400 remaining reach-134 stubs, **247 are the tractable shape** (≤80 ins, ≤4 calls); 80 call-heavy (§10
  tail), 28 giants. Projected tractable-247 wave ≈ **+3-4% fleet** at the calibration close-rate.

### 8d. The deferred wave (staged, ready to resume after the compiler research)
`.run/harvest_wave_s4.js` = the layer-aware probe (40 tractable reach-134, sig_unify-before-gate). Resume
after Phase 18 lands new gcc-quirk idioms (which raise the close-rate above 33% and so the wave's yield).

### 8e. Phase-18 OUTCOME (compiler-quirk research — the verdict, CORRECTED)
The research LANDED (cookbook §17, gcc source `tools/reference/gcc-papermario` + Xenogears mine), and a
mid-phase correction matters: I first concluded the highest-reach circular tail (the call-crossing
register-ALLOCATION-ORDER class, `global.c:allocno_compare` density ordering) was "not source-steerable" —
**that was WRONG.** Drew's "we hand-match everything" pushed the one lever I'd skipped: **`register __asm__`
PINS force the allocation** (+ a scheduling barrier for the last instruction). func_8012B8E4 — the flagship
"unsteerable" fn — is now **byte-gated + propagated ×134**. So the circular tail IS matchable; the wall was a
missing lever. New idioms: register-pins+barrier (the swap class), array-decay-remat (the hoist class),
for-loop/statement-order (structural). 2 circular reach-134 fns matched (func_801399A8 structural,
func_8012B8E4 pinned); fleet 55.51→55.58%. **Re-scope for the wave (Phase-19 = Step 1):** teach agents the §17
TOOLKIT — triage each residue with `match_one`, then: pure structure → reconstruct; stack-buffer-to-callee →
array-decay; call-crossing register swap → PINS (read the target asm, map values→callee-saved regs, pin);
last-instruction schedule → barrier. The pins are HAND-tier (the permuter rejects them; ~5-10 min/fn) but each
circular fn is ×134, so worth it. The ONLY genuine stub-and-skip is the **narrow-param loose-typing conflict**
(func_80146A6C). Expected close-rate rises above the prior 33% as agents apply the pin recipe to the swap tail.