BFM-decomp/phase-ends/PhaseEnd_Phase5.md

# PhaseEnd — Phase 5: splat config + build skeleton (all-asm byte-match)
**Date:** 2026-06-14 · **Project Version:** 1.5.0 · **Phase Status:** Complete

## Build Log

**Files created/changed and complete — do not recreate:**
- `config/splat.us.exe.yaml` — **new.** The splat config for the main EXE. Derived from splat 0.41.0's own
  `create_psx_config` template (platform `psx`, compiler `PSYQ`, `subalign: 2`, `section_order` rodata/text/
  data/bss, `find_file_boundaries: False`, `gp_value: 0x80074750`). `base_path: ..` (the yaml lives in
  `config/`, so paths anchor at the repo root). One `code` segment split into a `[0x800] asm` text
  subsegment + a `[0x531DC] data` subsegment, `align: 4` on the segment (see Deviations). Consumed by
  `make extract`.
- `config/check.us.sha` — **new, committed.** `143dbb89… SLUS_007.26` — the canonical build-check hash
  (validation stage 2). Consumed by `make check`.
- `config/symbols.us.txt` — **modified (now HAND-CURATED).** 15 `2D_*` → `gfx2D_*` renames (a leading digit
  is an illegal as/C identifier — it broke `as`); added the `D_800629D4` data label (boot-code-referenced
  address in the text→data boundary region that splat did not auto-label). Header rewritten to flag that
  ExportSymbols.java overwrites this file → re-apply curations + mirror to Ghidra (G6). Consumed by splat.
- `Makefile` — **modified.** The five Phase-5 stub targets replaced with real implementations: `extract`
  (splat split), `build` (assemble `asm/*.s` → `ld` via the splat linker script + `undefined_*_auto.txt` →
  `objcopy -O binary` → `build/us/SLUS_007.26`), `check` (SHA1 vs `config/check.us.sha`, auto-run by
  `build`), `expected` (snapshot a verified build → `expected/build/`), `clean` (remove all regenerable
  outputs). Added vars `SPLAT/CPP/OUT/ELF/LD_SCRIPT/ASFLAGS/ASPSX_VERSION/OBJS`. `check-env` untouched.
- `.gitignore` — **modified.** Ignore the regenerable splat outputs (`/asm/`, the four generated
  `include/` macros, `undefined_{syms,funcs}_auto.txt`); the earlier "commit asm/" note refined with
  rationale (durable record = `config/symbols.us.txt`). `/build/` + `/expected/` already ignored.
- `docs/SETUP.md` — **modified.** §4.5 binutils **VERDICT: 2.42 byte-clean** (no downgrade); §5.3 + ledger
  #8 **RESOLVED: -G0**; §6.3 **As-built (Phase 5)** target table note; ledger #6 resolved. Original
  deferred-verdict text preserved (additive).
- `docs/memory-map.md` — **modified.** §1 `gp0` row → **-G0 CONFIRMED**; added the **Text→data split**
  block (file/vram boundary, the mixed transition region, `vram = fileoff + 0x8000F800`).
- `phase-ends/PhaseEnd_Phase5.md` — this file.
- `phase-ends/CURRENT_PHASE.md` — **absorbed into this file and deleted** (P8).

**Local artifacts (gitignored / regenerable — do NOT recreate; `make extract` rebuilds them):**
- `asm/{header.s, 800.s, data/531DC.data.s}` — the splat disassembly (header reproduced via splat's
  structured `header` segtype; text + data).
- `include/{include_asm.h, macro.inc, labels.inc, gte_macros.inc}` — splat-generated assembler macros.
- `build/us/SLUS_007.26.ld` — the splat-generated linker script (`_gp=0x80074750`; `ALIGN(.,4)`).
- `undefined_syms_auto.txt` (899) + `undefined_funcs_auto.txt` (8) — splat-generated linker symbol defs.
- `build/` (objects, `.elf`, the 413,696-byte binary) + `expected/build/` (the asm-differ baseline).

