A matching decompilation of Brave Fencer Musashi (PlayStation, Square, 1998 — the USA release, SLUS-00726): C source that, compiled with the game's own 1990s toolchain, rebuilds every shipped code binary byte for byte. It is the first public decompilation of this game, and the whole of its game code is matched: the main executable, the always-resident engine, every location overlay and every code module streamed from the disc — 218 binaries, verified against a redump image of the original disc on every build.

The contract is narrow and machine-checkable. "Matching" means byte-identical output, checked by SHA1 against the originals; nothing "functionally equivalent" counts. What the repository claims is exactly what make check-all proves.

Where it stands

Metric	Matched	Of	%
Functions byte-identical (all binaries)	363,680	363,680	100.00%
Instructions byte-identical (instruction-weighted)	13,492,113	13,492,113	100.0%
Distinct code byte-identical (each body once)	5,820,205	5,820,205	100.0%
Main executable game code (excl. Sony objects)	45,150	45,150	100.0%

218 binaries rebuild byte-identical from source · 350,533 functions in C (251,903 of them shared bodies via 3,173 dedup groups) · 1,256 Sony PsyQ library functions linked from the SDK objects, not our C · 27 hand-written-assembly bodies kept verbatim · 8 Sony library routines carried as assembly where no SDK object matched · 0 assembly stubs left · 0 non-matching functions.

One source per unique function (Phase 35): 103,015 function bodies written once in C (3,173 of them shared headers instantiated 262,573 times); 160 duplicate copies remain in 51 ledgered classes (declaration conflicts left for the types phase); 38 functions whose bytes vary per binary share one text through the text tier (2,030 sites); 1,668 same-address copies of 381 tiny bodies inside the cross-address classes are deferred to the names phase.

Levers off (Phase 36, snapshot 2026-09-11): 2,141 register pins and 1,869 asm statements remain in 1,980 functions (674 distinct bodies), 4,010 of them marked // !FAKE:; 1,589 volatile qualifiers and 50 bare register keywords are censused; 6,447 GTE coprocessor operations and 22 whole-body assembly routines kept inside C shells (2,682 sites; the original's scratchpad stack-switch trampolines, one copy per overlay, listed in the verbatim manifest) are not levers and are excluded.

Generated by tools/progress.py --readme from docs/progress.json — numbers are never typed by hand.

The timeline is generated from the committed progress digests by tools/timeline.py (never drawn by hand); the dated rows behind it are in docs/story-timeline.md and the narrative in docs/story.md.

Two things in those binaries are deliberately not our C, and are stated as such:

1,256 functions of the main executable are Sony's PsyQ library code (libcd, libgs, libgte, libgpu, libspu/libsnd, libetc, libapi, libcard…). They link byte-identical from the SDK's own objects when you have the SDK, and are carried as assembly tiles taken from the disc when you do not — either way the executable is byte-identical. Reimplementing Sony's libraries is out of scope.
The original's hand-written assembly routines are kept as verbatim __asm__ bodies — the five file-scope ones (the boot code, two libgcc routines, two MDEC-side routines) and, since the Phase-36 census (2026-09-09), twenty-two scratchpad stack-switch trampolines that every location overlay carries inside a C shell — all listed in config/verbatim_manifest.json and audited by tools/verbatim_check.py --strict; the count in the block above is generated from that manifest.

Everything else is C that the pinned compiler turns into the original bytes — with one dated exception the Phase-36 census (2026-09-09) surfaced: fourteen game functions (eight in the main executable) were still carried whole as assembly inside C shells, a form the earlier verbatim detector could not see. They are listed in the manifest as DECOMPILE-NOW or UNCERTAIN and are Phase 36's to decompile; the count of such bodies is published by the census until it is zero. Progress numbers are generated from the sources (tools/progress.py), never typed by hand; the full recipe to reproduce them is in docs/verification.md.

Build it from your own disc

The repository contains no game data: no executable, no disassembly, no assets, no memory dumps — only source, build configuration, symbol names and hashes. You need your own redump-layout dump of the USA disc (Track 1 SHA1 b44f0f0a19936f23b26188b658e13201a6a9c211, CRC32 c238191b; the four-track BIN/CUE is ideal, Track 1 alone works).

