BFM-decomp/docs/gen3-standards.md

# Standards: accuracy, readability, and the use of AI — the bar this project holds itself to

> **Written 2026-09-07 (P33 S89) at the owner's direction, as the charter document for Gen3.** Two things are true at once about
> this repository: it is the largest fully machine-carried matching decompilation on record, and it is not yet code a human
> maintainer would call finished. This page states the standard on both counts — the accuracy bar already met and held, the
> readability bar Gen3 exists to meet — and the conduct rules for using AI that keep the project from being confused with
> low-effort machine output. The measurements are dated; re-derive them before quoting (R37, R41).

## 1. Accuracy — met, held, and stricter than the field

"Matched" here means one thing: the compiled output is instruction-identical to the original, register allocation included,
**and** the whole binary's SHA1 equals the original's (rule G3). Nothing "functionally equivalent" is ever counted (P9). The
enforcement is structural, not procedural:

| Guarantee | How it is enforced | Where the proof lives |
|---|---|---|
| Every shipped binary is byte-identical | `config/check.*.sha` is checked inside every `make build`; there is no third state between "identical" and "failed" | `docs/verification.md` (the recorded contract run: 218 of 218 from a clean rebuild) |
| No unmatched C in a default build | the `NON_MATCHING` guard (G4); the census reads 0 | `make audit-frontier`, `docs/progress.json` |
| A bank is verified from a clean rebuild, never incremental | R22 after every banked batch; main gated only by `gate_main`'s clean rebuild | the phase logs, `.run/P33/verify/` |
| The measuring instruments are themselves audited | corpus/cdecl/sig oracles in `make tools-health`; a second, disagreeing oracle where one is structurally blind (R34) | `docs/SETUP.md` §6, the P26/P27 audits |
| What is *not* our C is stated, not hidden | 1,256 Sony PsyQ objects linked byte-identical; the hand-written assembly routines kept verbatim, censused in `config/verbatim_manifest.json` (5 at the Phase-33 close; 27 since the Phase-36 census of 2026-09-09, which found the in-function form of the lane) | `README.md`, `docs/verification.md` |

Most projects gate per function with a diff score and check the whole ROM periodically; here the whole-binary hash runs on
every build of every binary, and a clean rebuild follows every batch. Accuracy is therefore not a Gen3 concern. It is the
floor Gen3 stands on: every edit below is byte-neutral by definition and is rejected the moment it is not.

## 2. Readability — the bar Gen3 meets

The community's expectations are written down; the clearest statement is sotn-decomp's `docs/STYLE.md`, and this project
adopts it as the baseline (read 2026-09-07):

- **Naming:** locals `camelCase`, globals `g_PascalCase`, statics `s_PascalCase`, struct members `camelCase`, types and
  functions `PascalCase`, enum values and macros `SCREAMING_SNAKE_CASE`, files `snake_case`. "Ideally names should be both
  short and clear, although it's better to be clear than short."
- **Types:** the project's own `u8 … u32` types; "We always write our enums and structs as typedefs."
- **Formatting:** clang-format — 4 spaces, 80 columns, braces on the same line, pointer on the type; a blank line between
  declarations and code; braces on every conditional and loop body.
- **Numbers:** decimal for counts, timers and indices; hexadecimal for angles, addresses and masks; `bool` for 0/1 returns;
  "It's better to not hardcode array sizes (easier to mod)."
- **Honesty markers:** `// !FAKE:` on code that exists only to force a match; `//! @bug` on original bugs; a comment wherever
  something is strange.
- **The rule this project ranks first:** *"If you are not sure what something does, it is better to leave it unnamed than name
  it wrongly."*
- **Organisation:** functions in the order of the assembly, in a file that belongs to the system they implement.

To that baseline this project adds four rules of its own, because its code was produced by a machine at scale and the
failure modes are different:

1. **Every name carries evidence.** A function or variable is renamed only on a recorded basis — a string it prints, a
   cross-reference chain, the debug menu, a live-RAM datapoint (R10), a community label with provenance (G5). The evidence is
   recorded the way addresses are recorded in `docs/memory-map.md`. No evidence, no name: it stays `func_80xxxxxx` /
   `D_80xxxxxx`, which is honest and greppable. A model may *propose* a name; it may never *assert* one.
2. **Every register pin goes.** `register … __asm__("$N")` was a matching lever; in finished code each one is either removed
   (the body re-shaped so the compiler allocates naturally — P32 showed every pin in the last drafts came off) or, if a body
   genuinely cannot be shaped, kept with a `// !FAKE:` line that names the residual. The count is a published metric until it is 0.
3. **Shared engine functions live as C, not as macros.** The 5,147 `DEFINE_func_…()` macro bodies in `src/shared/engine_core.h`
   were the dedup engine's way of instantiating one body in every location overlay. A reader expects a `.c` file per system,
   shared the way other overlay-heavy projects share it. The restructuring is byte-neutral and is proven so per family.
4. **Types come from the code, names from observation.** Structure is recovered from access patterns the compiler locked into
   the bytes (many functions reading a `u16` at one offset from one base); meaning comes from observation. The 1,232 struct
   definitions are unified before any field is named; a duplicate type is a defect, a wrong name is a worse one.

