BFM-decomp/docs/wall-taxonomy.md

Wall Taxonomy — the 957 unmatched shared residuals in ov_SC01_077 (Phase 17 / T1)

What: a full-census classification of every remaining INCLUDE_ASM stub in the canonical harvest source ov_SC01_077 by the blocker class it hits in the real drafting pipeline — so Phase 17 can size each avenue's ceiling and sequence the levers (biggest first). How: tools/wall_taxonomy.py runs m2c --valid-syntax → match_one (standalone, relocation-masked) → for the body-byte-correct subset, sig_unify + a full-overlay-TU cc1, and labels each stub by the first wall it hits (cookbook §14b/§14c/§14e/§15). Deterministic; reproduce with:

python3 tools/wall_taxonomy.py --jobs 16     # ~22 s; writes .run/wall_taxonomy.json + this table

Validated against the bytes (R14): the SIG_FIXABLE_KR bucket was confirmed on the real whole-binary byte-gate — the 4 functions the classifier flagged in a 40-stub probe were exactly the 4 (of 40) that harvest_verify verified byte-identical after sig_unify; all other buckets correctly did not byte-match through signature work alone. The classifier's "fixable-now" set = the real gate-passing set. (PERMUTER_CLASS is an evidenced candidate bucket — see its caveat below — pending T6.)

Baseline at census: fleet 136/136 byte-identical from clean; 54.48% byte-identical-from-source; ov_SC01_077 = 957 unmatched shared stubs (each propagates ×134 overlays via dedup_propagate).

⚠ Correction + T3 update (2026-06-19) — the "loose-typing wall" was a classifier artifact

