# Golf (JU) — Pass 1 complete, Pass 2 complete, Pass 3 complete

ROM: `_wip/NROM/Golf (JU)/Golf (JU).nes` (24,592 bytes, iNES). Status: **Pass 1
complete, Pass 2 complete, Pass 3 complete — ready for promotion.** The
**whole-ROM** build is **byte-identical** (header + PRG + CHR, `cmp
reconstructed.nes rom.nes`).

**Pass 1 (code/data split) — complete.** Reachable code traced from RESET
($C000) and NMI ($C0A6); all 4,217 reachable instructions are explicit source
in `prg.s` (13,541 lines). NMI callbacks ($C5A0=`GameplayInputNmiCallback`,
$C6C8, $CFAA, $DAA2; continuations $CFC3/$D03E/$D08A) and controller/attract
paths ($DAA2, $C0C7=`InitializeRuntimeState`) are in source. All remaining
`.incbin` spans have zero code entry points and are confirmed data.

**Pass 2 (label naming) — complete.** Startup/NMI/PPU/controller/course-decode
routines named (batches 1–3 per `PASS2_PLAN.md`). All 112 subroutine-entry
`Label_` labels renamed: 4 semantic (`WaitForFramePreservingY`,
`SpriteOffsetForController`, `SetPpuScrollAndMask`, `MultiplyABy32`) and 108
address-derived `SubC<addr>` where behaviour is not yet established. All
jsr/jmp call sites carry symbolic names — 0 raw `$XXXX` call operands.

The remaining 349 internal branch-target `Label_` labels are resolved: 339
given role-based names (`<Routine>_Loop`, `<Routine>_OnZero`,
`<Routine>_OnNonzero`, `<Routine>_OnCarryClear`, `<Routine>_OnCarrySet`,
`<Routine>_OnNonnegative`) derived with `_tools/derive_branch_names.py` from
`routinemap.tsv` and applied with `_tools/apply_pass2_map.py`; the other 10
(`Label_C198`, `Label_D424`, `Label_D9D8`, `Label_D9F9`, `Label_DF3A`,
`Label_FA78`, `Label_FB24`, `Label_FB83`, `Label_FC6B`, `Label_FF00`) are
fall-through-only labels that no branch or jump targets, so they intentionally
keep their `Label_<addr>` definitions.

**Pass 3 (semantic naming) — complete.** Conversions completed:
- Interrupt vectors at $FFFA–$FFFF → `.word NmiHandler`/`Reset`/`IrqLoop`
- Course-stream split pointer table at $E6C3/$E6D5 (18 entries) → `CourseLayoutPointerLo`/`CourseLayoutPointerHi`
- Bit-mask table $D6F4–$D6FB → `BitMaskTable` ($80 40 20 10 08 04 02 01)
- PPU write table $FD0A–$FD11 → `PpuTableFd0a`
- Score adjust table $D988–$D9B0 → `D988ScoreAdjustTable`
- PPU value table $FF85–$FF9F → `FF85PpuValueTable`
- Sprite/object tables (`sprite_object_tables.inc`) and gameplay PPU palette ($E1B8–$E1D7) already emitted as structured source.
- Audit comments converted from the pre-canonical spelling (`; C000: A9 00`)
  to the canonical `; CPU:$C000 PRG:0000  A9 00` form at column 35 via
  `_tools/repair_audit_comments.py` (ground truth: ca65 listing vs `prg.bin`)
  then `_tools/align_audit_comments.py` — 4,156 comments re-aligned; comment
  and whitespace only, no byte change.
- All NES hardware-register operands (`$2000`–`$4017`) use `symbols.inc`
  names (already done in Pass 2).
- 275 zero-page operands substituted with `locals.inc` aliases via
  `_tools/apply_symbols.py`; 0 multi-alias residue, no unexplained numeric
  operands remain.
- Every branch and jump target is a symbolic label; 0 raw `$XXXX` operands
  remain in code.

Remaining `.incbin` spans are largely Iwata's compressed level data
($E6E7–$F905, ~4.6 KB) and opaque lookup tables ($C786–$C84C, $CD85–$CE63,
$D304–$D3B6, $D563–$D659, $D823–$D8EC, $DC59–$DD77, $E1D8–$E281, $E3DE–$E3FB,
$E588–$E6AF, $FBBF–$FC23). Without runtime tracing / a code/data log to confirm
consumers and structure, converting these risks guessy rewrites. Per repo
convention, they remain as `.incbin` with address comments.

Remaining `.incbin` spans ($C71E–$C720, $C786–$C84C, $CD85–$CE63,
$D304–$D3B6, $D563–$D659, $D823–$D8EC, $DC59–$DD77, $E1D8–$E281, $E3DE–$E3FB,
$E588–$E6AF, $E6E7–$F905, $FBBF–$FC23) remain as data per the no-guessy-rewrites
convention; convert only when a consumer is identified.

## ROM Facts

