BFM-decomp/phase-ends/PhaseEnd_Phase1.md

PhaseEnd — Phase 1: Repo governance + WSL RE stack + first import

Date: 2026-06-13 · Project Version: 1.1.0 · Phase Status: Complete

Build Log

Files created/changed and complete — do not recreate:

• tools/ghidra_scripts/DumpProgramInfo.java — headless postScript; prints program metadata (language, image base, function count, and every Program-Information property incl. ghidra_psx_ldr's PsyQ Version). Consumed by analyzeHeadless -postScript.
• tools/ghidra_scripts/DecompileAt.java — headless postScript; decompiles a function by address (default 0x80018730) and prints the C. Used to verify milestone substance without MCP.
• tools/ghidra_scripts/ImportPsyqGdt.java — headless .gdt "attach"; opens a PsyQ type archive (default psyq400.gdt) and resolve()s all its types into the program DTM, registering the archive as a SourceArchive. This is the headless replacement for the GUI Data-Type-Manager attach.
• docs/SETUP.md — corrections recorded (see Deviations + Rules): PsyQ 4.0.0 confirmed (§2.5 step 3); 41 MCP tools + async get_code/SSE notes (§2.6); headless -loader auto-detect, extension-install-by-extraction, .rep lock note (§2.7); §2.5 step 5 answered (import types into program); ledger #1 moot, #2 & #12 RESOLVED.
• phase-ends/PhaseEnd_Phase1.md — this file.
• phase-ends/CURRENT_PHASE.md — absorbed into this file and deleted (per P8).
• (Section A, earlier this phase, already committed) PROJECT_CONTEXT.md env corrections, .gitignore H1 relaxation, .gitattributes, .mcp.json, docs/SETUP.md Linux-first, tools/bfm_extract/ extractor, docs/history/ archived research files.

Local artifacts (gitignored / outside the repo — present on this machine, do NOT recreate; a fresh clone elsewhere must redo them):

• ~/bfm-decomp/ghidra/bfm.{gpr,rep} — the saved Ghidra project: SLUS_007.26 imported + analyzed (PSX loader, 1726 functions, PsyQ 4.0.0) with the 2599 PsyQ 4.0 types imported. The import does not need redoing on this machine.
• ~/ghidra_12.1_PUBLIC/ — Ghidra install + both extensions in Ghidra/Extensions/.
• extracted/SLUS_007.26 — committed (H1 relaxed); SHA1 143dbb89f34491258bbc27810d0a12ec8b43a8dd, 413,696 bytes.

Tools/packages installed (whole phase):

• WSL2 Ubuntu 24.04.4 LTS; user musashi (passwordless sudo); git identity (Drew T / 50529377+Druthulu@users.noreply.github.com); gh 2.45.0; unzip 6.0; Claude Code 2.1.177 (B0 bootstrap).
• This session: JDK 21.0.11 (openjdk-21-jdk, apt); Ghidra 12.1 PUBLIC (ghidra_12.1_PUBLIC_20260513.zip, 567 MB, central-dir verified); GhidrAssistMCP v2.8.0 (…20260530…); ghidra_psx_ldr 2026.06.04 (…20260604…). Both extensions load at version=12.1 (exact-12.1 pin held — no version-lock issue).

Verification results (literal):

• extracted/SLUS_007.26: SHA1 143dbb89f34491258bbc27810d0a12ec8b43a8dd, 413,696 bytes, magic PS-X EXE. Track-1 --verify-disc PASSED on Windows (== redump b44f0f0a19936f23b26188b658e13201a6a9c211); WSL re-run deferred (dump not yet copied — not a milestone blocker).
• Headless import: Using Loader: PSX Executables Loader, PSX:LE:32:default, ImageBase 80000000, range 1f800000–801fffff, 1726 functions, analysis 177 s, PsyQ Version = 4.0.0 (DetectPsyQ).
• .gdt import: 2599 types resolved from psyq400.gdt (program DTM 205 → 2609); psyq400 SourceArchive registered; save succeeded.
• MCP server (headless): "started on port 8080 … with 41 tools".
• In-session MCP (Claude Code, the milestone): get_binary_info → SLUS_007.26 / 1726 funcs; get_code(0x80018730, decompiler) → LZSS streaming decompressor (scratchpad ring @ 0x1F800000, 0x3ff window mask, resumable state machine DAT_800c7d24, pos==0 terminator); types get DRAWENV → 92-byte struct (/LIBGPU.H).

Milestone achieved: In a live Claude Code session, mcp__ghidra__get_code(0x80018730) returned the documented LZSS streaming decompressor and DetectPsyQ recorded PsyQ Version = 4.0.0 — both Phase 1 observables, demonstrated end-to-end.

Next: Phase 2 — Deterministic disc & .CD extraction pipeline. Start with the full ISO9660 walker (all 27 root files) in tools/bfm_extract.

Deviations

Item	Plan	Actual	Reason
EXE import method	WSLg GUI (CodeBrowser)	Headless analyzeHeadless	Fully autonomous; milestone reachable without GUI
.gdt attach	"manual GUI step" (known-risk: GUI-only)	Headless ImportPsyqGdt.java (resolve types into program)	No GUI needed; resolves ledger #2 — import types into the program, MCP types/struct tools then see them
Headless -loader	-loader "PSX Executables Loader" (§2.7)	Omit -loader; auto-detect	Named loader rejected (InvalidInputException); auto-detect correctly selects the PSX loader for a PS-X EXE
MCP tool count	~38	41	GhidrAssistMCP v2.8.0 ships 41 tools
get_code execution	(sync implied)	Async task — returns task_id, poll get_task_status; SSE wire frames	v2.8.0 runs heavy tools asynchronously
--verify-disc in WSL	Re-run in WSL	Deferred (ran on Windows, PASS)	Dump not yet copied to disks/; EXE already sha1-verified; not a milestone blocker

Commit Message

chore(phase-1): close Phase 1 — RE stack live, EXE imported, LZSS matched via MCP

- PhaseEnd_Phase1.md written; CURRENT_PHASE.md absorbed + removed (P8)
- milestone: in-session mcp__ghidra__get_code(0x80018730) = LZSS streaming
  decompressor; DetectPsyQ recorded PsyQ Version 4.0.0
- formalizes 6 phase-1 rules (H1-relaxed-while-private, all-in-WSL H2,
  tools-in-tools/, plan-mode-per-phase, no-co-author, WSL-commit/GH-Desktop-push)
- bumps project version 1.0.0 -> 1.1.0

Rules Added This Phase

Rule	Reason
R1 — H1 relaxed while private. ROM-derived content (asm/, assets/, extracted/, decompressed .CD) MAY be committed while the repo is private; accidental inclusion is not a violation. The raw multi-GB disc dump stays ignored regardless. Compliance before going public = history scrub + a rom→decoder regeneration tool.	Solo private phase; momentum > purity until the public flip, when original H1 is restored.
R2 — All-in-WSL (H2 restatement). One ext4 clone at ~/bfm-decomp; no Windows/WSL split, no second clone, no /mnt builds; MCP is loopback 127.0.0.1:8080.	9P//mnt is 5–20× slower and breaks inotify; one clone removes the sync dance.
R3 — All tooling under tools/. Includes tools/bin (compilers), tools/psyq* (native PsyQ), tools/ghidra_scripts (headless scripts).	Keeps the repo root clean; one predictable home for executables/scripts.
R4 — Plan mode every phase. Present the task-by-task plan and get approval before executing (the Phase Start gate).	Drew's standing preference; reinforces the two-gate model (P3).
R5 — No Co-Authored-By trailer on commits. Overrides the harness default.	Drew's instruction (2026-06-11).
R6 — Git workflow = WSL-commit / GitHub-Desktop-push. Claude commits in-phase task work locally in WSL (name/email only, no auth); the user pushes/pulls with GitHub Desktop on Windows over \\wsl.localhost\…. Never git push from the WSL CLI (no credentials by design). core.filemode=false in the clone. Phase-boundary exception: Claude writes PhaseEnd_PhaseN.md and removes CURRENT_PHASE.md but leaves them uncommitted; the user commits AND pushes the PhaseEnd, reviewing the milestone-close before it lands.	Avoids git auth in WSL; keeps push (and the milestone-close commit) under human control; the H1 ROM-content safety net stays with the human committing/pushing.

PhaseEnd Changelog

v1.0.0 → v1.1.0 — Phase 1 complete. WSL RE stack live (JDK 21, Ghidra 12.1 + GhidrAssistMCP v2.8.0 + ghidra_psx_ldr 2026.06.04); SLUS_007.26 imported & analyzed (PSX loader, 1726 functions, PsyQ 4.0.0); PsyQ 4.0 types imported (2599); LZSS decompressor at 0x80018730 confirmed via in-session MCP get_code. Six rules formalized (R1–R6). Ledger: #1 moot (12.1 pinned), #2 RESOLVED (import .gdt types → MCP resolves them), #12 RESOLVED (PsyQ 4.0.0). Key finding: the entire RE loop runs headless (import, .gdt, MCP server, decompile, retype) — no WSLg GUI required.

🛑 Stop Here

Start a fresh session for the next phase. Keep this file forever.