During T3, verifying the wall bucket against the bytes (R14) found a flaw in the original step-3 classifier: the full-TU cc1 stderr includes pre-existing harmless warnings — the baseline ov_SC01_077.c already emits 3 "passing arg of func_80171AB0 makes integer from pointer" warnings and compiles rc=0, byte-identical (those warnings are byte-neutral: a pointer and an s32 share a register on MIPS). The classifier matched that warning text before the real, rc-flipping error, so it mislabeled 99 functions LOOSE_TYPING_WALL when their actual blocker was something else (e.g. void value not ignored — m2c using a void function's return). Fix: tu_compile_error now keeps only non-warning error lines. Corrected result:

There is no loose-typing wall (99 → 0). It re-bucketed into ARITY_WALL (74) — genuine param-count conflicts (conflicting types for func_X / too-few/many-args), the §14e documented dead-end — plus VOID_VALUE_MISUSE (17, structural → T4/T5) and a few others. Corrected post-T3 census (916 residual stubs, after T3 banked 42):

bucket	count	primary avenue
STRUCTURAL_MISS	368	T4/T5
PERMUTER_CLASS	146	T6 candidate
MCOMPILE_fnptr-call	85	T4 (fn-ptr-table types)
ARITY_WALL	74	the real wall — §14e param-count/arity dead-end
M2C_DECOMP_FAIL	59 (58 jtbl)	T4 (jump-table context)
MCOMPILE_stack-var / arg-arity / undeclared / void-value / bad-deref / incomplete-arg	143	T4/T5
NONFAITHFUL_DEFER	16	defer
SIG_FIXABLE_KR (remaining)	4	T3
DATA_CONFLICT	1	T2 (still ≈0 → skip)

Per-lever (corrected): T4+T5 ≈ 656 (72%), T6 = 146 (16%), ARITY_WALL = 74 (8%), defer = 16, T2 ≈ 0. The sequencing recommendation is unchanged and strengthened — the real wall is arity (74, smaller than the spurious 99) and even more of the residual is structural (T4/T5). The "cast the loose callee func_80171AB0" lever I briefly chased was built on the misattributed warnings → void (the warnings don't block or change bytes).

T3 result (the K&R / sig_unify avenue, gate-proven): banked 42 SIG_FIXABLE_KR matches in ov_SC01_077 (of 48 predicted; 6 honestly reverted by the gate) + propagated 13 ×134 fleet-wide → fleet 54.48% → 55.00% (+0.52%), REAL +1,778, 136/136 byte-identical, dedup-check 1408/0. The avenue is then exhausted: the remaining conflict-class is ARITY_WALL (dead-end) or structural (T4/T5), not signature-fixable.

---

The census (957 stubs, ranked by count) — original T1 snapshot (LOOSE_TYPING_WALL row superseded above)

count	%	Σnins	bucket	primary avenue
368	38%	25345	STRUCTURAL_MISS	T4 (rich context) / T5 (struct) — m2c gets the structure wrong
146	15%	4941	PERMUTER_CLASS	T6 candidate — near-miss, same instruction count
99	10%	3282	LOOSE_TYPING_WALL	WALL — a matched caller passes a contradictory type (§14e)
85	8%	3495	MCOMPILE_fnptr-call	T4 — type fn-pointer tables in the m2c context (§15 S2)
59	6%	12597	M2C_DECOMP_FAIL	T4 — feed jump tables to m2c (58/59 are jump-table, §8) | hard
48	5%	1419	SIG_FIXABLE_KR	T3 — sig_unify resolves it (gate-proven)
45	4%	4928	MCOMPILE_stack-var	T5/T4 — m2c stack/struct recovery
32	3%	4138	MCOMPILE_arg-arity	T4/T5 — m2c arg-count recovery
21	2%	838	MCOMPILE_undeclared-other	T4 — undeclared callee/symbol into context
16	1%	2437	NONFAITHFUL_DEFER	DEFER — GTE/handwritten/special; not m2c-matchable
14	1%	1382	MCOMPILE_m2c-incomplete-arg	T4/T5 — m2c incomplete arg recovery
14	1%	2277	MCOMPILE_bad-deref	T5/T4 — m2c deref'd a non-pointer (?/M2C_UNK)
8	1%	946	MCOMPILE_other	residual (8 fns; mixed m2c-output errors)
1	0%	204	MCOMPILE_bad-switch	T4/T5 — m2c switch reconstruction
1	0%	160	LEAF_READY	T6/harvest — directly matchable, trivial
957		70871		(99.2% carry an actionable label; DATA_CONFLICT = 0)

Example targets (biggest-first = highest leverage; full per-fn data in .run/wall_taxonomy.json):

• STRUCTURAL_MISS: func_80176218(327), func_8016A290(284), func_8015126C(254)
• M2C_DECOMP_FAIL (jtbl): func_8017C974(947), func_80178D40(890), func_8018103C(579)
• MCOMPILE_fnptr-call: func_8015EA3C(204), func_8015D738(201), func_8015F448(188)
• MCOMPILE_bad-deref: func_80144B9C(770 — the Phase-15 prime target, all-134), func_8012D714(284)
• PERMUTER_CLASS: func_80132288(97), func_8013DBE4(97), func_80164930(81)
• SIG_FIXABLE_KR: func_80128AF4(72), func_80144458(64), func_8017E51C(58)
• LOOSE_TYPING_WALL: func_80141CA4(476), func_80140F00(128), func_80155150(105)

Aggregated by primary lever (this is the sequencing driver)

count	%	Σnins	lever
639	67%	39204	T4 (rich context: struct + fn-ptr-table + jump-table + plain), with T5 the struct input to ~474 of them
146	15%	4941	T6 (decomp-permuter) — 146 candidates (101 are ≤4-mismatch near-certain; 19 likely 5–8; 26 speculative 9–16)
99	10%	3282	WALL (loose typing) — documented dead-end; T5's correct struct types may dissolve a subset (§14e)
48	5%	1419	T3 (sig_unify) — gate-proven immediate wins
16	1%	2437	DEFER (non-faithful: GTE/handwritten/special)
9	1%	1106	residual / trivial
0	0%	0	T2 (DATA-symbol byte-array header) — no addressable functions

Giants (106 functions > 150 ins, the ~3.4 MB highest-leverage targets): 30 are M2C_DECOMP_FAIL (jump-table → T4 jtbl context), 28 STRUCTURAL_MISS (T4/T5), 12 arg-arity, 12 stack-var, 6 NONFAITHFUL_DEFER, 5 bad-deref, 4 fnptr-call, rest scattered. The giants are unlocked by T4 (jump-table + struct context), not by T3 or T6.

What this means for sequencing (T1's purpose)

1. SKIP T2 (the DATA-symbol byte-array header). The census finds 0 data-symbol-conflict functions. The cookbook flagged this as "the next yield-limiter" (§14c-c) when Phase 16 jumped past it — but sig_unify (which canonicalizes data externs) plus the prior harvest already absorbed it. Building a universal extern u8 D_X[] header would address nothing. Document the finding; do not build T2.

2. Bank T3's 48 gate-proven SIG_FIXABLE_KR wins first — deterministic, byte-gate-verified, cheap; a clean opening (~5% of residuals, ×134 each). Extend sig_unify coverage / wire it into a propagation pass.

3. Lead with T4 (the rich-context generator) as the primary lever — it addresses 67% of residuals and all 30 jump-table giants. Build it with three context sources, in value order:

   • (a) jump-table data → unlocks M2C_DECOMP_FAIL (59, incl. the 947/890/579-ins giants). m2c literally errors "jump table is not provided"; the §8 rodata/jtbl machinery already exists.
   • (b) struct types (T5's output) → the 474 STRUCTURAL_MISS/bad-deref/stack-var/arg-arity set, incl. func_80144B9C (770). T5 (struct inference + emulator field-typing) is T4's enabling input — run them together, not as separate sequential avenues.
   • (c) fn-pointer-table types → the 85 MCOMPILE_fnptr-call ("called object is not a function").

4. T6 (permuter) is the byte-closer, validated early. 146 candidates (101 near-certain ≤4-mismatch). Critically, T4 will convert STRUCTURAL_MISS into PERMUTER_CLASS (better m2c structure → only regalloc/schedule left), growing T6's addressable set. Confirm the bucket is real on the known-answer ladder (p16_known_answer --gate) before projecting its yield (the only unverified bucket here).

5. The wall is ~99 LOOSE_TYPING_WALL (+ the arity subset). Phase 16's loose-typing finding, now quantified at ~10–13%. No clean deterministic fix; the only lever is T5's correct struct types possibly making some call sites type-consistent (§14e hypothesis — test, don't assume). Plus 16 NONFAITHFUL_DEFER.

Net: the deterministic ceiling (T3 sig_unify, no permuter) is ~5%, matching Phase 16. The eureka lever is T4+T5 (context+struct) at 67% reach, with T6 closing the regalloc residual — not T2 (empty) and not signature work alone. This reorders the plan's avenues to T3 (free wins) → T4+T5 (build together) → T6 (validate + close) ; T2 skipped.

Reproduce / maintain

• python3 tools/wall_taxonomy.py --jobs 16 — full census → .run/wall_taxonomy.json + the table above.
• --limit N probes the classifier on the first N stubs; --no-step3 skips the TU-context conflict sub-split.
• The tool is read-only on tracked files (step 3 uses throwaway src/ov_SC01_077/_wt_*.c copies, auto-removed).
• Re-run after any harvest wave to watch buckets drain and re-rank the remaining avenues.