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

# Repository layout

## What is tracked

| Path | What it holds |
|---|---|
| [`src/`](../../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/`](../../src/shared/) holds the bodies shared across binaries by [the dedup engine](The-dedup-engine.md) (`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`](../../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](The-dedup-engine.md). |
| [`config/`](../../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`](../../config/overlays.mk), [`modules.mk`](../../config/modules.mk) — generated by the onboarding scripts, never edited by hand), the dedup registry ([`dedup.us.yaml`](../../config/dedup.us.yaml)), the verbatim-assembly manifest ([`verbatim_manifest.json`](../../config/verbatim_manifest.json)), the Ghidra annotations as text ([`config/ghidra/`](../../config/ghidra/)). |
| [`tools/`](../../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`](../../tools/README.md) carries the one AGPL statement; [`docs/SETUP.md`](../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](Archive-index.md) 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](Docs-and-scratch-conventions.md). |
| [`phase-ends/`](../../phase-ends/) | The governance record: `PhaseEnd_Phase<N>.md` for every phase, [`DIGEST.md`](../../phase-ends/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/`](../../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`](../../CLAUDE.md), [`PROJECT_CONTEXT.md`](../../PROJECT_CONTEXT.md) | The session protocol and the static constitution the AI agent worked under — see [How to AI-decomp, chapter 01](../how-to-ai-decomp/01-governance.md). |
| `.github/workflows/` | [`no-rom.yml`](../../.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](Docs-and-scratch-conventions.md). |
| [`Makefile`](../../Makefile), [`requirements-python.txt`](../../requirements-python.txt), [`LICENSE`](../../LICENSE), [`THIRD_PARTY.md`](../../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-ROM-firewall.md). 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](Ghidra-rebuild-from-text.md). |
| `dumps/*.bin` | 28 RAM images the memory map was derived from. [`dumps/INDEX.md`](../../dumps/INDEX.md) describes each state and [`dumps/CHECKSUMS.sha1`](../../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`](../commit-map.tsv). [`docs/public-flip-runbook.md`](../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`](../../phase-ends/DIGEST.md).