**Tools/packages installed:** None — used the existing Phase-4 toolchain (splat64 0.41.0, mipsel-binutils
2.42, the cc1 candidates) entirely. (cc1/maspsx were not invoked — the build is all-assembly.)

**Verification results (literal):**
- **`make extract && make build && make check` → `build/us/SLUS_007.26`, 413,696 B, SHA1
  `143dbb89f34491258bbc27810d0a12ec8b43a8dd` == original (BYTE-IDENTICAL).** Reproduced from a full
  `make clean` cycle.
- **Check is a real gate:** a 1-byte corruption makes `make check` exit non-zero; a rebuild restores `[ OK ]`.
- `make check-env` still exits 0 (no Phase-4 regression).
- **binutils 2.42 byte-clean** with `as -march=r3000 -mtune=r3000 -no-pad-sections -O1 -G0` — the §4.5
  "≥2.38 regression" risk did not materialise; no 2.35 downgrade.
- **-G0 confirmed:** the disassembly has **0** `($gp)` base accesses and **0** `%gp_rel` relocations.
- `git status`: only `config/`, `Makefile`, `.gitignore`, `docs/` tracked; `asm/ build/ expected/` +
  generated macros + `undefined_*_auto.txt` ignored — **zero generated/ROM bulk staged.**

**Milestone achieved:** `make build` rebuilds `SLUS_007.26` **byte-for-byte (SHA1-identical)** from
disassembly alone at 100% assembly, with the SHA1 check auto-running and provably failing on corruption —
the split, linker script, and as→ld→objcopy tooling proven end-to-end.

**Next:** Phase 6 — Compiler fingerprint + first matched functions. Start with selecting 3–5 medium leaf
functions as fingerprint probes (⭐⭐ **Max** — the highest-stakes task in Gen1 per `docs/effort-map.md`).
Phase 6 also introduces the `c`/INCLUDE_ASM scaffold (flip the code subsegment to `c`, wire `decompile.py`
+ asm-differ, establish INCLUDE_ASM/NON_MATCHING headers) — the Makefile already has the dormant
cpp→cc1→maspsx path and the §5.4 candidate ladder is queued.

## Deviations
| Item | Plan | Actual | Reason |
|---|---|---|---|
| Code segment type | `c`/INCLUDE_ASM primary; `asm` as fallback | **`asm` (all-asm)** | The plan's documented fallback, and the better fit: the phase title is "all-asm byte-match" and the roadmap puts INCLUDE_ASM/NON_MATCHING setup in Phase 6. Keeps the unpinned compiler out of Phase 5. Drew-ratified. |
| Execution order | T1 split → T2 Makefile → T3 byte-match | Byte-identity proven by a **manual round-trip during T1**, before the Makefile | Isolated and cleared the High-risk binutils-2.42 variable first (as→ld→objcopy only); the Makefile then just transcribed the working chain. |
| binutils 2.42 verdict | possibly downgrade to 2.35 (§4.5) | **No downgrade — 2.42 is byte-clean** | The build is SHA1-identical with 2.42; the regression warning didn't bite our flags. |
| `asm/` git policy | gitignore (my plan) vs the repo's existing "commit asm/" note | **gitignored** (regenerable via `make extract`) | `make extract` deterministically regenerates it from committed yaml+symbols → build scaffolding, not durable work. `.gitignore` note refined; Drew-ratified. |
| Section-boundary effort | feared a fighting link (T3 Max-escalation) | The link was clean; the only real fights were **15 leading-digit symbol names** + **one un-labelled boundary address** + an **`align: 4`** tweak | splat round-trips bytes, so byte-identity was robust to the imperfect text/data split (as predicted). |
| `config/symbols.us.txt` role | seeded Ghidra export | became the **hand-curated** build input | Build validity (identifiers) + a boot-referenced label had to be fixed in the splat input; ExportSymbols now a careful re-merge, not a blind overwrite (→ R15). |

