BFM-decomp/cookbook/C0404.md

§363 ★★ — THE OVERLAY-LAYOUT ASSUMPTION IS A SYSTEMIC BUG CLASS, AND main IS THE EXCEPTION THAT FINDS IT (P31 S68; six instances, four of them in one session)

Every fleet tool that composes a path from a binary NAME is encoding the OVERLAY layout (src/<binary>/…, build/<binary>/<binary>, config/check.<binary>.sha). main matches none of it: its sources are LOOSE FILES in src/, its asm is asm/nonmatchings/<region>, its image is build/us/SLUS_007.26, its locked hash is config/check.us.sha, and its undefined_*_auto.txt sit at the REPO ROOT. Measured instances, each of which presented as "the model wrote bad drafts":

tool	wrong assumption	symptom
parallel_gate.stage_generated	build/<b>/<b>.ld + build/<b>/undefined_*	worktree cannot link; main banked 0/3
rtu_match	TU is src/<source>/<split>.c	ERR, empty detail
rtu_match (again)	asm is asm/<source>/nonmatchings/<split>	ERR, empty detail — identical symptom, which is what makes a one-layer fix feel complete
gate_stage	build/<b>/<b> + config/check.<b>.sha, then DEF_SHA	main gated against ov_SC01_077's hash, every draft "near"
recover_integration --auto	--binary defaults to the literal ov_SC01_077; backlog keyed by BARE NAME (R48)	"no candidates" fleet-wide
twin_sweep	family_sweep.load_sigs covers 141 of 213	main/resident/md_MAIN_* structurally invisible

THE RULE. Pass the fact you already have; never reconstruct it. corpus.Stub carries .path and .asm_dir. The Makefile declares <b>_OUT, <b>_CHECK_SHA, <b>_LD_SCRIPT, <b>_UNDEF_SYMS, <b>_UNDEF_FUNCS — ask it (make --eval='__p-%: ; @echo "$($*)"' __p-OUT BINARY=<b>). When you genuinely must reconstruct, assert the result EXISTS and refuse with the reason (R43): a reconstructed path handed to cpp surfaces as a compile failure and reads as a bad draft.

THE DIAGNOSTIC HABIT. When ONE binary's lane banks far below the rest, the prior is harness, not model. The cheapest test is to run the SAME draft through a SECOND, INDEPENDENT oracle and see whether they disagree (R34/R40) — here rtu_match's real-TU compile said MATCH ×3 while the whole-binary gate said "near" ×3, and the gate was the one that was wrong. And do not stop at the first layer: two of the six were the same tool, one call deeper, with an identical symptom.