git clone --recurse-submodules https://github.com/Druthulu/BFM-decomp.git && cd BFM-decomp
make bootstrap                    # toolchain preflight: venv, submodules, the pinned gcc-2.7.2 cc1 (sha256-checked)
mkdir -p disks && cp '/path/to/Brave Fencer Musashi (USA)'*.{bin,cue} disks/
make disc-extract                 # extracts the disc and checks all 1,801 files against the committed manifest
make clean && make -j"$(nproc)" extract-all && make -j"$(nproc)" check-all
                                  # -> "check-all: 218 passed, 0 failed of 218"

Linux (WSL2 Ubuntu 24.04 is what the project uses); binutils-mipsel-linux-gnu, cpp-mipsel-linux-gnu, Python 3.12. The main executable's SHA1 is 143dbb89f34491258bbc27810d0a12ec8b43a8dd. make help lists every target; docs/verification.md gives each step's expected last line and the record of the last full run.

Toolchain (pinned by fingerprint evidence): gcc-2.7.2-psx cc1 -O2 -G0 -mips1 -mcpu=3000 -mgas -msoft-float -fgnu-linker → maspsx --aspsx-version=2.56 --expand-div → mipsel-linux-gnu-as -march=r3000 -mtune=r3000 -no-pad-sections -O1 -G0, with per-file -O0 modules where the bytes demand it. The Sony PsyQ SDK objects are optional and user-supplied (tools/fetch_psyq.sh); they are never redistributed.

What is in the repository

Path	What
`src/`	The C — one directory per binary (`src/` itself is the main executable, `src/resident/`, `src/ov_/`, `src/md_/`), `src/shared/` for the code shared across binaries via the dedup registry
`config/`	splat configs, symbol files, per-binary SHA1 contracts (`check.*.sha`), the dedup registry, the Ghidra annotations as text (`config/ghidra/`)
`tools/`	Everything the project built to do this: the byte gate, the extractor, the matching harness, the campaign machinery, the CI audits, the public-flip rewrite tooling; pinned submodules (maspsx, asm-differ, decomp-permuter, m2c)
`docs/`	The matching cookbook (500+ compiler idioms), the gcc-2.7.2 codegen map, the memory map, the decision log, the accelerators, the runbooks, the story and the retrospective
`phase-ends/`	The project's own governance record: one PhaseEnd per phase, the digest, the per-phase logs
`include/`, `extracted/retail/manifest.*`	Headers; the sha1 manifest your disc extraction is checked against

How it was made

This project was carried out end to end by an AI coding agent — Claude Code — working inside a governance framework: a static constitution (PROJECT_CONTEXT.md), a session protocol (CLAUDE.md), two human gates per phase, an append-only record of every phase (phase-ends/), and a growing rule set distilled from what went wrong. The framework is published separately as ProjectArchitect; this repository is its largest worked example.

The reverse-engineering side ran on Ghidra driven over MCP, with a PCSX-Redux runtime oracle; the matching side is a byte gate over the whole binary, a permuter, a compiler-idiom cookbook, and — decisively — reading the gcc 2.7.2 source to explain the bytes the compiler emits. Everything that was learned is written down where it can be reused:

docs/matching-cookbook.md — the idioms, each byte-proven, and the compiler-internals laws
docs/gcc-2.7.2-map/ — the codegen map of the pinned compiler, by pass
docs/decision-log.md — every strategic pivot with its measurement and its hindsight
docs/accelerators.md — what would have made earlier phases faster
docs/story.md and docs/retrospective.md — the timeline and the retrospective
docs/public-flip-runbook.md — how a private repository with game bytes in its history became this public one