Every step is checked the only way this project checks anything: 218 binaries rebuild identical.

## 3. The use of AI — conduct

The project is openly machine-carried and says so in its README; that is the disclosure, made once, at the project level.
The conduct rules below are what keep that fact from being a liability:

- **The byte gate is the only claim of success.** The agent never reports a match the gate has not proven; "the compiler ran"
  and "looks equivalent" are not results (P9). Every "banked" is written from a tool's printed success line (R66).
- **Names and types are evidence-based, never guessed** (§2 rule 1). Hallucinated meaning is the specific way a model would
  damage a decompilation without any test catching it.
- **Outward text is written by a person.** Issues, pull requests, forum posts and outreach to other projects are written by the
  maintainer, the way a developer writes — short, plain, no dense inline-code formatting, no bullet walls, no evidence
  scaffolding — and never a model draft with the tells removed. The model supplies facts. (Rule candidate (j); the lesson cost a
  closed pull request.) Before any submission, the target project's own AI policy is read and followed: sotn-decomp, for one,
  requires that "commit messages and Pull Requests [be] submitted without autonomous tooling such as an LLM or coding agent."
- **No automated traffic against community infrastructure.** decomp.me asks that nobody "scrape the site, hook up an LLM, or
  otherwise make repeated, automated, requests"; the project's decomp.me use is a person in a browser, and its local replica
  (`tools/decompme_replica.sh`) exists so that proofs are run at home.
- **Agents assist; a person owns.** Every change is justifiable by a person from the record (the phase logs, the decision log,
  the cookbook's byte proofs). Governance — the constitution, the two gates per phase, the rule set distilled from failures — is
  what made the machine's output auditable; it stays in force in Gen3.

## 4. The gap, measured (2026-09-07), and the order of work

| Bar (§2) | This tree today |
|---|---|
| Named functions | 1,094 named in the symbol files vs **16,335** `func_80xxxxxx` |
| Named data | **61,898** `D_80xxxxxx` (most are per-overlay script data; many will honestly stay unnamed) |
| Typed structures | **1,232** struct definitions, many drafter-invented variants of one type; **143** raw address casts |
| No match-forcing tricks | **43,925** register-pin declarations (snapshot 2026-09-07: `grep -rhoE 'register [^;/]*__asm__\("\$?[a-z0-9]+"\)' src --include=*.c --include=*.h \| wc -l` — 43,857 in the `"$reg"` form + 68 in the bare `"reg"` form; 42,985 in `.c`, 940 in `.h`; the same command and number as `gen3-handoff.md` §3 — re-derive, do not trust) |
| Readable organisation | ~~**5,147** shared bodies as macros in one 8.4 MB, 227,730-line header~~ → **0** at Phase 35 (2026-09-08, `git grep -c "^#define DEFINE_func_" -- src` empty; 3,173 per-function headers under `src/shared/`, S1 asserted by `tools/share_census.py --check`); **3,558** of 4,287 C files are `_jr_` carve splits |
| Formatting, comments | no `.clang-format`, no `make format`; almost no code comments |

The order, each step gated by the 218 hashes and each sized by a probe before it is priced (R37):

1. **Pins off** — mechanical, batched by function family (`tools/alloc_table.py` + `tools/cc1_dumps_tu.sh` name the
   allocation order; the P32 recipes in cookbook §501 show the reshaping); publish the count as it falls.
   *Phase 36 (2026-09-09 → 2026-09-11): 53,234 → 4,010 sites (−92.5 %), 218/218 at every step; the rungs and their yields are in
   `docs/levers.md`, the moves in cookbook §454–§457; the 4,010 survivors are marked with their pass and named for the structs phase.*
2. **Macro bodies → shared C files** — one family first, measured, then the rest; the carve-split file layout regrouped by
   system where the linker script permits.
3. **Struct unification** — cluster the 1,232 definitions by access pattern (`tools/lift_types.py` knows the collision classes),
   one canonical type per shape, then field names only with evidence.
4. **Names with evidence** — the evidence ladder (strings → debug menu → xrefs → live RAM → community labels), recorded per name.
5. **Formatting and comments** — adopt clang-format with sotn's settings; a file-level description per system; `// !FAKE:` on
   every residual.

**Definition of done for Gen3 (proposed; the Gen3 plan ratifies):** 0 pins or each one `// !FAKE:`-marked with its reason; 0
macro bodies (**met at Phase 35**); one definition per structure; every renamed symbol with a recorded basis; clang-format clean; and, unchanged,
218 of 218 byte-identical from a clean rebuild.

## 5. Related

`docs/gen3-handoff.md` (the census, the levers, the sequencing against Phase 33) · `docs/verification.md` (the accuracy record)
· `docs/decision-log.md` P33 S89 (the closed pull request and what it taught) · `docs/how-to-ai-decomp/` (the method) ·
`docs/retrospective.md` · sotn-decomp `docs/STYLE.md` and `CONTRIBUTING.md`; decomp.me FAQ; `ser-pounce/rood-reverse` — all
read 2026-09-07 as data (X2).