# decompiler

Neural **matching decompilation** for the Game Boy Advance: learn to turn `agbcc`
assembly into C that recompiles to *byte-identical* assembly.

Unlike general decompilers, we do not try to recover names or readable structure — we
optimize a single, checkable objective:

```
agbcc(predicted_C, flags, context)  ==  target_asm     (byte-exact)
```

## The bet

`agbcc`'s optimizer makes C→ASM non-linear and many-to-one (register allocation,
scheduling, peepholes). We treat recovering the C as a *folding* problem and borrow
**AlphaFold 2's two-tower / recycling** ideas — most importantly a **compiler-in-the-loop
recycling** signal (assemble the prediction, diff against the target, feed the diff back).
We validate the analogy honestly and build a strong LLM baseline first. See `docs/`.

## Data

- **Curated git corpus** — 23 bare mirrors of GBA decomp projects under
  `data/corpus-mirrors/` (gitignored; ~1.4 GB). The pokémon repos dominate (~10k matched
  functions in pokeemerald alone). Each matched C function is a training pair.
- **decomp.me** — ~20k agbcc scratches; we harvest the **matches only**. See
  `docs/decompme-extraction-plan.md`.

Audit of what's actually usable: `docs/corpus-completeness.md` + `data/corpus-manifest.json`.

## Layout

See `CLAUDE.md` (symlinked as `AGENTS.md`) for the full agent briefing and repo map.
Vendored deps (the `agbcc` oracle, `llama.cpp`) are pinned in `VENDOR.md`.

## Quickstart

```bash
uv venv && uv pip install -e .          # Python 3.14 env
cd vendor/agbcc && ./build.sh && cd -    # build the compiler oracle
python scripts/measure_corpus.py         # audit the git corpus (if present)
```

## Status

A research project building toward two deliverables: **model weights** (to be hosted on Hugging
Face) and a **runtime** — an automated pipeline where you supply a disassembled `.o` and get
byte-exact matching C back after the model iterates against the agbcc compiler. See
`docs/architecture/model-architecture.md`. The core claim (transformers can defeat agbcc's
optimizer to byte-exactness) is being tested, not assumed.

## License

Code is licensed **GPL-3.0-or-later** (`LICENSE`). The full licensing audit — dependency
compatibility, and the separate handling of the model weights and training-data IP — is in
`docs/LICENSING.md`. The weights are a distinct artifact, **not** covered by this code license.

## Attribution

The training data is the work of the **decompilation community** — [decomp.me](https://decomp.me)
and 23 GBA decompilation projects (pret, zeldaret, metroidret, FireEmblemUniverse, and many
individual authors). Every source is credited with links in `ATTRIBUTION.md`. None of the raw data
is redistributed here; we link back to the originals.