mirror of https://github.com/Druthulu/BFM-decomp synced 2026-10-03 08:07:25 -04:00

Files

T

Drew T 0c29c9e16b tools+kit(phase-33.5): task 14.5 part 1 — the record as the third dictionary + kit_coverage (every rule and every accelerator entry cited or dispositioned)

- decomp-architect/corpus/record/: the how-to (13), decision-log, accelerators, retrospective, story, wave-playbook, effort-map,
  gen3-standards, gen3-handoff, DIGEST and every PhaseEnd (34) verbatim behind an authored front page (what each is, how to
  read it, what is NOT there — the phase logs, R19 — and that the mining pass is their distillation); tool_census: RECORD_SOURCES
  + record_dest + the third corpus in plan/write/check (358 copies + 28 pointers, --check OK); kit_lint exempts corpus/record;
  SETUP Step 6 gains 2c docs/inherited-record.md (+ the verify line; expected-manifest +1); ops-setup/README/tree/methodology/
  wiki page/Home/Tools page/README bullet/SETUP row: "two dictionaries" → three
- tools/kit_coverage.py (+ config/kit_coverage_map.tsv): derives R1..R83 from DIGEST §3 (asserted contiguous) and the 58
  accelerator entries (headings + numbered items), asserts each is cited by a provenance line of the registry seed / the
  kernels or dispositioned (G / DK / FOLDED:G / ENV / PA / SEED: / KIT: / RECORD / COOKBOOK / NOT-PORTABLE; unknown ids
  refused); first run: 26 uncited rules + 21 uncited entries → DK-66 (a ledger's tie-break, a checker's widening and a blanket
  commit are part of the instrument — R70/R80/R52), DK-67 (the ignore file's directory-form wall — S91 (1)), DK-68 (a
  summarised signal is a claim, not ground truth — R14/R66) in a new kernels section 8 (the museum is 9; "In all" 68) + 41
  dispositions (15 PA, 3 ENV, folds into G6/G18/G38/G66/DK-12/19/20/22/25/26/31/35/44/45/46/57/61, 1 KIT template, 1 COOKBOOK);
  now 0 UNCOVERED on both populations; wired into tools-health after tool_census --check; SETUP row + dictionary row
- verify: tool_census --check OK; kit_coverage OK (rules 57 cited + 26 dispositioned / 83; accelerators 41 + 15 / 58);
  kit_lint OK; doc_links --strict OK; wiki_render --selftest 32 pages / 0 unlisted

2026-09-07 23:03:34 -06:00

6.0 KiB

Raw Blame History

BFM-decomp — the wiki

Brave Fencer Musashi (Square, PlayStation, 1998; USA release SLUS-00726), decompiled to C that rebuilds every shipped code binary byte for byte with the game's own 1990s toolchain. It is the first public decompilation of the 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, each verified by SHA1 against a redump image of the original disc on every build. The repository is github.com/Druthulu/BFM-decomp.

The claim is narrow and machine-checkable: matching means byte-identical output, nothing "functionally equivalent" counts, and what the repository claims is exactly what make check-all proves. The live numbers are generated into the README's progress block and docs/progress.json, never typed by hand; at the Phase-33 close (September 2026) all three metrics — functions, instructions, distinct code — read 100%, with two things deliberately not our C and stated as such: Sony's PsyQ library objects linked into the main executable (1,256 functions) and five hand-written assembly routines kept verbatim.

The project was carried out end to end by an AI coding agent (Claude Code) under a written constitution and a two-gate phase system, in twelve weeks. How that was done — and what it cost — is the second half of this wiki.

This wiki is the source of truth for the project's documentation. The records behind it (the cookbook, the decision log, the memory map, the environment reference) live under docs/ and are listed, with how to read each one, in the Reference index; when a page and a record disagree, the record wins and the page gets fixed.

Using the project

Page	What it answers
Build from your own disc	The six-command recipe, what each step proves, the expected last lines, what to do when one fails
Toolchain setup	The pinned compiler/assembler triple and why it is pinned; every tool version; the optional Sony SDK; Ghidra and the emulator
Repository layout	What every top-level directory holds, and what is deliberately not in the repository
The matching workflow	Draft → gate → bank: the oracle ladder from a masked standalone compile to the whole-binary hash, and how a change is kept honest
The dedup engine	Why one matched function banks up to 138 copies: position-locked overlays, signatures, propagation, the registry that fail-closes
Overlays and modules	The disc, the 218 binaries, where each loads and how every load address was proven
Ghidra rebuild from text	The reverse-engineering database is not in git; here is how it regenerates from text + the disc, and the proof that it does
Verification and progress	The contract run, the three metrics and how they are computed, what CI proves without a disc, the published numbers
Contributing and the no-ROM policy	What may never enter the repository, what a useful contribution looks like now that the frontier is empty, the AI-use conduct rules, the license split
Tools from this project	xsig, the permuter driver, the codegen map, the decomp.me replica, the drafter write-up — what stands on its own for other projects
Start a new decomp project	The day-one kit for the next decompilation: the three install steps, what it installs and does not (the three dictionaries), the phase ladder, the conduct rules, the six inversions, every accelerator in one line, the four dry-runs that prove it

Working conventions

Page	What it answers
Docs and scratch conventions	Where each kind of knowledge goes, which files are generated, how links are checked, what the archive is, what may be tracked under `.run/`
The ROM firewall	The rule with no private exemption, the nine classes of ROM-derived content, a copyable `.gitignore`, the audit and CI, what a history rewrite costs

Reference

The Reference index: every live reference and generated file under docs/ — the environment reference, the formats and the memory map, the cookbook and the codegen map, the progress files, the releases, the record, the Gen3 inputs — with what each is, how to read it and who writes it.

How to AI-decomp

How to AI-decomp — the transferable part: thirteen chapters on running a byte-exact decompilation with AI agents, written from this project's records for the next one (any console, any compiler). Governance, the byte gate, the bootstrap order, oracles and instruments, cards/lanes/waves, the knowledge base, reading the compiler's source, models and budgets, the economics as measured, integration and propagation, publishing, and a museum of the failures that looked right at the time.

Where the project goes next

Where the project goes next: the flip and the Gen2 exit (Phase 34), then Gen3 — readability on a byte-exact floor: the style bar, the measured gap, the one invariant, the order of work, the levers.

History

The narrative and the retrospective are in the Reference index (docs/story.md, docs/story-timeline.md, docs/retrospective.md); the phase-by-phase record is phase-ends/ (Repository layout); the documents that served one phase and were then retired are in the Archive index, each with what came of it and where its information lives now.

Brave Fencer Musashi is © 1998 Square. This project is not affiliated with or endorsed by Square Enix. src/ asserts no license (src/NOTICE.md); the project's own tools and documents are AGPL-3.0 (LICENSE).

6.0 KiB Raw Blame History