| Property | Value |
|----------|-------|
| Format | iNES |
| Mapper | 0 — NROM-128 |
| Board | NROM |
| PRG | 16 KB (1 x 16 KB), mapped at CPU $C000-$FFFF |
| CHR | 8 KB (1 x 8 KB) |
| Mirroring | Vertical (header byte 6 bit 0 = 1) |
| Four-screen VRAM | no |
| Battery | no |
| Trainer | none |
| Footer | none |
| NMI vector | `$C0A6` |
| RESET vector | `$C000` |
| IRQ vector | `$C0C4` |
| ROM SHA-256 | `70986ed4fb441199a9ff50c7b5c6388d9f7a17c29990d1b5f7214572ae0a4bc6` |
| PRG SHA-256 | `9f729074cd7c74340f325460173519427b1180f5101f8dc37da7b1c2b9b604d5` |

### Header notes

- The header's mapper bits and size fields are read as-is; nothing is unusual
  about them.

## Interrupt Vectors (taken from PRG $3FFA–$3FFF)

| Vector | Target | Note |
|--------|--------|------|
| NMI | `$C0A6` | per-frame heartbeat |
| RESET | `$C000` | cold start at $C000 — the usual pattern in this repo |
| IRQ | `$C0C4` | IRQ handler |

## Build

This project keeps the **CPU-address linker layout** (one of the 38 `_wip/`
projects that do): the PRG really is one contiguous window at `$C000-$FFFF`,
so the memory area sits at that CPU address rather than at a `.nes` file
offset.

```
$ cd "_wip/NROM/Golf (JU)" && make
ca65 -g -o header.o header.s
ca65 -g -o prg.o prg.s
ca65 -g -o chr.o chr.s
ld65 -C linker.cfg -m reconstructed.map -Ln reconstructed.lbl -o reconstructed.nes header.o prg.o chr.o
cmp reconstructed.nes rom.nes
Byte-identical ROM verified.
```

The header and the CHR **are** linked and proven — the whole ROM is compared
byte for byte, exactly as in the promoted tier. (This project predates the
tier's move off the old PRG-only compare, so the older `Makefile.pass0`,
`prg.s.pass0` and `prg_pass1.s` artifacts are still in the folder as history;
the live build is `prg.s` + `linker.cfg` + `Makefile`.)

## Audit comments — canonical, column 35

Every instruction carries a canonical audit comment at column 35:

```
    LDA #$00                       ; CPU:$C000 PRG:0000  A9 00
    STA PPUCTRL                    ; CPU:$C002 PRG:0002  8D 00 20
```

Converted from the pre-canonical spelling (`; C000: A9 00`) with
`_tools/repair_audit_comments.py` (ca65 listing vs `prg.bin` ground truth)
then `_tools/align_audit_comments.py` — 4,156 comments re-aligned; comment
and whitespace only, no byte change. `make` stays byte-identical throughout.

## Files

| File | Purpose |
|------|---------|
| `Golf (JU).nes` | original ROM image (reference) |
| `rom.nes` | space-free copy of the original ROM, the byte-identity target |
| `prg.bin` / `header.bin` / `chr.bin` | split image, produced by `_tools/splitnes.py` |
| `prg.s` | Pass-1 disassembly: classified code/data split with canonical audit comments (column 35); Pass 2 and Pass 3 complete — all routine entries and branch targets named, all zero-page and hardware operands symbolic. Data split into `course_streams.inc` and `sprite_object_tables.inc` |
| `header.s` / `chr.s` | the header and CHR segments as ca65 includes |
| `symbols.inc` | shared NES hardware constants (PPU/APU/controller) |
| `locals.inc` | project-local zero-page aliases (32 semantic names; all 275 zero-page operands substituted, 0 multi-alias residue) |
| `course_streams.inc` | Pass-1 compressed primary course-stream bounds |
| `sprite_object_tables.inc` | Pass-3 sprite/object table structures |
| `linker.cfg` | HEADER / PRG / CHR memory areas (PRG at $C000, 16 KB) |
| `Makefile` | links `reconstructed.nes` and `cmp`s it against `rom.nes` |
| `PASS1_STATUS.md`, `PASS2_PLAN.md`, `NMI_CALLBACK_AUDIT.md`, `OVERLAP_AUDIT.md`, `SPRITE_OBJECT_TABLE_AUDIT.md`, `COMPRESSED_PARSER_AUDIT.md` | working notes kept alongside the source |

## Next Steps

1. **Pass 1** — done (byte-identical whole-ROM build, 4,217 instructions).
2. **Pass 2** — done: all 112 subroutine entries named (4 semantic + 108
   `SubC<addr>`); all jsr/jmp call sites symbolic (0 raw `$XXXX` call
   operands); 339 of 349 internal branch targets given role-based names
   (`<Routine>_Loop`, `<Routine>_OnZero`, …); 10 fall-through-only labels
   keep their `Label_<addr>` definitions.
3. **Pass 3** — done: audit comments canonical at column 35 (4,156 re-aligned);
   all hardware-register operands use `symbols.inc` names; 275 zero-page
   operands substituted with `locals.inc` aliases (0 residue); every branch
   and jump target is symbolic.
4. **Promotion** — `git mv "_wip/NROM/Golf (JU)" "NROM/Golf (JU)"` once the
   controlling agent approves, then add the row to the root `README.md`
   inventory and remove this entry here. The whole-ROM build is already in
   place, so promotion needs no build surgery.