# Disassembly Project 1

This is a set of disassembled NES roms using AI to translate.

# This is not for distribution. 
# This is not for you.

> **Layout changed 2026-10-20:** projects moved into **mapper directories**
> (`NROM/`, `AOROM/`, `CNROM/`, `MMC1/`, `MMC3/`, `MMC5/`, `UNROM/`), project
> folders were **flattened** (the old `copilot/` subfolder is gone — everything
> sits directly in the project folder), every project's `OVERVIEW.md` became its
> `README.md`, and a root `Makefile` now builds and verifies all projects at once
> (`make`, `make clean`, `make <MAPPER>`); the git pre-commit hook drives it.
> Older docs, commit messages and paths in this file's per-project notes may
> still reference the previous layout — mentally strip the `copilot/` prefix.

# Disassembly Project Index — /home/tmerritt/Projects/disasm/

This document provides a consolidated overview of the **promoted** NES disassembly projects in the repository. Projects are organized **by mapper** into a folder per project under `NROM/`, `AOROM/`, `CNROM/`, `MMC1/`, `MMC3/`, `MMC5/`, `UNROM/` or `MAPPER8/` — 38 of the 41 promoted projects are mapper 0 and live in `NROM/`, with `World Class Track Meet (U)` in `CNROM/` (mapper 3), `Zanac (U)` in `UNROM/` (mapper 2) and `Mermaids of Atlantis (U)` in `MAPPER8/` (mapper 8). The pre-promotion tier mirrors the structure under `_wip/<MAPPER>/<Project>/` and is documented separately in **`WIP.md`** (851 projects across 29 mapper folders). Each project folder is **flat**: the source (`prg.s`, plus `header.s`/`chr.s` where present), the build config (`linker.cfg`, `symbols.inc`, `locals.inc`, `Makefile`) and the ROM splits all sit directly in the folder. Each project carries its own `README.md` (the file was called `OVERVIEW.md` before 2026-10-20) with a detailed power-on execution flow analysis. The pass history of every project — Pass 1, Pass 2, Pass 3 and Promotion, with the date and what each milestone produced — is in **`CHANGELOG.md`**.

---

## Project Inventory

**Mirroring** is the iNES *arrangement* value taken from header byte 6, bit 0 (`0` = Horizontal, `1` = Vertical), the convention `AGENTS.md` fixes. Several per-project README files (then named `OVERVIEW.md`) previously carried the opposite *mirroring-direction* wording; all were normalized to this column on 2026-10-19.

| # | Project | Region/Version | PRG Size | CHR Size | Mirroring | Build Status | Vectors (NMI / RESET / IRQ) |
|---|---------|----------------|----------|----------|-----------|--------------|------------------------------|
| 1 | Balloon Fight (JU) | Japan | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass complete) | $C094 / $C000 / $C0F7 |
| 2 | Baseball (UE) | USA/Europe | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass complete) | $C046 / $C40B / $C43E |
| 3 | Bomberman (U) | USA | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass complete) | $C01A / $C000 / $FFF9 |
| 4 | Burger Time (U) | USA | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass complete) | $FF7F / $FD24 / $FD24 |
| 5 | Clu Clu Land (JU) | Japan | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass complete) | $C1F1 / $C196 / $C196 |
| 6 | Defender 2 (U) | USA | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass complete) | $CAA1 / $C983 / $CA9E |
| 7 | Excitebike (JU) | Japan | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass complete) | $C23B / $C184 / $FFF0 |
| 8 | Tennis (JU) | Japan | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass complete) | $C07D / $C000 / $C000 |
| 9 | Pac-Man (USA) (Namco) | — | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass complete) | $C10E / $C033 / $C17E |
| 10 | Donkey Kong 3 (JUE) | Japan / USA / Europe | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass complete) | $C08D / $C000 / $C000 |
| 11 | Donkey Kong Jr. (JU) | Japan | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass complete) | $C6E6 / $C66E / $FFF0 |
| 12 | CIRCUS | — | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass complete) | $C05A / $C000 / $4CB7 |
| 13 | Wild Gunman (U) | USA | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 3 complete, 49.1% code) | $C086 / $C000 / $C000 |
| 14 | Joypad Test Cartridge (U) | USA | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 3 complete) | $CCF7 / $C000 / $C000 |
| 15 | NES PowerPad Test Card (U) | USA | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass complete) | $E06E / $E000 / $E000 |
| 16 | MUSCLE (U) | USA | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass complete) | $86CB / $8000 / $8764 |
| 17 | Lunar Pool (U) | USA | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 2 complete, Pass 3 tables named) | $FF65 / $E80C / $FF64 |
| 18 | Donkey Kong (JU) | Japan | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 2/3 complete, 76.3% code) | $C85F / $C79E / $FFF0 |
| 19 | Donkey Kong Jr. Math (U) | USA | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 3 complete; 295 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets) | $C4A9 / $C41E / $FFF0 |
| 20 | Duck Hunt (JUE) | Japan / USA / Europe | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 3 complete) | $C086 / $C000 / $C000 |
| 21 | Ice Climber (JE) | — | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 3 complete) | $C076 / $C014 / $FFF0 |
| 22 | Ice Climber (U) | USA | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 3 complete) | $C076 / $C014 / $FFF0 |
| 23 | Lode Runner (U) | USA | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 2/3 complete) | $C02C / $C000 / $FFF9 |
| 24 | Pinball (JU) | Japan | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 2/3 complete; data tables interpreted) | $C1ED / $C000 / $C1ED |
| 25 | Millipede (U) | USA | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 2/3 complete, 74.6% code; 0 address-derived entry points) | $C7F1 / $C735 / $FFF0 |
| 26 | Popeye (JU) (PRG 0) | — | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 2/3 complete, 72.3% code; data tables interpreted) | $C701 / $C649 / $FFF0 |
| 27 | Popeye (JU) (PRG 1) | — | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 2/3 complete, 72.3% code; data tables interpreted; promoted from `_wip` 2026-10-20) | $C701 / $C649 / $FFF0 |
| 28 | Golf (JU) | Japan | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 1+2+3 complete; promoted from `_wip` 2026-10-21) | $C0A6 / $C000 / $C0C4 |
| 29 | Hogan's Alley (JU) | Japan | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 2 complete, Pass 3 complete, 49.1% code; promoted 2026-10-20) | $C088 / $C000 / $C000 |
| 30 | Mario Bros (JU) | Japan | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 2 complete, Pass 3 complete, 78.4% code; data tables interpreted; promoted 2026-10-20) | $C07D / $C000 / $C000 |
| 31 | Pac-Man (Tengen) (U) | USA | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 2 complete, Pass 3 complete, 47.3% code; promoted 2026-10-20) | $C0FA / $C033 / $C16A |
| 32 | Pac-Man (U) | USA | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 2 complete, Pass 3 complete, 47.4% code; promoted 2026-10-20) | $C0FA / $FF00 / $C16A |
| 33 | Pyramid (U) (Sachen) | — | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 2 complete, Pass 3 complete, 39.6% code; data tables interpreted; promoted 2026-10-20) | $D72E / $FF00 / $FF00 |
| 34 | Raid on Bungeling Bay (U) | USA | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 2/3 complete, 64.6% code; promoted 2026-10-20; 223 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets) | $C04C / $C000 / $C2C0 |
| 35 | Raid on Bungeling Bay (U) [a2] | — | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 2 complete, Pass 3 complete, 64.3% code; promoted 2026-10-20; 220 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets) | $C04C / $C000 / $C2C0 |
| 36 | Urban Champion (JU) | Japan | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 3 complete, 48.4% code; data tables interpreted) | $CA91 / $CA00 / $CA00 |
| 37 | Xevious (U) | USA | 32 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 3 complete, 37.7% code) | $FC4E / $FAF6 / $FF1D |
| 38 | Zanac (U) | USA | 128 KB | none | Horizontal | BYTE-IDENTICAL (Pass 3 complete, 10.5% code - banks 6 and 7 only; banks 0-3 are empty and banks 4-5 are stage data) | $CE8D / $E7BF / $CEC4 |
| 39 | Volleyball (U) | Japan | 32 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 3 complete, 73.0% code; promoted 2026-10-21) | $8053 / $8000 / $FFFF |
| 40 | Mermaids of Atlantis (U) | USA | 64 KB | 64 KB | Vertical | BYTE-IDENTICAL (Pass 3 complete, 12.3% code; promoted 2026-10-20, rebuilt 2026-10-21) | $808F / $FF00 / $8036 |
| 41 | World Class Track Meet (U) | USA | 32 KB | 32 KB | Horizontal | BYTE-IDENTICAL (Pass 1+2+3 complete, 55.0% code; promoted from `_wip` 2026-10-21) | $F803 / $F6FD / $C0C0 (dead) |
| 42 | Port Test Cartridge (U) | USA | 32 KB | none | Vertical | BYTE-IDENTICAL (Pass 1+2+3 complete, 4.8% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21) | $CC49 / $C000 / $CC17 |
| 43 | 10-Yard Fight (U) | USA | 32 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 1+2+3 complete, 32.0% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21) | $8471 / $8000 / $84FF |
| 44 | Chubby Cherub (U) | USA | 32 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 1+2+3 complete, 41.4% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21; 205 `SubC<addr>` entry points named 2026-10-21, 18 address-derived `jsr`/`jmp` targets left, recorded in the project README) | $82B7 / $8000 / $8331 |
| 45 | Dig Dug II (U) [!] | USA | 32 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 1+2+3 complete, 53.5% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21) | $A749 / $A52D / $A52D |
| 46 | Gyromite (JUE) | Japan / USA / Europe | 32 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 1+2+3 complete, 31.0% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21) | $8079 / $8000 / $8000 |
| 47 | Hydlide (U) | USA | 32 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 1+2+3 complete, 47.8% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21) | $8003 / $8000 / $8003 |
| 48 | Ice Hockey (U) | USA | 32 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 1+2+3 complete, 39.5% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21; 140 `SubC<addr>` entry points named 2026-10-21, 79 address-derived `jsr`/`jmp` targets left, recorded in the project README) | $805A / $8000 / $8000 |