About the history. The full development history is here — every commit, date and message — but it was rewritten before publication to remove game-derived files from every revision. Old commit hashes cited inside historical documents were replaced by inert tokens (commit:NNNN, the commit's ordinal); docs/commit-map.tsv maps them to the commits you see, and documents at the tip cite the current hashes directly.

Standards, and how the AI was used

Accuracy. A function is matched only when its compiled instructions are identical to the original, register allocation included, and the whole binary's SHA1 equals the original's. That check runs inside every build of every binary, and a clean rebuild follows every batch of banked functions. Nothing "functionally equivalent" is counted, and the default build never links unmatched C. What is not our C is listed above, not hidden.

Readability. The code is matched but not yet finished in the sense other decompilation projects mean. Most functions still carry generated names and thousands of register hints that were matching levers remain; shared engine code lives as one plain-C header per function, included where it is used (Phase 35). Bringing it to the community's standard is the next generation of the project; we adopt sotn-decomp's style guide as the baseline, and the rules are written down in docs/gen3-standards.md: names only with recorded evidence, every match-forcing trick removed or marked, structures unified before they are named, and everything still byte-identical.

How the AI was used. An agent did the work under a written constitution, two human gates per phase, and a rule set distilled from what went wrong. The byte gate, not the model, decides what counts as done. Communication with other projects is written by the maintainer, we do not automate against community infrastructure such as decomp.me, and other projects' policies on AI-assisted contributions are read and followed before anything is submitted.

Tools from this project

Things built here that stand on their own, for other decompilation projects:

xsig (MIT; also in tools/xsig/) — relocation-masked function signatures: the same function at two link addresses gets the same signature, so shared code is found across overlays and across games. Against Xenogears, Vagrant Story and Tomba it found 103 shared functions, all PsyQ library code, which is what it is good for: spotting library functions and shared overlay code.
The permuter driver (tools/permuter/) — an unattended way to run simonlindholm's decomp-permuter for byte-gated pipelines: a restart loop with guards and a relocation-masked scorer that reaches zero only when the object is link-identical. The upstream permuter is a pinned, unmodified submodule; the driver swaps one class on top of it. Offered upstream and declined (the stock scorer's behaviour is intentional for interactive use), so the only copy lives here.
The gcc 2.7.2 codegen map — what the pinned compiler does to your C, pass by pass, each claim tagged with the source tree it was read from and byte-proven on this game.
The decomp.me replica — runs a function through decomp.me's own PS1 toolchain locally and compares the words to the target, so a preset or a scratch is proven before it exists (how).
The drafter write-up — how a small local model was fine-tuned to draft matches under the byte gate, every measurement in order, and what it was worth.
How to AI-decomp — the whole method, for anyone doing this with an agent.
The day-one decomp kit (decomp-architect/) — what this project would hand its own day one, as a Phase-0.5 overlay on ProjectArchitect 2.0: the order of work, the ROM firewall from commit one, the rules distilled from the failures, the conduct rules, readability at draft time — and three dictionaries: the tools verbatim, keyed by the need each answers; the cookbook with its index and the codegen map behind a page that says what transfers to another compiler; and the record (the how-to, the decision log, the accelerators, the retrospective, every PhaseEnd) verbatim, with a check that no rule or lesson was left out. Installed five times in a throwaway under a judge script (wiki); split out after the flip.
The tool index — every tool in the tree keyed by the need it answers, with what proved it and what it hard-codes; generated by tools/tool_census.py from the tree and an authored dictionary, coverage asserted both ways.

License

tools/ and docs/ (the project's own work): AGPL-3.0 — see LICENSE.
src/: a reimplementation of copyrighted game code, provided for study and preservation; no license is asserted — see src/NOTICE.md.
Third-party components keep their own licenses — see THIRD_PARTY.md. tools/brave-CUE/ (CUE's reference extractor) is GPL-3.0; the Sony PsyQ SDK is never distributed.

Contributing, and the no-ROM policy

Nothing derived from the game may enter the repository: no executable, no disassembly, no assets, no memory image, no SDK. CI enforces the tracked tree (tools/audit_public.py: no ROM-derived content by hash, no purge path, nothing over 50 MiB), keeps every source text and portable, and compiles every translation unit with the pinned compiler. Byte identity itself is verified locally with the disc, and the record of the last full run is committed.

The matching frontier is empty, so contributions that help most are not new matches: readability (structs and names in place of raw addresses), shiftability, tooling, and documentation. Open an issue first if you are unsure whether something is ROM-derived.

Special thanks

In the tradition of sotn-decomp, whose method this project followed from day one — this work stands on:

splat, spimdisasm and rabbitizer — the split and the disassembly
maspsx (mkst) — ASPSX's quirks, reproduced
asm-differ and decomp-permuter (simonlindholm)
m2c (matt-kempster) — the scaffolds
old-gcc (decompals) — the compilers, and the gcc 2.7.2 source itself
Ghidra, ghidra_psx_ldr (lab313ru) and GhidrAssistMCP — the static oracle and its hands
psyq-obj-parser (decomp.me) — Sony's objects, readable
PCSX-Redux — the runtime oracle
brave-CUE (CUE) — the reference extractor ours was validated against
The Xenogears, Vagrant Story and Tomba! decompilations — sibling PsyQ idioms
redump, TCRF and gamehacking.org — the ground truth on the disc and in memory
The Brave Fencer Musashi Archipelago world (AegeusEvander) — the living RAM map
ProjectArchitect and Claude Code — the method and the hands