BFM-decomp/docs/wiki/Repository-layout.md

Repository layout

What is tracked

Path	What it holds
src/	The C. One directory per binary: src/ itself is the main executable (SLUS_007.26), src/resident/ the always-resident engine, src/ov_*/ the 141 overlays, src/md_*/ the 75 code modules. src/shared/ holds the bodies shared across binaries by the dedup engine (engine_core.h, ~8.8 MB of DEFINE_func_…() macros — every translation unit that shares code includes it). Sony's library regions in main are INCLUDE_ASM tiles (src/lib*.c, src/apicard*.c); the five original hand-written routines are verbatim __asm__ bodies. src/NOTICE.md states the licensing position. src/shared/ holds every shared function body ONCE as a plain-C header (ov/, slot_*/, main/, Phase 35), included at each member's site — see The dedup engine.
config/	The build definition: one splat yaml per binary (splat.<alias>.yaml), the symbol files (symbols.us*.txt, curated and build-valid — rule R15), the per-binary SHA1 contracts (check.<alias>.sha), the overlay and module registries (overlays.mk, modules.mk — generated by the onboarding scripts, never edited by hand), the dedup registry (dedup.us.yaml), the verbatim-assembly manifest (verbatim_manifest.json), the Ghidra annotations as text (config/ghidra/).
tools/	Everything the project built (about 236 Python tools, 25 shell tools, 12 Ghidra scripts): the disc extractor, the byte gates, the matching harness, the dedup and family engines, the campaign machinery, the audits, the public-flip rewrite package. The pinned submodules live here too (maspsx, asm-differ, decomp-permuter, m2c) and the tracked cc1 tarballs (tools/bin/). tools/README.md carries the one AGPL statement; docs/SETUP.md's tooling inventory has a one-line row for every tool.
docs/	The knowledge base and the record: the matching cookbook and its index, the gcc-2.7.2 codegen map, the memory map (addresses with provenance), the formats, the decision log, the accelerators, the wave playbook, the runbooks, the story, the retrospective, this wiki's sources (docs/wiki/, docs/how-to-ai-decomp/), the generated progress digests, badges and timeline, and the Archive index of closed-phase documents (their files left the tree at Phase 34; the history keeps them). Where each kind of knowledge goes, which files are generated, and how links are checked: Docs and scratch conventions.
phase-ends/	The governance record: PhaseEnd_Phase<N>.md for every phase, DIGEST.md (every phase's synopsis and every rule's full text), CURRENT_PHASE.md while a phase is open, logs/ (each closed phase's working log, on demand only).
include/	Headers, including the four generic splat preset headers (include_asm.h, macro.inc, labels.inc, gte_macros.inc).
extracted/retail/manifest.jsonl, manifest.sha1	The sha1 manifest of all 1,801 extracted files — the oracle your own make disc-extract is compared against. The files themselves are not tracked.
CLAUDE.md, PROJECT_CONTEXT.md	The session protocol and the static constitution the AI agent worked under — see How to AI-decomp, chapter 01.
.github/workflows/	no-rom.yml (the ROM-free CI: public-clean audits + compile-only) and progress.yml (the objdiff report artifact).
.run/	Scratch — the project-local replacement for /tmp. Ignored by contents (/.run/*), with dated ! exceptions for what a rerun cannot reproduce: .run/P33/verify/ (the recorded contract run), the Phase-32 drafts and reproducers, the giant-crack reconnaissance, the crack ledgers the cookbook cites. The rules, the allow-list idiom and the per-session layout: Docs and scratch conventions.
Makefile, requirements-python.txt, LICENSE, THIRD_PARTY.md	The build (every binary through one parameterized pipeline, BINARY=<alias>), the pinned Python set, AGPL-3.0 for the project's own work, every third-party license.

What is deliberately not in the repository

The policy in full — the nine classes of ROM-derived content, the .gitignore template, the audit and CI that enforce it — is The ROM firewall. The paths as they stand in this tree:

Path (local only)	Why
disks/	Your disc dump. Never committed (rule H1); make disc-extract reads it.
extracted/** (except the manifest), asm/, assets/, build/, expected/	ROM-derived or regenerated: the extracted payloads, splat's disassembly, the build outputs. make clean removes the last four; disc-extract regenerates the first.
ghidra/	The Ghidra project. Its database embeds the game's bytes (verified under Ghidra's page XOR mask). The hand-authored part is tracked as text in config/ghidra/ and the database regenerates from it — Ghidra rebuild from text.
dumps/*.bin	28 RAM images the memory map was derived from. dumps/INDEX.md describes each state and dumps/CHECKSUMS.sha1 records its identity; a re-capture is a new snapshot, never byte-identical.
tools/psyq/	Sony's SDK — user-supplied, optional, checksummed, never distributed.
tools/reference/	The gcc-2.7.2 source and sibling-decomp clones the codegen map cites.

The repository's history was rewritten before publication to remove those paths from every revision; old commit hashes cited inside historical documents were replaced by inert commit:NNNN tokens, mapped back at the tip by docs/commit-map.tsv. docs/public-flip-runbook.md is the procedure.

For maintainers with the local-only directories on disk: never git clean -x / git clean -fdx in this tree — the purged paths are ignored-but-present, and a -x clean deletes the reverse-engineering database. make clean is the only clean.

Naming

• Binary aliases are directory names: main, resident, ov_<DISC>_<FILE> (an overlay from <DISC>.CD's file <FILE>), md_<DISC>_<FILE> (a code module). The alias is what BINARY= takes and what config/check.<alias>.sha is named after.
• Functions and data are address-named until curated: func_80144B9C, D_800A4ED4; curated names live in the symbol files and are mirrored into Ghidra, never the other way round (rule G6). Because overlays are position-locked at one slot, the same address means the same function across overlays — the fact the dedup engine is built on.
• Rules are cited as P1…P10 (process), G1…G8 (ground truth), H1…H5 (hygiene), X1…X2 (communication) from the constitution, and R1…R83 from the PhaseEnds; the full text of every one is in phase-ends/DIGEST.md.