Thirty-six of the 48 rows are mapper 0 with a 16 KB PRG, 8 KB CHR and no trainer.
The exceptions: `Xevious (U)` and `Volleyball (U)` are mapper 0 with a 32 KB PRG;
`Port Test Cartridge (U)` is mapper 0 with a 32 KB PRG and no CHR (CHR RAM);
`10-Yard Fight (U)` is mapper 0 with a 32 KB PRG (NROM-256);
`Chubby Cherub (U)` is mapper 0 with a 32 KB PRG (NROM-256);
`Dig Dug II (U) [!]` is mapper 0 with a 32 KB PRG (NROM-256);
`Gyromite (JUE)` is mapper 0 with a 32 KB PRG (NROM-256);
`World Class Track Meet (U)` is mapper 3 (CNROM) with a 32 KB PRG and 32 KB CHR
(its header's CHR-size field overstates the CHR by 32 KB); `Zanac (U)` is mapper 2
with a 128 KB PRG and no CHR; `Mermaids of Atlantis (U)` is mapper 8 with a 64 KB
PRG, 64 KB CHR and eight 8 KB banks.

All 48 rows are promoted and **BYTE-IDENTICAL** — `make` compares the whole
reconstructed ROM against `rom.nes` in the project folder. The last nine to leave
`_wip/` were `Golf (JU)` (row 28), `World Class Track Meet (U)` (row 41),
`Port Test Cartridge (U)` (row 42), `10-Yard Fight (U)` (row 43),
`Chubby Cherub (U)` (row 44), `Dig Dug II (U) [!]` (row 45),
`Gyromite (JUE)` (row 46), `Hydlide (U)` (row 47) and `Ice Hockey (U)`
(row 48), all promoted on 2026-10-21. (Urban Champion, row 36, kept its tail number, so the
promoted numbering is no longer a single contiguous range.)

> **The seven NROM projects promoted on 2026-10-21 were re-split afterwards.**
> Their Pass 1 splits had classified between 0.7% and 24.9% of the PRG as code:
> the static trace reached the reset stub and the vblank wait and nothing else,
> because each game's main code sits behind a computed dispatch. A Mesen Code
> Data Logger capture of a real play session names the addresses the CPU
> actually branched to, and re-tracing with those seeds takes the coverage to
> 4.8%-53.5%. The numbers in the table are the re-split ones.

> **Still true after the 2026-10-20 reorganization.** The mapper reorganization moved
> `Donkey Kong Jr. Math (U)` (row 19) into `_wip/NROM/` — it was fixed the same day (its four
> `jsr $F218` call sites had been labelled `SubCF218_Block` = $F1DC; repointed to
> the true entry `SubCF218`) and promoted back into `NROM/`. **Popeye (JU) (PRG 1)**
> was promoted from `_wip/NROM/` the same day (row 27) — its whole-ROM compare passes
> on the first build. `Excitebike (JU)` (row 7) — the repo's one open block after
> being returned to `NROM/` with a broken mid-repair build (duplicate symbol) —
> was finished the same day: the byte-596 mismatch (`$0A` operands where the ROM
> uses `$11`, now aliased `NmiMaskShadow`) is fixed, the 4,401 damaged audit
> comments were re-anchored via `_tools/repair_audit_comments.py`, and 58 raw
> `jsr/jmp $XXXX` operands were substituted with labels/equates. **All 38
> projects under `NROM/` now verify byte-identical.**

**How to read this table.** The vectors are the three little-endian words at the **end of the
16 KB PRG** (`$FFFA-$FFFF` in the `$C000` mirror) — *not* fields in the iNES header, whose bytes
0-9 carry only sizes, mirroring and mapper. Regenerate the whole column with:

```bash
python3 - <<'EOF'
import os
MAPPERS = ('NROM', 'AOROM', 'CNROM', 'MMC1', 'MMC3', 'MMC5', 'UNROM')
for base in MAPPERS:
    if not os.path.isdir(base):
        continue
    for p in sorted(d for d in os.listdir(base) if os.path.isdir(os.path.join(base, d))):
        rom = open(f"{base}/{p}/rom.nes", 'rb').read()
        prg = rom[16:16 + rom[4]*16384]; vo = len(prg) - 6
        v = [prg[vo+i] | (prg[vo+i+1] << 8) for i in (0, 2, 4)]
        print(f"{p:30s} {'Vertical' if rom[6] & 1 else 'Horizontal':10s} "
              + " / ".join("$%04X" % x for x in v))
EOF
```

Five rows were wrong before this pass, all from copy-paste duplication of a neighbouring row's
vectors, and are corrected above:

| Project | Was | Actually |
|---------|-----|----------|
| Burger Time (U) | `$C046 / $C40B / $C43E` (Baseball's) | `$FF7F / $FD24 / $FD24` |
| Clu Clu Land (JU) | `$C1F1 / $C000 / $FFF9` | `$C1F1 / $C196 / $C196` |
| Excitebike (JU) | `$C1F1 / $FD24 / $FD24` | `$C23B / $C184 / $FFF0` |
| Pac-Man (USA) (Namco) | `$C10E / $C000 / $C17E` | `$C10E / $C033 / $C17E` |
| Donkey Kong 3 (JUE) | `$C07D / $C000 / $C000` | `$C08D / $C000 / $C000` |

Donkey Kong Jr.'s mirroring was also wrong (Horizontal, actually Vertical). Odd vector *targets*
are not mistakes: Burger Time's `$FF7F` NMI and CIRCUS's `$4CB7` IRQ point into unused/data space,
which is common in this set — see "Notes" under Per-Project Details.

Region/Version comes from the folder-name suffix (JU/U/UE/JUE); these mapper-0 headers do not
encode region, so CIRCUS — whose folder carries no suffix — is left as `—` rather than guessed.

---

## Per-Project Details

### 1. Balloon Fight (JU)
- **Folder:** `NROM/Balloon Fight (JU)/`
- **ROM:** `balloon.nes` (24,592 bytes)
- **Source:** `prg.s` (17,607 lines)
- **Linker:** PRG at $C000, 16 KB; single segment
- **Vectors:** NMI → $C094 (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $C0F7 (`IrqHandler`, self-loop)
- **Key subsystems:** NMI-driven frame loop with PPU command buffer, round spawner ($C790), bonus objects ($CB74), carrier/rescue sequence ($C6F9), particle system ($CDAA), sound driver ($FFF7 banked)
- **Build fix:** None needed; byte-identical out of the box. **Pass 1 verified complete 2026-10-16** — 5,303 instructions / 11,260 code bytes (68.7%), which is *more* than the complete-opcode static tracer finds (5,277 / 11,202); the 166 tracer-only bytes are genuine data (command scripts at $D437/$D45A, the $C3B5 pointer table, the arithmetic table at $FBCA), not missed code. The last two `.incbin` spans were converted to explicit classified bytes (`TrailingFillBeforeApuTables` at $F4C5, `SoundEngineTailBytes` at $F5FC), so no ROM byte is hidden
- **Pass 3 symbols (2026-10-19):** every operand `symbols.inc`/`locals.inc` defines is now
  named in `prg.s` — **125** hardware-register operands and **797 of 813** zero-page/RAM
  operands. The 15 multi-alias addresses were resolved per routine (`--sites` in
  `_tools/apply_symbols.py`). **16** operands are left numeric: `$13` used as a plain
  high-byte scratch beside `Temp12`, where none of its three aliases fits. Rebuild stays
  byte-identical.
- **Audit-trail repair (2026-10-21):** the per-instruction audit comments were **stale by
  two bytes** from `ResetInitializationData` ($C085) onward — 5,944 of the 6,007 comments
  named the wrong CPU address/PRG offset, because the 3-byte `.byte "HAL"` signature at
  $C082–$C084 was counted as one byte when the trail was generated. The routine headers
  and the linker labels were correct, so source and headers disagreed.
  `_tools/repair_audit_comments.py` rebuilt the trail from the `ca65 -l` listing
  (validated against `prg.bin`) and `_tools/align_audit_comments.py` restored the
  canonical column-35 layout. Comment-and-whitespace only: the code text of all 8,544
  lines is unchanged and `make` still prints **Byte-identical ROM verified.** All 6,007
  comments now re-check against `prg.bin`, all 65 routine headers agree with the
  instructions they describe, and every label agrees with `reconstructed.lbl`. A
  related off-by-one in `align_audit_comments.py` was fixed (it tested the indented code
  length against 31 instead of 35, so 28–31-character code texts were never padded into
  the column).
- **Routine headers completed (2026-10-21):** all **63** routine headers now carry the
  full template `AGENTS.md` describes — global, local, parameters, returns and
  **clobbers**. The `; Clobbers:` blocks are derived, not written by hand:
  `_tools/derive_clobbers.py` takes the opcode from the audit comment's byte list (so
  the addressing mode is exact), resolves the operand through `locals.inc`/`symbols.inc`
  to name what is written, follows the real control flow (a `jsr` to another named entry
  is a call; a branch or a fall-through is not), and models register preservation — so
  `NmiHandler` reports *no register* (it saves and restores A, X and Y) and
  `FlushPpuCommandPreserved` reports only A (X and Y come back unchanged). The flags are
  named individually. Comment-only change: the code text of all 8,538 lines is unchanged
  and `make` still prints **Byte-identical ROM verified.**
- **Details:** `Balloon Fight (JU)/README.md`

### 2. Baseball (UE)
- **Folder:** `NROM/Baseball (UE)/`
- **ROM:** `baseball.nes` (24,592 bytes)
- **Source:** `prg.s` (21,627 lines — largest source)
- **Linker:** PRG at $C000, 16 KB; single segment
- **Vectors:** NMI → $C046 (`NMI`), RESET → $C40B (`Reset`), IRQ → $C43E (`IRQ`, `rti`)
- **Key subsystems:** Queued event system ($EB66–$EB9C) as the main frame driver, round/state machine ($C5FE), batting/pitching ($C6044–$C6414), object sorting ($C339), sound driver ($F9D0–$FE2x)
- **Build fix:** None needed; byte-identical out of the box
- **Pass 3 symbols (2026-10-19):** **121 operands substituted** (85 single-name + 36 hardware) from `symbols.inc`/`locals.inc` via `_tools/apply_symbols.py` — zero residue. Rebuild stays byte-identical.
- **Details:** `Baseball (UE)/README.md`

### 3. Bomberman (U)
- **Folder:** `NROM/Bomberman (U)/`
- **ROM:** `bomberman.nes` (24,592 bytes)
- **Source:** `prg.s` (11,000 lines), `header.s`, `chr.s`
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C01A (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $FFF9 (`IrqHandler`, `rti`)
- **Key subsystems:** NMI-driven PPU command queue and VRAM transfers, main loop at $C368 with state dispatch table ($C75D), bomb/object slots (80 slots at $03E6), sound driver ($E642–$FE2x) with dispatch table ($E6AD)
- **Build fix:** One-byte mismatch at CPU $E71B (`dec $E4` vs `dec $54`) — resolved by adding `RandomStateAlt = $E4` to `locals.inc` alongside `RandomState0 = $54` (zero-page reuse); also renamed `ControllerState` → `ControllerState1`, `Main_HandleControl_C368` → `MainGameLoop`, `Gameplay_HandleControl_C79D` → `GameplayUpdate`, `Sound_HandleControl_E65F` → `SoundUpdate`
- **Pass 3:** Applied 354 single-name + 8 site-resolved multi-alias operands from `locals.inc`; 24 in-file table labels from `reconstructed.lbl`; 0 hardware substitutions needed. Residue: 758 unnamed operands (179 distinct addresses).
- **Details:** `Bomberman (U)/README.md`

### 4. Burger Time (U)
- **Folder:** `NROM/Burger Time (U)/`
- **ROM:** `Burger Time (U) [!].nes` (24,592 bytes)
- **Source:** `prg.s` (13,138 lines), `header.s`, `chr.s`
- **Linker:** HEADER, PRG at $C000 (0x3FFA), VECTORS at $FFFA, CHR
- **Vectors:** NMI → $FF7F (points *into* the vector page itself — not a real handler; NMI is effectively unused), RESET → $FD24 (`ResetHandler`, `sei` prologue), IRQ → $FD24 (reuses Reset)
- **Key subsystems:** Event-driven main loop via `CommonEngineExit` ($EB6A) and queued events ($EB9D), title screen / round state machine ($C5FE), object arrays ($03E6 state, $0436/$0486 position), audio engine ($F9D0–$FE2x) with music sequencer ($FD34)
- **Build fix:** None needed; byte-identical. Requires symlink `burger_time.nes → "../Burger Time (U) [!].nes"` due to spaces in ROM filename
- **Details:** `Burger Time (U)/README.md`

### 5. Clu Clu Land (JU)
- **Folder:** `NROM/Clu Clu Land (JU)/`
- **ROM:** `rom.nes` (24,592 bytes)
- **Source:** `prg.s` (10,501 lines)
- **Linker:** PRG at $C000, 16 KB; single segment (no separate HEADER/CHR segments in cfg, but CHR data is embedded inline at end of prg.s)
- **Vectors:** NMI → $C1F1 (`NMIHandler`), RESET → $C196 (`ResetEntry`, shared with the IRQ handler), IRQ → $C196 (`IrqHandler`, reuses Reset)
- **Key subsystems:** State-machine main loop via dispatch table at $C000–$C00D, NMI-driven PPU command queue + VRAM transfers, object pools ($03E6 state, $0436/$0486 position), sound driver ($E642–$F7C0) with dispatch table ($E6AD)
- **Build fix:** One `bpl` branch to undefined label at CPU $FAB4 — replaced with `bne *-$1B` to produce original `d0 e3` bytes (disassembler mislabeled `bne` as `bpl`)
- **Details:** `Clu Clu Land (JU)/README.md`

### 6. Defender 2 (U)
- **Folder:** `NROM/Defender 2 (U)/`
- **ROM:** `Defender 2 (U).nes` (24,592 bytes)
- **Source:** `prg.s` (17,432 lines)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (0x3FFA), VECTORS at $FFFA, CHR at $0000
- **Vectors:** NMI → $CAA1 (`NmiHandler`), RESET → $C983 (`ResetHandler`), IRQ → $CA9E (`IrqHandler`, reuses Reset)
- **Key subsystems:** Event-driven main loop (`UpdateSideScrollingGameplay_CA6A` at $CA6A) waiting on NMI flag, side-scrolling gameplay ($C073–$C324 family), PPU streaming ($F20B–$F7C0), audio engine ($E642–$F7C0) with dispatch table ($E6AD)
- **Build fix:** Same `bpl` → `bne *-$1B` fix at CPU $E811 as Clu Clu Land (disassembler mislabeled `bne` as `bpl`)
- **Details:** `Defender 2 (U)/README.md`

### 7. Excitebike (JU)
- **Folder:** `NROM/Excitebike (JU)/`
- **ROM:** `rom.nes` (24,592 bytes)
- **Source:** `prg.s` (13,993 lines)
- **Linker:** PRG at $C000, 16 KB; single segment
- **Vectors:** NMI → $C23B (`NMI`), RESET → $C184 (`Reset`), IRQ → $FFF0 (points into audio data region — likely placeholder/unused)
- **Key subsystems:** NMI-driven state machine with dispatch table at $C000–$C00D (14 states), title/menu system ($C346–$C454), gameplay update chain ($C99A), race update ($C8D6), audio engine ($F8DE) with 4 channels + SFX, serial I/O over controller port $4016
- **Build fix:** Same `bpl` → `bne *-$1B` fix at CPU $FAB4 (same pattern as Clu Clu Land/Defender 2). On 2026-10-20 the last whole-ROM mismatch (byte 596) was fixed — two NMI operands the ROM spends on `$11`, a second PPU-mask shadow, were emitted with `PpuMaskShadow` (`$0A`); `$11` is now aliased `NmiMaskShadow` in `locals.inc`. The same day the audit trail was re-anchored from the ca65 listing via `_tools/repair_audit_comments.py` (6,339 shifted comments + 4,401 doubled-`??` forms) and all 58 raw `jsr/jmp $XXXX` operands were substituted with routine labels/`locals.inc` sub-entry equates.
- **Details:** `Excitebike (JU)/README.md`

### 8. Tennis (JU)
- **Folder:** `NROM/Tennis (JU)/`
- **ROM:** `Tennis (JU).nes` (24,592 bytes)
- **Source:** `prg.s` (10,377 lines)
- **Linker:** PRG at $C000, 16 KB; single segment
- **Vectors:** NMI → $C07D (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $C000 (`Reset` reused)
- **Key subsystems:** NMI-synchronized main loop (`MainLoop` at $C04F), game state machine via `MainStateHandlerTable` ($C101, 12 states), game mode state machine via `GameModeStateTable` ($CAD7, 8 states), object/sprite system with fixed-point physics, audio engine ($F8DE) with serial I/O over controller port
- **Build fix:** None needed; byte-identical out of the box
- **Pass 3 symbols (2026-10-19):** **18 single-name operands** substituted from `locals.inc` via `_tools/apply_symbols.py` — zero residue. Rebuild stays byte-identical.
- **Details:** `Tennis (JU)/README.md`

### 9. Pac-Man (USA) (Namco)
- **Folder:** `NROM/Pac-Man (USA) (Namco)/`
- **ROM:** `rom.nes` (24,592 bytes)
- **Source:** `prg.s` (7,637 lines)
- **Linker:** PRG at $C000, 16 KB; single segment
- **Vectors:** NMI → $C10E (`NmiHandler`), RESET → $C033 (`Reset`; `locals.inc` defines `ResetOffset = $C033`), IRQ → $C17E (`IrqHandler`)
- **Key subsystems:** NMI-synchronized main loop (`MainLoop` at $C04F), game state machine via `MainStateHandlerTable` ($C101, 12 states), game mode state machine via `GameModeStateTable` ($CAD7, 8 states), object/sprite system with fixed-point physics, audio engine ($F8DE) with serial I/O over controller port
- **Build fix:** None needed; byte-identical out of the box
- **Pass 3 symbols (2026-10-19):** **524 single-name operands** substituted from `locals.inc` via `_tools/apply_symbols.py` — **727 multi-alias residues** left numeric (addresses with 2+ aliases, e.g. `$00` = `workPtr0`/`Zp00`). Rebuild stays byte-identical.
- **Details:** `Pac-Man (USA) (Namco)/README.md`

### 10. Donkey Kong 3 (JUE)
- **Folder:** `NROM/Donkey Kong 3 (JUE)/`
- **ROM:** `Donkey Kong 3 (JUE).nes` (24,592 bytes)
- **Source:** `prg.s` (14,647 lines)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C08D (`NmiHandler`; the `prg.s` header block records it as "Pass 2 control-flow entry at CPU $C08D"), RESET → $C000 (`Reset`), IRQ → $C000 (`Reset` reused)
- **Key subsystems:** Main loop with object/game state management at $C02E–$C18D, object movement and geometry calculations ($C28E–$C683), audio engine ($F8DE+) with sound channels ($F0–$FF), PPU command buffer streaming ($C3F4+)
- **Build fix:** Build split `main.s` into `header.s`, `prg.s`, `chr.s`; added `RandomStateAlt = $E4` for `dec $E4` at CPU $E71B (zero-page reuse with `RandomState0 = $54`). **2026-10-16 — one-byte branch-target bug fixed:** the project was recorded as BYTE-IDENTICAL but had never built byte-identical. The `bne` at CPU $C14C (PRG $014C) was annotated `D0 12` (target $C160) but assembled as `D0 0D`, because it was labelled `StoreSelectedPlayerAndScreenFlags` ($C15B) instead of the routine actually at $C160. Retargeted to `ClearAudioSetGameMode` — which is also the semantically correct target for a "mode != $01" test. `cmp` now passes.
- **Details:** `Donkey Kong 3 (JUE)/README.md`

### 11. Donkey Kong Jr. (JU)
- **Folder:** `NROM/Donkey Kong Jr. (JU)/`
- **ROM:** `Donkey Kong Jr. (JU).nes` (24,592 bytes)
- **Source:** `prg.s` (15,271 lines; 6,199 instructions, 266 routines, 68 data labels, 0 conflicts)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C6E6 (`NmiHandler`), RESET → $C66E (`ResetHandler`), IRQ → $FFF0 (stray byte, effectively unused)
- **Key subsystems:** Reset idles in a PRNG-advance loop — the entire frame state machine (title/attract/gameplay/sound) runs inside the NMI handler; VRAM/event queue at $0300 with dispatch table at $BFFE; 8-byte PRNG at $18–$1F; sound timers at $F1AF
- **Build fix:** None needed; byte-identical out of the box (`make` in the project folder). **Pass 1 verified complete 2026-10-16** — a full byte-accounting audit of `prg.s` confirms all 16,384 PRG bytes are emitted exactly once (6,199 instructions + 3,889 `.byte` + 16 `.word`), every emitted value equals the ROM byte, and there are zero audit-comment mismatches or duplicate addresses. No `.incbin` remains. A complete-opcode static tracer independently reaches 6,135 instructions / 12,358 code bytes (75.4%) — every one of which is already present in the file, and the file carries 121 further code bytes the tracer does not find (reached via the `DeferredTaskHandlerTable` dispatch at $BFFE). Pass 2/3 naming is complete; Pass 3 tables are named (`DeferredTaskHandlerTable`, `HudDigitDescriptorTable`, …)
- **Details:** `Donkey Kong Jr. (JU)/README.md`

### 12. CIRCUS
- **Folder:** `NROM/CIRCUS/`
- **ROM:** `rom.nes` (24,592 bytes)
- **Source:** `prg.s` (~18,661 lines)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C05A (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $4CB7 (outside mapped space — effectively unused)
- **Key subsystems:** NMI-driven frame state machine — main loop is a spin loop at $C057, all per-frame work runs in NMI; main state dispatcher at $C0D0 with 16-state pointer table; controller input with edge flags at $09; menu system with text table at $C763 ("CONTINUE", "STAGE", "SELECT", "PLAY"); palette/screen transfer via descriptor streams; VRAM queue processing; variant object state machine at $DC3F–$FE7B; audio engine with sequence data at $FABB–$FFFB
- **Build fix:** None needed; byte-identical out of the box (`make` in the project folder). Pass 1/2/3 complete — full code/data classification, semantic routine naming, and data table naming all done. **2026-10-21:** the 258 `SubC<addr>` entry points were given semantic names (the 586 internal branch-target children were re-based onto their parent's new name), so `grep -nE "^(SubC|Sub)_?[0-9A-F]{4}" prg.s` now returns nothing and no `jsr`/`jmp` target is address-derived
- **Pass 3 symbols (2026-10-19):** **118 operands substituted** (38 single-name + 80 hardware) from `symbols.inc`/`locals.inc` via `_tools/apply_symbols.py` — **23 multi-alias residues** left numeric (addresses with 2 aliases: `$E4`=`Controller1Shift`/`ZpE4`, `$7C`=`WorkPointer0Lo`/`Zp7C`, `$7E`=`WorkPointer1Lo`/`Zp7E`). Rebuild stays byte-identical.
- **Details:** `CIRCUS/README.md`

### 13. Wild Gunman (U)
- **Folder:** `NROM/Wild Gunman (U)/`
- **ROM:** `rom.nes` (24,592 bytes)
- **Source:** `prg.s` (~14,644 lines with routine headers)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C086 (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $C000 (reuses `Reset`)
- **Key subsystems:** NMI-driven frame loop — main loop is a spin loop waiting on NMI phase flag ($20); NMI handler does OAM DMA ($4014), PPU updates, and calls game logic subroutines ($C29F, $C233, $C3AC, $C265); main state dispatcher at $C0B3 based on `GameMode` ($30); reset copies sprite/OAM data from $C844 to $05F0; APU enabled via $4015 = $0F
- **Build fix:** None needed; byte-identical out of the box (`make` compares the whole ROM in the project folder: `cmp reconstructed.nes rom.nes`). **Pass 1 redone 2026-10-16** — the original tracer followed only RESET/NMI/IRQ and jsr/jmp/branch targets and knew just the 151 documented opcodes, so it missed Wild Gunman's runtime dispatch (`Label_C341`'s `pla`-based computed goto puts the jump table inline right after each `jsr $C341`) and filed ~4.9 KB of real code as `.byte` data. Code coverage went **1,597 instr / 3,352 B (20.5%) → 3,956 instr / 8,085 B (49.3%)**. **Pass 2 complete** — all 733 labels carry names (zero `Label_Cxxxx`/`SubCxxxx` remain), routine headers on every entry point, zero-page aliases in `locals.inc` (`GameMode`=$30, `NmiPhase`=$20, `NmiFlag`=$22, `Timer2F`=$2F, etc.). **Pass 3 complete** — data tables named: `SpriteAttributeTable` ($C6AC), `NoteVolumeTable` ($F3EF), `VolumeEnvelopeTable` ($F48F), `SpritePositionTable` ($F77C); the OAM sprite block at $C844 is documented in-place as a comment rather than a label
- **Pass 3 symbols (2026-10-19):** **76 operands substituted** (11 single-name + 65 hardware) from `symbols.inc`/`locals.inc` via `_tools/apply_symbols.py` — zero residue. Rebuild stays byte-identical.
- **Details:** `Wild Gunman (U)/README.md`

### 14. Joypad Test Cartridge (U)
- **Folder:** `NROM/Joypad Test Cartridge (U)/`
- **ROM:** `rom.nes` (24,592 bytes)
- **Source:** `prg.s` (5,871 lines; 202 routines, all with described headers)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $CCF7 (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $C000 (reuses `Reset`)
- **Key subsystems:** NMI-driven frame loop — main loop spins waiting on NMI phase; NMI handler does OAM DMA ($4014), PPU scroll/control latch, and burst VRAM writes from table at $0302; `VramPtrWrite` ($CD3F) uses a return-address modification trick at `RetAddrUpdate` ($CDC8) for runtime-computed dispatch; `VramWrite` ($CDEE) sets PPU address and writes data to PPUDATA; reset clears RAM, initializes PPU ($2000=$10, $2001=$00), triggers OAM DMA, and enters main loop
- **Build fix:** Byte-identical out of the box, but **Pass 1 was badly truncated and has been redone**. It claimed 282 instructions / 580 bytes (3.5%); the tracer halted at `$C09E` on `DCP $3C20` (`$CF`), an undocumented opcode used as ordinary code, and filed 3,256 bytes of real code as `.byte`. Now **1,773 instructions / 3,836 bytes (23.4%)**, verified against a fresh trace. `nesdis.py --undocumented` supplies the 105 undocumented NMOS opcodes; ca65 V2.19 encodes none of them, so the 4 affected instructions are emitted as explicit `.byte` with the disassembly in the comment. Pass 2 then renamed all 202 labels (zero `Label_Cxxxx` left) and rewrote all 202 routine headersr all labels, semantic naming for key routines, zero-page aliases in `locals.inc` (`VramPtrLo`=$00, `PpuCtrlShadow`=$EF, `FrameCounterLo`=$53, etc.)
- **Pass 3 symbols (2026-10-19):** **47 hardware operands** substituted from `symbols.inc` via `_tools/apply_symbols.py` — zero residue. Rebuild stays byte-identical.
- **Details:** `Joypad Test Cartridge (U)/README.md`

### 15. NES PowerPad Test Card (U)
- **Folder:** `NROM/NES PowerPad Test Card (U)/`
- **ROM:** `rom.nes` (24,592 bytes)
- **Source:** `prg.s` (3,170 lines)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $E06E (`NmiHandler`), RESET → $E000 (`Reset`), IRQ → $E000 (reuses `Reset`)
- **Key subsystems:** Minimal NMI-driven test cartridge — NMI reads PowerPad via $4016, processes transitions, updates score/lives display; APU at $4015=$0F; 8.3% code coverage
- **Build fix:** None needed; byte-identical out of the box
- **Pass 3 symbols (2026-10-19):** **89 hardware operands** substituted from `symbols.inc` via `_tools/apply_symbols.py` — zero residue. Rebuild stays byte-identical.
- **Details:** `NES PowerPad Test Card (U)/README.md`

### 16. MUSCLE (U)
- **Folder:** `NROM/MUSCLE (U)/`
- **ROM:** `M.U.S.C.L.E. (U).nes` (24,592 bytes); `rom.nes` is a relative symlink `../M.U.S.C.L.E. (U).nes`
- **Source:** `prg.s` (Pass 1/2/3 output, with 42 bytecode listings above the `.byte` data)
- **Linker:** HEADER at $0000 (16 bytes), **PRG at $8000 (16 KB)**, CHR at $0000 (8 KB) — the one ROM in the set mapped *low*
- **Vectors:** NMI → $86CB (`NmiHandler`), RESET → $8000 (`Reset`), IRQ → $8764 (a bare `RTI` that doubles as the NMI epilogue). Vectors themselves sit in the $C000 mirror at $FFFA.
- **Key subsystems:** bytecode VM — 40 opcodes at `$C8-$EF` handled through a table at `$9237`, everything else a literal operand. Gameplay dispatches through three jump tables plus two zero-page `jmp (zp)` calls a static descender cannot follow: 38-entry token-program pointer table at `$8CEF`, 40-entry opcode handler table at `$9237`, 16-entry handler table at `$9F2B`, 3-entry per-level VRAM-writer table at `$AC35`. Compressed-VRAM RLE decoder at `$AC82` with a 12-byte fill table at `$ACBD`; division by 20 restored at `$82AC`; four-channel sound engine with per-channel state in zero page `$C4-$EF`.
- **Build fix:** the skeleton's `$C000` linker assumption was wrong — RESET is `$8000`, so `linker.cfg` had to move. `Makefile` tool paths were `../../../_tools/` while in `_wip/`; promotion to top-level required `../../_tools/`. `make regen` (pass1→pass2→pass3) reproduces `prg.s` byte-for-byte.
- **Pass 3 symbols (2026-10-19):** **220 operands substituted** (91 single-name + 129 hardware) from `symbols.inc`/`locals.inc` via `_tools/apply_symbols.py` — zero residue. Rebuild stays byte-identical.
- **Pass 3 data-table inventory (2026-10-21):** all **69** data blocks are inventoried in the project README with their address range, size, name, structure and the instruction that reads them. Two blocks that had been given bytecode-program names turned out **not** to be bytecode and were renamed: `StandaloneBytecodeProgram_1` → `DeathSequenceVramStream` (`$881F`, the compressed nametable RLE stream of the death sequence) and `StandaloneBytecodeProgram_3` → `LevelOamTemplateTable` (`$AB14`, the per-level OAM template copied into the shadow at `$0300`). The pointer table's 38 entries are all distinct, so it reaches **38** distinct programs, not 37.
- **Details:** `MUSCLE (U)/README.md`

### 17. Lunar Pool (U)
- **Folder:** `NROM/Lunar Pool (U)/` (promoted out of `_wip/` 2026-10-18 by `git mv`, so the relative `rom.nes` symlink is live and tool paths are `../../_tools/`)
- **ROM:** `Lunar Pool (U).nes` (24,592 bytes)
- **Source:** `prg.s` (5,302 instructions, 67.5% code / 11,062 bytes; 705 labels, zero `Label_` residue, 38 semantic zero-page aliases + 66 neutral, 33 named data tables)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $FF65 (`NmiHandler`), RESET → $E80C (non-$C000 entry), IRQ → $FF64 (bare `rti`, adjacent to NMI)
- **Key subsystems:** NMI-driven frame loop with PPU command queue and VRAM transfers; main loop at $E80C; side-scrolling / pool gameplay; audio engine; print-inline-string helper at $CBDC/$CBC9
- **Build fix:** Promotion from `_wip/` added `header.s`, `chr.s`, HEADER/PRG/CHR `linker.cfg`, and whole-ROM `cmp`; rebuilt from Mesen CDL capture (10,028 bytes Code). **Pass 1/2/3 complete** — byte-identical at whole-ROM level.
- **Pass 3 symbols (2026-10-19):** **45 operands substituted** (18 single-name + 27 hardware) from `symbols.inc`/`locals.inc` via `_tools/apply_symbols.py` — zero residue. Rebuild stays byte-identical.
- **Details:** `Lunar Pool (U)/README.md`

### 18. Donkey Kong (JU)
- **Folder:** `NROM/Donkey Kong (JU)/` (promoted out of `_wip/` 2026-10-19 by `git mv`, so the relative `rom.nes → ../Donkey Kong (JU).nes` symlink survived)
- **ROM:** `Donkey Kong (JU).nes` (24,592 bytes)
- **Source:** `prg.s` (6,014 instructions, 76.3% code / 12,505 bytes; 1,015 labels with **zero `Label_` residue**, 145 zero-page slots with neutral `ZpXX` names, 10 named data regions)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C85F (`NmiHandler`), RESET → $C79E (non-$C000 entry, like DK Jr.), IRQ → $FFF0 (vector-page padding, unused)
- **Key subsystems:** reset enters at $C79E; NMI-driven frame loop; dispatchers at $C807/$C815/$C823/$C831/$C847 load 16-bit pointers from `ObjectPtrTable` ($C03C) and from `$C4A7,x`; large level-data pointer block $C044–$C79D; sound engine over `MusicDataTable` ($F55B), `APUDataTable` ($FAE6), `SfxDataTable` ($FE59)
- **Pass 2 (2026-10-19):** all 919 `Label_XXXX` definitions named — 102 new semantic routine names + 217 `SubC<addr>` entry names (honest residue) + 600 derived `<Routine>_Block[_n]` internal branch targets; `jsr`/`jmp` operands stay numeric (`Wild Gunman (U)` style). Applied with `_tools/pass2.py apply`; `make` still byte-identical
- **Build fix:** none at PRG level — it was PRG-identical in `_wip/` and stayed byte-identical through Pass 3. Promotion added `header.s`, `chr.s`, a HEADER/PRG/CHR `linker.cfg`, the `rom.nes` symlink, and the whole-ROM `cmp`; no `_tools` path change (the Makefile never referenced `_tools/`) and no `make regen` target. Mirroring was recorded as Vertical in the project README (then named OVERVIEW) but header byte 6 = $00 says **Horizontal** — corrected at promotion
- **Pass 3 symbols (2026-10-19):** **75 operands substituted** (17 single-name + 58 hardware) from `symbols.inc`/`locals.inc` via `_tools/apply_symbols.py` — zero residue. Rebuild stays byte-identical.
- **Details:** `Donkey Kong (JU)/README.md`

### 31. Pac-Man (Tengen) (U)
- **Folder:** `NROM/Pac-Man (Tengen) (U)/` (promoted out of `_wip/NROM/` 2026-10-20 by `git mv`)
- **ROM:** `Pac-Man (Tengen) (U) [!].nes` (24,592 bytes), reached through the `rom.nes` symlink
- **Source:** `prg.s` (12,739 lines; 3,841 instruction lines covering 7,743 code bytes = 47.3%; 227 labels — 199 routine entries + 28 branch targets — **zero `Label_` residue**, zero raw `$XXXX` jsr/jmp/branch operands, 2,479 canonical audit comments, 0 byte mismatches against `prg.bin`)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C0FA (`NmiHandler`), RESET → **$C033** (`Reset` — the boot sequence is inline here; there is no boot code at $FF00 in this build), IRQ → $C16A (`IrqHandler`)
- **Key subsystems:** NMI frame loop with two controller reads; game-state dispatch through `GameStateDispatchTable` ($C253); maze graphics (`MazeTileGraphics` $C2FD, `AttributeTableData` $C387, `BorderPattern` $C432); ghost AI with the target search at $C8AA and the four-ghost slots; `UpdateMazeTiles` ($DAB0) rewriting the maze through the four overlay tables; score/attribute VRAM writes; the level-script interpreter at $EE8F dispatching through `ScriptCommandTable` ($EFDD)
- **Variant:** a **different build** of the same game as row 32 — 56 PRG bytes differ in 8 runs, all of them code-versus-licensee-text (`$C3E3-$C408` is 26 spaces here against `LICENSED BY NAMCO AMERICA INC` there; `$FF00-$FF16` is `$FF` padding here against the boot code there), and the RESET vector differs to match. The CHR is identical
- **Build fix:** none at PRG level — it was PRG-identical in `_wip/` and stayed byte-identical through Pass 2/3. Promotion added `header.s`, `chr.s`, a HEADER/PRG/CHR `linker.cfg`, the `rom.nes` symlink and the whole-ROM `cmp`; the first promoted build was byte-identical (MD5 `d34e7a74…28ad0`)
- **Pass 2 (2026-10-20):** a fresh map derived from this dump's own committed split — no name, map or file was carried over from the row-32 dump. All 194 `Label_XXXX` definitions renamed to semantic routine entries plus `<Routine>_<Role>` branch targets, and all 48 raw `$XXXX` call operands resolved. Recorded in `routinemap.tsv`
- **Pass 3 (2026-10-20):** 30 semantic zero-page aliases, each applied only at the sites where its role is proven (the per-site choice is in `sites.tsv`; the addresses that carry two roles keep the neutral `ZpXX` name elsewhere, and `locals.inc` records the reason for every remaining neutral slot). 28 data tables named — including `CharacterDataTable` ($C66A) and `CharacterNameStrings` ($C67E), where the ROM itself names Blinky, Pinky, Inky and Clyde. `apply_symbols.py` reports **0 residue**
- **Pass 1 correction (2026-10-20):** six command handlers recovered. `ScriptCommandTable` ($EFDD) is read by the traced instruction at $EFCC, and six of its entries point at $F00A, $F022, $F03A, $F052, $F062 and $F072 — all of which the tracer had left as data, and two of which it had mis-split across the `jmp $EF61` at $F01F and $F04F. Those 120 bytes are code here, decoded straight from the ROM. **The same gap exists in the promoted row-32 dump**, which has not been corrected
- **Residue:** the unreached main game logic at **$C45A–$C55F** is still `.byte` data. It is code — the tracer's own decoder walks it cleanly and the dispatch table at $C511 points into it — but nothing reaches it, so it cannot be entered without a guess. The same gap exists in the row-32 dump. Re-deriving it is a Pass 1 job; a Mesen Code Data Logger capture is the tool the repo uses (`_tools/cdl_reclass.py`)
- **Details:** `Pac-Man (Tengen) (U)/README.md`

### 32. Pac-Man (U)
- **Folder:** `NROM/Pac-Man (U)/` (promoted out of `_wip/NROM/` 2026-10-20 by `git mv`; tool paths stay `../../_tools/`)
- **ROM:** `Pac-Man (U) [!].nes` (24,592 bytes), reached through the `rom.nes` symlink
- **Source:** `prg.s` (12,796 lines; 1,549 audited instruction lines covering 7,767 code bytes, plus 49 `jsr`/`jmp` call sites — 47.4% code by the Pass 1 tracer's accounting; **zero `Label_` residue**, zero raw `$XXXX` call operands)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C0FA (`NmiHandler`), RESET → **$FF00** (`Reset` — real boot code at the vector-page tail, not padding: `sei`/`cld`, PPU off, double vblank wait, `jmp ColdStart` at $C042), IRQ → $C16A (`IrqHandler`)
- **Key subsystems:** NMI-driven frame loop; game-state dispatch through `GameStateDispatchTable` ($C253) via `jmp (DispatchPtrLo)`; entity dispatch through `EntityPtrTable` ($D912) and a second table at $D9B9; palette upload from $0299/$02A9; VRAM write queue at $026B/$0272; audio engine with `AudioCommandTable` ($EFDD) dispatched via `jmp (AudioHandlerPtrLo)`; 15-byte copyright signature `ProgrammerSig` ($C0EB) checked against RAM at $0052
- **Build fix:** none at PRG level — it was PRG-identical in `_wip/` and stayed byte-identical through Pass 2/3. Promotion added `header.s`, `chr.s`, a HEADER/PRG/CHR `linker.cfg`, the `rom.nes` symlink and the whole-ROM `cmp`; the first promoted build was byte-identical (MD5 `a69d310f8cae9397fbd39f204672b5c7`)
- **Pass 2 (2026-10-20):** fresh map derived from the committed split (not from a drafted map): all 194 `Label_XXXX` definitions renamed to semantic routine entries plus `<Routine>_<Role>_<addr>` internal branch targets, and all 49 `jsr`/`jmp` call sites resolved to labels. Recorded in `routinemap.tsv` / `derived_names.tsv`
- **Pass 3 symbols (2026-10-20):** **119 operands substituted** (101 hardware + 11 single-name + 7 multi-alias resolved per site via `sites.tsv`) — `apply_symbols.py` reports **0 residue**. The 7 site resolutions are all proven from context: four `jmp ($0010)` immediately preceded by `sta DispatchPtrLo`/`sta DispatchPtrHi`, one `jmp ($00FE)` preceded by `sta AudioHandlerPtrLo`/`sta AudioHandlerPtrHi`, and two `sta a:$0000,y` zero-page clears that take the neutral `Zp00`. Audit-comment alignment was re-done afterwards with the new `_tools/align_audit_comments.py` (whitespace-only)
- **Details:** `Pac-Man (U)/README.md`

### 29. Hogan's Alley (JU)
- **Folder:** `NROM/Hogan's Alley (JU)/` (promoted out of `_wip/NROM/` 2026-10-20 by `git mv`)
- **ROM:** `Hogan's Alley (JU).nes` (24,592 bytes), reached through the `rom.nes` symlink
- **Source:** `prg.s` (14,620 lines; 3,950 instruction lines covering 8,041 code bytes = 49.1%; 681 labels, **zero `Label_` residue**, zero raw `$XXXX` jsr/jmp/branch operands, 4,490 canonical audit comments, 0 byte mismatches against `prg.bin`)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C088 (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $C000 (the same address)
- **Key subsystems:** the frame heartbeat — the NMI sets `GameFramePending` ($20) and the main loop spends it, with `NmiPhaseFlag` ($22) stopping the per-frame work from running twice; an **inline** dispatch architecture — `IndirectCall` at $C34D pops the return address of the `jsr` that called it and reads a 16-bit handler pointer from the word that follows, so the six handler tables live *inside* the code stream ($C124 19 entries, $C219 4, $C89C 14, $CDD1 1, $D234 2, $D3D6 14); the Zapper on `$4017` (`ReadZapper` $CF3E) with the controller debounced over five frames into `Player1Buttons` ($16); a three-accumulator sound engine (`SoundFlag0`/`1`/`2` at $F0–$F2) fed by 24 one-bit stubs and read at $F9FF/$FC48/$FAFC, with the note records in `NoteParameterTable` ($FCC8)
- **Build fix:** none at PRG level — it was PRG-identical in `_wip/` and stayed byte-identical through Pass 2/3. Promotion added `header.s`, `chr.s`, a HEADER/PRG/CHR `linker.cfg`, the `rom.nes` symlink and the whole-ROM `cmp`; the first promoted build was byte-identical
- **Pass 1 correction (2026-10-20):** the static trace classified only 41.8 % of the PRG as code. A fresh Mesen Code Data Logger capture was merged with the four captures already in the folder (`hogans_merged.cdl`, the OR of five per-byte flag arrays, 6,544 code bytes) and `_tools/cdl_reclass.py` rewrote the split to match what the CPU actually fetched: **1,216 bytes** moved from data to code, five moved the other way and 59 labels were emitted. The four branch targets the tool could not prove were turned into labels by the new `_tools/resolve_raw_branches.py`
- **Pass 2 (2026-10-20):** a fresh map derived from this dump's own committed split: 206 routine entries hand-named and 413 internal branch targets derived mechanically by `_tools/derive_branch_names.py`, 630 `Label_XXXX` definitions gone, 484 raw `$XXXX` call operands resolved, 15 call targets the tracer had never labelled given a label. Recorded in `routinemap.tsv`
- **Pass 3 (2026-10-20):** 60 semantic zero-page aliases, each applied only where its role is proven (`zp_aliases.inc` and `zp_alias_sites.tsv`); the slots that stay neutral are each listed with the reason. 34 data tables named — `SubStateHandlerTable`, `ModeHandlerTable`, `HandlerDispatchTable`, `ActorCommandTable`, `TargetBehaviourTable`, `NoteParameterTable` and the rest — and recorded in `data_region_names.tsv`. `apply_symbols.py` reports **1 residue**: `sta a:$00B4,y` at $C203, the same address as `Zp40`/`ActorPalette` but forced to absolute addressing, so it must stay numeric
- **Residue:** no `make regen` target. The Pass 1 split here is the static trace *corrected* by a CDL capture, and the base the correction was applied to is not what the current `_tools/nesdis.py` produces, so a regen pipeline could not reproduce `prg.s` byte for byte. `prg.s` is the maintained source of truth
- **Details:** `Hogan's Alley (JU)/README.md`

### 30. Mario Bros (JU)
- **Folder:** `NROM/Mario Bros (JU)/` (promoted out of `_wip/NROM/` 2026-10-20 by `git mv`)
- **ROM:** `Mario Bros (JU).nes` (24,592 bytes), reached through the `rom.nes` symlink
- **Source:** `prg.s` (22,010 lines; 6,210 instruction lines covering 12,847 code bytes = 78.4%; 1,025 labels, **zero `Label_` residue and zero `SubC` residue**, zero raw `$XXXX` jsr/jmp/branch operands, 6,458 canonical audit comments, 0 byte mismatches against `prg.bin`)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C07D (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $C000 (the same address)
- **Key subsystems:** the frame heartbeat — the NMI sets `FramePendingFlag` ($20) and the main loop spends it, with `NmiPhaseFlag` ($22) stopping the NMI handler from doing its per-frame work twice; an **inline** dispatch table — the handler pointers sit in the middle of the code stream, right after the call that reads them, so the static tracer cannot follow them (`GameStateHandlerTable` $C510 and its five continuation blocks); a script interpreter that drives the enemies (`SetupScriptPointer` $CB85, `FetchScriptByte` $E9FA, `RunScript` $E9D3) with the command byte compared against $AA and $BB; the Zapper-free controller read with a five-frame debounce into `Zp10`/`Zp11`; a per-note sound engine at $F8A7–$FD27 working from the note table at $FCC8
- **Build fix:** none at PRG level — it was PRG-identical in `_wip/` and stayed byte-identical through Pass 2/3. Promotion added `header.s`, `chr.s`, a HEADER/PRG/CHR `linker.cfg`, the `rom.nes` symlink and the whole-ROM `cmp`; the first promoted build was byte-identical
- **Pass 1 correction (2026-10-20):** the committed split was a strict subset of the correct one — only 72.0% of the PRG was classified as code. A Mesen Code Data Logger capture of this ROM (`mario_mesen.cdl`, 10,915 code bytes) showed **1,010 bytes** the tracer had left as data were code; the two branch targets the capture never reached (`$E4CB` and `$E639`) were forced with `--override` and account for 57 more, so **1,067 bytes** moved from data to code and 22 moved the other way. The biggest single win is `$D508`–`$D56D`, a hundred bytes that decode as a coherent routine, and `$CA3B`–`$CA5D`, the tile-drawing routine. The three branch targets the reclassifier could not prove were turned into labels by `_tools/resolve_raw_branches.py`
- **Pass 2 (2026-10-20):** a fresh map derived from this dump's own committed split: 206 routine entries and 519 internal branch targets, 931 `Label_XXXX` definitions gone, 51 raw `$XXXX` call operands resolved and 12 call targets the tracer had never labelled given a label. **Zero `SubC` residue**: the 185 entries the previous session had left as address-derived residue were all named from the code. Recorded in `routinemap.tsv`
- **Pass 3 (2026-10-20):** 25 semantic zero-page aliases, each applied only where its role is proven (`zp_aliases.inc`); the slots that stay neutral are each listed with the reason. 35 data tables named — `GameStateHandlerTable`, `EnemyBehaviourTable`, `EnemyScriptTable`, `EnemyTypePointerTable`, `SoundRoutineTable`, `NoteFrequencyTable` and the rest — and recorded in `data_region_names.tsv`. `apply_symbols.py` reports **0 residue**
- **Details:** `Mario Bros (JU)/README.md`

### 33. Pyramid (U) (Sachen)
- **Folder:** `NROM/Pyramid (U) (Sachen)/` (promoted out of `_wip/NROM/` 2026-10-20 by `git mv`; the folder was renamed from `NROM/Pyramid (U)` on 2026-10-21 to match the inventory row)
- **ROM:** `Pyramid (U) (Sachen).nes` (24,592 bytes), reached through the `rom.nes` symlink
- **Source:** `prg.s` (10,737 lines; 3,130 instruction lines covering 6,493 code bytes = 39.6%; 463 labels, **zero `Label_` residue**, zero raw `$XXXX` jsr/jmp/branch operands, 3,762 canonical audit comments, 0 byte mismatches against `prg.bin`)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $D72E (`NmiHandler`), RESET → $FF00 (`Reset`), IRQ → $FF00 (the same address — `sei` is never undone, so the IRQ never fires)
- **Key subsystems:** the unlicensed Sachen boot (`sta $4100` mapper unlock with a delay loop at $FF4C, the "A"/"V" check on RAM $0120/$0121 at $FF57, the seed at $FF69, the clear at $FF74, the hand-off to the game's own entry at $C800); a task table of `jmp` trampolines that live inside the data regions ($C01E, $C02A, $C042, $C054) plus ten more at $C000–$C01B; two queued-event dispatchers that jump through the zero page with `jmp ($0002)` ($C3A3 with `TaskVectorTable1` $C3A6, $CCCA with `TaskVectorTable2` $CCD5); a VRAM command list assembled in the $0700 buffer and flushed by `FlushVramCommandList`; the actor grid at $0436 with the actor tables at $D320/$D4EE/$D5D5; a four-voice sound engine with its period, envelope and sample tables
- **Build fix:** none at PRG level — it was PRG-identical in `_wip/` and stayed byte-identical through Pass 2/3. Promotion added `header.s`, `chr.s`, a HEADER/PRG/CHR `linker.cfg`, the `rom.nes` symlink and the whole-ROM `cmp`; the first promoted build was byte-identical (MD5 `aa285ff1…6c59e2`)
- **Pass 1 correction (2026-10-20):** the committed split was a strict subset of the correct one — **828 bytes** of code were still marked as data, because the tracer cannot follow a `jmp` that sits inside a data region. Re-tracing with the sixteen `jmp`-table targets, the `$C800` boot mainline and six further code starts seeded by hand recovers them (plus a five-byte stub at $DF89 in a hole between two routines), and the re-trace loses **no** committed code byte. `make regen` reproduces the split, so it stays verifiable
- **Pass 2 (2026-10-20):** a fresh map derived from this dump's own committed split: 431 routine entries and the 32 data blocks named, 428 `Label_XXXX` definitions gone, 320 raw `$XXXX` call operands resolved. The internal branch-target names are derived mechanically from the branch that reaches them by `_tools/derive_branch_names.py`. Recorded in `routinemap.tsv`
- **Pass 3 (2026-10-20):** 24 semantic zero-page aliases, each applied only where its role is proven (`zp_aliases.inc`); the 57 slots that stay neutral are each listed with the reason. 32 data tables named — `TaskVectorTable1`/`TaskVectorTable2`, `LevelScriptData`, `MusicPeriodTable`, `SoundEnvelopeTable`, the actor tables — and recorded in `data_region_names.tsv`. `apply_symbols.py` reports **0 residue**
- **Pass 3 data tables (2026-10-21):** all 31 data blocks are now *interpreted* rather than merely labelled, and the project README carries a **Pass 3 data-table inventory** giving every block's address range, size, name, structure and consuming instruction. Nine guessed names were corrected — `PaletteSlotRemapTable`, `SoundFrequencyDeltaTable` (five 24-bit decade multipliers: 100000, 10000, 1000, 100, 10), `ActorSpriteTileTable`, `ActorDefinitionTable`, `GridObjectTileTable`, `ActorDirectionOffsetTable`, `ActorSpriteOamTable`, `ActorSpriteYPositionTable` and `SoundApuInitTable` — and `ActorParameterTable` ($CD97) and `ActorFlagByte` ($D72D) were dropped because nothing reads them and their layout is not established. The block names live in `data_region_names.tsv`, so `make regen` reproduces them
- **Residue:** the zero page is reused heavily — 410 references still carry a neutral name, mostly the general-purpose scratch of the shift and arithmetic helpers. 482 absolute operands point at RAM and stay numeric. `sta $4100` stays a raw operand: it is outside the `$2000-$4017` range `PROMPTS.md` asks to be symbolic, and no hardware name would describe a mapper unlock
- **Details:** `Pyramid (U) (Sachen)/README.md`


### 34. Raid on Bungeling Bay (U)
- **Folder:** `NROM/Raid on Bungeling Bay (U)/` (promoted out of `_wip/NROM/` 2026-10-20 by `git mv`)
- **ROM:** `Raid on Bungeling Bay (U).nes` (24,592 bytes), reached through the `rom.nes` symlink
- **Source:** `prg.s` (~19,691 lines; 255 `SubC<addr>` entry points, 612 `Sub_<Role>_<addr>` branch names, **zero `Label_` residue**, zero raw `$XXXX` jsr/jmp/branch operands)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C04C (`NmiHandler`), RESET → $C000 (`Reset` → `ResetEntry` at $C6E3), IRQ → $C2C0 (`IrqHandler`)
- **Key subsystems:** NMI frame loop with two paths (`NmiPathSelector` $C4: minimal vs full); state bitmap at $0200 dispatching on bits 0–3; PPU helper at $C006; sprite/OAM update at $C08E; palette update at $C4E4; main game logic at $C17A; PRNG at $C412; four computed indirect jumps at $E2EC / $E79D / $E7A0 / $E7A3
- **Build fix:** none at PRG level — it was PRG-identical in `_wip/` and stayed byte-identical through Pass 2/3. Promotion added `header.s`, `chr.s`, a HEADER/PRG/CHR `linker.cfg`, the `rom.nes` symlink and the whole-ROM `cmp`; the first promoted build was byte-identical (MD5 `77285503…885000ac`)
- **Pass 3 (2026-10-20):** 11 semantic zero-page aliases added to `locals.inc` and applied at the proven sites. One of them was **corrected** while the `[a2]` sibling was finished: `$EA` had been named `VBlankWaitCounter`, but the routine at `$C412` is the game's PRNG (the classic `eor`/`asl`/`php`/`lsr`/`plp`/`rol` scrambler, called thirteen times from gameplay code, twice in a row at `$CDF4`/`$CDF9` with the second result masked `#$07`), so `$EA` is the scrambler's phase counter. Renamed `PrngPeriodCounter`, and `$EB`/`$EC` were named `PrngSeedB`/`PrngState`. Two `sta a:IndDispatch17,y` operands that were absolute stores to RAM `$0017` were also corrected to `a:Zp17,y`
- **Entry-point naming (2026-10-21):** all **223** address-derived `SubC<addr>` `jsr`/`jmp` entry points were given semantic names — the radar sweep and its blips, the five factories and the targets guarding them, the fuel gauge and the enemy sprites (`UpdatePseudoRandomNumber`, `UploadPaletteToPpu`, `DrawSpritePart`, `GetRadarScreenAddress`, `UpdateFuelGauge`, `MoveEnemyTowardsTarget`, `DestroyEnemy`, `DispatchEnemyRoutine17`/`19`/`1B`). **Zero address-derived entry points remain.** No instruction and no byte value changed
- **Details:** `Raid on Bungeling Bay (U)/README.md`

### 35. Raid on Bungeling Bay (U) [a2]
- **Folder:** `NROM/Raid on Bungeling Bay (U) [a2]/` (promoted out of `_wip/NROM/` 2026-10-20 by `git mv`)
- **ROM:** `Raid on Bungeling Bay (U) [a2].nes` (24,592 bytes), reached through the `rom.nes` symlink
- **Source:** `prg.s` (19,596 lines; 5,079 instruction lines covering 10,536 code bytes = 64.3%; 866 labels — 252 `SubC<addr>` entries + 610 `Sub_<Role>_<addr>` branch names — **zero `Label_` residue**, zero raw `$XXXX` jsr/jmp/branch operands, 5,467 canonical audit comments, 0 byte mismatches against `prg.bin`)
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
- **Vectors:** NMI → $C04C (`NmiHandler`), RESET → $C000 (`Reset` → `ResetEntry` at $C6E3), IRQ → $C2C0 (`IrqHandler`)
- **Key subsystems:** same structure as row 34 — NMI frame loop with two paths, state bitmap at $0200, PPU helper at $C006, sprite/OAM update at $C08E, palette update at $C4E4, main game logic at $C17A, PRNG at $C412, four computed indirect jumps
- **Variant:** a **different build** of the same game as row 34 — 150 of the 16,384 PRG bytes differ, in 7 runs, all of them code-versus-copyright-text at `$C67D–$C6D8` and `$C73B–$C779`; the CHR differs too; header byte 6 is $00 (Horizontal) against row 34's $01 (Vertical). The zero-page reference sets are otherwise identical
- **Build fix:** none at PRG level — it was PRG-identical in `_wip/` and stayed byte-identical through Pass 2/3. Promotion added `header.s`, `chr.s`, a HEADER/PRG/CHR `linker.cfg`, the `rom.nes` symlink and the whole-ROM `cmp`; the first promoted build was byte-identical (MD5 `659d340a1e9d420eee28df13319b0094`)
- **Pass 3 (2026-10-20):** 15 semantic zero-page aliases added to `locals.inc` and applied at the proven sites — every alias is applied only where its role is proven, and the addresses that carry two names keep the neutral name at the sites where the other role applies (`$01` is `PtrHi` at the 16-bit compare and `IndDispatch01` at the dispatch; `$17` is `IndDispatch17` at the dispatch and `Zp17` for the absolute RAM `$0017` store in the copy loop). The new `_tools/apply_zp_aliases.py` does the per-site substitution, because `apply_symbols.py` only rewrites numeric operands
- **Entry-point naming (2026-10-21):** all **220** address-derived `SubC<addr>` `jsr`/`jmp` entry points were given the same semantic names the base dump carries — the two PRGs differ in only 150 bytes, all of them in the copyright-text block, so every routine outside it is byte-identical. **Zero address-derived entry points remain.** No instruction and no byte value changed
- **Details:** `Raid on Bungeling Bay (U) [a2]/README.md`

### 36. Urban Champion (JU)
- **Folder:** `NROM/Urban Champion (JU)/`
- **ROM:** `Urban Champion (JU).nes` (24,592 bytes)
- **Source:** `prg.s` (Pass 3; 3,842 instructions, 691 labels)
- **Linker:** PRG at $C000, 16 KB; single segment
- **Vectors:** NMI → $CA91 (`NmiHandler`), RESET → $CA00 (`Reset`), IRQ → $CA00 (reuses `Reset`)
- **Key subsystems:** NMI-driven frame loop with simple fight game logic; the sound engine (a ten-slot sound-effect table with four APU-channel note sequences each, a note-period table and a note-length table) and the two fighters' 32-byte state blocks at `$0300`/`$0320`; 48.4% code
- **Build fix:** None needed; byte-identical out of the box
- **Pass 3 symbols (2026-10-19):** **70 operands substituted** (4 single-name + 66 hardware) from `symbols.inc`/`locals.inc` via `_tools/apply_symbols.py` — zero residue. Rebuild stays byte-identical.
- **Pass 3 data tables (2026-10-21):** the Pass 1 split was re-traced from the Mesen CDL captures and all 40 data blocks are now interpreted — 72 labels (`name_data_region.py`), and the project README carries a **Pass 3 data-table inventory** with every block's address range, size, name, structure and consuming instruction.
- **Details:** `Urban Champion (JU)/README.md`

### 37. Xevious (U)
- **Folder:** `NROM/Xevious (U)/` (promoted out of `_wip/NROM/Xevious (U)/`)
- **ROM:** `Xevious (U).nes` (32,768 bytes)
- **Source:** `prg.s` (Pass 3; 868 labels)
- **Linker:** HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
- **Vectors:** NMI → $FC4E (`NmiHandler`), RESET → $FAF6 (`Reset`), IRQ → $FF1D (`IrqHandler`)
- **Key subsystems:** NMI-driven frame loop with OAM DMA, PPU scroll/control latch, controller reading with shift register on $4016/$4017; two computed-dispatch mechanisms: `jmp ($fe)` through a 16-entry table at $BA8B (sprite attribute dispatch), `jmp ($4)` through a 44-entry table at $CA0A (the opcode dispatch of the stage-script VM); game mode state machine (title/game/demo) driven by `GameMode` ($10) and `GameSubMode` ($1B); object iteration, movement and drawing; sprite attribute packing into OAM
- **Build fix:** none at PRG level — it was PRG-identical in `_wip/` and stayed byte-identical through Pass 3. Promotion added `header.s`, `chr.s`, a HEADER/PRG/CHR `linker.cfg`, the `rom.nes` symlink and the whole-ROM `cmp`
- **Pass 1 correction:** static trace from vectors reached only 13.6% of PRG. Declaring both jump tables via `--table` plus 92 hand-seeded entry points recovered code behind computed dispatch, reaching 34.5%. On 2026-10-21 the split was redone from the project's Mesen CDL with `_tools/cdl_reclass.py`: 1,158 bytes data→code, 48 code→data, 42 labels emitted, giving 12,455 code bytes (38.0%) and 6,002 instructions; the 45 recovered entries are named `Sub_XXXX`, so no `Label_` remains
- **Pass 3 tables (2026-10-21):** all 129 data blocks are interpreted - 46 carry a semantic name and a description of what their bytes are and which instruction reads them, 44 are recorded as unreferenced data and 38 as code the tracer could not reach.  The $A74B-$B8AA block is split into `VramWritePtrTable`, `VramWriteData`, `StageScriptPtrTable`, `ObjSpritePtrTable`, `ObjSpriteData` and `StageScriptData`; $8000-$9FFF is the level's background tilemap (8192 bytes = 32 columns x 256 rows of background tile indices - sky gradients, terrain shapes and the creature markers); the table at $CA0A is the opcode dispatch of the stage-script VM and the scripts at $ACFB-$B8AA are what it executes; the sprite record is four bytes (Y, tile, attribute, X); the table at $F136 is a sine-wave flight path; `MessageTextTable` at $F5D8 decodes to PLAYER, GAME OVER, READY, SOLVALOU, LEFT and PAUSE; `InitRamSignature` at $FC45 is the nine-byte "Kei Cross" signature copied to $0100-$0108 at reset
- **Residue:** 20,313 bytes (62.0%) remain `.byte` data, and every one of the 129 blocks is now accounted for in the project's **Pass 3 data-table inventory** (46 named, 44 unreferenced data, 38 unreached code). Six CDL-silent raw call operands remain and five regions (`Sub_C626`, `$D24B`, `Sub_D61B`, `Sub_D63E`, `Sub_EA9F`) still decode as code although their bytes form tables; both are documented in the project README. Six addresses contain undocumented/illegal opcodes not decoded by the tracer: $9848, $A2C3, $CD89, $E0FF, $E3B5, $F230
- **Details:** `Xevious (U)/README.md`

### 38. Zanac (U)
- **Folder:** `UNROM/Zanac (U)/` (promoted out of `_wip/UNROM/Zanac (U)/`)
- **ROM:** `Zanac (U).nes` (131,072 bytes)
- **Source:** `prg.s` + `prg.07.s` (Pass 3; bank 7 traced with 391 labels, banks 0-6 as raw data)
- **Linker:** HEADER at $0000, PRG at $0010-$1C000, PRG7 at $1C010-$20000
- **Vectors:** NMI → $CE8D (`NmiHandler`), RESET → $E7BF (`Reset`), IRQ → $CEC4 (`IrqHandler`)
- **Key subsystems:** NMI-driven frame loop with OAM DMA, PPU scroll/control latch, controller reading with shift register on $4016/$4017; vertical scrolling shooter with attract mode; object iteration, movement and drawing; sprite attribute packing into OAM
- **Build fix:** none at PRG level — it was PRG-identical in `_wip/` and stayed byte-identical through Pass 3. Promotion added `header.s`, `chr.s`, a HEADER/PRG/PRG7 `linker.cfg`, the `rom.nes` symlink and the whole-ROM `cmp`
- **Pass 1 correction:** static trace from vectors reached only 37.9% of bank 7. Banks 0-6 remain as raw `.byte` data pending bank-switch analysis
- **Residue:** ~65.5% of bank 7 remains `.byte` data. Seven addresses contain undocumented/illegal opcodes not decoded by the tracer: $D506, $D876, $E15B, $E44B, $E520, $E909, $F0FE
- **Details:** `Zanac (U)/README.md`

### 39. Volleyball (U)
- **Folder:** `NROM/Volleyball (U)/` (promoted out of `_wip/NROM/Volleyball (U)/`)
- **ROM:** `Volleyball (U).nes` (40,976 bytes)
- **Source:** `prg.s` (Pass 3; 1,989 labels, all semantic — 730 read out of the code by hand, 1,221 internal branch targets derived mechanically)
- **Linker:** HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
- **Vectors:** NMI → $8053 (`NmiHandler`), RESET → $8000 (`Reset`), IRQ → $FFFF (not a handler — the last byte of the PRG image; the APU frame counter is never IRQ-enabled)
- **Key subsystems:** the whole game runs from the NMI handler — the main loop at $81B5 only re-arms $DF and refreshes eight zero-page bytes. OAM shadow at $03FF uploaded by DMA, a VRAM update-script interpreter driven from a four-byte command block at $05C0-$05C3, controller reading with a shift register on $4016/$4017, a per-frame crowd animation, and an eleven-entry game-state dispatch table at $85E1 keyed by `GameState` ($2B) and `GameSubState` ($2C)
- **Build fix:** none — it was whole-ROM byte-identical in `_wip/` and stayed that way through Pass 3. Promotion was `git mv` plus the doc updates
- **Pass 1 correction:** the static trace reached only 66% of the PRG image. Declaring the game-state dispatch table (`--table 85E1:11`) plus a Mesen Code Data Logger capture taken while a random-input bot played the attract demo promoted 1,757 further bytes from data to code, reaching 73.0% (11,395 instructions / 23,926 code bytes, 8,842 data bytes, 0 unclassified)
- **Verification:** `_tools/cdl_check.py` cross-checks the finished `prg.s` against the CDL — 0 CDL-code bytes not covered by an instruction and 0 CDL-data bytes that start one. `apply_symbols.py --report` reports 0 residue; `align_audit_comments.py` reports no column drift
- **Residue:** the ten copies of the per-nation player-movement and ball routines are named by their position in the ROM, not mapped to the ten selectable nations — the copies differ only in a few constants, so the mapping would need a per-copy behavioural trace. `BallHitOffsetTable` and the speed tables hold values whose exact meaning is still inferred from the surrounding code
- **Details:** `Volleyball (U)/README.md`

### 42. Port Test Cartridge (U)
- **Folder:** `NROM/Port Test Cartridge (U)/` (promoted out of `_wip/NROM/Port Test Cartridge (U)/`)
- **ROM:** `Port Test Cartridge (U).nes` (40,976 bytes)
- **Source:** `prg.s` (Pass 3; 114 routines, 18 data blocks, 4,563 lines)
- **Linker:** HEADER at $0000, PRG at $8000-$FFFF, CHR absent (the cartridge has CHR RAM)
- **Vectors:** NMI → $CC49 (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $CC17 (`IrqHandler`)
- **Key subsystems:** the NES Control Deck Test. A menu-driven diagnostic: the reset stub waits for vblank, enables the APU, strobes the controllers and dispatches through a VRAM command stream; the command stream is a sequence of (PPU address, descriptor, data) records that the engine at `SetupPpuAddress` ($CE7F) replays into the PPU. The controller port test at $CDC0 returns $00, $55 or $AA for the three ports
- **Build fix:** none — it was whole-ROM byte-identical in `_wip/` and stayed that way through Pass 3. Promotion was `git mv` plus the doc updates
- **Pass 1 correction:** the committed split classified 0.7% of the PRG as code — the static trace reached the reset stub and the vblank wait and nothing else, because the Control Deck Test is a menu-driven state machine and the code behind each menu entry was never executed. A Mesen Code Data Logger capture of the deck-test screen, with the capture's jump-target addresses and the start of every run of code the capture saw used as tracer seeds, takes the split to 4.8% (813 instructions / 1,697 code bytes)
- **Why the coverage stays low:** by design. The cartridge has no CHR ROM, so the 16 KB character font at $8001 is uploaded into CHR RAM at run time; the rest of the PRG is command tables and `$FF` fill. The engine that reads them is 1,697 bytes
- **Details:** `Port Test Cartridge (U)/README.md`

### 43. 10-Yard Fight (U)
- **Folder:** `NROM/10-Yard Fight (U)/` (promoted out of `_wip/NROM/10-Yard Fight (U)/`)
- **ROM:** `10-Yard Fight (U).nes` (40,976 bytes)
- **Source:** `prg.s` (Pass 3; 647 routines, 58 data blocks, 16,864 lines)
- **Linker:** HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
- **Vectors:** NMI → $8471 (`NmiHandler`), RESET → $8000 (`Reset`), IRQ → $84FF (`IrqHandler`)
- **Key subsystems:** an IREM American-football game. The CHR's pattern table 0 is an ASCII font (tiles $00-$09 the digits, $0A-$23 the letters), which decodes the game's own text: the skill menu (HIGH SCHOOL / COLLEGE / PROFESSIONAL / PLAYOFF / SUPER BOWL), the "SELECT YOUR OPPONENT" screen, "HALF TIME UP", the copyright lines, and the play-result strings ("NOT 10 YARD", "10 YARD BACK", "PASS INTERCEPT", "20 YARD BACK"). Two dispatch tables of 16-bit code addresses ($8569 and $9E57) are consumed by an indirect jump at $84D0 and $9ECC, so 12 of the "data" blocks are handler code the static tracer cannot follow
- **Build fix:** none — it was whole-ROM byte-identical in `_wip/` and stayed that way through Pass 3. Promotion was `git mv` plus the doc updates
- **Pass 1 correction:** the committed split classified 11.2% of the PRG as code. A Mesen Code Data Logger capture of the title screen, the opponent's skill menu and a game in progress, with the capture's jump targets and code-run starts used as tracer seeds, takes it to 32.0% (5,166 instructions / 10,491 code bytes)
- **Details:** `10-Yard Fight (U)/README.md`

### 44. Chubby Cherub (U)
- **Folder:** `NROM/Chubby Cherub (U)/` (promoted out of `_wip/NROM/Chubby Cherub (U)/`)
- **ROM:** `Chubby Cherub (U).nes` (40,976 bytes)
- **Source:** `prg.s` (Pass 3; 763 routines, 48 data blocks, 20,128 lines)
- **Linker:** HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
- **Vectors:** NMI → $82B7 (`NmiHandler`), RESET → $8000 (`Reset`), IRQ → $8331 (`IrqHandler`)
- **Key subsystems:** a Bandai platformer in the Little Nemo mould. The HUD and message text is 8x8 nametable tiles and the code that draws it is a table of tile codes; the mapping was recovered by running the ROM and matching the live nametable against the title, gameplay and game-over screens - $00-$09 the digits, $0A-$23 the letters, $24 '-', $25 '.', $26 the trademark, $2D a heart, $2E '!', $2F the copyright sign, $30 a space and $33 a blank - which turns opaque byte blobs into "TM AND (C) BANDAI 1986", "LICENSED BY NINTENDO", "1P-SCORE", "1P GAME OVER", "1P CONGRATULATIONS!", "FOOD", "POWER", "TIME" and "STAGE"
- **Build fix:** none — it was whole-ROM byte-identical in `_wip/` and stayed that way through Pass 3. Promotion was `git mv` plus the doc updates
- **Pass 1 correction:** the committed split classified 20.1% of the PRG as code. A Mesen Code Data Logger capture of a real session, with the capture's jump targets and code-run starts used as tracer seeds, takes it to 41.4% (6,630 instructions / 13,553 code bytes)
- **Entry-point naming (2026-10-21):** **205** of the 223 address-derived `SubC<addr>` `jsr`/`jmp` entry points were given semantic names — the state machine, the screen writers and the enemies (`ResetPlayerState`, `DispatchGameState`, `UpdateGameFrame`, `UpdateGameplay`, `UpdateEnemies`, `ClearNametable`, `WriteTextToNametable`, `DrawReadyRow`, `DrawGameOverRow`, `StartTitleScreen`, `UpdateEnemyObjects`, `DispatchEnemyBehaviour`). The 18 that are left — twelve sound-effect selectors that choose a pair of pointers into the one block whose layout is not established, plus six reset and sprite-gate variants — are recorded with the reason in the project README. No instruction and no byte value changed
- **Details:** `Chubby Cherub (U)/README.md`

### 45. Dig Dug II (U) [!]
- **Folder:** `NROM/Dig Dug II (U) [!]/` (promoted out of `_wip/NROM/Dig Dug II (U) [!]/`)
- **ROM:** `Dig Dug II (U) [!].nes` (40,976 bytes)
- **Source:** `prg.s` (Pass 3; 1,296 routines, 37 data blocks, 30,134 lines)
- **Linker:** HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
- **Vectors:** NMI → $A749 (`NmiHandler`), RESET → $A52D (`Reset`), IRQ → $A52D (the same address as RESET)
- **Key subsystems:** the 1985 Namco sequel. The game has **72 rounds** - $0259 counts 0-71 and wraps at $48 in $C8EA - and that is what the round-indexed palette, monster-type and enemy-offset tables are keyed on. The stage map is a pointer table at $8000 over 72 fixed 106-byte slots at $8090; the VRAM upload is RLE and is decoded byte for byte; the tile-graphics pointer tables at $B060 and $B160 resolve to their 8x8 bitmap targets
- **Build fix:** none — it was whole-ROM byte-identical in `_wip/` and stayed that way through Pass 3. Promotion was `git mv` plus the doc updates
- **Pass 1 correction:** the committed split classified 24.9% of the PRG as code. A Mesen Code Data Logger capture of a real session, with the capture's jump targets and code-run starts used as tracer seeds, takes it to 53.5% (8,161 instructions / 17,525 code bytes)
- **Details:** `Dig Dug II (U) [!]/README.md`

### 46. Gyromite (JUE)
- **Folder:** `NROM/Gyromite (JUE)/` (promoted out of `_wip/NROM/Gyromite (JUE)/`)
- **ROM:** `Gyromite (JUE).nes` (40,976 bytes)
- **Source:** `prg.s` (Pass 3; 742 routines, 52 data blocks, 17,936 lines)
- **Linker:** HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
- **Vectors:** NMI → $8079 (`NmiHandler`), RESET → $8000 (`Reset`), IRQ → $8000 (the same address as RESET)
- **Key subsystems:** the 1985 Namco game. The player drops bombs on five enemy motherships and then flies a small ship to finish them. The sprite system is a shape-id list at $9B16 over a 90-entry pointer table at $9B24 over variable-length shape records at $9BD8; the screen is four nametable tile-row tables written to VRAM $20A2 and $20E2; the wave layout is two strides over one 74-byte stream at $8A11 and $8A2A; the sound data is the APU noise register triples at $F100, the pulse-1 sweep and duration pairs and the note periods
- **Build fix:** none — it was whole-ROM byte-identical in `_wip/` and stayed that way through Pass 3. Promotion was `git mv` plus the doc updates
- **Pass 1 correction:** the committed split classified 4.8% of the PRG as code. A Mesen Code Data Logger capture of a real session - the "PUSH SELECT KEY" screen, the select-mode menu and a game in progress - takes it to 31.0% (4,933 instructions / 10,150 code bytes)
- **Open:** the tile numbers themselves are not decoded; that would need the CHR rendered and compared against the running game, the way `Chubby Cherub (U)` decoded its font codes
- **Details:** `Gyromite (JUE)/README.md`

### 47. Hydlide (U)
- **Folder:** `NROM/Hydlide (U)/` (promoted out of `_wip/NROM/Hydlide (U)/`)
- **ROM:** `Hydlide (U).nes` (40,976 bytes)
- **Source:** `prg.s` (Pass 3; 759 routines, 26 data blocks, 21,070 lines)
- **Linker:** HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
- **Vectors:** NMI → $8003 (`NmiHandler`), RESET → $8000 (`Reset`), IRQ → $8003 (the same address as NMI)
- **Key subsystems:** the 1986 Konami action game. The player explores a forest and a castle, chops trees and rocks with a sword, finds the five Crystals and fights monsters; the screen carries LIFE, STR and EXP meters. The sound engine writes instrument definitions straight to the APU registers, with the note periods in `ApuNotePeriodTable` ($E2CE) and the music scripts behind pointer tables
- **Build fix:** none — it was whole-ROM byte-identical in `_wip/` and stayed that way through Pass 3. Promotion was `git mv` plus the doc updates
- **Pass 1 correction:** the committed split classified 22.3% of the PRG as code. A Mesen Code Data Logger capture of a real session, with the capture's jump targets and code-run starts used as tracer seeds, takes it to 47.8% (7,708 instructions / 15,667 code bytes)
- **Details:** `Hydlide (U)/README.md`

### 48. Ice Hockey (U)
- **Folder:** `NROM/Ice Hockey (U)/` (promoted out of `_wip/NROM/Ice Hockey (U)/`)
- **ROM:** `Ice Hockey (U).nes` (40,976 bytes)
- **Source:** `prg.s` (Pass 3; 1,037 routines, 76 data blocks, 24,390 lines)
- **Linker:** HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
- **Vectors:** NMI → $805A (`NmiHandler`), RESET → $8000 (`Reset`), IRQ → $8000 (the same address as RESET)
- **Key subsystems:** the 1988 Nintendo ice hockey game, with the USA and Canada teams, a line-up screen, a 4 x 8 rink position grid, and a per-frame handler. The screen layout is four pointers into RLE-compressed nametable streams; the rink positions are 32 interleaved (Y, X) pairs; the player starts are four rows per team, the right-hand side mirrored from the left; the 15-entry game-state dispatch table at $83F3 is reached through an indirect jump at $836E
- **Build fix:** none — it was whole-ROM byte-identical in `_wip/` and stayed that way through Pass 3. Promotion was `git mv` plus the doc updates
- **Pass 1 correction:** the committed split classified 3.5% of the PRG as code. A Mesen Code Data Logger capture of the title screen, the team line-up and a game in progress, with the capture's jump targets and code-run starts used as tracer seeds, takes it to 39.5% (6,475 instructions / 12,954 code bytes)
- **Entry-point naming (2026-10-21):** **140** of the 219 address-derived `SubC<addr>` `jsr`/`jmp` entry points were given semantic names — the frame services, the player/puck simulation and the sound engine (`ClearGameMemory`, `UploadPaletteToPpu`, `DecompressScreenData`, `PollControllerButtons`, `WriteSpriteToOam`, `MovePlayerLeft`/`Right`/`Up`/`Down`, `ComputePlayerFacing`, `RemapPlayerRoleFromTableA`-`D`, `UpdateSoundEngine`, `PlaySoundEffect`). The 79 that are left — the steps of the contact simulation and the rink-zone drawing that read 8.8 fixed-point zone coordinates — are recorded with the reason in the project README. No instruction and no byte value changed
- **Details:** `Ice Hockey (U)/README.md`

## `_wip/` Projects

The pre-promotion tier is documented in **`WIP.md`**. It now holds **851
projects** across **29 mapper folders**:

| Folder | Mapper | Projects |
|--------|--------|----------|
| `_wip/NROM/` | 0 | 35 |
| `_wip/MMC1/` | 1 | 221 |
| `_wip/UNROM/` | 2 | 97 |
| `_wip/CNROM/` | 3 | 57 |
| `_wip/MMC3/` | 4 | 239 |
| `_wip/MMC5/` | 5 | 10 |
| `_wip/MAPPER7/` … `_wip/MAPPER232/` | 7-232 | 192 |

All 851 build **byte-identical for the whole ROM** — the tier was moved off
the old PRG-level-only compare on 2026-10-20, so the header and CHR are now
proven for every project here, exactly as in the promoted tier. **All 851 of
them are Pass 0 skeletons**: the folder shape and the build are proven, but
`prg.s` is still a single `.incbin "prg.bin"`. `Volleyball (U)` was the last
project to leave the tier with a full disassembly: Pass 1 + Pass 2 + Pass 3,
promoted to `NROM/Volleyball (U)` on 2026-10-21; `Golf (JU)` and `World Class
Track Meet (U)` followed on 2026-10-21, promoted to `NROM/Golf (JU)/` and
`CNROM/World Class Track Meet (U)/` respectively.

Two things are worth knowing before touching a `_wip/` project:

- **Most of the tier is a banked mapper with a PRG image larger than the
  6502's address space.** Only two projects have a 16 KB PRG; 149 have
  32 KB, 522 have 128 KB and one (`Action 52 (U) [!]`) has 1.5 MB. Those
  projects link their MEMORY areas at *file offsets* rather than CPU
  addresses, which is both the only option and the honest model. See
  "Two linker layouts" in `WIP.md`.
- **226 projects have no CHR at all** — the mapper supplies CHR RAM.

The tier is deliberately **not** built by the root `Makefile`'s `all`/`clean`/
`<MAPPER>` targets — `MAPPERS` names only the promoted mapper folders. The
pre-promotion tier has its own explicit targets:

```
make wip          # build + verify every _wip/<MAPPER>/<Project>/
make wipclean     # clean the build artifacts in the tier
```

Both are driven by `WIP := _wip` at the top of the root `Makefile`; without
that variable the loop expands to `for m in /*/`, which walks the filesystem
root instead of the tier.

(The old manual loop, `for d in _wip/*/*/; do make -C "$d"; done`, still works
as an equivalent.)

Promotion is now just `git mv` plus the disassembly work: the whole-ROM
build, the `header.s`/`chr.s` sources, the HEADER/PRG/CHR `linker.cfg` and
the `rom.nes` copy are already in place. No `_tools` path change is needed,
because both tiers sit two levels deep, so `../../_tools/` is correct either
way. `Lunar Pool (U)`, `Donkey Kong (JU)`, `Popeye (JU) (PRG 1)`,
`Raid on Bungeling Bay (U)`, `Pac-Man (U)`, `Raid on Bungeling Bay (U) [a2]`,
`Pac-Man (Tengen) (U)`, `Pyramid (U) (Sachen)`, `Hogan's Alley (JU)` and
`Mario Bros (JU)` (all 2026-10-20) went through exactly that and came out
whole-ROM byte-identical on the first promoted build. `Xevious (U)` and
`Zanac (U)` followed on 2026-10-20, `Mermaids of Atlantis (U)` on 2026-10-20,
and `Volleyball (U)` on 2026-10-21.

**`git mv` only moves the tracked files**, so the old `_wip/` folder survives
with its untracked build artifacts (`*.o`, `reconstructed.nes`,
`reconstructed.lbl`, `reconstructed.map`) and sometimes with a stale
`README.md` left behind. Delete the leftover folder — otherwise it counts as
a project in every tier tally while having no source to build. `Xevious (U)`
and `Zanac (U)` both left one behind on 2026-10-20; both were cleaned up on
2026-10-21.

Notable vector/header observations for Pass 1 work:
- **Pac-Man (U)** RESET at `$FF00` — the vector-page tail, but **not** padding: `$FF00` holds real boot code (`sei`/`cld`, PPU off, double vblank wait, `jmp ColdStart` at `$C042`). The **Tengen variant** RESETs at `$C033` and has no boot code at `$FF00` at all (that region is `$FF` padding) — the same boot sequence is inline at `$C033`. The two PRGs differ in 56 bytes in 8 runs, all of them code-versus-licensee-text.
- **Lunar Pool (U)** NMI `$FF65` / IRQ `$FF64` are adjacent in the vector page; RESET `$E80C`.
- **NES PowerPad Test Card (U)** — *at Pass 2/3*: minimal code (~7.2%), data-heavy test cartridge. RESET at $E000 (non-$C000 entry). NMI handler reads controllers via shift register, processes pad transitions, draws score/lives. See `NES PowerPad Test Card (U)/README.md`.
- **Lunar Pool (U)** — *Pass 2 and Pass 3 complete; promoted to the top level 2026-10-18*: RESET at `$E80C` (not `$C000`), NMI `$FF65`, IRQ `$FF64` (a bare `rti` just before the NMI handler, so IRQs are ignored). There is **no** `jmp ($7961)` RAM-pointer gate (an earlier claim): those three sites fell out of decoding two bytes into the word "player". `$CBDC`/`$CBC9` is a print-inline-string-and-return-after-it helper, so a `jsr $CBDC` is always followed by a `$81`-prefixed, `$00`-terminated string ("player", "shot", "game over", "hi`score__", "perfect_"). The split was re-derived from a Mesen CDL capture (10,028 bytes Code): now **5,300 instructions / 11,077 bytes (67.6%)**, 5,301 data bytes and the six vector bytes as `.word`. Pass 2 named all **705** labels — `Label_<addr>` is gone from the file — and Pass 3 named 33 tables plus the zero-page aliases (38 semantic, 66 neutral, ten former phantom aliases deleted). Residue, recorded rather than guessed: 73 bytes of *reachable* code are still `.byte` (`$EA9A`, `$EADC`, `$EAE5`, `$EAED`, `$EB04`, `$EB16-$EB4F` — the CDL capture never fetched them), another 75 bytes of ending-screen code sit at `$F5F9-$F643`, and ~206 bytes of unreached-but-clearly-code stubs stay data. The full 24,592-byte ROM (header + PRG + CHR) rebuilds byte-identically. See `Lunar Pool (U)/README.md`.
- **Ice Climber (JE) vs (U)**: byte-identical PRG *and* header — only the CHR differs (~regional title graphic).
- **Popeye (JU) PRG 0 vs PRG 1**: different PRG binaries (and mirroring); same vectors.
- **Raid on Bungeling Bay (U) vs [a2]**: `[a2]` differs in mirroring only per header, but PRGs differ — separate builds.
- **Pyramid (U)** (Sachen) — *promoted 2026-10-20*: the unlicensed Sachen boot pokes a mapper unlock at `$4100`, checks the RAM bytes `$0120`/`$0121` against "A"/"V", and dispatches through two queued-event tables with `jmp ($0002)`. It also dispatches through `jmp` trampoline tables that live *inside* the data regions — 828 bytes of code that the tracer could not reach were recovered by hand. See `NROM/Pyramid (U) (Sachen)/README.md`.
- **CIRCUS** — *at Pass 2/3*: full recursive disassembly complete. NMI-driven frame state machine (main loop is a spin loop at $C057). Menu text at $C763 ("CONTINUE", "STAGE", "SELECT", "PLAY"). Object state machine at $DC3F–$FE7B. Audio sequence data at $FABB–$FFFB. See `CIRCUS/README.md`.
- **Mermaids of Atlantis (U)** — *promoted 2026-10-20, rebuilt 2026-10-21*: mapper 8 (MMC3) with 64 KB of PRG, so the PRG is eight 8 KB banks and two of them can be visible at the same CPU address. The image carries the reset stub **and the vector table twice**: at file `$7FFA` (the fixed bank) the NMI vector is `$808F` — that is the live one, and `$808F` is the frame handler — while the copy at file `$FFFA` names `$8189`, which is a `BRK` in the first half of the image. The fixed bank is the *fourth* 8 KB bank (`$6000-$7FFF`), not the last one, which is why the game's text table lives at CPU `$F1D6`: that is the fixed window, and the code reads it there. Mesen maps the fixed bank the same way, and the dump's own code is what settles it. The disassembly therefore has one segment per bank (`PRG0`..`PRG7`), each with its own `.org` for the CPU window, and banks 4 to 7 carry a `Bank4_`..`Bank7_` label prefix. See `MAPPER8/Mermaids of Atlantis (U)/README.md`.
- **Mermaids of Atlantis (U) — Pass 3 data-table inventory (2026-10-21):** all **76** data blocks the tracer left are inventoried in the project README with their address range, size, name, structure and the instruction that reads them; 27 blocks carry a name (47 labels), the other 49 are recorded as unreferenced - 27 of them are code the tracer could not reach, one is `$FF` padding and 21 are unreferenced data. The fixed bank holds the game's tables (the digit table at `$F1D6`, the actor script pointers, the level layout), which is why code in banks 0, 2 and 4 reaches them with a plain absolute operand. The CHR is the oracle for the font - tiles `$30-$39` are the digits and `$40-$5A` the letters in ASCII order - which is what identifies the high-score table at `$9403` ("TOM1000", "ABCDEFGHIJKLMNOPQRSTUVWXYZ@") and the menu strings at `$9254` ("1PLAYER", "2PLAYERS", "STACKED", "TUNE1".."TUNE3") as plain ASCII, and shows that the 3,783-byte block at `$A000` in bank 1 is *not* text. The image is banked, so `_tools/name_data_region.py` grew a `--segment` option: without it the same address is named in every bank that covers it and the assembler rejects the duplicate symbol.
- **Joypad Test Cartridge (U)** — *Pass 3 complete*: minimal code (23.4%), data-heavy test cartridge. Data region `$CF06–$FFFF` broken into 20 named sub-blocks; VRAM command stream opcode set decoded via `RetAddrUpdate` return-address modification trick at `$CDC8`. See `Joypad Test Cartridge (U)/README.md`.
- **Wild Gunman (U)** — *Pass 1 redone, Pass 2/3 complete*: NMI-driven frame loop. Gates its code behind runtime computed-goto tables — see the `prg.s` header block and its `README.md`.
- **Mario Bros (JU)** — *Pass 1 corrected, Pass 2/3 complete, promoted 2026-10-20*: the engine's handler tables sit **inline**, right after the `jsr` that reads them, so the static tracer could not follow them. A Mesen Code Data Logger capture showed 1,067 bytes the tracer had left as data were code, taking the split from 72.0% to 78.4%. Pass 2 named every label (zero `Label_`, zero `SubC`) and Pass 3 added 25 semantic zero-page aliases and named 35 data tables. Code is gated behind stack-based indirect dispatch at `$CD9E` and a 20-entry `JSR` thunk table at `$C5A3`. Audio routines in `$F8xx-$F9xx` clearly identifiable from APU register writes. See `NROM/Mario Bros (JU)/README.md`.

## Common Patterns Across All Projects

### Memory Map
Every project uses a single 16 KB PRG bank mapped at CPU **$C000–$FFFF**, with 8 KB CHR. All builds are NROM (no bank switching).

### Interrupt Structure
All projects follow the same NES interrupt pattern:
- **NMI** fires once per frame and is the real-time heartbeat — handles OAM DMA, PPU updates, controller reading, and audio.
- **RESET** performs cold-start hardware init, RAM clearing, and enters the main loop.
- **IRQ** is almost always unused (either `rti` or a self-loop).

Two exceptions worth noting from branches of this family:
- **Excitebike** uses a state-dispatch table at $C000 rather than a conventional inline main loop, and its IRQ vector points into a data region (unused).
- **Donkey Kong Jr.** is the extreme case: its reset path idles forever in a PRNG-advance loop, and the *entire* frame state machine (title, attract, gameplay, sound) executes inside the NMI handler itself. Its reset entry is also at $C66E rather than $C000.

### Build Toolchain
All projects use the same toolchain:
- **ca65** (6502 assembler)
- **ld65** (linker with `.cfg` memory map)
- All rebuilds are verified **byte-identical** to the original `prg.bin` / ROM PRG bank.

### Disassembly Style
All sources are "Pass-1" style disassemblies:
- Every instruction annotated with PRG offset, CPU address, and emitted bytes
- Inline `.byte`/`.word`/`.res` data blocks interleaved with code
- Address-based labels where semantics are not yet resolved: `Label_Cxxxx` (unrenamed internal targets), `SubC<addr>` / `Sub_Cxxxx` (unnamed entry points), `<Routine>_Block[_n]` (internal blocks under a named parent routine)
- Zero-page symbol files (`locals.inc`) and hardware symbol files (`symbols.inc`)

---

## Navigation

Each project is a flat folder under its mapper directory — e.g.
`NROM/Balloon Fight (JU)/` — containing:
- `prg.s` — disassembly source; `header.s`, `chr.s` and the raw `header.bin` / `chr.bin` / `prg.bin` splits (where present)
- `symbols.inc`, `locals.inc` — hardware constants and application symbols
- `linker.cfg`, `Makefile` — memory map and build script
- `rom.nes` — space-free copy/symlink of the original ROM used by the compare
- `README.md` — detailed per-project power-on execution flow analysis

To rebuild any one project:
```bash
cd /home/tmerritt/Projects/disasm/NROM/<Project>
make
```

To build and verify every project at once (all mapper directories):
```bash
cd /home/tmerritt/Projects/disasm
make          # all projects, all mappers
make clean    # clean them all
make MMC3     # one mapper tier only
make wip      # the pre-promotion tier under _wip/
```

The root `Makefile` covers the **promoted** tier only — `make`, `make clean`
and `make <MAPPER>` never touch `_wip/`. The pre-promotion tier under `_wip/`
is built explicitly with `make wip` (and cleaned with `make wipclean`):
```bash
for d in _wip/*/*/; do make -C "$d"; done   # equivalent manual loop
```
See `WIP.md` for the `_wip/` tier's layout, its quirks and its open work.

---

## Pass 1 methodology note (2026-10-16)

The original Pass 1 disassembler had two limitations that silently understated
code coverage. Both are worth knowing before trusting a coverage percentage:

1. **Documented opcodes only.** Its table held the 151 documented 6502 opcodes.
   These ROMs also use the 54 undocumented opcodes and the 26 unofficial NOPs
   as 2/3-byte padding; a tracer that halts on them strands the real code behind.
2. **No runtime dispatch.** It followed only vectors and direct `jsr`/`jmp`/branch
   targets. Games here dispatch through computed jumps — `jmp ($0014)`, the
   `pla`-based inline-table gotos in Wild Gunman (`Label_C341`), and task tables
   like Donkey Kong Jr.'s `DeferredTaskHandlerTable` at $BFFE.

Effect measured per project (old tracer → complete-opcode dispatch-aware tracer):

| Project | Old | Complete | Action taken |
|---------|-----|----------|--------------|
| NES PowerPad Test Card (U) | 546 instr | 559 | Pass 1 already sound |
| Joypad Test Cartridge (U) | 282 instr | **1,773** | Pass 1 redone (23.4% code); Pass 2 complete; Pass 3 complete |
| Wild Gunman (U) | 1,600 instr | **4,083** | Pass 1 redone (49.3% code) |
| Balloon Fight (JU) | 5,216 instr | 5,277 | hand-done file was already better |
| Donkey Kong Jr. (JU) | 6,135 instr | 6,135 | file already complete |

**Joypad Test Cartridge (U) was the last project carrying the old, truncated
Pass 1, and has now been redone.** Its recorded "3.5% code" was really 23.4%: the
tracer stopped at `$C09E` on `DCP $3C20` (`$CF`), an undocumented opcode used as
ordinary code, and 3,256 bytes of real code were filed as `.byte` data. Redoing it
also invalidated its Pass 3, which had described `$C09E–$C173` and `$C17F–$CCF6` as
data — both are code. Pass 3 is now the outstanding work.

The fix generalises: `nesdis.py --undocumented` decodes all 105 undocumented NMOS
opcodes. It is **default off** so that projects whose `prg.s` is already
regen-stable keep reproducing byte-for-byte under `make regen`.

`_tools/verify_pass1.py` checks the **top-level projects** — it selects the project
folders under each mapper directory (`NROM/`, `AOROM/`, `CNROM/`, `MMC1/`, `MMC3/`,
`MMC5/`, `UNROM/`) that carry a `Makefile` and a `prg.bin`/`rom.nes`, so `_wip/`
projects are not covered (they are checked by plain `make`, now at the
whole-ROM level).
Current run, 2026-10-20: all 35 `NROM/` projects build, **all canonical**, and
**no truncated or unfaithful Pass 1**. The
last two carryovers are gone — Joypad Test Cartridge, the last project holding an
old truncated Pass 1, was redone, and Excitebike, the last source with uncommented
instructions, was commented.

The comment-spelling report used to claim that **no project follows the canonical
`; CPU:$xxxx PRG:xxxx AA BB` convention**. That was a bug in the checker, not a fact
about the sources: the `canonical` pattern ends with `$` but was compiled without
`re.MULTILINE`, so it could only ever match once — at end of file — and every
project fell through to whichever laxer spelling matched most lines. Fixed with
`re.M`, the true split was 8 canonical / 3 `pipe` / 2 `short` / `rom` / `bytes` /
`colon` / `slash`; the 2026-10-19 standardization (`_tools/audit_comment_tool.py`
over 9 projects, plus hand fixes to CIRCUS and Excitebike) closed it out, so the
checker now reports **all canonical**.

Inside `_wip/`, none of the 851 projects have instructions to comment at all —
they are all Pass 0 skeletons. (`Golf (JU)` and `World Class Track Meet (U)`
used to be the two exceptions, but both were promoted on 2026-10-21 and their
comments are canonical.)
(`Xevious (U)`, which used to be the second project in the tier with
instructions, was promoted to `NROM/` on 2026-10-20.)

The old claim that "Excitebike and Pac-Man carry no byte comments at all" is stale
on both counts. Pac-Man (USA) (Namco) is complete (4,695/4,695 instructions
commented), and Excitebike's 1,013-line gap was closed on 2026-10-19 — all 5,376
instruction lines now carry a canonical comment.

The earlier-reported re-trace crash on `MUSCLE (U)` / `Donkey Kong Jr. (JU)`
(`ValueError: invalid literal for int() with base 16: ':$0010'`) was a false alarm:
`nesdis.operand_value()` already strips the emitter's `a:` prefix via
`token.removeprefix("a:").lstrip("$")`, so re-tracing all promoted projects is
clean.

### Resolved — audit comments for Excitebike and Pac-Man (2026-10-19)

Both were hand-written sources with semantic labels but no byte-identity audit
trail. Both now carry canonical `; CPU:$xxxx PRG:xxxx AA BB` comments on every
instruction, and `verify_pass1.py` reports all-canonical across the top level, so
this section is closed.

The `ca65 -l` listing route described here was abandoned, for the reason recorded
in `AGENTS.md`: the listing carries no source line numbers, so entries cannot be
keyed back to source lines. The comment tooling went through the tracer instead
(`_tools/audit_comment_tool.py`, tracer as ground truth). The invariant still
holds and is the check to keep: after inserting comments, `make` must still print
`Byte-identical ROM verified.`, and each comment's byte list must match `prg.bin`
at the stated offset — a wrong offset that still assembles is the failure mode.

---

## Summary

Thirty-nine projects sit under `NROM/`, and all 39 rebuild **byte-identical**
to their original ROMs (rows 1-27 below plus row 29 `Hogan's Alley (JU)`,
row 30 `Mario Bros (JU)`, row 31 `Pac-Man (Tengen) (U)`, row 32 `Pac-Man (U)`,
row 33 `Pyramid (U) (Sachen)`, rows 34 and 35 `Raid on Bungeling Bay (U)` and
`Raid on Bungeling Bay (U) [a2]` — all promoted 2026-10-20 — and rows 36
and 37 (Urban Champion and Xevious (U)) which kept their tail numbers when
they were promoted; row 7 `Excitebike (JU)` was fixed on 2026-10-20 — the
byte-596 mismatch was two `$0A`/`$11` PPU-mask-shadow operands, see
`NROM/Excitebike (JU)/README.md`).

The pre-promotion tier holds **851 projects** under `_wip/`, and as of
2026-10-21 all 851 verify **byte-identical for the whole ROM** as well
(`make wip` builds and verifies the whole tier: 851 of 851 passed, 0
failures). None of the 851 carry a real disassembly — they are all Pass 0
skeletons; `Golf (JU)` (row 28) and `World Class Track Meet (U)` (row 41)
were promoted from this tier on 2026-10-21. The whole tier — its layout, its
quirks and its open work — is documented in **`WIP.md`**. Folder *locations*
changed on 2026-10-20 (mapper directories, flat project folders),
but each row's build-status claim in this table is the state at its own
promotion; verify against the tree with `make` if in doubt.

| # | Project | Build Status | Pass 3 |
|---| --------- | -------------- | -------- |
| 1 | Balloon Fight (JU) | BYTE-IDENTICAL | complete; symbols applied 2026-10-19 (16 `$13` operands left numeric) |
| 2 | Baseball (UE) | BYTE-IDENTICAL | complete; symbols applied 2026-10-19 (121 operands) |
| 3 | Bomberman (U) | BYTE-IDENTICAL | complete |
| 4 | Burger Time (U) | BYTE-IDENTICAL | complete |
| 5 | Clu Clu Land (JU) | BYTE-IDENTICAL | complete |
| 6 | Defender 2 (U) | BYTE-IDENTICAL | complete |
| 7 | Excitebike (JU) | BYTE-IDENTICAL | complete (Pass 2/3 complete); byte-596 `$0A`/`$11` mask-shadow fix + audit-trail re-anchor + 58 `jsr/jmp` operands symbolized 2026-10-20 |
| 8 | Tennis (JU) | BYTE-IDENTICAL | complete; symbols applied 2026-10-19 (18 operands) |
| 9 | Pac-Man (USA) (Namco) | BYTE-IDENTICAL | complete; symbols applied 2026-10-19 (524 operands; 727 multi-alias residues) |
| 10 | Donkey Kong 3 (JUE) | BYTE-IDENTICAL | complete |
| 11 | Donkey Kong Jr. (JU) | BYTE-IDENTICAL | complete (Pass 1 verified) |
| 12 | CIRCUS | BYTE-IDENTICAL | complete; symbols applied 2026-10-19 (118 operands; 23 multi-alias residues); 258 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets |
| 13 | Wild Gunman (U) | BYTE-IDENTICAL | complete (Pass 1 redone); symbols applied 2026-10-19 (76 operands) |
| 14 | Joypad Test Cartridge (U) | BYTE-IDENTICAL | Pass 3 complete; symbols applied 2026-10-19 (47 operands) |
| 15 | NES PowerPad Test Card (U) | BYTE-IDENTICAL | complete; symbols applied 2026-10-19 (89 operands) |
| 16 | MUSCLE (U) | BYTE-IDENTICAL | complete; symbols applied 2026-10-19 (220 operands) |
| 17 | Lunar Pool (U) | BYTE-IDENTICAL | complete (tables named); symbols applied 2026-10-19 (45 operands) |
| 18 | Donkey Kong (JU) | BYTE-IDENTICAL | complete (Pass 2/3, promoted 2026-10-19); symbols applied 2026-10-19 (75 operands) |
| 19 | Donkey Kong Jr. Math (U) | BYTE-IDENTICAL | complete (Pass 3 complete); promoted into `NROM/` 2026-10-20 after fixing the mislabeled `SubCF218` call sites; 295 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets |
| 20 | Duck Hunt (JUE) | BYTE-IDENTICAL | complete (Pass 3 complete) |
| 21 | Ice Climber (JE) | BYTE-IDENTICAL | complete (Pass 3 complete) |
| 22 | Ice Climber (U) | BYTE-IDENTICAL | complete (Pass 3 complete) |
| 23 | Lode Runner (U) | BYTE-IDENTICAL | complete (Pass 2/3 complete) |
| 24 | Pinball (JU) | BYTE-IDENTICAL | complete (Pass 2/3 complete; data tables interpreted) |
| 25 | Millipede (U) | BYTE-IDENTICAL | complete (Pass 2/3 complete, 74.6% code; 225 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets) |
| 26 | Popeye (JU) (PRG 0) | BYTE-IDENTICAL | complete (Pass 2/3 complete, 72.3% code; data tables interpreted) |
| 27 | Popeye (JU) (PRG 1) | BYTE-IDENTICAL | complete (Pass 2/3 complete, 72.3% code; data tables interpreted); promoted 2026-10-20 |
| 28 | Golf (JU) | BYTE-IDENTICAL | complete (Pass 1+2+3 complete; promoted from `_wip` 2026-10-21; 4,217 instructions / 13,541 lines; 0 residue) |
| 31 | Pac-Man (Tengen) (U) | BYTE-IDENTICAL | partial (Pass 2 complete, Pass 3 complete — 30 zero-page aliases, 28 named data tables, 0 residue, 20.0% code); promoted 2026-10-20 |
| 32 | Pac-Man (U) | BYTE-IDENTICAL | partial (Pass 2 complete, Pass 3 complete — 119 operands, 0 residue); promoted 2026-10-20 |
| 34 | Raid on Bungeling Bay (U) | BYTE-IDENTICAL | partial (Pass 2/3 complete, 64.6% code); promoted 2026-10-20; 223 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets |
| 33 | Pyramid (U) (Sachen) | BYTE-IDENTICAL | partial (Pass 2 complete, Pass 3 complete — 24 zero-page aliases, 0 residue, 39.6% code; 31 data blocks interpreted, 37 labels, 4 blocks unreferenced); promoted 2026-10-20 |
| 35 | Raid on Bungeling Bay (U) [a2] | BYTE-IDENTICAL | partial (Pass 2 complete, Pass 3 complete — 15 zero-page aliases, 0 residue, 64.3% code); promoted 2026-10-20; 220 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets |
| 30 | Mario Bros (JU) | BYTE-IDENTICAL | partial (Pass 2 complete, Pass 3 complete — 25 zero-page aliases, 35 named data tables, 0 residue, 78.4% code; data tables interpreted); promoted 2026-10-20 |
| 29 | Hogan's Alley (JU) | BYTE-IDENTICAL | partial (Pass 2 complete, Pass 3 complete — 60 semantic zero-page aliases, 34 named data tables, 0 residue, 49.1% code); promoted 2026-10-20 |
| 36 | Urban Champion (JU) | BYTE-IDENTICAL | complete; symbols applied 2026-10-19 (70 operands) |
| 37 | Xevious (U) | BYTE-IDENTICAL | complete (Pass 3 complete, 38.0% code; 143 semantic entry points, 32 named data tables, ~20 semantic ZP aliases; split corrected from Mesen CDL 2026-10-21) |
| 38 | Zanac (U) | BYTE-IDENTICAL | complete (Pass 3 complete, 34.5% code; 133 semantic entry points, 26 named data tables, 14 semantic ZP aliases) |
| 39 | Volleyball (U) | BYTE-IDENTICAL | complete (Pass 3 complete, 73.0% code; 1,989 semantic labels, 37 named data blocks, 0 residue; promoted 2026-10-21) |
| 40 | Mermaids of Atlantis (U) | BYTE-IDENTICAL | mapper 8; Pass 3 complete (12.3% code, 494 named routines, 13 semantic zero-page aliases; 8 banked segments; rebuilt 2026-10-21) |
| 41 | World Class Track Meet (U) | BYTE-IDENTICAL | complete (Pass 1+2+3 complete; promoted from `_wip` 2026-10-21; 8,400 instructions / 18,028 code bytes, 55.0% code; 24 semantic ZP aliases, 78 neutral ZpXX with reasons; 0 residue) |
| 42 | Slalom (U) | USA | 32 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 3 complete; promoted from `_wip` 2026-10-21) | $8123 / $8050 / $FEDF |
| 43 | Kung Fu (U) | USA | 32 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 3 complete; data tables interpreted; promoted from `_wip` 2026-10-21) | $82D6 / $8258 / $FFF0 |
| 44 | Othello (U) | USA | 32 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 3 complete; promoted from `_wip` 2026-10-21) | $D6B4 / $8000 / $804E |
| 45 | Elevator Action (U) | USA | 32 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 3 complete; promoted from `_wip` 2026-10-21; 339 `Sub_<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets) | $8081 / $8000 / $8000 |
| 46 | 1942 (JU) | Japan | 32 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 3 complete; promoted from `_wip` 2026-10-21) | $C030 / $BF90 / $BF90 |
| 47 | Tag Team Wrestling (U) | USA | 32 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 3 complete; promoted from `_wip` 2026-10-21) | $FFCD / $FD43 / $FD43 |
| 48 | Galaga (U) | USA | 32 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 3 complete; promoted from `_wip` 2026-10-21) | $C0C8 / $C000 / $C000 |
| 49 | Kung Fu (U) (a1) | USA | 32 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 3 complete; data tables interpreted; promoted from `_wip` 2026-10-21) | $82D6 / $8258 / $FFF0 |
| 50 | Stack-Up (JU) | Japan | 32 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 3 complete; promoted from `_wip` 2026-10-21) | $81AD / $8100 / $81E6 |
| 51 | Magmax (U) | USA | 32 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 3 complete; promoted from `_wip` 2026-10-21) | $BD33 / $BC33 / $BC33 |
| 52 | Ms Pac-Man (Namco) (U) | USA | 32 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 3 complete; data tables interpreted; promoted from `_wip` 2026-10-21) | $C107 / $FFF7 / $C198 |
| 53 | Soccer (JU) | Japan | 32 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 3 complete; promoted from `_wip` 2026-10-21) | $809F / $8000 / $8000 |
| 54 | Sqoon (U) | USA | 32 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 3 complete; promoted from `_wip` 2026-10-21; 271 `Sub_<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets) | $8014 / $8000 / $80F1 |
| 55 | Port Test Cartridge (U) | USA | 32 KB | none | Vertical | BYTE-IDENTICAL (Pass 1+2+3 complete, 4.8% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21) | $CC49 / $C000 / $CC17 |
| 56 | 10-Yard Fight (U) | USA | 32 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 1+2+3 complete, 32.0% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21) | $8471 / $8000 / $84FF |
| 57 | Chubby Cherub (U) | USA | 32 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 1+2+3 complete, 41.4% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21; 205 `SubC<addr>` entry points named 2026-10-21, 18 address-derived `jsr`/`jmp` targets left, recorded in the project README) | $82B7 / $8000 / $8331 |
| 58 | Dig Dug II (U) [!] | USA | 32 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 1+2+3 complete, 53.5% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21) | $A749 / $A52D / $A52D |
| 59 | Gyromite (JUE) | Japan / USA / Europe | 32 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 1+2+3 complete, 31.0% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21) | $8079 / $8000 / $8000 |
| 60 | Hydlide (U) | USA | 32 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 1+2+3 complete, 47.8% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21) | $8003 / $8000 / $8003 |
| 61 | Ice Hockey (U) | USA | 32 KB | 8 KB | Vertical | BYTE-IDENTICAL (Pass 1+2+3 complete, 39.5% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21; 140 `SubC<addr>` entry points named 2026-10-21, 79 address-derived `jsr`/`jmp` targets left, recorded in the project README) | $805A / $8000 / $8000 |

Row 28 (`Golf (JU)`, now promoted to `NROM/Golf (JU)/`) rebuilds byte-identical
at the whole-ROM level. Row 41 (`World Class Track Meet (U)`, now promoted to
`CNROM/World Class Track Meet (U)/`) rebuilds byte-identical as well. The other
851 `_wip/` projects are Pass 0 skeletons and need Pass 1 from scratch.
See **`WIP.md`**.
Use `_tools/verify_pass1.py` to re-check any of this at any time; it rebuilds each
project and re-traces it, and reports `TRUNCATED` when a project's committed split
claims less code than the tracer can reach.