## Commit Message
```
feat(phase-5): splat config + all-asm byte-identical build of SLUS_007.26

- config/splat.us.exe.yaml: splat PSX config (platform psx, compiler PSYQ,
  subalign 2, gp_value 0x80074750, base_path .., main segment align 4); one
  asm text seg [0x800] + data seg [0x531DC], header via splat's header segtype
- Makefile: implement extract (splat split) / build (as -> ld(splat .ld +
  undefined_*_auto) -> objcopy) / check (SHA1 vs config/check.us.sha, auto-run)
  / expected (asm-differ baseline) / clean; check-env untouched
- config/check.us.sha: committed build-check hash (validation stage 2)
- config/symbols.us.txt: now hand-curated — 15 2D_* -> gfx2D_* (illegal leading
  digit broke as), +D_800629D4 label; header flags re-merge + Ghidra-mirror (G6)
- .gitignore: ignore regenerable splat outputs (asm/, include macros,
  undefined_*_auto.txt); refine the earlier commit-asm/ note
- docs: SETUP.md §4.5 binutils 2.42 = byte-clean (no 2.35 downgrade), §5.3 +
  ledger #8 RESOLVED -G0, §6.3 as-built; memory-map.md gp0 -> -G0 + text/data split
- MILESTONE: make extract && make build && make check -> build/us/SLUS_007.26
  SHA1 143dbb89... == original (BYTE-IDENTICAL), 100% asm, check fails on corruption
- rule R15 (symbol file = curated, valid-identifier build input, Ghidra-mirrored)
- bumps project version 1.4.0 -> 1.5.0
```

## Rules Added This Phase
| Rule | Reason |
|---|---|
| **R15 — `config/symbols.us.txt` is the curated, build-valid symbol source.** It is hand-curated (seeded from `ExportSymbols.java`, then refined for the build); re-exporting is a **careful re-merge, never a blind overwrite**. Every name must be a valid as/C identifier (no leading digit, etc.). All curations — renames and added labels — are **mirrored back into Ghidra** so a future re-export stays valid and consistent (extends G5/G6). | Phase 5: `2D_*` names broke `as` (leading digit illegal); the fix lives only in this file, which `ExportSymbols` would silently overwrite, and Ghidra must carry the change to stay the static oracle. This recurs at scale in Gen2. |

## PhaseEnd Changelog
**v1.4.0 → v1.5.0** — Phase 5 complete. The repo now **rebuilds `SLUS_007.26` byte-for-byte (SHA1-identical)
from disassembly alone** via `make extract && make build && make check` — splat split → mipsel-`as` → `ld`
(splat linker script) → `objcopy`, at 100% assembly (no C). The build is **compiler-independent** (no
cc1/maspsx invoked), so it is solid before the Phase-6 fingerprint. Two roadmap unknowns fell out for free:
**binutils 2.42 is byte-clean** (the §4.5 ≥2.38 regression risk cleared — no 2.35 downgrade) and **ledger #8
= -G0** (zero `$gp`-relative addressing in the disassembly). The splat config uses splat's own PSX template
(PSYQ, subalign 2, gp 0x80074750) with a single `align: 4` tweak (the word- but not 16-aligned text→data
boundary at vram 0x800629DC). `config/symbols.us.txt` became the hand-curated build input (15 `2D_*`→`gfx2D_*`
for illegal identifiers, +`D_800629D4` label) → **R15**. Decisions (Drew-ratified): the code segment stays
**all-`asm`** (Phase 6 owns the INCLUDE_ASM/.c scaffold per the roadmap), and the regenerable splat outputs
(`asm/`, generated macros, `undefined_*_auto.txt`) are **gitignored**. No tools installed. One rule (R15).

## 🛑 Stop Here
PhaseEnd written; `CURRENT_PHASE.md` absorbed and removed. **Drew commits AND pushes** this PhaseEnd plus the
whole Phase-5 change set (R6/R8). Start a **fresh session for Phase 6 — Compiler fingerprint + first matched
functions**. Keep this file forever.